| |
|
|
|
2 USER's GUIDE
2.1 OVERVIEW
OSLX is intended to be used for handling the following common VLT data types:
The classes to handle these data types are only mentioned shortly here; a more thorough description of the behaviour and the methods provided by the individual class can be found in the man-pages enclosed in this document.
A Tcl library, slxtcl, is provided for handling of setup keywords in connection with user interfaces. For more about this issue see section 2.20.
2.2 THE INS ENVIRONMENT
OSLX is relying on the INS directory structure as defined in [1].The INS Specification defines the following environment variables
The following conditions apply for the various File Types recognized by OSLX:
2.3 NEW HEADER FOR SHORT-FITS FILES
From the MAY97 Release, the old format for the Short-Fits File Header (using keywords with category "SUP.") is no-longer used. It has been replaced by the so-called PAF Header. The format of the PAF Header is defined in [3].
OSLX still is capable of reading in the old format and convert it on-the-fly to the new format. However when files are stored the new format is used.
2.4 INHERITANCE FOR PAF FILES
OSLX supports inheritance for PAF Files. Using the keyword PAF.INCLUDE in the PAF Header it is possible to include other PAF Files into the one currently being loaded. With the inheritance scheme it is possible to make trees of PAFs like the one shown in figure 2.1. The big advantage of the inheritance is to avoid redundancy which makes the maintenance of PAF Files cumbersome.
Figure 2.1: Tree of PAF Files obtained using the PAF.INCLUDE keyword.
The rules for including other PAFs are as follows:
1. It is possible to include several files into one PAF (Multiple Inheritance). This is done simply by repeating the PAF.INCLUDE keyword with the various files to load. It is not necessary to index the keyword.
3. It is possible to re-define values of keywords defined in a parent. Parameters overidden will automatically be stored when saving PAF file (Parameter Overiding).
4. It is Possible to specify to store included keys when saving. Default is that included keywords are not stored.
Note, for generic PAFs (using the oslxSHORT_FITS Class), included PAFs must be located in a path given by the environment variable INS_USER_PATH, and the possible extension given with the filename.
2.5 THE TEMPLATE INHERITANCE SCHEME
2.5.1 Introduction
The number of Templates1 for a VLT instrument may become quite big. This in particular if the design is based on having a large number of specialized Templates with only a few parameters that can be adjusted by the user. Using a scheme like this has the advantage of diminishing the probability for erroneous parameter settings during the P2PP session, and at the same time making it easier for the user to prepare his observation run, without having him to worry about setting many parameters for each Template.
The Template Extension described in this paper makes it possible to have a huge number of Templates without having any redundant information, like repeated parameters in Template Signature Files. The big advantage of the scheme is that the maintenance of the Templates for an instrument becomes much easier and less time consuming.
2.5.2 The Basic Concept
The main problem of having many Templates is that the keyword definitions in the TSFs will have to be repeated again and again - not to mention the maintenance of all the Tcl procedures. The Template Extension makes it possible to inherit parameters from Parent Templates to Child Templates.
The implementation is fairly simple, and is based on 5 extensions to the current definition of TSFs:
· In the PAF Header of the TSF it is possible to include other TSFs using the "PAF.INCLUDE" keyword. These inclusions can be recursive so that the Parent TSF again includes other TSFs.
· In a Child TSF it is possible to assign values to Template parameters. These values will then be fixed for that Child Template and the user cannot change them from the P2PP Tools, in fact, the P2PP will not even show these values to the user. A new keyword "<keyword>.VALUE <value>", e.g., "DET.WIN1.NX.VALUE 100", is used to fix the value of a keyword.
· Template parameters fixed at a higher level can be overloaded with new values in Child TSFs inheriting from the TSF which had fixed the keyword with a certain value.
· Values of Templates Parameters having been fixed in a Parent Template, can be `unset' by assigning it the value "_tpl_undefine_", e.g.: "DET.WIN1.NX.VALUE _tpl_undefine_". In this case the "<keyword>.VALUE" will not appear in the final TSF.
· A Template parameter can be suppressed completely by given it the value "_tpl_suppress_", e.g.: DET.WIN1.NX.VALUE _tpl_suppress_". In this case the whole definition of that keyword in the TSF is omitted. If at a later stage the value is changed the keyword record for that key will re-appear.
These extended TSFs must have the extension ".tsfx" to distinguish them from the `normal' TSFs.
The Template sequence itself (Tcl procedure), can make use of a `rich' set of parameters making it possible to re-use it by setting these parameters/switches to various values. Such a set of a Template Sequencer (Tcl-procedure) together with a TSFX file is referred to as Master Template in the following. Note the term Master Template is not a term defined elsewhere, and is only used in the following to illustrate the usage of Template Inheritance.
Figure 1 illustrates the concept. The first thing to do is to group the Templates defined in a way so that one Master Template can provide the features of each Child Template in its group. A tree of the templates starting from the Master Template should be made to give an overview of the Templates.
Figure 1: Organizing the Templates for an instrument.
Note that it is only the TSFs that is actually inherited and exist as a set of independent files. The Tcl procedure only exists once for each branch in the inheritance tree. However, for the user it looks as though there are many different templates to choose from. In a TSFX the Sequencer script to use is specified as "TPL.PRESEQ <template name>". Note this normally only needs to be specified once in the Master Template, since it is inherited by the Child Templates.
It is possible for a Child TSF to inherit from several parents if appropriate.
A typical example where this can be used is for instruments with two detectors. For instance at the first level after the Master Template the key selecting arm could be fixed to a certain value which is then used in all the child templates.
Using the TSF Extension, introducing a new feature or fixing a bug in a Template Tcl procedure, only needs to be done in one place. The changes are then propagated down through the Template Tree.
Example of parts of the actual contents of TSFXs is shown in Figure 2. In Figure 2.A part of a Master TSF is shown. Figure 2.B shows how a Child Template fixes values of the Master TSF. Figure 2.C, shows a Child TSF overloading values previously put to a fixed value, and fixing again others.
Figure 2: Contents of the Template Signature Files.
2.5.3 VLT-SW-NOV97 Support
The implementation described in the following will be supported by the VLT-SW from the NOV97 Release.
OSLX supports the handling of TSFs via the class oslxTSF. Also the OSLX Server and the OSLX Shell provide from within the VLT Sequencer Wish Shell the features to handle the TSFs. Finally a tool, "oslxCompileTsf" is provided to compile TSFXs into plain TSFs. The usage of this tool is as follows:
% oslxCompileTsf <file> [<file>] -o <output directory> [-dictionary <dic>]
where one of more files can be specified, also as e.g. "sotpl*". The output directory could e.g. be specified as "~/vlt/sotpl/tsf". If no Dictionary is specified all Dictionaries found in the INS Tree will be loaded. Otherwise one or more Dictionaries can be specified according to the standard conventions for SLX/OSLX.
Figure 3: The handling of TSFs
2.5.4 Organizing the Source Data
When working with the Template Inheritance it is advantegeous to have a directory in the template module dedicated to the source TSFs (*.tsfx files). The directory structure of the template module could thus contain (at least) the following directories:
The compiled TSFs (target TSFs ".tsf") are then stored into the "tsf" directory whereas the source TSFs (".tsfx") are stored in the tsfx directory. Note, the OSLX TSF Compiler would not allow to overwrite an existing source TSFX.
2.6 USAGE OF OSLX FOR INS APPLICATIONS
OSLX is provided as a set of classes in a library and as a server process (OSLX Server) that can be executed on RTAP. The library is implemented in C++ and can thus only be used from C++ code. The OSLX Server provides the same features as the classes through a command interface. It then becomes possible to use the OSLX features from panels and from plain C code.
2.7 USING OF OSLX WITHOUT CCS
OSLX is supported also for operation without the availability of CCS. It must then be compiled with the compilation flag "NOCCS=t" set, and applications using the OSLX Library must set this flag. Using OSLX without CCS requires that the modules MISC and SLX have been compiled with the NOCCS flag set. Besides the OSLX Library a socket-based server process is also provided.
2.8 OSLX IN THE VLT SEQUENCER WISH/SHELL SHELLS
OSLX is available from within the Sequencer Wish/Sequencer Shell shells. It is a loadable extension which means that in order to use it the following must be executed from the Tcl script:
The command to use from the Tcl shell is called "seq_oslxCmd" and has the following input parameters:
seq_oslxCmd <command> <parameter> ?<instanceId> ?<arguments>?
where the <command> is one of the commands available for the OSLX Server e.g. SHOFITS (see man oslxSERVER), the <parameter> is one of the parameters available for that command, e.g. "-load". The instance ID is a name allocated by the user. Any name can be used. When a new instance name is specified, and new instance is automatically allocated in the OSLX Server. The arguments are the ones listed in connection with the parameter used as specified for the OSLX Server.
2.9 OSLX SHELL
OSLX proivdes a class oslxSHELL containing a method "CmdParser()" which gives access to the complete OSLX functionality. The interface for the oslxSHELL::CmdParser() is similar to the one of the OSLX Server. The oslxSHELL class has been developed to integrate OSLX into the Tcl Shell. In order to get the liboslxShell library, the compilation flag OSLXSH=t must be specified.
2.10 SINGLE KEYWORDS - CLASS oslxKEYWORD
The class oslxKEYWORD is used to handle a single keyword in memory and to perform various manipulation on these.
This class is used in the other OSLX classes for holding information about the current keyword being processed.
A keyword can be loaded into the object using the methods SplitKeyword() that splits a keyword line into its basic components, and SearchKeyword() that searches for a keyword in a file or in an SLX Dynamic Buffer.
The components of a keyword line can be accessed (set or read) using the methods String(), Logical(), ..., Category(), etc.
A new keyword can be built from the information currently stored in the object using the method BuildKeyword().
2.11 ALIAS CONVERSION - CLASS oslxALIAS
To make it more convenient for user's to enter setup keywords by hand, the VLT Instrument Common SW permits the usage of Aliases; see [2] for format and usage. The oslxALIAS class makes it possible to load an Alias Conversion Table into memory and to convert setup keywords in the Short- or Normal FITS format back and forth between the alias representation and the actual keyword.
2.12 CONFIGURATION FILES - CLASS oslxCONFIG
The class is provided to handle the three different kinds of Configuration Files. Each time a new Configuration files is loaded into the object, the object is first cleared. I.e. it is not possible to merge Configuration Files.
Note that the implementation in this release provides a quite basic functionality. I.e., there are currently no methods to check a Setup File against a certain Instrument Configuration, nor is it possible to check a certain Instrument Configuration Files against the Reference Configuration File. There will be more support in this area in a later release.
Maximum number of configuration keywords possible to use are 8191.
2.13 DATA INTERFACE DICTIONARIES - CLASS oslxDICTIONARY
The class oslxDICTIONARY provides an on-line version of a dictionary for a specific context. The class uses an internal Hash Table for the keywords to enable a fast access even when huge dictionaries are used.
It is possible to merge several Dictionaries into one object of the oslxDICTIONARY object, by setting the "merge" flag TRUE in the oslxDICTIONARY::LoadDic() method. In addition it is possible to load and merge all Dictionaries found in the INS Tree into one instance if "ALL" is specified as the name of the Dictionary.
2.14 KEYWORD FILTER - CLASS oslxKEYW_FILTER
The oslxKEYW_FILTER class is used to filter out certain keywords from an oslxSETUP or an oslxFITS instance. One instance of the OSLX Keyword Filter can contain an arbitrary number of subfilters. When filtering out keywords, the match between each keyword and each of these subfilters will be checked until a match is encountered or all subfilters have been employed. It is also possible to specify Strict Matching (oslxKEYW_FILTER::SetStrictFiltering(TRUE)) whereby all Sub-Filters must match.
The most convenient way of building up a filter, is to use the method AddSymbolicFilter(). It allows to enter Sub-Filters in the format
[<value> <operator>] <keyword> [<operator> <value>]
where the <value> can be a string, a logical (T|F), an integer, or a double value. The <operator> can be either "=", "<", ">", ">=" or "<=".
-> select files containing the DET.DIT keyword with value in the range from 10
to 20.-> select files containing keywords with the DET.CHIP.NAME set to the specified value.
Note, a Dictionary must be available before symbolic filters can be entered. The SetDictionary() method can be used to make an instance refer to an external Dictionary.
Using the methods AddFilter() Sub-Filters can also be added in the following way:
It is possible to filter also on the values of keywords. A value can be given either as a single value or as a range. The latter is not applicable for logicals. The end intervals are included in the range.
2.15 SHORT-FITS FILES - CLASS oslxSHORT_FITS
With the class it is possible to handle Short-FITS Files in a generic manner. In order to enable OSLX to locate these files, the path where they are stored must be contained in the environment variable INS_USER_PATH. Also the keywords in the Context Specific Short-FITS files must be defined in the Dictionary for the context.
It is possible to instruct the class methods to preserve comments that appeared before each keyword in a PAF File loaded. For obtaining this, the flag "saveComments" must be set TRUE for the methods oslxSHORT_FITS::Save()/SaveAs().
2.16 SETUP FILES AND KEYWORDS - CLASS oslxSETUP
The Setup Class provides all the methods necessary for handling Setup Files and setup keywords in memory. The proper operation of the class requires the availability of a Dictionary which can be made available with the SetDictionary() method. An on-the-fly check of setup keywords can be performed before storing these in the local setup buffer of the object. The check modes provided are
The following other features are provided
2.16.1 Example: Receiving/Sending off a CCS SETUP Command Message Buffer
The following example shows how to initialize the oslxSETUP class, how to process an incoming SETUP command message, and to sent a new SETUP command with the keywords in the object. Note that an external Dictionary is used rather than loading a Dictionary directly into the object.
// Load Dictionary and an Alias Table
if (diction.LoadDic("ISAAC") == FAILURE)
if (setup.LoadAliasTable("ISAAC") == FAILURE)
// Parse the SETUP message buffer. New setup keywords are merged into the local
if (setup.HandleSetupCmd(buffer) == FAILURE)
if (setup.NoMoveFlag() == TRUE)
... do required actions when No Move specified ...
if (setup.CheckFlag() == TRUE)
... perform the required check ...
if (setup.MakeMsgBuf() == FAILURE)
if (msgSendCommand(..., setup.SetupMsgBuf(), setup.SetupMsgBufLen(),
2.16.2 Example: Usage of the oslxSETUP Change Record
... initialize OSLX Dicitonary and OSLX Alias instances ...
oslxSETUP setup(&dictionary, &aliasTable);
... receive SETUP Command CCS Message ...
// Parse the SETUP message buffer
if (setup->HandleSetupCmd(buffer) == FAILURE)
// Make CCS Message buffer from the Change Record, i.e. only take only the keywords
if (setup->MakeMsgBufChRec() == FAILURE)
if (msgSendCommand(..., setup->SetupMsgBuf(), setup->SetupMsgBufLen(),
2.16.3 Example: Extraction of Selected Keywords
... load Dictionary + Alias Conversion Table ...
// Adjust a filter to extract only Detector Catagory keywords
filter.AddFilter("DET", "", "", "*");
filter.AddFilter("DET", "*", "", "*");
filter.AddFilter("DET", "*", "*", "*");
// Extract keywords for DCS these are packed into the local message buffer
if (setup->MakeMsgBuf(&filter) == FAILURE)
... send off CCS SETUP command ...
2.16.4 Example: Saving Keyword in a Setup File
... load Dictionary + Alias Conversion Table ...
// Adjust a filter to extract only Detector Catagory keywords
filter.AddFilter("DET", "", "", "*");
filter.AddFilter("DET", "*", "", "*");
filter.AddFilter("DET", "*", "*", "*");
// Save the keywords matching the filter in the Setup File,
// $INS_ROOT/$INS_USER/IMAGING/SETUPFILES/DET/mySetupFile.det
if (setup.SaveAs("mySetupFile", setupHeader, FALSE, &filter) == FAILURE)
2.17 DATA FILE FITS HEADER - CLASS oslxFITS
There are two classed that handles imagefiles. The original class oslxFITS provides methods for:
The class oslxFITS_EXT also provides the functionality of the oslxFITS class and besides it is enhanced with the following functionality:
The oslxFITS class is kept for back compatibility reason. Examples for the usage of this class are supplied in sections 2.17.1 and 2.17.2
For the new applications the users are suggested to use the oslxFITS_EXT class described in the next section 2.18 .
When compiling together the FITS file it is important for the oslxFITS user to make sure that enough space has been allocated to the primary header. If the primary header does not have enough of allocated space it will be necessary for OSLX to shift all data and images "below" the primary header. To avoid unnecessary shifting of large images in the FITS file a new warning is reported in the logMonitor if the primary header does not have enough allocated space.
2.17.1 Example: Creating a New Data FITS File using oslxFITS
if (diction.LoadDic("ALL") == FAILURE)
// Reset the object (does not delete the keywords in the object)
// Create a new FITS file with the number of FITS blocks (each 2880) requested.
// Write the END keyword. The filename will be:
// $INS_ROOT/$INS_USER/DETDATA/newDataFile.fits.
if (fits.CreateFile("newDataFile", 5, TRUE) == FAILURE)
// Store the data in the file after the header
if ((filePtr = fopen(fits.FitsFileName(), "a+")) == NULL)
... write the data in the file ...
// Add the necessary FITS keywords to the object
if (fits.CreateStoreFits("SIMPLE", &logicVal) == FAILURE)
// Add comments (would probably normally be done during the exposure)
if (fits.AddComment("Wheather conditions: clear") == FAILURE)
// Add logs (later the scheme for handling Operations Logs will be improved)
if (fits.AddLog("00:12:23> Started exposure") == FAILURE)
// Save the FITS header keywords into the file (filename is already stored
// in the object, so we give in a NULL string as filename). A filter can be used
// while saving the keywords into the file, but this is not done in this example.
while (more exposures to be done);
2.17.2 Example: Adding Keywords in an Existing FITS File
// Load in contents of the existing FITS file
// $INS_ROOT/$INS_USER/DETDATA/myImageFile.fits
if (fits.("myImageFile") == FAILURE)
while (<more keywords to generate>)
... generate and write the FITS lines in the object ...
} // end-while (<more keywords to generate>)
// Save (merge) the keywords into the FITS file. The header is extended automatically
if (fits->Save("") == FAILURE)
2.18 IMAGE FILE HANDLING --OSLXFITS_EXT
The class oslxFITS_EXT provides methods for:
The oslxFITS_EXT class makes use of the cfitsio library. Therefore the application have to include the cfitsio library as well.
2.18.1 Basic functionalities
When a new FITS file is created, the method CreateImageFile(char * filename) must be used.
At this time a temporary file is created. (i.e. in the filename the string "_tmp" is included).
To add keywords to the header use the function CreateStoreFits().
The file must be saved using the function SaveImageFile(). If the file is a a complete fitsfile (i.e. all the compulsory keywords are present) the file is saved with the name given as argument of CreateImageFile. See example 2.18.1.1
It is also possible to redaclare the filename during SaveImageFile.
Note that fitsfile can be saved without image data!
When an existing FITS file is to be updated (for exampe new keywords are to be added the function LoadImageFile(char * filename,vltLOGICAL update=ccsFALSE) has to be called.
If update is ccsFALSE overwriting of the existing imageefile is not allowed.
In this case imagefile name always has to be specified when the file is saved.
(Otherwise the file is saved with the string "_altered" included into the filename of the loaded file.)
See example 2.18.1.2.
The class checks the loaded file for completness. If the compolsary keywords are not present, the class returns an error. The keyword EXTEND is set to be true automatically when extention is present.VLTSW20020477 (see also VLTSW20020431)
In order to check the value of keywords in the fitsheader the functions ReadKeywordValue(),ReadKeywordStringValue() are supplied.
In order to handle header file (just a list of keywordlines withaout any imagedata) the function MergeHDUKeywords2() is supplied. See example 2.18.1.2. This function has to be used to merge headers created by DCS, TCS or ICS.
When compiling together the FITS file it is important for the oslxFITS_EXT user to make sure that enough space has been allocated to the primary header. If the primary header does not have enough of allocated space it will be necessary for OSLX to shift all data and images "below" the primary header. To avoid unnecessary shifting of large images in the FITS file a new warning is reported in the logMonitor if the primary header does not have enough allocated space.
In order to view pixels in the imagefile the executable oslxReadPixels can be used.
2.18.1.1 Example: Create a new image file, add keywords, and save it.
if(dict.LoadDic ("ESO-VLT-DIC.CCDDCS",FALSE)!=SUCCESS) {..}
//step 2: create an oslxFITS_EXT instance
//step 3: create a new image file
if(fitsext.CreateImageFile(testfile1)!=SUCCESS) {..}
//step 4: add the compulsory keywords
if(fitsext.CreateStoreFits("SIMPLE",simple)!=SUCCESS) {..}
if(fitsext.CreateStoreFits("BITPIX",8)!=SUCCESS) {..}
if(fitsext.CreateStoreFits("EXTEND",simple)!=SUCCESS)
if(fitsext.CreateStoreFits("NAXIS",0)!=SUCCESS) {..}
//step 5: add other keywords that (using autoadd dictionary)
fitsext.AutoAddKeysInDic(TRUE);
if(fitsext.CreateStoreFits("MY.STRING.KEYWORD","hello")!=SUCCESS) {..}
if(fitsext.CreateStoreFits("MY.INT.KEYWORD",6)!=SUCCESS) {..}
if(fitsext.CreateStoreFits("MY.DOUBLE.KEYWORD",1.23456789)!=SUCCESS) {..}
if(fitsext.CreateStoreFits("MY.LOGICAL.KEYWORD",lval)!=SUCCESS) {..}
//step 6: add comments and history
if(fitsext.AddComment("my comment1")!=SUCCESS) {..}
if(fitsext.AddComment("my comment2")!=SUCCESS) {..}
if(fitsext.AddHistory("my history1")!=SUCCESS) {..}
if(fitsext.AddHistory("my history2")!=SUCCESS) {..}
if(fitsext.SaveImageFile(testfile1)!=SUCCESS) {..}
2.18.1.2 Example2: Merge the header of an imagefile with the keywords of header file
oslxFITS_EXT fitsext2 (&dict);
if(fitsext2.LoadImageFile("ccdImageLcuSim.fits")!=SUCCESS) {..}
//step2 Merge the fitsfile with the header file
if(fitsext2.MergeHDUKeywords2("ccdImageLcuSim.fits.det")!=SUCCESS) {..}
//step3 Save the file with a different name
if(fitsext2.SaveImageFile(testfile2)!=SUCCESS) {..}
2.18.2 Extention Handling
The image file can contain extentions. The extentention is composed from a Header and Data Unit (referred as HDU) as well. The primary header and data unit is the first HDU in the image file while the first extention is the second HDU.
In order to navigate inside a fits file several functions are available. These are:
MoveToHDU(vltINT32 hdu); MoveToFirstHDU(); MoveToLastHDU();
MoveToBinaryTable(vltINT32 hdu); MoveToFirstBinaryTable();
MoveToLastBinaryTable(); MoveToExtention(char* extname)
It is possible to load or merge or append a particular HDU of an image file. See example 2.18.2.1 and example 2.18.2.2 or append a whole fitsfile at the end of an other fitsfile.
2.18.2.1 Example3: Load an existing file, and append the first hdu of an existing file
oslxFITS_EXT fitsext2 (&dict);
if(fitsext3.LoadImageFile(testfile1)!=SUCCESS) {..}
if(fitsext3.AppendHDU(testfileX,1)!=SUCCESS) {..}
if(fitsext3.SaveImageFile(testfile2)!=SUCCESS) {..}
2.18.2.2 Example4: Merge header keywords specifying the HDU number
oslxFITS_EXT fitsext3 (&dict);
if(fitsext4.LoadImageFile(testfile1)!=SUCCESS) {..}
//load the first file inmove to the requied hdu of the first file
if(fitsext4.MoveToHDU(1)!=SUCCESS) {..}
// specify the hdu number of the second file
if(fitsext4.MergeHDUKeywords(testfile2,1)!=SUCCESS) {..}
if(fitsext4.SaveImageFile(testfile)!=SUCCESS) {..}
2.18.3 Binary Table Handling
A binary table is a special extention in the fitsfile. Therefore when one wants to create a binary table using oslxFITS_EXT class a primary header with a minimum set of keywords will be automaticly created. See example below how to create a binary table:
For other operation (append, load) with binary tables the the extention handling functions
2.18.3.1 Example5: Create a binary table extention
// step 1: create an instance of oslxFITS_EXT
fitsext.AutoAddKeysInDic(TRUE);
char extname[] = "MY_FIRTS_BIN_TABLE";
char *ttype[] = {"Planet","Diameter","Density"};
char *tform[] = {"8a","IJ","1E"};
char *tunit[] = {"\0","km","g/cm"};
//step 3.create binarytable (creeate imagefile and add a binary table in one step)
//(primary header is automatically created with the compulsory keywords in it)
(nrows,tfields,ttype, tform,tunit, extname,testfile1)!=SUCCESS) {..}
char *planet[] = {"Mercury","Venus","Earth","Mars","Jupiter","Saturn"};
vltINT32 diameter[] = {100,200,300,400,500,600};
float density[] = {1.00,2.00,3.00,4.00,5.00,6.00};
int size= sizeof(planet)/sizeof(planet[0]);
//step5. add columns to binary tables
if(fitsext.AddSimpleColumnToBinaryTable(TSTRING ,1,size,planet)!=SUCCESS){..}
if(fitsext.AddSimpleColumnToBinaryTable
(TSHORT,2,sizeof(diameter)/sizeof(diameter[0]),diameter)!=SUCCESS) {..}
if(fitsext.AddSimpleColumnToBinaryTable(TFLOAT,3,6,density)!=SUCCESS) {..}
if(fitsext.SaveImageFile(testfile1)!=SUCCESS) {..}
2.18.3.2 Example for mutidimensional column
To modify the abve example 2.18.3.1 so that its second column conatin a two-dimensional integers the following has to be set:
char *tform[] = {"8a","2I","1E"}; // the second column is twodimensonal integer
vltINT32 diameter[][2] = {{11,12},{21,22},{31,32},{41,42},{51,52},{61,62}};
if(fitsext.AddElementsToBinaryTable(TSHORT,2,1,1,
sizeof(diameter)/sizeof(diameter[0]),diameter)!=SUCCESS){...}
2.18.4 View pixels of imagefile
The executable oslxReadPixels lists the pixel values in a part of an image. To print a small section of the image the top left point and the bottom right point of the rectangular section has to be specified. Optionally instead of the bottom right point the size of a square can be given. Imagefile containg extentions the extention can be specified as well.
oslxReadPixels myfile -topLeft [x1,y1] -size s
oslxReadPixels myfile -topLeft [x1,y1] -bottomRight [x2,y2]
oslxReadPixels myfile -topLeft [x1,y1] -size s -ext i
oslxReadPixels myfile -topLeft [10,20] -size 5
oslxReadPixels myfile -topLeft [10,20] -bottomRight [20,30]
oslxReadPixels myfile -topLeft 10,20 -size s -ext 2
x1,y1,x2,y2 are the coordinates of the points i.e.
s is the size, i.e. the number of pixels to be print out
in the rows and clumns (integer)
2.18.5 Printout the contents of a FITS file header on the stdout
The executable oslxCatFits prints out the header of o FITS file on the stdout. The program reads in the header of a FITS file, reformats each line by adding newlines after each FITS line, and prints these to stdout. The program also prints the FITS headers of possible extensions. If the sort parameter is defined then the keywords are rearranged according to the keyword ordering defined in the oslxSORT_REF_KEYW_LIST. All keywords that are not defined in the list will be printed after the sorted keywords in alphabetic order.
oslxCatFits <fits file> [<fits file>] [-sort] [-printName] [-details]
2.19 OSLX SERVER (CCS)
The OSLX Server provides, with a few exceptions, the same interface as the methods of the OSLX classes, on a command basis.
It is possible to have several instances of the OSLX Server running in the same RTAP environment. The name must always have the format "oslxServer_XXXXXX", where "XXXXXX" is the user definable part. It is not necessary to make a special CDT for the "oslxServer_XXXXXX" instance of the server, since the command checking function of CCS figures out that the oslxServer.cdt should be used. The requested name, "oslxServer_XXXXXX", can be given in as input parameter when starting up the server.
Also when starting the server it is possible to specify an Alias Table and a Dictionary. These will be made available for the instances of the oslxSETUP class, the oslxSHORT_FITS class, the oslxCONFIG class the oslxALIAS class (only an Alias Table) but not the oslxDICTIONARY class.
2.20 HANDLING OF SETUP FILES FROM GUI PANELS
(Responsible: Antonio Longinotti)
The Tcl library libslxtcl.tcl (module slxtcl) provides procedures to handle setup keywords and files within a GUI panel.
The GUI panel must have been built with the VLT panel editor or at least must conform to its conventions about naming of variables associated to widgets.
Panels, dedicated to handling of Setup Files, which intend to use this library, must register to it (see menu item "Options" --> "Register User Library" in the panel editor main panel).
The API of this library consists of the following procedures:
It saves in a oslx buffer name and value of variables associated to widgets within a GUI panel. To be used only if the returned oslx buffer has to be manipulated before saving in file.
It saves in a setup file the current value of variables associated to widgets within a GUI panel. It basically performs in sequence calls to slxtclPanToBuf and slxTclWriteSetup
It allows to exclude a set of variables associated to widgets from saving in a setup buffer or file.
It reads keywords and values from a setup file and updates variables in a GUI panel. It basically performs in sequence calls to slxTclReadSetup and slxtclBufToPan
For more information about these procedures and the conventions to be followed to associate a GUI variable to a setup keyword, see the manual pages.
Note: The procedures slxtclDictionary, slxtclWriteSetup and slxTclReadSetup use the functionality provided by oslx to handle setup files and keywords. The dictionaries have to be loaded through slxtclDictionary before using slxtclSaveSetup or slxtclLoadSetup.
2.21 ERROR HANDLING
OSLX is based on ECCS and uses therefore the eccsERROR_CLASS for the error handling. This means that none of the OSLX methods have the ccsERROR structure as input, but if an error occurs, access to the internal error stack can be obtained using the method, e.g. setup.ErrStack().
 Quadralay Corporation http://www.webworks.com Voice: (512) 719-3399 Fax: (512) 719-3606 sales@webworks.com |
| |
|
|
|
