CICS Interfaces and Compatibility

This article contains interface and compatibility considerations for CA InterTest for CICS and CA SymDump for CICS.
caitsd-11-0
This article contains interface and compatibility considerations for CA InterTest for CICS and CA SymDump for CICS.
2
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, CSDDB270, CSDDB271, and CSDDB272 members on CAI.CAVHJCL provide RDO entries.
  2. Bind the DBRM members (INB0FIDB and INB0AIDB) provided in the CAI.CAVHDBRM into an InterTest DB2 plan (the recommended name is INB0PLAN).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 INB0AIDB provided on the CAI.CAVHDBRM into the DB2 plan (the recommended name is INB0PLAN).
  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
  • 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
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
INT11068
SYM11068
CTS 5.2
INT11069
SYM11069
CTS 5.3
INT11070
SYM11070
CTS 5.4
INT11071
SYM11071
CTS 5.5
INT11072
SYM11072
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 USERTWAFUSERDSEC 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.
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=tablnameCNTL=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) //
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=NORECNTNW=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.
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
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.
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
  • 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.
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=SHRINKIN25UEX CALL=EXPANDIN25UEX CALL=PUFFUPIN25UEX CALL=PUFFDOWNIN25UEX 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 //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 * 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 TERMINATES THE ASSEMBLY OF IN25UEXI /* //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.
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.
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.
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.
117 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) /* //
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 support, 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.
    This routine is customized for each release of HOGAN. To ensure compatibility, please contact
    Broadcom 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 support 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.
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.
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:
IN25OPTSDFLTUSER=
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=.ANYATTACHSEC=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).
Ensure 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=SPECIFICATTACHSEC=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.
    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.
    We recommend that you have a single PROTDMP file for each CICS region because sharing files across regions is not yet supported. 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 DFHTU
    XX
    0 (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