This section describes the concepts of the current selection, current record, and named selections.

The current selection of records is the set of data with which you are going to work or on which you are going to perform some operation. For example, when you perform a sort operation, you sort the records in the current selection. There is a current selection of records for every table in the database for each connection (process) you opened.

The current record is the record in the current selection which currently has the focus. There is at most one current record for every current selection. By default, once a new selection of records has been established, the first record of the selection, if any, is made the current record. Using the GotoRecord method, you can make any record in the current selection the current record.

When you work with 4D Open for Java, you work with either the current selection or the current record.

You can perform "one record" operations, such as updating field values, on the current record.

You can perform "multiple record" operations, such as sorting or getting a list of values, on the current selection.

For each table, there can be only one current selection at a time. When you change the current selection, the original current selection is lost. Named selections, discussed later in this chapter, provide a way of temporarily preserving a selection in memory.

The current selection can contain none, one, some, or all the records from a table. Every table has a current selection of records. This selection can be different for each connection (process).

The current selection is always the set of records most recently selected. You can select records in a number of ways. For instance, suppose that you search for the records of all the engineers in a company. When the search begins, the current selection may contain the records of all the employees in the company — salespeople, production personnel, engineers, and so on. When the search is completed, the current selection contains only the engineers' records.

Once you have made a selection, you can perform multiple operations on the selection without reexecuting the code that created the selection. This provides a significant advantage over SQL-based systems in which you must reselect the appropriate rows before each operation.

For instance, consider the following situation:

you want to select all the Customers living in New York sorted by their name,

you want to print the sorted list,

you want to print the corresponding labels, and

you want to update a field indicating that a mailing has been performed.

With a SQL-based system, this would be performed by the means of two SELECT statements and one UPDATE statement. This means that you ask the server to perform the same search three times and download the rows twice. With 4D Server, you establish the selection once, sort it, then print the selection twice (and you can do that by downloading the values once if it fits into the client's memory), and update the selected records.

You can select all the records in a table by using the AllRecords method. Once you have created a selection of records, you can obtain the number of records in the current selection by using the RecordsInSelection method.

You change the selection of records in a table whenever you perform a search that selects records by using Search, or when you limit the selection of records to a certain number of records in the table by using ReduceSelection or DeleteSelection.

GotoRecord allows you to select one record out of all the records in the table. In this way, the current selection is reduced to the current record.

Once you have a selection of records, you may want to select the related records in another table by using RelateOne or RelateMany.

For example, suppose that you have a database containing a [People] table and a [Companies] table. In this database, the CompanyID field in the [People] table is related to the CompanyIDNum field in the [Companies] table.

When you select an employee record in the [People] table, you may want to select the company for which the employee works from the [Companies] table. And, when you select a company record from the [Companies] table, you may want to select the records of the employees who work for the company.

When you use RelateOne or RelateMany, 4D Server looks at the current selection of records in one table and selects the related records in another table.

If there is more than one record in the current selection of the first table, the records selected in the other table will contain the records related to all these records. If you want to select the records related to just one record, be sure to reduce the current selection to just that record. For example, to find the company for just one employee, reduce the selection of records in the [People] table to only that employee's record.

Note: If you do not want to reduce the current selection to a single record, you can use a search to select the related records. Since a relation between records is based on matching values in the related fields, you can search the related table for records that contain the desired value.

To delete the current selection of records, you use the DeleteSelection method.

The current record is the record in the current selection which currently has the focus. There is at most one current record per current selection.

By default, once a new selection of records is established, the first record of the selection becomes the current record as long as the current selection is not empty. You can change the current record to another record in the selection by using the GotoSelectedRecord method.

To reduce the current selection to just one record and make it the current record, call the GotoRecord method.

You can retrieve data from specified fields in the current record by using the LoadFields method. The data from the fields is returned in an opFieldArray.

If you have a current record in the Many table, you can retrieve data from the fields in the related One table record. For more information on table relations, refer to "The Many Table and the One Table" in the section Understanding the Database Structure.

To retrieve the data from the related record, you use LoadFields and pass mTableNumber equal to the target table number. The data from the fields is returned in an opFieldArray.

Given the previous example of the [People] table and the [Companies] table, you could specify a current record for the [People] table. Based on the current record in the People table, you could then select from the Companies table the record of the company for which the person works.

	First name	Last name	Title	Company name
	Biff	Davis	Salesperson	Howard Battery Co.

To delete the current record, you use the DeleteRecord method.

A named selection is a selection of records that has been given a name and saved in memory on the server. It consists of an ordered list of records for a table. This ordered list maintains both the order of the selection and the current record.

Named selections can be extremely useful when you know that you will want to reuse a selection of records. In this case, you can make the current selection of records a named selection. You can then perform other operations that change the current selection, knowing that you can retrieve the former current selection when needed.

You can have multiple named selections for each table in a connection.

Since named selections reside in memory, you should have enough memory for saving them as well as the tables current selections.

A named selection can be local to a particular connection (process) or can be shared among all the processes of a user. In the second case, the named selection is considered to be interprocess in its scope. You can specify that a named selection should be interprocess in its scope by giving it a name that starts with the diamond sign <>. For example, "<>GoodCustomers".

In any case, a named selection is local to a user. An interprocess named selection is accessible from any process started by the user who created the named selection. Other users cannot access the named selection.

CopyNamedSelection creates a named selection whose contents are identical to the current selection. The current selection does not change; you just make a copy of it .

Use ClearNamedSelection to clear the named selection and to free the memory it occupies on the server.

CutNamedSelection transforms the current selection into a named selection. Unlike CopyNamedSelection, CutNamedSelection does not duplicate the current selection. Therefore, after the call, the current selection is empty.

Important: 4D Server remembers how a named selection was created (whether it was copied or moved), and will act differently when reusing the named selection. A named selection created with CutNamedSelection can be used only once because it is transformed into the current selection when you call UseNamedSelection.

To use a named selection that you created with CopyNamedSelection or CutNamedSelection, call UseNamedSelection.

Using a Copied Named Selection

If you used CopyNamedSelection to create the named selection, it is copied to the current selection of a table. The named selection remains in the server memory until it is cleared by ClearNamedSelection.

Using a Moved Named Selection

If you used CutNamedSelection to create the named selection, it is transformed into the current selection when it is used. Because the named selection is transformed into the current selection rather than copied, it no longer exists after the call.

To clear a named selection from memory, call ClearNamedSelection. This method should only be called for named selections created with CopyNamedSelection.

When you create a named selection, you must decide whether you want to copy or move the selection. The following sections illustrate why you might want to use either method.

Copying the Selection With CopyNamedSelection: Copying the selection is ideal when you need to reuse a named selection several times.

Suppose that you are displaying a set of records in a list and you want to implement two radio buttons that allow the user to display the records in ascending or descending order.

One solution might be to sort the selection each time the user clicks on a radio button. However, if the sort is time consuming, you can optimize the operation by creating a named selection when the user clicks on the button the first time. The following time, the user will use the named selection instead of sorting.

Once you are done, do not forget to clear the named selections.

Moving the Selection With _4D_MoveSelection: Moving the selection is a good choice when you know that you will not need to reuse the selection more than once. In this case, moving the selection will yield faster results than copying the selection.

Suppose that in your database the combined value of certain fields must be unique. You want to check that the combined value is unique before allowing the user to validate a record. To do this, you could use 4D Client to create an invisible unique indexed field in which you concatenate the data to be unique. Another way to do it is to move the current selection into a named selection, perform a search that tests possible multi-field values, and then, after the search, restore the current selection by using the moved named selection.

Since CutNamedSelection does not duplicate the selection, this operation is extremely fast regardless of the size of the selection.