Send

(RPC Manager Library)

Description: This subroutine sends a message by invoking a remote procedure call (RPC). Subroutine call only.

Returns: Current session id of remote procedure, else RPC_NO_SID

Usage: Script

Format: \RPCManager\Send(Service, RemoteGUID, ModeCutOff, SendServer, MachineName, SendClients, ExecLocally, Recursive, ModuleName, ModuleContext, UpdateObject, InputSessionID [, Parmeters…])

Parameters: ServiceName { text } { required } { no default: }

The name of the service to transmit to. For directed RPCs, set this value to either Invalid or a zero-length string.

RemoteGUID { text } { required } { no default: }

The GUID of the application to receive the RPC. If Invalid, RemoteGUID is searched for in the caller's scope.

ModeCutOff { text } { required } { no default: }

The service synchronization mode above which this message should not be sent. Normal RPCs should set this to RPC_ACCEPT_ALL mode.

SendServer { Boolean } { required } { no default: }

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 { text } { required } { no default: }

The IP or name of the workstation to be used for a directed RPC. Invalid for service RPCs.

SendClients { Boolean } { required } { no default: }

If set to "1", this flag will transmit this RPC to all service instances that are currently clients of the service server. Ignored for directed RPC requests.

ExecLocally { Boolean } { required } { no default: }

If set to "1", this flag forces the RPC to be executed locally. Used with directed RPCs.

Recursive { Boolean } { required } { no default: }

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. Unless you have good reason, it is wise to set this flag when making service broadcast updates.

ModuleName { text } { required } { no default: }

The textual name of the RPC subroutine to be executed. Must be valid.

ModuleContext { text } { required } { no default: }

The context in which the "ModuleName" will be executed. The "base" context for a VTS layer-based application is "\Code". For a non-VTS (pure script) application, the base context is the root of the application specified by the RemoteGUID parameter. Must be valid.

UpdateObject { Object } { required } { no default: }

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 { numeric } { required } { no default: }

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 remote application; otherwise the RPC will not be queued for transmission. Only of use in directed RPCs.

Parameters { varies } { optional } { no default: }

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 AppMod.src.

The method returns the current SID of the remote application if the message was queued for transmission; otherwise, it will return RPC_NO_SID.

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.