View source for Horizon SOUL interface

<div class="toclimit-2">__TOC__</div>

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

===Dependence on conversation state===
<p>
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.</p>

===Error checking===
<p>
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.</p>

==CLOSE PROCESS statement==

====Function====
<p>
The CLOSE PROCESS statement deallocates the specified conversation from the process.</p>

====Syntax====
<p>
The CLOSE PROCESS format follows:</p>
<p class="syntax">CLOSE PROCESS {<span class="term">cid</span> | <span class="term">processname</span> | <span class="term">%variable</span>}
      [SYNCLEVEL | FLUSH | CONFIRM | ERROR | <span class="term">%variable</span>] </p>
<p>
Where:</p>
<ul>
<li>
<var class="term">cid</var> or <var class="term">processname</var> or <var class="term">%variable</var> is the conversation ID on the OPEN PROCESS statement for this conversation. </li>
<li>
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. </li>
<li>
SYNCLEVEL specifies that the actions taken depend on whether CONFIRM or NOCONFIRM is specified on the DEFINE PROCESS command:
<ul>
<li>
If CONFIRM is specified, the actions indicated by CLOSE PROCESS CONFIRM are taken.</li>
<li>
If NOCONFIRM is specified, the actions indicated by CLOSE PROCESS FLUSH are taken. </li>
</ul>
<p>SYNCLEVEL is the default. </p>
</li>
<li>
FLUSH specifies that any data buffered by preceding SEND statements is transmitted to the remote partner before the conversation is deallocated.    </li>
<li>
CONFIRM specifies that a CONFIRM request is sent to the remote partner before the conversation is deallocated.   CONFIRM also implies a buffer flush. </li>
<li>
ERROR specifies that the conversation is terminated abnormally.   </li>
<li>
<var class="term">%variable</var> contains "SYNCLEVEL," "FLUSH," "CONFIRM," or "ERROR." </li>
</ul>

====Conversation state====
<b>Valid conversation states</b>
<table>
<tr class="head">
<th>State</th>
<th>Statement</th>
</tr>
<tr>
<td>Send state</td>
<td>
For CLOSE PROCESS with SYNCLEVEL, CONFIRM, or FLUSH</td>
</tr>
<tr>
<td>Send, Receive, or Confirm state</td>
<td>For CLOSE PROCESS with ERROR</td>
</tr>
</table>

<b>Status codes</b>
<table>
<tr class="head">
<th>S / SD </th>
<th>New state</th>
<th>Description</th>
</tr>
<tr>
<td>0 / 0</td>
<td>Reset</td>
<td>Normal completion.</td>
</tr>
<tr>
<td>2 / 2 </td>
<td>Receive</td>
<td>SEND ERROR statement issued by partner.</td>
</tr>
<tr>
<td>4 / 0</td>
<td>Reset</td>
<td>Partner process closed conversation normally.</td>
</tr>
<tr>
<td>4 / 1</td>
<td>Reset</td>
<td>Partner process ended abnormally.</td>
</tr>
<tr>
<td nowrap>5 / any</td>
<td nowrap>no change</td>
<td>Parameter check (coding error). See [[#$STATUS/$STATUSD codes and accompanying error messages|$STATUS/$STATUSD codes and error messages]].</td>
</tr>
<tr>
<td>10-99</td>
<td>Close</td>
<td>Resource allocation failures. See [[#$STATUS/$STATUSD codes and accompanying error messages|$STATUS/$STATUSD codes and error messages]].</td>
</tr>
</table>

==<b id="Confirm statement"></b>CONFIRM statement==

====Function====
<p>
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.</p>

====Syntax====
<p>
The CONFIRM statement format follows:</p>
{{Template:Confirm statement syntax}}
<p>
Where:</p>
<ul>
<li>
<var class="term">cid</var> or <var class="term">processname</var> or <var class="term">%variable</var> is the conversation ID on the OPEN PROCESS statement for this conversation.</li>
<li>
If no CID value is specified on the OPEN PROCESS statement, <var class="term">processname</var> should be used.   If a CID value is specified on the OPEN PROCESS, you also must specify that value here on the CONFIRM statement.</li>
<li>
REQSEND <var class="term">%variable</var> 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.

<p>Reception of a SIGNAL from the partner is indicated in the REQSEND %variable:</p>
<ul>
<li>
A value of 1 indicates a SIGNAL was received.   </li>
<li>
A value of 0 indicates no SIGNAL was received. </li>
</ul>
</li>
</ul>

====Conversation state====
<p>
Valid conversation state: <code> Send</code></p>

<table>
<tr class="head">
<th>S / SD</th>
<th>New State</th>
<th>Description</th>
</tr>
<tr>
<td>0 / 0 </td>
<td>Send </td>
<td>Normal completion.</td>
</tr>
<tr>
<td>2 / 2</td>
<td>Receive</td>
<td>SEND ERROR statement issued by partner.</td>
</tr>
<tr>
<td>3 / 3 </td>
<td>no change</td>
<td>State check.</td>
</tr>
<tr>
<td>4 / 1</td>
<td>Close</td>
<td>Partner process ended abnormally.</td>
</tr>
<tr>
<td>5 / any</td>
<td>no change</td>
<td>Parameter check (coding error). See [[#$STATUS/$STATUSD codes and accompanying error messages|$STATUS/$STATUSD codes and error messages]].</td>
</tr>
<tr>
<td>10-99</td>
<td>Close</td>
<td>Resource allocation failures. See [[#$STATUS/$STATUSD codes and accompanying error messages|$STATUS/$STATUSD codes and error messages]].</td>
</tr>
</table>

==<b id="Confirmed statement"></b>CONFIRMED statement==

====Function====
<p>
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.</p>

====Syntax====
<p>
The syntax of the CONFIRMED statement follows:</p>
{{Template:Confirmed statement syntax}}
<p>
Where:</p>
<ul>
<li>
<var class="term">cid</var> or <var class="term">processname</var> or <var class="term">%variable</var> is the conversation ID on the OPEN PROCESS statement for this conversation.</li>
<li>
If no CID value is specified on the OPEN PROCESS statement, <var class="term">processname</var> should be used. If a CID value is specified on the OPEN PROCESS, you also must specify that value here on the CONFIRMED statement.</li>
</ul>

====Conversation state====
<p>
Valid conversation state: <code> Confirm</code> </p>

<table>
<tr>
<th>S  / SD </th>
<th>New State</th>
<th>Description</th>
</tr>
<tr>
<td rowspan="3" colspan="1">
0 / 0 </td>
<td>Receive</td>
<td>Normal completion when issued in Confirm state.</td>
</tr>
<tr>
<td>Send</td>
<td>Normal completion when issued in Confirm Send state.</td>
</tr>
<tr>
<td>Close</td>
<td>Normal completion when issued in Confirm Close state.</td>
</tr>
<tr>
<td>3 / 3 </td>
<td>no change</td>
<td>State check.</td>
</tr>
<tr>
<td nowrap>5 / any</td>
<td>no change</td>
<td>Parameter check (coding error). See [[#$STATUS/$STATUSD codes and accompanying error messages|$STATUS/$STATUSD codes and error messages]].</td>
</tr>
<tr>
<td>10-99</td>
<td>Close </td>
<td>Resource allocation failures. See [[#$STATUS/$STATUSD codes and accompanying error messages|$STATUS/$STATUSD codes and error messages]].</td>
</tr>
</table>

==FLUSH PROCESS statement==

====Function====
<p>
The FLUSH PROCESS statement causes the conversation buffer to be sent to the remote partner.</p>

====Syntax====
<p>
The FLUSH PROCESS format follows:</p>
<p class="syntax">FLUSH PROCESS {<span class="term">cid</span> | <span class="term">processname</span> | <span class="term">%variable</span>} </p>
<p>
Where:</p>
<ul>
<li>
<var class="term">cid</var> or <var class="term">processname</var> or <var class="term">%variable</var> is the conversation ID on the OPEN PROCESS statement for this conversation. </li>
<li>
If no CID value is specified on the OPEN PROCESS statement, <var class="term">processname</var> 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.</li>
</ul>

====Conversation state====
<p>
Valid conversation state: <code> Send</code></p>
<b>Status codes</b>
<table>
<tr>
<th>S  / SD</th>
<th> New State</th>
<th>Description</th>
</tr>
<tr>
<td>0 / 0 </td>
<td>Send</td>
<td>Normal completion.</td>
</tr>
<tr>
<td>2 / 2</td>
<td>Receive</td>
<td>SEND ERROR statement issued by partner.</td>
</tr>
<tr>
<td>3 / 3</td>
<td>no change</td>
<td>State check.</td>
</tr>
<tr>
<td>4 / 1</td>
<td>Close</td>
<td>Partner process ended abnormally.</td>
</tr>
<tr>
<td>5 / any</td>
<td>no change</td>
<td>Parameter check (coding error). See [[#$STATUS/$STATUSD codes and accompanying error messages|$STATUS/$STATUSD codes and error messages]].
</td>
</tr>
<tr>
<td>10-99</td>
<td>Close</td>
<td>Resource allocation failures. See [[#$STATUS/$STATUSD codes and accompanying error messages|$STATUS/$STATUSD codes and error messages]].</td>
</tr>
</table>

==<b id="Invite statement"></b>INVITE statement==

====Function====
<p>
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.</p>
<p>
The program that issues INVITE has the option of requesting that its partner send confirmation before entering Send state.</p>

====Usage====
<p>
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.</p>
<p>
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. </p>

====Syntax====
<p>
The INVITE statement format follows:</p>
{{Template:Invite statement syntax}}
<p>
Where:</p>
<ul>
<li>
<span class="term">cid</span> or <span class="term">processname</span> or <span class="term">%variable</span> 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.</li>
<li>
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:
<ul>
<li>
If CONFIRM is specified, the actions described below for INVITE CONFIRM are taken.</li>
<li>
If NOCONFIRM is specified, the actions described below for INVITE FLUSH are taken. </li>
</ul>
</li>
<li>
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.</li>
<li>
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.
<p>
INVITE CONFIRM is valid only when the conversation's synchronization level is CONFIRM.</p>
</li>
</ul>

====Conversation state====
<p>
Valid conversation state: <code> Send</code>
</p>
<table>
<caption>Status codes and state transitions</caption>
<tr class="head">
<th>S / SD</th>
<th>New State</th>
<th>Description</th>
</tr>
<tr>
<td>0 / 0 </td>
<td>Receive </td>
<td>OK</td>
</tr>
<tr>
<td>2 / 2 </td>
<td>Receive</td>
<td>Partner responded to INVITE CONFIRM with SEND ERROR</td>
</tr>
<tr>
<td>
3 / 3 </td>
<td>
no change</td>
<td>
State check (issued in wrong conversation state)</td>
</tr>
<tr>
<td>4 / 1</td>
<td>Close </td>
<td>Partner process ended abnormally</td>
</tr>
<tr>
<td nowrap>5 / any</td>
<td>no change </td>
<td>Parameter check (coding error). See [[#$STATUS/$STATUSD codes and accompanying error messages|$STATUS/$STATUSD codes and error messages]]. </td>
</tr>
<tr>
<td>10-99</td>
<td>Close</td>
<td>Resource allocation failures. See [[#$STATUS/$STATUSD codes and accompanying error messages|$STATUS/$STATUSD codes and error messages]].</td>
</tr>
</table>

==OPEN PROCESS statement==

====Function====
<p>
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.</p>
<p>
There are two distinct uses of the OPEN PROCESS statement:</p>
<ul>
<li>
For a client process, it allocates an outbound conversation.
<p>
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.</p>
</li>
<li>
For a server process, it identifies an inbound conversation.
<p>
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. </p>
</li>
</ul>
<p>
In addition, the OPEN PROCESS statement establishes the conversation ID (CID) for both types of conversations.</p>

====Usage====
<p>
A conversation begins when an OPEN PROCESS statement is issued in a SOUL request. A conversation ends when one of the following happens:</p>
<ul>
<li>The request issues the CLOSE PROCESS statement.</li>
<li>The end user's thread returns to command level.</li>
<li>The request issues the END statement (TPROCESS only).</li>
<li>The request is cancelled.</li>
<li>The thread is restarted.</li>
<li>The network connection is severed by the Model 204 system administrator who issues the CLOSE LINK command.</li>
<li>The communication path (session) is broken by some external event beyond the control of Model 204. </li>
</ul>
====Syntax====
<p>
The OPEN PROCESS format follows:</p>
<p class="syntax">OPEN PROCESS {<span class="term">processname</span>] <span class="term">%variable</span>}
[CID {<span class="term">name</span> | <span class="term">%variable</span>}]</p>

<p>Client process (outbound) parameters:</p> 

<p class="syntax">[AT {<span class="term">destination</span> | <span class="term">%variable</span>}]
[WITH]
[USERID {<span class="term">%variable</span> | '<span class="term">string</span>'}]
[PASSWORD {<span class="term">%variable</span> | '<span class="term">string</span>'}]
[{ACCOUNT | PROFILE} {<span class="term">%variable</span> | '<span class="term">string</span>'}]
[INITIAL {DATA '<span class="term">string</span>' | DATA <span class="term">%variable</span>
          | IMAGE <span class="term">image</span>}...]</p>

<p>Server process (inbound) parameters:</p> 

<p class="syntax">ACCEPT
[INITIAL {DATA <span class="term">%variable</span> | IMAGE <span class="term">image</span>}...] </p>
<p>
Where:</p>
<ul>
<li>
<var class="term">processname</var> depends on the program that issues the OPEN PROCESS:
<ul>
<li>
For a client (outbound) program: <var class="term">processname</var> is the name of a client process specified in a client DEFINE PROCESS command.</li>
<li>
For a server (inbound) program: <var class="term">processname</var> is any name chosen by the SOUL programmer. </li>
</ul></li>
<p class="note"><b>Note:</b> Names beginning with CCA are specifically disallowed from use in the OPEN PROCESS statement.</p>
<li>
CID is the ID of a conversation for subsequent Horizon SOUL statements. If CID is not specified, <var class="term">processname</var> 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.</li>
<li>
AT specifies the symbolic destination for a remote partner. The <var class="term">destination</var> name must correspond to a symbolic name specified on the DESTINATION parameter of the DEFINE PROCESS command for <var class="term">processname</var>. Refer to the DEFINE PROCESS command client (outbound) options. If not specified, the first processgroup of the DESTINATION parameter is used.</li>
<li>
AT <i>cannot</i> be specified if there is only one processgroup in the DESTINATION parameter.</li>
<li>
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 <var class="term">processname</var> must specify UIDSOURCE=OPEN.</li>
<li>
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.</li>
<li>
ACCOUNT and PROFILE are synonyms and are mutually exclusive.   They can only be coded if the DEFINE PROCESS command for <var class="term">processname</var> specifies the OPEN option. They behave in the same manner as the USERID parameter.</li>
<li>
INITIAL depends on the program that issues the OPEN PROCESS:
<ul>
<li>For a client (outbound) program: INITIAL specifies the Program Initialization Parameters (PIP data) to be passed to the remote partner.</li>
<li>
For a server (inbound) program: INITIAL specifies the SOUL areas used to accept the Program Initialization Parameters.</li>
</ul>
<p>
The total length of the PIP data must be less than the DATALEN value specified on the DEFINE PROCESS command for <var class="term">processname</var>.</p>
</li>
</ul>

====Conversation state====
<p>
Valid conversation state: <code>Reset</code>
</p>
<b>Status codes </b>
<table>
<tr class="head">
<th>S / SD</th>
<th>New State</th>
<th>Description</th>
</tr>
<tr>
<td rowspan="2" colspan="1">
0 / 0 </td>
<td>Send</td>
<td>Normal completion when issued by client (outbound) program.</td>
</tr>
<tr>
<td>Receive</td>
<td>Normal completion when issued by server (inbound) program.</td>
</tr>
<tr>
<td>2 / 2</td>
<td>Receive</td>
<td>SEND ERROR statement issued by partner.</td>
</tr>
<tr>
<td>4 / 1</td>
<td>Close</td>
<td>Partner process ended abnormally.</td>
</tr>
<tr>
<td nowrap>5 / any</td>
<td>no change</td>
<td>Parameter check (coding error). See [[#$STATUS/$STATUSD codes and accompanying error messages|$STATUS/$STATUSD codes and error messages]].</td>
</tr>
<tr>
<td>10-99</td>
<td>Close</td>
<td>Resource allocation failures. See [[#$STATUS/$STATUSD codes and accompanying error messages|$STATUS/$STATUSD codes and error messages]].</td>
</tr>
</table>

==<b id="Query Process statement"></b>QUERY PROCESS statement==

====Function====
<p>
QUERY PROCESS allows the SOUL programmer to retrieve information from the host LU about one or more characteristics of the conversation.</p>

====Syntax====
<p>
Following the choice of <var class="term">cid</var>, <var class="term">processname</var>, or <var class="term">%variable</var>
 is a list of parameter/%variable pairs. The parameters correspond to the conversation characteristics about which information can be returned by the host LU.</p>
<p>
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.</p>
<p>
The QUERY PROCESS format follows:</p>
{{Template:Query Process statement syntax}}
<p>
Where:</p>
<ul>
<li>
<var class="term">cid</var> or <var class="term">processname</var> or <var class="term">%variable</var> is the conversation ID on the OPEN PROCESS statement for this conversation, if it is open. </li>
<li>
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.</li>
<li>
STATE is the current conversation state of the conversation. The value of STATE is a string of maximum length 7. Value options follow:
<ul>
<li>RESET</li>
<li>SEND</li>
<li>RECV (to indicate Receive state)</li>
<li>CONFIRM</li>
<li>CONFSND (to indicate Confirm Send state)</li>
<li>CONFCLS (to indicate Confirm Close state)</li>
<li>CLOSE</li>
</ul>
<p>For more information about conversation states, see [[Horizon conversation interface#Conversation states|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|RECEIVE statement]].</p>
</li>
<li>
PROCESSGROUP is the name of the processgroup associated with the conversation. The value is a string of length 8.   </li>
<li>
REMOTEID is the name of the LU at which the remote partner is located. The value is a string of length 8.   </li>
<li>
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:
<ul>
<li>
CONFIRM</li>
<li>
NOCONFIRM </li>
</ul>
<p>
CONFIRM or NOCONFIRM can be set on the DEFINE PROCESS command, described in [[Horizon network management#Defining a Horizon network|Defining a Horizon network]].</p>
</li>
<li>
MODENAME is the mode table entry for the session which the conversation is using. The value is a string of length 8.     </li>
</ul>

====Conversation state====
<p>
Valid conversation states:</p>
<ul>
<li>
for STATE option: any state</li>
<li>
for other options: any state except <code>Reset</code></li>
</ul>

<table>
<caption>Status codes and state transitions</caption>
<tr class="head">
<th>
S  / SD</th>
<th>
New State</th>
<th>
Description</th>
</tr>
<tr>
<td>
0 / 0</td>
<td>
no change</td>
<td>
Normal completion.</td>
</tr>
<tr>
<td>
5 / any</td>
<td>
no change</td>
<td>
Parameter check (coding error). See [[#$STATUS/$STATUSD codes and accompanying error messages|$STATUS/$STATUSD codes and error messages]].</td>
</tr>
<tr>
<td>
10-99</td>
<td>
Close</td>
<td>
Resource allocation failures. See [[#$STATUS/$STATUSD codes and accompanying error messages|$STATUS/$STATUSD codes and error messages]].</td>
</tr>
</table>

==RECEIVE statement==

====Function====
<p>
The RECEIVE statement receives any data or indicator sent by the remote partner.</p>

====Syntax====
<p>
The RECEIVE statement format follows:</p>
<p class="syntax">RECEIVE {IMAGE <span class="term">imagename</span> | <span class="term">%variable</span>} FROM
   {<span class="term">cid</span> | <span class="term">processname</span> | <span class="term">%variable</span>} RESULT <span class="term">%variable</span> </p>
<p>
Where:</p>
<ul>
<li>
<var class="term">imagename</var> specifies that the receiving area is an image previously defined by an image definition.

<p>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.</p>
</li>
<li>
<var class="term">cid</var> or <var class="term">processname</var> or <var class="term">%variable</var> is the conversation ID on the OPEN PROCESS statement for this conversation. </li>
<li>
If no CID value is specified on the OPEN PROCESS statement, <var class="term">processname</var> should be used. If a CID value is specified on the OPEN PROCESS, you also must specify that value here on the RECEIVE statement.</li>
<li>
RESULT <var class="term">%variable</var> 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.
<p>
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:</p>
<ul>
<li>
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.) </li>
<li>
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. </li>
<li>
SEND: No data was received; the SOUL program may issue a SEND statement.   </li>
<li>
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.   </li>
<li>
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.   </li>
<li>
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.   </li>
</ul>
<p>
A compilation error results if the type or length of the RESULT %variable is incorrect. </p>
</li>
</ul>
<p class="note"><b>Note:</b> The end of the conversation is indicated by $STATUS=4 and not by a RESULT value.</p>

====Conversation state====
<p>
Valid conversation states: <code>Send</code> or <code>Receive</code>
</p>

<table>
<caption>Status codes and state transitions</caption>
<tr class="head">
<th>
S / SD
</th>
<th>
New State
</th>
<th rowspan="1" colspan="2">
Description</th>
</tr>
<tr>
<td>0 / 0</td>
<td>
Unchanged</td>
<td rowspan="1" colspan="2">
Normal completion.
</td>
</tr>
<tr>
<td>
1 / 0</td>
<td>
Check RESULT</td>
<td rowspan="1" colspan="2">
<p class="zcellbody">
Special completion: no data, check RESULT:</p>
</td>
</tr>
<tr>
<td rowspan="1" colspan="2">&nbsp;
</td>
<td nowrap><b>RESULT %variable</b></td>
<td><b>Meaning</b></td>
</tr>
<tr><td rowspan="1" colspan="2">&nbsp;
</td>
<td>DATA TRUNCATED</td>
<td>Data received was longer than target variable or DATALEN; remain in Receive state.</td>
</tr>
<tr><td rowspan="1" colspan="2">&nbsp;
</td>
<td>DATA INCOMPLETE</td>
<td>Not used (always truncated)</td>
</tr>
<tr><td rowspan="1" colspan="2">&nbsp;
</td>
<td>SEND</td>
<td>Receiver is now in Send state.</td>
</tr>
<tr><td rowspan="1" colspan="2">&nbsp;
</td>
<td>CONFIRM</td>
<td>
Respond with CONFIRMED or SEND ERROR; remain in Receive state.</td>
</tr>
<tr><td rowspan="1" colspan="2">&nbsp;
</td>
<td>
CONFIRM SEND</td>
<td>Respond with CONFIRMED or SEND ERROR; enter Send state.</td>
</tr>
<tr><td rowspan="1" colspan="2">&nbsp;
</td>
<td>CONFIRM CLOSE</td>
<td>Respond with CONFIRMED or SEND ERROR; enter Close state.</td>
</tr>
<tr>
<td>2 / 2</td>
<td>Unchanged</td>
<td rowspan="1" colspan="2">
SEND ERROR statement issued by partner.</td>
</tr>
<tr>
<td>3 / 3</td>
<td>Unchanged</td>
<td rowspan="1" colspan="2">
State check.</td>
</tr>
<tr>
<td>4 / 0</td>
<td>Close</td>
<td rowspan="1" colspan="2">
Partner process closed conversation normally</td>
</tr>
<tr>
<td>4 / 1</td>
<td>Close</td>
<td rowspan="1" colspan="2">
Partner process ended abnormally.</td>
</tr>
<tr>
<td nowrap>5 / any</td>
<td>no change
</td>
<td rowspan="1" colspan="2">
Parameter check (coding error). See [[#$STATUS/$STATUSD codes and accompanying error messages|$STATUS/$STATUSD codes and error messages]].</td>
</tr>
<tr>
<td>10-99</td>
<td>Close</td>
<td rowspan="1" colspan="2">
Resource allocation failures. See [[#$STATUS/$STATUSD codes and accompanying error messages|$STATUS/$STATUSD codes and error messages]].</td>
</tr>
</table>

==SEND statement==

====Function====
<p>
Initiate transmission of data from an application program to its remote partner.</p>
====Syntax====
<p class="syntax">SEND [IMAGE <span class="term">imagename</span> |'<span class="term">string</span>'| <span class="term">%variable</span>]
 TO {<span class="term">cid</span> | <span class="term">processname</span> | <span class="term">%variable</span>} [FLUSH | CONFIRM]
 REQSEND <span class="term">%variable</span> </p>
<p>
Where:</p>
<ul>
<li><var class="term">imagename</var> specifies that the object sent is an image previously defined by an image definition.
<p>
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.</p>
</li>
<li>
<var class="term">cid</var> or <var class="term">processname</var> or <var class="term">%variable</var> is the conversation ID on the OPEN PROCESS statement for this conversation. </li>
<li>
If no CID value is specified on the OPEN PROCESS statement, <var class="term">processname</var> should be used. If a CID value is specified on the OPEN PROCESS statement, you also must specify it on the SEND statement.</li>
<li>
FLUSH is identical to issuing a FLUSH statement following the SEND.</li>
<li>
CONFIRM is identical to issuing a Confirm statement following the SEND.</li>
<li>
REQSEND <var class="term">%variable</var> 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.

<p>The REQSEND %variable indicates a signal from the partner:</p>
<ul>
<li>A value of 1 indicates a SIGNAL was received.</li>
<li>A value of 0 indicates no SIGNAL was received. </li>
</ul>
</li>
</ul>

====Conversation state====
<p>Valid conversation state: <code>Send</code></p>

<table>
<caption>Status codes and state transitions</caption>
<tr class="head">
<th>S  / SD</th>
<th>New State</th>
<th>Description</th>
</tr>
<tr>
<td>0 / 0</td>
<td>Send</td>
<td>Normal completion.</td>
</tr>
<tr>
<td>2 / 2</td>
<td>Receive</td>
<td>SEND ERROR statement issued by partner.</td>
</tr>
<tr>
<td>3 / 3</td>
<td>no change</td>
<td>State check.</td>
</tr>
<tr>
<td>4 / 1</td>
<td>Close</td>
<td>Partner process ended abnormally.</td>
</tr>
<tr>
<td nowrap>5 / any</td>
<td>no change</td>
<td>Parameter check (coding error). See [[#$STATUS/$STATUSD codes and accompanying error messages|$STATUS/$STATUSD codes and error messages]].</td>
</tr>
<tr>
<td>10-99</td>
<td>Close</td>
<td>Resource allocation failures. See [[#$STATUS/$STATUSD codes and accompanying error messages|$STATUS/$STATUSD codes and error messages]].</td>
</tr>
</table>

==<b id="Send Error statement"></b>SEND ERROR statement==

====Function====
<p>
The SEND ERROR statement sends a negative acknowledgment indicating that the local partner detected an application error.</p>

====Syntax====

{{Template:Send Error statement syntax}}

Where:
<ul>
<li>
<var class="term">cid</var> or <var class="term">processname</var> or <var class="term">%variable</var> is the conversation ID on the OPEN PROCESS statement for this conversation. </li>
<li>
If no CID value is specified on the OPEN PROCESS statement, <var class="term">processname</var> 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.</li>
<li>
REQSEND <var class="term">%variable</var> 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.</li>
<p>Reception of a signal from the partner is indicated in the REQSEND %variable:</p>
<ul>
<li>A value of 1 indicates a SIGNAL was received.</li>
<li>A value of 0 indicates no SIGNAL was received. </li>
</ul>
</li>
</ul>

====Conversation state====
<p>
Valid conversation states: <code>Send</code>, <code>Receive</code>, or <code>Confirm</code></p>

<table>
<caption>Status codes and state transitions</caption>
<tr class="head">
<th nowrap>S / SD</th>
<th nowrap>New State</th>
<th>Description</th>
</tr>
<tr>
<td>0  / 0</td>
<td>Send</td>
<td>Normal completion.</td>
</tr>
<tr>
<td>2 / 2</td>
<td>Receive</td>
<td>SEND ERROR statement issued by partner.</td>
</tr>
<tr>
<td>3 / 3</td>
<td>no change</td>
<td>State check.</td>
</tr>
<tr>
<td>4 / 1</td>
<td>Close</td>
<td>Partner process ended abnormally.</td>
</tr>
<tr>
<td nowrap>5 / any</td>
<td>no change</td>
<td>Parameter check (coding error). See [[#$STATUS/$STATUSD codes and accompanying error messages|$STATUS/$STATUSD codes and error messages]].</td>
</tr>
<tr>
<td>10-99</td>
<td>Close</td>
<td>Resource allocation failures. See [[#$STATUS/$STATUSD codes and accompanying error messages|$STATUS/$STATUSD codes and error messages]].</td>
</tr>
</table>

==SIGNAL PROCESS statement==

====Function====
<p>
The SIGNAL PROCESS statement notifies the remote partner that the local partner is requesting to enter Send state for the conversation.</p>

====Syntax====
<p>
The SIGNAL PROCESS format follows:</p>
<p class="syntax">SIGNAL PROCESS {<span class="term">cid</span> | <span class="term">processname</span> | <span class="term">%variable</span>} </p>
<p>
Where:</p>
<ul>
<li>
<var class="term">cid</var> or <var class="term">processname</var> or <var class="term">%variable</var> is the conversation ID on the OPEN PROCESS statement for this conversation.</li>
<li>
If no CID value is specified on the OPEN PROCESS statement, <var class="term">processname</var> 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.</li>
</ul>

====Conversation state====
<p>
Valid conversation states: <code>Receive</code> or <code>Confirm</code>
</p>

<table>
<caption>Status codes and state transitions</caption>
<tr class="head">
<th>S / SD</th>
<th>New State</th>
<th>Description</th>
</tr>
<tr>
<td>0 / 0 </td>
<td>no change</td>
<td>Normal completion.</td>
</tr>
<tr>
<td>3 / 3 </td>
<td>no change</td>
<td>State check.</td>
</tr>
<tr>
<td nowrap>5 / any</td>
<td>no change</td>
<td>Parameter check (coding error). See [[#$STATUS/$STATUSD codes and accompanying error messages|$STATUS/$STATUSD codes and error messages]].</td>
</tr>
<tr>
<td>10-99</td>
<td>Close</td>
<td>Resource allocation failures. See [[#$STATUS/$STATUSD codes and accompanying error messages|$STATUS/$STATUSD codes and error messages]].</td>
</tr>
</table>

==<b id="Test Receipt statement"></b>TEST RECEIPT statement==

====Function====
<p>
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. </p>
<p>
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. </p>
<p>
After a reply is detected, the RECEIVE statement is used to receive the data or indicator sent.</p>

====Syntax====
<p>
The TEST RECEIPT statement format follows:</p>
{{Template:Test Receipt statement syntax}}
<p>
Where:</p>
<ul>
<li>
TEST ANY RECEIPT means that the receipt of information for <i>any one of</i> the conversations with outstanding INVITEs is sufficient to satisfy the TEST.
<p>
<var class="term">%variable</var> 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.</p>
</li>
<li>
TEST RECEIPT means that the receipt of information from the conversation or partner specified by <var class="term">cid</var> or <var class="term">processname</var> or <var class="term">%variable</var> is sufficient to satisfy the TEST.</li>

<p>
<var class="term">cid</var> or <var class="term">processname</var> or <var class="term">%variable</var> 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.</p>
</li>
</ul>

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

<table>
<caption>Status codes and state transitions</caption>
<tr class="head">
<th>S / SD
</th><th>New State
</th><th>Description
</th>
</tr>
<tr>
<td>0 / 0</td>
<td>N/A</td>
<td>OK (data has arrived from remote partner).</td>
</tr>
<tr>
<td>1 / 1</td>
<td>N/A</td>
<td>No outstanding INVITEs remain.</td>
</tr>
<tr>
<td>1 / 2 </td>
<td>N/A</td>
<td>No data has arrived from remote partner.</td>
</tr>
<tr>
<td>5 / 5</td>
<td>N/A</td>
<td>Process not opened (only if cid or process name specified).</td>
</tr>
<tr>
<td>5 / 17</td>
<td>N/A</td>
<td>Cid or process name too long.</td>
</tr>
<tr>
<td>10-99</td>
<td>N/A</td>
<td>Resource allocation failures. See [[#$STATUS/$STATUSD codes and accompanying error messages|$STATUS/$STATUSD codes and error messages]].</tr>
</table>

==WAIT FOR RECEIPT statement==

====Function====
<p>
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.</p>
<p>
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.</p>

====Syntax====
<p>
The WAIT FOR RECEIPT statement format follows:</p>
<p class="syntax">WAIT [<span class="term">duration</span>] [FOR] ANY RECEIPT RETURN <span class="term">%variable</span>

WAIT [<span class="term">duration</span>] [FOR] RECEIPT
 {<span class="term">cid</span> | <span class="term">processname</span> | <span class="term">%variable</span>} </p>
<p>
Where:</p>
<ul>
<li>
WAIT FOR ANY RECEIPT causes the program to reawaken upon the receipt of information from <i>any one of</i> the conversations with outstanding INVITEs.
<p>
<var class="term">%variable</var> 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.</p>
</li>
<li>
WAIT FOR RECEIPT causes the program to reawaken upon the receipt of information from the conversation or partner specified by <var class="term">cid</var> or <var class="term">processname</var> or <var class="term">%variable</var>.
<p>
<var class="term">cid</var> or <var class="term">processname</var> or <var class="term">%variable</var> 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.</p>
</li>
<li>
<var class="term">duration</var> = <var class="term">integer</var> | <var class="term">%variable</var> SEC[S]

<p>
<var class="term">duration</var> 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. </p>
</li>
</ul>

<p class="note"><b>Note:</b> <var class="term">duration</var> 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 <var class="term">duration</var> is exceeded, including abnormal termination of the conversation. </p>

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

<table>
<caption>Status codes and state transitions</caption>
<tr class="head">
<th>S / SD</th>
<th>New State</th>
<th>Description</th>
</tr>
<tr>
<td>0 / 0 </td>
<td>N/A </td>
<td>OK - information has arrived.</td>
</tr>
<tr>
<td>1 / 1</td>
<td>N/A</td>
<td>No outstanding INVITEs to wait for.</td>
</tr>
<tr>
<td>1 / 3</td>
<td>N/A</td>
<td>WAIT duration reached before events complete.</td>
</tr>
<tr>
<td>5 / any</td>
<td>N/A</td>
<td>Parameter check (coding error). See [[#$STATUS/$STATUSD codes and accompanying error messages|$STATUS/$STATUSD codes and error messages]].</td>
</tr>
<tr>
<td>10-99</td>
<td>N/A</td>
<td>Resource allocation failures. See [[#$STATUS/$STATUSD codes and accompanying error messages|$STATUS/$STATUSD codes and error messages]].</td>
</tr>
</table>


[[Category: Horizon]]