SDA 3.5 Documentation for DDLMOD

NAME

DDLMOD - Modify or Merge DDL or IDL files

USAGE

ddlmod -i DDLfile_1 [-j DDLfile_2] [-option]

DESCRIPTION

DDLMOD reads in a DDL file, then (if ‘-j’ is used) reads in a second file with additional or corrected specifications, and then carries out any specified editing. The program then writes out a new DDL file containing the additions and/or modifications. Diagnostic messages are written onto the file ‘DDLMOD.MSG’.

The program can also read an IDL file, which is an expanded DDL file containing additional elements to describe computer-assisted interviewing instruments. However the additional elements will not be preserved in the output file.

Merge Two DDL Files

If a second DDL file is specified (after ‘-j’), it is ordinarily used to supply DDL specifications LACKING in the first file, such as ‘text=’ specifications for certain variables, or complete variable definitions for variables not contained in the first DDL file. By default, any specifications already present in the first file, such as labels or missing-data codes, are NOT changed to match the contents of the second file.

However, if the ‘-m’ option is used, the contents of the second file will MODIFY any specifications already present in the first file.

The second file does not have to contain all the elements required for a valid DDL file. In the study description section, at the top of the DDL file, there only needs to be a ‘title=’ element. For each variable, the file only needs to contain the ‘name=’ element and any elements that are to be added to, or modified in, the corresponding variable in the first DDL file.

Editing Variable Names, Question Text, and Category Labels

The program can carry out some basic editing functions to make the output more useful and more attractive for documentation purposes. The ‘-b’, ‘-l’, ‘-u’, and ‘-x’ options fall into this category. This editing can be done on a single DDL file specified with ‘-i’. If a second file is specified with ‘-j’, the merging of the two files is done first, and then the editing is carried out on the merged file.

Produce DDL for CSA

The program can also convert a DDL file to the older DDL format used by the stand-alone CSA programs. The ‘-c’ option indicates that the output should be in that format. Some newer DDL features such as multiple missing-data codes and ranges, and character missing-data codes for numeric variables are not supported by CSA and therefore cannot be converted. If the input DDL file contains those newer features, the program will convert as many specifications as possible for each variable, and will write a warning in the DDLMOD.MSG file.

SUMMARY OF OPTIONS

Specification of the files

-i DDLfile_1: This is the name of the DDL file to start with. It is always REQUIRED to specify this input file.
-j DDLfile_2: This is the name of the additional file containing elements to add to, or to modify in, the DDL file specified with ‘-i’.
-m: Any elements contained in DDLfile_2 will modify the corresponding elements in DDLfile_1.
(Without this option, only the elements missing in DDLfile_1 will be taken from DDLfile_2.)
-o filename: Write the new DDL onto the file ‘filename’ (instead of to the standard output).
-w filename: Write variable descriptions for only those variables that are listed in the file ‘filename’.

Changing variable names to lower or upper case

-l: Convert all variable names to lower case (except CASEID)
(Note that the ‘-l’ is a lower-case ‘L’.)
-u: Convert all variable names to upper case

Editing the question text

-t: Remove a fixed number of leading spaces or tabs from lines of question text, while preserving relative indents. (Tabs are expanded to spaces, before this editing is done.)
For example, if most of the lines are indented by 8 spaces, but two of the lines are indented by 10 spaces, this option will remove 8 spaces from the beginning of each line, leaving two lines with indents of 2 spaces.
-b length: Break up long lines of text that exceed ‘length’ characters, where ‘length’ is the maximum number of characters (including leading spaces) that should be on a single line of text. The specified length must be at least 40. (If leading spaces are removed with the ‘-t’ option, that reduction in line length is carried out first.)
When lines are broken up by this option, the division is made at the space preceding the specified line length -- words are not divided. The names of all variables that have had their text broken up are listed in the DDLMOD.MSG file.

Editing category labels

-x: Remove code values from the beginning of category labels.
For example, if category labels had been created (or imported) like ‘1 Yes’ for code 1, and ‘2 No’ for code 2, this option would change those labels to ‘Yes’ for code 1 and ‘No’ for code 2. This also works if the labels include a decimal point like ‘1. Yes’.

Other options

-v filename: Write a list of variables contained in the new DDL file onto the file ‘filename’.
-c: Produce older DDL for CSA programs
-h: Display short program help and available options. (The program will not do anything else.)

EXAMPLES

ddlmod -i DDL1 -j DDL2 -o newddl: Add new material in ‘DDL2’ to ‘DDL1’, to make the file ‘newddl’ (but do not replace any specifications already contained in ‘DDL1’)
ddlmod -m -i DDL1 -j DDL2 -o newddl: Modify ‘DDL1’ by anything contained in ‘DDL2’, to make ‘newddl’
ddlmod -i DDL1 -t -b 60 -o newddl: Edit the question text in ‘DDL1’ by removing leading spaces and breaking up lines longer than 60 characters.
ddlmod -c -i DDL1 -o forCSA: Convert the file ‘DDL1’ into the older DDL format, and make the file ‘forCSA’.

DDL	Data Description Language
IDL	Instrument Documentation Language