Option Lists or Optlists
Many Silo functions take as a last argument a pointer to an Options List or optlist. This is intended to permit the Silo API to grow and evolve as necessary without requiring substantial changes to the API itself.
In the documentation associated with each function, the list of available options and their meaning is described.
This section of the manual describes only the functions to create and manage options lists.
A Common Coding Gotcha
Tip
Take care regarding memory used in a DBoptlist
object.
A number of developers have encountered problems using Silo’s option lists.
Many times, problems arise from the use of local scoped variables in a DBoptlist
object being used outside of that local scope.
The problematic coding looks as follows…
AddCycleAndTime(DBoptlist *ol)
{
int cycle = GetCycle();
double time = GetTime();
DBAddOption(ol, DBOPT_CYCLE, &cycle);
DBAddOption(ol, DBOPT_DTIME, &time);
return ol;
}
The problem with the above code is the contents of a DBoptlist
object are interrogated only at the time the object is used in a Silo DBPutXxxx()
call.
This means the optlist’s contents need to remain valid until the last DBPutXxxx()
call in which they are used.
In the example here, the DBAddOption()
calls are adding pointers to variables that are local to AddCycleAndTime()
.
Those memory locations are not valid outside of that function.
When the optlist is used in a Silo call such as DBPutUcdmesh()
, it will result in garbage data being written for cycle
and time
.
DBMakeOptlist()
Summary: Allocate an option list.
C Signature:
DBoptlist *DBMakeOptlist (int maxopts)
Fortran Signature:
integer function dbmkoptlist(maxopts, optlist_id)
returns created optlist pointer-id in optlist_id
Arguments:
Arg name
Description
maxopts
Initial maximum number of options expected in the optlist. If this maximum is exceeded, the library will silently re-allocate more space using the golden-rule.
Returned value:
DBMakeOptlist returns a pointer to an option list on success and
NULL
on failure.Description:
The
DBMakeOptlist
function allocates memory for an option list and initializes it. Use the functionDBAddOption
to populate the option list structure, andDBFreeOptlist
to free it.
Deprecated since version 4.10: In releases of Silo prior to 4.10, if the caller accidentally added more options to an optlist than it was originally created for, an error would be generated.
New in version 4.10: However, in version 4.10, the library will silently just re-allocate the optlist to accommodate more options.
DBAddOption()
Summary: Add an option to an option list.
C Signature:
int DBAddOption (DBoptlist *optlist, int option, void *value)
Fortran Signature:
integer function dbaddcopt (optlist_id, option, cvalue, lcvalue) integer function dbaddcaopt (optlist_id, option, nval, cvalue, lcvalue) integer function dbadddopt (optlist_id, option, dvalue) integer function dbaddiopt (optlist_id, option, ivalue) integer function dbaddropt (optlist_id, option, rvalue) integer ivalue, optlist_id, option, lcvalue, nval double precision dvalue real rvalue character*N cvalue (See [`dbset2dstrlen`](./fortran.md#dbset2dstrlen).)
Arguments:
Arg name
Description
optlist
Pointer to an
option
list structure containing option/value pairs. This structure is created with theDBMakeOptlist
function.option
Option definition. One of the predefined values described in the table in the notes section of each command which accepts an
option
list.value
Pointer to the
value
associated with the providedoption
description. The data type is implied byoption
. The pointer must remain valid through the last call in which the optlist is used.Returned value:
DBAddOption returns a zero on success and -1 on failure.
Description:
The
DBAddOption
function adds an option/value pair to anoption
list. Several of the output functions acceptoption
lists to provide information of an optional nature.
Deprecated since version 4.10: In releases of Silo prior to 4.10, if the caller accidentally added more options to an optlist than it was originally created for, an error would be generated.
New in version 4.10: However, in version 4.10, the library will silently just re-allocate the optlist to accommodate more options.
DBClearOption()
Summary: Remove an option from an option list
C Signature:
int DBClearOption(DBoptlist *optlist, int optid)
Fortran Signature:
None
Arguments:
Arg name
Description
optlist
The option list object for which you wish to remove an option
optid
The option id of the option you would like to remove
Returned value:
DBClearOption returns zero on success and -1 on failure.
Description:
This function can be used to remove options from an option list. If the option specified by
optid
exists in the given option list, that option is removed from the list and the total number of options in the list is reduced by one.This method can be used together with
DBAddOption
to modify an existing option in an option list. To modify an existing option in an option list, first callDBClearOption
for the option to be modified and then callDBAddOption
to re-add it with a new definition.There is also a function to query for the value of an option in an option list,
DBGetOption
.
DBGetOption()
Summary: Retrieve the value set for an option in an option list
C Signature:
void *DBGetOption(DBoptlist *optlist, int optid)
Fortran Signature:
None
Arguments:
Arg name
Description
optlist
The
optlist
to queryoptid
The option id to query the value for
Returned value:
Returns the pointer value set for a given option or
NULL
if the option is not defined in the given option list.Description:
This function can be used to query the contents of an
optlist
. If the givenoptlist
has an option of the given optid, then this function will return the pointer associated with the givenoptid
. Otherwise, it will returnNULL
indicating theoptlist
does not contain an option with the givenoptid
.
DBFreeOptlist()
Summary: Free memory associated with an option list.
C Signature:
int DBFreeOptlist (DBoptlist *optlist)
Fortran Signature:
integer function dbfreeoptlist(optlist_id)
Arguments:
Arg name
Description
optlist
Pointer to an option list structure containing option/value pairs. This structure is created with the
DBMakeOptlist
function.Returned value:
DBFreeOptlist returns a zero on success and -1 on failure.
Description:
The
DBFreeOptlist
function releases the memory associated with the given option list.
Tip
The individual option value pointers are not freed.
DBFreeOptlist will not fail if a NULL
pointer is passed to it.
DBClearOptlist()
Summary: Clear an optlist.
C Signature:
int DBClearOptlist (DBoptlist *optlist)
Fortran Signature:
None
Arguments:
Arg name
Description
optlist
Pointer to an option list structure containing option/value pairs. This structure is created with the
DBMakeOptlist
function.Returned value:
DBClearOptlist returns zero on success and -1 on failure.
Description:
The
DBClearOptlist
function removes all options from the given option list.