Epi Info™ User Guide

Analysis Commands: DIALOG

Description
This command provides interaction with the user from within a program. Dialogs can display information, ask for and receive input, and offer lists for making choices.

Syntax
Simple Form
DIALOG “<prompt>” {TITLETEXT=”<title>”}

• <prompt> represents the text to be displayed as message.
• <title> represents the text to be used as the caption for the dialog window. If <title> is omitted in the Dialog command, “Analysis” will be displayed on the dialog box’s title bar.

Get Variable Form
DIALOG “<prompt>” <variable> <entry type> {TITLETEXT=”<title>”}
DIALOG “<prompt>” <variable> “<value 1>”, “<value 2>”, “<value 3>”, … ,”<value n>” {TITLETEXT=”<title>”}

• <variable> represents the variable to store value entered.
• <entry type> represents a reserved word and/or mask that defines the type of input to be accepted and stored in the variable. The following are valid entry types:
  • TEXTINPUT specifies the input as text.
  • YN specifies the input as Boolean.
  • DATEFORMAT (“<date mask>”) specifies the input as a date; if a date mask is not specified, the system short date is used.
  • “<numeric mask>” specifies the input as numeric. This option is identified as “Number Only”. The numeric mask should be a text string (e.g., “####” or “##.###”) that indicates the type of data to be entered. # indicates a digit.
  • If no <entry type> is specified, the input variable is interpreted as a number if possible. If the value is not a valid number, but is a valid date, it is interpreted as a date. Otherwise, an error occurs.
• <value> represents a value in a drop-down list of choices. Each value included in the command will be shown as a single item in the list.
• <file type selection> controls the type of files that are displayed for selection. It consists of alternating description and filter elements separated by vertical bars. The description is displayed for you to select. The corresponding filter element selects the files. If this element is left blank, all files can be selected. Syntax is created using the File Open and File Save options from the Dialog Format drop down menu.

List of Values Form
DIALOG “<prompt>” <variable> [<list type>] {TITLETEXT=”<title>”}
DIALOG “<prompt>” <variable> DBVALUES <table name> {TITLETEXT=”<title>”}

• The [<list type>] are DATABASES and DBVIEWS

Comments
The Simple form of DIALOG places a dialog box on the screen, using the text provided, with an OK button.

The Get Variable form of DIALOG displays the text prompt and provides a means for entering a value.

• If YN is specified, “Yes,” “No” and “Cancel” buttons are presented and the specified variable is set to (+), (-), or (.).
• If TEXTINPUT or no entry type is specified, an entry field for user response is provided with OK and Cancel buttons. The variable is assigned the value of the input with a missing value if Cancel is chosen.
• The Get Variable form of the DIALOG command can also display a file selection dialog. If READ is used, only existing files are displayed. If WRITE is used and an existing file is selected, you will see the Overwrite? prompt.
• The Multiple Choice form of DIALOG displays the text prompt and provides a combo box for selecting among the values with OK and Cancel buttons. The variable is assigned the value of the input with a missing value if Cancel is chosen. Variable will text type.
• The Date form of the DIALOG command uses a special control for accepting input. Each section of the date (year, month, and day) can be increased or decreased independently using the drop down calendar. Using this control, it is impossible to select an invalid date.

The List of Values form of DIALOG displays a combo box of databases or form variables with OK and Cancel presented. The variable is assigned the value of your input with a missing value if Cancel is chosen. Variable will be text type. The VARIABLE VALUE form of DIALOG displays a combo box of distinct values of the specified variable in the specified database. The variable is assigned the value of input with a missing value if Cancel is chosen. The variable will be of the same type as the database variable.

Examples
Example 1: A prompt is displayed letting you know that the following commands may take several minutes to complete because of their complexity.

DIALOG "Warning: This script may take several minutes to complete" TITLETEXT="Warning"

Example 2: The DIALOG command is used to obtain a user-supplied date to calculate the patient’s age. If you do not supply a date (press the Cancel button), the default ending date contained in the survey data source is used instead.

READ {.\Projects\Sample\Sample.prj}:Surveillance 
DEFINE UpdateDate DATEFORMAT 
DEFINE SubmitDate DATEFORMAT 
ASSIGN SubmitDate = EventDate 
DIALOG "Enter a new ending date for survey data:" UpdateDate DATEFORMAT "MM-DD-YYYY" 
DEFINE NewAge NUMERIC 
ASSIGN NewAge = YEARS(SubmitDate, UpdateDate) 
GRAPH NewAge GRAPHTYPE="Column"

Example 3: You will see a drop-down list of choices. The list contains part of the command; in this case, several counties in the state of Georgia. Your selection is temporarily assigned to all records in the form.

READ {.\Projects\Sample\Sample.prj}:Surveillance 
DEFINE  NewCounty TEXTINPUT 
DIALOG "Select a county" NewCounty "Fulton", "Baldwin", "DeKalb", "Cobb" 
ASSIGN CountyName = NewCounty 
LIST CountyName

Example 4: A drop-down list of choices is displayed. Each list item is retrieved from the X_COORD column of the SohoDead data table.

READ {.\Projects\Sample\Sample.prj}:SohoDead 
DEFINE Coordinates TEXTINPUT 
DIALOG "Select Coordinates" Coordinates DBVALUES SohoDead X_COORD TITLETEXT="Coordinates"

Example 5: A dialog box is displayed that allows you to enter a number. An input mask is used to force your input to three whole digits and one decimal digit. Your input is temporarily assigned to each record in the form.

READ {.\Projects\Sample\Sample.prj}:Oswego
DEFINE  NewAge NUMERIC 
DIALOG "Enter patient age" NewAge "###.#"
ASSIGN Age = NewAge 
LIST Age

Example 6: A dialog box is displayed that allows you to enter a number. An input mask is used in order to force your input to either one or two whole digits and one decimal digit. (The 9 represents an optional digit.) Your input is temporarily assigned to each record in the form.

READ {.\Projects\Sample\Sample.prj}:Oswego 
DEFINE  NewAge NUMERIC 
DIALOG "Enter patient age" NewAge "9##.#" 
ASSIGN Age = NewAge 
LIST Age