Routines for accessing files (needs AMS 2.00 or later)
This set of routines (available only in AMS 2.00 or later) gives the possibility of managing custom type files.
They give a 'higher' level way for managing custom type symbols in the Variable Allocation Table than the routines in vat.h.
They can in any case be used in conjunction with the vat.h routines.
However, files.h routines are different from the file routines contained in stdio.h. First of all, they do not use the same files structures.
Moreover, stdio.h file functions are GCC4TI library functions working with any AMS versions while files.h functions are AMS (TIOS) functions which are only available under AMS 2.00 and later.
They do have the advantage of not requiring extra code in your program, unlike stdio.h.
Therefore the following routines must never be used with stdio.h file routines for the same file stream at the same time.
| unsigned short FAccess (const char *fileName, unsigned short mode, const char *typeName); |
Check to see if a file can be opened for a given mode without modifying the file.
FAccess checks to see if the file fileName can be opened for the given mode mode without modifying the
file first. The file, if it exists, must have the same type as typeName. fileName and typeName are normal zero-terminated C strings (i.e. you do not have to tokenize them).
mode is the given mode to be checked. This parameter can either be FM_READ_ACCESS or FM_WRITE_ACCESS.
typeName is a string which gives the type of the file to open. typeName is a normal-zero terminated C string which must contain one to four characters.
The value returned by FAccess is one of the following, as described in the FileStatusEnum enum:
| FS_OK | The file can be opened in the given mode. |
| FS_ERROR | The file cannot be opened for the specified mode. (It may be locked or not of custom (OTH) data-type.) |
| FS_NOT_FOUND | fileName does not exist. |
| FS_BAD_NAME | fileName is invalid. |
| unsigned short FClose (FILES *fsPtr); |
Close a file.
FClose closes the file fsPtr. This is required for files opened in WRITE mode. For files in
READ mode, FClose just updates the fsPtr->fileMode and fsPtr->fileStatus fields in the FILES structure.
fsPtr is a pointer to a FILES structure that was previously opened with FOpen.
FClose returns FS_OK if the file was successfully closed. There is extra overhead required
for a file that is always kept around by the file system and so closing a
file will only return an error if the file or the heap has been damaged.
See also: FAccess, FOpen, FStatus
| unsigned short FCreate (const char *fileName, const char *typeName); |
Create an empty file.
FCreate creates an empty file with the name fileName and the type typeName. It is normally only needed if multiple files must be
simultaneously opened in write mode. Filename is not a tokenized variable name (as required by the symbol
table code) but rather a normal zero-terminated C string of characters. It must not be a reserved
name. If filename does not contain a folder name, the file will be stored in
the current folder. Internally, files are stored as custom (third-party) data type files
(i.e. they are defined with the OTH_TAG). They will show up to the user in the VAR-LINK screen
as the type specified when the FILE was opened (up to four letters).
typeName must point to a normal zero-terminated C string of at most four characters which
describes the file type (FS_ERROR is returned if it does not).
FCreate returns one of the following values, as described in the FileStatusEnum enum:
| FS_OK | The file was opened for the specified mode. |
| FS_ERROR | The file cannot be opened for the specified mode. (It may be locked or not of custom (OTH) data-type.) |
| FS_BAD_NAME | fileName is invalid. |
| FS_MEMORY | Not enough memory. |
| unsigned short FDelete (const char *fileName); |
Deletes a file.
FDelete deletes the file fileName. fileName is a normal zero-terminated C string (i.e. it musn't be tokenized).
Note: FDelete may invalidate any current HSyms.
FDelete may return one of the following values as described in the FileStatusEnum enum:
| FS_OK | File deleted. |
| FS_BAD_NAME | Bad filename. |
| FS_ERROR | File not deleted because it is locked, in use, a folder, in Flash, or it does not exist. |
See also: FCreate
| short FEof (FILES *fsPtr); |
Returns TRUE if a file is at the end.
FEof returns TRUE if the file fsPtr is at the end of File mark, and FALSE otherwise. fsPtr must be a pointer to a FILES structure opened with FOpen.
Note that this is not an error condition (as returned by FStatus) and can
be changed not only by reading from a file but also by changing the current file
position.
See also: FOpen, FSetPos, FGetPos
| SYM_ENTRY *FFindFirst (unsigned short Options, const char *typeName, const char *folderName); |
Find the first file of a given type.
FFindFirst finds the first file of the type typeName and returns a SYM_ENTRY
pointer to it (or NULL if none found). typeName must point to a normal zero-terminated C string (i.e. not a tokenized form) of at most four characters which
describes the file type. Use FFindNext to find subsequent
entries, NULL will be returned after the last entry is found.
Options can be one of the following flags as described in the FindOptions enum:
| FO_NONE | When this flag is set, folderName is a string pointer to the folder to search. |
| FO_RECURSE | When this flag is set, FFindFirst searches all folders (folderName is ignored). |
See also: FFindNext, SymFindFolderName
| SYM_ENTRY *FFindNext (void); |
Find the next symbol as set up by a call to FFindFirst.
FFindNext finds the next symbol as set up by a call to FFindFirst and returns a
SYM_ENTRY pointer to it, or NULL if no more symbols can be found.
The pointer returned by FFindNext is a SYM_ENTRY pointer to a file with a type matching the one set up by a previous
call to FFindFirst. If using FO_RECURSE, then calling
SymFindFolderName will return the folder of the symbol just found.
Note that FFindFirst must have been called previously to find the first symbol.
Note: SYM_ENTRY pointers are only valid until heap compression is done or
another symbol is added to the symbol table.
See also: FFindFirst, SymFindFolderName
| unsigned short FGetC (FILES *fsPtr); |
Read a byte from an open file.
FGetC reads a byte from the open file fsPtr (which may be opened in either READ or WRITE mode) at the current file position
and returns the byte, or FS_EOF if the end of file was reached.
fsPtr is a pointer to a FILES structure previously opened with FOpen.
Note that the FILES structure pointed to by fsPtr must have been opened with FOpen.
FGetC returns the next byte in the file, or FS_EOF if the end of file has been reached.
See also: FOpen, FPutC, FRead, FSetPos
| unsigned short FGetPos (FILES *fsPtr); |
Return the current file position.
FGetPos returns the current file position (where the next read or write would occur)
for the file pointed to by fsPtr.fsPtr is a pointer to a FILES structure previously opened with FOpen.
Note that the FILES structure pointed to by fsPtr must have been previously opened with FOpen.
FGetPos returns the current file position.
See also: FOpen, FSetPos, FEof
| unsigned short FGetSize (FILES *fsPtr); |
Return the number of bytes currently stored in an opened file.
FGetSize returns the number of bytes currently stored in the opened file fsPtr.
The FILES structure pointed to by fsPtr must have been previously opened
with FOpen (either in read or in write mode).
| unsigned short FOpen (const char *fileName, FILES *fsPtr, unsigned short mode, const char *typeName); |
Open a file for a specific mode.
FOpen opens the file fileName for the mode mode. fileName is not a tokenized variable name (as required by the symbol
table code), but rather a normal zero-terminated C string of characters. It must not be a reserved
name. If fileName does not contain a folder name, the file will be stored in (or read from)
the current folder. Internally, files are stored as custom (third-party) data-type files
(OTH_TAG). They will show up to the user in the VAR-LINK screen
as the type specified when the file was opened (up to four letters).
When a file is opened with FOpen in FM_WRITE or FM_APPEND mode,
the associated variable is locked and inaccessible by any other routines in
the system. It must be closed with FClose to return the variable to a not-in-use mode,
to write the file type and the OTH_TAG, and to close
the associated buffer. For files opened in FM_READ mode, the call to FClose
will merely update the mode of the file in the FILES structure to closed and
clear the associated error status.
There is no separate mode to open a file for both reading and writing.
However, if a file is opened in FM_APPEND mode, the contents of the file
are not erased and the file may be subsequently positioned to any location
in the file (random access) and either read from or written to.
For all access modes, the given name must not be a system variable. For
FM_READ and FM_APPEND the name must correspond to an existing file of a custom data-type. For
FM_WRITE the file must either not exist or correspond to a file of a custom
data-type which is not locked or marked in-use.
Note that for files in read mode, FClose merely updates the
fsPtr->fileMode field in the FILES structure to indicate it is closed. For write mode, it must be
called to update information in the file needed by the system. While a file is
in write mode, it is marked as in-use so that no other application, nor the
system itself, will try to access it (it will not be visible in the VAR-LINK screen
either). Files in write or append mode may be accessed randomly by
using FSetPos.
Note: Any number of files may be simultaneously opened in read mode. If multiple
files are opened simultaneously in write (or append) mode, all but the
first file must already exist before they are opened. Use the FCreate routine if
they need to be created as empty files before they are opened with FOpen.
typeName must point to a normal (non-tokenized) zero-terminated C string of at most four characters
which describes the file type (FS_ERROR is returned
if it does not). If there is an existing file with the
same name as fileName, the types must match.
fsPtr is a pointer to a structure of type FILES.
The parameter mode can be one of the following commands, as described in the fileMode enum:
| FM_READ | The file must exist and can only be read. |
| FM_WRITE | Open the file for writing and erase its contents. Create the file if it does not exist. |
| FM_APPEND | If the file exists, open it for writing at the end of the file. If it does not exist, then create it and open it for writing. |
| FS_OK | The file was opened for the specified mode. |
| FS_ERROR | The file cannot be opened for the specified mode. (It may be locked or not of custom (OTH) data-type, or typeName may be invalid.) |
| FS_BAD_NAME | fileName is invalid. |
| FS_MEMORY | Not enough memory. |
See also: FAccess, FClose, FRead, FGetC, FSetPos, FStatus, FWrite, FPutC
| unsigned short FPutC (short byte, FILES *fsPtr); |
Write a byte to a file opened in write mode.
FPutC writes the byte byte to the file fsPtr opened in write mode at the current file position.
The FILES structure pointed to by fsPtr must have been opened with
FOpen in write mode.
FPutC returns FS_OK if successful, FS_ERROR if the file is not opened for write
mode or FS_MEMORY if the system is out of memory.
Note: Any error will cause the file status to be set to FS_ERROR so that multiple
writes may be performed without checking the return status as long as an
FStatus is done at the end to make sure all of the writes were successful.
This routine may cause heap compression.
See also: FOpen, FGetC, FWrite, FSetPos, FStatus
| unsigned short FRead (void *buffer, unsigned short bytesToRead, FILES *fsPtr); |
Read a given number of bytes from an open file.
FRead reads bytesToRead bytes from the open file fsPtr (which may be opened in either read or
write mode) into buffer. fsPtr must be a pointer to a FILES structure previously opened with
FOpen. buffer must be a pointer to a buffer at least bytesToRead bytes long.
FRead returns FS_OK if the file read was successful or FS_EOF if it read past the end of the file.
See also: FOpen, FWrite, FGetC, FSetPos
| unsigned short FSetBufSize (FILES *fsPtr, unsigned short newBufSize); |
Set the buffer size of a file.
FSetBufSize sets the buffer size of the file fsPtr to a new one: newBufSize.
The buffer size determines how much memory
is reallocated to the file every time a write needs more memory from the
heap. The default size (128 bytes) is set when the file is opened and
should be sufficient for most uses. Setting a larger value will make writes
faster but at the cost of possibly prematurely running out of memory.
FSetBufSize returns the value stored in newBufSize.
| unsigned short FSetPos (FILES *fsPtr, unsigned short pos); |
Set the position of the next read or write for an opened file.
FSetPos sets the position pos of the next read or write for the opened file fsPtr and returns the new
position (which may be less than specified if the end of the file is exceeded). fsPtr must be a pointer
to a FILES structure previously opened with FOpen.
pos is the file position (0 being the first byte in the file) to set.
See also: FOpen, FGetPos, FEof
| unsigned short FSetSize (FILES *fsPtr, unsigned short fileSize); |
Truncate the size of a file opened in write mode.
FSetSize truncates the size of the file opened in write mode to fileSize, which may not exceed the current file size. Return the new file size, but no more than the current size. Note that in read mode, the current file size is always returned without making any changes. fsPtr must be a pointer to a FILES structure previously opened with FOpen for writing.
| unsigned char FSetVer (FILES *fsPtr, unsigned char newVer); |
Change the version number of an opened file.
FSetVer changes the version number of the opened file fsPtr to the new one newVer and returns the old version number. Note that the file can be in read or write mode. fsPtr is a pointer to a FILES structure previously opened with FOpen in either read or write mode. The version number of a file is stored in the file’s symbol table entry. It is a byte and is used internally by TIOS to verify that a newer version of a symbol is not sent to an older TI-89, TI-92, or TI-92 Plus.
See also: FOpen
| unsigned short FStatus (FILES *fsPtr); |
Return the status of a file.
FStatus returns the status of the file fsPtr: FS_OK
if no errors have occurred, or
FS_ERROR if any errors have occurred. Note that errors accumulate so
that multiple writes may be done on a file as long as the status is checked
after the last write. The only way to clear the status is to close the file.
fsPtr must be a pointer to a FILES structure previously opened with FOpen.
See also: FOpen, FClose, FWrite, FPutC
| unsigned short FType (const char *fileName, char *buf); |
Gives the type of a specified file.
FType writes the type of the file fileName into the buffer buf as a zero-terminated string.
The buffer should be a least 5 bytes long (four bytes + a zero terminating byte). fileName file must not be opened for write mode.
FType can return one of the following values as enumerated in the FileStatusEnum enum:
| FS_OK | Ftype successfully wrote the type of the file into buf. |
| FS_ERROR | An error occured while opening the file, or the file was opened successfully, but the type field is invalid. |
| FS_BAD_NAME | fileName is invalid. |
See also: FOpen
| unsigned short FWrite (const void *buffer, unsigned short bytesToWrite, FILES *fsPtr); |
Write a specified number of bytes to a file.
FWrite writes bytesToWrite bytes of data from the buffer buffer to the output file associated with the FILES structure pointed to by fsPtr.
The data written begins at the current file position. buffer is a pointer to any object.
FWrite returns one of the following values as enumerated in the FileStatusEnum enum:
| FS_OK | The write was successful. |
| FS_ERROR | The file fsPtr is not opened in write mode. |
| FS_MEMORY | Out of memory. |
See also: FOpen, FPutC, FRead, FClose
enum fileMode {
|
An enumeration for describing possible file modes.
These constants describe the file modes stored in the FILES structure and needed by nearly every files.h function.
typedef struct fileStruct {
|
A structure for defining a file.
fileStruct is a structure for defining a file, used in commands like FOpen.
| enum FileStatusEnum {FS_OK = 0x0000, FS_EOF = 0xFFFF, FS_ERROR = 0xFFFE, FS_BAD_NAME = 0xFFFD, FS_MEMORY = 0xFFFC, FS_NOT_FOUND = 0xFFFB}; |
An enumeration for describing possible file statuses.
These constants describe the file status codes stored in the FILES structure and returned by nearly every files.h function.