amps-python-client 5.3.4.1__zip → 5.3.4.2__zip

amps-python-client-5.3.4.2/src/sowrecoverypointadapter.cpp

@@ -0,0 +1,248 @@
+////////////////////////////////////////////////////////////////////////////
+//
+// Copyright (c) 2010-2024 60East Technologies Inc., All Rights Reserved.
+//
+// This computer software is owned by 60East Technologies Inc. and is
+// protected by U.S. copyright laws and other laws and by international
+// treaties.  This computer software is furnished by 60East Technologies
+// Inc. pursuant to a written license agreement and may be used, copied,
+// transmitted, and stored only in accordance with the terms of such
+// license agreement and with the inclusion of the above copyright notice.
+// This computer software or any other copies thereof may not be provided
+// or otherwise made available to any other person.
+//
+// U.S. Government Restricted Rights.  This computer software: (a) was
+// developed at private expense and is in all respects the proprietary
+// information of 60East Technologies Inc.; (b) was not developed with
+// government funds; (c) is a trade secret of 60East Technologies Inc.
+// for all purposes of the Freedom of Information Act; and (d) is a
+// commercial item and thus, pursuant to Section 12.212 of the Federal
+// Acquisition Regulations (FAR) and DFAR Supplement Section 227.7202,
+// Government's use, duplication or disclosure of the computer software
+// is subject to the restrictions set forth by 60East Technologies Inc..
+//
+////////////////////////////////////////////////////////////////////////////
+
+#define PY_SSIZE_T_CLEAN 1
+#include <Python.h>
+#include <amps/ampsplusplus.hpp>
+#include <ampspy_types.hpp>
+#include <ampspy_defs.hpp>
+#include <amps/SOWRecoveryPointAdapter.hpp>
+
+using namespace AMPS;
+namespace ampspy
+{
+  namespace sowrecoverypointadapter
+  {
+//    def __init__(self, name):
+    static int _ctor(obj* self, PyObject* args, PyObject* kwds)
+    {
+      static const char* kwlist[] = { "store_client", "tracked_client_name",
+                                      "timeout_millis", "use_timestamp"
+                                      "close_client", "update_failure_throws",
+                                      "topic", "client_name_field",
+                                      "sub_id_field", "bookmark_field", NULL
+                                    };
+      PyObject* pStoreClient = NULL;
+      char* trackedClientName = NULL;
+      int timeoutMillis = 5000;
+      char useTimestamp = (char)false;
+      char closeClient = (char)true;
+      char updateFailureThrows = (char)false;
+      char* topic = (char*)AMPS_SOW_STORE_DEFAULT_TOPIC;
+      char* clientNameField = (char*)AMPS_SOW_STORE_DEFAULT_CLIENT_FIELD;
+      char* subIdField = (char*)AMPS_SOW_STORE_DEFAULT_SUB_FIELD;
+      char* bookmarkField = (char*)AMPS_SOW_STORE_DEFAULT_BOOKMARK_FIELD;
+      if (!PyArg_ParseTupleAndKeywords(args, kwds, (char*)"Os|ibbbssss", (char**)kwlist, &pStoreClient, &trackedClientName, &timeoutMillis, &useTimestamp, &closeClient, &updateFailureThrows, &topic,
+                                       &clientNameField, &subIdField, &bookmarkField))
+      {
+        return -1;
+      }
+      client::obj* pClient = (client::obj*)pStoreClient;
+      self->pImpl = std::make_shared<SOWRecoveryPointAdapter>(
+                      *(pClient->pClient),
+                      trackedClientName,
+                      (unsigned)timeoutMillis,
+                      useTimestamp != 0,
+                      closeClient != 0,
+                      updateFailureThrows != 0,
+                      topic,
+                      clientNameField,
+                      subIdField,
+                      bookmarkField);
+      self->adapter = RecoveryPointAdapter(self->pImpl.get(), false);
+      return 0;
+    }
+
+    static void _dtor(obj* self)
+    {
+      {
+        UNLOCKGIL;
+        self->pImpl.reset();
+      }
+      self->exceptionListener.reset();
+      shims::free(self);
+    }
+
+//    def set_exception_listener(self, exception_listener):
+    static PyObject* set_exception_listener(obj* self, PyObject* args)
+    {
+      PyObject* callable;
+      if (!PyArg_ParseTuple(args, "O", &callable))
+      {
+        return NULL;
+      }
+      if (!PyCallable_Check(callable) && callable != Py_None)
+      {
+        PyErr_SetString(PyExc_TypeError, "argument must be callable.");
+        return NULL;
+      }
+      // the ctor/dtor of pyexceptionlistener takes care of reference counts
+      self->exceptionListener.reset();
+      if (callable == Py_None)
+      {
+        self->exceptionListener = std::make_shared<PyExceptionListener>();
+      }
+      else
+      {
+        self->exceptionListener = std::make_shared<PyExceptionListener>(callable);
+      }
+      CALL_RETURN_NONE(((AMPS::SOWRecoveryPointAdapter*)(self->pImpl.get()))
+                       ->setExceptionListener(self->exceptionListener));
+    }
+
+    static PyObject* get_exception_listener(obj* self, PyObject* args)
+    {
+      if (self->exceptionListener)
+      {
+        PyObject* object = (PyObject*) ((PyExceptionListener*)(self->exceptionListener.get()))->callable();
+        if (object)
+        {
+          Py_INCREF(object);
+          return object;
+        }
+      }
+      NONE;
+    }
+
+    static PyObject* next(obj* self, PyObject* args)
+    {
+      RecoveryPoint current;
+      bool hasNext = false;
+      CALL_AND_CAPTURE_RETURN_VALUE(self->pImpl->next(current), hasNext);
+      PyObject* pRecoveryPoint = NULL;
+      recoverypoint::obj* pRecoverypointObj = PyObject_New(recoverypoint::obj, recoverypoint::type);
+      pRecoveryPoint = (PyObject*)pRecoverypointObj;
+      if (hasNext)
+      {
+        pRecoverypointObj->subId = strdup(((std::string)(current.getSubId())).c_str());
+        pRecoverypointObj->bookmark = strdup(((std::string)(current.getBookmark())).c_str());
+      }
+      return pRecoveryPoint;
+    }
+
+    static PyObject* update(obj* self, PyObject* args)
+    {
+      ampspy::recoverypoint::obj* pRecoveryPoint = NULL;
+      if (!PyArg_ParseTuple(args, "O!",
+                            &ampspy::recoverypoint::type,
+                            &pRecoveryPoint))
+      {
+        return NULL;
+      }
+      RecoveryPoint rp(new FixedRecoveryPoint(pRecoveryPoint->subId,
+                                              pRecoveryPoint->bookmark));
+      CALL_RETURN_NONE(self->pImpl->update(rp));
+    }
+
+// def purge() or purge(subId)
+    static PyObject* purge(obj* self, PyObject* args)
+    {
+      char* subId = NULL;
+      if (!PyArg_ParseTuple(args, "|s", &subId))
+      {
+        return NULL;
+      }
+      if (subId == NULL)
+      {
+        CALL_RETURN_NONE(self->pImpl->purge());
+      }
+      else
+      {
+        CALL_RETURN_NONE(self->pImpl->purge(subId));
+      }
+    }
+
+    static PyObject* close(obj* self, PyObject* args)
+    {
+      CALL_RETURN_NONE(self->pImpl->close());
+    }
+
+    static PyObject* prune(obj* self, PyObject* args)
+    {
+      CALL_RETURN_NONE(self->pImpl->prune());
+    }
+
+    static const char* sowrecoverypointadapter_class_doc = "\n"
+                                                           " This class can be used as an adapter on an AMPS.MemoryBookmarkStore"
+                                                           " to save enough recovery state information to guarantee no missed"
+                                                           " messages. It must be constructed with a client using json message"
+                                                           " type, connected and logged on to a server on which the chosen topic"
+                                                           " is defined as a SOW topic with key fields equivalent to the chosen"
+                                                           " client name field and sub id field. It also must not be the same"
+                                                           " client that is being tracked, whose name is provided as the"
+                                                           " tracked client name.";
+
+    AMPSDLL ampspy::ampspy_type_object type;
+
+    void add_types(PyObject* module_)
+    {
+      type.setName("AMPS.SOWRecoveryPointAdapter")
+      .setBasicSize(sizeof(obj))
+      .setDestructorFunction(_dtor)
+      .setBaseType()
+      .setConstructorFunction(_ctor)
+      .setDoc(sowrecoverypointadapter_class_doc)
+      .notCopyable()
+      .addMethod("set_exception_listener", set_exception_listener,
+                 "set_exception_listener(listener)\n\n"
+                 "set_exception_listener(exception_listener)\n\n"
+                 " Sets the exception listener instance used for communicating\n"
+                 "        absorbed exceptions.\n"
+                 "\n"
+                 ":param exception_listener: The exception listener instance to invoke\n"
+                 "           for exceptions.\n"
+                 ":type exception_listener: :exc:`Exception`\n"
+                 "\n")
+      .addMethod("get_exception_listener", get_exception_listener,
+                 "get_exception_listener()\n\n"
+                 " Returns the exception listener callable set on self, or None.\n\n")
+      .addMethod("next", next,
+                 "next()\n\n"
+                 " Returns the next RecoveryPoint from the SOW or an empty one if\n"
+                 "        recovery has completed.\n\n")
+      .addMethod("update", update,
+                 "update(recoveryPoint)\n\n"
+                 "Updates the SOW with the new information in recoveryPoint.\n"
+                 ":param recovery_point: The new recovery information to save.\n"
+                 ":type recovery_point: :ampspy:recoveryPoint\n\n")
+      .addMethod("purge", purge,
+                 "purge(sub_id)\n\n"
+                 "If sub_id is provided, remove all records related to sub_id.\n"
+                 "If no sub_id is provided, remove all records for this client.\n"
+                 ":param sub_id: The optional sub_id to remove or all if none\n"
+                 "\n")
+      .addMethod("close", close,
+                 "close(subid, bookmark)\n\n"
+                 "Close the store so it can no longer be used. May close the\n"
+                 "store client if that option was true when constructed.\n\n")
+      .addMethod("prune", prune,
+                 "prune()\n\n"
+                 "This has no affect on a SOWRecoveryPointAdapter.\n\n")
+      .createType()
+      .registerType("SOWRecoveryPointAdapter", module_);
+    }
+
+  } // namespace sowrecoverypointadapter
+} // namespace ampspy

amps-python-client-5.3.4.2/src/store.cpp

@@ -0,0 +1,62 @@
+////////////////////////////////////////////////////////////////////////////
+//
+// Copyright (c) 2010-2024 60East Technologies Inc., All Rights Reserved.
+//
+// This computer software is owned by 60East Technologies Inc. and is
+// protected by U.S. copyright laws and other laws and by international
+// treaties.  This computer software is furnished by 60East Technologies
+// Inc. pursuant to a written license agreement and may be used, copied,
+// transmitted, and stored only in accordance with the terms of such
+// license agreement and with the inclusion of the above copyright notice.
+// This computer software or any other copies thereof may not be provided
+// or otherwise made available to any other person.
+//
+// U.S. Government Restricted Rights.  This computer software: (a) was
+// developed at private expense and is in all respects the proprietary
+// information of 60East Technologies Inc.; (b) was not developed with
+// government funds; (c) is a trade secret of 60East Technologies Inc.
+// for all purposes of the Freedom of Information Act; and (d) is a
+// commercial item and thus, pursuant to Section 12.212 of the Federal
+// Acquisition Regulations (FAR) and DFAR Supplement Section 227.7202,
+// Government's use, duplication or disclosure of the computer software
+// is subject to the restrictions set forth by 60East Technologies Inc..
+//
+////////////////////////////////////////////////////////////////////////////
+
+#define PY_SSIZE_T_CLEAN 1
+#include <Python.h>
+#include <amps/ampsplusplus.hpp>
+#include <ampspy_types.hpp>
+#include <ampspy_defs.hpp>
+
+using namespace AMPS;
+namespace ampspy
+{
+  namespace store
+  {
+
+//    def __init__(self):
+    static int _ctor(obj* self, PyObject* args, PyObject* kwds)
+    {
+      return 0;
+    }
+    static void _dtor(obj* self)
+    {
+      shims::free(self);
+    }
+
+    static ampspy::ampspy_type_object store_type;
+
+    void add_types(PyObject* module_)
+    {
+      store_type.setName("AMPS.Store")
+      .setBasicSize(sizeof(obj))
+      .setDestructorFunction(_dtor)
+      .setConstructorFunction(_ctor)
+      .setDoc("AMPS Store Object")
+      .createType()
+      .registerType("Store", module_);
+    }
+
+  } // namespace store
+} // namespace ampspy

amps-python-client-5.3.4.2/src/versioninfo.cpp

@@ -0,0 +1,175 @@
+////////////////////////////////////////////////////////////////////////////
+//
+// Copyright (c) 2010-2024 60East Technologies Inc., All Rights Reserved.
+//
+// This computer software is owned by 60East Technologies Inc. and is
+// protected by U.S. copyright laws and other laws and by international
+// treaties.  This computer software is furnished by 60East Technologies
+// Inc. pursuant to a written license agreement and may be used, copied,
+// transmitted, and stored only in accordance with the terms of such
+// license agreement and with the inclusion of the above copyright notice.
+// This computer software or any other copies thereof may not be provided
+// or otherwise made available to any other person.
+//
+// U.S. Government Restricted Rights.  This computer software: (a) was
+// developed at private expense and is in all respects the proprietary
+// information of 60East Technologies Inc.; (b) was not developed with
+// government funds; (c) is a trade secret of 60East Technologies Inc.
+// for all purposes of the Freedom of Information Act; and (d) is a
+// commercial item and thus, pursuant to Section 12.212 of the Federal
+// Acquisition Regulations (FAR) and DFAR Supplement Section 227.7202,
+// Government's use, duplication or disclosure of the computer software
+// is subject to the restrictions set forth by 60East Technologies Inc..
+//
+////////////////////////////////////////////////////////////////////////////
+
+#define PY_SSIZE_T_CLEAN 1
+#include <Python.h>
+#include <amps/ampsplusplus.hpp>
+#include <ampspy_types.hpp>
+#include <ampspy_defs.hpp>
+#include <amps/util.hpp>
+
+using namespace AMPS;
+namespace ampspy
+{
+  namespace versioninfo
+  {
+    AMPSDLL ampspy::ampspy_type_object versioninfo_type;
+
+    //    def __init__(self, initialCapacity):
+    static int _ctor(obj* self, PyObject* args, PyObject* kwds)
+    {
+      char* version = NULL;
+      self->pVersionInfo = NULL;
+      if (!PyArg_ParseTuple(args, "|s", &version))
+      {
+        return -1;
+      }
+      if (version)
+      {
+        self->pVersionInfo = new VersionInfo(version);
+      }
+      else
+      {
+        self->pVersionInfo = new VersionInfo();
+      }
+      return 0;
+    }
+
+    static void _dtor(obj* self)
+    {
+      delete self->pVersionInfo;
+      self->pVersionInfo = NULL;
+      shims::free(self);
+    }
+
+    //    def set_version(self, version)
+    static PyObject* set_version(obj* self, PyObject* args)
+    {
+      const char* version = NULL;
+      if (!PyArg_ParseTuple(args, "s", &version))
+      {
+        return NULL;
+      }
+      if (!version)
+      {
+        PyErr_SetString(PyExc_ValueError, "version must be a string.");
+        return NULL;
+      }
+      CALL_RETURN_NONE(self->pVersionInfo->setVersion(version));
+    }
+
+    //  def get_version_string(self)
+    static PyObject* get_version_string(obj* self)
+    {
+      CALL_RETURN_STRING(self->pVersionInfo->getVersionString());
+    }
+
+    //  def get_version_number(self)
+    static PyObject* get_version_number(obj* self)
+    {
+      CALL_RETURN_UINT64_T(self->pVersionInfo->getVersionUint64());
+    }
+
+    //  def get_old_style_version(self)
+    static PyObject* get_old_style_version(obj* self)
+    {
+      CALL_RETURN_SIZE_T(self->pVersionInfo->getOldStyleVersion());
+    }
+
+#if PY_MAJOR_VERSION < 3
+    //  def versioninfo_cmp(self, other)
+    static int versioninfo_cmp(obj* self, obj* other)
+    {
+      if (*(self->pVersionInfo) < * (other->pVersionInfo))
+      {
+        return -1;
+      }
+      else if (*(self->pVersionInfo) > *(other->pVersionInfo))
+      {
+        return 1;
+      }
+      else if (*(self->pVersionInfo) == *(other->pVersionInfo))
+      {
+        return 0;
+      }
+      // "A tp_compare handler may raise an exception. In this case it should
+      //  return a negative value. The caller has to test for an exception
+      //  using PyErr_Occurred()."
+      PyErr_SetString(PyExc_TypeError, "Comparison not allowed between these types.");
+      return -2;
+    }
+
+#else
+    //  def versioninfo_richcmp(self, other, op)
+    static PyObject* versioninfo_richcmp(obj* self, obj* other, int op)
+    {
+      switch (op)
+      {
+      case Py_LT: CALL_RETURN_BOOL(*(self->pVersionInfo) < * (other->pVersionInfo)); break;
+      case Py_LE: CALL_RETURN_BOOL(*(self->pVersionInfo) <= *(other->pVersionInfo)); break;
+      case Py_EQ: CALL_RETURN_BOOL(*(self->pVersionInfo) == *(other->pVersionInfo)); break;
+      case Py_NE: CALL_RETURN_BOOL(*(self->pVersionInfo) != *(other->pVersionInfo)); break;
+      case Py_GT: CALL_RETURN_BOOL(*(self->pVersionInfo) > *(other->pVersionInfo)); break;
+      case Py_GE: CALL_RETURN_BOOL(*(self->pVersionInfo) >= *(other->pVersionInfo)); break;
+      default: break;
+      }
+      PyErr_SetString(PyExc_TypeError, "Comparison not allowed between these types.");
+      return NULL;
+    }
+#endif
+
+    static PyObject* str(obj* self)
+    {
+      return get_version_string(self);
+    }
+
+    void add_types(PyObject* module_)
+    {
+      versioninfo_type.setName("AMPS.VersionInfo")
+      .setBasicSize(sizeof(obj))
+      .setDestructorFunction(_dtor)
+      .setConstructorFunction(_ctor)
+      .setBaseType()
+      .setReprFunction(str)
+      .setStrFunction(str)
+#if PY_MAJOR_VERSION < 3
+      .setCompareFunction(versioninfo_cmp)
+#else
+      .setRichCompareFunction(versioninfo_richcmp)
+#endif
+      .setDoc("AMPS VersionInfo Object")
+      .notCopyable()
+      .addMethod("set_version", set_version, "set_version(version)\n\nSets the string version to represent.\n")
+      .addMethod("get_version_string", get_version_string, "get_version_string()\n\nReturns the version string.\n")
+      .addMethod("get_version_number", get_version_number,
+                 "get_version_number()\n\nReturns the version as number with 4 digits for major version, 4 digits for minor version, 5 digits for maintenance version and 5 digits for patch version.\n")
+      .addMethod("get_old_style_version", get_old_style_version,
+                 "get_old_style_version()\n\nReturns the version as number with 2 digits for major version, 2 digits for minor version, 2 digits for maintenance version and 2 digits for patch version. Any values greater than 99 are represented as 99.\n")
+      .createType()
+      .registerType("VersionInfo", module_);
+    }
+
+  } // namespace versioninfo
+} // namespace ampspy

amps-python-client-5.3.4.1/PKG-INFO

@@ -1,112 +0,0 @@
-Metadata-Version: 2.1
-Name: amps-python-client
-Version: 5.3.4.1
-Summary: AMPS Python Client
-Home-page: https://crankuptheamps.com
-Maintainer: 60East Technologies, Incorporated
-Maintainer-email: support@crankuptheamps.com
-License: Commercial/Proprietary :: see LICENSE
-Platform: Linux
-Platform: Windows
-Classifier: License :: Other/Proprietary License
-Description-Content-Type: text/markdown
-License-File: LICENSE
-
-AMPS Python Client
-==================
-
-Introduction
-------------
-
-The AMPS Python Client is a Python extension module that makes it easy to connect to AMPS. This client builds upon the AMPS C++ Client and Python/C api to bring high performance AMPS connectivity to Python code.
-
-
-Prerequisites
--------------
-
-To use the AMPS Python Client, you must have the following software installed and configured on your system:
-
-* Python 2.7 or Python 3.5 and above.
-* Python distutils. Most python installations build and include this package by default, but you may run into issues building this extension module if distutils is not functioning properly on your system.
-  Python distutils may be packaged in a standalone package named 'python-distutils', or included in 'python-devel.x86_64'. You can also run the setup script available [here](http://peak.telecommunity.com/dist/ez_setup.py).
-* C++ compiler. gcc 4.4 or greater on Linux, or a verion of Visual Studio with Mainstream Support from Microsoft (please
-  refer to Microsoft product lifecycle policies) on Windows. Note that this must be the same compiler used to build your
-  python distribution, else python distutils may be unable to invoke your compiler.
-
-
-Fedora prerequisites:
-1. dnf install redhat-rpm-config
-2. dnf install python-devel  # for use with Python2
-3. dnf install python3-devel # for use with Python3
-4. dnf install gcc-c++
-
-Building From a Git Clone
--------------------------
-
-If you obtained this client by a git clone of the 60East amps-client-python repository, you also need to fetch the correct version of the 
-AMPS C++ client submodule. To do this, issue a git submodule command to initialize and update the src/cpp submodule. One easy
-way to do this is by issuing the command:
-
-    git submodule update --init
-
-which will initialize and update the submodule in one step. Note that working with submodules in git requires extra care. Visit
-[this chapter](http://git-scm.com/book/en/Git-Tools-Submodules) to learn more about git submodules.
-
-Build
------
-
-This client is distributed as source code and must be compiled before it is used. The build process emits a shared library
-(or DLL on Windows) that can be imported into your python application.
-
-### To build on Linux:
-
-1. Run `python setup.py build` from the AMPS Python Client directory to build the client.
-
-   This script uses Python distutils to build the client library. Python distutils provides many additional options for installing the built library into your Python distribution, or
-   otherwise controlling the output of the build process. Run `python setup.py --help` to view command help.
-
-2. Check under the `build` directory for `AMPS.so` -- this is the Python extension module. Ensure this library's directory is in your PYTHONPATH.
-
-3. To test, run `python -c "import AMPS"`.  If any errors occur importing the AMPS module, validate that the module built properly, and that the containing directory is in your PYTHONPATH.
-
-### To build on Windows:
-
-1. Use a Visual Studio Command Prompt to create a command prompt where the necessary Visual Studio environment variables are set for command line builds.
-
-2. Add the Python directory (the location of the python.exe interpreter) to your path.
-   *Note:* The platform of your python installation must match the target platform for this python module. If you want to
-   build a 64-bit module, you must set your PATH to a 64-bit Python installation; for a 32-bit module, you must set it to
-   a 32-bit installation. If you'd like to build both, you must do so separately, once with each Python installation.
-3. Run `python setup.py build` fom the AMPS Python Client directory to build the client module. Use the `-p win32` option to build a 32-bit client module.
-4. Check under the `build` directory for `AMPS.pyd` -- this is the Python extension module. Ensure this library's directory is in your PYTHONPATH.
-5. To test, run `python -c "import AMPS"`. If any errors occur importing the AMPS module, validate that the module built properly, and that the containing directory is in your PYTHONPATH.
-
-Installing the Python Binary Wheel
-----------------------------------
-
-60East also provides Linux-x86-64 and Windows 64-bit binary wheels built with Python 2.7 and for Python 3.x.
-These wheel files are provided on the 60East website.
-
-If your system is not Linux-x86-64, or you are not using Python 2.6, you can generate your own egg by running 'python setup.py bdist_wheel'.
-
-## Installing:
-
-1. Download the wheel file from the 60East client release page.
-
-2. run 'python -m pip install *.whl'.
-
-Troubleshooting Build Problems
-------------------------------
-
-Symptom: Python.h not found
-
-Resolution: Update or install python distutils. See the entry on python distutils in the prequisites section for information on installing this package.
-
-
-For More Information
---------------------
-
-The developer's guide and generated reference documentation for this client are available under the doc/ directory.
-
-
-

amps-python-client-5.3.4.1/docs/command-reference/html/.buildinfo

@@ -1,4 +0,0 @@
-# Sphinx build info version 1
-# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: 951caf5bd819336a64039cd238b22ebf
-tags: 645f666f9bcd5a90fca523b33c5a78b7

amps-python-client-5.3.4.1/docs/command-reference/html/_sources/chapters/ack-messages.rst.txt

@@ -1,32 +0,0 @@
-.. _#command-guide-ack-messages:
-
-Ack Messages
-=================
-
-AMPS provides information to the application and
-AMPS client about the status of commands using
-acknowledgement, or ``ack``, messages.
-
-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 *AMPS User Guide* chapter on
-acknowledgements and the *Developer Guide*
-for each client language for details.
-
-In some cases, an application may want additional
-information about the state of a command, and may
-request an ``ack`` 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 ``stats``
-(statistics) ``ack``, while setting the number
-of data messages to be returned to ``0`` (using
-the ``top_n=0`` option).
-
-This section describes the ``ack`` messages
-returned by AMPS.
-
-.. include:: ./ack-messages/ack.inc
-