SET - Set a Command Variable

Contents of Article


Syntax

Operands

Description

Sample SET Edit session

Using SET to Define Command Aliases


Syntax


SET

SET

SET

[  name  [  OFF  |  { = value }  ]  ]

name  PUSH  [  =  value  ]

name  POP


Operands


name

Defines the name of the SET variable.  A SET variable name is case-insensitive, and must be a letter followed by zero or more letters, digits and underscores.  


SET variable names may also contain dot characters.  Dots may appear anywhere in the name, except for the first position which must be a letter.  Names may contain consecutive dots, may end in one or more dots, and dots may be followed by any of the legal characters: letters, digits and/or underscores.


Because the command notation =X is a shortcut for the command EXIT, a SET variable with a name of X is not allowed; the name X is reserved. (This shortcut emulates a notation used in IBM ISPF to quickly exit that editor.)


SET name by itself will display the current contents of SET variable name.


SET with no operands will bring up a SET Edit session.


OFF

SET name OFF will remove the SET variable name.  Once removed, attempting to remove it again will produce the message Unknown SET variable.


If the SET variable name has been pushed, and has one or more 'prior' values in addition to its current value, all of the values are deleted by OFF.


= value

SET name = value will assign value to SET variable name.  If the value contains embedded blanks, it must be quoted.


If the value contains quotes, you must enclose the entire value in other quotes.  For example, suppose you want to reference a number of 12345 as a string by using the SET variable name NUM in several CHANGE commands, such as:


CHANGE ABC =NUM  


If you defined this as SET NUM = '12345' this would not work, since the value would just stored as 12345 without the quotes, and the CHANGE command would effectively be


CHANGE ABC 12345


and the 12345 would look like a line number, not a string.  To store the SET variable's value so that the quotes are included, you would have to “quote the quotes”.  The correct command would be SET NUM = "'12345'".  

Then the CHANGE command would get correctly expanded to


CHANGE ABC '12345'


NOTE:   The operands of SET must be separated by blanks.  That is,


       SET LINE = 123


is valid, but


       SET LINE=123


is invalid syntax, and will result in Unknown SET variable: =123.  This happens because SPFLite tries to expand the '=123' part of the command as if it were a SET variable.  


You can use this fact to define ‘symbolic' SET variables if you wished.  Example:


       SET N = 10

       SET LINE=N = TEN


The first line sets SET variable N to 10.  The second line is first parsed, and since N is defined, LINE=N is converted to LINE10.  The effective command is, SET LINE10 = TEN, and the string “TEN” is assigned to the SET variable LINE10.


PUSH

The PUSH keyword will cause the current value of the SET symbol 'name' to be pushed on a 'stack', so that the current value of the variable is saved (and could be restored later with POP).  If you specify a value on the SET command, like SET name PUSH = value, that will be the new value of the SET symbol.  The 'stack' mechanism treats each name separately, so pushing and popping one SET variable has no effect on any other SET variable.


If you do not specify a value, and just say SET name PUSH, a duplicate copy of the current value will be placed on the stack.  When this is done, the name used must be a currently defined SET symbol, otherwise you will get the error message, "Unknown SET variable".


POP

The POP keyword will cause the current value of the SET variable 'name' to be discarded when SET name POP is issued, and the prior value of that variable that was stored on the 'stack' is restored.


The name used must be a currently defined SET symbol, otherwise you will get the error message, "Unknown SET variable".


The name used must also have at least one stacked value present for POP to be performed.  That is, in addition to setting the original value of the variable, you have to have issued a SET name PUSH command at least once.  If this was not done, you will get the error message, "No additional values to POP for: name".  That means you cannot "POP a SET name out of existence" by issuing the SET name POP command too many times.  To get rid of a SET variable, the command SET name OFF is required, or else you can enter a SET Edit session and delete the definition manually.


Description


The SET command is used to store named values, known as SET variables.  A SET variable is comparable to a Windows environment variable in the way it is defined and used.


In SPFLite primary commands, you can access the value of a SET variable by putting an = equal sign followed by the name of the variable.  Suppose you wanted to refer to a certain line number by name.  You could say,


       SET LINE = 1234


and then use it in commands as a symbolic name for 1234:


       CHANGE ABC DEF =LINE

or

       LOC =LINE

       

Wherever you said =LINE the value of LINE, 1234, would get substituted.


The substitution happens right away, so if you RETRIEVE a command that had a SET variable, the resolved value is what gets retrieved, not the =name notation.  So, in the examples above, what gets retrieved will be


       CHANGE ABC DEF 1234


and


       LOC 1234

       

Sample SET Edit session


If you issue the SET command by itself, you will bring up a SET edit session.  This is marked by a file tab of (SET Edit).



To ensure the integrity of the SET values, the SET command cannot be issued from any tab when a SET Edit session is active.


You can add, change or delete SET variables in the SET Edit session, or just browse their contents.  When you issue an END command (usually mapped to F3), the contents of the SET Edit session become the new values of all SET variables, and can be used immediately.  It's not necessary to say SAVE in a SET Edit session.  That is implied, and SPFLite takes care of that for you.  However, it is possible to say CANCEL in a SET Edit session, which will discard any changes you might have made.


The SET variable values are stored in a file called SPFLite.SPS which is normally in the SPFLite directory under My Documents.  As you will see if you start a SET Edit session, the values are stored in a straight-forward manner, as name=value entries, one per line, in the same manner that Windows environment variables would be stored if you issued the DOS command SET > MYFILE.TXT and then opened that file for editing.  This fact makes it easy to import environment-like values from outside SPFLite and use them as SET variables.


Note: As you observe the SET Edit display above, the name and value are separated by a single = sign with no spaces between.  This is not the same format as the SET command, which requires spaces between the operands.  Yes, we know it isn't consistent - it's just the way it is.


When you PUSH a value on a SET variable, and then issue the SET command with no arguments, you can see how the 'stack' is stored for that name. Let's say you issued SET name = one, and then SET name PUSH = two.  (The keywords are capitalized just to emphasize them; you can type them in upper or lower case, as usual.)  After this was done, issue a SET with no arguments.  Here is what it will look like:



Here, you can see that the current "top of the stack" for name is "two", and the definition of the variable looks like all the other ones, stored as VariableName=Value.  But the 'old' value appears underneath, with just a leading = sign.  When you POP a variable, this extra line is removed and only the 'current' value remains.  


SPFLite takes these actions automatically and you don't normally need to be concerned with it, unless you are going to edit the values in the SET Edit session, or import these values from outside SPFLite.  If you were going to do that, the main thing to remember is not to SORT the data in the SET Edit session, if there are any pushed values.  Otherwise, the 'top' value and the 'previous' value(s) could get separated, and any subsequent POP commands wouldn't work right.


Using SET to Define Command Aliases


You can define command aliases for primary commands using the SET command.


A command alias name applies to both an Edit/Browse session and to the File Manager.


You cannot define an alias to override an existing command.  For example, an alias cannot change BROWSE into EDIT.  Aliases come into play after SPFLite determines that a given primary command is not a built-in command name, and before it looks for a possible macro definition.


You define a primary command alias by the following SET command:


SET ALIAS.name = command


The name portion of the SET variable specifies the new alias name you want to define.  It should not be any existing built-in SPFLite command.


There is nothing to stop you from doing that, but you do so, SPFLite will never use your definition.  For example, if you tried to say SET ALIAS.BROWSE = EDIT and then typed BROWSE as a primary command, SPFLite will never look at your ALIAS definition, and it will not launch an EDIT command.


The command portion of the SET command specifies the primary command to be executed when you type name on the primary command line.  command may be the name of a macro or an SPFLite built-in primary command.


command may optionally contain operands.  When you type name on the command line and follow name by operands, those operands will appear after the command you defined, including any operands of its own that may be there.


Aliases are normal SET names, and all rules for SET names apply to SET aliases.  To delete an alias, you can issue SET ALIAS.name OFF, or enter a SET Edit session and delete the line containing the SET alias definition.


NOTE:  Alias names are only recognized as such as the first word on the command line.  If an alias name appears anywhere else, it is an ordinary SPFLite command operand with no special meaning.


How does this differ from defined SET names available previously?


Prior versions of SPFLite allowed general-purpose names to be defined.  When you use them on the command line, it is necessary to put an = equal sign in from of them.  So, if you wanted E to mean "EDIT", you would issue


SET E = EDIT


and then to use this E value as a command to edit file ABC.TXT, you have to put this on the command line:


=E ABC.TXT


With SET aliases, the = equal sign is no longer needed, as the following example shows:


Example


To define E as an alias for the primary command EDIT:


SET ALIAS.E = EDIT


and then to use this E value as a command to edit file ABC.TXT, you put this on the command line:


E ABC.TXT


Created with the Personal Edition of HelpNDoc: Easily create EPub books