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


Appendix B Configurations for Communications : Configuring TCP/IP

Configuring TCP/IP
Review this section if you are using TCP/IP to communicate between TIBCO Object Service Broker components—client processes, Execution Environments, Data Object Brokers, and external database gateways—on a z/OS system and TIBCO Object Service Broker components on z/OS or non-z/OS platforms.
Requirements for TCP/IP
You must have the following in place in order to use TCP/IP:
An OMVS segment defined for each user ID associated with TIBCO Object Service Broker that will be accessing TCP/IP functions. This is required by z/OS UNIX System Services.
Alternatively, you can set up RACF so that it can use a default OMVS segment for users that do not have a specific OMVS segment. This is described in the RACF Security Administrator’s Guide in the section Using default OMVS segments in USER and GROUP profiles.
For the corresponding information applicable to CA TSS or CA ACF environments, refer to the section Define a System Default UID and GID in eTrust CA-Top Secret Security for z/OS Cookbook r9 or the section Defining a Default OMVS UID and GID in eTrust CA-ACF2 Security for z/OS - Administrator Guide r9.
Properly configured relay file, member RELAYCFG to associate the TIBCO Object Service Broker communications identifier with the TCP/IP application addressing information. Refer to The Relay File for details.
Configuration of Resources for UNIX System Services
So that TIBCO Object Service Broker can access sufficient TCP/IP sockets concurrently, set the MAXFILEPROC UNIX System Services parameter to an appropriate value. TIBCO recommend MAXFILEPROC=256 at minimum. This value may need to be set much higher than 256 for highly active systems with a large user base. The maximum number of sockets allowed is set initially by the MAXFILEPROC parameter in PARMLIB member BXPPRMxx. To dynamically set MAXFILEPROC, type the following z/OS system command:
SETOMVS MAXFILEPROC=nnnnnn
To check your current setting of MAXFILEPROC, type:
D OMVS,O
To display your system resource limits and high-water marks, type this console command:
D OMVS,LIMITS
The output will help you allocate sufficient resources to ensure successful execution of TIBCO Object Service Broker.
Set the z/OS system-wide parameter MAXPROCSYS to limit the number of processes that execute concurrently. An insufficient number might cause your application to suffer such failures as U1979/U07BB abends as you use more UNIX services.
As a guideline, every Execution Environment (EE) uses at least two UNIX processes, one for the main TCB and the other for the TCB, which controls the communications RELAY. Also consider these examples:
If you set TASKPOSIXNUM=1 or default the parameter to 1, that is another UNIX process for POSIX-compliant code.
If you have set TCP/IP communications to be active, that is one more control process and several worker processes set by the tcbnum parameter in the S6BRELAY file.
The Relay File
The relay file, RELAYCFG, in the CNTL data set, contains information about TIBCO Object Service Broker components that use TCP/IP. It associates TCP/IP host names and port numbers with the TIBCO Object Service Broker communications identifiers that are used by these components running on any supported platform. The file is a text file in XML format that must be modified whenever changes to the TCP/IP environment are needed. Each component could have a separate relay file, or a common file could be shared across a number of components.
If XCF communications relay is deployed, TCP/IP parameters must be merged with the XCF parameters, and the combined parameters are contained in RELAYCFG in the CNTL data set. For details on XCF parameters, see Configuring XCF Communications.
The order of the relay parameters for each node name will be the order of selection for that node. If merged with XCF parameters, XCF will be considered before TCP/IP for nodes PRODZDOB and PRODZNEE; see Relay File Samples.
Run USERMODD in the JCL data set to customize the data set name of the relay file.
 
If you specify DSNAME=NULLFILE in USERMODD, this will disable TCP/IP access. In jobs and started tasks where you want to use TCP/IP, add an S6BRELAY DD statement pointing to the relay file.
If you specify a non-null relay file in a batch job, it is likely to have a short term region requirement at startup of over 64MB, as it runs the XML PARSER. This may cause jobs to fail. USERMODD with DSNAME=NULLFILE or an S6BRELAY DD DUMMY JCL statement removes this storage requirement.
The installation process for TIBCO Object Service Broker copies RELAYCFG to the data set $HLQNONV$.$SLQ$.RELAYCFG.
$HLQNONV$.$SLQ$.RELAYCFG contains your live TCP/IP information. If you need to make changes to your TCP/IP configuration, use the CNTL member RELAYCFG to make and verify your changes, then copy the new information to $HLQNONV$.$SLQ$.RELAYCFG.
To override the data set name set by USERMODD, add a DDNAME S6BRELAY to your TIBCO Object Service Broker component or any other z/OS components requiring TCP/IP communications. If this override is invalid during the component initialization, then the TCP/IP support is disabled until you provide a valid parameter file. Once the relay file has been processed during component initialization, it is freed.
The relay file consists of a set of protocol specific parameters followed by a directory that maps communications identifiers to protocol specific parameters.
Relay File Samples
The following is a sample the TCP/IP section of the HCS relay file:

 
<relay xmlns="http://www.tibco.com/OSB/relayparms.xsd">
   <tcpipparms tcbnum="3" maxtcbsockets="50" />
   <directory>
      <node name="PRODZDOB">
         <tcpip host="zos1.mydomain.com" service="emprec" />
      </node>
      <node name="PRODSDOB">
         <tcpip host="solaris5.mydomain.com" port="26360" />
      </node>
      <node name="PRODZEE">
         <tcpip host="zos1.mydomain.com" port="22636" />
      </node>
      <node name="TESTDOB">
         <tcpip host="168.192.0.101" port="26362"/>
      </node>
   </directory>
</relay>

 
Note that TIBCO Object Service Broker treats the value for the name attribute in the node element as though it were in uppercase. For example, <node name="MixedDOB"> is treated the same as <node name="MIXEDDOB">.
The following is a sample of merged HCS relay configuration file for TCP/IP and XCF:

 
<relay xmlns="http://www.tibco.com/OSB/relayparms.xsd">
   <tcpipparms tcbnum="3" maxtcbsockets="50" />
   <xcfparms groupname='S6BOSB'/>
   <directory>
      <node name="PRODZDOB">
         <xcf/>
         <tcpip host="zos1.mydomain.com" service="emprec" />
      </node>
      <node name="PRODSDOB">
         <tcpip host="solaris5.mydomain.com" port="26360" />
      </node>
      <node name="PRODZEE">
         <xcf/>
         <tcpip host="zos1.mydomain.com" port="22636" />
      </node>
      <node name="TESTDOB">
         <tcpip host="168.192.0.101" port="26362"/>
      </node>
   </directory>
</relay>

 
TCP/IP Protocol Parameters for the Relay File
The tcpipparms element specify TCP/IP specific parameters. The parameter values are static for the life of your TIBCO Object Service Broker component.
 
The number of z/OS tasks to be started that will process socket specific events (default is 3 and minimum is 1).
The maximum number of sockets that a TCP/IP relay task will handle (the default and the minimum is 50).
The name of the TCP/IP address space that you want to connect to. If the name is not specified, the system derives a value from the TCP/IP system configuration file, as described in the IBM publication z/OS Communications Server: IP Configuration Reference.
The Relay File Directory
The relay file directory maps communications identifiers to protocol specific parameters. Each node element defines a communications identifier. The following are attributes that you can used to define the TCP/IP parameters for a node.
 
The IP host name or IP address for the node. Names are limited to 255 characters and IP addresses can be represented in IPV4 or IPV6 format.
This optional value enables TCP/IP keepalive probes that will facilitate the detection of severed, idle connections, as well as possibly preventing the severing of idle connections by firewalls. The value is integer number between 1 and 65535; it specifies the interval in seconds between TCP/IP keepalive probes on outbound and inbound connections to this node.
The service name for the node that will be resolved to a port number. The names are limited to 255 characters.
Refer to the RELAYCFG member in the CNTL data set for sample TCP/IP configuration definitions.
Generating a Relay Utility
If you are upgrading from ObjectStar 4.1 or earlier to TIBCO Object Service Broker 5.x, you can use the S6BRLYGN utility to generate a relay file automatically. The utility converts the configuration data in a HRNPCSCM load module and creates the relay parameter file. The IN DD name specifies the load module library where HRNPCSCM is located job and the new configuration file is copied to the data set referenced by the OUT DD name. Any error messages are displayed in the file allocated to the SYSPRINT DD name.

 
//MYUSERGN JOB (0),'CONVERT PARMS',MSGCLASS=A,NOTIFY=MYUSER,TIME=10
//GENERATE EXEC PGM=S6BRLYGN,REGION=0M
//STEPLIB DD DISP=SHR,DSN=$HLQNONV$.$INSTVER$.AUTH
//IN DD DISP=SHR,DSN=SYS1.HRNCMCFG
//OUT DD DISP=SHR,DSN=$HLQNONV$.$SLQ$.RELAYCFG
//SYSPRINT DD SYSOUT=*

 
Refer to the RELAYGEN member in the JCL data set for sample JCL to run the utility.
Dynamically Refreshing a Relay File
The relay parameters for a TIBCO Object Service Broker component can be refreshed by using a z/OS System modify command. The command allows an administrator to change the mapping of communication identifiers to TCP/IP hosts and ports. Changes to tcpipparms are not be honored and you must restart the component for the changes to become effective.
This command reloads the relay file allocated to the component.
F MYDOB,CS,REFRESH
This command loads the new relay file $HLQNONV$.$SLQ$.NEWCFG.
F MYDOB,CS,PARMDSN=$HLQNONV$.$SLQ$.NEWCFG
You can check the status of the relay by issuing the following command:
F MYDOB,CS,STATUS
The target of the relay commands need not be a Data Object Broker job as shown. Any z/OS Object Service Broker address space is eligible.
For CICS jobs, the format of the transaction is as follows:
HREL STATUS
Note that for CICS, the CS, sub-command prefix should not be used. The HREL transaction is intended to be used from a z/OS console. You may enter the transaction from a CICS terminal, but the response will be issued via a WTO and not back to your terminal. STATUS may be replaced by any valid relay command, such as DISABLE, ENABLE, PARMDSN= and REFRESH.
For additional information, see Chapter 16, Operator Commands.
 
Verifying Relay File Syntax
The S6BRLYVA program allows the administrator of TIBCO Object Service Broker to verify that the syntax of a relay file is correct before starting a TIBCO Object Service Broker component that uses the file. The utility will parse the relay file allocated to the S6BRELAY DD name and will display any error messages in the SYSPRINT DD name.

 
//MYUSERGN JOB (0),'VERIFY PARMS',MSGCLASS=A,NOTIFY=MYUSER,TIME=10
//VALIDATE EXEC PGM=S6BRLYVA,REGION=0M
//STEPLIB DD DISP=SHR,DSN=$HLQNONV$.$INSTVER$.AUTH
//S6BRELAY DD DISP=SHR,DSN=$HLQNONV$.$SLQ$.RELAYCFG
//SYSPRINT DD SYSOUT=*

 
Refer to the RELAYVAL member in the JCL data set for sample JCL to run the utility.
Associated Documentation
For more information about IBM TCP/IP, refer to the appropriate IBM publication for the release of your z/OS system.

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