DSN command (TSO)

The TSO command DSN starts a DSN session.

For a list of commands that you can issue under the TSO command DSN, see Command types and environments in Db2.

DSN subcommands

The DSN command has the following subcommands:

ABEND (DSN)	The DSN subcommand ABEND causes the DSN session to terminate with abend completion code X'04E' and reason code of X'00C50101'. Important: The ABEND subcommand is used for diagnostic purposes only, and is intended to be used only under the direction of IBM® Support. Use it only when diagnosing a problem with DSN or Db2.
BIND PACKAGE (DSN)	The DSN subcommand BIND PACKAGE builds an application package. Db2 records the description of the package in the catalog tables and saves the prepared package in the directory. BIND PACKAGE also deletes phased-out package copies.
BIND SERVICE (DSN)	The BIND SERVICE (DSN) subcommand builds an application package that represents a Db2 REST service.
BIND PLAN (DSN)	The DSN subcommand BIND PLAN builds an application plan. All Db2 programs require an application plan to allocate Db2 resources and support SQL requests made at run time.
BIND QUERY (DSN)	The DSN subcommand BIND QUERY reads the statement text, default schema, and a set of bind options from every row of DSN_USERQUERY_TABLE, and information from correlated EXPLAIN table rows. When LOOKUP(NO) is in effect, Db2 inserts the pertinent data into certain catalog tables.
DSN (TSO)	The TSO command DSN starts a DSN session.
END (DSN)	The DSN subcommand END is used to end the DSN session and return to TSO.
FREE PACKAGE (DSN)	The DSN subcommand FREE PACKAGE can be used to delete a specific version of a package, all versions of a package, or whole collections of packages.
FREE SERVICE (DSN)	The FREE SERVICE (DSN) subcommand deletes an application package that represents a Db2 REST service.
FREE PLAN (DSN)	The DSN subcommand FREE PLAN deletes application plans from Db2.
FREE QUERY (DSN)	The DSN subcommand FREE QUERY removes from certain catalog tables for one or more queries. If any of the specified queries are in the dynamic statement cache, FREE QUERY purges them from the dynamic statement cache.
FREE STABILIZED DYNAMIC QUERY subcommand (DSN)	The DSN subcommand FREE STABILIZED DYNAMIC QUERY removes from certain catalog tables one or more stabilized dynamic queries. If any of the specified queries are in the dynamic statement cache, FREE STABILIZED DYNAMIC QUERY also purges the statements from the dynamic statement cache.
DCLGEN (DECLARATIONS GENERATOR) (DSN)	The declarations generator (DCLGEN) produces an SQL DECLARE TABLE statement and a COBOL, PL/I, or C data declaration for a table or a view named in the catalog.
REBIND PACKAGE (DSN)	The DSN subcommand REBIND PACKAGE rebinds an application package when you make changes that affect the package, but have not changed the SQL statements in the program.
REBIND PLAN (DSN)	The DSN subcommand REBIND PLAN rebinds an application plan when you make changes to the attributes of the plan, such as the package list.
REBIND TRIGGER PACKAGE (DSN)	The DSN subcommand REBIND TRIGGER PACKAGE rebinds a package for a basic trigger. You can identify basic triggers by querying the SYSIBM.SYSTRIGGERS catalog table. Blank values in the SQLPL column identify basic triggers. For advanced triggers, use the REBIND PACKAGE command instead.
RUN (DSN)	The DSN subcommand RUN executes an application program, which can contain SQL statements.
SPUFI (DSN)	The DSN subcommand SPUFI executes the SQL processor using file input.

During a DSN session, you can also enter Db2 commands, except for START DB2. Db2 commands must start with a hyphen (-). For detailed descriptions of the Db2 commands, see the commands with names that are preceded by the recognition character - and followed by(Db2) under Db2 commands.

You can also enter comments by starting them with an asterisk (*).

During a DSN session, you can also issue TSO commands, except for FREE, RUN, TEST, and TIME. To use TSO TEST to debug an application program, run it with the DSN command; for example:

TEST '
prefix
.SDSNLOAD(DSN)' CP

Important: Start of change

The ABEND subcommand is used for diagnostic purposes only, and is intended to be used only under the direction of IBM Support. Use it only when diagnosing a problem with DSN or Db2. End of change

Percent commands are not recognized during a DSN session, they are only supported by the TSO command processor.

Environment

A DSN session runs under TSO in either foreground or background mode. When you run it in background mode, you are not prompted for corrections or additional required information.

You can also start a DSN session from a CLIST running in either foreground or background mode.

Data sharing scope: Member

Authorization

None is required for the DSN command, but authorization is required for most subcommands.

Syntax

Option descriptions

None of the following options are required.

SYSTEM

( subsystem-name ): Specifies the name of the Db2 subsystem.
( group-attachment-name ): Specifies the group attachment name of the data sharing group.
( subgroup-attachment-name ): Specifies the subgroup attachment name of the data sharing group.

The default is SYSTEM( DSN ). This value can be modified during Db2 installation.

RETRY( integer )

Specifies the number (integer) of additional times connection to the Db2 subsystem should be attempted if Db2 is not up or the maximum number of batch connections has been reached when DSN is issued. Retries occur at 30-second intervals.

The default is RETRY( 0 ). The maximum number of retries is 120.

TEST( integer )

Specifies the last two digits (integer) of the module name in order to trace a single DSN module. Specify a number greater than 100 to trace all DSN modules. DSN trace information messages are written to the TSO SYSTSPRT DD statement, and optionally, to the DSNTRACE DD statement.

GROUP

( YES ): Specifies that group attachment processing is considered when the system is not active.
(NO): Specifies that group attach processing is not considered.

ASUSER( userid )

Specifies a user ID to associate with the trusted connection for the current DSN session.

A trusted connection is established if the primary authorization ID and jobname matches a trusted context defined in Db2. The user ID that you specify as ASUSER goes through the standard authorization and connection exit processing to pick up the primary and secondary IDs. If the primary authorization ID is allowed to use the trusted connection without authentication, Db2 establishes the trusted connection for the ASUSER user ID. The primary authorization ID, any secondary authorization IDs, and any role associated with the ASUSER user ID are now in effect for the trusted connection.

If the primary authorization ID associated with the user ID that you specify in the ASUSER option is not allowed to use the trusted connection or requires authentication information the connection request fails.

Db2 retains the ASUSER value only for the life of the DSN session.

Usage notes

Beginning a DSN session: Issue the DSN command to begin a DSN session, which allows you to enter DSN subcommands. The following rules govern the session:

In foreground operation, you are prompted for input by the prompt string DSN at the terminal. In background mode, your input is read from the SYSTSIN data set.
Except for delimited table names in the DCLGEN command, input in lowercase letters is changed to uppercase.
If duplicate keywords of any subcommand are specified, only the last of these keywords is processed. For example, if both MEMBER( dbrm-member-name1 ) and MEMBER( dbrm-member-name2 ) are specified with BIND PLAN, Db2 receives only the latter, MEMBER( dbrm-member-name2 ).
If ATTENTION (PA1) is pressed during a DSN session, and PROMPT is specified in the TSO user profile, message DSNE005 appears: EXECUTION IS INTERRUPTED, ENTER C TO CANCEL, OR ANY OTHER REPLY TO RESUME THE subcommand SUBCOMMAND.
If you enter C, the current subcommand is canceled and the current Db2 connection terminates; a new one is established, and another DSN prompt appears. Any other reply, except ATTENTION, causes the current subcommand to continue from the point at which it was interrupted.

If a DSN session is started from a CLIST, or a CLIST is executed under DSN, CONTROL PROMPT must be specified in the CLIST in order to receive message DSNE005.
After a command is processed during a DSN session, you are prompted for input. That cycle continues until you end the session.
You can end the session by taking one of the following actions:
- Issue the END subcommand. Control is passed to TSO.
- Press ATTENTION and respond to the message by pressing ATTENTION again.
- Issue another DSN command. The old session ends and a new one begins.

DSN return code processing: At the end of a DSN session, register 15 contains the highest value used by any DSN subcommand in the session or by any program run using the RUN subcommand. Your run time environment might format that value as a return code. The value does not, however, originate in DSN.

Establishing trusted context using TSO and DB2I: DB2I runs under TSO using ISPF services. The DB2I facility provides an ISPF front end for tools such as SPUFI and DCLGEN and tasks such as preparing Db2 programs and binding plans and packages. The DB2I Defaults Panel includes the field AS USER. Use the AS USER field to specify an authorization name to use for the current session that is associated with the trusted connection. The trusted connection is established when the TSO logon ID matches the system authorization ID and jobname defined for a trusted context. The ASUSER field is always blank on entry to DB2I. If you enter a value in the AS USER field it is passed to all TSO attach (DSN) calls by using the ASUSER option of the DSN (TSO) command.

Start of change Attachment facilities for monitors: For long-running programs such as monitors, use a programmable attachment facility like CAF or RRSAF, instead of using the Db2 TSO attachment facility. The TSO attachment facility is not designed for use in a long-running program. Use of the TSO attachment facility for that type of program might cause storage or recovery problems. End of change

Examples

Example: Starting a DSN session with multiple retry attempts

The following command starts a DSN session. If the attempt to connect to Db2 fails, up to five retries, at 30 second intervals, are made.

DSN SYSTEM (DB2) RETRY (5)

Example: Starting a DSN session, running a program, and ending a DSN session

The following example shows the commands to start a DSN session, run a program, and end the DSN session.

TSO prompt :  READY
USER enters:  DSN SYS(SSTR)
DSN prompt :  DSN
USER enters:  RUN PROGRAM(MYPROG)
DSN prompt :  DSN
USER enters:  END
TSO prompt :  READY