Available Entire Operations API Routines

#### Search Results

Search

# Available Entire Operations API Routines

- EORUCB1N: Check Use of BS2000 User IDs

- NOPFB2-N: Generate SYSOUT File Names for BS2000

- NOPMLA1N: Start and Stop the Monitor Activity Log

- NOPU--1N: Read Network Available to a Specific User

- NOPU--2N: Return all Usable Symbol Tables for a Network

- NOPU--3N: Get Correlation ID for an Activated Network

- NOPU--4N: Store New Event in Entire Operations System File

- NOPUAC5N: Activate Job Networks or Jobs

- NOPUAS1N: Retrieve Numbers of Active Jobs in Defined Status Ranges

- NOPUCN3N: Access Entire Operations Conditions

- NOPUCS1N: Access Calendars and Schedules

- NOPUJI4N: Import Operating System Jobs into the Active Queue

- NOPUJS2N: Job Schedule Inquiry and Modification

- NOPULW9N: Write Messages to System Automation Tools Log

- NOPUMI1N: Set/Reset Text Milestones in Master and Active Jobs

- NOPUMT3N: Expand Message Texts

- NOPUNI1N: Invalidate Entire System Server Node Table Entries

- NOPUNX1N: Entire System Server Calls to Access UNIX and Windows Files

- NOPURE2N: Handle Resource Allocations

- NOPURS1N: Access Entire Operations Resource Masters

- NOPUSN2N: Inquire Calling Job or Called Network for Subnetworks

- NOPUSP3N: Display Long Texts for Symbol Prompting

- NOPUST3N: Inquire Network and Job Status, Symbol Table

- NOPUSY7N: Access Entire Operations Symbols

- NOPUVI2N: Obtain Entire Operations Version Information

- NOPUXD1N: Maintain End-of-Job User Exits for a Network

- NOPUXI0N: Add Input Condition to an Activated Job

## EORUCB1N: Check Use of BS2000 User IDs

You can use the exit EORUCB1N contained in the library SYSEORU for a user-defined check if Natural users are allowed to use BS2000 user IDs.

Meaning of the input and output fields:

### Parameter Description

Parameter | Format/Length | Use
--- | --- | ---
`P-RC` | N4 | out | Return code (not evaluated, should be `0`).
`P-RT` | A70 | out | Return text (not evaluated).
`P-USER` | A8 | in | `*USER` in Natural.
`P-BS2000-USERID` | A8 | in | BS2000 user ID.
`P-ACCOUNT` | A8 | in | BS2000 account number.
`P-SUBMIT-PSWD` | A8 | in | BS2000 submit password.

In the following you find the example of the exit EORUCB1N delivered with Entire Operations which you can adapt according to your needs. The exit always returns `P-RC=0` (authorized).

#### Example

    * NOPFB2-N

    END

## NOPFB2-N: Generate SYSOUT File Names for BS2000

The exit NOPFB2-N may be copied into the library SYSEOR to enable the user-defined generation of SYSOUT file names in BS2000. Only one instance of this exit exists in the system and it is executed only if it is present. Otherwise, standard name generation is used.

This exit is called with the parameter list NOPXPL-A, so the first line of the exit must be:

    DEFINE DATA PARAMETER USING NOPXPL-A

This section covers the following topics:

- Parameter Description

- Rules for Exit Coding

- Use with Work File Deletion

- Example

### Parameter Description

Meaning of the parameters in NOPXPL-A:

Parameter | Format/Length | Use
--- | --- | ---
`P-CALL-PLACE` | A3 | in | Constant `FSB` (file name SYSOUT BS2000).
`P-RC` | N4 | out | Return code:
`0` | Function OK (name generation OK).
`1` | A name could not be generated. The default name routine of Entire Operations is to be called.
`2` | A name could not be generated. The action (activation) is to be cancelled.
If the activation is cancelled by means of the name routine, a corresponding log entry will be written.
`P-RT` | A66 | out | Return code (not evaluated).
`P-OWNER` | A10 | in | Network owner.
`P-NETWORK` | A10 | in | Job network.
`P-JOB` | A10 | in | Job.
`P-RUN` | P13 | in | Run number.
`P-ACTIVATION-TIME` | T | in | Activation time of the network.
`P-EXECUTION-NODE` | N3 | in | Entire System Server execution node.
`````P-EXECUTION-OPSYS` | A8 | in | Operating system of Entire System Server node.
`P-SYMBOL-TABLE` | A10 | in | Name of the defined symbol table.
`P-FSB-OBJECT-TYPE` | A5 | in | File type:
`SO-C` | Current SYSOUT file.
`SO-P` | Previous SYSOUT file.
`SO-P1` | Previous SYSOUT file without user ID.
`SO-A` | All SYSOUT files of a job.
`P-FSB-USERID` | A8 | in | BS2000 user ID.
`P-FSB-CATID` | A4 | in | BS2000 Cat ID.
`P-FSB-SUFFIX` | A2 | in | BS2000 suffix.
`P-SYSOUT-FILE` | A54 | out | Generated file name.

### Rules for Exit Coding

- File names must be created which are unique system-wide. Otherwise, the proper running of Entire Operations is no longer possible.

- File names which are unique system-wide can be produced by using the fields `P-OWNER`, `P-NETWORK`, `P-RUN`, `P-JOB` and `P-FSB-SUFFIX` simultaneously.

- You must be able to process all object types defined above.

- Except for the object type `SO-P1`, a fully-qualified file name must be created which includes the BS2000 user ID.

- A wildcard file entry valid for all SYSOUT files of an active job must be created for the type `SO-A`. This type is used for deleting files.

- The field `P-FSB-SUFFIX` is transferred and must be used to differentiate SYSOUT files when jobs are repeated. The caller ensures that the suffix for the currently active job is unique. For the object type `SO-C`, this field is blank.

Note
If no file name is returned, then standard name generation is used.

### Use with Work File Deletion

Even in case of work file deletion (in connection with deactivation or cleanup) this exit is called, if it exists at all. The following will apply in this context:

- At any rate, an attempt is made to also delete work files, which correspond to the default name conventions of Entire Operations, independent of the existence of the exit.

- It is presumed that the exit will generate the run number with exactly 5 digits, which are enclosed by dots:

  - `aaa.00000.bbb` (example: `aaa.01234.bbb`)

  For the Entire Operations file search, this pattern is replaced by a wildcard:

  - `aaa.00000.bbb` --> `aaa.*.bbb`

- If the name syntax of the exit is modified, files cannot be found any longer, the names of which have been generated before the modification. It is not recommended to exchange the exit, while active jobs are running in the operating system.

### Example

    * NOPFB2-N
    * EXAMPLE EXIT FOR SYSOUT FILE NAME
    *
    * MODIFICATIONS:
    * 29.10.08 (139240) SYSOUT FILE NAME EXIT                       SN210
    * -------------------------------------------------------------------
    DEFINE DATA PARAMETER USING NOPXPL-A
    END-DEFINE
    * -------------------------------------------------------------------
    COMPRESS P-OWNER P-NETWORK P-RUN P-JOB
      INTO P-SYSOUT-FILE LEAVING NO SPACE
    IF P-FSB-OBJECT-TYPE NE 'SO-P1'
    * -- ALL OBJECT TYPES EXCEPT SO-P1  M U S T  HAVE A BS2000 USERID --
      COMPRESS '$' P-FSB-USERID '.' P-SYSOUT-FILE
        INTO P-SYSOUT-FILE LEAVING NO SPACE
    END-IF
    IF P-FSB-OBJECT-TYPE EQ 'SO-A'
    * -- ALL SYSOUT FILES FOR A JOB --
      COMPRESS P-SYSOUT-FILE '*'
        INTO P-SYSOUT-FILE LEAVING NO SPACE
    ELSE
      COMPRESS P-SYSOUT-FILE '.S' P-FSB-SUFFIX
        INTO P-SYSOUT-FILE LEAVING NO SPACE
    END-IF
    RESET P-RC        /* OK
    END

## NOPMLA1N: Start and Stop the Monitor Activity Log

You can start and stop the monitor activity log using the following calls from your Natural application.

    CALLNAT 'NOPMLA1N'
    P-FUNCTION

### Parameter Description

Parameter | Format/Length | Use
--- | --- | ---
`P-FUNCTION` | A1 | in | Function code:
`Y` | Starting the monitor activity log.
`N` | Stopping the monitor activity log.

The call of this API has the same effect as setting the field Log Monitor Activity in the Monitor Defaults (see the Administration documentation).

This enables you to automatically start and stop the monitor activity log at particular times or on account of specific conditions.

## NOPU--1N: Read Network Available to a Specific User

You can get a list of networks owned or granted to a user using the following call from your Natural application.

    CALLNAT 'NOPU--1N'
      P-USER
      P-SELECTION
      P-RC
      P-RESULT-GRANTED-NETWORKS (*)

The parameters have the following meaning:

Parameter | Format/Length | Use
--- | --- | ---
`P-USER` | A8 | in | User name.
`P-SELECTION` | A10 | in | Selection criteria.
Select by `P-SELECTION` (combination of values possible):
`O` | Networks of owner.
`G` | Owner granted networks.
`A` | Active networks only. Note Only usable together with `O`, `G` or `U`.
`U` | User granted networks.
`P-RC` | N3 |  | `1` | User not defined.
`99` | Natural runtime error.
`P-RESULT-GRANTED-NETWORKS` Note This is a dynamic structure consisting of:
`P-OWNER` | A10 | out | Owner of network.
`P-NETWORK` | A10 | out | Network name.
`P-NETWORK-VERSION` | A10 | out | Network version.
`P-DESCRIPTION` | A70 | out | Short description of network.

## NOPU--2N: Return all Usable Symbol Tables for a Network

You can get a list of usable symbol tables for a given Network using the following call from your Natural application.

    CALLNAT 'NOPU--2N'
      P-OWNER
      P-NETWORK
      P-NETWORK-VERSION
      P-RC
      P-RESULT-SYMBOL-TABLES  (*)

The parameters have the following meaning:

Parameter | Format/Length | Use
--- | --- | ---
`P-OWNER` | A10 | in | Owner name.
`P-NETWORK` | A10 | in | Network name.
`P-NETWORK-VERSION` | A10 | in | Network version.
`P-RC` | N3 | 1 | Error when determining tables.
99 | Natural runtime error.
`P-RESULT-SYMBOL-TABLES` Note This is a dynamic structure consisting of:
`P-SYMBOL-TABLE_TYPE` | A2 | out | Symbol table type.
`P-SYMBOL-TABLE_OWNER` | A10 | out | Symbol table owner.
`P-SYMBOL-TABLE` | A10 | out | Symbol table name.
`P-SYMBOL-TABLE-VERSION` | A10 | out | Symbol table version.

## NOPU--3N: Get Correlation ID for an Activated Network

You can retrieve the correlation ID for a specific Network using the following call from your Natural application.

    CALLNAT 'NOPU--3N'
      P-OWNER
      P-NETWORK
      P-RUN-NUMBER
      P-RC
      P-CORRELATION-SUBSYS
      P-CORRELATION-ID
      P-CORRELATION-TYPE

The parameters have the following meaning:

Parameter | Format/Length | Use
--- | --- | ---
`P-OWNER` | A10 | in | Owner name.
`P-NETWORK` | A10 | in | Network name.
`P-RUN-NUMBER` | I4 | in | Run number.
`P-RC` | N3 | 1 | Activated network does not exist.
99 | Natural runtime error.
`P-CORRELATION-SUBSYS` | A32 | out | Correlation subsystem.
`P-CORRELATION-ID` | A36 | out | Correlation ID.
`P-CORRELATION-TYPE` | A32 | out | Correlation type.

## NOPU--4N: Store New Event in Entire Operations System File

You can store an event record for a given network run using the following call from your Natural application.

    CALLNAT 'NOPU--4N'
              P-EVENT-TYPE
              P-EVENT-VERSION
              P-EVENT-DATA (*)
              P-OWNER
              P-NETWORK
              P-NETWORK-RUN
              P-RC
              P-ERROR-NR

The parameters have the following meaning:

Parameter | Format/Length | Use
--- | --- | ---
`P-EVENT-TYPE` | A32 | in |
`P-EVENT-VERSION` | A5 | in |
`P-EVENT-DATA` | A80/1:19 |  |
`P-OWNER` | A10 | in | Owner of network.
`P-NETWORK` | A10 | in | Network.
`P-NETWORK-RUN` | I4 | in | Run number.
`P-RC` | N4 | out | `1` | Network run does not exist.
`99` | Natural runtime error.
`P-ERROR-NR` | N7 | out | Only filled with the contents of the Natural system variable `*ERROR-NR` in case of a runtime error.

## NOPUAC5N: Activate Job Networks or Jobs

You can activate job networks or jobs from your Natural application. The network of job definitions must exist in Entire Operations. Use:

    CALLNAT 'NOPUAC5N'
        FUNCTION RC OWNER NETWORK NETWORK-VERSION JOB SYMTAB  SYMTAB-VERSION
    START-TIME RUN [8X] [LATEST-START] [DEADLINE]

This section covers the following topics:

- Parameter Description

- Activation with Symbol Modification

- Repetition of an Active Network

### Parameter Description

Parameter | Format/Length | Use
--- | --- | ---
`FUNCTION` | A1 | in | Function code:
`A` | Activate, no hold for symbols.
`1` | Like `A`, but time frame as defined in schedule is used.
`C` | Change start time.
`D` | `RUN` > `0`: Deactivate network. `RUN = -1`: Delete network master.
`H` | Activate, but hold task until released with function `R`. See Activation with Symbol Modification.
`I` | Set run number initial value. The next network run will use the next run number available after the number entered. The run number must be between 0 and the highest run number permitted.
`J` | Modify the earliest start time, latest start time and deadline time of an active job. The three timestamps are shifted with the same offset.
`K` | Modify the earliest start time of an active job only. The latest start time and deadline time will not be modified.
`R` | Release activation that is in hold. Activation with Symbol Modification.
`2` | Like `R`, but time frame as defined in schedule is used.
`S` | Repetition of an active job.
`T` | Repetition of an active network.
`X` | Network or job existence test only.
`RC` | N4 `BY VALUE RESULT` | out | Return code:
`0` | OK.
`1` | Owner, network, job not found.
`2` | Activation entry not found.
`3` | Network not active.
`4` | Job cannot be restarted. For the function `S` (repetition), this return code is issued if there is a SYSOUT copy in progress.
`5` | Run number has already been used.
`6` | Run number not in valid range.
`7` | No free run number.
`8` | Active objects existing.
`9` | Current version cannot be determined.
`10` | Version default usage found. This return may be issued at a deletion attempt.
`11` | Invalid time frame. One or both of the following has occurred: `P-LATEST-START` is specified and is earlier than `P-START-TIME`. `P-DEADLINE` is specified and is earlier than `P-START-TIME` or `P-LATEST-START`.
`12` | Invalid activation origin. This return code may be issued for internal calls of the API only.
`101` | Invalid function code.
`102` | Parameters missing.
`111` | Symbol table name contained reserved prefix `=EOR=`.
`120` | Owner must not be used. Applies to the reserved owner `WASTEBIN`, for example.
`121` | Owner does not exist.
`122` | Network version is required.
`901` | OK; subnetwork symbol prompting.
`DBENV` | A10 `BY VALUE` `OPTIONAL` | in | Database environment (reserved for future use).
`OWNER` | A10 `BY VALUE` | in | Owner of the job network. If a job is placed in hold status by means of the function `H`, this will be written to the log.
`NETWORK` | A10 `BY VALUE` | in | The job network.
`NETWORK-VERSION` | A10 `BY VALUE` `OPTIONAL` | in | Version name of the job network or `(current)` (see Reserved Version Names for Networks).
`JOB` | A10 | in | Job. If empty, whole network is activated, deactivated or tested.
`SYMTAB` | A10 `BY VALUE` `OPTIONAL` | in | The symbol table.
`SYMTAB-VERSION` | A10 `BY VALUE` `OPTIONAL` | in | Symbol table version.
`START-TIME` | T | in | If zero (0), the network is activated immediately. Otherwise, the network is activated at the designated time. The field must contain both date and time.
out | Start time actually set.
`RUN` | I4 `BY VALUE RESULT` | in | Run number used by Entire Operations.
Functions `A` and `H`: When activating a single job, an existing run number can be entered. This should only be used for post activations of an active network. Functions `C`, `D`, `R` and `S`: Must be an existing run number of the job network. Function `X`: If 0, the network master is tested. Otherwise, an active network with this run number is tested.
out | Functions `A` and `H`: If 0, the next free run number is assigned. If not 0, this number is used; if this number is still active, the next free number in ascending order is used.
`8X` | `OPTIONAL` |  | Placeholder for 8 parameters that are intended for internal use. Required if you want to pass one or more of the following parameters.
`LATEST-START` | T `OPTIONAL` | in | If specified, the field must contain both date and time. For the activated run, the latest start passed here will override any other definitions on job or network level.
`DEADLINE` | T `OPTIONAL` | in | If specified, the field must contain both date and time. For the activated run, the deadline passed here will override any other definitions on job or network level.

Note
You can use this function from outside Entire Operations, as well as from user exits within Entire Operations. This function is comparable to the manual activation of networks or jobs in the Entire Operations online system.

### Activation with Symbol Modification

To activate a job or network and pass specific symbol values to this activation, proceed as follows

1. Activate the network and keep it in hold, with function `H`.

2. Use the returned run number to set symbols in the active symbol table(s) for this run. The API routine must be called NOPUSY7N.

3. After setting the symbol(s), release this activation with the `R` function.

   Notes:

   1. The parameters `START-TIME`, `EARLIEST-START` (optional), `DEADLINE` (optional) will be taken from the `R` (release) call.
   2. Active symbols, which are set here, will not be overwritten by a subsequent complete symbol table activation.

### Repetition of an Active Network

The field `P-JOB` may remain empty.

- If `P-JOB` is empty, all executed jobs of the active network will be repeated.

- If `P-JOB` contains a valid job name, the active network will be repeated, but the given job will be repeated as "dummy due to repetition".

The repetition also works correctly for jobs of type `NET` (subnetwork): subnetworks are also repeated, with their original run number.

The conditions `NET-BEGIN`, `NET-END` and `NET-END-NOTOK` will be reset before the repetition.

This API function enables you to repeat whole active networks, including subnetworks. Active conditions which are already set or reset will be backed out.

| Warning: You should exercise caution if the API NOPUAC5N function `T` is invoked for a network, in which jobs are currently executing. These will not be repeated. We recommend that you use this API function only for active networks, in which no job is currently executing.

## NOPUAS1N: Retrieve Numbers of Active Jobs in Defined Status Ranges

This section covers the following topics:

- Function Call

### Function Call

You can retrieve the numbers of active jobs in defined status ranges by using the following call:

    CALLNAT 'NOPUAS1N'
        NOPUAS-VERSION NOPUAS-PARMS

In the calling program, define the parameter list for this API as follows:

    DEFINE DATA
    ...
    LOCAL USING NOPUAS1L

Meaning of the parameters:

Parameter | Format/Length | Use
--- | --- | ---
`NOPUAS-VERSION` | N2 | in | Interface version (currently this is 01 constantly).
`NOPUAS-PARMS` | A250 | mod | Parameter data area.
Redefinition of `NOPUAS-PARMS`:
`P-FUNCTION` | A1 | in | Function code:
`S` | Get statistics.
`P-RC` | N3 | out | Return code:
`0` | OK.
`101` | Invalid function code.
`102` | Parameter(s) missing.
`P-NUMBER-WAITING` | I4 | out | Number of jobs waiting.
`P-NUMBER-HOLD` | I4 | out | Number of jobs in hold.
`P-NUMBER-INPUT-QUEUE` | I4 | out | Number of jobs in the input queue.
`P-NUMBER-EXECUTING` | I4 | out | Number of jobs executing.
`P-NUMBER-PERM-ERROR` | I4 | out | Number of jobs in permanent error status.

## NOPUCN3N: Access Entire Operations Conditions

You can handle conditions using the following statement in your Natural application:

    CALLNAT 'NOPUCN3N'
        P-FUNCTION P-RC P-OWNER P-NETWORK P-CONDITION P-RUN-FROM P-RUN-TO
        P-TIME-FROM P-TIME-TO P-CONFIRM P-JCL-CHECK

This section covers the following topics:

- Parameter Description

- Description of Function Codes

### Parameter Description

Parameter | Format/Length | Use
--- | --- | ---
`P-FUNCTION` | A1 | in | Function code:
`R` | Reset a condition.
`S` | Set a condition.
`T` | Test a condition.
See also Description of Function Codes.
`P-RC` | N3 | out | Return code:
`0` | Function OK.
`1` | Condition not found.
`2` | Time or run required for reset.
`3` | Invalid run number range.
`101` | Invalid function code.
`102` | Condition name missing.
`104` | Network name missing.
`121` | Owner does not exist.
`P-OWNER` | A10 | in | Owner of the job network/condition.
`P-NETWORK` | A10 | in | Job network.
`P-CONDITION` | A20 | in | Condition name.
`P-RUN-FROM` | I4 |  | Corresponding run number.
in | Absolute condition: -1.
out | Function `T` and field empty: Last run number found is returned.
`P-RUN-TO` | I4 | in | Run number to (end of interval). If zero, only `P-RUN-FROM` will be handled.
`P-TIME-FROM` | T | in | Starting time of condition.
out | Function `T` and field empty: Time belonging to run number is returned.
`P-TIME-TO` | T | in | End time of condition.
`P-CONFIRM` | A1 | in | Confirm deletions: `Y` (yes), `N` (no).
`P-JCL-CHECK` | A1 | in | If this field contains `C`, the condition is treated like one which is used during a JCL check.

### Description of Function Codes

Meaning of the function codes:

Code | Description
--- | ---
`R` | Reset a condition. The date or the run number must be specified. If a run number is specified, the date is not considered. If a date is specified, the deletion of several conditions with the same date, but different run numbers might occur.
`S` | Set a condition. The date and/or run number are optional.
`T` | Test a condition. If a run number is specified, the time frame is not considered. If no time frame and no run number are specified, each condition with the specified name matches. If no run number is specified, the last run number for the time frame up to the current time is returned. If no time frame was given, the time belonging to this run number is returned in `P-TIME-FROM`.

## NOPUCS1N: Access Calendars and Schedules

This section covers the following topics:

- Accessing Dates within Calendars or Schedules

- Example for Using NOPUCS1N

### Accessing Dates within Calendars or Schedules

You can access dates within calendars or schedules using the following statement in your Natural application:

    CALLNAT 'NOPUCS1N'
        P-FUNCTION P-RC P-OBJECT-TYPE P-OWNER P-OBJECT P-DATE-A8

Meaning of the parameters:

Parameter | Format/Length | Use
--- | --- | ---
`P-FUNCTION` | A1 | in | Function code:
`A` | Delete a calendar or schedule.
`B` | Add calendar.
`C` | Determine the calendar used.
`D` | Determine the schedule used.
`N` | Determine the next set date, from a start date.
`P` | Determine the previous set date, from a start date.
`R` | Reset a date. Date will be removed from calendar or schedule.
`S` | Set a date. Date will be added to calendar or schedule.
`T` | Test a date. If date exists within calendar or schedule: `RC` contains `0`, otherwise `1`.
`1` | Set all dates in the calendar. Not supported for schedule.
`2` | For calendar: Reset all dates in the calendar. For schedule: Delete all schedule definitions. The schedule will remain as empty body. Note An existing calendar link will be kept. This function is equivalent to `PF9 = Reset` in the Schedule Maintenance screen in the CUI, see also Special PF Keys: Schedule Definition.
`P-RC` | N3 | out | Return code:
`0` | Function OK, or date is set. Note For calendars, this means workday.
`1` | Date is not set. Note For calendars, this means holiday.
`2` | Object not found.
`3` | Object used in definitions.
`4` | Object already existing.
`101` | Invalid function code.
`102` | Parameter(s) missing.
`103` | Invalid parameter combination.
`104` | Invalid object type.
`105` | Invalid date.
`106` | Table of explicit dates full.
`121` | Owner does not exist.
`P-OBJECT-TYPE` | A1 | in | Object type:
`N` | Network.
`C` | Calendar.
`H` | Schedule history.
`S` | Schedule.
`P-OWNER` | A10 | in | Owner of object.
out | Functions `C` and `D`: owner of determined object.
`P-OBJECT` | A10 | in | Name of object: owner name resp. schedule name. If `P-FUNCTION` is `N`, `P`, or `T`, and if a calendar is expected as object: You may use the reserved calendar name `=EOR=WORK7`. This pseudo-calendar is valid for any year and has all days defined as workdays. The value of `P-OWNER` is meaningless in this case.
out | Function codes `C` and `D`: name of determined object.
`P-DATE-A8` | A8 | in | Date in format: YYYYMMDD. See also Date and Time Formats. `ALL` in this field means all years. This value applies for deletions.
out | Function codes `N` and `P`: the date found.

Notes:

1. Only function `T` (test a date) is allowed for object type `H` (schedule history).
2. Schedule history is usually available for the current year and previous two years.
3. Schedule dates can be set for the current year and the next year.
4. In calendars, a set date means workday, and a non-set date means holiday. The functions `N` and `P` work for a range of years. Limitations:
   For schedules, only the current and the previous year are available.
5. Calendars must be defined for all years in which a search is to be performed.
6. Function `A` deletes calendar/schedule master when `P-OBJECT-TYPE='C'` or `P-OBJECT-TYPE='S'`, respectively. In case calendar/schedule is for the current year, and if is referenced in schedule/network the `P-RC` value `3` (Object used in definitions) is returned. Calendars for past years will be deleted without reference check.
7. When a calendar is deleted (`P-FUNCTION='A'` and `P-OBJECT-TYPE='C'`), the value of `P-DATE-A8` shall be either in form YYYY or YYYYMMDD or constant `ALL`. Value `ALL` means: the calendar will be deleted for all defined years.

### Example for Using NOPUCS1N

The program calculates the first Monday of each month in 2008 and subsequently enters the network `REQUEST`/`NET001` for the calculated days in the schedule.

    * DETECT FIRST MONDAY IN MONTHS
    *
    DEFINE DATA
    LOCAL
    1 #YYYYMMDD (A8)
    1 REDEFINE #YYYYMMDD
     2 #YYYY    (N4)
     2 #MM      (N2)
     2 #DD      (N2)
    1 #D1      (D)
    1 #WD      (A1)
    1 #OWNER   (A10) INIT <'REQUEST'> /* Owner
    1 #OBJECT  (A10) INIT <'NET001'>  /* Network
    1 #RC3     (N3)
    END-DEFINE
    *
    #YYYY := 2010                     /* Year
    F1. FOR #MM = 01 TO 12
     RESET #DD
     R1. REPEAT
      ADD 1 TO #DD
      MOVE EDITED #YYYYMMDD TO #D1 (EM=YYYYMMDD)
      MOVE EDITED #D1 (EM=O) TO #WD
      WRITE #D1 (EM=YYYYMMDD) #WD
      UNTIL #WD = '1'      /* R1.
     END-REPEAT        /* R1.
     WRITE #D1 (EM=YYYYMMDD' 'N(10))
    *
    * CALL NOP SCHEDULE API TO SET THESE DAYS
    *
     CALLNAT 'NOPUCS1N'
      'S' #RC3 'S' #OWNER #OBJECT #YYYYMMDD
     WRITE #YYYYMMDD #RC3
    END-FOR      /* F1.
    END TRANSACTION
    END

## NOPUJI4N: Import Operating System Jobs into the Active Queue

You can activate a job in Entire Operations together with an existing operating system job number. This is possible if the job was submitted by any application and set to HOLD status.

Use the following statement:

    CALLNAT 'NOPUJI4N'
       P-FUNCTION P-RC P-OWNER P-NETWORK P-JOB P-RUN P-EXECUTION-NODE P-SYSOUT-NODE
                  P-SYSOUT-FILE P-BS2000-MONJV P-JOB-ID P-OS-JOB-NAME

### Parameter Description

Parameter | Format/Length | Use
--- | --- | ---
`P-FUNCTION` | A1 | in | Function code:
`I` | Import job, without prerequisite check.
`J` | Import job, with prerequisite check. The new active job is created with input and output condition definitions.
`P-RC` | I4 `BY VALUE RESULT` | out | Return code:
`0` | Function OK.
`101` | Invalid function code.
`102` | Parameter(s) missing.
`103` | `P-JOB-ID` value invalid:
`121` | Owner does not exist.
`P-OWNER` | A10 | in | Optional1.
`P-NETWORK` | A10 | in | Optional1.
`P-JOB` | A10 | in | Optional1.
`P-RUN` | I4 `BY VALUE RESULT` | in | Optional1. If `P-RUN` is set to zero (0), Entire Operations assigns a new run number; otherwise, the job is activated under the run number given. Job masters for imports with run number must be defined with the special type `R` to prevent automatic activation.
`P-EXECUTION-NODE` | I4 `BY VALUE` | in | Required. Execution node.
`P-SYSOUT-NODE` | I4 `BY VALUE` | in | Optional. Necessary only if `P-SYSOUT-FILE` is specified, and if `P-SYSOUT-NODE` is different from `P-EXECUTION-NODE`. Default: same value as `P-EXECUTION-NODE`.
`P-SYSOUT-FILE` | A250 `BY VALUE` | in | For BS2000, UNIX and Windows. File which contains the SYSOUT. UNIX (for example, Bourne Shell): End your script with
    set -x
    exit $EXITCODE
assuming the `EXITCODE` file contains the exit code you want to set so that Entire Operations End-of-Job checking can parse the exit code from the SYSOUT. Linux: If a SYSOUT file is not given here and if a process with `PID = P-JOB-ID` is currently executing, Entire Operations tries to determine the SYSOUT file from the stdout assignment of the PID.
`P-BS2000-MONJV` | A250 `BY VALUE` | in | Optional. BS2000 monitor job variable. Specify this parameter only for BS2000, and only if the job was started in conjunction with a monitor job variable.
`P-JOB-ID` | A10 | in | Required. The job ID can be passed left-justified in this field, regardless of whether it is numeric or alphanumeric.
`P-OS-JOB-NAME` | A8 | in | Optional; from operating system.

1 The parameters `P-OWNER`, `P-NETWORK`, `P-JOB` and `P-RUN` are optional. If any of these are empty, `IMPORT` is used instead as owner, network and/or job name. Entire Operations will try to find a job definition for these values. If a definition is found, the new active job entry is supplied from it.

## NOPUJS2N: Job Schedule Inquiry and Modification

You can inquire and modify a job schedule by using the following statement in your Natural application:

    CALLNAT 'NOPUJS2N'
        P-FUNCTION P-RC P-DBENV P-OWNER P-NETWORK P-NETWORK-VERSION
        P-RUN P-JOB P-AVERAGE-TIME P-EARLIEST-START
        P-LATEST-START P-DEADLINE

### Parameter Description

Parameter | Format/Length | Use
--- | --- | ---
`P-FUNCTION` | A1 | in | Function code:
`N` | Inquire job schedule for the next job (in alphabetical order). At the end of the list, `RC = 1` is returned.
`R` | Inquire job schedule.
`S` | Change job schedule.
`P-RC` | N3 | out | Return code:
`0` | Function OK.
`1` | Owner, network, run number or job not found.
`101` | Invalid function code.
`102` | Parameter missing.
`103` | Earliest start time invalid.
`104` | Latest start time invalid.
`105` | End time invalid.
`106` | Latest start must be greater than earliest start.
`107` | End time must be greater than latest start.
`108` | Job has already been started.
`109` | Earliest start must be greater than current time.
`110` | Job is in hold status.
`121` | Owner does not exist.
`P-DBENV` | A10 `OPTIONAL` | in | Database environment (reserved for future use).
`P-OWNER` | A10 | in | Owner of the network.
`P-NETWORK` | A10 | in | Job network.
`P-NETWORK-VERSION` | A10 | in | Network version.
`P-RUN` | I4 | in | Run number.
`0` | Data of the network master is inquired or modified.
Other value | Data of the specified active network run is inquired or modified.
`P-JOB` | A10 | in | Job.
`P-AVERAGE-TIME` | I4 | in/out | Expected runtime tenths of a second.
`P-EARLIEST-START` | A14 | in/out | Earliest possible start time. Format: YYYYMMDDHHIISS
`P-LATEST-START` | A14 | in/out | Latest possible start time. Format: YYYYMMDDHHIISS
`P-DEADLINE` | A14 | in/out | Deadline. Format: YYYYMMDDHHIISS

## NOPULW9N: Write Messages to System Automation Tools Log

You can write messages to the System Automation Tools log file. The messages will be written with the product identifier of Entire Operations so that they will appear in the Entire Operations log display.

Use the following statement:

    CALLNAT 'NOPULW9N'
        P-TASK-ID P-MESSAGE-CODE P-MESSAGE P-DBENV P-OWNER P-NETWORK P-NETWORK-VERSION
        P-RUN P-JOB P-JOB-ID P-LOG-TARGET P-USE-NAT-MSG-CACHE

### Parameter Description

Parameter | Format/Length | Use
--- | --- | ---
`P-TASK-ID` | A8 `BY VALUE` | in | User ID of person initiating the Entire Operations log messages. This can remain blank, in which case it is supplied with the content of the Natural `*USER` system variable. Entire Operations-internal use: name of the current Monitor task.
`P-MESSAGE-CODE` | N4 `BY VALUE` | in | Internal message code (not displayed); used for later message selection. Use message codes in the range 8000 - 8999 to avoid conflicts with internal messages.
`P-MESSAGE` | A70/1:V `BY VALUE` | in | The message text line(s). Note This parameter is a dynamic array. One or several text lines may be passed.
`P-DBENV` | A10 `BY VALUE` `OPTIONAL` | in | Database environment (reserved for future use).
`P-OWNER` | A10 `BY VALUE` `OPTIONAL` | in | Owner; used for later message selection; can remain blank.
`P-NETWORK` | A10 `BY VALUE` `OPTIONAL` | in | Network; used for later message selection; can remain blank.
`P-NETWORK-VERSION` | A10 `BY VALUE` `OPTIONAL` | in | Network version; used for later message selection; can remain blank.
`P-RUN` | I4 `BY VALUE` `OPTIONAL` | in | Run number assigned to the message; can remain blank.
`P-JOB` | A10 `BY VALUE` `OPTIONAL` | in | Job; used for later message selection; can remain blank.
`P-JOB-ID` | A10 `BY VALUE` `OPTIONAL` | in | Operating system job identifier; can remain blank. Numeric values must be right-justified with leading zeros, for example: `0000004711`.
`P-LOG-TARGET` | A3 | in |
Defines where to write the log message:
`NOP` | Writes to Entire Operations log (default).
`SO` | Writes to the SYSOUT of the current monitor task or of the batch job.
`ALL` | Writes to both the Entire Operations log and the SYSOUT.
`P-USE-NAT-MSG-CACHE` | L `OPTIONAL` | in | Use the Natural internal message cache. If this routine is called from outside the Entire Operations Monitor, this parameter must be skipped or set to `FALSE`, because the Natural message cache is not initialized in this case. If this routine is called from within the Entire Operations Monitor, you may set this parameter to `TRUE`. In case of any problems with this setting, skip the parameter or use `FALSE`.

The timestamp and the originating Natural user ID are inserted automatically.

This routine is also invoked internally by the other user API routines.

## NOPUMI1N: Set/Reset Text Milestones in Master and Active Jobs

You can inquire on or modify milestone definitions in master and active jobs (see also Milestone types in the section Job Maintenance) by using the following statement in your Natural application:

    CALLNAT 'NOPUMI1N'
        P-FUNCTION P-MILESTONE-TYPE P-DBENV P-OWNER P-NETWORK P-NETWORK-VERSION
        P-RUN P-JOB P-RC

The parameters have the following meaning:

Parameter | Format/Length | Use
--- | --- | ---
`P-FUNCTION` | A1 | in | Function code:
`S` | Set milestone.
`R` | Reset (delete) milestone.
`T` | Test milestone.
`P-MILESTONE-TYPE` | A1 | in | Milestone type:
`B` | Milestone set at network begin.
`E` | Milestone set at network end.
`I` | Milestone set for any job (any network position except begin and end).
`A` | All milestone types (not for function code `S`).
`P-DBENV` | A10 `OPTIONAL` | in | Database environment (reserved for future use).
`P-OWNER` | A10 | in | Owner of the network.
`P-NETWORK` | A10 | in | Name of the job network.
`P-NETWORK-VERSION` | A10 `OPTIONAL` | in | Version of the job network.
`P-RUN` | I4 `BY VALUE` `OPTIONAL` | in | Run number of the job network.
`P-JOB` | A10 | in | Name of the job.
`P-RC` | I4 `BY VALUE RESULT` | out | Return code:
`0` | Function OK. Or: Milestone was set.
`1` | Owner, network, version, run and/or job not found.
`2` | Milestone was not set.
`9` | Current version cannot be determined.
`101` | Invalid function code.
`102` | Parameter missing.
`103` | Invalid milestone type.
`121` | Owner does not exist.
`122` | Network version is required.

## NOPUMT3N: Expand Message Texts

Entire Operations stores its message texts in the Log file in a language-independent, compressed format.

To read the proper message text, you must use the following routine:

    CALLNAT 'NOPUMT3N'
        P-APPLIC-ID P-MESSAGE P-USE_NAT_MSG_CACHE P-LANGUAGE P-PREFIX-HANDLING

Note
Expansion is only necessary if the message text begins with a semicolon (;).

### Parameter Description

Parameter | Format/Length | Use
--- | --- | ---
`P-APPLIC-ID` | A8 | in | Name of the application from which the message is to be taken.
`P-MESSAGE` | A70 | in | The message text. Input: compressed. Output: readable text.
`P-USE-NAT-MSG-CACHE` | L | in | Use the Natural internal message cache. If this routine is called from outside the Entire Operations Monitor, this parameter must be set to `FALSE`, because the Natural message cache is not initialized. If this routine is called from within the Entire Operations Monitor, you may set this parameter to `TRUE`. In case of any problems with this setting, use `FALSE`.
`P-LANGUAGE` | I1 | in | Language code for the message. Values:
`0` | Use current setting of the Natural `*LANGUAGE` system variable.
`1` | English.
`2` | German.
other | English.
`P-PREFIX-HANDLING` | A1 | in | `A` (or blank) | Do not remove message prefix.
`,`
`B` | If prefix `AAA9999 -` , return from position 9. Example: `AAAA999 - text` --> `- text`
`C` | If prefix `AAA9999 -` , return from position 11. Example:`AAAA999 - text` --> `text`
`D` | If prefix is missing in SYSERR, insert a prefix. The resulting message will be `EOR1234 – Just an example`. Example: The message in internal format is `;EOR;1234`, and the SYSERR message text is `Just an example`. The resulting message will be `EOR1234 – Just an example`.

## NOPUNI1N: Invalidate Entire System Server Node Table Entries

You can use this API to invalidate session node table entries.

This API must be invoked before exiting a user exit if logons to Entire System Server nodes were made. The invalidation forces new Entire System Server logons to the nodes after termination of the calling user exit.

Use the following statement:

    CALLNAT 'NOPUNI1N'
        P-FUNCTION P-NODE(*) P-RC

### Parameter Description

Parameter | Format/Length | Use
--- | --- | ---
`P-FUNCTION` | A1 | in | Function code:
`I` | Invalidate nodes.
`P-NODE` | I4/1:V | in | Node number(s) of nodes to be invalidated. The array may have an arbitrary size.
`P-RC` | I4 | out | Return code:
`0` | Function OK.
`101` | Invalid function code.

## NOPUNX1N: Entire System Server Calls to Access UNIX and Windows Files

You can use this API to access UNIX and Windows files out of Natural programs.

For `FILE / READ` or `FILE / WRITE`, and if `BUFFER-TYPE` `B`, `C` or `D` is used:

`CALLNAT 'NOPUNX1N' NOPUNX1A data buffer[caller-module]`

For all other calls:

`CALLNAT 'NOPUNX1N' NOPUNX1A [1X caller-module ]`

For calls to `NOPUNX1N`, use the parameter data area `NOPUNX1A` described in the following sections.

- Parameter Description

- Runtime Environment

- Programming Requirements

- Opening and Closing a File

- Reading a File

- Searching for specific Data Sets in a File

- Writing a File

- Reading and Writing a File Using a Large Buffer

- Deleting a File

- Copying a File

- Moving or Renaming a File

- Verifying the Existence of a File

- Creating a List of Files of a Directory

### Parameter Description

This section covers the following sections:

- Data area NOPUNX1A
- data buffer
- caller module (input only, optional)

#### Data area NOPUNX1A

The parameters in the parameter data area `NOPUNX1A` have the following meaning:

Parameter | Format/Length | Use
--- | --- | ---
`OBJECT` | A16 | in | Possible values: `USER` `FILE` `JOB` `SERVER`
`FUNCTION` | A8 | in | Possible values for `USER`:
`LOGON` | Logon to a node.
`LOGOFF` | Logoff from a node.
Possible values for `FILE`:
`APPEND` | Append to an existing file.
`COPY` | Copy file.
`CLOSE` | Close file.
`DELETE` | Delete file.
`DELDIR` | Delete file directory.
`DIR` | List files.
`DTA` | List files sorted by modification time in descending order.
`DTD` | List files sorted by modification time in descending order.
`GETATTR` | Get file attributes.
`LINECNT` | Count lines in a file.
`MOVE` | Move file or rename.
`READ` | Read file.
`SCAN` | Search for strings in a file.
`WRITE` | Write file.
Possible values for `JOB`:
`CANCEL` | Cancel job.
`COMMAND` | Execute command.
`GETEXIT` | Get exit code of a terminated job.
Possible values for `SERVER`:
`CL-TL-G` | Get command log level and trace level.
`RETURN-CODE` | N8 | out | `0` | Function was OK.
`4` | No more data
`101` | Object is not implemented
`102` | Not a Unix or Windows node
`404` | User undefined
`5509` | Logon failed. Check USERID and / or PASSWORD.
`5510` | Logon required
`5995` | File not found
other value | See content of `RETURN-TEXT`.
`RETURN-TEXT` | A80 | out | Explanatory text for `RETURN-CODE`.
`NODE` | N5 | in | Node, as defined in Entire Operations.
`NODE-NAME` | A16 | in | Node name. Can be passed as an alternative to `NODE`. Will be used only if `NODE=0`.
`NODE-ACCESS-MODE` | A1 | Can only be changed by the API | empty | Has not yet been checked.
`N` | Node is not local.
`Y` | Node is local.
This field is set by API at `USER` / `LOGON`. It should not be changed by the application.
`USERID` | A20 | in | User ID for logon.
`GROUP` | A20 | in | Optional:
UNIX | Group for logon.
Windows | Domain for logon.
`PASSWORD` | A16 | in | Password for logon. Obsolete. Please use `UL-PASSWORD-A256`. We recommended that you clear this field after a successful `USER` / `LOGON`.
`SID` or `SESSION-ID` | N10 | Can only be changed by the API | Will be provided by the API after a successful `USER` / `LOGON` call. For other calls it is an input parameter.
`SERVER-COMMAND-LOG-LEVEL` | N5 | out | Output of `SERVER / CL-TL-G`.
`SERVER-TRACE-LEVEL` | N5 | out | Output of `SERVER / CL-TL-G`.
`HTML-CODE-HANDLING` | A1 | in/out | For `FILE` functions.
`CODEPAGE-ID` | N5 | in | For the `FILE` functions `WRITE` and `APPEND`.
`OPSYS-CLASS` | A1 | Can only be changed by the API | Operating system class of `NODE`. Possible values:
`B` | BS2000
`M` | z/OS
`X` | UNIX
`W` | Windows
`USE-PAM` | A1 | in | For `USER / LOGON` on UNIX nodes.
`N` | Do not use PAM for `LOGON`.
`Y` | Use PAM for `LOGON`.
`INHERIT-ACCESS-TIME` | A1 | in | For `FILE` functions.
`BUFFER-FORMAT` | A1 | in | For the `FILE` functions `READ`, `WRITE` and `APPEND`. Possible values:
`T` | Text, single record.
`3` | Text, multiple records, 3-byte fields.
`L` | Text, multiple records, variable-length fields.
`A` | Base64-encoded format.
`UNUSED-1` | A10 | - | Unused. |
`ESC-TRIGRAPH` | A1 | in | Trigraph usage:
empty or `N` | No trigraph converted.
`Y` | Use question mark (?) as trigraph escape character.
other | Use this character as trigraph escape character.
For information on trigraph encoding, see the relevant section in Submission of Jobs by Entire Operations.
`TRACE-LEVEL` | N1 | in | `0` | No trace.
> `0` | Trace activated.
`TRACE-TARGET` | A1 | in | Destination where trace will be stored.
`S` | SYSOUT.
`L` | Entire Operations log.
`B` | Both: SYSOUT and Entire Operations Log (only relevant if `TRACE-LEVEL` > `0`).
`BUFFER-TYPE` | A1 | in | Type of buffer. Mainly used for the `FILE` functions `READ`, `WRITE` and `APPEND`. Possible values:
`A` (or blank) | XS-FIRWA-BUFFER-TYPE, size 600.
`B` | XS-FIRWB-BUFFER-TYPE, size 9700.
`C` | XS-FIRWC-BUFFER-TYPE, size 99000.
`D` | XS-FIRWD-BUFFER-TYPE, size 59000.
For the buffer types `B`, `C` and `D`: The buffer is to be passed as a separate parameter in the `CALLNAT 'NOPUNX1N'` statement (mentioned earlier).
`OBJECT-AREA` | A1200 | - | Object-specific fields.
|  |  | Object: `FILE` (redefinition of `OBJECT-AREA`).
`F-FILE` | A250 | in | File name. The file name must be fully qualified. It must contain a complete path starting at the root of the file system. The file name may contain environment variables.
`F-HANDLE` | N10 | Can only be changed by the API | File handle. Is allocated by Entire System Server at the first access of a file. Is active until `FILE` / `CLOSE`.
`F-LINE` | N10 | in/out | In | Line number where reading begins (`0` or `1`: start reading at the beginning of the file).
Out | (Last) read line number.
`F-NUMBER-RECORDS` | N10 | out | Number of read data sets.
`F-SEARCH-TEXT` | A100 | in | Only `FILE` / `SCAN`: Text to be searched for in the file.
`F-RECORD-BUFFER` | A600 | in/out | Whole record buffer (redefinition of `F-RECORD BUFFER`). Used for `BUFFER-TYPE='A'` only.
`F-RECORD-250` | A250 | in/out | `FILE` / `READ`, `FILE` / `WRITE`: Effective record. Used for `BUFFER-TYPE='A'` only.
`F-RECORD-SEPARATOR` | A5 | in | For future use.
`F-LINE-LIMIT` | N10 | in | `FILE/COPY`, `FILE/MOVE`: For text files: The maximum number of records to be copied or moved.
|  |  | Object: `JOB` Function: `COMMAND` (redefinition of `OBJECT-AREA`).
`JCM-COMMAND` | A500 | in | The command to be executed.
`JCM-OUTPUT-FILE` | A250 | in | Output file for the command.
`JCM-REMOVE-OUTPUT-FILE` | A1 | in | `N` | Keep the output file.
`Y` | Delete the output file after successful command execution.
`JCM-USER` | A20 | in | User ID for the command.
`JCM-GROUP` | A20 | in | Optional:
UNIX | Group for the command.
Windows | Domain for the command.
`JCM-WAIT-FOR-TERMINATION` | A1 | in | `N` | The termination of the command is not to be waited for.
`Y` | The termination of the command is to be waited for.
`JCM-OUTPUT-MODE` | A1 | in | `C` | Overwrite existing output file. (default value)
`A` | If the output file already exists, append the output to it.
`JCM-EXIT-CODE-MSG-APPEND` | A1 | ein | `N` | Do not append an exit code message to the output file.
`Y` | Append the exit code message NPR3355 to the output file. (default value)
`JCM-EXIT-CODE` | N10 | out | Exit code of the command.
`JCM-PID` | N10 | out | Process ID of the command.
|  |  | Object: `JOB` Function: `SUBMIT` (redefinition of `OBJECT-AREA`)
`JSU-SUBMIT-FILE` | A250 | in | The file to be submitted (e.g. shell script, Windows BAT file).
`JSU-SYSOUT-FILE` | A250 | in | Output file for the file to be submitted.
`JSU-EXIT-CODE` | N10 | out | Only for the functions
`GETEXIT` | Read exit code from an output file.
`CANCEL` | Cancel the process.
`JSU-EXIT-CODE-SIGN` |  |  | Sign `+` or `-` of exit code. If the exit code itself has 10 digits, `exitCode` contains the absolute part, and the sign must be read from `exitCodeSign`. `exitCodeSign` is always being set, regardless of a sign in `exitCode`.
`JSU-USER` | A20 | in | User ID of the file to be submitted.
`JSU-GROUP` | A20 | in | Optional:
UNIX: | Group for the file to be submitted.
Windows: | Domain for the file to be submitted.
`JCA-KILL-MODE` | A1 | in | Only for UNIX, only for function `CANCEL`:
`K` | Use `SIGKILL`. (default value)
`T` | Use `SIGTERM`.
`JSU-PID` | N10 | out | Process ID of the submitted file.
|  |  | Object: `USER` Function: `LOGON` (redefinition of `OBJECT-AREA`)
`UL-PASSWORD-MODE` | A1 | in | `C` | `UL-PASSWORD-A256` contains a password in plain text. (default value)
`E` | `UL-PASSWORD-A256` contains an encrypted password.
`UL-PASSWORD-A256` | A256 | in | The password. The encryption is determined by `UL-PASSWORD-MODE`. When this field is empty, the password is taken from `PASSWORD`. Note We recommended that you clear this field after a successful `USER` / `LOGON`.

#### data buffer

Mandatory for `FILE / READ` or `FILE / WRITE`, and if BUFFER-TYPE B, C or D is used. Optional for all other cases.

#### caller module (input only, optional)

You can pass the name of a calling module here. It will be passed to `NPR / UNIX` for an easier identification of the caller. If you want to pass your own module name here, you can use the following code:

                ...
                1 #PROGRAM (A8)
                ...
                #PROGRAM := *PROGRAM
                ...
                CALLNAT ‘NOPUNX1N’ NOPUNX1A 1X #PROGRAM (AD=O)
                ...

### Runtime Environment

- The API can be run on mainframes, UNIX or Windows.

- With this API you can access only UNIX and Windows nodes.

- In the selected Natural environment you must define the steplib SYSEOR and the steplibs used by SYSEOR.

- The system files (System File 1, System Automation Tools Log File) used by Entire Operations must be defined by `LFILE` assignments.

### Programming Requirements

> API Invocation

>   In general, API `NOPUNX1N` is invoked with the requested object and function.

> Windows File Names

>   Windows file names can also be specified with a slash instead of a backslash.

>   Example:

>       c:/work/file1.txt

>   is equivalent to

>       c:\work\datei1.txt

> Return Code Checking

>   Checking NOPUNX1A.RETURN-CODE is mandatory after each API call.

>   `NOPUNX1A.RETURN-CODE = 0` (zero) indicates that the API call was ok.

>   NOPUNX1A.RETURN-TEXT can contain more information related to the return code.

>   If an error occurs, an appropriate reaction is required.

>   If processing is to be terminated as a reaction to an error, please take care of the following:

>   - If a file is currently open, it must be closed using `FILE / CLOSE`.

>   - If a session is currently open, it must be closed using `USER / LOGOFF`.

> Session

>   All file operations are functional only during a valid session.

>   A session must be started with `USER / LOGON`, and must be terminated with `USER / LOGOFF`.

>   During a session (including `USER / LOGOFF`), the `NOPUNX1A.SESSION-ID` must not to be changed.

>   A `USER / LOGOFF` at the end of a session is mandatory. After the `USER / LOGOFF`, the `NOPUNX1A.SESSION-ID` is invalid and must not be used anymore for any call.

> Course of Session

>       USER / LOGON
>       FILE / ...
>       FILE / ...
>       ...
>       USER / LOGOFF

### Opening and Closing a File

- Files must not be explicitly opened. This will be done automatically with the first call of `FILE / READ` or `FILE / WRITE`.

- At the first successful `FILE / READ` or `FILE / WRITE`, the API returns a file handle in `NOPUNX1A.F-HANDLE`. This must be passed by all subsequent calls to the same file (read or write session), including the final `FILE / CLOSE` call.

- After a read or write session, the file must be closed with the function `FILE / CLOSE`.

  `NOPUNX1A.F-HANDLE` becomes invalid then.

### Reading a File

With the function `FILE / READ`, a file is read in sequential mode.

In `NOPUNX1A.F-LINE` you can provide a line number to start.

If `NOPUNX1A.F-LINE` contains the value `0` (zero) or `1`, the read sequence starts at the beginning of the file.

> Scheme

>       USER / LOGON

>       R1. repeat
>          FILE / READ
>          if (NOPUNX1A.RETURN-CODE ne 0)
>              escape bottom (R1.)
>          end-if
>          ... handle record
>       end-repeat       /* R1.

>       FILE / CLOSE

>       USER / LOGOFF

### Searching for specific Data Sets in a File

With the function `FILE / SCAN`, it is possible to search for a specific string in a file. The search string must be present in `NOPUNX1A.F-SEARCH-TEXT`.

> Scheme

>       USER / LOGON

>       R1. repeat
>          FILE / SCAN
>          if (NOPUNX1A.RETURN-CODE ne 0)
>              escape bottom (R1.)
>          end-if
>          ... handle record
>          add 1 to NOPUNX1A.F-LINE
>       *           -- line start for follow-up scan
>       end-repeat       /* R1.

>       FILE / CLOSE

>       USER / LOGOFF

### Writing a File

With the function `FILE / WRITE`, a file is written in sequential mode.

> Scheme

>       USER / LOGON

>       R1. repeat
>          ... allocate record  in NOPUNX1A.F-RECORD-250
>       FILE / WRITE
>          if (...)
>              escape bottom (R1.)
>          end-if
>       end-repeat       /* R1.

>       FILE / CLOSE

>       USER / LOGOFF

### Reading and Writing a File Using a Large Buffer

The following is an example of using a large data buffer to read or write files.

1. Define a large data buffer:

       1 #BUFFER-99000 (A99000)

   Choose one of the following buffer types:

       NOPUNX1A.BUFFER-TYPE := 'B'              /* 9900 bytes
       NOPUNX1A.BUFFER-TYPE := 'C'              /* 99000 bytes
       NOPUNX1A.BUFFER-TYPE := 'D'              /* 59000 bytes

2. Call the API:

       CALLNAT 'NOPUNX1N' NOPUNX1A #BUFFER-99000

   The parameter definition of NOPUNX1N is:

       DEFINE DATA
       PARAMETER USING NOPUNX1A
       PARAMETER
       1 P-BUFFER-99000 (A99000)
         BY VALUE RESULT OPTIONAL
       ...
       END-DEFINE

Note
`#BUFFER-99000` can contain a maximum of 9900, 99000 or 59000 bytes depending on the size specified with `NOPUNX1A.BUFFER-TYPE`. The data written to the buffer can have less bytes but must not exceed the specified buffer size.

### Deleting a File

With the function `FILE / DELETE`, you can delete one or several files. If `F-FILE` contains a wildcard (*), all files will be deleted that match the wildcard.

### Copying a File

With the function `FILE / COPY`, the target file is passed on to `F-RECORD-250`.

### Moving or Renaming a File

With the function `FILE / MOVE`, the target file is passed on to `F-RECORD-250`.

### Verifying the Existence of a File

To verify the existence of a file, you can use the function `FILE / DIR` with a defined file name. If a 0 (zero) is returned to `NOPUNX1A.RETURN-CODE`, the files exists.

### Creating a List of Files of a Directory

With the function `FILE / DIR`, you can create a list of files of a directory. With the wildcard expression contained in `NOPUNX1A.F-FILE` you can keep the list small.

> Example

>   `/tmp/*` | All files in the directory /tmp.
>   `/tmp/*.txt` | All files in the directory /tmp that end with .txt.

>   The file names are stored in `F-RECORD-BUFFER`. The file names are separated by a semicolon (;) as indicated for `SHOW-DIR-BUFFER` in the following example.

>   If the buffer is not large enough for the file names, then the value 19 (more objects) is passed on to `NOPUNX1A.RETURN-CODE`.

> Scheme

>       USER / LOGON

>       ... allocate file name (with wildcard) in NOPUNX1A.F-FILE

>       R1. repeat
>       FILE / DIR
>          decide on first value of NOPUNX1A.RETURN-CODE
>              value 0, 19      /* 0: ok, 19: more objects
>                   perform SHOW-DIR-BUFFER
>              none value
>                   ignore
>          end-decide
>          if  NOPUNX1A.RETURN-CODE ne 19
>              escape bottom (R1.)
>          end-if
>          add 1 to NOPUNX1A.F-LINE
>       end-repeat       /* R1.

>       FILE / CLOSE

>       USER / LOGOFF

>       * ---------------------------------------------------------------------
>       DEFINE SUBROUTINE SHOW-DIR-BUFFER
>       *                 ---------------
>       * -- Function FILE / DIR:
>       * -- The record buffer contains a file list, with delimiter ';'
>       * -- This routine separates the single file names out of the buffer.
>       * -- #DIR-FILE and #DIR-REST should be declared as (A600)
>       *
>       SDB1. REPEAT
>            EXAMINE  NOPUNX1A.F-RECORD-BUFFER FOR ';' REPLACE FIRST WITH ':'
>       SEPARATE NOPUNX1A.F-RECORD-BUFFER INTO #DIR-FILE #DIR-REST
>                     WITH DELIMITER ':'
>       *  -- now #DIR-FILE contains a single file name, without qualifiers

>                IF #DIR-REST = ' '
>                    ESCAPE BOTTOM (SDB1.)
>                END-IF
>         NOPUNX1A.F-RECORD-BUFFER := #DIR-REST
>       END-REPEAT     /* SDB1.
>       END-SUBROUTINE

## NOPURE2N: Handle Resource Allocations

You can handle resource allocations and deallocations with the following statement:

    CALLNAT 'NOPURE2N'
        P-FUNCTION P-RC P-DBENV P-OWNER P-NETWORK P-NETWORK-VERSION P-RUN
        P-JOB P-RESOURCE P-QUANTITY P-DEALLOCATION P-JOB-EXECUTED
        [P-ALLOCATION-MODE] [P-DEALLOCATE-NOT-OK]

### Parameter Description

Parameter | Format/Length | Use
--- | --- | ---
`P-FUNCTION` | A1 | in | Function code:
`A` | Allocate resource.
`R` | Release one or several resources. If job and resource name given: release only one allocated resource of one job. If job given, but no resource: release all allocated resources of one job. If run number, but no job and no resource given: release all allocated resources of one network run. If no run number and no job and no resource given: Release all allocated resources of all network runs.
`N` | Network release. Release resources with deallocation = `N` as well. For other parameters, see `R`.
`F` | Forced release. Release resources with deallocation = `N` or `K` as well. For other parameters, see `R`.
`G` | Forced release, by resource usage. Release resources with deallocation = `N` or = `K` as well. For other parameters, see `R`.
`P` | Modify (active) prerequisite resource definition.
`T` | Test resource usage, sorted by active jobs. Subsequent calls read in the order of active jobs, then resource names. Sequential reading The sequential reading starts at the first found resource in the order of active jobs, then resource names. Fields returned by the previous call must be kept and passed for the next call. `P-RC = 5` (resource usage entry not found) is returned, if there are no more entries for this resource.
`U` | Test resource usage, sorted by resources, then by active jobs. Sequential reading The sequential reading starts at the first found resource, in alphabetical order, where the name of the first found resource is equal or subsequent to the name passed in `P-RESOURCE`. Fields returned by the previous call must be kept and passed for the next call. `P-RC = 5` (resource usage entry not found) is returned at the end of all resource usage entries.
`V` | Test resource usage, sorted by active jobs. Subsequent calls read in the order of resource names, then active jobs. Sequential reading The sequential reading starts at the first found resource followed by the superdescriptor of the active job (identified by `P-OWNER`, `P-NETWORK`, `P-RUN`, `P-JOB`). Fields returned by the previous call must be kept and passed for the next call. `P-RC = 5` (resource usage entry not found) is returned at the end of all resource usage entries.
`P-RC` | N3 | out | Return code:
`0` | Function OK.
`1` | Active job not found.
`2` | Resource not defined for job.
`3` | Resource (master) definition not found.
`4` | Quantity is not available.
`5` | OK, but no resource usage entries were found. This code may be returned: if the resource has already been freed. if the resource was never allocated.
`6` | Prerequisite resource definition not found.
`101` | Invalid function code.
`102` | Parameter(s) missing.
`103` | Wildcard not allowed.
`104` | `P-DEALLOCATION` has wrong value.
`121` | Owner does not exist.
`P-DBENV` | A10 `OPTIONAL` | in | Database environment (reserved for future use).
`P-OWNER` | A10 | in | Owner. Wildcard allowed. Function `A`: obligatory, no wildcard allowed.
`P-NETWORK` | A10 | in | Network. Wildcard allowed. Function `A`: obligatory, no wildcard allowed.
`P-NETWORK-VERSION` | A10 | in | Network version.
`P-RUN` | I4 | in | Run. A value of zero means all runs of a network. Function `A`: obligatory, no wildcard allowed.
`P-JOB` | A10 | in | Job. If empty, the whole network is meant. Wildcard allowed. Function `A`: obligatory, no wildcard allowed. Note If this API is used to free a resource and if the allocation was made by another job, this field must remain empty.
`P-RESOURCE` | A20 | in | Name of the resource. If empty, all prerequisite resource definitions of a job are meant. Function `A`: obligatory, no wildcard allowed.
`P-QUANTITY` | N7.2 | in | For function `A` and `B`: quantity to be allocated. The value must be greater than or equal to zero.
`P-DEALLOCATION` | A1 | in | How to deallocate this allocation (for function `A` only).
`J` | After job termination.
`N` | After network termination.
`K` | Keep until explicit release.
For a detailed description of deallocation modes, see Resource Deallocation Modes in the section Job Maintenance.
`P-JOB-EXECUTED` | L | in | Not reusable resources are decreased only if the job was really executed.
`P-ALLOCATION-MODE` | A1 `OPTIONAL` | in | Allocation mode
`A` | Always allocate the resource (default).
`T` | Do not allocate the resource if the active job becomes a temporary dummy, see Temporary Dummy Jobs.
`P-DEALLOCATE-NOT-OK` | A1 `OPTIONAL` | in | Deallocate if job not ok. Note This definition is only relevant for deallocation mode `J`, see Resource Deallocation Modes in the section Job Maintenance.
`Y` | Deallocate the resource even if the job was not ok (default).
`N` | Keep the resource allocated if the job ended not ok.

## NOPURS1N: Access Entire Operations Resource Masters

This section covers the following topics:

- Handling Entire Operations Resource Masters

- Description of Function Codes

### Handling Entire Operations Resource Masters

You can handle resource masters with the following statement:

    CALLNAT 'NOPURS1N'
        P-FUNCTION P-RC P-NODE P-RESOURCE P-TYPE P-INIT-QTY P-USED-QTY

Meaning of the parameters:

Parameter | Format/Length | Use
--- | --- | ---
`P-FUNCTION` | A1 | in | Function code:
`A` | Add a resource.
`D` | Delete a resource.
`M` | Modify a resource.
`T` | Test a resource.
See also Description of Function Codes.
`P-RC` | N3 | out | Return code:
`0` | Function OK; resource found.
`1` | Resource not found.
`2` | Resource already exists.
`3` | Inconsistent values.
`4` | Initial quantity may not be modified.
`101` | Invalid function code.
`102` | Resource name missing.
`P-NODE` | N3 | in | Not used; use constant with value=0.
`P-RESOURCE` | A20 | in | Name of the resource.
`P-TYPE` | A1 | in | Type of resource (only for `FUNCTION = 'A'`).
`N` | Not quantitative.
`R` | Quantitative, reusable.
`U` | Quantitative, not reusable.
`P-INIT-QTY` | P7.2 | in/out | Total quantity.
`P-USED-QTY` | P7.2 | in/out | Currently used quantity.

### Description of Function Codes

Meaning of the function codes:

Code | Description
--- | ---
`A` | Adds a new resource definition. You must give values for `P-TYPE`, `P-INIT-QTY` and `P-QTY`.
`D` | Deletes a resource definition.
`M` | Used to modify the values `P-INIT-QTY`.
`T` | Returns the current values of `P-INIT-QTY` and `P-QTY`.

Notes:

1. Before using `M` for modifications, you should use `T` to read the present values (unless you want to enter an absolute value).
2. The currently used amount of a resource can no longer be modified directly. You must perform a resource allocation or deallocation with the API NOPURE1N to modify the currently used resource amount.

## NOPUSN2N: Inquire Calling Job or Called Network for Subnetworks

You can use this API to:

- Find the current subnetwork for a job of type `NET` (subnetwork);

- Find the current job calling a subnetwork.

Use the following statement:

    CALLNAT 'NOPUSN2N'
        P-FUNCTION P-RC P-DBENV *P-OWNER P-NETWORK P-NETWORK-VERSION
        P-RUN P-JOB

The parameters `P-OWNER`, `P-NETWORK`, `P-RUN` and `P-JOB` are input and output parameters. They are overwritten with the values found by the API. Therefore the caller must supply these fields with new entries before each new call.

### Parameter Description

Parameter | Format/Length | Use
--- | --- | ---
`P-FUNCTION` | A1 | in | Function code:
`C` | Find calling job (available for active subnetworks only).
`S` | Find subnetwork.
`T` | Find the topmost calling job (available for active subnetworks only). This function recursively goes back in the subnetwork hierarchy, until the caller job is no longer part of a subnetwork.
`P-RC` | N3 | out | Return code:
`0` | Function OK.
`1` | Input object not found.
`2` | Wrong job type.
`3` | No calling job.
`4` | No symbol(s) with caller information.
`101` | Invalid function code.
`102` | Parameter missing.
`121` | Owner does not exist.
`141` | Symbol access error.
`P-DBENV` | A10 `OPTIONAL` | mod | Database environment (reserved for future use).
`P-OWNER` | A10 | mod | Owner of the network.
`P-NETWORK` | A10 | mod | Network.
`P-NETWORK-VERSION` | A10 | mod | Network version.
`P-RUN` | I4 | mod | Run number. If the function `S` is used for a job master, this parameter must be zero.
`P-JOB` | A10 | mod | Job.

## NOPUSP3N: Display Long Texts for Symbol Prompting

You can display the symbol prompting long text for a specified symbol by using the following statement in your Natural application:

    CALLNAT 'NOPUSP3N'
        P-FUNCTION P-DBENV P-OWNER P-NETWORK P-RUN P-SYMTAB P-SYMTAB-VERSION
                   P-SYMBOL P-PROMPT-TYPE P-RC P-PROMPT-TEXT (*)

### Parameter Description

Parameter | Format/Length | Use
--- | --- | ---
P-FUNCTION | A1 | in | Function code:
G | Get prompting attributes (for master and active).
S | Set prompting attributes (for master and active).
P-DBENV | A10 `OPTIONAL` | in | Database environment (reserved for future use).
P-OWNER | A10 | in | Owner of the symbol table.
P-NETWORK | A10 | in | Job network (for active symbols).
P-RUN | I4 | in | Job run number (for active symbols).
P-SYMTAB | A10 | in | Symbol table.
P-SYMTAB-VERSION | A10 | in | Symbol table version.
P-SYMBOL | A40 | in | Name of the prompted symbol.
P-PROMPT-TYPE | A1 | in/out | Input parameter for the function code S, and output parameter for the function code G. Possible values:
A | Prompt for a symbol at each activation.
E | Prompt only if no value is specified in the symbol table.
N | Never prompt for a symbol.
P-RC | N3 | out | Return code:
0 | Function ok.
1 | Symbol not found.
99 | Invalid parameter value.
111 | Symbol table name begins with reserved prefix `=EOR=`.
P-PROMPT-TEXT | A70/1:V | out | Symbol prompting long text. Caller should provide an array of at least 5 text lines.

## NOPUST3N: Inquire Network and Job Status, Symbol Table

You can inquire the current status of an active job network or of a single active job by using the following statement in your Natural application:

    CALLNAT 'NOPUST3N'
        P-FUNCTION P-RC P-DBENV P-OWNER P-NETWORK P-NETWORK-VERSION P-JOB P-RUN
        P-SYMTAB P-SYMTAB-VERSION P-JOB-ID P-STATUS-TIME

This section covers the following topics:

- Parameter Description

- Inquire Status of Whole Active Network

- Inquire Status of all Jobs of an Active Network Individually

- Inquire Symbol Table Used

- Example of Using NOPUST3N

### Parameter Description

Parameter | Format/Length | Use
--- | --- | ---
P-FUNCTION | A1 | in | Function code:
`A` | Get next active run number (in numerical order) beginning with a starting run number. If the starting run number is equal to the run number limit, the range from 1 to the starting run number minus 1 is checked.
`R` | Get last activated run number (in chronological order).
`S` | Inquire status.
`N` | Inquire status of next job (alphabetically).
`W` | Status of next job waiting for anything, or of next job in status `permanent error`.
`Y` | Get name of symbol table either from network master or from job definition.
P-RC | N3 | out | Return code:
| `0` | Function OK.
| `1` | Network/job not found, or run number does not exist.
| `20` | Waiting for symbol prompting.
| `21` | Waiting for job/network activation.
| `25` | Waiting for prerequisite.
| `26` | Job(s) are in hold.
| `27` | Waiting for next action or start time.
| `28` | Waiting for input condition.
| `29` | Waiting for resource.
| `30` | Waiting for operating system node.
| `31` | Waiting for JCL to be loaded.
| `32` | Network activation error.
| `33` | Job activation error.
| `34` | Symbol replacement error.
| `35` | Schedule extraction or network activation error.
| `36` | Job is being submitted.
| `37` | Job submission error.
| `38` | Job is executing.
| `39` | Job execution error.
| `41` | Network/job is executing.
| `42` | Performing End-of-Job checking.
| `43` | End-of-Job checking error.
| `44` | Performing End-of-Job actions.
| `45` | End-of-Job actions error.
| `65` | All jobs ended successfully.
| `66` | Job(s) ended not successfully.
| `69` | Permanent error(s).
| `93` | Waiting for network to be deactivated.
| `101` | Invalid function code.
| `102` | Parameters missing.
| `121` | Owner does not exist.
| `999` | Status not defined.
P-DBENV | A10 `OPTIONAL` | in | Database environment (reserved for future use).
P-OWNER | A10 | in | Owner of network.
P-NETWORK | A10 | in | Job network.
P-NETWORK -VERSION | A10 | in | Version of job network.
P-JOB | A10 | in | Job. If left blank, inquiry is for whole network.
out | The job for which the return code is returned.
P-RUN | I4 | in | Function code:
`A` | Starting run number (can be 0).
`S` | Run number to be checked.
out | Function code:
`A` | Next active run number (in numerical order).
`R` | Last run number of the network in chronological order.
P-SYMTAB | A10 | out | Name of the defined symbol table. Function `R`: Name of the defined symbol table on the network level. Function `Y`: Name of the defined symbol table on the network level (empty `P-JOB`), or the job level (given `P-JOB`). Empty, if a symbol table is not defined on the requested level.
P-SYMTAB-VERSION | A10 | out | Version of the symbol table. The parameter only applies if `P-SYMTAB` contains a name.
P-JOB-ID | A10 | out | ID of the job (for single jobs only, and only if the job was already submitted).
P-STATUS-TIME | A14 | out | Timestamp when the current status of the job was set. Format: YYYYMMDDHHIISS.

### Inquire Status of Whole Active Network

Use function `S`. Leave the `P-JOB` parameter blank.

### Inquire Status of all Jobs of an Active Network Individually

Use function `N`. Delete the `P-JOB` parameter. Then invoke this API in a `REPEAT` loop until you get RC = 1 (network end).

Each call returns the status of a job. The name is contained in `P-JOB`. Do not change the content of `P-JOB`, because it is used as starting value for the next call.

### Inquire Symbol Table Used

The symbol table used is always returned for active networks and jobs.

For network masters and jobs, you can use the function `Y`.

Notes:

- The status inquiry functions independently of Monitor activity, because it uses database entries.

- For a whole network inquiry (with function `S`), the statuses of the individual jobs are linked with logical AND. In the worst case, if at least one job has failed, the status `failed` is returned for the whole network.

- An active network is considered to have `terminated OK` only if all its active jobs have `terminated OK`.

- The status inquiry is only possible as long as the network or job involved has not been deactivated.

- To obtain all active run numbers of a network, proceed as follows:

  1. Use function `A`.

  2. Begin with starting run number 0.

  3. Call the API.

  4. Terminate when RC is not equal to 0, or when the number returned for the active run is less than the number of the previous run.

  5. Keep result as next starting run number and continue with Step 3 (Call the API).

### Example of Using NOPUST3N

    ...
     1 #RC (N3)
     1 #OWNER (A10)
     1 #NETWORK (A10)
     1 #NETWORK-VERSION (A10)
     1 #JOB (A10)
     1 #RUN (I4)
     1 #SYMTAB (A10)
     1 #SYMTAB-VERSION (A10)
     1 #JOB-ID (A10)
     1 #STATUS-TIME (A14)
     ...

    CALLNAT 'NOPUST3N'
     'S' /* get status
      #RC 1X #OWNER #NETWORK #NETWORK-VERSION #JOB #RUN
      #SYMTAB #SYMTAB-VERSION #JOB-ID #STATUS-TIME

In the above example, `1X` is the placeholder for the `OPTIONAL` parameter `P-DBENV`.

## NOPUSY7N: Access Entire Operations Symbols

You can handle symbols in symbol tables using the following statement:

    CALLNAT 'NOPUSY7N'
        FUNCTION RC DBENV OWNER NETWORK NETWORK-VERSION RUN JOB SYMTAB SYMTAB-VERSION SYMBOL FORMAT
        VALUE USER TIME
       1X 1X
       VALUE-INDEX

Where:

`1X 1X` are placeholders for `OPTIONAL` parameters required for internal purpose only.

This section covers the following topics:

- Description of Parameters

- Description of Function Codes

- Sequential Reading in a Symbol Table

- Example of Sequential Symbol Table Reading

#### Related Topic:

- Symbol Table and Symbol Maintenance

### Description of Parameters

Parameter | Format/Length | Use
--- | --- | ---
`FUNCTION` | A1 | in | Function code:
`D` | Delete one multiple value.
`M` | Add one multiple value.
`N` | Test next symbol.
`P` | Test next symbol to be prompted.
`R` | Reset a symbol.
`S` | Set (add or modify) a symbol.
`T` | Test existence of a symbol and inquire its value.
`1` | Test existence of a symbol and inquire its value, with recursive resolution.
`4` | Applies to active symbol tables only. Test next symbol and inquire its value, with recursive resolution.
See also Description of Function Codes.
`RC` | N3 | out | Return code:
`0` | Function OK; symbol found.
`1` | Symbol not found.
`2` | Invalid numeric value.
`3` | Invalid format.
`4` | Format modification attempted.
`5` | Multiple table full.
`6` | Value missing.
`7` | Attempted to write a predefined (read-only) symbol. Refer to Predefined Symbols Ranges.
`10` | Invalid value by user exit.
`11` | User exit not found.
`12` | Access to user exit not allowed (Natural Security).
`20` | OK; is a multiple value.
`30` | OK; the symbol master was also modified.
`101` | Invalid function code.
`102` | Parameter missing.
`111` | Symbol table name starts with reserved prefix `=EOR=`.
`121` | Owner does not exist.
`131` | Invalid symbol table name.
`132` | Invalid symbol table version name.
`777` | Internal parameter error. Refer to the Entire Operations log for more information.
`DBENV` | A10 `OPTIONAL` | in | Database environment (reserved for future use).
`OWNER` | A10 | in | Owner of the symbol table.
`NETWORK` | A10 | in | Network (for active symbol table only).
`NETWORK-VERSION` | A10 | in | Network version.
`RUN` | P13 | in | Run (for active symbol table only).
`JOB` | A10 | in | Job.
`SYMTAB` | A10 | in | Symbol table.
`SYMTAB-VERSION` | A10 | in | Symbol table version.
`SYMBOL` | A40 | in | Symbol.
out | For function codes `N` and `P`.
`FORMAT` | A1 | in | Symbol format. For the function `1` for symbol table masters, this parameter has a special meaning: `FORMAT` may contain the escape character to be used for the recursive resolution. The format values (below) and a question mark (?) must not be used as escape character.
out | For function codes `N`, `P` and `T`.
blank or `A` | Alphanumeric. No case conversion.
`D` | Date in the format: YYYYMMDD See also Date and Time Formats.
`H` | Alphanumeric. Hidden.
`L` | Alphanumeric. Conversion to lower case.
`N` | Numeric.
`U` | Alphanumeric. Conversion to upper case.
`VALUE` | A250 | in | Symbol value.
out | For function codes `N`, `P` and `T`.
`VALUE-INDEX` | I4 | in | Index for multiple-value symbols. Set `VALUE-INDEX` to an appropriate value. After the call, this value is adapted to the index of the next multiple-value symbol read. If the value set for `VALUE-INDEX` is higher than the highest index of the given symbol, the next symbol is read.
out | For function code `4` only.
`USER` | A8 | out | User who made the last modification.
`TIME` | T | out | Time of the last modification.

### Description of Function Codes

Meaning of the function codes:

Code | Description
--- | ---
`D` | Delete one multiple value. Resets one value in a multiple-value symbol. If this is the last symbol value, the whole symbol is removed from the table.
`M` | Add one multiple value. Sets one more value in a multiple-value symbol. Even if the quantity of the multiple values is `1`, the single value remains a multiple value. It will not be converted into a standard value.
`N` | Test next symbol. Tries to find the next symbol (in alphabetic order) from the specified symbol. The given name is overwritten by the name found. The other fields are returned as in function `T`. To find the first symbol of a symbol table, the symbol name can be omitted. If the end of the symbol table is reached, code `1` is returned. See also Sequential Reading in a Symbol Table.
`P` | Test next symbol to be prompted. Finds the next symbol in alphabetical order to be prompted for the current network/job run. Otherwise works like function code `N`.
`R` | Reset a symbol. The symbol is removed from the symbol table.
`S` | Set a symbol. If the symbol does not exist in the symbol table, it is inserted; if it already exists, it is overwritten.
`T` | Test a symbol. If the symbol is not found, code `1` is returned. If the symbol exists, its format and value are returned. The fields `USER` and `TIME` contain the user and timestamp of the last modification.
`1` | Test a symbol. If the symbol is not found, code `1` is returned. If the symbol exists, its format and value are returned. If the symbol value contains symbols, they will be resolved recursively. The fields `USER` and `TIME` contain the user and timestamp of the last modification.
`4` | Applies to active symbol tables only. Test next symbol and inquire its value, with recursive resolution. This function requires you to specify the following: A network and run number (in addition to owner). The `VALUE-INDEX` parameter. See also Sequential Reading in a Symbol Table.

Notes:

1. To access a symbol table master, the fields `NETWORK` and `RUN` must be empty. To access an active symbol table, the fields `NETWORK` and `RUN` must be supplied by the caller.
2. If a validation check user exit (see the section User Exits) is defined for the symbol, it is invoked from this API routine, too. Make sure that the user exit is accessible in the calling environment. The library containing the user exit must be defined as a steplib for the executing environment of these APIs. A symbol value is rejected if the exit returns `not OK` (`RC=10`) or if the exit is missing (`RC=11`).
3. All actions will be logged.
4. The API is can also read the values of predefined symbols (described in Symbol Table and Symbol Maintenance).
5. Symbol created by this API will get the symbol prompting setting `N` (never). See also Symbol Prompting during Network or Job Activation in the section Symbol Table and Symbol Maintenance.

### Sequential Reading in a Symbol Table

To read symbols sequentially from a master or an active symbol table

1. Set the function to `N`.

2. If you want to start reading at the start of the table, reset `SYMBOL` first; otherwise put a start name into `SYMBOL`.

3. Call the user exit in a `REPEAT` loop; leave it if `RC` is not `0` and not `20`.

4. Leave `SYMBOL` unchanged as the start value for the next call.

5. Reset `VALUE` before the next call if `RC=0`.

6. Do not reset `VALUE` if `RC=20`.

To read symbols sequentially from an active symbol table

1. Set the function to `4`.

2. If you want to start reading at the start of the table, reset `SYMBOL` first; otherwise put a start name into `SYMBOL`.

3. Leave `SYMBOL` and `VALUE-INDEX` unchanged as the start values for the next call.

4. Reset `VALUE` before the next call if `RC=0`.

5. Do not reset `VALUE-INDEX` if `RC=20`.

### Example of Sequential Symbol Table Reading

    MOVE 'N' TO FUNCTION
    RESET SYMBOL-NAME
    R1.  REPEAT
         CALLNAT 'NOPUSY7N' RC  ...

         DECIDE ON FIRST VALUE OF RC
         VALUE 0, 20 IGNORE
         VALUE 1 ESCAPE BOTTOM (R1.)
         NONE VALUE
                /* Error handling
         END-DECIDE
                /* process symbol here
         IF RC NE 20
              RESET VALUE
         END-IF
    END-REPEAT

## NOPUVI2N: Obtain Entire Operations Version Information

You can use this API to find out the version of Entire Operations. Use the following statement:

    CALLNAT 'NOPUVI2N'
        P-FUNCTION P-VERSION P-VERSION-DATE P-UPDATE-DATE

### Parameter Description

Parameter | Format/Length | Use
--- | --- | ---
`P-FUNCTION` | A1 | in | Function code:
`V` | Version information.
`P-VERSION` | A20 `BY VALUE RESULT` | out | Version, in the format vv.rr.ss.pppp: see Format for Product Versions.
`P-VERSION-DATE` | A8 | out | Date of version. Format: YYYYMMDD. See also Date and Time Formats.
`P-UPDATE-DATE` | A8 | out | Date of last updates. Format: YYYYMMDD. See also Date and Time Formats.

> Format for Product Versions

>   A product version in the format `vv.rr.ss.pppp` denotes the following:

>   `vv` | Major version.
>   `rr` | Minor version.
>   `ss` | Service pack.
>   `pppp` | Fix.

>   Leading zeros are omitted, for example: `5.5.1.1`.

>   Note
>   For further information on product versions, see Version in the Glossary of the Natural documentation.

## NOPUXD1N: Maintain End-of-Job User Exits for a Network

You can maintain End-of-Job (EJA) definitions of a specific activated network using the following call from your Natural application.

    CALLNAT 'NOPUXD1N' UXD-PARAMETER-AREA

The parameters have the following meaning:

Parameter | Format/Length | Use
--- | --- | ---
`UXD-FUNCTION` | A1 |  | `A` | Add.
`M` | Modify.
`D` | Delete.
`UXD-RC` | N4 |  | Return code:
`0` | Function OK.
`1` | Input object not found.
`2` | Wrong job type.
`3` | Not a calling job.
`4` | Call place not supported.
`5` | Invalid exit mode.
`6` | Run number not in range.
`7` | Exit is already defined. Note For `UXD-FUNCTION` `A` only.
`101` | Invalid function code.
`102` | Parameter(s) missing.
`121` | Owner does not exist.
`UXD-DBENV` | A10 |  | Reserved for future use.
`UXD-OWNER` | A10 |  | Reserved for future use.
`UXD-NETWORK` | A10 |  | Reserved for future use.
`UXD-RUN` | I4 |  | Reserved for future use.
`UXD-JOB` | A10 |  | Reserved for future use.
`UXD-EVENT-TYPE` | A3 |  | `JOK` | Job OK.
`JNO` | Job not OK.
`UEX` | No influence.
`UXD-EVENT-NAME` | A30 | in | Selected event. If empty, a new additional job-ok or job-not-ok event will be added.
out | Event name used.
`UXD-EXIT-CALL-PLACE` | A3 |  | `EJA` End-of-Job action.
`UXD-EXIT-LIBRARY` | A8 |  | Reserved for future use.
`UXD-USEREXIT` | A8 |  | Reserved for future use.
`UXD-EXIT-MODE` | A1 |  | blank | Synchronous execution.
`A` | Asynchronous execution.

## NOPUXI0N: Add Input Condition to an Activated Job

You can add an input condition to an activated job using the following call from your Natural application.

    CALLNAT 'NOPUXI0N'
      P-OWNER
      P-NETWORK
      P-JOB
      P-RUN-NUMBER
      P-RC
      P-CONDITION
      P-NATURAL-LIBRARY
      P-NATURAL-SUBPROGRAM

The parameters have the following meaning:

Parameter | Format/Length | Use
--- | --- | ---
`P-OWNER` | A10 | in | Owner name.
`P-NETWORK` | A10 | in | Network name.
`P-JOB` | A10 | in | Job name.
`P-RUN-NUMBER` | I4 | in | Run number.
`P-RC` | N3 |  | `1` | Activated job does not exist.
`2` | Maximum number of existing conditions.
`3` | Global condition only allowed for owner SYSDBA.
`4` | Invalid parameters for condition passed.
`5` | Condition already exists.
`99` | Natural runtime error.
`P-CONDITION` | A20 | in | Name of the new condition.
`P-NATURAL-LIBRARY` | A8 | in | Name of exit library.
`P-NATURAL-SUBPROGRAM` | A8 | in | Name of exit subprogram.

### On this page

- EORUCB1N: Check Use of BS2000 User IDs
- NOPFB2-N: Generate SYSOUT File Names for BS2000
- NOPMLA1N: Start and Stop the Monitor Activity Log
- NOPU--1N: Read Network Available to a Specific User
- NOPU--2N: Return all Usable Symbol Tables for a Network
- NOPU--3N: Get Correlation ID for an Activated Network
- NOPU--4N: Store New Event in Entire Operations System File
- NOPUAC5N: Activate Job Networks or Jobs
- NOPUAS1N: Retrieve Numbers of Active Jobs in Defined Status Ranges
- NOPUCN3N: Access Entire Operations Conditions
- NOPUCS1N: Access Calendars and Schedules
- NOPUJI4N: Import Operating System Jobs into the Active Queue
- NOPUJS2N: Job Schedule Inquiry and Modification
- NOPULW9N: Write Messages to System Automation Tools Log
- NOPUMI1N: Set/Reset Text Milestones in Master and Active Jobs
- NOPUMT3N: Expand Message Texts
- NOPUNI1N: Invalidate Entire System Server Node Table Entries
- NOPUNX1N: Entire System Server Calls to Access UNIX and Windows Files
- NOPURE2N: Handle Resource Allocations
- NOPURS1N: Access Entire Operations Resource Masters
- NOPUSN2N: Inquire Calling Job or Called Network for Subnetworks
- NOPUSP3N: Display Long Texts for Symbol Prompting
- NOPUST3N: Inquire Network and Job Status, Symbol Table
- NOPUSY7N: Access Entire Operations Symbols
- NOPUVI2N: Obtain Entire Operations Version Information
- NOPUXD1N: Maintain End-of-Job User Exits for a Network
- NOPUXI0N: Add Input Condition to an Activated Job