Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved


Chapter 2 Operating Service Gateway for DB2 : Operations

Operations
Implementing External Security
External security is used only if SECLEVEL=1. The IBM-supplied exit DSN3@ATH is invoked each time a connection to DB2 is requested. Refer to the SCOPE parameter in Gateway Parameters for information on the duration of connections.
Security Process
DSN3@ATH passes control to the HRNSECD2 macro supplied by TIBCO Object Service Broker. HRNSECD2 performs the following checks:
Verifies that the user ID requesting to start the Gateway is authorized to do so. The table of authorized users is in the HRNSECDT macro.
Verifies that the DB2 connection requestor is not a privileged DB2 user ID (that is, SYSADM). The table of unauthorized users is in the HRNSECDZ macro.
If the DB2 connection requestor passes all the previous checks, HRNSECD2 then changes the DB2 primary authorization ID to the TIBCO Object Service Broker session ID or to the current group name depending on the setting of the EXTERNALUSERID gateway parameter. If the first of these checks fails, HRNSECD2 returns control to DSN3@ATH with no changes. If one of the remaining checks fail, a SECURITYFAIL exception is raised.
Secondary Authorization ID Processing
Depending on the external security interface you are using, the DSN3@ATH exit sets secondary authorization IDs as follows:
Sets the primary authorization ID and calls CA-ACF2 to acquire secondary authorization ID information for each thread connection.
Assumes that the primary authorization ID used to start an address space is the DB2 primary authorization ID and that its associated secondary authorization IDs are used for all thread connections.
The external security interface changes only the primary authorization ID to the DB2 connection requestor; it does not remove the secondary authorization IDs from the security control block built by DSN3@ATH for RACF. Ensure that the RACF user ID that starts the Gateway does not have any secondary authorization IDs associated with it. This ID also does not require any DB2 security authorization.
 
3.
If Fail Safe level 1 is requested, ensure that the RECOVERYID gateway parameter is set to an appropriate authorization ID since the ID that starts the Gateway is the default recovery ID.
Installing the External Security Interface
Depending on which external security interface you are using, the sample source for the DSN3@ATH exit is located as follows:
The HRNSECD2, HRNSECDT, and HRNSECDZ TIBCO Object Service Broker macros are located in the MACRO data set distributed with TIBCO Object Service Broker. Installation instructions for each macro are detailed in the header information.
Implementing Fail Safe Processing
Fail Safe level‑1 processing guarantees consistency when updating both TDS and DB2 data from a single Gateway in a single transaction. At the end of a transaction, the Data Object Broker requests that the Gateway commit outstanding updates. As part of DB2 commit processing, the Gateway updates a DB2 transaction table to record the successful commit. If the Gateway does not respond to the Data Object Broker in a reasonable amount of time, the transaction is flagged as being in doubt. Locks held on TDS data remain until the problem is resolved.
When a connection is re-established between the Data Object Broker and an instance of the Gateway with the same configuration as the one that failed, the Data Object Broker asks the Gateway if the in-doubt transaction completed. The Gateway checks the DB2 transaction table to determine this. If the update was completed in DB2, the TDS updates are applied and the locks are released.
You can resolve in-doubt transactions only by starting an instance of the Gateway with exactly the same parameter settings as the Gateway in use at the time the transaction was placed in doubt.
See Also
Refer to TIBCO Object Service Broker for z/OS Managing Backup and Recovery for more information on Fail Safe processing.
Procedural Overview
To implement Fail Safe Processing, you must complete the following tasks:
1.
2.
3.
These tasks are described in the following sections.
 
Task A Define a DB2 transaction table
To implement Fail Safe level‑1 processing, you must define the DB2 table found in the CNTL data set in member XDB2TRXD. Do not change the DB2 Column definitions. This transaction table holds a maximum of one record for each combination of the Gateway and Data Object Broker.
Task B Define a TIBCO Object Service Broker DB2 transaction table
After defining a DB2 transaction table you must define a TIBCO Object Service Broker DB2 transaction table that points to the DB2 transaction table. A sample of this table is @DB2FSTRXDB, which uses server ID DEFAULT and points to the DB2 table creator.HRNTRXDB.
Task C Modify the Gateway Fail Safe startup parameters
Ensure that the following gateway startup parameters are included in your Gateway startup JCL:
TRXDB=creator.tablename
For more information on these startup parameters, see Gateway Parameters.
At startup, the Gateway asks the Data Object Broker for the TIBCO Object Service Broker DB2 transaction table definition specified in the FSTABLENAME gateway startup parameter. This table definition is bound for the life of the Gateway and is used at transaction end to update the DB2 transaction ID database.
You can manage the transaction table in TIBCO Object Service Broker like any other DB2 table. For example, you can write a TIBCO Object Service Broker rule to clean up the Fail Safe database when shutting down the Gateway.
Other Operational Procedures
Adding Gateway Threads
The number of Gateways attached to the Gateway address space is specified in the Gateway startup JCL. You can use either of the following methods to add additional Gateways:
Shut down the Gateway and start it again with an increased number of Gateway (using the SERVERS gateway parameter).
Using Distributed Data with the Gateway
Distributed access between TIBCO Object Service Broker and DB2 is allowed subject to requirements of all distributed access. Refer to TIBCO Object Service Broker Application Administion and TIBCO Object Service Broker for z/OS Installing and Operating for information on distributed access.
This illustration shows a sample Gateway distributed-data scenario:
Displaying the Status of instances of the Gateway
Use the RESOURCE MANAGEMENT option from the Administration menu to display the status of an instance of the Gateway. The sample screen below shows the type of information displayed for resource type DB2.

 
S6BADM33 HTSTSRV RESOURCE DETAIL FOR DB2 DB2SRV 2000JAN02 16:40:52
INTERMEDIATE ROLLBK N EARLY RELEASE Y LAST USER REUSE N COMMIT LEVEL 0
RETRY INTERVAL 0 TP NAME USER ID PREFIX FAILURES 0
NODE MMMSYSTEMA01 INDOUBTS N DELETE
CONNECTIONS IN-USE TRX MESSAGE
CUR MAX LMT CUR MAX COUNT COUNT
ONLINE 0 0 0 0 0 0 0
COMMON 0 0 25 0 0 0 0
SCHEDULE NAME IMSIMSDRASV
APPLICABLE DAYS EXCEPTION START ONLINE CONNECTIONS
MON TUE WED THR FRI SAT SUN DATE TIME ONLY MAX
Y Y Y Y Y Y 00:00 N 25
ENTER-PATHS PF2-TYPE PF4-GROUP PF5-PEER PF9-START PF10-SCHEDULES PF11-UPDATE
THERE ARE NO ACTIVE PATHS TO BE DISPLAYED, REQUEST IGNORED

 
Debugging Rules and Applications
The Rule Debugger helps you identify and fix errors within your application. You can also make and test certain ad hoc changes to your rules. The Debugger stops the rules execution at events specified from within the Debug screen.
To determine the SQL statements being sent to DB2 by your rules, include the TRACE parameter in your Gateway startup JCL. The SQL statements for all DB2 table accesses are included in the trace. To view only SQL statements created by your rules, you require a dedicated Gateway. This can be accomplished using the SERVERID gateway startup parameter. To change the server ID of a TIBCO Object Service Broker DB2 table definition to an alternate dedicated server ID, execute the CHANGE_SERVERID tool as follows:
CHANGE_SERVERID(table_name,old_serverid,new_serverid)
When the trace shows the application is using Static SQL, it displays the handler load module and cursor name. You must review the Static SQL handler assembler code to see the SQL statements associated with the named cursor.
Reporting Problems
Refer to How to Contact TIBCO Support for information about reporting problems. Have the following information available when reporting the Gateway related problems to TIBCO Support:
See Also
TIBCO Object Service Broker Application Administion and TIBCO Object Service Broker for z/OS Installing and Operating for more information on distributed access.
TIBCO Object Service Broker for z/OS Installing and Operating for more information on the RESOURCE MANAGEMENT option.
TIBCO Object Service Broker Programming in Rules for more information on debugging rules and applications.

Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved