Available Entire Operations API Routines

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

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 At least "" or "(current)".
P-DESCRIPTION A50 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 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

This section covers the following topics:

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

H Activate, but hold task until released.
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 time stamps 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.
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.
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.

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

Start of instruction set 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. You must call the routine NOPUSY7N (see the relevant section).

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

    Note:
    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

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

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

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 whole table (calendar or schedule).
2 Reset all dates in the whole table (calendar or schedule).
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       N3 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 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 in Required.

Execution node.
P-SYSOUT-NODE I4 in Optional.

Necessary only if P-SYSOUT-FILE is specified, and if P-SYSOUT-NODE is different from P-EXECUTION-NODE.

P-SYSOUT-FILE A250 in Required for BS2000, UNIX and Windows.

File which contains the SYSOUT.
P-BS2000-MONJV A250 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 time stamp 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 the buffer type B, C or D is used: 

CALLNAT 'NOPUNX1N' NOPUNX1A data-buffer

For all other calls:

CALLNAT 'NOPUNX1N' NOPUNX1A

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

Parameter Description

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 If 0, then the function was OK. If a different value was returned, then check the data content of RETURN-TEXT.
RETURN-TEXT A80 out Explanation of 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 analyzed 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.

We recommended that you clear this field after a successful USER / LOGON.

SID N10 can only be changed by the API Session ID from Entire System Server.

This field is set by the API at USER / LOGON. It should not be changed by the application until USER / LOGOFF.

UID A10 can only be changed by the API Internal user ID of the operating system.

This field is set by the API at USER / LOGON. It should not be changed by the application until USER / LOGOFF.

REDEF-1 A10 - Redefinition area.
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 in/out Operating system class of NODE.

Possible values:
B BS2000
M z/OS
V z/VSE
X UNIX
W Windows
USE-PAM A1 in For USER / 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 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 has to be in a qualified expression. That means in 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.

Runtime Environment

  • The API can be run under Entire Operations 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 Hints

Preface

In general the call OBJECT / FUNCTION (e.g. USER / LOGON), starts NOPUNX1N 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
Session

All file operations are functional only during a valid session.

The session is started with USER / LOGON, and ends with USER / LOGOFF.

During a session the SESSION-ID, UID and GID are not to be changed.

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.

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

Error Checking

After each call of NOPUNX1N, the error code is to be checked in NOPUNX1A.RETURN-CODE. In NOPUNX1A.RETURN-TEXT you can access the information.

Reading a File

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

In NOPUNX1A.F-LINE you can name 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.

Scrolling 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

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 Quantity to be allocated.

Function A only.

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.

NOPURS1N: Access Entire Operations Resource Masters

This section covers the following topics:

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

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:

Related Topic:

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 master symbol 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 master symbol tables, 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 time stamp 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 time stamp 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:

See also Sequential Reading in a Symbol Table.

Notes:

  1. To access a master symbol table, 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

Start of instruction set 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.

Start of instruction set 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.