Skip to main content

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

AMPS Header FieldAbbreviationName
ack_typeaAckType
passwordpwPassword
bookmarkbmBookmark
batch_sizebsBatchSize
client_nameClientName
cmdcCommand
cmd_idcidCommandId
correlation_idxCorrelationId
data_onlyDataOnly
expirationeExpiration
filterfFilter
gseqGroupSequenceNumber
heartbeatHeartbeat
leaseperiodlpLeasePeriod
matchesMatches
msg_lenlMsgLen
max_msgsMaximumMessages
optsoOpts
orderbyOrderBy
query_idQueryID
reasonReason
records_deletedRecordsDeleted
records_insertedRecordsInserted
records_returnedRecordsReturned
records_updatedRecordsUpdated
seqsSequence
send_emptySendEmpty
send_keysSendKeys
send_oofSendOutOfFocus
sow_keykSowKey
sow_keysSowKeys
statusStatus
sub_idSubscriptionId
sidsSubscriptionIds
srcSrc
timeout_intervalTimeoutInterval
timestamptsTransmissionTime
top_nTopNRecordsReturned
topic_matchesTopicMatches
topictTopic
use_nsUseNamespaces
user_idUserId
versionvVersion

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

NameTypeDefinition
AckTypestringAcknowledgment 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.
BookmarkstringA client-originated identifier used to mark a location in journaled messages.
ClientNamestring

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

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.

CorrelationIdstring, base64 encoded characters onlyOpaque token set by an application and returned with the message.
DataOnlyBoolean (true or false)If true, only send raw data to subscriber for a matching publish message, i.e. do not include FIX/NVFIX envelope.
Expirationinteger (seconds)SOW expiration time if used in publish.
Filterstring, should wrap in CDATAContent filter expression.
GracePeriodinteger (milliseconds)Grace period after heartbeat interval is exceeded before client is considered in error state.
GroupSequenceNumberintegerGroup Sequence Number returned with each batch message of a SOW response.
Heartbeat

One of:

  • start
  • stop
  • beat
Heartbeat command.
LeasePeriodtimestampFor 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.

MatchesintegerReturned in the acknowledgment to a SOW query that indicates number of matches.
MaximumMessagesinteger greater than zeroSpecifies the maximum number of messages within a batch publish.
MessageIDstring, e.g. MAMPS–XYZSet by AMPS engine to tag every incoming message.
MessageLengthintegerSent with messages that have data (a message body) to indicate the number of bytes in the message body.
MessageType

string

One of the configured message types in AMPS.

Message type.
MsgLenintegerSent with messages that have data (a message body) to indicate the number of bytes in the message body.
OptsstringA comma-delimited list of options on a specific command.
PasswordstringPassword used to authenticate with an AMPS server.
QueryIDstringSOW query identifier set by client to identify a query.
ReasonstringThe failure message that appears when an acknowledgment returns a status or failure.
RecordsDeletedintegerUsed in conjunction with the stats acknowledgment, this is the number of records deleted from the SOW with a sow_delete command.
RecordsInsertedintegerUsed in conjunction with the stats acknowledgment, this is the number of records inserted into the SOW.
RecordsUpdatedintegerUsed in conjunction with the stats acknowledgment, this is the number of records updated in the SOW.
RecordsReturnedintegerReturned in the acknowledgment to an SOW query that indicates number of records in the store.
SendEmptyBoolean (true or false); default is trueIf true, empty messages that are published will be forwarded to matching subscriptions.
SendKeysBoolean (true or false)Option to instruct AMPS that a client would like to receive the SowKey(s) back.
SendOutOfFocusBoolean (true or false)If true, Out of Focus messages are sent for the SOW query.
SendSubscriptionIDsBoolean (true or false)If false, subscription identifiers will not be sent for a matched message.
Sequenceinteger greater than zero

An integer that corresponds to the publish message sequence number.

For more information see the Replicating Messages Between Instances chapter in the AMPS 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.

SowKeyscomma-separated list of SowKey valuesComma-separated list of SowKey values.
Status

One of:

  • stopped
  • alive
  • timed out
  • error
Used to indicate client status when client is monitored for heartbeats.
SubscriptionIdstring, e.g. SAMPS-XYZThe subscription identifier set by server when processing a subscription.
SubscriptionIdsstringComma-separated list of SubIds sent from AMPS engine to identify which client subscriptions match a given publish message.
TimeoutIntervalintegerUsed in conjunction with the heartbeat interval to set the timeout interval for a publisher.
TopNRecordsReturnedunsigned 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.

TopicstringTopic
TopicMatchesintegerReturned in the acknowledgment to an SOW query that indicates number of topic matches.
TransmissionTimeISO-8601 date-timeTimestamp - Optionally set to time the message was processed by the server.
UseNamespacesBoolean (true or false)Use SOAP XML namespaces in all messages from the AMPS engine.
UserIdstringUsed to identify the user ID of a command.
VersionstringContains the version of the AMPS server.