SEND

Authorization

Privilege Class: C, G

Purpose

Operands

CP

indicates that CP should process the input text on behalf of the receiving virtual machine. If the first four characters of the text you want to send are your logical escape character, the receiver's logical line end character, and CP, then you need not specify the CP operand to send a CP command. The same holds true if the receiver's virtual machine is already in CP READ. If you specify the CP operand with no text, the receiving virtual machine is placed in console function mode, just as if a #CP command were entered.

userid

identifies the virtual machine that is to receive the console input.

prtid

indicates that the command is to be passed for processing to the print server virtual machine designated by prtid. The print server virtual machine that receives and processes the SEND command also provides prtid. The operand prtid is one to eight alphanumeric characters. If you specify four or fewer characters for the prtid, prtid cannot contain all hexadecimal characters, because CP then interprets prtid as rdev.

AT

indicates that the target user ID is on another member of the SSI cluster. AT sysname is required if the target user ID is a multiconfiguration virtual machine instance on another member of the SSI cluster.

sysname

is the system name of an active member in the SSI cluster.

text

is the data that is passed to the disconnected virtual machine as console input. Mixed DBCS data may be used as input text.

Usage Notes

1. Use a send cp userid command (without text) to force a CP READ when no CP READ exists.
2. If you are a secondary user, you might receive one of the following messages from the primary user:

   HCP150A  User userid has issued a CP read
   HCP150A  User userid has issued a VM read
   HCP150A  User userid has issued a CP or VM read.

   To reply to the message, issue one of the following SEND commands:

   send userid text
   send cp userid text

   Whether you need to specify the CP operand on the SEND command depends on the following principles:

   • If there is no CP read or VM read pending on the primary user's console, then SEND (without CP) will be posted as unsolicited input to either CP or the virtual machine, based on the TERM MODE setting. This is analogous to typing input when the screen shows RUNNING status.
   • If there is a CP read pending on the primary user's console, then SEND (without CP) will satisfy that CP read. This is analogous to typing input when the screen shows CP READ status.
   • If there is a VM read pending but no CP read pending on the primary user's console, then SEND (without CP) will satisfy that VM read. (A CP read supersedes a VM read.) This is analogous to typing input when the screen shows VM READ status.
   • SEND CP always either satisfies a CP read, if one is pending, or is presented as an unsolicited CP command. This is analogous to typing input prefixed with #CP.
   The different cases are shown in Table 1.

   Table 1. Issuing the SEND Command with or without the CP Operand

   CP Read Pending	VM Read Pending	TERM MODE	Effect ofSEND userid text	Effect ofSEND CP userid text
   No	No	VM	input goes to virtual machine	input goes to CP
   No	No	CP	input goes to CP	input goes to CP
   No	Yes	VM	input satisfies VM read	input goes to CP
   No	Yes	CP	input satisfies VM read	input goes to CP
   Yes	No	VM	input satisfies CP read	input satisfies CP read
   Yes	No	CP	input satisfies CP read	input satisfies CP read
   Yes	Yes	VM	input satisfies CP read	input satisfies CP read
   Yes	Yes	CP	input satisfies CP read	input satisfies CP read
   Notes: input goes to CP means the input is treated as unsolicited input and therefore is treated the same as a #CP command typed at the console. input goes to virtual machine means the input is treated as unsolicited input; it causes an attention interruption on the virtual console, and is supplied as the response to the line mode read which the guest is expected to post in response to that interruption.

3. If you are a Class G user, then:
   1. The receiving virtual machine must be disconnected at the time you enter the SEND command.
   2. You must be authorized as the secondary user on the CONSOLE statement in the directory entry of the receiving virtual machine or authorized as a result of the receiving virtual machine's use of the CP SET SECUSER command.
   3. The secondary user must not be disconnected when the SEND command is issued, unless the secondary user has a valid path to the *MSG or *MSGALL system service.
4. If you are not the receiving virtual machine's secondary user, you do not receive responses to the commands you send it.
5. If both a CP read and a VM read are pending, the CP read is satisfied first, regardless of the order in which they were posted.
6. If you want to send multiple lines of input on a single SEND command, use the receiver's logical-line-end character preceded by your logical-escape character to separate the lines. The receiving virtual machine must also have line editing enabled. This restriction applies to when you SEND a #CP command as well.

   If any of your logical-line-editing characters are part of the text to be sent to the disconnected virtual machine, they must be preceded by your logical-escape character.

7. For prtid, the virtual machine associated with the prtid processes the specified text. Therefore, the text on the SEND command must be valid for the virtual machine that is doing the processing.
8. You cannot use the class C version of this command if an external security manager is installed on your system and security label checking is enabled. For additional information, contact your security administrator.
9. Within a single system, the FOR command is an alternative to the SEND command. The FOR command is used to issue CP commands to other virtual machines and provides responses and return codes to the issuer. The responses can be directed to the console or handled by an IUCV connection to the Asynchronous CP Command Response (*ASYNCMD) system service. The target virtual machine does not see the command or command responses. See the description of FOR for further details.
10. If you are using the SEND command to send an AT command, you can preface the AT command with CP to avoid confusion with the SEND command AT operand.
11. In an SSI cluster, the secondary user and primary user can be logged on to different member systems.
    If either user is a multiconfiguration virtual machine:

    • The secondary user will function in that capacity only when it is local (logged on to the same member as the primary user). If the primary user is a multiconfiguration virtual machine, the secondary user must be logged on to the same member as the instance of the primary user for which the secondary user setting was established:
      • If the setting was established by a CONSOLE statement in the identity entry in the primary user's virtual machine definition, a potential secondary user relationship exists for every member instance of the primary user.
      • If the setting was established by a CONSOLE statement in a subconfiguration entry in the primary user's virtual machine definition, a potential secondary user relationship exists for that member instance of the primary user.
      • If the setting was established by a SET SECUSER command, a potential secondary user relationship exists for the member on which the SET SECUSER command was issued.
    • If the secondary user is remote:
      • The secondary user can issue SEND commands to the primary user. The AT sysname operands are required if the primary user is a multiconfiguration virtual machine instance.
      • The secondary user will not receive responses to SEND commands or any other output from the primary user.

Messages

• HCP020E Userid missing or invalid
• HCP045E userid not logged on
• HCP068E SEND command failed; text
• HCP1149E Error communicating with another SSI member. It cannot be determined if command executed remotely.
• HCP2970E The SSI cluster member name is missing or invalid.
• HCP2971I Specified SSI cluster member is not joined.