| |
|
|
|
3 REFERENCE
3.1 SET-UP HANDLING UTILITIES
The program reads in the header of a FITS file, reformats each line by
adding newlines after each FITS line, and prints these to stdout.
It is possible to specify several files at the same time. If "-printName"
is given in, each block of FITS lines will be separated and the filenames
written.
The program locates the set-up file according to the rules specified in
"INS Common SW Specification/VLT-SPE-ESO-17240-0385", and writes the
following report to standard output:
Set-Up File: <<path>/<set-up file>>
Format: <format>
The <format can be either "Short-FITS", "Normal FITS" or "unknown".
<set-up file> Name of the set-up file. Can be given with or without
extension.
-t Run the program in test mode.
3.2 SET-UP FILE HANDLING SUBROUTINES (AND OTHER FUNCTIONS)
#include "slx.h"
ccsCOMPL_STAT slxAliasToShortFITS(const slxKEYW_LINE alias,
const vltLOGICAL loadTable,
const slxFILENAME tableFileName,
slxKEYW_LINE shortFITS,
ccsERROR *error)
The function converts an alias into the complete Short-FITS keyword.
If the conversion was not possible, the first character of the "shortFITS"
buffer will be a NULL character.
When it is desired that the function loads a new set of alias definitions,
the parameter "loadTable" must be ccsTRUE, and the "tableFileName" must
specify the filename.
alias IN Points to buffer containing the alias.
loadTable IN Specifies if the function should update the Alias
Conversion Table. If this is the case, the value should
ccsTRUE, otherwise ccsFALSE.
tableFileName IN The name of the Alias Conversion Table to load. If
"loadTable" is ccsFALSE, this parameter is ignored.
shortFITS OUT Points to buffer which will contain the Short-FITS
keyword. If the alias was not defined, the first
element of this buffer will be a NULL character.
error OUT Indicates the type of error that possibly occurred.
SUCCESS If the operation was successfull.
FAILURE If the operation failed. The following error codes can be
produced by the function:
slxERR_OPEN_ALIAS_TABLE Couldn't open the alias conversion
table.
slxERR_CRE_ALIAS_HASH_TABLE Couldn't create the alias conversion
table.
slxERR_ALIAS_NOT_DEF The alias referenced is not defined
in the table.
The function keeps track of a local hash table for the conversions. It is
important that it is initialized with the correct alias definitions.
The function is private to each application, which then has to initialize
it itself.
Initializing the function should not be done while searching for an
alias. I.e. the table will only be created there will not be searched
for the alias in the table.
The subroutine converts an entire set-up file from the Normal FITS format
to the Short-FITS format. The set-up file in the Short-FITS format
overwrites the old set-up in the Normal FITS format.
setUpFileName IN Name of the set-up file. Can be either the complete
path, or just the filename. In the latter case there
will be searched after the set-up according to the
environment variable "INS_SETUPPATH".
If not set, uses the current directory.
error IN CCS error structure indicating the kind of error which
possibly occurred.
INS_SETUPPATH The environment variable contains a number of
concatenated paths where set-up files are located.
If not set, uses the current directory.
SUCCESS If the operation was successful.
FAILURE If something went wrong. In this case the CCS error structure
indicates the error. The following types are possible:
slxERR_LOCATE_FILE The set-up file could not be located.
slxERR_OPEN_FILE The set-up file could not be opened.
slxERR_FILE_FORMAT One or more lines in the set-up file has
a wrong format (is not Normal FITS).
slxERR_RENAME_FILE An error occurred while renaming the
temporary file.
slxERR_INS_SETUPPATH Could not get the value of the
environment variable INS_SETUPPATH.
The function calls slxLocateSetupFile(), slxDetectFormat() and
slxGetPath() and may return errors generated by these
functions.
#include "slx.h"
ccsCOMPL_STAT slxCreateShortFits2(const miscHASH_TABLE dictionary,
const slxFITS_VALUE value,
slxKEYW_LINE fitsLine,
ccsERROR *error, ..., NULL)
The function generates a Short-FITS keyword line from the input
parameters. This is done in accordance with the rules specified in
"INS Common SW -Part 2, Set-Up Files and FITS Log Handling - SLX,
Doc. No.: VLT-SPE-ESO-17240-0666", which is based on the original
definition of FITS in the "Data Interface Requirements" document
(ARC-SPE-ESO-0000-0001/1.4), and in "NOST Implementation of the Flexible
Image Transport System - FITS, November 6, 1991".
The Short-FITS keyword line generated can be either a non-hierarchical
keyword, i.e. only a parameter, a value and a comment:
"<par> <value>; # <comment>"
or it can be a hierarchical Short-FITS keyword line, i.e. with the format:
"<cat>.[<sub>.]<par> <value>; # <comment>"
Finally the function can generate a line which only consists of a comment:
# <comment>
All strings passed to the function must be NULL terminated.
The comment should be given only as the actual text - do not append any
"#" or try to format it in any way.
The generated Short-FITS line is stored in the buffer pointed to by
"fitsLine".
If for a string keyword the macro slxFITS_NO_VALUE is used, a line without
a value is generated, like for instance:
PAF.HDR.START; # Start of PAF Header
dictionary IN MISC Hash Table containing the Dictionary for the
context. Information such as the type of keyword,
value format, and comment is obtained from the
Dictionary.
value IN Pointer to the value to be written in the FITS line.
fitsLine OUT Pointer to array where the new FITS line will be
written. The line must be at least 80 characters long;
use possibly slxKEYW_LINE as type for the variable.
error OUT Pointer to CCS Error Structure.
#include "slx.h"
ccsCOMPL_STAT slxCreStoreShFITSDicBuf(slxDYN_BUF *setupBuf,
const slxCATEGORY category,
const slxSUBSYSTEM subSystem,
const slxPARAMETER parameter,
const void *value,
const slxDICTIONARY dictionary,
ccsERROR *error)
The function generates a Short-FITS keyword based on the knowledge about
the keyword extracted from a Data Interface Dictionary. It is thus
mandatory to specify a Dictionary.
The created FITS line is automatically stored in the SLX Dynamic Buffer.
setupBuf IN SLX Dynamic Buffer in which the setup keyword line should
be stored.
category IN The category. Can be an empty string ("").
subSystem IN The sunsystem for the keyword. Can be an empty string ("").
parameter IN The parameter name. Must be set.
value IN Pointer to the value. The function deducts from the
Dictionary what type the parameter is, and generates then
the FITS line. A string must be NULL terminated. A logical
must be of type "vltLOGICAL", an integer of type "vltINT32"
and a floating point of "vltDOUBLE".
dictionary IN Name of the Data Interface Dictionary to use for generating
the keywords. The Dictionary is only loaded once, and is
afterwards stored in static memory. If a new Dictionary
name is specified, the function loads the new Dictionary
automatically.
error OUT CCS error structure indicating a possible error
occurring.
#include "slx.h"
ccsCOMPL_STAT slxDetectFormat(const slxFILENAME fileName,
slxSETUP_FORMAT *type,
ccsERROR *error)
The function checks the format of a set-up to determine whether the format
is the normal FITS or the Short-FITS. The type is written to the variable
pointed to by "type".
filePtr IN Points to the file that should be checked.
type IN Points to variable (provided from calling application)
in which the result of the check is stored. Can be
either "slxNORMAL_FITS", "slxSHORT_FITS" or
"slxUNKNOWN_FORMAT".
error OUT CCS error structure in which a possible error
occurring is returned.
SUCCESS In case the operation was successful.
FAILURE In case the operation went wrong. Could be a problem with the
file access. The following error codes can be returned:
slxERR_INS_SETUPPATH Could get the value of this
environement variable.
slxERR_OPEN_FILE An error occurred while opening the file.
The function makes a call to slxLocateSetupFile() and may
return errors generated by this function.
#include "slx.h"
ccsCOMPL_STAT slxDetectFormat(const slxKEYW_LINE keywordLine,
slxSETUP_FORMAT *type,
ccsERROR *error)
The function checks the format of a set-up to determine whether the format
is the normal FITS or the Short-FITS. The type is written to the variable
pointed to by "type".
keywordLine IN The keyword line.
type IN Points to variable (provided from calling application)
in which the result of the check is stored. Can be
either "slxNORMAL_FITS", "slxSHORT_FITS" or
"slxUNKNOWN_FORMAT".
error OUT CCS error structure in which a possible error
occurring is returned.
Since the analysis of the keyword is done only on basis on this one line
the detection might be wrong if the keyword line contains ambigous
information.
slxDynBuf, slxInitDynBuf, slxDynBufAlloc, slxResetDynBuf,
slxSoftResetDynBuf, slxStoreBufDynBuf, slxDynBufReadToCrt,
slxRewindDynBuf, slxSizeDynBuf, slxAllocDynBuf,
slxGetCharDynBuf, slxSetCharDynBuf, slxTruncateDynBuf - tools for
handling SLX Dynamic Buffers
#include "slx.h"
ccsCOMPL_STAT slxInitDynBuf(slxDYN_BUF *dynBuf,
ccsERROR *error)
ccsCOMPL_STAT slxDynBufAlloc(slxDYN_BUF *dynBuf,
const vltUINT32 size,
ccsERROR *error)
ccsCOMPL_STAT slxResetDynBuf(slxDYN_BUF *dynBuf,
ccsERROR *error)
ccsCOMPL_STAT slxSoftResetDynBuf(slxDYN_BUF *dynBuf,
ccsERROR *error)
ccsCOMPL_STAT slxStoreBufDynBuf(slxDYN_BUF *dynBuf,
const char *buf,
const vltUINT32 bufLen,
ccsERROR *error)
ccsCOMPL_STAT slxDynBufReadToCrt(slxDYN_BUF *dynBuf,
char **buffer,
vltUINT32 *bufLen,
ccsERROR *error)
ccsCOMPL_STAT slxRewindDynBuf(slxDYN_BUF *dynBuf,
const vltINT32 bytes,
ccsERROR *error)
char *slxDynBuf(const slxDYN_BUF *dynBuf)
vltUINT32 slxSizeDynBuf(const slxDYN_BUF *dynBuf)
vltUINT32 slxAllocDynBuf(const slxDYN_BUF *dynBuf)
char slxGetCharDynBuf(const slxDYN_BUF *dynBuf,
const vltINT32 index)
ccsCOMPL_STAT slxSetCharDynBuf(slxDYN_BUF *dynBuf,
const vltINT32 index,
char chr,
ccsERROR *error)
ccsCOMPL_STAT slxTruncateDynBuf(slxDYN_BUF *dynBuf,
const vltINT32 bytes,
ccsERROR *error)
ccsCOMPL_STAT slxDynBufAddEOS(slxDYN_BUF *dynBuf,
ccsERROR *error)
slxInitDynBuf()
The function is used to initialize the SLX Dynamic Buffer. Note this
function _must_ be called before starting out using the Dynamic Buffer,
but should only be called once in the lifetime of this buffer.
If it is necessary to reset the buffer use slxResetDynBuf().
dynBuf IN Pointer to SLX Dynamic Buffer structure to handle e.g. a
setup in memory.
slxDynBufAlloc()
The function is used to allocate a number of bytes for a SLX Dynamic
Buffer. If the buffer already is allocated, the size is adjusted to
the specified one. If the buffer is enlarged the contents will
remain untouched after the reallocation.
If the size already allocated is the same as requested nothing is done.
New memory allocated will contain NULL's.
dynBuf IN Pointer to SLX Dynamic Buffer structure to handle e.g. a
setup in memory.
size IN Size to which the buffer should be adjusted.
slxResetDynBuf()
The function is used to reset/initialize the SLX Dynamic Buffer. Possibly
allocated memory is freed - so be sure that it is desirable to delete
the data contained in the buffer.
dynBuf IN Pointer to SLX Dynamic Buffer structure to handle e.g.
setup in memory.
slxSoftResetDynBuf()
The function is used to reset/initialize the SLX Dynamic Buffer. Possibly
allocated memory remains untouched.
dynBuf IN Pointer to SLX Dynamic Buffer structure to handle e.g.
setup in memory.
slxStoreBufDynBuf()
The function appends the contents of the buffer pointed to by "buf" in the
end of the SLX Dynamic Buffer, "dynBuf". If the Dynamic Buffer cannot
contain the new data, the buffer size is adjusted aytomatically.
dynBuf IN Pointer to SLX Dynamic Buffer structure to handle e.g. a
setup in memory.
buf IN Buffer to be stored in the SLX Dynamic Buffer.
bufLen IN Length of the buffer to store
slxDynBufReadToCrt()
The function reads in bytes from the SLX Dynamic Buffer untill it meets
a CRT ('\n') or the end of the buffer is reached.
The buffer read is stored in local memory.
dynBuf IN SLX Dynamic Buffer to handle a file in memory. It is
assumed that the Dynamic Buffer is initialized
properly (see slxGetNextLineBuf()).
buffer OUT Pointer to the beginning of the next line.
bufLen OUT Length of the buffer read.
slxRewindDynBuf()
Rewind the Dynamic Buffer a certain number of bytes from the current
internal reference.
slxDynBuf()
Return pointer to the actual (character) buffer of the slxDYN_BUF structure.
slxSizeDynBuf()
Return the size (bytes stored) in the Dynamic Buffer.
slxAllocDynBuf()
Return number of bytes allocated in the Dynamic Buffer.
slxGetCharDynBuf()
Return a specific character given by the "index". First character has
number 1.
slxSetCharDynBuf()
Set a character in the Dynamic Buffer at the "index" position. First
character in the Dynamic Buffer has number 1.
slxTruncateDynBuf()
Truncate the Dynamic Buffer starting from the last byte. the number of
bytes to truncate is indicated by "bytes".
#include "slx.h"
ccsCOMPL_STAT slxGetKeyword(const char *setupFilename,
const char *keyword,
const vltUINT16 keywordNumber,
slxKEYW_INFO *keywordInfo,
ccsERROR *error)
The function makes a search after the specified keyword in the specified
set-up file. If the keyword is found, the information about this keyword
is returned in the slxKEYW_INFO structure. This structure contains the
following members:
vltUINT8 found Indicates if the keyword was found.
vltUINT16 lineNo; Line number in set-up file;
char keyword[slxKEYW_INFO_LEN]; The complete keyword (Short-FITS).
char category[4]; The category of the keyword, or
empty if not defined.
char subSystem[16]; The subsystem of the keyword, or
empty if not defined.
char parameter[16]; The parameter of the keyword.
char value[slxKEYW_INFO_LEN]; The value as a string. A string
value keeps the quotes.
char comment[slxKEYW_INFO_LEN]; The possible comment of the keyword
line.
If the "keywordName" is initiated with a NULL character, the function
will search after the keyword with the number in the file as indicated by
"keywordNumber".
setupFilename IN The name of the set-up file in which to search for the
keyword.
keyword IN The name of the keyword. Must be in the Short-FITS
format. If given in as "\0", there is searched for the
specified keyword number.
keywordNumber IN The number of the keyword in the set-up file. The
set-up header is considered. The first keyword has
number 1.
keywordInfo OUT Structure that contains the various information about
the keyword.
error OUT CCS error structure that contains information about
a possible error occurring.
The set-up file to be accessed must be in the Short-FITS format, and must
be located in one of the directories defined by INS_SETUPPATH.
INS_SETUPPATH Is a colon separated list of paths, in which set-up files
and set-up related files must be situated.
If not set, uses the current directory.
SUCCESS If the keyword was found and the information read
successfully.
FAILURE If something went wrong during the operation. The following
error codes can be returned by the function:
slxERR_OPEN_FILE Error occurred while opening the
specified file.
slxERR_LOCATE_KEYWORD The keyword was not located.
slxERR_KEYWORD_NOT_FOUND The specified keyword was not
found.
Furthermore the function makes calls to
slxLocateSetupFile(),
#include "slx.h"
ccsCOMPL_STAT slxGetKeywordBuf(slxDYN_BUF *setupHandle,
const char *keyword,
const vltUINT16 keywordNumber,
slxKEYW_INFO *keywordInfo,
ccsERROR *error)
The function makes a search for the specified keyword in the specified
Dynamic Buffer. If the keyword is found, the information about this keyword
is returned in the slxKEYW_INFO structure. This structure contains the
following members:
vltUINT8 found Indicates if the keyword was found.
vltUINT16 lineNo; Line number in set-up file;
char keyword[slxKEYW_INFO_LEN]; The complete keyword (Short-FITS).
char category[4]; The category of the keyword, or
empty if not defined.
char subSystem[16]; The subsystem of the keyword, or
empty if not defined.
char parameter[16]; The parameter of the keyword.
char value[slxKEYW_INFO_LEN]; The value as a string. A string
value keeps the quotes.
char comment[slxKEYW_INFO_LEN]; The possible comment of the keyword
line.
If the "keywordName" is initiated with a NULL character, the function
will search after the keyword with the number in the file as indicated by
"keywordNumber".
setupHandle IN The SLX Dynamic Buffer containing the setup parameters
currently loaded in memory.
keyword IN The name of the keyword. Must be in the Short-FITS
format. If given in as NULL, there is searched for the
specified keyword number.
keywordNumber IN The number of the keyword in the buffer. The setup
header is considered. The first keyword has number 1.
keywordInfo OUT Structure that contains the various information about
the keyword.
error OUT CCS Error Structure that contains information about
a possible error occurring.
SUCCESS If the keyword was found and the information read
successfully.
FAILURE If something went wrong during the operation. The following
error codes can be returned by the function:
slxERR_FORMAT_KEYWORD The format of the keyword is
wrong.
slxERR_KEYWORD_NOT_FOUND The specified keyword was not
found.
Furthermore calls to the functions slxGetNextLineBuf(),
slxSplitShortFITS() are made, and errors generated by these
may be returned.
#include "slx.h"
ccsCOMPL_STAT slxGetNextField(const char *bufPtr,
const vltUINT16 maxLen,
char *nextField,
char **newPos,
ccsERROR *error)
The function returns the next field of a text buffer which could have a
format like:
"<string 1> <string 2>\t\t<string 3>\n<string4>\0"
A string can contain all characters but separators: ' ', '\t', '\n', '='.
If the "bufPtr" points to a place inside a string, like:
"first_string second_string"
^
|--- bufPtr
The "nextField" will be: "st_string\0".
The "newPos" points to the first character after the string in
"nextField" (if any). Can be used to make the function search from
this position to get the next field in the text buffer.
If there is no next field the "nextField" will be initiated with a
'\0'.
#include "slx.h"
ccsCOMPL_STAT slxGetNextField2(const char separator,
const char *bufPtr,
const vltUINT16 maxLen,
char *nextField,
char **newPos,
ccsERROR *error)
ccsCOMPL_STAT slxGetNextField3(const char separator,
const char *bufPtr,
char **nextField,
char **newPos,
ccsERROR *error)
The function returns the next field of a text buffer which could have a
format like:
"<field 1>|<field 2>|<field 3>|<field 4>\0"
A field can contain all characters but the "separator" defined by the
user. A separator could e.g. be ',' (comma).
If the "bufPtr" points to a place inside a string, like:
"first_field,second_field"
^
|--- bufPtr
The "nextField" will be: "st_field\0".
The "newPos" points to the first character after the string in
"nextField" (if any). Can be used to make the function search from
this position to get the next field in the text buffer.
If there is no next field the "nextField" will be initiated with a
'\0'.
#include "slx.h"
ccsCOMPL_STAT slxGetNextKeyBuf(slxDYN_BUF *setupHandle,
const slxDYN_BUF_OP initDynBuf,
char *keyword,
char *value,
ccsERROR *error)
The function returns the sequentially next setup keyword and associated
value from the "setupHandle" buffer.
Before starting out using the function, it should be called once with
the "initDynBuf" set to slxINIT_DYN_BUF; no keyword is returned in this
case. Afterwards "initDynBuf" must be slxDO_NOT_INIT.
When the last keyword has been read from the buffer, the length of the
the "keyword" string will be 0.
setupHandle IN SLX Dynamic Buffer containing setup keyword information.
initDynBuf IN Indicates if the SLX Dynamic Buffer internal pointer
shall be reset. Must be either slxINIT_DYN_BUF, or
slxDO_NOT_INIT.
keyword OUT String containing keyword name (length slxKEYW_LINE)
value OUT String containing keyword value (length slxKEYW_LINE)
If quoted, quotes are stripped.
error OUT CCS error structure indicating a possible error
occurring.
Remember to initialize the Dynamic Buffer before using the function the
1st time, when starting a new readout of keywords from the SLX Dynamic
Buffer.
#include "slx.h"
ccsCOMPL_STAT slxGetNextLineBuf(slxDYN_BUF *setupHandle,
const slxDYN_BUF_OP initDynBuf,
slxKEYW_LINE keywordLine,
ccsERROR *error)
ccsCOMPL_STAT slxGetNextLineBuf2(slxDYN_BUF *dynBuf,
const slxDYN_BUF_OP initDynBuf,
char **keywordLine,
ccsERROR *error)
The function returns the sequentially next setup keyword (including
value and possible comment) from the "setupHandle" buffer.
Before starting out using the function, it should be called once with
the "initDynBuf" set to "ccsTRUE"; no keyword is returned in this
case.
Note that the keyword lines in the Dynamic Buffer must be terminated with
CRT ('\n'). Only up to currently 128 bytes are copied to the "keywordLine"
buffer. In case the CRT is not found before it returns with an error.
When the last keyword has been read from the buffer, the length of the
the "keywordLine" buffer will be '\0'.
setupHandle IN SLX Dynamic Buffer containing setup keyword information.
initDynBuf IN Prepare the SLX Dynamic Buffer for the sequential
request of lines.
keywordLine OUT Buffer in which the next keywordline is copied to.
When the last keyword has been read, this buffer is
initiated with '\0'.
error OUT CCS error structure indicating a possible error
occurring.
SUCCESS In case the operation was successfull.
FAILURE In case the operation failed. The following error codes can be
be generated by the function:
slxERR_DYN_BUF_LINE_LEN The length of the next line longer than
what fits into a buffer of type
slxKEYW_LINE (use slxDynBufReadToCrt()).
Remember to initialize the Dynamic Buffer before using the function the
1st time, when starting a new readout of keywords from the SLX Dynamic
Buffer.
#include "slx.h"
csCOMPL_STAT slxLoadFile(slxFILENAME fileName,
const char *envVar,
slxDYN_BUF *fileBuf,
ccsERROR *error)
The function loads a file into an SLX Dynamic Buffer. The old contents
is automatically deleted.
fileName IN/OUT Name of the setup file to load (/merge) into the
buffer. The function will write the complete filename
of the file loaded in the buffer at successfull
return, if not the complete filename was specified.
envVar IN Colon separated list of paths in which the file
will be searched.
fileBuf IN/OUT SLX Dynamic Buffer to handle a file in memory. The
application should normally not themselves access
the contents of the structure, but should use the
access routines.
error OUT CCS Error Structure indicating a possible error
occurring.
INS_SETUPPATH Specifies a number of paths where set-up files are stored.
If not set, uses the current directory.
SUCCESS In case the operation was successfull.
FAILURE In case the operation failed. The following error codes can be
be generated by the function:
slxERR_OPEN_FILE Cannot open setup file.
slxERR_READ_FILE Cannot read from setup file.
Furthermore errors generated by the functions
slxLocateSetupFile(), slxStoreLineBuf() can be returned.
#include "slx.h"
csCOMPL_STAT slxLoadSetup(const slxFILENAME fileName,
slxDYN_BUF *setupHandle,
slxCHANGE_RECORD changeRec,
ccsERROR *error)
The function loads a setup file into a SLX Dynamic Buffer. If setup
keywords are already loaded in the Dynamic Buffer, the function will merge
the new keywords with the old ones -- the new ones overwrites the old.
Before loading a new setup it may be necessary to reset the Dynamic Buffer
(slxResetDynBuf()) in order not to mix up old and new parameters, if this
is not desirable.
Only actual keywords are loaded. I.e. no lines starting with the "#"
(comment) will be loaded, and blank lines will be skipped.
fileName IN/OUT Name of the setup file to load (/merge) into the
buffer. The function will write the complete filename
of the file loaded in the buffer at successfull
return, if not the complete filename was specified.
setupHandle IN/OUT SLX Dynamic Buffer to handle a setup in memory. The
application should normally not themselves access
the contents of the structure, but should use the
access routines.
changeRec OUT Array indicating which keywords that changed
while the function was operating on the Dynamic
Buffer. Should be declared of type slxCHANGE_RECORD.
The function does not reset the Change Record when
it starts its operations. Note that the first
keyword line has number _1_ (first field of the
Change Record is not used).
error OUT CCS Error Structure indicating a possible error
occurring.
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.
SUCCESS In case the operation was successfull.
FAILURE In case the operation failed. The following error codes can be
be generated by the function:
slxERR_FILE_FORMAT Format of setup file wrong.
slxERR_OPEN_FILE Cannot open setup file.
slxERR_READ_FILE Cannot read from setup file.
Furthermore errors generated by the functions
slxLocateSetupFile(), slxDetectFormat(), slxStoreLineBuf(),
can be returned.
If a setup file for a new exposure shall be loaded into memory, the
Dynamic Buffer should probably be reset using slxResetDynBuf().
#include "slx.h"
ccsCOMPL_STAT slxLocateFile(const char *envVar,
const slxFILENAME fileName,
slxFILENAME completeName,
ccsERROR *error)
The function searches for the specified filename in the path list given
by the environment variable "envName". The possible first occurrence of
the file is returned!
If it does not find the set-up file, the function returns with FAILURE,
and the first character of the "completeName" will be a NULL character
('\0'); i.e. the length (strlen()) will be 0.
It is up to the calling application itself to open/load the file.
envVar IN Colon separated list of paths in which there will
be searched for the file.
setUpFileName IN The name of the set-up file to locate.
completeName OUT The complete name of the specified set-up file
including the path. If the file was not found,
the first character of the buffer will be a NULL
character.
error IN Indicates a possible error occurring.
SUCCESS If the operation was successfull.
FAILURE If the operation failed. The following error code is defined:
slxERR_ENV_VAR Could not get the value of the environment
variable specified by "envVar".
slxERR_LOCATE_FILE Error occurred while locating set-up file.
It is assumed that filenames can consist of the characters a-z, A-Z,
0-9, "_", "-", "." and "#". Wildcards and tilde (~) representations are not
supported. The filenames in the specified environment variable the
absolute names including the complete paths.
#include "slx.h"
ccsCOMPL_STAT slxLocateSetupFile(const slxFILENAME setupFileName,
slxFILENAME completeName,
ccsERROR *error)
The function searches for the specified set-up file (or any file)
according to the environment variable INS_SETUPPATH. This is done in
accordance with the search criterias described in
INS Common SW/VLT-SPE-ESO-17240-0385.
If it does not find the set-up file, the function returns with FAILURE,
and the first character of the "completeName" will be a NULL character
('\0'); i.e. the length (strlen()) will be 0.
setUpFileName IN The name of the set-up file to locate.
completeName OUT The complete name of the specified set-up file
including the path. If the file was not found,
the first character of the buffer will be a NULL
character.
error IN Indicates a possible error occurring.
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.
SUCCESS If the operation was successfull.
FAILURE If the operation failed. The following error code is defined:
slxERR_INS_SETUPPATH Could not get the value of the environment
variable INS_SETUPPATH.
slxERR_LOCATE_FILE Error occurred while locating set-up file.
It is assumed that filenames can consist of the characters a-z, A-Z,
0-9, "_", "-", "." and "#". Wildcards and tilde (~) representations are not
supported. The filenames in the INS_SETUPPATH should be the absolute names
including the complete paths.
slxLookUpKeywordHashX, slxLoadDicHash, slxInstallDicBuf - load a
Dictionary into a Hash Tablelook/look up a keyword in an SLX Hash Table
#include "slx.h"
ccsCOMPL_STAT slxInstallDicBuf(slxDYN_BUF *dicBuf,
miscHASH_TABLE dicHashTable,
slxDIC_HANDLE *dicList,
ccsERROR *error)
ccsCOMPL_STAT slxLoadDicHash(miscHASH_TABLE dicHashTable,
const slxDICTIONARY dictionary,
ccsERROR *error)
ccsCOMPL_STAT slxLoadDicHashList(miscHASH_TABLE dicHashTable,
const slxDICTIONARY dictionary,
slxDIC_HANDLE *dicList,
ccsERROR *error)
ccsCOMPL_STAT slxLookUpKeywordHashX(const miscHASH_TABLE dicHashTable,
const slxKEYW_LINE keyword,
slxDIC_HANDLE **dicInfo,
ccsERROR *error)
These functions makes it possible to use several Dictionaries at the
same time.
slxLoadDicHash() is used to load a Data Interface Dictionary into an
SLX Hash Table. It is assumed that no Hash Table is already loaded into
the Hash Table. If this is the case the function slxHashDelete() must be
called first.
If "all" is specified for "dictionary" all Dictionaries stored in the
INS Tree are loaded and merged together. They are loaded in alphabetically
order.
If it is tried to load several Dictionaries into one miscHASH_TABLE without
calling the function slxFreeDictionary() on the table, the Dictionaries
are merged together. I.e., if the a keyword appears several times, the
last occurrence is the one stored in the Dictionary.
The slxLookUpKeywordHashX() function is used to perform a fast look-up of
a keyword in the SLX Hash Table.
slxInstallDicBuf() is used to install a Dictionary in an SLX Hash Table
from an SLX Dynamic Buffer.
dictionary IN Name of the dictionary to load.
dicHashTable IN The SLX Hash Table containing the Dictionary. The
Dictionary must be loaded by slxLoadDicHash().
keyword IN Name of the keyword to look up; must be in the
Short-FITS format.
dicInfo OUT Pointer-pointer to SLX Dictionary Structure that
contains the information of the Dictionary Record
searched. The element points to an element in the SLX
Hash Table (don't modify it).
dicList IN/OUT Pointer to header of list of SLX Dictionary Handle
structure. This list must have a header element.
When calling the function the first time,
it must be ensured that the element is properly
initialized (dicHandle->next = dicHandle,
dicHandle->prev = dicHandle).
The keywords in the SLX Dictionary Handle List
will be sorted alphabetically (order: decreasing).
If it is not desirable to have the list, NULL
can be given in for "dicList".
error OUT CCS error structure indicating a possible error
occurring.
Dictionaries The Dictionaries used must have the format as defined for
VLT Data Interface Dictionaries.
SUCCESS In case the operation was successfull.
FAILURE In case the operation failed. If the keyword was not found
the error->errorNumber will be slxERR_KEYWORD_NOT_FOUND.
It is the reponsability of the calling application to make a call to
miscHashInit(3) before calling slxLoadDicHash(3).
#include "slx.h"
ccsCOMPL_STAT slxGetDicRecSeq(const vltLOGICAL init,
vltLOGICAL *gotRecord,
slxDYN_BUF dicBuf,
slxDIC_HANDLE *dicInfo,
ccsERROR *error)
The function is used to return records in a Dictionary sequentially.
If the record for the parameter is found, the values from the dictionary
are stored in the SLX Dictionary Handle Structure. The context of this
structure is:
Parameter Name: Name of the parameter, e.g. "DET DATE"
Class: Class of the parameter.
Context: The context in which it is used.
Type: The type of the parameter. Possible types are "string"
"logical", "integer" and "double".
Value Format: Format in which the parameter should be represented.
The format representation from ANSI-C is used (see
e.g. printf()).
Unit: The SI or derived SI unit for the parameter.
Comment Format: The standard comment (if any) for the parameter.
Description: A (detailed) description of the parameter.
init IN Indicate for the function if it should start form the
first record. When the "init" parameter is ccsTRUE the
function returns with SUCCESS but doesn't set the SLX
Dictionary Handle. Before starting to use the function
on a buffer this flag must always be set to ccsTRUE.
gotRecord OUT Indicates for calling function if a record was found.
I.e. when there are no more records to return this flag
becomes ccsFALSE.
dicBuf OUT SLX Dynamic Buffer containing the Dictionary loaded in
from the file.
dicInfo OUT the next dictionary record.
error OUT CCS Error Structure.
ESO-VLT-DIC.<name> Dictionaries for the VLT. There are a number of
dictionaries defined, e.g. for the instruments
ISAAC, FORS and UVES.
#include "slx.h"
ccsCOMPL_STAT slxMergeSetupBuf(slxDYN_BUF *setupHandle,
const char *instrument,
slxCHANGE_RECORD changeRec,
ccsERROR *error,
..., NULL)
Merge a number of setup files and keywords into a SLX Dynamic Buffer.
The syntax of variable list of parameters is as follows:
"-k", "<Short-FITS keyword>"[, "<Short-FITS keyword>"]
"-f", "<filename>"[, "<filename>"]
"-b", <SLX Dynamic Buffer ptr>[, <SLX Dynamic Buffer ptr>]
("-b" = Setup Buffer (slxDYN_BUF))
It is possible to have as many "-k", "-f" and "-b" indicators as desired.
The order is not important.
Note that the SLX Dynamic Buffer only will contain the actual keywords
entered (found in files). I.e. no setup file header will be generated.
Blank lines and setup header keywords ("SUP." keywords) are discarded.
setupHandle IN/OUT Buffer in which the setup parameters will be merged.
instrument IN Designates the dictionary to use. Could be e.g.
"ISAAC" or "UVES". If this is initiated with '\0' no
Dictionary is used and setup keywords simply merged
into the buffer.
changeRec OUT Array indicating which keywords that changed
while the function was operating on the Dynamic
Buffer. Should be declared of type slxCHANGE_RECORD.
The function does not reset the Change Record when
it starts its operations. Note that the first
keyword line has number _1_ (first field of the
Change Record is not used).
error OUT CCS error structure indicating a possible error
occurring.
... IN Variable list of parameters. Note, that strings must
be given in _with_ quotes. References to SLX Dynamic
Buffers, must be pointers.
Setup files must be terminated with ".ref", ".ins", ".det", or ".targ",
and must be in the Short-FITS format.
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.
SUCCESS In case the operation was successfull.
FAILURE In case the operation failed. The following error codes can be
be generated by the function:
slxERR_FILE_FORMAT
slxERR_OPEN_FILE
slxERR_READ_FILE
slxERR_INPUT_PARS
The function makes calls to slxGetNextLineBuf(),
slxStoreLineBuf(), slxLocateSetupFile(), and slxDetectFormat(),
and may return errors generated by these functions.
If not the complete path of a setup filename is given in, the first
occurence of a setup file in the INS_SETUPPATH is used.
It might be usefull to reset the SLX Dynamical Buffer before performing
a new merge, since other 'old' setup parameters will be contained in the
buffer.
slxDYN_BUF setupHandle1;
slxDYN_BUF setupHandle2;
ccsERROR error;
slxCHANGE_RECORD changeRec;
slxInitDynBuf(&setupHandle1, &error);
slxInitDynBuf(&setupHandle2, &error);
if (slxLoadSetup("mode1.ref", &setupHandle2, &error) == FAILURE)
... error processing ...
slxResetDynBuf(&setupHandle, &error);
memset(changeRec, 0, sizeof(slxCHANGE_RECORD));
if (slxMergeSetupBuf(&setupHandle1,
"ISAAC",
changeRec,
&error,
"-b", &setupHandle2,
"-k", "DET.DIT 3.02E-2 # Integration Time",
"-f", "detector2.det",
"-k", "DET.NDIT 10 # Averaged DITs",
NULL) == FAILURE)
... error processing ...
When entering keywords (using the "-k" specifier) with their value
(and possible comment), this must be given in as one string as shown in
the example above. If the value is a string the whole keyword string must
have the format "<keyword> \"<string>\"; # <comment>".
The variable list of commands must be terminated with a NULL.
#include "slx.h"
ccsCOMPL_STAT slxNormalToShortFITS(const slxKEYW_LINE normalFITS,
slxKEYW_LINE shortFITS,
ccsERROR *error)
The function converts a set-up keyword from the normal FITS format to the
short FITS format.
If the Short-FITS line generated is longer than 80 characters it is
truncated to this value.
normalFITS IN Pointer to buffer containing the keyword string
in the normal FITS format.
shortFITS IN Pointer to buffer in which the keyword string in
Short-FITS keyword will be written. Must be provided
by the calling application. Make this buffer somewhat
larger say 100 character or so.
error OUT Indicates the type of an error possibly occurring.
SUCCESS In case the operation was successful.
FAILURE In case the operation went wrong. Could be a problem with the
format of the keyword line. The following error code can be
returned:
slxERR_FORMAT_KEYWORD The format of the keyword is wrong.
The function is used to reset an SLX Ditionary Record.
dicInfo IN Pointer to the dictionary record.
error OUT CCS error structure indicating a possible error
occurring.
The function should not be called on a dictionary handle in which a record
still has not been loaded.
#include "slx.h"
ccsCOMPL_STAT slxSaveFile(const slxFILENAME fileName,
const char *envVar,
slxDYN_BUF *fileBuf,
ccsERROR *error)
The function saves a file with an SLX Dynamic Buffer. The contents of the
Dynamic Buffer is flushed directly into the file without any kind of
reformatting. The contents of the Dynamic Buffer remains untouched.
If the filename is a complete path (must start with a "/") the function
tries to store the file according to the name as it is. Else the function
checks if the file already exists in one of the directories given by the
environment variable "envVar". If this is the case, the old file is
overwritten with the new one (if possible). If the file didn't exists and
the path was not given in, the function tries to store the file in the
first directory given by "envVar".
fileName IN/OUT Name of the setup file to save. If the name was not
given in with the complete path, the name plus the
path used will be returned in case of SUCCESS.
envVar IN Environment variable which is a colon separated list
of paths where this type of file is stored.
fileBuf IN/OUT SLX Dynamic Buffer to handle a file in memory. The
application should normally not themselves access
the contents of the structure, but should use the
access routines.
error OUT CCS Error Structure indicating a possible error
occurring.
SUCCESS In case the operation was successfull.
FAILURE In case the operation failed. The following error codes can be
be generated by the function:
slxERR_OPEN_FILE Cannot open setup file.
slxERR_WRITE_FILE Cannot read from setup file.
Furthermore errors generated by the functions
slxLocateSetupFile().
#include "slx.h"
ccsCOMPL_STAT slxSearchSetupFile(const slxFILENAME baseName,
vltINT32 *numberFound,
slxSTRING_LIST *fileList,
const vltLOGICAL globalSearch,
const vltLOGICAL stopFirstOccur,
const vltLOGICAL skipInsUserDir,
ccsERROR *error)
ccsCOMPL_STAT slxSearchDictionary(const slxDICTIONARY dictionary,
slxFILENAME pafDicFullName,
ccsERROR *error)
ccsCOMPL_STAT slxGetDirInfo(slxFILENAME dirName,
slxSTRING_LIST *entryList,
vltINT32 *noOfEntries,
ccsERROR *error)
Common parameters for search routines:
baseName IN The basename is the name of the file to look for.
The name may contain wildcards ("*"), e.g.:
"myFile*". In this case no assumption is made about the
extension. The basename can be given in as
o A single filename, e.g. "myFile.det".
o Including the complete path, e.g.
"/home/users/user/INS_ROOT/SYSTEM/COMMON/\
SETUPFILES/DET/myFile*"
o Starting with tilde for user's home directory,
e.g. "~/INS_ROOT/SYSTEM/COMMON/\
SETUPFILES/DET/myFile*"
o Starting with an environment variable, e.g.
"$MY_VAR/DIR/myFile.det".
In the latter three cases, a search will only be
performed in one directory, even if "globalSearch" is
ccsTRUE.
numberFound OUT Indicates the number of files found, matching the
specified conditions.
fileList IN Pointer to slxSTRING_LIST element. The instance must
be created and initialized by the calling application.
globalSearch IN Indicates if a global search in the INS Tree should be
performed.
stopFirstOccur IN If true, the file search will stop at the first
file found, matching the specified conditions.
skipInsUserDir IN Indicates if the search should skip the branch
currently referenced to by the INS_USER environment
variable.
slxSearchSetupFile()
Used to search for Setup Files in the INS Tree. The search is performed
according to the scheme defined in the INS Common Software Specification
"VLT-SPE-ESO-17240-0385, 2.1".
slxGetDirInfo()
Used to get all directories starting from a certain start directory.
The slxSTRING_LIST element must be allocated by the calling application.
The number of directory entries found is indcated by "noOfEntries".
The slxSTING_LIST pointer given in to the functions must point to an
element allocated by the calling application.
#include "slx.h"
ccsCOMPL_STAT slxShortFITSToAlias(const slxKEYW_LINE shortFITS,
const vltLOGICAL loadTable,
const slxFILENAME tableFileName,
slxKEYW_LINE alias,
ccsERROR *error)
The function converts a Short-FITS keyword into the alias representation.
If the alias was not defined, the first character of the buffer pointed
to be "alias" will be a NULL character.
The first time the function is used, and whenever the Alias Conversion
Table is changed, the function must be called with the "loadTable"
parameter set to ccsTRUE, and the name of the table to load must be
specified.
shortFITS IN Points to buffer containing the Short-FITS keyword.
loadTable IN Indicates if the function should reinitialize its
Alias Conversion Table. If this is the case, ccsTRUE
must be the value, otherwise ccsFALSE.
tableFileName IN Filename of Alias Conversion Table to be loaded. If
"loadTable" is ccsFALSE, this parameter is ignored.
alias OUT The alias corresponding to the Short-FITS keyword.
error OUT Indicates a possible error that occurred.
SUCCESS If the operation was successfull.
FAILURE If the operation failed. The following error codes can be
returned:
slxERR_OPEN_ALIAS_TABLE Couldn't open the alias conversion
table.
slxERR_CRE_ALIAS_HASH_TABLE Couldn't create the alias conversion
table.
slxERR_ALIAS_NOT_DEF The alias referenced is not defined
in the table.
The function keeps track of a local hash table for the conversions. It is
important that it is initialized with the correct alias definitions.
The function is private to each application, which then has to initialize
it itself.
#include "slx.h"
ccsCOMPL_STAT slxShortToNormalFits2(const slxKEYW_LINE shortFits,
slxKEYW_LINE normalFits,
const miscHASH_TABLE dictionary
ccsERROR *error)
The function converts a set-up keyword from the Short-FITS format to the
normal FITS format.
shortFits IN Buffer containing the keyword string in the Short-FITS
format.
normalFits IN Buffer in which the keyword string in normal FITS will
be written.
dictionary IN Dictionary loaded into a MISC Hash Table. Use the
function slxLoadDicHashX() to build up the Hash Table.
#include "slx.h"
ccsCOMPL_STAT slxSplitFits2(const slxKEYW_LINE fitsLine,
slxCATEGORY category,
slxSUBSYSTEM subSystem1,
slxSUBSYSTEM subSystem2,
slxPARAMETER parameter,
slxVALUE value,
slxCOMMENT comment,
ccsERROR *error)
The function splits a FITS line in its components and return these in the
output parameters. The "HIERACH ESO " is not returned.
All output buffers must be allocated by the calling application. They
should be at least one byte longer than the maximum length of the string to
fill in, i.e. for the category 4 bytes.
If an output buffer is not defined, the first element in this will be
a null charcter ('\0'). E.g. if a standard FITS line is parted, the
"category" and "subSystem" buffers will start with a '\0'.
fitsLine IN Pointer to buffer containing the FITS line. MUST be
terminated with a null character.
category OUT Pointer to buffer which will contain the possible
category.
subSystem1/2 OUT Pointers to buffers which will contain the possible
subsystems.
parameter OUT Pointer to buffer which will contain the parameter.
value OUT Pointer to buffer which will contain the value
(as a string). If the value is a string, the single
quotes are returned. A logical value is not returned
with single quotes.
comment OUT Pointer to buffer which will contain the possible
commment.
SUCCESS In case the operation was succcessful.
FAILURE In case the operation failed. The function can return the
following error code:
slxERR_FORMAT_KEYWORD The format of the keyword line is wrong.
The function does not check for the syntax of the line, so if it is not
correctly formatted, the result in the output buffers may be unpredictable.
#include "slx.h"
ccsCOMPL_STAT slxSplitShortFits2(const slxKEYW_LINE shortFitsLine,
slxCATEGORY category,
slxSUBSYSTEM subSystem1,
slxSUBSYSTEM subSystem2,
slxPARAMETER parameter,
slxVALUE value,
slxCOMMENT comment,
ccsERROR *error)
The function splits a Short-FITS line in its components and return these
in the output parameters.
All output buffers must be allocated by the calling application. They
should be at least one byte longer than the maximum length of the string to
fill in, i.e. for the category, 4 bytes.
If an output buffer is not defined, the first element in this will be
a null charcter ('\0'). E.g. if a standard FITS line is parted, the
"category" and "subSystem" buffers will start with a '\0'.
fitsLine IN Pointer to buffer containing the Short FITS line. MUST
be terminated with a null character.
category OUT Pointer to buffer which will contain the possible
category.
subSystem1/2 OUT Pointers to buffers which will contain the possible
subsystem keywords.
parameter OUT Pointer to buffer which will contain the parameter.
value OUT Pointer to buffer which will contain the value
(as a string). A string value is returned with quotes
(also a logical value).
comment OUT Pointer to buffer which will contain the possible
commment.
error OUT CCS error structure indicating s possible error
occurring.
SUCCESS If the operation was successful.
FAILURE If the operation failed: The following error codes can be
returned:
slxERR_FORMAT_KEYWORD The format of the keyword (line) is wrong.
The function does not check for the syntax of the line, so if it is not
correctly formatted, the result in the output buffers may be unpredictable.
#include "slx.h"
ccsCOMPL_STAT slxStoreLine(const slxKEYW_LINE keywordLine,
const slxFILENAME fileName,
ccsERROR *error)
The function searches in the specified file for a set-up keyword
identical to the one in the buffer pointed to by "keywordLine". If it
finds this line, it replaces the old with the new. Note that this
includes overwriting the old comment which might be there with the new one.
If the keyword (combination) was not found, the new line is appended in the
file.
The function works on kyewords in the Short-FITS format.
keywordLine IN The keyword command line which shall be stored in the
set-up file. Must be in the Short-FITS format.
fileName IN Pointer to the set-up file where the new keyword line
shall be stored.
error OUT CCS error structure. Indicates a possible error
occurring.
SUCCESS If the operation was successful.
FAILURE If something went wrong. The following error codes can be
returned:
slxERR_INS_SETUPPATH Could get the value of the environment
variable INS_SETUPPATH.
slxERR_OPEN_FILE Could not open file.
slxERR_FORMAT_KEYWORD Format of keyword is wrong.
slxERR_WRITE_FILE Error in writing in file.
The function makes calls to slxLocateSetupFile() and
slxGetPath() and may return errors generated by these functions.
The subroutine assumes that the set-up file is syntactically correct.
To ensure this, run possibly "slxCheckSyntaxSetUp" on the set-up first.
#include "slx.h"
ccsCOMPL_STAT slxStoreLineBuf(const slxKEYW_LINE keywordLine,
slxDYN_BUF *setupHandle,
vltINT32 *lineNo,
ccsERROR *error)
The function searches in the specified Dynamic Buffer for a set-up keyword
identical to the one in the buffer pointed to by "keywordLine". If it
finds this line, it replaces the old with the new. Note that this includes
overwriting the old comment which might be there with the new one. If not
found, the new keyword is appended in the Dynamic Buffer.
The keywords must be in the Short-FITS format.
keywordLine IN The keyword command line which shall be stored in the
set-up file. Must be in the Short-FITS format, and
NULL terminated.
setupHandle IN Pointer to a SLX Dynamic Buffer.
lineNo OUT Indicates in which line the new line was stored. First
line has number 1.
error OUT CCS Error Structure. Indicates a possible error
occurring.
SUCCESS If the operation was successful.
FAILURE If something went wrong. The following error codes can be
returned:
slxERR_FORMAT_KEYWORD The format of the keyword line entered
is wrong.
slxERR_ALLOC_MEM Could not allocate memory.
Furthermore calls are made to slxGetNextLineBuf(), and errors
generated by this function may be returned.
slxStringList, slxInitStrList, slxFreeStrList, slxDelStrEl, slxAddStrEl,
slxStrListMerge, slxStrNextEl - functions to handle the SLX String List
feature
#include "slx.h"
ccsCOMPL_STAT slxInitStrList(slxSTRING_LIST **strElPtr,
const char *hdrString,
ccsERROR *error)
ccsCOMPL_STAT slxFreeStrList(slxSTRING_LIST *strElPtr,
ccsERROR *error)
char *slxStrNextEl(const slxSTRING_LIST *strListHdr,
const vltLOGICAL init)
ccsCOMPL_STAT slxAddStrEl(slxSTRING_LIST *strElPtr,
const char *string,
const vltLOGICAL addFirstInList,
const vltINT32 id,
ccsERROR *error)
ccsCOMPL_STAT slxDelStrEl(slxSTRING_LIST *strElPtr,
ccsERROR *error)
ccsCOMPL_STAT slxStrListMerge(char *string,
slxSTRING_LIST *targList,
vltINT32 *elsStored,
ccsERROR *error)
ccsCOMPL_STAT slxStrListGetEl(slxSTRING_LIST *stringList,
vltINT32 elNumber,
char **string,
ccsERROR *error)
The SLX String List feature is used to maintain a list of strings.
Before starting to use a string list it should be initialized using the
slxInitStrList() function.
The functions slxAddStrEl(), respectively slxDelStrEl(), can be used to
add and delete string element in the list.
slxAddStrEl()
The "addFirstInList" can be used to specify if the new element should be
added first in the list. The "id" can be used to obtain a certain
sequence of the elements. The lower the ID the more in front of the list
the element will be inserted. The Header Element has ID 0.
slxStrListMerge()
Inserts a string on the "*elsStored" place in the list. If an element
exists it is overwritten, otherwise a new element is inserted.
slxUtils, slxGetPath, slxGenDayTim, slxGenDayTim2,
slxGetUTDate, slxGetUTTime,
slxSkipLine, slxStrToUpper, slxStripQuotes, slxStrDup,
slxBuildInsFileName, slxBuildInsUserDir, slxAssembleKeyword,
slxAssKey, slxIsShortFITS, slxGetLastChar, slxSetLastChar,
slxKeywClass2No, slxGetValueEnvVar, slxBitPix2NoBytes, slxGetKeywordIndex,
slxReplaceIndex, slxResolvePath, slxStr2Logical, slxCheckExtension,
slxYankExtension, slxYankTrailNewLines
- various small utilities
#include "slx.h"
ccsCOMPL_STAT slxGetPath(const slxFILENAME fileName,
slxFILENAME path,
ccsERROR *error)
ccsCOMPL_STAT slxGetFileName(const slxFILENAME completeName,
slxFILENAME fileName,
ccsERROR *error)
void slxGenDayTim(slxKEYW_LINE dayTime)
void slxGenDayTim2(const time_t timeSecs, slxKEYW_LINE dayTime)
void slxGetUTDate(slxUT_DATE utDate)
void slxGetUTTime(vltUINT32 *utTime)
int slxSkipLine(const char *line)
void slxStrToUpper(char *str)
void slxStripQuotes(char *str)
char *slxStrDup(const char *string)
ccsCOMPL_STAT slxBuildInsFileName(const slxFILENAME insPath1,
const slxFILENAME insPath2,
const slxFILENAME insPath3,
const slxFILENAME fileName,
slxFILENAME completeName,
ccsERROR *error)
ccsCOMPL_STAT slxBuildInsUserDir(slxFILENAME insUserDir,
char *user,
ccsERROR *error)
ccsCOMPL_STAT slxAssembleKeyword(const slxCATEGORY category,
const slxSUBSYSTEM subSystem,
const slxPARAMETER parameter,
slxKEYW_LINE keyword,
ccsERROR *error)
char *slxAssKey(const char *key1, const int index1, ...)
vltLOGICAL slxIsShortFITS(const slxKEYW_LINE keyword)
char slxGetLastChar(char *string)
void slxSetLastChar(char *string,
char chr)
ccsCOMPL_STAT slxKeywClass2No(const char *classStr,
slxKEYWORD_CLASS *classNo,
ccsERROR *error)
ccsCOMPL_STAT slxGetValueEnvVar(const char *envVar,
char **destBuf,
ccsERROR *error)
ccsCOMPL_STAT slxBitPix2NoBytes(const vltINT32 bitPix,
vltINT32 *noOfBytes,
ccsERROR *error)
ccsCOMPL_STAT slxGetKeywordIndex(const slxKEYW_LINE keyword,
vltINT32 *index,
ccsERROR *error)
void slxReplaceIndex(slxKEYW_LINE keyword, vltINT32 *index)
ccsCOMPL_STAT slxResolvePath(const slxFILENAME orgPath,
char **completePath,
ccsERROR *error)
vltLOGICAL slxStr2Logical(const char *strLogical)
void slxYankTrailNewLines(char *str)
slxGetPath()
Returns the path for a filename. Fails in case the path is not correctly
formatted.
If a filename is not entered with the absolute path (first character
different from '/'), the path will be an empty buffer ("\0").
fileName IN Name of file including the absolute path.
path OUT The path for the filename.
slxGenDayTim()
slxGenDayTim2()
Generate the string for the DAYTIM keyword as:
DAYTIM "1996-10-15T16:21:23"
slxGetUTDate()
The function generates the present UT date as a string in the format:
'DD/MM/YY'
(From 1998-01-01 or later, probably in the format 'YYYY-MM-DD')
This format is used e.g. in the FITS header of image data files, and in
the observation set-up files.
fitsDate OUT The generated date as a string. The buffer must be
allocated by the calling application.
slxGetUTTime()
The function generates the UT time (seconds since midnight) and returns
this figure in the "utTime" parameter. This time reference is e.g. used
for the FITS header of image data, and for the observation set-up files.
utTime OUT The UT time - seconds since midnight.
slxSkipLine()
The function is used when reading in VLT files, which typical has
a comment initiated with a "#".
The function returns 1 if the first character of the line is one of the
following characters: "#", " ", "\n", "\0" or "\t" , otherwise 0 is
returned.
line IN Pointer to string that shall be checked.
slxStringToUpper()
The function converts a string containing lower-case letters or a mixture
of lower-case and upper-case to consist of only uppercase letters. If a
non ASCII character is contained in the string, this is ignored (remains
unchanged). The string must be NULL terminated.
str IN Pointer to the string that shall be upper-cased.
slxStripQuotes()
Strings in setup files are enclosed in quotes. The function strips these
off using the same character buffer for storing the processed string.
The string must be NULL terminated.
If the string is not contained in quotes, the function simply returns
without changing the string.
str IN Pointer to the string that shall be stripped.
ccsCOMPL_STAT slxAssembleKeyword()
Assemble keyword and store it n a buffer provided by the calling process.
This function is obsolete; use rather slxAssKey().
char *slxAssKey(const char *key1, const int index1, ..., NULL)
Assembles a number of sub-keywords to a Short-FITS style one. An arbitrary
number of keywords can be given in. A keyword must always be followed by an
index. If this is zero no index is appended to the keyword.
slxKeywClass2No()
Converts a Keyword Class descriptor entered as a string to a number
type slxKEYWORD_CLASS).
ccsCOMPL_STAT slxGetValueEnvVar()
Gets the value of the specified environment variable.
ccsCOMPL_STAT slxGetKeywordIndex()
Gets the possible index of the keyword given in. E.g. if the keyword is
"FILT5", index will be 5.
void slxReplaceIndex()
Function that replace a possible index in a keyword with "i" and return
the index if defined
ccsCOMPL_STAT slxResolvePath()
Function to resolve a path of entries that may be environment variables
and indirect reference to HOME. E.g., the function can resolve:
"~/$MY_VAR/MY_DIR/file", "~<user>/MY_DIR" or "$HOME/$MY_VAR/MY_DIR/file".
A colon separated list of variables will be resolved as well.
3.3 IMAGE FITS HEADER MANIPULATION SUBROUTINES
#include "slx.h"
ccsCOMPL_STAT slxAddFITSBlocks(const int fd,
const vltUINT8 noOfBlocks,
const vltLOGICAL writeEND,
ccsERROR *error)
The function is used to reserve space for the FITS header of an image data
file. This is done by adding a number of FITS blocks, only consisting of
blanks, to an already existing image data file.
If 0 is specified as "noOfBlocks", the function will check that the number
of characters in the file is equal to: 'n x slxFITS_HD_BLOCK_LEN',
where n is 1, 2, 3, ..., and slxFITS_HD_BLOCK_LEN, is the number of
characters in one FITS header block. If this is not fulfilled, there is
padded with an adequate number of blanks. Otherwise if "noOfBlocks" is
larger that 0, the function will check for the completion of existing
blocks and add a number of blocks corresponding to "noOfBlocks".
The file pointer will point to the end of the file when the function
terminates successfully.
fd IN File descriptor for a file which is already opened.
noOfBlocks IN The number of blocks that should be allocated in the
image header.
writeEND IN If this flag is ccsTRUE the function will write the
END keyword at the end of the header.
error OUT Structure in which a possible error occurring is
specified.
SUCCESS In case the operation was successful.
FAILURE In case the operation failed. The following errors can be
generated by the function:
slxERR_READ_FILE An error occurred while reading from the file.
slxERR_WRITE_FILE An error occurred while writing in the file.
The file managed by "fd" must be opened for reading and writing.
The function assumes that there are no newline characters in the file.
#include "slx.h"
ccsCOMPL_STAT slxCreateFits2(const miscHASH_TABLE dictionary,
const slxFITS_VALUE value,
const vltLOGICAL trimLine,
slxKEYW_LINE fitsLine,
ccsERROR *error, ..., NULL)
The function generates a FITS keyword line from the input
parameters. This is done in accordance with the rules specified in
the "Data Interface Requirements" document (ARC-SPE-ESO-0000-0001/1.4),
and in "NOST Implementation of the Flexible Image Transport System
- FITS, November 6, 1991".
The FITS keyword generated can be either a standard FITS keyword,
i.e. only a parameter, a value and a comment:
"<par> = <value> / <comment>"
or it can be a hierarchical FITS keyword line, i.e. with the format:
"HIERARCH ESO <cat> [<sub>] <par> = <value> / <comment>"
The first two keywords ("HIERARCH ESO") are generated automatically.
All strings passed to the function must be terminated with '\0'.
The function is depending on the availability of a Dictionary loaded
into a MISC Hash Table.
The comment should be given only as the actual text - do not append any
"/" or try to format it in any way.
A comment line, i.e. "COMMENT <comment>" shall be created, the variable
parameter list should contain only the keyword "COMMENT".
The generated FITS line is stored in the buffer pointed to by "fitsLine".
This buffer must have the a length of at least 81 characters (use
slxKEYW_LINE as type).
If the generated FITS line is longer than the maximum FITS line length
(80 characters) the characters beyond the 80th position, are ignored if
the flag "trimLine" is ccsTRUE.
dictionary IN MISC Hash Table containing the Dictionary for the
context. Information such as the type of keyword,
value format, and comment is obtained from the
Dictionary.
value IN Union parameter of type slxFITS_VALUE containing the
value to be written in the FITS line. The members to
set for each of the four types of data are:
value.s - for a string (value.s = "string";)
value.l - for a logical (value.l = ccsTRUE|ccsFALSE;)
value.i - for an integer (value.i = 1234;)
value.d - for a double (value.d = 1234.1234;)
trimLine IN If "trimLine" is ccsFALSE, the FITS line generated will
not be trimmed to 80 character but can have a maximum
length of slxKEYW_LINE_LEN bytes.
fitsLine OUT Pointer to array where the new FITS line will be
written. The line must be at least 80 characters long;
use possibly slxKEYW_LINE as type for the variable.
error OUT Pointer to CCS Error Structure.
... IN The keyword that should be generated. It can either
be given in as one Short-FITS keyword, e.g.:
..., error, "DET.WIN.STARTX", NULL);
or it can be given as the individual sub-key
consituting the keyword to create, e.g.:
..., error, "DET", "WIN", "STARTX", NULL);
#include "slx.h"
ccsERROR error;
miscHASH_TABLE dicHashTable,
slxKEYW_LINE newFitsLine;
slxFITS_VALUE value;
if (slxLoadDicHash(dicHashTable, "ISAAC", &error) == FAILURE)
... error processing ...
value.d = 12.45;
* Create the FITS line
if (slxCreateFits2(dicHashTable, value, ccsTRUE, newFitsLine, "DET",
"WIN1", "DIT", NULL) == FAILURE)
... error processing ...
* The FITS is generated save it, print it ...
printf("New FITS line:\n\n%s\n", newFitsLine);
...
Output ->
New FITS line:
HIERARCH ESO DET WIN1 DIT = 1.245E+1 / Detector integration time
Note, it is also possible to enter the keyword in one piece in the
Short-FITS format, i.e.:
* Create the FITS line
if (slxCreateFits2(dicHashTable, value, ccsTRUE, newFitsLine,
"DET.WIN1.DIT", NULL) == FAILURE)
... error processing ...
#include "slx.h"
ccsCOMPL_STAT slxCreateWriteFits2(const int fd,
const miscHASH_TABLE dictionary,
const slxFITS_VALUE value,
ccsERROR *error, ..., NULL)
The function creates a FITS line by calling the function
"slxCreateFits2()", and appends this in the file specified by the file
descriptor. The function assumes that the file pointer points to the
correct place in the file, and simply writes the new FITS line at this
position.
For further information about the generation of the FITS keywords, see the
man page for "slxCreateFits2()".
fd IN File descriptor for the image data file which is opened and ready
to be written in. File pointer must point to the correct location
in the file.
For an explanation of the rest of the parameters, consult the man page for
the function "slxCreateFits2()".
SUCCESS In case the operation was successful and the FITS line was
written successfully in the file.
FAILURE If something went wrong. The following error codes can be
returned:
slxERR_WRONG_FD The error descriptor is wrong
slxERR_WRITE_FILE_FD An error occurred while writing in a file
referenced by the file descriptor.
The function calls slxCreateFITS() and may return errors
generated by this function.
#include "slx.h"
ccsCOMPL_STAT slxPrepImageFile(const slxFILENAME fileName,
const int noOfBlocks,
const vltLOGICAL writeEND,
ccsERROR *error)
The function creates a file with the given filename, and pads with blanks
to prepare a header. There is padded with blanks corresponding to the
number of FITS blocks specified. After the operation the file is closed
again.
fileName IN Name of the file to be created - must be full path!
noOfBlocks IN Number of FITS blocks to reserve space for in the file.
writeEND IN If this value is ccsTRUE there will be written an END
keyword in the end of the header.
error OUT Indicates a possible error occurring.
 Quadralay Corporation http://www.webworks.com Voice: (512) 719-3399 Fax: (512) 719-3606 sales@webworks.com |
| |
|
|
|