-
Notifications
You must be signed in to change notification settings - Fork 36
03. Usage guide
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.
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.
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.
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
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
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
.
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.
.