The Compact-Flash Wildcard and
CF Card Software Package User Guide
<< Previous | Next>>
C: void File_Abort_Action( void )
4th: File_Abort_Action ( -- )
This abort handler is installed by Process_File. If an abort occurs during file processing, this handler attempts to "clean up" by calling Put_Default_Serial and by attempting to close the files indicated by the input_file_id and output_file_id parameters passed to Process_File. Then it executes the standard abort behavior. This function is typically not directly called by the programmer.
C: int File_Ask_Key( void )
4th: File_Ask_Key ( -- flag )
Installed by Process_File as a revector of the AskKey (?KEY in Forth) serial input primitive function that is called by File_Interpreter. Based on the key_fileid initialized by Process_File, this function returns a -1 flag if the specified file is open and if the file_position is non-negative and is less than the file's size. If the file is not open or end of file is encountered, a false flag is returned. When coding a function that takes its output from a file via Redirect (see its glossary entry), File_Ask_Key may be called repeatedly to gracefully terminate when end of file is encountered.
C: int File_Capture( int file_id )
4th: File_Capture ( fileid -- error )
Stores a stream of text that is being sent to the Mosaic controller via the active serial port into the specified open file. If used interactively, any commands following File_Capture on the same line will be ignored, but text starting with the next line will be captured. This function puts text into the specified file starting at the current file position, ending each line with 'CR' 'LF' (hex 0D 0A), DOS-style. Terminates and closes the specified file when a line containing END_CAPTURE as its first blank-delimited word is encountered; END_CAPTURE is not written to the file. Also terminates and closes the specified file if the called function File_Write returns a nonzero error code.
CAUTION: If this function or other functions that accept name strings as parameters are typed interactively at the QED-Forth monitor using the Forth syntax, the dictionary pointer must point to modifiable RAM, not flash memory. This is because Forth emplaces strings typed interactively at the current dictionary pointer, and attempts to emplace data in flash without using the specially coded flash operations will cause a software crash. To avoid this problem, you can usually type the command
1 USE.PAGE
before an interactive session; this puts the dictionary pointer on page 1 RAM on a QED-Flash board that has 128K RAM and is operating in the STANDARD.MAP mode. If only 32K of RAM is present in the center socket, you could type
HEX BO00 0 DP X!
to locate the dictionary pointer in the processor's on-chip RAM.
EXAMPLE OF INTERACTIVE USE: This interactive Forth code opens a file, captures text into it, and closes the file (note that there is 1 blank space after the leading quote in the MYFILE.TXT string):
INTEGER: myfileID
" MYFILE.TXT" COUNT W_MODE File_Open TO myfileID
myfileID File_Capture
< text to be captured goes here; may be 1 or many lines>
END_CAPTURE
C: int File_Close( int file_id )
4th: File_Close ( file_id -- error )
Marks the specified file as closed and frees its file_id. If the specified file is writeable, calls File_Flush to update the disk version of the file. If the flush operation fails, returns ERR_ATA_WRITE. If the specified file_id is invalid, returns ERR_BAD_OR_UNOPEN_FILEID.
C: xaddr File_Contents( uint file_position, int file_id )
4th: File_Contents ( file_position\file_id -- xaddr )
Returns the extended address in the file_contents array of the specified position (byte offset) for the file specified by file_id. This buffer is dimensioned by Init_File_Heap (typically called via Init_File_IO or Init_File_System) and is available to the programmer as a scratchpad area for file operations. The File_Contents buffer of a file that is explicitly opened by the user is modified only by the File_To_Memory function, and not by any of the other pre-coded file system functions. File_Copy and File_Type transiently open a file and use its File_Contents buffer as a scratchpad. C programmers should note that this buffer is in paged memory, so the paged memory access functions such as StoreChar(), FetchChar(), and CmoveMany() must be used to access the buffer.
C: int File_Copy( char* prior_name_addr, uint prior_name_page, int prior_count,
char* new_name_addr, uint new_name_page, int new_count )
4th: File_Copy ( prior_name_xaddr\prior_count\new_name_xaddr\new_count--error)
Duplicates the specified prior file's contents into a file having a specified new name in the root directory, leaving the prior file unchanged. 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_Copy function opens the two specified files; this implies that there must be at least two available file_id's 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 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.
C: void File_Emit( char c )
4th: File_Emit ( char -- )
Installed by Process_File as a replacement for (revector of) the Emit serial output primitive function that is called by File_Interpreter. This function is typically not used directly by the programmer. Based on the emit_fileid initialized by Process_File, this function calls File_Putc to write the next character to the specified file if emit_fileid is non-negative. If the emit_fileid equals -1, then a standard Emit to the active serial port is performed, and if the emit_fileid equals NO_EMIT_FILEID, then no echo is performed by Process_File; these options offer much faster execution than echoing into a file.
C: int File_EOF( int file_id )
4th: File_EOF ( file_id -- flag )
Examines the error code for the specified file and returns true (-1) if the End Of File (EOF) was encountered during a file operation; otherwise returns false (0). See also ERR_EOF, File_Error, Clear_File_Error, Report_File_Errors, and Report_File_Open_Errors.
C: int File_Error( int file_id )
4th: File_Error ( file_id -- error_code )
Returns the error code for the specified file. See the glossary entries that begin with "Err_" for a list of bit-mapped error codes. See also Clear_File_Error, Report_File_Errors, and Report_File_Open_Errors.
C: int File_Flush( int file_id )
4th: File_Flush ( file_id -- error)
If the specified file is writeable, flushes to the flash card the ATA buffers, FAT buffers, and directory entry information whose corresponding update bits were set, and then clears the update bits. The buffers are not erased. Upon failure, returns a nonzero error code; see the glossary entries that start with "ERR_" for a complete list of error codes. Unlike some file system implementations, this flush routine is called automatically as needed by the File_Read and File_Write functions, so reads and writes to a file may be freely mixed without explicit calls to File_Flush. This function is also called by File_Seek, File_Set_Pos, File_Rewind, and File_Close.
C: int File_Getc( int file_id )
4th: File_Getc ( file_id -- [char] or [err_eof] )
Reads and returns 1 character at the current file position from the specified open file in the root directory, and then increments the file position pointer by 1. If there was a prior call to the File_Ungetc function, the "ungot" character is returned in place of the first file character. Returns ERR_EOF if the end of file was reached before the character was read, or if a read error occurred. If ERR_EOF is returned, further information about the error may be obtained by executing File_Error; see its glossary entry. See also File_Read and File_Putc.
C: int File_Gets( char* dest_addr, uint dest_page, uint bufsize, int file_id )
4th: File_Gets ( dest_xaddr\bufsize\file_id -- numchars_read )
Reads a string from a text file and returns the number of characters read as a 16-bit number. Reads the contents of the specified file starting at the current file position, into the destination buffer starting at dest_addr on the specified page. C programmers will typically specify a dest_addr in common RAM, with dest_page = 0. Terminates when bufsize - 1 chars have been read, or when EOF (end of file) is reached, or when a linefeed (ASCII 0x0A) is encountered, whichever occurs first. The terminating linefeed (if present) is included at the end of the stored string. If at least 1 character was read, this function stores a null (0) byte in the destination buffer after the last char read; the null character is not included in the returned numchars_read parameter. Returns 0 if the end of file is encountered before any chars are read; in this case, nothing is stored in the destination buffer. 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. Note that, unlike fgets() in C, this File_Gets function returns numchars_read instead of returning a pointer to the destination string. Also note that the LF (linefeed) end-of-line character scheme works for DOS text files which use CR/LF (carriage return followed by linefeed) to end each line. It also works for UNIX, which ends text lines with a LF character. Use cautiously with Apple Macintosh text files, which end lines with only the CR character. Use File_Error or File_EOF to test for errors after this function executes. See also File_Puts.
Benchmark: This function typically executes in under 14 milliseconds per character.
<< Previous | Next>>
| 
