Objects

Detailed Description

Object functions support object operations.

Objects have two parts, an OBJECTHDR block followed by an OBJECTDATA block. The OBJECTHDR contains all the common object information, such as it's id and clock. The OBJECTDATA contains all the data implemented by the module that created the object.

    OBJECTHDR       size                        size of the OBJECTDATA block
                    id                          unique id of the object
                    oclass                      class the implements the OBJECTDATA
                    next                        pointer to the next OBJECTHDR
                    parent                      pointer to parent's OBJECTHDR
                    rank                        object's rank (less than parent's rank)
                    clock                       object's sync clock
                    latitude, longitude         object's geo-coordinates
                    in_svc, out_svc             object's activation/deactivation dates
                    flags                       object flags (e.g., external PLC active)
    OBJECTDATA      (varies; defined by oclass)

Classes

struct s_namespace

Full object name (including space name). More...

Defines

#define GETADDR(O, P)   (O?((void*)((char*)(O+1)+(unsigned int64)((P)->addr))):NULL)

get the addr of an object's property

#define MYPARENT   ((((OBJECT*)this)-1)->parent)

get the parent from the object's data structure

#define object_id(X)   ((X)?(X)->id:-1)

get the id of the object X

#define object_parent(X)   ((X)?(X)->parent:NULL)

get the parent of the object

#define object_rank(X)   ((X)?(X)->name:-1)

get the rank of the object

#define object_size(X)   ((X)?(X)->size:-1)

get the size of the object X

#define OBJECTDATA(X, T)   ((T*)((X)?((X)+1):NULL))

get the object data structure

#define OBJECTHDR(X)   ((X)?(((OBJECT*)X)-1):NULL)

get the header from the object's data structure

#define OF_FOREIGN   0x0010

Object flag; indicates that object was created in a DLL and memory cannot be freed by core.

#define OF_HASPLC   0x0001

Object flag; external PLC is attached, disables local PLC.

#define OF_LOCKED   0x0002

Object flag; data write pending, reread recommended after lock clears.

#define OF_NONE   0x0000

Full object name (including space name).

#define OF_RECALC   0x0008

Object flag; recalculation of derived values is needed.

#define OF_RERANK   0x4000

Internal use only.

#define OF_SKIPSAFE   0x0020

Object flag; indicates that skipping updates is safe.

#define QNAN   sqrt(-1)

NaN quantity.

Typedefs

typedef struct s_callbacks CALLBACKS

core callback function table

typedef char FULLNAME [1024]

Object name.

typedef struct s_object_list OBJECT

Object header structure.

typedef char * OBJECTNAME

Object id number.

typedef unsigned int OBJECTNUM

Object data size.

typedef unsigned int OBJECTRANK

Object rank number.

Functions

TIMESTAMP _object_sync (OBJECT *obj, TIMESTAMP ts, PASSCONFIG pass)

int object_build_object_array ()

This will build (or rebuild) an array with all the instantiated GridLab-D objects placed at indices that correspond to their internal object ID.

int object_close_namespace ()

Closes the current namespace.

OBJECT * object_create_array (CLASS *oclass, unsigned int n_objects)

Create multiple objects.

OBJECT * object_create_foreign (OBJECT *obj)

Create a foreign object.

OBJECT * object_create_single (CLASS *oclass)

Create a single object.

NAMESPACE * object_current_namespace ()

Get the current namespace.

int object_dump (char *outbuffer, int size, OBJECT *obj)

Dump an object to a buffer.

OBJECT * object_find_by_id (OBJECTNUM id)

Find an object by its id number.

OBJECT * object_find_name (OBJECTNAME name)

Find an object from a name.

void * object_get_addr (OBJECT *obj, char *name)

Get the address of a property value.

unsigned int object_get_count ()

Get the number of objects defined.

OBJECT * object_get_first ()

Get the first object in the model.

int object_get_namespace (OBJECT *obj, char *buffer, int size)

Get full namespace of object's space.

OBJECT * object_get_next (OBJECT *obj)

Get the next object in the model.

PROPERTY * object_get_property (OBJECT *obj, PROPERTYNAME name)

Get a named property of an object.

OBJECT * object_get_reference (OBJECT *obj, char *name)

Get a reference to another object.

char * object_get_unit (OBJECT *obj, char *name)

Get the unit of an object, if any.

int object_get_value_by_addr (OBJECT *obj, void *addr, char *value, int size, PROPERTY *prop)

Get a property value by reference to its physical address.

int object_get_value_by_name (OBJECT *obj, PROPERTYNAME name, char *value, int size)

Get a value by reference to its property name.

int object_init (OBJECT *obj)

Initialize an object.

int object_isa (OBJECT *obj, char *type)

Tests the type of an object.

int object_locate_property (void *addr, OBJECT **pObj, PROPERTY **pProp)

Locate the object and property corresponding the address of data.

char * object_name (OBJECT *obj)

Get the name of an object.

void object_namespace (char *buffer, int size)

Get the full namespace of current space.

int object_open_namespace (char *space)

Opens a new namespace within the current name space.

NAMESPACE * object_pop_namespace ()

restore the previous namespace from stack

int object_push_namespace (char *space)

change to another namespace and push the one onto a stack

OBJECT * object_remove_by_id (OBJECTNUM id)

Removes a single object.

int object_saveall (FILE *fp)

Save all the objects in the model to the stream fp in the .GLM format.

int object_saveall_xml (FILE *fp)

Save all the objects in the model to the stream fp in the .XML format.

int object_saveall_xml_old (FILE *fp)

int object_select_namespace (char *space)

Makes the namespace active.

int object_set_dependent (OBJECT *obj, OBJECT *dependent)

Set the dependent of an object.

OBJECTNAME object_set_name (OBJECT *obj, OBJECTNAME name)

Sets the name of an object.

int object_set_parent (OBJECT *obj, OBJECT *parent)

Set the parent of an object.

int object_set_rank (OBJECT *obj, OBJECTRANK rank)

Set the rank of an object but forcing it's parent to increase rank if necessary.

int object_set_value_by_addr (OBJECT *obj, void *addr, char *value, PROPERTY *prop)

Set a property value by reference to its physical address.

int object_set_value_by_name (OBJECT *obj, PROPERTYNAME name, char *value)

Set a property value by reference to its name.

TIMESTAMP object_sync (OBJECT *obj, TIMESTAMP ts, PASSCONFIG pass)

Synchronize an object.

void remove_objects ()

Convenience method use by the testing framework.

Define Documentation

#define OF_NONE 0x0000

Full object name (including space name).

Object flag; none set

Definition at line 29 of file object.h.

Referenced by object_create_single().

Function Documentation

TIMESTAMP _object_sync	(	OBJECT *	obj,
		TIMESTAMP	ts,
		PASSCONFIG	pass
	)

Parameters:

obj	the object to synchronize
ts	the desire clock to sync to
pass	the pass configuration

Definition at line 1160 of file object.c.

References convert_from_timestamp(), min, object_name(), OF_HASPLC, OF_RECALC, OF_SKIPSAFE, output_fatal(), PC_BOTTOMUP, PC_POSTTOPDOWN, and PC_PRETOPDOWN.

Referenced by object_sync().

int object_build_object_array ( )

This will build (or rebuild) an array with all the instantiated GridLab-D objects placed at indices that correspond to their internal object ID.

Returns:: the number of objects instantiated when the call was made

Definition at line 130 of file object.c.

References object_get_count(), and object_get_first().

Referenced by object_find_by_id().

int object_close_namespace ( )

Closes the current namespace.

close the current namespace and restore the previous one

Returns:: 1 on success, 0 on failure

Definition at line 2042 of file object.c.

References s_namespace::next, and throw_exception().

OBJECT * object_create_array	(	CLASS *	oclass,
		unsigned int	n_objects
	)

Create multiple objects.

Returns:: Same as create_single, but returns the first object created.

Parameters:

oclass

a pointer to the CLASS structure

Definition at line 376 of file object.c.

References object_create_single().

OBJECT * object_create_foreign ( OBJECT * obj )

Create a foreign object.

Returns:

a pointer to object header, NULL of error, set errno as follows:

EINVAL type is not valid
ENOMEM memory allocation failed

To use this function you must set obj->oclass before calling. All other properties will be cleared and you must set them after the call is completed.

Definition at line 314 of file object.c.

References OF_FOREIGN, and throw_exception().

OBJECT * object_create_single ( CLASS * oclass )

Create a single object.

Returns:

a pointer to object header, NULL of error, set errno as follows:

EINVAL type is not valid
ENOMEM memory allocation failed

Definition at line 242 of file object.c.

References int64, object_current_namespace(), OF_NONE, and throw_exception().

Referenced by object_create_array().

NAMESPACE * object_current_namespace ( )

Get the current namespace.

access the current namespace

Returns:: pointer to namespace or NULL is global

Definition at line 2014 of file object.c.

Referenced by convert_from_object(), and object_create_single().

int object_dump	(	char *	outbuffer,
		int	size,
		OBJECT *	obj
	)

Dump an object to a buffer.

Returns:: the number of characters written to the buffer

Parameters:

outbuffer	the destination buffer
size	the size of the buffer

Definition at line 1289 of file object.c.

References class_get_property_typename(), convert_from_set(), convert_from_timestamp(), FMT_INT64, output_error(), PT_delegated, and throw_exception().

Referenced by exec_debug(), and exec_debug_cmd().

OBJECT * object_find_by_id ( OBJECTNUM id )

Find an object by its id number.

Returns:: a pointer the object

Definition at line 171 of file object.c.

References object_build_object_array(), and object_get_count().

Referenced by convert_to_object(), and object_remove_by_id().

OBJECT * object_find_name ( OBJECTNAME name )

Find an object from a name.

This only works for named objects. See object_set_name().

Returns:: a pointer to the OBJECT structure

Definition at line 1867 of file object.c.

Referenced by convert_to_object(), exec_debug_cmd(), and object_set_name().

void * object_get_addr	(	OBJECT *	obj,
		char *	name
	)

Get the address of a property value.

Returns:: void pointer to the data; NULL is not found

Parameters:

obj

object to look in

Definition at line 426 of file object.c.

References class_find_property(), int64, and PA_PRIVATE.

unsigned int object_get_count ( )

Get the number of objects defined.

Returns:: the number of objects in the model

Definition at line 104 of file object.c.

Referenced by class_profiles(), exec_start(), find_objects(), loadall(), loadall_glm(), loadall_glm_roll(), object_build_object_array(), and object_find_by_id().

OBJECT * object_get_first ( )

Get the first object in the model.

Returns:: a pointer to the first OBJECT

Definition at line 1029 of file object.c.

Referenced by exec_debug_cmd(), find_next(), find_objects(), loadall_glm(), loadall_glm_roll(), module_saveobj_xml(), and object_build_object_array().

int object_get_namespace	(	OBJECT *	obj,
		char *	buffer,
		int	size
	)

Get full namespace of object's space.

get the object's namespace

Returns:: 1 if in subspace, 0 if global namespace

Definition at line 2004 of file object.c.

Referenced by convert_from_object().

OBJECT * object_get_next ( OBJECT * obj )

Get the next object in the model.

Returns:: a pointer to the OBJECT after obj

Definition at line 1037 of file object.c.

PROPERTY * object_get_property	(	OBJECT *	obj,
		PROPERTYNAME	name
	)

Get a named property of an object.

Note that you must use object_get_value_by_name to retrieve the value of the property.

Returns:: a pointer to the PROPERTY structure

Parameters:

obj

a pointer to the object

Definition at line 116 of file object.c.

References class_find_property().

Referenced by cmex_set(), exec_debug_cmd(), and object_get_unit().

int object_get_value_by_addr	(	OBJECT *	obj,
		void *	addr,
		char *	value,
		int	size,
		PROPERTY *	prop
	)

Get a property value by reference to its physical address.

Returns:: the number of characters written to the buffer; 0 if failed

Parameters:

obj	the object from which to get the data
addr	the addr of the data to get
value	the buffer to which to write the result
size	the size of the buffer
prop	the property to use or NULL if unknown

Definition at line 981 of file object.c.

References class_property_to_string(), output_error(), and PA_PRIVATE.

int object_get_value_by_name	(	OBJECT *	obj,
		PROPERTYNAME	name,
		char *	value,
		int	size
	)

Get a value by reference to its property name.

Returns:: the number of characters written to the buffer; 0 if failed

Definition at line 1001 of file object.c.

int object_init ( OBJECT * obj )

Initialize an object.

This should not be called until all objects that are needed are created

Returns:: 1 on success; 0 on failure

Definition at line 1259 of file object.c.

int object_isa	(	OBJECT *	obj,
		char *	type
	)

Tests the type of an object.

Parameters:

obj

the object to test

Definition at line 1275 of file object.c.

int object_locate_property	(	void *	addr,
		OBJECT **	pObj,
		PROPERTY **	pProp
	)

Locate the object and property corresponding the address of data.

Returns:: 1 on success, 0 on failure Sets the pointers to the object and the property that matches

Definition at line 2070 of file object.c.

References int64.

char * object_name ( OBJECT * obj )

Get the name of an object.

Note that this function uses a static buffer that must be used immediately. Subsequent calls will reuse the same buffer.

Returns:: a pointer to the object name string

Definition at line 203 of file object.c.

References convert_from_object().

Referenced by _object_sync(), cmex_object_list(), exec_debug(), exec_test(), object_get_unit(), and object_set_parent().

void object_namespace	(	char *	buffer,
		int	size
	)

Get the full namespace of current space.

get the namespace

Returns:: the full namespace spec

Definition at line 1995 of file object.c.

Referenced by exec_debug_cmd().

int object_open_namespace ( char * space )

Opens a new namespace within the current name space.

open a new namespace and make it current

Returns:: 1 on success, 0 on failure

Definition at line 2022 of file object.c.

References s_namespace::name, s_namespace::next, and throw_exception().

OBJECT * object_remove_by_id ( OBJECTNUM id )

Removes a single object.

Returns:: Returns the object after the one that was removed.

Definition at line 395 of file object.c.

References object_find_by_id().

int object_saveall ( FILE * fp )

Save all the objects in the model to the stream fp in the .GLM format.

Returns:: the number of bytes written, 0 on error, with errno set.

Parameters:

fp	the stream to write to

Definition at line 1373 of file object.c.

References convert_from_object(), convert_from_set(), and convert_from_timestamp().

int object_saveall_xml ( FILE * fp )

Save all the objects in the model to the stream fp in the .XML format.

Returns:: the number of bytes written, 0 on error, with errno set.

Definition at line 1423 of file object.c.

References convert_from_object(), and convert_from_timestamp().

int object_saveall_xml_old ( FILE * fp )

< the stream to write to

Definition at line 1485 of file object.c.

References convert_from_object(), and convert_from_timestamp().

int object_select_namespace ( char * space )

Makes the namespace active.

change to another namespace

Returns:: 1 on success, 0 on failure

Definition at line 2060 of file object.c.

References output_error().

Referenced by exec_debug_cmd().

int object_set_dependent	(	OBJECT *	obj,
		OBJECT *	dependent
	)

Set the dependent of an object.

This increases to the rank as though the parent was set, but does not affect the parent.

Returns:: the rank of the object after the dependency was set

Parameters:

obj	the object to set
dependent	the dependent object

Definition at line 1122 of file object.c.

OBJECTNAME object_set_name	(	OBJECT *	obj,
		OBJECTNAME	name
	)

Sets the name of an object.

This is useful if the internal name cannot be relied upon, as when multiple modules are being used. Throws an exception when a memory error occurs or when the name is already taken by another object.

Definition at line 1917 of file object.c.

References object_find_name(), output_error(), and output_warning().

int object_set_parent	(	OBJECT *	obj,
		OBJECT *	parent
	)

Set the parent of an object.

Returns:: the rank of the object after parent was set

Parameters:

obj	the object to set
parent	the new parent of the object

Definition at line 1104 of file object.c.

References object_name(), and output_error().

Referenced by loadall_glm(), and loadall_glm_roll().

int object_set_rank	(	OBJECT *	obj,
		OBJECTRANK	rank
	)

Set the rank of an object but forcing it's parent to increase rank if necessary.

Returns:: object rank; -1 if failed

Parameters:

obj	the object to set
rank	the object

Definition at line 1090 of file object.c.

int object_set_value_by_addr	(	OBJECT *	obj,
		void *	addr,
		char *	value,
		PROPERTY *	prop
	)

Set a property value by reference to its physical address.

Returns:: the character written to the buffer

Parameters:

obj	the object to alter
addr	the address of the property
value	the value to set
prop	the property to use or NULL if unknown

Definition at line 654 of file object.c.

References class_string_to_property(), NM_POSTUPDATE, NM_PREUPDATE, OF_RECALC, output_error(), PA_PUBLIC, and PF_RECALC.

Referenced by object_set_value_by_name().

int object_set_value_by_name	(	OBJECT *	obj,
		PROPERTYNAME	name,
		char *	value
	)

Set a property value by reference to its name.

Returns:: the number of characters written to the buffer

Parameters:

obj	the object to change
name	the name of the property to change
value	the value to set

Definition at line 842 of file object.c.

References class_find_property(), int64, object_set_value_by_addr(), output_error(), and PA_PUBLIC.

Referenced by cmex_create(), cmex_set(), and exec_debug_cmd().

TIMESTAMP object_sync	(	OBJECT *	obj,
		TIMESTAMP	ts,
		PASSCONFIG	pass
	)

Synchronize an object.

The timestamp given is the desired increment.

If an object is called on multiple passes (see PASSCONFIG) it is customary to update the clock only after the last pass is completed.

For the sake of speed this function assumes that the sync function is properly defined in the object class structure.

Returns:: the time of the next event for this object.

Parameters:

obj	the object to synchronize
ts	the desire clock to sync to
pass	the pass configuration

Definition at line 1242 of file object.c.

References _object_sync().

Referenced by exec_debug(), and exec_test().

void remove_objects ( void )

Convenience method use by the testing framework.

This should only be exposed there.

Definition at line 1959 of file object.c.


Classes
struct	s_namespace
	Full object name (including space name). More...
Defines
#define	GETADDR(O, P) (O?((void)((char)(O+1)+(unsigned int64)((P)->addr))):NULL)
	get the addr of an object's property
#define	MYPARENT ((((OBJECT*)this)-1)->parent)
	get the parent from the object's data structure
#define	object_id(X) ((X)?(X)->id:-1)
	get the id of the object X
#define	object_parent(X) ((X)?(X)->parent:NULL)
	get the parent of the object
#define	object_rank(X) ((X)?(X)->name:-1)
	get the rank of the object
#define	object_size(X) ((X)?(X)->size:-1)
	get the size of the object X
#define	OBJECTDATA(X, T) ((T*)((X)?((X)+1):NULL))
	get the object data structure
#define	OBJECTHDR(X) ((X)?(((OBJECT*)X)-1):NULL)
	get the header from the object's data structure
#define	OF_FOREIGN 0x0010
	Object flag; indicates that object was created in a DLL and memory cannot be freed by core.
#define	OF_HASPLC 0x0001
	Object flag; external PLC is attached, disables local PLC.
#define	OF_LOCKED 0x0002
	Object flag; data write pending, reread recommended after lock clears.
#define	OF_NONE 0x0000
	Full object name (including space name).
#define	OF_RECALC 0x0008
	Object flag; recalculation of derived values is needed.
#define	OF_RERANK 0x4000
	Internal use only.
#define	OF_SKIPSAFE 0x0020
	Object flag; indicates that skipping updates is safe.
#define	QNAN sqrt(-1)
	NaN quantity.
Typedefs
typedef struct s_callbacks	CALLBACKS
	core callback function table
typedef char	FULLNAME [1024]
	Object name.
typedef struct s_object_list	OBJECT
	Object header structure.
typedef char *	OBJECTNAME
	Object id number.
typedef unsigned int	OBJECTNUM
	Object data size.
typedef unsigned int	OBJECTRANK
	Object rank number.
Functions
TIMESTAMP	_object_sync (OBJECT *obj, TIMESTAMP ts, PASSCONFIG pass)
int	object_build_object_array ()
	This will build (or rebuild) an array with all the instantiated GridLab-D objects placed at indices that correspond to their internal object ID.
int	object_close_namespace ()
	Closes the current namespace.
OBJECT *	object_create_array (CLASS *oclass, unsigned int n_objects)
	Create multiple objects.
OBJECT *	object_create_foreign (OBJECT *obj)
	Create a foreign object.
OBJECT *	object_create_single (CLASS *oclass)
	Create a single object.
NAMESPACE *	object_current_namespace ()
	Get the current namespace.
int	object_dump (char outbuffer, int size, OBJECT obj)
	Dump an object to a buffer.
OBJECT *	object_find_by_id (OBJECTNUM id)
	Find an object by its id number.
OBJECT *	object_find_name (OBJECTNAME name)
	Find an object from a name.
void *	object_get_addr (OBJECT obj, char name)
	Get the address of a property value.
unsigned int	object_get_count ()
	Get the number of objects defined.
OBJECT *	object_get_first ()
	Get the first object in the model.
int	object_get_namespace (OBJECT obj, char buffer, int size)
	Get full namespace of object's space.
OBJECT *	object_get_next (OBJECT *obj)
	Get the next object in the model.
PROPERTY *	object_get_property (OBJECT *obj, PROPERTYNAME name)
	Get a named property of an object.
OBJECT *	object_get_reference (OBJECT obj, char name)
	Get a reference to another object.
char *	object_get_unit (OBJECT obj, char name)
	Get the unit of an object, if any.
int	object_get_value_by_addr (OBJECT obj, void addr, char value, int size, PROPERTY prop)
	Get a property value by reference to its physical address.
int	object_get_value_by_name (OBJECT obj, PROPERTYNAME name, char value, int size)
	Get a value by reference to its property name.
int	object_init (OBJECT *obj)
	Initialize an object.
int	object_isa (OBJECT obj, char type)
	Tests the type of an object.
int	object_locate_property (void addr, OBJECT pObj, PROPERTY *pProp)
	Locate the object and property corresponding the address of data.
char *	object_name (OBJECT *obj)
	Get the name of an object.
void	object_namespace (char *buffer, int size)
	Get the full namespace of current space.
int	object_open_namespace (char *space)
	Opens a new namespace within the current name space.
NAMESPACE *	object_pop_namespace ()
	restore the previous namespace from stack
int	object_push_namespace (char *space)
	change to another namespace and push the one onto a stack
OBJECT *	object_remove_by_id (OBJECTNUM id)
	Removes a single object.
int	object_saveall (FILE *fp)
	Save all the objects in the model to the stream `fp` in the .GLM format.
int	object_saveall_xml (FILE *fp)
	Save all the objects in the model to the stream `fp` in the .XML format.
int	object_saveall_xml_old (FILE *fp)
int	object_select_namespace (char *space)
	Makes the namespace active.
int	object_set_dependent (OBJECT obj, OBJECT dependent)
	Set the dependent of an object.
OBJECTNAME	object_set_name (OBJECT *obj, OBJECTNAME name)
	Sets the name of an object.
int	object_set_parent (OBJECT obj, OBJECT parent)
	Set the parent of an object.
int	object_set_rank (OBJECT *obj, OBJECTRANK rank)
	Set the rank of an object but forcing it's parent to increase rank if necessary.
int	object_set_value_by_addr (OBJECT obj, void addr, char value, PROPERTY prop)
	Set a property value by reference to its physical address.
int	object_set_value_by_name (OBJECT obj, PROPERTYNAME name, char value)
	Set a property value by reference to its name.
TIMESTAMP	object_sync (OBJECT *obj, TIMESTAMP ts, PASSCONFIG pass)
	Synchronize an object.
void	remove_objects ()
	Convenience method use by the testing framework.