Programming considerations

For a multiple command, this exit is taken once for each command verb.
The same command can be presented to Exit 5 on multiple members of the MAS. If the command is operating on a job executing on a different member than where the command originated, JES2 will send the command to the target system where it will be reissued. Therefore, to distinguish between the original command and a reissued command your exit must check the contents of the COMFLAG3 field of the PCE pointed to by register 13. If the CMB3INTC bit is on, the command is a reissued command.
It is recommended that one member be chosen to process the command, and ignore the command on the other members.
To preprocess a standard JES2 command, a typical exit routine would perform some type of validation checking. This validation checking would determine whether JES2 should terminate command processing or allow standard command processing to continue. You can base a validation algorithm on various factors. The fields of the command processor work area of the PCE contain extensive command-related information that can be used in validation checking. Note, however, that even if your exit routine validates a command, it is still possible for JES2 to reject the command based on its standard validation checking.
In processing your own installation-specific JES2 commands, your exit routine should perform its own validation checking to replace the functions normally performed by HASPCOME. Your routine should validate the command verb, contained in the COMVERB field of the PCE's command processor work area, with the equivalent of the command table lookup performed by HASPCOME. This check should determine whether the command has a valid installation-specific command verb and what action your exit routine should take based on the verb. Your routine should also perform console authority checking by testing the COMAUTH field, of the PCE's command processor work area, which contains the command's restriction bits. COMAUTH has the following structure:
COMS

(X'01') when on indicates that the command should be rejected unless authorized for the system.

COMD

(X'02') when on indicates that the command should be rejected unless authorized for the device.

COMJ

(X'04') when on indicates that the command should be rejected unless authorized for the job.

COMR

(X'08') when on indicates that the command should be rejected if it was entered from a remote work station.

If your routine validates the command, it can then perform the requested function, serving as the equivalent to a standard command subprocessor. If, however, your routine determines that the command is not valid, it must terminate processing for the command internally before returning control to JES2. Then, it should pass a return code (of 8, 12, or 16) to terminate standard HASPCOMM processing, with or without an accompanying message to the operator.
When issuing job-related messages, IBM® suggests that you have a $CWTO for a control line if you also specify a console area (L=area). Issue job-related messages independently from any other messages in your exit; do not include JOB= or LAST=. Because JES2 inserts the message identifier and a time stamp, your message should not exceed 16 characters.
There is only one control line for a multi-line WTO, and the remaining lines (referred to as data lines) cannot exceed 70 characters in length.

When you have issued any job-related messages, you can then issue all remaining messages. Structure your logic to reduce dependencies on whether a console area is specified. Use the following guidelines:
- Assume JES2 issues each single-line and multi-line message independently, that is, as if no console area was specified.
  - Code LAST=YES on a $CWTO for a single-line message. Keep in mind the message isn't really a single line if a console area was specified and JES2 ignores LAST=YES.
  - Code LAST=NO on the first and middle lines and LAST=YES on the last line of multi-line messages.
- If you code JOB=YES on a multi-line message, code it for each line of that message. For a single or multi-line message with JOB=YES, place the 8-character JOBID followed by a blank in the first nine characters of the message text of the first or only message line. If a console area wasn't specified, JES2 removes the JOBID from the message text, shifts the remaining text to the left, and issues a WTO with the specified JOBID. If you are issuing a multi-line message, place nine blanks at the beginning of the text of all subsequent lines.
- Observe the following line length restrictions to reduce dependencies on whether an area was specified:
  - Place only the JOBID and job name on the first line of a job-related, multi-line message and not more than 25 characters on the first line of a non-job-related, multi-line message.
  - If JOB=YES, limit the length of subsequent message lines to 61 characters.
  - If JOB=NO, limit the length of subsequent message lines to 70 characters.
See z/OS JES2 Macros for more information about the use of the $CWTO macro.
Typically, to process nonstandard operands and suboperands, you must write your exit routine to replace standard JES2 processing entirely. That is, your exit routine must process both the nonstandard operands or suboperands and the standard portion of the command, by performing the function of the standard command subprocessor. This is typically because the command verb and the accompanying operands and suboperands are interdependent; the operands and suboperands modify the action of the command verb and cannot be processed independently.
When passing a return code of 16 and issuing an exit-generated message to the operator, move the text of the message to the COMMAND field of the command processor work area in the PCE. Place the length of the message in R0. Also, be certain to issue the $STORE (R0) macro after loading the message length in R0 but before issuing the $RETURN macro because $RETURN macro destroys the contents on register 0. (When passing a return code of 12, to cause JES2 to issue the standard “OK” return message, you do not have to supply the message length in R0.)
Use the $CWTO macro instruction in this exit to communicate to the operator. If you use the $CWTO macro, you must do all the processing required by the specified command within your exit routine and provide a return code indicating that JES2 should bypass any further processing of the specified command.
If the command being processed is a reissued command (the CMB3INTC bit in the COMFLAG3 field of the PCE pointed to by register 13 is on) the message issued by $CWTO will be displayed in the system log only.

See z/OS JES2 Macros for more information about the use of the $CWTO macro.
When this exit routine operates in a networking environment, your exit must check the contents of the COMGFLG1 flag byte of the PCE pointed to by register 13. If the COMG1SSI bit is on, the current command is in subsystem independent format, and registers 5, 6, and 7 do not contain pertinent information. (Note: These subsystem-independent commands are also known as formatted commands and can be issued through $G commands.) The structure of the subsystem-independent commands is located at COSICMDA in the mapping macro $COMWORK.