| |
|
|
|
3 REFERENCE
3.1 APPLICATIONS
oslxSERVER, oslxServer, oslxTcl, oslxSeqWish, oslxShell, oslxSHELL -
provides services for handling files in the INS Tree
The OSLX Server provides services for handling of the following VLT file
types:
o Alias Conversion Tables.
o Configuration Files.
o Data Interface Dictionaries.
o Data FITS file headers.
o Setup Files.
o Short-FITS Files (generic PAF Files).
The OSLX Server is executed on CCS using CCS for comunicating with other
processes.
The commands supported for handling these file types are:
ALIAS, CONFIG, DICTION, FILTER, FITS, FITS_EXT, INSDIR, OSETUP, SHOFITS
Furthermore the command "GEN" is provided for the general handling of the
OSLX Server.
Be aware, that the OSLX Server can only handle one parameter at a time.
I.e., "OSETUP -load mySetup setupFile -getSetupBuf mySetup" is not
possible, but will have to be executed in two calls. This behaviour
also goes when using the OSLX Shell.
The server can handle simultaneously an arbitrary number of instances
of the OSLX classes used inside the server. An instance is referred to
by an instance ID (<id> in this man-page). The ID can be any text
string. When a new instance ID is specified, and new instance of the
corresponding class is allocated.
The server expects the INS Tree directory structure as described in the
Instrument Common SW Specification (VLT-SPE-ESO-17240-0385).
Note that e.g. Setup Files and FITS Data Headers cannot be handled before
a Dictionary has been loaded. Aliasing needs an Alias Conversion Table
for being active. Dictionaries and Alias Conversion Tables can be
loaded dynamically during execution of the server. A Dictionary
and Alias Conversion Table can also be loaded at start-up in the first
instance of the various classes if the names of these are specified as
input parameters. In this case this Dictionary will be made available
automatically for new instances as they are created. It is also possible
to obtain the same effect using the "GEN -loadSetDicAll <dic>" command.
For more information about the naming convention for Dictionaries please
consult the man-page for slxLookUpKeywordHashX.
If OSLX is used from the seqWish shell via the SEQ Wish command
"seq_oslxCmd", the same interface as for the OSLX Server is used. E.g.:
seq_oslxCmd DICTION -load myInstance MYDIC merge
Note, before the seq_oslxCmd can be used it is necessary to do a:
package require SeqOslx
from the Tcl Shell.
The input parameters to the OSLX Server are (not relevant for the
usage from the Tcl Shell):
-v Start up the server in verbose mode. It will then
write information about various events happening to standard
output.
-name It is possible to specify a name with which the
server shall register on CCS. This makes
it possible to have several instances of the process
running in the same RTAP environment. If no name is
specified the generic name "oslxServer" will be the
process name to use when sending commands to the
server, but it is recommended to allocate a specific name.
This is only relevant when running the Server as a CCS Process.
The name must be of the format: "oslxServer_XXXXXX", where
"XXXXXX" is a string of up to 6 characters, that specifies
this instance of the OSLX Server.
-dictionary Specifies the name of a Dictionary to be loaded into the
server. All objects needing a reference to a Dictionary for
the proper execution (with the exception of the OSLX
Dictionary object, will refer to this Dictionary, unless
it is specified to use another Dictionary for that instance
later.
-alias Specify an Alias Conversion Table that should be loaded into
the server. The objects needing the Alias Conversion Table
(with exception of the OSLX Alias object) will automatically
refer to this.
-check This parameter specifies the kind of check there
shall be performed in connection with the handling of
setup files/keywords. The following check types are supported:
"SOFT", "NORMAL", "FULL"
The explanation of the various check types can be
found in the man page for "oslxSHORT_FITS".
INS_ROOT Defines the root of the instrument directory
struture. Can be changed dynamically
during run-time by issuing the "GEN" command.
INS_USER Points to the branch in the INS Directory,
e.g. "SYSTEM", where to search first for
files, and where to store Setup Files etc.
Can be changed dynamically during run-time by
issuing the "GEN" command.
INS_USER_PATH Colon separated path of directories where
Context Specific Short-FITS Files can be
located. These files should be stored in the
$INS_ROOT/<user>/MISC directory. It is
possible to make sub-directories.
INS_SETUPPATH Colon separated list of paths where Setup
Files are located. Can be changed dynamically
during run-time by issuing the "GEN" command.
ALIAS Used to handle Aliases.
-load <id> <alias table>
Description: If a table is already loaded, the new aliases
are merged together with the existing ones; the
new overwrite the old ones. "<alias table>"
should only be the context name, e.g. "ISAAC".
-clear <id>
Description: Clears the object by unloading an Alias
Conversion Table currently loaded.
-getKeyword <id> <alias>
Description: Gets the alias corresponding to the keyword if
existing.
Reply Buffer: "<keyword>"
-getAlias <id> <keyword>
Description: Gets the keyword corresponding to the alias if
existing.
Reply Buffer: "<alias>"
CONFIG Use to handle Configuration Files.
-clear <id>
Description: Clear the object. Normally it is probably
only necessary to reset the Change Record,
since in this way all keywords are kept in the
object, and subsequent operations will be
faster.
-loadDic <id> <dictionary> [merge]
Description: Load a Dictionary into an instance. If a
Dictionary is already loaded, it is first
unloaded automatically.
-loadAliasTable <id> <alias table>
Description: Load a Alias Table into an instance. If a
Alias Table is already loaded, it is first
unloaded automatically.
-resetChangeRecord <id>
Description: Reset the Change Record of an instance. I.e.,
the local list of keywords that has changed
since the last -clear of the instance or the
last reset of the Change Record.
-hasChanged <id> <keyword>|<keyword no>
Description: Query if a specific keyword referenced by its
names or by its internal number in the
instance.
Reply Buffer: "TRUE|FALSE"
-getChangedKeywords <id>
Description: Returns all keywords that are marked as changed
in an instance.
Reply Buffer: "<#>,<keyword n> <value n>,<keyword m> ..."
-getKeywordBuf <id> [useChRec] [filter <id>]
Description: Returns all keyword currently stored in the
object, or a subset if the Change Record should
be used or a filter is specified.
Reply Buffer: "<#>,<keyword n> <value n>,<keyword m> ..."
-noOfKeywords <id>
Description: Returns the number of keywords currently
stored in the referenced object.
Reply Buffer: "<#>"
-getValue <id> <keyword no>|<keyword>
Description: Get the value of a keyword referenced either
by its name or its number.
Reply Buffer: "<value>"
-getLongValue <id> <keyword no>|<keyword>
Description: Get the value of a long keyword referenced either
by its name or its number.
Reply Buffer: "<value>"
-resetKeywordPtr <id>
Description: Reset the pointer to the list of keywords in
the object. Used to return keywords
sequentially.
-getNextKeyword <id> [useChRec] [filter <id>]
Description: Return the sequential next keyword in the
object. When the last keyword has been returned
the subsequent call will return an empty error
message.
Reply Buffer: "<keyword> <value>"
-storeKeyword <id> <keyword> <value>[ <keyword> <value>]
Description: Store one or more keywords in the object. The
format of the keywords must be Short-FITS.
-load <id> <[path]filename[<.ext>]> [type <type>] \
[[filter <id>]
Description: Load a Configuration File into the referenced
object.
-save <id> [fileName <filename>] [useChRec] [filter <id>] \
[type <type>] [saveComments]
Description: Save the contents of the instance into a
Configuration File.
The type must be either "configuration",
or "ref-configuration".
It is possible to extract certain keywords by
specifying the usage of the Change Record or a
filter.
The new Configuration File will be stored in the
directory:
$INS_ROOT/$INS_USER/<obs mode>/CONFIGFILES/
If not the complete path is given, the file
will be stored in the "COMMON" Observation Mode
directory.
Note that the INS_USER and the INS_SETUPPATH
can be modified dynamically (GEN command).
The "saveComments" option can be used to
indicate for OSLX to store the comments there
might be in connection with the keywords as
well.
If the Configuration File already exists, it is
overwritten silently if writable.
DICTION Used to operate the OSLX Dictionary.
-load <id> <dictionary> [merge]
Description: Loads a Dictionary into the specified instance.
If "merge" is specified, the new Dictionary
will be loaded with the one already loaded,
otherwise this old Dictionary is first unloaded.
-clear <id>
Description: Clears the object, i.e. unloads a possible
Dictionary loaded.
-lookUpKeyword <id> <keyword>
Description: Look up a keyword in the Dictionary loaded into
the specified instance, and send back the
fields of the Dictionary Record.
Reply Buffer: "<#>,<keyw name>,<class>,<context>,<format>,
<unit>,<std comment>,<description>"
-resetRecordPtr <id>
Description: Reset the pointer to the list of Dictionary
Records.
-getNextRecord <id> [useChRec] [filter <id>]
Description: Get the sequential next Dictionary Record
pointed to by the Record Pointer. If there are
no more records a reply buffer containing only
a "0" is sent back.
Reply Buffer: "<#>,<keyw name>,<class>,<context>,<format>,
<unit>,<std comment>,<description>"
-matchKey <id> <key>
Description: Make OSLX search for a key containing
the pattern given for "key". A list of
keys matching "key" will be generated.
Reply Buffer: "<#>,<match key 1>,...,<match key #>"
-getBestFits <id>
Description: Returns the best fit pattern (completion)
which was generated during the last "-matchKey"
operation. The "<no of macthes>" parameter in
the reply, indicates how many times the
Best Fit matches a key in the Match Key List.
I.e., if this is 1, the Best Fit is unique.
Reply Buffer: "<no of matches>,<best fit pattern>"
-storeKeyword <id> (((<keyword>)))(((<classList>)))\
(((<context>)))(((<type>)))(((<valueFormat>)))\
(((<unit>)))(((<comment>)))\
((([<description>])))
Description: Store a new keyword in the referenced object.
if the keyword exists, it is replaced with
the new keyword. All fields must be specified.
If a field doesn't have a value "((()))" must be
given in.
-deleteKeyword <id> <keyword>
Description: Delete a keyword stored in object <id>.
-save <id> name <name>|buffer
Description: Save the Dictionary in the object into a file.
If a name is specified a new Dictionary will
be generated. If "buffer" is specified, the
contents of the object will be written into
a file with the name of the last Dictionary
loaded.
-getHeader <id>
Description: Return the the header of the current Dictionary
loaded. This may be empty if a new Dictionary
is being build up. As soon as the new
Dictionary has been saved once, the object
will contain a header for this.
Reply Buffer: "<header>"
-getDicName <id>
Description: Returns name and revision of the current
Dictionary loaded.
-storeHeader <id> <header>
Replace the current header in the object for
the Dictionary with a new one.
FILTER Used to operate the OSLX Filter Class.
-clear <id>
Description: Clear all filters adjusted for that instance.
-addFilter <id> [<cat>] [<sub1>] [<sub2>] <par> \
[[<type>Value <value>] | [<type>Range <range>]]\
[keywordClass <class>]
Description: Add a subfilter to the specified instance. A
filter can be e.g.:
"DET WIN* START*" --> Take all
DET.WINi.STARTi keywords.
Several such subfilters can be adjusted in
each filter instance.
When adding a Value or a Range Filter,
<type> must be "string", "logical", "integer"
or "double". Note for logicals it is not
possible to specify a range. A <range> must be
given as "<low limit> <high limit>". For
strings the rules applied for strcmp(3) are
used. The low and high limits are included in
the range.
If the Keyword Class is specified it must have
one of the values:
"setup", "header", "conf-log", "cond-log",
"ops-log", "reduc-log", "config", and
"private"
In this case there is only match if the keyword
+ possibly the value match and if the keyword
has the specified class in the Dictionary. If
it is needed to specify several classes,
several sub-filters (within the same filter
class instance) must be used.
-addSymbolicFilter <id> <symbolic filter>
Description: See decription in man-page for oslxKEYW_FILTER
method oslxKEYW_FILTER::AddSymbolicFilter().
NOTE, this method requires the availability of
a Dictionary (use e.g. GEN -loadSetDicAll).
-setStrictFiltering <id> on|off
Description: Switch on/off strict filtering for the filter.
-getFilter <id> <filter no>
Description: Return a specific filter by its number in the
list of filters.
Reply Buffer: "5,<cat filter>,<sub 1 filter>,<sub 2 filter>,\
<par filter>,<value match>"
FITS Used to handle FITS files. Note in the following that the
parameter "[fits_ext <no>]" can be used to specify a specific
extension in file making use of the FITS File Extension.
The 'main' header has number 1. If not specified it is
defaulted to 1.
-clear <id>
Description: Reset the referenced object.
Each keyword added to the object hereafter
will be stored when the Save() method is called.
However all keywords stored in the object will be
kept and only the values updated when they are issued again,
in order to save time when adding keywords in the object.
See also Reset() function on the manpage of oslxFITS.
Note that this option does not clear the fits instance
and should not be confused with the function ClearInstance()
of the oslxFITS.
-clearInstance <id>
Description: Clear the object and release all resources in use.
Envoking this method will delete the internal Hash Tables
used e.g. for storing keywords.
-loadDictionary <id> <dictionary> [merge]
Description: Load a Dictionary into the referenced object.
must be done before starting using an instance.
-loadAliasTable <id> <Alias Table>
Description: Load an Alias Table into the referenced object.
-loadHeader <id> <filename> [merge] [filter <id>] \
[ignoreUnknownKeys]
Description: Load a header of a FITS file into the referenced
object. If there are already keywords in the
objects the new ones are merged with the old.
ones If it is not desirable to mix up keywords
the object can be "-clear"ed first.
-clearCommentList <id> [fits_ext <no>]
Description: Clear the list of comments currently stored in
the object. This is also done when the "-clear"
parameter is issued.
-addComment <id> "<comment>" [fits_ext <no>]
Description: Add a comment to the list of comments currently
stored in the object. When generating a FITS
header the comments stored in the object are
written into the header after the last keyword.
-resetCommentPtr <id> [fits_ext <no>]
Description: Reset the pointer to the list of comments. Used
to be able to return the comments stored
sequentially.
-getNextComment <id> [useChRec] [filter <id>] [fits_ext <no>]
Description: Return the sequential next comment in the
Comment List. When there are no more comments
in the list an empty buffer is returned.
Reply Buffer: "<comment>"
-clearLogList <id> [fits_ext <no>]
-addLog <id> "<log>" [fits_ext <no>]
-resetLogPtr <id> [fits_ext <no>]
-getNextLog <id> [fits_ext <no>]
Description: See description of similar parameters for
handling of comments.
-clearHistList <id> [fits_ext <no>]
-addHist <id> "<log>" [fits_ext <no>]
-resetHistPtr <id> [fits_ext <no>]
-getNextHist <id> [fits_ext <no>]
Description: See description of similar parameters for
handling of comments.
-createFile <id> <filename> <no of blocks>
Description: Create a new FITS file with the specified
number of FITS blocks (2880 bytes each)
with the "END" keyword written. No FITS
information is written in the file at
this point; this must be done by issuing the
"-save" parameter.
Creation of a FITS file is typically done
before starting to receive a data frame. While
receiving the frame, the data transfer task can
then write data in the file after the allocated
header. It is thus important that enough FITS
blocks have been allocated to avoid unnecessary
copying of the image data.
-createStoreFits <id> <keyword (Short-FITS)> <value> \
[<keyword> <value>] [fits_ext <no>]
Description: Create and store one or more FITS keyword
in the referenced object.
-save <id> <filename> [filter <id>]
Description: Saves the FITS information stored in the object
in the specified file. The file must exist.
If the number of FITS blocks allocated for the
header is not enough for storing the FITS
keywords, the header is extended automatically.
Note that this may be time consuming if the file
already contains the image data.
If the header of the FITS file already contains
FITS keywords, these are merged into the object.
The keywords already stored in the object
overwrite the ones loaded from the file.
Following the main header the possible comments
and logs stored in the object will be written,
in the sequence they were issued. If comments
ands logs are loaded from a file, these will
be listed before the new ones.
-saveAsciiFile <id> <filename> [useChRec] [<filter> <id>]
Description: Saves the keywords, comments and logs currently
stored in the object into a readable ASCII
test file. The file will be located in the
"$INS_ROOT/$INS_USER/DETDATA" directory unless
the complete path is specified.
-resetFitsHeaderPtr <id> [fits_ext <no>]
Description: Resets the pointer to the list of FITS keywords
currently stored in the object. Used to query
sequentially the FITS keywords in the object.
-getNextFitsLine <id> [fits_ext <no>]
Description: Used to query sequentially the FITS keywords
stored in the object. When the last FITS line
has been requested, the next request will result
in a buffer of length 0.
Reply Buffer: "<FITS line>"
-getValue <id> <keyword (Short-FITS)> [useChRec] \
[fits_ext <no>]
Description: Searches for a specific keyword and returns
the value of this if found.
Reply Buffer: "<value>"
-extractKeywords <id> [useChRec] [filter <id>] [fits_ext <no>]
Description: Extracts a number of desired keywords
and returns these if found. The extraction can
be done taking only the keywords that have
changed since last -clear of the object was done
and/or by applying a filter. If neither the
change record is specified, nor a filter, all
keywords are returned. Keywords are returned in
the Short-FITS format.
Note, that all the different keywords which
have been loaded into an instance remain there
even after a -clear. However the object keeps
track of which keywords that have changed since
the last -clear. The reason for keeping all
keywords permanently in the object is for
speed reasons.
Reply Buffer: "<#>,<keyword1> <value1>,<keyword2> <value2>..."
-autoAddKeysInDicOn <id>
Description: Switch on Auto-Adding of unknown keywords
encountered in FITS Files being loaded.
-autoAddKeysInDicOff <id>
Description: Switch off Auto-Adding of unknown keywords
encountered in FITS Files being loaded.
-appendFile <id> <target file> <source file>
Description: Append the source file to the target file.
The result will become a FITS File using the
FITS Extension even if the two file originally
were not using the FITS extension.
-numberOfHdrs <id>
Description: Returns the number of FITS header currently
stored in the reference object. If there is
only the main header 1 will be returned. If
there are 3 FITS extension header, this number
will be 4.
Reply Buffer: "<of of headers>"
FITS_EXT Used to handle FITS files. Note in the following that the
parameter "[hdu <no>]" can be used to specify a specific
extension in file making use of the FITS File Extension.
The 'main' header has number 1. If not specified it is
default set to 1.
-reset <id>
Description: Method to reset the object.
It should be called if the object is used
for creating/modifying more files. When the
previously loaded/treated file is not yet saved
reset attempts to save it as a <fname>_tmp.fits
file.
During reset the dictionary is not unloaded.
-cancel <id>
Description: This method also resets the object.
The difference between reset and cancel is that the
cancel also DELETES THE FILE. This can be useful
in cases where a FITS file has been partially created,
but then an error occurs which prevents it from being
completed.
During this function the dictionary is not unloaded.
-loadDictionary <id> <dictionary> [merge]
Description: Loads a Dictionary into the object. If a Dictionary
is already loaded it is first deleted if the merge
is set to FALSE
-loadImageFile <id> <filename> <update>
Description: Load an image file. If update is ccsTRUE file will be
overwriten during saveImageFile, unless other filename
is specified during saving the image.
When 'update' is ccsFALSE overwriting of the existing
imagefile is not allowed. In this case, when filename
is not specified during saving the image
(i.e. SaveImageFile), the file will be saved as
<fname>_updated.fits.
-addComment <id> "<comment>" <hduNum>
Description: Add a comment to the list of comments currently
stored in the object. When generating a FITS
header the comments stored in the object are
written into the header after the last keyword.
-addHistory <id> "<log>" <hduNum>
Description: Add a history log to the list of logs currently
stored in the object.
-createImageFile <id> <filename> [<isFitsExt>]
Description: Creates a new image file.
Files with names "<fname>.fits" and "<fname>_tmp.fits"
(where <fname> is the filename without the extention)
should not exist before the function is called. File
has to be saved using the saveImageFile function.
In case of error during operation on the file or
saving the file the file is saved as
"<fname>_tmp.fits". As default (isFitsExt=ccsTRUE)
the filename is extended with ".fits" extention if it
does not end with ".fits" it already. In case the
imagefile name should have different extentention the
second argument (isFitsExt) has to be set to ccsFALSE.
-allocateHeaderSize <id> <noOfBlocks>
Description: Sets the primary header size of the created fits file.
For binary tables the size is set directly during the
creation with a parameter in the method CreateBinaryTable
-createStoreFitsString <id> <keyword> <value> [<keyword> <value>]
Description: This functions add a new string value to the header.
When 'hdunum' is not specified, the kewyword is
added to the current HDU. When 'hdunum' is specified,
after the function is executed the current hdu will
be set to the given hdu.
-createStoreFitsLogical <id> <keyword> <value> [<keyword> <value>]
Description: This functions add a new logical value to the header.
When 'hdunum' is not specified, the kewyword is
added to the current HDU. When 'hdunum' is specified,
after the function is executed the current hdu will
be set to the given hdu.
-createStoreFitsInt <id> <keyword> <value> [<keyword> <value>]
Description: This functions add a new integer value to the header.
When 'hdunum' is not specified, the kewyword is
added to the current HDU. When 'hdunum' is specified,
after the function is executed the current hdu will
be set to the given hdu.
-createStoreFitsDouble <id> <keyword> <value> [<keyword> <value>]
Description: This functions add a new keyword double value to the the
specified header.
When 'hdunum' is not specified, the kewyword is
added to the current HDU. When 'hdunum' is specified,
after the function is executed the current hdu will
be set to the given hdu.
-saveImageFile <id> <filename> [isFitsExt]
Description: Save the image file in the $INS_ROOT/$INS_USER/DETDATA
with the given name. File with the same name should
not exits. When filename is not given, the file will
be saved according to the descriptiion given at
CreateImageFile, LoadImageFile, LoadHDU. During the
saving the HDU-s are checked for the compulsory
keywords, and the keywords are sorted according to
the reference list.
When the file is to be saved with other then ".fits"
extention, the second argument (isFitsExt) has to be
set to ccsFALSE.
-deleteFitsKeyword <id> <keyword> [hduNum] [resetHdu]
Description: Deletes a keyword with the sepcified name from the given hdu.
If reset hdu is ccsTRUE, the current hdu after the function
is executed will be the given hdu. Otherwise the current hdu
will remain as before the function is called.
-autoAddKeysInDicOn <id>
Description: Switch on Auto-Adding of unknown keywords
encountered in FITS Files being loaded.
-autoAddKeysInDicOff <id>
Description: Switch off Auto-Adding of unknown keywords
encountered in FITS Files being loaded.
-readKeywordStringValue <id> <keyword>
Description: Retrieves the keyword from the header (current HDU) as string
regardless of the actual type of the kw. Error is returned
when keyword is not found in the header.
Reply Buffer: "<value>"
-append <id> <source file>
Description: Append a whole fitsfile to the current file. The the keyword
XTENSION will be automatically added to the primary HDU of
the appended file.
-appendHdu <id> <source file> <hduNum>
Description: Append the given HDU of the named file to the current
(to the end of) imagefile.
-appendExt <id> <source file>
Description: Append all extentions of the named file to the imagefile.
-mergeHduKeywords <id> <source file> <hduNum>
Description: Merge the keywords of the given hdu of the given file with
the keywords in current hdu of the imagefile.
The file given as argument must be a proper fitsfile.
(Note that any file that has been properly saved by this
class is a complete fitsfile.)
-mergeHduKeywords2 <id> <source file>
Description: Merge the keywords in the 'headerFile' with the
current hdu of the imagefile. Existing keywords will be
overwritten. The file given as argument of MergeHDUKeywords2
must be a (complete or incomplete) header file.
Typically this function should be used to handle the
headerfiles produced by e.g. TCCD and FIERA : '*.fits.det'
-sort <id>
Description: Sorts the keyword according to inner reference list. sort
will organise the keywords in all HDUs. The keywords that
are not on the list are placed in alphabetical order after
the list.
-setSortType <id> <sortType NO_SORT, REFLIST, REFLIST_ABC)
Description: Specifies wheter and how the keywords in the headers should
be sorted.
The argument 'type' can have the following values:
NO_SORT, REFLIST, REFLIST_ABC
To swich off the sorting give NO_SORT as argument.
Default sorttype is REFLIST_ABC. In this case the
keywords are sorted according to inner reference list. The
keywords that are not on the list are placed in alphabetical
order after the list. When sorting type REFLIST, the keywords
that are not on the list are not sorted. They are placed
after the ordered list in the same order as before.
-getSortType <id>
Description: Returns the type of the sort:
REFLIST_ABC, REFLIST, NO_SORT
Reply Buffer: "<Sorting type>"
-numberOfHdrs <id>
Description: Returns the number of headers
Reply Buffer: "<of of headers>"
-moveToHdu <id> <hduNum>
Description: The argument 'hduNum' is the serial number of the HDU to be
moved to.
The primary hdu : hdu=1,
First extention is hdu=2;
GEN General handling of the OSLX Server.
-setInsRoot <new dir>
Description: Changes the INS_ROOT used by the oslxServer.
-getInsRoot
Description: Get the current value of the INS_ROOT.
Reply Buffer: "$INS_ROOT"
-setInsUser <new user>
Description: Changes the INS_USER used by the oslxServer.
-getInsUser
Description: Return current value of the INS_USER.
Reply Buffer: "$INS_USER"
-getInsUsers
Description: Return a list with all INS Users in the
current INS_ROOT.
Reply Buffer: "<#>,<user 1>,<user 2>, ..."
-setInsSetupPath
Description: Set the INS_SETUPPATH environment variable
used by the server.
-addPathInsSetupPath
Description: Add one or more paths to the INS_SETUPPATH used
by the server.
-getInsSetupPath
Description: Return the contents of the INS_SETUPPATH
variable.
Reply Buffer: "$INS_SETUPPATH"
-loadSetDicAll <dictionary>
Description: Load a Dictionary and make all relevant
instances point to this Dictionary.
-setInsUserPath <INS User Path>
Description: Set the environment variable INS_USER_PATH.
-addPathInsUserPath <new path>
Description: Add a path to the environment variable
INS_USER_PATH.
-getInsUserPath
Description: Get the current value of the environment
variable INS_USER_PATH.
-verbose <switch>
Description: Switch verbose mode on/off. Values must be
"0" or "1".
INSDIR Operations on the INS Tree
-useInsTree TRUE|FALSE
Description: Specify for the object whether to use the
INS Tree or not.
-setDictionary <dic id>
Description: Make the object refer to a Dictionary.
-searchFitsFile <base name> [filter <id>] \
[globalSearch] [stopFirstOccur] \
[skipInsUserRoot] [ignoreUnknownKeys]
Description: Search for a FITS File applying possibly a
filter. The list of files matching will be
returned. "globalSearch" enables search in the
complete INS Tree. "stopFirstOccur" makes the
search stop at the first occurrence of a file
matching the conditions. "skipInsUserRoot"
makes OSLX jump the DETDATA directory of the
current INS User.
Reply Buffer: "<#>,<file info 1>,<file info 2>, ..."
The file info for each file has the format:
<path> <user> <filename> <extension> <size> \
<time> <date>
-getFormattedFileList <format> <fields>
Description: Format the files currently stored in the object
as result of the last search. The format can
be e.g. "%.10s_%.20s__%.10s_%s\n". Note that
blanks must be replaced by underscore (_).
The <fields> can be e.g.
"user_size_date_fileName". Note that the fields
must be separated by underscore charecter. The
possible fields are:
"path,user,fileName,extension,size,time,date".
Reply Buffer: "<formatted file info 1> ..."
OSETUP Handle Setup Files and keywords.
-clear <id>
Description: Clear the object. Normally it is probably
only necessary to reset the Change Record,
since in this way all keywords are kept in the
object, and subsequent operations will be
faster.
-loadDic <id> <dictionary> [merge]
Description: Load a Dictionary into an instance. If a
Dictionary is already loaded, it is first
unloaded automatically.
-loadAliasTable <id> <alias table>
Description: Load a Alias Table into an instance. If a
Alias Table is already loaded, it is first
unloaded automatically.
-setCheck <id> NORMAL|FULL|SOFT|NONE
Description: Switches on the requested check type for an
instance. An error will be returned if no
Dictionary is loaded and e.g. Normal Check is
requested.
-getExpoId <id>
Description: Returns the current Exposure ID stored in the
instance issued with the last Setup Command
Buffer sent to the instance.
Reply Buffer: "<expo ID>"
-getNoMoveFlag <id>
Description: Returns the value of the No Move Flag issued
with the last Setup Command Buffer sent to
the instance.
Reply Buffer: "TRUE|FALSE"
-getCheckFlag <id>
Description: Returns the value of the Check Flag issued
with the last Setup Command Buffer sent to
the instance.
Reply Buffer: "TRUE|FALSE"
-handleSetupCmd <id> <SETUP cmd buffer> [updateOnly]
Description: Merges the contents of the SETUP command buffer
into the specified instance of oslxSETUP. Setup
Files are automatically loaded into the instance
and the Exposure ID, the No Move Flag, and the
Check Flag set accordingly. Before sending the
SETUP command buffer to the server, the
cmdParamToForwardMsg() function should be
envoked on the Command Parameter List.
-resetChangeRecord <id>
Description: Reset the Change Record of an instance. I.e.,
the local list of keywords that has changed
since the last -clear of the instance or the
last reset of the Change Record.
-hasChanged <id> <keyword>|<keyword no>
Description: Query if a specific keyword referenced by its
names or by its internal number in the
instance.
Reply Buffer: "TRUE|FALSE"
-getChangedKeywords <id>
Description: Returns all keywords that are marked as changed
in an instance.
Reply Buffer: "<#>,<keyword n> <value n>,<keyword m> ..."
-makeMsgBuf <id> [filter <id>]
Description: Make a Setup Command Message buffer from the
keywords of the object. A filter can be applied
to extract only a subset. The buffer returned
can be sent directly with the SETUP command.
Reply Buffer: "<expo ID>,,<keyword 1> <value 1> ...,\
<no move flag>,<check flag>"
-makeMsgBufChangeRecord <id> [filter <id>]
Description: Make a message buffer for the SETUP command
taking only changed keywords into account.
Reply Buffer: "<expo ID>,,<keyword 1> <value 1> ...,\
<no move flag>,<check flag>"
-getMsgBuf <id>
Description: Return the message buffer currently stored in
the object.
Reply Buffer: "<expo ID>,,<keyword 1> <value 1> ...,\
<no move flag>,<check flag>"
-getMsgBufSize <id>
Description: Returns the size of the SETUP Command message
buffer.
Reply Buffer: "<size in bytes>"
-getSetupBuf <id> [filter <id>]
Description: Returns all keyword currently stored in the
object, or a subset if a filter is specified.
Reply Buffer: "<#>,<keyword n> <value n>,<keyword m> ..."
-noSetupKeywords <id>
Description: Returns the number of setup keywords currently
stored in the referenced object.
Reply Buffer: "<#>"
-getValue <id> <keyword no>|<keyword>
Description: Get the value of a keyword referenced either
by its name or its number.
Reply Buffer: "<value>"
-resetKeywordPtr <id>
Description: Reset the pointer to the list of keywords in
the object. Used to return keywords
sequentially.
-getNextKeyword <id>
Description: Return the sequential next keyword in the
object. When the last keyword has been returned
the subsequent call will return an empty error
message.
Reply Buffer: "<keyword> <value>"
-storeKeyword <id> <keyword> <value>[ <keyword> <value>]
Description: Store one or more keywords in the object. The
format of the keywords must be Short-FITS.
-load <id> <[path]filename>
Description: Load a Setup File into the referenced object.
-save <id> <setup type> [useChRec] [filter <id>] \
[header <id>] [saveComments]
Description: Save the contents of the instance into a
Setup File. Prior to that a filename must have
been attached to the object by means of the
-saveAs parameter or the -setSetupFile
parameter.
The Setup Type must be either "Reference Setup",
"Detector Setup", "Instrument Setup" or
"Telescope Setup".
It is possible to extract certain keywords by
specifying the usage of the Change Record or a
filter.
If another Setup File Header than the internal
one in the object is required, this can be given
in as well.
The new Setup File will be stored in the
directory:
$INS_ROOT/$INS_USER/<obs mode>/SETUPFILES/<type>
The <obs mode> (Observation Mode) can be
specified in the Setup Header used and must
then have a name corresponding exactly to a
directory in the $INS_USER. The <type>
(Setup Type, Reference, Detector, Instrument or
Target) determines in which of the
subdirectories in the /SETUPFILES directory the
Setup File is stored.
Note that the INS_USER and the INS_SETUPPATH
can be modified dynamically (GEN command).
The "saveComments" option can be used to
indicate for OSLX to store the comments there
might be in connection with the keywords as
well.
If the Setup File already exists, it is
overwritten silently if writable.
-saveAs <id> <[path]filename> <setup type> [useChRec] \
[filter <id>] [header <id>] [saveComments]
Description: Generate a Setup File from the keywords stored
in the object. See -save. If no Observation Mode
is specified in the Setup File Header, the
Setup File will be stored in the
$INS_ROOT/$INS_USER/COMMON/SETUPFILES directory.
-setSetupFile <id> <[path]<filename>>
Description: Attach a Setup Filename to the object.
-extractSetupFromFitsHd <id> <[path]<FITS filename>>
Description: Extract from a FITS data file the setup keywords
contained in the header. Only keywords marked
with the "setup" class in the Dictionary are
extracted. The keywords extracted are stored in
the referenced instance of oslxSETUP.
SHOFITS Used to handle Short-FITS files
-clear <id>
Description: Clear the object. Normally it is probably
only necessary to reset the Change Record,
since in this way all keywords are kept in the
object, and subsequent operations will be
faster.
-loadDic <id> <dictionary> [merge]
Description: Load a Dictionary into an instance. If a
Dictionary is already loaded, it is first
unloaded automatically.
-loadAliasTable <id> <alias table>
Description: Load a Alias Table into an instance. If a
Alias Table is already loaded, it is first
unloaded automatically.
-setCheck <id> NORMAL|FULL|SOFT|NONE
Description: Switches on the requested check type for an
instance. An error will be returned if no
Dictionary is loaded and e.g. Normal Check is
requested.
-resetChangeRecord <id>
Description: Reset the Change Record of an instance. I.e.,
the local list of keywords that has changed
since the last -clear of the instance or the
last reset of the Change Record.
-hasChanged <id> <keyword>|<keyword no>
Description: Query if a specific keyword referenced by its
names or by its internal number in the
instance.
Reply Buffer: "TRUE|FALSE"
-getChangedKeywords <id>
Description: Returns all keywords that are marked as changed
in an instance.
Reply Buffer: "<#>,<keyword n> <value n>,<keyword m> ..."
-getKeywordBuf <id> [useChRec] [filter <id>]
Description: Returns all keyword currently stored in the
object, or a subset if a filter is specified.
Reply Buffer: "<#>,<keyword n> <value n>,<keyword m> ..."
-noOfKeywords <id>
Description: Returns the number of keywords currently
stored in the referenced object.
Reply Buffer: "<#>"
-getValue <id> <keyword no>|<keyword>
Description: Get the value of a keyword referenced either
by its name or its number.
Reply Buffer: "<value>"
-resetKeywordPtr <id>
Description: Reset the pointer to the list of keywords in
the object. Used to return keywords
sequentially.
-getNextKeyword <id>
Description: Return the sequential next keyword in the
object. When the last keyword has been returned
the subsequent call will return an empty error
message.
Reply Buffer: "<keyword> <value>"
-storeKeyword <id> <keyword> <value>[ after <keyword>] \
[<keyword> <value>[ after <keyword>]]
Description: Store one or more keywords in the object. The
format of the keywords must be Short-FITS.
The "after" option can be sued to specify a
location in the objects keyword list.
-removeKeyword <id> <keyword> [<keyword>]
Description: Remove one or more keywords from the object. The
format of the keywords must be Short-FITS.
-load <id> <[path]filename[.<ext>]> [filter <id>] \
[updateOnly]
Description: Load a Short-FITS File into the referenced
object. If "updateOnly" is specified, only
keywords already stored in the instance will
be updated.
-save <id> [useChRec] [filter <id>] [saveComments] \
[saveIncludedKeys]
Description: Save the contents of the instance into a
Setup File. Prior to that a filename must have
been attached to the object by means of the
-saveAs parameter or the -setShortFitsFile
parameter.
It is possible to extract certain keywords by
specifying the usage of the Change Record or a
filter.
If another Short-FITS File Header than the
internal one in the object is required, this
can be given in as well.
If the Short-FITS File already exists, it is
overwritten silently if writable.
The "saveComments" option can be used to
indicate for OSLX to store the comments there
might be in connection with the keywords as
well.
If "saveIncludedKeys" is specified, possible
included keys will be saved in the file.
-saveAs <id> <[path]filename> [useChRec] [filter <id>] \
[saveComments] [saveIncludedKeys]
Description: Generate a Short-FITS File from the keywords
stored in the object. The new Short-FITS File
will be stored as:
"$INS_ROOT/$INS_USER/MISC/<filename>"
if not the complete path is given. The complete
path can be specified e.g. as:
"$INS_ROOT/$INS_USER/MISC/MY_DIR/myFile.config"
Note that INS_USER and INS_ROOT can be modified
dynamically (GEN command).
The "saveComments" option can be used to
indicate for OSLX to store the comments there
might be in connection with the keywords as
well.
-setShortFitsFile <id> <[path]<filename>>
Description: Attach a Short-FITS Filename to the object.
-copy <id> source <no2> [useChRec] [filter <id>]
Description: Copy all or a number of keywords in the
OSLX Short-FITS instance <no2> into the
instance <id>.
The utility is used to compile Extended TSFs into standard TSFs. The
Extended TSFs contains PAF.INCLUDEs and various other tags that need
to be resolved for obtaining a Standard TSF;
The include files are first search according to the path given by INS_USER_PATH
env. variable, or if it is not set in the directory $INS_ROOT/SYSTEM/COMMON/TEMPLATES/TSF
When the include files are not found at this location the search continues according
to the following path ./:../include:$INTROOT/include:$VLTROOT/include:
Please check the OSLX User Manual/Revision 1.3+ for more information.
The Extended TSFs must have the extension ".tsfx". It is recommended
to store these in the Template module in a directory named "tsfx" and
to output the compiled TSFs to a directory e.g. called "tsf".
The file that is given on the commandline to be compilled must be in the current
directory. Command line options (-sd -si) are available to add searchpath of the
file to be compilled.
If the "-i" option is specified the compiler runs interactively and
the user has the option of the following actions after each compilation:
[start output compiler]
...
Compiling file:
/home/ins1b/jknudstr/del/sotpl/tsfx/sotplSoStare.tsfx
Target File:
/home/ins1b/jknudstr/del/sotpl/tsf/sotplSoStare.tsf
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Do you want to compile other file(s) (y/n/r/d/<unix cmd>) [y]?
[end output compiler]
- whereby:
y: Means to make another compilation specifying again input
file(s) and output directory.
n: Exit the compiler.
r: Repeat the last compilation.
d: Re-load the Dictionaries.
<unix cmd>: Execute any UNIX command like "ls", "more <file>", etc.
Input parameters:
<file> [<file>] List of one or more files to be compiled.
It is possible to use wildcard "*" to terminate
a filename. Input files must have extension ".tsfx".
-si search the file to be compilled according to path given by
the env. var $INS_USER_PATH
Note, that files given are searched in the current directory first,
regardless the content of the $INS_USER_PATH.
If $INS_USER_PATH is not set the files are searched in directory
$INS_ROOT/$INS_USER/COMMON/TEMPLATES/TSF
If both -si and -sd are set the file first will be searched accoding to
default path (-sd) and then according to INS_USER_PATH.
Wildcards "*" in filenames are not supported.
-sd search the file to be compilled according to the default path:
., ../include, INTROOT/include,VLTROOT/include
If both -sd and -si are set the file first will be searched accoding to
default path and then according to INS_USER_PATH.
Wildcards "*" in filenames are not supported.
-o <output directory> The output directory to where the compiled TSFs
are written.
[-dictionary <dic>] Dictionary to use when parsing the TSFs. If not
defined default value is "all", i.e. all
Dictionaries are loaded. Otherwise one or more
Dictionaries can be specified: "MY_DIC",
"DIC1|DIC2|DIC3".
-i Run in interactive mode. In this mode the
compiler will ask the user if he wants to
perform another compilation before exiting.
-noCheck <prefix> don't check keywords with the given prefix in the dictionary
The 'prefix' can be a comma-separeted list of prefix-es.
(Optionally the -noCheck <prefix> can be repeated on the commandline.)
oslxReadPixels myfile -topLeft x1,y1 -size s
oslxReadPixels myfile -topLeft x1,y1 -size s -ext i
oslxReadPixels myfile -topLeft [x1,y1] -size s
oslxReadPixels myfile -topLeft [x1,y1] -size s -ext i
oslxReadPixels myfile -topLeft x1,y1 -bottomRight x2,y2
oslxReadPixels myfile -topLeft x1,y1 -bottomRight x2,y2 -ext i
oslxReadPixels myfile -topLeft [x1,y1] -bottomRight [x2,y2]
oslxReadPixels myfile -topLeft [x1,y1] -bottomRight [x2,y2] -ext i
oslxReadPixels myfile -topLeft x1,y1 -size s -ext i
oslxReadPixels myfile -topLeft [x1,y1] -size s -ext i
List 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.
where:
x1,y1,x2,y2 are the coordinates of the points i.e.
row and column numbers. Note that the first pixel is
[1,1] and NOT [0,0].
s is the size, i.e. the number of pixels to be print out
in the rows and clumns (integer)
ext extention number
Note: The coordinates can be given without the square brackets to avoid
use of escape characters in tcl code.
This program opens the file and checks that the HDU is a 1D or
2D image. It then allocates memory
to hold 1 row of pixels, and loops through
the image from top to bottom reading and printing out each row.
The data format of the image (integer or floating point) determines
the output display format that is used for the pixel values.
Note that the program reads the image into an array of doubles,
regardless of the intrinsic datatype of the image.
see also
http://heasarc.gsfc.nasa.gov/docs/software/fitsio/cexamples.html#imlist
oslxReadPixels myfile -topLeft [10,20] -size 5
oslxReadPixels myfile -topLeft [10,20] -bottomRight [20,30]
oslxReadPixels myfile -topLeft [10,20] -size s -ext 2
oslxReadPixels myfile -topLeft 10,20 -size 5
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 print the FITS headers of possible extensions.
If the paramater sort is set 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.
When printing large files the execution time is much improved if the
option sort is not used.
The detailed options can be given to readout fits details: number of
headers, 2880 byte block size of header, image size and total image
size. If an incomplete fits file shall be printed, please not that an
INS_ROOT must be defined.
3.2 CLASSES
The OSLX Alias Class provides services for handling the aliasing in VLT
applications. Conversion is performed in a fast manner using an internal
Hash Table. Methods are provided to convert both ways.
For the proper functioning of the object an alias table must be loaded.
The format of this is:
<short-FITS keyword1> <alias1>
<short-FITS keyword2> <alias2>
.
.
.
The keywords must be given in the Short-FITS format. The aliases
can be any string. The name of the dictionary must be <context>.alias.
Comments can be written in the Alias Conversion Table using the hash sign
"#".
Aliasing is typically used in connection with the SETUP command where
a shorter, more user-friendly designation for a function is required.
If the entry to be converted does not exist the methods return with
FAILURE.
oslxALIAS(slxALIAS_TAB_NAME aliasTable = NULL)
It loads an Alias Conversion Table during the initialization if this is
sp[ecified.
~oslxALIAS()
Destructor method that cleans up the memory used by the object.
ccsCOMPL_STAT Load(const slxFILENAME aliasTableName,
const vltLOGICAL merge = FALSE)
ccsCOMPL_STAT Unload()
Methods to load/unload an Alias Conversion Table. If the object already
contains an Alias Conversion Table this is deleted.
During loading if "merge" is TRUE the present Alias Table stored will
not be deleted.
If "aliasTableName" is "ALL" all Alias Tables found will be loaded.
It is also possible to specify a list of Alias Tables to be loaded
as "<name1>|<name2>|...".
ccsCOMPL_STAT GetAlias(const slxKEYW_LINE keyword, slxALIAS alias) const
Method to find the corresponding alias for a keyword. The keyword should
only be the keyword part of the Short-FITS keyword line.
ccsCOMPL_STAT GetKeyword(const slxALIAS alias, slxKEYW_LINE keyword) const
Method to convert an alias into the corresponding Short-FITS keyword.
vltLOGICAL IsAlias(const slxKEYW_LINE name,
slxKEYW_LINE keyword = NULL)
Check if the given key name is an alias. If yes it returns true
and, if a buffer is given in for the keyword, the keyword is
returned. If the key name given is a keyword or unknown FALSE is
returned.
ccsCOMPL_STAT ResetRecordPtr()
vltLOGICAL GetNextRecord(slxKEYW_LINE keyword,
slxALIAS alias)
Methods to navigate through the Alias Table loaded into memory. Before
starting traversing the table the ResetRecordPtr() method must be called.
When there are no more records in the table, GetNextRecord() returns
with FALSE and "keyword/alias" will be strings of length 0.
The class is used to handle Configuration Files, this implies reading,
generating and modifying these files. The class distiniguishes between
2 different kinds of Configuration Files:
o Instrument Configuration Files.
o Instrument Reference Configuration Files.
The meaning and usage of these files is defined in the document:
INS Common Software Specification, VLT-SPE-ESO-17240-0385.
It is not possible to mix up the 2 different kinds of Configuration
Files in the same object.
For further information about the class, check the parent class
oslxSHORT_FITS which provides a large part of the methods.
NOTE: For the moment the class does not support any methods for checking
Configuration Files against Reference Configuration Files, nor to
check Setup Files against a certain Instrument Configuration File. Will
be supported in a later release.
**** Constructor/Destructor Methods ****
oslxCONFIG(const oslxDICTIONARY *dictionary = NULL,
const oslxALIAS *alias = NULL)
Constructor method that associates a dictionary to the object and
an Alias Conversion Table (optional). Note, that if a reference to a
Dictionary is not passed on to the object, a Dictionary must be made
available using the SetDictionary() method.
WARNING: missing indeces in the keywords can cause error
Please see the manpage of oslxDICTIONARY
~oslxCONFIG()
Destructor method cleaning up memory etc.
ccsCOMPL_STAT LoadConfigFile(const slxFILENAME fileName,
const slxCONFIG_TYPE type,
oslxKEYW_FILTER *filter = NULL)
Load a Configuration File into the object. The "type" can be either
slxINS_CONFIG_FILE or slxREF_CONFIG_FILE. If a filter
is given in, only keyword lines matching the filter will be loaded.
When the envvariable INS_ROOT is not set the whole path has to be
supplied for the filename.
ccsCOMPL_STAT SaveConfigFile(const slxCONFIG_TYPE type,
const slxFILENAME fileName,
const vltLOGICAL useChangeRecord = FALSE,
oslxKEYW_FILTER *filter = NULL,
const vltLOGICAL saveComments = FALSE,
const vltLOGICAL saveIncludedKeys = FALSE)
Save a Configuration File.
INS_ROOT Defines the root directory of the INS directory structure
used by this application.
INS_USER Defines the current working point in the INS directory
structure. Could e.g. be "SYSTEM".
Missing indeces in the keywords used in the configuartion file can cause
'keyword not found in dictionary' error.
Please see the manpage of oslxDICTIONARY.
The OSLX Dictionary Class provides an on-line dictionary for fast access
to the definition of the VLT FITS keywords (setup, header etc.). The
VLT Dictionaries, define all the keywords used for a context, e.g. an
instrument (see Data Interface Control Document, GEN-SPE-ESO-00000-0794).
When a keyword is searched and found in the dictionary, internal members
hold the values for the record entries; these can be returned by using
the record entry methods (KeywName(), KeywClass(), KeywContext(),
DicKeywType(), ValFormat(), KeywUnit(), ComField(), Description()).
Note that the keyword name (e.g. "HIERARCH ESO DET DIT"), will appear in
the Short-FITS format (i.e. as DET.DIT).
WARNING: See Cautions at the end of the manpage before using indexed keywords.
oslxDICTIONARY()
Initilizes an instance of the OSLX Dictionary Class. A Dictionary can be
loaded with the LoadDic() method afterwards.
virtual ~oslxDICTIONARY()
Destructor method to clean up the memory used by the object.
ccsCOMPL_STAT ResetDic()
Method to reset the object. Includes deleting a possible dictionary loaded
into the internal Hash Table.
ccsCOMPL_STAT LoadDic(const slxDICTIONARY dictionary,
const vltLOGICAL merge = FALSE)
Method to load a Dictionary. If "merge" is FALSE a dictionary already
loaded will first be deleted, otherwise the one(s) already loaded are
merged with the new one. I.e., if the a keyword appears several times,
the last occurrence is the one stored in the Dictionary.
In "all" is given in as "dictionary", all Dictionaries stored in the
INS Tree will be loaded and merged. The loading will be done in
alpabetically order.
ccsCOMPL_STAT UnloadDic()
Method that unloads a Dictionary currently loaded into the object.
ccsCOMPL_STAT GetDicName(slxDICTIONARY fullDictName)
Returns the name of the dictionary in the format of:
ESO-VLT-DIC.<scope>-<version>
In the fits headers the name of the dictionary should be given in this
format by the keyword <cat>.DID.
Note that when dictionaries are merged the name of the last
dictionary is returned.
When the revision is given as '$Revision: 1.253 $' instead of a
number, the number will be extracted from the string and placed under
<version>.
dictionary must be loaded before function this function is called.
slxHASH_TABLE GetDictionary()
Returns pointer to the Dictionary Hash Table.
ccsCOMPL_STAT ResetRecordPtr()
vltLOGICAL NextRecord()
Used to step through the dictionary. The method ResetRecordPtr() must
be called prior to calling the NextRecord() method the first time.
The method returns FALSE when there are no more records in the Dictionary.
The attributes of the Dictionary Record can be accessed through the
the methods KeywName(), KeywClass() etc.
ccsCOMPL_STAT LookUp(const slxKEYW_LINE keywordLine)
Looks up a keyword entered as a complete line. The keyword line can
either in the Normal Hierarchical format, or the Short-FITS format.
ccsCOMPL_STAT LookUp2(const char *keyEl1, ..., NULL)
Looks up a keyword given in as its individual components, e.g.
LookUp("CAT", "SUB", "PAR", NULL), or LookUp("PAR", NULL).
vltLOGICAL DicFoundKeyword() const
Returns the status whether the last search for a keyword in the dictionary
was successfull.
char *KeywName()
ccsCOMPL_STAT KeywName(slxDIC_RECORD_ENTRY keyName)
Return pointer to keyword name of the keyword currently refenced (looked
up) or set the same parameter.
char *KeywClass() const
ccsCOMPL_STAT KeywClass(const slxDIC_RECORD_ENTRY keywClass)
Read or set the Keyword Class Specifier.
char *KeywContext() const
ccsCOMPL_STAT KeywContext(const slxDIC_RECORD_ENTRY context)
Read or set the Keyword Context Specifier.
slxPAR_TYPE DicKeywType() const
ccsCOMPL_STAT DicKeywType(const slxPAR_TYPE type)
Read or set the Keyword Type (slxSTRING, slxLOGICAL, slxINTEGER,
slxDOUBLE).
char *ValFormat() const
ccsCOMPL_STAT ValFormat(slxDIC_RECORD_ENTRY format)
Read or set the Value Format of current keyword looked up.
char *KeywUnit() const
ccsCOMPL_STAT KeywUnit(const slxDIC_RECORD_ENTRY unit)
Read or set the Unit Specifier of the current keyword.
char *ComField() const
ccsCOMPL_STAT ComField(const slxDIC_RECORD_ENTRY com)
Read or set the Comment Field Specifier.
char *Description() const
ccsCOMPL_STAT Description(char *descr) const
Read or set the Description Specifier.
ccsCOMPL_STAT DumpRecord(const slxKEYW_LINE keyword,
const vltLOGICAL detailed = TRUE)
ccsCOMPL_STAT DumpDictionary(const vltLOGICAL dumpOnlyKeys = TRUE)
Writes the contents of the Dictionary loaded to stdout. If "dumpOnlyKeys"
is TRUE, only the actual keywords are dumped, otherwise the complete
Dictionary records are dumped.
ccsCOMPL_STAT MatchKey(const slxKEYW_LINE key)
Matches the "key" given in trying to find keys in the Dictionary
macthing this pattern. An internal list is build up with the matching
keys. This list can be retrieved with the method MatchKeyList().
char *MatchKeyList()
Return pointer to buffer containing the list of keys matching the pattern
of MatchKey(). The keys are listed as: "<key 1>,<key 2>, ...".
char *BestFit()
Returns the best fit ~best completion of the key entered in the MatchKey()
method.
vltINT32 BestFitHits()
Return the number of keys matching the best fit.
ccsCOMPL_STAT StoreKeyword(const slxKEYW_LINE keyword,
const slxKEYW_LINE classList,
const slxKEYW_LINE context,
const slxKEYW_LINE type,
const slxKEYW_LINE valueFormat,
const slxKEYW_LINE unit,
const slxKEYW_LINE comment,
const char *description,
const vltLOGICAL sort = TRUE);
ccsCOMPL_STAT DeleteKeyword(const slxKEYW_LINE keyword = NULL)
Add or delete a keyword in the Dictionary in the object. If the keyword
exists when writing, the old definition is overwritten.
ccsCOMPL_STAT SaveDic(const slxDICTIONARY dictionary)
Save the keywords stored in the object into a file.
ccsCOMPL_STAT SortList()
Sort the list of keyword in the object. The sorting is a simple
alphebetical sort.
The Dictionaries must have the format specified in "Data Interface Control
Document", (GEN-SPE-ESO-00000-0794).
The indexed keyword must be handled with care (VLTSW00980470)
When indexed keywords are stored in the dictionary it is recommended that all the indeces
are supplied when using the keyword. Ommitting indeces in simpler cases are allowed,
nevertheless in many cases error message 'keyword not found in dictionary' is returned.
(The experience is that that you will have to supply at least N-1 indeces).
Should you encounter problem omitting the indeces there are two workarounds exist:
1) Simply add an index 1 to the category the index of which you whish to omit.
2) Add the required keyword (with less indeces) to the dictionary
(note that you can also use the StoreKeyword function to add the keyword dinamically
to the dictionary as the example at the bottom of this manpage shows)
The OSLX FITS Class provides services for doing the following operations
on FITS data files:
o Create FITS header keywords and write these in the header.
o Edit the header of an existing data file in the FITS format.
This could e.g. be adding new keywords or changing the value of
existing ones.
o Analyze the contents of FITS files. This is information such as
header size, data size, data type, etc., or to retrieve keywords.
If a new FITS file is created, the method CreateFile(...) must be used,
specifying the name of the file, the number of FITS blocks to reserve for
the header, and if the "END" keyword should be written. If keywords
created are written to the local buffer, it is up to the calling
application to call the Save() method to write the contents to the
referenced file.
If an existing FITS header is updated with new keywords, the method Save()
is called after having issued the new keywords to the object. The new and
the old keywords are merged together. In case of redundancy, the
new keywords overwrite the old ones. The existing Comments and Logs remain
in the header and the new ones written after in the header.
If an instance of the class works on an existing FITS data file, the
object must load the header of the data file using the LoadHeader()
method.
The object is first operational when a Dictionary is available. The
Dictionary can either be loaded in, and generated in the object, or
a reference to an existing instance of the OSLX Dictionary class given in
at start up. The latter has the advantage, that this Dictionary can be
shared by several instances, and that the application itself can use the
Dictionary. This may save quite some memory in case of big Dictionaries.
See Cautions at the end of the manpage before using indexed keywords.
Note, if FITS Files containing unknown keywords are loaded, the object
will stop the loading a return with an error. It is possible to make
the object try to add an unknown keyword automatically by envoking
the AutoAddKeysInDic() method. It is also possible to make the object
ignore unknown keywords by using the flag "ignoreUnknownKeys".
Handling of the FITS Image Extension is implemented in the following way:
Whenever oslxFITS encounters headers belonging to extensions, it
internally creates objects of oslxFITS in which to store the keywords
of these. This is done transparent for the user. With the method
NoOfHdrs() the number of headers contained in the object is returned.
The 'main' header of a FITS file has number 1. With the method GetHdr()
it is possible to get a reference to a specific header in the object
and to manipulate this as a normal instance of oslxFITS, i.e. all
methods are available. See also GetHdr().
oslxFITS(const oslxDICTIONARY *dictionary = NULL)
Creates and prepares an instance of the class. A reference to an external
Dictionary can be given in. Note, that if a reference to a Dictionary is
not passed on to the object, a Dictionary must be made available
using the SetDictionary() method before starting to use the object.
~oslxFITS()
Destructor method that cleans up the object.
ccsCOMPL_STAT Reset()
Method to reset the object. Each keyword added to the object hereafter
will be stored when the Save() method is called. However all keywords
stored in the object will be kept and only the values updated when
they are issued again, in order to save time when adding keywords in the
object.
void ClearInstance()
Clear the object and release all resources in use. Envoking this method
will delete the internal Hash Tables used e.g. for storing keywords.
void SortKeywords(const vltLOGICAL state)
vltLOGICAL SortKeywords()
Switch on/off the ordering of the keywords in the FITS Header.
ccsCOMPL_STAT LoadHeader(const slxFILENAME fileName,
const vltLOGICAL merge = FALSE,
oslxKEYW_FILTER *filter = NULL,
const vltLOGICAL dontWriteChKeys = FALSE,
const vltLOGICAL ignoreUnknownKeys = FALSE)
Load the FITS header of the data file. The filename of the object is set
to this filename. If "merge" is TRUE, the object will not be reset, but
the contents of the new header merged with the contents in the object.
If a filter is specified, only keywords matching the filter will be
stored in the object.
If the flag "dontWriteChKeys" is set TRUE, a keyword already stored in
the object which has been changed since the last reset of the Change
Record will not be overwritten.
If "ignoreUnknownKeys" is specified, the object will not return with a
FAILURE if an unknown keyword is encountered.
The header loaded may be an ordinary ASCII file, i.e. a text file with
FITS keyword lines. Only condition is that each line is terminated
with '\n', and that no line exceed 256 characters in length.
ccsCOMPL_STAT Copy(oslxFITS &srcObj)
Copy over keywords from one instance of oslxFITS to the instance
envoking Copy().
ccsCOMPL_STAT SetKeySequence(const char *keySequence)
Set the sequence of FITS Keywords in the header of the FITS File.
The list must be given as (e.g.): "SIMPLE,BITPIX,NAXIS,NAXIS1,NAXIS2".
A Dictionary must be available.
ccsCOMPL_STAT LoadImageFile(const slxFILENAME fileName);
Method to load a FITS image file. Header of image is automatically
loaded.
ccsCOMPL_STAT SaveImageFile(const slxFILENAME fileName = NULL);
Saves the image header and the image itself into a file.
ccsCOMPL_STAT StoreImage(const char *image,
const vltINT32 size);
Method to store a FITS image file into the image buffer of the object
char *Image();
Method to return pointer to the image buffer.
vltINT32 ImageSize();
Method to return size of the image stored in the object's image buffer.
The image size returned is the total allocated size. The total size is
therefore returned as multiple of an HDU block (2880 bytes block).
See also the method ccsCOMPL_STAT ImageSize(vltINT32 *imageSize) below.
void ResetCommentList()
Sets the comment counter to zero but does not free the memory occupied
by the Comment List. This can be used to save time when building up
a new set of comments for a FITS header, since it is thus not necessary
to allocate memory for each comment added.
ccsCOMPL_STAT ClearAllAuxKeys()
Clear all comments, logs and history keys stored in the object.
ccsCOMPL_STAT ClearCommentList()
Frees the memory occupied by the comments.
ccsCOMPL_STAT AddComment(const slxKEYW_LINE comment)
Adds a comment to the Comment List of the object. The command should be
the plain text as written after the "COMMENT" keyword.
void ResetCommentPtr()
Makes the Comment Pointer point to the first element in the Comment List.
char *GetNextComment() const
Returns pointer to the sequentially next comment. When the last comment
is read, NULL is returned.
vltINT32 NumberOfComments()
Return the number of comments.
void ResetLogList()
ccsCOMPL_STAT ClearLogList()
ccsCOMPL_STAT AddLog(const slxKEYW_LINE comment)
void ResetLogPtr()
char *GetNextLog() const
vltINT32 NumberOfLogs()
See corresponding functions for comments.
void ResetHistoryList()
ccsCOMPL_STAT ClearHistoryList()
ccsCOMPL_STAT AddHistory(const slxKEYW_LINE comment)
void ResetHistoryPtr()
char *GetNextHistory()
vltINT32 NumberOfHistoryEntries()
See corresponding functions for comments.
ccsCOMPL_STAT CreateFile(const slxFILENAME fileName,
vltUINT16 noOfBlocks)
Method to prepare a new data FITS file. The file will be located in
"$INS_ROOT/$INS_USER/DETDATA", if not the full path is given in.
ccsCOMPL_STAT StoreKeyword(oslxKEYWORD &keyword)
ccsCOMPL_STAT StoreKeyword(const slxKEYW_INFO *keyword)
ccsCOMPL_STAT StoreKeyword(const slxKEYW_LINE keywordLine)
Store a keyword in the object's keyword buffer.
ccsCOMPL_STAT CreateStoreFits(const slxKEYW_LINE keyword,
const char *value)
ccsCOMPL_STAT CreateStoreFits(const slxKEYW_LINE keyword,
const vltINT32 value)
ccsCOMPL_STAT CreateStoreFits(const slxKEYW_LINE keyword,
const vltLOGICAL value)
ccsCOMPL_STAT CreateStoreFits(const slxKEYW_LINE keyword,
const vltDOUBLE value)
Methods to generate and store a FITS keyword in the object. For the last
method the value is passed on as an ASCII string. Use the slxAssKey(),
slxAssKey2() to assemble a keyword from keyword elements.
CAUTION: Note that the method taking the value as a string also accepts
the other three types as strings. The method taking the value
as a void, expects a pointer to the value in the proper 'binary'
format.
Handling of pointer values are now improved and following functions
are also available:
ccsCOMPL_STAT CreateStoreFits(const slxKEYW_LINE keyword,
const vltDOUBLE *value);
ccsCOMPL_STAT CreateStoreFits(const slxKEYW_LINE keyword,
const vltINT32 *value);
ccsCOMPL_STAT CreateStoreFits(const slxKEYW_LINE keyword,
const vltLOGICAL *value);
ccsCOMPL_STAT RemoveKeyword(const slxKEYW_LINE keyword)
Remove a keyword from the internal keyword buffer.
ccsCOMPL_STAT Save(const slxFILENAME fileName,
oslxKEYW_FILTER *filter = NULL)
If "fileName" is NULL initiated, the header keywords are merged into
the file attached to the object. If the header is not big enough to
contain the FITS keywords in the object, it is extended automatically.
ccsCOMPL_STAT SaveAsciiFile(const slxFILENAME fileName,
const vltLOGICAL useChangeRecord = FALSE,
oslxKEYW_FILTER *filter = NULL)
Saves the keywords, comments and logs currently stored in the object into
a readable ASCII file. The file will be located in the
"$INS_ROOT/$INS_USER/DETDATA" directory unless the complete path is
specified. No extension is added.
char *FitsFileName() const
Return pointer to the buffer containing the FITS filename.
ccsCOMPL_STAT ResetFitsHeaderPtr()
ccsCOMPL_STAT GetNextFitsLine(slxKEYW_LINE fitsLine)
Methods to return FITS lines from a FITS file.
ccsCOMPL_STAT GetKeyword(const slxKEYW_LINE keyword)
Search for a keyword line and set the current keyword members
accordingly.
ccsCOMPL_STAT ExtractKeywords(const vltLOGICAL useChangeRecord,
oslxKEYW_FILTER *filter = NULL)
Method to extract a number of keywords from a FITS header. If it is
specified to use the Change Record, only keywords that changed since the
last Reset() will be taken into account. If a filter is specified, only
the keywords matching the specified filter will be selected.
char *GetExtractBuffer()
vltINT32 GetExtractBufferLen()
Returns a pointer, respectively, the length of the buffer containing
the extracted keywords.
ccsCOMPL_STAT ImageSize(vltINT32 *imageSize)
Returns the size (in bytes) of the image in connection with the
fitsheader. The image size is calculated on the information available in
the fitsheader. ImageSize is a function of BITPIX,NAXIS,NAXISi. Therefore
this imageSize does not have to be a multiple of the smallest saving blocks of
2880 bytes. To retrieve the total size saved in the fits file use the method
vltINT32 oslxFITS::ImageSize().
vltINT32 oslxFITS::GetHdrBlocks()
Returns the number of header blocks (2880 bytes)
vltINT32 ReqHdrBlocks()
Return the number of header blocks (2880 bytes) needed for the header.
vltINT32 NoOfHdrs()
Return the number of FITS Header contained in the object. If 1 'main'
header and 3 'extension' headers are stored in the object, 4 is
returned.
vltINT32 NoOfHdrBlocks()
Method to return the number of 2880 blocks used by the header blocks
vltINT32 DataSize()
Method to return the size of data blocks
oslxFITS *GetHdr(const vltINT32 hdrNo)
Return a pointer to a given header in the object. The 'primary/main'
header has number 1. After the reference has been returned there can
be worked on the header instance as normally while working on instances
of the oslxFITS object. E.g.:
oslxFITS *myFits;
if ((myFits = fits.GetHdr(2)) == NULL)
... error handling ...
if (myFits->KeyInBuffer("DET.DIT"))
{
myFits.GetKeyword("DET.DIT");
...
}
vltLOGICAL useChangeRecord = TRUE;
if (myFits->ExtractKeywords(TRUE) == FAILURE)
... error handling ...
printf("\n%s", myFits->GetExtractBuffer());
....
ccsCOMPL_STAT AppendFile(const slxFILENAME targetFile,
const slxFILENAME sourceFile)
Append a the "sourceFile" to the "targetFile" making use of
the FITS Image Extension. Note that this method works entirely on
files and does not change the status of the object.
INS_ROOT Points to the top of the Instrument Directory Tree.
INS_USER Points to the current working point in the Instrument
Directory Tree. Data files will be searched first/stored
in the directory "$INS_ROOT/$INS_USER/DETDATA".
This object expects that the FITS files are properly generated so that
the total size is a multiple of 2880. In addition, that the header
and data block each are a multiple of 2880.
Storing keywords (omitting indeces) in a fits instance, can cause
'keyword not found in dictionary' error. Please see the manpage of oslxDICTIONARY.
The oslxFITS_EXT class is a new version of oslxFITS class.
The oslxFITS_EXT class incorporates the main fetures of the oslxFITS
class , and in addition extention handling and support for Binary Tables.
(The class makes use of the publicly available cfitsio module.)
The class provides services for doing the following operations
on FITS data files:
o Create FITS header keywords and write these into the specified HDU.
o Edit the header of an existing data file in the FITS format.
This could e.g. be adding new keywords or changing the value of
existing ones.
o Analyze the contents of FITS files. This is information such as
header size, data size, data type, etc., or to retrieve keywords.
If 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 "_tmp" is included).
The file must be saved using the function SaveImageFile().
When the file is a complete fitsfile (i.e. all the compulsory keywords
are present) the file will be saved with the name given as argument of
CreateImageFile.
It is also allowed to specify a (different) filename
as argument of the SaveImageFile().
If an existing FITS file is to be updated with new keywords, the function
LoadImageFile(char * filename,vltLOGICAL update=ccsFALSE) has to be
called.
When the argument 'update' is ccsFALSE, overwriting of the existing
imagefile is not allowed. In this case imagefile name for the updated
file has to be specified during saving the file.
(If no othername is given during saving the imagefile
the file will be saved with the name composed from the origfilename
and "_altered" tag.)
It is also possible to extract a particular HDU from a fitsfile using:
LoadHDU(char * filename,vltINT32 hdu) , and save it as a separate file.
The object is first operational when a Dictionary is available. The
Dictionary can either be loaded in, and generated in the object, or
a reference to an existing instance of the OSLX Dictionary class given in
at start up. The latter has the advantage, that this Dictionary can be
shared by several instances, and that the application itself can use the
Dictionary. This may save quite some memory in case of big Dictionaries.
Note, if FITS Files containing unknown keywords are loaded, the Load
functions will return with an error. It is possible to add an unknown
keywords automatically by envoking the AutoAddKeysInDic() method.
Keywords in the current HDU can be merged with keywords in other file's
HDU using the function MergeHDUKeywords.
The keywords in the HDU-s are sorted according to a given reference list.
Sorting can be swithed of when required using by:
SetSortType(oslxSORTTYPE_NO_SORT).
In case the imagefile contains extention(s) the HDU can be also specifed
for most functions that are operating on the HDU. (e.g. adding or
removing keywords from the HDU. When HDU is not specified either the
current or the primary HDU is taken as defult depending on the give
function (see description at the 'public methods' below).
The current HDU can be selected using the MoveTo() functions.
Binary Table extentions are also supported.
oslxFITS_EXT(const oslxDICTIONARY *dictionary = NULL)
Creates and prepares an instance of the class. A reference to an external
Dictionary can be given in. Note, that if a reference to a Dictionary is
not passed on to the object, a Dictionary must be made available
using the SetDictionary() method before starting to use the object.
~oslxFITS_EXT()
Destructor method that cleans up the object.
void Reset()
Method to reset the object. It should be called if the object is used
for creating/modifying more files. When the previously
loaded/treated file is not yet saved Reset() attempts to save it as a
<fname>_tmp.fits file.
During reset the dictionary is not unloaded. If this is required call the
function UnloadDictionary();
void Cancel()
This method also resets the object. The difference between Reset() and
Cancel() is that that Cancel() also DELETES THE FILE. This can be useful
in cases where a FITS file has been partially created, but then an error
occurs which prevents it from being completed.
During this function the dictionary is not unloaded.
In order to unload the dictionary use the function UnloadDictionary();
ccsCOMPL_STAT RemoveFile(char *filename);
Removes the given file from the directory $INS_ROOT/$INS_USER/DETDATA.
ccsCOMPL_STAT RemoveTmpFiles(char *filename);
Removes all the temporary files that can be associated with the given
filename.
i.e.: basefilename_tmp.ext,
basefilename_update_tmp.ext ,
basefilename_altered_tmp.ext
Important: During the operation on a fitsfile it is forbidden to
remove its tmp file. This would lead to uncertain behaviour!!
ccsCOMPL_STAT CreateImageFile(char * filename,
vltLOGICAL isFitsExt=ccsTRUE);
Creates a new image file.
Files with names "<fname>.fits" and "<fname>_tmp.fits" (where <fname> is
the filename without the extention) should not exist before the
function is called. File has to be saved using the SaveImageFile()
function. In case of error during operation on the file or saving the
file the file is saved as "<fname>_tmp.fits".
As default (isFitsExt=ccsTRUE) the filename is extended with ".fits"
extention if it does not end with ".fits" it already. In case the
imagefile name should have different extentention the second argument
(isFitsExt) has to be set to ccsFALSE.
ccsCOMPL_STAT LoadImageFile(char * filename,vltLOGICAL update=ccsFALSE);
Load an image file. If update is ccsTRUE file will be overwriten during
SaveImageFile(), unless other filename is specified during saving the
image.
When 'update' is ccsFALSE overwriting of the existing imagefile is
not allowed. In this case, when filename is not specified during saving
the image (i.e. SaveImageFile()), the file will be saved as
<fname>_updated.fits.
ccsCOMPL_STAT LoadHDU(char * filename,vltINT32 hdu);
Extract the given hdu from the file in order to modify it and save it
with a differnt name. If filename for the new file is not specified file
will be saved as <fname>_altered.fits
ccsCOMPL_STAT Append(char * filename);
Append a whole fitsfile to the current file. The the keyword XTENSION
will be automatically added to the primary HDU of the appended file.
ccsCOMPL_STAT AppendHDU(char * filename,vltINT32 hdu);
Append the given HDU of the named file to the current
(to the end of) imagefile.
ccsCOMPL_STAT AppendExtentions(char * filename);
Append all extentions of the named file to the imagefile.
ccsCOMPL_STAT AppendBinaryTables(char * filename);
Append all binary table extentions of the named file to the image.
ccsCOMPL_STAT MergeHDUKeywords(char * filename,vltINT32 hdu);
Merge the keywords of the given hdu of the given file with the keywords
in current hdu of the imagefile.
The file given as argument must be a proper fitsfile.
(Note that any file that has been properly saved by this
class is a complete fitsfile.)
ccsCOMPL_STAT MergeHDUKeywords2(char * headerFile);
Merge the keywords in the 'headerFile' with the
current hdu of the imagefile. Existing keywords will be overwritten.
The file given as argument of MergeHDUKeywords2 must be a
(complete or incomplete) header file.
Tipically this function should be used to handle the headerfiles
produced by e.g. TCCD and FIERA : '*.fits.det'
ccsCOMPL_STAT MergeBufferOfKwLines(char *kwLineBuf, vltINT32 hdu)
Merge header hdu with the buffer 'kwLineBuf' containing keywordlines.
ccsCOMPL_STAT SaveImageFile(char *filename="",
vltLOGICAL isFitsExt=ccsTRUE);
Save the image file in the $INS_ROOT/$INS_USER/DETDATA with the given
name. File with the same name should not exits. When filename is not
given, the file will be saved according to the descriptiion given at
CreateImageFile, LoadImageFile, LoadHDU. During the saving the HDU-s are
checked for the compulsory keywords, and the keywords are sorted
according to the reference list.
When the file is to be saved with other then ".fits" extention,
the second argument (isFitsExt) has to be set to ccsFALSE.
ccsCOMPL_STAT CreateStoreFits(const slxKEYW_LINE keyword,
const vltDOUBLE value,
int hdunum=oslxCURRENT_HDU );
ccsCOMPL_STAT CreateStoreFits(const slxKEYW_LINE keyword,
const vltINT32 value,
int hdunum=oslxCURRENT_HDU );
ccsCOMPL_STAT CreateStoreFits(const slxKEYW_LINE keyword,
const vltLOGICAL value,
int hdunum=oslxCURRENT_HDU );
ccsCOMPL_STAT CreateStoreFits(const slxKEYW_LINE keyword,
const char *value,
int hdunum=oslxCURRENT_HDU );
This functions add a new keyword to the the specified header.
When 'hdunum' is not specified, the kewyword is added to the current HDU.
When 'hdunum' is specified, after the function is executed the current
hdu will be set to the given hdu.
ccsCOMPL_STAT DeleteFitsKeyword(const char *keyword,
int hdunum = oslxCURRENT_HDU,
vltLOGICAL resetHDU = ccsTRUE );
Deletes a keyword with the sepcified name from the given hdu.
If reset hdu is ccsTRUE, the current hdu after the function is executed
will be the given hdu. Otherwise the current hdu will remain as before
the function is called.
ccsCOMPL_STAT RemoveKeyword(const slxKEYW_LINE keyword,
int hdunum = oslxCURRENT_HDU,
vltLOGICAL resetHDU = ccsTRUE);
Method to remove a keyword from a fits file
ccsCOMPL_STAT AddComment (char * comment,
int hdunum = oslxCURRENT_HDU );
ccsCOMPL_STAT AddHistory (char * history,
int hdunum = oslxCURRENT_HDU );
Add comments and history to the header.
ccsCOMPL_STAT ReadKeywordValue(const char *keyword,
vltINT32 *value);
ccsCOMPL_STAT ReadKeywordValue(const char *keyword,
vltDOUBLE *value);
ccsCOMPL_STAT ReadKeywordValue(const char *keyword,
vltLOGICAL *value);
ccsCOMPL_STAT ReadKeywordValue(const char *keyword,
char *value);
These functions retrieve the value of the given keyword from the header.
(When extentions are present the keyword is read from the current HDU).
Error is returned when keyword is not found in the dictionary or the type
of the keyword does not match. Error is returned also when keyword is not
found in the header.
ccsCOMPL_STAT ReadKeywordStringValue( const char *keyword,
char* value );
Retrieves the keyword from the header (current HDU) as string
regardless of the actual type of the kw.
Error is returned when keyword is not found in the header.
See examples of usage of the function under 'EXAMPLES'.
ccsCOMPL_STAT GetNumberOfKeywordLines(vltINT32 hdu, vltINT32* numOfKw);
Retrieves information of the number of keywordlines from the specified header
ccsCOMPL_STAT GetKeywordLine(vltINT32 lineNumber, slxKEYW_LINE keyWordLine);
Retrieves the keyword stored for the current header.
ccsCOMPL_STAT Sort()
ccsCOMPL_STAT SortKeywordsInHDU(vltINT32 hdu=1);
Sorts the keyword according to inner reference list. Sort() will organise
the keywords in all HDUs.
The keywords that are not on the list are placed in alphabetical order
after the list.
void SetSortType(vltINT32 type=oslxSORTTYPE_REFLIST_ABC);
Specifies wheter and how the keywords in the headers should be sorted.
The argument 'type' can have the following values:
oslxSORTTYPE_NO_SORT
oslxSORTTYPE_REFLIST
oslxSORTTYPE_REFLIST_ABC
To swich off the sorting give oslxSORRTYPE_NO_SORT as argument.
Default sorttype is oslxSORTTYPE_REFLIST_ABC. In this case the keywords
are sorted according to inner reference list. The keywords that are not
on the list are placed in alphabetical order after the list.
When sorting type oslxSORTTYPE_REFLIST, the keywords that are not on the
list are not sorted. They are placed after the ordered list in the same
order as before.
vltINT32 GetSortType();
Returns the type of the sort:
oslxSORTTYPE_REFLIST_ABC,
oslxSORTTYPE_REFLIST, or
oslxSORRTYPE_NO_SORT
vltLOGICAL IsBinaryTable(vltINT32 hdu=oslxCURRENT_HDU);
Returns TRUE when the specified HDU is a binary table.
ccsCOMPL_STAT NoOfHdrBlocks(vltINT32* noOfBlocks)
Returns the number of 2880 blocks used by the current header
ccsCOMPL_STAT NoOfAllocHdrBlocks(vltINT32* noOfBlocks)
Returns the number of 2880 blocks allocated by the current header
ccsCOMPL_STAT AllocatePrimaryHeaderSize(vltINT32 nbFitsKewords)
Sets the primary header size of the created fits file. For binary tables the
size is set directly during the creation with a parameter in the method
CreateBinaryTable
ccsCOMPL_STAT GetHeaderSize(char * headerFile, vltUINT16* numberOfKeywords);
Returns the size of the primary header.
ccsCOMPL_STAT ImageSize(vltINT32* imageSize)
Return the image size (in bytes) of the current HDU.
The image size is calculated on the information available in the fitsheader.
ImageSize is a function of BITPIX,NAXIS,NAXISi. Therefore this imageSize
does not have to be a multiple of the smallest saving blocks of 2880 bytes.
To retrieve the total size saved in the fits file use the method
vltINT32 oslxFITS::TotalImageSize().
Only available for image files.
ccsCOMPL_STAT TotalImageSize(vltINT32* imageSize)
Method to return the total size of the image stored of the current HDU.
The image size returned is the total allocated size. The total size is
therefore returned as multiple of an HDU block (2880 bytes block).
Only available for image files.
ccsCOMPL_STAT MoveToHDU(vltINT32 hdu);
ccsCOMPL_STAT MoveToFirstHDU();
ccsCOMPL_STAT MoveToLastHDU();
ccsCOMPL_STAT MoveToBinaryTable(vltINT32 hdu);
ccsCOMPL_STAT MoveToFirstBinaryTable();
ccsCOMPL_STAT MoveToLastBinaryTable();
ccsCOMPL_STAT NrOfHDUs(int* hdus)
MoveToExtention(char* extname);
These functions are setting the current HDU.
They are only useful when extentions are present.
Moving to a binary table includes a check for the type of the hdu.
The argument 'hdu' is the serial number of the HDU to be moved to.
'hdu' must be bigger then 1 and smaller the the total number of hdu-s
in the file.
The primary hdu : hdu=1,
First extention is hdu=2;
The argument 'extname' is the name of the extention specified by the
keyword EXTNAME.
ccsCOMPL_STAT AddBinaryTable(vltINT32 naxis2, vltINT32 tfields,
char *ttype[], char *tform[],
char *tunit[], char *extname,
vltINT32 hdu=oslxLAST_HDU);
Add binary table after the specified HDU.If hdu is not defined the
binary table is appended at the end of the file.
ccsCOMPL_STAT CreateBinaryTable(vltINT32 naxis2,vltINT32 tfields,
char *ttype[], char *tform[],
char *tunit[], char *extname,
char *filename,
vltLOGICAL isFitsExt=ccsTRUE,
vltINT32 nbFitsKeywords=0);
Creates a new image file and puts an empty binary table in it
(in one step).
This is simply a combination of functions CreateImageFile() and
AddBinaryTable().
ccsCOMPL_STAT AddSimpleColumnToBinaryTable(vltINT32 datatype,
vltINT32 column ,
vltINT32 nelements ,
void *array ,
vltINT32 hdu =oslxCURRENT_HDU);
Adds a one dimensional column to the binary table.
Binary table should be created before this functions is called.
The function overwrites existing elements in the table.
datatype: The datatype must be specified as TSTRING,TSHORT,TLONG,
TDOUBLE, TFLOAT. On the basic types a check is performed whether datatype
corresponds to the type of the given columns.
The arguments of the function are:
column : specifies the column in the bin table to write the data in.
nelements : the number of element to be written into the table.
Must be equal with the size of the array.
Error is returned when 'nelements' is not equal to the
number of rows in the binary table. (No auto add rows.)
hdu : When hdu is given as argument and it is other then the
current HDU the function moves to the specified HDU.
Error is returned when the given HDU is not a binary table.
ccsCOMPL_STAT AddElementsToBinaryTable(vltINT32 datatype,
vltINT32 column,
vltINT32 firstrow,
vltINT32 firstelem ,
vltINT32 nelements ,
void *array,
vltINT32 hdu=oslxCURRENT_HDU);
Binary table should be created before this functions is called.
Overwrites existing elements if given
Move to the given HDU (if it is not the current one).
(return error if it is not a binary table.)
This function can be used to write into multidimensional columns,
or add individual elements.The arguments of the function are:
column : specifies the column in the bin table to write the data in.
firstrow : specifies the first row to where the first element should
be written.
firstelem : specifies the first element in the cell to where the first
elemen of the 'array' should be written.
For one dimentional column firstelem is always 1.
(An element is specified by its column and row.)
nelements : The number of elements to be written into the binary table.
Normally the size of the array but can be smaller.
If smaller only the the first 'nelements' are written into
the bintable.)
Improper array size (nelements) leads to coredump!!
Rows are added automatically when necessary. Warning (log) is given when
this happens. E.g. when there are 5 rows and one writes into a two
dimentional column 10 elements starting from the first element of the
third row (i.e firstrow=3,firstelem=1,nelements=10) then two rows are
added automatically.
ccsCOMPL_STAT ReadElementsFromBinaryTable(vltINT32 datatype,
vltINT32 column,
vltINT32 firstrow,
vltINT32 firstelem ,
vltINT32 nelements ,
void *array,
vltINT32 hdu=oslxCURRENT_HDU);
ccsCOMPL_STAT InsertBlankColumnToBinaryTable(vltINT32 colnum,
char *ttype,
char *tform,
vltINT32 hdu=oslxCURRENT_HDU)
ccsCOMPL_STAT DeleteColumnFromBinaryTable(vltINT32 colnum,
vltINT32 hdu=oslxCURRENT_HDU);
ccsCOMPL_STAT InsertBlankRowsToBinaryTable(vltINT32 firstrow,
vltINT32 nrow=1,
vltINT32 hdu=oslxCURRENT_HDU);
ccsCOMPL_STAT DeleteRowsFromBinaryTable(vltINT32 firstrow,
vltINT32 nrow=1,
vltINT32 hdu=oslxCURRENT_HDU);
The above four functions has no yet been tested thoroughly.
ccsCOMPL_STAT GetSizeOfBinaryTable(long &nrows, int &ncolumns);
ccsCOMPL_STAT CheckKeywordInDictionary(const slxKEYW_LINE keyword,
char *value);
Check the given keywords in the dictionary.
Note: Using the functions of the class the keywords are checked against
the dictionary automaticly.
ccsCOMPL_STAT ChangeCategory(char * category , char * newCategory,
vltINT32 hdu=1)
ccsCOMPL_STAT AddIndexToCategory(char* category,vltINT32 index,
vltINT32 hdu=1)
These functions are modifying the keyword names that include the given
'category'. The first function simply replace the the 'category' with
the given 'newcategory' while the second one just adds an index to the
given category. The new keyword is checked in the dictionary
(unless AutoAddKeysInDic(TRUE) is specified).
Note-1: the first occurance of <category> is replaced in the keyword
Note-2: the <category> is search only inside the keyword, i.e.
Note-3: is allowed to replace two cagories at a time e.g.:
'DET' -> 'XXX1 DET1'
Note-4: the max lengths of 'category' and 'newCategory' are limited
to 16 characters.
ccsCOMPL_STAT ChangeCategoryInHeaderFile(char *hdrFileName,
char *category ,
char *newCategory)
Changes the given <category> to a <newCategory> in the given header file
(which contains no image data), i.e. header files typically created by
ICS DCS and TCS.
ccsCOMPL_STAT OverrideDefaultExtend(vltLOGICAL override)
Gives the user a possibility to override the default setting of the
keyword EXTEND.
EXTEND should always be set to TRUE, even if the file does not contain
extensions. However, a call to this method (with the override parameter
set to TRUE) allows the user to override the default value and set the keyword
to FALSE.
NOTE: It is only possible to override the EXTEND keyword to FALSE if
and only if the fits file does not contain any extensions. If the
fits files contains an extension, the EXTEND keyword will still be
saved as TRUE.
This method shall only be used if the current remmendation, to set
keyword EXTEND to TRUE, can not be followed.
Storing keywords (omitting indeces) in a fits instance, can cause
'keyword not found in dictionary' error.
Please see the manpage of oslxDICTIONARY.
VLTSW20040392: The mandatory keywords types (e.g. BITPIX, NAXIS) are
checked by CFITSIO when a fits file is saved. Other user keywords types
must be checked by the application itself when they are saved with
the method CreateStoreFits.
Please note that the examples below don't include the error handling.
Example1: Create a new image file, add keywords, and save it.
--------
//step 1: declare dictionary
oslxDICTIONARY dict;
if(dict.LoadDic ("ESO-VLT-DIC.CCDDCS",FALSE)!=SUCCESS) {..}
//step 2: create an oslxFITS_EXT instance
oslxFITS_EXT fitsext (&dict);
//step 3: create a new image file
if(fitsext.CreateImageFile(testfile1)!=SUCCESS) {..}
//step 4: add the compulsory keywords (note that without
// saving the image file will return error)
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 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) {..}
//step 7: save the file
if(fitsext.SaveImageFile(testfile1)!=SUCCESS) {..}
Example2: Load the an existing file in (checking dictionary)
-------- Append the first hdu of an existing file
oslxFITS_EXT fitsext2 (&dict);
if(fitsext2.LoadImageFile(testfile1)!=SUCCESS) {..}
if(fitsext2.AppendHDU(testfileX,1)!=SUCCESS) {..}
if(fitsext2.SaveImageFile(testfile2)!=SUCCESS) {..}
Example3: Merge keywords in the current hdu with the keywords in the hdu
-------- of an other completed fitsfile
oslxFITS_EXT fitsext3 (&dict);
if(fitsext3.LoadImageFile(testfile1)!=SUCCESS) {..}
//When there are extentions in the file move to the requied hdu
if(fitsext3.MoveToHDU(1)!=SUCCESS) {..}
if(fitsext3.MergeHDUKeywords(testfile2,1)!=SUCCESS) {..}
if(fitsext3.SaveImageFile(testfile3)!=SUCCESS) {..}
Example4: Merge kws in the current hdu with the keywords in a
-------- header file (i.e. not completed fitsfile)
e.g. merge the files created by TCCD/FIERA
change the sorttype before saving the the imagefile
oslxFITS_EXT fitsext4 (&dict);
if(fitsext4.LoadImageFile("ccdImageLcuSim.fits")!=SUCCESS)
{..}
//When there are extentions in the file move to the requied hdu
if(fitsext4.MoveToHDU(1)!=SUCCESS)
{..}
if(fitsext4.MergeHDUKeywords2("ccdImageLcuSim.fits.det")!=SUCCESS)
{..}
fitsext4.SetSortType(oslxSORTTYPE_REFLIST);
if(fitsext4.SaveImageFile(testfile4)!=SUCCESS)
{..}
Example5: Create a binary table extention
---------
// step 1: create an instance of oslxFITS_EXT
oslxFITS_EXT fitsext (&dict);
fitsext.AutoAddKeysInDic(TRUE);
// step 2: declare parameters
int tfields = 3; // 3 columns
long nrows = 6; // 6 rows
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 (create imagefile and add a binary table
// in one step). Note that primary header is automatically
// created with the compulsory keywords in it.
if(fitsext.CreateBinaryTable
(nrows,tfields,ttype, tform,tunit, extname,testfile1)!=SUCCESS)
{..}
//step4. declare columns
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)
{..}
//step6. save the imagefile
if(fitsext.SaveImageFile(testfile1)!=SUCCESS)
{..}
Example6: Retrieve the value of keywords from the headers
---------
//check keyword and its type in the dictionary
vltLOGICAL logval;
if(fitsext.ReadKeywordValue("EXTEND",&logval)!=SUCCESS)
{..}
slxKEYW_LINE sval;
if(fitsext.ReadKeywordValue("MY.STRING.KEYWORD",sval)!=SUCCESS)
{..}
//retrieve value as string (regardless of the actual type of the kw)
slxKEYW_LINE value="";
if(fitsext.ReadKeywordStringValue("MY.STRING.KEYWORD",value)!=SUCCESS)
{..}
if(fitsext.ReadKeywordStringValue("EXTEND",value)!=SUCCESS)
{..}
The Keyword Filter class is used to filter out certain keywords e.g. from
an OSLX Setup object.
A filter can be constituted by several Sub-Filters. There are two ways
of building up a filter, either by using the method AddFilter() or
by using the AddSymbolicFilter(). The latter is the most convenient
to use.
When Sub-Filters are added using AddSymbolicFilter(), expressions
like "1.5 < DET.DIT < 2.7" can be entered directly. Consult in this
man-page the description of this method for more information.
Using the AddFilter() method Sub-Filters can be added as follows:
Filter: Results In:
-------------- ------------------
1. {GEN}{*}{*} -> take all "GEN.*.*"
2. {GEN}{}{*} -> take all "GEN.*"
3. {}{}{NX} -> take all "NX"
4. {*}{*}{NX} -> take all "*.*.NX"
5. {*}{*}{START*} -> take all "*.*.START*"
In each filter class it is possible to have several subfilters like the
ones listed above. I.e. if the subfilters 1. and 2. are added to an
object the all keywords matching "GEN.*.*" and "GEN.*" will be selected.
It is possible to filter also on the value of the keywords. The value can
either be given as a single value or as a range. The latter does not apply
for logicals.
Subfilters can be added and deleted dynamically. Typically in an
application that has to filter out keywords for various subsystems, e.g.
OS, it would set up a filter for each subsystem at start up, and apply
this filter on an instance of the OSLX Setup class to extract the
necessary keywords for each subsystem.
oslxKEYW_FILTER()
Constructor method to initialize the object.
~oslxKEYW_FILTER()
Destructor method that cleans up the object.
void Clear()
Clears all the filters currently added in the object.
oslxKEYW_FILTER* Clone() const
Allows to clone an instance of the class.
ccsCOMPL_STAT SetDictionary(const oslxDICTIONARY *dictionary)
Make a Dictionary available for the object.
ccsCOMPL_STAT AddFilter(const slxKEYW_LINE keyword)
ccsCOMPL_STAT AddFilter(const slxKEYW_LINE keyword,
const slxKEYWORD_CLASS keywClass)
ccsCOMPL_STAT AddFilter(const slxKEYWORD keyword,
const slxKEYWORD_CLASS keywClass,
const char *lowLim,
const char *upLim = NULL)
ccsCOMPL_STAT AddFilter(const slxKEYWORD keyword,
const slxKEYWORD_CLASS keywClass,
const vltLOGICAL value)
ccsCOMPL_STAT AddFilter(const slxKEYWORD keyword,
const slxKEYWORD_CLASS keywClass,
const vltINT32 lowLim,
const vltINT32 upLim = oslxINT_MAX)
ccsCOMPL_STAT AddFilter(const slxKEYWORD keyword,
const slxKEYWORD_CLASS keywClass,
const vltDOUBLE lowLim,
const vltDOUBLE upLim = oslxDBL_MAX)
Methods to add a filter to the object together with a specific value
or a range for the parameter value, which is used while doing the
matching. In case a specific value is requested for Strings, Integers,
and Doubles, only the "lowLim" needs to be specified as the requested
value.
ccsCOMPL_STAT AddSymbolicFilter(const slxKEYW_LINE symbolicFilter)
Adds a filter of the format:
[<value> <operator>] <keyword> [<operator> <value>]
where can be a string, a logical (TRUE|T|FALSE|F), an integer, or
a double. "<operator>" can be either "=", "<", ">", "<=", ">=".
A keyword must be given in. An example of such a filter is:
10 < DET.DIT < 20
--> Accept the keyword DET.DIT if the value lies in the interval ]10; 20[.
DET.CHIP.NAME = "SBRC256/2"
--> Accept the DET.CHIP.NAME if the value is "SBRC256/2".
NOTE, this method requires the availability of a Dictionary.
ccsCOMPL_STAT DelFilter(const slxCATEGORY category = NULL,
const slxSUBSYSTEM subSystem = NULL,
const slxPARAMETER parameter = NULL)
Delete a filter currently stored in the object.
vltLOGICAL Match(const slxKEYW_INFO *keywordInfo)
Perform a match based on the subfilters in the object and a set of
category (optional), subsystem (optional) and parameter strings. TRUE is
returned if there is a match, otherwise FALSE is returned.
ccsCOMPL_STAT
ApplyFilter(const slxKEYW_INFO *keywordList,
slxCHANGE_RECORD filterList,
const slxCHANGE_RECORD changeRecord = NULL) const
Apply the subfilters in the object on a list of keywords. The "filterList"
will indicate afterwards which SLX Keyword Info Structures that match the
filter. The first SLX keyword Info Structure has number 1.
ccsCOMPL_STAT GetFilter(const vltINT16 filterNo,
slxKEYW_LINE keyword,
slxKEYW_LINE valueMatch)
Get a filter from the object, based on its internal number in the object.
void RejectIncludedKeys(const vltLOGICAL onOff)
Switches on/off rejection of included keys. I.e., if a key is marked
as included (included from another PAF), the filter will not match that
key.
void SetStrictFiltering(const vltLOGICAL onOff)
vltLOGICAL StrictFiltering()
Switch on/off strict filtering for the filter and get the status.
The class contains data members and methods to handle one FITS keyword in
memory. This can be used either for Normal FITS keywords, or for Short-FITS
keywords.
Methods are provided to set and return the parameters of keywords in
a safe manner.
A Dictionary can be loaded which enables the object to decode the value
according to the type when a keyword line is split up in its components.
Note that when loading a Dictionary() using the methods LoadDictionary()
and SetDictionary(), this Dictionary will be global for all instances
of the oslxKEYWORD class. It is however possible, to specify that the
Dictionary loaded/specified should be only for that instance of
oslxKEYWORD.
oslxKEYWORD()
Creates an instance of the class.
~oslxKEYWORD()
Destructor method free'ing memory occupied by the object.
void ClearKeyword()
Clear the data members of the OSLX Keyword Object.
ccsCOMPL_STAT LoadDictionary(const slxDICTIONARY dicName,
const vltLOGICAL local = FALSE)
Loads a Dictionary into the object and builds up a local Hash Table for
that Dictionary. If "local" is TRUE, the Dictionary will be local and
used only by the instance of oslxKEYWORD calling this method, otherwise
the Dictionary will be available for all instances of oslxKEYWORD in
the given context.
ccsCOMPL_STAT SetDictionary(const oslxDICTIONARY *dictionary,
const vltLOGICAL local = FALSE)
Makes the object reference to an external instance of oslxDICTIONARY.
See LoadDictionary() for an explanation of the "local" parameter.
ccsCOMPL_STAT SplitKeyword(const slxKEYW_LINE keywLine)
Split a keyword line into its basic components and set the members of
the object accordingly.
vltLOGICAL ValueValid()
Indicates if the value has been set according to its proper type in
the object, and thus if the methods String(), Logical(), Integer() and
Double(), can be used when a keyword has been split up in its components.
slxPAR_TYPE Type() const
ccsCOMPL_STAT Type(const slxPAR_TYPE type)
Return or set the type of the keyword in the object.
char *String()
ccsCOMPL_STAT String(const char *string)
Return or set the string value of the keyword in the object.
char *LongString()
Return the long string value of the keyword in the object.
vltLOGICAL Logical() const
ccsCOMPL_STAT Logical(const vltLOGICAL logical)
Return or set the logical value of the keyword in the object.
vltINT32 Integer() const
ccsCOMPL_STAT Integer(const vltINT32 integer)
Return or set the integer value of the keyword in the object.
vltDOUBLE Double() const
ccsCOMPL_STAT Double(const vltDOUBLE dbl)
Return or set the double value of the keyword in the object.
char *KeywordLine()
ccsCOMPL_STAT KeywordLine(const slxKEYW_LINE keywLine)
Return or set the value of the keyword as a complete keyword line. Is
returned as the format in which it was stored in the object, i.e. Normal-
or Short-FITS.
char *Category() const
ccsCOMPL_STAT Category(const slxCATEGORY cat)
Return or set the category value of the object.
char *SubSystem(const vltINT32 no) const
ccsCOMPL_STAT SubSystem(const vltINT32 no,
const slxSUBSYSTEM subSyst)
Return or set sub-system of the object.
char *Parameter() const
ccsCOMPL_STAT Parameter(const slxPARAMETER par)
Return or set the parameter of the keyword in the object.
char *ValueString() const
char ValueString(const char *valStr)
Return or set the value of the keyword of the object as a string.
char *Comment() const
ccsCOMPL_STAT Comment(const slxCOMMENT com)
Return or set the value of the comment field of the keyword in the object.
vltINT32 KeywordNo()
Return the number of the keyword.
vltLOGICAL Included()
Return the flag indicating if the keyword has been included.
oslxKEYWORD &operator = (const slxKEYW_INFO &keywordPtr)
Operator that copies the members of an SLX Keyword Structure into the
corresponding members of the object.
Due to the fact that the dictionary in oslxKEYWORD is declared as static
(same dictionary is used by all objects) the dictionary must be handled
by care.
If an already loaded dictionary is overwritten by a method/function
the original dictionary must be restored if it is re-used. It is up to
the user of this class to always make sure that the proper dictionary is
loaded before using any method.
Example:
void worksfine()
{
oslxSETUP setupPtr;
//Load the ISS dictionary as local dictionary only used by worksFine
setupPtr.LoadDictionary("ISS");
slxKEYW_LINE mykw;
strcpy(mykw,"ISS.CHOP.FREQ");
setupPtr.StoreKeyword(mykw,2.0);
setupPtr.DumpKeywords();
//The local ISS dictionary is deleted
}
void doesNotWork()
{
oslxDICTIONARY issDic;
//The global dictionary COU is deleted and ISS is loaded
issDic.LoadDic("ISS");
oslxSETUP setupPtr(&issDic);
slxKEYW_LINE mykw;
strcpy(mykw,"ISS.CHOP.FREQ");
setupPtr.StoreKeyword(mykw,2.0);
setupPtr.DumpKeywords();
//The common dictionary COU is deleted
}
void main(int argc, char *argv[])
{
...
vltLOGICAL okKeyw=ccsFALSE;
//The global dictionary COU is loaded
nicekw.LoadDictionary("COU");
nicekw.SplitKeyword("COU.GUID.RA 3.14159");
//Call function which loads a new dictionary
worksFine();
//The local ISS dictionary was deleted by the destructor and
//the global dictionary COU is in use
nicekw.SplitKeyword("COU.GUID.DEC 2.1417");
printf("%s\n",nicekw.KeywordLine());
//Call function which loads a new dictionary
doesNotWork();
//The global ISS dictionary was deleted by the destructor and
//the global dictionary COU were alrady deleted in the function
//doesNotWork()
nicekw.SplitKeyword("COU.GUID.DEC 2.1417");
printf("%s\n",nicekw.KeywordLine());
}
The OSLX Setup Class is a processor to handle setup keywords in files,
and in memory. The class only operates on keywords in the Short-FITS
format.
The class could typically be used to parse/unpack a message buffer for
the SETUP command, into the local buffer. Afterwards some of the keywords
could be extracted for a specific subsystem.
The object is first operational when a Dictionary is available. The
Dictionary can either be loaded in and generated in the object, or
a reference to an existing instance of the OSLX Dictionary class given in
at start up. This has the advantage, that this Dictionary can be shared
among several instances, and that the application itself can use the
Dictionary. This may save quite some memory in case of big Dictionaries.
See Cautions at the end of the manpage before using indexed keywords.
The Dictionary which is used during operation to check the consistency of
the setup keywords treated.
An Alias Conversion Table can also be associated with the object either as
as reference to an external instance of the oslxALIAS class, or by loading
a local table into the object.
Setup information is stored in a local buffer. When new keywords are loaded
into this, either as single keywords or as a setup file, these keywords
are merged with the ones already stored in the buffer; i.e. the new values
overwrites the old ones. The information in the local setup buffer can be
deleted invoking the ClearSetup() method.
When setup files are loaded into the object, only the name of the last
setup file loaded is kept. If the method Save() is called, the
current contents of the local setup bufer is stored into this
file. An external instance of the OSLX Setup Header Class must be given
in in this connection to set the fields of the Setup Header Appropriately.
It is also possible to call the method SaveAs() to generate a new setup
file (this includes building) a new header.
Main features of the class are:
o Setup check/aliasing.
Check of setup keywords can be performed according to four different
schemes:
1. Normal Check:
Using this Check Type it is checked if the current keyword is
defined by the Dictionary, if yes, the keyword is accepted, if not,
and if an Alias Conversion Table is loaded, it is checked if the
keyword is defined as an alias. If this is the case, the alias is
replaced with the keyword, and stored in the buffer. If an unknown
keyword is found, the whole keyword buffer is rejected; e.g. a
SETUP command message buffer.
2. Full Check (same as Normal Check in this version):
Same as the Normal Check, except that a more thorough check (more
time consuming) is carried out. This is e.g. a check of the
correspondence between the actual and the defined type of the
value, and if keywords are valid in the current context.
3. Soft Check:
It is checked if the keyword is defined in the Dictionary.
If yes, the keyword is accepted. If not, and if an Alias Conversion
Table is available, it is tested if the keyword is defined as an
alias. If this is the case the alias is exchanged with the real
keyword and the keyword accepted. Otherwise the keyword is ignored
(discarded silently).
4. No Check:
No check is performed at all. It is not tried to convert aliases
into keywords.
Keywords are checked before they are stored in the local keyword
buffer. The Check Type is adjusted automatically at creation of the
object, according to if a Dictionary is loaded or not; default mode
in this case is Normal Check. Methods exist to change the Check Type
dynamically during the operation of the object.
o Change Record.
The Change Record feature makes it possible to monitor the change of
keywords in the local setup buffer. The object keeps track of which
keywords that changed since the last execution of the ResetChangeRec()
method. It is possible to have only the keywords that changed
extracted to make the setup of subsystems more efficient, since not
all keywords then must be issued each time a SETUP command is sent
off. Note, that the first keyword line has number _1_ according to the
Change Record (element 0 not used).
o Handling of SETUP command message buffers.
The object can parse/unpack a SETUP command message buffer received,
using the method HandleSetupCmd(). The mehtod sets the value of the
Exposure ID, and the No Move and Check Flags, which subsequently can
be retrieved. Single keywords are merged into the list of keywords
already stored in the object. Furthermore, file references are
resolved and the keywords of the possible Setup Files referenced,
merged into the object as well.
o Extraction of selected keywords.
Extraction of keywords and packing of these into a buffer that can be
sent as the buffer for the SETUP command are MakeMsgBuf() and
MakeMsgBufChRec(). The former makes a buffer of either all keywords or
a selection of keywords if an instance of the oslxKEYW_FILTER is given
in as input parameter.
If a number of keywords should be extracted the method
ExtractKeywords() can be used. Also here it is possible to specify an
oslxKEYW_FILTER to apply on the data, and to specify that the Change
Record should be taken into account.
Single keywords can also be searched for using the method
GetKeyword().
Note that many of the methods provided are described in the man-page
for the OSLX Short-FITS Class, since the class is derived from this.
**** Constructor/Destructor Methods ****
oslxSETUP(const oslxDICTIONARY *dictionary = NULL,
const oslxALIAS *alias = NULL)
Constructor method that associates a dictionary to the object and
an Alias Conversion Table (optional). Note, that if a reference to a
Dictionary is not passed on to the object, a Dictionary must be loaded
using the LoadDictionary() method before starting to use the object.
~oslxSETUP()
Destructor method cleaning up memory etc.
**** Methods to access SETUP command attributes ****
ccsCOMPL_STAT ExpoID(const vltINT32 expoID)
vltINT32 ExpoID() const
ccsCOMPL_STAT NoMoveFlag(const vltLOGICAL noMove)
vltLOGICAL NoMoveFlag() const
ccsCOMPL_STAT CheckFlag(const vltLOGICAL check)
vltLOGICAL CheckFlag() const
**** General methods acting on the whole setup ****
ccsCOMPL_STAT ClearSetup()
Resets the setup buffer of the object
**** Handling of buffers to/from SETUP commands ****
ccsCOMPL_STAT HandleSetupCmd(const char *setupBuf,
const vltLOGICAL updateOnly = FALSE)
Handle (read in) the parameters specified by the buffer of a SETUP
command the parameters are merged into the setup buffer of the object.
If the "updateOnly" flag is TRUE, only keywords already stored in the
object will be updated; the rest of the keywords will be ignored.
slxSETUP_FLAGS *GetSetupAttr()
ccsCOMPL_STAT ResetSetupAttr()
ccsCOMPL_STAT SetSetupAttr(const slxSETUP_FLAGS *setupAttrib)
Methods to access the SETUP command flags
ccsCOMPL_STAT MakeMsgBuf(oslxKEYW_FILTER *filter = NULL)
Method to generate a buffer which is suitable for sending via CCS.
The format of the generated buffer will be the position dependent
format as specified by the CDT for the SETUP command. It is possible to
specify an instance of oslxKEYW_FILTER to filter out desired keywords.
ccsCOMPL_STAT MakeMsgBufChRec(oslxKEYW_FILTER *filter = NULL)
Makes a message buffer from the keywords marked as changed in the
Change Record. It is possible to specify an instance of oslxKEYW_FILTER
to filter out desired keywords.
char *SetupMsgBuf() const
vltUINT32 SetupMsgBufLen() const
Methods to return pointers/lengths of the setup message buffer
**** Load and save methods ****
ccsCOMPL_STAT LoadSetup(const slxFILENAME fileName,
const vltLOGICAL globalSearch = FALSE)
Method to load a setup file into the local setup buffer while
checking the keywords. The Setup Header Attributes are set according to
the ones of the new Setup File.
If "globalSearch" is specified, there is searched for the file in all
the User Branches.
ccsCOMPL_STAT SetSetupFile(const slxFILENAME fileName)
Sets the file name for the setup-file.
ccsCOMPL_STAT Save(const slxSETUP_TYPE setupType,
const char *obsMode = NULL
const vltLOGICAL useChangeRecord = FALSE,
oslxKEYW_FILTER *filter = NULL,
const vltLOGICAL saveComments = FALSE,
const vltLOGICAL saveIncludedKeys = FALSE)
Save the setup parameters currently stored in the object into the file
with which the object is connected. Note, that the Setup Type parameter
specifies the type of Setup File to generate, and the storage location.
It can be specified to use the Change Record so that only keywords marked
as changed are taken into account. Furthermore and filter can be specified
to take only a subset of the keywords matching the other conditions
into account.
It may be relevant to adjust attributes of the Setup File Header,
in particular the Setup ID and the Observation Mode, in order to have
consistent information in the header. The Observation Mode decides in
which Mode Directory in the current INS_USER directory the Setup File
is stored. It is possible to enter an Observation Mode as input parameter,
this name must then correspond exactly to one of the Observation Mode
directories in the INS_USER directory.
ccsCOMPL_STAT SaveAs(const slxFILENAME fileName,
const slxSETUP_TYPE setupType,
const char *obsMode = NULL
const vltLOGICAL useChangeRecord = FALSE,
oslxKEYW_FILTER *filter = NULL,
const vltLOGICAL saveComments = FALSE,
const vltLOGICAL saveIncludedKeys = FALSE)
Save the setup keywords in the setup buffer in a file with a new name.
The new name is kept in the object, so subsequent calls to Save() stores
the keywords in this file.
The SaveAs() method has the same behaviour as the Save() method.
ccsCOMPL_STAT ExtractSetupFromFitsHd(const slxFILENAME dataFile)
Extracts the setup keywords from the header of a FITS File. The typical
usage will be to 1) Reset the Change Record of this OSLX Setup Object,
2) Invoking this method to extract the keywords from the FITS Header,
3) Save the changed keywords using the Save() or SaveAs() methods.
INS_ROOT Defines the root directory of the INS directory structure
used by this application.
INS_USER Defines the current working point in the INS directory
structure. Could e.g. be "SYSTEM".
INS_SETUPPATH Colon separated list of paths where Setup Files may be
located.
In the setup buffer the order of keywords are not garanteed therefore one should not
place the same keyword with different values in the same setup buffer (see also VLTSW00990392)
Work around for this problem is to send two separate SETUP commands. !!!
When a Setup File is searched according to the INS_SETUPPATH, the first
occurrence of the file is chosen.
Using keywords with less index then given in the dictionary
can cause 'keyword not found in dictionary' error. Please see the manpage of oslxDICTIONARY.
The TSF class is used to handle TSF Files. It is inherited from the
oslxSHORT_FITS class and thus have the same features.
As TSF Files can have repeated keywords that class has this feature
switched on permanently.
As the handling of all PAF Files is driven by the Dictionaries, the
keywords in connection with the TSF Files must be defined in a Dictionary
and made available for this class. Note however, that it is not necessary
to put in records for all the speciel TSF keys, having ".DEFAULT",
".RANGE" etc., as value. E.g., for
DET.WIN.NX.TYPE "..."
DET.WIN.NX.RANGE "..."
DET.WIN.NX.DEFAULT "..."
DET.WIN.NX.TARGIND "..."
DET.WIN.NX.VALUE "..."
DET.WIN.NX.MINIHELP "..."
DET.WIN.NX.HIDE "..."
It is enough to have a record defining "DET.WIN.NX".
With the ".VALUE" key it is possible to assign a 'static' value to
a keyword. This keyword will consequently not appear in the P2PP tools
and cannot be changed by the user. If the ".VALUE" key is set to
"_tpl_undefine_" an earlier assignment of a value to the key is
unset and the key will be written in the TSF when saving. If ".VALUE"
is set to "_tpl_suppress_" the whole record for that key will not
appear in the TSF generated.
As most of the methods are defined in oslxSHORT_FITS, please have a look
at the man-page for this class for more details.
ccsCOMPL_STAT LoadTsf(const slxFILENAME fileName)
Load a TSF File into the object.
The OSLX Short-FITS Class is a processor to handle Short-FITS keywords in
files, and in memory.
The object is first operational when a Dictionary is available. The
Dictionary can either be loaded in and generated in the object, or
a reference to an existing instance of the OSLX Dictionary class given in
at start up. This has the advantage, that this Dictionary can be shared
among several instances, and that the application itself can use the
Dictionary. This may save quite some memory in case of big Dictionaries.
The Dictionary is used during operation to check the consistency of
the Short-FITS keywords treated.
An Alias Conversion Table can also be associated with the object either as
as reference to an external instance of the oslxALIAS class, or by loading
a local table into the object.
Short-FITS keyword information is stored in a local buffer. When new
keywords are loaded into this, either as single keywords or as a file,
these keywords are merged with the ones already stored in the buffer; i.e.
the new values overwrites the old ones. The information in the local
keyword buffer can be deleted invoking the ClearInstance() method.
When Short-FITS files are loaded into the object, only the name of the last
file loaded is kept. If the method Save() is called, the current contents
of the local buffer is stored into this file. An external instance of the
OSLX Short-FITS Header Class can be given in in this connection to set
the fields of the header Appropriately. It is also possible to call
the method SaveAs() to generate a new Short-FITS file (this includes
building) a new header.
eywords are checked before they are stored in the local keyword
uffer according to the Dictionary in use by the object. Unknown keywords
re rejected.
Main features of the class are:
o Aliasing.
If an Alias Conversion Table is loaded, it is checked if the
keyword is defined as an alias. If this is the case, the alias is
replaced with the keyword, and stored in the buffer. If an unknown
keyword is found, the whole keyword buffer is rejected.
o Change Record.
The Change Record feature makes it possible to monitor the change of
keywords in the local keyword buffer. The object keeps track of which
keywords that changed since the last execution of the ResetChangeRec()
method. It is possible to have only the keywords that changed
extracted. Note, that the first keyword has number _1_ according to
the Change Record (element 0 not used).
o Extraction of selected keywords.
If a number of keywords should be extracted the method
ExtractKeywords() can be used. Also here it is possible to specify an
oslxKEYW_FILTER to apply on the data, and to specify that the Change
Record should be taken into account.
Single keywords can also be searched for using the method
GetKeyword().
o Storage of user data in PAFs.
It is possible to store blocks of data in PAFs with a free format.
To do so, the keywords PAF.DATA.START and PAF.DATA.END must be used
to delimit the block of data. It is possible to have several blocks
of data in a PAF.
The methods ResetData(), GetDataBlock(), SetDataBlock() and
NumberOfDataBlocks() are used to handle data blocks in the object.
Data Blocks found in PAF loaded into the object are automatically stored
when storing a PAF. Note, that if several PAFs are loaded sequentially
the object will accumulate the Data Blocks. It may therefore be
desirable to clear the Data Blocks using ResetData() or ClearInstance()
before loading a new PAF depending of the intentions with the data.
No attempt is done to try and reformat the data in a Data Block. The
data is returned as found in the PAF.
oslxSHORT_FITS(const oslxDICTIONARY *dictionary = NULL,
const oslxALIAS *alias = NULL)
Constructor method that associates a dictionary to the object and
an Alias Conversion Table (optional). Note, that if a reference to a
Dictionary is not passed on to the object, a Dictionary must be made
available using the SetDictionary() method before starting to use the
object.
~oslxSHORT_FITS()
Destructor method cleaning up memory etc.
ccsCOMPL_STAT DumpKeywords()
Dump the keywords stored in the object to stdout.
void AllowRepeatedKeys(const oslxREP_TYPE state)
Switches on/off the usage of repeated keys. The "state" input variable
can have the following values:
oslxREP_ALLOW_NO_KEYS, oslxREP_ALLOW_ALL_KEYS, oslxREP_ALLOW_SOME_KEYS
ccsCOMPL_STAT AllowRepeatedKeys(const char *keyList)
Method to add a list of keywords that are allowed to be repeated.
oslxREP_TYPE AllowRepeatedKeys() const
Returns the current type of keyword repition allowed.
oslxKEYWORD &CurrKeyword()
All search and set operations on keyword act on the CURRENT KEYWORD
This contains the values to be stored and the retrieved values
for the last search performed.
An abbreviated method exists "CK()" doing the same.
ccsCOMPL_STAT GetFormat(char* format)
Gets the format (e.g. %.2f) of the current keyword as declared in the dictionary.
(Currently To be used only for double values)
ccsCOMPL_STAT ClearInstance()
Resets the Short-FITS buffer of the object.
void ResetChangeRec(const vltLOGICAL resetValue = FALSE)
vltINT8 *GetChangeRec()
vltLOGICAL CurrKeywordChanged()
vltLOGICAL HasChanged(const slxKEYW_LINE keyword,
const vltINT32 keyNo = 0)
vltLOGICAL HasChanged(const vltINT16 keywordNo)
ccsCOMPL_STAT HasChanged(const slxKEYW_LINE keyword,
vltLOGICAL *hasChanged,
const vltINT32 keyNo = 0)
vltINT32 NoOfChangedKeywords() const
Note that the first keyword has number _1_ in the Change Record.
Using the methods HasChanged() that return the vltLOGICAL, it may be
that an internal error is logged if the keyword is not found. I.e., it is
more safe to use the
HasChanged(const slxKEYW_LINE keyword, vltLOGICAL *hasChanged), method.
The "keyNo" parameter is used to indicate the instance of the keyword
in case the object is set up to work on repeated keywords.
vltINT32 NumberOfKeywords()
Return the number of keywords currently stored in the object.
vltLOGICAL KeyInBuffer(const slxKEYW_LINE keyword)
Method to probe if a certain key is stored in the internal Hash Table
if the instance.
ccsCOMPL_STAT GetKeyword(const vltINT32 keywordNo)
Returns a specific keyword identified by its number in the buffer.
The first keyword being # 1. Comments do not count. The members for
CurrKeyword() are set accordingly.
ccsCOMPL_STAT GetKeyword(const slxKEYW_LINE keyword,
const vltINT32 keyNo = 0)
Searches for a keyword in the object's keyword buffer. The members for
CurrKeyword() are set accordingly.
The "keyNo" parameter is used to indicate the instance of the keyword
in case the object is set up to work on repeated keywords.
ccsCOMPL_STAT StoreKeyword(const slxKEYW_LINE keywordLine)
ccsCOMPL_STAT StoreKeywordAfter(const slxKEYW_LINE keywordLine,
const slxKEYW_LINE afterKey)
Stores a keyword line in the object's keyword buffer. If the keyword
exists the new value and possible comment overwrites the old. If the
'keyword' is found to be an alias, it is substituted with the actual
keyword in the "keyword" buffer.
If "afterKey" is set to a specific key stored in the object, the new
key is put in after the specified key. Otherwise the key is stored
in the end of the list of keywords in the object.
ccsCOMPL_STAT StoreKeyword(const slxKEYW_LINE keyword,
const char *stringVal,
const slxKEYW_LINE afterKey = NULL)
ccsCOMPL_STAT StoreKeyword(const slxKEYW_LINE keyword,
const vltLOGICAL logicalVal,
const slxKEYW_LINE afterKey = NULL)
ccsCOMPL_STAT StoreKeyword(const slxKEYW_LINE keyword,
const vltINT32 integerVal,
const slxKEYW_LINE afterKey = NULL)
ccsCOMPL_STAT StoreKeyword(const slxKEYW_LINE keyword,
const vltDOUBLE doubleVal,
const slxKEYW_LINE afterKey = NULL)
ccsCOMPL_STAT StoreKeyword(const slxKEYW_INFO *keyword)
ccsCOMPL_STAT StoreKeyword(oslxKEYWORD *keyword)
Stores a keyword based on its name and its value, or from an OSLX Keyword
Object or an SLX Keyword Info Structure. Use slxAssKey() or slxAssKey2(),
to assemble keywords from their basic elements.
ccsCOMPL_STAT RemoveKeyword(const slxKEYW_LINE keyword,
const vltINT32 keyNo = 0)
Remove a keyword stored in the objects keyword buffer.
The "keyNo" parameter is used to indicate the instance of the keyword
in case the object is set up to work on repeated keywords.
ccsCOMPL_STAT ResetKeywordPtr(const vltLOGICAL useChRec = FALSE)
ccsCOMPL_STAT NextKeyword(const vltLOGICAL useChRec = FALSE,
oslxKEYW_FILTER *filter = NULL)
Methods to return the sequential next keyword by each call.
The members of the Current Keyword in the object are set after each
call to the NextKeyword() method. The fields of the keyword can
be accessed via the CurrKeyword() member. As soon as ResetKeywordPtr()
the Current Keyword will contain the information about the first
key. When there is no more keywords in the list to return the method
return FAILURE.
ccsCOMPL_STAT ExtractKeywords(const vltLOGICAL useChangeRecord = FALSE,
oslxKEYW_FILTER *filter = NULL)
Method that extract keywords and organizes them in the format
"keyword value keyword value ...". If "useChangeRecord" is FALSE and
no filter is used all keywords will be taken.
char *ExtractedKeywords() const
vltINT32 ExtractedBufLen() const
vltINT32 NoExtractedKeywords() const
Return pointer to buffer containing extracted keywords/the length of this
buffer/the number of keywords extracted.
ccsCOMPL_STAT StoreExtrBuffer(const char *extrBuf)
Store an extracted buffer in the object. This buffer can be returned
with "*ExtractedKeywords()".
ccsCOMPL_STAT LoadShortFitsFile(const slxFILENAME fileName,
const char *envVar = NULL,
oslxKEYW_FILTER *filter = NULL,
const vltLOGICAL updateOnly = FALSE,
const vltLOGICAL globalSearch = FALSE)
Method to load a Short-FITS file into the internal keyword buffer while
checking the keywords. The Short-FITS Header Attributes are set according
to the ones of the new Short-FITS File. The environment variable
INS_USER_PATH indicates locations where Short-FITS files are stored.
If "updateOnly" is TRUE, only keywords already stored in the object are
updated.
Short-FITS Files should be stored in the $INS_ROOT/<user>/MISC Branch.
It is possible to make sub-directories in the MISC directory. A path
can be given in as e.g. "$INS_ROOT/$INS_USER/MISC/MY_DIR".
ccsCOMPL_STAT SetShortFitsFile(const slxFILENAME fileName)
Sets the file name for the Short-FITS file.
char *GetFileName()
Return pointer to the filename currently stored in the object.
ccsCOMPL_STAT Save(const vltLOGICAL useChRecord =FALSE,
oslxKEYW_FILTER *filter = NULL,
const vltLOGICAL saveComments = FALSE,
const vltLOGICAL saveIncludedKeys = FALSE)
Save the Short-FITS keywords currently stored in the object into the file
with which the object is connected.
It can be specified to use the Change Record so that only keywords marked
as changed are taken into account. Furthermore a filter can be specified
to take only a subset of the keywords matching the other conditions
into account.
If the flag "saveComments" is TRUE, the possible comments from the
original file will be re-generated. The scheme is such that the
comment lines (and blank lines) before each keyword are accumulated
when loading in the file and stored again when the keyword is stored.
If the flag "saveIncludedKeys" is TRUE, keys stored in the object
from included files will be stored in the file being saved. Otherwise
these will not be saved.
ccsCOMPL_STAT SaveAs(const slxFILENAME fileName,
const vltLOGICAL useChRecord = FALSE,
oslxKEYW_FILTER *filter = NULL,
const vltLOGICAL saveComments = FALSE,
const vltLOGICAL saveIncludedKeys = FALSE)
Save the Short-FITS keywords in the internal buffer into a file with a
new name. The new name is kept in the object, so subsequent calls to
Save() stores the keywords in this file.
The SaveAs() method has the same behaviour as the Save() method.
ccsCOMPL_STAT Copy(oslxSHORT_FITS *sourceObject,
const vltLOGICAL useChRecord = FALSE,
oslxKEYW_FILTER *filter = NULL)
Method to transfer keywords between two oslxSHORT_FITS objects.
The object invking the method is the destination object.
vltLOGICAL Included(const slxKEYW_LINE keyword)
Return flag indicating if the keyword was included from an external
PAF.
ccsCOMPL_STAT ResetData()
Reset the Data Blocks stored into the object.
ccsCOMPL_STAT GetDataBlock(char **dataPtr,
vltINT32 *dataLen,
const vltINT32 dataBlockNumber = 1)
Get a pointer to a Data Block stored in the object.
ccsCOMPL_STAT SetDataBlock(char *dataPtr,
vltINT32 dataLen,
const vltINT32 dataBlockNumber = 1)
Store a Data Block in the object.
vltINT32 NumberOfDataBlocks()
Return the number of Data Blocks stored in the object.
INS_ROOT Defines the root directory of the INS directory structure
used by this application.
INS_USER Defines the current working point in the INS directory
structure. Could e.g. be "SYSTEM".
INS_SETUPPATH Colon separated list of paths where Setup Files may be
located. In principle any file can be traced according
to the variable.
INS_USER_PATH Colon separated path of directories where user files can
be located. This could (should) be used only to specify
directories in the "$INS_ROOT/$INS_USER/MISC" branch.
3.3 SLXTCL LIBRARY PROCEDURES
Tcl procedure, used within GUI panels built with the VLT panel editor,
to assign to variables associated to widgets the values of setup
keywords contained in the setup buffer <buf>.
The format of this buffer is the same as returned by oslx after
the command OSETUP -getSetupBuf
This procedure is intended to be used in cases where a list of keywords
and values has been extracted from a setup file, loaded in a oslx setup
buffer, and then manipulated using functionality provided by oslx.
For those cases where the list has to be retrieved from a setup file as it
is (no manipulation needed), it is recommended to use slxtclLoadSetup.
The value of all variables associated to a widget matching a keyword
in the setup buffer are replaced with the value of that keyword (see
slxtclLoadSetup for examples and more information).
The list of variables whose value has been updated is returned to the
calling process.
It belongs to the library libslx.tcl; therefore, in order to be able
to use it, one has to register the panel edited with the Panel Editor
to this library.
# 1
# retrieve the contents of setup file myRef in a oslx buffer
seq_oslxCmd OSETUP -load slxtcl myRef
# add two keywords
set newKeys "DET.WIN1.BINX 8 DET.WIN1.BINY 8"
seq_oslxCmd OSETUP -storekeyword slxtcl $newKeys
# retrieve the contents of the oslx buffer
set buf [seq_oslxCmd OSETUP -getSetupBuf slxtcl]
# load the contents of the buffer in the panel
set varPan [slxtclBufToPan $buf]
# print the list of variables whose value has been updated
foreach name $varPan { puts $name }
slxtclLoadSetup
[1] VLT-MAN-ESO-17240-0726 VLT INS Common Software slx - User Manual
[2] VLT-MAN-ESO-17240-0853 VLT INS Common Software oslx - User Manual
Tcl procedure used to define a filter for the setup variables defined
in a panel.
Typically called from within a panel to exclude from the setup keywords
one or more variables defined in it, or modify the associated keyword.
For example, a panel defining the complete setup for an instrument having
two detectors will normally instanciate (import) twice a detector setup
panel class: in this case one has to modify the keywords associated
at least to one of the two detectors, in order to be able to distinguish
them from those of the other detector. Furthermore, for those observing
modes requiring one detector only, all variables associated to the other
detector have to be excluded from the setup file associated to that
observing mode.
The parameter <mode> determines the mode how the filter is used:
a : add an entry in the list of filters
r : remove an entry in the list of filters
c : add an entry in the list of keywords to be modified
u : remove an entry in the list of keywords to be modified
The parameter <pattern> indicates the pattern against which all
variables associated to widgets must be checked. Wildcard options, as
accepted by Tcl for glob-style pattern matching, can be used.
The special value "all" combined to the value "r" or "u" for <mode>
removes all existing filter entries.
The parameter <from> indicates the sub-string in the keyword to be replaced
(meaningful only if <mode> is "c")
The parameter <to> indicates the sub-string in the keyword replacing <from>
(meaningful only if <mode> is "c")
Note that the filtering applies to all operations done from the moment
when the filtering is requested by calling this function (<mode> "a" or
"c") until when the filtering is explicitely removed (<mode> "r" or "u").
Do not forget to remove filters (e.g. "r" "all") whenever you do not want
them to take effect in the next operations.
It belongs to the library libslx.tcl; therefore, in order to be able
to use it, one has to register the panel edited with the Panel Editor
to this library.
# 1
# Exclude for the creation of the setup file all variables whose
# associated setup keyword begins with DET.EXP.
slxtclFilterSetup a *DET.EXP.*
slxtclSaveSetup $file
# 2
# remove all filter entries defined before (all keywords will be written
# in the setup file)
slxtclFilterSetup r all
slxtclSaveSetup $file
# 3
# remove all filter entries defined before and define a new filter
# excluding all INS keywords
slxtclFilterSetup r all
slxtclFilterSetup a *INS*
slxtclSaveSetup $file
# 4
# For all those variables beginning with "blueArm", the sub-string
# ".DET" has to be replaced with "0.DET1"
# For example the keyword associated to the variable
# blueArm_setup.4.DET.EXP.TYPE will be DET1.EXP.TYPE and the index 40
# instead of 4
slxtclFilterSetup c blueArm* .DET 0.DET1
slxtclSaveSetup $file
# 5
# leave unchanged the keywords associated to all variables whose name
# begins with "blueArm"
slxtclFilterSetup u blueArm*
slxtclSaveSetup $file $dictionary $template
slxtclSaveSetup, slxtclPanToBuf
[1] VLT-MAN-ESO-17240-0726 VLT INS Common Software slx - User Manual
[2] VLT-MAN-ESO-17240-0853 VLT INS Common Software oslx - User Manual
Tcl procedure, used within GUI panels built with the VLT panel editor,
to assign to variables associated to widgets the values of setup
keywords contained in the setup file <file>.
The value of all variables associated to a widget matching a keyword
in the setup file (except prefix setup.<i>. See slxtclSaveSetup) are
replaced with the value of that keyword read from the setup file.
Example: if the setup file contains the following line:
DET.WIN1.BINX 8; # Binning factor in X
and in the panel a variable associated to a widget is called
setup.1.DET.WIN1.BINX, then its value is set to 8
Keywords not matching any variable name within the panel are ignored.
The list of variables whose value has been updated is returned to the
calling process.
This procedure uses funtionality provided by oslx to search for
the setup file specified by <file>, to read and format its contents.
It assumes that the data dictionary containing the description of the
keywords handled has already been loaded (see slxtclDictionary).
The parameter <inst> (default slxtcl) specifies the instance of setup
buffer oslx has to use.
It belongs to the library libslx.tcl; therefore, in order to be able
to use it, one has to register the panel edited with the Panel Editor
to this library.
1) This procedure does NOT check if the appropriate data dictionary has
been loaded through slxtclDictionary. The application has to make
sure that this is true.
# 1
# read the contents of setup file myRef and load keyword values in the
# panel using the setup buffer slxtcl of oslx
set dictionaries {TCS ICS CCDDCS}
slxtclDictionary $dictionaries
slxtclLoadSetup myRef
# 2
# read the contents of setup file myRef and load keyword values in the
# panel using the setup buffer myInst of oslx
slxtclDictionary $dictionaries
slxtclLoadSetup myRef myInst
# 3
# read the contents of setup file myRef, load keyword values in the
# panel using the setup buffer slxtcl of oslx and print the list of
# variables whose value has been updated
slxtclDictionary $dictionaries
set varPan [slxtclLoadSetup myRef]
foreach name $varPan { puts $name }
slxtclBufToPan
slxtclSaveSetup, slxtclDictionary
[1] VLT-MAN-ESO-17240-0726 VLT INS Common Software slx - User Manual
[2] VLT-MAN-ESO-17240-0853 VLT INS Common Software oslx - User Manual
Tcl procedure to get the list of all variables in a GUI panel (built with
the VLT panel editor), which follow the syntax for setup variables
(see slxtclSaveSetup).
The list of variable is filtered according to the filter settings
applied by previous calls to slxtclFilterSetup.
This procedure is intended to be used in cases where the list of keywords
and values extracted from the GUI panel has to be manipulated, e.g.
using functionality provided by oslx. For those cases where
the list has to be saved in a setup file as it is, it is recommended to
use slxtclSaveSetup.
The keywords associated to the variables and their current value are
returned to the caller in a string with the following format:
<keyword1> <value1> ... <keywordn> <valuen>
This string can be used as it is as parameter value in the command
OSETUP -storeKeyword to oslx (see [2])
It belongs to the library libslx.tcl; therefore, in order to be able
to use it, one has to register the panel edited with the Panel Editor
to this library.
# 1
# get keywords from panel, filter out DET keywords, and store the
# remaining in local variable
slxtclFilterSetup a *DET*
set oslxBuf [slxtclPanToBuf]
# 2
# remove previous filtering, get all keywords from panel and store in
# local variable
slxtclFilterSetup r all
set oslxBuf [slxtclPanToBuf]
# 3
# get keywords from panel and put them in a oslx setup buffer
set oslxBuf [slxtclPanToBuf]
seq_oslxCmd OSETUP -storeKeyword slxtcl $oslxBuf
slxtclSaveSetup, slxtclFilterSetup
[1] VLT-MAN-ESO-17240-0726 VLT INS Common Software slx - User Manual
[2] VLT-MAN-ESO-17240-0853 VLT INS Common Software oslx - User Manual
Tcl procedure, used within GUI panels built with the VLT panel editor,
to save values of variables associated to widgets in the setup file <file>.
When editing the configuration of a widget with the panel editor, the
field "Variable" must contain a name with the following syntax:
setup.<i>.<short FITS>
whereby
<i> is the order of appearance in the setup file to be generated
<short FITS> is the keyword name in short FITS (see [1])
Examples:
setup.0.DET.EXP.TYPE
setup.1.DET.WIN1.BINX
Widgets whose associated variable does not follow the syntax described
above are just ignored by this procedure. This allows to mix within a
panel information needed to be saved in a setup file with other just
needed for other purposes.
In some cases one might temporarily want to ignore also some variables
following the syntax described above. In this case, it is possible to
define filters (see slxtclFilterSetup).
In more complex cases, the same widget class is instanciated twice within
the same panel. In this case, one may want to change the name of the
keywords associated to one or more instances. Also for this case, see
slxtclFilterSetup
This procedure uses funtionality provided by oslx to search for
keywords and formats in a data dictionary and save formatted keywords
and values in the setup file specified by <file>; the type of setup file
(see [2]) is specified by <type> (default "Reference Setup").
It assumes that the data dictionary containing the description os the
keywords handled has already been loaded (see slxtclDictionary).
The parameter <inst> (default slxtcl) specifies the instance of setup
buffer that oslx has to use.
It belongs to the library libslx.tcl; therefore, in order to be able
to use it, one has to register the panel edited with the Panel Editor
to this library.
1) An already existing setup file is overwritten
2) This procedure does NOT check if the appropriate data dictionary has
been loaded through slxtclDictionary. The application has to make
sure that this is true.
# 1
# save keywords and values from a panel in the reference setup file myRef
# using the setup buffer slxtcl of oslx
set dictionaries {TCS ICS CCDDCS}
slxtclDictionary $dictionaries
slxtclSaveSetup myRef
# 2
# save keywords and values from a panel in the reference setup file myRef
# using the setup buffer myInst of oslx
slxtclDictionary $dictionaries myInst
slxtclSaveSetup myRef "Reference Setup" myInst
# 3
# save only detector keywords and values from a panel in the detector
# setup file myDet using the setup buffer slxtcl of oslx
slxtclFilterSetup a *GEN*
slxtclFilterSetup a *INS*
slxtclFilterSetup a *TEL*
slxtclSaveSetup myDet "Detector Setup"
# 4
# save only instrument keywords and values from a panel in the instrument
# setup file myIns using the setup buffer slxtcl of oslx
slxtclFilterSetup r all
slxtclFilterSetup a *GEN*
slxtclFilterSetup a *DET*
slxtclFilterSetup a *TEL*
slxtclSaveSetup myIns "Instrument Setup"
 Quadralay Corporation http://www.webworks.com Voice: (512) 719-3399 Fax: (512) 719-3606 sales@webworks.com |
| |
|
|
|