HYDLLP – Flat DLL Interface to Hydstra

Function

HYDLLP.DLL is a 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 HYDLL, it requires no COM registration and no special Windows security in order to use it.

The initial implementation of HYDLLP provides an identical set of calls to an 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\perl\examples.

If you decide to rework your code or develop new code, please consider using the JSonCall series of calls, as this is the preferred way forward.

Functions available in HYDLLP

All functions available in HYDLL are also available in HYDLLP. Users with legacy programs that used HYDLL in the past can be assured that the equivalent functions are available in HYDLLP with the same name, although the form of the parameters may change.

Users developing new applications from scratch are encouraged to develop their applications using only the JSonCall sub-functions.

A series of calls dedicated to supporting Standard Hydstra are documented separately under Standard Hydstra Data Publication.

Developing REST web service URLs

All functions detailed here may be used for 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 a 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 a connection string and table string for a Hydstra table.

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

get_hybatch_sections

return HYBATCH output details

Misc

multi_call

execute multiple functions with one call

Misc

write_log

write HYDLOG entry

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_trace

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

 

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

http://www.json.org/object.gif

An array is an ordered collection of values. An array begins with [ (left bracket) and ends with ] (right bracket). Values are separated by , (comma).

http://www.json.org/array.gif

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.

http://www.json.org/value.gif

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.

http://www.json.org/string.gif

A number is very much like a C or Java number, except that the octal and hexadecimal formats are not used.

http://www.json.org/number.gif

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

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.

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.

 

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

year

multiplier

interval multiplier

integer

5

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

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)

1

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)

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 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 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'  => 1,
  '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"},
        "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"},
         "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

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_join

Sets the maximum gap allowed between points in minutes.

 

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

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_join(maxgap), 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]…]

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

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.

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

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 o4 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 used (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. (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" : 889,
   "buff_supplied" : 1000000,
   "signature" : "760DBFD2E6C629727081080658E08FA7",
   "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 databases",
            "error_num" : 33
         },{
            "shifts" : True",
            "table_to" : " 140.00",
            "varfrom" : " 100.00",
            "name" : "",
            "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
               }
            ],
            "release" : "10",
            "varto" : " 140.00",
            "interval" : "0.9",
            "stage_high" : "8.0",
            "datetime" : "19930501000000",
            "site" : "410734",
            "table_from" : " 100.00",
            "stage_low" : "0.0"
         }
      ]
   }
}

 

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 can’t 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

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

 

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

 

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 can’t 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 doesn’t 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 but must be specified if title_height is specified, defaults to an empty string)

 

Lake Fido Storage

title_height

Font size of the title (optional but must be specified if title is specified, defaults to 0)

 

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

0 (false) 1 (true)

0

show_points

Displays a circle around data points

0 (false) 1 (true)

0

filled

Fills underneath the graph

0 (false) 1 (true)

1

invert

Changes the direction of the Y-Axis

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 don’t 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'           => 0,
        'show_points'          => 0,
        '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 doesn’t 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 doesn’t 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"
         }   
      ]
   }
}

 

 

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), haven’t 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 timeseries 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 timeseries 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

127

TABLEACCESSDENIED

Access to one or more tables is denied

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

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 can’t gain access to it. ClearTSCache erases the cache and relinquishes any locks on files that it had.

ClearTSCache is used when reading and writing in quick succession to time series files.

function ClearTSCache (

               aHandle  : integer)

                        : Integer; stdcall;

ClearDBCache

When reading a file, the data is kept in memory(cached) this is to improve performance when frequently performing operations on the same file. A side effect of this is that should you want to write to the file, you can’t 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;

DecodeMessage

Decodes a Hydstra message ID. Used for the translatability / localisation feature of Hydstra.

function DecodeMessage (
               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\perl\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


See Also

HYDLLPX, HYDLLP_UI, HYDLL, HYDDE, Web Services Overview