Installation Instructions for VSE

This article describes how to install the HostBridge software under the z/VSE operating system. These instructions assume you use the CICS HTTP Listener as the communication method to/from HostBridge. (The CICS HTTP listener is part of CICS Web Support (CWS) and IBM provides it as part of CICS TS 1.1.1 or later.)
 
Table of Contents:
  

System Software Requirements

When running under z/VSE, HostBridge requires CICS Transaction Server 1.1.1 or later. You must also have a working version of TCP/IP installed.

Other System Requirements

CICS Web Support must be active and accessible. Please be sure that:

  • TCPIP=YES is specified in the SIT for regions that will use HostBridge
  • All IBM-supplied resource definitions for web services are available
  • Conversion table DFHCNV is defined
  • TCP/IP is configured properly for CICS Web Support

For more detail on the above items, refer to the IBM manual 'CICS Internet Guide' that is provided with CICS TS 1.1.1 for z/VSE.

Upgrade Installation

New releases of HostBridge will usually include the same files as the release you used for your initial installation. If you upgrade to a newer version, replace only the HostBridge phases, unless otherwise instructed by the documentation that shipped with the new version.

Initial Installation Overview

Define the HostBridge sublibrary

Using the LIBR utility, define the sub-library that the HostBridge phases and sample files will reside in. Following is a sample JCL to accomplish this. (The JCL below presumes the existence of library HBR580.)

* $$ JOB JNM=HBDEFL,CLASS=4,DISP=D
* $$ LST class="K",DISP=D,PRI=3
// JOB HBDEFLI
// EXEC LIBR,SIZE=(AUTO,64K)
DEFINE S=HBR580.DIST –
REUSE=IMMEDIATE –
REPLACE=NO
/*
/&
* $$ EOJ

Unload the installation files from zip file to your VSE library

You will need to transfer a number of files in your installation ZIP file to your VSE sublibrary (previously defined as HBR580.DIST; you can use any sublibrary you wish).

Note: When you unload the zip file you should be careful to unload everything into a directory that you create, and not to use the directory structure that exists in the zip file (some of the files that have been added later have a different root directory structure than the others).

Before starting the FTP process, please be sure that the library member EXTTYPES.L (used by TCP/IP for VSE, and normally in PRD2.CONFIG or PRD1.BASE) contains the following line:

OBJ BIN80

You may need to recycle TCP/IP if you need to modify EXTTYPES.L.

After making certain that the EXTTYPES.L is correct, you should:

  1. Using FTP, and using BINARY transfer, upload the members in your installation ZIP file that have a filetype of OBJ to your virtual punch.
  2. Using FTP, and using TEXT transfer, upload the members in your installation ZIP file that do NOT have a filetype of OBJ to your virtual punch.
  3. Transfer all of the members above (175 total) to an ICCF library. You can do this by going to the ICCF primary menu (VSE FUNCTION SELECTION), entering 323 to get to the PUNCH QUEUE list, and then selecting option 4 (copy to primary library) for each member in the punch queue.
  4. Catalog all of the object members that you just downloaded using the member CATALOBO. Note: If you have alternative methods to accomplish the prior 4 steps, feel free to do so so long as the net result is to have the object decks end up in a VSE library with a type of OBJ, and to have the non-BINARY files available for use (submission or as an example).
  5. LNKEDT all of the HostBridge members to create PHASEs using the member LNKHBRPO.
  6. Run the JCL PATCHHB.JCL to implement the current APARs to HB release 5.80.
  7. Install the HostBridge license key (sent to you by HostBridge Technology in separate email) using the member ASMLICN.

Note: You can use any technique you wish to get the object from the zip file provided into a VSE sublibrary. The main thing to remember is to use binary transfer for the object decks, and to use the JCL provided in CATALOBO and LNKHBRPO to create the HostBridge phases.

Create the CICS resource definitions

Note: If you plan to use HostBridge to run IBM supplied transactions (CEMT, CECI, CEBR, etc.), you must specify EXECKEY(CICS) for all HostBridge programs. Failure to do so will cause AEZD abends and possible CICS termination.

HBRCSD contains the CICS resource definition statements required by HostBridge. While these definition statements have been formatted for processing by the DFHCSDUP utility, you can also use them as a guide if you wish to manually define the resources using CEDA. The contents of HBRCSD can be obtained from an attachment in the Supplementary Information section that is at the end of this article.

HBRDCT contains the transient data queue definitions for HostBridge. You will need to include these in your DCT assembly and recreate the DCT with them included. The contents of HBRDCT can be obtained from an attachment in the Supplementary Information section that is at the end of this article.

The TCPIPSERVICE definition is required if you use the CICS HTTP Listener as a communication method to/from HostBridge. If so, you will need to edit the TCPIPSERVICE definition to specify an unused PORT number on your system. Also, set the AUTHENTICATE and SSL parameters according to your installation preferences (the supplied TCPIPSERVICE definition indicates the use of BASIC authentication and no SSL). Note: Depending on the currency of your CICS TS release with regard to APAR and version, the AUTHENTICATE and SSL parameters may be unsupported and, if so, should be removed from the definition.

Install the CICS resource definitions

After you define the CICS resources, log on to CICS and install them. If you used the supplied definition statements, then all the HostBridge resources are in a group called HBRGROUP. To install the resources definitions in this group, issue the following CEDA commands:

CEDA INSTALL GROUP(HBRGROUP)

ADD GROUP(HBRGROUP) LIST(your-app-list)

Include the HostBridge phases in the CICS LIBDEF SEARCH list

You must include the library where the HostBridge phases reside (HBR580.DIST) in the LIBDEF search list in your CICS startup JCL. Alternatively, you may copy the HostBridge phases into a library already defined in the CICS LIBDEF search list.

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, then you will need to:

  • Rename the module HBR#AUTH to HBR$AUTH  in your HostBridge phase 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 in the section 'Password Change Using HTTP Headers'.

Restart CICS (optional)

You may need to restart CICS in order to activate the DCT table changes previously made. If you do not restart CICS, note that the HostBridge output file definitions will not be active until you do restart CICS.

Test HostBridge

To verify that you installed the software correctly, use Microsoft’s Internet Explorer v8.0 or later (or Chrome, Firefox, or other browser), and enter the following URL:

http://host_name:port_number/hostbridge

where host_name is the domain name or IP address of the HTTP server and port_number is the port you assigned for use with HostBridge. You should receive an XML document from HostBridge that looks similar to the following:

<?xml version="1.0" encoding="ISO-8859-1" ?>
<HostBridge>
<token />
<timestamp>20010827231000</timestamp>
<status>
<response>32</response>
<desc>error: cics start failed</desc>
</status>
<transaction facility="" next_tranid="">
<status>
<cics_resp>28</cics_resp>
<cics_resp2>0</cics_resp2>
<cics_desc>TRANSIDERR</cics_desc>
<task_end />
<abend_code />
</status>
<parameters>
<tranid />
<userid>DSI2</userid>
</parameters>
</transaction>
<copyright info="HostBridge Copyright 2000-2003 HostBridge Technology, U.S. Patent Pending" />
</HostBridge>

Supplementary 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.

HBRCSD Definition Statements

This section contains the definition statements used in the installation instructions for HostBridge. Member HBRCSD.Z in the HostBridge VSE library contains these definitions. They may also be found in the following attachment: hbrcsd.txt

DCT Entries for TD Queues

This section contains the transient data queue definitions statements used in the installation instructions for HostBridge. Please refer to the following attachment: hbvsedct.txt