Horizon SOUL interface

Overview

This section describes individually the SOUL statements used by Horizon. The description of each statement contains usage information, complete syntax, and conversation state dynamics.

Dependence on conversation state

Remember that the Horizon SOUL statements that can be issued by a process are dependent on the state of the particular conversation. This state can be determined by using the QUERY PROCESS statement, which is described in this section.

Error checking

Error conditions encountered during the execution of the Horizon SOUL statements are not displayed on the terminal. The SOUL request should check for errors by using the $STATUS and $STATUSD functions. The text of the most recently issued error message can be retrieved by using the $ERRMSG function.

CLOSE PROCESS statement

Function

The CLOSE PROCESS statement deallocates the specified conversation from the process.

Syntax

The CLOSE PROCESS format follows:

CLOSE PROCESS {cid | processname | %variable} [SYNCLEVEL | FLUSH | CONFIRM | ERROR | %variable]

Where:

• cid or processname or %variable is the conversation ID on the OPEN PROCESS statement for this conversation.
• If no CID value is specified on the OPEN PROCESS statement, processname should be used. If a CID value is specified on the OPEN PROCESS, you also must specify that value here on the CLOSE PROCESS statement.
• SYNCLEVEL specifies that the actions taken depend on whether CONFIRM or NOCONFIRM is specified on the DEFINE PROCESS command:
  • If CONFIRM is specified, the actions indicated by CLOSE PROCESS CONFIRM are taken.
  • If NOCONFIRM is specified, the actions indicated by CLOSE PROCESS FLUSH are taken.

  SYNCLEVEL is the default.

• FLUSH specifies that any data buffered by preceding SEND statements is transmitted to the remote partner before the conversation is deallocated.
• CONFIRM specifies that a CONFIRM request is sent to the remote partner before the conversation is deallocated. CONFIRM also implies a buffer flush.
• ERROR specifies that the conversation is terminated abnormally.
• %variable contains "SYNCLEVEL," "FLUSH," "CONFIRM," or "ERROR."

Conversation state

Valid conversation states

State	Statement
Send state	For CLOSE PROCESS with SYNCLEVEL, CONFIRM, or FLUSH
Send, Receive, or Confirm state	For CLOSE PROCESS with ERROR

Status codes

S / SD	New state	Description
0 / 0	Reset	Normal completion.
2 / 2	Receive	SEND ERROR statement issued by partner.
4 / 0	Reset	Partner process closed conversation normally.
4 / 1	Reset	Partner process ended abnormally.
5 / any	no change	Parameter check (coding error). See $STATUS/$STATUSD codes and error messages.
10-99	Close	Resource allocation failures. See $STATUS/$STATUSD codes and error messages.

CONFIRM statement

Function

CONFIRM sends a confirmation request to the remote partner. After issuing CONFIRM, the sending program waits for the receiver to issue CONFIRMED or SEND ERROR. This exchange allows the local and remote partners to synchronize their processing. CONFIRM causes the conversation buffer, which contains all accumulated messages, to be flushed.

Syntax

The CONFIRM statement format follows:

Confirm {cid | processname | %variable} REQSEND %variable

Where:

• cid or processname or %variable is the conversation ID on the OPEN PROCESS statement for this conversation.
• If no CID value is specified on the OPEN PROCESS statement, processname should be used. If a CID value is specified on the OPEN PROCESS, you also must specify that value here on the CONFIRM statement.
• REQSEND %variable is used to detect a signal from the partner. While the conversation is in Send state, a SIGNAL PROCESS (REQUEST_TO_SEND) statement from the conversation partner can be received, indicating that the partner wishes to enter Send state.

  Reception of a SIGNAL from the partner is indicated in the REQSEND %variable:

  • A value of 1 indicates a SIGNAL was received.
  • A value of 0 indicates no SIGNAL was received.

Conversation state

Valid conversation state: Send

S / SD	New State	Description
0 / 0	Send	Normal completion.
2 / 2	Receive	SEND ERROR statement issued by partner.
3 / 3	no change	State check.
4 / 1	Close	Partner process ended abnormally.
5 / any	no change	Parameter check (coding error). See $STATUS/$STATUSD codes and error messages.
10-99	Close	Resource allocation failures. See $STATUS/$STATUSD codes and error messages.

CONFIRMED statement

Function

The CONFIRMED statement sends a positive confirmation to the remote partner that the last statement was executed successfully. This is only issued in response to a CONFIRM request.

Syntax

The syntax of the CONFIRMED statement follows:

Confirmed {cid | processname | %variable}

Where:

• cid or processname or %variable is the conversation ID on the OPEN PROCESS statement for this conversation.
• If no CID value is specified on the OPEN PROCESS statement, processname should be used. If a CID value is specified on the OPEN PROCESS, you also must specify that value here on the CONFIRMED statement.

Conversation state

Valid conversation state: Confirm

S / SD	New State	Description
0 / 0	Receive	Normal completion when issued in Confirm state.
	Send	Normal completion when issued in Confirm Send state.
	Close	Normal completion when issued in Confirm Close state.
3 / 3	no change	State check.
5 / any	no change	Parameter check (coding error). See $STATUS/$STATUSD codes and error messages.
10-99	Close	Resource allocation failures. See $STATUS/$STATUSD codes and error messages.

FLUSH PROCESS statement

Function

The FLUSH PROCESS statement causes the conversation buffer to be sent to the remote partner.

Syntax

The FLUSH PROCESS format follows:

FLUSH PROCESS {cid | processname | %variable}

Where:

• cid or processname or %variable is the conversation ID on the OPEN PROCESS statement for this conversation.
• If no CID value is specified on the OPEN PROCESS statement, processname should be used. If a CID value is specified on the OPEN PROCESS, you also must specify that value here on the FLUSH PROCESS statement.

Conversation state

Valid conversation state: Send

Status codes

S / SD	New State	Description
0 / 0	Send	Normal completion.
2 / 2	Receive	SEND ERROR statement issued by partner.
3 / 3	no change	State check.
4 / 1	Close	Partner process ended abnormally.
5 / any	no change	Parameter check (coding error). See $STATUS/$STATUSD codes and error messages.
10-99	Close	Resource allocation failures. See $STATUS/$STATUSD codes and error messages.

INVITE statement

Function

The INVITE statement permits a program to request data from one or more partners simultaneously and allows the issuing program to continue to run while its requests for data are being processed. The INVITE statement causes the send buffer to be flushed to the partner, and it places the partner in Send state, enabling the partner to send data when it is ready. After INVITE is issued, the issuing program continues to execute.

The program that issues INVITE has the option of requesting that its partner send confirmation before entering Send state.

Usage

The INVITE statement is used to change the direction of the conversation from Send to Receive state. The RECEIVE statement is used to accept the data transmitted by the partner.

Following each INVITE statement you may issue multiple RECEIVE statements to accept data sent in reply to the INVITE. However, issuing consecutive INVITEs to the same partner is an error. Since INVITE may be issued only in Send state, and since the first INVITE statement changes the conversation state from Send to Receive, a second INVITE results in a state check. When the "inviting" partner next receives a send indication from its partner, it again enters Send state and may again issue INVITE.

Syntax

The INVITE statement format follows:

Invite {cid | processname | %variable}
[SYNCLEVEL | FLUSH | CONFIRM]

Where:

• cid or processname or %variable is the conversation ID on the OPEN PROCESS statement for this conversation. If no CID value is specified on the OPEN PROCESS statement, use the process name.
• SYNCLEVEL, the default, specifies that the actions taken depend on whether CONFIRM or NOCONFIRM is specified on the DEFINE PROCESS command for the program that issues this INVITE:
  • If CONFIRM is specified, the actions described below for INVITE CONFIRM are taken.
  • If NOCONFIRM is specified, the actions described below for INVITE FLUSH are taken.
• FLUSH causes the LU to flush the contents of the send buffer, sending with it a change-direction indicator. The remote partner enters Send state.
• CONFIRM causes the local LU to flush the contents of the send buffer along with a confirmation request and a change-direction indicator. The remote partner enters Confirm state and must issue an appropriate verb (CONFIRMED, SEND ERROR, or CLOSE). If it issues CONFIRMED or SEND ERROR, it then enters Send state.

  INVITE CONFIRM is valid only when the conversation's synchronization level is CONFIRM.

Conversation state

Valid conversation state: Send

Status codes and state transitions

S / SD	New State	Description
0 / 0	Receive	OK
2 / 2	Receive	Partner responded to INVITE CONFIRM with SEND ERROR
3 / 3	no change	State check (issued in wrong conversation state)
4 / 1	Close	Partner process ended abnormally
5 / any	no change	Parameter check (coding error). See $STATUS/$STATUSD codes and error messages.
10-99	Close	Resource allocation failures. See $STATUS/$STATUSD codes and error messages.

OPEN PROCESS statement

Function

The OPEN PROCESS statement allocates local resources necessary for a conversation. These resources include local storage as well as a session connecting the local Model 204 system to the remote partner. If a non-busy session is available, it is used; otherwise an attempt to activate a new session is made if session limits have not been reached.

There are two distinct uses of the OPEN PROCESS statement:

• For a client process, it allocates an outbound conversation.

  An outbound conversation is identified by the absence of the ACCEPT clause. Allocation involves creating control blocks, getting control of a session for the conversation, and requesting the initiation of the remote process with optional initialization parameters.

• For a server process, it identifies an inbound conversation.

  An inbound OPEN PROCESS statement, identified by OPEN PROCESS with the ACCEPT clause, may be issued only by a server process. It receives any initialization parameters passed to it during the initialization of the conversation by the client process.

In addition, the OPEN PROCESS statement establishes the conversation ID (CID) for both types of conversations.

Usage

A conversation begins when an OPEN PROCESS statement is issued in a SOUL request. A conversation ends when one of the following happens:

• The request issues the CLOSE PROCESS statement.
• The end user's thread returns to command level.
• The request issues the END statement (TPROCESS only).
• The request is cancelled.
• The thread is restarted.
• The network connection is severed by the Model 204 system administrator who issues the CLOSE LINK command.
• The communication path (session) is broken by some external event beyond the control of Model 204.

Syntax

The OPEN PROCESS format follows:

OPEN PROCESS {processname] %variable} [CID {name | %variable}]

Client process (outbound) parameters:

[AT {destination | %variable}] [WITH] [USERID {%variable | 'string'}] [PASSWORD {%variable | 'string'}] [{ACCOUNT | PROFILE} {%variable | 'string'}] [INITIAL {DATA 'string' | DATA %variable | IMAGE image}...]

Server process (inbound) parameters:

ACCEPT [INITIAL {DATA %variable | IMAGE image}...]

Where:

• processname depends on the program that issues the OPEN PROCESS:
  • For a client (outbound) program: processname is the name of a client process specified in a client DEFINE PROCESS command.
  • For a server (inbound) program: processname is any name chosen by the SOUL programmer.

Note: Names beginning with CCA are specifically disallowed from use in the OPEN PROCESS statement.

• CID is the ID of a conversation for subsequent Horizon SOUL statements. If CID is not specified, processname is used as the ID. However, CID must be specified if the user has two or more active conversations with the same process name. If CID is specified, subsequent conversation statements must also specify the same CID value.
• AT specifies the symbolic destination for a remote partner. The destination name must correspond to a symbolic name specified on the DESTINATION parameter of the DEFINE PROCESS command for processname. Refer to the DEFINE PROCESS command client (outbound) options. If not specified, the first processgroup of the DESTINATION parameter is used.
• AT cannot be specified if there is only one processgroup in the DESTINATION parameter.
• USERID is the user ID to be logged in at the server node on behalf of this OPEN PROCESS. If this parameter is omitted, Model 204 transmits the current user ID. If the local user on the client system is not logged in, Model 204 transmits no user ID. If this parameter is coded, the DEFINE PROCESS command for processname must specify UIDSOURCE=OPEN.
• PASSWORD is the password to be used for login at the server node. If USERID is coded, this parameter is required. If USERID is omitted, this parameter is used if coded and if a current user ID exists for the thread.
• ACCOUNT and PROFILE are synonyms and are mutually exclusive. They can only be coded if the DEFINE PROCESS command for processname specifies the OPEN option. They behave in the same manner as the USERID parameter.
• INITIAL depends on the program that issues the OPEN PROCESS:
  • For a client (outbound) program: INITIAL specifies the Program Initialization Parameters (PIP data) to be passed to the remote partner.
  • For a server (inbound) program: INITIAL specifies the SOUL areas used to accept the Program Initialization Parameters.

  The total length of the PIP data must be less than the DATALEN value specified on the DEFINE PROCESS command for processname.

Conversation state

Valid conversation state: Reset

Status codes

S / SD	New State	Description
0 / 0	Send	Normal completion when issued by client (outbound) program.
	Receive	Normal completion when issued by server (inbound) program.
2 / 2	Receive	SEND ERROR statement issued by partner.
4 / 1	Close	Partner process ended abnormally.
5 / any	no change	Parameter check (coding error). See $STATUS/$STATUSD codes and error messages.
10-99	Close	Resource allocation failures. See $STATUS/$STATUSD codes and error messages.

QUERY PROCESS statement

Function

QUERY PROCESS allows the SOUL programmer to retrieve information from the host LU about one or more characteristics of the conversation.

Syntax

Following the choice of cid, processname, or %variable is a list of parameter/%variable pairs. The parameters correspond to the conversation characteristics about which information can be returned by the host LU.

After a program issues a QUERY PROCESS statement with one or more parameters and accompanying %variables, the LU returns the value of the indicated conversation characteristic, storing it in the %variable following the parameter. A compilation error occurs if the type or length of any %variable is invalid.

The QUERY PROCESS format follows:

Query Process {cid | processname | %variable} options

where options must be one or more of the following:

• STATE %variable
• PROCESSGROUP %variable
• REMOTEID %variable
• SYNCLEVEL %variable
• MODENAME %variable

Where:

• cid or processname or %variable is the conversation ID on the OPEN PROCESS statement for this conversation, if it is open.
• If no CID value is specified on the OPEN PROCESS statement, processname should be used. If a CID value is specified on the OPEN PROCESS, you also must specify that value here on the QUERY PROCESS statement.
• STATE is the current conversation state of the conversation. The value of STATE is a string of maximum length 7. Value options follow:
  • RESET
  • SEND
  • RECV (to indicate Receive state)
  • CONFIRM
  • CONFSND (to indicate Confirm Send state)
  • CONFCLS (to indicate Confirm Close state)
  • CLOSE

  For more information about conversation states, see Conversation states. For more information about the Confirm Send and Confirm Close states, see the discussion of the RESULT parameter of the RECEIVE statement in RECEIVE statement.

• PROCESSGROUP is the name of the processgroup associated with the conversation. The value is a string of length 8.
• REMOTEID is the name of the LU at which the remote partner is located. The value is a string of length 8.
• SYNCLEVEL is the level of synchronization processing used for the conversation, that is, whether confirmation processing is allowed. The value is a string of maximum length 9. Values are:
  • CONFIRM
  • NOCONFIRM

  CONFIRM or NOCONFIRM can be set on the DEFINE PROCESS command, described in Defining a Horizon network.

• MODENAME is the mode table entry for the session which the conversation is using. The value is a string of length 8.

Conversation state

Valid conversation states:

• for STATE option: any state
• for other options: any state except Reset

Status codes and state transitions

S / SD	New State	Description
0 / 0	no change	Normal completion.
5 / any	no change	Parameter check (coding error). See $STATUS/$STATUSD codes and error messages.
10-99	Close	Resource allocation failures. See $STATUS/$STATUSD codes and error messages.

RECEIVE statement

Function

The RECEIVE statement receives any data or indicator sent by the remote partner.

Syntax

The RECEIVE statement format follows:

RECEIVE {IMAGE imagename | %variable} FROM {cid | processname | %variable} RESULT %variable

Where:

• imagename specifies that the receiving area is an image previously defined by an image definition.

  The receiving area can also be a %variable. The data received from the remote partner is assumed to be in string form and is converted to the type of %variable.

• cid or processname or %variable is the conversation ID on the OPEN PROCESS statement for this conversation.
• If no CID value is specified on the OPEN PROCESS statement, processname should be used. If a CID value is specified on the OPEN PROCESS, you also must specify that value here on the RECEIVE statement.
• RESULT %variable is used to determine what the process has received. RESULT should only be examined if $STATUS is 0 or 1, since otherwise, nothing is placed in this %variable.

  The RESULT %variable must be a string variable at least 15 characters in length. It can contain only one of these values following a RECEIVE statement:

  • DATA: All of the data issued by one send operation by the remote partner has been received in the %variable or IMAGE. (It may be necessary to IDENTIFY another IMAGE to reference all of the data.)
  • DATA TRUNCATED: Part of the data issued by one send operation by the remote partner has been received in the %variable or IMAGE. (It may be necessary to IDENTIFY another IMAGE to reference even the data received.) The data is truncated on the right. To correct this problem, increase the setting of DATALEN on the DEFINE PROCESSGROUP command.
  • SEND: No data was received; the SOUL program may issue a SEND statement.
  • CONFIRM: No data was received; the SOUL program may issue a CONFIRMED or SEND ERROR statement; a CONFIRMED statement can return the state to Receive.
  • CONFIRM SEND: No data was received. The SOUL program may now issue a CONFIRMED or SEND ERROR statement; a CONFIRMED statement can change the state to Send.
  • CONFIRM CLOSE: No data was received. The SOUL program may issue a CONFIRMED or SEND ERROR statement; a CONFIRMED statement can change the state to Reset.

  A compilation error results if the type or length of the RESULT %variable is incorrect.

Note: The end of the conversation is indicated by $STATUS=4 and not by a RESULT value.

Conversation state

Valid conversation states: Send or Receive

Status codes and state transitions

S / SD	New State	Description
0 / 0	Unchanged	Normal completion.
1 / 0	Check RESULT	Special completion: no data, check RESULT:
		RESULT %variable	Meaning
		DATA TRUNCATED	Data received was longer than target variable or DATALEN; remain in Receive state.
		DATA INCOMPLETE	Not used (always truncated)
		SEND	Receiver is now in Send state.
		CONFIRM	Respond with CONFIRMED or SEND ERROR; remain in Receive state.
		CONFIRM SEND	Respond with CONFIRMED or SEND ERROR; enter Send state.
		CONFIRM CLOSE	Respond with CONFIRMED or SEND ERROR; enter Close state.
2 / 2	Unchanged	SEND ERROR statement issued by partner.
3 / 3	Unchanged	State check.
4 / 0	Close	Partner process closed conversation normally
4 / 1	Close	Partner process ended abnormally.
5 / any	no change	Parameter check (coding error). See $STATUS/$STATUSD codes and error messages.
10-99	Close	Resource allocation failures. See $STATUS/$STATUSD codes and error messages.

SEND statement

Function

Initiate transmission of data from an application program to its remote partner.

Syntax

SEND [IMAGE imagename |'string'| %variable] TO {cid | processname | %variable} [FLUSH | CONFIRM] REQSEND %variable

Where:

• imagename specifies that the object sent is an image previously defined by an image definition.

  The object sent can also be a quoted string or a %variable. A %variable is converted to string form before being sent to the remote partner.

• cid or processname or %variable is the conversation ID on the OPEN PROCESS statement for this conversation.
• If no CID value is specified on the OPEN PROCESS statement, processname should be used. If a CID value is specified on the OPEN PROCESS statement, you also must specify it on the SEND statement.
• FLUSH is identical to issuing a FLUSH statement following the SEND.
• CONFIRM is identical to issuing a Confirm statement following the SEND.
• REQSEND %variable is used to detect a signal from the partner. While the conversation is in Send state, a signal may be received, indicating that the remote conversation partner wishes to enter Send state.

  The REQSEND %variable indicates a signal from the partner:

  • A value of 1 indicates a SIGNAL was received.
  • A value of 0 indicates no SIGNAL was received.

Conversation state

Valid conversation state: Send

Status codes and state transitions

S / SD	New State	Description
0 / 0	Send	Normal completion.
2 / 2	Receive	SEND ERROR statement issued by partner.
3 / 3	no change	State check.
4 / 1	Close	Partner process ended abnormally.
5 / any	no change	Parameter check (coding error). See $STATUS/$STATUSD codes and error messages.
10-99	Close	Resource allocation failures. See $STATUS/$STATUSD codes and error messages.

SEND ERROR statement

Function

The SEND ERROR statement sends a negative acknowledgment indicating that the local partner detected an application error.

Syntax

Send Error To {cid | processname | %variable}
Reqsend %variable

Where:

• cid or processname or %variable is the conversation ID on the OPEN PROCESS statement for this conversation.
• If no CID value is specified on the OPEN PROCESS statement, processname should be used. If a CID value is specified on the OPEN PROCESS, you also must specify that value here on the SEND ERROR statement.
• REQSEND %variable is used to detect a signal from the partner. While the conversation is in Send state, a SIGNAL (REQUEST_TO_SEND) may be received, indicating that the remote conversation partner wishes to enter Send state.

Reception of a signal from the partner is indicated in the REQSEND %variable:

• A value of 1 indicates a SIGNAL was received.
• A value of 0 indicates no SIGNAL was received.

Conversation state

Valid conversation states: Send, Receive, or Confirm

Status codes and state transitions

S / SD	New State	Description
0 / 0	Send	Normal completion.
2 / 2	Receive	SEND ERROR statement issued by partner.
3 / 3	no change	State check.
4 / 1	Close	Partner process ended abnormally.
5 / any	no change	Parameter check (coding error). See $STATUS/$STATUSD codes and error messages.
10-99	Close	Resource allocation failures. See $STATUS/$STATUSD codes and error messages.

SIGNAL PROCESS statement

Function

The SIGNAL PROCESS statement notifies the remote partner that the local partner is requesting to enter Send state for the conversation.

Syntax

The SIGNAL PROCESS format follows:

SIGNAL PROCESS {cid | processname | %variable}

Where:

• cid or processname or %variable is the conversation ID on the OPEN PROCESS statement for this conversation.
• If no CID value is specified on the OPEN PROCESS statement, processname should be used. If a CID value is specified on the OPEN PROCESS, you also must specify that value here on the SIGNAL PROCESS statement.

Conversation state

Valid conversation states: Receive or Confirm

Status codes and state transitions

S / SD	New State	Description
0 / 0	no change	Normal completion.
3 / 3	no change	State check.
5 / any	no change	Parameter check (coding error). See $STATUS/$STATUSD codes and error messages.
10-99	Close	Resource allocation failures. See $STATUS/$STATUSD codes and error messages.

TEST RECEIPT statement

Function

The TEST RECEIPT statement determines whether or not a partner process has sent anything in reply to an INVITE statement. Using the TEST RECEIPT statement instead of a WAIT FOR RECEIPT statement allows the issuing program to perform other tasks while the partner is preparing its reply to the INVITE.

The TEST RECEIPT statement permits the application to test for the reply from a specific conversation ID or from any of the partner conversations or processes.

After a reply is detected, the RECEIVE statement is used to receive the data or indicator sent.

Syntax

The TEST RECEIPT statement format follows:

Test [For]
{Any Receipt Return %variable
| Receipt {cid | processname | %variable}}

Where:

• TEST ANY RECEIPT means that the receipt of information for any one of the conversations with outstanding INVITEs is sufficient to satisfy the TEST.

  %variable is a SOUL string variable into which is stored the CID of the conversation that replied. Only this form of the TEST statement requires the return of identifying information from the partner.

• TEST RECEIPT means that the receipt of information from the conversation or partner specified by cid or processname or %variable is sufficient to satisfy the TEST.

cid or processname or %variable is the conversation or partner identifier on the OPEN PROCESS statement for this conversation. If no CID value is specified on the OPEN PROCESS statement, use the process name.

Conversation state

Valid conversation states: Not applicable (N/A). Horizon does no state checking for TEST RECEIPT.

Status codes and state transitions

S / SD	New State	Description
0 / 0	N/A	OK (data has arrived from remote partner).
1 / 1	N/A	No outstanding INVITEs remain.
1 / 2	N/A	No data has arrived from remote partner.
5 / 5	N/A	Process not opened (only if cid or process name specified).
5 / 17	N/A	Cid or process name too long.
10-99	N/A	Resource allocation failures. See $STATUS/$STATUSD codes and error messages.

WAIT FOR RECEIPT statement

Function

The WAIT FOR RECEIPT statement causes the issuing SOUL program to stop running until a reply is received from the specified remote partner(s). After a reply is detected, the RECEIVE statement is used to receive the data or indicator sent.

The WAIT FOR RECEIPT statement permits the application to wait for a specific conversation ID to respond before it awakens. Or, the application can awaken when any of the conversations or processes respond.

Syntax

The WAIT FOR RECEIPT statement format follows:

WAIT [duration] [FOR] ANY RECEIPT RETURN %variable WAIT [duration] [FOR] RECEIPT {cid | processname | %variable}

Where:

• WAIT FOR ANY RECEIPT causes the program to reawaken upon the receipt of information from any one of the conversations with outstanding INVITEs.

  %variable is a SOUL string variable into which is stored the CID of the conversation that replied. Only this form of the WAIT FOR RECEIPT statement requires the return of identifying information from the partner.

• WAIT FOR RECEIPT causes the program to reawaken upon the receipt of information from the conversation or partner specified by cid or processname or %variable.

  cid or processname or %variable is the conversation or partner identifier on the OPEN PROCESS statement for this conversation. If no CID value is specified on the OPEN PROCESS statement, use the process name.

• duration = integer | %variable SEC[S]

  duration is an optional parameter that limits the length of time (in seconds) that the WAIT statement waits for the specified receipt to occur. If the specified receipt does not occur before or during the execution of the timed WAIT, the WAIT statement completes with $STATUS=1 and $STATUSD=3.

Note: duration has nothing to do with the TIMEOUT parameter of the DEFINE PROCESS command for the conversation. If TIMEOUT is exceeded during execution of a conversation statement, the conversation is immediately terminated abnormally. The timed WAIT allows the programmer a variety of possible consequent actions if duration is exceeded, including abnormal termination of the conversation.

Conversation state

Valid conversation states: Not applicable (N/A). Horizon does no state checking for WAIT FOR RECEIPT.

Status codes and state transitions

S / SD	New State	Description
0 / 0	N/A	OK - information has arrived.
1 / 1	N/A	No outstanding INVITEs to wait for.
1 / 3	N/A	WAIT duration reached before events complete.
5 / any	N/A	Parameter check (coding error). See $STATUS/$STATUSD codes and error messages.
10-99	N/A	Resource allocation failures. See $STATUS/$STATUSD codes and error messages.