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¶
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:
|
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 A |
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. |