DSN commands in DB2 for z/OS

What a DSN session is

DSN executes as a TSO command processor. A session runs in the TSO foreground (you see the prompt DSN) or in background (input comes from SYSTSIN). You can also start DSN from a CLIST in either mode. Data sharing scope for the DSN command itself is member: you attach to one subsystem or through a group attach name that lands you on a member.

No authorization is required to issue DSN. Almost every subcommand then checks its own privileges (BIND, SELECT for DCLGEN, and so on). That split surprises beginners who expect the first command to fail when they lack SYSADM.

After each subcommand, DSN prompts again until you end the session. Duplicate keywords on a subcommand are not merged: only the last one is processed. Input is folded to uppercase except for delimited table names on DCLGEN. Comments start with an asterisk.

1
2
3
4
5
6
7
8
9
READY
DSN SYSTEM(DB2A)
DSN
BIND PACKAGE(COLL1) MEMBER(MYPROG) ACTION(REPLACE)
DSN
-DISPLAY THREAD(*)
DSN
END
READY

DSN options

SYSTEM

SYSTEM is how you name the Db2 you want. Use the four-character subsystem name on a standalone LPAR, the group attachment name when any member of a data sharing group is acceptable, or a subgroup attachment name when the shop defined subgroups. If you omit SYSTEM, the default is whatever install put in SYSTEM(DSN). Wrong names produce connection failures, not a SQLCODE — you are not in SQL yet.

RETRY

Batch jobs often start before Db2 has finished -START DB2. RETRY(integer) tries the attach again every 30 seconds. RETRY(0) (default) fails immediately. RETRY(120) is the documented maximum — an hour of waiting. Background mode does not prompt you to fix mistakes, so RETRY is the usual safety net for overnight BIND jobs.

TEST

TEST is for diagnosing DSN itself, not your COBOL. You pass the last two digits of a DSN module name, or a number greater than 100 to trace all DSN modules. Messages go to TSO SYSTSPRT and, if you allocate it, DSNTRACE. Leave TEST off in production CLISTs.

GROUP

GROUP(YES) considers group attachment processing when the system you named is not active, so a downed member can still land you elsewhere in the group if group attach is set up. GROUP(NO) does not. Pair this with SYSTEM(group-attachment-name) the way your sysprog documented it.

ASUSER

Trusted contexts let a connection run as a different authorization ID when the TSO logon ID and job name match the context. ASUSER(userid) names that ID for this session only. Standard authorization and connection exits still run. If the ASUSER primary ID is not allowed on the trusted connection, or the context requires authentication you did not supply, the connect fails. DB2I Defaults has an AS USER field that is always blank on entry and is passed through to DSN as this option.

1
2
DSN SYSTEM(DB2) RETRY(5)
DSN SYSTEM(DSNG) GROUP(YES) ASUSER(APPBAT)

What you can type at the DSN prompt

All DSN subcommands except SPUFI run under DSN in foreground or background. All except BIND QUERY and END also run under DB2 Interactive (DB2I). SPUFI runs only in the foreground under ISPF — there is no batch SPUFI subcommand in the same sense.

During the session you may also enter Db2 operator commands. They must start with a hyphen, for example -DISPLAY DATABASE(DSNDB06). The documented exception is START DB2: you cannot start the subsystem from inside an attach that already requires it to be up. You may enter TSO commands except FREE, RUN, TEST, and TIME. To debug a program with TSO TEST, TEST the DSN load module itself, for example TEST 'prefix.SDSNLOAD(DSN)' CP, then run the program under that DSN.

Percent commands (TSO implicit CLIST percent syntax) are not recognized inside DSN.

Attention, return codes, and batch

If ATTENTION (PA1) is pressed and PROMPT is in the TSO user profile, message DSNE005 asks you to enter C to cancel the current subcommand or anything else to resume. C cancels the subcommand, drops the Db2 connection, and establishes a new one; you get another DSN prompt. A CLIST that starts DSN needs CONTROL PROMPT to see that message.

At the end of the session, register 15 holds the highest value used by any subcommand or by a program run with RUN. Your runtime may show that as a step return code. The value does not originate inside DSN’s own logic in the way beginners assume — a failing COBOL program can set it.

Background: put the DSN command and subcommands in SYSTSIN. There is no prompt and no chance to correct a typo. END is optional if the stream ends with /* or //.

1
2
3
4
5
6
7
8
9
//BIND     EXEC PGM=IKJEFT01
//STEPLIB  DD DISP=SHR,DSN=DB2A.SDSNLOAD
//SYSTSPRT DD SYSOUT=*
//SYSTSIN  DD *
  DSN SYSTEM(DB2A) RETRY(10)
  BIND PACKAGE(PAYROLL) MEMBER(PAY001) ACTION(REPLACE) -
       ISOLATION(CS) QUALIFIER(HR)
  END
/*

Foreground, IKJEFT01, and libraries

In TSO READY you type DSN and the processor is found through the usual STEPLIB, ISPLLIB, or LINKLIST search. In batch the same processor is started by EXEC PGM=IKJEFT01 (the TSO terminal monitor program in batch). IKJEFT01 reads SYSTSIN; DSN then reads the following lines as its own input until END. STEPLIB must include the SDSNLOAD that matches the subsystem. Mixing a Db2 12 SDSNLOAD with a Db2 13 SSID is a classic connection or module mismatch. SYSTSPRT captures DSN messages and BIND reports. If you allocate DSNTRACE, TEST output can go there as well as SYSTSPRT.

A CLIST that wraps DSN should use CONTROL PROMPT if you want ATTENTION handling to show DSNE005. Without PROMPT, ATTENTION behaviour is harder to predict. Nested DSN is not a thing: issuing DSN while already in a session ends the old session and starts a new one with the new options. That is useful when you meant SYSTEM(DB2B) but typed DB2A; it is disastrous if a CLIST issues DSN twice by accident and drops your BIND mid-stream.

Connection type from DSN is TSO attach. That attach is intended for interactive work and short batch BIND/RUN steps. IBM warns that long-running monitors should use CAF or RRSAF instead. TSO attach was not designed for a started task that stays connected all day, creating and destroying many threads. Those patterns can exhaust TSO or Db2 storage and make recovery after a cancel uglier than an RRSAF IDENTIFY/SIGNON design.

Authorization, data sharing, and operator commands

Remember the split: DSN itself needs no privilege. BIND PACKAGE needs BIND on the collection (or BINDADD plus CREATE IN). DCLGEN needs SELECT on the table. Hyphen commands use the same authorization as if you typed them on the console: -DISPLAY DATABASE needs DISPLAY, SYSOPR, or stronger; -STOP DATABASE needs STOPDB or SYSOPR. Your TSO user ID is the primary authorization ID unless a connection exit or ASUSER trusted context changes it. Secondary IDs from RACF still apply to SQL and BIND the same way they do in SPUFI.

In a data sharing group, SYSTEM(group-attach) plus GROUP(YES) is how overnight BIND jobs survive a member being down for maintenance. The bind still runs on whichever member accepts the attach; package copies are group objects. Operator commands you type at the DSN prompt still have their documented scope: some are member, some are group. -DISPLAY GROUP is a good first command after attach to confirm which member you landed on. You cannot -START DB2 from DSN because the attach already requires Db2 to be up; start Db2 from a console or automation before the BIND job.

Hyphen commands inside DSN must begin with the command prefix character your shop defined (often a hyphen, sometimes a plus). If you omit the prefix, DSN tries to parse the word as a subcommand and you get a syntax error instead of DISPLAY output. START DB2 remains the documented exception even with a prefix.

DSN versus other ways in

DB2I is an ISPF front end that still calls DSN under the covers for BIND, DCLGEN, and SPUFI. The Utilities panel does not use DSN for LOAD; it builds JCL for DSNUTILB. CAF and RRSAF are programmable attaches for CICS, IMS, and long-running monitors. JDBC and the IBM Data Server Driver use DDF, not DSN. Pick DSN when a human or a TSO batch job needs BIND/RUN/DCLGEN or a quick -DISPLAY. Pick DSNUTILB when the work is an online utility control statement.

SPUFI from DB2I is still a DSN session with ISPF panels in front. BIND from DB2I fills the same subcommand keywords you would type: ISOLATION, QUALIFIER, ACTION, OWNER. The AS USER field on DB2I Defaults is ASUSER on the DSN command. If a panel BIND works and your SYSTSIN BIND fails, diff the generated JCL SYSTSIN against yours — missing continuation hyphens in column 72 and misspelled MEMBER names are the usual gaps.

Explain It Like I'm Five

DSN is the doorbell and hallway of the Db2 house. You ring SYSTEM(DB2A), wait in the hallway (the DSN prompt), then shout jobs like BIND or -DISPLAY THREAD. END is walking back outside to TSO READY. DSNUTILB is a different building: the loading dock where trucks (LOAD, COPY) back in with JCL. Do not ring the doorbell when you meant to send a truck.

Exercises

1. Start DSN SYSTEM(your-ssid), issue -DISPLAY GROUP, and END. Record the prompt strings you saw.
2. Write a SYSTSIN stream that RETRY(5), BIND a package, and END. Explain why RETRY helps a job that starts at IPL.
3. Try -START DB2 from a DSN session (on a sandbox) and explain the documented restriction.
4. Compare issuing BIND from DSN versus the DB2I BIND panel. What option maps to ASUSER?
5. List three reasons a monitor should use RRSAF instead of staying in a DSN session all day.