DBDSP-display logical records from a subfile

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

is the label of an 8-byte field that contains the reference name.

A/refname

is the label of a 4-byte field that contains the storage address of an 8-byte field that contains the reference name.

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 TPFDF product needs to search for the SW00SR slot with this duplicate 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 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:

• 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

  is the label of a field that contains the algorithm argument.

  A/algarg

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

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.

FADDR8=faddr8

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

faddr8

is the label of an 8-byte field that contains the file address of the prime block of the subfile.

A/faddr8

is 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

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

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

Note: When you use this parameter, you cannot specify the core block reference word (CBRW) or file address reference word (FARW) fields in an ECB

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:

1. The prime block is also released.
2. If the subfile is indexed:
   1. If an algorithm was specified either on the DBCLS macro or on a previous API managing this subfile, the subfile is de-indexed from the specified path.
   2. If the AUTODEINDEX=YES parameter is specified on the DBDEF macro, the subfile will be de-indexed from all its indexes.
   Note: In both cases, the application cannot open the indexes with the HOLD option in the same entry control block (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.

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.

None.

SW00RTN is set to zero.

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

In the following example, the amount of data to be stripped is equal to the length of the field 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,#TPFDBOK,Z               If no error ...             
*                                           LREC is successfully displyed