CA-Endevor Support for HostBridge

The HostBridge CA-Endevor interface allows a HostBridge admistrator to perform source version control of HB.js scripts using the CA-Endevor product. It will work with release 6.71 of HostBridge (and subsequent releases).

The interface is made up of several components:

  • A PUT/MAKE script that runs every time that a PUT or MAKE of an HB.js script is performed
  • JCL that is sent to the z/OS internal reader by the PUT/MAKE script
  • JCL to perform the MAKE that puts scripts back from CA-Endevor into a HostBridge script repository
  • A shell script that is associated with the MAKE JCL which allows security credentials to be specified outside of the actual JCL.

Following is a description of how the interface transports scripts to and from HostBridge and CA-Endevor.

CA-Endevor Support Initial Definitions

The PUT/MAKE scripts can send JCL to the JES2 spool and interact with CA-Endevor.

In order for the scripts to be protected via file permissions and to not be overwritten by updates from HostBridge, the PUT/MAKE scripts are put into a separate repository called hblocal. This repository should only contain site specific internal product scripts that should not be changed when a new version of HostBridge is installed.

The hblocal file that needs to be created is a VSAM file that has the same characteristics as any other HB.js repository (such as hbscript). You will need to define and seed this repository; sample JCL for this purpose can be uploaded from hblocal.jcl.

The hblocal repository will have to be defined to the HBCONFIG control file so that HostBridge is aware of it and can run scripts within it. To do this, sign on to a CICS session for the region where HostBridge resides and then type HBSM (short for HostBridge Session Monitor) on a cleared screen, and press the Enter key. You should see:

Enter H in the Option field (HB.js Configuration) and press the Enter key.  You should see:

Enter N in the Option field (Add New Repository Definition) and press the Enter key.  You should see:

Next, enter  hblocal (lower case with no /) in the URL field:

Press the Enter key.  You will see:

Now enter HBLOCAL in the Repository File Name field:

Press the Enter key.  You will see a confirmation message:

Finally, press the F12 key to exit HBSM:

In addition, you will need to define the HBLOCAL file to the CICS region. Following is a sample RDO definition for the file. If you wish, you can simply copy your HBUTILS definition and change it accordingly.

DEFINE FILE(HBLOCAL) 
GROUP(***HBGRUP***)
DSNAME(***HBVSAM***.V671.HBLOCAL)
LSRPOOLID(NONE)
ADD(YES)
BROWSE(YES)
DELETE(YES)
READ(YES)
UPDATE(YES)
RECORDSIZE(32760)
KEYLENGTH(80)
RECORDFORMAT(V)
DESCRIPTION(HB.js local utility script file)

Finally, you will have to define the hblocal repository to your IDE.

You are now ready to proceed with the CA-Endevor Support for HostBridge facility implementation.

HostBridge PUT/MAKE to CA-Endevor

The provided _hb.make.hbx script uses a parameter system and then stores the JCL as a text file that have been put into the HostBridge repository. This makes it easy to update the JCL without having to modify the script. Parameters are marked by percent signs (%) as in the example below:

//%jobname% JOB (ACCT#),'YOURNAME',NOTIFY=%user%,

The script at run time substitutes valid values in the parameters and then submits the JCL to the JES internal reader.

The MAKE and PUT exit scripts have special names:

  • _hb_make
  • _hb_put

So, they must be made accessible to your IDE and then have a MAKE performed against them into the the hblocal repository. Here is the make exit script: _hb_make.hbx. Also, here is a version of the HostBridge common services that will do the parameter substitution (common.hbx); look for the buildJob function at the end of the member. (Please contact HostBridge Support if you have any questions regarding how to implement common services.)

Once you get the _hb_make exit script working, then you will probably want to copy that to _hb_put and modify it if you have any needs. The scripts reference the JCL template with the following section of code:

/*
 * The JCL template is pulled from the hbscript repository and is called generJob.txt
*/
var template = {
name : 'generJob.txt',
repository : 'hbscript'
};

Following is what generJob.txt looks like: generJob.txt.

If you want to pull a different template, you would change the name and/or repository depending on where it has been PUT.

Once you MAKE the exit script(s) into services, they will be called each time a MAKE or PUT is performed by the user.

In the scripts, there is a line to log to the CEEOUT dataset in the CICS output to help verify it is being called. Also, you should see the job executing if it is working.

Be aware that SPOOL=YES needs to be defined in the System Initialization Table (SIT) for the CICS region where this facility is to be used, as the facility uses the EXEC CICS SPOOLOPEN/SPOOLWRITE/SPOOLCLOSE interfaces.

CA-Endevor MAKE/PUTting of a File Into HostBridge

Now we will cover getting versions of scripts out of CA-Endevor and back into a HostBridge repository via a MAKE or PUT.

The JCL that performs the MAKE/PUT process uses a tool called curl to do the HTTP/HTTPS request. This is an open source tool; IBM makes it available for z/OS as a Supplementary Toolkit. It can be found here:

http://www-03.ibm.com/systems/z/os/zos/features/unix/ported/suptlk

If you don't have it, you can request it from IBM.

Here are the two JCL members: make.jcl and put.jcl.

There are also Unix Systems Services shell scripts called make.sh and put.sh. You can find them here: make.sh and put.sh .

The JCL uses these scripts as it simplifies the calling; also, they can be updated to have hard-coded user id/password credentials, so it doesn't show up in the job stream.

The JCL will need to be updated to use the proper path where the make.sh and put.sh are placed.

The make.sh and put.sh scripts use 127.0.0.1 to loopback. This will need to be modified if you have multiple hosts/LPAR's that use different IP addresses.

The following parameters will need to be modified in the MAKE and PUT JCL:

//      SET USER='DEMO' 
// SET PASS='DEMO'
// SET SHSCR='/u/yourname/make.sh'
// SET INPUT='"YOUR.SOURCE.LIBRARY(MAKE)"'
// SET REPOS='hbscript'
// SET TARGET='maketest2'
// SET PORT='7001'

where:

  • USER and PASS are user id and password. These can be moved into the make.sh and put.sh to avoid passing them in the JCL.
  • SHSCR is the script that you want to execute. This will be the path to the Unix Systems Services make.sh and put.sh scripts.
  • INPUT is the z/OS data set name that contains the input source for a MAKE or file input for a PUT. If you need to use a Unix file path, there is a comment in make.sh and put.sh that tells you what you need to change/comment out.
  • REPOS is the repository where the MAKE or PUT will take place, i.e. hbscript.
  • TARGET is the name of the target service for a MAKE or the name of the file for a PUT.
  • PORT is the HTTP port where the HB.js engine is listening.

Please contact HostBridge Support if you have any questions regarding how to implement this facility.