User Exits

#### Search Results

Search

# 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

- Global User Exits

- Front-end User Exits

- Common User Exit Parameter Data Area NOPXPL-A

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

- User Exits for Resource Master Determination

- User Exits for Setting Input Conditions

- User Exits for End-of-Job Checking and Actions

- User Exits for Symbol Functions

- User Exits for Validation Checks of Symbol Values

- Reserved Symbols for UNIX and Windows Environment Variables

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

- Global Exit for Version Names

- Global JCL Activation Exit

- Global Symbol Modification Exit

- Global Symbol Not Found Exit

- Global Message Sending Exit

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

- Symbol prompting for a network or job activation. For more information, see Symbol Prompting during Network or Job Activation in the section Symbol Table and Symbol Maintenance.

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

- Parameters Used for Different Call Places

- Additional Independent (AIV) Variables

- Predefined Symbols

- Common Considerations for User Exits

- Decimal Character (DC) Setting

- User Exit Coding Restrictions

- User Exit Execution

### 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
P-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 | For returned symbol values longer than 54 bytes (A54), the AIV variable `+P-SYMBOL-VALUE-250 (A250)` must be used.
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-SYMBOL-VALUE-250 | A250 | n/a | n/a | n/a | n/a | n/a | n/a | n/a | n/a | out | 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-SYMBOL-VALUE-250 | A Symbol Function result value must be returned in this field if it exceeds the size of P-SYMBOL-VALUE (A54). The effective maximum size for single and multiple symbols is 120 (A120).
+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).

### User Exit Execution

If a user exit fails due to a Natural runtime error (e. g. a NAT0082 error if an invoked module does not exist), the user exit’s Natural object will be deleted by the Entire Operations (NOP) Monitor. This prevents a Monitor failure due to the repeated execution attempt of an erroneous user exit. The event will be logged, and the active job’s status text will be set accordingly. In this case, the user exit’s source must be corrected, and the user exit must be stowed (cataloged) again.

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

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

This section covers the following topics:

- Example

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

- Symbol Function Coding Rules

- Symbol Function Parameter List

- Symbol Function Usage and Execution

- Example of a Symbol Function

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

Example:

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

### Symbol Function Parameter List

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

> 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

>      `4513` (EOR4513 - Symbol :1: 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).

### Symbol Function Usage and Execution

- Symbol functions can also be used for input conditions that depend on a symbol value. Please keep in mind the overhead of the repeated execution until the input condition is satisfied.

- Depending on the escape character being used, symbol functions are executed at JCL loading time, or at job submission time. If a symbol function fails due to a runtime error, or if its Natural object is not available, the affected active job will be set to a permanent error state.

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

- Symbol Modification without Prompting

### 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
- Return Codes to Be Set by the Symbol Modification User Exit

#### Supplied by the Caller on Input

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

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

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

- Example of Using Reserved Symbols for Environment Variables

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

### On this page

- What User Exits Can Do
- Global User Exits
- Front-end User Exits
- Common User Exit Parameter Data Area NOPXPL-A
- Generation of Dynamic JCL and SYSOUT File Names (BS2000 only)
- User Exits for Resource Master Determination
- User Exits for Setting Input Conditions
- User Exits for End-of-Job Checking and Actions
- User Exits for Symbol Functions
- User Exits for Validation Checks of Symbol Values
- Reserved Symbols for UNIX and Windows Environment Variables