dftlg: Write a file or subfile to tape

Use this group of functions to write a file, or part of a file, to a real-time tape, a general tape, or a sequential data set.

Note: The dftlg function does not support large logical records (LLRs).

Last updated

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

Format

void dftlg(dft_fil *file, dft_opt options, dft_tpn *tape);
void dftlg_acc(dft_fil *file, dft_opt access, dft_opt options,
     dft_tpn *tape, dft_xxx acc);
void dftlg_inc(dft_fil *file, dft_opt options, dft_tpn *tape,
     dft_idl *inc_list);
void dftlg_acc_inc(dft_fil *file, dft_opt access, dft_opt options,
     dft_tpn *tape, dft_xxx acc, dft_idl *inc_list);
Access Parameter Values
Read syntax diagramSkip visual syntax diagramDFTLG_ALGDFTLG_FADDRDFTLG_FADDR8DFTLG_ORD
Options Parameter Values
Read syntax diagramSkip visual syntax diagram|DFTLG_DELETEDFTLG_FULLFILEDFTLG_INITIALIZE0
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
The method you want to use to access the subfile. Use one of the following values:
DFTLG_ALG
Specifies that you are providing a pointer to an algorithm argument in the acc parameter. The acc parameter is of type dft_alg.
Notes:
  • The z/TPFDF product uses the algorithm argument to determine the subfile (ordinal number) that is to be accessed. Specify the algorithm argument based on the type of algorithm that is defined in the DSECT or DBDEF macro for the file. If the DSECT or DBDEF macro defines the #TPFDB04 or the #TPFDB0D algorithm, do not use this parameter.
  • If the subfile you are accessing is contained in a detail file or intermediate index file defined with the #TPFDBFF algorithm, the z/TPFDF product uses the algorithm argument to locate the subfile. For more information about how the z/TPFDF product uses the algorithm argument to locate the subfile, see z/TPFDF Database Administration.
  • Any active keys are ignored when you use the #TPFDB0D algorithm.
  • 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.
DFTLG_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.
DFTLG_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.
DFTLG_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.
inc_list
A pointer to a list of file IDs that you want to be included in the action of the function.
options
The processing options for this function. Use the following values:
DFTLG_DELETE
Deletes all the LRECs in the input subfile after the records are written to tape. Any previously chained blocks are returned to pool. If the file is a pool file:
  1. The prime block is also released.
  2. If the subfile is indexed, then:
    1. If an algorithm was specified either on the dftlg function or on a previous API managing this subfile, the subfile is deindexed from the specified path.
    2. If the AUTODEINDEX=YES parameter is specified on the DBDEF macro, the input subfile will be deindexed from all its indexes.
    Note: In both cases, the application cannot open the indexes with the HOLD option in the same ECB.
DFTLG_FULLFILE
Writes LRECs from the whole input file (not from a single subfile) to tape.
DFTLG_INITIALIZE
Deletes all the LRECs in the DASD file after the records are written to tape. Any previously used blocks are returned to pool, except the prime block.
0
Specifies that you do not want to use any processing options.
tape
A pointer to a character array holding the 3-character tape name.

Entry requirements

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 any of the following parameters contain addresses above 2 GB, performance may be affected. The following parameters can affect performance if passed above the 2 GB bar:
    • acc when the access parameter is set to the DFTLG_ALG (pointer to an algorithm) option
    • inc_list (pointer to a list of IDs).
  • 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.
  • After opening a file, if you use fullfile processing to access or update records, you must continue to use fullfile processing on any subsequent functions when available until the file is closed. Accessing or updating subfiles using fullfile processing cannot be mixed with functions that access or update records without using fullfile processing.
  • The dftlg function does not write the B+Tree index information to tape because it is rebuilt when the B+Tree data file is restored.
  • If you specify the DFTLG_FULLFILE value and the end-of-file indicator is set, you cannot issue additional z/TPFDF functions until the file is closed. However, you can specify the DFCLS_REUSE option on the dfcls function. For information about the end-of-file indicator, see Identifying return indicators and errors.
  • If you use the dftlg function in a commit scope, a rollback of the commit scope will not restore the contents or the position of the tape. For more information about commit scopes, see Commit scopes.
  • This function does not support large logical records (LLRs). If an LLR is found, a system error is issued and the function returns to the application with appropriate error indicators set.
  • Related LRECs in the corresponding algorithm information file are not written to tape even if the ALGINFOID parameter is defined in the DBDEF macro.
  • 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 on the DBDEF macro, a DB014A system error is issued and the function returns to the application with appropriate error indicators set.
  • If the AUTODEINDEX=YES parameter is specified on the DBDEF macro and an indexed subfile is empty when the input subfile is written to tape, the input subfile will be deindexed from all its indexes and all corresponding pool file addresses will be released. The application cannot open the indexes with the HOLD option in the sameECB in this case.

Examples

  • The following example writes a complete file to tape. A pointer to the 3-character tape name is in tape_name. 
    dft_tpn *tape_name;
dft_fil *file_ptr;
⋮
dftlg(file_ptr, 0, tape_name);
  • The following example writes a subfile, specified in alg_ptr to tape. A pointer to the tape name is in tape_name. It deletes LRECs in the subfile after the write. 
    dft_tpn *tape_name;
dft_alg *alg_ptr;
dft_fil *file_ptr;
⋮
dftlg(file_ptr, DFTLD_ALG, DFTLG_INITIALIZE, tape_name, alg_ptr);