QUERY_LS

QUERY_LS returns a list of information about the link stations 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_LS).

The information is returned as a list in one of two formats, either summary or detailed information. To obtain information about a specific LS, or to obtain the list information in several chunks, the ls_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 ls_name. Ordering is according to name length first, and then by ASCII lexicographical ordering for names of the same length (in accordance with IBM's 6611 APPN® 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).

The list of link stations returned can be filtered by the name of the port that they belong to. In this case, the port_name field should be set (otherwise this field should be set to all zeros).

VCB Structure

Format 1

typedef struct query_ls
{
        unsigned short  opcode;             /* verb operation code            */
        unsigned char   attributes;         /* Verb 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   ls_name[8];         /* name of link station           */
        unsigned char   port_name[8];       /* name of link station           */
} QUERY_LS;

typedef struct ls_summary
{
        unsigned short  overlay_size;       /* size of this entry             */
        unsigned char   ls_name[8];         /* link station name              */
        unsigned char   description[RD_LEN];
                                            /* resource description           */
        unsigned char   dlc_type;           /* DLC type                       */
        unsigned char   state;              /* link station state             */
        unsigned short  act_sess_count;     /* currently active sess count    */
        unsigned char   det_adj_cp_name[17];
                                            /* determined adj CP name         */
        unsigned char   det_adj_cp_type;    /* determined adj node type       */
        unsigned char   port_name[8];       /* port name                      */
        unsigned char   adj_cp_name[17];    /* adjacent CP name               */
        unsigned char   adj_cp_type;        /* adjacent node type             */
} LS_SUMMARY;

typedef struct ls_detail
{
        unsigned short  overlay_size;       /* size of this entry             */
        unsigned char   ls_name[8];         /* link stations name             */
        LS_DET_DATA     det_data;           /* determined data                */
        LS_DEF_DATA     def_data;           /* defined data                   */
} LS_DETAIL;

typedef struct ls_det_data
{
        unsigned short  act_sess_count;     /* curr active sessions count     */
        unsigned char   dlc_type;           /* DLC type                       */
        unsigned char   state;              /* link station state             */
        unsigned char   sub_state;          /* link station sub state         */
        unsigned char   det_adj_cp_name[17];
                                            /* adjacent CP name               */
        unsigned char   det_adj_cp_type;    /* adjacent node type             */
        unsigned char   dlc_name[8];        /* name of DLC                    */
        unsigned char   dynamic;            /* is LS is dynamic ?             */
        unsigned char   migration;          /* supports migration partners    */
        unsigned char   tg_num;             /* TG number                      */
        LS_STATS        ls_stats;           /* link station statistics        */
        unsigned long   start_time;         /* time LS started                */
        unsigned long   stop_time;          /* time LS stopped                */
        unsigned long   up_time;            /* total time LS active           */
        unsigned long   current_state_time; /* time in current state          */
        unsigned char   deact_cause;        /* deactivation cause             */
        unsigned char   hpr_support;        /* TG HPR support                 */
        unsigned char   anr_label[2];       /* local ANR label                */
        unsigned char   hpr_link_lvl_error; /* HPR link-level error           */
        unsigned char   auto_act;           /* auto activate                  */
        unsigned char   ls_role;            /* link station role              */
        unsigned char   reserva;            /* reserved                       */
        unsigned char   node_id[4];         /* determined node id             */
        unsigned short  active_isr_count;   /* currently active ISR sessions  */
        unsigned short  active_lu_sess_count;
                                            /* active LU-LU session count     */
        unsigned short  active_sscp_sess_count;
                                            /* active SSCP session count      */
        ANR_LABEL       reverse_anr_label;  /* reverse ANR label              */
        LINK STATION    local_address;      /* local LS address               */
        unsigned short  max_send_btu_size;  /* negotiated max BTU length      */
        unsigned char   brnn_link_type;     /* branch link type               */
        unsigned char   adj_cp_is_brnn;     /* adjacent CP is a BrNN          */
        unsigned char   mltg_member;        /* Reserved                       */
        unsigned char   tg_sharing;         /* Reserved                       */
        unsigned char   reservb[6];         /* reserved                       */
} LS_DET_DATA;

typedef struct anr_label
{
        unsigned short  length;           /* ANR label length                 */
        unsigned short  reserv;           /* reserved                         */
        unsigned char   label[MAX_ANR_LABEL_SIZE];
                                          /* ANR label                        */
} ANR_LABEL;

typedef struct ls_def_data
{
        unsigned char   description[RD_LEN];
                                            /* resource description           */
        unsigned char   port_name[8];       /* name of associated port        */
        unsigned char   adj_cp_name[17];    /* adjacent CP name               */
        unsigned char   adj_cp_type;        /* adjacent node type             */
        LINK_ADDRESS    dest_address;       /* destination address            */
        unsigned char   auto_act_supp;      /* auto-activate supported        */
        unsigned char   tg_number;          /* Pre-assigned TG number         */
        unsigned char   limited_resource;   /* limited resource               */
        unsigned char   solicit_sscp_sessions;
                                            /* solicit SSCP sessions          */
        unsigned char   pu_name[8];         /* Local PU name (reserved if     */
                                            /* solicit_sscp_sessions is set   */
                                            /* to AP_NO)                      */
        unsigned char   disable_remote_act; /* disable remote activation flag */
        unsigned char   dspu_services;      /* Services provided for          */
                                            /* downstream PU                  */
        unsigned char   dspu_name[8];       /* Downstream PU name (reserved   */
                                            /* if dspu_services is set to     */
                                            /* AP_NONE or AP_DLUR)            */
        unsigned char   dlus_name[17];      /* DLUS name if dspu_services     */
                                            /* is set to AP_DLUR              */
        unsigned char   bkup_dlus_name[17]; /* Backup DLUS name if            */
                                            /* dspu_services is set           */
                                            /* to AP_DLUR                     */
        unsigned char   hpr_supported;      /* does the link support HPR?     */
        unsigned char   hpr_link_lvl_error; /* does the link support HPR      */
                                            /* link-level error recovery?     */
        unsigned short  link_deact_timer;   /* HPR link deactivation timer    */
        unsigned char   reserv1;            /* reserved                       */
        unsigned char   default_nn_server;  /* Use as default LS to NN server */
        unsigned char   ls_attributes[4];   /* LS attributes                  */
        unsigned char   adj_node_id[4];     /* adjacent node ID               */
        unsigned char   local_node_id[4];   /* local node ID                  */
        unsigned char   cp_cp_sess_support; /* CP-CP session support          */
        unsigned char   use_default_tg_chars;
                                            /* Use default tg_chars           */
        TG_DEFINED_CHARS tg_chars;          /* TG characteristics             */
        unsigned short  target_pacing_count;
                                            /* target pacing count            */
        unsigned short  max_send_btu_size;  /* max send BTU size              */
        unsigned char   ls_role;            /* link station role to use       */
                                            /* on this link                   */
        unsigned char   max_ifrm_rcvd;      /* max number of I-frames rcvd    */
        unsigned short  dlus_retry_timeout; /* DLUS retry timeout             */
        unsigned short  dlus_retry_limit;   /* DLUS retry limit               */
        unsigned char   conventional_lu_compression;
                                            /* Data compression requested for */
                                            /* conventional LU sessions       */
        unsigned char   conventional_lu_cryptography;
                                            /* Cryptography required for      */
                                            /* conventional LU sessions       */
        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   branch_link_type;   /* branch link type               */
        unsigned char   adj_brnn_cp_support;/* adjacent BrNN CP support       */
        unsigned char   reserv4[20];        /* reserved                       */
        unsigned short  link_spec_data_len; /* length of link specific data   */
} LS_DEF_DATA;

typedef struct link_address
{
        unsigned short  length;             /* length                         */
        unsigned short  reserve1;           /* reserved                       */
        unsigned char   address[MAX_LINK_ADDR_LEN];
                                            /* address                        */
} LINK_ADDRESS;

typedef struct link_spec_data
{
       unsigned char  link_data[SIZEOF_LINK_SPEC_DATA];

}  LINK_SPEC_DATA;

typedef struct tg_defined_chars
{
        unsigned char   effect_cap;         /* Effective capacity             */
        unsigned char   reserve1[5];        /* Reserved                       */
        unsigned char   connect_cost;       /* Connection Cost                */
        unsigned char   byte_cost;          /* Byte cost                      */
        unsigned char   reserve2;           /* Reserved                       */
        unsigned char   security;           /* Security                       */
        unsigned char   prop_delay;         /* Propagation delay              */
        unsigned char   modem_class;        /* Modem class                    */
        unsigned char   user_def_parm_1;    /* User-defined parameter 1       */
        unsigned char   user_def_parm_2;    /* User-defined parameter 2       */
        unsigned char   user_def_parm_3;    /* User-defined parameter 3       */
} TG_DEFINED_CHARS;

typedef struct ls_stats
{
        unsigned long   in_xid_bytes;       /* number of XID bytes received   */
        unsigned long   in_msg_bytes;       /* num message bytes received     */
        unsigned long   in_xid_frames;      /* num XID frames received        */
        unsigned long   in_msg_frames;      /* num message frames received    */
        unsigned long   out_xid_bytes;      /* num XID bytes sent             */
        unsigned long   out_msg_bytes;      /* num message bytes sent         */
        unsigned long   out_xid_frames;     /* num XID frames sent            */
        unsigned long   out_msg_frames;     /* num message frames sent        */
        unsigned long   in_invalid_sna_frames;
                                            /* num invalid frames received    */
        unsigned long   in_session_control_frames;
                                            /* num control frames received    */
        unsigned long   out_session_control_frames;
                                            /* num control frames sent        */
        unsigned long   echo_rsps;          /* response from adj LS count     */
        unsigned long   current_delay;      /* time taken for last test sig   */
        unsigned long   max_delay;          /* max delay by test signal       */
        unsigned long   min_delay;          /* min delay by test signal       */
        unsigned long   max_delay_time;     /* time since longest delay       */
        unsigned long   good_xids;          /* successful XID on LS count     */
        unsigned long   bad_xids;           /* unsuccessful XID on LS count   */
} LS_STATS;

VCB Structure

Format 0 (back-level)

typedef struct ls_det_data
{
        unsigned short  act_sess_count;     /* curr active sessions count     */
        unsigned char   dlc_type;           /* DLC type                       */
        unsigned char   state;              /* link station state             */
        unsigned char   sub_state;          /* link station sub state         */
        unsigned char   det_adj_cp_name[17];
                                            /* adjacent CP name               */
        unsigned char   det_adj_cp_type;    /* adjacent node type             */
        unsigned char   dlc_name[8];        /* name of DLC                    */
        unsigned char   dynamic;            /* is LS is dynamic ?             */
        unsigned char   migration;          /* supports migration partners    */
        unsigned char   tg_num;             /* TG number                      */
        LS_STATS        ls_stats;           /* link station statistics        */
        unsigned long   start_time;         /* time LS started                */
        unsigned long   stop_time;          /* time LS stopped                */
        unsigned long   up_time;            /* total time LS active           */
        unsigned long   current_state_time; /* time in current state          */
        unsigned char   deact_cause;        /* deactivation cause             */
        unsigned char   hpr_support;        /* TG HPR support                 */
        unsigned char   anr_label[2];       /* local ANR label                */
        unsigned char   hpr_link_lvl_error; /* HPR link-level error           */
        unsigned char   auto_act;           /* auto activate                  */
        unsigned char   ls_role;            /* link station role              */
        unsigned char   reserva;            /* reserved                       */
        unsigned char   node_id[4];         /* determined node id             */
        unsigned short  active_isr_count;   /* currently active ISR sessions  */
        unsigned char   reservb[30];        /* reserved                       */
} LS_DET_DATA;

Supplied Parameters

The application supplies the following parameters:

opcode

AP_QUERY_LS

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 one to specify the format 1 version of the VCB listed above. If this is set to 0, the Program returns the format 0 LS_DET_DATA structure.

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 ls_name specified (see the following parameter, ls_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.

ls_name

Link station 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.

port_name

Port name filter. This should be set to all zeros or an 8-byte alphanumeric type A EBCDIC string (starting with a letter), padded to the right with EBCDIC spaces. If this field is set then only link stations belonging to this port are returned. This field is ignored if it is set to all zeros.

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.

ls_summary.overlay_size

The number of bytes in this entry, and hence the offset to the next entry returned (if any).

ls_summary.ls_name

Name of link station. This is an 8-byte string in a locally displayable character set. All 8 bytes are significant.

ls_summary.description

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

ls_summary.dlc_type

Type of DLC. The Program supports the following types:

AP_ANYNET
AP_LLC2
AP_OEM_DLC
AP_SDLC
AP_X25

Additional DLC types can be defined by specifying the new type on the DEFINE_DLC verb. See DEFINE_DLC for more information.

ls_summary.state

State of this link station. This field is set to one of the following values:

AP_NOT_ACTIVE
AP_PENDING_ACTIVE
AP_ACTIVE
AP_PENDING_INACTIVE

ls_summary.act_sess_count

The total number of active sessions (both endpoint and intermediate) using the link.

ls_summary.det_adj_cp_name

Fully qualified, 17-byte, adjacent CP name determined during link activation. It is composed of two type-A EBCDIC character strings concatenated by an EBCDIC dot, and is right-padded with EBCDIC spaces. (Each name can have a maximum length of 8 bytes with no embedded spaces.) This will be null if the LS is inactive.

If ls_summary.adj_cp_type is not one of AP_NETWORK_NODE, AP_END_NODE, AP_APPN_NODE, or AP_BACK_LEVEL_LEN_NODE, then this field is reserved.

ls_summary.det_adj_cp_type

Type of the adjacent node determined during link activation. It is one of the following values:

AP_END_NODE
AP_NETWORK_NODE
AP_LEARN_NODE
AP_VRN

This will be AP_LEARN_NODE if the LS is inactive.

If ls_summary.adj_cp_type is not one of AP_NETWORK_NODE, AP_END_NODE, AP_APPN_NODE, or AP_BACK_LEVEL_LEN_NODE, then this field is reserved.

ls_summary.port_name

Name of port associated with this link station. This is an 8-byte string in a locally displayable character set. All 8 bytes are significant.

ls_summary.adj_cp_name

Fully qualified, 17-byte, adjacent control point name composed of two type-A EBCDIC character strings concatenated by an EBCDIC dot, which is right-padded with EBCDIC spaces. (Each name can have a maximum length of 8 bytes with no embedded spaces.) This will be null for an implicit link.

ls_summary.adj_cp_type

Type of the adjacent node. It is one of the following values:

AP_END_NODE
AP_NETWORK_NODE
AP_APPN_NODE
AP_BACK_LEVEL_LEN__NODE
AP_HOST_XID3
AP_HOST_XID0
AP_DSPU_XID
AP_DSPU_NOXID

ls_detail.overlay_size

The number of bytes in this entry, and hence the offset to the next entry returned (if any).

ls_detail.ls_name

Name of link station. This is an 8-byte string in a locally displayable character set. All 8 bytes are significant.

ls_detail.det_data.act_sess_count

Total number of active sessions (both endpoint and intermediate) using the link.

ls_detail.det_data.dlc_type

Type of DLC. The Program supports the following types:

AP_ANYNET
AP_LLC2
AP_OEM_DLC
AP_SDLC
AP_X25

Additional DLC types can be defined by specifying the new type on the DEFINE_DLC verb. See DEFINE_DLC for more information.

ls_detail.det_data.state

State of this link station. This field is set to one of the following values:

AP_NOT_ACTIVE
AP_PENDING_ACTIVE
AP_ACTIVE
AP_PENDING_INACTIVE

ls_detail.det_data.sub_state

This field provides more detailed information about the state of this link station. This field is set to one of the following values:

AP_SENT_CONNECT_OUT
AP_PENDING_XID_EXCHANGE
AP_SENT_ACTIVATE_AS
AP_SENT_SET_MODE
AP_ACTIVE
AP_SENT_DEACTIVATE_AS_ORDERLY
AP_SENT_DISCONNECT
AP_WAITING_STATS
AP_RESET

ls_detail.det_data.det_adj_cp_name

Fully qualified, 17-byte, adjacent control point name determined during link activation. It is composed of two type-A EBCDIC character strings concatenated by an EBCDIC dot, and is right-padded with EBCDIC spaces. (Each name can have a maximum length of 8 bytes with no embedded spaces.)

If ls_summary.adj_cp_type is not one of AP_NETWORK_NODE, AP_END_NODE, AP_APPN_NODE, or AP_BACK_LEVEL_LEN_NODE, then this field is reserved.

ls_detail.det_data.det_adj_cp_type

Type of the adjacent node determined during link activation. It is one of the following values:

AP_END_NODE
AP_NETWORK_NODE
AP_LEARN_NODE
AP_VRN

If ls_summary.adj_cp_type is not one of AP_NETWORK_NODE, AP_END_NODE, AP_APPN_NODE, or AP_BACK_LEVEL_LEN_NODE, then this field is reserved.

ls_detail.det_data.dlc_name

Name of the DLC. This is an 8-byte string in a locally displayable character set. All 8 bytes are significant.

ls_detail.det_data.dynamic

Specifies whether the link was defined explicitly (by a DEFINE_LS command), or implicitly or dynamically (either in response to a connection request from the adjacent node, or to connect dynamically to another node across a connection network). This can be AP_YES or AP_NO.

ls_detail.det_data.migration

Specifies whether the adjacent node is a migration level node (such as a low entry networking (LEN) node), or a full APPN® network node or end node (AP_YES, AP_NO, or AP_UNKNOWN).

ls_detail.det_data.tg_num

Number associated with the TG.

ls_detail.det_data.ls_stats.in_xid_bytes

Total number of XID (Exchange Identification) bytes received on this link station.

ls_detail.det_data.ls_stats.in_msg_bytes

Total number of data bytes received on this link station.

ls_detail.det_data.ls_stats.in_xid_frames

Total number of XID (Exchange Identification) frames received on this link station.

ls_detail.det_data.ls_stats.in_msg_frames

Total number of data frames received on this link station.

ls_detail.det_data.ls_stats.out_xid_bytes

Total number of XID (Exchange Identification) bytes sent on this link station.

ls_detail.det_data.ls_stats.out_msg_bytes

Total number of data bytes sent on this link station.

ls_detail.det_data.ls_stats.out_xid_frames

Total number of XID (Exchange Identification) frames sent on this link station.

ls_detail.det_data.ls_stats.out_msg_frames

Total number of data frames sent on this link station.

ls_detail.det_data.ls_stats.in_invalid_sna_frames

Total number of SNA incorrect frames received on this link station.

ls_detail.det_data.ls_stats.in_session_control_frames

Total number of session control frames received on this link station.

ls_detail.det_data.ls_stats.out_session_control_frames

Total number of session control frames sent on this link station.

ls_detail.det_data.ls_stats.echo_rsps

Number of echo responses received from the adjacent node. Echo requests are sent periodically to gauge the propagation delay to the adjacent node.

ls_detail.det_data.ls_stats.current_delay

Time (in milliseconds) that it took for the last test signal to be sent and returned from this link station to the adjacent link station.

ls_detail.det_data.ls_stats.max_delay

Longest time taken (in milliseconds) for a test signal to be sent and returned from this link station to the adjacent link station.

ls_detail.det_data.ls_stats.min_delay

Shortest time taken (in milliseconds) for a test signal to be sent and returned from this link station to the adjacent link station.

ls_detail.det_data.ls_stats.max_delay_time

Time since system startup (in hundredths of a second) when the longest delay occurred.

ls_detail.det_data.ls_stats.good_xids

Total number of successful XID exchanges that have occurred on this link station since it was started.

ls_detail.det_data.ls_stats.bad_xids

Total number of unsuccessful XID exchanges that have occurred on this link station since it was started.

ls_detail.det_data.start_time

Time since system startup (in hundredths of a second) when the link station was last activated (that is, the mode setting commands completed).

ls_detail.det_data.stop_time

Time since system startup (in hundredths of a second) when the link station was last deactivated.

ls_detail.det_data.up_time

The total time (in hundredths of a second) that this link station has been active since system startup.

ls_detail.det_data.current_state_time

The total time (in hundredths of a second) that this link station has been in the current state.

ls_detail.det_data.deact_cause

The cause of the last deactivation of the link station. The field is set to one of the following values:

AP_NONE: The link station has never been deactivated.
AP_DEACT_OPER_ORDERLY: The link station was deactivated as a result of an orderly STOP command from an operator.
AP_DEACT_OPER_IMMEDIATE: The link station was deactivated as a result of an immediate STOP command from an operator.
AP_DEACT_AUTOMATIC: The link station was deactivated automatically, for example because there were no more sessions using the link station.
AP_DEACT_FAILURE: The link station was deactivated because of a failure.

ls_detail.det_data.hpr_support

The level of high-performance routing (HPR) supported on this TG (AP_NONE, AP_BASE or AP_RTP), taking account of the capabilities of the local and adjacent nodes.

ls_detail.det_data.anr_label

The HPR automatic network routing (ANR) label allocated to the local link.

ls_detail.det_data.hpr_link_lvl_error

Specifies whether link-level error recovery is being used for HPR traffic on the link.

ls_detail.def_data.auto_act

Specifies whether the link currently allows remote activation or activation on demand. The following values are returned (and may be ORed together:

AP_AUTO_ACT: The link can be activated on demand by the local node.
AP_REMOTE_ACT: The link can be activated by the remote node.

ls_detail.det_data.ls_role

The link station role for this link station. This is initially set to the link station role defined for the link station. If the defined role is negotiable, this value changes to the negotiated role (primary or secondary) during the XID exchange, and reverts back to negotiable when the link is deactivated.

AP_LS_NEG: The link station role is negotiable.
AP_LS_PRI: The link station role is primary.
AP_LS_SEC: The link station role is secondary.

ls_detail.det_data.node_id

Node ID received from adjacent node during XID exchange. This a 4-byte hexadecimal string.

ls_detail.det_data.active_isr_count

Number of active intermediate sessions using the link.

ls_detail.det_data.active_lu_sess_count

The count of active LU-LU sessions using the link.

ls_detail.det_data.active_sscp_sess_count

The count of active LU-SSCP and PU-SSCP sessions using the link.

ls_detail.det_data.reverse_anr_label.length

The length of the reverse Automatic Network Routing (ANR) label for the link station. If the link does not support HPR, or the label is not known, this field is zeroed.

ls_detail.det_data.reverse_anr_label.label

The reverse Automatic Network Routing (ANR) label for the link station. If the link does not support HPR, or the label is not known, this field is zeroed.

ls_detail.det_data.local_address

The local address of this link station.

ls_detail.det_data.max_send_btu_size

The maximum BTU size that can be sent on this link, as determined by negotiation with the adjacent node. If link activation has not yet been attempted, zero is returned.

ls_detail.det_data.brnn_link_type

BrNN only. This branch link type. It is one of the following:

AP_UPLINK: This link is an uplink.
AP_DOWNLINK: The link is a downlink.
AP_OTHERLINK: This link is an otherlink.
AP_UNKNOWN_LINK_TYPE: This link is an otherlink.
AP_BRNN_NOT_SUPPORTED: This link supports PU 2.0 traffic only.
Other node types: This field is not meaningful and is always set to AP_BRNN_NOT_SUPPORTED.

ls_detail.det_data.adj_cp_is_brnn

All node types: Specifies whether the adjacent node is a BrNN.

AP_UNKNOWN: It is not known whether the adjacent node is a BrNN.
AP_NO: The adjacent node is not a BrNN.
AP_YES: The adjacent node is BrNN.

ls_detail.def_data.description

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

ls_detail.def_data.port_name

Name of port associated with this link station. This is an 8-byte string in a locally displayable character set. All 8 bytes are significant. If the link is to a VRN, this field specifies the name of the actual port used to connect to the VRN (as specified in the DEFINE_CN verb).

ls_detail.def_data.adj_cp_name

Fully qualified 17-byte adjacent control point name, which is composed of two type-A EBCDIC character strings concatenated by an EBCDIC dot, and is right-padded with EBCDIC spaces. (Each name can have a maximum length of 8 bytes with no embedded spaces.) This is defined if back_lvl_len_end_node is not set to AP_NO, or if the port associated with the link station is defined to be switched.

ls_detail.def_data.adj_cp_type

Adjacent node type.

AP_NETWORK_NODE: Specifies that the node is an APPN® network node.
AP_END_NODE: Specifies that the node is an APPN® end node or an up-level LEN node.
AP_APPN_NODE: Specifies that the node is an APPN® network node, an APPN® end node, or an up-level LEN node. The node type will be learned during XID exchange.
AP_BACK_LEVEL_LEN_NODE: Specifies that the node is a back-level LEN node.
AP_HOST_XID3: Specifies that the node is a host and that the Node Operator Facility responds to a polling XID from the node with a format 3 XID.
AP_HOST_XID0: Specifies that the node is a host and that the Node Operator Facility responds to a polling XID from the node with a format 0 XID.
AP_DSPU_XID: Specifies that the node is a downstream PU and that the Node Operator Facility includes XID exchange in link activation.
AP_DSPU_NOXID: Specifies that the node is a downstream PU and that the Node Operator Facility does not include XID exchange in link activation.
Note:
A link station to a VRN is always dynamic and is therefore not defined.

ls_detail.def_data.dest_address.length

Length of destination link station's address on adjacent node.

ls_detail.def_data.dest_address.address

Link station's destination address on adjacent node.

ls_detail.def_data.auto_act_supp

Specifies whether the link will be activated automatically after it has been started by a START_LS verb, and stopped by a STOP_LS. (AP_YES or AP_NO).

ls_detail.def_data.tg_number

Preassigned TG number (in the range one to 20). This number is used to represent the link when the link is activated. Zero indicates that the TG number is not preassigned but is negotiated when the link is activated.

ls_detail.def_data.limited_resource

Specifies whether this link station is to be deactivated when there are no sessions using the link. This is set to one of the following values:

AP_NO: The link is not a limited resource and will not be deactivated automatically.
AP_YES or AP_NO_SESSIONS: The link is a limited resource and will be deactivated automatically when no active sessions are using it.
AP_INACTIVITY: The link is a limited resource and will be deactivated automatically when no active sessions are using it, or when no data has flowed on the link for the time period specified by the link_deact_timer field.

ls_detail.def_data.solicit_sscp_sessions

AP_YES requests the host to initiate sessions between the SSCP and the local control point and dependent LUs. AP_NO requests no sessions with the SSCP on this link.

ls_detail.def_data.pu_name

Name of the local PU that is going to use this link if solicit_sscp_sessions is set to AP_YES. This is an 8-byte alphanumeric type-A EBCDIC string (starting with a letter), padded to the right with EBCDIC spaces. If solicit_sscp_sessions is set to AP_NO, this field is reserved.

ls_detail.def_data.disable_remote_act

Specifies whether remote activation of this link is supported (AP_YES or AP_NO).

ls_detail.def_data.dspu_services

Specifies the services that the local node provides to the downstream PU across this link if solicit_sscp_sessions is set to AP_NO. This is set to one of the following:

AP_PU_CONCENTRATION: Local node will provide PU concentration for the downstream PU.
AP_DLUR: Local node will provide DLUR services for the downstream PU.
AP_NONE: Local node will provide no services for this downstream PU.
If solicit_sscp_sessions is set to AP_YES, this field is reserved.

ls_detail.def_data.dspu_name

Name of the downstream PU. This is an 8-byte alphanumeric type-A EBCDIC string (starting with a letter), padded to the right with EBCDIC spaces. This is only valid if solicit_sscp_sessions is set to AP_NO.

ls_detail.def_data.dlus_name

Name of DLUS node which DLUR solicits SSCP services from when the link to the downstream node is activated. This is either set to all zeros or a 17-byte string composed of two type-A EBCDIC character strings concatenated by an EBCDIC dot, which is right-padded with EBCDIC spaces. (Each name can have a maximum length of 8 bytes with no embedded spaces.) If the field is set to all zeros, then the global default DLUS (if defined by the DEFINE_DLUR_DEFAULTS verb) is solicited when the link is activated. If the dlus_name is set to zeros and there is no global default DLUS, then DLUR will not initiate SSCP contact when the link is activated. This field is reserved if dspu_services is not set to AP_DLUR.

ls_detail.def_data.bkup_dlus_name

Name of DLUS node which serves as the backup for the downstream PU. This is either set to all zeros or to a 17-byte string composed of two type-A EBCDIC character strings concatenated by an EBCDIC dot, which is right-padded with EBCDIC spaces. (Each name can have a maximum length of 8 bytes with no embedded spaces.) If the field is set to all zeros, then the global backup default DLUS (if defined by the DEFINE_DLUR_DEFAULTS verb) is used as the backup for this PU. This field is reserved if dspu_services is not set to AP_DLUR.

ls_detail.def_data.hpr_supported

Specifies whether HPR is supported on this link (AP_YES or AP_NO).

ls_detail.def_data.hpr_link_lvl_error

Specifies whether the HPR link-level error recovery tower is supported on this link (AP_YES or AP_NO). Note that the parameter is reserved if hpr_supported is set to AP_NO.

ls_detail.def_data.link_deact_timer

Limited resource link deactivation timer (in seconds).

If limited_resource is set to AP_YES or AP_NO_SESSIONS, a link is automatically deactivated if no data traverses the link for the duration of this timer, and no sessions are using the link.

If limited_resource is set to AP_INACTIVITY then a link is automatically deactivated if no data traverses the link for the duration of this timer.

ls_detail.def_data.default_nn_server

Specifies whether a link can be automatically activated by an end node to support CP-CP sessions to a network node server. (AP_YES or AP_NO). The link must be defined to support CP-CP sessions for this field to take effect.

ls_detail.def_data.ls_attributes

Specifies further information about the adjacent node.

ls_detail.def_data.ls_attributes[0]

Host type.

AP_SNA: Standard SNA host.
AP_FNA: FNA (VTAM-F) host.
AP_HNA: HNA host.

ls_detail.def_data.ls_attributes[1]

This is a bit field. It may take the value AP_NO, or any of the following values bitwise ORed together

AP_SUPPRESS_CP_NAME: Network Name CV suppression option for a link to a back-level LEN node. If this bit is set, no Network Name CV is included in XID exchanges with the adjacent node. (This bit is ignored unless adj_cp_type is set to AP_BACK_LEVEL_LEN_NODE or AP_HOST_XID3.)
AP_REACTIVATE_ON_FAILURE: If the link is active and then fails, Personal Communications or Communications Server will attempt to reactivate the link. If the reactivation attempt fails, the link will remain inactive.
AP_USE_PU_NAME_IN_XID_CVS: If the adjacent node is defined to be a host or solicit_sscp_sessions is set to AP_YES on a link to an APPN® node, and the AP_SUPPRESS_CP_NAME bit is not set, then the fully-qualified CP name in Network Name CVs sent on Format 3 XIDs is replaced by the name supplied in def_data.pu_name, fully-qualified with the network ID of the CP.

ls_detail.def_data.adj_node_id

Defined node ID of adjacent node.

ls_detail.def_data.local_node_id

Node ID sent in XIDs on this link station. This is a 4-byte hexadecimal string. If this field is set to zero, the node_id is used in XID exchanges. If this field is nonzero, it replaces the value for XID exchanges on this LS.

ls_detail.def_data.cp_cp_sess_support

Specifies whether CP-CP sessions are supported (AP_YES or AP_NO).

ls_detail_def_data.use_default_tg_chars

Specifies whether the TG characteristics supplied on the DEFINE_LS were discarded in favor of the default characteristics supplied on the DEFINE_PORT (AP_YES or AP_NO). This field does not apply to implicit links.

ls_detail.def_data.tg_chars

TG characteristics (See DEFINE_CN).

ls_detail.def_data.target_pacing_count

Numeric value between 1 and 32␠767 inclusive indicating the desired pacing window size for BINDs on this TG. The number is only significant when fixed bind pacing is being performed. Note that Personal Communications or Communications Server does not currently use this value.

ls_detail.def_data.max_send_btu_size

Maximum BTU size that can be sent.

ls_detail.def_data.ls_role

The link station role that this link station should assume. This can be any one of AP_LS_NEG, AP_LS_PRI or AP_LS_SEC to select a role of negotiable, primary or secondary. The field can also be set to AP_USE_PORT_DEFAULTS to select the value configured on the DEFINE_PORT verb.

ls_detail.def_data.max_ifrm_rcvd

The maximum number of I-Frames that can be received by the XID sender before acknowledgment. Set to zero if the default value from DEFINE_PORT should be used.

ls_detail.def_data.dlus_retry_timeout

Interval in seconds between second and subsequent attempts to contact DLUS specified in the Is_detail.def_data.dlus_name and Is_detail.def_data.bkup_dlus_name fields. The interval between the initial attempt and the first retry is always one second. If zero is specified, the default value configured through DEFINE_DLUR_DEFAULTS is used. This field is ignored if def_data.dspu_services is not set to AP_DLUR.

ls_detail.def_data.dlus_retry_limit

Maximum number of retries after an initial failure to contact a DLUS specified in the Is_detail.def_data.dlus_name and Is_detail.def_data.bkup_dlus_name fields. If zero is specified, the default value configured through DEFINE_DLUR_DEFAULTS is used. If X'FFFF' is specified, the Program retries indefinitely. This field is ignored if def_data.dspu_services is not set to AP_DLUR.

ls_detail.def_data.link_spec_data_len

Unpadded length, in bytes, of data passed unchanged to link station component during initialization. The data is concatenated to the LS_DETAIL structure. This data will be padded to end on a 4-byte boundary.

ls_detail.def_data.conventional_lu_compression

Specifies whether data compression is requested for sessions on this link. Note that this field is only valid for links carrying LU 0 to 3 traffic.

AP_NO: The local node should not compress or decompress conventional LU data flowing over this link.
AP_YES: Data compression should be enabled for conventional LU sessions on this link if the host requests compression.

ls_detail.def_data.conventional_lu_cryptography

Specifies whether session level encryption is required for conventional LU sessions. This field only applies for links carrying conventional LU traffic.

AP_NONE: Session level encryption is not performed by the Program.
AP_MANDATORY: Mandatory session level encryption is performed by the Program if an import key is available to the LU. Otherwise, it must be performed by the application that uses the LU (if this is PU Concentration, it is performed by a downstream LU).
AP_OPTIONAL: This value allows the cryptography used to be driven by the host application on a per session basis. If the host request cryptography for a session dependent on this PU, then the behaviour of the Program is as for AP_MANDATORY. If the host does not request cryptography, then the behaviour is the same as AP_NONE.

ls_detail.def_data.retry_flags

This field specifies the conditions under which activation of this link station is 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_DELAY_INHERIT_RETRY: In addition to the retry conditions specified by flags in this field, those specified in the retry_flags field of the underlying port definition will also be used.

ls_detail.def_data.max_activation_attempts

This field has no effect unless at least one flag is set in retry_flags.

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 results in the use of max_activiation_attempts supplied on DEFINE_PORT.

ls_detail.def_data.activation_delay_timer

This field has no effect unless at least one flag is set in retry_flags.

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 AP_USE_DEFAULTS results in the use of activiation_delay_timer supplied on DEFINE_PORT.

If zero is specified, the Program uses a default timer duration of thirty seconds.

ls_detail.def_data.branch_link_type

BrNN only. Specifies whether a link is an uplink or a downlink. This field only applies if the field def_data.adj_cp_type is set to AP_NETWORK, NODE, AP_END_NODE, AP_APPN_NODE, or AP_BACK_LEVEL_LEN_NODE.

AP_UPLINK: This link is an uplink.
AP_DOWNLINK: The link is a downlink.

If the field adj_cp_type is set to AP_NETWORK_NODE, then this field must be set to AP_UPLINK.

Other node types: This field is ignored.

ls_detail.det_data.adj_brnn_cp_support

BrNN only. Specifies whether the adjacent CP is allowed to be, required to be, or prohibited from being an NN(BrNN), for example, a BrNN showing its NN face. This field only applies if the field adj_cp_type is set to AP_NETWORK_ NODE or AP_APPN_NODE, (and the node type learned during XID exchange is network node).

AP_BRNN_ALLOWED: The adjacent CP is allowed (but not required) to be an NN(BrNN).
AP_BRNN_REQUIRED: The adjacent CP is not allowed to be an NN(BrNN).
AP_BRNN_PROHIBITED: The adjacent CP is not allowed to be an NN(BrNN).

If the field adj_cp_type is set to AP_NETWORK_NODE and the field auto_act_supp is set to AP_YES, then this field must be set to AP_BRNN_REQUIRED or AP_BRNN_PROHIBITED.

Other node types: This field is ignored.

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_LINK_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

QUERY_LS

VCB Structure

VCB Structure

Supplied Parameters

Returned Parameters

Submit Your Feedback

Submitted Feedback