Midas Common Functions (cm_xxx)
[The midas.h & midas.c]


Data Structures

struct  TR_CLIENT

Functions

INT cm_synchronize (DWORD *seconds)
INT cm_asctime (char *str, INT buf_size)
INT cm_time (DWORD *time)
char * cm_get_version ()
INT cm_set_path (char *path)
INT cm_get_path (char *path)
INT cm_scan_experiments (void)
INT cm_delete_client_info (HNDLE hDB, INT pid)
INT cm_check_client (HNDLE hDB, HNDLE hKeyClient)
INT cm_set_client_info (HNDLE hDB, HNDLE *hKeyClient, char *host_name, char *client_name, INT hw_type, char *password, DWORD watchdog_timeout)
INT cm_get_client_info (char *client_name)
INT cm_get_environment (char *host_name, int host_name_size, char *exp_name, int exp_name_size)
INT cm_connect_experiment (char *host_name, char *exp_name, char *client_name, void(*func)(char *))
INT cm_connect_experiment1 (char *host_name, char *exp_name, char *client_name, void(*func)(char *), INT odb_size, DWORD watchdog_timeout)
INT cm_list_experiments (char *host_name, char exp_name[MAX_EXPERIMENT][NAME_LENGTH])
INT cm_select_experiment (char *host_name, char *exp_name)
INT cm_connect_client (char *client_name, HNDLE *hConn)
INT cm_disconnect_client (HNDLE hConn, BOOL bShutdown)
INT cm_disconnect_experiment (void)
INT cm_set_experiment_database (HNDLE hDB, HNDLE hKeyClient)
INT cm_get_experiment_database (HNDLE *hDB, HNDLE *hKeyClient)
INT cm_set_watchdog_params (BOOL call_watchdog, DWORD timeout)
INT cm_get_watchdog_params (BOOL *call_watchdog, DWORD *timeout)
INT cm_get_watchdog_info (HNDLE hDB, char *client_name, DWORD *timeout, DWORD *last)
INT cm_register_transition (INT transition, INT(*func)(INT, char *), INT sequence_number)
INT cm_set_transition_sequence (INT transition, INT sequence_number)
INT cm_register_deferred_transition (INT transition, BOOL(*func)(INT, BOOL))
INT cm_check_deferred_transition ()
INT cm_transition (INT transition, INT run_number, char *perror, INT strsize, INT async_flag, INT debug_flag)
INT cm_yield (INT millisec)
INT cm_execute (char *command, char *result, INT bufsize)
INT cm_shutdown (char *name, BOOL bUnique)
INT cm_exist (char *name, BOOL bUnique)
INT cm_cleanup (char *client_name, BOOL ignore_timeout)


Function Documentation

INT cm_asctime char *  str,
INT  buf_size
 

Get time from MIDAS server and set local time.

Parameters:
str return time string
buf_size Maximum size of str
Returns:
CM_SUCCESS

Definition at line 948 of file midas.c.

Referenced by al_trigger_alarm(), and cm_transition().

INT cm_check_client HNDLE  hDB,
HNDLE  hKeyClient
 

Check if a client with a /system/client/xxx entry has a valid entry in the ODB client table. If not, remove that client from the /system/client tree.

Parameters:
hDB Handle to online database
hKeyClient Handle to client key
Returns:
CM_SUCCESS, CM_NO_CLIENT

Definition at line 1216 of file midas.c.

Referenced by cm_set_client_info().

INT cm_check_deferred_transition  ) 
 

Check for any deferred transition. If a deferred transition handler has been registered via the cm_register_deferred_transition function, this routine should be called regularly. It checks if a transition request is pending. If so, it calld the registered handler if the transition should be done and then actually does the transition.

Returns:
CM_SUCCESS, <error> Error from cm_transition()

Definition at line 2851 of file midas.c.

Referenced by scheduler().

INT cm_cleanup char *  client_name,
BOOL  ignore_timeout
 

Remove hanging clients independent of their watchdog timeout.

Since this function does not obey the client watchdog timeout, it should be only called to remove clients which have their watchdog checking turned off or which are known to be dead. The normal client removement is done via cm_watchdog().

Currently (Sept. 02) there are two applications for that:

  1. The ODBEdit command "cleanup", which can be used to remove clients which have their watchdog checking off, like the analyzer started with the "-d" flag for a debugging session.
  2. The frontend init code to remove previous frontends. This can be helpful if a frontend dies. Normally, one would have to wait 60 sec. for a crashed frontend to be removed. Only then one can start again the frontend. Since the frontend init code contains a call to cm_cleanup(<frontend_name>), one can restart a frontend immediately.

Added ignore_timeout on Nov.03. A logger might have an increased tiemout of up to 60 sec. because of tape operations. If ignore_timeout is FALSE, the logger is then not killed if its inactivity is less than 60 sec., while in the previous implementation it was always killed after 2*WATCHDOG_INTERVAL.

Parameters:
client_name Client name, if zero check all clients
ignore_timeout If TRUE, ignore a possible increased timeout defined by each client.
Returns:
CM_SUCCESS

Definition at line 4530 of file midas.c.

Referenced by main().

INT cm_connect_client char *  client_name,
HNDLE *  hConn
 

Connect to a MIDAS client of the current experiment

For internal use only.

Parameters:
client_name Name of client to connect to. This name is set by the other client via the cm_connect_experiment call.
hConn Connection handle
Returns:
CM_SUCCESS, CM_NO_CLIENT

Definition at line 1990 of file midas.c.

INT cm_connect_experiment char *  host_name,
char *  exp_name,
char *  client_name,
void(*)(char *)  func
 

This function connects to an existing MIDAS experiment. This must be the first call in a MIDAS application. It opens three TCP connection to the remote host (one for RPC calls, one to send events and one for hot-link notifications from the remote host) and writes client information into the ODB under /System/Clients.

Attention:
All MIDAS applications should evaluate the MIDAS_SERVER_HOST and MIDAS_EXPT_NAME environment variables as defaults to the host name and experiment name (see Environment variables). For that purpose, the function cm_get_environment() should be called prior to cm_connect_experiment(). If command line parameters -h and -e are used, the evaluation should be done between cm_get_environment() and cm_connect_experiment(). The function cm_disconnect_experiment() must be called before a MIDAS application exits.
#include <stdio.h>
#include <midas.h>
main(int argc, char *argv[])
{
  INT  status, i;
  char host_name[256],exp_name[32];

  // get default values from environment
  cm_get_environment(host_name, exp_name);

  // parse command line parameters
  for (i=1 ; i<argc ; i++)
    {
    if (argv[i][0] == '-')
      {
      if (i+1 >= argc || argv[i+1][0] == '-')
        goto usage;
      if (argv[i][1] == 'e')
        strcpy(exp_name, argv[++i]);
      else if (argv[i][1] == 'h')
        strcpy(host_name, argv[++i]);
      else
        {
usage:
        printf("usage: test [-h Hostname] [-e Experiment]\n\n");
        return 1;
        }
      }
    }
  status = cm_connect_experiment(host_name, exp_name, "Test", NULL);
  if (status != CM_SUCCESS)
    return 1;
  ...do operations...
  cm_disconnect_experiment();
}
Parameters:
host_name Specifies host to connect to. Must be a valid IP host name. The string can be empty ("") if to connect to the local computer.
exp_name Specifies the experiment to connect to. If this string is empty, the number of defined experiments in exptab is checked. If only one experiment is defined, the function automatically connects to this one. If more than one experiment is defined, a list is presented and the user can interactively select one experiment.
client_name Client name of the calling program as it can be seen by others (like the scl command in ODBEdit).
func Callback function to read in a password if security has been enabled. In all command line applications this function is NULL which invokes an internal ss_gets() function to read in a password. In windows environments (MS Windows, X Windows) a function can be supplied to open a dialog box and read in the password. The argument of this function must be the returned password.
Returns:
CM_SUCCESS, CM_UNDEF_EXP, CM_SET_ERROR, RPC_NET_ERROR
CM_VERSION_MISMATCH MIDAS library version different on local and remote computer

Definition at line 1629 of file midas.c.

Referenced by main().

INT cm_connect_experiment1 char *  host_name,
char *  exp_name,
char *  client_name,
void(*)(char *)  func,
INT  odb_size,
DWORD  watchdog_timeout
 

Connect to a MIDAS experiment (to the online database) on a specific host.

For internal use only.

Definition at line 1651 of file midas.c.

Referenced by cm_connect_experiment(), and main().

INT cm_delete_client_info HNDLE  hDB,
INT  pid
 

Delete client info from database

Parameters:
hDB Database handle
pid PID of entry to delete, zero for this process.
Returns:
CM_SUCCESS

Definition at line 1165 of file midas.c.

Referenced by cm_check_client(), cm_cleanup(), and cm_disconnect_experiment().

INT cm_deregister_transition INT  transition  ) 
 

Definition at line 2663 of file midas.c.

INT cm_disconnect_client HNDLE  hConn,
BOOL  bShutdown
 

Disconnect from a MIDAS client

Parameters:
hConn Connection handle obtained via cm_connect_client()
bShutdown If TRUE, disconnect from client and shut it down (exit the client program) by sending a RPC_SHUTDOWN message
Returns:
see rpc_client_disconnect()

Definition at line 2056 of file midas.c.

INT cm_disconnect_experiment void   ) 
 

Disconnect from a MIDAS experiment.

Attention:
Should be the last call to a MIDAS library function in an application before it exits. This function removes the client information from the ODB, disconnects all TCP connections and frees all internal allocated memory. See cm_connect_experiment() for example.
Returns:
CM_SUCCESS

Definition at line 2070 of file midas.c.

Referenced by cm_connect_experiment1(), main(), and register_equipment().

INT cm_execute char *  command,
char *  result,
INT  bufsize
 

Executes command via system() call

Parameters:
command Command string to execute
result stdout of command
bufsize string size in byte
Returns:
CM_SUCCESS

Definition at line 3602 of file midas.c.

INT cm_exist char *  name,
BOOL  bUnique
 

Check if a MIDAS client exists in current experiment

Parameters:
name Client name
bUnique If true, look for the exact client name. If false, look for namexxx where xxx is a any number
Returns:
CM_SUCCESS, CM_NO_CLIENT

Definition at line 4452 of file midas.c.

Referenced by main().

INT cm_get_client_info char *  client_name  ) 
 

Get info about the current client

Parameters:
*client_name Client name.
Returns:
CM_SUCCESS, CM_UNDEF_EXP

Definition at line 1455 of file midas.c.

Referenced by bm_open_buffer().

INT cm_get_environment char *  host_name,
int  host_name_size,
char *  exp_name,
int  exp_name_size
 

Returns MIDAS environment variables.

Attention:
This function can be used to evaluate the standard MIDAS environment variables before connecting to an experiment (see Environment variables). The usual way is that the host name and experiment name are first derived from the environment variables MIDAS_SERVER_HOST and MIDAS_EXPT_NAME. They can then be superseded by command line parameters with -h and -e flags.
#include <stdio.h>
#include <midas.h>
main(int argc, char *argv[])
{
  INT  status, i;
  char host_name[256],exp_name[32];

  // get default values from environment
  cm_get_environment(host_name, exp_name);

  // parse command line parameters
  for (i=1 ; i<argc ; i++)
    {
    if (argv[i][0] == '-')
      {
      if (i+1 >= argc || argv[i+1][0] == '-')
        goto usage;
      if (argv[i][1] == 'e')
        strcpy(exp_name, argv[++i]);
      else if (argv[i][1] == 'h')
        strcpy(host_name, argv[++i]);
      else
        {
usage:
        printf("usage: test [-h Hostname] [-e Experiment]\n\n");
        return 1;
        }
      }
    }
  status = cm_connect_experiment(host_name, exp_name, "Test", NULL);
  if (status != CM_SUCCESS)
    return 1;
    ...do anyting...
  cm_disconnect_experiment();
}
Parameters:
host_name Contents of MIDAS_SERVER_HOST environment variable.
host_name_size string length
exp_name Contents of MIDAS_EXPT_NAME environment variable.
exp_name_size string length
Returns:
CM_SUCCESS

Definition at line 1531 of file midas.c.

Referenced by main().

INT cm_get_experiment_database HNDLE *  hDB,
HNDLE *  hKeyClient
 

Get the handle to the ODB from the currently connected experiment.

Attention:
This function returns the handle of the online database (ODB) which can be used in future db_xxx() calls. The hkeyclient key handle can be used to access the client information in the ODB. If the client key handle is not needed, the parameter can be NULL.
HNDLE hDB, hkeyclient;
 char  name[32];
 int   size;
 db_get_experiment_database(&hdb, &hkeyclient);
 size = sizeof(name);
 db_get_value(hdb, hkeyclient, "Name", name, &size, TID_STRING, TRUE);
 printf("My name is %s\n", name);
Parameters:
hDB Database handle.
hKeyClient Handle for key where search starts, zero for root.
Returns:
CM_SUCCESS

Definition at line 2215 of file midas.c.

Referenced by al_trigger_alarm(), ana_end_of_run(), analyzer_init(), cm_connect_client(), cm_deregister_transition(), cm_disconnect_experiment(), cm_exist(), cm_get_client_info(), cm_msg_log(), cm_msg_log1(), cm_msg_retrieve(), cm_register_deferred_transition(), cm_register_transition(), cm_set_transition_sequence(), cm_set_watchdog_params(), cm_shutdown(), cm_transition(), el_submit(), and main().

INT cm_get_path char *  path  ) 
 

Return the path name previously set with cm_set_path.

Parameters:
path Pathname
Returns:
CM_SUCCESS

Definition at line 1037 of file midas.c.

Referenced by cm_connect_experiment1(), cm_msg_log(), cm_msg_log1(), and cm_msg_retrieve().

char* cm_get_version  ) 
 

Return version number of current MIDAS library as a string

Returns:
version number * 100

Definition at line 1006 of file midas.c.

Referenced by cm_transition().

INT cm_get_watchdog_info HNDLE  hDB,
char *  client_name,
DWORD *  timeout,
DWORD *  last
 

Return watchdog information about specific client

Parameters:
hDB ODB handle
client_name ODB client name
timeout Timeout for this application in seconds
last Last time watchdog was called in msec
Returns:
CM_SUCCESS, CM_NO_CLIENT, DB_INVALID_HANDLE

Definition at line 2436 of file midas.c.

INT cm_get_watchdog_params BOOL *  call_watchdog,
DWORD *  timeout
 

Return the current watchdog parameters

Parameters:
call_watchdog Call the cm_watchdog routine periodically
timeout Timeout for this application in seconds
Returns:
CM_SUCCESS

Definition at line 2416 of file midas.c.

Referenced by bm_open_buffer(), cm_connect_experiment1(), cm_set_client_info(), and db_open_database().

INT cm_list_experiments char *  host_name,
char  exp_name[MAX_EXPERIMENT][NAME_LENGTH]
 

Connect to a MIDAS server and return all defined experiments in *exp_name[MAX_EXPERIMENTS]

Parameters:
host_name Internet host name.
exp_name list of experiment names
Returns:
CM_SUCCESS, RPC_NET_ERROR

Definition at line 1848 of file midas.c.

Referenced by cm_select_experiment().

INT cm_register_deferred_transition INT  transition,
BOOL(*)(INT, BOOL)  func
 

Register a deferred transition handler. If a client is registered as a deferred transition handler, it may defer a requested transition by returning FALSE until a certain condition (like a motor reaches its end position) is reached.

Parameters:
transition One of TR_xxx
(*func) Function which gets called whenever a transition is requested. If it returns FALSE, the transition is not performed.
Returns:
CM_SUCCESS, <error> Error from ODB access

Definition at line 2790 of file midas.c.

INT cm_register_transition INT  transition,
INT(*)(INT, char *)  func,
INT  sequence_number
 

Registers a callback function for run transitions. This function internally registers the transition callback function and publishes its request for transition notification by writing a transition request to /System/Clients/<pid>/Transition XXX. Other clients making a transition scan the transition requests of all clients and call their transition callbacks via RPC.

Clients can register for transitions (Start/Stop/Pause/Resume) in a given sequence. All sequence numbers given in the registration are sorted on a transition and the clients are contacted in ascending order. By default, all programs register with a sequence number of 500. The logger however uses 200 for start, so that it can open files before the other clients are contacted, and 800 for stop, so that the files get closed when all other clients have gone already through the stop trantition.

The callback function returns CM_SUCCESS if it can perform the transition or a value larger than one in case of error. An error string can be copied into the error variable.

Attention:
The callback function will be called on transitions from inside the cm_yield() function which therefore must be contained in the main program loop.
INT start(INT run_number, char *error)
{
  if (<not ok>)
    {
    strcpy(error, "Cannot start because ...");
    return 2;
    }
  printf("Starting run %d\n", run_number);
  return CM_SUCCESS;
}
main()
{
  ...
  cm_register_transition(TR_START, start, 500);
  do
    {
    status = cm_yield(1000);
    } while (status != RPC_SHUTDOWN &&
             status != SS_ABORT);
  ...
}
Parameters:
transition Transition to register for (see State Codes & Transition Codes)
func Callback function.
sequence_number Sequence number for that transition (1..1000)
Returns:
CM_SUCCESS

Definition at line 2595 of file midas.c.

Referenced by main().

INT cm_scan_experiments void   ) 
 

Scan the "exptab" file for MIDAS experiment names and save them for later use by rpc_server_accept(). The file is first searched under $MIDAS/exptab if present, then the directory from argv[0] is probed.

Returns:
CM_SUCCESS
CM_UNDEF_EXP exptab not found and MIDAS_DIR not set

Definition at line 1073 of file midas.c.

Referenced by cm_connect_experiment1(), and cm_list_experiments().

INT cm_select_experiment char *  host_name,
char *  exp_name
 

Connect to a MIDAS server and select an experiment from the experiments available on this server

For internal use only.

Parameters:
host_name Internet host name.
exp_name list of experiment names
Returns:
CM_SUCCESS, RPC_NET_ERROR

Definition at line 1951 of file midas.c.

Referenced by cm_connect_experiment1().

INT cm_set_client_info HNDLE  hDB,
HNDLE *  hKeyClient,
char *  host_name,
char *  client_name,
INT  hw_type,
char *  password,
DWORD  watchdog_timeout
 

Set client information in online database and return handle

Parameters:
hDB Handle to online database
hKeyClient returned key
host_name server name
client_name Name of this program as it will be seen by other clients.
hw_type Type of byte order
password MIDAS password
watchdog_timeout Default watchdog timeout, can be overwritten by ODB setting /programs/<name>/Watchdog timeout
Returns:
CM_SUCCESS

Definition at line 1278 of file midas.c.

Referenced by cm_connect_experiment1().

INT cm_set_experiment_database HNDLE  hDB,
HNDLE  hKeyClient
 

Set the handle to the ODB for the currently connected experiment

Parameters:
hDB Database handle
hKeyClient Key handle of client structure
Returns:
CM_SUCCESS

Definition at line 2152 of file midas.c.

Referenced by cm_connect_experiment1(), and cm_disconnect_experiment().

INT cm_set_path char *  path  ) 
 

Set path to actual experiment. This function gets called by cm_connect_experiment if the connection is established to a local experiment (not through the TCP/IP server). The path is then used for all shared memory routines.

Parameters:
path Pathname
Returns:
CM_SUCCESS

Definition at line 1020 of file midas.c.

Referenced by cm_connect_experiment1().

INT cm_set_transition_sequence INT  transition,
INT  sequence_number
 

Change the transition sequence for the calling program.

Parameters:
transition TR_START, TR_PAUSE, TR_RESUME or TR_STOP.
sequence_number New sequence number, should be between 1 and 1000
Returns:
CM_SUCCESS

Definition at line 2724 of file midas.c.

INT cm_set_watchdog_params BOOL  call_watchdog,
DWORD  timeout
 

Sets the internal watchdog flags and the own timeout. If call_watchdog is TRUE, the cm_watchdog routine is called periodically from the system to show other clients that this application is "alive". On UNIX systems, the alarm() timer is used which is then not available for user purposes.

The timeout specifies the time, after which the calling application should be considered "dead" by other clients. Normally, the cm_watchdog() routines is called periodically. If a client crashes, this does not occur any more. Then other clients can detect this and clear all buffer and database entries of this application so they are not blocked any more. If this application should not checked by others, the timeout can be specified as zero. It might be useful for debugging purposes to do so, because if a debugger comes to a breakpoint and stops the application, the periodic call of cm_watchdog is disabled and the client looks like dead.

If the timeout is not zero, but the watchdog is not called (call_watchdog == FALSE), the user must ensure to call cm_watchdog periodically with a period of WATCHDOG_INTERVAL milliseconds or less.

An application which calles system routines which block the alarm signal for some time, might increase the timeout to the maximum expected blocking time before issuing the calls. One example is the logger doing Exabyte tape IO, which can take up to one minute.

Parameters:
call_watchdog Call the cm_watchdog routine periodically
timeout Timeout for this application in ms
Returns:
CM_SUCCESS

Definition at line 2302 of file midas.c.

Referenced by cm_connect_experiment1(), cm_set_client_info(), and main().

INT cm_shutdown char *  name,
BOOL  bUnique
 

Shutdown (exit) other MIDAS client

Parameters:
name Client name or "all" for all clients
bUnique If true, look for the exact client name. If false, look for namexxx where xxx is a any number.
Returns:
CM_SUCCESS, CM_NO_CLIENT, DB_NO_KEY

Definition at line 4362 of file midas.c.

Referenced by cm_transition(), and main().

INT cm_synchronize DWORD *  seconds  ) 
 

Get time from MIDAS server and set local time.

Parameters:
seconds Time in seconds
Returns:
CM_SUCCESS

Definition at line 920 of file midas.c.

Referenced by main().

INT cm_time DWORD *  time  ) 
 

Get time from ss_time on server.

Parameters:
time string
Returns:
CM_SUCCESS

Definition at line 966 of file midas.c.

Referenced by cm_transition().

INT cm_transition INT  transition,
INT  run_number,
char *  perror,
INT  strsize,
INT  async_flag,
INT  debug_flag
 

Performs a run transition (Start/Stop/Pause/Resume).

Synchronous/Asynchronous flag. If set to ASYNC, the transition is done asynchronously, meaning that clients are connected and told to execute their callback routine, but no result is awaited. The return value is specified by the transition callback function on the remote clients. If all callbacks can perform the transition, CM_SUCCESS is returned. If one callback cannot perform the transition, the return value of this callback is returned from cm_transition(). The async_flag is usually FALSE so that transition callbacks can block a run transition in case of problems and return an error string. The only exception are situations where a run transition is performed automatically by a program which cannot block in a transition. For example the logger can cause a run stop when a disk is nearly full but it cannot block in the cm_transition() function since it has its own run stop callback which must flush buffers and close disk files and tapes.

...
    i = 1;
    db_set_value(hDB, 0, "/Runinfo/Transition in progress", &i, sizeof(INT), 1, TID_INT);

      status = cm_transition(TR_START, new_run_number, str, sizeof(str), SYNC, debug_flag);
      if (status != CM_SUCCESS)
      {
        // in case of error
        printf("Error: %s\n", str);
      }
    ...
Parameters:
transition TR_START, TR_PAUSE, TR_RESUME or TR_STOP.
run_number New run number. If zero, use current run number plus one.
perror returned error string.
strsize Size of error string.
async_flag SYNC: synchronization flag (SYNC:wait completion, ASYNC: retun immediately)
debug_flag If 1 output debugging information, if 2 output via cm_msg().
Returns:
CM_SUCCESS, <error> error code from remote client

Definition at line 2948 of file midas.c.

Referenced by cm_check_deferred_transition(), scan_fragment(), and scheduler().

INT cm_yield INT  millisec  ) 
 

Central yield functions for clients. This routine should be called in an infinite loop by a client in order to give the MIDAS system the opportunity to receive commands over RPC channels, update database records and receive events.

Parameters:
millisec Timeout in millisec. If no message is received during the specified timeout, the routine returns. If millisec=-1, it only returns when receiving an RPC_SHUTDOWN message.
Returns:
CM_SUCCESS, RPC_SHUTDOWN

Definition at line 3549 of file midas.c.

Referenced by scan_fragment(), and scheduler().

int tr_compare const void *  arg1,
const void *  arg2
 

Definition at line 2903 of file midas.c.

Referenced by cm_transition().


Midas DOC Version 1.9.5 ---- PSI Stefan Ritt ----
Contributions: Pierre-Andre Amaudruz - Sergio Ballestrero - Suzannah Daviel - Doxygen - Peter Green - Qing Gu - Greg Hackman - Gertjan Hofman - Paul Knowles - Rudi Meier - Glenn Moloney - Dave Morris - John M O'Donnell - Konstantin Olchanski - Renee Poutissou - Tamsen Schurman - Andreas Suter - Jan M.Wouters - Piotr Adam Zolnierczuk