SubnAdmGet() Operation
Background on the MAD's ComponentMask Field
An entity may issue a query to the SA requesting only records wherein the specified record element(s) match those supplied in the database query. The following example performs a SubnAdmGet(SwitchRecord) looking for any SwitchRecord with the SwitchInfo.LIDsPerPort element = 0008h (refer to Table 33-7 on page 938 and Table 29-4 on page 819):
The AttributeID identifies the record to be accessed (0014h specifies the SwitchRecord attribute).
Each specific record type contains one or more record elements. As an example, the SwitchInfo attribute (and therefore the SwitchRecord) contains 16 elements. “One bits” are placed in the 64-bit ComponentMask field in the bit positions corresponding to the record elements to be included in the compare operation. In this example, bit 10 is set to one and all other mask bits are cleared to zero, thereby specifying that only the 10th element in the SwitchRecord (the LIDsPerPort element) is to be compared.
The 192-byte Admin Data Area contains the template to be compared to the database records of the type specified by the AttributeID. Continuing with the same example, the initial 12 bytes of the Admin Data Area are cleared to zero (they are not included in the query), the next byte is the LIDsPerPort value to be searched for (0008h in this example), and the remainder of the Admin Data Area is cleared to zeros.
SubnAdmGet() Details
The SubnAdmGet() operation is used to read a single SA record. The SA responds with a SubnAdmGet(Resp() MAD containing the requested record. The state of the AttributeModifier field (see Table 33-1 on page 919) defines the type of access:
To access an RA with a specific RID. In this case, the AttributeModifier contains the RID to be read and returned (it is ≠ 00000000h or FFFFFFFFh).
To access a record matching a query template. In this case, the AttributeModifier = FFFFFFFFh. The SA returns the RA (a single RA) with attribute element(s) matching those flagged by one bits in the ComponentMask. The Admin Data Area contains the attribute element value(s) to be matched, with all of the other attribute elements cleared to zero.
When fetching a record using match criteria, an ERR_REQ_INVALID error status (see Table 33-8 on page 939) is returned if the query results in a match on multiple records.
The SA_Key is ignored and the SA_Key returned in the SubAdmGetResp() = 0. The following MAD elements are set to zero:
SA_Key.
Segment Number.
Payload Length.
Fragment Flag.
Edit Modifier.
Window.
End RID.
| Dword | Byte 0 | Byte 1 | Byte 2 | Byte 3 | ||
|---|---|---|---|---|---|---|
| 0 | Base MAD Header | Base Version = 01h | Management Class = SubnAdm | Class Version = 01h | R | SA Method = SubnAdmGet() |
| 1 | Status is only meaningful in response packets. See Table 27-2 on page 776 and Table 33-8 on page 939 | Not used | ||||
| 2 | Transaction ID | |||||
| 3 | ||||||
| 4 | SA AttributeID = 0014h | Reserved | ||||
| 5 | AttributeModifier = FFFFFFFFh | |||||
| 6 | SMP- specific fields | SA_Key is ignored | ||||
| 7 | ||||||
| 8 | SM_Key | |||||
| 9 | ||||||
| 10 | Segment Number = 0 | |||||
| 11 | Payload Length = 0 | |||||
| 12 | Fragment Flag = 0 | Edit Modifier= 0 | Window = 0 | |||
| 13 | End RID = 0 | |||||
| 14 | Component Mask = 0000000000100000000000000000000000000000000000000000000000000000b | |||||
| 15 | ||||||
| 16–63 | 192-byte Admin Data Area = 000000000000000000000000000800000h (followed by all zeros) | |||||
| Name | Bit(s) | Description |
|---|---|---|
| Common MAD status | 7:0 | See Table 27-2 on page 776. |
| ERR_KEY_STALE | 8 | Supplied key is stale. Must reload table records and get new lease. |
| ERR_REQ_INVALID | 9 | Supplied request or update is invalid. |
| 11:10 | Reserved. | |
| ERR_REFUSED | 12 | Policy violation. |
| 15:13 | Reserved. |