Midas Tcl interface

An interface (called mtcl) has been written to allow a Tcl program to access midas library functions. Midas is a data acquisition system used at Triumf , running under Linux.
 

Source code

The interface is written in c (midas_tcl.c), originally by G.J.Hofman. It has been modified and added to at Triumf.  It is still under development, and will be available under CVS.

To compile mtcl

Requires mtcl =  Tk + Tcl + Blt + midas_tcl.c

cc -g -o mtcl tkAppInit.c midas_tcl.c -L /usr/X11R6/lib/ -ltk -ltcl -lBLT -lX11 -lm -ldl -lmidas -DOS_LINUX -lutil

To run mtcl

Type "mtcl". At the "%" prompt, type the name of your Tcl file.
 
 

<back to top >
 

Introduction

Since Tcl has only one data type (strings) all communication between the Tcl code and the C code is via strings. For each supported command, midas_tcl.c takes the parameters received from the Tcl routine (as a string) and converts it (if necessary) to the correct type to make the appropriate call to the midas library. The result of the command or an error message are returned as a string to the calling routine.

It is best to use "catch" to handle any error returns (see the examples below).

Supported commands :

A limited number of Tcl commands are supported.  All  commands begin with "midas",

e.g.    midas connect_experiment
 

<back to top>

connect_experiment

  A call to connect_experiment followed by a call to get_experiment_database must be made before
   any other midas commands.
 

Usage:

   midas connect_experiment  hostname  expt  client_name
 

Parameters:

   hostname            name of midas host computer
   experiment          name of midas experiment
   client_name         the name that will be given to the client
 

 Returns:

     Integer return code  and   message string

Example:

set host "dasdevpc"
set expt "musr2"
if {  [ catch { midas connect_experiment $host $expt  tcl_UI } result ]} {
    puts stderr "Error after connect_experiment: $result"
}
 

<back to top>
 
 
 
 
 
 
 
 
 

disconnect_experiment

   A call to disconnect_experiment is usually done before exiting.
 

Usage:

   midas disconnect_experiment

Parameters:

none

 Returns:

       Integer return code  and   message string <back to top>

get_experiment_database

   A call to get_experiment_database follows a call to connect_experiment  before
   any other midas commands may be executed. No handler returned, so only 1 database
 can be accessed from Tcl/Tk
 

Usage:

 midas get_experiment_database

Parameters:

none
 

Returns:

  Integer return code  and   message string

Example:

       if {  [ catch {midas get_experiment_database } result ]} {
    puts stderr "Error after get_experiment_database: $result"
}
 

<back to top>
 
 
 
 
 
 
 
 
 

get_value

Gets a single value from a midas key. Any type conversion is handled automatically, and the value is returned as a string.
 

Usage:

midas get_value    key_name

Parameters:

key_name          name of midas odb key ( refers to a single value)

Returns:

  Integer return code  and   message string

Example:

#get a data value from midas:
set odb_item "Runinfo/Run number"
if {  [ catch { midas get_value $odb_item } run_no ]} {
    puts stderr "Error after get_value: $run_no"
} else {
    puts "Present run number: $run_no"
}
 

<back to top>
 
 
 
 
 
 
 
 

get_data


Gets an array of values from a midas key by a call to  midas library routine "db_get_data". The number of elements in the array defined in odb are determined automatically.
 

Usage:

 midas get_data     key_name

 Parameters:

  key_name  (string)    name of midas odb key ( refers to an array)

 Returns:

  Integer return code  and   message string

Example

# get the data from array mdarc_titles
set mdarc_titles "/Equipment/MUSR_TD_acq/Settings/mdarc/mdarc_titles"
if {  [ catch { midas get_data $mdarc_titles} titles ]} {
    puts stderr "Error: $titles"
} else {
    puts "histogram titles: $titles"
}
 

<back to top>
 
 
 
 
 
 
 
 

set_value

Writes a single data value to a midas key. Type conversion is handled automatically. If  the type of the odb key is a string, and length of the data to write exceeds the defined length of the odb key, the data will be truncated.

Usage:

midas set_value    key_name     value

Parameters:

key_name     name of midas odb key ( refers to a single value)
value             value to write

Returns:

  Integer return code  and   message string

Example:

 # write a value
set value 5
set item "/Equipment/MUSR_TD_acq/Settings/rig/archiver/num versions before purge"
 if {  [ catch { midas set_value $item $value } result ]} {
    puts stderr "Error: $result"
}
 

<back to top>
 
 
 
 
 
 
 
 
 

set_data_array

Writes a list of N values to an array starting at index 0. Any type conversion is handled automatically.

If less values are supplied than the array size, the first N elements will be written. If more values are supplied than existing array elements, the extra data will be ignored. If the type of the odb key is a string,  (i.e. the array  elements are strings), and any element of the data to write exceeds the defined string length, the data for that element  will be truncated.

Usage:

 midas set_data_array    key_name  values

Parameters:

key_name          name of midas odb key ( refers to an array)
 value             list of N values to write separated by spaces

Returns:

Integer return code  and   message string

Example:

# Write a  list of values to all (supplied) elements of an array

set mdarc "/equipment/$eqp_name/mdarc"
set mdarc_titles           "$mdarc/histograms/titles"
set value "histo1 histo2 histo3 histo4"
if {  [ catch { midas set_data_array $mdarc_titles $value } result ]} {
    puts stderr "Error: $result"
}
 

<back to top >
 
 
 
 
 
 
 

set_data

Writes the same value to the elements of an array.  Any type conversion is handled automatically.

If less values are supplied than the array size, the first N elements will be written. If more values are supplied than existing array elements, the extra data will be ignored. If the type of the odb key is a string,  (i.e. the array  elements are strings), and any element of the data to write exceeds the defined string length, the data for that element  will be truncated.

Usage:

        midas set_data   key_name  start  end   value
        Parameters:
        key_name          name of midas odb key ( refers to an array)
        start index       first array index
        end  index        last array index
        value             value to write

Returns:

  Integer return code  and   message string

Example:

# Write a value (3)  to elements 0,1,2 of "bin zero" array

# set up odb key addresses
set mdarc                  "/equipment/$eqp_name/mdarc"
set mdarc_bin_zero         "$mdarc/histograms/bin zero"
set value "3"
if {  [ catch { midas set_data $mdarc_bin_zero 0 2 $value] result ]} {
    puts stderr "Error: $result"
}
 

<back to top>
 
 
 
 
 
 
 
 
 

start

 - start a run
This command actually perfoms an odb command of  "start now", which does not offer the user the option of editing the edit-on-start parameters.Therefore the calling program must have already set up the edit-on-start parameters if they are required.

Usage:

        midas start

Parameters:

        none

Returns:

  Integer return code  and   message string

Example:

puts "Sending command  start"
if {  [ catch { midas start } result ]} {
    puts stderr "Error: $result"
} else {
    puts "result: $result"
}
 

Notes:

The most common reasons for failure after trying to start a run are reflected in the error messages returned,
i.e.


<back to top>
 
 
 
 
 
 
 
 
 

stop

This command stops the run.

Usage:

midas stop    or  midas stop now   or  midas stop again

Parameters:

        modifier                         stop run, waiting for any deferred transition. If run is stopped, take no action.
                                now        stop run immediately, i.e. do not wait for any deferred transition
                                again       if run is already stopped, send the stop command again

Returns:

  Integer return code  and   message string

Examples:

# stop the run
puts "Sending command  stop"
if {  [ catch { midas stop } result ]} {
    puts stderr "Error: $result"
}

#  stop the run again
puts "Sending command  stop again"
if {  [ catch { midas stop again} result ]} {
    puts stderr "Error: $result"
}

Notes:

The most common reasons for failure after trying to stop a run are reflected in the error messages returned,
i.e. The commands "stop now" and "stop again" are usually used when some kind of problem occurs stopping the run  with the  "stop" command.
 

<back to top>
 
 
 
 
 
 
 
 
 
 
 
 
 

save

Save the odb database into an ascii file at the position given by key_name . The full odb path is saved in the ascii file so that the file is always loaded (e.g. by the load command ) into the right place in odb.

Usage:

midas save  keyname filename

Parameters:

        keyname        position in odb at which to save the database
        filename         name  (and path)  of file in which to save database

Returns:

  Integer return code  and   message string

Example:

#  save the part of the odb database for the rig
#
#set the path in odb for the rig (keyname)
set odb_path "/Equipment/MUSR_TD_acq/Settings/rig"
#
# read the directory ($dir)  for saved rig files from odb
set rig_path "$odb_path/rig path"
if {  [ catch { midas get_value $rig_path } dir ]} {
    puts stderr "Error after get_value: $dir"
    midas disconnect_experiment
    exit
}
#
#read the current rig name from midas:
set rig_name "$odb_path/current rig"
if {  [ catch { midas get_value $rig_name } rig ]} {
    puts stderr "Error after get_value: $rig"
    midas disconnect_experiment
    exit
}

set filename "$dir/$rig.odb"
puts "Sending command   save $odb_path $filename"

if {  [ catch { midas save $odb_path $filename } result ]} {
    puts stderr "Error: $result"
} else {
    puts "Rig parameters saved in file $filename"
}
 

<back to top>
 
 
 
 
 
 
 
 
 
 
 
 
 

load

Load a saved odb ascii file (saved for example by the save command )  into the odb database. The full odb path is saved in the ascii file so that the file is always loaded into the right place in odb.

Usage:

midas load  filename

Parameters:

        filename         name  (and path)  of file to be loaded into the  odb

Returns:

  Integer return code  and   message string

Example:

#  load  a new rig
#  (i.e  the part of the odb database for the rig)
#set the path in odb for the rig (keyname)
#
set odb_path "/Equipment/MUSR_TD_acq/Settings/rig"
#
# read the directory ($dir)  for saved rig files from odb
set rig_path "$odb_path/rig path"
if {  [ catch { midas get_value $rig_path } dir ]} {
    puts stderr "Error after get_value: $dir"
    midas disconnect_experiment
    exit
}
#
#select a rig name
set rig "omni"
puts "Loading rig : $rig"
set filename "$dir/$rig.odb"
#
puts "Sending command load $filename"
#
if {  [ catch { midas load $filename } result ]} {
    puts stderr "Error: $result"
} else {
    puts "result: $result"
}
 

<back to top>
 
 
 
 
 
 
 
 
 

set_debug

Turn on debugging flag

Usage:

        midas set_debug  flag

Parameters:

         flag                 1=turn on  or  0=turn off debugging

Returns:

  Integer return code  and   message string

Example:

# Turn on debugging
if {  [ catch { midas set_debug 1 ] result ]} {
    puts stderr "Error: $result"
}
 

<back to top>
 
 
 
 
 
 
 

show_debug

Show status of debugging flag

Usage:

        midas show_debug

Parameters:

         none

Returns:

  Integer return code  and   message string

Example:


set debug [midas show_debug ]
puts "$debug"
 

<back to top>
 
 
 
 
 
 
 
 

get_RunNum

For TRIUMF MUSR experiment only:

Set up  the correct run number for the next run, which may be a  test or real run. This routine can be used to verify the current run number is correct, or to change to a test or real run number. If the run is in progress, an error condition will result. To toggle between real and test while a run is in progress requires midas toggle. Note that the run number will be incremented automatically at start of run.

This command is provided for the TRIUMF MUSR experiment where run numbering depends on the beamline for real runs. A specific range of run numbers is assigned to each beamline for real runs, and a different range for  test runs regardless of beamlines.
 

Usage:

        midas get_RunNum  run_type experiment beamline perlscript_path
Parameters:
run_type                       test or real
experiment                   name of midas experiment
beamline                       name of beamline (DEV or M15 or M20 or M9B)
perlscript_path            path where the perlscripts are located on the disk
These parameters are needed to pass to the perlscript.

Returns:

  Integer return code  and   message string

Outputs:

If successful, the perlscripts update the  odb system location "/Runinfo/Run number" with the latest run number, and also update the user-defined location in odb for the run type (test or real).

Details:

Perlscripts

This command actually calls the perlscripts written for the TRIUMF BNMR experiment, test_run.pl or real_run.pl , designed to run with the midas browser. The perlscripts also output a large amount of informational messages into files located in /var/log/midas. They also send information to the midas messaging system,
e.g.
 INFO: All informational output is in file /var/log/midas/test_run.txt    ( or real_run.txt)
 INFO: All informational output is in file /var/log/midas/get_run_number.txt

Error Messages:

In the case of  failure,  check the midas message log file  (or odbedit session or tcl debug session if available) and the informational  text file(s) for details.
 

User-defined odb locations

The perlscript path  and the run type are odb parameters  in a user-defined location in the odb. For MUSR, these are defined as parameters in the
mdarc area, i.e. "/Equipment/MUSR_TD_acq/mdarc/", i.e. "perlscript path" and  "run type".
 

Example:

This example shows how to get a real run number, followed by getting a test run number.

set expt "musr2"
set eqp_name "MUSR_TD_acq"
set beamline "dev"

set debug [midas show_debug ]
puts "$debug"

puts " --------------------------------------------------- "
puts " Get perlscript path from odb "
puts "---------------------------------------------------"
set mdarc "/equipment/$eqp_name/mdarc"
set perl_path "$mdarc/perlscript path"
if {  [ catch { midas get_value $perl_path } perl ]} {
    puts stderr "Error - $perl"
    midas disconnect_experiment
    exit
}

puts "perl script path: $perl"
puts " ----------------------------------------------- "
puts " Getting a REAL run number: "
puts " ----------------------------------------------- "
puts "calling get_RunNum with parameters: real $expt $beamline $perl"

if {  [ catch { midas get_RunNum real $expt $beamline $perl } result ]} {
    puts stderr "Error - $result"
    midas disconnect_experiment
    exit
}

puts " ----------------------------- "
puts " Get the new  run number "
#puts " ----------------------------- "
#get run number  from midas:
set odb_item "Runinfo/Run number"
if {  [ catch { midas get_value $odb_item } run_no ]} {
    puts stderr "Error - $run_no"
    exit
}
#puts "----------------------------------------"
puts " and the run type "
puts " ---------------------------------------- "
set type_path "$mdarc/run type"
if {  [ catch { midas get_value $type_path } run_type ]} {
    puts stderr "Error after get_value: $run_type"
    midas disconnect_experiment
    exit
}
puts "run number is $run_no and type is $run_type"

puts " ----------------------------- "
puts " Getting a TEST run number "
puts " ----------------------------- "

puts "calling get_RunNum with parameters: test $expt $beamline $perl"

if {  [ catch { midas get_RunNum test $expt $beamline $perl } result ]} {
    puts stderr "Error - $result"
    midas disconnect_experiment
    exit
}

puts " ----------------------------- "
puts " Get the new run number "
#puts " ----------------------------- "
#get run number  from midas:
set odb_item "Runinfo/Run number"
if {  [ catch { midas get_value $odb_item } run_no ]} {
    puts stderr "Error after get_value: $run_no"
    midas disconnect experiment
    exit
}
#puts "------------------------------------"
puts " and the run type "
puts " ------------------------------------- "
set type_path "$mdarc/run type"
if {  [ catch { midas get_value $type_path } run_type ]} {
    puts stderr "Error after get_value: $run_type"
    midas disconnect_experiment
    exit
}
puts "run number is now $run_no and the type is $run_type"
 
 

<back to top >
 
 
 
 
 
 
 
 
 
 

toggle

For TRIUMF MUSR experiment only.

Change from a test to a real run (or vice-versa) while a run is in progress.  Toggle is not permitted if the run is paused  (resume run first)  or stopped (use get_RunNum instead).
The toggle procedure takes some time to complete (depending on the interval between saves, an odb parameter) , since a data file must be saved with the new run number before the old data files can be deleted.

This command is provided for the TRIUMF MUSR experiment where a  specific range of run numbers is assigned to each beamline for real runs, and a different range for  test runs regardless of beamline.

Usage:

midas toggle   experiment  beamline  perlscript_path

Parameters:

experiment                   name of midas experiment
beamline                       name of beamline (DEV or M15 or M20 or M9B)
perlscript_path            path where the perlscripts are located on the disk
These parameters are needed to pass to the perlscript.

Returns:

  Integer return code  and   message string
  •          TCL_OK
  •   or   TCL_ERROR  &  message string
  • Outputs:

    If successful, the perlscripts update the  odb system location "/Runinfo/Run number" with the latest run number, and also update the user-defined location in odb for the run type (test or real).

    Details:

    Perlscripts

    This command actually calls the perlscript written for the TRIUMF BNMR experiment, toggle.pl, designed to run with the midas browser. The perlscript also outputs a large amount of informational messages into files located in /var/log/midas. It also sends information to the midas messaging system,
    e.g.
     INFO: All informational output is in file /var/log/midas/toggle.txt
     INFO: Toggle not allowed if run is PAUSED

    Error Messages:

    In the case of  failure,  check the midas message log file  (or odbedit session or tcl debug session if available) and the  text file toggle.txt for details.
     

    User-defined odb locations

    The perlscript path  is an odb parameters  in a user-defined location in the odb. For MUSR, this is defined as parameters in the
    mdarc area, i.e. "/Equipment/MUSR_TD_acq/mdarc/perlscript path"
     

    Example:

    set expt "musr2"
    set eqp_name "MUSR_TD_acq"
    set beamline "dev"

    puts " Using get_value to get perlscript path"
    set mdarc "/equipment/$eqp_name/mdarc"
    set perl_path "$mdarc/perlscript path"

    if {  [ catch { midas get_value $perl_path } perl ]} {
        puts stderr "Error after get_value: $perl"
        midas disconnect_experiment
        exit
    }

    puts "perl script path: $perl"
    puts " ----------------------------------------------- "
    puts " Toggling the run "
    puts " ----------------------------------------------- "
    puts "mtoggle.tcl: calling toggle with parameters: $expt $beamline $perl"

    if {  [ catch { midas toggle $expt $beamline $perl } result ]} {
        puts stderr "Error - $result"
        midas disconnect_experiment
        exit
    }
     
     

    <back to top>
     
     
     
     
     
     

    kill

    For TRIUMF MUSR experiment only.

    Kill the present run, deleting all saved data files for this run.  Kill is not permitted unless the run is first PAUSED.
     

    Usage:

    midas kill   experiment  run_number beamline  perlscript_path

    Parameters:

    experiment                   name of midas experiment
    beamline                       name of beamline (DEV or M15 or M20 or M9B)
    run_number                 the present run number, i.e. the  run to be killed
    perlscript_path            path where the perlscripts are located on the disk
    These parameters are needed to pass to the perlscript.

    Returns:

      Integer return code  and   message string
  •          TCL_OK
  •   or   TCL_ERROR  &  message string
  • Outputs:

    If successful, the perlscript decrements the  odb system location "/Runinfo/Run number"  and deletes all run files for the killed run.

    Details:

    Perlscripts

    This command actually calls the perlscript written for the TRIUMF BNMR experiment, kill.pl, designed to run with the midas browser. The perlscript also outputs a large amount of informational messages into a text file,  /var/log/midas/kill.txt. It also sends information to the midas messaging system,
    e.g.
     INFO: All informational output is in file /var/log/midas/kill.txt
     INFO: Toggle not allowed UNLESS  run is PAUSED

    Error Messages:

    In the case of  failure ,  check the midas message log file  , (or odbedit session or tcl debug session if available) and the  text file kill.txt for details.
     

    Example:

    set expt "musr2"
    set eqp_name "MUSR_TD_acq"
    set beamline "dev"

    puts " Using get_value to get perlscript path"
    set mdarc "/equipment/$eqp_name/mdarc"
    set perl_path "$mdarc/perlscript path"

    if {  [ catch { midas get_value $perl_path } perl ]} {
        puts stderr "Error after get_value: $perl"
        midas disconnect_experiment
        exit
    }

    #get run number  from midas:
    set odb_item "Runinfo/Run number"
    if {  [ catch { midas get_value$odb_item } run_no ]} {
        puts stderr "Error after get_value: $run_no"
        midas disconnect_experiment
        exit
    }
    puts "Present run number: $run_no"

    puts "perl script path: $perl"
    puts " ----------------------------------------------- "
    puts " Killing run $run_no "
    puts " ----------------------------------------------- "
    puts "mkill.tcl: calling kill with parameters: $expt  $run_no $beamline $perl"

    if {  [ catch { midas kill $expt $run_no $beamline $perl } result ]} {
        puts stderr "Error - $result"
        midas disconnect_experiment
        exit
    }
     
     

    <back to top>

    msg

    Send a message using the Midas messaging system. Depending on the message_type parameter, messages may be saved in the midas log file for the experiment, appear in all open odbedit sessions for the experiment, or may be heard through the speakers. For more information, refer to the examples and results below.
     

    Midas log file:

    Note: Midas maintains a log file containing messages sent by the Midas messaging system. These messages may be Midas system messages or messages sent by the various Midas clients. It is an excellent idea to send informational or error messages to this file. The file may be found in the directory given by the odb path: "/logger/Data dir"  and the name of the file is given by "logger/Message file ".  By default, the name of the file is midas.log.
    If there is no odb directory  "/logger" defined, the message file will be in the directory defined for the experiment in /etc/exptab.

    If no odbedit  or browser session is normally run (as is the case with MUSR),   a window should be put up to display the midas log file,  e.g. executing
    "tail -f /home/data/midas.log"
     
     
     

    Usage:

            midas msg  <message_type>   <user_name>   message

    Parameters

    The first two parameters are optional (optional parameters are denoted by angle brackets above).
     
    message_type:   optional
    A number which is equivalent to one of the Midas codes (e.g. MT_ERROR, MT_INFO, MT_LOG, MT_TALK, MT_USER etc.)  which are defined in the file /midas/include/midas.h.
    Most commonly used values are 1 for ERROR, 2 for INFO and 32 for TALK.  The default value  of MT_USER=8 is used if message_type is not supplied, or if message_type supplied is invalid.  The format of the messages is also dependent on the value of message_type.
    user_name:  optional
    A user name (string) may be given to denote who sent the message. The default value of "script" is used if user_name is not supplied. If the message_type is not MT_USER, the name of the calling program is used, regardless of the value of user_name.
    message:        a string i.e. the message that is to be sent.

    Returns:

      Integer return code  and   message string

    Examples:

    # assign midas message types

    set MT_ERROR 1; set MT_INFO 2; set MT_DEBUG 4;
    set MT_USER 8;  set MT_LOG 16; set MT_TALK 32;
    set MT_CALL 64; set MT_ALL   255;

    # Send a message using msg with 1 parameter:
    #  By default, message_type  = MT_USER = 8
    set message "This is test message 1 (1 parameter)"
    puts "Sending command msg with 1 param:  $message "
    if {  [ catch { midas msg $message  } result ]} {
        puts stderr "Error: $result"
    }

    # Send a message using msg with 2 parameters:
    set message "This is test message 2 (2 parameters)"
    #  By default, message_type  = MT_USER = 8
    set user_name "fred";
    puts "Sending command msg with 2 params: $user_name $message "
    if {  [ catch { midas msg $user_name $message  } result ]} {
        puts stderr "Error: $result"
    }

    # Send a message using msg with 3 parameters  (MT_ERROR):
    #   Set message_type  = MT_ERROR
    set message "This is test message 3 (3 params including MT_ERROR)"
    puts "Sending command msg with 3 params: $MT_ERROR $user_name $message"
    if {  [ catch { midas msg $MT_ERROR $user_name $message  } result ]} {
        puts stderr "Error: $result"
    }

    # Send another message using msg with 3 parameters (MT_INFO) :
    #   Set message_type  = MT_INFO
    set message "This is a test message 4 (3 params including MT_INFO)"
    puts "Sending command msg with 3 params: $MT_INFO $user_name $message"
    if {  [ catch { midas msg $MT_INFO $user_name $message  } result ]} {
        puts stderr "Error: $result"
    }

    # Send another message using msg with 3 parameters (MT_LOG):
    #   Set message_type  = MT_LOG
    set message "This is a test message 5 (3 params including MT_LOG)"
    puts "Sending command msg with 3 params: $MT_LOG $user_name $message"
    if {  [ catch { midas msg $MT_LOG $user_name $message  } result ]} {
        puts stderr "Error: $result"
    }

    # Send another message using msg with 3 parameters (MT_USER):
    #   Set message_type  = MT_USER
    set message "This is a test message 6 (3 params including MT_USER)"
    puts "Sending command msg with 3 params: $MT_USER $user_name $message"
    if {  [ catch { midas msg $MT_USER $user_name $message  } result ]} {
        puts stderr "Error: $result"
    }
     
     

    Results:

    The commands in the examples above will result in the following messages appearing in an odbedit session (or browser session):

    11:10:41 [script] This is test message 1 (1 parameter)
    11:10:41 [fred] This is test message 2 (2 parameters)
    11:10:41 [tcl_UI] [midas_tcl.c:1614:fred] This is test message 3 (3 params including MT_ERROR)
    11:10:41 [tcl_UI] This is a test message 4 (3 params including MT_INFO)
    11:10:41 [fred] This is a test message 6 (3 params including MT_USER)

    The following appears in the midas log file :

    Tue Apr  2 11:10:41 2002 [script] This is test message 1 (1 parameter)
    Tue Apr  2 11:10:41 2002 [fred] This is test message 2 (2 parameters)
    Tue Apr  2 11:10:41 2002 [tcl_UI] [midas_tcl.c:1614:fred] This is test message 3 (3 params including MT_ERROR)
    Tue Apr  2 11:10:41 2002 [tcl_UI] This is a test message 4 (3 params including MT_INFO)
    Tue Apr  2 11:10:41 2002 [tcl_UI] This is a test message 5 (3 params including MT_LOG)
    Tue Apr  2 11:10:41 2002 [fred] This is a test message 6 (3 params including MT_USER)
     

    <back to top>
     
     
     
     
     
     
     

    resume

     - resume a run that has been paused
    This command perfoms the odb command   "resume". Data taking is re-enabled. A run may only be resumed if it has previously been paused.

    Usage:

            midas resume

    Parameters:

            none

    Returns:

      Integer return code  and   message string

    Example:

    puts "Sending command  resume"
    if {  [ catch { midas resume } result ]} {
        puts stderr "Error: $result"
    } else {
        puts "result: $result"
    }

    <back to top>
     
     
     
     
     
     

    pause

    This command perfoms the odb command   "pause". Data taking is paused;  histogram data is saved, then no further saved files are written, no data is added to the histograms,
    scalers are disabled, and the io_register sends a level to disable data input.

    Usage:

    midas pause    or   midas pause now

    Parameters:

            modifier:                       pause run, waiting for any deferred transition. If run is stopped, takes no action.
                                    now        pause run immediately, i.e. do not wait for any deferred transition

    Returns:

      Integer return code  and   message string

    Examples:

    # stop the run
    puts "Sending command  stop"
    if {  [ catch { midas pause } result ]} {
        puts stderr "Error: $result"
    }

    #  stop the run again
    puts "Sending command  stop again"
    if {  [ catch { midas pause now} result ]} {
        puts stderr "Error: $result"
    }

    Notes:

    The most common reasons for failure after trying to pause a run are reflected in the error messages returned,
    i.e.


    <back to top>
     
     
     
     
     
     
     

    hot_save

    When mdarc is running, the data are saved automatically at a certain time interval (settable in the odb) and at transitions (e.g. run paused, run stopped).  This command gives the users the option to save a data file when they wish.

    This command causes a saved data (MUD) file to be written as soon as possible, providing :


     It does this by writing to the  odb parameter "/Equipment/MUSR_TD_acq/mdarc/histograms/musr/save now", which is hot-linked by mdarc when a run is in progress.

    The data will be saved immediately, unless a new midas event buffer is not yet available. This may happen if a save has been done within the last  few seconds,  in which case an information  message will be sent by the midas messaging system, e.g.

    13:25:10 [Mdarc] No valid Histogram data is available at this time; data not saved
    In this case, the user should simply execute midas hot_save again.

    Important Note:

    If the run is stopped or mdarc is not running, no data will be saved and there will be no informational or error messages, since this command (midas hot_save) merely writes to an odb key. If a data file is written successfully however, messages will be sent to this effect by mdarc, and the odb key  "/Equipment/MUSR_TD_acq/mdarc/time_of_last_save"  will be updated.

    This command is provided for convenience, since  the user could simply write to odb parameter "/Equipment/MUSR_TD_acq/mdarc/histograms/musr/save now" using midas set_value.
     
     

    Usage:

    midas hot_save

    Parameters:

            none

    Returns:

      Integer return code  and   message string

    Examples:

    # get the data archiver to save the data now
    # Note: if run is not in progress or mdarc is not running,
    # there will be no data saved.

    puts "Sending command  hot_save"
    if {  [ catch { midas hot_save } result ]} {
        puts stderr "Error: $result"
    }
     

    <back to top>
     
     
     

    Example of a complete tcl program

    Note that the first midas call must be to connect_experiment,  and get_experiment_database. Before exiting, call  disconnect_experiment. These calls are omitted from the examples for each  individual command (above).

    #!/bin/sh
    #-*-tcl-*-
    # the next line restarts using wish  \
    exec mtcl "$0" -- ${1+"$@"}
    #
    #
    set host "myhost"
    set expt  "myexpt"
    #  connect to the experiment
    if {  [ catch { midas connect_experiment $host $expt  tcl_UI } result ]} {
        puts stderr "Error after connect_experiment: $result"
        exit
    }

    # connect to the database - no handler returned, so only 1 database
    # can be accessed from Tcl/Tk !
    if {  [ catch { midas get_experiment_database } result ]} {
        puts stderr "Error after get_experiment_database: $result"
        exit
    }

    # read the run number from odb
    #
    set odb_item "Runinfo/Run number"
    if {  [ catch { midas get_value $odb_item } run_no ]} {
        puts stderr "Error after get_value: $run_no"
        midas disconnect_experiment
        exit
    }
    puts "Present run number: $run_no"

    # neatly disconnect
    midas disconnect_experiment
    exit
     

    <back to top>