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
- 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
- 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.
- primary_rc
- AP_PARAMETER_CHECK
- secondary_rc
- AP_INVALID_DLC_NAME
AP_INVALID_LIST_OPTION
- primary_rc
- AP_NODE_NOT_STARTED
- primary_rc
- AP_UNEXPECTED_SYSTEM_ERROR