FGETINFO

Requests access and status information about a file.

 

              IV      BA     L       L       I       I      L      L 

   FGETINFO   (filenum,filename,foptions,aoptions,recsize,devtype,ldnum,hdaddr, 



      I    D    D     D      D         D      I      L 

filecode,recpt,eof,flimit,logcount,physcount,blksize,extsize, 



       I         I         BA      D    O-V 

numextents,userlabels,creatorid,labaddr);

Once a file is opened on any device, the FGETINFO intrinsic can be used to request access and status information about that file.

PARAMETERS

filenum

integer by value (required)

A word identifier supplying the file number of the file about which information is requested.

filename

byte array (optional)

A byte array to which is returned the actual designator of the file being referenced, in this format:

f.g.a

where

f = the local file name
g = the group name (supplied or implicit).
a = the account name (supplied or implicit).

The byte array must be 28 bytes long. When the actual designator is returned, unused bytes in the array are filled with blanks on the right.

Default: The actual designator is not returned.

foptions

logical (optional)

The foptions parameter returns seven different file characteristics by setting corresponding bit groupings in a 16-bit word. Correspondence is from right to left. The file characteristics returned are the same as those specified for foptions in the FOPEN intrinsic (refer to Table 4-6 “FOPEN foptions Parameter Format”, in the FOPEN description). Note that bit 4 is set to 1 to indicate a KSAM file.

Default: Foptions are not returned.

aoptions

logical (optional)

The aoptions parameter returns up to seven different access options represented by bit groupings in a 16-bit word, as described for the aoptions parameter of FOPEN (refer to Table 4-7 “FOPEN aoptions Parameter Format” in the FOPEN description).

Default: Aoptions are not returned.

recsize

integer (optional)

A word to which is returned the logical record size associated with the file. If the file was created as a binary type, this value is positive and expresses the size in words. If the file was created as an ASCII type, this value is negative and expresses the size in bytes.

Default: The logical record size is not returned.

devtype

integer (optional)

A word to which is returned the type and subtype of device being used for the file, where

bits (0:8) = device subtype, and
bits (8:8) = device type.

If the file is not spooled, which can be determined from hdaddr (0:8), the returned devtype is actual. The same is true if the file is spooled and was opened via logical device number. However, if an output file is spooled and was opened by device class name, devtype contains the type and subtype of the first device in its class, which may be different from the device actually used.

Default: The device type and subtype are not returned.

ldnum

logical (optional)

A word to which is returned the logical device number associated with the device on which the file resides.

If the file is a disc file, then the logical device number will be that of the first extent. If the file is spooled, then ldnum will be a virtual device number which does not correspond to the system configuration I/O device list.

Default: The logical device number is not returned.

hdaddr

logical (optional) A word to which the hardware address of the device is returned, where

bits (0:8) = the Device Reference Table (DRT) number, and
bits (8:8) = the unit number.

If the device is spooled, the DRT number will be zero and the unit number is undefined.

Default: The hardware address is not returned.

filecode

integer (optional) A word to which is returned the value recorded with the file as its data file code (for disc files only).

Default: The file code is not returned.

recpt

double (optional)

A double word to which a double integer representing the current chronological record pointer setting is returned. Following a call to FREADC for example, recpt would be the chronological record number of the record just read by the FREADC intrinsic. Remember that chronological record numbers can begin with 0 or 1, depending on how the file was built.

Default: The chronological record pointer setting is not returned.

eof

double (optional)

A double word to which is returned a double positive integer equal to the number of logical records currently in the data file. If the file does not reside on disc, this value is zero.

Default: The number of logical records in the file is not returned.

flimit

double (optional)

A double word to which is returned a double positive integer representing the number of the last logical record that could ever exist in the data file because of the physical limits of the file.

Default: The file limit information is not returned.

logcount

double (optional)

A double word to which is returned a double positive integer representing the total number of logical records passed to and from the user during the current access of the file.

Default: The logical record count is not returned.

physcount

double (optional)

A double word to which is returned a double positive integer representing the total number of physical input/output operations performed within this process against the file since the last FOPEN call.

Default: The number of I/O operations is not returned.

blksize

integer (optional)

A word to which is returned the block size associated with the file. If the file was created as a binary type, this value is positive and expresses the size in words. If the file was created as an ASCII type, this value is negative and shows the size in bytes.

Default: The block size is not returned.

extsize

logical (optional)

A word to which is returned the disc extent size associated with the data file (in sectors).

Default: The disc extent size is not returned.

numextent

integer (optional)

A word to which is returned the maximum number of disc extents allowable for the data file.

Default: The maximum allowable number of extents is not returned.

userlabels

integer (optional)

A word to which is returned the number of user header labels defined for the file when it was created. When an old file is opened for overwrite output, the value of userlabels is not reset and old user labels are not destroyed.

Default: The number of user labels is not returned.

creatorid

byte array (optional)

A type array to which is returned the eight-byte name of the user who created the file. If the file is not a disc file, blanks are returned.

Default: The user name is not returned.

labaddr

double (optional)

A double word to which is returned the sector address of the label of the file. The high-order eight bits show the logical device number. The remaining 24 bits show the absolute disc address.

Default: The label address is not returned.

CONDITION CODES

CCE: Request granted.
CCG: Not returned by this intrinsic.
CCL: Request denied because an error occurred.

USING FGETINFO

By calling FGETINFO you can return to your program any or all of the items listed as parameters. Except for the identifying filenumber, each of these parameters is optional. When omitted, embedded parameters are indicated by commas. Parameters omitted from the end of the list need not be so indicated. For example, to locate the number of records in the file by finding the end of file, you can call FGETINFO as follows:

 

FGETINFO(FILNUM , , , , , , , , , , LSTREC); 

                                    ↑___________ eof parameter

The value returned to LSTREC is the number of records in the file. The value LSTREC is also the chronological number of the last record in the file. This number can be used to read the last chronological record with FREADC or FREADDIR.

Another useful parameter of FGETINFO is recpt. This parameter returns the chronological record number of the record last read. The example in Figure 4-4 FGETINFO Example illustrates both these parameters. First, FGETINFO is used to determine the total number of records in the file using the parameter eof. Then, each record in the file is read in sequential order by primary key. Following each sequential read, FGETINFO retrieves the chronological record number of the record just read.

In the output from the program (refer to Figure 4-4 FGETINFO Example), note that the record number returned by FGETINFO is the chronological number. For instance, the first record written to the file was the record with record number 1. This record, which contains the primary key value "NOLAN JACK", is the fourth consecutive record in key sequence.

Figure 4-4 FGETINFO Example

 

$CONTROL MAIN=JEXAMPLS 
<<*********************************************************>> 
<<*                                                       *>> 
<<*                        EXAMPLE 5                      *>> 
<<*      FIND NUMBER OF RECORDS & RECORD NUMBER           *>> 
<<*                                                       *>> 
<<*********************************************************>> 
INTEGER FILNUM: 
INTEGER ERRORCODE,LENGTH; 
BYTE ARRAY FILNAME(0:9):="JEXAMFIL "; 
ARRAY MESSAGE(0:35); 
ARRAY INPUT(0:39); 
ARRAY OUTPUT(*)=INPUT; 
 DOUBLE EOP,RECPTR; 
 INTRINSIC FOPEN,FCLOSE,FREAD,FGETINFO,DASCII; 
 INTRINSIC PRINT,TERMINATE,FCHECK,FERRMSG; 
<<************************>> 
<<* OPEN THE KSAM FILE   *>> 
<<************************>> 
FILNJM:=FOPEN(FILNAME,3); <<OPEN THE KSAM FILE>> 
IF FILNUM=0 
THEN BEGIN <<CANNOT OPEN KSAM FILE>> 
       MOVE MESSAGE:="CANNOT OPEN KSAM FILE"; 
       PRINT (MESSAGE,-21,0); 
       FCHECK(FILNUM,ERRORCODE): <<GET ERROR NUMBER>> 
       FERRMSG(ERRORCODE,MESSAGE,LENGTH0;<<CONVERT TO STRING>> 
       PRINT (MESSAGE,-LENGTH,0); <<PRINTOUT ERROR MESSAGE>> 
       TERMINATE; 
     END; 
<<****************************************************>> 
<<* FIND NUMBER OF RECORDS WRITTEN TO FILE           *>> 
<<****************************************************>> 
 FGETINFO(FILNUM,,,,,,,,,,EOF); 
 IF  < >
 THEN BEGIN 
        MOVE MESSAGE:="ERROR OCCURRED FINDING NUMBER 
            OF RECORDS"; 
        PRINT(MESSAGE,-40,00; 
        FCHECK(FILNUM,ERRORCODE); 
        FERRMSG(ERRORCODE,MESSAGE,LENGTH); 
        PRINT(MESSAGE,-LENGTH,0); 
        TERMINATE; 
      END; 
<<****************************************************>> 
<<* PRINT NUMBER OF RECORDS IN FILE                  *>> 
<<****************************************************>> 
 MOVE MESSAGE:="RECORDS IN ENTITY = "; 
 DASCII(EOF,10,MESSAGE(9)); 
 PRINT(MESSAGE,-20,0); 
L1; 
<<****************************************************>> 
<<* READ KSAM SEQUENTIALLY                           *>> 
<<****************************************************>> 
FREAD(FILNUM,INPUT,-72); 
IF >                   <<END OF DATA>> 
THEN BEGIN 
       FCLOSE(FILNUM,0,0);    <<CLOSE THE KSAM FILE>>
       IF <> THEN 
         BEGIN 
            MOVE MESSAGE:="CANNOT CLOSE THE KSAM FILE"; 
            PRINT(MESSAGE,-22,0); 
            FCHECK(FILNUM,ERRORCODE); <<GET ERROR NUMBER>> 
            FERRMSG(ERRORCODE,MESSAGE,LENGTH);<<CINVERT TO STRING>> 
            PRINT(MESSAGE,-LENGTH,0); <<PRINTOUT ERROR MESSAGE>> 
         END;
       TERMINATE;
     END; 
IF < 
THEN BEGIN 
       MOVE MESSAGE:="ERROR OCCURRED WHILE READING KSAM FILE": 
       PRINT(MESSAGE,-37,0); 
       FCHECK(FILNUM,ERRORCODE); <<GET ERROR NUMRER>> 
       FERRMSG(ERRORCODE,MESSAGE.LENGTH);<<CONVERT TO STRING>> 
       PRINT(MESSAGE#-LENGTH,0): <<PRINTOUT ERRUR MESSAGE>> 
       TERMINATE; 
     END; 
<<**************************************************>> 
<<* WRITE THE DATA JUST READ FROM KSAM FILE        *>> 
<<**************************************************>> 
PRINT(OUTPUT;-72,0): 
<<**********************************************************>> 
<<* TO FIND OUT RECORD NUMBER OF THE RECORD JUST READ      *>> 
<<**********************************************************>> 
FGETINFO(FTLENUM,,,,,,,,,RECPTR): 
IF  < >
THEN BEGIN 
       MOVE MESSAGE:="ERROR OCCURRED FINDING RECORD NUMBER": 
       PRINT(MESSAGE,-36,0); 
       FCHECK(FILNUM,ERRORCODE); 
       FERRMGG(ERRORCODE,MESSAGE,LENGTH); 
       PRINT(MESSAGE,-LENGTH,0); 
       TERMINATE; 
     END; 
<<***********************************************>> 
<<* PRINT THE RECORD NUMBER OF LAST RECORD READ *>> 
<<***********************************************>> 
MOVE MESSAGE:="RECORD# = ";  
DASCII(RECPTR,10,MESSAGE(5) );  
PRINT(MESSAGE,-12,0); 
<<***********************************>> 
<<* GO BACK TO GET ANOTHER RECORD   *>> 
<<***********************************>> 
GO TO L1; 
!EOD; 
!EOD 

When Executed, the Following Output is Printed: 


RECORDS IN FILE= 10 
CARDIN RICK 578-7018 11100 WOLFF ROAD CUPERTINO CA. 94053 
RECORD# = 4  
ECKSTETN LEO 287-5137 5303 STEVENS CREEK SANTA CLARA CA. 95050  
RECORD# = 3  
HOSODA JOE 227-8214 1180 SAINT PETER CT. LOS ALTOS CA. 94022  
RECORD# = 2  
NOLAN JACK 923-4975 967 REED AVE. SUNNYVALE CA. 94087  
RECORD# = 1  
PASBY LINDA 295-1187 TOWN & CNTRY VILLAGEF SAN JOSE CA. 94102  
RECORD# = 5  
ROBERT GERRY 259-5535 12345 TELEGRAPH AVE BERKELEY CA. 90871  
RECORD# = 7  
SEELY HENRY 293-4220 1144 LEBERTY ST. EL CERRITO CA. 94053  
RECORD# = 6  
TURNEWR IVAN 984-8498 22905 EMERSON ST. OAKLAND CA. 98234  
RECORD# = R  
WESTEP ELDER 287-4598 1256 KTNGFISHER ST. SUNNYVALE CA. 43098  
RECORD# = 10  
WHITE GORDON 398-0301 4350 ASHBY AVE. BERKELEY CA. 91234  
RECORD# = 9  

 END OF PROGRAM

FGETINFO

Technical documentation

» Table of Contents

PARAMETERS

CONDITION CODES

USING FGETINFO