DEFINE MSGPROC

Read syntax diagramSkip visual syntax diagram DEFine MSGProc msgprocid VDEVice vdev DEVICES 4DEVicesn1SINGLE_message_path
Notes:
  • 1 The device count must be an even decimal number within the 4 to 16 range.

Authorization

Privilege Class: G

Purpose

Use the DEFINE MSGPROC command to define a virtual message processor and associated message devices in the issuer's virtual I/O configuration. This command establishes a coupling connection between a CFUSER defined user ID and the specified CF Service Machine running under z/VM®.

Operands

msgprocid
specifies the user ID of a z/VM Virtual Machine that is defined to run as a Coupling Facility. CP will establish a coupling connection between the user ID that issues this command and the user ID specified by msgprocid.
VDEVice vdev
is the virtual device number of the base message device that you are defining to CP. The device number must be a 1 to 4 digit hexadecimal number between X'0000' and X'FFFC'. The virtual device number specified will be the first of four consecutive device numbers created. If the specified device number is not valid or if it or any of the next three consecutive device numbers are already defined, this command will fail.
DEVices n
specifies the number of message devices to be created in the coupling guest. The number of devices (n) must be an even number between 4 and 16 inclusive; the default is 4.
SINGLE_message_path
will force only a single message path to be created for each message device. By default this command will create two message paths per message subchannel. Specifying SINGLE will turn off multi-path simulation when communicating with the Message Processor being defined.

Usage Notes

  1. The user must be authorized to issue this command via the CFUSER operand on the OPTION directory statement in the user directory. Without authorization, the MSGProc operand is rejected as not valid.
  2. The SPECIAL directory statement allows the system administrator to restrict which message processors that a user is allowed to define. If SPECIAL directory statements are used to define the message processors for the user, then the user can specify only those msgprocids on the DEFINE MSGPROC command. Specifying a msgprocid not defined by the SPECIAL directory entry causes the operand to be rejected as not valid.
  3. The msgprocid must be set up and authorized to run as a CF Service Machine via the CFVM operand on the OPTION directory statement in the user directory.
  4. The CF Service Machine that you specified must be active and running prior to issuing this command. If the CF Service Machine is not running disconnected, no message devices will be defined.
  5. A single coupled guest can connect to a maximum of 8 different CF Service Machines at the same time.
  6. The vdev chosen must be a hexadecimal number low enough for the addition of vdev plus the number of DEVICES minus 1 with a result less than or equal to X'FFFF'.

    You can only have one connection with each CF SVM. Therefore, if you want to change the vdev number from one you have already defined, you need to use the DETACH MSGPROC command to first detach the virtual message processor and then DEFINE MSGPROC command to define a new message processor.

  7. When DEVICES n is used, specify between 4 and 16 inclusive; this device count must be even. If DEVICES is not specified, the default is 4.

    You can have only one connection with each CF SVM. Therefore, if you already have defined a device using the default 4 and want to define a different device number, you need to use the DETACH MSGPROC command to first detach the virtual message processor and then use DEFINE MSGPROC command to define a new message processor.

  8. If msgprocid is not z/Architecture® mode, CP forces the DEVICES value to 4 no matter what was specified. The only indication of this is when confirmation message HCP2804I is displayed containing the actual device count that was used.
  9. To display information about virtual message processors in your I/O configuration, use the QUERY VIRTUAL MSGPROC command.
  10. To display information about the virtual message devices within your I/O configuration, use the QUERY VIRTUAL MSGDEVICES command.
  11. To restart a virtual message processor that is within your I/O configuration, use the RESTART MSGPROC command.
  12. To remove all message facility capability from your virtual machine, use the SET MSGFACIL OFF command.
  13. To detach a virtual message processor and associated virtual message devices, use the DETACH MSGPROC command.
  14. CHPIDs 8X and CX are used for the message devices. 'X' depends on when the connection was established between the coupling guest and the coupling facility relative to when other connections were made. A conflict exists when an OSA device is attached to a CFVM user and the OSA's CHPID is the same as that of a message device associated with the CFVM. When this happens, the following MVS errors are received when trying to bring the OSA online: 
    IEE103I UNIT 0420      NOT BROUGHT ONLINE
IEE763I NAME= IOSVDSEO CODE= 0000000800000000
IOS576I OSA DEVICES REQUIRE AN OSA CHANNEL PATH BUT
TYPE 0B FOUND TYPE=COUPLING FACILITY SENDER
  15. For more information, see the DEFINE command.

Responses

Response 1:

To define a connection with four message devices and two Message Paths to a CF Service Machine user ID CFCC1, enter the following:

def msgp cfcc1 vdev 700
HCP2804I Message devices 0700-0703 defined and coupled to CFCC1.
Ready;

Messages

For the list of general messages for the DEFINE command, see Messages.