$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:

  1. 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!
    
    
  2. 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.
  3. BCX passes the source code line (Src$ in the BCXPP.bas example above) with the spaces removed from both ends of the line.
  4. BCX removes all end-of-line underscore continuation characters, concatenates the lines, and passes one long line of code to BCXPP.dll.
  5. The BCXPP.dll uses the STDCALL calling convention, making it easier to create a BCXPP.dll with various compilers and linkers.
  6. The BCXPP.dll is unloaded by BCX upon termination of the translation.