Short summary

Name	`GET_REF_FROM_VARNAME`
→POU type	→function
Category	IEC-block, MemoryEnh, block with internal error diagnostic
Conform to →IEC-standard	not defined in IEC-standard
Graphical interface
Available since	version 1.42.0 (for logi.CAD 3) and version 2.3.1701 of logi.RTS – initial variant: elementary data types for requested variable and return value version 1.51.0 (for logi.CAD 3) and version 3.0.7 of logi.RTS – enhancement: structured/array data type for requested variable and return value version 1.58.0 (for logi.CAD 3) and version 3.1.1 of logi.RTS – enhancement: derived data type for requested variable and return value This block is supported for the built-in PLC only. version 1.109.0 (for logi.CAD 3) and version 3.19.0 of logi.RTS This block is supported for the built-in PLC and the platforms `WindowsX86` and `LinuxX86` only. version 3.2.3 (for library `Standard` ) and version 4.12.0 of logi.RTS – enhancement: result code `16#83` for `VAR_IN_OUT` (instead of `16#81`) This block is supported for the built-in PLC and the platforms `WindowsX86` and `LinuxX86` only. version 3.2.6 (for library `Standard` ) and version 5.11.0 of logi.RTS – enhancement: supported →input variables ( `VAR_INPUT` ) and →output variables ( `VAR_OUTPUT` ) This block is supported for the built-in PLC and the platforms `WindowsX86` and `LinuxX86` only.

Functionality

The block returns the →reference to a variable. Enter its instance path in upper case at input NAME.
logi.cals recommends to call the GET_REF_FROM_VARNAME block just once for the variable to request. On the one hand, the time behavior might be unpredictable and on the other hand, it might take longer to determine the reference.

Restrictions for the usage:

The requested variable must have been declared with an elementary data type, a →derived data type, a →structured data type or an →array data type. The array type must be based on an elementary data type.
The elementary data types are the following data types: REAL, LREAL, USINT, UINT, UDINT, ULINT, SINT, INT, DINT, LINT, TIME, BOOL, BYTE, WORD, DWORD, LWORD, STRING, CHAR, DATE_AND_TIME, DATE or TIME_OF_DAY
There must be an instance for the requested variable. This means that the variables in →functions cannot be requested.
The following variables cannot be requested:
- variables with the keyword CONSTANT
- →in-out variables (VAR_IN_OUT)
The data type of the reference must match the data type of the requested variable. In case of STRING variables, the length must match as well.
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.

Inputs, outputs, return value

	Identifier	→Data type	Description
Inputs:	`NAME`	`STRING`	instance path of the variable (in upper case) Use `.` as separator.
Outputs:	`LEN`	`UINT`	length (= memory size) of the variable (in bytes) or `0`
Outputs:	`STATUS`	`USINT`	state of the operation (result code): `16#00`: operation succeeded `16#80`: The service is not available. `16#81`: The variable has not been found. `16#83`: invalid variable section `VAR_IN_OUT` `16#84`: invalid access to `CONSTANT` `16#85`: The data type does not match. `16#86`: The size does not match.
Return value:	–	→reference to an elementary data type, derived data type, a structured data type or an array data type (The array type must be based on an elementary data type.) The elementary data types are the following data types: `REAL`, `LREAL`, `USINT`, `UINT`, `UDINT`, `ULINT`, `SINT`, `INT`, `DINT`, `LINT`, `TIME`, `BOOL`, `BYTE`, `WORD`, `DWORD`, `LWORD`, `STRING`, `CHAR`, `DATE_AND_TIME`, `DATE` or `TIME_OF_DAY`	typed reference to the requested variable 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.

Internal error diagnostic for block

The block checks whether one of the above restrictions is violated. In such an error case, the output ENO of the block is set to the value FALSE (or an equivalent). Moreover, the output STATUS returns the appropriate code (see the above table under STATUS), the output LEN returns the value 0 and the block itself returns NULL (as return value).

Example for usage within ST-editor

Exemplary usage of the GET_REF_FROM_VARNAME block

PROGRAM DocumentationExamples
VAR
	iExampleGetRefFromVarname : ExampleGetRefFromVarname;
END_VAR
	iExampleGetRefFromVarname();
END_PROGRAM
 
FUNCTION_BLOCK ExampleGetRefFromVarname
    VAR
        requestedVar : INT;       
        reference : REF_TO INT;
         
        CheckSize : UINT;
        CheckState : USINT;
        CheckENO : BOOL;
    END_VAR
     
    IF reference = NULL THEN
        reference := GET_REF_FROM_VARNAME(NAME := 'DOCUMENTATIONEXAMPLES.IEXAMPLEGETREFFROMVARNAME.REQUESTEDVAR', LEN => CheckSize, STATUS => CheckState, ENO => CheckENO);
    END_IF;
     
    IF reference <> NULL THEN
        reference^ := 42;
    END_IF;
  
    ENO := requestedVar = 42;
END_FUNCTION_BLOCK

When 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.