| |
|
|
|
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 TRUE, 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
TRUE, otherwise FALSE.
tableFileName IN The name of the Alias Conversion Table to load. If
"loadTable" is FALSE, 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 slxCreateShortFITS(const char *category,
const char *subSystem,
const char *parameter,
const slxPAR_TYPE parameterType,
const char *stringValue,
const vltLOGICAL logicalValue,
const long int integerValue,
const vltUINT8 precision,
const vltLOGICAL exponential,
const vltDOUBLE doubleValue,
const char *comment,
char *fitsLine,
ccsERROR *error)
NOTE: A new function slxCreateShortFits2() is now supported providing a
more convenient interface, and providing two sub-system keywords.
This new function should be used.
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.
If a non-hierarchical Short-FITS keyword should be generated, slxSTD_FITS,
should used as input for the category. If there is no subsystem,
slxNULL_STR, should be the input value for this parameter.
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 the generated Short-FITS line is longer than the maximum
FITS line length (80 characters) the characters beyond the 80th position,
are not taken into account.
category IN Pointer to string buffer containing the category of the
Short-FITS keyword, e.g. "INS", "DET", ... . If it is a
non-hierarchical FITS keyword (only the parameter),
this string should be slxSTD_FITS.
subSystem IN Pointer to string buffer containing the subsystem.
If this is not used, slxNULL_STR, must be the input
parameter.
parameter IN Pointer to string buffer containing the name of the
parameter. This input parameter is mandatory.
parameterType IN The type of the parameter. Can be either slxSTRING,
slxLOGICAL, slxINTEGER or slxDOUBLE.
stringValue IN Pointer to buffer containing the possible string value.
If not used, i.e. "parameterType" is not a string, this
parameter is ignored (can be slxNULL_STR).
logicalValue IN Can be either TRUE or FALSE. If not used, the
parameter is ignored.
integerValue IN Contains an integer value. If "parameterType" is not
integer, this is ignored.
precision IN Used when the input value is of type double. Indicates
the number of decimals after the point. If the value is
not a double, this parameter is ignored.
exponential IN Indicates for a double type parameter if it should be
be written as an exponential number or a plain number.
Can be either TRUE for exponential or FALSE. If
the value is not a double, this parameter is ignored.
doubleValue IN Contains the value when parameter type is double. If the
type is not double, this parameter is ignored.
comment IN Used to give in the comment; should be plain text
terminated with "\x0".
fitsLine OUT The buffer in which the generated Short-FITS line will
be stored. Must be allocated by the calling application.
Use the contant slxMAX_FITS_LI_LEN to allocate the
buffer.
SUCCESS If the operation was successful.
FAILURE If the operation failed. The function only fails if the
parameter type is unknown, otherwise it will always try to
generate a Short-FITS line.
The function make calls to slxCreateFITS() and
slxNormalToShortFITS() and may return errors generated by these.
Beware that all string buffers must be allocated by the calling process,
and terminated by a null character ('\0').
#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)
ccsCOMPL_STAT slxGetXBytesBuf(slxDYN_BUF *dynBuf,
slxDYN_BUF_OP initialize,
vltINT32 reqLen,
char *buffer,
vltINT32 *bufLen,
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".
slxGetXBytesBuf()
Get the next X bytes from an SLX Dynamic Buffer.
#include "slx.h"
ccsCOMPL_STAT slxGetKeyword(const char *setupFilename,
const char *keyword,
const vltUINT16 keywordNumber,
slxKEYW_INFO *keywordInfo,
ccsERROR *error)
The function searches for a keyword in the given set-up file.
The keyword can be identified by its name or its serial number.
If the keyword is found, the information about this keyword
is returned in the slxKEYW_INFO structure.
When the name of the keyword i.e. the argument 'keyword' is given as
a non-zero-length string, the function search for the kewyord with
the given name. In this case the parameter 'keywordNumber' is ignored.
When the name of the keyword i.e. the argument 'keyword' is given as
zero-length string, the function will search for the keyword with the
given serial number as indicated by argument 'keywordNumber'.
Arguments of the function:
setupFilename IN The name of the set-up file where the
keyword will be searched.
keyword IN The name of the keyword. Must be in the Short-FITS
format. If given as a zero-length string, the
search is carried out 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. This argument is ignored when 'keyword'
is not a zero-length string.
keywordInfo OUT Structure that contains the various information about
the keyword.
This structure contains the following members:
vltUINT8 found - Indicates if the keyword was
found.
vltUINT16 number - Line number in set-up file
char keyword[200] - 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[200] - The value as a string. A string
value keeps the quotes.
char comment[200] - The possible comment of the
keyword line.
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.
The errors of the function slxLocateSetupFile() are
returned when file with 'setupFilename' is not found.
example-1: search according to the name of a keyword
^^^^^^^^^
slxKEYW_INFO keywordInfo;
char * filename="$INS_ROOT/SYSTEM/COMMON/SETUPFILES/DET/ccd.det";
if (slxGetKeyword(filename,"DET2.FRAM.FITSMTD",
0,&keywordInfo, stack)!=SUCCESS) {error handling}
printf("found=%d\n",keywordInfo.found);
printf("line number=%d\n",keywordInfo.number);
printf("complte kw=%s\n",keywordInfo.keyword);
printf("value =%s\n",keywordInfo.value);
printf("comment=%s\n",keywordInfo.comment);
example-2: search according to serial number
^^^^^^^^^
if (slxGetKeyword( filename,"\0", 7,&keywordInfo,
stack)!=SUCCESS) {error handling}
#include "slx.h"
ccsCOMPL_STAT slxGetKeywordBuf(slxDYN_BUF *setupHandle,
const char *keyword,
const vltUINT16 keywordNumber,
slxKEYW_INFO *keywordInfo,
ccsERROR *error)
The function searches for a keyword in the specified Dynamic Buffer.
The keyword can be identified by its name or its serial number.
If the keyword is found, the information about this keyword
is returned in the slxKEYW_INFO structure.
When the name of the keyword- i.e. the argument 'keyword'- is given as
a non-zero-length string, the function search for the kewyord with
the given name. In this case the parameter 'keywordNumber' is ignored.
When the name of the keyword - i.e. the argument 'keyword'- is given as
zero-length string, the function will search for the keyword with the
given serial number as indicated by argument 'keywordNumber'.
Arguments of the function:
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 as a zero-length string, the
search is carried out 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.
This structure contains the following members:
vltUINT8 found - Indicates if the keyword was
found.
vltUINT16 number - Line number in set-up file;
char keyword[200] - 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[200] - The value as a string. A string
value keeps the quotes.
char comment[200] - The possible comment of the
keyword line.
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 When something goes wrong during the operation, the
following error codes may 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.
The internal calls of functions slxGetNextLineBuf(),
slxSplitShortFITS() may generate error, in which case
these errors are returned.
The usage if slxGetKeywordBuf() is similar to slxGetKeyword().
See examples of the function slxGetKeyword in its manual.
#include "slx.h"
ccsCOMPL_STAT slxGetNextFieldMulti(const char *separators,
const char *bufPtr,
char **nextField,
char **newPos,
ccsERROR *error)
ccsCOMPL_STAT slxGetNextField(const char *bufPtr,
const vltUINT16 maxLen,
char *nextField,
char **newPos,
ccsERROR *error)
ccsCOMPL_STAT slxGetNextField2(const char separator,
const char *bufPtr,
const vltUINT16 maxLen,
char *nextField,
char **newPos,
ccsERROR *error)
The functions return 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,
e.g.: ' ', '\t', '\n', '='.
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.
E.g.:
"first_string second_string"
^
|--- bufPtr
The 'nextField' will be: "first_string" and 'newPos' will point to
the first letter of "second_string". If you call the function again
the 'nextField' will be "second_string".
Should the user manually modify the BufPtr to point in the middle of
the string, like
"first_string second_string"
^
|--- bufPtr
The "nextField" will be: "st_string\0".
If there is no Next Field, the "nextField" will be initiated
with a '\0'.
If a separator appear within a string it is not taken into account.
E.g.: string = "aaa bbb \"ccc ddd\" eee"
"ccc ddd" is considered as Next Field even though it includes the SPACE
separator.
Description of the various versions of the function:
slxGetNextFieldMulti():
Makes it possible for the user to specify and number of separators
like e.g.: " \t.", whereby separators are considers as SPACE,
TAB and period.
It allocates memory internally for storing the Next Field. I.e., the
memory should be copied before calling the function again. The
Next Field will always be NULL terminated.
slxGetNextField():
Separators are: ' ', '\t', '\n', '='.
The Next Field is copied into a buffer allocated by the user.
The length of the buffer (i.e. argument maxLen) must be given to
enable the function to check for buffer overflow.
When the length of the next element is greater then maxLen, the function
returns error. In this case 'nextField' will not be updated at all.
slxGetNextField2():of the various versions of the function:
Separator: One separator can be specified by the user.
The Next Field is copied into a buffer allocated by the user. The length
of the buffer must be given to enable the function to check for buffer
overflow.
Since slxGetNextFieldMulti() returns a pointer to internally allocated
memory, subsequent calls overwrite the previous 'Next Field'. I.e.,
make a local copy of the Next Field if this should be preserved.
Get the elements of the following string one by one.
Move the bufPtr into a middle of the string to see the effect.
char * bufPtr="ABCDEFG bbb\tabcdefg\nddd";
char** newpos=&bufPtr;
char nextField[10]="";
int maxLen=10;
if(slxGetNextField(bufPtr,maxLen,nextField,newpos,error)!=SUCCESS){}
printf("1 nextfield='%s'\n",nextField);
if(slxGetNextField(bufPtr,maxLen,nextField,newpos,error)!=SUCCESS){}
printf("2 nextfield='%s'\n",nextField);
bufPtr=bufPtr+3; // modify the buffer manually
if(slxGetNextField(bufPtr,maxLen,nextField,newpos,error)!=SUCCESS){}
printf("3 nextfield='%s'\n",nextField);
if(slxGetNextField(bufPtr,maxLen,nextField,newpos,error)!=SUCCESS){}
printf("4 nextfield='%s'\n",nextField);
results in:
1 nextfield='ABCDEFG'
2 nextfield='bbb'
3 nextfield='defg'
4 nextfield='ddd'
#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 TRUE; 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)
csCOMPL_STAT slxLoadFitsHeaderBuf(slxFILENAME fileName,
slxDYN_BUF *headerBuf,
vltLOGICAL *asciiFile,
ccsERROR *error)
slxLoadFile():
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.
Therefore it is important that that the filname is given
as type slxFILENAME (!)
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.
slxLoadFitsHeaderBuf():
Used to load a FITS File or a PAF file into an SLX Dynamic Buffer.
The flag asciiFile will indicate if the file was in ASCII format or in
the binary FITS formar (~ no newlines).
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,
slxGetDicRevision, slxGetDicVersion - 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 char *dictionary,
slxDIC_HANDLE *dicList,
ccsERROR *error)
ccsCOMPL_STAT slxLookUpKeywordHashX(const miscHASH_TABLE dicHashTable,
const slxKEYW_LINE keyword,
slxDIC_HANDLE **dicInfo,
ccsERROR *error)
ccsCOMPL_STAT slxGetDicRevision(const slxDICTIONARY dictionary,
const vltINT32 entryNo,
slxDIC_RECORD_ENTRY revision,
ccsERROR *error)
ccsCOMPL_STAT slxGetDicVersion(const slxDICTIONARY dictionary,
slxDIC_RECORD_ENTRY version,
ccsERROR *error)
ccsCOMPL_STAT slxConvMethNo2Id(const slxUNIT_CONVERSIONS number,
slxKEYW_LINE id,
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.
The name of the Dictionary/ies to load must follow the rules:
o dictionary = "ALL|all|All":
All Dictionaries found in the "$INS_ROOT/SYSTEM/Dictionaries" are loaded
and merged together. Only names of the structure
"<dictionary ID>-DIC.<name>" are taken.
o dictionary = "EMMI_OS":
The Dictionary is loaded as
"$INS_ROOT/SYSTEM/Dictionary/ESO-VLT-DIC.EMMI_OS".
o dictionary = "<path>/ALL":
E.g. "~/vlt/myDictionaries/all". All Dictionaries found in the
"<path>" directory are loaded.
o dictionary = "ESO-NTT-DIC.SOFI_DCS":
The Dictionary will be loaded as
"$INS_ROOT/SYSTEM/Dictionary/ESO-NTT-DIC.SOFI_DCS".
o dictionary = "<path>/ESO-VLT-DIC.ISAAC_ICS":
The Dictionary is loaded as "<path>/ESO-VLT-DIC.ISAAC_ICS".
It is possibly to specify to load several Dictionries in one go by
given a list of Dictionaries as Dictionary, each element separated by
"|":
"<name1>|<name2>|<name3>"
The names in the list must follow the naming convention given above.
If a Dictionary was not found in the "$INS_ROOT/SYSTEM/Dictionary"
it will also be tried in "$INTROOT/config" or "$VLTROOT/config".
A basic Dictionary "ESO-VLT-DIC.PAF" must be available in the
"$INS_ROOT/SYSTEM/Dictionary", "$INTROOT/include" or "$VLTROOT/include"
directories, or directory given with the Dictionary to load.
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.
The function slxGetDicRevision() returns the requested "Revision:" entry
from the Dictionary Header. If 0 (zero) is given, the last "Revision:"
entry found in the Dictionary Header is returned in the "revision"
parameter. The first "Revision:" entry has number 1.
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 TRUE 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 TRUE.
gotRecord OUT Indicates for calling function if a record was found.
I.e. when there are no more records to return this flag
becomes FALSE.
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 slxSearchTemplateFile(const slxFILENAME baseName,
const slxTEMPLATE_FILES fileType,
vltINT32 *numberFound,
slxSTRING_LIST *fileList,
const vltLOGICAL globalSearch,
const vltLOGICAL stopFirstOccur,
const vltLOGICAL skipInsUserDir,
const char *pathEnvVar,
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
TRUE.
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 TRUE, 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, TRUE
must be the value, otherwise FALSE.
tableFileName IN Filename of Alias Conversion Table to be loaded. If
"loadTable" is FALSE, 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 slxShortToNormalFITS(const slxKEYW_LINE shortFITS,
slxKEYW_LINE normalFITS,
ccsERROR *error)
NOTE: A new function slxShortToNormalFits2() is now supported providing
a more convenient interface, and providing two sub-system keywords.
This new function should be used.
The function converts a set-up keyword from the Short-FITS format to the
normal FITS format.
shortFITS IN Pointer to buffer containing the keyword string
in the Short-FITS format.
normalFITS IN Pointer to buffer in which the keyword string in
normal FITS will be written.
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.
slxERR_FORMAT_KEYWORD The format of the keyword (line) is
wrong.
slxERR_CREATE_FITS An error occurred while creating FITS
keyword - input parameters somehow wrong.
The function makes calls to slxSplitShortFITS() and
slxCreateFITS() and may return errors generated by these.
slxSetupToNormalFITS, slxConvertToNormal(), slxNormalToShortFITS(),
slxConvertToShort(), slxDetectFormat()
#include "slx.h"
ccsCOMPL_STAT slxSplitFitsDyn(const slxKEYW_LINE fitsLine,
const vltINT32 maxNoOfKeyEls,
slxKEYW_LINE keyElements[],
vltINT32 *noOfKeyElements,
slxVALUE value,
slxCOMMENT comment,
ccsERROR *error)
ccsCOMPL_STAT slxSplitFits2(const slxKEYW_LINE fitsLine,
slxCATEGORY category,
slxSUBSYSTEM subSystem1,
slxSUBSYSTEM subSystem2,
slxPARAMETER parameter,
slxVALUE value,
slxCOMMENT comment,
ccsERROR *error)
The functions split 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.
For slxSplitFitsDyn():
maxNoOfKeyEls IN Maximum number of key elements that can be stored in
"keyElements" array.
keyElements OUT String array in which the keyword components will be
stored. This array could typically be allocated as
follows:
slxKEYW_LINE keyArray[10];
whereby "maxNoOfKeyEls = 10".
noOfKeyElements OUT Number of keyword components encountered.
For slxSplitFits2():
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.
For both:
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
comment.
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 slxSplitShortFitsDyn(const slxKEYW_LINE shortFitsLine,
const vltINT32 maxNoOfKeyEls,
slxKEYW_LINE keyElements[],
vltINT32 *noOfKeyElements,
slxVALUE value,
slxCOMMENT comment,
ccsERROR *error)
ccsCOMPL_STAT slxAssShortFitsKey(const slxKEYW_LINE keyElements[],
const vltINT32 noOfKeyElements,
slxKEYW_LINE keyword,
ccsERROR *error)
ccsCOMPL_STAT slxSplitShortFits2(const slxKEYW_LINE shortFitsLine,
slxCATEGORY category,
slxSUBSYSTEM subSystem1,
slxSUBSYSTEM subSystem2,
slxPARAMETER parameter,
slxVALUE value,
slxCOMMENT comment,
ccsERROR *error)
The functions 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'.
shortfitsLine IN Pointer to buffer containing the Short FITS line.
For slxSplitShortFitsDyn():
maxNoOfKeyEls IN Maximum number of key elements that can be stored in
"keyElements" array.
keyElements OUT String array in which the keyword components will be
stored. This array could typically be allocated as
follows:
slxKEYW_LINE keyArray[10];
whereby "maxNoOfKeyEls = 10".
noOfKeyElements OUT Number of keyword components encountered.
For slxSplitShortFits2():
category OUT Pointer to buffer which will contain the possible
category.
subSystem1/2 OUT Pointer to buffer which will contain the possible
subsystem.
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.
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, slxGetFileName, slxGetExtension,
slxGenDayTim, slxGenDayTim2, slxGenDayTimPrec, slxGenDayTimCcsTime,
slxGenDayTimBasic, slxGetUTDate, slxGetUTTime, slxGenUTC,
slxSkipLine, slxStrToUpper, slxStripQuotes, slxStrDup,
slxBuildInsFileName, slxBuildInsUserDir, slxAssembleKeyword,
slxAssKey, slxIsShortFITS, slxGetLastChar, slxSetLastChar,
slxKeywClass2No, slxGetValueEnvVar, slxBitPix2NoBytes, slxGetKeywordIndex,
slxReplaceIndex, slxResolvePath, slxStr2Logical,
slxCheckExtension, slxCheckExtension2,
slxYankExtension, slxYankExtensionGen, slxYankExtensionGenLast, slxYankLastPath,
slxYankTrailNewLines, slxSplitFileName, slxDetermineType, slxTrimString,
slxSplit - various small (usefull) utilities
#include "slx.h"
ccsCOMPL_STAT slxGetPath(const slxFILENAME fileName,
slxFILENAME path,
ccsERROR *error)
ccsCOMPL_STAT slxGetFileName(const slxFILENAME completeName,
slxFILENAME fileName,
ccsERROR *error)
char *slxGetExtension(const slxFILENAME fileName)
Returns the extention of the given file name, i.e. the characters
after the last dot in the filename.
Note :NULL is returned when there is no dot in the filename or the last dot
is the first character of the filename,e.g.:
"/home/ins1b/jknudstr/.fhtHome"
"/home/ins1b/jknudstr/.fhtHome/DICTIONARY/ALL"
void slxYankExtension(slxFILENAME fileName, const slxFILENAME extension)
Cats down the given extention from the filename.
It is not recommended to include path in the 'fileName'.
Note that when filename does not end with the given extention the function
has no effect.
The extention can be given with or without the dots, e.g.: "fits", or ".fits".
Warning: The method looks for the FIRST occurance of the 'extention' in the 'filename'!
Therefore if the given filename is :'file.fitsname.fits' and the extention
is 'fits' the resulting filename is :'file'.
void slxYankExtensionGen(slxFILENAME fileName)
Removes the extention from the 'fileName'.
It is not recommended to include path in the 'fileName'.
Warning:It is not recommended to use this function.
The method searches for the FIRST dot in the filename, and cats
down the remaining characters including the first dot.
void slxYankExtensionGenLast(slxFILENAME fileName)
It is a more robust version of slxYankExtensionGen catting down the extention of
the given 'fileName' if it has any extention.
void slxGenDayTim(slxKEYW_LINE dayTime)
void slxGenDayTim2(const time_t timeSecs,
slxKEYW_LINE dayTime)
ccsCOMPL_STAT slxGenDayTimPrec(const vltINT32 precision,
slxKEYW_LINE dayTime,
ccsERROR *error)
void slxGenDayTimCcsTime(const ccsTIMEVAL *time,
const vltINT32 precision,
slxKEYW_LINE dayTime)
void slxGenDayTimBasic(const unsigned long tv_sec,
const long tv_usec,
const vltINT32 precision,
slxKEYW_LINE dayTime)
void slxGetUTDate(slxUT_DATE utDate)
void slxGetUTTime(vltUINT32 *utTime)
void slxGenUTC(const unsigned long tv_sec,
const long tv_usec,
const vltINT32 precision,
slxKEYW_LINE utcTime)
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 slxBuildImageFileName(const slxFILENAME fileName,
slxFILENAME completeName,
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)
void slxYankLastPath(slxFILENAME path)
ccsCOMPL_STAT slxSplitFileName(const slxFILENAME completeName,
slxFILENAME path,
slxFILENAME fileName,
slxFILENAME extension,
ccsERROR *error)
void slxDetermineType(const char *value,
slxPAR_TYPE *type)
void slxTrimString(char *string, char *trimChars)
ccsCOMPL_STAT slxSplit(const char *separators,
const char *stringPtr,
const vltINT32 maxNoOfSubStr,
slxKEYW_LINE subStrings[],
vltINT32 *noOfSubStr,
ccsERROR *error)
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()
slxGenDayTimPrec() (only available when CCS is available)
slxGenDayTimCcsTime() (only available when CCS is available)
slxGenDayTimBasic()
Generate the string for the DAYTIM keyword as (example):
DAYTIM "1996-10-15T16:21:23"
slxGetUTDate()
The function generates the present UT date as a string in the format:
'YYYY-MM-DDThh:mm:ss.sss'
This format is used e.g. in the FITS header of image data files, and in
the 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.
slxGenUTC()
Convert seconds and microseconds given in to the format:
"HH:MM:SS.SSS"
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)
char *slxAssKey2(const char *key1, ..., NULL)
Assembles a number of sub-keywords to a Short-FITS style one. An arbitrary
number of keywords can be given in.
For slxAssKey() a keyword must always be followed by an index. If this is
zero no index is appended to the keyword. For slxAssKey2() it is not
necessary to give in an index.
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.
Note that function can resolve pathes that starts with or includes
patterns: ./ or ../
Warning :no space is allowed in the input path name!
ccsCOMPL_STAT slxSplitFileName()
The function splits up a filename in its three basic parts:
path (if given), filename and extension (if given). Note that for the
the latter the extension is considered as the string after the last
period found in the filename without the path.
The filename can be given as e.g. "/diskb/user/vlt/myDir/myFile.ext",
"$HOME/vlt/myDir/myFile.ext", "~/vlt/myDir/myFile.ext", "myFile.ext" or
"myFile". If the path or extension are not available, these parameters
will be string of length 0.
void slxDetermineType(const char *value,
slxPAR_TYPE *type)
The function tries to determine the type of a string given in.
The "type" parameter will be set to either slxINTEGER, slxDOUBLE or
slxSTRING in case of a string or a logical value.
void slxTrimString(char *string, char *trimChars)
Trim a string for leading and trailing charecters according to the
characters given in the "trimChars" string. The Trim Chars could be e.g.
"{} ". In this case the string would be trimmed for all leading "{"'s,
"}"'s and spaces.
ccsCOMPL_STAT slxSplit(const char *separators,
const char *stringPtr,
const vltINT32 maxNoOfSubStr,
slxKEYW_LINE subStrings[],
vltINT32 *noOfSubStr,
ccsERROR *error)
Splits a string into its basic components using the characters given in
"separators" as criteria for the splitting. The separators could e.g. be
" ,", whereby the string is split according to spaces and commas.
The user must provide the array of slxKEYW_LINE buffers in which the
sub-strings will be written.
void slxYankLastPath(slxFILENAME path)
Remove the last path or filename in the path given.
3.3 IMAGE FITS HEADER MANIPULATION SUBROUTINES
#include "slx.h"
ccsCOMPL_STAT slxAddFITSBlocks(const int fd,
const vltUINT8 noOfBlocks,
const vltLOGICAL writeEND,
ccsERROR *error)
ccsCOMPL_STAT slxAddFITSBlocksWithEnd(const int fd,
const vltUINT8 noOfBlocks,
ccsERROR *error);
The functions are 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.
The function slxAddFITSBlocksWithEnd always writes the END keyword at the
end of the block. If the header already ends with an END keyword this is
removed before the new block is added.
For this function the file must be opened with read and write (O_RDWR) access.
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 TRUE 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 slxCreateFITS(const char *category,
const char *subSystem,
const char *parameter,
const slxPAR_TYPE *parameterType,
const char *stringValue,
const vltLOGICAL logicalValue,
const vltINT32 integerValue,
const vltUINT8 precision,
const vltLOGICAL exponential,
const vltDOUBLE doubleValue,
const char *comment,
char *fitsLine,
ccsERROR *error)
NOTE: A new function slxCreateFits2() is now supported providing a more
convenient interface, and providing two sub-system keywords.
This new function should be used.
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'.
If a standard FITS keyword should be generated, slxSTD_FITS, should used
as input for the category. If there is no subsystem, slxNULL_STR, should
be the input value for this parameter.
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 input
parameters "category", "subSystem" and "parameter" should be slxSTD_FITS,
slxNULL_STR and slxNULL_STR, and the comment given in in the "comment"
parameter.
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.
If the generated FITS line is longer than the maximum FITS line length
(80 characters) the characters beyond the 80th position, are not taken
into account.
category IN Pointer to string buffer containing the category of the
FITS keyword, e.g. "INS", "DET", ... . If it is a
standard FITS keyword (only the parameter), this string
should be, slxSTD_FITS. A category can maximum be
3 characters long.
subSystem IN Pointer to string buffer containing the subsystem.
If this is not used, slxNULL_STR must be the input
parameter.
parameter IN Pointer to string buffer containing the name of the
parameter. This input parameter is mandatory.
parameterType IN The type of the parameter. Can be either slxSTRING,
slxLOGICAL, slxINTEGER or slxDOUBLE.
stringValue IN Pointer to buffer containing the possible string value.
If not used, i.e. "parameterType" is not a string, this
parameter is ignored (can be slxNULL_STR).
logicalValue IN Can be either TRUE or FALSE. If not used, the
parameter is ignored.
integerValue IN Contains an integer value. If "parameterType" is not
integer, this is ignored.
precision IN Used when the input value is of type double. Indicates
the number of decimals after the point. If the value is
not a double, this parameter is ignored.
exponential IN Indicates for a double type parameter if it should be
be written as an exponential number or a plain number.
Can be either TRUE for exponential or FALSE. If
the value is not a double, this parameter is ignored.
doubleValue IN Contains the value when parameter type is double. If the
type is not double, this parameter is ignored.
comment IN Used to give in the comment; should be plain text
terminated with "\0".
fitsLine OUT The buffer in which the generated FITS will be stored.
Must be allocated by the calling application. The
function will fill exactly 80 characters into this
buffer. THE LENGTH OF THE BUFFER HOWEVER, MUST BE AT
LEAST 81!! If the actual FITS line contents is less than
that, there is zeropadded with blanks to obtain 80
characters. If the generated FITS line is longer, the
line is truncated. There will be written a '\0'
character in the 81th column.
error OUT Indicates the type of a possible error occurring.
SUCCESS If the operation was successful.
FAILURE If the operation failed. The function only fails if the
parameter type is unknown, otherwise it will always try to
generate a FITS line. The following error code can be
returned:
slxERR_CREATE_FITS An error occurred while creating FITS
keyword - input parameters somehow
wrong.
slxERR_INTEGER_TOO_LRG
slxERR_DOUBLE_TOO_LRG The value entered is larger than allowed
(string value too long).
Beware that all string buffers must be allocated by the calling process,
and terminated by a null character ('\0').
Quotes in strings and complex floating point values are not supported in
this version.
#include "slx.h"
ccsERROR error;
char *stringVal = "";
vltLOGICAL logicalVal;
long int integerVal;
vltUINT8 prec;
vltLOGICAL expo;
double doubleVal;
char newFitsLine[slxMAX_FITS_LI_LEN];
char com[slxSTD_FITS_COM_MAX_LEN];
(Get the parameters (would probably read them from OLDB))
(This is a double value)
parType = slxDOUBLE;
prec = 4;
expo = TRUE;
doubleVal = 12.45;
strcpy(comment, "Detector integration time");
(Create the FITS line)
if (slxCreateFITS("DET",
"WIN1",
"DIT",
parType,
stringVal,
logicalVal,
integerVal,
prec,
expo,
doubleVal,
com,
newFitsLine,
&error) == FAILURE)
{
... error processing ..
}
(The FITS is generated save it, print it ...)
printf("New FITS line: %s\n", newFitsLine);
...
Output ->
HIERARCH ESO DET WIN1 DIT = 1.245E+1 / Detector integration time
#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 TRUE 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 |
| |
|
|
|