RUNTSO command

You issue the RUNTSO command to start the Q.DSQQMFSP stored procedure from a CALL statement You use the RUNTSO command to pass the name of a query or procedure to run on QMF for TSO. The query or procedure that is named in this command must exist in the QMF catalog in the subsystem against which the RUNTSO command runs.

RUNTSO, returns one result set each time the following command is encountered in the procedure:

PRINT REPORT (PRINTER=' '

Classic forms are created on the basis of the returned result sets. These classic forms are generated without any additional form formats, but they can be specified in the Form design tab.

Note: Support for this command requires that the stored procedure interface to QMF for TSO be installed. Additionally, if your QMF for TSO installation does not use the default command synonyms table, Q.COMMAND_SYNONYMS, any synonym you issue must have a definition stored in the table that is named in the SYNONYMS field of the user profile. If the synonym definition is not found in this table, the command will fail. For information about installing the stored procedure interface, see the chapter “Installing the QMF stored procedure interface (TSO only)” in Installing and Managing Db2 QMF for TSO and CICS (GC19-2886-04).

Syntax

Use the following syntax to include the RUNTSO command in a procedure.

>>-RUNTSO--ObjectName--(--+---------------------------+-------->
                           |            .-=-. .-NONE-. |
                           '-TRACELEVEL-+---+-+-L2---+-'
                                              +-ALL--+
                                              '-PTF--'

>--+----------------------------------+------------------------->
   |               .-=-. .-NONE-----. |
   '-L2DESTINATION-+---+-+-DSQDEBUG-+-'

>--+------------------------------------+----------------------><
   |          .-=-.                     |
   '-LANGUAGE-+---+-'---language-id---'-'

Parameter	Description
ObjectName	Specifies the name of a QMF procedure or query that will run after QMF starts. All types of QMF queries are accepted. The procedure can be either a QMF linear procedure or a procedure with logic. The query or procedure that is named in this parameter must exist in the QMF catalog in the subsystem in which the stored procedure interface components are installed. One result set is returned if the specified object is a query; up to 21 result sets can be returned from a procedure (including trace output returned as the last result set when the TRACELEVEL parameter is L2 and the L2DESTINATION parameter is blank or null).
TRACELEVEL	Specifies the level of trace detail. Valid values include: NONE QMF trace output is not generated. This is the default trace level. L2 This option traces QMF messages and commands at the highest level of detail. The destination of the trace output depends on the L2DESTINATION setting. ALL This option traces QMF activity at the highest level of detail, including program initialization errors and other errors that might occur before the user's profile is established. Trace output is sent to the DSQDEBUG DD card. PTF This option is used to verify that the stored procedure interface is running correctly. Note: Do not use this option unless instructed to do so by an IBM® Software Support representative.
L2DESTINATION	Specifies the destination for the trace log when TRACELEVEL is set to L2. Valid values include: NONE Returns the trace output as the last result set from the stored procedure run. This is the default. DSQDEBUG Sends the trace output to the DSQDEBUG DD card.
LANGUAGE	Specifies the language in which QMF will run. This parameter can be a one-letter language identifier from the following table. The default value depends on the `DSQEC_NLFCMD_LANG` variable. For example, if `DSQEC_NLFCMD_LANG`=0 then `DSQAO_NLF_LANG` is used as the language. If DSQEC_NLFCMD_LANG=1 then `E` is used.

The following table lists the supported languages supported and the associated language identifier.

Table 1. Language-to-language identifier
National language feature	Name that QMF uses for this NLF	Language ID
English	ENGLISH	E
U/C English	UPPERCASE	U
Danish	DANSK	Q
Canadian French	FRANCAIS CANADIEN	C
French	FRANCAIS	F
German	DEUTSCH	D
Italian	ITALIANO	I
Japanese	NIHONGO	K
Korean	HANGEUL	H
Brazilian Portuguese	PORTUGUES	P
Spanish	ESPANOL	S
Swedish	SVENSKA	V
Swiss French	FRANCAIS (SUISSE)	Y
Swiss German	DEUTSCH (SCHWEIZ)	Z

Examples

The following example is of the RUNTSO command used to pass Q.STAFF query to run on QMF for TSO

RUNTSO Q.STAFF (TRACELEVEL=NONE L2DESTINATION=NONE LANGUAGE=E

The following examples show how to use the object name that contains parameters in the RUNTSO command:

Note: The STAFFPROC is the example QMF procedure that runs the Q.STAFF query.

The following example passes the parentheses as delimiters for the variable values:

RUNTSO "STAFFPROC(&NAME=('PERNAL'),&DEPT=(20),&JOB=('SALES'))" (LANGUAGE=E TRACELEVEL=L2 L2DESTINATION=NONE

The example command returns a result set containing the following row from the Q.STAFF sample table:

ID  NAME         DEPT  JOB     YEARS      SALARY        COMM 
------  ---------  ------  -----  ------  ----------  ---------- 
    20  PERNAL         20  SALES       8    18171.25      612.45

The following example passes variable values without using parentheses as delimiters:

RUNTSO "STAFFPROC(&NAME='PERNAL',&DEPT=20,&JOB='SALES')" (LANGUAGE=E TRACELEVEL=L2 L2DESTINATION=NONE

The following example passes a variable value that contains an apostrophe:

RUNTSO "STAFFPROC(&NAME='O''BRIEN',&DEPT=38,&JOB='SALES')" (LANGUAGE=E TRACELEVEL=L2 L2DESTINATION=NONE

This command returns the following row as the first result set:

ID  NAME         DEPT  JOB     YEARS      SALARY        COMM 
------  ---------  ------  -----  ------  ----------  ---------- 
    40  O'BRIEN        38  SALES       6    18006.00      846.55