Recommendations for implementing Exit 52

Exit 52 is called for each card in the job statement (the original card and all continuations). Each time the exit is called, it will pass the current card image and the statement buffer. The statement buffer includes all the operands for the JOB statement concatenated in a single buffer. For example:

//TEST JOB    (ACCOUNT),'PROGRAMMER',  COMMENT 1 
//            CLASS=A,MSGCLASS=A,      COMMENT 2 
//            USER=TEST,PASSWORD=TEST  COMMENT 3 

In this case the exit will be called 3 times, once for each card and 
will pass (on all 3 calls) the following data in the statement buffer 
(pointed to by X052STMT):

(ACCOUNT),'PROGRAMMER',CLASS=A,MSGCLASS=A,USER=TEST,PASSWORD=TEST

To alter the processing of the JOB card, the exit can:

Update the card image passed in X052CARD. This change shows up in the listing of the job.
Update the statement buffer in X052STMT 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 JOB card). If you update the statement buffer (X052STMT) in exit 52 and change the length of the buffer, you must update the field X052STME to indicate the new end of buffer (one byte past the last meaningful character).
Add additional card images to the JCL stream.

You can add card images to the JCL stream by either queuing a single RJCB or a chain of RJCBs to the XPL, or by placing a card image after the current card into the area pointed to by X052JXWR and setting X052XSNC. In either case, when a card is added, the current card is re-scanned and the statement buffer is re-built. Exit 52 is driven again for the updated statement, with X052SEC 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.

X052RJCP: Adds the card images before the first card in the current JOB statement.
X052RJCA: Adds the card images after the last card in the current JOB statement. In this case, the card(s) are assumed to not be a continuation of the current job statement and the job card is not re-scanned.
X052RJCC: 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 JOB statement, the difference between adding a card to the X052RJCA queue and the X052RJCC queue is that the first will not re-scan the job card and the second will. You can also add a single card image after the current card using the X052JXWR field. In this case, the job card will be re-scanned just as if the card was added to the X052RJCC queue. To add information to the job JCL statement:

Move a comma into the last byte of the job statement image exit 52 is currently processing. The comma indicates that additional information follows on the job statement.
Move the information you want to add to the job statement to the area pointed to by X052JXWR and set the X052XSNC bit in the X052RESP byte to one. Setting X052RESP to X052XSNC indicates that the installation has supplied an additional job statement image.
Set register 15 to X'00' or X'04' depending on whether you want to invoke additional installation exits to process the job.

You can also add an additional job level JCL statement to the job as follows:

Ensure that the job statement image that exit 52 is currently processing is the last. exit 52 is processing the last job statement image if a comma is not in the last byte of the job statement image.
Place the job-level JCL statement in the are pointed to by X052JXWR and set the X052XSNC bit in the X052RESP byte to one. Setting X052RESP to X052XSNC indicates that the installation has supplied an additional job statement image.
Set register 15 to X'00' or X'04' depending on whether you want to invoke additional installation exits to process the job.

If you want to issue messages when you cancel or purge the job:

Generate the message text in exit 52.
Move the message text to area pointed to by X052JXWR and set the X052XSEM bit in X052RESP to one. Setting X052RESP to X052XSEM indicates that the installation exit has supplied an error message that will be added to the JCL listing.
Set register 15 to X‘08’ to indicate JES2 should cancel or purge the job.

The following indicators in the XPL can assist you in adding a card image to the current job statement:

X052LOPR: Current card has the last operand in the job statement. There may be additional continued comments after the current card.
X052QUOT: 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.
X052CCMT: The current card is a continued comment. Operand added to this card or after this card will not be processed.
X052LAST: This is the last card image in the JOB statement.

To assist you in processing the operands on a statement, you can use either of the following services to parse the statement buffer passed in X004STMT:

Use the $SCAN facility to parse the operands with the standard $SCAN rules for statements. This give you the flexibility of $SCAN, but the parsing rules are not the same as normal JCL. See the $SCAN and $SCANTAB macros for additional information.
Use the RCARDSCN service and $STMTTAB macro to parse the operands with 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 access the submitting information for a job on the internal reader, you can use the following code segment:

USING JRW,R2              Est JRW addressability
USING RIDCWKAR,JRW        Est IRWD addressability
USING SJB,R3              Est SJB addressability
SPACE 1
L     R2,X05xAREA         Get JRW address
L     R3,RIDSJB           Get submitters SJB address
L     R4,SJBJCT           Get submitters JCT address

For STC and TSU INTRDRs, RIDSJB is zero because there is no submitting job in these situations.