Exits Reference

How to use
Endevor
with user exits
Endevor 18.1
This section explains how to use
Endevor
with user exits.
2
To use exit programs with
Endevor
, you must:
  • Identify the exits that you want to use.
  • Write the exits.
  • Identify the exits to
    Endevor
    by including them in the user exits table (C1UEXITS). The user exits table is created during
    Endevor
    implementation, and then updated as necessary.
During session initialization,
Endevor
loads the Defaults Table and the C1UEXITS table, then loads all exits that are defined in the C1UEXITS table into storage.
When it reaches an exit point,
Endevor
:
  • Builds one or more control blocks.
  • Checks the user exit table to determine the exits to be called.
  • Passes the control blocks to the exit program.
  • Receives the control blocks from the exit program, displaying messages and modifying information as necessary based on the control block information.
Exits written for package functions differ in some respects from other exits. For more information about package exits, see Using Package Exits.
The
Endevor
exit interface is designed for use with exits that are written in either assembler or in high-level languages such as COBOL.
Endevor
supports standard IBM calling conventions for all user exits. There is one exception: exit programs must pass return codes back to
Endevor
through the exit control block, not through Register 15. They must also be re-entrant and re-usable.
Endevor
has reserved storage subpools 10 to 19 for user exits. Although user exits can use any storage subpool, storage that is contained in subpools 10 through 19 can be freed at the subpool level without affecting the operation of
Endevor
.
ENUXSITE
ENUXSITE is an exit that is called at
Endevor
initialization that allows your site to identify the name of an alternate Defaults Table based on a user ID or other criteria.
An alternate Defaults Table might be used as a mechanism to test a new configuration at your site. An alternate Defaults table can also enable you to provide a specific Defaults Table for a group of users based on particular installation criteria.
Because the Defaults table stores the default table names used for the optional Feature table (ENCOPTBL), the Exits table (C1UEXITS), the Configuration table (ENDICNFG), and the Email look-up table (ESMTPTBL), ENUXSITE can be used to load a customized version of any of these tables.
Using ENUXSITE to Override the C1DEFLTS Name
With the application of PTF SO12677, a new sample version of the ENUXSITE exit is available. The new ENUXSITE exit can be used to override the default C1DEFLTS name, and the new C1DEFLTS name or names can then be pointed to different configurations, optional features, symbols, or security tables. The source for the new exit is distributed in
iprfx
.
iqual
.CSIQOPTN
.
The new ENUXSITE exit works by searching for a previously allocated DDNAME in the format
EN$DFT
xx
. If a suitable DDNAME is found, ENUXSITE overlays the last two characters of the default C1DEFLTS table name with the characters (
xx
) from the DDNAME.
Example: An
ALLOC FILE (EN$DFT
AA
) DUMMY SHR REU
startup routine would tell
Endevor
to load a defaults table called C1DEFL
AA
rather than the standard C1DEFLTS defaults table.
Sites that want to support multiple C1DEFLTS tables can add the following statement to their logon on startup CLISTs:
ALLOC FILE (EN$DFTxx) DUMMY SHR REU
Endevor
then automatically selects an appropriate defaults table and propagates that table to any batch jobs that are submitted through the [email protected] skeleton member. If you are using the new startup clists, you can propagate the keywords using the DF (xx) keyword or by overtyping the Defaults Suffix value on the Settings panel.
Call ENUXSITE Multiple Times
From Release 18.1 onward, the ENUXSITE exit is called only once when you execute
Endevor
. If your site requires ENUXSITE to be called multiple times, specify ENHOPT ALWAYS_CALL_ENUXSITE=ON in the Optional Feature Table (ENCOPTBL) to restore the pre-18.1 behavior. The option is turned off by default.
Installation Requirements for User Exits
All user exits must:
  • be assembled or compiled and linked with the RENT attribute
    An S0C4 ABEND might occur if you execute an exit program that has been linked with the RENT attribute but is not reentrant.
  • reside in an APF-authorized load library. If one of these modules comes from a non-authorized library, a U0078 ABEND occurs. The U0078 ABEND is accompanied by an eight-digit reason code, the first four digits of which indicate why the abend occurred:
    • ABEND=S000 U0078 REASON=00140000
      ENUXSITE was not found, or is missing from the APF load library.
    • ABEND=S000 U0078 REASON=00180000
      C1DEFLTS was not found, or is missing from the APF load library.
    • ABEND=S000 U0078 REASON=001C0000
      C1DEFLTS was not linked with the RENT attribute.
    ISPF services are not available when the ENUXSITE exit is invoked, even if the exit is invoked from
    Endevor
    running in TSO.
Exit Names
Endevor
provides a sample exit table with exit program names of C1UEXTnn, where nn is the number of the exit point where
Endevor
calls the program. For example, the default name for an exit program to be called at exit point 1 is C1UEXT01. We recommend that internal names for exits written in a high-level language (for example, COBOL) maintain this naming convention.
For more information about naming conventions for exits, see the "Exits and High-Level Languages" section of this article.
If you choose to use another naming convention for your exit programs, be sure to change the names in the sample exit table before building the table.
Exits and High-Level Languages
Endevor
provides an interface program, EPC1UEXT, which makes control blocks available to exit programs that are written in high-level languages such as COBOL. This program is provided as a load module in the
uprfx.iqual.CSIQLOAD
library. Program EPC1UEXT does not support package function exits.
To use EPC1UEXT, link-edit it with the high-level language exit program, naming EPC1UEXT as the entry point. Sample linkage editor input is shown next:
INCLUDE SYSLIB(EPC1UEXT) *front-end program* INCLUDE SYSLIB(exit program name) *real exit program* ENTRY EPC1UEXT NAME C1UEXTnn(R)
Program EPC1UEXT recognizes only one exit program for each exit point. The name of your COBOL exit and the exit name you code in the C1UEXITS table must be C1UEXT0
n
, where n is the exit number. For sample JCL that compiles and links a COBOL exit, see the CSIQJCL installation library, member name BC1JEXIT.
If you are using a COBOL compiler that supports address pointer fields, you do not need to use the EPCIUEXT program. Instead, you must edit the sample exits as follows:
  • Redefine all the pointer fields, in the sample exits, as 'USAGE IS POINTER'.
  • Use the SET statement in the Procedure Division, to set the address of the control blocks to the pointer field.
Define Multiple COBOL Programs for the Same Exit Point
Follow these steps:
  1. Compile the first exit program, for example C1UEXT03.
  2. Rename the compiled program. For example, you might rename program C1UEXT03 as XIT3PROG1.
  3. Compile the second program for the same exit. This program would also be named C1UEXT03.
  4. Rename the second program. For example, you might rename the second C1UEXT03 program as XIT3PROG2.
  5. Repeat the compile and rename steps as necessary.
  6. Edit the C1UEXITS table to include the renamed exits.
Sample COBOL Linkage Section
A sample COBOL linkage section is provided as member EXITBLKS in the
iprfx.iqual.CSIQOPTN
library. This member contains COBOL representations of most of the exit control blocks. It can be copied into exits that you are writing in COBOL.
Store User Exits
We recommend that you store exit programs in an APF-authorized LINKLIST library using the exit name as the load module name.
For testing purposes, the authorization parameter (AUTH=NO) for the @C1UEXIT macro allows you to load the exit routines from either CONLIB or STEPLIB.
Debug an Exit Program
Endevor
includes a trace facility for use in debugging exit programs and for viewing the information passed to your exit programs by
Endevor
. Exit trace output is contained in the User Exit Parameter Trace Log.
To produce the exit trace log, perform one of the following actions:
  • In
    batch
    mode, do one of the following:
    1. Include this statement in a batch job:
      //EN$TRXIT DD SYSOUT=*
    2. Allocate a data set with the following DCB parameters: LRECL=133, BLKSIZE=1330, RECFM=FB, DSORG=PS, and include the following statement in the job:
      //EN$TRXIT DD DSN=data set name, DISP=SHR
  • In the
    foreground
    , allocate the data set as previously described, and then allocate the file to the foreground session data set using the following command:
    ALLOC FI(EN$TRXIT) DA('data set name') SHR REUS
    The exit trace log includes a listing of control block contents for the before- and after-exit points. This allows you to compare input and output information. If the information in a particular field in the after-exit control block is not what you expect, there is a bug in your program.
Sample Exit Trace Log
The following illustration is a portion of a sample exit trace log for a before-action (exit 2) program. This sample trace log lists the libraries that are searched to find the exit program. If CONLIB/STEPLIB is listed, the exit was found in CONLIB, STEPLIB, LINKLIST, or LPA. If STEPLIB is listed, the exit was found in STEPLIB, LINKLIST, or LPA.
This figure illustrates a portion of a sample exit trace log.
For more information, see the "Exit Point Functions" section of Using Exit Points, and the "Exit Control Blocks" section of Using Package Exit Control Blocks.
The following illustration is a comparison of the after-action control block information for the modifiable fields. This indicates that the information has remained the same and the program is functioning normally.
Sample Trace Log After
How to Identify Exits
You identify exit programs to
Endevor
by adding a @C1UEXIT macro to the source code of the user exits table (C1UEXITS). The sample source code can be found in the C1UEXITS member in the
iprfx.iqual.CSIQSRC
library. During
Endevor
execution, within each exit number, the exits are called in the order defined in the exit point within the load module. Use sample JCL BC1JTABL to assemble and link-edit C1UEXITS to your
iprfx.iqual.CSIQAUTU
outside of SMP/E or use an SMP/E USERMOD to accomplish this. BC1JTABL can be found in the installation library
iprfx.iqual.CSIQJCL
.
C1UEXIT Macro Statements
The C1UEXITS source consists of a series of @C1UEXIT macro statements. The following list contains three varieties of @C1UEXIT macros statements:
  • @C1UEXIT TYPE=START...
  • @C1UEXIT EXIT#=number,NAME=program...
  • @C1UEXIT TYPE=END
One TYPE=START macro must be coded as the first macro in the table source. One TYPE=END macro must be coded as the last macro in the table source. One EXIT#= macro should be coded for each exit program that you identify to
Endevor
.
Identifying the Start of the User Exit Table Using the C1UEXIT Macro Statement
@C1UEXIT TYPE=START...identifies the start of the user exit table and sets a default value of Yes or No for PECBBATX. The format is as follows:
@C1UEXIT TYPE=START,XIT7BAT=YES
Where: XIT7BAT=
Sets a default value for PECBBATX If this keyword is not coded, a severity 4 MNOTE is generated at assembly time and a default value of "No" is chosen. Acceptable values are:
PECBBATX to "N" during the Setup call.
  • No
    Indicates that all or most package exits cannot run in batch (without TSO services). Those exits that can run in batch should set PECBBATX to "Y" during the Setup call.
  • Yes
    Indicates that all or most package exits can run in batch (without TSO services). Exits that cannot run in batch must set PECBBATX to "N" during the Setup call.
Identifying a Program as an Exit Using the C1UEXIT Macro Statement
Use the @C1UEXIT EXIT#=number,NAME=program to identify a program as an
Endevor
exit. A single macro is required for each exit module you want to identify. The format is as follows:
@C1UEXIT EXIT#=1,NAME=C1UEXT01,ANCHID=0,AUTH=YES,USE_ALTID=Y,CALLAPF=NO
  • EXIT#
    The exit point where you want
    Endevor
    to call the exit program. Acceptable values are 1 through 7.
  • NAME
    Defines the program name. This name must be the same as the name of the called program.
  • ANCHID
    Specifies the anchor ID for this user exit. The valid range for an anchor ID is 0-9999. If an anchor ID is not coded, the default is zero (0).
  • AUTH
    Specifies whether the exit program is stored in an APF-authorized library. Acceptable values are:
    • Yes
      - Default. Indicates that the user exits are stored in an APF-authorized library.
    • No
      - Indicates that the user exits are stored in either a STEPLIB or CONLIB. Use this option when testing exits.
  • USE_ALTID
    Specifies how the switch to the alternate ID is done for the exit program. Acceptable values are:
    • Y
      - Default. Indicates that
      Endevor
      switches to the alternate ID just before opening a data set. Then switches back to the user ID on completion of the open.
    • N
      - Indicates that
      Endevor
      does not switch to the alternate ID before opening a data set.
    • +
      - Indicates that
      Endevor
      switches to the alternate ID just before invoking the user exit. Then switches back to the user ID on completion of the exit. Coding this value also causes OPENs to be executed under the security context of the alternate ID.
  • CALLAPF
    Specifies whether the exit program is called in
    problem program state
    or in
    supervisor state
    .
    When CALLAPF=YES is coded, then AUTH=YES is required.
    • No
      - Default. Indicates the exit is called in problem program state.
    • Yes
      - Indicates the exit is called in supervisor state.
    For information about executing authorized exits, see the "Executing Authorized Exits and Processor Programs" topic.
Identifying the End of the User Exit Table Using the C1UEXIT Macro Statement
@C1UEXIT TYPE=END identifies the end of the user exit table. The format is as follows:
@C1UEXIT TYPE=END
Anchor IDs and Multiple User Exits
Anchor IDs allow you to store information produced by one user exit that needs to be passed to one or more other user exits. To do this, assign the same anchor ID to all the exits that use the information.
Anchor IDs work as follows:
  • Endevor
    initialization logic builds an anchor ID table, associating each anchor ID with a default value of 0000. Anchor IDs can have a value of 0-9999.
    Endevor
    user exits have an anchor ID of 0.
  • Before a user exit is invoked,
    Endevor
    copies the value stored in the anchor ID table into the ECBUEXT field in the $ECBDS DSECT.
    Endevor
    then executes the user exit.
  • The user exit, if necessary, can modify the ECBUEXT field in the $ECBDS DSECT. After the exit terminates,
    Endevor
    copies the value in the ECBUEXT field into the anchor ID table.
Example: Define Additional Exits for
Endevor
In this example, assume you want to specify three additional exits to be supported by
Endevor
and that the information produced by exit 1 will be used by exits 3 and 6. You might specify the following exit routines:
  • An exit 1 routine called SECEXIT1 with an anchor ID of 2.
  • An exit 3 routine called RECEXIT3 with an anchor ID of 2.
  • An exit 6 routine called STATEXT6 with an anchor ID of 2.
You would then modify the exit table by adding three lines to the @C1UEXIT macro in the BC1JXIT JCL, as follows:
*---------------------------------------------------------------------* C1UEXITS @C1UEXIT TYPE=START,XIT7BAT=YES *---------------------------------------------------------------------* * SEE
Endevor
EXITS MANUAL FOR A DESCRIPTION OF * * DEFINING MULTIPLE USER EXITS. * *---------------------------------------------------------------------* @C1UEXIT EXIT#=1,NAME=C1UEXT01,ANCHID=0,AUTH=YES
@C1UEXIT EXIT#=1,NAME=SECEXIT1,ANCHID=2,AUTH=YES
@C1UEXIT EXIT#=2,NAME=C1UEXT02,ANCHID=0,AUTH=YES @C1UEXIT EXIT#=3,NAME=C1UEXT03,ANCHID=0,AUTH=YES
@C1UEXIT EXIT#=3,NAME=RECEXIT3,ANCHID=2,AUTH=YES
@C1UEXIT EXIT#=4,NAME=C1UEXT04,ANCHID=0,AUTH=YES @C1UEXIT EXIT#=5,NAME=C1UEXT05,ANCHID=0,AUTH=YES @C1UEXIT EXIT#=6,NAME=C1UEXT06,ANCHID=0,AUTH=YES
@C1UEXIT EXIT#=6,NAME=STATEXT6,ANCHID=2,AUTH=YES
@C1UEXIT EXIT#=7,NAME=C1UEXT07,ANCHID=0,AUTH=YES *---------------------------------------------------------------------* * TYPE=DEFINITION DENOTES THE END OF THE EXIT TABLE. * *---------------------------------------------------------------------* @C1UEXIT TYPE=END END
When
Endevor
reaches the first exit point, both program C1UEXT01 and program SECEXIT1 will be called, in the order in which they are listed. This processing proceeds as follows:
  1. Prior to calling program SECEXIT1,
    Endevor
    reads the value associated with anchor ID 2 in the anchor ID table, and copies this value into the ECBUEXT field of the $ECBDS DSECT.
  2. Endevor
    then invokes SECEXIT1, passing the $ECBDS DSECT or one of the parameters.
  3. Program SECEXIT1 terminates and returns to
    Endevor
    .
  4. Endevor
    copies the value in the ECBUEXT field of the $ECBDS DSECT into the anchor ID table slot associated with anchor ID 2.
When exit point 3 is reached,
Endevor
calls both C1UEXT03 and RECEXIT3. Execution of program RECEXIT3 follows the four steps described previously. Note that the value associated with anchor ID 2 prior to calling RECEXIT3 in the anchor ID table will be the value in the ECBUEXT field after the execution of program SECEXIT1.
When exit point 6 is reached,
Endevor
calls both the C1UEXT06 and STATEXT6 routines. Execution of program STATEXT6 follows the four steps described above. Note that the value associated with anchor ID 2 in the anchor ID table prior to calling STATEXT6 will be the value in the ECBUEXT field after the execution of program RECEXIT3.