VARY TCPIP,,SMCAT

Use the VARY TCPIP,,SMCAT command to control the SMC Applicability Tool (SMCAT). Shared Memory Communications (SMC) provides optimized communications for qualifying TCP connections. SMC includes the following types:
  • Shared Memory Communications - Direct Memory Access (SMC-D), introduced in z/OS® V2R2
  • Shared Memory Communications over RDMA (SMC-R), introduced in z/OS V2R1
You can use the SMCAT to evaluate TCP/IP network traffic and use the evaluation to plan for any potential use of SMC. To make the evaluation, you do not need to enable the SMC function on any system or enable the RoCE Express® features.

You can use the SMCAT to monitor a TCP/IP stack for a set of configured destination IP addresses or subnets, and to provide a report in the job log for the TCP/IP stack. Enabling SMCAT does not modify any network flows for the TCP connections that are monitored. Use the VARY TCPIP,,SMCAT command to turn on or turn off the SMCAT.

The report indicates the following information for TCP connections on that stack that use the specified destination IP addresses or subnets:

  • The percentage of all TCP connections that are connected to one of the configured IP addresses that qualify for SMC communications. These TCP connections are considered eligible to use SMC communications.
  • The percentage of the eligible connections that have a workload pattern best suited for SMC communications. These eligible connections are considered well-suited connections. Connections that are short-lived and exchange a small amount of data are not well-suited for SMC communications.
  • The percentage of all TCP workloads, measured in segments sent and received, that flowed over the SMC well-suited connections.
  • A breakdown of the application send and receive sizes that are used by the well-suited connections. In general, the performance benefits of SMC versus TCP increase because the application send and receive size increases.
The report is generated at the end of the interval and contains the following sections:
  • A TCP SMC traffic analysis for all matching connections section, containing data for all eligible TCP connections. All eligible TCP connections include connections that are not directly connected and those that are directly connected. This section indicates the total amount of workload that can use SMC communications with some network topology changes.
    • For the eligible TCP connections that are not directly connected, network traffic between the hosts requires traversal of a router that the SMC protocol does not support.
    • For the eligible TCP connections that are directly connected, network traffic between the hosts does not require traversal of any IP routers.
  • A TCP SMC traffic analysis for matching direct connections section, containing data only for the eligible TCP connections that are directly connected. For the eligible TCP connections that are directly connected, network traffic between the hosts does not require traversal of any IP routers. This section indicates the amount of workload that can immediately use SMC communications after SMC enablement. This section is a subset of the TCP SMC traffic analysis for all matching connections section.
  • An SMCAT Summary Report Export Area section, containing the values from the application send and receive sizes. This report can be sent to IBM® for an analysis of potential network CPU savings that SMC might provide.

The SMCAT report is written as a multi-line WTO message to the TCP/IP stack job log by using routing code 11. To ensure that the report is not displayed on the consoles, your consoles must not be configured to receive routing code 11 messages. You can activate the IBM Health Checker for z/OS Consoles CNZ_Console_Routcode_11 to determine whether any consoles receive routing code 11 messages.

Guidelines:
  • The TCP connections that meet the following requirements are considered eligible to SMC communications:
    • The destination IP address of the TCP connection matches an SMCAT configured IP address or subnet.
    • The TCP connections do not use IPSec or Fast Response Cache Accelerator (FRCA).
  • When you consider workloads for SMC-R and select the IP address to be measured, consider that RoCE is an Ethernet based technology that imposes limits on the distance between exploiting hosts. The RoCE is typically deployed within a site but can be deployed across sites by using IBM Z®® Qualified Wavelength Division Multiplexer (WDM) products for Multi-site Sysplex and GDPS® solutions to extend Ethernet LANs/VLANs up to 100 KM.
  • When you have many instances of hosts that provide similar workloads using similar application servers, consider measuring only a subset of the hosts and extrapolating the SMCAT results of your sample across your enterprise data center.
  • You can authorize users to invoke the command by permitting user IDs for CONTROL access to the RACF® profile name MVS™.VARY.TCPIP.SMCAT.

Format

Read syntax diagramSkip visual syntax diagram

Parameters

procname
The identifier of the TCP/IP address space. When the procname value is not specified, only one TCP/IP address space can be started. If more than one TCP/IP address space is available and no procname value is specified, the request fails with an error message.
SMCAT
Specify this parameter to turn on or turn off the analysis of TCP connections to determine whether the connections can potentially use the SMC function.
datasetname
If the datasetname value is specified, it indicates that the SMCAT is turned on. The datasetname value is the name of a data set that contains the SMCATCFG statement that specifies monitoring interval and the IP addresses or subnets to be monitored. The datasetname value must be a cataloged and fully-qualified data set name that is specified without any quotation marks. The datasetname value can be either a sequential data set or a member in a PDS. The datasetname value cannot be a z/OS UNIX file. See SMCATCFG input statement for a description of the contents of datasetname.
If the tool is active, the following error message is issued:
EZZ0140I SMCAT COMMAND REJECTED - SMC APPLICABILITY TOOL ALREADY ACTIVE
Guideline: To modify an active SMCAT datasetname configuration, the tool must be turned off and restarted with the modified configuration.
OFF
Indicates that the SMCAT is turned off and a report is generated. If the tool is not active, the following error message is issued:
EZZ0141I SMCAT OFF COMMAND IGNORED - SMC APPLICABILITY TOOL NOT ACTIVE
Tip: Consider capturing SMCAT reports during periods of time of interest. For example, capture the typical workloads during periods of steady state traffic that are representative of the target hosts.

SMCATCFG input statement

The data set that is specified on the VARY TCPIP,,SMCAT command must contain an SMCATCFG statement. This statement provides the monitoring interval value and the list of IP addresses or subnets whose TCP connections are to be monitored.

Restriction: Only one SMCATCFG statement can be specified in the data set.

Syntax

Read syntax diagramSkip visual syntax diagram

Parameters

SMCATCFG
This is a configuration statement for the SMCAT. The data set can contain only one SMCATCFG statement.
INTERVAL minutes
Specifies the length of time in minutes of the monitoring interval at which data is collected before the results are reported. Valid values are in the range 1 - 1440. The default value is 60 minutes.
IPADDR
Specifies a list of 32-bit IPv4 addresses in dotted decimal notation and 128-bit IPv6 addresses that use colon hexadecimal notation and IP subnets. You can use the SMCAT to monitor TCP connections from this stack to these remote IP addresses and IP subnets. SMC-R is a peer to peer protocol, so it requires that both peers are capable and enabled for SMC-R communications. As a result, the IP addresses that are specified reflect peer hosts that are either capable of SMC-R or might be capable in the future. The following information shows key considerations in specifying the destination IP addresses to be monitored:
  • When you use an IPv4 subnet or IPv6 prefix specification, all hosts on these networks are considered SMC-R eligible. If the specified network contains hosts that will be SMC-R capable and hosts that will not, specification of individual IP addresses is recommended.
  • If TCP connections from the local TCP/IP stack to a monitored peer use multiple IP addresses, all of the peer's IP addresses that might be used are specified. The peer's IP addresses include all IP addresses, static VIPAs, and dynamic VIPAs for that peer.
Guideline: If the destination peer and the local host can communicate directly over a shared subnet but the configured peer IP address is a static or dynamic VIPA in a different subnet, you must also configure the host IP address of the OSA used on the remote system to connect to the shared subnet. This ensures that connections to that VIPA over the shared subnet will be counted as direct connections by SMCAT monitoring.

If the SMCAT is turned on, you must specify at least one IP address or IP subnet. A limit of 256 combined individual IP addresses and IP subnets can be specified.

The following values are not allowed for IPv4 addresses:
  • Broadcast address (255.255.255.255)
  • Multicast addresses
  • Default loopback address (127.0.0.1)
  • INADDR_ANY address (0.0.0.0)
The following values are not allowed for IPv6 addresses:
  • Default loopback address (::1)
  • IPv4-mapped IPv6 addresses
  • IPv4-compatible IPv6 addresses
  • Multicast addresses
  • Unspecified address (::)
  • Reserved addresses
    Note: For information about the IPv6 reserved addresses, see Restrictions on IPv6 addresses configured in the TCP/IP profile in z/OS Communications Server: IP Configuration Reference.

Code examples

VARY,,SMCAT command

The following examples show the VARY command for the SMCAT.
  • The following example shows the command for turning on the SMCAT and directing it to a TCP/IP address space named TCPPROC. In the example, the sequential data set USER99.TCPIP.SMCAT1 contains the SMCATCFG statement.
    VARY TCPIP,TCPPROC,SMCAT,USER99.TCPIP.SMCAT1
  • The following example shows the command for turning off the SMCAT.
    VARY TCPIP,TCPPROC,SMCAT,OFF

SMCATCFG statement

The following examples show the SMCATCFG statement in the input data set.
  • The following example specifies one IP subnet to be monitored and uses the default interval of 60 minutes.
    SMCATCFG IPADDR 9.10.1.3/24
  • The following example specifies multiple IP subnets to be monitored and specifies an interval of 120 minutes.
    SMCATCFG INTERVAL 120
    IPADDR
      C5::1:2:3:4/126
      9.67.113.61/24

Report examples

Configuration report

The following example shows the report that is created by using the SMCAT when it is turned on. This report provides the configuration parameters that are used for the monitoring interval. In the example, the tool monitors the TCP connections for stack TCPCS2 over a 3 minute interval, for the list of IP addresses or subnets.

EZD2040I TCP/IP CS V2R2   TCPIP Name: TCPCS2 
SMC Applicability Configuration Parameters - 10/08/2014, 14:04:40.08   
Interval:    3 minutes 
IP addresses/subnets being monitored   

  9.3.1.2/32
  2004::4/128   
  9.1.1.2/24                                                           
  9.3.1.3/32                                                           
  2001::1/96                                                           
  9.3.3.2/20                                                           
  2003::3/116                                                          
  2002::3/96

End of configuration parameters  

Report field descriptions

Interval
The interval that is in effect when the SMCAT is turned on.
IP Addresses/subnets being monitored
A list of IP addresses or subnets that the SMCAT monitors.

Interval report

The following example shows the interval report that is created by using the SMCAT when the monitoring interval expires or when the tool is turned off.

EZD2033I TCP/IP CS V2R2   TCPIP Name: TCPCS2                             
                                                                            
SMC Applicability Interval Report - 10/08/2014, 14:07:32.06              
                                                                           
Configured Interval Duration:    3 minutes                               
Actual Interval Duration:        3 minutes                               
                                                                         
TCP SMC traffic analysis for all matching connections                    
-----------------------------------------------------                    
  Includes connections not meeting direct connectivity requirements      
                                                                         
     20% of all TCP connections can use SMC (eligible)             
       90% of eligible connections are well-suited for SMC               
     22% of all TCP traffic (segments) is well-suited for SMC      
       20% of outbound traffic (segments) is well-suited for SMC         
       25% of inbound traffic (segments) is well-suited for SMC          
                                                                         
  Interval Details:                                                      
    Total TCP Connections:                                         100   
    Total SMC eligible connections:                                 20   
          Total SMC well-suited connections:                        18   
    Total outbound traffic (in segments)                          1000   
          SMC well-suited outbound traffic (in segments)           200   
    Total inbound traffic (in segments)                            500   
          SMC well-suited inbound traffic (in segments)            125   
                                                                         
    Application send sizes used for well-suited connections:             
      Size                                 # sends     Percentage        
      ----                                 -------     ----------        
      1500 (<=1500):                            20      36%              
      4K (>1500 and <=4k):                      10      18%              
      8K (>4k and <= 8k):                        4       7%              
      16K (>8k and <= 16k):                      5       9%              
      32K (>16k and <= 32k):                    10      18%              
      64K (>32k and <= 64k):                     5       9%              
      256K (>64K and <= 256K):                   2       4%              
      >256K:                                     0       0%              
                                                                         
    Application receive sizes used for well-suited connections:             
      Size                                 # recvs     Percentage        
      ----                                 -------     ----------        
      1500 (<=1500):                            10      33%              
      4K (>1500 and <=4k):                       5      17%              
      8K (>4k and <= 8k):                        3      10%              
      16K (>8k and <= 16k):                      3      10%              
      32K (>16k and <= 32k):                     5      17%              
      64K (>32k and <= 64k):                     2       7%              
      256K (>64K and <= 256K):                   2       7%                     
      >256K:                                     0       0%      

TCP SMC traffic analysis for matching direct connections                 
--------------------------------------------------------                 
  Connections meeting direct connectivity requirements                   
                                                                         
     15% of all TCP connections can use SMC (eligible)                    
       93% of eligible connections are well-suited for SMC               
     15% of all TCP traffic (segments) is well-suited for SMC       
       15% of outbound traffic (segments) is well-suited for SMC         
       14% of inbound traffic (segments) is well-suited for SMC          
                                                                         
  Interval Details:                                                      
    Total TCP Connections:                                         100   
    Total SMC eligible connections:                                 15   
          Total SMC well-suited connections:                        14   
    Total outbound traffic (in segments)                          1000   
          SMC well-suited outbound traffic (in segments)           150   
    Total inbound traffic (in segments)                            500   
          SMC well-suited inbound traffic (in segments)             70   
                                                                         
    Application send sizes used for well-suited connections:             
      Size                                 # sends     Percentage        
      ----                                 -------     ----------        
      1500 (<=1500):                            15      37%              
      4K (>1500 and <=4k):                       7      17%              
      8K (>4k and <= 8k):                        3       7%              
      16K (>8k and <= 16k):                      4      10%              
      32K (>16k and <= 32k):                     8      20%              
      64K (>32k and <= 64k):                     3       7%              
      256K (>64K and <= 256K):                   1       2%                     
      >256K:                                     0       0%              
                                                                         
    Application receive sizes used for well-suited connections:             
      Size                                 # recvs     Percentage        
      ----                                 -------     ----------        
      1500 (<=1500):                             8      38%              
      4K (>1500 and <=4k):                       3      14%              
      8K (>4k and <= 8k):                        2      10%              
      16K (>8k and <= 16k):                      2      10%              
      32K (>16k and <= 32k):                     4      20%              
      64K (>32k and <= 64k):                     1       5%              
      256K (>64K and <= 256K):                   1       5%                     
      >256K:                                     0       0%         

    -------------------SMCAT Summary Report Export Area------------------

    20,10,4,5,10,5,2,0
    10,5,3,3,5,2,2,0
    15,7,3,4,8,3,1,0
    8,3,2,2,4,1,1,0

    -------------------End Export Area-----------------------------------

End of report                                                            

Report field descriptions

Configured Interval Duration
The interval that is in effect when the SMCAT is turned on.
Actual Interval Duration
The interval that the report covers. This value might be different from the value of the Configured Interval Duration field if the SMCAT is stopped by using the VARY TCPIP,,SMCAT,OFF command.
TCP SMC traffic analysis for all matching connections
The data for all eligible TCP connections. The eligible TCP connections are connections with a destination IP address that match configured IP addresses or subnets. All eligible TCP connections include the connections that are not directly connected and the connections that are directly connected. This section indicates the total amount of workload that can use SMC communications with some network topology changes.
Percentage of all TCP connections can use SMC (eligible)
The percentage of all TCP connections that match the configured IP addresses or subnets. These TCP connections are the SMC eligible connections.
Percentage of eligible connections are well-suited for SMC
The percentage of all SMC eligible connections that have a workload pattern best suited for SMC communications. These eligible connections are well-suited connections for SMC.
Percentage of all TCP traffic (segments) is well-suited for SMC
The percentage of all TCP workload, measured in segments sent and received, that flowed over well-suited connections for SMC.
Percentage of outbound traffic (segments) is well-suited for SMC
The percentage of all outbound TCP workload, measured in segments sent, that flowed over well-suited connections for SMC.
Percentage of inbound traffic (segments) is well-suited for SMC
The percentage of all inbound TCP workload, measured in segments received, that flowed over well-suited connections for SMC.
Interval details
The breakdown of the data that is used to calculate the percentages.
Total TCP connections
The number of all active TCP connections during the SMCAT monitoring interval.
Total SMC eligible connections
The number of active TCP connections that are connected to a configured IP address during the SMCAT monitoring interval. These TCP connections are considered eligible to use SMC communications.
Total SMC well-suited connections
The number of eligible TCP connections that have a workload pattern best suited for SMC communications. These eligible connections are considered well-suited connections. Connections that are short-lived and that exchange a small amount of data are not considered well-suited for SMC communications.
Total outbound traffic (in segments)
The amount of outbound traffic over all TCP connections during the SMCAT monitoring interval.
SMC well-suited outbound traffic (in segments)
The amount of outbound traffic over the SMC well-suited connections during the SMCAT monitoring interval.
Total inbound traffic (in segments)
The amount of inbound traffic over all TCP connections during the SMCAT monitoring interval.
SMC well-suited inbound traffic (in segments)
The amount of inbound traffic over the SMC well-suited connections during the SMCAT monitoring interval.
Application send sizes for well-suited connections
The number and the percentage of the application send sizes that are used by the well-suited connections. These percentages might not add up to exactly 100% due to rounding
Application receive sizes for well-suited connections
The number and the percentage of the application receive sizes that are used by the well-suited connections. These percentages might not add up to exactly 100% due to rounding
TCP SMC traffic analysis for matching direct connections
The data for only the directly connected eligible TCP connections. The directly connected eligible TCP connections use one of the configured IP addresses or subnets. This section indicates the amount of workload that can use SMC communications immediately after SMC enablement. This section is a subset of the TCP SMC traffic analysis for all matching connections section.
The fields under this section are the same as the fields under the TCP SMC traffic analysis for matching connections with direct network connectivity.