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.