MsgOpen

Opens a message session with a CitectSCADA 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.

Note: For this function to be successful a user needs to be logged in.

Syntax

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

You should use MsgState() to check the return value of MsgOpen(). 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 CitectSCADA's existing sessions, so you create sessions to the Alarm Server, Report Server, Trend Server, or a named I/O Server.

Name:

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.

ClusterName:

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.

Related Functions

MsgClose, MsgRead, MsgWrite, MsgRPC

Example

INT hClient = -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("Message session is online!");

			//Send a message to the server

			MsgWrite(hClient, 1, "MyMessage");

		CASE -1

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

		CASE 0

			Prompt("Message session is offline!");

		CASE 2

			Prompt("Message session is connecting!");

		CASE 3

			Prompt("Message session is disconnecting!");

		CASE ELSE

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

		END SELECT

	ELSE

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

	END

END

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

//the server

INT

FUNCTION

MsgPostClient()

	INT Type;

	STRING Str;

	MsgRead(Type,Str);

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

	RETURN 0;

END

See Also

Task Functions