Define
The Define type defines a category list (sometimes called a defined list or a shared list) that can be reused. By itself, the Define type does not define a question.
Syntax
For clarity, each item is shown on a separate line, and optional items are indented, See also
Syntax conventions.
field_name
[
"field_label" ]
[
[ <properties>
] ]
[ <styles and templates> ]
define
<categories>
Parameters
field_name, field_label
<properties>
You can define custom properties for your field to store information that is not directly supported by the Metadata Model (MDM). For more information, see
Custom properties.
<styles and templates>
You can use styles and templates to define the appearance of a question. For more information, see
Styles and templates.
<categories>
The category list is defined in the same way as for the
Categorical type.
Remarks
Use the @ character to avoid issues with VDATA and HDATA expressions. To refer to the question that is using the defined list, include an @ character in the declaration. In the following example, the @ character has been added to a category expression in the Rating defined list. When the defined list is used, the @ character refers to the variable in which the list is used, allowing the expression to be resolved correctly:
Rating "" define
{
Top2 "Top 2" elementtype(AnalysisCategory)
expression("@ * {Excellent, VeryGood}"),
Excellent "Excellent",
VeryGood "Very Good",
Good "Good",
Fair "Fair",
Poor "Poor"
};
Similarly, this same technique can be used to avoid issues in loops, where different expressions are required for VDATA and HDATA. For example, for the RatingGrid grid in the UNICOM Intelligence Developer Documentation Library Museum sample, a Top 2 element is added as follows:
RatingGrid "Galleries planned to visit" loop
{
Dinosaurs "Dinosaurs",
Conservation "Conservation",
Fish_and_reptiles "Fish and reptiles",
Fossils "Fossils",
Birds "Birds",
Insects "Insects",
Whales "Whales",
Mammals "Mammals",
Minerals "Minerals",
Ecology "Ecology",
Botany "Botany",
Origin_of_species "Origin of species",
Human_biology "Human biology",
Evolution "Evolution",
Wildlife_in_danger "Wildlife in danger"
} fields
(
"Column" "Interest rating for galleries - respondents entering"
categorical [0..5]
{
Top2 "Top 2" elementtype(AnalysisCategory)
expression("@ * {Slightly_interested_4, Very_interested_5}"),
Very_interested_5 "Very interested (5)",
Slightly_interested_4 "Slightly interested (4)",
No_opinion_3 "No opinion (3)",
Not_particularly_interested_2 "Not particularly interested (2)",
Not_at_all_interested_1 "Not at all interested (1)"
};
) expand grid;
When the @ character is not used, different expressions need to be defined for the VDATA and HDATA. For example:
HDATA
Top2 "Top 2" elementtype(AnalysisCategory) expression("Column * {Slightly_interested_4, Very_interested_5}"),
VDATA
A different expression needs to be defined for each slice. For example:
Top2 "Top 2" elementtype(AnalysisCategory) expression("Rating[{Dinosaurs}].Column * {Slightly_interested_4, Very_interested_5}"),
Any defined lists that you create inside a block or a loop are visible only within that block or loop. If you create a defined list inside a block or loop using the same name as a defined list that already exists in the parent code, the defined list within the block or loop will take precedence over the one in the parent code.
For more information about writing defined lists in interview scripts, see
Creating shared lists.
Examples
Simple category list used in a categorical question
This example uses the Define keyword to create a simple category list called America, which is then used in a categorical question called Live1 with the namespace option. A Refused to answer category is added to the category list in the question.
America define
{
USA,
Canada,
Brazil,
Peru,
Chile
};
Live1 "Which country in the Americas do you live in?" categorical [1]
{
use America namespace,
- "Refused to answer" REF
};;
A defined list made up of other defined lists
This example creates four simple defined lists--America, Europe, Africa, and Dontknow. The example then uses them to create a fifth defined list, called World, and this is used in a question, Live2.
America define
{
USA,
Canada,
Brazil,
Peru,
Chile
};
Europe define
{
UK,
France,
Spain,
Germany,
Denmark
};
Africa define
{
Egypt,
Zimbabwe,
Kenya
};
Dontknow define
{
- "Don't know" DK,
- "Refused to answer" REF,
- "Not answered" NA
};
World define
{
use America,
use Europe,
use Africa,
use Dontknow
};
Live2 "Which country do you live in?" categorical [1]
{
use World
};
Multiple response question containing two groups of categories
This example is similar to the
Multiple response question containing two groups of categories in
Categorical, which defines a multiple response question that contains two groups of categories. However, now the category list is declared using two defined lists. The first defines the
Positive group of categories and the second defines the
Negative group.
Positive define
{
NoProb "No Problems - no cause to complain",
GoodService "Good Service",
GoodBreakdown "Provides breakdown of expenses",
CardsAccept "Wide acceptance of cards",
PosOther "Other positive" other fix
} ran;
Negative define
{
Slow "Slow to respond/poor service",
LimitedCards "Limited acceptance of cards",
Inaccurate "Inaccuracies of bills",
CostTooHigh "Costs too high/expensive",
CustContact "Not enough customer contact/service",
NegOther "Other negative" other fix
} ran;
Service "What are your impressions of the service/billing?" categorical [1..]
{
use Positive,
use Negative,
- "Don't know" DK
} rot;
You must declare the defined list before using it in a question. If it is used before it is declared, the name is assumed to be a category. An error occurs if a defined list name matches that of a category declared earlier in the script.
The MDM gives an error if two or more categories in a question have the same full name. However, you can combine category lists that contain categories that have the same name, provided you use the
namespace keyword. For more information, see
Categorical.
See