DEFINE_PORT

DEFINE_PORT defines a new port or modifies an existing one. This port belongs to a specified DLC, which must already have been defined using a DEFINE_DLC verb. The DEFINE_PORT verb provides the port name, which is unique throughout the node, along with port specific parameters and default LS characteristics for use with dynamic link stations. The port specific parameters are concatenated to the basic structure. The default LS characteristics are concatenated immediately following the port specific parameters.

DEFINE_PORT can be used to modify one or more fields on an existing port if the port is in a reset state (after STOP_PORT has been issued) and the dlc_name specified on the DEFINE_PORT has not changed since the previous definition of the port.

If the port is active, only the following fields can be modified:

description
implicit_dspu_services
implicit_deact_timer
implicit_cp_cp_sess_support
implicit_link_lvl_error
default_tg_chars
implicit_dspu_template
implicit_ls_limit
link_spec_data_len
link_spec_data

If the port spec data is changed while the port is active, the verb will not be rejected but the modifications will be ignored.

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

VCB Structure

typedef struct define_port
{
        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   port_name[8];         /* name of port                  */
        PORT_DEF_DATA   def_data;             /* port defined data             */
} DEFINE_PORT;

typedef struct port_def_data
{
        unsigned char   description;          /* resource description          */
        unsigned char   dlc_name[8];          /* DLC name associated with port */
        unsigned char   port_type;            /* port type                     */
        unsigned char   port_attributes[4];   /* port attributes               */
        unsigned char   implicit_uplink_to_en;/* Implicit links to EN are      */
                                              /* uplink                        */
        unsigned char   reserv3[2];           /* reserved                      */
        unsigned long   port_number;          /* port number                   */
        unsigned short  max_rcv_btu_size;     /* max receive BTU size          */
        unsigned short  tot_link_act_lim;     /* total link activation limit   */
        unsigned short  inb_link_act_lim;     /* inbound link activation limit */
        unsigned short  out_link_act_lim;     /* outbound link activation      */
                                              /* limit                         */
        unsigned char   ls_role;              /* initial link station role     */
        unsigned char   retry_flags;          /* conditions for automatic      */
                                              /* retries                       */
        usigned char    max_activation_attempts;
                                              /* how many automatic retries?   */
        unsigned char   activation_delay_timer;
                                              /* delay between automatic       */
                                              /* retries                       */
        unsigned char   reserv1[10];          /* reserved                       */
        unsigned char   implicit_dspu_template[8];
                                              /* reserved                      */
        unsigned char   implicit_ls_limit;    /* max number of implicit links  */
        unsigned char   reserv2;              /* reserved                      */
        unsigned char   implicit_dspu_services;
                                              /* implicit links support DSPUs  */
        unsigned char   implicit_deact_timer; /* Implicit link HPR link        */
                                              /* deactivation timer            */
        unsigned short  act_xid_exchange_limit;
                                              /* act.  XID exchange limit      */
        unsigned short  nonact_xid_exchange_limit;
                                              /* nonact.  XID exchange limit   */
        unsigned char   ls_xmit_rcv_cap;      /* LS transmit-receive           */
                                              /* capability                    */
        unsigned char   max_ifrm_rcvd;        /* max number of I-frames that   */
                                              /* can be received               */
        unsigned short  target_pacing_count;  /* Target pacing count           */
        unsigned short  max_send_btu_size;    /* Desired max send BTU size     */
        LINK_ADDRESS    dlc_data;             /* DLC data                      */
        LINK_ADDRESS    hpr_dlc_data;         /* HPR DLC data                  */
        unsigned char   implicit_cp_cp_sess_support;
                                              /* Implicit links allow CP-CP    */
                                              /* sessions                      */
        unsigned char   implicit_limited_resource;
                                              /* Implicit links are limited    */
                                              /* resource                      */
        unsigned char   implicit_hpr_support;
                                              /* Implicit links support HPR    */
        unsigned char   implicit_link_lvl_error;
                                              /* Implicit links support HPR    */
                                              /* link-level error recovery     */
        unsigned char   retired1;             /* reserved                      */
        TG_DEFINED_CHARS default_tg_chars;    /* Default TG chars              */
        unsigned char   discovery_supported     /* Discovery function            */
                                              /* supported?                    */
        unsigned short  port_spec_data_len;   /* length of port spec data      */
        unsigned short  link_spec_data_len;   /* length of link spec data      */
} PORT_DEF_DATA;

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

Supplied Parameters

The application supplies the following parameters:

opcode

AP_DEFINE_PORT

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.

port_name

Name of port being defined. This is an 8-byte string in a locally displayable character set. All 8 bytes are significant and must be set.

port_def_data.description

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

port_def_data.dlc_name

Name of the associated DLC, which is an 8-byte string in a locally displayable character set. All 8 bytes are significant and must be set. This named DLC must have already been defined by a DEFINE_DLC verb.

port_def_data.port_type

Specifies the type of line used by the port. The value corresponds to one of the following line types:

AP_PORT_NONSWITCHED
AP_PORT_SWITCHED
AP_PORT_SATF

Note that if this field is set to AP_PORT_SATF then the ls_role must be set to AP_LS_NEG.

port_def_data.port_attributes[0]

This is the bit field. It may take the value AP_NO, or the following:

AP_RESOLVE_BY_LINK_ADDRESS: This specifies that an attempt is made to resolve incoming calls by using the link address on CONNECT_IN before using the CP name (or node ID) carried on the received XID3 to resolve them. This bit is ignored unless the field port_type is set to AP_PORT_SWITCHED.

port_def_data.implicit_uplink_to_en

BrNN only: Specifies whether implicit link stations off this port are uplink or downlink if the adjacent node is an end node. The value of this field will only be considered if there are no existing links to the same partner, as such links are used first to determine the link type.

AP_NO: Implicit links are downlink.
AP_YES: Implicit links are uplink.
Other node types: This field is ignored.

port_def_data.port_number

Port number.

port_def_data.max_rcv_btu_size

Maximum BTU size that can be received. If implicit HPR-capable links are not supported on the port, then this must be set to a value greater than or equal to 99. If implicit HPR-capable links are supported on the port, then this must be set to a value greater than or equal to 768.

port_def_data.tot_link_act_lim

Total link activation limit. This specifies the maximum number of link stations that can be active concurrently. This must be greater than or equal to the sum of the inb_link_act_lim and out_link_act_lim fields. If the port_type is set to AP_PORT_NONSWITCHED and the ls_role is set to AP_LS_NEG or AP_LS_SEC then this field must be set to one. If the ls_role is set to AP_LS_PRI then this field must be in the range greater than or equal to one to 256. If this port is for the AnyNet® DLC, you must use 65535.

port_def_data.inb_link_act_lim

Inbound link activation limit. This specifies the number of link stations reserved for inbound activation on this port. The maximum number of outbound link stations that can be active concurrently is therefore port_def_data.tot_link_act_lim - port_def_data.inb_link_act_lim. If the port_type is set to AP_PORT_NONSWITCHED and the ls_role is set to AP_LS_NEG or AP_LS_PRI then this field must be set to zero. If the port_type is set to AP_PORT_NONSWITCHED and the ls_role is set to AP_LS_SEC then this field must be set to zero or one. If this port is for the AnyNet DLC, you must use zero.

port_def_data.out_link_act_lim

Outbound link activation limit. This specifies the number of link stations reserved for outbound activation on this port. The maximum number of inbound link stations that can be active concurrently is therefore port_def_data.tot_link_act_lim - port_def_data.out_link_act_lim. If the port_type is set to AP_PORT_NONSWITCHED and the ls_role is set to AP_LS_NEG then this field must be set to zero. If the ls_role is set to AP_LS_PRI then this field must be equal to tot_link_act_lim. If the port_type is set to AP_PORT_NONSWITCHED and the ls_role is set to AP_LS_SEC then this field must be set to zero or one. If this port is for the AnyNet DLC, you must use zero.

port_def_data.ls_role

Link station role. This can be negotiable (AP_LS_NEG), primary (AP_LS_PRI), or secondary (AP_LS_SEC). The link station role determines the relationship between the values specified by the tot_act_lim, inb_link_act_lim, and out_link_act_lim fields as described above. Note that if the port_type is set to AP_PORT_SATF then the ls_role must be set to AP_LS_NEG.

port_def_data.retry_flags

This field specifies the conditions under which activation of this link station is subject to automatic retry if the flag AP_INHERIT_RETRY is set on DEFINE_LS in port_def_data.retry_flags. 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, APPN 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, APPN 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: 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.

port_def_data.max_activation_attempts

This field has no effect unless at least one flag is set in DEFINE_LS in port_def_data.retry_flags and port_def_data.max_activation_attempts on DEFINE_LS 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 results in the use of max_activiation_attempts supplied on DEFINE_DLC.

port_def_data.activation_delay_timer

This field has no effect unless at least one flag is set in DEFINE_LS in port_def_data.retry_flags and activiation_delay_timer on DEFINE_LS 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 port_def_data.retry_flags.

The value AP_USE_DEFAULTS results in the use of activiation_delay_timer supplied on DEFINE_DLC.

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

port_def_data.implicit_dspu_template

Specifies the DSPU template, defined with the DEFINE_DSPU_TEMPLATE verb, that is used for definitions if the local node is to provide PU Concentration for an implicit link activated on this port. If the template specified does not exist (or is already at its instance limit) when the link is activated, activation fails. This is an 8-byte string in a locally-displayable character set. All 8 bytes are significant and must be set.

If the port_def_data.implicit_dspu_services field is not set to AP_PU_CONCENTRATION, then this field is reserved.

port_def_data.implicit_ls_limit

Specifies the maximum number of implicit link stations that can be active on this port simultaneously, including dynamic links and links activated for Discovery. A value of 0 means that there is no limit, a value of AP_NO_IMPLICIT_LINKS means that no implicit links are allowed.

port_def_data.implicit.dspu_services

Specifies the services that the local node will provide to the downstream PU across implicit links activated on this port. This is set to one of the following values:

AP_DLUR: Local node will provide DLUR services for the downstream PU (using the default DLUS configured through the DEFINE_DLUR_DEFAULTS verb). This setting is only valid if the local node is a network node.
AP_PU_CONCENTRATION: Local node will provide PU Concentration for the downstream PU (and will put in place definitions as specified by the DSPU template specified in the field port_def_data.implicit_dspu_template).
AP_NONE: Local node will provide no services for this downstream PU.

port_def_data.implicit_deact_timer

Limited resource link deactivation timer (in seconds). If implicit_limited_resource is set to AP_YES or AP_NO_SESSIONS, then an HPR-capable implicit link is automatically deactivated if no data traverses the link for the duration of this timer, and no sessions are using the link.

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

The value is an integer in the range of 0–1000 seconds. The default is 10 seconds.

If zero is specified, the default value of 30 is used. Otherwise the minimum value is 5. (If it is set any lower, the specified value will be ignored and 5 will be used.) Note that this parameter is reserved unless implicit_limited_resource is set to AP_NO.

port_def_data.act_xid_exchange_limit

Activation XID exchange limit.

port_def_data.nonact_xid_exchange_limit

Non-activation XID exchange limit.

port_def_data.ls_xmit_rcv_cap

Specifies the link station transmit/receive capability. This is either two-way simultaneous (AP_LS_TWS) (also known as duplex or full-duplex) or two way alternating (AP_LS_TWA) (also know as half-duplex).

port_def_data.max_ifrm_rcvd

Maximum number of I-frames that can be received by the local link stations before an acknowledgment is sent. The range is 1–127.

port_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.

port_def_data.max_send_btu_size

Maximum BTU size that can be sent from this link station. This value is used to negotiate the maximum BTU size than can be transmitted between a link station pair. If implicit HPR-capable links are not supported on the port then this must be set to a value greater than or equal to 99. If implicit HPR-capable links are supported on the port then this must be set to a value greater than or equal to 768.

port_def_data.dlc_data.length

Port address length.

port_def_data.dlc_data.address

Port address.

port_def_data.hpr_dlc_data.length

HPR Port address length.

port_def_data.hpr_dlc_data.address

HPR Port address. This is currently used when supporting HPR links. The field specifies the information sent by Personal Communications or Communications Server in the X'80' subfield of the X'61' control vector on XID3s exchanged on link stations using this port. It is passed on the ACTIVATE_PORT issued to the DLC by Personal Communications or Communications Server. Some DLCs can require this information to be filled in for ports supporting HPR links.

port_def_data.implicit_cp_cp_sess_support

Specifies whether CP-CP sessions are permitted for implicit link stations off this port (AP_YES or AP_NO).

port_def_data.implicit_limited_resource

Specifies whether implicit link stations off this port should be deactivated when there are no sessions using the link. This is set to one of the following values:

AP_NO: Implicit links are not limited resources and will not be deactivated automatically.
AP_YES or AP_NO_SESSIONS: Implicit links are a limited resource and will be deactivated automatically when no active sessions are using them.
AP_INACTIVITY: Implicit links are a limited resource and will be deactivated automatically when no active sessions are using them, or when no data has followed on the link for the time period specified by the implicit_deact_timer field.

port_def_data.implicit_hpr_support

Specifies whether HPR should be supported on implicit links (AP_YES or AP_NO).

port_def_data.implicit_link_lvl_error

Specifies whether HPR traffic should be sent on implicit links using link-level error recovery (AP_YES or AP_NO). Note that the parameter is reserved if implicit_hpr_support is set to AP_NO.

port_def_data.default_tg_chars

TG characteristics (See DEFINE_COS). These are used for implicit link stations off this port and also for defined link stations that specify use_default_tg_chars.

port_def_data.discovery_supported

Specifies whether Discovery functions are to be performed on this port (AP_YES or AP_NO).

port_def_data.port_spec_data_len

Length of data to be passed unchanged to port on ACTIVATE_PORT signal. The data should be concatenated to the basic structure.

port_def_data.link_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_PORT_NAME
AP_INVALID_DLC_NAME
AP_INVALID_PORT_TYPE
AP_INVALID_BTU_SIZE
AP_INVALID_LS_ROLE
AP_INVALID_LINK_ACTIVE_LIMIT
AP_INVALID_MAX_IFRM_RCVD
AP_INVALID_DSPU_SERVICES
AP_HPR_NOT_SUPPORTED
AP_DLUR_NOT_SUPPORTED
AP_PU_CONC_NOT_SUPPORTED
AP_INVALID_TEMPLATE_NAME
AP_INVALID_RETRY_FLAGS
AP_INVALID_IMPLICIT_UPLINK

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_PORT_ACTIVE
AP_DUPLICATE_PORT_NUMBER
AP_CANT_MODIFY_WHEN_ACTIVE
AP_CANT_MODIFY_VISIBILITY
AP_INVALID_IMPLICIT_UPLINK

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