If you are new to 4th Dimension, we suggest that you review the contents of the following web pages and the learning resources listed on those pages:
An Array is a variable. Unlike all other variables that hold only a single value, an array is a variable that can hold a series of values, essentially, a list of values. Unlike a series of values stored in individual variables, and referenced individually by each variable name, an array provides the logical convenience of being able to reference all its values by using the single array name. For example, it would make sense to have a list of states addressable as one object, rather than as separate variables for each state.
As a variable, an array is an area in memory (RAM) reserved under a name, and referred to by name, into which values can be assigned. These values can be changed and retrieved by referencing the array by name. Since the values in an array are stored in RAM, they are volatile; they do not persist once you quit the application.
Arrays can be used with the 4th Dimension language, with no graphic representation on your forms, or arrays can be displayed on forms as Scrollable Areas, Pop-up List/Drop-down Lists, or Combo Boxes; that is as active objects, with which users can interact.
In all cases, except when you create a Combo Box, arrays must be created by using commands in the 4th Dimension Language. When you create a Combo Box object, an associated array is automatically created. This is similar to when a display variable object is used on a form, and an associated variable (with the same name as the display variable object) is automatically created to monitor the user's interaction with the active object on the form (please refer to the web page on variables).
There are equivalent array data types for each of the data types that 4th Dimension stores in fields, plus support for the pointer data type: Integer, Long Integer, Real, String, Date, Boolean, Picture, and Pointer.
Arrays can hold up to 32000 elements.
There are array declaration commands in the 4th Dimension language that create an empty array of a specified number of elements. A literal value, or a value from a field or variable, is then assigned to an element of the array. The syntax used is:
arrayname{element number}:= value
NOTE: Array elements are numbered by their position in the array, starting at one and going up.
Additionally, every array has zero element number (more on this later).
In the three examples below, the first element of an array named asStates is assigned the literal state abbreviation "NY", then it is assigned a copy of the value in the [Contacts]State field, and then it is assigned a copy of the value in a variable named sState:
asStates{1}:="NY"
asStates{1}:=[Contacts]State
asStates{1}:=sState
This is a somewhat impractical example since it overwrites the contents of the first element successively. Note the optional naming conventions used here: "a" to indicate an array, and "s" to indicate a variable of type "string".
There are also commands in the 4th Dimension language that automatically fill arrays with values in one step. SELECTION TO ARRAY will populate arrays with field values from the current selection. You many pass any number of field/array pairs to the command. DISTINCT VALUES could be used to fill the asStates array with one instance of each state name from the current selection of records in the Contacts table: DISTINCT VALUES([Contacts]State;asStates)
To retrieve values from an element of an array the syntax explained above is reversed: the field or variable receiving the value from the array element is placed on the left of the assignment operator, and the array element number is placed on the right:
Field or variable:= arrayname{element number}
In the two examples below [Contacts]State field is assigned a copy of the value contained in the third element of the asStates array, and the sState variable is assigned a copy of the value contained in the third element of the asStates array:
[Contacts]State:=asStates{3}
sState:=asStates{3}
There are also commands in the 4th Dimension language that copy values from arrays. For example, the values in an array may be written into records in your database by using the command ARRAY TO SELECTION.
Now, you may in fact use arrays in your code, and never display them. On the other hand, 4th Dimension being an application designed to be used in a graphical user environment, arrays, like other variables can be displayed. As it turns out, there are several familiar user interface objects that are ideal for displaying the contents of an array.
To display the contents of array on a form, you simply give an active object capable of displaying an array, and an array, the same name. The contents of the array will then automatically be displayed in that object. The objects that can display the contents of an array are: Scrollable Areas, Pop-up Lists/Drop-down Lists, and Combo Boxes.
Arrays are displayed on forms by placing one of the above active objects on a form. Active objects are known as active objects because they can actively intercept either mouse clicks or key strokes (or both). Scrollable Areas, Pop-up List/Drop-down Lists, and Combo Boxes can all intercept mouse clicks. A Combo Box can also intercept keystrokes (more on this later).
All active objects store a value in a variable that has the same name as the active object. This value is used to monitor a user's interaction with that object. For example, when you place an enterable display variable on a form, you are creating both the object on the form, and a variable in memory with the same name as the displayed object. The variable will hold the value that the user types in the object on the form. Or, if you place a button on a form, you are creating both the button object on the form and a variable in memory with the same name as the button. That variable will have a value of zero until the user clicks on the button, at which time the variable will be set to 1.
The exact same thing is true of arrays that are displayed using active objects. When you place a Scrollable Area, Pop-up List/Drop-down List, or Combo Box on a form, you are creating both the object on the form and a variable in memory with the same name as the displayed object. This variable, associated by name with the object, will have a value of zero until the user clicks on the Scrollable Area, Pop-up List/Drop-down List, or Combo Box, at which time the variable will be set to a numeric value equal to the position number of the element that the user has clicked on in the displayed object. This value indicates that the user has interacted with the object, and indicates which element they selected, giving you a way of detecting in your code, which element of a displayed array the user has clicked on. Keep in mind that this single numeric value associated with the array name, is an entirely independent value that is separate and different from the multiple values stored in the array itself: You have the values in the array, and for arrays that are displayed, you have a separate single value associated with the array name, which is used to monitor which element of the displayed array that the user has clicked on.
Ok, so you can detect which element of a displayed array the user has clicked on. But, what does this enable you to do?
Lets review some facts we now know about arrays:
Now, let's suppose that we want to take the value that a user selects in the displayed array, and use it in some way. For example, suppose we want to take the user selected value and copy it to a field. Well, remember, that the value in an array element is accessed by the syntax arrayName{elementNumber}, and that the array name itself has a numeric value (either zero, or position number of the element that the user clicks on). Given these facts, the following syntax will let us easily access the value of the user selected element of the array: arrayName{arrayName}. In this syntax, the array name used within the curly braces is a numeric value. What value does it have? It is a numeric value equal to the position number of the element the user has selected in the displayed array. Now we can easily assign the value of the user selected element of the asStates array, into a field or variable:
[Contacts]State:=asStates{asStates}
or
sState:=asStates{asStates}
And how would you use this? Well, you could have a Pop-up List/Drop-down List on a form from which the user selects a state, and that state is copied to the Contacts table State field. Or, you could use the user selected value in some other manner in your code, for example in a Case statement:
Case of
: (asStates{asStates}="AK")
ALERT ("Is it cold?")
: (asStates{asStates}="AZ")
ALERT ("Is it hot?")
End case
While the proceeding code example is a poor attempt at humor, it does illustrate accessing the user selected value of an array and using it within your code.
Now, one final fact to know about arrays. When you create an array, the elements of the array that you create are numbered in ascending order starting at 1, and when you display an array, these elements are displayed. However, every array also has a zero element. This element does not display except in the case of Combo Boxes.
When a user interacts with a Combo Box the value they select from the Drop-down menu of the Combo Box, or the value they type in the enterable area of the Combo Box is stored in the zero element of the array. So, to copy the user entered value from a Combo Box to field, the code syntax would be: Field:=arrayName{0}.
For example to copy the user selected or typed value from an asStates Combo Box to the Contacts State field the code would be: [Contacts]State:=asStates{0}.
Or, to copy a value from a field to be used as a default value for a Combo Box, the code syntax would be: arrayName{0}:=Field.
To copy the value from the State field to be the default for the asStates Combo Box the code would be: asStates{0}:=[Contacts]State.
NOTE: Do not confuse the zero element of an array with the fact that the array name has a numeric value of zero until a user clicks on an element of the array; as you can see, the zero element of the array, and the numeric value associated with the array name are entirely different concepts.
Like all variables in 4th Dimension, arrays have a quality known as Scope:
How do you decide whether to declare a local, process or inter-process array?
When coding in 4D it is desirable to use local arrays because they are automatically cleared from memory, freeing that memory for other uses, when the method in which they were declared finishes execution. So, use local arrays when possible; that is, when the array does not need to be read beyond the method in which it is declared.
Process arrays should be used when an array's value needs to be read in methods other than the method in which the array was declared, but within the same process. Process arrays persist; they are not automatically cleared from memory (until you quit 4D). Therefore they should be cleared from memory by being re-declared with zero elements when the values that they contain are no longer needed.
Inter-process arrays should be used when an array needs to be read in methods that are running in processes other than the process of the method in which the array was declared. Inter-process arrays persist; they are not automatically cleared from memory (until you quit 4D). Therefore they should be cleared from memory by being re-declared with zero elements when the values that they contain are no longer needed.
Scrollable Areas, Pop-up List/Drop-down Lists, and Combo Boxes MUST NOT be scoped as local. In other words, the first character of the name of these active objects MUST NOT be a "$", or their values will not be able to be read by or set by any code. In fact, their values would be local to the object on the from, and would be unable to be accessed beyond that object, not even by that object's Object Method. Therefore, arrays that are going to be displayed must be scoped as either process or inter-process variables.
Implementing A Combo Box
This video tech tip explains the code, methods and events used for building a combo box.
Tech Tip: Insuring a continuous highlight across grouped Scrollable Areas
Tech Tip: Where to put splitters when used with grouped Scrollable Areas
4th Dimension Design Reference (PDF)
Pages 394 – 395: These pages cover Pop-up Lists/Drop-down Lists, Scrollable Areas
Commands and Topics for Arrays
This web page contains links to pages providing information on arrays and the commands used to create and work with arrays.
Arrays
This web page contains a brief explanation of arrays.
Arrays and the 4D Language
This web page covers the following topics:
Local, process, and interprocess arrays; passing arrays as parameters, assigning the contents of one array to another array.
Creating Arrays
This web page covers the commands used to create arrays, and provides links to pages containing the detail of using each command.
Arrays and Form Objects
This web page covers displaying arrays as form objects.
Grouped Scrollable Areas
This web page covers displaying multiple arrays as a single grouped scrollable area.
Using the element zero of an array
This web page covers using the zero element of an array.
Arrays and Memory
This web page covers how arrays effect memory usage.
4D v 6.8 Getting Started
Pages 300-307
Topics covered include: Element numbers; Scrollable Areas and Drop-down Lists, Finding a value in an array, Typing and Dimensioning arrays; Modifying arrays.
International | Company | Contact 4D | Site Map | Privacy Policy | © 4D, Inc. 1995-2008 | Change font size: [A] [A] [A] | 
| 4D RSS Feeds