Skip to content
CA InterTest™ and CA SymDump® - 10.0
Documentation powered by DocOps

CICS Interfaces and Compatibility

Last update February 28, 2019

This article contains interface and compatibility considerations for CA InterTest for CICS and CA SymDump for CICS.

CA InterTest for CICS and CA SymDump for CICS 

The following interface and compatibility information pertains to both CA InterTest for CICS and CA SymDump for CICS.

Install DB2 Support

Use the following procedure to install DB2 support.

Follow these steps:

  1. The CSDDB266, CSDDB267, CSDDB268, CSDDB269, and CSDDB270 members on CAI.CAVHJCL provide RDO entries.
  2. Bind the DBRM members (INA0FIDB and INA0AIDB) provided in the CAI.CAVHDBRM into an InterTest DB2 plan (the recommended name is INA0PLAN).The SAMPBIND member on CAI.CAVHJCL library provides a sample of DB2 BIND statements for the InterTest DB2 plan. For CA SymDump for CICS, you only need to bind the DBRM member INA0AIDB provided on the CAI.CAVHDBRM into the DB2 plan (the recommended name is INA0PLAN).
  3. The DBA must grant bind and execute authority to the plan created in the previous step.
  4. For DB2 subsystems running in new function mode (release 10.1 and above), ensure that the library containing the customized DSNHDECP (either SDSNEXIT or SDSNLOAD) is in the DFHRPL DD concatenation after the CICS program libraries.
  5. In order to support the CORE=LASTSQL command for CA InterTest and SymDump for CICS, the global exit XRMIOUT is started (by default) when you start the product. This exit then collects DB2-related call information for every DB2 call done in the system. This can have significant performance implications in some DB2 shops. The parameter XRMIO=YES/NO IN25OPTS controls use of this exit. The default is XRMIO=YES. We recommend that you carefully review this prior to using the default settings.

CICS Startup DSA Limit Parameter

CA InterTest for CICS and SymDump for CICS make calls to IEWBIND when using the new online COMPOSITE module command and IEWBIND requires about 750 KB of below the line storage. To ensure there is sufficient storage available (below the line for IEWBIND calls), you must insure that your DSALIM is at least 750 KB less than your below the line private area size. Failure to do this could result in S0F4 and U900 abends in your CICS region during dump capture.

Update the CICS JCL and Startup Parameters

If your site has previously installed CA InterTest or SymDump for CICS as a separate product, some DD statements may already exist.

If you use DD statements in your CICS startup JCL, your CA InterTest and SymDump for CICS files, as defined in the CSD, require DD statements in the JCL for CICS. DISP=SHR must be specified for PROTSYM to allow batch compiles to run concurrently with CICS. Alternatively, you may directly add the data set names to the CEDA FILE definition, defined in the CSDSYM member in CAI.CAVHJCL and remove the DD statements for those files.

CA InterTest and SymDump Common DD Statements

Add the product load library to the DFHRPL in the CICS startup JCL.

//  DD   DSN=CAI.CAVHLOAD,DISP=SHR

Note:

  • If you modified the IN25OPTS options during installation, make sure the load library that contains the modified IN25OPTS is in your DFHRPL concatenation before the CAI.CAVHLOAD library.
  • CA Intertest for CICS and CA SymDump for CICS do not support the IBM Dynamic program LIBRARY concatenation feature at this time.


If you execute the demo programs, add the following DD to the DFHRPL in your CICS startup JCL. Specify the name of the load library which contains the demo programs:

// DD DSN=CAI.demoload,DISP=SHR

CICS DD statements

//PROTCPF  DD DSN=CAI.PROTCPF,DISP=OLD (CA InterTest for CICS only)

//PROTDMP   DD DSN=CAI.PROTDMP,DISP=SHR (CA SymDump for CICS only)

//SYSMDUMP  DD DSN=your.dataset.name(CA SymDump for CICS only)
//PROTSYM  DD DSN=CAI.PROTSYM,DISP=SHR
//PROTHLF  DD DSN=CAI.CAVHHLF,DISP=SHR
//PROTUHF  DD DSN=CAI.PROTUHF,DISP=SHR

Note: Pre-allocate your SYSMDUMP data set with RECFM=FB,LRECL=4160,BLKSIZE=4160 and with enough space to capture an SVC dump for your CICS region.

Add the Required CICS Resource Definitions

Member, CSDINT in CAI.CAVHJCL library adds the CICS resource definitions for the CA InterTest for CICS programs, files, and transactions. The CSDSYM member in CAI.CAVHJCL adds the CICS resource definitions for the CA SymDump for CICS programs, files, and transactions. Modify the JCL according to the instructions in these members.

Add the corresponding RDO group to your CICS startup list (the SIT parameter GRPLIST=) as listed in the following table:

CICS Level CA InterTest for CICS RDO Group CA SymDump for CICS RDO Group
CTS 5.1 INT10068 SYM10068
CTS 5.2 INT10069 SYM10069
CTS 5.3 INT10070 SYM10070
CTS 5.4 INT10071 SYM10071
CTS 5.5 INT10072 SYM10072

The use of the CA InterTest for CICS transactions ISER, VIRC, and VTAT must not be protected to a specific sign on, and for CA ACF2 and RACF users must meet the special considerations described in Installation Considerations.

Do not change any of the options specified for the CA InterTest or SymDump for CICS entries. If you believe there is an error in any of the entries, contact CA Technical Support.

For CICS regions that use DB2, you must install the DB2CONN group before the CA InterTest or SymDump for CICS RDO entries.

Add Assembler DSECTs to the Symbolic File

CA InterTest and SymDump for CICS let you display the major CICS areas in Assembler DSECT format. You can also display your own user areas in DSECT format. One way to do this is to add your DSECTs to the ones supplied by CA InterTest and SymDump for CICS. However, if you do this, your entries will disappear when you install a new release of CA InterTest and SymDump for CICS. A better way is to create one or more symbolic file members to contain your DSECTs.

Saving all of the DSECTs used at your site in one symbolic file member allows users of the FILE transaction to omit the symbolic program name when requesting records or DL/I segments in structured format. The name of this member must be referenced in the FSYMP installation option. The default name is PROTFILE.

Complete the following steps to create your own symbolic file members:

  1. Run a job to add the members containing the DSECTs to the symbolic file.
  2. Run a job to define the CORE keywords needed to display the DSECTs.

Sample JCL for Adding Members to the Symbolic File

This sample JCL adds member USERDSEC to the symbolic file. This member contains the DSECT USERTWAF.

//USERDSEC         JOB   **your JOB card goes here**

//ASM          EXEC  PGM=ASMA90,REGION=1024K

//SYSLIB       DD    DSN=USER.SOURCE,DISP=SHR

//SYSUT1       DD    DSN=&SYSUT1,SPACE=(1024,(120,120),,,ROUND),

                     UNIT=VIO,

//                   DCB=BUFNO=1

//SYSPUNCH     DD    SYSOUT=B

//SYSTERM      DD    SYSOUT=*

//SYSPRINT     DD    DSN=&&TEMP,DISP=(,PASS),UNIT=SYSDA,

                     SPACE=(CYL,(3,2)),

//                   DCB=(RECFM=FBM,LRECL=121,BLKSIZE=2420)

//SYSIN        DD    *

USERTWAF       DSECT

               COPY USERTWAF

USERDSEC       CSECT

               END

//*

//PARM         EXEC  PGM=IN25PARM,REGION=512K,

//                   PARM='USERDSEC,LISTER=REF,NOPURGE'

//STEPLIB      DD    DSN=CAI.CAVHLOAD,DISP=SHR

//CARDS        DD    DSN=&&CARDS,DISP=(,PASS),UNIT=SYSDA,

                     SPACE=(80,1)

//*

//SA           EXEC  PGM=IN25SYMA,REGION=512K

//STEPLIB      DD    DSN=CAI.CAVHLOAD,DISP=SHR

//INPUT        DD    DSN=&&TEMP,DISP=(OLD,DELETE)

//OUTPUT       DD    SYSOUT=*,

                     DCB=(RECFM=FBM,LRECL=121,BLKSIZE=2420)

//MESSAGE      DD    SYSOUT=*

//PROTSYM      DD    DSN=INTRTST.PROTSYM,DISP=SHR

//CARDS        DD    DSN=&&CARDS,DISP=(OLD,DELETE)

 /*

For instructions on the STEPLIB DD, see the section Add COBOL File Structures to the Symbolic File.

For an explanation of the IN25PARM and IN25SYMA programs, see Adding Symbolic Information.

Note: This job does not require a link-edit step because it only updates the symbolic file. No load module is produced.

CA InterTest for CICS

Use the PROMMAC Macro

You can use PROMMAC macros in an assembly to create a load module defined in the CICS program definition that contains a number of CNTL commands. These commands are executed consecutively in the order of their appearance in the macros when either of the following commands is submitted:

CNTL=START,PROM=tablname

CNTL=EXEC,MODULE=tablname

Where tablname is the name of the load module generated by the assembly of the PROMMAC macros.

You can generate several alternate modules with different names, each with a CICS program definition, if you want alternate ways to start CA InterTest for CICS or execute CNTL commands.

If the PROMD=tablname option is specified in the IN25OPTS macro, you can achieve the same result by specifying:

CNTL=START

If the CNTL=START command is issued from a CRT terminal or CRLP-type terminal (a terminal whose input and output are two sequential files; see the IBM CICS System Programmer's Guide), the commands from the load module are displayed back. For a CRT terminal, there is a small time delay before each command is executed so the user can see what is being done.

The first positional parameter of the PROMMAC macro contains the CNTL command to be executed. The command must be enclosed in apostrophes.

If the table is to be used by the CNTL=START command, the first PROMMAC macro must contain this command:

CNTL=START,PROM=nn,PROX=nn'

Where nn sets the sizes of the internal CA InterTest for CICS tables.

The second positional parameter of the PROMMAC macro must contain END. It must be coded in the last PROMMAC macro before the END statement.

Any CNTL command can be specified except CNTL=LIST and CNTL=INQ.

Sample PROMMAC Macros

The following JCL is suitable for z/OS installations. These examples are shown for illustration purposes only. For more information, see CICS Debugging.

//PROMAC JOB (NTSM,473),'JOHN BROWN',CLASS=D,MSGCLASS=A

//ASSEM  EXEC  PGM=ASMA90,REGION=512K,
//       PARM='XREF(SHORT),DECK,NUM,LIST,ALIGN,NOOBJ'
//*
//SYSLIB   DD DSN=CAI.CAVHMAC,DISP=SHR
//SYSUT1   DD SPACE=(CYL,(1,1)),UNIT=SYSDA
//SYSUT2   DD SPACE=(CYL,(1,1)),UNIT=SYSDA
//SYSUT3   DD SPACE=(CYL,(1,1)),UNIT=SYSDA
//SYSPUNCH DD DSN=&OBJ,SPACE=(TRK,(1,1)),UNIT=SYSDA,
//       DCB=(BLKSIZE=800,LRECL=80,RECFM=FB),DISP=(,PASS)   
//SYSPRINT DD SYSOUT=A
//SYSIN    DD *
  PROMMAC  'CNTL=START,PROM=20,PROX=5'
  PROMMAC  'CNTL=ABP,ON,T321'
  PROMMAC  'CNTL=ON,PROG=(CFIL,TERMIO,FILEIO,ERRORS,SCAN,LLASRCH),
            USR=.ANY'
  PROMMAC  'CNTL=EXCL,PROG=(TERMIO,FILEIO)'
  PROMMAC  'CNTL=ON,PROG=PBMASTER,FOL=ON,USR=.ANY'
  PROMMAC  'CNTL=PURGE,INTRVAL=0100',END
  END
/*      
//LINK  EXEC  PGM=IEWL,PARM='LIST,XREF,MAP',REGION=512K
//SYSLMOD  DD DSN=CAI.CAVHLOAD(PROMAC),DISP=SHR
//SYSUT1   DD UNIT=SYSDA,SPACE=(TRK,(10,10))
//SYSPRINT DD SYSOUT=A
//SYSLIN   DD DSN=&&OBJ,DISP=(OLD,DELETE)
//

Note: A CICS program definition named PROMAC is required for the generated table.

Enter CNTL Commands from a CRLP-Type Terminal

If you have at least one CRLP-type terminal defined in your TCT, its input sequential file can contain CNTL commands. These commands are executed in sequence just as if they were entered manually from a terminal. Responses to them are written in the terminal's output sequential file.

To reduce the amount of time required to process large numbers of CNTL commands, perform the following steps:

  1. Create a load module that contains the CNTL commands to be processed using the PROMMAC macro.
  2. Add a PPT entry for the load module.
  3. Set the following CA InterTest for CICS options:

    RECNTMU=NO

    RECNTNW=NO

  4. Replace the CNTL commands in the sequential input with the following command:

    CNTL=START,PROM=name

Where name is the name of the module that was created in Step 1.

Note: You can add the USR= option to any embedded CNTL=ON commands to assign the entries to a specific user ID. See CNTL Commands and Menus.

Calls to Software and User Macro Support

This section explains how to support software (which must not be monitored by CA InterTest for CICS) that is invoked by CALLs from your application programs or your own macros. For example:

  • To support global routines whose addresses are found in the CWA and that are given control from monitored programs by a BALR 14,14 or BALR 14,15 instruction. When such routines are given control, they are not monitored by CA InterTest for CICS until they return to the next byte after the BALR in the calling program.
  • To make CA InterTest for CICS recognize a call (a COBOL or PL/I CALL verb or the Assembler CALL macro) to specific interfaces (such as database systems) and execute the call without monitoring the interface code.

In both cases, optional routines can be coded to do the following:

  • Check the parameters before the global routine is given control
  • Display CA InterTest for CICS automatic breakpoints with error codes defined by you
Important! CA InterTest for CICS assumes that the global routine of the CALL interface always returns control to the point of the CALL. If it does not, the user-written routine is mandatory.

How Support Is Provided

To provide support, code a few lines of Assembler source code using the IN25UEX macros delivered in the CAI.CAVHMAC library. (The next section explains how to code these macros.) Then run assembly and link-edit steps to create the IN25UEXI module.

The macros create a table that, in addition to identification names and other information, contains references to the same routines that get link-edited with application programs because of CALLs issued by application programs. These references are resolved at link-edit time.

The IN25UEXI module consists of the table and the same modules that are usually link-edited with application programs. In the IN25UEXI, however, these modules are never executed. They are there only to compare a piece of their code with the code in the application load module.

CA InterTest for CICS uses the IN25UEXI module to compare the two pieces of code: the one link-edited with the IN25UEXI and the one that is about to receive control from the application program. The compared pieces of code are at the offset (from the entry point) and the length specified in the IN25UEX macros. If a large piece of code is involved, there is no need to include all of it with the IN25UEXI; include just enough to make the comparison. The comparison is made when a BALR 14,15 or BALR 14,14 instruction (for XA, BASSM or BASR instruction) is about to be executed.

If the code matches and there is no associated routine (defined in the IN25UEXI), CA InterTest for CICS drops monitoring and produces a standard CA InterTest for CICS entry in the CICS Trace Table (USER 144 code) with the identifier found in the corresponding entry in the IN25UEXI module. Monitoring resumes only upon return from the called module to the CALL statement.

If there is a user-defined routine, the routine is performed first. The routine can check the CALL's parameters and decide whether a particular interface should be given control or an automatic breakpoint should occur (if the CALL is incorrect), and whether monitoring should continue when the interface returns to the calling program.

IN25UEXI routines receive control in:

  • AMODE31
  • EXECKEY (CICS)
  • BASESPACE MODE

Code IN25UEX Macros for Called Software

The entry points are specified by using one of the following formats:

IN25UEX CALL=entry1,ROUT=routine,LENGTH=xx,DISP=xx,ID=xx

   "      "    "

   "      "    "

or

IN25UEX CALL=(entry1,......,entryn)

   "      "    "

   "      "    "

IN25UEX TYPE=FINAL                   (REQUIRED)

 place optional routines here

CALL=entry1

This required parameter specifies the name of an entry point. Specify the same name used in your COBOL or PL/I CALL statement or Assembler CALL macro, or specify an arbitrary name.

A name specified in this CALL parameter is displayed on the CA InterTest for CICS Request Breakpoint menus and on the CNTL=INQ reports.

Multiple entry point names can be specified, as shown in the second format; however, the optional parameters listed next cannot be used.

Important! Do not specify entry points used in a CALL that is the result of an EXEC CICS.

ROUT=routine

This optional parameter specifies the name of your special routine. Omit this parameter if there is no routine.

LENGTH=xx

This optional parameter specifies the length (in decimal) of the comparison. The maximum length is 64 and the default length is 16. The default is sufficient in most cases.

DISP=xx

This optional parameter specifies the offset (in decimal) from the entry point of the code to be compared. The maximum offset (displacement) is 512; the default offset is 0.

ID=xx

This optional parameter specifies the identification value for the CA InterTest for CICS entry in the CICS Trace Table. Like all such entries produced by CA InterTest for CICS, the first byte contains the character C (USER 144), field A contains the displacement, and field B contains the characters US followed by the two characters specified in this parameter. If the ID= parameter is not specified, CA InterTest for CICS generates a value.

After IN25UEXI is link-edited, verify the total size of the result as shown in the link-edit listing. There is no need to include entire interface modules in the IN25UEXI, as the comparison occurs only for the specified (or default) length at the specified (or default) offset. If the IN25UEXI module is too large, you can code little Assembler CSECTs that identically replace the ones used by applications in IN25UEXI. This technique has been used in the pregenerated version of IN25UEXI. Its source code is provided in the CAI.CAVHJCL source library in member UEXIDB2. This technique has reduced the size of IN25UEXI from approximately 30 KB to just 192 bytes.

Support Your Site's Global Routines

This section does not apply to most CA InterTest for CICS sites. It applies to global routines that are given control by the following two machine instructions:

L     14,CWALABEL

BALR  14,14

Where CWALABEL is the label of a field in the CWA that contains the address of the global routine.

The entry points are specified by using one of the following formats:

  ********** CWA USER DSECT REQUIRED HERE **********

      USING CWADS,0 CA INTERTEST REQUIREMENT    

      CWADS  DSECT          USER CWA    

      CWAFLD1    DS CL20    

      CWAENT1    DS F       USER ROUTINE    

      CWAFLD3    DS CL100   

 ************ CA INTERTEST SPECIFICATIONS ************* 

      IN25UEX CWAD=label1,ROUT=routine,ID=xx

         "      "    "

         "      "    "

      IN25UEX CWAD=labeln

      IN25UEX TYPE=FINAL                        (REQUIRED)  

      place optional routines here

     or

      IN25UEX CWAD=(label1,.....,labeln)

      IN25UEX TYPE=FINAL                            (REQUIRED)  

      place optional routines here

CWAD=cwadadr

This required parameter specifies a label that is defined in the CWA and contains the address of the entry point of a piece of commonly used code, such as a date conversion routine. For example, if the routine address is 20 bytes from the beginning of the CWA, you can code:

IN25UEX CWAD=(CWADS+20)

Multiple entry point names can be specified as in the second format; however, if specified in this manner, the optional parameters listed next cannot be used.

ROUT=routine

This optional parameter is used as in the CALL= form.

ID=xx

This optional parameter is used as in the CALL= form.

Code the ROUT= Routine

The ROUT= parameter coded in the IN25UEX macro specifies the name of a routine that is performed by CA InterTest for CICS prior to the execution of the IN25UEXI-supported CWA routine or CALL. The routines are coded in Assembler after the IN25UEX TYPE=FINAL control card. CICS commands are not allowed.

Each routine must be a CSECT whose name is specified by the ROUT= keyword. When CA InterTest for CICS passes control to the routine, the registers are set as follows:

R0 = 0

R1 = address of the BALR instruction

R2 = address of the called routine that is about to receive control by the BALR (or, for XA, by BASSM or BASR)

R3 = address of the CA InterTest for CICS work area

R4 = undetermined

R5 = undetermined

R6 = undetermined

R7 = undetermined

R8 = undetermined

R9 = address of an eight-byte field that contains the name specified in the CALL= or CWAD= parameter

R10 = undetermined

R11 = undetermined

R12 = user's TWA address

R13 = EIB address

R14 = return address for this routine

R15 = entry point address for this routine

Notes:

  • In XA or ESA systems, this routine receives control in the same AMODE (addressing mode 24 or 31) that the branch instruction had prior to its execution.
  • Registers 3 and 14 must not be changed by the routine. If these registers are used, they must be saved and restored by the routine.
  • The application program registers 0 to 15 (prior to the execution of the branch instruction) are at 96 (X'60') bytes past the address in register 3.

In addition to checking application-related parameters, the routine must determine if CA InterTest for CICS should continue monitoring. Monitoring must not continue if the code that is called by the monitored program does not return control to the next byte after the BALR instruction.

Before the routine returns to the address in register 14, it must set register 0 to one of the following values:

0

Execute the CALL without monitoring.

X'D0' X'FF'

CA InterTest for CICS should issue an automatic breakpoint with this error code.

-1

The routine does not return control to the next byte after the BALR; therefore monitoring must be dropped.

Any other negative value

CA InterTest for CICS should monitor the called piece of code.

Sample JCL for Generating IN25UEXI Programs

This example shows a call to the global routine CWAENT1, which has an associated routine called MYCHECK.

//IN25UEXI JOB (123,45),USERID,MSGCLASS=A,TIME=(,09)

//ASM      EXEC PGM=ASMA90,REGION=1024K,

//         PARM='DECK,LIST,XREF(SHORT),ALIGN'

//SYSPRINT DD  SYSOUT=A

//SYSPUNCH DD  DSN=&&LOADSET,DISP=(NEW,PASS),UNIT=SYSDA,

//            DCB=(RECFM=FB,LRECL=80,BLKSIZE=400),SPACE=(400,(100,100,1))

//SYSLIB   DD  DSN=CAI.CAVHMAC,DISP=SHR

//SYSUT1   DD  UNIT=SYSDA,SPACE=(CYL,(5,1))

//SYSUT2   DD  UNIT=SYSDA,SPACE=(CYL,(5,1))

//SYSUT3   DD  UNIT=SYSDA,SPACE=(CYL,(5,1))

//SYSIN    DD  *

********** CWA USER DSECT REQUIRED HERE **********

        USING CWADS,0   CA INTERTEST REQUIREMENT    

CWADS    DSECT      USER CWA    

CWAFLD1  DS CL20    

CWAENT1  DS F       USER ROUTINE    

CWAFLD3  DS CL100   

************ CA INTERTEST SPECIFICATIONS *************

*

*    INSERT YOUR IN25UEX STATEMENTS HERE

*

      IN25UEX CWAD=CWAENT1,ROUT=MYCHECK

      IN25UEX TYPE=FINAL

*

*    INSERT USER WRITTEN ROUTINES HERE

*

        TITLE 'ROUTINE TO CHECK CWAENT1'

MYCHECK CSECT

        USING MYCHECK,15          ESTABLISH ADDRESSABILITY

        L     4,X'60'+4(,3)       OBTAIN APPLICATION'S REGISTER 1

        LTR   4,4                 IS REGISTER 1 ZERO ?

        BZ    RETOKAY             YES, NOTHING MORE TO CHECK.

        L     4,0(,4)             PICK UP 1ST ADDR FROM PARM LIST

        LTR   4,4                 IS THE HIGH ORDER BIT ON ?

        BM    ONLYONE             YES, ONLY ONE PARAMETER.

        CLC   =C'FINAL',0(4)      1ST PARAMETER SAYS 'FINAL' ?

        BNE   NOFINAL             NO, TREAT SEPARATELY.

        LH    0,=H'-1'            YES, INDICATE 'DROP MONITORING'

        BR    14                  AND RETURN TO CA INTERTEST.

 NOFINAL CLI   0(4),C'0'           1ST CHARACTER NUMERIC ?

        BNL   RETOKAY             YES, GO CONTINUE NORMALLY.

        LH    0,=H'-2'            NO, KEEP MONITORING THE CALLED-

        BR    14                    - ROUTINE.

 ONLYONE CLI   0(4),C'X'           1ST CHARACTER EQUAL TO "X"

        BE    RETOKAY             YES, GO CONTINUE NORMALLY.

        LA    0,X'E5'             NO,DO A BREAKPOINT WITH CODE E5

        BR    14                  AND RETURN TO CA INTERTEST.

 RETOKAY SR    0,0                 INDICATE 'CONTINUE NORMALLY'

*                                 (DO NOT MONITOR THE CALL)

        BR    14                  AND RETURN TO CA INTERTEST.

        LTORG                     TERMINATES THE ROUTINE.

 *

*      CODE ANY ADDITIONAL ROUTINES HERE

*

        END                       TERMINATES THE ASSEMBLY OF IN25UEXI

/*

//LKED     EXEC PGM=IEWL,REGION=512K,PARM=(XREF,LIST,MAP)

//SYSLMOD  DD  DSN= yourlib,DISP=SHR

//SYSUT1   DD  UNIT=SYSDA,DCB=BLKSIZE=1024,SPACE=(1024,(200,200))

//SYSPRINT DD  SYSOUT=A

//SYSLIN   DD  DSN=&&LOADSET,DISP=(OLD,DELETE)

//         DD *

    ENTRY IN25UEXI  

    NAME IN25UEXI(R)    

//

The IN25UEXI module created by the previous jobstream is used by the monitor program of CA InterTest for CICS. To install this module, perform the following steps:

  1. Terminate CA InterTest for CICS (you can issue the CA InterTest for CICS checkpoint command before terminating CA InterTest for CICS).
  2. Issue a CEMT SET PROG(IN25UEXI) NEWCOPY command for the new copy.
  3. Issue a CEMT SET PROG(IN##PGM2) NEWCOPY command for the new copy.
  4. Start or restart CA InterTest for CICS.
Notes: Replace ## with your two-digit CICS release number (68 for CICS 5.1, 69 for CICS 5.2, 70 for CICS 5.3, 71 for CICS 5.4, and 72 for CICS 5.5).

IN25UEXI Instructions for Additional Vendor Products

This section lists IN25UEXI instructions for the following vendor products:

  • Calls for COMPUTATIONS users
  • Calls for SHRINK users
  • Calls for Patient Care System (PCS) users
  • Calls for HOGAN users
  • Calls for CA Gen users

Calls for COMPUTATIONS Users

To handle a call to the COMPUTATIONS package, code the IN25UEX control statement as follows:

IN25UEX CALL=MGCALL,DISP=12,LENGTH=8

In addition, add an INCLUDE MSSECALL in your link-edit step.

You should exclude the COMPUTATIONS program from monitoring. To do this, issue the CNTL=EXCL,PROG=PS* and CNTL=EXCL,PROG=PE* commands.

Calls for SHRINK Users

To handle calls to SHRINK, code the IN25UEX control statements as follows:

IN25UEX CALL=SHRINK

IN25UEX CALL=EXPAND

IN25UEX CALL=PUFFUP

IN25UEX CALL=PUFFDOWN

IN25UEX CALL=CLOSE

Where SHRINK, EXPAND, PUFFUP, PUFFDOWN, and CLOSE are the entry points.

Calls for Patient Care System (PCS) Users

To handle calls to PCS, uncomment the COPY statement provided in the IN25UEXI member in CAI.CAVHSAMP:

***         COPY PCSUEXI

Calls for HOGAN Users

To handle calls to HOGAN, add this COPY statement to the IN25UEXI member in CAI.CAVHSAMP:

COPY UEXIHOGN

Add the HOGAN.MACLIB to the ASSEMBLY step's SYSLIB.

Add the HOGAN.LOADLIB to the LKED step's SYSLIB.

Calls for CA Gen Users

To handle calls to CA Gen, add this copy statement to the IN25UEXI member in CAI.CAVHSAMP:

COPY UEXIVG

DB2 Support

DB2 Application Program Support

The installation procedure is explained next. For information on how to test and debug DB2 application programs with CA InterTest for CICS, see CICS Debugging.

Using the Pregenerated Version -- A pregenerated IN25UEXI with DB2 support is provided. If you have no other special software situations that the IN25UEXI program will handle, there are no further installation steps you have to perform for DB2 support.

Creating the IN25UEXI Module for DB2 -- To monitor application programs that issue SQL calls, a special program named IN25UEXI must exist in your CA InterTest for CICS load library. A pregenerated version of IN25UEXI, assembled for DB2 Release 10.1 and above, is provided.

You can also use the IN25UEXI program to support calls to programs that are not to be monitored by CA InterTest for CICS. If you have programs that issue calls, or require special handling, review the section Calls to Software and User Macro Support. In this case, you must combine the two uses in one IN25UEXI.

The source code for the preassembled version of IN25UEXI with DB2 support is provided in the member UEXIDB2 in the CAI.CAVHMAC library.

The following JCL example creates the IN25UEXI module for combined DB2 and special uses. Modify this example to meet your system requirements.

//IN25UEXI JOB ...

//ASM      EXEC PGM=ASMA90,REGION=1024K,

//         PARM='DECK,LIST,XREF(SHORT),ALIGN'

//SYSPRINT DD  SYSOUT=A

//SYSLIN   DD  DSN=&&LOADSET,DISP=(NEW,PASS),UNIT=SYSDA,

//           DCB=(RECFM=FB,LRECL=80,BLKSIZE=400),SPACE=(400,(100,100,1))

//SYSPUNCH DD SYSOUT=B

//SYSLIB   DD  DSN=CAI.CAVHMAC,DISP=SHR

//SYSUT1   DD  UNIT=SYSDA,SPACE=(CYL,(5,1))

//SYSUT2   DD  UNIT=SYSDA,SPACE=(CYL,(5,1))

//SYSUT3   DD  UNIT=SYSDA,SPACE=(CYL,(5,1))

//SYSIN    DD  *

      COPY UEXIIDMS      CA IDMS

      COPY UEXIDATA      CA DATACOM

      COPY UEXITELN      CA TELON

      COPY UEXISORT      CA SORT

      COPY UEXIMAST      CA MASTERPIECE

      COPY UEXIDB2       DB2

      COPY UEXICPSM      CICSPLEX SM

      COPY UEXISOKT      TCP/IP SOCKETS

*

*    INSERT YOUR IN25UEX STATEMENTS FOR SPECIAL CALLS HERE

*

      IN25UEX TYPE=FINAL

*

*    INSERT ANY USER WRITTEN ROUTINE HERE

*

      END

/*

//LKED EXEC PGM=IEWL,REGION=512K,PARM=(XREF,LIST,MAP)

*

* INSERT ANY //SYSLIB STATEMENTS FOR SPECIAL LOADLIBS HERE

*

//SYSLMOD DD DSN=yourlib,DISP=SHR

//SYSUT1 DD UNIT=SYSDA,DCB=BLKSIZE=1024,SPACE=(1024,(200,200))

//SYSPRINT DD SYSOUT=A

//SYSLIN DD DSN=&&LOADSET,DISP=(OLD,DELETE)

//       DD *

       ENTRY IN25UEXI

    NAME IN25UEXI(R)    

//

The IN25UEXI module created by the previous jobstream is used by the monitor program of CA InterTest for CICS. To install this module, you must perform the following steps:

  1. Terminate CA InterTest for CICS (you can issue the CA InterTest for CICS checkpoint command before terminating CA InterTest for CICS).
  2. Issue a CEMT SET PROG(IN25UEXI) NEW command for the new copy.
  3. Issue a CEMT SET PROG(IN##PGM2) NEW command for the new copy.
  4. Start or restart CA InterTest for CICS.
Notes: Replace ## with your two-digit CICS release number (68 for CICS 5.1, 69 for CICS 5.2, 70 for CICS 5.3, 71 for CICS 5.4, and 72 for CICS 5.5).

Monitor DB2 Applications

A pregenerated version of IN25UEXI, assembled for DB2 Releases 10.1 and above, is provided in your CA InterTest for CICS load library.

If you do not have any other special software situations that will be handled by the IN25UEXI program, you need not perform any additional installation steps for DB2 support. However, if you have programs that issue calls or require special handling, see Calls to Software and User Macro Support.

Support DB2 Calls in the FILE and CORE Facilities

The FILE facility supports dynamic SQL calls to DB2. This feature lets users view, alter, add, or delete data in DB2 tables without leaving CICS. The CORE facility lets you view the last SQL statement executed (CORE=LASTSQL).

The pregenerated versions of IN25AIDB and IN25FIDB are preassembled with DB2 Release 10.1.

Handle Wild Branches

When a monitored program passes control to another program directly by a branch instruction, bypassing the CICS services of an XCTL or a LINK macro or command, CA InterTest for CICS treats this as a wild branch (branching outside a module) and causes an automatic breakpoint. Such direct passing of control, although not advised by CICS coding standards, is used frequently in some applications.

You cannot monitor just the program receiving control by a direct branch from another program. To monitor a receiving program, you must also monitor the program passing control to it. Monitoring can begin only with the program that originally received control from CICS.

Most often, the program receives control by a direct branch caused either by a CALL statement or by a special macro. Usually, such code should not be monitored by CA InterTest for CICS. See the section Calls to Software and User Macro Support for an explanation of how to make CA InterTest for CICS drop monitoring in such cases.

Monitor a Wild Branch

If the program that receives control should be monitored and you want to debug it with CA InterTest for CICS, there are three possible situations:

  • The receiving program resides in the same load module as the program that passes control. In this situation, use the composite support facility of CA InterTest for CICS. This facility lets you debug a subprogram as if it were a separate program and supports all language combinations.
  • The receiving program resides in another load module that has a CICS program definition. In this situation, use the FOL=CICS-program-definition-name online option and, if needed, composite support. This approach makes all CA InterTest for CICS debugging features available for the branched-to program.
Note: For COBOL II dynamically called programs, the FOL= option is not needed. Simply set breakpoints in the dynamically called program as you would for any other CICS program.
  • The receiving program resides elsewhere and has no CICS program definition. In this situation, use the FOL=ON online option. In this case, breakpoints can be set for addresses, not offsets, and symbolic CA InterTest for CICS support is not available.

Use the FOL=ON Option

We strongly advise that the FOL=ON online option be applied only at the program level; that is, monitoring declared with a CNTL=ON,PROG= command as opposed to CNTL=ON,TRAN= or CNTL=ON,TERM= commands. This allows online options to be used in the most convenient way, with different options such as breakpoints declared for different programs. If necessary, the FOL=ON online option can also be specified at the terminal or transaction level.

Add COBOL File Structures to the Symbolic File

The COBOL  program shown next is an example of a dummy default program that contains 01 level structures. Saving all of the 01 level structures used at a site in one file allows users of the FILE transaction to omit the symbolic program name when requesting records or DL/I segments in structured format. Symbolic information for the default program must be saved in the symbolic file, and its name must be referenced in the FSYMP installation option. The default name is PROTFILE.

//PROTFILE JOB (NTSM,473),'JOHN BROWN',CLASS=D,MSGCLASS=A 

//* 

//COB      EXEC PGM=IGYCRCTL,REGION=1024K, 

//   PARM='OBJECT,APOST,FLAG(I,W),LIST,XREF,MAP,NOOPT,VBREF' 

//STEPLIB  DD DSN=SYS1.COB2COMP,DISP=SHR 

//SYSLIB   DD DSN=CICS.COBLIB,DISP=SHR 

//SYSLIN   DD DSN=&&LOADSET,DISP=(MOD,PASS), 

//           UNIT=SYSDA,SPACE=(80,(250,100)) 

//SYSUT1   DD UNIT=SYSDA,SPACE=(460,(350,100)) 

//SYSUT2   DD UNIT=SYSDA,SPACE=(460,(350,100)) 

//SYSUT3   DD UNIT=SYSDA,SPACE=(460,(350,100)) 

//SYSUT4   DD UNIT=SYSDA,SPACE=(460,(350,100)) 

//SYSUT5   DD UNIT=SYSDA,SPACE=(460,(350,100)) 

//SYSUT6   DD UNIT=SYSDA,SPACE=(460,(350,100)) 

//SYSUT7   DD UNIT=SYSDA,SPACE=(460,(350,100)) 

//SYSPRINT DD DSN=&&TEMPIN,DISP=(,PASS),UNIT=SYSDA,SPACE=(TRK,(15,5)), 

//        DCB=(DSORG=PS,LRECL=133,BLKSIZE=1330,RECFM=FBA) 

//SYSIN    DD * 

       ID DIVISION.

       PROGRAM-ID. PROTFILE.

       ENVIRONMENT DIVISION.

       DATA DIVISION.

       WORKING-STORAGE SECTION.

       77  PROGRAM-NAME       PIC X(8) VALUE 'PROTFILE'. 


       LINKAGE SECTION. 


      **  CAR SEGMENT  ** 

       01  CAR.

           05  CAR-SEGMENT-KEY-FIELD.

               15  CAR-SEGMENT-MAKE    PIC X(12).

           05  CAR-SEGMENT-MODEL       PIC X(12).

           05  CAR-SEGMENT-TYPE        PIC X(10).

           05  CAR-SEGMENT-WEIGHT      PIC S9(5)      COMP-3.

           05  CAR-SEGMENT-CYLINDRS    PIC S9(3)      COMP-3.

      **  DEALER SEGMENT  ** 

       01  DEALER.

           05  CAR-DEALER-SEGMENT-KEY.

               15  CAR-DEALER-SHORT-NAME PIC X(9).

               15  CAR-DEALER-TIEB     PIC S999       COMP-3.

               15  CAR-DEALER-NBRWD    PIC S9         COMP-3.

           05  CAR-DEALER-FIRST-NAME   PIC X(24). 


       PROCEDURE DIVISION.

           MOVE 'PROTFILE' TO PROGRAM-NAME.

           GOBACK. 

//* 

//SYMSTEP  EXEC PGM=IN25COB2,REGION=1024K 

//STEPLIB  DD DSN=CAI.CAVHLOAD,DISP=SHR 

//INPUT    DD DSN=&&TEMPIN,DISP=(OLD,DELETE) 

//OUTPUT   DD SYSOUT=A,DCB=(RECFM=FBA,LRECL=133,BLKSIZE=1330) 

//MESSAGE  DD SYSOUT=A 

//PROTSYM  DD DSN=** your protsym file **,DISP=SHR 

//CARDS    DD * 

PROTFILE,LISTER=ALL,NOPURGE 

//*

In the STEPLIB DD statement on the symstep specify the name of the library that contains the Testing and Fault Management Symbolic component.

Note: A similar job can be used for COBOL/VS.

Declare User-Defined CORE Commands

This section explains how to define your own CORE keywords. User-defined CORE keywords provide a shorthand method for entering a complex CORE command by specifying a simple command that contains one or more of your own keywords. The new keyword is automatically replaced with a string of command elements that could otherwise be difficult to remember.

Among the new commands can be some to display your own areas in main storage, such as crucial control tables for running an application system. If your replacement command includes the USE= element, the storage areas can be displayed as COBOL or Assembler structures, with names and offsets attached to each data field.

For details, see the CA InterTest for CICS Help facility. Select the CORE Facility, then Structured Data Displays, and then Additional Features.

CORUCOM Macro

The CORUCOM macro lets you define any number of new CORE command keywords, each an abbreviation for a series of CORE command elements. For instance, there is a user table that is pointed to by an address located eight bytes into the CWA. There is a counter 12 bytes into this table that contains the number of times a service request transaction was issued. Add the following CORUCOM entry and assemble the CORUCOM table:

CORUCOM CODE=SERVCNT,COMND=CWA@8+C

To display the service request count online, issue:

CORE=SERVCNT

Code one CORUCOM macro for each new CORE keyword. Submit the resulting source code to assemble a new CA InterTest for CICS load module named IN25UCOM. The module is used by the CORE facility as a table to convert your own keywords into strings of CORE keywords.

Since the CORUCOM macro generates a separate CICS load module, you can add new or modified commands at any time. To do this, code the commands, assemble the module, and then do a NEWCOPY for the load module IN25UCOM by issuing:

CEMT SET PROG(IN25UCOM) NEWCOPY

Code the CORUCOM Macros

The CORUCOM macro is delivered in the CAI.CAVHMAC library. The first CORUCOM statement must be coded as follows:

1 1

     COL= 1...5....0....5

                   CORUCOM TYPE=INITIAL

The last CORUCOM statement must be coded as follows:

              1    1

     COL= 1...5....0....5

                   CORUCOM TYPE=FINAL

Each user-defined CORUCOM statement specifies one user-defined element of the CORE command and one string of CORE commands that will replace that user-defined element.

The user-defined element is specified by the CODE= keyword. Each element keyword must be less than eight characters long, must consist only of alphanumeric characters and, to prevent confusion with a hexadecimal number, must contain at least one of these characters: GHIJKLMNOPQRSTUVWXYZ. When two or more keywords have the same prefix (for example, ICE2, ICE), the longer keyword must be specified first, as illustrated in the following example.

The string of CORE command elements is specified by the COMND= keyword. The string must be enclosed in apostrophes and, within the string, any apostrophe must be coded as two apostrophes. All elements of the CORE command are permitted, including other user-defined elements. In the following example:

  • The new keyword ICE2 (second macro) uses another new keyword ICE (in the third macro). Notice that the longer keyword is specified first.
  • The fourth macro defines the keyword MYTABLE, which displays a storage area pointed to by the address in the CWA, and produces a display formatted as a structure named MYTABLE in the CA InterTest for CICS symbolic file records identified by the name MYSYMDEF. For more details, see the section Adding Assembler DSECTs to the symbolic file.
  • The * in column 72 means continuation.

1 1 7

 COL= 1...5....0.....6............................................2

               CORUCOM TYPE=INITIAL   (required)

               CORUCOM CODE=ICE2,COMND='ICE@4'

               CORUCOM CODE=ICE,COMND='=CSA@54'

               CORUCOM CODE=MYTABLE,COMND='=CWA@8,USE=MYSYMDEF.MYT*

                     ABLE'

               CORUCOM TYPE=FINAL     (required)

Sample JCL for Assembling IN25UCOM

The following IN25UCOM JCL example uses the standard IBM procedure to assemble and link-edit macro level programs.

//UCOM JOB ...

//*  (COMMENT: A STANDARD IBM PROC FOR ASSEMBLER MACRO LEVEL)

//STEP  EXEC ASMFCL

//ASM.SYSLIB DD DSN=CAI.CAVHMAC,DISP=SHR

//ASM.SYSIN  DD *

      CORUCOM TYPE=INITIAL

*     YOUR FIRST CORUCOM STATEMENT GOES HERE

         ..   .....

      CORUCOM TYPE=FINAL

      END

/*

//LKED.SYSLMOD DD DSN=CAI.CAVHLOAD,DISP=SHR

//LKED.SYSIN DD *

       NAME IN25UCOM(R)

 /*

//

Note: The IN25UCOM member of the CA InterTest for CICS source library contains sample source for assembling the IN25UCOM load module.

Sample JCL for Defining CORE Keywords

After you have added the necessary members to the symbolic file, run a job to define the commands needed to access your DSECTs. The sample job below uses CORUCOM macros to define the user CORE keyword TWAF. For more information, see Declare User-Defined CORE Commands.

//UCOM JOB ...

//*  (COMMENT: A STANDARD IBM PROC FOR ASSEMBLER MACRO LEVEL)

//STEP  EXEC ASMFCL

//ASM.SYSLIB   DD  DSN=CAI.CAVHMAC,DISP=SHR

//ASM.SYSIN  DD  *

        COPY CORUCOM

        CORUCOM TYPE=INITIAL

        CORUCOM CODE=TWAF,COMND='TWA,USE=USERDSEC.USERTWAF'

        CORUCOM TYPE=FINAL

        END

/*

//LKED.SYSLMOD     DD DSN=CAI.CAVHLOAD,DISP=SHR

//LKED.SYSIN       DD  *

        NAME IN25UCOM(R)

 /*

//

Special Considerations for HOGAN Systems

CA InterTest for CICS features are available for debugging HOGAN applications, including symbolic support if the CA InterTest for CICS post-compile step was executed.

Use Considerations

Monitoring the PEM Module -- The PEM module does not need to be debugged and should not be monitored by CA InterTest for CICS. Monitor only your HOGAN application programs using the segmented monitoring option, as discussed next.

Monitoring Application Programs that use HOGAN -- Application programs that use HOGAN should be monitored only by using the CA InterTest for CICS segmented monitoring options. Do not monitor such programs by transaction or terminal name, or by global monitoring. CICS Debugging explains how to use segmented monitoring.

The USH=ON monitoring option must also be used to prevent unnecessary automatic breakpoints from occurring.

All of the CA InterTest for CICS online options are available. However, the FOL= option should not be used. It is advisable to learn how to use the BYP= option and the PF11 override option.

Installation Procedure

To install CA InterTest for CICS for HOGAN, first complete all of the required steps given in Configure Your Product with CA CSM and Installing Your Product Using Pax ESD or DVD. Then complete your installation by performing the following steps.

  1. Create the IN25UEXI module for HOGAN. Instructions are given in the section IN25UEXI Instructions for Additional Vendor Products.

    Note: This routine is customized for each release of HOGAN. To ensure compatibility, please contact CA Support.

  2. Enable the CA InterTest for CICS segmented monitoring options. To do this, you must set the MONOM installation option in the IN25OPTS module to either MENU or NOMENU. Optionally, you can enable password security for segmented monitoring by setting the MONOMSEC installation option to YES.

This completes the installation for HOGAN in a CTS environment.

IBM's EXEC Debugging Facility (EDF) Support

The EDF facility, which is activated by the CEDF transaction and described in the IBM CICS/VS Application Programmer's Guide Command Level, does not interfere with the CA InterTest for CICS monitoring and interactive testing. CA InterTest for CICS also does not interfere with EDF, except when EDF presents the EDF breakpoint display of the program that is being monitored by CA InterTest for CICS, EDF incorrectly indicates the location of the command since commands are issued by CA InterTest for CICS, not by the program.

Advantages of CA InterTest for CICS over EDF

CA InterTest for CICS offers many advantages over the EDF facility, including the following advantages:

  • The ability to set breakpoints anywhere in the program (not just at EXEC CICS commands).
  • Data display and modification by symbolic names. This means the programmer does not need the most recent listing of the tested program, if the data names or paragraph names (labels in Assembler) remain the same.
  • Monitoring, such as the ability to detect any illegal action of the program between CICS commands. CICS abends are intercepted by EDF, but damage may have occurred on the way to the abend and EDF may not give any specifics on the problem.
  • The ability to declare an unconditional or conditional breakpoint at a specific location -- the EXEC CICS call at the point when the EXEC CICS call parameters have already been formatted. At that time you can change the parameters (for example, by issuing the CORE=ARGnn command) before you let the command execute.
  • The ability to set request breakpoints for a particular type of CICS command regardless of where in the program it occurs, for all EXEC CICS commands, or for all except some EXEC CICS commands. For example, with one specification you can set breakpoints at all File Control commands or at all READ or WRITE commands.

Use CA InterTest for CICS with EDF

If you want to use CA InterTest for CICS with EDF, you can turn on EDF before you begin monitoring a program with CA InterTest for CICS. Moreover, when a monitored program is stopped at a request breakpoint for an EXEC CICS command, you can activate EDF by entering any character in the field marked EDF in the lower-right corner of the Detailed Breakpoint display.

When CA InterTest for CICS and EDF are being used on the same task, be aware of the following:

  • If a CA InterTest for CICS breakpoint is set at an EXEC CICS command, the CA InterTest for CICS breakpoint occurs before the command is passed to CICS.
  • At the breakpoint, the programmer can review and change any parameters of the command before telling CA InterTest for CICS to continue with the task.
  • CA InterTest for CICS checks the parameters and, if necessary, halts the task at an automatic breakpoint.
  • If that does not happen, the command is passed by CA InterTest for CICS to CICS for execution; that is, to the EXEC interface.
  • Subsequently, EDF presents the EDF breakpoint display of the program that is being monitored by CA InterTest for CICS, before a command breakpoint. The EDF facility, however, is in control at that time and any changes by the user during the EDF breakpoint cannot be checked by CA InterTest for CICS.
  • Only after the command is executed and a command EDF breakpoint display appears and EDF is told to continue with the task can CA InterTest for CICS resume control and continue monitoring.

Special Considerations for MRO Support

To use CA InterTest for CICS in an MRO environment, you must have the following items:

  • All CA InterTest for CICS required CICS definitions in any CICS application-owning region (AOR) that will use CA InterTest for CICS for testing.
  • A local program definition for IN25VIRC in the terminal-owning region (TOR).
  • A local transaction definition for VIRC in the TOR; this transaction ID must be identical in the TOR and all AORs.
  • One remote transaction definition for VTAT in the TOR for each AOR that will use CA InterTest for CICS. Of course, the TOR's local VTAT transaction IDs must be unique (for example, VTA1, VTA2, VTA3, and so on). However, the remote transaction IDs can be the same for all AORs (for example, VTAT), so you do not need to maintain a unique IN25OPTS for each AOR. If you choose to specify an alternate VTAT transaction ID in one or more AORs, you must be sure to specify the same alternate transaction ID in the TOR's remote VTAT transaction definition.

In addition, for all CICS regions that will use CA InterTest for CICS -- both AOR and TOR -- the transaction definition for VIRC must specify the same transaction code.

A sample set of definitions is supplied in member CSDINTTO in CAI.CAVHJCL library. This sample set contains all of the RDO definitions required for the CICS TOR region. All CA InterTest for CICS transaction names are the same as those specified in the AOR and can be modified by your site.

Note: We recommend that the CA InterTest for CICS CORE transaction be installed in the TOR as local to help system support staff resolve problems in that region.

Remote transaction definitions can be defined for all transactions except VIRC, which can be started from the TOR to run in the AOR. Using these transaction definitions is usually preferable to starting routing sessions with the CRTE SYSID= transaction.

You can add a transaction definition in each TOR.

DEFINE  TRANSACTION(LNTL)

Where LNTL -- is a four-character transaction name for the CA InterTest for CICS CNTL transaction in the TOR:

REMOTENAME(RNTL)

Where RNTL -- is a four-character transaction name for the CA InterTest for CICS CNTL transaction in the AOR:

REMOTESYSTEM(TROW)

Where TROW -- the name under which the AOR is known to the TOR.

Note: RNTL and LNTL can be the same name.

Monitor Considerations for DFLTUSER

CA InterTest for CICS qualifies all monitoring entries with a CICS user ID. All monitoring entries use the form:

promid.userid

The ATTACHSEC option of the CONNECTION entry in the CSD is used with the DFLTUSER= option setting in IN25OPTS to provide the granularity of monitoring required. Only the combinations of DFLTUSER and ATTACHSEC given in the following table are supported:

IN25OPTS
DFLTUSER=
CSD CONNECTION, ATTACHSEC= Typical Use Additional Consideration
ANY LOCAL Nonsecure MRO environment AOR and TOR need the same default CICS user ID (set in the SIT)
SPECIFIC IDENTIFY Secure MRO environment TOR's SIT uses SEC=YES or MIGRATE option

The following sections discuss each combination in detail.

Monitor in a Nonsecure MRO Environment

The following combination says that monitoring and monitoring options should be set by terminal ID and not by CICS user ID.

DFLTUSER=.ANY

ATTACHSEC=LOCAL

This setting is typically used in a nonsecure MRO environment where the TOR's SIT uses the SEC=NO option. The user ID passed from the TOR is the TOR's default user ID as set in the SIT (typically CICSUSER).

CA InterTest for CICS compares this user ID to the AOR's default user ID and, if they match, sets the user ID to be monitored by .ANY user. This entry causes all users of the program to be monitored (as in earlier CA InterTest for CICS releases).

Important! Should the default user IDs of the AOR and TOR not match, the results are unpredictable. Therefore, you should check that the default user IDs in the AOR and TOR are the same.

Monitor in a Secure MRO Environment

The following combination is allowed in a secure MRO environment where the TOR's SIT uses the SEC=YES or MIGRATE option.

DFLTUSER=SPECIFIC

ATTACHSEC=IDENTIFY

In this case, the application's unique user ID is passed from the TOR to the AOR only if the ATTACHSEC option of the CONNECTION entry is IDENTIFY. This requirement and specifying DFLTUSER=SPECIFIC in IN25OPTS allows CA InterTest for CICS to assign the user ID to each monitoring command as a default. This saves the user from having to type it in or specify it, and allows CA InterTest for CICS to properly monitor user activity in the TOR.

Additional Monitoring Considerations

The CRT terminal that is to receive the CA InterTest for CICS breakpoint display is called the receiving terminal. After receiving the display, the terminal remains ready to execute any CA InterTest for CICS command. However, until the user disconnects from CA InterTest for CICS, it will accept only CA InterTest for CICS commands.

The receiving terminal must meet these specifications:

  • IBM 3270-type CRT or compatible:
    • The terminal must have ATI (automatic task initiation) capability.
    • If its screen is larger than model 2, its default screen size (as defined in the TCT) must be 24 lines x 80 characters (the model 2 size)
  • For two-terminal testing:
    • The receiving terminal must be logged on to the TOR at the time the breakpoint is about to be displayed.
    • At the time the first breakpoint display is about to appear, the receiving terminal must not be occupied by any task (transaction). This restriction also applies to CRTE.
    • The next transaction ID must not be primed in the TCTTE of the receiving terminal. If this occurs, CA InterTest for CICS cannot write the breakpoint screen because CICS prevents automatic task initiation.
    • The receiving terminal must not be occupied by an explicit routing session. (Explicit routing sessions are started by entering CRTE SYSID= and are normally ended by entering Cancel.) When necessary, the receiving terminal will have a routing session started for it by CA InterTest for CICS so the terminal can receive a breakpoint display.
    • The terminal from which the tested transaction is entered or the terminal that the tested transaction owns is called the sending terminal. Since a user typically sets breakpoints without naming the receiving or sending terminal, the receiving and sending terminal will be the terminal from which the CNTL command was entered when the user ID monitoring option=.ANY.
    • If the sending terminal is not the same as the receiving terminal, the sending terminal will be unavailable and tied to the tested transaction during the breakpoint. This restriction does not apply if the receiving terminal is the same as the sending one because the user can disconnect from CA InterTest for CICS.

Remote FILE Support

All CICS regions participating in a remote FILE transaction session must be at CA InterTest for CICS Version 4.2 or above. Also, the FILE transaction and its associated program entry IN25FLE must be defined to the file-owning region. The transaction name assigned to the FILE transaction must be the same in all regions.

CA SymDump for CICS

Install or Customize DFHPEP

If your site does not have a custom DFHPEP module implemented, then the DFHPEP included in the CAI.CAVHLOAD library must be installed in a library concatenated before the IBM CICS library suffixed with SDFHLOAD, so that it replaces the IBM supplied dummy version of DFHPEP.

If your site already uses a customized DFHPEP it should be customized and relinked to include the following source statement:

EXEC CICS LINK PROGRAM('IN25PEP')

Using the supplied copy of DFHPEP or customizing your own DFHPEP to link to IN25PEP is not a hard requirement for installation of CA SymDump for CICS. The dump capture still functions without DFHPEP/IN25PEP processing. However the failure to configure DFHPEP as suggested previously prevents capture of the last screen display in an MRO environment.

Performance Considerations

  • CICS Virtual Storage
    The CICS virtual storage requirement of the dump-writing part of CA SymDump for CICS is 20 KB for the permanent resident program IN25COLD. The CPU and I/O resources used by CA SymDump for CICS to produce a dump will, in many cases, be less than those required by a standard dump and are unlikely to exceed those required by a standard dump.The CICS virtual storage required to view a dump online is equal to the storage the dumping task originally required (including program storage for the program active at dump time). To this, add the size of the CSA, CWA, TCTTE, TUA, and the formatted trace table of the dumping task.

    Important! The formatted trace table is built only when the user explicitly asks to see it.

    Because the CA SymDump for CICS task is conversational, these CICS areas are held while a particular dump is analyzed. When the next dump is selected, these areas are freed. Most virtual storage requests, including the trace table, are moved above the 16-megabyte line, easing the virtual storage constraint.

  • CICS Internal Trace Table
    CA SymDump for CICS dump capture and analysis relies on the availability of the CICS internal trace table for many of its diagnostic functions. A trace table of 512 KB is usually large enough to hold a typical task's processing flow. You can increase or decrease the trace table size as required by your applications. Failure to activate the internal trace will result in a loss of product functionality.
    EDSA utilization increases approximately 600 KB for each concurrent CA SymDump for CICS user. If capturing the CICS Internal Trace Table using the SYMT transaction, increase the EDSA size approximately two times the size of the CICS Internal Trace Table for each concurrent user of the SYMT transaction. Adjust your SIT EDSA specification accordingly.
  • PROTDMP File
    PROTDMP files that were initialized using a release of CA SymDump for CICS after r8.0 are compatible with this release.
    A CA SymDump viewing region using the SYMD transaction to view dumps must be the same CICS release as the captured dumps that are being viewed. In this case we recommend that you have a separate PROTDMP for each release of CICS to minimize confusion. Clients who use the GUI to view dumps do not have this limitation, and are free to share a single PROTDMP file to contain any version of CICS dumps.
  • Trace Formatting Region
    The TRACE FORMAT REGION requires a maximum DASD workspace of approximately 40 KB for every 4 KB block of raw unformatted CICS trace as specified in the TRCFMEGT IN25OPTS parameter. This storage is dynamically obtained and released during the format process in a serial fashion for each CA SymDump for CICS, CICS trace that is selected, for example, only one format subtask has this DASD workspace at a time. Once a trace is formatted, the DASD workspace is released before the trace actually being displayed to the user. The next trace format request will re-obtain the needed DASD workspace. For parameters controlling where to get this dynamic DASD allocation, refer to your IN25OPTS definition.
    The TRACE FORMAT REGION also requires 50 KB of extended private area main storage for every 4 KB block of raw unformatted CICS trace that is being formatted. This is where the formatted trace is stored once formatted by DFHTUXX0 for review and filtering by the user. This is a cumulative amount for every trace that is simultaneously being formatted and reviewed. It is obtained during the format request, and is released once the user completely leaves the CA SymDump for CICS selection screen on the CICS region that the dump was selected from.
    For a transaction dump, CA SymDump for CICS captures up to 180 4 KB blocks of raw trace data. If the maximum 180 blocks were captured and the trace was selected for formatting by three users simultaneously, the TRACE FORMAT REGION would in a serial fashion obtain and release approximately 7 MB of DASD workspace, and also get 27 MB of total extended private area, that is, 9 MB per trace.
    If one of the users exits the trace, then the TRACE FORMAT REGION would be using 18 MB of extended private area for the two remaining traces. Since the traces have already been formatted by DFHTUXX0, and now reside in the extended private area of the TRACE FORMAT REGION, there is no DASD workspace being used until a new format request is received.
    The new CA SymDump for CICS TRACE FORMAT REGION allows trace formatting to be offloaded from the CICS region that the trace format request originates from. This results in improved performance within the CICS region, as the actual formatting of the CICS trace is performed by DFHTUXX0 in the TRACE FORMAT REGION. The response times for trace formatting are dependent on the size of the traces, the number of simultaneous requests being performed by a TRACE FORMAT REGION, the amount of machine resource you make available to the TRACE FORMAT REGION. Careful review of your IN25OPTS parameters that control trace formatting insures optimal performance.
    You are not limited to having one TRACE FORMAT REGION in your shop. By having a different TRCFFMID parameter specification in your IN25OPTS definition, you can have different TRACE FORMAT REGIONS each with different performance characteristics. For example, you may want to have a separate TRACE FORMAT REGION with much larger thread allocation sizes (TRCFMEGT) with only a few threads (TRCFTHRD) that you would make available to your users that want to view large traces captured with the SYMT trace capture facility.
    CA SymDump for CICS uses the CICS INTERNAL TRACE TABLE as its source for capturing trace information. A rule of thumb for the number of trace entries for a 4 KB trace block in the CICS internal trace table is 40. This may vary significantly with the application or system activity being traced at the client site.
    With regard to the TRCFMEGM (TRACE TOTAL MEGS, MAX IS 2000) and TRCFMEGT (TRACE THREAD MEGS MIN IS 9) settings each MB of storage set aside by these parameters support or 'back' approximately 20 raw 4 KB trace blocks.
    CA SymDump for CICS currently captures up to 180 4 KB trace blocks for a transaction dump, and will capture the entire CICS internal trace table for an SYMT dump. The minimum recommended thread storage limit is therefore estimated to be 9 MB, and the theoretical max thread limit for a 2 GB max storage specification is 222.
    Based on these guidelines, a general approximation for the SYMT internal trace capture is TRCFMEGT=((TRTABSZ/4)/20). The rule for the TRCFMEGM is also an approximation, as you cannot assume that all threads will always use maximum storage allocations. For a FORMAT REGION that would only handle SYMT traces, multiply threads * TRCFMEGT to get TRCFMEGM.
    Large traces, such as those captured by SYMT will significantly affect the performance of an individual TRACE FORMAT REGION.The new CA SymDump for CICS TRACE FORMAT REGION uses the IBM DFHTUXX0 (where XX corresponds to your release of CICS) module that is provided with the base CICS product. If IBM makes changes to this module due to routine maintenance, you will need to recycle your TRACE FORMAT REGION to pick up these changes. To recycle the TRACE FORMAT REGION, you would issue a cancel or purge on the address space and then restart it.

Language Environment (LE) Considerations

If your application is executing under IBM's Language Environment (LE), region level run-time options could prevent the application from intercepting some problems. One option is TERMTHDACT, which controls what happens when an error condition occurs and can prevent control from returning to InterTest.

For example, you could see the message ‘IGZ0063S An invalid sign was detected in a numeric edited sending field’ in your CEE message log, but the application does not stop at that instruction. The cause of the message might be that the value of TERMTHACT is set to TRACE, which would not produce an abend and return control to InterTest. Change the value to UADUMP to allow storage to be dumped and InterTest can get control and stop at the invalid instruction.

The CLER transaction in CICS can be used to dynamically change options while the region is running. Any changes made with CLER will be reset when the region is recycled. If you want to permanently change a run-time option but do not want to globally change the LE options at your site, assemble the CEEROPT CSECT and link it into a library. Place it into the RPL to override the options for a single CICS region. The input into the assembly step would look as follows:

Example:

CEEROPT CSECT 
CEEROPT AMODE ANY
CEEROPT RMODE ANY
CEEXOPT TERMTHDACT=((UADUMP,CESE,96),OVR)
END
Was this helpful?

Please log in to post comments.