MsgOpen

Opens a message session with a Plant SCADA server. You can specify a message post function - a callback function that is automatically called when a message arrives. In this function you can call MsgRead() to get the message, and perform other tasks common to your message sessions. You can then call MsgWrite() to send a message back to the caller, MsgRPC() to call a procedure on the caller, and so on.

A logged on user is required for this function to be successful.

Note: This function will only work successfully on a full-control client. It will not work on a view-only client.

Syntax

MsgOpen(Name, Mode, Fn [, sClusterName] )

You should use MsgState() to check the return value of MsgOpen(), unless you are using mode 1. The message post function is set effectively only if MsgState() returns 1, which means the message session is online.

You can open a client-server message session or a session between redundant servers. This function does not create extra network sessions; it uses Plant SCADA's existing sessions, so you create sessions to the alarm server, report server, trend server, or a named I/O server.

sName:

The name of the server to open, either:

For Mode 0, 1, or 3: "Alarm", "Report", "Trend", or the name of an I/O server.

For Mode 2: The default computer name, as set in the [LAN]Node parameter.

Mode:

The mode of the message session to open:

0 - Open the client side.

1 - Open the server side.

2 - Open a session from a server to the default computer name. Set Name to the computer name of the computer, as defined by the [LAN]Node parameter.

3 - Open a message session between redundant servers. (Clients cannot tell which server they are connected to or if something has changed on the server. Changes should be performed on the redundant server as well.)

4 - Open a message session from the calling process to the client process. The Name and Fn are ignored in this mode. The message session opened in this mode does not need to call MsgClose.

Fn:

The message post function, that is a callback function for the message event. Set Fn to 0 if no event callback function is required.

sClusterName:

The name of the cluster the server being communicated with belongs to, this is used when mode is 0, 1 or 3. This is not required if the client is connected to only one cluster containing a server of the type set in the name parameter.

Return Value

The message handle, or -1 if the session cannot be opened. The message handle identifies the table where data on the associated message is stored. The exception to this is mode 1 where the handle 4096 will be returned if the session can be opened.

Related Functions

MsgClose, MsgRead, MsgWrite, MsgRPC

Example

INT hClient = -1;

INT hServer = -1;

// Open message session on the client, connecting using the

//existing message session to the current Alarm server

FUNCTION

MsgClientOpen()

INT nState;

hClient = MsgOpen("Alarm", 0, MsgPostClient);

IF hClient <> -1 THEN

nState = MsgState(hClient);

SELECT CASE nState

CASE 1

Prompt("Client Message session is online!");

CASE -1

Prompt("Client Message session handle is invalid!");

CASE 0

Prompt("Client Message session is offline!");

CASE 2

Prompt("Client Message session is connecting!");

CASE 3

Prompt("Client Message session is disconnecting!");

CASE ELSE

Prompt("Client Message session has unknown status!");

END SELECT

ELSE

Prompt("Client Message session could not be opened!");

END

END

// Open message session on the server

FUNCTION

MsgServerOpen()

INT nState;

hServer = MsgOpen("Alarm", 1, MsgPostServer);

// Opening a server connection will result in returning 4096 (if successfully opened)

// and should not be checked via MsgState

IF hServer <> 4096 THEN

ErrLog("Server Message session could NOT be opened!");

ELSE

ErrLog("Server Message session is online!");

END

END

// This function is called when the server receives a message from

//the client

INT

FUNCTION

MsgPostServer()

INT Type;

INT hCurr;

STRING Str;

// Record the returned handle from the read to use it for the write

hCurr = MsgRead(Type,Str);

ErrLog("Server recieved Message: Type = "+Type:###+" Str = "+Str);

MsgServerWrite(hCurr);

RETURN 0;

END

// This function is called when the client receives a message from

//the server

INT

FUNCTION

MsgPostClient()

INT Type;

INT replyHandle;

STRING Str;

MsgRead(Type,Str);

Prompt("Client recieved message: Type = "+Type:###+" Str = "+Str);

RETURN 0;

END

// Write a message to the server

FUNCTION

MsgClientWrite()

Prompt("Client Write");

MsgWrite(hClient, 1, "MyClientMessage");

END

// Write a message to the client

FUNCTION

MsgServerWrite(INT hCurr)

MsgWrite(hCurr, 1, "MyServerMessage");

END

See Also

Task Functions