Questions for Metadata Item Struct (Section 5.2.2 SDRS)

[calvin.harman@…]

I'm not entirely clear on the functionality of the "items" member of the
psMetadataItem struct. How is it to be used?

To populate "items", should the metadata item allocator perform a search of the
psMetadata psHash struct?

If a new metadata item with the same name of an existing metadata item is added
to the metadata collection, should there be some type of function to cycle
through all entries to update the metadata "items" member? If so, where should
this be done, in the psMetadataAddItem() and psMetadataAdd() functions?

If one metadata item has the name "HISTORY1" and another has the
name "HISTORY2" would they be considered to have the same name and would
therefore be in the same "items" list?

[eugene]

the idea behind the psMetadataItem.items entry comes from the desire to beable
to carry around all of the entries in a typical FITS image header in the
metadata structure. the problem is that FITS image headers, which are based on
key/value pairs, do not require unique names, and this is particularly true in
the case of COMMENT and HISTORY entries. It is perfectly valid in a FITS header
to have 30 entries which all have the keyword COMMENT or 20 with the keyword
HISTORY all with different values. The idea with the psMetadataItem container
was to have a single psMetadataItem to define the keyword, and a list to hold
the actual values.

For example, suppose you have a FITS header with 5 HISTORY keywords. the
psMetadata would include one psMetadataItem with these values:

item.name = "HISTORY"
item.type = PS_META_ITEM_SET
item.flags = PS_META_NON_UNIQUE
item.data.void = NULL
item.comment = NULL

item.items would point to a psList, each entry of which points to a
psMetadataItem, which would carry the actual values. They would have keys which
are generated from the original key, but made unique by appending an integer;
they would have the actual data values.

Looking at this, two things occur to me:

1) the UNIQUE and NON_UNIQUE seem redundant with the PS_META_ITEM_SET value
2) we need a method to specify the existence of a NON_UNIQUE key before the key
is used.

The idea of the flag values with the value of UNIQUE or NON_UNIQUE was to force
psMetadataItemAdd to give an error if it tries to add a keyword which already
exists. But, this functionality could just as easily be carried by the type
entry. If the type has a value PS_META_ITEM_SET, then this means the data item
is not required to be unique, and psMetadataItemAdd should not give an error.
The only thing lacking is a was for a psMetadataItem to be converted from a
single entry to a PS_META_ITEM_SET. (It should be valid to have a
PS_META_ITEM_SET with only one, or even 0, entries. the list need not point to
anything).

In this case, I propose the following:

1) let's change the structure to read:
typedef struct {

const int id; /< unique ID for this item
char *restrict name; /< Name of item
psMetadataType type; /< type of this item
const union {

psS32 S32; /< integer value
psF32 F32; /< floating value
psF64 F64; /< double value
void *void; /< other type

} data; /< value of metadata
char *comment; /< optional comment ("", not NULL)
psList *restrict items; /< list of psMetadataItems with the

} psMetadataItem;

let's change the psMetadataItemAlloc to have the following arguments:

psMetadataItemAlloc (const char *name, int type, const char *comment, ...);

if the type is PS_META_ITEM_SET, then the value in the ellipsis may be NULL, in
which case a psMetadataItem is created with the given name, but no entries are
added to the items list. Additional items allocated later with the same name
will result in entries added to the list.

we may also need a function to convert one to another, but this would be a
convenience since it could be done with a psMetadataItemRemove followed by the
psMetadataItemAlloc above and a second one to insert the item.

[eugene]

the discussed changes have been added to the SDRS (not in v.05).