IKJEFT01 and the DSN command processor in DB2

IKJEFT01: TSO in batch

IKJEFT01 is the TSO/E Terminal Monitor Program. Foreground, you log on to TSO and type commands. Background, JCL EXEC PGM=IKJEFT01 and the commands come from SYSTSIN. That is how shops run BIND, DSNTEP2, and COBOL programs that use the TSO attachment facility—without a human at a terminal.

Related entry points: IKJEFT1A and IKJEFT1B are also TMP aliases. They differ in whether a failing command abends the step or only sets a return code. IBM Db2 samples typically show IKJEFT01. Use DYNAMNBR (IBM examples often use 20) so DSN can dynamically allocate DBRM libraries, load libraries, and SYSPRINT-type files.

Db2 batch execution of an application is almost always: TMP → DSN → RUN PROGRAM. The program uses the TSO attach to talk to Db2. CAF and RRSAF programs can EXEC the application module directly without DSN; that is a different pattern (IMS/CICS batch connections, or a CAF stub). This page stays on the IKJEFT01 + DSN pattern beginners meet first.

The DSN command processor

DSN is a TSO command. It starts a session attached to one Db2 subsystem. Until you type END, further lines are DSN subcommands or hyphenated operator commands—not raw TSO.

DSN SYSTEM

DSN SYSTEM(ssid) names the Db2 subsystem, a data sharing group attachment name, or a subgroup attachment. If you omit SYSTEM, the install default (often DSN) is used—which is wrong on a machine with DB2T and DB2P. Always code the ssid your job is meant to hit.

Optional DSN operands you will see in production:

• RETRY(n) — extra attach attempts every 30 seconds if Db2 is down or batch connections are full (max 120)
• TEST — TSO TEST environment for debugging
• ASUSER(userid) — trusted-context user for this session (DB2I Defaults “AS USER”)

You can issue Db2 commands that start with a hyphen (-DISPLAY THREAD, -STOP DATABASE) from the session. You cannot issue -START DB2 from DSN: the session already requires Db2 to be the attach target. Keep DSN job steps short. If the application abends or returns non-zero, DSN typically terminates.

SYSIN, SYSPRINT, SYSTSPRT, SYSUDUMP

Beginners mix SYSIN and SYSTSIN constantly.

• SYSTSIN is what IKJEFT01 reads: TSO commands, including DSN, RUN, BIND, END
• SYSIN is what many programs read after RUN: DSNTEP2 SQL, DSNTIAUL control, your COBOL ACCEPT file
• SYSTSPRT is the TSO session log (DSN prompt, “READY”, command RC)
• SYSPRINT is the program listing (SQL output from DSNTEP2, compiler listings in other steps)
• SYSUDUMP (or SYSMDUMP/SYSABEND per shop) captures an abend dump

Online utilities do the opposite: DSNUTILB reads utility statements from SYSIN and writes messages to SYSPRINT. There is no DSN prompt. Putting BIND PLAN in DSNUTILB SYSIN fails; putting COPY TABLESPACE in SYSTSIN fails.

STEPLIB, SDSNLOAD, SDSNEXIT

The DSN processor and TSO attach modules live in prefix.SDSNLOAD. The customized application defaults module (DSNHDECP or your shop’s name) and many exits live in prefix.SDSNEXIT. Concatenate EXIT before LOAD so the right DECP is found. Both libraries must be APF-authorized for attach. The maintenance level must match the running subsystem or you get module mismatch errors.

1
2
3
4
5
6
7
8
9
10
11
12
//GO     EXEC PGM=IKJEFT01,DYNAMNBR=20
//STEPLIB  DD DISP=SHR,DSN=DSN.DB2T.SDSNEXIT
//         DD DISP=SHR,DSN=DSN.DB2T.SDSNLOAD
//         DD DISP=SHR,DSN=HR.LOADLIB
//SYSTSPRT DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//SYSTSIN  DD *
  DSN SYSTEM(DB2T) RETRY(5)
  RUN PROGRAM(PAYROLL) PLAN(PAYPLAN) LIB('HR.LOADLIB')
  END
/*

JOB USER= on the JOB card often becomes the Db2 primary authorization ID for the TSO attach. RACF, GRANT EXECUTE on the plan, and the package owner must all line up or you see SQLCODE -922 / plan-not-found errors that look like JCL problems.

DB2I and SPUFI

DB2I (Db2 Interactive) is the ISPF panel set: SPUFI, DCLGEN, Program Preparation, Bind, Utilities, Commands, Defaults. Under the covers, many of those panels build the same DSN commands you put in SYSTSIN. The Defaults panel SSID is SYSTEM(). AS USER is ASUSER().

SPUFI (SQL Processor Using File Input) lets you edit an SQL file and execute it, with output to another file. It is a DSN/TSO tool, not DSNUTILB. Batch equivalent: IKJEFT01 + RUN PROGRAM(DSNTEP2) + SQL in SYSIN. Use SPUFI for ad-hoc SELECTs; use DSNTEP2 when the same SQL must run overnight; use UNLOAD/LOAD when the volume is a table space, not a query.

The DB2I Utilities option is different: it generates DSNUTILB JCL (or submits a utility job). That job will not contain IKJEFT01. Knowing which panel produces which program saves hours of “why is SYSTSIN ignored?”

1
2
3
4
5
6
7
8
9
10
11
12
//BIND   EXEC PGM=IKJEFT01,DYNAMNBR=20
//STEPLIB  DD DISP=SHR,DSN=DSN.DB2T.SDSNEXIT
//         DD DISP=SHR,DSN=DSN.DB2T.SDSNLOAD
//DBRMLIB  DD DISP=SHR,DSN=HR.DBRMLIB
//SYSTSPRT DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//SYSTSIN  DD *
  DSN SYSTEM(DB2T)
  BIND PACKAGE(HR) MEMBER(PAYROLL) -
       ACTION(REPLACE) ISOLATION(CS) VALIDATE(BIND)
  END
/*

Explain It Like I'm Five

IKJEFT01 is a robot that types TSO commands when nobody is at the keyboard. DSN is the doorbell for the Db2 house: SYSTEM(DB2T) picks which house. Inside, you can BIND (file the lesson plan), RUN (send a kid in to do homework), or ask “who is in the hallway?” (-DISPLAY). END walks back outside. SYSTSIN is the robot’s instruction card. SYSTSPRT is the robot’s diary. SYSIN is a different notebook that only the kid (DSNTEP2) reads. SDSNLOAD is the toolbox; SDSNEXIT is the labeled wrench set for this house. DB2I is the same doorbell with pretty ISPF buttons. The loading dock for COPY and LOAD is a different building called DSNUTILB—do not hand the robot a forklift work order.

Exercises

1. Write an IKJEFT01 step that connects to your test ssid with RETRY(5), runs DSNTEP2, and END. Label every DD.
2. Explain what breaks if SDSNLOAD is concatenated before SDSNEXIT.
3. Put a COPY control statement in SYSTSIN on purpose (on a sandbox) and record the error. Then put DSN SYSTEM in DSNUTILB SYSIN and record that error.
4. Compare a SPUFI run with the same SELECT in DSNTEP2 SYSIN. Where does output appear in each case?
5. Find the DB2I Defaults panel fields that map to SYSTEM and ASUSER.