Difference between revisions of "Filling Out the Packed Data Fields Sub-Structure"
m |
(Update for IM 1.14.0.0) |
||
Line 1: | Line 1: | ||
The '''''<Packed_Data_Fields>''''' class is used to define multiple sub-fields within a single ''<Field_Binary>'' value. These values do not have to observe byte boundaries, and so are defined in terms of bits. | The '''''<Packed_Data_Fields>''''' class is used to define multiple sub-fields within a single ''<Field_Binary>'' value. These values do not have to observe byte boundaries, and so are defined in terms of bits. | ||
− | {| class="wikitable" style="background-color: | + | {| class="wikitable" style="background-color: Yellow" |
− | | '''''Note:''''' '' | + | | '''''Note:''''' Packed Data ''is prohibited in observational archive files. Consequently, SBN data preparers should not be using the ''<Packed_Data_Fields>'' structure for any observational data products, and probably not anywhere else, either. Any packed data should be extracted into standard data types before archiving. If you think you have a data set that should be an exception to this rule, contact your SBN consultant.'' |
− | |||
− | |||
|} | |} | ||
− | |||
For additional explanation, see the PDS4 ''Standards Reference'', or contact your PDS node consultant. | For additional explanation, see the PDS4 ''Standards Reference'', or contact your PDS node consultant. | ||
Line 42: | Line 39: | ||
''OPTIONAL'' | ''OPTIONAL'' | ||
− | {| class="wikitable" style="background-color: | + | {| class="wikitable" style="background-color: yellow" |
− | | ''The definition for this attribute is not sufficiently specific for it to be used reliably. It is not clear, for example, whether the ''field_numbers'' within a ''Packed_Data_Field'' always start at one, or continue numbering started at a higher level | + | | ''The definition for this attribute is not sufficiently specific for it to be used reliably. It is not clear, for example, whether the ''field_numbers'' within a ''Packed_Data_Field'' always start at one, or continue numbering started at a higher level.'' |
|} | |} | ||
− | + | === <start_bit_location> === | |
− | === < | ||
− | |||
''REQUIRED'' | ''REQUIRED'' | ||
− | The first bit comprising the value in the bit field. Numbering begins at 1. | + | The first bit comprising the value in the bit field, relative to the start of the string of bytes containing the field. Numbering begins at 1. |
− | + | Note that the sequence of bytes containing packed data must be read in physical sequence from the file (i.e., as if they were characters). Then bit 1 is the most significant bit in the sequentially first byte in the field, and the bits are numbered sequentially across byte boundaries for the length of the field. | |
− | |||
− | |||
− | === < | + | === <stop_bit_location> === |
''REQUIRED'' | ''REQUIRED'' | ||
− | The last bit comprising the value in the bit field. | + | The last bit comprising the value in the bit field, also relative to the start of the string of bytes containing the field. Numbering begins at 1. |
=== <data_type> === | === <data_type> === | ||
Line 68: | Line 61: | ||
''REQUIRED'' | ''REQUIRED'' | ||
− | This must be one of two standard values: '''SignedBitString''' or '''UnsignedBitString'''. | + | This must be one of two standard values: '''SignedBitString''' or '''UnsignedBitString'''. These data types are described in section 5C.4 of the ''Standards Reference''. What it boils down to is this: |
− | + | :* '''UnsignedBitString''' values should be interpreted as unsigned integers, and so should be zero-extended on the left as they are transferred into standard integer fields. | |
− | + | :* '''SignedBitString''' values are two's complement integers, and should be sign-extended into standard integer fields. | |
− | |||
− | |||
− | |||
− | |||
=== <field_format> === | === <field_format> === | ||
''OPTIONAL'' | ''OPTIONAL'' | ||
− | + | ||
− | + | The only rational formats to have here would be for integers, although possibly for a non-decimal integer (hex codes, for example). This, however, is not validated. | |
− | |||
=== <unit> === | === <unit> === | ||
+ | |||
''OPTIONAL'' | ''OPTIONAL'' | ||
+ | |||
If there is a unit of measurement associated with the extracted value, here's where it goes. | If there is a unit of measurement associated with the extracted value, here's where it goes. | ||
+ | |||
=== <scaling_factor> === | === <scaling_factor> === | ||
+ | |||
''OPTIONAL'' | ''OPTIONAL'' | ||
+ | |||
If the original value was scaled to fit into the bit field, this attribute is the place to put the scaling factor to be applied when parsing the data into program memory. The value extracted from the packed data field is multiplied by this value before any ''value_offset'' is applied. | If the original value was scaled to fit into the bit field, this attribute is the place to put the scaling factor to be applied when parsing the data into program memory. The value extracted from the packed data field is multiplied by this value before any ''value_offset'' is applied. | ||
+ | |||
=== <value_offset> === | === <value_offset> === | ||
+ | |||
''OPTIONAL'' | ''OPTIONAL'' | ||
+ | |||
If a value was applied to the original value to fit it into the bit field, this attribute is the place to put that offset value for use when parsing the data into program memory. The value extracted from the packed data field is first multiplied by the ''scaling_factor'', then this ''value_offset'' is added. | If a value was applied to the original value to fit it into the bit field, this attribute is the place to put that offset value for use when parsing the data into program memory. The value extracted from the packed data field is first multiplied by the ''scaling_factor'', then this ''value_offset'' is added. | ||
+ | |||
=== <description> === | === <description> === | ||
+ | |||
''OPTIONAL'' | ''OPTIONAL'' | ||
+ | |||
This attribute holds free-format text containing a description of the extracted bit field value. | This attribute holds free-format text containing a description of the extracted bit field value. | ||
+ | |||
=== <Special_Constants> === | === <Special_Constants> === | ||
+ | |||
''OPTIONAL'' | ''OPTIONAL'' | ||
Latest revision as of 18:36, 3 August 2020
The <Packed_Data_Fields> class is used to define multiple sub-fields within a single <Field_Binary> value. These values do not have to observe byte boundaries, and so are defined in terms of bits.
Note: Packed Data is prohibited in observational archive files. Consequently, SBN data preparers should not be using the <Packed_Data_Fields> structure for any observational data products, and probably not anywhere else, either. Any packed data should be extracted into standard data types before archiving. If you think you have a data set that should be an exception to this rule, contact your SBN consultant. |
For additional explanation, see the PDS4 Standards Reference, or contact your PDS node consultant.
Following are the attributes and subclasses you'll find in the <Packed_Data_Fields> class, in label order.
Note that in the PDS4 master schema, all classes have capitalized names; attributes never do.
Contents
<bit_fields>
REQUIRED
This attribute contains the number of <Field_Bit> classes in this <Packed Data Field>.
<description>
OPTIONAL
This attribute provides space for a free-format text description of the packed data.
<Field_Bit>
REQUIRED
This class, analogous to the <Field_Binary> class, defines a binary field in terms of bits rather than bytes. There must be at least one of these in the Packed_Data_Fields class, and there may be many.
<name>
REQUIRED
The name of the bit field.
<field_number>
OPTIONAL
The definition for this attribute is not sufficiently specific for it to be used reliably. It is not clear, for example, whether the field_numbers within a Packed_Data_Field always start at one, or continue numbering started at a higher level. |
<start_bit_location>
REQUIRED
The first bit comprising the value in the bit field, relative to the start of the string of bytes containing the field. Numbering begins at 1.
Note that the sequence of bytes containing packed data must be read in physical sequence from the file (i.e., as if they were characters). Then bit 1 is the most significant bit in the sequentially first byte in the field, and the bits are numbered sequentially across byte boundaries for the length of the field.
<stop_bit_location>
REQUIRED
The last bit comprising the value in the bit field, also relative to the start of the string of bytes containing the field. Numbering begins at 1.
<data_type>
REQUIRED
This must be one of two standard values: SignedBitString or UnsignedBitString. These data types are described in section 5C.4 of the Standards Reference. What it boils down to is this:
- UnsignedBitString values should be interpreted as unsigned integers, and so should be zero-extended on the left as they are transferred into standard integer fields.
- SignedBitString values are two's complement integers, and should be sign-extended into standard integer fields.
<field_format>
OPTIONAL
The only rational formats to have here would be for integers, although possibly for a non-decimal integer (hex codes, for example). This, however, is not validated.
<unit>
OPTIONAL
If there is a unit of measurement associated with the extracted value, here's where it goes.
<scaling_factor>
OPTIONAL
If the original value was scaled to fit into the bit field, this attribute is the place to put the scaling factor to be applied when parsing the data into program memory. The value extracted from the packed data field is multiplied by this value before any value_offset is applied.
<value_offset>
OPTIONAL
If a value was applied to the original value to fit it into the bit field, this attribute is the place to put that offset value for use when parsing the data into program memory. The value extracted from the packed data field is first multiplied by the scaling_factor, then this value_offset is added.
<description>
OPTIONAL
This attribute holds free-format text containing a description of the extracted bit field value.
<Special_Constants>
OPTIONAL
This class defines flag values used to indicate that a particular field value is unknown for one reason or another. It is identical to the <Special_Constants> class used in the Array classes. For details, check the Filling Out the Array 2D Data Structure - <Special_Constants> page. Here is a quick list of the special constants available in this class:
- saturated_constant
- missing_constant
- error_constant
- invalid_constant
- unknown_constant
- not_applicable_constant