.lo 3,2
.lm 0.rm 72
.fl bold.fl break.fl capitalize.fl hyphenate.fl index.xl.fl period
.nhd
.c;^*GET__FILE__HEADER - Return the File Header Record of a File ID\*
.b
.c;by ^&Rodrick A. Eldridge\&
^*
.hl1 Introduction
\*
.b
The GET__FILE__HEADER routine will read the indexf system file on the device
specified and return the file header record of the file ID specified.
.tp 7
^*
.hl1 Using GET__FILE__HEADER
\*
^*
.hl2 Format
\*
The following shows the format of the GET__FILE__HEADER program:
.b
.lt
	GET_FILE_HEADER work-area,device-name,buffer
.el
.b
.tp 5
^*
.hl2 Arguments
\*
.lm 9
.i -9
^&work-area\&
.b
The work area is a record structure that contains the following fields.
The ^&work-area\& argument is the address of this record structure.
For each difference device specified, you must have a separate work area.
.lm 18
.b
.tp 5
.i -9
^&ifi\&
.b
Internal file identifier (IFI) that is assigned to the device from which the
indexf system file will be mapped and read.
The ^&ifi\& argument is a word value containing this number and must be zero
on the initial call to this routine.
.b
.tp 5
.i -9
^&file-id\&
.b
File identifier of the file header record to return.
The ^&file-id\& argument is a structure of 3 words containing the file
identifier.
.b
If the ^&file-id\& is greater than zero, the routine will return the file header
whose VBN is this file ID plus the VBN of the first file header.
.b
If the ^&file-id\& is less than zero, the routine will return the file header
whose VBN is the absolute value of the file ID.
Making the ^&file-id\& negative before calling this routine allows you to
access the fixed file headers (i.e. the home block, etc.) in the indexf system
file.
.b
After all calls have been made to the GET__FILE__HEADER routine for the specified
device, set the ^&file-id\& argument to zero and call this routine one last
time to disconnect and close the indexf system file on the device.
.b
.tp 5
.i -9
^&vbn-filehdr\&
.b
VBN of the start of the file headers.
The ^&vbn-filehdr\& argument is an unsigned longword value containing the
VBN of the first file header in the indexf system file.
.lm 9
.b
.tp 5
.i -9
^&device-name\&
.b
The device name of where the indexf system file is located.
The ^&device-name\& argument is the address of a descriptor pointing to this
device name.
The trailing colon (i.e. _:) must be included as part of the device name.
.b
.tp 5
.i -9
^&buffer\&
.b
The buffer for the file header record returned.
The ^&buffer\& argument is the address of a descriptor pointing to this
file header record.
.b
To contain the entire file header record, the buffer size must be at least 512
bytes.
If the buffer size is larger than 512 bytes, the record will be padded with
binary zeros, and if the buffer size is smaller than 512 bytes, the record will
be truncated to fit into the buffer.
.lm 0
.tp 7
^*
.hl2 Linking
\*
.b
To use the GET__FILE__HEADER routine, link your program to the TOOLS.OLB library in
ISU__COMMON:[LIB].
.b
.tp 5
For example:
.b
.lt
	LINK your_program+ISU_COMMON:[LIB]TOOLS/LIBR
.el
.tp 7
^*
.hl1 Condition Values Returned
\*
The following condition values may be returned by the GET__FILE__HEADER routine:
.b
.tp 3
.lm 9
.i -9
^*SS$__NORMAL\*
.b
Routine successfully completed; file header returned.
.b
.tp 3
.i -9
^*SS$__ENDOFFILE\*
.b
Routine successfully completed; end of file.
.b
.tp 3
.i -9
^*SS$__INSFARG\*
.b
The argument list contained fewer than the three required arguments.
.b
.tp 3
.i -9
Any condition values returned by ^*SYS$CLOSE\*.
.b
.tp 3
.i -9
Any condition values returned by ^*SYS$CONNECT\*.
.b
.tp 3
.i -9
Any condition values returned by ^*SYS$DISCONNECT\*.
.b
.tp 3
.i -9
Any condition values returned by ^*SYS$OPEN\*.
.b
.tp 3
.i -9
Any condition values returned by ^*SYS$READ\*.
.lm 0