9.31 CREATE_SPACE
Þ Note: Built-In Function Rules.
Creates a space object with the specified name.
For use with
|
Arguments
|
Return Values
|
Technical Notes
Space objects are unique within an operating system process (or job) by their name (case insensitive).
Space objects cannot be shared between operating system processes (or jobs). If operating system process A and B are both using a space object named X then they each have their own unique and independent instance of the space object named X.
Space objects are not persistent. A space object and its data content ceases to exist when the operating system process (or job) that owns them ends.
Space Naming Recommendations and Techniques
In most simple RDML function contexts a naming convention based on the name of the current function should be used.
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).
In more complex environments there is a possibility that a space has already been created and defined by another instance or previous execution of the same piece of logic.
In such situations you can check whether a space exists before attempting to create it by using a technique like the one demonstrated in these RDMLX code fragments:
Define #SpaceName RefFld(#SysVar$Av) Default(*Component)
Define #SpaceRC *Char 2
Def_Cond *NoSpace '#SpaceRC *ne OK'
EvtRoutine Handling(#Com_Owner.CreateInstance)
Use Space_Operation (#SpaceName CheckExistence) (#SpaceRC)
If *NoSpace
Use Create_Space (#SpaceName)
Use Define_Space_Cell (#SpaceName EmpNo Key)
Use Define_Space_Cell (#SpaceName SurName)
Use Define_Space_Cell (#SpaceName GiveName)
Endif
EndRoutine
In more complex multi-instance RDMLX components you may sometimes require a unique space (remembering that spaces are unique by name) for each separate instance of the component.
A technique like this may be used:
Define #SpaceName RefFld(#SysVar$Av) Default(*Component)
Define #SpaceRC *Char 2
Def_Cond *NoSpace '#SpaceRC *ne OK'
EvtRoutine Handling(#Com_Owner.CreateInstance)
Invoke #Com_Owner.CreateUniqueSpace ReturnName(#SpaceName)
Use Define_Space_Cell (#SpaceName EmpNo Key)
Use Define_Space_Cell (#SpaceName SurName)
Use Define_Space_Cell (#SpaceName GiveName)
EndRoutine
MthRoutine CreateUniqueSpace
Define_Map *Output #SysVar$av #ReturnName
Define #TempName RefFld(#SpaceName)
Define #TempChar *Char 10
Define #TempNum RefFld(#Date) Length(10) Decimals(0) edit_code(4) default(0) To_Overlay(#TempChar)
Begin_Loop Using(#TempNum)
Use TConcat (*Component '.' #TempChar) (#TempName)
Use Space_Operation (#TempName CheckExistence) (#SpaceRC)
Leave *NoSpace
End_Loop
Use Create_Space (#TempName)
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.
For example, imagine that you want to count the total number of rows in an employee space (which has about 125,000 rows).
You might use code like this:
Def_Cond *Okay '#SpaceRC = OK'
Change #EmpTotal 0
Use Select_in_Space #Space (#SpaceRc #EmpNo #GiveName #SurName)
DoWhile *okay
Change #EmpTotal '#EmpTotal + 1'
Use SelectNext_in_Space #Space (#SpaceRc #EmpNo #GiveName #SurName)
EndWhile
If any one of the fields #Space, #SpaceRc, #EmpNo, #GiveName or #SurName is defined in a visual context (ie: as part of a DEFINE_COM) then the performance of this loop will be impacted by mapping values into them 125,000 times.
Assuming that #EmpNo, #GiveName or #SurName are in fact defined in a visual context then to improve the performance of this logic you could do this:
Def_Cond *Okay '#SpaceRC = OK'
Change (EmpTotal 0
Use Select_in_Space #Space (#SpaceRc)
DoWhile *okay
Change #EmpTotal '#EmpTotal + 1'
Use SelectNext_in_Space #Space (#SpaceRc)
EndWhile
Or do this:
Def_Cond *Okay '#SpaceRC = OK'
Define #XEmpNo RefFld(#EmpNo)
Define #XGiveName RefFld(#GiveName)
Define #XSurName RefFld(#SurName);
Change (EmpTotal 0
Use Select_in_Space #Space #SpaceRc #XEmpNo #XGiveName #XSurName)
DoWhile *okay
Change #EmpTotal '#EmpTotal + 1'
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)