bdfp1m1gProgramming Concepts and Reference

dfopn-Open a Subfile

Use this group of functions to open a subfile. This is the first TPFDF function you use with any file. 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. See TPFDF General Information for more information about SW00SR and this control information.

Format

dft_fil *dfopn(dft_ref *ref_name, dft_fid *id, dft_opt options);
dft_fil *dfopn_acc(dft_ref *ref_name, dft_fid *id,
        dft_opt access, dft_opt options, dft_xxx acc);
dft_fil *dfopn_spa(dft_ref *ref_name, dft_fid *id, dft_opt options,
        dft_spc spc, dft_sps sps);
dft_fil *dfopn_are(dft_ref *ref_name, dft_fid *id, dft_opt options,
        dft_are *are);
dft_fil *dfopn_tpn(dft_ref *ref_name, dft_fid *id, dft_opt options,
        dft_tpn tpn);
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);
dft_fil *dfopn_acc_are(dft_ref *ref_name, dft_fid *id, dft_opt access,
        dft_opt options, dft_xxx acc,dft_are *are);
dft_fil *dfopn_acc_tpn(dft_ref *ref_name, dft_fid *id,
        dft_opt access, dft_opt options, dft_xxx acc, dft_tpn tpn);
dft_fil *dfopn_spa_are(dft_ref *ref_name, dft_fid *id,
        dft_opt options, dft_spc spc, dft_sps sps,dft_are *are);
dft_fil *dfopn_spa_tpn(dft_ref *ref_name, dft_fid *id,
        dft_opt options, dft_spc spc, dft_sps sps, dft_tpn tpn);
dft_fil *dfopn_are_tpn(dft_ref *ref_name, dft_fid *id,
        dft_opt options, dft_are *are, dft_tpn tpn);
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);
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);
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);
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);
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);



acc
is 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:

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.

The 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 TPFDF product uses the algorithm argument to locate the subfile. See TPFDF Database Administration for more information about how the TPFDF product uses the algorithm argument to locate the subfile.

DFOPN_FADDR
specifies that you are providing a file address in the acc parameter. A file address is in integer format. The acc parameter is of type dft_fad.

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
is the address of an area where the user information is loaded from index LRECs on subsequent dfred function calls. The data that will be provided is specified on the DBDEF macro for the index file.

id
is 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
are 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 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.

Note:
The TPF system and the ALCS environment issues a 000010 system error if an application program does not give up control in the time allotted by the application time-out counter. When processing in detac mode, a TPFDF application program can require more than the allotted time on a database with a large data structure. To prevent the 000010 system error, you can change the setting of the &TPFDBDV symbol in the DBLCL macro.

See TPFDF Installation and Customization for more information about the &TPFDBDV symbol and the DBLCL macro.

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. Holding occurs on the following 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 TPFDF calls by other ECBs to modify the subfile will 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.

See 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_NOHOLD
specifies that the 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 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 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 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 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.

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

ref_name
is the address of a variable containing the 8-byte reference name of the subfile to be opened.

spc
is the character that you want to fill the space area you have requested.

sps
is the size of the space area you require, which can be a maximum of 3952 bytes.

tpn
is a pointer to a variable containing a 3-character symbolic name of the tape or sequential data set you want to use. The TPFDF product then writes all overflow blocks to tape rather than to DASD.

You cannot open B+Tree files using the tpn parameter.

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.

Normal Return

The address of the SW00SR slot.

Error Return

The error indicators in the SW00RTN field of the SW00SR slot have no meaning for this function.

Programming Considerations

Examples

Related Functions

dfcls-Close a Subfile.