Coding Guidelines

Coding Guidelines

( by Greg Holmes )

Language Syntax 
The general rule of thumb is: built-in features in lowercase, and custom-written functions in mixed case. 
When specifying the complete syntax of a language element in documentation, the input items, parameters, and so on are referred to using the following symbols:

 Symbol  Description
< >  Indicates user input item
( )  Indicates function argument list
[ ]  Indicates optional item or list
{ }  Indicates code block or literal array
| |  Indicates code block argument list
–>  Indicates function return value
 Repeated elements if followed by a symbol
Intervening code if followed by a keyword
,  Item list separator
|  Indicates two or more mutually exclusive options
@  Indicates that an item must be passed by reference
*  Indicates a compatibility command or function

For example:

    len(<cString>|<aArray>) --> nLength

Metasymbols provide a place holder for syntax elements, and they describe the expected data types. A metasymbol consists of one or more lowercase data type designators followed by a mixed case description. This is known as Hungarian Notation.

 Designator  Description
a  Array
b  Code block
c  Character expression
d  Date expression
exp  Expression of any type
id  Literal identifier
l  Logical expression
m  Memo field
n  Numeric expression
o  Object
x  Extended expression

In this example, dnLower and dnUpper can be either date or numeric:

    @...get...range <dnLower>, <dnUpper>
Filenames and Aliases 
All filenames, in any context, are in upper case. Filenames follow DOS naming conventions (preferably limited to letters, numbers, and the underscore).

    use CUSTOMER
    nHandle := fopen('DATAFILE.DAT')

When referring to specific file types in documentation, include the period.
e.g. “A program is stored in a text file with a .PRG extension.” 
Alias names follow the same conventions as filenames, but are limited to A-Z, 0-9, and the underscore. If a filename begins with a number or contains unusual characters, an alias must be specified when the file is opened or an error will result. 
Note that CA-Clipper does not natively support Windows 95 long filenames, although third-party libraries are available to add the capability.

Fieldnames are all uppercase, and always include the alias of the table. Fieldnames may contain underscores, but should not begin with one (because the underscore is generally used to indicate an internal symbol).

    @ 10, 10 say BANKS->BRANCH
Memory Variables 
Memory variables consist of a lowercase type designator followed by a mixed case description (see Hungarian Notation). Although CA-Clipper only recognizes the first 10 characters as unique, variable names may be longer.

    cString := "Hello World"
    nYearlyAverage := CalcYearAvg()

If you use Hungarian Notation for your memory variable names and include the table alias with fieldnames, there will be no conflict between the two.

Commands, Functions, and Keywords 
All built-in commands, functions, and keywords are lowercase. In documentation, the font should be Courier or a similar font. If fonts are not available, then bold or CAPITALIZE the word for emphasis. 
Never use abbreviations — this practice is not necessary with a compiler, although it was common in the early days of dBase (which was an interpreter). 
There should never be a space between the function name and the opening parenthesis. Also, note that the iif() function should never be spelled if().

    replace CUSTOMER->CUSTNAME with cCustName
    nKey := inkey(0)

When specifying commands that have clauses in documentation, separate the keywords with an ellipsis (...) and do not include the to clause, unless it is followed by the file,print, or screen keywords.

Programmer-Defined Functions & Procedures 
These begin with an uppercase letter, followed by mixed case letters as appropriate.

    ? StripBlanks("Hello there, this will have no spaces.")

Function and procedure names may contain underscores, but should not begin with one (they may conflict with internal functions which often start with an underscore). There should be only one return statement per function or procedure, and it should not be indented.

    function SomeFunc (...)
      . <statements>
    return cResult

The return value of a function is not enclosed in parentheses, although parentheses may be used to clarify a complex expression.

    return nValue
    return (nCode * 47) + nAnswer
Preprocessor Directives 
Preprocessor directives are lowercase and are preceded by the # sign.

    #include 'INKEY.CH'

Optionally, you may use single quotes around header files that come with CA-Clipper and double quotes around your own. This convention is purely voluntary, but it helps to distinguish between the two. For example:

    #include 'INKEY.CH'
    #include "MY_APP.CH"

Manifest constants are uppercase.

    #define ESCAPE   27
    if lastkey() == ESCAPE

Pseudo-function names should also be uppercase.

    #define AREA(length, width)   ((length)*(width))
Local variables are grouped according to functionality, and may be declared on one or more lines. The declarations appear as the first code at the beginning of a function or procedure.

    procedure Main ( )
    local nTop, nLeft, nBottom, nRight
    local cOldScreen, cOldColor, nOldCursor

Variables may be declared one per line and accompanied by a description.

    local nCount        // Number of records found.
    local nTotal        // Sum of dollars.

The description can be omitted if better variable names are chosen.

    local nRecordCount
    local nDollarTotal

Variables can be initialized when they are declared, although it is often clearer (and safer) to initialize them immediately before they are used.

    local nRecordCount:=0
    local nDollarTotal:=0
The .T. and .F. are typed in uppercase.
The in-line assignment operator (:=) is used for all assignments, and the exact comparison operator (==) is used for all comparisons.

    lContinue := .T.
    nOfficeTotal := nRegionTotal := 0
    lDuplicate := (CUSTFILE->CUSTNAME == cCustName)
    if nLineCount == 4  ...
    if left(PRODUCT->CODE, 3) == left(cProdCode, 3)  ...

Although the compound assignment operators (+=-=*=, etc.) are convenient, they should not be used if readability suffers.

    // The traditional way to accumulate:
    nTotal := nTotal + INVDETAIL->PRICE
    // A good use of a compound assignment operator:
    nTotal += INVDETAIL->PRICE
    // But what does this do?
    nVal **= 2

The increment (++) and decrement (--) operators are convenient, but can lead to obscure code because of the difference between prefix and postfix usage.

    nY := nX-- - --nX        // Huh?
Whenever a list of two or more items is separated by commas, the commas are followed by a space.

    MyFunc(nChoice, 10, 20, .T.)

Spaces may be used between successive parentheses.

    DoCalc( (nItem > nTotal), .F. )
    cNewStr := iif( empty(cStr), cNewStr, cStr + chr(13) )

Spaces should surround all operators for readability.

    nValue := 14 + 5 - (6 / 4)

In declarations, often spaces are not used around the assignment operator. This tends to make searching for the declaration of a variable easier.

    local lResult:=.F., nX:=0

Thus, searching for “nX :=” would find the lines where an assignment is made, while searching for “nX:=” would find the declaration line (such as the local above).

Indenting control structures is one of the easiest techniques, yet it improves the readability the most. 
Indent control structures and the code within functions and procedures 3 spaces.

    procedure SaySomething
       do while .T.
          if nTotal < 50
             ? "Less than 50."
          elseif nTotal > 50
             ? "Greater than 50."
             ? "Equal to 50."

Case statements in a do…case structure are also indented 3 spaces.

    do case
       case nChoice == 1
          ? "Choice is 1"
       case ...
Do not use tabs in source code — insert spaces instead. Tabs cause problems when printing or when moving from one editor to another, because of the lack of a standard tab width between editors and printers. Typically, printers expand tabs to 8 spaces which easily causes nested control structures to fall off the right-hand side of the page. Commonly, a source code editing program will insert the appropriate number of spaces when the <TAB> key is hit.
Line Continuation 
When a line of code approaches the 80th column, interrupt the code at an appropriate spot with a semicolon and continue on the next line. Indent the line so that it lines up in a readable manner.

    set filter to CUSTFILE->NAME  == 'John Smith  ';
            .and. CUSTFILE->STATE == 'OR'

To continue a character string, end the first line with a quote and a plus sign and place the remainder on the next line. Try to choose a logical place in the string to break it, either at a punctuation mark or after a space.

    @ 10, 10 say "The lazy brown fox tripped over " + ;
                 "the broken branch."
Use double quotes for text that needs to be translated (will appear on the screen), and single quotes for other strings.

    ? "Hello World!"
    cColor := 'W+/B'

This is a simple but extremely effective technique because translation departments often want to see the messages in context (in the source code), so the different quote types indicate which messages are to be translated and which should be left alone.

Comments are structured just like English sentences, with a capital letter at the beginning and a period at the end.

    // Just like a sentence.
    /* This comment is longer. As you
       can see, it takes up two lines */

You may encounter old-style comment indicators if you maintain older (Summer’87 and earlier) code.

    && This is an older-style of comment indicator.
    *  The asterisk is also old.

For in-line comments, use the double slashes.

    use CUSTOMER            // Open the data file.
    goto bottom             // The last record.

Note that the ‘//‘ of in-line comments begins at column 40, if possible. This leaves enough room for a useful comment.

Source :

Simple Clipper Extensions

Simple extensions

Exact comparisons,
Name precedence,
Alias functions,
Call by reference and value,
Other Clipper extensions

C5 Memory Management

Clipper Memory Management

Once upon a time ..

PCs has a 640 KB memory limit and Clipper programmers was must struggled with errors such as Memory overflow, Conventional memory exhausted, Stack overflow and so on…

This article mainly focused on this subject.

In our modern era we haven’t such problems, because we have gigabytes of memory installed in our computers. Morever OS’s offers to us immense memory management possibilities transparent to us. Like we have unlimited memory to use.

But nothing can be unlimited …

This article of Roger Donnay has very useful info about efficient ways to using memory; and especially variable handling.

#command and #translate

What are #command and #translate directives ?

#command | #translate :

Specify a user-defined command or translation directive.

Syntax :

#command <matchPattern> => <resultPattern>
#translate <matchPattern> => <resultPattern>

Arguments :

<matchPattern> is the pattern the input text should match.

<resultPattern> is the text produced if a portion of input text matches the <matchPattern>.

The => symbol between <matchPattern> and <resultPattern> is, along with #command or #translate, a literal part of the syntax that must be specified in a #command or #translate directive. The symbol consists of an equal sign followed by a greater than symbol with no intervening spaces. Do not confuse the symbol with the >= or the <= comparison operators.

Description :

#command and #translate are translation directives that define commands and pseudofunctions. Each directive specifies a translation rule. The rule consists of two portions: a match pattern and a result pattern. The match pattern matches a command specified in the program (.prg) file and saves portions of the command text (usually command arguments) for the result  pattern to use. The result pattern then defines what will be written to the result text and how it will be written using the saved portions of the matching input text.

#command and #translate are similar, but differ in the circumstance under which their match patterns match input text.

A #command directive matches only if the input text is a complete statement, while #translate matches input text that is not a complete statement. #command defines a complete command and #translate defines clauses and pseudofunctions that may not  form a complete statement. In general, use #command for most definitions and #translate for special cases.

#command and #translate are similar to but more powerful than the #define directive. #define, generally, defines identifiers that control conditional compilation and manifest constants for commonly used constant values such as INKEY() codes. Refer to any of the header files in the \CLIP53\INCLUDE directory for examples of manifest constants defined using #define.

#command and #translate directives have the same scope as the #define directive. The definition is valid only for the current program (.prg) file unless defined in or the header specified with the /U option on the compiler command line. If defined elsewhere, the definition is valid from the line where it is specified to the end of the program file. Unlike #define, a #translate or #command definition cannot be explicitly undefined. The #undef directive has no effect on a #command or #translate definition.

As the preprocessor encounters each source line preprocessor, it scans for definitions in the following order of precedence: #define, #translate, and #command. When there is a match, the substitution is made to the result text and the entire line is reprocessed until there are no matches for any of the three types of definitions. #command and #translate rules are processed in stack-order (i.e., last in-first out, with the most recently specified rule processed first).

In general, a command definition provides a way to specify an English language statement that is, in fact, a complicated expression or function call, thereby improving the readability of source code. You can use a command in place of an expression or function call to impose order of keywords, required arguments, combinations of arguments that must be specified together, and mutually exclusive arguments at compile time rather than at runtime. This can be important since procedures and user-defined functions can now be called with any number of arguments, forcing any argument checking to occur at runtime. With command definitions, the preprocessor handles some of this.

All commands in Clipper are defined using the #command directive and supplied in the standard header file,, located in the \CLIP53\INCLUDE directory. The syntax rules of #command and #translate facilitate the processing of all Clipper and dBASE-style commands into expressions and function calls. This provides Clipper compatibility, as well as avenues of compatibility with other dialects.

When defining a command, there are several prerequisites to properly specifying the command definition. Many
pre-processor commands require more than one #command directive because mutually exclusive clauses contain a keyword or argument. For example, the @…GET command has mutually exclusive VALID and RANGE clauses and is defined with a different #command rule to implement each clause.

This also occurs when a result pattern contains different expressions, functions, or parameter structures for different clauses specified for the same command (e.g., the @…SAY command). In, there is a #command rule for @…SAY specified with the PICTURE clause and another for @…SAY specified without the PICTURE clause. Each formulation of the command is translated into a different expression. Because directives are processed in stack order, when defining more than one rule for a command, place the most general case first, followed by the more specific ones. This ensures that the proper rule will match the command specified in the program (.prg) file.

For more information and a general discussion of commands, please look at here :

Match Pattern :

The <matchPattern> portion of a translation directive is the pattern the input text must match. A match pattern is made from one or more of the following components, which the preprocessor tries to match against input text in a specific way:

. Literal values are actual characters that appear in the match pattern. These characters must appear in the input text, exactly as specified to activate the translation directive.

. Words are keywords and valid identifiers that are compared according to the dBASE convention (case-insensitive, first four letters mandatory, etc.). The match pattern must start with a Word.

#xcommand and #xtranslate can recognize keywords of more than four significant letters.

. Match markers are label and optional symbols delimited by angle brackets (<>) that provide a substitute (idMarker) to be used in the <resultPattern> and identify the clause for which it is a substitute. Marker names are identifiers and must, therefore, follow the CA-Clipper identifier naming conventions. In short, the name must start with an alphabetic or underscore character, which may be followed by alphanumeric or underscore characters.

This table describes all match marker forms:

 Match Markers :
 Match Marker Name
 <idMarker> Regular match marker
 <idMarker,...> List match marker
 <idMarker:word list> Restricted match marker
 <*idMarker*> Wild match marker
 <(idMarker)> Extended Expression match marker

Regular match marker: Matches the next legal expression in the input text. The regular match marker, a simple label, is the most general and, therefore, the most likely match marker to use for a command argument. Because of its generality, it is used with the regular result marker, all of the stringify result markers, and the blockify result marker.

List match marker: Matches a comma-separated list of legal expressions. If no input text matches the match marker, the specified marker name contains nothing. You must take care in making list specifications because extra commas will cause unpredictable and unexpected results.

The list match marker defines command clauses that have lists as arguments. Typically these are FIELDS clauses or expression lists used by database commands. When there is a match for a list match marker, the list is usually written to the result text using either the normal or smart stringify result marker. Often, lists are written as literal arrays by enclosing the result marker in curly ({ }) braces.

Restricted match marker: Matches input text to one of the words in a comma-separated list. If the input text does not match at least one of the words, the match fails and the marker name contains nothing.

A restricted match marker is generally used with the logify result marker to write a logical value into the result text. If there is a match for the restricted match marker, the corresponding logify result marker writes true (.T.) to the result text; otherwise, it writes false (.F.). This is particularly useful when defining optional clauses that consist of a command keyword with no accompanying argument. implements the REST clause of database commands using this form.

Wild match marker: Matches any input text from the current position to the end of a statement. Wild match markers generally match input that may not be a legal expression, such as #command NOTE <*x*> in, gather the input text to the end of the statement, and write it to the result text using one of the stringify result markers.

Extended expression match marker: Matches a regular or extended expression, including a file name or path specification. It is used with the smart stringify result marker to ensure that extended expressions will not get stringified, while normal, unquoted string file specifications will.

. Optional match clauses are portions of the match pattern enclosed in square brackets ([ ]). They specify a portion of the match pattern that may be absent from the input text. An optional clause may contain any of the components allowed within a <matchPattern>, including other optional clauses.

Optional match clauses may appear anywhere and in any order in the match pattern and still match input text. Each match clause may appear only once in the input text. There are two types of optional match clauses: one is a keyword followed by match marker, and the other is a keyword by itself. These two types of optional match clauses can match all of the traditional command clauses typical of the CA-Clipper command set.

Optional match clauses are defined with a regular or list match marker to match input text if the clause consists of an argument or a keyword followed by an argument (see the INDEX clause of the USE command in If the optional match clause consists of a keyword by itself, it is matched with a restricted match marker (see the EXCLUSIVE or SHARED clause of the USE command in

In any match pattern, you may not specify adjacent optional match clauses consisting solely of match markers, without generating a compiler error. You may repeat an optional clause any number of times in the input text, as long as it is not adjacent to any other optional clause. To write a repeated match clause to the result text, use repeating result clauses in the <resultPattern> definition.

Result Pattern :

The <resultPattern> portion of a translation directive is the text the preprocessor will produce if a piece of input text matches the <matchPattern>. <resultPattern> is made from one or more of the following components:

. Literal tokens are actual characters that are written directly to the result text.

. Words are Clipper language keywords and identifiers that are written directly to the result text.

. Result markers: refer directly to a match marker name. Input text matched by the match marker is written to the result text via the result marker.

This table lists the Result marker forms:

Result Markers :
Result Marker   Name
<idMarker>      Regular result marker
#<idMarker>     Dumb stringify result marker
<"idMarker">    Normal stringify result marker
<(idMarker)>    Smart stringify result marker
<{idMarker}>    Blockify result marker
<.idMarker.>    Logify result marker

Regular result marker:

Writes the matched input text to the result text, or nothing if no input text is matched. Use this, the most general result marker, unless you have special requirements. You can use it with any of the match markers, but it almost always is used with the regular match marker.

Dumb stringify result marker:

Stringifies the matched input text and writes it to the result text. If no input text is matched, it writes a null string (“”). If the matched input text is a list matched by a list match marker, this result marker stringifies the entire list and writes it to the result text.

This result marker writes output to result text where a string is always required. This is generally the case for
commands where a command or clause argument is specified as a literal value but the result text must always be written as a string even if the argument is not specified.

Normal stringify result marker:

Stringifies the matched input text and writes it to the result text. If no input text is matched, it writes nothing to the result text. If the matched input text is a list matched by a list match marker, this result marker stringifies each element in the list and writes it to the result text.

The normal stringify result marker is most often used with the blockify result marker to compile an expression while
saving a text image of the expression (See the SET FILTER condition and the INDEX key expression in

Smart stringify result marker:

Stringifies matched input text only if source text is enclosed in parentheses. If no input text matched, it writes nothing to the result text. If the matched input text is a list matched by a list match marker, this result marker stringifies each element in the list (using the same stringify rule) and writes it to the result text.

The smart stringify result marker is designed specifically to support extended expressions for commands other than SETs with <xlToggle> arguments. Extended expressions are command syntax elements that can be specified as literal text or as an expression if enclosed in parentheses. The <xcDatabase> argument of the USE command is a typical example. For instance, if the matched input for the <xcDatabase> argument is the word Customer, it is written to the result text as the string “Customer,” but the expression (cPath + cDatafile) would be written to the result text unchanged (i.e., without quotes).

Blockify result marker:

Writes matched input text as a code block without any arguments to the result text. For example, the input text x + 3 would be written to the result text as {|| x + 3}. If no input text is matched, it writes nothing to the result text. If the matched input text is a list matched by a list match marker, this result marker blockifies each element in the list.

The blockify result marker used with the regular and list match markers matches various kinds of expressions and writes them as code blocks to the result text. Remember that a code block is a piece of compiled code to execute sometime later. This is important when defining commands that evaluate expressions more than once per invocation. When defining a command, you can use code blocks to pass an expression to a function and procedure as data rather than as the result of an evaluation. This allows the target routine to evaluate the expression whenever necessary.

In, the blockify result marker defines database commands where an expression is evaluated for each record. Commonly, these are field or expression lists, FOR and WHILE conditions, or key expressions for commands that perform actions based on key values.

Logify result marker:

Writes true (.T.) to the result text if any input text is matched; otherwise, it writes false (.F.) to the result text. This result marker does not write the input text itself to the result text.

The logify result marker is generally used with the restricted match marker to write true (.T.) to the result text if an optional clause is specified with no argument; otherwise, it writes false (.F.). In, this formulation defines the EXCLUSIVE and SHARED clauses of the USE command.

. Repeating result clauses :

Are portions of the <resultPattern> enclosed by square brackets ([ ]). The text within a repeating clause is written to the result text as many times as it has input text for any or all result markers within the clause. If there is no matching input text, the repeating clause is not written to the result text. Repeating clauses, however, cannot be nested. If you need to nest repeating clauses, you probably need an additional #command rule for the current command.

Repeating clauses are the result pattern part of the #command facility that create optional clauses which have arguments. You can match input text with any match marker other than the restricted match marker and write to the result text with any of the corresponding result markers. Typical examples of this facility are the definitions for the STORE and REPLACE commands in

Notes :

. Less than operator:

If you specify the less than operator (<) in the <resultPattern> expression, you must precede it with the escape character (\).

. Multistatement lines:

You can specify more than one statement as a part of the result pattern by separating each statement with a semicolon. If you specify adjacent statements on two separate lines, the first statement must be followed by two semicolons.

Examples :

These examples encompass many of the basic techniques you can use when defining commands with the #command and #translate directives. In general, these examples are based on standard commands defined in Note, however, the functions specified in the example result patterns are not the actual functions found in, but fictitious functions specified for illustration only.

. This example defines the @…BOX command using regular match markers with regular result markers:

#command @ <top>, <left>, <bottom>, <right> BOX ;
CmdBox( <top>, <left>, <bottom>, ;
<right>,<boxstring> )

. This example uses a list match marker with a regular result marker to define the ? command:

#command ? [<list,...>] => QOUT(<list>)

. This example uses a restricted match marker with a logify result marker to implement an optional clause for a command definition. In this example, if the ADDITIVE clause is specified, the logify result marker writes true (.T.) to the result text; otherwise, it writes false (.F.):

#command RESTORE FROM <file> [<add: ADDITIVE>];
CmdRestore( <(file)>, <.add.> )

. This example uses a list match marker with a smart stringify result marker to write to the result text the list of fields specified as the argument of a FIELDS clause. In this example, the field list is written as an array with each field name as an element of the array:

#command COPY TO <file> [FIELDS <fields,...>];
CmdCopyAll( <(file)>, { <(fields)> } )

. These examples use the wild match marker to define a command that writes nothing to the result text. Do this when attempting to compile unmodified code developed in another dialect:

#command SET ECHO <*text*> =>
#command SET TALK <*text*> =>

. These examples use wild match markers with dumb stringify result markers to match command arguments specified as literals, then write them to the result text as strings in all cases:

#command SET PATH TO <*path*> => SET( _SET_PATH, #<path> )
#command SET COLOR TO <*spec*> => SETCOLOR( #<spec> )

. These examples use a normal result marker with the blockify result marker to both compile an expression and save the text version of it for later use:

#command SET FILTER TO <xpr>;
CmdSetFilter( <{xpr}>, <"xpr"> )
#command INDEX ON <key> TO <file>;
CmdCreateIndex( <(file)>, <"key">, <{key}> )

. This example demonstrates how the smart stringify result marker implements a portion of the USE command for those arguments that can be specified as extended expressions:

#command USE <db> [ALIAS <a>];
CmdOpenDbf( <(db)>, <(a)> )

. This example illustrates the importance of the blockify result marker for defining a database command. Here, the FOR and WHILE conditions matched in the input text are written to the result text as code blocks:

#command COUNT [TO <var>];
[FOR <for>] [WHILE <while>];
[NEXT <next>] [RECORD <rec>] [<rest:REST>] [ALL];
<var> := 0,;
DBEVAL( {|| <var>++}, <{for}>, <{while}>,;
<next>, <rec>, <.rest.> )

. In this example the USE command again demonstrates the types of optional clauses with keywords in the match pattern. one clause is a keyword followed by a command argument, and the second is solely a keyword:

#command USE <db> [<new: NEW>] [ALIAS <a>] ;
[INDEX <index,...>][<ex: EXCLUSIVE>] ;
[<sh: SHARED>] [<ro: READONLY>];
CmdOpenDbf(<(db)>, <(a)>, <.new.>,;
IF(<.sh.> .OR. <.ex.>, !<.ex.>, NIL),;
<.ro.>, {<(index)>})

. This example uses the STORE command definition to illustrate the relationship between an optional match clause and a repeating result clause:

#command STORE <value> TO <var1> [, <varN> ];
<var1> := [ <varN> := ] <value>

. This example uses #translate to define a pseudofunction:

#translate AllTrim(<cString>) => LTRIM(RTRIM(<cString>))

Linker Terms

Dynamic Overlay :

Allows a module’s code to be divided into pages to be brought into and out of memory on a least recently used basis.

Freeformat :

The suggested command interface for .RTLink, allowing you to specify linker commands in any order on the command line. It is easier to create, examine and change FREEFORMAT command lines. It is compatible with the Plink86-Plus syntax.

Group :

An Intel 8086 addressing classification defining a collection of segments to be addressed using the same segment register. Note that a group is not a section but rather a logical concept used only for addressing.

Incremental Linking :

The ability to link only the modules of an application that have been changed, greatly increasing the speed in which the link occurs.

See Also: Linking, Module

Library :

A file containing one or more object modules. Modules are extracted by linker and combined with object files to form an executable (.EXE) file or a prelink library (.PLL) file.

Linking :

The process in which object files and libraries are combined and references are resolved to produce a relocatable memory image (generally, an executable).

Map File (.MAP) :

The map file (.MAP) contains information about symbol and segment addresses within the memory image created by .RTLink. It is generated when requested through the use of the appropriate command line switch. A map file generated during a link will have much more information than one produced during the creation of a prelinked library. During the .PLL creation, only symbols, names, and some relative addresses are known. During a link, the final memory layout is known, and a more detailed map can be created.

Module :

A portion of the object code that is a discrete unit. If any part of a module is linked, the entire module must be linked.

Overlay :

A section of an executable program that shares memory with other sections of the same program. An overlay is read into memory when the code residing in it is requested by the root (nonoverlayed) section or another overlay.

See Also: Dynamic Overlay

Positional :

The POSITIONAL command interface requires that certain items appear on the input line in a specific order. This syntax is similar to Microsoft LINK interface. Because this syntax limits the use of .RTLink overlays to one overlay area, it is recommended that the FREEFORMAT syntax be used.

Prelinked Library :

Part of the executable program that is stored external to the .EXE file. Prelinked libraries are created before producing an executable in a multistep link. This allows you to create a runtime library with code that you access from different programs, considerably speeding up the linking process.

Root :

A special section of the program that has the lowest address of all sections. This is the first section of the program loaded into memory by DOS or the RTLINKST.COM startup code. Other sections are loaded by the overlay manager.

Section :

Load module portion of an .EXE or .OVL file loaded into memory as a single unit. In a program with overlays, the root section containing the main program module loads when the program is executed. Other sections are loaded as overlays when modules within them are invoked.

See Also: Dynamic Overlay, Linking

Segment :

Code or data handled by the linker as a indivisible unit.

Static Overlay :

A section of the program that is not always resident in RAM, and shares memory with other sections. The section that is currently in use is loaded into memory, allowing a larger program to execute in less available RAM.

Swapfile :

Also known as the workfile, used by .RTLink to swap data and code in and out of memory during the linking process.

Symbol :

An assigned name for a value representing a constant or the address of code or data. There are four types of symbols used by the linker defined as follows:

. Absolute symbol: a constant

. Relative symbol: address of code or data

. Public symbol: accessed by modules other than the module in which they are defined. Public symbols are used to share procedures and variables between modules. As such, the relative address of a public symbol is assigned by the compiler during compilation.

. External symbol: a public symbol not defined in the current module. Generally, these are references into CLIPPER.LIB or EXTEND.LIB, but the compiler generates them whenever there is a procedure or user-defined function referenced but not compiled into the current module.

Undefined Symbol :

An unresolved symbol) that was never declared public by a module, but which is referenced by another module. After the public symbol definition is encountered, the symbol becomes defined (resolved). When a symbol is referenced, but not defined, it is said to be undefined.

Workfile :

See : Swapfile