MsgOpen | Task Functions

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

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 Citect SCADA's existing sessions, so you create sessions to the alarm server, report server, trend server, or a named I/O server.

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.

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

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.

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.

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