![](media/image1.wmf){width="4.388888888888889in"
height="1.2083333333333333in"}

**DRAFT REPORT CONCERNING SPACE**

**DATA SYSTEM STANDARDS**

+-----------------------------------------------------------------------+
| **PARAMETER VALUE\                                                    |
| LANGUAGE---**                                                         |
|                                                                       |
| **A TUTORIAL**                                                        |
+-----------------------------------------------------------------------+

**CCSDS 641.0-G-2**

**GREEN BOOK**

June 2000

![](media/image2.wmf){width="4.111111111111111in"
height="1.9305555555555556in"}

# Authority

  ---- -------------------- ------------------------------------------ ----
                                                                       

       Issue                Green Book, Issue 2                        

       Date:                June 2000                                  

       Location:            Toulouse, France                           

                                                                       
  ---- -------------------- ------------------------------------------ ----

This document has been approved for publication by the Management
Council of the Consultative Committee for Space Data Systems (CCSDS) and
reflects the consensus of technical panel experts from CCSDS Member
Agencies. The procedure for review and authorization of CCSDS Reports is
detailed in the *Procedures Manual for the Consultative Committee for
Space Data Systems* (reference \[**1**\]).

This document is published and maintained by:

> CCSDS Secretariat
>
> Program Integration Division (Code MT)
>
> National Aeronautics and Space Administration
>
> Washington, DC 20546, USA

# FOREWORD

This Report is a tutorial on the use of the Parameter Value Language
(PVL). PVL provides a human-readable, machine-processable language for
naming and expressing data values. This report would be of interest to
those working with applications where a keyword-value language is
desired.

Through the process of normal evolution, it is expected that expansion,
deletion, or modification of this document may occur. This Report is
therefore subject to CCSDS document management and change control
procedures. Current versions of CCSDS documents are maintained at the
CCSDS Web site:

http://www.ccsds.org/ccsds/

Questions relating to the contents or status of this document should be
addressed to the CCSDS Secretariat at the address indicated on page i.

At time of publication, the active Member and Observer Agencies of the
CCSDS were

[Member Agencies]{.underline}

> -- Agenzia Spaziale Italiana (ASI)/Italy.
>
> -- British National Space Centre (BNSC)/United Kingdom.
>
> -- Canadian Space Agency (CSA)/Canada.
>
> -- Centre National d\'Etudes Spatiales (CNES)/France.
>
> -- Deutsche Forschungsanstalt für Luft- und Raumfahrt e.V.
> (DLR)/Germany.
>
> -- European Space Agency (ESA)/Europe.
>
> -- Instituto Nacional de Pesquisas Espaciais (INPE)/Brazil.
>
> -- National Aeronautics and Space Administration (NASA)/USA.
>
> -- National Space Development Agency of Japan (NASDA)/Japan.
>
> -- Russian Space Agency (RSA)/Russian Federation.

[Observer Agencies]{.underline}

> -- Austrian Space Agency (ASA)/Austria.
>
> -- Central Research Institute of Machine Building (TsNIIMash)/Russian
> Federation.
>
> -- Centro Tecnico Aeroespacial (CTA)/Brazil.
>
> -- Chinese Academy of Space Technology (CAST)/China.
>
> -- Commonwealth Scientific and Industrial Research Organization
> (CSIRO)/Australia.
>
> -- Communications Research Laboratory (CRL)/Japan.
>
> -- Danish Space Research Institute (DSRI)/Denmark.
>
> -- European Organization for the Exploitation of Meteorological
> Satellites (EUMETSAT)/Europe.
>
> -- European Telecommunications Satellite Organization
> (EUTELSAT)/Europe.
>
> -- Federal Service of Scientific, Technical & Cultural Affairs
> (FSST&CA)/Belgium.
>
> -- Hellenic National Space Committee (HNSC)/Greece.
>
> -- Indian Space Research Organization (ISRO)/India.
>
> -- Industry Canada/Communications Research Centre (CRC)/Canada.
>
> -- Institute of Space and Astronautical Science (ISAS)/Japan.
>
> -- Institute of Space Research (IKI)/Russian Federation.
>
> -- KFKI Research Institute for Particle & Nuclear Physics
> (KFKI)/Hungary.
>
> -- MIKOMTEK: CSIR (CSIR)/Republic of South Africa.
>
> -- Korea Aerospace Research Institute (KARI)/Korea.
>
> -- Ministry of Communications (MOC)/Israel.
>
> -- National Oceanic & Atmospheric Administration (NOAA)/USA.
>
> -- National Space Program Office (NSPO)/Taipei.
>
> -- Swedish Space Corporation (SSC)/Sweden.
>
> -- United States Geological Survey (USGS)/USA.

# DOCUMENT CONTROL

+-----------------+------------------------+--------+-----------------+
| **Document**    | **Title**              | **     | **S             |
|                 |                        | Date** | tatus/Remarks** |
+-----------------+------------------------+--------+-----------------+
| CCSDS 641.0-G-2 | Report Concerning      | June   | Issue 2         |
|                 | Space Data System      | 2000   |                 |
|                 | Standards: Parameter   |        | Updated to      |
|                 | Value Language \-- A   |        | reflect updated |
|                 | Tutorial, Green Book,  |        | PVL             |
|                 | Issue 2                |        | specification,  |
|                 |                        |        | which included  |
|                 |                        |        | the extended    |
|                 |                        |        | character set   |
|                 |                        |        | version. No     |
|                 |                        |        | change bars     |
|                 |                        |        | have been used  |
|                 |                        |        | since numerous  |
|                 |                        |        | changes have    |
|                 |                        |        | been made       |
|                 |                        |        | throughout the  |
|                 |                        |        | document.       |
+-----------------+------------------------+--------+-----------------+
| CCSDS 641.0-G-1 | Report Concerning      | May    | Issue 1         |
|                 | Space Data System      | 1992   | supersedes      |
|                 | Standards: Parameter   |        | portions of     |
|                 | Value Language \-- A   |        | CCSDS 620.0-G-1 |
|                 | Tutorial, Green Book,  |        |                 |
|                 | Issue 1                |        |                 |
+-----------------+------------------------+--------+-----------------+
|                 |                        |        |                 |
+-----------------+------------------------+--------+-----------------+
|                 |                        |        |                 |
+-----------------+------------------------+--------+-----------------+

# CONTENTS

Section Page

1 INTRODUCTION 1-1

1.1 Purpose and Scope 1-1

1.2 context 1-1

1.3 How to Use This Document 1-2

1.4 REFERENCES 1-2

2 ILLUSTRATING PVL USAGE 2-1

2.1 PVL Usage in Data Interchange 2-3

2.1.1 Identifying Objects 2-3

2.1.2 Use of PVL in Application Data Objects 2-4

2.1.3 Data Description Information 2-5

3 FORMING PVL STATEMENTS 3-1

3.1 Character Sets 3-1

3.2 Comment 3-2

3.3 Assignment Statement 3-3

3.3.1 Parameter Name 3-3

3.3.2 Value 3-4

3.4 Aggregation Block 3-11

3.5 End Statement 3-13

4 RECOMMENDED PRACTICES AND USAGE LIMITATIONS 4-1

4.1 Data Entity Dictionary Usage 4-1

4.2 Human Readability Practices 4-1

4.2.1 statement separation 4-1

4.2.2 aggregation block readability 4-2

4.2.3 Use of Meaningful Parameter AND BLOCK Names 4-3

4.2.4 Use of Comments 4-3

4.2.5 Use of NON-BREAKING SPACE CHARACTERS 4-4

4.3 Application Conventions 4-4

4.3.1 Parameter Name Conventions 4-4

4.3.2 Use of Group and Object Aggregation Types 4-4

4.3.3 Definition of a Null Value 4-5

4.3.4 Use of End Statement 4-5

4.4 Transfers of PVL Statements 4-5

4.4.1 Line Format Differences 4-6

4.4.2 End of Line Deletion 4-7

4.4.3 Addition of Spurious New Line 4-7

4.4.4 Character Representation Conversions 4-7

4.4.5 Blank Trimming 4-8

4.4.6 Tab Conversion 4-8

4.5 Limitations 4-8

4.5.1 Use of Embedded Quotes 4-8

4.5.2 Indexed Values 4-8

4.5.3 NonDecimal Numerics 4-9

5 REQUIREMENTS AND THEIR RATIONALES 5-1

5.1 High Level Requirements 5-1

5.2 Specific Requirements 5-1

ANNEX A ACRONYMS AND GLOSSARY A-1

ANNEX B PVL PARSER IMPLEMENTATION ADVICE B-1

INDEX I-1

Figure

2-1 Examples of PVL Statements 2-3

2-2 Identifying Information using PVL 2-4

2-3 Example of Application Data 2-5

2-4 Data Description Information Using PVL 2-6

2-5 Data Dictionary Information Using PVL 2-7

3-1 Examples of Decimal Numerics 3-5

3-2 Examples of Nondecimal Integers 3-6

3-3 Examples of Quoted Strings in PVL 3-7

3-4 Examples of Unquoted Strings 3-8

3-6 Examples of Sequences 3-9

3-7 Examples of Date/Time Values 3-10

3-8 Examples of Units Expressions 3-11

3-10 Example of an END Statement 3-13

4-1 Aggregation Style Example 4-3

4-2 End of Line Transfer Example 4-6

B-1 Language Translator Components B-2

B-2 Conceptual Model of a Data Structure for a List with Units B-5

# INTRODUCTION

## Purpose and Scope

This document describes a keyword-value language, the Parameter Value
Language (PVL); it provides a description of how and why one would use
this language to interchange information. This document provides the
rationale for the development of PVL, its intended usage, its format and
construc­tion rules as well as suggested practices and cautions.

Most users will be able to use the language after reading this document.
Those individuals who are responsible for implementing software
associated with the language, or who need more detailed information
should also consult the *Parameter Value Language Specification
(CCSD0006 and CCSD0008)* (reference \[\[2\]\]) which contains the formal
specification for the language. Both the basic version (CCSD0006) and
the extended character set version (CCSD0008) of PVL are specified in
that document; both versions are discussed in this document.

## context

The need to name values so that they may be referenced later is widely
known. Keyword-value notations are one of the most straightforward ways
of achieving this goal. For this reason, a number of keyword-value
notations have been developed over the years. Because each of these
notations was developed to address a specific need, the actual formats
of these notations are different. Because these forms seemed intuitive,
and are often \"parsed\" by human users, little thought had been given
to developing a formal standard intended for general usage.

Panel 2 of the Consultative Committee for Space Data Systems (CCSDS) is
involved with information interchange issues. As part of this work, the
CCSDS has developed the Standard Formatted Data Unit (SFDU) concept to
improve the automation of information interchange between and among
different environments. During the development of this concept, it
became clear that the capabilities of a keyword-value notation would be
very valuable. It also became clear that since SFDUs would be
transferred between heterogeneous systems that a simple yet robust
notation should be specified.

PVL was developed with these goals in mind. It is a simple, flexible
notation that is minimally impacted by typical data transfer mechanisms
used between heterogeneous systems. To this end, the basic version of
PVL (CCSD0006) is expressed in American Standard Code for Information
Interchange (ASCII) codes (reference \[7\]). The extended character set
version of PVL (CCSD0008) extends the basic version by the addition of
the G1 character set of ISO 8859-1 (reference \[4\]\]).

The development of PVL is built on previous keyword languages, such as
Flexible Image Transport System (FITS) (reference \[\[9\]) and Object
Description Language (ODL) (reference \[10\]). Much of the syntax of PVL
is based on ODL, developed for the Planetary Data System at the Jet
Propulsion Laboratory (JPL). PVL minimizes the semantics of the language
to provide implementers with the ability to specify the appropriate
semantics for their applications. PVL provides syntax and limited
semantics. Used in conjunction with a Data Entity Dictionary (DED), it
gives users all the capabilities they need in applications that require
keyword-value languages.

## How to Use This Document

This document is intended to assist general users in deciding whether
PVL is appropriate for their information interchange needs, and if so to
provide sufficient information for its effective use.

It is also intended to be an introduction to the formal specification of
PVL (reference \[\[2\]\]). This document consists of the following five
sections and annexes:

Section 1 - **Introduction** (this section), which provides a brief
background for the development of PVL

Section 2 - **Illustrating PVL Usage**, which provides information and
examples about how PVL is used, with emphasis on the SFDU environment. A
science scenario is used to provide a context for the examples.

Section 3 - **Forming PVL Statements,** which illustrates how PVL
statements are formed and gives exam­ples of various types of
information.

Section 4 - **Suggested Practices and Limitations,** which identifies
usage that may cause difficulties and suggests conven­tions which address
these concerns.

Section 5 - **Requirements and Rationale**, which contains the list of
language requirements on which PVL is based

Annex A - **Acronyms and Glossary,** which contains a list of the
acronyms and glossary of terms used in this document

Annex B - **Parser Implementation Advice,** which contains a set of
suggestions about the implementation of software providing PVL
capabilities

## REFERENCES

\[**1**\] *Procedures Manual for the Consultative Committee for Space
Data Systems*. CCSDS A00.0-Y-7. Yellow Book. Issue 7. Washington, D.C.:
CCSDS, November 1996 or later issue.

\[2\] *Parameter Value Language Specification (CCSD0006 and CCSD0008),*
Recommendation for Space Data System Standards, CCSDS 641.0-B-2. Blue
Book. Issue 2. Washington, D.C.: CCSDS, May 2000.

\[3\] *Information Processing---ISO 7-Bit Character Set for Information
Interchange.* International Standard, ISO 646:1991. Geneva: ISO, 1987.

\[4\] *Information Processing---8-bit Single-Byte Coded Graphic
Character Set - Part 1: Latin Alphabet No. 1.* International Standard,
ISO 8859-1:1987. Geneva: ISO, 1987. \[Note: ISO DIS 8859-1:1997 is
available\]

\[5\] *Standard Formatted Data Units---Structure and Construction
Rules*. Recommendation for Space Data System Standards, CCSDS 620.0-B-2.
Blue Book. Issue 2. Washington, D.C.: CCSDS, May 1992. (with Technical
Corrigendum 1 applied)

\[6\] *Standard Formatted Data Units---A Tutorial*. Report Concerning
Space Data System Standards, CCSDS 621.0-G-1. Green Book. Issue 1.
Washington, D.C.: CCSDS, May 1992.

\[7\] *Information Processing---Representation of Numerical Values in
Character Strings for Information Interchange*. International Standard,
ISO 6093-1985(E). Geneva: ISO, 1985.

\[8\] *Time Code Formats*. Recommendation for Space Data Systems
Standards, CCSDS 301.0-B-2. Blue Book. Issue 2. Washington, D.C.: CCSDS,
April 1990.

\[9\] D. C. Wells, E. W. Greisen, and R. H. Harten. \"FITS: A Flexible
Image Transport System,\" *Astron. Astrophys. Suppl*. No. 44. 1981,
363‑370.

\[10\] R. L. Davis. *Specification for the Object Description Language*.
Version 1.0. Boulder, Colorado : U of Colorado Press, 1990

\[11\] S. C. Johnson. \"Yacc: Yet Another Compiler-Compiler.\" Computing
Science Technical Report No. 32. Murray Hill, N.J.: Bell Laboratories,
1975.

\[12\] M. E. Lesk and E. Schmidt. \"Lex*---*A Lexical Analyzer
Generator.\" Computing Science Technical Report No. 39. Murray Hill,
N.J.: Bell Laboratories, 1976.

# ILLUSTRATING PVL USAGE

This section gives examples of possible uses of PVL in information
interchange. It does so within the context of a scenario demonstrating
how a science project could use the capabilities of PVL. Within the data
interchange environment, PVL may be used to support a number of common
data types. It may also be used in conjunction with specific data
dictionaries to form a data description for a data object. CCSDS has
defined the Data Entity Dictionary Specification Language (DEDSL) as a
means of defining data dictionaries.

There are several classes of objects that will be used in these
examples, each containing a specific type of information:

-- identification objects, which contain catalogue attribute informa­tion
about an accompanying object;

-- application data objects, which contain primary interest data or
supplementary data;

-- data description objects, which contain the descriptive information
used to interpret the contents of another object.

The scenario presented in the following subsections explains how PVL can
be used with each of these classes of objects. It is based on an
international, multi-year, multi-mission, multi-agency science program.
This international program will collect a large amount of data that will
need to be managed and distributed over a long period of time.

In order to manage and distribute the large amounts of associated data
with this program, the program has chosen to use the capabilities of the
CCSDS Standard Formatted Data Unit (references \[5\]and \[6\]). Within
its usage of SFDUs, the program will also utilize many of the
capabilities of PVL. These capabilities include, but are not limited,
to:

-- the ability to define identifying information about the data
collected;

-- the ability to provide descriptions of the format of the data:

-- the ability to define a data entity dictionary, which defines all the
parameters used in the project that appear within its data objects.

In order to see how PVL would be used in each of the examples in the
scenario, a very brief overview of the language format will be provided.
All PVL statements are expressed in the basic version of PVL (CCSD0006)
that uses ASCII codes. There are two basic constructs that provide the
basis of PVL statement formation. They are the assignment statement and
the aggregation block. There is also an optional end statement.

An assignment statement has the following general form:

Parameter = Value\[;\]

where the brackets indicate that the semicolon is optional.

PVL also permits naming collections of statements in the aggregation
block construct, which has the following general form:

Begin Aggregation = Block Name\[;\]

\...

A collection of assignment statements and/or aggregation blocks

\...

End Aggregation \[ = Block Name\]\[;\]

where the brackets indicate that the block name and the semicolons are
optional.

In addition, PVL allows the inclusion of comments. Comments begin with a
forward slash-asterisk (/\*) sequence, which is followed by the text of
the comment. The comment is ended with an asterisk-forward slash (\*/)
sequence. A full description of PVL constructs and their formation is
contained in section 3, as well as in reference \[2\].

Figure 2-1 illustrates the two major PVL constructs as well as the use
of comments. Following line by line in the figure, the first line is a
comment that identifies what follows as sample PVL statements. The next
line is an assignment statement; it associates the parameter name
Document with the value \"PVL Tutorial.\" The next series of statements
(starting with the parameter BEGIN_GROUP) is an example of an
aggregation block that associates the block name UserProfile with the
next four assignment statements. The END_GROUP statement closes the
aggregation block. In the figure, some of the values are quoted and some
are not, although all contain character information. These values are
all known as strings and the rules for whether they are quoted are
discussed in 3.3.2.2. This example illustrates that strings that contain
spaces must appear in quotation marks. Note however that the
Non-Breaking Space character available in the extended character set
version of PVL (CCSD0008) is not considered to be a space character.
Also note that each statement ends with a semicolon. An alternative
statement termination is white space. For consistency, the preferred
form with the semicolon is used for all examples in this tutorial.
Statement delimitation is discussed in section 3 and 0.

Figure 2-1: Examples of PVL Statements

## PVL Usage in Data Interchange

This section illustrates how PVL might be used to interchange several
different types of information in a science program such as the scenario
described. The examples given are intended to be representative, not to
provide full specification of an object. For a given project, each of
the three types of objects discussed earlier (identifying objects,
application data objects and data description objects) would be fairly
common.

### Identifying Objects

Data sets may contain objects that provide identifying information about
other data. Identifying objects, which might contain information used
for cataloging, are often useful in helping users verify that they have
the correct set of data. In our science program scenario, decommutated
instrument data and summarized key parameter data files are available
for distribution from the central data handling facility for a period of
time before they are shipped to a permanent archive. There is a catalog
that describes which data sets are available. This catalog is
implemented by maintaining a database of identifying attributes such as
spacecraft name, time span, instrument, file type, file name, etc.

These same catalog attributes are also contained within an identifying
object that is included in the distribution of the application data
object (i.e., the decommutated instrument data and the key parameters).
In our scenario, a PVL-based description for the identifying object is
used, since this information needs to be both machine-processable and
easily readable by humans. A portion of an identifying object,
associated with a key parameter file, is illustrated in figure 2-2.

In this example, the data is from the PIXIE experiment from the POLAR
mission. The starting time is 1:00 a.m. December 24, 1995. The file type
is KPGS, and the file name (identified by the parameter INPUT_FILE) is
XXXXXND555.W3. The formation rules for the parameter values are found in
an associated project data entity dictionary. Data entity dictionaries
contain at a minimum a list of data entity names with their semantic
meaning; they may also include information necessary for the validation
of values. The time is expressed in the PVL date/time format. The data
entity dictionary also contains the formation rules for the parameter
INPUT_FILE, which includes some encoded information about the file
origin that is incorporated into the name. The data entity dictionary
would specify that SPACECRAFT_ID has a previously designated set of
legitimate values, of which POLAR is one. Similarly, the DED would list
KPGS among the valid values for FILE_TYPE.

The use of an explicit DED with PVL is encouraged even when meanings of
the parameter names seem obvious, since what is obvious at one period of
time may not be as obvious at another. It is also not possible to tell,
without the use of a DED, whether a value must be from a designated set
of values or otherwise.

The use of PVL to specify a DED is discussed in 2.1.3.2.

### Use of PVL in Application Data Objects

In our scenario, there are two basic types of application data. One type
contains the data of primary interest from the producers\' viewpoint.
The other type contains supplementary data, which the data producer
deems important to also include. This supple­mentary data may be
necessary to interpret the primary data, (such as orbit and attitude)
and/or it may be explanatory material.

Within this project, the data of primary interest is of high volume, and
thus PVL is a format inappropriate for that portion of the interchange.
However, there is often low-volume ancillary and supplementary
information that needs to be interchanged. PVL could be used to
interchange this type of information.

Some of the ancillary information comes in the form of a calibration
curve. Figure 2-3 illustrates the use of PVL for describing this
calibration curve. The purpose of this curve is to calibrate the
temperature sensor raw data to determine the engineering value of
temperature. The temperature sensor raw value is collected in three
modes (science, dump and engineering), and the location of that data
within the telemetry frame changes depending on the mode. The
engineering mode data includes multiple readings of the sensor within
each major frame.

Figure 2-3: Example of Application Data

This example includes the heavy use of comments to explain how the
calibration curve information is intended to be used to calculate the
engineering value of temperature from the raw telemetry value. The
length of the raw value is given by the parameter TELEM_LENGTH and the
position of the value in each of three modes is given by the parameter
FRAME_POSITION. When these two items are applied to the frame data, the
raw telemetry value of temperature may be extracted. The equation
described by the calibration curve is then applied to convert the raw
telemetry value into an engineering value for temperature.

### Data Description Information

A Data Entity Dictionary (DED) is a repository of the definitions of the
vocabulary used in an information system. A DED enables users separated
by discipline, geography or time to share the same semantic view of that
data. The primary requirement of a DED is to provide complete
definitions of the vocabulary used in the data product labels, in the
metadata for the data product, and in the descriptive detail of data
objects. Each entry in a DED will typically define a data entity, give
information such as name, unit, type (e.g., digital, analog, etc.),
domain, etc.

In our scenario, the information being interchanged is described through
the use of data description objects. Data description objects may
contain:

1\) information about the physical representation and layout of data;

2\) data entity dictionary information which provides definitions of
data entities; or

3\) a combination of these and other types of information.

Each of these types of data description information may use PVL for its
format. Examples of types 1 and 2 are given below. Type 3 includes
descriptions where physical and semantic information is intermingled; it
may also include information on dependencies or relationships between
data objects.

#### Using PVL to Describe a Data Format

PVL can be used to describe the format of general data structures. In
the example shown in figure 2-4, the order of data fields is represented
as a sequence, FLD_ORD, and each data description is represented by the
aggregation block DATA_REP.

Figure 2-4: Data Description Information Using PVL

In this example, only the physical representation of the variables is
being described. Other descriptive information would be included in a
related data entity dictionary.

#### Using PVL in a Data Entity Dictionary

In this scenario, there are several spacecraft that carry instruments
for the science program. Among the items that the DED provides is a list
of the valid values for spacecraft names and their associated
instruments. It also contains information on the units of measure and
acceptable ranges of instrument readings. Example entries are shown in
figure 2-5.

Figure 2-5: Data Dictionary Information Using PVL

In the first entry, the name and definition of SPACECRAFT_ID are given.
The list of valid spacecraft identifiers is provided in DOMAIN_LIST. The
DATA_SYNTAX = Enumeration; statement indicates that this entry has a
specified list of valid values.

In the second entry, the DATA_SYNTAX = Date/Time; statement indicates
that the value is date/time.

# FORMING PVL STATEMENTS

This section describes PVL and provides examples that illustrate the
formation of PVL statements. PVL assignment statements are generally of
the form:

parameter name = value \[;\]

where the brackets around the semicolon indicate that it is optional

This format specifies the value to be associated with the parameter name
in a simple manner. There are two other statement types: aggregation
blocks (discussed in 3.4) and the end statement (discussed in 3.5). An
aggregation block is a named collection of assignment statements and/or
aggregation blocks. A sequence of PVL statements is known as the PVL
Module. The PVL Module exists in an external module such as a file, or
SFDU object. The end statement is an optional, special type of statement
that indicates the end of the PVL Module prior to the end of the
external module. A PVL Module may be empty and contain no statements.
Empty PVL Modules may occur within a standard data product, which
contains several PVL Modules, when data for one of the modules was not
available.

The following practices may be used to enhance the readability of PVL
statements:

-- the practice of placing only one statement per line;

-- the use of block names in end aggregation statements;

-- the use of an explicit delimiter.

For consistency, the examples in this section will use the semicolon for
statement delimitation, will include block names in end aggregation
statements, and will present statements on separate lines.

## Character Sets

PVL is designed to be used in the transfer of information between
heterogeneous environments. In order to accomplish this, the character
set used must be unambiguously specified. The basic version of PVL
(CCSD0006) specifies its character set based on the ASCII 7-bit encoding
set. It uses the printable ASCII character set, the space character and
the following format effector characters: horizontal tab, vertical tab,
line feed, carriage control and form feed. The printable ASCII character
set includes the lower case letters a through z, the upper case letters
A through Z, the digits 0 through 9, and the following non-alphanumeric
characters:

! \" \# \$ % & \' ( ) \* + , - . / : ; \< = \> ? @ \[ \\ \] \^ \_ \` {
\| } \~

The extended character set version of PVL (CCSD0008) extends the basic
version by including the Additional Character Set, which is the G1
character set of ISO 8859-1 (reference \[4\]). The use of this
Additional Character Set provides multilingual capabilities by
supporting the use of accented characters used in many languages.

The space character and format effector characters are referred to as a
white space characters. This is because they are often used between
statements or statement elements to provide formatting to improve human
readability. This formatting of space is said to create \"white space\"
within the display of the statements. Note however that the Non-Breaking
Space character available in the extended character set version of PVL
(CCSD0008) is not considered to be a space character.

Several characters are reserved for specific purposes within PVL or
future use. These characters, which are referred to as reserved
characters, are presented below:

! \" \# % & \' ( ) , ; \< = \> @ \[ \] \` { \| } \~

The reserved characters are not available for use in parameter names,
block names, or unquoted strings.

The remaining members of the character set which are neither white space
nor reserved characters are referred to as unrestricted characters. Note
that the Non-Breaking Space character in the extended character version
of PVL (CCSD0008) is considered an unrestricted character.

## Comment

PVL allows the use of comments to provide explanatory material within
the PVL Module. Comments do not impact the association of names with
values, and are ignored by that process. Comments promote human
readability and understandability of PVL statements, and can provide
additional contextual information for the human reader. Comments are a
sequence of PVL characters which begin with a forward slash-asterisk
character pair (/\*) and end with an asterisk-forward slash character
pair (\*/). Comments may not be nested. To prevent inadvertent nesting
of comments, it is invalid for a forward slash-asterisk character pair
(/\*) to appear within a comment.

Examples of valid comments:

/\*This is comment one \*//\* This is comment two\*/

/\* This is a long comment which has the format effectors

carriage return, line feed, and tab inside it \*/

Example of invalid comment:

/\*This /\* is not a comment \*/

The second forward slash-asterisk pair is not allowed within the comment
statement and would be considered an error.

## Assignment Statement

The assignment statement provides the mechanism to associate a value
with a parameter name. The assignment statement consists of a parameter
name followed by an assignment symbol (equal sign), and a value. A value
is required (e.g,. VAR2 = ; is an error). Any value may optionally be
followed by a units expression. The statement ends with an explicit
delimiter (the semicolon), the beginning of the next statement, or the
end of the PVL Module. If a statement is delimited due to the beginning
of the next statement, then white space, comment(s) or a combination of
white space and comment(s) must occur prior to the next statement. White
space and/or comments are ignored if they occur between the parameter
name and the assignment symbol; the assignment symbol and the value; the
value and the optional units expression; the value and the explicit
delimiter; the units statement and the explicit delimiter; or the
explicit delimiter and the beginning of the next statement. Explicit
delimiters are only allowed at the end of a PVL statement, hence null
statements are illegal (e.g., VAR1 = A;; is an error).

### Parameter Name

A parameter name is the name used to reference the value. The parameter
name may be any combination of unrestricted PVL characters. This means
that white space characters and reserved characters may not be used in
parameter names. However, since it is an unrestricted character, the
Non-Breaking Space character is allowed to be in a parameter name in the
extended character set version of PVL (CCSD0008). However, due to the
confusion this may cause for human readers, it is recommended that you
do not use parameter names containing the Non-Breaking Space.
Additionally, parameter names may not contain the character combinations
of forward slash-asterisk (/\*) or asterisk-forward slash (\*/), since
these are used as comment delimiters. It must also be distinguishable
from a numeric or date/time value.

A parameter name should be chosen for human readability. If a data
entity dictionary is used in conjunction with PVL, additional
descriptive information may be recorded in the data entity dictionary.

The following are examples of valid parameter names:

SPACE_CRAFT

StartTime

PHASE.2.4

Since the following contain characters not allowed in the basic version
of PVL (CCSD0006), they are NOT valid parameter names in the basic
version. But the following are valid parameter names in the extended
character set version of PVL (CCSD0008):

Vehículo

Téléphone

SPACE CRAFT \-- contains Non-Breaking Space \-- Allowed but not
recommended

The following are NOT valid parameter names in either version:

SPACE CRAFT \-- contains white space character

Start/\*Time \-- contains comment begin characters

PHASE\[2,4\] \-- contains reserved characters

PHASE(2) \-- contains reserved characters

### Value

The value portion of an assignment statement may contain a simple value,
a set or a sequence, any of which may be followed by a units expression.
A simple value is a numeric, a string or a date/time value. Sets and
sequences are a collection of zero or more other values, any of which
may be a set or sequence. A Sequence is a collection of values in which
the order of the values has meaning. A Set is a collection of values for
which the order is not important. A value must be provided in an
assignment statement (e.g., VAR =; is an error).

The types of values allowed within the assignment statement are
classified as being simple values, sets, or sequences. A simple value
may be a numeric, a string, or a date/time value. Simple values can be
viewed as a single occurrence of a number or sequence of characters.
Sets and sequences are collections of values.

#### Numeric Values

Numeric values are composed of PVL characters that follow the following
encoding rules. Numerics are widely used within the space science and
engineering communities. Numerics in PVL may be in either decimal or
nondecimal notation.

A decimal number in PVL uses one of the three numerical representations
(integer, floating point and exponential) specified in ISO 6093
(reference \[7\]). These representations use the following subset of the
PVL characters set: the digits (0-9), the period (.), minus (‑), plus
(+), e and E.

Figure 3-1 contains examples of decimal numerics to illustrate the three
different forms. Integers consist of a sequence of digits, which may
optionally be preceded by a sign. If no sign is present, then the value
is assumed to be positive. In the first example, the value of Records
contains a positive integer. In the second example, the value of OFFSET
contains a negative integer. In the third example, GRÖSSE is set to a
positive integral value.

Floating-point numbers are represented as a sequence of digits with an
embedded decimal point. A sign may optionally precede floating-point
numbers. Unsigned floating-point numbers are assumed to be positive. In
the fourth example, LONGITUDE contains a negative floating point number.
In the fifth example, PITCH contains a positive floating-point number
with an explicit sign.

Exponential numbers consist of a significand (i.e., mantissa) and an
exponent separated by the letter E or e. The value of the number equals
the value of the significand multiplied by the result of 10 raised to
the power represented by the exponent. The significand may be either an
integer or a floating-point number. The exponent must be an integer.
Either the significand or the exponent may be negative. In the sixth
example, Flux contains a positive exponential number with a negative
exponent. In the seventh example, ALTITUDE contains a positive
significand with a positive exponent. Note that the difference in case
of the exponent indicator E in the last two examples is a matter of
style, and does not affect the interpretation of the value.

Some applications require nondecimal numerics. The nondecimal encoding
forms allow the use of bases other than ten for numerics. Nondecimal
encoding is only allowed for integers. The supported nondecimal forms
are binary, octal and hexadecimal. The nondecimal notation used consists
of an optional sign, followed by the radix (expressed in base 10), a
number sign (#), the nondecimal number and the number sign. The
nondecimal number portion (the part between the number signs) is
interpreted as being a positive, uncomplemented integer.

Nondecimal numeric encodings provide an alternate method of providing
numeric information for conversion into local numeric form. If the
application intends to use nondecimal encodings without conversion, such
as for flag settings or masks, then the values should generally be
presented as quoted strings. Quoted strings will be passed unprocessed
to the application for its own uses. An application may use nondecimal
numerics to pass flag values if certain precautions are taken (see
4.5.3).

Nondecimal integers may be binary, octal or hexadecimal, using bases of
two, eight and sixteen respectively. Figure 3-2 contains examples of
nondecimal numerics to illustrate the encoding rules.

Binary numerics are expressed in base two, therefore the only digits
available for use within this representation are 0 and1. The radix value
for binary numbers is 2. In the first example, CODE_REP shows a positive
binary number. In the second example, OFFSET shows a negative binary
number, which would convert to -5 in decimal notation. Note that the
sign of the value precedes the radix value, the nondecimal number
portion (the part between the number signs) of all of the encodings are
expressed as positive, uncomplemented integers to allow for transport
between systems with different internal representations of negative
integers.

Octal integers may only use the digits 0-7 for their nondecimal
representation. The radix for octal numbers is 8. In the third example,
StatusCode shows a positive octal number.

Hexadecimal integers may only use the digits 0-9, and the letters a-f or
A-F for their nondecimal representation. The radix for hexadecimal
numbers is 16. In the fourth example, FluxMagnitude is assigned a
positive hexadecimal value.

#### String

A string value consists of a sequence of PVL characters. A string value
may be either quoted or unquoted. An unquoted string may only contain
unrestricted PVL characters. Since it is an unrestricted character, the
Non-Breaking Space character is allowed to be in an unquoted string in
the extended character set version of PVL (CCSD0008). However, due to
the confusion it could cause, we recommend against such a use. A string
that requires reserved characters or white space characters must be
quoted. A string must also be quoted if it could be interpreted as a
numeric when its intended usage is as a string.

A quoted string consists of a sequence of zero or more PVL characters
enclosed in matching quote string delimiters. The quote string
delimiters are the quotation mark (\") and the apostrophe (\').

The only restriction on the contents of a quoted string is that it may
not use the quote delimiter, which encloses the string, within the
string. Quoted strings are required when a string value contains white
space or reserved characters. A string must also be quoted if the value
could be interpreted as a numeric or date/time value, and a string value
is intended.

Quoted string values may include either an apostrophe or a quotation
mark, as long as the alternate quote delimiter is chosen, e.g., a string
enclosed within quotation marks may include apostrophes.

Figure 3-3 contains several examples of quoted strings. In the first
five examples the string is required to be quoted. In the first two,
reserved and white space characters were included in the string. In the
third, the identifier could be interpreted as a numeric. In the fourth,
white space and apostrophe are included in the value, which requires
that the string be enclosed in quotation marks. In the fifth example,
the user needed to represent an empty string as the value. The sixth
example is a quoted string, which could alternately be presented as an
unquoted string; it is quoted as a matter of preference. The last two
examples illustrate the use of quote delimiter characters enclosed
within strings delimited by alternate quote delimiter.

Figure 3-3: Examples of Quoted Strings in PVL

A string may take the unquoted form if it meets certain criteria. An
unquoted string may be of any length greater than zero, and consists of
a sequence of unrestricted PVL characters. They may not contain white
space, reserved PVL characters or comment delimiters (/\* or \*/). In
addition they must not conform to any of the numeric encoding rules
since they would be interpreted as numerics rather than strings. Figure
3-4 contains examples of unquoted strings. In the first example,
SPACE_CRAFT includes only alphabetic characters. In the second example,
EMAIL contains both alphabetic and non-restricted symbol characters.

#### Set

A set is collection of values for which order of the elements is not
important. Sets may contain simple values, sets, sequences or any
combination thereof. Generally, sets contain information of the same
type, but this is not a requirement. A set is delimited by curly
brackets. A set may be empty or it may contain one or more values. If a
set contains more than one value, the values are separated by commas.
When commas are used, a value must appear both before and after the
comma (i.e., the statement set1 = {2,,}; is illegal). White space or
comments may occur between the curly brackets, values and/or commas.
Figure 3-5 shows several examples of assignment statements containing
sets. Note that the last two examples are equivalent, since the
positional order of a set\'s elements is not significant.

#### Sequence

A sequence is a collection of values for which the order in which the
elements are given by the user is considered important. Sequences are
delimited by a matching parenthesis pair. Sequences may contain simple
values, lists or both. Sequences often contain values of more than one
type. If a data entity dictionary is used to provide descriptive
information, it may prescribe what type of value is valid at each
position in a sequence. A sequence may be empty, or may contain one or
more values. If more than one value is enclosed in a pair of
parentheses, they are separated by commas. When commas are used, a value
must appear both before and after the comma (i.e., the statement
sequence1 = (2,,); is illegal). White space and/or comments may occur
between the parentheses, values, and/or the commas separating values.

Figure 3-6 contains some examples of sequences. Note that the first
example is an empty sequence. The second example contains a sequence
with a single entry. The third example shows a case where all the
enclosed values are of the same type. The next example shows that
elements of a sequence need not be of the same type. The fifth and sixth
examples are of sequences of sequences. Note that although the sequences
in the last two examples contain the same elements, that they are not
equivalent because they are not in the same positional order, and that
order is significant for sequences.

#### Date/Time Value

Date and time values are used in number of different applications and
are often represented in a myriad of different formats. PVL uses a
subset of the CCSDS ASCII time code format. This provides a standard
time/date representation to be used across applications. All times are
expressed as Universal Coordinated Time, which is also known as
Greenwich Mean Time.

Date and time can be presented as independent units or combined into
date/time value. The date format may indicate year, month and day, or
year and day of year. In each case the year is represented by a four
digit sequence. At least one digit of the sequence must be non-zero.

For the year, month and day format the form is

yyyy-mm-dd

where yyyy is the four digit year (0001‑9999)

mm is the two digit month (01‑12)

dd is the two digit day (01-31)

For the year and day of year format the form is

yyyy-ddd

where yyyy is the four digit year (0001‑9999)

ddd is the three digit day of year (001-366)

Time is represented in the following form

hh:mm\[:ss\[.d\...d\]\]

where hh is the two digit hour (00-23)

mm is the two digit minute (00-59)

ss is the two digit second (00-60)

Figure 3-7 provides examples of the various date/time forms. The first
example uses the full time format using the year-month-day form of date
and a minimum length time code, without the optional terminator symbol.
The second example uses the full date/time code with the date in
year-day of year form, the full precision form of time, and the optional
terminator. The third example shows the date subset form using the
year-month-day form. Notice that the T separator is not used in this
form. The fourth example uses the time subset.

#### Units Expression

It is often helpful to provide information about the units involved with
simple values, sets or sequences. A units expression consists of a
string enclosed within angle brackets (\<\>). The units value is the
sequence of characters between the angle brackets excluding any leading
or trailing white space characters.

PVL allows a units expression to optionally follow a set, a sequence or
a simple value. A units expression may follow a value enclosed within a
set or sequence. Only one units expression may follow any simple value,
set or sequence.

PVL passes unit information to an application. The application does all
interpretation of the units and sets precedence in cases where a member
of a set or sequence has a units expression, and the list has a units
expression. The application also determines if a units expression
overrides units which may have been set by a data entity dictionary.

Units are provided by PVL as a service to the calling application, which
may or may not choose to use them, as appropriate.

Figure 3-8 contains examples of units expressions in assignment
statements. Note that in the first example, the units follow an
individual numeric. In the second case, two separate numerics are
included in a sequence each with its own units expression. In the third
case, the units expression following the sequence applies to the
sequence contents. The fourth case illustrates that reserved characters
and white space characters may be used as part of the units value. Only
the angle brackets themselves are disallowed within the units value. As
with quoted strings, the sequences forward slash-asterisk and
asterisk-forward slash are treated simply as characters within the units
value.

Note that while units are generally associated with numeric values, they
are not restricted to numeric values. The application determines the
interpretation of a unit following any set, sequence, or simple value.

## Aggregation Block

It is often useful to note that a group of values is related, and to be
able to refer to such a group by name. For example, the aggregation
block may be used to describe data entities in a data entity dictionary.

The aggregation block allows the grouping of statements and/or other
aggregation blocks into a named block. The block begins with a start
aggregation statement. The statement(s) and/or nested block(s) follow,
and the block is then closed with an end aggregation statement.
Aggregation blocks may be designated as either groups or objects. Both
designations are in common usage. PVL makes no distinction between the
two types of aggregation blocks. Applications may make use of both types
and assign any distinction in meaning or use that they deem appropriate.

A block name is required for the begin aggregation statement and is
recommended for end aggregation statements. The form of the block name
is the same as a parameter name. Begin aggregation statements are of the
form:

BEGIN_GROUP = block_name\[;\]

or

GROUP = block_name\[;\]

or

BEGIN_OBJECT =\_block name\[;\]

or

OBJECT = block_name\[;\]

These synonyms are allowed for historical compatibility with several
existing keyword languages. Since BEGIN_GROUP and GROUP are
syntactically equivalent and BEGIN_OBJECT and OBJECT are syntactically
equivalent, the use of synonymous forms of the keyword may not be used
to provide different meanings (semantics) for applications. Use of the
BEGIN_GROUP form is preferred over the GROUP form. Use of the
BEGIN_OBJECT form is preferred over the OBJECT form. Since BEGIN_GROUP
and BEGIN_OBJECT are **not** syntactically equivalent, applications may
assign different meanings (semantics) to their use.

End aggregation statements are of the form:

END_GROUP \[= block_name\]\[;\]

or

END_OBJECT \[= block_name\]\[;\]

where the use of square brackets shows that the semicolon delimiter is
optional and the block name is optional in the End Aggregation
statements. Use of a block name in the End Aggregation statement is the
preferred form.

The type (Group or Object) must match in the begin and end aggregation
statements. If a block name is used in the End aggregation statement, it
must match the name in the paired begin aggregation statement.
Aggregation blocks may be nested, but inner blocks must be closed before
any enclosing outer blocks are closed.

This means that the aggregations of the form:

Begin_aggregation = Name1;

Begin_aggregation = Name2;

End_aggregation = Name1;

End_aggregation =Name2;

are ILLEGAL, since the inner aggregation block (Name_2) had not been
ended before the enclosing block (Name_1). The indentation is used to
show the nesting level.

Figure 3-9 contains examples of valid aggregation blocks. All examples
include block names in the end aggregation statement since this is the
preferred practice. One of the examples illustrates how an aggregation
block can be used as a data entity dictionary entry (2.1.1). The other
example shows how an aggregation block can be used to describe an image
type. Note that group and object aggregation blocks may be nested within
each other.

Figure 3-9: Examples of Aggregation Statements

## End Statement

The PVL Module may be ended prior to the end of the provided sequence of
octets within which it is presented by the use of the End statement. The
End Statement is a special type of statement and has different
delimitation rules from other statements within PVL. In particular, the
End Statement is delimited by one of the following constructs: the first
white space character following END, a semicolon immediately following
END, the closing of a comment immediately following END or the end of
the provided octet space immediately following END. The End Statement
may also be used to promote readability in the SFDU environment, when
marker delimitation is used, by alerting the human reader that the PVL
Module has ended.

Figure 3-10 illustrates the use of the End Statement. The statement
Filter = Blue; is the last assignment statement in the PVL Module. In
the construct END ;/\*That\'s All!!\*/, the space following END
terminates the PVL Module, and that the semicolon is the first character
of Non-PVL data available to an application for its own uses. Note that
even though the data following END looks like a series of PVL
statements, it is outside of the PVL Module and therefore it is to be
processed separately by the application environment.

# RECOMMENDED PRACTICES AND USAGE LIMITATIONS

PVL is intended to enable both human readability and machine
parsability. Some of the suggested practices are intended to enhance
human readability without sacrificing machine parsability. Other
practices are intended to minimize problems associated with various
transfer techniques, or to assist applications in their use of PVL
values. This section also points out known limitations within the
language.

## Data Entity Dictionary Usage

Since PVL provides syntax with a limited set of semantics, the semantics
for interpreting PVL statements must be provided externally. The most
common way of providing semantics for a PVL Module is by the use of an
associated DED. As discussed in 2.1.3.2, a DED is a repository
containing information necessary for the interpretation of parameters
defined in a PVL statement. It contains, at a minimum, a list of data
names and their definitions. It may also contain information on the
validation of parameter values with information such as range, data
type, formation rules, or a list of valid values. It may also contain
information on the interrelationship of data entities.

A DED may also contain information on application conventions, such as
lexical rules for parameter names or possible semantic meaning
associated with use of GROUP or OBJECT as the keyword used in the
construction of aggregations.

The use of a DED in conjunction with PVL is highly recommended to
provide a fuller set of semantics for the interpretation of PVL
statements.

## Human Readability Practices

The following practices are aimed at improving the human under­standing
of PVL statements. These practices are not required, but serve to make
the information more readily accessible to the human user.

### statement separation

The ability to separate statements is vital to understanding the
information contained in a PVL Module. It is recommended that:

1\) The same statement delimitation technique is used throughout any
given PVL Module.

2\) Explicit statement delimitation is the preferred form to ensure
reliable interchange between different environments. This is
particularly the case where transfers take place between different text
environments, in which ASCII control characters may be transferred in
different ways and in which space characters can be removed by
underlying service software.

3\) Statements should appear on separate lines to enhance readability.

The preferences of the intended user community and the environments in
which the PVL Module is expected to be found may provide the basis for
deciding what particular delimitation technique is appropriate.

### aggregation block readability

In the definition of aggregation blocks, the use of indention between
the begin and end block statements greatly improves readability. Since
blocks may be long and nested, the use of these visual clues allows the
human user to more readily identify the structure and nesting of
aggregation block statements.

The use of block names in the end aggregation statement also aids in the
readability of aggregation blocks. Its use aids the reader in
determining the scope of long, complicated aggregations, particularly if
there is nesting.

Synonyms for begin aggregation are allowed for historical compatibility
with several existing keyword languages. Since BEGIN_GROUP and GROUP are
syntactically equivalent and BEGIN_OBJECT and OBJECT are syntactically
equivalent, the use of synonymous forms of the keyword may not be used
to provide different meanings (semantics) for applications. Use of the
BEGIN_GROUP form is preferred over the GROUP form. Use of the
BEGIN_OBJECT form is preferred over the OBJECT form.

Since BEGIN_GROUP and BEGIN_OBJECT are **not** syntactically equivalent,
applications may assign different meanings (semantics) to their use.

It is recommended that one of each set of begin-aggregation keywords be
used in any given module, e.g., do not mix the use of BEGIN_GROUP and
GROUP within a module. Mixing synonym types might cause a user
unnecessary confusion.

Figure 4-1 illustrates how the use of indentation and the use of block
names in the end aggregation statement make aggregation blocks more
readable. The first example uses the preferred methods, which increases
the visibility of the structure of the information. The second example
contains the same information with a different block name, but without
the use of indentation, block names in the end aggregation statement, or
consistent begin aggregation keyword forms. While the second example is
legal within PVL, it is much more difficult for a human reader to
understand.

A machine will properly parse both examples. However, if there had been
an error in the structure, the first example would be easier to examine
and find the error.

### Use of Meaningful Parameter AND BLOCK Names

The use of meaningful parameter and block names greatly increases the
human readability of PVL statements. While the statement VAR1 = POLAR;
is easily parsable, it is less meaningful than the statement
SPACE_CRAFT = POLAR;. Since PVL statements are often used with
identifying objects in the SFDU environment, it is important to choose
parameter names that will facilitate the identification of the
parameters even in the absence of the associated data entity dictionary.
Although Non-Breaking Space characters are allowed in parameter and
block names, their use could be confusing to human readers, and is
therefore discouraged.

### Use of Comments

Use of comments within PVL can aid the human reader in understanding the
data. However, the thoughtless use of comments may hinder rather than
assist human readability by producing a cluttered appearance. Common
uses of comments are to:

-- describe PVL Module structure;

-- describe aggregation blocks;

-- explain individual statements.

The use of special syntax within comments which is intended to be
machine-interpretable is severely discouraged.

### Use of NON-BREAKING SPACE CHARACTERS

Non-Breaking Space characters are part of the G1 character set of
8859-1. As such, they are available for use in the extended character
set version of PVL (CCSD0008). The Non-Breaking Space character is not
considered to be a White Space character, therefore it is available to
be used in places where white space characters are not allowed, e.g., in
parameter and block names and in unquoted strings. For some
applications, this will prove valuable. However, before PVL users choose
to use the Non-Breaking Space Character in these situations, they should
consider the likely confusion that would be caused by using it, since it
will normally appear in printed output exactly the same as a normal
space character.

## Application Conventions

This subsection discusses various conventions that application
developers may find useful. It focuses on the interface between
information in PVL form and the application that will be using it.

### Parameter Name Conventions

To facilitate the direct use of PVL parameter names within an
application, the parameter names should follow formation rules specific
to the application, project or discipline.

For example, within certain environments the hyphen is reserved as an
operator. In other environments, the hyphen is used to enhance the
readability of the variable names. In cases where the PVL Module may be
used in several different application environments, it may be necessary
to use a highly restrictive set of formation rules in the construction
of parameter names.

### Use of Group and Object Aggregation Types

PVL allows for the use of both group and object as designations for
aggregation blocks. If an application does not need to distinguish
between aggregation types, a single convention should be chosen, i.e.,
all aggregations should be designated as group or object.

Some applications have found it useful to differentiate between
aggregation types. As an example, an application may find it useful to
designate the OBJECT keyword to define a structure of items, and the
GROUP keyword to collect together a single instance of related items.

### Definition of a Null Value

There are some cases where it is useful to note that there is no valid
value for a parameter. While it is possible to denote an empty quoted
string, set or sequence by providing no value between delimiters, this
is not the case for parameters whose values are expected to be unquoted
strings, numerics or date/time values. Some applications may find it
useful to define a specific value in their data entity dictionary to
denote no valid value exists. The value NULL is often used for this
purpose. The use of a null keyword is especially useful in applications
where a template is used, to verify that the parameter was not simply
overlooked.

### Use of End Statement

Some applications may wish to have additional data included with the PVL
Module in the same group of externally provided octets. The End
Statement allows a way to indicate the end of the PVL Module prior to
the end of the externally provided sequence of octets. Other
applications may wish to use the End statement to stop PVL processing
when the provided octet set is substantially larger than the sequence of
PVL Statements.

## Transfers of PVL Statements

PVL is designed to be transferred between heterogeneous systems. As
noted previously, PVL consists of a defined set of octets (e.g., a file,
an SFDU), in which PVL statements are found. The hardware and software
services that are used in data transfer are called transfer protocols.
Transfer protocols exist for physical media (e.g., tapes and CD-ROMs) on
which data is placed and for communication networks over which data may
be transferred. There are two types of transfer: binary and text.

A binary transfer is defined as an octet by octet copy of the original
sequence of octets. The set of octets is strictly preserved, and the
data is not altered in any way. The internal representation of the data
is the same on the recipient system as it was on the sending system. In
general, transfers to media (e.g., CD-ROM and tape) are binary
transfers.

In text transfers, the sequence of octets is assumed to be a sequence of
characters intended for human interpretation. This assumption means that
certain transformations may take place to assure that the conventions
for character representation and end of line match what the recipient
system expects text to look like. For example, an end of line is
represented on some machines as a single character (line-feed), on other
machines end of line is represented as a two character sequence
(carriage-return and line-feed), and on some mainframes the line
indication is an embedded character count at beginning of each line in a
file. Text transfers can transform the sequence of octets to make sure
that lines are preserved in a manner that the receiving system
understands. Text transfers may also make assumptions about the maximum
number of octets in a line, and may trim trailing blanks from a line.
Text transfers will also convert character representations to the native
form of the receiving system (e.g., ASCII to EBCDIC). Text transfers
generally occur in protocols which rely on communications networks since
the transformations depend on knowing the text conventions in the
receiving environment. Transfers to transportable media have no
assurance of what the receiving system will be, therefore any
transformations occur outside of the transfer protocol itself, i.e.,
when the media concerned is read.

The choice of transfer protocol may be set by application convention or
the nature of context in which the PVL is being transferred. For
example, if the PVL Module is contained within an SFDU which also
contains binary data, the entire SFDU will need to be transferred using
a binary protocol.

Text transfers are, for the above reasons not ideal for the transfer of
PVL between heterogeneous systems. However, text transfer of PVL can be
done successfully. This subsection illustrates text transfer and
explains what actions a user can take to counteract some of the
pitfalls.

### Line Format Differences

PVL Modules environment may employ line formatting to assist human user
readability. Since different systems use different representations for
end of line, a binary transfer may result in the PVL Module looking
different in the receiving environment. Figure 4-2 illustrates how the
differences in the representation of end of line can effect the
appearance of the PVL Module. The examples show the effects of a binary
transfer between a system using line-feed to denote end of line to a
system using the sequence carriage-return/line-feed to denote end of
line.

The first set of PVL assignment statements shows how the statements were
intended to appear in the sending environment. The second set shows what
can happen when a transfer occurs from a system using carriage return
line-feed as end of line to a system using line-feed as the end of line:
the lines are double spaced, since the carriage-return and line-feed are
each interpreted as an end of line. In the third example, we see that
the line-feed character in the receiving environment advances down one
line, but does not return to left margin. While the three
representations look quite different to the human reader, the parser
would interpret each correctly since line-feed and carriage return are
both white space characters.

There may be problems with a text transfer that changes the line
delimiter if the provided set of octets is indicated by an octet count
as in some delimitation techniques in SFDU methodology. The problem
would arise because the number of octets would change as the end of line
marker changes between a one or two character indicator. If this is the
case, the count will be wrong, and the outside mechanism will present a
set of octets that ends too early, in the case of going from a single
character indicator to a double character indicator, or that includes
extraneous material when the transfer is in the reverse direction.

### End of Line Deletion

A troublesome problem may occur when moving from a system where the line
information is embedded in the internal file structure, (e.g., a
character count at the beginning of each variable length record,) to a
transfer media where specific characters are used to indicate lines. In
some instances, a binary transfer between systems results in a loss of
line delimitation between systems. Note that this type of end of line is
outside the scope of PVL, which deals with ASCII text characters. A
conformant PVL parser would not be required to treat this type of end of
line as white space. It may, however, be a local convention to treat the
embedded end of line as if it were a white space character.

In these instances, the ability to preserve tokens may be aided by using
an explicit delimiter to end statements and by beginning each line with
a blank. The explicit delimiter ensures that statement end is
recognized, the initial blank helps to separate items within a quoted
string.

### Addition of Spurious New Line

Certain text transfer mechanisms establish a maximum line length. If a
line is longer than the transfer maximum, then a new line is begun at
that point, without regard for the possible corruption of the data. This
could result in the insertion of white space in the middle of a
parameter name or value and invalidate the statement. If a transfer
mechanism with such properties is likely to be used, then it would be
prudent to assure that lines are shorter than the maximum dictated by
the transfer mechanism.

### Character Representation Conversions

If data is being transferred between systems using different character
representations, such as ASCII and EBCDIC, text transfers will convert
the data to the native character representation in the receiving
machine. Since the basic version of PVL (CCSD0006) is defined as being
in ASCII text, and the extended character set version of PVL (CCSD0008)
is the CCSD0006 character set extended by the G1 set of ISO 8859-1, a
PVL Module that has been translated to EBCDIC would no longer conform to
either version of the PVL standard. If it is possible to specify the
character encoding in a text transfer, it should be specified as ASCII
for the CCSD0006 version and ISO 8859-1 for the CCSD0008 version of PVL.

### Blank Trimming

Some text transfer systems trim trailing blanks from lines. If these
trailing blanks are within quoted strings and are expected by the
calling application, problems will arise. If it is necessary to preserve
these blanks, and to use the transfer protocol, a specific character or
sequence of characters can be used as a marker. This marker would be
inserted after the last blank to be preserved and before the end of
line. Thus, any blank trimming stops upon encountering the marker. Any
recipient application would need to be aware of this convention in order
to be able to effectively process a PVL Module using this convention.

### Tab Conversion

The tab character may represent a different number of spaces on
different systems. If information is to be presented in tabular fashion
for clarity, it would be prudent to convert tabs to spaces to ensure
that the alignment is as intended. Obviously, even the use of blanks may
not preserve the columns if a proportional font is used for display or
printing.

## Limitations

There are several types of data expression not supported in these
versions of PVL. The following subsections outline those areas where
limitations exist. The limitations are discussed along with strategies
for obtaining functional equivalents for unavailable services.

### Use of Embedded Quotes

The use of quoted strings within PVL is accomplished by using pairs of
either quotation marks or apostrophes. This allows for apostrophes to be
represented in text strings that are delimited by quotation marks and
for quotation marks to appear in text strings which are delimited by
apostrophes.

A limitation is that quoted strings may not contain both apostrophes and
quotation marks. It may be possible to break a quoted string into
multiple quoted strings, aggregated into a block structure, to allow for
the flexibility required to use both forms of quote string delimiters in
a combined form. This solution would be in the form of an application
convention, rather than a feature of the language.

### Indexed Values

PVL does not provide a standard method for indexed values or indexed
parameter names. Applications may set conventions to approximate these
capabilities.

### NonDecimal Numerics

Within applications, nondecimal numerics (binary, octal and hexadecimal)
are often used for masks or flag settings as bit strings. On the other
hand, within PVL, the nondecimal numerics are interpreted as numeric
values. If it is necessary for an application to receive data via PVL as
masks, flags, or complemented representations, then a quoted string
should be used. The quoted string will be available to the application
in unconverted form for processing by the application.

Non-decimal numbers can be used, but the application must use care to
make sure the flag settings are mapped to the decoded integer value
rather than to the internal representation of any given machine, since
machines differ in their addressing schemes for bit level access. On
some machines, the most significant bit in a byte is in position 0, in
another it is in position 7. By using care in the design of the
application, these differences can be taken into account.

# REQUIREMENTS AND THEIR RATIONALES

This section lists the requirements that PVL was designed to satisfy and
the rationale on which the requirement is based. These requirements are
categorized as being either high level or specific requirements. High
level requirements are listed in 5.1, and specific requirements are
listed in 5.2.

## High Level Requirements

H1. The language shall provide a method of assigning values to a named
parameter.

Rationale: It is a common need to be able to reference values by name.
This allows the recall of these values later.

H2. The language shall provide a flexible mechanism for the formatting
of data, i.e., it shall not require the fixed alignment of values within
the format of the language.

Rationale: This frees data producers and users from having to follow
rigid formats. It also lessens the impact of transfer induced
differences in white space.

H3. The language shall be human-readable.

Rationale: This will permit the language to be read and written by human
operators using standard word processors and displays.

H4. Correct parsing of the language by a receiving application shall be
possible by use of the language alone and shall not require external
communication with the generating application.

Rationale: The language shall be sufficiently well specified that it
will always be interpretable in the same way, independent of system
environment. This means that the data will not be subject to change when
transferred between different environments.

## Specific Requirements

S1. The language shall convey information using assignment statements.

Rationale: The use of assignment statements provides a reliable
unambiguous syntax for associating values with names.

S2. The language shall be expressed using a defined character set as
follows:

S2.1. The alphanumeric character set (a-z, A-Z and 0-9), space, plus the
following punctuation symbols:

! \" \# \$ % & \' ( ) \* + , - . / : ; \< = \> ? @ \[ \\ \] \^ \_ \` {
\| } \~

Rationale: This character set will permit human readability.

S2.2. The characters specified in S2.1 shall be encoded according to the
ASCII standard (ISO 646).

Rationale: Use of ASCII coding permits unambiguous interpretation in
different environments.

S2.3. The following ASCII codes will also be permitted in the language,
but shall be treated equivalently to the space character (ASCII code
32):

Horizontal Tab ASCII code 09

Line Feed ASCII code 10

Vertical Tab ASCII code 11

Form Feed ASCII code 12

Carriage Return ASCII code 13

Rationale: These format effector values are often used to promote human
readability when statements are displayed using standard utilities or
word processors.

S2.4. The extended character set version of PVL shall extend the
character set with the G1 set of ISO 8859-1.

Rationale: The G1 set of ISO 8859-1 is a widely used, human-readable
character set that includes support for accented characters used in a
number of languages.

S3. The language shall be able to convey one of the following types of
information for each of its parameters:

S3.1. a character string

S3.2. a numeric

S3.3. an unordered list of any combination of the types defined in the
language.

S3.4. an ordered set of any combination of types defined by the language

Rationale: Space scientists, engineers and data processing specialists
need to convey the above types of data.

S4. The language shall allow the grouping of statements into named
aggregations.

Rationale: There is a need to be able to express complex data structures
and/or to associate a group of statements.

S5. A numeric shall be defined as being one of the following:

S5.1. Decimal Integer

S5.2. Hexadecimal Integer

S5.3. Octal Integer

S5.4. Binary Integer

S5.5. Real number with a floating decimal point

S5.6. Real exponential number

Rationale: These numeric representations are those which are commonly
used for science and engineering purposes.

S6. Any value within a statement may be optionally assigned units.

Rationale: It may be necessary to indicate particular units used when
conveying science or engineering data (e.g., a set of temperature
readings in K).

S7. The end of statement delimiter shall be either an explicit
terminator, the beginning of the next statement or the end of the
provided octet space.

Rationale: This allows the accommodation of a variety of styles in the
formation of keyword-value statements. In particular, it provides an
easier transition from keyword-value languages that do not use explicit
statement delimiters.

S8. A mechanism to supply comments shall be provided.

Rationale: This allows the inclusion of explanatory information and thus
can contribute to human readability.

S9. A mechanism to denote date and time values shall be provided.

Rationale: These are commonly used constructs in the scientific
community.

S10. A mechanism to denote the end of processable statements shall be
provided.

Rationale: This allows additional data to be processed to be included
within the same provided octet sequence. This is analogous to the
construction allowed in other languages.

########   ACRONYMS AND GLOSSARY

This annex defines key acronyms and the glossary of terms that are used
throughout this Recommendation to describe the concepts and elements of
the Parameter Value Language.

##  Acronyms {#acronyms .Annex-Level-2}

ASCII American Standard Code for Information Interchange

ASN.1 Abstract Syntax Notation One

CCSDS Consultative Committee for Space Data Systems

CD-ROM Compact Disk - Read Only Memory

DED Data Entity Dictionary

EOL End of Line

ISO International Organization for Standardization

FITS Flexible Image Transport System

ODL Object Description Language

PVL Parameter Value Language

SFDU Standard Formatted Data Unit

YACC Yet Another Compiler-Compiler

##  Glossary of Terms {#glossary-of-terms .Annex-Level-2}

**Aggregation Block**: A named set sequence of assignment statements
and/or other aggregation blocks.

**Alphanumeric character set**: The set of characters comprised of the
digits 0 through 9 and the letters a-z or A‑Z.

**Block name**: The name used to identify an aggregation block.

**Comment string**: A delimited string of character information, which
provides explanatory information. This string is treated as white space
syntactically.

**Comment delimiter symbols**: The symbols used to delimit a comment
string.

**Data Element**: The smallest named item or items of data for a given
application.

**Data Entity**: A named collection of data elements.

**Data Entity Dictionary (DED)**: A collection of semantic definitions
for data entities.

**Format effector**: A control character that effects the display of the
printable characters. The format effector characters consist of the
horizontal tab, vertical tab, carriage return, line feed and form feed.

**Numeric**: A special case of an unquoted string that conforms to
formation rules for numeric values.

**Parameter Name**: The name used to associate a data value with a
parameter.

**PVL Module**: The externally defined octet space in which PVL
statements are written.

**Reserved Characters**: The set of PVL characters reserved for special
uses. These characters may not occur in parameter names, unquoted
strings or block names.

**Quote String Delimiters**: The symbols (apostrophe or quotation mark)
used to delimit quoted strings.

**Quoted String**: A delimited sequence of PVL characters.

**Standard Formatted Data Units (SFDUs)**: Data units that conform to a
specific set of CCSDS recommendations for structure, construction rules,
and field specification definition.

**Sequence**: A collection of values in which the order of the enclosed
values is significant.

**Set**: A collection of values in which the order of the enclosed
values is not significant.

**Units expression**: A string enclosed within angle brackets which may
follow a simple value, set or sequence.

**Unquoted String**: A value consisting of a sequence of unrestricted
characters.

**Unrestricted Characters**: The set of PVL characters that may be used
to form parameter names, unquoted strings or block names.

**White space**: One or more space or format effector characters. Used
to promote readability between syntactic elements or within the contents
of comment or text strings.

########   PVL PARSER IMPLEMENTATION ADVICE

This annex provides additional information about PVL in areas that
impact the implementation of automated parsing software.

This Annex is intended to augment the PVL specification (reference
\[\[2\]\]) in areas that impact the implementation of automated PVL
parsing tools. The purpose of PVL parsing tools is to translate PVL
statements into locally defined data structures that can be accessed by
local application programs. The purpose of this annex is to provide
guidance on issues which impact the functionality of a PVL parser
implementation while leaving all algorithmic and data structure issues
to the discretion of the local design and implementation team.
Subsection B.1 provides an overview of the area of automated language
translation to provide a common set of terms and concepts. Further
subsections deal with specific areas where experience has identified
common issues or concerns. This annex will be expanded in the future as
more implementation experience is gained.

B.1 Overview of Language Translators

Translators are highly complex programs, and it is reasonable to
consider the translation process as occurring in multiple steps. A
typical series of phases is shown in Figure B‑1. Each phase might
communicate with the next by means of a suitable intermediate format. In
practice the distinction between phases often becomes a little blurred.

![](media/image3.png){width="5.0625in"
height="3.4916666666666667in"}Figure B‑1: Language Translator Components

The character handler is the section that communicates with the outside
world, through the operating system, to read in the characters that make
up the PVL Module. Because character sets and file handling vary from
system to system, this phase is often machine dependent.

The lexical analyzer is the section that separates characters of the
source into groups that logically belong together to make up the tokens
of the language (symbols like identifiers, strings, numeric constants,
keywords like Begin and End, operators like =, and so on). These symbols
are represented as tokens on the output from the lexical analyzer,
although some tokens need attributes with them such as their names or
values.

The syntax analyzer compares the sequence of tokens to a defined
syntactic structure. It does this by parsing expressions and statements.
(This is analogous to a human analyzing a sentence to find components
like \'subject\', \'object\', \'dependent clause\' and so on.) Often the
syntax analyzer is combined with the semantic analyzer, whose job it is
to determine that the syntactic structures make reasonable sense. The
division between syntactic and semantic analysis is often blurred. An
example of a semantic analysis task in PVL is assuring the values of
paired begin-aggregation and end-aggregation statements are equal.

In language translators there is often an extensive code generator to
convert parsed language instructions into efficient object code. This
function is not necessary for PVL since there is no data manipulation
capability in the language. It may however be necessary to translate
internal symbol tables to an appropriate format for interface to
application programs.

There are a wide variety of compiler building tools available. The most
well known are lex (reference \[\[12\]\]) and yacc (reference
\[\[11\]\]). While it is expected that these tools will be used
appropriately in local implementation, specific techniques for using
compiler building tools are generally considered to be beyond the scope
of this Annex, although occasional notes on lex/yacc are included.

b.2 Input Handling Issues

PVL can be transmitted or stored using binary or text format files and
protocols. There are two issues that should be noted by the implementor:

\- Handling Local End-of-line (text only)

\- Handling End-of-PVL-module (text and binary)

b.2.1 Handling Local End-of-Lines

There are a large variety of methods used by computer systems to
represent End-of-Line (EOL) in a text environment. While most systems
represent EOL by some combination of white space character(s), there are
some systems that represent an EOL by a convention such as including a
byte count field prior to each line (record) and treating each line as
an individual variable length record. If your local system follows such
a convention for text files it is recommended that line boundaries be
recognized by the PVL Module reader and appropriate PVL white space
character(s), such as line feed or the sequence of carriage control and
line feed, be inserted into the character string passed to the lexical
analyzer. This will ensure that PVL statements, which the user intended
to be delimited by line termination characters, will be correctly
interpreted. It will also ensure that quoted strings that contain line
terminations will not lose semantic value by an unintended concatenation
of elements within the quoted string.

The exact implementation of the white space character(s) used as line
termination characters is left to the local implementation.

b.2.2 Handling End-of-PVL-Module

The End-of-PVL-Module concept is similar to the End-of-file or
End-of-transmission signals in conventional programming languages. The
mechanism of terminating the input and exiting the PVL translator are
local implementation issues. It is recommended that the PVL Module
reader pass a white space character to the lexical analyzer prior to
calling appropriate End-of-PVL-module routines to allow for the graceful
handling of unexpected termination.

B.3 Numeric Handling Issues

PVL has flexibility in the expression of numeric values. This
flexibility creates some issues for the implementors including:

-- Resolution of ambiguity between unquoted strings and numerics;

-- Optional conversion of numerics to internal machine representations
and associated precision issues.

B.3.1 Resolution of Ambiguity Between Unquoted Strings and Numerics

The Abstract Syntax Notation One (ASN.1) specification for all numeric
values is a subset of that for unquoted strings. This ambiguity should
be resolved by having numerics take precedence over unquoted strings in
the lexical analysis phase. The implementation of this is a local issue.

NOTE -- Lex accomplishes this through the ordering of context rules: if
two lex expressions match the same string, then the first of the two
expressions in the lex source is chosen.

B.3.2 Conversion of Numerics to Internal Machine Representations

The conversion of numeric values from an ASCII representation to an
internal numeric data type is a local implementation decision. In
general, the actual range and precision of the ASCII numbers that can be
converted will vary based on the host computing system. Therefore, a
parser should provide a mechanism for passing an ASCII numeric string
that cannot be represented in the internal numeric data types of the
host machine. In addition, each local implementation should document:

-- the maximum positive and negative integer numbers that can be
represented;

-- the maximum positive and negative real numbers that can be
represented;

-- the minimum number of significant digits which a real number can be
guaranteed to have without loss of precision.

The last point 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 fraction can guarantee at least 6 significant digits will be exact
(the seventh and subsequent digits may not be exact because of
truncation and round-off errors.)

B.3.3 Units Expression

PVL allows a units expression i.e., \<units\> to follow any value (i.e.,
a simple value, set or sequence) including those that are members of
other list values. This introduces some issues in the design of PVL
tools, including:

-- allowance for units expression;

-- inheritance or expansion of units expression.

b.3.4 Allowance for Units Expressions

A units expression is an optional expression which may follow any value
type. Therefore, for each PVL statement, the parser should be prepared
to pass to the application the contents of the units expression in
addition to the parameter name and value. The contents of the units
expression may be any units value (see 3.3.2.6). If no units expression
is present for a PVL statement, the parser should indicate that fact to
the application according to local convention.

In addition, a units expression may follow any value which is member of
a set or sequence. Therefore, for each member of a set or sequence, the
parser should be prepared to pass to the application the contents of the
units expression in addition to the value. Figure B‑2 contains an
example statement and a conceptual model of a data structure generated
by parsing the example. It is meant to illustrate the concept of parsing
complex PVL statements, the actual data structures used are left to the
local implementor. The example uses a recipe for fruit salad expressed a
PVL statement containing nested sets of integers with units to specify
the types and varieties of fruit to be cut into one inch cubes for the
salad.

![](media/image4.png){width="5.106944444444444in"
height="2.4375in"}Figure B‑2: Conceptual Model of a Data Structure for a
List with Units

b.4 Inheritance of Units Expressions

The inheritance of units expressions is the domain of the application.
An application may wish, for example, that a value inherits a units
expression from:

-- the previous PVL statement;

-- the list in which a value is contained.

This implies that the parser should allow the application access to the
units expression following a list prior to accessing the members of that
list. The table structure in figure B-2 follows this constraint by
constructing the data structure for the entire statement prior to
passing any information to the application program.

# INDEX

Aggregation block, 3-12

Binary, 3-6, 5-3

Block name, A-1

CCSDS Secretariat, i, ii

Comment, 3-2, A-1, A-2

Consultative Committee for Space Data Systems, i

Date/Time, v, 2-8, 3-9, 3-10

Decimal, v, 3-5, 5-3

End statement, 3-14, 4-5

Explicit delimiter, 3-3

Exponential, 3-5

Floating point, 3-5

Format effector, A-2

Hexadecimal, 3-6, 5-3

Integer, 3-5, 3-6, 5-3

Member Agencies, i

Numerics, v, 3-4, 3-5, 4-8, B-4

Octal, 3-6, 5-3

Quoted string, 3-6, 3-7

Sequence, 2-7, 3-4, 3-9, 3-11, A-2, B-5

Set, 2-4, 3-9, 5-2, B-5

Simple value, 3-4

String, 3-7, A-2

Tutorial, iv

Units expression, A-2

Value, A-2

White space, 3-3, 3-8, 3-9, A-3