TSO

The order of information for OS/390 is: TSO, ISPF, native OS/390, and CICS.

Authority to operate in batch mode (TSO)

To submit a batch job, you need to know what QMF and DB2 authority is needed.

How to determine the logon ID and DB2 primary authorization ID your job is running under:

• If your installation uses RACF, the logon ID is the value of the USER parameter on your JOB statement. The DB2 primary authorization ID is the one corresponding to that logon ID.
• If your installation does not use RACF, the logon ID and primary authorization ID are determined as described in The PROFILE PREFIX statement.

The logon ID and authorization ID play the same role as when you use QMF interactively. As a result, the procedure runs only if the following conditions are satisfied:

• You can operate QMF interactively using the logon ID for the batch run.
• The authorization ID corresponding to the logon ID owns the procedure to be run, or that procedure is shared.

In running the procedure's commands, the authorization ID works interactively. However, not every QMF command that can be run interactively can be run in batch mode. For more information about which commands are appropriate for the batch environment, see Using QMF

Users with authority to use QMF interactively, and who can run jobs in the background, can also use it in batch mode, while users who do not have authority cannot use it in batch mode.

RACF security considerations

If RACF is a part of your security, you can prevent users from running jobs under other users' logon IDs. A user who runs such a job can access all the DB2 data that the other user has access to, including data that the user running the job is not authorized to see.

Sending a job to OS/390 using the TSO SUBMIT command

You or your users must create the QMF procedure to be run and save it in the database. The procedure might issue queries or run other procedures and might run most other QMF commands. Through the TSO command of QMF, the procedure might also call CLISTs or online programs. For more information on writing procedures for batch, see Using QMF

After you save the procedure, you or your users must create a JCL file for the job that runs the procedure. The JCL for this job calls TSO for batch operations. It must allocate resources that TSO and QMF need, including a data set containing statements that TSO is to run. One of these statements must start a QMF session.

Submit the job to the background through the TSO SUBMIT command. SUBMIT is one of the FIB (foreground-initiated background) commands through which the user runs, monitors, and manipulates background jobs. Issuing a FIB command requires the proper TSO authority. (Granting this authority is a TSO administration task.) For more on FIB commands and their uses, see TSO Extensions Command Language Reference

The SUBMIT command can be run:

• During the user's QMF session by using the TSO command of QMF
• In TSO READY mode or in a CLIST that tailors the JCL of the job

The tailoring can be based on parameters whose values are passed to called CLIST.

Any error encountered while running a procedure can:

• Terminate the procedure
• Back out an uncommitted DB2 unit of recovery

The JOB statement for the job can specify that a message be sent to the user when the job is done. The message appears on the user's screen. The user need not end a QMF session to receive the message.

After the run is ended, the user can examine the printer output for errors. With the proper JCL, this output is routed to data sets that the user can examine with an editor. One of these data sets might contain a record of the confirmation and error messages and, if desired, a record of the QMF commands that have run.

JCL to execute a QMF batch job under TSO

Batch-job JCL is similar to a TSO logon JCL, because QMF is run in batch mode through batch-mode TSO. The JCL statements you can use in batch mode are discussed in this section.

The job statement

Begin your JCL with a JOB statement like this:

//BATCH   JOB  USER=LMN,PASSWORD=ABC,NOTIFY=LMN

The statement shown might not be adequate for every installation, because it contains neither accounting information nor the user's name. The operands shown specify that:

• The logon ID is LMN.
• The logon password is ABC.
• The terminal message is sent to user LMN when the job ends.

You can include other operands; among these are the MSGLEVEL and MSGCLASS operands that control the level of detail and the routing of the JCL and system messages.

The exec statement

You can use an exec statement for a JOB step to run batch-mode QMF similar to the following:

//SAMPLE  EXEC PGM=IKJEFT01,TIME=1440,DYNAMNBR=30,REGION=3072K

This statement:

• Calls TSO (PGM=IKJEFT01)
• Specifies an adequate number of allowable dynamic allocations (DYNAMNBR=30)
• Specifies a sufficiently large region for QMF (REGION=3072K)

The DD statements

You can use the same DD statements both for running QMF interactively and for batch mode. You must remove the statements for SYSPRINT, SYSTERM, and SYSIN.

You can add the operand HOLD=YES to one or more of the SYSOUT DD statements and then manipulate their output with the OUTPUT command of TSO (another FIB command). Using the OUTPUT command, you can route the output of the SYSOUT DD statement to your screen.

You also need DD statements for the SYSTSPRT and SYSTSIN data sets.

SYSTSPRT

This data set contains the message output from TSO and ISPF. For this data set write:

//SYSTSPRT DD SYSOUT=A

SYSTSIN

SYSTSIN holds the TSO statements that run during the job step. To include these statements in your JCL, write the following:

//SYSTSIN DD *
   EXEC CLISTA
   PROFILE PREFIX(LMN)
   ISPSTART PGM(DSQQMFE) NEWAPPL(DSQE) PARM(DSQSMODE=B,DSQSRUN=LMN.PROCA)
   
·
·
·

/*

TSO runs these statements in their order of appearance in SYSTSIN:

• The first statement runs a CLIST named CLISTA, which might do allocations of QMF libraries.
• The second sets the user's dsname prefix to LMN.
• The ISPSTART statement invokes batch-mode QMF with ISPF and runs the procedure LMN.PROCA.

The PROFILE PREFIX statement

The PROFILE PREFIX statement sets the user's dsname prefix to LMN, which is assumed in the example to be the user's logon ID.

Where to place the statement

Place the PROFILE PREFIX statement before the first ISPSTART statement that starts QMF. Issuing the PROFILE PREFIX statement within QMF is ineffective.

How PROFILE PREFIX can change a profile:

By itself, the QMF SET PROFILE command makes no permanent changes to the user's QMF profile. In contrast, the PROFILE PREFIX statement can make permanent changes to the user's TSO profile, depending on your installation's setup. If it does, a user might want to restore the dsname prefix. The initial value of the prefix setting is in the ISPF system variable ZPREFIX.

Making the PROFILE PREFIX effective

For the PROFILE PREFIX statement to be effective, the DSQSPRID parameter must be set to TSOID. A similar statement (one setting the user's prefix to the user's logon ID) might be needed in other jobs running QMF in batch mode for the following reasons:

• To identify the user to QMF when RACF is not used

  At installations where RACF is not used, QMF assumes that the user's logon ID is equal to the user's dsname prefix; if this prefix is null, QMF assumes that the logon ID is BATCH. Thus, by setting the dsname prefix to the user's logon ID, the PROFILE PREFIX statement provides the user's logon ID to QMF.

  The primary authorization ID that DB2 assigns the user in this case is the value specified by the DB2 installation parameter UNKNOWN AUTHID. The logon ID is used in trace output recorded in the DSQDEBUG data set. Either the primary authorization ID or the logon ID is used for reading from the profile and assigning a default resource group, depending on the setting of the DSQSPRID parameter. See the discussion of this parameter in Customizing Your Start Procedure.

• To avoid problems with data set names

  You can encounter problems when a QMF procedure uses both the fully qualified and the incomplete forms of a data set's name in the QMF IMPORT/EXPORT commands. For example, a procedure running under the logon ID LMN issues the following two commands:

  EXPORT QUERY TO 'LMN.QUERYX.QUERY'
   .             .            .
  IMPORT QUERY FROM QUERYX

  The EXPORT command uses the logon ID (LMN) as the first qualifier for the export file name. Later, the IMPORT command imports this file.

  If the user's dsname prefix is ABC instead of LMN, the file referenced in the IMPORT statement is named 'ABC.QUERYX.QUERY' instead of 'LMN.QUERYX.QUERY'. This is because the prefix is used for the first qualifier of a data set name when, as in the example IMPORT command, the name is not fully qualified.

  The procedure cannot find the file it previously exported. The PROFILE PREFIX statement avoids this problem by setting the dsname prefix to the user's logon ID (in this case, 'LMN').

Running QMF batch in the foreground using TSO or ISPF

To start QMF in batch mode in the foreground, you can use any of the methods to start QMF that were discussed in Starting QMF. For example, from the TSO READY mode, you can issue the following statement to start QMF from a CLIST:

ISPSTART CMD(clist__name) NEWAPPL

where clist_name is the name of the CLIST that starts QMF. This CLIST must contain a statement of the form:

ISPEXEC SELECT PGM(DSQQMFE) NEWAPPL(DSQE)
                     PARM(...DSQSMODE=B,DSQSRUN=aaa.bbb)

Here the ISPSTART statement runs in the foreground, not the background. You cannot do other things with TSO while waiting for the CLIST to end.

When the CLIST actually ends, you are back in TSO READY mode. Before the CLIST ends, you might see a display of the ISPF Disposition Prompt panel if your procedure terminates before you specify permanent disposition parameters for the TSO console, log, and list files. To avoid displaying this panel, specify permanent disposition parameters for these files. A value of D (specifying "delete") for each is probably adequate. If you do not know how to specify these dispositions, ask an ISPF expert or use ISPF help.

Debugging a procedure

You can use the trace codes and the HELP command to diagnose problems with a batch mode procedure. In fact, L2 tracing is the default for procedures run in batch mode. To change the trace setting, you need a SET command in your procedure. For example, to specify L1 tracing instead of L2, add the following statement at the start of the procedure:

SET PROFILE (TRACE=L1

With either L1 or L2 tracing, a log is produced in the DSQDEBUG data set. Within this log is a series of message records: one for each message that QMF issued while the procedure was being run.

With L2 tracing in effect, the log also contains a record for each QMF command run by the procedure (and its subordinates).

If the procedure terminates prematurely, an error message is written to the DSQDEBUG data set. You can then use the HELP command to display the corresponding message help panel.