DFS related functions

Macros
#define	CPL_DFS_PRO_CATG   "ESO PRO CATG"
	The name of the Product Category key.
#define	CPL_DFS_PRO_SCIENCE   "ESO PRO SCIENCE"
	The name of the Product Science key.
#define	CPL_DFS_PRO_TECH   "ESO PRO TECH"
	The name of the Product Tech key.
#define	CPL_DFS_PRO_TYPE   "ESO PRO TYPE"
	The name of the Product Type key.

Enumerations
enum	{   CPL_DFS_SIGNATURE_NONE ,   CPL_DFS_SIGNATURE_DATAMD5 ,   CPL_DFS_SIGNATURE_CHECKSUM }
	Pipeline products digital signature flags. More...

Functions
cpl_error_code	cpl_dfs_save_imagelist (cpl_frameset *allframes, cpl_propertylist *header, const cpl_parameterlist *parlist, const cpl_frameset *usedframes, const cpl_frame *inherit, const cpl_imagelist *imagelist, cpl_type type, const char *recipe, const cpl_propertylist *applist, const char *remregexp, const char *pipe_id, const char *filename)
	Save an imagelist as a DFS-compliant pipeline product.
cpl_error_code	cpl_dfs_save_paf (const char *instrume, const char *recipe, const cpl_propertylist *paflist, const char *filename)
	Create a new PAF file.
cpl_error_code	cpl_dfs_save_propertylist (cpl_frameset *allframes, cpl_propertylist *header, const cpl_parameterlist *parlist, const cpl_frameset *usedframes, const cpl_frame *inherit, const char *recipe, const cpl_propertylist *applist, const char *remregexp, const char *pipe_id, const char *filename)
	Save a propertylist as a DFS-compliant pipeline product.
cpl_error_code	cpl_dfs_save_table (cpl_frameset *allframes, cpl_propertylist *header, const cpl_parameterlist *parlist, const cpl_frameset *usedframes, const cpl_frame *inherit, const cpl_table *table, const cpl_propertylist *tablelist, const char *recipe, const cpl_propertylist *applist, const char *remregexp, const char *pipe_id, const char *filename)
	Save a table as a DFS-compliant pipeline product.
cpl_error_code	cpl_dfs_setup_product_header (cpl_propertylist *header, const cpl_frame *product_frame, const cpl_frameset *framelist, const cpl_parameterlist *parlist, const char *recid, const char *pipeline_id, const char *dictionary_id, const cpl_frame *inherit_frame)
	Add product keywords to a pipeline product property list.
cpl_error_code	cpl_dfs_sign_products (const cpl_frameset *set, unsigned int flags)
	Update DFS and DICB required header information of product frames.
cpl_error_code	cpl_dfs_update_product_header (cpl_frameset *self)
	Perform any DFS-compliancy required actions (DATAMD5/PIPEFILE update)

Detailed Description

Macro Definition Documentation

CPL_DFS_PRO_CATG

#define CPL_DFS_PRO_CATG   "ESO PRO CATG"

The name of the Product Category key.

See also

cpl_dfs_save_image()

Note

A pipeline product must contain a string property with this name

CPL_DFS_PRO_SCIENCE

#define CPL_DFS_PRO_SCIENCE   "ESO PRO SCIENCE"

The name of the Product Science key.

See also

cpl_dfs_save_image()

Note

A pipeline product should contain a boolean property with this name

CPL_DFS_PRO_TECH

#define CPL_DFS_PRO_TECH   "ESO PRO TECH"

The name of the Product Tech key.

See also

cpl_dfs_save_image()

Note

A pipeline product should contain a string property with this name

CPL_DFS_PRO_TYPE

#define CPL_DFS_PRO_TYPE   "ESO PRO TYPE"

The name of the Product Type key.

See also

cpl_dfs_save_image()

Note

A pipeline product should contain a string property with this name

Enumeration Type Documentation

anonymous enum

anonymous enum

Pipeline products digital signature flags.

Flags to select the different digital signatures to compute for pipeline product files. The values may be combined using bitwise or.

Enumerator
CPL_DFS_SIGNATURE_NONE	Do not compute any signatures
CPL_DFS_SIGNATURE_DATAMD5	Compute the DATAMD5 data hash
CPL_DFS_SIGNATURE_CHECKSUM	Compute FITS standard CHECKSUM and DATASUM

Function Documentation

cpl_dfs_save_imagelist()

cpl_error_code cpl_dfs_save_imagelist	(	cpl_frameset *	allframes,
		cpl_propertylist *	header,
		const cpl_parameterlist *	parlist,
		const cpl_frameset *	usedframes,
		const cpl_frame *	inherit,
		const cpl_imagelist *	imagelist,
		cpl_type	type,
		const char *	recipe,
		const cpl_propertylist *	applist,
		const char *	remregexp,
		const char *	pipe_id,
		const char *	filename
	)

Save an imagelist as a DFS-compliant pipeline product.

Parameters

allframes	The list of input frames for the recipe
header	NULL, or filled with properties written to product header
parlist	The list of input parameters
usedframes	The list of raw/calibration frames used for this product
inherit	NULL or product frames inherit their header from this frame
imagelist	The imagelist to be saved
type	The type used to represent the data in the file
recipe	The recipe name
applist	Propertylist to append to primary header, w. PRO.CATG
remregexp	Optional regexp of properties not to put in main header
pipe_id	PACKAGE "/" PACKAGE_VERSION
filename	Filename of created product

Note

remregexp may be NULL

Returns

CPL_ERROR_NONE or the relevant CPL error code on error

See also

cpl_dfs_save_image(), cpl_imagelist_save().

References cpl_ensure_code, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

cpl_dfs_save_paf()

cpl_error_code cpl_dfs_save_paf	(	const char *	instrume,
		const char *	recipe,
		const cpl_propertylist *	paflist,
		const char *	filename
	)

Create a new PAF file.

Parameters

instrume	Name of instrument in capitals (NACO, VISIR, etc.)
recipe	Name of recipe
paflist	Propertylist to save
filename	Filename of created PArameter File

Returns

CPL_ERROR_NONE or the relevant CPL error code on error

See also

cpl_dfs_save_image().

The example below shows how to create a PAF from some FITS cards from the file ref_file and QC parameters in a propertylist qclist. Please note that qclist can be used also in calls to cpl_dfs_save_image() and cpl_dfs_save_table(). Error handling is omitted for brevity:

const char pafcopy[] = "^(DATE-OBS|ARCFILE|ESO TPL ID|ESO DET DIT|MJD-OBS)$";
cpl_propertylist * paflist = cpl_propertylist_load_regexp(ref_file, 0,
                                                          pafcopy, 0);
 
cpl_propertylist_append(paflist, qclist);
 
cpl_dfs_save_paf("IIINSTRUMENT", "rrrecipe", paflist, "rrrecipe.paf");
 
cpl_propertylist_delete(paflist);

References cpl_ensure_code, CPL_ERROR_FILE_IO, cpl_error_get_code(), CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

cpl_dfs_save_propertylist()

cpl_error_code cpl_dfs_save_propertylist	(	cpl_frameset *	allframes,
		cpl_propertylist *	header,
		const cpl_parameterlist *	parlist,
		const cpl_frameset *	usedframes,
		const cpl_frame *	inherit,
		const char *	recipe,
		const cpl_propertylist *	applist,
		const char *	remregexp,
		const char *	pipe_id,
		const char *	filename
	)

Save a propertylist as a DFS-compliant pipeline product.

Parameters

allframes	The list of input frames for the recipe
header	NULL, or filled with properties written to product header
parlist	The list of input parameters
usedframes	The list of raw/calibration frames used for this product
inherit	NULL or product frames inherit their header from this frame
recipe	The recipe name
applist	Propertylist to append to primary header, w. PRO.CATG
remregexp	Optional regexp of properties not to put in main header
pipe_id	PACKAGE "/" PACKAGE_VERSION
filename	Filename of created product

Note

remregexp may be NULL

Returns

CPL_ERROR_NONE or the relevant CPL error code on error

See also

cpl_dfs_save_image(), cpl_propertylist_save().

The FITS header of the created product is created from the provided applist and the cards copied by cpl_dfs_setup_product_header(), with exception of the cards whose keys match the provided remregexp.

The FITS data unit will be empty.

References CPL_ERROR_NONE, and CPL_TYPE_INVALID.

cpl_dfs_save_table()

cpl_error_code cpl_dfs_save_table	(	cpl_frameset *	allframes,
		cpl_propertylist *	header,
		const cpl_parameterlist *	parlist,
		const cpl_frameset *	usedframes,
		const cpl_frame *	inherit,
		const cpl_table *	table,
		const cpl_propertylist *	tablelist,
		const char *	recipe,
		const cpl_propertylist *	applist,
		const char *	remregexp,
		const char *	pipe_id,
		const char *	filename
	)

Save a table as a DFS-compliant pipeline product.

Parameters

allframes	The list of input frames for the recipe
header	NULL, or filled with properties written to product header
parlist	The list of input parameters
usedframes	The list of raw/calibration frames used for this product
inherit	NULL or product frames inherit their header from this frame
table	The table to be saved
tablelist	Optional propertylist to use in table extension or NULL
recipe	The recipe name
applist	Propertylist to append to primary header, w. PRO.CATG
remregexp	Optional regexp of properties not to put in main header
pipe_id	PACKAGE "/" PACKAGE_VERSION
filename	Filename of created product

Returns

CPL_ERROR_NONE or the relevant CPL error code on error

See also

cpl_dfs_save_image(), cpl_table_save().

References cpl_ensure_code, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, and CPL_TYPE_INVALID.

cpl_dfs_setup_product_header()

cpl_error_code cpl_dfs_setup_product_header	(	cpl_propertylist *	header,
		const cpl_frame *	product_frame,
		const cpl_frameset *	framelist,
		const cpl_parameterlist *	parlist,
		const char *	recid,
		const char *	pipeline_id,
		const char *	dictionary_id,
		const cpl_frame *	inherit_frame
	)

Add product keywords to a pipeline product property list.

Parameters

header	Property list where keywords must be written
product_frame	Frame describing the product
framelist	List of frames including all input frames
parlist	Recipe parameter list
recid	Recipe name
pipeline_id	Pipeline unique identifier
dictionary_id	PRO dictionary identifier
inherit_frame	Frame from which header information is inherited

Returns

CPL_ERROR_NONE on success.

Errors

CPL_ERROR_NULL_INPUT	An input pointer is NULL.
CPL_ERROR_DATA_NOT_FOUND	The input framelist contains no input frames or a frame in the input framelist does not specify a file. In the former case the string "Empty set-of-frames" is appended to the error message returned by cpl_error_get_message().
CPL_ERROR_ILLEGAL_INPUT	The product frame is not tagged or not grouped as CPL_FRAME_GROUP_PRODUCT. A specified inherit_frame doesn't belong to the input frame list, or it is not in FITS format.
CPL_ERROR_FILE_NOT_FOUND	A frame in the input framelist specifies a non-existing file.
CPL_ERROR_BAD_FILE_FORMAT	A frame in the input framelist specifies an invalid file.

This function checks the header associated to a pipeline product, to ensure that it is DICB compliant. In particular, this function does the following:

1. Selects a reference frame from which the primary and secondary keyword information is inherited. The primary information is contained in the FITS keywords ORIGIN, TELESCOPE, INSTRUME, OBJECT, RA, DEC, EPOCH, EQUINOX, RADECSYS, DATE-OBS, MJD-OBS, UTC, LST, PI-COI, OBSERVER, while the secondary information is contained in all the other keywords. If the inherit_frame is just a NULL pointer, both primary and secondary information is inherited from the first frame in the input framelist with group CPL_FRAME_GROUP_RAW, or if no such frames are present the first frame with group CPL_FRAME_GROUP_CALIB. If inherit_frame is non-NULL, the secondary information is inherited from inherit_frame instead.
2. Copy to header, if they are present, the following primary FITS keywords from the first input frame in the framelist: ORIGIN, TELESCOPE, INSTRUME, OBJECT, RA, DEC, EPOCH, EQUINOX, RADESYS, DATE-OBS, MJD-OBS, UTC, LST, PI-COI, OBSERVER. If those keywords are already present in the header property list, they are overwritten only in case they have the same type. If any of these keywords are present with an unexpected type, a warning is issued, but the keywords are copied anyway (provided that the above conditions are fulfilled), and no error is set.
3. Copy all the HIERARCH.ESO._ keywords from the primary FITS header of the inherit_frame in framelist, with the exception of the HIERARCH.ESO.DPR._, and of the .PRO._ and .DRS._ keywords if the inherit_frame is a calibration. If those keywords are already present in header, they are overwritten.
4. If found, remove the HIERARCH.ESO.DPR._ keywords from header.
5. If found, remove the ARCFILE and ORIGFILE keywords from header.
6. Add to header the following mandatory keywords from the PRO dictionary: PIPEFILE, PRO.DID, PRO.REC1.ID, PRO.REC1.DRS.ID, PRO.REC1.PIPE.ID, and PRO.CATG. If those keywords are already present in header, they are overwritten. The keyword PRO.CATG is always set identical to the tag in product_frame.
7. Only if missing, add to header the following mandatory keywords from the PRO dictionary: PRO.TYPE, PRO.TECH, and PRO.SCIENCE. The keyword PRO.TYPE will be set to "REDUCED". If the keyword DPR.TECH is found in the header of the first frame, PRO.TECH is given its value, alternatively if the keyword PRO.TECH is found it is copied instead, and if all fails the value "UNDEFINED" is set. Finally, if the keyword DPR.CATG is found in the header of the first frame and is set to "SCIENCE", the boolean keyword PRO.SCIENCE will be set to "true", otherwise it will be copied from an existing PRO.SCIENCE keyword, while it will be set to "false" in all other cases.
8. Check the existence of the keyword PRO.DATANCOM in header. If this keyword is missing, one is added, with the value of the total number of raw input frames.
9. Add to header the keywords PRO.REC1.RAW1.NAME, PRO.REC1.RAW1.CATG, PRO.REC1.CAL1.NAME, PRO.REC1.CAL1.CATG, to describe the content of the input set-of-frames.

See the DICB PRO dictionary to have details on the mentioned PRO keywords.

Note

Non-FITS files are handled as files with an empty FITS header.

References cpl_ensure_code, CPL_ERROR_ACCESS_OUT_OF_RANGE, CPL_ERROR_DATA_NOT_FOUND, CPL_ERROR_FILE_NOT_FOUND, cpl_error_get_code(), CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, CPL_ERROR_UNSPECIFIED, cpl_errorstate_get(), cpl_errorstate_set(), cpl_frame_get_filename(), cpl_frame_get_group(), cpl_frame_get_tag(), CPL_FRAME_GROUP_CALIB, CPL_FRAME_GROUP_PRODUCT, CPL_FRAME_GROUP_RAW, cpl_frameset_get_size(), cpl_frameset_iterator_advance(), cpl_frameset_iterator_delete(), cpl_frameset_iterator_get_const(), cpl_frameset_iterator_new(), cpl_frameset_iterator_reset(), cpl_free(), cpl_msg_warning(), cpl_parameter_get_alias(), cpl_parameter_get_bool(), cpl_parameter_get_default_bool(), cpl_parameter_get_default_double(), cpl_parameter_get_default_int(), cpl_parameter_get_default_string(), cpl_parameter_get_double(), cpl_parameter_get_help(), cpl_parameter_get_int(), cpl_parameter_get_string(), cpl_parameter_get_type(), CPL_PARAMETER_MODE_CLI, cpl_parameterlist_get_first_const(), cpl_parameterlist_get_next_const(), cpl_property_delete(), cpl_property_duplicate(), cpl_property_get_bool(), cpl_property_get_size(), cpl_property_get_string(), cpl_property_get_type(), cpl_property_set_bool(), cpl_property_set_comment(), cpl_property_set_int(), cpl_property_set_name(), cpl_propertylist_append(), cpl_propertylist_append_property(), cpl_propertylist_delete(), cpl_propertylist_erase(), cpl_propertylist_get_property_const(), cpl_propertylist_has(), cpl_propertylist_new(), cpl_sprintf(), cpl_strdup(), CPL_TYPE_BOOL, CPL_TYPE_DOUBLE, cpl_type_get_name(), CPL_TYPE_INT, and CPL_TYPE_STRING.

cpl_dfs_sign_products()

cpl_error_code cpl_dfs_sign_products	(	const cpl_frameset *	set,
		unsigned int	flags
	)

Update DFS and DICB required header information of product frames.

Parameters

set	The frameset from which the product frames are taken.
flags	Bit mask for selecting the digital signatures to be written.

Returns

The function returns CPL_ERROR_NONE on success, or an appropriate CPL error code otherwise.

Note

Each product frame must correspond to a FITS file created with a CPL FITS saving function.

The function takes all frames marked as products from the input frameset set. For each product the header information PIPEFILE is updated unconditionally. In addition, depending on the bit mask flags, the DATAMD5 data hash and/or the standard FITS checksums are computed and written to the product header. If a digital signature is not selected by flags when the function is called, its corresponding header keyword(s) are removed from the product frame.

Errors

CPL_ERROR_NULL_INPUT	An input pointer is NULL.
CPL_ERROR_DATA_NOT_FOUND	The input framelist contains a frame of type product with a missing filename.
CPL_ERROR_BAD_FILE_FORMAT	The input framelist contains a frame of type product without a FITS card with key 'DATAMD5'.
CPL_ERROR_FILE_IO	The input framelist contains a frame of type product for which the FITS card with key 'DATAMD5' could not be updated.

References CPL_DFS_SIGNATURE_NONE, cpl_ensure_code, CPL_ERROR_ACCESS_OUT_OF_RANGE, cpl_error_get_code(), CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, cpl_errorstate_get(), cpl_errorstate_set(), cpl_frame_get_group(), CPL_FRAME_GROUP_PRODUCT, cpl_frameset_is_empty(), cpl_frameset_iterator_advance(), cpl_frameset_iterator_delete(), cpl_frameset_iterator_get_const(), and cpl_frameset_iterator_new().

cpl_dfs_update_product_header()

cpl_error_code cpl_dfs_update_product_header

(

cpl_frameset *

self

)

Perform any DFS-compliancy required actions (DATAMD5/PIPEFILE update)

Parameters

self	The list of frames with FITS products created by the recipe

Returns

CPL_ERROR_NONE or the relevant CPL error code on error

Note

Each product frame must correspond to a FITS file created with a CPL FITS saving function.

Errors

CPL_ERROR_NULL_INPUT	An input pointer is NULL.
CPL_ERROR_DATA_NOT_FOUND	The input framelist contains a frame of type product with a missing filename.
CPL_ERROR_BAD_FILE_FORMAT	The input framelist contains a frame of type product without a FITS card with key 'DATAMD5'.
CPL_ERROR_FILE_IO	The input framelist contains a frame of type product for which the FITS card with key 'DATAMD5' could not be updated.

References CPL_ERROR_NONE.