bdfp1m1g | Programming Concepts and Reference |
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
- The type definitions (for example, dft_fil,
dft_ref, and dft_kyl) are defined in the
c$cdfapi.h header file.
- 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. 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 file because a T-type file is a
temporary logical record (LREC) stored in a W-type file and is not defined in
the DBDEF macro. See TPFDF Database
Administration for more information about T-type files.
- If you use this function with a W-type file, the DFOPN_HOLD value is the
default. See TPFDF Database Administration for
more information about W-type files.
- It is not necessary to specify data level independence (DLI) with this
function.
The TPFDF product preserves all data levels holding blocks before a macro or
function call. See Data Level Usage for more information about DLI.
Examples
- The following example opens a subfile that has DSECT name GR91SR.
The 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_HOLD, faddr);
Related Functions
dfcls-Close a Subfile.