PPWIZARD is a free preprocessor for HTML, REXX, Visual Basic or any text files.
[Bottom][Contents][Search][Prev]: #import - WRAP[Next]: #Info
\ -> Commands -> #include

#include

A #include command 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).

PPWIZARD can include 'C' or 'C++' header files and can also automatically perform search and replace commands (see the #AutoTag command).

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. You don't have to use mine, make some up if you wish but use some! The convention for extensions that I use are as follows:

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).

  3. You can include a part of a header 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. The Main Input Files Directory
  3. /INCLUDEPATH
    Any locations specified with the /IncludePath switch or IncludePath() routine.
  4. PPWIZARD_INCLUDE environment variable.
  5. INCLUDE environment variable.
  6. PPWIZARD Install Directory

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.

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 specifies the text that marks the start and end of the part of the file you wish to process. Note that the comparison is case sensitive on unfiltered text.

The fragment can be specified in these ways:

The fragment parameter allows you to create a single include file from what might otherwise have been tens (or hundreds) of very small files (fragments). I use this parameter to contain all my larger example code fragments for my documentation.

#include a rexx array!

You may have executed some rexx code to build up a rexx array (stem variable), if this is the case probably the fastest way to include it would be as follows:

;--- Build an array for later inclusion ---
#NextId
#DefineRexx ''
   do  @@x = 1 to 500
       ;--- set up each line ---
       Array.@@x = 'Array Line ' || @@x;
   end;
   Array.0 = 500           ;;Holds line count
#DefineRexx

;--- #include the array ---
#{ for @@x = 1 to <??Array.0>
   <??Array.@@x>
#}

Example

;--- Include the whole file ---
#include <common.h>    ;;"C" format
#include "common.ih"
#include "\\server\share\dir1\common.ih"

;--- Include part of the file ---
#include 'common.ih'     ^[CounterExample]^
#include 'common.ih'     ^se:\[CounterExample]\[/CounterExample]\^
#include 'common.ih'     ^se:$[RestOfFileFromHere]$$^

Example - Roll your Own

Sometimes the #include command and its fragment handling may not do what you want, this example shows one "fairly generic" way of extracting information yourself. It is a two step process, the first reads the file into memory (this will be faster if you need to extract many fragments from the file). The following shows some code which should be placed into a common header file so it can be reused:

#NextId
#NextId LOCK 'ReadFileInfoMemory'
#( ''
   #define ReadFileInfoMemory
   #evaluate ^^ ^<$Rexx4ReadFileInfoMemory {$?}>^
#)
#DefineRexx 'Rexx4ReadFileInfoMemory'
   ;--- Get "parameters" ----------------------------------------------------
   @@File       = '{$File}';               ;;File name
   @@Maxlength  = {$Maxlength=^1000000^};  ;;Any limit on how much to read?

   ;--- Make sure the file exists! ------------------------------------------
   if  FileQueryExists(@@File) = '' then
       error('The file "' || @@File || '" does not exist');

   ;--- This file should be added as a dependancy ---------------------------
   call AddInputFileToDependancyList @@File;

   ;--- Read the file info memory -------------------------------------------
   {$MemoryVar} = charin(@@File, 1, @@MaxLength);

   ;--- Remove any carriage returns (leave line feeds) ----------------------
   {$MemoryVar} = ReplaceString({$MemoryVar}, '0D'x, '');

   ;--- Close the file ------------------------------------------------------
   call FileClose @@File;

   ;--- Validate parameter use ----------------------------------------------
   {$!}
#DefineRexx
#NextId UNLOCK 'ReadFileInfoMemory'

The following code reads a file into memory and extracts a fragment using the standard rexx parse instruction:

;--- Read the file info memory ----------------------------------------------
#NextId
<$ReadFileInfoMemory File="2.txt" MemoryVar="@@File2TXT">

;--- Now extract some information -------------------------------------------
#evaluate ^^ ^parse var @@File2TXT '<h3>' @@Title '</h3>'^
#if @@Title = ''
   #error ^We did not find the title^
#endif
<P> The title is "<??@@Title>".


email me  any feedback, additional information or corrections.
See this page online (look for updates)

[Top][Contents][Search][Prev]: #import - WRAP[Next]: #Info


PPWIZARD Manual
My whole website and this manual itself was developed using PPWIZARD (free preprocessor written by Dennis Bareis)
Saturday May 28 2022 at 2:55pm