DEVICE and LINK - MPCIPA OSA-Express QDIO devices statement

To define an OSA-Express® device in QDIO mode, use the MPCIPA DEVICE statement, specifying the PORTNAME value from the TRLE definition as the device_name value.

For details about defining a TRLE, see z/OS Communications Server: SNA Resource Definition Reference.

Use the LINK statement to define a network interface link associated with the QDIO interface.

Restriction: Only one LINK statement can be specified for each MPCIPA device.

Tip: You can also use the INTERFACE statement to define an IPv4 interface for OSA-Express QDIO Ethernet, which combines the definitions of the DEVICE, LINK, and HOME statements into a single statement.

When you start an MPCIPA device, TCP/IP registers all non-loopback (home) IPv4 addresses for this TCP/IP instance to OSA-Express feature. (For a dynamic VIPA that exists on multiple stacks, only the stack that owns the DVIPA, and therefore advertises the DVIPA to routers, registers the DVIPA to OSA-Express feature.) This enables the device to route datagrams destined for those IPv4 addresses to this TCP/IP instance. If a datagram is received at this device for an unknown IP address, the device routes the datagram to the TCP/IP instance, depending on the configuration of a virtual MAC (VMAC) address or definition of an instance as PRIROUTER or SECROUTER. If the datagram is not destined for a virtual MAC address and no active TCP/IP instance using this device is defined as PRIROUTER or SECROUTER, the device discards the datagram. For more details about OSA-Express feature routing considerations, see router information in z/OS Communications Server: IP Configuration Guide and primary and secondary routing in z/OS Communications Server: SNA Network Implementation Guide.

If you subsequently add, delete, or change any home IPv4 addresses on this TCP/IP instance, TCP/IP dynamically registers the changes to OSA-Express.

SNMP management data specific to OSA-Express and OSA-Express2 features is supported by the z/OS® Communications Server SNMP TCP/IP subagent, and the OSA-Express Direct SNMP subagent. For more information about these SNMP subagents, see TCP/IP subagent and OSA-Express Direct subagent in the z/OS Communications Server: IP Configuration Guide.

For detailed instructions on setting up an OSA-Express feature, see zEnterprise System and System z10 OSA-Express Customer's Guide and Reference.

To determine the OSA-Express microcode level, use the DISPLAY TRL command. If a specific OSA-Express feature is documented with a minimum microcode level, you can use this command to determine whether that function is supported. IBM® service might request the microcode level for problem diagnosis. For more information about the DISPLAY TRL command, see z/OS Communications Server: SNA Operation.

For more information about configuring OSA-specific SNMP support, see Step 4: Configure the Open Systems Adapter (OSA) support in z/OS Communications Server: IP Configuration Guide.

For more information about missing interrupt handler (MIH) considerations with TCP/IP devices, see Missing interrupt handler factors.

The following OSA-Express features can be defined in QDIO mode:

• Fast Ethernet
• ATM LANE Ethernet
• Gigabit Ethernet
• Token Ring
• 1000BASE-T Ethernet
• 10G Ethernet

Parameters

device_name

The name of the device. The device name must be the PORT name of the LAN adapter defined in a TRLE for a QDIO connection. The maximum length is eight characters.

MPCIPA

Specifies the device belongs to the MPC family of interfaces and uses the interface based on IP assist.

NONROUTER

If a datagram is received at this device for an unknown IP address, the datagram is not routed to this TCP/IP instance. This is the default value.

PRIRouter and SECRouter parameters interact with the VLANID parameter on the LINK statement. See the VLANID parameter to understand this relationship.

Rule: This keyword is ignored if the VMAC parameter is configured on the LINK statement.

PRIROUTER

If a datagram is received at this device for an unknown IP address and is not destined for a virtual MAC address, the datagram is routed to this TCP/IP instance.

Rule: This keyword is ignored if the VMAC parameter is configured on the LINK statement.

SECROUTER

If a datagram is received at this device for an unknown IP address and is not destined for a virtual MAC address, and there is no active TCP/IP instance defined as PRIROUTER, then the datagram can be routed to this TCP/IP instance. In this case, OSA routes to only one of the active TCP/IP instances that is defined with SECROUTER parameter. This parameter indicates that the OSA considers this TCP/IP instance to be one of the secondary routers.

Rule: This keyword is ignored if the VMAC parameter is configured on the LINK statement.

AUTORESTART | NOAUTORESTART

Controls device failure reactivation behavior.

NOAUTORESTART

For most device failures, specifying NOAUTORESTART indicates that the TCP/IP address space does not attempt to reactivate this device.

AUTORESTART

In the event of a device failure, the TCP/IP address space attempts to reactivate the device. For more information, see Recovering from device failures.

Parameters

link_name

The name of the link. The maximum length is 16 characters.

IPAQENET

Indicates that the link uses the interface bases on IP assist, belongs to the QDIO family of interfaces, and uses the Gigabit Ethernet or Fast Ethernet protocol. IPAQGNET is accepted for migration purposes.

device_name

The device_name must be the same as specified in the DEVICE statement.

IPBCAST

Specifies that the link both sends and receives IP broadcast packets. If this parameter is not specified, no IP broadcast packets are sent or received on this link.

VLANID id

An optional parameter followed by a decimal number indicating the virtual LAN identifier to be assigned to this OSA-Express Link. This field should be a virtual LAN identifier recognized by the switch for the LAN connected to this OSA-Express. The valid range is 1 - 4094.

The VLANID parameter interacts with the PRIROUTER and SECROUTER parameters on the DEVICE statement. If you configure both a VLANID and either the PRIROUTER or SECROUTER parameter, then this TCP/IP instance acts as a router for this VLAN ID only. Datagrams that are received at this device for an unknown IP address and are not destined for a virtual MAC are routed only to this TCP/IP instance if the datagrams are VLAN tagged with a matching VLAN ID. For more information about VLANID parameter interactions, see OSA VLAN in z/OS Communications Server: IP Configuration Guide.

READSTORAGE

An optional parameter indicating the amount of fixed storage that z/OS Communications Server should keep available for read processing for this adapter. The QDIOSTG VTAM start option allows you to specify a value which applies to all OSA-Express adapters in QDIO mode. You can use the READSTORAGE keyword to override the global QDIOSTG value for this adapter based on the inbound workload you expect over this adapter on this stack. The valid values are:

GLOBAL

The amount of storage is determined by the QDIOSTG VTAM start option. This is the default value.

MAX

Use this value if you expect a heavy inbound workload over this adapter.

AVG

Use this value if you expect a medium inbound workload over this adapter.

MIN

Use this value if you expect a light inbound workload over this adapter.

Tip: See the description of the QDIOSTG VTAM start option in the z/OS Communications Server: SNA Resource Definition Reference for details about exactly how much storage is allocated by z/OS Communications Server for each of these values.

Rule: If you define both a LINK and INTERFACE statement for the same adapter, then the READSTORAGE value on the LINK statement must match the READSTORAGE value on the corresponding INTERFACE statement. If you define a LINK statement that contains a value for READSTORAGE that conflicts with the READSTORAGE value for a previous INTERFACE statement for the same adapter, then TCP/IP rejects the LINK statement.

INBPERF

An optional parameter indicating how frequently the adapter should interrupt the host for inbound traffic.

There are three supported static settings (MINCPU, MINLATENCY, and BALANCED). The static settings use static interrupt-timing values. The static values are not always optimal for all workload types or traffic patterns, and cannot account for changes in traffic patterns.

There is also one supported dynamic setting. This setting causes the host (stack) to dynamically adjust the timer-interrupt value while the device is active and in use. This function exploits an OSA hardware function called dynamic LAN idle. Unlike the static settings, the DYNAMIC setting reacts to changes in traffic patterns, and sets the interrupt-timing values at the point where throughput is maximized.

Valid settings for this setting are:

BALANCED

This setting uses a static interrupt-timing value, selected to achieve reasonably high throughput and reasonably low CPU consumption. This is currently the default value.

DYNAMIC

This setting causes the host to dynamically signal the OSA-Express feature to change the timer-interrupt value, based on current inbound workload conditions. The DYNAMIC setting is effective only for OSA-Express2 or later features on at least an IBM System z9® with the corresponding dynamic LAN idle functional support. See the 2094DEVICE Preventive Service Planning (PSP) and the 2096DEVICE Preventive Service Planning (PSP) buckets for more information about the level of OSA-Express2 adapter that supports this function. See the 2097DEVICE Preventive Service Planning (PSP) bucket for more information about the OSA-Express3 adapter that supports this function. When this setting is specified for an Open Systems Adapter-Express that does not support the dynamic LAN idle function, the stack reverts to using the BALANCED setting. The DYNAMIC setting can decrease latency and provide increases in throughput for many interactive workloads. For all other workload combinations, this setting provides performance similar to the three static settings.

Restriction: The QDIO inbound workload queueing function, which is part of the DYNAMIC setting for OSA-Express3 or later features, is not supported for IPAQENET interfaces that are defined by DEVICE and LINK statements. You must convert your IPAQENET definitions to use the INTERFACE statement in order to enable this function. See the information about QDIO inbound workload queueing and Steps for converting from IPv4 IPAQENET DEVICE, LINK, and HOME definitions to the IPv4 IPAQENET INTERFACE statement in z/OS Communications Server: IP Configuration Guide.

MINCPU

This setting uses a static interrupt-timing value, selected to minimize host interrupts without regard to throughput. This mode of operation might result in minor queueing delays (latency) for packets into the host, which is not optimal for workloads with demanding latency requirements.

MINLATENCY

This setting uses a static interrupt-timing value, selected to minimize latency (delay), by more aggressively presenting received packets to the host. This mode of operation generally results in higher CPU consumption than the other three settings. Use this setting only if host CPU consumption is not an issue.

Rule: If you define both a LINK IPAQENET and an INTERFACE IPAQENET6 statement for the same adapter, then the following rules apply for the INBPERF parameter on these statements:

• The value on the LINK statement must match the INBPERF value on the corresponding INTERFACE statement.
• The INTERFACE statement supports the subparameters WORKLOADQ and NOWORKLOADQ for the INBPERF DYNAMIC parameter. These subparameters are associated with QDIO inbound workload queueing support and are not supported on the LINK IPAQENET statement. So, if you specify the INBPERF DYNAMIC parameter for both the LINK and the INTERFACE statements, then you must use the default or specify the NOWORKLOADQ subparameter for the INBPERF DYNAMIC parameter on the INTERFACE statement. This ensure that the INBPERF DYNAMIC setting for both statements is the same.
• If you define a LINK IPAQENET statement that contains a value for INBPERF that conflicts with the INBPERF value for a previous INTERFACE IPAQENET6 statement for the same adapter, then TCP/IP rejects the LINK statement.

IFSPEED ifspeed

An optional estimate of the interface's current bandwidth in bits per second. The minimum value that can be specified for the ifspeed variable for an MPCIPA link is 0; the maximum value is 2147483647. The default is 100 000 000. Until the interface is successfully started, this value is used by SNMP as the value of the ifSpeed MIB object. After the interface is successfully started, SNMP uses the actual speed reported by the interface as the value of the ifSpeed MIB object. The value of this parameter has no effect on the operation of the device.

IFHSPEED ifhspeed

An optional estimate of the interface's current bandwidth in one million bits per second units. The minimum value that can be specified for the ifhspeed variable for an MPCIPA link is 0; the maximum value is 2147. The default is 100. Until the interface is successfully started, this value is used by SNMP as the value of the ifHighSpeed MIB object. After the interface is successfully started, SNMP uses the actual speed reported by the interface as the value of the ifHighSpeed MIB object. The value of this parameter has no effect on the operation of the device.

SECCLASS security_class

Use this parameter to associate a security class for IP filtering with this interface. In order for traffic over the interface to match a filter rule, the filter rule must have the same security class value as the interface or a value of 0. Filter rules can be specified in the TCP/IP profile or in an IP Security policy file read by the Policy Agent. Filter rules can include a security class specification on the IpService statement in an IP Security policy file or on the SECCLASS parameter on the IPSEC statement in the TCP/IP profile.

Valid security classes are identified as a number in the range 1 - 255. The default value is 255. For more information about security class values, see z/OS Communications Server: IP Configuration Guide.

Restriction: The TCP/IP stack ignores this value if IPSECURITY is not specified on the IPCONFIG statement.

MONSYSPLEX | NOMONSYSPLEX

Specifies whether or not sysplex autonomics should monitor the link's status.

NOMONSYSPLEX

Specifies that sysplex autonomics should not monitor the link's status. This is the default value.

MONSYSPLEX

Specifies that sysplex autonomics should monitor the link's status.

Restriction: The MONSYSPLEX attribute is not in effect unless the MONINTERFACE keyword is specified on the GLOBALCONFIG SYSPLEXMONITOR profile statement. The presence of dynamic routes over this link is monitored if the DYNROUTE keyword is also specified on the GLOBALCONFIG SYSPLEXMONITOR profile statement.

DYNVLANREG | NODYNVLANREG

Controls VLAN ID configuration behavior for this link.

Restriction: This parameter is applicable only if a VLAN ID is specified on the statement.

Dynamic registration of VLAN IDs is handled by the OSA-Express feature and the physical switch on your LAN. Therefore, both must be at a level that provides the necessary hardware support for dynamic VLAN ID registration, in order for the DYNVLANREG parameter to be effective. After the link is active, you can view the Netstat DEVLINKS/-d report output to determine whether your OSA-Express feature can support VLAN dynamic registration. This Netstat report also displays whether or not dynamic VLAN ID registration has been configured for the link.

Rule: If you define both a LINK and INTERFACE statement for the same adapter, then the dynamic VLAN ID registration parameter value on the LINK statement must match the value of this same parameter on the corresponding INTERFACE statement. If you define a LINK statement that contains a dynamic VLAN ID registration parameter value that conflicts with the same parameter value for a previous INTERFACE statement for the same OSA-Express feature, then TCP/IP rejects the LINK statement.

NODYNVLANREG

Specifies that if a VLAN ID is configured for this link, the ID must be manually registered with the physical switches on the corresponding LAN. This is the default value. If this parameter is specified without a VLAN ID, it is ignored.

DYNVLANREG

Specifies that if a VLAN ID is configured for this link, the ID is dynamically registered with the physical switches on the corresponding LAN. If this parameter is specified without a VLAN ID, message EZZ0056I is issued and the NODYNVLANREG setting is used instead.

VMAC macaddr

Indicates the virtual MAC address, which can be represented by 12 hexadecimal characters. The OSA-Express feature uses this address rather than the physical MAC address of the device for all IPv4 packets to and from this TCP/IP stack.

The macaddr value is an optional parameter. If the macaddr is not coded, then the OSA-Express feature generates a virtual MAC address. If the macaddr value is coded, it must be defined as a locally administered individual MAC address. This means that the MAC address must have bit 6 (the universal or local flag U bit) of the first byte set to 1 and bit 7 (the group or individual flag G bit) of the first byte set to 0. The second hexadecimal character must be 2, 6, A, or E. The bit positions within the 12 hexadecimal characters are indicated in the following figure:

|               1|1              3|3              4|
|0              5|6              1|2              7|
+----------------+----------------+----------------+
|xxxxxxUGxxxxxxxx|xxxxxxxxxxxxxxxx|xxxxxxxxxxxxxxxx|
+----------------+----------------+----------------+

Rules:

• The same virtual MAC address generated by the OSA-Express feature at interface activation remains in effect for this OSA-Express for this TCP/IP stack, even if the device is stopped or becomes inoperative (INOPs). A new virtual MAC address is generated only if the LINK statement is deleted and redefined, or if the TCP/IP stack is recycled.
• The NONROUTER, PRIROUTER, and SECROUTER parameters are ignored for an OSA-Express feature if the VMAC parameter is configured on the LINK statement.

Guideline: Unless the virtual MAC address representing this OSA-Express device must remain the same even after TCP/IP termination and restart, configure VMAC without a macaddr value and allow the OSA-Express device to generate it. This guarantees that the VMAC address is unique from all other physical burned-in MAC addresses and from all other VMAC addresses generated by any OSA-Express feature.

ROUTEALL

All IP traffic destined to the virtual MAC is forwarded by the OSA-Express device to the TCP/IP stack. This is the default value. See the router information in z/OS Communications Server: IP Configuration Guide for more details.

ROUTELCL

This specifies that only traffic destined to the virtual MAC and whose destination IP address is registered with the OSA-Express device by this TCP/IP stack is forwarded by the OSA-Express device. See the router information in z/OS Communications Server: IP Configuration Guide for more details.

Parameters

link_name

The name of the link. The maximum length is 16 characters.

IPAQTR

Indicates that the link uses the interface based on IP assist, belongs to the QDIO family of interfaces, and uses the Token Ring protocol.

device_name

The device_name must be the same as specified in the DEVICE statement.

CANONICAL | NONCANONICAL

Specifies the canonical form of MAC addresses in Address Resolution Protocol (ARP) packets on this token-ring network.

NONCANONICAL

MAC addresses in ARP packets on this token-ring network are in the more common non-canonical format. This is the default value.

CANONICAL

MAC addresses in Address Resolution Protocol (ARP) packets on this token-ring network are in the canonical IEEE 802.5 form.

ALLRINGSBCAST

All IP and ARP broadcasts are sent as all-rings broadcasts, which are propagated through token-ring bridges (Source Route Bridging). This is the default value.

LOCALBCAST

All IP and ARP broadcasts are sent only on the local ring and are not propagated through token-ring bridges (Transparent Bridging).

IPBCAST

Specifies that the link both sends and receives IP broadcast packets. If this parameter is not specified, no IP broadcast packets are sent or received on this link.

READSTORAGE

An optional parameter indicating the amount of fixed storage that z/OS Communications Server should keep available for read processing for this adapter. The QDIOSTG VTAM start option allows you to specify a value which applies to all OSA-Express adapters in QDIO mode. You can use the READSTORAGE keyword to override the global QDIOSTG value for this adapter based on the inbound workload you expect over this adapter on this stack. The valid values are:

GLOBAL

The amount of storage is determined by the QDIOSTG VTAM start option. This is the default value.

MAX

Use this value if you expect a heavy inbound workload over this adapter

AVG

Use this value if you expect a medium inbound workload over this adapter.

MIN

Use this value if you expect a light inbound workload over this adapter.

Tip: See the description of the QDIOSTG VTAM start option in the z/OS Communications Server: SNA Resource Definition Reference for details about exactly how much storage is allocated by z/OS Communications Server for each of these values.

INBPERF

An optional parameter indicating how frequently the adapter should interrupt the host for inbound traffic. The valid values are:

MINCPU

This setting instructs the adapter to minimize host interrupts, thereby minimizing host CPU consumption. This mode of operation might result in minor queueing delays for packets into the host, and is not preferred for workloads with demanding latency requirements.

MINLATENCY

This setting instructs the adapter to minimize latency, by immediately presenting received packets to the host. This mode of operation generally results in higher CPU consumption than the other two settings, and is preferred only for workloads with demanding latency requirements. This setting should be used only if host CPU consumption is not an issue.

BALANCED

This setting instructs the adapter to strike a balance between MINCPU and MINLATENCY.

IFSPEED ifspeed

An optional estimate of the interface's current bandwidth in bits per second. Until the interface is successfully started, this value is used by SNMP as the value of the ifSpeed MIB object. After the interface is successfully started, SNMP uses the actual speed reported by the interface as the value of the ifSpeed MIB object. The value of this parameter has no effect on the operation of the device.

IFHSPEED ifhspeed

An optional estimate of the interface's current bandwidth in one million bits per second units. Until the interface is successfully started, this value is used by SNMP as the value of the ifHighSpeed MIB object. After the interface is successfully started, SNMP uses the actual speed reported by the interface as the value of the ifHighSpeed MIB object. The value of this parameter has no effect on the operation of the device.

SECCLASS security_class

Use this parameter to associate a security class for IP filtering with this interface. In order for traffic over the interface to match a filter rule, the filter rule must have the same security class value as the interface or a value of 0. Filter rules can be specified in the TCP/IP profile or in an IP Security policy file read by the Policy Agent. Filter rules can include a security class specification on the IpService statement in an IP Security policy file or on the SECCLASS parameter on the IPSEC statement in the TCP/IP profile.

Valid security classes are identified as a number in the range 1 - 255. The default value is 255. For more information about security class values, see z/OS Communications Server: IP Configuration Guide.

Restriction: The TCP/IP stack ignores this value if IPSECURITY is not specified on the IPCONFIG statement.

MONSYSPLEX | NOMONSYSPLEX

Specifies whether or not sysplex autonomics should monitor the link's status.

NOMONSYSPLEX

Specifies that sysplex autonomics should not monitor the link's status. This is the default value.

MONSYSPLEX

Specifies that sysplex autonomics should monitor the link's status.

Restriction: The MONSYSPLEX attribute is not in effect unless the MONINTERFACE keyword is specified on the GLOBALCONFIG SYSPLEXMONITOR profile statement. The presence of dynamic routes over this link is monitored if the DYNROUTE keyword is also specified on the GLOBALCONFIG SYSPLEXMONITOR profile statement.

Steps for modifying

See Modifying DEVICE and LINK statements for modifying information.

Usage notes

• If using a dynamic VIPA when connecting an OSA-Express QDIO Ethernet device to an intelligent bridge or switch, ensure that the Spanning Tree Protocol (STP) on the intelligent bridge or switch is configured properly for dynamic VIPA giveback and takeover operations. For more information, see z/OS Communications Server: IP Configuration Guide.
• Across one central processor complex (CPC), PRIROUTER can be specified only in the profile of one TCP/IP instance for the same MPCIPA device. If PRIROUTER is specified for an MPCIPA device but was already specified for the same device in the profile of another active TCP/IP instance, a warning message is issued during START DEVICE processing for the device. Depending on the level of OSA-Express being started, either only one or multiple TCP/IP instances can be allowed to have SECROUTER specified. If OSA-Express allows only one secondary router, any TCP/IP instance subsequently starting that device with SECROUTER receives a warning message during START processing for the device. If OSA-Express allows multiple secondary routers, then OSA-Express can select any TCP/IP instance which specifies SECROUTER as the secondary router. There is no requirement that the same TCP/IP instance be specified PRIROUTER or SECROUTER for all OSA-Express adapters attached to the CPC.
• MPCIPA devices have an ARP off-load function that off-loads all ARP processing to the OSA-Express adapter. For some MPCIPA devices, TCP/IP cannot display any ARP cache information or ARP counter statistics because OSA-Express does not provide this data to TCP/IP.

  For more information about devices that support ARP Offload, see z/OS Communications Server: IP Configuration Guide.

Related topics

• BEGINROUTES statement
• BSDROUTINGPARMS statement
• HOME statement
• INTERFACE - IPAQENET OSA-Express QDIO interfaces statement
• INTERFACE - IPAQENET6 OSA-Express QDIO interfaces statement
• SACONFIG statement
• START statement
• STOP statement