ACCESS

The ACCESS keyword is used in combination with input parameters to a function to support parameter passing by reference. The standard parameter passing method to a function is by value.

This is a simple example of using reference parameter passing:

FUNCTION TEST;
VAR_INPUT
   v1 : ACCESS INT;
   v2 : ACCESS STRING;
   v3 : INT;
END_VAR;
   v1 := v1 * 5; 
   v2 := "Hello world";
   v3 := 51;   <--- NOT ALLOWED
END_FUNCTION;
 
VAR
   x1 : INT := 1;
   x2 : INT := 1;
   s  : STRING := "Nice";
END_VAR;

Calling the function:

TEST( v1 := x1, v2 := s,  v3 := x2 );

After the call to "test", the contents of the parameters passed to the function are as follows: "x1" is 5, "x2" is 1, and "s" is "Hello world".

Please note that "x2" did not change its value as it was passed by value. "x1" and "s" were both passed by reference and therefore the changes for the actual parameters to "TEST" changed accordingly.

Actually it is not possible for "TEST" to update the "v3" parameter as changes to VAR_INPUT by value parameters in a function are not allowed. Using the ACCESS attribute on a VAR_INPUT variable will, however, change this rule and allow updating of the referenced parameter.

By using the ACCESS attribute, it is possible to pass a STRUCT_BLOCK to a function:

STRUCT_BLOCK server_pack;
   mode         : SINT;
   linsec       : DINT;
   latitude     : DINT;
   longitude    : DINT;
END_STRUCT_BLOCK;
 
 
FUNCTION SendData : BOOL;
VAR_INPUT
   v   : ACCESS server_pack;
   res : ACCESS INT;
END_VAR;
 
   ... Sends the data and returns the status in 'res'.
   res := 0; 
   SendData := TRUE;
    
END_FUNCTION;
 
VAR
   pack : server_pack;
   rc   : INT;
END_VAR;

Calling the function to send the "pack" of data:

... Fill in the data to send in 'pack', and send.

SendData( v := pack, res := rc );

Note that any possible changes to the "v" formal parameter in the SendData function will affect the content of the actual parameter "pack".

The ACCESS attribute can also be used with ARRAY parameters in a function VAR_INPUT section. An ACCESS ARRAY parameter gives the function direct access to the caller-owned array storage. The array is not copied, and writes through the formal parameter modify the caller's array elements.

FUNCTION SetWindow : INT;
VAR_INPUT
 values : ACCESS ARRAY[2..3] OF INT;
END_VAR;
 
values[2] := 22;
values[3] := 33;
SetWindow := values[2] + values[3];
END_FUNCTION;
 
PROGRAM example;
VAR
 data : ARRAY[0..9] OF INT;
 rc : INT;
END_VAR;
 
rc := SetWindow(values := data);
END_PROGRAM;

For ACCESS ARRAY parameters, the actual parameter must be a whole ARRAY variable. Passing an indexed element, for example values := data[0], is not allowed. A normal ARRAY input without ACCESS is not passable by callers; use ACCESS ARRAY when a function must receive an array supplied by the caller.

•For one-dimensional ACCESS ARRAY parameters, the actual array may be larger than the formal array when the actual array bounds fully cover the formal bounds. For example, ACCESS ARRAY[10..20] OF INT can receive ARRAY[0..50] OF INT, but ACCESS ARRAY[0..500] OF INT cannot receive ARRAY[0..50] OF INT.

•For two-dimensional ACCESS ARRAY parameters, the dimensions and bounds must match exactly. Larger two-dimensional actual arrays are not accepted.

•Supported element types are elementary types, STRING, and STRUCT_BLOCK. STRUCT_BLOCK elements may contain normal supported members, including strings and arrays.

•Arrays of FUNCTION_BLOCK or THREAD_BLOCK elements are not supported as ACCESS ARRAY parameters.

FUNCTION SetGrid : INT;
VAR_INPUT
 grid : ACCESS ARRAY[0..1,0..1] OF INT;
END_VAR;
 
grid[1,1] := 77;
SetGrid := grid[1,1];
END_FUNCTION;

The compiler checks ACCESS ARRAY calls at compile time. Common errors include using a non-array actual parameter, passing an indexed array element, using an incompatible element type, using one-dimensional actual bounds that do not cover the formal bounds, using non-identical two-dimensional bounds, or using unsupported FUNCTION_BLOCK or THREAD_BLOCK element arrays. No firmware or VM change is required for ACCESS ARRAY parameters; existing runtime bounds checking is preserved.

Using ACCESS parameters to a function has many advantages:

•In addition to the single return value from a function, an arbitrary number of additional return values can be realized.

•It can often be used easier and with a memory saving if used instead of a FUNCTION_BLOCK.

•ACCESS parameter passing with a STRUCT_BLOCK is possible, which allows a composite type to be passed and returned.

.. and only a few rules apply:

•All ACCESS parameters must be assigned by the caller.

•The variable types of the formal parameter and the actual parameter must be identical.

Also see the section on functions in the VPL Introduction Manual.