RECV

Receive a message

RECV(message, label[, message_id, length])

Arguments

message

A variable that is loaded with the received message, left-justified over blanks. (a)

label

A label to which control is transferred if no message is pending.

message_id

(optional) A variable that specifies the name of the message. It can be up to six characters long. (a)

length

(optional) A variable that will be returned with the length of the received message. (n)

Discussion

The RECV statement receives a message from a previously executed SEND statement in the same or a different program.

If the received message is longer than message, only the leftmost portion of the message is received and the remainder is ignored.

When a message is sent by the SEND statement, it is assigned a message ID. That message can only be received when the same ID is specified in a RECV statement. If message_id is not specified, the ID is assumed to be the name of the receiving routine (up to 31 characters, left-justified over blanks).

The receiving routine’s name is defined with the MAIN, FUNCTION, or SUBROUTINE statement. If MAIN is not used in the main routine, the filename is used as the message ID.

You can also use the specially interpreted [SELF] ID as the message ID. The [SELF] ID causes the name of the message ID to be the default program name or the name set by the RCVID subroutine.

If message_id is specified, length must also be specified. If more than one message with the same ID is outstanding, the messages are received in first-in-first-out order.

If length initially has a negative value, the message received is not deleted from the message pool, so it can be received again. If length is greater than or equal to zero, the message is deleted and cannot be received again. (This is called a destructive receive.) If length is not specified, a destructive receive is the default action.

On OpenVMS, the “SEND/RECV message failure” error ($ERR_MSGFAIL) on a RECV statement is normal if many messages are queued and the message controller has not yet processed them. In this case, the RECV has queued another message in sequence, but the message controller has not processed it in the time the runtime has allotted for a reply. You should retry the RECV if you are sure the message controller is actually running. This error protects the user from hanging if the message controller aborts; however, the time to wait is dependent on the processing activity and speed of the system, so you must determine if a retry is required.