DB2 attachment facilities on z/OS

Attachment facilities compared

All five choices reach the same Db2 engine, but they do not have the same lifecycle or recovery model. The table is an orientation guide, not a replacement for your installation's subsystem parameters and transaction-manager definitions.

TSO attachment facility: DSN, DB2I, and SPUFI

The TSO attachment facility is the first connection method many Db2 learners encounter. From a TSO/E session, the DSN command starts the DSN command processor. DSN SYSTEM(DB2P) selects a subsystem or data sharing group attachment name. Within that DSN session, subcommands such as RUN, BIND, REBIND, and DCLGEN work against the selected Db2.

DB2I is the ISPF panel interface for common Db2 development tasks. DB2I's SPUFI option reads SQL from a data set, executes it, and writes formatted results to an output data set. DB2I makes the interaction friendlier, but it still relies on TSO and DSN attachment services. The programmer normally has one active Db2 subsystem connection in a DSN session. It is a simple model, not a general-purpose multi-connection server.

When compiling or preprocessing an application for this environment, you will encounterATTACH(TSO). The option tells the application preparation process which attachment interface the program expects. It must agree with how the program is launched and linked. A mismatch can produce an attach failure before useful SQL runs.

Batch attachment: TSO in the background or a direct API

“Batch attachment facility” is often used informally, but batch is an execution style, not one single API. The most common pattern runs TSO in the background. JCL executesIKJEFT01, the TSO Terminal Monitor Program, and supplies commands in SYSTSIN. DSN attaches to Db2, and RUN PROGRAM starts the application. That is still the TSO attachment facility.

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

A different batch design executes an application directly and lets its code callCAF or RRSAF. There is no DSN RUN command in that design because the program is its own connection manager. Direct attachment is useful for started tasks, servers, and programs that need lifecycle control beyond one simple DSN session. It also requires more careful coding and recovery handling.

The DSN command and command processor

DSN is both the familiar TSO command and the name people use for the processor it starts. In foreground TSO, commands come from the terminal or DB2I panels. In background TSO, IKJEFT01 reads them from SYSTSIN and writes session messages to SYSTSPRT. The RUN PROGRAM subcommand loads an application and invokes it under the TSO attachment.

1
2
3
DSN SYSTEM(DB2T)
RUN PROGRAM(DSNTEP2) PLAN(DSNTEP13)
END

DSNTEP2 reads its SQL from SYSIN; DSN itself reads SYSTSIN. SPUFI is the interactive DB2I path for submitting SQL from a file. These paths solve related problems, but they are not Db2 utilities: COPY, LOAD, REORG, and RUNSTATS normally execute through DSNUTILB. See the dedicated DSN command processor tutorial for complete DD and command examples.

Call Attachment Facility: CAF and DSNALI

The Call Attachment Facility, or CAF, lets an application manage its Db2 relationship by calling an API. Its language interface module is DSNALI. CAF is well suited to flexible batch applications and started tasks that cannot be structured as one DSN RUN PROGRAM invocation.

• CONNECT establishes the application's connection to a named Db2 subsystem.
• OPEN creates or opens the thread used to process SQL.
• CLOSE ends the current thread after the application has correctly completed or backed out its unit of work.
• DISCONNECT removes the application's connection to Db2.

Those calls make lifecycle control explicit. The program must check return and reason codes, avoid disconnecting with unfinished work, and define recovery behavior if Db2 stops. ATTACH(CAF) selects the CAF interface during application preparation. CAF can be an excellent fit, but it does not automatically provide RRS two-phase commit coordination.

RRS attachment facility: RRSAF and DSNRLI

The Resource Recovery Services Attachment Facility, usually calledRRSAF, uses the DSNRLI interface. It connects Db2 work with z/OS Resource Recovery Services (RRS). When one logical transaction updates Db2 and another RRS-aware recoverable resource, RRS can coordinate a two-phase commit: participants first indicate whether they can commit, and RRS then tells all of them to commit or back out.

Beginner-level RRSAF flow uses functions such as IDENTIFY to identify the caller to RRS, SIGNON to establish an authorization context, andCREATE THREAD to obtain a Db2 thread. The application later terminates threads and connection state in the documented order. Exact call sequences and parameters depend on the application model, so production code should follow the IBM interface descriptions rather than treating the names as ordinary SQL calls.

RRSAF is required for WLM-established stored procedures. The WLM address space and Db2 need the recovery and identity services RRSAF supplies. Programs prepared for this interface use ATTACH(RRSAF). Choose RRSAF when RRS coordination or this execution model is a requirement, not merely because it is newer than CAF.

CICS attachment facility overview

CICS is a transaction manager, so it needs a connection that can serve many short transactions efficiently. A DB2CONN resource defines the CICS region's overall connection to a Db2 subsystem, including connection-level and pool settings. A DB2ENTRY maps selected CICS transactions to Db2 plans and thread rules. Work without a matching DB2ENTRY can use the pool configured by DB2CONN.

Entry, pool, and protected threads

• Entry threads are associated with a DB2ENTRY and provide predictable capacity and plan selection for named transaction groups.
• Pool threads handle eligible work that is not using a dedicated entry or when design settings permit overflow to the pool.
• Protected threads are entry threads retained for reuse, commonly controlled with DB2ENTRY settings such as PROTECTNUM. They reduce repeated creation and termination cost for busy transactions.

Too few threads can queue transactions; too many can consume Db2 storage and increase contention. CICS also handles sign-on, authorization propagation, commits, abends, and thread cleanup as part of transaction processing. This tutorial provides orientation only. Use the CICS + Db2 section for resource-definition syntax, command operations, protected-thread tuning, and failure diagnosis.

IMS attachment facility overview

IMS message-processing programs run under IMS control, so IMS coordinates their Db2 access and transaction boundaries. The IMS attachment uses external-subsystem facilities to connect dependent regions to Db2. IMS and Db2 cooperate so a successful message transaction can commit consistently and an application failure can back out related work.

You may see ESAF, the External Subsystem Attach Facility, in this area. You may also encounter DRA, the Database Resource Adapter, in broader IMS architecture discussions. They are not interchangeable names. ESAF concepts are relevant to IMS coordination with external subsystems such as Db2. DRA is associated with access to IMS databases from other address spaces, notably IMS DBCTL scenarios. At beginner level, remember that IMS owns the transaction environment and its Db2 attachment preserves that coordination; do not code a casual CAF connection inside an IMS transaction to bypass it.

Attachment facility threads

Local attachment facilities create allied threads. An allied thread is Db2's working context for a local application. It carries information about the connection, plan or packages, authorization, locks, unit of recovery, and current SQL activity. It differs from a distributed database access thread, or DBAT, used by remote clients through DDF.

Creation

Thread creation happens when the facility has enough identity and application information to begin SQL work. DSN RUN causes TSO attachment processing to obtain a thread. CAF OPEN and RRSAF CREATE THREAD make the point more visible. CICS and IMS create or assign threads according to transaction-manager definitions. Creation costs CPU and storage, so high-volume managers avoid doing it needlessly.

Reuse

Reuse means a suitable thread remains available for later work rather than being fully rebuilt. CICS protected threads are the clearest example. Pooling and carefully managed long-running CAF or RRSAF designs can also reduce churn. Reuse improves throughput, but stale identity, unfinished units of work, retained resources, or an inappropriate plan context can create serious defects. Reuse must occur through the facility's supported reset and sign-on rules.

Termination

Normal termination completes commit or rollback, closes the thread, and disconnects in the expected order. Abnormal termination requires the attachment and Db2 to detect the failed owner, back out uncommitted work, and release locks and storage. A lingering thread in DISPLAY THREAD output is therefore a diagnostic clue: investigate whether it is intentionally protected, waiting, in-doubt, or attached to a failed application.

Attachment security and authorization IDs

Connection success does not imply permission to use every Db2 object. Duringconnect or sign-on, the facility establishes an authorization identity. For TSO batch, the job's security identity commonly contributes the primary authorization ID. CICS and IMS can establish identities from transaction and sign-on context. CAF and RRSAF callers pass information according to their APIs and security configuration.

The primary authorization ID is the main identity for privilege checking. A Db2 connection or sign-on exit can add secondary authorization IDs, often based on RACF groups. Db2 can then recognize privileges granted to either the primary ID or applicable secondary IDs. The package owner, plan EXECUTE privilege, dynamic SQL authorization ID, trusted context, and role can also matter. These are distinct concepts; a user who can connect may still receive SQLCODE -922 or -551 for an unauthorized operation.

• Authenticate the address space and end user through approved z/OS security controls.
• Grant only the plan, package, and object privileges the workload requires.
• Ensure reused threads switch or reset identity through supported sign-on processing.
• Log the primary and secondary authorization context when investigating failures.
• Never invent a user ID in application data and assume Db2 will trust it.

Explain it like I'm five

Think of Db2 as a secure workshop. Programs cannot walk straight inside. TSO is the visitor desk for one person or one batch job. CAF gives a trained worker a phone with buttons for connect, open, close, and disconnect. RRSAF gives the worker a phone plus a referee who makes sure two workshops either both save their work or both erase it. CICS has a busy front desk with reusable passes for thousands of quick visitors. IMS has its own supervisor who keeps message work and database work together. A thread is the work bench assigned to a visitor, and the authorization IDs are the badges checked before tools can be used.

Exercises

1. Take the IKJEFT01 example and identify the line that starts TSO, the line that selects the Db2 subsystem, and the line that starts the application.
2. Draw the CAF lifecycle CONNECT → OPEN → SQL and commit/rollback → CLOSE → DISCONNECT. Write one cleanup action needed if OPEN fails.
3. Describe a business transaction that updates Db2 and another recoverable resource. Explain why RRSAF and RRS two-phase commit are safer than two unrelated commits.
4. For a CICS region, explain when an entry thread, a pool thread, and a protected entry thread would be useful. Include one cost of protecting too many threads.
5. Compare an allied thread with a DDF DBAT. State where each originates and why the names should not be used interchangeably.
6. Given a successful connection followed by SQLCODE -551, list the primary ID, secondary IDs, package/plan privilege, and object privilege evidence you would collect before changing any GRANT.