[ Previous | Next | Contents | Search ]
AIXLink/X.25 1.1 for AIX: Guide and Reference

CIO_START (Start Session) x25sioctl X.25 Device Handler Operation

Purpose

Starts an X.25 device handler session.

Description

The CIO_START x25sioctl operation starts an X.25 session. Only one X.25 session is associated with each CIO_START operation. An X.25 session can be initiated by any of the following:

If the CIO_START operation is the first one issued for a port, the operation also does the appropriate initialization (for example, downloading the microcode).

The CIO_START operation returns immediately to the caller, before the command completes. If the operation completes successfully, the X.25 device handler builds a CIO_START_DONE status block on completion. For kernel-mode processes, the status block is passed to the associated status function specified at x25sopen time. For user-mode processes, the block is placed in the associated status exception queue indicated by a / (slash).

If the immediate return indicates an error, there is no need to halt the operation. However, if the status block indicates an error, the calling process must issue a halt. An X.25 CIO_HALT operation can be called before a CIO_START_DONE status block is received. In this case, it is undefined whether or not the session generates a CIO_START_DONE status block.

Note: Read or write operations should not be performed until the CIO_START_DONE status block is received.

Parameter Block

For the CIO_START operation, the arg parameter points to an x25_start_data structure as defined in the /usr/include/sys/comio.h file. This structure contains the following fields:

sb Defines a session_blk structure as described in the /usr/include/sys/comio.h file. This structure contains the following fields:
netid Identifies the network ID. This field can be set by the caller to a correlator returned with any data received on this session.
status Identifies return values. This field is meaningful only if the return code is EIO.
session_name Specifies an ASCII name supplied by the caller for RAS purposes. This field is null-terminated if less than 16 characters.
session_id Specifies a unique ID for this session returned by the X.25 device handler. The caller must use this ID to identify the session on all subsequent calls.
session_type Specifies the type of session required.

The X.25 device handler permits a process to start a session of type SESSION_SVC_IN only if its UID is the same as that of the process that owns the session of type SESSION_SVC_LISTEN that received the incoming call.

If the session type is SESSION_SVC_OUT or SESSION_SVC_IN, then the CIO_START operation ext parameter is used. The ext parameter points to the data required for the Call Request and Call Accepted packets issued by an out or in session. This data is in the form described in the mbuf structure (found in the /usr/include/sys/x25user.h file). For a kernel-mode process, the data is an mbuf pointer. For user-mode, the data is a pointer to a buffer in user space of the same format.

For a SESSION_SVC_OUT session, the option[2] field of the status block points to the packet that completed the CIO_START operation. This is either a PKT_CALL_CONNECTED or PKT_CLEAR_INDICATION packet.

session_protocol Specifies the protocol for this session. This field is set by the caller and is valid only for a SESSION_SVC_OUT or SESSION_SVC_IN session. The protocol for SESSION_PVC is set in the configuration.

The session_protocol field accepts the following values:

PROTOCOL_ELLC Reserved.
PROTOCOL_ISO8208 No specific action. This value is used whenever no other specific protocol is wanted.
PROTOCOL_QLLC_1980 Selects SNA 1980 cause-and-diagnostic codes instead of CCITT.
PROTOCOL_QLLC_1984 Selects SNA 1984 cause-and-diagnostic codes instead of CCITT.
PROTOCOL_TCPIP No specific action.
PROTOCOL_YBTS Yellow Book Transport Service.

For this protocol, the X.25 device handler does not handle X.25 packet sequences on behalf of the user. Instead, incoming packets with the M bit set are passed to the user without waiting for the sequence to complete.

counter_id Specifies the counter to increment for any incoming data on this session. This field is set by the calling process. This field set to -1 indicates that counters are not used on this session.
Note: Counter functions are available only to user-mode processes.
session_type_data Contains additional data set by the caller. The data returned in this field depends on the value of the session_type field. Following are the possible data types:
listen_name Identifies the nickname of an entry (or collection of entries) in the router table. This must be set by the caller with the CIO_START operation when the session_type field is set to SESSION_SVC_LISTEN.
call_id Contains the incoming call ID supplied to a listening session by the device handler with an incoming call from remote data terminal equipment (DTE). This value must be set by the caller with the CIO_START operation when the session_type field is SESSION_SVC_IN.
logical_channel Specifies the logical channel number of the PVC to be acquired. This field must be set by the caller with the CIO_START operation when the session_type field is set to SESSION_PVC.
Note: When the session type is SESSION_SVC_OUT, no additional data is required.

Execution Environment

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

Return Values

A return code of -1 indicates an unsuccessful operation. The kernel sets the errno global variable to one of the following values:

EFAULT Indicates that an invalid address was specified.
EIO Indicates that an error has occurred. The error is returned in the sb.status field of the CIO_START parameter block and takes any one of the following four exception codes:

In addition, the sb.status field may take any of the following X.25-specific codes:

X25_AUTH_LISTEN Indicates the UID in the router table entry that corresponds to the listen_name field does not match the calling UID.
X25_BAD_CALL_ID Indicates the call_id field specified on a SESSION_SVC_IN session is not valid.
X25_BAD_PKT_TYPE Indicates the packet type passed by the ext parameter is not valid.
X25_CLEAR The session has been cleared.
X25_INV_CTR The counter specified in the x25_start_data field does not exist.
X25_NAME_USED Indicates the listen_name field specified on a SESSION_SVC_LISTEN session is in use by another application.
X25_NO_LINK Indicates could not connect to the link.
X25_NO_NAME Indicates the listen_name field specified on an SESSION_SVC_LISTEN session is not in the router table.
X25_NOT_PVC Indicates the channel is not defined as a PVC.
X25_PROTOCOL Indicates a protocol error occurred. For example, a SESSION_SVC_IN session was cleared by the remote DTE before it could be accepted. The clear packet can be read using the x25sread operation before issuing the halt.
X25_PVC_USED Indicates the PVC is in use by another application.
X25_TOO_MANY_VCS Indicates too many virtual circuits have been opened.
EINVAL Indicates that any of the following errors may have occurred:
  • The session_type field is not valid. This field must be set to PKT_CALL_REQ for a SESSION_SVC_OUT session or to PKT_CALL_ACCEPT for a SESSION_SVC_IN session.
  • The session_protocol field is not valid.
  • The chan parameter was not opened in the correct mode. For a SESSION_MONITOR session, the channel must be opened in M mode. For sessions of type SESSION_SVC_IN, SESSION_SVC_OUT, and SESSION_SVC_LISTEN, the channel must be opened without a mode.
EINTR Indicates that a signal was received during the call.
ENOBUFS Indicates that there are no spare buffers in the pool.
EBUSY Indicates that the number of starts for this device was exceeded. This occurs with a monitor device that can only support one start.
ENXIO Indicates that the device was not completely configured. Initial configuration must be completed before any starts can be issued.

Implementation Specifics

The CIO_START operation functions with an X.25 Interface Co-Processor/2 that has been correctly configured for use on a qualified network. Consult adapter specifications for more information on configuring the adapter and network qualifications.

Related Information

The x25sioctl entry point, x25sopen entry point, x25sread entry point.

The CIO_HALT x25sioctl X.25 Device Handler Operation.

Status Blocks for the X.25 Device Handler.

[ Previous | Next | Contents | Search ]