Page History
9.31 CREATE_SPACE
| Note | ||
|---|---|---|
| title | Note: | Built-In Function Rules Usage Options |
Creates a space object with the specified name.
Arguments
No | Type | Req/ Opt | Description | Min Len | Max Len | Min Dec | Max Dec |
|---|---|---|---|---|---|---|---|
1 | A | R | Space Name A name must be specified. Names are NOT case sensitive. Names should not be started with an asterisk (*) or blank character. | 1 | 256 |
Return Values
No | Type | Req/ Opt | Description | Min Len | Max Len | Min Dec | Max Dec |
|---|---|---|---|---|---|---|---|
1 | A | O | Standard Return Code "OK" = Space created or already exists. "ER" = Creation attempt failed. Messages issued will indicate more about the cause of the failure. | 2 | 2 |
Technical Notes
Space objects are unique within an operating system process (or job) by their name (case insensitive).
...
This is demonstrated in this working function:
FUNCTION OPTIONS(*DIRECT)
********** COMMENT(Prototypical cells must be referenced)
GROUP_BY NAME(#XG_SPACE) FIELDS(#EMPNO #SURNAME #GIVENAME)
********** COMMENT(Space name is based on function name and default)
DEFINE FIELD(#SPACENAME) REFFLD(#FUNCTION)
********** COMMENT(Create space keyed cell EMPNO and with 2 data cells)
USE BUILTIN(CREATE_SPACE) WITH_ARGS(#SPACENAME)
USE BUILTIN(DEFINE_SPACE_CELL) WITH_ARGS(#SPACENAME EMPNO KEY)
USE BUILTIN(DEFINE_SPACE_CELL) WITH_ARGS(#SPACENAME GIVENAME)
USE BUILTIN(DEFINE_SPACE_CELL) WITH_ARGS(#SPACENAME SURNAME)
********** COMMENT(Don't forget to destroy the space when finished)
USE BUILTIN(DESTROY_SPACE) WITH_ARGS(#SPACENAME)
Where a form or function creates multiple spaces an approach that suffixes the space names with a unique identifier is recommended.
This code fragment demonstrates a technique for doing this:
********** COMMENT(Name is longer and contains the function name)
DEFINE FIELD(#EMPSPACE) REFFLD(#SYSVAR$AV) DEFAULT(*FUNCTION)
DEFINE FIELD(#DEPSPACE) REFFLD(#SYSVAR$AV) DEFAULT(*FUNCTION)
DEFINE FIELD(#SECSPACE) REFFLD(#SYSVAR$AV) DEFAULT(*FUNCTION)
********** COMMENT(During initialization/startup)
USE BUILTIN(TCONCAT) WITH_ARGS(#EMPSPACE '.Emp') TO_GET(#EMPSPACE)
USE BUILTIN(TCONCAT) WITH_ARGS(#DEPSPACE '.Dep') TO_GET(#DEPSPACE)
USE BUILTIN(TCONCAT) WITH_ARGS(#SECSPACE '.Sec') TO_GET(#SECSPACE)
(In a component you would of course use a default value of *COMPONENT rather than *FUNCTION for each of the space names).
...
Set #ReturnName Value(#TempName)
EndRoutine
Other Tips, Techniques and Recommendations
In high volume repeated commands avoid using visually defined fields as mapping values unless absolutely necessary. When a field has been visually defined mapping into or out of its value is significantly slower because of the underlying visual context.
...
Use SelectNext_in_Space #Space (#SpaceRc #XEmpNo #XGiveName #XSurName)
EndWhile
Example
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)