Solaris System Management Agent Developer's Guide

Entity MIB API

This section lists and describes the API functions that are provided in the libentity.so module. Use these functions in your module when you want to use the Entity MIB.

Table 9–1 Entity MIB Functions Listed by Category


Function Category	Functions
Physical Table Functions	`allocPhysicalEntry()` `getPhysicalEntry()` `deletePhysicalTableEntry()` `makePhysicalTableEntryStale()` `makePhysicalTableEntryLive()` `getPhysicalStaleEntry()` `getAllChildrenFromPhysicalContainedIn()`
Physical Contains Table Functions	`addPhysicalContainsTableEntry()` `deletePhysicalContainsTableEntry()` `deletePhysicalContainsParentIndex()` `deletePhysicalContainsChildIndex()` `getPhysicalContainsChildren()`
Logical Table Functions	`allocLogicalEntry()` `getLogicalTableEntry()` `deleteLogicalTableEntry()` `makeLogicalTableEntryStale()` `makeLogicalTableEntryLive()` `getLogicalStaleEntry()`
LP Mapping Table Functions	`addLPMappingTableEntry()` `deleteLPMappingTableEntry()` `deleteLPMappingLogicalIndex()` `deleteLPMappingPhysicalIndex()`
Alias Mapping Table Functions	`addAliasMappingTableEntry()` `deleteAliasMappingTableEntry()` `deleteAliasMappingLogicalIndex()` `deleteAliasMappingPhysicalIndex()`

Physical Table Functions

The entPhysicalTable contains one row for each physical entity. The table contains at least one row for an overall physical entity. Each table entry provides objects to help an NMS to identify and characterize the entry. Other objects in the table entry help an NMS to relate the particular entry to other entries in the table.

The following functions are for use with the entPhysicalTable in the Entity MIB.

`allocPhysicalEntry()`

Synopsis

extern int allocPhysicalEntry(int physidx, entPhysicalEntry_t *newPhysEntry);

Description

Allocates an entry in the entPhysicalTable. The physidx parameter is the requested physical index. If physidx= 0, the function tries to use the first available index in the table. If physidx= 1 or greater, the function tries to use the specified index. If the specified index is in use, the function returns the first available index in the table. As a result, the returned index might not be the same as the requested physical index.

The memory that is associated with newPhysEntry can be freed. The function creates an internal copy of the data.

The entPhysicalEntry_t structure definition is shown in entPhysicalEntry_t Structure. Special cases for newPhysEntry values are handled as shown in the following table.

Object	Value of `newPhysEntry`	Entity MIB module handling
`entPhysicalDescr`	NULL	reject
`entPhysicalVendorType`	NULL	`{ 0, 0 }`
`entPhysicalName`	NULL	`""`
`entPhysicalHardwareRev`	NULL	`""`
`entPhysicalFirmwareRev`	NULL	`""`
`entPhysicalSoftwareRev`	NULL	`""`
`entPhysicalSerialNum`	NULL	`""`
`entPhysicalMfgName`	NULL	`""`
`entPhysicalModelName`	NULL	`""`
`entPhysicalAlias`	NULL	`""`
`entPhysicalAssetID`	NULL	`""`

Returns

index: allocated to the physical entry.
-1: if an error occurs when adding the entry. Check the log for more details.

`getPhysicalEntry()`

Synopsis

entPhysicalEntry_t *getPhysicalEntry(int index);

Description

Gets the actual physical table entry for the specified index. The caller must not change the values or release the memory of the entry that is returned. The entPhysicalEntry_t structure definition is shown in entPhysicalEntry_t Structure.

Returns

getPhysicalEntry() returns the entry for the specified index.

Returns NULL if an error occurs while finding the entry, or if a stale entry exists. In this context, stale means that the entry details are present in the agent memory but should not be displayed during any SNMP operation.

`deletePhysicalTableEntry()`

Synopsis

extern int deletePhysicalTableEntry(int xPhysicalIndex);

Description

Deletes the physical table entry that is associated with the specified xPhysicalIndex. The instances of xPhysicalIndex in the entAliasMappingTable, entLPMappingTable and the entPhysicalContainsTable are also deleted to maintain integrity among the various Entity MIB tables.

Returns

0: for success.
-1: if the xPhysicalIndex is not found.
-2: if a stale entry was found for the xPhysicalIndex. In this context, “stale” means that the entry details are present in the agent memory but are not displayed during any SNMP operation.

`makePhysicalTableEntryStale()`

Synopsis

extern int makePhysicalTableEntryStale(int xPhysicalIndex);

Description

Makes the physical table entry that is associated with the xPhysicalIndex become stale. In this context, “stale” means that the entry details are present in the agent memory but are not displayed during any SNMP operation. The index that was allocated to a stale entry is not allocated to another entry.

When you make an entry become stale, the instances of xPhysicalIndex in the entAliasMappingTable, entLPMappingTable and entPhysicalContainsTable are also deleted. The deletion maintains integrity among the various Entity MIB tables. Before you make an entry stale, you might want to store the entries that are to be deleted from the tables.

The physical table entry can be made available or “live” again by calling the makePhysicalTableEntryLive() functions, which is described in makePhysicalTableEntryLive().

Returns

0: for success.
-1: if the xPhysicalIndex is not found.
-2: if a stale entry already exists for xPhysicalIndex.

`makePhysicalTableEntryLive()`

Synopsis

extern int makePhysicalTableEntryLive(int xPhysicalIndex);

Description

Makes the stale physical table entry associated with the xPhysicalIndex live. In this context, “live” means that the entry details that are present in the agent memory are displayed during SNMP operations. The entry can be made stale by calling the makePhysicalTableEntryStale() function. In this context, “stale” means that the entry details are present in the agent memory but are not displayed during any SNMP operation.

If a stale entry is made live again, you must recreate the corresponding entries that were deleted in the entPhysicalContainsTable, the entLPMappingTable, and the entAliasMappingTable. Use the appropriate functions for adding an entry to each table: addPhysicalContainsTableEntry(), addLPMappingTableEntry(), and addAliasMappingTableEntry().

Returns

0: for success.
-1: if the xPhysicalIndex is not found.
-2: if a live entry already exists for xPhysicalIndex.

`getPhysicalStaleEntry()`

Synopsis

entPhysicalEntry_t *getPhysicalStaleEntry(int index);

Description

The caller must not change the values or release the memory of the entry that is returned.

Gets the stale physical table index structure for the specified index. In this context, stale means that the entry details are present in the agent memory but are not displayed during any SNMP operation. The entPhysicalEntry_t structure definition is shown in entPhysicalEntry_t Structure.

Returns

Returns the index structure for the specified index.

Returns NULL if an error occurs while finding the entry, or if a live entry exists.

`getAllChildrenFromPhysicalContainedIn()`

Synopsis

int getAllChildrenFromPhysicalContainedIn(int parentIndex);

Description

Gets the indexes for all children in the entPhysicalTable that have parentIndex as their parent in the entPhysicalContainedIn field.

Returns

Returns an array of integer indexes with null termination.

Returns NULL if no children, or invalid index, or not enough memory when allocating the array.

Physical Contains Table Functions

The entPhysicalContainsTable exposes the container relationships between physical entities. This table provides the same information that can be found by constructing the virtual containment tree for a given entPhysicalTable, but in a more direct format.

Returns an array of integer indexes, with null termination.

Returns NULL if children exist, or if not enough memory exists when allocating the array. The array is a copy that should be freed when done.

Logical Table Functions

The entLogicalTable table contains one row per logical entity. For agents that implement more than one naming scope, at least one entry must exist. Agents that instantiate all MIB objects within a single naming scope are not required to implement this table.

The following functions are for use with the entLogicalTable in the Entity MIB:

`allocLogicalEntry()`

Synopsis

extern int allocLogicalEntry(int logidx, entLogicalEntry_t *xnewLogicalEntry);

Description

Allocates an entry in the Logical Table. The logidx parameter is the requested logical index. If logidx= 0, the function tries to use the first available index in the table. If logidx= 1 or greater, the function tries to use the specified index. If the specified index is in use, the function returns the first available index in the table. As a result, the returned index might not be the same as the requested logical index.

The allocLogicalEntry() function returns the logical index that is allocated to the entry. The memory that is associated with xnewLogicalEntry can be freed. The function creates a internal copy of the data.

The entLogicalEntry_t structure definition is shown in entLogicalEntry_t Structure. Special cases for xnewLogicalEntry values are handled as shown in the following table.

Object	Value of `xnewLogicalEntry`	Entity MIB module handling
`entLogicalDescr`	NULL	reject
`entLogicalType`	NULL	`{ 1,3,6,1,2,1 }`
`entLogicalCommunity`	NULL	`""`
`entLogicalTAddress`	NULL or `""`	reject
`entLogicalTDomain`	NULL	reject
`entLogicalContextEngineId`	NULL	`""`
`entLogicalContextName`	NULL	`""`

Returns

Returns the index allocated to the logical entry.

Returns -1 for error in adding the entry. Check the log for more details.

`getLogicalTableEntry()`

Synopsis

entLogicalEntry_t *getLogicalTableEntry(int xLogicalIndex);

Description

This function gets the logical table index structure for a particular index. The caller must not change the value or release the memory of the entry that is returned. The entLogicalEntry_t structure definition is shown in entLogicalEntry_t Structure.

Returns

Returns the entry that is associated with xLogicalIndex.

Returns NULL on error in finding the entry, or if a stale entry exists.

`deleteLogicalTableEntry()`

Synopsis

extern int deleteLogicalTableEntry(int xLogicalIndex);

Description

Deletes the logical table entry that is associated with the xLogicalIndex. The instances of xLogicalIndex in the entAliasMappingTable and the entLPMappingTable are also deleted to maintain integrity among the various Entity MIB tables.

Returns

0: for success.
-1: if the xLogicalIndex is not found.
-2: if a stale entry was found for xLogicalIndex.

`makeLogicalTableEntryStale()`

Synopsis

extern int makeLogicalTableEntryStale(int xLogicalIndex);

Description

Makes the logical table entry associated with the xLogicalIndex become stale. In this context, “stale” means that the entry details are present in the agent memory but are not displayed during any SNMP operation. The index that was allocated to a stale entry is not allocated to another entry.

When you make an entry become stale, the instances of xLogicalIndex in the entAliasMappingTable, entLPMappingTable and entPhysicalContainsTable are also deleted. The deletion maintains integrity among the various Entity MIB tables. Before you make an entry stale, you might want to store the entries that are to be deleted from the other tables.

The stale logical table entry can be made available again by calling the makeLogicalTableEntryLive() function, which is described in makeLogicalTableEntryLive().

Returns

0: for success.
-1: if the xLogicalIndex is not found.
–2: if a stale entry was found for xLogicalIndex.

`makeLogicalTableEntryLive()`

Synopsis

extern int makeLogicalTableEntryLive(int xLogicalIndex);

Description

Makes the stale logical table entry associated with the xLogicalIndex become live. In this context, “live” means that the entry details that are present in the agent memory are displayed during any SNMP operations. The entry can be made stale by calling the makeLogicalTableEntryStale() function.

If an entry is made live again, you must recreate the corresponding entries that were deleted in the entPhysicalContainsTable, the entLPMappingTable, and the entAliasMappingTable. Use the appropriate functions for adding an entry to each table: addPhysicalContainsTableEntry(), addLPMappingTableEntry(), and addAliasMappingTableEntry().

Returns

0: for success.
-1: if the xLogicalIndex is not found.
–2: if a live entry already exists for xLogicalIndex.

`getLogicalStaleEntry()`

Synopsis

entLogicalEntry_t *getLogicalStaleEntry(int index );

Description

Gets the stale logical table index structure for the specified index. The caller must not change the values or release the memory of the entry that is returned. The entLogicalEntry_t structure definition is shown in entLogicalEntry_t Structure.

Returns

Returns the stale entry for the specified index.

Returns NULL if the entry is not found, or if a live entry exists.

LP Mapping Table Functions

The entLPMappingTable contains zero or more rows that associate logical entities to physical equipment. For each logical entity that is known by this agent, there are zero or more mappings to the physical resources that are used to realize that logical entity. An agent should limit the number and nature of entries in this table so that only meaningful and non-redundant information is returned. See the /etc/sma/snmp/mibs/ENTITY-MIB.txt file for more information about the entLPMappingTable.

number: of successfully deleted entries.
–1: if no entry was deleted.
-2: for stale physical entry.

Alias Mapping Table Functions

The entAliasMappingTable contains zero or more rows that represent mappings of logical entity and physical entities for ports to external MIB identifiers. Each physical port in the system can be associated with a mapping to an external identifier. The external identifier is associated with a particular logical entity's naming scope. A wildcard mechanism is provided to indicate that an identifier is associated with more than one logical entity.

The following functions are for use with the entAliasMappingTable in the Entity MIB:

`addAliasMappingTableEntry()`

Synopsis

extern int addAliasMappingTableEntry(int xentPhysicalIndex, int xentLogicalIndex, oid* xAliasMapId, int xAliasMapIdSize);

Description

Adds an entry to the entAliasMappingTable with the xentPhysicalIndex as the primary index and xentLogicalIndex as the secondary index. xAliasMapId is the alias (OID) for the entry and xAliasMapIdSize is the size in bytes of xAliasMapId.

Note that if entAliasMapId = NULL, the request is rejected.

Returns

0: for successful addition.
1: if the entry already exists for the given xentPhysicalIndex and xentLogicalIndex.
-1: for failure.
-2: for stale entry.

`deleteAliasMappingTableEntry()`

Synopsis

extern int deleteAliasMappingTableEntry(int xentPhysicalIndex, int xentLogicalIndex);

Description

Deletes the entry in the entAliasMappingTable that has xentPhysicalIndex as the primary index and xentLogicalIndex as the secondary index.

Returns

0: for successful deletion.
-1: for entry not found.
-2: for stale entry.

`deleteAliasMappingLogicalIndex()`

Synopsis

extern int deleteAliasMappingLogicalIndex(int xentLogicalIndex);

Description

Deletes all entries of the entAliasMappingTable that have xentLogicalIndex as the secondary index.

This function cannot be used to delete all indexes that have an xentLogicalIndex of zero. Use the deleteAliasMappingTableEntry() function to delete such entries one at a time, with the appropriate xentPhysicalIndex specified.

Returns

number: of entries successfully deleted.
-1: for entry not found.
-2: for stale logical entry.

`deleteAliasMappingPhysicalIndex()`

Synopsis

extern int deleteAliasMappingPhysicalIndex(int xentPhysicalIndex);

Description

Deletes all entries in the entAliasMappingTable whose primary index matches the specified xentPhysicalIindex.

Returns

number: of entries successfully deleted.
–1: for entry not found.
–2: for stale physical entry.