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

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 Software AG 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
ISBD---U ISBD---L BS2000 files BF
ISBJ---U ISBJ---L BS2000 jobs BJ
ISBL---U ISBL---L LMS elements LMS
ISBV---U ISBV---L BS2000 job variables JV
ISB6---U ISBL---L LMS element versions LMV
ISDA---U ISDA---L z/VSE active jobs DA
ISDD---U ISDD---L z/VSE files FIL
ISDJ---U ISDJ---L z/VSE jobs DJ
ISDL---U ISDP---L z/VSE sub-libraries SUB
ISDP---U ISDP---L z/VSE members MEM
ISDR---U ISDR---L z/VSE member versions VV
ISDZ---U ISDP---L z/VSE volumes DV
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, Software AG's Office system:

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