Programming considerations

This exit is taken once for each control statement (except for JOB statements) encountered by JES2. X054IND indicates whether the current statement is a JCL statement or a JES2 control statement. Your exit routine gets control for //* comment, /* (generated), and /* PRIORITY JES2 control statements.
During input processing, JES2 writes the JCL records to a JCL data set. If an error occurs during input processing, it is the JCL data set that is printed when the job goes through output processing. If the job is successfully processed by input processing, the JCL data set is the input for the converter. The converter produces a JCL images data set that is printed when the job goes to output processing after being successfully processed by input processing.
Exit 54 is called for each card in a JCL statement (the original card and all continuations) and for each JES2 control statement. Each time the exit is called, it is passed the current card image and the statement buffer. The statement buffer is all the operands for the JCL statement or JES2 control statement concatenated in a single buffer. For example:
```
//OUTSET   DD SYSOUT=H,OUTPUT=*.OUT1,      COMMENT1
//  DCB=(LRECL=8000,RECFM=FB,BLKSIZE=8000) COMMENT2
```
In this case the exit will be called 2 times, once for each card and will be passed (on both calls) the following data in the statement buffer (pointed to by X054STMT):
```
SYSOUT=H,OUTPUT=*.OUT1,DCB=(LRECL=8000,RECFM=FB,BLKSIZE=8000) 
```
To alter the processing of the JCL statement or JES2 control card, the exit can either:
- Update the card image passed in X054CARD. This change will show up in the listing of the job.
- Update the statement buffer in X054STMT to add or modify the operands. This change does not show up in the listing of the job and is not passed to conversion processing (it only affects keywords input processing scans from the JCL/JECL card). If you update the statement buffer (X054STMT) in Exit 54 and change the length of the buffer, you must update the field X054STME to indicate the new end of buffer (one byte past the last meaningful character).
- Add additional card images to the JCL stream.
Adding card images to the JCL stream can be accomplished by either queuing a single RJCB or a chain of RJCBs to the XPL or by placing a card image to be placed after the current card into the area pointed to by X054JXWR and setting X054XSNC. In either case, when a card is added, the current card is re-scanned and the statement buffer is re-built. Exit 54 will be driven again for the updated statement, with X054SEC set to indicate this card has been presented to the exit previously.

When adding cards using RJCBs, use the RGETRJCB service (located in HASCSRIP) to obtain a free RJCB; then add it to one of the three RJCB queues in the XPL. Use the $CALL macro to invoke the RGETRJCB service. Register 1 on entry must be the JRW address. The RJCB address is returned in register 1.

The 80-byte card image to be added is placed into the field RJCBCARD. RJCBs are chained together using the RJCBRJCB field in the $RJCB. They are added to the job stream in the order they exist in the chain. To add an element to the chain you would move the current RJCB queue head in the $XPL into the RJCBRJCB field of the last RJCB you are adding and then set the address of the first RJCB element into the $XPL queue head. Be aware that multiple exit 4s might be using these queues so ensure that you do not lose existing entries on the queue.

X054RJCP

Adds the card images before the first card in the current JCL statement or before the JES2 control card.

X054RJCA

Adds the card images after the last card in the current JCL statement. In this case, the cards are assumed not to be a continuation of the current JCL statement, and the JCL cards are not re-scanned.

X054RJCC

Adds the card images after the current card. It is the callers' responsibility to ensure that the proper continuation processing will occur.

When processing the last card in a JCL statement or when processing a JES2 control statement, the difference between adding a card to the X054RJCA queue and the X054RJCC queue is that the first will not rescan the current statement and the second will do.
You can also add a single card image after the current card using the X054JXWR field. In this case, the JCL statement will be re-scanned just as if the card was added to the X054RJCC queue. To add information to a JCL statement:
1. Move a comma into the last byte of the operand on the JCL card image (X054CARD) that exit 54 is currently processing. The comma indicates additional information follows this JCL statement.
2. Move the information you want to add to the JCL statement to the area pointed to by X054JXWR and set the X054XSNC bit in the X054RESP byte to one. Setting X054RESP to X054XSNC indicates that the installation has supplied an additional JCL statement image.
3. Set register 15 to X'00' or X'04' depending on whether you want to invoke additional installation exits to process the statement.
You can also add an additional JCL statement to the job by:
1. Ensuring that the JCL card image that exit 54 is currently processing is the last for the current statement (X054LOPR is on). Exit 54 is processing the last JCL statement image if a comma is not in the last byte of the JCL operand on the card image.
2. Placing the JCL statement in the are pointed to by X054JXWR and set the X054XSNC bit in the X054RESP byte to one. Setting X054RESP to X054XSNC indicates that the installation has supplied an additional JCL statement image.
3. Setting register 15 to X'00' or X'04' depending on whether you want to invoke additional installation exits to process the JCL or JECL card.
For JECL statements, because there are no formal rules for the format of the statement, the statement buffer will contain all the text after the VERB on the JECL statement. The following is an example of a JOBPARM JECL statement and the associated statement buffer:
/*JOBPARM SYSAFF=(IBM1),COPIES=2 This is a comment
The statement buffer for this statement would contain:
SYSAFF=(IBM1),COPIES=2 This is a comment
The statement buffer contains the comment in this case (and any trailing blanks) because there is no formal rule stating where a JECL statement ends.
Updating the statement buffer is only valid for parameters that have $STMTTABs in HASCSRIP.
Updates to the statement buffer are not passed to the converter and will not be seen by Exit 6 or Exit 60.
The following indicators in the XPL can assist you in adding a card image to the current JCL statement:
X054LOPR

Current card has the last operand in the JCL statement. There can be additional continued comments after the current card.

X054QUOT

A quoted sting is being continued from the current card to the next card. Pay attention if a card is being added after this card.

X054CCMT

The current card is a continued comment. Operand added to this card or after this card will not be processed.

X054LAST

This is the last card image in the JCL or JECL statement.
To assist you in processing the operands on a statement, you can use either of these services to parse the statement buffer passed in X054STMT:
- The $SCAN facility can be used to parse the operands using the standard $SCAN rules for statements. This give you the flexability of $SCAN but the parsing rules are not the same as normal JCL. See the $SCAN and $SCANTAB macros for additional information.
- The RCARDSCN service and $STMTTAB macro can be used to parse the operands using standard JCL rules. This is the service used by JES2 input processing to parse the statement buffer. However, the RCARDSCN service only parses the operands and calls a processing routine to do all the conversions and storing of data. Conversion of data to binary to store into data areas is the responsibility of the processing routines. See the $STMTTAB macro for more information.
To entirely replace standard JES2 control card processing (HASPRCCS) for a particular JES2 control statement, write your routine as a replacement version of the standard HASPRCCS routine and then pass a return code of 8 back to JES2 to suppress standard processing. Note that your routine becomes responsible for duplicating any HASPRCCS function you want to retain. If you merely want to supplement standard HASPRCCS processing, you can write your exit routine to perform the additional function and then, by passing a return code of 0 or 4, direct JES2 to execute the standard HASPRCCS routine.
To nullify a JES2 control statement, pass a return code of 8 to JES2 without using your exit routine to perform the function requested by the statement. Note that, based on what appears in the JCL images output data set, the user is not informed that the statement was nullified.
To modify a JES2 control statement, also use return code 8. Place the altered statement in the area pointed to by X054JXWR and set X054XSNC to one. If input processing is successful, the user will see the original statement in the output of the JCL images file , and the altered statement. Note that if you modify a JES2 control statement; then pass a return code of 0 or 4, JES2 carries out normal input (HASPRCCS) processing. The modified version of the statement will appear on the user's output in the JCL images file, but the original statement will not appear unless you go directly to output phase (bypassing the converter); then, the user will see the original statement when the JCL data set is printed.
You also use return code 8 in processing your own installation-specific JES2 control statements. Write your exit routine to perform the function requested by the statement and then pass return code 8 to JES2 to suppress standard processing and thereby prevent JES2 from detecting the statement as "illegal."
Extend the JCT Control Block. You can use the $JCTX macro extension service to add, expand, locate, and delete extensions to the job control table ($JCT) control block from this exit. For example, you can use these extensions to store job-related information. Extensions that are added can be SPOOLed extensions that are available to all exits that read the JCT or local extension that are available only to input processing exits (52, 53, 54, and 50) and the $QMOD exit (51). The size of SPOOLed extensions is based on the SPOOL buffer size and is less than 3K. You can have up to 8K of local extension regardless of SPOOL buffer size.
To process your own installation-specific JES2 control statement subparameters, you should generally write your exit routine to replace standard HASPRCCS processing entirely. That is, write your exit routine to perform the functions requested by the standard parameters and subparameters, and those requested by any unique installation-defined subparameters on a statement. Then, from your exit, pass a return code of 8 back to JES2. Typically, because the parameters and subparameters on a JES2 control statement are interdependent, you will be limited to this method. However, if you have defined an installation-specific subparameter which can be processed independently of the rest of the control statement on which it appears, you can write your exit routine to process this subparameter alone, delete it, and pass a return code of 0 or 4 to JES2. JES2 can then process the remainder of the statement as a standard JES2 control statement.
When passing a return code of 12 or 16, it is also possible for your exit routine to pass an error message to JES2 for display at the operator's console. To send an error message, generate the message text in your exit routine, move it to the area pointed to by X054JXWR, and set the X054XSEM bit in X054RESP to one.
If you intend to use this exit to affect the JCT, your exit routine must ensure the existence of the JCT on receiving control. If the JCT has not been created when your exit routine receives control, the pointer to X054JXWR is zero. For example, when your exit routine receives control for a /*PRIORITY statement, the JCT doesn't exist yet. In this case, your routine must store any data to be placed in the JCT until JES2 creates the JCT.
Your exit routine does not have access to the previous control card image. You should take this into account when devising your algorithm.
An 80-byte work area, pointed to by X054JXWR, is available for use by your exit routine. If your routine requires additional work space, use the $GETMAIN macro to obtain storage (and the $FREMAIN macro to return it to the system when your routine has completed).
Exit 54 can use field JCTIPRIO to force a priority for a job subject to the limitations of the input device's priority increment and priority limit values. When exit 54 receives control, a value of C'*' in JCTIPRIO indicates a priority has not been forced by an exit routine. If you want to force a priority in exit 54, set JCTIPRIO to a value between 0 and 15 in the low-order four bits on the field.
Note: Whether you can set field JCTIPRIO and the allowable values depend on the specific exit.
When this exit adds or modifies cards, whether the change is sent over NJE (including SPOOL offload) depends on the statement type and the setting of option flags in the $XPL or $RJCB. Modified JECL cards (original and modified card are both JECL) are not sent over NJE. By default, all other changes are sent over NJE. To limit changes to only the local node, you can set the X054RLOC in the XPL (affects the current card) or set the RJCB3LOC bit in any RJCBs that are added.
Accessing $NITs
The $NIT macro defines the characteristics of NJE nodes. The $NITs are arranged in a table that is indexed by the node number. The table of $NITs is in JES2 private storage and shadowed in a data space for use outside the JES2 address space. Installation exits can use three fields in the $NJEWORK work area to access the $NIT table. Installation exits can use these fields to access a $NIT without regard for what address space they are in.

Because these fields are in the $NJEWORK data area, you can address them using the ‘NJE’ prefix or the prefix for the device dependent work area in which the $NJEWORK is embedded. Therefore, you can address NJENITAD as JRWNITAD in the $JRW.
The following code accesses the origin node’s NIT in an NJE JOB receiver exit:
```
 USING NIT,R1               Est NIT addressability
 SPACE 1
$ARMODE ON,SYSSTATE=SET,INIT=CCTZEROS Enter AR mode
 SPACE 1
 LLGH  R1,JRWRDNOD          Get origin node number
 MH    R1,CCTNITSZ          Get NIT offset
 AL    R1,JRWNITBL          Get NIT address
 LAM   AR1,AR1,JRWNITAL     Get NIT ALET
```
Determining the device type
Most exits need to determine the type of device that they are being called under. The $NJEWORK area has copies of $DCT fields that can help identify the device. Which method you use depends on the condition that you are testing for.

The field NJEDEVTP (that corresponds to DCTDEVTP) is a one byte flag that can be used to test for classes of devices. A test of the DCTNET bit in NJEDEVTP indicates that the exit is being called under a networking device. A compare of the byte to DCTINR indicates that the exit is being called under an internal reader. See the $DCT for the meaning of the bits in DCTDEVTP.

NJEDEVID corresponds to DCTDEVID. This is a 3 byte value that can uniquely identify a device. This is more often used when knowing what specific device you are running under. See the $DCT for the meaning of the fields.
Do not issue a $GETMAIN storage request for subpool 0 (the default for $GETMAIN), or for subpool 240 or 250, which are translated to subpool 0 for authorized callers. Doing so would establish subpool 0 with an assigned key of 0, which can cause problems for a job step application that shares subpool 0 and requests subpool 0 storage, thereby obtaining the storage in key 0. To avoid this issue the exit should issue a $GETMAIN request for subpool 229 or 230, which are high private subpools intended for use by authorized functions, whereas subpools 0-127 are in low private subpools and are part of the user region.