Preparing Your Repository

CodeGen is almost always used with a repository structure providing the metadata that is to be used for the generation of the source file, and many of the tokens require the use of a repository structure.

The basic requirement is that you have a structure definition, and that structure definition includes one or more field definitions. Some tokens also require that keys are defined, and some require file definitions with structure assignments.

If you don't already have a repository then you can load most of the information that you will need by reading existing record layout files into repository structures.

Repository Structure Restrictions

In order to be used successfully with CodeGen, Repository structures must meet the following requirements.

•Enumeration, binary and structure fields are not currently supported by CodeGen.

•Overlay fields are allowed, but will generally be ignored by CodeGen.

•All keys must be correctly defined to exactly match the appropriate ISAM file.

•Only a single tag is allowed and that tag must be a FIELD.EQ.VALUE type.

•The use of some tokens requires that the structure being processed is assigned to a file definition, and some require that keys are defined.

•Keys must be defined in the correct sequence. CodeGen determines key numbers by the order in which keys are defined in the repository structure. Define access keys in the correct sequence, and define foreign keys after all access key definitions.

•If you intend to generate source code for languages other than Synergy, then you should avoid giving fields names which may be reserved words in the language concerned.

•If you wish to prevent a structure from being processed by CodeGen then you can add the text @NOCODEGEN to the structures user text field or long description.

•To specify that a field in a structure is the structures “display field” you can add the text @CODEGEN_DISPLAY_FIELD to the fields’ user text string or long description. For more information refer to the <DISPLAY_FIELD> token.

Array Fields

CodeGen supports array fields, but these arrays are expanded into multiple non-array fields. In other words each array field encountered is replaced by multiple fields with the same data type and size as the array field.

When an array is expanded to multiple individual fields, the name of each field is amended to include the array element definition. For example, the field MYFIELD, [2]A10 will be expanded to two separate fields named MYFIELD[1] and MYFIELD[2].

Group Fields

CodeGen supports groups, including group arrays. When processed by CodeGen, groups are expanded. In other words the fields in the group become fields in the main structure, and the group field is removed.

By default, group member field names are prefixed with the name of the parent group field followed by a period, but this behavior can be overridden with the –g f command line option. For example, if a group called ADDRESS contains a field called STREET, the name of the field used by CodeGen will be:

ADDRESS.STREET

But if you were to use the –g f command line option then the name of the field would be:

STREET

Obviously, in this scenario you would need to make sure that the name did not clash with any other identifiers in the same structure.

If the repository group definition includes a “member prefix” then this prefix is added to the name of each field in the group, but this behavior can be overridden with the –g r command line option.

For example, if a group called ADDRESS contains a field called STREET, and the group field defines a member prefix of HOME_, the name of the field used by CodeGen will be:

ADDRESS.HOME_STREET

With the –g f command line option the name would be:

HOME_STREET

With the –g r command line option the name would be:

ADDRESS.STREET

And with the –g f r command line options the name would be:

STREET

If a group member field is declared as an array then it will be treated as discussed earlier under Array Fields.

Loading Include Files

Before you load the fields from an include file into a repository structure it is often best to make a copy of the include file, and then perform some simple "cleanup" within the file before loading it into the repository structure:

•The repository can load the fields from a single record (or common) in an include file into a repository structure, so if the include file has multiple records defined then first identify which record you wish to load.

•Repository will use any comment which follows a field definition as the description for the field, so clean up the comments. If your field comments include things like position information then you may want to remove them. Note that if the positions are delimited with specific identifiable characters (for example if they are within parentheses) then you can specify these characters when you load the fields into repository, so in this case you don't need to manually edit them out.

•Repository will load any overlays that are defined within the record to be loaded, but if you have overlays that you want to preserve that are defined as separate overlay records (using record ,X) then you might want to consider moving those overlay fields into the actual record definition.

•Remember that generally CodeGen will ignore overlay fields however, so review any overlays and make sure that the fields that you are most likely to want to use in generated code are the "real" fields, and those less likely to be useful are the overlays. An example would be if you have date fields where the real fields are individual year, month and day, and there is a full date overlay. When generating code it is most likely that you will want to access the full date and not the individual fields, so switching the fields and overlays around would probably be best.

•If you have full overlay records (one record followed by one or more record, X's) then you will probably want to load each of the overlays into a separate repository structure.

Once you have cleaned up the include file you are ready to load the file into a new repository structure. The procedure is as follows:

•Start repository and Select Modify > Structures.

•Click the Add button (or press the Insert key) to add a new structure.

•Provide a name for the structure. It is usually best to use the original record name as the structure name.

•Set the file type. Most structures should be set to "DBL ISAM".

•Provide a meaningful description of the structure, such as "Customer Master Record".

•If the structure is to be associated with a file which has multiple record layouts within the data file, set the tag to tell repository and other tools how to detect this particular record layout within the file. If this is not the case then select None.

•Click the OK button to create the new structure.

•Click the Attributes button (ore press F3)

•From the menu, select Attributes > Fields.

•From the menu, select Field Functions > Load Fields (or press F9).

•Enter the name of the include file (or use the file browser to locate it).

•If the include file has multiple records, enter the number of the record to be read.

•If you want to strip information (for example position between parentheses) from the field descriptions then enter the characters that delimit the information to be removed.

•Click the OK button to load the fields into the structure.

•Press the F4 key to exit from the fields list.

•Press the F4 key again to exit from the structure, and save the changes.

•Keep pressing F4 to exit from the repository program.