|
<< Click to Display Table of Contents >> Navigation: Command Language > Preprocessor > Preprocessor index usage |
The preprocessor maintains a library of variables with a value.
To avoid confusion with a CL variable, they are referred to as an "index", or "indices" for more than one of them.
You can set, modify, test and substitute the value of an index into your output.
There is no limit on the number if indices used.
The indices are all preset to a special "null" value. You can assign a value to an index using *SET, *DO or *FOR commands.
Special types of index are used in *DATA, *DBOPEN, *DBLOOP, *SBDEF, and *SBCALL commands. Index names set in these commands are reserved for this purpose and cannot be used as ordinary indices elsewhere.
Each index has a name that must consist of letters (a-z) or numbers (0-9). The first character must be a letter (a-z). Case is ignored when comparing names so Top2Index is the same as TOP2INDEX.
We recommend using index names consisting of whole words put together with the first letter of each word in upper case, for example, ProductFirst.
For special use indexes, we recommend using the first two characters of any index name to identify the special use:
•ds for a *DATA data set index
•df for a *DBOPEN file index
•dl for a *DBLOOP loop index
•lp for a *DO or *FOR loop index
•sn for a *SBDEF subroutine name
•sp for a *SBDEF subroutine parameter
Normal indices hold a numeric (integer) value or a text value.
The numerical value of an index is within the range for a 64 bit integer and can be positive, negative, or zero.
A text value will be treated as a numeric value if it contains a valid number. If you do not want a text value to be used as a number use [@name].
The values of indices can be preserved using *PUSH and *POP, see Preprocessor inserting scripts.
The most common way to give an index a value is the *SET command which sets the value (or text) of an index. It takes one of these forms:
[*SET index = integer]
[*SET index = arithmetic]
[*SET index = 'text’]
[*SET index = datasetref]
[*SET index = cellref]
[*SET index = %ITEMS($varname)]
[*SET index = %ROWS(#tablename)]
[*SET index = %COLS(#tablename)]
[*SET index = %STARTYEAR]
[*SET index = %STARTMONTH]
[*SET index = %STARTDAY]
[*SET index = %STARTHOUR]
[*SET index = %STARTMINUTE]
[*SET index = %STARTSECOND]
[*SET index = %STARTSETUPPATH]
[*SET index = %STARTSETUPFILE]
IMPORTANT: %ITEMS, %ROWS, and %COLS are only available for entries and tables created in Companion when running tables in Companion.
The index to be set must not already be in use as a special type of index.
The value of an index can be changed at any time using a new *SET command.
Examples of valid *SET commands to set a value:
[*set This=5]
[*set Count=Count+1]
[*set Line=(Product-1)*(10+Part)]
[*set Col = Start+1, Card = Begin+2, LastCol = Start+3]
[*set PartType=1.Part]
[*set Colour=ColourSet.3]
[*set Found=Loop.Type+1]
[*set Value=dbList.value]
There is also a special command to add 1 to the value of an index, so the following commands have the same effect:
[+TableNumber]
[*set TableNumber=TableNumber+1]
The *SET command can be used to set an index to text, for example:
[*set ThisPlace=’Paris’]
[*set ThatPlace=dsPlaces.lpThis]
[*set OtherPlace=’[dlPlaces.’Place’]’]
When an index is substituted, any valid whole number value will be used. The text is only used if it does not contain a valid number or it is surrounded by quotes.
Arithmetic consists of numbers, indices, and the four operators:
+ plus
- minus
* multiply
/ divide
A number on its own or an index on its own are both valid.
The value is the result of the computation involving the operators.
IMPORTANT: computation always proceeds from left to right unless parentheses are used to control the order of processing. So for example:
[*set First = 4]
[*set Second = 5]
[*set NewOne = First + Second * 2]
[*set NewTwo = First + (Second * 2)]
Sets NewOne to 18 and NewTwo to 14.
IMPORTANT: the result of division will be whole numbers which are truncated. Thus, 11/4 will equal 2 and not 2.75 or 3. So for example, this sets Number to 12:
[*set First = 4]
[*set Second = 5]
[*set Number = ((First/2)+(Second/2))*3]
The evaluation must never result in a value outside the range for a 64 bit integer (approximately 18 digits).
It must not contain a reference to an index whose value is unset; all indices must be set before they are referenced.
%ITEMS, %ROWS, and %COLS are only available for entries and tables created in Companion when running tables in Companion. These set the index to the number of responses in the entry, the number of rows in the table, or the number of columns in the table respectively.
%START functions for date and time set the index to the numerical value.
%START functions for the script set the index to the relevant text for the main CL script file.
When the opening square bracket is not followed by a * (asterisk) or a + (plus sign) it is treated as a substitution.
Substitutions can be used inside other substitutions of any type, and in preprocessor commands.
See data sets and database commands for other types of substitutions.
A numeric substitution takes place when the whole of the contents inside the square brackets are replaced by a value, for example:
[Next]
[4365]
[Total+1]
[FirstPart*10-1]
[(Prod1*5)+(Prod2*4)+ProdExtra]
All of these will be replaced with the value or the result of the arithmetic.
If the text substitution may contain a valid number, make sure that text is substituted preceded the index name with @, so using:
[*set Mytext=’15.0’]
Number is [MyText] and Text is [@MyText]
will output "Number is 15 and Text is 15.0"
The @ can be followed by ~ for lower case and & for upper case so:
[*set Mytext=’This Item’]
[MyText], [@MyText], [@~MyText], [@&MyText],
will output "This Item, This Item, this item, THIS ITEM,".