.REPOSITORY_STRUCTURE

Establish the current repository structure

.REPOSITORY_STRUCTURE structure_name[=alias_name], ["main_file"][, "text_file"]

Arguments

structure_name

The name of the repository structure to access.

alias_name

(optional) The name by which structure_name will be referenced within this input window (a maximum of 30 characters).

main_file

(optional) The name of the main repository file to use.

text_file

(optional) The name of the repository text file to use.

Discussion

The .REPOSITORY_STRUCTURE command specifies that subsequent fields in the current input window definition are to be drawn from the given repository structure when you are compiling your script. If no fields exist in the structure, an error will be generated. The specified repository structure is in effect until a .LOCAL, .END, or another .REPOSITORY_STRUCTURE.

Field qualifiers on subsequent .FIELD commands will override repository specifications.

Additional requirements for drawing field definitions from a repository are discussed in the .FIELD Discussion.

The .REPOSITORY_STRUCTURE command automatically creates a .STRUCTURE in the window library with the specified structure name, containing all the referenced fields in the appropriate positions.

If you make changes to your repository structure after compiling your script, you will need to re-compile.

Use the alias_name argument in the following situations:

When you include the same repository structure more than once within an input window.
When you include two or more fields that have the same name although they are referenced from different repository structures.

In either of the preceding situations, you must rename the second and succeeding “same” structures using the alias_name argument. Note that there are no spaces between the equal sign (=) and the names.

After you have assigned an alias_name to a structure, any following references to the structure (for example, in a .SET) must use the alias name instead. If you have given the structure an alias_name and are referencing a field at runtime (for example, with I_NEXT, I_DSPFLD, or I_INPFLD), the reference to the field must have the following syntax:

alias_name.field_name

This syntax can be used only for fields that are in a renamed structure. The first 30 characters of the full reference above must be unique within the input window. Thus, we recommend that you use short alias names.

You can combine multiple repository structures, enabling their access as one structure, by using the implicit group feature of Repository. See Basic field information.

If main_file and text_file are not passed or are blank, the repository main and text file specified by the environment variables RPSMFIL and RPSTFIL, respectively, will be used. If these environment variables are not set, UI Toolkit will use the default repository files (rpsmain.ism and rpstext.ism) found in the directory specified by the RPSDAT environment variable.

If specified, main_file and text_file must be enclosed in quotation marks, and if you use an environment variable, it must be followed by a colon. For example:

.repository_structure s1, "D:\test\rpsmain.ism", "D:\test\rpstext.ism"
.repository_structure s2, "MAINFILE:", "TEXTFILE:"

See also

The .FIELD Discussion for more information on repository fields
Basic field information for more information on using implicit groups to combine repository structures

Examples

The following example defines an input window that contains four fields from the repository structure cusmas. A default set cusinf will be created that references the structure cusmas.

.input cusinf, 4, 45
.repository_structure cusmas, "RPS1:rpsmain.ism", "RPS1:rpstext.ism"
.field name
.field address
.field city
.field state
.end

The next example defines an input window that contains two fields from the repository structure cusmas, and one field from the repository structure cushis. The position specified for the field prev_address in the repository is overridden here. This example creates only one input set, cusinf, which references the first defined structure (cusmas). Cushis is a structure without a set here, and note that cushis is from the default repository (the rpsmain.ism and rpstext.ism files in the directory specified by the RPSDAT environment variable).

.input cusinf, 4, 45
.repository_structure cusmas, "RPS1:rpsmain.ism", "RPS1:rpstext.ism"
.field name
.field address
.repository_structure cushis
.field prev_address, pos(3,2)
.end

This example creates two input sets, old and new, which reference two identical structures, both of which are defined by the repository structure cusmas. In the program that uses this window, if you want to use old set, you would reference the name field. If you want to use new set, you would reference new.name.

.input cusinf, 4, 45
.repository_structure cusmas, "RPS1:rpsmain.ism", "RPS1:rpstext.ism"
.field name
.field address
.repository_structure cusmas=new
.field name
.field address
.set old, cusmas, name, address
.set new, new, name, address
.end