InterTest™ and SymDump ® 11.0
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 InterTest for CICS tables.
The second positional parameter of the PROMMAC macro must contain END. THis parameter 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 *


//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, the input sequential file can contain CNTL commands.
These commands are executed in sequence as if they were entered manually from a terminal. Responses to these
commands are written in the terminal 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.
 252


InterTest™ and SymDump ® 11.0
3.Set the following 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
To assign the entries to a specific user ID, you can add the USR= option to any embedded CNTL=ON
commands . 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 InterTest for CICS) that is invoked by
CALLs from your application programs or your own macros. For example:
•To support global routines with addresses 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 InterTest for
CICS until they return to the next byte after the BALR in the calling program.
•To make 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 InterTest for CICS automatic breakpoints with error codes defined by you
WARNING
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


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 only exist to compare a piece of their code with the
code in the application load module.
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), InterTest for CICS drops monitoring and
produces a standard 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.
 253


InterTest™ and SymDump ® 11.0
If there is a user-defined routine, the routine is performed first. The routine can check the CALL 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 InterTest for CICS Request Breakpoint menus and on the
CNTL=INQ reports.
As shown in the second format, multiple entry point names can be specified, however the optional parameters that are
listed next cannot be used.
WARNING
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. If there is no routine, omit this parameter.
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 usually sufficient.
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 InterTest for CICS entry in the CICS Trace Table. Like
all such entries produced by InterTest for CICS, the first byte contains the character C (USER 144), field A contains the
 254


InterTest™ and SymDump ® 11.0
displacement, and field B contains the characters US followed by the two characters specified in this parameter. If the ID=
parameter is not specified, 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 Global Routines
This section does not apply to most InterTest for CICS sites. This section 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.
To specify entry points, use 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 *************


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.
 255


InterTest™ and SymDump ® 11.0
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 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 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 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
NOTE
•In XA or ESA systems, this routine receives control in the same AMODE (Addressing mode 24 or 31) that the
branch instruction had before 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.


restored by the routine.
•The application program registers 0 to 15 (Before the branch instruction execution) are at 96 (X'60') bytes
past the address in register 3.
In addition to checking application-related parameters, the routine must determine if 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.
 256


InterTest™ and SymDump ® 11.0
X'D0' X'FF'
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
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


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.
 257


InterTest™ and SymDump ® 11.0
 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)
//


ENTRY IN25UEXI
    NAME IN25UEXI(R)
//
The IN25UEXI module created by the previous jobstream is used by the monitor program of InterTest for CICS. To install
this module, perform the following steps:
1.Terminate InterTest for CICS (You can issue the InterTest for CICS checkpoint command before you teminiate
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 InterTest for CICS.
NOTE
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
•72 for CICS 5.5
•73 for CICS 5.6
•74 for CICS 6.1
IN25UEXI Instructions for other Vendor Products
This section lists IN25UEXI instructions for the following vendor products:
 258


InterTest™ and SymDump ® 11.0
•Calls for COMPUTATIONS users
•Calls for SHRINK users
•Calls for Patient Care System (PCS) users
•Calls for HOGAN users
•Calls for InterTest 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
Also 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 SYSLIB of the LKED step.
Calls for InterTest Users


Calls for InterTest Users
To handle calls to InterTest, 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
InterTest for CICS, see CICS Debugging  .
 259


InterTest™ and SymDump ® 11.0
Using the Pregenerated Version -- A pregenerated IN25UEXI with DB2 support is provided. If you have no other special
software situations that the IN25UEXI program handles, there are no further installation steps 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 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 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
 260


InterTest™ and SymDump ® 11.0
    NAME IN25UEXI(R)
//
The IN25UEXI module created by the previous jobstream is used by the monitor program of InterTest for CICS. To install
this module, you must perform the following steps:
1.Terminate InterTest for CICS (you can issue the InterTest for CICS checkpoint command before terminating 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 InterTest for CICS.
NOTE
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
•72 for CICS 5.5
•73 for CICS 5.6
•74 for CICS 6.1
Monitor DB2 Applications
A pregenerated version of IN25UEXI, assembled for DB2 Releases 10.1 and above, is provided in your InterTest for CICS
load library.
If you do not have other special software situations to be handled by the IN25UEXI program, you do not need to perform
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, 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 InterTest for CICS. See the section Calls to Software and User Macro
Support  for an explanation of how to make InterTest for CICS drop monitoring in such cases.
 261


InterTest™ and SymDump ® 11.0
Monitor a Wild Branch
If the program that receives control should be monitored and you want to debug it with 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 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
InterTest for CICS debugging features available for the branched-to program.
NOTE
For COBOL II dynamically called programs, the FOL= option is not needed. 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 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


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.
 262


InterTest™ and SymDump ® 11.0
       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)


//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 InterTest for CICS Help facility. Select the CORE Facility, then Structured Data Displays, and then
Additional Features.
 263


InterTest™ and SymDump ® 11.0
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 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:
CORUCOM TYPE=INITIAL
The last CORUCOM statement must be coded as follows:
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 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*
 264


InterTest™ and SymDump ® 11.0
                     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 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


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
InterTest for CICS features are available for debugging HOGAN applications, including symbolic support if the InterTest for
CICS post-compile step was executed.
 265


InterTest™ and SymDump ® 11.0
Use Considerations
Monitoring the PEM Module  -- The PEM module does not need to be debugged and should not be monitored by
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 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 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 InterTest for CICS for HOGAN support, first complete all of the required steps given in Configure Your Product
with 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 Broadcom
Support .
2.Enable the 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


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 InterTest for CICS monitoring and interactive testing. 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 InterTest for CICS, EDF incorrectly indicates the location of the command since commands are issued by
InterTest for CICS, not by the program.
Advantages of InterTest for CICS over EDF
InterTest for CICS offers many advantages over the EDF facility, including the following advantages:
 266


InterTest™ and SymDump ® 11.0
•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 InterTest for CICS with EDF
If you want to use InterTest for CICS with EDF, you can turn on EDF before you begin monitoring a program with 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 InterTest for CICS and EDF are being used on the same task, be aware of the following:


•If an InterTest for CICS breakpoint is set at an EXEC CICS command, the 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 InterTest for
CICS to continue with the task.
•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 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 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 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 InterTest for CICS resume control and continue monitoring.
Special Considerations for MRO Support
To use InterTest for CICS in an MRO environment, you must have the following items:
•All InterTest for CICS required CICS definitions in any CICS application-owning region (AOR) that will use 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 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 InterTest for CICS -- both AOR and TOR -- the transaction definition for VIRC
must specify the same transaction code.
 267


InterTest™ and SymDump ® 11.0
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 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 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 InterTest for CICS CNTL transaction in the TOR:
REMOTENAME(RNTL)
Where RNTL -- is a four-character transaction name for the 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
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,


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
his 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).
 268


InterTest™ and SymDump ® 11.0
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 InterTest for CICS releases).
WARNING
Ensure that the default user IDs in the AOR and TOR are the same.
Monitor in a Secure MRO Environment
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 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 InterTest for CICS to properly monitor user activity in the TOR.
Additional Monitoring Considerations
The CRT terminal that is to receive the InterTest for CICS breakpoint display is called the receiving terminal. After
receiving the display, the terminal remains ready to execute any InterTest for CICS command. However, until the user
disconnects from InterTest for CICS, it will accept only 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, 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, InterTest for CICS starts a
routing session for the receiving terminal to allow the terminal to 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 is 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 is 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  terminal because the user can disconnect from InterTest for CICS.
Remote FILE Support
All CICS regions that participate in a remote FILE transaction session must be at InterTest for CICS Version 4.2 or above.
Also, the FILE transaction and the 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.
 269


InterTest™ and SymDump ® 11.0
SymDump  for CICS
Install or Customize DFHPEP
If your site does not have a custom DFHPEP module implemented, the DFHPEP included in the CAI.CAVHLOAD library
must be installed in a library that is 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  SymDump  for
CICS installation requirement. The dump capture functions without DFHPEP/IN25PEP processing. However, the failure to
configure DFHPEP as previously suggested 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 SymDump  for CICS is 20 KB for the permanent
resident program IN25COLD.  The CPU and I/O resources that are used by SymDump  for CICS to produce
a dump will often be less than the resources required by a standard dump, and are unlikely to exceed those
required by a standard dump. The CICS virtual storage that is 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).
Also add the size of the CSA, CWA, TCTTE, TUA, and the formatted trace table of the dumping task.
WARNING
The formatted trace table is only built upon user request.


WARNING
The formatted trace table is only built upon user request.
Because the 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
SymDump  for CICS dump capture and analysis relies on the availability of the CICS internal trace table for many
diagnostic functions. A trace table of 512 KB is usually large enough to hold a typical task processing flow. You
can increase or decrease the trace table size as required by your applications. Failure to activate the internal
trace results in product functionality loss.
EDSA utilization increases approximately 600 KB for each concurrent SymDump  for CICS user. If you capture
the CICS Internal Trace Table using the SYMT transaction, increase the EDSA size approximately twice 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 initialized using SymDump  for CICS release v9.0 and higher are compatible with this release. We
recommend a single PROTDMP file for each CICS region because sharing files across regions is not 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 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 is displayed to the user. The next trace
 270


InterTest™ and SymDump ® 11.0
format request re-obtains 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 region stores the formatted trace once formatted by
DFHTUXX0 for review and filtering by the user. This is a cumulative amount for every trace that is simultaneously
formatted and reviewed. It is obtained during the format request, and is released once the user completely leaves
the SymDump  for CICS selection screen on the CICS region from which the dump was selected.
For a transaction dump, SymDump  for CICS captures up to 180 4 KB blocks of raw trace data. If the maximum
180 blocks is captured and the trace is selected for formatting by three users simultaneously, the TRACE
FORMAT REGION, in a serial fashion, obtains and releases approximately 7 MB of DASD workspace, and gets
27 MB of total extended private area, or 9 MB per trace.
If one of the users exits the trace, the TRACE FORMAT REGION uses 18 MB of extended private area for the two
remaining traces. Since the traces are already formatted by DFHTUXX0, and reside in the extended private area
of the TRACE FORMAT REGION, no DASD workspace is used until a new format request is received.
The new 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
since the actual formatting of the CICS trace is performed by DFHTUXX0 in the TRACE FORMAT REGION.


The response times for trace formatting depend on the size of the traces, the number of simultaneous requests
performed by a TRACE FORMAT REGION, and the amount of machine resource available to the TRACE
FORMAT REGION. For optimal performance, carefully review the IN25OPTS parameters that control trace
formatting.
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
make available to your users that want to view large traces that are captured with the SYMT trace capture facility.
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.
For 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.
SymDump  for CICS currently captures up to 180 4 KB trace blocks for a transaction dump, and captures 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


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, since you cannot
assume that all threads 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, can significantly affect the performance of an individual TRACE
FORMAT REGION. The new 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 changes
this module due to routine maintenance, you need to recycle your TRACE FORMAT REGION to pick up these
changes. To recycle the TRACE FORMAT REGION, issue a cancel or purge on the address space and then
restart it .
Activate Your Product
Use these steps to activate your product.
This article describes the steps you need to activate your product. Product-specific instructions follow the instructions for
All Products . There are no product-specific instructions for InterTest Batch.
 271


InterTest™ and SymDump ® 11.0
All Products
Authorization
Before you activate your product, you must make the executables in CAI.CAVHAUTH available through STEPLIB or
LINKLIST. CAI.CAVHAUTH must be APF authorized.
CAIRIM
CAIRIM must be active on each system that runs InterTest or SymDump  products. You can specify the following
parameters to customize CAIRIM before activating your products.
STEPLIB
The following loadlibs are required if they are not in the linklist:
•The loadlib containing CAIRIM
•All customized configuration elements, which must be APF authorized.
•CAI.CAVHAUTH
•CAI.CAVHLOAD
RIMPARM
Add the following control card to the member or data set pointed to by the RIMPARM DD to initialize the InterTest
and SymDump  products.
PRODUCT(CA INTERTEST/SYMDUMP) VERSION(VHB0) INIT(CAVHINIT) PARM(220)
You can specify the INIT and PARM parameters as follows:
INIT
Specifies the name of the initialization routine. Specify one of the following values:
•CAVHINIT
(Required)
Initializes or refreshes the InterTest and SymDump  products based on the settings in CAVHCONF.
CAVHTERM
Terminates SymDump  Batch.
PARM
You can specify the following values:
•–SVC number (Required for InterTest Batch)
Specify an SVC value between 200 and 255. The value must be an unused SVC number that has no
locks assigned to it.
–RTLONLY
Activate or deactivate the Optimizer/II  RTL but not SymDump Batch.
–SBONLY


Activate or deactivate the Optimizer/II  RTL but not SymDump Batch.
–SBONLY
Activate or deactivate SymDump Batch but not the Optimizer/II  RTL. You must have Optimizer/II  RTL activated to
execute Optimizer/II  programs.
NOTE
CAIRIM inserts a hook into the SVC table (specifically SVC51). If you have concerns about compatibility with
other dump formatting products, see Installation Considerations. The existing address for SVC51 will be saved.
Control will be passed to this address depending on the value of the DUMP option of CAOETGEN.
NOTE
If you upgrade from a previous product release, an IPL is required to refresh all modules from the previous
release. However, there is no functional requirement for an IPL when upgrading from version 10 to version 11.
 272


InterTest™ and SymDump ® 11.0
Query Activation Status
JCL
A procedure called CAVHLPAQ is provided to invoke the Initialization Summary program. To obtain an initialization
summary for your data center, specify the following:
 // EXEC   CAVHLPAQ

The initialization summary program, CAVHLPAQ, uses the following DD statements:
STEPLIB
Defines the library containing InterTest and SymDump  Initialization Summary program.
SYSPRINT
Defines the report file.
Report
The Initialization Summary report displays the following information:
•Module name
•Address where module resides
•Release of each module
•Date module when the module was assembled
•Time when the module was assembled
•Size of module
•Number of InterTest SymDump  modules found
•Contents of module CAOESQAT (for support purposes)
•Contents of CAOETABL
InterTest for CICS
Activate InterTest for CICS from a Program
In one of your programs you can code a routine to activate InterTest for CICS by the CICS command:
 EXEC CICS START TRANSID('CNTL') FROM(data-area)...

The data-area  must contain the command:
 CNTL=START,PROM=tablname

Where tablname  is the name of the load module assembled through PROMMAC macros. The table name must be
followed by a space.
If the CNTL task to be automatically initiated is to own a terminal, be sure that the terminal is in service and has the ATI
(automatic task initiation) capability when the CNTL task is started.
Issuing CNTL Commands from a Program
You can issue any CNTL command using the EXEC CICS START command. However, for the CNTL=START command,
the only permitted format is:


the only permitted format is:
 CNTL=START,PROM=tablname
 273


InterTest™ and SymDump ® 11.0

If the CNTL task is activated at a terminal, response messages are displayed there and the command is executed as
if someone had entered it from that terminal. For example, if the CNTL command sets a breakpoint, the from and to
terminals are the terminal at which the task was activated.
After InterTest for CICS starts, a program can issue an EXEC CICS START command with the data record containing:
 CNTL=EXEC,MODULE=tablname

This command executes the table of commands contained in tablname .
Start InterTest for CICS from a PLT
If the program IN25PLT is included in the PLT, it starts InterTest for CICS as specified in the IN25OPTS member. IN25PLT
is delivered in the distribution load library.
The following InterTest for CICS PLTPI entry must be added after DFHDELIM so that it is part of stage 2 processing:
 DFHPLT TYPE=ENTRY,PROGRAM=IN25PLT

The IN25PLT program can be called by another user-written PLT program that passes a valid InterTest for CICS start
command in a COMMAREA to IN25PLT. An example is given next:
INTSTART DC  C'CNTL=START,PROM=PROMTABL ...'
.
.
.
 EXEC CICS      LINK
        PROGRAM('IN25PLT')
        COMMAREA(INTSTART)
        LENGTH(=Y(L'INSTART))
Note the following points:
•The transient data destination specified in the GLOG= InterTest for CICS option must be defined to CICS and must be
opened.
•The group DFHINQUI must be defined in the CICS startup list  for IN25PLT to execute.


•The InterTest for CICS Help file, PROTHLF, must be defined and available.
•If installing SymDump  with InterTest, the SymDump  for CICS IN25INST program should always be placed after the
InterTest for CICS IN25PLT program in the PLT.
•You can guarantee that the InterTest for CICS exits are first to receive control by adding the program entry IN25PLTX
to the CICS startup PLT. IN25PLTX is required as the first program entry in Phase 1 (prior to the DFHDELIM entry) of
the PLT.
Automatic Startup in CICSplex Regions
If InterTest for CICS is automatically started in a CICSplex-participating region (that is, CICSPLEX=YES in IN25OPTS), it
resynchronizes its monitoring options with any active CICSplex members upon startup.
NOTE
Resynchronization occurs whenever the CNTL=START or CNTL=RESTART command is issued in a CICSplex-
participating region.
 274


InterTest™ and SymDump ® 11.0
Activate InterTest for CICS
After you have completed the installation steps, you can activate InterTest for CICS in your CICS system at any time. To
activate InterTest for CICS, issue the following command:
 CNTL=START

For InterTest for CICS regions installed with CICSplex support (CICSPLEX=YES in IN25OPTS), the CNTL=START and
CNTL=RESTART commands automatically have InterTest for CICS resynchronize monitoring with any active regions in
the CICSplex.
At this time, you can compile and assemble your programs with the InterTest for CICS symbolic post-processor programs
as described in Symbolic Support. These programs let you use symbolic references during testing.
Remember, however, that you do not have to compile your programs with one of the InterTest for CICS symbolic
post-processor programs. All of the InterTest for CICS monitoring facilities are available for current programs without
recompiling or reassembling them. We do recommend that you recompile or reassemble current programs if InterTest for
CICS detects errors because symbolic support greatly facilitates debugging.
To activate InterTest for CICS at CICS startup, perform the following procedures:
1.Manually activate InterTest for CICS by issuing the CNTL=START command.
2.Automatically activate InterTest for CICS using the PROMMAC macro or the IN25PLT PLTPI program.
Deactivate InterTest for CICS
InterTest for CICS can be deactivated at any time by issuing the following command:
 CNTL=END

For regions using the CICSplex support option, you can issue the following command to concurrently deactivate InterTest
for CICS in all connected CICSplex regions:
 CNTL=END,SCOPE=GLOBAL


CNTL=END,SCOPE=GLOBAL

InterTest for CICS maintains a permanent  service task that runs under the transaction ID ISER. The program is
IN25SERV. CICS cannot complete a normal shutdown until this task ends. It is important that you deactivate InterTest for
CICS before CICS shutdown to terminate this task.
To deactivate InterTest for CICS at CICS shutdown, perform one of the following procedures:
•Manually deactivate InterTest for CICS by issuing the CNTL=END command.
•Automatically deactivate InterTest for CICS using the IN25PLTE program. If you add this InterTest for CICS-supplied
shutdown PLT program to your shutdown program list, InterTest for CICS will be deactivated automatically at normal
CICS termination.
Add the following InterTest for CICS PLTSD entry before DFHDELIM so that it is part of Stage 1 processing:
 DFHPLT TYPE=ENTRY,PROGRAM=IN25PLTE

Restart CICS and Run VRPT Transaction
After InterTest for CICS has been installed, restart CICS and run the InterTest for CICS check-out program IN25VRPT.
This program checks for common mistakes that may have been made during the installation of InterTest for CICS.
 275


InterTest™ and SymDump ® 11.0
WARNING
You are strongly advised to perform this step so errors can be detected quickly.
Use the following procedure to check out the installation of InterTest for CICS.
Follow these steps:
1.Enter the transaction code VRPT. InterTest for CICS displays the selection menu.
2.Enter 1 in the Option field and press Enter. InterTest for CICS displays the first screen of programs.
3.Continue to press Enter to display the next screen.
4.The InterTest for CICS check-out procedure is completed when the selection menu is displayed with the option field
set to 4  or beyond.
NOTE
If you are upgrading from a previous release, urge your users to use ITST Option 8 to review "What's New" in
this release.
SymDump  for CICS
Define and Schedule the Trace Format Region Job
The TRACE FORMAT REGION must be running within your CCI network in order for you to format CICS traces within
SymDump  for CICS.
Member TRCMSAMP contains the sample JCL for the SymDump  for CICS TRACE FORMAT REGION. This job
may be run as a normally scheduled job, or as a started task at your discretion. The TRACE FORMAT REGION can
accommodate trace format requests from multiple CICS regions that have SymDump  for CICS installed within an existing
CCI NETWORK. These CICS regions may be at different releases of CICS.
NOTE
The association between a given CICS region and the TRACE FORMAT REGION is made through CCI services
based on parameter TRCFFMID in your IN25OPTS definition.
Although the TRACE FORMAT REGION will probably work with the standard defaults for the relevant IN25OPTS
parameters, you are encouraged to familiarize yourself with the new IN25OPTS parameters that control trace formatting.


This helps to ensure that you are successful in implementing this powerful feature of SymDump  for CICS.
Edit the JCL to conform to your installation standards and the previously completed worksheet. However, never change
any of the ddnames.
You must now include a STEPLIB DD statement pointing to your CAVHLOAD load library in addition to the STEPLIB DD
statement pointing to your CICS load library. This is already in the TRCMSAMP sample JCL member.
Submit this job before attempting to format CICS traces from SymDump  for CICS.
Restart CICS and Run VRPT Transaction
After SymDump  for CICS is installed, restart CICS and run the SymDump  for CICS check-out program IN25VRPT. This
program checks for common mistakes that may have been made during the installation of SymDump  for CICS.
WARNING
You are strongly advised to perform this step so errors can be detected quickly.
Follow these steps:
1.Type the transaction code VRPT. SymDump  for CICS displays the selection menu.
2.Type 4 in the Option field and press Enter. SymDump  for CICS displays the first program screen.
3.Continue to press Enter to display the next screen.
 276


InterTest™ and SymDump ® 11.0
4.When the selection menu appears with the option field set to 1, the SymDump  for CICS check-out procedure is
complete.
Start and Stop Dump Capture Facility
After installing SymDump  for CICS, you can use one of the following methods to start the dump capture facility
automatically with your CICS system.
•Enter the SYMS command from a CRLP-type terminal . If you have at least one CRLP-type terminal defined in your
TCT, its input sequential file can contain the SYMS command. The command executes just as if it was entered
manually from a CRT, and responses to it are written in the terminal's output sequential file.
•Start SymDump  for CICS from a PLT table. If the program IN25INST is included in the PLT table, it starts SymDump  for
CICS. IN25INST is delivered in the target load library.
Purge a Dump Data Set Automatically at Startup
If you are starting SymDump  for CICS from the PLT table using IN25INST, you can automatically purge old dumps at
that time. If the automatic purge of dumps configuration parameter is set to Y, IN25INST purges any dumps equal to or
older than the number of days specified in the automatic purge hold days parameter. The default for this parameter is one
day. For more information, see CICS Abend Analysis.
WARNING
If you do not want your dumps to be automatically deleted, set the automatic purge of dumps parameter to N
and refer to the dynamic purge of oldest dump parameter. This allows SymDump  for CICS to dynamically purge
non-held dumps during dump capture on a first-in, first-out basis to obtain space for the new dump.
Shut Down Automatically


Shut Down Automatically
You must deactivate SymDump  for CICS prior to shutting down your CICS region, or an abend may occur.
You can manually deactivate SymDump  for CICS using the SYME transaction from a 3270 terminal.
You can automatically deactivate SymDump  for CICS using the IN25ENPL program. If you add this SymDump  for CICS-
supplied shutdown PLT program to your shutdown program list, SymDump  for CICS is deactivated automatically at normal
CICS termination.
To take advantage of this feature, add the following SymDump  for CICS PLTSD entry before DFHDELIM so it becomes
part of Stage 1 processing:
 DFHPLT TYPE=ENTRY,PROGRAM=IN25ENPL

Shut Down Trace Format Region
The SymDump  for CICS Trace Format Region can be shut down in an orderly fashion by replying shutdown to the
outstanding write to operator message (CAIN5951) that is on the operator's console.
SymDump  Batch
Deactivate SymDump  Batch
To deactivate SymDump  Batch, use the same procedure that is used to activate the product, but instead of the RIMPARM
card specified in that procedure, use the following:
 PRODUCT(CA SYMDUMP/INTERTEST) VERSION(VHB0) INIT(CAVHTERM)

 277


InterTest™ and SymDump ® 11.0
Installation Verification
Run the demo programs for each application to validate the installation.
This article describes how to run the demo programs for each application. Running the demo programs validates the
installation and provides an introduction to using your product.
InterTest Batch
Use one of the procedures customized in the Customize Compile Procedures to compile, assemble, and link one of the
demo programs provided in CAI.CAVHSAMP. The following list shows the demo program names for each compiler. For
detailed information about running the demo program, see InterTest Batch Demo Sessions.
CAMRASM
For Assembler programmers
CAMRPLI
For PL/I programmers
CAMRCOB
For OS/VS COBOL programmers
CAMRCOB2
For COBOL II programmers
NOTE
These programs use ISPF. Programmers on Roscoe  systems can use CAMRDMR and CAMRDMR2 for
demonstration purposes.
SymDump  Batch
Validate the SymDump  Batch installation by completing the following steps:
1.Review and edit JCL member CARXDEMO.
2.Run the demo and examine the results.
3.Run the database demo programs.
4.Review abend reports using the Viewer.
Review and Edit JCL Member CARXDEMO
JCL member CAI.CAVHJCL(CARXDEMO) is a compile, postprocess, link, and run of the demo program, CAOEDEMO.
Edit the JCL to conform to your installation standards.
Run the Demo and Examine the Results
Submit CARXDEMO and examine the results. Successful execution results in a S0C7 from the RUN step.
By default, the RUN step always produces the following SymDump  Batch reports:
•CAIOPTS File Processing report
•Abend report


•CAIOPTS File Processing report
•Abend report
Run the IDMS/DB , DB2, and IMS Demo Programs
If you use the IDMS/DB , DB2, and IMS abend reporting features, run the demo programs that apply to your site. If your
site is not using these features, skip this step.
The sample JCL members for the demo programs are stored in CAI.CAVHJCL. Review and edit the following members
that apply to your shop.
 278


InterTest™ and SymDump ® 11.0
CARXDEM1
—for IDMS/DB
CARXDEM2
—for DB2
CARXDEM3
—for IMS
Run the job and examine the results. A SymDump  Batch report is produced when each job abends.
Review Abend Reports Using the Viewer
You have an option of reviewing abend reports for validating the installation.
Follow these steps:
1.Select the appropriate option from your ISPF main menu (updated in Concatenate ISPF File and Tailor Master Panel)
to start the CAIPRINT repository viewer.
An index of all the abend reports that were created during this installation step is displayed.
CA SymDump Batch  ---------- Report Index -------------------- Line 1 of 1
Command ===>                                                   Scroll ===>
CSRCAPI100I Repository contains 1 report(s) --------------------------------------
Repository Dsname: CAI.PRTLIB
     3509 Data Records       36 Used     1.1% Full
Filter: Jobname *       Step/Tsk *        Program   *             Offset *
        Comp    *       UserID   *        Lock      *             System *
------------------------------------------------------------------------- Lvl 1>
Cmd  JobName   Step/Tsk  Program   Offset   Comp    Date        Time   UserId  .
     USER01X   RUN       CAOEDEMO  0003B64  S=0C7   2007/03/17  16.47  USER01
-------------------------------------------------------------------------------
2.Select a report for viewing by entering an s in the Cmd column next to the report entry, and press Enter.
The Report Tree panel appears.
CA SymDump Batch  ---------- Report Tree -------------------- Line 1 of 13
Command ===>                                                   Scroll ===>


Command ===>                                                   Scroll ===>
CSRCAPI052I Profile restored as of 17:58:49 on 2011/07/20 ------------------------
JobName  USER01A    Step/Tsk  RUN       UserId  USER01      Date  2011/07/20

Program  CAOEDEMO   Offset    00041B6   Comp    S=0C7       Time  17.57
------------------------------------------------------------------------- Lvl 2
Cmd  LineNo.   Description
.         1 - Job=USER01A
.         1   |-Input Options Display
If the report tree is displayed, you have successfully validated your installation.
NOTE
For a detailed description of the CAIPRINT repository viewer and its functionality, see Batch Abend Analysis.
 279


InterTest™ and SymDump ® 11.0
InterTest for CICS
Demonstration programs are distributed for Assembler, COBOL, and PL/I in the source format. You can assemble or
compile them using the jobs found in CAVHJCL. The PROCs executed by these sample jobs are defined in CAVHPROC.
The sample jobs provide symbolic parameter overrides to the respective PROC members. You can modify the appropriate
PROC members to define these symbolic parameters as defaults. You need to modify the PROC members to define
certain default symbolic parameters to comply with your installation standards. For detailed information about running the
demo program, see InterTest for CICS Primers.
The following list details the five members in CAI.CAVHJCL.
CABADMAJ
The CABADMAJ job prepares the Assembler language demonstration program for execution. For more
information about using the ASMDEMO program, see Assembler Primer. This job contains the following steps:
Step ALOCLIBS
Allocates an object library and a load library. This step can be deleted if you are using existing libraries.
Step ASMDEMO
Executes PROC CABAASMP to translate, assemble, and postprocess the Assembler language demonstration
program ASMDEMO.
Step LKEDDEMO
Executes program IEWL to bind the object module created by Step ASMDEMO.
CABADMCJ
The CABADMCJ job prepares the COBOL language demonstration program (COBDEMO) for execution. For
more information about using the COBDEMO program, see COBOL Primer. This job contains the following steps:
Step ALOCLIBS
Allocates an object library and a load library. This step can be deleted if you are using existing libraries.
Step COBDEMO


Step COBDEMO
Executes PROC CABACOBP to compile and postprocess the COBOL language demonstration program
COBDEMO.
Step LKEDDEMO
Executes program IEWL to bind the object module from the previous step.
Step CSBIN25
Executes PROC CABACOBP to compile and postprocess the COBOL language demonstration subprogram
CSBIN25.
Step ASBIN25
Executes PROC CABAASMP to translate, assemble, and postprocess the Assembler language demonstration
subprogram ASBIN25.
Step COBDEML
Executes PROC CABACOBP to compile and postprocess the COBOL language demonstration program
COBDEML.
Step LKEDDEML
Executes program IEWL to bind the object modules from the previous steps into a composite load module.
Step GLNKDEML
Executes program IN25LINK to prepare COBDEML for composite mapping demonstration.
CABADWCJ
The CABADWCJ job prepares the COBOL language demonstration program (COBDEMO) with DWARF symbolic
information for execution. For more information about using the COBDEMO program, see COBOL Primer. This
job contains the following steps:
Step ALOCLIBS
Allocates an object library and a load library. This step can be deleted if you are using existing libraries.
Step COBDEMO
Executes the PROC CABACOBD to compile the COBOL language demonstration program COBDEMO with
DWARF symbolic information.
 280


InterTest™ and SymDump ® 11.0
Step LKEDDEMO
Executes the program IEWL to bind the object module from the previous step.
CABADMDJ
The CABADMDJ job prepares the COBOL DB2 demonstration program (DB2DEMO) for execution. For more
information about using the DB2DEMO program, see COBOL Primer. This job contains the following steps:
Step ALOCLIBS
Allocates an object library and a load library. This step can be deleted if you are using existing libraries.
Step DB2TRAN
Executes the DB2 Translator for the demonstration program DB2DEMO.
Step COBDEMO
Executes PROC CABACOBP to compile and postprocess the COBOL language demonstration program
DB2DEMO.
Step LKEDDEMO
Executes program IEWL to bind the object module from the previous step.
Step BINDPLAN
Executes program IKJEFT01 to bind the plan for DB2DEMO program.
CABADMPJ
The CABADMPJ job prepares the PL/I language demonstration programs. For more information about using the
PL1DEMO program, see PL/I Primer. This job contains the following steps:
Step ALOCLIBS
Allocates an object library and a load library. This step can be deleted if you are using existing libraries.
Step PLIDEMO
Executes PROC CABAPLIP to compile and postprocess the PL/I language demonstration program PL1DEMO.
Step LKEDDEMO
Executes program IEWL to bind the object modules from the previous step.
Step PSBIN25
Executes PROC CABAPLIP to compile and postprocess the PL/I language demonstration subprogram PSBIN25.
Step ASBIN25


Step ASBIN25
Executes PROC CABAASMP to translate, assemble, and postprocess the Assembler language demonstration
subprogram ASBIN25.
Step PLIDEML
Executes PROC CABAPLIP compile and postprocess the PL/I language demonstration program PL1DEML.
Step LINKDEML
Executes program IEWL to bind the object modules from the previous steps into a composite load module.
Step GLNKDEML
Executes program IN25LINK to prepare PL1DEML for composite mapping demonstration.
SymDump  for CICS
After you install SymDump  for CICS and start CICS, you can run the demonstration programs to force and then view a
transaction dump.
Follow these steps:
1.Entering the transaction code SYMD to verify that SymDump  for CICS was started.
2.Type 4 in the Option field and press Enter.
SymDump  for CICS will start or will tell you that it was already started.
3.Type X to terminate SYMD.
4.Type one or more of the following transaction codes. After the menu appears, press Enter to force an ASRA abend
and the creation of a CICS transaction dump that should be captured and displayable by SymDump  for CICS.
DEMA    Assembler program ASRA (0C7)
DEMC    COBOL program ASRA (0C7)
DEMD    COBOL DB2 program ASRA (0C7)
 281


InterTest™ and SymDump ® 11.0
DEMP    PL1 program ASRA (0C7)
5.Type the transaction code SYMD.
6.Type 1 on the Option field and follow the menu instructions to view the dumps created in the previous Step 4.
Install Maintenance
After you have successfully installed any Broadcom  mainframe product software, check for important product
maintenance that may have been released after the product installation package was prepared. The product releases are
built and maintained using standardized SMP/E packaging and installation procedures. These procedures include error
and FIXCAT HOLDDATA, new product features, and product interoperability validation. PTFs that pass interoperability test
criteria are released monthly and designated as CARS .
You can install the following types of maintenance:
•Corrective maintenance that fixes an issue.
•Preventive maintenance to avoid problems that others have reported or to provide a compatibility fix for hardware and
software.
•FIXCAT maintenance to support a particular hardware device, software release, or new product function.
WARNING
You can initiate a maintenance installation activity at any time using z/OSMF Software Update, SMP/E JCL, or
CSM . However, before you do so, we recommend that you obtain the current SMP/E HOLDDATA.
See Broadcom Mainframe Product Maintenance  for a list of solutions that have been published within the last year. From
this page, you can search solutions for all Broadcom  mainframe products by product name, date, or keyword. You can
also search for new product features or by a CARS  level (CARSID). You can also find HIPER or PE PTFs and security
or integrity PTFs. Once you have your list, you can download in Excel or CSV format. To download PTFs automatically
without having to search regularly on the portal, use SMP/E Receive Order .


without having to search regularly on the portal, use SMP/E Receive Order .
For a comprehensive collection of articles that are dedicated to all mainframe maintenance concepts and procedures, see
Mainframe Common Maintenance Procedures .
Maintain Products Using z/OSMF Software Update
As a systems programmer, you are responsible for keeping your systems current with product maintenance to ensure
optimal system usage. To do so, use IBM z/OSMF Software Update. Software Update provides an easy to follow wizard
that guides systems programmers of all levels through the maintenance process. z/OSMF Software Update offers a
modern approach to software maintenance and provides the following features:
Corrective Service Installs a software update to fix an issue.
Preventive Service Installs vendor-recommended software updates.
FIXCAT Installs software updates (Fix Categories) that provide a new function to a system.
NOTE
We are not adding new features to CSM . We recommend that you use z/OSMF Software Update to apply
maintenance to z/OS software.
Prerequisites
Ensure that you meet the following software requirements before you use Software Update:
•Configure z/OSMF as described in the IBM documentation and address the z/OSMF security requirements for ACF2 ,
Top Secret, or IBM RACF as applicable.
•Apply all z/OSMF Software Update-related maintenance from IBM.
•Register your SMP/E environments (CSIs) in z/OSMF Software Management. For more information, see Software
Management task  in the IBM documentation.
 282


InterTest™ and SymDump ® 11.0
TIP
A migration tool is provided to help you register existing CSM  and non-CSM CSIs as new software instances
in z/OSMF. For more information about the migration tool, see Migrate SMP/E Environments into z/OSMF .
•Download and receive maintenance, HOLDDATA, and CARS  maintenance for your products. As a best practice, we
recommend that you do so on a daily or weekly basis and that you automate this process using SMP/E Receive Order
(see Configure SMP/E Internet Service Retrieval ). You can also perform these tasks manually from Broadcom Support .
NOTE
You can only apply maintenance for SYSMODs that are already received in the GLOBAL zone of the CSI.
IMPORTANT
The ASSIGN statements for CARS  maintenance are not cumulative. To install the latest CARS  maintenance,
download all YEARLY ASSIGN files, and then download the monthly ASSIGN files as needed.
Use Software Update
Log in to your instance of z/OSMF and click the Software Update  icon on the desktop. If the Software Update  icon does
not appear on the desktop, open the App Center in the bottom-left corner.
You can now maintain software instances, using the z/OSMF Software Update functionality. For more information about
how to use Software Update, see  Software Update in the IBM documentation.
Maintain Products Using CSM
Use the procedures in this topic to receive, apply, and accept maintenance for your products using CSM .
CSM  provides a product list that lets you display the list of licensed product maintenance packages and to download these
packages. You can also manage external maintenance packages that were acquired outside of CSM  so that they can be
applied using  CSM .
WARNING
As part of our ongoing commitment to customer success and to help our customer base achieve their


WARNING
As part of our ongoing commitment to customer success and to help our customer base achieve their
strategic business initiatives, we are investing our resources in z/OSMF for software management. We will
be discontinuing technical support for CSM . In accordance with the terms and conditions, guidelines, and
parameters of Broadcom’s support program, which is documented in the Broadcom Software Maintenance
Policy Handbook , this announcement provides written notification of End of Life for CSM . This notification means
that CSM  will no longer be enhanced and maintenance and technical support, including self-service support, will
be discontinued effective June 30, 2023 . For full details, see the End of Life Announcement.
NOTE
During your initial product installation, apply all product maintenance. Otherwise, you may have to repeat the
deployment and configuration processes.
The following diagram shows the maintenance process using CSM :
 283


InterTest™ and SymDump ® 11.0
Use the following procedure to maintain products using CSM :
1.(Optional) Configure automatic HOLDDATA download.
2.(Optional) Configure CSM  to reject unneeded maintenance .
3.Download product maintenance packages .
–(Optional) Configure CSM  to perform automatic maintenance updates .
4.(Optional) Manage maintenance downloaded outside of CSM . As part of this management, you can also view the
aggregated package details .
5.Receive maintenance .
6.(Optional) Reject maintenance .
7.Apply maintenance .
a.Consider whether you require a product USERMOD .
b.Review and process any unresolved HOLDDATA.
c.Apply CARS  maintenance .
d.(Optional) Apply FIXCAT maintenance.
8.(Optional) Restore maintenance .
9.Accept maintenance .
–(Optional) Accept maintenance in GROUPEXTEND mode .
 284


InterTest™ and SymDump ® 11.0
After you complete this process, the maintenance packages for your products are accepted.
You have deployed and configured a product across your enterprise. Now you are applying maintenance to this product.
Create a deployment and a configuration for this product to get this maintenance to your target systems.
Configure Automatic HOLDDATA Download
You can configure CSM  to download automatically the available HOLDDATA that it uses for each maintenance installation.
You then have current information about what maintenance packages are marked as PE (PTF in Error).
1.Select the Settings  tab, and select the Software Catalog  link under System Settings  in the Settings  section on the
left side.
2.In the HOLDDATA Settings section, select the Enable Automatic Updates  checkbox.
3.Set up values for the following fields, and select Apply :
Owner of Update Task
Specifies the TSO user ID under which the update task is run.
Recurrence
Specifies how often the task recurs.
Update Software Catalog Every number of Days
or Update Software Catalog On day of week  Every  number of  Weeks
Specifies the frequency of downloading HOLDDATA to your software catalog, in days or weeks, depending on the
value the Recurrence  field.
Example : Imagine you set the recurrence for a specific number of days and you set the time that precedes the
current time. Then the first update occurs in the specified number of days at the specified time. For example, on
Monday at 10.30 am, you set the number of days to 3 and time to 07.00. The first update then occurs on the third
day, Thursday, at 7.00 am. When you set the time past the current time, the first update occurs on the same day


at the time set. For example, on Monday at 10.30 am, you set the number of days to 3 and time to 11.00. The first
update then occurs on that Monday at 11.00 am.
System Time
Specifies the system time when an automatic update occurs. The system time reflects your CSM  application
server time zone. The TZ parameter within Tomcat startup libraries defines the time zone. If the TZ parameter is
not defined, the CSM  application server time zone defaults to GMT - Greenwich Mean Time.
Local time is calculated based on the system time that you set.
NOTE
To download available HOLDDATA to the software catalog immediately, select Update Immediately .
The automatic HOLDDATA download is configured.
Configure CSM  to Reject Unneeded Maintenance from the SMP/E Environment
During the regular, FIXCAT, or CARS  maintenance wizard execution, CSM  may receive maintenance. Some maintenance
packages may not be directly associated with the maintenance that you want to apply.
You can configure CSM  to reject the maintenance that was received but not applied during the wizard execution.
•If you exit the wizard before the maintenance installation started, CSM  rejects the maintenance that has been received
during the wizard execution. The SMP/E environment is restored to the state that it had before you started the wizard.
•If you navigated through the wizard steps, started the maintenance installation task, and the task completed
successfully, CSM  rejects the received but not applied maintenance that is not directly associated with the
maintenance that you have applied.
 285


InterTest™ and SymDump ® 11.0
This process ensures that your SMP/E environments do not contain unneeded received maintenance.
1.Select the Settings  tab, and select the Software Installation  link under System Settings  on the left side.
2.In the Maintenance Installation  section, select the Reject Received Maintenance  checkbox.
3.Select Apply .
A dialog that shows the progress of the task opens. When the task completes, select Show Results  on the Progress
tab to close this dialog. The task output browser opens, and you can view the action details.
NOTE
While a task is in progress, you can perform other work. Select Hide  to exit the dialog and view the task
status later on the Tasks tab.
CSM  is configured to reject unneeded maintenance.
Download Product Maintenance Packages
You can download maintenance packages for installed products through the Products  tab. You can download:
•All maintenance packages for a product
•Only maintenance packages that have been released from the time the product release was updated last
NOTE
The information for HIPERs and new maintenance on the Software Status tab  is based on the current
information in your software catalog. Update the product list on a daily or weekly basis to keep it current.
WARNING
You can also download maintenance using the SMP/E Internet Service Retrieval . This option uses the IBM
SMP/E RECEIVE ORDER command to download Broadcom  mainframe product maintenance over the Internet,
by securely submitting an order for PTFs and HOLDDATA to a remote Broadcom  server. This service eliminates
the manual steps that are required to download maintenance from Broadcom Support . The orders are fulfilled
based on the status of your SMP/E environments. Based on your order criteria, all PTFs and their requisites are
downloaded automatically and received to your system.


downloaded automatically and received to your system.
To use this download option, complete the procedures to configure the SMP/E Internet Service Retrieval  as
described in the Mainframe Common Maintenance Procedures  documentation. After you set up this service, you
can use CSM  to apply and accept your maintenance.
1.Verify that your CSM  login user name is associated with a registered user of Broadcom Support  on the Software
Acquisition Settings  page.
CSM  uses the credentials to access Broadcom Support .
2.Select the name of the product for which you want to download maintenance in the product list on the left side.
Maintenance information about the product appears in the Releases section on the right side.
3.For the product release for which you want to download maintenance, select the Actions  drop-down list to the right of
the release. Complete one of the following steps:
a.Select Update Product Release  to download all maintenance packages for the product release.
b.Select Get Latest Maintenance  to download only maintenance packages that have been released from the time
the product release was updated last.
A dialog that shows the progress of the task opens. When the task completes, select Show Results  on the Progress
tab to close this dialog. The task output browser opens, and you can view the action details.
The maintenance packages are downloaded.
 286


InterTest™ and SymDump ® 11.0
Configure CSM  to Perform Automatic Maintenance Updates
You can configure CSM  to perform automatic maintenance updates (downloading and receiving maintenance) for
products that are installed in an SMP/E environment.
Manage Maintenance Downloaded Outside of CSM
Sometimes you acquire maintenance packages, such as unpublished maintenance, PTF, APARs, and USERMODs,
outside of CSM . For example, you are validating a test PTF released for a product. You can add information about these
maintenance packages to CSM  from the Products tab.
Adding these maintenance packages to CSM  provides you with a complete view of all the maintenance for a product
release. After a package is migrated, you can use CSM  to apply the maintenance.
Usually, the maintenance is placed as a single package. However, some Broadcom  mainframe products still have older
aggregated maintenance packages that were released before December 31, 2013. An aggregated package  is a file that
comprises several single maintenance packages (nested packages). When you add an aggregated package, CSM  inserts
all the nested packages and the aggregated package itself. In the list of maintenance packages, the aggregated package
is marked with the CUMULATIVE type.
When you insert an aggregated package, CSM  assigns a fix number to it. The fix number is unique and contains eight
characters. The first two characters are AM (for Aggregated Maintenance) and a unique six-digit number follows. The
number value increases by 1 with each added aggregated package.
If the aggregated maintenance package has the same fix number as one of its nested packages, only the nested package
is added. The aggregated package itself is not available in the list of maintenance packages.
1.Select the Products  tab, and select the product release for which the maintenance applies.
2.Select the Add External Maintenance  button.


2.Select the Add External Maintenance  button.
3.Specify one of the following package types and package details:
Data Set
Adds a maintenance package that is located in a z/OS data set with an LRECL of 80 and RECFM of FB.
UNIX File
Adds a maintenance package that is located in a USS directory in binary mode.
FTP File
Adds a maintenance package that is not published on Broadcom Support . This option is intended for downloading
a PTF to validate it.
FTP Host Specifies the FTP server where the maintenance package is located. Select a server from the list, or
provide your FTP server host.
FTP Port Specifies the FTP port number for the FTP server.
FTP Path Defines the FTP path where the maintenance package is located. Start the path with a forward slash
(/). Enter only a forward slash to specify the root directory.
Example:  /outgoing/
Maintenance Name Defines the maintenance package name.
Example:  RO01111.bin
User Name Defines a valid user name to access the FTP location.
Password Defines a valid password to access the FTP location.
Solution
Adds a published solution on Broadcom Support .
NOTE
To add several data sets or UNIX file packages from the same location, use masking.
4.Select OK.
 287


InterTest™ and SymDump ® 11.0
A dialog that shows the progress of the task opens. When the task completes, select Show Results  on the Progress
tab to close this dialog. The task output browser opens, and you can view the action details.
The maintenance package with the related information is saved in the CSM  database. To see the added package, refresh
the page.
View Aggregated Package Details
You can view which nested packages are included in the aggregated package. The information includes the fix number,
package type, and package description.
NOTE
Aggregated maintenance packages were discontinued December 31, 2013. However, some Broadcom
mainframe products have aggregated maintenance packages that were released before this date.
1.Select the Products  tab, and select the product release that has the aggregated package whose details you want to
view.
2.Select the Fix #  link for the aggregated package.
The Maintenance Package Details dialog opens.
3.Select the Nested Packages  tab.
A list of nested packages that the aggregated package contains appears.
Receive Maintenance
After maintenance has been downloaded for a product, you can receive the maintenance to the global zone of an SMP/E
environment where the related products are installed. Once received, maintenance packages can be applied.
While you work with an SMP/E environment, the environment is locked and other CSM  users cannot perform any action
against it. When the task finishes, logging out from CSM , or a CSM  session is inactive for more than 10 minutes, the lock
releases.
1.Select the SMP/E Environments  tab, and select the SMP/E environment where you want to receive maintenance
packages.
2.Select Maintenance . If you do not see any maintenance packages, verify that you have maintenance view criteria
defined.
3.Select the maintenance packages that you want to receive, and select the Receive link.


defined.
3.Select the maintenance packages that you want to receive, and select the Receive link.
The maintenance wizard opens to the Introduction step.
NOTE
If you select an SMP/E environment being used in CSM  by another user, a notification message appears.
You are prevented from performing any actions on the SMP/E environment. Wait until the notification
message disappears and the SMP/E environment becomes available, or select Cancel to select another
SMP/E environment.
4.Review the information about the receiving, and select Next .
5.Review and adjust the receive list selections as required, and select Next .
6.Review the summary, and select Receive .
A dialog that shows the progress of the task opens. When the task completes, select Show Results  on the Progress
tab to close this dialog. The task output browser opens, and you can view the action details.
The maintenance packages are received to the SMP/E environment global zone.
Reject Maintenance
You can reject a received maintenance package. Information about the maintenance package is removed from the SMP/E
environment global zone.
 288


InterTest™ and SymDump ® 11.0
While you work with an SMP/E environment, the environment is locked and other CSM  users cannot perform any action
against it. When the task finishes, logging out from CSM , or a CSM  session is inactive for more than 10 minutes, the lock
releases.
1.Select the SMP/E Environments  tab, and select the SMP/E environment from which you want to reject maintenance.
2.Select Maintenance . If you do not see any maintenance packages, verify that you have maintenance view criteria
defined.
3.Select the maintenance packages that you want to reject, and select the Reject  link. You can filter out only received
packages.
The maintenance wizard opens to the Introduction step.
NOTE
If you select an SMP/E environment being used in CSM  by another user, a notification message appears.
You are prevented from performing any actions on the SMP/E environment. Wait until the notification
message disappears and the SMP/E environment becomes available, or select Cancel to select another
SMP/E environment.
4.Review the information about the rejection, and select Next .
5.Review and adjust the rejected list selections as required, and select Next .
6.Review the summary, and select Reject .
A dialog that shows the progress of the task opens. When the task completes, select Show Results  on the Progress
tab to close this dialog. The task output browser opens, and you can view the action details.
The maintenance packages are rejected. Information about the maintenance packages is removed from the SMP/E
environment global zone.
Apply Maintenance
After maintenance has been downloaded for a product, you can apply the maintenance to products that are installed in an
SMP/E environment.
WARNING
Before you apply maintenance, ensure that required file systems are mounted and that you have specified the