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

<< Previous | Next>>

C: void Put_Default_Serial( void )
4th: Put_Default_Serial ( -- )
If any of the key or emit serial primitives have been revectored to the file versions (File_Key, File_Ask_Key, or File_Emit), this function restores the vectors in the current user area to point to the default serial channel that is enabled at startup. This function is serial-aware: it knows whether serial1 or serial2 is the default serial port on the Mosaic controller at startup. This low level utility function is called by Init_File_IO and File_Abort_Action; it is typically not called directly by the programmer.

C: int Read_CF_Module
4th: Read_CF_Module ( -- module_num )
Returns the value that was set using the most recent call to Set_CF_Module; see its glossary entry.

C: void Redirect( int input_file_id, int output_file_id, void(*fn)(), uint fn_page )
4th: void Redirect ( input_file_id\output_file_id\fn_xcfa -- )
This powerful function is capable of revectoring the serial input and serial output primitives and then calling the function specified by the fn pointer. This enables the specified called function to accept input from a file specified by input_file_id and/or place output into a file specified by output_file_id. The specified input and output files must be in the root directory. This function assumes that Init_File_IO or Init_File_System has already executed to initialize all the required data structures. If the specified input_fileid parameter is non-negative, this function revectors the serial input primitives to point to File_Key and File_Ask_Key; if the input_fileid is negative, the serial input primitives are not changed. If the specified output_fileid parameter is non-negative or equals NO_ECHO_FILEID, this function revectors the serial output primitive to point to File_Emit. If the output_fileid is a negative value other than NO_ECHO_FILEID, the serial output primitive is not changed. (File_Emit suppresses serial output if the output_fileid equals NO_ECHO_FILEID). After revectoring the serial primitives, this function sets the serial access mode to RELEASE_ALWAYS, installs File_Abort_Action as the abort handler, and calls the function whose extended code field address is fn_xcfa (in Forth), or whose function pointer is specified by void(*fn)() on fn_page (in C). Recall that in C, function pointers are passed by referencing the function name without its parentheses, and the page is typically referenced by the macro THIS_PAGE (defined in \include\mosaic\types.h) as long as both the calling and callee functions are in the same C source code file . Note that the specified input file and output file must be open before this function is called; see File_Open. The file input and output occurs at the current file positions of the input and output files, respectively. When coding an action function that accepts input from a file, it is important that the function terminate gracefully when AskKey (?KEY in Forth) or File_Ask_Key returns 0; this indicates that the end of file has been reached. After the called action function terminates, Redirect restores all of the serial primitives, the serial access mode, and the abort handler to their prior behaviors. Note that this function does not close the input or output files; the calling program should call File_Close to take care of this. This function gets and releases the CF resource variable to ensure uncontested access to the card in multitasking applications. This function is called by Process_File which passes the xcfa of File_Interpreter as the called action function. Consult the glossary entry for Process_File to see how Redirect can be used to implement powerful capabilities.

C: uint Report_File_Errors( int file_id, char* string_addr, uint string_page, uint maxbytes )
4th: Report_File_Errors ( file_id\string_xaddr\maxbytes -- count )
Stores a string starting at the specified string_addr that describes the file errors for the open file with the specified valid file_id. Returns the number of characters placed in the string (not including the terminating null); if no errors occurred, the returned count equals zero. Limits the number of bytes stored in the string to maxbytes; however, maxbytes+1 bytes must be available in memory to accommodate the string plus the terminating null byte. If multiple errors are present, the messages are concatenated, separated by 1 space per message. Messages are 13 to 26 bytes each. After this function executes, the contents of the string may be printed to display user-friendly error diagnostics. C programmers will typically specify a string_addr in common RAM with string_page = 0. See the glossary entries that begin with "Err_" for a list of bit-mapped error codes. Note that this function does not clear the file_errors flag; use Clear_File_Error or File_Rewind to do that. A related function is Report_File_Open_Errors, which is useful to diagnose errors that occur while a file is being opened, or that occur when an invalid file_id is supplied to a function. See also File_Error.
CAUTION: C programmers should note that printf() on the Mosaic controller limits the size of the printed string to 80 characters, so maxbytes should be no greater than 79.

C: uint Report_File_Open_Errors( char* string_addr, uint string_page, uint maxbytes )
4th: Report_File_Open_Errors ( string_xaddr\maxbytes -- count )
Stores a string starting at the specified string_addr that describes the file errors that occurred during the most recent File_Open operation. Returns the number of characters placed in the string (not including the terminating null); if no errors occurred, the returned count equals zero. Limits the number of bytes stored in the string to maxbytes; however, maxbytes+1 bytes must be available in memory to accommodate the string plus the terminating null byte. If multiple errors are present, the messages are concatenated, separated by 1 space per message. Messages are 13 to 26 bytes each. After this function executes, the contents of the string may be printed to display user-friendly error diagnostics. C programmers will typically specify a string_addr in common RAM with string_page = 0. See the glossary entries that begin with "Err_" for a list of bit-mapped error codes. Note that this function does not clear the file_errors flag; use Clear_File_Error or File_Rewind to do that. Report_File_Open_Errors is useful to diagnose errors that occur while a file is being opened, or that occur when an invalid file_id is supplied to a function. A related function is Report_File_Errors, which reports errors related to open files that have a valid file_id. See also File_Error.
CAUTION: C programmers should note that the printf() implementation on the Mosaic controller limits the size of the printed string to decimal 80 characters, so maxbytes should be no greater than 79.

<< Previous | Next>>