VARY TCPIP,,SYSPLEX

procname

The identifier of the TCP/IP address space. When the procname value is not specified, there can be only one TCP/IP address space started. If multiple TCP/IP address spaces are available and no procname value is specified, the request fails with an error message.

SYSplex

Requests to change a TCP/IP stack's DVIPA sysplex characteristics.

LEAVEgroup

Requests the TCP/IP stack to leave the sysplex group.

This causes the stack to leave the sysplex group, delete all dynamic DVIPAs, and deactivate all its configured VIPADYNAMIC definitions. The VIPADYNAMIC configuration information is retained for possible future use by the SYSPLEX,JOINGROUP command.

To rejoin the sysplex group it is necessary to issue a VARY TCPIP,,SYSPLEX,JOINGROUP operator command, which also reprocesses the stack's saved VIPADYNAMIC configuration.

Guideline: Do this only as a last resort if the operator has determined that this sysplex member is not functioning correctly and if the only other alternative would be to force the stack down. For more information, see sysplex problem detection and recovery information in the z/OS Communications Server: IP Configuration Guide.

Tip: The Netstat VIPADCFG/-F report can be used to view the saved VIPADYNAMIC configuration.

JOINgroup

Requests the TCP/IP stack to join the sysplex group.

When this command is issued, if VTAM® is not running or if the DELAYJOIN parameter is configured for GLOBALCONFIG SYSPLEXMONITOR and OMPROUTE is not initialized, the join does not take place until after VTAM (and OMPROUTE, if DELAYJOIN is configured) is initialized. If this command is issued after the stack has left the sysplex group, it also reprocesses the stack's saved VIPADYNAMIC configuration.

If NOJOIN is configured on the GLOBALCONFIG SYSPLEXMONITOR statement, the JOINgroup command overrides NOJOIN. When you issue the JOINgroup command, the TCP/IP stack joins the sysplex group, as long as VTAM is running and OMPROUTE is initialized (if the DELAYJOIN parameter is also configured for GLOBALCONFIG SYSPLEXMONITOR).

Tip: The Netstat VIPADCFG/-F report can be used to view the saved configuration prior to issuing the JOINgroup command.

Restriction: You cannot use this command to cause the stack to rejoin the sysplex group if the Sysplex Problem Detection cleanup function was unsuccessful and message EZZ9675E was issued, or if a previous attempt to process the saved VIPADYNAMIC configuration and join the TCP/IP sysplex group failed and message EZD1194 was issued. If either has occurred, you must restart the stack before it will be able to rejoin the sysplex group.

DEACTivate

Requests the TCP/IP stack to deactivate a dynamic VIPA. When you deactivate a dynamic VIPA, it appears as though the DVIPA has been deleted, but the DVIPA's configuration is saved.

DVIPA=dvipa

dvipa is the IPv4 address, IPv6 address, or IPv6 interface name of a dynamic VIPA (DVIPA) that is currently defined by VIPADEFINE or VIPABACKUP on this stack. The DVIPA can be in ACTIVE, BACKUP, or MOVING status.

The stack deactivates the DVIPA and ends any distribution for that DVIPA being done by this stack. The DVIPA configuration and any VIPADISTRIBUTE definitions are saved, and the deactivated DVIPA continues to be counted toward the maximum number of DVIPAs that can be defined on the stack. If there are existing connections to the DVIPA on this stack and there is another stack able to maintain the connections, the DVIPA is kept in QUIESCING status until the last connection terminates, and then the DVIPA is deactivated.

Guidelines:

• Deactivating an active DVIPA while the stack is part of the sysplex group allows an already-configured backup stack to takeover the DVIPA. (The stack that is serving as a backup for this DVIPA should have OMPROUTE active so that when it takes over the DVIPA it has the capability to advertise to others that it is the new owner).
• Deactivating a sysplex distributor DVIPA does not prevent the DVIPA from being marked as a target for distribution from another stack. As long as the application remains active on the stack, new connection requests can be distributed to it.
• Deactivating a backup DVIPA while the stack is part of the sysplex group makes the stack ineligible to takeover the DVIPA.
• This command can be issued after a stack has left the sysplex group. Because all the stack's DVIPA definitions are inactive while the stack is out of the group, the DVIPA is marked deactivated. If the stack later rejoins the group and restores its VIPADYNAMIC configuration, the DVIPA remains deactivated.
• A deactivated DVIPA can be reactivated using the VARY TCPIP,,SYSPLEX,REACTIVATE command.

Restriction: You cannot deactivate a VIPARANGE DVIPA created by BIND, SIOCSVIPA or SIOCSVIPA6 ioctl, or the MODDVIPA utility.

REACTivate

Requests that the TCP/IP stack redefine a deactivated dynamic VIPA using its saved configuration.

DVIPA=dvipa

dvipa is the IPv4 adddress, IPv6 address, or IPv6 interface name of a dynamic VIPA (DVIPA) that has been deactivated.

The stack will reestablish the DVIPA and any distribution for that DVIPA, based on the configuration that was saved when the DVIPA was deactivated.

Guidelines:

• Reactivating a VIPADEFINE DVIPA while the stack is part of the sysplex group allows a stack to take back the DVIPA.
• Reactivating a VIPABACKUP DVIPA while the stack is part of the sysplex group makes the stack again an eligible backup for the DVIPA, but does not typically trigger an immediate activation of the DVIPA. An exception to this behavior occurs when the following conditions are met:
  • The reactivated DVIPA's VIPABACKUP profile statement specified the MOVEABLE parameter.
  • The DVIPA is not active elsewhere in the sysplex.
• This command can be issued after a stack has left the sysplex group. Because all the stack's DVIPA definitions are inactive while the stack is out of the group, the DVIPA is marked as reactivated. If the stack later rejoins the group and restores its VIPADYNAMIC configuration, the DVIPA definition is restored.

QUIesce

Requests that the specified application, or all applications on a particular TCP/IP stack, be quiesced from DVIPA sysplex distributor workload balancing. After the command is issued, sysplex distributor will no longer route new TCP connection requests to the specified applications. Existing connections to these applications are not affected. This command must be issued on the local system where the applications are to be quiesced. This command can be useful in scenarios where you would like to temporarily divert new TCP connection requests away from a specific application or target system. One such scenario is when a particular application or system is to be shutdown (for example, in order to apply maintenance). Issuing this command prior to the shutdown can allow applications to gracefully complete any existing workload requests. PORT, JOBNAME or TARGET parameters must be specified following the QUIESCE keyword.

POrt=portnum

The port number parameter is an integer in the range 1 – 65 535 and is optional. Applications bound to this port number are excluded from DVIPA sysplex distributor workload balancing (they do not receive new TCP connection requests from sysplex distributor). If the portnum value specifies a port that has more than one instance of an application bound to it with either a different jobname or asid value, then either the JOBNAME value or the JOBNAME and ASID values must be specified to identify a unique specific application instance to be quiesced. PORT or TARGET parameters must be specified following the QUIESCE keyword.

JOBNAME=jobname

The jobname value specifies the MVS™ job name of the application with which the Quiesce command is associated.

• If the JOBNAME parameter is specified without the PORT keyword, then all applications with this jobname or asid value are quiesced regardless of the port they are bound to.
• If the jobname value specifies a job name that has more than one instance of an application with that job name but that has a different asid value, then the ASID parameter must also be specified and all application instances that have a matching job name are quiesced, regardless of the port they are using.
• The environment in which the application runs determines the job name that is to be associated with a particular client or server application.
• The jobname value can be up to 8 characters in length and is optional.

Guidelines:

• Applications submitted as batch jobs use the batch job name.
• Job names associated with applications started from the MVS operator console using the START command are determined as follows:
  • If the START command is issued with the name of a member in a cataloged procedure library (for example, S APP1), the job name is the member name (for example, APP1).
  • If the member name on the START command is qualified by a started task identifier (for example, S APP1.ABC), the job name is the started task identifier (for example, ABC).
  • The JOBNAME parameter can also be used on the START command to identify the job name (for example, S APP1,JOBNAME=XYZ).
  • The JOBNAME parameter can also be included on the JOB card.
• Applications run from a TSO user ID use the TSO user ID as the job name.
• Applications run from the z/OS® shell normally have a job name that is the logged on user ID plus a one-character suffix.
• Authorized users can run applications from the z/OS shell and use the _BPX_JOBNAME environment variable to set the job name. In this case, the value specified for the environment variable is the job name.
• z/OS UNIX applications started by INETD typically use the job name of the INETD server plus a one-character suffix.

ASID=asid

The asid value is optional and specifies the hexadecimal address space ID associated with the application to be quiesced. If the portnum value specifies a port that has more than one instance of that application bound to it and the jobname value is not unique, then you can specify an asid value to quiesce all application instances that match this port, job name, and asid value.

Guidelines:

• This command must be issued on the system and the TCP/IP stack where the application instance is running.
• This command applies to a single TCP/IP stack's application instance. If the server needs to be quiesced over multiple stacks in a CINET environment, the command would need to be issued on each stack.
• Any sysplex distributor timed affinities will be terminated. Existing connections are not affected.
• The quiesce state is associated with the application's active listening socket. If the application is recycled or if the application closes and opens a new listening socket on the specified port, the socket will no longer be in a quiesced state.
• If the application is bound to the unspecified address, it can continue to receive connection requests that are not using a distributed DVIPA as the destination IP address.
• Applications quiesced with the PORT= option can be resumed by issuing a RESUME command.

Rule: When applications are quiesced using the PORT= or JOBNAME= option followed by a quiesce TARGET option for the stack on which those applications reside, you can no longer resume individual applications using the PORT= or JOBNAME= option. Instead, you must resume the entire TCP/IP stack using the TARGET option.

Tips:

• The Netstat ALL command can be issued as follows to determine which applications have been quiesced: QUIESCED DEST|NO.
• When an application is quiesced, the ready count (Rdy) field that appears on the Netstat VDPT display (issued on the sysplex distributor routing stack) is decremented. If no other applications are listening on this port on this target TCP/IP stack, the count is zero.

TARGET

Requests that all applications on this TCP/IP stack be quiesced from DVIPA sysplex distributor workload balancing. Existing connections are not affected.

Guidelines:

• This command must be issued on the system and the TCP/IP stack that is being quiesced.
• This command applies to a single TCP/IP stack. If an entire system with multiple TCP/IP stacks in the CINET environment needs to be quiesced, then a command needs to be issued for each TCP/IP stack on the system.
• Any sysplex distributor timer-based affinities are terminated. Existing connections are not affected.
• While sysplex distributor will no longer route new distributed DVIPA TCP connection requests to this TCP/IP stack, any TCP connections that do not specify a distributed DVIPA address as the destination IP address continue to be serviced by this TCP/IP stack.
• The QUIESCE state for a TARGET persists for all applications (existing and new) running on this TCP/IP stack, until the TCP/IP stack is recycled or a V TCPIP,,RESUME,TARGET command is issued.
• When an entire TCP/IP stack is quiesced using the TARGET option, you cannot resume individual applications for workload distribution. You can, however, resume distribution for the entire TCP/IP stack using the V TCPIP,,RESUME,TARGET command.
• When an entire TCP/IP stack is quiesced using the TARGET option, a quiesce for an individual application on that target stack is ignored.

Tips:

• The Netstat ALL command can be issued to determine which applications have been quiesced: QUIESCED DEST|NO
• When a TCP/IP stack is quiesced, the ready count (Rdy) field that appears on the Netstat VDPT display (issued on the sysplex distributor routing stack) will be zero for all entries associated with this target TCP/IP stack.

RESUME

Requests that the specified application or all applications associated with a TCP/IP stack be resumed for DVIPA sysplex distributor workload balancing (become eligible for new TCP connection requests). A PORT, JOBNAME or TARGET value must be specified following the RESUME keyword.

POrt=portnum

The portnum value is an integer in the range 1 – 65 535. Applications bound to this port number will be resumed for DVIPA sysplex distributor workload balancing. If the portnum value specifies a port that has more than one instance of an application bound to it, then either the JOBNAME value or the JOBNAME and ASID values must be specified to identify a unique specific application instance to be resumed. PORT or TARGET value must be specified following the RESUME keyword.

JOBNAME=jobname

The jobname value specifies the MVS job name of the application with which the resume command is associated.

• If the JOBNAME parameter is specified without the PORT keyword, then all applications with this jobname or asid value are resumed, regardless of the port they are bound to.
• If the jobname value specifies a job name that has more than one instance of an application with that job name but with a different asid value, then you must also specify the ASID parameter and all application instances that have a job name that matches are resumed regardless of port value.
• The environment in which the application runs determines the job name that is to be associated with a particular client or server application.
• The jobname value is optional and can be up to 8 characters in length.

Guidelines:

• Applications submitted as batch jobs use the batch job name.
• The job name associated with applications started from the MVS operator console using the START command will be determined as follows:
  • If the START command is issued with the name of a member in a cataloged procedure library (for example, S APP1), the job name will be the member name (for example, APP1).
  • If the member name on the START command is qualified by a started task identifier (for example, S APP1.ABC), the job name will be the started task identifier (for example, ABC).
  • The JOBNAME parameter can also be used on the START command to identify the job name (for example, S APP1,JOBNAME=XYZ).
  • The JOBNAME value can also be included on the JOB card.
• Applications run from a TSO user ID use the TSO user ID as the job name.
• Applications run from the z/OS shell normally have a job name that is a combination of the logged on user ID plus a one-character suffix.
• Authorized users can run applications from the z/OS shell and use the _BPX_JOBNAME environment variable to set the job name. In this case, the value specified for the environment variable is the job name.
• z/OS UNIX applications started by INETD typically use the job name of the INETD server plus a one-character suffix.

ASID=asid

The optional asid value defines the hexadecimal address space ID that is associated with the application to be quiesced. If the portnum value specifies a port that has more than one instance of an application bound to it and the job name is not unique, then you can specify an asid value to quiesce all application instances that match this portnum, jobname, and asid value.

TARGET

Requests that all applications on this TCP/IP stack be resumed for DVIPA sysplex distributor workload balancing. PORT or TARGET must be specified following the RESUME keyword.

Guidelines:

• This command must be issued on the stack that is quiesced or the stack where the quiesced application instance is running.
• This command applies to a single TCP/IP stack's application instance. If the server needs to be resumed over multiple stacks in a CINET environment, the command would need to be issued on each stack.
• RESUME with the TARGET option is the only valid command following a QUIESCE with the TARGET option command.

Users can be authorized to invoke the command by permitting their user IDs for CONTROL access to the RACF® profile name MVS.VARY.TCPIP.SYSPLEX.