GET_NAMED_MEMORY block
Short summary
|
Name |
GET_NAMED_MEMORY |
|
→POU type |
|
|
Category |
|
|
Conform to →IEC-standard |
|
|
Graphical interface |
|
|
Available since |
|
This block is supported for the Functionality
The block returns the →reference to a memory area the name of which you enter at input NAME.
When the block is called for the first time, the requested memory in the dynamic memory of the target system (heap) is allocated and a reference to it is returned. The memory area referenced by the return value is initialized with 0 during the request. For each subsequent call of the block, a reference to the already allocated memory is returned.
In case of a →cold restart or →warm restart of the application, an allocated memory is automatically released.
As the type information of the return value is saved in addition to the name of the memory area, it is only allowed to use the call of the block on the right side of the assignment operator ":=" for →assignments to a reference variable. The size of the memory area results from the data type of the reference variable.
Inputs, outputs, return value
|
|
Identifier |
Description |
|
|
Inputs: |
NAME |
STRING |
name of the memory area |
|
Outputs: |
RC |
USINT |
return code of the allocation:
|
|
Return value: |
– |
a →reference to the following data types: |
typed reference to the requested memory area or NULL |
Input EN and output ENO are available when →calling the block. See "Execution control: EN, ENO" for information on input EN and output ENO.
See:
"Blocks for safe logic" whether this block is supported for developing safety-relevant applications.
"Highlighting safe logic in the FBD-editor" for the effects when using the block as a block for safe logic .
Internal error diagnostic for block
The block checks the following error cases:
The target system is out of memory.
The data type of the variable to which the call has been assigned does not match the data type of the memory area.
The RTSSMem system service has not been loaded.
In such an error case, the output ENO of the block is set to value FALSE (or an equivalent). Moreover, the output RC returns the appropriate code (see the above table under RC) and the block itself returns NULL (as return value).
Example for usage within ST-editor
PROGRAM GET_NAMED_MEMORY_TEST VAR r_data : REF_TO DWORD; r_other : REF_TO DWORD; r_invalid : REF_TO LWORD; eno_data : BOOL := FALSE; eno_other : BOOL := FALSE; eno_invalid : BOOL := FALSE; rc_data : USINT := 0; rc_other : USINT := 0; rc_invalid : USINT := 0; END_VAR r_data := GET_NAMED_MEMORY(NAME := 'data', ENO => eno_data, rc => rc_data); IF eno_data THEN r_data^ := 16#01020304; END_IF; r_other := GET_NAMED_MEMORY(NAME := 'data', ENO => eno_other, rc => rc_other); IF eno_data AND eno_other THEN /* 'r_data_other' now refers to the same memory area as 'r_data' */ END_IF; r_invalid := GET_NAMED_MEMORY(NAME := 'data', ENO => eno_invalid, rc => rc_invalid); /* 'r_data_invalid' is 'NULL' because types do not match; 'ENO' is 'FALSE', 'rc' has value '16#02' */END_PROGRAMlogi.cals recommends to call the GET_NAMED_MEMORY block once at the most for each memory area to request. On the one hand the time behavior might be unpredictable and on the other hand it might take longer to determine the already allocated memory area. The following example demonstrates the one-time usage:
PROGRAM GET_NAMED_MEMORY_RECOMMENDED VAR r : REF_TO BYTE := NULL; rc : USINT := 16#FF; END_VAR IF r = NULL THEN r := GET_NAMED_MEMORY(NAME := 'sample', ENO => ENO, RC => rc); END_IF; IF ENO THEN /* code using the reference to the allocated byte */ r^ := 16#AF; END_IF;END_PROGRAMWhen creating your application within the ST-editor, enter a call of a block by typing the text as requested by the syntax or use Content Assist.