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 Delphi code will also handle 'yes' and 'no, or 'true' and 'false'. More specifically, it looks at the first character of the translated true/false message, so technically you could use 'S' and 'N' in Italian, though that would be very unwise as a change of language setting would invalidate the code.

Summary of JSON Functions

Search below for complete documentation of each function.

Domain	Function	Description
Time-series	get_site_list	Evaluate a HYSTNS site list expression and return a list of sites
Time-series	get_ts_traces	Retrieves one or more time series traces
Time-series	write_ts_traces	Writes one or more time series traces
Time-series	hyfiler_command	Run a hyfiler command
Time-series	get_datasources_by_site	enumerate datasources
Time-series	get_sites_by_datasource	enumerate sites
Time-series	get_variable_list	return list of variables for a TS file
Time-series	get_subvar_details	return functional and descriptive details of a subvar
Time-series	get_ts_blockinfo	return info about TS blocks
Time-series	get_latest_ts_values	return last time-series values
Time-series	get_varcon	convert data with variable
Time-series	get_effective_rating	returns an array of time, value pairs that represent the rating table.
Time-series	get_site_geojson	return GeoJSON and other field data from the site table for the provided site list
Time-series	clear_ts_cache	clears time-series files from the in memory cache
Database	get_db_info	return table data with simple or complex filters or geo filters
Database	get_db_areas	return list of database work areas
Database	get_decoded_value	decode database code or lookup
Database	get_ado_connection	returns an ADO connection string and table string for a Hydstra table.
Database	get_odbc_connection	returns an ODBC connection string and table string for a Hydstra table
Database	write_db_info	write records to a database in a work area
Database	table_doc_location	return location of documents for a record
Database	table_doc_record_key	return table and key from document location
Database	get_table_documents	return documents associated with tables
Database	get_cross_sections	return cross section details
Database	get_groups	return list of groups that site(s) are a member of
Database	clear_db_cache	clears database tables from the in memory cache
Misc	set_real_encoding	controls how real numbers are encoded in JSON
Misc	get_hybatch_sections	return HYBATCH output details
Misc	multi_call	execute multiple functions with one call
Misc	write_log	write HYDLOG entry
Misc	get_recalculation_periods	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	get_hybatch_env	return HYBATCH environment settings, as would be output by the HYBATCHE program
Misc	authenticate_user	check whether a user ID and password are valid according to the PASSWD table
Plots	get_widget	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	get_template_list	Returns a list of all templated output applications, and their available parameters
Templated output	get_template_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 Delphi syntax.

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 :.

get_ts_traces

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 or 0	19750501000000
end_time	data period end datetime YYYYMMDDhhmmss.	YYYYMMDDHHIIEE or 0	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 or not(100)
interval	data interpolation interval	year, month, day, hour, minute, second, period, default	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, point, partialtot, cum. Note that for max, min, and maxmin types the times returned are the actual time of the max or min. Note that Hydstra does not have a time of 24:00 so a max at time 24:00 will be shown as 00:00 on the following day.	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
}
]
}
}

write_ts_traces

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
}

hyfiler_command

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"
}
}

get_site_list

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"]
}
}

get_db_info

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.

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: [latitude, longitude, radius in degrees] Rectangle takes an array of arrays: [[top_left_latitude,top_left_longitude], [bottom_right_lat,bottom_right_long]] Region takes an array of arrays: [[latitude1,longitude1], [latitude2,longitude2], [latitude3,longitude3]] (more information on geo_filter below)	Circle	'circle' => ['-35','149',1]
		Rectangle	'rectangle' => [['-35','148'],['-36','149']]
		region	'region' => [['-35','148'],['-36','149'], ['-36','148']]
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', 'value'=>'1'
NE	not equals	Yes	Yes	'fieldname'=>'region, 'operator'=>'NE', 'value'=>'1'
GT	greater than	Yes	Yes	'fieldname'=>'region, 'operator'=>'GT', 'value'=>'1'
LT	less than	Yes	Yes	'fieldname'=>'region, 'operator'=>'LT', 'value'=>'1'
GE	greater than or equal	Yes	Yes	'fieldname'=>'region, 'operator'=>'GFE', 'value'=>'1'
LE	less than or equal	Yes	Yes	'fieldname'=>'region, 'operator'=>'LE', 'value'=>'1'
CONT	contains	Yes	Yes	'fieldname'=>'stname', 'operator'=>'CONT', 'value'=>'river'
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', value=>'HYD%'
NOTCONT	does not contain	Yes	No	'fieldname'=>'stname', 'operator'=>'NOTCONT', 'value'=>'creek'
NOTCONT	does not contain	Yes	No	'fieldname'=>'stname', 'operator'=>'NOTCONT', 'value'=>'creek'
NOTIN	not in comma delimited list	Yes	No	'fieldname'=>'owner', 'operator'=>'NOTIN', 'value'=>'DWR,SCA,NSW'

* 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.

write_db_info

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: (a) if you have specified a field_list parameter, each row must be an array or values, which will be written to the corresponding field in fileld_list. This is the fastest and most memory-efficient format. (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. Basically if you are writing data in multiple chunks the first call should have erase=>1 and all subsequent calls should have erase=>0.
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. If you are running under SQL Server, the bulk dump file is in SQL Server bulk dump format, and the script will include a call to BCP.EXE, and relies on your HYSQLLOAD.INI file for various database-related settings. If you are running under the FoxPro format database, the bulk dump file is a Hydstra CSV file, and the import script includes a call to HYDBUTIL APPEND.

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"

}

get_db_areas

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"
}]
}
}
}

get_latest_ts_values

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. REMOVED IN VERSION 2	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}
]
}
}

get_ts_blockinfo

Retrieves a list of sites having data for one or more specified data sources

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
}

get_sites_by_datasource

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"]}
]
}
}

get_varcon

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_effective_rating

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_site_geojson

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"
}
}

clear_ts_cache

(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
}

get_datasources_by_site

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"]}
]
}
}

get_variable_list

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. NB: one feature of variable filters is disabled in this call: if you specify a single variable, and omit the decimals, it will be treated as .00, and *not* all matching subvariables.		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"}
]
}
]
}
}

get_ado_connection

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).

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).

get_subvar_details

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\\"
}
}

table_doc_record_key

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"]
}
}

get_table_documents

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"
}
]
}
}
]
}

get_cross_sections

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" : ""
}
]
}
}
]
}}

get_groups

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"
}
]
}

set_real_encoding

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

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
}

clear_db_cache

(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"
}
}
]
}}

multi_call

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_log

Write a log entry to HYDLOG.TXT or a nominated HYDEBUG file

parameter	description	options	example
log_type	The type of log	HYDLOG, HYDEBUG
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)		Lake Fido Storage
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.		Lake Fido Storage
title_2	A second title displayed within but at the top of the storage (optional) (%VALUE% macro will be replaced with the actual value)		%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% macro will be replaced with the actual value)		%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"
}
]
}
}

get_recalculation_periods

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"
}
],
}
]
}
}

get_hybatch_env

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",
<>
}
}

authenticate_user

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
}

get_template_list

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" }
]
}

get_template_output

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 Delphi syntax. The main reason for using these routines is if you are upgrading an existing program from HYDLL to HYDLLP.

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

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 ADO connection string required to open a nominated database table using ADO directly (ie, bypassing TableOpen() etc. For a Foxpro connection this will be automatically constructed. For a SQL Server or other SQL database this will return the value from CONNECT.INI of the ExternalConnectStr keyword.

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 Delphi syntax uses the var reserved word. This indicates that the caller passes a pointer to the integer.

Double parameters

Parameters of type Double are standard IEEE double precision floats.

For [in] parameters, the declaration is unadorned.

For [out] parameters, the Delphi syntax uses the var reserved word. This indicates that the caller passes a pointer to the double.

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#, Delphi or C++ etc, there are a few factors to bear in mind when calling HYDLLP.

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