RCS/NML Diagnostics Tool Instructions

Introduction

The diagnostic tool allows programmers to see the current command and status of every module in his controller and to send commands to any module. The tool determines which commands each module will accept and the parameters of each status and command message using some of the C++ header files the application is expected to be built with and an architecture file to provide information on how the controller fits together.

The applet can be viewed in an offline mode here. To see it connected to a running controller you will need to contact Will Shackleford to start one of our controllers.

Creating the Architecture File

The architecture file is a simple text file that provides information on where the header files are how the modules are connected. The following are sample architecture files.

The files consist of a series of module blocks ( one for each module in the controller). Each module block has a module name followed by a series of module attributes separated by semi-colons and surrounded by braces.

MODULE_NAME{ MODULE_ATTRIBUTE=value; MODULE_ATTRIBUTE=value; MODULE_ATTRIBUTE=value; } 

The following are the currently defined module attributes.

child

cmd_buffer_name

cmd_configuration_file

cmd_port

cmd_buffer_number

cmd_types_file

stat_buffer_name

stat_configuration_file

stat_port

stat_buffer_number

stat_types_file

stat_types_file

predefined_types_file

SourceCodeDirectory

Special Rules for the Header Files

1. #include directives are ignored. Use the predefined_types_file attribute in the architecture file instead.
2. #if directives are considered false unless JAVA_DIAG_APPLET_FORCE_TRUE is defined.
3. Only one variable should be defined on a line.
4. Surround things that should not be parsed by the tool with #ifndef JAVA_DIAG_APPLET and #endif. This includes:

• Multiple line functions and macros. (Most functions don't belong in the header file any way.)
• Variables included in the message but not updated in the NML update function.
• Large classes which will never be sent as NML messages and will just slow down the tool and eat up more memory to include.

enum WMSA_MODE { WMSA_AUTO, WMSA_MDI, WMSA_MANUAL };  class NML_WMSA_WM: public NMLmsg { . . . #ifdef JAVA_DIAG_APPLET  WMSA_MODE mode; #else  int mode; #endif . . . 

To use the diagnostics tool you will need a Web browser that supports Java. If the browser has a Just-In Time (JIT) Compiler, the applet will run much faster. When you start the applet, depending on some parameters that are set in the HTML page that includes it, it may automatically load an architecture file and then it may connect to a running controller. Otherwise you would enter the name or URL of an architecture file, to load it and click the checkbox next to "NOT CONNECTED" to connect to the corresponding controller. If the controller is running the checkbox will eventually say "CONNECTED (n out of m)". (n is the number of modules which successfully connected and m is the total number of modules. -- You can check the Java Console or log file for some explanation of why a module didn't connect.)

Here is a screen dump of the top part of the applet:

Under the heading of modules is the list of modules that were loaded. If you select one of the modules the commands that module accepts will be displayed in the list next to it under available commands. Selecting one of the available commands shows the parameters for that command under the command to send. After editing the commands by selecting them and entering appropriate values in the text box below you can send the command by pressing the send usa-button. The current command and status are displayed below that in with all of their parameters. Next there is a checkbox for specifying whether to read the error log. The error log is a special NML buffer that any module can write. The text of messages written there will be appended to the text area beneath the checkbox. Also a special NML_DISPLAY message can be sent to cause the browser showing the applet to automatically jump to a certain URL. This has been used for providing special instructions to an operator. Instead of telling the operator to load tool X with just text it can jump him/her to a page with a picture of the tool and formatted instructions on how to load it.

The hierarchy itself is shown at the bottom of the applet:

Each module lists its current command followed by its status. The modules are color coded.

Handling Some Browser Security Restrictions

Most browsers do not allow applets to connect to hosts other than the one the applet was loaded from. This is a problem since usually the computer running the controller is not a web server. There are 2 work arounds for this problem.

1. Use a browser that allows you to disable the Java Security Manager. Usually these are made for Java developers, such as appletviewer which comes with the Java Developer's Kit (JDK) or by running Internet Explorer from within Visual J++.
2. Use tcpproxy to temporarily turn your host into a Web server. The tcpproxy server allows some port on the remote machine accept requests and respond to replies on a port the machine it is running on.
   

   tcpproxy [local_port] [remote_host] [remote_port]  

   So if I am on the machine cosmos I could run:
   

   tcpproxy 3000 www.isd.mel.nist.gov 80  

   Now if I go to web pages starting with "http://cosmos:3000/" I will see the same web pages I would see at "http://www.isd.mel.nist.gov/" but my browser will believe it loaded the applet from cosmos and allow the tool to connect directly to the controller on cosmos.
3. Use a browser that accepts the Digital-Signature and then gives the user the option of relaxing security. Currently Internet Explorer 3.0 and later and Netscape 4.0 or later accept digital-signatures.

Last Modified: 06/10/98

If you have questions or comments regarding this page or you would like to be notified of changes to the RCS library via email, please contact Will Shackleford at shackle [at] cme.nist.gov (shackle[at]cme[dot]nist[dot]gov)