(RPC Manager Library)
| Description: | This subroutine sends a message by invoking a remote procedure call (RPC). |
| Returns: | Current session id of remote procedure, else RPC_NO_SID |
Usage:  |
Script Only. |
| Function Groups: | Network |
| Related to: | ConnectToMachine | DisconnectFromMachine | GetServer | GetServersListed | GetStatus | IsClient | IsPotentialServer | IsPrimaryServer | Register (RPC Manager) | SetRemoteValue |
| Format: |
\RPCManager\Send(Service, RemoteGUID, ModeCutOff, SendServer, MachineName, SendClients, ExecLocally, Recursive, ModuleName, ModuleContext, UpdateObject, InputSessionID [, Parameters…]) |
| Parameters: |
| ServiceName |
| Required. The name of the service to transmit to. For directed RPCs, set this value to either Invalid or a zero-length string. |
| RemoteGUID |
| Required. The GUID of the application to receive the RPC. If Invalid, RemoteGUID is searched for in the caller's scope. |
| ModeCutOff |
| Required. The service synchronization mode above which this message should not be sent. Normal RPCs should set this to RPC_ACCEPT_ALL mode. |
| SendServer |
| Required. If set to "1", this flag will transmit this RPC to the service instance that is currently the server for the service. Ignored for directed RPC requests. |
| MachineName |
| Required. The IP or name of the workstation to be used for a directed RPC. Invalid for service RPCs. |
| SendClients |
|
Required. May be any of the following: 0: Do not send to clients 1: Transmit this RPC to all service instances that are currently clients of the service server. Ignored for directed RPC requests. 2: Send to all clients that are on the local machine's list of potential service servers. |
| ExecLocally |
| Required. If set to "1", this flag forces the RPC to be executed locally. Used with directed RPCs. |
| Recursive |
| Required. If set to "1", and SendClients is also set to "1", this flag will transmit this RPC to all service instances that are clients of this workstation and all service instances that are clients of them. If set to a "1" and SendServer is also a "1", will transmit to servers of this workstation and servers of those workstations. This is of use when "clients of clients" are configured. In most cases, it is wise to set this flag when making service broadcast updates. |
| ModuleName |
| Required. The textual name of the RPC subroutine to be executed. Must be valid. |
| ModuleContext |
|
Required. The context in which the "ModuleName" will be executed. The "base" context for a VTScada layer-based application is "Code". "." may be used as an alias for the object that registered for the RPC service. See comments. |
| UpdateObject |
| Required. If valid, is an object that will act as a holding point for the RPC until it is actually transmitted to the remote workstation. A subsequent RPC with the same UpdateObject value will discard the previous RPC if it has not yet been transmitted, and replace it with the new one. This is of most use to services whose updates completely negate the effect of previous updates, and serves to minimize the transmission of redundant RPCs. |
| InputSessionID |
| Required. If Invalid, the RPC will be queued for transmission. If valid, will be interpreted as a SID which must match the current SID for the multi-server application. Otherwise, the RPC will not be queued for transmission. Only of use in directed RPCs. |
| Parameters |
| A set of up to 32 parameters to the RPC subroutine. Can be any mixture of the legal types. Supplying a parameter of an illegal type will cause it to be replaced with Invalid when the RPC subroutine is invoked. |
Comments
This subroutine is a member of the RPC Manager's Library, and must therefore be prefaced by \RPCManager\, as shown in the "Format" section. If the application you are developing is a script application, the subroutine call must be prefaced by System\RPCManager\, and the System variable must be declared in AppRoot.src.
The method returns the current SID of the multi-server application if the message was queued for transmission. Otherwise, it will return RPC_NO_SID.
Service Relative Context
As of VTScada version 12.0, you can send a message to a remote service object using a module context of "." as an alias for the full scope path of the object that registered for the RPC service. This works on any service-based Send() operation.
The context should be specified as "." where "." is an alias for the object that called RPCManager\Register(). Directed RPC do not support relative context, even if Send() is run using a ServiceName, as those are not truly service RPCs.
Example:
If 1 Main;
[
sessID = \RPCManager\Send("MyService" { service }, \RemoteGUID,
\RPC_ACCEPT_FILTER { mode cut-off },
1 { server }, Invalid { machine },
0 { clients }, 0 { locally },
0 { recursive }, "Start" { module },
"\" { service scope },
Invalid { queue msgs },
Invalid { no initial session ID },
{ Parameters: } rev, myName);
sessID = \RPCManager\Send("MyService" { service },
\RemoteGUID,
\RPC_ACCEPT_FILTER { mode cut-off },
1 { server }, Invalid { machine },
0 { clients }, 0 { locally },
0 { recursive }, "Finish" { module },
"\" { service scope },
Invalid { queue msgs },
sessID { original server's sess ID },
{ Parameters: } index);
]
This will cause the modules called Start and Finish, which are found in the scope of the service called MyService, to be executed on the server. Note that by handing in the session ID from the first call to the second call it is guaranteed that module Finish will either be queued for the workstation that was the server at the time when the first message was queued or will be discarded. It will not be sent to another workstation that may take over servership for the MyService service.
