.lo 3,2
.lm 0.rm 72
.fl bold.fl break.fl capitalize.fl hyphenate.fl index.xl.fl period
.nhd
.c;^*GET__INDEXF - Map and Read the INDEXF System File\*
.b
.c;by ^&Rodrick A. Eldridge\&
^*
.hl1 Introduction
\*
.b
The GET__INDEXF routine will map the indexf system file into virtual memory
and allow the calling program to access each file header record.
.tp 7
^*
.hl1 Using GET__INDEXF
\*
^*
.hl2 Format
\*
The following shows the format of the GET__INDEXF program:
.b
.lt
	GET_INDEXF 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
^&flag\&
.b
Access flag to specify what type of file header to return.
The ^&flag\& argument is a word value containing either zero or non-zero.
.b
If the ^&flag\& value is zero, then the routine will return the next used
file header.
If the ^&flag\& value is non-zero, then the routine will return the next
file header, regardless of whether it is currently used by the system
(i.e. has a file assigned to it).
.b
.tp 5
.i -9
^&n-filehdr\&
.b
Number of file headers in the indexf system file.
The ^&n-filehdr\& argument is an unsigned longword value containing the number
of file headers in the indexf system file currently mapped.
.b
.tp 5
.i -9
^&vbn-filehdr\&
.b
VBN of last mapped file header.
The ^&vbn-filehdr\& argument is an unsigned longword value containing the
current VBN of the last file header mapped.
.b
.tp 5
.i -9
^&n-mapped\&
.b
Number of pages currently mapped.
The ^&n-mapped\& argument is an unsigned longword value containing the
number of pages currently being mapped.
.b
.tp 5
.i -9
^&adr-filehdr\&
.
.i -9
^&adr-actual\&
.b
Addresses of mapped sections.
The ^&adr-filehdr\& and ^&adr-actual\& arguments are unsigned quadword values
containing the addresses of currently mapped sections of 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__INDEXF 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__INDEXF routine:
.b
.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$CRMPSC\*.
.b
.tp 3
.i -9
Any condition values returned by ^*SYS$DELTVA\*.
.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