> ## 4. Language

> Dynamic C is based on the C language. The programmer is expected to know programming methodologies and the basic principles of the C language. Dynamic C has its own set of libraries, which include user-callable functions. Please see the Dynamic C Function Reference Manual for detailed descriptions of these API functions. Dynamic C libraries are in source code, allowing the creation of customized libraries.

> Before starting on your application, read through the rest of this chapter to review C-language features and understand the differences between standard C and Dynamic C.

> ### 4.1 C Language Elements

> A Dynamic C program is a set of files consisting of one file with a `.c` extension and the requested library files. Each file is a stream of characters that compose statements in the C language. The language has grammar and syntax, that is, rules for making statements. Syntactic elements--often called tokens--form the basic elements of the C language. Some of these elements are listed in the table below.

> Table 1. C Language Elements
> punctuation | Symbols used to mark beginnings and endings
> names | Words used to name data and functions
> numbers | Literal numeric values
> strings | Literal character values enclosed in quotes
> directives | Words that start with `#` and control compilation
> keywords | Words used as instructions to Dynamic C
> operators | Symbols used to perform arithmetic operations

> ### 4.2 Punctuation and Tokens

> Punctuation marks serve as boundaries in C programs. The table below lists the punctuation marks and tokens.

> Table 2. Punctuation Marks and Tokens
> Symbol | Description
> : | Terminates a statement label.
> ; | Terminates a simple statement or a `do` loop. C requires these!
> , | Separates items in a list, such as an argument list, declaration list, initialization list, or expression list.
> ( ) | Encloses argument or parameter lists. Function calls always require parentheses. Macros with parameters also require parentheses. Also used for arithmetic and logical sub expressions.
> { } | Begins and ends a compound statement, a function body, a structure or union body, or encloses a function chain segment.
> // | Indicates that the rest of the line is a comment and is not compiled
> /* ... */ | Comments are nested between the `/*` and `*/` tokens.

> ### 4.3 Data

> Data (variables and constants) have type, size, structure, and storage class. Basic, or primitive, data types are shown below.

> Table 3. Dynamic C Basic Data Types
> Type | Description
> `char` | 8-bit unsigned integer. Range: 0 to 255 (0xFF)
> `int` | 16-bit signed integer. Range: -32,768 to +32,767
> `unsigned int` | 16-bit unsigned integer. Range: 0 to +65,535
> `long` | 32-bit signed integer. Range: -2,147,483,648 to +2,147,483,647
> `unsigned long` | 32-bit unsigned integer. Range 0 to 232 - 1
> `float` | 32-bit IEEE floating-point value. The sign bit is 1 for negative values. The exponent has 8 bits, giving exponents from -127 to +128. The mantissa has 24 bits. Only the 23 least significant bits are stored; the high bit is 1 implicitly. (Z180 controllers do not have floating-point hardware.) Range: 1.18 x 10-38 to 3.40 x 1038
> `enum` | Defines a list of named integer constants. The integer constants are signed and in the range: -32,768 to +32,767. This keyword is available starting with Dynamic C version 7.20.

> #### 4.3.1 Data Type Limits

> The symbolic names for the hardcoded limits of the data types are defined in `limits.h` and are shown here.

>     #define CHAR_BIT             8
>     #define UCHAR_MAX          255
>     #define CHAR_MIN             0
>     #define CHAR_MAX           255
>     #define MB_LEN_MAX           1

>     #define SHRT_MIN        -32768
>     #define SHRT_MAX         32767
>     #define USHRT_MAX        65535

>     #define INT_MIN         -32767
>     #define INT_MAX          32767
>     #define UINT_MAX         65535
>     #define LONG_MIN   -2147483647
>     #define LONG_MAX    2147483647
>     #define ULONG_MAX   4294967295

> ### 4.4 Names

> Names identify variables, certain constants, arrays, structures, unions, functions, and abstract data types. Names must begin with a letter or an underscore (`_`), and thereafter must be letters, digits, or an underscore. Names may not contain any other symbols, especially operators. Names are distinct up to 32 characters, but may be longer. Prior to Dynamic C version 6.19, names were distinct up to 16 characters, but could be longer. Names may not be the same as any keyword. Names are case-sensitive.

> ##### Examples

>     my_function              // ok
>     _block                   // ok
>     test32                   // ok

>     jumper-                  // not ok, uses a minus sign
>     3270type                 // not ok, begins with digit

>     Cleanup_the_data_now     // These names are
>     Cleanup_the_data_later   // not distinct!

> References to structure and union elements require compound names. The simple names in a compound name are joined with the dot operator (period).

>     cursor.loc.x = 10;   // set structure element to 10

> Use the `#define` directive to create names for constants. These can be viewed as symbolic constants. See Section 4.5, "Macros."

>     #define READ   10
>     #define WRITE  20
>     #define ABS     0
>     #define REL     1
>     #define READ_ABS   READ + ABS
>     #define READ_REL   READ + REL

> The term `READ_ABS` is the same as 10 + 0 or 10, and `READ_REL` is the same as 10 + 1 or 11. Note that Dynamic C does not allow anything to be assigned to a constant expression.

>     READ_ABS = 27;     // produces compiler error

> ### 4.5 Macros

> Macros can be defined in Dynamic C. A macro is a name replacement feature. Dynamic C has a text preprocessor that expands macros before the program text is compiled. The programmer assigns a name, up to 31 characters, to a fragment of text. Dynamic C then replaces the macro name with the text fragment wherever the name appears in the program. In this example,

>     #define OFFSET 12
>     #define SCALE  72
>     int i, x;
>     i = x * SCALE + OFFSET;

> the variable `i` gets the value `x * 72 + 12`. Macros can have parameters such as in the following example.

>     #define word( a, b ) (a<<8 | b)
>     char c;
>     int i, j;
>     i = word( j, c );      // same as i = (j<<8|c)

> The compiler removes the surrounding white space (comments, tabs and spaces) and collapses each sequence of white space in the macro definition into one space. It places a `\` before any `"` or `\` to preserve their original meaning within the definition.

> Dynamic C implements the `#` and `##` macro operators.

> The `#` operator forces the compiler to interpret the parameter immediately following it as a string literal. For example, if a macro is defined

>     #define report(value,fmt)\
>     printf( #value "=" #fmt "\n", value )

> then the macro in

>     report( string, %s );

> will expand to

>     printf( "string" "=" "%s" "\n", string );

> and because C always concatenates adjacent strings, the final result of expansion will be

>     printf( "string=%s\n", string );

> The `##` operator concatenates the preceding character sequence with the following character sequence, deleting any white space in between. For example, given the macro

>     #define set(x,y,z) x ## z ## _ ## y()

> the macro in

>     set( AASC, FN, 6 );

> will expand to

>     AASC6_FN();

> For parameters immediately adjacent to the `##` operator, the corresponding argument is not expanded before substitution, but appears as it does in the macro call.

> Generally speaking, Dynamic C expands macro calls recursively until they can expand no more. Another way of stating this is that macro definitions can be nested.

> The exceptions to this rule are

> 1. Arguments to the `#` and `##` operators are not expanded.
> 2. To prevent infinite recursion, a macro does not expand within its own expansion.

> The following complex example illustrates this.

>     #define A B
>     #define B C
>     #define uint unsigned int
>     #define M(x) M ## x
>     #define MM(x,y,z) x = y ## z
>     #define string something
>     #define write( value, fmt )\
>     printf( #value "=" #fmt "\n", value )

> The code

>     uint z;
>     M (M) (A,A,B);
>     write(string, %s);

> will expand first to

>     unsigned int z;          // simple expansion
>     MM (A,A,B);              // M(M) does not expand recursively
>     printf( "string" "=" "%s" "\n", string );
>                             // #value  "string" #fmt  "%s"

> then to

>     unsigned int z;
>     A = AB;                  // from A = A ## B
>     printf( "string" "=" "%s" "\n", something );
>                              // string   something

> then to

>     unsigned int z;
>     B = AB;                                 // A  B
>     printf( "string=%s\n", something );    // concatenation

> and finally to

>     unsigned int z;
>     C = AB;                                 // B  C
>     printf("string = %s\n", something);

> #### 4.5.1 Restrictions

> The number of arguments in a macro call must match the number of parameters in the macro definition. An empty parameter list is allowed, but the macro call must have an empty argument list. Macros are restricted to 32 parameters and 126 nested calls. A macro or parameter name must conform to the same requirements as any other C name. The C language does not perform macro replacement inside string literals or character constants, comments, or within a `#define` directive.

> A macro definition remains in effect unless removed by an `#undef` directive. If an attempt is made to redefine a macro without using `#undef`, a warning will appear and the original definition will remain in effect.

> ### 4.6 Numbers

> Numbers are constant values and are formed from digits, possibly a decimal point, and possibly the letters `U, L, X`, or `A-F`, or their lower case equivalents. A decimal point or the presence of the letter `E` or `F` indicates that a number is real (has a floating-point representation).

> Integers have several forms of representation. The normal decimal form is the most common.

>     10   -327   1000   0

> An integer is long (32-bit) if its magnitude exceeds the 16-bit range (-32768 to +32767) or if it has the letter `L` appended.

>     0L   -32L   45000   32767L

> An integer is unsigned if it has the letter `U` appended. It is `long` if it also has `L` appended or if its magnitude exceeds the 16-bit range.

>     0U   4294967294U   32767U   1700UL

> An integer is hexadecimal if preceded by `0x`.

>     0x7E   0xE000   0xFFFFFFFA

> It may contain digits and the letters `a-f` or `A-F`.

> An integer is octal if begins with zero and contains only the digits `0-7`.

>     0177   020000   000000630

> A real number can be expressed in a variety of ways.

>     4.5 means 4.5

>     4f means 4.0

>     0.3125 means 0.3125

>     456e-31 means 456 ×  10-31

>     0.3141592e1 means 3.141592

> ### 4.7 Strings and Character Data

> A string is a group of characters enclosed in double quotes (" ").

>        "Press any key when ready..."

> Strings in C have a terminating null byte appended by the compiler. Although C does not have a string data type, it does have character arrays that serve the purpose. C does not have string operators, such as concatenate, but library functions `strcat()` and `strncat()` are available.

> Strings are multibyte objects, and as such they are always referenced by their starting address, and usually by a `char*` variable. More precisely, arrays are always passed by address. Passing a pointer to a string is the same as passing the string. Refer to Section 4.15 for more information on pointers.

> The following example illustrates typical use of strings.

>     const char* select = "Select option\n";
>     char start[32];
>     strcpy(start,"Press any key when ready...\n");
>     printf( select );             // pass pointer to string
>     ...
>     printf( start );              // pass string

> #### 4.7.1 String Concatenation

> Two or more string literals are concatenated when placed next to each other. For example:

>     "Rabbits" "like carrots."

> becomes

>     "Rabbits like carrots."

> during compilation.

> If the strings are on multiple lines, the macro continuation character must be used. For example:

>     "Rabbits"\
>     "don't like line dancing."

> becomes

>     "Rabbits don't like line dancing."

> during compilation.

> #### 4.7.2 Character Constants

> Character constants have a slightly different meaning. They are not strings. A character constant is enclosed in single quotes (' ') and is a representation of an 8-bit integer value.

>     'a'    '\n'    '\x1B'

> Any character can be represented by an alternate form, whether in a character constant or in a string. Thus, nonprinting characters and characters that cannot be typed may be used.

> A character can be written using its numeric value preceded by a backslash.

>     \x41                 // the hex value 41
>     \101                 // the octal value 101
>     \B10000001           // the binary value 10000001

> There are also several "special" forms preceded by a backslash.

>     \a  bell
>     \f  formfeed
>     \r  carriage return
>     \v  vertical tab
>     \\  backslash
>     \'  single quote
>     \b  backspace
>     \n  newline
>     \t  tab
>     \0  null character
>     \c  the actual character c
>     \"  double quote

> ##### Examples

>     "He said \"Hello.\""   // embedded double quotes
>     const char j = 'Z';    // character constant
>     const char* MSG = "Put your disk in the A drive.\n";
>                            // embedded new line at end
>     printf( MSG );         // print  MSG
>     char* default = "";    // empty string: a single Null byte

> ### 4.8 Statements

> Except for comments, everything in a C program is a statement. Almost all statements end with a semicolon. A C program is treated as a stream of characters where line boundaries are (generally) not meaningful. Any C statement may be written on as many lines as needed. Comments (the `/*...*/` kind) may occur almost anywhere, even in the middle of a statement, as long as they begin with `/*` and end with `*/`.

> A statement can be many things. A declaration of variables is a statement. An assignment is a statement. A `while` or `for` loop is a statement. A compound statement is a group of statements enclosed in braces `{` and `}`.

> ### 4.9 Declarations

> A variable must be declared before it can be used. That means the variable must have a name and a type, and perhaps its storage class could be specified. If an array is declared, its size must be given. Root data arrays are limited to a total of 32,767 elements.

>     static int thing, array[12];     // static integer variable &
>                                      //  static integer array

>     auto float matrix[3][3];         // auto float array with 2 dimensions

>     char *message="Press any key..." // initialized pointer to char array

> If an aggregate type (`struct` or `union`) is being declared, its internal structure has to be described as shown below.

>     struct {                        // description of structure
>        char flags;
>        struct {                     // a nested structure here
>           int x;
>           int y;
>        } loc;
>     } cursor;
>     ...
>     int a;
>     a = cursor.loc.x;              // use of structure element here

> ### 4.10 Functions

> The basic unit of a C application program is a function. Most functions accept parameters--or arguments--and return results, but there are exceptions. All C functions have a return type that specifies what kind of result, if any, it returns. A function with a `void` return type returns no result. If a function is declared without specifying a return type, the compiler assumes that it is to return an `int` (integer) value.

> A function may call another function, including itself (a recursive call). The `main` function is called automatically after the program compiles or when the controller powers up. The beginning of the `main` function is the entry point to the entire program.

> ### 4.11 Prototypes

> A function may be declared with a prototype. This is so that:

> 1. Functions that have not been compiled may be called.
> 2. Recursive functions may be written.
> 3. The compiler may perform type-checking on the parameters to make sure that calls to the function receive arguments of the expected type.

> A function prototype describes how to call the function and is nearly identical to the function's initial code.

>     /* This is a function prototype.*/
>     long tick_count ( char clock_id );

>     /* This is the function's definition.*/
>     long tick_count ( char clock_id ){
>        ...
>     }

> It is not necessary to provide parameter names in a prototype, but the parameter type is required, and all parameters must be included. (If the function accepts a variable number of arguments, as `printf` does , use an ellipsis.)

>     /* This prototype is as good as the one above. */
>     long tick_count ( char );

>     /* This is a prototype that uses ellipsis. */
>     int startup ( device id, ... );

> ### 4.12 Type Definitions

> Both types and variables may be defined. One virtue of high-level languages such as C and Pascal is that abstract data types can be defined. Once defined, the data types can be used as easily as simple data types like `int`,`char`, and `float`. Consider this example.

>     typedef int MILES;    // a basic type named MILES

>     typedef struct {      // a structure type...
>        float re;          // ...
>        float im;          // ...
>     } COMPLEX;            // ...named COMPLEX

>     MILES distance;       // declare variable of type MILES
>     COMPLEX z, *zp;       // declare variable of  & pointer to type COMPLEX .

> Use `typedef` to create a meaningful name for a class of data. Consider this example.

>     typedef unsigned int node;
>     void NodeInit( node );              // type name is informative
>     void NodeInit( unsigned int );      // not very informative

> This example shows many of the basic C constructs.

>     /* Put descriptive information in your program code using  this form of comment,
>      which can be inserted anywhere and can span lines. The double slash comment
>     (shown below) may be placed at the end of a line.*/

>     #define SIZE 12                   // A symbolic constant defined.
>     int g, h;                         // Declare global integers.
>     float sumSquare( int, int );      // Prototypes for
>     void init();                      //   functions below.

>     main(){                           // Program starts here.
>        float x;                       // x is local to main.
>        init();                        // Call a void function.
>        x = sumSquare( g, h );         // x gets sumSquare value.
>        printf("x = %f",x);            // printf is a standard function.
>     }
>     void init(){                      // Void functions do things but
>        g = 10;                        //   they return no value.
>        h = SIZE;                      // Here, it uses the symbolic
>     }                                 //   constant defined above.
>     float sumSquare( int a, int b ){  // Integer arguments.
>        float temp;                    // Local variables.
>        temp = a*a + b*b;              // Arithmetic statement.
>        return( temp );                // Return value.
>     }

>     /* and here is the end of the program */

> The program above calculates the sum of squares of two numbers, `g` and `h`, which are initialized to 10 and 12, respectively. The main function calls the `init` function to give values to the global variables `g` and `h`. Then it uses the `sumSquare` function to perform the calculation and assign the result of the calculation to the variable `x`. It prints the result using the library function `printf`, which includes a formatting string as the first argument.

> Notice that all functions have `{` and `}` enclosing their contents, and all variables are declared before use. The functions `init` and `sumSquare` were defined before use, but there are alternatives to this. The "Prototypes" section explained this.

> ### 4.13 Aggregate Data Types

> Simple data types can be grouped into more complex aggregate forms.

> #### 4.13.1 Array

> A data type, whether it is simple or complex, can be replicated in an array. The declaration

>     int item[10];        // An array of 10 integers.

> represents a contiguous group of 10 integers. Array elements are referenced by their subscript.

>     j = item[n];        // The nth element of item.

> Array subscripts count up from 0. Thus, `item[7]` above is the eighth item in the array. Notice the `[` and `]` enclosing both array dimensions and array subscripts. Arrays can be "nested." The following doubly dimensioned array, or "array of arrays."

>     int matrix[7][3];

> is referenced in a similar way.

>     scale = matrix[i][j];

> The first dimension of an array does not have to be specified as long as an initialization list is specified.

>     int x[][2] = { {1, 2}, {3, 4}, {5, 6} };
>     char string[] = "abcdefg";

> #### 4.13.2 Structure

> Variables may be grouped together in structures (`struct` in C) or in arrays. Structures may be nested.

>     struct {
>        char flags;
>        struct {
>           int x;
>           int y;
>        } loc;
>     } cursor;

> Structures can be nested. Structure members--the variables within a structure--are referenced using the dot operator.

>     j = cursor.loc.x

> The size of a structure is the sum of the sizes of its components.

> #### 4.13.3 Union

> A union overlays simple or complex data. That is, all the union members have the same address. The size of the union is the size of the largest member.

>     union {
>        int ival;
>        long jval;
>        float xval;
>     } u;

> Unions can be nested. Union members--the variables within a union--are referenced, like structure elements, using the dot operator.

>     j = u.ival

> #### 4.13.4 Composites

> Composites of structures, arrays, unions, and primitive data may be formed. This example shows an array of structures that have arrays as structure elements.

>     typedef struct {
>        int *x;
>        int c[32];       // array in structure
>     } node;

>     node list[12];      // array of structures

> Refer to an element of array `c` (above) as shown here.

>     z = list[n].c[m];
>     ...
>     list[0].c[22] = 0xFF37;

> ### 4.14 Storage Classes

> Variable storage can be `auto` or `static`. The default storage class is `static`, but can be changed by using `#class auto`. The default storage class can be superseded by the use of the keyword `auto` or `static` in a variable declaration.

> These terms apply to local variables, that is, variables defined within a function. If a variable does not belong to a function, it is called a global variable--available anywhere in the program--but there is no keyword in C to represent this fact. Global variables always have `static` storage

> The term `static` means the data occupies a permanent fixed location for the life of the program. The term `auto` refers to variables that are placed on the system stack for the life of a function call.

> ### 4.15 Pointers

> A pointer is a variable that holds the 16-bit logical address of another variable, a structure, or a function. Variables can be declared pointers with the indirection operator (`*`). Conversely, a pointer can be set to the address of a variable using the `&` (address) operator.

>     int *ptr_to_i;
>     int i;
>     ptr_to_i = &i;       // set pointer equal to the address of i
>     i = 10:              // assign a value to i
>     j = *ptr_to_i;       // this sets j equal to the value in i

> In this example, the variable `ptr_to_i` is a pointer to an integer. The statement `j =` `*ptr_to_i`; references the value of the integer by the use of the asterisk. Using correct pointer terminology, the statement dereferences the pointer `ptr_to_i`. Then `*ptr_to_i` and `i` have identical values.

> Note that `ptr_to_i` and `i` do not have the same values because `ptr_to_i` is a pointer and `i` is an `int`. Note also that `*` has two meanings (not counting its use as a multiplier in others contexts) in a variable declaration such as `int *ptr_to_i;` the `*` means that the variable will be a pointer type, and in an executable statement `j = *ptr_to_i;` means "the value stored at the address contained in `ptr_to_i`."

> Pointers may point to other pointers.

>     int *ptr_to_i;
>     int **ptr_to_ptr_to_i;

>     int i,j;

>     ptr_to_i = &i;                // Set pointer equal to the address of i.
>     ptr_to_ptr_to_i = &ptr_to_i;  // Set a pointer to the pointer
>                                   // to the address of i.
>     i = 10;                       // Assign a value to i.
>     j = **ptr_to_ptr_to_i;        // This sets j equal to the value in i.

> It is possible to do pointer arithmetic, but this is slightly different from ordinary integer arithmetic. Here are some examples.

>     float f[10], *p, *q;         // an array and some ptrs
>     p = &f;                      // point p to array element 0
>     q = p+5;                     // point q to array element 5
>     q++;                         // point q to array element 6
>     p = p + q;                   // illegal!

> Because the `float` is a 4-byte storage element, the statement `q = p+5` sets the actual value of `q` to `p+20.` The statement `q++` adds 4 to the actual value of `q`. If `f` were an array of 1-byte characters, the statement `q++` adds 1 to `q`.

> Beware of using uninitialized pointers. Uninitialized pointers can reference ANY location in memory. Storing data using an uninitialized pointer can overwrite code or cause a crash.

> A common mistake is to declare and use a pointer to `char`, thinking there is a string. But an uninitialized pointer is all there is.

>     char* string;
>     ...
>     strcpy( string, "hello" );     // Invalid!
>     printf( string );              // Invalid!

> Pointer checking is a run-time option in Dynamic C. Use the compiler options command in the `OPTIONS` menu. Pointer checking will catch attempts to dereference a pointer to un allocated memory. However, if an uninitialized pointer happens to contain the address of a memory location that the compiler has already allocated, pointer checking will not catch this logic error. Because pointer checking is a run-time option, pointer checking adds instructions to code when pointer checking is used.

> ### 4.16 Pointers to Functions, Indirect Calls

> Pointers to functions may be declared. When a function is called using a pointer to it, instead of directly, we call this an indirect call.

> The syntax for declaring a pointer to a function is different than for ordinary pointers, and Dynamic C syntax for this is slightly different than the standard C syntax. Standard syntax for a pointer to a function is:

>     returntype (*name)( [argument list] );

> for example:

>     int (*func1)(int a, int b);
>     void (*func2)(char*);

> Dynamic C doesn't recognize the argument list in function pointer declarations. The correct Dynamic syntax for the above examples would be:

>     int (*func1)();
>     void (*func2)();

> You can pass arguments to functions that are called indirectly by pointer, but the compiler will not check them for correctness. The following program shows some examples of function pointer usage.

>     typedef int (*fnptr)();  // create pointer to function that returns an intenger

>     main(){
>        int x,y;
>        int (*fnc1)();        // declare var fnc1 as a pointer to an int function.
>        fnptr  fp2;           // declare var fp2 as pointer to an int function
>        fnc1 = intfunc;       // initialize fnc1 to point to intfunc()
>        fp2 = intfunc;        // initialize fp2 to point to the same function.

>        x = (*fnc1)(1,2);     // call intfunc() via fnc1
>        y = (*fp2)(3,4);      // call intfunc() via fp2

>        printf("%d\n", x);
>        printf("%d\n", y);
>     }

>     int intfunc(int x, int y){
>        return x+y;
>     }

> ### 4.17 Argument Passing

> In C, function arguments are generally passed by value. That is, arguments passed to a C function are generally copies--on the program stack--of the variables or expressions specified by the caller. Changes made to these copies do not affect the original values in the calling program.

> In Dynamic C and most other C compilers, however, arrays are always passed by address. This policy includes strings (which are character arrays).

> Dynamic C passes `structs` by value--on the stack. Passing a large `struct` takes a long time and can easily cause a program to run out of memory. Pass pointers to large `structs` if such problems occur.

> For a function to modify the original value of a parameter, pass the address of, or a pointer to, the parameter and then design the function to accept the address of the item.

> ### 4.18 Program Flow

> Three terms describe the flow of execution of a C program: sequencing, branching and looping. Sequencing is simply the execution of one statement after another. Looping is the repetition of a group of statements. Branching is the choice of groups of statements. Program flow is altered by calling a function, that is transferring control to the function. Control is passed back to the calling function when the called function returns.

> #### 4.18.1 Loops

> A `while` loop tests a condition at the start of the loop. As long as expression is true (non-zero), the loop body (some statement(s)) will execute. If expression is initially false (zero), the loop body will not execute. The curly braces are necessary if there is more than one statement in the loop body.

>     while( expression ){
>        some statement(s)
>     }

> A `do` loop tests a condition at the end of the loop. As long as expression is true (non-zero) the loop body (some statement(s)) will execute. A `do` loop executes at least once before its test. Unlike other controls, the `do` loop requires a semicolon at the end.

>     do{
>        some statements
>     }while( expression );

> The `for` loop is more complex: it sets an initial condition (exp1), evaluates a terminating condition (exp2), and provides a stepping expression (exp3) that is evaluated at the end of each iteration. Each of the three expressions is optional.

>     for( exp1 ; exp2 ; exp3 ){
>        some statements
>     }

> If the end condition is initially false, a `for` loop body will not execute at all. A typical use of the `for` loop is to count `n` times.

>     sum = 0;
>     for( i = 0; i < n; i++ ){
>        sum = sum + array[i];
>     }

> This loop initially sets `i` to 0, continues as long as `i` is less than `n` (stops when `i` equals `n`), and increments `i` at each pass.

> Another use for the `for` loop is the infinite loop, which is useful in control systems.

>     for(;;){some statement(s)}

> Here, there is no initial condition, no end condition, and no stepping expression. The loop body (some statement(s)) continues to execute endlessly. An endless loop can also be achieved with a `while` loop. This method is slightly less efficient than the `for` loop.

>     while(1)  { some statement(s) }

> #### 4.18.2 Continue and Break

> Two other constructs are available to help in the construction of loops: the `continue` statement and the `break` statement.

> The `continue` statement causes the program control to skip unconditionally to the next pass of the loop. In the example below, if `bad` is true, more statements will not execute; control will pass back to the top of the `while` loop.

>     get_char();

>     while( ! EOF ){
>        some statements
>        if( bad ) continue;
>        more statements

>     }

> The `break` statement causes the program control to jump unconditionally out of a loop. In the example below, if `cond_RED` is true, more statements will not be executed and control will pass to the next statement after the ending curly brace of the `for` loop

>     for( i=0;i<n;i++ ){
>        some statements
>        if( cond_RED ) break;
>        more statements

>     }

> The `break` keyword also applies to the`switch/case` statement described in the next section. The `break` statement jumps out of the innermost control structure (loop or switch statement) only.

> There will be times when `break` is insufficient. The program will need to either jump out more than one level of nesting or there will be a choice of destinations when jumping out. Use a `goto` statement in such cases. For example,

>     while( some statements ){
>        for( i=0;i<n;i++ ){
>           some statements
>           if( cond_RED ) goto yyy;
>           some statements
>           if( code_BLUE ) goto zzz;
>           more statements
>        }
>     }
>     yyy:
>        handle cond_RED
>     zzz:
>        handle code_BLUE

> #### 4.18.3 Branching

> The `goto` statement is the simplest form of a branching statement. Coupled with a statement label, it simply transfers program control to the labeled statement.

>         some statements
>     abc:
>         other statements
>         goto abc;
>         ...
>         more statements
>         goto def;
>         ...
>     def:
>         more statements

> The colon at the end of the labels is required.

> The next simplest form of branching is the `if` statement. The simple form of the `if` statement tests a condition and executes a statement or compound statement if the condition expression is true (non-zero). The program will ignore the `if` body when the condition is false (zero).

>     if( expression ){
>        some statement(s)
>     }

> A more complex form of the `if` statement tests the condition and executes certain statements if the expression is true, and executes another group of statements when the expression is false.

>     if( expression ){
>        some statement(s)      // if true
>     }else{
>        some statement(s)      // if false
>     }

> The fullest form of the `if` statements produces a "chain" of tests.

>     if( expr1 ){
>        some statements
>     }else if( expr2 ){
>        some statements
>     }else if( expr3 ){
>        some statements
>        ...
>     }else{
>        some statements
>     }

> The program evaluates the first expression (expr1). If that proves false, it tries the second expression (expr2), and continues testing until it finds a true expression, an `else` clause, or the end of the if statement. An `else` clause is optional. Without an `else` clause, an `if/else if` statement that finds no true condition will execute none of the controlled statements.

> The `switch` statement, the most complex branching state-ment, allows the programmer to phrase a "multiple choice" branch differently.

>     switch( expression ){

>        case const1 :
>           statements1
>           break:

>        case const2 :
>           statements2
>           break:

>        case const3 :
>           statements3
>           break:

>        ...
>        default:
>           statementsDEFAULT
>     }

> First the `switch` expression is evaluated. It must have an integer value. If one of the `const`N values matches the `switch` expression, the sequence of statements identified by the `const`N expression is executed. If there is no match, the sequence of statements identified by the `default` label is executed. (The `default` part is optional.) Unless the `break` keyword is included at the end of the case's statements, the program will "fall through" and execute the statements for any number of other cases. The `break` keyword causes the program to exit the`switch/case` statement.

> The colons (`:`) after `break`, `case` and `default` are required.

> ### 4.19 Function Chaining

> Function chaining allows special segments of code to be distributed in one or more functions. When a named function chain executes, all the segments belonging to that chain execute. Function chains allow the software to perform initialization, data recovery, and other kinds of tasks on request. There are two directives, `#makechain` and `#funcchain`, and one keyword, `segchain` that create and control function chains:

>     #makechain chain_name

> Creates a function chain. When a program executes the named function chain, all of the functions or chain segments belonging to that chain execute. (No particular order of execution can be guaranteed.)

>     #funcchain chain_name name

> Adds a function, or another function chain, to a function chain.

>     segchain chain_name { statements }

> Defines a program segment (enclosed in curly braces) and attaches it to the named function chain.

> Function chain segments defined with `segchain` must appear in a function directly after data declarations and before executable statements, as shown below.

>     my_function(){

>        /* data declarations */

>        segchain chain_x{
>            /* some statements which execute under chain_x */
>        }
>        segchain chain_y{
>           /* some statements which execute under chain_y */
>        }
>        /* function body which executes when my_function is called  */
>     }

> A program will call a function chain as it would an ordinary void function that has no parameters. The following example shows how to call a function chain that is named `recover`.

>     #makechain recover
>     ...

>     recover();

> ### 4.20 Global Initialization

> Various hardware devices in a system need to be initialized not only by setting variables and control registers, but often by complex initialization procedures. Dynamic C provides a specific function chain, `_GLOBAL_INIT`, for this purpose.

> Your program can initialize variables and take initialization action with global initialization. This is done by adding segments to the `_GLOBAL_INIT` function chain, as shown in the example below.

>     long my_func( char j );

>     main(){
>        my_func(100);
>     }

>     long my_func(char j){
>        int i;
>        long array[256];

>        // The GLOBAL_INIT section is automatically run once when the program starts up

>        #GLOBAL_INIT{
>           for( i = 0; i < 100; i++ ){
>              array[i] = i*i;
>           }
>        }

>        return array[j];   // only this code runs when the function is called
>     }

> The special directive `#GLOBAL_INIT{ }` tells the compiler to add the code in the block enclosed in braces to the `_GLOBAL_INIT` function chain. The `_GLOBAL_INIT` function chain is always called when your program starts up, so there is nothing special to do to invoke it. It may be called at anytime in an application program, but do this with caution. When it is called, all costatements and cofunctions will be initialized. See Calling _GLOBAL_INIT() for more information.

> Any number of `#GLOBAL_INIT` sections may be used in your code. The order in which the `#GLOBAL_INIT` sections are called is indeterminate since it depends on the order in which they were compiled.

> ### 4.21 Libraries

> Dynamic C includes many libraries--files of useful functions in source code form. They are located in the `LIB` subdirectory where Dynamic C was installed. The default library file extension is `.LIB`. Dynamic C uses functions and data from library files and compiles them with an application program that is then downloaded to a controller or saved to a `.bin` file.

> An application program (the default file extension is `.c`) consists of a source code file that contains a main function (called `main`) and usually other user-defined functions. Any additional source files are considered to be libraries (though they may have a `.c` extension if desired) and are treated as such. The minimum application program is one source file, containing only

>     main(){
>     }

> Libraries (both user defined and Z-World defined) are "linked" with the application through the `#use` directive. The `#use` directive identifies a file from which functions and data may be extracted. Files identified by `#use` directives are nestable, as shown below. The `#use` directive is a replacement for the `#include` directive, which is not supported in Dynamic C. Any library that is to be used in a Dynamic C program must be listed in the file `LIB.DIR`, or another `*.DIR` file specified by the user. (Starting with version Dynamic C 7.05, a different `*.DIR` file may be specified by the user in the Compiler Options dialog to facilitate working on multiple projects.)

> Figure 2. Nesting Files in Dynamic C

> Most libraries needed by Dynamic C programs are `#use`'d in the file `lib\default.h`.

> The "Modules" section later in this chapter explains how Dynamic C knows which functions and global variables in a library to use.

> ### 4.22 Support Files

> Dynamic C has several support files that are necessary in building an application. These files are listed below.

> Table 4. Dynamic C Support Files
> File Name | Purpose of File
> `DCW.CFG` | Contains configuration data for the target controller.
> `DC.HH` | Contains prototypes, basic type definitions, `#define`, and default modes for Dynamic C. This file can be modified by the programmer.
> `LIB.DIR` | Contains pathnames for all libraries that are to be known to Dynamic C. The programmer can add to, or remove libraries from this list. The factory default is for this file to contain all the libraries on the Dynamic C distribution disk. Any library that is to be used in a Dynamic C program must be listed in the file`LIB.DIR`, or another `*.DIR` file specified by the user. (Starting with version Dynamic C 7.05, a different `*.DIR` file may be specified by the user in the Compiler Options dialog to facilitate working on multiple projects.)
> `DEFAULT.H` | Contains a set of `#use` directives for each control product that Z-World ships. This file can be modified.

> ### 4.23 Headers

> The following table describes two kinds of headers used in Dynamic C libraries.

> Table 5. Dynamic C Library Headers
> Header Name | Description
> Module headers | Makes functions and global variables in the library known to Dynamic C.
> Function Description headers | Describe functions. Function headers form the basis for function lookup help.

> You may also notice some "Library Description" headers at the top of library files. These have no special meaning to Dynamic C, they are simply comment blocks.

> ### 4.24 Modules

> To write a custom source library, modules must be understood because they provide Dynamic C with the ability to know which functions and global variables in a library to use. It is important to note that the #use directive is a replacement for the #include directive, and the #include directive is not supported.

> A library file contains a group of modules. A module has three parts: the key, the header, and a body of code (functions and data).

> A module in a library has a structure like this one.

>     /*** BeginHeader func1, var2, .... */
>         prototype for func1
>         declaration for var2
>     /*** EndHeader */
>         definition of func1 and
>         possibly other functions and data

> #### 4.24.1 The Key

> The line (a specially-formatted comment)

>     /*** BeginHeader [name1, name2, ....] */

> begins the header of a module and contains the module key. The key is a list of names (of functions and data). The key tells the compiler what functions and data in the module are available for reference. It is important to format this comment properly. Otherwise, Dynamic C cannot identify the module correctly.

> If there are many names after `BeginHeader`, the list of names can continue on subsequent lines. All names must be separated by commas. A key can have no names in it and it's associated header will still be parsed by the precompiler and compiler.

> #### 4.24.2 The Header

> Every line between the comments containing `BeginHeader` and `EndHeader` belongs to the header of the module. When an application `#use`s a library, Dynamic C compiles every header, and just the headers, in the library. The purpose of a header is to make certain names defined in a module known to the application. With proper function prototypes and variable declarations, a module header ensures proper type checking throughout the application program. Prototypes, variables, structures, typedefs and macros declared in a header section will always be parsed by the compiler if the library is used, and will have global scope. It is even permissible to put function bodies in header sections, but this is not recommended. Variables declared in a header section will be allocated memory space unless the declaration is preceded with `extern` .

> #### 4.24.3 The Body

> Every line of code after the `EndHeader` comment belongs to the body of the module until (1) end-of-file or (2) the `BeginHeader` comment of another module. Dynamic C compiles the entire body of a module if any of the names in the key are referenced (used) anywhere in the application. For this reason, it is not wise to put many functions in one module regardless of whether they are actually going to be used by the program.

> To minimize waste, it is recommended that a module header contain only prototypes and `extern` declarations. (Prototypes and `extern` declarations do not generate any code by themselves.) Define code and data only in the body of a module. That way, the compiler will generate code or allocate data only if the module is used by the application program. Programmers who create their own libraries must write modules following the guideline in this section. Remember that the library must be included in `LIB.DIR` (or a user defined replacement for `LIB.DIR`) and a `#use` directive for the library must be placed somewhere in the code.

> It should be noted that there is no way to define file scope variables other than having a file consist of a single module (which would mean that all data and functions in the file would be compiled whenever a function specified in the header is compiled).

> #### Example

>     /*** BeginHeader ticks */
>         extern unsigned long ticks;
>     /*** EndHeader */
>         unsigned long ticks;
>     /*** BeginHeader Get_Ticks */
>         unsigned long Get_Ticks();
>     /*** EndHeader */
>     unsigned long Get_Ticks(){
>         ...
>     }
>     /*** BeginHeader Inc_Ticks */
>         void Inc_Ticks( int i );
>     /*** EndHeader */
>     #asm
>     Inc_Ticks::
>         or   a
>         ipset 1
>         ...
>         ipres
>         ret

>     #endasm

> There are three modules defined in this code. The first one is responsible for the variable `ticks`, the second and third modules define functions `Get_Ticks` and `Inc_Ticks` that access the variable. Although `Inc_Ticks()` is an assembly language routine, it has a function prototype in the module header, allowing the compiler to check calls to it.

> If the application program calls `Inc_Ticks()` or `Get_Ticks()` (or both), the module bodies corresponding to the called routines will be compiled. The compilation of these routines further triggers compilation of the module body corresponding to `ticks` because the functions use the variable `ticks`.

> #### 4.24.4 Function Description Headers

> Each user-callable function in a Z-World library has a descriptive header preceding the function to describe the function. Function headers are extracted by Dynamic C to provide on-line help messages.

> The header is a specially formatted comment, such as the following example.

>     /* START FUNCTION DESCRIPTION **********************
>     WrIOport                      <IO.LIB>
>     SYNTAX: void WrIOport(int portaddr, int value);
>     DESCRIPTION:
>     Writes data to the specified I/O port.
>     PARAMETER1:  portaddr - register address of the port.
>     PARAMETER2:  value - data to be written to the port.

>     RETURN VALUE:  None
>     KEY WORDS: parallel port

>     SEE ALSO:  RdIOport
>     END DESCRIPTION ***********************************/

> If this format is followed, user-created library functions will show up in the Function Lookup/Insert facility. Note that these sections are scanned in only when Dynamic C starts.

Z-World http://www.zworld.com Voice: (530) 757-3737 FAX: (530) 757-3792 sales@zworld.com