BEAT-II IDL

The BEAT-II IDL interface consists of handful of functions that allow the user to easily ingest, analyze, compare, and manipulate data from product files.

This page describes how to use the functions that are provided by the BEAT-II IDL interface.

Contents

• Named Structures
  • BEATL2_ERROR
• Functions and Procedures
  • BEATL2_APPEND
  • BEATL2_EXPORT
  • BEATL2_FIND_COLOCATED_DATA
  • BEATL2_GETOPT
  • BEATL2_IMPORT
  • BEATL2_INGEST
  • BEATL2_IS_ERROR
  • BEATL2_SETOPT
  • BEATL2_SLICE
  • BEATL2_UNLOAD
  • BEATL2_VERSION

Named Structures

The BEAT-II IDL interface defines one 'named structure', which is discussed below.

The BEATL2_ERROR named structure

The BEATL2_ERROR may be returned by any BEAT-II IDL function to indicate that the operation failed for some reason. Despite the name, you should think of a BEATL2_ERROR as a 'status report' of the last BEAT-II IDL call; the status may, in fact, indicate successful completion.

For example, the BEATL2_EXPORT function will always return a value of type BEATL2_ERROR, even when the operation succeeds.

The BEATL2_ERROR has two fields. The ERRNO field gives a numerical error code. This code is guaranteed to be either 0 (zero), indicating success, or a negative number, indicating failure.

The MESSAGE field is a STRING that provides a human-readable description corresponding to the ERRNO field. Some errors originate from the underlying BEAT-II C library or even the BEAT-I C Library that the BEAT-II IDL interface uses, others are specific to IDL (for example, if you try to pass incorrect parameters to a BEAT-II IDL function or procedure).

Functions and Procedures

Function BEATL2_APPEND(...)

With BEATL2_APPEND you can append two BEAT-II records in the main dimension. The first two parameters should be BEAT-II records that need to be of the same type. The third parameter is optional, and, if specified, should be a string specifying the dimension (a sub-dimension of the main dimension) in which to append. If you do not provide the dimension option the main dimension is used.

The function will return an anonymous (unnamed) IDL structure containing the BEAT-II record with the appended data or a BEATL2_ERROR structure in case an error occured.

More information about BEAT-II records can be found in the BEAT-II Data Description documentation.

Function BEATL2_EXPORT(STRING format, STRING filepath, ...): BEATL2_ERROR

With BEATL2_EXPORT you can export a BEAT-II record, which should be passed as the third parameter, to the file that is specified by 'filepath'. The 'format' parameter is used to indicate the kind of export format that should be used. Possible values are:

• ASCII
• BINARY
• NETCDF
• HDF4
• HDF5

If the export file already exists it will be overwritten.

Function BEATL2_FIND_COLOCATED_DATA(...)

With the BEATL2_FIND_COLOCATED_DATA function you can find co-located data for two BEAT-II records matching time, geolocation, and/or altitude. The first two parameters should be the records for which the co-located data should be found. The thirth, fourth, and fifth parameters should be respectively the time, radial, and altitude distance.

In order for the co-location to work both records need to have at least two similar fields to match on (time, latitude, longitude, and altitude). Each of these fields that are in a record need to be one dimensional and its dimension must be the "measurements" dimension.
If both records have a valid time field then the time distance (distance in seconds) parameter is used to match the time values.
If both records have valid geolocation fields (latitude and longitude) then the radial distance parameter (which represents an earth surface distance in km) is used to match the geolocation values.
If both records have a valid altitude field then the altitude distance parameter (in km) is used to match the altitude values.
The final result is the intersection of the results for each of the fields. This means that the result is two records that only contain the measurements that lie within the given distances. The first of these records (the one corresponding with the first function parameter) is passed as return value of the function. The second result record can be retrieved using the keyword RECORD2 (e.g. RESULTRECORD_1 = BEATL2_FIND_COLOCATED_DATA(INPUTRECORD_1, INPUTRECORD_2, -1, 100, -1, RECORD2=RESULTRECORD_2).

If a distance parameter is negative then no comparison will be performed for the associated property. If the function is unable to perform any comparisons (because all distance parameters are negative) the function will treat this similar to the situation where it could not find co-located data.

More information about BEAT-II records can be found in the BEAT-II Data Description documentation.

Function BEATL2_GETOPT(option_name: STRING): INT

The BEATL2_GETOPT function returns the numerical value of a BEAT-II IDL option. The following options are supported:

option name	possible values	default value	meaning
Verbose	0 or 1	1	if set, the BEAT-II IDL interface will echo 'error' return values to the IDL command line just before returning them to the IDL user level. This can be helpful in detecting problems.

Function BEATL2_IMPORT(STRING format, STRING filepath)

BEATL2_IMPORT will import the record stored in the file that is specified by 'filepath'. You should specify the format of the file with the 'format' parameter. Possible values for format are:

• ASCII
• BINARY
• NETCDF
• HDF4
• HDF5

The function will return an anonymous (unnamed) IDL structure containing the BEAT-II record or a BEATL2_ERROR structure in case an error occured.

Function BEATL2_INGEST(...)

With BEATL2_INGEST you can read data from one or more product files.

The first parameter should be a string containing the full path (or relative path with respect to the current working directory) of the product file you want to ingest. If you want to ingest multiple files just provide a string array of filepaths. However, in that case all product files should be of the same product type or the ingestion will fail.

The second parameter, which is optional, is the filter parameter. With this filter parameter you can specify restrictions on the amount of data that will be ingested form the product file(s). The filter should be a single string containing a ',' or ';' separated list of filter options.

The function will return an anonymous (unnamed) IDL structure containing the ingested BEAT-II record or a BEATL2_ERROR structure in case an error occured.

More information about BEAT-II records can be found in the BEAT-II Data Description documentation.

Function BEATL2_IS_ERROR(...): INT

The BEATL2_IS_ERROR function takes one argument; it returns a value of TRUE (1) if and only if

• the argument is a BEATL2_ERROR structure
• its ERRNO field is not equal to zero

If either of these is not true, BEATL2_IS_ERROR returns FALSE (0).

Using BEATL2_IS_ERROR, you can make your BEAT-II IDL programs robust (i.e., resistant to failures). If you test the result of any BEAT-II IDL call with BEATL2_IS_ERROR, you should be able to intercept any error.

Function BEATL2_SETOPT(option_name: STRING, new_value: INT): INT

The BEATL2_SETOPT function is used to set the BEAT-II IDL option to a new value. See the BEATL2_GETOPT description above for a list of allowed options and values, and their associated meanings.

The BEATL2_SETOPT function will return the previous value of the option.

Function BEATL2_SLICE(...)

The BEATL2_SLICE function can be used to shrink a BEAT-II record to a subrange of its data. The first parameter should be the BEAT-II record that needs to be sliced. The second parameter is optional and, if present, should be to a string containing the dimension name (which should be a sub-dimension of the main dimension) in which the slice should take place. The final parameter should be a range of integers representing the indices (with regard to the given dimension) of the elements that should be kept.

The function will return an anonymous (unnamed) IDL structure containing the sliced BEAT-II record or a BEATL2_ERROR structure in case an error occured.

More information about BEAT-II records can be found in the BEAT-II Data Description documentation.

Procedure BEATL2_UNLOAD

The BEATL2_UNLOAD procedure will unload the BEAT-I data-dictionary from memory.

BEATL2_UNLOAD will clean up any BEAT-II resources. At the first call to a BEAT-II IDL function or procedure the BEAT-II C Library will be initialized which will create a full representation of the BEAT-I data dictionary in memory (which can be a few megabytes in size). A call to BEATL2_UNLOAD will clean up any BEAT-II resources and thus also remove the data dictionary. After a clean up, the first call to a BEAT-II IDL function will initialize the BEAT-II C Library again.

This function may be (slightly) useful on systems with little memory. You could ingest a product file and then unload the data dictionary to free an extra megabyte of memory before starting data-processing. Other than that, this function is of little practical use.

Function BEATL2_VERSION(): STRING

The BEATL2_VERSION function returns a string containing the current version number of BEAT.