C5_#xcommand | #xtranslate

#xcommand | #xtranslate
 Specify a user-defined command or translation directive
------------------------------------------------------------------------------
 Syntax

     #xcommand   <matchPattern> => <resultPattern>
     #xtranslate <matchPattern> => <resultPattern>

 Arguments

     <matchPattern> is the pattern to match in the input text.

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

 Description

     The #xcommand and #xtranslate directives work like #command and
     #translate except that they overcome the dBASE keyword length
     limitation.  They are significant beyond the first four letters, limited
     only by available memory.  All other rules apply.

See Also: #command

C5_#undef

#undef
 Remove a #define macro definition
------------------------------------------------------------------------------
 Syntax

     #undef <identifier>

 Arguments

     <identifier> is the name of the manifest constant or pseudofunction
     to remove.

 Description

     #undef removes an identifier defined with the #define directive. After
     an #undef, the specified identifier becomes undefined.  Use #undef to
     remove an identifier before you redefine it with #define, preventing the
     compiler warning that occurs when an existing identifier is redefined.
     Also, use #undef to make conditional compilation specific to certain
     sections of a program.

 Examples

     .  To define and then undefine a manifest constant and a
        pseudofunction:

        #define K_ESC  27
        #define MAX(x, y)   IF(x > y, x, y)
        .
        . <statements>
        .
        #undef K_ESC
        #undef MAX

     .  To use #undef to undefine an identifier before redefining it:

        #define DEBUG
        .
        . <statements>
        .
        #undef DEBUG
        #define DEBUG   .T.

     .  To undefine an identifier if it exists, and otherwise define
        it for later portions of the program file:

        #ifdef TEST
           #undef TEST
        #else
           #define TEST
        #endif

See Also: #define #ifdef #ifndef



C5_#stdout

#stdout
 Send literal text to the standard output device
------------------------------------------------------------------------------
 Syntax

     #stdout [<messageText>]

 Arguments

     <messageText> is the text of the message to display.  <messageTest>
     is a literal character string.  Do not enclose the message in quotation
     marks unless you want them to appear as part of the display.

 Description

     #stdout causes the compiler to output the literal text to the standard
     output device (stdout) during compilation.  If <messageText> is not
     specified, a carriage return/line feed pair echoes to stdout.

     Warning!  Manifest constants are not translated in #stdout.
     Implementation is identical to #error with the following exceptions:
     output is written to STDOUT and no compiler error is generated.

 Examples

     This example demonstrates use of #stdout:

     #ifdef DEBUG
        #stdout Compiling debugging version...
     #endif

     PROCEDURE Main()

     ? "Hello world"
     RETURN

     #stdout End of "Hello World" program

See Also: #error

C5_#include

#include
 Include a file into the current source file
------------------------------------------------------------------------------
 Syntax

     #include "<headerFileSpec>"

 Arguments

     <headerFileSpec> specifies the name of another source file to
     include in the current source file.  As indicated in the syntax, the
     name must be enclosed in double quotation marks.

     <headerFileSpec> may contain an explicit path and file name as well as a
     file extension.  If, however, no path is specified, the preprocessor
     searches the following places:

     .  Source file directory

     .  Directories supplied with the /I option

     .  Directories specified in the INCLUDE environment variable

     #include directives may be nested up to 15 levels deep--that is, a file
     that has been included may contain #include directives, up to 15 levels.

 Description

     #include inserts the contents of the specified file in place of the
     #include directive in the source file.  By convention, the file inserted
     is referred to as a header file.  Header files should contain only
     preprocessor directives and external declarations.  By convention
     Clipper header files have a .ch extension.

     When deciding where to locate your header files, you have two basic
     choices.  You can place them in the source file directory where they are
     local to the current system; or, you can make them globally available by
     placing them in the directory specified in the INCLUDE environment
     variable.  A list of one or more directories can be specified.

     Header files overcome the one major drawback of defining constants or
     inline functions--the #define directive only affects the file in which
     it is contained.  This means that every program which needs access to
     these statements must have a list of directives at the top.  The
     solution to this problem is to place #define statements in a separate
     file and use the #include directive to tell the preprocessor to include
     that file before compiling.

     For example, suppose the file "Inkey.ch" contains a list of #define
     directives assigning key values to constants.  Instead of including
     these directives at the top of each program file (.prg) requiring access
     to them, you can simply place the following line at the top of each
     program file:

     #include "Inkey.ch"

     This causes the preprocessor to look for Inkey.ch and place all the
     directives contained within it at the top of this program.

     Another advantage of using the #include directive is that all the
     #define statements are contained in one file.  If any modifications to
     these statements are necessary, only the #include file need be altered;
     the program itself remains untouched.

     Note that the scope of definitions within an included header file is the
     current program file unless the header file is included on the compiler
     command line with the /U option.  In this case, the scope is all the
     program files compiled in the current invocation of the compiler.

 Notes

     .  Supplied header files: Clipper provides a number of header
        files containing manifest constants for common operations.  Refer to
        \CLIP53\INCLUDE for more information.

     .  Std.ch--the standard header file: Std.ch is the standard
        header file provided with Clipper.  Its default location is
        \CLIP53\INCLUDE.  Std.ch contains the definitions of all Clipper
        commands and the standard functions specified as pseudofunctions.  It
        is strongly recommended that no changes be made to Std.ch.  If
        changes are desired, it is advisable to copy Std.ch to a new name,
        make the changes, and compile with /U.

        This header file differs somewhat from a header file you might
        #include in that everything defined in Std.ch, with #define,
        #translate, or #command, has a scope of the entire compile rather
        than the current source file.

 Examples

     .  This example uses #include to insert Inkey.ch, a file of
        common keyboard definitions, into a key exception handler called by
        an interface function:

        #include "Inkey.ch"

        FUNCTION GetEvent()
           LOCAL nKey, nResult
           nKey = INKEY(0)
           DO CASE
           CASE nKey = K_F10
              nResult := DoMenu("Browse")
           CASE nKey = K_ESC
              nResult := DoQuit()
              .
              . <statements>
              .
           CASE nKey = K_CTRL_RIGHT
              nResult := DoNextRec()
           ENDCASE
           RETURN nResult

See Also: #command #define



C5_#ifndef

#ifndef
 Compile a section of code if an identifier is undefined
------------------------------------------------------------------------------
 Syntax

     #ifndef <identifier>
        <statements>...
     [#else]
        <statements>...
     #endif

 Arguments

     <identifier> is the name of a definition whose absence is being
     verified.

 Description

     #ifndef...#endif lets you perform conditional compilation by identifying
     a section of source code to compile if the specified <identifier> is
     undefined.

     The #else directive specifies the code to compile if <identifier> is
     defined.  The #endif terminates the conditional compilation block.

 Examples

     .  This code fragment is a general skeleton for conditional
        compilation with #ifndef:

        #define DEBUG
        .
        . <statements>
        .
        #ifndef DEBUG
           <optimized version of code>
        #else
           <debugging version of code>
        #endif

     .  This example compiles a section of code if a specific
        identifier is undefined.

        In DOS:

        C>CLIPPER Myfile

        In the program (.prg) file:

        #ifndef NODEBUG
           Assert(<some condition>)
        #endif

     .  This example overrides a default definition in the program
        (.prg) file using a manifest constant defined on the compiler command
        line with the /D option

        In DOS:

        C>CLIPPER Myfile /DM_MARGIN=10

        In the program (.prg) file:

        #ifndef M_MARGIN
           #define M_MARGIN   15
        #endif

See Also: #define #ifdef

C5_#ifdef

#ifdef
 Compile a section of code if an identifier is defined
------------------------------------------------------------------------------
 Syntax

     #ifdef <identifier>
        <statements>...
     [#else]
        <statements>...
     #endif

 Arguments

     <identifier> is the name of a definition whose existence is being
     verified.

 Description

     #ifdef...#endif lets you perform a conditional compilation.  It does
     this by identifying a section of source code to be compiled if the
     specified <identifier> is defined.  The <identifier> can be defined
     using either the #define directive or the /D compiler option which lets
     you define an identifier or manifest constant from the compiler command
     line.

     The #else directive specifies the code to compile if <identifier> is
     undefined.  The #endif terminates the conditional compilation block.

     Conditional compilation is particularly useful when maintaining many
     different versions of the same program.  For example, the demo code and
     full system code could be included in the same program file and
     controlled by a single #define statement.

 Examples

     .  This code fragment is a general skeleton for conditional
        compilation with #ifdef:

        #define DEMO
        .
        . <statements>
        .
        #ifdef DEMO
           <demo specific statements>
        #endif

     .  This example controls conditional compilation with an
        identifier defined on the compiler command line with the /D option.

        In DOS:

        C>CLIPPER Myfile /DDEBUG

        In the program (.prg) file:

        #ifdef DEBUG
           Assert(<some condition>)
        #endif

     .  This example defines a manifest constant to one value if it
        does not exist and redefines it to another if it exists:

        #ifdef M_MARGIN
           #undef  M_MARGIN
           #define M_MARGIN   15
        #else
           #define M_MARGIN   10
        #endif

See Also: #define #ifndef



C5_#error

#error
 Generate a compiler error and display a message
------------------------------------------------------------------------------
 Syntax

     #error [<messageText>]

 Arguments

     <messageText> is the text of the message to be displayed.
     <messageText> is a literal character string--do not enclose the message
     in quotations unless you want them to appear as part of the display.

 Description

     #error causes the compiler to generate error number C2074.  If the
     <messageText> parameter is specified, an error message is displayed.

 Examples

     .  This example displays an error message based on whether or not
        a NETWORK identifier was defined:

        #ifdef NETWORK
           #error Network version not implemented.
        #endif

See Also: #command #ifdef #ifndef