The requirements for the caller are:

• Your program must be running under a task with the same home ASID as the issuer of the COFIDENT macro that identified the user.
• For non-PDS classes, you can issue COFCREAT with the REPLACE option. If you specify REPLACE, VLF does not require that COFRETRI precede COFCREAT. Because VLF cannot then guarantee that the source object has not changed, your application must ensure that the source object remains unchanged between the time when you reference the source object to create the object parts list and the time when you receive control back from COFCREAT.

  If you do not specify REPLACE, you must issue the COFRETRI macro before you issue COFCREAT.

• 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. If a user changes the data set allocation associated with a DDNAME used to identify a VLF user, 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. Read the object from DASD, ensuring the following:
     • The DCB used for I/O must not be in key 8 storage.
     • 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 steps 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.

• If you do not specify REPLACE and issue COFCREAT for an object that already exists in VLF storage, VLF returns a successful completion code but does not replace the object data. In this case, VLF assumes that the data you supply is identical to the data that already exists in its storage.

  If you specify REPLACE and issue COFCREAT for an object that already exists in VLF storage, VLF does replace the existing object with the parts specified in the object parts list.

None.

Before issuing the COFCREAT macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.

Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.

None.

The standard form of the COFCREAT macro is written as follows:

The parameters are explained as follows:

MAJOR=major

Specifies the major name of the object to be created. The length of the major name must be the same as the length specified by MAJLEN on the COFDEFIN macro that defined the class of objects. Specify MAJOR only for a non-PDS class. (For a PDS class, you must use CINDEX and DDNAME.)

CINDEX=cindex

Identifies a one-byte field that contains the concatenation index of the major name associated with the object being created. CINDEX is required for a PDS class. The index is the zero-origin relative number of the major name for the object in the major name list of the user creating the object. This list is the one supplied to VLF on the COFIDENT macro that identified the user to VLF.

For concatenated partitioned data sets, the CINDEX value is the same as the “K” (concatenation index) value returned when your application issued a BLDL macro to locate a member.

When you specify CINDEX, you must also specify DDNAME.

,DDNAME=ddname

Specifies the 8-character DDNAME of the concatenated data set list. DDNAME is required for a PDS class. This DDNAME must be the same as the one supplied to VLF on the COFIDENT macro that identifies the user to VLF. It represents the major name search order for this identified user.

When you specify DDNAME, you must also specify CINDEX.

,REPLACE=YES

,REPLACE=NO

Indicates that an object existing in VLF should (REPLACE=YES) or should not (REPLACE=NO) be replaced by the parts in the input object parts list. If the object does not exist in VLF, then VLF creates a new object.

,MINOR=minor

Specifies the minor name of the object. The length of the significant portion of the name depends on the MINLEN value defined for the class on the COFDEFIN macro, either explicitly or by default. (For a PDS class, the length is always 8.)

,UTOKEN=utoken

Specifies the required 16-character user token returned from the COFIDENT macro for the user on whose behalf your application is issuing COFCREAT.

,OBJPRTL=objprtl

Specifies the required object parts list. The object parts list describes the source areas from which VLF can obtain consecutive parts of the object. The object parts list consists of a fullword containing the number of object parts, followed by three words for each part:

1. A fullword that contains the ALET that currently addresses the part. An ALET of 1, referencing the SASN of the caller, or ALETs referencing entries on the PASN access list of the caller, are not allowed.
2. A fullword that contains the 31-bit address of the data for the part.
3. A fullword that contains the length of the part.

The number of parts list entries must be from 1 to 16. If your program is not running in access register (AR) ASC mode, the ALET(s) must be zero.

,OBJPLSZ=objplsz

Specifies the required fullword field that contains the size (in bytes) of the object parts list.

,RETCODE=retcod

Specifies the location where the system is to store the return code. The return code is also in general purpose register (GPR) 15. If you specify a storage location, it must be on a fullword boundary,

,RSNCODE=rsncod

Specifies the location where the system is to store the reason code. If you specify a storage location, it must be on a fullword boundary. The reason code is also in GPR 0.

None.

When the COFCREAT macro returns control to your program, GPR 15 (and retcod, if you coded RETCODE) contains one of the following hexadecimal return codes. GPR 0 (and rsncod, if you coded RSNCODE) contains one of the following reason codes.