|In any of the data set names that are shown as having a qualifier of HBV6xx, the xx should be replaced with the current HostBridge sub-release level (currently 93).|
|HostBridge V6.62 and higher have been tested and approved for CICS TS 4.1 thru 5.4. HostBridge 6.75 and higher have been tested and approved for all versions of CICS TS through CICS TS 5.6.|
|Table of Contents|
Review the Release Notes for the current version
The release notes will tell you what has changed in HostBridge in the current version, including modifications to scripts and functions in the supplied hbutils repository, bug fixes, and documentation upgrades. They can be found here: Release Notes for HostBridge V6.93
Load the HostBridge software to your machine
To download the installation files and transfer them to the host:
- You can download the installation files here. There are two versions of the UNPACK file: HBV693.UNPACK (binary format), and HBV693.UNPACK.TXT (text format). They are otherwise identical.
- Under the heading of "HostBridge Installation Files" save the "Batch Job" and "Installation File" to a directory on your workstation (right mouse click on the link and select "Save Target As").
- Transfer the downloaded files to the host using IND$FILE, FTP, etc
- Transfer the XMT file in binary format
- Transfer either the UNPACK file in binary format or the UNPACK.TXT file in text format
- Attributes of the target files must be fixed block (RECFM=FB) and have a logical record length of 80 (LRECL=80)
- The "Batch Job" file will be 1 track
- The HBV6xx.XMT file will have to be pre-allocated with 93 cylinders
- The unpacking of the HBV6xx.XMT file will create files that will take approximately 210 cylinders of space. They do not have to be pre-allocated.
Unpack the installation files
To unpack the installation files,
- In Step 1, you created a file called HBV6xx.UNPACK. This file contains the JCL to necessary to unpack the HBV6xx.XMT file using the TSO RECEIVE command. Edit the job as indicated in the comments.
- Submit the job. A return code 0 does not necessarily indicate a successful run. Check the output of the job to ensure that it completed successfully.
Create the VSAM files
- Edit the job ***HB-HLQ***.V6xx.JCL(CREATE) as indicated in the comments. HostBridge recommends that you retain the HostBridge version number in the file names that are created. This will give you complete isolation between releases of HostBridge. The next installation step will migrate scripts, services and settings from previous releases of HostBridge to this release.
- Submit the job; a return code of zero indicates a successful execution.
Here is a list of the files that will be created.
Migrate/Clone from previous installation/release
Migrate or copy license, configuration settings, customizations, and repositories to new installation. This step is only required to migrate from a previous release or to clone an existing installation.
- Carefully review and edit the job ***HB-HLQ***.V6xx.JCL(MIGRATE) as indicated in the comments.
- Close all of the source VSAM files.
- Submit the job; a return code of zero indicates a successful execution. A return code of 12 may indicate that a copy (REPRO) of a empty VSAM file was attempted; you should review the output to determine if the job completed successfully.
If you are implementing the HostBridge for zIIP facility for the first time, click here to see a checklist of steps that you should take.
Install the HostBridge license key
Install the license key to activate HostBridge. For existing customers the license key was copied in the previous step.
- Contact HostBridge Sales. and request a license key.
- Edit/create the parmlib member ***HB-HLQ***.V6xx.PARMLIB(HBR@LICN), and enter the license key on the first line in column zero. If you have multiple keys enter each key on a line by itself. HostBridge will use the first key that passes validation.
Note: If you use IBM's HourGlass product, please inform HostBridge Sales.
Install CICS resource definitions
The RDO member in HB.V6xx.SOURCE contains the CICS resource definition statements required by HostBridge.
- Edit the member ***HB-HLQ***.V6xx.SOURCE(RDO) as indicated in the comments. You will need:
- The TCP/IP port numbers to be assigned to HostBridge Base, HBX and HB.js.
- Names of the VSAM files created in step 3
- Your DB2 sub-system name (optional)
- If you licensed the optional EMRO support:
- Edit the member ***HB-HLQ***.V6xx.SOURCE(RDOAOR) as indicated in the comments
- If you licensed the optional DB2 support:
- Edit the member ***HB-HLQ***.V6xx.SOURCE(RDODB2) as indicated in the comments
- Edit the member appropriate to your version of CICS as indicated in the comments:
- CICS TS 5.2 - ***HB-HLQ***.V6xx.JCL(RDO#52)
- CICS TS 5.3 - ***HB-HLQ***.V6xx.JCL(RDO#53)
- CICS TS 5.4 - ***HB-HLQ***.V6xx.JCL(RDO#54)
- CICS TS 5.5 - ***HB-HLQ*** V6xx.JCL(RDO#55)
- Submit the job; a return code of four or less generally indicates a successful execution, 4 warnings, 0 errors.
Here is a list of files to be defined.
If you are installing HostBridge in an MRO (not EMRO) environment, please review the following bulletin: Required RDO Entries for MRO Setup (HostBridge Version 6.81 and Prior)
Establish and Enable the Security Authorization Exit (optional)
If you need to use the HBR$AUTH user exit to perform additional security checks on your system (this is uncommon), then you will need to:
- Rename the module HBR#AUTH to HBR$AUTH in your HostBridge load library (or copy the module HBR$AUTH from your previous release if you have altered it)
- Ensure that the AUTHENTICATE attribute in your HostBridge TCPIPSERVICE definitions is set to NO
Further information on the security user exit can be found on this page
The establishment and enabling of the Security Authorization Exit should only be undertaken after direct consultation with HostBridge Support.
Install CWXN Elimination Definitions (optional)
HostBridge now has the capability to take advantage of a facility in CICS TS 5.3 (and later releases) that eliminates the need to execute CWXN transactions when performing a HostBridge requests, thus improving HostBridge performance.
You can find the information about this enhancement and the RDO definitions needed to implement the enhancement here.
Create, define, and install DFHBRNSF
HostBridge uses the IBM CICS Link Bridge Interface. This interface requires you to create, define, and install the DFHBRNSF file (this file is used in the assignment and management of bridge facility tokens).
If you have not already done so to support other applications or software, create, define and install DFHBRNSF as documented in the IBM External Interfaces Guide. For your convenience, here is a basic sample JCL to create the DFHBRNSF file: dfhbrnsf.jcl
|If you define the DFHBRNSF file as a coupling facility loaded data table, be sure to specify the Opentime parameter of Startup in the RDO definition for the file. Failure to do so may cause CICS to generate a 'severe error in module DFHBRNS' when executing the first request to HostBridge within a region.|
Add HostBridge to the PLT
In each region in which HostBridge will run, add a set of entries to the CICS Program List Table (PLT). The entries, which will cause several programs to be executed, should execute as part of phase 2 initialization. Thus, place the following entries after the first DFHDELIM entry:
DFHPLT TYPE=INITIAL,SUFFIX=HB * * THE FOLLOWING PROGRAMS ARE RUN IN THE FIRST PASS OF PLTPI * DFHPLT TYPE=ENTRY,PROGRAM=DFHDELIM * * THE FOLLOWING PROGRAMS ARE RUN IN THE SECOND PASS OF PLTPI * * * THE FOLLOWING INITIALIZES BASE HB * DFHPLT TYPE=ENTRY,PROGRAM=HBR$INIT * * THE FOLLOWING PROGRAM INITIALIZES HBZ * DFHPLT TYPE=ENTRY,PROGRAM=HBZ$INIT * * THE FOLLOWING STATEMENT SHOULD BE UNCOMMENTED IF YOU WANT TO * AUTOMATICALLY LAUNCH A HOSTBRIDGE SERVICE WHEN THE REGION STARTS * * DFHPLT TYPE=ENTRY,PROGRAM=HBR$SCLD * * * THE FOLLOWING STATEMENT SHOULD ONLY BE UNCOMMENTED IF THE * FEPI OPTION HAS BEEN INSTALLED. * * DFHPLT TYPE=ENTRY,PROGRAM=HBR0VZXS * * * THE FOLLOWING STATEMENT SHOULD ONLY BE UNCOMMENTED IF YOU * ARE UTILIZING THE HOSTBRIDGE ACTIVITIES FEATURE * * DFHPLT TYPE=ENTRY,PROGRAM=HBZCMSTI * * * THE FOLLOWING STATEMENT SHOULD ONLY BE UNCOMMENTED IF YOU * ARE UTILIZING THE HOSTBRIDGE ASSERTED ID FEATURE * * DFHPLT TYPE=ENTRY,PROGRAM=HBIPINIT DFHPLT TYPE=FINAL END
|A sample PLT is provided in ***HB-HLQ***.V6xx.JCL(PLT). For CICS TS 5.5 or later, a sample PLT (which does not have to be assembled) is provided in ***HB-HLQ***.V6xx.PARMLIB(DFHPLTHB).|
Update the CICS SIT
- Add TCPIP=YES to the SIT for the region.
- If you created a new PLT in the previous step add it to the SIT: PLTPI=HB
- Increase the MAXOPENTCBS parameter by the number of expected concurrent HostBridge sessions. If you are unsure start by increasing the value by 25. If you currently don't have a MAXOPENTCBS parameter in your SIT the default is 12 so the minimum MAXOPENTCBS value would be 37. In CICS TS 5.1 only, MAXOPENTCBS is calculated by CICS and should not be specified in the SIT.
- Increase the MXT (max tasks) parameter by 2 X (the number of expected concurrent HostBridge sessions). If you are unsure start by increasing the value by 50. If you currently don't have a MXT parameter in your SIT the default is 5 (pre-CICS TS 5.1) or 500 (CICS TS 5.1 or later), so we recommend a minimum MXT value of 55 for pre-CICS TS 5.1 and 550 for CICS TS 5.1 or later.
- Be sure that the HostBridge RDO group is in one of the lists in the GRPLIST SIT parameter for the region. Only four CICS lists are allowed in the GRPLIST parameter. It may be necessary to combine lists in order to add the HostBridge required groups.
- If you are installing the FEPI option, add FEPI=YES to the SIT for the region.
- If you are using HostBridge's dynamic promotion capabilities, be sure to specify RRMS=YES in the SIT for any region where a HostBridge repository that is to be accessed via the dynamic promotion capability exists.
APF authorize the HostBridge library
APF authorize the HostBridge load library. This step is only required for customers licensed for HostBridge for zIIP.
- APF authorize ***HB-HLQ***.V6xx.LIBRARY.
Edit the CICS started task JCL
- Add a DD card to the EXEC PGM=DFHSIP step to allocate the HostBridge parameter library.
//HBPARMS DD DISP=SHR,DSN=***HB-HLQ***.V6xx.PARMLIB
2. Add the HostBridge load libraries to the DFHRPL DD.
// DD DISP=SHR,DSN=***HB-HLQ***.V6xx.LIBRARY.LOCAL
// DD DISP=SHR,DSN=***HB-HLQ***.V6xx.LIBRARY
|The LIBRARY.LOCAL load library must be concatenated in front of the LIBRARY load library and should be defined to be the same size as the LIBRARY load library to provide flexibility in the event that HostBridge Support needs to provide updates to your current release.|
3. Required for HBz (HostBridge for zIIP). If you have licensed HostBridge for zIIP, add the HostBridge load library to the STEPLIB statement for the EXEC PGM=DFHSIP step.
// DD DISP=SHR,DSN=***HB-HLQ***.V6xx.LIBRARY
|If you have not APF authorized this library CICS will fail to start. The ***HB-HLQ***.V6xx.LIBRARY is required both in the STEPLIB DD statement and DFHRPL DD statement for HostBridge for zIIP to be active.|
4. Required for EMRO. If you licensed EMRO support, repeat steps 1 and 2 above for the the AOR regions. Step 3 is not required in the AOR regions.
Create the HBZ Server Started Task
This step is only required if you have licensed HostBridge for zIIP.
Create the started task that manages the HBZ server tasks. The HBZMGR01 started task requires no special permissions but should have the same performance characteristics as the HostBridge CICS regions that use it. This task will accumulate almost no CPU time and can support any number of CICS regions.
- Copy member ***HB-HLQ***.V6xx.JCL(HBZMGR01) to one of your proclib libraries, edit the member as indicated in the comments.
- From the operator console issue a start for HBZMGR01.
- Using tools/processes appropriate to your environment ensure that this task is started after each IPL and is not subject to automated timeout/cancel processes.
Install FEPI support (optional)
If you licensed the optional FEPI support, read FEPI Support for installation instructions.
Restart the CICS region(s)
Restart the regions.
You may see the following messages in the MSGUSR sysout:
DFHAM4910 E Install of DOCTEMPLATE HBR@INIT failed
DFHAM4910 E Install of DOCTEMPLATE HBR@RQST failed
DFHAM4910 E Install of DOCTEMPLATE HBR@SESS failed
they are to be expected and do not indicate an error.
Check values of initialization and termination scripts
As of version 6.81, HostBridge enables the use of initialization and termination scripts. However, previous releases of HostBridge used the name of test for a default for these scripts. If these values are not removed from your configuration file, then your existing scripts will not run properly. Please review the following product bulletin for further information on how to remove these default values: HB V6.81 Requirement - Remove Default Initialization and Termination Scripts.
Test HostBridge installation
To ensure HostBridge installed properly, open a web browser and enter the following URL:
where “ip-address” is the IP address of the z/OS systems on which CICS is running and “ip-port” is the port assigned in the HBRNSSL TCPIPSERVICE definition (which was defined during the Install CICS resource definitions step earlier in this article). You will be prompted for your CICS login credentials; if you don't receive the prompt you most likely have the wrong port number. After successful authentication you should receive the following XML document in response.
<hostbridge sysid="CICD" build_date="Jun 22 2006 14:52:11"> <token>93fd4a60</token> <timestamp>20060915141910</timestamp> <status> <response>0</response> <desc>ok</desc>| </status> <transaction tranid="NOOP" facility="AA8}" next_tranid="" next_tranid_src="normal" sysid="CICD"> <status> <cics_resp>0</cics_resp> <cics_resp2>0</cics_resp2> <cics_desc>NORMAL</cics_desc> <task_end>endtask</task_end> <abend_code /> </status> <parameters> <tranid>noop</tranid> <entry>noop</entry> <userid>JAMES</userid> <show_token>1</show_token> <link3270>2</link3270> <show_fields>2</show_fields> </parameters> <command> <empty /> </command> <fields count="1"> <field name="field_r0_c0" row="1" col="1" pos="0"> <name len="11">field_r0_c0</name> <value maxlen="1920" len="4">NOOP</value> <attr byte="40" justify="n" disp="y" prot="n" num="n" int="n" mdt="n" /> </field> </fields> <cursor type="pos" pos="4" row="1" col="5">4</cursor> </transaction> <copyright info="HostBridge Copyright (c) 2001-2020 HostBridge Technology, LLC. US Patent No. 6,981,257 B2" /> </hostbridge>
To ensure that the script repository that contains the HB.js utilities was installed properly, issue the following URL.
where “ip-address” is the IP address of the z/OS systems on which CICS is running and “ip-port” is the port assigned in the HBJNSSL TCPIPSERVICE definition (which was defined during the Install CICS resource definitions step earlier in this article). You will be prompted for your CICS login credentials; if you don't receive the prompt you most likely have the wrong port number. After successful authentication you should receive the following HTML web page in response.
This section contains information about special conditions that may require additional steps to install and run HostBridge.
Pre-Enterprise COBOL Considerations (versions prior to COBOL Version 6)
HostBridge is shipped with a number of COBOL modules that were compiled using the release 6.2 (Enterprise) compiler.
For those sites that have not converted to and are not using Enterprise COBOL release 6 or later, you may choose to run HostBridge with its COBOL modules compiled with the version 4 COBOL compiler. To do so, please do the following:
- Install Hostbridge using the previously documented procedure and test to ensure that it is working properly.
- Upload the following attachment to your mainframe in BINARY format: v693_cobolv4.xmt. The file characteristics for uploading this file should be RECFM=FB, LRECL=80, and any valid BLKSIZE.
- Using the TSO receive command, create a new load library from the uploaded XMT file. We recommend that you name it YOURHLQ.HBV691.COBOLV4.LIBRARY.
- Include the newly created library in the DFHRPL concatenation for the CICS region(s) that HostBridge is running on. It should go just above the standard HostBridge load library in the concatenation.
- Retest HostBridge.
If you wish to consolidate your HostBridge libraries by overlaying the COBOL load modules in your standard library with the ones in the COBOLV4 library, you may do so; however, we recommend that you keep the libraries separate.
CICS Multi-Region Operation (MRO)
When running in a CICS TS 2.2 environment or later, HostBridge can run in one region and start terminal-oriented transactions in another. If these transactions use BMS, then the BMS map load modules must be defined and accessible to the region in which HostBridge runs. If you purchased HostBridge Enhanced MRO support, click here for more information.
DFHMDF macro and DATA=BLOCK on BMS MAP definitions
The IBM-supplied BMS macro DFHMDF has a problem when DATA=BLOCK is specified. If you use DATA=BLOCK in your BMS map definitions, please contact HostBridge Support for instructions on how to work around this problem.
IBM's z/OS Debugger
There is a conflict between the IBM z/OS Debugger and HostBridge that can manifest itself as abends in HostBridge modules (including HBZCCLIL). To avoid this problem, you will need to specify that HostBridge modules need to be excluded from the modules that the IBM z/OS Debugger can access. This is accomplished by modifying and reassembling the EPAOPTS module (JCL for doing this is found in the IBM z/OS Debugger SEQASAMP library). You will need to add the following control statements:
Once the module is reassembled, the library that contains it will need to be included in the DFHRPL concatenation ABOVE the libraries that contain the z/OS debugger load modules.
Running Compuware's XPEDITER
There is a conflict between older versions of XPEDITER (pre v7.4) and programs compiled using the SAS/C compiler (such as HostBridge). To avoid this problem specify four control statements, which instruct XPEDITER to ignore HostBridge and the SAS/C support modules. When XPEDITER is available within a CICS region, the JCL used to start CICS includes the following DD statement (the dataset name might be different):
//XDDBPINP DD DSN=XPEDITOR.CICS.PARMLIB(member),DISP=SHR
Edit the “member” referenced by this DD statement to include the following control statements:
DBPA 9.4.1 PROGRAM=L$*
DBPA 9.4.1 CSECT=L$*
DBPA 9.4.1 PROGRAM=HB*
DBPA 9.4.1 CSECT=HB*
These statements will instruct XPEDITER to ignore programs/csects that begin with the characters “L$” and “HB”. The CICS region must be restarted in order for XPEDITER to process these control statements.
To specify the equivalent control statements while CICS and XPEDITER are running:
- Logon to CICS
- Execute transaction XPSP
- Go to menu option 9.4.1
A panel will display to allow the entry of transaction/program/csect information. Use one line on the panel to enter the following values in the TRAN, PROGRAM, and CSECT columns:
TRAN PROGRAM CSECT
* L$* *
* * L$*
* HB* *
* * HB*
Running AllFusion® CA-InterTest® for CICS
One of the key features of products like CA-InterTest is the ability to intercept and moderate a transaction's interaction with a terminal user. If you are having problems with a particular transaction and want to debug it with CA-InterTest for CICS, then we suggest logging on to CICS and simply running the transaction from a terminal and use CA-InterTest as you normally do. To run CA-InterTest and HostBridge, apply the following maintenance to CA-InterTest for CICS:
/* PRODUCT: CA-Intertest-CICS OS/390 Realia II WB Common
/* RELEASE: 6.1
/* CICS62 ABP 29 ON RETURN WITH BRIDGE EXIT.
DFHCNV and DFHCCNV
In order for character translation to work correctly under CICS, the IBM-supplied program modules DFHCNV and DFHCCNV must be defined with EXECKEY CICS. The resource definitions currently provided by IBM do specify EXECKEY CICS. However, older versions of CICS defined these modules with EXECKEY USER. Thus, use the CEMT INQUIRE command to check the attributes of these modules and insure that both are defined to run in EXECKEY CICS (indicated by "Cex" on the second line of the CEMT INQUIRE output). If "Uex" is shown, instead of "Cex", these modules have been defined to run in EXECKEY USER. In this case, use CEDA to change the resource definitions for these modules. The following snippet illustrate the correct definition of DFHCNV and DFHCCNV. ("Cex" indicated on the second line):
STATUS: RESULTS - OVERTYPE TO MODIFY
Prog(DFHCNV ) Leng(0000000768) Ass Pro Ena Pri
Res(000) Use(0000000462) Bel Cex Ful Qua Cic Nat
RESPONSE: NORMAL TIME: 13.48.14 DATE: 11/11/10
PF 1 HELP 3 END 5 VAR 7 SBH 8 SFH 9 MSG 10 SB 11 SF
CA IDMS® Session Cleanup
HostBridge includes specific features to support CA IDMS transactions. If you have release 15.0 or later of the CA IDMS CICS Universal Communication Facility (UCF), HostBridge can execute the UCF transaction under a CICS bridge facility. This is the preferred approach. For further information about this capability, click here.
When using UCF to execute a CA IDMS transaction, care must be taken to ensure that the state/status of the CICS-based activities are synchronized with the CA IDMS activities. Specifically, when a CICS bridge facility is deleted, appropriate cleanup actions must be taken within CA IDMS.
CA IDMS provides a program to perform these cleanup actions. This program is referred to in the CA IDMS documentation as the “CICS Abort Session Program”. This program is generated by a CA-provided macro called #UCFCICZ macro. Normally, the program generated by the #UCFCICZ macro is LINKed to by the CICS terminal error program (DFHTEP) and/or the VTAM node error program (DFHZNEP). DFHTEP or DFHZNEP are automatically LINKed to by CICS when a session associated with a terminal facility terminates. However, these programs are not automatically executed when a session associated with a bridge facility terminates.
Bridge facility cleanup is the responsibility of a CICS Global User Exit (GLUE) program invoked at exit point XFAINTU. Provided with HostBridge is such a program (HBR$INTU). HBR$INTU performs cleanup activities that are common to all HostBridge sessions and bridge facilities. It also LINKs to installation-specific programs to perform additional initialization or cleanup activities. Once such program, HBR$FRTU, is invoked during bridge facility cleanup in the router region (the “router region” is the region in which HostBridge runs). This is the place where the CA IDMS CICS Abort Session Program should be invoked.
HB.V6xx.SOURCE(IDMSFRTU) contains the assembler source code for program HBR$FRTU, which LINKs to a CA IDMS CICS Abort Session Program. The name of the CICS Abort Session Program is specified in the variable UCF_PROGRAM (by default, it is ‘UCFCICX’). Before you assemble and link HBR$FRTU, change this variable to the name of the correct CICS Abort Session Program.
The HBR$FRTU load module should be placed in library HB.V6xx.LIBRARY.LOCAL.
|NOTE: The CICS Abort Session Program LINKed to by HBR$FRTU must be generated with the following #UCFCICZ parameters: BRIDGE=TERMID and PASSVAL=TERMID. (These parameters were added to the #UCFCICZ macro as of release 15.0.)|