APPLICATION PROGRAM INTERFACE
IDL / SDDS
sddsIDL
Description
This API (sddsIDL) provides the capability for an IDL program to read and write SDDS formatted files. The API is implemented as an IDL object, sdds_table, whose methods implement the API functionality. The sdds_table interface methods which are used in an IDL application program are documented here.This API has only been tested on a Solaris 2.x operating system.
The user is expected to be familiar with SDDS formatted files.
Usage
A dynamic library, libsddsIDLLib.so, is provided for use by the API. The location of the dynamic library must be set in the LD_LIBRARY_PATH environment variable.An IDL module, sdds_table_define.pro, which implements the sdds_table IDL object is provided. The location of the object ( sdds_table) implementation code must specified in the IDL system variable !PATH. !PATH is initialized from the environment variable IDL_PATH when IDL starts, and can be changed once in IDL as follows:
!path = '/net/epics/sddsIDL:' + !pathAt the start of an application program then following IDL command should be included to compile the sdds_table object.
.run sdds_table_define.pro
Errors
All errors in the API are reported by the MESSAGE procedure. The application program should specify an action by the ON_ERROR procedure or the CATCH mechanism. Using this technique the application program need not check each sdds_table method call for an error return. An error message is placed in the system variable !ERROR_STRING. An example of what might be used in the application follows:
CATCH, error_status
IF error_status NE 0 THEN BEGIN
PRINT, 'API Error Message: ', !ERR_STRING
RETURN
ENDIFWhenever an sdds_table object is instantiated the validity of the object must be checked as follows:
dataSet = OBJ_NEW('sdds_table', 'neds.sdds')
if OBJ_VALID(dataSet) then PRINT, 'It worked'
API Functions:obj_new, obj_destroy getParameterDefinition, getColumnDefinition, getArrayDefinition getParameter, getColumn, getArray getParameterNumber, getColumnNumber, getArrayNumber getParameterNames, getColumnNames, getArrayNames setParameterDefinition, setColumnDefinition, setArrayDefinition setParameter, setColumn, setArray, setRow startTable, writeTable readTable
Typical API Sequence For Writing :
NOTE: ... notation means detail not includedtable=obj_new('sdds_table', 'old.sdds', /NEW, /BINARY)
if ( NOT obj_valid(table) ) then MESSAGE, 'table not created'
table->setParameterDefinition, ...
table->setColumnDefinition, ...
table->setArrayDefinition, ...
table->startTable, ...
table->setParameter, ...
table->setColumn, ...
table->setArray, ...
table->writeTable
table->setParameter, ...
table->setColumn, ...
table->setArray, ...
table->writeTable
obj_destroy, tableBACK TO API FUNCTIONSTypical API Sequence For Reading:
table=obj_new('sdds_table', 'old.sdds', /BINARY)
if ( NOT obj_valid(table) ) then MESSAGE, 'table not created'
r1=table->getParameterNumber( )
r2=table->getColumnNumber( )
r3=table->getArrayNumber( )
r4=table->getParameterNames( )
r5=table->getColumnNames( )
r6=table->getArrayNames( )
r7=readTable( )
r8=table->getParameter(...)
r9=table->getColumn(...)
r10=table->getArray(...)
r7=table->readTable( )
r8=table->getParameter(...)
r9=table->getColumn(...)
r10=table->getArray(...)
obj_destroy, table
API Descriptions:
obj_new, obj_destroy
Creates an IDL 'sdds_table' object. Initializes internal data structures for reading or writing. The /NEW switch is used for writing new files. The /BINARY switch is used for binary files as opposed to ASCII files.t=obj_new('sdds_table','check.sdds')
if obj_valid(t), print, 'It worked'
t1=obj_new('sdds_table','test.sdds',/NEW,/BINARY)
if obj_valid(t1), print, 'It worked'
obj_destroy, t
obj_destroy, t1If reading an existing file, the names and number of the parameters, columns and arrays is also retrieved and stored internally.
The created object must be checked for validity before being used.
Any object created must be destroyed. Destroying an object clears up any dynamic memory allocated and cleans up internal structures.
getParameterDefinition, getColumnDefinition, get ArrayDefinition
r=t->getParameterDefinition('aParameterName')
print, r.DESCRIPTION
r=t->getColumnDefinition('aColumnName')
print, r.UNITS
r=t->getArrayDefinition('aArrayName')
print, r.TYPE
Used for existing data sets.
Returns a IDL structure defining a named parameter, a named column or a named array. The structures are:
For parameter: {NAME:' ', SYMBOL:' ', UNITS:' ', DESCRIPTION:' ', FORMAT_STRING:' ', FIXED_VALUE:' ', TYPE: ' '}
For column: {NAME:' ', SYMBOL:' ', UNITS:' ', DESCRIPTION:' ', FORMAT_STRING:' ', TYPE: ' ', FIELD_LENGTH:0l}
For array: {NAME:' ', SYMBOL:' ', UNITS:' ', DESCRIPTION:' ', FORMAT_STRING:' ',:' TYPE: ' ', GROUP_NAME:' ', FIELD_LENGTH:0l, DIMENSIONS:0l}The TYPE is one of the string constants:
'DOUBLE'
'FLOAT'
'LONG'
'SHORT'
'STRING'
'BYTE'
getParameter, getColumn, getArray
r=t->getParameter('aNamedParameter')Used for existing data sets.
r=t->getColumn('aNamedColumn')
r=t->getArray('aArrayName')For parameters returns a scalar parameter of the proper type.
For columns returns a vector of the proper length and type.
For arrays returns an array of the proper dimensions and type. Up to 4 dimensions supported.The application program can query the size, type, and dimensions of the returned variable with
the IDL functions n_elements(r) and/or size(r).The API function readTable() MUST be issued before these functions may be called.
getParameterNumber, getColumnNumber, getArrayNumber
Used for existing data sets.r=t->getParameterNumber()
print, 'number of parameters in t=', r
r=t->getColumnNumber()
print, 'number of columns in t=', r
r=t->getArrayNumber()
print, 'number of arrays in t=', rReturns the number of parameters, columns or arrays found when sdds_table object is created.
getParameterNames, getColumnNames, getArrayNames
r=t->getParameterNames()
print, 'names of parameters in t=', r
r=t->getColumnNames()
print, 'names of columns in t=', r
r=t->getArrayNames()
print, 'namesof arrays in t=', rUsed for existing data sets.Returns a vector containing the names of parameters, columns or arrays found when sdds_table object is created. If no names are found, returns a blank string ' '. To differentiate between a single
name returned and a blank string, the application should first use the functions getParameterNumber, getColumnNumber and getArrayNumber to determine how many names were found.
setParameterDefinition, setColumnDefinition, setArrayDefinition
Defines a new parameter, column, or name to be included in the sdds file. Only the NAME element of the structure passed as a parameter to the IDL procedure must be specified since defaults are provided for all other possible structure elements. The possible elements for parameters, columns and arrays are shown below together with default values .t1->setParameterDefinition, {NAME:'aParameterName'}
t1->setParameterDefinition, {NAME:'aa',TYPE:'STRING'}
t1->setParameterDefinition, {NAME: 'aaa',TYPE:'STRING',FIXED_VALUE:'a comment'}
t1->setColumnDefinition, {NAME:'aColumnName'}
t1->setColumnDefinition, {NAME:'b',TYPE:'SHORT',DESCRIPTION:'a short'}
t1->setArrayDefinition, {NAME:'aArrayName'}
t1->setArrayDefinition, {NAME:'c',TYPE:'FLOAT',DIMENSIONS:3l}For parameter: {NAME:' ', SYMBOL:' ', UNITS:' ', DESCRIPTION:' ', FORMAT_STRING:' ', FIXED_VALUE:' ', TYPE: ' DOUBLE'}
For column: {NAME:' ', SYMBOL:' ', UNITS:' ', DESCRIPTION:' ', FORMAT_STRING:' ', TYPE: ' DOUBLE', FIELD_LENGTH:0l}
For array: {NAME:' ', SYMBOL:' ', UNITS:' ', DESCRIPTION:' ', FORMAT_STRING:' ',:' TYPE: ' DOUBLE', GROUP_NAME:' ', FIELD_LENGTH:0l, DIMENSIONS:2l}
setParameter, setColumn, setArray
Used for NEW data sets.d=2.12D
t1->setParameter, 'aParameterName', d
st='Run 11'
t1->setParameter, 'aa', st
dvector=[11D, 2.2D, 3.3D]
t1->setColumn, 'aColumnName', dvector
svector=[1, 2, 3]
t1->setColumn, 'b', svector
twodim=make_array(2,4,/DOUBLE,VALUE=1.1D)
t1->setArray, 'aArrayName', twodim
threedim=make_array(3,4,/FLOAT,/VALUE=1.1)
t1->setArray, 'c', threedimAssign values to previously defined parameters, columns or arrays
The startTable procedure MUST be called prior to these procedures.
The writeTable procedure MUST be called to write page to disk after values are assigned.
a=obj_new('sdds_table', 'row_ascii.sdds', /NEW)
a->setColumnDefinition, {NAME:double}
d=[1.1D, 2.2D, 3.3D, 4.4D]
a->startTable
for i=0, n_elements(d)-1 do a->setRow, 'double', i
a->writeTableUsed for NEW data sets.
Assign a value to a specified row of a data table. The column variable name and row number are specified in the call. Must be preceeded by a call to startTable.
a=obj_new('sdds_table', 'row_ascii.sdds', /NEW)
a->setColumnDefinition, {NAME:double}
d=[1.1D, 2.2D, 3.3D, 4.4D]
a->startTable, 4
for i=0, n_elements(d)-1 do a->setRow, 'double', i
a->writeTable
Used for NEW data sets.
The startTable procedure is used in preparation for placing data into a table in a new data set. The call can specify the number of expected rows in the data table. If not specified, a default value of 10 is used for the number of expected rows. This call MUST be made before any values are assigned to values in the data table. May be called repeatedly to proceed to the next table in the data set.
Thw writeTable procedure causes the current data table to be written to file.
a=obj_new('sdds_table', 'existing.sdds', /BINARY)
r=a->readTable(2)
if r EQ -1 then print, "No more pages left in data set'Used for existing data sets.
Reads a new table from a data set. Specifies as a parameter the page to read. Pages start with the number 1. If the
page number to read is not specified, the next page is read. Returns the page read; or if the EOF has been reached, returns a -1.
API Documentation and Examples:
The API documentation (i.e. this document) is located in a subdirectory 'doc' of the distribution directory.Examples used for documentation and testing are located in a sbbdirectory 'examples' of the distribution directory.