Kmax General

Kmax/KmaxNT Compatibility

Kmax Instrument Control

Kmax Event Stream and Event Buffer

Kmax Histogram Widgets

Kmax File I/O

Kmax Data Analysis

Runnables

Kmax CSL

---

1.0 Kmax General

1.1 What is Kmax
Kmax is multiparameter, list-mode data acquisition and process control environment.  Kmax can be used to configure and operate data acquisition and process control systems which use modular instrumentation.  Kmax provides high-level features for data display and analysis.  The Kmax environment can be configured to operate remote hardware via it's powerful client/server features. 

---

1.2 What is required to run Kmax
Kmax will run on Windows XP, Mac OS X 10.3 and Linux.  A Java virtual machine is required, version 1.4.2 or above.  A high-end workstation is recommended.

---

1.3 What type of instrumentation does Kmax support?
Kmax supports most standard modular instrumentation, including CAMAC, VME, GPIB, RS232, PCI expansion cards etc.  In fact, Kmax can control and interact with any hardware for which native or java drivers are available.  Support for a particular module depends on the availability of a specific driver for that module or instrument interface.  Kmax can communicate with embedded systems via the client/server architecture.  A Kmax server process must be written for the target system.

---

1.4 What device interfaces are supported by Sparrow?
Currently, Kmax drivers are provided for:
SPARROW SCM-301, SCSI CAMAC Crate Controller (Mac OS X, Windows NT/2000, and Linux).
and
Jorway 73A, SCSI CAMAC Crate Controller (Mac OS X, Windows NT/2000, and Linux).
Other drivers can be special ordered from Sparrow Corp.

---

1.5 Can I get a demonstration version of Kmax?
Yes.  Go the "Downloads" page on the Sparrow web site and follow the instructions for downloading and installing Kmax.  The default license is a demonstration license.  You may also request an full evaluation license by contacting Sparrow Corp.

---

1.6 How do I determine the Machine ID for my computer?
Open the  "About Kmax..." item in the "Help" menu ,  then click on the License tab.  The machine ID is  displayed  with the other  licensing information.  Note that the ID may be different for different users on the same machine.  If you move Kmax to another computer, you will need a new license password.  Contact Sparrow Corp. for additional information.

---

1.7 Do I need a separate license to run the Kmax client-server configuration?
You can run the Kmax server process in the demonstration mode (with a demonstration license) so you will not need a second full license to utilize the client-server features of Kmax.  A source code example for a stand-alone Kmax server is also provided for custom or embedded applications.

---

1.8 Do I need a module description resource (MDR) for every instrument or module that I want to use?
You must have the MDR and the associated driver for any module that interfaces directly with the computer.  MDRs for slave modules (e.g., CAMAC, VME, PXI, etc.) that only communicate with a controller module via the instrument bus do not require an MDR.  If no MDR is available for the module that you want to use, just leave the slot blank and enter the  CAM (common addressing model)  address  by hand.  MDRs are just text files and are generally easy to write.  Associated drivers must often be native code modules.  The MDR is used to locate, load and initialize the low-level driver for the module.

---

1.9 How do I adjust the memory used for the Kmax application?
Kmax runs in the Java virtual machine.  The VM is usualy responsible for assigning the initial memory partition and expanding the partition if Kmax needs more memory.  If you are running Kmax from the command line, or from a batch (.bat) or shell (.sh) file, you can specify the initial memory or maximum memory using the java command -mx, -Xms and -Xmx option switches.  See the documentation for the Java VM for more information.  (Type "java -help" or "java -X" on the command line for an explanation.)

---

1.10 I get error messages when I try to run Kmax for the first time or when I try to compile a toolsheet.  What is wrong with my system?
The most probable causes are that the SDK is not properly installed, the path variable does not contain the directory where the javac command resides, or you may not have read/write permissions for some directory or file.

Try logging in as root (on linux) or as administrator (on Windows).  If this solves the problem, then you need additional permissions.  Check that the path variable is properly modified to include the /bin directory where the javac executable is located.

If you see a message similiar to the one below:


It is an indication that the Kmax process cannot find the javac tool specified in the "Toolsheet Properties" dialog under the "Compiler" tab.

---

2.0 Kmax/KmaxNT Compatibility

2.1 What is the difference between Kmax and KmaxNT?
Kmax version 1.x - 6.x is designed to operate under the original (classic) Macintosh OS.   KmaxNT runs under Windows NT/2000/XP  The file formats of these versions are not compatibile.  Kmax 7.x and above runs in the Java VM on on Windows XP, Mac OS X 10.1 and Linux.  The data and toolsheet formats for a specific version of Kmax ( > 7.x) are cross-platform compatibility. 

---

2.2 What is the difference between Kmax 8.x and Kmax 7.x?
The driver model in Kmax version 8.x has been significantly upgraded and improved.  Toolsheets written for version 8.0 that use the IO interface are not generally compatible with Kmax 7.x.  Consult the "Java Interfaces" documentation available with the Kmax distribution.

---

2.3 Can I read Kmax instruments files with KmaxNT?
No. The file formats are quite different; however, by saving the CSL scripts as a text file, they can be ported to KmaxNT. The scripts will need minor modifications to conform to the KmaxNT syntax. Histogram data may be ported by saving it "as text" and adding the word 'TEXT" on the first line. In this format, the file can ne read by KmaxNT.   

---

3.0 Kmax Instrument Control

3.1 Why will Kmax not talk to my instrumentation module?

1. Make sure the proper cables are used.
2. Some CAMAC controllers must have a lemo cable installed on the front panel from the "Request" to the "Grant In" connectors.
3. VME instruments require that the controller slot be set properly.
4. Make sure that the device ID and the bus ID are correct in the device pane of the toolsheet and that they are set properly in the hardware.
5. Make sure that the remote/local option is properly selected and that the remote address is correct if a remote connection is desired.
6. Check the messgae panes for information if the connection fails.

 

---

3.2 Does Kmax support RS-232?
Support for serial connections like RS-232 and RS-422 will depend on the specific platform.  Third party support should use the standard Kmax instrument driver API.  

---

3.3 What is the difference between an MDR and a Kmax instrument driver?
An MDR (Module Description Resource) is just a mini database with text information used to describe the characteristics of an instrument or device.  An MDR can be provided for any instrument module.

A Kmax instrument driver provides the low-level, native code used to communicate between the device/interface and the computer. The MDR for the controller module identifies the driver component which is loaded when the instrument is compiled.   Both are necessary in order to communicate with a external device. MDRs for instrumentation slave modules are not necessary in order to communicate with them via the intrface module, but they make the system easier to setup and use.

---

3.4 Why does the operating system recognise the SCM 301 as a JORWAY 73A during the boot process?
The SCM_301 is functionally identical to the Jorway 73A and uses the same firmware.  An SCM 301 module will always detect as a Jorway 73A.  This is normal and does not indicate an error coondition.

---

3.5 When an SCM 301 CAMAC controller module is connected to the computer and the system is started, the OS requests a driver but there is no driver in the Kmax distribution that is appropriate for the module.  Where is the driver?
Kmax avoids modifying the system directories by loading all its drivers from the Kmax directory at compile-time.  When Windows XP boots the Plug-N-Play (PNP) process detects new hardware and starts the "Found New Hardware Wizard" to load the appropriate drivers.  Just cancel the dialogs and continue.  Kmax will load the appropriate drivers when you compile a toolsheet that needs them.   On Windows-based workstations, you will need to make sure that the WINASPI layer is properly installed.  See Adaptec's website for installation instructions.

---

3.6 An SCM 301 CAMAC controller module is connected to the computer but when the SCM301_Test toolsheet is compiled, an error is reported similiar to the following:


What do I need to do to get the test toolsheet to compile?

In order to compile properly, the toolsheet must load and initialize the driver for the controller.  Consider the following issues:

System:
    If you are using a Windows computer, insure that you are using a wnaspi-compatible host adapter and that the WINASPI layer is properly installed.  The WINASPI drivers can be downloaded from ADAPTEC's web site and installation can be verified using the tools available in the download.

At power-up, Windows may display a dialog asking you to install a driver for the controller.  Do not attempt to load a driver through the plug-and-play dialog.  Just cancel the dialog.  Kmax will load the appropriate driver(s) when the toolsheet is compiled.

Hardware:
    Insure that the controller is properly configured.  Also verify that the SCSI ID on the controller is set to 5, the test default ID.  If the controller is being used in R/G mode, insure that the R/G lemo cable has been properly installed.

Kmax:
    Insure that Kmax is installed with the "Extensions" folder in the same directory with the Kmax8.jar/Kmax8.app files.  Make sure that the "Extensions" folder has not been modified.

Kmax toolsheet:
    Insure that the the device ID is set to 5 (the test default) in the device pane of the toolsheet.  On the Mac, just set the Bus ID and the Device ID to -1, if you want the driver to find ny controller available.

---

3.7 Do I need to use a real-time operating system in order to get high performance when implementing  Kmax server process in a VME system?

In many cases the additional complexity, cost, time, etc., is not worth the benefit, if any, of using a real-time OS (RTOS).  If you really need the fine-scale scheduling, predictable latency, etc., of an RTOS, then that is what you need.  Sysems based on the client/server architecture of Kmax don't care how the server is implemented as long as the appropriate commands are implemented.

---

3.8  I am using a VME system with a Kmax embedded server.  Each time the VME has data ready, the server sends the SRQ message and the client reads it out.  Everything works fine, but the performance is not as good as I expected.  How can I get better performance??

Generally speaking, to get the best performance, you should keep the rate of client/server transaction as low as possible and the transfer block size high.  Let the VME do what it does well - handle the VME data IO.  Let the workstation do what it does well - process control and command and display data buffers.

Systems designed to have a client workstation respond to every event generated by the VME system, generally are limited to a few hundred events per second.  This is one reason why VME systems usually have an embedded processor and and embedded data acquisition process -- to get higher performance.  In the design of your DAQ process on the VME CPU you should implement a buffering strategy using separate processes or threads for data acquisition and client/server IO. 

A data acquisition process on the VME can service the raw DAQ events and build event buffers in the VME memory.  This should proceed very fast.  When the VME data buffer is full (or based on some other criteria, e.g., timers, client requests, etc.), the DAQ process can signal the embedded server process to send the SRQ message tot he client (which is running on the host workstation).   The client workstation can read out the data as a large event block for processing.  During readout the DAQ process continues to build the next event buffer.  After readout, the workstation client processes the event block.  By keeping the number of client/server transactions to a few per second, but making the transfer blocks large you can get high throughput, and parallel processing in the VME and the client.

---

4.0 The Kmax Event Stream and Event Buffer

4.1 How do I change the size of the Event Buffer and Event Data File?

The sizes of the Event Buffer and the Event Data File may be changed by selecting the "Toolsheet Properties.." item from the Edit. The Event Buffer size is specified in 4-byte words and the Event Data File size is specified in bytes.

---

5.0 Kmax Histogram Widgets

5.1 How do I use the histogram widget to display 3D surfaces?

The 3D surface plotting option is not yet available in Kmax 7.x.  It will be implemented in an upcoming release.
 

---

6.0 Kmax File I/O

6.3 How can I save the Event Data File as ASCII?

Select the "Text Format" item from the "Event Files" section of the "Toolsheet Properties..." dialog.  The event data will be saved to the event data file  in text format.  Text formated event files, however, cannot be processed using the standard built-in mechanisms of Kmax.  They can be useful, when the data will be analysed by other software.
 

---

6.4 What is the Event Data File format?

The Event Data File format is a binary format specific to Kmax.  It is described in the Kmax Manual.
 

---

6.5 Can I save Kmax Event Buffers in zero suppressed format?
There is no built-in mechanism in Kmax for writing zero-suppressed event files. Over the years we have discussed doing this and continue to consider the options. Unfortunately, there is no format for zero-suppressed data in common use. The structure of headers and the size of tag and data words are the most common differences. Several module venders have implemented zero-suppression in hardware, but different formats have been used. If you save the Event Buffers with zeros suppressed, you will need to read and analyze the files manually.  This can be done using the Kmax FILE variable type.
 

---

7.0 Kmax Data Analysis

7.1 How can I get information about my histogram data such as FWHM, total counts, etc.?
Information about the histogram data, such as the plot sum, area, centroid, FWHM, plot max, plot min, and total counts, may be obtained from the histogram object with the following yntax:

value = histObj.getRegionSum(regionName);
value = histObj.getRegionArea(regionName);
value = histObj.getRegionCentroid(regionName);
value = histObj.getRegionFWHM(regionName);
value = histObj.getRegionMin(regionName);
value = histObj.getRegionMax(regionName);

If regionName is null, the calculation will use the region defined by the current cursor settings. The return value may be an integer, a double, or an array.  Check the Kmax Java interfaces documentation to see now to get a object reference to a Kmax histogram.
 

---

8.0 Kmax Runnable Jar Files

8.1 I am exporting a toolsheet that connects to a Kmax server.  Kmax requires the server IP address to be entered in the device pane, but this cannot be edited in the runnable.  The problem is that I don't know the server address in advance.  How can I set the server address in a Kmax runnable after it is exported.?
Just leave the field blank.  When the runnable is executed the user will be prompted for the server address.

---

9.0 Kmax Command Sequence Language (deprecated)

9.1 How can I obtain the information in a text widget using Command Sequence Language?
The widget properties syntax provides a easy way to extract the full text or individual lines of text from text widgets.

SET #StringVar# TO {"WidgetName"}.TEXT
SET #StringVar# TO {"WidgetName"}.FIRSTLINE

Will return the full text or the first line of text in the widget named "WidgetName" in the #StringVar# variable.  Properties for line count and other characteristics are also available.
  

---

9.2 Can I use Hex numbers in Command Sequence Language?
Yes, hex numbers are distinguished by placing a $ in front of the number. For example:
DATA = $FFFF

Decimal numbers may be converted to hexidecimal strings by using the HEX qualifier in the SET command.  For example:

SET #StringVar# TO HEX #Data#

---

9.3 How do I break out of a CSL loop without forcing Kmax to quit?
Press CTRL-ALT ESCAPE to break ou of a CSL  FOR or REPEAT loop.  You may have to hold the keys down for  several seconds.

---

9.4 How can I read data from my instument module?
Data is read-from or written-to instruments and interfaces by executing WRDIO, BLKIO, BUFIO, or STRIO commands.  External commands (components) may also be used to preform IO to hardware, but this is rare.

The WRDIO command executes single reads, writes or command (dataless) operations.
The syntax for the WRDIO command is:
WRDIO < #DeviceName#,  #Address#, #SubAdd#, #FCode# > #Data#

The BLKIO command executes block transfers to or from a Kmax histogram widget.
The syntax for the BLKIO command is:
BLKIO < #DeviceName#,  #Address#, #SubAdd#, #FCode# >  #HistogramName# #CountVal#

The BUFIO command executes block transfers into the Kmax event data buffer.  The BUFIO command cannot be used to write data.
The syntax for the BUFIO is:
BUFIO < #DeviceName#,  #Address#, #SubAdd#, #FCode# > #CountVal#  #SizeVal#

---

9.5 Why is the data read from the device not sorted into my histograms?
When using CSL. you must make sure your histogram widgets are defined with the proper event type and parameter number. Also make sure sorting is turned on by selecting the option from the "Toolsheet Properties..." dialog pane.

---

9.6 Can I insert data into the event data stream from within a CSL loop?
Data can be written to the Kmax event data buffer by using the WRDIO and BUFIO commands.  You can also use the "WRITE #Data# AS PARAMETER" command.  You cannot insert data into the event stream (write to the event data buffer) from a CALLed sequence.

---

9.7 How are the Q and X bits returned from a CAMAC cycle in Command Sequence Language?
This will depend on the CAMAC driver of course but the usual mechanism, when using CSL, is to return error codes from the Kmax device driver in the %_STATUS variable.  You can test, display or print the value of %_STATUS after each WRDIO command to determine whether an error code was returned. The information that can be returned depends on the type of CAMAC controller you are using. The usual meaning of the bits in the STATUS variable for most controllers is shown below. If a bit is set it indicates the following condition:
1--No Q
2--No X
3--Off Line
4--NoDriver
5--
6--Time Out
7--
8--Protocol Error
 

---

9.8 How can I open an ASCII file as a histogram from CSL?
Insure that the text file has the proper format (see the Kmax manual).  Use the "Import.." item from the histogram context (popup) menu.  You can also use command sequences to automate opening histogram data. Use the

   OPEN "dataPath/dataName" IN "HistName".

See the Kmax manual for more detail.

---

9.9 How can I open an Event Data File from CSL?
Use the
   
    OPEN "EventFilePath"

command.  See the Kmax manual for more information.

---

9.10 How do I read the Event Buffer manually from CSL?
Use the object-data-array syntax:

{"%_BUF1"}[index] - for the primary buffer and
{"%_BUF2"}[index] - for the secondary buffer.

For examle:

     DATA = {"%_BUF1"}[15]

Gets the 15th integer from the primary buffer.  See the Kmax manual for the buffer storage format.7.1 How do I perform a guassian fit on my data from Command Sequence Language?
Use the PEAK_FIT CSL Extension to perform a guassian fit on your data. This CSL Extension is part of the standard Kmax distribution. 

---

9.11 How do I perform a guassian fit on my data from CSL?
Use the PEAK_FIT CSL Extension to perform a guassian fit on your data. This CSL Extension is part of the standard Kmax distribution. 

---

9.12 In CSL, how can I get information about my histogram data such as FWHM, total counts, etc.?
Information about the histogram data, such as the plot sum, area, centroid, FWHM, plot max, plot min, and total counts, may be obtained from CSL in two different ways.  The most standard is to use widget properties syntax:

Max = {"HistName"}.MAX or
LCursor = {"HistName"}.LCUR

The second mechanism is to use CSL commands
 
GET SUM #Sum(IntVar)# IN #data#
GET AREA #Area(IntVar)# IN #data#
GET CENTROID #Centroid(RealVar)# IN #data#
GET FWHM #FWHM(RealVar)# IN #data#
GET MAX #Max(IntVar)# IN #data#
GET MIN #Min(IntVar)# IN #data#
GET TOTAL #Total(IntVar)# IN #data#