Session: E05 DB2 Attachment Facilities. John Maenpaa Health Care Service Corporation. October 7, :00 a.m. 12:00 p.m. Platform: DB2 for z/os

Transcription

1 Session: E05 DB2 Attachment Facilities John Maenpaa Health Care Service Corporation October 7, :00 a.m. 12:00 p.m. Platform: DB2 for z/os

2 Objectives The TSO Attachment Facility is often used for batch and TSO access to DB2. The CICS Attachment Facility is always used by CICS when connecting to DB2. The Call Attach Facility and RRS Attach Facility have a lot in common, providing more control over the DB2 connection than the prior facilities. So far so good. Now what about those Java programs? Details on making sure we're using the right attachment when we build our programs. 2 Abstract: The DB2 Attachment Facilities provide the interfaces between our programs and the databases. What are they? Which one should we use? This presentation will cover the basics of each of the attachment facilities along with how and when it should be used.

3 TODO Still very rough Need images for each attachment CICS needs definition work RRS need slide consolidation (and content reduction) CAF needs more content Include IMS? Include ODBS? Need Java Type 2 and Java Type 4 3

4 Environments and Attachments TSO CICS IMS CAF RRSAF TSO Interactive Y Y Y JDBC Type 2 JDBC Type 4 TSO Batch (Background TSO) CICS (including Java) IMS Y Y Y Y Y Batch (non-tso) Y Y USS (Interactive & Batch) Stored Procedure / User-Defined Function Y Y Java (local) Y Y Java (remote) Y 4

5 TSO Attachment Facility 5

6 TSO Environment to DB2 TSO programs have a choice of attachments available TSO Attachment Facility Call Attach Facility RRS Attach Facility The TSO Attachment has historically been used because it requires less programming effort. Drawbacks in the execution of those programs then becomes an effort. 6 For batch programs, the TSO Attachment Facility is usually used because it requires less work for the application programmers. The TSO Attachment Facility version of DSNHLI is included in module DSNELI. You should see an include for this in your link edit control statements.

7 TSO Attach Facility 7

8 DSN Command Provides the interface between TSO and DB2 Establishes connection DSN SYSTEM(ssid) Common Subcommands BIND PLAN/PACKAGE REBIND PLAN/PACKAGE RUN DCLGEN DB2 Commands (under DSN) -DISPLAY -START DATABASE 8 The DSN command resides in DBxx.SDSNLOAD which needs to be in STEPLIB/JOBLIB or the link list. If the appropriate Steplib is allocated, you can issue the DSN command within a TSO session and then issue any of its subcommands. The subcommands available under DSN include BIND, RUN, DCLGEN, -DISPLAY, - TERM, and a few others that are used less frequently. When you use the DB2I panels (including SPUFI) you are using IBM-supplied panels that invoke these commands. You can also run your batch programs using the RUN subcommand within your interactive TSO session (debugging utilities like Xpediter do this for you).

9 TSO Foreground Interactive TSO Users Includes those in ISPF/PDF DB2 Interactive screens - DB2I Includes SPUFI Not QMF QMF uses Call Attach Facility 9

10 TSO Background Execute IKJEFT01 or its variants IKJEFT01 Abend receives Condition Code 12 Execution continues with bad return codes IKJEFT1A Abend S04C for system abends Return code propagated for user abends Non-zero return codes stop processing (except CLISTs) IKJEFT1B Abend S04C for system and user abends Non-zero return codes stop processing 10 Running a program under the TSO Attachment Facility is not as simple as just loading the program and running it. This is the reason you cannot just code PGM=MYPGM on your JCL EXEC card to run the program. DB2 requires that an environment be set up at run time in order to execute the module. This TSO-based runtime environment is managed by a command/program called DSN. When running a batch program that uses the TSO Attachment Facility, you must have a TSO background session established by running program IKJEFT01 (or IKJEFT1A or IKJEFT1B). The background TSO session includes the DSN command (and subcommands) in the SYSTSIN input stream. Now, when your program is executed, the DSNHLI program (that was linked from DSNELI) interacts with the internal environment set up by the DSN RUN command/subcommand to talk to the designated DB2 subsystem. This version of DSNHLI must run within TSO as it was written to take advantage of the TSO infrastructure.

11 TSO Background Streams Background TSO execution substitutes streams for terminal interaction SYSTSIN input stream DSN SYSTEM(mydb2) RUN PROGRAM(myprogram) Supplies program id and plan name Optionally supplies load library and input parameters SYSTSPRT output stream 11

12 DSNZPARM Limits IDFORE Limits interactive TSO user connections Includes TSO users using CAF and RRSAF IDBACK Limits background connections Includes TSO background jobs Includes CAF and RRSAF jobs 12

13 TSO Attachment Summary Environments Module TSO Foreground, TSO Background DSNELI Non-SQL Calls Implicit Connection Group Attach Not available Yes, to DB2 subsystem specified in DSNHDECP Yes, DSN SYSTEM(db2g) Program Parms Multithreading Included in PARM() option of DSN RUN subcommand No Authorization Id Precompiler Option Commits Logged in userid (foreground) JCL USER specification (background) ATTACH(TSO) This is the default Single Phase Use SQL COMMIT and SQL ROLLBACK statements 13

14 CICS Attachment Facility 14

15 CICS Environments Programs running under CICS must use this attachment Yes, Java programs too Shipped as part of CICS Transaction Server Manage multiple connection threads Definitions managed using RDO (Resource Definition Online) transactions within CICS Stored in CSD file Connection managed using DSNC transaction 15 For programs that will run in a CICS region, you link DSNHLI from module DSNCLI.Under CICS, the DB2 interface is managed at the region level. The interface is usually started when the region comes up and it establishes communication between CICS and DB2. Each of the regions builds a set of subtask TCBs that are used for each program that is using a connection to DB2. The interface used to be in a module called DSNRCT00, where RCT stands for Resource Control Table. We still tend to call it the RCT even though it is now managed using CICS RDO (Resource Definition Online) commands. The RCT controls several aspect of the DB2 connection, including the authorization id that is sent to DB2 and the number of concurrently executable threads.when a program under CICS issues an SQL statement, it calls (the DSNCLI version of) DSNHLI to process the statement. The DSNHLI program links to the CICS/DB2 interface modules that are running in the region and uses one of the DB2 connections.all DB2 programs that run under CICS must use the CICS Attachment Facility.

16 CICS Attach Facility 16

17 DSNC Command Dynamic control of connection from CICS to DB2 DSNC DISPLAY STAT Displays one line of the statistical counters that are associated with each connection thread (DB2ENTRY) DSNC STOP QUIESCE Stops the CICS attachment facility DSNC STRT ssid Starts the CICS attachment facility DSNC MODIFY TRANSACTION tranid integer Modifies the maximum number of active threads 17 To change the maximum active thread value, use one of the following transaction IDs: - For the pool: CEPL - For command threads: DSNC - For DB2ENTRY: the ID of any transaction that is defined to use DB2ENTRY

18 Attachment Definitions DB2CONN Overall connection settings Defaults Command thread settings Pool thread settings DB2ENTRY Entry thread settings Including Plan, number of dedicated/protected entries May be wildcarded to associate multiple transactions DB2TRAN Associates additional transactions with and entry thread 18 Once known as the RCT (Resource Control Table), the CICS Attachment includes several definitions that are all managed in the standard manner of other CICS resources. The DB2 resources have several entries whose settings impact the connection to DB2 and the performance of the application programs that us it.

19 CICS Open TCBs 19

20 Pool Threads Defined with DB2CONN THREADLIMIT(n) Used for transaction when: No DB2ENTRY or DB2TRAN matches DB2ENTRY exists with THREADLIMIT(0) DB2ENTRY exists and THREADLIMIT(n) exceeded and THREADWAIT=POOL Operation Always unprotected (see next slide) Very unlikely thread reuse 20 There are four cases when a pool thread can be used: 1) A transaction is not specified in any DB2ENTRY or DB2TRAN, but issues SQL requests. This transaction defaults to the pool and uses the plan specified for the pool. 2) A transaction is specified in a DB2ENTRY or DB2TRAN referencing a DB2ENTRY, but is forced to the pool because the DB2ENTRY specifies THREADLIMIT(0) and THREADWAIT(POOL). This transaction uses the plan specified in the DB2ENTRY. 3) A transaction is specified in a DB2ENTRY or DB2TRAN referencing a DB2ENTRY, but overflows to the pool (THREADWAIT=POOL) when the THREADLIMIT value is exceeded. This transaction uses the plan specified in the DB2ENTRY. 4) A transaction is specified in a DB2ENTRY or a DB2TRAN referencing a DB2ENTRY, but the DB2ENTRY is disabled. The DISABLEDACT keyword is set to POOL, therefore a pool thread is used. This transaction uses the plan specified for the pool. Pool threads are always unprotected threads.pool threads are created, used, and terminated as follows: No thread TCBs are attached when the CICS DB2 attachment facility is started. A TCB is attached only if needed by a thread.a thread is created only when needed by a transaction.the thread is terminated immediately after it is released, unless it has a transaction queued f it Oth t ti i th l th d

21 Unprotected Threads Defined with a DB2ENTRY PROTECTNUM(0) THREADLIMIT(n) Operation No TCBs attached at CICS DB2 attachment startup TCB is attached only if needed by a thread Thread is created only when needed by a transaction If no thread is available, but an open TCB can be used a new thread is created and related to the TCB Thread is terminated immediately after it is release Unless a transaction is queued waiting for it 21 This is the recommended type of definition for: Critical transactions requiring a fast response time, but with a volume so low that a protected thread cannot be used. You could use a protected thread for limited concurrency transactions, if the transaction rate makes it possible to reuse the thread.unprotected entry threads for critical transactions are created, used, and terminated as follows: No thread TCBs are attached when the CICS DB2 attachment facility is started. A TCB is attached only if needed by a thread.a thread is created only when needed by a transaction. If no thread is available, but an open TCB can be used as a thread TCB for this DB2ENTRY, a new thread is created and related to the TCBThe thread is terminated immediately after it is released, unless it has a transaction queued for it. Other transactions specified to use the same DB2ENTRY can reuse a thread, if it is available. This happens only if a transaction is waiting for the thread when the thread becomes available. Overflow to pool

22 Protected Threads Defined with a DB2ENTRY PROTECTNUM(n) THREADLIMIT(n) Operation TCB is allocated to the prior to calling the CICS DB2 attachment facility A thread is created when existing thread is not available Up to PROTECTNUM threads are kept after thread termination Terminated if unused for two purge cycles. Reuse likely, but dependent on transaction volume 22 Using protected threads (by specifying PROTECTNUM=n on the DB2ENTRY definition for an entry thread) is a performance option that reduces the resources involved in creating and terminating a thread. A protected thread is not terminated when a transaction ends, and the next transaction associated with the same DB2ENTRY reuses the thread. By using protected threads, you eliminate much of the work required for thread creation and termination for individual transactions. For performance reasons, it is recommended that you use protected entry threads whenever possible, and especially where a transaction is frequently used, or issues many SYNCPOINTS. The main exception is when a transaction is infrequently used, because even a protected thread is likely to terminate between such transactions.from an accounting viewpoint, the situation is different. An accounting record is produced for each thread termination and for each new user signon. This means that only one accounting record is produced if the thread stays alive and the user ID does not change. This record contains summarized values for all transactions using the same thread, but it is not possible to assign any value to a specific transaction. This can be overcome by specifying ACCOUNTREC(UOW) to make sure an accounting record is cut per unit of work, or by specifying ACCOUNTREC(TASK) to make th i ti d t CICS t k S

23 Thread Reuse Reuse CICS DB2 threads to save CPU Application Considerations Close all WITH HOLD cursors before each syncpoint DB2 does not automatically close them and their existence prevents reuse. Close all cursors before ending (or sooner) Use plan with PKLIST Preferably with wild card for package name Grant plan/package execution to Public and specify ENABLE(CICS) on package binds CICS fixed application userid (specified in DB2CONN) Take care with RELEASE(DEALLOCATE) 23

24 Maximum Thread Reuse Create a single DB2ENTRY Assign many protected threads PROTECTNUM(20) THREADLIMIT(20) ACCOUNTREC(NONE) - cut only at thread termination Use '*' wildcard for transaction Associates all transactions with this entry Use AUTHTYPE(SIGN) and SIGNID(xxxx) All connections use same authid for DB2 Define plan for use of all transactions in CICS Use PKLIST(xxx.*) 24 Use ACCOUNTREC(TASK) in just one CICS region to get a representative sample of your real accounting.

25 CICS Java Considerations Use the default JDBC connection jdbc:default:connection Commit via JDBC (or SQLJ) are allowed Translated by the JDBC driver into JCICS Commits Use of Autocommit is not recommended JDBC driver defaults for AUTOCOMMIT(FALSE) for CICS 25

26 CICS Attachment Summary Environments Module CICS DSNCLI Non-SQL Calls Implicit Connection Group Attach Program Parms Multithreading Authorization Id Precompiler Option Not required No, subsystem specified in DB2CONN or region init settings and plan in DB2CONN or DB2ENTRY Yes, and default is to reconnect only to the same DB2 member subsystem for reconnection Not applicable Yes, managed by CICS Specified in DB2CONN or DB2ENTRY, may be USER, GROUP, TXID, SIGNID Commits Two Phase or Single Phase, controlled by CICS Use EXEC CICS SYNCPOINT and ROLLBACK 26

27 Call Attach Facility 27

28 Call Attach Facility A program that uses CAF can Access DB2 from address spaces where TSO, IMS, or CICS attachments do not already exist Connect to DB2 from multiple subtasks Access the DB2 IFI Run when DB2 is down Though it cannot access DB2 data 28 The Call Attachment Facility (CAF) was the original method that IBM provided where a program can control its own connection to DB2 rather than rely on either the CICS or TSO environment to be pre-established. The RRS Attachment Facility is now preferred over the CAF.Programs that use the Call Attachment Facility link DSNHLI from module DSNALI. They also call DSNALI directly to establish the DB2 connection, supplying the DB2 subsystem id and plan name. It is possible to omit these DSNALI calls and defaults will be determined based on the program name (for the plan) and the DB2 subsystem id loaded from module DSNHDECP (which is usually in library DBxx.SDSNEXIT in Steplib/Joblib). You may see DSNALI included in older stored procedures that run in the DB2SPAS address space.programs that use the Call Attachment Facility may be run in batch by specifying PGM=MYPGM on the JCL EXEC card. They may also be run from within TSO environments by loading the program as if it were a non-db2 program.

29 Call Attach Facility 29

30 Load or Link DSNALI Dynamically load DSNALI during execution Isolates load modules from DB2 maintenance Specify precompiler ATTACH(CAF) option Issue LOAD requests for DSNALI and DSNHLI2 DSNWLI2 if using IFI Link DSNALI into your load module DB2 maintenance may require re-linking Decide which of the following two methods you want to use to make DSNALI available: - Explicitly issuing LOAD requests when your program runs. By explicitly loading the DSNALI module, you beneficially isolate the maintenance of your application from future IBM maintenance to the language interface. If the language interface changes, the change will probably not affect your load module. - Including the DSNALI module in your load module when you link-edit your program. If you do not need explicit calls to DSNALI for CAF functions, link-editing DSNALI into your load module has some advantages. When you include DSNALI during the link-edit, you do not need to code a dummy DSNHLI entry point in your program or specify the precompiler option ATTACH. Module DSNALI contains an entry point for DSNHLI, which is identical to DSNHLI2, and an entry point DSNWLI, which is identical to DSNWLI2. A disadvantage to link-editing DSNALI into your load module is that any IBM maintenance to DSNALI requires a new link-edit of your load module.

31 Implicit Connections Use default DB2 subsystem Specified in DSNHDECP Use program name as plan name First program to execute SQL statement 31 Implicit connections to CAF If the CAF language interface (DSNALI) is available and you do not explicitly specify CALL DSNALI statements in your application, CAF initiates implicit CONNECT and OPEN requests to DB2. These requests are subject to the same DB2 return codes and reason codes as explicitly specified requests. Implicit connections use the following defaults: Subsystem name The default name that is specified in the module DSNHDECP. CAF uses the installation default DSNHDECP, unless your own DSNHDECP module is in a library in a STEPLIB statement of a JOBLIB concatenation or in the link list. In a data sharing group, the default subsystem name is the group attachment name. Be certain that you know what the default name is and that it names the specific DB2 subsystem you want to use. Plan name The member name of the database request module (DBRM) that DB2 produced when you precompiled the source program that contains the first SQL call. Different types of implicit connections exist. The simplest is for an application to call neither the CONNECT nor OPEN functions. You can also use the CONNECT function only or the OPEN function only. Each of these calls implicitly connects your application to DB2. To terminate an implicit connection, you must use the proper calls.

32 Call Attach Functions CONNECT Establishes an address space connection to DB2 OPEN Allocates a plan Can implicitly do Connect CLOSE Commits and deallocates the plan DISCONNECT Performs implicit CLOSE if necessary Use if explicit CONNECT was done 32 CAF connection functions A CAF connection function specifies the action that you want CAF to take. You specify these functions when you invoke CAF through CALL DSNALI statements. You can specify the following CAF functions in a CALL DSNALI statement: CONNECT Establishes the task (TCB) as a user of the named DB2 subsystem. When the first task within an address space issues a connection request, the address space is also initialized as a user of DB2. OPEN Allocates a DB2 plan. You must allocate a plan before DB2 can process SQL statements. If you did not request the CONNECT function, the OPEN function implicitly establishes the task, and optionally the address space, as a user of DB2. CLOSE Commits or abnormally terminates any database changes and deallocates the plan. If the OPEN function implicitly requests the CONNECT function, the CLOSE function removes the task, and possibly the address space, as a user of DB2. DISCONNECT Removes the task as a user of DB2 and, if this task is the last or only task in the address space with a DB2 connection, terminates the address space connection to DB2. TRANSLATE Returns an SQL code and printable text that describe a DB2 hexadecimal error reason code. This information is returned to the SQLCA. Restriction: You cannot call the TRANSLATE function from the Fortran language.

33 Call Attach Summary Environments Module TSO (Foreground or Background), UNIX System Services, batch jobs or started tasks DSNALI Non-SQL Calls Implicit Connection Group Attach Optional: Connect, Open, Close, Disconnect Yes, using default subsystem from DSNHDECP and program name as plan name Yes Program Parms Multithreading Authorization Id Passed using standard language mechanisms No Client address space userid Precompiler Option ATTACH(CAF) Commits Single Phase Use SQL COMMIT and ROLLBACK 33

34 RRS Attach Facility 34

35 What is RRSAF? Recoverable Resource Manager Services DB2 Attachment Facility Embedded SQL DB2 Commands IFI Transaction Management Connection control Advanced thread management 35 The RRS Attachment Facility (RRSAF) allows DB2 programs to control their connections similar to the Call Attach Facility (CAF). It also provides interfaces to the z/os Resource Recovery Manager Services features that allow programs to coordinate recoverable units across resource managers (like DB2, VSAM, and MQ Series). Programs that use RRSAF must include their DSNHLI from module DSNRLI. This includes DB2 stored procedures that run in WLM environments. When a program runs using RRSAF, it must also issue individual calls to DSNRLI to establish and terminate the DB2 connection. Details on these calls are in that article, but to issue the calls the program must know which DB2 subsystem to connect to and which plan to use. I prefer to supply these as input parameters to the program and have C and COBOL samples for doing this.you can run a program that uses RRSAF in batch (via EXEC PGM=MYPGM), under TSO, and under UNIX System Services (USS).Java applications that run on z/os are generally configured to use RRSAF.

36 RRS Attach Facility 36

37 Why do we need RRSAF? WLM Application Environments Stored Procedures User-Defined Functions Flexible program execution Batch TSO UNIX System Services WebSphere and Java Complex unit of work CICS (invoked from stored procedure) MQ Series 37

38 Complex Interactions 38 Stored procedures that run in WLM environments must use the RRS Attachment Facility by including DSNRLI in their link edit control statements. The individual calls to DSNRLI are done by DB2 itself on behalf of the stored procedure program so must not also be done within the program. All of the stored procedures that Brian developed for MWV fall into this category if you want to have a look at his link control cards.

39 How do we use RRSAF? Specify ATTACH(RRSAF) on precompile Include DSNRLI in load module Call DSNRLI to establish connection Identify Signon Create Thread Do normal SQL processing Control our unit of work Use Commit/Rollback for local transactions Use SRRCMIT/SRRBACK for global transactions Call DSNRLI to release connection (optional) 39

40 Commit or Rollback 40

41 Commit Transactions with global scope need to use the RRS functions to handle their commits and rollbacks. CALL SRRCMIT(&ReturnCode); CALL SRRBACK(&ReturnCode); Transactions that only use DB2 resources can let DB2 handle the commit. EXEC SQL COMMIT; EXEC SQL ROLLBACK; 41

42 Use the correct modules 42

43 Advanced API Calls Contexts Provide userid and secondary authids via RRS context Alternate Authids Provide userid Provide secondary authids Multiple Connections Used after successful Identify Must be issued prior to subsequent Identify After all connections made Use Switch To again to change current subsystem 43

44 Implicit Connection Connects to DB2 without explicit calls Handles IDENTIFY and CREATE THREAD calls No SIGNON call done Subsystem from DSNHDECP Plan from program name that executes first SQL statement Authid from allied agent address space SET_CLIENT_ID Allows setting of client userid, accounting token, etc. 44

45 RRS Attach Summary Environments Module TSO (Foreground or Background), UNIX System Services, batch jobs or started tasks, External Stored Procedures DSNRLI Non-SQL Calls Implicit Connection Group Attach Recommended: Identify, Signon, Create Thread, Terminate Thread, Terminate Signon Yes, using default subsystem from DSNHDECP and program name as plan name Yes Program Parms Multithreading Authorization Id Passed using standard language mechanisms No Address space userid or explicit specification Precompiler Option ATTACH(RRSAF) Commits Two Phase or Single Phase Use SQL COMMIT & ROLLBACK or SRRCMIT & SRRBACK 45

46 Java Connections 46

47 DB2 Universal Driver Java applications use the JDBC Driver to communicate with DB2 DB2 Universal Driver supports DB2 access from each platform/environment WebSphere Application Server Standalone applications Driver jar files db2jcc.jar db2jcc_license_cisuz.jar Enables access to DB2 for z/os 47

48 JDBC Connection Types Type 2 Local connection Uses RRS Attachment Facility Recommended when running on same system as DB2 Type 4 Network connection Enables some ziip offload (up to 50%) Pure Java DRDA Client implementation Recommended for distributed platform connections 48

49 JDBC Type 2 Connection 49

50 JDBC Type 4 Connection 50

51 Global Transactions Allow synchronization of multiple resources DB2 for z/os WebSphere MQ CICS (via CTG, perhaps) Java applications that are part of a global transaction Cannot use JDBC Autocommit Cannot use JDBC Commit() Cannot use JDBC Rollback() 51

52 Java Type 2 with Global Tran 52

53 Sysplex Distributor & Type 4 53

54 E05 DB2 Attachment Facilities John Maenpaa Health Care Service Corporation 54