PPWIZARD is a free preprocessor for HTML, REXX, Visual Basic or any text files.

#NextId

The #NextId command is designed to make it easy for you to generate code (for example rexx) with global variable names (rexx or ppwizard variables) that will not clash with others of the same name. It does this by creating a unique namespace which exists up until the next #NextId command changes it.

For example you may have a global variable called "string", it may be used in a number of locations (including called subroutines), if no care is taken you may "corrupt" the value. Now in rexx you could use the "procedure" command however there are reasons why you would not want to use it. This command allows you to call the variable by the name "@@string" and have the '@@' (or whatever characters you choose) replaced with a unique identifier. Other parts of your code might also refer to "@@string" however the "@@" would be replaced by a different prefix.

Note that there is only ever one ID in use at any time. Apart from the obvious use of having short unique variable names without risk of clashing with those defined elsewhere in your code you can also protect yourself from clashing with variables that ppwizard uses.

Syntax

    [WhiteSpace]#NextId
    [WhiteSpace]#NextId  ON   | OFF
    [WhiteSpace]#NextId  PUSH | POP
    [WhiteSpace]#NextId  REPLACE Parm | MASK Parm
    [WhiteSpace]#NextId  LOCK [Parm] | UNLOCK [Parm]
    

If no parameters are supplied then NextId processing is turned on (if off) and the next id (new namespace) is chosen.

If parameters are supplied then the first (possibly only) parameter is a command, valid commands are:

• OFF
  Turns off #NextId processing.

• ON
  Turns on #NextId processing. Processing resumes with the same counter and other information as specified when processing was turned off.

• PUSH
  Saves state, possibly from included file or a macro could use to protect the users state. For maximum protection the counter is also incremented by this command. The new state always begins unlocked with next ID processing turned off.

• POP
  Restores state.

• LOCK
  This allows you to prevent any accidental insertion of code from incrementing the ID over what might be a largish piece of code. The parameter (if supplied) is a "key" that must be used on the "unlock" command. Basically this is to protect you against yourself!

  You can use the "PUSH" command to temporarily create an unlocked state with its own IDs if that is required.

• UNLOCK
  This is used to unlock a previously locked state. If a key was supplied on the "lock" command then the same key must be specified when unlocking.

• REPLACE
  By default "@@" is used as a prefix and gets replaced by #NextId processing. This string will be replaced in any line read from a file. The parameter you pass specifies the text that you would like replaced instead. If no parameter supplied the default is used.

  You must carefully pick this value so that you will never use it in your source code for any other reason (such as in a literal). The use of <?xXX> codes is one way of handling the odd occurance of the string when it is not a Next ID marker.

• MASK
  The prefix that PPWIZARD generates is always made up of the lower case characters (a-z) and so is always safe for the start of a rexx or other type of variable name. You can add a wrapper to adjust the format of the prefix. If no parameter supplied the default is used.

  The mask would normally contain one "*" character to indicate where the unique number should be placed. The default mask is "*_" which means that PPWIZARD adds an underscore after the generated prefix.

Example #1

The following shows some rexx fragments where I am using Next ID processing to ensure that each routine has it's own variables (which other routines don't also use).

    ;=================
    Function1:
    ;=================
       #NextId
       #define @@FRED ...
       parse arg @@Parm1, @@Parm2
       ...
       @@Result = Function1(1, 2)
       return(@@Result || @@Parm1 || <$@@FRED>)
    
    ;=================
    Function2:
    ;=================
       #NextId
       #define @@FRED ...
       parse arg @@Parm1, @@Parm2
       ...
       @@Result = ...
       return(@@Result)
    

Note that the ppwizard variable "FRED" and the rexx variables "Parm1" and "Parm2" actually have different names between "function1" and "function2" and therefore do not overwrite each overs values.

Example #2

We need to keep some state information in a PPWIZARD macro:

    #NextId
    #( '<?NewLine>'
       #define SelfRegister
       <$HereWeAre "{$?MacName} - {$#1} = {$SELFREG=^Y^}">
       #if ['{$SELFREG}' = 'N']
           #define+ @@SelfReg  false  ;;Want to remove self registration info
       #elseif
           #define+ @@SelfReg  true   ;;Want this filekey self registered
       #endif
       OK = <$WiseObj>.SetFileSelfRegister("{$#1}", <$@@SelfReg>)
       BoolMustBeTrue(Ok)
    #)
    

Another very common use is to define all rexx variables you might use in any rexx code your macros might call, this ensures they will not clash with those of other macros or those that PPWIZARD itself might use.

PPWIZARD Manual

Thursday January 17 2002 at 6:27pm