ACCEPT, DISPLAY and Console I/O

The figure contrasts the two environments. In GnuCOBOL the program talks to the process’s standard streams, its arguments and its environment, and to the terminal for screens. On z/OS the same statements are bound to data definition (DD) statements of the job, and the program’s arguments arrive as the PARM string.

The format is DISPLAY followed by one or more literals or identifiers, an optional UPON device and an optional WITH NO ADVANCING. The operands are sent to the device left to right as one record, and when the statement ends the device moves to the start of the next line unless WITH NO ADVANCING was written. In GnuCOBOL, ON EXCEPTION, NOT ON EXCEPTION and END-DISPLAY are also accepted. A figurative constant operand is shown once, not repeated. The two programs below use the member record layout from the copybook MEMBREC and show the UPON devices.

Standard output and standard error are separate streams. Running the program and keeping only standard output (./display1 2>/dev/null) prints:

Keeping only standard error (./display1 2>&1 >/dev/null) prints the one line sent UPON SYSERR:

ALL "-" shows a single hyphen, as the IBM Language Reference says for a figurative constant in DISPLAY. UPON CONSOLE, SYSOUT and a mnemonic name for CONSOLE all land on standard output in GnuCOBOL; only SYSERR and STDERR use standard error. The numeric field MEMBER-FINES is shown with its sign and decimal point, which is the next topic.

Source: GnuCOBOL Programmer’s Guide, DISPLAY UPON device and Enterprise COBOL for z/OS 6.5 Language Reference, DISPLAY statement

ACCEPT identifier reads one piece of input into a data item; with no FROM phrase it reads the system input device, and FROM selects SYSIN or SYSIPT (the system logical input unit), CONSOLE, or in GnuCOBOL also STDIN. IBM’s Language Reference states that there is no editing and no error checking of the incoming data. The program below reads one loan transaction from standard input, with the prompts written by DISPLAY ... WITH NO ADVANCING; SYSIN IS TRANS-INPUT in SPECIAL-NAMES gives the device a mnemonic name that ACCEPT can use.

Because standard input is a pipe, nothing is echoed, so the three prompts run together on one line. Run as printf 'O\n000100\n1\n' | ./accept1:

Run with -std=ibm and the input R, 000101, 000002, the program compiles with no warnings and prints:

If the input ends early, the remaining ACCEPT statements get no data. In GnuCOBOL 3.2.0 a field that cannot be filled is cleared (spaces for an alphanumeric item, zero for a numeric one). Run as printf 'O\n' | ./accept1, the second and third prompts get nothing:

Enterprise COBOL behaves differently: if end of file is reached before any data has moved to the receiving area, the receiving area keeps its previous contents. Test for end of input explicitly instead of relying on either behaviour; GnuCOBOL raises the exception condition, so ON EXCEPTION on the ACCEPT can detect it, as the next program shows.

Source: GnuCOBOL Programmer’s Guide, ACCEPT FROM CONSOLE and Enterprise COBOL for z/OS 6.5 Language Reference (PDF), ACCEPT statement

GnuCOBOL gives access to the process’s arguments and environment through special device names. ACCEPT n FROM ARGUMENT-NUMBER returns the number of arguments; DISPLAY k UPON ARGUMENT-NUMBER chooses which one the next ACCEPT x FROM ARGUMENT-VALUE returns; ACCEPT x FROM COMMAND-LINE returns all arguments as one string. Environment variables are read with ACCEPT x FROM ENVIRONMENT "NAME", or in two steps with DISPLAY "NAME" UPON ENVIRONMENT-NAME followed by ACCEPT x FROM ENVIRONMENT-VALUE, and set with DISPLAY "NAME" UPON ENVIRONMENT-NAME followed by DISPLAY "value" UPON ENVIRONMENT-VALUE. ON EXCEPTION detects a variable that does not exist. The program below prints its arguments and reads two variables.

Run as ./args1 20261020 "A B" extra with neither variable set:

Run with CIRC_RUN_DATE=20261020 CIRC_LIBRARY="North Branch" ./args1 and no arguments:

Source: GnuCOBOL Programmer’s Guide, ACCEPT FROM COMMAND-LINE, ACCEPT FROM ENVIRONMENT and DISPLAY UPON ENVIRONMENT-NAME

The last line shows that DISPLAY ... UPON ENVIRONMENT-VALUE replaced the variable for the rest of the run. The change is visible to child processes started with CALL "SYSTEM" but not to the shell that started the program. The shell, not COBOL, expands wildcards in the arguments, so quote any argument that contains *.

Compiling the same program with -std=ibm works, because GnuCOBOL keeps these devices in that dialect, but -std=ibm-strict and -std=cobol85 reject them:

A batch program on z/OS gets its small inputs from three places: the PARM string on the EXEC statement, the in-stream SYSIN data set, and the environment of the step. Its console-style output goes to the data set named by the SYSOUT ddname, or by the OUTDD compiler option if that was set. The job below runs the nightly circulation program with the run date as PARM and a control card in SYSIN; the JCL is covered in JCL for COBOL Programmers and the options in Compiling, Linking and Language Environment.

Source: Enterprise COBOL for z/OS 6.5 Programming Guide (PDF), Displaying data on the system logical output device

This JCL is z/OS only (z/OS; not run here); it follows the shape of the SYSIN, SYSOUT and PARM examples in the IBM Programming Guide. The trailing slash separates the program argument from the Language Environment run-time options; IBM’s own example passes '95/' and the program receives parm-len=002. The parameter is an area that starts with a two-byte binary length followed by the characters, so the program describes it in the LINKAGE SECTION and names it in PROCEDURE DIVISION USING:

Source: Enterprise COBOL for z/OS 6.5 Programming Guide (PDF), Example: accessing main program parameters under z/OS

Enterprise COBOL passes the PARM as a halfword length followed by the string, which is exactly the shape that OS-PARM describes (use a two-byte binary item such as PIC S9(4) COMP, as IBM’s own example does). The program checks the length before it uses the data, because PARM may be absent or shorter than expected and the PARM-DATA bytes beyond PARM-LEN are not valid. It reads the control card with ACCEPT ... FROM SYSIN into an 80-byte item, the length of a card image, and writes with DISPLAY ... UPON SYSOUT. Anything wrong sets RETURN-CODE for the COND and IF tests of the following job steps.

The program syntax and logic can be run without a mainframe if a small driver builds the same two-byte-length parameter and calls the program, so the following driver does that. It is not how the job runs on z/OS (the system builds the parameter there), and the compile uses -std=ibm so that PIC S9(4) COMP is two bytes, as on z/OS.

Source: Enterprise COBOL for z/OS 6.5 Programming Guide (PDF), Accessing main program parameters under z/OS

Compiled with cobc -m -Wall -std=ibm circ010.cob, cobc -x -Wall -std=ibm parmdrv.cob and run with printf 'LIMIT 006\n' | ./parmdrv, with no warnings, the output is:

The first call received an eight-character date and the card LIMIT 006; the second received a five-character string and ended with return code 16. With the card LIMIT 6 (printf 'LIMIT 6\n' | ./parmdrv) the numeric test on columns 7 to 9 fails and the default limit 004 is kept:

Other ways to read the PARM are the Language Environment services CEE3PRM (a string up to 80 characters) and CEE3PR2 (string and its length). Under CBLOPTS(ON), the default, the string is program_arguments/runtime_options; for AMODE 64 CBLOPTS is not supported and the order is reversed. A program started from the z/OS UNIX shell, exec() or spawn() receives three parameters instead: an argument count, an array of pointers to the argument lengths and an array of pointers to the null-terminated arguments, the first of which is the name of the program.

Source: Enterprise COBOL for z/OS 6.5 Programming Guide (PDF), Accessing main program parameters under z/OS and Assigning input from a screen or file (ACCEPT)

GnuCOBOL adds statement forms for a text terminal that do not need a SCREEN SECTION: DISPLAY item AT LINE n COLUMN m and ACCEPT item AT LINE n COLUMN m, with a WITH list of attributes (BACKGROUND-COLOR, FOREGROUND-COLOR, HIGHLIGHT, LOWLIGHT, REVERSE-VIDEO, UNDERLINE, BLINK, BELL, BLANK LINE or SCREEN, ERASE EOL or EOS, AUTO, SECURE, REQUIRED, FULL, UPDATE, SIZE, TIMEOUT AFTER n) and ON EXCEPTION for keys that end the input. DISPLAY SPACE clears from the cursor to the end of the screen. ACCEPT OMITTED waits for a key and sets the status without storing data. The key that ended the input is returned in the CRT STATUS data item.

Source: GnuCOBOL Programmer’s Guide, ACCEPT screen-data-item

This program needs a real terminal (it uses curses), so it was compiled with cobc -x -Wall (no warnings) and then run under a pseudo-terminal (script) with TERM=xterm and scripted keystrokes, writing its result to standard error. Doing nothing for one second gives the time-out status, typing 123456 and Enter takes the normal path, and the F3 key (the xterm sequence ESC O R) ends the input with its function-key code:

CRT STATUS IS WS-KEY in SPECIAL-NAMES names a four-digit data item that receives one of the codes below after every screen ACCEPT. If the clause is not written, GnuCOBOL uses an implicit COB-CRT-STATUS item. The copybook screenio.cpy, supplied with the compiler, defines names for them (COB-SCR-F3 and so on) and for the eight colors (COB-COLOR-BLACK to COB-COLOR-WHITE); it is licensed under the GPL and is included with COPY screenio. rather than copied.

Page Up and Page Down end an ACCEPT only when the run-time variable COB_SCREEN_EXCEPTIONS has a non-blank value, and Esc also needs COB_SCREEN_ESC. COB_TIMEOUT_SCALE sets the unit of the TIMEOUT value. When a program shows a screen and then stops without an ACCEPT, COB_EXIT_WAIT (default on) makes the run-time wait for a key so that the screen is not wiped at once.

Source: GnuCOBOL Programmer’s Guide, ACCEPT screen-data-item and DISPLAY screen-data-item

The SCREEN SECTION is the last section of the Data Division. It describes whole screens as a hierarchy of screen items, and a single DISPLAY screen-name paints the screen while a single ACCEPT screen-name reads every input field on it. COBOL 2002 introduced it, and GnuCOBOL implements it for text terminals only (no graphics).

A screen item has a level number, an optional name, and clauses:

The synonyms in parentheses are interchangeable in GnuCOBOL. Level 01 constants, 66, 78 and 88 are also allowed in this section. The -fscreen-section-rules= compiler option selects whether the clause rules follow the GnuCOBOL (gc, the default), std, mf, acu, rm or xopen behaviour.

The program below is a checkout form for the Circulation scenario. CHECKOUT-SCREEN clears the screen and has two input fields (USING), one output field (FROM) that shows a message, and literals. The main loop shows the screen, reads it, and stops when CRT STATUS reports F3.

The program compiled with cobc -x -Wall with no warnings. It cannot run in a pipe: with standard input at end of file each ACCEPT returns at once, F3 never arrives, and the loop does not end (the container running it had to be stopped). It was therefore run under a pseudo-terminal (TERM=xterm, 10 rows by 40 columns) with the keystrokes 000102, Enter, Enter and F3. Because the captured output is a stream of terminal escape sequences, the final screen below was reconstructed from it by hand: Member id 000102 is highlighted in reverse video, and the red message Member 102 is suspended was set by the program after the first Enter. Pressing Enter on the empty required Member id field instead made the terminal beep and kept the cursor on the field.

Source: GnuCOBOL Programmer’s Guide, SCREEN SECTION and SPECIAL-NAMES

The messages in the table were produced by GnuCOBOL 3.2.0.