Defining field templates

A template is a set of field characteristics that can be assigned to one or more field definitions (up to 6,000) and one or more template definitions (up to 3,000). Templates provide consistency for your fields throughout all structures in your repository, and also reduce data entry. They also provide an easy way to modify a common field type (for example, changing all date fields from d6 to d8). You can assign a template when you define or modify a field or template. You can define a maximum of 9,999 templates.

To display the Template Definitions list, select Modify > Templates. For each template, the template name and description are displayed. The total number of templates in your repository is displayed at the bottom of the window. (See figure 1.)

1. The Template Definitions list.

Defining a new template

You can define a new template from scratch or by copying and modifying an existing template.

1. From the Template Definitions list,

The Template Definition window displays with tabs on which you can define template information. Instructions are given in this section for the Template Definition tab, but not for the other tabs, as they are the same as the tabs for fields.

Defining basic template information

2. Defining basic template information.

1. Enter or modify data as instructed below.

Template name

Enter a unique template name. The template name can have a maximum of 30 characters and must begin with a letter. The remaining characters can be letters, digits, underscores (_), or dollar signs ($).

Parent template

If desired, enter the name of a parent template to use to create the current template. (A parent template is a template for a template.) Up to 3,000 templates can use the same parent template. To display a list of available templates, select Edit Template Functions > List Selections.

All attributes of the parent template are copied to the current template, including display, input, validation, and method information. You can override any of the parent template attributes simply by specifying new values. If the parent template is later modified, only the attributes that have not been overridden are copied to the child template. The check boxes at the bottom of the window indicate the attributes of the parent template that have been overridden in the current template.

Repository sets these flags when you exit the window, but you can also set them manually. You might want to do this when an attribute matches the parent and you don’t want it to be changed later if the parent changes. By default, these fields are read‑only. To modify them, select Edit Template Functions > Access Template Overrides. This menu entry is a toggle: select it a second time and the override fields revert to read‑only. The Access Template Overrides setting remains in effect for all field and template definitions until you change it.

Description

Enter a description for the template, with a maximum of 40 characters. The description displays on the Template Definitions list.

Type

Select the type of data the field will contain:

Alpha

Decimal

Integer

Date

Time

User

Binary

Boolean

Enum

AutoSeq

AutoTime

If you select Date, Time, or User, the cursor moves to the Class field. If you select Enum, the cursor moves to the Enumeration field (see Enumeration below).

Note

In Synergy DBL, the Binary data type is treated as an alpha.

In xfNetLink Java (when genjava is run with the ‑c 1.5 option) and xfNetLink .NET. a Binary data type field in a structure is converted to a byte array on the client, and can be used, for example, to store an RFA. For xfNetLink Synergy clients, a Binary data type field is converted to a string.

In xfODBC, a Binary data type field is described as a binary field (SQL_BINARY). This is also true of a User type field with a class of binary (see Class below), but in this case you can use the routines for user‑defined data types in xfODBC to manipulate the data read from the ISAM file and return it as a binary field to the ODBC‑enabled application.

Class

If you selected Date or Time in the Type field, specify the storage format in the Class field:

YYMMDD = two‑digit year, month, day

YYYYMMDD = four‑digit year, month, day

YYJJJ = two‑digit year, Julian day

YYYYJJJ = four‑digit year, Julian day

YYPP = two‑digit year, period

YYYYPP = four‑digit year, period

HHMM = hour, minute

HHMMSS = hour, minute, second

If you selected User in the Type field, specify the user subtype in the Class field. User subtypes are used by the xfODBC user‑defined processing routines and are available in the gs_inpfld structure within UI Toolkit’s user‑defined processing routines. Subtypes also affect data type mapping in xfNetLink Java and xfNetLink .NET; see Appendix B: Data Type Mapping for xfNetLink Java or Appendix C: Data Type Mapping for xfNetLink .NET for details. The available subtypes are

Alpha

Numeric

Date

Binary

Additional date storage formats are supported by xfODBC. See Appendix B: Date and Time Formats for more information.

User data

If you selected User in the Type field, specify a string of up to 30 characters to identify your user‑defined data type, and press enter to save it.

In a UI Toolkit input window, a user type field flags the runtime input processor to call the ECHKFLD_METHOD, EDSPFLD_METHOD, and EEDTDSP_METHOD subroutines for additional processing. The user data string is passed to these subroutines to be used as a control code. The user subtype (class) is available in the gs_inpfld structure.

User type fields also flag ReportWriter to call user‑overloadable subroutines (for example, RPS_DATA_METHOD which formats the data for display). See Customizing ReportWriter Routines for more information about the user‑overloadable subroutines called by ReportWriter.

User type fields also flag xfODBC to call user‑overloadable subroutines to process the data for those fields. The user data string is passed to these routines. See Creating Routines for User-Defined Data Types for more information.

Enumeration

If you selected Enum in the Type field, enter the enumeration name or select Edit Template Functions > List Selections and choose it from the list.

Note

The Enum data type is not supported by UI Toolkit. To use an enumerated data field with an allow list or selection list or window, use the Enumerated field on the Validation tab. See Enumerated for more information.

Coerced type

If the structure that this field belongs to is included in an xfNetLink Java JAR file or an xfNetLink .NET assembly, you can optionally specify a non‑default data type for the field to be coerced to on the client side. Type coercion is available when Type is one of the following: Decimal, Integer, Date, Time, User.

See Appendix B: Data Type Mapping for xfNetLink Java and Appendix C: Data Type Mapping for xfNetLink .NET for more information on data type mapping and coercion in xfNetLink.

Size

Enter the maximum number of characters the template field can contain. The following restrictions apply:

Precision

If the data type is implied‑decimal, enter the number of characters to the right of the decimal point. This value must be between 1 and 28, inclusive, and must be less than or equal to the size of the field.

Dim1 – 4

If the template defines an array, enter the number of elements in each dimension. The maximum number of dimensions is 4. The maximum number of elements per dimension is 999. If the template doesn’t define an array, the Dim field displays 1.

Excluded by Language

This value determines whether a template field is available to the Synergy compiler. Select this option if you do not want the template field to be available to the compiler. Excluded by Language is cleared by default, which means the field will be included when using the .INCLUDE compiler directive to reference the structure to which this field belongs, and will be included in any definition files generated by the Generate Definition File utility. This feature is useful when your repository contains overlay fields defined solely for the purpose of referencing group elements from within ReportWriter.

Excluded by Toolkit

This value determines whether a template field is available to UI Toolkit. Select this option if you do not want to be able to reference the template field from Toolkit. Excluded by Toolkit is cleared by default, which means the field can be referenced by the Script compiler, Composer, and the IB_FIELD subroutine.

Excluded by ReportWriter

This value determines whether a template field is available in ReportWriter as a selectable field. Select this option if you do not want this template field to be selectable in ReportWriter. Excluded by ReportWriter is cleared by default, which means the field can be selected for inclusion in a report. This flag can also be honored when generating a system catalog in xfODBC; see Setting catalog generation options for details on including and omitting fields.

Excluded by Web

This value determines how the template field is treated by xfNetLink. The Excluded by Web flag should be used only to control how fields in an overlay are handled. If this field is not part of a structure that contains overlays, do not select this option. Select Excluded by Web if you do not want this template field to be included in a Synergy JAR file assembly. Excluded by Web is cleared by default, which means that all fields are included in the Synergy component. For details on using this flag to control how overlays are handled, see Passing structures as parameters.

Do not name link

ReportWriter can use name links you establish in Repository to access related files. This field determines whether the template field is name linked to its parent (if one exists). By default, Repository will use the name of the parent to generate name links. Select this field if you want Repository to use the template field’s name when generating name links. (See also Generate Cross‑Reference utility (rpsxref).)

Template overrides

If the current template references a parent template, the Template overrides section indicates the template attributes that are overridden. If these override fields are read‑only, select Edit Template Functions > Access Template Overrides to make them active. (See the description of Parent template for more information about template override flags.)

2. To define display, input, validation, or method information, or to add a long description for a template, go to the desired tab or select the entry from the Edit Template Functions menu. Refer to the following sections for instructions:

Display information

Input information

Validation information

Method information

Assigning a long description to a field (Long Desc tab)

3. Exit the window to save the new template and return to the Template Definitions list.

Modifying a template

1. Highlight the template in the Template Definitions list and press enter. The Template Definition window is displayed, with the tab that you viewed last on top.
2. Modify data as desired on any of the tabs. The template name cannot be modified.

If you modify the parent template name, all attributes of the new parent (including display, input, validation, and method information, as well as the long description) are copied to the current template, with the exception of any attributes that were overridden in the current template. See the description of Parent template for more information.

For details on completing the fields on each tab, refer to the relevant section:

Defining basic template information (Template Definition tab)

Display information

Input information

Validation information

Method information

Assigning a long description to a field (Long Desc tab)

3. Exit the window to save your changes and return to the Template Definitions list.

If the template that you’re modifying is assigned to one or more fields or templates, when you save your changes you are prompted

Modifying template “NAME” will affect one or more template, field, and key definitions.
Are you sure you want to save your modifications?

The default response is No. If you press enter, the template modifications are ignored and you are returned to the Template Definitions list. If you select Yes, the new template information is applied to all fields and templates that refer to it. Repository also applies the changes to any fields that reference any templates that in turn reference the template being modified.

Note

Any attribute of any field or template that overrides a template or parent template attribute is not modified.

Additionally, all keys that use the updated fields are updated (key size and key data type). The record size of all affected structures is updated.

Deleting a template

You cannot delete a template that is assigned to a field or to another template.

1. Highlight the template in the Template Definitions list.
2. Select Template Functions > Delete Template.
3. At the prompt, select Yes to delete the template or No to cancel the deletion.