download
Usage
>> download <dataset_label>/<schedule_label>/<block> <count_key>=<count_value> <start_key>=<start_offset>
Security
Open.
Description
Reads all or part of a specified storage object. For the initial use of the download command, all parameters are required. When retrieving large amounts of information in 'blocks' using multiple instances of the command, parameters can be optional; this is discussed following the description of the parameters below.
<dataset_label>/<schedule_label>/<block> specifies the storage object to be retrieved. The specifier has three components:
<dataset_label> identifies the complete dataset corresponding to the deployment of interest, For a list of available datasets, use dataset list.
<schedule_label> identifies the sampling schedule used to acquire the data. For a list of available schedules, use dataset <dataset_label> schedulelist.
<block> is one of the three keywords data, events, or meta, and determines the type of data retrieved for the specified schedule.
It is important to understand that the “/” character is not just a separator; although it marks the boundaries between specification components, it also combines them into a single parameter. ensuring that they appear in the correct order with no other parameters in between.
When a source is specified, the <dataset_label> and <block> are required components; the instrument must know which dataset to read and what type of information is required. When retrieving a <block> of sample data, a <schedule_label> is also required; it is not possible to download sample data from multiple schedules with a single instance of the command.
When retrieving events or meta, a <schedule_label> should not be specified; these types of data can not be retrieved on a per-schedule basis, only for the entire deployment. Use one of <dataset_label>/events or <dataset_label>/meta.
<count_key> = <count_value> specifies the quantity of information that the instrument should attempt to retrieve and report. As well as introducing the <count_value>, the <count_key> also determines the 'units' in which the information will be measured:
The bytecount <count_key> indicates that the information is measured in bytes; this option is available for all three block types, data, events, and meta.
The samplecount <count_key> can be used only with the data block type, and indicates that the information is measured in samples.
The eventcount <count_key> can be used only with the events block type, and indicates that the information is measured in events.
Any transfer from a given storage object that uses multiple download commands must all use the same measurement units.
<start_key>=<start_offset> specifies an offset from the beginning of the storage object where reading should begin. It must be specified in the same units used for the <count_key>; one of bytes, samples, or events:
bytestart indicates that the starting point is specified in bytes.
samplestart indicates that the starting point is specified in samples.
eventstart indicates that the starting point is specified in events.
The first item stored in memory for this deployment always has <start_key>=0.
In all cases, if the requested amount of data would overrun the boundary of the target object, a valid transfer still occurs, but the amount of data actually returned will be less than the request. This is reflected in the instrument's response to the command.
The instrument responds with all parameter values it intends to use with this instance of the command. As with most commands, this response is terminated by a <carriage_return><line_feed> pair of characters. For example:
>> download <dataset_label>/<schedule_label>/data samplecount=<requested_sample_count>, samplestart=<start_sample_offset>
<< download <dataset_label>/<schedule_label>/data bytecount = <expected_byte_count>, samplecount=<expected_sample_count>, samplestart=<start_sample_offset>
The requested data then follows immediately, in binary format as it is stored in the instrument. Any multi-byte quantities are stored and transmitted least-significant-byte first.
Note that the count measurements reported in the response depend in part on how the retrieval was specified.
bytecount is a valid <count_key> for all three <block> types specified in the source, namely data, events, and meta. It is always reported in the response, and will always accurately reflect the number of bytes the instrument is attempting to return. This assists the host in knowing exactly how much data to expect, even if the count was specified in samples or events. Note that the 2-byte CRC appended to the transfer is NOT included in this count; the count indicates the quantity of information being returned from the logger’s memory, and does not take into account the transfer protocol used.
samplecount is a valid <count_key> only for <block> type data. It will be reported in the response only if specified in the command. For <block> types events and meta a samplecount is not valid and is never reported.
eventcount is a valid <count_key> only for <block> type events. It will be reported in the response only if specified in the command. For <block> types data and meta an eventcount is not valid and is never reported.
If data or events are requested using bytecount, the instrument can not guarantee that this will correspond to a whole number of objects (samples or events). If that is a requirement, use samplecount or eventcount instead; the bytecount reported in the response will then be accurate for the requested number of objects.
At the end of the data the instrument appends a CRC (cyclic redundancy check). This is a 16-bit CRC using the CCITT polynomial f(x)=x^16 + x^12 + x^5 + 1, feeding bytes into the generator LSB first and using 0xFFFF as a seed value. The bytes of the CRC computed by the instrument are swapped before appending to the data; this means that the host can include them in its CRC-check as an extra two bytes, and if the CRC is correct this always gives a result of zero. These two bytes are not included in the bytecount reported in the command’s response.
Using multiple instances of the command
When retrieving a large amount of information from the instrument, for the purpose of managing potential communications errors it is advisable to break the transfer into smaller amounts using multiple instances of the download command.
Transfers specified in bytes always use the byte values for these substitutions and calculations, regardless of whether they represent whole numbers of objects. For transfers specified in samples or events the correspondence between whole numbers of objects and bytes is exact.
Examples
>> download dataset_00/sched_CTD/data bytecount=32000 bytestart=0
<< download dataset_00/sched_CTD/data bytecount=32000 bytestart=0
<< <32000 bytes of sample data from the start of the specified schedule><CRC>
% The 1st part of a transfer of sample data from the schedule labelled sched_CTD, starting with the first byte.>> download dataset_00/meta bytecount=64000 bytestart=0
<< download dataset_00/meta bytecount=13584 bytestart=0
<< <13584 bytes of metadata associated with the entire dataset><CRC>
% A new request for all the metadata associated with the dataset. Again the number of bytes available is less than the requested number. The <schedule_label> portion of the source specification has been omitted, so metadata for all schedules as well as the whole instrument are included.>> download dataset_00/sched_CTD/data samplecount=2000 samplestart=0
<< download dataset_00/sched_CTD/data bytecount=56000 samplecount=2000 samplestart=0
<< <The first 2000 samples from the start of the specified schedule><CRC>
% Here is an alternative start to the transfer of sample data, this time using samples as the measurement unit.