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:

   • GETFILELIST
     This hook allows you to create your own mask handler, this lets you determine what the mask means, for example you may only wish to process files that match the mask and were modified today.

     This hook affects PPWIZARD internals as well as the Files4Mask() routine.

     Extra parameters are:

     1. File Mask Location
        This is any drive or path component of the file mask.

     2. File Mask Name
        This is the file mask less any drive or path component. Combining this with the location will rebuild the original mask.

     3. Scan Subdirectories
        Either 'Y' or 'N', did user preceed filemask with '+'? You can ignore this if you wish, after all you have full control in how you evaluate the filemask.

     4. Output File
        This is the name of the output file into which you are expected to place the full names of files to be processed (one per line). Blank lines are ignored but all other lines are not and leading and trailing whitespace is not removed.

   • BEFORE
     This hook is called just before a build is started.

     Extra parameters are:

     1. PPWH_INPUT
        Contains "" or the full name of the base input file.

     2. PPWH_OUTPUT
        Contains "" or the name of the base output file.

     3. PPWH_TEMPLATE
        Contains "" or the name of any template file being used.

   • AFTER
     This hook is called after a build completes.

     Extra parameters are:

     1. PPWH_INPUT
        Contains "" or the full name of the base input file.

     2. PPWH_OUTPUT
        Contains "" or the name of the base output file.

     3. PPWH_TEMPLATE
        Contains "" or the name of any template file being used.

   • WARNING
     This hook is called for each warning that is not being ignored.

     Extra parameters are:

     1. PPWH_INPUT
        Contains "" or the full name of the base input file.

     2. PPWH_OUTPUT
        Contains "" or the name of the base output file.

     3. PPWH_TEMPLATE
        Contains "" or the name of any template file being used.

     4. Warning Message Text
        This contains the text of the message. If you wish to cause ppwizard to completely ignore the warning then you should return "OK:IGNORE". To ignore a message but still increment the warning counter then return "OK:IGNORE+".

   • ERROR
     This hook is called when an error occurs.

     Extra parameters are:

     1. PPWH_INPUT
        Contains "" or the full name of the base input file.

     2. PPWH_OUTPUT
        Contains "" or the name of the base output file.

     3. PPWH_TEMPLATE
        Contains "" or the name of any template file being used.

     4. Number of lines
        This contains the number of lines, each one is in its own environment variable.

        Each line can be found in the PPWH_ERROR? environment variable (where '?' is the line number).

     Do not return anything but "OK:" otherwise you won't get the "see" the original error text.

   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)

PPWIZARD Manual

Sunday November 05 2017 at 10:00am