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


Chapter 2 Operating the Service Gateway for IMS/DB : Supplying Gateway Startup Parameters

Supplying Gateway Startup Parameters
You can specify gateway parameters in the HRNIN DD statement, in the startup JCL, or in the IMSSRV00 SYSIN file. For more information, refer to Specifying Gateway Parameters.
HRNIN Parameters
The gateway parameters you specify in the HRNIN DD statement are:
 
Valid only for an instance of the Gateway using the CICS Interface. This is the TIBCO Object Service Broker transaction identifier (trans ID) that the CICS Execution Environment assigns to all CICS transactions associated with the Gateway. It is recommended that you specify HURN.
 
 
The pattern for selecting the VTAM ACB name that the Gateway uses for communications. If not specified, the Gateway uses the TDS parameter as the pattern. If you do not specify this parameter, ensure that the TDS parameter is a valid VTAM ACB model. For example, if TDS=OSB001 and you do not include this parameter, the model OSBnnn is used.
 
The number of Gateway tasks to initialize. For Gateways using the DL/I or BMP interface the value must be 1 or not supplied. For Gateways using the DRA and CICS interface the default is 1. This number can be from 1 to a value less than or equal to the value set in the Maximum Connection Count field in your Network Configuration. For more information, refer to the TIBCO Object Service Broker for z/OS Installing and Operating manual.
 
 
Valid only for an instance of the Gateway using the DL/I or BMP interface. The parameter string must be passed to DFSRRC00. The default for an instance of the Gateway accessing only IMS data is 'DLI,S6BDRSSR,S6BIMSS,,,,,,,,,,,N,,,Y'. The default for an instance of the Gateway concurrently accessing IMS and DB2 data is 'DLI,DSNMTV01,S6BIMSS,,,,,,,,,,,N,,,Y'.
 
 
Gateway for IMS concurrently accessing IMS and DB2 data running in a Batch Execution Environment and using the DL/I or BMP interface to IMS.
Gateway running in a Native Execution Environment, concurrently accessing IMS and DB2 data, and using the DL/I or BMP interface to IMS.
 
Supplies the communications identifier of the Data Object Broker with which the Gateway communicates. This parameter is required and does not have a default.
IMSSRV00 Parameters
The Gateway parameters you specify in IMSSRV00 are:
 
Has meaning only if SECLEVEL=1. Specifies the System Authorization Facility (SAF) class name to which the RESOURCE parameter value belongs. Valid entries are from 1 to 8 bytes long. This name and the name specified for the RESOURCE parameter are used by the Gateway when issuing the SAF RACROUTE REQUEST=AUTH macro to determine if the TIBCO Object Service Broker session ID, current security group, or a combination of both has access to the resource-level security. Refer to Implementing External Security for more information.
 
Has meaning only if SECLEVEL=1. The SAF security class under which the IMS databases are secured and defined.
 
 
Has meaning only if SECLEVEL=1. The default is NO. This parameter is documented in the RACF External Security Interface (RACROUTE) Macro Reference IBM manual for z/OS and VM. Depending on the external security package you are using, specify one of the following:
 
Security such as CA-ACF2 or CA-Top Secret is being used. REQSTOR and SUBSYS are used to verify SAF control point and subsystem. Review the defaults for these parameters and modify if required.
 
Use this parameter only in development or if you enable ad hoc access to IMS through TIBCO Object Service Broker to avoid IMS database scans that overload IMS lock pools.
Controls the number of update DL/I calls the Gateway can perform within a DL/I unit of work. If the limit is exceeded, the Gateway returns a COMMITLIMIT error with the appropriate message. After a COMMITLIMIT error the only valid request is a COMMIT/ROLLBACK; any other request terminates the DL/I unit of work with a ROLLBACK and the Gateway returns a SERVERFAIL. IMS calls GHU, GHN, and ISRT are counted in the update limit. The default is 0. Valid values:
 
Limit on number of GHU, GHN, and ISRT calls within one TIBCO Object Service Broker transaction.
 
Use this parameter only in development or if you enable ad hoc access to IMS through TIBCO Object Service Broker to avoid IMS database scans that overload IMS lock pools.
Controls the number of query DL/I calls the Gateway can perform within a DL/I unit of work. If the limit is exceeded, the Gateway returns a COMMITLIMIT error with the appropriate message. After a COMMITLIMIT error the only valid request is a COMMIT/ROLLBACK; any other request terminates the DL/I unit of work with a ROLLBACK and the Gateway returns a SERVERFAIL. IMS calls GU and GN are counted in the query limit. A GU or GN call acquires an IMS record lock if PCB procopt = a/i/r/d (update). The lock is released after the application removes positioning from the record unless the record is updated. The default is 0. Valid values:
 
 
Has meaning only if SECLEVEL=1 and EXTERNALUSERID=USERID. Specifies the use of both the TIBCO Object Service Broker session ID and current security group name to verify access to IMS resources. Do not include this parameter if EXTERNALUSERID=GROUP. If the value of the current security group exceeds 8 bytes, only the TIBCO Object Service Broker session ID is used. Refer to Establishing the TIBCO Object Service Broker Authorization ID for more information.
 
Has meaning only if SECLEVEL=1. Specifies the use of the TIBCO Object Service Broker session ID or the current security group name to verify access to IMS resources. The default is USERID. Refer to Establishing the TIBCO Object Service Broker Authorization ID for more information.
 
The current security group. This group can be up to 16 characters, but only 8 characters are supported. A SECURITYFAIL is signalled for more than 8 characters.
 
 
Activate Fail Safe Level 1. The Gateway informs the Data Object Broker that it can support Fail Safe level‑1 processing. If the Gateway is to attach to a z/OS Data Object Broker, the Data Object Broker’s connection attribute setting “commit level” must be set to 1. If not, the Gateway connection is rejected. Refer to Implementing Fail Safe Processing for more information.
De-activate Fail Safe processing. The Gateway informs the Data Object Broker that it does not support Fail Safe level‑1 processing. If the Gateway is to attach to a z/OS Data Object Broker, the Data Object Broker’s connection attribute setting “commit level” must be set to 0. If not, the Gateway connection is rejected. Refer to Implementing Fail Safe Processing for more information.
 
Required only if FSLEVEL=1. Specifies the name of the DB2 table that maps to the DB2 or IMS transaction database. The default is @IMSFSTRXDB for IMS and @DB2FSTRXDB for concurrent access to IMS and DB2 data.
 
If you also specify the TRXDB parameter, the system uses the TRXDB userid.trxdb and replaces the DB2 userid and trxdb in the DB2 table specified in FSTABLENAME.
If you have multiple instances of the Gateway with the same SERVERID, the FSLEVEL, FSTABLENAME, and TRXDB gateway parameters must have the same values for each instance.
 
Specifies a unique name for each instance of the Gateway. Each Gateway must have a unique IDPREFIX and it must be a valid level‑1 TIBCO Object Service Broker user ID. The Gateway uses this parameter as the Gateway connection identifier when connecting to the Data Object Broker. This parameter can have up to eight characters. The default is IMS01.
 
If you have multiple instances of the Gateway using the CICS interface and connecting to the same Data Object Broker, ensure the first five characters of the IDPREFIX are unique.
If USERTYPE=LOCAL, the Gateway appends four decimal digits to the first four characters of the prefix.
 
Determines whether the Gateway operates in update (UPD) or read-only (RO) mode. If MODE=RO, update requests are rejected. The default is UPD.
 
Provides the DB2 plan name if using the BMP interface. If omitted, the DB2 PLAN name defaults to the PSBNAME. For more information, refer to TIBCO Service Gateway for DB2 Installing and Operating.
 
Sets the amount of space (in KB) to hold IMS or DB2 table definitions in the Gateway, to a maximum of 16384 KB. The default value is 256. An estimate of the number of IMS or DB2 tables that can be accessed in a single transaction is POOLSIZE divided by CTABLESIZE. Refer to Estimating the CTABLESIZE Parameter for more information.
 
Has meaning only if SECLEVEL=1. The SAF security class under which the IMS Program Specification Blocks (PSBs) are secured and defined.
 
Provides the Gateway with the default PSB name. This PSB is scheduled if no other value can be ascertained from the transaction. The default is S6BIMSS.
 
Has meaning only if FSLEVEL=1 and SECLEVEL=1. Sets the TIBCO Object Service Broker authorization ID that you want to use during recovery when querying the IMS transaction database to see if the transaction completed (in-doubt transactions). This parameter can be up to eight characters. The default is the ID used to start the Gateway.
 
If you have multiple instances of the Gateway with the same SERVERID, ensure that the FSLEVEL, FSTABLENAME, RECOVERYID, and TRXDB gateway parameters have the same values for each Gateway.
 
Has meaning only if SECLEVEL=1 and DECOUPL=NO. The default is S6BIMSS. Specifies the SAF control point name to use when issuing SAF security calls. The value specified identifies the program or piece of code issuing the request.
The REQSTOR parameter is documented in the External Security Interface (RACROUTE) Macro Reference IBM manual for z/OS and VM.
 
Has meaning only if SECLEVEL=1. Specifies the name of the resource such as the IMS transaction, a group of transactions, the PSB name, an Application Group Name (AGN), or any other site specific value that uniquely identifies the Gateway session. Valid entries are from 1 to 8 bytes long.
Using the names specified for this and the CLASS parameter, the Gateway issues the SAF RACROUTE REQUEST=AUTH macro. This determines if the TIBCO Object Service Broker session ID, the current security group, or a combination of the two has access to the specified class/resource combination. Refer to Implementing External Security for more information.
 
The mode that the Gateway uses to respond to requests. You can use this mode to free up a Gateway more quickly for a new transaction in read-only situations. For use only with a Data Object Broker on z/OS. The default is ASYNC. Valid entries:
 
The Data Object Broker releases the Gateway from the TIBCO Object Service Broker transaction when the end of transaction request is sent, provided no updates are requested. The next transaction can then be scheduled before the previous transaction is completed. ASYNC is recommended for online Gateways. If SYNC is used, performance can be affected.
Causes the Data Object Broker to wait for the Gateway to complete end of transaction processing. SYNC is recommended for Gateways running in batch mode.
 
The length of time to hold the connection between an instance of the Gateway and a IMS subsystem. The defaults are SESSION for a Gateway running in a non-CICS environment and TRANSACTION for a Gateway running in a CICS environment.
 
Hold the connection for the life of the Gateway. The connection is not established until the first request for IMS data is processed by the Gateway.
Hold the connection for nnnn seconds beyond the end of theTIBCO Object Service Broker transaction. Valid entries are 0-9999.
 
 
The TIBCO Object Service Broker session ID, current security group, or a combination of the two is used to verify access to the specified combinations of CLASS, RESOURCE, PSBCLASS, DBDCLASS, SEGCLASS, IMS PSBs, IMS databases, and IMS databases/segments. Refer to Implementing External Security for more information.
 
Has meaning only if SECLEVEL=1. The SAF security class under which IMS databases/segments, and PSBCLASS and PSBs are secured.
 
Identifies a pool of Gateways with common characteristics. If you have multiple instances of the Gateway with the same SERVERID, ensure that the FSLEVEL, FSTABLENAME, RECOVERYID, and TRXDB gateway parameters have the same values for each Gateway. This parameter can be up to eight characters long. The default is DEFAULT.
 
Has meaning only if SECLEVEL=1 and DECOUPL=NO. Specifies the subsystem name for the SAF security call. The default is HURON.
This parameter is documented in the External Security Interface (RACROUTE) Macro Reference IBM manual for z/OS and VM.
 
Valid only for an instance of the Gateway executing in a CICS Execution Environment. Specifies where to get the PSB name and whether to check the PSB name specified with each IMS table accessed in a TIBCO Object Service Broker transaction. The default is TRANSACTION. Valid entries:
 
The PSB specified by the first IMS table accessed in a TIBCO Object Service Broker transaction is used.
If the first IMS table accessed in a transaction does not contain a PSB, the PSB specified by the PSBNAME parameter in the IMSSRV00 SYSIN file is used.
When a PSB is established, it is used for all subsequent TIBCO Object Service Broker IMS access requests for the duration of the transaction.
The PSB specified by the first IMS table accessed in a TIBCO Object Service Broker transaction is used.
If the first IMS table accessed in a transaction does not contain a PSB, the PSB specified by the PSBNAME parameter in the IMSSRV00 SYSIN file is used.
All remaining IMS tables accessed in the transaction must specify either the same PSB or no PSB. If there is a discrepancy, the transaction fails.
 
Logs the Segment Search Arguments (SSAs) built by TIBCO Object Service Gateway for IMS/DB and sent to the CICS Execution Environment. It also includes additional information similar to the DL/I Trace Facility. To activate the TRACE you must configure the following:
 
Include the TRACE parameter for error resolution only. For Service Gateway for IMS, the TRACE parameter also turns on SQL tracing in the HDBTRACE DD. For more information, refer to TIBCO Service Gateway for DB2 Installing and Operating.
 
The transaction database. Required only if FSLEVEL=1. For access to IMS data only, this parameter specifies the name of the IMS transaction database.
For concurrent access to IMS and DB2 data, it is required only if the actual Fail Safe DB2 transaction table name and creator are different than the ones that the DB2 table name specified using the FSTABLENAME parameter points. The name of the DB2 transaction file to contain information about the last transaction processed by the Gateway.
 
If you have multiple instances of Gateway with the same SERVERID, the FSLEVEL, FSTABLENAME, RECOVERYID, and TRXDB gateway parameters must have the same values for each Gateway.
 
The type of user that can connect to this Gateway. When allocating an instance of the Gateway, the Data Object Broker first tries to allocate an online user to an online Gateway. If it cannot, it allocates the user to a Gateway with USERTYPE=ANY. For use only with a Data Object Broker on z/OS. Valid entries:
 
Enables batch and online users to use the Gateway. This is the default for Gateways running in a Batch or Native Execution Environment.
Causes the SERVERID to be replaced by a unique identifier (the Gateway jobname). Reserves the Gateway for user sessions executing in a Batch or CICS Execution Environment as the Gateway. Not valid for online Gateways.
For Gateways running in a Batch Execution Environment, a unique IDPREFIX is created to enable the execution of all batch jobs with the same IDPREFIX value.
Reserves the Gateway for online users only. This is the default for Gateways running in a CICS Execution Environment.
In the following table, a checkmark indicates a valid user type according to Execution Environment.
Y (deflt)
Y (deflt)
 
Specifies how the Gateway should behave at Gateway initialization when one or more databases defined in the Gateway PSB are not available. For Gateways executing in a CICS Execution Environment, this parameter has meaning only if THREADUSAGE=SESSION. Valid entries are CALL and STARTUP. The default is CALL. Depending on the setting of this parameter and the type of Gateway, the following actions occur:
 
Database access is determined at the time of the DL/I call.
Gateway using the DL/I or BMP interface with THREADUSAGE=SESSION
When the Gateway starts, the status of any unavailable database appears in the Gateway job log. If the IMS status code NA or NU is encountered Gateway initialization fails, otherwise, initialization completes.
Gateway using the CICS interface with THREADUSAGE=SESSION
When the Gateway starts, the status of any unavailable database appears in the Gateway job log, the PSB terminates, and Gateway initialization completes.
If this parameter is set to CALL and access to an unavailable database is requested, the ERROR exception is raised and the corresponding IMS status code (NA or NU) is passed back to TIBCO Object Service Broker.
Estimating the CTABLESIZE Parameter
When you select IMS fields as TIBCO Object Service Broker IMS fields, the number of fields you can access using an IMS table definition is dependent upon the CTABLESIZE Data Object Broker parameter. To estimate the number of bytes required to support a specified number of fields, execute the following rule:
ESTIMATETBLDFN(num_fields)
You must supply one argument, which is the maximum number of fields accessed by an IMS table in your system. The rule returns an estimate of the maximum CTABLESIZE required (for each TIBCO Object Service Broker table type) to support this number of fields.
Result of Executing ESTIMATETBLDFN for 50 Fields

 
----------------------------- INFORMATION LOG --------------------------------
COMMAND ===> SCROLL ===> P
DATE: Nov 28,2006 REPORT ON ESTIMATE CTABLESIZE
FOR "50" FIELDS
 
Table Type CTablesize(K) XTablesize(K)
---------- ------------- -------------
 
ADA 5
DAT 7
DB2 5
IDM 6
IMS 6 3
MAP 4
SLK 4
TDS 3
 
 
 
 
 
 
 
PFKEYS: 2=NEXT LOG 3=EXIT 5=REPEAT FIND 12=EXIT 13=PRINT 9=RECALL

 
See Also
TIBCO Object Service Broker for z/OS Installing and Operating for more information on the CTABLESIZE parameter.

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