Tag Access

This group contains functions for getting and setting data tag values, querying a list of all data tags present in the drawing, as well as exporting and importing data tags. More...

Detailed Description

This group contains functions for getting and setting data tag values, querying a list of all data tags present in the drawing, as well as exporting and importing data tags.

Functions
GlgObject	GlgCreateTagList (GlgObject object, GlgBoolean unique_tag_sources)
	Creates and returns a list of data tags defined in the drawing. More...
GlgLong	GlgExportTags (GlgObject object, char *filename, GlgLong separator1, GlgLong separator2)
	Writes tag names and tag sources of all data tags defined in a drawing to a tag translation file. More...
GlgBoolean	GlgGetDTag (GlgObject object, char *tag_source, double *value)
	Returns the current value of a D (double) tag. More...
GlgBoolean	GlgGetGTag (GlgObject object, char *tag_source, double *x_value, double *y_value, double *z_value)
	Returns the current value of a G (geometrical or color) tag. More...
GlgBoolean	GlgGetSTag (GlgObject object, char *tag_source, char **value)
	Returns the current value of a S (string) tag. More...
GlgBoolean	GlgHasTagName (GlgObject object, char *tag_source)
	Checks if a data tag with a specified tag name exists. More...
GlgBoolean	GlgHasTagSource (GlgObject object, char *tag_source)
	Checks if a data tag with a specified tag source exists. More...
GlgLong	GlgImportTags (GlgObject object, char *filename, GlgBoolean verbose)
	Replaces the TagName and TagSource attributes of the data tags in a drawing with information loaded from a tag translation file. More...
GlgBoolean	GlgSetDTag (GlgObject object, char *tag_source, double value, GlgBoolean if_changed)
	Sets a new value of a D (double) tag. More...
GlgBoolean	GlgSetGTag (GlgObject object, char *tag_source, double x_value, double y_value, double z_value, GlgBoolean if_changed)
	Sets new values of a G (geometrical or color) tag. More...
GlgBoolean	GlgSetSTag (GlgObject object, char *tag_source, char *value, GlgBoolean if_changed)
	Replaces the string of an S (string) tag. More...
GlgBoolean	GlgSetSTagFromD (GlgObject object, char *tag_source, char *format, double value, GlgBoolean if_changed)
	Replaces the string of an S (string) tag with a value specified by an input number and a format string. More...

Function Documentation

GlgCreateTagList()

GlgObject GlgCreateTagList	(	GlgObject	object,
		GlgBoolean	unique_tag_sources
	)

Creates and returns a list of data tags defined in the drawing.

Parameters

object	An object whose tags are queried. The top level viewport may be used to query the list of tags of the whole drawing.
unique_tag_sources	If True, only the first encountered tag of the highest priority will be added to the list for tags with the same tag source. Input tags are prioritized over output tags, and enabled tags over disabled tags. If False, all instances with the same tag source will be included.

Returns

A group containing all data tag objects, or NULL if no tags were found. The returned group object must be dereferenced using GlgDropObject when it is no longer needed.

Each element of the returned group is an attribute object that has a data tag attached. The GlgGetElement and GlgGetSize functions of the Intermediate API may be used within the Standard API to handle the returned group object.

If object is not a viewport, the returned tag list will include only the tags contained inside the object. For a viewport, the tag list will contain all tags defined in the viewport's drawing.

Example

The following code prints information about all tags defined in the drawing:

char * tag_name, * tag_source;
 
// Query list of tags defined in the drawing.
GlgObject tag_list = GlgCreateTagList( viewport, False );
if( tag_list )
{
   int size = GlgGetSize( tag_list );
   for( int i=0; i<size; ++i )
   {
      // Query TagName and TagSource of each tag.
      GlgObject tag_object = GlgGetElement( tag_list, i );
      GlgGetSResource( tag_object, "TagName", &tag_name );
      GlgGetSResource( tag_object, "TagSource", &tag_source );
      printf( "TagName: %s, TagSource: %s\n", tag_name, tag_source );
   }
   // Free the tag list.
   GlgGropObject( tag_list );
}

Tag Access Performance Optimization

Since tags returned by GlgCreateTagList are actually data objects the tags are attached to, their object IDs may be stored and then used repeatedly to optimized tag access performance when tags are used to supply data for a drawing with large number of tags.

Instead of setting new tag values with GlgSetDTag:

GlgSetDTag( viewport, tag_source, new_value, True );

the stored object IDs may be used with the the GlgSetDResource function using NULL as the resource_name parameter to set a new value of each data object directly without an overhead of searching the drawing for each tag by its TagSource:

GlgSetDResourceIf( tag_object, NULL, new_value, True );

The GlgAddDataSampleNode function of the Intermediate API can also be used instead of setting values of chart entry points to prefill a chart with a large number of data samples.

The GlgGetTagObject and GlgQueryTags functions of the Intermediate API provide extended functionality for querying both data and export tags.

GlgExportTags()

GlgLong GlgExportTags	(	GlgObject	object,
		char *	filename,
		GlgLong	separator1,
		GlgLong	separator2
	)

Writes tag names and tag sources of all data tags defined in a drawing to a tag translation file.

Parameters

object	Specifies a viewport or an object whose tags to export.
filename	Specifies the filename of the tag translation file.
separator1	Defines the first separator character to be used in the generated file.
separator2	Defines the second separator character to be used in the generated file.

Returns

The number of exported tags or -1 in case of an error.

This function exports all data tags defined in the drawing to an ASCII tag file that can be edited using a text editor.

Each tag entry contains two copies of the tag's TagName and TagSource attributes separated by two separator characters. The first copy of the TagName and TagSource attributes contains the current values. It is used to identify the tag and should not be changed.

The second copy of the attributes contains new values that may be changed to modify the tag. The new value of the TagSource attribute supplies the data source variable associated with the tag. Tag names can also be localized by translating new values of the TagName attributes to different languages.

The file can be edited to modify new values, and then imported into the drawing using GlgImportTags.

This makes it possible to use the drawing as a template, and modify it on the fly to use a different set of tags. This technique may be used to create a single drawing, and then use it at run time to display different sections of a plant or different rooms of a data center. Alternatively, tag remapping may also be done programmatically as shown in the GLG demos.

This function provides a programming interface for exporting tag from a drawing. The File, Export Tags option of the GLG editors can be used to export tags from the loaded drawing, in which case two double quotation characters are used as the default separators. This can be changed by defining the GLG_STRING_SEPARATOR environment variable to supply a two character string to be used as a separator.

Refer to the Tag Export and Import Features for Run-Time Tag Mapping section of the GLG User's Guide and Builder Reference Manual for more information about the tag file format.

GlgGetDTag()

GlgBoolean GlgGetDTag	(	GlgObject	object,
		char *	tag_source,
		double *	value
	)

Returns the current value of a D (double) tag.

Parameters

object	Specifies a GLG object.
tag_source	Specifies the TagSource of the scalar tag to query.
value	Specifies a pointer used to return the tag value.

Returns

Success or failure status.

If a scalar tag with the given TagSource exists, this function copies its current value into the address specified by the value pointer and returns True, otherwise it generates an error message and returns False.

GlgGetGTag()

GlgBoolean GlgGetGTag	(	GlgObject	object,
		char *	tag_source,
		double *	x_value,
		double *	y_value,
		double *	z_value
	)

Returns the current value of a G (geometrical or color) tag.

Parameters

object	Specifies a GLG object.
tag_source	Specifies the TagSource of the G tag to query. All object's tags with the specified TagSource will be set to the supplied values.
x_value	Specifies a pointer used to return the X value of a geometrical tag or an R component of the color tag.
y_value	Specifies a pointer used to return the Y value of a geometrical tag or a G component of the color tag.
z_value	Specifies a pointer used to return the Z value of a geometrical tag or a B component of the color tag.

Returns

Success or failure status.

If a G tag with the given TagSource exists, this function copies its current three values to the addresses specified with the x_value, y_value and z_value pointers and returns True. Otherwise, it generates an error message and returns False.

GlgGetSTag()

GlgBoolean GlgGetSTag	(	GlgObject	object,
		char *	tag_source,
		char **	value
	)

Returns the current value of a S (string) tag.

Parameters

object	Specifies a GLG object.
tag_source	Specifies the TagSource of the string tag to query.
value	Specifies a pointer used to return the tag value.

Returns

Success or failure status.

If a string tag with the given TagSource exists, this function copies the string pointer into the address specified by value pointer and returns True, otherwise it generates an error message and returns False.

Warning: The returned pointer points to GLG internal data structures and should not be modified. The pointer is valid only immediately after a call to GlgGetSTag. To store the returned string, create a copy of it using GlgStrClone.

GlgHasTagName()

GlgBoolean GlgHasTagName	(	GlgObject	object,
		char *	tag_source
	)

Checks if a data tag with a specified tag name exists.

Parameters

object	Specifies a GLG object whose tag to query.
tag_source	Specifies the TagName to query.

Returns

True if a tag with the given TagName exists, otherwise returns False without generating an error message.

GlgHasTagSource()

GlgBoolean GlgHasTagSource	(	GlgObject	object,
		char *	tag_source
	)

Checks if a data tag with a specified tag source exists.

Parameters

object	Specifies a GLG object whose tag to query.
tag_source	Specifies the tag source to query.

Returns

True if a tag with the given tag source exists, otherwise returns False without generating an error message.

GlgImportTags()

GlgLong GlgImportTags	(	GlgObject	object,
		char *	filename,
		GlgBoolean	verbose
	)

Replaces the TagName and TagSource attributes of the data tags in a drawing with information loaded from a tag translation file.

Parameters

object	Specifies a viewport or an object whose tags to change.
filename	Specifies the tags translation file to load.
verbose	If True, generates an error for each tag that was not modified because it was missing a matching entry in the tag translation file.

Returns

The number of imported tags or -1 in case of an error.

This function can be used at run time to modify the data tags used by the drawing. It load the specified tag translation file and uses it to modify the drawing's data tags. See GlgExportStrings for more information.

This function provides a run time interface for importing modified tags into a drawing. The File, Import Tags option of the GLG editors can be used to import tags into the currently loaded drawing for testing.

GlgSetDTag()

GlgBoolean GlgSetDTag	(	GlgObject	object,
		char *	tag_source,
		double	value,
		GlgBoolean	if_changed
	)

Sets a new value of a D (double) tag.

Parameters

object	Specifies a GLG object.
tag_source	Specifies TagSource of the scalar tag to be set. All object's tags with the specified TagSource will be set to the supplied value.
value	Specifies a new value.
if_changed	If set to False, the graphical updates will be performed even if the new value is the same as the old one. Setting if_changed=True optimizes performance of applications that set tag values regardless whether the values have changed. The parameter is ignored when updating chart entry points to allow plotting straight lines when the plotted value does not change over time.

Returns

Success or failure status.

If scalar tags with the given TagSource exist, this function sets their new values and returns True, otherwise it generates an error message and returns False.

See Tag Access Performance Optimization for more.

GlgSetGTag()

GlgBoolean GlgSetGTag	(	GlgObject	object,
		char *	tag_source,
		double	x_value,
		double	y_value,
		double	z_value,
		GlgBoolean	if_changed
	)

Sets new values of a G (geometrical or color) tag.

Parameters

object	Specifies a GLG object.
tag_source	Specifies the TagSource of the geometrical or color tag to be set. All object's tags with the specified TagSource will be set to the supplied values.
x_value	Specifies the new X value.
y_value	Specifies the new Y value.
z_value	Specifies the new Z value.
if_changed	If set to False, the graphical updates will be performed even if the new value is the same as the old one. Setting if_changed=True optimizes performance of applications that set tag values regardless whether the values have changed.

Returns

Success or failure status.

If G tags with the given TagSource exist, this function sets their new value and returns True, otherwise it generates an error message and returns False.

See Tag Access Performance Optimization for more.

GlgSetSTag()

GlgBoolean GlgSetSTag	(	GlgObject	object,
		char *	tag_source,
		char *	value,
		GlgBoolean	if_changed
	)

Replaces the string of an S (string) tag.

Parameters

object	Specifies a GLG object.
tag_source	Specifies TagSource of the string tag to be set. All object's tags with the specified TagSource will be set to the supplied value.
value	Specifies a new string.
if_changed	If set to False, the graphical updates will be performed even if the new value is the same as the old one. Setting if_changed=True optimizes performance of applications that set tag values regardless whether the values have changed.

Returns

Success or failure status.

If string tags with the given TagSource exist, this function creates copies of the input string, sets these copies as new values of the tags and returns True, otherwise it generates an error message and returns False.

The memory associated with the old strings is automatically freed.

See Tag Access Performance Optimization for more.

GlgSetSTagFromD()

GlgBoolean GlgSetSTagFromD	(	GlgObject	object,
		char *	tag_source,
		char *	format,
		double	value,
		GlgBoolean	if_changed
	)

Replaces the string of an S (string) tag with a value specified by an input number and a format string.

Parameters

object	Specifies a GLG object.
tag_source	Specifies the TagSource of the string tag to be set. All object's tags with the specified TagSource will be set to the supplied values.
format	Specifies the printf-style format to use when setting the tag string.
value	Specifies the numerical value to be converted to a string according to the specified format.
if_changed	If set to False, the graphical updates will be performed even if the new value is the same as the old one. Setting if_changed=True optimizes performance of applications that set tag values regardless whether the values have changed.

Returns

Success or failure status.

If string tags with the given TagSource exist, this function replaces their strings with new strings containing the value parameter formatted using the format argument and returns True, otherwise it generates an error message and returns False.

The memory associated with the old strings is automatically freed.

See Tag Access Performance Optimization for more.