SDA 3.5 Documentation for Q4TODDL

NAME

USAGE

DESCRIPTION

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.

CONTENTS OF THIS DOCUMENT

OVERVIEW

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.

MODES OF OPERATION

1. Batch mode: q4toddl -b filename [Q_files]

2. Command-line option mode: q4toddl [-option] Q_files

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.

FILES TO PREPARE

1. Q-language file(s): ’QFile = filenames’

2. Layout file: ’Layout = filename’ / ’-l filename’

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.

3. File with overall dataset definitions: ’Studydefs = filename’ / ’-s filename’

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.

4. List of variables: ’Varlist = filename’ / ’-v filename’

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.

OPTIONS

File Options

1. Alternate Names for Input Files

• Dataset definition file - default name = SDEFS
• Layout file - default name = LAYOUT
• List of variables - default name = VARLIST

2. Create an Inventory File: ’Inventory’ / ’-i’

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’.

Data Location Conversion

1. Map layout record numbers to other values: ’Map = a:b,c:d’ / ’-m a:b,c:d’

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.

2. Convert locations to a single long record: ’Appending’ / ’-a’

Diagnostic Message Handling

1. Save diagnostic messages in a particular file: ’Errorfile=filename’ / ’-e filename’

2. Report missing variables: ’Report’ / ’-r’

Missing Data Specifications

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).

1. Automatic md1 Generation: ’9fill’ / ’-9’

2. Automatic md2 Generation: ’8fill’ / ’-8’

3. Force Automatic md1 and md2 Generation: ’0fill’ / ’-0’

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’.

4. Automatic min Generation: ’Floor’ / ’-f’

Text Control Options

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.

1. Include all item/form lines in text: ’QUesfull’ / ’-q’

2. Suppress all text sections: ’Textelim’ / ’-t’

Miscellaneous Options

1. Attach a prefix to variable names: ’Prefix=abc’ / ’-p abc’

2. Suppress category labels: ’Catselim’ / ’-c’

3. Create DDL for non-input items: ’Noninput’ / ’-n’

Name of the Output File: ’Output=filename’ / ’-o filename’

DDL KEYWORDS AS Q-LANGUAGE EXTENSIONS

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 ‘===>’.

1. DDL Keywords

     

     [##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].

2. Suppression of text or category labels

     [##nt]     Suppress the ‘text=’ segment
     [##nc]     Suppress category labels
     

     

3. Control of text to be output

     [##bt]     Begin text for output to DDL
     [##et]     End text for output to 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.

NOTE ON NAMES FOR ARRAY ELEMENTS

     myarray_1_1
     myarray_1_2
     myarray_2_1
     myarray_2_2
     

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.

NOTE ON VARIABLE TYPES

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.

LIMITS

The maximum number of precodes per item is 110.

SEE ALSO