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()

• getPhysicalEntry()

• deletePhysicalTableEntry()

• makePhysicalTableEntryStale()

• makePhysicalTableEntryLive()

• getPhysicalStaleEntry()

• getAllChildrenFromPhysicalContainedIn()

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.