<title=Compiler Directives>
<keywords=compiler directive directives include link linkwith maxlomem maxhimem minlomem minhimem align>

      The # (pound sign) indicates a compiler directive, when it occures
    as a first non-whitespace character of a line. It signifies a compiler
    action, not necessarily associated with code generation.
      The compiler directives may be also indicated by language tokens (see
    Language Description for more details).


      Directives description
      

      <link=include directive=include>
      <link=link directive=link>
      <link=linkwith directive=linkwith>
      <link=maxlomem directive=maxlomem>
      <link=minlomem directive=minlomem>
      <link=maxhimem directive=maxhimem>
      <link=minhimem directive=minhimem>
      <link=align directive=align>
      <link=define directive=define>
      <link=undef directive=undef>
      <link=ifndef directive=ifndef>
      <link=ifdef directive=ifdef>
      <link=endif directive=endif>
      <link=else directive=else>
      <link=error directive=error>

   See also :

     <link=XS.LDF Directives=XS.LDF Directives>

<title=include directive>
<keywords=include compiler directive>

         Ŀ
         include
         

              Indicated by : - a pound sign followed by the "include" string
                   (#include);
                             - 'include_k' token.

              Argument list syntax
              
                  filename1,[filename2,...filenameN]
                 "filename1,[filename2,...filenameN]"
                 <filename1,[filename2,...filenameN]>

              Description
              
                 Treats the text from specified files as if it appeared in
               the current file.
                 When the compiler encounters this directive, it will compile
               the files from its argument list, in their appearence order,
               then will continue compiling the current file.
                 This is usefull for splitting big source files into
               multiple, smaller and easier to organize modules.

              Valid examples
              

                 #include  file.inc
                 #include "file.inc"
                 #include <file.inc>

                     This will include the 'file.inc' file.

                 #include  file1.inc,file2.inc
                 #include "file1.inc,file2.inc"
                 #include <file1.inc,file2.inc>

                     This will include the 'file1.inc' and 'file2.inc' files.


<title=link directive>
<keywords=link compiler directive>

         Ŀ
         link
         

              Indicated by : - a pound sign followed by the "link" string
                   (#link);
                             - 'link_k' token.

              Argument list syntax
              
                  filename1,[filename2,...filenameN]
                 "filename1,[filename2,...filenameN]"
                 <filename1,[filename2,...filenameN]>

              Description
              
                 Treats the code from specified object files as if its
               source code was included in the current file, at the current
               position.
                 When the compiler encounters this directive, it will load
               and append the object code to the current file compiled code.
                 This is usefull for splitting the source files into
               multiple pre-compiled modules, speeding up the compiling
               process.

              Valid examples
              

                 #link  file.xso
                 #link "file.xso"
                 #link <file.xso>

                     This will link to the current file the 'file.xso'
                   object file.

                 #link  file1.xso,file2.xso
                 #link "file1.xso,file2.xso"
                 #link <file1.xso,file2.xso>

                     This will link to the current file the 'file1.xso' and
                   'file2.xso' object files.


<title=linkwith directive>
<keywords=linkwith compiler directive link>

         Ŀ
         linkwith
         

              Indicated by : - a pound sign followed by the "linkwith" string
                   (#linkwith);
                             - 'linkwith_k' token.

              Argument list syntax
              
                  filename1,[filename2,...filenameN]
                 "filename1,[filename2,...filenameN]"
                 <filename1,[filename2,...filenameN]>

              Description
              
                  Adds the specified object files to this current file link
                list. This link list specifies what files should be linked
                with the current file.
                  This is very usefull in case of libraries including.
                Normaly every library has an include file associated, that
                contains the library items declarations. Including this
                declarations file to a project means that the library that
                contains the definitions of the functions and variables used
                in project must be linked with the project. Normaly, this
                mean the library must be specified in the linker's command
                line. When are used many libraries, this will be complicated
                and unhandy. To simplify this process, into the include files
                should be specified the library (or libraries) that contains
                (contain) the code to be linked with the current project.This
                is possible using the 'linkwith' directive.


              Valid examples
              

                 #linkwith  file.xso
                 #linkwith "file.xso"
                 #linkwith <file.xso>

                      Whenever the current file will be linked, the 'file.xso'
                    file will be linked, too.

                 #linkwith  file1.xso,file2.xso
                 #linkwith "file1.xso,file2.xso"
                 #linkwith <file1.xso,file2.xso>

                      Whenever the current file will be linked, the
                    'file1.xso' and 'file2.xso' files will be linked, too.



<title=maxlomem directive>
<keywords=maxlomem compiler directive memory malloc lalloc mem>

         Ŀ
         maxlomem
         

              Indicated by : - a pound sign followed by the "maxlomem" string
                   (#maxlomem);
                             - 'maxlomem' token.

              Argument list syntax
              

                 number_of_bytes

              Description
              

                 Limits the maximum amount of low (DOS) memory to be allocated
               on program start. By default, the all free DOS memory will
               be allocated. But, if we need some DOS memory to be left free
               for DOS processes (eg.  DOS exec) the maximum amount of DOS
               memory allocated must be specified using this directive.

              Valid examples
              

                 #maxlomem 65536

                     Maximum 65536 bytes of DOS memory will be allocated.



<title=minlomem directive>
<keywords=minlomem compiler directive memory malloc lalloc mem>

         Ŀ
         minlomem
         

              Indicated by : - a pound sign followed by the "minlomem" string
                   (#minlomem);
                             - 'minlomem' token.

              Argument list syntax
              

                 number_of_bytes

              Description
              

                 Specifies the minimum amount of low (DOS) memory to be
               allocated on program start. If this memory can't be allocated,
               the program will not start. This can be used to avoid  the
               'lalloc' function failures. The 'lalloc' function will alloc
               for the user a piece of the DOS memory allocated on program
               start. If the current program needs 8192 bytes of DOS memory,
               and this directive is used, the program will not start unless
               8192 bytes of DOS memory can be allocated.


              Valid examples
              

                 #minlomem 8192

                     Minimum 8192 bytes of DOS memory will be allocated.


<title=maxhimem directive>
<keywords=maxhimem compiler directive memory malloc halloc mem>

         Ŀ
         maxhimem
         

              Indicated by : - a pound sign followed by the "maxhimem" string
                   (#maxhimem);
                             - 'maxhimem' token.

              Argument list syntax
              

                 number_of_bytes

              Description
              

                 Specifies the maximum amount of high (extended) memory that
               will be allocated on program start. By default, maximum 32Mb
               will be allocated. If more memory is needed, this directive
               must be used to specify the new maximum amount of high memory
               allocated. This can be also used to limit the memory allocated,
               If some memory must be left free for other processes.


              Valid examples
              

                 #maxlomem 4194304

                     Maximum 4194304 bytes (4Mb) of high memory will be
                   allocated.


<title=minhimem directive>
<keywords=minhimem compiler directive memory malloc halloc mem>

         Ŀ
         minhimem
         

              Indicated by : - a pound sign followed by the "minhimem" string
                   (#minhimem);
                             - 'minhimem' token.

              Argument list syntax
              

                 number_of_bytes

              Description
              

                 Specifies the minimum amount of high (extended) memory to
               be allocated on program start. The program will not start if
               this minimum amount of high memory cannot be allocated. This
               may be used to avoid the memory allocation failures : if the
               program needs at least 1Mb of memory, and this directive is
               used, the program will not start unless it can allocate 1Mb of
               high memory.


              Valid examples
              

                 #minlomem

                     Minimum 1048576 bytes (1Mb) of high memory will be
                   allocated.


<title=align directive>
<keywords=align compiler directive>

         Ŀ
         align
         

              Indicated by : - a pound sign followed by the "align" string
                   (#align);
                             - 'align' token.

              Argument list syntax
              

                 power_of_2_number

              Description
              
                 The current code will be aligned to the specified number of
               bytes.
                 See also the 'Oav' and 'Oaf' compiler options.

              Valid examples
              

                 #align 4

                     The code will be aligned on dword. If the current code
                   offset was 161, then the new current code offset will
                   become 164.

<end>

<title=define directive>
<keywords=define macro directive>

  Ŀ
   define directive         <link=Compiler Directives=Compiler Directives>
  

   Indicated by : - a pound sign followed by the "define" string
                    (#define);
                  - 'define' token.

   Argument list syntax :

     <token> [<token list>]

   Description

     Defines a macro.
     Macros provide a mechanism for token replacement, allowing
    a token to be replaced with a group of tokens.
    All the subseqent instances of the specified token in the
    source text will be replaced with the specified list of
    tokens.

      <token list> can be void.
      <token> can be of any type (identifier, operator etc.).


    Valid examples

    #define PI 3.14159
    //...
    float f=PI*2;   //PI will be replaced with 3.14159

    #define ++ +=1          //define ++ as +=1
    //...
    i++;      //will be replaced with i+=1;

   See also :

     <link=defin directivee=define directive>
     <link=undef directive=undef directive>
     <link=ifdef directive=ifdef directive>
     <link=ifnde directivef=ifndef directive>
     <link=endif directive=endif directive>
     <link=else directive=else directive>
     <link=Macro Definition Example=Macro Definition Example>

<end>


<title=undef directive>
<keywords=undef macro>

  Ŀ
   undef directive         <link=Compiler Directives=Compiler Directives>
  

    Indicated by : - a pound sign followed by the "undef" string
                     (#undef);
                   - 'undef' token.

    Argument list syntax

      <token>

    Description :

      Undefines a macro, previously defined with a <link=define=define>
      directive.

    Valid examples :

       #define PI 3.14159
       //...
       #undef PI

   See also :

     <link=define directive=define directive>
     <link=undef directive=undef directive>
     <link=ifdef directive=ifdef directive>
     <link=ifndef directive=ifndef directive>
     <link=endif directive=endif directive>
     <link=else directive=else directive>
     <link=Macro Definition Example=Macro Definition Example>

<end>


<title=ifdef directive>
<keywords=ifdef macro directive>

  Ŀ
   ifdef directive         <link=Compiler Directives=Compiler Directives>
  

    Indicated by : - a pound sign followed by the "ifdef" string
                     (#ifdef);
                   - 'ifdef' token.

    Argument list syntax

      <token>

    Description :

      Conditional compilation directive.
      If a symbol specified by <token> is defined, the compiler will compile
     the lines that follow the ifdef directive, until the first else or
     endif directive. Otherwise, it will skip the lines that follow until
     the first else or endif directive.

    Valid examples :

       #ifdef PI
       //...            //lines compiled if PI is defined
       #endif

       #ifdef PI
       //...            //lines compiled if PI is defined
       #else
       //...            //lines compiled if PI is not defined
       #endif

   See also :

     <link=define directive=define directive>
     <link=undef directive=undef directive>
     <link=ifdef directive=ifdef directive>
     <link=ifndef directive=ifndef directive>
     <link=endif directive=endif directive>
     <link=else directive=else directive>
     <link=Macro Definition Example=Macro Definition Example>

<end>

<title=ifndef directive>
<keywords=ifndef macro directive>

  Ŀ
   ifndef directive         <link=Compiler Directives=Compiler Directives>
  

    Indicated by : - a pound sign followed by the "ifndef" string
                     (#ifndef);
                   - 'ifndef' token.

    Argument list syntax

      <token>

    Description :

      Conditional compilation directive.
      If a symbol specified by <token> is not defined, the compiler will
     compile the lines that follow the ifdef directive, until the first
     else or endif directive. Otherwise, it will skip the lines that follow
     until the first else or endif directive.

    Valid examples :

       #ifndef PI
       //...            //lines compiled if PI is not defined
       #endif

       #ifndef PI
       //...            //lines compiled if PI is not defined
       #else
       //...            //lines compiled if PI is defined
       #endif

   See also :

     <link=define directive=define directive>
     <link=undef directive=undef directive>
     <link=ifdef directive=ifdef directive>
     <link=ifndef directive=ifnde directivef>
     <link=endif directive=endif directive>
     <link=else directive=else directive>
     <link=Macro Definition Example=Macro Definition Example>

<end>

<title=endif directive>
<keywords=endif macro directive>

  Ŀ
   endif directive         <link=Compiler Directives=Compiler Directives>
  

    Indicated by : - a pound sign followed by the "endif" string
                     (#endif);
                   - 'endif' token.

    No arguments.

    Description :

      Conditional compilation directive.
      Closes a conditional compilation section opened by <link=ifdef directive=ifdef directive>
      or <link=ifndef directive=ifndef directive>.

    Valid examples :

       #ifdef PI
       //...            //lines compiled if PI is defined
       #endif

       #ifdef PI
       //...            //lines compiled if PI is defined
       #else
       //...            //lines compiled if PI is not defined
       #endif

   See also :

     <link=define directive=define directive>
     <link=undef directive=undef directive>
     <link=ifdef directive=ifdef directive>
     <link=ifndef directive=ifndef directive>
     <link=endif directive=endif directive>
     <link=else directive=else directive>
     <link=Macro Definition Example=Macro Definition Example>

<end>

<title=else directive>
<keywords=else macro directive>

  Ŀ
   else directive         <link=Compiler Directives=Compiler Directives>
  

    Indicated by : - a pound sign followed by the "else" string
                     (#else);
                   - 'elseif' token.

    No arguments.

    Description :

      Conditional compilation directive.
      See <link=ifdef directive=ifdef directive> and
          <link=ifndef directive=ifndef directive>.

    Valid examples :

       #ifdef PI
       //...            //lines compiled if PI is defined
       #else
       //...            //lines compiled if PI is not defined
       #endif

   See also :

     <link=define directive=define directive>
     <link=undef directive=undef directive>
     <link=ifdef directive=ifdef directive>
     <link=ifndef directive=ifndef directive>
     <link=endif directive=endif directive>
     <link=else directive=else directive>
     <link=Macro Definition Example=Macro Definition Example>

<end>

<title=error directive>
<keywords=error directive>

  Ŀ
   error directive         <link=Compiler Directives=Compiler Directives>
  

    Indicated by : - a pound sign followed by the "error" string
                     (#error);
                   - 'error' token.

    Argument list syntax :

      <message>

    Description :
    
      Issues an error message.
      If the line of code containing this directive is compiled, a fatal
     error message will be issued for this line and include the text
     defined by <message>.

    Valid examples :

      #ifndef VIDEOMODE
      #error Video mode is not defined!
      #endif

<end>





<title=Macro Definition Example>
<keywords=define undef ifdef ifndef else endif macro directive>

#include stdio.xh

//if you comment the following line, PI will be defined as 3.2
//otherwise, it will be defined as 3.3

#define PI 3.14159

#ifndef PI
#define PI 3.2
#else
#undef PI
#endif

#ifndef PI
#define PI 3.3
#endif

#define PI2  PI/2.0

main()
{
  printf("%f\n",PI2);
}

See also :
  <link=Compiler Directives=Compiler Directives>

<end>