HP 3000 Manuals HP 3000 Manuals
FGETINFO
INTRINSIC NUMBER 11
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, 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 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 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), 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.
_______________________________________________________________________
| |
| $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; |
_______________________________________________________________________
Figure 4-4. FGETINFO Example
______________________________________________________________________
| |
| <<****************************************************>> |
| << 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): |
______________________________________________________________________
Figure 4-4. FGETINFO Example (continued)
________________________________________________________________________
| |
| <<**********************************************************>> |
| <<* 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 |
________________________________________________________________________
Figure 4-4. FGETINFO Example (continued)