JPL D-7669, Part 2 Planetary Data System Standards Reference June 15, 2001 Version 3.4 Jet Propulsion Laboratory California Institute of Technology Pasadena, California Table of Contents i PDS Standards Reference Table of Contents Chapter 1. Introduction ........................................................................................ 1-1 1.1 PDS Data Policy ................................ ................................ ................... 1-1 1.2 Purpose................................ ................................ ................................ . 1-1 1.3 Scope................................ ................................ ................................ .... 1-2 1.4 Audience................................ ................................ ............................... 1-2 1.5 Document Organization................................ ................................ ........ 1-2 1.6 Other Reference Documents................................ ................................ .. 1-2 1.7 Online Document Availability................................ ............................... 1-3 Chapter 2. Cartographic Standards.....................................................................2-1 2.1 Inertial Reference Frame, Time Tags and Units................................ ..... 2-1 2.2 Spin Axes and Prime Meridians................................ ............................ 2-1 2.3 Reference Coordinates................................ ................................ .......... 2-2 2.4 Rings ................................ ................................ ................................ .... 2-3 2.5 Reference Surface................................ ................................ ................. 2-5 2.6 Map Resolution................................ ................................ ..................... 2-5 2.7 References................................ ................................ ............................ 2-5 Chapter 3. DATA_TYPE Values and Data File Storage Formats.......................3-1 3.1 Data Elements................................ ................................ ....................... 3-1 3.2 Data Types................................ ................................ ............................ 3-1 3.3 Binary Integers ................................ ................................ ..................... 3-5 3.4 Signed vs. Unsigned Integers................................ ................................ 3-5 3.5 Floating Point Formats................................ ................................ .......... 3-5 3.6 Bit String Data................................ ................................ ...................... 3-6 3.7 Character Data ................................ ................................ ...................... 3-6 3.8 Format Specifications................................ ................................ ........... 3-6 3.9 Internal Representations of Data Types................................ ................. 3-6 Chapter 4. Data Objects and Products.................................................................4-1 4.1 Data Product File Configurations................................ .......................... 4-2 Chapter 5. Data Product Labels...........................................................................5-1 5.1 Format of PDS Labels................................ ................................ ........... 5-1 5.1.1 Labeling methods................................ ................................ ............... 5-1 5.1.2 Label format ................................ ................................ ...................... 5-4 5.2 Data Product Label Content ................................ ................................ .. 5-5 5.2.1 Attached and Detached Labels................................ ........................... 5-5 5.2.2 Combined Detached Labels................................ ................................ 5-7 5.2.3 Minimal Labels................................ ................................ .................. 5-9 5.3 Detailed Label Contents Description................................ ................... 5-11 5.3.1 Label Standards Identifiers................................ ............................... 5-11 ii Table of Contents 5.3.2 File Characteristic Data Elements................................ ..................... 5-12 5.3.3 Data Object Pointers ................................ ................................ ........ 5-14 5.3.4 Data Identification Elements................................ ............................ 5-17 5.3.5 Descriptive Data Elements................................ ............................... 5-19 5.3.6 Data Object Definitions................................ ................................ .... 5-19 5.3.7 End Statement................................ ................................ .................. 5-19 5.4 Syntax for Element Values................................ ................................ .. 5-20 Chapter 6. Data Set/Data Set Collection Contents and Naming..........................6-1 6.1 Data Set/Data Set Collection Contents ................................ .................. 6-2 6.2 Data Set Naming and Identification................................ ....................... 6-3 6.3 Data Set Collection Naming and Identification................................ ...... 6-4 6.4 Description of Name and ID Components................................ ............. 6-6 6.4.1 Format Restrictions on NAME- and ID-Class Elements..................... 6-6 6.4.2 Standard Acronyms and Abbreviations................................ .............. 6-7 Chapter 7. Date/Time Format...............................................................................7-1 7.1 Date/Times ................................ ................................ ........................... 7-1 7.2 Dates................................ ................................ ................................ ..... 7-2 7.2.1 Conventional Dates................................ ................................ ............ 7-2 7.2.2 Native Dates ................................ ................................ ...................... 7-2 7.3 Times................................ ................................ ................................ .... 7-2 7.3.1 Conventional Times................................ ................................ ........... 7-2 7.3.2 Native Times................................ ................................ ...................... 7-3 Chapter 8. Directory Types and Naming..............................................................8-1 8.1 Standard Directory Names ................................ ................................ .... 8-1 8.2 Formation of Directory Names................................ .............................. 8-2 8.3 Path Formation Standard................................ ................................ ....... 8-4 8.4 Tape Volumes................................ ................................ ....................... 8-4 8.5 Exceptions to These Standards................................ .............................. 8-4 Chapter 9. Documents...........................................................................................9-1 9.1 PDS Objects for Documents................................ ................................ .. 9-2 9.1.1 TEXT Objects................................ ................................ .................... 9-2 9.1.2 DOCUMENT Objects................................ ................................ ........ 9-2 9.2 Document Format Details ................................ ................................ ..... 9-4 9.2.1 Flat ASCII Text ................................ ................................ ................. 9-4 9.2.2 ASCII Text Containing Markup Language................................ ......... 9-5 9.2.3 Non-ASCII Formats................................ ................................ ........... 9-6 9.2.4 Validation................................ ................................ .......................... 9-6 9.3 Examples................................ ................................ .............................. 9-6 9.3.1 Simple Attached label (Plain ASCII Text)................................ .......... 9-6 9.3.2 Complex Detached Label (Two Document Versions)......................... 9-6 9.3.3 Complex Detached Label (Documents Plus Graphics)........................ 9-7 Table of Contents iii Chapter 10. File Specification and Naming.......................................................... 10-1 10.1 File Specification Standards................................ ................................ 10-1 10.1.1 ISO 9660 Level 1 Specification................................ ........................ 10-2 10.1.2 ISO 9660 Level 2 Specification................................ ........................ 10-2 10.2 Reserved Directory Names, File Names and Extensions...................... 10-3 10.2.1 Reserved Directory Names................................ ............................... 10-3 10.2.2 Reserved File Names................................ ................................ ....... 10-3 10.2.3 Reserved Extensions................................ ................................ ........ 10-3 10.3 Guidelines for Naming Sequential Files................................ .............. 10-5 Chapter 11. Media Formats for Data Submission and Archive..........................11-1 11.1 CD-ROM Recommendations................................ .............................. 11-1 11.1.1 Use of Variant Formats................................ ................................ .... 11-1 11.1.2 Premastering Recommendation................................ ........................ 11-2 11.2 DVD Recommendations................................ ................................ ..... 11-2 11.2.1 Use of Variant Formats................................ ................................ .... 11-2 11.2.2 Premastering Recommendation................................ ........................ 11-2 11.3 Packaging Software Files on a CD or DVD................................ ......... 11-2 11.4 Software Packaging Under Previous Versions of the Standard............ 11-2 Chapter 12. Object Description Language Specification and Usage...................12-1 12.1 About the ODL Specification................................ .............................. 12-1 12.1.1 Implementing ODL................................ ................................ .......... 12-2 12.1.2 Notation ................................ ................................ ........................... 12-3 12.2 Character Set ................................ ................................ ...................... 12-4 12.3 Lexical Elements................................ ................................ ................. 12-6 12.3.1 Numbers ................................ ................................ .......................... 12-6 12.3.2 Dates and Times................................ ................................ ............... 12-8 12.3.3 Strings ................................ ................................ ........................... 12-11 12.3.4 Identifiers................................ ................................ ....................... 12-12 12.3.5 Special Characters................................ ................................ .......... 12-12 12.4 Statements ................................ ................................ ........................ 12-13 12.4.1 Lines and Records................................ ................................ .......... 12-13 12.4.2 Attribute Assignment Statement................................ ..................... 12-14 12.4.3 Pointer Statement................................ ................................ ........... 12-15 12.4.4 OBJECT Statement................................ ................................ ........ 12-15 12.4.5 GROUP Statement................................ ................................ ......... 12-16 12.5 Values................................ ................................ ............................... 12-17 12.5.1 Numeric Values................................ ................................ ............. 12-17 12.5.2 Units Expressions................................ ................................ ........... 12-17 12.5.3 Text String Values ................................ ................................ ......... 12-18 12.5.4 Symbolic Literal Values................................ ................................ . 12-20 12.5.5 Sequences ................................ ................................ ...................... 12-21 12.5.6 Sets................................ ................................ ................................ 12-21 12.6 ODL Summary ................................ ................................ ................. 12-21 12.7 Differences Between ODL Versions................................ ................. 12-23 iv Table of Contents 12.7.1 Differences from ODL Version 1................................ ................... 12-23 12.7.2 Differences from ODL Version 0................................ ................... 12-24 12.7.3 ODL/PVL Usage................................ ................................ ............ 12-24 Chapter 13. PDS Objects......................................................................................13-1 13.1 Generic and Specific Data Object Definitions................................ ..... 13-1 13.2 Primitive Objects................................ ................................ ................ 13-2 Chapter 14. Pointer Usage....................................................................................14-1 14.1 Types of Pointers................................ ................................ ................ 14-1 14.1.1 Data Location Pointers (Data Object Pointers) ................................ . 14-1 14.1.2 Include Pointers ................................ ................................ ............... 14-1 14.1.3 Related Information Pointers (Description Pointers)......................... 14-2 14.2 Rules for Resolving Pointers................................ ............................... 14-3 Chapter 15. Record Formats.................................................................................15-1 15.1 FIXED_LENGTH Records ................................ ................................ . 15-1 15.2 STREAM Records ................................ ................................ .............. 15-2 15.3 VARIABLE_LENGTH Records................................ ......................... 15-2 15.4 UNDEFINED Records................................ ................................ ........ 15-3 Chapter 16. SFDU Usage ......................................................................................16-1 16.1 The ZI SFDU Organization................................ ................................ . 16-2 16.2 The ZKI SFDU Organization................................ .............................. 16-5 16.3 Examples................................ ................................ ............................ 16-7 16.4 Exceptions to this Standard ................................ ................................ . 16-8 Chapter 17. Usage of N/A, UNK and NULL........................................................17-1 17.1 Interpretation of N/A, UNK, and NULL................................ .............. 17-1 17.1.1 N/A................................ ................................ ................................ .. 17-1 17.1.2 UNK ................................ ................................ ................................ 17-1 17.1.3 NULL ................................ ................................ .............................. 17-1 17.2 Implementation Recommendations for N/A, UNK, and NULL........... 17-3 Chapter 18. Units of Measurement.......................................................................18-1 18.1 SI Units................................ ................................ ............................... 18-1 Chapter 19. Volume Organization and Naming...................................................19-1 19.1 Volume Set Types................................ ................................ ............... 19-1 19.2 Volume Organization Guidelines................................ ........................ 19-7 19.3 Description of Directory Contents and Organization........................... 19-7 19.3.1 ROOT Directory Files................................ ................................ ...... 19-7 19.3.2 CATALOG Subdirectory (Required)................................ ................ 19-8 19.3.3 Data Subdirectory (Required)................................ ........................... 19-9 19.3.4 INDEX Subdirectory (Required)................................ ...................... 19-9 19.3.5 CALIBration Subdirectory (Optional)................................ ............ 19-11 Table of Contents v 19.3.6 DOCUMENT Subdirectory (Optional)................................ ........... 19-11 19.3.7 EXTRAS Subdirectory (Optional)................................ .................. 19-12 19.3.8 GAZETTER Subdirectory (Optional)................................ ............. 19-12 19.3.9 GEOMETRY Subdirectory (Optional) ................................ ........... 19-13 19.3.10 LABEL Subdirectory (Optional)................................ .................... 19-13 19.3.11 SOFTWARE Subdirectory (Optional)................................ ............ 19-14 19.4 Volume Naming................................ ................................ ................ 19-16 19.4.1 Volume ID................................ ................................ ..................... 19-16 19.5 Volume Set Naming................................ ................................ .......... 19-17 19.5.1 Volume Set ID................................ ................................ ............... 19-17 19.6 Logical Volume Naming................................ ................................ ... 19-18 19.7 Exceptions to This Standard................................ .............................. 19-18 Chapter 20. Zip Compression...............................................................................20-1 20.1 Zip Software ................................ ................................ ....................... 20-1 20.2 Zip File Labels................................ ................................ .................... 20-2 20.3 Packaging Zip Archives on Volumes................................ .................. 20-3 20.4 Label Example................................ ................................ .................... 20-3 20.5 ZIPINFO.TXT Example ................................ ................................ ..... 20-4 20.6 Additional Files................................ ................................ .................. 20-5 Appendix A. PDS Data Object Definitions............................................................. A-1 A.1 ALIAS................................ ................................ ................................ . A-3 A.2 ARRAY (Primitive Data Object)................................ .......................... A-4 A.3 BIT COLUMN ................................ ................................ .................... A-8 A.4 BIT ELEMENT (Primitive Data Object)................................ ............ A-11 A.5 CATALOG................................ ................................ ........................ A-12 A.6 COLLECTION (Primitive Data Object)................................ ............. A-15 A.7 COLUMN................................ ................................ .......................... A-16 A.8 CONTAINER ................................ ................................ .................... A-21 A.9 DATA PRODUCER ................................ ................................ .......... A-28 A.10 DATA SUPPLIER................................ ................................ ............. A-30 A.11 DIRECTORY ................................ ................................ .................... A-32 A.12 DOCUMENT................................ ................................ ..................... A-34 A.13 ELEMENT (Primitive Data Object)................................ ................... A-38 A.14 FILE ................................ ................................ ................................ .. A-39 A.15 GAZETTEER_TABLE................................ ................................ ...... A-43 A.16 HEADER................................ ................................ ........................... A-53 A.17 HISTOGRAM ................................ ................................ ................... A-55 A.18 HISTORY................................ ................................ .......................... A-58 A.19 IMAGE................................ ................................ .............................. A-62 A.20 INDEX_TABLE................................ ................................ ................ A-67 A.21 PALETTE................................ ................................ .......................... A-72 A.22 QUBE................................ ................................ ................................ A-75 A.23 SERIES ................................ ................................ ............................. A-83 A.24 SPECTRUM................................ ................................ ...................... A-88 vi Table of Contents A.25 SPICE KERNEL................................ ................................ ................ A-91 A.26 TABLE................................ ................................ .............................. A-94 A.27 TEXT ................................ ................................ .............................. A-115 A.28 VOLUME................................ ................................ ........................ A-117 Appendix B. Complete PDS Catalog Object Set.................................................... B-1 B.1 DATA_SET................................ ................................ ......................... B-4 B.2 DATA_SET_COLL_ASSOC_DATA_SETS................................ ..... B-10 B.3 DATA_SET_COLL_REF_INFO................................ ....................... B-11 B.4 DATA_SET_COLLECTION................................ ............................. B-12 B.5 DATA_SET_COLLECTION_INFO................................ .................. B-15 B.6 DATA_SET_HOST................................ ................................ ........... B-17 B.7 DATA_SET_INFORMATION................................ .......................... B-18 B.8 DATA_SET_MAP_PROJECTION................................ .................... B-22 B.9 DATA_SET_MAP_PROJECTION_INFO................................ ......... B-25 B.10 DATA_SET_REFERENCE_INFORMATION................................ .. B-27 B.11 DATA_SET_TARGET................................ ................................ ...... B-28 B.12 DS_MAP_PROJECTION_REF_INFO ................................ .............. B-29 B.13 IMAGE_MAP_PROJECTION ................................ .......................... B-30 B.14 INSTRUMENT................................ ................................ .................. B-35 B.15 INSTRUMENT_HOST................................ ................................ ...... B-39 B.16 INSTRUMENT_HOST_INFORMATION................................ ......... B-41 B.17 INSTRUMENT_HOST_REFERENCE_INFO................................ ... B-42 B.18 INSTRUMENT_INFORMATION................................ ..................... B-43 B.19 INSTRUMENT_REFERENCE_INFO................................ ............... B-46 B.20 INVENTORY................................ ................................ .................... B-50 B.21 INVENTORY_DATA_SET_INFO................................ .................... B-52 B.22 INVENTORY_NODE_MEDIA_INFO................................ .............. B-53 B.23 MISSION ................................ ................................ .......................... B-54 B.24 MISSION_HOST................................ ................................ ............... B-59 B.25 MISSION_INFORMATION................................ .............................. B-60 B.26 MISSION_REFERENCE_INFORMATION................................ ...... B-62 B.27 MISSION_TARGET ................................ ................................ ......... B-63 B.28 PERSONNEL ................................ ................................ .................... B-64 B.29 PERSONNEL_ELECTRONIC_MAIL ................................ .............. B-66 B.30 PERSONNEL_INFORMATION ................................ ....................... B-67 B.31 REFERENCE ................................ ................................ .................... B-68 B.32 SOFTWARE................................ ................................ ...................... B-70 B.33 SOFTWARE_INFORMATION................................ ......................... B-72 B.34 SOFTWARE_ONLINE ................................ ................................ ..... B-73 B.35 SOFTWARE_PURPOSE................................ ................................ ... B-74 B.36 TARGET ................................ ................................ ........................... B-75 B.37 TARGET_INFORMATION ................................ .............................. B-77 B.38 TARGET_REFERENCE_INFORMATION ................................ ...... B-78 Table of Contents vii Appendix C. Internal Representation of Data Types.............................................C-1 C.1 MSB_INTEGER................................ ................................ .................. C-1 C.2 MSB_UNSIGNED_INTEGER ................................ ............................ C-2 C.3 LSB_INTEGER................................ ................................ ................... C-3 C.4 LSB_UNSIGNED_INTEGER ................................ ............................. C-5 C.5 IEEE_REAL ................................ ................................ ........................ C-6 C.6 IEEE_COMPLEX................................ ................................ ................ C-8 C.7 PC_REAL................................ ................................ ............................ C-9 C.8 PC_COMPLEX ................................ ................................ ................. C-11 C.9 VAX_REAL, VAXG_REAL................................ ............................. C-12 C.10 VAX_COMPLEX, VAXG_COMPLEX ................................ ............ C-15 C.11 MSB_BIT_STRING ................................ ................................ .......... C-15 C.12 LSB_BIT_STRING ................................ ................................ ........... C-16 Appendix D. Examples of Required Files............................................................... D-1 D.1 AAREADME.TXT................................ ................................ .............. D-1 D.1.1 Annotated Outline................................ ................................ ................ D-1 D.1.2 Example................................ ................................ ............................... D-2 D.2 INDXINFO.TXT ................................ ................................ ................. D-6 D.2.1 Example................................ ................................ ............................... D-6 D.3 SOFTINFO.TXT ................................ ................................ ................. D-7 D.3.1 Outline................................ ................................ ................................ . D-7 D.3.2 Example................................ ................................ ............................... D-8 Appendix E. NAIF TOOLKIT DIRECTORY STRUCTURE............................... E-1 E.1 NAIF Directory................................ ................................ ..................... E-1 E.2 TOOLKIT Directory................................ ................................ ............. E-1 E.3 Using the NAIF Toolkit................................ ................................ ........E-5 E.4 NAIF's File Naming Conventions................................ ......................... E-5 Appendix F. Acronyms............................................................................................F-1 Appendix G. SAVED Data......................................................................................G-1 Appendix H. Reference Citation Specification and Naming..................................H-1 H.1 Materials Appropriate for Inclusion in a Reference List....................... H-1 H.2 Materials Inappropriate for a Reference List................................ ......... H-1 H.3 Reference List Citations................................ ................................ ....... H-2 H.3.1 Citations - Articles................................ ................................ ............ H-2 H.3.2 Citations ­ Books or Reports ................................ ............................. H-2 H.3.3 Citations ­ Papers Presented at Meetings ................................ .......... H-3 H.3.4 Citations ­ Electronic Publications................................ .................... H-4 Change Log viii PDS Standards Reference Change Log Version Section Change 3.1 1.1 PDS Data Policy added 2.3 Reference coordinate standard expanded to support body- fixed rotating, body-fixed non-rotating, and inertial coordinate systems. 2.4 Ring coordinate standard added. 3.0 List of internal representations of data types moved to Appendix C 3.2 EBCDIC_CHARACTER added to PDS Standard data types 5.2.3 Minimal label option described 6.3 Data set collection naming -- data processing level component made optional 6.4 Data set naming -- added support for SPICE and Engineering, where no instrument component applies 10.0, ALL PDS use of UNIX/POSIX forward slash separator for path names. VMS-style bracket notation replaced. 10.2.1 Required file names for catalog objects included 12.5.4.2 PDS use of double quotes clarified 13.2 Use of Primitive objects described 14 New chapter -- Pointer Usage 17 New chapter -- PDS Usage of N/A, UNK, and NULL 19 Logical Volume organization added Appendix A Primitive Objects added Appendix A Header object -- required and optional keyword lists changed Container object -- Column no longer a requried sub-object ix Change Log Appendix B Streamlined Catalog Object Templates with examples replace 3.0 set Appendix C New appendix containing internal representations of data types (moved from Chapter 3) Appendix D Outline and example for AAREADME.TXT added Appendix E Version 3.0 Acronyms and Abbreviations modified and moved to this Appendix. Spelling and Word Usage section deleted. Index The document now features an index. ALL No other substantive changes have been made to the standards since the release of Version 3.0. Throughout the document, clarifications have been made, typos corrected, some sections have been rearranged, and new examples have been supplied. Version Section Change 3.2 Release Date: 7/24/95 5.1.2 Label format discussion added Noted that values in labels should be upper case (except descriptions). Fixed examples in Appendix A. 5.2.3, Appendix A Noted that for data products using minimal labels, DATA_OBJECT_TYPE = FILE in the Data Set Catalog Template 6 Added target IDs for DUST and SKY Added instrument component values SEDR and POS Noted that Data Set and Data Set Collection IDs and Names should be upper case. Fixed examples. 8 and 19 Listed CALIB and GEOMETRY as recommended directory names (as opposed to required). 8.2 SOFTWARE Subdirectory naming recommendation added 9.1 Volumes may contain multiple versions of VOLINFO Change Log x 9.2.1 Increased maximum line length in text file to 78 characters plus CR/LF 10.1 Clarified file name spcification. Noted that file name must be upper case and that full stop character required 10.2 Added recommendation that file extension identify the data type of a file. Added .QUB as reserved file extension for spectral image qubes. Added SPICE file extensions to reserved file extension list. catalog pointer name and file name: SWINV.CAT Added LABINFO.TXT to list of required xxxINFO.TXT files. Added recommended xxx INFO.TXT file names for SOFTWARE subdirectories. 10.2.3 and 5.1 added note that detached label file (*.LBL) should have the same base name as the associated data file 11.1.1 Added PDS Extended Attribute Record (XAR) policy 11.1.2 Added recommendation that CDs be premastered using single- session, single-track format. 11.1.3 Added section on Packaging Software files on a CD-ROM 14.1.2 Added new example of structure pointer 15 Added recommendation that for VAX/VMS-compatible CDs, fixed length and variable length files be an even number of bytes. Removed reference to VMS restriction to an even number of bytes in section 15.2 15.1 Removed discussion of use of BLOCK_BYTES and BLOCKING_TYPE (since this data element not in PSDD) 15.3 Added notation that CR/LF is required line terminator for PDS label and catalog files 15.5 Reworded first sentence. 17.2 Allow definition of numeric constants representing N/A, UNK, and NULL to be defined for use in an INDEX table. 18 replaced reference to PDS V1.0 with a general statement xi Change Log 19 Added SOFTWARE subdirectory recommendations 19 Recommend that an archive volume be based on a single version of the PDS standards. Volume organization guidelines added. 19.2 Clarified requirements for files & directories when logical volumes used 19.3 INDEX table standard update 19.3 use of axx- and bxx- prefixes in required file names clarified 19.4, Appendix A fixed examples--Volume and Volume set names capitalized 19.5.1 Volume set ID formation rule modified. Appendix A updated COLUMN, BIT_COLUMN, and HISTOGRAM objects required and optional keyword lists to be consistent with Table 3.1 Appendix A Added ALIAS and INDEX_TABLE objects Appendix A Added examples of COLUMN objects having ITEMs Appendix A Clarified use of ROW_SUFFIX_BYTES and ROW_PREFIX_BYTES for SPARE fields in Tables with fixed length records Appendix A Clarified the requirements for VOLUME objects for Logical volumes Appendix A Fixed examples using HEADER object to conform to current standard. Modified description of Header object to eliminate confusion.. Appendix B Inventory, Software_Inventory and Target templates added Appendix B Removed incorrect example of use of Personnel template Appendix D INDXINFO.TXT and SOFTINFO.TXT outlines and examples added Appendix D.1 Modified example of AAREADME.TXT to include rules on how pointer statements are resolved. Change Log xii Appendix E and F Added Appendix E - NAIF Toolkit Directory Structure. Acronyms and Abbreviations moved to Appendix F. ALL corrected typos, clarified text, added rationale for some standards, updated examples to conform to latest standards Change Log Version 3.1 change log updated--some items were missing Version Section Change 3.3 Release Date: 6/1/99 1.0 Added DVD as new medium 1.3 Changed Version to 3.3 1.6 Updated/corrected references 1.7 Added reference to PDS web page 2.0 Added definition for IAU Clarified text 2.3 Corrected punctuation 2.7 Fixed punctuation for references 3.4 Corrected punctuation 3.7 Corrected spelling and punctuation 4.0 Added Section headers for Primary & Secondary Objects 4.1 Corrected paragraph formatting 5.1.2 Added paragraph about ASCII character set Added paragraph about Label Padding Fixed math in calculating start byte of 8th record Aligned keyword/values 5.2.2 Corrected grammar 5.2.3 Removed "'"in the Data Set catalog template. 5.3.1 Changed Version to 3.3 5.3.2 Modified last paragraph 5.3.3 Listed examples of primary and secondary objects 5.3.3.2 Changed 'bottom' to 'following' 5.3.4 Removed AMMOS as an example 5.3.4.1 Removed SPACECRAFT_NAME as valid keyword 5.3.4.3 Removed SPACECRAFT_NAME as valid keyword. 5.3.5 Changed PDS has developed and continues to develop... Added example for a pointer (^DESCRIPTION) 5.3.6 Aligned keyword/values Clarified statement 5.3.7 Changed: needed for conformance 6.0 Prioritized organizations that PDS works with 6.1 Provided definition for Data Set Collection and removed MGN example. xiii Change Log Corrected spelling (considerations) and punctuation 6.2 Added acronyms for data set name and identifier 6.3 Changed paragraph from future tense to past tense 6.4 Section 5 - comets Section 6 - added acronyms to list Section 6 - corrected spelling (ephemeris) Section 7 - corrected spelling (gravity) Section 8 - clarified version number rules 7.0 Updated paragraph 7.1 Clarified statements about date/time formats 7.2.1 Added PDS preference for convention 7.3.1 Corrected grammar Reformatted paragraph 7.3.2 Corrected grammar Updated paragraphs 8.1 Corrected grammar (standards directory) Added EXTRAS directory Added Browse and Data directory descriptions 8.2 Section 4 - Better examples of directory names Section 5 - Reformatted paragraph Section 8 - Corrected spelling and grammar 8.3 Changed to valid keywords 8.4 Corrected grammar (data are) 9.0 - 9.3.3 Complete rewrite of Documentation Standard Added HTML standards 10.0 - 10.1 Added ISO 9660 Level 2 description Added ";1" to Level 1 description 10.2.1 Clarified required file names paragraphs Added TARGET_CATALOG pointer to list 10.2.2 VOLDESC.SFD file becomes deprecated 10.2.3 Described detached label Corrected grammar (its) 10.2.4 Added extensions and changed SPICE extensions Corrected spelling (postscript) and grammar (data that have) 11.1.1 Changed chapter name 12.1 Aligned equal signs 12.1.1.1 Added reference 12.2 Reformatted paragraph 12.3 Spelling 12.3.1 Corrected punctuation (1.234E2) 12.3.1.2 Corrected value (16#+4B#) Reformatted paragraph 12.3.1.3 Corrected value (1.234E3) 12.3.2 Updated paragraphs 12.3.2.1 Clarified date format 12.3.2.3 Clarified paragraph Change Log xiv 12.3.2.4 Changed year to 4 digits 12.3.2.5 Updated paragraph 12.3.2.5.1 Corrected value (1990-158T15:24:12z) 12.3.3.1 Corrected value ("::=") 12.3.4 Added examples 12.3.5 Corrected punctuation and grammar (units) 12.4 Corrected punctuation 12.4.1 Corrected grammar (the the) Aligned equal signs 12.4.2 Aligned equal signs 12.5.2 Reformatted asterisks to not be superscript Corrected value (60.15) 12.5.3.1 Corrected grammar (affect) Reformatted paragraphs 12.5.4 Corrected value (IO) Added valid quoted strings 12.5.4.1 Clarified paragraph 12.5.5 Reformatted asterisk to not be superscript Corrected spelling (eccentricity) Changed to valid keyword 12.5.6 Corrected value (removed 1st bracket "[") Changed to valid keyword 12.6 Reformatted paragraphs 12.7 Reformatted paragraphs 12.7.1 Corrected grammar (sections detail) 12.7.2 Corrected grammar ("is that are") 13.1 Added required keywords to definition 14.1.1 Corrected grammar (occurs) 14.1.2 Corrected punctuation Corrected value (^STRUCTURE) Changed paragraph numbering 14.2 Reformatted pointer rules 15.0 Reformatted paragraph and table 15.2 Changed paragraph numbering 15.3 Changed paragraph numbering 16.0 Corrected grammar 16.2 Clarified paragraph Changed case of #mark# 17.1 Changed case of title (and) 17.1.2 Corrected punctuation (information) 17.2 Corrected case of title (and) 18.0 Corrected SI Units (electricity potential, etc) Updated paragraph 19.1 Corrected grammar (volume types) Corrected grammar (up to the) 19.3 Corrected grammar (an SFDU) xv Change Log Corrected spelling (global) Updated Catalog and Index definitions Added description of the EXTRAS directory Added Preferred Method for supplying PDS catalog objects 19.4.1 Corrected grammar (data have been) Changed case of value (ID) 19.5 Corrected spelling (radiometry) Corrected value (VOLUME_SET_NAME) Corrected value (VOLUME_SET_ID) 19.5.1 Reformatted paragraph 19.7 Corrected case of value (IDs) 20.0 - 20.6 Complete rewrite of Zip Compression Appendix A Added URL to Cold Fusion pages A.1 Updated definition for ALIAS Corrected spelling (subobject) A.2 Added and changed Optional keywords Reformatted paragraphs Corrected spelling (the time) A.3 Changed Optional keywords Corrected spelling (created) A.5 Added TARGET to Optional Objects Clarified use of CATALOG.CAT Formatted paragraph A.7 Formatted paragraph Changed Optional keywords A.8 Updated paragraph A.10 Changed case of keyword values to uppercase A.11 Corrected grammar (on a) Corrected grammar (on the medium) A.12 Removed incorrect statements Updated example A.13 Changed Optional keywords A.14 Removed a Required keyword Added Optional keywords A.15 Changed value to keyword (GAZETTEER_TABLE) Corrected grammar (the breath & upper right) Added Optional Keywords section Added Optional Objects section Added trailing double quote to DESCRIPTION section A.16 Corrected paragraph to reflect proper file name Changed value to be enclosed in double quotes A.18 Added Required and Optional Keywords and Objects sections A.19 Added BAND_NAME keyword Added Optional keyword Changed values to be keyword (CHECKSUM) Changed values to be keyword (SCALING_FACTOR) Change Log xvi A.20 Changed paragraphs Changed case of keyword values to uppercase A.21 Reformatted paragraphs Removed Optional Keyword Added Optional Objects Corrected example (see additional example in A.27.1) A.23 Added example for CORE_ITEM_TYPE Corrected FILE_RECORDS to be accurate Corrected invalid keyword (SUB_SOLAR_AZIMUTH) A.24 Corrected grammar (data that vary) A.26 Corrected grammar (data are) Corrected punctuation (The Tookit) A.27 Corrected grammar (meta-data which are) Updated section numbers to reflect location (spares) Repaired examples (byte lengths) A.28 Line length to 72 chars Added Required and Optional Objects Repaired example A.29 Updated Optional keyword Changed case of keyword values to uppercase Appendix B Changed paragraph Changed text description length to be 80 characters from 72 Added text formatting standards B.1 Corrected punctuation Repaired example B.2 Reformatted paragraph Reformatted and repaired example B.3 Corrected spelling (DESCRIPTION) Reformatted paragraph Reformatted and repaired example B.4 Corrected spelling (description & instrument) Reformatted paragraph Reformatted and repaired example B.5 Corrected grammar (properties of the) Reformatted paragraph Reformatted and repaired example B.6 Repaired example B.7 Reformatted paragraph Reformatted and repaired example B.8 Repaired example B.10 Corrected spelling (package) Replaced example of SOFTWARE_INVENTORY template B.11 Corrected grammar (target catalog) Corrected grammar (SURFACE_GRAVITY) Repaired example Appendix C Minor corrections throughout text xvii Change Log C.5 Corrected spelling (exponent-as-stored) C.10 Corrected spelling (imaginary) Appendix E Corrected sentence (source code for) Corrected spelling (spacit) Corrected grammar (These data are) Corrected punctuation Appendix F Corrected CD-WO nomenclature Added DE (Data Engineer) Corrected spelling (Principal) Appendix G Added SAVED Data as new section Version Section Change 3.4 Release Date: 06/15/2001 Technical editing of the entire document (Chapters 1-20, Appendices A-G) was performed by Anne Raugh under contract to JPL. This editing focused on correcting awkward language, making examples consistent with the text, clarifying apparent internal inconsistencies, and in general ensuring a more readable document. Substantive changes to the standards themselves were specifically prohibited. Document changes made by Raugh were reviewed by Lyle Huber (ATMOS) and Ron Joyner (CN). Cases in which the intention of the original document could not be determined by the above team were referred to Steve Hughes (CN), who acted as both historian and final arbiter. On May 04, 2001, Ann Raugh, Richard Simpson, Lyle Huber, Steve Hughes, and Ron Joyner met at New Mexico State University to discuss and arbitrate the final set of changes to be incorporated into this document. Chapter 1. Introduction 1-1 Chapter 1. Introduction In order for planetary science data to be useful to those not directly involved in its creation, sup- porting information must be made available with the data to allow effective use and interpretation. The exchange of data is increasingly important in planetary science; thus there is a need for establishment and enforcement of standards regarding the quality and completeness of data. Electronic communication has become more sophisticated, and the use of new media (such as CD-ROMs and DVD) for data storage and transfer requires additional formatting standards to ensure long-term readability and usability. To these ends, the Planetary Data System (PDS) has developed a data set nomenclature consistent across discipline boundaries, as well as standards for labeling data files. 1.1 PDS Data Policy Only data that comply with PDS standards will be published in volumes labeled "Conforms to PDS Standards". When the PDS assists in the preparation of data published in a non-compliant format, PDS participation should be acknowledged with the statement such as "funded by PDS". The PDS Management Council makes decisions on compliance waivers. Non-compliant data sets will be incorporated into the PDS archives only under unusual circumstances. 1.2 Purpose This document is intended as a reference manual for use in conjunction with the PDS Data Preparation Workbook and the Planetary Science Data Dictionary. The PDS Data Preparation Workbook describes the end-to-end process for submitting data to the PDS and gives instructions for preparing data sets. In addition, a glossary of terms used throughout the documentation is included as an appendix to the Workbook. The Planetary Science Data Dictionary (PSDD) contains definitions of the standard data element names and objects. This Standards Reference defines all PDS standards for data preparation. 1.3 Scope The information included here constitutes Version 3.4 of the Planetary Data System data preparation standards for producing archive quality data sets. 1-2 Chapter 1. Introduction 1.4 Audience This document is intended primarily to serve the community of scientists and engineers responsible for preparing planetary science data sets for submission to the PDS. These include restored data from the era prior to PDS, mission data from active and future planetary missions, and data from earth-based sites. The audience includes personnel at PDS discipline and data nodes, mission principal investigators, and ground data system engineers. 1.5 Document Organization The first chapter of this document, "Chapter 1 ­ Introduction", provides introductory material and citations of other reference documents. The remaining chapters provide an encyclopedia of data preparation standards, organized alphabetically by standard title. 1.6 Other Reference Documents The following references are cited in this document: ?? Batson, R. M., (1987) "Digital Cartography of the Planets: its Status and Future", Photo- grammetric Engineering & Remote Sensing 53, 1211-1218. ?? Davies, M.E., et al. (1991) "Report of the IAU/IAG/COSPAR Working Group on Carto - graphic Coordinates and Rotational Elements of the Planets and Satellites: 1991", Celestial Mechanics, 53,377-397. ?? Greeley, R. and Batson, R.M. (1990) Planetary Mapping, Cambridge University Press, Cambridge, 296p. ?? Guide on Data Entity Naming Conventions, NBS Special Publication 500-149. ?? Planetary Science Data Dictionary, JPL D-7116 Rev D, July 15, 1996, (Available from the PDS). ?? Planetary Data System Data Preparation Workbook Version 3.1, JPL D-7669 Part 1, Feb- ruary 17, 1995, (Available from the PDS) ?? Issues and Recommendations Associated with Distributed Computation and Data Management Systems for the Space Sciences, National Academy Press, Washington, DC, 111p. International Standards Organization (ISO) References: ?? ISO 9660:1988 "Information Processing - Volume and File Structure of CD-ROM for Information Exchange", April 15, 1988. Chapter 1. Introduction 1-3 ?? ISO 646:1991 ASCII character set. ?? ISO 8601:1988 "Data Element and Interchange Formats ­ Representations of Dates and Times" SFDU and PVL References: ?? Standard Formatted Data Units - Structure and Construction Rules, CCSDS 620.0-R- 1.1c, May 1992. ?? Standard Formatted Data Units - A Tutorial; CCSDS 620.0-G-1, May 1992. ?? Parameter Value Language Specification (ccsd0006); CCSD 641.0-R-0.2, June 1991. ?? Parameter Value Language -- A Tutorial; CCSDS 641.0-G-1.0, May 1992. 1.7 Online Document Availability The Planetary Science Data Dictionary, Planetary Data System Data Preparation Workbook, and this document, the Planetary Data System Standards Reference, are available online. Information on accessing these references may be found on the PDS website at the following URL: http://pds.jpl.nasa.gov To obtain a copy of these documents or for questions concerning these documents, contact the PDS Operator (at PDS_OPERATOR@jpl.nasa.gov, 626-744-5579) or a PDS data engineer. The examples provided throughout the chapters and appendices are based on both existing and planned PDS archive products, modified to reflect the current version of the PDS Standards. Data object definitions are refined and augmented from time to time, as user community needs arise, so object definitions from products designed under older versions of the Standards may differ significantly. To check the current state of any object definition, consult a PDS data engineer or this URL: http://pdsproto.jpl.nasa.gov/ddcolstdval/newdd/top.cfm Additional examples may be obtained by contacting a Data Engineer. 1-4 Chapter 1. Introduction Compliance waivers, 1-1 , 1-1 Data Preparation Workbook, 1-1 data set Non-compliant, 1-1 Management Council, 1-1 object definitions, 1-3 Planetary Science Data Dictionary, 1-1 , 1-2 , 1-2 , 1-3 , 1-2 , 1-3 , 1-3 , 1-1 Waivers (compliance), 1-1 Chapter 2. Cartographic Standards 2-1 Chapter 2. Cartographic Standards The following cartographic data standards were developed through an iterative process involving both the NASA Planetary Cartography Working Group (PCWG) and the PDS. Members of the PCWG also serve on the key International Astronomical Union (IAU) committee that formulates these standards for international adoption. It is the intention of the PDS to keep its own cartographic standards in line with those of the PCWG, and in turn the IAU. The cartographic standards used in any particular data set should be identified and, where helpful, documented on the archive volume. 2.1 Inertial Reference Frame, Time Tags and Units The Earth Mean Equator and Equinox of Julian Date 2451545.0 (referred to as the J2000 system) is the standard inertial re ference frame. The Earth Mean Equator and Equinox of Besselian 1950 (JD 2433282.5) is also supported because of the wealth of previous mission data referenced to this system. (The transformation between the two systems is well defined.) The standard format for time tags is UTC in year, month, day, hour, minute and decimal seconds, although Julian dates are also supported. The standard units are SI metric units, including decimal degrees. 2.2 Spin Axes and Prime Meridians The IAU-defined spin axes and prime meridians defined relative to the J2000 inertial reference system are the standard for planets, satellites and asteroids where these parameters are defined. For other planetary bodies, definitions of spin axis and prime meridian determine d in the future should have the body-fixed axis aligned with the principal moment of inertia, with the North Pole defined as lying along the spin axis and above the Invariable Plane. Where insufficient observations exist for a particular body to determine the principal moment of inertia, coordinates of a surface feature will be specified and these used to define the prime meridian. Note that some small, irregular bodies may have chaotic rotations and will thus need to be handled on a case -by- case basis. 2.3 Reference Coordinates There are three basic types of coordinate systems: body-fixed rotating; body-fixed non-rotating; and inertial. A body-fixed coordinate system is one associated with the body (e.g., a planet or satellite). The body-fixed system is centered on the body and rotates with the body (unless it is a non-rotating type), whereas an inertial coordinate system is fixed at some point in space. To support the descriptions of these various reference coordinate systems, the PDS has defined the following set of data elements (See the Planetary Science Data Dictionary for complete definitions.): 2-2 Chapter 2. Cartographic Standards COORDINATE_SYSTEM_TYPE COORDINATE_SYSTEM_NAME LATITUDE LONGITUDE EASTERNMOST_LONGITUDE WESTERNMOST_LONGITUDE MINIMUM_LATITUDE MAXIMUM_LATITUDE POSITIVE_LONGITUDE_DIRECTION Currently, the PDS has specifically defined two types of body-fixed rotating coordinate systems: planetocentric and planetographic. However, the set of related data elements are modeled such that definitions for other body-fixed rotating coordinate systems, body-fixed non-rotating and inertial coordinate systems can be added as the need arises. Contact a PDS data engineer for assistance in defining a specific coordinate system. The definition of planetographic longitude is dependent upon the rotation direction of the body, with longitude defined as increasing in the direction opposite to the rotation. That is to say, the longitude increases to the west if the rotation is prograde (or eastward) and vice versa. Table 2.1 lists the rotation direction (prograde or retrograde) of the primary planetary bodies and the Earth's Moon. It also indicates the valid longitude range f or each body. In order to accommodate different traditions in measuring longitude, the Planetary Science Data Dictionary defines a broad longitude range: (-180, 360). Table 2.1 indicates which part of that range is applicable to which body. Table 2.1: Primary Bodies and Earth's Moon: Rotation Direction and Longitude Range Planet Rotation Direction Longitude Range Earth Prograde (0, 360) (-180, 180)* Mars Prograde (0, 360) Mercury Prograde (0, 360) Moon Prograde (0, 360) (-180, 180)* Jupiter Prograde (0, 360) Neptune Prograde (0, 360) Pluto Retrograde (0, 360) Saturn Prograde (0, 360) Sun Prograde (0, 360) (-180, 180)* Uranus Retrograde (0, 360) Venus Retrograde (0, 360) * The rotations of the Earth, Moon and Sun are prograde, however it has been traditional to measure longitudes for these bodies as increasing to the east instead of the west. The PDS recommends that the planetographic longitude standard be followed, but also supports the Chapter 2. Cartographic Standards 2-3 traditional method. Specifically, the longitude range of (-180, 180) is supported for the Earth, Moon and Sun 2.3.1 Body-Fixed Rotating Coordinate Systems 2.3.1.1 Planetocentric The planetocentric system has an origin at the center of mass of the body. Planetocentric latitude is the angle between the equatorial plane and a vector connecting the point of interest and the origin of the coordinate system. Latitudes are defined as positive in the northern hemisphere of the body, where north is in the direction of Earth's angular momentum vector, i.e., pointing toward the hemisphere north of the solar system invariant plane. Longitudes increase toward the east, making the planetocentric system right-handed. 2.3.1.2 Planetographic The planetographic system has an origin at the center of mass of the body. The planetographic latitude is the angle between the equatorial plane and a vector through the point of interest, where the vector is normal to a biaxial ellipsoid reference surface. Planetographic longitude is defined as increasing with time to an observer fixed in space above the object of interest. Thus, for prograde rotators (rotating counter clockwise as seen from a fixed observer located in the hemisphere to the north of the solar system invariant plane), planetographic longitude increases toward the west. For a retrograde rotator, planetographic longitude increases toward the east. 2.4 Rings Locations in planetary ring systems are specified in polar coordinates by a radius distance (measured from the center of the planet) and a longitude. Longitudes increase in the direction of orbital motion, so the ring pole points in the direction of right -handed rotation. Note that this corresponds to the IAU-defined North Pole for Jupiter, Saturn and Neptune, but the South Pole for Uranus. Longitudes are given relative to the ascending node of the ring plane on the Earth's mean equator of J2000. However, the Earth's mean equator of B1950 is also supported as a reference longitude because of the wealth of data already reduced using this coordinate frame. The difference is generally a small, constant offset to the longitude. All longitude values fall between 0 and 360 degrees. Note that ring coordinates are always given in an inertial frame, as it is impossible to define a suitable rotating coordinate frame for a ring system where features rotate at different rates. When it is necessary to specify the location of a moving body or feature, the rotation rate and epoch must be specified in addition to the longitude. To support the description of locations in a planetary ring system, the PDS has defined the following elements: 2-4 Chapter 2. Cartographic Standards RING_RADIUS MINIMUM_RING_RADIUS MAXIMUM_RING_RADIUS RING_LONGITUDE MINIMUM_RING_LONGITUDE MAXIMUM_RING_LONGITUDE B1950_RING_LONGITUDE MINIMUM_B1950_RING_LONGITUDE MAXIMUM_B1950_RING_LONGITUDE RING_EVENT_TIME RING_EVENT_START_TIME RING_EVENT_STOP_TIME RADIAL_RESOLUTION MINIMUM_RADIAL_RESOLUTION MAXIMUM_RADIAL_RESOLUTION The radius and longitude elements define an inertial location in the rings, and the ring event time elements define the time at the ring plane to which an observation refers. If desired, the radial resolution elements can be used to specify the radial dimensions of ring features that can be resolved in the data. See the Planetary Science Data Dictionary (PSDD) for complete definitions of these elements. In general, the above elements refer to locations in an equatorial ring. However, under certain circumstances it is necessary to define these values for an inclined ring, in which case the interpretations are slightly more complicated. Here longitudes are measured as a "broken angle" along the planet's equatorial plane to the ascending node of the ring plane, and thence along the ring plane. In these circumstances, it is also necessary to define the orbital elements of the ring in question via the following elements in the PSDD: RING_INCLINATION RING_ASCENDING_NODE_LONGITUDE NODAL_REGRESSION_RATE POLE_RIGHT_ASCENSION POLE_DECLINATION COORDINATE_SYSTEM_ID The ascending node longitude refers to the moment defined by the RING_EVENT_TIME. The ring inclination is given relative to the planet's equator, as specified by the spin pole's right ascension and declination. The COORDINATE_SYSTEM_ID can be either "J2000" or "B1950", with "J2000" serving as the default. See the PSDD for further details. Chapter 2. Cartographic Standards 2-5 2.5 Reference Surface Two standard reference surface models are supported: the digital terrain model (DTM) and the digital image model (DIM). Note, however, that Mars is an exception for which planetographic latitude is used. The digital terrain model defines body radius as a function of cartographic latitude and longitude in a sinusoidal equal-area projection. Spheroids, ellipsoids and harmonic expansions giving analytic expressions for radius as a function of cartographic coordinates are all supported. The digital image model (DIM) defines body brightness in a specified spectral band or bands as a function of cartographic latitude and longitude in a sinusoidal equal -area projection, and associated with the surface radius values in the corresponding DTM. DIMs registered to spheroids, ellipsoids and harmonic expansions are supported. 2.6 Map Resolution The suggested spatial resolution for a map is 1/2n degrees. The suggested vertical resolution is 1 x 10m meters, with m and n chosen to preserve all the resolution inherent in the data. 2.7 References The following references provide more detail on the cartographic data standards: Davies, M. E., et al (1991) "Report of the IAU/IAG/COSPAR Working Group on Cartographic Coordinates and Rotational Elements of the Planets and Satellites: 1991," Celestial Mechanics, 53, 377-397. Batson, R.M., (1987) "Digital Cartography of the Planets: New Methods, its Status and Future", Photogrammetric Engineering & Remote Sensing, 53, 1211-1218. Greeley, R. and Batson, R.M. (1990) Planetary Mapping, Cambridge University Press, Cambridge, 296p. 2-6 Chapter 2. Cartographic Standards body coordinates prime meridians, 2-1 spin axes, 2-1 map resolution, 2-5 reference coordinates, 2-1 body-fixed, 2-2, 2-3 data elements, 2-2 planetocentric, 2-2, 2-3 planetographic, 2-2, 2-3 ring systems, 2-3 ring systems, data elements, 2-4 reference frames B1950, 2-1 standard inertial (J2000), 2 -1 reference surface models, 2-5 digital image model (DIM), 2-5 digital terrain model (DTM), 2-5 rotation direction of Solar System bodies, 2-2 time tags format, 2-1 Chapter 3. DATA_TYPE Values and Data File Storage Formats 3-1 Chapter 3. DATA_TYPE Values and Data File Storage Formats Each PDS archived product is described using label objects that provide information about the data types of stored values. The data elements DATA_TYPE, BIT_DATA_TYPE, and SAMPLE_TYPE appear together with related elements defining starting location and length for each field. In PDS data object definitions the byte, bit, and record positions are counted from left to right, or first to last encountered, and always begin with 1. Data files may be in ASCII or binary format. ASCII format is often more easily transferred between hardware systems or even application programs on the same computer. Notwithstanding, numeric data are often stored in binary files when the ASCII representatio n would require substantially more storage space. (For example, each 8-bit signed pixel value in a binary image file would require a four-byte field if stored as an ASCII table.) 3.1 Data Elements Table 3.1 identifies by object the data elements providing type, location, and length information. The elements ITEMS and ITEM_BYTES are used to subdivide a single COLUMN, BIT_COLUMN or HISTOGRAM into a regular vector containing as many elements as specified for the value of ITEMS. In these objects the DATA_TYPE must indicate the type of a single item in the vector. In the past, the data element ITEM_TYPE was used for this purpose, but DATA_TYPE is now the preferred parameter. 3.2 Data Types Table 3.2 identifies the valid values for the DATA_TYPE, BIT_DATA_TYPE, and SAMPLE_TYPE data elements used in PDS data object definitions. The values for these elements must be one of the standard values listed in the Planetary Science Data Dictionary (PSDD). Please note: ?? In all cases, these standard values refer to the physical storage format of the data in the data file. ?? In some cases, obsolete values from previous versions of the PDS Standards have been retained as aliases for more specific values (the type "INTEGER", for example, is interpreted as "MSB_INTEGER" when it is encountered). In these cases the m ore specific value should always be used in new data sets ­ the obsolete value is retained only for backward compatibility. Obsolete values are indicated in the table. ?? Aliases have been supplied for some of the generic data types that indicate the kind of system on which the data originated. For example, "MAC_REAL" is an alias for "IEEE_REAL", but "VAX_REAL" has no alias, as the VAX binary storage format is unique to VAX systems. In general, the more generic term is preferred, but the system-specific version may be used if needed. 3-2 Chapter 3. DATA_TYPE Definitions and Data File Storage Formats Table 3.1: Type Elements Used in Data Label Objects Data Object Data Elements Notes COLUMN DATA_TYPE (without ITEMS) START_BYTE BYTES COLUMN DATA_TYPE alias for ITEM_TYPE (with ITEMS) START_BYTE BYTES (optional) total bytes in COLUMN ITEMS ITEM_BYTES bytes in each ITEM BIT_COLUMN BIT_DATA_TYPE (without ITEMS) START_BIT BITS BIT_COLUMN START_BIT (with ITEMS) BITS (optional) total bits in BIT_COLUMN ITEMS ITEM_BITS bits in each ITEM IMAGE SAMPLE_TYPE SAMPLE_BITS HISTOGRAM DATA_TYPE alias for ITEM_TYPE BYTES (optional) total bytes in HISTOGRAM ITEMS number of bins in HISTOGRAM ITEM_BYTES bytes in each ITEM Chapter 3. DATA_TYPE Values and Data File Storage Formats 3-3 Table 3.2: Standard PDS Data Types Data Element Usage Codes: D = DATA_TYPE B = BIT_DATA_TYPE S = SAMPLE_TYPE Usage Value Description D ASCII_REAL ASCII character string representing a real number; see Section 5.4 for formatting rules D ASCII_INTEGER ASCII character string representing an integer; see Section 5.4 for formatting rules D ASCII_COMPLEX ASCII character string representing a complex number; see Section 5.4 for formatting rules Obsolete BIT_STRING alias for MSB_BIT_STRING D, B BOOLEAN True/False Indicator: a 1-, 2- or 4-byte integer or 1-32 bit number. All 0 = False; anything else = True. D CHARACTER ASCII character string; see Section 5.4 for formatting rules Obsolete COMPLEX alias for IEEE_COMPLEX D DATE ASCII character string representing a dat e in PDS standard format; see Section 5.4 for formatting rules D EBCDIC_CHARACTER EBCDIC character string Obsolete FLOAT alias for IEEE_REAL D IBM_COMPLEX IBM 360/370 mainframe complex number (8- or 16- byte) D, S IBM_INTEGER IBM 360/370 mainframe 1-, 2-, and 4-byte signed integers D, S IBM_REAL IBM 360/370 mainframe real number (4- or 8-byte) D, B, S IBM_UNSIGNED_INTEGER IBM 360/370 mainframe 1-, 2-, and 4-byte unsigned integers D IEEE_COMPLEX 8-, 16-, and 20-byte complex numbers D, S IEEE_REAL 4-, 8- and 10-byte real numbers Obsolete INTEGER alias for MSB_INTEGER D LSB_BIT_STRING 1-, 2-, and 4-byte bit strings D, S LSB_INTEGER 1-, 2-, and 4-byte signed integers D, B, S LSB_UNSIGNED_INTEGER 1-, 2-, and 4-byte unsigned integers D MAC_COMPLEX alias for IEEE_COMPLEX D, S MAC_INTEGER alias for MSB_INTEGER D, S MAC_REAL alias for IEEE_REAL D, B, S MAC_UNSIGNED_INTEGER alias for MSB_UNSIGNED_INTEGER D MSB_BIT_STRING 1-, 2-, and 4-byte bit strings D, S MSB_INTEGER 1-, 2-, and 4-byte signed integers D, B, S MSB_UNSIGNED_INTEGER 1-, 2-, and 4-byte unsigned integers D, B N/A Used only for spare (or unused) fields included in the data file. 3-4 Chapter 3. DATA_TYPE Definitions and Data File Storage Formats D PC_COMPLEX 8-, 16-, and 20-byte complex numbers in IBM/PC format D, S PC_INTEGER alias for LSB_INTEGER D, S PC_REAL 4-, 8-, and 10-byte real numbers in IBM/PC format D, B, S PC_UNSIGNED_INTEGER alias for LSB_UNSIGNED_INTEGER Obsolete REAL alias for IEEE_REAL D SUN_COMPLEX alias for IEEE_COMPLEX D, S SUN_INTEGER alias for MSB_INTEGER D, S SUN_REAL alias for IEEE_REAL D, B, S SUN_UNSIGNED_INTEGER alias for MSB_UNSIGNED_INTEGER D TIME ASCII character string representing a date/time in PDS standard format; see Section 5.4 for formatting rules Obsolete UNSIGNED_INTEGER alias for MSB_UNSIGNED_INTEGER D VAX_BIT_STRING alias for LSB_BIT_STRING D VAX_COMPLEX Vax F-, D-, and H-type (8-, 16- and 32-byte, respectively) complex numbers D, S VAX_DOUBLE alias for VAX_REAL D, S VAX_INTEGER alias for LSB_INTEGER D, S VAX_REAL Vax F-, D-, and H-type (4-, 8- and 16-byte, respectively) real numbers D, B, S VAX_UNSIGNED_INTEGER alias for LSB_UNSIGNED_INTEGER D VAXG_COMPLEX Vax G-type (16-byte) complex numbers D, S VAXG_REAL Vax G-type (8-byte) real numbers 3.3 Binary Integers There are two widely used formats for integer representations in 16-bit and 32-bit binary fields: most significant byte first (MSB) and least significant byte first (LSB) architectures. The MSB architectures include IBM mainframes, many UNIX systems such as SUN, and Macintosh computers. The LSB architectures include VAX systems and IBM PCs. In the original PDS system the default format was MSB, thus the designation of "INTEGER" and "UNSIGNED_INTEGER" as aliases of "MSB_INTEGER" and "MSB_UNSIGNED_IN - TEGER". New data sets should be prepared using the appropriate specific designation from Table 3.2, above. 3.4 Signed vs. Unsigned Integers The "_INTEGER" data types refer to signed , 2's complement integers. Use the co rresponding "_UNSIGNED_INTEGER" type for unsigned integer and bit string fields. Chapter 3. DATA_TYPE Values and Data File Storage Formats 3-5 3.5 Floating Point Formats The PDS default representation for floating point numbers is the ANSI/IEEE standard. Thi s representation is defined as the IEEE_REAL data type, with aliases identified in Table 3.2. Several additional specific floating-point representations supported by PDS are described in Appendix C. 3.6 Bit String Data The BIT_STRING data types are used in definitions of table columns holding individual bit field values. A BIT_COLUMN object defines each bit field. BIT_STRING data types can be 1-, 2-, or 4-byte fields, much like a binary integer. Extraction of specific bit fields within a 2- or 4-byte BIT_STRING is dependent on the host architecture (MSB or LSB). In interpreting bit fields (BIT_COLUMNS) within a BIT_STRING, any necessary conversions such as byte swapping from LSB to MSB are done first, then bit field values (START_BIT, BITS) are used to extract the appropriate bits. This procedure ensures that bit fields are not fragmented due to differences in hardware architectures. 3.7 Character Data Specification of character field format in ASCII and binary files pending. 3.8 Format Specifications Data format specifications provided in the FORMAT element serve two purposes: 1. In an ASCII data file, they provide a format which can be used in scanning the ASCII record for individual fields; and 2. In a binary data file, they provide a format that can be used to display the binary values. A subset of the FORTRAN data format specifiers is used for the values of FORMAT elements. Valid specifiers include: Aw Character data value Iw Integer value Fw.d Floating point value, displayed in decimal format Ew.d[Ee] Floating point value, displayed in exponential format Where: w is the total number of positions in the output field (including sign, decimal point, and exponentiation character ­ usually "E" ­ if any); d is the number of positions to the right of the decimal point; e is the number of positions in exponent length field. 3-6 Chapter 3. DATA_TYPE Definitions and Data File Storage Formats 3.9 Internal Representations of Data Types Appendix C contains the detailed internal representations of the PDS standard data types listed in Table 3.2. The PDS has developed tools designed to use the specifications contained in Appendix C for interpreting data values for display and validation. Chapter 3. DATA_TYPE Values and Data File Storage Formats 3-7 aliases for data types, 3-1 binary data bit string format, 3-5 integer formats, 3-4 bit field representation, 3-5 BIT_COLUMNS, 3-5 BIT_DATA_TYPE standard values, 3-1 BIT_STRING, 3-5 data type data elements, 3-1 data types table of data element, 3-2 table of standard values, 3-3 DATA_TYPE standard values, 3-1 floating point, 3-5 floating point representation, 3-5 format specifications, 3-5 for ASCII data files, 3-5 for binary data files, 3-5 integer representations least significant byte first (LSB), 3-4 most significant byte first (MSB), 3-4 signed vs. unsigned, 3-4 ITEM_TYPE (obsolete), 3-1 ITEMS, 3-1 LSB integers. See integer representations MSB integers. See integer representations Planetary Science Data Dictionary (PSDD), 3-1 SAMPLE_TYPE standard values, 3-1 storage formats binary integers, 3-4 Chapter 4. Data Products 4-1 Chapter 4. Data Objects and Products At its simplest, a data product consists of a PDS label and the data object that it describes. More complex data products may contain several mutually dependent data objects, a primary object and one or more secondary objects, or both. In all cases, a single label is used to describe all parts of the product (even if they are held in separate physical files). A single PRODUCT_ID value is defined for the entire set in that PDS label. A data product is one component of a data set (see the Data Set/Data Set Collection Contents and Naming chapter of this document). Primary Data Object A primary data object is a set of results from a scientific observation. Primary data objects are usually described using one of these PDS object structures: TABLE IMAGE SERIES SPECTRUM Secondary Data Object A secondary data object is any data used for processing or interpreting the primary data object(s), for example, a histogram derived from an image. Secondary data objects are usually described using one of these PDS object structures: HISTOGRAM PALETTE HEADER The PDS data product label, written in Object Description Language (ODL) (see the Object Description Language (ODL) Specification and Usage chapter of this document), defines both the physical and logical structure of the constituent data object(s). 4-2 Chapter 4. Data Products 4.1 Data Product File Configurations The PDS label and data object may be in the same file or separate files. For data products with more than one object, the data objects may be in one or more files. In all cases, however, there must be exactly one PDS label containing exactly one PRODUCT_ID value. The PRODUCT_ID value must be unique within the data set containing this data product. Example Consider a data product that consists of a 3-color image in which each color plane is stored in a separate physical file (that is, one file each for red, blue and green). Since all three colors are required to get the full image, this product contains three mutually dependent primary objects. The label for this data product will contain a single PRODUCT_ID, three pointers to the separate data files, and three IMAGE object definitions. To aid in distinguishing between data files, the data preparer may also choose to include an IMAGE_ID keyword in each IMAGE object definition. The resulting PDS label would contain the following lines: PRODUCT_ID = "22A190" ... ^RED_IMAGE = "22A190R.IMG" ^GREEN_IMAGE = "22A190G.IMG" ^BLUE_IMAGE = "22A190B.IMG" ... OBJECT = RED_IMAGE IMAGE_ID = "22A190-RED" ... END_OBJECT = RED_IMAGE OBJECT = GREEN_IMAGE IMAGE_ID = "22A190-GREEN" ... END_OBJECT = GREEN_IMAGE OBJECT = BLUE_IMAGE IMAGE_ID = "22A190-BLUE" ... END_OBJECT = BLUE_IMAGE Figure 4.1 illustrates file configurations for a data product with a single data object. Chapter 4. Data Products 4-3 Figure 4.1 Data Product with a Single Data Object Figure 4.2 shows the possible file configurations for a single data product consisting of one primary and one secondary data object. Similar examples could be made using data products composed of more than two data objects. 4-4 Chapter 4. Data Products Figure 4-2. Data Product with Multiple Data Objects Chapter 4. Data Products 4-1 data product and PRODUCT_ID, 4-1 definition, 4-1 file configurations, 4-2 label example, 4-2 primary data object, 4-1 seconday data object, 4-1 PRODUCT_ID, 4-1 Chapter 5. Data Product Labels 5-1 Chapter 5. Data Product Labels PDS data product labels are required for describing the contents and format of each individual data product within a data set. PDS data product labels are written in the Object Description Language (ODL). The PDS has chosen to label the wide variety of data products under archival preparation by implementing a standard set of data object definitions, data elements, and standard values for the elements. These data object definitions, data elements, and standard values are defined in the Planetary Science Data Dictionary (PSDD). Appendix A of this document provides general descriptions and examples of the use of these data object definitions and data elements for labeling data products. 5.1 Format of PDS Labels 5.1.1 Labeling methods In order to identify and describe the organization, content, and format o f each data product, PDS requires a distinct data product label for each individual data product file. These distinct product labels may be constructed in one of three ways: Attached - The PDS data product label is attached at the beginning of the data product file. There is one label attached to each data product file. Detached - The PDS data product label is detached from the data and resides in a separate file which contains a pointer to the data product file. There is one detached label file for every data product file. The label file should have the same base name as its associated data file, but the extension .LBL . Combined Detached - A single PDS detached data product label file is used to describe the contents of more than one data product file. The combined detached label contains pointers to individual data products. NOTE: Although all three labeling methods are equally acceptable, the PDS tools do not currently support the Combined Detached label option. Figure 5.1 illustrates the use of each of these methods for labeling individual data product files. 5-2 Chapter 5. Data Product Labels Figure 5.1 Attached, Detached, and Combined Detached PDS Labels Chapter 5. Data Product Labels 5-3 5.1.2 Label format PDS recommends that labels have stream record format, and line lengths of at most 80 characters (including the CR/LF line terminators) so that the entire label can be seen on a computer screen without horizontal scrolling. The carriage return and line feed (CR/LF) pair is the required line terminator for all PDS labels. (See the Record Formats chapter of this document.) All values in a PDS label should be in upper case, except values for descriptive elements (DESCRIPTION, NOTE, etc.). It is also recommended that the equal signs in the labels be aligned for ease of reading. ASCII Character Set All values in a PDS label must conform to the standard 7-bit ASCII character set. Labels may include characters in the range of ASCII ch aracters 32 through 127 (decimal), and the record delimiters Line Feed (10 decimal) and Carriage Return (13 decimal). The remaining 7-bit ASCII characters (1-9, 11, 12, and 14-31 decimal, which includes the horizontal and vertical tab and form feed charac ters) are not permitted in PDS labels. Note that the 8-bit characters 128 through 255 (decimal) are not used in the PDS as the interpretation of these characters varies by operating system, computer platform, and font selected. Specifically, extended-set characters with diacritical marks are not to be used as they are interpreted differently by different applications. Label Padding When a fixed length data file has an attached label, the label is padded with space characters (ASCII 32 decimal) in one of the following ways: 1) Spaces are added after the label's END statement and before the data so that the total of the label (in bytes) is an integral multiple of the record length of the data. In this case, LABEL_RECORDS is calculated by dividing the total padded length of the label section, in bytes, by the stated value of RECORD_BYTES. Example In the example below, the label portion of the file is 7 x 324 = 2268 bytes in length, including blank fill between the END statement and the first byte of data. The actual data portion of the file starts at record 8 (i.e., the 1st byte of the 8th record starts at byte (7 x 324)+1 = 2269) RECORD_TYPE = FIXED_LENGTH RECORD_BYTES = 324 FILE_RECORDS = 334 LABEL_RECORDS = 7 ^IMAGE = 8 END ....blank fill.... data 5-4 Chapter 5. Data Product Labels 2) Each line in the label may be padded with space characters so that each line in the label has the same record length as the data file. In this case, the label line length may exceed the recommended 80 characters; LABEL_RECORDS is the number of physical records in the label section of the file. Example In the example below, the label portion of the file is 80 x 85 = 6800 bytes in length. Each line in the label portion of the file is 85 bytes long, the same length as each data record. Notice the blank space between the actual values in the label and the line delimiters. In the example, the label is 80 lines long (i .e., 80 records long) and the data begin at record 81. Note that the label is padded so that are in bytes 84 and 85. RECORD_TYPE = FIXED_LENGTH RECORD_BYTES = 85 FILE_RECORDS = 300 LABEL_RECORDS = 80 ... ^TABLE = 81 END Data 5.2 Data Product Label Content 5.2.1 Attached and Detached Labels PDS data product labels have a general structure that is used for all attached and d etached labels, except for data products described by minimal labels. (Minimal labels are described in Section 5.2.3.) ?? LABEL STANDARDS identifier ?? FILE CHARACTERISTIC data elements ?? DATA OBJECT pointers ?? IDENTIFICATION data elements ?? DESCRIPTIVE data elements ?? DATA OBJECT DEFINITIONS ?? END statement Figure 5.2 provides an example of how this general structure appears in an attached or detached label for a data product file containing multiple data objects. Chapter 5. Data Product Labels 5-5 Figure 5.2 PDS Attached / Detached Label Structure 5-6 Chapter 5. Data Product Labels 5.2.2 Combined Detached Labels For the Combined Detached label option, the general label structure is modified slightly to reference each individual file within its own FILE object explicitly. In addition, identification and descriptive data elements that apply to all of the files can be located before the FILE objects. ?? LABEL STANDARDS identifiers ?? IDENTIFICATION data elements that apply to all referenced data files ?? DESCRIPTIVE data elements that apply to all referenced data files ?? OBJECT=FILE statement (Repeats for each data product file) ?? FILE CHARACTERISTIC data elements ?? DATA OBJECT pointers ?? IDENTIFICATION data elements ?? DESCRIPTIVE data elements ?? DATA OBJECT DEFINITION ?? END_OBJECT=FILE statement ?? END statement Figure 5.3 provides an example of how this general structure appears in a combined detached label that describes more than one data product file. Chapter 5. Data Product Labels 5-7 Figure 5.3 PDS Combined / Detached PDS Label Structure 5-8 Chapter 5. Data Product Labels 5.2.3 Minimal Labels Use of the minimal label option is only allowed when the format of the data cannot be supported by any PDS data object structure other than the FILE object. For minimal labels the required use of data objects is waived. A minimal label does not require any explicit PDS data object definitions or pointers to data objects. This applies to both attached and detached labels. Minimal labels must satisfy the following requirements: (1) Provide the ability to locate the data associated with the label. 1a. Attached labels Since data objects and pointers are not required in the minimal label, by definition the data follow immediately after the label. 1b. Detached Labels Both the implicit and explicit use of the FILE object are supported. The FILE_NAME keyword is required in the explicit FILE object, or in the label itself if no FILE object is included. (2) Provide the ability to locate a description of the format/content of the data. One of the following must be provided in the minimal label: 2a. ^DESCRIPTION = "" This is a pointer to a file containing a detailed description of the data format, which may be located in the same directory as the data or in the DOCUMENT subdirectory. 2b. DESCRIPTION = "" This is either a detailed description of the data file, its format, data types, and use, or it is a reference to a document available externally, e.g., a Software Interface Specification (SIS) or similar document. (3) When minimal labels are used, DATA_OBJECT_TYPE = FILE should be used in the DATA_SET catalog file Chapter 5. Data Product Labels 5-9 5.2.3.1 Implicit File Object (Attached and Detached Minimal Label) The general structure for minimal labels with implicit file objects is as follows: ?? LABEL STANDARDS identifier ?? FILE CHARACTERISTIC data elements ?? IDENTIFICATION data elements ?? DESCRIPTIVE data elements ?? END statement 5.2.3.2 Explicit File Object (Detached Minimal Label) The general structure for minimal labels with explicit file objects is as follows: ?? LABEL STANDARDS identifier ?? IDENTIFICATION data elements ?? DESCRIPTIVE data elements ?? OBJECT=FILE statement ?? FILE CHARACTERISTIC data elements ?? END_OBJECT=FILE ?? END statements Figure 5.4 provides an example of how this general structure appears in a detached minimal label. In this example, an implicit FILE object is used. 5-10 Chapter 5. Data Product Labels Figure 5.4 PDS Detached Minimal Label Structure 5.3 Detailed Label Contents Description This section describes the detailed requirements for the content of PDS labels. The subsections describe label standards identifiers, file characteristic data elements, data object pointers, identification data elements, descriptive data elements, data object definitions, and the END statement. 5.3.1 Label Standards Identifiers Each PDS label must begin with the PDS_VERSION_ID data element. This element identifies the published version of the Standards to which the label adheres, for purposes of both validation as well as software development and support. For labels adhering to the standards described in this document (the PDS Standards Reference, Version 3.4), the appropriate value is "PDS3": Chapter 5. Data Product Labels 5-11 PDS_VERSION_ID = PDS3 The PDS does not require Standard Formatted Data Unit (SFDU) labels on individual products, but they may be desired for conformance with specific project or other agency requirements. When SFDU labels are provided on a PDS data product, the SFDU label must precede the PDS_VERSION_ID keyword, thus: CCSD.... [optional SFDU label] PDS_VERSION_ID LABEL_REVISION_NOTE SFDU labels in PDS products must follow the format standards described in SFDU Usage chapter in this document. The LABEL_REVISION_NOTE element is a free form, unlimited-length character string providing information regarding the revision status and authorship of a PDS label. It should include at least the latest revision date and the author of the current version, but may include a complete editing history. This element is required in all catalog labels. Example PDS_VERSION_ID = PDS3 LABEL_REVISION_NOTE = "1999-08-01, Anne Raugh (SBN), initial release;" RECORD_TYPE = FIXED_LENGTH RECORD_BYTES = 80 5.3.2 File Characteristic Data Elements PDS data product labels contain data element information that describes important attributes of the physical structure of a data product file. The PDS file characteristic data elements are: RECORD_TYPE RECORD_BYTES FILE_RECORDS LABEL_RECORDS The RECORD_TYPE data element identifies the record characteristics of the data product file. A complete discussion of the RECORD_TYPE data element and its use in describing data products produced on various platforms is provided in the Record Formats chapter in this document. The RECORD_BYTES data element identifies the number of bytes in each physical record in the data product file. The FILE_RECORDS data element identifies the number of physical records in the file. The LABEL_RECORDS data element identifies the number of physical records that make up the PDS product label. Not all of these data elements are required in every data product label. Table 5.1 lists the required (Req) and optional (Opt) file characteristic data elements for a variety of data products and labeling methods for both attached (Att) and detached (Det) labels. Where (max) is specified, the value indicates the maximum size of any physical record in the file. 5-12 Chapter 5. Data Product Labels Chapter 5. Data Product Labels 5-13 Table 5.1: File Characteristic Data Element Requirements Labeling Method Att Det Att Det Att Det Att Det RECORD_TYPE FIXED_LENGTH VARIABLE_LENGTH STREAM UNDEFINED RECORD_BYTES Req Req Rmax Rmax Omax - - - FILE_RECORDS Req Req Req Req Opt Opt - - LABEL_RECORDS Req - Req - Opt - - - Note: The FILE_NAME keyword is required in detached minimal labels. 5.3.3 Data Object Pointers "Data objects" are the actual data for which the structure and attributes are defined in a PDS label. Each data product file contains one or more data objects. The PDS uses a pointer within the product labels to identify the file locations for all objects in a data product. Example ^TABLE = "DATA.DAT" ^TABLE = ("DATA.DAT", 10 ) 5.3.3.1 Use of Pointers in Attached Labels Data object pointers are required in labels with one exception: attached labels tha t refer to only a single object. In the absence of a pointer, the data object is assumed to start in the next physical record after the PDS product label area. This is commonly the case with ASCII text files described by a TEXT object and ASCII SPICE files described by a SPICE_KERNEL object. The top two illustrations in Figure 5.5 show example files that do not require data object pointers. Object pointers are required for all data objects, even when multiple data objects are stored in a single data product file. Data object pointers in attached labels take one of two forms: ^ = nnn where nnn represents the starting record number within the file (first record is numbered 1), Or, ^ = nnn where nnn represents the starting byte location within the file (first byte is numbered 1). See Chapter 12, Object Description Language (ODL) Specification and Usage, and Chapter 14, Pointer Usage, in this document for a complete description of pointer syntax. 5-14 Chapter 5. Data Product Labels The bottom two illustrations in Figure 5.5 show the use of required data object pointers for attached label products containing multiple data objects. Figure 5.5 Data Object Pointers-Attached Labels 5.3.3.2 Use of Pointers in Detached and Combined Detached Labels When the PDS data product label is a detached or a combined detached label, data object pointers are required for all data objects referenced. The syntax for these data object pointers takes one of three forms: (1) ^object_identifier = "filename" (2) ^object_identifier = ("filename", nnn) (3) ^object_identifier = ("filename", nnn ) Chapter 5. Data Product Labels 5-15 With respect to the above three cases: (a) These object pointers reference either byte or record locations in data files that are detached, or separate from, the label file. (b) "Filename" is the name of the detached data file. Fil e names must be in uppercase characters. (c) When no offset is specified, the first record is assumed. (d) Records and bytes are numbered from 1. In the first case, the data object is located at the beginning of the referenced file. In the second case, the data object begins with the nnnth physical record from the beginning of the referenced file. In the third case, the data object begins with the nnn th byte from the beginning of the referenced file. Examples ^IMAGE = ("DATA.IMG") ^ENGINEERING_TABLE = ("DATA.DAT", 10) ^TABLE = ("DATA.TAB", 10 ) Figure 5.6 contains several examples of data object pointer usage for data product files with detached or combined detached labels. The top example shows a data product consisting of a HEADER data object and a TABLE data object together in a single file. The detached label for this product includes pointers for both data objects, with the TABLE object starting at byte 601 of file A. The middle example illustrates a combined detached label for a data product contained in two data objects, each in a separate file. A separate pointer is provided for each data object. The bottom example shows a detached label for a data product containing multiple data objects. The third example shows a complex data file structure. The HEADER object comes first in the data file and, as the pointer ("^HEADER") shows, it requires no explicit offset (record 1 is assumed). Two parallel objects, a TABLE and an IMAGE, then follow the header. For this section of the file, each record contains one row of the TABLE followed by one line of the IMAGE. In the TABLE object description, the bytes of the IMAGE are accounted for as ROW_SUFFIX_BYTES; in the IMAGE object description, the bytes of the TABLE object are accounted for as LINE_PREFIX_BYTES. Both objects start in the same record, and therefore have the same offset (4). See the IMAGE and TABLE object descriptions for more information on prefix and suffix bytes. Had this data file been organized sequentially (so that, for example, the HEADER was followed by the TABLE, which in turn was followed by the IMAGE), then each object would have had its own offset. 5.3.3.3 Note Concerning Minimal Attached and Detached Labels Data object pointers do not exist in minimal labels. In these cases the format of the data is usually fully described in a separate file or document. 5-16 Chapter 5. Data Product Labels Figure 5.6 Data Object Pointers ­ Detached & Combined Labels 5.3.4 Data Identification Elements The data identification elements provide additional information about a data product that can be used to relate the product to other data products from the same data set or data set col lection. The minimum set of identification elements required by the PDS standards (see the following subsections) is sufficient to populate a high-level database like, for example, the PDS central catalog. In addition, data preparers will choose additional identification elements from the Planetary Science Data Dictionary (PSDD) to support present and future cataloging and search operations. NOTE: When a data preparer desires a new element for a data product label - one not yet recorded in the PSDD - it can be proposed for addition to the dictionary. Contact a PDS Data Engineer for assistance. Chapter 5. Data Product Labels 5-17 5.3.4.1 Spacecraft Science Data Products The following data identification elements must be included in product labels for all spacecraft science data products: DATA_SET_ID PRODUCT_ID INSTRUMENT_HOST_NAME INSTRUMENT_NAME TARGET_NAME START_TIME STOP_TIME SPACECRAFT_CLOCK_START_COUNT SPACECRAFT_CLOCK_STOP_COUNT PRODUCT_CREATION_TIME 5.3.4.2 Earthbased Science Data Products The following data identification elements must be included in product labels for all Earth-based science data products: DATA_SET_ID PRODUCT_ID INSTRUMENT_HOST_NAME INSTRUMENT_NAME TARGET_NAME START_TIME STOP_TIME PRODUCT_CREATION_TIME 5.3.4.3 Ancillary Data Products The following data identification elements must be included in product labels for all ancillary data products. Ancillary products may be more general in nature, supporting a wide variety of instruments for a particular mission. For example, SPICE data sets, genera l engineering data sets, and uplink data are considered ancillary data products. DATA_SET_ID PRODUCT_ID PRODUCT_CREATION_TIME The following identification elements are highly recommended, and should be included in ancillary data products whenever they apply: INSTRUMENT_HOST_NAME INSTRUMENT_NAME TARGET_NAME START_TIME STOP_TIME SPACECRAFT_CLOCK_START_COUNT SPACECRAFT_CLOCK_STOP_COUNT 5-18 Chapter 5. Data Product Labels 5.3.5 Descriptive Data Elements In addition to the data identification elements required for various types of data, PDS strongly recommends including additional data elements related to specific types of data. These descriptive elements should include any elements needed to interpret or process the data objects or which would be needed to catalog the data product to support potential search criteria at the product level. Recommendations for descriptive data elements to be included come from the PDS mission interface personnel as well as the data producer's own suggestions. These additional data elements are selected from the Planetary Science Data Dictionary. NOTE: When a data element is needed for a data product label, but is not yet recorded in the PSDD, it may be proposed for addition to the dictionary. Contact a PDS data engineer for assistance in submitting new data elements for inclusion in the PSDD. Pointers are sometimes used in a PDS label to provide a shorthand method for referencing either a set of descriptive data elements (e.g., ^DESCRIPTION) or a long descriptive text passage relevant to several data product labels. 5.3.6 Data Object Definitions The PDS requires a separate data object definition within the product label for each object in the product, to describe the structure and associated attributes of each constituent object. Each object definition, whether for a primary or a secondary object, must have a corresponding object pointer as described in Section 5.3.3. Object definitions are of the form: OBJECT = aaa where aaa is the name of th e data object ... END_OBJECT = aaa The PDS has designed a set of standard data object definitions to be used for labeling products. Among these standard objects are those designed to describe structures commonly used for scientific data storage. Appendix A provides the complete set of PDS object definition requirements, along with examples of product labels. Pointers are sometimes used in a PDS label to provide a shorthand method for including a standard set of sub-objects referenced in several data product labels. For example, a pointer called "^STRUCTURE" is o ften used to include a set of COLUMN sub-objects for a TABLE structure used in many labels of the same data set. Chapter 5. Data Product Labels 5-19 5.3.7 End Statement The END statement ends a PDS label. Where required by an outside agency, the END statement may be followed by one or more SFDU labels. The PDS does not require SFDU labels on individual products, but they may be required to conform with specific project or other agency requirements. If SFDUs are provided on a data product, they must follow the standards described in the SFDU Usage chapter in this document. In some, but not all cases, another SFDU label is required after the PDS END statement to provide "end label" and sometimes "start data" information. 5.4 Syntax for Element Values The values of keywords must be expressed in a manner appropriate to the type of the keyword. Data types for element values are specified in the element definitions contained in the PSDD. The syntax rules for expressing these values in PDS labels are discussed in detail in Section 12.3 of Chapter 12: Object Description Language Specification and Usage. A brief summary is provided here for reference. Character Strings Character strings are enclosed in double quotes unless they consist entirely of uppercase letter, number, and/or underscore ( _ ) characters. Examples NAME = FILTER Correct NAME = "FILTER WAVELENGTH" Correct NAME = FILTER_WAVELENGTH Correct NAME = FILTER WAVELENGTH Incorrect Integers Integer values must be presented as a string of digits, optionally preceded by a sign. Specifically, no comma or point should be used to group digits. Values that are to be interpreted as integers must not be enclosed in quotation marks of any kind. Examples ITEMS = 12 Correct REQUIRED_STORAGE_BYTES = 43364 Correct ITEMS = "12" Incorrect REQUIRED_STORAGE_BYTES = 43,364 Incorrect 5-20 Chapter 5. Data Product Labels Floating-Point Numbers Real data values may be expressed as either floating-point numbers with a decimal point or in scientific notation with an exponent. Scientific notation is formatted in the standard manner for program I/O, using the letter "E" as an exponentiation operator. Values that are t o be interpreted as real numbers must not be enclosed in quotation marks of any kind. Examples TELESCOPE_LATITUDE = 33.476 Correct TELESCOPE_LATITUDE = 3.3476E+01 Correct TELESCOPE_LATITUDE = "33.476" Incorrect TELESCOPE_LATITUDE = 3.3476 x 10^01 Incorrect Dates and Times Date and time values must be in the PDS standard date/time format: YYYY-MM- DDThh:mm:ss.sss. Date and time values must never be enclosed in quotes of any kind. Examples START_TIME = 1990-08-01T23:59:59 Correct START_TIME = "1990-08-01T23:59:59" Incorrect Chapter 5. Data Product Labels 5-21 data elements data identification, 5-16 descriptive, 5-19 file characteristics, 5-11 proposing new, 5-17 required and optional, 5-12 standards identifiers, 5-10 syntax summary, 5-20 data identification data elements, 5-16 data identification elements required for ancillary data, 5-17 required for Earth-based data, 5-17 required for spacecraft data, 5-17 data objects definition of, 5-13 object definitions, 5-19 standard data objects, 5-19 data products labels, 5-1 descriptive data elements, 5-19 END statement, 5-20 file characteristics data elements, 5-11 FILE_NAME, 5-13 FILE_RECORDS, 5-11 Label structure combined detached example, 5-7 LABEL_RECORDS, 5-11 LABEL_REVISION_NOTE, 5-11 labels, 5-1 and SFDU labels, 5-11, 5-20 attached, 5-1 combined detached, 5-1, 5-6 descriptive text pointers, 5-19 detached, 5-1 END statement, 5-20 format, 5-3 character set, 5-3 minimal, 5-8, 5-9 Object Description Language (ODL), 5-1 object pointers, 5-13 attached label examples, 5-14 detached label examples, 5-15 padding, 5-3 5-2 Chapter 5. Data Product Labels pointers to data objects, 5-13 to descriptive text, 5-19 to structure files, 5-19 standard data objects, 5-19 standards identifiers, 5-10 structure attached and detached, 5-4 combined detached, 5-6 minimal, 5-9 minimal example, 5-10 structure pointers, 5-19 Labels structure attached/detached example, 5-5 minimal label, 5-8 minimal labels, 5-15 object definitions format, 5-19 Object Description Language (ODL), 5-1 object pointers, 5-13 attached label examples, 5-14 formats, 5-13 syntax, 5-14 Planetary Science Data Dictionary (PSDD), 5-1, 5-16, 5-19 pointers structure pointers, 5-19 to descriptive text, 5-19 RECORD_BYTES, 5-11 RECORD_TYPE, 5-11 Standard Formatted Data Unit (SFDU), 5-11, 5-20 standards identifier data elements, 5-10 Chapter 6. Data Set/Data Set Collection Contents and Naming 6-1 Chapter 6. Data Set / Data Set Collection Contents and Naming The Data Set / Data Set Collection Contents and Naming standard defines the conventions for maintaining consistency in the contents, organization and naming of archive quality data sets . Data Sets are defined in terms of Data Products, which were introduced in Chapter 4. A data set is an aggregation of data products with a common origin, history, or application. A data set includes primary (observational) data plus the ancillary data, software, and documentation needed to understand and use the observations. Files in a data set share a unique data set name, share a unique data set identifier, and are described by a single DATA_SET catalog object (or equivalent). Data Set Collections are defined in terms of data sets. A data set collection is an aggregation of several data sets that are related by observation type, discipline, target, or time which are to be treated as a unit; that is, they are intended to be archived and distributed together. Data sets in a data set collection share a unique data set collection name, share a unique data set collection identifier, and are described by a single DATA_SET_COLLECTION object (or equivalent). One of the primary considerations in creating a data set collection is that the collection as a whole provides more utility than the sum of the utilities of the individual data sets. Figure 6.1 shows the relationships among Data Products, Data Sets, and a Data Set Collection. Figure 6.1 Relationships among a Data Set Collection, its Data Sets, and their Data Products. 6-2 Chapter 6. Data Set/Data Set Collection Contents and Naming Note that with respect to Figure 6.1, additional data sets (e.g., Data Set #2) have structure similar to Data Set #1. And, Ancillary Data Products are often organized into directories corresponding to the subject areas shown (see Chapter 19 for a more detailed description of each directory). Ancillary Data Products may include any or all of the following: Calibration - Data products used in the conversion of raw measurements to physically meaningful values or data products needed to use the data. Geometry - Data products needed to describe the observing geometry. Examples include SEDRs and SPICE files. Documentation - Data products which describe the mission, spacecraft, instrument, and/or data set. These may include references to science papers or the papers themselves. Catalog Information - Descriptive information about a data set expressed in Object Description Language (ODL) and suitable for loading into a catalog. For more information, see Appendix B. Index Files - Information that allows a user to locate the data of interest - a table of contents. An example might be a table mapping latitude/longitude ranges to file names. Data Dictionary Files - An extract of the Planetary Science Data Dictionary (PSDD) that is pertinent to the data set and expressed in ODL . Gazetteer - Information about the named features on a target body associated with the data set. Software - Software libraries, utilities, and/or application programs to access/process the data products. 6.1 Data Set Naming and Identification Each PDS data set must have a unique name (DATA_SET_NAME) and a unique identifier (DATA_SET_ID), both formed from up to seven components. The components are listed here; valid assignments for each component are described in Section 6.3: Instrument host Target Instrument Data processing level number Data set type (optional) Description (optional) Chapter 6. Data Set/Data Set Collection Contents and Naming 6-3 Version number A DATA_SET_NAME must not exceed 60 characters in length. Where the character limitation is not exceeded, the full-length name of each component is used. If the full-length name is too long, an acronym is used to abbreviate components of the name. Where possible, each component of the DATA_SET_NAME should identify and reflect the corresponding (acronym) component used in forming the DATA_SET_ID. The DATA_SET_ID cannot exceed 40 characters in length. Each component of the DATA_SET_ID is an acronym that identifies and reflects the corresponding (full -name) component used in forming the DATA_SET_NAME. Within the DATA_SET_ID, acronyms are separated by hyphens. Multiple instrument hosts, instruments, or targets are referenced in a DATA_S ET_NAME or DATA_SET_ID by concatenation of the values with a forward slash, "/", which is interpreted as "and." The slash may not be used in any other capacity in a DATA_SET_ID. 6.2 Data Set Collection Naming and Identification Each PDS data set collection must have a unique name (DATA_SET_COLLECTION_NAME) and a unique identifier (DATA_SET_COLLECTION_ID), both formed from up to six components. A data set collection may contain data sets that cover several targets, be of different processing levels, or have different instrument hosts and instruments. Since the individual data sets will be identified by their own data set names, some of this information need not be repeated at the collection level. Therefore, the DATA_SET_COLLECTION_NAME uses a subset of the DATA_SET_NAME components in addition to a new component, the collection name, which identifies the group of related data sets. The components are listed here; valid assignments for each component are described in Section 6.3: Collection name Target Data processing level number (optional) Data set type (optional) Description (optional) Version number A DATA_SET_COLLECTION_NAME must not exceed 60 characters in length. Where the character limitation is not exceeded, the full-length name of each component is used. If the full- length name is too long, an acronym should be substituted. Where possible, each component of the DATA_SET_COLLECTION_NAME should identify and reflect the corresponding (acronym) component used in forming the DATA_SET_COLLECTION_ID. The DATA_SET_COLLECTION_ID must not exceed 40 characters in length. Each component is an acronym that identifies and reflects the corresponding (full-name) component used in forming the DATA_SET_COLLECTION_NAME. 6-4 Chapter 6. Data Set/Data Set Collection Contents and Naming Multiple targets or data processing levels are referenced in the data set collection name or identifier by concatenation of the values with a forward slash (/) which is interpreted as "and." 6.3 Name and ID Components 6.3.1 Restrictions on DATA_SET_ID and DATA_SET_COLLECTION_ID Within the DATA_SET_ID and DATA_SET_COLLECTION_ID, acronyms are separated by hyphens. The only characters allowed are: ?? Uppercase characters, A-Z ?? Digits, 0-9 ?? The hyphen character, "-" ?? The forward slash, "/" ?? The period character, ".", but only as part of a numeric component (e.g., "V1.0" but not "C.A") 6.3.2 Standard Acronyms, Abbreviations, and Assignments This section details the standard acronyms and abbreviations required for formulating the DATA_SET_ID and DATA_SET_COLLECTION_ID values. They are also recommended for use, as appropriate, in the formation of other NAME- and ID-class element values. Standard values for data dictionary elements mentioned in the following sections are listed in the PSDD. New values are added to these lists as needed by the PDS data engineers. 1. Instrument host name and ID values are selected from the standard value list of the corresponding PSDD entry (INSTRUMENT_HOST_NAME or INSTRUMENT_HOST_ID data element). Note that the acronym EAR has been used for Earth-based data sets without a specific instrument host. 2. Collection names and IDs are created as needed by the data preparers in conjunction with the PDS data engineer. Current IDs and their corresponding nam es include: GRSFE Geological Remote Sensing Field Experiment IHW International Halley Watch PREMGN Pre-Magellan 3. Target name values are selected from the standard values listed in the PSDD for the TARGET_NAME element. Target acronyms are selected from the following list: Target ID Target Name Chapter 6. Data Set/Data Set Collection Contents and Naming 6-5 A Asteroid C Comet CAL Calibration D Dust E Earth H Mercury J Jupiter L Moon M Mars MET Meteorite N Neptune P Pluto R Ring S Saturn SA Satellite SS Solar System U Uranus V Venus X Other, (e.g., Checkout) Y Sky NOTE: Satellites or rings are referenced in DATA_SET_NAMEs and DATA_SET_IDs by the concatenation of the satellite or ring identifier with the associated planet identifier; for example: JR Jupiter's rings JSA Jupiter's satellites If Jupiter data are also included in the ring and/or satellite data set then only Jupiter ("J") is referenced as the target. Note that in some cases this component represents the TARGET_TYPE rather than the target name, for example: A Asteroid C Comet CAL Calibration MET Meteorite Valid values for the TARGET_TYPE data element are listed in the PSDD. 4. Instrument name and ID values are taken either from the corresponding PSDD element, or from the following list of values designated for certain types of ancillary data: Names: INSTRUMENT_NAME data element in the PSDD IDs: INSTRUMENT_ID data element in the PSDD 6-6 Chapter 6. Data Set/Data Set Collection Contents and Naming Ancillary Data: ENG or ENGINEERING for engineering data sets SPICE for SPICE data sets GCM for Global Circulation Model data SEDR for supplemental EDR data POS for positional data 5. Data processing level number is the National Research Council (NRC) Committee on Data Management and Computation (CODMAC) data processing level number. Normally a data set contains data of one processing level. PDS recommends that data of different processing levels be treated as different data sets. However, if it is not possible to separate the data, then a single data set with multiple processing levels will be accepted. Use the following guidelines when specifying the data processing level number component of the data set identifier and name: (a) the processing level number of the largest subset of data or (b) the highest processing level number if there is no predominant subset. Level Type Data Processing Level Description 1 Raw Data Telemetry data with data embedded. 2 Edited Data Corrected for telemetry errors and split or decommutated into a data set for a given instrument. Sometimes called Experimental Data Record. Data are also tagged with time and location of acquisition. Corresponds to NASA Level 0 data. 3 Calibrated Data Edited data that are still in units produced by i nstrument, but that have been corrected so that values are expressed in or are proportional to some physical unit such as radiance. No resampling, so edited data can be reconstructed. NASA Level 1A. 4 Resampled Data Data that have been resampled in the time or space domains in such a way that the original edited data cannot be reconstructed. Could be calibrated in addition to being resampled. NASA Level lB. 5 Derived Data Derived results, as maps, reports, graphics, etc. NASA Levels 2 through 5. 6 Ancillary Data Nonscience data needed to generate calibrated or resampled data sets. Consists of instrument gains, offsets, pointing information for scan platforms, etc. 7 Correlative Data Other science data needed to interpret space-based data sets. May include ground- based data observations such as soil type or ocean buoy measurements of wind drift. 8 User Description Description of why the data were required, any peculiarities associated with the data sets, and enough documentation to allow secondary user to extract information from the data. N N Not Applicable Chapter 6. Data Set/Data Set Collection Contents and Naming 6-7 6. Data set type provides additional identification if, for example, the CODMAC data processing level component is not sufficient to identify the type or level of data. Following is a list of valid IDs and names that may be used for this component. NOTE: Several of the values in this table are currently unique to a particular mission (e.g., BIDR and MIDR were used on Magellan). These values may be used on other missions, if deemed appropriate. ID Name ADR Analyzed Data Record BIDR Basic Image Data Record CDR Composite Data Record CK SPICE CK (Pointing Kernel) DDR Derived Data Record (possibly multiple instruments) DIDR Digitalized Image Data Record DLC Detailed Level Catalog EDC Existing Data Catalog EDR Experiment Data Record EK SPICE EK (Event Kernel) GDR Global Data Record IDR Intermediate Data Record IK SPICE IK (Instrument Kernel) LSK SPICE LSK (Leap Second Kernel) MDR Master Data Record MIDR Mosaicked Image Data Record ODR Original Data Record PCK SPICE PCK (Planetary Constants Kernel) PGDR Photograph Data Record RDR Reduced Data Record REFDR Reformatted Data Record SDR System Data Record SEDR Supplementary Experiment Data Record SPK SPICE SPK (Ephemeris Kernel) SUMM Summary (data) (to be used in the browse function) SAMP Sample data from a data set (not subsampled data) 7. Description is optional, but allows the data provider to describe the data set better ­ for example, to identify a specific comet or asteroid. Following is a list of example values (both IDs and names) that can be used for this component. ID Name 6-8 Chapter 6. Data Set/Data Set Collection Contents and Naming ALT/RAD Altimetry and Radiometry BR Browse CLOUD Cloud ELE Electron ETA-AQUAR Eta-Aquarid Meteors FULL-RES Full Resolution GIACOBIN-ZIN Comet P/Giacobini-Zinner HALLEY Comet P/Halley ION Ion LOS Line of Sight Gravity MOM Moment PAR Parameter SA Spectrum Analyzer SA-4.0SEC Spectrum Analyzer 4.0 second SA-48.0SEC Spectrum Analyzer 48.0 second 8. Version number is determined as follows: (a) If there is not a previous version of the PDS data set/data set collection, then use Version 1.0. (b) If a previous version exists, then PDS recommends the following: i. If the data sets/data set collections contain the same set of data, but use a different medium (e.g., CD-ROM), then no new version number is required (i.e., no new data set identifier). The invent ory system will handle the different media for the same data set. ii. If the data sets/data set collections contain the same set of data, but have minor corrections or improvements such as a change in descriptive labeling, then the version number is inc remented by a tenth. For example, V1.0 becomes V1.1. iii. If a data set/data set collection has been reprocessed, using, for example, a new processing algorithm or different calibration data, then the version number is incremented by one (V1.0 would become V2.0). Also, if one data set/data set collection contains a subset, is a proper subset, or is a superset of another, then the version number is incremented by one. 6.4 Examples For a data set containing the first version of Mars Cloud Data derived from the Mariner 9, Viking Orbiter 1, and Viking Orbiter 2 imaging subsystems, the data set name and identifier would be : DATA_SET_NAME = "MR9/V01/V02 MARS ISS/VIS 5 CLOUD V1.0" Chapter 6. Data Set/Data Set Collection Contents and Naming 6-9 DATA_SET_ID = "MR9/V01/V02-M-ISS/VIS-5-CLOUD-V1.0" In this example the optional data set type is not used. The other components are: ?? Instrument hosts are Mariner 9, Viking Orbiter 1 and Viking Orbiter 2 ?? Target is Mars ?? Instruments are the Imaging Science Subsystem and Visual Imaging Subsystem ?? Data Processing Level number is 5 ?? Description is CLOUD ?? Version number is V1.0 Note that the individual components in the DATA_SET_ID closely match the corresponding components used in the DATA_SET_NAME. The Pre-Magellan Data Set Collection contains radar and gravity data similar to the kinds of data that Magellan collected and was used for pre-Magellan analyses of Venus and for comparisons to actual Magellan data. In conversation the data set might be described as Pre -Magellan Earth, Moon, Mercury, Mars, and Venus Resampled and Derived Radar and Gravity Data Version 1.0. The data set collection name and ID were: : DATA_SET_COLLECTION_NAME = "PRE-MAGELLAN E/L/H/M/V 4/5 RADAR/GRAVITY DATA V1.0" DATA_SET_COLLECTION_ID = "PREMGN-E/L/H/M/V-4/5-RAD/GRAV-V1.0" 6-10 Chapter 6. Data Set/Data Set Collection Contents and Naming A ancillary data product contents................................ ................................ ................................ ................................ 6-2 contents (diagram) ................................ ................................ ................................ ............... 6-2 archive quality data set................................ ................................ ................................ ................................ .6-1 data set collection................................ ................................ ................................ ................. 6-1 C calibration data ................................ ................................ ................................ ........................ 6-2 catalog information ................................ ................................ ................................ .................. 6-2 CODMAC numbers ................................ ................................ ............... See data processing level D data dictionary files................................ ................................ ................................ .................. 6-3 data processing level ................................ ................................ ................................ ................ 6-7 CODMAC numbers ................................ ................................ ................................ ............. 6-6 data product relation to data set ................................ ................................ ................................ ................ 6-1 relation to data set collection ................................ ................................ ................................ 6-1 data set contents................................ ................................ ................................ ................................ 6-1 definition ................................ ................................ ................................ ............................. 6-1 naming and identification ................................ ................................ ................................ .....6-3 processing level................................ ................................ ................................ .................... 6-7 relation to data products ................................ ................................ ................................ .......6-1 reprocessed, version number ................................ ................................ ................................ 6-9 data set collection contents................................ ................................ ................................ ................................ 6-1 contents (diagram) ................................ ................................ ................................ ............... 6-2 definition ................................ ................................ ................................ ............................. 6-1 naming and identification ................................ ................................ ................................ .....6-4 relation to data products ................................ ................................ ................................ .......6-1 reprocessed, version number ................................ ................................ ................................ 6-9 data set description acronyms ................................ ................................ ................................ ............................. 6-8 data set type acronyms ................................ ................................ ................................ ............................. 6-7 DATA_SET_COLLECTION_ID constituent components................................ ................................ ................................ ........6-4 data set type ................................ ................................ ................................ ......................... 6-7 description ................................ ................................ ................................ ........................... 6-8 6-2 Chapter 6. Data Set/Data Set Collection Contents and Naming example ................................ ................................ ................................ ............................. 6-10 standard acronyms and abbreviations ................................ ................................ ................... 6-5 syntax ................................ ................................ ................................ ................................ ..6-4 version number ................................ ................................ ................................ .................... 6-9 DATA_SET_COLLECTION_NAME constituent components................................ ................................ ................................ ........6-4 example ................................ ................................ ................................ ............................. 6-10 DATA_SET_ID constituent components................................ ................................ ................................ ........6-3 data set type ................................ ................................ ................................ ......................... 6-7 description ................................ ................................ ................................ ........................... 6-8 example ................................ ................................ ................................ ............................... 6-9 satellite and ring names in ................................ ................................ ................................ ....6-6 standard acronyms and abbreviations ................................ ................................ ................... 6-5 syntax ................................ ................................ ................................ ................................ ..6-4 version number ................................ ................................ ................................ .................... 6-9 DATA_SET_NAME constituent components................................ ................................ ................................ ........6-3 example ................................ ................................ ................................ ............................... 6-9 satellite and ring names in ................................ ................................ ................................ ....6-6 documentation ................................ ................................ ................................ ......................... 6-2 G gazetteer data ................................ ................................ ................................ ........................... 6-3 geometry data ................................ ................................ ................................ .......................... 6-2 I index files ................................ ................................ ................................ ................................ 6-3 P processing level number................................ ................................ ......... See data processing level S software files ................................ ................................ ................................ ........................... 6-3 T target acronyms ................................ ................................ ................................ ............................. 6-5 TARGET_NAME acronym list ................................ ................................ ................................ ......................... 6-5 Chapter 6. Data Set/Data Set Collection Contents and Naming 6-3 V version number ................................ ................................ ................................ ........................ 6-9 Chapter 7. Date/Time Format 7-1 Chapter 7. Date/Time Format PDS has adopted a subset of the International Standards Organization Standard (ISO/DIS) 8601 standard entitled "Data Element and Interchange Formats - Representations of Dates and Times", and applies the standard across all disciplines in order to give the system generality. See also Dates and Times in Object Description Language (Chapter 12, Section 12.3.2) of this document. It is important to note that the ISO/DIS 8601 standard covers only ASCII representations of dates and times. 7.1 Date/Times In the PDS there are two recognized date/time formats: CCYY-MM-DDTHH:MM:SS.sssZ (preferred format) CCYY-DDDTHH:MM:SS.sssZ Each format represents a concatenation of the conventional date and time expressions with the two parts separated by the letter T: CC - century (00-99) YY - year (00-99) MM - month (01-12) DD - day of month (01-31) DDD - day of year (001-366) T - date/time separator HH - hour (00-23) MM - minute (00-59) SS - second (00-59) sss - fractions of second (000-999) The time part of the expression represents time in Universal Time Coordinated (UTC), hence the Z at the end of the expression (see Section 7.3.1 for further discussion). Note that in both the PDS catalog files and data product labels the "Z" is optional and is assumed. PDS standard date/time format, i.e., the preferred date/time format, is: CCYY-MM- DDTHH:MM:SS.sssZ. Date/Time Precision The above date/time formats may be truncated on the right to match the precision of the date/time value in any of the following forms: 7-2 Chapter 7. Date/Time Format 1998 1998-12 1998-12-01 1998-12-01T23 1998-12-01T23:59 1998-12-01T23:59:58 1998-12-01T23:59:58.1 ODL Date/Time Information Chapter 12, Object Description Language (ODL) Specification and Usage, Section 12.3.2, Dates and Times, of this document provides additional information on the use of ODL in date/time formation, representation, and implementation. 7.2 Dates The PDS allows dates to be expressed in conventional and native (alternate) formats. 7.2.1 Conventional Dates Conventional dates are represented in ISO/DIS 8601 format as either year (including century), month, day-of-month (CCYY-MM-DD), or as year, day-of-year (CCYY-DDD). The hyphen character (`-`) is used as the field separator in this format. The former is the preferred format for use in PDS labels and catalog files and is referred to as PDS standard date format, but either format is acceptable. 7.2.2 Native Dates Dates in any format other than the ISO/DIS 8601 format described above are considered to be in a format native to the specific data set, thus "native dates". Native date formats are specified by the data preparer in conjunction with the PDS data engineer. Mission -elapsed days and time-to- encounter are both examples of native dates. 7.3 Times The PDS allows times to be expressed in conventional and native (alternate) formats. 7.3.1 Conventional Times Conventional times are represented as hours, minutes, and seconds using the full ISO/DIS 8601 format: HH:MM:SS.sss. Note that the hours, minutes, and integral seconds fields must contain two digits. The colon character (`:') is used as a field separator. The seconds field may include a fractional part if appropriate; if so, a period is used as the decimal point (the European -style comma may not be used). The fractional part may not exceed 3 digits (thousandths of a second). The PDS has adopted the use of Universal Time Coordinated (UTC) for expressing time, using Chapter 7. Date/Time Format 7-3 the format HH:MM:SS.sssZ. Note that in both the PDS catalog files and data product labels the "Z" is optional and is assumed. Fractions of seconds cannot exceed a precision of milliseconds. This format is hereafter referred to as PDS standard time format. The START_TIME and STOP_TIME data elements required in data product labels and catalog templates use the UTC format. For data collected by spacecraft-mounted instruments, the date/ time must be a time that corresponds to "spacecraft event time". For data collected by instruments not located on a spacecraft, this time shall be an earth -based event time value. Adoption of UTC (rather than spacecraft-clock-count, for example) as the standard facilitates comparison of data from a particular spacecraft or ground-based facility with data from other sources. 7.3.2 Native Times Times in any format other than the ISO/DIS 8601 format described above are considered to be in a format native to the data set, and thus "native times ". The NATIVE_START_TIME and NATIVE_STOP_TIME elements hold the native time equivalents of the UTC values in START_TIME and STOP_TIME, respectively. There is one native time of particular interest, however, which has specific keywords associated with it. The spacecraft clock reading (that is, the "count") often provides the essential timing information for a space-based observation. Therefore, the elements SPACECRAFT_CLOCK_START_COUNT and SPACECRAFT_CLOCK_STOP_COUNT are required in labels describing space-based data. This value is formatted as a string to preserve precision. Note that in rare cases in which there is more than one native time relevant to an ob servation, the data preparer should consult a PDS data engineer for assistance in selecting the appropriate PDS elements. The following paragraphs describe typical examples of native time formats. 1. Spacecraft Clock Count (sclk) - Spacecraft clock count (sclk) provides a more precise time representation than event time for instrument -generated data sets, and so may be desirable as an additional time field. In a typical instance, a range of spacecraft -clock- count values (i.e., a start-and a stop-value) may be required. Spacecraft clock count (SPACECRAFT_CLOCK_START_COUNT and SPACECRAFT_CLOCK_STOP_COUNT) shall be represented as a right -justified character string field with a maximum length of thirty characters. This format will accommodate the extra decimal point appearing in these data for certain spacecraft and other special formats, while also supporting the need for simple comparison (e.g., ">" or <") between clock count values. Note that if the spacecraft clock values are not strictly numeric strings (for example, if 7-4 Chapter 7. Date/Time Format they contain colon separators), care should be taken in dealing with blank padding and justification of the string value. If necessary, non-numeric strings may be left-justified to ensure that clock values will sort in the expected way. Example SPACECRAFT_CLOCK_START_COUNT = " 1234:36.401" correct SPACECRAFT_CLOCK_START_COUNT = "1234:36.401 " incorrect 2. Longitude of Sun - Longitude of Sun ("LS") is a derived data value that can be computed, for a given target, from UTC. 3. Ephemeris Time - Ephemeris time (ET) is calculated as "TAI + 32.184 sec. + periodic terms". The NAIF S and P kernels have data that are in ET, but the user (via NAIF ephemeris readers which perform data conversion) can obtain the UTC values. 4. Relative Time - In addition to event times, certain "relative time " fields will be needed to represent data times or elapsed times. Time-from-closest-approach is an example of such a data element. These times shall be presented in a (D, H,M,S) format as a floating point number, and should include fractional seconds when necessary. The inclusion of "day" in relative times is motivated by the possible multi-day length of some delta times, as could occur, for example, in the case of the several-month Galileo Jupiter orbit. 5. Local Times - For a given celestial body, LOCAL_TIME is the hour relative to midnight in units of 1/24th the length of the solar day for the body. 6. Alternate Time Zones (Relative to UTC) - When times must be expressed according to an alternate time zone, they shall consist of hours, minutes, seconds, and an offset, in the form HH:MM:SS.sss+n, where n is the number of hours from UTC. Chapter 7. Date/Time Format 7-5 alternate time zone, 7-5 date format conventional, 7-2 native, 7-2 precision, 7-1 syntax, 7-1 Ephemeris time (ET), 7-4 local time, 7-4 LOCAL_TIME, 7-4 native time examples, 7-3 relative time, 7-4 sclk. See spacecraft clock count (sclk) spacecraft clock count (sclk), 7-3 syntax, 7-4 SPACECRAFT_CLOCK_START_COUNT, 7-3, 7-4 SPACECRAFT_CLOCK_STOP_COUNT, 7-3, 7-4 START_TIME, 7-3 STOP_TIME, 7-3 time format conventional, 7-2 native, 7-3 PDS standard time format, 7-3 precision, 7-1 syntax, 7-1 Universal Time Coordinated (UTC). See time format date/time formats, use in UTC, use of, 7-5 in labels and catalog files, 7-3 Chapter 8. Directory Types and Naming 8-1 Chapter 8. Directory Types and Naming The Directory Naming standard defines the conventions for naming directories on a data volume. This chapter lists the standard directories established by PDS, plus the rules for forming subdirectory names and abbreviations. 8.1 Standard Directory Names When any of the following directories are included on an archive product, the following standard directory naming conventions are used. Directory Contents CATALOG PDS catalog files DOCUMENT Documentation, supplementary and ancillary information to assist in understanding and using the data products EXTRAS "Value added" elements included by the data preparer, but outside the scope of the PDS archive requirements GAZETTER Tables of information about the geological features of a target INDEX Indices to assist in locating data of interest LABEL "Include" files which describe specific aspects of the data format and organization SOFTWARE Utilities, application programs, or subprograms used to access or process the data The following standard directory names are recommended for use on archive volumes. Note that these directory names are reserved for the uses described below. That is, if they appear on an archive volume, they must contain the indicated information: CALIB Calibration files used in the original processing of the data, or needed to use the data GEOMETRY Files describing the observational geometry (e.g., SEDRs, SPICE kernels) BROWSE Reduced resolution versions of data products DATA Contains one or more subdirectories of data products. The DATA subdirectory is used to unclutter the root directory of a volume by providing a single entry point to multiple data subdirectories. 8-2 Chapter 8. Directory Types and Naming Note that some data sets may not contain all the components above and, as a result, do not need all of the directories listed. For example, many image data sets do not include geometry files and so do not need a GEOMETRY directory. See the Volume Organization and Naming chapter of this document for a list of required and optional subdirectories on any specific volume. 8.2 Formation of Directory Names 1. A directory name must consist of only uppercase alphanumeric characters and the underscore character (i.e., A-Z, 0-9, or "_"). No lowercase letters (i.e., a -z) or special characters (e.g., "#", "&", "*") are allowed. 2. A directory name must not exceed eight characters in length, to comply with th e ISO 9660 level 1 media interchange standard. 3. The first letter of a directory name must be an alphabetic character, unless the directory name represents a year (e.g., 1984). 4. If numeric characters are used as part of the name (e.g., DIR1, DIR2, DIR3) the n umeric part should be padded with leading zeros up to the maximum size of the numeric (DIR0001, DIR0002, DIR3267). 5. Directories which contain a range of similarly named files must be assigned directory names using the portion of the filename which encompasses all the files in the directory, with "X's" used to indicate the range of values of actual filenames in the directory. For example, the PDS Uranus Imaging CD-ROM disk contains image files that have filenames that correspond to SPACECRAFT_CLOCK_START_COUNT values. The directory that contains the image files ranging from C2674702.IMG through C2674959.IMG has the directory name C2674XXX. 6. Directory names must use full length terms whenever possible (e.g., SATURN, MAGELLAN, CRUISE, NORTH, DATA, SOFTWARE). Otherwise, directory names must be constructed from abbreviations of full-length names using the underscore character to separate abbreviated terms, if possible. The meaning of the directory name should be clear from the abbreviation and from the directory structure. Chapter 8. Directory Types and Naming 8-3 For example, the following directory structure can be found on the Voyager 2 Images of Uranus CD-ROM Volume 1: ROOT ARIEL DOCUMENT INDEX OBERON TITANIA UMBRIEL UNKNOWN URANUS C2674XXX C2675XXX ... C2687XXX U_RINGS C2674XXX ... In this case, it is clear from the context that the directory U_RINGS is the abbreviated form of URANUS_RINGS. 7. High level directories that deal with data sets covering a range of planetary science disciplines or targets shall adhere to the following hierarchy: A Planetary science directory: PLANET Planetary body subdirectories: MERCURY, MOON, MARS, VENUS, COMET Discipline subdirectories: ATMOS, IONOSPHE, MAGNETOS, RING, SURFACE, and SATELLIT (Use satellite name if numerous files exist) 8. The recommended SOFTWARE subdirectory naming convention is described in the Volume Organization and Naming chapter of this document. Either a platform -based model or an application-based model can be used in defining software subdirectories. In a platform-based model, the hardware platform, operating system and environment must be explicitly stated. If there is more than one operating system/environment supported they are addressed as subdirectories under the hardware directories. When there is only one, the subdirectory may be promoted to the hardware directory. For example, if software for the PC for both DOS and Windows were present on the volume, the directories SOFTWARE/PC/DOS and SOFTWARE/PC/WIN would exist. If only DOS software were present, the directory would be SOFTWARE/PCDOS. 8-4 Chapter 8. Directory Types and Naming 8.3 Path Formation Standard The PDS standard for path names is based on Level 1 of the ISO 9660 international standard. A pathname may consist of up to eight directory levels. Each directory name is limited to eight characters; the forward-slash character ("/") is used as the separator in path names. Path names typically appear on PDS volumes as data in index tables for locating specific files on an archive volume. They may also appear as values in a limited number of keywords (e.g., FILE_SPECIFICATION_NAME, PATH_NAME, and LOGICAL_VOLUME_PATH_NAME). The following are examples of valid values for the keywords listed above: TG15NXXX/TG15N1XX/TG15N12X identifies the location of the directory TG15N12X at the third level below the top level of an archive volume. DOCUMENT identifies a DOCUMENT directory within the root directory. Note: The leading slash is omitted because these are relative paths. The trailing slash is included so that concatenation of PATH_NAME and FILE_NAME will yield the full file specification. See the File Specification and Naming chapter of this document for more information. Previous PDS standards allowed the use of the DEC VMS syntax for path names. While PDS support for this format continues to exist, it is recommended that all future volumes use the UNIX syntax instead. 8.4 Tape Volumes When magnetic tape is the archive medium, a disk directory structure cannot be used because the medium does not support multi-level directories. In this case, files must be stored sequentially. A directory structure for the volume must be designed in any case, so that when the data are transferred to a medium that supports hierarchical file management they can be placed into an appropriate directory structure. A DIRECTORY object must be included with each tape volume within the VOLUME object. This object is then used to describe how the sequential files should be loaded into a hierarchical structure. 8.5 Exceptions to These Standards In certain cases, the archive medium used to store the data, the hardware used to produce the data set, or the software operating on the data may impose restrictions on directory names and organization. In these cases, consult a PDS data engineer for guidance in designing the archive volume structure. Chapter 8. Directory Types and Naming 8-5 directories path names, 8-4 reserved names, 8-1 standard directories, 8-1 DIRECTORY, 8-4 directory names and ISO 9660, 8-2 syntax, 8-2 directory naming, 8-1 directory paths and ISO 9660, 8-4 syntax, 8-4 directory structure example, 8-3 on sequential media, 8-4 tape volumes, 8-4 VOLUME, 8-4 Chapter 9. Documents 9-1 Chapter 9. Documents Supplementary or ancillary reference materials are usually included with archive products to improve their short- and long-term utility. These documents augment the internal documentation of the product labels and provide further assistance in understanding the data products and accompanying materials. Typical archive documents include: ?? Flight project documents ?? Instrument papers ?? Science articles ?? Volume information ?? Software Interface Specifications (SISs) ?? Software user manuals The PDS criteria for inclusion of a document in the archive are: 1. Would this information be helpful to a data user? 2. Is the material necessary? 3. Is the documentation complete? In general, the PDS seeks to err on the side of completeness. Each document to be archived must be prepared and saved in a PDS-compliant format, including a PDS label. Documents are delivered in the DOCUMENT directory of an archive volume (see the Volume Organization and Naming chapter of this document). A flat, human-readable ASCII text version of each document must be included on the volume, although additional versions may be included in other supported formats at the option of the data producer. "Flat ASCII text" means the file may contain only the standard, 7 -bit printable ASCII character set, plus the blank character and the carriage -return and linefeed characters as record delimiters. A file is "human -readable" if it is not encoded and if any special markup tags which may be included do not significantly interfere with an average user's ability to read the file. So, for example, simple HTML files and TeX/LaTeX files with relatively little markup embedded in the text are generally considered human-readable and may, therefore, be used to satisfy the above ASCII text version requirement. Note that the PDS takes the requirement for complete documentation very seriously. Documents that are essential to the understanding of an archive are considered as important as the data files themselves. Furthermore, including a document in a PDS archive constitutes publication (or re - publication) of that document. Consequently, documents prepared for inclusion in an archive are expected to meet not only the PDS label and format requirements, but also the structural, grammatical and lexical requirements of a refereed journal submission. Documents submitted for archiving which contain spelling errors, poor grammar or illogical organization will be rejected and may ultimately lead to the rejection of the submitted data for lack of adequate documentation. 9-2 Chapter 9. Documents 9.1 PDS Objects for Documents PDS labels of documentation files use either the TEXT or DOCUMENT object, as appropriate. The DOCUMENT object is usually used with documentation files found in the DOCUMENT directory of an archive volume. Files described by a DOCUMENT object may be in any of the formats described in Section 9.2. The TEXT object may only be used with ASCII text files containing no markup. TEXT objects are most often used for small text files occurring anywhere in the archive volume (for example, the AAREADME.TXT file in the root directory or the DOCINFO.TXT file in the DOCUMENT directory). 9.1.1 TEXT Objects TEXT objects are preferred for stand-alone documents with a narrow focus. For example, the AAREADME.TXT or DOCINFO.TXT files on the archive volume are usually labeled using a TEXT object. Files described by a TEXT object must: a) Be plain, flat ASCII files without markup tags (i.e., no HTML or TeX files), encoded graphics (as in PostScript files), or programmatic structures (i.e., no source code files or scripting commands); and b) Have a file extension of ".TXT" 9.1.2 DOCUMENT Objects DOCUMENT objects are preferred when several versions of the same file are provided or when there are several component files constituting a single version of the document - for example, when graphics are included in separate files from the text. Any file labeled using a DOCUMENT object must: a) Be in one of the PDS-approved formats listed below; and b) Use the appropriate object characteristics (listed below) for the DOCUMENT object parameters and the file extension. DOCUMENT labels are most often combined detached labels, since attaching them to most of the formats listed below would make the combined file unusable in its customary environment (Microsoft Word, for example, cannot recognize ".DOC" files with attached PDS labels). Chapter 9. Documents 9-3 Format Object Interchange Document Format File Extension Format Plain ASCII Text ASCII_DOCUMENT ASCII TEXT .ASC HTML HTML_DOCUMENT ASCII HTML .HTM or .HTML* TeX TEX_DOCUMENT ASCII TEX .TEX LaTeX LATEX_DOCUMENT ASCII LATEX .TEX Adobe PDF PDF_DOCUMENT BINARY ADOBE PDF .PDF MS Word WORD_DOCUMENT BINARY MICROSOFT WORD .DOC Rich Text RTF_DOCUMENT BINARY RICH TEXT .RTF GIF GIF_DOCUMENT BINARY GIF .GIF JPG JPG_DOCUMENT BINARY JPG .JPG Encapsulated EPS_DOCUMENT BINARY ENCAPSULATED .EPS Postscript POSTSCRIPT PNG PNG_DOCUMENT BINARY PNG .PNG Postscript PS_DOCUMENT BINARY POSTSCRIPT .PS Tagged Image TIFF_DOCUMENT BINARY TIFF .TIF or .TIFF* File Format * See chapter File Specification and Naming regarding extensions with more than three characters. Example: "MYDOC" is a documentation file to be included in the DOCUMENT directory of an archive volume. Two versions will be supplied: a flat ASCII version with the graphics in separate TIFF files; and a Microsoft Word version with in-line graphics in a single file. In the PDS label, "MYDOC" will be described using a DOCUMENT object for each different file format provided. The files included in the directory will be: 1. MYDOC.ASC required ASCII version 2. MYDOC.DOC optional Microsoft Word version to retain all graphics 3. MYDOC001.TIF optional scanned TIFF version of selected pages 4. MYDOC002.TIF optional scanned TIFF version of other selected pages 5. MYDOC.LBL PDS label defining DOCUMENT object(s) for these files Optional versions of the document should have the same file name as the required ASCII version but with different extensions. Optional versions should be defined as additional DOCUMENT objects in the single PDS label; the name of the required ASCII file should be indicated in the text of the DESCRIPTION keyword. 9.2 Document Format Details 9.2.1 Flat ASCII Text Line Length and Delimiters - PDS recommends plain text files have line length restricted to 78 characters or fewer, to accommodate printing and display on standard devices. Each line must be terminated by the two-character carriage-return/linefeed sequence (ASCII decimal character codes 13 and 10, respectively). 9-4 Chapter 9. Documents Page Length and Breaks - Block paragraph style is preferred, with paragraphs being separated by at least one blank line. The form feed character (ASCII decimal code 12) may be used to indicate page breaks, in which case pages should contain no more than 60 lines of text. A formfeed character should be inserted immediately after the END statement line of an attached PDS label in these files. 9.2.2 ASCII Text Containing Markup Language Line Length and Delimiters - The 78-character line length recommendation is dropped for these files. Notwithstanding, the lines must be delimited by the carriage return/linefeed character combination. Page Length and Breaks - Page breaks are controlled by the markup in these files. Consequently, there are no specific page length recommendations. Note: ASCII files containing extensive markup may not pass the "human -readable" test. Also, some automatic converters producing, for example, HTML files that might be expected to be human-readable in fact add so many additional marks and notations that those files also fail the "human-readable" test. Consult a PDS data engineer for help in determining whether a particular file can be considered "human -readable" for archive purposes. 9.2.2.1 Hyper-Text Markup Language (HTML) Files PDS archive products must adhere to Version 3.2 of the HTML language, a standard generalized markup language (SGML) conforming to the ISO 8879 standard. All files are subject to validation against the HTML 3.2 SGML Declaration and the HTML Document Type Definition. Note: Constructs not defined in the HTML 3.2 standard (e.g., FRAME, STYLE, SCRIPT, and FONT FACE tags) are not allowed in PDS documentation files. 9.2.2.2 Location of Files PDS strongly recommends that targets of all HTML links be present on the archive volume. In cases where external links are provided, the link should lead to supplementary information that is not essential to understanding or use of the archival data. PDS recommends that all files comprising an HTML document or series of documents be located in a single directory. However, locating ancillary files (e.g., images, common files) in subdirectories may be required under certain circumstances (e.g., to avoid conflicts in file names or to minimize replication of common files). 9.2.2.3 Discouraged HTML 3.2 Capabilities Although the APPLET tag is advertised to be supported by all Java enabled browsers, not all Chapter 9. Documents 9-5 applets execute on all browsers on all platforms. Further, some browsers require that the user explicitly enable use of Java applets before the applet will execute. Consequently, applets are permitted in PDS document files only when the information they convey is not essential to understanding or use of the archival data. Use of the TAB character is permitted but strongly discouraged because of variations in implementation among browsers and resulting misalignments within documents. Use of animated GIF image files is discouraged. 9.2.3 Non-ASCII Formats Wherever possible the specific encoding and version level information should be included in the label for all non-ASCII documents. The ENCODING_TYPE keyword is used to indicate the base encoding type (e.g., PostScript, GIF, etc.), while the specific version information should be included in the text of the DESCRIPTION keyword. See the PSDD for a list of standard encoding types. Additional types may be added at the discretion of the PDS data engineer. 9.2.4 Validation Documentation files prepared to accompany a data set or data set collection must be validated. Validation consists of checking to ensure that the files can be copied or transmitted electronically, and can be read or printed by their target text -processing program. Documentation files should be spell-checked prior to being submitted to PDS for validation. 9.3 Examples 9.3.1 Simple Example of Attached label (Plain ASCII Text) The following label could be attached to a plain ASCII text file describing the content and format of Mars Pathfinder Imager Experiment Data Records. PDS_VERSION_ID = PDS3 RECORD_TYPE = STREAM OBJECT = TEXT NOTE = "Mars Pathfinder Imager Experiment Data Record SIS" PUBLICATION_DATE = 1998-06-30 END_OBJECT = TEXT END 9.3.2 Complex Example of Detached Label (Two Document Versions) If the data producer chose to provide the same document in both plain ASCII text and as a Microsoft Word document, the detached label would have the name EDRSIS.LBL and would be as follows: 9-6 Chapter 9. Documents PDS_VERSION_ID = PDS3 RECORD_TYPE = UNDEFINED ^ASCII_DOCUMENT = "EDRSIS.ASC" ^WORD_DOCUMENT = "EDRSIS.DOC" OBJECT = ASCII_DOCUMENT DOCUMENT_NAME = "Mars Pathfinder Imager Experiment Data Record" PUBLICATION_DATE = 1998-06-30 DOCUMENT_TOPIC_TYPE = "DATA PRODUCT SIS" INTERCHANGE_FORMAT = ASCII DOCUMENT_FORMAT = TEXT DESCRIPTION = "This document contains a textual description of the VICAR and PDS formatted Mars Pathfinder IMP Experiment Data Records. This is the ASCII text version of the document required by PDS." END_OBJECT = ASCII_DOCUMENT OBJECT = WORD_DOCUMENT DOCUMENT_NAME = "Mars Pathfinder Imager Experiment Data Record" PUBLICATION_DATE = 1998-06-30 DOCUMENT_TOPIC_TYPE = "DATA PRODUCT SIS" INTERCHANGE_FORMAT = BINARY DOCUMENT_FORMAT = "MICROSOFT WORD" DESCRIPTION = "This document contains a textual description of the VICAR and PDS formatted Mars Pathfinder IMP Experiment Data Records. The document was created using Microsoft Word 6.0.1 for the Macintosh." END_OBJECT = WORD_DOCUMENT END 9.3.3 Complex Example of Detached Label (Documents Plus Graphics) The following label (EDRSIS.LBL) illustrates the use of an HTML document as the required ASCII document. The same document is also included as a PDF file, and four PNG images are included separately. PDS_VERSION_ID = PDS3 RECORD_TYPE = UNDEFINED ^HTML_DOCUMENT = "EDRSIS.HTM" ^PDF_DOCUMENT = "EDRSIS.PDF" ^PNG_DOCUMENT = ("FIG1.PNG","FIG2.PNG","TAB1.PNG","TAB2.PNG") OBJECT = HTML_DOCUMENT DOCUMENT_NAME = "Mars Pathfinder Imager Experiment Data Record" PUBLICATION_DATE = 1998-06-30 DOCUMENT_TOPIC_TYPE = "DATA PRODUCT SIS" INTERCHANGE_FORMAT = ASCII DOCUMENT_FORMAT = HTML DESCRIPTION = "This document contains a description of the VICAR and PDS formatted Mars Pathfinder IMP Experiment Data Records. This is an HTML version of the document." Chapter 9. Documents 9-7 END_OBJECT = HTML_DOCUMENT OBJECT = PDF_DOCUMENT DOCUMENT_NAME = "Mars Pathfinder Imager Experiment Data Record" PUBLICATION_DATE = 1998-06-30 DOCUMENT_TOPIC_TYPE = "DATA PRODUCT SIS" ENCODING_TYPE = "PDS-ADOBE-1.1" INTERCHANGE_FORMAT = BINARY DOCUMENT_FORMAT = "ADOBE PDF" DESCRIPTION = "This document contains a description of the VICAR and PDS formatted Mars Pathfinder IMP Experiment Data Records. This is a PDF version of the document." END_OBJECT = PDF_DOCUMENT OBJECT = PNG_DOCUMENT DOCUMENT_NAME = "Mars Pathfinder Imager Experiment Data Record" PUBLICATION_DATE = 1998-06-30 DOCUMENT_TOPIC_TYPE = "DATA PRODUCT SIS" FILES = 4 ENCODING_TYPE = "PNG1.0" INTERCHANGE_FORMAT = BINARY DOCUMENT_FORMAT = PNG DESCRIPTION = "This document is a PNG representation of two figures and two tables from the Mars Pathfinder IMP Experiment Data Record SIS." END_OBJECT = PNG_DOCUMENT END 9-8 Chapter 9. Documents AAREADME.TXT, 9-2 ASCII files containing markup, 9-4 format, 9-3 DOCINFO.TXT, 9-2 DOCUMENT, 9-2 DOCUMENT objects, 9-2 documentation, 9-1 ASCII file format, 9-3 criteria for inclusion, 9-1 example attached TEXT, 9-5 detached, 9-5 with graphics, 9-6 format, 9-1 HTML, 9-1, 9-4 labels for, 9-2 markup files, 9-4 non-ASCII files, 9-5 required ASCII format, 9-1 TeX/LaTeX, 9-1 validation, 9-5 ENCODING_TYPE, 9-5 extensions table of, 9-3 TEXT, 9-2 TEXT objects, 9-2 Chapter 10. File Specification and Naming 10-1 Chapter 10. File Specification and Naming The File Specification and Naming standard defines the PDS conventions for forming file specifications and names. This chapter is based on levels 1 and 2 of the international standard ISO 9660, "Information Processing - Volume and File Structure of CD-ROM for Information Interchange." ISO 9660 Level 1 versus ISO 9660 Level 2 PDS recommends that archive products adhere to the ISO 9660 Level 1 specification. Specifically, CD-ROM volumes that are expected to be widely distributed should use file identifiers consisting of a maximum of eight characters in the base name and three characters in the extension (i.e., "8.3" file names). When there are compelling reasons to relax the 8.3 file name standard, the IS O 9660 Level 2 specification with respect to file names only may be used, subject to the restrictions listed in Section 10.1.2. 10.1 File Specification Standards A file specification consists of the following elements: 1. A complete directory path name (as discussed in the Directory Types and Naming chapter of this document) 2. A file name (including extension) The PDS has adopted the UNIX/POSIX forward slash character (/) as the directory separator for use in path names. Dir ectory path name formation is discussed further in the Directory Types and Naming chapter of this document. The following is an example of a simple file specification. The file specification identifies the location of the file relative to the root of a volume, including the directory path name. File Name: TG15N122.IMG File Specification: TG15NXXX/TG15N1XX/TG15N12X/TG15N122.IMG Do not use path or file names that correspond to operating system specific names, such as: AUX COM1 CON LPT1 NUL PRN 10-2 Chapter 10. File Specification and Naming 10.1.1 ISO 9660 Level 1 Specification A file name consists of a base name and an extension, separated by a full stop character ("."). Under ISO 9660 Level 1, the length of the base name may not exceed eight characters and the extension may not exceed three characters. In addition, a version number consisting of a semicolon and an integer must follow the file identifier. The base name and extension may only contain characters from the following set: the upper case alphanumeric characters (A - Z, 0-9) and the underscore ("_"). Collectively, these requirements are often referred to as the "8.3 " ("8 dot 3") file naming convention. These limitations exist primarily to accommodate older computer systems that cannot handle longer file names. Since PDS archive volumes are designed to be read on many platforms, including PCs, these restrictions are necessary. Preferred format: BASENAME (1..8 characters) "." EXTENSION (3 characters) Allowable format: BASENAME (1..8 characters) "." EXTENSION (1..3 characters) Actual format on archive medium: BASENAME (1..8 characters) "." EXTENSION (1..3 characters) ";1" 10.1.2 ISO 9660 Level 2 Specification The PDS use of ISO 9660 Level 2 file names adheres to all the above restrictions, with one exception: the base name may be up to 27 characters long (total file name length not to exceed 31 characters). Thus, this format is sometimes referred to as the "27.3 " format. Note: In rare cases the following variations are allowed on the 27.3 format file name: ?? The file name portion may be up to 29 characters long; or ?? The extension may be up to 29 characters long. In no case, however, may the total file name length, including the ".", exceed 31 characters. Preferred format: BASENAME (1..27 characters) "." EXTENSION (3 characters) Allowable format: BASENAME (1..29 characters) "." EXTENSION (1..29 characters) Actual format on archive medium: BASENAME (1..29 characters) "." EXTENSION (1..29 characters) ";1" Note that only the file name specification for Level 2 may be used in PDS archive volumes. All other Level 2 extensions are prohibited. Chapter 10. File Specification and Naming 10-3 10.2 Reserved Directory Names, File Names and Extensions A number of file names, directory names and file extensions are reserved for files that are required in PDS archive volumes under various circumstances. These reserved names and extensions are listed in the following sections for easy reference. For details concerning what directories and files are required where and when, see the indicated chapter. 10.2.1 Reserved Directory Names The following directory names are reserved. The contents of these directories are described in Chapter 19, Volume Organization and Naming. BROWSE CALIB CATALOG DATA DOCUMENT EXTRAS GAZETTER GEOMETRY INDEX LABEL SOFTWARE 10.2.2 Reserved File Names The following file names are reserved. Not all of them are required in all cases. For a complete description of what files are required where and when, see Chapter 19, Volume Organization and Naming. AAREADME.TXT GAZINFO.TXT PERSON.CAT BROWINFO.TXT GEOMINFO.TXT REF.CAT CALINFO.TXT INDEX.TAB SGIINFO.TXT CATALOG.CAT INDXINFO.TXT SOFTINFO.TXT CATINFO.TXT INST.CAT SUNINFO.TXT CUMINDEX.TAB INSTHOST.CAT VOLDESC.CAT DATASET.CAT LABINFO.TXT VOLDESC.SFD DOCINFO.TXT MACINFO.TXT VOLINFO.TXT ERRATA.TXT MISSION.CAT ZIPINFO.TXT EXTRINFO.TXT PCINFO.TXT 10.2.3 Reserved Extensions The following file extensions are reserved. A brief description is provided in the table below. Additional detail is contained in Chapter 19, Volume Organization and Naming, and Chapter 9, Documentation Standard. 10-4 Chapter 10. File Specification and Naming Extension Description (use with files of this type) ASC Plain ASCII documentation files BC SPICE Binary format CK (pointing) files BSP SPICE Binary format SPK (ephemeris) files CAT Catalog object(s) DAT Binary files (other than images) DLL Dynamic Link Library DOC Microsoft Word document EPS Encapsulated Postscript EXE Application or Executable FMT Include file for describing data object (meta data) GIF GIF image HTM or HTML HTML document IBG Browse image data IMG Image data IMQ Image data that have been compressed JPG JPEG image LBL Detached label for describing data object LIB Library of object files MAK Makefile for compiling / linking application or executable OBJ Object file PDF Adobe PDF document PNG Portable Network Graphics PS Postscript QUB Spectral (or other) image QUBEs RTF Rich Text document TAB Tabular data, including ASCII TABLE objects with detached labels TEX TeX or LaTeX document TI SPICE Text IK (instrument parameters) files TIF or TIFF Tagged Image File Format documents TLS SPICE Leap seconds kernel files TPC SPICE Physical and cartographic constants kernel files TSC SPICE Spacecraft clock coefficients kernel files TXT Plain text documentation files XC SPICE Transfer format CK (pointing) files XES SPICE E-kernel files XSP SPICE Transfer format SPK (ephemeris) files ZIP Zip-compressed files within PDS Table 10.1 ­ Reserved File Extensions Chapter 10. File Specification and Naming 10-5 10.3 Guidelines for Naming Sequential Files In cases where file names are constructed from a time tag or sequential data object identifier, the following forms are suggested (but not required): Pnnnnnnn.EXT where ".EXT" is the file extension (see above) and P is a character indicating: C nnnnnnn is a clock count value (e.g., "C3345678.IMG") T nnnnnnn is a time value (e.g., "T87031 5.TAB") F nnnnnnn is a frame ID or an image ID (e.g., "F242AO3.IMG") N nnnnnnn is a numeric file identification number (e.g., "N003.TAB") 10-6 Chapter 10. File Specification and Naming directories reserved names, 10-3 file extensions reserved extensions, 10-3 file names, 10-1 27.3 convention, 10-2 8.3 convention, 10-2 ISO 9660 Level 1, 10-2 ISO 9660 Level 2, 10-2 reserved extensions, 10-3 reserved names, 10-3 sequential file names, 10-5 syntax, 10-2 file specification definition, 10-1 example, 10-1 ISO 9660 Level 1 file names, 10-2 Level 2 file names, 10-2 Chapter 11. Media Formats for Data Submission and Archiv e 11-1 Chapter 11. Media Formats for Data Submission and Archive This standard identifies the physical media formats to be used for data submission or delivery to the PDS or its science nodes. The PDS expects flight projects to deliver all archive products on magnetic or optical media. Electronic delivery of modest volumes of special science data products may be negotiated with the science nodes. Archive Planning - During archive planning, the data producer and PDS will determine the medium (or media) to use for data submission and archiving. This standard lists the media that are most commonly used for submitting data to and subsequently archiving data with the PDS. Delivery of data on media other than those listed here may be negotiated with the PDS on a case- by-case basis. Physical Media for Archive - For archival products only media that conform to the appropriate International Standards Organization (ISO) standard for physical and logical recording formats may be used. 1. The preferred data delivery medium is the Compact Disk (CD-ROM or CD-Recordable) produced in ISO 9660 format, using Interchange L evel 1, subject to the restrictions listed in Section 10.1.1. 2. Compact Disks may be produced in ISO 9660 format using Interchange Level 2, subject to the restrictions listed in Section 10.1.2. 3. Digital Versatile Disk (DVD-ROM or DVD-R) should be produced in UDF-Bridge format (Universal Disc Format) with ISO 9660 Level 1 or Level 2 compatibility. Because of hardware compatibility and long-term stability issues, the use of 12-inch Write Once Read Many (WORM) disk, 8-mm Exabyte tape, 4-mm DAT tape, Bernoulli Disks, Zip disks, Syquest disks and Jaz disks is not recommended for archival use. WORM disk formats are proprietary to the specific vender hardware. Helical scan tape (8-mm or 4-mm) is prone to catastrophic read errors. Bernoulli, Zip, Jaz, Syquest and other vendor -specific storage media are prone to obsolescence. 11.1 CD-ROM Recommendations 11.1.1 Use of Variant Formats The use of Extended Attribute Records (XARs), Rock Ridge Extensions or Macintosh Hybrid Disk Extensions on archival CD-ROMs is discouraged because these extensions can cause errors with CD-ROM drivers on some systems. 11-2 Chapter 11. Media Formats for Data Submission and Archive 11.1.2 Premastering Recommendation PDS recommends that CD-ROMs be premastered using a single-session, single-track format. Other formats have been found to be incompatible with some readers. 11.2 DVD Recommendations 11.2.1 Use of Variant Formats The official volume structure for DVD media is UDF. DVD volumes should not be produced using ISO 9660 only. While current operating systems support ISO 9660 on DVD volumes, there is no guarantee that future operatin g system upgrades, set-top boxes or other new devices will continue to support ISO 9660 formatted DVD volumes. 11.2.2 Premastering Recommendation PDS recommends that DVD-ROMs or DVD-Rs be premastered using a single-session, single- track format using the UDF-Bridge format. 11.2.3 Recommended DVD Formats There are currently three "variants" of DVD media: ?? DVD-5 - single sided, single layer (4.7 GB) ?? DVD-9 - single sided, double layer (8.5 GB) ?? DVD-10 - double sided, single layer (9.4 GB) Currently, only the DVD-5 is approved by the PDS for archiving data. A waiver may be obtained for using the DVD-9 format if the archive consists of very large quantities of data (e.g., cost considerations may warrant using this format). The DVD-10 format is not recommended. 11.3 Packaging Software Files on a CD or DVD The ISO 9660 Level 1 standard requires all pathnames and directory names to be in uppercase, and to be limited to eight characters with a three -character file extension for file names. In some cases it may be desirable to include software packages on an ISO 9660 Level 1 archive product that do not conform to these naming standards. The recommended method for packaging software is to use a "Zip" utility in accordance with the PDS standards for archiving data using Zip compression. See the Zip Compression chapter for more information. 11.4 Software Packaging Under Previous Versions of the Standard Under previous versions of the Standards ­ prior to the adoption of the Zip standard (see the Zip Compression chapter ) ­ archive products that included software specifically intended for the Chapter 11. Media Formats for Data Submission and Archiv e 11-3 Mac and SUN operating systems used the following conventions: 1. Mac Software In this case the Mac files must be prepared in a particular format, as other platforms do not recognize the resource and data fork files that come with Mac applications. (For an example of properly formatted Mac software, see the NIHIMAGE software on the Magellan GxDR and Clementine EDR CD-ROMs.) The Mac utility "STUFFIT" is used to prepare the files by compressing them and encoding them using the BINHEX utility. Users will also need this STUFFIT utility in order to unpack the software for use. The procedure and software requirements should be described in a text file included on the CD-ROM (in the appropriate SOFTWARE/DOCUMENT subdirectory ­ see the Volume Organization and Naming chapter in this document). Example ­ Text Documenting HQX Files Macintosh Software This directory contains software that can be used to display the GXDR images on a Macintosh II computer with an 8-bit color display. NOTE: Because of the way this CD-ROM was produced, it was not possible to record this display program as a Macintosh executable file. Anyone who is unfamiliar with the Macintosh STUFFIT utility should contact the PDS operator, 818-306-6026, SPAN address JPLPDS::PDS_OPERATOR, INTERNET address PDS_OPERATOR@JPLPDS.JPL.NASA.GOV The file IMAGE.HQX contains the NIH Image program, along with several ancillary files and documentation in Microsoft WORD format. It was written by Wayne Rasband of the National Institutes of Health. The program can be used to display any of the image files on the GXDR CD-ROM disks. The Image executable and manual are stored in BINHEX format, and the utility STUFFIT or UNSTUFFIT must be used to: 1) decode the BINHEX file IMAGE.HQX into IMAGE.SIT, using the 'DECODE BINHEX FILE...' option in the Other menu; and 2) use 'OPEN ARCHIVE' from the File menu to extract Image 1.40 from the STUFFIT archive file. There are also several other files in the archive file which should be unstuffed and kept together in the same folder as the Image executable is stored. The STUFFIT software is distributed as shareware. STUFFIT, Version 1.5.1, is available by contacting: Raymond Lau MacNET:RayLau Usenet:raylau@dasys1.UUCP 100-04 70 Ave. GEnie:RayLau Forest Hills, N.Y. 11375-5133 CIS:76174,2617 United States of America. Delphi:RaymondLau Alternatively, STUFFIT CLASSIC, Version 1.6, is available by contacting: Aladdin Systems, Inc. Deer Park Center Suite 23A-171 Aptos, CA 95003 United States of America 11-4 Chapter 11. Media Formats for Data Submission and Archive 2. SUN Software The problem in this case is preserving the SUN file names, since case is significant in file names on that platform. Since the ISO standard requires all file and directory names to be uppercase, a disk premastered as an ISO CD may encounter problems in the case- sensitive SUN environment. Specifically, some CD readers mounted on SUN systems show file names as uppercase regardless of the format prior to mastering. If build routines ("make" files, for example) refer to lowercase file names, the corresponding files will not be found. A method for dealing with this situation is to store the entire original directory structure and contents in a compressed, encoded archive (a compressed "tar " file, for example), and document the procedures and utilities needed to restore the files in the ap propriate file. This is equivalent to the STUFFIT approach described above for Mac software. Chapter 11. Media Formats for Data Submission and Archiv e 11-5 B Bernoulli Disks delivery medium ................................ ................................ ................................ ................ 11-1 BINHEX utility................................ ................................ ................................ ...................... 11-3 C CD-Recordable delivery medium ................................ ................................ ................................ ................ 11-1 CD-ROM delivery medium ................................ ................................ ................................ ................ 11-1 formatting recommendations ................................ ................................ .............................. 11-2 premastering ................................ ................................ ................................ ...................... 11-2 D DAT tape delivery medium ................................ ................................ ................................ ................ 11-1 data delivery media ................................ ................................ ................................ ................................ .11-1 data submission................................ ................................ ................................ ...................... 11-1 delivery media ................................ ................................ ................................ ....................... 11-1 DVD media archive format................................ ................................ ................................ .................... 11-2 DVD-R delivery medium ................................ ................................ ................................ ................ 11-1 DVD-ROM delivery medium ................................ ................................ ................................ ................ 11-1 formatting recommendations................................ ................................ .............................. 11-2 premastering ................................ ................................ ................................ ...................... 11-2 UDF................................ ................................ ................................ ................................ ...11-2 E Exabyte tape delivery medium ................................ ................................ ................................ ................ 11-1 Extended Attribute Records (XARs) on delivery disks................................ ................................ ................................ ................ 11-2 J Jaz disks delivery medium ................................ ................................ ................................ ................ 11-1 11-2 Chapter 11. Media Formats for Data Submission and Archive P physical media formats ................................ ................................ ................................ ..........11-1 S software packaging for delivery................................ ................................ ................................ ........11-3 STUFFIT utility................................ ................................ ................................ ..................... 11-3 Syquest disks delivery medium ................................ ................................ ................................ ................ 11-1 T tar utility ................................ ................................ ................................ ................................ 11-4 W WORM disk delivery medium ................................ ................................ ................................ ................ 11-1 Z Zip disks delivery medium ................................ ................................ ................................ ................ 11-1 Chapter 12. Object Description Language Specification and Usage 12-1 Chapter 12. Object Description Language Specification and Usage The following provides a complete specification for Object Description Language (ODL), the language used to encode data labels for the Planetary Data System (PDS) and other NASA data systems. This standard contains a formal definition of the grammar semantics of the language. PDS specific implementation notes and standards are referenced in separate sections. 12.1 About the ODL Specification This standard describes Version 2.1 of ODL. Version 2.1 of ODL supersedes Versions 0 and 1 of the language, which were used previously by the PDS and other groups. For the most part, ODL Version 2.1 is backwardly compatible with previous versions of ODL. There are, however, some features found in ODL Versions 0 and 1 that have been removed from or changed within Version 2. The differences between ODL versions are described in Section 12.7. Following is a sample ODL data label describing a file and its contents: /* File Format and Length */ RECORD_TYPE = FIXED_LENGTH RECORD_BYTES = 800 FILE_RECORDS = 860 /* Pointer to First Record of Major Objects in File */ ^IMAGE = 40 ^IMAGE_HISTOGRAM = 840 ^ANCILLARY_TABLE = 842 /* Image Description */ SPACECRAFT_NAME = VOYAGER_2 TARGET_NAME = IO IMAGE_ID = "0514J2-00" IMAGE_TIME = 1979-07-08T05:19:11Z INSTRUMENT_NAME = NARROW_ANGLE_CAMERA EXPOSURE_DURATION = 1.9200 NOTE = "Routine multispectral longitude coverage, 1 of 7 frames" /* Description of the Objects Contained in the File */ OBJECT = IMAGE LINES = 800 LINE_SAMPLES = 800 SAMPLE_TYPE = UNSIGNED_INTEGER SAMPLE_BITS = 8 END_OBJECT = IMAGE OBJECT = IMAGE_HISTOGRAM ITEMS = 25 ITEM_TYPE = INTEGER ITEM_BITS = 32 END_OBJECT = IMAGE_HISTOGRAM OBJECT = ANCILLARY_TABLE ^STRUCTURE = "TABLE.FMT" END_OBJECT = ANCILLARY_TABLE END 12-2 Chapter 12. Object Description Language Specification and Usage 12.1.1 Implementing ODL Notes to implementers of software to read and write ODL-encoded data descriptions appear throughout the following sections. These notes deal with issues beyond language syntax and semantics, but are addressed to assure that software for reading and writing ODL will be uniform. The PDS, which is the major user of ODL-encoded data labels, has imposed additional implementation requirements for software used within the PDS. These PDS requirements are discussed below where appropriate. 12.1.1.1 Language Subsets Implementers are allowed to develop software to read or write subsets of the ODL. Specifically, software developers may opt to: ?? Eliminate support for the GROUP statement (see Section 12.4.5.2 for additional information) ?? Not support pointer statements ?? Not support certain types of data values For every syntactic element supported by an implementation, the corresponding semantics, as spelled out in this chapter, must be fully supported. Software developers should be careful to assure that language features will not be needed for their particular applications before eliminating them. Documentation on label reading/writing software should clearly indicate whether or not the software supports the entire ODL specification and, if not, should clearly indicate the features not supported. 12.1.1.2 Language Supersets Software for writing ODL must not provide or allow lexical or syntactic elements over and above those described below. With the exception of the PVL-specific extensions below, software for reading ODL must not provide or allow any extensions to the language. 12.1.1.3 PDS Implementation of PVL-Specific Extensions PDS implementation of software for reading ODL may, in some cases, provide handling of lexical elements that are included in the CCSDS specification of the Parameter Value Language (PVL), which is a superset of ODL. Extensions handled by such software include: ?? BEGIN_OBJECT as a synonym for the reserved word OBJECT ?? BEGIN_GROUP as a synonym for the reserved word GROUP ?? Use of the semicolon (;) as a statement terminator These lexical elements are not supported by software that writes the ODL subset. They must either be removed (in the case of semicolons) or replaced (in the case of the BEGIN_OBJECT and BEGIN_GROUP synonyms) upon output. Chapter 12. Object Description Language Specification and Usage 12-3 12.1.2 Notation The formal description of the ODL grammar is given below in Backus-Naur Form (BNF). Language elements are defined using rules of the following form: defined_element ::= definition where the definition is composed from the following components: 1. Lower case words, some containing underscores, are used to denote syntactic categories. For example: units_expression Whenever the name of a syntactic category is used outside of the formal BNF specification, spaces take the place of underscores (for example, units expression). 2. Boldface type is used to denote reserved identifiers. For example: object Special characters used as syntactic elements also appear in boldface type. 3. Square brackets enclose optional elements. Elements within brackets occur zero or one times. 4. Square brackets followed immediately by an asterisk or plus sign specify repeated elements. In the case of an asterisk, the elements in brackets may appear zero, one, or more times. In the case of a plus sign, the elements in brackets must appear at least once. The repetitions occur from left to right. 5. A vertical bar separates alternative elements. 6. If the name of any syntactic category starts with an italicized part, it is equivalent to the category name without the italicized part. The italicized part is intended to convey some semantic information. For example, both object_identifier and units_identifier are equivalent to identifier; object_identifier is used in places where the name of an object is required and units_identifier is used where the name of some unit of measurement is expected. 12.2 Character Set The character set of ODL is the International Standards Organ ization's ISO 646 character set. The U.S. version of the ISO 646 character set is ASCII; the ASCII graphical symbols are used throughout this document. In other countries certain symbols have a different graphical representation. 12-4 Chapter 12. Object Description Language Specification and Usage The ODL character set is partitioned into letters, digits, special characters, spacing characters, format effectors and other characters: character :: = letter | digit | special_character | spacing_character | format_effector | other_character 12.2.1 ODL Character Set - Letters The letters are the uppercase letters A - Z and the lowercase letters a - z. ODL language elements are not case sensitive. Thus the following identifiers are equivalent: ?? IMAGE_NUMBER ?? Image_Number ?? image_number Case is significant inside of literal text strings, i.e., string "abc" is not the same as the string "ABC". 12.2.2 ODL Character Set - Digits The digits are 0, 1, 2, 3, 4, 5, 6, 7, 8, 9. 12.2.3 ODL Character Set ­ Special Characters The special characters used in ODL are: Symbol Name Usage = Equals The equals sign equates an attribute or pointer to a value. { } Braces Braces enclose an unordered set of values. ( ) Parentheses Parentheses enclose an ordered sequence of values. + Plus The plus sign indicates a positive numeric value. - Minus The minus sign indicates a negative numeric value. < > Angle brackets Angle brackets enclose a units expression associated with a numeric value. . Period The period is the decimal place in real numbers. " Quotation Marks Quotation marks denote the beginning and end of a text str ing value. Case is significant within the quotes of a text string. ' Apostrophe Apostrophes mark the beginning and end of a symbol value. Case is not significant within delimiting apostrophes (a.k.a. "single quotes"). Chapter 12. Object Description Language Specification and Usage 12-5 _ Underscore The underscore separates words within an identifier. , Comma The comma separates individual values in a set or sequence. / Slant The slant character indicates division in units expressions. The slant is also part of the comment delimiter. * Asterisk The asterisk indicates multipl ication in units expressions. Two asterisks in a row indicate exponentiation in units expressions. The asterisk is also part of the comment delimiter. : Colon The colon separates hours, minutes and seconds within a time value. # Crosshatch Also known as "the pound sign", this symbol delimits the digits in an integer number value expressed in notation other than base-10. & Ampersand The ampersand denotes continuation of a statement onto another line. ^ Circumflex The circumflex (or caret) indicates that a value is to be interpreted as a pointer. 12.2.4 ODL Character Set ­ Spacing Characters Two characters, called the spacing characters, separate lexical elements of the language and can be used to format characters on a line: Space Horizontal Tabulation 12.2.5 ODL Character Set ­ Format Effectors The following ISO characters are format effectors, used to separate ODL encoded statements into lines: Carriage Return Line Feed Form Feed Vertical Tabulation The spacing characters and format effectors are discussed further in section 12.4.1 below. There are other characters in the ISO 646 character set that are not required to write ODL statements and labels. These characters may, however, appear within text strings and quoted symbolic literals: ! $ % ; ? @ [ ] | ~ 12-6 Chapter 12. Object Description Language Specification and Usage 12.2.6 ODL Character Set ­ Control Characters The category of other characters also includes the ASCII control characters except for horizontal tabulation, carriage return, line feed, form feed and vertical tabulation (e.g., the control characters that serve as spacing characters or format effectors). As with the printing characters in this category, the control characters in this category can appear within a text string. The handling of control characters within text strings and symbolic literals is discussed in Section 12.3.3 below. 12.3 Lexical Elements This section describes the lexical elements of ODL. Lexical elements are the basic building blocks of the ODL. Statements in the language are composed by stringing lexical elements together according to the grammatical rules presented in Section 12.4. The lexical elements of ODL are: ?? Numbers ?? Dates and Times ?? Strings ?? Identifiers ?? Special symbols used for operators, etc. There is no inherent limit on the length of any lexical element. However, software for reading and writing ODL may impose limitations on the length of text strings, symbol strings and identifiers. It is recommended that at least 32 characters be allowed for symbol strings and identifiers and at least 400 characters for text strings. 12.3.1 Numbers ODL can represent both integer numbers and real numbers. Integer numbers are usually represented in decimal notation ("123"), but ODL also provides for integer values in other number bases (for example, "2#1111011#" is the binary representation of the decimal integer "123"). Real numbers can be represented in simple decimal notation ("123.4") or in scientific notation (i.e., with a base 10 exponent: "1.234E2"). 12.3.1.1 Integer Numbers In Decimal Notation An integer number in decimal notation consists of a string of digits optionally preceded by a number sign. A number without an explicit sign is always taken as positive. integer :: = [sign] unsigned_integer unsigned_integer :: = [digit] + sign ::= + | - Chapter 12. Object Description Language Specification and Usage 12-7 Examples ­ Decimal Integers 0 123 +440 -150000 12.3.1.2 Integer Numbers In Based Notation An integer number in based notation specifies the number base explicitly. The number base must be in the range 2 to 16, which allows for representations in the most popular number bases, including binary (base 2), octal (base 8) and hexadecimal (base 16). In general, for a number base X the digits 0 to X-1 are used. For example, in octal (base 8) the digits 0 to 7 are allowed. If X is greater than 10, then the letters A, B, C, D, E, F (or their lower case counterparts) are used as needed for the additional digits. A based integer may optionally include a number sign. A number without an explicit sign is always taken as positive. based_integer :: = radix # [sign] [extended_digit] + # extended_digit :: = digit | letter radix :: = unsigned_integer Examples ­ Based Integers 2#1001011# 8#113# 10#75# 16#4B# 16#+4B# 16#-4B# All but the last example above are equivalent to the decimal integer number 75. The final example is the hexadecimal representation of -75 decimal. 12.3.1.3 Real Numbers Real numbers may be represented in floating-point notation ("123.4") or in scientific notation with a base 10 exponent ("1.234E2"). A real number may optionally include a sign. Unsigned numbers are always taken as positive. real :: = [sign] unscaled_real | [sign] scaled_rea l unscaled_real :: = unsigned_integer. [unsigned_integer] | .unsigned_integer scaled_real :: = unscaled_real exponent exponent :: = E integer | e integer 12-8 Chapter 12. Object Description Language Specification and Usage Note that the letter `E' in the exponent of a real number may appear in either upper or lower case. Examples ­ Real Numbers 0.0 123. +1234.56 -.9981 -1.E-3 31459e1 12.3.2 Dates and Times ODL includes lexical elements for representing dates and times. The formats for dates and times are a subset of the formats defined by the International Standards Organization draft standard ISO/DIS 8601. (For information regarding PDS specific use of dates and times, see the Date/Time chapter in this document.) 12.3.2.1 Date and Time Values Date and time scalar values represent a date, a time, or a combination of date and time: date_time_value :: = date | time | date_time The following rules apply to date values: ?? The year must be Anno Domini. PDS requires a 4-digit year format be used (i.e., "2000", not "00 "). ?? Month must be a number between 1 and 12. ?? Day of month must be a number in the range 1 to 31, as appropriate for the particular month and year. ?? Day of year must be in the range 1 to 365, or 366 in a leap year. The following rules apply to time values: ?? Hours must be in the range 0 to 23. ?? Minutes must be in the range 0 to 59. ?? Seconds, if specified, must be greater than or equal to 0 and less than 60. The following rules apply to zone offsets within zoned time values: ?? Hours must be in the range -12 to + 12 (the sign is mandatory). ?? Minutes, if specified, must be in the range 0 to 59. Chapter 12. Object Description Language Specification and Usage 12-9 12.3.2.2 Implementation of Dates and Times All ODL reading/writing software shall be able to handle any date within the 20th and 21st centuries. Software for writing ODL must always output full four-digit year numbers so that labels will be valid across century boundaries. Times in ODL may be specified with unlimited precision, but the actual precision with which times will be handled by label reading/writing software is determined by the software implementers, based upon limitations of the hardware on which the software is implemented. Developers of label reading/writing software should document the precision to which times can be represented. Software for writing ODL must not output local time values, since a label may be read in a time zone other than where it was written. Use either the UTC or zoned time format instead. 12.3.2.3 PDS Implementation of Dates and Times PDS software for reading ODL labels interprets label times as UTC times. On output, a "Z" will be appended to label times. 12.3.2.4 Dates Dates can be represented in two formats: as year and day of year; or as year, month and day of month. date :: = year_doy | year_month_day year_doy :: = year-doy year_month_day :: = year-month-day year :: = unsigned_integer month :: = unsigned_integer day :: = unsigned_integer doy :: = unsigned_integer Examples ­ Dates 1990-07-04 1990-158 2001-001 12.3.2.5 Times Times are represented as hours, minutes and (optionally) seconds using a 24 -hour clock. Times may be specified in Universal Time Coordinated (UTC) by following the time with the letter Z (for Zulu, a common designator for Greenwich Mean Time). Alternately, the time may be referenced to any time zone by following the time with a number that specifies the offset from UTC. Most time zones are an integral number of hours from Greenwich, but some are different by some non-integral time; both can be represented in the ODL. A time that is not followed by 12-10 Chapter 12. Object Description Language Specification and Usage either the Zulu indicator or a time zone offset is assumed to be a local time. time :: = local_time | utc_time | zoned_time local time :: = hour_min_sec utc_time :: = hour_min_sec Z zoned_time :: = hour_min_sec zone_offset hour_min_sec :: = hour: minute [:second] zone_offset :: = sign hour [: minute] hour :: = unsigned_integer minute :: = unsigned_integer second :: = unsigned_integer | unscaled_real Note that either an integral or a fractional number of seconds can be specified in a time value. Examples ­ Times 12:00 15:24:12Z 01:10:39.4575+07 (time offset of 7 hours from UTC) 12.3.2.5.1 Combining Date and Time A date and time can be specified together using the format below. Either of the two date formats can be combined with any time format - UTC, zoned or local. date_time::=date T time The letter T separating the date from the time may be specified in either upper or lower case. Note that, because this is a lexical element, spaces may not appear within a date, within a time or before or after the letter T. Examples ­ Date/Times 1990-07-04T12:00 1990-158T15:24:12Z 2001-001T01:10:39.457591+7 12.3.3 Strings There are two kinds of string elements in ODL: text strings and symbol strings. 12.3.3.1 Text Strings Text strings are used to hold arbitrary strings of characters. Chapter 12. Object Description Language Specification and Usage 12-11 quoted_text ::= "[character]*" The empty string - a quoted text string with no characters within the delimiters - is allowed. A quoted text string may not contain the quotation mark, which is reserved to be the text string delimiter. A quoted text string may contain format effectors, hence it may span multiple lines in a label: the lexical element begins with the opening quotation mark and extends to the closing quotation mark, even if the closing mark is on a following line. The rules for interpreting the characters within a text string, including format effectors, are given in the subsection on string values in Section 12.5.3. 12.3.3.2 Symbol Strings Symbol strings are sequences of characters used to represent symbolic values. For example, an image ID may be a symbol string like `J123 -U2A', or a camera filter might be a symbol string like `UV1'. quoted_symbol ::= `[character]+' A symbol string may not contain any of the following characters: ?? The apostrophe, which is reserved to be the symbol string delimiter ?? Format effectors, which means that a symbol string must fit on a single line ?? Control characters 12.3.4 Identifiers Identifiers are used as the names of objects, attributes and units of measurement. They can also appear as the value of a symbolic literal. Identifiers are composed of letters, digits, and underscores. Underscores are used to separate words in an identifier. The first character of an identifier must be a letter. The last character may not be an underscore. identifier : : = letter [letter | digit | _letter | _digit]* Because ODL is not case sensitive, lower case characters in an identifier can be converted to their upper case equivalent upon input to simplify comparisons and parsing. Examples ­ Identifiers VOYAGER VOYAGER_2 BLUE_FILTER USA_NASA_PDS_1_0007 SHOT_1_RANGE_TO_SURFACE 12-12 Chapter 12. Object Description Language Specification and Usage 12.3.4.1 Reserved Identifiers A few identifiers have special significance in ODL statements and are therefore reserved. They cannot be used for any other purpose (specifically, they may not be used to name objects or attributes): end end_group end_object group object begin_object 12.3.5 Special Characters ODL is a simple language and it is usually clear where one lexical element ends and another begins. Spacing characters or format effectors may appear before a lexical element, between any pair of lexical elements, or after a lexical element without changing the meaning of a statement. Some lexical elements incorporate special characters (e.g., the decimal point in real numbers or the quotation marks that delimit a text string). Some special characters are also lexical elements in their own right. These are: = The equals sign is the assignment operator. , The comma separates the elements of an array or a set. * The asterisk serves as the multiplication operator in units expressions. / The slant serves as the division operator within units expressions. ^ The circumflex denotes a pointer to an object. <> The angle brackets enclose units expressions. () The parentheses enclose the elements of a sequence. { } The braces enclose the elements of a set. The following two-character sequence is also a lexical element. ** Two adjacent asterisks are the exponentiation sign within units expressions. 12.4 Statements An ODL-encoded label is made up of a sequence of zero, one, or more statements followed by the reserve identifier end. label ::= [statement]* end The body of a label is built from four types of statements: Chapter 12. Object Description Language Specification and Usage 12-13 statement :: = attribute_assignment_statement | pointer_statement | object_statement | group_statement Each of the four types of statements is discussed below. 12.4.1 Lines and Records Labels are also typically composed of lines, where each line is a string of characters terminated by a format effector or a string of adjacent format effectors. The following recommendations are given for how software that writes ODL should format a label into lines: ?? There should be at most one statement on a line, although a statement may be more than a single line in length. As noted in Section 12.3.5 above, format effectors may appear before, after or between the lexical elements of a statement without changing the meaning of the statement. For example, the following statements are identical in meaning: FILTER_NAME = {RED, GREEN, BLUE} FILTER_NAME = {RED, GREEN, BLUE} ?? Each line should end with a carriage return character followed immediately by a line feed character. This sequence is an end-of-line signal for most computer operating systems and text editors. ?? The character immediately following the END statement must be either an optional spacing character or format effector, such as a space, line feed, carriage return, etc. A line may include a comment. A comment begins with the two characters "/*" and ends with the two characters "*/". A comment may conta in any character in the ODL character set except format effectors, which are reserved to mark the end of line (i.e., comments may not be more than one line long). Comments are ignored when parsing an ODL label. When the comment delimiters ("/*" and "*/") a ppear within a text string, they are not interpreted as a comment - they are simply part of the text string. For example, in the following example the comment will be included as part of the text string: NOTE = "All good men come to the /* Example of incorrect comment*/ aid of their party" Any characters on a line following a comment are ignored. In some computer systems files are divided into records. Software for writing and reading ODL- encoded labels in record-oriented files should adhere to the following rules: 12-14 Chapter 12. Object Description Language Specification and Usage ?? A line of an ODL-encoded label may not cross a record boundary, i.e., each line should be contained within a single record. Any space left over at the end of a record after the last line in that record should be set to all space characters. ?? The remainder of the record that contains the END statement is ignored. The data portion of the file begins with the next record in sequence. 12.4.2 Attribute Assignment Statement The attribute assignment statement is the most common type of statement in ODL and is used to specify the value for an attribute of an object. The value may be a single scalar value, an ordered sequence of values, or an unordered set of values. assignment_statement ::= attribute_identifier = value The syntax and semantics of values are given in Section 12.5. Examples ­ Assignment Statements RECORD_BYTES = 800 TARGET_NAME = JUPITER SOLAR_LATITUDE = (0.25 , 3.00 ) FILTER_NAME = {RED, GREEN, BLUE} 12.4.3 Pointer Statement The pointer statement indicates the location of an object. pointer_statement :: = ^object_identifier = value As with the attribute assignment statement, the value may be a scalar value, an ordered sequence of values, or an unordered set of values. A common use of pointer statements is to reference a file containing an auxiliary label. For example: ^STRUCTURE = "TABLE.FMT" This is a pointer statement pointing to a file named "TABLE.FMT" that contains a description of the structure of the ancillary table from our sample label. Another use of the pointer statement is to indicate the position of an object within another object. This is often used to indicate the position of major objects within a file. The following examples are from the sample label in Section 12.1: ^IMAGE = 40 Chapter 12. Object Description Language Specification and Usage 12-15 ^IMAGE_HISTOGRAM = 840 ^ANCILLARY_TABLE = 842 The first pointer statement above indicates that the image is located starting at the 40th record from the beginning of the present file. If an integer value is used to indicate the relative position of an object, the units of measurement of position are determined by the nature of the object. For files, the default unit of measurement is records. Alternatively, a units expression can be specified for the integer value to indicate explicitly the units of measurement for the position. For example, this pointer: ^IMAGE = 10200 indicates that the image starts 10,200 bytes from the beginning of the file. The object pointers above reference locations in the same files as the label containing the pointer. Pointers may also reference either byte or record locations in data files that are detached, or separate, from the label file: ^IMAGE = ("IMAGE.DAT", 10) ^HEADER = ("IMAGE.DAT", 512 ) 12.4.4 OBJECT Statement The OBJECT statement begins the description of an object. The description typically consists of a set of attribute assignment statements defining the values of the object's attributes. If an object is itself composed of other objects, then OBJECT statements for the component objects are nested within the object's description. There is no limit to the depth to which OBJECT statements may be nested. The format of the OBJECT statement is: object_statement ::= object = object_identifier [statement ]* end_object [= object_identifier] The object identifier gives a name to the particular object being described. For example, in a file containing images of several planets, the image object descriptions might be named VENUS_IMAGE, JUPITER_IMAGE, etc. The object identifier at the end of the OBJECT statement is optional, but if it appears it must match the name given at the beginning of the OBJECT statement. 12.4.4.1 Implementation of OBJECT Statements It is recommended that all software for writing ODL include the object identifier at the end as well as the beginning of every OBJECT statement. 12-16 Chapter 12. Object Description Language Specification and Usage 12.4.5 GROUP Statement The GROUP statement is used to group together statements that are not components of a larger object. For example, in a file containing many images, the group BEST_IMAGES might contain the object descriptions of the three highest quality images. The three image objects in the BEST_IMAGES group don't form a larger object: all they have in common is their superior quality. The GROUP statement is also used to group related attributes of an object. For example, if two attributes of an image object are the time at which the camera shutter opened and closed, then the two attributes might be grouped as follows: GROUP = SHUTTER_TIMES START = 12:30:42.177 STOP = 14:01:29.265 END_GROUP = SHUTTER_TIMES The format of the group statement is as follows: group_statement ::= group = group_identifier [statement]* end_group [= group_identifier] The group identifier gives a name to the particular group, as shown in the example for shutter times above. The object identifier at the end of the GROUP statement is optional, but if it appears it must match the name given at the beginning of the GROUP statement. Groups may be nested within other groups. There is no limit to the depth to which groups can be nested. 12.4.5.1 Implementation of GROUP Statements It is recommended that all software for writing ODL include the group identifier at the end as well as the beginning of every GROUP statement. 12.4.5.2 PDS Usage of GROUP Although ODL includes the GROUP statement, the PDS does not recommend its use because of confusion concerning the difference between OBJECT and GROUP. 12.5 Values ODL provides scalar values, ordered sequences of values, and unordered sets of values. value :: = scalar_value | sequence_value | set_value A scalar value consists of a single lexical element: Chapter 12. Object Description Language Specification and Usage 12-17 scalar_value :: = numeric_value | date_time_value | text_string_value | symbol_value The format and use of each of these scalar values are discussed in the sections below. 12.5.1 Numeric Values A numeric scalar value is either a decimal or based integer number, or a real number. A numeric scalar value may optionally include a units expression. numeric_value :: = integer [units_expression] | based_integer [units_expression] | real [units_expression] 12.5.2 Units Expressions Many of the values encountered in scientific data are measurements of something. In most computer languages, only the magnitude of a measurement is represented, without the units of measurement. ODL, however, can represent both the magnitude and the units of a measurement. A units expression has the following format: units_expression :: = < units_factor [mult_op units_factor] * > units_factor :: = units_identifier [exp_op integer] mult_op :: = * | / exp_op :: = ** A units expression is always enclosed within angle brackets. The expression may consist of a single units identifier like "KM",for kilometers, or "SEC", for seconds (for example, "1.341E6 " or "1.024 "). More complex units can also be represented; for example, the velocity "3.471 " or the acceleration "0.414 < KM/SEC/SEC>". There is often more than one way to represent a unit of measure. For example: 0.414 0.414 0.414 are all valid representations of the same acceleration. The following rules apply to units expressions: ?? The exponentiation operator can specify only a decimal integer exponent. The exponent value may be negative, which signifies the reciprocal of the units. For example, "60.15 12-18 Chapter 12. Object Description Language Specification and Usage " and "60.15 " are both ways to specify a frequency. ?? Individual units may appear in any order. For example, a force might be specified as either "1.55 " or "1.55 ". 12.5.2.1 Implementation of Numeric Values There is no defined maximum or minimum magnitude or precision for numeric values. In general, the actual range and precision of numbers that can be represented will be different for each kind of computer used to read or write an ODL-encoded label. Developers of software for reading/writing ODL should document the following: ?? The largest magnitude positive and negative integers that can be represented ?? The largest magnitude positive and negative real numbers that can be represented ?? The minimum number of significant digits that a real number can be guaranteed to have without loss of precision. This is to account for the loss of precision that can occur when representing real numbers in floating point format within a computer. For example, a 32 - bit floating-point number with 24 bits for the mantissa can guarantee at most 6 significant digits will be exact (the seventh and subsequent digits may not be exact because of truncation and round-off errors). If software for reading ODL encounters a numeric value too large to be represented, the software must report an error to the user. 12.5.3 Text String Values A text string value consists of a text string lexical element: text_string_value :: = quoted_text 12.5.3.1 Implementation of String Values A text string read in from a label is reassembled into a string of ch aracters. The way in which the string is broken into lines in a label does not affect the format of the string after it has been reassembled. The following rules are used when reading text strings: ?? If a format effector or a sequence of format effectors is encountered within a text string, the effector (or sequence of effectors) is replaced by a single space character, unless the last character is a hyphen (dash) character. Any spacing characters at the end of the line are removed and any spacing characters at the beginning of the following line are removed. This allows a text string in a label to appear with the left and right margins set at arbitrary points without changing the string value. For example, the following two strings are the same: "To be or n ot to be" and Chapter 12. Object Description Language Specification and Usage 12-19 "To be or not to be" ?? If the last character on a line prior to a format effector is a hyphen (dash) character, the hyphen is removed with any spacing characters at the beginning of the following line. This follows the standard convention in English of using a hyphen to break a word across lines. For example, the following two strings are the same: "The planet Jupiter is very big" and "The planet Jupi - ter is very big" ?? Control codes, other than the horizontal tabulation character a nd format effectors, appearing within a text string are removed. 12.5.3.1.1 PDS Text String Formatting Conventions The PDS defines a set of format specifiers that can be used in text strings to indicate the formatting of the string on output. These specifiers can be used to indicate where explicit line breaks should be placed, and so on. The format specifiers are: \n Indicates that an end-of-line sequence should be inserted. \t Indicates that a horizontal tab character should be inserted. \f Indicates that a page break should be inserted. \v Must be used in pairs, begin and end. Interpreted as verbatim. \\ Used to place a backslash in a text string. For example, the string "This is the first line \n and this is the second line." will print as: This is the first line and this is the second line. Note: These format specifiers have meaning only when a text string is printed - not when the string is read in or stored. 12-20 Chapter 12. Object Description Language Specification and Usage 12.5.4 Symbolic Literal Values A symbolic value may be specified as either an identifier or a symbol string: symbolic-value :: = identifier | quoted_symbol The following statements assign attributes to symbolic values specified by identifiers: TARGET_NAME = IO SPACECRAFT_NAME = VOYAGER_2 SPACECRAFT_NAME = 'VOYAGER-2' SPACECRAFT_NAME = 'VOYAGER 2' REFERENCE_KEY_ID = SMITH1997 REFERENCE_KEY_ID = 'LAUREL&HARDY1997' The quotes must be used if the symbolic value does not have the proper format for an identifier or if it contains characters not allowed in an identifier. For example, the value `FILTER_+_7' must be enclosed within quotes, since this would not be a legal ODL identifier. Similarly, the symbolic value `U13-A4B' must be in quotes because it contains a special character (the dash) not allowed in an identifier. There is no harm in putting a legal identifier within quotes. For example: SPACECRAFT_NAME = 'VOYAGER_2' is equivalent to the second example in the list above. Symbolic values may not contain format effectors, i.e., they may not cross a line boundary. 12.5.4.1 Implementation of Symbolic Literal Values Symbolic values are converted to upper case on input. This means that a lowercase string is converted to the equivalent uppercase string; as in the following example: Original string: SPACECRAFT_NAME = 'Voyager_2' Converted string: SPACECRAFT_NAME = 'VOYAGER_2' 12.5.4.2 PDS Convention for Symbolic Literal Values Since the current use of the ODL within the PDS does not require syntactic differentiation between symbols and text strings, PDS prefers that double quotation marks (") be used instead of apostrophes around symbol strings. Chapter 12. Object Description Language Specification and Usage 12-21 12.5.5 Sequences A sequence represents an ordered set of values. It can be used to represent arrays and other kinds of ordered data. Only one- and two-dimensional sequences are allowed. sequence_value :: = sequence_1D | sequence_2D sequence_1D :: = (scalar_value [, scalar_value]*) sequence_2D :: = ([sequence _1D] +) A sequence may have any kind of scalar value for its members. It is not required that all the members of the sequence be of the same type. Thus a sequence may represent a heterogeneous record. Each member of a two-dimensional sequence is a one-dimensional sequence. This can be used, for example, to represent a table of values. The order in which members of a sequence appear must be preserved. There is no upper limit on the number of values in a sequence. For example: AVERAGE_ECCENTRICITY = (0,1,2,3,4,5,9) 12.5.6 Sets Sets are used to specify unordered values drawn from some finite set of values. set_value :: = {scalar_value [, scalar_value]*} | {} Note that the empty set is allowed: The empty set is denoted by opening and closing brackets with nothing except optional spacing characters or format effectors between them. The order in which the members appear in the set is not significant and the order need not be preserved when a set is read and manipulated. There is no upper limit on the number of values in a set. Example FILTER_NAME = { RED, BLUE, GREEN, HAZEL } 12.5.6.1 PDS Restrictions on Sets The PDS allows only symbol values and integer values within sets. 12.6 ODL Summary Character Set (Section 12.2) ODL uses the ISO 646 character set (the American version of the ISO 646 standard is ASCII). 12-22 Chapter 12. Object Description Language Specification and Usage The ODL character set is partitioned as follows: character : : = letter | digit | special_character | spacing_character | format_effector | other_character letter : : = A-Z | a-z digit : : = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8| 9 special_character : : = { | } | ( | ) | + | - | . | " | ' | = | _ | , | / | * | : | # | & | ^ | < | > spacing_character : : = space | horizontal tabulation format_effector : : = carriage return | line feed | form feed | vertical tabulation other_character : : = ! | $ | % | ; | ? | @ | [ | ] | | ~ | vertical bar | other control characters Lexical Elements (Section 12.3) integer : : = [sign] unsigned_integer unsigned_integer : : = [digit]+ sign : : = + | - based_integer : : = radix # [sign] [extended_digit]+ # extended_digit : : = digit | letter radix : : = unsigned_integer real : : = [sign] unscaled_real | [sign] scaled_real unscaled_real : : = unsigned_integer . [unsigned_integer] | . unsigned_integer scaled_real : : = unscaled_real exponent exponent : : = E integer | e integer date : : = year_doy | year_month_day year_doy : : = year - doy year_month_day : : = year - month - day year : : = unsigned_integer month : : = unsigned_integer day : : = unsigned_integer doy : : = unsigned_integer time : : = local_time | utc_time | zoned_time local_time : : = hour_min_sec utc_time : : = hour_min_sec Z zoned_time : : = hour_min_sec zone_offset hour_min_sec : : = hour : minute [ : second] zone_offset : : = sign hour [: minute] hour : : = unsigned_integer minute : : = unsigned_integer second : : = unsigned_integer | unscaled_real date_time : : = date T time quoted_text : : = "[character]*" Chapter 12. Object Description Language Specification and Usage 12-23 quoted_symbol : : = `[character]+ ' identifier : : = letter [letter | digit | _letter | _digit ]* Statements (Section 12.4) label : : = [statement]* end statement : : = assignment_stmt | pointer_stmt | object_stmt | group_stmt assignment_stmt : : = attribute_identifier = value pointer_stmt : : = ^object_identifier = value object_stmt : : = object = object_identifier [statement]* end_object [= object_identifier] group_stmt : : = group = group_identifier [statement]* end_group [= group_identifier] Values (Section 12.5) value : : = scalar_value | sequence_value | set_value scalar_value : : = numeric_value | date_time_value | text_string_value | symbolic_value numeric_value : : = integer [units_expression] | based_integer [units_expression] | real [units_expression] units_expression : : = units_factor : : = units_identifier [exp_op integer] mult_op : : = * | / exp_op : : = ** date_time_value : : = date | time | date_time text_string_value : : = quoted_text symbolic_value : : = identifier | quoted_symbol sequence_value : : =sequence_lD | sequence_2D sequence_1D : : = (scalar_value [, scalar_value]*) sequence_2D : : = ([sequence_lD]+) set_value : : = { scalar_value [,scalar_value]* } | { } 12.7 Differences Between ODL Versions This section summarizes the differences between the current Version 2 of ODL and the previous Versions 0 and 1. Software can be constructed to read all three versions of ODL, however it is important that software for writing labels only write labels that conform to ODL Version 2. 12-24 Chapter 12. Object Description Language Specification and Usage 12.7.1 Differences from ODL Version 1 Version 1 labels were used on the Voyager to the Outer Planets CD-ROM disks and many other data sets. Version 1 did not include the GROUP statement and had more restrictive definitions for sets, which were limited to integer or symbolic literal values, and sequences, which were limited to arrays of homogeneous values. The following sections detail non-compatible differences and how they can be handled by software writers. 12.7.1.1 Ranges Version 1 of ODL had a specific notation for integer ranges: range_value :: = integer..integer This notation is not allowed in ODL Version 2, though parsers may still recognize the `double - dot' range notation. On output, a range is now encoded as a two value sequence, with the low - value of the range being the first element of the sequence and the high-value being the second element of the sequence. 12.7.1.1.1 Delimiters in Sequences and Sets In Version 1 the individual values in sets and sequences could be separated by a comma or by a spacing character. As of Version 2, a comma is required. Parsers may allow spacing characters between values rather than commas. Software that writes ODL should place commas between all values in a sequence or set. 12.7.1.1.2 Exponentiation Operator in Units Expressions In Version 1 of ODL the circumflex character (^) was used as the exponentiation operator in units expressions rather than the two-asterisk sequence (**). Parsers may still allow the circumflex to appear within units expressions as an exponentiation operator. Software for writing ODL should use only the ** notation. 12.7.2 Differences from ODL Version 0 Version 0 of ODL was developed for and used on the PDS Space Science Sampler CD-ROM disks. The major difference between this and subsequent versions is that Version 0 did not include the OBJECT statement. All of the attributes specified in a label described a single object: the file that contained the label (or that was referenced by a pointer). 12.7.2.1 Date­Time Format ODL Version 0 was produced prior to the space community's acceptance of the ISO/DIS 8601 standard for dates and time and it uses a different date and date -time format. The format for Version 0 dates and date-times is as follows: Chapter 12. Object Description Language Specification and Usage 12-25 date :: = year / month / day_of_month | year / day_of_year date_time :: = date - time zone zone :: = < identifier> The options for time specification in ODL Version 0 are a subset of those in Version 2. Consequently, parsers that handle Version 2 time formats will also handle Version 0 times. 12.7.3 ODL/PVL Usage The concept for a Parameter Value Language/Format (PVL) is being formalized by the Consultative Committee for Space Data Systems (CCSDS). It is intended to provide a human readable data element/value structure to encode data for interchange. The CCSDS version of the PVL specification is in preliminary form. Some organizations that deal with the PDS have accepted PVL as their standard language for product labels. PVL is a superset of ODL, so some PVL constructs are not supported by the PDS. In addition, some ODL constructs may be interpreted differently by PVL software. The ODL/PVL usage standard defines restrictions on the use of ODL/PVL in archive quality data sets. These restrictions are intended to ensure the compatibility of PVL with ODL and existing software. 1. A label constructed using PVL may be attached - embedded in the same file as the data object it describes, or detached - residing in a separate file and pointing to the data file the label describes. 2. All statements must be terminated by a pair. Semicolons may not be used to terminate statements. 3. Only alphanumeric characters and the underscore character may be used in data ele - ments and undelimited text values (literals). In addition, data elements and undelimited text values must begin with a letter. 4. Keywords must be 30 characters or less in length. 5. Keywords and standard values must be in upper case. Literals and strings may be in upper case, lower case, or mixed case. 6. Comments must be contained on a single line, and a comment terminator (*/) must be used. Comments may not be embedded within statements. Comments may not be used on the same line as any statement if the comment precedes the statement. Comments may be on the same line as a statement if the comment follows the statement and is separated from the statement by at least one white space, but this is not recommended. 12-26 Chapter 12. Object Description Language Specification and Usage 7. Text values that cross line boundaries must be enclosed in double quotation marks (" "). 8. Values that consist only of letters, numbers, and underscores and that begin with a letter may be used without quotation marks. All other text values must be enclosed in either single (` ') or double (" ") quotation marks. 9. Sequences are limited to two dimensions. Null (empty) sequences are not allowed. Sets are limited to one dimension. In other words, sets and sequences may not be used inside a set. 10. Only the OBJECT, END_OBJECT, GROUP and END_GROUP aggregation mark- ers may be used. 11. Unit expressions are only allowed following numeric values (i.e., "DATA_ELEMENT = 7 " is valid. but "DATA_ELEMENT = MANY " is not). 12. Unit expressions may include only alphanumeric characters, the underscore, and the symbols "*", "/", "(", ")", and "**" (the last representing exponentiation). 13. Signs may not be used in non-decimal numbers (i.e., "2#10001#" is valid, but "-2#10001#" and "2# -10001#" are not). Only the bases 2, 8, and 16 may be used for non-decimal numbers. 14. Alternate time zones (e.g., YYYY-MM-DDTHH:MM:SS.SSS + HH:MM) may not be used. The only allowed time format is YYYY-MM-DDTHH:MM:SS.SSS. 15. Values in integral parts of dates and times must be padded on the left with zeroes as necessary to fill the field. In other words, the first of April in the year 2001 must be written as "2001 -04-01", not "2001 -4-1" 16. AnEND statement must conclude each ODL/PVL statement list. The following are guidelines for formatting ODL/PVL expressions. 1. The assignment symbol (=) must be surrounded by blanks. 2. Assignment symbols (=) should be aligned if possible. 3. Keywords placed inside an aggregator (OBJECT or GROUP) must be indented with respect to the OBJECT and END_OBJECT or GROUP and END_GROUP state- Chapter 12. Object Description Language Specification and Usage 12-27 ments which enclose them. 4. PDS label lines must be 80 characters or less in length, including the end -of- statement (i.e., ) delimiter. (Note that while 80 characters can be displayed on most screens, some editors and databases will wrap or truncate lines that exceed 72 characters.) 5. Horizontal tab characters may not be used in PDS labels. Although both ODL and PVL allow the use of these characters some simple parsers cannot handle them. The equivalent number of space characters should be used instead. 12-28 Chapter 12. Object Description Language Specification and Usage GROUP, 12-15 PDS use, 12-16 OBJECT, 12-15 Object Description Language (ODL) character set, 12-3 comments, 12-13 date and time formats, 12-8 date formats, 12-9 END statement, 12-13 file format, 12-13 identifiers reserved, 12-12 syntax, 12-11 implementation date and time, 12-9 implementation notes, 12-2 integer formats, 12-6, 12-7 language summary, 12-21 lexical elements, 12-6 numeric values, 12-17 Parameter Value Language (PVL), 12-25 PDS implementation, 12-2 date and time, 12-9 sets, 12-21 symbolic literals, 12-20 PVL guidelines, 12-26 PVL restrictions on archive files, 12-25 real number formats, 12-7 revision notes, 12-23 version 0, 12-24 version 1, 12-23 sample data label, 12-1 sequences, 12-20 sets, 12-21 special characters, 12-12 specification, 12-1 statements, 12-12 assignment, 12-14 GROUP, 12-15 OBJECT, 12-15 pointer, 12-14 symbol strings, 12-11 symbolic literals, 12-20 text string values, 12-18 text strings, 12-10 12-2 Chapter 12. Object Description Language Specification and Usage time formats, 12-9 units of measure, 12-17 Parameter Value Language (PVL), 12-2, 12-25 Chapter 13. PDS Objects 13-1 Chapter 13. PDS Objects The Planetary Data System has designed a set of standard objects to be used for submitting catalog object information as well as for labeling data products. These standard objects, along with definitions of individual keywords comprising those objects, are defined in the Planetary Science Data Dictionary. In addition, object definitions and examples are also included in Appendix A and Appendix B of this document. 13.1 Generic and Specific Data Object Definitions For each type of data object that PDS has defined (i.e., IMAGE, TABLE, etc.), there are two categories of definitions: generic and specific. A generic object definition is the universal definition of an object, or superset of keywords that can be used. A specific object definition is a subset of keywords used for a particular data product to allow effective use of validation tools. Generic object definitions are designed and approved by the Planetary Data System, and defined in the Planetary Science Data Dictionary. Each object definition lists the elements and sub- objects required to be present each time the object is used in a product label. The dictionary definition also provides a list of additional, optional keywords that are frequently used by data preparers. Finally, note that any element defined in the PSDD may be included as an optional element in any object definition, at the discretion of the data preparer. A specific object definition is defined for a particular data product and is based on a single generic object. The data preparer, in consultation with a data engineer, combines all the required elements of that object with a set of optional elements selected for their relevance to the data at hand. The result is a specific object definition. This definition is subject to approval during a design review. The following examples illustrate the evolution from the generic IMAGE object to a specific IMAGE object, followed by an instance of that specific IMAGE. Note that when a specific object definition is created and used, the usage should be consistent for all labels using that object. OBJECT = GENERIC_OBJECT_DEFINITION NAME = IMAGE STATUS_TYPE = APPROVED STATUS_NOTE = "V2.1 1991-01-20 MDM New Data Object Definition" DESCRIPTION = "An image object is a regular array of sample values. Image objects are normally processed with special display tools to produce a visual representation of the sample values. This is done by assigning brightness levels or display colors to the various sample values. Images are composed of LINES and SAMPLES. They may contain multiple bands, in one of several storage orders. Note: Additional engineering values may be prepended or appended to each LINE of an image, and are stored as concatenated TABLE objects, which must be named LINE_PREFIX and LINE_SUFFIX. IMAGE objects may be associated with other objects, including HISTOGRAMs, PALETTEs, HISTORYs and TABLEs which contain statistics, display parameters, engineering values or other ancillary data." 13-2 Chapter 13. PDS Objects SOURCE_NAME = "PDS CN/M.MARTIN" REQUIRED_ELEMENT_SET = {LINE_SAMPLES, LINES, SAMPLE_BITS, SAMPLE_TYPE} OPTIONAL_ELEMENT_SET = {BAND_SEQUENCE, BAND_STORAGE_TYPE, BANDS, CHECKSUM, DERIVED_MAXIMUM, DERIVED_MINIMUM, DESCRIPTION, ENCODING_TYPE, FIRST_LINE, FIRST_LINE_SAMPLE, INVALID, LINE_PREFIX_BYTES, LINE_SUFFIX_BYTES, MISSING, OFFSET, SAMPLE_BIT_MASK, SAMPLING_FACTOR, SCALING_FACTOR, SOURCE_FILE_NAME, SOURCE_LINES, SOURCE_LINE_SAMPLES, SOURCE_SAMPLE_BITS, STRETCHED_FLAG, STRETCH_MAXIMUM, STRETCH_MINIMUM, PSDD} REQUIRED_OBJECT_SET = "N/A" OPTIONAL_OBJECT_SET = "N/A" OBJECT_CLASSIFICATION_TYPE = STRUCTURE OBJECT = ALIAS NAME = "N/A" USAGE_NOTE = "N/A" END_OBJECT = ALIAS END_OBJECT = GENERIC_OBJECT_DEFINITION _______________________________________________________________________________ This next example illustrates an IMAGE object definition being used for a specific case. _______________________________________________________________________________ OBJECT = SPECIFIC_OBJECT_DEFINITION NAME = XYZ_IMAGE STATUS_TYPE = APPROVED STATUS_NOTE = "V2.1 1991-02-10 TMA New specific data object definition" DESCRIPTION = "The XYZ image is..." SOURCE_NAME = "PDS CN/M.MARTIN" REQUIRED_ELEMENT_SET = {LINE_SAMPLES, LINES, SAMPLE_BITS, SAMPLE_TYPE, SAMPLING_FACTOR, SOURCE_FILE_NAME, SOURCE_LINES, SOURCE_LINE_SAMPLES, SOURCE_SAMPLE_BITS, FIRST_LINE, FIRST_LINE_SAMPLE} OBJECT_CLASSIFICATION_TYPE = STRUCTURE OBJECT = ALIAS NAME = "N/A" USAGE_NOTE = "N/A" END_OBJECT = ALIAS END_OBJECT = SPECIFIC_ OBJECT_DEFINITION 13.2 Primitive Objects Generic objects have a subclass called primitive objects that includes the ARRAY, COLLECTION, ELEMENT, and BIT_ELEMENT objects. The primitive objects are used as the Chapter 13. PDS Objects 13-3 building blocks for describing very irregular data that cannot be accommodated by any other generic object. If at all possible, standard, well-supported generic objects (such as TABLE and IMAGE) should be used to describe archival data. 13-4 Chapter 13. PDS Objects objects generic, 13-1 example, 13-1 primitive, 13-2 specific, 13-1 example, 13-1 standard objects, 13-1 Chapter 14. Pointer Usage 14-1 Chapter 14. Pointer Usage Pointers are used within PDS labels to indicate the relative locations of objects in the same file and to reference external files. Pointer statements begin with a caret ("^") and the name of a PDS object or element. The value part of the pointer statement indicates the location of the referenced information. 14.1 Types of Pointers Pointer statements fall into three main categories: data location pointers, include pointers, and related information pointers. 14.1.1 Data Location Pointers (Data Object Pointers) The most common use of pointers is for linking object descriptions to the actual data. The syntax of these pointers depends on whether the label is attached or detached from the data it describes. There are five forms for the value fields, as shown in these examples: (1) ^IMAGE = 12 (2) ^IMAGE = 600 (3) ^INDEX_TABLE = "INDEX.TAB" (4) ^SERIES = ("C100306.DAT", 2) (5) ^SERIES = ("C100306.DAT", 700 ) Examples (1) and (2) are pointers in attached labels. This type of pointer allows reading software to scan the label for the appropriate pointer and then skip right to the data at its location elsewhere in the file. In the first case, the data begin at record 12 of the labeled file. In the second, the data begin at byte 600. External data files are referenced in examples (3), (4) and (5). Since these pointers occur in detached labels, they must identify a file name and (optional) offset. In example (3), the data begin at record 1 of the data file "INDEX.TAB" (i.e., no explicit offset is taken as an offset of "1"). In example (4), the data begin at record 2 of the data file, "C10030 6.DAT", whereas in example (5), the data begin at byte 700. 14.1.2 Include Pointers Another common use of pointers is to reference external files in PDS labels or catalog objects. Files referenced by include pointers are included directly at the location of the pointer statement. These pointers are classified as include-type pointers since they act like the "#include" statements in C program source files. STRUCTURE, CATALOG, and MAP_PROJECTION pointers fall into this category. Following are some examples of include pointer statements: (1) ^STRUCTURE = "ENGTAB.FMT" (2) ^STRUCTURE = "IMAGE.FMT" 14-2 Chapter 14. Pointer Usage (3) ^CATALOG = "CATALOG.CAT" (4) ^DATA_SET_MAP_PROJECTION = "DSMAPDIM.CAT" The structure file in example (1) is referenced by a TABLE object. The "ENGTAB.FMT" file contains column object definitions needed to complete the TABLE definition. Some column definitions might be stored in a separate file if, for example, a number of different TABLE objects use the same definitions. Similarly, in example (2) an IMAGE object definition (i.e., all statements beginning with "OBJECT = IMAGE" and ending with "END_OBJECT = IMAGE") is contained in an external file called "IMAGE.FMT". In example (3), the external file "CATALOG.CAT" i s referenced by a VOLUME object in order to provide a full set of catalog information associated with the volume without having to duplicate definitions that already exist in the other file. In example (4), the external file "DSMAPDIM.CAT" is referenced b y an IMAGE_MAP_PROJECTION object to complete the map projection information associated with the image. 14.1.3 Related Information Pointers (Description Pointers) The third and final use of pointers occurs in PDS labels that reference external files of additional documentation of special use to human readers. These pointers are formed using elements that end in "DESCRIPTION" or "DESC". They reference text files not written in ODL. Note: These pointers are not meant to be used to refer to software tools. For example: ^DESCRIPTION = "TRK_2_25.ASC" In this example, the pointer references an external ASCII document file, TRK_2_25.ASC, which provides a detailed description of the data. Note that in this case the documentation file must have its own PDS label, since the label containing the ^DESCRIPTION pointer describes the contents of a different file. Chapter 14. Pointer Usage 14-3 14.2 Rules for Resolving Pointers Following are the rules for resolving pointer references to external files (see the Volume Organization and Naming chapter in this document for information about physical and logical volume structures): For a pointer statement in FILE_A: (1) Look in the same directory as FILE_A (2a) For a single physical volume (no logical volumes), look in the following top level directory: Pointer Directory ^STRUCTURE LABEL ^CATALOG CATALOG ^DATA_SET_MAP_PROJECTION CATALOG* ^INDEX_TABLE INDEX ^DESCRIPTION or ^TEXT DOCUMENT (2b) Within a logical volume, look in the top level subdirectory specified by the LOGICAL_VOLUME_PATH_NAME keyword: Pointer LOGICAL_VOLUME_PATH_NAME / Directory ^STRUCTURE LABEL ^CATALOG CATALOG ^DATA_SET_MAP_PROJECTION CATALOG* ^INDEX_TABLE INDEX ^DESCRIPTION or ^TEXT DOCUMENT * Note: For volumes using PDS Version 1 or 2 standards, the MAP_PROJECTION files may be located in the LABEL directory All pointers to data objects should be resolved in step (1), since these files are always required to be located in the same directory as the label file. 14-4 Chapter 14. Pointer Usage data pointers, 14-1 description pointers, 14-2 include pointers, 14-1 pointers data, 14-1 in attached labels, 14-1 in detached labels, 14-1 description, 14-2 include, 14-1 rules for resolving, 14-3 use in labels, 14-1 Chapter 15. Record Formats 15-1 Chapter 15. Record Formats The choice of proper record format for a data file is influenced by a number of factors. In general, the PDS strongly recommends a record format of fixed-length or stream be used whenever possible to ensure transportability across operating systems and computer platforms and to avoid potential difficulties with interpretation of the underlying data. Records of type FIXED_LENGTH are required for ASCII files described by TABLE Objects. Records of type VARIABLE_LENGTH may be used in cases where storage efficiency is a major consideration, as, for example, in storing compressed images. Records of type STREAM should be used for text files for ease of transportation to various computer systems. Input/output operations with stream files will generally use string-oriented access, retrieving one delimited record from the file each time. The RECORD_TYPE element in the PDS label indicates the format of the records in the associated data file (attached or detached). Table 15.1: Recommended Record Formats RECORD_TYPE= RECORD_TYPE=STREAM RECORD_TYPE=VARIABLE FIXED_LENGTH Data format BINARY, ASCII ASCII BINARY Environment STRUCTURED AD HOC STRUCTURED (VAX/VMS) Data volume LARGE SMALL, MEDIUM VERY LARGE Input / Output READ / WRITE STRING I/O CUSTOM, SPICE 15.1 FIXED_LENGTH Records Records of type FIXED_LENGTH normally use a physical record length (RECORD_BYTES) that corresponds directly to the logical record length of the data objects (that is, one physical record for each image line, or one physical record for each row of a table). In some cases, logical records are blocked into larger physical records to provide more efficient storage and access to the data. This blocking is still an important consideration when storing data on magnetic tape, (which requires a gap on the tape between records), but is not generally a consideration in data sets stored on magnetic or CD-ROM disks. In other cases, the physical record length is determined by compatibility with external systems or standards, as in FITS-formatted files. The PDS strongly recommends using a physical record length that matches the logical record length of the primary data object in the file for greatest compatibility with application software. In the data label, RECORD_BYTES defines the physical record length. Figure 15.1 illustrates the physical and logical structure used to build a standard PDS FIXED_LENGTH file. 15-2 Chapter 15. Record Formats Figure 15.1 Physical and Logical Structure for Fixed Length Files 15.2 STREAM Records The STREAM record type is reserved for ASCII text files. The records must be delimited by the two-character (carriage return, linefeed) sequence ("" or "CR/LF"). This is the same record delimiter used for all PDS label and catalog files. All major operating systems recognize one of either the carriage return, the line feed, or the CR/LF sequence as an ASCII record delimiter; thus, will work in all cases. There are utilities available for Macintosh (Apple File Exchange) and Unix (tr translation utility) systems to remove the unneeded extra control character. Note that the STREAM record type should only be used in those cases where the data contain delimited ASCII records that are not of fixed length. The FIXED_LENGTH specification should be used wherever possible. 15.3 VARIABLE_LENGTH Records PDS data files using the VARIABLE_LENGTH record type must use the VAX/VMS counted byte string format. That is, each record string is preceded by a two-byte LSB integer containing the length of the record. The records may not contain carriage control characters. The use of the VARIABLE_LENGTH record type is discouraged because of its inherent dependence on a priori knowledge of the record structure for proper reading and writing. Notwithstanding, VARIABLE_LENGTH records may be used in the following circumstances: ?? When supporting software, which can be executed on a variety of hosts, is provided along with the data. For example, the Voyager CD-ROM disks contain variable-length Chapter 15. Record Formats 15-3 compressed images along with a decompression program that can be compiled and executed on VAX, PC, Macintosh and UNIX platforms. The decompression program reformats the data into a variety of forms. ?? When the files are intended for use only in a specific environment that supports the selected record structure. For example, the Viking Infrared Thermal Mapper (IRTM) CDROM uses a VAX/VMS variable-length record format for software and command files. Note, however, that such proprietary formats are generally inappropriate for PDS deep archiving purposes and should be vigorously avoided in archive volumes. 15.4 UNDEFINED Records Records with an undefined record type have no specific record structure. For files with attached labels, the label portion should be written using the STREAM conventions described above. When the record type is designated UNDEFINED, no record terminators are recognized and no record length is implied; the data are taken to b e a continuous stream of bytes. The use of the UNDEFINED record type when referring to a single data file is strongly discouraged. "RECORD_TYPE = UNDEFINED" is properly used in cases where a single label points to two or more different data files with different record types (i.e., one file with STREAM records and another with VARIABLE_LENGTH records). 15-4 Chapter 15. Record Formats ASCII text files record format, 15-2 data files record format, 15-1 record formats, 15-1 blocking, 15-1 FIXED_LENGTH, 15-1 STREAM, 15-2 UNDEFINED, 15-3 VARIABLE_LENGTH, 15-2 VAX counted byte strings, 15-2 RECORD_TYPE, 15-1 STREAM, 15-2 UNDEFINED, 15-3 VARIABLE_LENGTH, 15-2 Chapter 16. SFDU Usage 16-1 Chapter 16. SFDU Usage This standard defines restrictions on the use of Standard Formatted Data Units (SFDUs) in archive quality data sets. PDS does not require that data products be packaged as SFDUs. However, if data products are packaged as SFDUs, the following standards apply. The Consultative Committee for Space Data Systems (CCSDS) has prepared a recommendation for the standardization of the structure and construction rules of SFDUs for the inter change of digital space-related data. An SFDU is a type-length-value object. That is, each SFDU consists of: a type identifier which indicates the type of data within the SFDU; a length field which either states the length of the data or indicates how the data are delimited; and a value field which contains the actual data. Both the type and the length fields are included in a 20 -byte label, called an SFDU label in this document. The value field immediately follows the 20-byte SFDU Label. For PDS data products, this value field is the PDS label, including one or more data object definitions. There are three versions of SFDUs. In Version 1, the length of an SFDU is represented in binary. In Version 2, the length could also be represented in ASCII. In Version 3, the length can be represented in binary, ASCII, or using one of several delineation techniques. Unless previously negotiated, all PDS data products packaged as SFDUs must be constructed using Version 3 SFDU Labels. A Version 3 SFDU label consists of the following parts: l) Control Authority ID 4 Bytes 2) Version ID 1 Byte 3) Class ID 1 Byte 4) Delimiter Type 1 Byte 5) Spare 1 Byte 6) Description Data Unit ID 4 Bytes 7) Length 8 Bytes The Control Authority ID and the Description Data Unit ID together form an identifier called an Authority and Description Identifier which points to a semantic (Planetary Science Data Dictionary, in the PDS case) and syntactic (Object Definition Language, 2.0) description of the value field. . The Data Description Unit ID varies by data product type. It is supplied by the JPL Control Authority and is usually documented in the science data product Software Interface Specifications (SIS). Version 3 allows delimiting of SFDUs either by end-of-file or by start and end markers rather than by explicit byte counts. Further details of the SFDU architecture will not be discussed here. Other sources of information can be found in the SFDU References listed in the Introduction to this document. 16-2 Chapter 16. SFDU Usage Since archive quality data sets are internally defined, only a limited set of SFDU labels are used to identify the files on a data volume in order to simplify not only the archive products themselves, but also the processing of those products by software. PDS labels are included in the data products, and the information in these PDS labels are considered more than adequate for data identification and scientific analysis. PDS does not require SFDU labels in its archive products. However, SFDU labels can be accommodated in PDS products when they are required by projects or other agencies concerned in the preparation of the data. The standard use of SFDUs in PDS labels from current missions and data restorations is different from the use of SFDUs in data products from upcoming missions fully supported by the Jet Propulsion Laboratory's Advanced Multi-Mission Operations System (AMMOS). The following sections define the standards for including SFDUs in each case. Two SFDU organizations are allowed in PDS data products. The first organization (the ZI Structure) has been used historically in PDS data products from restoration and past missions. The second organization (the ZKI organization) is requ ired for data products that pass through the JPL Advanced Multi-Mission Operations System (AMMOS) project database. 16.1 The ZI SFDU Organization Any PDS data products packaged as SFDUs that are not required to pass through the AMMOS project database as part of an active mission may use the following SFDU organization. Each instance of a data product (file) in a data set must include two (and only two) SFDU labels. These are a Z Class SFDU label and an I Class SFDU label. The two SFDU labels are concatenated (i.e. Z, then I) and left justified in the first line or record of the PDS label for each data product. (See Figure 16.1.) In the case of data products with detached PDS labels, the two SFDU labels must appear in the first record of the PDS label files and no SFDU labels appear in the data object files. (See Figure 16.2.) Chapter 16. SFDU Usage 16-3 Figure 16.1 Attached PDS Label Example for non-AMMOS compatible products Figure 16.2 Detached PDS Label Example for non-AMMOS compatible products The first SFDU label must be a Z Class Version 3 SFDU label. "Z Class" indicates that the value field (everything after the first 20 bytes) is an aggregation. In this case, the aggre gation consists of only the I Class SFDU. This label also indicates that the delimiter type is End-of-File and that this SFDU (data product) is terminated by a single End-of-File. It is formed as follows: 1) Control Authority ID CCSD 2) Version ID 3 3) Class ID Z 4) Delimiter Type F 5) Spare 0 6) Description Data Unit ID 0001 7) Length Field 00000001 Example: CCSD3ZF0000l0000000l The second SFDU label must be an I Class Version 3 SFDU label. "Class I" indicates that the 16-4 Chapter 16. SFDU Usage value field (everything after the second 20 bytes) is application data, i.e., the PDS label and the data object(s). The Data Description Unit ID of "PDSX" indicates that the data product uses the Object Description Language (ODL) syntax and the Planetary Science Data Dictionary semantics to present descriptive information. This SFDU label also indicates that the SFDU (data products) will be terminated by a single End-of-File. It is formed as follows: 1) Control Authority ID NJPL 2) Version ID 3 3) Class ID I 4) Delimiter Type F 5) Spare 0 6) Description Data Unit ID PDSX 7) Length Field 00000001 Example: NJPL3IF0PDSX0000000l Figure 16.3: SFDU Example The two SFDU labels are concatenated and left justified in the first line or record of the PDS label. Note that there are no characters between the two SFDU labels. See Figure 16.3. For RECORD_TYPE = STREAM or FIXED_LENGTH or UNDEFINED, the concatenated SFDU labels must be followed immediately by . For data products that have RECORD_TYPE =VARIABLE_LENGTH, the two SFDU labels may not be followed by . STREAM example CCSD3ZF0000l0000000lNJPL3IF0PDSX0000000l FIXED_LENGTH Example CCSD3ZF0000l0000000lNJPL3IF0PDSX0000000l VARIABLE_LENGTH Example CCSD3ZF0000l0000000lNJPL3IF0PDSX0000000l UNDEFINED Example CCSD3ZF0000l0000000lNJPL3IF0PDSX0000000l Chapter 16. SFDU Usage 16-5 The remainder of the PDS label begins on the next line or record. The last line of the PDS label contains the END statement. Then, if the PDS Label is attached, the data object begins on the next record. If the PDS label is detached, the END statement is the last line of the file. 16.2 The ZKI SFDU Organization Any PDS data products packaged as SFDUs that are required to pass through the AMMO S project database as part of an active mission must use the following SFDU organization. All data products of this type are assumed to have attached PDS labels. Each instance of a data product (file) in a data set must include four (and only four) SFDU labels. These are: the Z Class SFDU label; the K Class SFDU label; the End-Marker label for the K Class SFDU; and the I Class SFDU label. The Z and K Class SFDU labels are concatenated (i.e., Z, then K) and left justified in the first line or record of the PDS label for each data product. The End-Marker for the K Class SFDU label and the I Class SFDU label are right justified on the last record of the PDS label (following the END statement). See Figure 16.4. Figure 16.4: PDS Label Example for AMMOS compatible products The first SFDU label must be a Z Class Version 3 SFDU label. The Z Class indicates that the value field (everything after the first 20 bytes) is an aggregation. In this case, the aggregation consists of a K Class (PDS label) and an I Class (data object) SFDU. This label also indicates that the delimiter type is End-of-File and that this SFDU (data product) is terminated by a single End-of-File. It is formed as follows: 1) Control Authority CCSD 2) Version ID 3 3) Class ID Z 4) Delimiter Type F 5) Spare 0 6) Description Data Unit ID 0001 7) Length Field 00000001 16-6 Chapter 16. SFDU Usage Example: CCSD3ZF0000l0000000l The second SFDU label must be a K Class Version 3 SFDU label. "Class K" indicates that the value field (everything after the second 20 bytes) is catalog and directory information, i.e., the PDS label (sometimes referred to as the K Header). The Data Description Unit ID of PDSX indicates that the PDS label uses the Object Description Language (ODL) syntax and the Planetary Science Data Dictionary semantics to present data descriptive information. The SFDU label also indicates that the SFDU is delimited by a Start-Marker/End-Marker pair. It is formed as follows: 1) Control Authority ID NJPL 2) Version ID 3 3) Class ID K 4) Delimiter Type S 5) Spare 0 6) Description Data Unit ID PDSX 7) Length Field ##mark## The marker pattern ("##mark##" in the example) c an be set to any string that is unlikely to be repeated elsewhere in the data product. Example: NJPL3KS0PDSX##mark## The two SFDU labels must be concatenated and left justified in the first line or record of the PDS label. Note that there are no characters between the two SFDU labels. For data products with RECORD_TYPE equal to VARIABLE_LENGTH, the two concatenated SFDU labels must not be followed by . Example: CCSD3ZF0000l0000000lNJPL3KS0PDSX##mark## The remainder of the PDS label begins on the next line. The last line of the PDS label contains the END statement. Then, in the same line or record, right justified, is the End -Marker for the K Class SFDU and the I Class SFDU label. The End-Marker pattern must appear as: Example: CCSD$$MARKER##mark## Note that the start marker and the end marker fields must be identical within the SFDU (in the example, "##mark##"). Next must be an I Class Version 3 SFDU label. "Class I" indicates that the value field (everything after the SFDU label) is application data, i.e., the data object. The Data Description Unit ID varies by data product type. It is supplied by the JPL Control Authority and is usually documented in the science data product Software Interface Specifications (SIS). The SFDU label also indicates that the SFDU will be terminated by a single End-of-File. It is formed as follows: Chapter 16. SFDU Usage 16-7 1) Control Authority ID NJPL 2) Version ID 3 3) Class ID I 4) Delimiter Type F 5) Spare 0 6) Description Data Unit ID XXXX 7) Length Field 00000001 Example: NJPL3IF001060000000l (where XXXX has been replaced by 0106.) The two SFDU labels must be concatenated, right justified, and appear in the last line or record of the PDS label following the END statement. (If it happens that there are not 40 bytes left in the last record of the PDS label, add an additional record and right justify the two SFDU labels.) Note that there are no characters between the two SFDU labels, and that the marker pattern and I Class SFDU Labels are transparent to PDS label processing software. Example: END CCSD$$MARKER##mark##NJPL3IF001060000000l The data object begins with the next physical record. 16.3 Examples RECORD_TYPE = STREAM: End Statement blank(s) End marker I Class SFDU End of record END CCSD$$MARKER##mark##NJPL3IF0010600000001 RECORD_TYPE = FIXED_LENGTH: End Statement Terminator Record Boundary END bbbbb CCSD$$MARKER##mark##NJPL3IF0010600000001 RECORD_TYPE = UNDEFINED: State ment terminator End Statement END CCSD$$MARKER##mark##NJPL3IF0010600000001 16-8 Chapter 16. SFDU Usage RECORD_TYPE = VARIABLE_LENGTH: Record Length END end of statement END CCSD$$MARKER##mark##NJPL3IF0010600000001 16.4 Exceptions to this Standard Software files and document files should not be packaged as SFDUs. Previous versions of the PDS standards expressed the ZI SFDU labels as an ODL statement. The ZI SFDU labels were followed by "= SFDU_LABEL". Example: CCSD3ZF0000100000001NJPL3IF0PDSX00000001 = SFDU_LABEL Chapter 16. SFDU Usage 16-9 END statements, 16-5 Standard Formatted Data Unit (SFDU) AMMOS usage, 16-5 definition, 16-1 examples FIXED_LENGTH file, 16-7 STREAM file, 16-7 UNDEFINED file, 16-7 VARIABLE_LENGTH file, 16-8 exceptions, 16-8 I class, 16-2, 16-5 K class, 16-5 usage in PDS products, 16-1 versions, 16-1 Z class, 16-2, 16-5 Chapter 17. Usage of N/A, UNK, and NULL 17-1 Chapter 17. Usage of N/A, UNK and NULL 17.1 Interpretation of N/A, UNK, and NULL During the completion of data product labels or catalog files, one or more values may not be available for some set of required data elements. In this case PDS provides the symbolic literals "N/A", "UNK", and "NULL", each of which is appropriate under different circumstances. 17.1.1 N/A "N/A" ("Not Applicable ") indicates that the values within the domain of this data element are not applicable in this instance. For example, a data set catalog file describing NAIF SPK kernels would contain the line: INSTRUMENT_ID = "N/A" because this data set is not associated with a particular instrument. "N/A" may be used as needed for data elements of any type (i.e., text, date, numeric, etc.). 17.1.2 UNK "UNK" ("Unknown ") indicates that the value for the data element is not known and never will be. For example, in a data set comprising a series of images, each taken with a different filter, one of the labels might contain the line: FILTER_NAME = "UNK" if the observing log recording the filter name was lost or destroyed and the name of the filter is not otherwise recoverable. "UNK" may be used as needed for data elements of any type. 17.1.3 NULL "NULL" is used to flag values that are temporarily unknown. It indicates that the data preparer recognizes that a specific value should be applied, but that the true value was not readily available. "NULL" is a p laceholder. For example, the line: DATA_SET_RELEASE_DATE = "NULL" might be used in a data set catalog file during the development and review process to indicate that the release date has not yet been determined. 17-2 Chapter 17. Usage of N/A, UNK, and NULL Note that all "NULL" indicators should b e replaced by their actual values prior to final archiving of the associated data. 17.2 Implementation Recommendations for N/A, UNK, and NULL The figurative constants defined above require special values for storage in data base systems. The PDS has the following recommendations for software intended to support PDS labels and catalog objects: 1. In the case of character fields, the explicit string can be stored in the corresponding data elements without further modification. This approach can also be taken where date and time data types are stored as strings. 2. Numeric fields require special flag values to represent the "N/A", "NULL" and "UNK" indicators. Table 17.1 provides suggested standard flag values for each case. In creating index files based on element values extracted from PDS labels, there are two options for dealing with "N/A", "NULL", and "UNK" in non -string columns: 1. The character strings can be used explicitly in the index. Note, however, that in this case the DATA_TYPE of the column may be forced to "CHARACTER", since, for example, encountering the string "NULL" in what is otherwise a numeric column would cause a read failure. 2. The character strings can be replaced with an appropriate numeric constant. In this case the substitution is indicated in the corresponding column definition by including the NOT_APPLICABLE_CONSTANT, NULL_CONSTANT or UNKNOWN_CONSTANT elements as needed. Table 17.1: Numeric values for N/A, UNK, NULL Signed Signed Unsigned Unsigned Tiny Integer Real Integer Integer Integer Integer (1 byte - (4 byte) (2 byte) (4 byte) (2 byte) unsigned) N/A -2147483648 -32768 4294967293 65533 locally defined -1.E32 UNK 2147483647 32767 4294967294 65534 locally defined +1.E32 NULL NULL* NULL* NULL* NULL* NULL* NULL* ?? "NULL" refers to a system-defined null value. The availability of NULL as a universal value across data types in some data management systems simplifies the implementation of the figurative constant "NULL". However, if a system "null" is not available, then either a) an arbitrary value can be chosen, or b) the Chapter 17. Usage of N/A, UNK, and NULL 17-3 meanings of UNK and NULL can be combined and the token or numeric representation of UNK used. 17-4 Chapter 17. Usage of N/A, UNK, and NULL N/A constant, 17-1 Not Applicable constant, 17-1 NULL constant, 17-1 UNK constant, 17-1 Unknown constant, 17-1 Chapter 18. Units of Measurement 18-1 Chapter 18. Units of Measurement The uniform use of units of measure facilitates broad catalog searches across archive systems.The PDS standard system for units, where applicable, is the Systeme Internationale d'Unites (SI). The default units for data elements in the Planetary Science Data Dictionary (PSDD) are determined as each element is defined and added to the dictionary. Specific unit definitions are also included in the PSDD. In cases where more than one type of unit is commonly used for a given data element, an additional data element is provided to explicitly identify the corresponding unit. SAMPLING_PARAMETER_RESOLUTION and SAMPLING_PARAMETER_UNIT are one such pair. The PDS allows exceptions to the SI unit requirement when common usage conflicts with the SI standard (e.g., angles which are measured in degrees rather than radians). Both singular and plural unit names, as well as unit symbols, are allowed. The double asterisk (**) is used, rather than the caret (^), to indicate exponentiation. When the units associated with a value of a PDS element are not the same as the default units specified in the PSDD (or when explicit units are preferred), a unit expression is used with the value. These unit expressions are enclosed in angular brackets (< >) and follow the value to which they apply. Examples EXPOSURE_DURATION = 10 DECLINATION = -14.2756 MASS = 123 MASS_DENSITY = 123 MAP_RESOLUTION = 123 MAP_SCALE = 123 Note that in the above example, MASS_DENSITY is not expressed in the SI default unit of measurement for density (kg/m**3). PDS recommends (in order of preference) that measurements be expressed using the default SI units of measurements, as defined in the following paragraphs. If it is n ot desirable to use the default SI unit of measurement, then the unit of measurement should be expressed using the SI nomenclature defined in the following paragraphs. If a unit of measurement is not defined by the SI standard, then a unit of measurement c an be derived (e.g., pixels per degree, kilometers per pixel, etc.). 18.1 SI Units The following summary of SI unit information is extracted from The International System of Units. Base units - As the system is currently used, there are seven fundamental SI units, termed "base 18-2 Chapter 18. Units of Measurement units": QUANTITY NAME OF UNIT SYMBOL length meter m mass kilogram kg time second s electric current ampere A thermodynamic temperature kelvin K amount of substance mole mol luminous intensity candela cd SI units are all written in mixed case; symbols are also mixed case except for those derived from proper names. No periods are used in any of the symbols in the international system. Derived units - In addition to the base units of the system, a host of derived units, which stem from the base units, are also employed. One class of these is formed by adding a prefix, representing a power of ten, to the base unit. For example, a kilometer is equal to 1,000 meters, and a millisecond is .001 (that i s, 1/1,000) second. The prefixes in current use are as follows: SI PREFIXES Factor Prefix Symbol Factor Prefix Symbol 10**18 exa E 10**-1 deci d 10**15 peta P 10**-2 centi c 10**12 tera T 10**-3 milli m 10**9 giga G 10**-6 micro 10**6 mega M 10**-9 nano n 10**3 kilo k 10**-12 pico p 10**2 hecto h 10**-15 femto f 10**1 deka da 10**-18 atto a Note that the kilogram (rather than the gram) was selected as the base unit for mass for historical reasons. Notwithstanding, the gram is the basis for creating mass units by addition of prefixes. Another class of derived units consists of powers of base units and of base units in algebraic relationships. Some of the more familiar of these are the following: QUANTITY NAME OF UNIT SYMBOL area square meter m**2 volume cubic meter m**3 density kilogram per cubic meter kg/m**3 velocity meter per second m/s angular velocity radian per second rad/s acceleration meter per second squared m/s**2 Chapter 18. Units of Measurement 18-3 angular acceleration radian per second squared rad/s**2 kinematic viscosity square meter per second m**2/s dynamic viscosity newton-second per square meter N*s/m**2 luminance candela per square meter cd/m**2 wave number 1 per meter m**-1 activity (of a radioactive source) 1 per second s**-1 Many derived SI units have names of their own: QUANTITY NAME OF UNIT SYMBOL EQUIVALENT frequency hertz Hz s**-1 force newton N kg*m/s**2 pressure (mechanical stress) pascal Pa N/m**2 work, energy, quantity of heat joule J N*m power watt W J/s quantity of electricity potential difference coulomb C A*s electromotive force volt V W/A electrical resistance ohm ­ V/A capacitance farad F A*s/V magnetic flux weber Wb V*s inductance henry H V*s/A magnetic flux density tesla T Wb/m**2 luminous flux lumen lm cd*sr illuminance lux lx lm/m**2 Supplementary units are as follows: QUANTITY NAME OF UNIT SYMBOL plane angle radian rad solid angle steradian sr Use of figures with SI units - In the international system it is considered preferable to use only numbers between 0.1 and 1,000 in expressing the quantity associated with any SI unit. Thus the quantity 12,000 meters is expressed as "12 km", not "12,000 m". So too, 0.003 cubic centi meters is preferably written "3 mm 3", not "0.003 cm 3". 18-4 Chapter 18. Units of Measurement SAMPLING_PARAMETER_RESOLUTION, 18-1 SAMPLING_PARAMETER_UNIT, 18-1 Systeme Internationale d'Unites (SI), 18-1 units of measure, 18-1 default units, 18-1 SI prefixes, 18-2 SI units, 18-1 supplementary units, 18-3 symbols, 18-1 Chapter 19. Volume Organization and Naming 19-1 Chapter 19. Volume Organization and Naming The Volume Organization and Naming Standard defines the organization of data sets onto physical media and the conventions for forming volume names and identifiers. A volume is one unit of a physical medium such as a CD, a DVD, or a magnetic tape. Data sets may reside on one or more volumes and multiple data sets may also be stored on a single volume. Volumes are grouped into volume sets. Each volume has a directory structure containing subdirectories and files. Both random access (CD, DVD) and sequential access (magnetic tape) media are supported. A PDS volume on a sequential access medium has a virtual directory structure defined in the VOLUME object included in the file "VOLDESC.CAT". This virtual structure may then be used to recre ate the volume directory structure when the files are moved to a random access medium. PDS recommends that the entire contents of an archive volume and volume set be based on a single version of the PDS Standards Reference. Software tools that work with one version of the Standards may not work with all versions. 19.1 Volume Set Types Data may be organized into one of four types of archive volumes, based on the number of data sets on each volume and the number of volumes required to capture all the data. The directory organization of the volumes and the required files varies slightly depending on this volume type. Figures 19.1 through 19.4 depict the various volume directory structure options. The four volume types are described below. 1. One data set on one volume. This basic volume organization is illustrated in Figure 19.1. The required and optional files and directories are detailed in Section 19.3 . 2. One data set on many volumes. In this case the INDEX subdirectory includes both local indices, for the data on the present volume, and cumulative indices, for the data on all (preceding) volumes. This layout is illustrated in Figure 19.2. 3. Many data sets on one volume. In this case, additional file naming conventions are imposed to prevent collisions; data subdirectories are organized by data set. There are two variations on this scheme: a. One logical volume ­ That is, the data sets collected on the physical medium constitute a single logical volume and would generally be distributed together. See Figures 19.3a and 19.3b, and Section 19.6 for more information on logical volumes. b. Many logical volumes ­ and The physical medium contains several largely independent collections of data sets, with each collection organized as though it were on its own volume. This is useful when a larger capacity medium (say, DVD) is being used to hold several volumes originally produced on a smaller 19-2 Chapter 19. Volume Organization and Naming capacity medium (e.g., CD-ROM). In this case, directories that are common to and identical on all volumes need only be reproduced once (e.g., the SOFTWARE directory in Figure 19.3b). See Figures 19.3a and 19.3b, and Section 19.6 for more information on logical volumes. 4. Many data sets on many volumes. This organization is most useful when several large data sets are being produced in parallel over an extended period of time (as with some space missions). Sections of each data set appear on each physical volume, requiring additional naming considerations. See Figure 19.4 for more information. Note that it is possible to have one or more volumes containing only data accompanied by an ancillary volume containing the DOCUMENT, CATALOG, GAZETTER, SOFTWARE, CALIB, and GEOMETRY directories relevant to all the other volumes. When this is done, the PDS requires that all files referenced by include-type pointers (see the Pointer Usage chapter in this document) be present on the data volume. The PDS recommends that ancillary files be archived on the same volume as the corresponding data wherever possible, to facilitate science access. The contents and organization of the directories of all the volume types are described in the remainder of this chapter. Chapter 19. Volume Organization and Naming 19-3 Figure 19.1 Volume Set Organization Standard - One Data Set, One Volume 19-4 Chapter 19. Volume Organization and Naming Figure 19.2 Volume Set Organization Standard - One Data Set, Many Volumes Chapter 19. Volume Organization and Naming 19-5 Figure 19.3a Volume Set Organization Standard - Many Data Sets, One Volume 19-6 Chapter 19. Volume Organization and Naming Figure 19.3b Volume Set Organization Standard - Many Data Sets, One Physical Volume, Many Logical Volumes Chapter 19. Volume Organization and Naming 19-7 Figure 19.4 Volume Set Organization Standard - Many Data Sets, Many Volumes 19.2 Volume Organization Guidelines The PDS recommends that directory structures be simple, path names short, and directory and file names constructed in a logical manner. When determining the number of files to be stored in each subdirectory, data preparers should keep in mind that most users rely on visual inspection to glean the contents of a directory or confirm that a disk is intact. Not e that some older operating systems will "crash" when encountering a directory containing more than 128 files. Note also that device load time can be directly dependent on the number of files in a directory, making large directories inconvenient for large numbers of users. The typical practical limit for these purposes is on the order of 100 files per directory. As a further convenience to users, PDS recommends that empty subdirectories be omitted entirely. 19.3 Description of Directory Contents and Organization The root directory is the top-level directory of a volume. The following sections describe the contents of the root directory, followed by the contents of the required subdirectories (in alphabetical order), and finally the contents of the optional directories (in alphabetical order). 19-8 Chapter 19. Volume Organization and Naming 19.3.1 ROOT Directory Files AAREADME.TXT Required This file contains an overview of the contents and organization of the associated volume, general instructions for its use, and contact information. The name has been chosen so that it will be listed first in an alphabetical directory listing. See Appendix D for an example of an AAREADME.TXT file. VOLDESC.CAT Required This file contains the VOLUME object, which gives a high-level description of the contents of the volume. ERRATA.TXT Optional This file identifies and describes errors and/or anomalies found in the current volume, and possibly in previous volumes of a set. When a volume contains known errors they must be documented in this file. VOLDESC.SFD Obsolete This file is identified here only for backward compatibility with previous versions of the PDS standards. It is not to be used in current archive products. This file contains the SFDU reference object structure that aggregates the separate file contents of the volume into an SFDU. The reference object itself is expressed in ODL. This file should only be included if the data products are packaged as SFDUs. (Note the ".SFD" file extension is a reserved file extension in the CCSDS SFDU standard indicating the file contains a valid SFDU.) 19.3.2 Required Subdirectories 19.3.2.1 CATALOG Subdirectory This subdirectory contains the catalog object files (for the mission, instrument, data sets, etc.) for the entire volume. When several logical volumes are present on a single physical volume, each logical volume should have its own CATALOG subdirectory. CATINFO.TXT Required This file identifies and describes the function of each file in the CATALOG subdirectory. CATALOG.CAT Optional Chapter 19. Volume Organization and Naming 19-9 In most cases, the individual catalog objects are in separate files, one for each object. On some older archive volumes, however, all catalog objects were collected into a single file called CATALOG.CAT. PDS Methodology for Supplying Catalog Objects The preferred method for supplying catalog objects is as separate files for each catalog object, since this facilitates the review, verification and archiving process. In Figure 19.5, for example, the files axxxxxDS.CAT and bxxxxxDS.CAT represent two separate files each containing single data set catalog objects (descriptive information about the data set) for data sets a and b respectively. See the File Specification and Naming chapter in this document for the file naming rules; see Section A.5, CATALOG, for the required contents of the catalog object, and see Appendix B for information on each of the referenced catalog objects. When catalog objects are organized in separate files or sets of files, pointer expressions shall be constructed according to the following table. Under "File Name", the first line shows the file name to be used if a single catalog file is present on the volume for the particular type of catalog object named. The second shows the syntax and file name convention to be followed if multiple catalog files are present for the named object. Catalog Pointer Name File Name ^DATA_SET_CATALOG = "DATASET.CAT" = {"xxxxxxDS.CAT","yyyyyyDS.CAT"} ^DATA_SET_COLLECTION_CATALOG = "DSCOLL.CAT" = {"xxxxxDSC.CAT","yyyyyDSC.CAT"} ^DATA_SET_MAP_PROJECTION_CATALOG = "DSMAP.CAT" = {"xxxDSMAP.CAT","yyyDSMAP.CAT"} ^INSTRUMENT_CATALOG = "INST.CAT" = {"xxxxINST.CAT","yyyyINST.CAT"} ^INSTRUMENT_HOST_CATALOG = "INSTHOST.CAT" = {"xxxxHOST.CAT","yyyyHOST.CAT"} ^MISSION_CATALOG = "MISSION.CAT" = {"xxxxxMSN.CAT","yyyyyMSN.CAT"} ^PERSONNEL_CATALOG = "PERSON.CAT" = {"xxxxPERS.CAT,"yyyyPERS.CAT"} ^REFERENCE_CATALOG = "REF.CAT" = {"xxxxxREF.CAT","yyyyyREF.CAT"} ^SOFTWARE_CATALOG = "SOFTWARE.CAT" = {"xxxSW.CAT", "yyySW.CAT"} ^TARGET_CATALOG = "TARGET.CAT" = {"xxxTGT.CAT", "yyyTGT.CAT"} 19.3.2.2 Data Subdirectory The DATA subdirectory may be used to unclutter the root directory of a volume by providing a single entry point to multiple data subdirectories. These directories contain the data product files. The directories are organized and named according to the standards in Chapter 8, Directory Types and Naming, in this document. Subdirectories may be nested up to eight levels deep on a physical volume. 19-10 Chapter 19. Volume Organization and Naming Data Files A data file contains one or more data objects, which is a grouping of data resulting from a scientific observation (such as an image or table) and representing the measured instrument parameters. Label Files A label file contains a detached PDS label that identifies, describes, and defines the structure of the data objects. The associated data objects are contained in an accompanying data file. The label file must have the same base name as the associated data file, with an extension of ".LBL". Labeled Data Files PDS labels may be attached directly to the data they describe. In this case the PDS label comes first and the data begin immediately following the end of the label. When attached labels are used, no ".LBL" files will be present in the data directories. See the Data Products and Data Product Labels chapters in this manual for details. 19.3.2.3 INDEX Subdirectory This directory contains the indices for all data products on the volume. Note: If the physical volume is organized as several logical volumes (case 3b of Section 19-1), there will generally not be an INDEX subdirectory at the root of the physical volume. Instead there will be individual INDEX subdirectories at the root of each logical volume. See Section A.20, INDEX_TABLE, for more information. INDXINFO.TXT Required This file identifies and describes the function of each file in the INDEX subdirectory. This description should include at least: 1) A description of the structure and contents of each index table in this subdirectory 2) Usage notes For an example of the INDXINFO.TXT file, see Appendix D, Section D.2. INDEX.LBL Required This is the PDS label for the volume index file, INDEX.TAB. The INDEX_TABLE specific object should be used to identify and describe the columns of the index table. See Appendix A for an example. Although INDEX.LBL is the preferred name for this file, the name axxINDEX.LBL Chapter 19. Volume Organization and Naming 19-11 may also be used (with axx replaced by an appropriate mnemonic). Note: The PDS recommends detached labels for index tables. If an attached label is used, this file is omitted. INDEX.TAB Required This file contains the volume index in tabular format (i.e., the INDEX_TABLE specific object is used to identify and describe the data stored on an archive volume). Only data product label files (i.e., not the data files) are included in an index table. In rare cases, however, ancillary files are also included. Although INDEX.TAB is the preferred name for this file, the name axxINDEX.TAB may also be used, with axx replaced by an appropriate mnemonic. Note that the axx prefix is neither required nor recommended. Data producers may use a prefix to distinguish two or more files by data set, instrument, or other criteria. The data producer should replace the generic prefixes shown here with a suitable mnemonic. The following files are recommended for multi-volume sets: CUMINDEX.LBL Optional This file contains the cumulative volume set index in tabular format (i.e., the INDEX_TABLE specific object is used to identify and describe the data stored on each archive volume). Only data product label files (i.e., not the data files) are included in an index table. In rare cases, however, ancillary files may be included. Although CUMINDEX.LBL is the preferred name for this file, the name axxCMIDX.LBL may also be used, with axx replaced by an appropriate mnemonic. PDS recommends the use of detached labels for index tables. If an attached label is used, this file is omitted. CUMINDEX.TAB Optional This file contains the cumulative volume set index in a tabular format. Normally only data files are included in a cumulative index table. In some cases, however, ancillary files may be included. Although CUMINDEX.TAB is the preferred name for this file, the name axxCMIDX.TAB may also be used, with axx replaced by an appropriate mnemonic. 19.3.3 Optional Subdirectories 19.3.3.1 CALIBration Subdirectory This directory contains the calibration files used in the processing of the raw data or needed to use the data products on the volume. Note that "CALIB" is only a recommended name - a different directory name may be used if appropriate. 19-12 Chapter 19. Volume Organization and Naming CALINFO.TXT Required This file identifies and describes the function of each file in the CALIB subdirectory. Calibration Files Required In Figures 19.3 and 19.5, the files axxCALIB.TAB and bxxCALIB.TAB represent sample files. The axx and bxx prefixes indicate that the calibration files for different data sets (a and b) may be combined in the same CALIB subdirectory. Note that the axx and bxx prefixes in the sample names are neither required nor recommended. Data producers may use them to distinguish two or more files (by data set, instrument, or other criteria). Also, in this case the "CALIB" file name is not required. It is used in the figures to differentiate calibration files from observational data files. The data producer should replace the generic file names shown here by suitably mnemonic names. 19.3.3.2 DOCUMENT Subdirectory This directory contains the files that provide documentation and supplementary and anc illary information to assist in understanding and using the data products on the volume. The documentation may describe the mission, spacecraft, instrument, and data set(s). It may include references to science papers published elsewhere as well an entire papers republished on the volume. See Section A.12, DOCUMENT, for more information. DOCINFO.TXT Required This file identifies and describes the function of each file in the DOCUMENT subdirectory. VOLINFO.TXT Optional This file describes the attributes and contents of the volume. This file is sometimes included in addition to the catalog files in the CATALOG subdirectory to provide the same information in an alternate format. Note: In rare cases, the data engineer may allow the data preparer to place all the corresponding catalog object descriptions in the VOLINFO.TXT file of the DOCUMENT subdirectory in lieu of separate files in the CATALOG subdirectory. Regardless of which method is used, the descriptions themselves must always be supplied. 19.3.3.3 EXTRAS Subdirectory The EXTRAS directory is the designated area for housing additional elements provided by data preparers beyond the scope of the PDS archive requirements. Examples include HTML-based disk navigators, educational and public interest aids, and other useful but nonessentia l items. The PDS places no restrictions on the contents and organization of this subdirectory other than Chapter 19. Volume Organization and Naming 19-13 conformance to ISO-9660/UDF standards. EXTRINFO.TXT Required This file identifies and describes the function of each file in the EXTRAS subdirectory. This description should include at least the following: 1. A description of the structure and contents of each file in the subdirectory 2. Usage notes 19.3.3.4 GAZETTER Subdirectory This directory contains detailed information about all the named features on a target body (i.e., the gazetteer information) associated with the data sets on the volumes. "Named features" are those the International Astronomical Union (IAU) has named and approved. See Section A.15, GAZETTER_TABLE, for more information. GAZINFO.TXT Required This file identifies and describes the function of each file in the GAZETTER subdirectory. 19-14 Chapter 19. Volume Organization and Naming GAZETTER.TXT Required This file contains text describing the structure and contents of the gazetteer table in GAZETTER.TAB. GAZETTER.LBL Required This file is the PDS label containing a formal description of the structure of the gazetteer table. GAZETTER.TAB Required This file contains the gazetteer table. 19.3.3.5 GEOMETRY Subdirectory This directory contains the files (e.g., SEDR file, SPICE kernels, etc.) needed to describe the observation geometry for the data. Note that "GEOMETRY" is only a recommended directory name, another appropriate name may be used. GEOMINFO.TXT Required This file identifies and describes the function of each file in the GEOMETRY subdirectory. 19.3.3.6 LABEL Subdirectory This directory contains additional PDS labels and include files that were not packaged with the data products or in the data subdirectories. When multiple logical volumes reside on a single physical volume, the LABEL subdirectories must appear below the logical volume root directories. This is because the rules governing pointer resolution preclude a search across logical volumes. LABINFO.TXT Required This file identifies and describes the function of each file in the LABEL subdirectory. Include Files Required Include files are files referenced by a pointer in a PDS label. Typically they contain additional metadata or descriptive information. Only files of type LBL, TXT, or FMT ("format") may be included in the LABEL subdirectory. In Figures 19.1-5, the files axxINCLUDE FILE1, bxxINCLUDE FILE1 and INCLUDE FILE1 represent sample files of the above types. The axx and bxx prefixes indicate that the include files for different data sets (a and b) may be combined in the same LABEL subdirectory. Note that the axx and bxx prefixes in the sample names are neither required nor recommended. Data producers may use them to distinguish two or more files (by data set, instrument, or other Chapter 19. Volume Organization and Naming 19-15 criteria). The data producer should replace the generic prefixes shown here by a suitable mnemonic. 19.3.3.7 SOFTWARE Subdirectory This directory contains the software libraries, utilities, or application programs supplied for accessing or processing the data. It may also include descriptions of processing algorithms. Only public domain software may be included on PDS archive volumes. Two subdirectory structures are available for organizing the SOFTWARE directory: platform- based and application-based. Platform-based is the recommended method for general archives and is described below. For an example of application-based organization see the example for SOFTINFO.TXT in Appendix D of this document, and the NAIF directory structure in Appendix E. See Section 11.3 for information about packaging software for inclusion in an archive product. SOFTINFO.TXT Required This file identifies and describes the function of each file in the SOFTWARE subdirectory. SRC Subdirectory Optional There can be a global SRC directory under the SOFTWARE directory if there is source code applicable to all platforms. For example, application-programming languages such as IDL are relatively platform independent and would be placed in a global SRC directory. Note that in the example below, there is both a global source directory as well as source directories at the lower levels. DOC Subdirectory Optional This directory contains documentation for the software in the parallel SRC directory. LIB Subdirectory Optional This directory contains libraries applicable to all platforms. Hardware Platform and Operating System/Environment Subdirectories Optional If only global source code is being provided on the volume, no further organization is required. If platform- or environment- specific software is being provided, the structure in Figure 19.6 should be followed. Specifically: 1. The hardware platform and the operating system/environ ment must be explicitly stated. If more than one operating system/environment (OS/Env) is supported for a single hardware platform, each should have its own subdirectory under the hardware directory. If there is only one, then that subdirectory can be promoted to the hardware directory level (via naming conventions). In Figure 19.6, several environments are supported for 19-16 Chapter 19. Volume Organization and Naming platform HW1, but only one for HW2 ­ thus the difference in subdirectory structures. 2. The next directory level contains BIN, SRC, DOC, LIB and OBJ. If any of these are not applicable, it should be left out (i.e., empty directories should be omitted). 3. Following are examples of subdirectory names for both multiple and single OS/Env per platform. (This list is provided for illustration only. It is not meant to be exhaustive.) ------------------------------------------------- Multiple Single ------------------------------------------------- PC DOS PCDOS WIN PCWIN WINNT PCWINNT OS2 PCOS2 MAC SYS7 MACSYS7 AUX MACAUX SUN SUNOS SUNOS SOLAR SUNSOLAR VAX VMS VAXVMS ULTRX VAXULTRX SGI IRX4 SGIIRX4 IRX5 SGIIRX5 Chapter 19. Volume Organization and Naming 19-17 SOFTWARE SOFTINFO.TXT * * BIN SRC DOC LIB OBJ ... ... BIN SRC DOC LIB OBJ * NOTE: INFO.TXT files under SOFTWARE subdirectories are optional (e.g., PCINFO.TXT, MACINFO.TXT, VAXINFO.TXT, SUNINFO.TXT, etc.). Figure 19.6 ­ Platform-based SOFTWARE Subdirectory Structure 19.4 Volume Naming Volume names must be no more than 60 characters in length and in upper case. They should describe the contents of the volume in terms that a human user can understand. In most cases the volume name is more specific than the volume set name. For example, the volume name for the first volume in the VOYAGER IMAGES OF URANUS volume set is "VOLUME 1: COMPRESSED IMAGES 24476.54 - 26439.58." 19.4.1 Volume ID Many types of media and the machines that read them place a limit on the length of the volume ID. Therefore, although the complete volume set ID should be placed on the outside label of the volume, a shorter version is actually used when the volume is recorded. PDS has adopted a limit of 12 characters for these terse volume identifiers. This volume ID consists of the last two components of the volume set ID, with the "X" wildcard values replaced by the sequence number associated with the particular volume (see the Volume Set ID Standard below). This ID must always be unique for PDS data volumes. The volume ID must be in upper case. Examples: VG_0002 Volume 2 of the Voyager set MG_0001 The first volume of the Magellan set VGRS_0001 A potential Voyager Radio Science collection 19-18 Chapter 19. Volume Organization and Naming If a volume is redone because of errors in the initial production the volume ID should remain the same and the VOLUME_VERSION_ID incremented. This parameter is contained in the VOLDESC.CAT file on the volume. The version ID should also be placed on the external volume label as "Version n" where n indicates the revision number. A revision number greater than one indicates that the original volume should be replaced with the new version. 19.5 Volume Set Naming The volume set name provides the full, formal name of a group of data volumes containing one or a collection of related data sets. Volume set names may be at most 60 characters in length and must be in upper case. Volume sets are normally considered a single orderable entity. For example, the volume series MISSION TO VENUS consists of the following volume sets: MAGELLAN: THE MOSAIC IMAGE DATA RECORD MAGELLAN: THE ALTIMETRY AND RADIOMETRY DATA RECORD MAGELLAN: THE GLOBAL ALTIMETRY AND RADIOMETRY DATA RECORD PRE-MAGELLAN RADAR AND GRAVITY DATA SET COLLECTION In certain cases, the volume set name can be the same as the volume name, e.g., when the volume set consists of only one volume. 19.5.1 Volume Set ID A volume set is a series of archive volumes that are closely related. In general, the volumes of a set will be distributed and used together. Each volume within the set must have a VOLUME_ID that is unique across the PDS archive. The volume set is identified by a VOLUME_SET_ID of up to 60 characters incorporating the range of constituent VOLUME_IDs. VOLUME_SET_IDs must be in upper case, and are composed by concatenating the following fields, separated by underscores, using abbreviations if necessary: 1. The country of origin (abbreviated) 2. The government branch 3. The discipline within the branch that is producing the volumes 4. A campaign, mission or spacecraft identifier (2 characters) followed by an optional 2-character instrument or product identifier 5. A 4-digit sequence identifier: The first digit(s) represent the volume set; the remaining digits contain "X", representing the range of volumes in the set. Up to four "X" characters may be used. Example USA_NASA_PDS_GO_10XX could be the volume set ID for the Galileo EDR volume set, since there are less than 100 volumes (since the XX placeholder accommodates the range 01 - 99 only). Volume IDs for volumes in the set would then be GO_1001, GO_1002, etc. Chapter 19. Volume Organization and Naming 19-19 Note: Because of the uniqueness constraint, data preparers should consult with their PDS data engineer when it comes time to formulate new VOLUME_ID and VOLUME_SET_ID values. Volume Set IDs Prior to PDS Version 3.2 Prior to version 3.2, the 4-digit sequence identifier (item 5 above) did not include the "X" wildcards. Instead, the last digits represented the volume. For example, on Magellan, a volume set ID "USA_NASA_JPL_MG_0001" was used only for the volume with the volume ID "MG_0001". Subsequent volumes in the same set had volume set IDs that differed in the final field. When a set of volumes was to be distributed as one logical unit, the volume set ID included the range of volume IDs. Example USA_NASA_PDS_VG_0001_TO_VG_0003 for the three volumes that comprise the Voyager Uranus volume set. 19.6 Logical Volume Naming Logical volumes retain the volume and volume set naming used at the physical volume level. For further information, see the "Vol ume Object" in Appendix A of this document. 19.7 Exceptions to This Standard In rare cases volume IDs are subject to restrictions imposed by specific hardware or software environments. Also, volumes made in the past may have IDs that do not meet this standard and there may be compelling reasons for keeping the same volume ID when making a new copy of the data. All new data sets, however, must adhere to this standard wherever possible. 19-20 Chapter 19. Volume Organization and Naming A AAREADME.TXT................................ ................................ ................................ ................ 19-8 ancillary files ................................ ................................ ................................ ......................... 19-2 ancillary volume ................................ ................................ ................................ .................... 19-2 C CALIB subdirectory................................ ................................ ................................ ............. 19-12 calibration files ................................ ................................ ................................ .................... 19-12 calibration subdirectory................................ ................................ ................................ ........19-12 CALINFO.TXT................................ ................................ ................................ ................... 19-12 catalog object files................................ ................................ ................................ ................. 19-8 catalog objects how to supply................................ ................................ ................................ ..................... 19-9 CATALOG subdirectory................................ ................................ ............................. 19-8, 19-12 CATALOG.CAT ................................ ................................ ................................ ................... 19-9 CATINFO.TXT ................................ ................................ ................................ ..................... 19-8 catalog pointer ................................ ................................ ................................ ....................... 19-9 CUMINDEX.LBL................................ ................................ ................................ ............... 19-11 CUMINDEX.TAB................................ ................................ ................................ ............... 19-11 cumulative index................................ ................................ ................................ .................. 19-11 D data files contents................................ ................................ ................................ ............................ 19-10 DATA subdirectory ................................ ................................ ................................ ............. 19-10 19-7 DOCINFO.TXT................................ ................................ ................................ ................... 19-12 DOCUMENT subdirectory................................ ................................ ....................... 19-12, 19-13 19-8 19-12 19-8 19-12 19-14 19-10, 19-13 19-2 Chapter 19. Volume Organization and Naming 19-15 19-14 19-13 19-14 19-12 E ERRATA.TXT ................................ ................................ ................................ ...................... 19-8 EXTRAS subdirectory................................ ................................ ................................ ......... 19-13 EXTRINFO.TXT................................ ................................ ................................ ................. 19-13 G gazetteer table................................ ................................ ................................ ...................... 19-14 GAZETTER subdirectory................................ ................................ ................................ ....19-13 GAZETTER.LBL................................ ................................ ................................ ................ 19-14 GAZETTER.TAB................................ ................................ ................................ ................ 19-14 GAZETTER.TXT................................ ................................ ................................ ................ 19-14 GAZINFO.TXT................................ ................................ ................................ ................... 19-13 GEOMETRY subdirectory................................ ................................ ................................ ...19-14 GEOMINFO.TXT ................................ ................................ ................................ ............... 19-14 I include files ................................ ................................ ................................ ......................... 19-14 INDEX subdirectory................................ ................................ ................................ ............ 19-10 INDEX.LBL................................ ................................ ................................ ........................ 19-11 INDEX.TAB................................ ................................ ................................ ........................ 19-11 INDEX_TABLE................................ ................................ ................................ .................. 19-11 INDXINFO.TXT ................................ ................................ ................................ ................. 19-10 L label files contents................................ ................................ ................................ ............................ 19-10 LABEL subdirectory................................ ................................ ................................ ............ 19-14 LABINFO.TXT................................ ................................ ................................ ................... 19-14 logical volumes multiple logical volumes (definition)................................ ................................ .................. 19-1 naming ................................ ................................ ................................ ............................. 19-19 single logical volume (definition)................................ ................................ ....................... 19-1 Chapter 19. Volume Organization and Naming 19-3 M 19-1 P physical media organization ................................ ................................ ................................ ....................... 19-1 pointers catalog ................................ ................................ ................................ ............................... 19-9 R ROOT Directory Files ................................ ................................ ................................ .........19-8 S SOFTINFO.TXT ................................ ................................ ................................ ................. 19-15 SOFTWARE subdirectory................................ ................................ ................................ ...19-15 T target named features................................ ................................ ................................ ................. 19-13 V 19-16 VOLDESC.CAT................................ ................................ ................................ ......... 19-8, 19-18 VOLDESC.SFD ................................ ................................ ................................ .................... 19-8 VOLINFO.TXT................................ ................................ ................................ ........ 19-12, 19-13 volume ancillary volumes................................ ................................ ................................ ............... 19-2 definition ................................ ................................ ................................ ........................... 19-1 IDs................................ ................................ ................................ ................................ ...19-17 exceptions................................ ................................ ................................ .................... 19-19 logical volume naming ................................ ................................ ................................ .....19-19 names................................ ................................ ................................ ............................... 19-17 VOLUME................................ ................................ ................................ .............................. 19-8 volume index ................................ ................................ ................................ ....................... 19-11 volume organization and naming ................................ ................................ ............................ 19-1 volume set definition ................................ ................................ ................................ ........................... 19-1 IDs................................ ................................ ................................ ................................ ...19-18 names................................ ................................ ................................ ............................... 19-18 organization 19-4 Chapter 19. Volume Organization and Naming many data sets, many volumes ................................ ................................ .............. 19-2, 19-7 many data sets, one physical volume ................................ ................................ ............. 19-6 many data sets, one volume................................ ................................ ............................ 19-1 one data set, many volumes................................ ................................ ................... 19-1, 19-4 one data set, one volume ................................ ................................ ....................... 19-1, 19-3 recommendations ................................ ................................ ................................ ........... 19-7 types ................................ ................................ ................................ ................................ ..19-1 volume set organization many data sets, one volume ................................ ................................ ........................... 19-5 VOLUME_ID................................ ................................ ................................ ...................... 19-18 VOLUME_SET_ID................................ ................................ ................................ ............. 19-18 VOLUME_VERSION_ID................................ ................................ ................................ ...19-18 19-17 19-17 19-18 19-18 19-1 19-1 volumes, logical................................ ................................ ................................ ................... 19-10 Chapter 20. Zip Compression 20-1 Chapter 20. Zip Compression The PDS standards support two different approaches to data compression: 1. In one case, a data object contains numbers that have been encoded using one of several supported methods (e.g., "Huffman first difference") . In this approach, the label describes the compressed data and the ENCODING_TYPE keyword indicates how the data object is to be decompressed by the user. PDS standards support this approach to compression for IMAGE objects only. For more information on compression of individual IMAGE objects, see Section A.19. 2. In the alternative approach, a standard compression method called "Zip" is used. In this case, an entire data file is compressed rather than a particular data object. The user is expected to apply an "Unzip" utility to decompress the file, and the label then describes the decompressed data directly. This chapter describes PDS standards for archiving data using Zip compression. In general, the archiving of data in a compressed format should be used sparingly. Although compression reduces the number of physical volumes, it makes the data more difficult for users to interpret. PDS recommends that data compression be used only in limited situations, such as to compress very large and infrequently used data, or to archive processed data where the source product is readily available in a non-compressed PDS archive. 20.1 Zip Software The Zip method was chosen because the algorithm and supporting software for all major platforms are available without charge to the general user community. The Info-Zip Consortium and Info-Zip working group, for example, provide information and software at these URLs: http://www.info-zip.org/pub/infozip http://www.freesoftware.com/pub/infozip This same information is available on line from PDS at: http://pds.jpl.nasa.gov 20.2 Zip File Labels When archiving data in Zip format, two files need to be considered: (1) the zip file itself, and (2) the data file produced by decompressing the zip file. PDS strongly recommends that these two files have the same name but different extensions: ".ZIP" for the zip file and a more descriptive extension (e.g., ".DAT" or ".IMG") for the unzipped file. The ".ZIP" file extension is reserved exclusively for zip-compressed files within the PDS. 20-2 Chapter 20. Zip Compression PDS does not recommend the practice of compressing multiple data files into a single zip file, unless those files reside in the same directory and have the same name, but different extensions. For example, if file "ABC.IMG" contains an image and file "ABC.TAB" contains a table of additional information relevant to that image, then both files can be archived in the file "ABC.ZIP". This will minimize the potential confusion for a user who may not be able to locate a desired file because it is hidden inside a zip file with a different name. Like all PDS data files, both the zipped and the unzipped data files require labels. Both files must be described by a single, detached PDS label file using the combined-detached label approach (see Section 5.2.2). Attached labels are not permitted for Zip-compressed data, because the user must be able to examine the label before deciding whether or not to decompress the file. In a combined-detached label, each individual file is described as a FILE object. Here is the general framework: PDS_VERSION_ID = PDS3 DATA_SET_ID = ... PRODUCT_ID = ... (other parameters relevant to both Zipped and Unzipped files) OBJECT = COMPRESSED_FILE (parameters describing the compressed file) END_OBJECT = COMPRESSED_FILE OBJECT = UNCOMPRESSED_FILE (parameters describing the first uncompressed file) END_OBJECT = UNCOMPRESSED_FILE OBJECT = UNCOMPRESSED_FILE (parameters describing a second uncompressed file, if present) END_OBJECT = UNCOMPRESSED_FILE END The first FILE object, the COMPRESSED_FILE, refers to the zipped file; additional FILE objects, called UNCOMPRESSED_FILEs, refer to the decompressed data file(s) that the user will obtain by unzipping the first. The zip file is described via a "minimal label" (see Section 5.2.3). The following keywords are required: FILE_NAME = name of the zipfile RECORD_TYPE = UNDEFINED ENCODING_TYPE = ZIP INTERCHANGE_FORMAT = BINARY UNCOMPRESSED_FILE_NAME = a list of the names of all the files archived in the zipfile REQUIRED_STORAGE_BYTES = approximate total number of bytes in the data files DESCRIPTION = a brief description of the zipfile format Chapter 20. Zip Compression 20-3 Typically, the DESCRIPTION is given as a pointer to a file called "ZIPINFO.TXT" found in the DOCUMENT directory on the same volume. The subsequent UNCOMPRESSED_FILE object(s) contain complete descriptions of the data files obtained by unzipping the zip file. 20.3 Packaging Zip Archives on Volumes A volume containing zip files with combined-detached labels as presented above conforms to all established PDS standards provided both the zip file and its constituent data files are archived. The unique feature of a Zip-compressed PDS archive volume is that only the zip files appear; the UNCOMPRESSED_FILE objects described by the labels are not present on the volume, but can be obtained by unzipping the zip files provided. In the interests of long-term archiving, a PDS archive zip file must include all the support files required to completely reconstitute the labeled data files. Specifically, the zipped archive must include not only the data files, but also the label file(s) for the uncompressed data. Ideally, any .FMT files referenced by ^STRUCTURE keywords in the labels should also be included in the zip file. Note: These additional .LBL and .FMT files do not need to be described by UNCOMPRESSED_FILE objects in the label, because PDS label and format files never require labels. Furthermore, the sizes of these files do not need to be included in the value of the REQUIRED_STORAGE_BYTES keyword. However, the names of these files do need to be included in the list of UNCOMPRESSED_FILE_NAME values. 20.4 Label Example The following is an example of a PDS label for a Zip-compressed data file. PDS_VERSION_ID = PDS3 DATA_SET_ID = "HST-S-WFPC2-4-RPX-V1.0" SOURCE_FILE_NAME = "U2ON0101T.SHF" PRODUCT_TYPE = OBSERVATION_HEADER PRODUCT_CREATION_TIME = 1998-01-31T12:00:00 OBJECT = COMPRESSED_FILE FILE_NAME = "0101_SHF.ZIP" RECORD_TYPE = UNDEFINED ENCODING_TYPE = ZIP INTERCHANGE_FORMAT = BINARY UNCOMPRESSED_FILE_NAME = {"0101_SHF.DAT", "0101_SHF.LBL"} REQUIRED_STORAGE_BYTES = 34560 ^DESCRIPTION = "ZIPINFO.TXT" END_OBJECT = COMPRESSED_FILE OBJECT = UNCOMPRESSED_FILE FILE_NAME = "0101_SHF.DAT" RECORD_TYPE = FIXED_LENGTH 20-4 Chapter 20. Zip Compression RECORD_BYTES = 2880 FILE_RECORDS = 12 ^FITS_HEADER = ("0101_SHF.DAT", 1 ) ^HEADER_TABLE = ("0101_SHF.DAT", 25921 ) OBJECT = FITS_HEADER HEADER_TYPE = FITS INTERCHANGE_FORMAT = ASCII RECORDS = 7 BYTES = 20160 ^DESCRIPTION = "FITS.TXT" END_OBJECT = FITS_HEADER OBJECT = HEADER_TABLE NAME = HEADER_PACKET INTERCHANGE_FORMAT = BINARY ROWS = 965 COLUMNS = 1 ROW_BYTES = 2 DESCRIPTION = "This is the HST standard header packet containing observation parameters. It is stored as a sequence of 965 two-byte integers. For more detailed information, contact Space Telescope Science Institute." OBJECT = COLUMN NAME = PACKET_VALUES DATA_TYPE = MSB_INTEGER START_BYTE = 1 BYTES = 2 END_OBJECT = COLUMN END_OBJECT = HEADER_TABLE END_OBJECT = UNCOMPRESSED_FILE END 20.5 ZIPINFO.TXT Example While the ZIPINFO.TXT file is not required, it is strongly recommended that this file be included as part of the process of documenting the contents of a zip file. The following is an example ZIPINFO.TXT file and the type of information that should be included in the ZIPINFO.TXT file: PDS_VERSION_ID = PDS3 RECORD_TYPE = STREAM OBJECT = TEXT PUBLICATION_DATE = 1999-07-26 NOTE = "This file provides an overview of the ZIP file format." END_OBJECT = TEXT Chapter 20. Zip Compression 20-5 END Many of the files in this data set are compressed using Zip format. They are all indicated by the extension ".ZIP". ZIP is a utility that compresses files and also allows for multiple files to be stored in a single Zip archive. You will need the UNZIP utility to extract the files. The SOFTWARE directory on this volume contains a complete description of the Zip file format and also the complete source code for the UNZIP utility. The file format and file decompression algorithms are described in the file SOFTWARE/APPNOTE.TXT. It is far simpler to obtain a pre-built binary of the UNZIP application for your platform. Binaries for most platforms are available from the Info-ZIP web site, currently at these URLs: http://www.info-zip.org/pub/infozip http://www.freesoftware.com/pub/infozip The same information can also be found a the PDS Central Node's web site, currently at: http://pds.jpl.nasa.gov/ 20.6 Additional Files As of this writing, Zip appears to be a robust standard with a long future of general use. Nevertheless, PDS long-term archiving goals reach well past the lifetime of many popular standards, past and present. For this reason, a ny volume containing zip files is required to contain a complete description of the zip file format with sample "Unzip" source code. This information must be located in an appropriate subdirectory of the SOFTWARE directory tree. The required text and source code may be obtained directly from the Info-Zip web site or by contacting a Central Node data engineer. 20-6 Chapter 20. Zip Compression COMPRESSED_FILE, 20-2 data compression, 20-1 Zip, 20-1 example, 20-3 file format, 20-1 on archive volumes, 20-3 DOCUMENT subdirectory, 20-2 ENCODING_TYPE, 20-1 FILE object, 20-2 IMAGE objects compression, 20-1 minimal labels and compressed data, 20-2 REQUIRED_STORAGE_BYTES, 20-3 UNCOMPRESSED_FILE, 20-2 UNCOMPRESSED_FILE_NAME, 20-3 Zip compression, 20-1 ZIPINFO.TXT, 20-2, 20-4 Appendix A. PDS Data Object Definitions A-1 Appendix A. PDS Data Object Definitions This section provides an alphabetical reference of approved PDS data object definitions used for labeling primary and secondary data objects. The definitions include descriptions, lists of required and optional keywords, lists of required and optional subobjects (or child objects), and one or more examples of specific objects. For a more detailed discussion on primary and secondary data objects, see the Data Products chapter in this document. Data object definitions are refined and augmented from time to time, as user community needs arise, so object definitions for products designed under older versions of the Standards may differ significantly. To check the current state of any object definition, consult a PDS data engineer or either of these URLs: PDS Catalog Search: http://pdsproto.jpl.nasa.gov/onlinecatalog/top.cfm Data Dictionary Search: http://pdsproto.jpl.nasa.gov/ddcolstdval/newdd/top.cfm The examples provided in this Appendix are based on both existing and planned PDS archive products, modified to reflect the current version of the PDS Standards. Additional examples may be obtained by contacting a PDS Data Engineer. NOTE: Any keywords in the Planetary Science Data Dictionary may also be included in a specific data object definition. Primitive Objects There exist four primitive data objects: ARRAY; BIT_ELEMENT; COLLECTION; and ELEMENT. Although these objects are available, they should only be used after careful consideration of the current high-level PDS Data Objects. Please see the PDS Objects chapter in this document for guidelines on the use of primitive objects. A-2 Appendix A. PDS Data Object Definitions Chapter Contents Appendix A. PDS Data Object Definitions................................ ................................ ...... A-1 A.1 ALIAS................................ ................................ ................................ ................... A-3 A.2 ARRAY (Primitive Data Object)................................ ................................ ............ A-4 A.3 BIT_COLUMN................................ ................................ ................................ ..... A-8 A.4 BIT ELEMENT (Primitive Data Object)................................ .............................. A-11 A.5 CATALOG................................ ................................ ................................ .......... A-12 A.6 COLLECTION (Primitive Data Object)................................ ............................... A-15 A.7 COLUMN ................................ ................................ ................................ ........... A-16 A.8 CONTAINER................................ ................................ ................................ ...... A-20 A.9 DATA_PRODUCER................................ ................................ ........................... A-27 A.10 DATA_SUPPLIER................................ ................................ .............................. A-29 A.11 DIRECTORY................................ ................................ ................................ ...... A-31 A.12 DOCUMENT................................ ................................ ................................ ...... A-33 A.13 ELEMENT (Primitive Data Object)................................ ................................ ..... A-36 A.14 FILE................................ ................................ ................................ .................... A-38 A.15 GAZETTEER_TABLE ................................ ................................ ....................... A-42 A.16 HEADER ................................ ................................ ................................ ............ A-52 A.17 HISTOGRAM................................ ................................ ................................ ..... A-54 A.18 HISTORY................................ ................................ ................................ ........... A-57 A.19 IMAGE ................................ ................................ ................................ ............... A-61 A.20 INDEX_TABLE................................ ................................ ................................ .. A-66 A.21 PALETTE ................................ ................................ ................................ ........... A-71 A.22 QUBE ................................ ................................ ................................ ................. A-74 A.23 SERIES................................ ................................ ................................ ............... A-82 A.24 SPECTRUM................................ ................................ ................................ ........ A-87 A.25 SPICE KERNEL ................................ ................................ ................................ . A-90 A.26 TABLE................................ ................................ ................................ ................ A-93 A.27 TEXT................................ ................................ ................................ ................ A-114 A.28 VOLUME ................................ ................................ ................................ ......... A-116 Appendix A. PDS Data Object Definitions A-3 A.1 ALIAS The ALIAS object provides a method for identifying alternate terms or names for approved data elements or objects within a data system. The ALIAS object is an optional sub-object of the COLUMN object. A.1.1 Required Keywords 1. ALIAS_NAME 2. USAGE_NOTE A.1.2 Optional Keywords Any A.1.3 Required Objects None A.1.4 Optional Objects None A.1.5 Example The following label fragment shows the ALIAS object included as a sub-object of a COLUMN: OBJECT = COLUMN NAME = ALT_FOOTPRINT_LONGITUDE START_BYTE = 1 DATA_TYPE = REAL BYTES = 10 OBJECT = ALIAS ALIAS_NAME = AR_LON USAGE_NOTE = "MAGELLAN MIT ARCDR SIS" END_OBJECT = ALIAS END_OBJECT = COLUMN A-4 Appendix A. PDS Data Object Definitions A.2 ARRAY (Primitive Data Object) The ARRAY object is provided to describe dimensioned arrays of homogeneous objects. Note that an ARRAY may contain only a single sub-object, which can itself be another ARRAY or COLLECTION if required. A maximum of 6 axes is allowed in an ARRAY. By default, the rightmost axis is the fastest varying axis. The optional "AXIS_*" elements are used to describe the variation between successive objects in the ARRAY. Values for AXIS_ITEMS and "AXIS_*" elements for multidimensional arrays are listed in axis order. The optional START_BYTE data element provides the starting location relative to an enclosing object. If a START_BYTE is not specified, a value of 1 is assumed. A.2.1 Required Keywords 1. AXES 2. AXIS_ITEMS 3. NAME A.2.2 Optional Keywords 1. AXIS_INTERVAL 2. AXIS_NAME 3. AXIS_UNIT 4. AXIS_START 5. AXIS_STOP 6. AXIS_ORDER_TYPE 7. CHECKSUM 8. DESCRIPTION 9. INTERCHANGE_FORMAT 10. START_BYTE A.2.3 Required Objects None Note that while no specific sub-object is required, the ARRAY object must contain at least one of the optional objects, following. That is, a null ARRAY object may not be defined. Appendix A. PDS Data Object Definitions A-5 A.2.4 Optional Objects 1. ARRAY 2. BIT_ELEMENT 3. COLLECTION 4. ELEMENT A.2.5 Example 1 Following is an example of a two-dimensional spectrum array in a detached label. PDS_VERSION_ID = PDS3 RECORD_TYPE = FIXED_LENGTH RECORD_BYTES = 1600 FILE_RECORDS = 180 DATA_SET_ID = "IHW-C-SPEC-2-EDR-HALLEY-V1.0" OBSERVATION_ID = "704283" TARGET_NAME = "HALLEY" INSTRUMENT_HOST_NAME = "IHW SPECTROSCOPY AND SPECTROPHOTOMETRY NETWORK" INSTRUMENT_NAME = "IHW SPECTROSCOPY AND SPECTROPHOTOMETRY" PRODUCT_ID = "704283" OBSERVATION_TIME = 1986-05-09T04:10:20.640Z START_TIME = 1986-05-09T04:07:50.640Z STOP_TIME = UNK PRODUCT_CREATION_TIME = 1993-01-01T00:00:00.000Z ^ARRAY = "SPEC2702.DAT" /* Description of Object in File */ OBJECT = ARRAY NAME = "2D SPECTRUM" INTERCHANGE_FORMAT = BINARY AXES = 2 AXIS_ITEMS = (180,800) AXIS_NAME = ("RHO","APPROXIMATE WAVELENGTH") AXIS_UNIT = (ARCSEC,ANGSTROMS) AXIS_INTERVAL = (1.5,7.2164) AXIS_START = (1.0,5034.9) OBJECT = ELEMENT DATA_TYPE = MSB_INTEGER BYTES = 2 NAME = COUNT DERIVED_MAXIMUM = 2.424980E+04 DERIVED_MINIMUM = 0.000000E+00 OFFSET = 0.000000E+00 A-6 Appendix A. PDS Data Object Definitions SCALING_FACTOR = 1.000000E+00 NOTE = "Conversion factor 1.45 may be applied to data to estimate photons/sq m/sec/angstrom at 6800 angstroms." END_OBJECT = ELEMENT END_OBJECT = ARRAY END A.2.6 Example 2 The following label shows ARRAY, COLLECTION and ELEMENT primitive objects all used together. PDS_VERSION_ID = PDS3 RECORD_TYPE = FIXED_LENGTH RECORD_BYTES = 122 FILE_RECORDS = 7387 ^ARRAY = "MISCHA01.DAT" DATA_SET_ID = "VEGA1-C-MISCHA-3-RDR-HALLEY-V1.0" TARGET_NAME = HALLEY SPACECRAFT_NAME = "VEGA 1" INSTRUMENT_NAME = "MAGNETOMETER" PRODUCT_ID = "XYZ" START_TIME = "UNK" STOP_TIME = "UNK" SPACECRAFT_CLOCK_START_COUNT = "UNK" SPACECRAFT_CLOCK_STOP_COUNT = "UNK" NOTE = "VEGA 1 MISCHA DATA" OBJECT = ARRAY NAME = MISCHA_DATA_FILE INTERCHANGE_FORMAT = BINARY AXES = 1 AXIS_ITEMS = 7387 DESCRIPTION = "This file contains an array of fixed- length Mischa records." OBJECT = COLLECTION NAME = MISCHA_RECORD BYTES = 122 DESCRIPTION = "Each record in this file consists of a time tag followed by a 20-element array of magnetic field vectors." OBJECT = ELEMENT NAME = START_TIME BYTES = 2 DATA_TYPE = MSB_INTEGER START_BYTE = 1 Appendix A. PDS Data Object Definitions A-7 END_OBJECT = ELEMENT OBJECT = ARRAY NAME = MAGNETIC_FIELD_ARRAY AXES = 2 AXIS_ITEMS = (3,20) START_BYTE = 3 AXIS_NAME = ("XYZ_COMPONENT","TIME" ) AXIS_UNIT = ("N/A" ,"SECOND") AXIS_INTERVAL = ("N/A" , 0.2 ) DESCRIPTION = "Magnetic field vectors were recorded at the rate of 10 per second. The START_TIME field gives the time at which the first vector in the record was recorded. Successive vectors were recorded at 0.2 second intervals." OBJECT = ELEMENT NAME = MAG_FIELD_COMPONENT_VALUE BYTES = 2 DATA_TYPE = MSB_INTEGER START_BYTE = 1 END_OBJECT = ELEMENT END_OBJECT = ARRAY END_OBJECT = COLLECTION END_OBJECT = ARRAY END A-8 Appendix A. PDS Data Object Definitions A.3 BIT_COLUMN The BIT_COLUMN object identifies a string of bits that do not fall on even byte boundaries and therefore cannot be described as a distinct COLUMN. BIT_COLUMNs defined within columns are analogous to columns defined within rows. Notes: (1) The Planetary Data System recommends that all fields (within new objects) be defined on byte boundaries. This precludes having multiple values strung together in bit strings, as occurs in the BIT_COLUMN object. (2) BIT_COLUMN is intended for use in describing existing binary data strings, but is not recommended for use in defining new data objects because it will not be recognized by most general purpose software. (3) A BIT_COLUMN must not contain embedded objects. BIT_COLUMNs of the same format and size may be specified as a single BIT_COLUMN by using the ITEMS, ITEM_BITS, and ITEM_OFFSET elements. The ITEMS data element is used to indicate the number of occurrences of a bit string. A.3.1 Required Keywords 1. NAME 2. BIT_DATA_TYPE 3. START_BIT 4. BITS (required for BIT_COLUMNs without items) 5. DESCRIPTION A.3.2 Optional Keywords 1. BIT_MASK 2. BITS (optional for BIT_COLUMNSs with ITEMS) 3. FORMAT 4. INVALID_CONSTANT 5. ITEMS 6. ITEM_BITS 7. ITEM_OFFSET 8. MINIMUM 9. MAXIMUM 10. MISSING_CONSTANT Appendix A. PDS Data Object Definitions A-9 11. OFFSET 12. SCALING_FACTOR 13. UNIT A.3.3 Required Objects None A.3.4 Optional Objects None A.3.5 Example The label fragment below was extracted from a larger example which can be found under the CONTAINER object. The BIT_COLUMN object can be a sub-object only of a COLUMN object, but that COLUMN may itself be part of a TABLE, SPECTRUM, SERIES or CONTAINER object. ____________________________________________________________________________ OBJECT = COLUMN NAME = PACKET_ID DATA_TYPE = LSB_BIT_STRING START_BYTE = 1 BYTES = 2 VALID_MINIMUM = 0 VALID_MAXIMUM = 7 DESCRIPTION = "Packet_id constitutes one of three parts in the primary source information header applied by the Payload Data System (PDS) to the MOLA telemetry packet at the time of creation of the packet prior to transfer frame creation." OBJECT = BIT_COLUMN NAME = VERSION_NUMBER BIT_DATA_TYPE = MSB_UNSIGNED_INTEGER START_BIT = 1 BITS = 3 MINIMUM = 0 MAXIMUM = 7 DESCRIPTION = "These bits identify Version 1 as the Source Packet structure. These bits shall be set to '000'." END_OBJECT = BIT_COLUMN A-10 Appendix A. PDS Data Object Definitions OBJECT = BIT_COLUMN NAME = SPARE BIT_DATA_TYPE = MSB_UNSIGNED_INTEGER START_BIT = 4 BITS = 1 MINIMUM = 0 MAXIMUM = 0 DESCRIPTION = "Reserved spare. This bit shall be set to '0'" END_OBJECT = BIT_COLUMN OBJECT = BIT_COLUMN NAME = FLAG BIT_DATA_TYPE = BOOLEAN START_BIT = 5 BITS = 1 MINIMUM = 0 MAXIMUM = 0 DESCRIPTION = "This flag signals the presence or absence of a Secondary Header data structure within the Source Packet. This bit shall be set to '0' since no Secondary Header formatting standards currently exist for Mars Observer." END_OBJECT = BIT_COLUMN OBJECT = BIT_COLUMN NAME = ERROR_STATUS BIT_DATA_TYPE = MSB_UNSIGNED_INTEGER START_BIT = 6 BITS = 3 MINIMUM = 0 MAXIMUM = 7 DESCRIPTION = "This field identifies in part the individual application process within the spacecraft that created the Source Packet data." END_OBJECT = BIT_COLUMN OBJECT = BIT_COLUMN NAME = INSTRUMENT_ID BIT_DATA_TYPE = MSB_UNSIGNED_INTEGER START_BIT = 9 BITS = 8 MINIMUM = "N/A" MAXIMUM = "N/A" DESCRIPTION = "This field identifies in part the individual application process within the spacecraft that created the Source Packet data. 00100011 is the bit pattern for MOLA." END_OBJECT = BIT_COLUMN END_OBJECT = COLUMN Appendix A. PDS Data Object Definitions A-11 A.4 BIT ELEMENT (Primitive Data Object) Under review. A-12 Appendix A. PDS Data Object Definitions A.5 CATALOG The CATALOG object is used within a VOLUME object to reference the completed PDS high- level catalog object set. The catalog object set provides additional information related to the data sets on a volume. Please refer to the File Specification and Naming chapter in this document for more information. A.5.1 Required Keywords None A.5.2 Optional Keywords 1. DATA_SET_ID 2. LOGICAL_VOLUME_PATHNAME 3. LOGICAL_VOLUMES A.5.3 Required Objects 1. DATA_SET 2. INSTRUMENT 3. INSTRUMENT_HOST 4. MISSION A.5.4 Optional Objects 1. DATA_SET_COLLECTION 2. PERSONNEL 3. REFERENCE 4. TARGET A.5.5 Example The example below is a VOLDESC.CAT file for a volume containing multiple data sets. In this case, the catalog objects are provided in separate files referenced by pointers. PDS_VERSION_ID = PDS3 LABEL_REVISION_NOTE ="1998-07-01, S. Joy (PPI);" RECORD_TYPE = STREAM Appendix A. PDS Data Object Definitions A-13 OBJECT = VOLUME VOLUME_SERIES_NAME = "VOYAGERS TO THE OUTER PLANETS" VOLUME_SET_NAME = "VOYAGER NEPTUNE PLANETARY PLASMA INTERACTIONS DATA" VOLUME_SET_ID = USA_NASA_PDS_VG_1001 VOLUMES = 1 VOLUME_NAME = "VOYAGER NEPTUNE PLANETARY PLASMA INTERACTIONS DATA" VOLUME_ID = VG_1001 VOLUME_VERSION_ID = "VERSION 1" VOLUME_FORMAT = "ISO-9660" MEDIUM_TYPE = "CD-ROM" PUBLICATION_DATE = 1992-11-13 DESCRIPTION = "This volume contains a collection of non-imaging Planetary Plasma datasets from the Voyager 2 spacecraft encounter with Neptune. Included are datasets from the Cosmic Ray System (CRS), Plasma System (PLS), Plasma Wave System (PWS), Planetary Radio Astronomy (PRA), Magnetometer (MAG), and Low Energy Charged Particle (LECP) instruments, as well as spacecraft position vectors (POS) in several coordinate systems. The volume also contains documentation and index files to support access and use of the data." DATA_SET_ID = {"VG2-N-CRS-3-RDR-D1-6SEC-V1.0", "VG2-N-CRS-4-SUMM-D1-96SEC-V1.0", "VG2-N-CRS-4-SUMM-D2-96SEC-V1.0", "VG2-N-LECP-4-SUMM-SCAN-24SEC-V1.0", "VG2-N-LECP-4-RDR-STEP-12.8MIN-V1.0", "VG2-N-MAG-4-RDR-HG-COORDS-1.92SEC-V1.0", "VG2-N-MAG-4-SUMM-HG-COORDS-48SEC-V1.0", "VG2-N-MAG-4-RDR-HG-COORDS-9.6SEC-V1.0", "VG2-N-MAG-4-SUMM-NLSCOORDS-12SEC-V1.0", "VG2-N-PLS-5-RDR-2PROMAGSPH-48SEC-V1.0", "VG2-N-PLS-5-RDR-ELEMAGSPHERE-96SEC-V1.0", "VG2-N-PLS-5-RDR-IONMAGSPHERE-48SEC-V1.0", "VG2-N-PLS-5-RDR-IONLMODE-48SEC-V1.0", "VG2-N-PLS-5-RDR-IONMMODE-12MIN-V1.0", "VG2-N-PLS-5-RDR-ION-INBNDWIND-48SEC-V1.0", "VG2-N-POS-5-RDR-HGHGCOORDS-48SEC-V1.0", "VG2-N-POS-5-SUMM-NLSCOORDS-12-48SEC-V1.0", "VG2-N-PRA-4-SUMM-BROWSE-SEC-V1.0", "VG2-N-PRA-2-RDR-HIGHRATE-60MS-V1.0", "VG2-N-PWS-2-RDR-SA-4SEC-V1.0", "VG2-N-PWS-4-SUMM-SA-48SEC-V1.0", "VG2-N-PWS-1-EDR-WFRM-60MS-V1.0"} OBJECT = DATA_PRODUCER INSTITUTION_NAME = "UNIVERSITY OF CALIFORNIA, LOS ANGELES" FACILITY_NAME = "PDS PLANETARY PLASMA INTERACTIONS NODE" A-14 Appendix A. PDS Data Object Definitions FULL_NAME = "DR. RAYMOND WALKER" DISCIPLINE_NAME = "PLASMA INTERACTIONS" ADDRESS_TEXT = "UCLA IGPP LOS ANGELES, CA 90024 USA" END_OBJECT = DATA_PRODUCER OBJECT = DATA_SUPPLIER INSTITUTION_NAME = "NATIONAL SPACE SCIENCE DATA CENTER" FACILITY_NAME = "NATIONAL SPACE SCIENCE DATA CENTER" FULL_NAME = "NATIONAL SPACE SCIENCE DATA CENTER" DISCIPLINE_NAME = "NATIONAL SPACE SCIENCE DATA CENTER" ADDRESS_TEXT = "Code 633 \n Goddard Space Flight Center \n Greenbelt, Maryland, 20771, USA" TELEPHONE_NUMBER = "3012866695" ELECTRONIC_MAIL_TYPE = "NSI/DECNET" ELECTRONIC_MAIL_ID = "NSSDCA::REQUEST" END_OBJECT = DATA_SUPPLIER OBJECT = CATALOG ^MISSION_CATALOG = "MISSION.CAT" ^INSTRUMENT_HOST_CATALOG = "INSTHOST.CAT" ^INSTRUMENT_CATALOG = {"CRS_INST.CAT", "LECPINST.CAT", "MAG_INST.CAT", "PLS_INST.CAT", "PRA_INST.CAT", "PWS_INST.CAT"} ^DATA_SET_CATALOG = {"CRS_DS.CAT", "LECP_DS.CAT", "MAG_DS.CAT", "PLS_DS.CAT", "POS_DS.CAT", "PRA_DS.CAT", "PWS_DS.CAT"} ^TARGET_CATALOG = TARGET.CAT ^PERSONNEL_CATALOG = PERSON.CAT ^REFERENCE_CATALOG = REF.CAT END_OBJECT = CATALOG END_OBJECT = VOLUME END Appendix A. PDS Data Object Definitions A-15 A.6 COLLECTION (Primitive Data Object) The COLLECTION object allows the ordered grouping of heterogeneous objects into a structure. The COLLECTION object may contain a mixture of different object types, including other COLLECTIONs. The optional START_BYTE data element provides the starting location relative to an enclosing object. If a START_BYTE is not specified, a value of 1 is assumed. A.6.1 Required Keywords 1. BYTES 2. NAME A.6.2 Optional Keywords 1. DESCRIPTION 2. CHECKSUM 3. INTERCHANGE_FORMAT 4. START_BYTE A.6.3 Required Objects None Note that although a specific sub-object is not required, the COLLECTION must contain at least one of the optional objects listed following. That is, a null COLLECTION may not be defined. A.6.4 Optional Objects 1. ELEMENT 2. BIT_ELEMENT 3. ARRAY 4. COLLECTION A.6.5 Example Please refer to Section A.2.6, Example 2 under the ARRAY object for an illustration of the COLLECTION object used in conjunction with other primitive objects. A-16 Appendix A. PDS Data Object Definitions A.7 COLUMN The COLUMN object identifies a single column in a data object. Notes: (1) Current PDS data objects that include COLUMN objects are the TABLE, CONTAINER, SPECTRUM and SERIES objects. (2) COLUMNs must not themselves contain embedded COLUMN objects. (3) COLUMNs of the same format and size which constitute a vector may be specified as a single COLUMN by using the ITEMS, ITEM_BYTES, and ITEM_OFFSET elements. The ITEMS data element indicates the number of occurrences of the field (i.e., elements in the vector). (4) BYTES and ITEM_BYTES counts do not include leading or trailing delimiters or line terminators. (5) For a COLUMN containing ITEMS, the value of BYTES should represent the total size of the column including delimiters between the items. (See examples 1 and 2 below.) A.7.1 Required Keywords 1. NAME 2. DATA_TYPE 3. START_BYTE 4. BYTES (required for COLUMNs without ITEMs) A.7.2 Optional Keywords 1. BIT_MASK 2. BYTES (optional for COLUMNs with ITEMs) 3. COLUMN_NUMBER 4. DERIVED_MAXIMUM 5. DERIVED_MINIMUM 6. DESCRIPTION 7. FORMAT 8. INVALID_CONSTANT 9. ITEM_BYTES 10. ITEM_OFFSET 11. ITEMS 12. MAXIMUM 13. MAXIMUM_SAMPLING_PARAMETER 14. MINIMUM Appendix A. PDS Data Object Definitions A-17 15. MINIMUM_SAMPLING_PARAMETER 16. MISSING_CONSTANT 17. OFFSET 18. SAMPLING_PARAMETER_INTERVAL 19. SAMPLING_PARAMETER_NAME 20. SAMPLING_PARAMETER_UNIT 21. SCALING_FACTOR 22. UNIT 23. VALID_MAXIMUM 24. VALID_MINIMUM A.7.3 Required Objects None A.7.4 Optional Objects 1. BIT_COLUMN 2. ALIAS A.7.5 Example 1 The label fragment below shows a simple COLUMN object, in this case from an ASCII TABLE. OBJECT = COLUMN NAME = "DETECTOR TEMPERATURE" START_BYTE = 27 BYTES = 5 DATA_TYPE = ASCII_REAL FORMAT = "F5.1" UNIT = "KELVIN" MISSING_CONSTANT = 999.9 END_OBJECT = COLUMN A.7.6 Example 2 The fragment below shows two COLUMNs containing multiple items. The first COLUMN is a vector containing three ASCII_INTEGER items: xx, yy, zz. The second COLUMN contains three character items: "xx", "yy" and "zz". Note that the value of BYTES includes the comma delimiters between items, but the ITEM_BYTES value does not. The ITEM_OFFSET is the number of bytes from the beginning of one item to the beginning of the next. OBJECT = COLUMN NAME = COLUMN1XYZ A-18 Appendix A. PDS Data Object Definitions DATA_TYPE = ASCII_INTEGER START_BYTE = 1 BYTES = 8 /*includes delimiters*/ ITEMS = 3 ITEM_BYTES = 2 ITEM_OFFSET = 3 END_OBJECT = COLUMN OBJECT = COLUMN NAME = COLUMN2XYZ DATA_TYPE = CHARACTER START_BYTE = 2 /* value does not include leading quote */ BYTES = 12 /* value does not include leading and */ /* trailing quotes */ ITEMS = 3 ITEM_BYTES = 2 /* value does not include leading and */ /* trailing quotes */ ITEM_OFFSET = 5 /* value does not include leading quote */ END_OBJECT = COLUMN A.7.7 Example 3 The fragment below was extracted from a larger example which can be found under the CONTAINER object. It illustrates a single COLUMN object subdivided into several BIT_COLUMN fields. OBJECT = COLUMN NAME = PACKET_ID DATA_TYPE = LSB_BIT_STRING START_BYTE = 1 BYTES = 2 VALID_MINIMUM = 0 VALID_MAXIMUM = 7 DESCRIPTION = "Packet_id constitutes one of three parts in the primary source information header applied by the Payload Data System (PDS) to the MOLA telemetry packet at the time of creation of the packet prior to transfer frame creation. " OBJECT = BIT_COLUMN NAME = VERSION_NUMBER BIT_DATA_TYPE = MSB_UNSIGNED_INTEGER START_BIT = 1 BITS = 3 MINIMUM = 0 MAXIMUM = 7 DESCRIPTION = "These bits identify Version 1 as the Source Packet structure. These bits shall be set to '000'." END_OBJECT = BIT_COLUMN Appendix A. PDS Data Object Definitions A-19 OBJECT = BIT_COLUMN NAME = SPARE BIT_DATA_TYPE = MSB_UNSIGNED_INTEGER START_BIT = 4 BITS = 1 MINIMUM = 0 MAXIMUM = 0 DESCRIPTION = "Reserved spare. This bit shall be set to '0'" END_OBJECT = BIT_COLUMN OBJECT = BIT_COLUMN NAME = FLAG BIT_DATA_TYPE = BOOLEAN START_BIT = 5 BITS = 1 MINIMUM = 0 MAXIMUM = 0 DESCRIPTION = "This flag signals the presence or absence of a Secondary Header data structure within the Source Packet. This bit shall be set to '0' since no Secondary Header formatting standards currently exist for Mars Observer." END_OBJECT = BIT_COLUMN OBJECT = BIT_COLUMN NAME = ERROR_STATUS BIT_DATA_TYPE = MSB_UNSIGNED_INTEGER START_BIT = 6 BITS = 3 MINIMUM = 0 MAXIMUM = 7 DESCRIPTION = "This field identifies in part the individual application process within the spacecraft that created the Source Packet data." END_OBJECT = BIT_COLUMN OBJECT = BIT_COLUMN NAME = INSTRUMENT_ID BIT_DATA_TYPE = MSB_UNSIGNED_INTEGER START_BIT = 9 BITS = 8 MINIMUM = "N/A" MAXIMUM = "N/A" DESCRIPTION = "This field identifies in part the individual application process within the spacecraft that creeated the Source Packet data. 00100011 is the bit pattern for MOLA." END_OBJECT = BIT_COLUMN END_OBJECT = COLUMN A-20 Appendix A. PDS Data Object Definitions A.8 CONTAINER The CONTAINER object is used to group a set of sub-objects (such as COLUMNs) that repeat within a data object (such as a TABLE). Use of the CONTAINER object allows repeating groups to be defined within a data structure. A.8.1 Required Keywords 1. NAME 2. START_BYTE 3. BYTES 4. REPETITIONS 5. DESCRIPTION A.8.2 Optional Keywords Any A.8.3 Required Objects None A.8.4 Optional Objects 1. COLUMN 2. CONTAINER A.8.5 Example The set of labels and format fragments below illustrates a data product layout in which the CONTAINER object is used. The primary data product is a TABLE of data records. Each record within the TABLE begins with 48 columns (143 bytes) of engineering data. The data product acquires science data from seven different frames. Since the data from each frame are formatted identically, one CONTAINER description suffices for all seven frames. In this example there are two CONTAINER objects. The first CONTAINER object describes the repeating frame information. Within this CON TAINER there is a second CONTAINER object in which a 4-byte set of three COLUMN objects repeats 20 times. The use of the second Appendix A. PDS Data Object Definitions A-21 CONTAINER object permits the data supplier to describe the three COLUMNS (4 bytes) once, instead of specifying sixty column definitions. In the first CONTAINER, the keyword REPETITIONS is equal to 7. In the second CONTAINER, REPETITIONS equals 20. Both CONTAINER objects contain a collection of COLUMN objects. In most cases it is preferable to save space in the product label by placing COLUMN objects in a separate file and pointing to that file from within the CONTAINER object. This attached label example describes the above TABLE structure using CONTAINER objects. PDS_VERSION_ID = PDS3 RECORD_TYPE = FIXED_LENGTH FILE_RECORDS = 467 RECORD_BYTES = 1080 LABEL_RECORDS = 4 FILE_NAME = "AEDR.A01" ^MOLA_SCIENCE_MODE_TABLE = 5 DATA_SET_ID = "MO-M-MOLA-1-AEDR-L0-V1.0" PRODUCT_ID = "MOLA-AEDR-10010-0001" SPACECRAFT_NAME = MARS_OBSERVER INSTRUMENT_ID = MOLA INSTRUMENT_NAME = MARS_OBSERVER_LASER_ALTIMETER TARGET_NAME = MARS SOFTWARE_NAME = "BROWSER 17.1" UPLOAD_ID = "5.3" PRODUCT_RELEASE_DATE = 1994-12-29T02:10:09.321 START_TIME = 1994-09-29T04:12:43.983 STOP_TIME = 1994-09-29T06:09:54.221 SPACECRAFT_CLOCK_START_COUNT = "12345" SPACECRAFT_CLOCK_STOP_COUNT = "12447" PRODUCT_CREATION_TIME = 1994-01-29T07:30:333 A-22 Appendix A. PDS Data Object Definitions MISSION_PHASE_NAME = MAPPING ORBIT_NUMBER = 0001 PRODUCER_ID = MO_MOLA_TEAM PRODUCER_FULL_NAME = "DAVID E. SMITH" PRODUCER_INSTITUTION_NAME = "GODDARD SPACE FLIGHT CENTER" DESCRIPTION = "This data product contains the aggregation of MOLA telemetry packets by Orbit. All Experiment Data Record Packets retrieved from the PDB are collected in this data product. The AEDR data product is put together with the Project-provided software tool Browser." OBJECT = MOLA_SCIENCE_MODE_TABLE INTERCHANGE_FORMAT = BINARY ROWS = 463 COLUMNS = 97 ROW_BYTES = 1080 ^STRUCTURE = "MOLASCI.FMT" DESCRIPTION = "This table is one of two that describe the arrangement of information on the Mars Observer Laser Altimeter (MOLA) Aggregated Engineering Data Record (AEDR). ..." END_OBJECT = MOLA_SCIENCE_MODE_TABLE ... END Contents of the MOLASCI.FMT file: OBJECT = COLUMN NAME = PACKET_ID DATA_TYPE = LSB_BIT_STRING START_BYTE = 1 BYTES = 2 VALID_MINIMUM = 0 VALID_MAXIMUM = 7 DESCRIPTION = "Packet_id constitutes one of three parts in the primary source information header applied by the Payload Data System (PDS) to the MOLA telemetry packet at the time of creation of the packet prior to transfer frame creation." OBJECT = BIT_COLUMN NAME = VERSION_NUMBER BIT_DATA_TYPE = UNSIGNED_INTEGER START_BIT = 1 BITS = 3 MINIMUM = 0 MAXIMUM = 7 DESCRIPTION = "These bits identify Version 1 as the Source Packet structure. These bits shall be set to '000'." END_OBJECT = BIT_COLUMN OBJECT = BIT_COLUMN NAME = SPARE Appendix A. PDS Data Object Definitions A-23 BIT_DATA_TYPE = UNSIGNED_INTEGER START_BIT = 4 BITS = 1 MINIMUM = 0 MAXIMUM = 0 DESCRIPTION = "Reserved spare. This bit shall be set to '0'" END_OBJECT = BIT_COLUMN OBJECT = BIT_COLUMN NAME = SECONDARY_HEADER_FLAG BIT_DATA_TYPE = BOOLEAN START_BIT = 5 BITS = 1 MINIMUM = 0 MAXIMUM = 0 DESCRIPTION = "This flag signals the presence or absence of a Secondary Header data structure within the Source Packet. This bit shall be set to '0' since no Secondary Header formatting standards currently exist for Mars Observer." END_OBJECT = BIT_COLUMN OBJECT = BIT_COLUMN NAME = ERROR_STATUS BIT_DATA_TYPE = UNSIGNED_INTEGER START_BIT = 6 BITS = 3 MINIMUM = 0 MAXIMUM = 7 DESCRIPTION = "This field identifies in part the individual application process within the spacecraft that created the Source Packet data." END_OBJECT = BIT_COLUMN OBJECT = BIT_COLUMN NAME = INSTRUMENT_ID BIT_DATA_TYPE = UNSIGNED_INTEGER START_BIT = 9 BITS = 8 MINIMUM = 2#0100011# MAXIMUM = 2#0100011# DESCRIPTION = "This field identifies in part the individual application process within the spacecraft that created the Source Packet data. 00100011 is the bit pattern for MOLA." END_OBJECT = BIT_COLUMN END_OBJECT = COLUMN ... OBJECT = COLUMN NAME = COMMAND_ECHO DATA_TYPE = INTEGER START_BYTE = 125 BYTES = 16 A-24 Appendix A. PDS Data Object Definitions ITEMS = 8 ITEM_BYTES = 2 MINIMUM = 0 MAXIMUM = 65535 DESCRIPTION = "First 8 command words received during current packet, only complete commands are stored, MOLA specific commands only. The software attempts to echo all valid commands. If the command will fit in the room remaining in the..." END_OBJECT = COLUMN OBJECT = COLUMN NAME = PACKET_VALIDITY_CHECKSUM DATA TYPE = INTEGER START_BYTE = 141 BYTES = 2 MINIMUM = 0 MAXIMUM = 65535 DESCRIPTION = "Simple 16 bit addition of entire packet contents upon completion. This location is zeroed for addition. This word is zeroed, then words 0-539 are added without carry to a variable that is initially zero. The resulting lower 16 bits are..." END_OBJECT = COLUMN OBJECT = CONTAINER NAME = FRAME_STRUCTURE ^STRUCTURE = "MOLASCFR.FMT" /*points to the columns*/ /*that make up the frame descriptors */ START_BYTE = 143 BYTES = 134 REPETITIONS = 7 DESCRIPTION = "The frame_structure container represents the format of seven repeating groups of attributes in this data product. The data product reflects science data acquisition from seven different frames. Since the data from each frame are ..." END_OBJECT = CONTAINER Contents of the MOLASCFR.FMT FILE: OBJECT = CONTAINER NAME = COUNTS START_BYTE = 1 BYTES = 4 REPETITIONS = 20 ^STRUCTURE = "MOLASCCT.FMT" DESCRIPTION = "This container has three sub-elements (range to surface counts, 1st channel received pulse energy, and 2nd channel received pulse energy). The three sub-elements repeat for each of 20 shots." END_OBJECT = CONTAINER OBJECT = COLUMN Appendix A. PDS Data Object Definitions A-25 NAME = SHOT_2_LASER_TRANSMITTER_POWR DATA_TYPE = UNSIGNED_INTEGER START_BYTE = 81 BYTES = 1 MINIMUM = 0 MAXIMUM = 65535 DESCRIPTION = "..." END_OBJECT = COLUMN OBJECT = COLUMN NAME = SHOT_1_LASER_TRANSMITTER_POWR DATA_TYPE = UNSIGNED_INTEGER START_BYTE = 82 BYTES = 1 MINIMUM = 0 MAXIMUM = 65535 DESCRIPTION = "..." END_OBJECT = COLUMN OBJECT = COLUMN NAME = SHOT_4_LASER_TRANSMITTER_POWR DATA_TYPE = UNSIGNED_INTEGER START_BYTE = 83 BYTES = 1 MINIMUM = 0 MAXIMUM = 65535 DESCRIPTION = "..." END_OBJECT = COLUMN ... OBJECT = COLUMN NAME = CH_3_2ND_HALF_FRAME_BKGRND_CN DATA_TYPE = UNSIGNED_INTEGER START_BYTE = 133 BYTES = 1 MINIMUM = 0 MAXIMUM = 255 DESCRIPTION = "The background energy or noise count levels in channels 1, 2, 3, and 4 respectively by half-frame. Pseudo log value of NOISE(1, 2, 3, 4) at the end of a half-frame of current frame, 5.3 bit format. Plog base 2 of background count sum..." END_OBJECT = COLUMN OBJECT = COLUMN NAME = CH_4_2ND_HALF_FRAME_BKGRND_CN DATA_TYPE = UNSIGNED_INTEGER START_BYTE = 134 BYTES = 1 MINIMUM = 0 MAXIMUM = 255 DESCRIPTION = "The background energy or noise count levels in channels 1, 2, 3, and 4 respectively by half-frame. A-26 Appendix A. PDS Data Object Definitions Pseudo log value of NOISE(1, 2, 3, 4) at the end of a half-frame of current frame, 5.3 bit format. Plog base 2 of background count sum..." END_OBJECT = COLUMN Contents of the MOLASCCT.FMT FILE: OBJECT = COLUMN NAME = RANGE_TO_SURFACE_TIU_CNTS DATA_TYPE = MSB_INTEGER START_BYTE = 1 BYTES = 2 DESCRIPTION = "The possible 20 valid frame laser shots surface ranging measurements in Timing Interval Unit (TIU) counts. The least significant 16 bits of TIU (SLTIU), stored for every shot. B[0] = Bits 15-8 of TIU reading; B[1] = Bits 7-0 of ..." END_OBJECT = COLUMN OBJECT = COLUMN NAME = FIRST_CH_RCVD_PULSE_ENRGY DATA_TYPE = UNSIGNED_INTEGER START_BYTE = 3 BYTES = 1 DESCRIPTION = "The level of return, reflected energy as received by the first channel and matched filter to trigger. This is a set of values for all possible 20 shots within the frame. Lowest numbered non-zero energy reading for each shot." END_OBJECT = COLUMN OBJECT = COLUMN NAME = SECOND_CH_RCVD_PULSE_ENRGY DATA_TYPE = UNSIGNED_INTEGER START_BYTE = 4 BYTES = 1 DESCRIPTION = "The level of return, reflected energy as received by the second channel and matched filter to trigger. This is a set of values for all possible 20 shots within the frame. 2nd lowest numbered non-zero energy reading for each shot..." END_OBJECT = COLUMN Appendix A. PDS Data Object Definitions A-27 A.9 DATA_PRODUCER The DATA_PRODUCER object is a required sub-object of the VOLUME object. The DATA_PRODUCER, as opposed to the DATA_SUPPLIER, is an individual or organization responsible for collecting, assembling, and/or engineering the raw data into one or more data sets. A.9.1 Required Keywords 1. INSTITUTION_NAME 2. FACILITY_NAME 3. FULL_NAME 4. ADDRESS_TEXT A.9.2 Optional Keywords 1. DISCIPLINE_NAME 2. NODE_NAME 3. TELEPHONE_NUMBER 4. ELECTRONIC_MAIL_TYPE 5. ELECTRONIC_MAIL_ID A.9.3 Required Objects None A.9.4 Optional Objects None A.9.5 Example The fragment below was extracted from the example under the VOLUME object. OBJECT = DATA_PRODUCER INSTITUTION_NAME = "U.S.G.S. FLAGSTAFF" FACILITY_NAME = "BRANCH OF ASTROGEOLOGY" FULL_NAME = "ERIC M. ELIASON" DISCIPLINE_NAME = "IMAGE PROCESSING" ADDRESS_TEXT = "Branch of Astrogeology United States Geological Survey 2255 North Gemini Drive A-28 Appendix A. PDS Data Object Definitions Flagstaff, Arizona 86001 USA" END_OBJECT = DATA_PRODUCER Appendix A. PDS Data Object Definitions A-29 A.10 DATA_SUPPLIER The DATA_SUPPLIER object is an optional sub-object of the VOLUME object. The DATA_SUPPLIER, as opposed to the DATA_PRODUCER, is an individual or organization responsible for distributing the data sets and associated data to the science community. A.10.1 Required Keywords 1. INSTITUTION_NAME 2. FACILITY_NAME 3. FULL_NAME 4. ADDRESS_TEXT 5. TELEPHONE_NUMBER 6. ELECTRONIC_MAIL_TYPE 7. ELECTRONIC_MAIL_ID A.10.2 Optional Keywords 1. DISCIPLINE_NAME 2. NODE_NAME A.10.3 Required Objects None A.10.4 Optional Objects None A.10.5 Example The fragment below was extracted from the larger example which can be found under the VOLUME object. OBJECT = DATA_SUPPLIER INSTITUTION_NAME = "NATIONAL SPACE SCIENCE DATA CENTER" FACILITY_NAME = "NATIONAL SPACE SCIENCE DATA CENTER" FULL_NAME = "NATIONAL SPACE SCIENCE DATA CENTER" DISCIPLINE_NAME = "NATIONAL SPACE SCIENCE DATA CENTER" ADDRESS_TEXT = "Code 633 Goddard Space Flight Center Greenbelt, Maryland, 20771, USA" TELEPHONE_NUMBER = "3012866695" A-30 Appendix A. PDS Data Object Definitions ELECTRONIC_MAIL_TYPE = "NSI/DECNET" ELECTRONIC_MAIL_ID = "NSSDCA::REQUEST" END_OBJECT = DATA_SUPPLIER Appendix A. PDS Data Object Definitions A-31 A.11 DIRECTORY The DIRECTORY object is used to define a hierarchical file organization on a linear (i.e., sequential) medium such as tape. The DIRECTORY object identifies all directories and subdirectories below the root level. It is a required sub-object of the VOLUME object for volumes delivered on sequential media. Note: The root directory on a volume does not need to be explicitly defined with the DIRECTORY object. Subdirectories are identified by defining DIRECTORY objects as sub-objects of the root DIRECTORY. Files within the directories and subdirectories are sequentially identified by using FILE objects with a SEQUENCE_NUMBER value corresponding to their position on the medium. The SEQUENCE_NUMBER value must be unique for each file on the medium. A.11.1 Required Keywords 1. NAME A.11.2 Optional Keywords 1. RECORD_TYPE 2. SEQUENCE_NUMBER A.11.3 Required Objects 1. FILE A.11.4 Optional Objects 1. DIRECTORY A-32 Appendix A. PDS Data Object Definitions A.11.5 Example The fragment below was extracted from the larger example which can be found under the VOLUME object. OBJECT = DIRECTORY NAME = INDEX OBJECT = FILE FILE_NAME = "INDXINFO.TXT" RECORD_TYPE = STREAM SEQUENCE_NUMBER = 5 END_OBJECT = FILE OBJECT = FILE FILE_NAME = "INDEX.LBL" RECORD_TYPE = STREAM SEQUENCE_NUMBER = 6 END_OBJECT = FILE OBJECT = FILE FILE_NAME = "INDEX.TAB" RECORD_TYPE = FIXED_LENGTH RECORD_BYTES = 512 FILE_RECORDS = 6822 SEQUENCE_NUMBER = 7 END_OBJECT = FILE END_OBJECT = DIRECTORY Appendix A. PDS Data Object Definitions A-33 A.12 DOCUMENT Note: This section is currently undergoing major revision. Please consult a PDS data engineer for the latest available information on document labelling. The DOCUMENT object is used to label a particular document that is provided on a volume to support an archived data product. A document can be made up of one or more files in a single format. For instance, a document may be comprised of as many TIFF files as there are pages in the document. Multiple versions of a document can be supplied on a volume with separate formats, requiring a DOCUMENT object for each document version (i.e., OBJECT = TEX_DOCUMENT and OBJECT = PS_DOCUMENT when including both the TEX and Postscript versions of the same document). PDS requires that at least one version of any document be plain ASCII text in order to allow users the capability to read, browse, or search the text without requiring software or text processing packages. This version can be plain, unmarked text, or ASCII text containing a markup language. (See the Documentation chapter of this document for more details.) The DOCUMENT object contains keywords that identify and describe the document, provide the date of publication of the document, indicate the number of files comprising the document, provide the format of the document files, and identify the software used to compress or encode the document, as applicable. DOCUMENT labels must be detached files unless the files are plain, unmarked text that will not be read by text or word processing packages. A DOCUMENT object for each format type of a document can be included in the same label file with pointers, such as ^TIFF_DOCUMENT for a TIFF formatted document. (See example below.) A.12.1 Required Keywords 1. DOCUMENT_NAME 2. DOCUMENT_TOPIC_TYPE 3. INTERCHANGE_FORMAT 4. DOCUMENT_FORMAT 5. PUBLICATION_DATE A.12.2 Optional Keywords 1. ABSTRACT_TEXT 2. DESCRIPTION A-34 Appendix A. PDS Data Object Definitions 3. ENCODING_TYPE 4. FILES A.12.3 Required Objects None A.12.4 Optional Objects None A.12.5 Example The following example detached label, PDSUG.LBL, is for a Document provided in three formats: ASCII text, TIFF, and TEX. PDS_VERSION_ID = PDS3 RECORD_TYPE = UNDEFINED ^ASCII_DOCUMENT = "PDSUG.ASC" ^TIFF_DOCUMENT = {"PDSUG001.TIF", "PDSUG002.TIF", "PDSUG003.TIF", "PDSUG004.TIF" } ^TEX_DOCUMENT = "PDSUG.TEX" OBJECT = ASCII_DOCUMENT DOCUMENT_NAME = "Planetary Data System Data Set Catalog User's Guide" PUBLICATION_DATE = 1992-04-13 DOCUMENT_TOPIC_TYPE = "USER'S GUIDE" INTERCHANGE_FORMAT = ASCII DOCUMENT_FORMAT = TEXT DESCRIPTION = "The Planetary Data System Data Set Catalog User's Guide describes the fundamentals of accessing, searching, browsing, and ordering data from the PDS Data Set Catalog at the Central Node. The text for this 4-page document is provided here in this plain, ASCII text file." ABSTRACT_TEXT = "The PDS Data Set Catalog is similar in function and purpose to a card catalog in a library. Use a Search screen to find data items, a List/Order screen to order data items, and the More menu option to see more information." END_OBJECT = ASCII_DOCUMENT OBJECT = TIFF_DOCUMENT DOCUMENT_NAME = "Planetary Data System Data Set Catalog User's Guide" Appendix A. PDS Data Object Definitions A-35 DOCUMENT_TOPIC_TYPE = "USER'S GUIDE" INTERCHANGE_FORMAT = BINARY DOCUMENT_FORMAT = TIFF PUBLICATION_DATE = 1992-04-13 FILES = 4 ENCODING_TYPE = "CCITT/3" DESCRIPTION = "The Planetary Data System Data Set Catalog User's Guide describes the fundamentals of accessing, searching, browsing, and ordering data from the PDS Data Set Catalog at the Central Node. The 4-page document is provided here in 4 consecutive files, one file per page, in Tagged Image File Format (TIFF) using Group 3 compression. It has been successfully imported into WordPerfect 5.0, FrameMaker, and Photoshop." ABSTRACT_TEXT = "The PDS Data Set Catalog is similar in function and purpose to a card catalog in a library. Use a Search screen to find data items, a List/Order screen to order data items, and the More menu option to see more information." END_OBJECT = TIFF_DOCUMENT OBJECT = TEX_DOCUMENT DOCUMENT_NAME = "Planetary Data System Data Set Catalog User's Guide" DOCUMENT_TOPIC_TYPE = "USER'S GUIDE" INTERCHANGE_FORMAT = ASCII DOCUMENT_FORMAT = TEX PUBLICATION_DATE = 1992-04-13 DESCRIPTION = "The Planetary Data System Data Set Catalog User's Guide describes the fundamentals of accessing, searching, browsing, and ordering data from the PDS Data Set Catalog at the Central Node. The 4-page document is provided here in TeX format with all necessary macros included." ABSTRACT_TEXT = "The PDS Data Set Catalog is similar in function and purpose to a card catalog in a library. Use a Search screen to find data items, a List/Order screen to order data items, and the More menu option to see more information." END_OBJECT = TEX_DOCUMENT END A-36 Appendix A. PDS Data Object Definitions A.13 ELEMENT (Primitive Data Object) The ELEMENT object provides a means of defining a lowest-level component of a data object, and which can be stored in an integral multiple of 8 -bit bytes. ELEMENT objects may be embedded in COLLECTION and ARRAY data objects. The optional START_BYTE element identifies a location relative to the enclosing object. If not explicitly included, a START_BYTE = 1 is assumed for the ELEMENT. A.13.1 Required Keywords 1. BYTES 2. DATA_TYPE 3. NAME A.13.2 Optional Keywords 1. START_BYTE 2. BIT_MASK 3. DERIVED_MAXIMUM 4. DERIVED_MINIMUM 5. DESCRIPTION 6. FORMAT 7. INVALID_CONSTANT 8. MINIMUM 9. MAXIMUM 10. MISSING_CONSTANT 11. OFFSET 12. SCALING_FACTOR 13. UNIT 14. VALID_MINIMUM 15. VALID_MAXIMUM A.13.3 Required Objects None A.13.4 Optional Objects None Appendix A. PDS Data Object Definitions A-37 A.13.5 Example Please refer to the example in the ARRAY Primitive object (Section A.2) for an example of the use of the ELEMENT object. A-38 Appendix A. PDS Data Object Definitions A.14 FILE The FILE object is used in attached or detached labels to define the attributes or characteristics of a data file. In attached labels, the file object is also used to indicate boundaries between label records and data records in data files which have attached labels. The FILE object may be used in three ways: 1. As an implicit object in attached or detached labels. All detached label files and attached labels contain an implicit FILE object which starts at the top of the label and ends where the label ends. In these cases, the PDS recommends against using the NAME keyword to reference the file name. This label fragment shows the required FILE object elements as they typically appear in labels: RECORD_TYPE = FIXED_LENGTH RECORD_BYTES = 80 FILE_RECORDS = 522 LABEL_RECORDS = 10 For data products labelled using the implicit file object (e.g., in minimal labels) "DATA_OBJECT_TYPE = FILE" should be used in the DATA_SET catalog object. 2. As an explicit object which is used when a file reference is needed in a combined detached or minimal label. In this case, the optional FILE_NAME element is used to identify the file being referenced. OBJECT = FILE FILE_NAME = "IM10347.DAT" RECORD_TYPE = STREAM FILE_RECORDS = 1024 ... END_OBJECT = FILE For data products labelled using the explicit FILE object (e.g., in minimal labels) DATA_OBJECT_TYPE = FILE should be used in the DATA_SET catalog object. 3. As an explicit object to identify specific files as sub-objects of the DIRECTORY in VOLUME objects. In this case, the optional FILE_NAME element is used to identify the file being referenced on a tape archive volume. OBJECT = FILE FILE_NAME = "VOLDESC.CAT" RECORD_TYPE = STREAM SEQUENCE_NUMBER = 1 END_OBJECT = FILE Appendix A. PDS Data Object Definitions A-39 The keywords in the FILE object always describe the file being referenced, and not the file in which the keywords are contained (i.e., if the FILE object is used in a detached label file, the FILE object keywords describe the detached data file, not the label file which contains the keywords). For example, if a detached label for a data file is being created and the label will be in STREAM format, but the data will be stored in a file having FIXED_LENGTH records, then the RECORD_TYPE keyword in the label file must be given the value FIXED_LENGTH. The following table identifies data elements that are required (Req), optional (Opt), and not applicable (-) for various types of files Labeling Method Att Det Att Det Att Det Att Det RECORD_TYPE FIXED_LENGTH VARIABLE_LENGTH STREAM UNDEFINED RECORD_BYTES Req Req Rmax Rmax Omax - - - FILE_RECORDS Req Req Req Req Opt Opt - - LABEL_RECORDS Req - Req - Opt - - - A.14.1 Required Keywords 1. RECORD_TYPE (See above table for the conditions of use of additional required keywords) A.14.2 Optional Keywords 1. DESCRIPTION 2. ENCODING_TYPE 3. FILE_NAME (required only in minimal detached labels and tape archives) 4. FILE_RECORDS (required only in minimal detached labels and tape archives) 5. INTERCHANGE_FORMAT 6. LABEL_RECORDS 7. RECORD_BYTES 8. REQUIRED_STORAGE_BYTES 9. SEQUENCE_NUMBER 10. UNCOMPRESSED_FILE_NAME A.14.3 Required Objects None A-40 Appendix A. PDS Data Object Definitions A.14.4 Optional Objects None A.14.5 Example Following is an example of a set of explicit FILE objects in a combined detached label. An additional example of the use of explicit FILE object can be found under the VOLUME object (Section A.29). PDS_VERSION_ID = PDS3 HARDWARE_MODEL_ID = "SUN SPARC STATION" OPERATING_SYSTEM_ID = "SUN OS 4.1.1" SPACECRAFT_NAME = "VOYAGER 2" INSTRUMENT_NAME = "PLASMA WAVE RECEIVER" MISSION_PHASE_NAME = "URANUS ENCOUNTER" TARGET_NAME = URANUS DATA_SET_ID = "VG2-U-PWS-4-RDR-SA-48.0SEC-V1.0" PRODUCT_ID = "T860123-T860125" OBJECT = FILE FILE_NAME = "T860123.DAT" FILE_RECORDS = 1800 RECORD_TYPE = FIXED_LENGTH RECORD_BYTES = 105 START_TIME = 1986-01-23T00:00:00.000Z STOP_TIME = 1986-01-24T00:00:00.000Z ^TIME_SERIES = "T860123.DAT" OBJECT = TIME_SERIES INTERCHANGE_FORMAT = BINARY ROWS = 1800 ROW_BYTES = 105 COLUMNS = 19 ^STRUCTURE = "PWS_DATA.FMT" SAMPLING_PARAMETER_NAME = TIME SAMPLING_PARAMETER_UNIT = SECOND SAMPLING_PARAMETER_INTERVAL = 48.0 END_OBJECT = TIME_SERIES END_OBJECT = FILE OBJECT = FILE FILE_NAME = "T860124.DAT" FILE_RECORDS = 1800 RECORD_TYPE = FIXED_LENGTH RECORD_BYTES = 105 START_TIME = 1986-01-24T00:00:00.000Z STOP_TIME = 1986-01-25T00:00:00.000Z Appendix A. PDS Data Object Definitions A-41 ^TIME_SERIES = "T860124.DAT" OBJECT = TIME_SERIES INTERCHANGE_FORMAT = BINARY ROWS = 1800 ROW_BYTES = 105 COLUMNS = 19 ^STRUCTURE = "PWS_DATA.FMT" SAMPLING_PARAMETER_NAME = TIME SAMPLING_PARAMETER_UNIT = SECOND SAMPLING_PARAMETER_INTERVAL = 48.0 END_OBJECT = TIME_SERIES END_OBJECT = FILE OBJECT = FILE FILE_NAME = "T860125.DAT" FILE_RECORDS = 1799 RECORD_TYPE = FIXED_LENGTH RECORD_BYTES = 105 START_TIME = 1986-01-30T00:00:00.000Z STOP_TIME = 1986-01-30T23:59:12.000Z ^TIME_SERIES = "T860125.DAT" OBJECT = TIME_SERIES INTERCHANGE_FORMAT = BINARY ROWS = 1799 ROW_BYTES = 105 COLUMNS = 19 ^STRUCTURE = "PWS_DATA.FMT" SAMPLING_PARAMETER_NAME = TIME SAMPLING_PARAMETER_UNIT = SECOND SAMPLING_PARAMETER_INTERVAL = 48.0 END_OBJECT = TIME_SERIES END_OBJECT = FILE END A-42 Appendix A. PDS Data Object Definitions A.15 GAZETTEER_TABLE The GAZETTEER_TABLE object is a specific type of TABLE object that provides information about the geographical features of a planet or satellite. It contains information about named features such as location, size, origin of feature name, and so on. The GAZETTEER_TABLE contains one row for each named feature on the target body. The table is formatted so that it may be read directly by many data management systems on various host computers. All fields (columns) are separated by commas, and character fields are enclosed by double quotation marks. Each record consist of 480 bytes, with a carriage return/line feed sequence in bytes 479 and 480. This allows the table to be treated as a fixed length record file on hosts that support this file type and as a normal text file on other hosts. Currently the PDS Imaging Node at the USGS is the data producer for all GAZETTEER_TABLEs. A.15.1 Required Keywords 1. NAME 2. INTERCHANGE_FORMAT 3. ROWS 4. COLUMNS 5. ROW_BYTES 6. DESCRIPTION A.15.2 Optional Keywords Any A.15.3 Required Objects 1. COLUMN A.15.3.1 Required COLUMN Objects (NAME =) TARGET_NAME SEARCH_FEATURE_NAME DIACRITIC_FEATURE_NAME MINIMUM_LATITUDE MAXIMUM_LATITUDE CENTER_LATITUDE Appendix A. PDS Data Object Definitions A-43 MINIMUM_LONGITUDE MAXIMUM_LONGITUDE CENTER_LONGITUDE LABEL_POSITION_ID FEATURE_LENGTH PRIMARY_PARENTAGE_ID SECONDARY_PARENTAGE_ID MAP_SERIAL_ID FEATURE_STATUS_TYPE APPROVAL_DATE FEATURE_TYPE R EFERENCE_NUMBER MAP_CHART_ID FEATURE_DESCRIPTION A.15.3.2 Required Keywords (for Required COLUMN Objects) NAME DATA_TYPE START_BYTE BYTES FORMAT UNIT DESCRIPTION A.15.4 Optional Objects None A.15.5 Example PDS_VERSION_ID = PDS3 RECORD_TYPE = FIXED_LENGTH RECORD_BYTES = 480 FILE_RECORDS = 1181 PRODUCT_ID = XYZ TARGET_NAME = MARS ^GAZETTEER_TABLE = "GAZETTER.TAB" OBJECT = GAZETTEER_TABLE NAME = "PLANETARY NOMENCLATURE GAZETTEER" INTERCHANGE_FORMAT = ASCII ROWS = 1181 COLUMNS = 20 ROW_BYTES = 480 A-44 Appendix A. PDS Data Object Definitions DESCRIPTION = "The gazetteer (file: GAZETTER.TAB) is a table of geographical features for a planet or satellite. It contains information about a named feature such as location, size, origin of feature name, etc. The Gazetteer Table contains one row for each feature named on the target body. The table is formatted so that it may be read directly into many data management systems on various host computers. All fields (columns) are separated by commas, and character fields are preceded by double quotation marks. Each record consist of 480 bytes, with a carriage return/line feed sequence in bytes 479 and 480. This allows the table to be treated as a fixed length record file on hosts that support this file type and as a normal text file on other hosts." OBJECT = COLUMN NAME = TARGET_NAME DATA_TYPE = CHARACTER START_BYTE = 2 BYTES = 20 FORMAT = "A20" UNIT = "N/A" DESCRIPTION = "The planet or satellite on which the feature is located." END_OBJECT = COLUMN OBJECT = COLUMN NAME = SEARCH_FEATURE_NAME DATA_TYPE = CHARACTER START_BYTE = 25 BYTES = 50 FORMAT = "A50" UNIT = "N/A" DESCRIPTION = "The geographical feature name with all diacritical marks stripped off. This name is stored in upper case only so that it can be used for sorting and search purposes. This field should not be used to designate the name of the feature because it does not contain the diacritical marks. Feature names not containing diacritical marks can often take on a completely different meaning and in some cases the meaning can be deeply offensive." END_OBJECT = COLUMN OBJECT = COLUMN NAME = DIACRITIC_FEATURE_NAME DATA_TYPE = CHARACTER START_BYTE = 78 BYTES = 100 FORMAT = "A100" UNIT = "N/A" DESCRIPTION = "The geographical feature name containing standard diacritical information. A detailed description of the diacritical mark formats are described in the gazetteer documentation. Appendix A. PDS Data Object Definitions A-45 DIACRITICALS USED IN THE TABLE The word diacritic comes from a Greek word meaning to separate. It refers to the accent marks employed to separate, or distinguish, one form of pronunciation of a vowel or consonant from another. This note is included to familiarize the user with the codes used to represent diacriticals found in the table, and the values usually associated with them. In the table, the code for a diacritical is preceded by a backslash and is followed, without a space, by the letter it is modifying. This note is organized as follows: the code is listed first, followed by the name of the accent mark, if applicable, a brief description of the appearance of the diacritical and a short narrative on its usage. acute accent; a straight diagonal line extending from upper right to lower left. The acute accent is used in most languages to lengthen a vowel; in some, such as Oscan, to denote an open vowel. The acute is also often used to indicate the stressed syllable; in some transcriptions it indicates a palatalized consonant. diaeresis or umlaut; two dots surmounting the letter. In Romance languages and English, the diaeresis is used to indicate that consecutive vowels do not form a dipthong (see below); in modern German and Scandinavian languages, it denotes palatalization of vowels. circumflex; a chevron or inverted 'v' shape, with the apex at the top. Used most often in modern languages to indicate lengthening of a vowel. tilde; a curving or waving line above the letter. The tilde is a form of circumflex. The tilde is used most often in Spanish to form a palatalized n as in the word 'ano', pronounced 'anyo'. It is also used occasionally to indicate nasalized vowels. macron; a straight line above the letter. The macron is used almost universally to lengthen a vowel. breve; a concave semicircle or 'u' shape surmounting the letter. Originally used in Greek, the breve indicates a short vowel. a small circle or 'o' above the letter. Frequently used in Scandinavian languages to indicate a broad 'o'. e dipthong or ligature; transcribed as two letters in contact with each other. The dipthong is a combination of vowels that are pronounced together. cedilla; a curved line surmounted by a vertical line, placed at the bottom of the letter. The cedilla is used in Spanish and French to denote a dental, or soft, 'c'. In the new Turkish transcription, A-46 Appendix A. PDS Data Object Definitions 'c' cedilla has the value of English 'ch'. In Semitic languages, the cedilla under a consonant indicates that it is emphatic. check or inverted circumflex; a 'v' shape above the letter. This accent is used widely in Slavic languages to indicate a palatal articulation, like the consonant sounds in the English words chapter and shoe and the 'zh' sound in pleasure. a single dot above the letter. This diacritical denotes various things; in Lithuanian, it indicates a close long vowel. In Sanskrit, when used with 'n', it is a velar sound, as in the English 'sink'; in Irish orthography, it indicates a fricative consonant (see below). accent grave; a diagonal line (above the letter) extending from upper left to lower right. The grave accent is used in French, Spanish and Italian to denote open vowels. fricative; a horizontal line through a consonant. A fricative consonant is characterized by a frictional rustling of the breath as it is emitted." END_OBJECT = COLUMN OBJECT = COLUMN NAME = MINIMUM_LATITUDE DATA_TYPE = REAL START_BYTE = 180 BYTES = 7 FORMAT = "F7.2" UNIT = DEGREE DESCRIPTION = "The minimum_latitude element specifies the southernmost latitude of a spatial area, such as a map, mosaic, bin, feature, or region." END_OBJECT = COLUMN OBJECT = COLUMN NAME = MAXIMUM_LATITUDE DATA_TYPE = REAL START_BYTE = 188 BYTES = 7 FORMAT = "F7.2" UNIT = DEGREE DESCRIPTION = "The maximum_latitude element specifies the northernmost latitude of a spatial area, such as a map, mosaic, bin, feature, or region." END_OBJECT = COLUMN OBJECT = COLUMN NAME = CENTER_LATITUDE DATA_TYPE = REAL START_BYTE = 196 BYTES = 7 FORMAT = "F7.2" Appendix A. PDS Data Object Definitions A-47 UNIT = DEGREE DESCRIPTION = "The center latitude of the feature." END_OBJECT = COLUMN OBJECT = COLUMN NAME = MINIMUM_LONGITUDE DATA_TYPE = REAL START_BYTE = 204 BYTES = 7 FORMAT = "F7.2" UNIT = DEGREE DESCRIPTION = "The minimum_longitude element specifies the easternmost latitude of a spatial area, such as a map, mosaic, bin, feature, or region. " END_OBJECT = COLUMN OBJECT = COLUMN NAME = MAXIMUM_LONGITUDE DATA_TYPE = REAL START_BYTE = 212 BYTES = 7 FORMAT = "F7.2" UNIT = DEGREE DESCRIPTION = "The maximum_longitude element specifies the westernmost longitude of a spatial area, such as a map, mosaic, bin, feature, or region. " END_OBJECT = COLUMN OBJECT = COLUMN NAME = CENTER_LONGITUDE DATA_TYPE = REAL START_BYTE = 220 BYTES = 7 FORMAT = "F7.2" UNIT = DEGREE DESCRIPTION = "The center longitude of the feature." END_OBJECT = COLUMN OBJECT = COLUMN NAME = LABEL_POSITION_ID DATA_TYPE = CHARACTER START_BYTE = 229 BYTES = 2 FORMAT = "A2" UNIT = "N/A" DESCRIPTION = "The suggested plotting position of the feature name (UL=Upper left, UC=Upper center, UR=Upper right, CL=Center left, CR=Center right, LL=Lower left, LC=Lower center, LR=Lower right). This field is used to instruct the plotter where to place the typographical label with respect to the center of the feature. This code is used to avoid crowding of names in areas where there is a high density of named features." END_OBJECT = COLUMN A-48 Appendix A. PDS Data Object Definitions OBJECT = COLUMN NAME = FEATURE_LENGTH DATA_TYPE = REAL START_BYTE = 233 BYTES = 8 FORMAT = "F8.2" UNIT = KILOMETER DESCRIPTION = "The longer or longest dimension of an object. For the Gazetteer usage, this field refers to the length of the named feature." END_OBJECT = COLUMN OBJECT = COLUMN NAME = PRIMARY_PARENTAGE_ID DATA_TYPE = CHARACTER START_BYTE = 243 BYTES = 2 FORMAT = "A2" UNIT = "N/A" DESCRIPTION = "This field contains the primary origin of the feature name (i.e. where the name originated). It contains a code for the continent or country origin of the name. Please see Appendix 5 of the gazetteer documentation (GAZETTER.TXT) for a definition of the codes used to define the continent or country." END_OBJECT = COLUMN OBJECT = COLUMN NAME = SECONDARY_PARENTAGE_ID DATA_TYPE = CHARACTER START_BYTE = 248 BYTES = 2 FORMAT = "A2" UNIT = "N/A" DESCRIPTION = "This field contains the secondary origin of the feature name. It contains a code for a country, state, territory, or ethnic group. Please see Appendix 5 of the gazetteer documentation (GAZETTER.TXT) for a defintion of the codes in this field." END_OBJECT = COLUMN OBJECT = COLUMN NAME = MAP_SERIAL_ID DATA_TYPE = CHARACTER START_BYTE = 253 BYTES = 6 FORMAT = "A6" UNIT = "N/A" DESCRIPTION = "The identification of the map that contains the named feature. This field represents the map serial number of the map publication used for ordering maps from the U.S. Geological Survey. The map identified in this field best portrays the named feature." END_OBJECT = COLUMN Appendix A. PDS Data Object Definitions A-49 OBJECT = COLUMN NAME = FEATURE_STATUS_TYPE DATA_TYPE = CHARACTER START_BYTE = 262 BYTES = 12 FORMAT = "A12" UNIT = "N/A" DESCRIPTION = "The IAU approval status of the named feature. Permitted values are 'PROPOSED', 'PROVISIONAL', 'IAU- APPROVED', and 'DROPPED'. Dropped names have been disallowed by the IAU. However, these features have been included in the gazetteer for historical purposes. Some named features that are disallowed by the IAU may commonly be used on some maps." END_OBJECT = COLUMN OBJECT = COLUMN NAME = APPROVAL_DATE DATA_TYPE = INTEGER START_BYTE = 276 BYTES = 4 FORMAT = "I4" UNIT = "N/A" DESCRIPTION = "Date at which an object has been approved by the officially sanctioned organization. This field contains the year the IAU approved the feature name." END_OBJECT = COLUMN OBJECT = COLUMN NAME = FEATURE_TYPE DATA_TYPE = CHARACTER START_BYTE = 282 BYTES = 20 FORMAT = "A20" UNIT = "N/A" DESCRIPTION = "The feature type identifies the type of a particular feature, according to IAU standards. Examples are 'CRATER', 'TESSERA', 'TERRA', etc. See Appendix 7 of the gazetteer documentation (GAZETTER.TXT). DESCRIPTOR TERMS (FEATURE TYPES) FEATURE DESCRIPTION ALBEDO FEATURE Albedo feature CATENA Chain of craters CAVUS Hollows, irregular depressions CHAOS Distinctive area of broken terrain CHASMA Canyon COLLES Small hill or knob CORONA Ovoid-shaped feature CRATER Crater DORSUM Ridge ERUPTIVE CENTER Eruptive center FACULA Bright spot A-50 Appendix A. PDS Data Object Definitions FLEXUS Cuspate linear feature FLUCTUS Flow terrain FOSSA Long, narrow, shallow depression LABES Landslide LABYRINTHUS Intersecting valley complex LACUS Lake LARGE RINGED FEATURE Large ringed feature LINEA Elongate marking MACULA Dark spot MARE Sea MENSA Mesa, flat-topped elevation MONS Mountain OCEANUS Ocean PALUS Swamp PATERA Shallow crater; scalloped, complex edge PLANITIA Low plain PLANUM Plateau or high plain PROMONTORIUM Cape REGIO Region RIMA Fissure RUPES Scarp SCOPULUS Lobate or irregular scarp SINUS Bay SULCUS Subparallel furrows and ridges TERRA Extensive land mass TESSERA Tile; polygonal ground THOLUS Small domical mountain or hill UNDAE Dunes VALLIS Sinuous valley VASTITAS Widespread lowlands VARIABLE FEATURE Variable feature " END_OBJECT = COLUMN OBJECT = COLUMN NAME = REFERENCE_NUMBER DATA_TYPE = INTEGER START_BYTE = 304 BYTES = 4 FORMAT = "I4" UNIT = "N/A" DESCRIPTION = "Literature reference from which the spelling and description of the feature name was derived. See Appendix 6 of the gazetteer documentation (GAZETTER.TXT)." END_OBJECT = COLUMN OBJECT = COLUMN NAME = MAP_CHART_ID DATA_TYPE = CHARACTER START_BYTE = 310 BYTES = 6 FORMAT = "A6" UNIT = "N/A" Appendix A. PDS Data Object Definitions A-51 DESCRIPTION = "This field contains the abbreviation of the map designator or chart identification (example MC-19, MC-18, etc.)." END_OBJECT = COLUMN OBJECT = COLUMN NAME = FEATURE_DESCRIPTION DATA_TYPE = CHARACTER START_BYTE = 319 BYTES = 159 FORMAT = "A159" UNIT = "N/A" DESCRIPTION = "Short description of the feature name." END_OBJECT = COLUMN END_OBJECT = GAZETTEER_TABLE END A-52 Appendix A. PDS Data Object Definitions A.16 HEADER The HEADER object is used to identify and define the attributes of commonly used header data structures such as VICAR or FITS. These structures are usually system or software specific and are described in detail in a referenced description text file. The use of BYTES within the header object refers to the number of bytes for the entire header, not a single record. A.16.1 Required Keywords 1. BYTES 2. HEADER_TYPE A.16.2 Optional Keywords 1. DESCRIPTION 2. INTERCHANGE_FORMAT 3. RECORDS A.16.3 Required Objects None A.16.4 Optional Objects None A.16.5 Example The following example shows the detached label file "TIMTC02A.LBL". The label describes the data product file "TIMTC02A.IMG" which contains a HEADER object followed by an IMAGE object. PDS_VERSION_ID = PDS3 /* PDS label for a TIMS image */ RECORD_TYPE = FIXED_LENGTH RECORD_BYTES = 638 FILE_RECORDS = 39277 /* Pointers to objects */ Appendix A. PDS Data Object Definitions A-53 ^IMAGE_HEADER = ("TIMTC02A.IMG",1) ^IMAGE = ("TIMTC02A.IMG",2) /* Image description */ DATA_SET_ID = "C130-E-TIMS-2-EDR-IMAGE-V1.0" PRODUCT_ID = "TIMTC02A" INSTRUMENT_HOST_NAME = "NASA C-130 AIRCRAFT" INSTRUMENT_NAME = "THERMAL INFRARED MULTISPECTRAL SCANNER" TARGET_NAME = EARTH FEATURE_NAME = "TRAIL CANYON FAN" START_TIME = 1989-09-29T21:47:35Z STOP_TIME = 1989-09-29T21:47:35Z CENTER_LATITUDE = 36.38 CENTER_LONGITUDE = 116.96 INCIDENCE_ANGLE = 0.0 EMISSION_ANGLE = 0.0 /* Description of objects */ OBJECT = IMAGE_HEADER BYTES = 638 RECORDS = 1 HEADER_TYPE = VICAR2 INTERCHANGE_FORMAT = BINARY ^DESCRIPTION = "VICAR2.TXT" END_OBJECT = IMAGE_HEADER OBJECT = IMAGE LINES = 6546 LINE_SAMPLES = 638 SAMPLE_TYPE = UNSIGNED_INTEGER SAMPLE_BITS = 8 SAMPLE_BIT_MASK = 2#11111111# BANDS = 6 BAND_STORAGE_TYPE = LINE_INTERLEAVED END_OBJECT = IMAGE END A-54 Appendix A. PDS Data Object Definitions A.17 HISTOGRAM The HISTOGRAM object is a sequence of numeric values that provides the number of occurrences of a data value or a range of data values in a data object. The number of items in a histogram will normally be equal to the number of distinct values allowed in a field of the data object. For example, an 8-bit integer field can have a maximum of 256 values, and would result in a 256 item histogram. HISTOGRAMs may be used to bin data, in which case an offset and scaling factor indicate the dynamic range of the data represented. The following equation allows the calculation of the range of each bin in the histogram: bin_lower_boundary = bin_element * SCALING_FACTOR + OFFSET A.17.1 Required Keywords 1. ITEMS 2. DATA_TYPE 3. ITEM_BYTES A.17.2 Optional Keywords 1. BYTES 2. INTERCHANGE_FORMAT 3. OFFSET 4. SCALING_FACTOR A.17.3 Required Objects None A.17.4 Optional Objects None Appendix A. PDS Data Object Definitions A-55 A.17.5 Example PDS_VERSION_ID = PDS3 /* FILE FORMAT AND LENGTH */ RECORD_TYPE = FIXED_LENGTH RECORD_BYTES = 956 FILE_RECORDS = 965 LABEL_RECORDS = 3 /* POINTERS TO START RECORDS OF OBJECTS IN FILE */ ^IMAGE_HISTOGRAM = 4 ^IMAGE = 6 /* IMAGE DESCRIPTION */ DATA_SET_ID = "VO1/VO2-M-VIS-5-DIM-V1.0" PRODUCT_ID = "MG15N022-GRN-666A" SPACECRAFT_NAME = VIKING_ORBITER_1 TARGET_NAME = MARS START_TIME = 1978-01-14T02:00:00 STOP_TIME = 1978-01-14T02:00:00 SPACECRAFT_CLOCK_START_TIME = UNK SPACECRAFT_CLOCK_STOP_TIME = UNK PRODUCT_CREATION_TIME = 1995-01-01T00:00:00 ORBIT_NUMBER = 666 FILTER_NAME = GREEN IMAGE_ID = "MG15N022-GRN-666A" INSTRUMENT_NAME = {VISUAL_IMAGING_SUBSYSTEM_CAMERA_A, VISUAL_IMAGING_SUBSYSTEM_CAMERA_B} NOTE = "MARS MULTI-SPECTRAL MDIM SERIES" /* SUN RAYS EMISSION, INCIDENCE, AND PHASE ANGLES OF IMAGE CENTER*/ SOURCE_PRODUCT_ID = "666A36" EMISSION_ANGLE = 21.794 INCIDENCE_ANGLE = 66.443 PHASE_ANGLE = 46.111 /* DESCRIPTION OF OBJECTS CONTAINED IN FILE */ OBJECT = IMAGE_HISTOGRAM ITEMS = 256 DATA_TYPE = VAX_INTEGER ITEM_BYTES = 4 END_OBJECT = IMAGE_HISTOGRAM OBJECT = IMAGE LINES = 960 LINE_SAMPLES = 956 SAMPLE_TYPE = UNSIGNED_INTEGER SAMPLE_BITS = 8 SAMPLE_BIT_MASK = 2#11111111# CHECKSUM = 65718982 A-56 Appendix A. PDS Data Object Definitions /* I/F = SCALING_FACTOR*DN + OFFSET, CONVERT TO INTENSITY/FLUX */ SCALING_FACTOR = 0.001000 OFFSET = 0.0 /* OPTIMUM COLOR STRETCH FOR DISPLAY OF COLOR IMAGES */ STRETCHED_FLAG = FALSE STRETCH_MINIMUM = ( 53, 0) STRETCH_MAXIMUM = (133,255) END_OBJECT = IMAGE END Appendix A. PDS Data Object Definitions A-57 A.18 HISTORY A HISTORY object is a dynamic description of the history of one or more associated data objects in a file. It supplements the essentially static description contained in the PDS label. The HISTORY object contains text in a format similar to that of the ODL statements used in the label. It identifies previous computer manipulation of the principal data object(s) in the file. It includes an identification of the source data, processes performed, processing parameters, as well as dates and times of processing. It is intended that the history be available for display, be dynamically extended by any process operating on the data, and be automatically propagated to the resulting data file. Eventually, it might be extracted for loading in detailed level cat alogs of data set contents. The HISTORY object is structured as a series of History Entries, one for each process which has operated on the data. Each entry contains a standard set of ODL element assignment statements, delimited by "GROUP = program_name" and "END_GROUP = program_name" statements. A subgroup in each entry, delimited by "GROUP = PARAMETERS" and "END_GROUP = PARAMETERS", contains statements specifying the values of