Using an API Routine

An Entire Operations API routine is supplied as Natural subprogram with the name NOPxxxxN in the Natural SYSEOR system library.

The naming convention is:

NOPUxxxy

where NOPU means Entire Operations User API Routine, xxx is the program name (sometimes containing a version number) and y is the program type (N - subprogram, P - program).

To use the Entire Operations API routines, define at least the SYSEOR and SYSSAT libraries as Steplibs.

You execute an API subprogram with the Natural CALLNAT statement. The CALLNAT statement is described in detail in the Natural Statements documentation.

This section covers the following topics:

API Usage Rules and Restrictions

The following general rules apply when using an API:

  • We recommend that you do not rename API routines because they are also used internally by Entire Operations.

  • The routines delivered with the previous Entire Operations version are still supported (except for special notice, and only if they are delivered again with the current SYSEOR library). Convert their calls to the newer version when you modify the calling programs. Change all relevant CALLNAT statements and adapt the API parameter list. The complete range of functions and functionality is only available with the latest API version.

  • Entire Operations internal data structures are subject to change between versions. The usage of an outdated API may cause data inconsistencies, unexpected Monitor failures or abnormal termination of Entire Operations.

  • With newer API versions, new fields might have been added. You may leave these fields blank or zero if their description says "for future use". These fields are intended to become meaningful with a future Entire Operations version.

  • No END TRANSACTION statement will be executed inside of Entire Operations APIs.

  • If you invoke APIs from within an Entire Operations user exit, you must not code any END TRANSACTION statement within the exit. Refer to the user exit coding rules.

  • If you invoke APIs from anywhere else than an Entire Operations user exit, you must code an END TRANSACTION statement in an appropriate location after the CALLNAT statement to close Entire Operations transaction logic.

  • You can change the parameter names, but not the parameter format, number and order.

API Access Restrictions

If Natural Security is installed, you can restrict Natural RPC access to particular APIs. For more information, see the Service Protection option of an RPC server profile described in the section Allowing/Disallowing Services in the Natural Security documentation.

Invoking the API Routines

First, the user application must establish a link to the Entire Operations system files. This can be done in any of the following ways:

The link is already established if the user application startup is extended with either of the following: 

NTLFILE ID=216,DBID=eor-sysf1-dbid,FNR=eor-sysf1-fnr
NTLFILE ID=131,DBID=sat-log-dbid,FNR=sat-log-fnr (in parameter module)

or

LFILE (216,eor-sysf1-dbid,eor-sysf1-fnr)
LFILE (131,sat-log-dbid,sat-log-fnr)     (as dynamic parameter)

Example of Use of API Routines

The Natural program NOPUT1-P can be invoked to find out how API routines react to real data. It shows how to code the calls of the supplied routines, and how to check the return codes.

The source and the cataloged object of NOPUT1-P are supplied in the SYSEOR system library.

When you execute the program NOPUT1-P, you can select and test the required API routine from a screen similar to the example below: 

    Entire Operations - API Routines                              
                                                              
Please Select:                                                
  Network / Job Status       ST                  NOPUST3N     
  Conditions                 CO                  NOPUCN3N     
  Resource Master            RM                  NOPURS1N     
  Resource Usage             RU                  NOPURE2N     
  Symbols                    SY                  NOPUSY6N     
  Calendars/Schedules        CS                  NOPUCS1N     
  Activation                 AC                  NOPUAC5N     
  Milestone                  MI                  NOPUMI1N     
  Subnetwork                 SN                  NOPUSN2N     
  Job Import                 JI                  NOPUJI4N     
  Version Info               VE                  NOPUVI2N     
  Symbol Prompt Texts        SP                  NOPUSP3N     
  Job Schedule               SC                  NOPUJS2N     
  Log Monitor Activity       LM                  NOPMLA1N     
  Active Job Statistics      AS                  NOPUAS1N     
  Message Text               MT                  NOPUMT3N     
                        ===> __  (blank or . or PF3  ==>  End)