Skip to end of metadata
Go to start of metadata

HostBridge supports executing IDMS transactions via the standard IDMS UCF interface (HostBridge and CA collaborated to allow UCF to be executed under the CICS Link Bridge interface).  To HostBridge, IDMS transactions executed in this manner appear as well-behaved, non-BMS transactions (3270 data streams are exchanged between HostBridge and IDMS).  As a result, HostBridge generates field names (e.g., field_r1_c5) for each field on a screen.  For some customers this may be adequate. 

However, HostBridge is committed to achieving the “highest fidelity” application integration possible.  To us, this implies achieving integration with CICS-based applications on the basis of field names  (not field locations) within a screen space.  To this end, HostBridge collaborated with CA to incorporate support within HostBridge for CA-IDMS panels/maps. This capability is an optional feature of HostBridge and permits an enhanced level of integration between HostBridge (running under CICS TS) and a CA-IDMS ADSO application.  This document describes this feature.

IDMS supports a robust screen mapping facility which is common used by ADSO applications (from this point on we will use “panel” and “map” interchangeably, unless there is a need to differentiate).  When maps are designed, variable fields on a screen (referred to as “data fields” or “DFLDs”) are assigned names.  These are the names used by an ADSO application to reference the contents of a data field.  Thus, the ideal situation would be for HostBridge to allow fields on an IDMS panel to be referenced using the exact same name.  The HB-IDMS Feature does just that.



The examples in this document are based on our collaboration with an actual HostBridge customer: Pacific Blue Cross, headquartered in Vancouver, Canada.  All JCL samples reflect their data set naming conventions, and must be adjusted accordingly for other users.  Thank you PBC!

{C}We also want to acknowledge and thank the CA-IDMS product team for their assistance and support in developing this Feature of HostBridge.  They have been wonderful partners in this effort. 


Solution Overview

The following diagram provides an overview of the HB-IDMS Enhanced Integration Feature.  The primary components are denoted by the highlighted boxes. 

 Each component will be described in this article. 

HostBridge Panel Import Utility

In order for HostBridge to assign the correct name to an IDMS panel field, it must have knowledge of the IDMS panel(s).  HostBridge keeps such information in its “Screen File”.  Thus, an important part of HB-IDMS integration is importing IDMS panel definitions into the HostBridge Screen File.  This process is performed via a batch job and must be performed for each IDMS panel that HostBridge should recognize.  If a particular IDMS panel has not been imported to HostBridge, no field renaming will occur (the HostBridge generated field names will be used). 

Step 1:  Allocate/Initialize the HostBridge Screen File

If you do not currently have a HostBridge Screen File allocated, then the following job  should be run to define it.  Modify the JCL and IDCAMS commands per your installation requirements.

//JOBCARD  JOB   

//*
//*  DEFINE/INIT HB SCREEN FILE
//*
//STEP1    EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//INPUT    DD *
0000000000000000000000000000000000000000
/*
//SYSIN    DD *
 DEFINE CLUSTER(NAME(HB.LOCSITE.SCRNFILE) NOERASE -
    SHAREOPTION(3) INDEXED FREESPACE(10 10) -
    CYL(60 5) -
    VOLUME(***VOLUME***) -
    RECOVERY NOREUSE) -
   DATA(NAME(HB.LOCSITE.SCRNFILE.DATA) -
     BUFFERSPACE(37376) -
     RECORDSIZE(4086 32600) -
     CONTROLINTERVALSIZE(18432) KEYS(40 0) -
     SPANNED) -
   INDEX(NAME(HB.LOCSITE.SCRNFILE.INDEX) -
     CONTROLINTERVALSIZE(512))                                                        
 
 REPRO -
   INFILE(INPUT) -
   OUTDATASET(HB.LOCSITE.SCRNFILE)                                                        
 
 DEFINE ALTERNATEINDEX (NAME(HB.LOCSITE.SCRNFILE.AIX) -
       RELATE(HB.LOCSITE.SCRNFILE) -
       UPGRADE -
       VOLUME(***VOLUME***) -
       CONTROLINTERVALSIZE(18432) -
       CYL(30 10) -
       KEYS(8 52))                                                         
 
 DEFINE PATH(NAME(HB.LOCSITE.SCRNFILE.PATH) -
        PATHENTRY(HB.LOCSITE.SCRNFILE.AIX))
 
 BLDINDEX INDATASET(HB.LOCSITE.SCRNFILE) -
          OUTDATASET(HB.LOCSITE.SCRNFILE.AIX)
/*
//

The sample JCL can also be found here: idms_hbscreen_define.txt

Step 2:  Define the HostBridge Screen File to CICS


If the HostBridge Screen File is not currently defined to CICS, then the following CICS resources should be defined.  Modify the DSNAME information accordingly.

DEFINE FILE(HBSCREEN)

       GROUP(HBRGROUP)
       DSNAME(HB.LOCSITE.SCRNFILE)
       STRINGS(3)
       RECORDFORMAT(V)
       LSRPOOLID(NONE)
       BROWSE(YES)
       DELETE(NO)
       READ(YES)
       UPDATE(NO)
       DESCRIPTION(Ideal panel definitions)                                                 
*
DEFINE FILE(HBSCRNAM)
       GROUP(HBRGROUP)
       DSNAME(HB.LOCSITE.SCRNFILE.PATH)
       STRINGS(3)
       RECORDFORMAT(V)
       LSRPOOLID(NONE)
       BROWSE(YES)
       DELETE(NO)
       READ(YES)
       UPDATE(NO)
       DESCRIPTION(Ideal panel definitions alt index)

The sample RDO denifitions can also be found here: hbscreen_rdo_definitions.txt

Step 3:  Export the IDMS panels

The following JCL defines an instream procedure, and executes it three times.  The first step in the procedure executes the IDMS Panel Utility to export (“decompile”) a particular Panel.  The second step executes the HostBridge IDMS Panel Import Utility (HBR$IDMS) to process the exported IDMS map.

All DD statements may be modified according to local file naming choices.

//HBIDMSM  PROC

//DECOMP   EXEC PGM=RHDCMPUT,REGION=0M
//STEPLIB  DD  DSN=PROD.IS.CV.LOAD,DISP=SHR
//         DD  DSN=PROD.IS.IDMS.LOAD,DISP=SHR
//SYSCTL   DD  DSN=APPL.IS.DBTRNG.SYSCTL,DISP=SHR
//SYSLST   DD  SYSOUT=*
//SYSPCH   DD DSN=&&DECOMP,DISP=(NEW,PASS),UNIT=SYSDA,
//         SPACE=(CYL,(1,1)),DCB=(LRECL=80,RECFM=FB,BLKSIZE=6160)
//SYSIDMS  DD  DSN=PROD.TEC.IDMS.PARMLIB(DEVDICT),DISP=SHR
//SYSIPT   DD  DUMMY          <<<  OVERRIDE OUTSIDE OF PROC
//*
//PANEL    EXEC PGM=HBR$IDMS,PARM=' -D'
//STEPLIB  DD DISP=SHR,DSN=PROD.TEC.IDMS.HBR.LOAD
//* INPUT FILE CONTAINS EXPORTED IDMS MAP/PANEL (LRECL=80)
//PANELSRC DD DISP=(OLD,DELETE),DSN=&&DECOMP
//* VSAM FILE USED BY HOSTBRIDGE (STORES PARSED INFO)
//VSAMOUT  DD DISP=SHR,DSN=PROD.TEC.HBR.SCRNFILE
//STDOUT   DD SYSOUT=*
//STDERR   DD SYSOUT=*
//SYSOUT   DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//SYSTERM  DD SYSOUT=*
//       PEND
//*
//       EXEC  HBIDMSM
//DECOMP.SYSIPT   DD  *
 PROCESS=DECOMPILE
 MAP=MEMU0000
/*
//       EXEC  HBIDMSM
//DECOMP.SYSIPT   DD  *
 PROCESS=DECOMPILE
 MAP=MEMU2000
/*
//       EXEC  HBIDMSM
//DECOMP.SYSIPT   DD  *
 PROCESS=DECOMPILE
 MAP=MEHI5000
/*
//

The sample procedure can also be found here: idms_export_proc.txt

HostBridge IDMS Exit 18 and RHDCUXIT

In order for HostBridge to assign the correct names to fields on an IDMS panel, HostBridge must know the name of the IDMS panel being referenced by an ADSO application.  Obtaining this information at runtime, and passing it to HostBridge (running within CICS), is the job of the HostBridge IDMS Exit 18.

IDMS User exits 0 through 255 are reserved for “system-invoked numbered” exit routines. Exit 18 is the “output data stream” exit.  At runtime, a system-invoked numbered exit routine is called by IDMS if the exit has been installed in the system by means of the #DEFXIT macro.  #DEFXIT macros are specified in the RHDCUXIT module.

The following JCL has 3 steps and illustrates how to: (1) assemble the HostBridge Exit 18 module, (2) assemble the RHDCUXIT module which invokes the HostBridge Exit 18, and (3) links the resulting RHDCUXIT module.

//JOBCARD  JOB

//*-----------------------------------*                                 
//* ASSEMBLE 'EXIT18' SOURCE          *                                 
//*-----------------------------------*                                 
//ASSMBX18 EXEC PGM=ASMA90,PARM='USING(WARN(11))'                       
//SYSIN    DD DSN=PROD.TEC.HBR.IDMS.JCL(EXIT18HB),DISP=SHR              
//SYSLIB   DD DISP=SHR,DSN=SYS1.MACLIB                                  
//         DD DSN=PROD.TEC.CAI.PBC02.DISTMAC,DISP=SHR                    
//         DD DSN=PROD.TEC.CAI.PBC02.DISTSRC,DISP=SHR                    
//         DD DSN=PROD.TEC.CICSTS31.CICS.SDFHMAC,DISP=SHR                
//         DD DSN=PROD.TEC.HBR.MACLIB,DISP=SHR                           
//         DD DSN=SYS1.MACLIB,DISP=SHR                                   
//         DD DSN=SYS1.MODGEN,DISP=SHR                                   
//         DD DISP=SHR,DSN=SYS1.AMODGEN                                 
//SYSPRINT DD SYSOUT=*                                                  
//SYSPUNCH DD SYSOUT=B                                                  
//SYSUT1   DD DSN=&&SYSUT1,SPACE=(4096,(120,120),,,ROUND),UNIT=SYSDA,   
//            DCB=BUFNO=1                                               
//SYSLIN   DD DSN=&&OBJX18,UNIT=SYSDA,SPACE=(100,(500,150)),            
//            DISP=(MOD,PASS),DCB=(RECFM=FB,LRECL=80,BLKSIZE=3200)      
//*-----------------------------------*                                 
//* ASSEMBLE RHDCUXIT SOURCE          *                                 
//*-----------------------------------*                                 
//ASSMBRHD EXEC PGM=ASMA90,PARM='USING(WARN(11))'                       
//SYSIN    DD DSN=PROD.TEC.HBR.IDMS.JCL(RHDCUXIT),DISP=SHR              
//SYSLIB   DD DISP=SHR,DSN=SYS1.MACLIB                                  
//         DD DSN=PROD.TEC.CAI.PBC02.DISTMAC,DISP=SHR                    
//         DD DSN=PROD.TEC.CAI.PBC02.DISTSRC,DISP=SHR                    
//         DD DSN=PROD.TEC.CICSTS31.CICS.SDFHMAC,DISP=SHR                
//         DD DSN=SYS1.MACLIB,DISP=SHR                                   
//         DD DSN=SYS1.MODGEN,DISP=SHR                                   
//         DD DISP=SHR,DSN=SYS1.AMODGEN                                 
//SYSPRINT DD SYSOUT=*                                                  
//SYSPUNCH DD SYSOUT=B                                                  
//SYSUT1   DD DSN=&&SYSUT1,SPACE=(4096,(120,120),,,ROUND),UNIT=SYSDA,   
//            DCB=BUFNO=1                                               
//SYSLIN   DD DSN=&&OBJRHD,UNIT=SYSDA,SPACE=(100,(500,150)),            
//            DISP=(MOD,PASS),DCB=(RECFM=FB,LRECL=80,BLKSIZE=3200)      
//*-----------------------------------*                                 
//*   LINK RHDCUXIT                   *                                 
//*-----------------------------------*                                 
//LINK     EXEC PGM=IEWL,COND=(4,LT),                                   
// PARM='RENT,AMODE=31,RMODE=ANY,LET,MAP,LIST,SIZE=(524288,65536),NCAL' 
//SYSPRINT DD SYSOUT=*                                                  
//SYSUT1   DD UNIT=SYSDA,SPACE=(CYL,(20,20))                            
//OBJLIBHB DD DSN=&&OBJX18,DISP=(OLD,DELETE)                            
//OBJLIB   DD DSN=&&OBJRHD,DISP=(OLD,DELETE)                            
//SYSLMOD  DD DISP=SHR,                                                 
//            DSN=PROD.TEC.IDMS.HBR.LOAD                                
//SYSLIN   DD *                                                         
 INCLUDE OBJLIB                                                         
 INCLUDE OBJLIBHB                                                       
 ENTRY   UXITEP1                                                        
 NAME    RHDCUXIT(R)                                                    
/*                                                                      
// 

The sample JCL can also be found here: idms_exit18.txt

Appendix A contains the RHDCUXIT source code (#DEFXIT definitions, etc.) used by one customer. 

Appendix B contains a sample HBEXIT18 program.

IDMS Front End System Table

Given the technique used by the HostBridge Exit 18 to send the IDMS panel name to HostBridge across UCF, it would be inappropriate for the HostBridge Exit 18 to take action for all IDMS output requests.  Rather, it should only take action for requests coming from HostBridge.  Thus, an important step in the HostBridge Exit 18 is to determine whether the UCF connection is, in fact, being used by HostBridge. 

UCF connections always involve two components: (1) the UCF “back end” component running within IDMS, and (2) the UCF “front end” component running within a subsystem like CICS.  UCF connections between the front end and back end components have various attributes; one such attribute is the system identifier.  The system ID denotes the characteristics of the UCF front end environment.

The HostBridge Exit 18 assumes that a UCF connection used by HostBridge will have a system id of ‘HB’.  This has two implications.  First, the UCF front end used by HostBridge must specify system id ‘HB’. Second, the system id ‘HB’ must be defined to the UCF back end.

The following job illustrates how to assemble and link the IDMS Front End System Table.  An entry has been added to define ‘HB’ as a valid front end system id.

//JOBNAME  JOB

//ASSEMBLE EXEC PGM=ASMA90,PARM='USING(WARN(11))'                       
//SYSLIB   DD DISP=SHR,DSN=SYS1.MACLIB                                  
//         DD DSN=PROD.TEC.CAI.PBC02.DISTMAC,DISP=SHR                    
//         DD DSN=PROD.TEC.CAI.PBC02.DISTSRC,DISP=SHR                    
//         DD DSN=PROD.TEC.CICSTS31.CICS.SDFHMAC,DISP=SHR                
//         DD DSN=SYS1.MACLIB,DISP=SHR                                   
//         DD DSN=SYS1.MODGEN,DISP=SHR                                   
//         DD DISP=SHR,DSN=SYS1.AMODGEN                                 
//SYSPRINT DD SYSOUT=*                                                  
//SYSPUNCH DD SYSOUT=B                                                  
//SYSUT1   DD DSN=&&SYSUT1,SPACE=(4096,(120,120),,,ROUND),UNIT=SYSDA,   
//            DCB=BUFNO=1                                               
//SYSLIN   DD DSN=&&OBJ(RHDCFSTB),SPACE=(3040,(40,40,5),,,ROUND),       
//            UNIT=SYSDA,DISP=(NEW,PASS),                               
//            DCB=(BLKSIZE=3040,LRECL=80,RECFM=FB,BUFNO=1)              
//SYSIN    DD *                                                         
FSTB     TITLE 'FRONT END SYSTEM TABLE FOR UCF'                         
         #MOPT CSECT=RHDCFSTB,ENV=USER,REGS=NO                          
         EJECT                                                          
         COPY  #UCFDS                                                   
         EJECT                                                          
RHDCFSTB CSECT                                                          
* BLKSIZ= DEFINES THE PACKET SIZE USED FOR THE BULK DATA TRANSFER        
FESTABLE #FESTDEF CNT=17                                                
         #FESTENT FESID=HB                      HOSTBRIDGE              
         #FESTENT FESID=CICS                                            
         #FESTENT FESID=CICSBULK,BLKSIZ=4096    CICS DTS ACCESS         
         #FESTENT FESID=BATCH                                           
         #FESTENT FESID=BATCBULK,BLKSIZ=16384   BATCH DTS ACCESS        
         #FESTENT FESID=IDMS-DC                                         
         #FESTENT FESID=DCXXBULK,BLKSIZ=4096    DC TO DC DTS AC         
         #FESTENT FESID=TSO                                             
         #FESTENT FESID=TIAM                                            
         #FESTENT FESID=UTM                                             
         #FESTENT FESID=UTMBULK,BLKSIZ=4096     UTM DTS ACCESS          
         #FESTENT FESID=CMS,BLKSIZ=8016                                 
         #FESTENT FESID=CMSBULK,BLKSIZ=3920     CMS DTS ACCESS          
         #FESTENT FESID=IMS                                             
         END   FESTABLE                                                 
/*                                                                      
//*                                                                     
//LINK     EXEC PGM=IEWL,                                               
//             PARM='LET,MAP,LIST,SIZE=(524288,65536),NCAL'             
//SYSPRINT DD SYSOUT=*                                                  
//SYSUT1   DD UNIT=SYSDA,SPACE=(CYL,(20,20))                            
//SYSLIN   DD DISP=(OLD,DELETE),DSN=&&OBJ(RHDCFSTB)                     
//SYSLMOD  DD DISP=SHR,                                                 
//            DSN=PROD.TEC.IDMS.HBR.LOAD(RHDCFSTB)
//

The sample JCL can also be found here: idms_front_end_assembly.txt

HostBridge UCF Program and Transaction

The standard UCF front end program distributed with IDMS for use within CICS specifies a system id of ‘CICS’.  As a result, if we used this UCF front end program with HostBridge, the HostBridge Exit 18 will not kick into action (since it’s expecting a system id of ‘HB’).  Thus, we need to generate a HostBridge-specific UCF front end program.

Step 1:  Generate the HostBridge UCF Front End Program

The following JCL illustrates how to generate the HostBridge-specific UCF front end program. This JCL is based on the standard CA-provided JCL to generate a CICS UCF front end program.  The only differences are:

  • ·         Specify SYSTEM=HB
  • ·         Specify NTID=HBI1 (this will be the CICS transaction ID used to invoke this UCF program)
  • ·         Name the module UCFHBI1 (i.e., “UCF HostBridge IDMS interface 1”)

Below, the highlighted lines/items are related to these differences.

//JOBNAME  JOB

//CICSTRNS EXEC PGM=DFHEAP1$,REGION=2048K
//STEPLIB  DD DSN=PROD.TEC.CICS130.CICS.SDFHLOAD,DISP=SHR
//SYSPUNCH DD DSN=&&TRANS(#UCFCICS),DISP=(NEW,PASS),UNIT=SYSDA,
//          SPACE=(CYL,(3,,04)),DCB=(LRECL=80,RECFM=FB,BLKSIZE=3120)
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
*ASM XOPTS(NOPROLOG NOEPILOG EDF SP)
/*
//         DD DSN=PROD.TEC.CAI.PBC02.DISTMAC(#UCFCICS),DISP=SHR
//         DD *
           END
/*
//IDMSINTC EXEC PGM=ASMA90,REGION=2048K
//* PARM='DECK,NOLOAD,NORLD,XREF'
//SYSTERM  DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//SYSLIB   DD DSN=&&TRANS,DISP=(OLD,DELETE)
//         DD DSN=PROD.TEC.CAI.PBC02.DISTMAC,DISP=SHR
//         DD DSN=PROD.TEC.CAI.PBC02.DISTSRC,DISP=SHR
//         DD DSN=PROD.TEC.CICS130.CICS.SDFHMAC,DISP=SHR
//         DD DSN=SYS1.MACLIB,DISP=SHR
//         DD DSN=SYS1.MODGEN,DISP=SHR
//SYSUT1   DD DSN=&&WRKAWORK,UNIT=SYSDA,
//         VOL=SER=BSL203,SPACE=(CYL,(5,1))
//SYSUT2   DD DSN=&&WRKBWORK,UNIT=SYSDA,
//         VOL=SER=BSL203,SPACE=(CYL,(5,1))
//SYSUT3   DD DSN=&&WRKCWORK,UNIT=SYSDA,
//         VOL=SER=BSL203,SPACE=(CYL,(5,1))
//SYSLIN   DD DSN=JMAN.TEC.OBJECT(UCFHBI1),DISP=SHR
//SYSIN    DD *
UCFHBI1  #UCFCICS OS=OS,UCTRAN=TCT,COLOR=YES,DISC=YES
CICSFET  #UCFUFT SYSTEM=HB,NTID=HBI1,MODE=PCONV,PTID=UCFP             
         #UCFUTD TYPE=T3277,MODEL=2
         #UCFUTD TYPE=T3279,BUFSIZ=3840
         #UCFUTD TYPE=T3280,TERM=A560
         #UCFUTD TYPE=T3280,TERM=A561
         #UCFUTD TYPE=T3280,TERM=A562
         #UCFUTD TYPE=T3280,TERM=A563
         #UCFUTD TYPE=T3280,TERM=A564
         #UCFUTD TYPE=T3280,TERM=A565
         #UCFUTD TYPE=T3280,TERM=A566
         #UCFUTD TYPE=T3280,TERM=A56B
         #UCFUTD TYPE=T3280,TERM=A56C
         #UCFUTD TYPE=T3280,TERM=A56D
         #UCFUTD TYPE=T3280,TERM=A56E
         #UCFUTD TYPE=T3280,TERM=A56F
         #UCFDEND
         END UCFHBI1
/*
//LNKUCFC EXEC PGM=IEWL,REGION=2048K,
//     PARM='LET,LIST,MAP,XREF,SIZE=(524288,65536),NCAL,NORENT'
//IN4      DD DSN=PROD.TEC.CICS130.IDMS16RX.LOAD,DISP=SHR
//IN1      DD DSN=PROD.TEC.CAI.PBC02.LOADLIB,DISP=SHR
//IN2      DD DSN=PROD.TEC.CICS130.CICS.SDFHLOAD,DISP=SHR
//IN3      DD DSN=JMAN.TEC.OBJECT,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSUT1   DD  DSN=&&WRKAWORK,UNIT=SYSDA,
//             VOL=SER=BSL203,SPACE=(CYL,(5,1))
//SYSLMOD  DD DSN=PROD.TEC.CICS130.IDMS16RX.LOAD,DISP=SHR
//SYSLIN   DD DDNAME=SYSIN
//SYSIN    DD  *
 INCLUDE IN2(DFHEAI)
 INCLUDE IN3(UCFHBI1)
 INCLUDE IN1(RHDCUCFC)
 INCLUDE IN4(UCFPRINT)
 INCLUDE IN4(IDMSCINT)
 INCLUDE IN2(DFHEAI0)
 MODE AMODE(31),RMODE(24)
 ENTRY UCFHBI1
 NAME UCFHBI1(R)
/*
//

The sample JCL can also be found here: hostbridge_ucf_front_end.txt

Step 2:  Define the HostBridge UCF Front End Program and Transaction to CICS

The HostBridge Front End program and its corresponding transaction must be defined to CICS.  The following CICS resource definitions will accomplish this (they are clones of the CA-provided definitions for program UCFCICS and transaction DBDC).

DEFINE PROGRAM(UCFHBI1)

       GROUP(HBRGROUP)
       LANGUAGE(ASSEMBLER)
       DATALOCATION(BELOW)
       EXECKEY(CICS)
*
DEFINE TRANSACTION(HBI1)
       GROUP(HBRGROUP)
       PROGRAM(UCFHBI1)
       PROFILE(IDMSPRF)
       TASKDATALOC(BELOW)
       TASKDATAKEY(CICS)

The sample RDO definitions can also be found here: ucf_rdo_definitions.txt

HostBridge IDMS Field Rename Feature

Once all the above steps have been accomplished, the HostBridge IDMS Enhanced Integration Feature is ready to use.  And, using this feature is simple:

  • ·         Use the HostBridge UCF Transaction (e.g., HBI1) to establish the connection to IDMS.
  • ·         Specify hb_field_rename=1 on the request.

The following HostBridge script illustrates the invocation of an ADSO transaction, and the exploitation of the HostBridge IDMS Enhanced Integration Feature.  The output of the script is contained in Appendix B.  Note that certain options were specified (e.g, hb_show_screen=1) to make the HostBridge XML output easier to read and reflect the state of the application.  Normally, HostBridge scripts do not process, or display, such XML output.

HostLib( hb, "MSCRHBR" );

var globalCommands =
      '&hb_show_screen=1&hb_field_rename=1&hb_show_rowcol=1';
function hbrun(commands)
{
       output=hb.run(globalCommands + commands );
       input=hb.getCommand();
       writeln(input,'\n\n',output,'\n\n');      
}
function main()
{
//  Get started
       hb.create();
//  Use the HB UCF transaction to enter IDMS
       hbrun("&hb_tranid=hbi1");
//  Execute the ADSO program
       hbrun("&hb_type=ads tehb4000");
//  Navigate to the function we want
       hbrun("&hb_aid=pf3");
       hbrun("&hb_aid=pf1");
//  Specify group and policy number
       hbrun("&MR-ACT-MBR-NUM=065490256&MR-ACT-GRP-NUM=e024216");
//  This idms map uses an indexed field to display the first/last name.
//  Thus, we must specify an index value on the getField method.
//  MR-ADDR-NME is the same name used by the ADS app to refer to these fields.
       lastName=hb.getField("MR-ADDR-NME",0);
       firstName=hb.getField("MR-ADDR-NME",1);
//  Exit the ADSO app such that we get thrown into a BMS app. Cool!
       hbrun("&hb_aid=pf10");
       hbrun("&hb_aid=pf10");
       hbrun("&hb_aid=pf10");
       hbrun("&hb_aid=pf10");
//  Display data we gathered above
       writeln(">>> [",firstName,"] [",lastName,"]");
//  We’re done
       hb.endSession();
    return;
}
main();

The sample script can also be found here: sampleADSOTransaction.hbx
Appendix C contains a sample HostBridge script that executes an ADSO application.

Summary

The HostBridge IDMS Enhanced Integration Feature permits an enhanced level of integration between HostBridge (running under CICS TS) and a CA-IDMS ADSO application.  This Feature allows HostBridge scripts (and XML documents) to reference fields on ADSO panels using the exact same name as the ADSO programs themselves.  As a result, integration solutions based on HostBridge and this Feature can be resilient to changes in the ADSO applications.

This document describes the initial set of capabilities included in this Feature.  We hope that current and prospective customers will provide additional input as to how they would like to see this Feature evolve in future versions.


Appendix A – Sample RHDCUXIT Module

The statements added to define and implement the HostBridge Exit 18 are highlighted.  Note that this RHDCUXIT defines multiple Exit 18’s. 

UXIT     TITLE 'USER EXIT TABLE AND ENTRY CODE'                         00010000
* RHDCUXIT EP=UXITEP1                                                   00020000
*Added Optional HostBridge VCON to X18STUB    exit 18   MFS 12/05/08    00030000
*                                                                       00031000
*CONTAINS PTF# Added slot for Quiesce Area    exit 38   KJM 05/15/00    00032000
*CONTAINS PTF# Added slot for Recovery Wait   exit 37   JPD 04/27/99    00040000
*CONTAINS PTF# Added slot for Global deadlock exit 35   KJM 02/26/99    00050000
*CONTAINS PTF# Added slot for Global deadlock exit 36   KJM 02/26/99    00060000
*CONTAINS PTF# Added slot for DBKEY FIND exit           LRD 12/11/98    00070000
*CONTAINS PTF# NUMBER OF EMPTY EXITS INCREASED FOR      WAD 11/12/93    00080000
*CONTAINS PTF#   CA-IDMS TOOLS TO 340.                  WAD 11/12/93    00090000
*CONTAINS PTF# CHANGE NAMES FOR DBCS AND FACOM EXITS    DDK 09/05/91    00100000
*CONTAINS PTF# OTP EXITS                                HRH 01/16/86    00110000
*******************************************************************     00120000
         EJECT                                                          00130000
*******************************************************************     00140000
*                                                               ***     00150000
*   WE NOW HAVE A MEANS TO CALL MULTIPLE EXITS OF THE SAME      ***     00160000
*   NUMBER.  CHECK EXITS 17 AND 18 FOR MORE INFORMATION.        ***     00170000
*   (LAF 3/5/90)                                                ***     00180000
*                                                               ***     00190000
*   CHANGES FOR IDMS-DC RELEASE 10.0                            ***     00200000
*                                                               ***     00210000
*    SYSTEM-INVOKED USER EXITS BEGINNING WITH EXIT 15 ARE NEW   ***     00220000
*    WITH RELEASE 10.0.  EXIT 3 HAS CHANGES FROM 2.0 TO 10.0.   ***     00230000
*                                                               ***     00240000
*    FOR INSTRUCTIONS ON DEFINING USER EXITS, SEE THE           ***     00250000
*    APPROPRIATE DOCUMENTATION FOR YOUR RELEASE.                ***     00260000
*        RELEASE 10.0 -- OPERATIONS GUIDE                       ***     00270000
*        RELEASE 2.0  -- SYSGEN AND OPERATIONS GUIDE            ***     00280000
*                                                               ***     00290000
*******************************************************************     00300000
         EJECT                                                          00310000
         #MOPT CSECT=RHDCUXIT,ENV=SYS,MODNO=28                          00320000
         COPY  #CSADS                                                   00330000
RHDCUXIT CSECT                                                          00340000
        USING CSA,R10                                                   00350000
*                                                                       00360000
* VECTOR OF EXIT TABLE ADDRESSES                                        00370000
*                                                                       00380000
*        EXITS 00 - 255 ARE RESERVED FOR IDMS AND SHOULD NOT BE         00390000
*              ASSIGNED BY USERS                                        00400000
*                                                                       00410000
*        EXITS 256 AND HIGHER ARE FOR USERS AND WILL NOT BE ASSIGNED    00420000
*              BY COMPUTER ASSOCIATES                                   00430000
*                                                                       00440000
*                                                                       00450000
         ENTRY UXITEP1                                                  00460000
UXITEP1  DS    0A                                                       00470000
SYSTABA  DC    A(SYSCNT)          POINTER TO SYSTEM EXIT TABLE          00480000
USERTABA DC    A(USERCNT)         POINTER TO USER EXIT TABLE            00490000
SYSCNT   DC    A(SYSTABN)                                               00500000
SYSTAB   DS    0F                                                       00510000
*                                                                       00520000
* TABLE OF STANDARD EXITS INVOKED BY THE DC SYSTEM ITSELF               00530000
*                                                                       00540000
         #DEFXIT ,     EXIT 00 - SYSTEM INITIALIZATION                  00550000
         #DEFXIT ,     EXIT 01 - SIGNON                                 00560000
         #DEFXIT ,     EXIT 02 - SIGNOFF                                00570000
         #DEFXIT ,     EXIT 03                                          00580000
         #DEFXIT ,     EXIT 04 - NEW TASK                               00590000
         #DEFXIT ,     EXIT 05 - TASK TERMINATION 1                     00600000
         #DEFXIT ,     EXIT 06 - TASK TERMINATION 2                     00610000
         #DEFXIT ,     EXIT 07 - WRITE TO LOG                           00620000
         #DEFXIT ,     EXIT 08 - LOG FULL                               00630000
         #DEFXIT ,     EXIT 09 - SYSTEM STATISTICS                      00640000
         #DEFXIT ,     EXIT 10 -                                        00650000
         #DEFXIT ,     EXIT 11 -                                        00660000
         #DEFXIT ,     EXIT 12 - TERMINAL I/O ERROR                     00670000
         #DEFXIT ,     EXIT 13 - SHUTDOWN                               00680000
         #DEFXIT ,     EXIT 14 - BIND RUN UNIT                          00690000
         #DEFXIT ,     EXIT 15 - VIB STATISTICS                         00700000
         #DEFXIT ,     EXIT 16 - PRINT REPORT                           00710000
         #DEFXIT MODE=SYSTEM,CALL=DC,EP=X17STUB                         00720000
*                      EXIT 17 - INPUT DATASTREAM                       00730000
         #DEFXIT MODE=SYSTEM,CALL=DC,EP=X18STUB                         00740000
*                      EXIT 18 - OUTPUT DATASTREAM                      00750000
         #DEFXIT ,     EXIT 19 - ASYNCHRONOUS TERMINAL CONNECTION       00760000
         #DEFXIT ,     EXIT 20 - TASK LIMIT EXCESSION                   00770000
         #DEFXIT ,     EXIT 21 - SYSOUT REPORT TERMINATION              00780000
         #DEFXIT ,     EXIT 22 - PRINT REPORT II - RPE AVAILABLE        00790000
         #DEFXIT ,     EXIT 23 - Pre-BIND RUN UNIT Exit                 00800000
         #DEFXIT ,     EXIT 24 - Hourglass 2000 feature                 00810000
         #DEFXIT ,     EXIT 25 - OTP JOBNAME CONSTRUCTION EXIT          00820000
         #DEFXIT ,     EXIT 26 - OTP JOB READER EXIT                    00830000
         #DEFXIT ,     EXIT 27 - DDS & ERUS SECURITY EXIT               00840000
         #DEFXIT ,     EXIT 28 - SECURITY PREPROCESSING EXIT  JDM 11/90 00850000
         #DEFXIT ,     EXIT 29 - SECURITY POSTPROCESSING EXIT JDM 11/90 00860000
         #DEFXIT ,     EXIT 30 - DEADLOCK VICTIM SELECTION    JDM 11/90 00870000
         #DEFXIT ,     EXIT 31 - TRANSACTION STATISTICS EXIT  JDM 11/90 00880000
         #DEFXIT ,     EXIT 32 - SYSOUT DETAIL REC EXIT   TAMSU01 08/95 00890000
         #DEFXIT ,     EXIT 33 - Program Loader Exit                    00900000
         #DEFXIT ,     EXIT 34 - Unqualified dbkey find exit   LRD98345 00910000
         #DEFXIT ,     EXIT 35 - Global deadlock user info gathering    00920000
         #DEFXIT ,     EXIT 36 - Global deadlocg victim selection       00930000
         #DEFXIT ,     EXIT 37 - Recovery wait exit (LMGR)              00940000
         #DEFXIT ,     EXIT 38 - Quiesce Area/Segment/Dbname (DBRC)     00950000
         #DEFXIT ,     EXIT 39 - Future growth                          00960000
*** PLACE ADD'L #DEFXIT'S FOR SYS-INVOKED EXITS ABOVE THIS LINE ***     00970000
******   NO OTHER CHANGES TO THIS PROGRAM ARE NEEDED  *************     00980000
SYSTABN  EQU   (*-SYSTAB)/12     NUMBER OF ENTRIES IN SYSTEM TABLE      00990000
         EJECT                                                          01000000
X17STUB  #START  MPMODE=CALLER                                          01010000
         LR    R2,R1             SAVE PARM POINTER                      01020000
         L     R15,VX17H         LOAD HITACHI STREAM CONVERSION ADDR    01030000
         LTR   R15,R15           IS IT LINKED?                          01040000
         BNP   X17010            NO, BYPASS CALL                        01050000
         BAL   R3,XCALL          CALL THE EXIT                          01060000
         LR    R1,R2             RESTORE PARM REG                       01070000
         SPACE                                                          01080000
X17010   DS    0H                                                       01090000
         L     R15,VX17DBFC      LOAD DBCS AND FACOM ADDR               01100000
         LTR   R15,R15           IS IT LINKED?                          01110000
         BNP   X17020            NO, BYPASS CALL                        01120000
         BAL   R3,XCALL          CALL THE EXIT                          01130000
         LR    R1,R2             RESTORE PARM REG                       01140000
         SPACE                                                          01150000
X17020   DS    0H                                                       01160000
         L     R15,VX17CASD      LOAD CASDATA ADDR                      01170000
         LTR   R15,R15           IS IT LINKED?                          01180000
         BNP   X17030            NO, BYPASS CALL                        01190000
         BAL   R3,XCALL          CALL THE EXIT                          01200000
         SPACE                                                          01210000
X17030   DS    0H                                                       01220000
         #RTN                    BACK TO DC (NO RETURN CODE PASSED)     01230000
         SPACE 2                                                        01240000
         WXTRN XIT17EP1                                                 01250000
VX17H    DC    V(XIT17EP1)       EPADDR OF HITACHI CONVERSION EXIT      01260000
         WXTRN DBFCEP17                                                 01270000
VX17DBFC DC    V(DBFCEP17)       EPADDR OF DBCS/FACOM CONVERSION EXIT   01280000
         WXTRN INPTXEP1                                                 01290000
VX17CASD DC    V(INPTXEP1)       EPADDR OF CASDATA EXIT                 01300000
         SPACE                                                          01310000
        DROP  R12                                                       01320000
         EJECT                                                          01330000
X18STUB  #START  MPMODE=CALLER                                          01340000
         LR    R2,R1             SAVE PARM POINTER                      01350000
         L     R15,VX18CASD      LOAD CASDATA ADDR                      01360000
         LTR   R15,R15           IS IT LINKED?                          01370000
         BNP   X18010            NO, BYPASS CALL                        01380000
         BAL   R3,XCALL          CALL THE EXIT                          01390000
         LR    R1,R2             RESTORE PARM REG                       01400000
         SPACE                                                          01410000
X18010   DS    0H                                                       01420000
         L     R15,VX18DBFC      LOAD DBCS AND FACOM ADDR               01430000
         LTR   R15,R15           IS IT LINKED?                          01440000
         BNP   X18020            NO, BYPASS CALL                        01450000
         BAL   R3,XCALL          CALL THE EXIT                          01460000
         LR    R1,R2             RESTORE PARM REG                       01470000
         SPACE                                                          01480000
X18020   DS    0H                                                       01490000
         L     R15,VX18H         LOAD DATASTREAM CONVERSION ADDR        01500000
         LTR   R15,R15           IS IT LINKED?                          01510000
         BNP   X18030            NO, BYPASS CALL                        01520000
         BAL   R3,XCALL          CALL THE EXIT                          01530000
         SPACE                                                          01540000
X18030   DS    0H                                                       01550000
* Insert after label X18030                                             01550101
         L     R15,VX18HB        LOAD HOSBRIDGE DATASTREAM ADDR         01551000
         LTR   R15,R15           IS IT LINKED?                          01552000
         BNP   X18040            NO, BYPASS CALL                        01553000
         BAL   R3,XCALL          CALL THE EXIT                          01554000
         SPACE                                                          01555000
X18040   DS    0H                                                       01556000
         #RTN                    BACK TO DC (NO RETURN CODE PASSED)     01560000
         SPACE 2                                                        01570000
* Insert before label VX18H                                             01571001
         WXTRN XIT18HBE                                                 01580000
VX18HB   DC    V(XIT18HBE)       EPADDR OF HOSTBRIDGE DATASTREAM EXIT   01590000
         WXTRN XIT18EP1                                                 01591000
VX18H    DC    V(XIT18EP1)       EPADDR OF HITACHI CONVERSION EXIT      01592000
         WXTRN DBFCEP18                                                 01600000
VX18DBFC DC    V(DBFCEP18)       EPADDR OF DBCS/FACOM CONVERSION EXIT   01610000
         WXTRN OUTPXEP1                                                 01620000
VX18CASD DC    V(OUTPXEP1)       EPADDR OF CASDATA EXIT                 01630000
         SPACE                                                          01640000
         EJECT                                                          01650000
XCALL    DS    0H                                                       01660000
         #CALL (R15),(R2-R3)     CALL THE EXIT                          01670000
         SPACE                                                          01680000
         BR    R3                RETURN TO CALLER                       01690000
         SPACE 3                                                        01700000
         #PATCH   50S(*)           Copy in 100 byte PATCH area          01710000
        DROP  R12                                                       01720000
         EJECT                                                          01730000
USERCNT  DC    A(USERTABN)                                              01740000
USERTAB  DS    0F                                                       01750000
*                                                                       01760000
* TABLE OF INSTALLATION-DEFINED EXITS INVOKED BY USER PROGRAMS          01770000
*                                                                       01780000
         #DEFXIT ,                          EXIT 256                    01790000
         #DEFXIT ,                          EXIT 257                    01800000
         #DEFXIT ,                          EXIT 258                    01810000
         #DEFXIT ,                          EXIT 259                    01820000
         #DEFXIT ,                          EXIT 260                    01830000
         #DEFXIT ,                          EXIT 261                    01840000
         #DEFXIT ,                          EXIT 262                    01850000
         #DEFXIT ,                          EXIT 263                    01860000
         #DEFXIT ,                          EXIT 264                    01870000
         #DEFXIT ,                          EXIT 265                    01880000
         #DEFXIT ,                          EXIT 266                    01890000
         #DEFXIT ,                          EXIT 267                    01900000
         #DEFXIT ,                          EXIT 268                    01910000
         #DEFXIT ,                          EXIT 269                    01920000
         #DEFXIT ,                          EXIT 270                    01930000
         #DEFXIT ,                          EXIT 271                    01940000
         #DEFXIT ,                          EXIT 272                    01950000
         #DEFXIT ,                          EXIT 273                    01960000
         #DEFXIT ,                          EXIT 274                    01970000
         #DEFXIT ,                          EXIT 275                    01980000
         #DEFXIT ,                          EXIT 276                    01990000
         #DEFXIT ,                          EXIT 277                    02000000
         #DEFXIT ,                          EXIT 278                    02010000
         #DEFXIT ,                          EXIT 279                    02020000
         #DEFXIT ,                          EXIT 280                    02030000
         #DEFXIT ,                          EXIT 281                    02040000
         #DEFXIT ,                          EXIT 282                    02050000
         #DEFXIT ,                          EXIT 283                    02060000
         #DEFXIT ,                          EXIT 284                    02070000
         #DEFXIT ,                          EXIT 285                    02080000
         #DEFXIT ,                          EXIT 286                    02090000
         #DEFXIT ,                          EXIT 287                    02100000
         #DEFXIT ,                          EXIT 288                    02110000
         #DEFXIT ,                          EXIT 289                    02120000
         #DEFXIT ,                          EXIT 290                    02130000
         #DEFXIT ,                          EXIT 291                    02140000
         #DEFXIT ,                          EXIT 292                    02150000
         #DEFXIT ,                          EXIT 293                    02160000
         #DEFXIT ,                          EXIT 294                    02170000
         #DEFXIT ,                          EXIT 295                    02180000
         #DEFXIT ,                          EXIT 296                    02190000
         #DEFXIT ,                          EXIT 297                    02200000
         #DEFXIT ,                          EXIT 298                    02210000
         #DEFXIT ,                          EXIT 299                    02220000
         #DEFXIT ,                          EXIT 300                    02230000
         #DEFXIT ,                          EXIT 301                    02240000
         #DEFXIT ,                          EXIT 302                    02250000
         #DEFXIT ,                          EXIT 303                    02260000
         #DEFXIT ,                          EXIT 304                    02270000
         #DEFXIT ,                          EXIT 305                    02280000
         #DEFXIT ,                          EXIT 306                    02290000
         #DEFXIT ,                          EXIT 307                    02300000
         #DEFXIT ,                          EXIT 308                    02310000
         #DEFXIT ,                          EXIT 309                    02320000
         #DEFXIT ,                          EXIT 310                    02330000
         #DEFXIT ,                          EXIT 311                    02340000
         #DEFXIT ,                          EXIT 312                    02350000
         #DEFXIT ,                          EXIT 313                    02360000
         #DEFXIT ,                          EXIT 314                    02370000
         #DEFXIT ,                          EXIT 315                    02380000
         #DEFXIT ,                          EXIT 316                    02390000
         #DEFXIT ,                          EXIT 317                    02400000
         #DEFXIT ,                          EXIT 318                    02410000
         #DEFXIT ,                          EXIT 319                    02420000
         #DEFXIT ,                          EXIT 320                    02430000
         #DEFXIT ,                          EXIT 321                    02440000
         #DEFXIT ,                          EXIT 322                    02450000
         #DEFXIT ,                          EXIT 323                    02460000
         #DEFXIT ,                          EXIT 324                    02470000
         #DEFXIT ,                          EXIT 325                    02480000
         #DEFXIT ,                          EXIT 326                    02490000
         #DEFXIT ,                          EXIT 327                    02500000
         #DEFXIT ,                          EXIT 328                    02510000
         #DEFXIT ,                          EXIT 329                    02520000
         #DEFXIT ,                          EXIT 330                    02530000
         #DEFXIT ,                          EXIT 331                    02540000
         #DEFXIT ,                          EXIT 332                    02550000
         #DEFXIT ,                          EXIT 333                    02560000
         #DEFXIT ,                          EXIT 334                    02570000
         #DEFXIT ,                          EXIT 335                    02580000
         #DEFXIT ,                          EXIT 336                    02590000
         #DEFXIT ,                          EXIT 337                    02600000
         #DEFXIT ,                          EXIT 338                    02610000
         #DEFXIT ,                          EXIT 339                    02620000
         #DEFXIT ,                          EXIT 340                    02630000
*** PLACE ADD'L #DEFXIT'S FOR USER-INVOKED EXITS ABOVE THIS LINE ***    02640000
********  NO OTHER CHANGES TO SYSTEM CODE ARE NEEDED  **************    02650000
USERTABN EQU   (*-USERTAB)/12  NUMBER OF ENTRIES IN USER TABLE          02660000
         SPACE 2                                                        02670000
        DROP  R10                                                       02680000
         END                                                            02690000



The source code can also be found here: rhdcuxit.asm

Appendix B – Sample HostBridge

Following is a sample IDMS exit 18 to be used with HostBridge.

         TITLE 'HostBridge Exit 18'                                     00001034
*********************************************************************   00010034
*  COPYRIGHT (C) 2009 HOSTBRIDGE TECHNOLOGY, LLC. ALL RIGHTS RESERVED   00020034
*  THE TECHNIQUES EMBODIED IN THIS SOFTWARE PROCESS ARE CONFIDENTIAL    00030032
*  AND PROPRIETARY TO HOSTBRIDGE.                                       00040032
*  THEY ARE ALSO CONSIDERED BY HOSTBRIDGE TO BE A TRADE SECRET AND      00050032
*  SHOULD BE TREATED BY HOSTBRIDGE CUSTOMERS/LICENSEES ACCORDINGLY.     00060032
*  THESE MATERIALS ARE LICENSED FOR USE BY HOSTBRIDGE CUSTOMERS UNDER   00070032
*  APPLICABLE LICENSING AGREEMENTS.                                     00080032
*********************************************************************   00090034
***                                                               ***   00092034
*** THIS IS AN IDMS-CV/UCF/DC EXIT 18; 'OUTPUT DATA STREAM' EXIT  ***   00093034
*** IT IS INVOKED BY THE I/O REQUEST HANDLER BEFORE THE LINE      ***   00094034
*** DRIVER IS POSTED TO PERFORM AN OUTPUT OPERATION.              ***   00095034
***                                                               ***   00096034
*** THE EXIT IS INVOKED AFTER COMPACTION IS PERFORMED             ***   00097034
***  (IF APPLICABLE).                                             ***   00098034
***                                                               ***   00099034
*** THIS PARTICULAR EXIT IS SPECIFIC TO HOSTBRIDGE TO ACHIEVE A   ***   00099134
*** DEEPER LEVEL OF INTEGRATION BETWEEN HOSTBRIDGE (HB) AND AN    ***   00099234
*** IDMS/ADSO APPLICATIONS BY PROVIDING THE NAME OF THE IDMS/ADSO ***   00099334
*** MAP THAT WAS USED TO GENERATE A 3270 DATA STREAM TO HB VIA A  ***   00099434
*** STRUCTURED FIELD APPENDED TO THE OUTGOING DATABUFFER.         ***   00099534
***                                                               ***   00099634
*** TO INSTALL THIS EXIT IN A SYSTEM, YOU MUST MAKE THE FOLLOWING ***   00099734
*** ENTRY IN THE RHDCUXIT MODULE AT THE APPROPRIATE POINT FOR     ***   00099834
*** SYSTEM-INVOKED EXIT 18:                                       ***   00099934
***       #DEFXIT MODE=SYSTEM,CALL=DC,EP=XIT18HBE                 ***   00100034
***                                                               ***   00100134
*** YOU THEN MUST RE-ASSEMBLE AND LINK THE RHDCUXIT MODULE.       ***   00100234
*** (**NOTE** BE SURE TO SPECIFY ENTRY XIT18HBE                   ***   00100334
***           IN THE RHDCUXIT MODULE LINKEDIT.)                   ***   00100434
***                                                               ***   00100534
*** ADDITONAL INFORMATION AT END OF PROGRAM.                      ***   00100634
*********************************************************************   00100734
         GBLC &RELEASE                                                  00110032
         GBLB &IDMSMPL                                                  00120032
&IDMSMPL SETB 1        **SO WE CAN CODE MRBPLIST WHERE WE WANT**        00130032
         #MOPT CSECT=XIT18HB,ENV=SYS,MODNO=255                          00140032
         @INVOKE                                                        00150032
         USING CSA,R10                  BASE THE CSA (AT ENTRY)         00220032
         USING TCE,R9                   BASE THE TCE (AT ENTRY)         00230032
         USING XITPARM,R1               BASE EXIT INPUT PARM LISt       00240032
XIT18HBE #START MPMODE=DRIVER                                           00250032
         #GETSTK =(X18WKFWS)                                            00260032
         USING  X18WKAR,R11                                             00270032
         STM    R1,R8,X18SVAR                                           00280032
         L      R6,XITPXITP       ADDRESS PARAMETER LIST                00300032
         USING  X18PARM,R6         . BASE INPUT PARM LIST               00310032
         DROP   R1 ,               . LOSE ORIGINAL 2-WORD PARM LIST     00320032
                                                                        00321034
         MVI    TRACE_FLAG,C'1'   <---<<< LOOK !!!                      00330034
                                                                        00340032
         CLI    TRACE_FLAG,C'1'                                         00350032
         IF     BNL                                                     00360032
         THEN                                                           00370032
         #SNAP TITLE=' HB Exit18 Entry',RGSV=(R2-R8),REGS=YES           00380032
         ELSE                                                           00390032
         ENDIF                                                          00400032
                                                                        00410032
         LTR   R6,R6             NO  PARAMETER LIST?                    00420032
         BZ    END                . NO? EXIT IMMEDIATELY                00430032
         LA    R6,0(R6)  #SNAP does not like high bit set               00440032
                                                                        00450032
         CLI    TRACE_FLAG,C'1'                                         00460032
         IF     BNL                                                     00470032
         THEN                                                           00480032
         LA    R5,20                                                    00490032
         #SNAP TITLE=' HB Exit18 Parmlist',RGSV=(R2-R8),               *00500032
               AREA=((R6),(R5)),REGS=NO                                 00510032
         ELSE                                                           00520032
         ENDIF                                                          00530032
                                                                        00540032
         NC     OUTBUF,OUTBUF     NO OUTPUT BUFFER?                     00550032
         BZ     END                . NO? EXIT IMMEDIATELY               00560032
         NC     OUTBUFLN,OUTBUFLN EMPTY OUTPUT BUFFER?                  00570032
         BZ     END                . NO? EXIT IMMEDIATELY               00580032
                                                                        00590032
         CLI    TRACE_FLAG,C'1'                                         00600032
         IF     BNL                                                     00610032
         THEN                                                           00620032
         LM    R4,R5,OUTBUF                                             00630032
         #SNAP TITLE=' HB Exit18 Buffer',RGSV=(R2-R8),                 *00640032
               AREA=((R4),(R5)),REGS=NO                                 00650032
*        #SNAP TITLE=' HB Exit18 Task Areas',RGSV=(R2-R8),FORMAT=TASK   00660032
         ELSE                                                           00670032
         ENDIF                                                          00680032
                                                                        00690032
         L      R8,PTEADDR        ADDRESS PTE AREA                      00700032
         USING  PTE,R8             . BASE FOR PTE (Phys Term Element)   00710032
                                                                        00720032
         CLI    TRACE_FLAG,C'1'                                         00730032
         IF     BNL                                                     00740032
         THEN                                                           00750032
         LA      R5,PTEX-PTE                                            00760032
         #SNAP TITLE=' HB Exit18 PTE',RGSV=(R2-R8),                    *00770032
               AREA=((R8),(R5)),REGS=NO                                 00780032
         ELSE                                                           00790032
         ENDIF                                                          00800032
                                                                        00810032
         ICM    R7,15,PTEPLEA     ADDRESS PLE (Phys Line Element)       00820032
         BZ     END                . exit if no PLE                     00830032
         USING  PLE,R7             . BASE THE PLE (Phys Line Element)   00840032
                                                                        00850032
         CLI    TRACE_FLAG,C'1'                                         00860032
         IF     BNL                                                     00870032
         THEN                                                           00880032
         LA      R5,PLEX-PLE                                            00890032
         #SNAP   TITLE=' HB Exit18 PLE',RGSV=(R2-R8),                  *00900032
               AREA=((R7),(R5)),REGS=NO                                 00910032
         ELSE                                                           00920032
         ENDIF                                                          00930032
                                                                        00940032
         CLI    PLETYPE,PLEUCFD   IS THIS A UCF LINE?                   00950032
         BNE    END                . NO? EXIT IMMEDIATELY               00960032
         DROP   R7 ,                                                    00970032
                                                                        00980032
         CLI    TRACE_FLAG,C'1'                                         00990032
         IF     BNL                                                     01000032
         THEN                                                           01010032
         #SNAP TITLE=' HB Exit18 UCF Connection',RGSV=(R2-R8),         *01020032
               REGS=NO                                                  01030032
         ELSE                                                           01040032
         ENDIF                                                          01050032
                                                                        01060032
         CLC    PTEZFSID,=CL8'HB' IS HB IS #UCFUFT SYSTEM=?             01070032
         BNE    END                . NO? EXIT IMMEDIATELY               01080032
                                                                        01090032
         CLI    TRACE_FLAG,C'1'                                         01100032
         IF     BNL                                                     01110032
         THEN                                                           01120032
         #SNAP TITLE=' HB Exit18 HB Connection',RGSV=(R2-R8),          *01130032
               REGS=NO                                                  01140032
         ELSE                                                           01150032
         ENDIF                                                          01160032
                                                                        01170032
*  PTEMAP MEANS "REQUEST INVOLVES MAPPING OR LINEOUT".                  01180032
*  THUS, ACCORDING TO MIKE M, IT IS NOT CONCLUSIVE.                     01190032
*  UNTIL CA GETS THE PTEMBRA BUG CORRECTED, THIS IS THE BEST WE HAVE.   01200032
                                                                        01210032
         #TEST PTEMAP,OFF=END     Is this a mapping request?            01220032
                                                                        01230032
         CLI    TRACE_FLAG,C'1'                                         01240032
         IF     BNL                                                     01250032
         THEN                                                           01260032
         #SNAP TITLE=' HB Exit18 Mapping Request',RGSV=(R2-R8),        *01270032
               REGS=NO                                                  01280032
         ELSE                                                           01290032
         ENDIF                                                          01300032
                                                                        01310032
* Per Mike M at CA, there is a bug whereby PTEMRBA is not reset to      01320032
* 0 when a non-mapped output request follows a mapped output request.   01330032
* Thus, it will appear that an MRB exists for non-mapped requests.      01340032
* Per Mike M, an APAR has been opened (5/09).                           01350032
                                                                        01360032
* Locate the Mapping Request Block (MRB)                                01370032
         ICM    R7,15,PTEMRBA        Address MRB (Mapping Request Blk)  01380032
         BZ     END                   . exit if no MRB                  01390032
         USING  MRB,R7                . BASE FOR MRB (Mapping Req Blk)  01400032
                                                                        01410032
         CLI    TRACE_FLAG,C'1'                                         01420032
         IF     BNL                                                     01430032
         THEN                                                           01440032
         LA    R5,MRBDSLN1                                              01450032
         #SNAP TITLE=' HB Exit18 MRB',RGSV=(R2-R8),                    *01460032
               AREA=((R7),(R5)),REGS=NO                                 01470032
         ELSE                                                           01480032
         ENDIF                                                          01490032
                                                                        01500032
* Before we actually do anything let's sanity check the map name.       01510032
* and version.  if either are nulls, then do nothing.                   01520032
         CLC   MRBNAME(8),=XL8'00'                                      01530032
         BE    END                                                      01540032
         CLC   MRBVERID(16),=XL16'00'                                   01550032
         BE    END                                                      01560032
                                                                        01570032
         CLI    TRACE_FLAG,C'1'                                         01580032
         IF     BNL                                                     01590032
         THEN                                                           01600032
         #SNAP TITLE=' HB Exit18 Good Map Name/Verid',RGSV=(R2-R8),    *01610032
               REGS=NO                                                  01620032
         ELSE                                                           01630032
         ENDIF                                                          01640032
                                                                        01650032
* Allocate replacement DataStream Buffer                                01660032
         LA     R1,NWBUFPL           ADDRESS GET BUFFER PARM AREA       01670032
         XC     0(NWBUFPLN,R1),0(R1) CLEAR NEW BUFFER PARMS             01680032
         ST     R8,NWPTEAD           PASS EXISTING PTE ADDRESS          01690032
         L      R15,OUTBUFLN         Get existing buffer length         01700032
         LA     R15,WSFFLDLN(,R15)    . add Hostbridge add-on length    01710032
         ST     R15,NWBUFLN          SET REQUIRED AREA LENGTH           01720032
         L      R15,GETBUFRT         ADDRESS THE GET BUFFER ROUTINE     01730032
         STM    R6,R8,X18GBSV         . Save work registers             01740032
         BALR   R14,R15               . CALL TO GET NEW BUFFER          01750032
         LM     R6,R8,X18GBSV         . Restore work registers          01760032
* ??? is the Get Buffer return data foramtted like?                     01770032
* ???  Is it simply another chained data buffer or is it a new area?    01780032
                                                                        01790032
* Move in existing datastream                                           01800032
         L      R2,NWBUFAD           Get new buffer address             01810032
         L      R14,OUTBUF           Get old buffer address             01820032
         L      R3,OUTBUFLN          Get old buffer length              01830032
         LR     R15,R3                .                                 01840032
         MVCL   R2,R14               Move datastream to new buffer      01850032
* Move in structure field templates into new data buffer                01860032
         MVC    0(WSFFLDLN,R2),WSFFIELD  . Move in template area        01870032
         MVC    WSFMNOFF(L'WSFMNPRM,R2),MRBNAME   Move in Name          01880032
         MVC    WSFMVOFF(L'WSFMVPRM,R2),MRBVERID  Move in Version       01890032
* Return new buffer address and length                                  01900032
         MVC    OUTBUF(8),NWBUFAD     Return new buffer addr/len        01910032
                                                                        01920032
         CLI    TRACE_FLAG,C'1'                                         01930032
         IF     BNL                                                     01940032
         THEN                                                           01950032
         LM    R4,R5,OUTBUF                                             01960032
         #SNAP TITLE=' HB Exit18 Return Buffer',RGSV=(R2-R8),          *01970032
               AREA=((R4),(R5)),REGS=NO                                 01980032
         ELSE                                                           01990032
         ENDIF                                                          02000032
                                                                        02010032
         B     END                                                      02020032
                                                                        02030032
END      DS    0H                                                       02040032
                                                                        02050032
         CLI    TRACE_FLAG,C'1'                                         02060032
         IF     BNL                                                     02070032
         THEN                                                           02080032
         #SNAP TITLE=' HB Exit18 Exit',RGSV=(R2-R8),REGS=YES            02090032
         ELSE                                                           02100032
         ENDIF                                                          02110032
                                                                        02120032
         SR    R15,R15           SIGNAL ALL IS OK                       02130032
         LM    R1,R8,X18SVAR                                            02140032
         #RTN                                                           02150032
                                                                        02160032
         #PATCH   50S(*)           Copy in 100 byte PATCH area          02170032
                                                                        02180032
         DROP R6,R7,R8,R9,R10,R11,R12                                   02190032
                                                                        02200032
         TITLE 'HostBridge Exit 18 - Literals'                          02490032
*********************************************************************** 02500032
*  STATIC STORAGE/LITERALS                                              02510032
*********************************************************************** 02520032
WSFFIELD DS     0D                                                      02522032
                                                                        02523032
WSFHDR   DS     0XL16                                                   02524032
WSFINTRO DC     XL5'1140401D40'     WSF IDENTIFIER X'1140401D40'        02525032
WSFHB    DC     CL11'HOSTBRIDGE:'   HostBridge Identifier               02526032
                                                                        02527032
WSFMN    DS     0XL22               STRUCTURED FIELD FOR MRBNAME        02528032
WSFMNLN  DC     YL2(WSFMNLN#)       MEMBER NAME FIELD LENGTH            02529032
WSFMNIDF DC     CL2'HB'             MEMBER NAME ID CODE                 02529132
WSFMNIDL DC     AL1(L'WSFMNID)      MEMBER NAME ID LENGTH               02529232
WSFMNPRL DC     AL1(L'WSFMNPRM)     MEMBER NAME PARAMETER LENGTH        02529332
WSFMNID  DC     CL8'MRBNAME'        MEMBER NAME ID                      02529432
WSFMNPRM DS     CL8                 MEMBER NAME PARAMETER               02529532
WSFMNOFF EQU    WSFMNPRM-WSFFIELD                                       02529632
WSFMNLN# EQU    *-WSFMN             MUST BE 22 (X'16')                  02529732
                                                                        02529832
WSFMV    DS     0XL30               STRUCTURED FIELD FOR MRBVERID       02529932
WSFMVLN  DC     YL2(WSFMVLN#)       MEMBER VERSION FIELD LENGTH         02530032
WSFMVIDF DC     CL2'HB'             MEMBER VERSION ID CODE              02530132
WSFMVIDL DC     AL1(L'WSFMVID)      MEMBER NAME ID LENGTH               02530232
WSFMVPRL DC     AL1(L'WSFMVPRM)     MEMBER NAME PARAMETER LENGTH        02530332
WSFMVID  DC     CL8'MRBVERID'       MEMBER VERSION ID                   02530432
WSFMVPRM DS     CL16                MEMBER VERSION PARAMETER            02530532
WSFMVOFF EQU    WSFMVPRM-WSFFIELD                                       02530632
WSFMVLN# EQU    *-WSFMV             MUST BE 30 (X'1E')                  02530732
                                                                        02530832
WSFFLDLN EQU    *-WSFFIELD                                              02530932
                                                                        02531032
         LTORG                                                          02532032
                                                                        02540032
         TITLE 'HostBridge Exit 18 - Workarea'                          02550032
*********************************************************************** 02560032
*  DYNAMIC STORAGE                                                      02570032
*********************************************************************** 02580032
X18WKAR  DSECT                                                          02590032
X18SVAR  DS     8F                  Save area for incoming R1-R8        02600032
X18GBSV  DS     3F                  Save area across GetBuf call R6-R8  02610032
TRACE_FLAG  DS  C                                                       02620032
SYSPLIST  DS   10F'0'              Parm list for IDMS Macros            02630032
* SYSPLIST DS  (5+(2*0)+1)F                                             02640032
* Calculate # of fullwords in the SYSPLIST area using this formula:     02650032
*             5 + 2P + T                                                02660032
* where:                                                                02670032
*  P is the number of AREA data-area-pointer,data-length-register pairs 02680032
*  T is equal to 1 if the TITLE parameter specified; 0 otherwise        02690032
                                                                        02700032
*  GetBuffer Parameter List                                             02710032
NWBUFPL  DS     0D                                                      02720032
NWBUFAD  DS     A                   Returned Buffer Address             02730032
NWBUFLN  DS     F                   New Buffer Length Required          02740032
NWPTEAD  DS     A                   Existing PTE Address                02750032
NWSVAREA DS     12A                  . Get Buffer Work Area             02760032
NWBUFPLN EQU    *-NWBUFPL           New Buffer Parm List length         02770032
         DS     0D                                                      02780032
X18WKLEN EQU    *-X18WKAR           Exit 18 Workarea length             02790032
X18WKFWS EQU    X18WKLEN/4          Exit 18 Workarea FullWords          02800032
                                                                        02810032
*********************************************************************** 02820032
*  DSECTS DESCRIBING INPUT PARAMETERS                                   02830032
*********************************************************************** 02840032
XITPARM  DSECT                    EXIT 18 Input Parmlist                02850032
XITPXIT# DS     F                  . Fullword containing Exit Number    02860032
XITPXITP DS     A                  . Address of Exit-Specific Parms     02870032
                                                                        02880032
X18PARM  DSECT                    EXIT 18 Input Parmlist                02890032
OUTBUF   DS     A                  . Output Buffer Address              02900032
OUTBUFLN DS     F                  . Output Buffer Length               02910032
PTEADDR  DS     A                  . PTE Addr (Phys Term Element)       02920032
GETBUFRT DS     A                  . Get Buffer Routine Address         02930032
FLAGS    DS     XL4                . Buffer Flags                       02940032
PLISTEND EQU    X'80'              .  . End of Parm List                02950032
SNAHDR   EQU    X'40'              .  . SNA Mngt Hdr Buffer             02960032
BUF3270  EQU    X'20'              .  . PTERM expects 3270 stream       02970032
                                                                        02980032
*********************************************************************** 02982032
*  DSECTS FOR REFERENCED AREAS                                          02983032
*********************************************************************** 02984032
         TITLE '#PTEDS - Physical Terminal Element'                     02990032
         COPY #PTEDS                                                    03000032
         TITLE '#PTXDS - Physical Terminal Element Extensions'          03010032
         COPY #PTXDS                                                    03020032
         TITLE '#PLEDS - Physical Line Element'                         03030032
         COPY #PLEDS                                                    03040032
         TITLE '#MRBDS - Mapping Request Block'                         03050032
         COPY #MRBDS                                                    03060032
         TITLE '#IBHDS - Input Buffer Header'                           03070032
         COPY #IBHDS                                                    03080032
         TITLE '#CSADS - Common System Area'                            03090032
         COPY #CSADS                                                    03100032
         TITLE '#TCEDS - Task Control Element Area'                     03110032
         COPY #TCEDS                                                    03120032
                                                                        03121034
*********************************************************************   03381034
*  ADDITIONAL INFORMATION                                               03381134
*********************************************************************   03382034
* Objective                                                             03400032
* ---------                                                             03410032
* The overall objective is to achieve a deeper level of integration     03420032
* between HostBridge (HB) and an IDMS/ADSO applications. Specifically,  03430032
* we want HB to reference IDMS map fields using their real field names  03440032
* -- rather than generated field names based on screen coordinates      03450032
* (e.g., field_r1_c30). To accomplish this, we need to create a         03460032
* mechanism for HB to obtain the name of the IDMS/ADSO map that was     03470032
* used to generate a 3270 data stream.                                  03480032
*                                                                       03490032
* Methodology                                                           03500032
* -----------                                                           03510032
* Currently, HB invokes/interacts with IDMS ADSO transactions via UCF.  03520032
* For the most part, the UCFCICS program/transaction just acts as a     03530032
* terminal I/O processor. It gets the input from the CICS terminal      03540032
* operator and sends it over to IDMS. IDMS sends a 3270 data stream     03550032
* (generated via an ADSO map) back to UCFCICS. UCFCICS outputs that     03560032
* datastream to the terminal via an EXEC CICS SEND.                     03570032
*                                                                       03580032
* The simplest solution seems to involve the implementation of an IDMS  03590032
* Exit 18, the 'output data stream' exit. Exit 18 has access to the     03600032
* IDMS control block in which the name of the most recently reference   03610032
* map is stored. Thus, our Exit 18 could append the map name and        03620032
* version information at the end of the 3270 datastream. When UCFCICS   03630032
* does the EXEC CICS SEND, HostBridge will get the datastream and can   03640032
* extract this information from the data stream.                        03650032
*                                                                       03660032
* From that point, standard HostBridge techniques will be used to       03670032
* access the HB Screen File and perform the appropriate field           03680032
* name/value mapping.                                                   03690032
*                                                                       03700032
* Exit 18 Description                                                   03710032
* -------------------                                                   03720032
* IDMS User exits 0 through 255 are reserved for 'system-invoked        03730032
* numbered' exit routines. At runtime, a system-invoked numbered exit   03740032
* routine is called by an IDMS module if the exit has been installed    03750032
* in the system by means of the #DEFXIT macro.                          03760032
*                                                                       03770032
* Exit 18 is the 'output data stream' exit, and the CA-IDMS Systems     03780032
* Operations manual describes it as follows:                            03790032
*                                                                       03800032
*   Description:    Called by the I/O request handler before the line   03810032
*                   driver is posted to perform an output operation.    03820032
*                   The exit is invoked after compaction is performed   03830032
*                   (if applicable).                                    03840032
*                                                                       03850032
*   Sample uses:    Exit 18 can be used to examine and/or alter the     03860032
*                   contents of the output data stream.                 03870032
*                                                                       03880032
*   Considerations: If the exit routine alters the contents of the data 03890032
*                   stream, you must return the length of the altered   03900032
*                   data stream in the second parameter.                03910032
*                                                                       03920032
*   Buffers can be built by using the get-buffer routine whose address  03930032
*   is passed in the fourth word in the parameter list.                 03940032
*                                                                       03950032
*   All registers are preserved by the get-buffer routine.              03960032
*                                                                       03970032
*   Invoke the get-buffer routine with BALR 14,15                       03980032
*     where register 15 contains the address of the get-buffer routine  03990032
*       and register 1 contains the address of the parameter list.      04000032
*                                                                       04010032
*   The id of the task's physical terminal (PTERM) can be found in      04020032
*   the PTEID field of the physical terminal element (PTE). The         04030032
*   PTE layout is given by the #PTEDS DSECT.                            04040032
*                                                                       04050032
*   An exit routine that builds buffers can be:                         04060032
*    - Written to execute in system mode. In this case, the #DEFXIT     04070032
*      macro that adds the routine to the system must specify           04080032
*      MODE=SYSTEM.                                                     04090032
*    - Written to execute in user mode. The program must run with       04100032
*      storage protection disabled. The #DEFXIT macro that adds the     04110032
*      routine to the system must specify MODE=USER and call            04120032
*      the routine by name.                                             04130032
*                                                                       04140032
*   When creating a new input buffer, make sure that the exit 18        04150032
*   routine returns values as follows:                                  04160032
*    - The first parameter must return the address of the first buffer  04170032
*    - The second parameter must return the total length of the output  04180032
*      data stream.                                                     04190032
*                                                                       04200032
*   Parameters: The parameter lists for the exit routine and for the    04210032
*               get-buffer routine are each given below.                04220032
*                                                                       04230032
*   The exit 18 routine receives and can return changed values by       04240032
*   means of a five fullword parameter list:                            04250032
*    - The address of the output buffer; contains zeros if no           04260032
*      buffer exists.                                                   04270032
*    - The length of the output data stream.                            04280032
*    - The address of the task's physical terminal element (PTE).       04290032
*    - The address of a get-buffer routine.                             04300032
*    - A fullword in which the first byte contains:                     04310032
*        > X'80' - End of parameter list.                               04320032
*        > X'40' - The buffer contains the SNA functional management    04330032
*                  header (for lines defined with TYPE=VTAMLU).         04340032
*        > X'20' - The task's physical terminal (PTERM) expects a       04350032
*                  3270-type data stream (for lines defined with        04360032
*                  TYPE=VTAMLU). If the buffer contains converted data  04370032
*                  that originally was in 3270-type format, make sure   04380032
*                  the fifth parameter does not return X'20'. (X'20'    04390032
*                  causes 3270 WRITE commands to be prefixed to the     04400032
*                  buffer.)                                             04410032
*                                                                       04420032
*   The get-buffer routine receives and returns the following fifteen   04430032
*   (15) fullword parameter list that the Exit must build:              04440032
*    - The address of the buffer on return.                             04450032
*    - The length of buffer needed.                                     04460032
*    - The address of the task's physical terminal element (PTE). This  04470032
*      value is required.                                               04480032
*    - A twelve-fullword work area.                                     04490032
*                                                                       04500032
*   Return codes: None.                                                 04510032
*                                                                       04520032
*                                                                       04530032
* Determining When to Process a Request                                 04540032
* -------------------------------------                                 04550032
* Our Exit 18 will need some mechanism to determine whether or not to   04560032
* modify the datastream (i.e. it should not modify data that isn't      04570032
* going to be parsed by HostBridge).                                    04580032
*                                                                       04590032
* The first check should be to determine if this is a UCF connection.   04600032
* One of the parameters passed to Exit 18 is the address of the PTE,    04610032
* described by #PTEDS in the Dsect Reference. PTEPLEA points to the     04620032
* PLE. For UCF PTEs, PLETYPE is equal to the constant PLEUCFD. If       04630032
* this is a UCF connection, processing should continue.                 04640032
*                                                                       04650032
* The next check should be to determine if this is a HostBridge UCF     04660032
* connection. When a client creates a UCFCICS front-end module          04670032
* (invoked via a specific CICS tranid), one of the macros used is       04680032
* #UCFUFT and one of its parameters is "SYSTEM=". The Exit has access   04690032
* to this value via field PTEZFSID described in dsect #PTXDS. By        04700032
* requiring HB clients to use a specific set of UCF front-end IDs,      04710032
* we can set up Exit 18 to only modify data streams for the HB UCF      04720032
* front-ends.                                                           04730032
*                                                                       04740032
* We will assume that #UCFUFT specifies SYSTEM=HB. Thus, our Exit 18    04750032
* should check PTEZFSID to see if it has the value of 'HB'. If so,      04760032
* processing will continue.                                             04770032
*                                                                       04780032
* Obtaining the Map Information                                         04790032
* -----------------------------                                         04800032
* Obtaining the map information is straightforward. PTEMRBA points to   04810032
* the MRB, described by #MRBDS. There are two fields in the MBR that    04820032
* our Exit 18 should return to HB via the 3270 datastream:              04830032
*  - MRBNAME (offset 0) is an 8 byte field that contains the name of    04840032
*    the map.                                                           04850032
*  - MRBVERID (offset 8) is a 16 byte field that contains the map       04860032
*    version information (8 byte compile date, 6 byte compile time,     04870032
*    2 byte map id/release).                                            04880032
*                                                                       04890032
* Allocating the New Output Datastream Buffer                           04900032
* -------------------------------------------                           04910032
* As described above, one of the parameters passed to Exit 18 is the    04920032
* address of a get-buffer routine. The get-buffer routine can be used   04930032
* to allocate a new buffer if the exit intends to modify the output     04940032
* datastream (as we will do)                                            04950032
*                                                                       04960032
* If invoked for HB processing, our Exit 18 will do the following:      04970032
*  - Allocate new 3270 output datastream buffer - Since we will be      04980032
*    adding information to the 3270 datastream, we must allocate a      04990032
*    new buffer for it. The length of the new buffer should be:         05000032
*     (length of the current 3270 output datastream)                    05010032
*      + (length of HB information to be added to datastream).          05020032
*  - Copy the current 3270 output datastream to the new buffer.         05030032
*  - Extract the map name and version information out of the MRB.       05040032
*  - Copy (append) the map name and version information to the          05050032
*    buffer in the prescribed format (see below).                       05060032
*  - Return the address/length of the new buffer to IDMS such that      05070032
*    the contents of this buffer will be sent to UCFCICS.               05080032
*                                                                       05090032
*    Note: It is unnecessary to free the old buffer                     05100032
*          (as per CA support and the documentation in the IDMS code).  05110032
*                                                                       05120032
* Embedding Information in the 3270 Datastream                          05130032
* --------------------------------------------                          05140032
* Structured Fields are the ideal way to embed odd-ball stuff in a 3270 05150032
* data stream. Structured fields are sent using a special 3270 command  05160032
* 'Write Structured Field' (code X'F3'). While this would be ideal, it  05170032
* would also require more invasive modification to the 3270 datastream  05180032
* generated by IDMS (e.g., we would have to replace the Write/WCC       05190032
* command with a WSF). Actually, I'm not even sure that the Write/WCC   05200032
* are in the data stream at the time Exit 18 is called.                 05210032
*                                                                       05220032
* So, in the spirit of Structured Fields, our Exit 18 will append the   05230032
* following 16 byte string to the end of the 3270 data stream:          05240032
*     X'1140401D40',C'HOSTBRIDGE:'                                      05250032
*                                                                       05260032
* This string is will act as a structured field 'introducer';           05270032
* HostBridge will treat the remainder of the message as a series of     05280032
* structured fields.                                                    05290032
*                                                                       05300032
* Each structured field contains a 2-byte length field. This field      05310032
* defines the length of the structured field (including the length      05320032
* bytes). Next is an ID field that defines the function of the          05330032
* structured field; the ID field can be either 1 or 2 bytes.            05340032
* HostBridge will process structured field that have an ID code of      05350032
* x'C8C2' ( c'HB'). It does not appear that this 2 byte ID code         05360032
* conflicts with any architected/defined IBM codes. Following the ID    05370032
* field are parameters and data in the format defined by the ID code.   05380032
*                                                                       05390032
* For ID code c'HB', HostBridge will expect 2 single-byte length values 05400032
* to following the ID code. The first length indicates the length of a  05410032
* parameter name; the second length indicates the length of a parameter 05420032
* value. A single structured field is used to pass a single parameter   05430032
* name/value pair.                                                      05440032
*                                                                       05450032
* HostBridge will recognize two parameter names: MRBNAME and MRBVERID.  05460032
*                                                                       05470032
                                                                EJECT   05480032
* The structured field to pass MRBNAME would be formatted as follows:   05490032
*                                                                       05500032
*                  Offst Length   Value               Notes             05510032
* +---------------+-----+-----+-------------+-------------------------+ 05520032
* | Structured    |  0  |   2 |    H'22'    | Includes the length of  | 05530032
* |  . field len  |     |     |             |  . this length field    | 05540032
* +---------------+-----+-----+-------------+-------------------------+ 05550032
* | ID Code       |  2  |   2 |    X'HB'    | Length of parameter name| 05560032
* +---------------+-----+-----+-------------+-------------------------+ 05570032
* | Length of     |  4  |   1 |      8      |                         | 05580032
* |  . parm name  |     |     |             |                         | 05590032
* +---------------+-----+-----+-------------+-------------------------+ 05600032
* | Length of     |  5  |   1 |      8      |                         | 05610032
* |  . parm value |     |     |             |                         | 05620032
* +---------------+-----+-----+-------------+-------------------------+ 05630032
* | Parm name     |  5  |   1 | C'MRBNAME'  | Space padded to 8 bytes | 05640032
* +---------------+-----+-----+-------------+-------------------------+ 05650032
* | Parm value    |  6  |   8 |             | Value of MRBNAME        | 05660032
* +---------------+-----+-----+-------------+-------------------------+ 05670032
* |               |     |  22 |             |                         | 05680032
* +---------------+-----+-----+-------------+-------------------------+ 05690032
*                                                                       05700032
* The structured field to pass MRBVERID would be formatted as follows:  05710032
*                                                                       05720032
*                  Offst Length   Value       Notes                     05730032
* +---------------+-----+-----+-------------+-------------------------+ 05740032
* | Structured    |  0  |   2 |    H'30'    | Includes the length of  | 05750032
* |  . field len  |     |     |             |  this length field      | 05760032
* +---------------+-----+-----+-------------+-------------------------+ 05770032
* | ID Code       |  2  |   2 |    X'HB'    |                         | 05780032
* +---------------+-----+-----+-------------+-------------------------+ 05790032
* | Length of     |  4  |   1 |      8      |                         | 05800032
* |  . parm name  |     |     |             |                         | 05810032
* +---------------+-----+-----+-------------+-------------------------+ 05820032
* | Length of     |  5  |   1 |     16      |                         | 05830032
* |  . parm value |     |     |             |                         | 05840032
* +---------------+-----+-----+-------------+-------------------------+ 05850032
* | Parm name     |  6  |   8 | C'MRBVERID' | Space padded to 8 bytes | 05860032
* +---------------+-----+-----+-------------+-------------------------+ 05870032
* | Parm value    | 14  |  16 |             | Value of MRBVERID       | 05880032
* +---------------+-----+-----+-------------+-------------------------+ 05890032
* |               |     |  30 |             |                         | 05900032
* +---------------+-----+-----+-------------+-------------------------+ 05910032
*                                                                       05920032
* Example                                                               05930032
* The following is an example of how IDSM map information would be      05940032
* appended to the end of the 3270 data stream by our Exit 18            05950032
* (using assembler-style syntax to express values):                     05960032
*                                                                       05970032
*    DC X'1140401D40',C'HOSTBRIDGE:'                                    05980032
*    DC H'22',C'HB',AL1'8',AL1'8',CL8'MRBNAME ',CL8'TESTPNL1'           05990032
*    DC H'30',C'HB',AL1'8',AL1'16',CL8'MRBVERID',CL16'2008110523270001' 06000032
*                                                                       06010032
*********************************************************************   06011034
         END                                                            06020032


This source code can also be found here: EXIT18HB.asm

Appendix C– Sample HostBridge Script Output


The following output was generated by the sample HostBridge script.  This particular ADSO application is unique in that as you exit it, you enter a CICS BMS application.  It illustrates how HostBridge can support both BMS and IDMS field renaming simultaneously, and how the HostBridge script author can be oblivious to this fact. 

HostBridge command:

&hb_show_xml=1&&hb_show_screen=1&hb_field_rename=1&hb_show_rowcol=1&hb_show_attr=0&hb_show_name=0&hb_tranid=hbi1

XML output generated: See sampleADSOTransactionOutput1.xml

HostBridge command:  

&hb_token=f04df849&hb_show_xml=1&&hb_show_screen=1&hb_field_rename=1&hb_debug=0&hb_show_rowcol=1&hb_show_attr=0 &hb_show_name=0&hb_type=ads tehb4000 

XML output generated: See sampleADSOTransactionOutput2.xml

HostBridge command:  

&hb_token=f04df849&hb_show_xml=1&&hb_show_screen=1&hb_field_rename=1&hb_debug=0&hb_show_rowcol=1&hb_show_attr=0&hb_show_name=0&hb_aid=pf3 

XML output generated: See sampleADSOTransactionOutput3.xml

HostBridge command:  

&hb_token=f04df849&hb_show_xml=1&&hb_show_screen=1&hb_field_rename=1&hb_debug=0&hb_show_rowcol=1&hb_show_attr=0&hb_show_name=0&hb_aid=pf1 

XML output generated: See sampleADSOTransactionOutput4.xml

HostBridge command:  

&hb_token=f04df849&hb_show_xml=1&&hb_show_screen=1&hb_field_rename=1&hb_debug=0&hb_show_rowcol=1&hb_show_attr=0&hb_show_name=0&MR-ACT-MBR-NUM=065490256&MR-ACT-GRP-NUM=e024216 

XML output generated: See sampleADSOTransactionOutput5.xml

HostBridge command:  

&hb_token=f04df849&hb_show_xml=1&&hb_show_screen=1&hb_field_rename=1&hb_debug=0&hb_show_rowcol=1&hb_show_attr=0&hb_show_name=0&hb_aid=pf10

 XML output generated: See sampleADSOTransactionOutput6.xml

HostBridge command: 

&hb_token=f04df849&hb_show_xml=1&&hb_show_screen=1&hb_field_rename=1&hb_debug=0&hb_show_rowcol=1&hb_show_attr=0&hb_show_name=0&hb_aid=pf10

XML output generated: See sampleADSOTransactionOutput7.xml

HostBridge command:  

&hb_token=f04df849&hb_show_xml=1&&hb_show_screen=1&hb_field_rename=1&hb_debug=0&hb_show_rowcol=1&hb_show_attr=0&hb_show_name=0&hb_aid=pf10

XML output generated: See sampleADSOTransactionOutput8.xml

HostBridge command: 

&hb_token=f04df849&hb_show_xml=1&&hb_show_screen=1&hb_field_rename=1&hb_debug=0&hb_show_rowcol=1&hb_show_attr=0 &hb_show_name=0&hb_aid=pf10

XML output generated: See sampleADSOTransactionOutput9.xml


  • No labels
Write a comment…