Using ~write_specs and ~reformat to Output Specs

By default, a variable such as [10.2#1//20] is converted to a NUMERIC question, but a variable such as [10.2#1/AA/BB/CC/DD/EE] is converted to a FIELD question because there are too many alpha exception codes. By using the PREFER_FLD_TO_NUM option, both of these variables will be converted to FIELD questions.

Variables like [1#] are illegal.

The default for an unspecified NUMERIC minimum is zero, which means that there are a couple of small changes in the def files.

1) When cmentor= is used on a numeric data location such as [1], the specs created now begin at 1 instead of zero.

2) You can now use cmentor= on pound-sign variables that do not have any range specified, such as [1#].

Using ~write_specs and ~reformat without ~prepare questions

You might want to use ~write_specs or ~reformat on variables that were not created by compiling a Survent questionnaire via ~prepare. Ina ~write_specs block you can achieve this by using keyword=varname as in:

~write_specs cmentor=Q1

In ~reformat you do this by using the variables=(var, var, …) option, as in:

~reformat variables=(Q1) cmentor

NOTE: When used, the variables= option must be the first option specified.

What variables may be used?

Not all C-Mentor variables may be used. Mentor attempts to turn the variable into a question. If it cannot do this, it cannot convert thevariable. In particular, expressions cannot be converted. Thus, any variable that contains “with”, “by”, “when”, etc. cannot be converted. Likewise variables that contain $[keyword] cannot be used. The following variables may be used with ~write_specs:

• test2: [1] <— Not legal in tabsets
• test4: [1$] <— Not legal in tabsets
• test6: [1^1//5]
• test8b: [1#a/b/c/d/e]
• test8d: [1#”1″/”2″/”3″/”4″/”5″]

NOTE: See below for how to use write_specs with tabsets.

The following variables MAY NOT be used with ~write_specs:

• test1: 1
• test3: [1] with [2]
• test7: [1^1//5] with [2^1//5]
• test8: [1#1/2/3/4/5]
• test8a: [1#]
• test9: [1#1/2/3/4/5] with [2#1/2/3/4/5]
• test10: $[mean] [1]
• test11: [1#] $[mean] [1]
• test12: [1#1/2/3/4/5] $[mean] [1]

What do ~write_spec/~reformat do?

The ~write_specs command writes out table specs for the tab language specified. The options currently available are: cmentor, quantum, spss,persee, and hpsplmentor.

NOTE: Since the only tab language that everyone reading this must know is C-Mentor, the examples which follow will be for cmentor specs. Any of the other types of specs available may be substituted where the examples say “cmentor=”.

Mentor attempts to make the nearest equivalent in the language specified to a row=, stub= and a title=. For example, if you were to ask Mentor to write cmentor specs for “Q1: [5^1//3]”, you would get the following tabset in the .def file:

tabset= { q1_z:title=:q1}stub=:001002003}row=: [5.1^1/2/3]}

And the following in the .tab file:

tabset=q1_z

The ~reformat variables=(Q1) command would do essentially the same thing, however, the row variable’s data location would be that of thereformatted data, instead of the original location.

What about tabsets?

Besides the variables already mentioned, ~write_specs may also be used to output specs from tabsets.

Tabsets used as input to ~write_specs must contain the following three elements: row=, stub=, and title=. Without all three of these anerror will be generated, and no specs will be written for the tabset containing the error. The row= spec inside the tabset must follow thesame rules as already mentioned, in addition to which the variable may NOT be spec’ed without categories as in “Q1: [1]”. Tabsets may notcontain tab= or store= statements, these will cause errors.

The tabset written by Mentor will contain only the title, stub, and row from the original tabset. All other tabset elements are not passedto the .def file. This means that tabsets written with the intention of later using them with ~write_specs should have all of their importanttext infomation on the title= and not on the header, title_2,4,5 or footer.

Example Spec writeref1.spx:

~comment&writref.doc~deftest1: 1test2: [1]test3: [1] with [2]test4: [1$]'' test5: [1$] with [2$]test6: [1^1//5]test7: [1^1//5] with [2^1//5]test8: [1#1/2/3/4/5]test8a: [1#]test8b: [1#a/b/c/d/e]'' test8c: [1#a//e]test8d: [1#"1"/"2"/"3"/"4"/"5"]test9: [1#1/2/3/4/5] with [2#1/2/3/4/5]test10: $[mean] [1]test11: [1#] $[mean] [1]test12: [1#1/2/3/4/5] $[mean] [1]~specfile writref1~write_specs'' These should all work.cmentor=test2cmentor=test4cmentor=test6cmentor=test8bcmentor=test8d'' These variables cannot be converted.cmentor=test1cmentor=test3cmentor=test5cmentor=test7cmentor=test8cmentor=test8acmentor=test8ccmentor=test9cmentor=test10cmentor=test11cmentor=test12~end

Example Spec writeref2.spx:

~comment'' &writref.doc~deftest2: [1]test4: [1$]test6: [1^1//5]test8b: [1#a/b/c/d/e]test8d: [1#"1"/"2"/"3"/"4"/"5"]Q1: [5^1//3]~specfile writref2~write_specscmentor=test2cmentor=test4cmentor=test6cmentor=test8bcmentor=test8dcmentor=Q1~input $~reformat variables=(test2 test4 test6 test8b test8d) cmentor~def&writref2.def~set autotab~exccol=: total&writref2.tabrunchain reset printall~end~comment&writref.doc~deftest1: 1test2: [1]test3: [1] with [2]test4: [1$]'' test5: [1$] with [2$]test6: [1^1//5]test7: [1^1//5] with [2^1//5]test8: [1#1/2/3/4/5]test8a: [1#]test8b: [1#a/b/c/d/e]'' test8c: [1#a//e]test8d: [1#"1"/"2"/"3"/"4"/"5"]test9: [1#1/2/3/4/5] with [2#1/2/3/4/5]test10: $[mean] [1]test11: [1#] $[mean] [1]test12: [1#1/2/3/4/5] $[mean] [1]~specfile writref1~write_specs'' These should all work.cmentor=test2cmentor=test4cmentor=test6cmentor=test8bcmentor=test8d'' These variables cannot be converted.cmentor=test1cmentor=test3cmentor=test5cmentor=test7cmentor=test8cmentor=test8acmentor=test8ccmentor=test9cmentor=test10cmentor=test11cmentor=test12~end

Example Spec writeref3.spx:

~comment'' &writref.doc~deftabset={tabset1:title={: Just a number. }row=: 1stub={:one}}tabset={tabset2:title={: Numeric data locataion. }row=: [1]stub={:one}}tabset={tabset3:title={: Numeric data locataion with another numeric data location. }row=: [1] with [2]stub={:onetwo}}tabset={tabset4:title={: String data location }row=: [1$]stub={:one}}tabset={tabset5:title={: Range of punches. }row=: [1^1//5]stub={:onetwothreefourfive}}tabset={tabset6:title={: Range of punches with another range of punches. }row=: [1^1//5] with [2^1//5]stub={:onetwothreefourfivesixseveneightnineten}}tabset={tabset7:title={: Pound sign range of categories. }row=: [1#1/2/3/4/5]stub={:onetwothreefourfive}}tabset={tabset8:title={: Pound sign no categories. }row=: [1#]stub={:one}}tabset={tabset9:title={: Pound sign, all alpha. }row=: [1#a/b/c/d/e]stub={:abcde}}tabset={tabset10:title={: Pound sign, quoted numbers. }row=: [1#"1"/"2"/"3"/"4"/"5"]stub={:onetwothreefourfive}}tabset={tabset11:title={: Pound sign with another pound sign. }row=: [1#1/2/3/4/5] with [2#1/2/3/4/5]stub={:onetwothreefourfivesixseveneightnineten}}tabset={tabset12:title={: Just a mean. }row=: $[mean] [1]stub={:mean}}tabset={tabset13:title={: Pound sign with mean. }row=: [1#] $[mean] [1]stub={:onemean}}tabset={tabset14:title={: Pound sign range with mean. }row=: [1#1/2/3/4/5] $[mean] [1]stub={:onetwothreefourfivemean}}~specfile writref3~write_specscmentor=tabset1cmentor=tabset2cmentor=tabset3cmentor=tabset4cmentor=tabset5cmentor=tabset6cmentor=tabset7cmentor=tabset8cmentor=tabset9cmentor=tabset10cmentor=tabset11cmentor=tabset12cmentor=tabset13cmentor=tabset14~end

Example spec writeref4.spx:

~comment'' &writref.doc~deftabset={Q1:header={: Header for tabset one. }title={: Title for tabset one. }footer={: Footer for tabset one. }edit={: -coltna colwid=6 }col=: totalbanner={: