A C++11 object-oriented interface to the [[ODB|ODB (online database)]] was introduced in May 2020. You can think of it like a "magic" map/dictionary that automatically sends changes you make to the ODB, and receives updates that others have made.

The header for this odbxx interface is at [https://bitbucket.org/tmidas/midas/src/develop/include/odbxx.h odbxx.h] and example usage in [https://bitbucket.org/tmidas/midas/src/develop/examples/odbxx/odbxx_test.cxx].

You can find more details about the ODB on the [[ODB_Access_and_Use|ODB Access and Use]] page, which includes links to the command-line, javascript, python, and non-object C++ interfaces.

== Basic usage ==

The simplest usage is like:

<pre>// Grab a bit of the ODB
midas::odb exp("/Experiment");

// Simple read
std::cout << "The current transition timeout is " << exp["Transition timeout"] << std::endl;

// Make a change. The new value is automatically sent to the ODB.
// Most C++ operators are supported (++, += etc), or you can do a simple
// re-assignment like `exp["Transition timeout"] = 12345;`.
exp["Transition timeout"] += 100;

// Read the new value
std::cout << "The transition timeout is now " << exp["Transition timeout"] << std::endl;
</pre>

You can automatically cast to regular data types (int, double) etc if you want a copy of the value to work with:

<pre>int curr_timeout = exp["Transition timeout"];</pre>

'''Note''': The ODB directory you connect to ("/Experiment" in the above example), has to start with a "/" to tell the midas::odb object
to connect directly to the ODB. Otherwise, a simple local midas::odb string object gets created without any connection to the ODB.

== Automatic refreshing ==

You may temporarily disable the automatic updating to/from the ODB
using <code>odb::set_auto_refresh_write(false)</code> and <code>odb::set_auto_refresh_read(false)</code>.

If auto-refresh is enabled (the default), your new values are sent to
the ODB as soon as you touch the value in the <code>midas::odb</code> object. The ODB
is queried for new values whenever you access the value. In the above
example, the ODB is queried 4 times (during construction of <code>exp</code>, and
each time <code>exp["Transition timeout"]</code> is mentioned), and written to 1
time (when <code>exp["Transition timeout"]</code> is assigned to).

See the [[#Callback functions]] section below for details on how to have a function
called when a value changes.

== Arrays/vectors ==

ODB arrays are represented by std vectors.

You can access/edit individual elements using []:

<pre>odb["Example"][1] = 1.2;</pre>

You can completely re-assign content using a std::vector or std::array:

<pre>std::vector<float> vec = std::vector<float>(10);
odb["Example"] = vec;
</pre>

You can resize arrays using <code>odb::resize()</code>. If the existing array is longer,
it will be truncated; if shorter it will be extended with default values
(0 or an empty string).

<pre>odb["Example"].resize(5); // Now is 5 elements long</pre>

Note that arithmetic operators are supported for arrays, and will apply
the operation to ALL ELEMENTS IN THE ARRAY:

<pre>// Create the vector
std::vector<float> vec = std::vector<float>(2);
vec[0] = 3;
vec[1] = 5;

// Assign in ODB
odb["Example"] = vec;

// Multiply ALL elements by 2
odb["Example"] *= 2;

// odb["Example"] now contains {6, 10}.
</pre>

You can directly iterate over arrays/vectors:

<pre>// Iterating using standard begin/end.
for (auto it = o["Int Array"].begin(); it != o["Int Array"].end(); it++) {
int val = *it;
std::cout << val << std::endl;
}
</pre>

<pre>// Iterating using C++11 range-based for loop.
for (int val : o["Int Array"]) {
std::cout << val << std::endl;
}
</pre>

== Strings ==

Strings in the ODB are returned as std::string (unlike the midas.h <code>db_get_value()</code>
family of functions, where strings are returned as char*). You may have vectors of strings.

== Creating new bits of the ODB ==

You can automatically create bits of the ODB by passing a struct to the
<code>midas::odb</code> constructor, then calling <code>odb::connect()</code>, like:

<pre>// Define the ODB structure
midas::odb o = {
{"Int32 Key", 42},
{"Bool Key", true},
{"Subdir", {
{"Float key", 1.2f}, // floats must be explicitly specified
}},
{"Int Array", {1, 2, 3}},
{"Double Array", {1.2, 2.3, 3.4}},
{"String Array", {"Hello1", "Hello2", "Hello3"}},
{"Large Array", std::array<int, 10>{} }, // array with explicit size
{"Large String", std::string(63, '\0') }, // string with explicit size
};

// Then sync the structure. This function
// - keeps the existing value of any keys that are in the ODB and your code
// - creates any keys that are in your code but not yet in the ODB
o.connect("/Test/Settings");

// If you make the `write_defaults` argument true, then the function
// - overwrites the value of any keys that are in the ODB with the value in your code
// - creates any keys that are in your code but not yet in the ODB
o.connect("/Test/Settings", true);

// The `connect_and_fix_structure()` method acts like the old db_check_record() function, and
// - keeps the existing value of any keys that are in the ODB and your code
// - creates any keys that are in your code but not yet in the ODB
// - deletes any keys that are in the ODB but not your code
// - updates the order of keys in the ODB to match your code
o.connect_and_fix_structure("/Test/Settings");
</pre>

Note that the ODB path in teh odb::connect() call must start with a '/'. The ODB root path like <code>o.connect("/");</code> is not allowed in this call.

If you want to add new keys to existing ODB subdirectories, you can also just use the [] operator:

<pre>midas::odb existing_key("/MyExistingKey");
existing_key["MyNewSubKey"] = 1.23;
</pre>

You can also create new keys by providing a default value when reading a value. If the key doesn't already exist, the default value will be used.

<pre>midas::odb existing_key("/MyExistingKey");
double val = existing_key["MyNewSubKey"](1.23);
</pre>

== Iterating over subkeys ==

You can iterate over subkeys using normal iterator functions.

<pre>// Iterating using standard begin/end.
midas::odb exp("/Experiment");

for (auto it = exp.begin(); it != exp.end(); it++) {
midas::odb& subkey = *it;
std::cout << subkey.get_name() << " = " << subkey << std::endl;
}
</pre>

<pre>// Iterating using C++11 range-based for loop.
for (midas::odb& subkey : exp) {
std::cout << subkey.get_name() << " = " << subkey << std::endl;
}
</pre>

You can check whether a subkey exists using <code>odb::is_subkey()</code>.

== Callback functions ==

You may also set up callback functions that are called whenever a value
changes, using the <code>odb::watch()</code> function. Note that you must call
<code>cm_yield()</code> (from midas.h) periodically for this to work - deep down it
is <code>cm_yield()</code> itself that calls your callback function.

The callback functions can either be a "normal" function, a C++ lambda, or a member function of a C++ class.
In all cases it should accept one argument - a <code>midas::odb</code> object (passed
by reference) that contains the new state.

<pre>// Example with a lambda:
midas::odb to_watch("/Experiment");
to_watch.watch([](midas::odb &arg) {
std::cout << "Value of key \"" + arg.get_full_path() + "\" changed to " << arg << std::endl;
});
</pre>

<pre>// Example with a "normal" function:
void my_function(midas::odb &arg) {
std::cout << "Value of key \"" + arg.get_full_path() + "\" changed to " << arg << std::endl;
}

midas::odb to_watch("/Experiment");
to_watch.watch(my_function);
</pre>

<pre>// Example with a member function of a class:
#include <functional>

void MyClass::my_function(midas::odb& arg) {
std::cout << "Value of key \"" + arg.get_full_path() + "\" changed to " << arg << std::endl;
}

void MyClass::some_initialisation_code() {
// Arguments to std::bind() are: "member function to call", "object to call that function on", "placeholder for midas::odb arg"
std::function<void(midas::odb&)> callback = std::bind(&MyClass::my_function, this, std::placeholders::_1);

midas::odb to_watch("/Experiment");
to_watch.watch(callback);
}
</pre>

== Utility functions ==

There are various utility functions which can be used:

==== void odb::create(const char *name, int type) ====

Simple wrapper around db_create_key() to create a single key in the ODB. <code>type</code> is one of TID_xxx.

==== void odb::delete_key() ====

This member function of a midas::odb object deletes that object from the ODB:

<pre>midas::odb o("/Some/ODB/Path");
o.delete_key();
</pre>

==== int odb::delete_key(const std::string &name) ====

This function deletes a key or a subtree in the ODB passed by its path in the <code>name</code> argument. It is a simple wrapper around the C function db_delete_key() and returns the status of that function.

==== bool odb::exists(const std::string *name) ====

This boolean function checks if a key given by its name exists in the ODB.

==== void odb::exists(const std::string *name) ====

This boolean function checks if a key given by its name exists in the ODB.

==== void odb::set_debug(bool flag) / bool odb::get_debug() ====

These functions set and retrieve the debug flag. If the debug flag is <code>true</code> all communication with the ODB is printed to the screen. This can be helpful in debugging some problems.

== Example code ==

A full working example exploring most of the features can be found in
<code>odbxx/odbxx_test.cxx</code>. The test executable will be compiled as
<code>build/odbxx/odbxx_test</code> (it is not installed in the `bin` directory).

Mjsonrpc

2023-12-07T09:56:05Z

Zaher: fixed links

{{Pagelinks}}

== Links ==
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* [[Mhttpd.js|MIDAS Javascript library]]
* [[Custom Page]]
* [[Custom Page Features]]
* [[mhttpd]]
</div>

= MIDAS JSON-RPC interface =
This page described the MIDAS JSON-RPC interface found in the MIDAS Javascript library [[mhttpd.js]].

== JSON general information ==

JSON is a lightweight data-interchange format usually associated with Javascript and web programming. It is a popular choice as replacement for older general purpose data formats such as XML. JSON is defined by [https://tools.ietf.org/html/rfc7159 RFC-7159] (read more at http://www.json.org/). When necessary, the overhead of text encoded JSON is reduced by compressing JSON documents (using gzip), or by using binary-encoded JSON.

JSON documents look like this:
<pre>
{ "Runinfo" : { "State" : 1, "Online Mode" : 1, "Run number" : 13585 } }
</pre>

Note that the JSON standard is incompatible with [https://en.wikipedia.org/wiki/IEEE_floating_point IEEE Standard for Floating-Point Arithmetic (IEEE 754)], specifically, there is no standard way to encode the special numerical values +Infinity, -Infinity and NaN ("-0.0" is ok).

In MIDAS, JSON support is provided by an ODB data encoder (in odb.c), an ODB "JSON paste" decoder (in json_paste.cxx) and a general purpose JSON encoder/decoder (mjson.h, mjson.cxx, see https://daq.triumf.ca/~daqweb/doc/midas-devel/html/mjson_8h.html and https://daq.triumf.ca/~daqweb/doc/midas-devel/html/class_m_json_node.html).

The MIDAS implementation of JSON has following variances from the JSON standard:
* numerical values +Infinity, -Infinity and NaN are encoded and decoded as JSON strings "Infinity", "-Infinity" and "NaN". This is compatible with most in-browser JSON implementations. See also http://stackoverflow.com/questions/1423081/json-left-out-infinity-and-nan-json-status-in-ecmascript and similar.
* numerical values that are usually presented as hex numbers, such a DWORD values, are encoded as JSON strings, i.e. "0x55b961c8".

== JSON encoding of ODB data ==

MIDAS has 3 way to encode ODB data into JSON:
* "save" format for saving all ODB data and metadata, ODB can be fully reloaded or restored from an ODB JSON save file. Links are preserved as links, upper and lower case in names of ODB keys is preserved.
* "db_values" format for exporting ODB data to web pages: links are followed to their final values, '''ODB key names are converted to lower case''' for use with case-sensitive languages such as Javascript.
* "list" format encodes a single ODB directory and returns the full information printed by the odbedit "ls -l" command.

For example:

=== JSON "save" format: db_copy_json_save() ===

The "save" format encodes all ODB data and metadata. ODB can be fully reloaded or restored from ODB JSON save files.

<pre>
$ odbedit
odbedit> cd runinfo
[local:testexpt:S]/Runinfo>json
status: 1, json: {
"State/key" : { "type" : 7, "access_mode" : 7, "last_written" : 1438212553 },
"State" : 1,
"Online Mode/key" : { "type" : 7, "access_mode" : 7, "last_written" : 1436830326 },
"Online Mode" : 1,
"Run number/key" : { "type" : 7, "access_mode" : 7, "last_written" : 1438212481 },
"Run number" : 13585,
"Transition in progress/key" : { "type" : 7, "access_mode" : 7, "last_written" : 1438212553 },
"Transition in progress" : 0,
"Start abort/key" : { "type" : 7, "access_mode" : 7, "last_written" : 1438212552 },
"Start abort" : 0,
"Requested transition/key" : { "type" : 7, "access_mode" : 7, "last_written" : 1436923816 },
"Requested transition" : 0,
"Start time/key" : { "type" : 12, "item_size" : 32, "access_mode" : 7, "last_written" : 1438212481 },
"Start time" : "Wed Jul 29 16:28:01 2015",
"Start time binary/key" : { "type" : 6, "access_mode" : 7, "last_written" : 1438212481 },
"Start time binary" : "0x55b96181",
"Stop time/key" : { "type" : 12, "item_size" : 32, "access_mode" : 7, "last_written" : 1438212552 },
"Stop time" : "Wed Jul 29 16:29:12 2015",
"Stop time binary/key" : { "type" : 6, "access_mode" : 7, "last_written" : 1438212552 },
"Stop time binary" : "0x55b961c8"
}
[local:testexpt:S]/Runinfo>
</pre>

=== JSON "db_values" format: db_copy_json_values() ===

The "db_values" format is intended for easy web page development - main thing is to return easy to parse ODB values with minimal metadata (only ODB last_written is provided).

Because most programming languages and most JSON parser (including Javascript) are case sensitive, but ODB key names are not, this JSON encoding normalizes ODB key names by converting them to lower-case. (Converting spaces to underscores is also a possibility). Only the function "db_get_values" returns lower-case names - this remains the simplest way to have simple parsing of ODB JSON data in Javascript. "db_get_values" now returns an additional field for true names of ODB entries from before they were converted to lower case. This can be turned off with the "omit_names" RPC parameter.

This allows easy use of parsed JSON in Javascript, i.e. runinfo.state or runinfo["run number"] while avoiding case-matching getter functions (i.e. get_case_insensitive_property(runinfo, "state")).

Symlinks are followed to their final values and subdirectories are recursed.

An option is provided to '''transfer the minimum amount of data''' by suppressing the 'last_written' value and the true names by setting the RPC parameters "omit_last_written" and "omit_names". See $MIDASSYS/examples/javascript1/example.html.

Also you can specify a timestamp and only data that is newer will be returned (caveats: no way to get rid of empty directories, for now, and no way to specify timestamps for individual array elements - you get the whole array or none of it).

<pre>
$ odbedit
odbedit> cd runinfo
[local:testexpt:S]/Runinfo>jsvalues
status: 1, json: {
"state/last_written" : 1438212553,
"state" : 1,
"online mode/last_written" : 1436830326,
"online mode" : 1,
"run number/last_written" : 1438212481,
"run number" : 13585,
"transition in progress/last_written" : 1438212553,
"transition in progress" : 0,
"start abort/last_written" : 1438212552,
"start abort" : 0,
"requested transition/last_written" : 1436923816,
"requested transition" : 0,
"start time/last_written" : 1438212481,
"start time" : "Wed Jul 29 16:28:01 2015",
"start time binary/last_written" : 1438212481,
"start time binary" : "0x55b96181",
"stop time/last_written" : 1438212552,
"stop time" : "Wed Jul 29 16:29:12 2015",
"stop time binary/last_written" : 1438212552,
"stop time binary" : "0x55b961c8"
}
[local:testexpt:S]/Runinfo>
</pre>

=== JSON "ls" format: db_copy_json_ls() ===

The "ls" format returns all the data printed by odbedit command "ls -l" and shown by the mhttpd ODB editor web page. It is intended for implementing web ODB editor functions.

Note how subdirectories are encoded as empty JSON objects "{}".

<pre>
$ odbedit
odbedit> cd experiment
[local:testexpt:S]/Experiment>jsls
jsls "/Experiment", status: 1, json: {
"Name/key" : { "type" : 12, "item_size" : 32, "access_mode" : 7, "last_written" : 1448038414 },
"Name" : "testexpt",
"Buffer sizes" : { },
"edit on start" : { },
"Security" : { },
"Transition debug flag/key" : { "type" : 7, "access_mode" : 7, "last_written" : 1436830326 },
"Transition debug flag" : 0,
"Transition timeout/key" : { "type" : 7, "access_mode" : 7, "last_written" : 1436830326 },
"Transition timeout" : 30000,
...
</pre>

== Access to ODB arrays ==

Some (not all) JSON-RPC methods allow access to individual array elements in ODB, i.e. {{Odbpath|path=/equipment/rpcexample/settings/a[10]}}.

RPC methods that can do this are:
* db_copy
* db_get_values
* db_paste

=== Supported array index syntax ===
An array index syntax has been implemented to make it easier to write individual array elements (Table 1)
;Table 1
{| class="wikitable"
|-
! Array Syntax !! Array Elements !! Number of elements/data values
|-
| a[1] || 1 || 1
|-
| a[1,2,3] || 1,2,3 || 3
|-
| a[1-3] || 1,2,3 || 3
|-
| a[3-1] || 3,2,1 || 3
|-
| a[1,2,3-5,6] || 1,2,3,4,5,6 || 6
|-
| a[1-3,4-6,7-9]|| 1,2,3,4,5,6,7,8,9 || 9
|-
| a[3-0,6-4,9-7] || 3,2,1,6,5,4,9,8,7 || 9
|-
| a[4,2,5-6,8] || 4,2,5,6,8 || 5
|-
| a || 0-n || n <sup>**</sup>
|}
<sup>**</sup> <small>n=number of data values supplied - see [[#array name only]].</small>

See [[#Writing an array]] and [[#Reading an array]] for examples.

== JSON-RPC general information ==

* JSON-RPC standard: https://daq.triumf.ca/~daqweb/doc/midas-devel/doc/jsonrpc/JSON-RPC%202.0%20Specification.html
* JSON-RPC home page: http://www.jsonrpc.org/specification
* JSON-RPC via HTTP transport: https://daq.triumf.ca/~daqweb/doc/midas-devel/doc/jsonrpc/simple%20is%20better%20-%20JSON-RPC%202.0%20Transport_%20HTTP.html
* http://www.simple-is-better.org/json-rpc/index.html

== Javascript client library ==

MIDAS provides a simple client library:
* documentation, see the mjsonrpc functions: https://daq.triumf.ca/~daqweb/doc/midas-develop/html/group__mjsonrpc__js.html
* source code, see the mjsonrpc functions: https://daq.triumf.ca/~daqweb/doc/midas-develop/resources/mhttpd.js

The MIDAS JSON RPC client library is based on the '''Javascript Promise''' pattern:

* http://www.html5rocks.com/en/tutorials/es6/promises/
* https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise

A simple example using the Promise API to display an ODB value on a web page:

<pre>
mjsonrpc_db_get_values(["/runinfo/run number"]).then(function(rpc) {
document.getElementById("run_number").innerHTML = rpc.result.data[0];
}).catch(function(error) {
mjsonrpc_error_alert(error);
});
</pre>

A partial list of available javascript functions. For the full list, and for full documentation, please go to the doxygen-generated documentation at
https://daq.triumf.ca/~daqweb/doc/midas-devel/html/mhttpd_8js.html

* function mjsonrpc_set_url (url) - set the URL of the MIDAS JSON-RPC server, if different from web page URL. Cross-site access is fully supported (see CORS).
* function mjsonrpc_call (method, params, id) - call arbitrary RPC method
* function mjsonrpc_start_program (name, id, callback, error_callback)
* function mjsonrpc_stop_program (name, unique, id, callback, error_callback)
* function mjsonrpc_db_get_values (paths, id, callback, error_callback) - read ODB values
* function mjsonrpc_db_paste (paths, values, id, callback, error_callback) - write ODB values

=== Batch Requests ===

The MIDAS mjson_rpc supports making combining together multiple different requests into the same HTTP request. This batch mode requesting is much more efficient and should be used whenever possible. An example of a mjson_rpc batch request for the transition status and ODB values is shown here:

<pre>
var req = new Array;
req.push(mjsonrpc_make_request("cm_transition_status"));
req.push(mjsonrpc_make_request("db_get_values", {"paths": ["/runinfo"]}));
mjsonrpc_send_request(req).then(function (rpc) {
USER CODE HERE
}).catch(function (error) {
});
</pre>

== Examples ==

Only a few examples are given below. For more examples:
* look elsewhere on this page
* look at the example experiment examples/javascript1/example.html
* look at the doxygen-generated documentation for mjsonrpc_xxx functions
* look at the implementation of the functions
* look at the implementation of mhttpd internal web pages (functions mhttpd_xxx in mhttpd.js)

<pre>
$ curl -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","id":null,"method":"db_get_values","params":{"paths":["/runinfo/run number"]}}' 'http://localhost:8080?mjsonrpc'
{"jsonrpc": "2.0","result":{"data":[324],"status":[1],"last_written":[1443570804]},"id":null}
$
</pre>

=== Read ODB data ===
The following code illustrates how to use function '''mjsonrpc_db_get_values()''' (see [https://daq.triumf.ca/~daqweb/doc/midas-devel/htm/group__mjsonrpc__js.html#ga80cf049d190f57f6a3f6004791d7f0e9| rpc get_values]) to read data from the ODB. Some of the data are displayed using InnerHTML. The data are read every 10 seconds. The time changes and a counter increments each time the data are read.
<pre>
<html>
<head>
<title>My Title</title>
<script src='mhttpd.js'>
</script>
<script>
var updatePeriod = 10000; // in msec
var updateTimerId = 0;
var counter = 0;

function update() {
clearTimeout(updateTimerId);
load();
if (updatePeriod > 0)
updateTimerId = setTimeout('update()', updatePeriod);
}
function load() {
counter++;
document.getElementById('LastUpdated').innerHTML = "Updating..." + new Date;
document.getElementById('counter').innerHTML = 'Counter: '+ counter

mjsonrpc_db_get_values(["/Runinfo","/Experiment/name"]).then(function(rpc) {
var runinfo= rpc.result.data[0]
var name = rpc.result.data[1]
document.getElementById("name").innerHTML ='Experiment name ='+ name
document.getElementById("state").innerHTML ='Run State='+ runinfo.state
document.getElementById("rn").innerHTML ='Run number='+ runinfo["run number"]
document.getElementById("status").innerHTML = 'Status: '+ rpc.result.status
}).catch(function(error) {
mjsonrpc_error_alert(error);
});
}
</script>
</head>
<body>
<h2> Javascript code example using mjson_db_get_values with Promises </h2>
<p id="LastUpdated">Last updated: never</p>
<p id="rn">Run Number : unknown</p>
<p id="state">Run State : unknown</p>
<p id="name">Experiment name : unknown</p>
<p id="status">Status : unknown</p>
<p id="counter">Counter: zero</p>
<script>
update()
</script>
</body>
</pre>
When run as a [[Custom Page]] using the web server [[mhttpd]], the above html code looks like this:
[[File: mjson_example1.jpg|center|frame|Figure 1: code to read from ODB run as a Custom Page]]
<br clear=all> 

The status value (rpc.result.status) is an array.
* rpc.result.status[0] is the status from reading "/Runinfo", and
* rpc.result.status[1] is the status from reading "/Experiment/name".
A value of 1 means success.
If the path does not exist, the status value will be 312, corresponding to the error DB_NO_KEY defined in midas.h.

=== Write ODB data and read it back ===
The following example illustrates how to write ODB data using the function '''mjsonrpc_db_paste()''' (see [https://daq.triumf.ca/~daqweb/doc/midas-devel/html/group__mjsonrpc__js.html#ga2a1da2269d82fbb9edf410a9241997b8| rpc db_paste]). In this example, when the "Set" button is pressed, data are written to the ODB keys {{Odbpath|path=test}}(integer), {{Odbpath|path=pi}}(float) and {{Odbpath|path=my_string}}(string), all in the ODB subdirectory {{Odbpath|path=/equipment/rpcexample/settings/}}. When the "Read" button is pressed, the three ODB keys are read and the data written to the screen (Figure 2). For convenience, in function set(), the paths of the ODB keys to be written are stored in the array "paths". Unlike the example above, there is no automatic update.
<pre>
<html>
<head>
<title>My Custom Page Title</title>
<script src='mhttpd.js'>
</script>
<script>
var counter = 0;

function load() {
counter++;
document.getElementById('LastUpdated').innerHTML = "Updating..." + new Date;
mjsonrpc_db_get_values(["/equipment/rpcexample/settings/"]).then(function(rpc) {
settings= rpc.result.data[0]
document.getElementById("test").innerHTML ='Integer test ='+ settings.test
document.getElementById("pi").innerHTML ='Float pi ='+ settings.pi
document.getElementById("string").innerHTML ='String my_string='+ settings["my string"]
document.getElementById("status").innerHTML = 'Read Status: '+ rpc.result.status
}).catch(function(error) {
mjsonrpc_error_alert(error);
});
}

function set() {
var paths=["/equipment/rpcexample/settings/test","/equipment/rpcexample/settings/pi","/equipment/rpcexample/settings/my string"];
mjsonrpc_db_paste(paths, [10,3.1416,"hallo world"]).then(function(rpc) {
result=rpc.result;
document.getElementById("wstatus").innerHTML = 'Write status '+rpc.result.status
}).catch(function(error) {
mjsonrpc_error_alert(error);
});
}
</script>
</head>
<body>
<h2> Example code using mjsonrpc calls to write and read </h2>
<p id="LastUpdated">Last updated: never</p>
<p id="test"> Test : unknown</p>
<p id="pi">Pi : unknown</p>
<p id="string">String : unknown</p>
<p id="status">Read Status : unknown</p>
<p id="wstatus">Write Status: zero</p>
<p> <input type=button value='Set values' onClick='set();'> </input>
<input type=button value='Read values' onClick='load();'></input> >/p>
</body>
</pre>
When run as a [[Custom Page]] using the web server [[mhttpd]], the output from the above html code is shown in Figure 2 below.
{| class="wikitable"
|-
! Figure 2a: Initial custom page !! Figure 2b: After pressing "Set" button !! Figure 2c: After pressing "Read" button
|-
|[[File: mjson_example2a.jpg|frame]] || [[File: mjson_example2b.jpg|frame ]] || [[File: mjson_example2c.jpg|frame]]
|}
<br clear=all> 

After the data is written (Figure 2b) the write status is shown.
The status value (rpc.result.status) is an array with each element showing the status of the three write operations to the three keys, i.e.
* rpc.result.status[0] is the status from writing "test", and
* rpc.result.status[1] is the status from writing "pi".
* rpc.result.status[2] is the status from writing "my_string"
A value of 1 means success.
After the data is read (Figure 2c), the values read and the read status is shown. In this case, the read status only has one value (1=success) because one read operation of the whole subdirectory is performed.

==== Error handling ====
If one of the paths to write does not exist, there will be an error reported in the status value. For example, if the path to write the variable "pi" does not exist, the write status will be
: Write status 1,312,1
The value 312 is that of the error DB_NO_KEY defined in midas.h.

If the number of data values supplied to the function mjsonrpc_db_paste() does not equal the number of paths (i.e. lengths of paths and data arrays are not equal) an error popup will result (Figure 3). The error message also contains the response ID - see [https://daq.triumf.ca/~daqweb/doc/midas-devel/html/group__mjsonrpc__js.html#ga2a1da2269d82fbb9edf410a9241997b8| rpc db_paste] for more information.
[[File: mjson_slerr.jpg|center|frame|Figure 3: Error popup when lengths of paths array and data array are not equal]]
<br clear=all> 

=== Writing an array ===
The following example shows using mjsonrpc_db_paste() to write to an array in ODB. See above for [[#supported array index syntax]].
Because each array element is accessed individually, each array element value comes with a corresponding status value of odb db_get_data_index(), encoded as an array (i.e. rpc.result.status in example below). Note that the data to be written to the array elements must be enclosed by their own square brackets [] and the number of data values must match the number of array elements listed (except when the array name is used alone - see [[#array name only]]). Too few data values will throw an error, too many will be ignored.
If the array in the ODB is not large enough for the number of elements and data to be written, it will be expanded automatically.

==== Writing to a variable and an array ====
The following example shows using mjsonrpc_db_paste() to
* write "9" to an integer variable called "test", and to
* write values to a number of elements of the array "array"
Both "test" and "array" are keys in the ODB subdirectory {{Odbpath|path=/equipment/rpcexample/settings/}}.
<pre>
mjsonrpc_db_paste(["/equipment/rpcexample/settings/test","/equipment/rpcexample/settings/array[3-1,4,5,8-10]"], [9,[1,2,3,4,5,8,9,10]]).then(function(rpc) {
document.getElementById("wstatus").innerHTML ='Set Status='+ rpc.result.status
}).catch(function(error) {
mjsonrpc_error_alert(error);
});
</pre>
Assuming the array was filled with zeroes to start with, after writing to the array and [[#reading an array|reading it back]], it would now contain the values
: Array= 0,3,2,1,4,5,0,0,8,9,10,11
: Set Status = 1,1,1,1,1,1,1,1,1 (rpc.result.status)
There are 9 elements in the rpc.result.status array, where 1=success. The first element is the status after writing "test", the next 8 the status after writing each array element.

==== Automatically expand the array ====
If the array in the ODB contains 12 elements, writing
mjsonrpc_db_paste(["/equipment/rpcexample/settings/test","/equipment/rpcexample/settings/array[3-1,4,5,8-10,14]"], [9,[1,2,3,4,5,8,9,10,14] ]).then(function(rpc) { ...
will automatically expand the array to 15 elements.

==== Too few data values ====
Supplying too few data values, e.g. writing
mjsonrpc_db_paste(["/equipment/rpcexample/settings/array[4,5,8-10]"], [ [4,5,8,9] ]).then(function(rpc) { ...
results in an error (rpc.result.status= 315) i.e. DB_TYPE_MISMATCH because there aren't enough data words supplied (4) for the number of indices (5).

<div id="array name only"></div>
==== Array name only supplied ====
If you supply just the array name, then you do not need to supply the same number of elements as the array length. For example,
mjsonrpc_db_paste(["/equipment/rpcexample/settings/array"],[ [7,6,0] ]).then(function(rpc){ ...
will write the first three elements of the array to 7,6,0. Other array elements will be untouched. In this case, there is only one status value for the whole array.
: Array= 7,6,0,1,4,5,0,0,8,9,10,11
: Set Status = 1 (rpc.result.status)

==== Set all elements to one value ====
If you want to set all 19 elements of an array to 1, you can write
<pre>
mjsonrpc_db_paste(["/equipment/rpcexample/settings/array[0-18]"], [1]).then(function(rpc) { ...
</pre>
or to set a group of indices to 999, you can write
<pre>
mjsonrpc_db_paste(["/equipment/rpcexample/settings/array[1-3,4,5,8-10]"], [999]).then(function(rpc) { ...
</pre>

Note that the single value is written as [999] rather than as an array with single value, i.e. [ [999] ].

=== Reading an array ===
In the same way, you can read all or part of an array. See above for [[#Supported array index syntax]].
<pre>
var array = new Array();
mjsonrpc_db_get_values(["/Runinfo","/Experiment/name","/Equipment/rpcexample/Settings/array","/Equipment/rpcexample/Settings/array[3-6,11]"]).then(function(rpc) {
document.getElementById("status").innerHTML = 'Status : '+ result.status
var runinfo= rpc.result.data[0]
var name = rpc.result.data[1]
array = rpc.result.data[2] // whole array
document.getElementById("array").innerHTML ='Array='+ array
array=rpc.result.data[3] // array indices
document.getElementById("array_ele").innerHTML ='Array elements='+ array
}).catch(function(error) {
mjsonrpc_error_alert(error);
});
</pre>
This example gives
: Array=1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,0
: Array elements=4,5,6,7,12
: Status : 1,1,1,1,1,1,1,1 (rpc.result.status)
Note that the "Array elements" line has read the contents of indices 3-6 and 11 as requested (5 indices in total). The status array contains 8 values. The last 5 values are the status from reading the 5 array elements.

== Schema (List of all RPC methods) ==

The MIDAS JSON RPC API is documented via an automatically generated JSON Schema.

The JSON Schema ("describes your JSON data format") is not a well established standard (there is no final RFC) but seems to be in common use. Multiple 3rd party tools exist
to visualize, explore and interface with JSON documents described by JSON Schemas. For more general information go here:
* http://json-schema.org/
* https://tools.ietf.org/html/draft-zyp-json-schema-04

The MIDAS JSON RPC Schema is automatically generated by mhttpd and is <b>linked by the mhttpd "Help" page in JSON and in text format</b>.

For reference, a recent copy of the JSON RPC API Schema is pasted here from the mhttpd "help" page. For final, complete and up-to-date schema, please get your own copy from the midas "help" page.

In this schema, "?" means an optional parameter, "[]" means an array parameter. (There is an artefact: all method names have question marks because they are optional as far as the schema generator is concerned).

=== MIDAS JSON RPC API Schema ===
<pre>

-----------------------------------------------------------------------------------------------
Autogenerated schema for all MIDAS JSON-RPC methods
-----------------------------------------------------------------------------------------------
al_reset_alarm? | reset alarms
| -----------------------------------------------------------------
| params | alarms[] | array of alarm names
| | | array of | string
| -----------------------------------------------------------------
| result | status[] | return status of al_reset_alarm() for each alarm
| | | array of | integer
-----------------------------------------------------------------------------------------------
al_trigger_alarm? | trigger an alarm
| -----------------------------------------------------------------
| params | name | string | alarm name
| | message | string | alarm message
| | class | string | alarm class
| | condition | string | alarm condition
| | type | integer | alarm type (AT_xxx)
| -----------------------------------------------------------------
| result | status | integer | return status of al_trigger_alarm()
-----------------------------------------------------------------------------------------------
al_trigger_class? | trigger an alarm
| -----------------------------------------------------------------
| params | class | string | alarm class
| | message | string | alarm message
| | first? | bool | see al_trigger_class() in midas.c
| -----------------------------------------------------------------
| result | status | integer | return status of al_trigger_class()
-----------------------------------------------------------------------------------------------
bm_receive_event? | read event buffers
| -----------------------------------------------------------------
| params | buffer_name | string | name of event buffer
| | event_id? | integer | requested event id, -1 means any event id
| | trigger_mask? | integer | requested trigger mask, -1 means any trigger mask
| | get_recent? | bool | get last available event that matches this event request
| | last_event_header[]? | do not resend an event we already received: event header of last received event [event_id,trigger_mask,serial_number,time_stamp]
| | | array of | integer
| | timeout_millisec? | number | how long to wait for an event
| -----------------------------------------------------------------
| result | binary data | arraybuffer | binary event data
| | status | integer | return status of bm_open_buffer(), bm_request_event(), bm_set_cache_size(), bm_receive_alloc()
-----------------------------------------------------------------------------------------------
cm_exist? | calls MIDAS cm_exist() to check if given MIDAS program is running
| -----------------------------------------------------------------
| params | name | string | name of the program, corresponding to ODB /Programs/name
| | unique? | bool | bUnique argument to cm_exist()
| -----------------------------------------------------------------
| result | status | integer | return status of cm_exist()
-----------------------------------------------------------------------------------------------
cm_msg1? | Generate a midas message using cm_msg1()
| -----------------------------------------------------------------
| params | facility? | string | message facility, default is "midas"
| | user? | string | message user, default is "javascript_commands"
| | type? | integer | message type, MT_xxx from midas.h, default is MT_INFO
| | message | string | message text
| -----------------------------------------------------------------
| result | status | integer | return status of cm_msg1()
-----------------------------------------------------------------------------------------------
cm_msg_facilities? | get message facilities using cm_msg_facilities()
| -----------------------------------------------------------------
| result | status | integer | return status of cm_msg_facilities()
| | facilities[] | array of facility names
| | | array of | string
-----------------------------------------------------------------------------------------------
cm_msg_retrieve? | Retrieve midas messages using cm_msg_retrieve2()
| -----------------------------------------------------------------
| params | facility? | string | message facility, default is "midas"
| | min_messages? | integer | get at least this many messages, default is 1
| | time? | number | start from given timestamp, value 0 means give me newest messages, default is 0
| -----------------------------------------------------------------
| result | num_messages | integer | number of messages returned
| | messages | string | messages separated by \n
| | status | integer | return status of cm_msg_retrieve2()
-----------------------------------------------------------------------------------------------
cm_shutdown? | calls MIDAS cm_shutdown() to stop given MIDAS program
| -----------------------------------------------------------------
| params | name | string | name of the program, corresponding to ODB /Programs/name
| | unique? | bool | bUnique argument to cm_shutdown()
| -----------------------------------------------------------------
| result | status | integer | return status of cm_shutdown()
-----------------------------------------------------------------------------------------------
cm_transition? | start and stop runs
| -----------------------------------------------------------------
| params | transition | string | requested transition: TR_START, TR_STOP, TR_PAUSE, TR_RESUME
| | run_number? | integer | New run number, value 0 means /runinfo/run_number + 1, default is 0
| | async_flag? | integer | Transition type. Default is multithreaded transition TR_MTHREAD
| | debug_flag? | integer | See cm_transition(), value 1: trace to stdout, value 2: trace to midas.log
| -----------------------------------------------------------------
| result | status | integer | return status of cm_transition()
| | error_string? | string | return error string from cm_transition()
-----------------------------------------------------------------------------------------------
db_copy? | get complete ODB data in the "save" json encoding, suitable for reloading with odbedit command "load"
| -----------------------------------------------------------------
| params | paths[] | array of ODB subtree paths
| | | array of | string
| -----------------------------------------------------------------
| result | data[] | keys and values of ODB data for each path
| | | array of | object
| | status[] | return status of db_copy_json_save() for each path
| | | array of | integer
-----------------------------------------------------------------------------------------------
db_create? | Create new ODB entries
| -----------------------------------------------------------------
| params[] | array of ODB paths to be created
| | array of | arguments to db_create_key() and db_set_num_values()
| | | path | string | ODB path to be created
| | | type | integer | MIDAS TID_xxx type
| | | array_length? | integer | optional array length, default is 1
| | | string_length? | integer | for TID_STRING, optional string length, default is NAME_LENGTH
| -----------------------------------------------------------------
| result | status[] | return status of db_create_key(), db_set_num_values() and db_set_data() (for TID_STRING) for each path
| | | array of | integer
-----------------------------------------------------------------------------------------------
db_delete? | delete ODB keys
| -----------------------------------------------------------------
| params | paths[] | array of ODB paths to delete
| | | array of | string
| -----------------------------------------------------------------
| result | status[] | return status of db_delete_key() for each path
| | | array of | integer
-----------------------------------------------------------------------------------------------
db_get_values? | get values of ODB data from given subtrees
| -----------------------------------------------------------------
| params | paths[] | array of ODB subtree paths, see note on array indices
| | | array of | string
| | omit_names? | bool | omit the /name entries
| | omit_last_written? | bool | omit the /last_written entries and the last_written[] result
| | omit_tid? | bool | omit the tid[] result
| | omit_old_timestamp? | number | omit data older than given ODB timestamp
| | preserve_case? | bool | preserve the capitalization of ODB key names (WARNING: ODB is not case sensitive); note that this will also have side effect of setting the omit_names option
| -----------------------------------------------------------------
| result | data[] | values of ODB data for each path, all key names are in lower case, all symlinks are followed
| | | array of | any
| | status[] | return status of db_copy_json_values() or db_copy_json_index() for each path
| | | array of | integer
| | tid[]? | odb type id for each path, absent if omit_tid is true
| | | array of | integer
| | last_written[]? | last_written value of the ODB subtree for each path, absent if omit_last_written is true
| | | array of | number
-----------------------------------------------------------------------------------------------
db_key? | get ODB keys
| -----------------------------------------------------------------
| params | paths[] | array of ODB paths
| | | array of | string
| -----------------------------------------------------------------
| result | status[] | return status of db_key() for each path
| | | array of | integer
| | keys[] | key data for each path
| | | array of | object
| | keys[] | key type TID_xxx
| | | array of | integer
| | keys[] | array length, 1 for normal entries
| | | array of | integer
| | keys[] | key name
| | | array of | string
| | keys[] | data total size in bytes
| | | array of | integer
| | keys[] | array element size, string length for TID_STRING
| | | array of | integer
| | keys[] | access mode bitmap of MODE_xxx
| | | array of | integer
| | keys[] | number of hotlinks attached to this key
| | | array of | integer
| | keys[] | timestamp when data was last updated
| | | array of | integer
-----------------------------------------------------------------------------------------------
db_link? | Create ODB symlinks
| -----------------------------------------------------------------
| params | new_links[] | array of new symlinks to be created
| | | array of | string
| | target_paths[] | array of existing ODB paths for each link
| | | array of | string
| -----------------------------------------------------------------
| result | status[] | return status of db_create_link() for each path
| | | array of | integer
-----------------------------------------------------------------------------------------------
db_load? | Save ODB subtree to file
| -----------------------------------------------------------------
| params | filename | string | Filename to read ODB contents from
| -----------------------------------------------------------------
| result | status | integer | return status of db_load
-----------------------------------------------------------------------------------------------
db_ls? | get contents of given ODB subdirectory in the "ls" json encoding - similar to odbedit command "ls -l"
| -----------------------------------------------------------------
| params | paths[] | array of ODB subtree paths
| | | array of | string
| -----------------------------------------------------------------
| result | data[] | keys and values of ODB data for each path
| | | array of | object
| | status[] | return status of db_copy_json_ls() for each path
| | | array of | integer
-----------------------------------------------------------------------------------------------
db_paste? | write data into ODB
| -----------------------------------------------------------------
| params | paths[] | array of ODB subtree paths, see note on array indices
| | | array of | string
| | values[] | array of data values written to ODB via db_paste_json() for each path
| | | array of | any
| -----------------------------------------------------------------
| result | status[] | array of return status of db_paste_json() for each path
| | | array of | integer
-----------------------------------------------------------------------------------------------
db_rename? | Change size of ODB arrays
| -----------------------------------------------------------------
| params | paths[] | array of ODB paths to rename
| | | array of | string
| | new_names[] | array of new names for each ODB path
| | | array of | string
| -----------------------------------------------------------------
| result | status[] | return status of db_rename_key() for each path
| | | array of | integer
-----------------------------------------------------------------------------------------------
db_reorder? | Change order of ODB keys in a subdirectory
| -----------------------------------------------------------------
| params | paths[] | array of new symlinks to be created
| | | array of | string
| | indices[] | array of existing ODB paths for each link
| | | array of | integer
| -----------------------------------------------------------------
| result | status[] | return status of db_reorder_key() for each path
| | | array of | integer
-----------------------------------------------------------------------------------------------
db_resize? | Change size of ODB arrays
| -----------------------------------------------------------------
| params | paths[] | array of ODB paths to resize
| | | array of | string
| | new_lengths[] | array of new lengths for each ODB path
| | | array of | integer
| -----------------------------------------------------------------
| result | status[] | return status of db_set_num_values() for each path
| | | array of | integer
-----------------------------------------------------------------------------------------------
db_resize_string? | Change size of ODB string arrays
| -----------------------------------------------------------------
| params | paths[] | array of ODB paths to resize
| | | array of | string
| | new_lengths[] | array of new lengths for each ODB path
| | | array of | integer
| | new_string_lengths[] | array of new string lengths for each ODB path
| | | array of | integer
| -----------------------------------------------------------------
| result | status[] | return status of db_resize_string() for each path
| | | array of | integer
-----------------------------------------------------------------------------------------------
db_save? | Save ODB subtree to file
| -----------------------------------------------------------------
| params | path | string | ODB path
| | filename | string | Filename so save ODB contents to
| -----------------------------------------------------------------
| result | status | integer | return status of db_save
-----------------------------------------------------------------------------------------------
db_scl? | Show ODB clients
| -----------------------------------------------------------------
| result | scl | json | return value of db_scl()
-----------------------------------------------------------------------------------------------
db_sor? | Show ODB open records starting from given ODB path
| -----------------------------------------------------------------
| params | path? | string | ODB path
| -----------------------------------------------------------------
| result | sor | json | return value of db_sor()
-----------------------------------------------------------------------------------------------
el_delete? | Delete elog message
| -----------------------------------------------------------------
| params | tag | string | tag of message to delete
| -----------------------------------------------------------------
| result | status | integer | return status of el_delete
-----------------------------------------------------------------------------------------------
el_query? | Query elog messages
| -----------------------------------------------------------------
| params | last_n_hours? | integer | return messages from the last N hours
| -----------------------------------------------------------------
| result | status | integer | return status of el_retrieve
| | msg[] | message tag
| | | array of | string
-----------------------------------------------------------------------------------------------
el_retrieve? | Get an elog message
| -----------------------------------------------------------------
| params | tag | string | elog message tag
| -----------------------------------------------------------------
| result | status | integer | return status of el_retrieve
| | msg.tag | string | message tag
-----------------------------------------------------------------------------------------------
exec_script? | execute custom script defined in ODB /Script (scripts show in the menu) or /CustomScript (scripts from custom pages)
| -----------------------------------------------------------------
| params | script? | string | Execute ODB /Script/xxx
| | customscript? | string | Execute ODB /CustomScript/xxx
| -----------------------------------------------------------------
| result | status | integer | return status of cm_exec_script()
-----------------------------------------------------------------------------------------------
ext_list_files? | js_ext_list_files
| -----------------------------------------------------------------
| params | subdir | string | List files in experiment_directory/userfiles/subdir
| | fileext | string | Filename extension
| -----------------------------------------------------------------
| result | status | integer | return status of midas library calls
| | path | string | Search path
| | subdirs[] | list of subdirectories
| | | array of | string
| | files[] | script filename
| | | array of | string
| | files[] | script description
| | | array of | string
-----------------------------------------------------------------------------------------------
ext_read_file? | js_ext_read_script
| -----------------------------------------------------------------
| params | filename | string | File name, read from experiment_directory/userfiles/filename
| -----------------------------------------------------------------
| result | content | string | ASCII file content
| | status | integer | return status of midas library calls
| | error | string | error text
-----------------------------------------------------------------------------------------------
ext_save_file? | js_ext_save_file
| -----------------------------------------------------------------
| params | filename | string | File name, save in experiment_directory/userfiles/filename
| | script | string | ASCII content
| -----------------------------------------------------------------
| result | status | integer | return status of midas library calls
| | error | string | error text
-----------------------------------------------------------------------------------------------
get_alarms? | get alarm data
| -----------------------------------------------------------------
| params | get_all? | bool | get all alarms, even in alarm system not active and alarms not triggered
| -----------------------------------------------------------------
| result | status | integer | return status of midas library calls
| | alarm_system_active | bool | value of ODB "/Alarms/alarm system active"
| | alarms | object | alarm data, keyed by alarm name
| | alarms[] | alarm is triggered
| | | array of | bool
| | alarms[] | alarm is enabled
| | | array of | bool
| | alarms[] | alarm class
| | | array of | string
| | alarms[] | alarm type AT_xxx
| | | array of | integer
| | alarms[] | display background color
| | | array of | string
| | alarms[] | display foreground color
| | | array of | string
| | alarms[] | alarm ODB message field
| | | array of | string
| | alarms[] | alarm ODB condition field
| | | array of | string
| | alarms[] | evaluated alarm condition (AT_EVALUATED alarms only)
| | | array of | string
| | alarms[] | next time the periodic alarm will fire (AT_PERIODIC alarms only)
| | | array of | string
| | alarms[] | time when alarm was triggered
| | | array of | string
| | alarms[] | final alarm text shown to user by mhttpd
| | | array of | string
-----------------------------------------------------------------------------------------------
get_debug? | get current value of mjsonrpc_debug
| -----------------------------------------------------------------
| params | any | there are no input parameters
| -----------------------------------------------------------------
| result | integer | current value of mjsonrpc_debug
-----------------------------------------------------------------------------------------------
get_http_trace? | get current value of mhttpd http_trace
| -----------------------------------------------------------------
| params | any | there are no input parameters
| -----------------------------------------------------------------
| result | integer | current value of http_trace
-----------------------------------------------------------------------------------------------
get_schema? | Get the MIDAS JSON-RPC schema JSON object
| -----------------------------------------------------------------
| params | any | there are no input parameters
| -----------------------------------------------------------------
| result | object | returns the MIDAS JSON-RPC schema JSON object
-----------------------------------------------------------------------------------------------
get_sleep? | get current value of mjsonrpc_sleep
| -----------------------------------------------------------------
| params | any | there are no input parameters
| -----------------------------------------------------------------
| result | integer | current value of mjsonrpc_sleep
-----------------------------------------------------------------------------------------------
get_time? | get current value of mjsonrpc_time
| -----------------------------------------------------------------
| params | any | there are no input parameters
| -----------------------------------------------------------------
| result | integer | current value of mjsonrpc_time
-----------------------------------------------------------------------------------------------
get_timezone? | get current server timezone offset in seconds
| -----------------------------------------------------------------
| params | any | there are no input parameters
| -----------------------------------------------------------------
| result | integer | offset in seconds
-----------------------------------------------------------------------------------------------
hs_get_active_events? | get list of active history events using hs_read_event_list()
| -----------------------------------------------------------------
| result | status | integer | return status of hs_read_event_list()
| | events[] | array of history event names
| | | array of | string
-----------------------------------------------------------------------------------------------
hs_get_channels? | get list of history channels in /Logger/History
| -----------------------------------------------------------------
| result | status | integer | return status of hs_get_events()
| | default_channel | string | name of the default logger history channel in /History/LoggerHistoryChannel
| | channels[] | logger history channel names
| | | array of | string
-----------------------------------------------------------------------------------------------
hs_get_events? | get list of history events that existed at give time using hs_get_events()
| -----------------------------------------------------------------
| params | channel? | string | midas history channel, default is the default reader channel
| | time? | number | timestamp, value 0 means current time, default is 0
| -----------------------------------------------------------------
| result | status | integer | return status of hs_get_events()
| | channel | string | logger history channel name
| | events[] | array of history event names
| | | array of | string
-----------------------------------------------------------------------------------------------
hs_get_last_written? | get list of history tags for given history events that existed at give time using hs_get_last_written()
| -----------------------------------------------------------------
| params | channel? | string | midas history channel, default is the default reader channel
| | time? | number | timestamp, value 0 means current time, default is 0
| | events[] | array of history event names
| | | array of | string
| | tags[] | array of history event tag names
| | | array of | string
| | index[] | array of history event tag array indices
| | | array of | string
| -----------------------------------------------------------------
| result | status | integer | return status
| | channel | string | logger history channel name
| | last_written[] | array of last-written times for each history event
| | | array of | number
-----------------------------------------------------------------------------------------------
hs_get_tags? | get list of history tags for given history events that existed at give time using hs_get_tags()
| -----------------------------------------------------------------
| params | channel? | string | midas history channel, default is the default reader channel
| | time? | number | timestamp, value 0 means current time, default is 0
| | events[]? | array of history event names, default is get all events using hs_get_events()
| | | array of | string
| -----------------------------------------------------------------
| result | status | integer | return status
| | channel | string | logger history channel name
| | events[] | array of history event names for each history event
| | | array of | string
| | events[] | array of status ohistory tags for each history event
| | | array of | integer
| | events[] | array of history tags for each history event
| | | array of | string
| | events[] | history tag name
| | | array of | string
| | events[] | history tag midas data type
| | | array of | integer
| | events[] | history tag number of array elements, omitted if 1
| | | array of | integer
-----------------------------------------------------------------------------------------------
hs_image_retrieve? | Get a list of history image files
| -----------------------------------------------------------------
| params | image? | string | image name as defined under /History/Images/<image>
| | start_time | number | start time of the data
| | end_time | number | end time of the data
| -----------------------------------------------------------------
| result | time[] | array of time stamps in seconds
| | | array of | arraybuffer
| | filename[] | array of file names
| | | array of | arraybuffer
-----------------------------------------------------------------------------------------------
hs_read? | get history data for given history events that existed at give time using hs_read_buffer()
| -----------------------------------------------------------------
| params | channel? | string | midas history channel, default is the default reader channel
| | start_time | number | start time of the data
| | end_time | number | end time of the data
| | events[] | array of history event names
| | | array of | string
| | tags[] | array of history event tag names
| | | array of | string
| | index[] | array of history event tag array indices
| | | array of | string
| -----------------------------------------------------------------
| result | status | integer | return status
| | channel | string | logger history channel name
| | data[] | array of history data
| | | array of | array
| | data[] | status for each event
| | | array of | integer
| | data[] | number of data for each event
| | | array of | integer
| | data[] | time data
| | | array of | number
| | data[] | value data
| | | array of | number
-----------------------------------------------------------------------------------------------
hs_read_arraybuffer? | get history data for given history events that existed at give time using hs_read_buffer()
| -----------------------------------------------------------------
| params | channel? | string | midas history channel, default is the default reader channel
| | start_time | number | start time of the data
| | end_time | number | end time of the data
| | events[] | array of history event names
| | | array of | string
| | tags[] | array of history event tag names
| | | array of | string
| | index[] | array of history event tag array indices
| | | array of | string
| -----------------------------------------------------------------
| result | binary data | arraybuffer | binary data, see documentation
-----------------------------------------------------------------------------------------------
hs_read_binned? | get history data for given history events that existed at give time using hs_read_buffer()
| -----------------------------------------------------------------
| params | channel? | string | midas history channel, default is the default reader channel
| | start_time | number | start time of the data
| | end_time | number | end time of the data
| | num_bins | integer | number of time bins
| | events[] | array of history event names
| | | array of | string
| | tags[] | array of history event tag names
| | | array of | string
| | index[] | array of history event tag array indices
| | | array of | string
| -----------------------------------------------------------------
| result | status | integer | return status
| | channel | string | logger history channel name
| | data[] | array of history data
| | | array of | array
| | data[] | status for each event
| | | array of | integer
| | data[] | number of data points for each event
| | | array of | integer
| | data[] | number of data points for each bin
| | | array of | integer
| | data[] | mean for each bin
| | | array of | number
| | data[] | rms for each bin
| | | array of | number
| | data[] | minimum value for each bin
| | | array of | number
| | data[] | maximum value for each bin
| | | array of | number
| | data[] | time of last data entry
| | | array of | number
| | data[] | value of last data entry
| | | array of | number
-----------------------------------------------------------------------------------------------
hs_read_binned_arraybuffer? | get history data for given history events that existed at give time using hs_read_buffer()
| -----------------------------------------------------------------
| params | channel? | string | midas history channel, default is the default reader channel
| | start_time | number | start time of the data
| | end_time | number | end time of the data
| | num_bins | integer | number of time bins
| | events[] | array of history event names
| | | array of | string
| | tags[] | array of history event tag names
| | | array of | string
| | index[] | array of history event tag array indices
| | | array of | string
| -----------------------------------------------------------------
| result | binary data | arraybuffer | binary data, see documentation
-----------------------------------------------------------------------------------------------
hs_reopen? | reopen the history channel to make sure we see the latest list of events using hs_clear_cache()
| -----------------------------------------------------------------
| params | channel? | string | midas history channel, default is the default reader channel
| -----------------------------------------------------------------
| result | status | integer | return status of hs_get_events()
| | channel | string | logger history channel name
-----------------------------------------------------------------------------------------------
jrpc? | make RPC call into frontend program via RPC_JRPC
| -----------------------------------------------------------------
| params | client_name | string | Connect to this MIDAS client, see cm_connect_client()
| | cmd | string | Command passed to client
| | args | string | Parameters passed to client as a string, could be JSON encoded
| | max_reply_length? | integer | Optional maximum length of client reply. MIDAS RPC does not support returning strings of arbitrary length, maximum length has to be known ahead of time.
| -----------------------------------------------------------------
| result | reply | string | Reply from client as a string, could be JSON encoded
| | status | integer | return status of cm_connect_client() and rpc_client_call()
-----------------------------------------------------------------------------------------------
null? | RPC method always returns null
| -----------------------------------------------------------------
| params | any | method parameters are ignored
| -----------------------------------------------------------------
| result | null | always returns null
-----------------------------------------------------------------------------------------------
seq_list_files? | js_seq_list_files
| -----------------------------------------------------------------
| params | subdir | string | List files in /Seq/State/Path/subdir
| -----------------------------------------------------------------
| result | status | integer | return status of midas library calls
| | path | string | Search path
| | subdirs[] | list of subdirectories
| | | array of | string
| | files[] | script filename
| | | array of | string
| | files[] | script description
| | | array of | string
-----------------------------------------------------------------------------------------------
seq_save_script? | js_seq_save_script
| -----------------------------------------------------------------
| params | filename | string | Script file name
| | script | string | Script text
| -----------------------------------------------------------------
| result | status | integer | return status of midas library calls
| | error | string | error text
-----------------------------------------------------------------------------------------------
set_debug? | set new value of mjsonrpc_debug
| -----------------------------------------------------------------
| params | integer | new value of mjsonrpc_debug
| -----------------------------------------------------------------
| result | integer | new value of mjsonrpc_debug
-----------------------------------------------------------------------------------------------
set_http_trace? | set new value of mhttpd http_trace
| -----------------------------------------------------------------
| params | integer | new value of http_trace
| -----------------------------------------------------------------
| result | integer | new value of http_trace
-----------------------------------------------------------------------------------------------
set_sleep? | set new value of mjsonrpc_sleep
| -----------------------------------------------------------------
| params | integer | new value of mjsonrpc_sleep
| -----------------------------------------------------------------
| result | integer | new value of mjsonrpc_sleep
-----------------------------------------------------------------------------------------------
set_time? | set new value of mjsonrpc_time
| -----------------------------------------------------------------
| params | integer | new value of mjsonrpc_time
| -----------------------------------------------------------------
| result | integer | new value of mjsonrpc_time
-----------------------------------------------------------------------------------------------
ss_millitime? | get current MIDAS time using ss_millitime()
| -----------------------------------------------------------------
| params | any | there are no input parameters
| -----------------------------------------------------------------
| result | integer | current value of ss_millitime()
-----------------------------------------------------------------------------------------------
start_program? | start MIDAS program defined in ODB /Programs/name
| -----------------------------------------------------------------
| params | name | string | name of the program, corresponding to ODB /Programs/name
| -----------------------------------------------------------------
| result | status | integer | return status of ss_system()
-----------------------------------------------------------------------------------------------
user_example1? | example of user defined RPC method that returns up to 3 results
| -----------------------------------------------------------------
| params | arg | string | example string argment
| | optional_arg? | integer | optional example integer argument
| -----------------------------------------------------------------
| result | string | string | returns the value of "arg" parameter
| | integer | integer | returns the value of "optional_arg" parameter
-----------------------------------------------------------------------------------------------
user_example2? | example of user defined RPC method that returns more than 3 results
| -----------------------------------------------------------------
| params | arg | string | example string argment
| | optional_arg? | integer | optional example integer argument
| -----------------------------------------------------------------
| result | string1 | string | returns the value of "arg" parameter
| | string2 | string | returns "hello"
| | string3 | string | returns "world!"
| | value1 | integer | returns the value of "optional_arg" parameter
| | value2 | number | returns 3.14
-----------------------------------------------------------------------------------------------
user_example3? | example of user defined RPC method that returns an error
| -----------------------------------------------------------------
| params | arg | integer | integer value, if zero, throws a JSON-RPC error
| -----------------------------------------------------------------
| result | status | integer | returns the value of "arg" parameter
</pre>
[[Category:Javascript library]]