bdfp1m27Programming Concepts and Reference

DBDSP-Display Logical Records from a Subfile

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

Format




Notes:

  1. See Specifying File Organization with Keyn Parameters for information about the rules for using the KEYn parameters and file organization parameters together.




REF=dsectvv
specifies the file or subfile that you want to access, where dsectvv is the DSECT name and an optional 2-character version.

REF=refname
specifies the file or subfile that you want to access, where refname is a label that references the DSECT name in one of the following formats:

refname
is the label of an 8-byte field that contains the 6-byte DSECT name and an optional 2-character version.

A/refname
is the label of a 4-byte field that contains the storage address of the DSECT name and an optional 2-character version.

FILE=dsect
specifies the file or subfile that you want to access, where dsect is the 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 will be loaded with this address.
Note:
Do not use this parameter; it is provided only for migration purposes. Use the REF parameter to specify the file that you want to access.

ALG=algarg
identifies the subfile that you want to access, where algarg specifies an algorithm argument.

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.

Specify algarg as one of the following:

Note:
Do not modify the area of storage containing the algorithm argument until the subfile is closed.

FADDR=faddr
identifies the subfile that you want to access, where faddr is one of the following:

faddr
is the label of a 4-byte field that contains the file address of the prime block of the subfile.

A/faddr
is the label of a 4-byte field that contains the storage address of the 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
is the label of a 4-byte field that contains the ordinal number of the subfile.

A/ordnum
is 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
checks the record code check (RCC) value in each block, where rcc is the label of a 1-byte field that contains the RCC character.

ERROR=spmlbl
branches to the specified location if a serious error is detected when processing the macro, where spmlbl is a TPFDF structured program macro (SPM) label defined with the #LOCA macro. See TPFDF and TPF Structured Programming Macros for more information about the #LOCA macro. See Identifying Return Indicators and Errors for more information about serious errors.

ERRORA=asmlbl
branches to the specified location if a serious error is detected when processing the macro, where asmlbl is an assembler label. See Identifying Return Indicators and Errors for more information about serious 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:

interlvnum
is 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. See TPFDF Database Administration for more information about interleaves.

PARTITN
specifies the partition that you want to use. Specify one of the following:

partitnum
is one of the following:
  • A register that contains the address of 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. See TPFDF Database Administration for more information about partitions.

Note:
Do not use this parameter with the #TPFDB0F algorithm. This algorithm computes the partition used from the algorithm argument. See TPFDF Database Administration for more information about algorithms.

KEYn
specifies the key parameters that you want to use with this macro, where n is a number from 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. See Specifying File Organization with Keyn Parameters for more information about how to do this. 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
is the name of a field defined in the DSECT for the LREC; for example:
... KEY1=(PKY=#GR00K80),KEY2=(R=GR00FLD,S=EBW000)

label1
is 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
is a halfword literal containing the displacement into the LREC; for example:
... KEY1=(PKY=#GR00K80),KEY2=(R==H'2',S=EBW000,L==H'4')

flddisp
is the displacement off the field of the LREC; for example:
... KEY1=(PKY=#GR00K80),KEY2=(R=GR00FLD+2,S=EBW000,L==H'4')

or

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

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:

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
    is the label of the search argument.

    A/searcharg
    is the label of a 4-byte field that contains the storage address of the search argument.

    P/searcharg
    is 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.

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
is the label of a 5-byte field that contains the bit settings.

A/opmtbits
is 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.

See TPFDF Database Administration for more information about path numbers.

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 RELFC parameter to release W-type files.

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:

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.

Entry Requirements

None.

Normal Return

SW00RTN is set to zero.

Error Return

 See Identifying Return Indicators and Errors for information about how to check the error indicators. 

Programming Considerations

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)

Related Macros

DBCLS-Close a Subfile.