Progress
Language Reference


DEFINE VARIABLE Statement

Interfaces
OS
SpeedScript
All
All
Yes

Defines a variable for use within a procedure or within several procedures.

SYNTAX

DEFINE [ [ NEW [ GLOBAL ] ] SHARED ] VARIABLE variable
  { AS datatype | LIKE field } 
  [ NO-UNDO ]
  [ BGCOLOR expression ]
  [ COLUMN-LABEL label ]
  [ CONTEXT-HELP-ID expression ]
  [ DCOLOR expression ]
  [ DECIMALS n ]
  [ DROP-TARGET ]
  [ EXTENT n ] 
  [ FONT expression ]
  [ FGCOLOR expression ]
  [ FORMAT string ]
  [ INITIAL
      { constant | { [ constant [ , constant ] ... ] } }
  ]
  [ LABEL string [ , string ] ... ]
  [ MOUSE-POINTER expression ]
  [ [ NOT ] CASE-SENSITIVE ]
  [ PFCOLOR expression ]
  { [ view-as-phrase ] }
  { [ trigger-phrase ] } 

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.

r-collbl.p
DEFINE VARIABLE credit-percent AS INTEGER
    COLUMN-LABEL "Enter   !percentage!increase ".

FOR EACH customer:
    DISPLtAY name credit-limit.
    SET credit-percent.
    credit-limit = (credit-limit * (credit-percent / 100))
                   + credit-limit.
    DISPLAY credit-limit @ new-credit LIKE credit-limit
        LABEL "New max cred".
END. 

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.

DEFINE VARIABLE fill-in-1 AS CHARACTER DROP-TARGET. 

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
  1. 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.

DEFINE VARIABLE array-var 
  AS CHARACTER EXTENT 3 INITIAL ["Add","Delete","Update"]. 

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.

Table 25: Default Variable Initial Values 
Data Type
Default Initial Value
CHARACTER
"" (an empty string)
COM-HANDLE
? (unknown value)
DATE
? (unknown value-displays as blanks for dates)
DECIMAL
0
HANDLE
? (unknown value)
INTEGER
0
LOGICAL
no
MEMPTR
A zero-length sequence of bytes
RAW
A zero-length sequence of bytes
RECID
? (unknown value)
ROWID
A zero-length sequence of bytes
WIDGET-HANDLE
? (unknown value)

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.

SYNTAX
VIEW-AS 
  {     combo-box-phrase
     |  editor-phrase
     |  FILL-IN
          [ NATIVE ]
          [ size-phrase ]
          [ TOOLTIP tooltip ]
     |  radio-set-phrase
     |  selection-list-phrase
     |  slider-phrase
     |  TEXT
          [ size-phrase ]
          [ TOOLTIP tooltip ]
     |  TOGGLE-BOX
          [ size-phrase ]
          [ TOOLTIP tooltip ]
  } 

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.

SYNTAX
TRIGGERS:
  { ON event-list [ ANYWHERE ]
      {     trigger-block
         |  PERSISTENT RUN proc-name
              [ IN handle ]
              [ ( input-parameters ) ]
      }
  } ... 
END [ TRIGGERS ] 

For more information on triggers, see the Trigger Phrase reference entry.

EXAMPLES

The r-dfvar.p procedure defines two variables, del and nrecs to be shared with procedure r-dfvar2.p. The del variable passes information to r-dfvar2.p, while nrecs passes information back to r-dfvar.p from r-dfvar2.p.

r-dfvar.p
DEFINE NEW SHARED VARIABLE del AS LOGICAL.
DEFINE NEW SHARED VARIABLE nrecs AS INTEGER.
del = no.
MESSAGE "Do you want to delete the orders
  being printed (y/n)?"
UPDATE del.
RUN r-dfvar2.p.
IF del
THEN MESSAGE nrecs
  "Orders have been shipped and were deleted".
ELSE MESSAGE nrecs "Orders have been shipped". 

r-dfvar2.p
DEFINE SHARED VARIABLE del AS LOGICAL.
DEFINE SHARED VARIABLE nrecs AS INTEGER.

OUTPUT TO PRINTER.
nrecs = 0.
FOR EACH order WHERE ship-date <> ?:
     nrecs = nrecs + 1.
     FOR EACH order-line OF order:
         DISPLAY order-num line-num qty price.
        IF del THEN DELETE order-line.
     END.
     IF del THEN DELETE order.
END.
OUTPUT CLOSE. 

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.

r-dfvar3.p
DEFINE NEW GLOBAL SHARED VARIABLE first-time
  AS LOGICAL INITIAL TRUE.
DEFINE VARIABLE selection AS INTEGER FORMAT "9"
  LABEL "Selection".

IF first-time THEN DO:
  RUN r-init.p.
  first-time = false.
END.
FORM
    "    MAIN MENU          " SKIP(1)
    "1 - Accounts Payable   " SKIP
    "2 - Accounts Receivable" WITH CENTERED ROW 5 FRAME menu.
REPEAT:
    VIEW FRAME menu.
    UPDATE selection AUTO-RETURN WITH FRAME sel
      CENTERED ROW 12 SIDE-LABELS.
    IF selection = 1 THEN DO:
      HIDE FRAME menu.
      HIDE FRAME sel.
      RUN apmenu.p.
    END.
    ELSE IF selection = 2 THEN DO:
        HIDE FRAME menu.
        HIDE FRAME sel.
        RUN armenu.p.
      END.
      ELSE DO:
        MESSAGE "Invalid selection. Try again".
        UNDO, RETRY.
      END.
END. 

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.

r-dfvar4.p
DEFINE VARIABLE dow AS CHARACTER FORMAT "x(9)" EXTENT 7
  INITIAL ["Sunday", "Monday", "Tuesday", "Wednesday",
  "Thursday", "Friday", "Saturday"].

DEFINE VARIABLE dob AS DATE INITIAL TODAY.

REPEAT WITH SIDE-LABELS 1 DOWN CENTERED ROW 10 TITLE "Date of Birth":
  DISPLAY SKIP(1).
  UPDATE dob LABEL "Enter date of birth".
  DISPLAY dow[WEEKDAY(dob)] LABEL "It was a".
END. 

The following example defines a variable with a VIEW-AS phrase and a Trigger phrase.

r-defse1.p
DEFINE VARIABLE i AS INTEGER NO-UNDO.

DEFINE VARIABLE clubs AS CHARACTER
  VIEW-AS SELECTION-LIST SIZE 20 BY 5 MULTIPLE
    SCROLLBAR-VERTICAL NO-DRAG
    LIST-ITEMS "One Iron", "Two Iron", "Three Iron", "Four Iron",
               "Five Iron", "Six Iron", "Seven Iron", "Eight Iron",
               "Nine Iron", "Pitching Wedge"
  LABEL "Golf Clubs Available"
  TRIGGERS:
    ON GO 
      DO:
        IF SELF:SCREEN-VALUE <> "" THEN
        DO i = 1 TO NUM-ENTRIES(SELF:SCREEN-VALUE) :
           DISPLAY ENTRY(i, SELF:SCREEN-VALUE) FORMAT "X(16)" 
            WITH FRAME clubs-sel CENTERED
              NUM-ENTRIES(SELF:SCREEN-VALUE) + 1 DOWN
              TITLE "Clubs Selected" USE-TEXT.
          DOWN 1 WITH FRAME clubs-sel. 
        END.
      END.
  END TRIGGERS.
    
ENABLE clubs WITH FRAME get-info TITLE "Select the Desired Club(s)".
  
WAIT-FOR WINDOW-CLOSE OF CURRENT-WINDOW. 

NOTES

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