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


Chapter 2 Installing and Using TIBCO Service Gateway for Files : Installing the Software on a z/OS Host

Installing the Software on a z/OS Host
You can install the Service Gateway for Files as follows:
The software is installed on the host where TIBCO Object Service Broker for z/OS is present, but the components do not share configuration files. This would be suitable for implementations where the Service Gateway for Files will communicate with a Data Object Broker other than that on the local host.
You must install and accept (through SMP/E) the TIBCO Object Service Broker base component before installing Service Gateway for Files. Also, you must have the <HLQ>.INSTALL data set that was created during that installation.
The software is installed on a host where TIBCO Object Service Broker for z/OS is absent, that is, it is not local to the Data Object Broker.
Installing Remote on Same Host
If you have acquired the Service Gateway for Files by downloading it from the TIBCO Software site, you must upload the software to the z/OS host system.
Preparing and Uploading the Product File
1.
Download or copy the TIB_srvcgw_file_6.0.0_zos.zip file to a PC that can connect to the z/OS host system.
2.
Unzip the file to a temporary location on the PC. The zip file contains multiple files; of these, the following file is the only file used in this installation:
file.xm1 — compressed file containing Service Gateway for Files.
The srvcgw.file.xm1, install.bin, ostarrec.bin, property.bin, and OSTAREDC files are not used in this procedure.
3.
<HLQ>.FILE.XM1 (size 18 KB)
Use the same <HLQ> that you specified when you uploaded the base component. Below is sample JCL to allocate this data set. Provide a JOB card and submit the JCL.
//ALLOC EXEC PGM=IEFBR14
//DD1 DD DSN=<HLQ>.FILE.XM1,
// DISP=(,CATLG,DELETE),UNIT=SYSDA,
// DCB=(RECFM=FB,LRECL=1024,BLKSIZE=0,DSORG=PS),
// SPACE=(TRK,(2,1))
4.
FTP the file.xm1 file in BIN mode to the <HLQ>.FILE.XM1 data set.
Installing the Software
This section describes the procedure for installing the Service Gateway for Files.
You must perform the installation under an ISPF environment only.
You can start the installation if you have the following data sets ready:
<HLQ>.INSTALL  
<HLQ>.FILE.XM1  
You must use the <HLQ>.INSTALL data set that was created during the installation of the TIBCO Object Service Broker base component.
To install Service Gateway for Files, perform the following:
1.
2.
These steps are described in depth below.
 
Task A Edit the Properties File
Edit the PROPERTY member in <HLQ>.INSTALL. Table 3 describes keywords in the properties file for installing this component.
Task B Initial Installation
1.
Member in: <HLQ>.INSTALL
Member: INSTALL (EX member)
The FILE.JCL data set is created at the successful completion of this step.
2.
Run Job FILE.JCL.
This batch job uncompresses the FILE.XM1 file to produce the distribution library.
JCL in: <HLQ>.FILE.JCL (Edit JOB card to your site's standards)
Data Set: <HLQ>.FILE.JCL (SUB data set). Do not hold data set open in ISPF edit.
Uncompressing <HLQ>.FILE.XM1 produces the distribution library <HLQ>.FILE.FILEI.
3.
Member in: <HLQ>.FILE.FILEI
Member: S6F1CUST (EX member)
The following work copies are created and customized with values specified by OSEMOD variables:
Customized copy - Library Description
<HLQNONV>.<INSTVER>.JCL - Sample JCL
<HLQNONV>.<INSTVER>.FILE.JOBS - Install jobs for Files
4.
Member in: <HLQNONV>.<INSTVER>.FILE.JOBS
Member: S6F2RUNJ (EX member)
SEND messages are directed to the userid specified in the NOTIFY parameter of each job submitted, informing user of submission and normal completion or abnormal termination. The successful completion of the final job in JOBSF list is accompanied by the message ALL MEMBERS PROCESSED.
This completes the installation process for Files.
See Also
TIBCO Object Service Broker for z/OS Installing and Operating for more information on installing the base component.
 
Installing Remote on Separate Host
You can install Service Gateway for Files remotely on separate hosts, where TIBCO Object Service Broker for z/OS is absent, that is, it is not local to the Data Object Broker.
Preparing the Product Files and Utilities for Uploading
1.
Download or copy the TIB_srvcgw_file_6.0.0_zos.zip file to a PC that can connect to the z/OS host system.
2.
srvcgw_file.xm1 – A compressed file containing the installation libraries.
install.bin – The REXX EXEC to perform the installation.
ostarrec.bin – The REXX EXEC to uncompress the .xm1 files.
property.bin – A template of mandatory install variables required for product installation.
OSTAREDC – A decompression utility program.
3.
HLQ.INSTALL
where HLQ is any valid high-level qualifier.
The value assigned to HLQ should be consistent during the entire installation cycle.
See sample allocation JCL in Step 4.
4.
HLQ.OS.FILE.XM1 (size 50,000 KB)
Use the same HLQ as the previous data set. Below is a sample JCL to allocate these data sets. Provide a JOB card and submit the JCL.
//ALLOC EXEC PGM=IEFBR14
//DD1 DD DSN=HLQ.INSTALL,
// DISP=(,CATLG,DELETE),UNIT=SYSDA,
// DCB=(RECFM=FB,LRECL=80,BLKSIZE=0),
// SPACE=(TRK,(10,5,10))
//DD2 DD DSN=HLQ.OS.FILE.XM1,
// DISP=(,CATLG,DELETE),UNIT=SYSDA,
// DCB=(RECFM=FB,LRECL=1024,BLKSIZE=0,DSORG=PS),
// SPACE=(TRK,(1000,50))
5.
FTP install.bin, ostarrec.bin and property.bin to your z/OS system in BIN mode to the HLQ.INSTALL data set. Name these utilities INSTALL, OSTARREC, and PROPERTY, respectively.
6.
FTP the srvcgw_file.xm1 file in BIN mode to the HLQ.OS.FILE.XM1 data set.
Installing the OSTAREDC Program
1.
Upload the OSTAREDC file to z/OS in binary format to a data set with LRECL=80 and RECFM=FB.
2.
“RECEIVE INDA(/)”
When prompted, specify DA('HLQ.INSTLOAD' as the name of the load library where you want the OSTAREDC program restored.
3.
Edit OSTARREC as follows:
Issue the command FIND OSTAREDC 1.
Change the constant after the equal sign to contain the full data set name of the program. The string must start with a double quote and a single quote, and end with a single quote and a double quote (the double quotes delimit the string and the single quotes tell TSO that the data set name is fully qualified). For example, change the following:
 
OSTAREDC = "'HLQ.INSTLOAD(OSTAREDC)'"
to
OSTAREDC = "'your.load.library(OSTAREDC)'"
where your.load.library is the name of the library referenced in Step 2.
Installing the Software
You can start the installation if you have uploaded the following data sets as described in Preparing the Product Files and Utilities for Uploading:
HLQ.INSTALL  
HLQ.OS.FILE.XM1  
 
The HLQ referenced throughout this chapter is the high-level qualifier you specified when you uploaded the product software. This is the value of the INSTALL and XM1 files you specified. It will be used as the default value for all distribution files created when an XM1 is uncompressed. It is equivalent to the value of symbolic parameter $HLQ$ as described in OSEMOD.
Overview
To install Service Gateway for Files, perform the following:
1.
2.
Editing of the Properties File using the values determined in Step 1.
3.
 
Task A System Environment Checklist
Before installation, review the system-environment information in Table 4 and determine whether to use the default value or provide your own value.
 
Table 4 OSEMOD Variables 
OSEMOD Variable
Your
Value
High-level qualifier for non-VSAM and VSAM data sets you are authorized to create
$NMGTCLAS
$NDATCLAS$
$NSTOCLAS$
STANDARD
STANDARD
S6BNONV
$VMGTCLAS
$VDATCLAS$
$VSTOCLAS$
STANDARD
STANDARD
S6BVSAM
High-level qualifier of Language Environment libraries for SCEELKED and SCEEBIND
For details, see the TIBCO Object Service Broker for z/OS Installing and Operating manual.
Task B Editing of the Properties File
Use the PROPERTY member in HLQ.INSTALL as a template and modify it to suit your requirements. Table 5 describes the keywords in the properties file that correspond to the system-environment variables in System Environment Checklist.
 
YES for SMS site, NO for non-SMS site.
Warning: If you select the SMS=YES option, be sure to specify SMS-managed data-set names. The SMS automatic class selection (ACS) rules at your site determine whether a data-set name is eligible for SMS management. If the answer is yes, SMS manages that name. Otherwise, the result is unpredictable.
Use if SMS=YES. Valid values: YES for SMS compatible data set name classes; NO for SMS non-compatible data set name classes.
If COMPAT=NO, specify the following:
NMGTCLAS MANAGEMENTCLASS for non-VSAM data sets
NDATCLASDATACLASS for non-VSAM data sets
NSTOCLASSTORAGECLASS for non-VSAM data sets
VMGTCLASMANAGEMENTCLASS for VSAM data sets
VDATCLASDATACLASS for VSAM data sets
VSTOCLASSTORAGECLASS for VSAM data sets
If SMS=YES, specify one DASD volume for VSAM data set allocation. Default is USER01. If SMS=NO, specify three DASD volumes separated by commas. Defaults are OSBS06, OSBD18, OSBB02.
Data set name of your CA IPC CAILIB load library.
Task C Installation
 
1.
Press PA1.
2.
3.
Press ENTER twice.
HLQ.INSTALL
STEP 1 will verify that files can be allocated successfully using the values provided in the PROPERTY file. Test files of type sequential, PDS, PDSE, and VSAM will be allocated then deleted. Installation will stop if any test allocation fails. You should investigate the cause, correct the condition and repeat STEP 1.
The HLQ.FILE.JCL data set is created at the successful completion of this step.
HLQ.FILE.JCL (Edit Job Card to your site’s standards.)
HLQ.FILE.JCL (SUB data set). Do not hold data set open in ISPF edit.
This batch job will uncompress the OS.FILE.XM1 file to produce the distribution libraries. If you modify the job name, make sure it does not exceed seven characters. The job should successfully complete with a return code of 0.
Edit OSEMOD.
To make additional changes to the values of the OSEMOD variables, make the changes now.
HLQ.FILECLS
If Service Gateway for Files is connecting to a Data Object Broker that runs in an Open Systems platform. you must specify the values for these two OSEMOD variables: $HOST$ and $DOBPORT$.
These variables customize the member RELAYTCP in HLQNONV.INSTVER.CNTL before it is copied to the data set HLQNONV.SLQ.RELAYCFG. It is required to establish TCP/IP connectivity. For further details, see Configuration of TCP/IP.
HLQ.OS.FILE.FILEI
HLQNONV.INSTVER.CLIST – CLIST
HLQNONV.INSTVER.CNTL – CNTL
HLQNONV.INSTVER.JCL – Sample JCL
HLQNONV.INSTVER.OS.FILE.JOBS – Install jobs for remote Service Gateway for Files
HLQNONV.INSTVER.OS.FILE.JOBS
Jobs in JOBSM are evaluated in the order they are listed and are submitted based upon their specified STATUS. The next job is submitted only if the previous one completed with its expected return code RC.
Status is modified from INSTALL to DONE only if the job's completion code is equal to or less than the stated return code.
You can modify the STATUS of any job as per your requirement. For example, if your shop normally ACCEPTs the product FMID at some future time, then change the status of S6M4ACPT from INSTALL to FUTURE.
HLQNONV.INSTVER.OS.FILE.JOBS
SEND messages are directed to the userid specified in the NOTIFY parameter of each job submitted, informing user of submission and normal completion or abnormal termination. The successful completion of the final job in the JOBSM list is accompanied by the message ALL MEMBERS PROCESSED.
If you have opted to delay accepting the product as described in step 5 by changing the original STATUS of job S6M4ACPT from INSTALL to FUTURE in member JOBSM, then be sure to accept the Service Gateway for Files product by performing the final ACCEPT when ready. This step is required for future maintenance of the product.
HLQNONV.INSTVER.OS.FILE.JOBS
Configuration of TCP/IP
You need 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.
The relay file, RELAYTCP in the CNTL data set, contains information on the TIBCO Object Service Broker components that use TCP/IP. The file associates TCP/IP host names and port numbers with the TIBCO Object Service Broker communication identifiers that are used by those components that run on any supported platform. Also, the file is a text file in XML format, which you must modify when changes to the TCP/IP environment are required. 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; the combined parameters are in RELAYCFG in the CNTL data set. For details on the XCF parameters, see Configuring XCF Communications in Chapter 2 of the TIBCO Object Service Broker for z/OS Installing and Operating manual.
The order of the relay parameters for each node name is the order of selection for that node. If merged with XCF parameters, XCF is considered before TCP/IP.
Run USERMODD in the JCL data set to customize the data set name of the relay file.
If you specify DSNAME=NULLFILE in USERMODD, you disable TCP/IP access. In jobs and started tasks where you want to use TCP/IP, add an S6BRELAY DD statement to point 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 64 MB as it runs XMLPARSER and might 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 RELAYTCP to the data set $HLQNOVN$.$SLQ$.RELAYCFG, which contains your live TCP/IP information. To change your TCP/IP configuration, use the CNTL member RELAYTCP to make and verify your changes, and then copy the new information to $HLQNOVN$.$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 that require TCP/IP communications. If this override is invalid during the component’s initialization, support for TCP/IP is disabled until you specify a valid parameter file. Once the relay file has been processed during component initialization, it is freed.
The relay file contains a set of protocol specific parameters, followed by a directory that maps communication identifiers to protocol-specific parameters. When configuring a TIBCO Service Gateway on z/OS to attach with a TIBCO Data Object Broker on Windows or Solaris, be sure to specify the keepalive attribute for the node that describes the TIBCO Data Object Broker (WINDOB in the sample below).
Following is a sample of 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="FILEZGW">
<tcpip host="zos1.mydomain.com" port="22636" />
</node>
<node name="WINDOB">
<tcpip host="168.192.0.101" port="26362" keepalive="600"/>
</node>
</directory>
</relay>

 
For a detailed description of TCP/IP protocol parameters, see TCP/IP Protocol Parameters for the Relay File in Chapter 2 of the TIBCO Object Service Broker for z/OS Installing and Operating manual.
Verification of Installation
Installation verification for an external DBMS provides a quick method to verify that the installation of a TIBCO Object Service Broker DOB and one or more DBMS Service Gateways was successful. This verifies that the communication between the DOB and a Service Gateway, and a Service Gateway and the DBMS, is functioning properly.
Verification can be accomplished by including sample TIBCO Object Service Broker table definitions for DB2, IMS, CA-IDMS and CA-Datacom. Each of these comes with sample tables or demo databases.
 
If a DBMS does not have sample tables or a demo database, or these were not included in its installation, you need to manually verify access to one of your databases. Instructions to perform this can be found later in this manual.
The TIBCO Object Service Broker tables are prefixed with the name S6BIVP*, for example S6BIVP_DATACOM.
Requirements
Installation verification requires the following:
If the DOB is on Windows or UNIX, the crparm file must contain in the OPERATOR parameter the name of the TSO ID for submitting the JCL(IVPDAT) job. For example:

 
OPERATOR = winuser1, TSOID1
# Note:
# - winuser1 is a Windows login ID, from which the Windows DOB is administered.
# - TSOID1 is a TSO ID, from which the JCL(IVPDAT) job is submitted.

 
Data set HLQNONV.INSTVER.JCL(IVPDAT) contains all the job steps required to execute the verification process. If all requirements are met customize the JCL and run it.
Have your z/OS systems programmer APF-authorize the library HLQNONV.INSTVER.AUTH so that you can use TCP/IP or z/OS cross-memory communications in IVPDAT.
Process
The steps in the verification process are as follows:
1.
2.
3.
4.
Reruns of the Installation
To do a rerun of the installation:
HLQ.INSTALL
HLQ.OS.FILE.XM1
Run the job HLQNONV.INSTVER.OS.FILE.JOBS(S6M9CLEN). It will delete all the data sets previously created by job S6M3APLY, i.e., SMP/E-related libraries, etc.
HLQNONV.INSTVER.CLIST
HLQNONV.INSTVER.CNTL
HLQNONV.INSTVER.JCL
HLQNONV.INSTVER.OS.FILE.JOBS
There are 12 of them, with a high-level qualifier of HLQ ….
Restarts of the Installation
To do a restart of the SMP/E installation, assuming that there are no data set name changes:
Manually run these three jobs in HLQNONV.INSTVER.OS.FILE.JOBS in the following order:
//PROCLIB JCLLIB ORDER=HLQ.OS.FILE.FILEI
1.
S6M3APLY – Should complete with a return code of 4.
2.
S6M4ACPT – Should complete with a return code of 4.
3.
S6M5CFGR – Should complete with a return code of 0.
To change the second-level qualifier of SMP/E libraries from its default of SMP60 to one of your choice, do the following:
Run the job HLQNONV.INSTVER.OS.FILE.JOBS(S6M9CLEN) to delete all previous SMP/E libraries.
Edit the members S6M3APLY, S6M4ACPT, S6M5CFGR, and S6M9CLEN in HLQNONV.INSTVER.OS.FILE.JOBS, changing all occurrences of SMP60 to that of your choice and then manually run these jobs:
//PROCLIB JCLLIB ORDER=HLQ.OS.FILE.FILEI
1.
S6M3APLY – Should complete with a return code of 4.
2.
S6M4ACPT – Should complete with a return code of 4.
3.
S6M5CFGR – Should complete with a return code of 0.

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