Epi Info™ User Guide

Check Commands: Define

Description
This command creates a new variable. In Check Code, all user defined variables are saved in the DEFINEDVARIABLES section.

Syntax
DEFINE <variable> {<scope>} {<type indicator>}

• <variable> represents the name of the variable to be created. The name of the newly defined variable cannot be a reserved word. For a list of reserved words, see the List of Reserved Words section.
• <scope> is optional and is the level of visibility and availability of the new variable. <scope> must be one of the reserved words: STANDARD, GLOBAL, or PERMANENT. If omitted, STANDARD is assumed and a type indicator cannot be used. For information on defining a variable as a DLL OBJECT, see the DEFINE DLLOBJECT command.
• <type indicator> is required and cannot be used if <scope> is omitted. <type indicator> is the data type of the new variable and must be one of the following reserved words: NUMERIC, TEXTINPUT, YN, or DATEFORMAT. If omitted, the data type will be inferred based on the type of data of the first value assigned to the variable. However, omitting the data type is not recommended. Once a data type is defined, the field type cannot be changed. An error will occur if you attempt to assign data of a different type to the variable.

Comments
A custom variable defined in Epi Info 7 might not have a predefined data type if the <type indicator> is omitted at the time the variable is defined.  If the variable does not have a predefined data type, and the variable has not been used, the variable will accept a value in any of the four data types (Text, Number, Date, Yes/No [Boolean]) that is assigned to the variable the first time. Thereafter, the variable takes on the data type of the value assigned and it’s data type cannot be changed. However, omitting field type is not recommended.  An error will occur if you attempt to assign data of a different data type. Various functions can be used to manipulate data such as changing the data type of values to match the data type of the variable.  Some of these functions include FORMAT, TXTTONUM, TXTTODATE, and NUMTODATE.

Variable Scope

• STANDARD variables retain their value only within the current record and are reset when you load a new record. Standard variables are used as temporary variables behaving like other fields in the database. In Classic Analysis, Standard variables lose their values and definitions with each READ statement.
• GLOBAL variables retain values across related forms and when the program opens a new form, but are removed when you close the Enter program. Global variables persist while the program is executed. Global variables are also used in Classic Analysis to store values between changes of data source.
• PERMANENT variables are stored in the EpiInfo.Config.xml file and retain any value assigned until the value is changed by another assignment or the variable is undefined. They are shared among Epi Info programs (i.e., Enter, Classic Analysis, Visual Dashboard, etc.) and persist even if the computer is shut down. Permanent variables in Classic Analysis may not have values that depend directly or indirectly on table fields.  A <prompt/description> created for a permanent variable will exist for one session, and must be re-established each time it is used.

Type Indicators

• TEXTINPUT – Variables of this data type can receive any alpha-numeric characters including symbols and text output of functions (e.g., FORMAT).
• NUMERIC – Variables of this data type can receive numbers and the numeric output of functions (e.g., TXTTONUM).
• DATEFORMAT – Variables of this data type can receive date values including the date output of functions (e.g., TXTTODATE and NUMTODATE).
• YN – Variables of this data type can receive the Boolean values of (+) for Yes and (-) for No. Until an assignment is made, YN type variable values are (.) or missing.

Examples
Example 1: A variable is defined without <scope>, <type indicator>, and <prompt/description>. Standard scope thus becomes the default scope. As no type is specified, the variable can be assigned number, date, text, or Boolean data. However, once assigned a value, the data type of the variable becomes the data type of the value that has been assigned and may not be changed.

DEFINE BodyMassIndex NUMERIC

Example 2: A variable with standard scope and of type YN is defined.

DEFINE DoYouSmoke YN 
IF DateSmokingStarted = (+) THEN
     ASSIGN DoYouSmoke = (+) 
ELSE
     ASSIGN DoYouSmoke = (.) 
END

Example 3: A variable with standard scope and in date format is defined.

DEFINE DateOfBirth DATEFORMAT

Example 4: A variable with permanent scope is defined, but with no <type indicator>. As described in Example 1, the variable data type will be set with the first assignment of data and cannot be changed thereafter.

DEFINE StateID PERMANENT

Example 5: A variable with global scope and of type text is defined.

DEFINE  PatientID GLOBAL TEXTINPUT