bdfp1m1i | Programming Concepts and Reference |
Use this group of functions to read a logical record (LREC) or block header
and get the address where the record is stored. You can read the next
LREC in sequence or specify details of the LREC you require.
You can also use these functions to read a sequence of LRECs. In
this case, you perform a sequence of dfred calls and get a
different LREC each time.
Format
dft_rec *dfred(dft_fil *file, dft_opt options);
dft_rec *dfred_acc(dft_fil *file, dft_opt access, dft_opt options,
dft_xxx acc);
dft_rec *dfred_nbr(dft_fil *file, dft_opt nbr_type,
dft_opt options, dft_xxx nbr);
dft_rec *dfred_are(dft_fil *file, dft_opt options, dft_are *are);
dft_rec *dfred_pth(dft_fil *file, dft_opt options, dft_pth pth);
dft_rec *dfred_acc_nbr(dft_fil *file, dft_opt nbr_type, dft_opt access,
dft_opt options, dft_xxx acc, dft_xxx nbr);
dft_rec *dfred_acc_are(dft_fil *file, dft_opt access, dft_opt options,
dft_xxx acc, dft_are *are);
dft_rec *dfred_acc_pth(dft_fil *file, dft_opt access, dft_opt options,
dft_xxx acc, dft_pth pth);
dft_rec *dfred_nbr_are(dft_fil *file, dft_opt nbr_type, dft_opt options,
dft_nbr nbr, dft_are *are);
dft_rec *dfred_nbr_pth(dft_fil *file, dft_opt nbr_type, dft_opt options,
dft_xxx nbr, dft_pth pth);
dft_rec *dfred_are_pth(dft_fil *file, dft_opt options, dft_are *are,
dft_pth pth);
dft_rec *dfred_acc_nbr_are(dft_fil *file, dft_opt nbr_type, dft_opt access,
dft_opt options, dft_xxx acc, dft_xxx nbr, dft_are *are);
dft_rec *dfred_acc_nbr_pth(dft_fil *file, dft_opt nbr_type, dft_opt access,
dft_opt options, dft_xxx acc, dft_xxx nbr, dft_pth pth);
dft_rec *dfred_acc_are_pth(dft_fil *file, dft_opt access, dft_opt options,
dft_xxx acc, dft_are *are, dft_pth pth);
dft_rec *dfred_nbr_are_pth(dft_fil *file, dft_opt nbr_type, dft_opt options,
dft_xxx nbr, dft_are *are, dft_pth pth);
dft_rec *dfred_acc_nbr_are_pth(dft_fil *file, dft_opt nbr_type,
dft_opt access, dft_opt options, dft_xxx acc, dft_xxx nbr,
dft_are *are, dft_pth pth);
- 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:
- DFRED_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.
- DFRED_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.
- DFRED_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 a pointer to an area to which the TPFDF product copies user data from
the index LREC referencing the detail subfile you are accessing. This
user data is defined in the DBDEF macro of the detail subfile. See TPFDF Database Administration for more information about
defining this user data.
- file
- is a pointer to the base address of the SW00SR slot (defined in
c$sw00sr.h) of the subfile that you want to access
and is returned by the dfopn function.
- nbr
- is a variable containing one of the following based on the value of the
nbr_type parameter:
- A single LREC number (type dft_nbr) if the nbr_type
parameter is set to DFRED_LRECNBR.
- A pointer to a list of LRECs (type dft_rcl) if the
nbr_type parameter is set to DFRED_LIST.
Specify the LRECs in this list as character array. For
example:
char nbrs[10] = "2/3-6/LAST";
The list contains one or more LREC sequence numbers separated by a slash
(/). You can also specify a range of sequence numbers by separating
the beginning and end of the range by a hyphen (-). You can use LAST to
mean the last LREC of the subfile and ALL to mean all the remaining
LRECs. You can also end the list with a nonnumeric character.
Notes:
- The ranges must be in ascending order; if one is found out of order,
that range and all subsequent ranges are ignored.
For example, if there are 41 LRECs in a subfile, the following lists all
have the same effect:
20/31/32/33/37/38/39/40/41
20/31/32/33/37-41
20/31-33/37-LAST
20/31-33/37/ALL
- You cannot specify the number zero in the list of LREC numbers,
even if you specify the ADJUST parameter with a value that would adjust the
number zero to a valid LREC number.
- A stack reference number (type dft_srn) if the
nbr_type parameter is set to DFRED_STACKREF.
- A pointer to a stack area (type dft_stk) if the
nbr_type parameter is set to DFRED_STACK.
Notes:
- If you use the #TPFDB0D algorithm, you must specify a specific LREC number
for the value of nbr.
- LRECs are numbered in increasing order from the start of the subfile (the
first LREC in the prime block has sequence number 1).
- If you specify this parameter with active keys, only those LRECs that
match the key conditions are included in the sequence numbering; LRECs
that do not match are ignored.
- In functions that do not include the nbr_type parameter, the
value of nbr is a specific LREC number.
- nbr_type
- is one of the following:
- DFRED_LIST
- specifies that you are supplying a pointer to a list of LREC numbers (type
dft_rcl) in the nbr parameter. The TPFDF product
reads these LRECs in sequence on subsequent dfred function calls
(unless you change the dfred parameters).
- DFRED_LRECNBR
- specifies that you are supplying the sequence number of a single LREC
(type dft_nbr) in the nbr parameter. The TPFDF
product reads the LREC with this sequence number.
- DFRED_STACK
- specifies that you are supplying a pointer to a stack area (type
dft_stk) in the nbr parameter.
- DFRED_STACKREF
- specifies that you are supplying a stack reference number (type
dft_srn) in the nbr parameter.
The DFRED_STACK and DFRED_STACKREF values allow you to read an LREC that
you have retained with an earlier dfret function.
- options
- are the processing options for this function. Use the following
values:
- DFRED_BACKWARD
- reads backward through the subfile; that is, the TPFDF product reads
the LREC immediately before the current LREC position.
Notes:
- If you use DFRED_BACKWARD and also use the dfret function, you
must specify DFRET_STACK or DFRET_STACKREF with the dfret
function. See dfret-Retain a Logical Record Position for more information about these values and the
dfret function.
- If you use DFRED_BACKWARD, the default and recommended setting for symbol
&DB013A in the DBLCL macro is 0. This setting requires files to use
full backward chaining (bit 0 of &SW00OP1 is set) to read backward.
See TPFDF Database Administration for more
information about defining full backward chaining. See TPFDF Installation and Customization for more information
about the DBLCL macro.
- Exception:
- If the file uses add current processing (bit 2 of &SW00OP1 is set) with
no chains (&SW00NOC = 0), you can specify DFRED_BACKWARD regardless of
how bit 0 of &SW00OP1 is set.
- DFRED_BEGIN
- reads LRECs from the start of the subfile.
- DFRED_LAST
- reads the last LREC from the subfile. If you have specified keys
with the read, the TPFDF product reads the last LREC that matches the
keys.
- DFRED_PREVIOUS
- reads the LREC saved with the last dfret function that used a
DFRET_CURRENT value for the ret_type parameter.
- DFRED_FAST
- used for migration purposes only; use the DFRED_INLINE or DFRED_NOKEY
values instead. If you specify this value, the DFRED_NOKEY value is
implemented; that is, keys that are currently active are
deactivated.
- DFRED_HEADER
- locates the subfile header in the prime block and returns the address in
field SW00RC rather than the address of an LREC.
If you specify the DFRED_HEADER and DFRED_FULLFILE values on an open
subfile, the dfred function retrieves the header of the next
subfile.
- DFRED_INLINE
- provides inline processing for this function. You can only use this
value if you are reading LRECs sequentially, without any key
parameters. This option also deactivates any keys that are currently
active; that is, any previous key arguments are set to zero.
- DFRED_FULLFILE
- reads an LREC from any of the subfiles in the file.
If you do not specify this value, you can only read an LREC in the current
subfile.
- DFRED_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 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.
- DFRED_NODUMP
- specifies that you do not want the TPFDF product to issue any of the
following system errors while processing this function:
- DB0100
- DB0102
- DB0117
- DB0123
- DB0138
- DB0140.
See Messages (System Error, Online, Offline) and
Master Glossary for more information about these system errors.
- Note:
- Using the DFRED_NODUMP value is not recommended because it can prevent system
errors from being issued that indicate a critical problem.
- DFRED_NOKEY
- deactivates any currently active keys.
- DFRED_USR
- returns a pointer to the userLREC. Use this option when working
with extended LRECs. See Using Extended Logical Records for more information about extended LRECs.
- 0
- specifies that you do not want to use any processing options.
- pth
- is the path number for a detail subfile using index support. The
value is defined in the DBDEF macro and is a decimal number (0, 1, 2, and so
on). The default path number is 0.
See TPFDF Database Administration for more
information about path indexes.
Entry Requirements
If you specify the DFRED_PREVIOUS, DFRED_STACK, or DFRED_STACKREF values,
you must first open the subfile using the DFOPN_DETAC or DFOPN_HOLD values for
the options parameter on the dfopn function.
Normal Return
- If you specify the DFRED_USR value, a pointer to the userLREC portion of
the extended LREC is returned.
- If you specify the DFRED_HEADER value, a pointer to the standard header of
the block is returned.
- In all other cases, a pointer to the LREC that is read is returned.
Error Return
See Identifying Return Indicators and Errors for information about how to check the error
indicators.
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.
- 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.
- Note:
- The DFRED_HEADER value can be used with the DFRED_FULLFILE value to move from
subfile to subfile, which can then be accessed using the DBRED macros that do
not use the DFRED_FULLFILE value.
- If you have set up keys with the file you are reading (using the
dfkey function), the TPFDF product ignores LRECs where the LREC key
does not match the keys.
- If you specify the DFRED_FULLFILE option, and the end-of-file indicator is
set, you cannot issue additional TPFDF functions until the file is
closed. However, you can specify the DFCLS_REUSE option on the
dfcls function. See Identifying Return Indicators and Errors for information about the end-of-file
indicator.
- Any active keys are ignored when you use the #TPFDB0D
algorithm.
- To ensure an LREC is retrieved accurately when you use the
dfred function, do not use the dfret function with the
DFRET_STACK and DFRET_STACKREF values specified on the same open file.
If you do, the wrong LREC could be retrieved. You must close and reopen
the file each time you alternate between specifying the DFRET_STACK and
DFRET_STACKREF values.
Examples
- The following example reads an LREC from the current subfile. The
new LREC goes into lrec_ptr.
dft_fil *file_ptr;
struct gr95sr *lrec_ptr;
·
·
·
lrec_ptr = dfred(file_ptr, 0);
- The following example reads an LREC retained from a subfile. The
subfile is specified with an algorithm. (The program has set up a
pointer to the algorithm argument in member_number.)
dft_fil *file_ptr;
char member_number[10];
·
·
·
lrec_ptr = dfred_acc(file_ptr, DFRED_ALG, DFRED_PREVIOUS, member_number);
- The following example shows how to read a file using keys, without using
default keys.
struct gr95sr lrec_def;
struct gr95sr *lrec_ptr;
dft_kyl select_keylist;
df_nbrkeys(&select_keylist,4);
df_setkey(&select_keylist,1,offsetof(lrec_def,lrec_id),
member_size(lrec_def,lrec_id),DF_EQ,NULL,X'80',
DF_UPORG,DF_CONST);
df_setkey(&select_keylist,2,offsetof(lrec_def,key1),
member_size(lrec_def,key1),DF_EQ,search_name,0,
DF_UPORG,DF_CHAR);
df_setkey(&select_keylist,3,offsetof(lrec_def,key2),
member_size(lrec_def,key2),DF_EQ,search_city,0,
DF_UPORG,DF_CHAR);
df_setkey(&select_keylist,4,offsetof(lrec_def,key3),
member_size(lrec_def,key3),DF_EQ,search_sal,0,
DF_UPORG,DF_CHAR);
dfkey(file_ptr,&select_keylist);
lrec_ptr = dfred(file_ptr, 0);
- The following example shows how to read a file using read-only and
read-write default keys.
After the prototype LREC is initialized to zeros, each of the selection key
values (including the primary key) is copied into the prototype LREC. A
call to the df_setkey_dbdef function sets up the selection
key list structure and a call to the dfkey function copies the
default key values from the key list into the SW00SR. Finally, a call
to the dfred function returns the next LREC that matches the
default keys. See df_setkey-Setting Up a Key in a Key List for more information.
struct gr95sr proto_lrec;
dft_kyl select_keylist;
memset(&proto_lrec, 0x00, sizeof(proto_lrec));
proto_lrec.lrec_id = 0x80;
memcpy(proto_lrec.key1,search_name,sizeof(proto_lrec.key1));
memcpy(proto_lrec.key2,search_city,sizeof(proto_lrec.key2));
memcpy(proto_lrec.key3,search_sal,sizeof(proto_lrec.key3));
df_setkey_dbdef(&select_keylist,&proto_lrec,0x80);
dfkey(file_ptr,&select_keylist);
lrec_ptr = dfred(file_ptr,0);
df_setkey_dbdef(&select_keylist,&proto_lrec,0x06);
dfkey(file_ptr,&select_keylist);
lrec_ptr = dfred(file_ptr,0);
- The following example shows how to read a file using Boolean logic.
It sets up a key list containing three Boolean logic keys before reading the
LREC.
The logic used is equivalent to:
gr95key AND (gr95nam OR gr95adr).
See df_setkey-Setting Up a Key in a Key List for more information about setting up a key list for Boolean
logic.
dft_rec *lrec91;
dft_pky pky = 0x80;
dft_pky name1 = "Smith";
dft_pky addr1 = "Main Street";
dft_kyl keys;
/* set up the keys */
df_nbrkeys(&keys, 3);
df_setkey_bool(&keys, 1, offsetof(struct gr95sr, gr95key),
1, DF_EQ, &pky, 0, DF_UPORG, DF_CHAR, DF_ANDIF);
df_setkey_bool(&keys, 2, offsetof(struct gr95sr, gr95nam),
10, DF_EQ, &name1, 0, DF_UPORG, DF_CHAR, DF_OR);
df_setkey(&keys, 3, offsetof(struct gr95sr, gr95adr),
10, DF_EQ, &addr1, 0, DF_UPORG, DF_CHAR);
/* activate the key list */
dfkey(file_ptr, &keys);
/* read an LREC with matching primary key and either matching */
/* the name or the address. */
/* (start at the beginning of the subfile) */
lrec91 = dfred(file_ptr, DFRED_BEGIN);
- The following example shows how to read an LREC from a detail file using
index support. First, open the detail file normally, specifying a DSECT
name as the first parameter and then use a dfred function to read
the LREC by providing an index key string as an algorithm argument.
dbptr = dfopn ("GR44DF ",.........)
alg_string="ALDER";
dfred_acc (dbptr,DFRED_ALG,alg_string);
Related Functions