Technical Reference: Base Operating System and Extensions, Volume 1

HBA_GetAdapterAttributes, HBA_GetPortAttributes, HBA_GetDiscoveredPortAttributes, HBA_GetPortAttributesByWWN Subroutine

Purpose

Gets the attributes of the end device's adapter, port, or remote port.

Library

Common Host Bus Adapter Library (libHBAAPI.a)

Syntax

#include <hbaapi.h>

HBA_STATUS HBA_GetAdapterAttributes (handle, hbaattributes)
HBA_STATUS HBA_GetAdapterPortAttributes (handle, portindex, portattributes)
HBA_STATUS HBA_GetDiscoveredPortAttributes (handle, portindex, discoveredportindex, portattributes)
HBA_STATUS HBA_GetPortAttributesByWWN (handle, PortWWN, portattributes)

HBA_HANDLE handle;
HBA_ADAPTERATTRIBUTES *hbaattributes;
HBA_UINT32 portindex;
HBA_PORTATTRIBUTES *portattributes;
HBA_UINT32 discoveredportindex;
HBA_WWN PortWWN;

Description

The HBA_GetAdapterAttributes subroutine queries the ODM and makes system calls to gather information pertaining to the adapter. This information is returned to the HBA_ADAPTERATTRIBUTES structure. This structure is defined in the /usr/include/sys/hbaapi.h file.

The HBA_GetAdapterAttributes, HBA_GetAdapterPortAttributes, HBA_GetDiscoveredPortAttributes, and HBA_GetPortAttributesByWWN subroutines return the attributes of the adapter, port or remote port.

These attributes include:

Manufacturer
SerialNumber
Model
ModelDescription
NodeWWN
NodeSymbolicName
HardwareVersion
DriverVersion
OptionROMVersion
FirmwareVersion
VendorSpecificID
NumberOfPorts
Drivername

The HBA_GetAdapterPortAttributes, HBA_GetDiscoveredPortAttributes, and HBA_GetPortAttributesByWWN subroutines also query the ODM and make system calls to gather information. The gathered information pertains to the port attached to the adapter or discovered on the network. The attributes are stored in the HBA_PORTATTRIBUTES structure. This structure is defined in the /usr/include/sys/hbaapi.h file.

These attributes include:

NodeWWN
PortWWN
PortFcId
PortType
PortState
PortSupportedClassofService
PortSupportedFc4Types
PortActiveFc4Types
OSDeviceName
PortSpeed
NumberofDiscoveredPorts
PortSymbolicName
PortSupportedSpeed
PortMaxFrameSize
FabricName

The HBA_GetAdapterPortAttributes subroutine returns the attributes of the attached port.

The HBA_GetDiscoveredPortAttributes, and HBA_GetPortAttributesByWWN subroutines return the same information. However, these subroutines differ in the way they are called, and in the way they acquire the information.

Parameters

handle	Specifies the open file descriptor obtained from a successful call to the open subroutine.
hbaatributes	Points to an HBA_AdapterAttributes structure, which is used to store information pertaining to the Host Bus Adapter.
portindex	Specifies the index number of the port where the information was obtained.
portattributes	Points to an HBA_PortAttributes structure used to store information pertaining to the port attached to the Host Bus Adapter.
discoveredportindex	Specifies the index of the attached port discovered over the network.
PortWWN	Specifies the world wide name or port name of the target device.

Return Values

Upon successful completion, the attributes and a value of HBA_STATUS_OK, or 0 are returned.

If no information for a particular attribute is available, a null value is returned for that attribute. HBA_STATUS_ERROR or 1 is returned if certain ODM queries or system calls fail while trying to retrieve the attributes.

Error Codes

The Storage Area Network Host Bus Adapter API subroutines return the following error codes:

HBA_STATUS_OK	A value of 0 on successful completion.
HBA_STATUS_ERROR	A value of 1 if an error occurred.
HBA_STATUS_ERROR_INVALID_HANDLE	A value of 3 if there was an invalid file handle.
HBA_STATUS_ERROR_ARG	A value of 4 if there was a bad argument.
HBA_STATUS_ERROR_ILLEGAL_WWN	A value of 5 if the world wide name was not recognized.

Related Information

HBA_GetAdapterName Subroutine, and HBA_GetNumberOfAdapters Subroutine.

Special Files in AIX 5L Version 5.2 Files Reference describes specific qualities of the files that define devices.