Labels

There is another character identifier that can be stored in the database and used to distinguish a picture more precisely. This is the label which is an optional component of a picture. It differs from other structures in AGI in that its contents can be changed at any time (by overwriting the existing contents), whereas other picture elements can only be defined when they are first created. Because the label contents can be changed at any time the responsibility for guarding against misuse is left up to the application/user.

The labels differ in another way from the name component in that each label within a workstation structure must be unique. If a new label clashes with an exiting one within a workstation structure then the existing label will be deleted and replaced by a blank string. Although the labels are stored with mixed case the comparison is done with leading blanks removed and in uppercase only.

The routine AGI_SLAB will associate a label with an existing picture, indicated by the picture identifier. If the picture identifier is negative then the current picture is used to store the label. If a label already exists for a picture then the old one will be overwritten. The routine AGI_ILAB will return the label of the requested picture. If the picture identifier is negative then the current picture is searched. If no label is associated with this picture then a blank string is returned.

The length of the label string is limited to the number of characters defined by the AGI__SZLAB constant from the AGI_PAR include file (currently 15 characters).