Enumerated Sets Functions

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
• ihuEnumeratedSetAdd
• ihuEnumeratedSetRawValue
• ihuEnumeratedSetsFree
• ihuEnumeratedSetRename
• ihuEnumeratedSetDelete
• ihuEnumeratedStateAdd
• ihuEnumeratedStateModify
• ihuEnumeratedStateDelete

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

Prototype

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.

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

Prototype

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

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.

Prototype

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

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

Prototype

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

Use the ihuEnumeratedSetRename function to rename an enumerated set.

Prototype

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

Use the ihuEnumeratedSetDelete function to delete an enumerated set.

Prototype

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

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

Prototype

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

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

Prototype

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

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

Prototype

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