DBDSP: Display logical records from a subfile

Use this general macro to display the logical records (LRECs) from a subfile.

Last updated

Changed in 2024 (information only; no code change).
Changed in 2021.
Changed in 2020 (information only; no code change).
Changed for PUT10.
Changed for PUT07.
Changed for PUT06.
Changed for PUT05.
Changed for PUT04.
Changed for PUT03.
Changed for PUT00.

Format

Notes:

¹ See Specifying file organization with keyn parameters for information about the rules for using the KEYn parameters and file organization parameters together.

Key Subparameters

REF=dsectvv

Specifies the file that you want to access, where dsectvv is the 6-character DSECT name and an optional 1- or 2-character suffix. If a suffix is omitted, the DSECT name will be padded with blanks (X'40') to build an 8-byte character string.

The reference name can be any 8-byte value that is unique for the current ECB. If you specify the same reference name more than once, a DB0170 system error may occur on any subsequent command if the z/TPFDF product needs to search for the SW00SR slot with this duplicate reference name.

REF=refname

Specifies the name associated with the file that you want to access, where refname is a label that references the name in one of the following formats:

refname: The label of an 8-byte field that contains the reference name.
A⁄refname: The label of a 4-byte field that contains the storage address of an 8-byte field that contains the reference name.

FILE=dsect

Specifies the file or subfile that you want to access, where dsect is the 6-character DSECT name.

R3=address

Specifies the location of the SW00SR slot for this subfile, where address is the label of a field that contains the address of the SW00SR slot. Register 3 (R3) will be loaded with this address. If R3 already contains the address of the SW00SR slot before this macro is called, you do not need to specify the R3 parameter.

Note: Do not use this and the FILE parameter; they are provided only for migration purposes. Use the REF parameter to specify the file that you want to access.

AMODE

Specifies the addressing mode that is being used when the macro is called. Specify one of the following values:

amodedef: The value that is specified by the AMODE parameter on the BEGIN macro. If the AMODE parameter is not specified on the BEGIN macro, the default value is 31.
31: Indicates that 31-bit addressing mode is in use.
64: Indicates that 64-bit addressing mode is in use.

ALG=algarg

Identifies the subfile that you want to access, where algarg specifies an algorithm argument.

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.

Specify algarg as one of the following:

A register that contains the address of the algorithm argument
A literal value that specifies the algorithm argument (for example, ALG==C'SMITH')
A label in one of the following formats:

algarg

The label of a field that contains the algorithm argument.

A⁄algarg

The label of a 4-byte field that contains the storage address of the algorithm argument.

Note: 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.

FADDR=faddr

Identifies the subfile that you want to access, where faddr is one of the following:

faddr: The label of a 4-byte field that contains the file address of the prime block of the subfile.
A⁄faddr: The label of a 4-byte field that contains the storage address of the file address of the prime block of the subfile.

FADDR8=faddr8

Identifies the subfile that you want to access, where faddr8 is one of the following:

faddr8: The label of an 8-byte field that contains the file address of the prime block of the subfile.
A⁄faddr8: The label of a 4-byte field that contains the storage address of the 8-byte file address of the prime block of the subfile.

ORD=ordnum

Identifies the subfile that you want to access, where ordnum is one of the following:

ordnum: The label of a 4-byte field that contains the ordinal number of the subfile.
A⁄ordnum: The label of a 4-byte field that contains the storage address of the ordinal number of the subfile.

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.

CHKA=rcc

User supplied record code check (RCC) used in the created subfile, where rcc is the label of a 1-byte field that contains the RCC value.

ERROR=spmlbl

Branches to the specified location if a serious error is detected when processing the macro, where spmlbl is a z/TPFDF structured program macro (SPM) label defined with the #LOCA macro. For more information about serious errors, see Identifying return indicators and errors. For more information about the #LOCA macro, see z/TPF and z/TPFDF Structured Programming Macros.

ERRORA=asmlbl

Branches to the specified location if a serious error is detected when processing the macro, where asmlbl is an assembler label. For more information about serious errors, see Identifying return indicators and errors.

FULLFILE

Allows you to display LRECs from the whole file instead of from just one subfile. Do not use this parameter with W-type files or the NOCLOSE parameter.

INTERLV

Specifies the interleave that you want to use. Specify one of the following:

intrlvnum

One of the following:

A register that contains the address of the interleave number
An absolute value representing the interleave number
The label of a 2-byte field that contains the interleave number.

ALL

Specifies all interleaves. Use this value when you use fullfile processing to ensure that you do not miss an LREC located in a different interleave.

If you specify this parameter, the maximum interleave number must be defined in the DSECT or DBDEF macro. For more information about interleaves, see z/TPFDF Database Administration.

PARTITN

Specifies the partition that you want to use. Specify one of the following values:

partitnum

One of the following conditions:

A register that contains the partition number
An absolute value representing the partition number
The label of a 2-byte field that contains the partition number.

ALL

Specifies all partitions. Use this value when you use fullfile processing to ensure that you do not miss an LREC located in a different partition.

If you specify this parameter, the number of partitions and the end ordinal must be defined in the DSECT or DBDEF macro. For more information about partitions, see z/TPFDF Database Administration.

Notes:

Do not use this parameter with the #TPFDB0F algorithm. This algorithm computes the partition used from the algorithm argument.
If you specify PARTITN when opening an indexed detail file (#TPFDBFF algorithm), the partition value will be used in combination with the algorithm argument (ALG parameter) to retrieve the appropriate fixed file record.

For more information about algorithms, see z/TPFDF Database Administration.

KEYn

Specifies the key parameters that you want to use with this macro, where n is a number in the range 1 - 6. You can specify as many as six KEYn parameters and they must be specified in sequential order beginning with 1. That is, you cannot code a KEY2 parameter without a KEY1 parameter, a KEY3 parameter without the KEY1 and KEY2 parameters, and so on.

If you use these parameters, you must also specify the file organization of the keys. For more information about how to do this, see Specifying file organization with keyn parameters. Use one or more of the following subparameters with the KEYn parameter:

PKY=primarykey

Specifies a value that will be compared against the primary key of an LREC, where primarykey is a 1-byte immediate value; for example:

… KEY1=(PKY=#RR00K80)

This has the same effect as:

… KEY1=(R=RR00KEY,S=#RR00K80)

R

Specifies a field in the LREC to be compared with the search argument specified with the S subparameter or to be tested against the mask specified with the M or D subparameter.

T

Specifies a field in the subLREC of an extended LREC to be compared with the search argument specified with the S subparameter or to be tested against the mask specified with the M or D subparameter.

fldname

The name of a field defined in the DSECT for the LREC; for example:

… KEY1=(PKY=#GR00K80),KEY2=(R=GR00FLD,S=EBW000)

label1

A 2-byte field containing the displacement into the LREC; for example:

… KEY1=(PKY=#GR00K80),KEY2=(R=EBX010,S=EBW000,L==H'4')

D⁄absval

Specifies the displacement into the LREC of the field, where absval is an absolute value; for example:

… KEY1=(PKY=#GR00K80),KEY2=(R=D/2,S=EBW000,L=L'GR00NAM,UP)

You can also specify the absolute value implicitly; for example:

… KEY1=(PKY=#GR00K80),KEY2=(R=D/GR00NAM-GR00REC,S=EBW000,L=L'GR00NAM,UP)

literal

A halfword literal containing the displacement into the LREC; for example:

… KEY1=(PKY=#GR00K80),KEY2=(R==H'2',S=EBW000,L==H'4')

flddisp

The displacement off the field of the LREC; for example:

… KEY1=(PKY=#GR00K80),KEY2=(R=GR00FLD+2,S=EBW000,L==H'4')

… KEY1=(PKY=#GR00K80),KEY2=(R=GR00FLD+L'GR00FLD,S=EBW000,L==H'4')

C=condition

Specifies the condition to be used when comparing fields in the logical record (specified with the R subparameter) with the search argument (specified with the S or PKY subparameter) or with the bit mask (specified with the M or D subparameter).

If you specify the S or PKY subparameter, use one of the following values:

Table 1. S and PKY parameter conditions
Value	Condition
EQ	Equal (this is the default)
E	Equal
NE	Not equal
GE	Greater than or equal
LE	Less than or equal
GT	Greater than
LT	Less than
H	High
L	Low
NH	Not high
NL	Not low.

If you specify the M or D subparameter, use one of the following values:

Table 2. M and D parameter conditions
Value	Condition
Z	Zeros
O	Ones
M	Mixed
NZ	Not zeros
NO	Not ones
NM	Not mixed.

D=dynmask

Specifies the label of a 1-byte field containing a mask to be tested against the LREC field specified with the R or T subparameter; for example:

… KEY1=(PKY=#GR00K80),KEY2=(R=GR00FLD,D=EBW000,C=Z)

M=mask

Specifies a mask to be tested against the LREC field specified with the R or T subparameter; for example:

… KEY1=(PKY=#GR00K80),KEY2=(R=GR00FLD,M=X'80',C=Z)

S=searcharg

Specifies the search argument to be compared with the LREC field specified with the R or T subparameter, where searcharg is one of the following:

A register that contains the address of the search argument
A literal that represents the search argument
A label in one of the following formats:

searcharg

The label of the search argument.

A⁄searcharg

The label of a 4-byte field that contains the storage address of the search argument.

P⁄searcharg

The label of a field that contains the search argument in packed decimal format.

If you specify P⁄searcharg or a literal in the form of =P "…", the LREC field and search argument are compared as decimal numbers in packed format. Otherwise, the LREC field and search argument are compared as character data.

Notes:

When you use this parameter, you cannot specify the core block reference word (CBRW) or file address reference word (FARW) fields in an ECB.
Do not use literals with the S parameter. For example, do not code the following statement:
```
 S==AL2(#MYVALUE)
```
If a literal is used and subsequent processing in the same ECB attempts to reuse the key information in a different program, the key information might be inaccessible and a system error may occur.

L=length

Specifies the length of the search argument, where length is one of the following:

The address of a 2-byte field containing the length of the search argument
A 2-byte literal
An absolute value in the form of L'fldname (for example, L=L'GR92FLD).

The default value is the length of the field specified with the R subparameter.

UP

Specifies that the key field is in ascending order in the subfile.

DOWN

Specifies that the key field is in descending order in the subfile.

NOORG

Specifies that the key field is in no particular order in the subfile.

NOKEY

Deactivates any currently active keys.

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.

NOCLOSE

Specifies that you do not want to close the subfile displayed with the DBDSP macro. This allows the application program to return to the open subfile once the macro has completed processing. If you specify this parameter, you cannot specify the FULLFILE parameter. In addition, if you specify the NOCLOSE parameter, ensure that you specify control be returned to the application program after the DBDSP macro processes.

NOFINAL

Indicates that this is only part of a message. The complete output message is displayed only when you code the DBDSP macro without the NOFINAL parameter specified.

NOPGM

Specifies not to change the program stamp in a block when filing it.

NOUIO

Prevents the activation of the output edit CRT driver (UIO) and returns to the application program.

OPMT=opmtbits

Specifies how you want the FMSG program to format the output message, where opmtbits is the value of the bit settings as defined in the UI2PF DSECT (labels UI2INC - UI2CNN). Specify one of the following:

opmtbits: The label of a 5-byte field that contains the bit settings.
A/opmtbits: The label of a 4-byte field that contains the storage address of the bit settings.

If you do not specify this parameter, the default value for these bytes is X'10F2C20080'. If you specify the LONGTERM parameter, the default value is X'05F2C20090'.

If you specify a value with the OPMT parameter and do not specify NOUIO, control is returned to the application program only if an error occurs.

PATH=pathnum

Specifies the path number for a detail subfile using index support, where pathnum is the path number or the label of a 2-byte field that contains the path number. The number of index paths used is defined by your database administrator. If there is only one index path, do not specify this parameter.

For more information about path numbers, see z/TPFDF Database Administration.

RELFC

Marks the subfile to be released when the subfile is closed. If the NOCLOSE parameter is specified on the DBDSP macro, subsequent processing can reset the release indicator in the prime block before the subfile is closed, for example, if an LREC is added.

If the subfile is a remote subfile, the document that corresponds to the subfile is deleted from the remote data store.

If the subfile is still marked to be released when the subfile is closed, all overflow blocks are released.

If the file is a pool file, the following conditions occur:

The prime block is also released.
If the subfile is indexed, one of the follow conditions occurs:
- If an algorithm was specified either on the DBDSP macro or on a previous API that manages this subfile, the subfile is deindexed from the specified path.
- If the AUTODEINDEX=YES parameter is specified on the DBDEF macro, the subfile will be deindexed from all its indexes.
Note: In both cases, the application cannot open the indexes with the HOLD parameter in the same ECB.

If the file is a fixed file, the prime block is initialized to empty.

Because W-type files are released automatically, you do not need to specify the RELFC parameter to release W-type files unless they have been sorted, merged, or checkpointed.

Note: Except for indexing errors, if an error occurs before the subfile is closed, the RELFC parameter is ignored.

STRIP=striplen

Discards data from the user data area of an LREC that you do not want to display, where striplen is the length of the part of the LREC that you want to discard starting from the beginning of the LREC (or of the user portion of an extended LREC). Specify one of the following:

A register containing the number of bytes that you want to discard.
The label of a 2-byte area that contains the number of bytes that you want to discard.

Variable length LRECs contain a 2-byte size field at the front of the user data section. The DBDSP macro automatically discards this field; do not include it in the number of bytes you specify with the STRIP parameter.

Do not use registers R14 or R15 with the STRIP parameter.

SUFFIX=char

Allows you to use the same DSECT to map two different areas of storage, where char is the suffix character.

UP

Specifies that the LRECs are organized in the subfile in ascending order of key fields.

DOWN

Specifies that LRECs in the subfile are organized in descending order of key fields.

NOORG

Specifies that the LRECs are organized in the subfile in no particular order. (NOORG is the default if subfile organization has not been defined in the DBDEF).

WTOPC

Specifies the format in which the LRECs are displayed, as follows:

YES: Specifies to use the WTOPC format. With the WTOPC format, the maximum length displayed for an LREC is 255 bytes, and the LONGTERM, NOUIO, and OPMT parameters are ignored.
NO: Specifies to use OMSG format will be used.

REG=register

Specifies a register in which to return the address of the current LREC, which is also contained in SW00SR field SW00REC.

Entry requirements

None.

Return conditions

The SW00RTN field is set to zero.
For information about how to check the error indicators, see Identifying return indicators and errors.

Programming considerations

For information about macro register conventions, see Assembler program register conventions.
The contents of R3, which contains the storage address of the SW00SR slot, are used by z/TPFDF macro calls. Do not change the value of R3 between macro calls unless you save the value after each macro call and restore the value before each macro call.
If register R8 is not used as a base register, its contents are unknown upon return from this macro. If R8 is used as a base register, its contents are unchanged.
All data, address reference fields, and storage areas that are passed to the z/TPFDF product assembler macros must reside below 2 GB in storage unless otherwise noted.
If a literal value is specified as a parameter, the program must have a base register.
The optional 2-character version on the REF parameter allows you to access more than one subfile in the same file at the same time. For example, you can code REF=IR71DF01,ALG==C"A" to access subfile A and REF=IR71DF02,ALG==C"B" to access subfile B.
If you specify a label, the label must be more than 3 characters long.
After opening a file, if you use fullfile processing to access or update records, you must continue to use fullfile processing on any subsequent macros when available until the file is closed. Accessing or updating subfiles using fullfile processing cannot be mixed with macros that access or update records without using fullfile processing.
The subfile you select must contain LRECs with only extended binary code decimal interchange code (EBCDIC) characters that can be displayed (such as, letters, numbers, punctuation, and so on).
The ECB exits after a successful display unless you specify NOUIO or NOFINAL, or you specify not to exit using OPMT.
Although the z/TPFDF product preserves all data levels across z/TPFDF macro calls, the following exceptions exist when you specify the DBDSP macro:
- Data level 1 (D1) and data level 3 (D3) are not data level independent (DLI) if the WTOPC parameter is specified with the NO value (the default), or the YES value is not specified, and DBLCL macro symbol &ACPDBAA is set to zero.
- Data level 2 (D2) is not DLI.
You cannot use this macro with P-type files.
You can limit the number of output lines displayed by the DBDSP macro by using the #DF_MAX_DSP equate in the ACPDBE macro.
If you use this macro to display a large logical record (LLR), only the data in the first 4-K block of the LLR is displayed.
You cannot use this macro in a commit scope. See Commit scopes for more information about commit scopes.
If the AUTODEINDEX=YES parameter is specified on the DBDEF macro and an indexed subfile is empty when the subfile is displayed, the subfile will be deindexed from all its indexes and all corresponding pool file addresses will be released. The application cannot open the indexes with the HOLD parameter in the same ECB in this case.

Examples

In the following example, the amount of data to be stripped is equal to the length of the field GR25KEY:

DBDSP REF=GR25DF,STRIP==AL2(L'GR25KEY)

The following example displays all LRECs in the subfile that is specified by the 8-byte prime file address.

FA4X4C ACTION=4TO8,FA4=(R5),FA8=MYFADDR
DBDSP  REF=ILLRDF,ERROR=ERRLOC,FADDR8=MYFADDR,,STRIP==AL2(1),    *
       KEY1=(PKY=#ILLRK80)
#IF    CLI,SW00RTN,EQ,#TPFDBOK               If no error ...
*                                  LREC is successfully displayed