.. _#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.

