Repeating Group API

There is API for Repeating Group in FIX Antenna .NET Core. It allows to create, remove and modify Repeating Groups and their entries.

Indexing Repeating Group

To use the Repeating Group API, you can pass the FixMessage instance to static method RawFixUtil.IndexRepeatingGroup(). There are four implementations of this method:

Indexes Repeating Group according to FIX dictionary. Dictionary version and message type selects by passed arguments.
```
FixMessage IndexRepeatingGroup(FixMessage msg, FixVersion version, string msgType, bool validation)
```
Indexes Repeating Group according to FIX dictionary. Dictionary version and message type selects by passed arguments and validation is turn off.
```
FixMessage IndexRepeatingGroup(FixMessage msg, FixVersion version, string msgType)
```
Indexes Repeating Group according to FIX dictionary. FIX version and message type extracted from message.
```
FixMessage IndexRepeatingGroup(FixMessage msg, bool validation)
```
Indexes Repeating Group according to FIX dictionary. FIX version and message type extracted from message and validation turned off.
```
FixMessage IndexRepeatingGroup(FixMessage msg)
```

All methods return the passed message. If you try to work with Repeating Group API without calling RawFixUtil.IndexRepeatingGroup(), method IndexRepeatingGroup(FixMessage msg) will be implicitly called, so you get indexed message with turned off validation.

Working with Repeating Groups through API

There are two classes for working with Repeating Group through api: RepeatingGroup and RepeatingGroup.Entry. RepeatingGroup contains methods for managing entries of Repeating Group. Entry contains methods for managing tags in specific entry of RepeatingGroup and sub groups. By default, FIX Antenna uses instances of RepeatingGroup and RepeatingGroup.Entry from internal pool to reduce garbage production.

Repeating Group Pool

The first thing that you should know about Repeating Group API is pooling. Remember simple rule: if you got RepeatingGroup or Entry instance by calling method that returns instance of group or entry, then there is no need in group.Release() / entry.Release(): all groups and entries will come back to pool after the call of msg.ReleaseInstance(). In other case, if you get group or entry by an explicit call of RepeatingGroupPool.GetEntry() / GetRepeatingGroup() you should explicitly return group/entry object to pool by Release method call.

Get Repeating Group

There are two ways to get Repeating Group from indexed message:

Don't forget about msg.ReleaseInstance()! If you don't call this method it may cause unnecessary object creation.

FixMessage msg = RawFixUtil.GetFixMessage(executionReport.GetBytes());
msg = RawFixUtil.IndexRepeatingGroup(msg, true);

RepeatingGroup group = msg.GetRepeatingGroup(555); //Leading tag of Repeating Group
//Some operations
msg.ReleaseInstance();

In this case FixMessage filling passed group by information about group content.

FixMessage msg = RawFixUtil.GetFixMessage(executionReport.GetBytes());
msg = RawFixUtil.IndexRepeatingGroup(msg, true);
RepeatingGroup group = RepeatingGroupPool.GetRepeatingGroup(); // Or new RepeatingGroup() or something else
msg.GetRepeatingGroup(555, group); // Leading tag of Repeating Group
//Some operations
group.Release();

If you try to get non-existent group, you get exception (if you call void method) or null value (if you call method which returns RepeatingGroup instance). There are safe methods (GetOrAddRepeatingGroup()) which adds repeating group if it's doesn't exist.

Get Entry

After you get RepeatingGroup instance, you can get entries of this group. There are also two ways to get it:

Don't forget about msg.ReleaseInstance() ! If you don't call this method, it may cause unnecessary object creation.

FixMessage msg = RawFixUtil.GetFixMessage(executionReport.GetBytes());
msg = RawFixUtil.IndexRepeatingGroup(msg, true);

RepeatingGroup group = msg.GetRepeatingGroup(555); //Leading tag of Repeating Group
RepeatingGroup.Entry entry = group.GetEntry(0); //Number of entry in group
//Some operations
msg.ReleaseInstance();

In this case FixMessage filling passed entry by information about entry content.

FixMessage msg = RawFixUtil.GetFixMessage(executionReport.GetBytes());
msg = RawFixUtil.IndexRepeatingGroup(msg, true);
RepeatingGroup group = RepeatingGroupPool.GetRepeatingGroup(); // Or new RepeatingGroup() or something else
RepeatingGroup.Entry entry = RepeatingGroupPool.GetEntry();
msg.GetRepeatingGroup(555, group); // Leading tag of Repeating Group
group.GetEntry(0, entry); //Number of entry in group
//Some operations
entry.Release();
group.Release();

Get nested group

You can get nested group using method Entry.GetGroup():

FixMessage msg = RawFixUtil.GetFixMessage(executionReport.GetBytes());
msg = RawFixUtil.IndexRepeatingGroup(msg, true);
RepeatingGroup group = RepeatingGroupPool.GetRepeatingGroup(); // Or new RepeatingGroup() or something else
RepeatingGroup.Entry entry = RepeatingGroupPool.GetEntry();
msg.GetRepeatingGroup(555, group); // Leading tag of Repeating Group
group.GetEntry(0, entry); //Number of entry in group

RepeatingGroup subGroup = entry.GetGroup(FIX43.ExecutionReport.InstrumentLeg.NoLegSecurityAltID);

//Some operations
entry.Release();
msg.ReleaseInstance();

Add new Repeating Group to message

To create Repeating Group is used method AddRepeatingGroupAtIndex:

FixMessage msg = RawFixUtil.GetFixMessage(executionReport.GetBytes());
msg = RawFixUtil.IndexRepeatingGroup(msg, true);

int repeatingGroupIndex = 20; //Index in message
int leadingTag = 555; //Leading tag for group
bool validation = true; //Turn on validation
RepeatingGroup group = msg.AddRepeatingGroupAtIndex(repeatingGroupIndex, leadingTag, validation);
//Some operations
msg.ReleaseInstance();

Parameter repeatingGroupIndex is an index of leading tag in FIX message. First tag has index = 0. Parameter validation enables or disables validation of group. Information about validation is below. Also you can add nested group to entry:

FixMessage msg = RawFixUtil.GetFixMessage(executionReport.GetBytes());
msg = RawFixUtil.IndexRepeatingGroup(msg, true);
RepeatingGroup group = RepeatingGroupPool.GetRepeatingGroup(); // Or new RepeatingGroup() or something else
RepeatingGroup.Entry entry = RepeatingGroupPool.GetEntry();
msg.GetRepeatingGroup(555, group); // Leading tag of Repeating Group
group.GetEntry(0, entry); //Number of entry in group

int leadingTag = FIX43.ExecutionReport.InstrumentLeg.NoLegSecurityAltID;
bool validation = true;
RepeatingGroup subGroup = entry.AddRepeatingGroup(FIX43.ExecutionReport.InstrumentLeg.NoLegSecurityAltID, validation);

//Some operations
entry.Release();
group.Release();
msg.ReleaseInstance();

Parameter validation is optional for creating repeating group. If it is ommited, its value will be inherited from parent group.

Add new Entry to Repeating Group

To create new Entry is used method AddEntry():

FixMessage msg = RawFixUtil.GetFixMessage(executionReport.GetBytes());
msg = RawFixUtil.IndexRepeatingGroup(msg, true);
RepeatingGroup group = RepeatingGroupPool.GetRepeatingGroup(); // Or new RepeatingGroup() or something else
RepeatingGroup.Entry entry = RepeatingGroupPool.GetEntry();
msg.GetRepeatingGroup(555, group); // Leading tag of Repeating Group

//Add at end
Entry entry1 = group.AddEntry()
//Add at index. First index = 0
Entry entry2 = group.AddEntry(1);

entry.Release();
group.Release();
msg.ReleaseInstance();

If you pass index greater than current group size or less than zero, you will get IndexOutOfRangeException.

Remove Entry from Repeating Group

There are few methods to remove entry from group:

group.Remove(index); //remove entry by index
entry.Remove(); //remove current entry, but doesn't return it in pool
group.Remove(entry); //remove passed entry, but doesn't return it in pool

Leading tag self-maintaining

Leading tag of group is fully self-maintaining. You can't update it directly. Leading tag doesn't appear in message, until group is empty. Also when group becomes empty leading tag is removed from message.

FixMessage msg = new FixMessage();
msg.Set(8, "FIX.4.4");
msg.Set(35, "8");
msg.Set(10, 123);

RepeatingGroup group = msg.AddRepeatingGroupAtIndex(555, 2);
Console.WriteLine(msg.ToPrintableString()); //8=FIX.4.4 | 35=8 | 10=123  group is empty, so it doesn't show in message

RepeatingGroup.Entry entry1 = msg.AddEntry();
RepeatingGroup.Entry entry2 = msg.AddEntry();
Console.WriteLine(msg.ToPrintableString()); //8=FIX.4.4 | 35=8 | 10=123  group have two entries now, but all entry is empty, so group still doesn't show in message
Console.WriteLine(group.GetSize()); // Prints 2, method getSize returns number of all groups - empty and non empty
Console.WriteLine(group.GetLeadingTagValue()); // Prints 0

entry1.addTag(600, "TBD");
Console.WriteLine(msg.ToPrintableString()); //8=FIX.4.4 | 35=8 | 555=1 | 600=TBD | 10=123  group appear in message.
Console.WriteLine(group.GetSize()); // Prints 2
Console.WriteLine(group.GetLeadingTagValue()); // Prints 1

entry.removeTag(600);
Console.WriteLine(msg.ToPrintableString()); //8=FIX.4.4 | 35=8 | 10=123  group is removed from message because there is no non-empty entries
Console.WriteLine(group.GetSize()); // Prints 2, method getSize returns number of all groups - empty and non empty
Console.WriteLine(group.GetLeadingTagValue()); // Prints 0

When we add two or more groups at the same place in message the behavior is the same as when we add two tags in the same place in message:

FixMessage msg = new FixMessage();
msg.set(8, "FIX.4.4");
msg.set(35, "8");
msg.set(10, 123);

RepeatingGroup group555 = msg.AddRepeatingGroupAtIndex(555, 2);
RepeatingGroup group454 = msg.AddRepeatingGroupAtIndex(454, 2); //group 555 will appear right after group 454

group555.AddEntry().addTag(600, "TBD");
Console.WriteLine(msg.ToPrintableString()); //8=FIX.4.4 | 35=8 | 555=1 | 600=TBD | 10=123
group454.AddEntry().addTag(455, 5);
Console.WriteLine(msg.ToPrintableString()); //8=FIX.4.4 | 35=8 | 454=1 | 455=5 | 555=1 | 600=TBD | 10=123
RepeatingGroup group = msg.AddRepeatingGroup(555, 2);

Nested repeating groups also have self-maintained leading tags.

When we add two nested groups one by one, they will appear in the order of adding:

RepeatingGroup.Entry entry = group555.AddEntry();
entry.addTag(600, "TBD");
RepeatingGroup group604 = entry.AddRepeatingGroup(604);
RepeatingGroup group539 = entry.AddRepeatingGroup(539);

Console.WriteLine(msg.ToPrintableString()); //8=FIX.4.4 | 35=8 | 454=1 | 455=5 | 555=1 | 600=TBD | 10=123 sub groups 604 and 539 is empty, so they doesn't show

group539.addTag(524, "524val");
Console.WriteLine(msg.ToPrintableString()); //8=FIX.4.4 | 35=8 | 454=1 | 455=5 | 555=1 | 600=TBD | 525=1 | 524=524val | 10=123
group604.addTag(605, "605val");
Console.WriteLine(msg.ToPrintableString()); //8=FIX.4.4 | 35=8 | 454=1 | 455=5 | 555=1 | 600=TBD | 604=1 | 605=605val | 525=1 | 524=524val | 10=123

All methods which work with index inside entry like RemoveTagAtIndex, GetTagValueAsXXXAtIndex do not work with empty groups:

RepeatingGroup.Entry entry = group555.AddEntry();
entry.AddTag(600, "TBD");
RepeatingGroup group604 = entry.AddRepeatingGroup(604);

entry.RemoveTagAtIndex(1); //returns false, because there is no any real tag at index 1 inside entry.

ITagList interface

There is a common interface for FixMessage and RepeatingGroup.Entry for Add, Get, Update, Remove operations on tags in entry:

ITagList entry = group.GetEntry(0);
entry.AddTag(tag, tagValue);
entry.UpdateValue(tag, tagValue, missingTagHandling);
entry.RemoveTag(tag);
entry.GetTagValueAsString(tag);
//And others

Validation

Validation of repeating groups is available during initial indexing of Repeating Group and during modification of Repeating Group.

During indexing there are such validations:

Leading tag value validation. Leading tag value must be equal to number of Repeating Group entries.
Duplicate tag validation. All tags inside entry must be unique.
Delimiter tag validation. Delimiter tag must be followed by leading tag.

During modification of Repeating group there are such validations:

Tag refers to group validation. Must be mapping group -> tag in dictionary.
Duplicate tag validation. All tags inside entry must be unique.

Copying

It is possible to copy repeating group and entry to other message or group. To copy repeating group from one FIX message to another, use method FixMessage.CopyRepeatingGroup:

RepeatingGroup srcGroup = srcMsg.GetRepeatingGroup(232);
RepeatingGroup copiedGroup = dstMsg.CopyRepeatingGroup(srcGroup, 9); // group for copy and index where group will be inserted

To copy entry of repeating group to other group, use method RepeatingGroup.CopyEntry:

RepeatingGroup groupForCopy = srcMsg.GetRepeatingGroup(454);
RepeatingGroup.Entry entryForCopy = groupForCopy.GetEntry(1);
RepeatingGroup tarGetGroup = dstMsg.GetRepeatingGroup(454);

Entries can be copied to the same message or to another message. To copy nested repeating group, use method Entry.CopyRepeatingGroup:

RepeatingGroup groupForCopy = srcMsg.GetRepeatingGroup(555).GetEntry(0).GetRepeatingGroup(539);
RepeatingGroup.Entry tarGetEntry = dstMsg.GetRepeatingGroup(555).GetEntry(0);

RepeatingGroup copiedGroup = tarGetEntry.CopyRepeatingGroup(groupForCopy);

You can insert nested group in any entry or even in root of message without limitation

Finishing work with Repeating Group API.

If you created FixMessage message from pool, call of ReleaseInstance() will return all RG instances and message itself to corresponding pools. In other case you should call method InvalidateRepeatingGroupIndex() at the end of the work with Repeating Group API. Also don't forget to call methods Release() for RepeatingGroup.Entry and RepeatingGroup if you got it from pool explicitly.