9.187 SELECT_IN_SPACE

Note: Built-In Function Rules     Usage Options

Selects the first row of cells that matches the key values supplied and returns the cell values into the specified fields.

Arguments

No

Type A/N

Req/ Opt

Description

Min Len

Max Len

Min Dec

Max Dec

1

A

R

Space Name

1

256

 

 

2-20

X

O

Fields that specify the key values to be used to locate the first cell row required. 

1

Unlimited

0

Unlimited

 

Return Values

No

Type

Req/ Opt

Description

Min Len

Max Len

Min Dec

Max Dec

1

A

O

Standard Return Code

"OK" = A cell row was found and the cell values have been returned.

"NR" = No cell row could be found with a key matching the key values supplied.

"ER" = Select attempt failed. Messages issued will indicate more about the cause of the failure.  

2

2

 

 

2-20

X

O

Fields to receive the values of the cells in the selected cell row. 

1

Unlimited

0

Unlimited

 

Technical Notes

The return fields must be specified in the same order as the cells in the space were defined. Cells are matched by the order of their specification in return values 2 -> 20. The names of the fields used have no bearing whatsoever on the cell mapping logic.

You can specify less key values than are defined in the space. The first matching cell row will be returned. This means that partial key operations can be performed.

If you specify more key values than are defined as key cells for the space then the additional values will be ignored and have no effect on the outcome of the search.

If you specify less return field values than there are cells in the space then the non-specified cells are not mapped back into the fields.

If you specify more return field values than there are cells in the space then the additional field values are ignored and are not changed by the search operation.

If a key value longer than 256 bytes is specified, a fatal error will occur.

Example

This example is selecting the first record with a matching surname.

Define Field(#SpaceRC) Type(*Char) Length(2)

Def_Cond Name(*Okay) Cond('#SpaceRC = OK')

*

Use Builtin(Select_in_Space) With_Args(TEST #SURNAME) To_Get(#SpaceRC #SURNAME #GIVENAME #EMPNO)

Dowhile (*Okay)

Add_Entry To_List(#Emplist)

Use Builtin(SelectNext_in_Space) With_Args(TEST #SURNAME) To_Get(#SpaceRC #SURNAME #GIVENAME #EMPNO)

Endwhile