Extension Functions

These functions are extensions to the core PPVL library module.


        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. */
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 *
        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:
Either The_File or The_Aggregate are NULL.
The_Aggregate does not have an EOL=1 parameter.
The_Aggregate is missing a necessary parameter.
The EOL label block could not be read from the file.