Enumerated Sets Functions

Important: You do not have the latest version of Historian! You are missing out on the newest capabilities and enhanced security. For information on all the latest features, see the Historian product page. For more information on upgrades, contact your GE Digital sales agent or e-mail GE Digital Sales Support. For the most up-to-date documentation, go here.

Enumerated Sets Functions Overview

You can use the enumerated sets functions to create, modify, delete, and browse enumerated sets, and assign tags to those sets.

When you query tag data by using these functions, the string state name value is returned by default. To retrieve the numeric value, use ihuEnumeratedSetRawValue.

When you write to a tag by using these functions, write the numeric value.

Use these functions to retrieve all the enumerated sets that match the setname mask criteria. If you want to retrieve all sets, pass * as the mask.

Enumerated Sets Functions

ihuGetEnumeratedSets

Prototype

Use the ihuGetEnumeratedSets function to retrieve all the enumerated sets that match the setname mask criteria. To retrieve all sets, pass * as the mask.

ihuErrorCode IHUAPI ihuGetEnumeratedSets (
in long serverhandle,
in MSO Char *EnumeratedSetMask,
out long *numberofrecords,
out ihuEnumeratedSetRecordSet
*EnumeratedSetRecordSet  )

Remarks

The ihuGetEnumeratedSets function returns the number of enumerated set records, plus the enumerated sets.

Returns

The ihuGetEnumeratedSets function returns ihuSTATUS_OK on success, or errors if invalid input parameters are found or if out-of-memory issues occur during dynamic memory allocation.

ihuEnumeratedSetAdd

Prototype

Use the ihuEnumeratedSetAdd function to add enumerated sets. You can specify sets that have states, or add states later on.

ihuEnumeratedSetAdd
( in long serverhandle,
in ihuEnumeratedSetProperties
*EnumeratedSet  )

Remarks

Any existing set with a name that matches the specified set name is overwritten by the new set.

Returns

The ihuEnumeratedSetAdd function returns ihuSTATUS_OK on success, or returns errors on:

  • Invalid input parameters
  • Out-of-memory issues during dynamic memory allocation
  • User not a member of ihTag Admin group
Note: Set the Administrator parameter to the ihTag Admin security group to assign the highest precedence to this parameter.

ihuEnumeratedSetRawValue

Prototype

Use the ihuEnumeratedSetRawValue function to specify whether to return string or numeric values returned when reading tags by using enumerated sets. By default, string values are retrieved for tags associated with enumerated sets. To retrieve numeric values, set SetRawValue to TRUE. If string values are unavailable, raw values are retrieved.

ihuEnumeratedSetRawValue (
in long serverhandle,
in BOOL SetRawValue
)

Remarks

Override the default value of FALSE only to return numeric values. The value persists until the function is called again or your program exits.

Returns

The ihuEnumeratedSetRawValue function returns ihuSTATUS_OK on success, or returns errors on:

  • Invalid input parameters
  • User not a member of ihTag Admin group
Note: Set the Administrator parameter to the ihTag Admin security group to assign the highest precedence to this parameter.

ihuEnumeratedSetsFree

Prototype

Use the ihuEnumeratedSetsFree function to clear the enumerated set buffers after you call ihuGetEnumeratedSets().

ihuEnumeratedSetsFree (
in long serverhandle,
ihuEnumeratedSetRecordSet
in *EnumeratedSetRecordSet )

Remarks

When you use the ihuEnumeratedSetsFree function, memory is cleared from the enumerated set buffers.

Returns

The ihuEnumeratedSetsFree function returns ihuSTATUS_OK on success, or returns errors on:

  • Invalid input parameters
  • User not a member of ihTag Admin group
Note: Set the Administrator parameter to the ihTag Admin security group to assign the highest precedence to this parameter.

ihuEnumeratedSetRename

Prototype

Use the ihuEnumeratedSetRename function to rename an enumerated set.

ihuEnumeratedSetRename (
in long serverhandle,
in MSO Char *oldEnumeratedSetName,
in MSO Char *newEnumeratedSetName )

Remarks

You must be an administrator of a set to rename it.

Returns

The ihuEnumeratedSetRename function returns ihuSTATUS_OK on success, or returns errors on:

  • Invalid input parameters
  • Out-of-memory issues during dynamic memory allocation
  • No set name that matches OldEnumeratedSetName value
  • User not a member of ihTag Admin group
Note: Set the Administrator parameter to the ihTag Admin security group to assign the highest precedence to this parameter.

ihuEnumeratedSetDelete

Prototype

Use the ihuEnumeratedSetDelete function to delete an enumerated set.

ihuEnumeratedSetDelete (
in long serverhandle,
in MSO Char *EnumeratedSetName )

Remarks

You must be an administrator of a set to delete it.

Returns

The ihuEnumeratedSetDelete function returns ihuSTATUS_OK on success, or returns errors on:

  • Invalid input parameters
  • Out-of-memory issues during dynamic memory allocation
  • No set name that matches EnumeratedSetName value
  • User not a member of ihTag Admin group
Note: Set the Administrator parameter to the ihTag Admin security group to assign the highest precedence to this parameter.

ihuEnumeratedStateAdd

Prototype

Use the ihuEnumeratedStateAdd function to add a state to an existing enumerated set.

ihuEnumeratedStateAdd (
in long serverhandle,
in MSO Char *EnumSetName,
in ihuEnumeratedSetState *EnumState )

Remarks

When you add a state to an existing enumerated set, the data type of the new state matches the data type of other states in the set.

Any existing state with a name that matches the specified state name is overwritten by the new state.

Returns

The ihuEnumeratedStateAdd function returns ihuSTATUS_OK on success, or returns errors on:

  • Invalid input parameters
  • Out-of-memory issues during dynamic memory allocation
  • No set name that matches EnumSetName value
  • User not a member of ihTag Admin group
Note: Set the Administrator parameter to the ihTag Admin security group to assign the highest precedence to this parameter.

ihuEnumeratedStateModify

Prototype

Use the ihuEnumeratedStateModify function to modify a state in an enumerated set.

ihuEnumeratedStateModify (
  in long serverhandle,
  in MSO Char *EnumeratedSetName,
  in MSO Char *EnumeratedStateName,
  ihuEnumeratedSetState
  in *EnumStateToModify )

Remarks

You can modify state values and names, but not data types. To change a state name, pass the old and new names as string values inside the EnumStateToModify parameter.

Returns

The ihuEnumeratedStateModify function returns ihuSTATUS_OK on success, or returns errors on:

  • Invalid input parameters
  • No set name that matches EnumeratedSetName value
  • No state name that matches EnumeratedStateName value
  • User not a member of ihTag Admin group
Note: Set the Administrator parameter to the ihTag Admin security group to assign the highest precedence to this parameter.

ihuEnumeratedStateDelete

Prototype

Use the ihuEnumeratedStateDelete function to delete a state from an enumerated set.

ihuEnumeratedStateDelete
( in long serverhandle,
in MSO Char *EnumeratedSetName,
in MSO Char *EnumeratedStateName
)

Remarks

When only one state is available in a set, you cannot delete the state. The only way to delete the state is to delete the set. There is no need to delete each state before you delete a set.

You must be an administrator of a set to delete its associated states.

Returns

The ihuEnumeratedStateDelete function returns ihuSTATUS_OK on success, or returns errors on:

  • Invalid input parameters
  • No set name that matches EnumeratedSetName value
  • No state name that matches EnumeratedStateName value
  • Out-of-memory issues during dynamic memory allocation
  • User not a member of ihTag Admin group
Note: Set the Administrator parameter to the ihTag Admin security group to assign the highest precedence to this parameter.