User Exits

#### Search Results

Search

# User Exits

Natural ISPF provides a number of user exits written in Natural. The sources are delivered in the Exit Library. Before modifying any of these programs, you must copy them to one of your Natural libraries, as any subsequent `INPL` from the installation medium overwrites the Exit Library. Useful examples for user exits can be found in the Example Library.

After successful modification of an exit, you must copy the module to library `SYSLIB`, and activate the exit as described in the section System Configuration.

The various types of provided exits are described in the following subsections.

This document covers the following topics:

- Object Exits

- Examples of Object Exits

- CA Panvalet Save Exit ISPT-SVU

- Logon Exit ISP-LONU

- Logoff Exit ISP-LOFU

- Print User Exit ISP-PRTU

- Import/Export Exits

- Color Settings Exit ISP-ECLU

- Resume Exit ISP-RESU

- Suspend Exit ISP-SUSU

- Session Exit ISP--S-U

- Rename Function Exit ISP-RN-U

- User Library Exit ISP-PRFU

- User Group Exit ISP-UGRU

- Node Exit ISP-NODU

- HSM - Hierarchical Storage Manager Exit ISP-HSMU

- Editor Profile Exit ISP-ED-U

- Incore Database Defaults Exit IDB-USRN

- Container File Access Exit IDBC---U

## Object Exits

A user exit is provided for each Natural ISPF object type (for example, PDS members, Natural objects, views, jobs, etc.).

Whenever a user issues a specified function command for a certain object, the corresponding user exit is called before the command is executed. A user exit can check whether the function, object type and parameters are valid for the user and can react in any of the following ways:

- Deny access to the function and return an error message;

- Return a warning message;

- Modify invalid function parameters;

- Allow access to the function.

### Data Parameters

The data parameters you can define for object exits are the same for each object type:

Parameter | Format | Type | Meaning (Member: TAB-FUNC)
--- | --- | --- | ---
`#FUNCTION` | (A2) | `I` | Contains a 2-character abbreviation of the function to be executed. Possible options:
`--` | `ENTRY` | `FR` | `FORMAT`
`-2` | Target of `COPY` | `HL` | `HOLD`
`AL` | `ALLOCATE` | `IN` | `INFORMATION`
`BR` | `BROWSE` | `LS` | `LIST`
`CC` | Condition codes | `OT` | `OUTPUT`
`CH` | `CHANGE` | `PG` | `PURGE`
`CM` | `COMPRESS` | `PL` | `PLAY`
`CP` | `COPY source` | `PR` | `PRINT`
`CR` | `COMPARE` | `RL` | `RELEASE`
`CT` | `CATALOG` | `RN` | `RENAME`
`DF` | `DEFINITION` | `RU` | `RUN`
`DI` | `DIFFERENCE` | `SB` | `SUBMIT`
`DL` | `DELETE` | `ST` | `STATUS`
`DO` | `DOWNLOAD` | `UN` | `UNCATALOG`
`DS` | `DESCRIPTION` | `UP` | `UPLOAD`
`ED` | `EDIT` | `XE` | `EXECUTE`
`ET` | `EXTENTS` | `XT` | `EXTERNS`
`EX` | `EXPORT` | `ZP` | `ZAPS`
`FL` | `FOLLOW` |  |
Note Not all functions are valid for all object types. See the Natural ISPF User's Guide.
`#SES-DATA` | (A253) | `I/O` | Contains object-specific parameters; you must redefine these according to the object type. A parameter data area is delivered in source form for this redefinition.
`#ERROR-CODE` | (N3) | `O` | Function will be denied if an error code greater than 0 (zero) is received.
`#ERROR-NR` | (N4) | `O` | Error number for `SYSERR`, the errors greater than 9000 in the System Profile Library are not used by the product and you can therefore define them (currently, 9001 and 9002 are used for example exit `ISPN---U`, but these can be overwritten). If this field is set and `ERROR-CODE` is zero, the message will be displayed as a warning, unless more important messages (like `FOLLOW`) have to be displayed.
`#ERROR-PARM` | (A75) | `O` | Parameters for the error message can be passed to the Natural ISPF error handler, multiple parameters must be separated by a semicolon (;). They replace `:1:`, `:2:`, `:3:`, etc. parameters in the error text.
`#OPTIONS` | (A20) | `I/O` | Global data which can be shared by all user exits and by all Open NSPF subprograms. Can also be used to transfer control to another object (also an Open NSPF object). This is useful if a user-written routine handles functions for existing objects. The syntax is:
    'OBJECT = xx'
where: xx is the object code as defined in the `CONTROLS` table. The field is cleared by Natural ISPF when transferring control to the new object. Example:
    MOVE 'OBJECT = -7' TO #OPTIONS

### Table of Exits and Object Abbreviations

This table lists all object-related user exits provided, as well as the data areas used by them, and an abbreviation of the object valid for the `OBJECT` parameter.

The data areas are also delivered in source form, the fields used have meaningful names and are documented in the data area source itself.

Exit Name | Data Area | Object (Member: TAB-EXIT) | Object Abbreviation
--- | --- | --- | ---
`ISIC---U` | `ISIC---L` | Incore container files | `CTN`
`ISPA---U` | `ISPA---L` | z/OS active jobs | `A`
`ISPB---U` | `ISPB---L` | Buffer Pool files | `BPF`
`ISPC---U` | `ISPC---L` | Console | `CON`
`ISPD---U` | `ISPD---L` | z/OS data sets | `D`
`ISPE---U` | `ISPE---L` | Recovery files | `R`
`ISPF---U` | `ISPN---L` | ISPF configuration | `F`
`ISPG---U` | `ISPJ---L` | Syslog | `LOG`
`ISPJ---U` | `ISPJ---L` | z/OS Jobs | `J`
`ISPK---U` | `ISPP---L` | CSECT | `CST`
`ISPL---U` | `ISPL---L` | CA Librarian | `LIB`
`ISPM---U` | `ISPM---L` | ISPF Menus | `MNU`
`ISPN---U` | `ISPN---L` | Natural | `N`
`ISPO---U` | `ISPO---L` | Output (workpool entries) | `O`
`ISPP---U` | `ISPP---L` | PDS members | `P`
`ISPR---U` | `ISPR---L` | PDS member versions | `PV`
`ISPS---U` | `ISPJ---L` | z/OS SYSOUT files | `S`
`ISPT---U` | `ISPT---L` | CA Panvalet | `PAN`
`ISPU---U` | `ISPU---L` | ISPF users | `U`
`ISPV---U` | `ISPV---L` | Views | `V`
`ISPX---U` | `ISPN---L` | Macro | `MAC`
`ISPY---U` | `ISPY---L` | Natural errors | `E`
`ISPZ---U` | `ISPP---L` | z/OS volumes | `VOL`
`ISP1---U` | `ISP1---L` | Member versions | `MV`
`ISP2---U` | `ISP2---L` | Natural versions | `NV`
`ISP4---U` | `ISPE---L` | Buffer Pool Recovery files | `BPR`
`ISP5---U` | `ISPL---L` | CA Librarian versions | `LV`

## Examples of Object Exits

### Example 1: Exit for Natural

The following program is invoked when a user issues an `EDIT` command for a Natural object. It restricts write access to objects in Natural library `NSPFWORK` to users `JWO`, `GW1` and `MBE`. The program warns these specified users to be careful, and unauthorized users are presented with an error message.

    * JOB USER EXIT
      *
      * List JOB queue without selection criteria is not allowed.
      * exit modifies the selection criteria and puts first 3 characters of
      * user-id into it.
      *
      DEFINE DATA PARAMETER
      1 #FUNCTION(A2)
      PARAMETER USING ISPJ---L
      PARAMETER
      1 #ERROR-CODE(N3)
      1 #ERROR-NR  (N4)
      1 #ERROR-PARM(A75)
      1 #OPTIONS   (A20)
      LOCAL
      1 #A3     (A3)
      END-DEFINE
      *
      DECIDE ON FIRST VALUE OF #FUNCTION
        VALUE 'LS'
          IF #JOBNAME   = ' ' OR = '*'
              MOVE *USER TO #A3
              COMPRESS #A3 '*' INTO #JOBNAME LEAVING NO
          END-IF
        NONE IGNORE
      END-DECIDE
      END

### Example 2: Exit for JOBS

This exit is invoked when a user issues the `LIST` command on object type `JOBS`. It does not allow a list request without selection criteria and writes the first three characters of the user ID to the job name parameter:

    * JOB USER EXIT
      *
      * List JOB queue without selection criteria is not allowed.
      * exit modifies the selection criteria and puts first 3 characters of
      * user-id into it.
      *
      DEFINE DATA PARAMETER
      1 #FUNCTION(A2)
      PARAMETER USING ISPJ---L
      PARAMETER
      1 #ERROR-CODE(N3)
      1 #ERROR-NR  (N4)
      1 #ERROR-PARM(A75)
      1 #OPTIONS   (A20)
      LOCAL
      1 #A3     (A3)
      END-DEFINE
      *
      DECIDE ON FIRST VALUE OF #FUNCTION
        VALUE 'LS'
          IF #JOBNAME   = ' ' OR = '*'
              MOVE *USER TO #A3
              COMPRESS #A3 '*' INTO #JOBNAME LEAVING NO
          END-IF
        NONE IGNORE
      END-DECIDE
      END

## CA Panvalet Save Exit ISPT-SVU

This exit is called after each successful save of a CA Panvalet member. The exit must be activated by the definitions in the `PANDEF` member (see the section System Configuration).

An example program is delivered in the User Exit Library. It illustrates how to access the output from `PAM#1` and displays the output on the screen.

The following table lists all definable parameters:

Parameter | Format | Type | Meaning
--- | --- | --- | ---
`P1` | (A250) | `I/O` | Exit control block has to be redefined with the following definitions.
`FILLER-1` | (A12) |  |
`EX-RNUM` | (B4) | `I` | Number of records (saved).
`EX-RLEN` | (B2) | `I` | Record length.
`FILLER-2` | (A2) |  |
`EX-ECODE` | (B2) | `O` | Error code.
`FILLER-3` | (A10) |  |
`EX-ETEXT` | (A64) | `O` | Error text.
`FILLER-4` | (A4) |  |
`EX-DSNAME` | (A44) | `I` | CA Panvalet data set name.
`FILLER-5` | (A10) |  |
`EX-MEMBER` | (A10) | `I` | CA Panvalet member name.
`EX-VOLSER` | (A6) | `I` | Volume serial number.
`EX-PASSWD` | (A8) | `I` | Password.
`FILLER-6` | (A1) |  |
`EX-NODE` | (B1) | `I` | Entire System Server node.

## Logon Exit ISP-LONU

This exit is called when the user logs on to Natural ISPF. It is executed after standard logon handling, and can be used to issue a command to Natural ISPF directly at logon. Any valid Natural ISPF command is possible; for example, this could be a `PLAY` command.

In addition to the standard data parameters described above, you must define the following data in the exit:

Parameter | Format | Type | Meaning
--- | --- | --- | ---
`#USER` | (A8) | `I` | User ID of the user for whom the exit is to be executed.
`#COMMAND` | (A50) | `I/O` | Natural ISPF command sequence to be executed at logon.

## Logoff Exit ISP-LOFU

This exit is called when the user logs off from Natural ISPF. It is executed after standard logoff handling, and can be used to issue a command to Natural directly at logoff. Any valid Natural command is possible.

In addition to the standard data parameters described above, you must define the following data in the exit:

Parameter | Format | Type | Meaning
--- | --- | --- | ---
`#USER` | (A8) | `I` | User ID of the user for whom the exit is to be executed.
`#COMMAND` | (A50) | `I/O` | Natural ISPF command sequence to be executed at logon.

### Example

The following example logoff exit issues the `FIN` (`FINISH`) command to Natural after user `JWO` logs off from Natural ISPF: the user is returned to the TP environment directly, bypassing Natural.

      * LOGOFF USER EXIT
      *
      * SKIP NATURAL AT LOGOFF
      * DEFINE DATA PARAMETER
      1 #USER(A8)
      1 #COMMAND(A50)
      1 #ERROR-CODE(N3)
      1 #ERROR-NR (N4)
      1 #OPTIONS(A20)
      END-DEFINE
      *
      IF #USER EQ 'JWO'
        MOVE 'FIN' TO #COMMAND
      END-IF
      *
      END

## Print User Exit ISP-PRTU

When this exit is activated in the Natural ISPF configuration member by entering (`PRINT`, it is called twice whenever a user invokes the Natural ISPF print function.

The exit is invoked before the printer is opened, with `FC=O`. The following actions can be performed:

- `DEFINE PRINTER` (for Printer 2): A printer can be opened with the `PROFILE` parameter to activate specific profiles; `#FC` must be `RESET` in this case, no define printer will be executed by the caller;

- Abort print function by returning an error-code, error number and parameters.

- Modify printer and number of lines per page;

- Return an escape sequence to be printed as first line of the printout;

- Define whether the escape sequence has to be printed on printer `CCONTROL`;

The exit is also invoked before the printer is closed, with `FC=C`. The following action can be performed:

- `DEFINE/CLOSE PRINTER` for Printer (2). `#FC` must be `RESET` in this case, no close printer will be executed by the caller;

- Return an escape sequence to be printed as last line of the printout;

- Define whether the escape sequence has to be printed on Printer `CCONTROL`.

The following is an example of a customized user print exit: `ISP-PRTU`, Lib.`NSPFEXAM`.

      * *********************  **    *************************************
      DEFINE DATA PARAMETER
      * ********************* **    *************************************
      1 #FC       (A1)     /* I/O   Function-Code: O=open,C=Close
                           /*       when reset to ' '
                           /*       no Open/Close will be done by caller
      1 #PRINTER  (A8)     /* I/O   Printer id
      1 #OBJECT   (A2)     /* I     Object type to be printed
      1 #SES-DATA (A200)   /* I     Session data for object
      1 #RECLEN   (N4)     /* I     Length of records to be printed
      1 #CCONTROL (N1)     /* O     CCONTROL available:
                           /*        0 = no
                           /*        1 = yes
                           /*        2 = yes and printer can handle MCC
                           /*            (machine code control chars) for future use
      1 #PROFILE  (A8)     /* O     Printer profile for future use
      1 #ESC-SEQ  (A80)    /* O     Esc-sequence to be printed:
                           /*       #FC='O' before the first line
                           /*       #FC='C' after  the last  line
      1 #NO-LINES (N3)     /* I/O   No of lines per page
      1 #REFRESH-SCREEN(L) /* O     True if screen has to be refreshed
                           /*       Must be set if this exit does any
                           /*       terminal I-O
      1 #ERROR-CODE  (N3)  /* O     AS USUAL
      1 #ERROR-NUMBER(N4)  /* O     AS USUAL
      1 #ERROR-PARM(A75)   /* O     AS USUAL
      1 #OPTIONS(A20)      /* I/O   FFU
      1 #WORK   (A20)      /* I/O   Internal work area
      LOCAL
      1 #START-SEQ
        2 #S-B (A17) INIT <' &%21,132;99,999&'>
        2 #S-P (A63) INIT <'!R! SPO L; FONT 23; SCPI 14; SLPI 9; EXIT;'>
      1 REDEFINE #START-SEQ
        2 #START (A80)
      1 #END-SEQ
        2 #E-B (A17) INIT <'&%21,80;99,999&'>
        2 #E-P (A63) INIT
          <' !R! SPO P; FONT 8; SCPI 12; SLPI 6; UNIT I; SLM 1; EXIT;'>
      1 REDEFINE #END-SEQ
        2 #END (A80)
      1 #LANDS (A1)
      END-DEFINE
      *
      DEFINE WINDOW WIND1 SIZE 04 * 30
        BASE 04/25
        CONTROL WINDOW
        FRAMED ON
      *
      *
      IF #PRINTER  = 'EDITOR' OR = 'WORKPOOL'
          OR #RECLEN LE 80
        ESCAPE ROUTINE
      END-IF
      *
      *
      * If the printer is called 'EXIT' then Open/Close is done
      * by this routine (and not by ISPF)
      *
      IF #PRINTER EQ 'EXIT'
        DECIDE ON FIRST VALUE OF #FC
          VALUE 'O'                        /* open call
            DEFINE PRINTER (2) OUTPUT 'MYPRINT'
            RESET #FC                      /* open done
          VALUE 'C'                        /* close call
            DEFINE PRINTER (2) OUTPUT 'MYPRINT' /* valid for nat21
            RESET #FC                      /* close done
          NONE IGNORE
        END-DECIDE
        ESCAPE ROUTINE
      END-IF
      *
      *
      * This example sets landscape mode on kyocera printer, if
      * the records to be printed contain more than 80 bytes.
      *
      IF #PRINTER EQ 'DAEPRT14' OR         /* kyocera printers
          #PRINTER EQ SCAN 'TEMP'
        DECIDE ON FIRST VALUE OF #FC
          VALUE 'O'                        /* open call
            SET WINDOW 'WIND1'
            INPUT 'Mark for Landscape' #LANDS(AD=MI)
            MOVE TRUE TO #REFRESH-SCREEN
            RESET #WORK
            MOVE #LANDS TO #WORK
            IF #LANDS NE ' '
            MOVE  #START TO #ESC-SEQ       /* set landscape mode
            CALLNAT 'ISP-C22N' #NAT22
            IF #NAT22                      /* if executing under NAT22
              MOVE 1 TO #CCONTROL          /* print on CCONTROL
            END-IF
            END-IF
          VALUE 'C'                        /* close call
            MOVE #WORK TO #LANDS
            IF #LANDS NE ' '
            MOVE  #END   TO #ESC-SEQ       /* set mode back
            END-IF
          NONE IGNORE
        END-DECIDE
      END-IF
      END

## Import/Export Exits

Natural ISPF provides exits that are required when you wish to change the default work file number for the `IMPORT/EXPORT` PC function. The default work file number is 7. These routines contain all `READ/WRITE` operations. You can adapt the source to enforce use of another work file.

After each source change, you must recompile the programs and copy them to the `SYSLIB` library. Note especially, that if you change one program, you must change them all accordingly.

The import/export exits are:

ISP-SEPU
ISP-SE2U
ISP-SE3U
ISP-SE4U
ISP-SIMU
ISP-UPBU
ISP-DLBU
ISP-SECU
ISP-SEWU

## Color Settings Exit ISP-ECLU

This exit is always called whenever Natural ISPF is invoked or suspended. It can be used to modify Natural color settings when leaving or entering Natural ISPF.

The following parameters are passed to the exit:

Parameter | Format | Type | Meaning
--- | --- | --- | ---
`#FC` | (A1) | `I` | `I` = when entering Natural ISPF. Any other value = when suspending Natural ISPF.
`#USER-ID` | (A8) | `I` | User ID of the user for whom the exit is to be executed.

## Resume Exit ISP-RESU

This program can be invoked when returning to Natural ISPF after execution of the command `NATURAL` or `APPLICATION`. This program can be used to display messages to the user.

To invoke this resume exit, you must enter `(RESUME` in the `CONFIG` member.

In addition to the standard data parameters described above, you must define the following data in the exit:

Parameter | Format | Type | Meaning
--- | --- | --- | ---
`#USER` | (A8) | `I` | User ID of the user for whom the exit is to be executed.
`#COMMAND` | (A50) | `I/O` | Command to be executed.

### Example

The following example program checks for new messages in the user's Inbasket in Con-nect:

      * USER EXIT TO BE INVOKED WHEN resuming NSPF
      * *********************  **    *************************************
      DEFINE DATA PARAMETER
      * *********************  **    *************************************
      1 #USER(A8)          /* I
      1 #COMMAND(A50)      /* I/O   command to be executed
      1 #ERROR-CODE(N3)    /* O     GT ZERO  command will not be executed
      1 #ERROR-NUMBER(N4)  /* O     AS USUAL
      1 #ERROR-PARM(A75)
      1 #OPTIONS(A20)      /* I/O   FFU
      LOCAL
      *
      * example to check con-nect inbasket items
      *
      1 #RETURN-CODE (N2)
      1 #CABINET     (A8)
      1 #PASSWORD    (A8)
      1 #NEW-PHONE   (P8)
      1 #NEW-MAIL    (P8)
      1 #NEW-INVIT   (P8)
      1 #OPEN-MAIL   (P8)
      1 #POST-MAIL   (P8)
      1 #MAIL-SUM    (P8)
      1 #MARK        (A1)
      END-DEFINE
      *
      DEFINE WINDOW WIND1 SIZE 06 * 30
        BASE 09/25
        CONTROL WINDOW
        FRAMED ON
      SET WINDOW 'WIND1'
      SET CONTROL 'Y45'
      INPUT (AD=IM) 'Mark for mail check: ' #MARK
      IF #MARK NE ' '
        MOVE #USER TO #CABINET
        CALLNAT 'Z-INBKT'
          #RETURN-CODE #CABINET #PASSWORD
          #NEW-PHONE #NEW-MAIL #NEW-INVIT
          #OPEN-MAIL #POST-MAIL
        IF #RETURN-CODE EQ 0
          COMPUTE #MAIL-SUM = #NEW-PHONE + #NEW-MAIL + #NEW-INVIT
          IF #MAIL-SUM GT 0
            MOVE #MAIL-SUM TO #ERROR-PARM
            MOVE 9004 TO #ERROR-NUMBER
          END-IF
        END-IF
      END-IF
      *
      END

## Suspend Exit ISP-SUSU

This program can be invoked when suspending Natural ISPF before execution of the command `NATURAL` or `APPLICATION`. For example, the program can be used to prohibit execution of these commands by setting an error code.

To invoke this suspend exit, you must enter `(SUSP` in the `CONFIG` member.

In addition to the standard data parameters described above, you must define the following data in the exit:

Parameter | Format | Type | Meaning
--- | --- | --- | ---
`#USER` | (A8) | `I` | User ID of the user for whom the exit is to be executed.
`#COMMAND` | (A50) | `I` | Command to be executed (`APPLICATION`/ `NATURAL`).
`#PARM` | (A78) | `I` | Parameters to be passed with the command.

### Example of Data Parameters

      * User exit to be invoked when ISPF is suspended
      * .i.e before the commands NAT or APPL are executed
      * *********************  **    *************************************
      DEFINE DATA PARAMETER
      * *********************  **    *************************************
      1 #USER(A8)          /* I
      1 #COMMAND(A50)      /* I
      1 #PARM   (A78)      /* I
      1 #ERROR-CODE(N3)    /* O     GT ZERO  command will not be executed
      1 #ERROR-NUMBER(N4)  /* O     AS USUAL
      1 #ERROR-PARM(A75)
      1 #OPTIONS(A20)      /* I/O   FFU
      END-DEFINE
      *
      IF *USER EQ 'JWO'
        IF #COMMAND EQ SCAN 'HUGO' OR
            #PARM    EQ SCAN 'HUGO'
          MOVE 1 TO #ERROR-CODE         /* not allowed
          MOVE 9001 TO #ERROR-NUMBER
        END-IF
      END-IF
      *
      END

## Session Exit ISP--S-U

The session exit is invoked when a `SUBMIT` command has been entered in an edit or browse session. This exit can be used to disallow the submit function.

To invoke this exit, you must enter `(SESS` in the `CONFIG` member. For using this exit in the context of `EXPORT` operations, see the description of `APPLYMOD 91`.

In addition to the standard data parameters described above, you must define the following data in the exit:

Parameter | Format | Type | Meaning
--- | --- | --- | ---
`#OBJECT` | (A2) | `I` | Identifies the object type to be submitted (for example, `P` for PDS member). For a list of possible values, see Table of Exits and Object Abbreviations.
`#SES-DATA` | (A200) | `I` | Parameters for this object. The session data is used differently for every object type. The correct redefinitions can be found in the data areas for the object, see also Table of Exits and Object Abbreviations.
`#OPTIONS` | (A20) | `O` | Current SAG Editor session number in format `'SES=n'` or `'SES=nn'` where n is a one-digit and nn a two-digit session number.

### Example of Data Parameters

      * Session user EXIT
      *
      DEFINE DATA PARAMETER
      1 #OBJECT  (A2)
      1 #SES-DATA(A200)
      1 #FUNCTION-DATA(A64)
      1 #FUNCTION(A2)
      1 #ERROR-CODE(N3)
      1 #ERROR-NR  (N4)
      1 #ERROR-PARM(A75)
      1 #OPTIONS   (A20)      /* I/O   for future use

## Rename Function Exit ISP-RN-U

The rename exit is invoked when a `RENAME` command has been entered. The exit is invoked by the new name and can check whether the new name is valid.

To invoke this rename exit, you must enter `(RENAME` in the `CONFIG` member.

In addition to the standard data parameters described above, you must define the following data in the exit:

Parameter | Format | Type | Meaning
--- | --- | --- | ---
`#OBJECT` | (A2) | `I` | Identifies the object type to be renamed (for example, `P` for PDS member). For a list of possible values, see Table of Exits and Object Abbreviations.
`#SES-DATA` | (A200) | `I` | Parameters for this object. The session data is used differently for every object type. The correct redefinitions can be found in the data areas for the object, see also Table of Exits and Object Abbreviations.
`#FUNCTION-DATA` | (A64) | `I` | Contains the function parameters, in this case the new name of the object to be renamed.

### Example

The following little example program reports new name `ANTON` as invalid.

      * RENAME function user exit
      *
       DEFINE DATA PARAMETER
       1 #OBJECT  (A2)
       1 #SES-DATA(A200)
       1 #FUNCTION-DATA(A64)
       1 #ERROR-CODE(N3)
       1 #ERROR-NR  (N4)
       1 #ERROR-PARM(A75)
       1 #OPTIONS   (A20)      /* I/O   for future use
       LOCAL USING ISP-RN-L
       LOCAL
       END-DEFINE
       MOVE #FUNCTION-DATA TO #FUNC-DATA-RN
       SET CONTROL 'WB'
       DISPLAY #OBJECT  #NEWNAME
       IF #NEWNAME EQ 'ANTON'
          MOVE 1 TO #ERROR-CODE
          MOVE 6800 TO #ERROR-NR
      END-IF
      *
      END

## User Library Exit ISP-PRFU

User-specific data such as profiles and menus is stored in the User Profile Library, which is called `SYSISPFU` and resides on the `FNAT` system file.

With this exit, the names of all user-specific libraries can be changed. If the modified library name does not start with `SYS`, the data will be stored and subsequently read from the `FUSER` system file. This exit is always invoked when a user library is accessed.

If you want to change the library name, modify the program accordingly, compile it and copy it to `SYSLIB` to activate it.

Parameter | Format | Meaning
--- | --- | ---
`#LIBRARY` | (A8) | The name of the library. `SYSxxx` libraries are read from `FNAT`, others from `FUSER`.
`#TYPE` | (A1) | Library type. Possible values:
`' '` | Profile library. Default: `SYSISPFU`
`'H'` | Help text library. Default: `SYSISPHU`
`'N'` | News text library (usually identical with the help text library). Default: `SYSISPHU`
`'U'` | Uinfo library. Default: `SYSISPIU`

This subroutine can be modified by the user. It can be used to modify the Natural library names, where site-specific Natural ISPF data is stored

If the standard library names (on the `FNAT` system file) are acceptable, do not modify this program.

## User Group Exit ISP-UGRU

When activated, this exit receives control each time a profile item is to be located within the User Profile Library.

With this exit, the sequence of user names or group names to be checked for existing profile definitions can be modified before accessing the database to search for them. In particular, the exit can erase some of the array entries from the array of group names passed to the exit, thus reducing the number of database calls required to locate a profile definition.

To make use of this option, modify the program accordingly, compile it an copy it to `SYSLIB`. To activate the user group exit, you must enter `(GROUPS` in the `CONFIG` member. In addition to the standard data parameters described above, you must define the following data in the exit:

Parameter | Format | Type | Explanation
--- | --- | --- | ---
`#S-OPTION` | (A1) | `I` | Search option in use: Contains `T` if `APPLYMOD 101` is set to `S`. Contains `Q` if `" "` is set to `P`. Contains `D` in all other cases.
`#USER-ID` | (A8) | `I` | User ID of current session or of the user being edited (if invoked in the context of user maintenance).
`#PROFCHAIN` | (A253) | `I/O` | To be redefined with the following array:
`#CHAIN-GROUPID` | (A8/1:23) |  | Array of user IDs, group IDs or prefixes to be searched for. This array will be filled by Natural ISPF before calling the exit, in the manner specified by `APPLYMOD 101`.

### Example

      DEFINE DATA
      PARAMETER
      1 #S-OPTION               (A1)    /* IN : search option derived
      *                                 /* from APPLYMOD / global flag
      *                                   = C: compatibility mode:
      *                                          use old prefix logic
      *                                   = D: like C, but invoke user exit
      *                                   = S: search all NSC groups
      *                                        (first priviledged,then others)
      *                                   = T: like S, but invoke user exit
      *                                   = P: serach priviledged NSC groups
      *                                        only
      *                                   = Q: like P, but invoke user exit
      *                                         ISP-UGRU after building chain
      1 #USER-ID               (A8)    /* IN : User-Id (from GDA)
      1 #PROFCHAIN             (A253)  /* OUT:chain of profiles to be searched
      1 REDEFINE #PROFCHAIN
        2 CHAIN-GROUPID        (A8/1:23) /* WARNING: you are advised NOT to
                                         /*  extend the length of this array !
                                         /* NOTE: adding array entries will
                                         /*   slow down performance, removing
                                         /*   entries will speed up NATURAL ISPF
      1 #ERROR-CODE(N3)
      1 #ERROR-NR  (N4)
      1 #ERROR-PARM(A75)
      1 #OPTIONS   (A20)      /* I/O   for future use
      *
      LOCAL
      1 #I (N2)
      END-DEFINE
      *
      * Example: If in your environment, only department ids consisting of
      *          2 characters are used for defining group profiles, you can
      *          reduce the number of array entries in the following way:
      *           IN: FIAA068,FIAA06*,FIAA0*,FIAA*,FIA*,FI*,F*,*
      *           OUT:FIAA068,FI*,*
      FOR #I = 1 TO 23
        IF CHAIN-GROUPID(#I) = MASK (XX'*') #USER-ID
          CHAIN-GROUPID(2) := CHAIN-GROUPID(#I)
          CHAIN-GROUPID(3) := '*'
          RESET CHAIN-GROUPID(4:23)
          ESCAPE ROUTINE
        END-IF
      END-FOR
      *
      END

## Node Exit ISP-NODU

This exit can be used to check whether access to a specific node is allowed. It is invoked whenever a user enters a Natural ISPF function or command, which needs access to an Entire System Server node.

By setting `#ERROR-CODE` and `#ERROR-NUMBER` access to a specific node can be disallowed. If the exit permits access to a specific node, this information is stored in Natural ISPF and the exit is not called any more with the same node ID.

To invoke the node exit, you must enter `(NODE` in the `CONFIG` member.

In addition to the standard data parameters described above, you must define the following data in the exit:

Parameter | Format | Type | Meaning
--- | --- | --- | ---
`#NODE` | (N5) | `I` | Node ID to be checked.

### Example

      DEFINE DATA PARAMETER
      1 #NODE       (N5)       /* I     Node ID to be checked. Note: N5 format.
      1 #ERROR-CODE (N3)
      1 #ERROR-NR   (N4)
      1 #ERROR-PARM (A75)
      1 #OPTIONS    (A20)      /* I/O   for future use
      END-DEFINE
      *
      * Restrict access to node 148
      *
      IF #NODE NE 148
        #ERROR-CODE := 1       /* set return code
        #ERROR-NR   := 7009    /* and message number (e.g. Invalid node)
      END-IF
      END

## HSM - Hierarchical Storage Manager Exit ISP-HSMU

This exit is invoked (if activated in `CONFIG`) whenever a migrated data set has to be recalled before Natural ISPF recalls the data set.

This exit can recall the data set by submitting a batch job and inform the user to try again later. A special `DELETE` handling for migrated data sets can also be coded within this exit.

To invoke the `HSM` exit, you must enter either `(HSM` or `(HSM-S` in the `CONFIG` member:

- (HSM
  Setting the option `(HSM` in the `CONFIG` member causes the user exit to be invoked after the user has been prompted by Natural ISPF and has confirmed recall of the data set.

- (HSM-S
  Setting the option `(HSM-S` activates the user exit in "silent mode", that is, Natural ISPF's prompting is suppressed: the exit will be invoked without any prompting, whenever a user-initiated function refers to a migrated data set. This option is useful when you want the user exit to set up its own customized prompting dialog.

In addition to the standard data parameters described above, you must define the following data in the exit:

Parameter | Format | Type | Meaning
--- | --- | --- | ---
`ISPD---L` |  | `I` | Contains session data including the field `#DSNAME`.
`#RECALL-STATUS` | (N1) | `O` | Possible options:
`0` | Exit did not start `RECALL`. `RECALL` will be performed by caller.
`1` | `RECALL` terminated successfully. Caller will continue processing.
`2` | `RECALL` started but not yet terminated. Caller will abort processing and inform user to try again later.
`3` | `DELETE` operation has been initiated or completed (valid only if `#OPTIONS='FCT=DELETE'`). Caller will abort processing and signal deletion with appropriate message.
`9` | `RECALL` rejected by user or user exit. Makes sense mainly in "silent mode", that is, with `(HSM-S` in `CONFIG` member. Caller will abort processing.
`#OPTIONS` | (A20) | `I/O` | This field usually contains blanks. If it contains `FCT=DELETE`, this indicates that the exit is being invoked while handling a `DELETE-DATASET` command issued by the user. The exit can either ignore this information, or else it can set appropriate actions to delete the data set from archive without recalling it. In the latter case, `#RECALL-STATUS` must be set to 3. Warning At the time when the exit is invoked, Natural ISPF has not yet prompted for a confirmation of file deletion. If desired, this prompting has to be performed by the user exit.

### Example

      DEFINE DATA PARAMETER
            USING ISPD---L    /* Contains session data including
      PARAMETER               /* field #DSNAME
      1 #ERROR-CODE(N3)
      1 #ERROR-NR  (N4)
      1 #ERROR-PARM(A75)
      1 #RECALL-STATUS (N1)
      1 #OPTIONS   (A20)      /* I/O
      END-DEFINE
      *
      RESET #RECALL-STATUS
      END

## Editor Profile Exit ISP-ED-U

When activated, this exit is invoked before an edit session is opened in Natural ISPF. The exit can change the list of profile names requested for this edit session.

To invoke this exit, you must enter `(PROFIL` in the `CONFIG` member.

In addition to the standard data parameters described above, you must define the following data in the exit:

Parameter | Format | Type | Meaning
--- | --- | --- | ---
`#SES-DATA` | (A200) | `I` | Session data for object.
`#PROFILE-NAME` | (A8/10) | `I/O` | Profile names.

### Example

      DEFINE DATA PARAMETER
      * ********************* **    *************************************
      1 #OBJECT   (A2)       /* I     Object type for the session
      1 #FUNCTION (A2)       /* I     Function entered by user
      1 #SES-DATA (A200)     /* I     Session data for object
      1 #PROFILE-NAME(A8/10) /* I/O   Profile names
      END-DEFINE
      *
      END

## Incore Database Defaults Exit IDB-USRN

This exit is invoked whenever the `EDIT`/`BROWSE` function is invoked in the Incore database. It can be used to define application-specific defaults and return language-dependent data.

Before modifying the exit, copy it to the application library which uses the Incore database, then make the changes and recompile it.

Parameter | Format | Type | Meaning
--- | --- | --- | ---
`#LANGUAGE` | (A1) | `I/O` | Requested language *
`#DEFAULT-SCROLL` | (A4) | `O` | Scroll value `MOVE 'CSR' TO #DEFAULT-SCROLL`
Language-dependent constants:
`#-ROW` | (A4) | `O` | Row `MOVE 'Row' TO #-ROW`
`#-OF` | (A4) | `O` | Of `MOVE 'of' TO #-OF`
`#-COMMAND` | (A10) | `O` | Command `MOVE 'COMMAND==>' TO #-COMMAND`
`#-SCROLL` | (A9) | `O` | Scroll `MOVE 'SCROLL==>' TO #-SCROLL`
PF keys:
`#PF-KEY` | (A50/24) | `O` | Contents `ASSIGN #PF-KEY(1)=':I'`
`#PF-NAME` | (A5/24) | `O` | Language dependent name `ASSIGN #PF-NAME(1)='Insrt'`

* Possible values for `#LANGUAGE` when used as an output parameter:

- The value `'H'` indicates that additional calls to Natural's text translation module `NATPM` are to be made to support inverted terminal display for Middle Eastern countries during the functions `EDIT` and `BROWSE`. When `#LANGUAGE='H'` is specified, the `NATPM` module must be specified as `CSTATIC` in your Natural parameter module.

- Any character other than `H` causes the screen to be displayed in the normal mode, without invoking the `NATPM` module.

## Container File Access Exit IDBC---U

This exit is invoked whenever the Incore database container file is accessed. It can be used to restrict access to the container file

Before modifying the exit, copy it to the application library which uses the Incore database container file. You can then make the changes and recompile the exit.

Parameter | Format | Type | Meaning
--- | --- | --- | ---
`#ACTION` | (A8) | `I` | Access type for incore file. Valid actions:
`' '` | Directory from container.
`DELETE` | Delete file from container.
`RETRIEVE` | Read from container.
`STORE` | Write to container.
`T#YPE` | (A8) | `I` | Identification of container file consists of the `#TYPE`, `#GROUP` and `#NAME` fields.
`#GROUP` | (A48) | `I`
`#NAME` | (A32) | `I`
`#ERROR-CODE` | (N3) | `O` | Access denied if this field is anything but zero.
`#ERROR-TEXT` | (A75) | `O` | Optional message text.

### On this page

- Object Exits
- Examples of Object Exits
- CA Panvalet Save Exit ISPT-SVU
- Logon Exit ISP-LONU
- Logoff Exit ISP-LOFU
- Print User Exit ISP-PRTU
- Import/Export Exits
- Color Settings Exit ISP-ECLU
- Resume Exit ISP-RESU
- Suspend Exit ISP-SUSU
- Session Exit ISP--S-U
- Rename Function Exit ISP-RN-U
- User Library Exit ISP-PRFU
- User Group Exit ISP-UGRU
- Node Exit ISP-NODU
- HSM - Hierarchical Storage Manager Exit ISP-HSMU
- Editor Profile Exit ISP-ED-U
- Incore Database Defaults Exit IDB-USRN
- Container File Access Exit IDBC---U