Skip to content

Contributing to zCICS

zCICS was written entirely in assembler code. Transactions can be written either in assembler or in zCobol.

This document explains how to build zCICS and how to run a regression test

Building zCICS

The zCICS source code is pre-packaged with z390. But zCICS is not pre-built with z390. To use zCICS you have to build it from source.

The build procedure for zCICS consists of two steps: 1. DFHALL compiles/assembles all programs involved 2. DFHALLV creates all the zVSAM clusters to run zCICS

bat> cics\bat\DFHALL.BAT bat> cics\bat\DFHALLV.BAT

bash> ./cics/bash/dfhall bash> ./cics/bash/dfhallv

Under Windows, the DFHALL.BAT may be invoked with argument unref: bat> cics\bat\DFHALL.BAT unref When the unref parameter is supplied the UNREF utility will be run after each assembly to provide an overview of unreferenced fields.

Note: On Windows zCICS can also be built as part of the z390 build procedure: bat> BUILD.BAT *All

zCICS Sequential Terminal Support

This chapter explains the use of zCICS Sequential Terminal Support, which can be used for zCics and/or zCics application regression testing.

Create a trace of your transactions

You are well advised to keep a document relating the file number to the transaction and functions being tested. The standard zCICS tests are documented in cics\seq\SEQDOC.TXT.

  1. Run cics\bat\Z390TRC.BAT to start Z390\CICS in trace mode 1.1 This uses the Z390TRC.INI file which has SEQ_TERM=TRACE This adjusts other INI parms: 1.2 LOCAL_TERMINALS=1 1.3 No INITIAL_TRANSID= 1.4 TRACE_LOCALS=YES
  2. Run a planned test of your transaction
  3. CEMT P SHU to end zCICS
  4. Run cics\bat\Z390SEQG.BAT If you change the INI parm TERMID_PREFIX then change Z390SEQG.BAT as well. This reads the trace file ttt0.TRE and extracts the input and output streams to create the files SEQInnnn.TXT and SEQCnnnn.TXT. Enter the file number when requested as a 4-digit decimal number including leading zeros, e.g. 0009. nnnn is one more than the last one starting from 0001 or the file number if you are replacing a previous one. Note: The final CEMT P SHU command is not included in the SEQInnnn stream.
  5. Repeat the above steps for each of your transactions

Runnning the simulation

  1. If you want the simulation to shut down after running, a sample stream is provided called SEQISHUT.TXT, copy this to a new file called SEQInnnn, where nnnn is the next available input file sequence.
  2. Run cics\bat\Z390RT.BAT to start Z390\CICS
    1. This uses the Z390RT.INI file which has SEQ_TERM=YES This adjusts other INI parms:
    2. LOCAL_TERMINALS=0
    3. No INITIAL_TRANSID=
    4. TRACE_LOCALS=NO
    5. To prevent a MAXQUE overflow add a MAXQUE argument to the invocation command. E.g. cics\bat\Z390RT.BAT MAXQUE(256000)
  3. The regression test will run and shut down if item 1 above has been done.
    1. It will use the SEQInnnn files as input and creates a single SEQO0001.TXT file as output.
    2. The output streams are also sent to the Sequential terminal.
    3. The log is captured in cics\Z390CICS.LOG

Status Note: The current configuration abends U0444. This is a secondary symptom following a zCICS AEIV abend indicating a length error of some kind. The problem seems to be triggered from SEQI0012. This problem will need to be investigated and resolved before we can validate test results using the comparator process described below.

This problem is covered by issue 784 in the github repository.

Running the comparator

  1. Run cics\bat\Z390CMPG.BAT This will compare all SEQCnnnn files with the new output stream SEQO0001.TXT. It produces SEQCOMP.TXT with those data streams that have differences. There is a WTO message at the end with the number of streams that have been written. The ideal state for a Z390CMPG run is zero which results in a null SEQCOMP.TXT file.
  2. Exclusion file Many output data streams have fields which are known to vary. Date and time are the most frequently encountered. Study the existing exclusion file called cics\seq\SEQEXCL.TXT. You can create your own exclusion file, any name will do, just change the SET SEQEXC= line in Z390CMPG to your path/filename. If you change your exclusion file or create a new one, just rerun Z390CMPG to see the new results.

Abends

Z390COMP may abend with code U900.

This error is caused by a structural mismatch between SEQO0001.TXT and the comparator files SEQCnnnn. The output file SEQCOMP.TXT will contain an error message and a full dump of both files.

Before reporting these as errors, please check the following: 1. Are all the SEQI and SEQC files in sequence ? 2. Has a simulation run been done using the SEQI files (SEQ_TERM=YES) ? 3. Have any of the transactions changed since the last run of Z390SEQ for those transactions ?