What is a JES2 exit?

JES2 exits provide a clean, convenient, relatively stable interface between JES2 and your installation-written code. Installation-written exit routines are invoked from standard JES2 processing at various strategic locations in JES2 source code. These strategic locations in JES2 source code are called exit points. A JES2 exit is established by one or more exit points.

An exit point is defined by the $EXIT macro and, as illustrated in Figure 1, is the exact location in JES2 code where JES2 can pass control to your exit routine (that is, your installation-written code). The JES2 exit, identified by the “exit-id code” of nnn, is defined by one exit point at label JLBL in the JES2 code. It is at JLBL in JES2 processing that JES2 passes control to your exit routine.

To use the exit facility you perform the following steps, as illustrated in Figure 1.

Package your code into one or more exit routines, identifying each exit routine with an entry point name. (In Figure 1 there is a series of exit routines noted as entry points X1...Xn.) Then include the exit routine in a load module. In this case LMOD is the load module containing the exit routine.
In the JES2 initialization stream include the LOADmod(jxxxxxxx) initialization statement, which causes your exit routine's load module to be loaded into either private (PVT), common (CSA), or to locate the module in link pack area (LPA) storage. The linkage editor RMODE attribute determines whether the system loads the module above or below 16 megabytes.
Also include the EXIT(nnn) initialization statement, which associates your exit routines' entry point with the exit point in the JES2 code. The EXIT(nnn) initialization statement matches the exit point “nnn” at label JLBL for the $EXIT macro in the JES2 code. The EXIT(nnn) initialization statement identifies the label “X1” as the entry point of the exit routine for exit point “nnn”. The LOAD initialization statement identifies LMOD as the load module to be loaded into storage.

Figure 1. A JES2 Exit

JES2 can have up to 256 exits, each identified by a number from 0 to 255. You specify the number on the required “exit-id code” parameter on the $EXIT macro.

This exit-id code identifies the JES2 exit. When more than one exit point is defined for a single exit, the $EXIT macros that defined the multiple exit points have unique labels but are all specified with the same exit-id code – see Figure 2.

Figure 2. EXIT Point Variations

JES2 code includes a number of IBM-defined exits. That is, various exit points – through the $EXIT macro – have already been strategically placed in the JES2 code. The intended purpose of each of these exits is summarized in Table 1. For these IBM-defined exits you need only write your own exit routines and incorporate them through the EXIT(nnn) initialization statement and the LOADmod(jxxxxxxx). The selection of the point in JES2 code where the exit point should be placed has already been done for you. To ensure a proper implementation, you should thoroughly understand the IBM-defined exit and its JES2 operating environment. A comprehensive description of each exit is presented in IBM-defined exits.

Also, the JES2 exit facility allows you to establish your own exits, should the IBM-defined exits not suffice. Exits established by you are modifications to JES2 and are called installation-defined exits, and you define them by placing the $EXIT macro yourself at appropriate points in the JES2 code (or in your own exit routine code). Note, however, that implementing your own exit can be considerably more difficult than writing an exit routine for an IBM-defined exit. You should realize that in establishing your own exits, you run a greater risk of disruption when installing a new version of JES2 code. The new JES2 code into which you have placed your exits may have significantly changed since your $EXIT macros were inserted. For more information, see Establishing installation-defined exits.

Every exit, both IBM-defined and installation-defined, has a status of enabled or disabled which is set at initialization through the EXIT(nnn) initialization statement and which can be dynamically altered by the $T EXIT(nnn) operator command. When an exit is enabled, JES2 checks for the existence of an associated exit routine and then passes control to the exit routine. If no associated exits are found, standard JES2 processing continues. For certain exits, called job-related exits, (see Job-related exits) the status can be altered on a job-by-job basis by the action of an exit routine. When an exit is disabled for a particular job (by use of the job mask), it is automatically bypassed by standard JES2 processing.