SEND

Send a message

SEND(message, message_id[, terminal])

Arguments

message

A variable that contains the message to be sent. (a)

message_id

The name that identifies the message (up to 6 characters, or 39 characters on OpenVMS). (a)

terminal

(optional) The number of the terminal to which the message will be sent. The number is operating system specific. (n)

Discussion

The SEND statement sends a message to the same or a different program. The maximum length of the message is system-dependent.

The message controller saves the message until it is retrieved by the RECV statement. Only a RECV statement with the same message ID can receive the message.

The sending 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.

Message facilities

There are two types of message facilities to process Synergy messages:

Local message facility (default)
Synergy message manager

The local message facility is maintained by the runtime. Once the runtime terminates, all messages in the local message facility are lost. If the local message facility is sufficient for your needs, we recommend using it rather than the Synergy message manager, which can incur additional processing overhead.

Unlike the local message facility, the Synergy message manager (which is the Synergy DBL daemon on UNIX) enables you to send messages between processes. The Synergy message manager is a detached program that retains and maintains your messages. Even after the runtime terminates, the messages still exist, and you can run another program and receive those messages.

To use the Synergy message manager on UNIX, you must set system option #7 with the DBLOPT environment variable. If you don’t set option #7, Synergy DBL uses the local message facility instead of the Synergy message manager for SEND and RECV statements.

On OpenVMS, the Synergy message manager is used by default. It writes errors to the log file DBLDIR:dblmsgctl.log. To disable the messaging facilities, set system option #47. The message manager can buffer up to 32,000 messages.

On Windows, there is no Synergy Message Manager; Synergy DBL uses only local queues.

Synergy DBL messages and message queues

Each Synergy DBL message is identified by a combination of the terminal number to which it is directed and a message ID of one to six characters (or one to thirty-nine characters on OpenVMS). If a SEND statement doesn’t specify a terminal number, the resulting message’s terminal identification includes the number of the terminal that initiated the program.

There are three kinds of messages:

Local (UNIX only)
Group
Global

On UNIX, each terminal running a Synergy program has its own local message queue into which messages are inserted. Messages are retrieved from this queue in “first in, first out” order, according to message ID. Each message in a terminal’s local queue is called a local message. By default, if you don’t specify a terminal number in a SEND statement, the message is inserted into the local message queue unless system option #1 or #13 is set. These options are explained in more detail below

Sometimes you’ll want to send a message that has an ID but that is not directed to any particular terminal. You can use either group messages or global messages for this purpose. If you are sending to or from a detached process, you need to use a group or global queue and the Synergy message manager.

A global message can be received by any program that explicitly specifies the correct message ID in its RECV statement. Synergy DBL provides one global message queue for your system. Any message directed to terminal number 255 is inserted into the global queue and can be retrieved by referencing the message’s ID.

A group message can be received by any program specifying the correct message ID and running under the same group number as the sending program. Synergy DBL provides one group message queue for each group (which consists of a unique project and programmer number combination for each account). Any message directed to terminal number 254 is inserted into the group queue.

If you specify system option #13 with the DBLOPT environment variable, a SEND statement that does not specify a terminal number sends the message to terminal number 254 (the group message queue) by default. If you specify system option #1, the message goes to terminal number 255 (the global message queue) by default. Option #13 supersedes option #1. Therefore, if you specify both options, option #1 is ignored.

If you need to send a message to a program that will be running in the future, send it to a group or global message queue using the Synergy message manager. Programs whose terminal number is negative (for example, detached processes or batch jobs) use a global message queue by default.

On OpenVMS, group messages are the same as global. Sending a message to terminal -1 is the same as sending to the global queue.

Receiving messages

Unless the DFLAG subroutine’s runtime option flag 1 is set, the RECV statement begins searching for a requested message ID in the local queue for that process. If no message ID is specified, RECV assumes that the message ID is [SELF]. If RECV can’t find a message that matches the specified ID, it searches first in the group message queue and finally in the global message queue for the first message with the specified ID.

If RECV can’t find the message in any of these queues, it returns a “message not found” status. You can also use the DFLAG subroutine to indicate that your program should wait for the requested message to become available if no message exists. If you set DFLAG’s runtime option flag 2, your program waits for the message and does not signal the “message not found” status.

By default, the RECV statement searches all three message queues in the order described above. However, you can use the RCFLG subroutine to disable the searching of any queue for a particular program. RCFLG enables you to change the searching algorithm of the Synergy message manager by setting one or more of its receive option flags.

Special message IDs

On Windows and UNIX, both message facilities recognize two message IDs that are specially interpreted:

[SELF] — The message ID is the default program name or the name set by the RCVID subroutine. [SELF] eliminates the need to update the message ID if the routine name changes and ensures that the SEND and RECV will function as intended. [SELF] sends to any program in the process chain.
[INIT] — No message is sent. Instead, [INIT] deletes all messages currently contained in the local message queue. Messages associated with other programs are not affected. When using the Synergy message manager, you can use [INIT] to restore the environment to a known state after a Synergy program terminates abnormally.

The square brackets around [SELF] and [INIT] are part of the message IDs.

When [SELF] is specified in the SEND statement, the program determines the message ID to send based on the current program name. When it is specified in the RECV statement, the program determines the message ID to look for based on the current program name. Therefore, if you SEND to [SELF] in program abc, the message ID will be “abc”. If you then chain to program xyz and do a RECV on [SELF], the program will look for “xyz”, not “abc”, and the message will not be found.

Examples

The following example shows a message being sent to another program, which receives it using the [SELF] ID.

The file records.def contains the following:

record cust_master 
name    ,a30 
addr    ,2a40 
city    ,a15 
state   ,a2 
zip     ,d5 
phone   ,d10 
fax     ,d10

The file custmain.dbl contains the following:

.include "records.def" 
proc 
xcall get_cusrec(cust_master) 
send(cust_master, "cust") 
stop "cust" 
end

The file customer.dbl contains the following:

main cust 
.include "records.def" 
record 
len ,d5 
proc 
if (%true) then 
recv(cust_master, nomsg, "[SELF]", len) 
else                            ;Recv wasn't chained to 
    begin 
nomsg, 
    xcall get_cusrec(cust_master) 
    end 
end