Purpose and Use of Entire Operations APIs

This document covers the following topics:

• Features Provided by Entire Operations APIs

• Locating and Implementing an API

• API Usage Rules and Restrictions

• Testing Available API Routines

• API-specific Parameter Definitions

Features Provided by Entire Operations APIs

An API can be used for accessing Entire Operations data and/or performing Entire Operations functions from any Natural application.

An API provides the following features:

• Dynamic connection to the Entire Operations data file;

• Access to conditions;

• Access to symbols;

• Writing to the Entire Operations log.

An API can be used for a number of purposes within and outside Entire Operations. Among them are:

• Dynamic modification of symbol tables during the execution of a job network;

• Modification of conditions from Natural programs;

• Exchanging information between Entire Operations and any other online or batch application;

• Setting input conditions for job networks from online applications;

• Inquiring the status of job networks from applications;

• Setting Entire Operations symbols from external tables;

• Inquiring Entire Operations symbols for use in external applications.

Locating and Implementing an API

An Entire Operations API (Application Programming Interface) routine is supplied as a Natural subprogram in the Natural SYSEOR system library.

The naming convention for an API subprogram is usually as follows:

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 make use of an API

• Call the API subprogram from a Natural program that executes a CALLNAT statement using the following syntax:

  CALLNAT 'NOPUxxxN' parameters

  where parameters represents the individual API parameters that can be passed to the API subprogram. See also API-specific Parameter Definitions.

  The CALLNAT statement is described in detail in the Natural Statements documentation.

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 "reserved 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.

Testing Available API Routines

You can execute the Natural NOPUT1-P program 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                  NOPUSY7N     
  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)

API-specific Parameter Definitions

The parameters that can be passed to an API subrogram with the CALLNAT statement are described for each API in the section Available Entire Operations APIs.

The data types listed in the individual parameter description of an API represent the Natural data format and length, for example, A1 for an alphanumeric variable with a one-byte length. For details, see User-Defined Variables in the Natural Programming Guide.

By default, parameters are passed to an API subprogram by reference, that is, the data is transferred via address parameters, the parameter values themselves are not moved. The parameter descriptions indicate parameters that are defined with BY VALUE, BY VALUE RESULT and/or OPTIONAL.

OPTIONAL

For a parameter defined with OPTIONAL, a value can, but need not be supplied.

Since the parameter sequence is fixed, usually a value must be passed from the calling program to each parameter. However, a parameter defined with OPTIONAL, can be skipped by substituting it with 1X in the CALLNAT statement as indicated in Example of Using NOPUST3N.

BY VALUE

A parameter defined with BY VALUE is passed to the API subprogram by value; that is, the actual parameter value (instead of its address) is passed. Consequently, the field in the subprogram need not have the same format/length as the parameter passed in the CALLNAT statement.

BY VALUE RESULT

A parameter defined with BY VALUE RESULT is passed by value in both directions; that is, the actual parameter value is passed from the calling program to the API subprogram and, on return to the calling program, the actual parameter value is passed from the subprogram back to the calling program.

For further information, refer to Defining Parameter Data in the DEFINE DATA section of the Natural Statements documentation.