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:
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.
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: |
||||||
#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
Example: MOVE 'OBJECT = -7' TO #OPTIONS |
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 |
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
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
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. |
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. |
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. |
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
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
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
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. |
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. |
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
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. |
* 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
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.
|
* 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
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. |
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-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.
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 Contains |
#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 .
|
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
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. |
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
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
|
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
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. |
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
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.
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. |