Epi Info™ User Guide

Command Reference


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.

Date Mask
* System Time Format
! System Long Date

 

Numeric Mask
# Digit placeholder (Entry required).
. Decimal placeholder. The actual character used is the one specified as the decimal placeholder in the computer’s international settings.
, Thousand separator. The actual character used is the one specified as the thousands placeholder in the computer’s international settings.
9 Digit placeholder. (Entry optional).
Punctuation Included in the display.

 

Custom Formats
D One- or two-digit day.
Dd Two-digit day. Single-digit day values are preceded by a zero.
Ddd Three-character weekday abbreviation.
dddd Full weekday name.
H One- or two-digit in a 12- hour format.
Hh Two-digit hour in a 12-hour format. Single digit values are preceded by a zero.
H One- or two-digit hour in 24-hour format.
HH Two-digit hour in a 24-hour format. Single digit values are preceded by a zero.
M One- or two-digit minute.
Mm Two-digit minute. Single digit values are preceded by a zero.
M One- or two-digit month number.
MM Two-digit month number. Single digit values are preceded by a zero.
MMM Three-character month abbreviation.
MMMM Full month name.
S One- or two-digit seconds.
Ss Two-digit seconds. Single- digit day values are preceded by a zero.
T One-letter AM/PM abbreviation. AM displays as A.
Tt Two-letter AM/PM abbreviation. AM displays as AM.
Y One-digit year. 1997 displays as 7.
Yy Last two digits of the year. 1997 displays as 97.
Yyyy Full year. 1997 displays as 1997.
Punctuation Included in the display

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
Page last reviewed: September 16, 2022, 12:00 pm