Interface l3

Enumerate Open Modes

L3E_OPEN_NEW 0 create a new file that should not already exist
L3E_OPEN_OLD 1 read or write an existing file
L3E_OPEN_RDO 2 open an existing file as read only

Enumerate Data Types

L3E_NULL 0 no data
L3E_C1 1 char
L3E_C1ptr 2 pointer to char
L3E_I4 3 simple integer
L3E_I8 4 double integer
L3E_R4 5 simple float
L3E_R8 6 double float
L3E_I4ptr 7 pointer to simple integer
L3E_I8ptr 8 pointer to double integer
L3E_R4ptr 9 pointer to simple float
L3E_R8ptr 10 pointer to double integer
L3E_VOID 11 pointer to unknown

Enumerate L3 Flags

L3F_NONE 0x0000 empty flag, all values set to false
L3F_NULL 0xFFFF unsignificant flags value
L3F_WITHDATA 0x0001 get/set data into the node
L3F_WITHCHILDREN 0x0002 parse the children of the node
L3F_FAILSONLINK 0x0004 raises an error if link unreachable
L3F_FOLLOWLINKS 0x0008 follow links
L3F_MERGELINKS 0x0010 unused
L3F_COMPRESS 0x0020 unused
L3F_SKIPONERROR 0x0040 errors reported, process continues
L3F_NOALLOCATE 0x0080 no data allocation in L3
L3F_NOCHILDMERGE 0x0100 unused
L3F_LINKOVERWRITE 0x0200 link create/update overwrite existing
L3F_WITHMUTEX 0x0400 use mutexes
L3F_FILLNANDATA 0x0800 fill new data with NaN
L3F_XXX2 0x1000 unused
L3F_HASEXTFLAGS 0x2000 another set of flags is present
L3F_DEBUG 0x4000 set debug traces
L3F_TRACE 0x8000 set end-user trace

Enumerate L3 node release Flags

L3F_R_NONE 0x0000 empty flag, all values set to false
L3F_R_ALL 0xFFFF unsignificant flags value
L3F_R_HID_NODE 0x0001 release node hid_t s
L3F_R_MEM_CHILDREN 0x0002 free children list
L3F_R_HID_CHILDREN 0x0004 release children hid_t s
L3F_R_MEM_NODE 0x0008 release node itself
L3F_R_MEM_DATA 0x0010 actual data memory of node

Interface L3/Macro

L3M_HASFLAG


     
cursor L3_Cursor_t* Context to use
flag flag enum Flag to test

Return An integer, 1 if the flag is set, 0 if unset

L3M_SETFLAG


     
cursor L3_Cursor_t* Context to use
flag flag enum Flag to set

Return The flags as integer

L3M_UNSETFLAG


     
cursor L3_Cursor_t* Context to use
flag flag enum Flag to unset

Return The flags as integer

Interface L3/raw

L3_nodeCreate


     
ctxt L3_Cursor_t* Context to use
pid hid_t Parent node
node L3_Node_t* Node attributes to use

Return A successful creation returns the new node hid_t, -1 if failure

Remarks All node arguments are immediatly used and copied, it is then possibleto release L3_Node_t as the function returns

API C hid_t L3_nodeCreate(L3_Cursor_t *ctxt, hid_t pid, L3_Node_t *node);

L3_nodeUpdate


     
ctxt L3_Cursor_t* Context to use
node L3_Node_t* Node attributes to use

Return The parameter context is returned

Remarks The target node hid_t is in the L3_Node_t* If a value is NULL, or L3F_NULL for flags or L3E_NULL for data type,then previous node value is unchanged for this attribute

API C hid_t L3_nodeUpdate(L3_Cursor_t *ctxt,L3_Node_t *node);

L3_nodeRelease


     
node L3_Node_t** Pointer to L3 Node to release

Return Status

Remarks The target L3_Node_t is released depending on flags see ‘L3 node release Flags’ at the top of this fileThe node pointer is set to NULL

API C int L3_nodeRelease(L3_Node_t **nodeptr,int flags);

L3_nodeChildrenFree


     
node L3_Node_t** Pointer to L3 Node to release

Return Status

Remarks Release the children list of the L3 node and close the children hid_tsame as with flags: L3F_R_MEM_CHILDREN|L3F_R_HID_CHILDREN

API C int L3_nodeChildrenFree(L3_Node_t **nodeptr);

L3_nodeFree


     
node L3_Node_t** Pointer to node attributes to use

Return status -1 if failure

Remarks The target node should be passed as L3_Node_t** and is set to NULLafter the memory is released. Node data is kept untouched.The embedded hid_t of the node is released, it is no more valid

API C int L3_nodeFree(L3_Node_t **node);

L3_nodeFreeNoDecRef


     
node L3_Node_t** Pointer to node attributes to use

Return status -1 if failure

Remarks The target node should be passed as L3_Node_t** and is set to NULLafter the memory is released. Node data is kept untouched.The embedded hid_t of the node is NOT released, it is still valid

API C int L3_nodeFreeNoDecRef(L3_Node_t **node);

L3_nodeFree


     
node L3_Node_t** Pointer to node attributes to use

Return status -1 if failure

Remarks The target node should be passed as L3_Node_t** and is set to NULLafter the memory is released. Node data is released too.The embedded hid_t of the node is released, it is no more valid

API C int L3_nodeAndDataFree(L3_Node_t **node);

L3_nodeMove


     
ctxt L3_Cursor_t* Context to use
parent hid_t Parent node
newparent hid_t New parent node
name char* Name of the node to move
newname char* New node name

Return The new node id is returned

Remarks The move is performed by HDF5, check HDF5 docs for details.

API C hid_t L3_nodeMove(L3_Cursor_t *ctxt,hid_t parent,hid_t newparent,char *name,char *newname);

L3_nodeDelete


     
ctxt L3_Cursor_t* Context to use
parent hid_t Parent node
name char* Name of the node to delete

Return The parameter context is returned

Remarks The delete is performed by HDF5, check HDF5 docs for details.

API C L3_Cursor_t *L3_nodeDelete(L3_Cursor_t *ctxt,hid_t parent,char *name);

L3_nodeFind


     
ctxt L3_Cursor_t* Context to use
parent hid_t Parent node
path char* Path of the node to find

Return The hid_t of the node, -1 if failure

Remarks The nodeFind retrieves the hid_t of a node from its path.Forces the link traversal, even if FOLLOWLINKS is set to false

API C hid_t L3_nodeFind(L3_Cursor_t *ctxt,hid_t parent,char *path);

L3_nodeRetrieve


     
ctxt L3_Cursor_t* Context to use
id hid_t Node target id
node L3_Node_t* Pointer to allocated node to fill in

Return A L3_Node_t with target node attributes copies

Remarks The return value is allocated by the user and data should have correctdimensions. If node id is not found or if the context is bad a NULL value is returned.

API C L3_Node_t *L3_nodeRetrieve(L3_Cursor_t *ctxt,hid_t id,L3_Node_t *node);

L3_nodePrint


     
node L3_Node_t Node attributes buffer

Remarks Prints node attributes on standard output for debug/trace purpose

API C void L3_nodePrint(L3_Node_t *node);

L3_openFile


     
filename char* File name to handle
mode int Open mode
flags long Set of flags

Return A new L3_Cursor_t

Remarks The first function to call with L3 interface. All subsequent L3 callswould us the returned L3_Cursor_t as argument.Mode enumerate should be in Open Modes listFlags are a OR-ed list of values from L3 Flags

API C L3_Cursor_t *L3_openFile(char *filename,int mode,long flags);

L3_openHID


     
flags long Set of flags

Return A new L3_Cursor_t

Remarks The first function to call with L3 interface. All subsequent L3 callswould us the returned L3_Cursor_t as argument.The root id should be a valid HDF5 device.

API C L3_Cursor_t *L3_openHID(hid_t root,long flags);

L3_close


     
ctxt L3_Cursor_t* Context to close

Return Status int (1 is ok)

Remarks All cursor contents are released, cursor itself is released, pointer is set to NULL

API C int L3_close(L3_Cursor_t **ctxt_ptr);

L3_setFlags


     
ctxt L3_Cursor_t* Context to update
flags long Set of flags

Return Modified context

Remarks Sets the current context with the flags, all previous flagsare removed

API C L3_Cursor_t *L3_setFlags(L3_Cursor_t *ctxt,long flags);

L3_getFlags


     
ctxt L3_Cursor_t* Context to use
flags long* Pointer to the set of flags

Return Context itself

Remarks Gets the current context flags

API C L3_Cursor_t *L3_getFlags(L3_Cursor_t *ctxt,long *flags);

L3_nodeSet


     
ctxt L3_Cursor_t* Context to use
node L3_Node_t* Old node tu update or NULL
name char* Name string
label char* Label string
dims int* Dimensions array of data
dtype int Type of data
data void* Pointer to data array
flags int Set of flags

Return New node or updated node

Remarks A NULL value for node arg forces the creation of a new (returned) node.Dims array of int ends with a -1Data type should be an L3E_<DataType> enumerate

API C L3_Node_t *L3_nodeSet(L3_Cursor_t *ctxt,L3_Node_t *node,char *name,char *label,int  *dims,int dtype,void *data,int flags);

L3_nodeGet


     
ctxt L3_Cursor_t* Context to use
node L3_Node_t* Old node tu update or NULL
name char* Name string
label char* Label string
dims int* Dimensions array of data
dtype int* Type of data
data void* Pointer to data array
flags int* Set of flags

Return New node or updated node

Remarks Reads the node structure and fills the arguments with the values.

API C L3_Node_t *L3_nodeGet(L3_Cursor_t *ctxt,L3_Node_t *node,char *name,char *label,int *dims,int *dtype,void *data,int *flags);

L3_isSameNode


     
ctxt L3_Cursor_t* Context to use
id1 hid_t First HDF5 id
id2 hid_t Second HDF5 id

Return Status int (1 is ok)

Remarks Checks if different ids refer to the same HDF5 object.

API C int L3_isSameNode(L3_Cursor_t *ctxt,hid_t id1,hid_t id2);

L3_isLocalNode


     
ctxt L3_Cursor_t* Context to use
id hid_t HDF5 id

Return Status int (1 is ok, node is local)

Remarks CHecks if id is in the same file than root node, so that it is not a link

API C int L3_isLocalNode(L3_Cursor_t *ctxt,hid_t id);

L3_incRef


     
ctxt L3_Cursor_t* Context to use
id hid_t HDF5 id to keep

Return arg id

Remarks Increments the hid_t so that you can call l3_freeNode and still use id

API C int L3_incRef(L3_Cursor_t *ctxt,hid_t id);

L3_decRef


     
ctxt L3_Cursor_t* Context to use
id hid_t HDF5 id to release

Return void

Remarks Decrements the hid_t once you are finished with it

API C void L3_decRef(L3_Cursor_t *ctxt,hid_t id);

L3_isLinkNode


     
ctxt L3_Cursor_t* Context to use
id1 hid_t HDF5 id to check
file char* File name
name char* Node name

Return Status int (1 is ok)

Remarks Checks if a node is a link. If yes, the file name and the node nameof the target of the link are copied into the user-allocated strings.

API C int L3_isLinkNode(L3_Cursor_t *ctxt,hid_t id,char *file,char *name);

L3_node2Path


     
ctxt L3_Cursor_t* Context to use
id hid_t HDF5 target node
path char* Char buff to fill with resulting path

Return Path char*

Remarks Finds a path from the file root to the target node.If path is NULL then the function allocates a char buffer, it is to theuser application to release the memory of this buffer. If the path is notNULL, the user has to provide enough memory for the function.

API C char *L3_node2Path(L3_Cursor_t *ctxt,hid_t id,char *path);

L3_path2Node


     
ctxt L3_Cursor_t* Context to use
path char* Path to search for

Return hid_t found node

Remarks Finds a node id in the file from a path.

API C hid_t L3_path2Node(L3_Cursor_t *ctxt,char *path);

L3_initDims


     
dims int* Array of dimensions
d1 int Dimensions one...
dn int ... up to last dimension

Return Arrays of dimensions

Remarks Fills the array with the dimensions and fills the rest with -1.If the arg dims is NULL, the returned array is allocated and has to bereleased by the userIf it is not NULL, the user has to insure that the array size isat least number-of-dimensions + 1 (last value should be -1)

API C int *L3_initDims(int *dims,int d1,...);

L3_initData


     
dims int* Array of dimensions
data void* Pointer to data
dtype int Type of data
arglist data type variable arguments

Return Pointer to data

Remarks Fills the array with variable arguments

API C void *L3_initData(int *dims,void *data,int dtype,...);

L3_fillData


     
dims int* Array of dimensions
data void* Pointer to data
dtype int Type of data
arglist data type variable arguments

Return Pointer to data

Remarks Fills the array with variable arguments

API C void *L3_fillData(int  *dims,void *data,int dtype,...);

L3_typeAsStr


     
dtype int Data type

Return String type

Remarks Returns the string type corresponding to the int enumerateReturns NULL if the integer is not found.

API C char *L3_typeAsStr(int dtype);

L3_typeAsEnum


     
dtype char* Data type

Return Integer enumerate data type

Remarks Returns the integer enumerate type corresponding to string type.Returns -1 if the string type is not found.

API C int L3_typeAsEnum(char *dtype);

L3_config


     
p int Parameter

Return Parameter

Remarks Unused

API C int    L3_config(int p);

Interface CHL/raw

CHL_printError


     
ctxt L3_Cursor_t* Context to use

Return None

Remarks Prints the message for the last error recorded in the context.

API C void CHL_printError(L3_Cursor_t *ctxt);

CHL_setError


     
ctxt L3_Cursor_t* Context to use
err int Error code
arglist ... Variable argument list

Return None

Remarks Sets the last context error to error given as argument.The variable argument list should fit with the corresponding error messagearguments are used to fill % formated stringSee the error tables headers: each entry has an integer as key, then anenumerate to set the level of severity and then the string for the message itself.

API C void CHL_setError(L3_Cursor_t *ctxt,int err,...);

CHL_getError


     
ctxt L3_Cursor_t* Context to use

Return Error code int

Remarks Gets the last context error

API C int CHL_getError(L3_Cursor_t *ctxt);

CHL_setMessage


     
ctxt L3_Cursor_t* Context to use
msg char* Message to use

Return Error code int

Remarks Sets the error message

API C int CHL_setMessage(L3_Cursor_t* ctxt,char *msg);

CHL_getMessage


     
ctxt L3_Cursor_t* Context to use

Return Error message string

Remarks Gets the error message

API C char *CHL_getMessage(L3_Cursor_t* ctxt);

CHL_addLinkSearchPath


     
ctxt L3_Cursor_t* Context to use
path char* Path string to add

Return Index of path in the list int

Remarks Adds the given path in the link search path

API C int CHL_addLinkSearchPath(L3_Cursor_t* ctxt,char *path);

CHL_getFileInSearchPath


     
ctxt L3_Cursor_t* Context to use
file char* Target file

Return Index of path in the list int

Remarks Searches the file in the link path link list, return the index of firstpath where the file was found.Returns -1 if the file was not found.

API C int CHL_getFileInSearchPath(L3_Cursor_t *ctxt,char *file);

CHL_freeLinkSearchPath


     
ctxt L3_Cursor_t* Context to use

Return int status

Remarks Removes all path entries

API C int CHL_freeLinkSearchPath(L3_Cursor_t* ctxt);

CHL_delLinkSearchPath


     
ctxt L3_Cursor_t* Context to use
path char* Path to remove

Return Index of path in the list int

Remarks Removes the path from path list if found.The index entry is released but may be re-used by next add.Returns -1 if the path was not found.

API C int CHL_delLinkSearchPath(L3_Cursor_t* ctxt,char *path);

CHL_getLinkSearchPath


     
ctxt L3_Cursor_t* Context to use
index int Position in the list

Return Path string

Remarks Returns the path in the index entry of link path search listReturns NULL if the index entry is empty

API C char *CHL_getLinkSearchPath(L3_Cursor_t* ctxt,int index);

Error Codes

3000 - File ‘<filename>’ not found (read only mode)

3001 - File ‘<filename>’ not found (modify mode)

3002 - Create file ‘<filename>’ fails

3003 - Update file ‘<filename>’ fails

3004 - Open file ‘<filename>’ as read only fails

3010 - Unknown file mode (integer=<filename>)

3011 - Property list fails for ‘file’

3012 - Property list fails for ‘link’

3013 - Property list fails for ‘group’

3017 - L3 HDF_Add_DataArray DataType not found in this node

3018 - L3 HDF_Set_DataArray DataType not found in [<nodename>]

3019 - L3 HDF_Get_DataArray DataType not found in this node

3020 - No data to get in this node

3021 - No data to set in this node

3022 - Create root fails while trying H5Gopen2

3023 - Create root fails while trying to add HDF5 MotherNode

3024 - Create root fails while trying to add Root Node

3025 - Create root fails while trying to set MT

3026 - Create root fails while trying to set format

3027 - Create root fails while trying to set version

3030 - Bad nodeCreate cannot create node [<nodename>]

3031 - Bad nodeCreate cannot add name attribute [<attributename>]

3032 - Bad nodeCreate cannot add ‘label’ attribute

3033 - Bad nodeCreate cannot add ‘datatype’ attribute

3034 - Bad nodeCreate cannot add data

3035 - Bad nodeCreate empty data in non-MT node

3036 - Bad nodeCreate cannot add flags

3040 - Bad nodeMove source/destination is a link

3041 - Bad nodeMove cannot change name attribute

3050 - Bad nodeUpdate cannot update a link

3051 - Bad nodeUpdate bad node id

3052 - Bad nodeUpdate cannot change name on [<nodename>]

3053 - Bad nodeUpdate cannot update label on [<nodename>]

3054 - Bad nodeUpdate cannot update dtype on [<nodename>]

3055 - L3 nodeUpdate cannot update data on [<nodename>]

3056 - Bad nodeUpdate cannot update flags on [<nodename>]

3060 - Bad nodeLink parent already is a link

3061 - Bad nodeLink cannot create node [<nodename>]

3062 - Bad nodeLink cannot add name attribute [<nodename>]

3063 - Bad nodeLink cannot set LK type

3064 - Bad nodeLink cannot set empty label

3070 - Bad nodeDelete bad parent node id

3080 - Bad nodeFind path too long (<pathsize> chars)

3081 - Bad nodeFind bad parent node id

3090 - Bad nodeRetrieve bad node id

3091 - Bad nodeRetrieve link not found

3092 - Bad nodeRetrieve node to return not allocated

3093 - Bad node2Path invalid node id [<id>]

3100 - L3 context is NULL