|
<< Click to Display Table of Contents >> Navigation: Command Language > Preprocessor > Preprocessor data sets |
The *DATA command defines a data set.
Data sets contain a list of texts that can be referred to using their position in the list.
Each data set is given an index name which cannot be used for any other purpose.
A data set contains a list of items (usually separated by commas) that are used for substitution into the CL script.
The list of items can be supplied in the *DATA command or can be read in from a CSV file, see below for details of *DATA from CSV.
The syntax of the *DATA command is:
[*DATA dsindex (par, par..., par) = item, item, ..., item]
The dsindex is the data set name, par are data set parameters, item are the texts to be substituted when the data set is referenced.
In items, leading blanks are ignored but others are not. New lines in or between items are ignored.
Items may be empty or consist only of one or more blanks, but a data set must contain at least one item.
Items are separated by commas, unless the *DSEP command has been used, or parameter T has been set.
An individual set may be redefined as often as necessary. Redefinitions replace earlier definitions.
IMPORTANT: for data sets which are defined within a loop you should use data set parameter (B=1) which causes each redefinition to overwrite the previous one rather using new resources. If (B=) or (L=) are used then any new definition cannot have more items than the previous definition.
Parameters appear in parentheses after the data set index name. If more than one parameter is required, a comma is used as a separator, for example:
[*data dsNumbers (m=p,t=/) = six/seven/[ThisOne]/[NextOne]]
This parameter allows the replacement of items in an existing data set starting at a particular numbered item. If this is the first definition of the data set then this parameter must be 1.
This parameter allocates a number of items in a data set. For the second and subsequent definitions of a data set this parameter must be the same if present. You cannot add items beyond the length specified.
[*data dsReplace (l=10) = 0]
[*data dsReplace (b=6) = 6,7,8,9,10]
[*data dsReplace (b=1) = a,b,c,d]
This data set now contains a,b,c,d,,6,7,8,9,10. The fifth item has not been set and is empty.
This specifies that the items in this definition may contain PP code within [ ]. If this parameter is not used all items are treated as text.
Any commands or substitutions in the items will be done when the item itself is substituted, not when the data set is created.
This parameter is not needed for CSV data sets unless NOPPINCSV is used.
[*DATA MyDataSet (M=P) = ... ]
This specifies that character set is the delimiter for items in this definition which cannot therefore be used as a character in an item. The standard setting is , (comma); this can be over-ridden globally by the *DSEP command. This parameter may be set to any character other than square brackets or an exclamation mark. Different definitions of the same set may use different settings for parameter T.
[*DATA MyList (T=:) = 1,3:5,8:9,0] ! has three items
Examples of *DATA commands:
[*data dsType = car, train, boat, bus, plane]
[*data 1=All answering question 14a]
[*data dsValues = 1,4,26]
[*data dsCode (m=p) = [1.Which], [5.1], [Loop.Next]]
[*data dsList = 10012, 10013, 79121]
[*data dsAnimals (t=;) = Rats, mice; Goats, Cows] ! contains 2 items with commas in them
[*data dsReplace (l=10) = 0]
[*data dsReplace (b=6) = 6,7,8,9,10]
[*data dsReplace (b=5) = 5]
[*data dsReplace (b=1) = 1,2,3,4] ! now contains a list of numbers 1-10
A data set reference takes the form:
[dsindex.arithmetic]
[dsindex.#]
The dsindex is the data set index name and the arithmetic is any valid calculation that produces a value which represents an item in the list.
References must be to valid items in a defined data set.
Where # is used, the reference is evaluated as the number of items in the data set.
Examples of valid set references:
[dsMine.5]
[5.Loop]
[dsLots.#]
The form of this command is:
[*DSEP=c]
where c is any character other than right square bracket or exclamation mark. The character c is used from this point on as the item delimiter in *DATA set definitions unless parameter T is used.
The syntax of the *DATA command is:
[*DATA dsindex (par, par..., par) CSV = filename]
[*DATA dsindex ( ) CSV=filename]
The dsindex is the data set name, par are data set parameters (see above), and filename is the name of the CSV file containing the items.
The ( ) must be present even if no parameters are needed, otherwise CSV will be treated as a part of the data set name.
If no extension is used in the filename, then the extension ".csv" is assumed.
Use quotes around the file name if it contains spaces.
The file is read and the contents placed into the data set.
A CSV file is assumed to use a comma (,) to separate the columns. A (T=) parameter can be used to specify another character.
The command *DSEP (see above) does not affect CSV files, you must use a T parameter (see below) if a comma is not used.
If a file called Value.csv contains:
23,Fred,100
24,"Jim",200
,Doug,50
then
[*data dsValues () csv=value]
is equivalent to
[*data dsValues = 23,Fred,100,24,Jim,200, ,Doug,50]
The *LINES is used to find out whether a file exists, and if it exists how many lines are in the file.
The form of the command is:
[*LINES index = filename]
The index is any index not currently in use for any special purpose.
The filename must include the extension, the preprocessor will not automatically add a suffix.
Examples of *LINES commands:
[*lines Present=main.stp][*skip 99 null Present][*insert main.stp][*99]
[*lines LineCount=\files\p123.asc]The file counts [LineCount] lines