Module functions

Module functions - Required and optional module export functions

Synopsis

 * Required functions :

EXPORT CLASS *init(CALLBACKS *fntable, MODULE *module, int argc, char *argv[]); EXPORT void term(void); CDECL int do_kill;


 * Optional functions :

EXPORT int check; EXPORT int export(const char *file); EXPORT int import(const char *file); EXPORT int kmldump( int(*)(const char *file,...), OBJECT *obj); EXPORT void test(int argc, const char *argv[]); EXPORT size_t stream(void *ptr, size_t len, bool is_str=false, void *match==NULL);


 * Subsecond functions :

EXPORT unsigned long deltamode_desired(int *flags); EXPORT unsigned long preupdate(MODULE *module, TIMESTAMP t0, unsigned int64 dt); EXPORT SIMULATIONMODE interupdate(MODULE *module, TIMESTAMP t0, unsigned int64 delta_time, unsigned long dt, unsigned int iteration_count_val); EXPORT STATUS postupdate(MODULE *module, TIMESTAMP t0, unsigned int64 dt);

init
The init function is required for all GridLAB-D modules. It is called once when the module is loaded. The init should use this opportunity to register all classes and module globals. The template for this function as of is:

// module/main.cpp (init template) EXPORT CLASS *init(CALLBACKS *fntable, MODULE *module, int argc, char *argv[]) {  if (set_callback(fntable)==NULL) {    errno = EINVAL; return NULL; }  // TODO: add gl_global_create calls here (see module globals for details) // TODO: call new for each class here (see create class for details) return NULL; // TODO: return oclass member of first new class }
 * 1) define DLMAIN
 * 2) include 
 * 3) include "gridlabd.h"

do_kill
The do_kill function is required for all GridLAB-D modules. It is called when GridLAB-D terminates. The do_kill function should be used only to cleanup temporary files and memory allocation used by the module.

// module/main.cpp (do_kill template) CDECL int do_kill {  // TODO: perform cleanup actions if needed return 0; }
 * 1) define DLMAIN
 * 2) include 
 * 3) include "gridlabd.h"

term
The term function is called when the simulation stop (normally or on error).

// module/main.cpp (do_kill template) EXPORT void term(void) {  // TODO: perform simulation end operations }
 * 1) define DLMAIN
 * 2) include 
 * 3) include "gridlabd.h"

check
The check function is used to allow user to perform module checks before running a simulation. These can be used to verify model consistency, disk space available, and other verification procedures that are not always needed, but can be helpful in diagnosing problems.

// module/main.cpp (do_kill template) CDECL int check {  // TODO: perform check operations and report issues return 0; }
 * 1) define DLMAIN
 * 2) include 
 * 3) include "gridlabd.h"

export
The export function allows a module to define a method for exporting a GridLAB-D to an arbitrary file format. If defined, the export routine is called after the simulation is completed.


 * module/main.cpp

EXPORT int (*export)(const char *file) {  // your export code return count; // count of entities exported }

import
The import function is used to load a model from an arbitrary file format. The import GLM directive is used to initiative the import process.

EXPORT int import(const char *file) {  // import processing code return n; // n=0: failed; n<0: error after loading n entities; n>0: successfully loaded n entities }

kmldump
The kmldump function is used to output KML (Google Earth) data.

typedef int (*KMLOUT)(const char *format, ...); EXPORT int kmldump(KMLOUT kmlout, OBJECT *obj) {  kmlout("kml data"); return 0; // return value is ignored }

See Google KML Documentation for details on the KML format.

test
The test function is relatively unused and was intended to support module tests.

stream
The stream function will soon be required to support checkpoints.

Subsecond functions
See Dev:Subsecond for details.

Contingent functionalities
Modules may have runtime functionalities that are not always available, e.g., when an external application is not installed. In such cases, it is highly recommended that the module create a global flag variable only when the functionality is available. You can create a global variable in init, for example:

bool mytool_ok = false; if ( load_mytool ) {  mytool_ok = true; gl_create_global("module-name",PT_bool, &mytool,NULL); }

This will allow users to create GLM files that have contingent models depending on the presence of the external tools:

class ... object ...
 * 1) ifdef module-name
 * 1) endif

Some examples of contingent functionalities are MATLAB and MYSQL.


 * VS2005 : Often these functionalities are only supported when the proper libraries are installed on the build machine. These modules usually have a special flag set, e.g., HAVE_MYSQL or HAVE_MATLAB so that Linux/Mac machine can automatically build the proper code based on what is installed.  In Windows this is not possible.  If the libraries are not available, we recommend you unload the project and not build it rather than changing the flag.

Version

 * Prior to : The implementation functions and file structures are different and deprecated.