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:' + !path

At 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
                                    ENDIF

Whenever 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 included
    table=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, table

    Typical 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
    BACK TO API FUNCTIONS




     

    API Descriptions:




    obj_new, obj_destroy
     
    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, t1
    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.

    If  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.

    BACK TO API FUNCTIONS



     

    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'

    BACK TO API FUNCTIONS


    getParameter, getColumn, getArray
     

        r=t->getParameter('aNamedParameter')
        r=t->getColumn('aNamedColumn')
        r=t->getArray('aArrayName')
    Used for existing  data sets.

    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.

    BACK TO API FUNCTIONS



    getParameterNumber, getColumnNumber, getArrayNumber
     
    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=', r
    Used for existing  data sets.

    Returns the number of parameters, columns or arrays found when sdds_table object is created.

    BACK TO API FUNCTIONS


    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=', r

    Used 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.


    BACK TO API FUNCTIONS


    setParameterDefinition, setColumnDefinition, setArrayDefinition
     
     

    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}
    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 .

    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}
     
     

    BACK TO API FUNCTIONS


    setParameter, setColumn, setArray
     

    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', threedim
    Used for NEW  data sets.

    Assign 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.
     

    BACK TO API FUNCTIONS


    setRow

                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->writeTable

    Used 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.
     

    BACK TO API FUNCTIONS


    startTable, writeTable

                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.
     

    BACK TO API FUNCTIONS


    readTable

                    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.

    BACK TO API FUNCTIONS
     





     

    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.