Retrieving a VLF object

To retrieve a VLF object, issue the COFRETRI macro. Retrieving a VLF object means using VLF to obtain a copy of a VLF object on behalf of an end user. (Your application must check authority to access objects before you issue COFIDENT, the macro that connects the user to a class of VLF objects.) VLF retrieves objects according to the major name search order of the VLF end user, identified by the user token (UTOKEN).

When an end user requests a VLF object, your application must issue COFRETRI to attempt to retrieve the object before attempting to create the object. VLF ensures that, if you follow this processing order, VLF does not create an object if the permanent source data on DASD changes between the time you obtain the object from permanent storage and the time you create the object.

To issue COFRETRI, you must specify:

The minor name of the object. This information comes from the user request.
The user token (UTOKEN). This user token is the token returned from the earlier COFIDENT macro for the user. From the UTOKEN, VLF knows the class and major name search order for the user.

When you issue COFRETRI, you must provide locations where VLF can return the object it retrieves from virtual storage. You provide this area by defining a target area list, using two parameters: TLSIZE and TLIST.

TLSIZE defines the total size of the target area list. TLIST defines the target area list, which describes the target areas into which VLF is to place consecutive areas of the object. There must be at least one target area; there can be as many as sixteen target areas.

You must also provide locations where VLF can return:

The size of the object it retrieves (OBJSIZE).
The concatenation index (CINDEX) of the major name associated with the object. The index is the zero-origin relative number of the major name for the object in the major name list of the user.
For concatenated partitioned data sets, the CINDEX value is the same as the “K” (concatenation index) value returned when a BLDL is performed to locate a member. This value indicates which major name in the concatenation list includes the object that VLF has retrieved.

When control returns to your program from COFRETRI, check the return codes carefully. Possible actions for some common return codes include:

For return code 2 (best available object found), your application can issue a BLDL to determine if the object VLF returned is the correct object. If it is not, use traditional methods to obtain the object from DASD for the user, then issue the COFCREAT macro to create the object in VLF storage.
For return code 4 (the object was found but the target area was too small), provide a larger target area and reissue COFRETRI.
For return code 8 (no object was found), issue a BLDL and use traditional methods to obtain the object from DASD for the user, then issue the COFCREAT macro to create the object in VLF storage.