User Exits

User exits (user routines) must be coded as Natural subprograms and are automatically invoked by the Entire Operations Monitor according to where they are defined.

Entire Operation user exits require information specified in the Natural parameter data area NOPXPL-A.

When implementing Entire Operation user exits, you use the Entire Operations editor (see also Editing Master JCL and Natural Sources in the section Job Maintenance) and must obey the User Exit Coding Restrictions.

This document covers the following topics:

What User Exits Can Do

User exits can be used to check job results and influence job flow by their return codes. Apart from running checks, however, the use of Entire System Server and Adabas technology allows user exits to perform various actions such as

  • Database updates;

  • File access and handling;

  • Access to operating system functions;

  • Validation checks.

User exits for the Monitor can perform any Adabas or Entire System Server function, but must not perform any type of screen I/O.

Entire Operations checks the existence of a user exit while it is being defined, as well as at invocation time. Entire Operations treats the non-existence of a user exit as an error. When such an error occurs at invocation time or during job processing, the job network execution is interrupted.

User exits can affect the Entire Operations job flow by sending a return code or other information back to the caller after execution, depending on the type and result of the routine.

Notes:

  1. User exits are invoked by the Entire Operations Monitor, which performs them as subroutines. Do not forget that intensive use of user exits can influence other work to be performed by the Monitor.
  2. For user exit coding, the user exit coding restrictions must be adhered to.

The following section describes the different types of user exit in more detail.

Global User Exits

Global user exits can be used in your whole Entire Operations environment. For more information, see the following sections in Global User Exits in the Administration documentation:

Front-end User Exits

Front-end user exits are coded as Natural subprograms and are invoked by the Entire Operations front end for specific processing.

They can use any user-defined map with the following restrictions:

  • The map (Natural object type M) must be accessible from the SYSEOR system library. The easiest way is to copy the required maps into the SYSEOR system library.

  • Note that Entire Operations can be executed with the following Natural language codes: 1 = English; 2 = German. So it could be useful to supply two maps and to refer to them with the ampersand & as a placeholder representing the current language code. For more information on this technique, see the section Multilingual User Interfaces in the Natural Programming Guide.

You can define the following front-end user exit:

Common User Exit Parameter Data Area NOPXPL-A

All user exits under Entire Operations must use the common parameter data area NOPXPL-A, which is available in both object and source format in the SYSEOR library.

For this reason, the initial coding of a user exit must always resemble: 

DEFINE DATA PARAMETER USING NOPXPL-A

This section covers the following topics:

User Exit Types, P-CALL-PLACE

The field P-CALL-PLACE in the parameter list shows for which purpose the user exit was called:

P-CALL-PLACE Description
EJA   End-of-Job Action

See also Defining Action User Exits in the section Defining and Managing End-of-Job (EOJ) Checking and Actions.

EJC   End-of-Job Checking

See also Defining Action User Exits in the section Defining and Managing End-of-Job (EOJ) Checking and Actions.

FSB   SYSOUT File Name Generation (BS2000)

See also NOPFB2-N: Generate SYSOUT File Names for BS2000 in the section API Routines.

ICO   Input Condition Value Determination

See also Input Condition with User Exit in the section Job Maintenance.

MAC   Dynamic JCL Generation

See also Dynamic JCL Generation (JCL Location MAC) in the section Job Maintenance.

NAT   Natural Program Standalone under Entire Operations (NAT-type Job)

See also Job Types in the section System Overview.

NVN Network version name, syntax check

See also Global Exit for Version Names in the Administration documentation.

RMD Resource Master Determination Exit

See also Using a Resource Master Determination Exit in the Administration documentation.

SFX   Symbol Function Exit

See User Exits for Symbol Functions.

SNF   Global Symbol not Found Exit

See Global Symbol not Found Exit in the Administration documentation.

SVN Symbol table version name, syntax check

See Global Exit for Version Names in the Administration documentation.

SYC   Symbol Validation Check

See User Exit for Validating Symbol Values.

SYF Symbol Function

See User Exits for Symbol Functions.

Parameters Used for Different Call Places

Field Name Format Call Place
P-CALL-PLACE A3 EJA EJC FSB ICO MAC NAT NVN RMD SFX SNF SVN SYC SYF
P-RC
(Return code) 		N4 out out out (15) out n/a out out out out out out out out
P-RT
(Return text) 		A66 out out out (15) out n/a out out out out out out out out
P-OWNER  A10 in in in in in in in in in in in in in
P-NETWORK  A10 in in in in in in in in in in in (3) in
P-NETWORK-VERSION-1 A10 n/a n/a n/a n/a n/a n/a in n/a n/a n/a n/a n/a n/a
P-JOB  A10 in in in in in in n/a in in in n/a n/a in
P-RUN  P13 in in in in in in n/a in in in n/a (3) in
P-ACTIVATION-TIME  T in in in in in in n/a in (7) n/a n/a n/a (3) n/a
P-EXECUTION-NODE  (10) N3 in in in in in in n/a in in in n/a n/a in
P-EXECUTION-OPSYS  A8 in in in in in in n/a in n/a n/a n/a n/a n/a
P-SYMTAB  A10 in in in in in in n/a in in in n/a n/a in
P-SYMTAB-VERSION-1 A10 n/a n/a n/a n/a n/a n/a n/a n/a n/a n/a in n/a n/a
P-CONDITION  A20 (6) (6) n/a in (2) n/a n/a n/a n/a n/a n/a n/a n/a
P-RESOURCE A20 in n/a n/a n/a n/a n/a n/a in n/a n/a n/a n/a n/a
P-SYMBOL (13) A20 (1) n/a n/a n/a n/a n/a n/a n/a n/a mod n/a n/a in
P-JOB-ID A10 out out n/a n/a n/a n/a n/a n/a n/a n/a n/a n/a n/a
P-JOB-NUMBER  (9)

(obsolete)

 N5 out out n/a n/a n/a n/a n/a n/a n/a n/a n/a n/a n/a
P-SYSOUT-FILE (11)  A54 (1) (1) out n/a n/a n/a n/a n/a n/a n/a n/a n/a n/a
P-FSB-OBJECT-TYPE  A5 n/a n/a in n/a n/a n/a n/a n/a n/a n/a n/a n/a n/a
P-FSB-USERID  A8 n/a n/a in n/a n/a n/a n/a n/a n/a n/a n/a n/a n/a
P-FSB-CATID  A4 n/a n/a in n/a n/a n/a n/a n/a n/a n/a n/a n/a n/a
P-FSB-SUFFIX  A2 n/a n/a in n/a n/a n/a n/a n/a n/a n/a n/a n/a n/a
P-SYMBOL-VALUE (14) A54 n/a n/a n/a n/a n/a n/a n/a n/a n/a out n/a n/a in
R-RMD-OLD-QTY-INITIAL
N7.2 n/a n/a n/a n/a n/a n/a n/a in n/a n/a n/a n/a n/a
P-RMD-NEW-QTY-INITIAL
N7.2 n/a n/a n/a n/a n/a n/a n/a out n/a n/a n/a n/a n/a
P-RMD-PARAMETER
A36 n/a n/a n/a n/a n/a n/a n/a in n/a n/a n/a n/a n/a

where:

n/a = Parameter can contain invalid values, do not modify.

in = Parameter contains input values.

out = Parameter contains output values.

mod = Parameter modifications are saved.

Notes:

1 in; BS2000 only
2 in; contains P-SUFFIX in first 10 bytes
3 in; only for active symbols
6 in; contains P-JOB-ID (A5) in first 5 bytes
7 in; here: timestamp of previous exit call
9 This field is obsolete. Use P-JOB-ID instead. The size of P-JOB-NUMBER is too small for some operating systems. For compatibility reasons, the field will be filled on return, if the job number is in the range of 1 to 99999.
10 Node numbers from 1 thru 999 are provided here. For node numbers greater than 999, P-EXECUTION-NODE is zero. Node numbers of any size are provided in the AIV variable +P-EXEC-NODE-I4 (I4).
11 For longer file names, you must use the AIV variable +P-SYSOUT-FILE-250 (A250).
13 This field is only maintained for compatibility reasons. Parameter modifications using the internal A40 format/length can truncate values thus causing data loss.
14 This field is only maintained for compatibility reasons. Parameter modifications using the internal A80 format/length can truncate values thus causing data loss.
15 For the fields P-RC and P-RT with P-CALL-PLACE set to ICO: see Input Condition with User Exit in the section Job Maintenance.

Additional Independent (AIV) Variables

In addition to the parameter list NOPXPL-A, some parameters are provided as independent (AIV) variables.

Field Name Format Call Place
    EJA EJC FSB ICO MAC NAT NVN RMD SFX SNF SVN SYC SYF
+P-NETWORK-VERSION A10 in in in in in in in in in in in n/a in
+P-SYMTAB-VERSION A10 in in in in in in n/a in in in n/a n/a in
+P-EXEC-NODE-I4 I4 in in in in in in n/a in in in n/a in in
+P-SYSOUT-FILE-250 A250 in in n/a n/a n/a n/a n/a n/a n/a n/a n/a n/a n/a
+P-JI-JOB-TYPE A3 in in n/a n/a n/a n/a n/a n/a n/a n/a n/a n/a n/a
+P-JI-DUMMY-FLAG A1 in in n/a n/a n/a n/a n/a n/a n/a n/a n/a n/a n/a

Field Descriptions

+P-NETWORK-VERSION Version of the network.
+P-SYMTAB-VERSION Version of the symbol table.
+P-EXEC-NODE-I4 This field provides node numbers of any size (1 thru 99900). It is provided for each node number. You must use it instead of P-EXECUTION-NODE, if the node number is greater than 999.
+P-SYSOUT-FILE-250 This field provides the SYSOUT file name in a field with a length of 250 bytes. You must use this field for the name of the SYSOUT file for a UNIX or Windows job (instead of P-SYSOUT-FILE) to avoid truncation.
+P-JI-JOB-TYPE The job type (A3). For valid values, see the three-letter codes in Available Job Types in the section Job Maintenance.
+P-JI-DUMMY-FLAG Reason why a job became a temporary dummy job (dummy due to …).
J JCL check.
D Definition.
S Schedule.
R Recovery.
T Repetition.
E Empty JCL.
C Condition.
M Multiple suffix.
K To be deactivated.

Predefined Symbols

For a list of predefined symbols, see Predefined Symbols in the section Symbol Table and Symbol Maintenance.

Common Considerations for User Exits

All user exits must return the field P-RC (return code). 0 (zero) means OK.

The field P-RT (return text) can be used optionally to pass back some specific information. Entire Operations writes this text into the log and displays it on the Active Jobs screen, if supplied.

All other parameters pass environment information to the user exit. Some parameters and AIV variables are not always required; see the relevant field descriptions for details.

Decimal Character (DC) Setting

The parameter data area NOPXPL-A contains numbers with decimal characters. The default setting for decimal character in the delivered source of NOPXPL-A is a period (.). If you want to catalog your user exits and Natural programs with another decimal character (e.g. comma, DC=,), you must also modify NOPXPL-A:

  • Make sure that the decimal character of your Natural session is set correctly. You can verify this with the system command GLOBALS (described in the Natural System Commands documentation).

  • Use the Natural Editor to edit NOPXPL-A.

  • Change the decimal character to your current DC parameter setting in the numeric fields, which contain a decimal character. Stow NOPXPL-A.

You will now be able to use NOPXPL-A with your own decimal character.

User Exit Coding Restrictions

  1. User exits must reside in a Natural library on the FUSER system file but may not reside in the Entire Operations SYSEOR system library.

    Sub-objects invoked by user exits (subprograms, etc.) and global user exits (see the Administration documentation) and must reside in the SYSEORU system library.

  2. ON ERROR routines are allowed in Entire Operations user exits, with the following restriction: The ON ERROR block must not be left by any ESCAPE ROUTINE, ESCAPE MODULE, TERMINATE or similar statement. The purpose of this restriction is that the common Entire Operations Monitor (or Entire Operations online) error transaction gets control after the execution of the user-defined ON ERROR block. The common Entire Operations error transaction performs some common error handling, logging, notifications etc.

  3. No programs with their own GDA (global data area) may be invoked.

  4. The names of user exits must not begin with the letter V, particularly if they are to be stored in the library SYSEOR, because the prefix V is reserved for the internal Entire Operations exit directory.

  5. The following Natural statements must not be coded in any user exit invoked by Entire Operations:

    • END TRANSACTION

      The transaction logic is handled by the Entire Operations Monitor itself.

    • BACKOUT TRANSACTION

    • STOP

    • TERMINATE

    • FETCH without RETURN (FETCH RETURN is allowed)

  6. Entire System Server node logons and logoffs should be avoided. This applies for mainframe nodes (view NATPROC-LOGON), UNIX nodes, and Windows nodes. If any logons and/or logoffs to Entire System Server nodes were made in a user exit, the exit must invoke the Entire System Server node invalidation API NOPUNI1N prior to termination. This forces subsequent new logons to these nodes.

  7. Do not code any screen and map input/output in user exits. An exception is the symbol prompting user exit in online usage mode. See also Specifying User Exits for Symbol Modification in the section Symbol Table and Symbol Maintenance.

  8. In general, the execution of all kinds of code, which can disturb the Entire Operations Monitor execution, is forbidden in user exits (exits). If in doubt, contact Software AG technical support.

Notes:

  1. If you want to use the values of the special parameters in Macro JCL, you must first read them with the special statement #GET-SYMBOL (described in the section System Overview).
  2. See also User Exits for Validation Checks of Symbol Values. For foreground usage, this exit may use maps (with some restrictions).

Generation of Dynamic JCL and SYSOUT File Names (BS2000 only)

For MAC-type jobs, you can generate dynamic JCL: see Dynamic JCL Generation (JCL Location MAC) in the section Job Maintenance.

In a BS2000 environment, you can generate file names for SYSOUT: see NOPFB2-N: Generate SYSOUT File Names for BS2000 in the section API Routines.

User Exits for Resource Master Determination

For each resource master, you can define a resource amount determination exit: see Using a Resource Master Determination Exit in the Administration documentation.

User Exits for Setting Input Conditions

Before Entire Operations can submit a job, all its input conditions must be fulfilled.

If a user exit is defined for a condition, Entire Operations invokes the defined exit (of the type ICO) each time it checks the condition status. See Return Code Settings for an Input Condition User Exit for the meaning of the return codes.

Otherwise, the condition checking will be continued.

You can set a return text in the P-RT parameter additionally.

User Exits for End-of-Job Checking and Actions

You can define user exits as part of End-of-Job checking. Entire Operations bases its End-of-Job checking on the occurrence of defined events during job execution. You can define a user exit as an event check. Entire Operations automatically executes the user exit when the job terminates.

Typically, such a user exit routine can check the result of a job, for example. The user exit returns a code which determines the event status. A return code zero means Check OK, any other return code means Check not OK. Condition codes returned by user exits can determine End-of-Job status.

End-of-Job action user exits can be used to perform any actions after job termination.

End-of-Job checking and action user exits are supplied with both the job number and the name of the SYSOUT file in which Entire Operations collected the job SYSOUT (BS2000 only).

For End-of-Job user exits, the common exit parameter list NOPXPL-A must be used. The parameter P-CALL-PLACE contains EJC for End-of-Job checking user exits or EJA for End-of-Job action user exits.

Related Topic:

This section covers the following topics:

Example

An End-of-Job checking user exit is shown in the example below.

This user exit routine adds up the contents of a numeric field in the SYSOUT and compares it with a given value. If the sum of the contents equals the sum of the given value, the event is treated as ok, otherwise as not ok. 

DEFINE DATA PARAMETER USING NOPXPL-A
LOCAL
1 READ-SPOOL VIEW OF READ-SPOOL      /* AN ENTIRE SYSTEM SERVER VIEW
  2 RECORD
  2 REDEFINE RECORD
    3 RECORD-HEADER    (A05)
*
1 #NF              (I02) CONST <10>   /* MAX. NUMBER FOR SEPARATION
1 #SUM             (N08) INIT  <0>
1 #SUM-EXPECTED    (N08) CONST <2000>
1 #FIELD           (A10/1:#NF)
1 #USERID          (A08)
1 #DBENV           (A10)
1 #NETWORK-VERSION (A10)
 
1 #LOG-STATUS      (N04)
1 #LOG-MESSAGE     (A60)
1 #LOG-TARGET      (A03) CONST <’NOP’>     
1 #USE-NAT-MSG-CACHE (L) CONST <FALSE>
END-DEFINE
* -------------------------------------------------
* This EOJ User Exit will read the Job SYSOUT (data set 2)
* and will summarize a defined field.
* If the sum is equal to a given value, this routine returns
* an 'OK' (P-RC = 0), otherwise 'NOT OK'.
*
* A log record will be written to document the result.
*
RESET #SUM
RS. FIND READ-SPOOL
    WITH NODE = P-EXECUTION-NODE AND JOB-NUMBER = P-JOB-ID
    AND TYPE = 'SO' AND DATA-SET = 2 AND RECORD-NUMBER >= 1
  ACCEPT IF RS.RECORD-HEADER = 'REC01'     /* interesting only
  SEPARATE RS.RECORD LEFT JUSTIFIED INTO #FIELD(*)
  ADD VAL(#FIELD(3)) TO #SUM
END-FIND
*
IF #SUM = #SUM-EXPECTED
  RESET P-RC
  MOVE 'Sum check is ok' TO #LOG-MESSAGE
ELSE
  MOVE 1 TO P-RC
  COMPRESS 'Sum:' #SUM 'Expected:' #SUM-EXPECTED INTO #LOG-MESSAGE
END-IF
#USERID := *USER
MOVE 9999 TO #LOG-STATUS
CALLNAT 'NOPULW93N'          /* WRITE LOG RECORD
  #LOG-STATUS #LOG-MESSAGE #DBENV 
  P-OWNER P-NETWORK #NETWORK-VERSION P-RUN P-JOB 
  P-JOB-ID #LOG-TARGET # USE-NAT-MSG-CACHE
END

User Exits for Symbol Functions

You can perform user-specific symbol functions via a user exit. For the symbol functions available, see Functions for Symbol Replacement in the section Symbol Table and Symbol Maintenance.

This section covers the following topics:

Symbol Function Syntax

Syntax for symbol functions:

§!|?function[parm,...]

Symbol Function Coding Rules

  • As for other user exits (exits), the user exit coding restrictions must be adhered to.

  • For a function to be recognized, an exclamation mark (!) or a question mark (?) must always follow the escape character. In BS2000 the exclamation mark (!) is represented by an ö character.

  • The parameter list is optional and is enclosed in square brackets ([ ]). No spaces are allowed between function name and parameter list.

  • Parameters must be separated by commas.

  • The total length of the function call may not be longer than 20.

  • The symbol functions must be located in the SYSEORU library.

  • The Entire Operations Monitor performs logging of symbol replacements. Additional logging may also be performed.

  • After successful replacement, the symbol value is written to the active symbol table of the job. The symbol function is not called for subsequent replacements. Instead, the value is read from the active table.

The names of the symbol function exits begin with SX. Since the length of the names of Natural objects is limited to 8 characters, the function name (the exclamation mark (!) not counted) can have a maximum length of 6 characters.

Symbol Function Parameter List

The function !RANDOM is handled by the Natural subprogram SXRANDOM.

The symbol function exits are called with the parameter list NOPXPL-A, so the first line of the exit should be: 

DEFINE DATA PARAMETER USING NOPXPL-A

Meaning of the parameters in NOPXPL-A:

Parameter
P-CALL-PLACE 
P-RC 
P-RT 
P-OWNER 
P-NETWORK 
P-JOB 
P-RUN 
P-EXECUTION-NODE 
P-SYMBOL-TABLE 
P-SYMBOL 
P-SYMBOL-VALUE 

We strongly recommend that you only use the fields listed in the previous table. Using any other field from NOPXPL-A, can cause unpredictable results.

Notes:

  1. Caller supplied SFX (symbol function exit) for P-CALL-PLACE.

  2. Set P-RC to either of the following return codes:

    0 (Function ok.), or

    4531 (Symbol not found.)

  3. P-SYMBOL only transfers the function parameters (without brackets). The function names can be identified from the Natural variable *PROGRAM (described in the Natural System Variables documentation).

Example of a Symbol Function

User Exit Subprogram SXQS
* SYMBOL FUNCTION EXIT EXAMPLE
* SXQS<PARM1>
* CROSSFOOTING OF THE PARAMETER
* -------------------------------------------------------------
DEFINE DATA PARAMETER USING NOPXPL-A
LOCAL
1 #I   (I02)
1 #N   (I02)
1 #SUM (I02)
1 #A   (A01)
END-DEFINE
* -------------------------------------------------------------
RESET #SUM
F1. FOR #I = 1 TO 20
  #A := SUBSTR (P-SYMBOL,#I,1)
  IF #A IS (N1)
    #N := VAL(#A)
    ADD #N TO #SUM
  END-IF
END-FOR    /* F1.
P-SYMBOL-VALUE := #SUM
RESET P-RC P-RT
END
Master JCL
//SN000001 JOB ,SN,CLASS=K
//IEFBR14  EXEC PGM=IEFBR14
//*
//* +!D<AQ+1>
//* §!D<AQ+1>
//*
//* +!QS<4711>
//* §!QS<4711>
//*
//* +!QS<+*DATE>                 NESTED SYMBOLS
//* +!QS<§*DATE>                 NESTED SYMBOLS
//* §!QS<§*DATE>                 NESTED SYMBOLS
//*
//* +!QS<+!D<AM-1>>              NESTED FUNCTIONS
//* +!QS<§!D<AM-1>>              NESTED FUNCTIONS
//* §!QS<§!D<AM-1>>              NESTED FUNCTIONS
//*
Active JCL
//SN000001 JOB ,SN,CLASS=K
//IEFBR14  EXEC PGM=IEFBR14
//*
//* +!D<AQ+1>
//* 20080101
//*
//* +!QS<4711>
//* 13
//*
//* +!QS<+*DATE>                 NESTED SYMBOLS
//* +!QS<29/10/08>               NESTED SYMBOLS
//* 18                           NESTED SYMBOLS
//*
//* +!QS<+!D<AM-1>>              NESTED FUNCTIONS
//* +!QS<20080131>               NESTED FUNCTIONS
//* 30                           NESTED FUNCTIONS
//*
Active Symbol Table
Symbol            F A Value                        modified by
!D<AM-1>          A E 20080131                     EORMON   11.01.08 17:25
!D<AQ+1>          A E 20080101                     EORMON   11.01.08 17:25
!QS<11/01/08>     A E 20                           EORMON   11.01.08 17:25
!QS<20080131>     A E 15                           EORMON   11.01.08 17:25
!QS<4711>         A E 13                           EORMON   11.01.08 17:25
X                 A E x                            SN       10.11.08 13:13

User Exits for Validation Checks of Symbol Values

You can write a user exit routine (front-end user exit) that defines your own prompting screens and validation (plausibility) checks for symbol prompting during job network activation. For more information on symbol prompting, see Symbol Prompting during Network or Job Activation in the section Symbol Table and Symbol Maintenance.

The user exit is called by the Entire Operations Monitor after the creation of the active symbol tables, but before the JCL loading. If the user exit is missing or receives a run time error, network activation is stopped and a message is sent to the mailbox, which is assigned to the network as the message recipient. If no mailbox is assigned, the message is sent to the SYSDBA mailbox. For details, see the section Mailboxes.

When writing the user exit routine, use the mandatory parameter data area NOPXPL-A and the parameter list NOPSYP3A.

NOPXPL-A contains the owner, symbol table, symbol name, etc. It can therefore be used for different symbols.

NOPSYP3A contains all needed environment parameters. The list of symbol tables used for this network activation will be passed to the Entire Operations API routine.

The symbols must be read and updated by the Entire Operations API routine NOPUSYxN which allows sequential reading in the active symbol table. x denotes a sequential version number of 1 through 6, where 6 is the most recent version of the API.

The parameters P-RC (return code) and P-RT (return text) are examined by the caller after execution of the user exit. If P-RC is zero, the symbol is accepted as OK. Otherwise, the symbol is not accepted.

If the text from P-RT is not blank, it will be displayed to the user with message code EOR1855. If P-RT is not zero and blank, a standard error message is displayed.

As in other user exits, Adabas, Entire System Server and Natural system variables can provide a lot of flexibility to symbol checking.

This section covers the following topic:

Parameter List NOPSYP3A

*    NOPSYP3A
*    Entire Operations
*    Exit parameter list
*    for symbol prompting
*
*    27.09.12 N1399    SN541                       /* successor of NOPSYP2A
*    11.03.13 N1574    SN541                       /* N1574
*    20.08.13 N1649    SN541                       /* P-USED-SYMTAB-34
*    --------------------------------
   1 P-CALL-PLACE                     A          3
*      'SYP'  symbol prompting online
*      'SYM'  symbol modif.    batch
   1 P-RC                             N          4 /* in/out  return code
*      0  out: ok
*      1  out: no symbols prompted                        
*      2  out: activation cancelled                         
*      4  out: end (no modification)                       
*
*      3  in:  rewrite modified                                              
*              symbols to symbol                                             
*              master too                                                   
   1 P-RT                             A         70 /* out  return text
*
   1 P-OWNER                          A         10 /* in
   1 P-NETWORK                        A         10 /* in
   1 P-NETWORK-VERSION                A         10 /* in  312641 add
   1 P-RUN                            I          4 /* in  312641 fmt, order
   1 P-JOB                            A         10 /* in  312641 order
   1 P-ACTIVATION-TIME                T            /* in
   1 P-EARLIEST-START                 T            /* in
   1 P-NETWORK-SYMTAB                 A         10 /* in                     
R  1 P-NETWORK-SYMTAB                              /* REDEF. BEGIN : P-NETWORK-SYMT
   2 P-NETWORK-SYMBOL-TABLE           A         10 /* 312641.3
   1 P-NETWORK-SYMTAB-VERSION         A         10 /* 312641 add             
   1 P-USED-SYMTAB-34                 A         34 (1:V) /* N1649
*      -- Use LDA NOPSYT1L for the                 N1649
*      -- layout / redefinition of                 N1649
*      -- the table elements.                      N1649
   1 P-DATE-FORMAT                    A          1 /* in
*      'A' American
*      'E' European
*      'G' German
*      'I' International
*
*    -- end of parameter data area --

This section covers the following topics:

Supplied by the Caller on Input

P-RC Meaning
3 Rewrite modified symbols to master symbol table.

Return Codes to Be Set by the Symbol Modification User Exit

P-RC Meaning
0 OK, modifications were done.
1 OK, no symbols prompted or modified.
2 Activation cancelled.
4 End; no modification.

Symbol Modification without Prompting

Code the user exit analogous to the symbol prompt user exit and use the provided parameter list NOPSYP3A, in conjunction with the local data area NOPSYT1L. Do not code any screen I/O if you do not use foreground prompting.

This section covers the following topics:

Data Area NOPSYT1L

The layout of the field P-USED-SYMTAB-34 is specified in the data area NOPSYT1L. 

*    NOPSYT1L
*    'Symbol tables used'
*    table entry
*
*    Maintenance
*    13.08.13  N1649     SN541                     created
*    07.10.13  N1649.A   SN541                     'origin object type' val.
*    --------------------------------              -------------------------
*    -- values for SYTU-SYMTAB-STATUS
*
   1 SYTU-SYMTAB-STATUS-EV-DUP        A          2 CONST<'ED'>
*    -- effective symbol table
*    -- version is a duplicate --
*    -- entry should be skipped
*    -- during prompting
   1 SYTU-SYMTAB-STATUS-UNDEF         A          2 CONST<'00'>
*    -- undefined
   1 SYTU-SYMTAB-STATUS-NPN           A          2 CONST<'10'>
*    -- no prompting necessary
   1 SYTU-SYMTAB-STATUS-PN            A          2 CONST<'20'>
*    -- prompting necessary
   1 SYTU-SYMTAB-STATUS-PD            A          2 CONST<'30'>
*    -- prompting done
*
*    --------------------------------
*
*    -- values for
*    -- SYTU-ORIGIN-OBJECT-TYPE
*
   1 SYTU-ORIGIN-OBJECT-NV            A          2 CONST<'NV'>
*    -- network version definition
   1 SYTU-ORIGIN-OBJECT-JM            A          2 CONST<'JM'>
*    -- job (master) definition
   1 SYTU-ORIGIN-OBJECT-IM            A          2 CONST<'IM'>
*    -- input cond. (mult. suffix)
   1 SYTU-ORIGIN-OBJECT-IS            A          2 CONST<'IS'>
*    -- input cond. (dep. on symbol)
   1 SYTU-ORIGIN-OBJECT-AS            A          2 CONST<'AS'>
*    -- EOJ action (symbol setting)
*
*    --------------------------------
*
   1 SYTU-ENTRY-34                    A         34
R  1 SYTU-ENTRY-34                                 /* REDEF. BEGIN : SYTU-ENTRY-34
   2 SYTU-SYMTAB-STATUS               A          2
*    -- values see above
   2 SYTU-ORIGIN-OBJECT-TYPE          A          2
*    -- values see above                           /* N1649.A
*    ...
   2 SYTU-SYMTAB                      A         10
   2 SYTU-SYMTAB-VERSION-DEFINED      A         10
   2 SYTU-SYMTAB-VERSION-EFFECTIVE    A         10
*      blank:
*        not determined yet
*      KVE-TEXT-UNNAMED = '(none)'
*        determined and blank
*      other:
*        determined and non-blank
*
*    -- end of area --

Reserved Symbols for UNIX and Windows Environment Variables

A set of reserved symbols can be used to set environment variables in the JCL frame script (UNIX) or in the JCL frame BAT file (Windows) for jobs submitted on UNIX or Windows nodes.

Prerequisite: The symbols must be defined in the Natural text object NOPVS001 supplied in the SYSEORU system library.

Special Usage Considerations

Consider the following when using reserved symbols as environment variables:

  • For valid format/length specifications of the reserved symbols, see Table of Predefined Symbols in the section Symbol Table and Symbol Maintenance.

  • Dash signs (-) within a symbol name are converted to underscore signs (_) as indicated in the following example.

  • For UNIX:

    Environment variables are exported. Therefore, they are available in all subscripts and executables called from the frame script.

  • For Windows:

    Environment variables are set in the frame BAT file. They are available in the user BAT or PS1 file.

Example of Using Reserved Symbols for Environment Variables

The following is an example of using reserved symbols to set environment variables.

Variables defined in the NOPVS001 text object: 

P-SYSF1 
P-OWNER 
P-NETWORK 
P-NETWORK-VERSION 
P-RUN 
P-RUN5 
P-JOB 
P-REPEAT
P-ESC-ACT
P-ESC-SUB 
P-SYMTAB 
P-SYMTAB-VERSION 
P-JCL-NODE 
P-EXEC-NODE 
P-SUL 
P-SUG 
P-NADIR 
P-SYSOUT 
P-DATE 
P-C-OWNER 
P-C-NETWORK 
P-C-NETWORK-VERSION 
P-C-RUN 
P-C-RUN5 
P-C-JOB

Excerpt of the generated JCL frame script for UNIX: 

... 
# setting of variables defined in SYSEORU/NOPVS001 
P_SYSF1="0000900017" ; export P_SYSF1 
P_OWNER="NOPALL" ; export P_OWNER 
P_NETWORK="N2838S02" ; export P_NETWORK 
P_NETWORK_VERSION="" ; export P_NETWORK_VERSION 
P_RUN="6" ; export P_RUN 
P_RUN5="00006" ; export P_RUN5 
P_JOB="J101" ; export P_JOB 
P_REPEAT="0" ; export P_REPEAT
P_ESC_ACT="@" ; export P-ESC-ACT
P_ESC_SUB="^" ; export P-ESC-SUB 
P_SYMTAB="" ; export P_SYMTAB 
P_SYMTAB_VERSION="" ; export P_SYMTAB_VERSION 
P_JCL_NODE="517" ; export P_JCL_NODE 
P_EXEC_NODE="517" ; export P_EXEC_NODE 
P_SUL="sag" ; export P_SUL 
P_SUG="" ; export P_SUG 
P_NADIR="$EOR_WORK/sag/0000900017/NOPALL/N2838S02/0000/0006" 
export P_NADIR 
P_SYSOUT="$EOR_WORK/sag/0000900017/NOPALL/N2838S02/0000/0006/J101.00000000.sysout.txt" 
export P_SYSOUT 
P_DATE="20161219" ; export P_DATE 
P_C_OWNER="NOPALL" ; export P_C_OWNER 
P_C_NETWORK="N2838M02" ; export P_C_NETWORK 
P_C_NETWORK_VERSION="" ; export P_C_NETWORK_VERSION 
P_C_RUN="7" ; export P_C_RUN 
P_C_RUN5="00007" ; export P_C_RUN5 
P_C_JOB="S002" ; export P_C_JOB 
# setting of variables - end
...

Excerpt of the generated JCL frame BAT file for Windows: 

...
rem - setting of variables defined in SYSEORU/NOPVS001 
set P_SYSF1=0000900018 
set P_OWNER=SN 
set P_NETWORK=W401-2 
set P_NETWORK_VERSION= 
set P_RUN=2382 
set P_RUN5=02382 
set P_JOB=J001 
set P_REPEAT=0
set P_ESC_ACT=@
set P_ESC_SUB=$ 
set P_SYMTAB=W401-2 
set P_SYMTAB_VERSION= 
set P_JCL_NODE=401 
set P_EXEC_NODE=401 
set P_SUL=sn 
set P_SGL=eur 
set P_NADIR=c:\SAG\eor_work\sn\0000900018\SN\W401-2\0000\2382 
set P_SYSOUT=c:\SAG\eor_work\sn\0000900018\SN\W401-2\0000\2382\J001.00000000.sysout.txt 
set P_DATE=20180503 
set P_C_OWNER= 
set P_C_NETWORK= 
set P_C_NETWORK_VERSION= 
set P_C_RUN=0 
set P_C_RUN5=00000 
set P_C_JOB= 
rem - setting of variables - end
...