HPlogo Accessing Files Programmer's Guide > Chapter 14 Getting File Information

Displaying File Error Information

MPE documents

Complete PDF
Table of Contents
Index

E0300 Edition 6 ♥
E0692 Edition 5

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:
FCHECKFile system intrinsic error number
FERRMSGFile system intrinsic error message
PRINTFILEINFOFile 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, 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 is shown in Example 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
1Warns that no corresponding file is open.
2ERROR 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.
3In 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
1The file name.
2,3The foptions in effect.
4,5The aoptions in effect.
6,7The 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.
8The record and block size of the offending record, in bytes and words, as noted.
9The size of the current extent and the maximum number of records in the file.
10The current record pointer, and limit on number of records in the file.
11The present count of logical and physical records.
12The locations of the current EOF and header label of the file.
13The file code, name of the file's creator, and number of user-created labels.
14The physical (hardware) status of the device on which the file resides.
15NUMBER 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.
16The error number and residue.
17The 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;



Determining Interactive/Duplicative Files with FRELATE

Appendix A Pascal/XL Program Examples