This version of the Q4TODDL program has been updated for SDA. It is almost identical to the older CSA version, except that the interactive interface (based on old character-based technology) is no longer supported. Q4TODDL still generates the old (CSA- compatible) version of DDL. However, SDA programs are able to read such DDL files.
|MODES OF OPERATION|
|* Batch mode|
|* Command-line mode|
|FILES TO PREPARE|
|* Q-language files|
|* Layout file|
|* Dataset definitions|
|* List of variables|
|* Alternate names for files|
|* Create list of items processed|
|DATA LOCATION CONVERSION|
|* Map record numbers to other values|
|* Convert locations to a single long record|
|DIAGNOSTIC MESSAGE HANDLING|
|* File for diagnostic messages|
|* Report missing variables|
|MISSING DATA SPECIFICATIONS|
|* Automatic MD1 specification|
|* Automatic MD2 specification|
|* Force Automatic MD1 and MD2 Generation|
|* Automatic MIN specification|
|TEXT CONTROL OPTIONS|
|* Include all item/form lines in text|
|* Suppress all text sections|
|* Attach a prefix to variable names|
|* Suppress category labels|
|* Create DDL for non-input items|
|NAME OF THE OUTPUT FILE|
|DDL KEYWORDS AS Q-LANGUAGE EXTENSIONS|
|* DDL Keywords|
|* Suppression of text or category labels|
|* Control of text to be output|
|NOTE ON NAMES FOR ARRAY ELEMENTS|
|NOTE ON VARIABLE TYPES|
These additional specifications can either be added to the DDL file produced by Q4TODDL, or they can be included in the Q- language file itself in a way that will not affect the execution of the CASES programs. The advantage of including these additional specifications in the Q-language file itself is that it consolidates in one place all of the relevant specifications for a variable. Instructions for doing this are given below under the heading DDL Keywords as Q-language Extensions.
In the following descriptions of Q4TODDL options, the corresponding batch keywords and command-line options are given.
Every time Q4TODDL runs in either of the two modes, a file named Q4TODDL.OPT is generated. This file contains the batch-mode keywords for the options requested and the Q-language files used as input on the last run. This file can be edited or used as is to repeat a run in batch mode, using the ‘-b’ option. Since this file is overwritten each time Q4TODDL runs, rename or copy it if you want to preserve it.
If necessary, a layout file can be created manually, using the following format: Each line consists of a variable name (the item name in the Q-language instrument); variable type (integer, float, or char); record number; starting column location; width of the field (the number of columns; if there are implied decimal places, they are indicated by appending a period (.) and the number of implied decimals); and finally, an indicator of whether or not the variable is an input item (for a non-input item, put a zero in the last field or just leave it blank; for an input item, put ‘Y’ or ‘1’ or any other character except a zero). Each of these fields must be separated by one or more blanks. For an example of a layout file, see the q4toddl examples help file.
Q4TODDL simply copies the contents of this overall dataset definition file to the beginning of its DDL output file. The dataset definition file, consequently, could also contain DDL specifications created on a previous run or by hand.
If this file is not found, Q4TODDL will warn you and will generate the minimum necessary dataset definition and CASEID keywords, but they will have blanks after the equal sign, and you will have to edit the resulting DDL file manually. If you really want to generate DDL without overall dataset definitions -- in order to append the output to a DDL file that already has that information, for example -- simply create a file named ‘SDEFS’ with nothing in it.
Note that DDL is generated for variables in the order in which those variables are found in the Q-language file(s). A varlist does not affect that order.
A useful application of this inventory option is to run Q4TODDL without a VARLIST file. You will then generate a complete list of the (input) items in the Q-language file(s) which have an entry in the layout file. That list (saved in the file ‘Q4TODDL.IN1’) can be edited and used as the VARLIST for subsequent Q4TODDL runs.
Another application of this option is to use this list of variables as input to the SDA XCODEBK program. Without a list of variables, XCODEBK will output the variable descriptions in alphabetic order by name, which is unlikely to be the same order desired for a codebook (usually you want it to be in the same order as the questions were asked during the interview). If item names have been transformed by Q4TODDL, the list to use for this application is the one saved in ‘Q4TODDL.IN2’.
If, however, the datafile to be described with DDL is a subset of the original set of records for each case, and if the overall LAYOUT file (produced by the CASES ‘layout’ command) is used to determine the locations of each variable, the record numbers in the DDL must be adjusted to reflect that situation.
For example, if you create a data file containing only records 12 and 14, Q4TODDL needs to be informed that record 12 is now record 1, and record 14 is now record 2, for purposes of generating DDL to match that specific data file. In this situation you should also provide Q4TODDL with a list of variables, so that the program will limit its output to variables on those two records; otherwise you could end up with conflicting DDL definitions -- variable definitions from the original record 1 could conflict with definitions from the original record 12 (which is mapped to record 1 also).
If you want Q4TODDL to generate DDL for variables located on the zero record (variables identified in the LAYOUT file as being on record 0), you MUST use this mapping option. A location on record 0 will not make sense to any statistical system. For example, say you plan to create a data file that will contain for each case four regular data records followed by that case’s zero record (from the ZEROS file used by CASES). If you map record 0 to record 5, then the DDL locations will be correct.
If these options are selected, they are overridden if a variable in the Q-language file has its own missing-data specification (such as the ‘[##md1= ]’ Q-language extension discussed below).
Typically this option would be required if the Q-language instrument allows the input of characters like ’D’ or ’R’ for "don’t know" or "refusal" responses, and if those characters are then changed to numeric codes of ’8’ and ’9’.
For input items, this text segment consists of the template area for that item (or for the entire form, if the item is the first one on a multi-item form). Q-language commands other than ‘[fill]’, ‘[goto]’, and ‘[etc]’ are removed from the text. For many or even most input items, this text segment will show the wording for the question being asked and is more or less what we usually need in order to document that item.
For non-input items, the default text segment is all of the plain text in the item; all commands are removed.
This default generation of the ‘text=’ segment can be further restricted for a particular variable by using the ‘[##bt]’ and ‘[##et]’ Q-language extensions discussed below.
In addition, the following two options affect the generation of the ‘text=’ segment for ALL variables.
The following Q-language extensions are recognized by Q4TODDL. In CASES version 4 instruments, the commands for a variable must be placed either in the template area corresponding to that item (the part of the template BEFORE the field marker ‘@’) or in the part of the post-template area corresponding to that item (the part of the post-template AFTER the field marker ‘[@’ for that item). In CASES version 3 instruments, the commands can be placed anywhere in the item before the arrow ‘===>’.
[##label= ] long variable name -- up to 80 characters (default is 1st line of text segment) [##dname= ] DDL name for this item (default is item name in Q-file) [##type= ] variable type: decimal, integer, or character [##scale= ] number of implied decimal points [##min= ] minimum valid value [##max= ] maximum valid value [##md1= ] first missing-data code [##md2= ] second missing-data code [##blank= ] number into which an all-blank field should be converted [##other= ] number into which a field with non-numeric characters should be converted [##[ ] ] short label for a code value -- up to 16 chars (this bracketed label can be located either in the template or in the post-template, after the relevant code value in ‘<>’ and before the next code value; this label is in addition to any plain text for a category found in the item template.)
All of the above keywords except the last can be abbreviated to 3|characters, and the equal sign is optional. For instance, [##label=myvariable] can be abbreviated as [##lab myvariable].
[##nt] Suppress the ‘text=’ segment [##nc] Suppress category labels
[##bt] Begin text for output to DDL [##et] End text for output to DDLUp to 50 pairs of these commands can be used within a single item, in order to specify the blocks of Q-language text that should be output as a ‘text=’ DDL segment. Each block specified in such a manner is output beginning on a new line in the DDL.
Every item has an implied [##bt] marker at the beginning of the
item. Thus, if you only want the first four lines to be output
to the DDL, a closing [##et] command at the end of the fourth
line would be the only command required. Otherwise, [##bt] and
[##et] should always be used in pairs.
myarray_1_1 myarray_1_2 myarray_2_1 myarray_2_2If you want to generate DDL for only some of the array elements, specify which elements you want in the VARLIST file. For example, the second element of the array given above can be specified in a VARLIST either as ‘myarray(1,2)’ or as ‘myarray(<1>,<2>)’. Notice that this latter form is the same as the syntax required for an itemlist for the CASES ‘output’ program. A list of items used for ‘output’ can be edited and used also for Q4TODDL.
If you request Q4TODDL to create an inventory file of items processed (see the option description above), the names of array elements will appear with different formats in each of the two lists. In the file ‘Q4TODDL.IN1’ that second element of the array will be listed as ‘myarray(<1>,<2>)’. This is the form useful for creating and editing a list to be used either as a VARLIST on successive runs of Q4TODDL or as an itemlist for the CASES ‘output’ program.
In the second inventory list, ‘Q4TODDL.IN2’, that same element of
the array will be listed as ‘myarray_1_2’. This is the form that
would be required on a list of variables used as input to the
‘ddltox’ program to produce a setup for SPSS or SAS. This is
also the form that would be used in a variable list for the SDA
‘xcodebk’ program. Note that if a DDL name for the array has
been supplied with a ‘[##dname=]’ command, the transformed name
is used in this second inventory list.
The distinction in DDL between integer and decimal types only refers to the particular characters that are allowed (by the older CSA programs) in the ascii data file for a variable. Both of those type specifications, however, produce a numeric variable in an SDA (or CSA) dataset, and that variable can have implied decimal places. (See the DDL documentation for more on this topic.)
Since the ascii data file produced by the CASES ‘output’ program does not contain explicit decimal points, all numeric fields look like integers. If there are implied decimal places in a number, that information is contained in the layout file. For example, if the layout file specifies that a variable is of type float, and has a width of 4.2, Q4TODDL will translate that into a DDL specification for a variable of type integer, with a width of 4, and with a scale factor of 2. Be aware, however, that an integer or float with a field width greater than 9 columns is currently specified as a character variable in the DDL.
The conversion of character and date variables is more direct. Character and date variables in CASES are always specified as character type in DDL. Note, however, that you may not really want a variable defined by CASES as a character or date variable to be treated as such for purposes of analysis. CASES version 4 will consider an item to be of type character if it has any non- numeric precodes that are not designated as ‘missing’, even if those non-numeric precodes were never actually used. If such items are really intended to be interpreted as numeric variables for purposes of analysis, the type of that item can be changed to integer in the layout file before running Q4TODDL. However, if non-numeric characters are present in the data field itself, CSA will not process such an "integer" variable unless the DDL specification ’other=’ has been added. SDA will set cases with non-numeric characters in a numeric field to the system missing- data value, unless the non-numeric codes have been specified as missing-data.
CASES version 3 does not provide a type specification for each item in the layout file. For those instruments Q4TODDL attempts to interpret each item as an integer; however, if the item has one or more non-numeric precodes or it has a width greater than 9 columns, it is treated as a character variable.
Q4TODDL does not currently attempt to create category labels for character variables; for numeric variables it generates labels for the numeric precodes, but it ignores any non-numeric precodes.
The ‘no data’ type of variable in Version 4 of CASES is used for
informational screens. Such variables do not have data or data
locations and consequently cannot be stored in an SDA dataset.
However, they are sometimes of interest when generating codebooks
that document a CASES instrument. Q4TODDL will treat such items
as input items and will assign record and column specifications
of 0 (zero) in the DDL file. If the XCODEBK program is run
directly from a DDL file (instead of from an SDA dataset), ‘no
data’ items can appear in the codebook.
The maximum number of precodes per item is 110.
|DDL||Data Description Language|
|q4toddlb||Summary of batch keywords for Q4TODDL command files|
|q4toddlc||Summary of command-line options for Q4TODDL|
|q4toddle||Examples of Q4TODDL input and output|