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

<< Previous | Next>>

C: void File_Interpreter( void )
4th: File_Interpreter ( -- )
A replacement for QUIT, the standard QED-Forth interpreter. This function is typically not called directly; rather, it is invoked by Process_File. It is an infinite loop that typically takes its input from a specified file. It is capable of loading hex records (Intel or Motorola S records) into memory, calling File_To_Memory to perform a fast binary transfer of code, or executing or compiling any other valid Forth commands including commands to program flash, remove or set priority autostart vectors, or even recursively interpret other files. It is terminated by error-induced aborts, or when an end of file is encountered.
Implementation Details: This modified Forth interpreter assumes that the serial input primitives Key and AskKey have been revectored to point to File_Key and File_Ask_Key (see their glossary entries) so that input comes from a file, and that SERIAL_ACCESS has been properly initialized. These details are handled automatically by Process_File (which passes the xcfa of File_Interpreter to the Redirect function); see its glossary entry.

C: uchar File_Key( void )
4th: File_Key ( -- char )
Installed by Process_File as a revector of the Key serial input primitive function that is called by File_Interpreter. This function is typically not used directly by the programmer. Based on the key_fileid initialized by Process_File, this function calls File_Getc to get the next character from the file. If the end of file is encountered, this function returns an ASCII carriage return. No error reporting is performed via the return value; the calling program must use File_Error to trap errors such as end of file.

C: int File_Open( char* name_addr, uint name_page, int name_count, int access_mode )
4th: File_Open ( name_xaddr\name_count\access_mode -- file_id )
Opens in the root directory the file having the name and extension contained in the name_addr string, and assigns access privileges as specified by the access_mode. Returns a non-negative file_id if the open was successful. Returns -2 if the file system was not initialized (see Init_File_System); returns -1 if the open failed for any other reason. Valid access modes are R_MODE, RPLUS_MODE, W_MODE, WPLUS_MODE, A_MODE, and APLUS_MODE. The access modes behave just like the ANSI C standard access modes; see their glossary entries for details. Briefly, the modes that start with "R" (read) require that the file pre-exists. The modes that start with "W" (write) cause a like-named pre-existing file (if present) to be truncated to zero size. The modes that start with "A" (append) force any write to occur at the end of the file. The modes that include "PLUS" allow both reads and writes; otherwise, only the operation suggested by the leading letter of the mode is allowed ("R" = read, "W" or "A" = write). All files are treated as binary files (that is, text files are not stored in a different format than other files). 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. The name string may have up to 8 characters followed by an optional period and up to 3 extension characters. No leading or trailing spaces are allowed in the name string. All names are automatically converted to upper case by this function. "Long file names" (that is, more than 8 characters in the name) are not supported. The following are examples of valid names:
    myname.4th
    MYNAME.C
    MYname
    SOMEBODY.TXT
The following are invalid for the reason shown in parentheses:

C: int File_Putc( char c, int file_id )
4th: File_Putc ( char\file_id -- [char] or [err_eof] )
Writes the specified character to the specified open file in the root directory at the current file position, and increments the file position pointer by 1. Returns ERR_EOF if a write 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_Write and File_Getc.

C: int File_Puts( char* source_addr, uint source_page, uint maxchars, int file_id )
4th: File_Puts ( source_xaddr\maxchars\file_id -- numchars_written )
Writes a string to a text file and returns the number of characters written as a 16-bit number. Writes the contents from the source buffer starting at source_addr on the specified page to the specified file starting at the current file position. C programmers will typically specify a source_addr in common RAM with source_page = 0. Terminates when maxchars bytes have been written, or when a null character in the source buffer is encountered, whichever occurs first. There is no special treatment of any characters other than the null. Note that, unlike fputs() in C, this File_Puts function returns numchars_written instead of returning a pointer to the source string. Use File_Error or File_EOF to test for errors after this function executes. See also File_Gets.
Benchmark: This function typically executes in under 21 milliseconds per character.

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.

<< Previous | Next>>