9.41 DEFINE_SPACE_CELL

Note: Built-In Function Rules     Usage Options

Defines a cell (or column) within the nominated space object. Refer also to the other SPACE Built-In Functions.

Arguments

No Type Req/ Opt Description Min Len Max Len Min Dec Max Dec 1 A R Name of the space into which the cell should be defined. 1 256     2 A R Name of a field whose definition is to be used as a prototype for the definition of this space cell. Note that this is the name of the field, not the field itself. Thus you should specify an employee number field as EMPNO rather than #EMPNO (which means that the content of  field #EMPNO contains the field name).    1 10     3 A O Cell attributes. Multiple cell attributes should be separated by a single space. The list of valid attributes (which may be in any case) includes: KEY:  specifies that this cell is a key to the space contents. Space objects should always have at least one key cell. DESCEND: specifies that descending sequence should be applied to this cell. This attribute is only valid when used with the KEY attribute, otherwise it is ignored.   NOCASE: specifies that the case of the key is ignored and all key comparisons are done in lowercase. This attribute is only valid when used with alphanumeric KEY cells, otherwise it is ignored. 1 256

Return Values

No Type Req/ Opt Description Min Len Max Len Min Dec Max Dec 1 A O Standard Return Code "OK" = Cell defined.  "ER" = Cell definition attempt failed. Messages issued will indicate more about the cause of the failure.   2 2

Technical Notes

The specified space object must be defined before any attempt is made to define cells within it (see the CREATE_SPACE Built-In Function) 

The currently active invocation stack is searched backwards until the first instance of a field with the specified name is found.

If an instance of the field name is found it is then instantaneously used as a definitional prototype for the space cell in terms of type, length, etc.

If an instance of the field name cannot be found a fatal error message is issued and the application terminates. 

It is recommended that all KEY cells be defined as the first cells in a space object.

The order that a key cell is defined implies their order within the aggregate key to the cell row. 

The order that any cell is defined implies the order that they will be mapped into and out of other space commands such as INSERT_IN_SPACE and FETCH_IN_SPACE.

If the data in the space requires more than one level of key to uniquely identify an individual entry, then more than one cell MUST be defined as the key.

Examples

Example 1

This example defines a space whose name is the current components name suffixed by ".emp" and then defines 3 cells within it whose type and length are based on the definitions of fields EMPNO, GIVENAME and SURNAME respectively. The first cell the key to the space:

Define #SpaceName *char 20

Use TConcat (*component '.EMP') (#SpaceName)

Use Create_Space (#SpaceName)

Use Define_Space_Cell (#SpaceName EmpNo Key)

Use Define_Space_Cell (#SpaceName GiveName)

Use Define_Space_Cell (#SpaceName SurName);

Example 2

The section file (SECTAB) in the LANSA demonstration system requires that two levels of key be specified to identify any given record.  The space must be defined in a similar format.  Failure to do so will cause unpredictable results when attempting to retrieve data from the space using SELECT_IN_SPACE and SELECT_NEXT_IN_SPACE.

Define field(#SpaceName) type(*char) length(20)

Use TConcat (*component '.EMP') #SpaceName)

Use Create_Space (#SpaceName)

Use Define_Space_Cell (#SpaceName Deptment Key)

Use Define_Space_Cell (#SpaceName Section Key)

Use Define_Space_Cell (#SpaceName Secdesc)