Technical Reference: Communications, Volume 1

DLC_GET_EXCEP ioctl Operation for DLC

The DLC_GET_EXCEP ioctl operation is selectable through the fp_ioctl kernel service or the ioctl subroutine. It can be called from the process environment only.

The following parameter block returns asynchronous exception notifications to the application user:

struct dlc_getx_arg { __ulong32_t user_sap_corr; /* user SAP corr - RETURNED */ __ulong32_t user_ls_corr; /* user ls corr - RETURNED */ __ulong32_t result_ind; /* the flags identifying the type */ /* of excep*/ int result_code; /* the manner of excep */ u_char_t result_ext[DLC_MAX_EXT];/* excep specific ext */ };

The fields of this ioctl operation are:

Field	Description
`user_sap_corr`	Indicates the user service access point (SAP) correlator for this exception.
`user_ls_corr`	Indicates the user link station (LS) correlator for this exception.
`result_ind`	Result indicators: DLC_TEST_RES Test complete: a nonextended result. Set to 1, this bit indicates that the link test has completed as indicated in the result code. DLC_SAPE_RES SAP enables: an extended result. Set to 1, this bit indicates that the SAP is active and ready for LSs to be started. See DLC_SAPE_RES operation for the format of the extension area. DLC_SAPD_RES SAP disabled: a nonextended result. Set to 1, this bit indicates that the SAP has been terminated as indicated in the result code. DLC_STAS_RES Link station started: an extended result. Set to 1, this bit indicates that the link station is connected to the remote station in asynchronous or normal disconnected mode. GDLC is waiting for link receive data from the device driver or additional commands from the user such as the DLC_CONTACT ioctl operation. See the DLC_STAS_RES operation for the format of the extension area. DLC_STAH_RES Link station halted: a nonextended result. Set to 1, this bit indicates that the LS has terminated due to a DLC_HALT_LS ioctl operation from the user, a remote discontact, or an error condition indicated in the result code. DLC_DIAL_RES Dial the phone: a nonextended result. Set to 1, this bit indicates that the user can now manually dial an outgoing call to the remote station. DLC_IWOT_RES Inactivity without termination: a nonextended result. Set to 1, this bit indicates that the LS protocol activity from the remote station has terminated for the length of time specified in the configuration (receive inactivity timeout). The local station remains active and notifies the user if the remote station begins to respond. Additional notifications of inactivity without termination are suppressed until the inactivity condition clears up. DLC_IEND_RES Inactivity ended: a nonextended result. Set to 1, this bit indicates that the LS protocol activity from the remote station has restarted after a condition of inactivity without termination. DLC_CONT_RES Contacted: a nonextended result. Set to 1, this bit indicates that GDLC has either received a Set Mode, or has received a positive response to a Set Mode initiated by the local LS. GDLC is now able to send and receive normal sequenced data on this LS. DLC_RADD_RES Remote address/name change: an extended result. Set to 1, this bit indicates that the remote LS address (or name) has been changed from the previous value. This can occur on synchronous data link control (SDLC) links when negotiating a point-to-point connection, for example. See the DLC_RADD_RES operation for the format of the extension area.
`result_code`	Indicates the result code. The following values specify the result codes for GDLC. Negative return codes that are even indicate that the error condition can be remedied by restarting the LS returning the error. Return codes that are odd indicate that the error is catastrophic, and, at the minimum, the SAP must be restarted. Additional error data may be obtained from the GDLC error log and link trace entries. DLC_SUCCESS The result indicated was successful. DLC_PROT_ERR Protocol error. DLC_BAD_DATA A bad data compare on a TEST. DLC_NO_RBUF No remote buffering on test. DLC_RDISC Remote initiated discontact. DLC_DISC_TO Discontact abort timeout. DLC_INACT_TO Inactivity timeout. DLC_MSESS_RE Mid session reset. DLC_NO_FIND Cannot find the remote name. DLC_INV_RNAME Invalid remote name. DLC_SESS_LIM Session limit exceeded. DLC_LST_IN_PRGS Listen already in progress. DLC_LS_NT_COND LS unusual network condition. DLC_LS_ROUT Link station resource outage. DLC_REMOTE_BUSY Remote station found, but busy. DLC_REMOTE_CONN Specified remote is already connected. DLC_NAME_IN_USE Local name already in use. DLC_INV_LNAME Invalid local name.
	DLC_SAP_NT_COND SAP network unusual network condition. DLC_SAP_ROUT SAP resource outage. DLC_USR_INTRF User interface error. DLC_ERR_CODE Error in the code has been detected. DLC_SYS_ERR System error.
`result_ext`	Indicates result extension. Several results carry extension areas to provide additional information about them. The user must provide a full-sized area for each result requested since there is no way to tell if the next result is extended or nonextended. The extended result areas are described by type below.

DLC_SAPE_RES SAP Enabled Result Extension

The following parameter block enables a service access point (SAP) result extension:

struct dlc_sape_res { __ulong32_t max_net_send; /* maximum write network data length */ __ulong32_t lport_addr_len; /* local port network address length */ u_char_t lport_addr[DLC_MAX_ADDR];/* the local port address */ };

The fields of this extension are:

Field	Description
`max_net_send`	Indicates the maximum number of bytes that the user can write for each packet when writing network data. This is generally based on a communications mbuf/mbufs page cluster size, but is not necessarily limited to a single mbuf structure since mbuf clusters can be linked.
`lport_addr_len`	Indicates the byte length of the local port network address.
`lport_addr`	Indicates the hexadecimal value of the local port network address.

DLC_STAS_RES Link Station Started Result Extension

The following parameter block starts a link station (LS) result extension:

struct dlc_stas_res { ulong32_t maxif; /* max size of the data sent */ /* on a write */ ulong32_t rport_addr_len; /* remote port network address */ /* length */ u_char_t rport_addr[DLC_MAX_ADDR]; /* remote port address */ ulong32_t rname_len; /* remote network name length */ u_char_t rname[DLC_MAX_NAME]; /* remote network name */ uchar_t res[3]; /* reserved */ uchar_t rsap; /* remote SAP */ ulong32_t max_data_off; /* the maximum data offsets for sends*/ };

The fields of this extension are:

Field	Description
`maxif`	Contains the maximum byte size allowable for user data. This value is derived from the value supplied by the user at the start link station (DLC_START_LS) and the actual number of bytes that can be handled by the GDLC and device handler on a single transmit or receive. Generally this value is less than the size of a communications mbuf page cluster. However, some communications devices may be able to link page clusters together, so the maximum I-field receivable may exceed the length of a single mbuf cluster. The returned value never exceeds the value supplied by the user, but may be smaller if buffering is not large enough to hold the specified value.
`rport_addr_len`	Contains the byte length of the remote port network address.
`rport_addr`	Contains the hexadecimal value of the remote port network address.
`rname_len`	Contains the byte length of the remote port network name. This is returned only when name discovery procedures are used to locate the remote station. Otherwise this field is set to 0 (zero). Network names can be 1 to 20 characters in length.
`rname`	Contains the name used by the remote SAP. This field is valid only if name-discovery procedures were used to locate the remote station.
`rsap`	Contains the hexadecimal value of the remote SAP address.
`max_data_off`	Contains the write data offset in bytes of a communications mbuf cluster where transmit data must minimally begin. This allows ample room for the DLC and MAC headers to be inserted if needed. Some DLCs may be able to prepend additional mbuf clusters for their headers, and in this case will set this field to 0 (zero). This field is only valid for kernel users that pass in a communications mbuf structure on write operations. Note To align the data moves to a particular byte boundary, the kernel user may wish to choose a value larger than the minimum value returned.

DLC_STAH_RES Link Station Halted Result Extension

The following parameter block halts the link station (LS) result extension:

struct dlc_stah_res { __ulong32_t conf_ls_corr; /* conflicting link station corr */ };

The field of this extension is:

Field	Description
`conf_ls_corr`	Indicates conflicting link station correlator. Contains the user's link station identifier that already has the specified remote station attached.

This extension is valid only if the result code value indicates -936 (specified remote is already connected).

DLC_RADD_RES Remote Address/Name Change Result Extension

The following parameter block changes the remote address or name of the result extension:

struct dlc_radd_res { __ulong32_t rname_len; /* remote network name/addr length */ u_char rname[DLC_MAX_NAME];/* remote network name/addr */ };

The fields of this extension are:

Field	Description
`rname_len`	Indicates the remote network address or name length. Contains the byte length of the updated remote SAP's network address or name.
`rname`	Contains the updated address or name being used by the remote SAP.