Arguments are used in CitectVBA to pass values into subroutines and functions when they are being called. Arguments are positioned between parentheses '( )' immediately after the subroutine or function name in the subroutine or function declaration. If no arguments are required for the subroutine or function, the parentheses must be included and left empty in the declaration.
Arguments are optional in the sense that subroutines and functions do not require them. However, if arguments are to be used in a subroutine or function, the arguments must first be declared with the subroutine or function declaration, before they can be used. If declared, they must be used whenever the subroutine or function is called.
CitectVBA does NOT support named arguments so all arguments must be used in declaration order. If omitted, strings default to an empty string (""), and numeric values default to zero (0). Boolean values in CitectVBA are represented with -1 for TRUE, and 0 for FALSE.
Multiple arguments must be separated by a comma ( , ) placed between the arguments. The number of arguments that can be used in any single subroutine or function is not stated, (but likely limited to something like 255). If you are declaring a subroutine or function with that many arguments, you should probably split your subroutine or function into smaller separate logical routines with less arguments for each routine. If an argument is omitted, its place must be declared by the use of a comma in the call.
If you want to use the value in a CitectSCADA tag as an argument to a function or subroutine, you must assign the value of the tag to a CitectVBA variable, and then pass the variable as the argument. You cannot pass a CitectSCADA tag name as an argument to a function or subroutine.
Each argument declaration in a subroutine or function must be structured using the proper CitectVBA argument syntax as described below.
CitectVBA argument structure syntax in the declaration of functions or subroutines is as follows:
( [ Byval ] <Argument/s> [ As <DataType> ] )
where:
The optional 'Byval' parameter specifies that the variable is passed by value instead of by reference (see the section titled 'Passing Variables Byref and Byval with CitectVBA').
Note:CitectSCADA tag values MUST be declared by value when passed as argument values to a CitectVBA procedure from within a CitectSCADA command or expression field. This is best done by declaring a variable, assigning it the tag value, then passing the variable by value.
The function or subroutine name always ends with a pair of parentheses ( ) which may or may not contain one or more arguments required by (necessary for use in) the function or subroutine. Multiple arguments if used, are separated by commas ( , ).
The optional 'As <DataType>' parameter is used to specify the data type of the argument variable. The argument data types must be individually declared, or will be of Variant data type by default. Valid data types for arguments in CitectVBA are: String, Integer, Double, Long, and Variant (see the section titled 'CitectVBA_Data_Types' for descriptions of data types in CitectVBA).
Example
' Arguments are declared with the function or subroutine
' The function is called from the subroutine highlighted below
Function longArea(Byval longLength As Long, _
Byval longWidth As Long) As Long
' multiplies arguments and
' assigns result to return value
longArea = longLength * longWidth
End Function
Sub FindArea
' declare long variables X Y and Z
Dim longX As Long
Dim longY As Long
Dim longZ As Long
' assign numeric value 12 to variable X
X = 12
' assign numeric value 34 to variable Y
Y = 34
' call function named longArea,
' passing in values of X and Y variables
' as arguments
'store result in variable Z
Z = longArea(X, Y)
' copy result Z to tag
TestTag_1 = Z
End Sub
Granted, that's not likely the way you'd actually calculate an area given two fixed values in a subroutine that calls a function. You could just as easily do the calculation within the subroutine. However, this example does demonstrate the passing of values from a subroutine to a function, and the retrieval of a return value from the function back to the calling subroutine.
Note in the previous example, that the argument names ('longLength' and 'longWidth') are only used within the function in which they were declared. The values they represented were passed in with the call to the function in the statement line:
Z = longArea(X, Y)
The values of the variables 'X' and 'Y' were passed into the function 'longArea' and were handled within the function as its argument names 'longLength' and 'longWidth'. The result was returned and stored in the variable named 'Z'.
See Also