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:

'OBJECT = xx'

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.

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:

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:

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:

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:

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:

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:

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:

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:

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.

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:

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:

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:

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:

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.

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