Selects a key for a table.


[Ok :=] Record.SETCURRENTKEY(Field1, [Field2],...)

Parameters

Record

Type: Record

The record that contains the fields that identify the key that you want to select.

Field1, Field2, …

Type: Field

One or more fields that identify the key that you want to select.

Property Value/Return Value

Type: Boolean

true if the key was selected; otherwise, false.

If you omit this optional return value and if the key cannot be found, then a run-time error occurs. If you include a return value, then you must handle any errors.

Remarks

SETCURRENTKEY is used to select a key for a record and set the sort order that is used for the table in question. This key becomes the current key and is used by the FIND Function (Record), the NEXT Function (Record), and other functions until another key is selected. Until this function is called, the table's primary key is used as the current key.

Use the following guidelines when you use SETCURRENTKEY:

Inactive fields are ignored. Only active keys are scanned.
When searching for a key, C/SIDE selects the first occurrence of the specified field(s). This means the following:
- If you specify only one field as a parameter when you call SETCURRENTKEY, then the key that is actually selected may consist of more than one field.
- If the field that you specify is the first component of several keys, then the key that is selected may not be the key that you expect.
If no keys can be found that include the field(s) that you specify, then a run-time error occurs unless you test the Boolean return value of SETCURRENTKEY in your code.
If you do test the return value, then you must decide what the program should do if the function returns false, because without a run-time error, the program will continue to run even though no key was found.
Use only the necessary key fields in a call of SETCURRENTKEY. If the table order is not important, then use only the fields that are used in the subsequent calls of SETRANGE and SETFILTER. If the definition of the key still includes the fields that are specified in the call of SETCURRENTKEY in the order given, then you can change the definition of the key without having to change any code.

Example 1

This example shows how to use the SETCURRENTKEY function without using a return value. This example requires that you create the following variable.

Name	DataType	Subtype
MyCustomer	Record	Customer

	Copy Code
MyCustomer.SETCURRENTKEY(Name);

This statement selects the Name key for the Customer table. If the key cannot be found, a run-time error occurs.

Example 2

This example shows how to use the SETCURRENTKEY function with a return value.

This example requires that you create the following variable.

Name	DataType	Subtype
MyCustomer	Record	Customer

This example requires that you create the following text constants.

Name	ConstValue
Text000	The key was successfully selected.
Text001	The key could not be found.

	Copy Code
IF MyCustomer.SETCURRENTKEY(Name) THEN MESSAGE(Text000) ELSE MESSAGE(Text001);

By including a return value, you can avoid a run-time error if a key cannot be found.

Parameters

Property Value/Return Value

Remarks

Example 1

Example 2

See Also

Reference