Enscribe Programmer's Guide

File Number Parameters
All of the file-system procedures except DISK_REFRESH_, FILE_CREATE_, FILE_GETINFOBYNAME_,
FILE_OPEN_, FILE_PURGE_, FILENAME_FINDNEXT64_, and FILENAME_FINDNEXT_, use the
filenum parameter returned by the FILE_OPEN_ procedure to identify which file the call refers
to. The FILE_CREATE_, FILE_GETINFOBYNAME_, FILE_OPEN_, and FILE_PURGE_ procedures refer
to the file by filename; the LASTRECEIVE and FILE_REPLY64_, REPLY procedures always refer
to the $RECEIVE file. For every procedure except FILE_OPEN_ and AWAITIO[X]/FILE_AWAITIO64_
that has afilenum parameter, the file number is an INT:value parameter.
Tag Parameters
An application-specified double integer (INT(32)) tag can be passed as a calling parameter when
an I/O operation (read or write) is initiated with a nowait file. The tag is passed back to the
application process, through the AWAITIO[X]/FILE_AWAITIO64_ procedure, when the I/O
operation completes. The tag is useful for identifying individual file operations and can be used
in application-dependent error recovery routines.
Buffer Parameter
The buffer parameter in a file-system procedure call specifies where the data is to be read from or
written to.
For I/O operations such as FILE_READ64_, READ, FILE_WRITE64_ or WRITE, the designated buffer
must be of the type integer (INT) or double-integer (INT(32)) and it must reside in the user's data
area (P-relative read-only arrays are not permitted).
For extended I/O operations such as READX or WRITEX, the designated buffer must be of type
INT or INT(32) and it can reside in either the user's data area or an extended data segment
(P-relative read-only arrays are not permitted).
Transfer Count Parameter
The read-count or write-count parameter in a file-system procedure call specifies how many bytes
are to be read or written.
A SETMODE procedure call with a function code of 141 enables and disables bulk transfers of
data between an extended data segment (or the upper 32 K of the data stack) and a DP2 disk file
that has been opened for unstructured access. Note that the SETMODE 141 call requires that the
file be opened for unstructured access (bit 2 of open^flags = 1) and for exclusive access (bits 10
and 11 of open^flags = 2).
With the bulk transfer feature disabled, you can transfer from 0 to 4096 bytes in a single operation.
With the bulk transfer feature enabled, you can transfer up to 30 K bytes in a single operation.
The amount of data transferred must be a multiple of 2 K bytes. Note that with the bulk transfer
feature enabled, the only data transfer I/O operations that are allowed are READX, READUPDATEX,
WRITEX, and WRITEUPDATEX.
Condition Codes
Some file-system procedures return a condition code indicating the outcome of the operation. For
these procedures, the condition code should always be checked after a call to a file-system
procedure and should be checked before an arithmetic operation is performed or a value is
assigned to a variable. Generally, the condition codes have these meanings:
< (CCL)
An error occurred (call the file system FILE_GETINFO_ procedure to determine the error).
> (CCG)
A warning message was generated (typically EOF, but see the individual procedures for the
meaning of CCG or call FILE_GETINFO_ to get an error number).
42 System Procedures