| |
|
|
|
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, INSDIR, OSETUP, SHOFITS
Furthermore the command "GEN" is provided for the general handling of the
OSLX Server.
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.
In the following "<id>" indicates the instance name. The instance can
be any string (containing a-z, A-Z, 0-9), of any length. Note, that
each time a new instance name is given a new object is created. The name
for a FITS instance could e.g. be "fits1", "fits2"), ... .
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>"
-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 Setup Type must be either "configuration",
"ref-configuration" or "aux-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>"
-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.
-clear <id>
Description: Reset the referenced object making it ready to
handle the next FITS file.
-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>
Description: Clear the list of comments currently stored in
the object. This is also done when the "-clear"
parameter is issued.
-addComment <id> "<comment>"
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>
Description: Reset the pointer to the list of comments. Used
to be able to return the comments stored
sequentially.
-getNextComment <id> [useChRec] [filter <id>]
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>
Description: Clear the list of (Operations) Logs currently
stored in the header. Is also done when the
"-clear" command is issued.
-addLog <id> "<log>"
Description: Add a log to the list of logs in the objects.
When storing the contents of the object into a
FITS file, the logs stored are written into the
header after the possible comments.
-resetLogPtr <id>
Description: Reset the Pointer to the list of logs. Used to
retrieve the logs sequentially from the object.
-getNextLog <id>
Description: Return the sequential next log stored in the
object. When there are no more logs in the
object an empty buffer is returned.
Reply Buffer: "<log>"
-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>]
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>
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>
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]
Description: Searches for a specific keyword and returns
the value of this if found.
Reply Buffer: "<value>"
-extractKeywords <id> [useChRec] [filter <id>]
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>..."
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 <id> <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; 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".
When first started 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".
-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".
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)
ccsCOMPL_STAT Unload()
Methods to load/unload an Alias Conversion Table. If the object already
contains an Alias Conversion Table this is deleted.
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.
~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.
ccsCOMPL_STAT SaveConfigFile(const slxCONFIG_TYPE type,
const slxFILENAME fileName,
const vltLOGICAL useChangeRecord = NULL,
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".
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).
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 LoadFromUrl(const char *url,
const vltLOGICAL merge = FALSE)
Loads a Dictionary via HTTP and builds up the Hash Table in the object.
The address to give in is a standard URL, like, e.g.:
"http://archive.eso.org/DICB/DID/ESO-VLT-DIC.GENERIC-1.0"
ccsCOMPL_STAT UnloadDic()
Method that unloads a Dictionary currently loaded into the object.
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 LookUp(const slxCATEGORY cat,
const slxSUBSYSTEM subSyst,
const slxPARAMETER par)
Looks up a keyword according to the category, subsystem and parameter
given in as individual NULL terminated strings. If the keyword is
non-hierarchical, only the "par" should be specified, the other parameters
can be set to NULL. If the keyword is hierachical but there is no
subsystem, "subSyst" must be "".
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 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.
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.
ccsCOMPL_STAT LoadDictionary(const slxDICTIONARY dictionary)
ccsCOMPL_STAT UnloadDictionary()
Method to load a Dictionary into the object and build up the
Hash Table. If a Dictionary is already loaded it is first unloaded.
If a reference to an external Dictionary was given in at creation this
external Dictionary is not deleted.
ccsCOMPL_STAT SetDictionary(const oslxDICTIONARY *dictionary)
Method to make the object reference to an external Dictionary
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 128 characters in length.
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.
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 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.
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 CreateStoreFits(const slxCATEGORY category,
const slxSUBSYSTEM subSystem1,
const slxSUBSYSTEM subSystem2,
const slxPARAMETER parameter,
const char *value)
ccsCOMPL_STAT CreateStoreFits(const slxCATEGORY category,
const slxSUBSYSTEM subSystem1,
const slxSUBSYSTEM subSystem2,
const slxPARAMETER parameter,
const vltLOGICAL value)
ccsCOMPL_STAT CreateStoreFits(const slxCATEGORY category,
const slxSUBSYSTEM subSystem1,
const slxSUBSYSTEM subSystem2,
const slxPARAMETER parameter,
const vltINT32 value)
ccsCOMPL_STAT CreateStoreFits(const slxCATEGORY category,
const slxSUBSYSTEM subSystem1,
const slxSUBSYSTEM subSystem2,
const slxPARAMETER parameter,
const vltDOUBLE value)
ccsCOMPL_STAT CreateStoreFits(const slxKEYW_LINE keyword,
const void *value)
ccsCOMPL_STAT CreateStoreFits(const slxKEYW_LINE keyword,
const char *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.
ccsCOMPL_STAT Save(const slxFILENAME fileName,
oslxKEYW_FILTER *filter = NULL,
const vltLOGICAL dontWriteChKeys = FALSE)
The file must exist before calling this method. This is done to force
the user to determine the size of the header block. 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.
Note that the keywords in the exiting FITS Header will overwrite
the ones in the object. If this is not desirable, the flag
"dontWriteChKeys" can be set TRUE to signal that a keyword already
stored in the object which has been changed since the last reset of the
Change Record should not be overwritten.
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.
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".
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(). If the file is a
a complete fitsfile (i.e. all the compulsory keywords are present the file) the
file will be saved with the name given as argument of CreateImageFile.
It is also possible to specify the filename during 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.
If update is ccsFALSE overwriting of the existing imageefile is not allowed.
In this case imagefile name always has to be specified when the file is saved.
(Otherwise the file will saved with the name composed from the origfilename
and "_altered" keyword.
It is also possible to extract a particular HDU from a fitsfile by:
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 operaing 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 functions.
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.
ccsCOMPL_STAT Reset()
Method to reset the object. It should be called if the object is used
for creating/modifiind 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 unlodad if this is required call the
function UnloadDictionary();
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.
csCOMPL_STAT LoadHDU(char * filename,vltINT32 hdu);
xtract the given hdu from the file in order to modify it and save it with
differnt name. If filename for the new file is not specified file will be
aved as <fname>_altered.fits
csCOMPL_STAT Append(char * filename);
ppend a whole fitsfile to the current file. The the keyword XTENSION
ill be automatically added to the primary HDU of the appended file.
csCOMPL_STAT AppendHDU(char * filename,vltINT32 hdu);
ppend the given HDU of the named file to the current imagefile (at the end)
csCOMPL_STAT AppendExtentions(char * filename);
ppend all extentions of the named file to the imagefile.
csCOMPL_STAT AppendBinaryTables(char * filename);
ppend all binary table extentions of the named file to the image.
csCOMPL_STAT MergeHDUKeywords(char * filename,vltINT32 hdu);
erge the keywords of the given hdu of the given file with the keywords in
urrent hdu of the imagefile. The file given as argument must be a proper
itsfile.(Note that any file that has been properly saved by this class is a
omplete fitsfile )
csCOMPL_STAT MergeHDUKeywords2(char * headerFile);
erge the keyword in the given header file with the
urrent hdu of the imagefile. Existing keywords will be overwritten.
he difference between the functions MergeHDUKeywords2 and MergeHDUKeywords
s that the file given as argument must be a (complete or incomplete) header
ile. Tipically this function should be used to handle the *.fits.det files
roduced by e.g. TCCD and FIERA.
csCOMPL_STAT oslxFITS_EXT :: MergeBufferOfKwLines(char *kwLineBuf ,vltINT32 hdu)
erge header hdu with the buffer 'kwLineBuf' containing keywordlines.
csCOMPL_STAT SaveImageFile(char * filename="",vltLOGICAL isFitsExt=ccsTRUE);
ave the image file in the $INS_ROOT/$INS_USER/DETDATA with the given name.
ile with the same name should not exits. If filename is not given, file will
e saved according to the descriptiion given at CreateImageFile, LoadImageFile,
oadHDU. During the saving the HDU-s are checked for the compulsory keywords,
nd the keywords are sorted according to the reference list.
hen the file is to be saved with other then ".fits" extention, the second argument
isFitsExt) has to be set to ccsFALSE.
csCOMPL_STAT CreateStoreFits(const slxKEYW_LINE keyword,
const vltDOUBLE value,
int hdunum=oslxCURRENT_HDU );
csCOMPL_STAT CreateStoreFits(const slxKEYW_LINE keyword,
const vltINT32 value,
int hdunum=oslxCURRENT_HDU );
csCOMPL_STAT CreateStoreFits(const slxKEYW_LINE keyword,
const vltLOGICAL value,
int hdunum=oslxCURRENT_HDU );
csCOMPL_STAT CreateStoreFits(const slxKEYW_LINE keyword,
const char *value,
int hdunum=oslxCURRENT_HDU );
his functions add a new keyword to the the specified header. If hdr is not
pecified
o the kewyword is added to the current HDU. After the function is executed
he current hdu will be set to the given hdu.
csCOMPL_STAT DeleteFitsKeyword(const char *keyword,
int hdunum = oslxCURRENT_HDU,
vltLOGICAL resetHDU = ccsTRUE );
eletes a keyword with the sepcified name from the given hdu. If reset hdu is
csTRUE the current hdu after the function is executed will be the given hdu.
therwise the current hdu will remain as before the function is called.
sCOMPL_STAT AddComment (char * comment,
int hdunum = oslxCURRENT_HDU );
sCOMPL_STAT AddHistory (char * history,
int hdunum = oslxCURRENT_HDU );
d comments and history to the header.
sCOMPL_STAT Sort()
sCOMPL_STAT SortKeywordsInHDU(vltINT32 hdu=1);
rts the keyword according to inner reference list. Sort() will organise the
ywords in all HDUs. The keywords that are not on the list are placed in
phabetical order after the list.
oid SetSortType(vltINT32 type=oslxSORTTYPE_REFLIST_ABC);
pecifies wheter and how the keywords in the headers should be sorted.
he argument 'type' can have the following values:
oslxSORTTYPE_NO_SORT
oslxSORTTYPE_REFLIST
oslxSORTTYPE_REFLIST_ABC
o swich off the sorting give oslxSORRTYPE_NO_SORT as argument.
efault sorttype is oslxSORTTYPE_REFLIST_ABC. In this case the keywords are
orted according to inner reference list. The keywords that are not on the
ist are placed in alphabetical order after the list.
hen sorting type oslxSORTTYPE_REFLIST, the keywords that are not on the
ist are not sorted. They are placed after the ordered list in the same
rder as before.
ltINT32 GetSortType();
eturns the type of the sort. oslxSORTTYPE_REFLIST_ABC, oslxSORTTYPE_REFLIST
r oslxSORRTYPE_NO_SORT;
ltLOGICAL IsBinaryTable(vltINT32 hdu=oslxCURRENT_HDU);
eturns TRUE when the specified HDU is a binary table.
ccsCOMPL_STAT MoveToHDU(vltINT32 hdu);
ccsCOMPL_STAT MoveToFirstHDU();
ccsCOMPL_STAT MoveToLastHDU();
ccsCOMPL_STAT MoveToBinaryTable(vltINT32 hdu);
ccsCOMPL_STAT MoveToFirstBinaryTable();
ccsCOMPL_STAT MoveToLastBinaryTable();
MoveToExtention(char* extname);
Functions setting the Current HDU. Only useful when extentions are present.
Moving to a binary table includes a check for the type of the hdu.
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 therefore hdu=1,
first extention is hdu=2;
extname: 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);
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.
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.
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 (specified by column and firstrow)
to where the first elemen of the 'array' should be written.
For one dimentional column firstelem is always 1.
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.)
Note 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);
csCOMPL_STAT InsertBlankColumnToBinaryTable(vltINT32 colnum,
char *ttype,
char* tform,
vltINT32 hdu=oslxCURRENT_HDU);
csCOMPL_STAT DeleteColumnFromBinaryTable(vltINT32 colnum,
vltINT32 hdu=oslxCURRENT_HDU);
csCOMPL_STAT InsertBlankRowsToBinaryTable(vltINT32 firstrow,
vltINT32 nrow=1,
vltINT32 hdu=oslxCURRENT_HDU);
csCOMPL_STAT DeleteRowsFromBinaryTable(vltINT32 firstrow,
vltINT32 nrow=1,
vltINT32 hdu=oslxCURRENT_HDU);
he above four functions has no yet been tested thoroughly.
csCOMPL_STAT GetSizeOfBinaryTable(long &nrows, int &ncolumns);
csCOMPL_STAT CheckKeywordInDictionary(const slxKEYW_LINE keyword,char* value );
eywords are checked against the dictionary automaticly.
Storing keywords (omitting indeces) in a fits instance, can cause
'keyword not found in dictionary' error. Please see the manpage of oslxDICTIONARY.
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 keywords 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 (creeate imagefile and add a binary table in one step)
//(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) {..}
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(const slxCATEGORY category = NULL,
const slxSUBSYSTEM subSystem = NULL,
const slxPARAMETER parameter = NULL)
Constructor method to initialize the object, and to add a filter if
desired.
~oslxKEYW_FILTER()
Destructor method that cleans up the object.
void Clear()
Clears all the filters currently added in the object.
ccsCOMPL_STAT SetDictionary(const oslxDICTIONARY *dictionary)
Make a Dictionary available for the object.
ccsCOMPL_STAT AddFilter(const slxKEYW_LINE keyword)
Add a filter with only a keyword in it. Format of keyword must be
Short-FITS.
ccsCOMPL_STAT AddFilter(const slxCATEGORY category,
const slxSUBSYSTEM subSystem1,
const slxSUBSYSTEM subSystem2,
const slxPARAMETER parameter,
const slxKEYWORD_CLASS keywClass = slxANY_CLASS)
Adds a filter to the object. Note that when a filter is specified where
the category and/or subsystem the should be ignored, these must be given
in as a NULL initiated string.
ccsCOMPL_STAT AddFilter(const slxCATEGORY category,
const slxSUBSYSTEM subSystem1,
const slxSUBSYSTEM subSystem2,
const slxPARAMETER parameter,
const slxKEYWORD_CLASS keywClass,
const char *lowLim,
const char *hiLim = NULL)
ccsCOMPL_STAT AddFilter(const slxCATEGORY category,
const slxSUBSYSTEM subSystem1,
const slxSUBSYSTEM subSystem2,
const slxPARAMETER parameter,
const slxKEYWORD_CLASS keywClass = slxANY_CLASS,
const vltLOGICAL matchValue = FALSE,
const vltLOGICAL value = FALSE)
ccsCOMPL_STAT AddFilter(const slxCATEGORY category,
const slxSUBSYSTEM subSystem1,
const slxSUBSYSTEM subSystem2,
const slxPARAMETER parameter,
const slxKEYWORD_CLASS keywClass,
const vltINT32 lowLim,
const vltINT32 hiLim = oslxINT_MAX)
ccsCOMPL_STAT AddFilter(const slxCATEGORY category,
const slxSUBSYSTEM subSystem1,
const slxSUBSYSTEM subSystem2,
const slxPARAMETER parameter,
const slxKEYWORD_CLASS keywClass,
const vltDOUBLE lowLim,
const vltDOUBLE hiLim = 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,
slxCATEGORY category,
slxSUBSYSTEM subSystem,
slxPARAMETER parameter)
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() const
ccsCOMPL_STAT String(const char *string)
Return or set the 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
ccsCOMPL_STAT SubSystem(const slxSUBSYSTEM subSyst)
char *SubSystem2() const
ccsCOMPL_STAT SubSystem2(const slxSUBSYSTEM subSyst)
Return or set the sub-system value 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.
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.
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.
When a Setup File is searched according to the INS_SETUPPATH, the first
occurrence of the file is chosen.
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 "..."
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.
Main features of the class are:
o Keyword check/aliasing.
Check of 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.
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).
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 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().
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.
ccsCOMPL_STAT NormalCheck()
Switch Normal Check on. Will fail if no Dictionary is available.
ccsCOMPL_STAT FullCheck()
Switch Full Check on. Will fail if no Dictionary is available.
ccsCOMPL_STAT SoftCheck()
Switch Soft Check on. Will fail if no Dictionary is available.
ccsCOMPL_STAT LoadDictionary(const slxDICTIONARY dicName)
Load a Dictionary into the object. If a Dictionary is already loaded
it is first unloaded.
ccsCOMPL_STAT SetDictionary(const oslxDICTIONARY *dictionary)
Make object use external Dictionary. If a dictionary is already loaded, it
is first unloaded.
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 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.
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 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.
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 |
| |
|
|
|