User`s manual

48 digi.com Language
4.23.1 The Parts of a Module
A module has three parts: the key, the header, and the body. The structure of a module is:
A module begins with its BeginHeader comment and continues until either the next BeginHeader
comment or the end of the file is encountered.
4.23.1.1 Module Key
The module key is usually contained within the first line of the module header. It is a list of function and
data names separated by commas. The list of names may continue on subsequent lines.
It is important to format the BeginHeader comment correctly, otherwise Dynamic C cannot find the
contents of the module. The case of the word “beginheader” is unimportant, but it must be preceded by a
forward slash, 3 asterisks and one space (/*** ). The forward slash must be the first character on the
line. The BeginHeader comment must end with an asterisk and a forward slash ( */).
The key tells the compiler which functions exist in the module so the compiler can exclude the module if
names in the key are not referenced. Data declarations (constants, structures, unions and variables) as well
as macros and function chains (both #makechain and #funchain statements) do not need to be
named in the key if they are completely defined in the header, i.e, no extern declaration. They are fully
known to the compiler by being completely defined in the module header. An important thing to remember
is that variables declared in a header section will be allocated memory space unless the declaration is pre-
ceded with extern.
4.23.1.2 Module Header
Every line between the BeginHeader and EndHeader comments belongs to the header of the module.
When a library is linked to an application (i.e., the application has the statement: #use “library_name”),
Dynamic C precompiles every header in the library, and only the headers.
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 everything will have
global scope. It is even permissible to put function bodies in header sections, but it’s not recommended
because the function will be compiled with any application that #uses the library. Since variables declared
in a header section will be allocated memory space unless the declaration is preceded with extern, the
variable declaration should be in the module body instead of the header to save data space.
The scope of anything inside the module header is global; this includes compiler directives. Since the
headers are compiled before the module bodies, the last one of a given type of directive encountered will
be in effect and any previous ones will be forgotten.
/*** BeginHeader func1, var2, .... */
prototype for func1
extern var2
/*** EndHeader */
definition of func1
declaration for var2
possibly other functions and data
/*** BeginHeader [name
1
, name
2
, ....] */