= Chronicle Queue Utilities
Neil Clifford
:toc: macro
:toclevels: 3
:css-signature: demo
:toc-placement: macro
:icons: font

toc::[]

This document describes Chronicle Queue utility programs that have been created to help in the maintenance of your Chronicle Queue environment.

== Chronicle Reader utility

Chronicle Reader allows you to specify a Chronicle Queue folder, and export the queue message data to text in standard output (`stdout`).

To run the Chronicle Reader utility using Maven:

[source, java]
....
$ mvn exec:java -Dexec.mainClass="net.openhft.chronicle.queue.ChronicleReaderMain"
....

You can specify arguments that tailor the way that the Chronicle Reader utility behaves. For example:

=== Command-line arguments
The following table lists the available command line option arguments:

.Command-line arguments

|===
|Argument |Description
|`-d`
|Mandatory. The directory containing the source Chronicle Queue files.
|`-i`
|Display data containing this regular expression.
|`-e`
|Do not display data containing this regular expression.
|`-f`
|Follow. Wait for new data to arrive.
|`-m`
|Show a maximum of this many messages from the end of the dataset.
|`-n`
|Start reading from this index point.
|`-r`
|For use when reading from a queue written to by a `MethodWriter`.
|`-h`
|Print this help and exit. +

The `-h` argument cannot be used in conjunction with other arguments.
|===

The Chronicle Reader main class is located at
https://github.com/OpenHFT/Chronicle-Queue/blob/ea/src/main/java/net/openhft/chronicle/queue/ChronicleReaderMain.java

=== Command-line examples

The following examples show how the option arguments can be used:

==== Export data from a queue

To write out the data from a queue that exists in `/data/queue`:

[source, java]
....
$ mvn exec:java -Dexec.mainClass="net.openhft.chronicle.queue.ChronicleReaderMain"  -Dexec.args="-d /data/queue"
....

==== Follow a queue

Following a queue ensures that the latest messages are written out to `Standard-Out`. It will wait, and append new messages as they arrive on the queue.

To follow a queue:

[source, java]
....
$ mvn exec:java -Dexec.mainClass="net.openhft.chronicle.queue.ChronicleReaderMain"  -Dexec.args="-d /data/queue -f"
....

==== Use regular expressions

To export data from a queue which includes only messages containing `USD`:

[source, java]
....
$ mvn exec:java -Dexec.mainClass="net.openhft.chronicle.queue.ChronicleReaderMain"  -Dexec.args="-d /data/queue -i USD"
....

To display records that contain certain string values: For example:

===== `USD`, *and* `CHI-X` (Include)
[source, java]
....
$ mvn exec:java -Dexec.mainClass="net.openhft.chronicle.queue.ChronicleReaderMain"  -Dexec.args="-d /data/queue -i USD" -i "CHI-X"
....

===== `USD`, *but not* `CHI-X` (Exclude)
[source, java]
....
$ mvn exec:java -Dexec.mainClass="net.openhft.chronicle.queue.ChronicleReaderMain"  -Dexec.args="-d /data/queue -i USD" -e "CHI-X"
....

==== Maximum message history

To export up to the last `1000` messages from a queue:

[source, java]
....
$ mvn exec:java -Dexec.mainClass="net.openhft.chronicle.queue.ChronicleReaderMain"  -Dexec.args="-d /data/queue -m 1000"
....

==== Index points

To follow a queue from the index point, `0x123ABE`:

[source, java]
....
$ mvn exec:java -Dexec.mainClass="net.openhft.chronicle.queue.ChronicleReaderMain"  -Dexec.args="-d /data/queue -f -n 0x123ABE"
....

==== Method Reader

When reading from a queue that has been created using a `MethodWriter`:

[source, java]
....
MethodWriterBuilder<StringEvents> methodWriterBuilder = excerptAppender.methodWriterBuilder(StringEvents.class);
StringEvents events = methodWriterBuilder.build();
events.say("hello");
....

Using `-r` will cause the reader to treat each event within a document excerpt as a single message for the purposes of applying regular expressions.

==== Help

To display the help documentation:

[source, java]
....
$ mvn exec:java -Dexec.mainClass="net.openhft.chronicle.queue.ChronicleReaderMain"  -Dexec.args="-h"
....

== Packaging

For convenience, this tool can be packaged for deployment to a server environment.

To create an archive `tar` file for deployment, run the following commands from the project root:

[source,bash]
....
$ ./bin/package_scripts.sh
Created /tmp/chronicle-queue-tools.tar
....

The resulting `tar` file can be copied to another location, and expanded.
Once unpacked, invoke the `queue_reader.sh` script in order to execute the
`InternalChronicleReader` utility:

[source,bash]
....
$ ./queue_reader.sh
Please specify the directory with -d

usage: ChronicleReaderMain [-d <directory>] [-e <exclude-regex>] [-f]
    [-h] [-i <include-regex>] [-m <max-history>] [-n <from-index>] [-r]
....

'''

<<../README.adoc#,Back to Chronicle Queue>>
