CIO_GET_STAT (Get Status) mpioctl MPQP Device Handler Operation

Purpose

Note: This function is supported in AIX® 5.1 and earlier only.

Gets the status of the current Multiprotocol Quad Port (MPQP) adapter and device handler.

Description

Note: Only user-mode processes can use the CIO_GET_STAT operation.

The CIO_GET_STAT operation gets the status of the current MPQP adapter and device handler. For the MPQP device handler, both solicited and unsolicited status can be returned.

Solicited status is status information that is returned as a completion status to a particular operation. The CIO_START, CIO_HALT, and mpwrite operations all have solicited status returned. However, for many asynchronous events common to wide-area networks, these are considered unsolicited status. The asynchronous events are divided into three classes:

The CIO_GET_STAT operation functions with a 4-Port Multiprotocol Interface adapter that has been correctly configured for use on a qualified network. Consult the adapter specifications for more information on configuring the adapter and network qualifications.

Status Blocks for the Multiprotocol Device Handler

For the CIO_GET_STAT operation, the extptr parameter points to a status_block structure. When returned, the device handler fills this structure with the appropriate information. The status_block structure is defined in the /usr/include/sys/comio.h file and returns one of seven possible status conditions:

Status blocks are used to communicate status and exception information to user-mode processes.

User-mode processes receive a status block whenever they request a CIO_GET_STAT operation. A user-mode process can wait for the next available status block by issuing a mpselect entry point with the specified POLLPRI event.

Status blocks contain a code field and possible options. The code field indicates the type of status block code (for example, CIO_START_DONE). Seven possible MPQP status blocks exist:

CIO_ASYNC_STATUS Status Block

Asynchronous status notifies the data link control of asynchronous events such as network and adapter failures.

Code CIO_ASYNC_STATUS
option[0] Can be one of the following:
  MP_DSR_DROPPED, MP_RCV_TIMEOUT, MP_RELOAD_CMPL, MP_RESET_CMPL, MP_X21_CLEAR
option[1] Not used
option[2] Not used
option[3] Not used
Note: The MP_RELOAD_C and MPLMP_RESET_CMPL values are for diagnostic use only.

CIO_HALT_DONE Status Block

The CIO_HALT operation ends a session with the MPQP device handler. On a successfully completed Halt Device operation, the following status block is provided:

Code CIO_HALT_DONE
option[0] CIO_OK
option[1] MP_FORCED_HALT or MP_NORMAL_HALT
option[2] MP_NETWORK_FAILURE or MP_HW_FAILURE

A forced halt is a halt completed successfully in terms of the data link control is concerned, but terminates forcefully because of either an adapter error or a network error. This is significant for X.21 or other switched networks where customers can be charged if the call does not disconnect properly.

Note: When using the X.21 physical interface, X.21 centralized multiport (multidrop) operation on a leased-circuit public data network is not supported.

CIO_START_DONE Status Block

On a successfully completed CIO_START operation, the following status block is provided:

Code CIO_START_DONE
option[0] CIO_OK
option[1] Network ID
option[2] Not used
option[3] Not used

On an unsuccessful Start Device CIO_START mpioctl operation, the following status block is provided:

Code CIO_START_DONE
option[0] Can be one of the following:
MP_ADAP_NOT_FUNC
Adapter not functional
MP_TX_FAILSAFE_TIMEOUT
Transmit command did not complete.
MP_DSR_ON_TIMEOUT
DSR failed to come on.
MP_DSR_ALRDY_ON
DSR already on for a switched line.
MP_X21_RETRIES_EXC
X.21 retries exceeded. Call not completed.
MP_X21_TIMEOUT
X.21 timer expired.
MP_X21_CLEAR
Unexpected clear received from the DCE.
option[1] If the option[0] field is set to MP_X21_TIMEOUT, the option[1] field contains the specific X.21 timer that expired.
option[2] Not used.
option[3] Not used.

CIO_TX_DONE Status Block

On completion of a multiprotocol transmit, the following status block is provided:

Code CIO_TX_DONE
option[0] Can be one of the following:
CIO_OK
MP_TX_UNDERRUN
MP_X21_CLEAR
MP_TX_FAILSAFE_TIMEOUT
The transmit command did not complete.
MP_TX_ABORT
Transmit aborted due to CIO_HALT operation.
option[1] Identifies the write_id field supplied by the caller in the write command if TX_ACK was selected.
option[2] Points to the buffer with transmit data.
option[3] Not used.

MP_END_OF_AUTO_RESP Status Block

The MP_STOP_AR mpioctl operation has completed. The adapter is in Normal Receive mode. All receive data is routed to the data link control.

Code MP_END_OF_AUTO_RESP
option[0] CIO_OK
option[1] Not used
option[2] Not used
option[3] Not used

MP_RDY_FOR_MAN_DIAL Status Block

The manual dial switched line is ready for dialing. The start operation is pending the call completion.

Code MP_RDY_FOR_MAN_DIAL
option[0] CIO_OK
option[1] Not used
option[2] Not used
option[3] Not used

MP_THRESH_EXC Status Block

A threshold for one of the counters defined in the start profile has reached its threshold.

Code MP_THRESH_EXC
option[0] Indicates the expired threshold.
  The following values are returned to indicate the threshold that was exceeded: MP_TOTAL_TX_ERR, MP_TOTAL_RX_ERR, MP_TX_PERCENT, MP_RX_PERCENT
option[1] Not used.
option[2] Not used.
option[3] Not used.

Execution Environment

The CIO_GET_STAT operation can be called from the process environment only.

Return Values

The return codes for the CIO_GET_STAT operation are:

Return Code Description
ENOMEM Indicates no mbufs or mbuf clusters are available.
ENXIO Indicates the adapter number is out of range.