Using CitectVBA in Command or Expression fields

CitectVBA Programming Reference > Integrating CitectVBA into a Project > Using CitectVBA in Command or Expression fields

Using CitectVBA in Command or Expression fields

Citect SCADA expects that all code contained within a Citect SCADA Command or Expression field to be Cicode by default. When using CitectVBA code script directly in a Citect SCADA Command or Expression field within Citect SCADA, you must precede the CitectVBA script with the keyword CiVBA, as shown here:

CiVBA
TestTag_1 = TestTag_1 + 1

This is known as the language override command. When the Citect SCADA compiler reads the keyword CiVBA, it knows to handle that code (within the same Citect SCADA Command or Expression field) as CitectVBA script, and compiles it as such. No such override command is required to use Cicode.

The CiVBA language override statement must be placed first in the Citect SCADA Command or Expression field if you want to use CitectVBA script code instead of Cicode in that Citect SCADA Command or Expression field.

Note: You must use either Cicode or CitectVBA in a Citect SCADA Command or Expression field. You cannot change or swap between the two programming languages (within the same Citect SCADA Command or Expression field) once you've started using one or the other.

You can, however, call a single Cicode function from within CitectVBA script if you wrap the Cicode call within special CitectVBA functions CicodeCallOpen()and CicodeCallReturn().

Calling Cicode from CitectVBA

Calling a Cicode function from CitectVBA is accomplished by two CitectVBA functions: CicodeCallOpen()and CicodeCallReturn().

To call a given Cicode function, use the CicodeCallOpenfunction which will create and execute a Cicode thread that runs the function. For multitasking purposes, a separate function CicodeCallReturnis used to obtain the return-value of the completed Cicode function most recently called by the CicodeCallOpenfunction.

UNINTENDED EQUIPMENT OPERATION

Do not nest the CicodeCallOpen and CicodeCallReturn functions. Nesting these functions can lead to unintended equipment operation when your program is run.

Failure to follow these instructions can result in death, serious injury, or equipment damage.

The return value is initialized when control is returned to the Citect SCADA kernel. This occurs only after completion of the line of CitectVBA code containing CicodeCallOpen. For details on multithreading in CitectVBA, see Multithread Considerations with CitectVBA.

To call a given Cicode function or subroutine from CitectVBA, use the CicodeCallOpenfunction. Upon return from CicodeCallOpen, you can call the CicodeCallReturnfunction to obtain the return value of the Cicode function called.

The CicodeCallOpenfunction is a CitectVBA function used to call a Cicode function from CitectVBA. It is used to initiate and execute a call to the Cicode function and returns an integer value representing the success or the type of error encountered by the CicodeCallOpen function.

<ReturnValue> = CicodeCallOpen(<FunctName>, <ArgList>)

where:

<ReturnValue> represents the return value of:

0 if CicodeCallOpenfunction was successful
1 for CicodeCallOpenfunction general error
2 for specified Cicode function not found
3 for incorrect number of arguments for specified Cicode function passed in <ArgList>.

<FunctName> is a string representing the name of the Cicode function being called. The function name should be enclosed in double quotes.
<ArgList> represents a variable length comma separated argument list of all the arguments to be passed to the Cicode function being opened (dependant upon which Cicode function is being called and the arguments that Cicode function requires). The argument list should not be enclosed within brackets, although when using variable names as arguments, those variable arguments within the list need to be individually enclosed within brackets to force the passing of the variable to Cicode by value.

The CicodeCallReturnfunction is a CitectVBA function used to obtain the return value of the most recently completed Cicode function opened with the CitectVBA CicodeCallOpenfunction.

<ReturnValue> = CicodeCallReturn()

where:

<ReturnValue> represents the return value of the Cicode function specified in the most recent call of the CicodeCallOpenfunction. Note that the return data type of CicodeCallReturnwill depend upon the return data type of the Cicode function called in the most recent call of the CicodeCallOpenfunction.

No arguments are passed to the CicodeCallReturnfunction, as it can only return the result of the most recent return-value for the Cicode function called by the CitectVBA CicodeCallOpenfunction.

Note:In the following example, a CitectVBA variable is enclosed in brackets to force the passing of the variable by value. See Passing variables Byref and Byval.

CitectVBA

' declare modular variant variable to store function results
Dim vntRet as Variant
Function TestCicode() As Integer
' declare local variables
Dim intRet As Integer
Dim strReply as String
Dim intMaxScale as Integer
' copy current tag value to variable
' uses the project variable tag named MAX_SCALE
intMaxScale = MAX_SCALE
' call Cicode function
' for example: TrnSetScale( AN, Pen, Percent, Scale) 
intRet = CicodeCallOpen(  "TrnSetScale", 53, -1, 100, (IntMaxScale) )
' Note the syntax used: 
'- brackets around the CitectVBA function argument list
'(Only necessary when the CitectVBA function is preceded by an equals (=) sign .)
'     - double quotes around the Cicode function name
'- no brackets around the Cicode function argument list 
'- brackets around individual variable arguments
' test results
If  intRet = 0 Then
'
' insert code for successful completion here
'
vntRet = CicodeCallReturn() 
strReply = "CicodeCallOpen Function successfully called"
Else
'
' insert code for unsuccessful completion here
'
Select Case intRet
Case = 1
' assign return comment for this case
strReply = "CicodeCallOpen Function call general error"

Case = 2
' assign return comment for this case
strReply = "Cicode Function not found"
Case = 3
' assign return comment for this case
strReply = "Wrong number of arguments "_
& "in Cicode CallOpen function call"
Case Else
' assign return comment for this case
strReply = "Unknown error"
End Select
End If
' display return comment for your information
MsgBox strReply
' assign return value for this function
TestCicode = intRet
End Function

Alternatively, to call a single CitectVBA function (from within the Citect SCADA Command or Expression field) after you have already used Cicode in that field, you can wrap the CitectVBA within three nested special Cicode functions: VbCallOpen(), VbCallRun()and VbCallReturn().

Calling Cicode from CitectVBA

Calling a Cicode function from CitectVBA is accomplished by two CitectVBA functions: CicodeCallOpen()and CicodeCallReturn().

UNINTENDED EQUIPMENT OPERATION

Do not nest the CicodeCallOpen and CicodeCallReturn functions. Nesting these functions can lead to unintended equipment operation when your program is run.

Failure to follow these instructions can result in death, serious injury, or equipment damage.

<ReturnValue> = CicodeCallOpen(<FunctName>, <ArgList>)

where:

<ReturnValue> represents the return value of:

0 if CicodeCallOpenfunction was successful
1 for CicodeCallOpenfunction general error
2 for specified Cicode function not found
3 for incorrect number of arguments for specified Cicode function passed in <ArgList>.

<FunctName> is a string representing the name of the Cicode function being called. The function name should be enclosed in double quotes.
<ArgList> represents a variable length comma separated argument list of all the arguments to be passed to the Cicode function being opened (dependant upon which Cicode function is being called and the arguments that Cicode function requires). The argument list should not be enclosed within brackets, although when using variable names as arguments, those variable arguments within the list need to be individually enclosed within brackets to force the passing of the variable to Cicode by value.

The CicodeCallReturnfunction is a CitectVBA function used to obtain the return value of the most recently completed Cicode function opened with the CitectVBA CicodeCallOpenfunction.

<ReturnValue> = CicodeCallReturn()

where:

<ReturnValue> represents the return value of the Cicode function specified in the most recent call of the CicodeCallOpenfunction. Note that the return data type of CicodeCallReturnwill depend upon the return data type of the Cicode function called in the most recent call of the CicodeCallOpenfunction.

No arguments are passed to the CicodeCallReturnfunction, as it can only return the result of the most recent return-value for the Cicode function called by the CitectVBA CicodeCallOpenfunction.

Note:In the following example, a CitectVBA variable is enclosed in brackets to force the passing of the variable by value. See Passing variables Byref and Byval.

CitectVBA

' declare modular variant variable to store function results
Dim vntRet as Variant
Function TestCicode() As Integer
' declare local variables
Dim intRet As Integer
Dim strReply as String
Dim intMaxScale as Integer
' copy current tag value to variable
' uses the project variable tag named MAX_SCALE
intMaxScale = MAX_SCALE
' call Cicode function
' for example: TrnSetScale( AN, Pen, Percent, Scale) 
intRet = CicodeCallOpen(  "TrnSetScale", 53, -1, 100, (IntMaxScale) )
' Note the syntax used: 
'- brackets around the CitectVBA function argument list
'(Only necessary when the CitectVBA function is preceded by an equals (=) sign .)
'     - double quotes around the Cicode function name
'- no brackets around the Cicode function argument list 
'- brackets around individual variable arguments
' test results
If  intRet = 0 Then
'
' insert code for successful completion here
'
vntRet = CicodeCallReturn() 
strReply = "CicodeCallOpen Function successfully called"
Else
'
' insert code for unsuccessful completion here
'
Select Case intRet
Case = 1
' assign return comment for this case
strReply = "CicodeCallOpen Function call general error"

Case = 2
' assign return comment for this case
strReply = "Cicode Function not found"
Case = 3
' assign return comment for this case
strReply = "Wrong number of arguments "_
& "in Cicode CallOpen function call"
Case Else
' assign return comment for this case
strReply = "Unknown error"
End Select
End If
' display return comment for your information
MsgBox strReply
' assign return value for this function
TestCicode = intRet
End Function