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

<< Previous | Next>>

C: NO_ECHO_FILEID
4th: NO_ECHO_FILEID ( -- n )
A constant equal to -2 that is passed as an output_fileid (emit_fileid) to the Process_File function to suppress echoing of the input file's contents to the serial port. See Process_File.

C: int Numsectors_Transferred( void )
4th: Numsectors_Transferred ( -- n )
Returns the number of sectors transferred by the most recent ATA command. This low-level function is typically not called by the programmer. Use care when interpreting the returned value, and note that the file system operations such as File_Read and File_Write may execute multiple ATA commands.

C: void Page_To_File ( uint page )
4th: Page_To_File ( page -- )
Creates a file named PAGEpp.BIN, where pp is a hexadecimal representation of the specified page, invokes File_Write to copy the contents of the specified page to the file, and closes the file. If the file already exists, it is overwritten. For example, if the specified page is 4, then PAGE04.BIN will be created and the 32 kbyte contents of page 4 will be written to the file. its contents copied to page 4. See the glossary entries for File_Write and File_To_Page. The file system must have been initialized prior to calling this function. This function prints a string to the serial output reporting the result. Output messages are:
    Page_To_File completed copy of PAGEpp.BIN
    Page_To_File couldn't open PAGEpp.BIN
    Page_To_File could not complete copy of PAGEpp.BIN
This routine is always callable by Process_File, even if the CF Card Forth headers have not been loaded onto the Mosaic controller.

C: int PCC_Present( void )
4th: PCC_Present ( -- flag )
Returns a true (-1) flag if a CF Card (formerly called a PC Card, or PCC) is installed; otherwise returns a false (0) flag.
Implementation details: Reads the card status bits. A true flag is returned if the active-low card detection bits 0 and 1 are low, the READY signal is active high, and the /WAIT signal is inactive high.

C: int Process_Autoexec( int autoexec_echo )
4th: Process_Autoexec ( autoexec_echo -- error )
This function checks for a file named AUTOEXEC.QED in the root directory of the flash card and, if the file is present, calls Process_File to interpret and execute its contents. The autoexec_echo parameter is a boolean flag that specifies whether the contents of AUTOEXEC.QED are echoed to the active serial port by Process_File. Typically, autoexec_echo is set true (nonzero) only during debugging or diagnostic sessions so that echoed source code is visible via the serial port, and is false (zero) in an actual application. If the AUTOEXEC.QED file is not found, the returned error flag is ERR_FILE_DOES_NOT_EXIST. This function is called (with autoexec_echo = FALSE) by Do_Autoexec if a CF card is present. This automated file processing capability facilitates in-field software upgrades. See the AUTOEXEC.QED examples at the end of this document.
Implementation Notes: If the AUTOEXEC.QED file is present, it is opened as a read-only file with file_id = 0, Process_File is called to interpret its contents, and then the file is closed. As mentioned above, if this function is called by Do_Autoexec, the echo is suppressed. If you need to monitor the echoed output from the processing of the AUTOEXEC.QED file via the serial port, you can explicitly accomplish this by placing the following Forth command at the top of the AUTOEXEC.QED file:
    CFA.FOR EMIT1 UEMIT X!
To direct the output to the secondary serial port, simply substitute EMIT2 for EMIT1 (assuming that the secondary serial port has been initialized). Note that the programmer can explicitly call this function from an autostart or priority autostart routine after calling Init_File_IO or Init_File_System. If the contents of AUTOEXEC.QED cause a crash or abort, then upon the next startup during which the CF Card is not present, Put_Default_Serial will be called to vector the serial input primitives Key and AskKey (KEY and ?KEY in Forth) back to their standard serial port versions if they previously pointed to File_Key/File_Ask_Key. In other words, to recover from a buggy AUTOEXEC.QED file, simply remove the CF Card from its socket.

C: void Process_File( int input_file_id, int output_file_id )
4th: Process_File ( input_fileid\output_fileid -- )
This powerful function processes (that is, interprets and executes) the contents of the ASCII text file specified by input_fileid, and optionally directs the serial output (including echoing of the input contents) to the file indicated by output_file_id. This function is called by Process_Autoexec (see its glossary entry) to automatically check for and process a file named AUTOEXEC.QED. This function can be explicitly called by the programmer from within a function or from within a file that is itself being processed by Process_File. In other words, file processing can be nested. 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). Note that execution speed is greatly enhanced if the output is not directed to a file. 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 File_Interpreter to process the specified input file. Note that the specified input file and output file must be open before this function is called; see File_Open. The File_Interpreter function processes all of the contents of the file starting at the current file position, returning when the end of file is encountered. Then Process_File 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 CF Card in multitasking applications. The file contents must be executable QED-Forth code (note that the *.txt output file created by the C compiler contains executable QED-Forth code, so a C program can be installed into QED flash memory using this method). The file will typically contain a File_To_Memory command to rapidly load pre-compiled binary code and data into modifiable RAM or flash. Another common entry in the file may be an AUTOSTART or PRIORITY.AUTOSTART statement. See the glossary entries for AUTOSTART and PRIORITY.AUTOSTART in the Mosaic controller Glossary documentation.
To Use: If you want to interpret the executable (Forth) source code in a file, or if you want to compile the results of a *.txt file created by the C compiler, use File_Open to open the file and obtain a valid fileid, then pass it as input_fileid to process_file. If you want standard echoing of the source code to the active serial port, specify output_fileid = -1. If you want no echo, specify output_fileid = NO_ECHO_FILEID (= -2). If you want the echoed source to be stored into a file (it cannot be the input_fileid), use File_Open to open the file, and pass its output_fileid to Process_File (this will significantly slow the processing). When Process_File completes (returns), you should call File_Close to close any files that you opened.
Example of Use: See the AUTOEXEC.QED example section of this document.
Implementation Notes: This function simply passes the extended code field address (xcfa) of File_Interpreter to the Redirect function. Process_File sets SERIAL_ACCESS equal to RELEASE_ALWAYS during file processing, then restores SERIAL_ACCESS to its prior value at file end. If desired, this serial access mode may be overridden by inserting the command:
    SERIAL_ACCESS = RELEASE_NEVER; // if programming in C
or:
    RELEASE.NEVER SERIAL.ACCESS ! \ if programming in Forth.
at the top of the input file to be processed.
Caution: The RELEASE_AFTER_LINE access mode is not supported.

<< Previous | Next>>