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


Chapter 1 Installing Service Gateway for IDMS/DB : Installing on a Remote Host

Installing on a Remote Host
This section describes the procedure for installing the software on a remote host in relation to the Data Object Broker installation.
Distribution Media and Contents
This software is distributed in .xm1 format within a ZIP file. The file is in a format compatible with IBM System Modification Program/ Extended (SMP/E) naming conventions. The software is packaged in SMP/E txlib format.
Installation Media
You can download the software from the TIBCO site by following these steps:
1.
2.
3.
Installation Files
The following ZIP file comprises the distribution media:
 
TIB_srvcgw-idms_6.0.0_zos.zip
Uploading of the Software
If you have acquired the software by downloading it from the TIBCO 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-idms_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 files are the only files used in this installation:
srvcgw_idms.xm1 – Compressed file containing Service Gateway for IDMS/DB for installation on a remote host
install.bin – The REXX EXEC to perform the installation
ostarrec.bin – The REXX EXEC to uncompress the .xm1 file
property.bin – A template of mandatory install variables required for product installation
OSTAREDC – A load module to improve the performance of OSTARREC
The idms.xm1 file is not used in this procedure.
3.
HLQ.INSTALL
where HLQ is any valid high-level qualifier. Note that this HLQ will be used during the installation. See the sample JCL in the next step.
4.
HLQ.OS.IDMS.XM1 (size 46,220 KB)
Use the same HLQ as the previous data set. Below is 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,(5,15,100))
//DD2   DD DSN=HLQ.OS.IDMS.XM1,
// DISP=(,CATLG,DELETE),UNIT=SYSDA,
// DCB=(RECFM=FB,LRECL=1024,BLKSIZE=0,DSORG=PS),
// SPACE=(TRK,(1000,50))
5.
FTP install.bin, property.bin and ostarrec.bin to your z/OS system in BIN mode to the HLQ.INSTALL data set. Name these utilities INSTALL, PROPERTY and OSTARREC, respectively.
6.
FTP the srvcgw_idms.xm1 file in BIN mode to the HLQ.OS.IDMS.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, using the following syntax:
DA(’datasetname’)
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.
Installation Process
You can start the installation if you have the following data sets ready:
HLQ.INSTALL
HLQ.OS.IDMS.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.
To install Service Gateway for IDMS/DB:
1.
2.
Input Updates to the Properties File according to the values determined in Step 1.
3.
System Environment Checklist
Before you begin the installation, review the system environment information described in Table 3 and determine whether you will use the default value or provide your own value.
 
Table 3 OSEMOD Variables
OSEMOD Variable
High-level qualifier for uploaded data sets INSTALL and OS.IDMS.XM1
High-level qualifier for non-VSAM and VSAM data sets you are authorized to create
Second-level qualifier for TIBCO Service Gateway system files
For SMS Shops – managementclass, dataclass, and storageclass, if required
High-level qualifier of Language Environment libraries for SCEELKED and SCEEBIND
High-level qualifier of IBM's Callable Services library CSSLIB
IDMS SYSCTL file
For details, refer to the TIBCO Object Service Broker for z/OS Installing and Operating manual.
Updates to the Properties File
Use the PROPERTY member in HLQ.INSTALL as a template, and modify to suit your requirements. Table 4 describes 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. The defaults are OSBS06, OSBD18, and OSBB02.
vol1 – DASD volser for temp work files
vol2 – DASD volser for install files
vol3 – DASD volser for TIBCO Object Service Broker system files
Installation Steps
 
1.
Press PA1.
2.
3.
Press ENTER twice.
 
Execute File Tailoring EXEC to start installation.
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 IDSM.JCL data set is created at the successful completion of this step.
HLQ.IDMS.JCL (Edit Job Card to your site’s standards.)
HLQ.IDMS.JCL (SUB data set)
This batch job will uncompress the OS.IDMS.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. (Optional)
If you wish to make additional changes to the values of OSEMOD variables, make the changes now.
HLQ.FILECLS
HLQ.OS.IDMS.FILEI
HLQNONV.INSTVER.CLIST – CLIST
HLQNONV.INSTVER.CNTL – CNTL
HLQNONV.INSTVER.JCL – Sample JCL
HLQNONV.INSTVER.OS.IDMS.JOBS – Install jobs for remote Service Gateway for IDMS/DB
Modify STATUS of installation jobs, as required.
HLQNONV.INSTVER.OS.IDMS.JOBS
Jobs in MEMBER 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.
Valid status: INSTALL (run the job), FUTURE/OPTIONAL (skip the job), DONE (job already completed).
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 S6R4ACPT from INSTALL to FUTURE. Note that you must ACCEPT the remote Service Gateway for IDMS/DB FMID before applying any hotfix maintenance using SMP/E.
Skip this step if the default STATUS of all the jobs is acceptable.
HLQNONV.INSTVER.OS.IDMS.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 JOBSR list is accompanied by the message ALL MEMBERS PROCESSED.
Verification of Installation
The Installation Verification Procedure (IVP) for an external DBMS enables you to quickly verify that the installation of a TIBCO Object Service Broker DOB and one or more DBMS Service Gateways was successful. The IVP verifies that the communication between the DOB and a Service Gateway and that between a Service Gateway and the DBMS is functioning properly.
The IVP is split between two elements:
Member IVPIDMSP, which was placed in HLQNONV.INSTVER.JCL by the installation procedure for the Service Gateway for IDMS, starts the gateway.
A batch file, shell script, or JCL member, which is run in the DOB environment, loads dictionary information for the IDMS sample table and invokes the Gateway to ensure that the IDMS data is accessible.
If the gateway was installed locally, that is, inside an existing OSB installation, then both JCL members are in that installation's JCL data set.
You can perform each of the steps manually. That is, you can start the Service Gateway for IDMS normally rather than by running IVPIDMSP. You can also browse data in the external database via the Gateway without using the batch file, shell script, or JCL.
Requirements
The IVP requires the following:
The installation of a Service Gateway. Recall that it must run from an APF- authorized library and that, if the DOB is running on z/OS, you must properly configure the Gateway in Resource Management.
The sample record EMPLOYEE in the IDMS database.
Configurations
Before running the IVP, you must configure the communication path through which the Service Gateway will use to communicate with the DOB. The details of this configuration depend upon the DOB’s installation platform (z/OS or Open Systems) and upon which the communications protocol.
If the DOB is on Windows or UNIX and the communications protocol is TCP/IP, then the communications configuration for the Service Gateway is determined by the Relay Parameter File, which is placed in HLQNONV.SLQ.RELAYCFG by the installer. A complete discussion of how to configure that file is beyond the scope of this manual; see the section Configuring TCP/IP in the TIBCO Object Service Broker for z/OS Installing and Operating manual.
For the purpose of the IVP only, a simplified file will suffice. The following example illustrates a Relay Parameter File that configures a connection to a remote DOB on Windows/UNIX.

 
<?xml version="1.0"?>
<relay xmlns="http://www.tibco.com/OSB/relayparms.xsd">
<tcpipparms tcbnum="3" maxtcbsockets="50" />
<directory>
<node name="WINDOB">
<tcpip host="192.168.1.1" port="12000" />
</node>
</directory>
</relay>

 
Substitute the name, host, and port number for your DOB into this template. Their values are in the HURON.DIR file in the database directory of the OSB installation to which you would like to connect.
The data set HLQNONV.INSTVER.JCL(IVPIDMSP) contains the job steps required for preparing the Service Gateway for verification. Once you have met all the requirements, customize the JCL and run it. Note that if the Service Gateway has already been configured and started, omit that step.
To customize the JCL, replace each instance of $TDS$ in the JCL with the DOB node name that you placed in the Relay Parameter File.
Recall that the IVP itself is a batch file, shell script, or JCL member in the DOB environment. Depending on your operating system, do the following:
On Windows    Locate the batch file ivpidms.bat in the bin directory of your OSB installation. Follow the directions in the file to customize the variables within that file, including the settings for where to place the results.
On Solaris    Locate the (ksh) shell script ivpidms.ksh in the bin directory of your OSB installation. Follow the directions in the script to customize the shell and environment variables within the script, including the settings for where to place the results.
On z/OS    Locate the JCL member IVPDIMS in the JCL data set associated with the DOB and configure the values for TDS, USERID, and PASSWORD. You can view the results in the job's output with SDSF.
Verification
Follow these steps for verification:
1.
2.
On the DOB side, run the IVPIDMSP JCL member, ivpdims.bat, or ivpdims.ksh to access the predefined DBMS sample table.
3.
If the verification procedure succeeded, the sample data from the database is in the output.
Uninstalling on a Remote Host
To uninstall the software, perform the following:
 
HLQNONV.INSTVER.OS.IDMS.JOBS
 

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