using filestatus

7/28/2019 Using Filestatus

1/4

Using File Status

What is File Status?

File status is a two-byte code that indicates how a file operation completed; either successfully, or withsome form of error. If an error occurs, the file status indicates the reason for the error. File status is a dataitem which you define in your program. Defining a file status data item is optional. If a file status data itemis not declared and a file error occurs, the COBOL run-time system displays an error message and abortsyour program.

If you have a file status item defined for a file, then after every input/output operation on the file (that is,OPEN, CLOSE, READ, WRITE, REWRITE, START and DELETE) the run-time system updates it toindicate how the operation completed. After each operation, it is your responsibility to ensure that yourprogram checks the file status to see if the operation completed satisfactorily.

For example, when your program is writing to disk, there might not be enough disk space to complete theWRITE operation. If you have not defined a file status item and you run out of disk space, the run-timesystem displays an error number and aborts the program. If you have a file status item defined (for the fileyou are writing), it is updated and the program continues to run. The program can then check the file status,determine from it that the disk is full, and take the appropriate action.

Note: If you declare a USE procedure (in the Declarative section of your program) to handle I/O errors, theprocedure is only executed if a file status is also defined for the file. The file status item is updated beforethe USE procedure is executed. See theLanguage Referencefor more information about Declaratives andUSE procedures.

Defining a File Status

Each file in a program can have a file status item attached to it by specifying the FILE STATUS clause inits file-control entry. A separate item can be used for each file's file status, or a single item can be used forthe file status of several files. The data item to be used for the file status of a file is indicated in theSELECT clause of the File-Control paragraph for that file. The data item used for a file status is defined inthe Working-Storage or Linkage Section.

For all file status conventions, except extended file status codes, the data item is defined as twoalphanumeric characters (that is PIC XX). Extended file status codes use the second byte as a binary(COMP-X) item.

The first byte of the file status data item is known as status key 1 and indicates one of the followingconditions:


2/4

Value Condition

0 Successful operation

1 AT END

2 Invalid Key

3 Permanent Error4 Logic Error (improper sequence of I/O operations)

9 COBOL run-time system error message

If the first byte of the file status data item is other than 9, the second byte (known as status key 2) should betreated as alphanumeric. The values and meanings of status key 2 are listed in the chapterFile Status Code

Tables.

If the first byte of the file status data item is "9", the second byte is a binary field containing a Micro Focusdefined RTS error code. These messages are listed and explained in yourError Messages.

Example

sel ect i n- f i l eassi gn t o. . . .. . .

f i l e s tatus i s ws - f i l e- s tatus .dat a di vi si on.f i l e sect i on.f d i n- f i l e. . . .

. . .wor ki ng- st or age secti on.01 ws- f i l e- st at us pi c xx.

Displaying File StatusIf you want to display the second byte of an extended file status code with its correct decimal value, youneed to redefine the file status data item to avoid truncation.

The example program that follows illustrates one method of retrieving the value of the second byte of thefile status for display purposes. Note how truncation has been avoided by redefining the second byte of thefile status data item as PIC 99 COMP-X.

000010 envi r onment di vi si on.000020 i nput - out put sect i on.000030 f i l e- cont r ol .000040 sel ect f i l e1

000050 assi gn "t st . f i l "000060 st at us i s f i l e1- st at .000070 data di vi si on.000080 f i l e sect i on.000090 f d f i l e1.000100 01 f 1- r ec pi c x( 80)000110 worki ng- st orage sect i on.000120 01 f i l e1- st at .000130 03 s1 pi c x.000140 03 s2 pi c x.


3/4

000150 03 st at - bi n r edef i nes s2 pi c 9( 2) comp- x.000160 01 di spl y- st at .000170 03 s1- di spl pi c x.000180 03 f i l l er pi c x(3).000190 03 s2- di spl pi c pi c zz9.000200 pr ocedure di vi si on.000210 st ar t - t est .000220 open i nput f i l e1000230 move s1 t o s1- di spl000240 i f s1 not = 9000250 move s2 t o s2- di spl pi c000260 el se000270 move st at - bi n t o s2- di spl pi c000280 end- i f000290 di spl ay di spl y- st at000300 st op r un.

If you have not specified a file status item in the SELECT clause of your program, file errors with a firstbyte value of 9 result in display of a run-time error.

Checking File Status

The example below demonstrates how to check file status. First,st at us- key- 1 is interrogated; then, if

more information about the error is required,st at us- key- 2 is interrogated. The codes that are checkedhere represent some of the more common error codes.

Example

sel ect r ecseq assi gn t o "r ecseq. dat "f i l e s tat us i s ws - f i l e- s tatusor gani zat i on i s r ecor d sequent i al .

f i l e sect i on.f d r ecseqr ecord cont ai ns 80 charact ers.

01 r ecseq- f d- r ecor d pi c x(80) .worki ng- st or age secti on.01 ws- f i l e- st at us.

05 st at us- key- 1 pi c x.05 st at us- key- 2 pi c x.05 bi nar y- st at us r edef i nes st at us- key- 2

pi c 99 comp- x.pr ocedur e di vi si on.

. . .per f or m check- st at us.

. . .

check- st at us.eval uat e st at us- key- 1when "0" next sent encewhen "1" di spl ay "end of f i l e r eached"

per f or m check- eof - st at uswhen "2" di spl ay "i nval i d key"

per f or m check- i nv- key- st at uswhen "3" di spl ay "per manent err or "

per f or m check- per m- er r - st at us


4/4

when "4" di spl ay "l ogi c er r or "when "9" di spl ay "r un- t i me- system er r or "

per f orm check- mf - er r or- messageend- eval uat e.

check- eof - st at us.i f st at us- key- 2 = "0"

di spl ay "no next l ogi cal r ecor d"end- i f .

check- i nv- key- st at us.eval uat e st at us- key- 2when "2" di spl ay "at t empt t o wr i t e dup key"when "3" di spl ay "no recor d f ound"

end- eval uat e.

check- per m- er r - st at us.i f st at us- key- 2 = "5"

di spl ay "f i l e not f ound"end- i f .

check- mf - err or - message.eval uat e bi nar y- st at uswhen 002 di spl ay " f i l e not open"when 007 di spl ay "di sk space exhaust ed"when 013 di spl ay "f i l e not f ound"when 024 di spl ay "di sk er r or "when 065 di spl ay " f i l e l ocked "when 068 di spl ay " r ecor d l ocked "when 039 di spl ay "r ecord i nconsi st ent "when 146 di spl ay "no curr ent r ecor d "when 180 di spl ay " f i l e mal f ormed "when 208 di spl ay "net work er r or "when 213 di spl ay " t oo many l ocks "when other di spl ay "not er r or st at us "

di spl ay bi nar y- st at usend- eval uat e.

In the paragraphcheck- st at us, the value ofst at us- key- 1 is evaluated in order to determine

whetherst at us- key- 2 should also be interrogated.

Common run-time system errors are listed in the EVALUATE statement in the paragraphcheck- mf -

err or - message.

Of course, in your own program, you need to process these errors, not simply display them.

using filestatus

Documents