|
<< Click to Display Table of Contents >> Navigation: Reference > Pre-processor > *DATA |
The *DATA command defines a data set.
Each data set is given a name or may be given a unique number, in the range 1 through 1000000000. There may be any number of data sets in a CL script.
A PP 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 insert file.
If you use a CSV file (as output from Excel) for the data set the file is read and the contents placed into the data set. In this case speech marks round text items are stripped off before being 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] does not affect CSV files, you must use a T parameter (see below) if a comma is not used.
The syntax of the *DATA command is:
[*DATA dsname (par,par...)=item,item,]
[*DATA dsname (par,par...) CSV=filename]
[*DATA dsname ( ) CSV=filename]
where dsname is the data set name (or number), par are data set parameters, item are the texts to be substituted when the data set is referenced or filename is the name of the CSV file containing the items.
If CSV is used, then 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 suffix is used in the filename then the suffix .CSV is assumed. The filename may contain any characters that are legal for a file name under the current operating system. Full path names are allowed.
See also *LINES which may be used to check whether a CSV file is present.
IMPORTANT: for PP data sets which are defined (using the *DATA command) 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.
The data set name follows the word DATA in the command, for example:
[*DATA dsNames ... ] defines data set dsNames.
An individual set may be redefined as often as necessary. Redefinitions replace earlier definitions.
There are some parameters for set definition which appear in parentheses after the set number. If more than one parameter is required, 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. See next paragraph for example.
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.
[*DATA x (M=C) = ... ] no longer allowed.
[*DATA x (M=P) = ... ] specifies that the items in this definition may contain PP code (within [ ]). If this parameter is omitted all items are treated as text. Any PP commands or substitutions in the items will be done when the item itself is substituted. This parameter is not needed for CSV data sets unless [*NOPPINCSV] is used.
Ignored.
[*DATA x (T=c) = ... specifies that character c is the delimiter for items in this set definition (and 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 exclamation mark. Different definitions of the same set may use different settings for parameter T.
The items are specified following an equals sign. Items may be up to 255 characters long; leading blanks are ignored by the Pre-processor 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.
Examples of valid *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=;) = Cats, Mice; Goats, Cows]
[*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]
CSV example:
If a file called VALUE.CSV contains:
23,Fred,100
24,"Jen",200
,Flynn,50
then:
[*data dsValues () csv=value]
is equivalent to:
[*data dsValues =
23,Fred,100,
24,Jen,200,
,Flynn,50]