COBOL exits allow you to invoke special processing at one, some, or all of the CA JCLCheck standard exit points. If the COBEXIT option is active, the COBOL exit program receives processing control at every standard exit point. You control the specific processing at each exit by including or excluding custom procedure code for each of the standard CA JCLCheck exit points.
The code structure of the COBOL exit program is critical to the proper implementation of user exits. The following COBOL code must not be altered by you, except as noted:
IDENTIFICATION DIVISION
Use any name for PROGRAM-ID.
ENVIRONMENT DIVISION
Change the SOURCE-COMPUTER and OBJECT-COMPUTER statements to match your installation, if necessary.
DATA DIVISION
The Working Storage section is constructed from copybooks. It defines the data areas for the JCL statements and the I/O function requests. Some major data division features are described here; for more in-depth documentation, see the copybook members themselves.
WORKING-STORAGE SECTION
Definitions of data areas prior to the USER-WORK-AREA must remain intact. You can insert additional field re-definitions; however, you must not change the positioning, length and PICTURE of the existing fields.
JCLCEXIT INTERFACE DATA AREA (copy member: JCLINTR)
This data area is divided into four sections, each of which handles a different data function.
These data names are preceded by the word JCLCHECK. This data area contains information returned to the exit by CA JCLCheck about the JCL statement or the CA JCLCheck-issued error statement. Query these data fields to find out what statement is being processed, where it came from (proc, instream), and if it is a special statement such as STEPCAT or JOBLIB. The step status and maximum error severity encountered are found in this area. Information regarding CA JCLCheck-issued error messages (what statement number and what type of statement caused the error message to be issued) is found here.
These data names are preceded by the words I-O-REQ- and JCLCEXIT- respectively. These areas set calling values for I/O requests to CA JCLCheck. The data fields provided for issuing your own error messages are in this area.
These data names are preceded by the word JCLCXIO-. Data are returned to this area as the result of an I/O request issued from the COBOL exit. This area also contains parameter information, the raw JCL statements, and the substituted text for the raw statements.
JOB STATEMENT INFO (copy member: JCLCJOB)
EXEC STATEMENT INFO (copy member: JCLCEXEC)
DD STATEMENT INFO (copy member: JCLCDD)
These data areas contain information about each respective type of statement. All the data available in the fields and indicators from the copybooks are available at the time of the exit, and also whenever an I/O request causes it to be restored. Other types of information, however, are only available during the exit itself. For example, on the JOB or EXEC statement, whether a REGION size was coded can always be determined, but only at the time of the exit can the value coded for the REGION parameter be retrieved. If it is necessary to retain such information, the exit program must set up data areas or files to do so.
Although you can modify information residing in the COBOL data areas, you cannot alter the JCL statements. Therefore, take care when changing any information about a statement.
DATA SET INFORMATION DATA AREA (copy member: JCLCDS)
At any point in processing, you can examine data collected about the data sets processed so far. The data set information is stored alphabetically by data set name. During JCLCHECK-DDEXIT, the data set information data area contains information about the data set on the DD statement, if there is one. The information is overlayed by the next DD statement, if that statement has a data set. It is also overlayed if an I/O request brings in data for another data set. You must use I/O requests to read forward or backward to a data set other than the current one.
USER WORK AREA (copy member: JCLCUSER)
Use this area to define any Working-Storage data fields that the COBOL exit program may require. You can specify user-defined copybooks for areas unique to the exit program. Do not modify any other copybooks that originally came with the sample COBOL exits.
LINKAGE SECTION
You must not alter the program's LINKAGE SECTION.
PROCEDURE DIVISION
Do not alter the following control paragraphs:
0000-ENTRY-AND-FINISH 1500-LOOP-TO-CXIO (first sentence only) 9900-CALL-JCLCXIO 9998-INITIATED-BY-ERROR 9999-RETURNED-BY-ERROR
You can insert installation specific procedure code in any of the following paragraphs:
1000-INITIALIZATION 2000-JOB-EXIT 3000-EXEC-EXIT 4000-DD-EXIT 5000-STEP-EXIT 6000-EOJ-EXIT 7000-ERR-EXIT 8000-EOF-EXIT
Additional paragraphs pertaining to and subordinate to these exit driver paragraphs may be inserted.
Do not alter the USING statement at the beginning of the Procedure Division. A primary rule to remember is that all communication with CA JCLCheck, such as for I/O requests, MUST be accomplished through calls to JCLCXIO, the interface module. The 9900-CALL-JCLCXIO paragraph provides this service.
A brief description of the Procedure Division paragraphs in the CAZ1XCOS program follows:
0000-ENTRY-AND-FINISH:
This paragraph drives the COBOL program. Do not alter the check for erroneous initiation of the exit, as this provides an escape route should you accidentally invoke the exit.
1000-INITIALIZATION:
Open any files and set the counters the exit program uses to zero. Initialize any counters or data fields not having a VALUE clause associated with them, if these fields are queried before being set to a value.
1500-LOOP-TO-CXIO:
This paragraph sets up the "continue with JCLCheck" call in the first sentence. Do not alter the first sentence. The next sentence contains the PERFORM statements necessary to execute the particular types of exits. Alter this sentence as required by exit processing.
2000-JOB-EXIT:
This routine contains several types of checks that may be made on the JOB statement.
It demonstrates the use of the special error message number series 996-999. Notice how the statement number field is used to ensure that the error message is associated with the statement causing the error. The code to check the password illustrates how CA JCLCheck uses the keyword I/O request to retrieve the actual value coded on a parameter at exit time. Notice how all I/O requests are issued using a PERFORM of the 9900-CALL-JCLCXIO paragraph.
3000-EXEC-EXIT:
The EXEC sample exit routines show one way to determine whether the EXEC statement is from in-stream JCL or from a procedure at exit time by checking the EXEC-PROCSTEP-NAME field. This routine shows how to issue the user-defined error messages. These messages must be added to the JCLMSG table. Notice how parameters are passed to user-defined messages.
4000-DD-EXIT:
This paragraph demonstrates how to examine data set information at exit time. In this example, all nontemporary data sets must be cataloged.
5000-STEP-EXIT:
The end-of-step example illustrates how the read-backward I/O request can be used to ensure that an installation standard is being met.
5500-STEP-EXIT:
This second end-of-step exit example demonstrates the method for fetching the raw, unaltered, JCL statements and their substituted text. In this example, the JCL statements are displayed. They may also be routed to a file or printed. Access to the raw JCL statements is available through these I/O requests:
I-O-REQ-START-AT-JOB I-O-REQ-START-AT-THIS-STEP I-O-REQ-START-AT-STEP-NAME I-O-REQ-READ-BACKWARD-STMT I-O-REQ-READ-FORWARD-STMT I-O-REQ-START-AT-STMT-NUMBER
6000-EOJ-EXIT:
This paragraph demonstrates the ability to retrieve data set information after the data set's DD exit has already been taken. The data set name is cross-checked with the data set status to determine whether the data set should be deleted.
7000-ERR-EXIT:
Altering the severity or suppressing the issuance of a CA JCLCheck error message is demonstrated in this routine. Some CA JCLCheck messages are issued with a warning level. You can suppress any messages that are not useful to your organization. However, do not suppress any error level messages issued by CA JCLCheck without careful consideration. At least one call to JCLCXIO must be made within this paragraph for the error exit to work properly.
8000-EOF-EXIT:
Close any files and perform any post-processing. After this paragraph executes, the COBOL user exit program no longer has control.
9900-CALL-JCLCXIO:
All I/O requests, and therefore, all communication with CA JCLCheck, must be done using the interface module, JCLCXIO. User-defined copybooks must be added to the USING clause in the CALL statement. Do not delete any copybooks supplied by CA from this CALL; they are interface areas required by the assembler programs for correctly passing data to the COBOL exit.
9998-INITIATED-BY-ERROR and 9999-RETURNED-BY-ERROR:
These two paragraphs offer a chance for CA JCLCheck to continue normal processing in the event that something is wrong with the invocation or the exiting of the COBOL program. They provide useful information, and can prevent CA JCLCheck from abnormally terminating. Do not delete these two routines.
User-specific processing may alter the values of fields in the JOB, EXEC DD, DATA SET information areas through the use of I/O requests. If current information is obliterated by these actions, but is necessary for proper user processing (in either the current or a later exit), it is up to your exit code to refresh current JOB, EXEC, DD, or DATA SET information by issuing the appropriate series of I/O requests to the interface module (JCLCXIO).
A user exit code should never modify the value of the field defined as JCLCHECK-FUNCTION-CODE. This data field contributes to the control of CA JCLCheck upon exit processing completion. Alteration of its value can produce erroneous results from CA JCLCheck.
A user exit process must not issue a CONTINUE-JCLCHECK I/O request (request type 0) to the interface module. This value is reserved for use by the control logic (paragraph named 1500-LOOP-TO-CXIO). Any other use of this Request Code can produce erroneous results from CA JCLCheck.
The assembler language user exit facility can be used concurrently with COBOL user exit processing. If CA JCLCheck encounters both an assembler and a COBOL user exit at any of the standard exit points, CA JCLCheck invokes the assembler exit first. Upon completion of the assembler exit processing, CA JCLCheck builds the associated interface data areas and passes control to the COBOL exit program. It is important that the assembler exit restore all registers to their content on entry to the exit. Use the $JCLRTRN macro in the assembler exit to accomplish this.
Always set the file pointer and file status. When reading backward, as well as forward, always include a check for end-of-file. When performing UNTIL condition-1, or condition-2, or condition-n, always clear these conditions before entering the PERFORM structure. For example, include these statements before the PERFORM structure:
MOVE +0 TO JCLCXIO-STMT-TYPE. MOVE +0 TO JCLCXIO-REQUEST-STATUS.
This is the PERFORM structure:
PERFORM 9900-CALL-JCLCXIO
UNTIL JCLCXIO-STMT-TYPE-EXEC
OR JCLCXIO-END-OF-FILE.
The current end-of-file is always the current statement in process by CA JCLCheck: it is not possible to read forward beyond the statement that CA JCLCheck is currently handling.
|
Copyright © 2014 CA.
All rights reserved.
|
|