PJS Installation - PJS Exits

4. PJS Exits

One of the optional installation subtasks in Chapter 2 enables you to modify PJS user exits so that PJS meets site requirements. The following exits will be discussed:

Module Name	Module Description (Relevant Section)
PJSIDFX	PJS Installation Data Format Exit (Section 4.1)
PJSOPTX	PJS Options Exit (Section 4.2)
PJSSECX	PJS Security Exit (Section 4.3)
PJSSUBX	PJS Submit Exit (Section 4.4

The PJS Installation Data Format Exit enables you to format the Installation Data Area from a PJS Job Request Record for display.

The PJS Options Exit enables you to dynamically set options at installation time.

The PJS Security Exit enables you to define and establish access control to PJS request records.

The PJS Submit Exit enables you to automatically modify JCL submitted through PJS and, if needed, to suppress the job.

The default exits perform no significant actions and have no adverse side effects. Even if you do not intend to modify any of these exits, we recommend that you read about them. Please pay particular attention to the section on the PJS Security Exit (PJSSECX); this section and Chapter 5 both contain a great deal of information on PJS site security issues.

Several sample exits are provided in the PJSSAMP library. Each exit is documented in the comments at the start of the program source.

4.1 The PJS Installation Data Format Exit (PJSIDFX)

PJSIDFX is an exit routine that enables the installation to format the data in the installation data area of a PJS Job Request Record for display. For an example of how this information can be displayed, please refer to Chapter 3 in the Personal Job Scheduler (PJS) User Guide. This exit will be called by the PJS TSO command processors and the PJS ISPF interface when a job request record is formatted for display.

The PJSIDFX module must be link‑edited with the RENT, AMODE=31, and RMODE=ANY attributes specified. The load module should be placed into the PJSLINK library.

The PJSIDFX exit is called using standard IBM linkage conventions. Register 15 will point to the program entry point address. The exit should return to the address passed in register 14. Register 13 will point to a 72‑byte save area into which the exit should save the caller's registers. On return, the caller's registers (except register 15, which is set to the return code) must be restored.

4.1.1 PJSIDFX Input Parameters

Parm 1 ‑ Address of the PJSVT (PJS Vector Table)

Parm 2 ‑ Address of the PJS Job Request Record being formatted

Parm 3 ‑ Address of the area in which the exit is to place the formatted data

If the Input PJS Job Request Record address (Parm 2) is zero, the exit should place a heading for the installation data into the Formatted Installation Data Area (Parm 3). If the input PJS Job Request Record address (Parm 2) is non-zero, the exit should place the formatted installation data for the record into the Formatted Installation Data Area (Parm 3). The PJS Job Request Record must not be changed by the exit. For more information on the PJS Vector Table and the Job Request Record, please refer to Appendix B.

The format of the Formatted Installation Data Area is:

Bytes 0 ‑ 1 Length of text area (set by calling program)

Bytes 2 ‑ 3 Length of formatted text (to be set by the exit)

Bytes 4 ‑ n Text area

The first length is the length of the text area (not including the length fields) and is set by the calling program. The second length is the actual length of the formatted text, and is to be set by this routine. The formatted text length should generally be set to the same length for the heading and all data lines, since this length is used to determine break points for multi‑line data and scroll lengths for the ISPF List Job Request dialog.

4.1.2 PJSIDFX Return Codes

On return, register 15 should be set to a return code of zero.

4.2 The PJS Installation Options Exit (PJSOPTX)

PJSOPTX is an exit routine that enables the installation to dynamically set installations options at execution time. For example, this exit can enable you to run multiple copies of PJS in some specialized environments.

This exit will be called by the PJS routines when the PJS Installation Options Module is loaded. The information in the options module is copied into the PJS Vector Table (PJSVT) and the exit called. The exit can then test any system control blocks available to it to change the installation options as desired.

The PJSOPTX module must be link‑edited with the RENT, AMODE=31, and RMODE=ANY attributes specified. The load module should be placed into the PJSLINK library.

The PJSOPTX exit is called using standard IBM linkage conventions. Register 15 will point to the program entry point address. The exit should return to the address passed in register 14. Register 13 will point to a 72‑byte save area into which the exit should save the caller's registers. On return, the caller's registers (except register 15, which is set to the return code) must be restored.

4.2.1 PJSOPTX Input Parameters

Parm 1 ‑ Address of the PJSVT (PJS Vector Table)

For more information on the PJS Vector Table, please refer to Appendix B.

4.2.2 PJSOPTX Return Codes

On return, register 15 should be set to a return code of zero.

4.3 The PJS Installation Security Exit (PJSSECX)

Note: For more information on PJS security issues, please refer to Chapter 5.

PJSSECX is an exit routine that enables the installation to secure the PJS Request Queue and provide access control to the PJS functions and the request records. This exit will be called by several of the PJS programs at strategic points that can enable the installation to provide complete security. The specific calling point is identified by the function code parameter.

It is recommended that some type of security exit be written. The default exit will always approve all requests ‑ it provides no security.

The PJSSECX module must be link‑edited with the RENT, AMODE=31, and RMODE=ANY attributes specified. The load module should be placed into the PJSLINK library.

The PJSSECX exit is called using standard IBM linkage conventions. Register 15 will point to the program entry point address. The exit should return to the address passed in register 14. Register 13 will point to a 72‑byte save area into which the exit should save the caller's registers. On return, the caller's registers (except register 15, which is set to the return code) must be restored.

4.3.1 PJSSECX Input Parameters

Parm 1 ‑ Pointer to a 1‑byte function code. This will contain one of the following values:

Parm 2 ‑ Address of the PJSVT

The following parameter is passed for function codes X'41', X'42', X'81', X'82', X'83', X'84', and X'F1':

Parm 3 ‑ Address of the PJSQ Job Request Record

The following parameter is passed for function codes X'91', X'92', X'93', and X'94':

Parm 3 ‑ Address of the PJSQ Calendar Record

The following parameter is passed for function codes X'A1', X'A2', X'A3', and X'A4':

Parm 3 ‑ Address of the PJSQ Event Record

The following parameters are passed for function code X'41':

Parm 3 ‑ Address of 44‑byte Data Set Name

Parm 4 ‑ Address of 8‑byte Member Name

Parm 5 ‑ Address of 6‑byte Volume Serial Number

For more information on the PJSQ Job Request record, the PJSQ Calendar record, the PJSQ Event record, and the PJS Vector Table formats, please refer to Appendix B.

4.3.2 PJSSECX Return Codes

On return, register 15 should be set to one of the following return codes:

0 Access Permitted

4 Access Denied

4.4 The PJS Installation Submit Exit (PJSSUBX)

PJSSUBX is an exit routine that enables the installation to examine and, if necessary, modify the submitted JCL or suppress the job. This exit will be called by the PJS each time a JCL image is to be passed to the internal reader.

The member ASMEXIT in the PJSINST library contains a sample job to link‑edit PJSSUBX. The PJSSECX module must be link‑edited with the RENT, AMODE=31, and RMODE=ANY attributes specified. The load module should be placed into the PJSLINK library.

The PJSSUBX exit is called using standard IBM linkage conventions. Register 15 will point to the program entry point address. The exit should return to the address passed in register 14. Register 13 will point to a 72‑byte save area into which the exit should save the caller's registers. On return, the caller's registers (except register 15, which is set to the return code) must be restored.

4.4.1 PJSSUBX Input Parameters

Parm 1 ‑ Address of the PJSVT (PJS Vector Table)

Parm 2 ‑ Address of the PJS Job Request Record being processed

Parm 3 ‑ Address of the 80‑byte JCL image last read by the system

Parm 4 ‑ Address of the 80‑byte JCL image to be inserted by the exit

After the last JCL image has been passed to the internal reader, the exit will be called with Parm 3 equal to 0 (zero). This enables the exit to add any additional JCL statements required to the end of the job by generating a return code of 4.

The JCL image area pointed to by Parm 4 is initialized to blank characters when the exit is called. The JCL image placed in the area by the exit will be used only if the return code is set to 4.

For more information on the PJS Vector Table (PJSVT) and the PJS Request Queue Entry, which contains information pertaining to the Job Request Record, please refer to Appendix B.

4.4.2 PJSSUBX Return Codes

On return, register 15 should be set to one of the following return codes:

0 Pass the JCL image pointed to by Parm 3. If Parm 3 is non‑zero, call the PJS Submit Exit again with the next JCL image; if Parm 3 is 0 (zero), the submission is complete and the exit will not be called again.

4 Insert the JCL image pointed to by Parm 4. Call the exit again with the same JCL image.

8 Delete the JCL image pointed to by Parm 3. If Parm 3 is non‑zero, call the PJS Submit Exit again with the next JCL image; if Parm 3 is 0 (zero), the submission is complete and the exit will not be called again.

12 Suppress the job submission. A /*PURGE statement will be passed to the internal reader and the exit will not be called again.

4.4.3 How to Use the PJSSUBX Exit

The PJS Installation Submit Exit can modify the JCL being submitted by using the JCL image area passed by Parm 3 and Parm 4, and by setting the return code:

· To pass an input JCL image without change, set the return code to 0 (zero).

· To modify an input JCL image before submission, change the input JCL image in the area pointed to by Parm 3, then set the return code to 0 (zero).

· To insert a JCL image before the input JCL image, place the JCL image to be inserted into the area pointed to by Parm 4, then set the return code to 4.

· To delete the JCL image before the input JCL image, set the return code to 8.

· To suppress the job submission, set the return code to 12. A /*PURGE statement will be passed to the internal reader.

The PJS Vector Table (PJSVT) contains four fullwords labelled PJSVT_USERn. The exit can use these fullwords to hold information or point to storage areas between calls to the exit. The exit must perform cleanup before it sets the return code to 0 (zero) or 4 when Parm 3 is zero, i.e., the call after the final input JCL image; it must also perform cleanup when it sets the return code to 12 to purge the job.

For more information on the PJSVT, refer to the section on the PJS Vector Table in Appendix B.