Appendix D: Instance Names

This refers to the INSTANCE NAME field which is available in the Transaction maintenance screens MNU_0030x.

When a transaction is selected for processing an instance (copy) of the associated Uniface component is created and activated. The instance is given a name which may or may not be the same as the component name. If only one instance of a component is allowed to be active at any one time then it is usual to use the component name as the instance name. If more than one instance is to be allowed then each instance must be given a unique name.

Multiple instances are typical when creating child instances from a LIST form. The user selects the 1st occurrence and creates the 1st child instance, then selects a 2nd occurrence and creates a 2nd instance of the same child form. It is possible to get the system to generate a random and unique instance name (see the "RANDOM" option below), but this would allow multiple instances of the same child form being created for the same occurrence at the same time. It would therefore be advisable to construct each instance name using a value that links it with a particular occurrence. It would not be a good idea to use the occurrence number within the current hitlist as renumbering will occur if occurrences are added to or deleted from that hitlist. A value that is both unique and unchangeable for every database occurrence is the primary key, so it would seem logical to use this in the construction of the instance name.

If the primary key value were to be used on its own this would prevent instances of different components with the same value from being active at the same time. A way to avoid this would be to use a combination of the component name and the primary key value. Rather than using a single fixed method for the generation of all instance names the system administrator must specify a separate pattern for each component. This can be defined in the INSTANCE_NAME field for the component's entry in the MNU_TRAN table. A blank value (the default) signifies that the instance should have the same name as the component. A non-blank value signifies the pattern to be used when constructing the instance name. The pattern should consist of the following:-

Any combination of letters, numbers or underscore characters.
Field names enclosed in parentheses '(' and ')'. The field name must exist within the set of key values which is passed down from the parent form to the child.
The keyword "RANDOM" on its own.

UNIFACE insists that the instance name begins with a letter, and as some primary key values may be purely numeric it is advisable to specify an alpha prefix in the pattern. The instance name cannot exceed 16 characters, therefore rather than using the full component name as the prefix it would be advisable to use a shortened version. This name has three parts - <system prefix>, <sequence number>, and <dialog type>, therefore a unique prefix can be constructed from <dialog type> and <sequence number>.

For example, the menu system contains a transaction (component) called MNU_0020R which accesses a database entity (MNU_USER) whose primary key is USER_ID. The pattern for generating different instance names for each occurrence could therefore be defined as "R20_(USER_ID)". At run time the pattern characters "(USER_ID)" will be replaced by the actual value from the database occurrence, so if the value was "FRED27" the generated name would be "R20_FRED27".

It is possible to specify more than one field name in the pattern. This is useful if the primary key is composed of more than one field.

Do not worry if the resulting instance name contains invalid characters or is more than 16 characters long - the standard software will strip out and truncate as necessary.

Another option is to let UNIFACE itself generate a unique instance name. This is for those cases where multiple instances may be required but either there is no parameter from which to construct the name, or it is not necessary to tie an instance to a particular occurrence. In this case the keyword "RANDOM" can be used which will cause UNIFACE to generate a unique name using a random set of letters and numbers.

http://www.tonymarston.net