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.
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.
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 |
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.
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:
|
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:
|
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. |
The CIO_GET_STAT operation can be called from the process environment only.
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. |