DEFINE_DLC

DEFINE_DLC defines a new DLC or modifies an existing DLC. This verb defines the DLC name, which is unique throughout the node, and some DLC-specific data, which is concatenated to the basic structure. This data is used during initialization of the DLC, and the format is specific to the DLC type (such as Token Ring). Only the DLC-specific data appended to the verb can be modified using the DEFINE_DLC verb. To do this, a STOP_DLC verb must first be issued so that the DLC is in a reset state.

See DLC Processes, Ports, and Link Stations for more information about the relationship between DLCs, ports and link stations.

VCB Structure

typedef struct define_dlc
{
        unsigned short  opcode;            /* verb operation code         */
        unsigned char   attributes;        /* verb attributes             */
        unsigned char   reserv2;           /* reserved                    */
        unsigned char   format;            /* format                      */
        unsigned short  primary_rc;        /* primary return code         */
        unsigned long   secondary_rc;      /* secondary return code       */
        unsigned char   dlc_name[8];       /* name of DLC                 */
        DLC_DEF_DATA    def_data;          /* DLC defined data            */
} DEFINE_DLC;

typedef struct dlc_def_data
{
        DESCRIPTION     description;       /* resource description        */
        unsigned char   dlc_type;          /* DLC type                    */
        unsigned char   neg_ls_supp;       /* negotiable LS support       */
        unsigned char   port_types;        /* allowable port types        */
        unsigned char   hpr_only;          /* DLC only supports HPR links:*/
        unsigned char   reserv3;           /* reserved                    */
        unsigned char   retry_flags;       /* conditions for automatic    */
                                           /* retries                     */
        unsigned short  max_activation_attempts;
                                           /* how many automatic retries? */
        unsigned short  activation_delay_timer;
                                           /* delay between automatic     */
                                           /* retries                     */
        unsigned char   reserv4[4];           /* reserved                 */
        unsigned short  dlc_spec_data_len; /* Length of DLC specific data */
} DLC_DEF_DATA;

Supplied Parameters

The application supplies the following parameters:

opcode

AP_DEFINE_DLC

attributes

The attributes of the verb. This field is a bit field. The first bit contains the visibility of the resource to be defined and corresponds to one of the following:

AP_EXTERNALLY_VISIBLE
AP_INTERNALLY_VISIBLE

format

Identifies the format of the VCB. Set this field to zero to specify the version of the VCB listed above.

dlc_name

Name of the DLC. This is an 8-byte string in a locally displayable character set. All 8 bytes are significant and must be set. For OEM devices, this name is manufacturer-specific. Valid values are LAN, SDLC, AnyNet®, or X25 (padded to 8 chars with spaces).

def_data.description

Resource description (returned on QUERY_DLC). This is a 16-byte string in a locally displayable character set. All 16 bytes are significant.

def_data.dlc_type

Type of the DLC.Personal Communications and Communications Server support the following types:

AP_ANYNET
AP_LLC2
AP_OEM_DLC
AP_SDLC
AP_X25

For EEDLC, use AP_OEM_DLC.

def_data.neg_ls_supp

Specifies whether the DLC supports negotiable link stations (AP_YES or AP_NO). If the dlc_type is AP_ANYNET, then only AP_YES is supported.

def_data.port_types

Specifies the allowable port types for the supplied dlc_type. The value corresponds to one or more of the following values ORed together.

AP_PORT_NONSWITCHED
AP_PORT_SWITCHED
AP_PORT_SATF

Use the following table to set the fields for the corresponding DLC type.

Table 1. Port Types for DLC Types
DLC Type	Port Type
AP_ANYNET	AP_PORT_SATF
AP_LLC2	AP_PORT_SATF
AP_OEM_DLC	AP_PORT_SWITCHED or AP_PORT_NONSWITCHED
AP_SDLC	AP_PORT_SWITCHED or AP_PORT_NONSWITCHED

AP_X25	AP_PORT_SWITCHED or AP_PORT_NONSWITCHED

def_data.hpr_only

This field specifies whether the DLC only supports HPR links. This must be set to AP_YES for HPR over IP links.

AP_YES
AP_NO

def_data.retry_flags

This field specifies the conditions under which link stations are subject to automatic retry. It is a bit field, and may take any of the following values bit-wise ORed together.

AP_RETRY_ON_START: Link activation will be retried if no response is received from the remote node when activation is attempted. If the underlying port is inactive when activation is attempted, the Program will attempt to activate it.
AP_RETRY_ON_FAILURE: Link activation will be retried if the link fails while active or pending active. If the underlying port has failed when activation is attempted, the Program attempts to activate it.
AP_RETRY_ON_DISCONNECT: Link activation will be retried if the link is stopped normally by the remote node.
AP_DELAY_APPLICATION_RETRIES: Link activation retries, initiated by applications (using START_LS or on-demand link activation) will be paced using the activation_delay_timer.
AP_INHERIT_RETRY: This flag has no effect.

def_data.max_activation_attempts

This field has no effect unless at least one flag is set in DEFINE_LS in def_data.retry_flags, def_data.max_activation_attempts on DEFINE_LS is set to AP_USE_DEFAULTS, and def_data.max_activation_attempts on DEFINE_PORT is set to AP_USE_DEFAULTS.

This field specifies the number of retry attempts the Program allows when the remote node is not responding, or the underlying port is inactive. This includes both automatic retries and application-driven activation attempts.

If this limit is ever reached, no further attempts are made to automatically retry. This condition is reset by STOP_LS, STOP_PORT, STOP_DLC or a successful activation. START_LS or OPEN_LU_SSCP_SEC_RQ results in a single activation attempt, with no retry if activation fails.

Zero means no limit. The value AP_USE_DEFAULTS means no limit.

def_data.activation_delay_timer

This field specifies the number of seconds that the Program waits between automatic retry attempts, and between application-driven activation attempts if the AP_DELAY_APPLICATION_RETRIES bit is set in def_data.retry_flags.

The value of zero or AP_USE_DEFAULTS results in the use of default timer duration of thirty seconds.

def_data.dlc_spec_data_len

This field should always be set to zero.

Returned Parameters

If the verb executes successfully, the Program returns the following parameter:

primary_rc: AP_OK

If the verb does not execute because of a parameter error, the Program returns the following parameters:

primary_rc: AP_PARAMETER_CHECK
secondary_rc: AP_INVALID_DLC_NAME
AP_INVALID_DLC_TYPE
AP_INVALID_RETRY_FLAGS
AP_INVALID_PORT_TYPE
AP_HPR_NOT_SUPPORTED

If the verb does not execute because of a state error, the Program returns the following parameters:

primary_rc: AP_STATE_CHECK
secondary_rc: AP_DLC_ACTIVE
AP_INVALID_DLC_TYPE
AP_CANT_MODIFY_VISIBILITY

If the verb does not execute because the node has not yet been started, the Program returns the following parameter:

primary_rc: AP_NODE_NOT_STARTED

If the verb does not execute because the node is stopping, the Program returns the following parameter:

primary_rc: AP_NODE_STOPPING

If the verb does not execute because of a system error, the Program returns the following parameter:

primary_rc: AP_UNEXPECTED_SYSTEM_ERROR