The Compact-Flash Wildcard and
CF Card Software Package User Guide

<< Previous | Next>>

C: int File_Put_CRLF( int file_id )
4th: File_Put_CRLF ( file_id--error)
A handy utility for emplacing a carriage return (ASCII 0x0D) followed by a linefeed (ASCII 0x0A) sequence into the specified file at the current file position. Increments the file position by 2, and returns a nonzero error flag if a write error occurred.

C: long File_Read( void* dest_addr, uint dest_page, ulong numbytes, int file_id )
4th: File_Read ( dest_xaddr\d.numbytes\file_id -- d.numbtyes_read )
Reads from the specified open file to the specified destination in RAM memory, and returns the number of bytes read as a 32-bit number. (See File_To_Memory if you need to transfer data from a file to flash memory). This function reads numbytes characters starting at the current file position. The bytes are placed in memory starting at the specified dest_addr on the specified page. Programs that read small amounts of data at a time may specify a dest_addr in common RAM with dest_page = 0. A standard procedure is for the calling program to test whether the returned number of bytes read equals the specified input parameter numbytes, and to infer that an error condition occurred if they are unequal. If an error occurs during the read operation, the error code is OR'd with any prior error condition, and the composite bitmapped error code can be retrieved by calling File_Error. An end of file condition can be separately tested for by calling the File_EOF function. See the glossary entries that start with "ERR_" for a complete list of error codes.
Implementation details: If there was a prior call to the File_Ungetc function, the "ungot" character is moved to the destination in place of the first file character. This function uses a modified buffered I/O scheme. Two 1-sector (512-byte) buffers are maintained. Each read operation is broken into 3 segments that are aligned to the sectors on the flash disk device: a starting partial sector, a number of whole sectors, and an ending partial sector. The starting partial sector (if present) is handled by pre-reading the full starting sector's contents from the disk into the starting sector buffer, and then moving the partial sector contents from the buffer to the destination in memory. The whole sectors (if present) are transferred directly from the file on disk to the destination memory without the use of buffers; this speeds the process. The ending partial sector (if present) is handled in the same manner as the starting partial sector. Before reading data into either partial sector buffer, this File_Read function automatically flushes any buffers that require flushing; this allows the user to freely mix File_Read, File_Write, File_Seek, and File_Set_Pos operations without explicit calls to File_Flush.
Benchmark: Transfers from the ATA flash card to RAM take approximately 125 msec per Kbyte.

C: int File_Remove( char* name_addr, uint name_page, int name_count )
4th: File_Remove ( name_xaddr\name_count -- error )
Removes the pre-existing file from the root directory with the name and extension contained in the string at name_addr on the specified page, and returns a nonzero error code if the operation failed. The filename is passed to the function as a character string whose first byte is at the specified name_addr on the specified page. Forth programmers should pass a string that has been "unpacked" using the COUNT function. C programmers must pass name_count = -1 to inform the function that this is a null-terminated string. C programmers will typically pass the THIS_PAGE macro (defined in \include\mosaic\types.h) to specify the name_page parameter. See the glossary entry for File_Open to review the restrictions on the name. This File_Remove function opens the specified file before removing it; this implies that there must be at least one available file_id before this function is called; otherwise the ERR_TOO_MANY_FILES_OPEN error code is returned. Returns the ERR_FILE_DOES_NOT_EXIST error code if the specified file does not exist. Returns -1 if the specified file was already open. See the CAUTION notice in the File_Open glossary entry if you intend to call this function interactively.
Implementation details: This function opens the specified file in the root directory, writes 0 to the file's clusters in the FAT so no clusters are assigned, then writes the DOS-specified 0xE5 (erase character) to the first character of the name in the specified file's directory entry to mark it as erased. Finally, closes the file which flushes the modified FAT and directory entry contents to disk.

C: int File_Rename( char* prior_name_addr, uint prior_name_page, int prior_count,
      char* new_name_addr, uint new_name_page, int new_count )
4th: File_Rename ( prior_name_xaddr\prior_count\new_name_xaddr\new_count--error)
Renames the pre-existing file in the root directory with the prior name specified by the string at prior_name_addr on the specified page. Assigns the new name specified by the string at new_name_addr on the specified page. Returns a nonzero error code if the operation failed. The filenames are passed to the function as a pair of character strings, each of whose first byte is at the specified address on the specified page. Forth programmers should pass strings that have been "unpacked" using the COUNT function. C programmers must pass name_count = -1 for each string to inform the function that these are null-terminated strings. C programmers will typically pass the THIS_PAGE macro (defined in \include\mosaic\types.h) to specify the prior_name_page and new_name_page parameters. See the glossary entry for File_Open to review the restrictions on the names. This File_Rename function opens the specified file before removing it; this implies that there must be at least one available file_id before this function is called; otherwise the ERR_TOO_MANY_FILES_OPEN error code is returned. Returns the ERR_FILE_DOES_NOT_EXIST error code if the specified prior filename does not exist. Returns -1 if the specified file was already open, or if a file with the specified new filename already exists, or if the file system was not properly initialized. See the CAUTION notice in the File_Open glossary entry if you intend to call this function interactively.
Implementation details: This function opens the specified file in the root directory, rewrites the name in the specified file's directory entry, and closes the file, which flushes the modified directory entry contents to disk.

C: int File_Rewind( int file_id )
4th: File_Rewind ( file_id -- )
Sets the file position indicator of the specified file to point to the first byte of the file at offset 0, and clears the error flag associated with the file. Equivalent to calling File_Seek with offset = 0 and mode = FROM_START, except that no error value is returned. See File_Seek.

C: int File_Seek( int file_id, long offset, int mode )
4th: File_Seek ( file_id\d.offset\mode -- error )
Moves the file position indicator according to the specified signed 32-bit offset and mode; subsequent reads and writes of the specified file will start at the indicated file position. The allowed mode parameters are FROM_START, FROM_CURRENT, and FROM_END; see their glossary entries. Note that specifying offset = 0 with mode = FROM_END sets the file position to (filesize-1) which points to the last character in the file. To append a character at the end of a file, specify offset = 1 with mode = FROM_END (that is, point 1 byte beyond the end of the file). Specifying offset = 0 with mode = FROM_START points to the first byte in the file. If the seek operation is successful, the function sets the file position, calls File_Flush, undoes the effect of any prior call to Ungetc, clears the EOF (end of file) error flag, and returns zero to indicate success. If the requested position is less than 0, returns the ERR_NEGATIVE_FILE_POSN error code and leaves the file position unchanged. If the requested position is greater than the filesize, returns ERR_EOF and leaves the file position unchanged. If the specified file_id is invalid, returns ERR_BAD_OR_UNOPEN_FILEID. See also File_Set_Pos, File_Rewind, and File_Tell_Pos.

<< Previous | Next>>