PPWIZARD is a free preprocessor for HTML, REXX, Visual Basic or any text files.

#include

A #include can be used to include another (external) file for processing. This allows you to split a very large complicated html file into smaller logical pieces or more commonly to include standard 'header' files which contain all or most of the common definitions/text. This is a very common method for code reuse and is like the SSI (Server Side Includes) include "virtual" or "file" commands (but can also include fragments or parts of files and is less limiting on the external files location).

You can nest to any level however each level adds to the number of open files (unless you use the /Inc2Cache switch) so in reality the nesting level is system dependant. Another problem may be that the rexx intrepreter will have its own limit on how far you can nest files. On OS/2 (and probably other operating systems) there are mechanisms for increasing the numbers of file handles if required. For example on OS/2 version 4 fixpack 6 onwards to increase the numbers of available handles by 30 add "SET SHELLHANDLESINC=30" to your config.sys file.

You can call the included file anything you like (including the extension) however I recommend the use of conventions for extensions as this can make it easier to determine the context under which a file is expected to be used. The convention for extensions that I use are as follows:

• .IT - Internet Text (source code)
• .IH - Internet Header (source code)
• .HTM - Generated HTML
• .D - Document Main (source code)
• .DH - Document Header (source code)

It is possible for a header file to validate the release of a preprocessor if it needs to use a feature which may not be available in older release, please see the #require command.

Note that there are times when you might wish to share a file between 'C' code and PPWIZARD, you might just wish access to some of the values defined with #define statements. If you can't ensure that all commands (and their parameters) that the 'C' code uses are valid in PPWIZARD then you could:

1. Conditionally include portions (example "#ifndef _PPWIZARD_"). Note that "_PPWIZARD_" is automatically defined by PPWIZARD.

2. Use the #autotag commands to modify the contents on the file (on the fly - not on disk!) to convert invalid statements to valid ones (bit of a hack but would work).

It is also possible to include a part of the identified file if you can identify some text which marks the start and end of the parts you wish.

The following locations are searched in order, using FindFileInPath():

1. The Current Directory
2. /INCLUDEPATH
   Any locations specified with the/IncludePath switch.
3. PPWIZARD_INCLUDE environment variable.
4. INCLUDE environment variable.
5. PPWIZARD Install Directory

Syntax

    [WhiteSpace]#include  ["|']FileName["|']  [["]Fragment["]]    OR
    [WhiteSpace]#include  <FileName>  [["]Fragment["]]
    

The "FileName" specifies the file to be included. If the filename is or contains #defined variables they will be replaced. Note that the "<" & ">" quoted form is to make it compatible with existing "C" headers so you can use these if you require.

The optional "Fragment" parameter can be used to indicate the start and end of the portion of an included file you wish to process. The text must exist on the line immediately before and immediately after the part you need. Note that the comparison is case sensitive on unfiltered text. This parameter allows you to create a single include file from what might have been tens of very small files (fragments). I will use this parameter to contain all my example code for my documentation.

Example

    #include "common.ih"
    
    #include 'common.ih'     ^<CounterExample>^
    
    #include <common.h>
    

PPWIZARD Manual

Thursday January 17 2002 at 6:27pm