bdfp1m18 | Programming Concepts and Reference |
Use this group of functions to display the logical records (LRECs) from a
subfile.
Format
void dfdsp(dft_fil *file, dft_opt options);
void dfdsp_acc(dft_fil *file, dft_opt access,
dft_opt options, dft_xxx acc);
void dfdsp_str(dft_fil *file, dft_opt options, dft_str str);
void dfdsp_acc_str(dft_fil *file, dft_opt access,
dft_opt options, dft_xxx acc, dft_str str);
void dfdsp_acc_opm(dft_fil *file, dft_opt access,
dft_opt options, dft_xxx acc, dft_opm *opm);
void dfdsp_str_opm(dft_fil *file, dft_opt options,
dft_str str, dft_opm *opm);
void dfdsp_acc_str_opm(dft_fil *file, dft_opt access, dft_opt options,
dft_xxx acc, dft_str str, dft_opm *opm);
- 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:
- DFDSP_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.
- DFDSP_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.
- DFDSP_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
- 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.
- opm
- is a pointer to the output message transmitter (OPMT) parameters (the
5-byte indicators for UIO).
- options
- are the processing options for this function. Use the following
values:
- DFDSP_FULLFILE
- allows you to display LRECs from the whole file instead of from just one
subfile.
Do not use this value with W-type files or the DFDSP_NOCLOSE value.
- DFDSP_LONGTERM
- instructs the application program to use the MOSG internal program to
build the output message (OMSG) display using long-term pool records.
If you do not specify this value, short-term pool records are used for the
display by the FMSG program.
- DFDSP_NOCLOSE
- specifies that you do not want to close the subfile displayed with the
dfdsp function. This allows the application program to
return to the open subfile once the function has completed processing.
If you specify this value, ensure you specify that control is returned to the
application program after the function completes its processing.
- DFDSP_NOFINAL
- indicates that this is only part of a message. The complete output
message is displayed only when you call the dfdsp function without
the DFDSP_NOFINAL value specified.
- DFDSP_NOKEY
- deactivates any currently active keys.
- DFDSP_NOUIO
- prevents the activation of the output edit CRT driver (UIO) and returns to
the application program.
- DFDSP_RELFC
- releases the subfile and deletes it from DASD. All overflow blocks
are released. If the file is a pool file, the prime block is also
released. If the file is a fixed file, the prime block is initialized
to empty.
W-type files are automatically released unless they have been sorted,
merged, or checkpointed. In these cases, you must specify the
DFDSP_RELFC value to release W-type files.
- DFDSP_WTOPC
- displays the LREC in WTOPC format. (By default, the function uses
OMSG format.) This value indicates that the maximum length displayed
for an LREC will be 255 bytes. The DFDSP_LONGTERM and DFDSP_NOUIO
values and opm parameter are ignored.
- 0
- specifies that you do not want to use any processing options.
- str
- is a variable containing the number of bytes that you want to strip from
the start of each LREC (or from the start of the user portion of an extended
LREC).
Variable length LRECs contain a 2-byte size field at the front of the user
data section. The dfdsp function automatically discards this
field; do not include it in the number of bytes you specify with this
parameter.
Entry Requirements
None.
Normal Return
None.
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.
- The TPFDF product does not normally return control to the application when
you call dfdsp functions. The application exits unless you
specify DFDSP_NOUIO or DFDSP_NOFINAL, or you specify not to exit using the
opm parameter. However, you must still test SW00RTN for errors
because control is returned to the program if there are no LRECs to display,
or if an error condition occurs.
- Note:
- Although the TPFDF product preserves all data levels across TPFDF macro
calls, the following exceptions exist when you use the dfdsp
function:
- Data level 1 (D1) and data level 3 (D3) are not data level
independent (DLI) if you do not specify the DFDSP_WTOPC value and DBLCL macro
symbol &ACPDBAA is set to zero.
- Data level 2 (D2) is not DLI.
- You can limit the number of output lines displayed by the dfdsp
function by using the #DF_MAX_DSP equate in the ACPDBE macro. See TPFDF Installation and Customization for more information
about the ACPDBE macro.
- You cannot use the dfdsp function in a commit scope. See
Commit Scopes for more information about commit scopes.
Examples
The following example displays a message consisting of all the LRECs from a
subfile pointed to in file_ptr. The subfile is released after
use.
dft_fil *file_ptr;
·
·
·
dfdsp(file_ptr, DFDSP_RELFC);
Related Functions
dfcls-Close a Subfile.