HP 3000 Manuals HP 3000 Manuals
Operation
Each file in a program can have a file status item attached to it. A
separate item can be used for each file's file status, or a single item
can be used for the file status of several files. The data item to be
used for the file status of a file is indicated in the SELECT clause of
the FILE-CONTROL section of that file. The data item used for a file
status is defined in the Working-Storage or Linkage section of that file.
It is the programmer's responsibility to trap any error that occurs on an
I/O operation for the associated file by testing the file status item and
taking the appropriate action should you receive an error.
A value of 0 is placed in the first byte of this data item if an I/O
operation is successfully executed. A value of 1, 2, 3 or 4 in the first
byte indicates that an error has occurred during an I/O operation on the
file. These errors are fully defined by the ANSI standard and are
described in the Language Reference. A value of 9 in the first byte
indicates that an error has occurred during an I/O operation on the file.
In this case, the associated run-time error number is placed in the
second byte in binary (COMP) format. A full description of such run-time
errors can be found in the Error Messages manual, together with any
corrective actions you can make to recover from the condition which
caused the error.
Alternatively, you can map those errors with a value of 9 in the first
byte onto an alternate set of error numbers; by default these are the
error numbers returned by RM/COBOL for status 9 error conditions. See
the section "Alternate File Status Table" later in this chapter for
full details on how to select this mapping.
If you want to display this status with its correct decimal value,
careful redefinition of data-items is required in order to avoid
truncation of the value. This is because the facility that enables the
storage of a non-numeric value greater than decimal 99 as a hexadecimal
value is an extension to the ANSI COBOL standard X3.23 (1974) but the
rules for moving or manipulating such data are restricted by the standard
to a maximum of decimal 99. Alternatively, you can redefine the second
status byte as a PIC 99 COMP-X item.
The example program that follows illustrates one method of retrieving the
values of the second byte of the file status for display purposes. Note
how truncation has been avoided by redefining the two status bytes as one
numeric data item (length two bytes) capable of storing up to four
decimal digits.
000010 environment division.
000020 input-output section.
000030 file-control.
000040 select file1
000050 assign "tst.fil"
000060 status is file1-stat
000070 data division.
000080 file section.
000090 fd file1
000100 01 f1-rec pic x(80)
000110 working-storage section.
000120 01 file1-stat.
000130 03 s1 pic x.
000140 03 s2 pic x.
000150 01 stat-bin redefines file1-stat pic 9(4) comp.
000160 01 disply-stat.
000170 03 s1-displ pic x.
000180 03 filler pic x(3).
000190 03 s2-displpic pic zz9.
000200 procedure division.
000210 start-test.
000220 open input file1
000230 move s1 to s1-displ
000240 if s1 not= 9
000250 move s2 to s2-displpic
000260 else
000270 move low-values to s1
000280 move stat-bin to s2-displpic
000290 end if
000300 display disply-stat
000310 stop run.
If you have not specified file status item in the SELECT clause of the
FILE-CONTROL paragraph in a program, file errors with a first byte value
of 9 will result in a run-time error being output.
Alternate File Status Table
This COBOL system supplies a C source file, filestat.c, which contains
tables of the file status values defined by ANSI '74 and ANSI '85
standards. We do not recommend that you alter these tables in any way.
However, this file also contains a table giving an alternate set of file
status values for those input-output error conditions which return a
value of 9 in the first byte. You can alter this table if you want. By
default, this alternate set of error numbers is output by RM/COBOL. If
you want this COBOL system to output error messages from this list,
rather than from its standard list of run-time error messages as defined
in the Error Messages manual, you must either:
* compile your program with the RM directive set. See Chapter 3
, Compiling and Appendix G , Directives for
Compiler/Generator for further information on this option.
or:
* specify the +Q file status error switch when you run your program.
See Appendix E , Descriptions of Run-Time Switches for further
information on this run-time switch.
If you want to alter the default table of alternate file status item
values to a set of values which conform to the statuses returned in the
COBOL dialect of your choice by editing filestat.c in $COBDIR/src, you
must index the table using the second byte of any status 9 items. The
table entry then contains the new value for that file status in Binary
Coded Decimal (BCD) format. Any undefined or unrecognized status values
are mapped onto status 30 "permanent I-O error".
Once you have altered the table, you must rebuild the RTS so that it uses
your altered version of filestat.c rather than the original version. You
can either do this globally or individually for each RTS. The following
sections show you how to do this.
Globally Altering File Status Values.
To globally rebuild the RTS so that it uses your altered version of
filestat.c when outputting file status error messages, you must perform
the following:
1. Compile your new version of the module by entering the command:
cc -c filestat.c
As any further run-time systems that you build will use the new
version of filestat.c, we recommend that you keep a copy of the
original version.
2. Replace filestat.o in the COBOL library by entering:
ar rv $COBDIR/coblib/libcobol.a filestat.o
3. Rebuild the RTS using the cob command. For example:
cd $COBDIR
cob -xvo rts32 -e ""
See Chapter 2 , COBOL System Interface for further details of the cob
command.
Altering File Status Values for Individual Run-Time Systems.
You can use the cob command to rebuild a single RTS so that it uses your
altered version of filestat.c when outputting file status error messages.
If you have not already compiled filestat.c, you enter the command:
cob -o rts32 filestat.c -e ""
If you have compiled filestat.c, you enter:
cob -o rts32 filestat.o -e ""
As usual, you can include any COBOL or C programs or other object modules
in the command line.
See Chapter 2 , COBOL System Interface for a full description of the
cob command.
USE Procedures
If you declare USE procedures in the DECLARATIVES SECTION to handle
input-output errors, these procedures are only executed if a file status
data item is also declared.