RUN subcommand (DSN)

The DSN subcommand RUN executes an application program, which can contain SQL statements.

Environment for RUN

This subcommand can be issued under the DSN command processor running in either foreground or background mode, or it can be issued by using the DB2I RUN panel.

Data sharing scope: Member

Authorization for RUN

To execute this command, you must use a privilege set of the process that includes one of the following privileges or authorities:

EXECUTE privilege on the plan
Ownership of the plan
SYSADM authority

To run an application, the plan must be enabled for your local server. Any associated packages from which you execute statements must also be enabled.

Syntax for RUN

Option descriptions for RUN

Use at least one of the two following clauses, but do not use the same clause twice.

PROGRAM ( program-name )

Identifies the program that you want to run.

CP

Directs input to the user's command processor, and causes a prompt to be issued:

ENTER
TSO COMMAND

. This is useful for running command processors and debugging programs (for example, COBTEST).

Processing the specified TSO command creates a new task control structure under which the TSO command executes. All application programs that are initiated from this TSO command session also execute under the same task structure, and must establish a new connection to Db2 if they use SQL requests.

When the TSO command completes, the new task structure is terminated, and control is returned to the original Db2 connection and task structure established by the DSN command.

Later TSO commands can be issued directly from the DSN session, or through the RUN subcommand with the CP option.

PLAN( plan-name )

Is optional after the PROGRAM option, but required after the CP option.

plan-name is the name of the application plan for the program.

When PROGRAM is used, the default plan name is program-name .

LIBRARY( library-name )

Specifies the name of the data set that contains the program to be run.

If library-name is not specified, normal z/OS® library searching is used. The data sets that are specified in the STEPLIB DD statements are first searched for the entry point name of the program. If STEPLIB is not present, the data sets that are specified in the JOBLIB DD statements are searched. If the entry point name is not found there, the link list is searched.

Subprograms: Normal z/OS library searching is always used for any subprograms that is loaded by the main program. If the subprograms reside in the same library as the main program, the library-name must also be defined for the normal z/OS search pattern (STEPLIB, JOBLIB, link list). If a library that is defined in that way contains both the main program and any loaded subprograms, you do not need to use the LIBRARY option.

PARMS( parameter-string )

parameter-string is a list of parameters that are to be passed to your application program. Separate items in the list with commas, blanks, or both, and enclose the list between apostrophes. If the list contains apostrophes, represent each apostrophe by using two consecutive apostrophes. The list is passed as a varying-length character string of 1 to 100 decimal characters.

For Assembler: Use a list of the form 'program parameters'. There are no run time parameters.

No run time or application parameter validation is performed by the RUN subcommand on the parameter-string that is passed to your application program. All specified parameter values are assumed to adhere to the parameter syntax and format criteria defined by the language in which the application program is written.

For C: Use a list of the form A/B, where A represents a list of run time options, and B represents a list of parameters for the C application program. If run time options are not needed, write the list in the form /B. If the NOEXECOPS run time option is in effect, omit the /.

For COBOL: If Language Environment® is not the run time environment, use a list of the form B/A, where B represents a list of parameters for the COBOL application program, and A represents a list of run time options. If program parameters are not needed, write the list in the form of /A.

If Language Environment is the run time environment, use a list of the form A/B, where A represents a list of run time options, and B represents a list of parameters for the COBOL application program. If run time options are not needed, write the list in the form of /B. For compatibility, Language Environment provides the CBLOPTS run time option. When CBLOPT(YES) is specified in CEEDOPT or CEEUOPT and the main routine is COBOL, specify the list in the form of B/A, the same form as when the run time environment is not Language Environment. CBLOPT(NO) is the default.

For Fortran: Use a list of the form A/B, where A represents a list of Fortran run time options and B represents a list of parameters for the Fortran application program. If Fortran run time options are not needed, write the list in the form of B or /B. The second form must be used if a slash is present within the program arguments. If only Fortran run time options are present, write the list in the form of A/.

For PL/I: Use a list of the form A/B, where A represents a list of run time options, and B represents a list of parameters for the PL/I application program. If run time options are not needed, write the list in the form /B. If the PL/I NOEXECOPS procedure option is specified, omit the /. An informational system message is issued if you omit the slash, or if the value that is passed to the PL/I run time package is not valid.

Usage note for RUN

Multitasking restriction: When running a program that uses a multitasking environment, the first task to issue an SQL statement must issue all subsequent SQL calls. That is, only one task in a multitasking environment can issue SQL calls. This task must be a subtask of, or running at the same TCB level as, the DSN main program.

Examples for RUN

Example 1: Run application program DSN8BC4. The application plan has the same name. The program is in library ' prefix .RUNLIB.LOAD'.

DSN SYSTEM (DSN)
RUN PROGRAM (DSN8BC4) LIB ('
prefix
.RUNLIB.LOAD')

Example 2: Run application program DSN8BP4. The application plan is DSN8BE81. The program is in library 'prefix.RUNLIB.LOAD'. Pass the parameter O'TOOLE to the PL/I application program with no PL/I run time options. Because O'TOOLE contains an apostrophe, you need to double that apostrophe in the PARMS parameter value.

DSN SYSTEM (DSN)
RUN PROGRAM (DSN8BP4) PLAN (DSN8BE81) -
    LIB ('prefix.RUNLIB.LOAD') PARMS ('/O''TOOLE')