File Access Library Reference

The File Access Library (FAL) is a collection of procedures that provide access to the BASIC file system from a CSUB. By using these procedures, you can create, purge, open, close, read, write and position files.

There is a one-to-one functionality between FAL procedures and corresponding BASIC statements. For example, FAL_CREATE_BDATA creates a BDAT file from the CSUB the same way the BASIC CREATE BDAT statement creates a BDAT file.

This appendix is a reference that describes each procedure in the File Access Library. For more general information, see the "I/O From CSUBs" chapter, section "File Access Library."

FAL_CLOSE

IMPORT: CSFA

This procedure closes a file. Files must be explicitly closed since the system does not know about FAL files and cannot close them automatically at subroutine exit and stop.

Syntax

FAL_CLOSE ( file pointer )
Item Description Range
file pointer pointer of TYPE fcb_ptr_type (pointer to idtable) --

Example Procedure Calls


FAL_CLOSE(idptr)

FAL_CLOSE(Ptr)

Semantics

The "file pointer" (idptr) parameter is a pointer to an idtable.

You must allocate an idtable for use by all routines that have an idptr as a parameter. An idtable is a file control block. From the user's point of view, an idtable can be a packed array of 148 bytes. When a file is opened, file control information is written into the idtable. When a file is accessed, the idtable is consulted for information regarding file location, type, etc. You should never change any data in the idtable except by FAL procedures.

An idtable uniquely identifies a file. The same idtable must be used to access the file once it is open. Several files can be open at the same time; each must have it's own idtable. Access to one file with two different idtables at the same time is not supported.

Calling FAL_CLOSE with an idtable that is not open does not give an error.

FAL_CREATE

IMPORT: CSFA

This procedure creates an HP-UX file.

Syntax

FAL_CREATE ( file specifier, number of bytes )

Item Description Range
file specifier string expression of TYPE STRING[160] (file_name_type) any valid file specifier
number of bytes numeric expression of TYPE INTEGER 1 thru 2 31 - 1

Example Procedure Calls


FAL_CREATE(File_spec,N_bytes)

FAL_CREATE("NewFile:,700",128)

Semantics

The "file specifier" (File_spec) parameter may include a directory specifier (if the file is to be created on a volume that supports hierarchical directories), and a mass storage unit specifier (msus).

The "number of bytes" (N_bytes) parameter specifies how many bytes are to be allocated to the file.

FAL_CREATE_ASCII

IMPORT: CSFA

This procedure creates an ASCII file.

Syntax

FAL_CREATE_ASCII (file specifier, number of records)
Item Description Range
file specifier string expression of TYPE STRING[160] (file_name_type) any valid file specifier
number of records (256 bytes) numeric expression of TYPE INTEGER 1 thru 2 31 - 1

Example Procedure Calls


FAL_CREATE_ASCII(File_spec,N_recs)

FAL_CREATE_ASCII("NewFile:,700",128)

Semantics

The "file specifier" (File_spec) parameter may include a directory specifier (if the file is to be created on a volume that supports hierarchical directories), and a mass storage unit specifier (msus).

The "number of records" (N_recs) parameter specifies how many records are to be allocated to the file. For ASCII files, one record is 256 bytes.

FAL_CREATE_BDAT

IMPORT: CSFA

This procedure creates a BDAT file.

Syntax

FAL_CREATE_BDAT (file specifier, record size, number of records)
Item Description Range
file specifier string expression of TYPE STRING[160] (file_name_type) any valid file specifier
record size numeric expression of TYPE INTEGER 1 thru 2 31 - 1
number of records numeric expression of TYPE INTEGER 1 thru 2 31 - 1

Example Procedure Calls


FAL_CREATE_BDAT(File_spec,Rec_size,N_recs)

FAL_CREATE_BDAT("NewFile:,700",20,128)

Semantics

The "file specifier" (File_spec) parameter may include a directory specifier (if the file is to be created on a volume that supports hierarchical directories), and a mass storage unit specifier (msus).

The "record size" (Rec_size) parameter specifies the size of logical records to be used with the file. If the BDAT file is not to be used with random access operations, then use a record size of 256 (default value in BASIC).

The "number of logical records" (N_recs) parameter specifies how many logical records are to be allocated to the file.

FAL_EOF

IMPORT: CSFA

This procedure writes an end of file at the current file position. The file must be open.

Syntax

FAL_EOF (file pointer)
Item Description Range
file pointer pointer of TYPE fcb_ptr_type (pointer to idtable) --

Example Procedure Calls


FAL_EOF(idptr)

FAL_EOF(Ptr)

Semantics

The "file pointer" (idptr) parameter is a pointer to an idtable.

You must allocate an idtable for use by all routines that have an idptr as a parameter. An idtable is a file control block. From the user's point of view, an idtable can be a packed array of 148 bytes. When a file is opened, file control information is written into the idtable. When a file is accessed, the idtable is consulted for information regarding file location, type, etc. You should never change any data in the idtable except by FAL procedures.

An idtable uniquely identifies a file. The same idtable must be used to access the file once it is open. Several files can be open at the same time; each must have it's own idtable. Access to one file with two different idtables at the same time is not supported.

In a BDAT file, this updates the end of data pointer. In an ASCII file, it writes a -1 at the current location; if the user has been using FAL_READ and FAL_WRITE, he takes responsibility for actually being at the end of a record when he writes the -1 (else it will not be seen as an end-of-data).

FAL_LOADSUB_ALL

IMPORT: CSFA

This procedure loads all subprograms from a specified PROG file and appends them to the program in memory.

Syntax

FAL_LOADSUB_ALL  (file specifier)
Item Description Range
file specifier string expression of TYPE STRING[160] (file_name_type) any valid file specifier

Example Procedure Calls


FAL_LOADSUB_ALL(File_spec)

FAL_LOADSUB_ALL("NewFile:,700")

Semantics

The "file specifier" (File_spec) parameter may include a directory specifier (if the file is to be created on a volume that supports hierarchical directories), and a mass storage unit specifier (msus).

FAL_LOADSUB_NAME

IMPORT: CSFA

This procedure loads the specified subprogram from the specified PROG file and appends it to the program in memory.

Syntax

FAL_LOADSUB_NAME (file specifier)
Item Description Range
file specifier string expression of TYPE STRING[160] (file_name_type) any valid file specifier
subprogram name string expression of TYPE STRING[160] any valid subprogram name

Example Procedure Calls


FAL_LOADSUB_NAME(File_spec,Sub_name)

FAL_LOADSUB_NAME("NewFile:,700","Test1")

Semantics

The "file specifier" (File_spec) parameter may include a directory specifier (if the file is to be created on a volume that supports hierarchical directories), and a mass storage unit specifier (msus).

The "subprogram name" (Sub_name) is the name of the subprogram to be loaded. It must appear exactly as it would in the program.

FAL_OPEN

IMPORT: CSFA

This procedure opens a file for reading and writing. It can be an ASCII, BDAT or HP-UX file.

Syntax

FAL_OPEN ( file specifier, file pointer )
Item Description Range
file specifier string expression of TYPE STRING[160] (file_name_type) any valid file specifier
file pointer pointer of TYPE fcb_ptr_type (pointer to idtable) --

Example Procedure Calls


FAL_OPEN(File_spec,idptr)

FAL_OPEN("NewFile:,700",ptr)

Semantics

The "file specifier" (File_spec) parameter may include a directory specifier (if the file is to be created on a volume that supports hierarchical directories), and a mass storage unit specifier (msus).

The "file pointer" (idptr) parameter is a pointer to an idtable.

You must allocate an idtable for use by all routines that have an idptr as a parameter. An idtable is a file control block. From the user's point of view, an idtable can be a packed array of 148 bytes. When a file is opened, file control information is written into the idtable. When a file is accessed, the idtable is consulted for information regarding file location, type, etc.

An idtable uniquely identifies a file. The same idtable must be used to access the file once it is open. Several files can be open at the same time; each must have it's own idtable. Access to one file with two different idtables at the same time is not supported.

NOTE
As part of opening a file, the system will close any I/O path which is open using the same idtable. Since Pascal variables are not cleared when they are allocated, your idtable may initially contain data which will appear to the system to be an open I/O path. Errors and incorrect behavior may occur if the system tries to close an I/O path based on this random data. To prevent this, you must zero the idtable before you use it the first time in FAL_OPEN. Once you are using the idtable, never change any data in it except by using FAL procedures.

Files must be explicitly closed using FAL_CLOSE. They will not be closed at subroutine exit or stop.

FAL_OPEN initializes the idtable with the default ASSIGN attributes, but the FAL routines themselves do not observe any of the ASSIGN attributes.

Unlike ASSIGN, FAL_OPEN will always close an open idtable, even if the subsequent attempt to open the file fails.

FAL_POSITION

IMPORT: CSFA

This procedure positions the file to a specified logical record number. The file must be open and must be a BDAT or HP-UX file.

Syntax

FAL_POSITION (file pointer, logical record)
Item Description Range
file pointer pointer of TYPE fcb_ptr_type (pointer to idtable) --
logical record numeric expression of TYPE INTEGER 1 thru 2 31 - 1

Example Procedure Calls


FAL_POSITION(idptr,logrecno)

FAL_POSITION(Ptr, 1)

Semantics

The "file pointer" (idptr) parameter is a pointer to an idtable.

You must allocate an idtable for use by all routines that have an idptr as a parameter. An idtable is a file control block. From the user's point of view, an idtable can be a packed array of 148 bytes. When a file is opened, file control information is written into the idtable. When a file is accessed, the idtable is consulted for information regarding file location, type, etc. You should never change any data in the idtable except by FAL procedures.

An idtable uniquely identifies a file. The same idtable must be used to access the file once it is open. Several files can be open at the same time; each must have it's own idtable. Access to one file with two different idtables at the same time is not supported.

The logrecno (logical record) is the logical record for BDAT files or byte number for HP-UX files at which the file pointer is to be positioned. The beginning of a file is at logical record number 1.

FAL_PURGE

IMPORT: CSFA

This procedure purges a file. The file must be closed.

Syntax

FAL_PURGE ( file specifier )
Item Description Range
file specifier string expression of TYPE STRING[160] (file_name_type) any valid file specifier

Example Procedure Calls


FAL_PURGE(File_spec)

FAL_PURGE("NewFile:,700")

Semantics

The "file specifier" (File_spec) parameter may include a directory specifier (if the file is to be created on a volume that supports hierarchical directories), and a mass storage unit specifier (msus).

FAL_PURGE will detect attempts to purge files which are opened in BASIC (i.e., by assigning an I/O path name (@Name) to the file). It will not detect attempts to purge files which are opened in the CSUB (i.e., by assigning a file control block (equivalent to the value area for an I/O path) to the file). This is also true for the BASIC PURGE statement. A method for avoiding this problem is given in the "Advanced Topics" chapter.

FAL_READ

IMPORT: CSFA

This procedure reads a file. The file must be open. It can be an ASCII, BDAT or HP-UX file.

Syntax

FAL_READ ( file pointer, bytes, buffer pointer)
Item Description Range
file pointer pointer of TYPE fcb_ptr_type (pointer to idtable) --
bytes numeric expression, of TYPE INTEGER 0 to 2 31 - 1
buffer pointer pointer to a buffer (anyptr) --

Example Procedure Calls


FAL_READ(idptr,nbytes,bufptr)

FAL_READ(Ptr,70,Tobuf)

Semantics

The "file pointer" (idptr) parameter is a pointer to an idtable.

You must allocate an idtable for use by all routines that have an idptr as a parameter. An idtable is a file control block. From the user's point of view, an idtable can be a packed array of 148 bytes. When a file is opened, file control information is written into the idtable. When a file is accessed, the idtable is consulted for information regarding file location, type, etc. You should never change any data in the idtable except by FAL procedures.

An idtable uniquely identifies a file. The same idtable must be used to access the file once it is open. Several files can be open at the same time; each must have it's own idtable. Access to one file with two different idtables at the same time is not supported.

The "bytes" (nbytes) parameter defines the number of bytes to read.

The "buffer pointer" (bufptr) is a pointer to the buffer.

This procedure provides direct access to the data bytes in the file. Therefore, the user must keep track of the record structure in a ASCII file. (Each item (logical record) in an ASCII file is proceeded by a two-byte length header and contains an even number of bytes. If necessary a null byte, CHR$(0), is added to the item to make an even number of bytes in each record.)

FAL_READ_BDAT_INT

IMPORT: CSFA

This procedure reads a BASIC 16-bit integer from a file. This file must be open and should be a BDAT or HP-UX file.

Syntax

FAL_READ_BDAT_INT ( file pointer, buffer pointer)
Item Description Range
file pointer pointer of TYPE fcb_ptr_type (pointer to idtable) --
buffer pointer pointer to a 16-bit INTEGER (anyptr) --

Example Procedure Calls


FAL_READ_BDAT_INT(idptr,intbufptr)

FAL_READ_BDAT_INT(Ptr,Froms)

Semantics

The "file pointer" (idptr) parameter is a pointer to an idtable.

You must allocate an idtable for use by all routines that have an idptr as a parameter. An idtable is a file control block. From the user's point of view, an idtable can be a packed array of 148 bytes. When a file is opened, file control information is written into the idtable. When a file is accessed, the idtable is consulted for information regarding file location, type, etc. You should never change any data in the idtable except by FAL procedures.

An idtable uniquely identifies a file. The same idtable must be used to access the file once it is open. Several files can be open at the same time; each must have it's own idtable. Access to one file with two different idtables at the same time is not supported.

The intbufptr (buffer pointer) is a pointer to a 16-bit integer.

FAL_READ_STRING

IMPORT: CSFA

This procedure reads a string from an ASCII, BDAT or HP-UX file. This file must be open.

Syntax

FAL_READ_STRING ( file pointer, bytes, buffer pointer)
Item Description Range
file pointer pointer of TYPE fcb_ptr_type (pointer to idtable) --
bytes numeric expression, rounded to an integer 0 to 2 31 - 1
buffer pointer pointer to a buffer (anyptr) --

Example Procedure Calls


FAL_READ_STRING(idptr,nbytes,bufptr)

FAL_READ_STRING(Ptr,70,Tobuf)

Semantics

The "file pointer" (idptr) parameter is a pointer to an idtable.

You must allocate an idtable for use by all routines that have an idptr as a parameter. An idtable is a file control block. From the user's point of view, an idtable can be a packed array of 148 bytes. When a file is opened, file control information is written into the idtable. When a file is accessed, the idtable is consulted for information regarding file location, type, etc. You should never change any data in the idtable except by FAL procedures.

An idtable uniquely identifies a file. The same idtable must be used to access the file once it is open. Several files can be open at the same time; each must have it's own idtable. Access to one file with two different idtables at the same time is not supported.

The "bytes" (nbytes) parameter defines the maximum number of bytes to read.

The "buffer pointer" (bufptr) is a pointer to the string buffer. The length of the string in the file is determined from the file itself; the next 4-bytes for a BDAT file and the next 2-bytes for an ASCII file. If the length is odd, then it is increased by 1. If the result of that increase is greater than the nbytes specified, an escape is generated. Otherwise, the next length bytes are read into the buffer. Note that, if you specify nbytes greater than the buffer size you may write over system information.

In an HP-UX file, a string is terminated by a null character. There is no length field at the beginning of the string.

FAL_WRITE

IMPORT: CSFA

This procedure writes a file. The file must be open. It can be an ASCII, BDAT or HP-UX file.

Syntax

FAL_WRITE (file pointer, bytes, buffer pointer)
Item Description Range
file pointer pointer of TYPE fcb_ptr_type (pointer to idtable) --
bytes numeric expression, rounded to an integer 0 to 2 31 - 1
buffer pointer pointer to a buffer (anyptr) --

Example Procedure Calls


FAL_WRITE(idptr,nbytes,bufptr)

FAL_WRITE(Ptr,70,Tobuf)

Semantics

The "file pointer" (idptr) parameter is a pointer to an idtable.

You must allocate an idtable for use by all routines that have an idptr as a parameter. An idtable is a file control block. From the user's point of view, an idtable can be a packed array of 148 bytes. When a file is opened, file control information is written into the idtable. When a file is accessed, the idtable is consulted for information regarding file location, type, etc. You should never change any data in the idtable except by FAL procedures.

An idtable uniquely identifies a file. The same idtable must be used to access the file once it is open. Several files can be open at the same time; each must have it's own idtable. Access to one file with two different idtables at the same time is not supported.

The "bytes" (nbytes) parameter defines the number of bytes to write.

The "buffer pointer" (bufptr) is a pointer to the buffer.

This procedure provides direct access to the data bytes in the file. Therefore, the user must keep track of the record structure in a ASCII file. (Each item (logical record) in an ASCII file is proceeded by a two-byte length header and contains an even number of bytes. If necessary a null byte, CHR$(0), is added to the item to make an even number of bytes in each record.)

FAL_WRITE_BDAT_INT

IMPORT: CSFA

This procedure writes a BASIC 16-bit integer to a file. This file must be open and should be a BDAT or HP-UX file.

Syntax

FAL_WRITE_BDAT_INT ( file pointer, buffer pointer)
Item Description Range
file pointer pointer of TYPE fcb_ptr_type (pointer to idtable) --
buffer pointer pointer to a 16-bit INTEGER (anyptr) --

Example Procedure Calls


FAL_WRITE_BDAT_INT(idptr,intbufptr)

FAL_WRITE_BDAT_INT(Ptr,Tosix)

Semantics

The "file pointer" (idptr) parameter is a pointer to an idtable.

You must allocate an idtable for use by all routines that have an idptr as a parameter. An idtable is a file control block. From the user's point of view, an idtable can be a packed array of 148 bytes. When a file is opened, file control information is written into the idtable. When a file is accessed, the idtable is consulted for information regarding file location, type, etc. You should never change any data in the idtable except by FAL procedures.

An idtable uniquely identifies a file. The same idtable must be used to access the file once it is open. Several files can be open at the same time; each must have it's own idtable. Access to one file with two different idtables at the same time is not supported.

The intbufptr (buffer pointer) is a pointer to a 16-bit integer.

FAL_WRITE_STRING

IMPORT: CSFA

This procedure writes a string to an ASCII, BDAT or HP-UX file. This file must be open.

Syntax

FAL_WRITE_STRING ( file pointer, bytes, buffer pointer)
Item Description Range
file pointer pointer of TYPE fcb_ptr_type (pointer to idtable) --
bytes numeric expression, rounded to an integer 0 to 2 31 - 1
buffer pointer pointer to a buffer (anyptr) --

Example Procedure Calls


FAL_WRITE_STRING(idptr,nbytes,bufptr)

FAL_WRITE_STRING(Ptr,70,Tobuf)

Semantics

The "file pointer" (idptr) parameter is a pointer to an idtable.

You must allocate an idtable for use by all routines that have an idptr as a parameter. An idtable is a file control block. From the user's point of view, an idtable can be a packed array of 148 bytes. When a file is opened, file control information is written into the idtable. When a file is accessed, the idtable is consulted for information regarding file location, type, etc. You should never change any data in the idtable except by FAL procedures.

An idtable uniquely identifies a file. The same idtable must be used to access the file once it is open. Several files can be open at the same time; each must have it's own idtable. Access to one file with two different idtables at the same time is not supported.

The "bytes" (nbytes) parameter defines the number of bytes to write. When you write to a BDAT file a 4-byte binary length is written followed by the string, padded to the next even byte if necessary. When you write to an ASCII file a 2-byte binary length is written followed by the string, padded to the next even byte if necessary.

The "buffer pointer" (bufptr) is a pointer to the string buffer.

In an HP-UX file, a string is terminated by a null character. There is no length field at the beginning of the string.