/sys$common/syshlp/helplib.hlb DECTPU, TPU$FILEIO, Arguments  *Conan The Librarian (sorry for the slow response - running on an old VAX)

 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:

    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.