From GridLAB-D Wiki
Jump to: navigation, search

link - Developer's guide to creating an application link DLL Template:NEW30

GridLAB-D developers can create application link modules by coding the interface in C++.

Three functions must be exported to support the interface:

EXPORT bool init(link *lnk)
This function is called during the initialization process and must return true for GridLAB-D to continue.
EXPORT TIMESTAMP sync(link *lnk,TIMESTAMP t0)
This function is called each time the global clock changes or GridLAB-D iterates (in which case the clock does not change). The function must return TS_ERROR to halt GridLAB-D, TS_NEVER to allow GridLAB-D to halt at steady state, a future time t1 > t0 to request a synchronization event at the time t1, or the time t0 to force GridLAB-D to iterate.
EXPORT bool term(link *lnk)
This function is called when the simulation is completed, either because of an error, because of steady state, or because the global clock has reached the stoptime.

C++ API

The following are defined in core/link.h.

link

The link class provides the complete specification and interface elements for an external application link.

LINKLIST *get_globals(void)
This function retrieves the first item in the list of globals.
GLOBALVAR *get_globalvar(LINKLIST *item)
Retrieves the item as a global variable.
LINKLIST *get_objects(void)
This function retrieves the first item in the list of objects.
OBJECT *get_object(LINKLIST *item)
Retrieves the item as an object.
LINKLIST *get_exports(void)
This function retrieves the first item in the list of variables to export.
OBJECTPROPERTY *get_export(LINKLIST *item)
Retrieves the item as an object property reference.
LINKLIST *get_imports(void)
This function retrieves the first item in the list of variables to import.
OBJECTPROPERTY *get_import(LINKLIST *item)
Retrieves the item as an object property reference.
char *get_name(LINKLIST *item)
This function is used to retrieve the name of an item.
char *get_next(LINKLIST *item)
This function is used to retrieve the next item in an item list.
char *get_data(LINKLIST *item)
This function is used to retrieve the GridLAB-D data associated with an item.
char *get_addr(LINKLIST *item)
This function is used to retrieve the address of the application data associated with an item.

LINKLIST

typedef struct s_linklist {
	char *name; // spec for link
	void *data; // local data
	void *addr; // remote data
	size_t size; // size of data
	size_t index; // index to data
	struct s_linklist *next;
} LINKLIST;

OBJECTPROPERTY

typedef struct {
	OBJECT *obj; // object reference
	PROPERTY *prop; // property reference
} OBJECTPROPERTY;
gld_property(OBJECT*,PROPERTY*);

This structure is used to pair objects and properties for import and export items.

The gld_property class is used to obtain values for the variable.

Includes

You will need to include the target application's API definition headers and the GridLAB-D API header:

#include <core/gridlabd.h>

Libraries

You will typically need to include the target application's runtime interface link libraries.

See also