Resolution:
Description: Defining peer server sessions in a z/OS environment.

Object Service Broker systems can be connected so that data can be accessed remotely from other systems running in remote z/OS systems. To access remote data you must define paths between your local Data Object Broker (DOB) and the remote Data Object Broker (DOB). Although systems may be connected across disparate operating systems (z/OS, Windows and Solaris are supported), this solution only will speak about z/OS to z/OS peer connections.

In addition to defining peer connections, you must also provide a remote Execution Environment (EE) running peer server sessions to service the remote data access requests at the remote system.

In z/OS the DOB connections are made through the Resource Management component of the S6BTLADM utility which runs as a Time Sharing Option (TSO) application using the ADMIN clist. For information on defining the peer connections, see the "TIBCO® Object Service Broker for z/OS Installing and Operating Software Release 5.0" Chapter 12 Managing TIBCO Object Service Broker Networked Resources for information on defining these resources. The outbound connection, type "HRN" is used to send originating requests to the remote DOB while the "HIN" type connections are used to receive requests sent over a HRN connection.

                               (Local DOB-"A")         (Remote DOB-"B")
Execution Environment (EE) <----> API
                                  HRN +---------//--------> HIN
                                  HIN <---------//--------+ HRN
                                                           API <----> Execution Environment (EE)

Once a request is sent outbound on a HRN connection, traffic flows both directions over the connection until the request / unit of work is completed.

In addition to the HIN/HRN connections, you must also define API sessions using the same Resource Management utility in S6BTLADM ADMIN. You can define the maximum number of API sessions allowed and give it a name. Use of "DEFAULT0" is recommended unless you need to distinguish between API servers on the same system. You might do this if VSAM files, for instance, are owned by a particular CICS system and not available to other API servers connected to your remote DOB. See the "TIBCO® Object Service Broker Managing External Data Release 5.0" for additional information on specifying the SERVERID on table definitions and to the server using PEERSERVERID EE parameter.

After defining the appropriate API server definitions using S6BTLADM, you will need to add PEERSERVERNUM= to your EE HRNIN or EECONFIG definitions to start the API server sessions. The number started should match the number defined to the DOB's Resource Manager. If this is not the case, you will get error messages on the remote DOB:

S6BKC016L-PRD U0139000 CONNECTED #=000267 TYPE=CICSUSER COMM=XMS    SOURCE=T0139000
S6BKC036L-PRD T0139000 REJECTED TYPE=DBMSSRVR REASON=12/36                        

which means that maximum number of sessions allowed by the DOB's Resource Manager has been reached. Further sessions are rejected. The reason codes for S6BKC036L error messages are defined in the "TIBCO® Object Service Broker Messages With Identifiers Software Release 5.0" manual.

If the configuration is compatible, you will see messages of the form:

S6BKC016L-PRD U016C000 CONNECTED #=000206 TYPE=NEE USER COMM=XMS    SOURCE=T016C000
S6BKC018I-PRD T016C000 SERVER AVAILABLE, TYPE=API, SERVER ID=DEFAULT0 COMM=XMS    
S6BKC016L-PRD U016C001 CONNECTED #=000208 TYPE=NEE USER COMM=XMS    SOURCE=T016C001
S6BKC018I-PRD T016C001 SERVER AVAILABLE, TYPE=API, SERVER ID=DEFAULT0 COMM=XMS    

for each API session started. There are actually two sessions established between the EE and the DOB for each logical API server session. The Uaaaaa### session is used to receive and send the original request and response while the Taaaaa### is used to perform the actual table accesses on behalf of the remote user. It is like a surrogate remote user session. The format of the name is important in debugging situations. The "aaaa" part is the hexadecimal z/OS address space identifier of the EE address space and the "###" is an occurrence value to make the session id unique.

There are a number of restrictions that must be met in order for a request to successfully be processed by a remote DOB and API server. These are outlined in the "TIBCO® Object Service Broker Application Administration Software Release 5.0" Chapter 3, "Administering a Distributed Environment". If you fail to meet these requirements, you will receive the following error when accessing remote data:
  "Unable to EDIT or BROWSE; Message could not be sent to location "xxxxxxxx" PEERSERVERID "ssssssss"
Unfortunately this message is not very helpful in determining the specific issue causing the failure. [CR 1-9BUYJY is open requesting Engineering provide more information in the error message to distinguish various problems causing the access failure.] In this case, you must check each restriction and resource to make sure that the requirements are met. Pay particular attention to the items described in section "TIBCO Object Service Broker Security" concerning security requirements at both the local and remote nodes. S6BTLADM can be used to examine the API statistics for the locally attached API server. Make sure that the sessions are active and free sessions are running to service new requests.

Environment:
z/OS Data Object Brokers running peer connections with peerserver sessions.


Symptoms:
S6BKC016L-PRD U0139000 CONNECTED #=000267 TYPE=CICSUSER COMM=XMS    SOURCE=T0139000
S6BKC036L-PRD T0139000 REJECTED TYPE=DBMSSRVR REASON=12/36  
                      
S6BKC016L-PRD U016C000 CONNECTED #=000206 TYPE=NEE USER COMM=XMS    SOURCE=T016C000
S6BKC018I-PRD T016C000 SERVER AVAILABLE, TYPE=API, SERVER ID=DEFAULT0 COMM=XMS    

"Unable to EDIT or BROWSE; Message could not be sent to location "xxxxxxxx" PEERSERVERID "ssssssss"


References:
TIBCO® Object Service Broker Application Administration Software Release 5.0
TIBCO® Object Service Broker for z/OS Installing and Operating Software Release 5.0
TIBCO® Object Service Broker Messages With Identifiers Software Release 5.0
TIBCO® Object Service Broker Security Software Release 5.0

Defining peer server sessions in a z/OS environment.