QUERY_DLC

QUERY_DLC returns a list of information about the DLCs defined at the node. This information is structured as determined data (data gathered dynamically during execution) and defined data (the data supplied by the application on DEFINE_DLC).

The information is returned as a list in one of two formats, either summary or detailed information. To obtain information about a specific DLC, or to obtain the list information in several chunks, the dlc_name field should be set. Otherwise (if the list_options field is set to AP_FIRST_IN_LIST), this field will be ignored. See Querying the Node for background on how the list formats are used.

This list is ordered by the dlc_name. Ordering is by name length first, and then by ASCII lexicographical ordering for names of the same length (in accordance with normal MIB ordering).

If AP_LIST_FROM_NEXT is selected the returned list starts from the next entry according to the defined ordering (whether the specified entry exists or not).

VCB Structure

typedef struct query_dlc
{
        unsigned short  opcode;            /* verb operation code         */
        unsigned char   attributes;        /* ver attributes              */
        unsigned char   format;            /* format                      */
        unsigned short  primary_rc;        /* primary return code         */
        unsigned long   secondary_rc;      /* secondary return code       */
        unsigned char   *buf_ptr;          /* pointer to buffer           */
        unsigned long   buf_size;          /* buffer size                 */
        unsigned long   total_buf_size;    /* total buffer size required  */
        unsigned short  num_entries;       /* number of entries           */
        unsigned short  total_num_entries; /* total number of entries     */
        unsigned char   list_options;      /* listing options             */
        unsigned char   reserv3;           /* reserved                    */
        unsigned char   dlc_name[8];       /* name of DLC                 */
} QUERY_DLC;
typedef struct dlc_summary
{
        unsigned short  overlay_size;      /* size of this entry          */
        unsigned char   dlc_name[8];       /* name of DLC                 */
        unsigned char   description[RD_LEN];
                                           /* resource description        */
        unsigned char   state;             /* State of the DLC            */
        unsigned char   dlc_type;          /* DLC type                    */
} DLC_SUMMARY;
typedef struct dlc_detail
{
        unsigned short  overlay_size;      /* size of this entry          */
        unsigned char   dlc_name[8];       /* name of DLC                 */
        unsigned char   reserv2[2];        /* reserved                    */
        DLC_DET_DATA     det_data;         /* Determined data             */
        DLC_DEF_DATA     def_data;         /* Defined data                */
} DLC_DETAIL;
typedef struct dlc_det_data
{
        unsigned char   state;             /* State of the DLC            */
        unsigned char   reserv3[3];        /* reserved                    */
        unsigned char   reserva[20];       /* reserved                    */
} DLC_DET_DATA;
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   retry_flags;       /* conditions for automatic    */
                                           /* retries                     */
        unsigned short  max_activaion_attempts;
                                           /* how many automatic retries? */
        unsigned short  activation_delay_timer;
                                           /* delay between automatic     */
                                           /* retries                     */
        unsigned char   reserv3[6];        /* 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_QUERY_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.
buf_ptr
Pointer to a buffer into which list information can be written. The application can append data to the end of the VCB, in which case buf_ptr must be set to NULL.
buf_size
Size of buffer supplied. The data returned will not exceed this size.
num_entries
Maximum number of entries to return. The number of entries will not exceed this value. A value of zero means no limit.
list_options
This indicates what should be returned in the list information:
AP_SUMMARY
Returns summary information only.
AP_DETAIL
Returns detailed information.

The dlc_name specified (see the following parameter, dlc_name) represents an index value that is used to specify the starting point of the actual information to be returned.

AP_FIRST_IN_LIST
The index value is ignored, and the returned list starts from the first entry in the list.
AP_LIST_FROM_NEXT
The returned list starts from the next entry in the list after the one specified by the supplied index value.
AP_LIST_INCLUSIVE
The returned list starts from the entry specified by the index value.
dlc_name
DLC name. This is an 8-byte string in a locally displayable character set. All 8 bytes are significant and must be set. This field is ignored if list_options is set to AP_FIRST_IN_LIST.

Returned Parameters

If the verb executes successfully, the Program returns the following parameters:
primary_rc
AP_OK
buf_size
Length of the information returned in the buffer.
total_buf_size
Returned value indicating the size of buffer that would have been required to return all the list information requested. This can be higher than buf_size.
num_entries
Number of entries actually returned.
total_num_entries
Total number of entries that could have been returned. This can be higher than num_entries.
dlc_summary.overlay_size
The number of bytes in this entry, and hence the offset to the next entry returned (if any).
dlc_summary.dlc_name
DLC name. This is an 8-byte string in a locally displayable character set. All 8 bytes are significant.
dlc_summary.description
Resource description (as specified on DEFINE_DLC). This is a 16-byte string in a locally displayable character set. All 16 bytes are significant.
dlc_summary.state
State of the DLC. This field is set to one of the following values:

AP_ACTIVE
AP_NOT_ACTIVE
AP_PENDING_INACTIVE

dlc_summary.dlc_type
Type of DLC. The Program supports the following types:

AP_ANYNET
AP_LLC2
AP_OEM_DLC
AP_SDLC
AP_X25

dlc_detail.overlay_size
The number of bytes in this entry (including dlc_spec_data), and hence the offset to the next entry returned (if any).
dlc_detail.dlc_name
DLC name. This is an 8-byte string in a locally displayable character set. All 8 bytes are significant.
dlc_detail.det_data.state
State of the DLC. This field is set to one of the following values:

AP_ACTIVE
AP_NOT_ACTIVE
AP_PENDING_INACTIVE

dlc_detail.def_data.description
Resource description (as specified on DEFINE_DLC). This is a 16-byte string in a locally displayable character set. All 16 bytes are significant.
dlc_detail.def_data.dlc_type
Type of DLC. The Program supports the following types:

AP_ANYNET
AP_LLC2
AP_OEM_DLC
AP_SDLC
AP_X25

dlc_detail.def_data.neg_ls_supp
Specifies whether the DLC supports negotiable link stations (AP_YES or AP_NO).
dlc_detail.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

dlc__detail.def_data.retry_flags
This field specifies the conditions under which link stations, defined on this DLC, are subject to automatic retry if the flag AP_INHERIT_RETRY is set on both DEFINE_LS and DEFINE_PORT in def_data.retry_flags. It is a bit field, and may take any of the following values bitwise 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.
dlc_detail.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'.

dlc_detail.def_data.activation_delay_timer
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 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.

dlc_detail.def_data.dlc_spec_data_len
Unpadded length, in bytes, of data specific to the type of DLC. The data will be concatenated to the DLC_DETAIL structure. This data will be padded to end on a 4-byte boundary. This field should always be set to zero.
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_LIST_OPTION

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 of a system error, the Program returns the following parameter:
primary_rc
AP_UNEXPECTED_SYSTEM_ERROR