Installing the Data Engine

Note Media for the Services Builder for CICS 3270 Bridge includes both a tape and a CD. The license for both is located on the CD. Ensure that the license on the CD has been accepted before proceeding with the installation.

All installation steps are required unless a particular step is specifically noted to be optional.

This product uses approximately 9 KBytes of auxiliary temporary storage per active Bridge session. In order to have enough auxiliary temporary storage in your region, you may need to factor this requirement into your auxiliary temporary storage definition.

You can upload the product files from tape or CD using the following procedures:

Before starting the installation, you may wish to verify that you have all the information needed for installing at your site. For details, see Site-Specific Information.

To install the data engine from CD
  1. From the CICS_Data_Engine directory on the installation CD, upload the following binaries to your OS/390 server.
    Upload this binary To
    ATTMF.XXTR200.F1 YourHLQ.TXTR200.F1
    ATTMF.XXTR200.F2 YourHLQ.TXTR200.F2
    ATTMF.XXTR200.F3 YourHLQ.TXTR200.F3
    ATTMF.XXTR200.F4 YourHLQ.TXTR200.F4
    ATTMF.XXTR200.SMPMCS YourHLQ.TXTR200.SMPMCS

  2. Upload the text file CD_Drive:\CICS_Data_Engine\RECVPROD to your OS/390 server at YourHLQ.ATTM.JCL(RECVPROD).

    This text file contains JCL that allocates files in relfile format on SYSDA and then does the RECEIVES (not to be confused with SMP/E RECEIVE) from the uploaded binaries into the appropriate relfiles.

  3. In YourHLQ.ATTM.JCL(RECVPROD), follow the instructions in the member, modifying as per your local qualifiers, and submit the job:
    //RECVPROD JOB (BATCH),BLDSMP1.SMPEUSER,
    //             MSGCLASS=X,NOTIFY=&SYSUID,
    //             REGION=6M,TIME=1439
    //*
    //*** BUILD PRODUCT ON DISK IN RELFILE FORMAT
    //*********************************************************
    //* PRIOR TO SUBMITTING, CHANGE THE FOLLOWING:
    //*
    //*********************************************************
    //*  JOB CARD: TO MEET YOUR INSTALLATION STANDARDS
    //*  GLOBAL CHANGE &HLQ TO YOUR INSTALLATION DSN HIGH LEVEL
    //*                     QUALIFIER
    //*  GLOBAL CHANGE &PRDVOL TO THE SMP DATASET DASD VOLUME
    //*********************************************************
    //*
    

    At this point, you should have the product files in relfile format on SYSDA on your mainframe. To continue the installation, follow the steps To complete the CICS definitions.

Note This product uses approximately 9 KBytes of auxiliary temporary storage per active Bridge session. In order to have enough auxiliary temporary storage in your region, you may need to factor this requirement into your auxiliary temporary storage definition.
To install the data engine to an IBM OS/390 server from tape
  1. Upload the text file CD_Drive:\CICS_Data_Engine\TAPEUNLD on the installation CD, to your OS/390 server at YourHLQ.ATTM.JCL(TAPEUNLD).

    This text file contains JCL that allocates and copies the product files in relfile format on SYSDA.

  2. In YourHLQ.ATTM.JCL(TAPEUNLD), follow the instructions in the member, modifying as per your local qualifiers, and submit the job:
    //TAPEUNLD JOB (BATCH),TAPEUNLD.SMPEUSER,
    //             MSGCLASS=X,NOTIFY=&SYSUID,
    //             REGION=6M,TIME=1439
    //*-----------------------------------------------------
    //*     LOAD RELFILE FORMAT FILES TO DISK
    //*-----------------------------------------------------
    //* 
    //******************************************************
    //*  PRIOR TO SUBMITTING, CHANGE THE FOLLOWING:
    //*               
    //*  JOB CARD: TO MEET YOUR INSTALLATION STANDARDS.
    //*  PROC VARIABLES TO YOUR INSTALLATION STANDARDS.
    //******************************************************
    

    At this point, you should have the product files in relfile format on SYSDA on your mainframe. To continue the installation, follow the steps To complete the CICS definitions.

To complete the CICS definitions
  1. Upload the text file CD_Drive:\CICS_Data_Engine\CICSDEFS to your OS/390 server at YourHLQ.ATTM.JCL(CICSDEFS).

    This text file contains JCL that defines required CICS resources for the target CICS region. This file is used during the system definition process.

  2. In YourHLQ.ATTM.JCL(CICSDEFS), follow the instructions in the member, modifying as per your local qualifiers, and submit the job.

  3. From the installation CD, upload the text file CD_Drive:\CICS_Data_Engine\UNLOAD to your OS/390 server at YourHLQ.ATTM.JCL(UNLOAD).

    This text file contains JCL that allocates a local Partitioned Data Set (PDS) and copies your SMP/E samples as members into that PDS.

  4. In YourHLQ.ATTM.JCL(UNLOAD), follow the instructions in the member, modifying as per your local qualifiers, and submit the job:
    //UNLOAD JOB (BATCH),BLDSMP1.SMPEUSER,
    //MSGCLASS=X,NOTIFY=&SYSUID,
    //REGION=6M,TIME=1439
    //*
    //***UNLOAD SMP/E SAMPLE MEMBERS FOR PRODUCT INSTALL
    //**********************************************************
    //* PRIOR TO SUBMITTING, CHANGE THE FOLLOWING:
    //*
    //*  JOB CARD: TO MEET YOUR INSTALLATION STANDARDS.
    //*
    //* CHANGE &HLQ TO THE DSN HIGH LEVEL QUALIFIER YOU USED FOR
    //* YOUR SMP/E PRODUCT FILES:
    //*                                                          
    //* FOR EXAMPLE: IF YOU MADE YOUR SMPE PRODUCT FILES START
    //*     WITH ATTMF AS IN ATTMF.XXTR200.SMPMCS
    //*     THEN DSN=&HLQ.XXTR200.F2
    //*     SHOULD BE DSN=ATTMF.XXTR200.F2
    //*
    //* CHANGE &SYSDA TO MATCH YOUR INSTALL UNIT DEVICE NAME.
    //* CHANGE &PRDVOL TO MATCH YOUR INSTALL VOLUME NAME.
    //* CHANGE &YOUR.INSTALL.LIB TO THE PDS NAME YOU WANT FOR
    //* YOUR SAMPLE MEMBERS.
    //*********************************************************
    
  5. Build the SMP/E environment by updating the restored XT1SMPBL member, then follow the change specifications at the beginning of the member, save, and submit the job:
    //jobname JOB (account)//*
    //******************************************************
    //*
    //* THIS JOB WILL ALLOCATE SMP/E DATASETS, DEFINE AND 
    //* INITIALIZE THE CSI, AND THEN DEFINE GLOBAL, TARGET,
    //* AND DLIB ZONES WITHIN THE SAME PHYSICAL VSAM DATASET
    //*
    //* PRIOR TO SUBMITTING, CHANGE THE FOLLOWING:
    //*
    //******************************************************
    //*  JOB CARD: TO MEET YOUR INSTALLATION STANDARDS
    //*  GLOBAL CHANGE &SMQ    TO THE HIGH LEVEL INDEX OF 
    //*                        DATASETS (MAXIMUM 18 
    //*                        CHARACTERS)
    //*  GLOBAL CHANGE &HLQ    TO THE HIGH LEVEL INDEX OF 
    //*                        PRODUCT DATASETS
    //*  GLOBAL CHANGE &SYSDA  TO THE UNIT NAME FOR DASD 
    //*                        DEVICES
    //*  GLOBAL CHANGE &SMPVOL TO THE SMP DATASET DASD VOLUME
    //*  GLOBAL CHANGE &PRDVOL TO THE PRODUCT LIBRARY DASD 
    //*                        VOLUME
    //*  GLOBAL CHANGE &DFHLOD TO THE CICS SDFHLOAD LIB WITH
    //*                        DFHEI1
    //*  GLOBAL CHANGE &CEELKD TO THE LE LINK EDIT LIBRARY 
    //*                        CEE.SCEELKED
    //******************************************************
    
    Note This step can be omitted if you have previously installed this product on your mainframe.

At this point, you are ready To receive the product.

To receive the product
  1. If you are using a multi-segment high-level qualifier, go to Step 2. If you are not using a multi-segment high-level qualifier, do the following:
    • Update the &hlq.XXTR200.SMPMCS(SMPMCS) member. Change the RFDSNPFX(&HLQ) to equal the &hlq value in &hlq.XXTR200.SMPMCS(SMPMCS) and &hlq.XXTR200.F1 through &hlq.XXTR200.F4. Save the changed SMPMCS member:
      ++FUNCTION(XXTR200) FILES(4) REWORK(2005090) RFDSNPFX(&HLQ)
      /**********************************************************
      //* LICENSED MATERIALS - PROPERTY OF ATTACHMATE            */
      /*                                                         */
      /***********************************************************/
      /***********************************************************/
      /* IN THE ABOVE ++FUNCTION STATEMENT
      /* CHANGE &HLQ TO THE DSN HIGH LEVEL QUALIFIER YOU USED FOR
      /* YOUR SMP/E PRODUCT FILES:
      /* FOR EXAMPLE: IF YOU MADE YOUR SMPE PRODUCT FILES START
      /*       WITH ATTMF AS IN ATTMF.XXTR200.SMPMCS
      /*       THEN RFDSNPFX(ATTMF)
      /*
      /**********************************************************/
      
    • After completing the RFDSNPFX(&HLQ) modification, update the restored XT1RECV member, then follow the change specifications at the beginning of the member, save, and submit the job:
      //SMPERECV JOB (BATCH),XT1RECV.SMPUSER,
      //             MSGCLASS=X,NOTIFY=&SYSUID,
      //             REGION=6M,TIME=1439
      //*
      //************************************************************
      //*
      //* RECEIVE PRODUCT
      //*
      //* PRIOR TO SUBMITTING, CHANGE THE FOLLOWING:
      //*
      //************************************************************
      //*  JOB CARD: TO MEET YOUR INSTALLATION STANDARDS
      //*  GLOBAL CHANGE &SMQ    TO THE HIGH LEVEL INDEX OF 
      //*                        SMP DATASETS (MAXIMUM 18
      //*                        CHARACTERS)
      //*  GLOBAL CHANGE &SYSDA  TO THE UNIT NAME FOR YOUR
      //*                        INSTALL DISK.
      //*  GLOBAL CHANGE &PRDVOL TO THE DISK VOLUME FOR YOUR
      //*                        INSTALL DISK.
      //*
      //* CHANGE &HLQ TO THE DSN HIGH LEVEL QUALIFIER YOU USED FOR  
      //* YOUR SMP/E PRODUCT FILES:                                 
      //*                                                           
      //* FOR EXAMPLE: IF YOU MADE YOUR SMPE PRODUCT FILES START    
      //*              WITH ATTMF AS IN ATTMF.XXTR200.SMPMCS        
      //*              THEN DSN=&HLQ.XXTR200.SMPMCS(SMPMCS)         
      //*              SHOULD BE DSN=ATTMF.XXTR200.SMPMCS(SMPMCS)
      //*
      //* IMPORTANT NOTE:
      //*   MAKE SURE TO EDIT THE &HLQ.XXTR200.SMPMCS (SMPMCS) AND
      //*   UPDATE RFDSNPFX (&HLQ) IN THAT MEMBER TO YOUR DNS HIGH
      //*   LEVEL QUALIFIER BEFORE SUBMITTING THIS JOB!
      //************************************************************
      

      Now go to Step 3.

  2. If you are using a multi-segment high-level qualifier, do the following:
    • Comment out or remove the RFDSNPFX parameter of the ++FUNCTION statement in yourHiLvl.SMPMCS(SMPMCS) as in the following:

      From:

      ++FUNCTION(XXTR200) FILES(4) REWORK(2005090) RFDSNPFX(&HLQ)   
       /***********************************************************/
       /* LICENSED MATERIALS - PROPERTY OF ATTACHMATE             */
       /*                                                         */
       /***********************************************************/
      

      To:

      ++FUNCTION(XXTR200) FILES(4) REWORK(2005090)   
       /***********************************************************/
       /* LICENSED MATERIALS - PROPERTY OF ATTACHMATE             */
       /*                                                         */
       /***********************************************************/
      
    • Add a PREFIX parameter to your XT1RECV member of your SMP/E sample library as in the following example.
      Note Don't forget to move the period to after the ending parenthesis of the RFPREFIX value as shown.
      //RECEIVE  EXEC PGM=GIMSMP,REGION=4096K,PARM='DATE=U'       
      //SMPCSI   DD  DSN=HLVL.SMPE2.ATTACHMT.SMPCSI.CSI,DISP=SHR 
      //*                                                         
      //SMPPTFIN DD  DSN=HLVL.ATTMF101.XXTR200.SMPMCS(SMPMCS),   
      //             UNIT=SYSDA,                                  
      //             VOL=SER=OS39M1,                              
      //             LABEL=(1,SL),                                
      //             DISP=OLD                                     
      //SMPCNTL  DD *                                             
       SET BDY(GLOBAL).                                           
       RECEIVE S(XXTR200) SYSMOD RFPREFIX(SMPE.ATTACH.MATE).        
      
    • Do the same for the re-receives in the XT1UANLZ, XT1UCNVT and XT1USRVR if/when you submit them. Follow this model (which is an example of XT1UANLZ):
      //APPLY    EXEC PGM=GIMSMP,PARM='DATE=U'                        
      //SMPCSI   DD DISP=SHR,DSN=HLVL.SMPE2.ATTACHMT.SMPCSI.CSI      
      //SMPCNTL  DD *                                                 
       SET BDY(GLOBAL) .                                              
        RECEIVE S(LUMANLZ) SYSMOD RFPREFIX(SMPE.ATTACH.MATE).         
       SET BDY(XT1TGT1) .                                             
        APPLY                                                         
                /*  CHECK   /* COMMENTED OUT FOR ACTUAL APPLY */     
                 REDO       /* "REDO" USED TO RE-APPLY USERMOD */     
           S(LUMANLZ) .                                               
      
  3. Apply the product by updating the restored XT1APPLY member, then follow the change specifications at the beginning of the member, save, and submit the job:
    //jobname JOB (account)
    //*
    //*
    //******************************************************
    //*
    //* APPLY PRODUCT
    //*
    //* PRIOR TO SUBMITTING, CHANGE THE FOLLOWING:
    //*
    //******************************************************
    //*  JOB CARD: TO MEET YOUR INSTALLATION STANDARDS
    //*  GLOBAL CHANGE &SMQ TO THE HIGH LEVEL INDEX OF 
    //*                        SMP DATASETS
    //******************************************************
    

    This job will end with a condition code of 0. Message GIM23913I, with a return code of 4 from link edit processing to the SMPLTS, is normal and can be ignored.

    Note Make sure the loadlib to which the CICS modules are loaded is in the CICS loadlib concatenation. See your CICS DD DFHRPL.
  4. Accept the product by updating the restored XT1ACCPT member, then follow the change specifications at the beginning of the member, save, and submit the job:
    //jobname JOB (account)
    //*
    //******************************************************
    //* ACCEPT PRODUCT
    //* PRIOR TO SUBMITTING, CHANGE THE FOLLOWING:
    //******************************************************
    //*  JOB CARD: TO MEET YOUR INSTALLATION STANDARDS
    //*  GLOBAL CHANGE &SMQ    TO THE HIGH LEVEL INDEX OF 
    //*  SMP DATASETS
    //******************************************************
    
  5. Customize the Analyzer Controller Template using the XTR1S001 macro embedded in the restored XT1UANLZ member.

    For specific information on how to use the XTR1S001 macro, refer to Customizing the CWI Analyzer Module.

  6. Note Without IP Filter modification, the Analyzer as delivered will accept requests from any IP Address.
  7. Update CICS Web Analyzer installation options by updating the XT1UANLZ member, then follow the change specifications at the beginning of the member, and submit the job.

    Note To modify options from a previous APPLY, uncomment the REDO parameter on the APPLY statement, modify the REWORK parameter provided to a larger number than used on the prior APPLY of this USERMOD, and resubmit the job.
  8. (Optional) Customize the Good Morning Message (CSGM) by updating the XTR1S004 logo embedded in the XTR1USRVR JCL to match the CICS logo screen used in your local environment.

    By default, if new 3270 connections in your local environment are greeted with a Good Morning Message rather than a security logon, a standard representation of the actual IBM CICS CSGM logo screen is displayed on the 3270 screen of the connecting client.

    As shipped, each line of the logo in the XTR1USRVR JCL is 40 characters wide, and each logo is 11 lines long. At run-time, the Attachmate Bridge places this logo in the center of the 3270 screen of the connecting client. The placement varies based on the number of columns and lines of the particular terminal model.

    >The standard logo is as follows:

    XTR1S004 CSECT
    XTR1S004 AMODE 31
    XTR1S004 RMODE ANY
             DC A(GMLINLEN)
             DC A(GMSCRLNS)
             DC A(GMSCRLEN)
    *--------------------------------------------------------
    *  24X80 DC'D AS 48 LINES OF 40 BYTE CONSTANTS COMPRISING
    *  THE WELCOME TO CICS SCREEN
    *--------------------------------------------------------
    GMSCREEN DS  0H
    GMSCRLN1 DC  CL40' ******\  ******\  ******\   ******\'
    GMSCRLN2 DC  CL40'********\ ******\ ********\ ********\'
             DC  CL40'**\\\\**\   **\\\ **\\\\**\ **\\\\**\'
             DC  CL40'**\    \\   **\   **\    \\ **\    \\'
             DC  CL40'**\         **\   **\       *******\'
             DC  CL40'**\         **\   **\        *******\'
             DC  CL40'**\         **\   **\         \\\\**\'
             DC  CL40'**\   **\   **\   **\   **\ **\   **\'
             DC  CL40'********\ ******\ ********\ ********\'
             DC  CL40' ******\\ ******\  ******\\  ******\\'
             DC  CL40'  \\\\\\   \\\\\\   \\\\\\    \\\\\\ TM'
    GMSCREND DC  X'FF'
    GMLINLEN EQU GMSCRLN2-GMSCRLN1
    GMSCRLEN EQU GMSCREND-GMSCREEN
    GMSCRLNS EQU ((GMSCRLEN/GMLINLEN)+1)
                END   XTR1S004
    
    

    Only the lines GMSCRLN1 to the line preceding GMSCREND should be altered to match your customized CICS logo. All other lines should remain unaltered in order for the runtime to support logo customization.

    Please note that the one-line "Welcome to CICS…" message superimposed is customized by the CICS systems programmer in the CICS Systems Initialization Table (SIT), and so shouldn't be added to the modified logo.

    The Attachmate run-time 3270 Bridge Server harvests this customized string and superimposes it at run time, in a manner identical to that used by IBM.

    Whether the Attachmate-supplied logo screen is modified or not, the job in member XTR1USRVR should be submitted to complete the tailoring of the Attachmate 3270 Bridge program.

    Care should be taken to ensure return codes from the assembly and link-edit steps are successful, as is standard practice when customizing an assembler macro.

    Note To modify options from a previous APPLY, uncomment the REDO parameter on the APPLY statement, modify the REWORK parameter provided to a larger number than used on the prior APPLY of this USERMOD, and resubmit the job.
  9. Update CICS Converter installation options by updating the restored XT1UCNVT member, then follow the change specifications at the beginning of the member and submit the job.
    Note To modify options from a previous APPLY, uncomment the REDO parameter on the APPLY statement, modify the REWORK parameter provided to a larger number than used on the prior APPLY of this USERMOD, and resubmit the job.

    The following Converter Macro shows default values for the macro keyword parameters:

    *----------------------------------------------------------*
    *       CONFIGURATION MACRO DEFINITION FOR XTR1S002        *
    *                                                          *
    *  - CONFIGURE PRINCIPLE FACILITY MODELS FOR 327X          *
    *    TERMINALS MODEL 1 THROUGH MODEL 5.                    *
    *  - CONFIGURE FACILITY KEEPTIME VALUE, THE AMOUNT OF      *
    *    TIME AFTER THE TRANSACTION TASK ENDS THAT THE BRIDGE  *
    *    WILL KEEP THE FACILITY (AND FACILITY TOKEN) VALID.    *
    *  - CONFIGURE GET WAIT INTERVAL FOR SERVER:BRIDGE AND     *
    *    BRIDGE: SERVER TIMEOUT IN MILLISECONDS.               *
    *  - CONFIGURE SESSION INACTIVITY TIMEOUT FOR AMOUNT OF    *
    *    TIME THE SESSION STATE WILL BE MAINTAINED WHILE       *
    *    INACTIVE, IN SECONDS.                                 *
    *----------------------------------------------------------*
     MACRO                             MACRO HEADER
     XTR1S003
        MOD1FAC=CBRF,     PRINCIPLE TERMINAL FACILITY MOD1     X
       &MOD2FAC=CBRF,     PRINCIPLE TERMINAL FACILITY MOD2     X
       &MOD3FAC=CBRF,     PRINCIPLE TERMINAL FACILITY MOD3     X
       &MOD4FAC=CBRF,     PRINCIPLE TERMINAL FACILITY MOD4     X
       &MOD5FAC=CBRF,     PRINCIPLE TERMINAL FACILITY MOD5     X
       &GMMTRAN=NO,       DON'T RUN A GOOD MORNING TRANSACTION X
       &CTRAN=ATMC,       SESS INACTIVE TIMEOUT CLEANUP TRANS  X
       &FACKPTIM=00000258, FACILITY KEEPTIME OF 600 SECONDS     X
       &GETWAIT=000927C0,  SERVER:BRIDGE TIMEOUT OF 600,000 MSECs X
       &TIMEOUT=00000258   SESSION INACTIV TIMEOUT OF 600 SECS
     MVC   0(4,7),=C'&MOD1FAC'
     MVC   4(4,7),=C'&MOD2FAC'
     MVC   8(4,7),=C'&MOD3FAC'
     MVC  12(4,7),=C'&MOD4FAC'
     MVC  16(4,7),=C'&MOD5FAC'
     MVC  20(4,7),=C'&CTRAN'
     MVC  24(4,7),=X'&FACKPTIM'
     MVC  28(4,7),=X'&GETWAIT'
     MVC  32(4,7),=X'&TIMEOUT'
     MVC  36(4,7),=CL'&GMMTRAN'
     BR   14
     CICSSTUB DC  V(DFHEAI)
              MEND
    

    MOD1FAC through MOD5FAC are your installation's 3270 terminal profiles for models 1 through 5.

    GMMTRAN determines the initial state for a session. Using the default value GMMTRAN=NO, the connected session begins at a blank screen, ready to start a CICS transaction. If a valid user-id and password are not supplied with the ConnectBridge API, GMMTRAN can be utilized to identify the sign on transaction or good morning banner to be issued to the newly created session. Candidates for GMMTRAN must be CSGM, CESN, or a 3270 Bridge compatible CICS transaction program.

    Note If a valid set of user-id and password credentials are supplied with the ConnectBridge API, the Extermal Security Manager (e.g., RACF) authenticated session begins at a blank screen and the GMMTRAN transaction is bypassed.

    CTRAN is the cleanup Transaction ID defined for the data engine server program (XTR1A002).

    FACKPTIM is the number of seconds after completion of the bridge task, that CICS will keep the virtual principle facility it has created for the task.

    GETWAIT is the maximum wait in milliseconds by the linkable bridge for message input from the data engine server for the session.

    TIMEOUT is the number of seconds an active Services Builder session can remain inactive before it is timed out and cleaned up.

    Note For proper operation, the data engine requires that the IBM-supplied 3270 Bridge Formatter program, located in the PDS cicshlq.CICS.SDFHSAMP(DFH0CBRF), must be compiled and link-edited into an accessible load library identified in the DFHRPL statement. Please refer to the CICS DD DFHRPL in the CICS startup JCL of the target region.
Related Topics
Bullet Installation, Overview
Bullet Upgrading, Overview
Bullet Installing in UNIX
Bullet Installation Prompts for Management Components in Windows
  Attachmate