PPWIZARD is a free preprocessor for HTML, REXX, Visual Basic or any text files.
[Bottom][Contents][Search][Prev]: /HideCmd[Next]: /HTML
\ -> PPWIZARD Command Line -> Switches -> /Hook

Switch /Hook[:When[;RexxFile]]

This is a PPWIZARD command line switch.

This switch allows you to call external Rexx code to perform processing at specific times.

On success all hooks return a string which begins with "OK:", otherwise ppwizard treats the return code as an error and aborts processing. Some hooks allow you to pass information back to ppwizard (for example warning hooks can return "OK:IGNORE").

The rexx code for all hook types always gets passed these parameters:

  1. Interface Version Number
    I will modify this value if you need to do anything to get your hook code running again. I recommend you check this value!

  2. Source Location
    This value will contain the current location in the source that you are processing or "" if not processing any input file. It is intended for display purposes only, do not assume any specific format as it may change in the future.

  3. When Code
    The reason this hook was called (as described below). If you wish, the same rexx code can be called for all hooks you process. In any case I recommend that the value be validated in case someone uses it incorrectly.

If no parameter is supplied on the "/HOOK" switch then all hooks are turned off, otherwise the parameter is broken up into 2 components as follows:

  1. When Code
    This parameter if empty indicates that all hooks are being adjusted, otherwise lists the hooks (seperated by ",") as follows:

    Note that you can specify any abbreviation of the above on the /hook switch, so for example "a" is the same as "after".

  2. RexxFile
    This is the name of the rexx program that will be called to handle the hooks you have indicated. If not supplied then the hooks indicated are turned off.

Example Switches

   REM *** CALL SAME HOOK for before, after and warnings ***
   /Hook:after,before,warning;hook.cmd

   REM *** CALL MULTI HOOKS for before, after and warnings ***
   /Hook:before;hookb.cmd /Hook:after;hooka.cmd /Hook:warning;hookw.cmd

   REM *** Reset some hooks ***
   /Hook:bef,a

   REM *** Reset all hooks ***
   /Hook

Example - File Mask Handler

The example shows how "dir" could be used, unix people could use either "ls" or "find" with appropriate switches to generate a list of files. In any case the processing can be as complex or as simple as you wish.

/*---------------------------------------------------------------------------
;    MODULE NAME:   LISTFILE.CMD
;
;        $Author:   USER "Dennis"  $
;      $Revision:   1.0  $
;          $Date:   30 Mar 2001 18:05:30  $
;       $Logfile:   C:/DBAREIS/Projects.PVCS/MultiOs/PPWIZARD/listfile.cmd.pvcs  $
;
;    DESCRIPTION:   Simple hook file to demonstrate for a "GETFILELIST"
;                   hook works.
;
;                   Hook code would generally tend to be operating system
;                   specific.  This code was tested under OS/2 and would
;                   probably require MINOR changes to work elsewhere.
;----------------------------------------------------------------------------*/

/*--- I highly recommend use of trap handlers for ALL rexx code -------------*/
signal on NOVALUE name RexxTrapUninitializedVariable;
signal on SYNTAX  name RexxTrapSyntaxError;

/*--- Get parameters --------------------------------------------------------*/
InterfaceVersion   = arg(1);
InterfaceType      = arg(3);
FileMaskLocn       = arg(4);
FileMaskName       = arg(5);
ScanSubdirectories = arg(6);    /* You can ignore if you wish (you might have your own way of flagging it) */
OutputFile         = arg(7);

/*--- Get shortname of this routine -----------------------------------------*/
parse source . . RexxId;
S1Pos    = lastpos('/', RexxId);
S2Pos    = lastpos('\', RexxId);
SlashPos = max(S1Pos, S2Pos);
if SlashPos <> 0 then
   RexxId = substr(RexxId, SlashPos+1);

/*--- Say what is going on --------------------------------------------------*/
if GetEnv("PPWIZARD_DEBUG") = 'Y' then
do
   /*--- Debug is on! -------------------------------------------------------*/
   say '';
   call SayIt 'arg(1) = Interface Version   = "' || InterfaceVersion   || '"';
   call SayIt 'arg(2) = Mask Location       = "' || FileMaskLocn       || '"';
   call SayIt 'arg(3) = Mask less Location  = "' || FileMaskName       || '"';
   call SayIt 'arg(4) = Scan Subdirs = Y|N  = "' || ScanSubdirectories || '"';
   call SayIt 'arg(5) = Temp File to create = "' || OutputFile         || '"';
end;

/*--- This code only designed to handle a single interface! -----------------*/
ExpectedInterfaceVersion = '00.050';
if InterfaceVersion <> ExpectedInterfaceVersion then
   Die('Unsupported Interface of "' || InterfaceVersion || '", Expected "' || ExpectedInterfaceVersion || '"');

/*--- This code only designed to handle a single hook type! -----------------*/
ExpectedInterfaceType = 'GETFILELIST';
if InterfaceType <> ExpectedInterfaceType then
   Die('Unsupported Interface of "' || InterfaceType || '", Expected "' || ExpectedInterfaceType || '"');

/*--- Want to scan subdirectories as well? (you can ignore this flag) -------*/
if ScanSubdirectories = 'Y' then
   Subdir = ' /S'
else
   Subdir = ''

/*--- Get a list using "dir" (could be "ls" or "find" in unix) --------------*/
Executing = '@dir "' || FileMaskLocn || FileMaskName || '" /F' || Subdir || ' > ' || OutputFile;
if GetEnv("PPWIZARD_DEBUG") = 'Y' then
   call SayIt 'Executing: ' || Executing;
Executing;

/*--- Did the 'dir' command fail --------------------------------------------*/
if Rc <> 0 then
   Die('"dir" returned a return code of ' || Rc);

/*--- All OK ----------------------------------------------------------------*/
exit('OK:');



/*===========================================================================*/
SayIt:
/*===========================================================================*/
   say RexxId || ' : ' || arg(1);
   return;


/*===========================================================================*/
GetEnv:                                            /* OS/2 specific function */
/*===========================================================================*/
   return( value(arg(1),,'OS2ENVIRONMENT') );


/*===========================================================================*/
Die:
/*===========================================================================*/
   /*--- Return with error --------------------------------------------------*/
   ErrorLine = SIGL;
   call SayIt 'ERROR(Line ' || ErrorLine || ') - ' || arg(1);
   exit(arg(1));


/*===========================================================================*/
CommonTrapHandler:
/*                                                                           */
/* arg(1) = Failing Line                                                     */
/* arg(2) = Type of trap (heading to be underlined)                          */
/* arg(3) = Trap specific Title  (text description)                          */
/* arg(4) = Trap specific Text                                               */
/*===========================================================================*/
   /*--- Work out some details based on passed info -------------------------*/
   FailingLine     = arg(1);
   TrapHeading     = 'BUG: ' || arg(2);
   TextDescription = arg(3);
   Text            = arg(4);

   /*--- Work out name of THIS rexx procedure -------------------------------*/
   parse source . . SourceFileName;

   /*--- Display details of the failing rexx code ---------------------------*/
   say '';
   call SayIt copies('=+', 39);
   call SayIt TrapHeading;
   call SayIt copies('~', length(TrapHeading));
   call SayIt substr(TextDescription, 1 , 16) || ': ' || Text;
   call SayIt 'Failing Module  : ' || SourceFileName;
   call SayIt 'Failing Line #  : ' || FailingLine;
   call SayIt 'Failing Command : ' || strip(SourceLine(FailingLine));
   call SayIt copies('=+', 39);

   /*--- We won't let a failure in one subprocedure stop others working -----*/
   exit(TrapHeading || ' on line ' || FailingLine || ', ' || TextDescription || ': ' || Text);


/*===========================================================================*/
RexxTrapUninitializedVariable:
/*===========================================================================*/
   /*--- Process the trap (it never returns) --------------------------------*/
   ReginaBug = SIGL;
   call CommonTrapHandler ReginaBug, 'NoValue Abort!', 'Unknown Variable', condition('D');

/*===========================================================================*/
RexxTrapSyntaxError:
/*===========================================================================*/
   /*--- Process the trap (it never returns) --------------------------------*/
   ReginaBug = SIGL;
   call CommonTrapHandler ReginaBug, 'Syntax Error!', 'Reason', errortext(Rc);



Example HOOK file [HOOK.CMD]

This example shows how one rexx procedure can handle many hook types (as well as how to write a number of different hook types).

/*---------------------------------------------------------------------------
;    MODULE NAME:   HOOK.CMD
;
;        $Author:   USER "Dennis"  $
;      $Revision:   1.0  $
;          $Date:   30 Mar 2001 18:05:28  $
;       $Logfile:   C:/DBAREIS/Projects.PVCS/MultiOs/PPWIZARD/hook.cmd.pvcs  $
;
;    DESCRIPTION:   Simple example hook file.
;
;
;           NOTE:   This is an example skeleton only
;
;                   There is no requirement that all hooks use the same
;                   rexx procedure, they can each use their own if you
;                   wish.
;
;                   Trap Handlers are very simplistic
;
;                   Do not assume specific format for location = arg(2)
;
;                   filespec() is only available on OS/2! That is MINOR
;                   changes will be required to run on other operating
;                   systems.
;----------------------------------------------------------------------------*/

/*--- I highly recommend use of trap handlers for ALL rexx code -------------*/
signal on NOVALUE name RexxTrapUninitializedVariable;
signal on SYNTAX  name RexxTrapSyntaxError;

/*--- Get parameters --------------------------------------------------------*/
InterfaceVersion   = arg(1);  /* Both ends must know exactly how things passed! */
Location           = arg(2);  /* Location in source file                        */
HookType           = arg(3);  /* What hook type do we want processed?           */
InputFile          = arg(4);
OutputFile         = arg(5);
TemplateFile       = arg(6);
WarningText        = arg(7);
ErrorLineCount     = arg(7);

/*--- Get shortname of this routine -----------------------------------------*/
parse source . . RexxId;
S1Pos    = lastpos('/', RexxId);
S2Pos    = lastpos('\', RexxId);
SlashPos = max(S1Pos, S2Pos);
if SlashPos <> 0 then
   RexxId = substr(RexxId, SlashPos+1);

/*--- Display "parameters" (if user has debug mode on) ----------------------*/
if GetEnv("PPWIZARD_DEBUG") = 'Y' then
do
   /*--- Debug mode is on ---------------------------------------------------*/
   call SayIt 'Hook Type    = "' || HookType                || '"';
   if  Location <> '' then
       call SayIt 'Source Locn  = "' || Location            || '"';
   call SayIt 'InputFile    = "' || InputFile   || '"';
   call SayIt 'TemplateFile = "' || TemplateFile || '"';
   call SayIt 'OutputFile   = "' || OutputFile  || '"';
end;

/*--- Lets set up default OK parm (return code) -----------------------------*/
OkParm = '';

/*--- Do hook specific processing -------------------------------------------*/
select
   /*++++++++++++++++++++++++++++++++*/
   when HookType = "WARNING" then
   /*++++++++++++++++++++++++++++++++*/
   do
       /*--- Display if in debug mode ---------------------------------------*/
       if  GetEnv("PPWIZARD_DEBUG") = 'Y' then
           call SayIt 'WARNING = "' || WarningText  || '"';

       /*--- Log to file ----------------------------------------------------*/

       /*--- Tell caller to ignore ------------------------------------------*/
       OkParm = "IGNORE";
   end;
   /*++++++++++++++++++++++++++++++++*/
   when HookType = "ERROR" then
   /*++++++++++++++++++++++++++++++++*/
   do
       /*--- Display if in debug mode ---------------------------------------*/
       if  GetEnv("PPWIZARD_DEBUG") = 'Y' then
       do
           /*--- Display Each line ------------------------------------------*/
           do Line = 1 to ErrorLineCount
              call SayIt 'ERROR TEXT  = "' || GetEnv("PPWH_ERROR" || Line)   || '"';
           end;
       end;

       /*--- Log to file ----------------------------------------------------*/
   end;
   /*++++++++++++++++++++++++++++++++*/
   otherwise
   /*++++++++++++++++++++++++++++++++*/
       nop;
end;

/*--- Say OK ----------------------------------------------------------------*/
exit("OK:" || OkParm);




/*===========================================================================*/
SayIt:
/*===========================================================================*/
   say RexxId || ' : ' || arg(1);
   return;


/*===========================================================================*/
GetEnv:
/*                                                                           */
/* arg(1) : Name of environment variable.                                    */
/*===========================================================================*/
   return( value(arg(1),,'OS2ENVIRONMENT') );



/*===========================================================================*/
CommonTrapHandler:
/*                                                                           */
/* arg(1) = Failing Line                                                     */
/* arg(2) = Type of trap (heading to be underlined)                          */
/* arg(3) = Trap specific Title  (text description)                          */
/* arg(4) = Trap specific Text                                               */
/*===========================================================================*/
   /*--- Work out some details based on passed info -------------------------*/
   FailingLine     = arg(1);
   TrapHeading     = 'BUG: ' || arg(2);
   TextDescription = arg(3);
   Text            = arg(4);

   /*--- Work out name of THIS rexx procedure -------------------------------*/
   parse source . . SourceFileName;

   /*--- Display details of the failing rexx code ---------------------------*/
   say '';
   call SayIt copies('=+', 39);
   call SayIt TrapHeading;
   call SayIt copies('~', length(TrapHeading));
   call SayIt substr(TextDescription, 1 , 16) || ': ' || Text;
   call SayIt 'Failing Module  : ' || SourceFileName;
   call SayIt 'Failing Line #  : ' || FailingLine;
   call SayIt 'Failing Command : ' || strip(SourceLine(FailingLine));
   call SayIt copies('=+', 39);

   /*--- We won't let a failure in one subprocedure stop others working -----*/
   exit(TrapHeading || ' on line ' || FailingLine || ', ' || TextDescription || ': ' || Text);


/*===========================================================================*/
RexxTrapUninitializedVariable:
/*===========================================================================*/
   /*--- Process the trap (it never returns) --------------------------------*/
   ReginaBug = SIGL;
   call CommonTrapHandler ReginaBug, 'NoValue Abort!', 'Unknown Variable', condition('D');

/*===========================================================================*/
RexxTrapSyntaxError:
/*===========================================================================*/
   /*--- Process the trap (it never returns) --------------------------------*/
   ReginaBug = SIGL;
   call CommonTrapHandler ReginaBug, 'Syntax Error!', 'Reason', errortext(Rc);


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

[Top][Contents][Search][Prev]: /HideCmd[Next]: /HTML


PPWIZARD Manual
My whole website and this manual itself was developed using PPWIZARD (free preprocessor written by Dennis Bareis)
Sunday November 05 2017 at 10:00am