CIO_HALT (Halt Device) tsioctl PCI MPQP Device Handler Operation

Purpose

Ends a session with the IBM® ARTIC960Hx PCI adapter (PCI MPQP) and device handler and terminates the connection to the PCI MPQP link.

Description

The CIO_HALT operation terminates a session with the PCI MPQP device handler. The caller specifies which network ID to halt. The CIO_HALT operation removes the network ID from the network ID table and disconnects the physical link. A CIO_HALT operation must be issued for each CIO_START operation that completed successfully.

Data received for the specified network ID before the CIO_HALT operation is called can be retrieved by the caller using the tsselect and tsread entry points.

If the CIO_HALT operation terminates abnormally, the status is returned either asynchronously or as part of the CIO_HALT_DONE. Whatever the case, the CIO_GET_STAT operation is used to get information about the error. When a halt is terminated abnormally (for example, due to network failure), the following occurs:

No recovery procedure is required by the caller; however, logging the error is required.

Errors are reported on halt operations because the user could continue to be charged for connect time if the network does not recognize the halt. This error status permits a network application to be notified about an abnormal link disconnection and then take corrective action, if necessary.

The CIO_HALT 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.

Parameter Block

For the PCI MPQP CIO_HALT operation, the extptr parameter points to a session_blk structure. This structure is defined in the /usr/include/sys/comio.h file and contains the following fields:

Item Description
status Specifies the status of the port. This field is set for immediately detectable errors. Possible values for the status filed are:
  • CIO_OK
  • CIO_NETID_INV

If the calling process does not wish to sleep while the halt is in progress, the DNDELAY option can be used. In either case, the status of the halt is retrieved using the CIO_GET_STAT operation and a CIO_HALT_DONE status block is returned. The CIO_HALT_DONE status block should be used as an indication of completion.

netid Contains the network ID the caller wishes to halt. The network ID is placed in the least significant byte of the netid field.

Execution Environment

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

Return Values

The CIO_HALT operation returns common communications return values. In addition, the following PCI MPQP specific errors may be returned:

Item Description
EBUSY Indicates the device is not started or is not in a data transfer state.
ENOMEM Indicates there are no mbufs or mbuf clusters available.
ENXIO Indicates the adapter number is out of range.

Files

Item Description
/usr/include/sys/comio.h Contains the session_blk structure definition.