Watching Your Application

As discussed in the previous section, a common way to monitor your TIBCO SmartSockets application is by watching the items of interest. When an item of interest changes, your program can be notified instantly. The first example program of this lesson shows how to watch the /tutorial/lesson5 subject. Whenever a process starts subscribing to or unsubscribing from the /tutorial/lesson5 subject, the new program, watchsub.c, outputs information about the current subject membership of /tutorial/lesson5.

Step 1

Before proceeding, copy the watchsub.c program. You also need to copy receive.c and send.c from the same directory. Under Windows you also need to copy the makefiles watsw32m.mak, sendw32m.mak and recvw32m.mak into your working directory.

These sending and receiving programs are modified so that they continue to run until you manually interrupt them (by entering Ctrl-c).

Use the watchsub.c program to monitor the subject activities of the RTclients. The contents of the watchsub.c program are:

  /* watchsub.c - Output info whenever there is a change in subject  
                    count */ 
    /* $RTHOME/examples/smrtsock/tutorial/lesson5/watchsub.c */ 
 
1   #include <rtworks/ipc.h> 
2   static void T_ENTRY DefaultCallback(T_IPC_CONN conn, 
                T_IPC_CONN_PROCESS_CB_DATA data,      T_CB_ARG arg); 
3   static void T_ENTRY ProcessSubjectStatus(T_IPC_CONN conn, 
                T_IPC_CONN_PROCESS_CB_DATA data, T_CB_ARG arg); 
 
 
    /* =========================================================== */ 
4   static void T_ENTRY DefaultCallback 
    ( 
     T_IPC_CONN conn, 
     T_IPC_CONN_PROCESS_CB_DATA data, 
     T_CB_ARG arg 
    ) 
    { 
5   TipcMsgPrintError(data->msg); 
    } /* DefaultCallback */ 
 
    /* =========================================================== */ 
    /* ProcessSubjectStatus - callback to process a MON_SUBJECT_SUBSCRIBE_STATUS message */ 
6   static void T_ENTRY ProcessSubjectStatus 
    ( 
     T_IPC_CONN conn, 
     T_IPC_CONN_PROCESS_CB_DATA data, 
     T_CB_ARG arg 
    ) 
    { 
7    T_IPC_MSG msg = data->msg; 
8    T_STR subject_name; 
9    T_STR *subscribe_client_names; 
10   T_INT4 num_subscribe_clients; 
11   T_STR start_client; 
12   T_STR stop_client; 
13   T_INT4 n;   
 
    /* Set current field */ 
14  TipcMsgSetCurrent(msg, 0); 
 
    /* Get the fields from the message */ 
15  TipcMsgNextStr(msg, &subject_name); 
16  TipcMsgNextStrArray(msg, &subscribe_client_names, 
                        &num_subscribe_clients); 
17  TipcMsgNextStr(msg, &start_client); 
18  TipcMsgNextStr(msg, &stop_client); 
 
    /* Print out the new information received about the subject */ 
19  TutOut("Received change notice for subject <%s>\n", 
           subject_name); 
20  TutOut("Number of clients subscribed to <%s> = %d\n",  
           subject_name, num_subscribe_clients); 
21  for (n = 0; n < num_subscribe_clients; n++) { 
22    TutOut(" [%d] %s\n", n, subscribe_client_names[n]); 
    } 
 
23  TutOut("Client who just subscribed:   %s\n", start_client); 
24  TutOut("Client who just unsubscribed: %s\n", stop_client); 
25  TutOut("==================================================\n"); 
   
  } /* ProcessSubjectStatus */ 
 
   /* =========================================================== */ 
26 int main(int argc, char **argv) 
   { 
27   T_IPC_MT mt; 
 
     /* Set the project name */ 
28   TutCommandParseStr("setopt project smartsockets"); 
 
     /* Connect to RTserver */ 
29   if (!TipcSrvCreate(T_IPC_SRV_CONN_FULL)) { 
30      TutOut("Could not connect to RTserver.\n"); 
31      TutExit(T_EXIT_FAILURE); 
     } 
 
     /* Create callback to process MON_SUBJECT_SUBSCRIBE_STATUS messages */ 
32   mt = TipcMtLookupByNum(T_MT_MON_SUBJECT_SUBSCRIBE_STATUS); 
33   TipcSrvProcessCbCreate(mt, ProcessSubjectStatus, NULL); 
 
     /* Setup callback to receive unwanted message types */ 
34   TipcSrvDefaultCbCreate(DefaultCallback, NULL); 
 
     /* Start watching who is subscribed to /tutorial/lesson5 
        subject */ 
35   TipcMonSubjectSubscribeSetWatch("/tutorial/lesson5", TRUE); 
 
     /* Read messages from RTserver and call the callbacks */ 
36   TipcSrvMainLoop(T_TIMEOUT_FOREVER); 
 
     /* Disconnect from RTserver */ 
37   TipcSrvDestroy(T_IPC_SRV_CONN_NONE); 
 
  } /* main */

Line 35	Turns on watching for all processes subscribed to the `/tutorial/lesson5` subject. Whenever a process subscribes to or unsubscribes from the `/tutorial/lesson5` subject, RTserver asynchronously sends a T_MT_MON_SUBJECT_SUBSCRIBE_STATUS to our subject activities program.
Lines 32-33	Set up a callback (ProcessSubjectStatus) to process a message of this type when it arrives. The callback function ProcessSubjectStatus then prints out the information contained in the message.
Lines 15-18	Retrieve the results (in ProcessSubjectStatus) from the returned message.
Lines 19-25	Output the fields from the message.

A T_MT_MON_SUBJECT_SUBSCRIBE_STATUS message is sent by RTserver (initiated by calling TipcMonSubjectSubscribeSetWatch) each time there is a change in subject membership for /tutorial/lesson5. This means that initially, if there are no processes subscribed to the subject, no message is sent by RTserver to watchsub.

Step 2

Step 3

	On platforms that support both 32- and 64-bit, use the rtserver64 command to run the 64-bit RTserver.

To see how the subject activities program, watchsub.c, works, you need three separate windows; one each for watchsub.c, receive.c and send.c. In one window, compile and link watchsub.c, and then start executing it:

You do not see any new output in the window where you are running the subject activities program because there are no changes in subject membership. In fact, there are no processes currently subscribed to the /tutorial/lesson5 subject.

To see the callback function ProcessSubjectStatus invoked in the subject activities program, you need to start a process that subscribes to the /tutorial/lesson5 subject.

Step 4

In a separate window, compile and link the receive.c program. Then execute it:

Upon starting the receiving program, you should see this new output in the window where the subject activities program is running:

Received change notice for subject </tutorial/lesson5> 
Number of clients subscribed to </tutorial/lesson5> = 1 
   [0] /_workstation1_5622 
Client who just subscribed:   /_workstation1_5622 
Client who just unsubscribed:  
======================================================

This information tells you there is now one RTclient subscribed to the /tutorial/lesson5 subject. The new process that just subscribed is /_workstation1_5622 (note that this name is different on your system). The clients are identified by the setting of their Unique_Subject option. In the sample programs, you are not explicitly setting the value of this option. Thus, the option defaults to a generated value consisting of a slash, an underscore, followed by the node name, followed by an underscore, followed by the process ID (/_Node_Pid).

Step 5

In a separate window from where the receiving program and the subject activities program are running, compile and link the send.c program. Then execute it:

When the sending program is executed, you should see the receiving program print out the contents of a "Hello World!" INFO message the sending program transmits over and over:

Text from INFO message = Hello World! 
Text from INFO message = Hello World! 
...

Note that there was no new output in the subject activities program window. This is because the sending program does not subscribe to the /tutorial/lesson5 subject; it just publishes messages over and over, with a one second delay.

Step 6

Step 7

Now start a second instance of the receiving program in the same window where the sending program was running:

Received change notice for subject </tutorial/lesson5> 
Number of clients subscribed to </tutorial/lesson5> = 2 
   [0] /_workstation1_5622 
   [1] /_workstation1_5624 
Client who just subscribed:   /_workstation1_5624 
Client who just unsubscribed:  
======================================================

This indicates there are now two RTclients subscribed to the /tutorial/lesson5 subject: /_workstation1_5622 and /_workstation1_5624. The most recent one to subscribe to the subject is /_workstation1_5624.

Step 8

Now go to the window where you just started the receiving program and stop the program by typing Ctrl-c. You see this new output the subject activities program window:

Received change notice for subject </tutorial/lesson5> 
Number of clients subscribed to </tutorial/lesson5> = 1 
   [0] /_workstation1_5622 
Client who just subscribed:    
Client who just unsubscribed: /_workstation1_5624 
======================================================

Notice that there is now only one process subscribed to /tutorial/lesson5, and the process that just unsubscribed was /_workstation1_5624. It is important to remember that RTserver sends notification when RTclients unsubscribe to a subject, as well as when they subscribe.

You should also notice how quickly the subject activities program picks up and sends its notifications about changes in subject membership. It occurs almost instantaneously. This instant notification capability can be used to implement hot failover of RTclients. An example of this is presented in Guardian (Hot Backup Manager) Source Code in the chapter on project monitoring in the TIBCO SmartSockets User’s Guide.

Step 9

Go back to the window where the receiving program is running and stop the program by typing Ctrl-c.

The subject activities program notifies you that no processes are subscribing to /tutorial/lesson5:

Received change notice for subject </tutorial/lesson5> 
Number of clients subscribed to </tutorial/lesson5> = 0 
Client who just subscribed:    
Client who just unsubscribed: /_workstation1_5622 
======================================================

This information could be used in a program that is publishing messages, to prevent it from sending messages if there are no processes subscribed to the subject. For example, you could modify your sending program to watch, and keep a count of, the RTclients subscribed to the /tutorial/lesson5 subject, and if no processes are subscribed to /tutorial/lesson5, then not call TipcSrvMsgWrite. Leave the subject activities program running in its window; it is needed in the next set of exercises.

Uniquely Identifying an RTclient

In our previous examples, the subject activities program was printing information about the RTclients by using their unique subject. Every RTclient has a unique subject, and it is typically used as a way to send a message to only that process. The unique subject of a process is determined by the setting of the Unique_Subject option.

The Unique_Subject option specifies a unique subject that a process automatically starts subscribing to when it creates a connection to RTserver. RTserver does not allow multiple processes to have the same value for the option Unique_Subject. As described earlier, the default value for Unique_Subject is _Node_Pid, where Node is the network node name of the computer on which the process is running, and Pid is the operating system process identifier of the process.

In the examples shown earlier, Unique_Subject was not set and the option defaulted to values such as _workstation1_5622, indicating the process is running on workstation1 and its process ID is 5622.

Step 10

To see how you can use the Unique_Subject option to uniquely identify a process, edit the receive.c program to add the following line. This defines the Unique_Subject to be /lesson5/receiver, before the call to TipcSrvCreate in the main program:

TutCommandParseStr("setopt unique_subject /lesson5/receiver");

You must add it before the call to TipcSrvCreate because the value of the Unique_Subject option is sent to RTserver when a connection is created.

Step 11

Now, save your changes, and compile, link, and start the new receive.c program:

Upon starting the receiving program, you should see this output in the window where you started the program:

Message from RTserver: Connection established. 
Start subscribing to subject </lesson5/receiver>.

You should now see this new output in the window where the subject activities program is running:

Received change notice for subject </tutorial/lesson5> 
Number of clients subscribed to </tutorial/lesson5> = 1 
   [0] /lesson5/receiver 
Client who just subscribed:   /lesson5/receiver 
Client who just unsubscribed:  
======================================================

Note that the process is now identified by its unique subject, /lesson5/receiver. This is much easier to understand than our previous default values such as /_workstation1_5622.

It is strongly recommended that you explicitly set the Unique_Subject option. It is the primary way you have for uniquely identifying (and locating) the RTclients when using TIBCO SmartSockets. This option must be set if you are using the guaranteed message delivery feature of TIBCO SmartSockets, which is described in Lesson 6: Fault Tolerance.

Step 12

Go to a window that is not running the receiving program or the subject activities program and try to start a second instance of our receiving program:

Connecting to project <smartsockets> on <-node> RTserver using 
local protocol 
RTserver denied access. 
Message from RTserver: Client name </lesson5/receiver> is not 
unique. 
Could not connect to RTserver!

There is a second benefit of explicitly setting the Unique_Subject option. It is a security feature. RTserver keeps track of this information and denies a process in any project that tries to connect with a unique subject that is already in use.

Before moving on to our next set of exercises in this lesson, kill all the programs that are still running; enter Ctrl-c in the windows where the subject activities, receiving, and sending programs are running.