CEFLIB IDL API for Windows (2017/06/30)

This is a beta release, comments are welcome.

New in version 1.8.1 (2016/06/24)

  • Modifications in the Python API interface, in order to allow the use of the library from both Python 2.x and Python 3.x

  • Thanks to Thomasz KLOS from CAA team, who incorporate these changes.

New in version 1.8.0 (2016/03/19)

Updated Matlab API

  • Minor internal changes on Matlab API to ensure compatibility with Matlab 2016a.

  • This release is mandatory if you are using latest Mac OSX "El Capitan".

  • You will have also to download the latest Matlab 2016a version

  • And probably upgrade to Xcode 7.2.

Updated C and Python API

As needed by Thomasz KLOS, member of CAA teem, the C and Python API have been updated to give the ability of reading only the CEF metadata.

A new function has been added in the Python interface :

ceflib.read_metadata (filename.cef)

This function parse the content of CEF header, to allow further metadata queries, without reading data records, to improve performances.

New in version 1.7.3 (2014/02/20)

Minor changes, due to internal usage :

  • Adding a new fonction to LIB/src/LISTS.c :

    char *Join_list (t_list *, char * sep);
  • Modification of the generation process of IDL CEFLIB DLM :

    CEFLIB/IDL/bin/idl_cef.dlm

New in version 1.7.2 (2013/09/27)

A bug was discovered by Nataliya Bourrel, when building the CEFLIB C API in a Fedora 19 computer, that embed the zlib.1.2.7 package.

Changes were necessary in the zlib interface (module ZZLIB).

  • LIB/inc/ZZLIB.h

  • LIB/src/ZZLIB.c

  • C/src/CEF.c

New in version 1.7.1 (2013/09/04)

Bugs solved on Mac OSX

If the library was extracted on a case insensitive file system, a conflict between local and system header files occurs, and make the building process fail.

Some header files had to be renamed.

Another problem should occur while building the library.

You will need to update manually the mexopts.sh scripts delivered with MATLAB, as indicaed in Known bugs

CEFLIB Python Interface (Beta testing)

It’s now possible to call the CEFLIB from Python, using numpy package to handle multi-dimensionnal arrays.

Plots can be done using matplotlib package, that gives plot capabilities similar to Matlab.

This is a preliminar release for this language, and the interface should evolve in the future to become more Pythonic.

Handling BYTE data type

The library was not able to handle variables with VALUE_TYPE = BYTE.

This bug was found by A. Masson while readind a CEF file, generated with Qtran translator from CSDS CDF Prime Parameter file.

The BYTE data type was defined in the "Cluster Exchange Format" document, but not present in the "CAA Metadata dictionnary".

The library has been updated to take in account this datatype.

Handling CEF files generated on Windows

The library was modified in order to allow reading of CEF files generated on Windows,
with CR + LF (0x0C + 0x0A) end of line terminators.

It’s actually not possible to read CEF files generated on old MacOS systems,
using CR (0x0C) end of line terminators.

Other

An older bug corrected in CEFLIB/Makefile but not yet redelivered.

New features in version 1.6

Solving bug on 64 bits architecture

The LIB/Makefile and CEFLIB/Makefile have been modified to solve a bug found when building libraries on a 64 bits architecture.

The flag -fPIC has been added while compiling C source files, to create relocable functions

Converting ISO_TIME variables into ISO_TIME strings

The function Milli_to_isotime() has been added in both IDL and MATLAB interface.

This function accepts 2 parameters :

  • an ISO_TIME or ISO_TIME_RANGE CEF variable, scalar or array (coded in milli-seconds from 1958)

  • an integer in range 0..6, giving the number of fractionnal seconds digits expected

The return value is an ISO_TIME string (or array of strings)

Changes on the MATLAB interface

This delivery makes easier the use and setup of the CEFLIB interface.

You have just to modify the startup.m script file delivered in the MATLAB directory, and copy in your usual Matlab working directory (or insert in your usual startup file).

New features in version 1.5

Multi-valued attributes

Variable attributes with multiple values are now allowed in the CEFLIB.

The functions cef_gattr (global-attribute) and cef_vattr (variable, attribute) have been updated, in both IDL and MATLAB interface, and now return :

  • a string value if the attribute has an unique value

  • a list of string values in the case where attribute has multiple ones

Examples :

cef_vattr ("b_vec_xyg_gse", "VALUE_TYPE") => "FLOAT"
cef_vattr ("b_vec_xyz_gse", "REPRESENTATION_1") => [ "x", "y", "z" ]

The functions cef_gattributes (global-attribute) and cef_vattributes (variable) have also been updated, for both IDL and MATLAB interface:

  • Previously, they were returning a list of (attribute, value), for each attribute of a given variable.

  • Now, they just return the list of the attributes names

ISO_TIME_RANGE

The ISO_TIME_RANGE datatype is now handled by the CEFLIB, and data is returned as a two fields structure { START, STOP }

As other time-tags values, ISO_TIME_RANGE are internally coded in milli-seconds from 1958, and can be converted into others IDL or MATLAB base times values using :

  • MILLI_TO_JULIAN () : returns fractional Julian days (IDL interface)

  • MILLI_TO_EPOCH () : returns CDF Epoch milli-seconds (IDL interface)

  • CEF_DATE () : returns fractionnal days from 1-Jan-0000 (MATLAB interface)

Commas now allowed in string variables

String CEF variables and metadata attributes can now contain commas.

Example :

CATDESC = "Quality flag : 1 = Known problems, 2 = Survey data, 3 = Good, 4 = Excellent"

It’s also allowed to use " in ' delimited strings, and ' in " delimited strings.

Examples :

ENTRY = "9th Workshop in King's College"
ENTRY = '500 Gb 2.5" disk'

New features in version 1.4

Include files

The possibility to handle include files while reading CEF files has been added, to allow parsing files containing lines as below :

INCLUDE = CL_CH_MISSION.ceh

However, it’s necessary to specify one or several directories where to find such include files.

This can be specified by using the CEFPATH environment variable (as for other CAA’s tools).

Syntax :

# ksh, bash environment
$ export CEFPATH=/home/CAA/INCLUDE:/home/CIS/INCLUDE:/home/FGM/INCLUDE
# csh, tcsh environment
$ setenv CEFPATH /home/CAA/INCLUDE:/home/CIS/INCLUDE:/home/FGM/INCLUDE

Include files can be nested: for example a CEF header file describing the content of a dataset, included in each dataset data file, can use another INCLUDE directive to include mission or instrument metadata description.

Unfortunately, include files cannot actually be zipped files.

Handling missing data type

The DOUBLE data type was not allowed previous releases of the CEFLIB.

This functionality has been added.

Known limitations

Examples files

Examples script files for IDL and MATLAB have not been updated specifically for CEFLIB V1.5.

Some of them should work whereas other will fail if they are using the updated functions :

  • cef_gattributes ()

  • cef_gattr ()

  • cef_vattributes ()

  • cef_vattr ()

Some CEF examples files used in these scripts are also delivered, whereas others are not.

Variable names

Actually, the variable names are truncated before the __<dataset>.

If you desagree with this usage, you can edit the CEFLIB/src/CEF.c file and replace the following line :

#define TRUNCATE

with :

#undef  TRUNCATE

The C interface functions used to access to a given variable are case insensitive, and consequently the IDL and MATLAB interface have the same behaviour.