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

<< Previous | Next>>

C: void File_Type( char* name_addr, uint name_page, int name_count )
4th: File_Type ( name_xaddr\name_count -- )
Types to the active serial port the contents of specified text file in the root directory, terminating when EOF (end of file) is reached or when a carriage return or period is typed from the terminal. Implements PauseOnKey (PAUSE.ON.KEY in Forth) functionality after each character is sent; see the glossary entry in the standard C or Forth glossary. The "pause on key" feature enables XON/XOFF flow control, and also allows the user to pause and resume the output stream by typing characters (such as the space character) from the terminal. For example, typing one space pauses the listing, and typing a second space resumes the listing. Typing a carriage return (or period) aborts the typing process and closes the file. This function uses the File_Contents buffer; see its glossary entry. Because it is typically used interactively, this function does not return an error flag; error conditions may be determined by calling File_Error after this function terminates. An error occurs if the specified filename does not exist, or if the maximum number of files are already open before this function is called. 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 calling this function from within a C program 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.
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: Typical interactive use from the terminal is as follows (note that there is 1 blank space after the leading quote in the MYFILE.TXT string):
    " MYFILE.TXT" COUNT File_Type
To pause and resume, use the space bar. To abort the listing, type a carriage return.

C: int File_Ungetc( char c, int file_id )
4th: File_Ungetc ( char\file_id -- [char] or [err_eof] )
If the specified file is open, and its file position is non-zero, and there was no previous pending "ungot" character, this function "pushes" the specified character onto the specified file stream so that it will be the pending next character accessed by any of the file read functions (File_Read, File_Gets, and File_Getc). If there is no error, this function returns the specified character; otherwise, ERR_EOF is returned.
Implementation Details: This function sets a char_pending flag (which is cleared by File_Seek, File_Set_Pos, and File_Read), saves the specified character in an internal structure, and decrements the file position pointer.

C: long File_Write( void* source_addr, uint source_page, ulong numbytes, int file_id )
4th: File_Write ( source_xaddr\d.numbytes\file_id -- d.numbytes_written )
Writes from memory to the specified open file, and returns the number of bytes written as a 32-bit number. This function writes numbytes characters starting at the specified source_addr on the specified page. C programmers will typically specify a source_addr in common RAM with source_page = 0. The bytes are placed in the file starting at the current file position, except that the file position is forced to be at the end of the file (that is, file position = filesize) if the file was opened in A_MODE or APLUS_MODE. A standard procedure is for the calling program to test whether the returned number of bytes written equals the specified input parameter numbytes, and to infer that an error condition occurred if they are unequal. If an error occurs during the write 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. Note that this function can be used to save a binary image of a compiled program into a file on the ATA flash card; to perform a software upgrade on another Mosaic controller, the file can then be loaded into a board under the control of an AUTOEXEC.QED program that calls File_To_Memory.
Implementation Details: This function uses a modified buffered I/O scheme. Two 1-sector (512-byte) buffers are maintained. Each write 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 overwriting the buffer with the partial sector contents from the source memory. The whole sectors (if present) are transferred directly from the source memory to the file on disk 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 writing data to either partial sector buffer, this File_Write 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 to the ATA flash card take approximately 125 msec per Kbyte.

C: FROM_CURRENT
4th: FROM_CURRENT ( -- n )
A constant that is passed as a parameter to the File_Seek function to indicate that the position is to be set with respect to the current file position. See File_Seek, FROM_START and FROM_END.

C: FROM_END
4th: FROM_END ( -- n )
A constant that is passed as a parameter to the File_Seek function to indicate that the position is to be set with respect to the end of the file. See File_Seek, FROM_START and FROM_CURRENT.

C: FROM_START
4th: FROM_START
( -- n ) A constant that is passed as a parameter to the File_Seek function to indicate that the position is to be set with respect to the start of the file. See File_Seek, FROM_END and FROM_CURRENT.

C: int Hidden_Sectors( void )
4th: Hidden_Sectors ( -- n )
Returns the number of “hidden” sectors on the ATA drive. This parameter is stored in the FI structure, and is initialized by ATA_ID_Drive which is called by Init_File_IO and Init_File_System. If for some reason you need to read the master boot record in the hidden sector region at the physical start of the drive, specify a startsector of -{Hidden_Sectors} and call ATA_Read.

<< Previous | Next>>