Creating a VLF object

To create a VLF object, obtain the object from DASD, then issue the COFCREAT macro. Creating a VLF object means using VLF to add an object to a class of VLF objects in virtual storage. You create a VLF object when an end user requests an object that does not yet exist in VLF storage.

To ensure that 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, VLF requires that you issue COFRETRI to try to retrieve the object before you issue COFCREAT.

Thus, normal processing of an end user request for an object includes the following steps:
  1. Issue the COFRETRI macro to attempt to retrieve the object.
  2. Examine the return code from COFRETRI.
  3. If the return code is 2 or 8, create the object. Between issuing the COFRETRI and the COFCREAT for this object, do not issue any COFRETRI macro with the same UTOKEN but a different minor name.
To ensure the integrity of the data, the working storage that your application uses to create the VLF object must not be key 8 storage, and you must perform the following steps:
  1. Change to (or remain in) supervisor state.
  2. Issue a BLDL macro for the PDS member using the same DDNAME used to identify the user to VLF. VLF guarantees that no manipulations with allocation can allow the user to alter the data sets associated with a DDNAME used to identify a VLF user. In such a case, VLF invalidates that user's token (UTOKEN).
  3. Save the “K” value from a successful BLDL to pass to VLF as the CINDEX value on COFCREAT.
  4. Perform secure I/O to read the object from DASD. Performing secure I/O, which protects the data from malicious tasks, has the following requirements:
    1. The DCB used for I/O must not be in key 8 storage.
    2. The I/O buffers must not be in key 8 storage.
  5. Issue the COFCREAT macro to create the VLF object.
  6. If necessary, copy the object to key 8 storage to enable the user program to access it.

Failure to follow these rules compromises the integrity of data objects in VLF storage. Depending on the nature of the class of VLF objects, incorrect data could cause severe system integrity problems.

To issue COFCREAT, you must specify:
  • The major name for the object:
    • For a non-PDS class, you specify the major name on the MAJOR parameter.
    • For a PDS class, you specify the major name indirectly through the concatenation index on the CINDEX parameter. (You obtain this value by issuing a BLDL macro.)
    This information comes from the end user requesting the object.

    To ensure that VLF does not retain objects containing down-level data, your application must determine the highest level major name (in the user's major name search order) only after it receives a non-zero return code from COFRETRI. For a PDS class, you must issue the BLDL after the COFRETRI.

  • The minor name of the object. This information comes from the end user requesting the object.
  • The user token for the user on whose behalf you are creating this object. This token is the UTOKEN returned when you issued the COFIDENT macro for the user.

You must also describe where VLF can find the source data for the object it is to add to its virtual storage. You provide this source area for the object by defining an object parts list, using two parameters: OBJPLSZ and OBJPRTL.

OBJPLSZ defines the total size of the object parts list. OBJPRTL defines the object parts list, which describes source areas from which VLF can obtain consecutive pieces of the object. There must be at least one source area; there can be as many as sixteen source areas.

To issue COFCREAT, your program must be running under a task with the same home ASID as the issuer of the COFIDENT macro that identified the user.

Parent topic: Using the VLF macros