$PP directive

☞ Since BCX Version 7.5.0, the $PP directive has been changed. Any existing BCXPP.dll will need to be re-compiled if a calling program is translated with BCX Version 7.5.0 or later. Use the syntax and structure as shown in the BCXPP.dll example below.

Purpose: The $PP directive invokes a user created preprocessor to process each line of code until a second $PP directive is encountered.

Syntax:


 $PP ' Loads and turns on preprocessor.
     ' source code here to be preprocessed
 $PP ' Turn off preprocessor.

Remarks

To use the $PP directives, a preprocessor must first be compiled as a .dll from BCX source code. The preprocessor contains instructions to process the lines of code embedded between the $PP directives.

The preprocessor .dll, which must be named BCXPP.dll, contains one exported FUNCTION procedure which must be named ProcessLine and, as well, the processing instructions. Below is an example for a BCXPP.dll.


 $DLL STDCALL
 FUNCTION ProcessLine (Src$) AS LONG EXPORT
   IF Src$ = "DISPLAY MESSAGE" THEN
     Src$ = "PRINT " & ENC$(" MAGIC HAPPENS!")
   END IF
   FUNCTION = 1
 END FUNCTION

When the BCX translator encounters a $PP directive, the line following is passed to the BCXPP.dll for processing after which the BCXPP.dll passes the processed line back to the BCX translator. This exchange continues until the closing $PP directive is encountered.

For example, the above example BCXPP.dll would preprocess the line between between the $PP directives


 PRINT "When you wish you may, and wish you might, then";
 $PP
 DISPLAY MESSAGE
 $PP

pass the result back to the BCX translator which would translate the above example into this C code


 int main(int argc, char *argv[])
 {
 printf("%s","When you wish you may, and wish you might, then ...");
 printf("%s\n"," MAGIC HAPPENS!");
 return 0;   // End of main program
 }

☞ The BCX $PP system allows using either a 32-bit or 64-bit BCXPP.dll. If a 32-bit BCXPP.dll is used, then a 32-bit version of the BCX translator must be used to call it or else it will fail. Likewise, if a 64-bit BCXPP.dll is used then a 64-bit version of BCX must be used to call it or else it will fail.

Final notes about $PP:

When BCX encounters the first occurence of $PP, it loads the dll if it can find it. If it cannot find the dll it aborts with
```
 Failed to Open BCX Preprocessor DLL! 
```
or if it cannot locate the ProcessLine procedure in the dll, it aborts with
```
 Couldn't Find 'ProcessLine' Procedure in BCX Preprocessor DLL!
```
Each line of code which is not a directive or part of a directive is passed to the preprocessor. For example, a line of code beginning with a comment is not passed, lines of between $COMMENT directives are not passed, etc.
BCX passes the source code line (Src$ in the BCXPP.bas example above) with the spaces removed from both ends of the line.
BCX removes all end-of-line underscore continuation characters, concatenates the lines, and passes one long line of code to BCXPP.dll.
The BCXPP.dll uses the STDCALL calling convention, making it easier to create a BCXPP.dll with various compilers and linkers.
The BCXPP.dll is unloaded by BCX upon termination of the translation.