JES2 environments

When writing an exit routine, you must consider the calling JES2 environment, because your exit routine runs as an extension of that calling environment (JES2 main task, JES2 subtask, user address space, and functional subsystem). The calling environment has broad implications to your exit routine; it determines the JES2 system services available to your exit routine, the reentry considerations you should consider, the linkage conventions that are necessary, and several other essential factors (such as, control block access, synchronization, recovery, and JES2 programmer macro usage). Specifically, the use of macros in exit routines is limited. Before attempting to use a particular macro in an exit routine, be certain to check the “Environment” section of each macro description in Chapter 4 to determine the environments in which the macro can be used.

Every exit is explicitly defined to JES2 as belonging to one of the four execution environments. The ENVIRON= operand of the $MODULE macro is specified as either “JES2”, “SUBTASK,” “USER,” or “FSS”. This specification determines which of two exit effectors (the JES2 subroutines that establish the linkage between JES2 and an exit routine) will be called when the exit is enabled. One exit effector establishes linkage to an exit routine from the JES2 main task environment; the other establishes linkage to an exit routine from either the JES2 subtask environment, the user environment or the FSS. In all environments (JES2 main task, functional subsystem, subtask, and user environment) JES2 linkage conventions (that is, $SAVE and $RETURN) are used.

You cannot define an exit “across” environments. That is, when an exit is required to serve the same purpose in two distinct environments, two separate exits must be defined, each with its own identification number. For example, Exit 11, an IBM-defined exit that can give you control to reset the spool partitioning mask, belongs to the JES2 main task environment. Exit 12, which serves the same functional purpose, belongs to the user environment. In implementing these exits, you must write a separate exit routine for each defined exit and adapt the routine to its calling environment.

To stress again, whether defining an exit or writing an exit routine, you must be aware of the operating environment; it influences where your exit is to be defined or what processing your exit routine can really perform. In the descriptions of the following general programming considerations for writing an exit routine, specific environmental influences are described.

JES2 has four execution environments - maintask, subtask, user, and functional subsystem (FSS).

JES2 Main Task - The JES2 main task is the most common operating environment for JES2 exits. The JES2 main task routines are included in the JES2 load module HASJES20 which is loaded in the private area of the JES2 address space. JES2 main task routines run under the control of the JES2 dispatcher (in HASPNUC). The load module, HASPINIT, which performs JES2 initialization, runs under the main task but is not controlled by the JES2 dispatcher.
The execution of maintask routines, with the exception of asynchronous routines such as I/O appendages, are controlled by the JES2 dispatcher and are represented by a dispatching unit called processor control elements ($PCEs). $PCEs, which are analogous to task control blocks (TCBs) in MVS™, are the dispatchable elements in JES2 maintask.
There are two important coding considerations in the JES2 maintask environment.
- JES2 Reentrancy - An exit routine called from the JES2 main task must be reentrant in the JES2 sense. Because JES2 processors ($PCEs) do not relinquish control to another JES2 processor involuntarily, an exit routine, invoked out of a main task processor may use a JES2 nonreentrant work area. Therefore, the work area is serialized unless the exit routine issues a $WAIT macro (or service called from an exit routine issues the $WAIT macro). When the exit routine issues the $WAIT macro directly or through a called routine, control returns to the JES2 dispatcher and the serialization on the nonreentrant work area ceases. The nonreentrant work area may also be passed between exit routines, or between an exit routine and JES2, before a $WAIT macro call. Work areas to be used "across" a $WAIT must either be within the processor's work area established as part of the $PCE or else must be directly owned by the processor. In the same JES2 reentrant sense, an exit routine may search or manipulate a JES2 queue (for example, job queue or job output table) providing it has ownership of the queue (through the $QSUSE macro) and doesn't issue a $WAIT macro until the search routine is completed.
- MVS WAITs - The JES2 dispatcher controls all processing within the maintask environment; therefore, no routine or exit may issue any macro or call any service that could result in the execution of an MVS WAIT macro. Issuing MVS WAITs in JES2 maintask is contrary to the design of JES2 and will cause performance problems.
  An exception to this rule is JES2 initialization and JES2 termination. During initialization and termination, maintask processing is essentially single threaded. That is, there is only one $PCE dispatched so that JES2 reentrancy is not a factor. This also removes the concern about MVS WAITs causing a performance problem because during JES2 initialization and termination JES2 is not providing system services for other subsystems, started tasks, time sharing sessions and batch jobs. Therefore, there are no restrictions about MVS WAITs and MVS macros that can result in MVS WAITs in JES2 exits 0, 19, 24, and 26.
  
  If it is necessary to invoke MVS services from JES2 maintask exits that may cause MVS waits, these services should be invoked from a subtask environment. The $SUBIT macro can be used to cause a routine to execute in a subtask environment. The WAIT/POST synchronization of the subtask is provided as part of this service.
JES2 Subtask - JES2 subtasks run in the private area of the JES2 address space but run asynchronously with the JES2 main task. Subtasks run under the control of the MVS dispatcher (not the JES2 dispatcher) and their asynchronous operation allows them to perform the WAIT/POST type processing without imposing the same WAIT/POST operations on the JES2 main task. System-wide MVS services are available to programs in this environment.
Many JES2 maintask data areas are directly addressable, but users of these resources must understand when and where serialization of these resources is relevant. Most importantly, subtask should not directly reference the checkpoint area (job queue, job output table, and so on), because in certain portions of the checkpoint cycle this storage area is not addressable. If a subtask requires a view of the checkpoint, use the JES2 checkpoint versioning facility and the appropriate SSI calls.
User Environment - Some JES2 routines are loaded into common storage (located either in extended or non-extended LPA, PLPA, or CSA) execute in the user's address space. This environment, which permits user programs to interface with JES2, differs greatly from the JES2 maintask environment. System-wide MVS services are available to programs in this environment, but the environment is also more complex. It involves many integrity, synchronization, locking and cross-address space communications considerations. JES2 services in the user environment are limited.
A special operating environment you can use called (USER,ANY). It is intended for environments where a routine is able to be invoked in the USER run-time environment, or under the JES2 main task. For example, Use (USER,ANY) to write a common routine invoked by both Exit 2 and Exit 52. To use it, you can code ENVIRON=(USER,ANY) on your $MODULE statement or on a $ENVIRON macro invocation. The (USER,ANY) environment is similar to the USER environment (for instance, R11 is the HCCT address) except for the following differences in the way that $SAVE and $RETURN services are implemented:
1. If the routine is called by the JES2 main task, JES2 main task $SAVE/$RETURN services are called. This allows the possibility of a $WAIT within the routine. With a user-environment $SAVE that uses the linkage stack, this processing is not possible.
2. In any environment, a PSV-type save area is obtained rather than using a BAKR to save the registers and environment. This allows services such as $STORE and $RESTORE to be used in any environment.
FSS Environment - The functional subsystem (FSS) resides in the functional subsystem address space. This environment is similar to the user environment in that JES2 services are limited. You must consider task interaction within the FSS. All data areas and control blocks are not accessible from the FSS. The accessible control blocks are the job output element ($JOE) JOE information block ($JIB), FSS control block (FSSCB), and FSA control block (FSACB). System-wide MVS services are available to programs in this environment.

Figure 1. JES2 and FSS Address Spaces