Variables

version 6.0

Data in 4th Dimension is stored in two fundamentally different ways. Fields store data permanently on disk; variables store data temporarily in memory.

When you set up your 4th Dimension database, you specify the names and types of fields that you want to use. Variables are much the same—you also give them names and different types.

The following variable types correspond to each of the data types:

• String: Fixed alphanumeric string of up to 255 characters

• Text: Alphanumeric string of up to 32,000 characters

• Integer: Integer from -32768 to 32767

• Long Integer: Integer from -2^31 to (2^31)-1

• Real: A number to ±1.7e±308 (15 digits)

• Date: 1/1/100 to 12/31/32767

• Time: 00:00:00 to 596000:00:00 (seconds from midnight)

• Boolean: True or False

• Picture: Any Windows or Macintosh picture

• BLOB (Binary Large OBject): Series of bytes up to 2 GB in size

• Pointer: A pointer to a table, field, variable, array, or array element

You can display variables (except Pointer and BLOB) on the screen, enter data into them, and print them in reports. In these ways, enterable and non-enterable area variables act just like fields, and the same built-in controls are available when you create them:

• Display formats

• Data validation, such entry filters and default values

• Character filters

• Choice lists (hierarchical lists)

• Enterable or non-enterable values

Variables can also do the following:

• Control buttons (buttons, check boxes, radio buttons, 3D buttons, and so on)

• Control sliders (meters, rulers, and dials)

• Control scrollable areas, pop-up menus, and drop-down list boxes

• Control hierarchical lists and hierarchical pop-up menus

• Control button grids, tab controls, picture buttons, and so on

• Display results of calculations that do not need to be saved.

You create variables simply by using them; you do not need to formally define them as you do with fields. For example, if you want a variable that will hold the current date plus 30 days, you write:

   MyDate:=Current date+30

4th Dimension creates MyDate and holds the date you need. The line of code reads "MyDate gets the current date plus 30 days." You could now use MyDate wherever you need it in your database. For example, you might need to store the date variable in a field of same type:

   [MyTable]MyField:=MyDate

Sometimes you may want a variable to be explicitly defined as a certain type. For more information about typing variables for a database that you intend to compile, see the section Compiler Commands.

Data can be put into and copied out of variables. Putting data into a variable is called assigning the data to the variable and is done with the assignment operator (:=). The assignment operator is also used to assign data to fields.

The assignment operator is the primary way to create a variable and to put data into it. You write the name of the variable that you want to create on the left side of the assignment operator. For example:

   MyNumber:=3

creates the variable MyNumber and puts the number 3 into it. If MyNumber already exists, then the number 3 is just put into it.

Of course, variables would not be very useful if you could not get data out of them. Once again, you use the assignment operator. If you need to put the value of MyNumber in a field called [Products]Size, you would write MyNumber on the right side of the assignment operator:

   [Products]Size:=MyNumber

In this case, [Products]Size would be equal to 3. This example is rather simple, but it illustrates the fundamental way that data is transferred from one place to another by using the language.

Important: Be careful not to confuse the assignment operator (:=) with the comparison operator, equal (=). Assignment and comparison are very different operations. For more information about the comparison operators, see the section Operators.

You can create three types of variables: local variables, process variables, and interprocess variables. The difference between the three types of variables is their scope, or the objects to which they are available.

A local variable is, as its name implies, local to a method—accessible only within the method in which it was created and not accessible outside of that method. Being local to a method is formally referred to as being "local in scope." Local variables are used to restrict a variable so that it works only within the method.

You may want to use a local variable to:

• Avoid conflicts with the names of other variables

• Use data temporarily

• Reduce the number of process variables

The name of a local variable always starts with a dollar sign ($) and can contain up to 31 additional characters. If you enter a longer name, 4th Dimension truncates it to the appropriate length.

When you are working in a database with many methods and variables, you often find that you need to use a variable only within the method on which you are working. You can create and use a local variable in the method without worrying about whether you have used the same variable name somewhere else.

Frequently, in a database, small pieces of information are needed from the user. The Request command can obtain this information. It displays a dialog box with a message prompting the user for a response. When the user enters the response, the command returns the information the user entered. You usually do not need to keep this information in your methods for very long. This is a typical way to use a local variable. Here is an example:

   $vsID:=Request("Please enter your ID:")
   If (OK=1)
      QUERY ([People];[People]ID =$vsID)
   End if

This method simply asks the user to enter an ID. It puts the response into a local variable, $vsID, and then searches for the ID that the user entered. When this method finishes, the $vsID local variable is erased from memory. This is fine, because the variable is needed only once and only in this method.

A process variable is available only within a process. It is accessible to the process method and any other method called from within the process.

A process variable does not have a prefix before its name. A process variable name can contain up to 31 characters.

In interpreted mode, variables are maintained dynamically, they are created and erased from memory "on the fly." In compiled mode, all processes you create (user processes) share the same definition of process variables, but each process has a different instance for each variable. For example, the variable myVar is one variable in the process P_1 and another one in the process P_2.

Starting with version 6, a process can "peek and poke" process variables from another process using the commands GET PROCESS VARIABLE and SET PROCESS VARIABLE. It is good programming practice to restrict the use of these commands to the situation for which they were added to 4D:

• Interprocess communication at specific places or your code

• Handling of interprocess drag and drop

• In Client/Server, communication between processes on client machines and the stored procedures running on the server machines

For more information, see the section Processes and the description of these commands.

Interprocess variables are available throughout the database and are shared by all processes. They are primarily used to share information between processes.

The name of an interprocess variable always begins with the symbols (<>) — a "less than" sign followed by a "greater than" sign— followed by 31 characters.

Note: This syntax can be used on both Windows and Macintosh. In addition, on Macintosh only, you can use the diamond (Option-Shift-V on US keyboard).

In Client/Server, each machine (Client machines and Server machine) share the same definition of interprocess variables, but each machine has a different instance for each variable.

In the Form editor, naming an active object—button, radio button, check box, scrollable area, meter bar, and so on—automatically creates a variable with the same name. For example, if you create a button named MyButton, a variable named MyButton is also created. Note that this variable name is not the label for the button, but is the name of the button.

The form object variables allow you to control and monitor the objects. For example, when a button is clicked, its variable is set to 1; at all other times, it is 0. The variable associated with a meter or dial lets you read and change the current setting. For example, if you drag a meter to a new setting, the value of the variable changes to reflect the new setting. Similarly, if a method changes the value of the variable, the meter is redrawn to show the new value.

For more information about variables and forms, see the 4th Dimension Design Reference Manual as well as the section Form event.

4th Dimension maintains a number of variables called system variables. These variables let you monitor many operations. System variables are all process variables, accessible only from within a process.

The most important system variable is the OK system variable. As its name implies, it tells you if everything is OK in the particular process. Was the record saved? Has the importing operation been completed? Did the user click the OK button? The OK system variable is set to 1 when a task is completed successfully, and to 0 when it is not.

For more information about system variables, see the section System Variables.

Arrays, Constants, Control Flow, Data Types, Identifiers, Methods, Operators, Pointers.