IB_RPS_STRUCTURE

Specify the repository structure for a new input window

WTSupported in traditional Synergy on Windows
WNSupported in Synergy .NET on Windows
USupported on UNIX
VSupported on OpenVMS
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:

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")