# 8. Ack Messages

AMPS provides information to the application and AMPS client about the status of commands using acknowledgement, or `ack`, messages.

A command to AMPS must explicitly request acknowledgement to receive a response from AMPS. By default, the AMPS client libraries request acknowledgements as needed to detect failures: see the AMPS User Guide chapter on acknowledgements and the Developer Guide for each client language for details.

In some cases, an application may want additional information about the state of a command, and may request an `ack` explicitly. For example, an application may want to know how many records would be returned by a particular query. In that case, a common technique is to request a `stats` (statistics) `ack`, while setting the number of data messages to be returned to `0` (using the `top_n=0` option).

This section describes the `ack` messages returned by AMPS.

## ack message

The `ack` message returns status information from AMPS.

AMPS does not create `ack` messages unless an acknowledgment is specifically requested. The exact meaning and content of ack messages depends on the command the requests the message. AMPS supports the following types of ack messages with the general semantics described below.

ack Type | Meaning
--- | ---
`completed` | An operation has completed. For example, subscriptions that replay from the transaction log can produce a `completed` acknowledgment to indicate when transaction log replay has finished and further messages for the subscription are the result of new publishes.
`persisted` | Data has been persisted.
`processed` | AMPS has processed the command. Notice that, depending on the command, AMPS may not have executed the command when this acknowledgment is produced.
`received` | AMPS has received the command, but has not yet processed it.
`stats` | Statistics for the command. This acknowledgment is typically produced after the command has fully completed.

Types of ack message

### Common Header Fields For Ack Messages

Field | Description
--- | ---
`Command` | Type of message. Always `ack`, as encoded by the protocol.
`AckType` | The type of acknowledgment. One of `completed`, `persisted`, `processed`, `received` or `stats`.
`CommandId` | The `CommandId` that this ack refers to. Clients can use this field to correlate the `ack` returned with the command being acknowledged.
`Status` | The status of the command.
`Reason` | The reason for a `failure` status.

Header fields provided in ack

#### Additional fields for logon

When the `ack` message is produced in response to a `logon` command, the following additional header fields may be set:

Field | Description
--- | ---
`ClientName` | The name of the client provided with the command.
`SequenceId` | The last `SequenceId` persisted to the transaction log for this client, as identified by the `ClientName`.
`Bookmark` | The last bookmark from this client.
`UserId` | `UserId` to use when the status is retry.
`Password` | `Password` to use when the status is retry.
`Version` | The version of the AMPS server.

Additional ack headers for logon

#### Additional fields for publish and delta_publish

When the `ack` message is produced in response to a `publish` or `delta_publish` command, the following additional header fields may be set:

Field | Description
--- | ---
`SequenceId` | The last SequenceId persisted for this client.
`Bookmark` | The last Bookmark persisted for this client.

Additional ack headers for publish or delta_publish

#### Additional fields for subscribe and delta_subscribe

When the `ack` message is produced in response to a `subscribe` or `delta_subscribe` command, the following additional header fields may be set:

Field | Description
--- | ---
`SubId` | The `SubId` sent with the command, or the `SubId` generated by AMPS if no `SubId` was provided. This field is not returned in `processed` acks.
`Options` | Returned when the command is a `subscribe` to a queue. Contains the following options: `max_backlog` indicates the effective maximum backlog that the server has assigned for this subscription.
`Bookmark` | For a `completed` acknowledgement on a bookmark subscription, this indicates the point in the transaction log where the acknowledgement message was generated. Notice that the message that corresponds to this bookmark need not be a message matched by the subscription.

Additional ack headers for subscribe or delta_subscribe

#### Additional fields for unsubscribe

When the `ack` message is produced in response to a `unsubscribe`, AMPS does not provide additional header fields.

#### Additional fields for sow, sow_and_subscribe, sow_and_delta_subscribe

When the `ack` message is produced in response to a `sow`, `sow_and_subscribe`, or `sow_and_delta_subscribe`, the following additional header fields may be set:

Field | Description
--- | ---
`SubId` | The `SubId` sent with the sow command.
`QueryId` | The `QueryId` sent with the sow command.
`RecordsReturned` | The number of records returned by a SOW query. This header field is present on `stats` acknowledgments.
`TopicMatches` | The total number of records compared across all matching SOW topics. This header field is present on `stats` acknowledgments.
`Matches` | The number of records that match the topic regular expression and content filter. This header field is present on `stats` acknowledgments.

Additional ack headers for sow, sow_and_subscribe, sow_and_delta_subscribe

#### Additional fields for sow_delete

When the `ack` message is produced in response to a `sow_delete` the following additional header fields may be set:

Field | Description
--- | ---
`QueryId` | The `QueryId` sent with the `sow_delete` command.
`RecordsDeleted` | The number of records deleted by the command. This header field is present on `stats` acknowledgments.
`TopicMatches` | The total number of records compared across all matching SOW topics. This header field is present on `stats` acknowledgments.
`Matches` | The number of records that match the topic regular expression and content filter. This header field is present on `stats` acknowledgments.

Additional ack headers for sow_delete