Using Global Variables

Update this for

GridLAB-D supports dynamic definition of global variables. All of these are accessible through the core by any module at any time, and are exported to the output file as a group. These variables control output verbosity and output files, how many threads to use, how to output the results, the strictness of the global variable creation, various module states, etc.

= Using Global Variables = Global variables are created and accessed through GL_* functions. There is no particular constraint on what can be done with the global variables, but it is recommended to declare them in the module init functions, and explicitly link them to a static variable.

The GLOBALVAR struct should be considered opaque. It is much simpler and much more reliable to only use the struct as a handle for getting and setting the value within the variable.

GLOBALVAR *gl_global_create(char *name, …)
Explicitly creates and defines a global variable. The first argument is the name of the variable, which must be unique. The subsequent arguments must specify a PT_type as a second argument, then any arguments for that type, such as keywords, key values, and access types.

Example:

This will create an entry named myglobalname that is treated as a double, and will point to myglobalvar. PA_REFERENCE declares that the value should only be read through the global implementation. The last argument must always be NULL, or the function will behave aberrantly – so don’t skip it.

STATUS gl_global_setvar(char *name, …)
This function uses a character string to set the value of a global variable, then returns 0 if the value could not be set as specified, 1 if it could. The arguments either end up as one string in the form (“name=val”), or (“name”, “value”). In both cases, the value is written as a string.

Example:

This will set “myglobal” to 4.360.

Example:

This will fail, since the string input “camera” is nonsensical for a double value.

char *gl_global_getvar(char *name, char*value, int len)
This function will look for the most recently constructed variable published with name, and attempt to convert the contents into value (len chars long) with the value for the global variable. If value is null, a static buffer will be used. In either case, a pointer to the buffer holding the string representation of the global variable’s value will be returned on success, and NULL will be returned if the global variable could not be found, or if insufficient buffer space was available for the conversion.

GLOBALVAR *gl_global_find(char *name)
Looks for the global variable published as name and returns the first global variable with that name that was found, if any were.

= Using Module Variables =

Module-level variables use the global variable interface for construction and access. The significant difference is that the variables must be prefixed with the module name and two colons to associate them with a module within the code. Within model files, these variables can be set within the module property block. For example,

These module variables will be grouped underneath their modules within model dump XML files.

= Global Variable Access =