PBShell does not offer any pre or post processing itself, but it offers a way of optionally shelling out to separate pre and post processing programs by recognizing the following "comment directives" in the primary source file:
'#PRECOM command line ... command to be executed before compilation
'#POSTCOM command line ... command to be executed after compilation
Or, if you are using PB/CC5 or PB/Win9, you can use the new #UTILITY metastatement:
#UTILITY #PRECOM command line ... command to be executed before compilation
#UTILITY #POSTCOM command line ... command to be executed after compilation
Notice that you must still prefix the PBShell directives with a hash. The remainder of this description assumes that you are using the older comment method, but the principle is the same (except that the #UTILITY word must be the first significant thing on the line, and there must always be at least one space after the #UTILITY word of course).
The preprocessor and postprocessor commands are executed using the PB SHELL statement and so the command line follows the same rules. See the PB Help for the SHELL statement for full details, and see below for how the window style is specified with the #PRECOM and #POSTCOM directives. Pay particular attention to the directory rules. The default directory when the command is executed will be the source file directory, but note that the executable command file is first looked for in the same directory as PBSHELL.EXE.
PBShell will expand all relative directory paths to absolute paths in the parameters to #PRECOM and #POSTCOM commands, thus allowing specification of relative directory paths in the source code even for processing executables which don't recognize them or change the current directory (rsrc.exe and rlink32.exe). Note that this will only work correctly if parameters are separated by spaces. It will work correctly with or without surrounding quotes, however, and surrounding quotes will be added if a relative path expands to a long name path which contains one or more spaces.
Because #PRECOM and #POSTCOM commands are specified in the source file, replaceable parameters are generally not required - the file specifications are known to the programmer, at least with relative path specifications. So, #PRECOM and #POSTCOM support only one replaceable parameter:
%incpaths% (not case sensitive)
This expands to the include file search path specification exactly as PBShell passes it to either the resource compiler or the PB compiler. This may include multiple paths separated by semicolons, so it is not valid to use it to reference a particular file. It is provided so that RC.EXE (the resource compiler) can be invoked as a #PRECOM or #POSTCOM command. It is expanded after relative paths have been expanded to absolute paths.
There can be more than one #PRECOM command and/or more than one #POSTCOM command. These will be accumulated by PBShell and executed in the order encountered. Of course, it makes logical and organizational sense to group them together but this is not required - the only requirement is that they appear in the source code before the first executable statement (like most metacommands).
Everything following the first space character(s) following the directive, up to the end-of-line, three successive space characters or an apostrophe character will be passed to the SHELL command, exactly as it is entered (except for the expansion of relative paths and substution of %incpaths%, mentioned above), preserving case, quotation marks and everything else.
The comment marker (') may be indented, or may follow other significant line content, and may be followed by space characters before the #PRECOM or #POSTCOM directives. If directive switches are used (see below) they must be directly attached to the directive word with no spaces, then there must be at least one space before the command line. The directive words and switch characters are not case sensitive.
Two switches may be added to the #PRECOM and #POSTCOM directives:
/<n> - window style, where <n> is a numeric digit.
/E - force execution where execution would normally be inhibited.
For full details of the window style values, see the PB Help for the SHELL statement. Valid values are 0 to 6. For example, the following will hide the window of a post processing command:
'#POSTCOM/0 command line
The /E switch on a #PRECOM directive forces the command to be run before compile and debug. The /E switch on a #POSTCOM directive forces the command to be run after compilation with an error or after a syntax check compilation. This is further explained below.
The /E and numerical switches may be combined in either order, for example as follows, but there must be no space between the directive and switch or between the switches:
'#PRECOM/0/E command line or
'#PRECOM/E/6 command line
There is no opportunity to execute post-processor commands when using the compile and debug option, since the primary source file is passed to the PB IDE for compilation and execution under the debugger. Therefore, the default behaviour is NOT to execute pre-processor commands also under this option. To override this default behaviour and execute an individual pre processor command even when compiling and debugging, append the /E switch to the directive, as follows:
'#PRECOM/E command line
When using the syntax check option, there is no new EXE or DLL produced and so default behaviour is NOT to execute post processor commands under this option (although pre processor commands ARE executed). To override this default behaviour and execute an individual post processor command even when compiling for syntax check, even if there is a compilation error, append the /E switch to the directive, as follows:
'#POSTCOM/E command line
Likewise, when compilation produces an error, there is no new EXE or DLL produced and so default behaviour is NOT to execute post processor commands under these circumstances. There is no way to know in advance whether there will be a compilation error, so pre processing commands WILL have been executed. To override this default behaviour and execute an individual post processor command even when there is a compilation error, or when compiling for syntax check, append the /E switch to the directive, as follows:
'#POSTCOM/E command line
#PRECOM commands are always executed before compiling (except under compile and debug by default), but of course it is very easy to manually disable them, for example when compiling for syntax check.
'#PRECOM command line
'$PRECOM command line
or something similar, and it will not be executed.
#PRECOM and #POSTCOM commands are not executed when compiling a resource file or executing a pre-compiled executable.
PBShell does not capture output from #PRECOM and #POSTCOM commands. If you need to detect errors from such commands, you will need to rely on their own reporting or wrap them in your own code to capture output.
An Example of Pre-Processing - Auto build number increment
In the primary source file of a large project, I place the following line:
%BUILD_NUMBER = 2966 '#precom IncBuild SCADA.BAS Automatic increment
A small program named INCBUILD.EXE, which is in the compiler directory, opens the command line file (which has the same name as the source file in which the above line appears) and looks for the %BUILD_NUMBER assignment line. It then reads, increments and writes back the following number. The modified source file is then passed to the compiler. The value of %BUILD_NUMBER is included for display in the "About" dialog.
This example demonstrates that the comment form of the pre or post processing directive does not have to be the first item on the line, which can occasionally be useful, as here, in aiding neatness. The following #UTILITY form would work in exactly the same way:
%BUILD_NUMBER = 2966
#utility #precom IncBuild SCADA.BAS 'Automatic increment
An Example of Post-Processing - Separate compilation and linking of resources
Some people want to avoid use of PBRES.EXE and linking of resources by the PB compiler and use another tool.
Using RLINK32.EXE by Roland Walter, which is placed in the compiler and resource compiler directory. To compile and link the resource script on every program compile, add the following lines to the primary source file:
'#postcom/0 rc /i %IncPaths% ..\Resource\MyApp.RC
'#postcom/0 rlink32 ..\Resource\MyApp.RES ..\MyApp.EXE
'#postcom/0 delete ..\Resource\SCADA.RES
Your source file should not include the #RESOURCE metastatement. If you compile your resource script in such a way, you will not, of course, see PBShell's resource compilation information or completion dialogs (just the normal source code compilation information and completion dialogs). If recompiling the resource on every program compile is not necessary, delete the first and last lines.
BTW, I got so fed up with grappling with CMD.EXE, which doesn't respect the window mode switch and flashes up a full screen console, to issue the DEL command, that I created a little program called DELETE.EXE which consists of only the statement "KILL COMMAND$" in PBMAIN.