03. Usage guide

Special note for uploading source files to a mainframe

If you want to run this on a mainframe system, do not upload the versions of ZUTZCPC, ZUTZCWS, and ZUTZCPD located in src/main/cobol. Special versions of these files have been tweaked to function properly on a mainframe, and they are located in directory upload.

Text files "should" upload just fine. The magic word "should" has proven to be unreliable in testing ZUTZCPC on a zOS system.

Specifically, the records have been padded to 80 characters, and the SELECT statements in ZUTZCPC have been changed from ORGANIZATION LINE SEQUENTIAL to ORGANIZATION SEQUENTIAL.

If you want to upload any of the sample programs to a mainframe, add their names to the Python program padder.py, located in the project root directory. Then run the bash script prepare to tweak the files as described above. The tweaked files will be written to the upload directory.

Environment variables

Edit the file envvars in the project root directory and set the values of environment variables to the correct paths depending on where you placed the project on your filesystem.

When running scripts from the project root directory (assuming bash), you can source the environment variable settings with

. envvars

If you use a different shell, adjust these instructions accordingly.

Directory structure (*nix and Windows)

README.md                     The project README file.
envvars                       Environment variable settings.
compile                       Bash script to compile a program.
run-ut                        Run the unit tests for a program.
run-examples                  Run all the unit test examples.
target/                       Destination directory (.so and executable).  
win/                          Windows-specific files.
  |
  +-- envvars.cmd             Command file to set environment variables.
  |
  +-- compile.cmd             Command file to compile a program.
  |
  +-- run-ut.cmd              Command file to run unit tests for a program.
src/
  |
  +-- main/
  |     |
  |     +-- cobol/            "Production" source code.
  |     |     |
  |     |     +-- copy/       "Production" copy library.
  |     |
  |     +-- resources/        "Production" resource files.
  |
  +-- test/  
        |
        +-- cobol/            Test source code.
        |     |
        |     +-- unit-tests/ Unit test copy files.
        |
        +-- resources/        Test config files & other resources.
  

Compile a program

The bash script compile wraps the cobc command and "knows" the project directory structure. Output from compile --help

GNU COBOL compile script
Version 0.2.0 Jan 5 2015
Usage: compile [options] program-name-without-suffix [subprogram-names]
    -c | --clean  Delete the existing executable before compiling
    -h | --help     Display usage help (this text) and exit
    -t | --test     Source is in the project test directory (not main)
    -s | --subprogram Generate a callable subprogram (not an executable)

The compile script looks in src/main/cobol/xxx for source code, copybooks, and resource files. Object files are written to target/. Program name is case-sensitive. Omit the .CBL suffix from the program name.

Examples:

compile MYPROGRAM
compile -s MYSUBPRG

Run unit tests

The bash script run-ut executes the unit tests for a given Cobol program. Output from run-ut --help

Run unit test cases for a Cobol program
Usage: run-ut [options]
           config-file-name
           program-name-without-suffix
           unit-test-copy-file-name
           [test-driver-program-name]
    -d | --debug      Echo debugging information
    -h | --help       Display usage help (this text) and exit
    -s | --subprogram Compile the program under test as a subprogram
                      (requires test-driver-program-name)
    -v | --version Display the version of the unit test framework

Examples:

run-ut PROG1C PROG1 PROG1T
run-ut -s PROG2C PROG2 PROG2T PROG2DRV

Test configuration file

The precompiler looks in src/test/resources to find the configuration file referenced in the first argument to the run-ut script. The contents of the configuration file are:

First line: The name of a WORKING-STORAGE copybook containing fields used by the unit tests. This is normally ZUTZCWS but you can create a custom copybook if you need to include additional WORKING-STORAGE items to support your unit test cases.

Second line: (Deprecated) The name of the file containing the unit test cases. The current version ignores this value. Instead, the unit test case filename is specified as a command-line argument to run-ut.

Testing a subprogram

To test a subprogram, you must write a main program (driver) to call it. Then pass the -s or --subprogram command-line option to the run-ut script, and pass the name of the driver as the fourth command-line argument to run-ut.

run-ut --subprogram SUBPROGC SUBPROG SUBPROGT SUBPROGD

Driver program for the SUBPROG sample program:

       IDENTIFICATION DIVISION.
       PROGRAM-ID. SUBPROGD.
       ENVIRONMENT DIVISION.
       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01  WS-ARGUMENTS.
           05  WS-ARG-1      PIC X(80).
           05  WS-ARG-2      PIC X(80).
       PROCEDURE DIVISION.
           MOVE 'Argument 1 initial value' TO WS-ARG-1
           MOVE 'Argument 2 initial value' TO WS-ARG-2
           CALL 'SUBPROG' USING
               BY REFERENCE WS-ARGUMENTS
           END-CALL    
           .
       9999-END.
           .

CICS application programs are called by CICS. Test CICS application programs the same way as you would test any other subprogram, passing DFHEIBLK and DFHCOMMAREA as arguments.

run-ut -s CICSDEMC CICSDEMO CICSDEMT CICSDEMD

Driver for the CICSDEMO sample program:

       IDENTIFICATION DIVISION.
       PROGRAM-ID. CICSDRIV.
       ENVIRONMENT DIVISION.
       DATA DIVISION.
       WORKING-STORAGE SECTION.
           COPY DFHEIBLK.
       01  DFHCOMMAREA PIC X VALUE SPACES.
       PROCEDURE DIVISION.
           CALL 'CICSDEMO' USING
               BY REFERENCE DFHEIBLK
               BY REFERENCE DFHCOMMAREA
           END-CALL    
           .
       9999-END.
           .