HYDLLP – Flat DLL Interface to Hydstra

Function

HYDLLP.DLL is a Windows DLL (Dynamic Link Library) which provides access to various aspects of Hydstra, including database information and time-series data.

HYDLLP is a simple Windows 32 bit DLL that can be linked into a program written in any language at run time. Unlike the earlier HYDLL, it requires no COM registration and no special Windows security in order to use it.

Although HYDLLP supports some other call formats for backwards compatibility reasons,  all new users of the DLL should interact with it only via the JSonCall interface.

A further benefit of the JSonCall interface is that many Hydstra clients publish data on the web using web services, and the Hydstra Web Services interface simply wraps the JSonCall interface in a web skin.

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

Under certain tightly controlled situations the output from almost any Hydstra program can be made available via a HYDLLP call to DLL users inside and via web services outside the firewall. Read up on HYDLLP Templated Output for more information.

Upgrading from legacy HYDLL.DLL

The implementation of HYDLLP provides an identical set of calls to the earlier technology HYDLL. For Perl users the transition from using HYDLL to HYDLLP is almost trivial, since we have encapsulated the different calling mechanisms in HYDLLP.PM. However if you wish to convert from HYDLL to HYDLLP using other languages like VBA, C# and Delphi then the process will require significant changes, and you should study the examples distributed in \hyd\sys\misc\examples.

Data Privacy

The get_db_info, get_ts_traces and get_ts_blockinfo calls, when made available over the web, are able to publish potentially sensitive personal data about your staff and clients. You can control this with the DATAPRIV.INI, which is administered by program HYDATAPRIV. This lets you deny access to specified tables, columns, rows and timeseries data comments and user info. HYDLLP only consults DATAPRIV.INI when it detects that it is running under the Hydstra/WEB framework.  Inside the firewall normal Hydstra security rules apply.

Developing REST web service URLs

All functions detailed here may be also used in web service calls except:
clear_ts_cache
clear_db_cache
write_ts_traces
hyfiler_command

IMPORTANT
When developing web service URLs, be aware that the Perl examples listed below must be translated to native JSON as follows:

·         remove all line breaks (the whole JSON data structure request must be on the same line)

·         remove unnecessary spaces between parameters (but not any vital spaces within parameter values)

·         replace single quotes with double quotes

·         replace all instances of the Perl reference operator '=>' with ': '

For example

{
  'function' => 'get_site_list',
  'version' => 1,
  'params' => {
    'site_list' => 'TSFILES(DSOURCES(ARCHIVE))'
  }
}

becomes

{"function":"get_site_list","version":1,"params":{"site_list":"TSFILES(DSOURCES(ARCHIVE))"}}

 

HYDLLP JSON Calling Conventions

When calling HYDLLP using the JSonCall call we use the following conventions for passing in and returning parameters:

      Dates take the form yyyymmddhhiiee, e.g. 19741225120000

      Times take the form, hhii or hhii.ee, e.g. 1245 or 1245.01 for one second later.

      Booleans take the form 1 (true) or 0 (false). However the underlying Delphi code will also handle 'yes' and 'no, or 'true' and 'false'. More specifically, it looks at the first character of the translated true/false message, so technically you could use 'S' and 'N' in Italian, though that would be very unwise as a change of language setting would invalidate the code.

Summary of JSON Functions

Search below for complete documentation of each function.

Domain

Function

Description

Time-series

get_site_list

Evaluate a HYSTNS site list expression and return a list of sites

Time-series

get_ts_traces

Retrieves one or more time series traces

Time-series

write_ts_traces

Writes one or more time series traces

Time-series

hyfiler_command

Run a hyfiler command

Time-series

get_datasources_by_site

enumerate datasources

Time-series

get_sites_by_datasource

enumerate sites

Time-series

get_variable_list

return list of variables for a TS file

Time-series

get_subvar_details

return functional and descriptive details of a subvar

Time-series

get_ts_blockinfo

return info about TS blocks

Time-series

get_latest_ts_values

return last time-series values

Time-series

get_varcon

convert data with variable

Time-series

get_effective_rating

returns an array of time, value pairs that represent the rating table.

Time-series

get_site_geojson

return GeoJSON and other field data from the site table for the provided site list

Time-series

clear_ts_cache

clears time-series files from the in memory cache

Database

get_db_info

return table data with simple or complex filters or geo filters

Database

get_db_areas

return list of database work areas

Database

get_decoded_value

decode database code or lookup

Database

get_ado_connection

returns an ADO connection string and table string for a Hydstra table.

Database

get_odbc_connection

returns an ODBC connection string and table string for a Hydstra table

Database

write_db_info

write records to a database in a work area

Database

table_doc_location

return location of documents for a record

Database

table_doc_record_key

return table and key from document location

Database

get_table_documents

return documents associated with tables

Database

get_cross_sections

return cross section details

Database

get_groups

return list of groups that site(s) are a member of

Database

clear_db_cache

clears database tables from the in memory cache

Misc

set_real_encoding

controls how real numbers are encoded in JSON

Misc

get_hybatch_sections

return HYBATCH output details

Misc

multi_call

execute multiple functions with one call

Misc

write_log

write HYDLOG entry

Misc

get_recalculation_periods

return a list of periods that have been influenced by modifications to various types of data (time series, rating tables, time-based tables etc).

Misc

get_hybatch_env

return HYBATCH environment settings, as would be output by the HYBATCHE program

Misc

authenticate_user

check whether a user ID and password are valid according to the PASSWD table

Plots

get_widget

return small plot widgets

Standard Hydstra

get_std_unit_details

return information about standard units

Standard Hydstra

get_std_parameter_list

return all the parameters you serve and the units they are in

Standard Hydstra

get_std_site_list

return list of sites that have a parameter or lie in a region

Standard Hydstra

get_std_trace_list

return list of traces for a site list

Standard Hydstra

get_std_trace_periods

return periods for specified sites

Standard Hydstra

get_std_ts_traces

return time-series data

Standard Hydstra

get_std_site_geojson

return GeoJSON and other field data from the site table for the provided site list

Standard Hydstra

get_std_group_list

Return all the named site list groups specified in the SiteList section of the HYSTANDARD_CONF.ini

Standard Hydstra

get_std_datasource_list

Return a list of all the datasources served and their descriptions.

Standard Hydstra

get_std_latest_ts_values

Return a list of the latest time-series points for a site list. By default, it looks back to the most recent data point. All datetimes are in UTC 0.

Standard Hydstra

get_kiwis_ts_list

Return all the time-series traces and periods of record associated with this site list. All datetimes are in UTC 0.

Templated output

get_template_list

Returns a list of all templated output applications, and their available parameters

Templated output

get_template_output

Runs a templated output application and returns its output

 

Introduction to JSON

The preferred way of using HYDLLP is to use the JSonCall interface. JSON (JavaScript Object Notation) is as methodology for encoding complex objects into a character string. You should visit www.json.org for information on JSON, which you will need to have in order to build parameter strings and parse return objects from the JSonCall entry point in HYDLLP.

JSON (JavaScript Object Notation) is a lightweight data-interchange format. It is easy for humans to read and write. It is easy for machines to parse and generate. It is based on a subset of the JavaScript Programming Language, Standard ECMA-262 3rd Edition - December 1999. JSON is a text format that is completely language independent but uses conventions that are familiar to programmers of the C-family of languages, including C, C++, C#, Java, JavaScript, Perl, Python, and many others. These properties make JSON an ideal data-interchange language.

JSON is built on two structures:

A collection of name/value pairs. In various languages, this is realized as an object, record, struct, dictionary, hash table, keyed list, or associative array.

An ordered list of values. In most languages, this is realized as an array, vector, list, or sequence.

These are universal data structures. Virtually all modern programming languages support them in one form or another. It makes sense that a data format that is interchangable with programming languages also be based on these structures.

In JSON, they take on these forms:

An object is an unordered set of name/value pairs. An object begins with { (left brace) and ends with } (right brace). Each name is followed by : (colon) and the name/value pairs are separated by , (comma).

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

Using JSonCall from Python

As for Perl, we also provide a wrapper code for Python programmers in the hydllp.py module, call the HyDllP class. This class has a .jsoncall() method which allows you to pass in and receive back native Python structures (dicts and lists). The transcoding between Python dicts and JSON is handled inside the module and you donlt need to worry about it.

HyDllP.jsoncall() checks the return from a DLL call and if the buffer was too small on the initial call it automatically enlarges the buffer to a suitable size and runs the request again. While it is advisable to try and get the buffer size right first time, this at least means your program works even if you guess wrong. Note that there is also a significant overhead in specifying a ridiculously large buffer like 1,000,000 so it’s a balancing act. The default buffer size is 2000 bytes. Note also that the DLL stores your response when the buffer size is too small, this response will get returned when HyDllP.jsoncall() tries again with a bigger buffer.

The following program should give you some ideas on how to use this class in Python:

import logging
import json

import hydlog
import hydlib
import hydllp

# get Hydstra standard logger
logger = logging.getLogger(hydlog.HYDSTRA_LOGGER)

_hydebug = hydlib.hydebug()

with hydlib.file_open("REPORT", hydlib.hyconfig("TEMPPATH") + "junk", "w") as hrep, hydllp.HyDllP() as dll:

    def dotest(testname, request, bufflen=2000):
        logger.info(f"Testing HYDLLP JSonCall with {testname} --------------------------------------------------------------", tag="FILE.REPORT")
        logger.info("JSON request: " + json.dumps(request, indent=4), tag="FILE.REPORT")

        if dll.jsoncall(request, bufflen):
            logger.info("HYDLLP return: " + json.dumps(dll.result, indent=4), tag="FILE.REPORT")
        else:
            logger.info('Error '+str(dll.result['error_num'])+': '+dll.result['error_msg'], tag="FILE.REPORT")
        logger.info('', tag="FILE.REPORT")


    dotest('get_site_list', {
        'function' : 'get_site_list',
        'version'  : 1,
        'params'   : {'site_list': 'TSFILES(DSOURCES(tscARCHIVE))'}
    })

    dotest('get_db_info', {
        'function' : 'get_db_info',
        'version'  : 2,
        'params'   : {
            'table_name'  : 'bench',
            'return_type' : 'array',
            'decodes'     : 1,
            'field_list'  : ['bdate', 'bench', 'elev', 'rlgd', 'method'],
            'filter_values': {
                'station' : 'HYDSYS01'
        }
      }
    })

    dotest('get_datasources_by_site', {
        'function' : 'get_datasources_by_site',
        'version'  : 1,
        'params'   : {
            'site_list' : "HYDSYS01,HYDSYS02,HYDSYS03"
        }
    })

    dotest('get_sites_by_datasource',{
        'function' : 'get_sites_by_datasource',
        'version'  : 1,
        'params'   : {
            'datasources': ["A","B"]
        }
    })

    dotest('get_ts_traces', {
        'function' : 'get_ts_traces',
        'version'  : 1,
        'params'   : {
            'site_list'   : 'HYDSYS01,HYDSYS02',
            'datasource'  : 'A',
            'varfrom'     : '100.00',
            'varto'       : '100.00',
            'start_time'  : '19750801000000',
            'end_time'    : '19750805000000',
            'data_type'   : 'mean',
            'interval'    : 'day',
            'multiplier'  : '1'
        }
    },1500)

    dotest('get_variable_list', {
        'function' : 'get_variable_list',
        'version'  : 1,
        'params'   : {
            'site_list'  : "HYDSYS01,HYDSYS02",
            'datasource' : "A"
        }
    },5000)

    dotest('test_error_return',{
        'function' : 'get_ts_traces',
        'version' : 1,
        'params' : {
            'site_list'   : 'HYDSYS01,HYDSYS02',
            'datasource'  : 'X',
            'varfrom'     : '100.00',
            'varto'       : '100.00',
            'start_time'  : '19750801000000',
            'end_time'    : '19750901000000',
            'data_type'   : 'mean',
            'interval'    : 'day',
            'multiplier'  : '1'
        }
    },5000)

    dotest('get_latest_ts_values',{
        'function' : 'get_latest_ts_values',
        'version' : 1,
        'params' : {
            'site_list' : 'hydsys01,hydsys02',
            'datasource' :'A',
            'trace_list' : [
                {'varfrom':'100.00','varto':'100','lookback':'60'},
                {'varfrom':'10.00','varto':'10','now':'19910524050000'},
                {'varfrom':'100.00','varto':'100','anyqual':1},
                {'varfrom':'10.00','varto':'10','accum_period':'60'},
            ]
        }
    },5000)

HYDLL Caching and Open Files

In order to improve efficiency HYDLLP keeps a cache of open time-series files and open database tables, so that it doesn't have to keep re-opening time-series files and re-establishing table connections. Mostly this is a good thing, but in a busy server environment, or in the case where a long running process uses DLL, the result can be that time-series files and tables can be held open for long periods, which sometimes interferes with other processes such as incoming telemetry through SVRIMP.

If you find yourself in a program loop operating site by site, where you open some TS files for the site, process some data, and then move on to the next site, we suggest you call ClearTSCache at the end of the loop to release the TS file. Likewise if your program reads some database records at the start, and never again, call ClearDBCache once you are done with database methods.

Encoding of real values in JSON

When JSonCall() was introduced in 2010 (v10.03), we decided to encode all “real” numbers (numbers with decimals) as strings. We did this to avoid “scientific notation” (eg 1E-5), which we thought Perl couldn’t handle (though it actually can). But since the primary use case was Perl, and Perl is not a strongly-typed language, it didn’t matter. Perl was quite capable of taking the string values returned in JSON, and interpreting them as real values.

Now that we are also support Python, which is a strongly-typed language, we need the ability to return real numbers encoded in JSON as proper “float” format values.

To avoid causing any unintended side-effects on the Perl world, if you take no action, the feature will not be activated – HYDLLP will behave as it always has – encoding real values as strings.

To allow maximum flexibility across use cases, you can enable the feature in two ways:

Across entire “session”

The JSonCall() function set_real_encoding. If you call this function (with the “real_encoding” parameter set to “FLOAT”), HYDLLP will switch to encoding real values as JSON-format floats. You can switch it back again by calling the function with a value of “STRING”.

The Hydstra hydllp.py Python module calls this function automatically, so there are very few cases where you would need to call this function yourself.

For single call only

To allow use cases like web services, the feature is also available on a call-by-call basis for all JSonCall functions. You simply include the optional “real_encoding” parameter in your JSON data, that the feature will be enabled for that call only.

HYDLLP Exported Functions

Below is a list of functions exported by HYDLLP.DLL, expressed in Delphi syntax.

StartupEx

Starts up a session, where you specify the hyconfig .ini file.

function StartUpEx (
               aUserID   : pChar;
               aPassword : pChar;
               aHyAccess : pChar;
               aHyConfig : pChar;
           var aHandle   : integer)
                         : integer; stdcall;

Return Code

Explanation

0

OK

10 *

StartUp failed. Possible reasons include: SDE7.DLL or SDECDX7.DLL not found, HYCONFIG.INI or HYACCESS.INI not found or incorrect.

12 *

Login failed. Make sure the user ID and password are correct.

Shutdown

Closes down a session.

function Shutdown(aHandle : integer) : integer; stdcall;

Return Code

Explanation

0

OK

11 *

ShutDown failed.

JSonCall

JSonCall is a single “exported” call that can access several supported functions. The idea is that we can add new functions without modifying the DLL interface.

function JSonCall (
               aHandle       : integer;
               aRequestStr   : pAnsiChar;
           {>} aReturnStrBuf : pAnsiChar;
               aReturnStrLen : integer)
                             : integer; stdcall;

Return Code

Explanation

0

OK

200

Buffer insufficient

Anything else

(Depends on which function is called)

The aRequestStr parameter is a string in JSON format that includes the function you wish to call, and any parameters appropriate to it. See below for a list of all current JSON calls, and the parameters they require.

Here is a sample JSON request string, formatted for clarity:

{
   "function" : "get_ts_traces",
   "version"  : 1,
   "params"   : {
      "site_list"  : "HYDSYS01,HYDSYS02",
      "varfrom"    : "100.00",
      "start_time" : "19750801000000",
      "datasource" : "A",
      "varto"      : "100.00",
      "interval"   : "day",
      "end_time"   : "19750802000000",
      "data_type"  : "mean",
      "multiplier" : "1"
   }
}  

The name of the desired function must be specified in an outer-level item called “function”. You must also specify the version of the call (all calls are currently at version 1) to allow for future enhancements.

The “params” item is a wrapper in which you specify named items, depending on which function you are calling.

Here is an example of the output from the above call, which is also encoded using JSON, formatted for clarity:

{ "error_num":0,
  "buff_supplied":8192,
  "buff_required":1363,
  "return":{
    "traces":[
      { "site":"HYDSYS01",
        "site_details":{
          "short_name":"Hydstra Test Station",
          "name":"Hydstra Test Station - Composite data"},
        "varfrom_details":{
          "short_name":"Level     (Metres)",
          "subdesc":"",
          "variable":" 100.00",
          "units":"Metres",
          "name":"Stream Water Level"},
        "varto_details":{
          "short_name":"Level     (Metres)",
          "subdesc":"",
          "variable":" 100.00",
          "units":"Metres",
          "name":"Stream Water Level"},
        "quality_codes":{
          "1":"Good continuous records"},
        "trace":[
          {"v":"0.363","t":19750801000000,"q":1},
          {"v":"0.368","t":19750802000000,"q":1},
          {"v":"0.363","t":19750803000000,"q":1},
          {"v":"0.464","t":19750804000000,"q":1},
          {"v":"0.505","t":19750805000000,"q":1}]
      },
      {  "site":"HYDSYS02",
         "site_details":{
           "short_name":"Hydstra Test Station",
           "name":"Hydstra Test Station - Secondary rainfall data"},
         "varfrom_details":{
           "short_name":"Level     (Metres)",
           "subdesc":"",
           "variable":" 100.00",
           "units":"Metres",
           "name":"Stream Water Level"},
         "varto_details":{
           "short_name":"Level     (Metres)",
           "subdesc":"",
           "variable":" 100.00",
           "units":"Metres",
           "name":"Stream Water Level"},
         "quality_codes":{
           "1":"Good continuous records"},
         "trace":[
           {"v":"0.363","t":19750801000000,"q":1},
           {"v":"0.368","t":19750802000000,"q":1},
           {"v":"0.363","t":19750803000000,"q":1},
           {"v":"0.464","t":19750804000000,"q":1},
           {"v":"0.505","t":19750805000000,"q":1}]
      }
    ]
  }
}

NB:

Tokens that have a multiple line value will have the lines separated by '/013/010'

 

List of Available JSonCall Functions

All JSonCall examples are formatted using Perl syntax. If you want JSON formatting then you can use HYDLLP_UI with the Input Type set to PERL and making sure to set Print JSON input.

If you are developing web service call REST URLs, you may wish to set HYDLLP_UI Print JSON output.

In general all Perl requests can be easily translated to JSON by replacing all single quotes with double quotes and the reference operator ‘=>’ with ‘:’.

get_ts_traces

Retrieves one or more time series traces.

When HYDLLP is running under the Hydstra/WEB framework, certain privacy-sensitive information can be excluded from the returned data by settings in DATAPRIV.INI, which is administered by HYDATAPRIV. This lets you deny access to personal information in TS comments.

Changes for version 2

In version 2, with the addition of var_list we decided that returning an error for each variable at each site that didn't contain any data no longer made sense. Now, if there is no data for a given variable at a given site, nothing is returned for that variable and site.

The report_time parameter has been added.

 

parameter

description

options

example

site_list

Hydstra site list expression

 

group(REGION,NORTH)

start_time

data period start datetime YYYYMMDDhhmmss

YYYYMMDDHHIIEE
or
0

19750501000000

end_time

data period end datetime YYYYMMDDhhmmss.

YYYYMMDDHHIIEE
or
0

19750510000000

varfrom

source variable. Optional in version 2. Either var_list or varfrom must be specified.

 

100.00

varto

destination variable. Only used when varfrom is specified.

 

140.00

var_list

A list of source variables. Only available in version 2. Optional but either varfrom or var_list must be specified.

 

100,140.01,232
or
not(100)

interval

data interpolation interval

year, month, day, hour, minute, second,
period,
default

year

multiplier

interval multiplier

integer

5

recent_points

only return the most recent n points that were retrieved, discarding any trailing bad quality points (eg for “data current” type plots / reports)

integer

20

report_time

(optional) (Version 2 only) Specifying the report_time as “end” will cause the time output with aggregated values for mean, total, and partial total data types to be the end of the period instead of the start.

start, end

end

offset

(optional) If you specify start_time = end_time = 0 then the interval will round to the start of the current interval. (day for example) This offset is specified in minutes and lets you translate the period.

Integer

60

datasource

Hydstra datasource code

 

A

data_type

data extraction type

mean, maxmin, max, min, start, end, first, last, tot,
point, partialtot, cum.  Note that for max, min, and maxmin types the times returned are the actual time of the max or min. Note that Hydstra does not have a time of 24:00 so a max at time 24:00 will be shown as 00:00 on the following day.

mean

match_comment

(optional) Only return points that match the regular expression provided.

A regular expression

Proc.*

rel_times

(optional) if true, return datetimes in minutes since 01/01/1601

0 (false) 1 (true)

1

bad_value

(optional) lets you override the value element for data items where the quality is bad (greater than your hyconfig MAXGOODQ). You may provide a flag value (eg “Missing”) or a censoring numeric value (eg 0.0). If you provide a numeric, it will be formatted the same as other extracted values.

Any expression, string or numeric.

0.0

compressed

(optional) determines the output formatting of the trace data. Compressed formatted data is similar to Hydstra Standard Time Series Text File Format with the format of each line being TIME,VAL,QUAL,DT,COMNT

0 (false) 1 (true)

0

rounding

(optional) a rounding specification used by various JSonCall functions to format value results with a defined variable.

 

JSonCall Number Formatting

NB:

If data_type = POINT, the interval and multiplier are ignored.

If data_type = TOT, the datetime of the returned value is the start of the period.
(e.g. a daily total discharge with datetime of 20111020000000 means the total discharge for the period from 00:00_20/10/2011 to 00:00_21/10/2011)

A note on timing when retrieving data - if you retrieve point data then the retrieval is driven by the data points in the time series file, and points between the start and end time (inclusive) will be retrieved, and interval and multiplier are ignored. If however you select any aggregating type like mean, tot etc. then the retrieval is driven by interval and multiplier. Values will be retrieved and reported against the start of the interval (unless you specify reporttime=end)until the start time of a retrieval period exceeds the end time of the request. What this means is that if you request daily totals from 01 Jan to 02 Jan, you will get two values back, one for the period starting 01 Jan and another for the period starting 02 Jan.

If data_type = CUM, the data should be of total type otherwise the results will be invalid. Total type mean to be datatrans 5 or 6, i.e. rainfall data.

If interval = PERIOD, a single value spanning the specified period is returned, (and data_type cannot be POINT).

If interval = DEFAULT (and data_type is not POINT), an interval will be chosen automatically, based on the period extracted. The algorithm is the same as used by HYPLOT when you specify interval=DEFAULT. This makes most sense if the data_type is CUM (for total type data) or MAXMIN (for everything else).

If you wish to get a single value you can use the data_type of START with the
start_time = end_time = the time of the value you wish to get.

If you are producing a “data current” type plot, and are only interested in a limited number of points, you can specify recent_points to limit the number of points returned. The end_time parameter would typically be “now”, and your choice of start_time now controls “how far back to look”, rather than the start time of the returned series of points. If you do this, any trailing bad-quality points are discarded – the final point returned will be the final good-quality point.

If you wish to get the period of record then you can set the start_time and end_time to 0. This will cause the period of record to be used for the requested variable.

Sample request

{
  'function' => 'get_ts_traces',
  'version'  => 2,
  'params'   => {
    'site_list'  => 'HYDSYS01,HYDSYS02',
    'start_time' => '19750801000000',
    'varfrom'    => '100.00',
    'interval'   => 'day',
    'varto'      => '100.00',
    'datasource' => 'A',
    'end_time'   => '19750802000000',
    'data_type'  => 'mean',
    'rounding'   => [
      {
        'zero_no_dec' => '1',
        'dec_first'   => '1',
        'sigfigs'     => '4',
        'variable'    => '100',
        'decimals'    => '2'
      }
    ],
    'multiplier' => '1'
  }
}  

Sample return data

{ "error_num":0,
  "buff_supplied":8192,
  "buff_required":1363,
  "return":{
    "traces":[
      { "site":"HYDSYS01",
        "site_details":{
          "short_name":"Hydstra Test Station",
          "name":"Hydstra Test Station - Composite data"},
          "timezone":"10.0",
        "varfrom_details":{
          "short_name":"Level     (Metres)",
          "subdesc":"",
          "variable":" 100.00",
          "units":"Metres",
          "name":"Stream Water Level"},
        "varto_details":{
          "short_name":"Level     (Metres)",
          "subdesc":"",
          "variable":" 100.00",
          "units":"Metres",
          "name":"Stream Water Level"},
        "quality_codes":{
          "1":"Good continuous records"},
        "trace":[
          {"v":"0.3600","t":19750801000000,"q":1},
          {"v":"0.3700","t":19750802000000,"q":1},
          {"v":"0.3600","t":19750803000000,"q":1},
          {"v":"0.4600","t":19750804000000,"q":1},
          {"v":"0.5000","t":19750805000000,"q":1}],
        "compressed":"0",
        "error_num" : 0
      },
      {  "site":"HYDSYS02",
         "site_details":{
           "short_name":"Hydstra Test Station",
           "name":"Hydstra Test Station - Secondary rainfall data"},
           "timezone":"10.0",
         "varfrom_details":{
           "short_name":"Level     (Metres)",
           "subdesc":"",
           "variable":" 100.00",
           "units":"Metres",
           "name":"Stream Water Level"},
         "varto_details":{
           "short_name":"Level     (Metres)",
           "subdesc":"",
           "variable":" 100.00",
           "units":"Metres",
           "name":"Stream Water Level"},
         "quality_codes":{
           "1":"Good continuous records"},
         "trace":[
           {"v":"0.3600","t":19750801000000,"q":1},
           {"v":"0.3700","t":19750802000000,"q":1},
           {"v":"0.3600","t":19750803000000,"q":1},
           {"v":"0.4600","t":19750804000000,"q":1},
           {"v":"0.5000","t":19750805000000,"q":1}],
         "compressed":"0",
         "error_num" : 0
      }
    ]
  }
}

 

write_ts_traces

Writes one or more time series traces.  (Do NOT use with REST web service requests.)

parameter

description

traces

An array of trace specifications

 

parameter

description

options

example

site

The name of the site you wish to store the time-series data under.

 

HYDSYS01

(optional) open_mode

The open mode specifies how data should be added to a time-series file if it already exists. The default value is erase.

erase, search, append, increment, overlay, and abort. See HYCREATE for a full description of open_modes.

erase

datasource

Hydstra datasource code

 

A

variable

Output variable

 

100

(optional) datatrans

This is an override datatrans. If you don't specify a value for this then you must specify the 'd' value for every point.

 

5

(optional) quality

This is an override quality. If you don't specify a value for this then you must specify the 'q' value for every point.

 

150

(optional) max_gap

Sets the maximum gap allowed between points in minutes.

 

60

(optional) max_join

Sets the maximum gap allowed between the end of the existing file and the first new point, when open_mode = increment.

 

60

(optional) max_truncate

Sets the maximum amount of data that can be truncated by an open_mode of overlay. Defaults to max_join if no value is provided.

 

60

(optional) fixed_interval

Specifies that data points correspond to fixed time intervals. This causes HYDLLP to write appropriate anchor points (depending on the data type), and also preserve the quality of points (and their corresponding intervals) surrounding gaps.

year, month, day, hour, minute, second.

 

(optional) fixed_intmult

Specifies the multiplier for fixed_interval, required if you specify it.

 

 

points

An array of points

 

parameter

description

example

v

The value of the point

10.5

t

The time of the point

YYYYMMDDHHIIEE

20130318140135

(optional) q

The quality of the point

5

(optional) d

The datatrans of the point

6

(optional) c

Any comments associated with the point. Comments can be line separated by inserting /013/010 where you desire a line break.

line 1/013/010line 2

For further details on the open_mode, max_gap, max_join, and max_truncate parameters you should look at HYCREATE.

 

NB:

If you want to add a \ to a comment then you will need to double it, \\. This is done to help with round trips for comments from get_ts_traces. It should be noted though, that comments containing /013 or /010 cannot be round tripped.

 

Sample request

{
  'function' => 'write_ts_traces',
  'version'  => 1,
  'params'   => {
    'traces' => [{
      'site'         => 'HYDSYS01',
      'open_mode'    => 'erase',
      'datasource'   => 'D',
      'variable'     => '10',
      'datatrans'    => '5',
      'quality'      => '2',
      'max_join'     => '0.0',
      'max_truncate' => '0.0',
      'points'       => [
        {
          'v' => '0.5',
          'q' => '1',
          't' => '20130318140100',
        },{
          'v' => '0.15',
          't' => '20130318140130',
          'c' => 'A comment'
        },{
          'v' => '10.5',
          'q' => '1',
          'd' => '6',
          't' => '20130318140135',
        }
      ]
    },{
      'site'       => 'HYDSYS01',
      'open_mode'  => 'append',
      'datasource' => 'D',
      'variable'   => '100',
      'datatrans'  => '1',
      'quality'    => '2',
      'points'     => [
        {
          'v' => '0.5',
          'q' => '1',
          't' => '20130318140100',
        },{
          'v' => '0.15',
          't' => '20130318140130',
          'c' => 'A comment/013/010Second line'
        }
      ]
    }]
  }

Sample return data

{
   "buff_required" : 59,
   "buff_supplied" : 1000000,
   "error_num" : 0
}  

 

hyfiler_command

Executes a HYFILER command. (Do NOT use with REST web service requests.)

parameter

description

options

example

command

A hyfiler command. If a command has a listdev parameter then you must place %LIST% in its place if you wish to receive the results.

 

MIRROR HYDSYS01 A Q %LIST% /QUIET /RETRY=2

wait (optional)

If the hyfiler command can't access a time-series file then this option specifies in minutes how long this call should keep trying to gain access. Specifying 0 means the call will not try again. This option isn't supported in Hydstra versions earlier than 11. In Hydstra versions earlier than 11 the default behaviour is to not try again.

integer value representing minutes

5

 

Sample request

{
  'function' => 'hyfiler_command',
  'version'  => 1,
  'params'   => {
    'command' => 'MIRROR HYDSYS01 A Q %LIST%',
    'wait'    => '0'
  }
}

Sample return data

{
   "buff_required" : 371,
   "buff_supplied" : 1000000,
   "error_num" : 0,
   "return" : {
      "output" : "HYDLLP V209  Output 30/10/2013\r\n\r\n  Command:           MIRROR\r\n  Site(s):           HYDSYS01\r\n  Source Datasource: A\r\n  Target Datasource: Q\r\n  Options:           QUIET, OVWRITE, RETRY=5, WAIT=2.0\r\n\r\nCopy HYDSYS01        succeeded\r\n\r\nSummary:\r\n  1 files copied\r\n"
   }
}  

 

get_site_list

Retrieves a list of sites from a HYSTNS sitelist expression

parameter

description

options

example

site_list

Hydstra site list expression

 

201001,201002

Sample request

{
  'function' => 'get_site_list',
  'version' => 1,
  'params' => {
    'site_list' => 'TSFILES(DSOURCES(ARCHIVE))'
  }
}

Sample return data

{ "error_num":0,
  "buff_supplied":8192,
  "buff_required":483,
  "return":{
    "sites":[
      "HYDSYS01",
      "HYDSYS02",
      "HYDSYS03",
      "HYDSYS04",
      "HYDSYS05",
      "HYDSYS06",
      "HYDSYS07"]
  }
}

 

get_db_info

Retrieves data from a database table.

If a user has an insufficient read level based on PASSWD.LEVELS and USERMAS.MINLEVREAD then an error will be returned. You can use this to stop certain tables from being accessed by web users.

When HYDLLP is running under the Hydstra/WEB framework, certain privacy-sensitive information can be excluded from the returned data by settings in DATAPRIV.INI, which is administered by HYDATAPRIV. This lets you deny access to specified timeseries data comments and user info.

 

Changes for version 2

The version breaking change came about because we were handling dates in an inconsistent way. We decided that the best approach was to standardise on a single date format YYYYMMDD. This could cause issues with any dates being used in complex_filter or simple_filter. Dates being returned may have also changed format.

 

Changes for version 3

The version breaking change occurs when asking for a hash return_type. If one of the hash keys is a date field then in version 2 it was formatted as YYYYMMDDHHIIEE which was inconsistent with the direction we chose. Date key returns are now formatted as YYYYMMDD instead.

 

parameter

description

options

example

table_name

Hydstra database table name

 

site

return_type

type of data structure returned. HASH returns a deep hash with the record preceded in the hash tree by all the key fields, whereas ARRAY returns an array of records.

hash, array

hash

filter_values

(optional) query filter using a hash of fieldname=value pairs

WARNING: you can not use filter_values and complex_filter at the same time.

Filters on date fields are specified as YYYYMMDDhhmmss.

Filters on logical/boolean fields are specified as ‘true’ or ‘false’

 

'station' =>: '201001'

‘date’ => ‘19990101000000’

‘active’ => ‘true’

field_list

(optional) an array of field names, to return a subset of columns

 

'STATION','STNAME'

sitelist_filter

(optional) filter based on the station field using a HYSTNS filter expression.

NOTE: If you do not specify a complex_filter or filter_values then the internal operation of the sitelist_filter will change. This may have implications on the performance of this call if you specify a large site list against a small table.

 

'match(hy*)'

geo_filter

(optional) filter based on latitude and longitude

·         Circle takes an array parameter:
[latitude, longitude, radius in degrees]

·         Rectangle takes an array of arrays:
[[top_left_latitude,top_left_longitude], [bottom_right_lat,bottom_right_long]]

·         Region takes an array of arrays:
[[latitude1,longitude1], [latitude2,longitude2], [latitude3,longitude3]…]

(more information on geo_filter below)

Circle

'circle' => ['-35','149',1]

Rectangle

'rectangle' =>
[['-35','148'],['-36','149']]

region

'region' =>
[['-35','148'],['-36','149'], ['-36','148']]

complex_filter

(optional) filter based on the values of fields

WARNING: you can not use filter_values and complex_filter at the same time.

Filters on date fields are specified as YYYYMMDD.

combine (optional)

'combine'=>'OR'

not (optional)

'not'=>'NOT'

left (optional)

'left'=>'('

fieldname

'fieldname'=>'longitude'

operator

'operator'=>'GT'

value

'value'=>'100'

right (optional)

'right'=>') '

raw_db_filter

(optional) This filter allows you to directly filter the database in the same way hymanage or hydbutil do. HYMANAGE - Xbase filter expressions

 

 

order

(optional) a named order (from the Hydstra DBI files) to control the order of the returned rows; for a hash, it influences the hierarchical structure

 

REGION

start_from

(optional) This lets you trim the return by skipping the first (start_from – 1) rows.

 

 

return_limit

(optional) This lets you limit the number of rows returned to the number provided. If the limit is reached without running out of rows then a next_from parameter will be placed in the return structure. Using the next_from value as your start_from value allows you to iterate over smaller chunks of the original result.

 

 

decodes

Include field value decodes, ie site/variable names, coded value descriptions etc. These will be returned as elements named fieldname_decode

 

'decodes'=>1

labels

Include field labels, ie the field description from DATADICT. This is especially useful for fields with names like SPARE1 and CATEGORY1, where the field name gives no clue about the data it contains.

 

'labels'=>1

Sample request

{
  'function' => 'get_db_info',
  'version' => 2,
  'params' => {
    'geo_filter' => {
      'region' => [
        [
          '-35',
          '149'
        ],[
          '-35.1',
          '150'
        ],[
          '-33',
          '142'
        ]
      ]
    },
    'return_type' => 'array',
    'sitelist_filter' => 'match(hy*)',
    'field_list' => [
      'bdate',
      'bench',
      'elev',
      'rlgd',
      'method'
    ],
    'raw_db_filter' => '(station > "A               ") AND (station < "C")',
    'complex_filter' => [
      {
        'operator' => 'NE',
        'value' => 'HYDSYS04',
        'fieldname' => 'station'
      }
    ],
    'table_name' => 'bench',
    'filter_values' => {
      'station' => 'HYDSYS01'
    }
  }
}

Sample return data

{ "error_num":0,
  "buff_required":249,
  "buff_supplied":8192,
  "return":{
    "rows":[
      {"method":"",
       "rlgd":"3.438",
       "elev":"0.000",
       "bench":"       2",
       "bdate":19960101000000},
      {"method":"",
       "rlgd":"1.419",
       "elev":"0.000",
       "bench":"       4",
       "bdate":19960101000000}
    ]
  }
}

Complex_filter continued

option

default value

combine (optional, AND or OR)

‘AND’

not (optional)

‘’

left (optional)

‘’

right (optional)

‘’


Bracketing of complex expressions is performed by including a left or right or not operator in a subfilter. In order to build a complex filter expression such as

elev>=682 or ((elev<=1000) and (longitude>149.9) and not ((longitude<175) and (latitude=-30.885)) and (longitude!=0))

the expression would be:

'complex_filter' => [{
  'fieldname'=>'elev',
  'operator'=>'GE',         #elev is greater than or equal to 682
  'value'=>'682',
},{
  'combine'=>'OR',
  'left'=>'(',       #begin OR
  'fieldname'=>'elev',
  'operator'=>'LE',         #elev is less than or equal to 1000
  'value'=>'1000',
},{
  'fieldname'=>'longitude',
  'operator'=>'GT',         #longitude is greater than 149.9
  'value'=>'149.9',
},{
  'not'=>'NOT',            
  'left'=>'(',       #begin NOT
  'fieldname'=>'longitude',
  'operator'=>'LT',         #longitude is less than 175
  'value'=>'175',
},{
  'fieldname'=>'latitude',
  'operator'=>'EQ',         #latitude is equal to -30.855
  'value'=>'-30.85500000',
  'right'=>')',             #end NOT
},{
  'fieldname'=>'longitude',
  'operator'=>'NE',         #longitude is not equal to 0
  'value'=>'0.0000000',
 'right'=>')',             #end OR
}]

The following text operators are also supported, in addition to the usual comparison operators:

text operator

meaning

FoxPro

SQL

Example

EQ

equals

Yes

Yes

'fieldname'=>'region’, 'operator'=>'EQ',
'value'=>'1'

NE

not equals

Yes

Yes

'fieldname'=>'region’, 'operator'=>'NE',
'value'=>'1'

GT

greater than

Yes

Yes

'fieldname'=>'region’, 'operator'=>'GT',
'value'=>'1'

LT

less than

Yes

Yes

'fieldname'=>'region’, 'operator'=>'LT',
'value'=>'1'

GE

greater than or equal

Yes

Yes

'fieldname'=>'region’, 'operator'=>'GFE',
'value'=>'1'

LE

less than or equal

Yes

Yes

'fieldname'=>'region’, 'operator'=>'LE',
'value'=>'1'

CONT

contains

Yes

Yes

'fieldname'=>'stname', 'operator'=>'CONT',
'value'=>'river'

IN (only available in Apollo)

string is exactly in a comma delimited list

Yes

No

'fieldname'=>'station',  'operator'=>'IN',  'value'=>'HYDSYS02       ,HYDSYS03       '

LIKE

the sql condition with _ and % wildcards

Yes*

Yes

'fieldname'=>'station', 'operator'=>'LIKE',
value=>'HYD%'

NOTCONT

does not contain

Yes

No

'fieldname'=>'stname', 'operator'=>'NOTCONT',
'value'=>'creek'

NOTCONT

does not contain

Yes

No

'fieldname'=>'stname', 'operator'=>'NOTCONT',
'value'=>'creek'

NOTIN

not in comma delimited  list

Yes

No

'fieldname'=>'owner', 'operator'=>'NOTIN',
'value'=>'DWR,SCA,NSW'

* A limited version of the LIKE operator is available under FoxPro, but does not support the full SQL features.
All text comparisons are performed in alphabetical order (case is ignored), hence

A < AA < AB < B < BA
4 < 5  < A

 

Geo_filter continued

circle => [lat, long, difference in degrees]

The circle filter will return points that fall inside the great circle and will inconsistently return points that fall on the boundaries due to errors in floating point arithmetic. The radius of the circle is degrees of the central angle.

rectangle => [[lat, long], [lat, long]] ([[top, left], [bottom, right]])

The rectangle filter will return points that fall inside the region, including the boundary points.

region => [[lat, long], [lat, long], ..., [lat, long]]

The region filter will return points that fall inside the region, excluding the boundary points.

The geo_filter feature has an optional performance boost, allowing the retrieval to be much faster, if and only if the following conditions are met:

•You are retrieving from the SITE table

•There is no “filter_values” filter

•There is no “complex_filter” filter

•There is no “raw_db_filter” filter

•There is no “order” specified

If those conditions are not met, the retrieval will be slower (depending on your other filtering etc).

There is also a minor side-effect of this speedup: if you have specified that the data is to be returned in “array” form (as opposed to “hash”) the sites will be in LATITUDE order instead of by site ID.

write_db_info

Writes rows to database tables in a work area.

 

parameter

description

options

example

table_name

Hydstra database table name, which must include a work area specifier, see example

 

[priv.test]site

rows

An array of the rows to write.

There are two possible formats:
(a) if you have specified a field_list parameter, each row must be an array or values, which will be written to the corresponding field in fileld_list. This is the fastest and most memory-efficient format.

(b) if you have not specified a field_list parameter, each row must be a hash of field=value pairs. This option is slightly slower and less memory efficient.

To help you keep track of problems, there is a special “pseudo-field” supported, called _CONTEXT_. If you specified field_list, you may specify a field called _CONTEXT_, and you must provide a value for it in each row. If you are using the hash method, you may provide a _CONTEXT_ value on any row you choose. Whenever a record cannot be written (or fails validation), HYDLLP will provide the context, as well as the key (if possible) so that you can connect the failure to its original source.

hash, array

field_list

(optional) As discussed above, this parameter lets you choose to specify rows as arrays or hashes.

 

erase

(optional, Default is True.) if True (or 1, or “Y” etc), the table will be erased and recreated before any rows are added. If False (or 0 or “N”), any existing data is preserved, and the new data appended.
Basically if you are writing data in multiple chunks the first call should have erase=>1 and all subsequent calls should have erase=>0.

 

 

validate

(optional) controls validation.

All data is checked for “critical” errors (in valid numeric column values, invalid dates, character strings too long).

This parameter controls whether or not additional checking – the type that is typically specified by DATADICT – is performed.

Default is True

Only data that passes these checks is written to the database.

 

bulkdump

(Optional, default = No) If you specify this as Yes, the data is written to a bulk dump file, and the return value includes an additional value: “bulkload_script”, consisting of an array of commands which will load the data to the database table.
If you are running under SQL Server, the bulk dump file is in SQL Server bulk dump format, and the script will include a call to BCP.EXE, and relies on your HYSQLLOAD.INI file for various database-related settings.
If you are running under the FoxPro format database, the bulk dump file is a Hydstra CSV file, and the import script includes a call to HYDBUTIL APPEND.

 

 

Sample request

{

   "params" : {

      "erase" : "Y",

      "table_name" : "[priv.test]site",

      "rows" : [

         {

            "shortname" : "Test site",

            "station" : "HYDSYS01",

            "stname" : "Test site"

         }

      ]

   },

   "function" : "write_db_info",

   "version" : 1



Sample return data

{

   "buff_required" : 702,

   "error_msg" : "Some validation errors were encountered",

   "buff_supplied" : 1000000,

   "error_num" : 141,

   "return" : {

      "rows_written" : "0",

      "errors" : [

         "Table SITE, key [HYDSYS01]: SITE.LATITUDE : Invalid latitude (): latitude must be within -90 and 90",

         "Table SITE, key [HYDSYS01]: SITE.LONGITUDE : Invalid longitude (): longitude must be within -180 and 180",

         "Table SITE, key [HYDSYS01]: SITE.TIMEZONE : Value () must be within the range -12.000000 to 13.000000",

         "Table SITE, key [HYDSYS01]: SITE.OWNER : Please specify a currently enabled, active, TS>0 user from the PASSWD table ()",

         "Table SITE, key [HYDSYS01]: SITE.REGION : Code [] not found in code group [REGION - Region]"

      ],

      "rows_rejected" : "1"

   }

}

 

get_db_areas

Takes a list of area classes and returns a list of work area specifiers.

parameter

description

options

example

area_classes

A list of area classes used to specify a list of work area specifiers.

['priv','pub','temp','junk','archive']

['priv','temp','junk']

user_specific

(optional) Set to true if you wish to find work areas owned by other users.

0 (false) 1 (true)

0

return_tables

(optional) Set to true if you wish to find the tables in each work area.

0 (false) 1 (true)

1

check_upgrade

(optional) Set to true if you wish to determine which work area tables need to be upgraded.

0 (false) 1 (true)

1

Sample request

{
  'function' => 'get_db_areas',
  'version'  => 1,
  'params'   => {
#    'area_classes' => ['priv','pub','temp','junk','archive'],
    'area_classes' => ['pub','archive'],
    'user_specific' => '0', #(optional) (defaults to false)
    'return_tables' => '1', #(optional) (defaults to false)
    'check_upgrade' => '1'  #(optional) (defaults to false)
  }
}

Sample return data

{
   "buff_required" : 16439,
   "buff_supplied" : 17259,
   "error_num" : 0,
   "return" : {
      "work_area_specifics" : {
         "temp" : [{
            "table"   : "[TEMPFILES]HYCONFIG",
            "current" : "False",
            "reason"  : "error encountered while checking: Table C:\\TEMP\\HYCONFIG could not be opened."
         },{
            "table"   : "[TEMPFILES]HYCONFIGFC",
            "current" : "False",
            "reason"  : "error encountered while checking: Table C:\\TEMP\\HYCONFIGFC could not be opened."
         }],
         "archive" : [{
            "table"   : "[ARCHIVE]ACCINST",
            "current" : "TRUE"
         },{
            ... many lines
         },{
            "table"   : "[ARCHIVE]WREHOUSE",
            "current" : "TRUE"
         }],
         "junk" : [{
            "table"   : "[JUNKFILES]CQLLRAOH",
            "current" : "FALSE",
            "reason"  : "error encountered while checking: F:\\hyd\\sys\\misc\\dbi\\CQLLRAOH.DBI does not exist."
         }],
         "priv" : [{
            "table"   : "[CMR.HYRATED]RATEEQN",
            "current" : "TRUE"
         },{
            ... many lines
         },{
            "table"   : "[CMR.MASTDICTUM]MASTDICT",
            "current" : "TRUE"
         }],
         "pub" : [{
            "table"   : "[PUBLIC.ACC]ACC",
            "current" : "FALSE",
            "reason"  : "error encountered while checking: F:\\hyd\\sys\\misc\\dbi\\ACC.DBI does not exist."
         },{
            ... many lines
         },{
            "table"   : "[PUBLIC.WQWRK]SAMPLES",
            "current" : "FALSE",
            "reason"  : "SAMPLES: Field Count = 29; DBI Field Count = 39"
         }]
      }
   }

get_latest_ts_values

Retrieves a list of the latest time-series points for a site list. By default it looks back to the latest good quality data point. Mainly used for web sites and other displays of current value from telemetered data.

parameter

description

options

example

site_list

Hydstra site list expression

 

201001

datasource

A datasource code

 

A

site_details

(optional) a boolean value used to request site details be returned with each varfrom and varto pair.

0 (false) 1 (true)

Defaults to 0

1

rounding

(optional) a rounding specification used by various JSonCall functions to format value results with a defined variable.

 

JSonCall Number Formatting

trace_list

A list of parameters defining the latest value required. accum_period is used for total-type data like rainfall, and is latched to the start of the day, so if you ask for the latest 15 minute value it will start on the hour, or at 15,30 or 45 minutes past the hour – you won't ever get a 15 minute total starting at 12:17. daystart specifies the start time in the day, so if you ask for daily values they will start at this time (midnight by default).

varfrom

100.00

varto

100

accum_period (in minutes) (optional defaults to 0)

15

accum_partial. If set to 0 then the last complete accumulated period is used. If set to 1 then the last 2 accumulated periods with any data are returned (optional defaults to 0)

1

output_time (start or end). Only makes sense when accum_period is non zero. Determines which end of the accum_period the output_time is associated with.
REMOVED IN VERSION 2

start

daystart (hhmm) (optional defaults to 0:00, midnight)

0900

lookback (minutes). If not specified the call will look back as far as it needs to.

120

anyqual. If set to 0 the last good quality point in the lookback period will be returned, if set to 1 the last point will be returned even if it is bad quality. If accum_period is greater than 0 then anyqual defines whether or not a bad quality value will be returned but doesn't keep looking for a good quality value. (optional defaults to 0)

1

now (used mainly for testing), Normally the call looks back from the current time , e.g. Now(), but the start time of the lookback can be overridden with this parameter. This parameter must be used in conjunction with the lookback parameter; otherwise the end time of the trace will be used. (optional defaults to right now)

19910524062000

The call returns the latest value, the time of the latest value (start time of a periodic total) and the trend, which is the difference between the last value and the one before it. Trend can be + for rising, - for falling, 0 for static, and ? if unknown because of bad/missing data. Static trend is defined as the two values being equal when rounded to the precision stored in VARIABLE.

Sample request

{ 'function' => 'get_latest_ts_values',
  'version' => 2,
  'params' => {
    'site_list' => 'hydsys01',
    'datasource' =>'A',
    'trace_list' => [
      {'varfrom'=>'100.00','varto'=>'100','lookback'=>'60'},
      {'varfrom'=>'100.00','varto'=>'100','lookback'=>'60', 'anyqual'=>'1'},
    ]
  }
}

Sample return data

{  "buff_required" : 263,
   "buff_supplied" : 1000,
   "error_num" : 0,
   "return" : {
      "HYDSYS01" : [
         {"varfrom" : "100.00",
          "values" : [
             {"time_start" : "",
              "p" : "",
              "time_end" : "",
              "q" : 151,
              "v" : "0.0",
              "trend" : "?",
              "time" : "20110513150431"}
          ],
          "varto" : "100.00"},
         {"varfrom" : "100.00",
          "values" : [
             {"time_start" : "",
              "p" : "",
              "time_end" : "",
              "q" : 151,
              "v" : "0.0",
              "trend" : "?",
              "time" : "20110513150431"}
          ],
          "varto" : "100.00"}
      ]
   }
}

Sample request

{ 'function' => 'get_latest_ts_values',
  'version'  => 2,
  'params'   => {
    'site_list'  => 'hydsys01',
    'datasource' => 'A',
    'trace_list' => [
      {'varfrom'  => '10.00',
       'varto'    => '10',
       'accum_period' => '1440',
       'accum_partial' => '1',
       'daystart' => '0900',
       'lookback' => '10080'},
      {'varfrom'  => '10.00',
       'varto'    => '10',
       'accum_period' => '1440',
       'daystart' => '0900'},
      {'varfrom'  => '10.00',
       'varto'    => '10',
       'accum_period' => '1440',
       'accum_partial' => '1',
       'daystart' => '0900',
       'anyqual'  => '1',
       'lookback' => '10080'}
    ] ,
    'rounding' => [
      {
        'variable'   => '10',
        'zero_no_dec'=> '1',
        'dec_first'  => '0',
        'ranges'     => [
          {'val'     => '0',
           'decimals'=> '3'},
          {'val'     => '0.7',
           'sigfigs' => '2',
           'decimals'=> '2'},
          {'val'     => '1.4',
           'decimals'=> '4'}
        ]
      }
    ]
  }
}

Sample return data

{  "buff_required" : 3016,
   "buff_supplied" : 3166,
   "error_num" : 0,
   "return" : {
      "HYDSYS01" : [
         {"varfrom" : "10.00",
          "values" : [
             {"time_start" : "20120315090000",
              "p" : "3.472",
              "time_end" : "20120315095000",
              "time" : "20120315095000",
              "q" : 2,
              "v" : "0.100",
              "trend" : "?"}
          ],
          "varto" : "10.00",
          "accum_period" : 1440},
         {"varfrom" : "10.00",
          "values" : [
            "time_start" : "20110306090000",
            "time" : "20120301121949",
            "v" : "1.5000",
            "p" : "100.0",
            "time_end" : "20120304090000",
            "q" : 2,
            "trend" : "+"
          ],
          "varto" : "10.00",
          "accum_period" : 1440},
         {"varfrom" : "10.00",
          "values" : [
             {"time_start" : "20120314090000",
              "p" : "99.306",
              "time_end" : "20120315090000",
              "time" : "20120315085500",
              "q" : 254,
              "v" : "0.90",
              "trend" : "?"},
             {"time_start" : "20120315090000",
              "p" : "3.472",
              "time_end" : "20120315095000",
              "time" : "20120315095000",
              "q" : 2,
              "v" : "0.100",
              "trend" : "?"}
          ],
          "varto" : "10.00",
          "accum_period" : 1440}
      ]
   }
}      

get_ts_blockinfo

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

When HYDLLP is running under the Hydstra/WEB framework, certain privacy-sensitive information can be excluded from the returned data by settings in DATAPRIV.INI, which is administered by HYDATAPRIV. This lets you deny access to personal information in in the “audit trail” section of TS data blocks.

 

Changes for version 2

The version breaking change came about because we wanted a consistent return structure across all HYDLLP Json calls. The return structure has had a return element added at its base.

 

parameter

description

options

example

site_list

Hydstra site list expression

 

filter(table(site),match(h*))

datasources

an array of one or more datasource codes

 

'A','T'

variables

an array of one or more variable codes. (optional)

 

'100','10'

starttime

a datetime, combined with endtime that all blocks returned must be at least partially between. (optional)

 

'20110111143015'

endtime

a datetime, combined with starttime that all blocks returned must be at least  partially between. (optional)

 

'20110113143015'

start_modified

a datetime, combined with end_modified that the modified date of all blocks returned must be at least  partially between. (optional)

 

'20110111143015'

end_modified

a datetime, combined with start_modified that the modified date of all blocks returned must be at least partially between. (optional)

 

'20110113143015'

fill_gaps

a boolean value used to request gaps returned as blocks with the block being marked as a gap. (optional)

0 (false) 1 (true)

'1'

auditinfo

a boolean value used to request the return of audit information. (optional, defaults to 0)

0 (false) 1 (true)

'1'

Sample request

{
  'function' => 'get_ts_blockinfo',
  'version' => 2,
  'params' => {    
    'site_list'   => 'HYDSYS01,HYDSYS02',
    'datasources'  => ['A','B','C'],
    'variables'     => ['100.00','100.01','140.00'],
    'starttime'  => '19700801000000',
    'endtime'    => '19710805000000',
    'start_modified'=>'20000101000000',
    'end_modified'=>'20110201000000',
    'auditinfo'   => '0'
  }
}

Sample return data

{
  "buff_required" : 431,
  "buff_supplied" : 1500,
  "return" : {
    "blocks" : [
      {
        "site" : "HYDSYS02       ",
        "variable" : " 100.00",
        "starttime" : "19700101000000",
        "endtime" : "19710101000000",
        "datasource" : "A"
      },{
        "site" : "HYDSYS02       ",
        "variable" : " 100.00",
        "starttime" : "19710101000000",
        "endtime" : "19710122093200",
        "datasource" : "A"
      },{
        "site" : "HYDSYS02       ",
        "variable" : " 100.00",
        "starttime" : "19710122093200",
        "endtime" : "19720215145500",
        "datasource" : "A"
      }
    ],
  }
  "error_num" : 0
}

get_sites_by_datasource

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

parameter

description

options

example

datasources

an array of one or more datasource codes

 

'A','T'

Sample request

{
  'function' => 'get_sites_by_datasource',
  'version' => 1,
  'params' => {
    'datasources' => ['T','Z']
  }

Sample return data

{ "error_num":0,
  "buff_supplied":8192,
  "buff_required":209,
  "return":{
    "datasources":[
      {"datasource":"T",
         "sites":["HYDSYS01", "HYDSYS02"]},
      {"datasource":"Z",
          "sites":["HYDSYS01"]}
    ]
  }
}

 

get_varcon

Uses the variable conversion defined in the varcon table to appropriately adjust the value and quality provided.

 

Changes for version 2

The version breaking change came about because we wanted a consistent return structure across all HYDLLP Json calls. The return structure has had a return element added at its base.

 

parameter

description

options

example

site_list

a Hydstra site list expression

 

'filter(table(site),match(h*))'

datasource

the Hydstra datasource code (optional, defaults to A)

 

'A'

varfrom

source variable

 

'100'

varto

destination variable

 

'140'

rounding

(optional) a rounding specification used by various JSonCall functions to format value results with a defined variable.

 

JSonCall Number Formatting

requests

an Array of request objects

qf1, quality code

1

qf2 (optional), quality code

155

t1, datetime

19700125000000

t2 (optional), datetime

19700126000000

vf1, value

0.52

vf2 (optional), value

1.93

dtransf1 (optional), datatrans

2

dtrandf2 (optional), datatrans

2

Sample request

{ 'function'=>'get_varcon',
  'version'=>'2',
  'params'=>{
    'varcons'=>[
      { 'site_list'=>'HYDSYS01',
        'datasource'=>'A',
        'varfrom'=>'100.00',
        'varto'=>'140',
        'requests'=> [
          {'qf1'=>'1','t1'=>'19700125000000','vf1'=>'0.082'},
          {'qf1'=>'1','t1'=>'19700126000000','vf1'=>'0.111'},
          {'qf1'=>'1','t1'=>'19700127000000','vf1'=>'0.160'},
        ]
      }
    ]
  }
}

Sample return data

{
   "buff_required" : 352,
   "return" : {
      "varcons" : [
         {
            "site" : "HYDSYS01",
            "varfrom" : "100.00",
            "varto" : "140.00",
            "datasource" : "A",
            "results" : [
               {
                  "vt" : "0.104",
                  "qt" : 1,
                  "qf1" : 1,
                  "t1" : "19700125000000",
                  "vf1" : "0.082"
               },{
                  "vt" : "0.212",
                  "qt" : 1,
                  "qf1" : 1,
                  "t1" : "19700126000000",
                  "vf1" : "0.111"
               },{
                  "vt" : "0.464",
                  "qt" : 1,
                  "qf1" : 1,
                  "t1" : "19700127000000",
                  "vf1" : "0.160"
               }
            ]    
         }
      ],
   }
   "buff_supplied" : 1000,
   "error_num" : 0
}

 

get_effective_rating

Get a representation of a rating table for a specific site.

parameter

description

options

example

site_list

A site list

 

HYDSYS01,HYDSYS02

table_from

var_from, used to specify the rating table.

 

100

table_to

var_to, used to specift the rating table.

 

140

interval

The size of the gap you wish to have between input stage values.

A real number

1.5

datetime

The date and time you want the rating table to be valid for. (optional defaults to right now)

YYYYMMDDHHIIEE

20131009115430

force_range

Setting to 1 makes sure that the bounding points of the rating table are returned in the output. (optional defaults to 0)

0 (false) 1 (true)

1

quantised

Setting to 1 rounds the value from values to the nearest interval before retrieving the value to. (optional defaults to 1)

0 (false) 1 (true)

1

shifts

Setting to 1 applies the active shift to the rating table. Only applicable if there are shifts in the TSHIFT and/or SSHIFT tables. (optional defaults to 1)

0 (false) 1 (true)

1

lostage

Lets you define the low pre shift stage value to interpolate from. (optional)

A real number

0.1

histage

Lets you define the high pre shift stage value to interpolate to. (optional)

A real number

5.3

Sample request

{
  'function' => 'get_effective_rating',
  'version'  => 1,
  'params'   => {
    'site_list'   => '410001,410734',
    'table_from'  => '100',
    'table_to'    => '140',
    'interval'    => '0.9',
    'datetime'    => '19930501000000',
    'force_range' => '1',
    'quantised'   => '1',
    'shifts'      => '1'
  }
}

Sample return data

{
   "buff_required" : 1372,                                           
   "buff_supplied" : 1000000,
   "signature" : "69FE92A2B9B54A1FE7A483C70517D8DC",
   "error_num" : 0,
   "return" : {
      "sites" : [
         {
            "error_msg" : "Points rating table has no points:; STN    =410001; varfrom=100.00; varto  =140.00; tabno  =0.9; error in rating tables",
            "error_num" : 33
         },
         {
            "" : {
               "quality_codes" : {
                  "150" : "Rating table extrapolated due to inadequate gauging information"
               }
            },
            "shifts" : "True",
            "ctf" : "0.611",
            "table_to" : "140.00",
            "varfrom" : "100.00",
            "table" : 7,
            "points" : [
               {
                  "vt" : "0.0",
                  "vf" : "0.0",
                  "q" : 1
               },
               {
                  "vt" : "0.7",
                  "vf" : "0.9",
                  "q" : 1
               },
               {
                  "vt" : "16.14716093",
                  "vf" : "1.8",
                  "q" : 1
               },
               {
                  "vt" : "71.09622802",
                  "vf" : "2.7",
                  "q" : 1
               },
               {
                  "vt" : "163.452929281",
                  "vf" : "3.6",
                  "q" : 1
               },
               {
                  "vt" : "245.0",
                  "vf" : "4.5",
                  "q" : 150
               },
               {
                  "vt" : "359.860718042",
                  "vf" : "5.4",
                  "q" : 150
               },
               {
                  "vt" : "491.196753205",
                  "vf" : "6.3",
                  "q" : 150
               },
               {
                  "vt" : "650.116112695",
                  "vf" : "7.2",
                  "q" : 150
               },
               {
                  "vt" : "800.0",
                  "vf" : "8.0",
                  "q" : 150
               }
            ],
            "varto" : "140.00",
            "datetime" : "19930501000000",
            "site_details" : {
               "short_name" : "Qbn at Tinderry",
               "timezone" : "10.0",
               "name" : "Queanbeyan River at Tinderry"
            },
            "stage_low" : "0.0",
            "name" : "",
            "release" : 10,
            "stage_high" : "8.0",
            "interval" : "0.9",
            "varto_details" : {
               "subdesc" : "",
               "variable" : "140.00",
               "short_name" : "Discharge (Cumecs)",
               "name" : "Stream Discharge",
               "units" : "Cubic Metres/Second"
            },
            "site" : "410734",
            "varfrom_details" : {
               "subdesc" : "",
               "variable" : "100.00",
               "short_name" : "Level     (Metres)",
               "name" : "Stream Water Level",
               "units" : "Metres"
            },
            "table_from" : "100.00"
         }
      ]
   }
}

 

get_site_geojson

Get GeoJSON and other site table field data for the requested site list.

 

Changes for version 2

The version breaking change was fixing the ordering of latitude and longitude in the coordinates. Longitude now comes before latitude as specified by the GeoJSON specifications. Longitude, latitude, and elevation are now returned as numbers instead of strings.

 

parameter

description

options

example

site_list

A site list

 

HYDSYS01,HYDSYS02

fields

An array of fields to be returned as properties

Any field that is part of the site table

'zone','region'

get_elev

(optional) Return the elevation with the latitude and longitude?

0 (false) 1 (true)

1

Sample request

{
  'function' => 'get_site_geojson',
  'version'  => 2,
  'params' => {    
    'site_list' => 'HYDSYS01,HYDSYS02',
    'get_elev'  => 1,
    'fields'    => ['ZONE','region']
  }
}

Sample return data

{
   "buff_required" : 394,
   "buff_supplied" : 1000000,
   "error_num" : 0,
   "return" : {
      "features" : [
         {
            "type" : "Feature",
            "id" : "HYDSYS01",
            "geometry" : {
               "coordinates" : [
                  149.31388889,
                  -35.33527778,
                  682.0"
               ],
               "type" : "Point"
            },
            "properties" : {
               "region" : "1",
               "ZONE" : 55
            }
         },
         {
            "type" : "Feature",
            "id" : "HYDSYS02",
            "geometry" : {
               "coordinates" : [
                  149.31805556,
                  -35.34722222,
                  582.0
               ],
               "type" : "Point"
            },
            "properties" : {
               "region" : "2",
               "ZONE" : 55
            }
         }
      ],
      "type" : "FeatureCollection"
   }
}

 

clear_ts_cache

(Do NOT use with REST web service requests.)

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

var_filter

Optional, a variable filter expression. If specified, only variable matching the filter will be included. See HYSTNS for more information on variable filter syntax.

This is primarily designed to let you get the period of a single variable in a TS file, so you don’t have to iterate through a list of all variables looking for the one you want.
NB: one feature of variable filters is disabled in this call: if you specify a single variable, and omit the decimals, it will be treated as .00, and not all matching subvariables.

 

100.00

Sample request

{
  'function' => 'get_variable_list',
  'version' => 1,
  'params' => {
    'site_list' => 'HYDSYS03',
    'datasource' => 'A'
  }
}    

Sample return data

{ "error_num":0,
  "buff_required":484,
  "buff_supplied":8192,
  "return":{
    "sites":[
      { "site":"HYDSYS03"
        "site_details": {
          "short_name":"Hydstra Test Station",
          "name":"Hydstra Test Station - Wind data"},
          "timezone":"10.0",
        "variables":[
          { "variable":" 500.00",
            "name":"Wind Direction",
            "subdesc":"",
            "units":"Degrees",
            "period_end":"19860101000000",
            "period_start":"19811230122900"},
          { "variable":" 520.00",
            "subdesc":"",
            "name":"Wind Run",
            "units":"Kilometres",
            "period_end":"19830101000000",
            "period_start":"19811229212300"}
        ]
      }
    ]
  }
}

 

get_ado_connection

returns an ADO connection string and table string for a Hydstra table.

parameter

description

options

example

table_spec

A table specification

 

' [PUB.SITE]SITE'

Sample request

{
  'function' => 'get_ado_connection',
  'version'  => 1,
  'params'   => {
    'table_spec' => '[PUB.SITE]SITE'
  }
}

Sample return data

{
  "buff_required" : 244,
  "buff_supplied" : 1000000,
  "error_num" : 0,
  "result" : {
    "database" : "F:\\HYD\\DAT\\WDB\\SITE\\",
    "table" : "SITE",
    "server" : "",
    "schema" : "Driver={Microsoft Visual FoxPro Driver};UID=;PWD=;SourceType=DBF;SourceDb=F:\\HYD\\DAT\\WDB\\SITE\\",
    "rawname" : "F:\\HYD\\DAT\\WDB\\SITE\\SITE.DBF"
  }
}

Note that the connection string is (somewhat confusingly) called “schema” (in contrast to get_odbc_connection).

 

get_odbc_connection

returns an ODBC connection string and table string for a Hydstra table.

parameter

description

options

example

table_spec

A table specification

 

' [PUB.SITE]SITE'

Sample request

{
  'function' => 'get_odbc_connection',
  'version'  => 1,
  'params'   => {
    'table_spec' => '[PUB.SITE]SITE'
  }
}

Sample return data

{
  "buff_required" : 244,
  "buff_supplied" : 1000000,
  "error_num" : 0,
  "result" : {
    "database" : "F:\\HYD\\DAT\\WDB\\SITE\\",
    "table" : "SITE",
    "server" : "",
    "connect" : "Driver={Microsoft Visual FoxPro Driver};UID=;PWD=;SourceType=DBF;SourceDb=F:\\HYD\\DAT\\WDB\\SITE\\",
    "rawname" : "F:\\HYD\\DAT\\WDB\\SITE\\SITE.DBF"
  }
}

Note that the connection string is called “connect” (in contrast to get_ado_connection).

 

get_subvar_details

retrieves the functional and descriptive details of a subvar

parameter

description

options

example

site_list

Hydstra site list expression

 

201001,201003

variable

A Hydstra variable and subvariable

 

100.01

Sample request

{
  'function' => 'get_subvar_details',
  'version'  => 1,
  'params'   => {
    'site_list' => 'hydsys01,hydsys02',
    'variable'  => '100.01'
  }
}

Sample return data

{
   "buff_required" : 281,
   "buff_supplied" : 1000000,
   "error_num" : 0,
   "return" : {
      "sites" : [
         {
            "max_gap" : "1.000",
            "site" : "HYDSYS01",
            "variable" : "100.01",
            "desc" : "Logger",
            "compress" : "True"
         },{
            "max_gap" : "1.000",
            "site" : "HYDSYS02",
            "variable" : "100.01",
            "desc" : "Logger",
            "compress" : "True"
         }
      ]
   }
}

 

table_doc_location

Returns the root location for documents associated with a nominated record in a table.

parameter

description

options

example

table_name

The table name

 

SITE

key_fields

A list of the key field names

 

["STATION"]

key_values

The corresponding key values

 

["HYDSYS01"]

Sample request

{
  'function' => 'table_doc_location',
  'version' => 1,
  'params' => {
    'key_values' => [
      'HYDSYS0'
    ],
    'key_fields' => [
      'station'
    ],
    'table_name' => 'site'
  }
}

Sample return data

{ "error_num":0,
  "buff_required":484,
  "buff_supplied":8192
  "return":{
    "location": "F:\\hyd\\dat\\doc\\SITE\\HYDSYS01\\"
  }
}

 

table_doc_record_key

Returns the table and key values associated with a file name in the documents tree.

parameter

description

options

example

location

A folder or document name

 

"f:\\hyd\\dat\\doc\\site\\hydsys01"

Sample request

{
  'function' => 'table_doc_record_key',
  'version' => 1,
  'params' => {
    'location' => 'F:\hyd\dat\doc\SITE\HYDSYS01\'
  }
}

Sample return data

{ "error_num":0,
  "buff_required":484,
  "buff_supplied":8192
  "return":{
    "table_name": "site",
    "key_fields": ["station"],
    "key_values": ["HYDSYS0"]
  }
}

 

get_table_documents

Returns site-related document details associated with one or more tables.

parameter

description

options

example

site_list

Hydstra site list expression

 

201001,201002

table_list

A list of table names

 

["SITE","HISTORY"]

pattern

(optional) A pattern so that only certain file names or extensions are returned

 

 

root_url

(optional) A root URL to replace \HYD\WEB folder

 

 

Sample request

{
  'function' => 'get_table_documents',
  'version'  => 1,
  'params'   => {
    'site_list'  => 'HYDSYS01,HYDSYS02',
    'table_list' => ['site','history'],
    'pattern'    => '(\.jpg)|(\.doc)|(\.xls)'
  }
}

Sample return data

{
   "buff_required" : 1236,
   "buff_supplied" : 1000000,
   "error_num" : 0,
   "return" : [
      {
         "station" : "HYDSYS01",
         "tables" : {
            "history" : [],
            "site" : [
               {
                  "filesize" : 61440,
                  "filename" : "F:/hyd/dat/doc/SITE/HYDSYS01/Excel spreadsheet.xls"
               },
               {
                  "filesize" : 20480,
                  "filename" : "F:/hyd/dat/doc/SITE/HYDSYS01/Origin of HYDSYS test data.doc"
               },
               {
                  "filesize" : 271973,
                  "filename" : "F:/hyd/dat/doc/SITE/HYDSYS01/Photo - Control structure.jpg"
               }
            ]
         }
      },
      {
         "station" : "HYDSYS02",
         "tables" : {
            "history" : [],
            "site" : [
               {
                  "filesize" : 61440,
                  "filename" : "F:/hyd/dat/doc/SITE/HYDSYS02/Excel spreadsheet.xls"
               },
               {
                  "filesize" : 20480,
                  "filename" : "F:/hyd/dat/doc/SITE/HYDSYS02/Origin of HYDSYS test data.doc"
               },
               {
                  "filesize" : 271973,
                  "filename" : "F:/hyd/dat/doc/SITE/HYDSYS02/Photo - Control structure.jpg"
               }
            ]
         }
      }
   ]
}

 

get_cross_sections

Return cross section details from the SECTHED and SECTIONS tables.

parameter

description

options

example

site_list

Hydstra site list expression

 

201001,201002

section_types

A list of section types

 

 

comments

(optional) Include any section point comments?

yes/no

 

gauge_datum

(optional) Subtract gauge zero (from SECTHED table) from all reduced levels?

yes/no

 

start_date

(optional) Only return cross sections that were measured after this date

 

 

end_date

(optional) Only return cross sections that were measured before this date

 

 

Sample request

{
  'function' => 'get_cross_sections',
  'version'  => 1,
  'params'   => {
    'site_list'     => 'HYDSYS01,HYDSYS02',
    'section_types' => ['xs'],
    'comments'      => 'yes',
    'gauge_datum'   => 'yes',
    'start_date'    => '19800101',
    'end_date'      => '19900101'
  }
}

Sample return data

{
   "buff_required" : 2903,
   "buff_supplied" : 1000000,
   "error_num" : 0,
   "return" : [
      {
         "station" : "HYDSYS01",
         "sections" : {
            "820001" : [
               {
                  "rl" : "8.620",
                  "chain" : "0.000",
                  "order" : 10,
                  "commnt" : ""
               },
               {
                  "rl" : "6.710",
                  "chain" : "19.000",
                  "order" : 20,
                  "commnt" : ""
               },
               ...
               {
                  "rl" : "7.480",
                  "chain" : "135.200",
                  "order" : 230,
                  "commnt" : ""
               },
               {
                  "rl" : "8.850",
                  "chain" : "139.690",
                  "order" : 240,
                  "commnt" : ""
               }
            ],
            "850006" : [
               {
                  "rl" : "8.620",
                  "chain" : "0.000",
                  "order" : 10,
                  "commnt" : ""
               },
               {
                  "rl" : "6.710",
                  "chain" : "19.000",
                  "order" : 20,
                  "commnt" : ""
               },
               ...
               {
                  "rl" : "7.480",
                  "chain" : "135.200",
                  "order" : 230,
                  "commnt" : ""
               },
               {
                  "rl" : "8.850",
                  "chain" : "139.690",
                  "order" : 240,
                  "commnt" : ""
               }
            ]
         }
      }
   ]
}}

 

get_groups

Return group membership details.

parameter

description

options

example

site_list

Hydstra site list expression

 

201001,201002

group_list

(optional) Only return membership details for these groups

 

 

Sample request

{
  'function' => 'get_groups',
  'version'  => 1,
  'params'   => {
    'site_list'  => 'HYDSYS01,HYDSYS02',
    'group_list' => ['catch','region','visits']
  }
}

Sample return data

{
   "buff_required" : 979,
   "buff_supplied" : 1000000,
   "error_num" : 0,
   "return" : [
      {
         "group" : "CATCH",
         "value" : "410",
         "value_decode" : "Murrumbidgee River Basin",
         "stations" : [
            "HYDSYS01"
         ],
         "group_decode" : "Station Catchment"
      },
      {
         "group" : "REGION",
         "value" : "1",
         "value_decode" : "Region 1",
         "stations" : [
            "HYDSYS01"
         ],
         "group_decode" : "Station Region"
      },
      {
         "group" : "VISITS",
         "value" : "AREA1",
         "value_decode" : "Area one",
         "stations" : [
            "HYDSYS02",
            "HYDSYS01"
         ],
         "group_decode" : "NT Grnd Water model"
      }
   ]
}

 

set_real_encoding

When JSonCall() was introduced, we decided to encode all “real” numbers (numbers with decimals) as strings. We did this to avoid “scientific notation” (eg 1E-5), which we thought Perl couldn’t handle (though it actually can). But since the primary use case was Perl, and Perl is not a strongly-typed language, it didn’t matter. Perl was quite capable of taking the string values returned in JSON, and interpreting them as real values.

Now that we are also support Python, a strongly-typed language, we need the ability to return real numbers encoded in JSON as proper “float” format values.

To avoid causing any unintended side-effects on the Perl world, if you take no action, the feature will not be activated – HYDLLP will behave as it always has – encoding real values as strings.

To allow maximum flexibility across use cases, you can enable the feature in two ways:

Across entire “session”

Calling this function (with the “FLOAT” parameter value) will switch HYDLLP to encoding real values as JSON-format floats. You can switch it back again by calling the function with a value of “STRING”.

The Hydstra hydllp.py Python module calls this function automatically, so there are very few cases where you would need to call this function yourself.

For single call only

To allow use cases like web services, the feature is also available on a call-by-call basis for all JSonCall functions. You simply include the optional “real_encoding” parameter in your JSON data, that the feature will be enabled for that call only.

parameter

description

options

example

real_encoding

How to encode real values in JSON?

string / float

201001,201002

Sample request

{
  'function' => 'set_real_encoding',
  'version' => 1,
  'params' => {
    'real_encoding' => 'float'
  }
}

Sample return data

{
  "error_num":0,
  "buff_required":54,
  "buff_supplied":1000000
}

 

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)

 

Lake Fido Storage

title_height

Font size of the title (optional but only used if title is specified, defaults to 15)

 

9

starttime

Plot start time

YYYYMMDDHHIIEE

19600221090000

endtime

Plot end time (optional if period and period_multiplier are provided)

YYYYMMDDHHIIEE

19600228090000

interval

Gather data from the trace every interval_multiplier * interval. For example interval_multiplier => 3 and interval => hour

second, minute, hour, day, week, month, year

hour

interval_multiplier

 

 

3

period

Period_multiplier * period defines the duration of the plot. Using these settings causes the X-Axis to display differently. (optional if endtime is provided)

second, minute, hour, day, week, month, year

hour

period_multiplier

 

 

159

show_lines

Displays lines in-between data points (optional, defaults to yes)

0 (false) 1 (true)

0

show_points

Displays a circle around data points (optional, defaults to no)

0 (false) 1 (true)

0

filled

Fills underneath the graph (optional, defaults to no)

0 (false) 1 (true)

1

invert

Changes the direction of the Y-Axis (optional, defaults to no)

0 (false) 1 (true)

1

background_color

The color inside the plot area (optional)

BBGGRR format or supported color literal (default: white)

$0000FF (or red)

background_gradient_color

If specified then the colour inside the plot area will shift from background_color (top) into background_gradient_color (bottom) (optional)

BBGGRR format or supported color literal (default: nothing)

$0000FF (or red)

show_bad_qual

If false then bad quality data won't be displayed by the plot (optional)

0 (false) 1 (true)  (default: 0)

1

grid_color

Sets the colour of the grid lines inside the plot area. Set to -1 to disable the grid lines.

-1, BBGGRR format or supported color literal (default: silver)

$0000FF (or red)

suppress_x_axis

If set to yes then this will remove the X-Axis from the plot.

0 (false) 1 (true)  (default: 0)

0

suppress_y_axis

If set to yes then this will remove the Y-Axis from the plot.

0 (false) 1 (true) (default: 0)

1

line_thickness

Lets you set the thickness of the trace line in pixels

 

2

trace_requests

An array of trace requests

see below

see below

 

trace request parameters

parameter

description

options

example

site

A Hydstra site

 

HYDSYS01

datasource

The Hydstra datasource

 

A

varfrom

Source variable

 

100.00

varto

Destination variable

 

140.00

trace_type

Data aggregation type

max: maximum point in period.

min: minimum point in period.

period: mean value in period.

mean: mean value in period.

cum: cumulative trace from period values.

tot: total cumulative value in period.

start: instantaneous value at the start of the period.

end: instantaneous value at the end of the period.

first: first point in the period if there are any.

last: last point in the period if there are any.

startpoint: value of point at period start if there are any.

endpoint: value of point at period end if there are any.

maxmin: max and min values in the period.

maxminpt: max and min points in the period if they exist.

point: stored points.

pointbnds: stored point with start and end values if they 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'           => 1,
        'show_points'          => 1,
        'filled'               => 0, #max and min trace types are bar graphs which are always filled.
        'invert'               => 0,
        'background_color'     => 'White',
        #'background_gradient_color' => 'transparent_color',
        'fill_color'           => '$FCFEFF',
        'fill_gradient_color'  => '$DEFAFF',
        #'transparent_color'   => 'White',
        'show_bad_qual'        => '1',
        #'grid_color'                => '-1',
        #'suppress_x_axis'           => 1,
        #'suppress_y_axis'           => 1,
        'trace_requests'       => [
        {
          'site'       => 'HYDSYS01',
          'datasource' => 'A',
          'varfrom'    => '100',
          'varto'      => '100.00',
          'trace_type' => 'max',
          'axis_align' => 'left',
          'color'      => '$C6BE6B',
          'bad_color'  => 'blue'
        },{
          'site'       => 'HYDSYS01',
          'datasource' => 'B',
          'varfrom'    => '100',
          'varto'      => '100.00',
          'trace_type' => 'min',
          'axis_align' => 'left',
          'color'      => '$CC6699',       
          'bad_color'  => 'blue'
        }]
      }
    ]
  }
}

Sample return data

{
   "buff_required" : 11605,
   "buff_supplied" : 1000000,
   "error_num" : 0,
   "return" : {
      "widgets" : [
         {
            "width" : "400px",
            "id" : "1",
            "height" : "400px",
            "base64_widget" : "iVBORw0KGgoAAAANSUhEUgAAAZAAAAGQCAIAAAAP3aGbAAAABnRSTlMA/wD/AP83WBt9AAAfR0lE\r\n
QVR42u2dSYwc53WAq0mK2Zw9lhFYMWJ7hrZpWV6kbDOke+AbaR94oWDkwtsQiBsgLwZ84JGHALyQ\r\n
{* Many more lines have been removed *}
QFgAYAaEBQBmQFgAYAaEBQBmQFgAYIb/B3fvE9skGvn2AAAAAElFTkSuQmCC"
         }
      ]
   }
}

 

 

weir

This section specifies the parameter set used by the weir widget.

parameter

description

options

example

widget_type

The type of widget

plotlet, weir, storage

weir

widget_width

The width of the returned image

 

200

widget_height

The height of the returned image

 

200

id

The id assigned to this widget for later reference

 

first weir

fill_color

The color outside the plot area (optional)

BBGGRR format or supported color literal (default: white)

$FF0000 (or blue)

fill_gradient_color

If specified then the colour outside the plot area will shift from fill_color (top) into fill_gradient_color (bottom) (optional)

BBGGRR format or supported color literal (default: nothing)

$0000FF (or red)

transparent_color

Transparent_color specifies which color should be made transparent. Anti-aliasing gets performed before the background can be made transparent by using transparent_color in place of a color value for any color parameter and if your transparent_color 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"
         }   
      ]
   }
}

 

 

get_recalculation_periods

Scans a time series trace for all “contributing” components that have been modified within a specified period, and produce a list of sub-periods thus affected.

The context in which this might be used is a script to send data incrementally to a third party, and each time you run the job you need to ask “what has been modified since the last time I ran this job?”

Change-contributors include the actual time series data itself, rating tables and time-based tables used as part of variable conversion.

parameter

description

options

example

site_list

A list of sites to process

201001,201003

datasource

The data source of the traces

 

A

var_from

The source variable of the traces

 

100.00

var_to

The converted variable of the traces

 

140

mods_from

The start date and time of the “window” of modification times.

 

20180320123000

mods_to

The end date of the modification windows, typically a far-future date.

 

21000101000000

Sample request

{
  'function' => 'get_recalculation_periods',
  'version'  => 1,
  'params'   => {
    'site_list'   => 'HYDSYS01',
    'datasource'  => 'A',
    'varfrom'     => '100.00',
    'varto'       => '140.00',
    'mods_from'   => '19800101000000',
    'mods_to'     => '21000101000000'
  }
}

Sample return data

{
   "buff_required" : 203,
   "buff_supplied" : 1000000,
   "error_num" : 0,
   "return" : {
      "sites" : [
         {
            "site" : "HYDSYS01",
            "latest_mod" : "20160913112400"
            "periods" : [
               {
                  "period_start" : "19290101000000",
                  "period_end" : "19860226101500"
               }
            ],
         }
      ]
   }
}

 

get_hybatch_env

returns a hash of the same HYBATCH environment information as is written by the HYBATCH program. This can allow scripts to perform some special case programming, with the convenience of HYDLLP rather than executing HYBATCHE.

parameter

description

options

example

batch_code

The HYBATCH section code

PRECOMP

site

The site of interest

 

HYDSYS10

datasource

The source variable of the traces

 

A

starttime

The converted variable of the traces

(optional)

20180201000000

endtimem

The start date and time of the “window” of modification times.

(optional, both missing means period of record)

20180301000000

Sample request

{
  'function' => 'get_hybatch_env',
  'version'  => 1,
  'params'   => {
    'batch_code'  => 'precomp',
    'site'        => 'HYDSYS01',
    'datasource'  => 'A',
    'starttime'   => '20180201000500',
    'endtime'     => '20180401000500'
  }
}]  

Sample return data (extract)

{
   "buff_required" : 7572,
   "buff_supplied" : 1000000,
   "error_num" : 0,                                          
   "return" : {
      "print" : "C:\\TEMP\\JUNK",
      "site.category15" : "",
      "vmend(140.02)" : "01/01/1987",
      "clearoutputs" : "yes",
      "rainhours" : "900",
      "site.timecreate" : "0",                                                                     
      "site.shortname" : "Hydstra Test Station",
      "site.elev" : "682",
      "stnini.stagerange" : "-0.05,3.0",
      "vwystart(220.00)" : "1938",
      "site.zone" : "55",
      "site.station" : "HYDSYS01",
      "latestrating3" : "-1",
      "site.latitude" : "-35.33527778",
      "site.category19" : "",
      "site.longitude" : "149.31388889",
      "vmend(100.00)" : "01/02/1986",
      "vmend(220.00)" : "01/01/1988",
      "vwystart(140.01)" : "1959",
      "vpstart(140.01)" : "01/01/1959",
      "site.hut" : "False",
      "latestratsite" : "0",
      "periodvar" : "100.00",
      "startwyear" : "2018",
      <…>
   }
}

 

authenticate_user

Check whether a supplied user ID and password is authenticated according to the PASSWD table. Note that no logging on is performed, just a simple authentication check.

parameter

description

options

example

user_id

The user id

JCITIZEN

password

The password

 

as_if

Sample request

{
  "function" : 'authenticate_user',
  "version"  : 1,
  "params"   : {
    "user_id"  : 'user2',
    "password" : 'pass2',
  }
}

Sample return data

{
   "return" : {
      "authenticated" : "true"
   },
   "error_num" : 0,
   "buff_supplied" : 1000000,
   "buff_required" : 86
}

 

get_template_list

Returns a list of available templated output applications. Templates are special automation files that live in a folder under INIPATH called TEMPLATE, with the ability for the caller to specify selected parameters. This allows applications to be run by the caller, without compromising security, as you can control

·         which applications are exported

·         which parameters may be modified

·         what values those parameters may take

This call has no parameters, though you must provide an empty “params” json element.

Sample request

{
  'function' => 'get_template_list',
  'version'  => 1,
  'params'   => {}
}

Sample return data

{
   "buff_required" : 900,
   "buff_supplied" : 1000000,
   "error_num" : 0,
   "return" : [
      {
         "params" : [
            {
               "name" : "site",
               "default" : "HYDSYS01",
               "validation" : "^[0-9A-Z_.]{1,20}$",
               "description" : "Site to plot"
            },
            {
               "name" : "startmonth",
               "default" : "1",
               "validation" : "^\\d+$",
               "description" : "Start month in year"
            },
            {
               "name" : "startyear",
               "default" : "0",
               "validation" : "^\\d\\d\\d\\d$",
               "description" : "Start year"
            },
            {
               "name" : "endyear",
               "default" : "0",
               "validation" : "^\\d\\d\\d\\d$",
               "description" : "End year"
            },
            {
               "name" : "printtype",
               "default" : "HTM",
               "validation" : "(^TXT$)|(^HTM$)",
               "description" : "Report Type"
            }
         ],
         "name" : "Daily Flow Report",
         "description" : "Report Daily flows for a year"
         "content":"&hyd-junkpath.template.&prm-printtype.",
         "type":"&prm-printtype.",
         "encoding":"base64"
      },
      {
         "params" : [
            {
               "name" : "site",
               "default" : "HYDSYS01",
               "validation" : "^[0-9A-Z_.]{1,20}$",
               "description" : "Site to plot"
            },
            {
               "name" : "plottype",
               "default" : "SVG",
               "validation" : "^PNG$|^SVG$",
               "description" : "Plot type to return"
            }
         ],
         "name" : "Simple Plot",
         "description" : "Plot period of record stage"
         "content":"&hyd-junkpath.template.&prm-plottype.",
         "type":"&prm-plottype.",
        "encoding":"base64"      }
   ]
}

 

get_template_output

Runs a templated output application and returns the output. Templates are named in the template path with any name and '.aut' extension, e.g.

\hyd\dat\ini\template\Flow Plot.aut

and called without the '.aut'.

Read up on HYDLLP Templated Output for more information on using templates from the DLL.

 

parameter

description

options

example

template_name

The name of the template, not including the '.aut' extension.

as returned by get_template_list

Flow Plot

template_params

An array of template parameter objects

 

 

name

(within a template_params item) the name of the parameter

Must be a parameter specified in the nominated template

site

value

(within a template_params item) the value you wish to specify for that parameter

Must match the validation regular expression in the template (if one is specified)

HYDSYS01

Sample request to call 'Simple Plot.aut' in inipath\template:

{
  'function' => 'get_template_output',
  'version'  => 1,
  'params'   => {
    'template_name' => 'Simple Plot',
    'template_params' => [
      {'name' => 'site',     'value' => 'hydsys01'},
      {'name' => 'plottype', 'value' => 'SVG'}
    ]
  }
}

Sample return data (with bulk removed to keep size down)

{
   "buff_required" : 37188,
   "buff_supplied" : 1000000,
   "error_num" : 0,
   "return" : {
     "type" : "SVG",
     "encoding " : "BASE64",
      "content" : "PD94bWwgdmVyc2lvbj0iMS4wIiBzdGFuZGFsb25lPSJubyI/Pg0KPCFET0NUWVBFIHN2ZyBQVUJMSUMg
      <…>
      IjkxNyIgeT0iNzExIiBmb250LXNpemU9IjEzIiBmb250LWZhbWlseT0iQXJpYWwiIGZpbGw9IiMwMDAw
   }
}

 

An additional series of Standard Hydstra calls are documented separately under Standard Hydstra Data Publication.

 

Return Codes

Here is a list of the return codes that various HYDLLP calls may return.

The JSonCall function returns the error number in the ‘error_num’ attribute, and a text description of the error in the ‘error_msg’ attribute:

{
   "buff_required" : 14200,
   "buff_supplied" : 50000,
   "error_num" : 121,
   "error_msg" : Incorrect version (2) for function get_db_info, (must be 1)

Italicised codes are only used by legacy functions (see below).

Value

Name

Explanation

0

OK

OK

10

STARTUPFAIL

Startup failed

11

SHUTDOWNFAIL

Shutdown failed

12

LOGINFAIL

Login failed

20

INVALIDSITE

Invalid station/suffix/variable

21

INVALIDDATE

Invalid date

22

INVALIDTIME

Invalid time

23

INVALIDSTARTEND

Start time > End time

24

INVALIDDATATYPE

Invalid data type, should be one of  Mean, Max, Min, Start, End, First, Last, Tot, MaxMin

25

INVALIDVARTO

Invalid varto

30

NORATINGTABLE

No rating table

31

RATINGTABLEOVER

Value over rating table

32

RATINGTABLEUNDER

Value under rating table

33

RATINGTABLEERROR

Error loading rating table

40

ENDOFDATA

End of data

41

ENDOFVARS

End of variables

42

ENDOFSTNS

End of stations

43

INVALIDHYSTNS

Invalid HYSTNS expression

44

ENDOFSUFFS

End of suffixes

45

ENDOFBLOCKS

End of blocks

50

PUTHYDFAIL

Time series writing failed

51

INVALIDOPENMODE

Invalid open mode, must be 0..5

52

INVALIDACTION

Invalid action, must be 0..6

53

INVALIDDATATRANS

Invalid datatrans, must be 1..7

54

INVALIDACTIONDT

Invalid action for datatrans

55

INVALIDQUALITY

Invalid quality, must be 1..254

56

INVALIDINTERVAL

Invalid interval, must be YEAR, MONTH,  DAY,  HOUR,  MINUTE or SECOND

57

INVALIDGEOFILTER

Invalid geo filter

59

TABLECANNOTREAD

Cannot read table because of an insufficient user level

60

TABLENOTEXIST

Table does not exist

61

TABLEALREADYOPEN

A table is already open (TableClose has not been called), 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 time-series file is locked

80

STDHYDINVALIDDATASOURCE

Invalid datasource

81

STDHYDINVALIDUNITCODE

Invalid unit code

82

STDHYDINVALIDTRACE

Invalid trace

83

STDHYDINVALIDSITE

Invalid site

84

STDHYDINVALIDSITELIST

Invalid site list

85

STDHYDINVALIDPARAMLIST

Invalid parameter list

86

STDHYDINVALIDGROUP

Invalid group

90

KIWISINVALIDTSLIST

Invalid time-series list

100

INVALIDFUNCNAME

Invalid function name, function name was not recognised

101

INVALIDHANDLE

Invalid object handle

120

INVALIDJSONDATA

Invalid JSON request string

121

UNSUPPORTEDVERSION

Unsupported function version

122

PARAMETERERROR

Missing/unsupported parameter(s)

123

INVALIDTABLEKEY

Invalid table key

124

UNHANDLEDEXCEPTION

Unhandled exception

125

NODATAINFILE

No data for specified variable in file

126

NODATAINPERIOD

No data within specified period

130

TEMPLATENOTFOUND

Template file not found

131

TEMPLATEBADPARAMS

Could not load parameters from template file

132

TEMPLATEMISSINGOUTPUT

Expected output from template application not found

140

TABLEDENIEDDATAPRIV

Cannot read table because it is denied due to data privacy settings

200

BUFFERTOOSMALL

Buffer too small

 

Exported Legacy Functions

Below is a list of legacy functions exported by HYDLLP.DLL, expressed in Delphi syntax. The main reason for using these routines is if you are upgrading an existing program from HYDLL to HYDLLP.

Please see HYDLL for more detailed information on how to use these entry points. However we strongly recommend that new programs should only use StartupEx, JSonCall, and Shutdown if possible.

VarConvert

Converts a value from one variable to another.

function VarConvert (
               aHandle     : integer;
               aStation    : pChar;
               aVarFrom    : Double;
               aVarTo      : Double;
               aTime       : pChar;
               aValue      : Double;
               aQuality    : Integer;
           var aOutValue   : Double;
           var aOutQuality : Integer)
                           : Integer; stdcall;

GetValue

Retrieves a TS data value or aggregate.

function GetValue (
               aHandle     : integer;
               aStation    : pChar;
               aSuffix     : pChar;
               aVarFrom    : Double;
               aVarTo      : Double;
               aStartTime  : pChar;
               aEndTime    : pChar;
           var aOutValue   : Double;
           var aOutQuality : Integer)
                           : Integer; stdcall;

GetValueEx

Retrieves a TS data value or aggregate, with some additional options.

function GetValueEx (
               aHandle     : integer;
               aStation    : pChar;
               aSuffix     : pChar;
               aVarFrom    : Double;
               aVarTo      : Double;
               aStartTime  : pChar;
               aEndTime    : pChar;
               aDataType   : Integer;
           {>} aOutTimeBuf : pChar;
               aOutTimeLen : integer;
           var aOutValue   : Double;
           var aOutQuality : Integer)
                           : Integer; stdcall;

DataType

Explanation

0 (Mean)

Mean (average) value in period

1 (Maximum)

Maximum value in period

2 (Minimum)

Minimum value in period

3 (Start)

Instantaneous value at start of period

4 (End)

Instantaneous value at end of period

5 (First)

First actual value in period. This may be different to a (possibly) interpolated value at the start of the period

6 (Last)

Last actual value in period. This may be different to a (possibly) interpolated value at the end of the period

7 (Total)

Total value in period

8 (MaxMin) *

Maximum and minimum values in period

GetValueStr

Retrieves a series of TS values and returns them in a long string.

NB: this form is only for backward compatibility with HYDLL calls, and is inefficient. Please use GetValueStrInit() and GetValueStrMore(), or better yet, JSonCall's get_ts_traces method.

function GetValueStr (
                 aHandle     : integer;
                 aStation    : pChar;
                 aSuffix     : pChar;
                 aVarFrom    : Double;
                 aVarTo      : Double;
                 aStartTime  : pChar;
                 aEndTime    : pChar;
                 aDataType   : Integer;
                 aInterval   : pChar;
                 aMultiplier : Integer;
                 aRelTimes   : integer;
             {>} aOutDataBuf : pChar;
                 aOutDataLen : integer;
             var aPointCount : Integer)
                             : Integer; stdcall;

GetValueStrInit

Initiates a retrieval run of TS values, but does not return them.

After a successful call to this one, use GetValueStrMore() to unload the values, buffer by buffer.

function GetValueStrInit (
                 aStation    : pChar;
                 aSuffix     : pChar;
                 aVarFrom    : Double;
                 aVarTo      : Double;
                 aStartTime  : pChar;
                 aEndTime    : pChar;
                 aDataType   : Integer;
                 aInterval   : pChar;
                 aMultiplier : Integer;
                 aRelTimes   : integer;
             var aPointCount : Integer)
                             : Integer; stdcall;

GetValueStrMore

Returns a buffer of values retrieved by GetValueStrInit().

You should call this repeatedly until aLoadCount is zero. The larger the supplied buffer, the fewer calls will be required.

function GetValueStrMore (
                 aHandle     : integer;
             {>} aOutDataBuf : pChar;
                 aOutDataLen : integer;
             var aLoadCount  : Integer)
                             : Integer; stdcall;

NextValue

Returns the next value after a call to GetValue().

After calling GetValue() you can call NextValue() as many times as you like, until the time becomes far future.

function NextValue (
               aHandle     : integer;
               aStation    : pChar;
               aSuffix     : pChar;
               aVarFrom    : Double;
               aVarTo      : Double;
           {>} aOutTimeBuf : pChar;
               aOutTimeLen : integer;
           var aOutValue   : Double;
           var aOutQuality : Integer)
                           : Integer; stdcall;

NextValueEx

Returns the next value after a call to GetValueEx().

After calling GetValueEx() you can call NextValueEx() as many times as you like, until the time becomes far future.

function NextValueEx (
               aHandle       : integer;
               aStation      : pChar;
               aSuffix       : pChar;
               aVarFrom      : Double;
               aVarTo        : Double;
           {>} aOutTimeBuf   : pChar;
               aOutTimeLen   : integer;
           var aOutValue     : Double;
           var aOutQuality   : Integer;
           var aOutDataTrans : Integer;
           {>} aOutCommentBuf: pChar;
               aOutCommentLen: Integer)
                             : Integer; stdcall;

TimeBounds

Returns the period of record for a nominated variable in a nominated TS file. The times are returned as Strtimes (yyyymmddhhiiee) if data is found, but zero if no data is found.

function TimeBounds (
               aHandle      : integer;
               aStation     : pChar;
               aSuffix      : pChar;
               aVarFrom     : Double;
           {>} aStartTimeBuf: pChar;
               aStartTimeLen: integer;
           {>} aEndTimeBuf  : pChar;
               aEndTimeLen  : integer)
                            : Integer; stdcall;

QualitySummary

Creates a multi-line quality summary string for a nominated TS data trace.

function QualitySummary (
               aHandle     : integer;
               aStation    : pChar;
               aSuffix     : pChar;
               aVarFrom    : Double;
               aStartTime  : pChar;
               aEndTime    : pChar;
           {>} aQualSummBuf: pChar;
               aQualSummLen: integer)
                           : Integer; stdcall;

NextVariable

Returns the next variable in a nominated TS file.

HYDLLP detects when you are calling this for the first time (or for the first time with a given site and datasource), and returns the first variable in the nominated file. You may call this repeatedly, until there are no more, in which case the return value is non-zero.

function NextVariable (
               aHandle  : integer;
               aStation : pChar;
               aSuffix  : pChar;
           var aVariable: Double)
                        : Integer; stdcall;

NextStation

Returns the next site in a site list expression.

HYDLLP detects when you call this with a new site list expression, so that you can make multiple calls to get each site.

A non-zero return code signifies that there are no more.

function NextStation (
               aHandle    : integer;
               aHyStns    : pChar;
           {>} aStationBuf: pChar;
               aStationLen: integer)
                          : Integer; stdcall;

NextSuffix

Returns the next archive or work class TS datasource for a given station.

HYDLLP detects when you call this with a new site, so that you can make multiple calls to get each datasource.

A non-zero return code signifies that there are no more.

function NextSuffix (
               aHandle   : integer;
               aStation  : pChar;
           {>} aSuffixBuf: pChar;
               aSuffixLen: integer)
                         : Integer; stdcall;

NextBlock

Returns information about the blocks for a given variable in a TS file.

HYDLLP detects when you call this with a new site / datasource / variable, so that you can make multiple calls to get each block.

A non-zero return code signifies that there are no more.

function NextBlock (
               aHandle   : integer;
               aStation  : pChar;
               aSuffix   : pChar;
               aVariable : Double;
           {>} aBlockBuf : pChar;
               aBlockLen : integer)
                        : Integer; stdcall;

ClearTSCache

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;

DecMsg

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

function DecMsg (
               aMessID      : pChar;
               aSubstParams : pChar;
           {>} aOutStrBuf   : pChar;
               aOutStrLen   : integer)
                            : integer; stdcall;

aMessID is the MSGID from the MESSAGES table.

aSubstParams is a list of comma separated strings that replace the %1, %2 and so on in the returned message text.

use strict;
require 'hydlib.pl';
use HydDLLp;
main:{
  my $dll=HydDllp->New();

  my $message=$dll->DecMsg("APP.HYCREATE.AUTOCOMLONG","first param","second param","third param");
 
  print($message);
}

In the above Perl example code the message "APP.HYCREATE.AUTOCOMLONG" gets translated into "Created by HYCREATE. %1 %2 from %3" and then the %# are replaced with the strings passed to aSubstParams resulting in the string "Created by HYCREATE. first param second param from third param".

TableOpen

Opens a database table for retrieval.

function TableOpen (
           aHandle    : integer;
           aTableName : pChar)
                      : integer; stdcall;

TableFilter

Applies a filter to an open database table.

function TableFilter (
           aHandle    : integer;
           aFieldList : pChar;
           aValueList : pChar)
                      : integer; stdcall;

TableOrder

Applies a named order to an open database table.

function TableOrder (
           aHandle    : integer;
           aOrderName : pChar)
                      : integer; stdcall;

TableEOF

Checks to see if an opened database table is sitting at the end of rows.

The aEofInt parameter will be true (non-zero) if the table is at EOF, and false (zero) if not.

function TableEOF (
               aHandle : integer;
           var aEofInt : integer)
                       : integer; stdcall;

Return Code

Explanation

0

Not at EOF

Other

At EOF

TableValue

Rerturns the string representation of a field in the current database table.

function TableValue (
               aHandle    : integer;
               aFieldName : pChar;
           {>} aValueBuf  : pChar;
               aValueLen  : integer)
                          : integer; stdcall;

TableNext

Moves the current database table to the next row.

function TableNext(aHandle : integer): integer; stdcall;

TableClose

Closes the current database table.

function TableClose(aHandle : integer) : integer; stdcall;

ADOConnection

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

function ADOConnection (
               aTableSpec       : pChar;
           {>} aConnectionStrBuf: pChar;
               aConnectionStrLen: integer;
           {>} aTableStrBuf     : pChar;
               aTableStrLen     : integer)
                                : integer; stdcall;

Using HYDDLLP from Perl

Updating Perl programs is usually simple. In your Perl you will find statements of the form:

use HydDll;
...
my $dll=HydDll->new()

All you need to do is add 'p' to these two locations (and any other HydDLL->new calls)

use HydDllp;
...
my $dll=HydDllp->new()

All delivered Perl programs under \HYD\SYS have already been amended to use HYDLLP. The only programs you might need to address will be in INIPATH.

If you are calling HYDLL from other languages it is somewhat more challenging to use HYDLLP as the calling sequences, types of parameters etc have changed. We provide an example spreadsheet HYDLLP Excel.JSON Example.Xlsm in \hyd\sys\misc\examples, as well as examples in other languages.

HYDLLP Calling Conventions from Other Languages

Calling convention

All functions in HYDLLP use the “stdcall” calling convention.

Return values

Every function returns a 32-bit integer as its return value.

Zero means the call was successful.

Some calls, particularly those that are intended to be called in a loop, use a non-zero return code to mean “no more”.

In most other cases, non-zero means that a problem was encountered. Further information can be gained by immediately through the ‘error_msg’ attribute or by calling DecodeError().

The aHandle parameter

The first call to HYDLLP should be StartUp() or StartUpEx(). These calls return to you (via an “out” parameter) a value valled aHandle. Many subsequent calls require that you pass in this handle as the first parameter. This allows HYDLLP to service calls coming from more than one user, or even parallel calls coming from the same user, but referring to different items (ie, tables, time series files). The aHandle parameter allows HYDLLP to keep the data items for each “caller” separate.

Time values

When a time value is stored in a Double-precision float, it uses the Hydstra “reltime” encoding, meaning the number of days since midnight on 01/01/1601.

If a time is stored in a string, it uses the Hydstra “string time” convention:

yyyymmddhhiiee

There are calls that can convert between the two if required.

pChar parameters

Parameters of type pChar are a pointer to an ascii character buffer (of 8 bit ANSI characters), and are used for specifying string values to a call ([in] parameters) and to return string information to the caller ([out] parameters).

In the list below, [in] parameters are unadorned, while [out] parameters have a {>} comment before the parameter name.

[Out] pChar parameters also have an associated xxxLen parameter following them, in which the caller declares the maximum length of the character buffer.

Integer parameters

Parameters of type Integer are standard 32-bit signed integers.

For [in] parameters, the declaration is unadorned.

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

Double parameters

Parameters of type Double are standard IEEE double precision floats.

For [in] parameters, the declaration is unadorned.

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

Logical/Boolean values

Boolean parameters and return values are specified as ‘true’ or ‘false’.

Calling HYDLLP from external applications

If you develop applications in VB, C#, Delphi or C++ etc, there are a few factors to bear in mind when calling HYDLLP.

Paths

HYDLLP needs to be run "in situ" - that is, in the hyd\sys\run folder (under your choice of "root location").  You can't copy it to a Windows directory, which you sometimes have to do with other DLLs.

Paths (again)

HYDLLP needs to access some other libraries (DLL and BPL) which live in RUNPATH.

Normally, if the application also lives in RUNPATH, they are found automatically, as they are in the "same" folder as the app.

But... when the HYDLL{x} is invoked from another app, somewhere else, that doesn't work - both "folder of current app" and "current working directory" are <> runpath!!!

According to the MSDN website, when Windows is asked to load a DLL, it searches through the following list:

1.                     The directory from which the application loaded.

2.                     The current directory.

3.                     The system directory. Use the GetSystemDirectory function to get the path of this directory.

4.                     The 16-bit system directory. There is no function that obtains the path of this directory, but it is searched.

5.                     The Windows directory. Use the GetWindowsDirectory function to get the path of this directory.

6.                     The directories that are listed in the PATH environment variable. Note that this does not include the per-application path specified by the App Paths registry key. The App Paths key is not used when computing the DLL search path.

And, if it can't find it, it will probably fall over in an uncontrollable (and uncatchable) manner.

Solution: call SetCurrentDirectory() to the known RUNPATH just before loading the COM object (and calling StartUpEx())

Paths (yet again)

When a Hydstra processes starts up (and loads HYCONFIG.INI) it tries to find out where all the Hydstra paths are.

Quote often, folk will have a sparse [Path Prefixes] section in HYCONFIG.INI, since the default behaviour is "find out the Hydstra root, then use the standard path underneath that".

As in the previous point, this means using the location of the running application - which for Hydstra apps means RUNPATH, but when an external DLL is involved, the location could be elsewhere, and the defaulting algorithm would turn out all wrong.

Solution: be more specific in your hyconfig.ini file:

[Path Prefixes]
\HYD\ = h:\hydstra\prod

DLLs and IDEs

According to Microsoft, once a COM interface is published, it is immutable.

According to Hydstra, things are a little more flexible. Although we try not to change individual calls, the server itself goes through lots of changes from release to release.

It is possible that some IDEs, when importing a COM object, will store some of that information, and compile it into the app.

If is possible that when a new version of the DLL is registered, the IDE will be out of whack.

Solution: remove/uninstall the COM object from the project, then reimport/install the new one