bdfp1m2fProgramming Concepts and Reference

DBRED-Read a Logical Record

Use this macro 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 this macro to read a sequence of LRECs. In this case, you perform a sequence of DBRED macro calls and get a different LREC each time.

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.

AREA=arealbl
specifies an area to which the TPFDF product copies user data from the index LREC referencing the detail subfile you are accessing, where arealbl is one of the following:

arealbl
is the label of a field to which the user data will be copied.

A/arealbl
is the label of a 4-byte field that contains the storage address of the field to which the user data will be copied.

The user data is defined in the DBDEF macro of the detail subfile. See TPFDF Database Administration for more information about defining this user data.

BACKWARD
reads through a subfile backwards. The DBRED macro reads the LREC immediately preceding the current one.

Notes:

  1. You cannot use the BACKWARD parameter with KEYn or LRECNBR parameters.

  2. If you use the BACKWARD parameter with the DBRED macro and also use the DBRET macro, you must specify the STACK or STACKREF parameter with the DBRET macro. See DBRET-Retain a Logical Record Position for more information about these parameters and the DBRET macro.

  3. If you use the BACKWARD parameter, 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 code the DBRED macro with the BACKWARD parameter specified regardless of how bit 0 of &SW00OP1 is set.

BEGIN
reads the subfile from the beginning rather than from the current LREC. This ensures that the DBRED macro locates the first LREC in the file that matches any search arguments you have specified.

LAST
reads the last LREC in a subfile. If you use the LAST parameter together with KEYn parameters, the DBRED macro supplies the last LREC that matches the search arguments.

PREVIOUS
retrieves an LREC that you saved using the DBRET macro.

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.

NOCHK
specifies that you do not want to check the record code check (RCC) value of the blocks.

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.

FAST
used for migration purposes only; use the INLINE or NOKEY parameter instead. If you specify this parameter, the NOKEY parameter is implemented; that is, keys that are currently active are deactivated.

FULLFILE
reads an LREC (specified using the ALG and KEYn parameters) from any of the subfiles in the file referenced by the REF parameter. If you do not specify the FULLFILE parameter, you can only read an LREC in the current subfile.
Note:
If the BEGORD and ENDORD parameter were defined on the DBOPN macro, the DBRED macro with the FULLFILE parameter only accesses the subfiles between the specified ordinals.

HEADER
locates the subfile header in the prime block and returns the address in field SW00REC rather than the address of an LREC. The address of the prime block is also returned in field SW00PCA..

If you specify the HEADER and FULLFILE parameters on an open subfile, the DBRED macro retrieves the header of the next subfile.

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

INLINE
provides inline processing for this macro. You cannot use this parameter with the KEYn or LRECNBR parameters. Any keys that are active from previous TPFDF macros are deactivated.

Use this parameter when you want to read each LREC in a subfile sequentially.

Notes:

  1. After a DBRED macro is issued with the INLINE parameter specified, you cannot be certain that the TPFDF product will check the keys if you issue a DBMOD macro when KEYCHECK=YES is defined on the DBDEF macro.

  2. You cannot use this parameter with P-type files.

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.

KEYLIST=keyloc
specifies a key list that you want to use with this macro, where keyloc is one of the following:

See Setting Up and Using a Key List for information about how to set up a key list.

NOKEY
deactivates any currently active keys.

LIST=lreclst
reads a list of LRECs, where lreclst is a register that contains the address of a list of LREC numbers. The TPFDF product reads these LRECs sequentially when you make a series of DBRED macro calls.

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:

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

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

ADJUST=factor
specifies an adjustment factor for the values in the list, where factor is a register or the label of a field that contains a positive or negative adjustment factor. For example, if you set the adjustment factor to 1, and the list contains LRECs 1/3/5, the DBRED macro reads LRECs 2/4/6.

LRECNBR=lrecnum
specifies the sequence number of an LREC that you want to access, where lrecnum is one of the following:

Notes:

  1. If you use the #TPFDB0D algorithm, you must specify this parameter.

  2. LRECs are numbered in increasing order from the start of the subfile (the first LREC in the prime block has sequence number 1).

  3. If you specify the LRECNBR parameter with KEYn parameters, only those LRECs that match the key conditions are included in the sequence numbering; LRECs that do not match are ignored.

NODUMP
specifies that you do not want the TPFDF product to issue any of the following system errors while processing this macro:

See Messages (System Error, Online, Offline) and Master Glossary for more information about these system errors.

Note:
Using the NODUMP parameter is not recommended because it can prevent system errors from being issued that indicate a critical problem.

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

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.

REG=register
specifies a register in which to return the address of the current LREC (this address is contained in SW00SR field SW00REC). If the HEADER parameter is specified, the address of the prime block (contained in SW00SR field SW00PCA) is returned in the register. You must specify this parameter for T-type files.

REGD=register
specifies a register in which to return the base address of the userLREC part of an extended LREC.

STACK=stkloc
reads an LREC that you saved using the DBRET macro, where stkloc is the location of a 10-byte field that contains the details about the LREC. Specify the same value you used with the STACK parameter on the previous DBRET macro call. See DBRET-Retain a Logical Record Position for more information about saving LRECs.
Note:
Where possible, use the STACKREF parameter.

STACKREF=stkval
reads an LREC that you saved using the DBRET macro, where stkval is a value assigned to the retained LREC. Specify the same value you used with the STACKREF parameter on the previous DBRET macro call. See DBRET-Retain a Logical Record Position for more information about saving LRECs.

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

TLREC
specifies one of the following:

YES
includes technical LRECs (TLREC) when searching for LRECs to be read.

NO
does not include TLRECs when searching for the LRECs to be read.

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

Entry Requirements

If you specify the PREVIOUS, STACK, or STACKREF parameter, you must first open the subfile using the DETAC or HOLD parameters.

Normal Return

If the specified LREC is located, the address of that LREC (the current LREC) is loaded into the SW00REC field of the SW00SR slot. If you specify the REG parameter, the address is also loaded into the register that you specify. For P-type files, the current LREC is the address of the block that contains the record.

Error Return

Programming Considerations

Examples

Related Macros