COUPLE
Authorization
Privilege Class: G
Purpose
Use COUPLE to connect a virtual channel-to-channel adapter (CTCA) to a compatible virtual CTCA, or to connect a simulated network interface card (NIC) to a compatible guest LAN or virtual switch.
Operands
- vdev1
- is the virtual device number (hex) of a CTCA, or network device in the invoker's virtual machine configuration. If vdev1 is a virtual CTCA, it can be connected with a compatible virtual CTCA (designated by userid vdev2). If vdev1 is a fully-simulated virtual OSA device type (created by the DEFINE NIC command), the adapter can be connected to a compatible guest LAN (designated by ownerid and lanname).
- userid vdev2
- is the target 'remote' virtual CTCA when vdev1 is a virtual CTCA. If userid is specified as *, it represents the user ID of the invoker. Use this form of the command to connect two virtual CTCA devices to emulate a single adapter. The invoker should be able to communicate with the 'remote' virtual machine using software appropriate for a compatible physical CTCA.
- cfgowner cfgname
- if a network is configured on the NICDEF user directory statement, the COUPLE command defaults to the configured network (cfgowner cfgname).
- ownerid lanname
- identifies a guest LAN as the target of the connection when vdev1 is a virtual OSA device. The subject adapter is connected to the LAN named lanname owned by ownerid. Use this form of the command to connect a simulated network interface card (NIC) to a guest LAN. After a successful connection, the invoker should be able to communicate with other virtual machines on the same guest LAN using software appropriate for a comparable physical network adapter.
- SYSTEM switchnm
- identifies a virtual switch as the target of the connection when vdev1 is a virtual OSA device. Use this form of the command to connect a simulated network interface card (NIC) to a virtual switch.
- PORTnumber AUTO
- CP determines the virtual switch port number to be used.
Connect using an automatically assigned port number. If a NICDEF PORTNUMBER is configured for this device, the configured port and associated NICDEF attributes will be used. If a single port has been reserved for this user (using SET VSWITCH), the port and its associated port settings will be used. If more than one port has been reserved for this user, then the COUPLE command will fail because it cannot automatically resolve port number.
- PORTnumber portnum
- The NIC is coupled to the specified portnum on the virtual switch. The specified portnum must be configured by SET VSWITCH, or the NICDEF must include network attributes. Otherwise the COUPLE command will fail. The portnum is a value from 1 to 2048.
Usage Notes
- If you do not specify TO, the userid you specify cannot be T or TO.
- If vdev1 is already connected to another virtual device, a guest LAN, or a virtual switch, that connection is broken. However, when a target virtual CTCA is already connected to another virtual device, the existing connection is not broken.
- If an external security manager is installed on your system, you may not be authorized to enter this command. For additional information, contact your security administrator.
- The connection established by the COUPLE command is automatically broken when the adapter, the guest LAN, or the virtual switch is detached. If you need to break this connection without detaching the adapter, the guest LAN, or the virtual switch, use the UNCOUPLE command.
- A simulated network interface card (NIC) can be coupled only to a compatible guest LAN or virtual switch. For example, a QDIO NIC can be coupled only to a QDIO LAN or a QDIO virtual switch. Any attempt to connect to an incompatible network will be rejected and reported by message HCP6024E.
- To connect a NIC to a virtual switch:
- The connection may be configured by the NICDEF user directory statement that defines this virtual NIC. This method binds the port configuration to a specific virtual NIC in the user directory. When NICDEF LAN is configured, it also authorizes the connection (without the need for a SET VSWITCH command). If the network is protected by an External Security Manager (ESM) then use the appropriate ESM interface to authorize this connection.
- A user-defined port may be configured with the SET VSWITCH PORTNUMBER command. This method binds the network configuration to a specific port (in the range 1-2048) and allows the user to decide which virtual NIC to connect with each port. Use the appropriate External Security Manager (ESM) interface to grant authorization if the virtual switch is protected by an ESM.
- A port may be configured with the SET VSWITCH GRANT command where the port number is assigned by z/VM®. This method binds the network configuration to a user ID. Any virtual NIC belonging to this user will be connected to a port (in the range 2176-4095) and will adopt the port configuration. Use the appropriate External Security Manager (ESM) interface to grant authorization if the virtual switch is protected by an ESM.
- After the virtual NIC is coupled to a virtual network, the port configuration can
be changed dynamically:
- Use a SET VSWITCH GRANT or PORTNUMBER command to change the configuration, including the configured Virtual Local Area Network (VLAN) ID set, dynamically. The guest does not have to uncouple and re-couple to activate this change. This method only overrides the NICDEF configuration until the next time this virtual NIC is coupled to the virtual network.
- If the NICDEF statement (in the user directory) provides network configuration, update the directory with a new configuration and refresh the configuration by having the guest uncouple and re-couple to the virtual network.
- For a virtual CTCA the specified user must be logged on, and the virtual machine must have a virtual CTCA defined. The virtual machine may be operating in disconnect mode.
- If you want to connect the vdev1 CTCA to another CTCA in your own virtual machine, specify userid as an asterisk (*).
- The vdev2 user must have authorized the connection using the DEFINE CTCA command or the SPECIAL directory entry.
- The originator of the command and the owner of the coupled CTCA (if different from the originator) receive messages indicating that the CTCAs have been coupled.
- It is possible to
UNCOUPLE
a virtual CTCA device by using an obscure form of the COUPLE command (COUPLE vdev1 TO * vdev1). This method is supported for compatibility, but should be replaced by the UNCOUPLE command. Message HCPCPL058E (RC58) results when using this method. - The virtual ESCON® devices (defined with subclass SCTC, BCTC or CNC) cannot be coupled to
virtual 3088 devices (defined with subclass CTCA or 3088), or to virtual FICON® devices (defined with subclass FCTC). A virtual ESCON connection requires one controller (SCTC or BCTC) coupled
with one non-control device (the CNC). The following combinations are permitted for ESCON devices:
- COUPLE a subclass SCTC device with a subclass CNC device to get a virtual ESCON connection in Standard Mode
- COUPLE a subclass BCTC device with a subclass CNC device to get a virtual ESCON connection in Basic Mode.
A virtual FICON device (defined with FCTC) cannot be coupled to virtual 3088 devices (defined with subclass CTCA or 3088) or to virtual ESCON devices (defined with subclass SCTC, BCTC, or CNC).
Any other combination of virtual device types will be rejected and the invoker will receive message HCP6024E.
Responses
CTCA vdev1 COUPLED TO userid vdev2
is the normal response sent to the invoker of the COUPLE command when
vdev1 represents a virtual CTCA.- vdev1
- is the virtual device address of the invoker's CTCA.
- userid vdev2
- is the user ID and virtual device address of the targeted CTCA.
CTCA vdev2 COUPLED BY invoker vdev1
is the normal response sent to the owner of the target CTCA.- vdev2
- is the virtual device address of the targeted CTCA.
- invoker vdev1
- is the user ID and virtual device address of the originating CTCA.
CTCA vdev1 DROPPED FROM userid vdev2
is the normal response sent to the invoker (and to the other userid) if the originating CTCA was
already coupled to a different device.- vdev1
- is the virtual device address of the
local
CTCA. - userid vdev2
- is the user ID and virtual device address of the
remote
CTCA.
NIC vdev1 is connected to ownerid lanname
is the normal response sent to the invoker if vdev1 is part of a simulated
network interface card (NIC).- vdev1
- is the virtual device address that is part of a simulated network interface card (NIC).
- ownerid lanname
- is the fully-qualified name of the coupled guest LAN.
NIC vdev1 is connected to SYSTEM switchnm
is the normal response sent to the invoker if vdev1 is part
of a simulated network interface card (NIC) connected to the virtual network via a port assigned by z/VM (2176-4095).- vdev1
- is the virtual device address that is part of a simulated network interface card (NIC).
- switchnm
- is the name of the virtual switch.
NIC vdev1 is connected to SYSTEM switchnm port portnumber
is the
normal response sent to the invoker if vdev1 is part of a simulated
network interface card (NIC) connected to the virtual network via a user-defined port (1-2048).- vdev1
- is the virtual device address that is part of a simulated network interface card (NIC).
- switchnm
- is the name of the virtual switch.
- portnumber
- is the port number assigned to the connection.
Messages
- HCP006E Invalid device type - {rdev|vdev|ldev}
- HCP011E Invalid device type - userid vdev
- HCP020E Userid missing or invalid
- HCP022E A virtual device number was not supplied or it was invalid.
- HCP040E Device {rdev|vdev|ldev} does not exist
- HCP045E userid not logged on
- HCP047E userid vdev does not exist
- HCP058E CTCA vdev busy on userid
- HCP644E Unknown/unauthorized CP command COUPLE
- HCP2785E LAN name is missing
- HCP2786E NIC vdev not connected; the LAN name is not valid
- HCP2787E NIC vdev not connected; LAN ownerid lanname does not exist
- HCP2788E NIC vdev not connected; already connected to LAN ownerid lanname
- HCP2788E NIC vdev not connected; already connected to VSWITCH switchnm
- HCP2788E NIC vdev not connected; already connected to VSWITCH ownerid switchname port portname.
- HCP2789E NIC vdev not connected; LAN ownerid lanname has reached its MAXCONN limit
- HCP2791E NIC vdev was not connected to a LAN
- HCP2848E A VLAN list is not allowed for a [guest LAN | virtual switch with the VLAN UNAWARE attribute | virtual switch when your PORTTYPE is ACCESS]
- HCP2849E ESM VLAN configuration error. [No VLANs were provided for a VLAN AWARE virtual switch | Invalid VLAN ID provided.]
- HCP3034E NIC vdev not connected; port number was not specified.
- HCP3034E NIC vdev not connected; port portnum is not defined.
- HCP3034E NIC vdev not connected; NIC vdev2 is already connected to VSWITCH SYSTEM switchname port portnum.
- HCP3034E NIC vdev not connected; Uplink NIC port number portnum does not match.
- HCP3034E NIC vdev not connected; Uplink NIC port number portnum was requested.
- HCP3034E NIC vdev not connected; port portnum is already connected.
- HCP3034E NIC vdev not connected; all system assigned ports are in use.
- HCP3041E Port number is missing.
- HCP3042E Port number is not valid.
- HCP3043E AUTO is the only PORTNUMBER option allowed for a guest LAN.
- HCP3044E ESM VLAN configuration error. ESM VLAN IDs do not match VLAN IDs for port portnum.
- HCP3046E Port number conflicts with configured port portnum.
- HCP3171E NIC vdev is not connected; COUPLE to an IVL virtual switch is not allowed.
- HCP6011E You are not authorized to COUPLE to {userid vdev|ownerid lanname|ownerid switchname|ownerid switchname port portnum}
- HCP6011E You are not authorized to COUPLE to {userid vdev|ownerid lanname|ownerid switchname|ownerid switchname port portnum} with NIC vdev.
- HCP6024E Incompatible device - userid vaddr is a vdevtype device.
- HCP6024E Incompatible LAN - ownerid lanname is a vdevtype LAN.
- HCP6525E External Security Manager is unavailable.
- HCP6528E The ESM has more than 2000 VLAN entries so the COUPLE command cannot be completed.