How the Client Works

The monitor gets information to the Monitor Server. The setup is very similar to the super communication. In fact, the code base is identical for the two of them. In fact, they are so similar, I'll not repeat the graphics and other amazing stuff you can find on the page that describes the supervisor-client communication theory of operation.

The first thing you must do is decide what data to furnish and what format to use.

Programming a Client

First, you must prepare your project. In Visual Source Safe, from the $/l3_super project, share the l3_communication_base project with your project. If you've already done that (say for supervisor communication), then you need to make sure all the files are present. A lot of new files were created while adding the monitor callbacks, and many old ones were changed. You must also share the ErrorReporter project. Add these to your workspace and make sure they build correctly. If you are going to use the l3_monitor_objs (see below), then also share the l3_monitor_util project.

Next, make sure the client you are building has its Dependencies set correctly (to include the two projects you've just copied in), and also make sure that the C++ include paths are set correctly so the compiler will search the l3_communication_base project (ErrorReporter is not required).

Next, decide what kind of a callback you'd like, and write a basic one (click on the link to see how). You have three options when writing the monitor call back.

1. Use only l3_monitor_objs These objects allow you to write code similar to below:

   l3_monitor_obj_op<int> my_counter ("a_counter");
   
   my_counter=10;
   my_counter+=10;

   And have them automatically dumped to the Monitor Server in the correct XML format. This is useful if all of your monitored items fit into this model of a variable that is constantly updated to keep track of some item.

2. Use only a direct callback At its simplest level, the Monitor Server's callback just returns a string. You can fill it with anything you want (but it really should be XML). This method is best when your monitor data requires some assembly that you'd rather not do in real-time, or if you've already got counters and you don't want to change them, just fetch them and send them off to the Monitor Server.
3. Use a combination of the two You can implement the callback yourself, and, as one of the things you do during the callback, you can grab XML data for l3_monitor_obj's in your program.

Once you've created the callback interface, you create the monitor thread, and start it on its way. To do this, first include the file l3_monitor_com.hpp, and then just create it:

l3_monitor_com mon_connection ( client_type, &my_callback, monitor_server );

clinet_type is the type of the client, like "VRC", "ETG_SB", etc. my_callback is the callback interface you created in the previous line. monitor_server is a C++ string that contains the location of the monitor machine. If you leave it blank, or don't even include it on the line, it will default to the machine d0l3mon.fnal.gov.

You're done. The rest of your program shouldn't need to change, other than those changes you have to add to allow the monitor callback to get at your data! Whenever monitor server requires some data, it will run your callback and return the XML data to whichever Monitor Server client has requested it.

Notes on Running

Simplest way to test is use a local JavaScript to access your monitor data. There are quick instructions on how to do this; it is very useful especially when you are getting up and going.

When you run you can expect some messages to be printed out to a console window. These are the monitor subsystem attempting to connect to the Monitor Server. If no monitor machine can be connected to, it is likely you'll get these messages once every 10-30 seconds. Also, if the Monitor Server crashes, these messages will start up again until the monitor machine returns and a connection can be reestablished.

Note that the callback occurs in a different thread than your main program. Thus, you must be aware of multi-threaded issues when collecting monitor data. It is possible, for example, that a std::list may not be in a consistent state unless protected by a critical section or mutex!