| Library Manager | Integrated Preprocessor Interface | |
COBOL recognizes various devices, either implicitly or explicitly. This chapter describes the COBOL aspects of the devices as well as their operating system dependent aspects. It describes how they can be configured for use and how they can then be accessed from COBOL.
The COBOL language recognizes various logical devices and the run-time system (RTS) automatically maps them onto suitable physical devices. For files, you can override the automatic mapping by specifying a filename that is recognized as a device by either the run-time system or the operating system. Such filenames are operating system dependent and you should not use them if you require your program to be portable.
The COBOL language implicitly recognizes four categories of logical device:
COBOL files are typically mapped onto the file system supported by the operating system but can be mapped onto other devices or functions such as a physical printer, a print spooler, named pipes, logical devices or device drivers. The run-time system may recognize a particular name or may find out the type of file from the operating system and as a result direct the file to a special logical or physical device.
COBOL assumes a standard input device for a simple unformatted ACCEPT statement and assumes a standard output device for a simple unformatted DISPLAY or for a STOP literal statement. These two standard logical devices can be mapped directly to the operator console or indirectly via the operating system's standard input and output devices.
COBOL ACCEPT and DISPLAY statements can also handle full screen, non-scrolling forms which the COBOL run-time system maps onto the operator's physical or logical terminal device.
COBOL can identify logical device-dependent functions by specifying a function-name in the Configuration Section of your source program (see The Special Names Paragraph in your Language Reference). These are mapped onto suitable operating system facilities.
The following sections detail the use of both logical and physical devices.
COBOL files are typically mapped onto the file system supported by the operating system which hides any fixed or exchangeable media devices from the COBOL system (see your Programmer's Guide to File Handling).
Alternatively, the COBOL files can be mapped in other ways by using:
In all cases, if a COBOL file is mapped to something other than a file held on the standard file system, the COBOL program must adhere to any restrictions implied by using the special device. For example, a printer should not be used for input, a magnetic tape device should not be used for indexed files or random file access, and a named pipe should not use record locking syntax.
Table 14-1 shows the special names recognized by the COBOL run-time system for various operating systems.
The 16-bit run-time system is not case sensitive for device names and also allows the listed device-names to optionally include a trailing colon. The 32-bit run-time system is case-sensitive for device-names.
You should not attempt to access a file held on the file system with a filename that matches a special device-name recognized by the COBOL system.
Table 14-1: COBOL Special Device Names
| Device name | DOS, Windows & OS/2 | UNIX | Implied operating system device | |
| 16-bit | 32-bit | 32-bit | ||
| :CI: :CI RDR stdin |
Y Y Y |
Y Y Y Y |
Y Y |
Standard input stream |
| :CO: :CO stdout |
Y Y |
Y Y Y |
Y Y |
Standard output stream |
| PUN | Y | Y | Standard auxiliary stream | |
| CON: con: CON |
Y Y Y |
Y Y Y |
Standard input or output stream depending on the context of use | |
| :CE: ERR: err: ERR stderr |
Y Y Y |
Y Y Y Y Y |
Y Y |
Standard error stream or if not available standard output stream |
| :BB NUL |
Y Y |
Y Y |
Signifies output to be discarded | |
| :LP LPT LPT1 LST PRN |
Y Y Y Y Y |
Y Y Y Y Y |
First parallel printer device | |
| LPT2 LPT3 |
Y Y |
Y Y |
Second parallel printer device Third parallel printer device |
|
Table 14-2 gives examples of the special names typically recognized by the operating system in the environments shown. See your operating system documentation for an exhaustive list of such devices.
Table 14-2: Operating System Special Device Names
| Filename | DOS, Windows & OS/2 | UNIX | Facility provided by operating system |
|---|---|---|---|
| AUX: | Y | First asynchronous communications port | |
| COM1: | Y | First asynchronous communications port | |
| COM2: | Y | Second asynchronous communications port | |
| /dev/null | Y | Device that discards output | |
| /dev/floppy | Y | Floppy disk drive | |
| /dev/cart0 | Y | Cartridge tape drive |
In addition, the operating system can identify any filename with a special type of file such as a named pipe.
UNIX:
The filenames used for devices such as the floppy disk or tape cartridge
drives vary between versions of UNIX and sometimes even between different
installations of the same version. The typical examples shown above are
given only as an illustration.
DOS, Windows and OS/2:
DOS, Windows and OS/2 support parallel printers and serial printers.
Instructions on configuring DOS and OS/2 to redirect parallel printer
output to the Asynchronous Communications Adapter are given in the
operating system manuals under the MODE command. Windows does not have a
command-line. It is not, therefore, possible to configure Windows to
redirect parallel printer output to the Asynchronous Communications
Adapter.
A portable program should not attempt to access a file held on the filesystem with a filename that matches a special device name recognized by any other operating system.
The FILE-CONTROL paragraph names each file and enables specification of other file-related information, some of which is device-dependent. This is shown in Table 14-3.
Table 14-3: COBOL Special Device Clauses
| Filename
|
Facility provided by operating system
|
|---|---|
| LINE ADVANCING | Printer-destined file |
| MULTIPLE REEL | File that might extend over more than one unit |
| MULTIPLE UNIT | File that might extend over more than one unit |
| DISK | Phrase is documentary only |
| KEYBOARD | Line sequential organization, default filename :CI: |
| DISPLAY | Line sequential organization, default filename :CO: |
| PRINTER | Printer-destined file, default filename LPT1 |
| PRINTER-1 | Printer-destined file, default filename LPT2 |
LINE ADVANCING specifies that the file is destined for a printer and that the output format is a standard operating system independent printer format. See the chapter File Structures in your Programmer's Guide to File Handling for further details. Any WRITE statement referencing the file without a BEFORE or AFTER phrase automatically acts as if an AFTER 1 phrase had been specified. See the section The WRITE Statement in your Language Reference for further details.
MULTIPLE REEL and MULTIPLE UNIT are equivalent and specify that files might extend over more than one unit of media appropriate to the device. For example a floppy disk or tape cartridge. See your Programmer's Guide to File Handling for further details.
DISK is purely documentary and has no effect.
KEYBOARD specifies that the standard input device is to be treated as a file of records with line sequential file organization. If no explicit filename is specified a filename of :CI: is assumed, the standard input device.
DISPLAY specifies that the standard output device is to be treated as a file of records with line sequential file organization. If no explicit filename is specified a filename of :CO: is assumed, the standard output device.
PRINTER and PRINTER-1 are equivalent to specifying LINE ADVANCING and in addition, if no explicit filename is specified, a filename of LPT1 or LPT2 is assumed respectively. The files get mapped to the first or second parallel printer ports respectively when the program is run in the DOS, Windows or OS/2 environment but get mapped to a disk file named LPT1 or LPT2 respectively in the current directory when run under UNIX.
This COBOL system provides for three special types of stream of messages, one for input and two for output; known as standard input, standard output and standard error respectively. These message streams can be accessed in a variety of ways from COBOL, via simple ACCEPT, DISPLAY or STOP literal statements or by normal file operations on files whose filename identifies the appropriate special device name (see the earlier section COBOL Special Device-names).
UNIX:
The UNIX operating system supports standard input, output and error as
special devices or files and the COBOL streams are directly mapped to
them. The operating system then allows these special files to be
redirected in various ways but directs them to the terminal by default.
DOS and OS/2:
The DOS and OS/2 operating systems provide support for standard input and
output. If the +S5 run-time switch is set the COBOL streams are directly
mapped to them. OS/2 also supports standard error. The operating system
enables these special files to be redirected in various ways but directs
them to the terminal by default. Such operating system support incurs
large performance overheads, so the +S5 switch is set off by default
causing the run-time system to redirect the COBOL streams to the terminal.
Thus, by default, they cannot be redirected. Standard error is not
supported on DOS and so the file can never be redirected; the run-time
system always directs it to the terminal. For information on run-time
switches, see the chapter Running Applications in your Object
COBOL User Guide.
All components of this COBOL system, including the Compiler and run-time system, make use of the standard input, output and error streams where appropriate. Note in particular that normal output and error output are logically distinguished and where the operating system allows, they can be redirected individually.
The COBOL system allows COBOL sequential or line-sequential files that have been specified with disk-file names to be redirected to or from the standard input, output or error devices. See your Programmer's Guide to File Handling for details of the External File-Mapper (Mfextmap).
The following program, demo.cbl, reads a line from standard input and writes a line to each of standard output and standard error. Typical command lines follow that run the program and redirect the standard input from demo.in, the standard output to demo.out, and the standard error to demo.err. The file demo.in is assumed to contain "Redirected input!". Note that the operating system carries out the redirection and the results are not under the control of the COBOL system.
working-storage section.
01 tmp pic x(20).
procedure division.
accept tmp from sysin.
display "Message stdout is: " tmp upon sysout
display "This is a message to stderr" upon syserr.
Under UNIX, if you run the command:
cobrun demo <demo.in >demo.out 2>demo.err
then demo.out contains "Message to stdout is: Redirected input!", and demo.err contains "This is a message to stderr".
Under OS/2, if you run the command:
run demo <demo.in >demo.out 2>demo.err
then demo.out contains "Message to stdout is: Redirected input!", and demo.err contains "This is a message to stderr".
Under DOS, if you run the command:
run demo <demo.in >demo.out 2>demo.err
then demo.out contains the lines: "Redirected input!" and "Message to stdout is: Redirected input!"
A COBOL program can access a terminal device in one of two ways using the ACCEPT or DISPLAY statements:
The COBOL system takes no special action when treating the terminal as a CONSOLE device, relying on the standard operating system support to handle the terminal.
For formatted screen I-O, the COBOL system has to take action at two levels: the logical level and the physical level. The Adis module translates the high-level COBOL requirements into logical, low-level, terminal-independent operations. The run-time system translates these logical operations into the terminal-dependent instructions required to drive the terminal as well as translating any terminal-dependent response into a logical form before passing it back to the Adis module.
DOS, Windows and OS/2:
DOS, Windows and OS/2 run in a fairly standardized hardware environment
and the software environment further standardizes the terminal interface.
The run-time system needs no tailoring for handling any terminal. Some
terminal characteristics, such of the number of lines on the screen, can
be configured.
UNIX:
A UNIX system might have virtually any type of terminal connected. The
run-time system task of translating between the Adis terminal-independent
operations and the physical character strings and escape sequences used by
the terminal device is performed by a separate module, libscreen. The
libscreen module is a part of the COBOL system but it uses the standard
UNIX method for handling a terminal: the environment variable TERM
contains the name of the terminal type and the details for that terminal
type are held in the UNIX terminfo system database. The run-time
system requires that terminfo holds a minimum set of details for
the terminal otherwise it will give a run-time error. See the chapter Terminfo
Database and Terminal Devices in your COBOL System Reference
for details on specifying and using your terminals capabilities with your
COBOL system.
The libscreen module drives the terminal via the standard UNIX input and output devices. Terminal I-O can be redirected but with the restriction that you must not redirect standard input from a file unless it represents a terminal device. So, for example, the following is legal:
cobrun prog < ` tty ` > ` tty `
whereas redirecting the input from an ordinary file or /etc/null is not legal and could result in a run-time error. If you try the above example, be sure to use the correct apostrophe (`) rather than the similar but incorrect one (').
The COBOL Compiler recognizes various function-names in the Special-Names paragraph (see your Language Reference section The Special-Names Paragraph) and allows you to reference them in the Procedure Division using the associated mnemonic-name. Different COBOL dialects recognize different sets of function-names. The following table lists all the function-names recognized by your Compiler for the various COBOL dialects, together with an indication of the meaning of the function-name and the COBOL statement in which it may be referenced. The letter Y indicates that the function-name is recognized for the given dialect, the letter U indicates that it is recognized by your compiler and the mainframe compiler but that it is not a documented mainframe function-name. A blank indicates that the function-name is not recognized for that COBOL dialect.
| Function-name | Meaning | Statements in which function can be used | COBOL Dialect | ||||
|---|---|---|---|---|---|---|---|
| MF | XOPEN | OSVS | VSC2 | ||||
| 2 | 3 | ||||||
| COMMAND- LINE | The line of system commands that invoked the main program Text to substitute for the system command line | ACCEPT and DISPLAY | Y | ||||
| PRINTER | System logical printer | DISPLAY | Y | ||||
| TAB | Skip to vertical tabulation position | WRITE | Y | ||||
| ARGUMENT- NUMBER |
Number of component of COMMAND-LINE | ACCEPT and DISPLAY | Y | Y | |||
| ARGUMENT- VALUE |
Value of component of COMMAND-LINE | ACCEPT | Y | Y | |||
| ENVIRONMENT- NAME |
Name of environment variable | DISPLAY | Y | Y | |||
| ENVIRONMENT- VALUE |
Value associated with environment variable | ACCEPT and DISPLAY | Y | Y | |||
| SYSERR | System logical error device | DISPLAY | Y | Y | |||
| SYSIN | System logical input device | ACCEPT | Y | Y | Y | Y | Y |
| SYSIPT | System logical input device | ACCEPT | Y | U | U | Y | |
| SYSOUT | System logical output device | DISPLAY | Y | Y | Y | Y | Y |
| SYSLIST | System logical output device | DISPLAY | Y | Y | |||
| SYSLST | System logical output device | DISPLAY | Y | U | U | Y | |
| SYSPCH | System logical output device | DISPLAY | Y | U | U | Y | |
| SYSPUNCH | System logical output device | DISPLAY | Y | U | Y | Y | |
| CONSOLE | System logical I-O device | ACCEPT and DISPLAY | Y | Y | Y | Y | |
| C01 | Skip to printer channel 1 | WRITE | Y | Y | Y | Y | |
| C02 through C12 | Skip to printer channel 2 through 12 respectively | WRITE | Y | Y | Y | Y | |
| S01 through S02 | Select punch pocket | WRITE | Y | Y | Y | Y | |
| S03 through S05 | Select punch pocket | WRITE | Y | U | Y | ||
| CSP | Suppress spacing | WRITE | Y | Y | Y | Y | |
| One-character non-numeric literal | Report writer code | CODE clause | Y | Y | |||
COMMAND-LINE provides the standard way of accessing a COBOL application command line. See your Language Reference sections The ACCEPT Statement and The DISPLAY Statement for details.
ARGUMENT-NUMBER and ARGUMENT-VALUE provide access to the command line using the method specified by X/Open. See your Language Reference sections The ACCEPT Statement and The DISPLAY Statement for details.
ENVIRONMENT-NAME and ENVIRONMENT-VALUE provide access to environment variables held by the operating system using the method specified by X/Open. See your Language Reference sections The ACCEPT Statement and The DISPLAY Statement for details.
FORMFEED and TAB provide vertical and horizontal positioning in a printer-destined LINE ADVANCING file using the WRITE statement with the ADVANCING phrase. See your Programmer's Guide to File Handling for details on the format of LINE ADVANCING files.
The PRINTER function-name provides source code compatibility for source code developed in mainframe environments. Micro Focus recommends that you do not use it unless absolutely necessary. It has no effect at run time except under the DOS and UNIX operating systems. This function-name must not be confused with the PRINTER clause to the SELECT statement in the Input-Output Section.
DOS:
The DISPLAY data-item UPON PRINTER statement causes the contents
of data-item to be directed to the first parallel printer device
LPT1.
UNIX:
The DISPLAY data-item UPON PRINTER statement writes the contents
of data-item as a single record to a print spooler process via a
pipe. Once the record has been written, the pipe is closed. By default,
the spooler that is run is lp but any alternative process can be
specified by using the COBPRINTER environment variable
. See the appendix Micro Focus Environment Variables in your
UNIX COBOL System Reference for details of COBPRINTER.
The system logical input, output and error devices are mapped to the COBOL special devices :CI:, :CO: and :CE: respectively.
The CONSOLE function-name causes the ACCEPT or DISPLAY statement to map the I-O to the COBOL special devices :CI: and :CO: for input and output respectively. This option cannot be used with the FROM CRT phrase or with a Screen Section item.
DOS, Windows and OS/2:
On the COBOL systems for DOS, Windows and OS/2, a WRITE statement that
references C01 through C12, S01 through S05 or CSP acts as if the AFTER 1
phrase had been specified.
UNIX:
On UNIX, your system emulates printer channels
C01 through C12 by line feeds and form feeds. If you want to write
to these channels you should set the COBLPFORM environment variable
to define the line numbers on the form. This must consist of a
series of numbers separated by colons as in the following example:
COBLPFORM=1:::::::::::60 export COBLPFORM
UNIX:
On UNIX, this sets channel 1 to line 1 (the beginning of the page) and
channel 12 to line 60. You can specify only a single line number for each
channel. Those channels which have line number zero, function-names
S01-S052, CSP, or are undefined, are set to line 1. See the appendix Micro
Focus Environment Variables in your UNIX COBOL System
Reference for further details of COBLPFORM.
Any WRITE BEFORE/AFTER PAGE statements cause positioning to be at line 1. Each line that is advanced increases the line number by one. A request to skip to a line number less than or equal to the current line causes a new page to begin. The appropriate number of line feeds are then generated.
Any WRITE BEFORE/AFTER TAB statements generate a form feed and cause any subsequent skips to a channel number to start a new page.
The value of the literal has no effect at run time.
Copyright © 1999 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names
used herein are protected by international law.
| Library Manager | Integrated Preprocessor Interface | |