This appendix is a reference that describes each routine in the file access library. There is a one-to-one functionality between fal routines and corresponding BASIC statements. For example, FAL_CREATE_BDAT creates a BDAT file from the CSUB the same way the BASIC CREATE BDAT statement creates a BDAT file.
The routines described in this appendix are implemented in HP Pascal for the Pascal Workstation and HP-UX. If you wish to call them from another language, you will need to determine the parameter types in that language which match the types of the formal parameters of the routines. Note that in HP Pascal an idtable is a packed array of 190 bytes. Therefore, in this appendix where it mentions an idtable is 148 bytes, it is refering to an idtable for a Pascal Workstation.
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.
FAL_CLOSE ( file pointer )
Item | Description | Range |
---|---|---|
file pointer | pointer of TYPE fcb_ptr_type (pointer to idtable) | -- |
FAL_CLOSE(idptr)
FAL_CLOSE(Ptr)
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 190 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 it 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.
IMPORT: | CSFA |
This procedure creates an HP-UX file.
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 |
FAL_CREATE(File_spec,N_bytes)
FAL_CREATE("NewFile:,700",128)
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.
IMPORT: | CSFA |
This procedure creates an ASCII file.
FAL_CREATE_ASCII ( 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 records (256 bytes) | numeric expression of TYPE INTEGER | 1 thru 2 31 - 1 |
FAL_CREATE_ASCII(File_spec,N_recs)
FAL_CREATE_ASCII("NewFile:,700",128)
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.
IMPORT: | CSFA |
This procedure creates a BDAT file.
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 |
FAL_CREATE_BDAT(File_spec,Rec_size,N_recs)
FAL_CREATE_BDAT("NewFile:,700",20,128)
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.
IMPORT: | CSFA |
This procedure writes an end of file at the current file position. The file must be open.
FAL_EOF ( file pointer )
Item | Description | Range |
---|---|---|
file pointer | pointer of TYPE fcb_ptr_type (pointer to idtable) | -- |
FAL_EOF(idptr)
FAL_EOF(Ptr)
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 190 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 it 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).
IMPORT: | CSFA |
This procedure loads all subprograms from a specified PROG file and appends them to the program in memory.
FAL_LOADSUB_ALL ( file specifier )
Item | Description | Range |
---|---|---|
file specifier | string expression of TYPE STRING[160] (file_name_type) | any valid file specifier |
FAL_LOADSUB_ALL(File_spec)
FAL_LOADSUB_ALL("NewFile:,700")
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).
IMPORT: | CSFA |
This procedure loads the specified subprogram from the specified PROG file and appends it to the program in memory.
FAL_LOADSUB_NAME ( file specifier, subprogram name )
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 |
FAL_LOADSUB_NAME(File_spec,Sub_name)
FAL_LOADSUB_NAME("NewFile:,700","Test1")
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.
IMPORT: | CSFA |
This procedure opens a file for reading and writing. It can be an ASCII, BDAT or HP-UX file.
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) | -- |
FAL_OPEN(File_spec,idptr)
FAL_OPEN("NewFile:,700",ptr)
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 190 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 it 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.
BDAT and HP-UX files are opened in FORMAT OFF.
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.
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 |
FAL_POSITION(idptr,logrecno)
FAL_POSITION(Ptr, 1)
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 190 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 it 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.
IMPORT: | CSFA |
This procedure purges a file. The file must be closed.
FAL_PURGE ( file specifier)
Item | Description | Range |
---|---|---|
file specifier | string expression of TYPE STRING[160] (file_name_type) | any valid file specifier |
FAL_PURGE(File_spec)
FAL_PURGE("NewFile:,700")
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.
IMPORT: | CSFA |
This procedure reads a file. The file must be open. It can be an ASCII, BDAT or HP-UX file.
margin=0pt nonumber
width=4.816in penwidth="0.14mm,0.21mm,0.32mm,0.48mm">
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) | -- |
FAL_READ(idptr,nbytes,bufptr)
FAL_READ(Ptr,70,Tobuf)
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 190 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 it 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.)
IMPORT: | CSFA |
This procedure reads a BASIC 16-bit integer from a BDAT file. This file must be open and must be a BDAT file.
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) | -- |
FAL_READ_BDAT_INT(idptr,intbufptr)
FAL_READ_BDAT_INT(Ptr,Froms)
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 190 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 it 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.
IMPORT: | CSFA |
This procedure reads a string from an ASCII, BDAT or HP-UX file. This file must be open.
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) | -- |
FAL_READ_STRING(idptr,nbytes,bufptr)
FAL_READ_STRING(Ptr,70,Tobuf)
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 190 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 it 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.
IMPORT: | CSFA |
This procedure writes a file. The file must be open. It can be an ASCII, BDAT or HP-UX file.
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) | -- |
FAL_WRITE(idptr,nbytes,bufptr)
FAL_WRITE(Ptr,70,Tobuf)
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 190 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 it 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.)
IMPORT: | CSFA |
This procedure writes a BASIC 16-bit integer to a BDAT file. This file must be open and must be a BDAT file.
FAL_WRITE_BDAT_INT ( file pointer, bytes , 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) | -- |
FAL_WRITE_BDAT_INT(idptr,intbufptr)
FAL_WRITE_BDAT_INT(Ptr,Tosix)
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 190 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 it 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.
IMPORT: | CSFA |
This procedure writes a string to an ASCII, BDAT or HP-UX file. This file must be open.
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) | -- |
FAL_WRITE_STRING(idptr,nbytes,bufptr)
FAL_WRITE_STRING(Ptr,70,Tobuf)
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 190 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 it 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.