The Lightweight API is designed to allow object-model access and customizing of the LIGO_LW format documents which are based on the XML( Extensible Markup Language ). More information about LIGO_LW format can be found in LIGO-T990023-01.
The Lightweight API is divided into two layers, the TCL layer and the C++ layer. The TCL layer is what the end-user "sees" -- they write code which the TCL layer executes. The C++ layer, on the other hand, is available only indirectly.
TCL provides a mechanism for extending the command-set by writing functions in C or C++. These functions are loaded into TCL as a shared object using the "package require" or "load" command. When this is done, the extended commands become available. The C++ layer consists of these extended commands and the memory space which they use to store and manipulate data.
In order to create C or C++ functions which TCL can understand, one must write them in a special format. In LDAS, this is handled by a program known as SWIG (Simplified Wrapper and Interface Generator). The SWIG program uses 1 or more SWIG interface files to create a set of C functions which TCL can understand. These functions are written to a source file (.c or .cc) which is then compiled into the shared object.
This document is divided into 3 areas:
The lightweight API creates LWDocument objects in the C++ layer which need to be manipulated by TCL. In order to do so, each of these objects must have a unique label. The pointer value of the object in the C++ layer is used as the label. This value is converted by SWIG into an ascii representation of the pointer with the format:
_xxxxxxxx_LWDocument_p
where 'xxxxxxxx' is a hexadecimal number representing the pointer value (it may have fewer than 8 characters). For example LWDocument object may appear as:
_555f0_LWDocument_p
A text-based LIGO_LW document is a hierarchical structure of elements. Each element is described by a content model within the DTD( Document Type Declaration ) that lists the subsidiary elements it can contain and attributes associated with it. LIGO_LW DTD can be found on the last page of the mentioned above document LIGO-T990023-01.
Here are some examples of LIGO_LW format elements as they may appear in a LIGO_LW document.
<AdcData Name="channel name::AdcData:GTimeS:GTimeN:Frame">
<Comment>comment</Comment>
<Param Name="crate" Type="int_4u">crate</Param>
<Param Name="channel" Type="int_4u">channel</Param>
<Param Name="nBits" Type="int_4u">nBits</Param>
<Param Name="bias" Type="real_4">bias</Param>
<Param Name="slope" Type="real_4">slope</Param>
<Param Name="units" Type="lstring">units</Param>
<Param Name="sampleRate" Type="real_8">sampleRate</Param>
<Time Name="timeOffset" Type="GPS">GTimeS.GTimeN</Time>
<Param Name="fShift" Type="real_8">fShift</Param>
<Param Name="overRange" Type="int_2u">overRange</Param>
<Param Name="dt" Type="real_8">dt</Param>
<LIGO_LW Name=":data:Container(Vect):Frame">
<Array Name="name" Type="type">
<Dim Units="units">dim</Dim>
<Stream Name="name" Type="locationType" Delimiter="delimiter">
...delimiter separated streamdata...
</Stream>
</Array>
</LIGO_LW>
</AdcData>
<LIGO_LW Name="channel name::AdcData:GTimeS:GTimeN:Frame:AdcData:XML" Type="TimeSeries">
<Comment>comment</Comment>
<Param Name="crate:Param:XML" Type="int_4u">crate</Param>
<Param Name="channel:Param:XML" Type="int_4u">channel</Param>
<Param Name="nBits:Param:XML" Type="int_4u">nBits</Param>
<Param Name="bias:Param:XML" Type="real_4">bias</Param>
<Param Name="slope:Param:XML" Type="real_4">slope</Param>
<Param Name="units:Param:XML" Type="lstring">units</Param>
<Param Name="sampleRate:Param:XML" Type="real_8">sampleRate</Param>
<Time Name="StartTime" Type="GPS">GTimeS.GTimeN</Time>
<Param Name="fShift:Param:XML" Type="real_8">fShift</Param>
<Param Name="overRange:Param:XML" Type="int_2s">overRange</Param>
<Param Name="Duration" Type="real_8">duration</Param>
<Array Name="arrayName:Array:XML" Type="type">
<Dim Units="units">dim</Dim>
<Stream Name="arrayName:Array:XML" Type="locationType" Delimiter="delimiter">
...delimiter separated streamdata...
</Stream>
</Array>
</LIGO_LW>
<Table Name="name">
<Column Name="name1" Type="type1"/>
<Column Name="name2" Type="type2"/>
<Column Name="name3" Type="type3"/>
<Stream Name="name" Type="locationType" Delimiter="delimiter">
...delimiter separated streamdata...
</Stream>
</Table>
The Lightweight API commands implement the following features:
Transfer of LWDocument objects between C++ and TCL layers:
Transfer of LWDocument objects through sockets:
Manipulation of LWDocument objects or their raw data in the C++ layer:
I/O:
Conversion between ILWD and LIGO_LW formats:
1.5.4