Progress
Language Reference
DEFINE VARIABLE Statement
Defines a variable for use within a procedure or within several procedures.
SYNTAX
NEW SHARED VARIABLE variable
Defines a variable to be shared by a procedure called directly or indirectly by the current procedure. The called procedure must name the same variable in a DEFINE SHARED VARIABLE statement.
NEW GLOBAL SHARED VARIABLE
Defines a variable that can be used by any procedure that names that variable using the DEFINE SHARED VARIABLE statement. The value of a global shared variable remains available throughout a Progress session.
SHARED VARIABLE variable
Defines a variable that was created by another procedure that used the DEFINE NEW SHARED VARIABLE or DEFINE NEW GLOBAL SHARED VARIABLE statement.
VARIABLE variable
Defines a variable whose value is available only within the current procedure.
AS datatype
Indicates the data type of the variable you are defining. The data types are CHARACTER, COM-HANDLE, DATE, DECIMAL, HANDLE, INTEGER, LOGICAL, MEMPTR, RAW, RECID, ROWID, and WIDGET-HANDLE.
LIKE field
Indicates the name of the variable, database field, temporary table field, or work table field whose characteristics you want to use for the variable you are defining. If you name a variable with this option, you must have defined that variable earlier in the procedure. You can override the format, label, initial value, decimals, and extent of the variable or database field by using the FORMAT, LABEL, COLUMN-LABEL, INITIAL, DECIMALS, EXTENT, and VIEW-AS options. If you do not use these options, the variable takes on the characteristics of the variable or database field you name.
If field has help and validate options defined, the variable you are defining does not inherit those characteristics.
If you reference a database field in a LIKE option in a DEFINE VARIABLE statement, DEFINE TEMP-TABLE statement, DEFINE WORK-TABLE statement, or format phrase, the database containing the referenced field must be connected at both compile time and runtime. Therefore, use the LIKE option with caution.
NO-UNDO
When the value of a variable is changed during a transaction and the transaction is undone, Progress restores the value of the variable to its prior value. If you do not want, or if you do not need, the value of a variable to be undone even when it has been changed during a transaction, use the NO-UNDO option with the DEFINE VARIABLE statement. NO-UNDO variables are efficient; use this option whenever possible.
Specifying NO-UNDO for a variable is useful if you want to indicate an error condition as the value of the variable, perform an UNDO, and later take some action based on that error condition. If one variable is defined LIKE another that is NO-UNDO, the second variable NO-UNDO only if you specify NO-UNDO in the definition of that second variable.
BGCOLOR expression
Specifies a background color for the variable in graphical interfaces. This option is ignored in character interfaces.
[ NOT ] CASE-SENSITIVE
CASE-SENSITIVE indicates that the value stored for a character variable is case sensitive, and that all comparisons operations involving the variable are case sensitive. If you do not use this option, Progress comparisons are usually case insensitive. If you define a variable LIKE another field of variable, the new variable inherits case sensitivity. Use [NOT] CASE-SENSITIVE to override this default.
COLUMN-LABEL label
Names the label you want to display above the variable data in a frame that uses column labels. If you want the label to use more than one line (a stacked label), use an exclamation point (!) in the label to indicate where to break the line.
If you want to use the exclamation point (!) as one of the characters in a column label, use two exclamation points (!!).
Progress does not display column labels if you use the SIDE-LABELS or NO-LABELS options with the Frame phrase.
If you define a variable to be LIKE a field, and that field has a column label in the Data Dictionary, the variable inherits that column label.
CONTEXT-HELP-ID expression
An integer value that specifies the identifier of the help topic for this variable in a help file specified at the session, window or dialog box level using the CONTEXT-HELP-FILE attribute.
DCOLOR expression
Specifies the display color for the variable in character interfaces. This option is ignored in graphical interfaces.
DECIMALS n
Specifies the number of decimal places to store for a DECIMAL variable, where n is an integer constant. When you define a variable AS DECIMAL, Progress automatically stores up to 10 decimal places for the value of that variable. Use the DECIMALS option to store a smaller number of decimal places. The DECIMALS option has nothing to do with the display format of the variable, just the storage format.
If you use the LIKE option to name a field whose definition you want to use to define a variable, Progress uses the number of decimals in the field definition to determine how many decimal places to store for the variable.
EXTENT n
Specifies the extent of an array variable, where n is an integer constant. If you are using the AS datatype option and you do not use the EXTENT option (or specify n as 0), the variable is not an array variable. If you are using the LIKE field option and you do not use the EXTENT option, the variable uses the extent defined for the database field you name.
If you want to define a variable that is like an array variable or field, but you do not want the variable to be an array, you can use EXTENT 0 to indicate a non-array field.
Specifies a flat button which is a two-dimensional button until the mouse passes over it, at which time, a 3D border appears.
DROP-TARGET
Indicates whether you want to be able to drop a file onto the object.
The following example shows setting the DROP-TARGET option for a variable.
FGCOLOR expression
Specifies a foreground color for the variable in graphical interfaces. This option is ignored in character interfaces.
FONT expression
Specifies a font for the variable.
FORMAT string
The data format of the variable you define. If you use the AS datatype option and you do not use FORMAT string, the variable uses the default format for its data type. Table 24 lists the default data formats for the data types.
Table 24: Default Display Formats Data Type Default Display Format CHARACTER x(8) COM-HANDLE >>>>>>9 DATE 99/99/99 DECIMAL ->>,>>9.99 HANDLE >>>>>>9 INTEGER ->,>>>,>>9 LOGICAL yes/no MEMPTR1 See the footnote at the bottom of this table. RAW1 See the footnote at the bottom of this table. RECID >>>>>>9 ROWID1 See the footnote at the bottom of this table. WIDGET-HANDLE >>>>>>9
- You cannot display a MEMPTR, RAW, or ROWID value directly. However, you can convert it to a character string representation using the STRING function and display the result. A ROWID value converts to a hexadecimal string, “0xhexdigits,” where hexdigits is any number of characters “0" through “9" and “A” through “F”. A MEMPTR or RAW value converts to decimal integer string.
See the Progress Programming Handbook for more information on data formatting.
If you use the LIKE field option and you do not use the FORMAT string option, the variable uses the format defined for the database field you name. You must enclose the string in quotes.
INITIAL { constant | [ constant [ , constant ] . . . ] }
The initial value of the variable you want to define. If you use the AS datatype option and you do not use the INITIAL constant option, the default is the initial value for the data type of the variable.
When you define an array variable, you can supply initial values for each element in the array.
If you do not supply enough values to fill up the elements of the array, Progress puts the last value you named into the remaining elements of the array. If you supply too many values, Progress returns an error message.
Table 25 lists the default initial values for the eight variable data types.
If you are using the LIKE field option and you do not use the INITIAL constant option, the variable uses the initial value of the field or variable. In the DEFINE SHARED VARIABLE statement, the INITIAL option has no effect. However, the DEFINE NEW SHARED VARIABLE, the DEFINE NEW SHARED TEMP-TABLE, and the DEFINE NEW WORK-TABLE statements work with the INITIAL option.
LABEL string [ , string ] ...
The label you want to use when the variable is displayed. If you use the AS datatype option and you do not use the LABEL string option, the default label is the variable name. If you use the LIKE field option and you do not use the LABEL string option, the variable uses the label of the field or variable you name. You must enclose the string in quotes. For an array variable, you can specify a label for each element of the array.
In MS-Windows, you can designate a character within each label as a navigation mnemonic. Precede the character with an ampersand (&). When the variable is displayed with side labels, the mnemonic is underlined. The user can move focus to the variable by pressing ALT and the underlined letter. Navigation mnemonics operate only when you use side labels. If you specify more than one widget with the same mnemonic, Progress transfers focus to each of these in tab order when you make a selection.
Ending a label with an ampersand might produce unwanted behavior. To include a literal ampersand within a label, specify a double ampersand (&&).
MOUSE-POINTER expression
Specifies the default mouse pointer for the variable.
NO-UNDO
When the value of a variable is changed during a transaction and the transaction is undone, Progress restores the value of the variable to its prior value. If you do not want, or if you do not need, the value of a variable to be undone even when it has been changed during a transaction, use the NO-UNDO option with the DEFINE VARIABLE statement. NO-UNDO variables are often much more efficient, and you should carefully consider when you can do without the default undo service.
Specifying NO-UNDO for a variable is especially useful if you want to indicate an error condition as the value of the variable, perform an UNDO, and later take some action based on that error condition. If one variable is defined LIKE another that is NO-UNDO, the second variable will be NO-UNDO if you explicitly specify NO-UNDO in the definition of that second variable.
PFCOLOR expression
Specifies the prompt-for color for the variable in character interfaces. This option is ignored in graphical interfaces.
view-as-phrase
Specifies the default data representation widget for this variable.
For more information on view-as-phrase, see the VIEW-AS Phrase reference entry.
trigger-phrase
Defines triggers for the data representation widget specified in the view-as-phrase.
For more information on triggers, see the Trigger Phrase reference entry.
EXAMPLESThe
r-dfvar.p
procedure defines two variables, del and nrecs to be shared with procedurer-dfvar2.p
. The del variable passes information tor-dfvar2.p
, while nrecs passes information back tor-dfvar.p
fromr-dfvar2.p
.
The following example is a startup procedure. It defines a new global variable with the initial value TRUE and uses that variable to determine whether to run an initialization procedure,
r-init.p
, that displays sign-on messages. Then the global variable first-time is set to FALSE. If you restart this procedure during the same session (pressed STOP),r-init.p
does not run again.The procedure also defines the variable selection for entering menu choices within this procedure.
The following procedure finds the day of the week of a date the user enters. The procedure defines an array with seven elements and uses the INITIAL option to define the initial value of each element in the array.
The following example defines a variable with a VIEW-AS phrase and a Trigger phrase.
NOTES
- You can use the DEFINE VARIABLE statement anywhere in a procedure. However, all references to the variable must appear after the DEFINE VARIABLE statement that defines it.
- The ROWID and MEMPTR data types are allowed for variables and procedure parameters, but are invalid for table fields. They provide a way to exchange data with applications external to Progress. For more information on using ROWID, see the Progress Programming Handbook and the Progress DataServer Guides, Progress DataServer for ODBC Guide and Progress DataServer for ORACLE Guide. For more information on using the MEMPTR and RAW data types, see the Progress External Program Interfaces manual.
- You should use the CASE-SENSITIVE option only when it is important to distinguish between uppercase and lowercase values entered for a character variable. For example, use CASE-SENSITIVE to define a variable for a part number that contains mixed uppercase and lowercase characters.
- After you use the DEFINE NEW GLOBAL SHARED VARIABLE statement to create a global shared variable, use the DEFINE SHARED VARIABLE statements in other procedures to access that variable.
- You cannot define the same global variable twice in the same Progress session. If you try, and the definitions of the two variables do not match, Progress returns an error. If the definitions of the two variables match, Progress disregards the second variable you tried to define (if you are rerunning a startup procedure).
- Changes made to variables when there is no active transaction are not undone when a block is undone.
- When a procedure names and uses a shared variable:
- Progress searches through the calling chain of procedures looking for the most recent DEFINE NEW SHARED VARIABLE statement that created that shared variable.
- If no DEFINE NEW SHARED VARIABLE statement is found, Progress searches for a DEFINE NEW GLOBAL SHARED VARIABLE statement that created the shared variable.
- If the procedure that names the shared variable is called from a trigger or internal procedure that is part of a persistent procedure context, the persistent context is also checked for the most recent DEFINE NEW SHARED VARIABLE or DEFINE NEW GLOBAL SHARED VARIABLE statement at the point in the calling chain where the trigger or internal procedure is executed.
- If Progress finds one of these statements, it does not search any further for other statements that might have defined the same variable as NEW or NEW GLOBAL.
- Progress checks the definition of a SHARED variable against that of the corresponding NEW SHARED or NEW GLOBAL SHARED variable. The data types and array extents must match. If the FORMAT, LABEL and DECIMALS specifications are not the same, each procedure uses its individual specification. The DEFINE NEW statement determines if a shared variable is NO-UNDO.
- A SHARED variable remains in scope for an instance of a persistent procedure until the instance is deleted. This is true even if the original procedure that defined the variable as NEW SHARED goes out of scope while the procedure instance remains persistent.
If a trigger or internal procedure of a persistent procedure executes an external subprocedure that defines a SHARED variable, Progress includes the persistent procedure in the resolution of the corresponding NEW SHARED variable as though the procedure were on the procedure call stack.
- If an application with several procedures defines a NEW SHARED variable with the same name in each procedure, Progress creates a different instance of the NEW SHARED variable in each procedure. This behavior supports recursive procedures and bill-of-materials applications. For an example, see the “NEW SHARED Variables with the Same Name in Multiple Procedures” section of the “Block Properties” chapter of the Progress Programming Handbook .
- SpeedScript — These options are invalid: BGCOLOR, CONTEXT-HELP-ID, DCOLOR, FONT, FGCOLOR, MOUSE-POINTER, PFCOLOR, and view-as-phrase.
SEE ALSO
DEFINE BUFFER Statement, RUN Statement, Trigger Phrase, VIEW-AS Phrase
Copyright © 2004 Progress Software Corporation www.progress.com Voice: (781) 280-4000 Fax: (781) 280-4095 |