Resolution:
These parameters are all used to configure different types of servers within an TIBCO® Object Service Broker configuration. A typical configuration might consist of the following component address spaces on z/OS:


[Client/Command Language Interface (CLI/SDK) or 3270 green screen] (#1)
    <--> [Execution Environment (EE)] (#2)
      <--> [Data Object Broker (DOB)] (#3)       <-->   [Peer Data Object Broker (DOB)] (#5)]  
        <--> [Service Gateway for IMS/DB2 etc] (#4)

The client, entity #1, provides a window for the end user to execute rules and access data from various external data base systems. The CLI client connects to the Execution Environment (EE) which is entity #2. The EE is responsible for running rules and manipulating data. Requests for rules and data are made by the EE to the Data Object Broker (DOB), entity # 3. Rule requests are satisfied by the DOB locally but external database requests are passed through the DOB and sent to the appropriate Service Gateway which is entity #4. The Service Gateway interacts with the external database server software, such as IMS or DB2 etc, to obtain the data and pass it back through the DOB to the EE.

At each point of this chain, parameters are used to configure the different entities. In addition, the z/OS Data Object Broker (DOB) uses a special interface accessed through TSO called S6BTLADM (ADMIN clist) to define resources connecting to the DOB such as for Service Gateways for IMS and DB2.


Call Level Interface (CLI):
===========================
STANDBYNUM= sets the number of standby sessions that are started in an EE to service CLI client sessions connecting to the EE. An unused "standby" session is selected from a pool and the remote client is then authenticated and logged on to the DOB as if the client were connected to the EE directly. This interface is used to support the User Interface client which runs on Windows using Eclipse but you can write your own clients. TIBCO BusinessWorks (TM) OSB Plug-in also uses this interface. See TIBCO Object Service Broker for z/OS External Environments for more information on CLI Clients. Languages supported include C/C++/Java etc. When the client session ends, the standby session is returned to the pool for use by another client in the future.

When specifying STANDBYNUM, you must ensure that sufficient signon tasks are provided in your z/OS EE. This is especially critical in a CICS EE where extra processing occurs under the signon task and where insufficient signon tasks can cause a CICS hang or maxtask condition. You can control the number of signon tasks by using the TASKINITNUM parameter. To avoid running out of this resource, specify TASKINITNUM to twice the value of STANDBYNUM expecially in a CICS environment.

If you are connecting from an environment outside of z/OS by TCP/IP, you will also need to configure your TCP/IP Relay component so that the listening port and IP address are defined to the Relay. This is only required for entities that accept TCP/IP connection. To configure an EE for TCP/IP connections, review the information in the TIBCO Object Service Broker for z/OS Installing and Operating manual Appendix B Configuring TCP/IP. Basically you define a communications identifier using the EE parameter EENAME= making sure that the identifier does not end with a numeric. Then define the EENAME, port and IP address used by the EE to the Relay Parameter File using XML.

For 3270 connections, you will need to define the EENAME to VTAM as an application logical unit and use TCP port 23 to begin a mainframe VTAM session and connect to the EE using a LOGON APPLID(eename) command.


Execution Environment (EE)
==========================
The use of EENAME has already been discussed. This parameter can be set by either running EECONFIG assembly and linkedit job or by overriding the value in the EE JCL using the DD statement //HRNIN DD *

Make sure that the EENAME does not end with a numeric as the name will then be interpreted as a pattern rather than a specific name that will not change at port open time. Patterns are useful for say batch jobs or TSO sessions that are never targets of logon requests. Usually the parameter MDL=&ltprefix>&ltnumeric suffix> is used to set the pattern but this function is the same as EENAME internally although EENAME always overrides the value specified for MDL.

Remote Peer Access
If you are supporting remote peer access to your z/OS data then you will need to define some peer server sessions to run in your Execution Environment (EE) to service remote requests. This is done by using the following EE parameters:

PEERSERVERID (EE)
The name of the peer server to be started within the Execution Environment in order to service remote data access requests.

This parameter is also used to name the Gateway for Files server. See the TIBCO® Object Service Broker Managing External Data manual, chapter "Installing and Using TIBCO Service Gateway for Files" for more information concerning configuration of the Gateway for Files component.


PEERSERVERNUM (EE)
The number of peer servers within an Execution Environment to be started up for a Data Object Broker using the same startup parameters with the same SERVERID.

To have the peer server sessions work, you will also need to use the S6BTLADM/ADMIN clist to logon to the DOB and define API type resources to the DOB's Resource Manager component. See the TIBCO® Object Service Broker for z/OS Installing and Operating manual section Resource Management.


Data Object Broker (DOB)
========================
The Data Object Broker (DOB) does have parameters to control its configuration but the definitions to support remote peer access and external Service Gateways are made through the S6BTLADM/ADMIN clist. All definitions are managed by the DOB's Resource Manager component. For more information, see the TIBCO® Object Service Broker for z/OS Installing and Operating manual section Resource Management.

External Service Gateway Resources:
To provide external database access, you will need to define each Service Gateway connecting to the DOB. Each type of server has its own type: "IMS", "DB2" and etc. Check with the documentation for the specific Service Gateway being used to see what definitions are required in the DOB. Typically you will need to define a SCHEDULE setting the number of threads supported and their availability plus the recovery failsafe level in use for the server. Usually Service Gateway servers execute in their own z/OS address spaces, but some servers can execute within an Execution Environment (EE). In this case, the parameters may be specified through a combination of EECONFIG JCL, //HRNIN DD overrides and DD names specific to the server at hand, such as //IMSSRV00 DD for IMS Service Gateways.


Remote Peers:
As mentioned, Remote Peer connections allow separate DOBs to access data owned and controlled by remote DOBs. To support this, you need to:
1) define connections between the Data Object Brokers. On z/OS, two types of connections will be made: HRN for inbound requests from a remote DOB and HIN for local requests to be shipped to a remote peer DOB
2) remote peer server sessions used to process remote requests for data. This concept is very similar to "mirror processing" implemented in CICS/TS for functions shipping.

Connections between DOBs are made using the S6BTLADM/ADMIN clist. Connections will be made in pairs so that a HIN connects via a HRN definition in the remote peer DOB and vice versa:
  HIN (inbound) <--- HRN (outbound)
  HRN (outbound) ---> HIN (inbound)
Once traffic flows over the connection, each pair can send and receive data bi-directionally. Initial requests are always sent by the local DOB over a HRN connection to the remote DOB's HIN pair. The connections will be z/OS cross memory managed if on the same LPAR; otherwise, TCP/IP Relay is recommended. If using TCP/IP, you will need to define the DOB's COMMID, port and IP address to the Relay Parameter File using XML and also the remote peer DOB's COMMID as well.

The HIN and HRN connections are independent of each other and are defined to the DOB's Resource Manager component. You should try to have equal numbers of pairs defined; otherwise, sessions will fail to connect since their counterpart will be missing.

In addition to defining the physical DOB peer connections, you will also need to configure some remote peer server sessions. See the discussion above for Remote Peer Access and the EE. You will need to define API resources to the DOB's Resource Manager to match the EE's PEERSERVERNUM value.



Service Gateway for IMS/DB2 etc
===============================
When accessing external database data, you will need to configure Service Gateways. At least one is required for each database type being accessed, although "DB2" and "IMS" types can be combined using the DOB's Resource Manager type of "IM2" resource. Other common resource types for Service Gateways include "DB2", "IMS". If you are running your gateway on Windows but connected to a z/OS DOB, you may access ODBC or Oracle databases. See TIBCO Service Gateways™ for ODBC and Oracle Installing and Operating manual for more information on non-z/OS database configurations.


On z/OS, each server will have a resource identifier associated with it. This is to allow requests to be sent to a specific service gateway which has the ability to satisfy the data request. The id is assigned through use of the SERVERID parameter:

SERVERID (Service Gateway or EE parameter)
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 for IMS is DEFAULT and for DB2.
This parameter can be overridden at runtime.  

The SERVERID can be specified in the table definition for the database being accessed. This enables the DOB to send the request for data to a Service Gateway component that can satisfy the data request. EE rules can also select which SERVERID they wish to service their database access request by invoking the tool CHANGE_SERVERID.

SERVERS (Service Gateway or EE parameter)
The maximum number of server sessions that are managed in this Execution or Service Gateway environment. Define enough connections (threads) to the z/OS DOB's Resource Manager to allow this number of connections to be made. See the specific


References:
TIBCO Service Gateways™ for ODBC and Oracle Installing and Operating
TIBCO Service Gateway™ for DB2 Installing and Operating
TIBCO Service Gateway™ for IMS/DB Installing and Operating
TIBCO® Object Service Broker for z/OS Installing and Operating
TIBCO® Object Service Broker Managing External Data
TIBCO® Object Service Broker Parameters
TIBCO® Object Service Broker Shareable Tools