Displaying File Error Information

Several file system intrinsics are designed specifically for handling errors. If an I/O error occurs, most file system intrinsics return a condition code indicating this.

You use:	To obtain information about:
`FCHECK`	File system intrinsic error number
`FERRMSG`	File system intrinsic error message
`PRINTFILEINFO`	File information error display

FCHECK

The FCHECK intrinsic returns an error code that indicates the nature of a file system I/O error. A table of error codes appears in the MPE/iX Intrinsics Reference Manual (32650-90028), or you can use FERRMSG (described below) to display an error message.

FCHECK has five optional parameters. The filenum parameter indicates the file for which error information is to be returned. If you set this parameter to zero, FCHECK assumes you want information about the last failed FOPEN call. The error code is returned in the errorcode parameter.




	NOTE: Do not use `FCHECK` to determine error conditions of you last failed `HPFOPEN` intrinsic call. Error conditions associated with `HPFOPEN` are returned in the `HPFOPEN` `status` parameter. Instead, you can use the `HPERRMSG` intrinsic to return a message explaining the nature of an `HPFOPEN` intrinsic error or warning.

Three other parameters give additional information about file system errors. The tlog parameter returns the number of half-words read or written if an I/O error occurs. The blknum parameter gives the logical record count for a spool file, or the physical record count for any other type of file. The numrecs parameter returns the number of logical records in the bad block.

You must use this intrinsic prior to calling FERRMSG, since the error code returned by FCHECK is used as a parameter in the call to FERRMSG.

FERRMSG

This intrinsic is used following a call to FCHECK, to return an error message explaining the nature of a file system error. It has three required parameters: errorcode is the error number returned by FCHECK, msgbuf returns the error message, and msglgth returns the length of the error message returned in msgbuf.

This example shows a call to FCLOSE. If this returns a CCL condition, a call to FCHECK requests the error code; then FERRMSG returns the error message associated with this code:

   FCLOSE(FILENUM,1,0); 

     IF CCODE = CCL

     THEN BEGIN

          FCHECK(FILENUM,ERRNUM);          {Returns error number    }

          FERRMSG(ERRNUM,MESSAGE,LENGTH);  {Returns error message   } 

          PRINT(MESSAGE,-LENGTH,0);        {Prints error message to

                                             $STDLIST} 

               TERMINATE;                  {Terminate process       }

               END;

If the FCHECK code has no assigned meaning, the following message is returned:

   UNDEFINED ERROR errorcode

PRINTFILEINFO

This intrinsic prints a file information display on the job or session list device, $STDLIST. The information shown depends upon whether or not a file is opened when the error occurs. For files not yet opened, or for which the FOPEN intrinsic fails, the display shown in Figure 14-1.

Example 14-1. File Information Display, Unopened File

   +-F-I-L-E---I-N-F-O-R-M-A-T-I-O-N---D-I-S-P-L-A-Y+ 

   !  FILE NUMBER 5      IS UNDEFINED.              !   Line #1 

   !  ERROR NUMBER:  2    RESIDUE:  0       (WORDS) !   Line #2 

   !  BLOCK NUMBER:  0           NUMREC:  0         !   Line #3 

   +------------------------------------------------+

The lines in this display show the following information:

Line #	Meaning
1	Warns that no corresponding file is open.
2	`ERROR NUMBER` indicates the last `FOPEN` error for the calling program. `RESIDUE` is the number of words not transferred in an I/O request; since no such request applies here, this is zero.
3	In this form, the `BLOCK, NUMBER`, and `NUMREC` fields are always zero.

For files that are open when a CCG (EOF error) or CCL (irrecoverable file error) was returned, the file information display appears as shown in example 14-2.

Example 14-2. File Information Display, Opened File



   +-F-I-L-E---I-N-F-O-R-M-A-T-I-O-N---D-I-S-P-L-A-Y+ 

   !  FILE NAME IS TREEFILE.PSMG.LOZAR              !    Line #1 

   !  FOPTIONS:  NEW,ASCII,FORMAL,F,NOCCTL,FEQ,     !    Line #2 

   !             NOLABEL                            !    Line #3 

   !  AOPTIONS:  INPUT,NOMR,NOLOCK,DEF,BUF,NOMULTI, !    Line #4 

   !             WAIT,NOCOPY                        !    Line #5 

   !  DEVICE TYPE:  0      DEVICE SUBTYPE:  9       !    Line #6 

   !  LDEV:  2       DRT:  4        UNIT:  1        !    Line #7 

   !  RECORD SIZE:  256    BLOCK SIZE:  256 (BYTES) !    Line #8 

   !  EXTENT SIZE:  128    MAX EXTENTS:  8          !    Line #9 

   !  RECPTR:  0           RECLIMIT:   1023         !    Line #10 

   !  LOGCOUNT:  0             PHYSCOUNT:  0        !    Line #11 

   !  EOF AT:  0         LABEL ADDR:  %00201327630  !    Line #12 

   !  FILE CODE:  0    ID IS PAULA      ULABELS: 0  !    Line #13 

   !  PHYSICAL STATUS:  1000000000000001            !    Line #14 

   !  NUMBER WRITERS:  0    NUMBER READERS:  1      !    Line #15 

   !  ERROR NUMBER:  0       RESIDUE:  0            !    Line #16 

   !  BLOCK NUMBER:  0               NUMREC:  1     !    Line #17 

   +------------------------------------------------+

The lines on the above display show the information listed in Table 14-3 “PRINTFILEINFO Information”.

Table 14-3 PRINTFILEINFO Information

Line #	Meaning
1	The file name.
2,3	The `foptions` in effect.
4,5	The `aoptions` in effect.
6,7	The device type and subtype, logical device number, (LDEV), device reference table (DRT), and unit of the device on which the file resides. If the file is a spool file, the `ldev` is the virtual rather than the physical device.
8	The record and block size of the offending record, in bytes and words, as noted.
9	The size of the current extent and the maximum number of records in the file.
10	The current record pointer, and limit on number of records in the file.
11	The present count of logical and physical records.
12	The locations of the current EOF and header label of the file.
13	The file code, name of the file's creator, and number of user-created labels.
14	The physical (hardware) status of the device on which the file resides.
15	`NUMBER WRITERS` is the number of `FOPEN` calls of the file with some type of WRITE access. `NUMBER READERS` is the number of `FOPEN` calls to the file with READ access. This field applies only to message files; it does not appear for other files.
16	The error number and residue.
17	The block number and number of records (`NUMREC`) for the file.

Writing a file system error-check procedure

Error checking intrinsics can be used throughout a program every time that there is an intrinsic call. Instead of repeating a call to PRINTFILEINFO many times, it is more efficient to write an error-check procedure and merely call this procedure where necessary.

The following example is a sample error-check procedure, named FILERROR. This procedure is declared at the beginning of the program; from that point on, it can be called with a single statement.

The procedure contains two parameters. FILENO is an identifier through which the file number is passed. The PRINTFILEINFO intrinsic then prints a file information display for that file. QUITNO is part of the abort message printed by the QUIT intrinsic. This enables you to determine the point at which the process was aborted.

   PROCEDURE FILERROR(FILENO,QUITNO:SHORTINT); 

   

      BEGIN 

          PRINTFILEINFO(FILENO); 

          QUIT(QUITNO); 

      END;

Displaying File Error Information

Technical documentation

» Table of Contents

» Index

FCHECK

FERRMSG

PRINTFILEINFO

Writing a file system error-check procedure