The PVL Object 

Last modified: September 13th, 1995

Welcome

This library contains a PVL object and a developer's interface routines. Through the interface routines, a program can:

1. Load a PVL document.
2. Interrogate the document, line-by-line.

uncompress pvl.tar.Z

and then type:

tar -xvf pvl.tar

Installation

index.html

this document.

bin/

the test program and 2 test files are here.

src/

a Makefile and the test program's source code.

lib/

a Makefile and the library's source code.

Creating the PVL Library

1. Go into the lib/ directory.
2. Make the library by typing make.

Creating the Test Program

1. Go into the src/ directory.
2. Make the executable by typing make.

To run this program type:

1. tester file1
2. tester file2

How to Interpret the Tester's Results

The tester simply dumps out all the results it finds to the screen. The tester starts by printing out: [BEGIN DOCUMENT]

The tester ends by printing out: [END DOCUMENT]

Each line is preceeded by the statements:
[LINE LISTING]
Parameter=(the parameter string follows the equal sign)

Each element in the line looks like this:
[ELEMENT]
Class=(Simple, Aggregate, Set, or Sequence)
MyLevel=(an integer - a unique number given to each field)
MyParent=(an integer - a number of a previous field, or a 0)
Value=(a string or null)
Unit=(a string or null)

How the Tester Gets the Results

To load in a PVL Document

The tester calls PvlInterfaceFunction() like this (this is simplified code to amplify the point):

/* 
PvlInterfaceFunction() is called with an action and data

#define Pvl_LOAD_PVLFILE in file Pvl.h
#define Pvl_SUCCESS      in file Pvl.h

char *argv[] - passed through main() arguments
*/
int rtn;

rtn = PvlInterfaceFunction( Pvl_LOAD_PVLFILE, argv[1] );
if (rtn != Pvl_SUCCESS) exit( 0 );

To parse a PVL statement and return a line

The tester calls PvlInterfaceFunction() like this (this is simplified code to amplify the point):

/* 
PvlInterfaceFunction() is called with an action and data

#define Pvl_NEXT_TOKEN in file Pvl.h
#define Pvl_LITERAL    in file Pvl.h
*/
rtn = PvlInterfaceFunction( Pvl_NEXT_TOKEN, NULL );
if (rtn != Pvl_LITERAL) exit( 0 );

To return the parameter of the PVL statement

The tester calls Pvlparameter() like this:

char *ptr;
ptr = Pvlparameter();

To return the type of a PVL field

There may be complex PVL statements which include many different Simples, Sets, and Sequences.

The final type, an Aggregate, is never complex and returns either a beginning or end marker.

The tester calls PvlRetClass() like this:

/*
PvlRetClass() returns the class of the current field.  

Fields are incremented as the program calls PvlnextSimple()
and PvlnextValue().  To start from the first field, call
Pvlparameter() once.
*/
int type;
type = PvlRetClass();

To return the Unique Value of a PVL field

The first field (and only field for a Simple PVL statement) will have a unique value of 1. If there are more fields, as in any complex PVL statement, each will be assigned an integer value.

The tester calls PvlRetMyId() like this:

int value;
value = PvlRetMyId();

To return the Parent Value of a PVL field

The parent of a Simple PVL statement is 0.

Here is how a Complex Field is defined. For a Set like this:
SET = {1,5,9};

The fields in the set are as follows:

1. Id=1 Parent=0 Value="" Unit=""
2. Id=2 Parent=1 Value="1" Unit=""
3. Id=3 Parent=1 Value="5" Unit=""
4. Id=4 Parent=1 Value="9" Unit=""

Notice that Id=1 is the "place holder" for the beginning of the Set.

The tester calls PvlRetMyParentId() like this:

int value;
value = PvlRetMyParentId();

To return the Value or Unit of a PVL field

Here are the rules for moving along the fields and retrieving Values and Units:

1. The first field is obtained by calling Pvlparameter()
2. The beginning of a Set or Sequence is marked by a field with no Value. This field might have a Unit (Example statement:

   SET = (1,2)

   the first field has no Value but the Unit="inches")
3. For each field you must call PvlnextSimple() twice, once for the Value and once for the Unit, even if you know it isn't there. If it is empty a NULL is returned.

The tester calls PvlnextSimple() like this:

char *ptr;
ptr = PvlnextSimple();

Output from the Test Files

File1

/* this is a test file consisting of comments, an aggregation,
        simple, set and sequence statements */

BEGIN_OBJECT = EXAMPLE1
        STRING = "this is a test string";
END_OBJECT = EXAMPLE1

[BEGIN DOCUMENT]
   [LINE LISTING]
      Parameter=BEGIN_OBJECT
      [ELEMENT]
         Class=Aggregate
         MyLevel=1
         MyParent=0
         Value=EXAMPLE1
         Unit=(null)
   [LINE LISTING]
      Parameter=STRING
      [ELEMENT]
         Class=Simple
         MyLevel=1
         MyParent=0
         Value=this is a test string
         Unit=(null)
   [LINE LISTING]
      Parameter=END_OBJECT
      [ELEMENT]
         Class=Aggregate
         MyLevel=1
         MyParent=0
         Value=EXAMPLE1
         Unit=(null)
Getpvl_Parm:EOFFound:ignore line and return Failure
[END DOCUMENT]
End Program

File2

/* this is a test file consisting of comments and a set

*/

        SET = {0, 1};

[BEGIN DOCUMENT]
   [LINE LISTING]
      Parameter=SET
      [ELEMENT]
         Class=Set
         MyLevel=1
         MyParent=0
         Value=(null)
         Unit=feet

      [NEXT ELEMENT]
         Class=Set
         MyLevel=2
         MyParent=1
         Value=0
         Unit=(null)

      [NEXT ELEMENT]
         Class=Simple
         MyLevel=3
         MyParent=1
         Value=1
         Unit=(null)
Getpvl_Parm:EOFFound:ignore line and return Failure
[END DOCUMENT]
End Program