PyPI - amps-python-client - Versions diffs - 5.3.4.1__zip - Mend

amps-python-client 5.3.4.1__zip

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (550) hide show

amps-python-client-5.3.4.1/docs/command-reference/html/chapters/ack-messages.html ADDED Viewed

@@ -0,0 +1,417 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    <title>8. Ack Messages &#8212; Advanced Message Processing System (AMPS) Command Reference develop
+ documentation</title>
+    <link rel="stylesheet" href="../_static/alabaster.css" type="text/css" />
+    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+    <script type="text/javascript">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    '../',
+        VERSION:     'develop',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true,
+        SOURCELINK_SUFFIX: '.txt'
+      };
+    </script>
+    <script type="text/javascript" src="../_static/jquery.js"></script>
+    <script type="text/javascript" src="../_static/underscore.js"></script>
+    <script type="text/javascript" src="../_static/doctools.js"></script>
+    <link rel="index" title="Index" href="../genindex.html" />
+    <link rel="search" title="Search" href="../search.html" />
+    <link rel="next" title="9. Query Result Set Delimiters" href="query-delimiters.html" />
+    <link rel="prev" title="7. Content Messages" href="content-messages.html" />
+  <link rel="stylesheet" href="../_static/custom.css" type="text/css" />
+  <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
+  </head>
+  <body role="document">
+  <div class="document">
+      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
+        <div class="sphinxsidebarwrapper">
+            <p class="logo"><a href="../index.html">
+              <img class="logo" src="../_static/flag_logo.png" alt="Logo"/>
+            </a></p>
+  <h3><a href="../index.html">Table Of Contents</a></h3>
+  <ul>
+<li><a class="reference internal" href="#">8. Ack Messages</a><ul>
+<li><a class="reference internal" href="#ack-message">ack message</a><ul>
+<li><a class="reference internal" href="#common-header-fields-for-ack-messages">Common Header Fields For Ack Messages</a><ul>
+<li><a class="reference internal" href="#additional-fields-for-logon">Additional fields for logon</a></li>
+<li><a class="reference internal" href="#additional-fields-for-publish-and-delta-publish">Additional fields for publish and delta_publish</a></li>
+<li><a class="reference internal" href="#additional-fields-for-subscribe-and-delta-subscribe">Additional fields for subscribe and delta_subscribe</a></li>
+<li><a class="reference internal" href="#additional-fields-for-unsubscribe">Additional fields for unsubscribe</a></li>
+<li><a class="reference internal" href="#additional-fields-for-sow-sow-and-subscribe-sow-and-delta-subscribe">Additional fields for sow, sow_and_subscribe, sow_and_delta_subscribe</a></li>
+<li><a class="reference internal" href="#additional-fields-for-sow-delete">Additional fields for sow_delete</a></li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+<div class="relations">
+<h3>Related Topics</h3>
+<ul>
+  <li><a href="../index.html">Documentation overview</a><ul>
+      <li>Previous: <a href="content-messages.html" title="previous chapter">7. Content Messages</a></li>
+      <li>Next: <a href="query-delimiters.html" title="next chapter">9. Query Result Set Delimiters</a></li>
+  </ul></li>
+</ul>
+</div>
+<div id="searchbox" style="display: none" role="search">
+  <h3>Quick search</h3>
+    <form class="search" action="../search.html" method="get">
+      <div><input type="text" name="q" /></div>
+      <div><input type="submit" value="Go" /></div>
+      <input type="hidden" name="check_keywords" value="yes" />
+      <input type="hidden" name="area" value="default" />
+    </form>
+</div>
+<script type="text/javascript">$('#searchbox').show(0);</script>
+        </div>
+      </div>
+      <div class="documentwrapper">
+        <div class="bodywrapper">
+          <div class="body" role="main">
+  <div class="section" id="ack-messages">
+<span id="command-guide-ack-messages"></span><h1>8. Ack Messages<a class="headerlink" href="#ack-messages" title="Permalink to this headline">¶</a></h1>
+<p>AMPS provides information to the application and
+AMPS client about the status of commands using
+acknowledgement, or <code class="docutils literal"><span class="pre">ack</span></code>, messages.</p>
+<p>A command to AMPS must explicitly request
+acknowledgement to receive a response from AMPS.
+By default, the AMPS client libraries request
+acknowledgements as needed to detect failures:
+see the <em>AMPS User Guide</em> chapter on
+acknowledgements and the <em>Developer Guide</em>
+for each client language for details.</p>
+<p>In some cases, an application may want additional
+information about the state of a command, and may
+request an <code class="docutils literal"><span class="pre">ack</span></code> explicitly.  For example,
+an application may want to know how many records
+would be returned by a particular query. In that
+case, a common technique is to request a <code class="docutils literal"><span class="pre">stats</span></code>
+(statistics) <code class="docutils literal"><span class="pre">ack</span></code>, while setting the number
+of data messages to be returned to <code class="docutils literal"><span class="pre">0</span></code> (using
+the <code class="docutils literal"><span class="pre">top_n=0</span></code> option).</p>
+<p>This section describes the <code class="docutils literal"><span class="pre">ack</span></code> messages
+returned by AMPS.</p>
+<div class="section" id="ack-message">
+<h2>ack message<a class="headerlink" href="#ack-message" title="Permalink to this headline">¶</a></h2>
+<p>The <code class="docutils literal"><span class="pre">ack</span></code> message returns status information from AMPS.</p>
+<p>AMPS does not create <code class="docutils literal"><span class="pre">ack</span></code> messages unless an acknowledgment is
+specifically requested. The exact meaning and content of ack messages
+depends on the command the requests the message. AMPS supports the
+following types of ack messages with the general semantics described
+below.</p>
+<table border="1" class="docutils" id="message-ack-types">
+<colgroup>
+<col width="50%" />
+<col width="50%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head"><strong>ack Type</strong></th>
+<th class="head"><strong>Meaning</strong></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal"><span class="pre">completed</span></code></td>
+<td><p class="first">An operation has completed.</p>
+<p class="last">For example, subscriptions that replay from the
+transaction log can produce a <code class="docutils literal"><span class="pre">completed</span></code>
+acknowledgment to indicate when transaction log
+replay has finished and further messages for the
+subscription are the result of new publishes.</p>
+</td>
+</tr>
+<tr class="row-odd"><td><code class="docutils literal"><span class="pre">persisted</span></code></td>
+<td>Data has been persisted.</td>
+</tr>
+<tr class="row-even"><td><code class="docutils literal"><span class="pre">processed</span></code></td>
+<td>AMPS has processed the command. Notice that,
+depending on the command, AMPS may not have
+executed the command when this acknowledgment
+is produced.</td>
+</tr>
+<tr class="row-odd"><td><code class="docutils literal"><span class="pre">received</span></code></td>
+<td>AMPS has received the command, but has not yet
+processed it.</td>
+</tr>
+<tr class="row-even"><td><code class="docutils literal"><span class="pre">stats</span></code></td>
+<td>Statistics for the command. This acknowledgment
+is typically produced after the command has
+fully completed.</td>
+</tr>
+</tbody>
+</table>
+<p><em>Types of ack message</em></p>
+<div class="section" id="common-header-fields-for-ack-messages">
+<h3>Common Header Fields For Ack Messages<a class="headerlink" href="#common-header-fields-for-ack-messages" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils" id="message-ack-headers">
+<colgroup>
+<col width="50%" />
+<col width="50%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head"><strong>Field</strong></th>
+<th class="head"><strong>Description</strong></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal"><span class="pre">Command</span></code></td>
+<td>Type of message. Always <code class="docutils literal"><span class="pre">ack</span></code>, as encoded by
+the protocol.</td>
+</tr>
+<tr class="row-odd"><td><code class="docutils literal"><span class="pre">AckType</span></code></td>
+<td>The type of acknowledgment. One of
+<code class="docutils literal"><span class="pre">completed</span></code>, <code class="docutils literal"><span class="pre">persisted</span></code>, <code class="docutils literal"><span class="pre">processed</span></code>,
+<code class="docutils literal"><span class="pre">received</span></code> or <code class="docutils literal"><span class="pre">stats</span></code>.</td>
+</tr>
+<tr class="row-even"><td><code class="docutils literal"><span class="pre">CommandId</span></code></td>
+<td>The <code class="docutils literal"><span class="pre">CommandId</span></code> that this ack refers to.
+Clients can use this field to correlate the
+<code class="docutils literal"><span class="pre">ack</span></code> returned with the command being
+acknowledged.</td>
+</tr>
+<tr class="row-odd"><td><code class="docutils literal"><span class="pre">Status</span></code></td>
+<td>The status of the command.</td>
+</tr>
+<tr class="row-even"><td><code class="docutils literal"><span class="pre">Reason</span></code></td>
+<td>The reason for a <code class="docutils literal"><span class="pre">failure</span></code> status.</td>
+</tr>
+</tbody>
+</table>
+<p><em>Header fields provided in ack</em></p>
+<div class="section" id="additional-fields-for-logon">
+<h4>Additional fields for logon<a class="headerlink" href="#additional-fields-for-logon" title="Permalink to this headline">¶</a></h4>
+<p>When the <code class="docutils literal"><span class="pre">ack</span></code> message is produced in response to a <code class="docutils literal"><span class="pre">logon</span></code> command,
+the following additional header fields may be set:</p>
+<table border="1" class="docutils" id="message-logon-ack-headers">
+<colgroup>
+<col width="50%" />
+<col width="50%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head"><strong>Field</strong></th>
+<th class="head"><strong>Description</strong></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal"><span class="pre">ClientName</span></code></td>
+<td>The name of the client provided with the
+command.</td>
+</tr>
+<tr class="row-odd"><td><code class="docutils literal"><span class="pre">SequenceId</span></code></td>
+<td>The last <code class="docutils literal"><span class="pre">SequenceId</span></code> persisted to the
+transaction log for this client, as identified
+by the <code class="docutils literal"><span class="pre">ClientName</span></code>.</td>
+</tr>
+<tr class="row-even"><td><code class="docutils literal"><span class="pre">Bookmark</span></code></td>
+<td>The last bookmark from this client.</td>
+</tr>
+<tr class="row-odd"><td><code class="docutils literal"><span class="pre">UserId</span></code></td>
+<td><code class="docutils literal"><span class="pre">UserId</span></code> to use when the status is retry.</td>
+</tr>
+<tr class="row-even"><td><code class="docutils literal"><span class="pre">Password</span></code></td>
+<td><code class="docutils literal"><span class="pre">Password</span></code> to use when the status is retry.</td>
+</tr>
+<tr class="row-odd"><td><code class="docutils literal"><span class="pre">Version</span></code></td>
+<td>The version of the AMPS server.</td>
+</tr>
+</tbody>
+</table>
+<p><em>Additional ack headers for logon</em></p>
+</div>
+<div class="section" id="additional-fields-for-publish-and-delta-publish">
+<h4>Additional fields for publish and delta_publish<a class="headerlink" href="#additional-fields-for-publish-and-delta-publish" title="Permalink to this headline">¶</a></h4>
+<p>When the <code class="docutils literal"><span class="pre">ack</span></code> message is produced in response to a <code class="docutils literal"><span class="pre">publish</span></code> or
+<code class="docutils literal"><span class="pre">delta_publish</span></code> command, the following additional header fields may be
+set:</p>
+<table border="1" class="docutils" id="message-publish-ack-headers">
+<colgroup>
+<col width="50%" />
+<col width="50%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head"><strong>Field</strong></th>
+<th class="head"><strong>Description</strong></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal"><span class="pre">SequenceId</span></code></td>
+<td>The last SequenceId persisted for this client.</td>
+</tr>
+<tr class="row-odd"><td><code class="docutils literal"><span class="pre">Bookmark</span></code></td>
+<td>The last Bookmark persisted for this client.</td>
+</tr>
+</tbody>
+</table>
+<p><em>Additional ack headers for publish or delta_publish</em></p>
+</div>
+<div class="section" id="additional-fields-for-subscribe-and-delta-subscribe">
+<h4>Additional fields for subscribe and delta_subscribe<a class="headerlink" href="#additional-fields-for-subscribe-and-delta-subscribe" title="Permalink to this headline">¶</a></h4>
+<p>When the <code class="docutils literal"><span class="pre">ack</span></code> message is produced in response to a <code class="docutils literal"><span class="pre">subscribe</span></code> or
+<code class="docutils literal"><span class="pre">delta_subscribe</span></code> command, the following additional header fields may
+be set:</p>
+<table border="1" class="docutils" id="mesage-subscribe-ack-headers">
+<colgroup>
+<col width="50%" />
+<col width="50%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head"><strong>Field</strong></th>
+<th class="head"><strong>Description</strong></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal"><span class="pre">SubId</span></code></td>
+<td>The <code class="docutils literal"><span class="pre">SubId</span></code> sent with the command, or the
+<code class="docutils literal"><span class="pre">SubId</span></code> generated by AMPS if no <code class="docutils literal"><span class="pre">SubId</span></code> was
+provided. This field is not returned in
+<code class="docutils literal"><span class="pre">processed</span></code> acks.</td>
+</tr>
+<tr class="row-odd"><td><code class="docutils literal"><span class="pre">Options</span></code></td>
+<td><p class="first">Returned when the command is a <code class="docutils literal"><span class="pre">subscribe</span></code> to
+a queue. Contains the following options:</p>
+<p class="last"><code class="docutils literal"><span class="pre">max_backlog</span></code> indicates the effective maximum
+backlog that the server has assigned for this
+subscription.</p>
+</td>
+</tr>
+<tr class="row-even"><td><code class="docutils literal"><span class="pre">Bookmark</span></code></td>
+<td>For a <code class="docutils literal"><span class="pre">completed</span></code> acknowledgement on a
+bookmark subscription, this indicates the point
+in the transaction log where the
+acknowledgement message was generated. Notice
+that the message that corresponds to this
+bookmark need not be a message matched by the
+subscription.</td>
+</tr>
+</tbody>
+</table>
+<p><em>Additional ack headers for subscribe or delta_subscribe</em></p>
+</div>
+<div class="section" id="additional-fields-for-unsubscribe">
+<h4>Additional fields for unsubscribe<a class="headerlink" href="#additional-fields-for-unsubscribe" title="Permalink to this headline">¶</a></h4>
+<p>When the <code class="docutils literal"><span class="pre">ack</span></code> message is produced in response to a <code class="docutils literal"><span class="pre">unsubscribe</span></code>,
+AMPS does not provide additional header fields.</p>
+</div>
+<div class="section" id="additional-fields-for-sow-sow-and-subscribe-sow-and-delta-subscribe">
+<h4>Additional fields for sow, sow_and_subscribe, sow_and_delta_subscribe<a class="headerlink" href="#additional-fields-for-sow-sow-and-subscribe-sow-and-delta-subscribe" title="Permalink to this headline">¶</a></h4>
+<p>When the <code class="docutils literal"><span class="pre">ack</span></code> message is produced in response to a <code class="docutils literal"><span class="pre">sow</span></code>,
+<code class="docutils literal"><span class="pre">sow_and_subscribe</span></code>, or <code class="docutils literal"><span class="pre">sow_and_delta_subscribe</span></code>, the following
+additional header fields may be set:</p>
+<table border="1" class="docutils" id="message-sow-ack-headers">
+<colgroup>
+<col width="50%" />
+<col width="50%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head"><strong>Field</strong></th>
+<th class="head"><strong>Description</strong></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal"><span class="pre">SubId</span></code></td>
+<td>The <code class="docutils literal"><span class="pre">SubId</span></code> sent with the sow command.</td>
+</tr>
+<tr class="row-odd"><td><code class="docutils literal"><span class="pre">QueryId</span></code></td>
+<td>The <code class="docutils literal"><span class="pre">QueryId</span></code> sent with the sow command.</td>
+</tr>
+<tr class="row-even"><td><code class="docutils literal"><span class="pre">RecordsReturned</span></code></td>
+<td>The number of records returned by a SOW query.
+This header field is present on <code class="docutils literal"><span class="pre">stats</span></code>
+acknowledgments.</td>
+</tr>
+<tr class="row-odd"><td><code class="docutils literal"><span class="pre">TopicMatches</span></code></td>
+<td>The total number of records compared across all
+matching SOW topics. This header field is
+present on <code class="docutils literal"><span class="pre">stats</span></code> acknowledgments.</td>
+</tr>
+<tr class="row-even"><td><code class="docutils literal"><span class="pre">Matches</span></code></td>
+<td>The number of records that match the topic
+regular expression and content filter.
+This header field is present on <code class="docutils literal"><span class="pre">stats</span></code>
+acknowledgments.</td>
+</tr>
+</tbody>
+</table>
+<p><em>Additional ack headers for sow, sow_and_subscribe, sow_and_delta_subscribe</em></p>
+</div>
+<div class="section" id="additional-fields-for-sow-delete">
+<h4>Additional fields for sow_delete<a class="headerlink" href="#additional-fields-for-sow-delete" title="Permalink to this headline">¶</a></h4>
+<p>When the <code class="docutils literal"><span class="pre">ack</span></code> message is produced in response to a <code class="docutils literal"><span class="pre">sow_delete</span></code> the
+following additional header fields may be set:</p>
+<table border="1" class="docutils" id="message-sow-delete-ack-headers">
+<colgroup>
+<col width="50%" />
+<col width="50%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head"><strong>Field</strong></th>
+<th class="head"><strong>Description</strong></th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal"><span class="pre">QueryId</span></code></td>
+<td>The <code class="docutils literal"><span class="pre">QueryId</span></code> sent with the <code class="docutils literal"><span class="pre">sow_delete</span></code>
+command.</td>
+</tr>
+<tr class="row-odd"><td><code class="docutils literal"><span class="pre">RecordsDeleted</span></code></td>
+<td>The number of records deleted by the command.
+This header field is present on <code class="docutils literal"><span class="pre">stats</span></code>
+acknowledgments.</td>
+</tr>
+<tr class="row-even"><td><code class="docutils literal"><span class="pre">TopicMatches</span></code></td>
+<td>The total number of records compared across all
+matching SOW topics. This header field is
+present on <code class="docutils literal"><span class="pre">stats</span></code> acknowledgments.</td>
+</tr>
+<tr class="row-odd"><td><code class="docutils literal"><span class="pre">Matches</span></code></td>
+<td>The number of records that match the
+topic regular expression and content filter.
+This header field is present on <code class="docutils literal"><span class="pre">stats</span></code>
+acknowledgments.</td>
+</tr>
+</tbody>
+</table>
+<p><em>Additional ack headers for sow_delete</em></p>
+</div>
+</div>
+</div>
+</div>
+          </div>
+        </div>
+      </div>
+    <div class="clearer"></div>
+  </div>
+    <div class="footer">
+      &copy;2022, 60East Technologies, Inc..
+      |
+      Powered by <a href="http://sphinx-doc.org/">Sphinx 1.5.3</a>
+      &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.10</a>
+    </div>
+  </body>
+</html>