Calling CitectVBA from Cicode

Three new Cicode functions allow CitectVBA code to be called from within Cicode script, and be pre-emptively multitasked by Citect SCADA. These calls VbCallOpen(), VbCallRun(), and VbCallReturn()can be nested to implement the entire function set with a single line of Cicode.

Note: When using the CiVBA language override in a Command field, the compiler constructs the nested call for you. The same mechanism is used even though it is not self evident. For details, see Using CitectVBA in Citect SCADA Command or Expression fields.

For information on multithreading in CitectVBA, see Multithread Considerations with CitectVBA.

To call a given CitectVBA function or subroutine from Cicode, use the VbCallOpenfunction. This returns a handle which can then be used to execute the call by passing it to the VbCallRunfunction. Upon return from VbCallRun, you can call the VbCallReturnfunction to get the return value of the CitectVBA function called.

The Cicode VbCallOpen()function is used to initiate a call to the CitectVBA function or subroutine, and returns a handle to the open function.

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

where:

<ReturnValue> represents the handle to the opened function.
<FunctName> represents the name of the CitectVBA function or subroutine being called.
<ArgList> represents a comma separated list of arguments to pass to the opened CitectVBA function or subroutine named in <FunctName>.

The Cicode VbCallRun()function is used to execute the CitectVBA function or subroutine (previously opened with the Cicode VbCallOpenfunction), and requires the handle returned from the VbCallOpenfunction call. The VbCallRunfunction provides an opportunity for the opened CitectVBA function to complete and return a value in the multi-threaded Citect SCADA environment. It passes its argument value (of OBJECT data type) through as its return value upon completion.

<ReturnValue> = VbCallRun(<CallHandle>)

where:

<ReturnValue> represents the handle to the opened CitectVBA function passed through for the <CallHandle>argument.
<CallHandle> represents the handle to the previously opened CitectVBA function as returned by the Cicode VbCallOpenfunction.

The Cicode VbCallReturn()function is used to obtain the return value of the completed CitectVBA function (previously opened with the Cicode VbCallOpenfunction), and requires the handle returned from the VbCallRunfunction call.

<ReturnValue> = VbCallReturn(<CallHandle>)

where:

<ReturnValue> represents the value returned by the completed CitectVBA function (which was previously opened by the Cicode VbCallOpenfunction). The data type of the return value is dependent upon the data type of the return value for the CitectVBA function opened.
<CallHandle> represents the handle to the previously opened CitectVBA function as returned by the Cicode VbCallRunfunction.

Example

FUNCTION
TestCitectVBA()
INT iRet;
STRING sMsg = "Hello";
INT iVal = 123;
iRet = VbCallReturn(VbCallRun(VbCallOpen("CiVBATest", iVal)));
Message("TestCitectVBA Function", "CiVBATest = " + 
IntToStr(iRet), 0);
END

Example

Function CiVBATest(Value As Integer) As Integer
CiVBATest = Value * 2
End Function