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

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

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

The following table describes how the headers in the `xml` protocol are processed by AMPS.

### 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 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 | `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: `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.