MsgRPC

Calls a remote procedure on another Plant SCADA computer. You can call any of the built-in Cicode functions remotely, or your own functions. You pass the sName of the function as a string, not as the function tag, and pass all the arguments for that function in Arg.

You can call the function in synchronous or asynchronous Mode. In synchronous mode, MsgRPC() does not return until the remote function is called and the result is returned. In asynchronous mode, MsgRPC() returns before the function is called, and the result cannot be returned.

Note:
• The Allow RPC property for a Role determines if a user or group of users can perform remote MsgRPC and ServerRPC calls. This functionality now requires a user-specific permission. To allow existing users to use MsgRPC and ServerRPC, you need to manually change the value of Allow RPC to "TRUE" in Plant SCADA Studio’s Security | Roles view. You also need to set the Allow RPC property to "TRUE" for each server process that these functions will access.
• If you want to use MsgRPC to call a procedure on a remote client computer, you will need to set the parameter [Client]AllowRPC=1 on the client computer.

Syntax

MsgRPC(hMsg, sName, Arg, Mode)

hMsg:

The message handle, returned from the MsgOpen() function. The message handle identifies the table where all data on the associated message is stored.

sName:

The name of the function to call remotely, as a string.

If this function returns an error, you should confirm that the name you have used is not a label instead of the actual function name. Some functions are aliased using a label, for example, the function _AlarmGetFieldRec is defined in the labels database as "AlarmGetFieldRec". In this case, only "_AlarmGetFieldRec" should be passed to MsgRPC.

Arg:

The arguments to pass to the function, separated by commas (,). Enclose string arguments in quotes "" and use the string escape character (^) around strings enclosed within a string. If you do not enclose the string in quotes, then the string is only the first tag found.

Mode:

The mode of the call:

0 - Blocking mode - synchronous.

1 - Non-blocking mode - asynchronous.

Return Value

The result of the remote function call (as a string). If the function is called in asynchronous mode the result of the remote function cannot be returned, so an empty string is returned.

Note: The error code 513 will be returned if the Allow RPC property is not set to TRUE in an associated Role or server process.

Related Functions

MsgOpen, MsgClose, MsgRead, MsgWrite

Example

! Call remote procedure, call MyRPC() on server. Wait for result

Str=MsgRPC(hMsg,"MyRPC","Data",0);

! Call remote procedure, pass two strings. Don't wait for call to complete.

! be careful of your string delimiters as shown.

MsgRPC(hMsg,"MyStrFn","^"First string^",^"Second string^"",1);

! Call remote procedure, pass Cicode string. Don't wait for call to complete.

STRING sMessage = "this is a message";

MsgRPC(hMsg,"MyStrFn","^"" + sMessage + "^"",1);

! These functions could be used to acknowledge an alarm by record
from any Plant SCADA Client on the network.

! The AlmAck() function is initialized by the Control Client
(Don't forget that servers are also Control Clients.)

! The Alarm tag is passed into the function as a string and a
message is sent to the Alarms Server to initialize

! the AlmAckMsg() function.

FUNCTION

AlmAck(String AlmTag)

INT hAlarm1;

hAlarm1 = MsgOpen("Alarm", 0, 0);

MsgRPC(hAlarm1,"AlmAckMsg",AlmTag,1);

MsgClose("Alarm", hAlarm1);

END

! The AlmAckMsg() function is executed on the Alarms Server that
the client is connected to. This could be

! either the primary or standby Alarms Server. The function
performs the alarm acknowledge.

FUNCTION

AlmAckMsg(String AlmTag)

AlarmAckRec(AlarmFirstTagRec(AlmTag,"",""));

END

See Also

Task Functions