Single system launcher setup

Edit online

2.1.0+

Each job that invokes a performance analysis is controlled by the IBM® watsonx Code Assistant for Z Code Optimization Advice launcher. The main launcher program is a single system launcher that consists of two files: the JCL that invokes the launcher (CQIINITJ) and a REXX program that is invoked by the JCL (CQIINIT).

JCL invocation file (CQIINITJ)

CQIINITJ is the provided sample JCL that is used for invoking the launcher's REXX program. The sample CQIINITJ JCL file is provided in the z/OS host installation package for Z Code Optimization Advice. After installation, it will be located in the IBM watsonx Code Assistant for Z Code Optimization Advice sample library, <HLQ>.SCQIJCL, where <HLQ> was the prefix used for the target libraries in during installation. Contact your system programmer for information on where the z/OS host component was installed.

Note: 2.5.0+
Some settings have changed from previous versions. The OUTPUT parameter replaces the JSON parameter.

The following input parameters must be specified in this JCL.

Table 1. CQIINITJ input parameters
Parameter name Example from file Description
JCLNAME // SET JCLNAME=hlq.JCL.LIB(COBJCL) Name of the sequential file or PDS(E) member that contains the JCL to run the main COBOL program in your application.
PGMNAME // SET PGMNAME=pgmname Name of the main COBOL program in your application that gets run directly from the JCL in JCLNAME.
COA // SET COA=hlq.coa.loadlib Data set name of the Z Code Optimization Advice load library.
EXE // SET EXE=hlq.cqiinit.location Data set name where the REXX program (CQIINIT) is located.
PROCNAME // SET PROCNAME=N

Name of the sequential file or library member that contains the cataloged procedure that executes the PGMNAME program. If there is a chain of nested procedures, the one to specify is the cataloged procedure that contains the EXEC PGM=PGMNAME card specified explicitly.

A setting of N is the default when there is no cataloged procedure involvement in the PGMNAME program execution.
LISTING // SET LISTING=N hlq.listing[(member)]

Name of the PDS(E) that contains the listings for all programs in your application. If you are only analyzing one program, specify a member name if the member name of your LISTING file is not PGMNAME. If you are analyzing multiple programs, the program name is used as a member name and you must specify a PDS(E) without a member name. If you have listings in multiple data sets or if you have multiple non-nested programs in a source file, use CONFIG instead.

A setting of N is the default when no data set for listings is provided.

Note: If the COBOL program is compiled with the SMARTBIN or SMARTBIN(NAMES) compiler option in Enterprise COBOL 6.4 or 6.5, the LISTING files are not required as inputs to the analysis engine.
ADATA // SET ADATA=hlq.adata(member) hlq.adata[(member)]

Name of the PDS(E) that contains the ADATA files for all programs in your application. If you are only analyzing one program, specify a member name if the member name of your ADATA file is not PGMNAME. If you are analyzing multiple programs, the program name is used as a member name and you must specify a PDS(E) without a member name. If you have ADATA files in multiple data sets or if you have multiple non-nested programs in a source file, use CONFIG instead.

A setting of N is the default when no data set for ADATA files is provided.
CONFIG // SET CONFIG=hlq.coa.config.file Name of the configuration file that specifies the ADATA files and listings for the programs in your application. The CONFIG parameter cannot be used in conjunction with the ADATA or LISTING parameters.

A setting of N is the default when no CONFIG file is provided.
PROF // SET PROF=hlq.sysprofd(member) hlq.profiling.dataset[(member)]

Name of the PDS(E) (with or without member name) where the profiling report for your application will be generated. The profiling report will be automatically copied to the OUTPUT file specified. If the member name is omitted, PGMNAME is used as the member name.
2.5.0+
OUTPUT		 2.5.0+
// SET OUTPUT=hlq.coa.output		 2.5.0+
hlq.output.dataset[(member)]

Name of the PDS(E) where the members containing the analysis results will be generated.
ENTRY // SET ENTRY=N The main entry point name of the PGMNAME program. Must be provided only if it differs from the entry name determined by the binder.

A setting of N is a default when no entry is provided.

APPNAME // SET APPNAME=N Name of the application to be associated with the COBOL program specified with PGMNAME. This name is logical and can be any value compliant with the definition rules for JCL symbolic variables. A setting of N defaults APPNAME equal to the provided PGMNAME.
JOBNAME // SET JOBNAME=USERID Name of the job to be submitted by the launcher.

A setting of USERID defaults the job name to the username appended with character 1.

HLQ // SET HLQ=USERID Name of a temporary data set high-level qualifier.

A setting of USERID defaults it to the username.
Notes:
  • After submitting the CQIINITJ job, it will automatically build JCL and submit an additional launcher-modified job with the following job name format:
    • When JOBNAME=USERID is specified, then the jon name format is userid1.

      For example, if the user ID is COAEVAL, the generated job name is COAEVAL1.

    • When JOBNAME is equal to something other than USERID, then the job name is what that explicitly specified value is.
  • When the PROCNAME parameter is specified and it points to the cataloged procedure location, then the procedure is copied into the launcher-modified JCL as an in-stream procedure.
  • The Z Code Optimization Advice launcher REXX program CQIINIT in hlq.cqiinit.location will submit the modified job to automatically profile and run the program PGMNAME in the original application JCL at hlq.JCL.LIB(COBJCL). Then, it will execute Z Code Optimization Advice for the PGMNAME program using the Z Code Optimization Advice load library at hlq.coa.loadlib and generate the hlq.coa.output file in JSON format.
  • The ENTRY parameter will usually be set to N to allow binder detecting of the default entry point. If the Z Code Optimization Advice invocation fails (confirmed with checking the generated logs), try to detect and specify the correct main entry point name with the ENTRY parameter and rerun the CQIINITJ job.
  • Refer to data set allocation sample CQIALC for information on settings needed for the various data sets used by CQIINITJ.

REXX program (CQIINIT)

CQIINIT is the REXX program that is invoked by the sample job CQIINITJ.

The CQIINITJ job automatically builds the JCL and submits one job with the job name format of userid. This job is a modified version of your original JCL to enable profiling and automatically invoke the execution.

If the PROCNAME parameter is specified and it points to the cataloged procedure location, then the procedure is copied into the modified job JCL as an in-stream procedure.

If the CQIINITJ job fails, refer to the SYSTSPRT file for error messages. Refer to Error messages for the JCL invocation file for a list of possible messages.

If the launcher-modified job fails, refer to the CQILOG and CQIERR files for the Z Code Optimization Advice error messages. Refer to Launcher messages in the JOBLOG for a list of possible messages.

For more information refer to Limitations and requirements of the launcher.

Error messages for the JCL invocation file

If the JCL invocation file is incomplete or contains invalid parameter values, a job failure occurs with the return code 8 and the SYSTSPRT log file will contain at least one error message, indicating the reason for failure.

All error messages in the SYSTSPRT log file will be from the launcher-modified job, unless otherwise indicated.
Table 2. JCL invocation error messages in SYSTSPRT
Error Description and resolution
*** Error: no JOB card provided in jclname

The JCLNAME parameter

*** Error: no EXEC card provided in jclname The JCLNAME parameter
*** Error: no step with PGM=pgmname located in jclname The JCLNAME parameter
*** Error: no step with PGM=pgmname located in jclname and procname  
*** Error: invalid data set dsname  
*** Error: data set dsname could not be found  
*** Error: no ENTRY provided  
*** Error: N is required for deafult  

Limitations and requirements of the launcher

2.6.0+

The launcher program has some limitations and requirements on the types and format of JCL it can process and the application environments where it can operate.

  1. The launcher uses the same system and hardware requirements as Z Code Optimization Advice.
  2. The launcher does not support IBM CICS or IMS applications.
  3. The COBOL program specified by the pgmname variable, as well as any other COBOL program implicitly called, must be in the STEPLIB or JOBLIB data set concatenation for it to be available for launcher program processing.

    If a module is not found in the STEPLIB or JOBLIB, but still found in the LINKLIST or any other system library, then the launcher program will continue. If the module is not found at all then ABEND 806 will be generated.

    User response: Add the missing data set(s) containing all modules required for the application to the STEPLIB or JOBLIB concatenation.

  4. The target COBOL program name provided in the original JCL with ‘PGM=’ parameter cannot be a variable. For example, //STEP1 EXEC PGM=&pgm or PGM=%pgm are not allowed.

    If a variable name is used in the ‘PGM=’ field, or there is no step with the specified COBOL program name pgmname found in the original JCL, the CQIINITJ job fails with return code 8 and an error message is generated.

    This error can occur if your JCL contains cataloged JCL procedures call but parameter PROCNAME=N was used in your CQIINITJ configuration. This error can also happen if the PROCNAME=hlq.lib(procname) specified in your CQIINITJ configuration points to a cataloged procedure that has no ‘EXEC PGM=pgmname’ card specified explicitly but has a nested cataloged procedure call instead.

    Message: *** Error: no step with PGM=pgmname located in jclname [and procname]

    User response: Correct the JCL so a variable is not used for the program name. If your JCL contains cataloged JCL procedures call, then configure the CQIINITJ parameter PROCNAME to point to the sequential file or library member that contains the cataloged procedure that executes the pgmname program. If there is a chain of nested procedures, the one to specify is the cataloged procedure that contains the ‘EXEC PGM=pgmname’ card specified explicitly.

  5. The TSO user invoking the Z Code Optimization Advice launcher program must be authorized to use the TSO SUBMIT command. If not, then the tool’s use of this command will fail, and the CQIINITJ job will fail with return code 8 and an error message generated.

    Message: *** Error: TSO SUBMIT command failure

    User response: Obtain TSO user authorization for using TSO SUBMIT.

  6. The STEPLIB JCL card must be present in the target step (Step 4) of the original JCL, unless the JOBLIB card is present in the original JCL. If no STEPLIB or JOBLIB card is found, then the CQIINITJ job fails with return code 8 and an error message is generated.

    Message: *** Error: no STEPLIB provided for stepname step in jclname

    User response: Add the required STEPLIB card to the JCL.

  7. The data sets that CQIINITJ uses need to be configured correctly. Use the data set allocation sample (CQIALC) to help allocate the data sets for CQIINITJ.