D-9594 STANDARD FORMATTED DATA UNIT SOFTWARE TOOL KIT VERSION 1.2 USER'S GUIDE September 7, 1993 This Page Intentionally Left Blank D-9594 STANDARD FORMATTED DATA UNIT SOFTWARE TOOL KIT VERSION 1.2 USER'S GUIDE September 7, 1993 Prepared by: SFDU SOFTWARE TOOL KIT DEVELOPMENT TEAM ________________________ Ronald A. Green (CDE) ________________________ Mikael Aronsson Approved by: ________________________ J. Grimes SFDU System Engineer ________________________ C. Wong SFDU System Engineer Jet Propulsion Laboratory California Institute of Technology Pasadena, California TABLE OF CONTENTS 1 INTRODUCTION. . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 1.1 Identification . . . . . . . . . . . . . . . . . . . . . . . 7 1.2 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 7 1.3 Document Scope . . . . . . . . . . . . . . . . . . . . . . . 7 1.4 Other Documents. . . . . . . . . . . . . . . . . . . . . . . 7 1.5 Acronyms and Abbreviations . . . . . . . . . . . . . . . . . 8 2 TOOL KIT OVERVIEW . . . . . . . . . . . . . . . . . . . . . . . . . 8 2.1 Parameter Value Language (PVL) Verifier Application. . . . . 8 2.2 PVL Library. . . . . . . . . . . . . . . . . . . . . . . . . 8 2.3 SFDU Library . . . . . . . . . . . . . . . . . . . . . . . . 8 2.4 WRAP Application . . . . . . . . . . . . . . . . . . . . . . 8 2.5 UNWRAP Application . . . . . . . . . . . . . . . . . . . . . 9 2.6 EXTRACT Application. . . . . . . . . . . . . . . . . . . . . 9 2.7 MAP Language . . . . . . . . . . . . . . . . . . . . . . . . 9 2.8 MACROGEN Application . . . . . . . . . . . . . . . . . . . . 9 3 TOOL KIT PLATFORMS. . . . . . . . . . . . . . . . . . . . . . . . . 9 3.1 SUN/UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . 9 3.2 PC/DOS . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 3.3 VAX/VMS. . . . . . . . . . . . . . . . . . . . . . . . . . . 10 3.4 Software Distribution. . . . . . . . . . . . . . . . . . . . 10 4 MAP LANGUAGE. . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 4.1 Aggregations . . . . . . . . . . . . . . . . . . . . . . . . 11 4.2 Simple Statements. . . . . . . . . . . . . . . . . . . . . . 11 4.2.1 ADID = adidname . . . . . . . . . . . . . . . . . . . 11 4.2.2 DELIMITATION = (type, delimitation_parameter) . . . . 11 4.2.3 INCLUDE_DATA_FILE = pathname REFERENCE_DATA_FILE = pathname. . . . . . . . . . . . 11 4.2.4 PRE_DATA_DELIMITER = (list) . . . . . . . . . . . . . 12 4.2.5 PAD_NEXT_LVO_VALUE = (record_length, char). . . . . . 12 4.2.6 MACRO_NAME = name MACRO_PARAMETERS = (list) . . . . . . . . . . . . . . 12 4.3 Data Administration Simple Statements. . . . . . . . . . . . 12 4.4 Replacement Class Simple Statements. . . . . . . . . . . . . 13 5 CREATING MAP FILES. . . . . . . . . . . . . . . . . . . . . . . . . 13 5.1 Adding LVOs. . . . . . . . . . . . . . . . . . . . . . . . . 14 5.2 Adding Delimitation. . . . . . . . . . . . . . . . . . . . . 15 5.3 Adding ADID Values . . . . . . . . . . . . . . . . . . . . . 16 5.4 Adding the Data. . . . . . . . . . . . . . . . . . . . . . . 18 5.5 Prefixing the Data . . . . . . . . . . . . . . . . . . . . . 19 5.6 Padding the Data . . . . . . . . . . . . . . . . . . . . . . 20 5.7 Making Macros. . . . . . . . . . . . . . . . . . . . . . . . 20 5.8 Entering Service Class Data. . . . . . . . . . . . . . . . . 22 6 PVL VERIFIER. . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 6.1 Data Dictionary Files. . . . . . . . . . . . . . . . . . . . 25 7 WRAP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 7.1 Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 26 7.2 OPTIONS.DEF File . . . . . . . . . . . . . . . . . . . . . . 26 7.2.1 VALID_CAIDS . . . . . . . . . . . . . . . . . . . . . 27 7.2.2 LVO_NAMES . . . . . . . . . . . . . . . . . . . . . . 27 7.2.3 MARKER_TYPE . . . . . . . . . . . . . . . . . . . . . 28 7.2.4 WARNINGS. . . . . . . . . . . . . . . . . . . . . . . 28 7.3 WRAP Map Language File Macros. . . . . . . . . . . . . . . . 28 8 UNWRAP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 8.1 Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 29 8.2 OPTIONS.DEF File . . . . . . . . . . . . . . . . . . . . . . 30 8.2.1 VALID_CAIDS . . . . . . . . . . . . . . . . . . . . . 30 8.2.2 FILE_EXTENSIONS . . . . . . . . . . . . . . . . . . . 31 8.2.3 RESOLVE REPLACEMENT (R) CLASSES . . . . . . . . . . . 31 8.2.4 MARKER_TYPE . . . . . . . . . . . . . . . . . . . . . 31 8.2.5 WARNINGS. . . . . . . . . . . . . . . . . . . . . . . 32 9 EXTRACT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 9.1 Options. . . . . . . . . . . . . . . . . . . . . . . . . . . 32 10 MACROGEN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 APPENDIX A - MAP LANGUAGE SPECIFICATION . . . . . . . . . . . . . . .A-1 A-1 INTRODUCTION. . . . . . . . . . . . . . . . . . . . . . . .A-1 A-2 CONVENTIONS. . . . . . . . . . . . . . . . . . . . . . . . .A-1 A-3 AGGREGATION DEFINITIONS. . . . . . . . . . . . . . . . . . .A-1 A-3.1 LVO Aggregation . . . . . . . . . . . . . . . . . . .A-1 A-3.2 SERVICE_DATA Aggregation. . . . . . . . . . . . . . .A-2 A-3.3 Macro Aggregation . . . . . . . . . . . . . . . . . .A-2 A-4 SIMPLE STATEMENTS. . . . . . . . . . . . . . . . . . . . . .A-3 A-4.1 ADID = adidname . . . . . . . . . . . . . . . . . . .A-3 A-4.2 DELIMITATION = (type, delimitation_parameter) . . . .A-4 A-4.3 Data Administration Simple Statements . . . . . . . .A-4 A-4.3.1 ADIDNAME = adid. . . . . . . . . . . . . . . .A-4 A-4.3.2 DEDID = adid . . . . . . . . . . . . . . . . .A-4 A-4.3.3 DDRID = adid . . . . . . . . . . . . . . . . .A-5 A-4.3.4 SUPID = adid . . . . . . . . . . . . . . . . .A-5 A-4.4 Replacement Class Simple Statements . . . . . . . . .A-5 A-4.4.1 REFERENCETYPE = (attrib_1, attrib_2,..., attrib_n) . . . . . . . . . . . . . . . . . . . .A-5 A-4.4.2 LABEL = label. . . . . . . . . . . . . . . . .A-5 A-4.4.3 REFERENCE = pathname . . . . . . . . . . . . .A-6 A-4.5 INCLUDE_DATA_FILE = pathname. . . . . . . . . . . . .A-6 A-4.6 PRE_DATA_DELIMITER = (val_1, val_2, ..., val_n) . . .A-6 A-4.7 PAD_NEXT_LVO_VALUE = (record_length, char). . . . . .A-7 A-4.8 REFERENCE_DATA_FILE = pathname. . . . . . . . . . . .A-7 A-4.9 MACRO_NAME = name . . . . . . . . . . . . . . . . . .A-8 A-4.10 MACRO_PARAMETERS = (list). . . . . . . . . . . . . .A-9 A-5 MACRO EXAMPLES . . . . . . . . . . . . . . . . . . . . . . .A-9 A-5.1 ZKI Macro . . . . . . . . . . . . . . . . . . . . . .A-9 A-5.2 Description Data Macro. . . . . . . . . . . . . . . A-10 APPENDIX B - WRAP, UNWRAP, and EXTRACT EXAMPLES . . . . . . . . . . .B-1 B-1 Create the MAP File. . . . . . . . . . . . . . . . . . . . .B-1 B-2 Verify the MAP File. . . . . . . . . . . . . . . . . . . . .B-1 B-3 WRAP the SFDU. . . . . . . . . . . . . . . . . . . . . . . .B-2 B-4 UNWRAP the SFDU. . . . . . . . . . . . . . . . . . . . . . .B-2 B-5 EXTRACT Objects from the SFDU. . . . . . . . . . . . . . . .B-4 1 INTRODUCTION 1.1 Identification This document is the User's Guide for the Standard Formatted Data Unit (SFDU) Software Tool Kit. The information contained in this document is applicable to Phase I of the development effort. 1.2 Overview The SFDU Software Tool Kit is a collection of software libraries and applications that will allow users the ability to implement data format standards as specified by the Consultative Committee for Space Data Systems (CCSDS). 1.3 Document Scope This document is intended for users who will be utilizing Tool Kit Applications. A Programmer's Guide is available for those who want to incorporate Tool Kit functionality into their own applications. This document assumes the reader is familiar with the SFDU concept as presented by the CCSDS. It also assumes the Tool Kit software has been installed on the particular machine which will be utilized. 1.4 Other Documents 1) STANDARD FORMATTED DATA UNIT SOFTWARE TOOL KIT SOFTWARE SPECIFICATION DOCUMENT, Ron Green; Norbert Piega, June 1991 2) STANDARD FORMATTED DATA UNIT SOFTWARE TOOL KIT PROGRAMMER'S GUIDE, Ron Green; Mike Aronsson, October 1993 3) RECOMMENDATION FOR SPACE DATA SYSTEM STANDARDS, STANDARD FORMATTED DATA UNITS -- STRUCTURE AND CONSTRUCTION RULES BLUE BOOK, Consultative Committee for Space Data Systems (CCSDS), May 1992 4) RECOMMENDATION FOR SPACE DATA SYSTEM STANDARDS, PARAMETER VALUE LANGUAGE SPECIFICATION (CCSD0006) BLUE BOOK, Consultative Committee for Space Data Systems (CCSDS), May 1992 5) RECOMMENDATION FOR SPACE DATA SYSTEM STANDARDS, STANDARD FORMATTED DATA UNITS -- A TUTORIAL, Consultative Committee for Space Data Systems (CCSDS), May 1992 1.5 Acronyms and Abbreviations ADID - Authority Description Identifier CAID - Control Authority Identifier CCSDS - Consultative Committee for Space Data Systems DDID - Data Description Identifier DDU - Description Data Unit IDU - Information Data Unit LVO - Label Value Object PVL - Parameter Value Language SFDU - Standard Formatted Data Unit 2 TOOL KIT OVERVIEW The Standard Formatted Data Unit (SFDU) Software Tool Kit consists of the following eight components: PVL Verifier, PVL Library, SFDU Library, WRAP application, UNWRAP application, EXTRACT application, the MAP Language, and MACROGEN (MAP Language Macro generator) application. They are described in more detail below. 2.1 Parameter Value Language (PVL) Verifier Application This standalone application program can be used to parse and verify PVL statements contained in files. This is useful in checking the syntax of Map Language files used in conjunction with the WRAP application of the Tool Kit. 2.2 PVL Library The PVL Library is a collection of C functions that can be integrated into user applications to create and process PVL statements. Certain functions in the PVL Library have already been linked into the SFDU Library. These functions were also used to create the PVL Verifier application. Complete documentation on the PVL Library can be found in the SFDU SOFTWARE TOOL KIT PROGRAMMER'S GUIDE. 2.3 SFDU Library The SFDU Library is a collection of C functions that can be linked into user applications to create and manipulate SFDUs. These functions have been used to create the WRAP and UNWRAP applications of the Tool Kit. Complete documentation on the SFDU Library can be found in the SFDU SOFTWARE TOOL KIT PROGRAMMER'S GUIDE. 2.4 WRAP Application The WRAP program is a standalone application that can be used to wrap individual data files (catalog data, application data, etc.) into Standard Formatted Data Units. The application makes use of user specified information on how to build the SFDU using Map Language statements. 2.5 UNWRAP Application The UNWRAP program is a standalone application that can be used to unwrap data files from Standard Formatted Data Units. UNWRAP removes all SFDU related information (labels, markers, etc.) and leaves the original data that was used to create the SFDU. 2.6 EXTRACT Application The EXTRACT program is a standalone application that can be used to extract specified data objects from Standard Formatted Data Units. EXTRACT removes all SFDU related information (labels, markers, etc.) and leaves the original data (of specified class) that was used to create the SFDU. 2.7 MAP Language The MAP Language is a set of PVL statements that are used throughout the Tool Kit to describe SFDUs. Files containing Map Language statements (MAP files) provide the capability to describe how an SFDU is to be wrapped. The PVL statements that make up this language are described in Section 4. 2.8 MACROGEN Application The MACROGEN program can be used to create Map Language macros from generic Map Language files. The macros can then be used to create specific SFDUs (via the WRAP application) that have the same structure as described by the macro statements. 3 TOOL KIT PLATFORMS This section discusses the different hardware/software platforms that can utilize the SFDU Software and any limitations they have. Developers wishing to incorporate Tool Kit functionality into their applications should review the SFDU SOFTWARE TOOL KIT PROGRAMMER'S GUIDE for information on specific platforms. 3.1 SUN/UNIX The Tool Kit was designed to run on the SUN/UNIX platform. The Tool Kit was tested on a Sun SPARCstation running Sun OS 4.1 and the SUN C compiler. 3.2 PC/DOS The Tool Kit was developed and tested on the PC-AT (286) using MS-DOS Version 5. There is no reason the Tool Kit would not work using a lower version of DOS such as Version 3.3, however Version 5 is recommended since DOS can be relocated to upper memory (i.e., above 640k) thus freeing up more memory for the Tool Kit. Tool Kit programs will stop execution and generate an error message if not enough memory can be allocated to store information about the SFDU. This would happen when there is a large amount of LVOs in an SFDU. 3.3 VAX/VMS Currently there is no support for the VAX/VMS platform. This is due to the different implementation of File I/O utilized by VMS. Later versions of the Tool Kit will support this platform. 3.4 Software Distribution Copies of the software can be obtained from the ftp anonymous account on binky.jpl.nasa.gov under the pub/current directory. A tar file of all needed files is in the /pub/sfdutool/current/tar directory. DOS users who don't have access to a compiler can find the executables in /pub/sfdutool/current/dosexe. There is also a failure report form which can be utilized to report problems. Procedures for reporting problems/questions, etc. are contained in the README file contained in the /pub directory. 4 MAP LANGUAGE The Map Language is a set of statements implemented using the Parameter Value Language (PVL). These statements adhere to the guidelines established in the RECOMMENDATION FOR SPACE DATA SYSTEM STANDARDS, PARAMETER VALUE LANGUAGE SPECIFICATION (CCSD0006) BLUE BOOK. The purpose of these statements is to form MAPs that describe how SFDUs are constructed (UNWRAP) or how they are to be constructed (WRAP). The Map Language is used primarily with the WRAP application, however there is an option implemented in UNWRAP which will produce a MAP of an SFDU. The following section contains the Map Language statements and a brief explanation of each. For a complete definition of each statement, as well as the set of valid values, consult the MAP LANGUAGE SPECIFICATION contained in Appendix A. To review examples and usage of Map Language statements, consult Section 5. 4.1 Aggregations BEGIN_OBJECT = lvo_type END_OBJECT = lvo_type The lvo_type aggregation indicates the type of LVO to be made (e.g., BEGIN_OBJECT = SFDU or BEGIN_OBJECT = VOLUME_DATA). All BEGIN_OBJECTs must have a matching END_OBJECT. BEGIN_OBJECT = SERVICE_DATA END_OBJECT = SERVICE_DATA The SERVICE DATA aggregation is entered exactly as shown with simple statements entered between the BEGIN and END objects. BEGIN_OBJECT = MACRO END_OBJECT = MACRO Finally, the MACRO aggregation is used to define a macro which could be considered much like subroutines in a computer program, with parameters taking on different values each time the macro is processed. 4.2 Simple Statements The following is a list of simple statements used within the Map Language. An explanation follows each statement(s). 4.2.1 ADID = adidname The ADID statement is used to indicate the ADID name that was (will be) used to construct the label for the LVO. 4.2.2 DELIMITATION = (type, delimitation_parameter) The DELIMITATION statement is used to indicate the method that will be used to delimit the LVO. Available delimitation methods are Delimitation by Length (specified in ASCII or Binary), Delimitation by Marker Pattern, and Delimitation by End-of-File(s) (Sequential EOF, Contiguous EOFs, or Shared EOF). 4.2.3 INCLUDE_DATA_FILE = pathname REFERENCE_DATA_FILE = pathname The INCLUDE_DATA_FILE statement is used to indicate the file whose contents will be inserted directly into the SFDU. This is different from the REFERENCE_DATA_FILE statement which will cause a REPLACEMENT class LVO to be created which will reference the file name. The key difference between these statements is that one will cause data to be INCLUDED directly into the SFDU while the other will cause a REFERENCE to be made to the external file. 4.2.4 PRE_DATA_DELIMITER = (list) The PRE_DATA_DELIMITER statement is used to prefix data to the LVO value. The delimitation characters specified in the value list will be written to the SFDU before the actual LVO value. The list can contain any combination of spaces, carriage returns, linefeeds, and semicolons. Any library function requesting the value field of an LVO with a PRE_DATA_DELIMITER will get the original value plus the delimitation data. 4.2.5 PAD_NEXT_LVO_VALUE = (record_length, char) The PAD_NEXT_LVO_VALUE statement is used to force the value field of the next LVO to begin on a multiple of the value specified by record length. The additional char characters are included as part of the value field of the current LVO. Some caution should be used when selecting a character to pad with, as that character will affect the actual value of the LVO. Any library function requesting the value field of a padded LVO will get the original value plus the padded data. 4.2.6 MACRO_NAME = name MACRO_PARAMETERS = (list) The MACRO_NAME statement is used to identify the macro being defined within a macro aggregation. The MACRO_PARAMETERS statement will show the parameters that are to be substituted for when the macro is processed. 4.3 Data Administration Simple Statements ADIDNAME = adid DEDID = adid DDRID = adid SUPID = adid The values for these statements should be 8 byte RESTRICTED ASCII codes that represent ADID names such as CCSD0001 or NJPLL015. For further details, consult the RECOMMENDATION FOR SPACE DATA SYSTEM STANDARDS, STANDARD FORMATTED DATA UNITS -- STRUCTURE AND CONSTRUCTION RULES BLUE BOOK. 4.4 Replacement Class Simple Statements REFERENCETYPE = refenv LABEL = label REFERENCE = pathname The value for the REFERENCETYPE statement is one of the proposed Referencing Environment Specifications contained in an Annex of the RECOMMENDATION FOR SPACE DATA SYSTEM STANDARDS, STANDARD FORMATTED DATA UNITS -- STRUCTURE AND CONSTRUCTION RULES BLUE BOOK. These specifications instruct the Tool Kit Software how to interpret the file names listed as values for the REFERENCE statement. Currently the Tool Kit supports only two defined specifications: CCSDS1 and CCSDS2. The '$CCSDS1' is most similar to filenames associated with the DOS environment. The filenames can have up to eight (8) characters and an optional three (3) letter extension, separated by a period (.). The '$CCSDS2' allows for larger filenames and extensions. Consult the Recommendation for complete syntax. The value for the LABEL statement is a 20 byte RESTRICTED ASCII string that follows the rule of label construction as specified in the Recommendation. The value for REFERENCE statement is the complete specification for a file that will be referenced in the Replacement Class LVO. 5 CREATING MAP FILES The following section steps through the process of specifying SFDUs using the Map Language statements described in Section 4. The Map Language statements are organized into a MAP file which is used as input into the WRAP application. The WRAP application will use data files specified in the MAP file to create (wrap) an SFDU file. The MAP file can be created using any simple ASCII text editor such as vi on UNIX platforms or EDIT on MS-DOS 5 platforms. Although any editor can be used, a full screen editor is highly recommended. Throughout this section, the examples will show which bytes (characters) of the LVO label will be affected by the Map Language Statements. 5.1 Adding LVOs To begin an SFDU, we must encompass all other LVOs to be defined. So the first part of the MAP would be: BEGIN_OBJECT = SFDU . . END_OBJECT = SFDU Now the decision should be made as to what to put in the SFDU. Our example will be a ZKI SFDU, where the CATALOGUE DATA (K) and APPLICATION DATA (I) are wrapped inside an SFDU (Z). Adding these aggregations would change the MAP to be: BEGIN_OBJECT = SFDU BEGIN_OBJECT = CATALOGUE_DATA . END_OBJECT = CATALOGUE_DATA BEGIN_OBJECT = APPLICATION_DATA . END_OBJECT = APPLICATION_DATA END_OBJECT = SFDU Even though our example is limited in scope, more LVOs can be added to this MAP. For example, a ZKII type SFDU can be created by adding another APPLICATION aggregation after the first one, or another SFDU could be added directly after the first creating a file which contains two SFDUs. The following table summarizes the recognized LVO aggregation types. The last column shows which bytes of a 20 byte label are affected by the LVO aggregation statements: LVO TYPE CLASS ID LABEL EXAMPLE SFDU Z CCSDxZxx0001xxxxxxxx DDU F CCSDxFxx0005xxxxxxxx IDU U CCSDxUxx0009xxxxxxxx REPLACEMENT R CCSDxRxx0003xxxxxxxx DATA_ADMINISTRATION C CCSDxCxx0004xxxxxxxx APPLICATION_DATA I xxxxxIxxxxxxxxxxxxxx SUPPLEMENTARY_DATA S xxxxxSxxxxxxxxxxxxxx DATA_DESCRIPTION D xxxxxDxxxxxxxxxxxxxx DATA_ENTITY E xxxxxExxxxxxxxxxxxxx CATALOGUE_DATA K xxxxxKxxxxxxxxxxxxxx VOLUME_DATA V xxxxxVxxxxxxxxxxxxxx SERVICE_DATA The SERVICE_DATA aggregation is used in conjunction with the REPLACEMENT and DATA_ADMINISTRATION class LVOs. This aggregation is used primarily to separate the actual service data to be entered into the LVO and the characteristics of the LVO itself such as ADID and delimitation. See Section 5.8 on 'Entering Service Class Data' for further explanation. 5.2 Adding Delimitation All LVOs (aggregations) must have some delimitation method. The SFDU encompassing the other LVOs is usually delimited by a SHARED_EOF while the others can use other methods such as ASCII_LENGTH or MARKER. The 'DELIMITATION = (type, parameter)' statement should be entered as follows: BEGIN_OBJECT = SFDU DELIMITATION = (SHARED_EOF, NULL) BEGIN_OBJECT = CATALOGUE_DATA DELIMITATION = (MARKER, $$INFO$$) . END_OBJECT = CATALOGUE_DATA BEGIN_OBJECT = APPLICATION_DATA DELIMITATION = SHARED_EOF . END_OBJECT = APPLICATION_DATA END_OBJECT = SFDU The value for the parameter in the DELIMITATION statement is NULL except for the cases of MARKER, NUMBER_OF_EOFS, and CONTIG_EOF. The parameter for the MARKER method must be an 8 byte RESTRICTED ASCII string while the EOF type parameters are the actual number of EOFs in an ASCII string (e.g., 3 EOFs would be '00000003'). Note that the EOF parameters are not implemented in Phase I of the Tool Kit. If any parameters other than 'NULL' are entered for LENGTH or SHARED_EOF, they will be ignored. If a BINARY_LENGTH delimitation method is entered into a MAP file, the Tool Kit will use ASCII length delimitation if the number can fit in 8 bytes (i.e. n <= 99999999). This is done because it is easier to read the labels of the SFDU when they are readable ASCII characters. The following table summarizes the different delimitation methods available in the Tool Kit. The last column shows which bytes of a 20 byte version 3 label are affected by the DELIMITATION statement (bytes 5, 7, 8, and 13-20): DELIM TYPE DELIM PARAMETER V3 LABEL EXAMPLE ASCII_LENGTH NULL xxxx3xA0xxxx99999999 BINARY_LENGTH NULL xxxx3xB0xxxx99999999 MARKER 8 BYTE RA STRING xxxx3xS0xxxxAPATTERN SHARED_EOF 00000001 xxxx3xF0xxxx00000001 NUMBER_EOF NUMBER IN 8 BYTE ASCII STRING xxxx3xE0xxxx99999999 CONTIGUOUS_EOF NUMBER IN 8 BYTE ASCII STRING xxxx3xC0xxxx99999999 5.3 Adding ADID Values Next an ADID should be specified for each LVO. CCSDS standard LVOs already have default ADIDs. These are SFDU (CCSD0001), DESCRIPTION_DATA_UNIT (CCSD0005), INFORMATION_DATA_UNIT (CCSD0009), DATA_ADMINISTRATION (CCSD0004), and REPLACEMENT_CLASS (CCSD0003). If the CCSDS standard LVOs do not have an ADID statement, the default ADID previously listed will be used. All other LVOs must have an adidname specified in an ADID statement. With the updated ADID statements our MAP file will look as follows: BEGIN_OBJECT = SFDU DELIMITATION = (SHARED_EOF, NULL) BEGIN_OBJECT = CATALOGUE_DATA ADID = NJPLPDSX DELIMITATION = (MARKER, $$INFO$$) . END_OBJECT = CATALOGUE_DATA BEGIN_OBJECT = APPLICATION_DATA DELIMITATION = SHARED_EOF ADID = NJPL0043 . END_OBJECT = APPLICATION_DATA END_OBJECT = SFDU Note that the order of the ADID and DELIMITATION statements does not matter in the MAP FILE. Also, remember that since an SFDU is a CCSDS standard LVO, an ADID is not required. The following table summarizes the default ADIDs for the CCSDS recognized standard LVOs. The last column shows which bytes of a 20 byte version 3 label are affected by the ADID statement (bytes 1-4 are the CAID, while bytes 9-12 are the DDID): LVO TYPE DEFAULT ADID CLASS V3 LABEL EXAMPLE SFDU CCSD0001 Z CCSDxxxx0001xxxxxxxx DESCRIPTION_DATA_UNIT CCSD0005 F CCSDxxxx0005xxxxxxxx INFORMATION_DATA_UNIT CCSD0009 U CCSDxxxx0009xxxxxxxx DATA_ADMINISTRATION CCSD0004 C CCSDxxxx0004xxxxxxxx REPLACEMENT_CLASS CCSD0003 R CCSDxxxx0003xxxxxxxx 5.4 Adding the Data Finally, the actual data must be incorporated into the SFDU. This can be done in one of two ways. Data to be entered directly into the SFDU is specified using the INCLUDE_DATA_FILE statement, while data to be referenced by the SFDU is specified using the REFERENCE_DATA_FILE statement. The REFERENCE_DATA_FILE will cause a REPLACEMENT Class LVO to be created which makes a reference to the data file. The example will make use of both statements. BEGIN_OBJECT = SFDU DELIMITATION = (SHARED_EOF, NULL) BEGIN_OBJECT = CATALOGUE_DATA ADID = NJPLPDSX DELIMITATION = (MARKER, $$INFO$$) INCLUDE_DATA_FILE = MO.LBL END_OBJECT = CATALOGUE_DATA BEGIN_OBJECT = APPLICATION_DATA DELIMITATION = SHARED_EOF ADID = NJPL0043 INCLUDE_DATA_FILE = MO.DAT END_OBJECT = APPLICATION_DATA END_OBJECT = SFDU Both the CATALOGUE_DATA contained in the file MO.LBL and the data in the file MO.DAT will be entered directly into the SFDU. The resulting SFDU can be represented graphically as shown in Figure 4.4.1. If the SFDU were to be built with a REPLACEMENT_CLASS LVO by substituting 'REFERENCE_DATA_FILE = MO.DAT' for 'INCLUDE_DATA_FILE = MO.DAT', the resulting LVO is graphically shown in Figure 4.4.2. It is important to point out that the files specified using the INCLUDE_DATA_FILE or REFERENCE_DATA_FILE statements should contain just data and not LVOs and/or SFDUs. LVOs/SFDUs already contained in a file can be incorporated into other SFDUs using the SERVICE CLASS DATA aggregation (see Section 5.8). The value specified for the LABEL keyword within the created REPLACEMENT Class will use an overriding delimitation method of SHARED_EOF (F) rather than the MARKER (S) value stated in the DELIMITATION keyword. This is because all referenced data files are treated as unlabelled data delimited with an EOF. The REPLACEMENT Class LVO itself is delimited by length. The current example would generate a REPLACEMENT Class such as this: ...... . CCSD3RA0000300000070 REFERENCETYPE = $CCSDS1 LABEL = SOME3IF0DATA00000001 REFERENCE = MO.DAT Again, note from the LABEL statement that MO.DAT is treated as unlabelled data. 5.5 Prefixing the Data In certain cases, some applications process data while they are still in SFDU format. For instance, some record length applications will read the SFDU as records terminated by a carriage return - line feed combination. This way the application can read over the first record to get to the next record that might contain data of interest. Usually the created data file doesn't put a record terminator at the beginning of the file. So when the data file is wrapped into SFDU format, a request to read the first record returns the SFDU label(s) and the data. The PRE_DATA_DELIMITER statement can be used to put delimitation characters between the LVO label and its value field. For example, the following Map Language statements will generate the SFDU as listed: BEGIN_OBJECT = CATALOGUE_DATA ADID = NJPLPDSX DELIMITATION = (MARKER, $$INFO$$) INCLUDE_DATA_FILE = MO.LBL END_OBJECT = CATALOGUE_DATA Generated SFDU: NJPL3KS0PDSX$$INFO$$START_K_DATA = HERE . . By adding a PRE_DATA_DELIMITER statement as follows, the generated SFDU changes as shown: BEGIN_OBJECT = CATALOGUE_DATA ADID = NJPLPDSX DELIMITATION = (MARKER, $$INFO$$) PRE_DATA_DELIMITER = (CR, LF) INCLUDE_DATA_FILE = MO.LBL END_OBJECT = CATALOGUE_DATA Generated SFDU: NJPL3KS0PDSX$$INFO$$ START_K_DATA = HERE . . 5.6 Padding the Data Sometimes it is necessary to have LVO values begin on a record boundary. This allows applications to read SFDUs as whole records until the record of interest is found. The PAD_NEXT_LVO_VALUE provides a way to do this. Adding the PAD_NEXT_LVO_VALUE to the previous example yields the following results: BEGIN_OBJECT = CATALOGUE_DATA ADID = NJPLPDSX DELIMITATION = (MARKER, $$INFO$$) PRE_DATA_DELIMITER = (CR, LF) PAD_NEXT_LVO_VALUE = (512, 'X') INCLUDE_DATA_FILE = MO.LBL END_OBJECT = CATALOGUE_DATA BEGIN_OBJECT = SIMPLE_DATA ADID = NJPL0043 DELIMITATION = SHARED_EOF INCLUDE_DATA_FILE = MO.DAT END_OBJECT Generated SFDU: NJPL3KS0PDSX$$INFO START_K_DATA = HERE . . KEYWORD-VALUE PAIRS . . . START PADDING XXXXXXXXXXXXXXXXX. XXXXNJPL3IF0L004300000001 START_I_DATA = HERE 5.7 Making Macros Macros are collections of Map Language statements contained within aggregations that support variable values. It can be compared to a function or subroutine call in a programming language. Macros can be used to create multiple SFDUs having the same general structure but different data and/or ADIDs. The macro can be invoked with different parameters every time the same type of SFDU is needed. In the previous example from Section 5.3, if the same SFDU structure was desired for Mars Observer data, the information in the MAP file would have to be edited to reflect different file names and possibly different ADID values. This would produce two MAP files describing the same SFDU structure which could be specified instead using the following macro: BEGIN_OBJECT = MACRO MACRO_NAME = ZKI MACRO_PARAMETERS = (CAT_ADID, CATALOG_FILE, DAT_ADID, DATA_FILE) BEGIN_OBJECT = SFDU DELIMITATION = (SHARED_EOF, NULL) BEGIN_OBJECT = CATALOGUE_DATA ADID = CAT_ADID DELIMITATION = (MARKER, $$INFO$$) INCLUDE_DATA_FILE = CATALOG_FILE END_OBJECT = CATALOGUE_DATA BEGIN_OBJECT = APPLICATION_DATA DELIMITATION = (SHARED_EOF, NULL) ADID = DAT_ADID INCLUDE_DATA_FILE = DATA_FILE END_OBJECT = APPLICATION_DATA END_OBJECT = SFDU END_OBJECT = MACRO The above macro may be invoked as follows: ZKI = (NJPLPDSX, MO.LBL, SOMEDATA, MO.DAT) ZKI = (NJPLPDSX, MAGELLAN.LBL, SOMEDATA, MAGELLAN.DAT) These macro statements can be contained in the same file as the macro, in a separate file, or invoked on the WRAP command line. These ZKI macro calls would produce two SFDUs: One ZKI structure containing Mars Observer data and another containing Magellan data. The SFDUs would be created when the ZKI statements were encountered at the end of the MAP file. The invoking macro statements could also be contained in a separate parameter file, or single statements could be entered on the WRAP command line. In the above example, the macro definition would be processed using the first set of parameters followed by a second processing using the next set. For each case, the actual values for CAT_ADID, CATALOG_FILE, etc. would be substituted into the macro. The last two ZKI keyword statements are not required in the MAP file. Ideally, these statements would be entered on the command line when invoking the WRAP application (see Section 7 for WRAP options). Any keyword value in a macro can be a parameter, however the keywords themselves can not be parameters. The number of parameters in the invoking statement 'ZKI = (...)' should match the number in the 'MACRO_PARAMETERS = (...)' statement. Macros can also be generated from existing MAP Language files by using the MACROGEN application (see Section 10.) 5.8 Entering Service Class Data The RECOMMENDATION FOR SPACE DATA SYSTEM STANDARDS, STANDARD FORMATTED DATA UNITS -- STRUCTURE AND CONSTRUCTION RULES BLUE BOOK makes reference to two types of Service Class LVOs: The REPLACEMENT_DATA and the DATA_ADMINISTRATION classes. These LVOs can be entered directly into the MAP file by using a SERVICE_DATA aggregation. The primary purpose of this aggregation is to enter the data directly into the MAP file rather than enter the data into a separate file and then use an INCLUDE_DATA_FILE statement. A REPLACEMENT_DATA LVO example follows: BEGIN_OBJECT = REPLACEMENT_DATA DELIMITATION = (MARKER, ABCDEFG) BEGIN_OBJECT = SERVICE_DATA REFERENCETYPE = $CCSDS2 LABEL = ATTACHED REFERENCE = ANOTHER.SFDU END_OBJECT = SERVICE_DATA END_OBJECT = REPLACEMENT_DATA The secondary purpose of the SERVICE_DATA aggregation is to provide a way to create more complex SFDU structures. The above example will create an SFDU that points to another SFDU via a REPLACEMENT_DATA LVO. This would not be possible using the REFERENCE_DATA_FILE (or INCLUDE_DATA_FILE) statement. The REFERENCE_DATA_FILE statement assumes the data file is just plain data and not data wrapped into LVOs. Note that since REPLACEMENT_DATA LVOs are CCSDS standard LVOs, there is no need to specify an ADID statement. An ADID of CCSD0003 will be used when creating the label for this LVO. Complete information on valid keywords and values for REPLACEMENT_DATA Class LVOs are contained in the CCSDS RECOMMENDATION FOR SPACE DATA SYSTEM STANDARDS, SFDUs -- STRUCTURE AND CONSTRUCTION RULES BLUE BOOK. The next example is of the DATA_ADMINISTRATION Service Class: BEGIN_OBJECT = DATA_ADMINISTRATION ADID = USEMYOWN DELIMITATION = (ASCII_LENGTH, NULL) BEGIN_OBJECT = SERVICE_DATA ADIDNAME = NSSD0041 END_OBJECT = SERVICE_DATA END_OBJECT = DATA_ADMINISTRATION These MAP statements produce the following DATA_ADMINISTRATION LVO: ...... . CCSD3CA0000400000021 ADIDNAME = NSSD0041 . ...... The ADID of USEMYOWN was not incorporated into the label because DATA_ADMINISTRATION LVOs are CCSDS standard LVOs, therefore they use a default ADID of CCSD0004. Information on valid keywords and values for the Data Administration Class LVOs can also be found in the Structure and Construction Blue Book. 6 PVL VERIFIER The PVL Verifier is a command line application that validates files containing Parameter Value Language (PVL) formatted data. Input PVL data is parsed and checked according to the RECOMMENDATION FOR SPACE DATA SYSTEM STANDARDS, PARAMETER VALUE LANGUAGE SPECIFICATION (CCSD0006) BLUE BOOK. By default, the verifier determines keyword validity and value data types by checking compliance to the CCSDS PVL standard. The use of a data dictionary for checking valid keywords and expected value types is supplied as an option (see -k option). Other options included are a parsing report dump, a PVL table generator, and other parsing set-up options. Syntax errors are reported and directed to stderr. Syntax errors terminate parsing of the file. Other errors may terminate the parsing as well unless the -i option is used. Usage summary: pvl [-k] [-d ] [-i] [-r] [-q] [-t ] [-b] [-c] [-e] where [] is optional and <> is required. filename is the name of the SFDU file to be validated. Options: -k Keyword lookup Turn on keyword lookup of data dictionary (see -d option) for the following file. By default, the utility does not read any dictionary table. If this option is used, the program looks up all keywords and validates value data types using the data dictionary. -d data_dictionary_file Use data_dictionary_file as data dictionary By default, the program uses a file named ./datadict.dat if the -k option is used. This option may be used to change the dictionary file so that multiple versions or dictionaries may be maintained. A universal data dictionary syntax has not yet been established by the CCSDS. Currently, several dictionary syntaxes are being reviewed. The resulting dictionary from these reviews will try to incorporate the general features of each and will be incorporated into the Tool Kit. The data dictionary format used here is a prototype and is unlikely to be used. The format is detailed in Section 6.1. -i Ignore errors Attempt to ignore syntax errors and continue parsing. This is only possible in some cases. For instance, grammar errors found by the parser are usually fatal because the current state becomes ambiguous. Syntax errors in value strings can often be ignored. -r Display report Print a formatted report of the parsed data tree after parsing. The report is in the form of 'keyword = value' expressions with statement numbers. Note that the converted value is shown for values that are of types real, integer, and non-decimal. -q Quiet mode All error messages are suppressed in this mode and only the return status is available to report on program results. -t n Allocate dictionary table for n entries This option allows the user to configure the tool to be able to read large dictionary tables or to conserve memory when small dictionaries are being used. By default, the program allocates enough memory for a dictionary table of 1000 entries. If more than this number of entries are read from the dictionary file, the program will fail. The value of n is limited by available memory. -b Generate table Create a table of keyword values. A filename vs. parameters table (where parameters are interactively requested) is printed. Note that this disables the -r option and enables the -q option. -c Convert keywords and unquoted values to upper case This option converts keywords and unquoted strings to upper case during parsing. This allows the semantic meaning of keyword values to be independent of case (e.g., BEGIN_OBJECT = a is equivalent to BEGIN_OBJECT = A). This is the SFOC/PDS convention. -e Disallow empty values The PVL standard allows empty strings or empty lists as values. While this is syntactically legal, it may make no sense semantically to the application. If you wish to disallow empty values, you can use this option and an error will be generated when any empty value is encountered. If this option is used with the -i option, only a warning is issued and processing continues. 6.1 Data Dictionary Files By default, the data dictionary file ./datadict.dat is read at start-up when the -k option is used. The data dictionary file contains a lookup table which the PVL utility can use to verify each keyword it parses. The file must be composed of records, one per line, containing the keyword, value data type, and optional units name, separated by white space. The keywords can be in either upper or lower case, although upper case is recommended. The data types can be any of the following: REAL, INTEGER, DATE, TIME, or NON_DECIMAL. If no unit name is given, the value is considered unitless. Comments can be placed in the data dictionary file by placing a '#' symbol in the first column of a line. EXAMPLES: The following are statements that could be contained in a data dictionary file: #Column name General data type Unit A_AXIS_RADIUS REAL km BUILD_DATE DATE EARTH_RECEIVED_TIME TIME OCTAL_NUMBER NON_DECIMAL ALT_FLAG2_GROUP INTEGER 7 WRAP WRAP is a command line utility which creates an SFDU by interpreting an SFDU Structure Map. When using this program, the names of the files containing the Structure Map and the output for the SFDU must be specified. A complete example of the WRAP application is shown in Appendix B. Usage summary: wrap [-m ] [-o ] [-p ] [-s <"statement">] [-x ] [-w ] [-j] [-f ] where [] is optional and <> is required. 7.1 Options Options: -m inmapfile Use inmapfile as the input MAP file to be used for building the output SFDU. -o sfdufile Store the SFDU created by WRAP in the output file sfdufile. -p parameterfile Perform macro call(s) listed in parameterfile. The parameterfile must contain valid macro invocations of a macro defined in the input MAP file inmapfile (see -m option). -s "statement" Perform the macro call statement specified in the command line. Note that statement must be a valid Map Language statement and must always be enclosed by double quotes. Also, the macro being called must be defined in the input MAP file inmapfile (see -m option). -x optionsfile Use an options file optionsfile to specify execution options instead of through the command line. Other options not available through the command line also exist. See the following section for details. -w warningcode Turn on/off printing of warning messages. The warningcode may be: 1 - print warnings, 0 - do not print warnings. Warnings are non-fatal error messages generated by the WRAP program. -j Use JPL standard markers This option uses the JPL standard marker (CCSD3RE00000...) for LVOs delimited by marker patterns in the output SFDU. By default, the CCSDS standard marker (CCSD$$MARKER...) is used. -f msg_file Direct error (and informational) output messages to the specified msg_file (instead of directing them to standard output = default). 7.2 OPTIONS.DEF File Some of the options listed in the OPTIONS section of the WRAP application can be specified in an options file. The options are specified using PVL statements. The options that can be placed in the options file are listed here with a summary following. A OPTIONS.DEF file is included in the software distribution with the default option values. VALID_CAIDS = { NJPL } BEGIN_OBJECT = LVO_NAMES Z = SFDU /* SFDU */ U = IDU /* IDU */ F = DDU /* DDU */ C = DATA_ADMINISTRATION /* DATA_ADMINISTRATION */ R = REFERENCE /* REFERENCE */ I = SIMPLE_DATA /* SIMPLE_DATA */ S = SUPPLEMENTARY_DATA /* SUPPLEMENTARY_DATA */ D = DATA_DESCRIPTION /* DATA_DESCRIPTION */ E = DATA_ENTITY /* DATA_ENTITY */ K = CATALOG_DATA /* CATALOGUE_DATA */ V = VOLUME_DATA /* VOLUME_DATA */ END_OBJECT MARKER_TYPE = JPL_ONLY /* or CCSD_ONLY */ WARNINGS = ON NOTE: The WARNINGS and MARKER_TYPE options can also be entered on the command line. If these options are present on both the command line and in the OPTIONS.DEF file, the options listed on the command line have precedence. The OPTIONS.DEF file is also used by the UNWRAP program and can contain other PVL statements. These other statements are ignored by the WRAP program. 7.2.1 VALID_CAIDS The VALID_CAIDS statement may be used to specify what Control Authority IDs. are valid for the SFDU being wrapped. This statement is optional. When an ADID statement in the MAP file is processed, the CAID specified is checked against the CAIDs specified in the VALID_CAIDs statement if it was used. By default, the CAID "CCSD" is recognized. Other CAIDs may be added by adding them in the set value of this statement, e.g., VALID_CAIDS = { NJPL, XJPL }. 7.2.2 LVO_NAMES The LVO_NAMES aggregation instructs WRAP to recognize the listed values as valid names for the respective LVO Class types. These names will be used when WRAP is reading the Map Language file to determine what should be placed in the SFDU. For instance, the aggregation statement to begin a Data Entity (E) Class LVO should read BEGIN_OBJECT = DATA_ENTITY If you wish to change the recognized name, the new LVO name can be entered in the OPTIONS.DEF file. The values in the listed table above are the default names. 7.2.3 MARKER_TYPE The MARKER_TYPE statement instructs WRAP which type of marker should be used when creating LVOs. A MARKER_TYPE value of JPL_ONLY will instruct WRAP to create JPL markers (CCSD3RE0...), while a value of CCSD_ONLY will instruct WRAP to create CCSDS standard markers (CCSD$$MARKER...). The default marker is the CCSDS standard marker. 7.2.4 WARNINGS The WARNINGS statement instructs WRAP whether or not to display warning messages during the WRAP process. The default is WARNINGS = ON The other value accepted for the WARNINGS statement is OFF. 7.3 WRAP Map Language File Macros Macros can be defined in the Map Language file (see Section 5 for information on macros). Macros provide a convenient way to create different SFDUs by changing a few values for each SFDU (i.e., file name, ADID, etc.) in the invoking macro statement. The macros contained in the file can be invoked in one of three ways: 1) the invoking statement is included in the MAP file, 2) the invoking statement is specified in the command line (see -s option), 3) the invoking statement is specified in a parameter file (see -p option). 8 UNWRAP UNWRAP is a command line utility which parses Standard Formatted Data Units (SFDUs) and writes the value data of each LVO to separate files. The written data do not include any SFDU labels or markers. The names of the created data files extracted from the SFDU are based on the original SFDU file name. UNWRAP can also be used to generate an SFDU Structure Map of an SFDU. A complete example of the UNWRAP application is shown in Appendix B. A usage summary of the UNWRAP utility follows: unwrap [-r] [-b ] [-k ] [-m ] [-w ] [-x ] [-d] [-f ] where [] is optional and <> is required. sfdufile is the name of the SFDU file to UNWRAP. 8.1 Options -r Do not resolve Replacement Class Objects By default, UNWRAP tries to resolve all Replacement Class Objects found in the SFDU file. This option allows you to skip Replacement Objects. -b basefilename Use basefilename for the output data files. The output data files generated by UNWRAP use part of the original SFDU file name as a base file name by default. This option may be used so that the name basefilename is used instead. Note that a number n is concatenated to each output base file name where n means it is the nth file generated with the same extension. -k marker_code By default, UNWRAP recognizes JPL standard markers (CCSD3RE000000 ...) as well as CCSDS standard markers (CCSD$$MARKER...) used to delimit LVOs. This option restricts valid markers to only one of the two types. The marker type recognized may be specified through a marker_code: j - only JPL standard markers recognized, c - only CCSDS standard markers recognized, b - allow both JPL and CCSDS standard markers (default). -m outmapfile Create an SFDU Structure Map file for the parsed SFDU and write it to outmapfile. A MAP file is not created by default. -w warningcode Turn on/off printing of warning messages. The warningcode may be: 1 - print warnings, 0 - do not print warnings. Warnings are non-fatal error messages generated by the UNWRAP program. -x optionsfile Use an options file optionsfile to specify execution options instead of through the command line. Other options not available through the command line also exist. See the following section for details. -d Do not generate "unwrapped" files This option causes UNWRAP to perform a parse without generating the output files for the extracted data. -f msg_file Direct error (and informational) output messages to the specified msg_file (instead of directing them to standard output = default). NOTE: The generated file names for the unwrapped SFDU data are based on the input SFDU file name on default operation. Therefore, the generated output files are written to the same directory that contains the input SFDU file (see the -b option). 8.2 OPTIONS.DEF File Some of the options listed in the OPTIONS section of the UNWRAP application can be specified in an options file. The options are specified using PVL statements. The options that can be placed in the options file are listed here with a summary following. A OPTIONS.DEF file is included in the software distribution with the default option values. VALID_CAIDS = { CCSD } OBJECT = FILE_EXTENSIONS Z = .SFD /* SFDU */ U = .IDU /* IDU */ F = .DDU /* DDU */ C = .ADM /* DATA_ADMINISTRATION */ R = .REF /* REFERENCE */ I = .DAT /* SIMPLE_DATA */ S = .SUP /* SUPPLEMENTARY_DATA */ D = .DES /* DATA_DESCRIPTION */ E = .ENT /* DATA_ENTITY */ K = .LBL /* CATALOGUE_DATA */ V = .VOL /* VOLUME_DATA */ END_OBJECT RESOLVE_R_CLASS = OFF MARKER_TYPE = JPL_ONLY WARNINGS = ON NOTE: The RESOLVE_R_CLASS, MARKER_TYPE, and WARNINGS options can also be entered on the command line. If these options are present on both the command line and in the OPTIONS.DEF file, the options listed on the command line have precedence. The OPTIONS.DEF file is also used by the WRAP program and can contain other PVL statements. These other statements are ignored by the UNWRAP program. 8.2.1 VALID_CAIDS The VALID_CAIDS statement may be used to specify what Control Authority IDs. should be considered valid while parsing an SFDU. This statement is optional. By default, the CAID "CCSD" is recognized. All other CAIDs found in an SFDU generate WARNINGs unless they are included in the VALID_CAIDs statement. CAIDs may be added in the statement by adding them in the statement's set value, i.e., VALID_CAIDS = { NJPL, XJPL }. 8.2.2 FILE_EXTENSIONS The FILE_EXTENSIONS aggregation instructs UNWRAP which file extensions to add on to the data files produced by UNWRAP. For instance, the statement K = .LBL would add the extension .LBL to any Catalog Object (K Class LVO) file written by the UNWRAP program. If you wish to change the extension, the new LVO name can be entered in the OPTIONS.DEF file. The values in the listed table below are the default extensions. LVO class Extension Z No file generated U No file generated F No file generated C .ADM R .REF I .DAT S .SUP D .DES E .ENT K .LBL V .VOL 8.2.3 RESOLVE REPLACEMENT (R) CLASSES The RESOLVE_R_CLASS statements instruct the UNWRAP program whether or not to resolve the Replacement Class Objects. The valid values are ON and OFF. If OFF is used the replacement classes are not processed, while the ON value would process those files listed in the REPLACEMENT object. 8.2.4 MARKER_TYPE The MARKER_TYPE statement instructs UNWRAP which type of markers should be recognized when unwrapping or parsing SFDUs. Any one of three MARKER_TYPE values can be used. The value of JPL_ONLY will instruct UNWRAP to recognize only JPL markers (CCSD3RE0...), while CCSD_ONLY will instruct UNWRAP to recognize only CCSDS standard markers (CCSD$$MARKER...). The final value of BOTH will instruct UNWRAP to recognize both types of marker patterns. Both the CCSDS standard and JPL marker pattern types are recognized by default. 8.2.5 WARNINGS The WARNINGS statement instructs UNWRAP whether or not to display warning messages during the UNWRAP process. The default is WARNINGS = ON The other value accepted for the WARNINGS statement is OFF. 9 EXTRACT EXTRACT is a command line utility which extracts data objects of specified class(es) from Standard Formatted Data Units (SFDUs) and writes the data objects either to standard output (default) or to one or several files. The written data does not include any SFDU labels or markers. A complete example of the EXTRACT application is shown in Appendix B. A usage summary of the EXTRACT utility follows: extract -c [ADID] [-c [ADID] ...] [-f ] [-o ] [-s] [-w ] where [] is optional and <> is required. sfdufile is the name of the SFDU file that specified class objects are extracted from. The available options are discussed below: 9.1 Options -c class[ADID] Extract all objects of the specified class (where class can be any of C, D, E, I, K, R, S, or V). If the (optional) ADID is given, extract all objects of the specified class with matching ADID. This option must be included at least once in the command line and may be repeated. -f msg_file Direct error and (informational) output messages to the specified msg_file (instead of directing them to standard error = default). -o file Write extracted object(s) to the specified (output) file (instead of directing them to standard output = default). -s Write extracted object(s) to a file with the same name as the SFDU (input) file, but with the extension .EXT. -w warningcode Turn on/off printing of warning messages. The warningcode may be: 1 - print warnings, 0 - do not print warnings. Warnings are non-fatal error messages generated by the EXTRACT program. 10 MACROGEN MACROGEN is a command line utility that can be used to create generic Map Language Macro files from specific Map Language files. The specific files are usually generated from the UNWRAP application using the -m option. These generated MAP files can only construct an SFDU exactly the same as the SFDU it was derived from. If a macro of the Map Language commands are generated, the macro can be used to generate the same SFDU with different parameters, e.g., different data files, ADIDs, delimitation, etc. MACROGEN allows some customizing of the MAP file by interactively prompting the user as to what items in the Map Language file should be parameterized. After all the parameters are specified, the user is prompted for an output file name where the new macro is written. A usage summary of the MACROGEN utility follows: macrogen where is Map Language file. NOTE: The file may not already contain Map Language Macros. APPENDIX A MAP LANGUAGE SPECIFICATION APPENDIX A - MAP LANGUAGE SPECIFICATION A-1 INTRODUCTION This is a specification of the Map Language that will be used by the SFDU Software Tool Kit. This Language will be used to WRAP (and possibly UNWRAP) SFDUs. The Map Language is implemented using the May 1992 CCSDS Parameter Value Language Specification Blue Book. The statements defined within this document should be able to be utilized by software adhering to the standards specified in this publication. A-2 CONVENTIONS The keywords and values that make up the Map Language try to adhere to the naming conventions adopted by the Planetary Science Data Dictionary. When reading the statements contained within this document, remember that all text displayed in upper case should be specified exactly as written. Any text displayed in lower case is to be interpreted as having different values that are to be substituted for the text. Also, note after each simple statement (non-aggregations) there is information regarding the scope (where) and use (when) of each statement. A-3 AGGREGATION DEFINITIONS Aggregations will be used to define Label Value Objects (LVOs). In other instances, aggregations can be used to define sets of statements that can take on different values for certain keywords. A-3.1 LVO Aggregation The definition of an LVO aggregation is as follows: BEGIN_OBJECT = lvo_type . . END_OBJECT = lvo_type Statements within the aggregation will determine delimitation, value, and other information for the LVO. The valid aggregation values for LVO objects are as follows: SFDU (Standard Formatted Data Unit) DDU (Description Data Unit) IDU (Information Data Unit) DATA_ADMINISTRATION REPLACEMENT_DATA APPLICATION_DATA SUPPLEMENTARY_DATA DATA_DESCRIPTION_RECORD DATA_ENTITY_DICTIONARY CATALOG_DATA VOLUME_DATA Note that these are values used by default. These values may be modified using an options file (see Section 7.1). A-3.2 SERVICE_DATA Aggregation The definition of a service aggregation is as follows: BEGIN_OBJECT = SERVICE_DATA . . END_OBJECT = SERVICE_DATA The SERVICE DATA aggregation will provide a means for entering data relating to SERVICE CLASS LVOs (Replacement Class Objects and Data Administration Objects). The information contained within this aggregation should conform to the rules specified in the May 1992 CCSDS SFDU -- Structure and Construction Rules Blue Book. Each LVO aggregation that defines a Service Class LVO must contain a Service Data aggregation. The primary purpose of this aggregation is to distinguish between statements that define the LVO aggregation (e.g., DELIMITATION and ADID) and the statements that are the actual data for the Service Class. A-3.3 Macro Aggregation The definition of a macro aggregation is as follows: BEGIN_OBJECT = MACRO MACRO_NAME = name MACRO_PARAMETERS = (parameter 1, parameter 2, ...) . . END_OBJECT = MACRO The macro aggregation will provide a means for repeating similar information to be contained within the same SFDU or different SFDUs. Any simple statements can be contained within a macro aggregation, however macro aggregations cannot be defined within other macro aggregations. The name of the macro is identified by the MACRO_NAME statement which must immediately follow the BEGIN_OBJECT = MACRO statement. The next statement that must appear is the MACRO_PARAMETERS statement which is a list of parameters. These parameters are substituted with actual values when the macro is invoked by a statement with name as the keyword and a list of its parameters as its value. EXAMPLE: BEGIN_OBJECT = MACRO MACRO_NAME = ZKI MACRO_PARAMETERS = (reference, data) . . END_OBJECT = MACRO The above macro would be invoked using statements such as ZKI = (PDSLABEL.LBL, VOYAGER.IMG) ZKI = (INFO.LBL, INFO.TXT) A more detailed example of construction and use of macros can be found in Section È. A-4 SIMPLE STATEMENTS A-4.1 ADID = adidname Scope: Within LVO aggregations Use: Optional for SFDU, DDU, IDU, DATA_ADMINISTRATION, and REPLACEMENT Class LVOs. Required for all other classes. The ADID or Authority Description ID is specified by an eight character restricted ASCII (RA) string. LVO aggregations should contain only one ADID statement. If more than one statement is found, the first one is used. The ADID should only be specified if the user wishes to use non-CCSDS standard LVOs, otherwise adidnames that are CCSDS standard are created automatically based on the LVO being defined. EXAMPLE: BEGIN_OBJECT = DATA_ADMINISTRATION ADID = NJPL1234 These statements would create an LVO with label NJPL3CS01234xxxxxxxx where as without the ADID statement the label would read CCSD3CS00004xxxxxxxx Remember that CCSD0004 is the default ADID for a DATA ADMINISTRATION LVO. A-4.2 DELIMITATION = (type, delimitation_parameter) Scope: Within LVO aggregations Use: Optional The DELIMITATION will specify the method that will be used to delimit an LVO. This keyword should appear only once within an aggregation that defines an LVO, although it may appear again within nested LVO aggregations. Valid values for type and delimitation parameter are as follows: (MARKER_PATTERN, 8 character RA marker pattern) (ASCII_LENGTH, NULL) or ASCII_LENGTH (BINARY_LENGTH, NULL) or BINARY_LENGTH (SHARED_EOF, NULL) or SHARED_EOF The ASCII_LENGTH, BINARY_LENGTH, and SHARED_EOF can be entered using the two methods listed above. The MARKER_PATTERN delimitation is the only type that requires a delimitation parameter, therefore needing the value expressed as a list of two items. If a list value is used for the other delimitation types, the parameter should be NULL. NOTE: Contiguous and Sequential End-Of-File markers will not be supported in this version of the Map Language. A-4.3 Data Administration Simple Statements The following are simple statements that can appear only within DATA ADMINISTRATION LVOs (C CLASS). A-4.3.1 ADIDNAME = adid Use: Required The adid is an eight character RA string that supplies the ADID under which the associated data description information is registered. This statement is required for aggregations that define DATA_ADMINISTRATION LVOs and can only be defined once within the aggregation. A-4.3.2 DEDID = adid Use: Optional The adid value is an eight character RA string that supplies an ADID of registered information which contains one or more Data Entity Dictionary data objects. This statement can occur more than once within the DATA ADMINISTRATION LVO. A-4.3.3 DDRID = adid Use: Optional The adid value is an eight character RA string that supplies an ADID of registered information which contains one or more Data Description Record data objects. This statement can occur more than once within the same DATA_ADMINISTRATION LVO. A-4.3.4 SUPID = adid Use: Optional The adid value is an eight character RA string that supplies an ADID of registered information which contains one or more Supplementary Information Data objects. This statement can occur more than once within the same DATA_ADMINISTRATION LVO. A-4.4 Replacement Class Simple Statements The following are simple statements that can appear only within REPLACEMENT DATA LVOs (R CLASS). These statements provide the user a method to specify R Classes explicitly rather than use the REFERENCE_DATA_FILE statement that causes R Classes to be generated implicitly. These statements are the same statements specified in Section 5.2 (Specification for ADID = CCSD0003) of the May 1992 CCSDS SFDU -- STRUCTURE AND CONSTRUCTION RULES BLUE BOOK. Review the BLUE BOOK for more details on these statements. A-4.4.1 REFERENCETYPE = (attrib_1, attrib_2,..., attrib_n) Scope: 1st statement in REPLACEMENT aggregation Use: Required For each REPLACEMENT Class LVO there must be one, and only one, REFERENCETYPE statement and this statement must be first. The attrib_1 identifies the referencing environment, e.g., $CCSDS1, $CCSDS2, etc. The remaining attributes will specify values for any additional parameters which are required to complete the definition of the referencing environment. A-4.4.2 LABEL = label Scope: 2nd statement in REPLACEMENT aggregation Use: Required The LABEL = label statement can appear any number of times within the REPLACEMENT Class aggregation definition, but it must appear at least once immediately following the REFERENCETYPE statement. There can be two different values for the LABEL = label statement. First, the label value can be a 20 character RA string that conforms to the definition of an SFDU label. The only other value that the label can have is ATTACHED, which indicates the label definition is attached to the file to be specified in a REFERENCE statement. A-4.4.3 REFERENCE = pathname Scope: Within LVO aggregations Use: Optional The REFERENCE = pathname statement specifies the location of the data file to be included in the SFDU. The pathname must be specified exactly as shown in Section A-4.5. There can be any number of these statements within the definition of a REPLACEMENT CLASS LVO. NOTE: Any files specified by the REFERENCE statement in the R Class will not be verified for correctness. It is the responsibility of the user to ensure any LVOs contained in the files are correct. A-4.5 INCLUDE_DATA_FILE = pathname Scope: Within non-structure LVO aggregations Use: Optional The INCLUDE_DATA_FILE statement will be used to specify the location of a file containing data to be inserted into an LVO. The data will be physically included in the SFDU file. The INCLUDE_DATA_FILE statement assumes that there is just data contained in the file. Currently there is no support for wildcards in the directory portion of the filename. However, wildcards will be supported for the file portion of the pathname. The wildcard specification will cause LVOs to be generated for each filename that the pathname expands to. WILDCARD EXAMPLES: \MAGELLAN\DATA\*.DAT is correct, \MAGELLAN\*\*.DAT is incorrect. A-4.6 PRE_DATA_DELIMITER = (val_1, val_2, ..., val_n) Scope: Within non-structure LVO aggregations Use: Optional The PRE_DATA_DELIMITER will be used to specify a set of characters to be placed between the LVO label and its value. The value of val_n can be one of the following: SPACE for blank space, CR for carriage return, LF for linefeed, SEMICOLON for the semicolon character. There can be any number of these characters contained in the value list of this MAP statement. There can only be one PRE_DATA_DELIMITER statement per non-structure class LVO. The PRE_DATA_DELIMITER statement affects all INCLUDE_DATA_FILE statements listed after it. A-4.7 PAD_NEXT_LVO_VALUE = (record_length, char) Scope: Within non-structure LVO aggregations Use: Optional The PAD_NEXT_LVO_VALUE is used to force the value field of the next LVO to begin on a multiple of the record length. The previous value is padded with enough char characters so as to leave enough space for the LABEL of the next LVO. The LABEL will be the last bytes written in the previous record and the value will be the first bytes written in the next record. The record_length is an integer number, while the char value is any printable ASCII character that can be contained in quotes. The word NULL can be substituted if the NULL character is desired. There can only be one PAD_NEXT_LVO_VALUE statement per non- structure LVO. The PAD_NEXT_LVO statement affects all INCLUDE_DATA_FILE statements listed after it. A-4.8 REFERENCE_DATA_FILE = pathname Scope: Within non-structure LVO aggregations Use: Optional The REFERENCE_DATA_FILE will be used to specify the location of a file containing data to be placed into a REPLACEMENT (R) Class LVO. This statement assumes that there is just data contained in the file, therefore no checking is done on the data itself. This REFERENCE_DATA_FILE statement will cause a REPLACEMENT_CLASS LVO to be generated into the SFDU structure with a LABEL = label statement. Note that the value of the LABEL statement will depend on statements that must directly precede the REFERENCE_DATA_FILE statement. For example, the statements: BEGIN_OBJECT = SIMPLE_DATA ADID = SMPLDATA DELIMITATION = (MARKER, END_DATA) REFERENCE_DATA_FILE = DATAFILE.DAT would generate this label: LABEL: SMPL3IS0DATAEND_DATA |SMPL| |3| |I| |S| |0| |DATA| |END_DATA| |----| |-| |-| |-| |-| |----| |--------| | | | | | | | | | | | | | | | | | | | | | | | | | | | |Delimitation Parameter | | | | | | | | | | | |Data Description ID | | | | | | | | | |Spare byte 2: NOT USED | | | | | | | |Delimitation: MARKER | | | | | |Data Class: SIMPLE_DATA | | | |Version: 3 | |Control Authority ID As with the INCLUDE_DATA_FILE statement, there is no support for wildcards in the directory portion of the pathname. Wildcard support is provided for the filename. Review Section 5.2 (Specification for ADID = CCSD003) of the May 1992 CCSDS SFDU -- STRUCTURE AND CONSTRUCTION RULES BLUE BOOK for more information on Replacement Class LVOs. A-4.9 MACRO_NAME = name Scope: Within macro aggregations. Use: Required The MACRO_NAME keyword will be used to identify the names of macro aggregations. The macro is invoked when the value of the MACRO_NAME appears as a keyword further in the PVL specification (see Section A-5). The value of the keyword should be a parameter list of values that should be substituted in for the list of values contained in the MACRO_PARAMETERS statement defined within the macro aggregation. A-4.10 MACRO_PARAMETERS = (list) Scope: 2nd statement within macro aggregations Use: Required The MACRO_PARAMETERS keyword is a list of values to be used to replace the parameters that are specified within an aggregation object defined as a macro. If there are no parameters to be substituted for the macro, the statement should read: MACRO_PARAMETERS = () A-5 MACRO EXAMPLES A-5.1 ZKI Macro A continuation of the example from the macro aggregation definition in Section A-3.2 is given below. BEGIN_OBJECT = MACRO MACRO_NAME = ZKI MACRO_PARAMETERS = (catdata, data) BEGIN_OBJECT = SFDU DELIMITATION = (SHARED_EOF, NULL) BEGIN_OBJECT = CATALOG_DATA ADID = NJPLPDS2 DELIMITATION = (MARKER, MRKODL01) INCLUDE_DATA_FILE = catdata END_OBJECT = CATALOG_DATA BEGIN_OBJECT = DATA_ENTITY ADID = NJPLDATA DELIMITATION = (ASCII_LENGTH, NULL) INCLUDE_DATA_FILE = data END_OBJECT = DATA_ENTITY END_OBJECT = SFDU END_OBJECT = MACRO The above macro can be invoked with one of the following statements: ZKI = (VOYAGER.LBL, VOYAGER.IMG), ZKI = (MAGELLAN.LBL, MAGELLAN.TXT). The CATALOG_DATA LVO data in this macro will always be delimited with the MRKODL01 marker, while the DATA_ENTITY LVO will be delimited by ASCII_LENGTH. Note that the parameter in the ASCII_LENGTH delimitation statement is NULL. This is because the length will be determined once the INCLUDE_DATA_FILE is read. Also note that since the SFDU LVO aggregation has no ADID statement, the default ADID of CCSD0001 will be used to construct the LVO label. A-5.2 Description Data Macro The following is an example of a Data Administration macro: BEGIN_OBJECT = MACRO MACRO_NAME = DESCRIPTION_DATA MACRO_PARAMETERS = (adidname, pattern, data_descript_id, filename) BEGIN_OBJECT = DESCRIPTION_DATA_UNIT BEGIN_OBJECT = DATA_ADMINISTRATION DELIMITATION = (MARKER, pattern) BEGIN_OBJECT = SERVICE_DATA ADIDNAME = adidname END_OBJECT = SERVICE_DATA END_OBJECT = DATA_ADMINISTRATION BEGIN_OBJECT = DATA_DESCRIPTION_OBJECT ADID = data_descript_id REFERENCE_DATA_FILE = filename END_OBJECT = DATA_DESCRIPTION_OBJECT END_OBJECT = DATA_DESCRIPTION_UNIT END_OBJECT = MACRO This macro can be invoked by statements such as: DESCRIPTION_DATA = (NSSD0041, MRKADI41, CCSD0002, FITSFORM.TXT), DESCRIPTION_DATA = (NSSD0042, MRKADI42, CCSD0002, HDRFORM.TXT). The LVOs for this macro that will use the CCSDS-defined ADID values are the DESCRIPTION_DATA_UNIT LVO (CCSD0005) and the DATA_ADMINISTRATION LVO (CCSD0004). The ADID for the DATA DESCRIPTION object is determined from the invocation statement. The REFERENCE_DATA_FILE statement in the DATA_DESCRIPTION_OBJECT LVO will cause the data in the filename to be included in the SFDU as a REPLACEMENT (R) Class LVO. APPENDIX B WRAP, UNWRAP, and EXTRACT EXAMPLES APPENDIX B - WRAP, UNWRAP, and EXTRACT EXAMPLES This appendix is intended to be a quick example on how to WRAP, UNWRAP, and EXTRACT an SFDU. The section does not provide information on what to put into an SFDU, rather it gives the user the steps needed (how) to create an SFDU. B-1 Create the MAP File Create a MAP file of the SFDU to be created. The MAP file can be generated with the help of an editor. The following is the contents of the MAP file from our examples in Section 5. This example could be created by the user: BEGIN_OBJECT = SFDU DELIMITATION = (SHARED_EOF, NULL) BEGIN_OBJECT = CATALOGUE_DATA ADID = CCSDL015 DELIMITATION = (ASCII_LENGTH, NULL) INCLUDE_DATA_FILE = VOYAGER.LBL END_OBJECT = CATALOGUE_DATA BEGIN_OBJECT = SIMPLE_DATA DELIMITATION = (MARKER, END_DATA) ADID = CCSDIDAT INCLUDE_DATA_FILE = VOYAGER.DAT END_OBJECT = SIMPLE_DATA END_OBJECT = SFDU The MAP file can also be generated from an existing SFDU (if we wanted to use an existing structure) by using the following UNWRAP command on the command line: UNWRAP -d -m mapfile filename where filename is the name of the file containing the SFDU and mapfile is the name of the file where the newly created MAP will be stored. The -d option prevents the unwrapped LVO files (Data Objects) from being generated into separate files (we only want the MAP). B-2 Verify the MAP File Verify the correctness of the MAP file by using the PVL verifier. From the command line: PVL mapfile where mapfile is the name of the file containing the Map Language specification of the SFDU (the MAP is specified using PVL). Correct any reported errors by the PVL Verifier and run again. When there are no errors in the MAP file, the output from the PVL verifier should be displayed as follows: PVL: --> PVL VERIFIER, version 1.0 91/05/24 ----------------------------------------------------------- Processing file : mapfile There were no parsing errors found. B-3 WRAP the SFDU Run the WRAP application program from the command line using the following syntax: WRAP -m mapfile -o sfdufile where mapfile is the name of the file containing the Map Language specification of the SFDU and sfdufile is the file that will contain the generated SFDU. The output of the WRAP program will be displayed as follows: Standard Formatted Data Unit (SFDU) S/W Tool Kit WRAP Version 1.2 PROCESSING MAP FILE: sample.map Processing BEGIN_OBJECT = SFDU Processing DELIMITATION = SHARED_EOF Processing BEGIN_OBJECT = CATALOGUE_DATA Processing ADID = NJPLPDSX Processing DELIMITATION = (MARKER, $$INFO$$) Processing INCLUDE_DATA_FILE = sfdufil1.LBL Processing BEGIN_OBJECT = SIMPLE_DATA Processing ADID = NJPL0043 Processing DELIMITATION = SHARED_EOF Processing INCLUDE_DATA_FILE = sfdufil1.DAT --- Finished Processing --- CREATING SFDU: sfdufile Writing LVO for label (CCSD3ZF0000100000001) Writing LVO for label (NJPL3KS0PDSX$$INFO$$) Writing LVO for label (NJPL3IF0004300000001) --- Finished SFDU --- B-4 UNWRAP the SFDU Run the UNWRAP application program from the command line using the following syntax: UNWRAP sfdufile where sfdufile is the name of the file that contains the SFDU. The UNWRAP program will generate the following files that contain the data unwrapped from the SFDU. The output of the UNWRAP program will be displayed as follows: Standard Formatted Data Unit (SFDU) S/W Tool Kit UNWRAP version 1.2 Parsing SFDU: ar10010b.t 1 Parsing SFDU (Z) object (CCSD0001).... 2 Parsed CATALOGUE_DATA (K) object (NJPLPDSX) 2 Parsed APPLICATION_DATA (I) object (NJPL0043) LVO summary for SFDU: ar10010b.t Object Type Authority Delimiter Delimiter Value Object Description Method Parameter Size ID ID (bytes) SFDU CCSD0001 SHARED_EOF 00000001 23818 Z CATALOGUE_DATA NJPLPDSX MARKER $$INFO$$ 336 K APPLICATION_DATA NJPL0043 SHARED_EOF 00000001 23422 I UNWRAPPED OBJECTS: OBJECT (LABEL ) OUTPUT FILE ________________________________________________________ CATALOGUE_DATA (NJPL3KS0PDSX$$INFO$$) ar100101.LBL APPLICATION_DATA (NJPL3IF0004300000001) ar100101.DAT B-5 EXTRACT Objects from the SFDU Run the EXTRACT application program from the command line using the following syntax: EXTRACT -c K sfdufile where sfdufile is the name of the file that contains the SFDU. The output of the EXTRACT program will be displayed as follows: Standard Formatted Data Unit (SFDU) S/W Tool Kit EXTRACT version 1.2 1 Parsing SFDU object (CCSD0001).... 2 Parsed CATALOGUE_DATA (K) object (CCSDL015) 2 Parsed SIMPLE_DATA (I) object (CCSDIDAT) ...... Remember, this example was intended to be simple. It does not contain all of the features of the Tool Kit (e.g., the macro facility of the Map Language), however it gives the user just enough information to WRAP, UNWRAP, and EXTRACT an SFDU.