)DECLARE

Defines how variable names are used.

Type

Placeholder

Format


)DECLARE
[varname ALIAS(alias) [SCOPE(SHARED | LOCAL | SESSION | SYSTEM)]]
  .
  .
  .
[varname SCOPE(SHARED | LOCAL | SESSION | SYSTEM
  .
  .
  .

varname: Specifies a 1- to 8-character variable name.

alias: Specifies a 1- to 8-character alias name. In the BODY section of the current dialog only, alias may be used as an alternate spelling for the variable name. This permits short input fields for long variable names. Do not use alias in any section other than the BODY section.

scope

Specifies from which dialogs a variables value is accessible and when its value will be automatically erased. The four scopes are:

LOCAL scope variables are only known to the dialog for which they are defined. The DIALOG statement ignores all LOCAL values in the invoking dialog until the invoked dialog issues a RETURN. The SELECT statement erases all local values in the invoking dialog.
SHARED variables need not be declared, and are accessible by any dialog that has not declared them to have some other scope and is running as part of the same process. SHARED variables are automatically erased when the related process terminates. A process is:
- A screen window. One of these is automatically created for each physical terminal session. The last window for a session may be deleted only by terminating the session.
  New windows are created with the PSMSPLIT dialog function and terminated at physical session termination or with the PSMDELET function.
- Timeout handling. When a physical session timeout occurs, a separate timeout dialog begins (for example, one that locks the terminal until a password is given). Timeout handling terminates when all the timeout dialogs exit or return, or when the physical session terminates.
- Message delivery. A message delivery dialog runs as a separate process and is scheduled by an operator request or by another user. They are otherwise just like timeout dialogs.
SESSION scope variables are erased when the current physical terminal session ends. They are accessible from any dialog that declares them properly and is running on that physical terminal session.
SYSTEM scope variables are never erased except when explicitly set to the null string. They are accessible to any dialog running in the CL/SuperSession address space that declares them properly.

Usage Notes®

A DECLARE section consists of:
- )DECLARE, starting in column 1, alone on a line.
- Zero or more lines, each containing a variable name (varname), followed by either ALIAS(alias), SCOPE(scope), or both.
Two variables with the same name but declared with different scopes are not the same variable.
SESSION or SYSTEM variables are accessible to asynchronously executing dialogs, and their values may be altered at almost any time. The Dialog Manager serializes access to the variables only during each statement that references them. For example, if you wish to use a system variable as a global index, this code will not work properly:
```
   )declare
    MyName scope(local) 
    GIndex scope(system)
   )prolog
    set GIndex (&GIndex + 1) 
    set MyName TERM&GIndex
```
No other dialog will be able to access the GIndex variable while the first SET statement is executing. However, as soon as that SET completes, another dialog could update the GIndex value, and the second SET statement would not use the value that you expect. This code will work:
```
   )declare
    MyName scope(local)
    TIndex scope(local) 
    GIndex scope(system)
   )prolog
    set TIndex (set GIndex (&GIndex + 1)) 
    set MyName TERM&TIndex
```
Access to the GIndex value is serialized until the innermost SET statement is complete. Then, because that SETs result is being assigned directly to the TIndex variable, we are assured that the value we use is the value we expect.

Note: Each SET is considered a separate statement, even though they may appear on the same line.
Use )DECLARE and ALIAS to provide variable names that are:
- meaningful
- short
- equal in length (to set up the columns of a table, for example)
Code an ALIAS statement for each alias you need.
A short alias can reduce the amount of space a variable uses in a panel definition.
You can include a line comment in this section by preceding it with an asterisk (*). The asterisk causes the remainder of the line to be ignored. DO NOT use the multiple line comment format (/* comment */).

Example

In the following example, )DECLARE sets an alias name of Y for the variable YesNo. Yis known only to the )BODY section, and is used so that the data entry field is only 1 character long. YesNois known to the other sections in the dialog and is used because it is a more descriptive name.


   )declare
    YesNo alias(Y) scope(local)
   )prolog
    set YesNo N
   )body
   #Do you want to continue?_Y#(Y or N)
   )epilog
         if &YesNo = N then return 
    else if &YesNo = Y then ... 
    else ...