Midas C++ API - cm_xxx functions

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 (HNDLE) –
  Handle to online database
• hKeyClient (HNDLE) –
  Handle to client key

Returns:

• INT –
  CM_SUCCESS, CM_NO_CLIENT

Declared in include/midas.h:1731, defined in src/midas.cxx:1935

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:

• INT –
  CM_SUCCESS, \<error> Error from cm_transition()

Declared in include/midas.h:1714, defined in src/midas.cxx:3985

INT cm_cleanup(const 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: -# 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. -# 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 (const char *) –
  Client name, if zero check all clients
• ignore_timeout (BOOL) –
  If TRUE, ignore a possible increased timeout defined by each client.

Returns:

• INT –
  CM_SUCCESS

Declared in include/midas.h:1742, defined in src/midas.cxx:7684

INT cm_connect_client(const char *client_name, HNDLE * hConn)

Connect to a MIDAS client of the current experiment

Declared in include/midas.h:1720, defined in src/midas.cxx:2854

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

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.

#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 (const char *) –
  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 (const char *) –
  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 (const char *) –
  Client name of the calling program as it can be seen by others (like the scl command in ODBEdit).
• func (void (*) (char *)) –
  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:

• INT –
  CM_SUCCESS, CM_UNDEF_EXP, CM_SET_ERROR, RPC_NET_ERROR
  CM_VERSION_MISMATCH MIDAS library version different on local and remote computer

Declared in include/midas.h:1700, defined in src/midas.cxx:2368

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

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

Declared in include/midas.h:1702, defined in src/midas.cxx:2387

INT cm_delete_client_info(HNDLE hDB, INT pid)

Delete client info from database

Parameters:

• hDB (HNDLE) –
  Database handle
• pid (INT) –
  PID of entry to delete, zero for this process.

Returns:

• INT –
  CM_SUCCESS

Declared in include/msystem.h:534, defined in src/midas.cxx:1918

INT cm_deregister_transition(INT transition)

Declared in include/midas.h:1709, defined in src/midas.cxx:3765

INT cm_disconnect_client(HNDLE hConn, BOOL bShutdown)

Disconnect from a MIDAS client

Parameters:

• hConn (HNDLE) –
  Connection handle obtained via cm_connect_client()
• bShutdown (BOOL) –
  If TRUE, disconnect from client and shut it down (exit the client program) by sending a RPC_SHUTDOWN message

Returns:

• INT –
  see rpc_client_disconnect()

Declared in include/midas.h:1721, defined in src/midas.cxx:2921

INT cm_disconnect_experiment()

Disconnect from a MIDAS experiment.

Returns:

• INT –
  CM_SUCCESS

Declared in include/midas.h:1706, defined in src/midas.cxx:2934

INT cm_execute(const char *command, char *result, INT buf_size)

Executes command via system() call

Parameters:

• command (const char *) –
  Command string to execute
• result (char *) –
  stdout of command
• buf_size (INT) –
  string size in byte

Returns:

• INT –
  CM_SUCCESS

Declared in include/midas.h:1747, defined in src/midas.cxx:5813

INT cm_exist(const char *name, BOOL bClientName)

Check if a MIDAS client exists in current experiment

Parameters:

• name (const char *) –
  Client name
• bClientName (BOOL) –
  If true, look for the exact client name (odbedit, odbedit1, odbedit2, ...) If false, look for the exact program name (odbedit) a any number

Returns:

• INT –
  CM_SUCCESS, CM_NO_CLIENT

Declared in include/midas.h:1741, defined in src/midas.cxx:7555

std::string cm_expand_env(const char* str)

Expand environment variables in filesystem file path names

Examples of expansion: $FOO=foo, $BAR=bar, $UNDEF is undefined (undefined, not empty)

ok &= test_cm_expand_env1("aaa", "aaa");
ok &= test_cm_expand_env1("$FOO", "foo");
ok &= test_cm_expand_env1("/$FOO", "/foo");
ok &= test_cm_expand_env1("/$FOO/", "/foo/");
ok &= test_cm_expand_env1("$FOO/$BAR", "foo/bar");
ok &= test_cm_expand_env1("$FOO1", "$FOO1");
ok &= test_cm_expand_env1("1$FOO", "1foo");
ok &= test_cm_expand_env1("$UNDEF", "$UNDEF");
ok &= test_cm_expand_env1("/$UNDEF/", "/$UNDEF/");

Parameters:

• str (const char*) –
  Input file path

Returns:

• std::string –
  expanded file path

Declared in include/midas.h:1778, defined in src/midas.cxx:7784

std::string cm_get_client_name()

Get current client name

Returns:

• std::string –
  current client name

Declared in include/midas.h:1730, defined in src/midas.cxx:2149

INT cm_get_experiment_database(HNDLE * hDB, HNDLE * hKeyClient)

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

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 (HNDLE *) –
  Database handle.
• hKeyClient (HNDLE *) –
  Handle for key where search starts, zero for root.

Returns:

• INT –
  CM_SUCCESS

Declared in include/midas.h:1723, defined in src/midas.cxx:3099

std::string cm_get_history_path(const char* history_channel)

Declared in include/msystem.h:535, defined in src/midas.cxx:5876

INT cm_get_path_string(std::string* path)

Declared in include/msystem.h:529, defined in src/midas.cxx:1595

const char*cm_get_revision()

Return git revision number of current MIDAS library as a string

Returns:

• const char* –
  revision number

Declared in include/midas.h:1683, defined in src/midas.cxx:1534

const char*cm_get_version()

Return version number of current MIDAS library as a string

Returns:

• const char* –
  version number

Declared in include/midas.h:1682, defined in src/midas.cxx:1526

INT cm_get_watchdog_info(HNDLE hDB, const char *client_name, DWORD * timeout, DWORD * last)

Return watchdog information about specific client

Parameters:

• hDB (HNDLE) –
  ODB handle
• client_name (const char *) –
  ODB client name
• timeout (DWORD *) –
  Timeout for this application in seconds
• last (DWORD *) –
  Last time watchdog was called in msec

Returns:

• INT –
  CM_SUCCESS, CM_NO_CLIENT, DB_INVALID_HANDLE

Declared in include/midas.h:1734, defined in src/midas.cxx:3432

INT cm_get_watchdog_params(BOOL * call_watchdog, DWORD * timeout)

Return the current watchdog parameters

Parameters:

• call_watchdog (BOOL *) –
  Call the cm_watchdog routine periodically
• timeout (DWORD *) –
  Timeout for this application in seconds

Returns:

• INT –
  CM_SUCCESS

Declared in include/midas.h:1733, defined in src/midas.cxx:3413

INT cm_list_experiments_local(STRING_LIST* exp_names)

Read exptab and return all defined experiments in *exp_name[MAX_EXPERIMENTS]

Parameters:

• exp_names (STRING_LIST*)
• host_name –
  Internet host name.
• exp_name –
  list of experiment names

Returns:

• INT –
  CM_SUCCESS, RPC_NET_ERROR

Declared in include/midas.h:1689, defined in src/midas.cxx:2674

INT cm_list_experiments_remote(const char *host_name, STRING_LIST* exp_names)

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

Parameters:

• host_name (const char *) –
  Internet host name.
• exp_names (STRING_LIST*)
• exp_name –
  list of experiment names

Returns:

• INT –
  CM_SUCCESS, RPC_NET_ERROR

Declared in include/midas.h:1690, defined in src/midas.cxx:2700

INT cm_periodic_tasks()

Perform midas periodic tasks - check alarms, update and check timeouts on odb and on event buffers, etc. Normally called by cm_yield(). Programs that do not use cm_yield(), i.e. the mserver, should call this function periodically, every 1 or 2 seconds.

Returns:

• INT –
  CM_SUCCESS

Declared in include/midas.h:1745, defined in src/midas.cxx:5669

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

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. a transition is requested. If it returns FALSE, the transition is not performed.

Parameters:

• transition (INT) –
  One of TR_xxx
• func (BOOL(*) (INT, BOOL))

Returns:

• INT –
  CM_SUCCESS, \<error> Error from ODB access

Declared in include/midas.h:1713, defined in src/midas.cxx:3933

INT cm_register_transition(INT transition, INT(*func) (INT, char *), 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.

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 (INT) –
  Transition to register for (see state_transition)
• func (INT(*) (INT, char *)) –
  Callback function.
• sequence_number (int) –
  Sequence number for that transition (1..1000)

Returns:

• INT –
  CM_SUCCESS

Declared in include/midas.h:1707, defined in src/midas.cxx:3689

INT cm_select_experiment_local(std::string *exp_name)

Read exptab and select an experiment from the experiments available on this server

Declared in include/midas.h:1697, defined in src/midas.cxx:2758

INT cm_select_experiment_remote(const char *host_name, std::string *exp_name)

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

Declared in include/midas.h:1698, defined in src/midas.cxx:2807

INT cm_set_client_info(HNDLE hDB, HNDLE * hKeyClient, const char *host_name, const char *client_name, INT computer_id, const char *password, DWORD watchdog_timeout)

Set client information in online database and return handle

Parameters:

• hDB (HNDLE) –
  Handle to online database
• hKeyClient (HNDLE *) –
  returned key
• host_name (const char *) –
  server name
• client_name (const char *) –
  Name of this program as it will be seen by other clients.
• computer_id (INT) –
  Type of byte order
• password (const char *) –
  MIDAS password
• watchdog_timeout (DWORD) –
  Default watchdog timeout, can be overwritten by ODB setting /programs/\<name>/Watchdog timeout

Returns:

• INT –
  CM_SUCCESS

Declared in include/midas.h:1726, defined in src/midas.cxx:1959

INT cm_set_client_run_state(INT state)

Declared in include/midas.h:1711, defined in src/midas.cxx:3879

INT cm_set_experiment_database(HNDLE hDB, HNDLE hKeyClient)

Set the handle to the ODB for the currently connected experiment

Parameters:

• hDB (HNDLE) –
  Database handle
• hKeyClient (HNDLE) –
  Key handle of client structure

Returns:

• INT –
  CM_SUCCESS

Declared in include/midas.h:1722, defined in src/midas.cxx:3027

INT cm_set_experiment_local(const char* exp_name)

Declared in include/midas.h:1699, defined in src/midas.cxx:2256

INT cm_set_experiment_name(const char *name)

Set name of the experiment

Parameters:

• name (const char *) –
  Experiment name

Returns:

• INT –
  CM_SUCCESS

Declared in include/msystem.h:530, defined in src/midas.cxx:1608

INT cm_set_path(const 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 (const char *) –
  Pathname

Returns:

• INT –
  CM_SUCCESS

Declared in include/msystem.h:525, defined in src/midas.cxx:1547

INT cm_set_transition_sequence(INT transition, INT sequence_number)

Change the transition sequence for the calling program.

Parameters:

• transition (INT) –
  TR_START, TR_PAUSE, TR_RESUME or TR_STOP.
• sequence_number (INT) –
  New sequence number, should be between 1 and 1000

Returns:

• INT –
  CM_SUCCESS

Declared in include/midas.h:1710, defined in src/midas.cxx:3819

INT cm_set_watchdog_params(BOOL call_watchdog, DWORD timeout)

set also local timeout to requested value (needed by cm_enable_watchdog())

Declared in include/midas.h:1732, defined in src/midas.cxx:3371

INT cm_start_watchdog_thread()

watchdog does not run inside remote clients. watchdog timeout timers are maintained by the mserver

Declared in include/midas.h:1736, defined in src/midas.cxx:7390

INT cm_stop_watchdog_thread()

watchdog does not run inside remote clients. watchdog timeout timers are maintained by the mserver

Declared in include/midas.h:1737, defined in src/midas.cxx:7405

INT cm_synchronize(DWORD * sec)

Get time from MIDAS server and set local time.

Parameters:

• sec (DWORD *) –
  Time in seconds

Returns:

• INT –
  CM_SUCCESS

Declared in include/midas.h:1748, defined in src/midas.cxx:1419

INT cm_time(DWORD * t)

Get time from ss_time on server.

Parameters:

• t (DWORD *) –
  string

Returns:

• INT –
  CM_SUCCESS

Declared in include/midas.h:1752, defined in src/midas.cxx:1484

INT cm_transition(INT transition, INT run_number, char *error, INT strsize, INT async_flag, INT debug_flag)

wrapper around cm_transition1() for detached multi-threaded transitions

Declared in include/midas.h:1715, defined in src/midas.cxx:5376

INT cm_transition_cleanup()

Declared in include/midas.h:1716, defined in src/midas.cxx:5357

INT cm_watchdog_thread(void*unused)

Watchdog thread to maintain the watchdog timeout timestamps for this client

Declared in include/midas.h:1735, defined in src/midas.cxx:7364

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 (INT) –
  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:

• INT –
  CM_SUCCESS, RPC_SHUTDOWN

Declared in include/midas.h:1743, defined in src/midas.cxx:5732