Mjsonrpc: Difference between revisions

From MidasWiki
Jump to navigation Jump to search
(The midas documentation has moved to https://midas.triumf.ca/docs/)
Tag: Replaced
 
(36 intermediate revisions by 6 users not shown)
Line 1: Line 1:
== MIDAS JSON-RPC interface ==
The midas documentation has moved. The new documentation about the JSON-RPC interface is in:
 
* [https://midas.triumf.ca/docs/develop/api/rpc/jsonrpc/ mjsonrpc schema] (all JSON-RPC methods, and calling them from other languages), including:
== JSON general information ==
** [https://midas.triumf.ca/docs/develop/api/rpc/jsonrpc/#array-indices-in-odb-paths Array indices in ODB paths]
 
** [https://midas.triumf.ca/docs/develop/api/rpc/jsonrpc/#how-values-are-encoded How values are encoded] (hexadecimal strings, 64-bit integers, NaN and Infinity)
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.
** [https://midas.triumf.ca/docs/develop/api/rpc/jsonrpc/#key-names-in-db_get_values-results Key names in db_get_values results]
 
** [https://midas.triumf.ca/docs/develop/api/rpc/jsonrpc/#reading-only-values-that-have-changed Reading only values that have changed] (omit_old_timestamp)
JSON documents look like this:
** [https://midas.triumf.ca/docs/develop/api/rpc/jsonrpc/#sending-several-requests-at-once Sending several requests at once]
<pre>
* [https://midas.triumf.ca/docs/develop/features/core_system/odb/programming/#json-encodings-of-odb-data JSON encodings of ODB data] on the ODB: programming page (the "save", "values" and "ls" formats)
{ "Runinfo" : { "State" : 1, "Online Mode" : 1, "Run number" : 13585 } }
* [https://midas.triumf.ca/docs/develop/features/core_system/odb/programming/ ODB: programming] (examples of reading and writing ODB values and arrays)
</pre>
* [https://midas.triumf.ca/docs/develop/api/javascript/midas/ midas.js] (the JavaScript functions that call them)
 
* [https://midas.triumf.ca/docs/develop/api/javascript/#pages-that-arent-served-by-mhttpd Pages that aren't served by mhttpd] on the Midas JavaScript API page (calling mhttpd from another web server)
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.
 
== JSON encoding of ODB data ==
 
aaa
 
== JSON-RPC general information ==
 
This page is a placeholder for the documentation of the MIDAS JSON RPC interface.
 
test
 
== Javascript client library ==
 
MIDAS provides a simple client library:
https://daq.triumf.ca/~daqweb/doc/midas-devel/resources/mhttpd.js
https://daq.triumf.ca/~daqweb/doc/midas-devel/html/
 
== Examples ==
 
<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>
 
== Schema (List of all RPC methods) ==
 
<pre>
------------------------------------------------------------------------
Autogenerated schema for all MIDAS JSON-RPC methods
------------------------------------------------------------------------
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_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()
------------------------------------------------------------------------
db_copy?      | get copies of given ODB subtrees in the "save" json encoding
              | -------------------------------------------------------
              | params  | paths[]        | array of ODB subtree paths, see note on array indices
              |          |                | array of       | string
              | -------------------------------------------------------
              | result  | data[]        | copy of ODB data for each path
              |          |                | array of      | object
              |          | status[]       | return status of db_copy_json() for each path
              |          |                | array of      | integer
              |          | last_written[] | last_written value of the ODB subtree for each path
              |          |                | array of      | number
------------------------------------------------------------------------
db_create?    | get copies of given ODB subtrees in the "save" json encoding
              | -------------------------------------------------------
              | params[] | array of ODB paths to be created
              |          | array of      | arguments to db_create() and db_resize()
              |          |                | path          | string  | ODB path
              |          |                | 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() 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
              | -------------------------------------------------------
              | 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() for each path
              |          |                | array of      | integer
              |          | last_written[] | last_written value of the ODB subtree for each path
              |          |                | array of      | number
------------------------------------------------------------------------
db_paste?      | write data into ODB
              | -------------------------------------------------------
              | params  | paths[]        | array of ODB subtree paths, see note on array indices
              |          |                | array of      | string
              |          | values[]      | data to be written using db_paste_json()
              |          |                | array of      | any   
              | -------------------------------------------------------
              | result  | status[]      | return status of db_paste_json() for each path
              |          |                | array of      | integer
------------------------------------------------------------------------
get_debug?    | get current value of mjsonrpc_debug
              | -------------------------------------------------------
              | params  | any            | there are no input parameters
              | -------------------------------------------------------
              | result  | integer        | current value of mjsonrpc_debug
------------------------------------------------------------------------
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
------------------------------------------------------------------------
null?          | RPC method always returns null
              | -------------------------------------------------------
              | params  | any            | method parameters are ignored
              | -------------------------------------------------------
              | result  | null          | always returns null
------------------------------------------------------------------------
set_debug?    | set new value of mjsonrpc_debug
              | -------------------------------------------------------
              | params  | integer        | new value of mjsonrpc_debug
              | -------------------------------------------------------
              | result  | integer        | new value of mjsonrpc_debug
------------------------------------------------------------------------
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>

Latest revision as of 22:01, 30 October 2026

The midas documentation has moved. The new documentation about the JSON-RPC interface is in:

Retrieved from "https://daq00.triumf.ca/MidasWiki/index.php?title=Mjsonrpc&oldid=3772"