Processing GROUP Fields

Understanding GROUP Fields

The GROUP statement defines a data structure within a record or another group structure. The ENDGROUP statement indicates the end of a group declaration. A group name must be unique among all other field and group names within a parent group. If a group isn’t part of another group, its name must be unique within the record. Here is an example of a record containing several groups:

record info

group customer ,[100]a

name ,a30

group office ,a

bldg ,a20

group address ,a

street ,a40

zip ,d10

endgroup

group contact ,a

name ,a40

group address ,a

street ,a40

zip ,d10

endgroup

endgroup
endrecord

Overlay Groups

Group fields can also be used to define overlays. By default, CodeGen excludes overlays when processing, and that included the exclusion of overlay groups. However, if the -f o command line option is used to cause overlays to be included when processing, then overlay groups will also be included. When processing in a field loop you can detect whether an unexpanded overlay group is being processed by using the <IF GROUP_OVERLAY> expression.

Implicit and Explicit Groups

While DBL has only one type of group, Repository allows you to define groups in two ways. These are referred to as "explicit groups" and "implicit groups". An explicit group is a group where the group members are defined explicitly within the definition of the group, all within the same structure. An implicit group is a group where the members of the group are defined by the members of a different structure.

Group Member Prefix

When a field is declared as a GROUP it is possible to also provide a "member prefix", which is a value to be pre-pended to the names of all fields in the group. By default, CodeGen will use any prefix specified, but if you prefer not to use the prefix when generating code then that behavior can be suppressed by specifying the -g f command line option.

When processing groups, you can determine whether a group member prefix is present by using the <IF GROUP_MEMBER_PREFIX> expression, and you can access the prefix value with the <FIELD_GROUP_MEMBER_PREFIX> expansion token.

How CodeGen Processes Groups

Under normal circumstances, whenever CodeGen encounters a GROUP field in a structure, it expands the group into individual fields. So, if a structure contains a group that has ten member fields, then the group field is removed from the structure and ten individual fields are added in its place. And if a group contains other "nested" groups, then the same process is applied to those fields also. For example, given the following structure:

structure customer

customer_id, a10

company_name, a40

group address, a

street, a30

city, a20

state, a2

zip, d5

endgroup

phone, d10

endstructure

If you use the <field_name> token to access the field names in a field loop, you would see field names like this:

customer_id

company_name

address.street

address.city

address.state

address.zip

phone

If you use the <field_sqlname> token to access the field names in a field loop, you would see field names like this:

customer_id

company_name

address_street

address_city

address_state

address_zip

phone

Controlling Group Expansion

If you prefer to not have group fields expanded during code generation then you can control that behavior, for both explicit and implicit groups, via two command-line options. The -g e option prevents explicit groups from being expanded, and the -g i option prevents the expansion of implicit groups.

When you use these options the original group field remains in the structure, and the values of some field loop tokens is altered for those fields. When processing a field loop you can detect whether groups are or are not being expanded using expression tokens <IF EXPLICIT_GROUP_NO_EXPAND> and <IF IMPLICIT_GROUP_NO_EXPAND>, and you can detect unexpanded group fields with expressions like <IF GROUP>, <IF EXPLICIT_GROUP>, <IF IMPLICIT_GROUP> and <IF GROUP_OVERLAY>. And when processing an unexpanded implicit group, you can refer to the name of the structure that defines the members of the group via the <FIELD_GROUP_STRUCTURE> token.

Generating Code for Unexpanded Groups

This is a complex subject, and one for which there are likely to be many different scenarios, and different requirements, but here is one example, based on the following structure:

structure CUSTOMER

CUSTOMER_ID ,D8 ; Customer ID

COMPANY ,A40 ; Company name

group BILLING_ADDRESS ,A ; Billing address

STREET ,A30 ; Street address

CITY ,A20 ; City

STATE ,A2 ; State

ZIP ,D5 ; Zip code

endgroup ;

group SHIPPING_ADDRESS ,A ; Shipping address

STREET ,A30 ; Street address

CITY ,A20 ; City

STATE ,A2 ; State

ZIP ,D5 ; Zip code

endgroup ;

group PRIMARY_CONTACT ,A ; Primary contact name

FIRST_NAME ,A15 ; First name

MIDDLE_INITIAL ,A1 ; Middle initial

LAST_NAME ,A15 ; Last name

endgroup ;

group BILLING_CONTACT ,A ; Billing contact

FIRST_NAME ,A15 ; First name

MIDDLE_INITIAL ,A1 ; Middle initial

LAST_NAME ,A15 ; Last name

endgroup ;

group SHIPPING_CONTACT ,A ; shipping contact

FIRST_NAME ,A15 ; First name

MIDDLE_INITIAL ,A1 ; Middle initial

LAST_NAME ,A15 ; Last name

endgroup ;

endstructure

In the repository, the groups BILLING_ADDRESS and SHIPPING_ADDRESS are defined as IMPLICIT groups, their fields being defined by a second structure named ADDRESS. Whereas the groups PRIMARY_CONTACT, BILLING_CONTACT and SHIPPING_CONTACT are all defined as explicit groups, i.e. their member fields are defined LOCALLY within the CUSTOMER structure

If we wanted to generate a Synergy .NET class to represent this structure, we might use a template like this:

namespace <NAMESPACE>

public class <StructureName>

<FIELD_LOOP>

public readwrite property <FieldSqlName>, <FIELD_SNTYPE>

</FIELD_LOOP>

endclass

endnamespace

And we might use a codegen command like this:

codegen -t grouptest -s customer -n MyNamespace

And the output would be something like this:

namespace MyNamespace

public class Customer

public readwrite property CustomerId, int

public readwrite property Company, String

public readwrite property BillingAddressStreet, String

public readwrite property BillingAddressCity, String

public readwrite property BillingAddressState, String

public readwrite property BillingAddressZip, int

public readwrite property ShippingAddressStreet, String

public readwrite property ShippingAddressCity, String

public readwrite property ShippingAddressState, String

public readwrite property ShippingAddressZip, int

public readwrite property PrimaryContactFirstName, String

public readwrite property PrimaryContactMiddleInitial, String

public readwrite property PrimaryContactLastName, String

public readwrite property BillingContactFirstName, String

public readwrite property BillingContactMiddleInitial, String

public readwrite property BillingContactLastName, String

public readwrite property ShippingContactFirstName, String

public readwrite property ShippingContactMiddleInitial, String

public readwrite property ShippingContactLastName, String

endclass

endnamespace

But what if we didn't want to expand the groups into individual properties. What happens if we add the command line options to tell CodeGen not to expand explicit and implicit groups, like this:

codegen -t grouptest -s customer -n MyNamespace -g e i

Well, we wind up with this:

namespace MyNamespace

public class Customer

public readwrite property CustomerId, int

public readwrite property Company, String

public readwrite property BillingAddress, @ADDRESS

public readwrite property ShippingAddress, @ADDRESS

public readwrite property PrimaryContact, @PRIMARY_CONTACT

public readwrite property BillingContact, @BILLING_CONTACT

public readwrite property ShippingContact, @SHIPPING_CONTACT

endclass

endnamespace

As you can see, the group fields were not expanded, and the data type produced for the unexpanded groups by the <FIELD_SNTYPE> token became a class reference. In the case of the two implicit group fields, BILLING_ADDRESS and SHIPPING_ADDRESS, the type refers to a class defined by the name of the other structure that was used to define the group members, and in the case of the three explicit groups, the type refers to a class based on the name of the original group field.

This code may or may not compile, depending on whether the three other classed being referred to actually exist or not. Let's explore how we can leverage the functionality of the special <FIELD_GROUP_EXPAND> token to enhance out template:

namespace <NAMESPACE>

public class <StructureName>

<FIELD_LOOP>

public readwrite property <FieldSqlName>, @<FIELD_GROUP_STRUCTURE>

<ELSE>

public class <FieldName>

<FIELD_GROUP_EXPAND>

endclass

public readwrite property <FieldSqlName>, @<FieldName>

</IF IMPLICIT_GROUP>

<ELSE>

public readwrite property <FieldSqlName>, <FIELD_SNTYPE>

</IF GROUP>

</FIELD_LOOP>

endclass

endnamespace

This template is a little hard to explain, so we'll break down the most important parts of the template one at a time:

1.Within the field loop, notice that the first thing we do is use an <IF GROUP> expression to give us a place to do special things for unexpanded groups, and the associated <ELSE> clause provides a place for the code for regular, non-group fields. In fact the code in that <ELSE> clause is the same code that we had in our original template, so for non-group fields we will continue to produce a public read-write property.

2.In the unexpanded group section of the field loop, notice how the next thing we do is use the <IF EXPLICIT_GROUP> expression, and it's associated <ELSE> clause, to allow us to generate different code for implicit groups and explicit groups.

3.For implicit groups we generate a read-write property and type it using the <FIELD_GROUP_STRUCTURE> token. This will result in a reference to the other structure that defines the members for the group.

4.For explicit groups we do a little more; we output the code for a nested class (a class within a class, just like a group is kind of like a record within a record), named after the original explicit group field, and we also emit a public property whose type is defined by that new nested class.

5. This is where it gets complicated. Notice that the body of the nested class contains a single token called <FIELD_GROUP_EXPAND>, which is a very special token that behaves very differently to most other field loop expansion tokens. Essentially what it does is "replay" the entire body of the field loop that contains it, but for the members of the current group field. If the group field only contains fields as members, then the nested class will simply contain public properties for those fields, but if the group contains members that are other groups, then the exact same process will occur, and on, and on, until all fields have been processed.

So, if we process this template, using the exact same CodeGen command that we used last time, the output will look like this:

namespace MyNamespace

public class Customer

public readwrite property CustomerId, int

public readwrite property Company, String

public readwrite property BillingAddress, @ADDRESS

public readwrite property ShippingAddress, @ADDRESS

public class PrimaryContact

public readwrite property FirstName, String

public readwrite property MiddleInitial, String

public readwrite property LastName, String

endclass

public readwrite property PrimaryContact, @PrimaryContact

public class BillingContact

public readwrite property FirstName, String

public readwrite property MiddleInitial, String

public readwrite property LastName, String

endclass

public readwrite property BillingContact, @BillingContact

public class ShippingContact

public readwrite property FirstName, String

public readwrite property MiddleInitial, String

public readwrite property LastName, String

endclass

public readwrite property ShippingContact, @ShippingContact

endclass

endnamespace

As you can see, the regular fields in the structure are exposed as public properties, the implicit groups are exposed as class references to an externally defined class, presumably code-generated separately using a different template, and the explicit groups are implemented as nested classes exposed via public properties.

By the way, if you were to process this token without the -g e i command line options, it would produce the exact same content as the original template, because there would not be any unexpended group fields present.

And I should also mention that if you use the sample templates from this article, the output won't be exactly as shown here; we are still working on how to get appropriate indentation when we iterate through multiple levels of groups with a single expansion token, so for the time being the code may look a little onorganized, but that's nothing that a quick CTRL+K+D in the Visual Studio editor can't fix!