AGNT Chunk

See more on Chunks in general.

This identfies an “agent”, used to identify the creator of the archive, especially for purposes of recognizing the meanings of user-defined chunks.

Any portion file in a multi-part archive that contains user-defined or experimental chunks must have a AGNT or AGNT-nd chunk in the same file to register the usage of non-standard chunks.

AGNT Chunk structure

Flags

Flagusage
r (range of instances) all used in the general manner.
p (multi-part) & c
y (payload specification)
i (instance sizes) Set when r and b are used and Subtype == 1
Clear otherwise.
b (subtype) AGNT has both plain and subtyped forms. See below.
a (correlated) Cleared.
n (pointer) AGNT-nd has a distinct meaning, documented below.
d (redundant)

Subtype

The Subtype is assigned as follows:

Subtypemeaning
absentOriginal Creator of the Archive
0Updated the Archive
1Uses User-Defined chunks

Payload Specification

The decryption value of hex 44 (specify reserved COMP#68) is especially designed to compress AGNT chunks holding agent names (not Subtype 1).

However, any payload specification may be used, provided it does not involve any user-defined or experimental chunks.

Instance Number

When the Subtype is absent, the Instance Number must be 0. There is only one instance per archive file (in a multi-part archive, each portion file can have its own).

For Subtypes 0 and 1, a unique non-zero Instance Number is used. If present, the Instance Number on a Subtype 1 (user-defined chuck registration) is associated with the same Instance Number on the Subtype 0 (agent who updated the archive) chunk.

AGNT Chunk Payload

The Payload contains a string that identifies the program or “agent” that wrote to the archive, and/or a list of any user-defined or experimental chunks that were written to.

The AGNT#0 (no subtype) is used only by the original creator of the archive, and is not changed. It contains an lpstring for the agent ID, followed by any chunk IDs (may be empty), both explained below.

The Subtype 0 chunks contain an agent ID only.

The Subtype 1 chunks contain list of chunk IDs only.

The agent and chunk information is separated out because the chunk ID list is rare, and by not having it the chunk does not need the i (instance sizes field is present) flag and its associated list of lengths.

Agent ID

The Agent ID is an lpstring naming the program, library, component, or otherwise the “agent” responsible for composing and encoding the chunks in the file.

The identification string shall not begin or end with a space or other non-printing character. Creative use of spaces or non-spacing characters within the string is discouraged.

The identification string should identify the program (or underlying library) and version, in a simple manner. Every use of the identification string should be binary identical, so programs can match against it if it becomes necessary to test for a particular program.

Insignificant Text

The string can contain parts that are not to be used in the matching, by enclosing it in parenthesis. Before matching the strings, delete everything inside parenthesis. For example, “Great Library (English)” is a match against “Great Library (French)”.

Version Numbering

The string ought to contain a version number, too. That version number should be contained within square brackets (“[]”) so it can be easily parsed out in a consistent manner. Furthermore, updates to the program, library or whatever the “agent” is should leave the non-version text the same.

So, “Great Library [1.3]” and “Great Library [1.4]” are recognized as being different versions of the same agent.

It is recommended that the version number conform to the general form described in Ordered Comparison of Version Strings so that strings may be compared as greater/less in a known consistent manner.

Chunk ID list

All user-defined or experimental chunks (anything with the u or x flags) must be listed here. Nothing else may be listed.

Each Chunk ID is the 2-byte Type tag of the chunk being declared, followed by the Subtype (if the b flag is used) and Experimental ID (if the x flag is used).

Concatenate one or more Chunk IDs together to form the payload of a Subtype 1 AGNT chunk, or the rest of a plain AGNT#0 chunk after the lpstring.

Usage Notes

Too long?!

A way of compressing the Agent ID text is not part of this chunk’s specification. That is, it doesn’t use special codes for known agent names. Rather, the general mechanism of a Payload Specification is used, to add compression as a separate step. This means that the underlying technology can be reused for other chunks including DATA, and the description of how to handle the Agent ID text is uncluttered with these details.

A programmer can register his Agent ID name and then the use of COMP#68 will replace that known string with 2 bytes.

Comparing IDs

∴Link to a page describing the comparison algorithm in detail (e.g. code example).

Updating using the Same Agent

An existing record may be updated (with more user-defined chunk names) or left alone if the same program modifies the archive more than once—don’t list the same program more than once.

Examples

∴Need examples of AGNT#0 with Chunk ID list, correlating subtype 1 and 0.

COMP-nd Chunk

A part number, as with DATA.


Valid HTML 4.01!

Page content copyright 2003 by John M. Dlugosz. Home:http://www.dlugosz.com, email:mailto:john@dlugosz.com