IX.2 JCL Considerations

GBAT makes calls to the Geosupport System via Geosupport’s standard API in the same manner as is done by any user-written batch Geosupport application program. To execute GBAT, the user sets up a batch job that invokes a catalogued procedure called GBAT2, which contains all the JCL necessary to support the Geosupport calls. This ‘proc’ consists of a single step, the stepname of which is also GBAT2. It contains an EXEC statement that executes the GBAT program and a STEPLIB DD statement specifying the program library containing the GBAT and Geosupport load modules. The user must add DD statements to the GBAT execution step for GBAT’s own input and output files. Those files, and their required DDnames, are as follows:

  • Input data file, DDname INFILE or INVSAM. Mandatory. Contains the user’s geographic information to be processed. Discussed in Chapter IX.4.

  • Input control file, DDname CARDIN. Mandatory. Contains encoded information that describes the use’s input data file and specifies GBAT processing options. Discussed in Chapter IX.5.

  • Input alias file, DDname ALIASES. Optional. Allowable if the function being executed accepts street name input. Contains user-defined street name aliases (alternative names and spelling variants) that GBAT is to use to supplement the street names recognized by Geosupport. Discussed in Chapter IX.6.

  • Output file of accepted data, DDname OUTFILE. Optional. Contains one record corresponding to each input data record that is accepted by Geosupport. The record consists of an exact copy of the input data record, followed by data obtained from Geosupport. Discussed in Chapter IX.7.

  • Output file of rejected data, DDname ERRFILE. Mandatory (except when WORKAREA1=YES). Contains one record corresponding to each input data record that is rejected by Geosupport. The record consists of the Geosupport Return Code and Reason Code, followed by an exact copy of the input data record. Discussed in Chapter IX.8.

  • Output file of rejected data, DDname ERRFIL2. Mandatory when RECTYPE=1B and WORKAREA1=NO. Contains one record corresponding to each input data record that is rejected (or partially rejected) by Geosupport Function 1B. The record consists of the Geosupport Return Code and Reason Code for the Function 1E Extended portion of Function 1B, followed by the Geosupport Return Code and Reason Code from the 1A Extended portion of Function 1B, followed by an exact copy of the input data record. Discussed in Chapter IX.8.

  • Output file of rejected data, DDname ERRFIL3. Mandatory when RECTYPE=2 and RELATEDNODES=YES. Contains one record corresponding to each input data record that is rejected by Geosupport with GRC 03 Reason Code B (many-node case). The record consists of the Geosupport Return Code and Reason Code, followed by an exact copy of the input data record, followed by the information needed to choose a node. Discussed in Chapter IX.8.

  • Output file of rejected data, DDname ERRFIL4. Mandatory when WORKAREA1=YES. Contains one record corresponding to each input data record that is rejected by Geosupport. The record consists of the Geosupport Return Code and Reason Code, followed by an exact copy of the input data record, followed by a copy of Work Area 1. Discussed in Chapter IX.8.

  • Output file of rejected data, DDname ERRFIL5. Mandatory when RECTYPE=1B and WORKAREA1=YES. Contains one record corresponding to each input data record that is rejected (or partially rejected) by Geosupport Function 1B. The record consists of the Geosupport Return Code and Reason Code for the Function 1E Extended portion of Function 1B, followed by the Geosupport Return Code and Reason Code from the 1A Extended portion of Function 1B, followed by an exact copy of the input data record, followed by a copy of Work Area 1. Discussed in Chapter IX.8.

  • Output print file, DDname SYSPRINT. Mandatory. Contains GBAT messages and summary run statistics. Discussed in Chapter IX.9.

Some of the GBAT files, e.g. the input alias file and the output file of accepted data, are optional. GBAT opens these files only if there are certain entries in the control file specifying their use. If an optional file is not used, a DD statement for that file need not be included in the JCL. However, including such a DD statement causes no harm, unless the file it refers to does not exist, which would cause a JCL error.

In the course of execution, certain conditions (described in Chapter IX.3) may arise that cause GBAT to terminate abnormally. In all cases in which GBAT exits via a programmed abnormal termination, it issues a Condition Code11 of 12 or greater, and it produces incomplete or no output files. If the user’s job contains any steps following the GBAT execution step (the step that invokes the GBAT2 proc) that are dependent on the existence of the output files that GBAT is expected to create, it is advisable to code the COND parameter in the EXEC statements of those steps so that those steps are bypassed if the Condition Code issued by the GBAT execution step is 12 or greater. For example, if GBATSTEP is the stepname of the GBAT execution step, then coding COND=(12,LE,GBATSTEP.GBAT2) in the EXEC statement of a subsequent step will cause that step to be bypassed if 12 is less than or equal to the Condition Code of GBATSTEP.

_________________________

11 Each step of a batch job running on an IBM mainframe can issue a Condition Code upon termination of the step. By convention, a Condition Code of ‘00’ indicates normal completion of the step, ‘04’ indicates generally normal completion but with a minor condition warranting a warning and higher values indicate severe problems or errors causing abnormal termination. Condition Codes appear in the SYSPRINT output job log. A JCL parameter, COND, can be coded in the EXEC statement of any job step to cause that step to be bypassed if the Condition Code of a specified previous step satisfies a specified condition.

Note: Condition Codes are sometimes called ‘Return Codes’, in IBM documentation and elsewhere. Condition Codes are not to be confused with Geosupport Return Codes (GRCs). The Condition Codes discussed in this chapter are issued by the GBAT program, appear in the output job log and can be tested by the COND JCL parameter. GRCs are issued by the Geosupport System and are returned to the calling application (including to GBAT) in Work Area 1; they do not appear in the output job log and are not accessible to COND. GBAT does include the GRC in each record it writes into the output file of rejected data (discussed in Chapter IX.8).