amps-python-client 5.3.4.1__zip

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

@@ -0,0 +1,1474 @@
+.. _#command-ref-protocol:
+
+
+Protocol Reference
+========================
+
+This section contains information on how different protocols represent
+AMPS headers. The AMPS clients handle constructing and parsing AMPS
+headers. However, understanding the format of command can be useful when
+inspecting trace level logs or network traffic captures.
+
+
+.. warning::
+
+   The ``amps`` protocol is the recommended protocol for
+   all application development. The other
+   protocols are included for legacy compatibilty. While they
+   will remain supported for their current functionality,
+   the legacy protocols will not be enhanced further. These protocols
+   have limitations in current versions of AMPS, and future features
+   of AMPS may require the ``amps`` protocol.
+
+   (Notice that websocket connections use the websocket transport
+   framing, but interact with AMPS using the ``amps`` protoco.)
+
+
+
+FIX/NVFIX Protocol
+------------------
+
+The following table describes how the headers in
+the ``fix`` and ``nvfix`` protocols are processed
+by AMPS.
+
+FIX/NVFIX Message Header - Sorted by Value
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. list-table:: 
+     :header-rows: 1
+
+     * - **FIX/NVFIX Header Field**
+
+       - **Name**
+
+     * - 20000
+
+       - ``Command``
+
+     * - 20001
+
+       - ``CommandId``
+
+     * - 20002
+
+       - ``ClientName``
+
+     * - 20003
+
+       - ``UserId``
+
+     * - 20004
+
+       - ``TransmissionTime``
+
+     * - 20005
+
+       - ``Topic``
+
+     * - 20006
+
+       - ``Filter``
+
+     * - 20007
+
+       - ``MessageType``
+
+     * - 20008
+
+       - ``AckType``
+
+     * - 20009
+
+       - ``SubscriptionId``
+
+     * - 20011
+
+       - ``Version``
+
+     * - 20012
+
+       - ``Expiration``
+
+     * - 20013
+
+       - ``SendSubscriptionIDs``
+
+     * - 20014
+
+       - ``DataOnly``
+
+     * - 20015
+
+       - ``Heartbeat``
+
+     * - 20016
+
+       - ``TimeoutInterval``
+
+     * - 20017
+
+       - ``LeasePeriod``
+
+     * - 20018
+
+       - ``Status``
+
+     * - 20019
+
+       - ``QueryID``
+
+     * - 20020
+
+       - ``SendOutOfFocus``
+
+     * - 20021
+
+       - ``LogLevel``
+
+     * - 20022
+
+       - ``UseNamespaces``
+
+     * - 20023
+
+       - ``BatchSize``
+
+     * - 20025
+
+       - ``TopNRecordsReturned``
+
+     * - 20029
+
+       - ``SendEmpty``
+
+     * - 20031
+
+       - ``MaximumMessages``
+
+     * - 20032
+
+       - ``SowKeys``
+
+     * - 20033
+
+       - ``SendKeys``
+
+     * - 20034
+
+       - ``Src``
+
+     * - 20035
+
+       - ``CorrelationId``
+
+     * - 20036
+
+       - ``Sequence``
+
+     * - 20037
+
+       - ``Bookmark``
+
+     * - 20038
+
+       - ``Password``
+
+     * - 20039
+
+       - ``Options``
+
+     * - 20052
+
+       - ``RecordsInserted``
+
+     * - 20053
+
+       - ``RecordsUpdated``
+
+     * - 20054
+
+       - ``RecordsDeleted``
+
+     * - 20055
+
+       - ``RecordsReturned``
+
+     * - 20056
+
+       - ``TopicMatches``
+
+     * - 20057
+
+       - ``Matches``
+
+     * - 20058
+
+       - ``MessageLength``
+
+     * - 20059
+
+       - ``SowKey``
+
+     * - 20060
+
+       - ``GroupSequenceNumber``
+
+     * - 20061
+
+       - ``SubscriptionIds``
+
+     * - 20062
+
+       - ``Reason``
+
+     * - 20063
+
+       - ``MessageID``
+
+     * - 20074
+
+       - ``CorrelationID``
+
+
+FIX/NVFIX Message Header - Sorted by Name
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. list-table:: 
+     :header-rows: 1
+
+     * - **FIX/NVFIX Header Field**
+
+       - **Name**
+
+     * - 20008
+
+       - ``AckTyp``
+
+     * - 20037
+
+       - ``BkMrk``
+
+     * - 20023
+
+       - ``BtchSz``
+
+     * - 20002
+
+       - ``ClntName``
+
+     * - 20000
+
+       - ``Cmd``
+
+     * - 20001
+
+       - ``CmdId``
+
+     * - 20035
+
+       - ``CorrelationId``
+
+     * - 20014
+
+       - ``DatOnly``
+
+     * - 20012
+
+       - ``Expn``
+
+     * - 20006
+
+       - ``Fltr``
+
+     * - 20017
+
+       - ``GrcPrd``
+
+     * - 20060
+
+       - ``GrpSqNum``
+
+     * - 20015
+
+       - ``Hrtbt``
+
+     * - 20017
+
+       - ``LeasePeriod``
+
+     * - 20021
+
+       - ``LogLvl``
+
+     * - 20057
+
+       - ``Matches``
+
+     * - 20063
+
+       - ``MsgId``
+
+     * - 20058
+
+       - ``MsgLen``
+
+     * - 20007
+
+       - ``MsgTyp``
+
+     * - 20031
+
+       - ``MxMsgs``
+
+     * - 20039
+
+       - ``Opts``
+
+     * - 20038
+
+       - ``PW``
+
+     * - 20019
+
+       - ``Qld``
+
+     * - 20062
+
+       - ``Reason``
+
+     * - 20054
+
+       - ``RecordsDeleted``
+
+     * - 20053
+
+       - ``RecordsInserted``
+
+     * - 20055
+
+       - ``RecordsReturned``
+
+     * - 20036
+
+       - ``Seq``
+
+     * - 20029
+
+       - ``SndEmpty``
+
+     * - 20033
+
+       - ``SndKeys``
+
+     * - 20020
+
+       - ``SndOOF``
+
+     * - 20013
+
+       - ``SndSubIds``
+
+     * - 20059
+
+       - ``SowKey``
+
+     * - 20032
+
+       - ``SowKeys``
+
+     * - 20034
+
+       - ``Src``
+
+     * - 20018
+
+       - ``Status``
+
+     * - 20009
+
+       - ``SubId``
+
+     * - 20061
+
+       - ``SubIds``
+
+     * - 20016
+
+       - ``TmIntvl``
+
+     * - 20025
+
+       - ``TopN``
+
+     * - 20056
+
+       - ``TopicMatches``
+
+     * - 20005
+
+       - ``Tpc``
+
+     * - 20004
+
+       - ``TxmTm``
+
+     * - 20022
+
+       - ``UseNs``
+
+     * - 20003
+
+       - ``UsrId``
+
+
+XML Protocol
+------------
+
+The following table describes how the headers in
+the ``xml`` protocol are processed
+by AMPS.
+
+XML Message Header - Sorted by Name
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. list-table:: 
+     :header-rows: 1
+
+     * - **XML Header Field**
+
+       - **Name**
+
+     * - AckTyp
+
+       - ``AckType``
+
+     * - BkMrk
+
+       - ``Bookmark``
+
+     * - BtchSz
+
+       - ``BatchSize``
+
+     * - ClntName
+
+       - ``ClientName``
+
+     * - Cmd
+
+       - ``Command``
+
+     * - CmdId
+
+       - ``CommandId``
+
+     * - DatOnly
+
+       - ``DataOnly``
+
+     * - Expn
+
+       - ``Expiration``
+
+     * - Fltr
+
+       - ``Filter``
+
+     * - GrcPrd
+
+       - ``GracePeriod``
+
+     * - GrpSqNum
+
+       - ``GroupSequenceNumber``
+
+     * - Hrtbt
+
+       - ``Heartbeat``
+
+     * - LeasePeriod
+
+       - ``LeasePeriod``
+
+     * - LogLvl
+
+       - ``LogLevel``
+
+     * - Matches
+
+       - ``Matches``
+
+     * - MsgId
+
+       - ``MessageID``
+
+     * - MsgLen
+
+       - ``MessageLength``
+
+     * - MsgTyp
+
+       - ``MessageType``
+
+     * - MxMsgs
+
+       - ``MaximumMessages``
+
+     * - Opts
+
+       - ``Opts``
+
+     * - PW
+
+       - ``Password``
+
+     * - QId
+
+       - ``QueryID``
+
+     * - Reason
+
+       - ``Reason``
+
+     * - RecordsDeleted
+
+       - ``RecordsDeleted``
+
+     * - RecordsReturned
+
+       - ``RecordsReturned``
+
+     * - Seq
+
+       - ``Sequence``
+
+     * - SndEmpty
+
+       - ``SendEmpty``
+
+     * - SndKeys
+
+       - ``SendKeys``
+
+     * - SndOOF
+
+       - ``SendOutOfFocus``
+
+     * - SndSubIds
+
+       - ``SendSubscriptionIDs``
+
+     * - SowKey
+
+       - ``SowKey``
+
+     * - SowKeys
+
+       - ``SowKeys``
+
+     * - Status
+
+       - ``Status``
+
+     * - SubId
+
+       - ``SubscriptionId``
+
+     * - SubIds
+
+       - ``SubscriptionIds``
+
+     * - TmIntvl
+
+       - ``TimeoutInterval``
+
+     * - TopN
+
+       - ``TopNRecordsReturned``
+
+     * - TopicMatches
+
+       - ``TopicMatches``
+
+     * - Tpc
+
+       - ``Topic``
+
+     * - TxmTm
+
+       - ``TransmissionTime``
+
+     * - UseNS
+
+       - ``UseNamespaces``
+
+     * - UsrId
+
+       - ``UserId``
+
+
+AMPS Protocol
+------------------
+
+The following table describes how the headers in
+the ``amps`` protocol are processed
+by AMPS.
+
+Current releases of AMPS use a simplified
+JSON-like syntax for the ``amps`` protocol.
+
+AMPS Message Header - Sorted by Name
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. list-table:: 
+     :header-rows: 1
+
+     * - **AMPS Header Field**
+
+       - **Abbreviation**
+
+       - **Name**
+
+     * - ack\_type
+
+       - a
+
+       - ``AckType``
+
+     * - password
+
+       - pw
+
+       - ``Password``
+
+     * - bookmark
+
+       - bm
+
+       - ``Bookmark``
+
+     * - batch\_size
+
+       - bs
+
+       - ``BatchSize``
+
+     * - client\_name
+
+       - 
+
+       - ``ClientName``
+
+     * - cmd
+
+       - c
+
+       - ``Command``
+
+     * - cmd\_id
+
+       - cid
+
+       - ``CommandId``
+
+     * - correlation\_id
+
+       - x
+
+       - ``CorrelationId``
+
+     * - data\_only
+
+       - 
+
+       - ``DataOnly``
+
+     * - expiration
+
+       - e
+
+       - ``Expiration``
+
+     * - filter
+
+       - f
+
+       - ``Filter``
+
+     * - gseq
+
+       - 
+
+       - ``GroupSequenceNumber``
+
+     * - heartbeat
+
+       - 
+
+       - ``Heartbeat``
+
+     * - leaseperiod
+
+       - lp
+
+       - ``LeasePeriod``
+
+     * - matches
+
+       - 
+
+       - ``Matches``
+
+     * - msg\_len
+
+       - l
+
+       - ``MessageLength``
+
+     * - max\_msgs
+
+       - 
+
+       - ``MaximumMessages``
+
+     * - opts
+
+       - o
+
+       - ``Opts``
+
+     * - orderby
+
+       - 
+
+       - ``OrderBy``
+
+     * - query\_id
+
+       - 
+
+       - ``QueryID``
+
+     * - reason
+
+       - 
+
+       - ``Reason``
+
+     * - records\_deleted
+
+       - 
+
+       - ``RecordsDeleted``
+
+     * - records\_inserted
+
+       - 
+
+       - ``RecordsInserted``
+
+     * - records\_returned
+
+       - 
+
+       - ``RecordsReturned``
+
+     * - records\_updated
+
+       - 
+
+       - ``RecordsUpdated``
+
+     * - seq
+
+       - s
+
+       - ``Sequence``
+
+     * - send\_empty
+
+       - 
+
+       - ``SendEmpty``
+
+     * - send\_keys
+
+       - 
+
+       - ``SendKeys``
+
+     * - send\_oof
+
+       - 
+
+       - ``SendOutOfFocus``
+
+     * - sow\_key
+
+       - k
+
+       - ``SowKey``
+
+     * - sow\_keys
+
+       - 
+
+       - ``SowKeys``
+
+     * - status
+
+       - 
+
+       - ``Status``
+
+     * - sub\_id
+
+       - 
+
+       - ``SubscriptionId``
+
+     * - sids
+
+       - 
+
+       - ``SubscriptionIds``
+
+     * - src
+
+       - 
+
+       - ``Src``
+
+     * - timeout\_interval
+
+       - 
+
+       - ``TimeoutInterval``
+
+     * - timestamp
+
+       - ts
+
+       - ``TransmissionTime``
+
+     * - top\_n
+
+       - 
+
+       - ``TopNRecordsReturned``
+
+     * - topic\_matches
+
+       - 
+
+       - ``TopicMatches``
+
+     * - topic
+
+       - t
+
+       - ``Topic``
+
+     * - use\_ns
+
+       - 
+
+       - ``UseNamespaces``
+
+     * - user\_id
+
+       - 
+
+       - ``UserId``
+
+     * - version
+
+       - v
+
+       - ``Version``
+
+
+Header Fields - Reference
+-------------------------
+
+This section provides a reference to the header fields that have been used in
+AMPS messages. Not all headers are present on all outgoing messages, and not
+all headers are processed on incoming commands. See the detailed message
+descriptions in this guide for descriptions of which fields are used on
+a given command or a given response from AMPS. Further, although this
+table lists the header fields defined in every protocol, current versions
+of AMPS may not use every header defined in this table (see the detailed
+message descriptions for which fields are relevant for a given command or
+response).
+
+.. list-table:: 
+     :header-rows: 1
+
+     * - **Name**
+
+       - **Type**
+
+       - **Definition**
+
+     * - ``AckType``
+         
+
+       - string
+         
+
+       - Acknowledgment type for
+         the given command.
+
+     * - ``BatchSize``
+         
+
+       - Integer. Default is 1
+         when not present.
+         
+
+       - Specifies the number of
+         messages that are
+         batched together when
+         returning a query
+         result.
+
+     * - ``Bookmark``
+         
+
+       - string
+         
+
+       - A client-originated
+         identifier used to mark
+         a location in journaled
+         messages.
+
+     * - ``ClientName``
+         
+
+       - string
+         
+
+       - Used to identify a
+         client. Useful for
+         publishers that wish to
+         identify the source of a
+         publish, client status
+         messages and for client
+         heartbeats. Can be set
+         with ``logon`` command.
+
+     * - ``Command``
+         
+
+       - One of:
+         
+         -  ``publish``
+         
+         -  ``subscribe``
+         
+         -  ``sow``
+         
+         -  ``sow_and_subscribe``
+         
+         -  ``sow_delete``
+         
+         -  ``unsubscribe``
+         
+         -  ``flush``
+         
+         -  ``heartbeat``
+         
+         -  ``logon``
+
+       - Command to be executed.
+         
+
+     * - ``CommandId``
+         
+
+       - string
+         
+
+       - Client-specified command
+         id. The ``CmdId`` is
+         returned by the engine
+         in responses to commands
+         to allow the client to
+         correlate the response
+         to the command.
+
+     * - ``CorrelationId``
+         
+
+       - string, base64 encoded
+         characters only
+         
+
+       - Opaque token set by an
+         application and returned
+         with the message.
+
+     * - ``DataOnly``
+         
+
+       - Boolean (``true`` or
+         ``false``)
+         
+
+       - If ``true``, only send
+         raw data to subscriber
+         for a matching publish
+         message, i.e. do not
+         include FIX/NVFIX
+         envelope.
+
+     * - ``Expiration``
+         
+
+       - integer (seconds)
+         
+
+       - SOW expiration time if
+         used in ``publish``.
+
+     * - ``Filter``
+         
+
+       - string, should wrap in
+         CDATA
+
+       - Content filter
+         expression.
+
+     * - ``GracePeriod``
+         
+
+       - integer (milliseconds)
+         
+
+       - Grace period after
+         heartbeat interval is
+         exceeded before client
+         is considered in error
+         state.
+
+     * - ``GroupSequenceNumber``
+         
+
+       - integer
+         
+
+       - Group Sequence Number
+         returned with each batch
+         message of a SOW
+         response.
+
+     * - ``Heartbeat``
+         
+
+       - one of: ``start``,
+         ``stop``, ``beat``
+
+       - Heartbeat command.
+         
+
+     * - ``LeasePeriod``
+         
+
+       - timestamp
+         
+
+       - For messages from a
+         queue, the time at which
+         the lease expires.
+
+     * - ``LogLevel``
+         
+
+       - one of: ``info``,
+         ``none``
+         
+
+       - Set the log level.
+         
+         *Deprecated*
+         
+         Not used in current versions
+         of AMPS.
+
+     * - ``Matches``
+         
+
+       - integer
+         
+
+       - Returned in the
+         acknowledgment to a SOW
+         query that indicates
+         number of matches.
+
+     * - ``MaximumMessages``
+         
+
+       - integer greater than
+         zero
+         
+
+       - Specifies the maximum
+         number of messages
+         within a batch publish.
+
+     * - ``MessageID``
+         
+
+       - string, e.g.
+         ``MAMPS–XYZ``
+         
+
+       - Set by AMPS engine to
+         tag every incoming
+         message.
+
+     * - ``MessageLength``
+         
+
+       - integer
+         
+
+       - Sent with XML formatted
+         message data to indicate
+         the number of bytes used
+         by the message body.
+
+     * - ``MessageType``
+         
+
+       - string
+         
+         one of the configured message
+         types in AMPS
+
+       - Message type.
+         
+
+     * - ``Opts``
+         
+
+       - string
+         
+
+       - A comma-delimited list
+         of options on a specific
+         command.
+
+     * - ``Password``
+         
+
+       - string
+         
+
+       - Password used to
+         authenticate with an
+         AMPS server.
+
+     * - ``QueryID``
+         
+
+       - string
+         
+
+       - SOW Query identifier set
+         by client to identify a
+         query.
+
+     * - ``Reason``
+         
+
+       - string
+         
+
+       - The failure message that
+         appears when an
+         acknowledgment returns
+         a ``status`` of
+         ``failure``.
+
+     * - ``RecordsDeleted``
+         
+
+       - integer
+         
+
+       - Used in conjunction with
+         the ``stats``
+         acknowledgment, this is
+         the number of records
+         deleted from the SOW
+         with a ``sow_delete``
+         command.
+
+     * - ``RecordsInserted``
+         
+
+       - integer
+         
+
+       - Used in conjunction with
+         the ``stats``
+         acknowledgment, this is
+         the number of records
+         inserted into the SOW.
+
+     * - ``RecordsUpdated``
+         
+
+       - integer
+         
+
+       - Used in conjunction with
+         the ``stats``
+         acknowledgment, this is
+         the number of records
+         updated in the SOW.
+
+     * - ``RecordsReturned``
+         
+
+       - integer
+         
+
+       - Returned in the
+         acknowledgment to an
+         SOW query that indicates
+         number of records in the
+         store.
+
+     * - ``SendEmpty``
+         
+
+       - Boolean (``true`` or
+         ``false``); default is
+         ``true``
+         
+
+       - If ``true``, empty
+         messages that are
+         published will be
+         forwarded to matching
+         subscriptions.
+
+     * - ``SendKeys``
+         
+
+       - Boolean (``true`` or
+         ``false``)
+         
+
+       - Option to instruct AMPS
+         that a client would like
+         to receive the SowKey(s)
+         back.
+
+     * - ``SendOutOfFocus``
+         
+
+       - Boolean (``true`` or
+         ``false``)
+         
+
+       - If ``true``,
+         Out-of-Focus messages
+         are sent for the SOW
+         query.
+
+     * - ``SendSubscriptionIDs``
+         
+
+       - Boolean (``true`` or
+         ``false``)
+         
+
+       - If ``false``,
+         subscription identifiers
+         will not be sent for a
+         matched message.
+
+     * - ``Sequence``
+         
+
+       - integer greater than
+         zero
+         
+
+       - An integer that
+         corresponds to the
+         publish message sequence
+         number. For more
+         information see the
+         Replication section in
+         the User Guide.
+
+     * - ``SowKey``
+         
+
+       - string containing the
+         digits of an unsigned
+         long for AMPS-generated
+         SOW keys
+         
+         arbitrary string in the
+         base64 character set for
+         user-provided SOW keys
+         
+
+       - A ``SowKey`` will
+         accompany each message
+         returned in an SOW
+         batch. A ``SowKey`` may
+         also be added to
+         messages coming in on a
+         subscription when the
+         published message
+         matches a record in the
+         SOW.
+         
+         A ``publish`` command
+         may contain a SOW key if
+         the SOW for the topic is
+         configured to accept
+         user-provided SOW keys.
+
+     * - ``SowKeys``
+         
+
+       - comma-separated list of
+         ``SowKey`` values
+
+       - Comma-separated list of
+         ``SowKey`` values.
+
+     * - ``Status``
+         
+
+       - one of: ``stopped``,
+         ``alive``,
+         ``timed out``, ``error``
+         
+
+       - Used to indicate client
+         status when client is
+         monitored for
+         heartbeats.
+
+     * - ``SubscriptionId``
+         
+
+       - string, e.g.
+         ``SAMPS-XYZ``
+         
+
+       - The subscription
+         identifier set by server
+         when processing a
+         subscription.
+
+     * - ``SubscriptionIds``
+         
+
+       - string
+         
+
+       - Comma-separated list of
+         ``SubIds`` sent from
+         AMPS engine to identify
+         which client
+         subscriptions match a
+         given publish message.
+
+     * - ``TimeoutInterval``
+         
+
+       - integer
+         
+
+       - Used in conjunction with
+         the heartbeat interval
+         to set the timeout
+         interval for a
+         publisher.
+
+     * - ``TopNRecordsReturned``
+         
+
+       - unsigned integer
+         
+
+       - The number of records to
+         return. Note: If
+         ``TopN`` is not equally
+         divisible by the
+         ``BtchSz``, then more
+         records will be returned
+         so that the total number
+         of records is equally
+         divisible by the
+         ``BtchSz`` setting.
+
+     * - ``Topic``
+
+       - string
+
+       - Topic
+
+     * - ``TopicMatches``
+         
+
+       - integer
+         
+
+       - Returned in the
+         acknowledgment to an
+         SOW query that indicates
+         number of topic matches.
+
+     * - ``TransmissionTime``
+         
+
+       - ISO-8601 date-time
+         
+
+       - Timestamp: optionally
+         set to time the message
+         was processed by the server.
+
+     * - ``UseNamespaces``
+         
+
+       - Boolean (``true`` or
+         ``false``)
+         
+
+       - Use SOAP XML namespaces
+         in all messages from the
+         AMPS engine.
+
+     * - ``UserId``
+         
+
+       - string
+         
+
+       - Used to identify the
+         user id of a command.
+
+     * - ``Version``
+         
+
+       - string
+         
+
+       - Contains the version of
+         the AMPS server.
+