Switch /Syntax:Spec

This is a PPWIZARD command line switch.

For some output extensions or file types PPWIZARD automatically checks the syntax of the generated files. You can turn this off, on, or tweek the output using this switch.

The syntax checking typically works by executing code which returns a specific return code if a certain 'unusual' parameter is passed. REXX, VBS and some other languages go through a loading step where syntax is validated, if this fails the code will never get executed. This is why we add a little stub to return a specific return code. The stub does not get in the way because if is never accidently invoked.

If you use this switch you will probably want to also use "/DeleteOnError:NO", so you can examine the code if an error is detected.

The first and last characters of the "Spec" defines the delimiter being used to delimit the following values:

1. ToWhat
   You can specify the following for this value:

   1. FileExtension
      You can apply the rule to a particular extension, for example use "VBS" (no dot!) for VBSCRIPT files.

   2. *ProcessingMode
      You can apply the rule to all extensions covering a particular processing mode, for example use "*REXX" for rexx files.

   3. *
      You can apply the rule to all files that did not match the rules above by specifying "*".

   The above are listed in the order that PPWIZARD will look for it.

2. The Test Command
   This is the command line of the command required to test the syntax of the generated program. Use "{?}" to indicate where the filename should be placed. Pass "" to disable checking.

   As a special case while in REXX mode if "*" is passed this specifies that the internal validation should be used.

3. The Expected Return Code
   This is the expected return code from the above command. Typically the lines you insert (see below) will return this value. Pass "" to disable checking.

4. A Failing Line Number Extraction Mask
   See "OutSyntaxErrLineMask" below, use "" for no mask.

5. One or More lines
   The 'Spec' delimiter can be used to split this into multiple lines. This is the line or lines of code which is inserted into the header of the file to allow the syntax checking to take place.

   If this value begins with "?:" then the code should not be automatically inserted but will be inserted manually via the <?SyntaxCheck> symbol. The <?SyntaxCheck> symbol can be used if for some reason you do not wish to perform syntax checking for the odd one or two files.

Use of Header File

If the test command value starts with '@' and there is no return code or lines then this indicates that a file should be read to create the stub code and set the command and expected return code values.

If your header file included conditional generation of the header based on the extension of the output file then it could make sense to use a "*" rule.

You header should output the syntax checking stub and should also set these rexx variables:

• OutSyntaxCmd
  This is the command line to be executed which invokes the file is a manner that should exercise the stub you inserted to return a specific return code. It is also possible that no stub is required and a validation program exists and you wish to call this.

• OutSyntaxRc
  This is the return code you expect your command (usually stub) to return. You are generally relying on the loading process to fail on syntax error and therefore return some other return code.

• OutSyntaxMsg
  This optional value allows you to alter the generated error message. If the message starts with '-' then the text replaces the normal error text otherwise it is additional to the normal message.

• OutSyntaxCode
  Normally you will insert the syntax checking stub into the header file immediately. This optional value allows you to indicate that you do not wish to do this but that the user will indicate the exact location they wish the code inserted by use of the <?SyntaxCheck> symbol. The reason for this is that the insertion of "unexpected code" can itself cause syntax errors in some languages (for example VBSCRIPT if it uses the "OPTION" command). In other languages the appropriate spot may ne nowhere near the start of the file. If you need to delay the insertion then this variable should contain the code.

• OutSyntaxErrLineMask
  This allows you to specify how the failing line number can be extracted from the redirected output, you should supply as much identifying before and after text as possible and use "{?}" to represent the line number (and "{?C}" for the column information if it exists), for example VBSCRIPT returns:

  c:\TMP\1out.vbs(17, 6) Microsoft VBScript compilation error: Syntax error
  

  So you would use "({?}, {?C}) " to extract the line and column numbers (line 17 column 6 in the example above). There is not as much identifying text as we might like but this is the best we can do. If PPWIZARD can extract the line number it will display the failing part of the file.

Default REXX Configuration (/SYNTAX not used)

PPWIZARD has an inbuilt (but primitive) method of locating syntax errors in your code, however it relies on you reading the resultant output to determine the error line (and will not display it).

It is possible to give PPWIZARD a bit of help in which case it will tell you the failing line number and display the line in context.

Examples

The following shows how syntax checking for files with the extension ".VBS" can be turned off:

/syntax:~/VBS/~

The following shows how a file can be included to add syntax checking code for multiple extensions (first removes existing VBS code):

/syntax:~/VBS/~ /syntax:~/*/@c:\tmp\syntax.h~

The following is an example of what the "syntax.h" file could look like:

;--- Determine what we wish to do -------------------------------------------
#NextId
#NextId LOCK 'SYNTAX.H'
#info 'in syntax.h'
#DefineRexx ''
   ;---- Get extension (if not unix then make upper case) -------------------
   @@Extn = FilePart('EXTN', '<?OutputFile>');
   #if ['<?OpSys>' <> 'UNIX']
       @@Extn = translate(@@Extn);    ;;Make upper case
   #endif

   ;---- Want a comment? ---
   select
       ;%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
       when @@EXTN = "VBS" then
       ;%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
       do
           ;--- VB SCRIPT (user must use "SyntaxCheck" standard symbol) ---
           OutSyntaxRc          = '21924';
           OutSyntaxCode        = 'if Wscript.Arguments.Count = 1 then if Wscript.Arguments(0) = "!CheckSyntax!" then wscript.quit(' || OutSyntaxRc || ')';
           @@Code               = '';       ;;Generate nothing now (below)!
           OutSyntaxErrLineMask = '({?}, '  ;;How to extract the failing line #
           OutSyntaxCmd         = 'cscript.exe "{?}" //NOLOGO !CheckSyntax!'
           OutSyntaxMsg         = "Note that you must not use VBSCRIPT's OPTION command after the syntax checking code is inserted!";
       end;
       ;%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
       otherwise
       ;%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
       do
           ;--- Don't want any syntax checking code ---
           @@Code       = '';

           ;--- Return reserved variables with "empty" values ---
           OutSyntaxRc  = '';
           OutSyntaxCmd = '';
           OutSyntaxMsg = '';
       end;
   end
#DefineRexx

;--- Any syntax checking code to generate? ---------------------------------*/
#if [@@Code <> '']
    ;--- This code returns a specific return code when passed specific parameter ---
    <??@@Code>
#endif
#NextId UNLOCK 'SYNTAX.H'

If you add any extensions (Perl etc) please consider sending them to me so I can update the documentation fo others.

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

PPWIZARD Manual

Saturday May 28 2022 at 2:55pm