<h3>4 <span class="Heading">Message exchange by <strong class="pkg">SCSCP</strong></span></h3>
<p>To ensure the message exchange as required by <strong class="pkg">SCSCP</strong> specification, the <strong class="pkg">SCSCP</strong> package extends the global record <code class="code">OMsymRecord</code> from the <strong class="pkg">OpenMath</strong> package with new entries to support <strong class="pkg">scscp1</strong> and <strong class="pkg">scscp2</strong> content dictionaries (<a href="chapBib_mj.html#biBscscp1cd">[FHK+a]</a>, <a href="chapBib_mj.html#biBscscp2cd">[FHK+c]</a>), and also service-dependent transient private content dictionaries (see Chapter <a href="chap5_mj.html#X7DEE95317812A998"><span class="RefLink">5</span></a> for details about transient content dictionaries). It also overwrites some <strong class="pkg">OpenMath</strong> functions by their extended (but backwards compatible) versions, and adds some new <strongclass="pkg">OpenMath</strong>-related functions to send and receive <strong class="pkg">SCSCP</strong> messages, documented below.</p>
<p>Note that functions documented in this chapter belong to the middle-level interface, and the user may find it more convenient to use functions developed on top of them and explained in next chapters.</p>
<p>Initialises <strong class="pkg">SCSCP</strong> session and negotiates with the server about the version of the protocol. Returns the string with the <code class="code">service_id</code> (which may be used later as a part of the call identifier) or causes an error message if can not perform these tasks.</p>
<p>Takes a stream <var class="Arg">stream</var>, the string <var class="Arg">proc_name</var> and a record <var class="Arg">objrec</var>, and writes to <var class="Arg">stream</var> an <strong class="pkg">OpenMath</strong> object <code class="code">procedure_call</code> for the procedure <var class="Arg">proc_name</var> with arguments given by the list <code class="code">objrec.object</code> and procedure call options (which should be encoded as <strong class="pkg">OpenMath</strong> attributes) given in the list <code class="code">objrec.attributes</code>.</p>
<p>This function accepts options <code class="code">cd</code> and <code class="code">debuglevel</code>.</p>
<p><code class="code">cd:="cdname"</code> may be used to specify the name of the content dictionary if the procedure is actually a standard <strong class="pkg">OpenMath</strong> symbol. Note that the server may reject such a call if it accepts only calls of procedures from the transient content dictionary, see <code class="func">InstallSCSCPprocedure</code> (<a href="chap5_mj.html#X8031C2F4787E0C1A"><span class="RefLink">5.1-1</span></a>) for explanation). If the <code class="code">cdname</code> is not specified, <code class="code">scscp_transient_1</code> content dictionary will be assumed by default. The value of the <code class="code">debuglevel</code> option is an integer. If it is non-zero, the <code class="code">procedure_completed</code> message will carry on also some additional information about the call, for example, runtime and memory used.</p>
<p>This function may be used by the <strong class="pkg">SCSCP</strong> client to wait (using <code class="func">IO_select</code> (<a href="../../../pkg/io/doc/chap3_mj.html#X81CA6EE88062010E"><span class="RefLink">IO: IO_select</span></a>)) until the result of the procedure call will be available from <var class="Arg">stream</var>. By default the timeout is one hour, to specify another value give it as the optional second argument in seconds. See the end of this chapter for the example.</p>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ OMGetObjectWithAttributes</code>( <var class="Arg">stream</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>Returns: record with components <code class="code">object</code> and <code class="code">attributes</code>, or <code class="keyw">fail</code></p>
<p>This function is similar to the function <code class="code">OMGetObject</code> from the <strongclass="pkg">OpenMath</strong> package, and the main difference is that it is able to understand <strong class="pkg">OpenMath</strong> attribution pairs. It retrieves exactly one <strong class="pkg">OpenMath</strong> object from the stream <var class="Arg">stream</var>, and stores it in the <code class="code">object</code> component of the returned record. If the <strong class="pkg">OpenMath</strong> object has no attributes, the <code class="code">attributes</code> component of the returned record will be an empty list, otherwise it will contain pairs <code class="code">[attribute_name,attribute_value]</code>, where <code class="code">attribute_name</code> is a string, and <code class="code">attribute_value</code> is a <strong class="pkg">GAP</strong> object, whose type is determined by the kind of an attribute. Only attributes, defined by the SCSCP are allowed, otherwise an error message will be displayed.</p>
<p>If the procedure was not successful, the function returns <code class="keyw">fail</code> instead of an error message like the function <code class="func">OMGetObject</code> (<a href="../../../pkg/openmath/doc/chap2_mj.html#X7FBDCB3C83BBB115"><span class="RefLink">OpenMath: OMGetObject</span></a>) does. Returning <code class="keyw">fail</code> is useful when <code class="code">OMGetObjectWithAttributes</code> is used inside accept-evaluate-return loop.</p>
<p>As an example, the file <code class="file">scscp/tst/omdemo.om</code> contains some <strong class="pkg">OpenMath</strong> objects, including those from the SCSCP Specification <a href="chapBib_mj.html#biBSCSCP">[FHK+b]</a>. We can retrieve them from this file, preliminary installing some SCSCP procedures using the function <code class="func">InstallSCSCPprocedure</code> (<a href="chap5_mj.html#X8031C2F4787E0C1A"><span class="RefLink">5.1-1</span></a>):</p>
<p>Takes a stream <var class="Arg">stream</var>, and a record <var class="Arg">objrec</var>, and writes to <var class="Arg">stream</var> an <strong class="pkg">OpenMath</strong> object <code class="code">procedure_completed</code> with the result being <code class="code">objrec.object</code> and information messages (as <strong class="pkg">OpenMath</strong> attributes) given in the list <code class="code">objrec.attributes</code>.</p>
<p>Takes a stream <var class="Arg">stream</var>, and a record with an error message <var class="Arg">objrec</var> (for example <code class="code">rec( attributes := [ [ "call_id", "localhost:26133:87643:gcX33cCf" ] ],</code> <code class="code">object := "localhost:26133 reports : Rational operations: <divisor> must not be zero")</code> and writes to the <var class="Arg">stream</var> an <strong class="pkg">OpenMath</strong> object <code class="code">procedure_terminated</code> containing an error determined by the symbol <var class="Arg">error_type</var> from the content dictionary <var class="Arg">error_cd</var> (for example, <code class="code">error_memory</code>, <code class="code">error_runtime</code> or <code class="code">error_system_specific</code> from the <strong class="pkg">scscp1</strong> content dictionary (<a href="chapBib_mj.html#biBscscp1cd">[FHK+a]</a>).</p>
<p>This is the internal function of the package which is used only in the code for the <strong class="pkg">SCSCP</strong> server to return the error message to the client.</p>
<p>In the following example we start an <strong class="pkg">SCSCP</strong> session and perform ten procedure calls in a loop before closing that session. Note that we demonstrate the usage of the session ID <code class="code">sid</code> and the function <code class="code">RandomString</code> from the <strong class="pkg">OpenMath</strong> package to produce some unique call identifier. The call ID is a mandatory attribute for any procedure call, however, it is not nesessarily random; for example, it may be just a string with the number of the procedure call.</p>
<p>Also note the usage of <code class="func">SCSCPwait</code> (<a href="chap4_mj.html#X7ABD2EA6792279CF"><span class="RefLink">4.1-3</span></a>) to wait until the result of the computation will be available from <code class="code">stream</code>.</p>
<p>In this example we assumed that there is an <strong class="pkg">SCSCP</strong> server running at <code class="code">localhost</code>, port 26133. In the next chapter we will explain how to configure and run a <strong class="pkg">GAP</strong> <strong class="pkg">SCSCP</strong> server and how to interrogate it from a <strong class="pkg">GAP</strong> client to learn about its functionality. After that, we will proceed with the <strong class="pkg">SCSCP</strong> client functionality for the end-user.</p>
Die Informationen auf dieser Webseite wurden
nach bestem Wissen sorgfältig zusammengestellt. Es wird jedoch weder Vollständigkeit, noch Richtigkeit,
noch Qualität der bereit gestellten Informationen zugesichert.
Bemerkung:
Die farbliche Syntaxdarstellung ist noch experimentell.
