The TPU$FILEIO routine handles all DECTPU file operations.
Your own file I/O routine can call this routine to perform some
operations for it. However, the routine that opens the file must
perform all operations for that file. For example, if TPU$FILEIO
opens the file, it must also close it.
Format
TPU$FILEIO code ,stream ,data
1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
Longword condition value. Most utility routines return a
condition value in R0. Condition values that this routine can
return are listed under Condition Values Returned.
2 – Arguments
code
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Item code specifying a DECTPU function. The code argument is
the address of a longword containing an item code from DECTPU
specifying a function to perform. Following are the item codes
that you can specify in the file I/O routine:
o TPU$K_OPEN-This item code specifies that the data parameter
is the address of an item list. This item list contains the
information necessary to open the file. The stream parameter
should be filled in with a unique identifying value to be used
for all future references to this file. The resultant file
name should also be copied with a dynamic string descriptor.
o TPU$K_CLOSE-The file specified by the stream argument is to
be closed. All memory being used by its structures can be
released.
o TPU$K_CLOSE_DELETE-The file specified by the stream argument
is to be closed and deleted. All memory being used by its
structures can be released.
o TPU$K_GET-The data parameter is the address of a dynamic
string descriptor to be filled with the next record from the
file specified by the stream argument. The routine should use
the routines provided by the Run-Time Library to copy text
into this descriptor. DECTPU frees the memory allocated for
the data read when the file I/O routine indicates that the end
of the file has been reached.
o TPU$K_PUT-The data parameter is the address of a descriptor
for the data to be written to the file specified by the stream
argument.
stream
OpenVMS usage:unspecified
type: longword (unsigned)
access: modify
mechanism: by reference
File description. The stream argument is the address of a data
structure consisting of four longwords. This data structure
describes the file to be manipulated.
This data structure is used to refer to all files. It is written
to when an open file request is made. All other requests use
information in this structure to determine which file is being
referenced.
The following figure shows the stream data structure:
----------------------------------------------
| File identifier |
----------------------------------------------
| RFM | | Allocation |
----------------------------------------------
| Class | Type | Length |
----------------------------------------------
The first longword holds a unique identifier for each file. The
user-written file I/O routine is restricted to values between 0
and 511. Thus, you can have up to 512 files open simultaneously.
The second longword is divided into three fields. The low word
is used to store the allocation quantity, that is, the number
of blocks allocated to this file from the FAB (FAB$L_ALQ).
This value is used later to calculate the output file size for
preallocation of disk space. The low-order byte of the second
word is used to store the record attribute byte (FAB$B_RAT)
when an existing file is opened. The high-order byte is used
to store the record format byte (FAB$B_RFM) when an existing file
is opened. The values in the low word and the low-order and high-
order bytes of the second word are used for creating the output
file in the same format as the input file. These three fields are
to be filled in by the routine opening the file.
The last two longwords are used as a descriptor for the resultant
or the expanded file name. This name is used later when DECTPU
processes EXIT commands. This descriptor is to be filled in with
the file name after an open operation. It should be allocated
with either the routine LIB$SCOPY_R_DX or the routine LIB$SCOPY_
DX from the Run-Time Library. This space is freed by DECTPU when
it is no longer needed.
data
OpenVMS usage:item_list_3
type: longword (unsigned)
access: modify
mechanism: by reference
Stream data. The data argument is either the address of an item
list or the address of a descriptor.
NOTE
The meaning of this parameter depends on the item code
specified in the code field.
When the TPU$K_OPEN item code is issued, the data parameter is
the address of an item list containing information about the
open request. The following DECTPU item codes are available for
specifying information about the open request:
o TPU$K_ACCESS item code lets you specify one of three item
codes in the buffer address field, as follows:
- TPU$K_IO
- TPU$K_INPUT
- TPU$K_OUTPUT
o TPU$K_FILENAME item code is used for specifying the address
of a string to use as the name of the file you are opening.
The length field contains the length of this string, and the
address field contains the address.
o TPU$K_DEFAULTFILE item code is used for assigning a default
file name to the file being opened. The buffer length field
contains the length, and the buffer address field contains the
address of the default file name.
o TPU$K_RELATEDFILE item code is used for specifying a related
file name for the file being opened. The buffer length field
contains the length, and the buffer address field contains the
address of a string to use as the related file name.
o TPU$K_RECORD_ATTR item code specifies that the buffer address
field contains the value for the record attribute byte in the
FAB (FAB$B_RAT) used for file creation.
o TPU$K_RECORD_FORM item code specifies that the buffer address
field contains the value for the record format byte in the FAB
(FAB$B_RFM) used for file creation.
o TPU$K_MAXIMIZE_VER item code specifies that the version number
of the output file should be one higher than the highest
existing version number.
o TPU$K_FLUSH item code specifies that the file should have
every record flushed after it is written.
o TPU$K_FILESIZE item code is used for specifying a value to be
used as the allocation quantity when creating the file. The
value is specified in the buffer address field.
3 – Description
By default, TPU$FILEIO creates variable-length files with
carriage-return record attributes (FAB$B_RFM = VAR, FAB$B_RAT
FORM item, that item is used instead.
The following combinations of formats and attributes are
acceptable:
Format Attributes
STM,STMLF,STMCR 0,BLK,CR,BLK+CR
VAR 0,BLK,FTN,CR,BLK+FTN,BLK+CR
All other combinations are converted to VAR format with CR
attributes.
This routine always puts values greater than 511 in the first
longword of the stream data structure. Because a user-written
file I/O routine is restricted to the values 0 through 511, you
can easily distinguish the file control blocks (FCB) this routine
fills in from the ones you created.
NOTE
DECTPU uses TPU$FILEIO by default when you use the
simplified callable interface. When you use the full
callable interface, you must explicitly invoke TPU$FILEIO
or provide your own file I/O routine.
4 – Condition Values Returned
The TPU$FILEIO routine returns an OpenVMS RMS status code to
DECTPU. The file I/O routine is responsible for signaling all
errors if any messages are desired.