HBA_SendCTPassThru(3HBAAPI)		      Common Fibre Channel HBA Information Library Functions		       HBA_SendCTPassThru(3HBAAPI)

NAME

       HBA_SendCTPassThru, HBA_SendCTPassThruV2 - end a Fibre Channel Common Transport request to a Fabric

SYNOPSIS

       cc [ flag... ] file... -lHBAAPI [ library... ]
       #include <hbaapi.h>

       HBA_STATUS HBA_SendCTPassThru(HBA_HANDLE handle, void *pReqBuffer, HBA_UINT32 ReqBufferSize, void *pRspBuffer, HBA_UINT32 RspBufferSize);

       HBA_STATUS  HBA_SendCTPassThruV2(HBA_HANDLE  handle,  HBA_WWN  hbaPortWWN,  void  *pReqBuffer,  HBA_UINT32 ReqBufferSize, void *pRspBuffer,
       HBA_UINT32 *RspBufferSize);

PARAMETERS

       handle	       an open handle returned from HBA_OpenAdapter(3HBAAPI)

       hbaPortWWN      the Port Name of the local HBA Port through which the caller is issuing the CT request

       pReqBuffer      a pointer to a CT_IU request. The contents of the buffer must be in big-endian byte order

       ReqBufferSize   the length of the CT_IU request buffer pReqBuffer

       pRspBuffer      a pointer to a CT_IU response buffer. The response received from the fabric is copied into this buffer in  big-endian  byte
		       order.  Success	of  the function need not imply success of the command. The CT_IU Command/Response field should be checked
		       for the Accept Response code.

       RspBufferSize
		       HBA_SendCTPassThru()

			   the length of the CT_IU accept response buffer pRspBuffer.

		       HBA_SendCTPassThruV2()

			   a Pointer to the length of the CT_IU accept response buffer pRspBuffer.

DESCRIPTION

       The HBA_SendCTPassThru() and HBA_SendCTPassThruV2() functions provide access to the standard in-band fabric management interface. The  pRe-
       qBuffer	argument  is interpreted as a CT_IU request, as defined by the T11 specification FC-GS-3, and is routed in the fabric based on the
       GS_TYPE field.

RETURN VALUES

       Upon successful transport and receipt of a CT_IU response, HBA_SendCTPassThru() returns HBA_STATUS_OK. The CT_IU payload indicates  whether
       the  command was accepted by the fabric based on the Command/Response code returned.  Otherwise, an error value is returned from the under-
       lying VSL and the values in pRspBuffer are undefined.

       Upon successful transport and receipt of a CT_IU response,  HBA_SendCTPassThruV2()  returns  HBA_STATUS_OK.  The  CT_IU	payload  indicates
       whether the command was accepted by the fabric based on the Command/Response code returned.   Otherwise, an error code is returned from the
       underlying VSL, and the values in pRspBuffer are undefined. The HBA_SendCTPassThruV2() function returns the following values:

       HBA_STATUS_ERROR_ILLEGAL_WWN

	   The value of hbaPortWWN is not a valid port WWN on the specified HBA.

       HBA_STATUS_ERROR

	   An error occurred.

ERRORS

       See libhbaapi(3LIB) for general error status values.

EXAMPLES

       Example 1: Data structures for the GIEL command.

       struct ct_iu_preamble {
	   uint32_t  ct_rev	   : 8,
		     ct_inid	   : 24;
	   uint32_t  ct_fcstype    : 8,
		     ct_fcssubtype : 8,
		     ct_options    : 8,
		     ct_reserved1  : 8;
	   uint32_t  ct_cmdrsp	   : 16,
		     ct_aiusize    : 16;
	   uint32_t  ct_reserved2  : 8,
		     ct_reason	   : 8,
		     ct_expln	   : 8,
		     ct_vendor	   : 8;
       };
       struct gs_ms_ic_elem {
	   uchar_t   elem_name[8];
	   uint32_t  reserved1	 : 24,
		     elem_type	 : 8;
       };
       struct gs_ms_giel_rsp {
	   struct ct_iu_preamble  ct_header;
	   uint32_t		  num_elems;
       struct gs_ms_ic_elem   elem_list[1];
       };
       #define MAX_PAYLOAD_LEN 65536 /* 64K */

       Example 2: Send an GIEL Management Service command through the given HBA handle.

       The following example sends an GIEL Management Service command through the given HBA handle.

       req.ct_rev	 = 0x01;
       req.ct_fcstype	 = 0xFA;   /* Management Service */
       req.ct_fcssubtype = 0x01;   /* Config server */
       req.ct_cmdrsp	 = 0x0101; /* GIEL command */
       req.ct_aiusize	 = MAX_PAYLOAD_LEN / 4 -
		sizeof (struct ct_iu_preamble) / 4;
       if ((status = HBA_SendCTPassThru(handle, &req, sizeof (req),
	       rsp, MAX_PAYLOAD_LEN)) != HBA_STATUS_OK) {
	   fprintf(stderr, "Unable to issue CT command on
	       " for reason %d0, adaptername, status);
       } else {
	   giel = (struct gs_ms_giel_rsp *)rsp;
	   if (giel->ct_header.ct_cmdrsp != 0x8002) {
	       fprintf(stderr, "CT command rejected on HBA "
		   "
	   } else {
	       for (cntr = 0; cntr < giel->num_elems; cntr++) {
	       memcpy(&wwn, giel->elem_list[cntr].elem_name, 8);
	       printf(" Fabric element name: %016llx0, wwn);
	       }
	   }
       }

ATTRIBUTES

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Standard: FC-MI  1.92  (API  |
       |			     |version 1)		   |
       +-----------------------------+-----------------------------+
       |			     |Standard:  FC-HBA Version 4  |
       |			     |(API version 2)		   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |Safe			   |
       +-----------------------------+-----------------------------+

SEE ALSO

       HBA_OpenAdapter(3HBAAPI), libhbaapi(3LIB), attributes(5)

       T11 FC-MI Specification

BUGS

       The HBA_SendCTPassThru() function does not take a portindex 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 always being sent on port 0 of the HBA.
	SNIA  version  2  defines  HBA_SendCTPassThruV2()  which  takes  a  Port WWN as an argument.  This fixes the bug with multi-ported HBAs in
       HBA_SendCTPassThru().

SunOS 5.10							    1 Sep 2003					       HBA_SendCTPassThru(3HBAAPI)