dfopn: Open a subfile

Use this group of functions to open a subfile and optionally to start find processing or find-with-hold processing for the prime block of the subfile.

This function is the first z/TPFDF function that you use with any z/TPFDF files, except automatically opened files. The first dfopn function creates a database interface block (DBIFB) and reserves a SW00SR slot in the DBIFB. The SW00SR slot contains control information about the subfile.

Last updated

  • Changed in 2022 (information only; no code change).
  • Changed in 2020.
  • Changed for PUT13.
  • Changed for PUT12.
  • Changed for PUT11.
  • Changed for PUT10.
  • Changed for PUT07.
  • Changed for PUT06.
  • Changed for PUT05.
  • Changed for PUT04.
  • Changed for PUT00.

Format

#include <cdf.h>
dft_fil *dfopn(dft_ref *ref_name, dft_fid *id, dft_opt options);
#include <cdf.h>
dft_fil *dfopn_acc(dft_ref *ref_name, dft_fid *id,
        dft_opt access, dft_opt options, dft_xxx acc);
#include <cdf.h>
dft_fil *dfopn_spa(dft_ref *ref_name, dft_fid *id, dft_opt options,
        dft_spc spc, dft_sps sps);
#include <cdf.h>
dft_fil *dfopn_are(dft_ref *ref_name, dft_fid *id, dft_opt options,
        dft_are *are);
#include <cdf.h>
dft_fil *dfopn_tpn(dft_ref *ref_name, dft_fid *id, dft_opt options,
        dft_tpn tpn);
#include <cdf.h>
dft_fil *dfopn_acc_spa(dft_ref *ref_name, dft_fid *id, dft_opt access,
        dft_opt options, dft_xxx acc, dft_spc spc,dft_sps sps);
#include <cdf.h>
dft_fil *dfopn_acc_are(dft_ref *ref_name, dft_fid *id, dft_opt access,
        dft_opt options, dft_xxx acc,dft_are *are);
#include <cdf.h>
dft_fil *dfopn_acc_tpn(dft_ref *ref_name, dft_fid *id,
        dft_opt access, dft_opt options, dft_xxx acc, dft_tpn tpn);
#include <cdf.h>
dft_fil *dfopn_spa_are(dft_ref *ref_name, dft_fid *id,
        dft_opt options, dft_spc spc, dft_sps sps,dft_are *are);
#include <cdf.h>
dft_fil *dfopn_spa_tpn(dft_ref *ref_name, dft_fid *id,
        dft_opt options, dft_spc spc, dft_sps sps, dft_tpn tpn);
#include <cdf.h>
dft_fil *dfopn_are_tpn(dft_ref *ref_name, dft_fid *id,
        dft_opt options, dft_are *are, dft_tpn tpn);
#include <cdf.h>
dft_fil *dfopn_acc_spa_are(dft_ref *ref_name, dft_fid *id,
        dft_opt access, dft_opt options, dft_xxx acc, dft_spc spc,
        dft_sps sps, dft_are *are);
#include <cdf.h>
dft_fil *dfopn_acc_spa_tpn(dft_ref *ref_name, dft_fid *id,
        dft_opt access, dft_opt options,
        dft_xxx acc, dft_spc spc, dft_sps sps, dft_tpn tpn);
#include <cdf.h>
dft_fil *dfopn_acc_are_tpn(dft_ref *ref_name, dft_fid *id,
        dft_opt access, dft_opt options,
        dft_xxx acc, dft_are *are, dft_tpn tpn);
#include <cdf.h>
dft_fil *dfopn_spa_are_tpn(dft_ref *ref_name, dft_fid *id,
        dft_opt options, dft_spc spc,
        dft_sps sps, dft_are *are, dft_tpn tpn);
#include <cdf.h>
dft_fil *dfopn_acc_spa_are_tpn(dft_ref *ref_name, dft_fid *id,
        dft_opt access, dft_opt options, dft_xxx acc,
        dft_spc spc, dft_sps sps, dft_are *are, dft_tpn tpn);
Access Parameter Values
Read syntax diagramSkip visual syntax diagramDFOPN_ALGDFOPN_FADDRDFOPN_FADDR8DFOPN_ORD
Options Parameter Values
Read syntax diagramSkip visual syntax diagram|DFOPN_INDEX_HOLDDFOPN_NOCHKDFOPN_PREFETCH_PRIMEDetac Mode OptionsHold OptionsDFOPN_NODUMP0
Detac Mode Options
Read syntax diagramSkip visual syntax diagramDFOPN_NODETDFOPN_DETAC
Hold Options
Read syntax diagramSkip visual syntax diagramDFOPN_NOHOLDDFOPN_HOLD1
Notes:
  • 1 The default option for W-type files is DFOPN_HOLD.
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:
DFOPN_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.
DFOPN_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.
DFOPN_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.
DFOPN_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.

are
The address of an area where the user information is copied from index LRECs on subsequent dfred function calls. The data that will be provided is specified on the DBDEF macro for the index file. See data extraction parameter information in z/TPFDF Database Administration for more information about defining this user data.
id
A pointer to the 2-byte file identifier (held in each block of the file). You can specify this in character form or as 4 hexadecimal digits.
options
The processing options for this function. Use the following values:
DFOPN_DETAC
Opens the subfile in detac mode. When the subfile is in detac mode, all modified blocks are saved in main storage. No modified blocks are written to DASD until you checkpoint the subfile (using the dfckp function) or close the subfile (using the dfcls function).

If you do not want to keep any modifications that you made to the subfile opened with DFOPN_DETAC, you can use the DFCLS_ABORT value for the options parameter of the dfcls function.

Notes:
  • When you are using fullfile processing, each subfile, in turn, is put in detac mode, but not the entire file.
  • The z/TPF system issues system error 000010 if an application program does not give up control in the time allotted by the application timeout counter. When processing in detac mode, a z/TPFDF application program can require more than the allotted time on a database with a large data structure. To prevent system error 000010, change the setting of the &TPFDBDV symbol in the DBLCL macro.
  • If you use this function with a W-type file, overflow pools can be written to DASD unless the DETAC parameter is specified when the subfile is opened.
DFOPN_NODET
Specifies that you do not want the subfile opened in detac mode.
DFOPN_HOLD
Potentially holds the subfile that you are accessing and prevents two or more application programs from modifying the subfile at the same time. The subfile is held on the following z/TPFDF call that accesses the subfile if bits 4 and 5 in the &SW00OP2 global set symbol in the DSECT macro, or the OP2, PRIMEHLD, or CHAINHLD parameters in the DBDEF macro, are set appropriately. Subsequent z/TPFDF calls by other ECBs to modify the subfile do not occur until the subfile is no longer held. If more than one application can update the same subfile, or the file is processed in fullfile mode, you must specify this value to ensure the updates are synchronized.

For information about how bits 4 and 5 in the &SW00OP2 global set symbol in the DSECT macro, or the OP2, PRIMEHLD, and CHAINHLD parameters in the DBDEF macro, affect hold processing, see Global DSECT override parameters.

If you use this value to concurrently update multiple subfiles in the same ECB, you must issue the dfopn function in the same order across all ECBs to avoid a deadlock condition.

Note: If you use this function with a W-type file, the DFOPN_HOLD value is the default. For more information about W-type files, see z/TPFDF Database Administration.
DFOPN_NOHOLD
Specifies that the z/TPFDF product does not hold the file blocks and other applications can read or write blocks. (This implies that you are not going to modify the subfile.)
DFOPN_INDEX_HOLD
Potentially holds any index files that reference the subfiles you are accessing and prevents two or more application programs from modifying the index files at the same time. Holding occurs on the following z/TPFDF call that accesses the subfile if bits 4 and 5 in the &SW00OP2 global set symbol in the DSECT macro, or the OP2= parameter in the DBDEF macro, have been set appropriately. Subsequent z/TPFDF calls by other ECBs to modify the index file will not occur until the index file is no longer held. If more than one application can update the same index file, or the file is processed in fullfile mode, you must specify this value to ensure the updates are synchronized.

See z/TPFDF Database Administration for information about how bits 4 and 5 in the &SW00OP2 global set symbol in the DSECT macro, or the OP2= parameter in the DBDEF macro, affect hold processing.

DFOPN_NOCHK
Specifies that you do not want to check the record code check (RCC) value of the blocks that are read from DASD with subsequent dfred function calls. In addition, use this value to prevent the z/TPFDF product from using a random RCC value when creating new subfiles. If this value is used, new subfiles will be created without an RCC value unless you specify the DFOPT_CHKA value on the dfopt function. In this case, new subfiles are created with the RCC specified by the dfopt function.
DFOPN_PREFETCH_PRIME
Specifies that a find function is issued for the prime block. If you specify this value, a waitc function is issued only when the DFOPN_HOLD value is specified and the current ECB is not the owner of the record hold. Before you issue any other z/TPFDF functions (except the dfifb function) that access the returned SW00SR slot, you must issue the dfwait function to complete the outstanding I/O operations.
Before you issue the dfwait function, you can issue multiple dfopn functions with this value specified to open multiple subfiles and to process the underlying I/O operations in parallel.
Notes:
  • You cannot specify this value to open the following files:
    • A detail file or mid-level index file when the DFOPN_ALG value is specified. A detail file or mid-level index file is a file that uses the #TPFDBFF algorithm.
    • A W-type file.
  • If you specify this value, the dfopn function might internally issue a waitc function. The dfwait function returns any errors from waitc function processing.
DFOPN_NODUMP
Specifies that you do not want the z/TPFDF product to issue system errors with return while the z/TPFDF product is processing this function.
Note: Use the DFOPN_NODUMP value with caution because it can prevent the z/TPFDF system errors that indicate a critical problem from being issued.
0
Specifies that you do not want to use any processing options.
ref_name
The address of a variable containing the 8-byte reference name of the subfile to be opened. If less than 8 bytes are provided, it must be null-terminated. The z/TPFDF product will pad it with blanks (X'40') to build an 8-byte reference name.
spc
The character that you want to fill the space area you have requested.
sps
The size of the space area that you need, which can be a maximum of 4069 bytes.
tpn
A pointer to a variable containing a 3-character symbolic name of the tape or sequential data set you want to use. The z/TPFDF product then writes all overflow blocks to tape rather than to DASD.
You cannot use the tpn parameter to open the following files:
  • B+Tree files
  • Files that have the REMOTEALLOW=YES parameter specified on the DBDEF macro

Entry requirements

Ensure that the subfile you open was previously defined in a DSECT macro and in a DBDEF macro instruction by your database administrator.

Return conditions

The address of the SW00SR slot.

Error return

  • For information about how to check the error indicators, see Identifying return indicators and errors.
  • The error indicators in the SW00RTN field of the SW00SR slot have no meaning for this function.

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 access parameter is set to DFOPN_ALG (pointer to an algorithm) and the acc parameter contains an address above the 2 GB bar, performance may 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 cannot use this function with a T-type DSECT because a T-type DSECT represents a temporary logical record (LREC) stored in a W-type file and is not defined in the DBDEF macro. See z/TPFDF Database Administration for more information about T-type DSECTs and W-type files.
  • Any return-optional system errors that occur during dfopn function processing are not reflected in the number of failed I/O operations upon return from dfwait function processing. Check for errors on the dfopn function call.
  • If you specify the DFOPN_PREFETCH_PRIME and DFOPN_HOLD values, dfopn function processing might issue a waitc function in the following situations to avoid deadlocks that result from multiple attempts of the ECB to open the same prime blocks:
    • For non-loosely coupled systems, a waitc function is issued if the record hold request is in the record hold table wait queue.
    • For loosely coupled systems, a waitc function is issued in one of the following situations:
      • The record hold request is in the record hold table wait queue.
      • The record hold request must be sent to an external lock facility. That is, the record ID of the prime block is not defined as LOCK-IN-PROC in the record ID attribute table (RIAT).

    If dfopn function processing issues a waitc function, some of the benefits of the DFOPN_PREFETCH_PRIME value and parallel I/O operations might be lost. In other words, if you use a non-loosely coupled environment, or if you use a loosely coupled environment together with the LOCK-IN-PROC RIAT setting, you can benefit more from using the DFOPN_PREFETCH_PRIME value.

  • If z/TPFDF cache support is active and enabled for this z/TPFDF file and its subfile is opened without the DFOPN_HOLD parameter specified, the following behaviors occur:
    • Detac mode is automatically turned on when the initial file access is done.
    • The DFOPN_NODET option is ignored, if specified.
  • If you open a subfile that is in a remote data store, the following behaviors occur:
    • Detac mode is automatically turned on when the initial file access is done.
    • The DFOPN_NODET option is ignored, if specified.
  • For programming considerations when you use this function with data event processing, see z/TPFDF API programming considerations for data event processing.
  • If a threaded process is using this function, be aware that z/TPFDF does not explicitly release all ECB heap storage upon exit; this can cause a memory leak for long-running thread processes.

Examples

  • The following example opens a subfile that has DSECT name GR91SR. The z/TPFDF product sets a pointer to the SW00SR slot in file_ptr. The file ID is "S0". 
    dft_fil *file_ptr;
file_ptr = dfopn("GR91SR  ", "S0", DFOPN_HOLD | DFOPN_DETAC);
  • The following example opens a subfile that has a DSECT name of GR91SR and requests 50 bytes of space. The file ID is X'C701'. 
    #define file_id "\xC7\x01"
file_ptr = dfopn_spa("GR91SR  ", file_id, DFOPN_HOLD, ' ', 50);
  • The following example opens a subfile that has a DSECT name of GR91SR in detac mode. The program provides a file address in faddr. The file ID is "S0". 
    file_ptr = dfopn_acc("GR91SR  ", "S0", DFOPN_FADDR, DFOPN_DETAC, faddr);
  • In the following example, four subfiles are opened, and the prime blocks of the subfiles are immediately accessed. Two of the subfiles are opened with a hold. The subsequent dfwait function completes the access of all the subfiles. After successful completion, the subfiles are ready for use.
    dft_fil *sw_ptr_01;
dft_fil *sw_ptr_02;
dft_fil *sw_ptr_03;
dft_fil *sw_ptr_04;

sw_ptr_01 = dfopn_acc("GR00SR01", "G0", DFOPN_ALG,
                     DFOPN_PREFETCH_PRIME, "A");
sw_ptr_02 = dfopn_acc("IR90DF  ", "\xBD\x90", DFOPN_ORD,
                     DFOPN_HOLD|DFOPN_PREFETCH_PRIME, 6);
sw_ptr_03 = dfopn_acc("GR00SR02", "G0", DFOPN_ALG,
                     DFOPN_HOLD|DFOPN_PREFETCH_PRIME, "B");
sw_ptr_04 = dfopn_acc("IR90DF  ", "\xBD\x90", DFOPN_ORD,
                     DFOPN_PREFETCH_PRIME, 6);
if (dfwait() != 0)
{
    // Find each SW00SR marked with a serious error
    sw_ptr_wait = dfifb_fst();  // loacte 1st SW00SR
    while (sw_ptr_wait != NULL) // loop trough all SW00SR
    {
      if (DF_ER(sw_ptr_wait))   // serious error detected
      {
        // error processing for this 'error SW00SR'
      }
      sw_ptr_wait = dfifb_nxt(); // loacte next SW00SR
    }                           // end SW00SR loop
}
⋮

For more information about W-type files, see z/TPFDF Database Administration.