10. 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.

FIX/NVFIX protocol

FIX/NVFIX Message Header - Sorted by Value

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

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

XML Message Header - Sorted by Name

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/JSON Protocol

AMPS Message Header - Sorted by Name

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

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
  • start_timer
  • stop_timer
  • 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.
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 one of: xml, fix, nvfix 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.