Variables

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

When you set up your 4D 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(*) or Text: Alphanumeric string of up to 2 GB of text
• Integer: Integer from -32768 to 32767
• Long Integer: Integer from -2^31 to (2^31)-1
• Real: A number to ±1.7e±308 (13 significant 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
• Object: A set of "property/value" pairs structured in a JSON type format
• Collection: An ordered list of values of different types
• 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

(*) In Unicode mode, String and Text type variables are identical. In non-Unicode mode (compatibility mode), a String is a fixed alphanumeric string of up to 255 characters.

You can display variables (except Pointer and BLOB) on the screen, enter data into them, and print them in reports. In this way, 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 list boxes, scrollable areas, pop-up menus, and drop-down lists
• 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 can create variables simply by using them; you do not necessarily 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:

4D 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:

However, it is usually recommended for a variable to be explicitly defined as a certain type. For more information about typing variables for a database, see the chapter Compiler.

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:

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:

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, 4D 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:

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.

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 chapter 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, each active object—button, radio button, check box, scrollable area, meter bar, and so on—is identified by an object name and is automatically associated with a variable (or expression). By default, the variable is not defined when the object is created: it will be created dynamically when the form is loaded (see below). You can, if you want, name the variable in the Property List to create it. For example, if you create a button named MyButton, you can associated it with a MyButton variable (you can also use the same name as the object).

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 4D Design Reference Manual as well as the chapter Form Events.

You can leave it up to 4D to create variables associated with your form objects (buttons, enterable variables, check boxes, etc.) dynamically and according to your needs. To do this, simply leave the "Variable Name" field blank in the Property list for the object:

When a variable is not named, when the form is loaded, 4D creates a new variable for the object, with a calculated name that is unique in the space of the process variables of the interpreter (which means that this mechanism can be used even in compiled mode). This temporary variable will be destroyed when the form is closed.
In order for this principle to work in compiled mode, it is imperative that dynamic variables are explicitly typed. There are two ways to do this:

• You can set the type using the "Variable Type" menu of the Property list.
  Note: When the variable is named, the "Variable Type" menu does not actually type the variable but simply allows the options of the Property list to be updated (except for picture variables). In order to type a named variable, it is necessary to use the commands of the Compiler theme.
• You can use a specific initialization code when the form is loaded that uses, for example, the VARIABLE TO VARIABLE command:
  
   If(Form event=On Load)
    C_TEXT($init)
    $Ptr_object:=OBJECT Get pointer(Object named;"comments")
    $init:=""
    VARIABLE TO VARIABLE(Current process;$Ptr_object->;$init)
 End if

Note: If you specify a dynamic variable, select the value None in the "Variable Type" menu, and do not use initialization code, a typing error will be returned by the compiler.

In the 4D code, dynamic variables can be accessed using a pointer obtained with the OBJECT Get pointer command. For example:

There are two advantages with this mechanism:

• On the one hand, it allows the development of "subform" type components that can be used several times in the same host form. Let us take as an example the case of a datepicker subform that is inserted twice in a host form to set a start date and an end date. This subform will use objects for choosing the date of the month and the year. It will be necessary for these objects to work with different variables for the start date and the end date. Letting 4D create their variable with a unique name is a way of resolving this difficulty.
• On the other hand, it can be used to limit memory usage. In fact, form objects only work with process or inter-process variables. However, in compiled mode, an instance of each process variable is created in all the processes, including the server processes. This instance takes up memory, even when the form is not used during the session. Therefore, letting 4D create variables dynamically when loading the forms can economize memory.

Note: When there is no variable name, the object name is shown in quotation marks in the form editor (when the object display a variable name by default).

4D 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.