HYDLLP - Flat DLL Interface to Hydstra
Function
HYDLLP.DLL is a Windows DLL (Dynamic Link Library) which provides access to various aspects of Hydstra, including database information and time-series data.
HYDLLP is a simple Windows 32 bit DLL that can be linked into a program written in any language at run time. Unlike the earlier HYDLL, it requires no COM registration and no special Windows security in order to use it.
Although HYDLLP supports some other call formats for backwards compatibility reasons, all new users of the DLL should interact with it only via the JSonCall interface.
A further benefit of the JSonCall interface is that many Hydstra clients publish data on the web using web services, and the Hydstra Web Services interface simply wraps the JSonCall interface in a web skin.
A series of calls dedicated to supporting Standard Hydstra are documented separately under Standard Hydstra Data Publication.
Under certain tightly controlled situations the output from almost any Hydstra program can be made available via a HYDLLP call to DLL users inside and via web services outside the firewall. Read up on HYDLLP Templated Output for more information.
Upgrading from legacy HYDLL.DLL
The implementation of HYDLLP provides an identical set of calls to the earlier technology HYDLL. For Perl users the transition from using HYDLL to HYDLLP is almost trivial, since we have encapsulated the different calling mechanisms in HYDLLP.PM. However if you wish to convert from HYDLL to HYDLLP using other languages like VBA, C# and Delphi then the process will require significant changes, and you should study the examples distributed in \hyd\sys\misc\examples.
Data Privacy
The get_db_info, get_ts_traces and get_ts_blockinfo calls, when made available over the web, are able to publish potentially sensitive personal data about your staff and clients. You can control this with the DATAPRIV.INI, which is administered by program HYDATAPRIV. This lets you deny access to specified tables, columns, rows and timeseries data comments and user info. HYDLLP only consults DATAPRIV.INI when it detects that it is running under the Hydstra/WEB framework. Inside the firewall normal Hydstra security rules apply.
Developing REST web service URLs
All functions detailed here may be also used in web service
calls except:
clear_ts_cache
clear_db_cache
write_ts_traces
hyfiler_command
IMPORTANT
When developing web service URLs, be aware that the Perl examples listed below
must be translated to native JSON as follows:
· remove all line breaks (the whole JSON data structure request must be on the same line)
· remove unnecessary spaces between parameters (but not any vital spaces within parameter values)
· replace single quotes with double quotes
· replace all instances of the Perl reference operator '=>' with ': '
For example
{
'function' => 'get_site_list',
'version' => 1,
'params' => {
'site_list' => 'TSFILES(DSOURCES(ARCHIVE))'
}
}
becomes
{"function":"get_site_list","version":1,"params":{"site_list":"TSFILES(DSOURCES(ARCHIVE))"}}
HYDLLP JSON Calling Conventions
When calling HYDLLP using the JSonCall call we use the following conventions for passing in and returning parameters:
· Dates take the form yyyymmddhhiiee, e.g. 19741225120000
· Times take the form, hhii or hhii.ee, e.g. 1245 or 1245.01 for one second later.
·
Booleans take the form 1 (true) or 0 (false). However
the underlying
Summary of JSON Functions
Search below for complete documentation of each function.
Domain |
Function |
Description |
Time-series |
Evaluate a HYSTNS site list expression and return a list of sites |
|
Time-series |
Retrieves one or more time series traces |
|
Time-series |
Writes one or more time series traces |
|
Time-series |
Run a hyfiler command |
|
Time-series |
enumerate datasources |
|
Time-series |
enumerate sites |
|
Time-series |
return list of variables for a TS file |
|
Time-series |
return functional and descriptive details of a subvar |
|
Time-series |
return info about TS blocks |
|
Time-series |
return last time-series values |
|
Time-series |
convert data with variable |
|
Time-series |
returns an array of time, value pairs that represent the rating table. |
|
Time-series |
return GeoJSON and other field data from the site table for the provided site list |
|
Time-series |
clears time-series files from the in memory cache |
|
Database |
return table data with simple or complex filters or geo filters |
|
Database |
return list of database work areas |
|
Database |
decode database code or lookup |
|
Database |
returns an ADO connection string and table string for a Hydstra table. |
|
Database |
returns an ODBC connection string and table string for a Hydstra table |
|
Database |
write records to a database in a work area |
|
Database |
return location of documents for a record |
|
Database |
return table and key from document location |
|
Database |
return documents associated with tables |
|
Database |
return cross section details |
|
Database |
return list of groups that site(s) are a member of |
|
Database |
clears database tables from the in memory cache |
|
Misc |
controls how real numbers are encoded in JSON |
|
Misc |
return HYBATCH output details |
|
Misc |
execute multiple functions with one call |
|
Misc |
write HYDLOG entry |
|
Misc |
return a list of periods that have been influenced by modifications to various types of data (time series, rating tables, time-based tables etc). |
|
Misc |
return HYBATCH environment settings, as would be output by the HYBATCHE program |
|
Misc |
check whether a user ID and password are valid according to the PASSWD table |
|
Plots |
return small plot widgets |
|
Standard Hydstra |
get_std_unit_details |
return information about standard units |
Standard Hydstra |
get_std_parameter_list |
return all the parameters you serve and the units they are in |
Standard Hydstra |
get_std_site_list |
return list of sites that have a parameter or lie in a region |
Standard Hydstra |
get_std_trace_list |
return list of traces for a site list |
Standard Hydstra |
get_std_trace_periods |
return periods for specified sites |
Standard Hydstra |
get_std_ts_traces |
return time-series data |
Standard Hydstra |
get_std_site_geojson |
return GeoJSON and other field data from the site table for the provided site list |
Standard Hydstra |
get_std_group_list |
Return all the named site list groups specified in the SiteList section of the HYSTANDARD_CONF.ini |
Standard Hydstra |
get_std_datasource_list |
Return a list of all the datasources served and their descriptions. |
Standard Hydstra |
get_std_latest_ts_values |
Return a list of the latest time-series points for a site list. By default, it looks back to the most recent data point. All datetimes are in UTC 0. |
Standard Hydstra |
get_kiwis_ts_list |
Return all the time-series traces and periods of record associated with this site list. All datetimes are in UTC 0. |
Templated output |
Returns a list of all templated output applications, and their available parameters |
|
Templated output |
Runs a templated output application and returns its output |
Introduction to JSON
The preferred way of using HYDLLP is to use the JSonCall interface. JSON (JavaScript Object Notation) is as methodology for encoding complex objects into a character string. You should visit www.json.org for information on JSON, which you will need to have in order to build parameter strings and parse return objects from the JSonCall entry point in HYDLLP.
JSON (JavaScript Object Notation) is a lightweight data-interchange format. It is easy for humans to read and write. It is easy for machines to parse and generate. It is based on a subset of the JavaScript Programming Language, Standard ECMA-262 3rd Edition - December 1999. JSON is a text format that is completely language independent but uses conventions that are familiar to programmers of the C-family of languages, including C, C++, C#, Java, JavaScript, Perl, Python, and many others. These properties make JSON an ideal data-interchange language.
JSON is built on two structures:
A collection of name/value pairs. In various languages, this is realized as an object, record, struct, dictionary, hash table, keyed list, or associative array.
An ordered list of values. In most languages, this is realized as an array, vector, list, or sequence.
These are universal data structures. Virtually all modern programming languages support them in one form or another. It makes sense that a data format that is interchangable with programming languages also be based on these structures.
In JSON, they take on these forms:
An object is an unordered set of name/value pairs. An object begins with { (left brace) and ends with } (right brace). Each name is followed by : (colon) and the name/value pairs are separated by , (comma).
An array is an ordered collection of values. An array begins with [ (left bracket) and ends with ] (right bracket). Values are separated by , (comma).
A value can be a string in double quotes, or a number, or true or false or null, or an object or an array. These structures can be nested.
A string is a sequence of zero or more Unicode characters, wrapped in double quotes, using backslash escapes. A character is represented as a single character string. A string is very much like a C or Java string.
A number is very much like a C or Java number, except that the octal and hexadecimal formats are not used.
Whitespace can be inserted between any pair of tokens. Excepting a few encoding details, that completely describes the language.
Using JSonCall from Perl
We provide a wrapper function in HYDDLLP.PM named JSonCall which allows you to pass in and receive back native Perl structures (hashes and arrays). The transcoding between Perl hashes and JSON is handled inside HYDLLP and you don't need to worry about it.
JSonCall checks the return from a DLL call and if the buffer was too small on the initial call it automatically enlarges the buffer to a suitable size and runs the request again. While it is advisable to try and get the buffer size right first time, this at least means your program works even if you guess wrong. Note that there is also a significant overhead in specifying a ridiculously large buffer like 1,000,000 so it's a balancing act. The default buffer size is 1000 bytes. Note also that the DLL stores your response when the buffer size is too small, this response will get returned when JSonCall tries again with a bigger buffer.
The following program should give you some ideas on how to use JSonCall from Perl:
require 'hydlib.pl';
use HydDLLp;
use JSON;
use strict;
#examples of every JSonCall call available
main: {
OpenFile(*hREPORT,HyconfigValue('TEMPPATH').'junk','>');
my $dll=HydDllp->New();
sub dotest {
my ($testname,$requestref,$buffersize)=@_;
my $jsonstr=JSON::XS->new->utf8->space_after->pretty->encode
($requestref);
Prt('-RLS',"Testing HYDLLP JSonCall with $testname
--------------------------------------------------------------\n\n");
#Prt('-RLS',"Input JSON String:\n",$jsonstr,"\n");
Prt('-RLS',"Perl hash representation input string is:\n",HashDump($requestref),"\n");
my $responseref=$dll->JSonCall($requestref,$buffersize);
my $responsestr=JSON::XS->new->utf8->space_after->pretty->encode
($responseref);
#Prt('-RLS',"Output JSON String:\n",$responsestr,"\n");
Prt('-RLS',"perl hash representation of output string
is:\n",HashDump($responseref),"\n\n\n");
}
dotest('get_site_list',{
'function' => 'get_site_list',
'version' => 1,
'params' => {'site_list' => 'TSFILES(DSOURCES(ARCHIVE))'}
});
dotest('get_db_info',{
'function' => 'get_db_info',
'version' => 2,
'params' => {
'table_name' => 'bench',
'return_type' => 'array',
'decodes' => 1,
'field_list' => ['bdate', 'bench', 'elev', 'rlgd', 'method'],
'filter_values' => {
'station' => 'HYDSYS01'
}
}
});
dotest('get_datasources_by_site',{
'function' => 'get_datasources_by_site',
'version' => 1,
'params' => {
'site_list' => "HYDSYS01,HYDSYS02,HYDSYS03"
}
});
dotest('get_sites_by_datasource',{
'function' => 'get_sites_by_datasource',
'version' => 1,
'params' => {
'datasources' => ["A","B"]
}
});
dotest('get_ts_traces',{
'function' => 'get_ts_traces',
'version' => 1,
'params' => {
'site_list' => 'HYDSYS01,HYDSYS02',
'datasource' => 'A',
'varfrom' => '100.00',
'varto' => '100.00',
'start_time' => '19750801000000',
'end_time' => '19750805000000',
'data_type' => 'mean',
'interval' => 'day',
'multiplier' => '1'
}
},1500);
dotest('get_variable_list',{
'function' => 'get_variable_list',
'version' => 1,
'params' => {
'site_list' => "HYDSYS01,HYDSYS02",
'datasource' => "A"
}
},5000);
dotest('test_error_return',{
'function' => 'get_ts_traces',
'version' => 1,
'params' => {
'site_list' => 'HYDSYS01,HYDSYS02',
'datasource' => 'X',
'varfrom' => '100.00',
'varto' => '100.00',
'start_time' => '19750801000000',
'end_time' => '19750901000000',
'data_type' => 'mean',
'interval' => 'day',
'multiplier' => '1'
}
},5000);
dotest('get_latest_ts_values',{
'function' => 'get_latest_ts_values',
'version' => 1,
'params' => {
'site_list' => 'hydsys01,hydsys02',
'datasource' =>'A',
'trace_list' => [
{'varfrom'=>'100.00','varto'=>'100','lookback'=>'60'},
{'varfrom'=>'10.00','varto'=>'10','now'=>'19910524050000'},
{'varfrom'=>'100.00','varto'=>'100','anyqual'=>1},
{'varfrom'=>'10.00','varto'=>'10','accum_period'=>'60'},
]
}
},5000
);
$dll->Close;
}
Using JSonCall from Python
As for Perl, we also provide a wrapper code for Python programmers in the hydllp.py module, call the HyDllP class. This class has a .jsoncall() method which allows you to pass in and receive back native Python structures (dicts and lists). The transcoding between Python dicts and JSON is handled inside the module and you donlt need to worry about it.
HyDllP.jsoncall() checks the return from a DLL call and if the buffer was too small on the initial call it automatically enlarges the buffer to a suitable size and runs the request again. While it is advisable to try and get the buffer size right first time, this at least means your program works even if you guess wrong. Note that there is also a significant overhead in specifying a ridiculously large buffer like 1,000,000 so its a balancing act. The default buffer size is 2000 bytes. Note also that the DLL stores your response when the buffer size is too small, this response will get returned when HyDllP.jsoncall() tries again with a bigger buffer.
The following program should give you some ideas on how to use this class in Python:
import logging
import json
import hydlog
import hydlib
import hydllp
# get Hydstra standard logger
logger = logging.getLogger(hydlog.HYDSTRA_LOGGER)
_hydebug = hydlib.hydebug()
with hydlib.file_open("REPORT", hydlib.hyconfig("TEMPPATH")
+ "junk", "w") as hrep, hydllp.HyDllP() as dll:
def dotest(testname, request, bufflen=2000):
logger.info(f"Testing HYDLLP JSonCall with {testname}
--------------------------------------------------------------",
tag="FILE.REPORT")
logger.info("JSON request: " + json.dumps(request, indent=4),
tag="FILE.REPORT")
if dll.jsoncall(request, bufflen):
logger.info("HYDLLP return: " + json.dumps(dll.result, indent=4),
tag="FILE.REPORT")
else:
logger.info('Error '+str(dll.result['error_num'])+': '+dll.result['error_msg'],
tag="FILE.REPORT")
logger.info('', tag="FILE.REPORT")
dotest('get_site_list', {
'function' : 'get_site_list',
'version' : 1,
'params' : {'site_list': 'TSFILES(DSOURCES(tscARCHIVE))'}
})
dotest('get_db_info', {
'function' : 'get_db_info',
'version' : 2,
'params' : {
'table_name' : 'bench',
'return_type' : 'array',
'decodes' : 1,
'field_list' : ['bdate', 'bench', 'elev', 'rlgd', 'method'],
'filter_values': {
'station' : 'HYDSYS01'
}
}
})
dotest('get_datasources_by_site', {
'function' : 'get_datasources_by_site',
'version' : 1,
'params' : {
'site_list' : "HYDSYS01,HYDSYS02,HYDSYS03"
}
})
dotest('get_sites_by_datasource',{
'function' : 'get_sites_by_datasource',
'version' : 1,
'params' : {
'datasources': ["A","B"]
}
})
dotest('get_ts_traces', {
'function' : 'get_ts_traces',
'version' : 1,
'params' : {
'site_list' : 'HYDSYS01,HYDSYS02',
'datasource' : 'A',
'varfrom' : '100.00',
'varto' : '100.00',
'start_time' : '19750801000000',
'end_time' : '19750805000000',
'data_type' : 'mean',
'interval' : 'day',
'multiplier' : '1'
}
},1500)
dotest('get_variable_list', {
'function' : 'get_variable_list',
'version' : 1,
'params' : {
'site_list' : "HYDSYS01,HYDSYS02",
'datasource' : "A"
}
},5000)
dotest('test_error_return',{
'function' : 'get_ts_traces',
'version' : 1,
'params' : {
'site_list' : 'HYDSYS01,HYDSYS02',
'datasource' : 'X',
'varfrom' : '100.00',
'varto' : '100.00',
'start_time' : '19750801000000',
'end_time' : '19750901000000',
'data_type' : 'mean',
'interval' : 'day',
'multiplier' : '1'
}
},5000)
dotest('get_latest_ts_values',{
'function' : 'get_latest_ts_values',
'version' : 1,
'params' : {
'site_list' : 'hydsys01,hydsys02',
'datasource' :'A',
'trace_list' : [
{'varfrom':'100.00','varto':'100','lookback':'60'},
{'varfrom':'10.00','varto':'10','now':'19910524050000'},
{'varfrom':'100.00','varto':'100','anyqual':1},
{'varfrom':'10.00','varto':'10','accum_period':'60'},
]
}
},5000)
HYDLL Caching and Open Files
In order to improve efficiency HYDLLP keeps a cache of open time-series files and open database tables, so that it doesn't have to keep re-opening time-series files and re-establishing table connections. Mostly this is a good thing, but in a busy server environment, or in the case where a long running process uses DLL, the result can be that time-series files and tables can be held open for long periods, which sometimes interferes with other processes such as incoming telemetry through SVRIMP.
If you find yourself in a program loop operating site by site, where you open some TS files for the site, process some data, and then move on to the next site, we suggest you call ClearTSCache at the end of the loop to release the TS file. Likewise if your program reads some database records at the start, and never again, call ClearDBCache once you are done with database methods.
Encoding of real values in JSON
When JSonCall() was introduced in 2010 (v10.03), we decided to encode all real numbers (numbers with decimals) as strings. We did this to avoid scientific notation (eg 1E-5), which we thought Perl couldnt handle (though it actually can). But since the primary use case was Perl, and Perl is not a strongly-typed language, it didnt matter. Perl was quite capable of taking the string values returned in JSON, and interpreting them as real values.
Now that we are also support Python, which is a strongly-typed language, we need the ability to return real numbers encoded in JSON as proper float format values.
To avoid causing any unintended side-effects on the Perl world, if you take no action, the feature will not be activated - HYDLLP will behave as it always has - encoding real values as strings.
To allow maximum flexibility across use cases, you can enable the feature in two ways:
Across entire session
The JSonCall() function set_real_encoding. If you call this function (with the real_encoding parameter set to FLOAT), HYDLLP will switch to encoding real values as JSON-format floats. You can switch it back again by calling the function with a value of STRING.
The Hydstra hydllp.py Python module calls this function automatically, so there are very few cases where you would need to call this function yourself.
For single call only
To allow use cases like web services, the feature is also available on a call-by-call basis for all JSonCall functions. You simply include the optional real_encoding parameter in your JSON data, that the feature will be enabled for that call only.
HYDLLP Exported Functions
Below is a list of functions exported by HYDLLP.DLL, expressed
in
StartupEx
Starts up a session, where you specify the hyconfig .ini file.
function
StartUpEx (
aUserID : pChar;
aPassword : pChar;
aHyAccess : pChar;
aHyConfig : pChar;
var aHandle : integer)
: integer; stdcall;
Return Code |
Explanation |
0 |
OK |
10 * |
StartUp failed. Possible reasons include: SDE7.DLL or SDECDX7.DLL not found, HYCONFIG.INI or HYACCESS.INI not found or incorrect. |
12 * |
Login failed. Make sure the user ID and password are correct. |
Shutdown
Closes down a session.
function Shutdown(aHandle : integer) : integer; stdcall;
Return Code |
Explanation |
0 |
OK |
11 * |
ShutDown failed. |
JSonCall
JSonCall is a single exported call that can access several supported functions. The idea is that we can add new functions without modifying the DLL interface.
function
JSonCall (
aHandle : integer;
aRequestStr : pAnsiChar;
{>} aReturnStrBuf : pAnsiChar;
aReturnStrLen : integer)
: integer; stdcall;
Return Code |
Explanation |
0 |
OK |
200 |
Buffer insufficient |
Anything else |
(Depends on which function is called) |
The aRequestStr parameter is a string in JSON format that includes the function you wish to call, and any parameters appropriate to it. See below for a list of all current JSON calls, and the parameters they require.
Here is a sample JSON request string, formatted for clarity:
{
"function" : "get_ts_traces",
"version" : 1,
"params" : {
"site_list" : "HYDSYS01,HYDSYS02",
"varfrom" : "100.00",
"start_time" : "19750801000000",
"datasource" : "A",
"varto" : "100.00",
"interval" : "day",
"end_time" : "19750802000000",
"data_type" : "mean",
"multiplier" : "1"
}
}
The name of the desired function must be specified in an outer-level item called function. You must also specify the version of the call (all calls are currently at version 1) to allow for future enhancements.
The params item is a wrapper in which you specify named items, depending on which function you are calling.
Here is an example of the output from the above call, which is also encoded using JSON, formatted for clarity:
{ "error_num":0,
"buff_supplied":8192,
"buff_required":1363,
"return":{
"traces":[
{ "site":"HYDSYS01",
"site_details":{
"short_name":"Hydstra Test Station",
"name":"Hydstra Test Station - Composite data"},
"varfrom_details":{
"short_name":"Level (Metres)",
"subdesc":"",
"variable":" 100.00",
"units":"Metres",
"name":"Stream Water Level"},
"varto_details":{
"short_name":"Level (Metres)",
"subdesc":"",
"variable":" 100.00",
"units":"Metres",
"name":"Stream Water Level"},
"quality_codes":{
"1":"Good continuous records"},
"trace":[
{"v":"0.363","t":19750801000000,"q":1},
{"v":"0.368","t":19750802000000,"q":1},
{"v":"0.363","t":19750803000000,"q":1},
{"v":"0.464","t":19750804000000,"q":1},
{"v":"0.505","t":19750805000000,"q":1}]
},
{ "site":"HYDSYS02",
"site_details":{
"short_name":"Hydstra Test Station",
"name":"Hydstra Test Station - Secondary rainfall data"},
"varfrom_details":{
"short_name":"Level (Metres)",
"subdesc":"",
"variable":" 100.00",
"units":"Metres",
"name":"Stream Water Level"},
"varto_details":{
"short_name":"Level (Metres)",
"subdesc":"",
"variable":" 100.00",
"units":"Metres",
"name":"Stream Water Level"},
"quality_codes":{
"1":"Good continuous records"},
"trace":[
{"v":"0.363","t":19750801000000,"q":1},
{"v":"0.368","t":19750802000000,"q":1},
{"v":"0.363","t":19750803000000,"q":1},
{"v":"0.464","t":19750804000000,"q":1},
{"v":"0.505","t":19750805000000,"q":1}]
}
]
}
}
NB:
Tokens that have a multiple line value will have the lines separated by '/013/010'
List of Available JSonCall Functions
All JSonCall examples are formatted using Perl syntax. If you want JSON formatting then you can use HYDLLP_UI with the Input Type set to PERL and making sure to set Print JSON input.
If you are developing web service call REST URLs, you may wish to set HYDLLP_UI Print JSON output.
In general all Perl requests can be easily translated to JSON by replacing all single quotes with double quotes and the reference operator => with :.
Retrieves one or more time series traces.
When HYDLLP is running under the Hydstra/WEB framework, certain privacy-sensitive information can be excluded from the returned data by settings in DATAPRIV.INI, which is administered by HYDATAPRIV. This lets you deny access to personal information in TS comments.
Changes for version 2
In version 2, with the addition of var_list we decided that returning an error for each variable at each site that didn't contain any data no longer made sense. Now, if there is no data for a given variable at a given site, nothing is returned for that variable and site.
The report_time parameter has been added.
parameter |
description |
options |
example |
site_list |
Hydstra site list expression |
|
group(REGION,NORTH) |
start_time |
data period start datetime YYYYMMDDhhmmss |
YYYYMMDDHHIIEE |
19750501000000 |
end_time |
data period end datetime YYYYMMDDhhmmss. |
YYYYMMDDHHIIEE |
19750510000000 |
varfrom |
source variable. Optional in version 2. Either var_list or varfrom must be specified. |
|
100.00 |
varto |
destination variable. Only used when varfrom is specified. |
|
140.00 |
var_list |
A list of source variables. Only available in version 2. Optional but either varfrom or var_list must be specified. |
|
100,140.01,232 |
interval |
data interpolation interval |
year, month, day, hour, minute, second, |
year |
multiplier |
interval multiplier |
integer |
5 |
recent_points |
only return the most recent n points that were retrieved, discarding any trailing bad quality points (eg for data current type plots / reports) |
integer |
20 |
report_time |
(optional) (Version 2 only) Specifying the report_time as end will cause the time output with aggregated values for mean, total, and partial total data types to be the end of the period instead of the start. |
start, end |
end |
offset |
(optional) If you specify start_time = end_time = 0 then the interval will round to the start of the current interval. (day for example) This offset is specified in minutes and lets you translate the period. |
Integer |
60 |
datasource |
Hydstra datasource code |
|
A |
data_type |
data extraction type |
mean, maxmin, max, min, start, end, first, last, tot, |
mean |
match_comment |
(optional) Only return points that match the regular expression provided. |
A regular expression |
Proc.* |
rel_times |
(optional) if true, return datetimes in minutes since 01/01/1601 |
0 (false) 1 (true) |
1 |
bad_value |
(optional) lets you override the value element for data items where the quality is bad (greater than your hyconfig MAXGOODQ). You may provide a flag value (eg Missing) or a censoring numeric value (eg 0.0). If you provide a numeric, it will be formatted the same as other extracted values. |
Any expression, string or numeric. |
0.0 |
compressed |
(optional) determines the output formatting of the trace data. Compressed formatted data is similar to Hydstra Standard Time Series Text File Format with the format of each line being TIME,VAL,QUAL,DT,COMNT |
0 (false) 1 (true) |
0 |
rounding |
(optional) a rounding specification used by various JSonCall functions to format value results with a defined variable. |
|
JSonCall Number Formatting |
NB:
If data_type = POINT, the interval and multiplier are ignored.
If data_type = TOT, the datetime of the returned value is the
start of the period.
(e.g. a daily total discharge with datetime of 20111020000000 means the total
discharge for the period from 00:00_20/10/2011 to 00:00_21/10/2011)
A note on timing when retrieving data - if you retrieve point data then the retrieval is driven by the data points in the time series file, and points between the start and end time (inclusive) will be retrieved, and interval and multiplier are ignored. If however you select any aggregating type like mean, tot etc. then the retrieval is driven by interval and multiplier. Values will be retrieved and reported against the start of the interval (unless you specify reporttime=end)until the start time of a retrieval period exceeds the end time of the request. What this means is that if you request daily totals from 01 Jan to 02 Jan, you will get two values back, one for the period starting 01 Jan and another for the period starting 02 Jan.
If data_type = CUM, the data should be of total type otherwise the results will be invalid. Total type mean to be datatrans 5 or 6, i.e. rainfall data.
If interval = PERIOD, a single value spanning the specified period is returned, (and data_type cannot be POINT).
If interval = DEFAULT (and data_type is not POINT), an interval will be chosen automatically, based on the period extracted. The algorithm is the same as used by HYPLOT when you specify interval=DEFAULT. This makes most sense if the data_type is CUM (for total type data) or MAXMIN (for everything else).
If you wish to get a single value you can use the data_type of
START with the
start_time = end_time = the time of the value you wish to get.
If you are producing a data current type plot, and are only interested in a limited number of points, you can specify recent_points to limit the number of points returned. The end_time parameter would typically be now, and your choice of start_time now controls how far back to look, rather than the start time of the returned series of points. If you do this, any trailing bad-quality points are discarded - the final point returned will be the final good-quality point.
If you wish to get the period of record then you can set the start_time and end_time to 0. This will cause the period of record to be used for the requested variable.
Sample request
{
'function' => 'get_ts_traces',
'version' => 2,
'params' => {
'site_list' => 'HYDSYS01,HYDSYS02',
'start_time' => '19750801000000',
'varfrom' => '100.00',
'interval' => 'day',
'varto' => '100.00',
'datasource' => 'A',
'end_time' => '19750802000000',
'data_type' => 'mean',
'rounding' => [
{
'zero_no_dec' => '1',
'dec_first' => '1',
'sigfigs' => '4',
'variable' => '100',
'decimals' => '2'
}
],
'multiplier' => '1'
}
}
Sample return data
{ "error_num":0,
"buff_supplied":8192,
"buff_required":1363,
"return":{
"traces":[
{ "site":"HYDSYS01",
"site_details":{
"short_name":"Hydstra Test Station",
"name":"Hydstra Test Station - Composite data"},
"timezone":"10.0",
"varfrom_details":{
"short_name":"Level (Metres)",
"subdesc":"",
"variable":" 100.00",
"units":"Metres",
"name":"Stream Water Level"},
"varto_details":{
"short_name":"Level (Metres)",
"subdesc":"",
"variable":" 100.00",
"units":"Metres",
"name":"Stream Water Level"},
"quality_codes":{
"1":"Good continuous records"},
"trace":[
{"v":"0.3600","t":19750801000000,"q":1},
{"v":"0.3700","t":19750802000000,"q":1},
{"v":"0.3600","t":19750803000000,"q":1},
{"v":"0.4600","t":19750804000000,"q":1},
{"v":"0.5000","t":19750805000000,"q":1}],
"compressed":"0",
"error_num" : 0
},
{ "site":"HYDSYS02",
"site_details":{
"short_name":"Hydstra Test Station",
"name":"Hydstra Test Station - Secondary rainfall data"},
"timezone":"10.0",
"varfrom_details":{
"short_name":"Level (Metres)",
"subdesc":"",
"variable":" 100.00",
"units":"Metres",
"name":"Stream Water Level"},
"varto_details":{
"short_name":"Level (Metres)",
"subdesc":"",
"variable":" 100.00",
"units":"Metres",
"name":"Stream Water Level"},
"quality_codes":{
"1":"Good continuous records"},
"trace":[
{"v":"0.3600","t":19750801000000,"q":1},
{"v":"0.3700","t":19750802000000,"q":1},
{"v":"0.3600","t":19750803000000,"q":1},
{"v":"0.4600","t":19750804000000,"q":1},
{"v":"0.5000","t":19750805000000,"q":1}],
"compressed":"0",
"error_num" : 0
}
]
}
}
Writes one or more time series traces. (Do NOT use with REST web service requests.)
parameter |
description |
|||
traces |
An array of trace specifications |
|||
|
parameter |
description |
options |
example |
site |
The name of the site you wish to store the time-series data under. |
|
HYDSYS01 |
|
(optional) open_mode |
The open mode specifies how data should be added to a time-series file if it already exists. The default value is erase. |
erase, search, append, increment, overlay, and abort. See HYCREATE for a full description of open_modes. |
erase |
|
datasource |
Hydstra datasource code |
|
A |
|
variable |
Output variable |
|
100 |
|
(optional) datatrans |
This is an override datatrans. If you don't specify a value for this then you must specify the 'd' value for every point. |
|
5 |
|
(optional) quality |
This is an override quality. If you don't specify a value for this then you must specify the 'q' value for every point. |
|
150 |
|
(optional) max_gap |
Sets the maximum gap allowed between points in minutes. |
|
60 |
|
(optional) max_join |
Sets the maximum gap allowed between the end of the existing file and the first new point, when open_mode = increment. |
|
60 |
|
(optional) max_truncate |
Sets the maximum amount of data that can be truncated by an open_mode of overlay. Defaults to max_join if no value is provided. |
|
60 |
|
(optional) fixed_interval |
Specifies that data points correspond to fixed time intervals. This causes HYDLLP to write appropriate anchor points (depending on the data type), and also preserve the quality of points (and their corresponding intervals) surrounding gaps. |
year, month, day, hour, minute, second. |
|
|
(optional) fixed_intmult |
Specifies the multiplier for fixed_interval, required if you specify it. |
|
|
|
points |
An array of points |
|||
|
parameter |
description |
example |
|
v |
The value of the point |
10.5 |
||
t |
The time of the point |
YYYYMMDDHHIIEE 20130318140135 |
||
(optional) q |
The quality of the point |
5 |
||
(optional) d |
The datatrans of the point |
6 |
||
(optional) c |
Any comments associated with the point. Comments can be line separated by inserting /013/010 where you desire a line break. |
line 1/013/010line 2 |
For further details on the open_mode, max_gap, max_join, and max_truncate parameters you should look at HYCREATE.
NB:
If you want to add a \ to a comment then you will need to double it, \\. This is done to help with round trips for comments from get_ts_traces. It should be noted though, that comments containing /013 or /010 cannot be round tripped.
Sample request
{
'function' => 'write_ts_traces',
'version' => 1,
'params' => {
'traces' => [{
'site' => 'HYDSYS01',
'open_mode' => 'erase',
'datasource' => 'D',
'variable' => '10',
'datatrans' => '5',
'quality' => '2',
'max_join' => '0.0',
'max_truncate' => '0.0',
'points' => [
{
'v' => '0.5',
'q' => '1',
't' => '20130318140100',
},{
'v' => '0.15',
't' => '20130318140130',
'c' => 'A comment'
},{
'v' => '10.5',
'q' => '1',
'd' => '6',
't' => '20130318140135',
}
]
},{
'site' => 'HYDSYS01',
'open_mode' => 'append',
'datasource' => 'D',
'variable' => '100',
'datatrans' => '1',
'quality' => '2',
'points' => [
{
'v' => '0.5',
'q' => '1',
't' => '20130318140100',
},{
'v' => '0.15',
't' => '20130318140130',
'c' => 'A comment/013/010Second line'
}
]
}]
}
}
Sample return data
{
"buff_required" : 59,
"buff_supplied" : 1000000,
"error_num" : 0
}
Executes a HYFILER command. (Do NOT use with REST web service requests.)
parameter |
description |
options |
example |
command |
A hyfiler command. If a command has a listdev parameter then you must place %LIST% in its place if you wish to receive the results. |
|
MIRROR HYDSYS01 A Q %LIST% /QUIET /RETRY=2 |
wait (optional) |
If the hyfiler command can't access a time-series file then this option specifies in minutes how long this call should keep trying to gain access. Specifying 0 means the call will not try again. This option isn't supported in Hydstra versions earlier than 11. In Hydstra versions earlier than 11 the default behaviour is to not try again. |
integer value representing minutes |
5 |
Sample request
{
'function' => 'hyfiler_command',
'version' => 1,
'params' => {
'command' => 'MIRROR HYDSYS01 A Q %LIST%',
'wait' => '0'
}
}
Sample return data
{
"buff_required" : 371,
"buff_supplied" : 1000000,
"error_num" : 0,
"return" : {
"output" : "HYDLLP V209 Output 30/10/2013\r\n\r\n Command:
MIRROR\r\n Site(s): HYDSYS01\r\n Source Datasource: A\r\n Target Datasource:
Q\r\n Options: QUIET, OVWRITE, RETRY=5, WAIT=2.0\r\n\r\nCopy HYDSYS01
succeeded\r\n\r\nSummary:\r\n 1 files copied\r\n"
}
}
Retrieves a list of sites from a HYSTNS sitelist expression
parameter |
description |
options |
example |
site_list |
Hydstra site list expression |
|
201001,201002 |
Sample request
{
'function' => 'get_site_list',
'version' => 1,
'params' => {
'site_list' => 'TSFILES(DSOURCES(ARCHIVE))'
}
}
Sample return data
{ "error_num":0,
"buff_supplied":8192,
"buff_required":483,
"return":{
"sites":[
"HYDSYS01",
"HYDSYS02",
"HYDSYS03",
"HYDSYS04",
"HYDSYS05",
"HYDSYS06",
"HYDSYS07"]
}
}
Retrieves data from a database table.
If a user has an insufficient read level based on PASSWD.LEVELS and USERMAS.MINLEVREAD then an error will be returned. You can use this to stop certain tables from being accessed by web users.
When HYDLLP is running under the Hydstra/WEB framework, certain privacy-sensitive information can be excluded from the returned data by settings in DATAPRIV.INI, which is administered by HYDATAPRIV. This lets you deny access to specified timeseries data comments and user info.
Changes for version 2
The version breaking change came about because we were handling dates in an inconsistent way. We decided that the best approach was to standardise on a single date format YYYYMMDD. This could cause issues with any dates being used in complex_filter or simple_filter. Dates being returned may have also changed format.
Changes for version 3
The version breaking change occurs when asking for a hash return_type. If one of the hash keys is a date field then in version 2 it was formatted as YYYYMMDDHHIIEE which was inconsistent with the direction we chose. Date key returns are now formatted as YYYYMMDD instead.
parameter |
description |
options |
example |
|
table_name |
Hydstra database table name |
|
site |
|
return_type |
type of data structure returned. HASH returns a deep hash with the record preceded in the hash tree by all the key fields, whereas ARRAY returns an array of records. |
hash, array |
hash |
|
filter_values |
(optional) query filter using a hash of fieldname=value pairs WARNING: you can not use filter_values and complex_filter at the same time. Filters on date fields are specified as YYYYMMDDhhmmss. Filters on logical/boolean fields are specified as true or false |
|
'station' =>: '201001' date => 19990101000000 active => true |
|
field_list |
(optional) an array of field names, to return a subset of columns |
|
'STATION','STNAME' |
|
sitelist_filter |
(optional) filter based on the station field using a HYSTNS filter expression. NOTE: If you do not specify a complex_filter or filter_values then the internal operation of the sitelist_filter will change. This may have implications on the performance of this call if you specify a large site list against a small table. |
|
'match(hy*)' |
|
geo_filter |
(optional) filter based on latitude and longitude
Circle takes an array parameter:
Rectangle takes an array of arrays:
Region takes an array of arrays: (more information on geo_filter below) |
Circle |
'circle' => ['-35','149',1] |
|
Rectangle |
'rectangle' => |
|||
region |
'region' => |
|||
complex_filter |
(optional) filter based on the values of fields WARNING: you can not use filter_values and complex_filter at the same time. Filters on date fields are specified as YYYYMMDD. |
combine (optional) |
'combine'=>'OR' |
|
not (optional) |
'not'=>'NOT' |
|||
left (optional) |
'left'=>'(' |
|||
fieldname |
'fieldname'=>'longitude' |
|||
operator |
'operator'=>'GT' |
|||
value |
'value'=>'100' |
|||
right (optional) |
'right'=>') ' |
|||
raw_db_filter |
(optional) This filter allows you to directly filter the database in the same way hymanage or hydbutil do. HYMANAGE - Xbase filter expressions |
|
|
|
order |
(optional) a named order (from the Hydstra DBI files) to control the order of the returned rows; for a hash, it influences the hierarchical structure |
|
REGION |
|
start_from |
(optional) This lets you trim the return by skipping the first (start_from - 1) rows. |
|
|
|
return_limit |
(optional) This lets you limit the number of rows returned to the number provided. If the limit is reached without running out of rows then a next_from parameter will be placed in the return structure. Using the next_from value as your start_from value allows you to iterate over smaller chunks of the original result. |
|
|
|
decodes |
Include field value decodes, ie site/variable names, coded value descriptions etc. These will be returned as elements named fieldname_decode |
|
'decodes'=>1 |
|
labels |
Include field labels, ie the field description from DATADICT. This is especially useful for fields with names like SPARE1 and CATEGORY1, where the field name gives no clue about the data it contains. |
|
'labels'=>1 |
|
Sample request
{
'function' => 'get_db_info',
'version' => 2,
'params' => {
'geo_filter' => {
'region' => [
[
'-35',
'149'
],[
'-35.1',
'150'
],[
'-33',
'142'
]
]
},
'return_type' => 'array',
'sitelist_filter' => 'match(hy*)',
'field_list' => [
'bdate',
'bench',
'elev',
'rlgd',
'method'
],
'raw_db_filter' => '(station > "A ") AND (station <
"C")',
'complex_filter' => [
{
'operator' => 'NE',
'value' => 'HYDSYS04',
'fieldname' => 'station'
}
],
'table_name' => 'bench',
'filter_values' => {
'station' => 'HYDSYS01'
}
}
}
Sample return data
{ "error_num":0,
"buff_required":249,
"buff_supplied":8192,
"return":{
"rows":[
{"method":"",
"rlgd":"3.438",
"elev":"0.000",
"bench":" 2",
"bdate":19960101000000},
{"method":"",
"rlgd":"1.419",
"elev":"0.000",
"bench":" 4",
"bdate":19960101000000}
]
}
}
Complex_filter continued
option |
default value |
combine (optional, AND or OR) |
AND |
not (optional) |
|
left (optional) |
|
right (optional) |
Bracketing of complex expressions is performed by including a left or right
or not operator in a subfilter. In order to build a complex filter
expression such as
elev>=682 or ((elev<=1000) and (longitude>149.9) and not ((longitude<175) and (latitude=-30.885)) and (longitude!=0))
the expression would be:
'complex_filter' => [{
'fieldname'=>'elev',
'operator'=>'GE', #elev is greater than or equal to 682
'value'=>'682',
},{
'combine'=>'OR',
'left'=>'(', #begin OR
'fieldname'=>'elev',
'operator'=>'LE', #elev is less than or equal to 1000
'value'=>'1000',
},{
'fieldname'=>'longitude',
'operator'=>'GT', #longitude is greater than 149.9
'value'=>'149.9',
},{
'not'=>'NOT',
'left'=>'(', #begin NOT
'fieldname'=>'longitude',
'operator'=>'LT', #longitude is less than 175
'value'=>'175',
},{
'fieldname'=>'latitude',
'operator'=>'EQ', #latitude is equal to -30.855
'value'=>'-30.85500000',
'right'=>')', #end NOT
},{
'fieldname'=>'longitude',
'operator'=>'NE', #longitude is not equal to 0
'value'=>'0.0000000',
'right'=>')', #end OR
}]
The following text operators are also supported, in addition to the usual comparison operators:
text operator |
meaning |
FoxPro |
SQL |
Example |
EQ |
equals |
Yes |
Yes |
'fieldname'=>'region, 'operator'=>'EQ', |
NE |
not equals |
Yes |
Yes |
'fieldname'=>'region, 'operator'=>'NE', |
GT |
greater than |
Yes |
Yes |
'fieldname'=>'region, 'operator'=>'GT', |
LT |
less than |
Yes |
Yes |
'fieldname'=>'region, 'operator'=>'LT', |
GE |
greater than or equal |
Yes |
Yes |
'fieldname'=>'region, 'operator'=>'GFE', |
LE |
less than or equal |
Yes |
Yes |
'fieldname'=>'region, 'operator'=>'LE', |
CONT |
contains |
Yes |
Yes |
'fieldname'=>'stname', 'operator'=>'CONT', |
IN (only available in Apollo) |
string is exactly in a comma delimited list |
Yes |
No |
'fieldname'=>'station', 'operator'=>'IN', 'value'=>'HYDSYS02 ,HYDSYS03 ' |
LIKE |
the sql condition with _ and % wildcards |
Yes* |
Yes |
'fieldname'=>'station', 'operator'=>'LIKE', |
NOTCONT |
does not contain |
Yes |
No |
'fieldname'=>'stname', 'operator'=>'NOTCONT', |
NOTCONT |
does not contain |
Yes |
No |
'fieldname'=>'stname', 'operator'=>'NOTCONT', |
NOTIN |
not in comma delimited list |
Yes |
No |
'fieldname'=>'owner', 'operator'=>'NOTIN', |
* A limited version of the LIKE operator is available under
FoxPro, but does not support the full SQL features.
All text comparisons are performed in alphabetical order (case is ignored),
hence
A < AA < AB < B < BA
4 < 5 < A
Geo_filter continued
circle => [lat, long, difference in degrees]
The circle filter will return points that fall inside the great circle and will inconsistently return points that fall on the boundaries due to errors in floating point arithmetic. The radius of the circle is degrees of the central angle.
rectangle => [[lat, long], [lat, long]] ([[top, left], [bottom, right]])
The rectangle filter will return points that fall inside the region, including the boundary points.
region => [[lat, long], [lat, long], ..., [lat, long]]
The region filter will return points that fall inside the region, excluding the boundary points.
The geo_filter feature has an optional performance boost, allowing the retrieval to be much faster, if and only if the following conditions are met:
You are retrieving from the SITE table
There is no filter_values filter
There is no complex_filter filter
There is no raw_db_filter filter
There is no order specified
If those conditions are not met, the retrieval will be slower (depending on your other filtering etc).
There is also a minor side-effect of this speedup: if you have specified that the data is to be returned in array form (as opposed to hash) the sites will be in LATITUDE order instead of by site ID.
Writes rows to database tables in a work area.
parameter |
description |
options |
example |
|
table_name |
Hydstra database table name, which must include a work area specifier, see example |
|
[priv.test]site |
|
rows |
An array of the rows to write. There are two possible formats: (b) if you have not specified a field_list parameter, each row must be a hash of field=value pairs. This option is slightly slower and less memory efficient. To help you keep track of problems, there is a special pseudo-field supported, called _CONTEXT_. If you specified field_list, you may specify a field called _CONTEXT_, and you must provide a value for it in each row. If you are using the hash method, you may provide a _CONTEXT_ value on any row you choose. Whenever a record cannot be written (or fails validation), HYDLLP will provide the context, as well as the key (if possible) so that you can connect the failure to its original source. |
hash, array |
||
field_list |
(optional) As discussed above, this parameter lets you choose to specify rows as arrays or hashes. |
|
||
erase |
(optional, Default is True.) if True (or 1, or Y
etc), the table will be erased and recreated before any rows are added. If
False (or 0 or N), any existing data is preserved, and the new data appended. |
|
|
|
validate |
(optional) controls validation. All data is checked for critical errors (in valid numeric column values, invalid dates, character strings too long). This parameter controls whether or not additional checking - the type that is typically specified by DATADICT - is performed. Default is True Only data that passes these checks is written to the database. |
|
||
bulkdump |
(Optional, default = No) If you specify this as Yes, the
data is written to a bulk dump file, and the return value includes an
additional value: bulkload_script, consisting of an array of commands which
will load the data to the database table. |
|
|
|
Sample request
{
"params" : {
"erase" : "Y",
"table_name" : "[priv.test]site",
"rows" : [
{
"shortname" : "Test site",
"station" : "HYDSYS01",
"stname" : "Test site"
}
]
},
"function" : "write_db_info",
"version" : 1
}
Sample return data
{
"buff_required" : 702,
"error_msg" : "Some validation errors were encountered",
"buff_supplied" : 1000000,
"error_num" : 141,
"return" : {
"rows_written" : "0",
"errors" : [
"Table SITE, key [HYDSYS01]: SITE.LATITUDE : Invalid latitude (): latitude must be within -90 and 90",
"Table SITE, key [HYDSYS01]: SITE.LONGITUDE : Invalid longitude (): longitude must be within -180 and 180",
"Table SITE, key [HYDSYS01]: SITE.TIMEZONE : Value () must be within the range -12.000000 to 13.000000",
"Table SITE, key [HYDSYS01]: SITE.OWNER : Please specify a currently enabled, active, TS>0 user from the PASSWD table ()",
"Table SITE, key [HYDSYS01]: SITE.REGION : Code [] not found in code group [REGION - Region]"
],
"rows_rejected" : "1"
}
}
Takes a list of area classes and returns a list of work area specifiers.
parameter |
description |
options |
example |
area_classes |
A list of area classes used to specify a list of work area specifiers. |
['priv','pub','temp','junk','archive'] |
['priv','temp','junk'] |
user_specific |
(optional) Set to true if you wish to find work areas owned by other users. |
0 (false) 1 (true) |
0 |
return_tables |
(optional) Set to true if you wish to find the tables in each work area. |
0 (false) 1 (true) |
1 |
check_upgrade |
(optional) Set to true if you wish to determine which work area tables need to be upgraded. |
0 (false) 1 (true) |
1 |
Sample request
{
'function' => 'get_db_areas',
'version' => 1,
'params' => {
# 'area_classes' => ['priv','pub','temp','junk','archive'],
'area_classes' => ['pub','archive'],
'user_specific' => '0', #(optional) (defaults to false)
'return_tables' => '1', #(optional) (defaults to false)
'check_upgrade' => '1' #(optional) (defaults to false)
}
}
Sample return data
{
"buff_required" : 16439,
"buff_supplied" : 17259,
"error_num" : 0,
"return" : {
"work_area_specifics" : {
"temp" : [{
"table" : "[TEMPFILES]HYCONFIG",
"current" : "False",
"reason" : "error encountered while checking: Table
C:\\TEMP\\HYCONFIG could not be opened."
},{
"table" : "[TEMPFILES]HYCONFIGFC",
"current" : "False",
"reason" : "error encountered while checking: Table
C:\\TEMP\\HYCONFIGFC could not be opened."
}],
"archive" : [{
"table" : "[ARCHIVE]ACCINST",
"current" : "TRUE"
},{
... many lines
},{
"table" : "[ARCHIVE]WREHOUSE",
"current" : "TRUE"
}],
"junk" : [{
"table" : "[JUNKFILES]CQLLRAOH",
"current" : "FALSE",
"reason" : "error encountered while checking:
F:\\hyd\\sys\\misc\\dbi\\CQLLRAOH.DBI does not exist."
}],
"priv" : [{
"table" : "[CMR.HYRATED]RATEEQN",
"current" : "TRUE"
},{
... many lines
},{
"table" : "[CMR.MASTDICTUM]MASTDICT",
"current" : "TRUE"
}],
"pub" : [{
"table" : "[PUBLIC.ACC]ACC",
"current" : "FALSE",
"reason" : "error encountered while checking:
F:\\hyd\\sys\\misc\\dbi\\ACC.DBI does not exist."
},{
... many lines
},{
"table" : "[PUBLIC.WQWRK]SAMPLES",
"current" : "FALSE",
"reason" : "SAMPLES: Field Count = 29; DBI Field Count =
39"
}]
}
}
}
Retrieves a list of the latest time-series points for a site list. By default it looks back to the latest good quality data point. Mainly used for web sites and other displays of current value from telemetered data.
parameter |
description |
options |
example |
site_list |
Hydstra site list expression |
|
201001 |
datasource |
A datasource code |
|
A |
site_details |
(optional) a boolean value used to request site details be returned with each varfrom and varto pair. |
0 (false) 1 (true) Defaults to 0 |
1 |
rounding |
(optional) a rounding specification used by various JSonCall functions to format value results with a defined variable. |
|
JSonCall Number Formatting |
trace_list |
A list of parameters defining the latest value required. accum_period is used for total-type data like rainfall, and is latched to the start of the day, so if you ask for the latest 15 minute value it will start on the hour, or at 15,30 or 45 minutes past the hour - you won't ever get a 15 minute total starting at 12:17. daystart specifies the start time in the day, so if you ask for daily values they will start at this time (midnight by default). |
varfrom |
100.00 |
varto |
100 |
||
accum_period (in minutes) (optional defaults to 0) |
15 |
||
accum_partial. If set to 0 then the last complete accumulated period is used. If set to 1 then the last 2 accumulated periods with any data are returned (optional defaults to 0) |
1 |
||
output_time (start or end). Only makes sense when
accum_period is non zero. Determines which end of the accum_period the
output_time is associated with. |
start |
||
daystart (hhmm) (optional defaults to 0:00, midnight) |
0900 |
||
lookback (minutes). If not specified the call will look back as far as it needs to. |
120 |
||
anyqual. If set to 0 the last good quality point in the lookback period will be returned, if set to 1 the last point will be returned even if it is bad quality. If accum_period is greater than 0 then anyqual defines whether or not a bad quality value will be returned but doesn't keep looking for a good quality value. (optional defaults to 0) |
1 |
||
now (used mainly for testing), Normally the call looks back from the current time , e.g. Now(), but the start time of the lookback can be overridden with this parameter. This parameter must be used in conjunction with the lookback parameter; otherwise the end time of the trace will be used. (optional defaults to right now) |
19910524062000 |
The call returns the latest value, the time of the latest value (start time of a periodic total) and the trend, which is the difference between the last value and the one before it. Trend can be + for rising, - for falling, 0 for static, and ? if unknown because of bad/missing data. Static trend is defined as the two values being equal when rounded to the precision stored in VARIABLE.
Sample request
{ 'function' => 'get_latest_ts_values',
'version' => 2,
'params' => {
'site_list' => 'hydsys01',
'datasource' =>'A',
'trace_list' => [
{'varfrom'=>'100.00','varto'=>'100','lookback'=>'60'},
{'varfrom'=>'100.00','varto'=>'100','lookback'=>'60',
'anyqual'=>'1'},
]
}
}
Sample return data
{ "buff_required" : 263,
"buff_supplied" : 1000,
"error_num" : 0,
"return" : {
"HYDSYS01" : [
{"varfrom" : "100.00",
"values" : [
{"time_start" : "",
"p" : "",
"time_end" : "",
"q" : 151,
"v" : "0.0",
"trend" : "?",
"time" : "20110513150431"}
],
"varto" : "100.00"},
{"varfrom" : "100.00",
"values" : [
{"time_start" : "",
"p" : "",
"time_end" : "",
"q" : 151,
"v" : "0.0",
"trend" : "?",
"time" : "20110513150431"}
],
"varto" : "100.00"}
]
}
}
Sample request
{ 'function' =>
'get_latest_ts_values',
'version' => 2,
'params' => {
'site_list' => 'hydsys01',
'datasource' => 'A',
'trace_list' => [
{'varfrom' => '10.00',
'varto' => '10',
'accum_period' => '1440',
'accum_partial' => '1',
'daystart' => '0900',
'lookback' => '10080'},
{'varfrom' => '10.00',
'varto' => '10',
'accum_period' => '1440',
'daystart' => '0900'},
{'varfrom' => '10.00',
'varto' => '10',
'accum_period' => '1440',
'accum_partial' => '1',
'daystart' => '0900',
'anyqual' => '1',
'lookback' => '10080'}
] ,
'rounding' => [
{
'variable' => '10',
'zero_no_dec'=> '1',
'dec_first' => '0',
'ranges' => [
{'val' => '0',
'decimals'=> '3'},
{'val' => '0.7',
'sigfigs' => '2',
'decimals'=> '2'},
{'val' => '1.4',
'decimals'=> '4'}
]
}
]
}
}
Sample return data
{ "buff_required" : 3016,
"buff_supplied" : 3166,
"error_num" : 0,
"return" : {
"HYDSYS01" : [
{"varfrom" : "10.00",
"values" : [
{"time_start" : "20120315090000",
"p" : "3.472",
"time_end" : "20120315095000",
"time" : "20120315095000",
"q" : 2,
"v" : "0.100",
"trend" : "?"}
],
"varto" : "10.00",
"accum_period" : 1440},
{"varfrom" : "10.00",
"values" : [
"time_start" : "20110306090000",
"time" : "20120301121949",
"v" : "1.5000",
"p" : "100.0",
"time_end" : "20120304090000",
"q" : 2,
"trend" : "+"
],
"varto" : "10.00",
"accum_period" : 1440},
{"varfrom" : "10.00",
"values" : [
{"time_start" : "20120314090000",
"p" : "99.306",
"time_end" : "20120315090000",
"time" : "20120315085500",
"q" : 254,
"v" : "0.90",
"trend" : "?"},
{"time_start" : "20120315090000",
"p" : "3.472",
"time_end" : "20120315095000",
"time" : "20120315095000",
"q" : 2,
"v" : "0.100",
"trend" : "?"}
],
"varto" : "10.00",
"accum_period" : 1440}
]
}
}
Retrieves a list of sites having data for one or more specified data sources
When HYDLLP is running under the Hydstra/WEB framework, certain privacy-sensitive information can be excluded from the returned data by settings in DATAPRIV.INI, which is administered by HYDATAPRIV. This lets you deny access to personal information in in the audit trail section of TS data blocks.
Changes for version 2
The version breaking change came about because we wanted a consistent return structure across all HYDLLP Json calls. The return structure has had a return element added at its base.
parameter |
description |
options |
example |
site_list |
Hydstra site list expression |
|
filter(table(site),match(h*)) |
datasources |
an array of one or more datasource codes |
|
'A','T' |
variables |
an array of one or more variable codes. (optional) |
|
'100','10' |
starttime |
a datetime, combined with endtime that all blocks returned must be at least partially between. (optional) |
|
'20110111143015' |
endtime |
a datetime, combined with starttime that all blocks returned must be at least partially between. (optional) |
|
'20110113143015' |
start_modified |
a datetime, combined with end_modified that the modified date of all blocks returned must be at least partially between. (optional) |
|
'20110111143015' |
end_modified |
a datetime, combined with start_modified that the modified date of all blocks returned must be at least partially between. (optional) |
|
'20110113143015' |
fill_gaps |
a boolean value used to request gaps returned as blocks with the block being marked as a gap. (optional) |
0 (false) 1 (true) |
'1' |
auditinfo |
a boolean value used to request the return of audit information. (optional, defaults to 0) |
0 (false) 1 (true) |
'1' |
Sample request
{
'function' => 'get_ts_blockinfo',
'version' => 2,
'params' => {
'site_list' => 'HYDSYS01,HYDSYS02',
'datasources' => ['A','B','C'],
'variables' => ['100.00','100.01','140.00'],
'starttime' => '19700801000000',
'endtime' => '19710805000000',
'start_modified'=>'20000101000000',
'end_modified'=>'20110201000000',
'auditinfo' => '0'
}
}
Sample return data
{
"buff_required" : 431,
"buff_supplied" : 1500,
"return" : {
"blocks" : [
{
"site" : "HYDSYS02 ",
"variable" : " 100.00",
"starttime" : "19700101000000",
"endtime" : "19710101000000",
"datasource" : "A"
},{
"site" : "HYDSYS02 ",
"variable" : " 100.00",
"starttime" : "19710101000000",
"endtime" : "19710122093200",
"datasource" : "A"
},{
"site" : "HYDSYS02 ",
"variable" : " 100.00",
"starttime" : "19710122093200",
"endtime" : "19720215145500",
"datasource" : "A"
}
],
}
"error_num" : 0
}
Retrieves a list of sites having data for one or more specified data sources
parameter |
description |
options |
example |
datasources |
an array of one or more datasource codes |
|
'A','T' |
Sample request
{
'function' => 'get_sites_by_datasource',
'version' => 1,
'params' => {
'datasources' => ['T','Z']
}
}
Sample return data
{ "error_num":0,
"buff_supplied":8192,
"buff_required":209,
"return":{
"datasources":[
{"datasource":"T",
"sites":["HYDSYS01", "HYDSYS02"]},
{"datasource":"Z",
"sites":["HYDSYS01"]}
]
}
}
Uses the variable conversion defined in the varcon table to appropriately adjust the value and quality provided.
Changes for version 2
The version breaking change came about because we wanted a consistent return structure across all HYDLLP Json calls. The return structure has had a return element added at its base.
parameter |
description |
options |
example |
site_list |
a Hydstra site list expression |
|
'filter(table(site),match(h*))' |
datasource |
the Hydstra datasource code (optional, defaults to A) |
|
'A' |
varfrom |
source variable |
|
'100' |
varto |
destination variable |
|
'140' |
rounding |
(optional) a rounding specification used by various JSonCall functions to format value results with a defined variable. |
|
JSonCall Number Formatting |
requests |
an Array of request objects |
qf1, quality code |
1 |
qf2 (optional), quality code |
155 |
||
t1, datetime |
19700125000000 |
||
t2 (optional), datetime |
19700126000000 |
||
vf1, value |
0.52 |
||
vf2 (optional), value |
1.93 |
||
dtransf1 (optional), datatrans |
2 |
||
dtrandf2 (optional), datatrans |
2 |
Sample request
{ 'function'=>'get_varcon',
'version'=>'2',
'params'=>{
'varcons'=>[
{ 'site_list'=>'HYDSYS01',
'datasource'=>'A',
'varfrom'=>'100.00',
'varto'=>'140',
'requests'=> [
{'qf1'=>'1','t1'=>'19700125000000','vf1'=>'0.082'},
{'qf1'=>'1','t1'=>'19700126000000','vf1'=>'0.111'},
{'qf1'=>'1','t1'=>'19700127000000','vf1'=>'0.160'},
]
}
]
}
}
Sample return data
{
"buff_required" : 352,
"return" : {
"varcons" : [
{
"site" : "HYDSYS01",
"varfrom" : "100.00",
"varto" : "140.00",
"datasource" : "A",
"results" : [
{
"vt" : "0.104",
"qt" : 1,
"qf1" : 1,
"t1" : "19700125000000",
"vf1" : "0.082"
},{
"vt" : "0.212",
"qt" : 1,
"qf1" : 1,
"t1" : "19700126000000",
"vf1" : "0.111"
},{
"vt" : "0.464",
"qt" : 1,
"qf1" : 1,
"t1" : "19700127000000",
"vf1" : "0.160"
}
]
}
],
}
"buff_supplied" : 1000,
"error_num" : 0
}
Get a representation of a rating table for a specific site.
parameter |
description |
options |
example |
site_list |
A site list |
|
HYDSYS01,HYDSYS02 |
table_from |
var_from, used to specify the rating table. |
|
100 |
table_to |
var_to, used to specift the rating table. |
|
140 |
interval |
The size of the gap you wish to have between input stage values. |
A real number |
1.5 |
datetime |
The date and time you want the rating table to be valid for. (optional defaults to right now) |
YYYYMMDDHHIIEE |
20131009115430 |
force_range |
Setting to 1 makes sure that the bounding points of the rating table are returned in the output. (optional defaults to 0) |
0 (false) 1 (true) |
1 |
quantised |
Setting to 1 rounds the value from values to the nearest interval before retrieving the value to. (optional defaults to 1) |
0 (false) 1 (true) |
1 |
shifts |
Setting to 1 applies the active shift to the rating table. Only applicable if there are shifts in the TSHIFT and/or SSHIFT tables. (optional defaults to 1) |
0 (false) 1 (true) |
1 |
lostage |
Lets you define the low pre shift stage value to interpolate from. (optional) |
A real number |
0.1 |
histage |
Lets you define the high pre shift stage value to interpolate to. (optional) |
A real number |
5.3 |
Sample request
{
'function' => 'get_effective_rating',
'version' => 1,
'params' => {
'site_list' => '410001,410734',
'table_from' => '100',
'table_to' => '140',
'interval' => '0.9',
'datetime' => '19930501000000',
'force_range' => '1',
'quantised' => '1',
'shifts' => '1'
}
}
Sample return data
{
"buff_required" : 1372,
"buff_supplied" : 1000000,
"signature" : "69FE92A2B9B54A1FE7A483C70517D8DC",
"error_num" : 0,
"return" : {
"sites" : [
{
"error_msg" : "Points rating table has no points:; STN =410001;
varfrom=100.00; varto =140.00; tabno =0.9; error in rating tables",
"error_num" : 33
},
{
"" : {
"quality_codes" : {
"150" : "Rating table extrapolated due to inadequate gauging
information"
}
},
"shifts" : "True",
"ctf" : "0.611",
"table_to" : "140.00",
"varfrom" : "100.00",
"table" : 7,
"points" : [
{
"vt" : "0.0",
"vf" : "0.0",
"q" : 1
},
{
"vt" : "0.7",
"vf" : "0.9",
"q" : 1
},
{
"vt" : "16.14716093",
"vf" : "1.8",
"q" : 1
},
{
"vt" : "71.09622802",
"vf" : "2.7",
"q" : 1
},
{
"vt" : "163.452929281",
"vf" : "3.6",
"q" : 1
},
{
"vt" : "245.0",
"vf" : "4.5",
"q" : 150
},
{
"vt" : "359.860718042",
"vf" : "5.4",
"q" : 150
},
{
"vt" : "491.196753205",
"vf" : "6.3",
"q" : 150
},
{
"vt" : "650.116112695",
"vf" : "7.2",
"q" : 150
},
{
"vt" : "800.0",
"vf" : "8.0",
"q" : 150
}
],
"varto" : "140.00",
"datetime" : "19930501000000",
"site_details" : {
"short_name" : "Qbn at Tinderry",
"timezone" : "10.0",
"name" : "Queanbeyan River at Tinderry"
},
"stage_low" : "0.0",
"name" : "",
"release" : 10,
"stage_high" : "8.0",
"interval" : "0.9",
"varto_details" : {
"subdesc" : "",
"variable" : "140.00",
"short_name" : "Discharge (Cumecs)",
"name" : "Stream Discharge",
"units" : "Cubic Metres/Second"
},
"site" : "410734",
"varfrom_details" : {
"subdesc" : "",
"variable" : "100.00",
"short_name" : "Level (Metres)",
"name" : "Stream Water Level",
"units" : "Metres"
},
"table_from" : "100.00"
}
]
}
}
Get GeoJSON and other site table field data for the requested site list.
Changes for version 2
The version breaking change was fixing the ordering of latitude and longitude in the coordinates. Longitude now comes before latitude as specified by the GeoJSON specifications. Longitude, latitude, and elevation are now returned as numbers instead of strings.
parameter |
description |
options |
example |
site_list |
A site list |
|
HYDSYS01,HYDSYS02 |
fields |
An array of fields to be returned as properties |
Any field that is part of the site table |
'zone','region' |
get_elev |
(optional) Return the elevation with the latitude and longitude? |
0 (false) 1 (true) |
1 |
Sample request
{
'function' => 'get_site_geojson',
'version' => 2,
'params' => {
'site_list' => 'HYDSYS01,HYDSYS02',
'get_elev' => 1,
'fields' => ['ZONE','region']
}
}
Sample return data
{
"buff_required" : 394,
"buff_supplied" : 1000000,
"error_num" : 0,
"return" : {
"features" : [
{
"type" : "Feature",
"id" : "HYDSYS01",
"geometry" : {
"coordinates" : [
149.31388889,
-35.33527778,
682.0"
],
"type" : "Point"
},
"properties" : {
"region" : "1",
"ZONE" : 55
}
},
{
"type" : "Feature",
"id" : "HYDSYS02",
"geometry" : {
"coordinates" : [
149.31805556,
-35.34722222,
582.0
],
"type" : "Point"
},
"properties" : {
"region" : "2",
"ZONE" : 55
}
}
],
"type" : "FeatureCollection"
}
}
(Do NOT use with REST web service requests.)
When reading a file, the data is kept in memory(cached) this is to improve performance when frequently performing operations on the same file. A side effect of this is that should you want to write to the file, you cant gain access to it. ClearTSCache erases the cache and relinquishes any locks on files that it had.
ClearTSCache is used when reading and writing in quick succession to time series files.
Sample request
{
'function' => 'clear_ts_cache',
'version' => 1,
'params' => {}
}
Sample return data
{
"buff_required" : 54,
"buff_supplied" : 1000000,
"error_num" : 0
}
Retrieves a list of datasources having data for one of more specified sites
parameter |
description |
options |
example |
site_list |
Hydstra site list expression |
|
201001 |
ts_classes |
(optional) an array of one or more of: ARCHIVE, WORK, AUX, TEMP |
|
'WORK','AUX' |
Sample request
{
'function' => 'get_datasources_by_site',
'version' => 1,
'params' => {
'site_list' => 'HYDSYS01,HYDSYS02,HYDSYS03'
}
}
Sample return data
{ "error_num":0,
"buff_required":282,
"buff_supplied":8192,
"return":{
"sites":[
{"site":"HYDSYS01",
"datasources":["A","B","C","D","T","X","Z"]},
{"site":"HYDSYS02",
"datasources":["A","B","T"]},
{"site":"HYDSYS03",
"datasources":["A"]}
]
}
}
Retrieves period-of-record information from time series files for a specified series of sites and datasources
parameter |
description |
options |
example |
site_list |
Hydstra site list expression |
|
201001,201003 |
datasource |
the Hydstra datasource code |
|
A |
var_filter |
Optional, a variable filter expression. If specified, only variable matching the filter will be included. See HYSTNS for more information on variable filter syntax. This is primarily designed to let you get the period of a
single variable in a TS file, so you dont have to iterate through a list of
all variables looking for the one you want. |
|
100.00 |
Sample request
{
'function' => 'get_variable_list',
'version' => 1,
'params' => {
'site_list' => 'HYDSYS03',
'datasource' => 'A'
}
}
Sample return data
{ "error_num":0,
"buff_required":484,
"buff_supplied":8192,
"return":{
"sites":[
{ "site":"HYDSYS03"
"site_details": {
"short_name":"Hydstra Test Station",
"name":"Hydstra Test Station - Wind data"},
"timezone":"10.0",
"variables":[
{ "variable":" 500.00",
"name":"Wind Direction",
"subdesc":"",
"units":"Degrees",
"period_end":"19860101000000",
"period_start":"19811230122900"},
{ "variable":" 520.00",
"subdesc":"",
"name":"Wind Run",
"units":"Kilometres",
"period_end":"19830101000000",
"period_start":"19811229212300"}
]
}
]
}
}
returns an ADO connection string and table string for a Hydstra table.
parameter |
description |
options |
example |
table_spec |
A table specification |
|
' [PUB.SITE]SITE' |
Sample request
{
'function' => 'get_ado_connection',
'version' => 1,
'params' => {
'table_spec' => '[PUB.SITE]SITE'
}
}
Sample return data
{
"buff_required" : 244,
"buff_supplied" : 1000000,
"error_num" : 0,
"result" : {
"database" : "F:\\HYD\\DAT\\WDB\\SITE\\",
"table" : "SITE",
"server" : "",
"schema" : "Driver={Microsoft Visual FoxPro
Driver};UID=;PWD=;SourceType=DBF;SourceDb=F:\\HYD\\DAT\\WDB\\SITE\\",
"rawname" : "F:\\HYD\\DAT\\WDB\\SITE\\SITE.DBF"
}
}
Note that the connection string is (somewhat confusingly) called schema (in contrast to get_odbc_connection).
returns an ODBC connection string and table string for a Hydstra table.
parameter |
description |
options |
example |
table_spec |
A table specification |
|
' [PUB.SITE]SITE' |
Sample request
{
'function' => 'get_odbc_connection',
'version' => 1,
'params' => {
'table_spec' => '[PUB.SITE]SITE'
}
}
Sample return data
{
"buff_required" : 244,
"buff_supplied" : 1000000,
"error_num" : 0,
"result" : {
"database" : "F:\\HYD\\DAT\\WDB\\SITE\\",
"table" : "SITE",
"server" : "",
"connect" : "Driver={Microsoft Visual FoxPro
Driver};UID=;PWD=;SourceType=DBF;SourceDb=F:\\HYD\\DAT\\WDB\\SITE\\",
"rawname" : "F:\\HYD\\DAT\\WDB\\SITE\\SITE.DBF"
}
}
Note that the connection string is called connect (in contrast to get_ado_connection).
retrieves the functional and descriptive details of a subvar
parameter |
description |
options |
example |
site_list |
Hydstra site list expression |
|
201001,201003 |
variable |
A Hydstra variable and subvariable |
|
100.01 |
Sample request
{
'function' => 'get_subvar_details',
'version' => 1,
'params' => {
'site_list' => 'hydsys01,hydsys02',
'variable' => '100.01'
}
}
Sample return data
{
"buff_required" : 281,
"buff_supplied" : 1000000,
"error_num" : 0,
"return" : {
"sites" : [
{
"max_gap" : "1.000",
"site" : "HYDSYS01",
"variable" : "100.01",
"desc" : "Logger",
"compress" : "True"
},{
"max_gap" : "1.000",
"site" : "HYDSYS02",
"variable" : "100.01",
"desc" : "Logger",
"compress" : "True"
}
]
}
}
table_doc_location
Returns the root location for documents associated with a nominated record in a table.
parameter |
description |
options |
example |
table_name |
The table name |
|
SITE |
key_fields |
A list of the key field names |
|
["STATION"] |
key_values |
The corresponding key values |
|
["HYDSYS01"] |
Sample request
{
'function' => 'table_doc_location',
'version' => 1,
'params' => {
'key_values' => [
'HYDSYS0'
],
'key_fields' => [
'station'
],
'table_name' => 'site'
}
}
Sample return data
{ "error_num":0,
"buff_required":484,
"buff_supplied":8192
"return":{
"location": "F:\\hyd\\dat\\doc\\SITE\\HYDSYS01\\"
}
}
Returns the table and key values associated with a file name in the documents tree.
parameter |
description |
options |
example |
location |
A folder or document name |
|
"f:\\hyd\\dat\\doc\\site\\hydsys01" |
Sample request
{
'function' => 'table_doc_record_key',
'version' => 1,
'params' => {
'location' => 'F:\hyd\dat\doc\SITE\HYDSYS01\'
}
}
Sample return data
{ "error_num":0,
"buff_required":484,
"buff_supplied":8192
"return":{
"table_name": "site",
"key_fields": ["station"],
"key_values": ["HYDSYS0"]
}
}
Returns site-related document details associated with one or more tables.
parameter |
description |
options |
example |
site_list |
Hydstra site list expression |
|
201001,201002 |
table_list |
A list of table names |
|
["SITE","HISTORY"] |
pattern |
(optional) A pattern so that only certain file names or extensions are returned |
|
|
root_url |
(optional) A root URL to replace \HYD\WEB folder |
|
|
Sample request
{
'function' => 'get_table_documents',
'version' => 1,
'params' => {
'site_list' => 'HYDSYS01,HYDSYS02',
'table_list' => ['site','history'],
'pattern' => '(\.jpg)|(\.doc)|(\.xls)'
}
}
Sample return data
{
"buff_required" : 1236,
"buff_supplied" : 1000000,
"error_num" : 0,
"return" : [
{
"station" : "HYDSYS01",
"tables" : {
"history" : [],
"site" : [
{
"filesize" : 61440,
"filename" : "F:/hyd/dat/doc/SITE/HYDSYS01/Excel
spreadsheet.xls"
},
{
"filesize" : 20480,
"filename" : "F:/hyd/dat/doc/SITE/HYDSYS01/Origin of HYDSYS test
data.doc"
},
{
"filesize" : 271973,
"filename" : "F:/hyd/dat/doc/SITE/HYDSYS01/Photo - Control
structure.jpg"
}
]
}
},
{
"station" : "HYDSYS02",
"tables" : {
"history" : [],
"site" : [
{
"filesize" : 61440,
"filename" : "F:/hyd/dat/doc/SITE/HYDSYS02/Excel
spreadsheet.xls"
},
{
"filesize" : 20480,
"filename" : "F:/hyd/dat/doc/SITE/HYDSYS02/Origin of HYDSYS test
data.doc"
},
{
"filesize" : 271973,
"filename" : "F:/hyd/dat/doc/SITE/HYDSYS02/Photo - Control
structure.jpg"
}
]
}
}
]
}
Return cross section details from the SECTHED and SECTIONS tables.
parameter |
description |
options |
example |
site_list |
Hydstra site list expression |
|
201001,201002 |
section_types |
A list of section types |
|
|
comments |
(optional) Include any section point comments? |
yes/no |
|
gauge_datum |
(optional) Subtract gauge zero (from SECTHED table) from all reduced levels? |
yes/no |
|
start_date |
(optional) Only return cross sections that were measured after this date |
|
|
end_date |
(optional) Only return cross sections that were measured before this date |
|
|
Sample request
{
'function' => 'get_cross_sections',
'version' => 1,
'params' => {
'site_list' => 'HYDSYS01,HYDSYS02',
'section_types' => ['xs'],
'comments' => 'yes',
'gauge_datum' => 'yes',
'start_date' => '19800101',
'end_date' => '19900101'
}
}
Sample return data
{
"buff_required" : 2903,
"buff_supplied" : 1000000,
"error_num" : 0,
"return" : [
{
"station" : "HYDSYS01",
"sections" : {
"820001" : [
{
"rl" : "8.620",
"chain" : "0.000",
"order" : 10,
"commnt" : ""
},
{
"rl" : "6.710",
"chain" : "19.000",
"order" : 20,
"commnt" : ""
},
...
{
"rl" : "7.480",
"chain" : "135.200",
"order" : 230,
"commnt" : ""
},
{
"rl" : "8.850",
"chain" : "139.690",
"order" : 240,
"commnt" : ""
}
],
"850006" : [
{
"rl" : "8.620",
"chain" : "0.000",
"order" : 10,
"commnt" : ""
},
{
"rl" : "6.710",
"chain" : "19.000",
"order" : 20,
"commnt" : ""
},
...
{
"rl" : "7.480",
"chain" : "135.200",
"order" : 230,
"commnt" : ""
},
{
"rl" : "8.850",
"chain" : "139.690",
"order" : 240,
"commnt" : ""
}
]
}
}
]
}}
Return group membership details.
parameter |
description |
options |
example |
site_list |
Hydstra site list expression |
|
201001,201002 |
group_list |
(optional) Only return membership details for these groups |
|
|
Sample request
{
'function' => 'get_groups',
'version' => 1,
'params' => {
'site_list' => 'HYDSYS01,HYDSYS02',
'group_list' => ['catch','region','visits']
}
}
Sample return data
{
"buff_required" : 979,
"buff_supplied" : 1000000,
"error_num" : 0,
"return" : [
{
"group" : "CATCH",
"value" : "410",
"value_decode" : "Murrumbidgee River Basin",
"stations" : [
"HYDSYS01"
],
"group_decode" : "Station Catchment"
},
{
"group" : "REGION",
"value" : "1",
"value_decode" : "Region 1",
"stations" : [
"HYDSYS01"
],
"group_decode" : "Station Region"
},
{
"group" : "VISITS",
"value" : "AREA1",
"value_decode" : "Area one",
"stations" : [
"HYDSYS02",
"HYDSYS01"
],
"group_decode" : "NT Grnd Water model"
}
]
}
When JSonCall() was introduced, we decided to encode all real numbers (numbers with decimals) as strings. We did this to avoid scientific notation (eg 1E-5), which we thought Perl couldnt handle (though it actually can). But since the primary use case was Perl, and Perl is not a strongly-typed language, it didnt matter. Perl was quite capable of taking the string values returned in JSON, and interpreting them as real values.
Now that we are also support Python, a strongly-typed language, we need the ability to return real numbers encoded in JSON as proper float format values.
To avoid causing any unintended side-effects on the Perl world, if you take no action, the feature will not be activated - HYDLLP will behave as it always has - encoding real values as strings.
To allow maximum flexibility across use cases, you can enable the feature in two ways:
Across entire session
Calling this function (with the FLOAT parameter value) will switch HYDLLP to encoding real values as JSON-format floats. You can switch it back again by calling the function with a value of STRING.
The Hydstra hydllp.py Python module calls this function automatically, so there are very few cases where you would need to call this function yourself.
For single call only
To allow use cases like web services, the feature is also available on a call-by-call basis for all JSonCall functions. You simply include the optional real_encoding parameter in your JSON data, that the feature will be enabled for that call only.
parameter |
description |
options |
example |
real_encoding |
How to encode real values in JSON? |
string / float |
201001,201002 |
Sample request
{
'function' => 'set_real_encoding',
'version' => 1,
'params' => {
'real_encoding' => 'float'
}
}
Sample return data
{
"error_num":0,
"buff_required":54,
"buff_supplied":1000000
}
(Do NOT use with REST web service requests.)
When reading a file, the data is kept in memory(cached) this is to improve performance when frequently performing operations on the same file. A side effect of this is that should you want to write to the file, you cant gain access to it. clear_db_cache erases the cache and relinquishes any locks on files that it had.
clear_db_cache is used when reading and writing is being held up by file access on currently unused databases.
parameter |
description |
options |
example |
|
db_list |
Lets you specify which tables should be removed from the memory chache. (optional) |
Default / Parameter not used |
All user-opened tables, plus system lookup tables only |
rateper,ratehed |
+ |
All user-opened tables, plus all system tables |
|||
table1,table2 |
A comma separated list of tables |
Sample request
{
'function' => clear_db_cache',
'version' => 1,
'params' => {
'db_list' => rateper,ratehed'
}
}
Sample return data
{
"error_num":0,
"buff_required":54,
"buff_supplied":1000000
}
get_hybatch_sections
Return HYBATCH details on precomputed reports, documents and applications.
parameter |
description |
options |
example |
site_list |
Hydstra site list expression |
|
201001,201002 |
reports_section |
(optional) HYBATCH reports section |
|
|
documents_section |
(optional) HYBATCH documents section |
|
|
applications_section |
(optional) HYBATCH applications section |
|
|
Sample request
{
'function' => 'get_hybatch_sections',
'version' => 1,
'params' => {
'site_list' => 'HYDSYS01,HYDSYS02',
'reports_section' => 'sample',
'documents_section' => 'documents',
'applications_section' => ''
}
}
Sample return data
{
"buff_required" : 6093,
"buff_supplied" : 1000000,
"error_num" : 0,
"return" : [
{
"station" : "HYDSYS01",
"documents" : {
"outputs" : [
{
"filesize" : 61440,
"filename" : "F:/hyd/dat/doc/SITE/HYDSYS01/Excel
spreadsheet.xls",
"heading" : "Excel spreadsheet",
"type" : "DOC"
},
{
"filesize" : 6048,
"filename" : "F:/hyd/dat/doc/SITE/HYDSYS01/index.htm",
"heading" : "index",
"type" : "DOC"
},
],
"section" : "documents"
},
"reports" : {
"outputs" : [
{
"filesize" : 12511,
"filename" : "F:/hyd/map/demo/HYDSYS01.SSM.txt",
"heading" : "HYSITREP Site Summary report",
"type" : "PRN"
},
{
"filesize" : 37430,
"filename" : "F:/hyd/map/demo/HYDSYS01.MXP.wip",
"heading" : "HYMXMEAN Plot of Daily Flows",
"type" : "PLT"
},
],
"section" : "sample"
}
}
]
}}
Call multiple functions at once, if performance is critical.
parameter |
description |
options |
example |
function_list |
A list of other JSonCall function parameters |
|
|
Sample request
{
'function' => 'multi_call',
'version' => 1,
'params' => {
'function_list' => [
{
'function' => 'get_datasources_by_site',
'version' => 1,
'params' => {
'site_list' => 'HYDSYS01,HYDSYS02'
}
},
{
'function' => 'get_variable_list',
'version' => 1,
'params' => {
'site_list' => 'HYDSYS01,HYDSYS02',
'datasource' => 'A'
}
}
]
}
}
Sample return data
{
"buff_required" : 3971,
"buff_supplied" : 1000000,
"error_num" : 0,
"return" : [
{
"error_num" : 0,
"return" : {
"sites" : [
{
"datasources" : [
"A",
"C",
"D",
"E",
"S",
"T",
"movingmean(a,100,day,5)",
"movingmean(a,100,hour,5)",
"CTF(100,140)"
],
"site" : "HYDSYS01"
},
{
"datasources" : [
"A"
],
"site" : "HYDSYS02"
}
]
}
},
{
"error_num" : 0,
"return" : {
"sites" : [
{
"site" : "HYDSYS01",
"site_details" : {
"short_name" : "Hydstra Test Station",
"name" : "Hydstra Test Station - Composite data"
},
"variables" : [
{
"subdesc" : "",
"variable" : "10.00",
"period_start" : "19620601151500",
"period_end" : "19870630095000",
"name" : "Rainfall",
"units" : "Millimetres"
},
{
"subdesc" : "",
"variable" : "100.00",
"period_start" : "19591210174000",
"period_end" : "19860226101500",
"name" : "Stream Water Level",
"units" : "Metres"
}
]
}
]
}
}
]
}
get_decoded_value
Returns a fields decode value if it exists for the provided value.
parameter |
description |
options |
example |
decode_requests |
An array of request objects |
value |
100 |
|
|
table |
GAUGINGS |
|
|
field |
METHOD |
Sample request
{
'function' => 'get_decoded_value',
'version' => 1,
'params' => {
'decode_requests' => [
{
'value' => '100',
'table' => 'RATEHED',
'field' => 'VARFROM'
},{
'value' => 'WA',
'table' => 'GAUGINGS',
'field' => 'METHOD'
}
]
}
}
Sample return data
{
"buff_required" : 238,
"buff_supplied" : 1000,
"error_num" : 0,
"return" : {
"decode_results" : [
{
"decode" : "Level (Metres)",
"value" : "100",
"table" : "RATEHED",
"field" : "VARFROM"
},{
"decode" : "Wading",
"value" : "WA",
"table" : "GAUGINGS",
"field" : "METHOD"
}
]
}
}
Write a log entry to HYDLOG.TXT or a nominated HYDEBUG file
parameter |
description |
options |
example |
log_type |
The type of log |
HYDLOG, |
|
app_name |
Calling application name |
|
201001,201003 |
topic |
Main keyword of log entry |
|
INFO, ERROR etc |
log_file |
Filename for HYDEBUG output only |
|
|
message |
the message string to write |
|
|
Sample request
{
'function' => 'write_log',
'version' => 1,
'params' => {
'topic' => 'INFO',
'app_name' => 'MYAPP',
'log_type' => 'HYDLOG',
'message' => 'Opening data file'
}
}
Sample return data
{ "error_num":0,
"buff_required":484,
"buff_supplied":8192
}
get_widget
Generates a widget/plot that is then returned in base64 encoding.
Every get_widget request has an array of 'widgets' directly under params. Each of these widgets can be a plotlet, weir or storage.
Sample request
{
'function' => 'get_widget',
'version' => 1,
'params' => {
'widgets' => [
{ first widgets parameters },
{ second widgets parameters }
]
}
}
Colour codes supported by the get_widget call are:
black silver lightgrey ltgrey
darkgrey
dkgrey grey blue ltblue lightblue
navy dkblue darkblue green dkgreen
darkgreen lime ltgreen lightgreen red
ltred lightred maroon dkred darkred
cyan teal dkcyan darkcyan aqua
ltcyan lightcyan magenta pink purple
dkpurple darkpurple ltpurple lightpurple brown
olive orange yellow white transparent_color
plotlet
This section specifies the parameter set used by the plotlet widget
parameter |
description |
options |
example |
widget_type |
The type of widget |
plotlet, weir, storage |
plotlet |
widget_width |
The width of the returned image |
|
200 |
widget_height |
The height of the returned image |
|
200 |
id |
The id assigned to this widget for later reference |
|
first plot |
fill_color |
The color outside the plot area (optional) |
BBGGRR format or supported color literal (default: white) |
$FF0000 (or blue) |
fill_gradient_color |
If specified then the colour outside the plot area will shift from fill_color (top) into fill_gradient_color (bottom) (optional) |
BBGGRR format or supported color literal (default: nothing) |
$0000FF (or red) |
transparent_color |
Transparent_color specifies which color should be made transparent. Anti-aliasing gets performed before the background can be made transparent by using transparent_color in place of a color value for any color parameter and if your transparent_color doesnt match the background that the image will be placed on then you get an undesirable effect. (optional) |
BBGGRR format or supported color literal (default: white) |
$123456 |
title |
Title displayed at the top of the image (optional) |
|
|
title_height |
Font size of the title (optional but only used if title is specified, defaults to 15) |
|
9 |
starttime |
Plot start time |
YYYYMMDDHHIIEE |
19600221090000 |
endtime |
Plot end time (optional if period and period_multiplier are provided) |
YYYYMMDDHHIIEE |
19600228090000 |
interval |
Gather data from the trace every interval_multiplier * interval. For example interval_multiplier => 3 and interval => hour |
second, minute, hour, day, week, month, year |
hour |
interval_multiplier |
|
|
3 |
period |
Period_multiplier * period defines the duration of the plot. Using these settings causes the X-Axis to display differently. (optional if endtime is provided) |
second, minute, hour, day, week, month, year |
hour |
period_multiplier |
|
|
159 |
show_lines |
Displays lines in-between data points (optional, defaults to yes) |
0 (false) 1 (true) |
0 |
show_points |
Displays a circle around data points (optional, defaults to no) |
0 (false) 1 (true) |
0 |
filled |
Fills underneath the graph (optional, defaults to no) |
0 (false) 1 (true) |
1 |
invert |
Changes the direction of the Y-Axis (optional, defaults to no) |
0 (false) 1 (true) |
1 |
background_color |
The color inside the plot area (optional) |
BBGGRR format or supported color literal (default: white) |
$0000FF (or red) |
background_gradient_color |
If specified then the colour inside the plot area will shift from background_color (top) into background_gradient_color (bottom) (optional) |
BBGGRR format or supported color literal (default: nothing) |
$0000FF (or red) |
show_bad_qual |
If false then bad quality data won't be displayed by the plot (optional) |
0 (false) 1 (true) (default: 0) |
1 |
grid_color |
Sets the colour of the grid lines inside the plot area. Set to -1 to disable the grid lines. |
-1, BBGGRR format or supported color literal (default: silver) |
$0000FF (or red) |
suppress_x_axis |
If set to yes then this will remove the X-Axis from the plot. |
0 (false) 1 (true) (default: 0) |
0 |
suppress_y_axis |
If set to yes then this will remove the Y-Axis from the plot. |
0 (false) 1 (true) (default: 0) |
1 |
line_thickness |
Lets you set the thickness of the trace line in pixels |
|
2 |
trace_requests |
An array of trace requests |
see below |
see below |
trace request parameters
parameter |
description |
options |
example |
site |
A Hydstra site |
|
HYDSYS01 |
datasource |
The Hydstra datasource |
|
A |
varfrom |
Source variable |
|
100.00 |
varto |
Destination variable |
|
140.00 |
trace_type |
Data aggregation type |
max: maximum point in period. min: minimum point in period. period: mean value in period. mean: mean value in period. cum: cumulative trace from period values. tot: total cumulative value in period. start: instantaneous value at the start of the period. end: instantaneous value at the end of the period. first: first point in the period if there are any. last: last point in the period if there are any. startpoint: value of point at period start if there are any. endpoint: value of point at period end if there are any. maxmin: max and min values in the period. maxminpt: max and min points in the period if they exist. point: stored points. pointbnds: stored point with start and end values if they dont coincide with a point. |
max |
axis_align |
Defines which axis this trace is associated with |
left, right |
left |
color |
The colour of this trace |
BBGGRR format or supported color literal |
$0000FF (or red) |
trace_fill |
This lets you control whether and how the trace is filled in: If you specify NO, then the trace is not filled in unless the default for the graph type is to be filled. Bar graphs for example are filled by default. If you specify YES, then the trace is filled in using a method specified in the TraceFillPercent keyword in your WIP.INI. This is a percentage, where 0% is white and 100% is the same as the trace line. A value of 50%, being halfway between those colours, is the default. Any other value is assumed to be a literal colour name / RGB hex value, following the standard Hydstra colour naming rules. See WIP.INI for more information. (optional) |
YES, NO, BBGGRR format or supported color literal (default: NO) |
YES |
bad_color |
The color that is used for bad quality data if show_bad_qual is yes (optional) |
BBGGRR format or supported color literal (default: red) |
$0000FF (or red) |
Sample request
{ 'function' => 'get_widget',
'version' => 1,
'params' => {
'widgets' => [
{
'widget_type' => 'plotlet',
'widget_width' => '400',
'widget_height' => '400',
'id' => '1',
'title' => 'HYDSYS01 Latest Data',
'title_height' => '9',
'starttime' => '19600221000000',
'endtime' => '19600326000000',#optional
'interval' => 'hour',
'interval_multiplier' => '12',
#'period' => 'day',
#'period_multiplier' => '4',
'show_lines' => 1,
'show_points' => 1,
'filled' => 0, #max and min trace types are bar graphs which are always
filled.
'invert' => 0,
'background_color' => 'White',
#'background_gradient_color' => 'transparent_color',
'fill_color' => '$FCFEFF',
'fill_gradient_color' => '$DEFAFF',
#'transparent_color' => 'White',
'show_bad_qual' => '1',
#'grid_color' => '-1',
#'suppress_x_axis' => 1,
#'suppress_y_axis' => 1,
'trace_requests' => [
{
'site' => 'HYDSYS01',
'datasource' => 'A',
'varfrom' => '100',
'varto' => '100.00',
'trace_type' => 'max',
'axis_align' => 'left',
'color' => '$C6BE6B',
'bad_color' => 'blue'
},{
'site' => 'HYDSYS01',
'datasource' => 'B',
'varfrom' => '100',
'varto' => '100.00',
'trace_type' => 'min',
'axis_align' => 'left',
'color' => '$CC6699',
'bad_color' => 'blue'
}]
}
]
}
}
Sample return data
{
"buff_required" : 11605,
"buff_supplied" : 1000000,
"error_num" : 0,
"return" : {
"widgets" : [
{
"width" : "400px",
"id" : "1",
"height" : "400px",
"base64_widget" :
"iVBORw0KGgoAAAANSUhEUgAAAZAAAAGQCAIAAAAP3aGbAAAABnRSTlMA/wD/AP83WBt9AAAfR0lE\r\n
QVR42u2dSYwc53WAq0mK2Zw9lhFYMWJ7hrZpWV6kbDOke+AbaR94oWDkwtsQiBsgLwZ84JGHALyQ\r\n
{* Many more lines have been removed *}
QFgAYAaEBQBmQFgAYAaEBQBmQFgAYIb/B3fvE9skGvn2AAAAAElFTkSuQmCC"
}
]
}
}
weir
This section specifies the parameter set used by the weir widget.
parameter |
description |
options |
example |
widget_type |
The type of widget |
plotlet, weir, storage |
weir |
widget_width |
The width of the returned image |
|
200 |
widget_height |
The height of the returned image |
|
200 |
id |
The id assigned to this widget for later reference |
|
first weir |
fill_color |
The color outside the plot area (optional) |
BBGGRR format or supported color literal (default: white) |
$FF0000 (or blue) |
fill_gradient_color |
If specified then the colour outside the plot area will shift from fill_color (top) into fill_gradient_color (bottom) (optional) |
BBGGRR format or supported color literal (default: nothing) |
$0000FF (or red) |
transparent_color |
Transparent_color specifies which color should be made transparent. Anti-aliasing gets performed before the background can be made transparent by using transparent_color in place of a color value for any color parameter and if your transparent_color doesnt match the background that the image will be placed on then you get an undesirable effect. (optional) |
BBGGRR format or supported color literal (default: white) |
$123456 |
layout |
A weir layout specification. |
see below |
see below |
left_side |
A side specification defining the water level and other details of the left side |
see below |
see below |
right_side |
A side specification defining the water level and other details of the right side |
see below |
see below |
reference_levels |
An array of reference levels. A reference level creates a line at a given level (optional) |
see below |
see below |
Weir layout parameters
parameter |
description |
options |
example |
base |
The weir level goes from base to full_scale up the Y-Axis |
|
0 |
weir_height |
The height of the weir relative to the full_scale |
|
4 |
full_scale |
The weir level goes from base to full_scale up the Y-Axis |
|
5 |
title |
Title displayed at the top of the image. |
|
Wobbly Weir |
show_scale |
Defines whether or not the Y-Axis will have labels on it. |
0 (false) 1 (true) |
1 |
background |
No longer available |
BBGGRR format or supported color literal |
$0000FF (or red) |
box_fill |
The color inside the weir diagram area (optional) |
BBGGRR format or supported color literal (default: -1/clear) |
$0000FF (or red) |
box_gradient_fill |
If specified then the colour inside the weir diagram area will shift from background_color (top) into background_gradient_color (bottom) (optional) |
BBGGRR format or supported color literal (default: -1/clear) |
$0000FF (or red) |
level_fill |
The color of the depicted levels on either side of the weir |
BBGGRR format or supported color literal |
$0000FF (or red) |
weir_fill |
The color of the weir in the weir diagram |
BBGGRR format or supported color literal |
$0000FF (or red) |
value_text_color |
The font color of the title, Y-Axis, and value readings |
BBGGRR format or supported color literal |
$0000FF (or red) |
weir_width |
The percent of the image width that will be occupied by the weir. |
|
8 |
value_text_height |
The minimum font size that text can be displayed as |
|
10 |
value_text_limit |
The maximum font size that text can be displayed as |
|
15 |
top_margin |
The percent of the image height that will be taken up by the top margin |
|
10 |
left_margin |
The percent of the image width that will be taken up by the left margin |
|
15 |
right_margin |
The percent of the image width that will be taken up by the right margin |
|
5 |
bottom_margin |
The percent of the image height that will be taken up by the bottom margin |
|
5 |
shadow |
Displays a shadow styled border around the diagram |
0 (false) 1 (true) |
1 |
side parameters
parameter |
description |
options |
example |
offset |
Increase the value by |
|
1.0 |
value_snapshot_data |
A value snapshot specification |
see below |
see below |
value snapshot parameters
parameter |
description |
options |
example |
site |
A Hydstra site |
|
HYDSYS01 |
datasource |
The Hydstra datasource |
|
A |
varfrom |
Source variable |
|
100.00 |
varto |
Destination variable |
|
140.00 |
starttime |
Start time of aggregation |
YYYYMMDDHHIIEE |
19600221090000 |
endtime |
End time of aggregation |
YYYYMMDDHHIIEE |
19600228090000 |
value_type |
Data aggregation type |
max: maximum point in period. min: minimum point in period. period: mean value in period. start: instantaneous value at the start of the period. end: instantaneous value at the end of the period. first: first point in the period if there are any. last: last point in the period if there are any. |
max |
value_format |
Label above depicted level (%VALUE% macro will be replaced with the actual value) |
|
%VALUE% ML |
missing_format |
Message displayed when data missing |
|
(Missing) |
precision |
Number of decimals to provide in the output value (optional) |
|
0.001 |
reference level parameters
parameter |
description |
options |
example |
level |
The value of level will define how far up the Y-Axis the reference level will be. Level is a literal level and not a percent. |
|
4 (if the Y-Axis goes to 5 then 4 is 80% of the way up it, where 4 would be marked) |
color |
The color used to draw the reference level on the weir diagram |
BBGGRR format or supported color literal |
$0000FF (or red) |
style |
The style of the reference line |
dot, solid, dash |
dot |
label |
The text to associate with the reference level (displayed just above) |
|
2010 or Max allowed |
Sample request
{
'function' => 'get_widget',
'version' => 1,
'params' => {
'widgets' => [
{
'widget_type' => 'weir',
'widget_width' => '400',
'widget_height' => '400',
'id' => '1',
'fill_color' => '$F2DFD0',
'fill_gradient_color' => 'White',
'layout' => {
'base' => '0',
'weir_height' => '4',
'full_scale' => '5',
'title' => 'Wobbly Weir',
'show_scale' => 1,
'box_fill' => '$F8D7C4',
'box_gradient_fill' => 'White',
'level_fill' => 'blue',
'weir_fill' => 'silver',
'value_text_color' => 'black',
'weir_width' => '8',
'value_text_height' => '10',
'value_text_limit' => '15',
'top_margin' => '10',
'left_margin' => '15',
'right_margin' => '5',
'bottom_margin' => '5',
'shadow' => 1
},
'left_side' => {
'offset' => '0.0',
'value_snapshot_data' => {
'site' => 'HYDSYS01',
'datasource' => 'A',
'varfrom' => '100.00',
'varto' => '100',
'starttime' => '19750918000000',
'endtime' => '19750921000000',
'value_type' => 'last',
'value_format' => '%VALUE%ML',
'missing_format' => '(Missing)',
'precision' => '0.001'
}
},
'right_side' => {
'offset' => '0.0',
'value_snapshot_data' => {
'site' => 'HYDSYS01',
'datasource' => 'A',
'varfrom' => '100.00',
'varto' => '100',
'starttime' => '19750918000000',
'endtime' => '19750921000000',
'value_format' => '%VALUE%',
'missing_format' => '(Missing)',
'precision' => '0.001',
'value_type' => 'last'
}
},
'reference_levels' => [
{
'level' => '4.0',
'color' => 'blue',
'style' => 'dot',
'label' => '2010'
},{
'level' => '3.2',
'color' => 'blue',
'style' => 'dot',
'label' => '2009'
}
]
}
]
}
}
Sample return data
{
"buff_required" : 9221,
"buff_supplied" : 1000000,
"error_num" : 0,
"return" : {
"widgets" : [
{
"width" : "400px",
"id" : "1",
"height" : "400px",
"base64_widget" :
"iVBORw0KGgoAAAANSUhEUgAAAZAAAAGQCAIAAAAP3aGbAAAABnRSTlMA/wD/AP83WBt9AAAYmklE\r\n
{* Many more lines have been removed *}
BAuAGgQLgBoEC4AaBAuAGgQLgBoEC4Aa/w/kCxMKAWNdMwAAAABJRU5ErkJggg=="
}
]
}
}
storage
This section specifies the parameter set used by the storage widget.
parameter |
description |
options |
example |
widget_type |
The type of widget |
plotlet, weir, storage |
storage |
widget_width |
The width of the returned image |
|
200 |
widget_height |
The height of the returned image |
|
200 |
id |
The id assigned to this widget for later reference |
|
first storage |
fill_color |
The color outside the plot area (optional) |
BBGGRR format or supported color literal (default: white) |
$FF0000 (or blue) |
fill_gradient_color |
If specified then the colour outside the plot area will shift from fill_color (top) into fill_gradient_color (bottom) (optional) |
BBGGRR format or supported color literal (default: nothing) |
$0000FF (or red) |
transparent_color |
Transparent_color specifies which color should be made transparent. Anti-aliasing gets performed before the background can be made transparent by using transparent_color in place of a color value for any color parameter and if your transparent_color doesnt match the background that the image will be placed on then you get an undesirable effect. (optional) |
BBGGRR format or supported color literal (default: white) |
$123456 |
layout |
A storage layout specification |
see below |
see below |
value_snapshot_data |
A value snapshot specification |
see below |
see below |
reference_levels |
An array of reference levels. A reference level creates a line at a given level (optional) |
see below |
see below |
storage layout parameters
parameter |
description |
options |
example |
storage_min |
The storage level goes from storage_min to storage_max up the Y-Axis |
|
0 |
storage_max |
The storage level goes from storage_min to storage_max up the Y-Axis |
|
5 |
title_1 |
Title displayed at the top of the image. |
|
|
title_2 |
A second title displayed within but at the top of the
storage (optional) |
|
%VALUE% GL |
title_color |
The color used when displaying title_1 and title_2 |
BBGGRR format or supported color literal |
$0000FF (or red) |
shape |
The shape of the storage in the diagram |
opentrapezoid, semiellipse, roundedrectangle, vnotch, narrowbar |
opentrapezoid |
font_limit |
The maximum font size for all text on the storage diagram |
|
15 |
outline_color |
The color used to draw the storage outline and the text that shows how much is in the storage |
BBGGRR format or supported color literal |
$0000FF (or red) |
fill_color |
The color of the depicted level of the storage |
BBGGRR format or supported color literal |
$0000FF (or red) |
top_margin |
The percent of the image height that will be taken up by the top margin |
|
10 |
left_margin |
The percent of the image width that will be taken up by the left margin |
|
15 |
right_margin |
The percent of the image width that will be taken up by the right margin |
|
5 |
bottom_margin |
The percent of the image height that will be taken up by the bottom margin |
|
5 |
shadow |
Displays a shadow styled border around the diagram |
0 (false) 1 (true) |
1 |
value snapshot parameters
parameter |
description |
options |
example |
site |
A Hydstra site |
|
HYDSYS01 |
datasource |
The Hydstra datasource |
|
A |
varfrom |
Source variable |
|
100.00 |
varto |
Destination variable |
|
140.00 |
starttime |
Start time of aggregation |
YYYYMMDDHHIIEE |
19600221090000 |
endtime |
End time of aggregation |
YYYYMMDDHHIIEE |
19600228090000 |
value_type |
Data aggregation type |
max: maximum point in period. min: minimum point in period. period: mean value in period. start: instantaneous value at the start of the period. end: instantaneous value at the end of the period. first: first point in the period if there are any. last: last point in the period if there are any. |
max |
value_format |
Label above depicted level |
|
%VALUE% ML |
missing_format |
Message displayed when data missing |
|
(Missing) |
precision |
Precision required in the output value (optional) default: VARIABLE:PRECISION setting |
|
0.001 |
reference level parameters
parameter |
description |
options |
example |
Level |
The value of level will define how far up the Y-Axis the reference level will be. Level is a literal level and not a percent. |
|
4 (if the Y-Axis goes to 5 then 4 is 80% of the way up it, where 4 would be marked) |
color |
The color used to draw the reference level on the weir diagram |
BBGGRR format or supported color literal |
$0000FF (or red) |
style |
The style of the reference line |
dot, solid, dash |
dot |
label |
The text to associate with the reference level (displayed just above) |
|
2010 or Max allowed |
Sample request
{
'function' => 'get_widget',
'version' => 1,
'params' => {
'widgets' => [
{
'widget_type' => 'storage',
'widget_width' => '400',
'widget_height' => '400',
'id' => '1',
'fill_color' => '$464646',
'fill_gradient_color' => '$747474',
'layout' => {
'title_1' => 'Lake Fido Storage',
'title_2' => '%VALUE% GL',
'title_color' => 'web_Lightgrey',
'top_margin' => '10',
'left_margin' => '5',
'right_margin' => '5',
'bottom_margin' => '5',
'storage_min' => '-0.01',
'storage_max' => '5.0',
'shape' => 'cone',
'shadow' => 1,
'font_limit' => '15',
'outline_color' => 'Silver',
'fill_color' => '$FF7F7F'
},
'value_snapshot_data' => {
'site' => 'HYDSYS01',
'datasource' => 'A',
'varfrom' => '100.00',
'varto' => '100',
'starttime' => '19750918000000',
'endtime' => '19750921000000',
'precision' => '0.001',
'value_type' => 'last',
'value_format' => '%VALUE%',
'missing_format' => '(Missing)',
},
'reference_levels' => [
{
'level' => '4.5',
'color' => '$FF7F7F',
'style' => 'dot',
'label' => '2010'
},{
'level' => '4.0',
'color' => '$FF7F7F',
'style' => 'dot',
'label' => '2009'
}
]
}
]
}
}
Sample response data
{
"buff_required" : 7082,
"buff_supplied" : 1000000,
"error_num" : 0,
"return" : {
"widgets" : [
{
"width" : "400px",
"id" : "1",
"height" : "400px",
"base64_widget" :
"iVBORw0KGgoAAAANSUhEUgAAAZAAAAGQCAIAAAAP3aGbAAAABnRSTlMA/wD/AP83WBt9AAASqElE\r\n
{* Many more lines have been removed *}
WEAYggWEMfLoo49WfQ4A8yJYQBiCBYQhWEAYggWEIVhAGIIFhCFYQBj/D3MoRVvd/pMbAAAAAElF\r\n
TkSuQmCC"
}
]
}
}
Scans a time series trace for all contributing components that have been modified within a specified period, and produce a list of sub-periods thus affected.
The context in which this might be used is a script to send data incrementally to a third party, and each time you run the job you need to ask what has been modified since the last time I ran this job?
Change-contributors include the actual time series data itself, rating tables and time-based tables used as part of variable conversion.
parameter |
description |
options |
example |
site_list |
A list of sites to process |
201001,201003 |
|
datasource |
The data source of the traces |
|
A |
var_from |
The source variable of the traces |
|
100.00 |
var_to |
The converted variable of the traces |
|
140 |
mods_from |
The start date and time of the window of modification times. |
|
20180320123000 |
mods_to |
The end date of the modification windows, typically a far-future date. |
|
21000101000000 |
Sample request
{
'function' => 'get_recalculation_periods',
'version' => 1,
'params' => {
'site_list' => 'HYDSYS01',
'datasource' => 'A',
'varfrom' => '100.00',
'varto' => '140.00',
'mods_from' => '19800101000000',
'mods_to' => '21000101000000'
}
}
Sample return data
{
"buff_required" : 203,
"buff_supplied" : 1000000,
"error_num" : 0,
"return" : {
"sites" : [
{
"site" : "HYDSYS01",
"latest_mod" : "20160913112400"
"periods" : [
{
"period_start" : "19290101000000",
"period_end" : "19860226101500"
}
],
}
]
}
}
returns a hash of the same HYBATCH environment information as is written by the HYBATCH program. This can allow scripts to perform some special case programming, with the convenience of HYDLLP rather than executing HYBATCHE.
parameter |
description |
options |
example |
batch_code |
The HYBATCH section code |
PRECOMP |
|
site |
The site of interest |
|
HYDSYS10 |
datasource |
The source variable of the traces |
|
A |
starttime |
The converted variable of the traces |
(optional) |
20180201000000 |
endtimem |
The start date and time of the window of modification times. |
(optional, both missing means period of record) |
20180301000000 |
Sample request
{
'function' => 'get_hybatch_env',
'version' => 1,
'params' => {
'batch_code' => 'precomp',
'site' => 'HYDSYS01',
'datasource' => 'A',
'starttime' => '20180201000500',
'endtime' => '20180401000500'
}
}]
Sample return data (extract)
{
"buff_required" : 7572,
"buff_supplied" : 1000000,
"error_num" : 0,
"return" : {
"print" : "C:\\TEMP\\JUNK",
"site.category15" : "",
"vmend(140.02)" : "01/01/1987",
"clearoutputs" : "yes",
"rainhours" : "900",
"site.timecreate" : "0",
"site.shortname" : "Hydstra Test Station",
"site.elev" : "682",
"stnini.stagerange" : "-0.05,3.0",
"vwystart(220.00)" : "1938",
"site.zone" : "55",
"site.station" : "HYDSYS01",
"latestrating3" : "-1",
"site.latitude" : "-35.33527778",
"site.category19" : "",
"site.longitude" : "149.31388889",
"vmend(100.00)" : "01/02/1986",
"vmend(220.00)" : "01/01/1988",
"vwystart(140.01)" : "1959",
"vpstart(140.01)" : "01/01/1959",
"site.hut" : "False",
"latestratsite" : "0",
"periodvar" : "100.00",
"startwyear" : "2018",
<>
}
}
Check whether a supplied user ID and password is authenticated according to the PASSWD table. Note that no logging on is performed, just a simple authentication check.
parameter |
description |
options |
example |
user_id |
The user id |
JCITIZEN |
|
password |
The password |
|
as_if |
Sample request
{
"function" : 'authenticate_user',
"version" : 1,
"params" : {
"user_id" : 'user2',
"password" : 'pass2',
}
}
Sample return data
{
"return" : {
"authenticated" : "true"
},
"error_num" : 0,
"buff_supplied" : 1000000,
"buff_required" : 86
}
Returns a list of available templated output applications. Templates are special automation files that live in a folder under INIPATH called TEMPLATE, with the ability for the caller to specify selected parameters. This allows applications to be run by the caller, without compromising security, as you can control
which applications are exported
which parameters may be modified
what values those parameters may take
This call has no parameters, though you must provide an empty params json element.
Sample request
{
'function' => 'get_template_list',
'version' => 1,
'params' => {}
}
Sample return data
{
"buff_required" : 900,
"buff_supplied" : 1000000,
"error_num" : 0,
"return" : [
{
"params" : [
{
"name" : "site",
"default" : "HYDSYS01",
"validation" : "^[0-9A-Z_.]{1,20}$",
"description" : "Site to plot"
},
{
"name" : "startmonth",
"default" : "1",
"validation" : "^\\d+$",
"description" : "Start month in year"
},
{
"name" : "startyear",
"default" : "0",
"validation" : "^\\d\\d\\d\\d$",
"description" : "Start year"
},
{
"name" : "endyear",
"default" : "0",
"validation" : "^\\d\\d\\d\\d$",
"description" : "End year"
},
{
"name" : "printtype",
"default" : "HTM",
"validation" : "(^TXT$)|(^HTM$)",
"description" : "Report Type"
}
],
"name" : "Daily Flow Report",
"description" : "Report Daily flows for a year"
"content":"&hyd-junkpath.template.&prm-printtype.",
"type":"&prm-printtype.",
"encoding":"base64"
},
{
"params" : [
{
"name" : "site",
"default" : "HYDSYS01",
"validation" : "^[0-9A-Z_.]{1,20}$",
"description" : "Site to plot"
},
{
"name" : "plottype",
"default" : "SVG",
"validation" : "^PNG$|^SVG$",
"description" : "Plot type to return"
}
],
"name" : "Simple Plot",
"description" : "Plot period of record stage"
"content":"&hyd-junkpath.template.&prm-plottype.",
"type":"&prm-plottype.",
"encoding":"base64" }
]
}
Runs a templated output application and returns the output. Templates are named in the template path with any name and '.aut' extension, e.g.
\hyd\dat\ini\template\Flow Plot.aut
and called without the '.aut'.
Read up on HYDLLP Templated Output for more information on using templates from the DLL.
parameter |
description |
options |
example |
template_name |
The name of the template, not including the '.aut' extension. |
as returned by get_template_list |
Flow Plot |
template_params |
An array of template parameter objects |
|
|
name |
(within a template_params item) the name of the parameter |
Must be a parameter specified in the nominated template |
site |
value |
(within a template_params item) the value you wish to specify for that parameter |
Must match the validation regular expression in the template (if one is specified) |
HYDSYS01 |
Sample request to call 'Simple Plot.aut' in inipath\template:
{
'function' => 'get_template_output',
'version' => 1,
'params' => {
'template_name' => 'Simple Plot',
'template_params' => [
{'name' => 'site', 'value' => 'hydsys01'},
{'name' => 'plottype', 'value' => 'SVG'}
]
}
}
Sample return data (with bulk removed to keep size down)
{
"buff_required" : 37188,
"buff_supplied" : 1000000,
"error_num" : 0,
"return" : {
"type" : "SVG",
"encoding " : "BASE64",
"content" :
"PD94bWwgdmVyc2lvbj0iMS4wIiBzdGFuZGFsb25lPSJubyI/Pg0KPCFET0NUWVBFIHN2ZyBQVUJMSUMg
<>
IjkxNyIgeT0iNzExIiBmb250LXNpemU9IjEzIiBmb250LWZhbWlseT0iQXJpYWwiIGZpbGw9IiMwMDAw
}
}
An additional series of Standard Hydstra calls are documented separately under Standard Hydstra Data Publication.
Return Codes
Here is a list of the return codes that various HYDLLP calls may return.
The JSonCall function returns the error number in the error_num attribute, and a text description of the error in the error_msg attribute:
{
"buff_required" : 14200,
"buff_supplied" : 50000,
"error_num" : 121,
"error_msg" : Incorrect version (2) for function get_db_info, (must
be 1)
Italicised codes are only used by legacy functions (see below).
Value |
Name |
Explanation |
0 |
OK |
OK |
10 |
STARTUPFAIL |
Startup failed |
11 |
SHUTDOWNFAIL |
Shutdown failed |
12 |
LOGINFAIL |
Login failed |
20 |
INVALIDSITE |
Invalid station/suffix/variable |
21 |
INVALIDDATE |
Invalid date |
22 |
INVALIDTIME |
Invalid time |
23 |
INVALIDSTARTEND |
Start time > End time |
24 |
INVALIDDATATYPE |
Invalid data type, should be one of Mean, Max, Min, Start, End, First, Last, Tot, MaxMin |
25 |
INVALIDVARTO |
Invalid varto |
30 |
NORATINGTABLE |
No rating table |
31 |
RATINGTABLEOVER |
Value over rating table |
32 |
RATINGTABLEUNDER |
Value under rating table |
33 |
RATINGTABLEERROR |
Error loading rating table |
40 |
ENDOFDATA |
End of data |
41 |
ENDOFVARS |
End of variables |
42 |
ENDOFSTNS |
End of stations |
43 |
INVALIDHYSTNS |
Invalid HYSTNS expression |
44 |
ENDOFSUFFS |
End of suffixes |
45 |
ENDOFBLOCKS |
End of blocks |
50 |
PUTHYDFAIL |
Time series writing failed |
51 |
INVALIDOPENMODE |
Invalid open mode, must be 0..5 |
52 |
INVALIDACTION |
Invalid action, must be 0..6 |
53 |
INVALIDDATATRANS |
Invalid datatrans, must be 1..7 |
54 |
INVALIDACTIONDT |
Invalid action for datatrans |
55 |
INVALIDQUALITY |
Invalid quality, must be 1..254 |
56 |
INVALIDINTERVAL |
Invalid interval, must be YEAR, MONTH, DAY, HOUR, MINUTE or SECOND |
57 |
INVALIDGEOFILTER |
Invalid geo filter |
59 |
TABLECANNOTREAD |
Cannot read table because of an insufficient user level |
60 |
TABLENOTEXIST |
Table does not exist |
61 |
TABLEALREADYOPEN |
A table is already open (TableClose has not been called), havent called close table after last time |
62 |
TABLECANNOTOPEN |
Could not open table (all other problems opening table) |
63 |
TABLENOTOPEN |
Table not open (calling other table apps before opening a table) |
64 |
TABLETOOMANYCOLS |
Too many columns specified |
65 |
TABLEINVALIDCOL |
Invalid column name, field name not in list |
66 |
TABLEBADFORMAT |
Bad format of passed-in data, problems with passed-in values of date/logical etc. |
67 |
TABLEATEOF |
Table is at eof; cannot retrieve data, tried to get data; but eof |
68 |
TABLEERROR |
Unknown error with table access, all other inexplicable errors |
69 |
TABLEINVALIDORDER |
Order name does not exist |
70 |
TIMESERIESFILELOCKED |
The specified time-series file is locked |
80 |
STDHYDINVALIDDATASOURCE |
Invalid datasource |
81 |
STDHYDINVALIDUNITCODE |
Invalid unit code |
82 |
STDHYDINVALIDTRACE |
Invalid trace |
83 |
STDHYDINVALIDSITE |
Invalid site |
84 |
STDHYDINVALIDSITELIST |
Invalid site list |
85 |
STDHYDINVALIDPARAMLIST |
Invalid parameter list |
86 |
STDHYDINVALIDGROUP |
Invalid group |
90 |
KIWISINVALIDTSLIST |
Invalid time-series list |
100 |
INVALIDFUNCNAME |
Invalid function name, function name was not recognised |
101 |
INVALIDHANDLE |
Invalid object handle |
120 |
INVALIDJSONDATA |
Invalid JSON request string |
121 |
UNSUPPORTEDVERSION |
Unsupported function version |
122 |
PARAMETERERROR |
Missing/unsupported parameter(s) |
123 |
INVALIDTABLEKEY |
Invalid table key |
124 |
UNHANDLEDEXCEPTION |
Unhandled exception |
125 |
NODATAINFILE |
No data for specified variable in file |
126 |
NODATAINPERIOD |
No data within specified period |
130 |
TEMPLATENOTFOUND |
Template file not found |
131 |
TEMPLATEBADPARAMS |
Could not load parameters from template file |
132 |
TEMPLATEMISSINGOUTPUT |
Expected output from template application not found |
140 |
TABLEDENIEDDATAPRIV |
Cannot read table because it is denied due to data privacy settings |
200 |
BUFFERTOOSMALL |
Buffer too small |
Exported Legacy Functions
Below is a list of legacy functions exported by HYDLLP.DLL,
expressed in
Please see HYDLL for more detailed information on how to use these entry points. However we strongly recommend that new programs should only use StartupEx, JSonCall, and Shutdown if possible.
VarConvert
Converts a value from one variable to another.
function
VarConvert (
aHandle : integer;
aStation : pChar;
aVarFrom : Double;
aVarTo : Double;
aTime : pChar;
aValue : Double;
aQuality : Integer;
var aOutValue : Double;
var aOutQuality : Integer)
: Integer; stdcall;
GetValue
Retrieves a TS data value or aggregate.
function
GetValue (
aHandle : integer;
aStation : pChar;
aSuffix : pChar;
aVarFrom : Double;
aVarTo : Double;
aStartTime : pChar;
aEndTime : pChar;
var aOutValue : Double;
var aOutQuality : Integer)
: Integer; stdcall;
GetValueEx
Retrieves a TS data value or aggregate, with some additional options.
function
GetValueEx (
aHandle : integer;
aStation : pChar;
aSuffix : pChar;
aVarFrom : Double;
aVarTo : Double;
aStartTime : pChar;
aEndTime : pChar;
aDataType : Integer;
{>} aOutTimeBuf : pChar;
aOutTimeLen : integer;
var aOutValue : Double;
var aOutQuality : Integer)
: Integer; stdcall;
DataType |
Explanation |
0 (Mean) |
Mean (average) value in period |
1 (Maximum) |
Maximum value in period |
2 (Minimum) |
Minimum value in period |
3 (Start) |
Instantaneous value at start of period |
4 (End) |
Instantaneous value at end of period |
5 (First) |
First actual value in period. This may be different to a (possibly) interpolated value at the start of the period |
6 (Last) |
Last actual value in period. This may be different to a (possibly) interpolated value at the end of the period |
7 (Total) |
Total value in period |
8 (MaxMin) * |
Maximum and minimum values in period |
GetValueStr
Retrieves a series of TS values and returns them in a long string.
NB: this form is only for backward compatibility with HYDLL calls, and is inefficient. Please use GetValueStrInit() and GetValueStrMore(), or better yet, JSonCall's get_ts_traces method.
function
GetValueStr (
aHandle : integer;
aStation : pChar;
aSuffix : pChar;
aVarFrom : Double;
aVarTo : Double;
aStartTime : pChar;
aEndTime : pChar;
aDataType : Integer;
aInterval : pChar;
aMultiplier : Integer;
aRelTimes : integer;
{>} aOutDataBuf : pChar;
aOutDataLen : integer;
var aPointCount : Integer)
: Integer; stdcall;
GetValueStrInit
Initiates a retrieval run of TS values, but does not return them.
After a successful call to this one, use GetValueStrMore() to unload the values, buffer by buffer.
function
GetValueStrInit (
aStation : pChar;
aSuffix : pChar;
aVarFrom : Double;
aVarTo : Double;
aStartTime : pChar;
aEndTime : pChar;
aDataType : Integer;
aInterval : pChar;
aMultiplier : Integer;
aRelTimes : integer;
var aPointCount : Integer)
: Integer; stdcall;
GetValueStrMore
Returns a buffer of values retrieved by GetValueStrInit().
You should call this repeatedly until aLoadCount is zero. The larger the supplied buffer, the fewer calls will be required.
function
GetValueStrMore (
aHandle : integer;
{>} aOutDataBuf : pChar;
aOutDataLen : integer;
var aLoadCount : Integer)
: Integer; stdcall;
NextValue
Returns the next value after a call to GetValue().
After calling GetValue() you can call NextValue() as many times as you like, until the time becomes far future.
function
NextValue (
aHandle : integer;
aStation : pChar;
aSuffix : pChar;
aVarFrom : Double;
aVarTo : Double;
{>} aOutTimeBuf : pChar;
aOutTimeLen : integer;
var aOutValue : Double;
var aOutQuality : Integer)
: Integer; stdcall;
NextValueEx
Returns the next value after a call to GetValueEx().
After calling GetValueEx() you can call NextValueEx() as many times as you like, until the time becomes far future.
function
NextValueEx (
aHandle : integer;
aStation : pChar;
aSuffix : pChar;
aVarFrom : Double;
aVarTo : Double;
{>} aOutTimeBuf : pChar;
aOutTimeLen : integer;
var aOutValue : Double;
var aOutQuality : Integer;
var aOutDataTrans : Integer;
{>} aOutCommentBuf: pChar;
aOutCommentLen: Integer)
: Integer; stdcall;
TimeBounds
Returns the period of record for a nominated variable in a nominated TS file. The times are returned as Strtimes (yyyymmddhhiiee) if data is found, but zero if no data is found.
function
TimeBounds (
aHandle : integer;
aStation : pChar;
aSuffix : pChar;
aVarFrom : Double;
{>} aStartTimeBuf: pChar;
aStartTimeLen: integer;
{>} aEndTimeBuf : pChar;
aEndTimeLen : integer)
: Integer; stdcall;
QualitySummary
Creates a multi-line quality summary string for a nominated TS data trace.
function
QualitySummary (
aHandle : integer;
aStation : pChar;
aSuffix : pChar;
aVarFrom : Double;
aStartTime : pChar;
aEndTime : pChar;
{>} aQualSummBuf: pChar;
aQualSummLen: integer)
: Integer; stdcall;
NextVariable
Returns the next variable in a nominated TS file.
HYDLLP detects when you are calling this for the first time (or for the first time with a given site and datasource), and returns the first variable in the nominated file. You may call this repeatedly, until there are no more, in which case the return value is non-zero.
function
NextVariable (
aHandle : integer;
aStation : pChar;
aSuffix : pChar;
var aVariable: Double)
: Integer; stdcall;
NextStation
Returns the next site in a site list expression.
HYDLLP detects when you call this with a new site list expression, so that you can make multiple calls to get each site.
A non-zero return code signifies that there are no more.
function
NextStation (
aHandle : integer;
aHyStns : pChar;
{>} aStationBuf: pChar;
aStationLen: integer)
: Integer; stdcall;
NextSuffix
Returns the next archive or work class TS datasource for a given station.
HYDLLP detects when you call this with a new site, so that you can make multiple calls to get each datasource.
A non-zero return code signifies that there are no more.
function
NextSuffix (
aHandle : integer;
aStation : pChar;
{>} aSuffixBuf: pChar;
aSuffixLen: integer)
: Integer; stdcall;
NextBlock
Returns information about the blocks for a given variable in a TS file.
HYDLLP detects when you call this with a new site / datasource / variable, so that you can make multiple calls to get each block.
A non-zero return code signifies that there are no more.
function
NextBlock (
aHandle : integer;
aStation : pChar;
aSuffix : pChar;
aVariable : Double;
{>} aBlockBuf : pChar;
aBlockLen : integer)
: Integer; stdcall;
ClearTSCache
When reading a file, the data is kept in memory(cached) this is to improve performance when frequently performing operations on the same file. A side effect of this is that should you want to write to the file, you cant gain access to it. ClearTSCache erases the cache and relinquishes any locks on files that it had.
ClearTSCache is used when reading and writing in quick succession to time series files.
function ClearTSCache (
aHandle : integer)
: Integer; stdcall;
ClearDBCache
When reading a file, the data is kept in memory(cached) this is to improve performance when frequently performing operations on the same file. A side effect of this is that should you want to write to the file, you cant gain access to it. ClearDBCache erases the cache and relinquishes any locks on files that it had.
ClearDBCache is used when reading and writing is being held up by file access on currently unused databases.
The aDBList param may take several values:
{blank} |
All user-opened tables, plus system lookup tables only |
+ |
All user-opened tables, plus all system tables |
table1,table2 |
A comma separated list of tables |
function ClearDBCache (
aHandle : integer;
aDBList : string)
: Integer; stdcall;
DecodeError
If you get an unexpected non-zero return code, you can learn more about the problem using DecodeError().
function
DecodeError (
aErrorNum : Integer;
{>} aErrorStrBuf : pChar;
aErrorStrLen : integer)
: integer; stdcall;
StrToTime
Converts a reltime to a time string format (yyyymmddhhiiee).
function
StrToTime (
aTimeStr : pChar;
var aRelTime : Double)
: integer; stdcall;
TimeToStr
Converts a time string format to a reltime.
function
TimeToStr (
aTime : Double;
{>} aStrBuf : pChar;
aStrLen : integer)
: integer; stdcall;
HyConfig
Returns the value of a given HYCONFIG keyword setting.
function
HyConfig (
aKeyword : pChar;
{>} aValueBuf: pChar;
aValueLen: integer)
: integer; stdcall;
Environment
Returns the value of an environment variable.
NB: this call respects the Hydstra convention of /e= command line switches, and thus may return a different value to that in the actual environment. However, the value it returns will be the same that any regular Hydstra app would use under the same circumstances.
function
Environment (
aKeyword : pChar;
{>} aValueBuf: pChar;
aValueLen: integer)
: integer; stdcall;
LLtoEN
Converts Lat/Long to Easting/Northing
function
LLToEN (
aLatitude : Double;
aLongitude : Double;
aDatum : pChar;
var aEasting : Double;
var aNorthing : Double;
var aZone : Integer)
: integer; stdcall;
ENToLL
Converts Easting/Northing to Lat/Long
function
ENToLL (
aEasting : Double;
aNorthing : Double;
aZone : Integer;
aDatum : pChar;
var aLatitude : Double;
var aLongitude : Double)
: integer; stdcall;
WriteInit
Sets up for writing TS values to a file.
function
WriteInit (
aHandle : integer;
aOpenMode : Integer;
aAction : Integer;
aMaxJoin : Double;
aMaxTruncate : Double)
: Integer; stdcall;
OpenMode |
Explanation |
0 (Erase) |
The old file is erased, and the new file is written. |
1 (Abort) |
The program aborts. |
2 (Search) |
The program searches for the next 'unused' datasource - it increments the datasource until it either goes past 'Z', or finds a filename that does not exist. |
3 (Append) |
The file is opened, but not erased, and the new data is written to the end of it. |
4 (Increment) |
The file is opened, not erased, and the new data is written to the end of an existing block in the file, if an appropriate block can be found. An appropriate block is one that has the same variable and datatrans, and has its end time within a certain number of minutes of the first data value that is being written. That number of minutes is the MaxJoin parameter. If the presented data is earlier than the end of this block, it is IGNORED! |
5 (Overlay) |
Similar to increment, however if the data is earlier than the existing data, the existing data is TRUNCATED. The maximum amount of data truncated is the MaxTruncate parameter. |
Action determines what to do with points that have the same time.
Action |
Explanation |
0 (Hold) |
Holds the value where it is until the instant before the next change. Generates a "square wave" type of trace. |
1 (Add) |
Adds values that occur at the same time. This would be a good idea for event rainfall. |
2 (Put) |
Standard Put. Discards equivalent points. |
3 (First) |
Takes the first value of concurrent samples. This is actually the same as Put. |
4 (Last) |
Takes the last value of concurrent samples. |
5 (Max) |
Takes the maximum value of concurrent samples. |
6 (Min) |
Takes the minimum value of concurrent samples. |
WriteValue
Writes a TS value to a file.
function WriteValue (
aHandle : integer;
aStation : pChar;
{>} aSuffixBuf : pChar;
aSuffixLen : integer;
aVariable : Double;
aDataTrans : Integer;
aTime : pChar;
aValue : Double;
aQuality : Integer)
: Integer; stdcall;
WriteBlock
Causes a block break to be created with writing TS values to a file.
function WriteBlock(aHandle : integer) : Integer; stdcall;
WriteEnd
Finishes off a run of writing TS values to a file.
function WriteEnd(aHandle : integer) : Integer; stdcall;
WriteComment
Writes a comment to a TS file (against most recently-written point)
function
WriteComment (
aHandle : integer;
aComment : pChar)
: integer; stdcall;
WriteHyFiler
Registers a HYFILER action against a TS file that is being written.
The action will be executed when the file is closed.
function
WriteHyFiler (
aHandle : integer;
aOnOpen : pChar;
aOnClose: pChar)
: integer; stdcall;
WritePopValue
Discards the most recently-written TS point.
function WritePopValue(aHandle : integer) : integer; stdcall;
DecMsg
Decodes a Hydstra message ID. Used for the translatability / localisation feature of Hydstra.
function
DecMsg (
aMessID : pChar;
aSubstParams : pChar;
{>} aOutStrBuf : pChar;
aOutStrLen : integer)
: integer; stdcall;
aMessID is the MSGID from the MESSAGES table.
aSubstParams is a list of comma separated strings that replace the %1, %2 and so on in the returned message text.
use strict;
require 'hydlib.pl';
use HydDLLp;
main:{
my $dll=HydDllp->New();
my $message=$dll->DecMsg("APP.HYCREATE.AUTOCOMLONG","first
param","second param","third param");
print($message);
}
In the above Perl example code the message "APP.HYCREATE.AUTOCOMLONG" gets translated into "Created by HYCREATE. %1 %2 from %3" and then the %# are replaced with the strings passed to aSubstParams resulting in the string "Created by HYCREATE. first param second param from third param".
TableOpen
Opens a database table for retrieval.
function
TableOpen (
aHandle : integer;
aTableName : pChar)
: integer; stdcall;
TableFilter
Applies a filter to an open database table.
function
TableFilter (
aHandle : integer;
aFieldList : pChar;
aValueList : pChar)
: integer; stdcall;
TableOrder
Applies a named order to an open database table.
function
TableOrder (
aHandle : integer;
aOrderName : pChar)
: integer; stdcall;
TableEOF
Checks to see if an opened database table is sitting at the end of rows.
The aEofInt parameter will be true (non-zero) if the table is at EOF, and false (zero) if not.
function
TableEOF (
aHandle : integer;
var aEofInt : integer)
: integer; stdcall;
Return Code |
Explanation |
0 |
Not at EOF |
Other |
At EOF |
TableValue
Rerturns the string representation of a field in the current database table.
function
TableValue (
aHandle : integer;
aFieldName : pChar;
{>} aValueBuf : pChar;
aValueLen : integer)
: integer; stdcall;
TableNext
Moves the current database table to the next row.
function TableNext(aHandle : integer): integer; stdcall;
TableClose
Closes the current database table.
function TableClose(aHandle : integer) : integer; stdcall;
ADOConnection
Returns the
function
ADOConnection (
aTableSpec : pChar;
{>} aConnectionStrBuf: pChar;
aConnectionStrLen: integer;
{>} aTableStrBuf : pChar;
aTableStrLen : integer)
: integer; stdcall;
Using HYDDLLP from Perl
Updating Perl programs is usually simple. In your Perl you will find statements of the form:
use HydDll;
...
my $dll=HydDll->new()
All you need to do is add 'p' to these two locations (and any other HydDLL->new calls)
use HydDllp;
...
my $dll=HydDllp->new()
All delivered Perl programs under \HYD\SYS have already been amended to use HYDLLP. The only programs you might need to address will be in INIPATH.
If you are calling HYDLL from other languages it is somewhat more challenging to use HYDLLP as the calling sequences, types of parameters etc have changed. We provide an example spreadsheet HYDLLP Excel.JSON Example.Xlsm in \hyd\sys\misc\examples, as well as examples in other languages.
HYDLLP Calling Conventions from Other Languages
Calling convention
All functions in HYDLLP use the stdcall calling convention.
Return values
Every function returns a 32-bit integer as its return value.
Zero means the call was successful.
Some calls, particularly those that are intended to be called in a loop, use a non-zero return code to mean no more.
In most other cases, non-zero means that a problem was encountered. Further information can be gained by immediately through the error_msg attribute or by calling DecodeError().
The aHandle parameter
The first call to HYDLLP should be StartUp() or StartUpEx(). These calls return to you (via an out parameter) a value valled aHandle. Many subsequent calls require that you pass in this handle as the first parameter. This allows HYDLLP to service calls coming from more than one user, or even parallel calls coming from the same user, but referring to different items (ie, tables, time series files). The aHandle parameter allows HYDLLP to keep the data items for each caller separate.
Time values
When a time value is stored in a Double-precision float, it uses the Hydstra reltime encoding, meaning the number of days since midnight on 01/01/1601.
If a time is stored in a string, it uses the Hydstra string time convention:
yyyymmddhhiiee
There are calls that can convert between the two if required.
pChar parameters
Parameters of type pChar are a pointer to an ascii character buffer (of 8 bit ANSI characters), and are used for specifying string values to a call ([in] parameters) and to return string information to the caller ([out] parameters).
In the list below, [in] parameters are unadorned, while [out] parameters have a {>} comment before the parameter name.
[Out] pChar parameters also have an associated xxxLen parameter following them, in which the caller declares the maximum length of the character buffer.
Integer parameters
Parameters of type Integer are standard 32-bit signed integers.
For [in] parameters, the declaration is unadorned.
For [out] parameters, the
Double parameters
Parameters of type Double are standard IEEE double precision floats.
For [in] parameters, the declaration is unadorned.
For [out] parameters, the
Logical/Boolean values
Boolean parameters and return values are specified as true or false.
Calling HYDLLP from external applications
If you develop applications in VB, C#,
Paths
HYDLLP needs to be run "in situ" - that is, in the hyd\sys\run folder (under your choice of "root location"). You can't copy it to a Windows directory, which you sometimes have to do with other DLLs.
Paths (again)
HYDLLP needs to access some other libraries (DLL and BPL) which live in RUNPATH.
Normally, if the application also lives in RUNPATH, they are found automatically, as they are in the "same" folder as the app.
But... when the HYDLL{x} is invoked from another app, somewhere else, that doesn't work - both "folder of current app" and "current working directory" are <> runpath!!!
According to the MSDN website, when Windows is asked to load a DLL, it searches through the following list:
1. The directory from which the application loaded.
2. The current directory.
3. The system directory. Use the GetSystemDirectory function to get the path of this directory.
4. The 16-bit system directory. There is no function that obtains the path of this directory, but it is searched.
5. The Windows directory. Use the GetWindowsDirectory function to get the path of this directory.
6. The directories that are listed in the PATH environment variable. Note that this does not include the per-application path specified by the App Paths registry key. The App Paths key is not used when computing the DLL search path.
And, if it can't find it, it will probably fall over in an uncontrollable (and uncatchable) manner.
Solution: call SetCurrentDirectory() to the known RUNPATH just before loading the COM object (and calling StartUpEx())
Paths (yet again)
When a Hydstra processes starts up (and loads HYCONFIG.INI) it tries to find out where all the Hydstra paths are.
Quote often, folk will have a sparse [Path Prefixes] section in HYCONFIG.INI, since the default behaviour is "find out the Hydstra root, then use the standard path underneath that".
As in the previous point, this means using the location of the running application - which for Hydstra apps means RUNPATH, but when an external DLL is involved, the location could be elsewhere, and the defaulting algorithm would turn out all wrong.
Solution: be more specific in your hyconfig.ini file:
[Path Prefixes]
\HYD\ = h:\hydstra\prod
DLLs and IDEs
According to Microsoft, once a COM interface is published, it is immutable.
According to Hydstra, things are a little more flexible. Although we try not to change individual calls, the server itself goes through lots of changes from release to release.
It is possible that some IDEs, when importing a COM object, will store some of that information, and compile it into the app.
If is possible that when a new version of the DLL is registered, the IDE will be out of whack.
Solution: remove/uninstall the COM object from the project, then reimport/install the new one