'\" te
.\" Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved.
.TH HBA_SetRNIDMgmtInfo 3HBAAPI "1 Sep 2003" "SunOS 5.11" "Common Fibre Channel HBA Information Library Functions"
.SH NAME
HBA_SetRNIDMgmtInfo, HBA_GetRNIDMgmtInfo, HBA_SendRNID, HBA_SendRNIDV2 \- access Fibre Channel Request Node Identification Data (RNID)
.SH SYNOPSIS
.LP
.nf
cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lHBAAPI\fR [ \fIlibrary\fR\&.\|.\|. ]
#include <hbaapi.h>

\fBHBA_STATUS\fR \fBHBA_SetRNIDMgmtInfo\fR(\fBHBA_HANDLE\fR \fIhandle\fR,
     \fBHBA_MGMTINFO *\fR\fIpInfo\fR);
.fi

.LP
.nf
\fBHBA_STATUS\fR \fBHBA_GetRNIDMgmtInfo\fR(\fBHBA_HANDLE\fR \fIhandle\fR,
     \fBHBA_MGMTINFO *\fR\fIpInfo\fR);
.fi

.LP
.nf
\fBHBA_STATUS\fR \fBHBA_SendRNID\fR(\fBHBA_HANDLE\fR \fIhandle\fR, \fBHBA_WWN\fR \fIwwn\fR,
     \fBHBA_WWNTYPE\fR \fIwwntype\fR, \fBvoid *\fR\fIpRspBuffer\fR,
     \fBHBA_UINT32 *\fR\fIRspBufferSize\fR);
.fi

.LP
.nf
\fBHBA_STATUS\fR \fBHBA_SendRNIDV2\fR(\fBHBA_HANDLE\fR \fIhandle\fR, \fBHBA_WWN\fR \fIhbaPortWWN\fR,
     \fBHBA_WWN\fR \fIdestWWN\fR, \fBHBA_UINT32\fR \fIdestFCID\fR, 
     \fBHBA_UINT32\fR \fINodeIdDataFormat\fR, \fBvoid *\fR\fIpRspBuffer\fR,
     \fBHBA_UINT32 *\fR\fIRspBufferSize\fR);
.fi

.SH PARAMETERS
.sp
.ne 2
.mk
.na
\fB\fIhandle\fR\fR
.ad
.sp .6
.RS 4n
an open handle returned from \fBHBA_OpenAdapter\fR(3HBAAPI)
.RE

.sp
.ne 2
.mk
.na
\fB\fIpInfo\fR\fR
.ad
.sp .6
.RS 4n
.sp
.ne 2
.mk
.na
\fB\fBHBA_SetRNIDMgmtInfo()\fR\fR
.ad
.sp .6
.RS 4n
a pointer to a \fBHBA_MGMTINFO\fR structure containing the new RNID
.RE

.sp
.ne 2
.mk
.na
\fB\fBHBA_GetRNIDMgmtInfo()\fR\fR
.ad
.sp .6
.RS 4n
a pointer to a HBA_MGMTINFO structure into which the RNID is copied
.RE

.RE

.sp
.ne 2
.mk
.na
\fB\fIwwn\fR\fR
.ad
.sp .6
.RS 4n
the discovered port WWN to which the request is sent
.RE

.sp
.ne 2
.mk
.na
\fB\fIwwntype\fR\fR
.ad
.sp .6
.RS 4n
deprecated
.RE

.sp
.ne 2
.mk
.na
\fB\fIhbaPortWWN\fR\fR
.ad
.sp .6
.RS 4n
the Port WWN of the local HBA through which to send the ELS
.RE

.sp
.ne 2
.mk
.na
\fB\fIdestWWN\fR\fR
.ad
.sp .6
.RS 4n
the Port WWN of the remote Target to which the ELS is sent
.RE

.sp
.ne 2
.mk
.na
\fB\fIdestFCID\fR\fR
.ad
.sp .6
.RS 4n
If \fIdestFCID\fR is non-zero, \fIdestFCID\fR is the address identifier of the remote target to which the ELS is sent.  If \fIdestFCID\fR is 0, \fIdestFCID\fR is ignored.
.RE

.sp
.ne 2
.mk
.na
\fB\fINodeIdDataFormat\fR\fR
.ad
.sp .6
.RS 4n
the Node Identification Data Fromat value as defined in FC-FS
.RE

.sp
.ne 2
.mk
.na
\fB\fIpRspBuffer\fR\fR
.ad
.sp .6
.RS 4n
A pointer to a buffer into which the RNID response is copied .  The data will be in Big Endian format.
.RE

.sp
.ne 2
.mk
.na
\fB\fIRspBufferSize\fR\fR
.ad
.sp .6
.RS 4n
A pointer to the size of the buffer.  On completion it will contain the size of the actual response payload copied into the buffer.
.RE

.SH DESCRIPTION
.sp
.LP
These functions access Fibre Channel Request Node Identification Data (RNID) as defined in the T11 specification FC-FS.
.sp
.LP
The \fBHBA_SetRNIDMgmtInfo()\fR function sets the RNID returned from by HBA.
.sp
.LP
The \fBHBA_GetRNIDMgmtInfo()\fR function retrieves the stored RNID from the HBA.
.sp
.LP
The \fBHBA_SendRNID()\fR function sends an RNID request to a discovered port.  The Node Identification Data format is always set to 0xDF for General Topology Discovery Format as defined in the T11 specification FC-FS.
.sp
.LP
The \fBHBA_SendRNIDV2()\fR function sends an RNID request to a discovered port requesting a specified Node Identification Data format.
.SH RETURN VALUES
.sp
.LP
Upon successful completion, \fBHBA_SetRNIDMgmtInfo()\fR returns \fBHBA_STATUS_OK\fR and sets the RNID.
.sp
.LP
Upon successful completion, \fBHBA_GetRNIDMgmtInfo()\fR returns \fBHBA_STATUS_OK\fR. Otherwise, an error value is returned and the content of \fIpInfo\fR is undefined.
.sp
.LP
Upon successful completion, \fBHBA_SendRNID()\fR returns \fBHBA_STATUS_OK\fR. Otherwise, an error value is returned and the content of \fIpRspBuffer\fR is undefined.
.sp
.LP
The \fBHBA_SendRNIDV2()\fR returns the following values:
.sp
.ne 2
.mk
.na
\fB\fBHBA_STATUS_OK\fR\fR
.ad
.sp .6
.RS 4n
The RNID ELS has been successfully returned.
.RE

.sp
.ne 2
.mk
.na
\fB\fBHBA_STATUS_ERROR_ELS_REJECT\fR\fR
.ad
.sp .6
.RS 4n
The RNID ELS was rejected by the HBA Port.
.RE

.sp
.ne 2
.mk
.na
\fB\fBHBA_STATUS_ERROR_ILLEGAL_WWN\fR\fR
.ad
.sp .6
.RS 4n
The value of \fIhbaPortWWN\fR is not a valid port WWN on the specified HBA. 
.RE

.sp
.ne 2
.mk
.na
\fB\fBHBA_STATUS_ERROR_ILLEGAL_FCID\fR\fR
.ad
.sp .6
.RS 4n
The \fIdestWWN\fR/\fIdestFCID\fR pair conflicts with a discovered Port Name/address identifier pair known by the HBA.
.RE

.sp
.ne 2
.mk
.na
\fB\fBHBA_STATUS_ERROR_ILLEGAL_FCID\fR\fR
.ad
.sp .6
.RS 4n
The N_Port WWN in the RNID response does not match \fIdestWWN\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fBHBA_STATUS_ERROR\fR\fR
.ad
.sp .6
.RS 4n
An error occurred.
.RE

.SH ERRORS
.sp
.LP
See \fBattributes\fR(5) for general error status values.
.SH ATTRIBUTES
.sp
.LP
See \fBlibhbaapi\fR(3LIB) for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Interface StabilityCommitted
_
T{
Standard: FC-HBA Version 4 (API version 2)
T}
_
MT-LevelSafe
_
StandardFC-MI 1.92 (API version 1)
.TE

.SH SEE ALSO
.sp
.LP
\fBHBA_OpenAdapter\fR(3HBAAPI), \fBlibhbaapi\fR(3LIB), \fBattributes\fR(5)
.sp
.LP
T11 FC-MI Specification
.SH BUGS
.sp
.LP
The \fBHBA_SetRNIDMgmtInfo()\fR and \fBHBA_GetRNIDMgmtInfo()\fR functions do not take a \fIportindex\fR to define to which port of a multi-ported HBA the command should apply. The behavior on multi-ported HBAs is vendor-specific and can result in all ports being set to the same value.
.sp
.LP
The \fBHBA_SetRNIDMgmtInfo()\fR and \fBHBA_GetRNIDMgmtInfo()\fR functions allow only 0xDF (General Topology Discovery Format).
.sp
.LP
The \fBHBA_SendRNID()\fR function does not take a \fIportindex\fR to define through which port of a multi-ported HBA to send the command. The behavior on multi-ported HBAs is vendor-specific and can result in the command being sent through the first port.
.sp
.LP
The \fBHBA_SendRNID()\fR function does not take an argument to specify the Node Identification Data Format. It always assumes that 0xDF (General Topology Discovery Format) is desired. SNIA version 2 defines \fBHBA_SendRNIDV2()\fR to take a Port WWN and a Node Data Format. This fixes the bugs with multi-ported HBAs of allowing only0xDF (General Topology Discovery Format) in \fBHBA_SendRNID()\fR.