AMPS Protocol
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 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
MsgLen
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).
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 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.
MsgLen
integer
Sent with messages that have data (a message body) to indicate the number of bytes in the message body.
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
or 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 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.
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.
Last updated