VMS Help DECTPU, TPU$FILEIO  *Conan The Librarian (sorry for the slow response - running on an old VAX)

    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:

    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.