Purpose and Use of Entire Operations APIs

#### Search Results

Search

# 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 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 like 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 subprogram 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.

>   For further information about `OPTIONAL` parameters, refer to the description of the `DEFINE DATA` statement, section Defining Parameter Data, Syntax Description, `OPTIONAL`, in the Natural Statements documentation.

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

### On this page

- Features Provided by Entire Operations APIs
- Locating and Implementing an API
- API Usage Rules and Restrictions
- Testing Available API Routines
- API-specific Parameter Definitions