The CICS®-DB2® Attachment facility allows connection
to a DB2 subsystem using the CICS resource manager interface (RMI),
which is also known as the task related user exit interface. The Attachment
facility interfaces to DB2 through a series of requests to three components
of DB2, each of which processes specific types of requests:
- Subsystem Support Subcomponent (SSSC) for thread and system control
requests
- Advanced Database Management Facility (ADMF) for SQL requests
- Instumentation Facility Component (IFC) for IFI requests
There no are DB2 release dependencies within the attachment
facility, it can connect to a DB2 subsystem running any supported
level of DB2.
The architecture of the CICS-DB2 interface is described in CICS DB2 Guide:
- For DB2 for OS/390 Version 6 or later, the attachment facility
exploits the open transaction environment (OTE) and uses CICS-managed
open TCBs.
- For DB2 for OS/390 Version 5 or earlier, the attachment facility
manages its own set of subtask TCBs on which it builds threads to
access DB2.
During CICS Initialization the following modules are invoked:
CICS-DB2 initialization gate DFHD2IN1
DFHD2IN1 first receives control from DFHSII1 duiring CICS initialization
by means of a DFHROINM INITIALISE call. When invoked with this function
DFHD2IN1 attaches a system task CSSY to run program DFHD2IN2.
DFHD2IN1 is invoked a second time later by DFHSII1 by means of
a DFHROINM WAIT_FOR_INITIALIZATION call for which DFHD2IN1 issues
a CICS wait to wait for DFHD2IN2 processing to complete.
CICS-DB2 recovery task DFHD2IN2
DFHD2IN2 runs under CICS system task CSSY attached by DFHD2IN1.
DFHD2IN2 links to program DFHD2RP, the CICS-DB2 restart program. On
return from DFHD2RP, DFHD2IN2 posts the ecb waited on by DFHD2IN1
so that CICS Initialization can continue.
CICS-DB2 restart program DFHD2RP
DFHD2RP runs under system task CSSY during CICS initialization.
DFHD2RP performs the following functions:
- Adds storage manager subpools for the DFHD2ENT, DFHD2TRN and DFHD2CSB
control blocks.
- Issues lock manager domain ADD_LOCK requests to add the necessary
locks required by the CICS-DB2 Attachment facility to manage the dynamic
chains of DFHD2LOT and DFHD2CSB control blocks, plus locks to manipulate
the DFHD2GLB, DFHD2ENT and DFHD2TRN control blocks.
- Loads CICS-DB2 modules DFHD2CC, DFHD2CO, DFHD2D2, DFHD2STR, DFHD2STP
and DFHD2TM
- Activates the DFHD2TM gate with the kernel.
- For cold and Initial CICS starts:
- Purges the Global catalog of DFHD2GLB, DFHD2ENT and DFHD2TRN control
blocks
- For warm and emergency CICS starts:
- Installs DFHD2GLB, DFHD2ENT and DFHD2TRN blocks found on the global
catalog
The CICS-DB2 Attachment facility can be started using one of the
following methods:
- specifying program DFHD2CM0 in PLTPI
- specifying SIT parameter DB2CONN=YES
- Issuing the DSNC STRT command
- Issuing the CEMT or EXEC CICS SET DB2CONN CONNECTED command
All of the above ways result in an EXEC CICS SET DB2CONN CONNECTED
command being issued and the CICS-DB2 startup program DFHD2STR getting
control.
CICS-DB2 startup program DFHD2STR
The startup program starts by reading a temporary storage queue
to obtain any parameters passed if a DSNC STRT command has been issued.
It also retrieves any parameters specified via the INITPARM SIT parameter
by linking to program DFHD2INI.
Next DFHD2STR must ensure the necessary DFHD2GLB block is installed.
If a DFHD2GLB is already installed, representing an installed DB2CONN,
then it is checked to make sure interface is currently shut before
startup can proceed.
The remainder of DFHD2STR processing is as follows:
- Initialise the DFHD2GLB and set the state to 'connecting'
- MVS™ load the DB2 program request handler
- Attach a CICS system task to run the CICS DB2 service task CEX2
- Call DFHD2CO to connect to DB2 and obtain indoubts
- Enable the CICS-DB2 TRUE DFHD2EX1
- If connected to DB2 for OS/390 Version 5 or earlier, then issue
an MVS Attach for the CICS-DB2 master subtask program DFHD2MSB and
wait for DFHD2MSB initialization processing to complete
- Set the status of the connection to 'connected'
- Post CEX2 to process any indoubts passed from DB2
- Update state in the temporary storage queue to pass back to a
DSNC STRT command
The CICS-DB2 Attachment facility can be stopped using one of the
following methods:
- Issuing the DSNC STOP command
- Issuing the CEMT or EXEC CICS SET DB2CONN NOT CONNECTED command
- Running the CDBQ or CDBF transactions
- Shutting down CICS
All of the above ways result in an EXEC CICS SET DB2CONN NOTCONNECTED
command being issued and the CICS-DB2 shutdown program DFHD2STP getting
control.
CICS-DB2 shutdown program DFHD2STP
Processing in DFHD2STP is as follows:
- If CDB2SHUT is set in the dump table, take a system dump (serviceability
aid)
- If a CDB2SHUT dump has not been taken, and the CICS-DB2 master
subtask program DFHD2MSB has unexpectedly abended, then a system dump
is taken with a dumpcode of MSBABEND.
- post CICS-DB2 service task CEX2 to terminate all subtasks then
terminate itself. Wait for service task to complete.
- If present, post master subtask DFHD2MSB to terminate. Wait for
it to terminate, then detach master subtask TCB.
- Call DFHD2CO to disconnect from DB2
- Call DFHD2CC to write out shutdown statistics
- If the CICS-DB2 attachment is to go into 'standbymode':
- Re-initialise the DFHD2GLB, set the state to 'connecting'
- Post any tasks who are waiting for shutdown to complete
- Issues 'Waiting for DB2 attach' message
- If the CICS-DB2 attachment is not to go into 'standbymode':
- Disable the CICS-DB2 TRUE DFHD2EX1
- MVS delete the program request handler
- Re-initialise the DFHD2GLB, set the state to 'shut'
- Issue the shutdown complete message and post any tasks who are
waiting for shutdown to complete
CICS-DB2 task related user exit (TRUE) DFHD2EX1
Control is passed to the TRUE via the CICS RMI. The TRUE manages
the relationship between a CICS task (represented by a LOT control
block), and a CICS-DB2 thread (represented by a CSB control block).
DFHD2EX1 uses parameters set in the DB2CONN and DB2ENTRY definitions
to manage use of the CICS DB2 threads, each thread running under a
thread TCB.
- When connected to DB2 for OS/390 Version 5 or earlier, the thread
TCB is a subtask managed by the CICS DB2 attachment facility. It is
the subtask running program DFHD2EX3 which issues requests to DB2
on behalf of a CICS task. A wait/post protocol is executed between
the CICS task running in the CICS-DB2 TRUE, and the subtask in program
DFHD2EX3.
- When connected to DB2 for OS/390 Version 6 or later, the thread
TCB is a CICS open TCB (L8 mode). Program DFHD2D2 is called under
the open TCB, and issues the requests to DB2. In this case, both DFHD2EX1
and DFHD2D2 run under the L8 TCB.
The CICS-DB2 TRUE DFHD2EX1 gets invoked by the RMI for the following
events:
- EXEC SQL commands and DB2 IFI commands from application programs
- syncpoint
- end of task
- INQUIRE EXITPROGRAM commands for the DB2 TRUE with the CONNECTST
or QUALIFIER keywords (RMI SPI calls)
- EDF - when EDFing EXEC SQL commands
- CICS shutdown
CICS-DB2 coordinator program DFHD2CO
The coordinator program runs under the CICS Resource owning (RO)
TCB, and handles the overall connection between CICS and a DB2 subsystem.
It is called :
- by DFHD2STR during startup of the attachment facility to issue
the coordinator identify to DB2, that is to establish connection to
DB2. Once established, it passes DB2 an ECB to be posted should DB2
terminate, and it also obtains from DB2 a list of units of work (UOWs)
that DB2 is indoubt about. This list is anchored off the CICS-DB2
global block (DFHD2GLB) for processing later in startup.
- by DFHD2STP during shutdown of the attachment facility to terminate
the identify to DB2 and so disconnect.
- by the CICS-DB2 TRUE DFHD2EX1 during resync processing to pass
the resolution of a indoubt unit of work to DB2. Indoubt resolution
has to be done under the same TCB that issued the coordinator identify
to DB2.
CICS-DB2 master subtask program DFHD2MSB
When operating with DB2 for OS/390 Version 5 or earlier, the DFHD2MSB
TCB is attached by DFHD2STR during startup of the Attachment facility.
It runs as a 'daughter' of the main CICS TCB. It is 'mother' to all
the subtask TCBs which process the DB2 work. The DFHD2MSB TCB is detached
by DFHD2STP during CICS-DB2 Attachment shutdown.
The main functions of DFHD2MSB are:
- To attach thread subtasks as required
- To detach thread subtasks as required
- To provide a recovery routine to cleanup if a thread subtask fails
CICS-DB2 subtask program DFHD2EX3
When operating with DB2 for OS/390 Version 5 or earlier, a
CICS-DB2 subtask TCB is attached by DFHD2MSB when required by DFHD2EX1.
It runs as a daughter of the DFHD2MSB TCB and a granddaughter of the
main CICS TCB. A CICS-DB2 subtask TCB normally remains active for
the lifetime of the CICS Attachment facility and terminates as part
of CICS-DB2 Attachment facility shutdown. Exception conditions that
cause a subtask TCB to be detached are:
- if the DB2CONN TCBLIMIT parameter is lowered
- if a CICS task is forcepurged whilst its associated subtask is
active in DB2
- If a failure occurs during syncpoint processing during the indoubt
window requiring the thread to be released.
The DFHD2EX3 program issues requests to DB2 using the DB2 SSSC,
ADMF and IFC interfaces communicating via the DB2 program request
handler DSNAPRH. In order to process DB2 requests a TCB first has
to IDENTIFY to DB2, secondly it has to SIGNON to DB2 to establish
authorization ids to DB2. Thirdly a thread has to be created. Once
a thread has been created API and syncpoint requests can flow to DB2.
Subsequent SIGNON requests can occur for a thread to change authorization
ids to DB2 or for the purposes of DB2 cutting accounting records (partial
SIGNON) When a thread is nolonger required it is terminated. The TCB
remains identified and signed on to DB2 and awaits another request
requiring it to create a thread again.
Each DB2 subtask runs an instance of program DFHD2EX3 and each
is represented by a DFHD2CSB control block. A CSB control block is
anchored to one of three CSB chains depending on its state (an active
thread within a UOW, a thread waiting for work, or an identified,
signed on TCB with no thread). The CICS-DB2 TRUE DFHD2EX1 manages
the CSB chains.
CICS-DB2 thread processor DFHD2D2
The thread processor program DFHD2D2 is used only when operating
with DB2 for OS/390 Version 6 and above, when the CICS-DB2 Attachment
Facility uses CICS open TCBs (L8 TCBs) rather than privately managed
subtask TCBs. In the Open Transaction environment (OTE), the CICS-DB2
TRUE DFHD2EX1 is invoked under an L8 TCB. Instead of posting a subtask,
DFHD2EX1 calls DFHD2D2 under the L8 TCB. DFHD2D2 performs the same
functions as performed by subtask program DFHD2EX3 in a non OTE environment,
that is issuing the identify, signon, create thread, terminate thread
calls to DB2, plus the api and syncpoint calls to DB2.
DFHD2D2 is called via a subroutine domain call on which the address
of the relevant connection control block (DFHD2CSB) is passed. On
the first call of a unit of work, DB2 is called to "associate" the
connection with the calling L8 TCB. Once this is done, calls to DB2
can proceed as normal. When a DB2 thread is released from a CICS transaction
(typically at syncpoint), the connection is "dissociated" from the
L8 TCB. Hence a connection control block (DFHD2CSB) has an affinity
to an L8 TCB whilst is associated. With DB2 for OS/390 Version 5 and
below a connection has a permanent affinity to its subtask TCB.
CICS-DB2 service task program DFHD2EX2
The CICS-DB2 service task program DFHD2EX2 runs as a CICS system
task under transaction CEX2. Its mains functions are:
- To wait for DB2 to startup if DB2 is down when connection is attempted
if STANDBYMODE=RECONNECT or CONNECT is specified in the DB2CONN.
- To initiate shutdown of the CICS-DB2 Attachment facility if posted
to do so.
- To perform the protected thread purge cycle.
- To issue EXEC CICS RESYNC to process DB2 indoubts.
- For DB2 for OS/390 Version 5 or earlier, to terminate all subtasks
during CICS-DB2 Attachment facility shutdown.
CICS-DB2 PLTPI program DFHD2CM0
Used in PLTPI or as a result of DB2CONN=YES being set in the SIT.
It issues an EXEC CICS SET DB2CONN CONNECTED command to start up the
CICS DB2 Attachment facility.
CICS-DB2 comand processor DFHD2CM1
DFHD2CM1 processes commands issues via the DSNC command. The following
commands are processed:
- DSNC STRT - EXEC CICS SET DB2CONN CONNECTED command issued
- DSNC STOP - EXEC CICS SET DB2CONN NOTCONNECTED command issued
- DSNC MODIFY DEST - EXEC CICS SET DB2CONN MSGQUEUEn command issued
- DSNC MODIFY TRAN - EXEC CICS SET DB2CONN THREADLIMIT or EXEC CICS
SET DB2ENTRY THREADLIMIT command issued.
- DSNC DISC - call passed to DFHD2CC to disconnect threads
- DSNC DISP PLAN - call passed to DFHD2CC to display information
on threads for a particular DB2 plan
- DSNC DISP TRAN - call passed to DFHD2CC to display information
on threads for a transaction.
- DSNC DISP STAT - call passed to DFHD2CC to write out statistics
- DSNC -db2command - DB2 IFI ccommand issued to send operator command
to the connected DB2 subsystem.
CICS-DB2 shutdown quiesce program DFHD2CM2
Runs under transaction CDBQ. Issues an EXEC CICS SET DB2CONN NOTCONNECTED
WAIT command to shutdown the CICS-DB2 Attachment facility.
CICS-DB2 shutdown force program DFHD2CM3
Runs under transaction CDBF. Issues an EXEC CICS SET DB2CONN NOTCONNECTED
FORCE command to shutdown the CICS-DB2 Attachment facility.
CICS-DB2 table manager DFHD2TM
Handles installs, discards, inquire and set requests for the DFHD2GLB,
DFHD2ENT and DFHD2TRN control blocks representing the DB2CONN, DB2ENTRY
and DB2TRAN resources. Callers of DFHD2TM are:
- DFHAMD2 - for CEDA install and EXEC CICS CREATE
- DFHD2EX1 - to complete disablement of a DB2ENTRY or to complete
Attachment facility shutdown
- DFHD2RP - to install objects from the Global Catalog during CICS
restart
- DFHEIQD2 - for EXEC CICS INQUIRE,SET and DISCARD of DB2 objects
- DFHESE - for inquiry during EXEC CICS QUERY SECURITY processing.
CICS DB2 statistics program DFHD2ST
Called by AP domain statistics program DFHAPST to process CICS-DB2
statistics for EXEC CICS COLLECT STATISTICS and EXEC CICS PERFORM
STATISTICS commands.
CICS DB2 connection control program DFHD2CC
DFHD2CC proceses the following requests:
- Start_db2_attachment - request routed on to DFHD2STR
- Stop_db2_attachment - request routed on to DFHD2STP
- Write_db2_statistics - statistics collected from control blocks
and are written out to the terminal, to transient data or to SMF.
- disconnect_threads - CSB control blocks searched and marked so
that threads are terminated when they are next released.
- display_plan and display_tran - thread information collected from
control blocks and output to the terminal.
CICS DB2 EDF processor DFHD2EDF
Receives control from CICS-DB2 TRUE DFHD2EX1 when the TRUE is invoked
for an EDF request. DFHD2EDF uses the RMI provided parameters to format
the screen to be output by EDF before and after an EXEC SQL request
is issued.
[[ Contents Previous Page | Next Page Index ]]