Reference to data

It may often be desirable to access the data used by one application in a second one. To store the actual data in the database would be wasteful of disk space since this data would be replicated in the original data file and in the database. Even more space would be wasted if the same data was associated with more than one picture in the database. Instead of saving the data in the database AGI stores a reference to it (a string describing it's location) that enables other applications to recover the data.

A reference to a data object is not a compulsory component of a database picture, and as such will not be created when a new picture is inserted in the database. An explicit call to one of the appropriate routines is used to create or access a reference object in the database. The subroutine argument that defines the reference object can be either an HDS locator or any character string reference. If the string is a valid HDS locator then a reference is constructed to point to the relevant object, otherwise the string is assumed to be a reference itself and is stored as supplied. This dual definition of what defines a reference is intended to smooth the transition from applications using raw HDS calls to using NDF routines to access the data. When the NDF reference mechanism is well established the HDS interface will be removed.

A reference is saved in the database by calling the routine AGI_PTREF. The reference structure is stored within the picture indicated by the picture identifier. If the picture identifier is negative then the current picture is used to store the reference. If a reference already exists in the picture then an error status will be returned.

A reference is obtained from the database by calling the routine AGI_GTREF. The reference is obtained from the picture indicated by the picture identifier. If the picture identifier is negative then the current picture is used to obtain the reference. If the reference was created from an HDS locator then an HDS locator is returned and this should be annulled in the application using REF_ANNUL rather than DAT_ANNUL. This will ensure that the file containing the reference is properly shut down.

One important point to note is that AGI does not check if the data being referenced is valid or not.