Specify the repository structure for a new input window
|
WSupported on Windows
|
USupported on Unix
|
VSupported on OpenVMS
|
NSupported in Synergy .NET
|
xcall IB_RPS_STRUCTURE(build_id, structure_name, [main_file, text_file][, alias_name])
Arguments
build_id
The ID of the input window under construction. (n)
structure_name
The name of the repository structure to access. (a)
main_file
(optional) The name of the main repository file to use. (a)
text_file
(optional) The name of the repository text file to use. (a)
alias_name
(optional) The name by which structure_name will be referenced within this input window. (a)
Discussion
IB_RPS_STRUCTURE specifies that subsequent calls to IB_FIELD are to draw the definitions from the given repository structure. This subroutine is used when building a new input window at runtime.
IB_RPS_STRUCTURE automatically creates a .STRUCTURE in the input window with the specified structure_name, containing all the referenced fields in the appropriate positions. You do not need to call IB_STRUCTURE for this structure.
If main_file and text_file are not specified, the repository filenames specified by the RPSMFIL and RPSTFIL logicals will be used. (RPSMFIL should be set to the name of the main repository file. RPSTFIL should be set to the name of the repository text file.) If these logicals are not set, the default repository file name will be used: RPSDAT:rpsmain.ism and RPSDAT:rpstext.ism, respectively.
You should use the alias_name qualifier in the following circumstances:
- 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.
After you have assigned an alias_name to a structure, any runtime references to the structure must use the alias_name. If you have given the structure an alias_name and are referencing a field during runtime, the reference to the field will 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 also
Basic field information for information on using implicit groups to combine repository structures
Examples
The following example specifies that subsequent fields in the input window being built are to be drawn from the cusmas structure in the default repository.
xcall ib_rps_structure(bldid, "cusmas")
The next example specifies that subsequent fields in the input window being built are to be drawn from the order structure in the repository residing in the files frnchmn.ism and frnchtx.ism.
xcall ib_rps_structure(bldid, "order", "frnchmn.ism", "frnchtx.ism")
