dftld: Write a subfile from main storage to DASD

Use this function to do one of the following:
  • Write the subfile to DASD
  • Ignore the subfile.

Last updated

  • Changed in 2020.
  • Changed for PUT10.
  • Changed for PUT07.
  • Changed for PUT04.
  • Changed for PUT02.
  • Changed for PUT00.

Format

void dftld(dft_fil *file, dft_opt options);
void dftld_acc(dft_fil *file, dft_opt access, dft_opt options,
     dft_xxx acc);
Access Parameter Values
Read syntax diagramSkip visual syntax diagramDFTLD_ALGDFTLD_FADDRDFTLD_FADDR8DFTLD_ORD
Options Parameter Values
Read syntax diagramSkip visual syntax diagram|DFTLD_CREATEDFTLD_SKIP0
acc
An ordinal number, a file address, or a pointer to an algorithm string that specifies the subfile you want to access. The type for this parameter is determined by the value you specify for the access parameter.
access
is the method you want to use to access the subfile. Use one of the following values:
DFTLD_ALG
specifies that you are providing a pointer to an algorithm argument in the access parameter. The access parameter is of type dft_alg.
Note: The area of storage that contains the algorithm argument must not be modified and must be accessible to the z/TPFDF product until the subfile is closed and the SW00SR is released.
DFTLD_FADDR
specifies that you are providing a 4-byte file address for the acc parameter. A file address is in integer format. The acc parameter is of type dft_fad.
DFTLD_FADDR8
specifies that you are providing a pointer to an 8-byte file address for the acc parameter. The acc parameter is of type * dft_fad8.
DFTLD_ORD
specifies that you are providing an ordinal number in the acc parameter. Ordinal numbers in a file start at zero and are in integer format. The acc parameter is of type dft_ord.

If the file is partitioned or interleaved, specify the relative ordinal number within the partition or interleave. If the file is not partitioned or interleaved, specify the file address compute program (FACE) ordinal number.

file
A pointer to the base address of the SW00SR slot (defined in c_sw00sr.h) of the file that you want to access and is returned by the dfifb or dfopn function. Use the acc parameter to specify a particular subfile to access. If you do not specify the acc parameter, the last subfile accessed with this SW00SR slot will be accessed.
options
are the processing options for this function. Use the following values:
DFTLD_CREATE
writes the subfile to new pool blocks in DASD. (The default is to use the same file addresses as before.)
DFTLD_SKIP
discards the blocks that were read from tape with the dftrd function. The dftld function releases all the blocks, both prime and chained, that the dftrd function retrieved and placed in main storage.

You can use the DFTLD_SKIP option in a restart situation when a number of blocks need to be read from tape or to reach the point where a system failure occurred. (All the blocks up to the failure point have already been written to DASD, so you only need to read them without saving them again.)

The DFTLD_SKIP option is also useful if you want to end the transfer of information from tape to disk, or if there are unwanted blocks of data on a tape.

0
Specifies that you do not want to use any processing options.

Entry requirements

You must successfully read a subfile using the dftrd function before calling the dftld function.

Return conditions

None.

Error return

For information about how to check the error indicators, see Identifying return indicators and errors.

Programming considerations

  • The type definitions (for example, dft_fil, dft_ref, and dft_kyl) are defined in the c_cdfapi.h header file.
  • If the acc parameter contains an address above the 2 GB bar when the access parameter is set to the DFTLD_ALG (pointer to an algorithm) option, performance can be affected.
  • Some parameters can be of different types based on the value you specify for that parameter or a related parameter. In the function format, the type of these parameters is shown as dft_xxx. For more information, see the description of the specific parameter for information about what type definition to use for that parameter.
  • You must always call dftld after calling dftrd. No other function calls are allowed between the dftld and dftrd calls. Ensure your application checks for any error conditions before calling dftld. During dftrd processing, if an error occurs that causes SW00RTN to be nonzero, invoking dftld is treated as an incorrect command sequence.
  • This function rebuilds the B+Tree index for B+Tree files.
  • This function does not support files that can have subfiles stored in a remote data store. If this function is called for a file with the REMOTEALLOW=YES parameter specified in the DBDEF macro, a DB014A system error is issued and the function returns to the application with appropriate error indicators set.
  • Because the dftld function requires a significant amount of system resources, do not use this function in a commit scope. See Commit scopes for more information about commit scopes.

Examples

The following example writes a subfile, specified in alg_ptr, to new pool blocks in DASD. It ignores any blocks that were read from tape by a dftrd. 
dft_fil *file_ptr;
dft_alg *alg_ptr;
⋮
dftld_acc(file_ptr, DFTLD_ALG, DFTLD_SKIP | DFTLD_CREATE, alg_ptr);