How to use
Endevorwith user exits
This section explains how to use
Endevorwith user exits.
To use exit programs with
Endevor, you must:
- Identify the exits that you want to use.
- Write the exits.
- Identify the exits toEndevorby including them in the user exits table (C1UEXITS). The user exits table is created duringEndevorimplementation, and then updated as necessary.
During session initialization,
Endevorloads 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,
- 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.
Endevorexit interface is designed for use with exits that are written in either assembler or in high-level languages such as COBOL.
Endevorsupports standard IBM calling conventions for all user exits. There is one exception: exit programs must pass return codes back to
Endevorthrough the exit control block, not through Register 15. They must also be re-entrant and re-usable.
Endevorhas 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
ENUXSITE is an exit that is called at
Endevorinitialization 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
The new ENUXSITE exit works by searching for a previously allocated DDNAME in the format
EN$DFT. 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.
ALLOC FILE (EN$DFTstartup routine would tell
AA) DUMMY SHR REU
Endevorto load a defaults table called C1DEFL
AArather 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
Endevorthen 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 attributeAn 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:
ISPF services are not available when the ENUXSITE exit is invoked, even if the exit is invoked fromEndevorrunning in TSO.
- ABEND=S000 U0078 REASON=00140000ENUXSITE was not found, or is missing from the APF load library.
- ABEND=S000 U0078 REASON=00180000C1DEFLTS was not found, or is missing from the APF load library.
- ABEND=S000 U0078 REASON=001C0000C1DEFLTS was not linked with the RENT attribute.
Endevorprovides a sample exit table with exit program names of C1UEXTnn, where nn is the number of the exit point where
Endevorcalls 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
Endevorprovides 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.CSIQLOADlibrary. 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:
- Compile the first exit program, for example C1UEXT03.
- Rename the compiled program. For example, you might rename program C1UEXT03 as XIT3PROG1.
- Compile the second program for the same exit. This program would also be named C1UEXT03.
- Rename the second program. For example, you might rename the second C1UEXT03 program as XIT3PROG2.
- Repeat the compile and rename steps as necessary.
- 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.CSIQOPTNlibrary. 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
Endevorincludes 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:
- Inbatchmode, do one of the following:
- Include this statement in a batch job://EN$TRXIT DD SYSOUT=*
- 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 theforeground, 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 REUSThe 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.
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.
How to Identify Exits
You identify exit programs to
Endevorby 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
Endevorexecution, 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.CSIQAUTUoutside of SMP/E or use an SMP/E USERMOD to accomplish this. BC1JTABL can be found in the installation library
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
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:
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.
- NoIndicates 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.
- YesIndicates 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
Endevorexit. A single macro is required for each exit module you want to identify. The format is as follows:
- EXIT#The exit point where you wantEndevorto call the exit program. Acceptable values are 1 through 7.
- NAMEDefines the program name. This name must be the same as the name of the called program.
- ANCHIDSpecifies 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).
- AUTHSpecifies 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_ALTIDSpecifies how the switch to the alternate ID is done for the exit program. Acceptable values are:
- Y- Default. Indicates thatEndevorswitches to the alternate ID just before opening a data set. Then switches back to the user ID on completion of the open.
- N- Indicates thatEndevordoes not switch to the alternate ID before opening a data set.
- +- Indicates thatEndevorswitches 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.
- CALLAPFSpecifies whether the exit program is called inproblem program stateor insupervisor 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.
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:
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:
- Endevorinitialization 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.Endevoruser exits have an anchor ID of 0.
- Before a user exit is invoked,Endevorcopies the value stored in the anchor ID table into the ECBUEXT field in the $ECBDS DSECT.Endevorthen executes the user exit.
- The user exit, if necessary, can modify the ECBUEXT field in the $ECBDS DSECT. After the exit terminates,Endevorcopies the value in the ECBUEXT field into the anchor ID table.
Example: Define Additional Exits for
In this example, assume you want to specify three additional exits to be supported by
Endevorand 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 *---------------------------------------------------------------------* * SEEEndevorEXITS 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
Endevorreaches 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:
- Prior to calling program SECEXIT1,Endevorreads the value associated with anchor ID 2 in the anchor ID table, and copies this value into the ECBUEXT field of the $ECBDS DSECT.
- Endevorthen invokes SECEXIT1, passing the $ECBDS DSECT or one of the parameters.
- Program SECEXIT1 terminates and returns toEndevor.
- Endevorcopies 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,
Endevorcalls 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,
Endevorcalls 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.