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

<< Previous | Next>>

Overview of Glossary Notation

The main glossary entries presented in this document are listed in case-insensitive alphabetical order (the underscore character comes at the end of the alphabet). The keyword name of each entry is in bold typeface. Each function is listed with both a C-style declaration and a Forth-style stack comment declaration as described below. The "C:" and "4th:" tags at the start of the glossary entry distinguish the two declaration styles.

The Forth language is case-insensitive, so Forth programmers are free to use capital or lower case letters when typing keyword names in their program. Because C is case sensitive, C programmers must type the keywords exactly as shown in the glossary. The case conventions are as follows:

• Function names begin with a capital letter, and every letter after an underscore is also capitalized. Other letters are lower case, except for capitalized acronyms such as "ATA".
• Constant names and C macros use capital letters.
• Variable names use lower case letters.

It is best to discuss glossary notation in terms of an example. Here is a partial glossary entry:

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. ... Valid access modes are R_MODE, RPLUS_MODE, W_MODE, WPLUS_MODE, A_MODE, and APLUS_MODE. ... 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. ... "Long file names" (that is, more than 8 characters in the name) are not supported. ...

The C declaration is first: the returned data type is shown before the function name, and the comma-delimited input parameters are listed between parentheses showing the type and a descriptive name for each. In this example, the returned file_id (file identifier) parameter is an integer (int), and the input parameters are a pointer to a character string (char*) and the memory page upon which the string resides, the integer count of the string, and an integer access mode.

The Forth declaration contains a "stack picture" between parentheses; this is recognized as a comment in a Forth program. The items to the left of the double-dash ( -- ) are input parameters, and the item to the right of the double-dash is the output parameter. Forth is stack-based, and the first item shown is lowest on the stack. The backslash ( \ ) character is read as "under" to indicate the relative positions of the input parameters on the stack. In the Forth declaration the parameter names and their data types are combined. All unspecified parameters are 16-bit integers. Forth promotes all characters to integer type. An "xaddr" is an "extended address", meaning a 32-bit address that contains page information. The presence of "xaddr" or "xbuf" in a parameter name means that it is a 32-bit address parameter. Forth refers to 32-bit integers as "double" numbers indicated by "d." names. For example, Card_Size returns parameter "d.size".

The presence of both C and Forth declarations is helpful: the C syntax explicitly shows the types of the parameters, and the Forth declaration provides a descriptive name of the output parameter.

<< Previous | Next>>