These functions are extensions to the core PPVL library module.
int PPVL_selections ( PPVL_Parameter *The_Aggregate, PPVL_Parameter_Selections *The_Selections )
The_Aggregate
is searched for
named parameters and their values are put in internal variables.
Typically The_Aggregate
is obtained by the
PPVL_read_aggregate function.
The_Selections
refers to a list of
PPVL_Parameter_Selections
that controls
the mapping of PVL parameter values into application variables.
typedef struct { char *name; /* Name of parameter to find. */ PPVL_Type type; /* Data type of value expected. */ int count; /* Number of values sought. */ void *value; /* Location of value storage. */ } PPVL_Parameter_Selections;The
PPVL_Parameter_Selections
provide a generic way to
specify what to look
for in an aggregate
PPVL_Parameter
, and the program variables that will
store what is found. This is typically the linkage between the
external file
information structure and the internal program information structure.
The type
entry is one of the
PPVL_Type
values:
PPVL_TYPE_INTEGER - unsigned long PPVL_TYPE_REAL - double PPVL_TYPE_STRING - char *
The value
for the two numeric types is the address of an appropriate
variable (or array, or array member). If the variable has not been
typed the
same as the specific PPVL_Type
, then appropriate
casting may be necessary when
the variable is used. For strings, the variable used for the
value
is expected
to be typed as a string pointer (char**
).
Note: The original string from the parameter aggregate will not be copied so don't free the parameters until the strings are no longer needed or have been copied.
Parameters that are not found in The_Aggregate
result
in no change to the
value
storage for that parameter. So it may be
appropriate to initialize value
storage with a default value. However, the same value
storage may be referred
to by more than one parameter name in The_Selections
list, in which case the value of the last
parameter name found, if any, will be placed in the value storage.
It may be
desirable to initialize value
storage with a special
value that can be used to
indicate that no parameter was found for that variable.
Parameters that are found to have the specified name
but do not have the
specified type
will be silently ignored. However, the
same parameter name may
be listed more than once with a different specified type
(and possibly a
different value
storage reference).
Parameter values are stored in sequential value
storage
locations starting a
the value
storage address specified up to the
count
of values specified or the
number of values available, whichever is less. Since arrays of
parameter
values may have different types for each value, only the values of
the
specified type
are used.
Note: Don't forget to NULL
-terminate
The_Selections
list. This is easily done by
using PPVL_PARAMETER_SELECTIONS_END
as the last entry
in the list.
On success PPVL_SUCCESS
(0) is returned.
On failure a non-zero PPVL_errno
value is returned
and the global variable PPVL_selections_error
(a
PPVL_Parameter_Selections*
)
refers to the problem selection.
Note: The return value, and PPVL_errno
, will
be set to
PPVL_ERROR_ILLEGAL_SYNTAX
if an array type
is specified. The parameter selection in the list will be ignored and
processing will
continue. PPVL_selections_error
will be set to point to
this selection.
This condition is really just a warning and can be ignored
if desired.
PPVL_Parameter * PPVL_get_PDS_EOL ( FILE *The_File, PPVL_Parameter *The_Aggregate )Check for an EOL label at the end of the file's image data. If the EOL parameter is present in
The_Aggregate
, as well as all the
other parameters necessary to determine the location of the EOL
label after the end of the image data, then
The_File
is repositioned at the
beginning of the EOL label and it is read in as a new
PPVL_Parameter
aggregate. This new aggregate is renamed "EOL" and added to the end
of
The_Aggregate
.
On success a pointer to the EOL aggregate is returned. On failure a
NULL
is returned and the PPVL_errno
is set
accordingly. Any error from
the PPVL module is passed through. Possible error/warning conditions
are:
PPVL_ERROR_BAD_ARGUMENT
The_File
or
The_Aggregate
are NULL
.
PPVL_ERROR_EMPTY_STATEMENT
The_Aggregate
does not have an
EOL=1
parameter.
PPVL_ERROR_ILLEGAL_SYNTAX
The_Aggregate
is missing a necessary parameter.
PPVL_ERROR_READING_FILE
- The
EOL
label block could not be read from
the file.