bdfp1m2eProgramming Concepts and Reference

DBOPN-Open a Subfile

Use this macro to open a subfile. This is the first TPFDF macro you use with any file. The first DBOPN macro creates a database interface block (DBIFB) and reserves a SW00SR slot in the DBIFB. The SW00SR slot contains control information about the subfile. See TPFDF General Information for more information about SW00SR and this control information.

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 will contain the address of the SW00SR slot on return from the macro.
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.

BEGORD=bordnum
overrides the default starting ordinal number for use in a subsequent DBRED macro or other macro statement, where bordnum is a label pointing to a 4-byte field containing the required ordinal number.

ENDORD=eordnum
overrides the default ending ordinal number for use in a subsequent DBRED macro or other macro statement, where bordnum is a label pointing to a 4-byte field containing the required ordinal number.

WRAPAROUND
sets a wraparound bit. If you use other TPFDF macros with the FULLFILE parameter with this file, the TPFDF product processes the subfiles in order, returning to the first subfile from the last subfile.

For example, consider a file that contains 5 subfiles. If you specify BEGORD=3 and the WRAPAROUND parameter with the DBOPN macro, and then code a DBRED macro with the FULLFILE parameter specified, the TPFDF product processes the subfiles in order 3, 4, 0, 1, 2, then indicates end of file.

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.

DATA
specifies the data level for the data block. Specify one of the following:

dlevel
is the data level.

R3
is for internal TPFDF use only.
Note:
Do not use this parameter; it is provided only for migration purposes. In addition, do not specify the DATA parameter if you have specified the REF parameter in your application program.

DETAC
opens the subfile in detac mode. When the subfile is in detac mode, all modified blocks are saved in main storage. No blocks are written to DASD until you checkpoint the subfile (using the DBCKP macro) or close the subfile (using the DBCLS macro). Access to LRECs in blocks in main storage can be very fast.

If you do not want to keep any modifications that you made to the subfile opened with the DETAC parameter, you can use the ABORT parameter with the DBCLS macro. This closes the file without saving any modifications to disk.

Each subfile that you open with the DETAC parameter uses up some main storage, so avoid using this parameter unnecessarily.

Notes:

  1. When you are using fullfile processing, each subfile in turn is put in detac mode, not the entire file.

  2. The TPF system and the ALCS environment issues a 000010 system error if an application program does not give up control in the time allotted by the application time-out counter. When processing in detac mode, a TPFDF application program can require more than the allotted time on a database with a large data structure. To prevent the 000010 system error, you can change the setting of the &TPFDBDV symbol in the DBLCL macro.

    See TPFDF Installation and Customization for more information about the &TPFDBDV symbol and the DBLCL macro.

HOLD
potentially holds the subfile that you are accessing and prevents two or more application programs from modifying the subfile at the same time. Holding occurs on the following TPFDF call that accesses the subfile 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 subfile will not occur until the subfile is no longer held. If more than one application can update the same subfile, or when 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 OP=2 parameter in the DBDEF macro, affect hold processing.

NOHOLD
does not hold the subfile that you are accessing. You can specify this parameter when you open a subfile and are not going to make modifications to it.

ID=fileid
specifies the ID of the file to be opened, where fileid is a halfword containing the file ID. This parameter is for use by the database administrator only; for example, in ZUDFM utilities for performing centralized database routines.

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 on the following TPFDF call that accesses the subfile 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 marco, or the OP2= parameter in the DBDEF macro, affect hold processing.

INDEX=NOHOLD
does not hold the index files that reference the subfiles you are accessing.

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.

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

PARAM
specifies the entry control block (ECB) data level for the SW00SR space to be allocated. Specify one of the following:

level
is the data level.

AUTO
specifies automatic SW00SR allocation. Use this value if you specified the DATA parameter.
Note:
Do not use this parameter; it is provided only for migration purposes.

PATH
specifies the path for a detail subfile using index support. If there is only one index path, do not specify this parameter. Specify one of the following:

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.

ALL
specifies all paths.

See TPFDF Database Administration for more information about path numbers.

POOLTYP
overrides the pool type defined by the database administrator, where:

0
uses the pool type defined by the PF0 parameter of the DBDEF macro.

1
uses the pool type defined by the PF1 parameter of the DBDEF macro.

2
uses the pool type defined by the PF2 parameter of the DBDEF macro.

type
is the label of a 1-byte field that contains a 0, 1, or 2 to specify to pool type.

Use the POOLTYP parameter as directed by the database administrator.

REG=register
generates the DSECT macro specified with the REF or FILE parameter and generates a USING statement to provide addressability to the DSECT, where register is the register that will be used on the USING statement. If you specify the SUFFIX parameter as well, the DBOPN macro generates the DSECT using the specified suffix.

If you do not specify the REG parameter and if the application program needs access to the DSECT labels, you must code the DSECT in the application source code directly.

SPACE
provides work space when you open a subfile and initializes the work space to X'00'

SPACEB
provides work space when you open a subfile and initializes the work space to X'40'

space
is the number of bytes of space you want, which can be a maximum of 3952 bytes. Specify one of the following:

spacereg
is the register in which you want the base address of the work space loaded.

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

TAPE=tapename
specifies the tape or sequential data set to be used when creating overflow blocks, where tapename is a 3-character symbolic tape name. When you specify this parameter, if you are adding LRECs and the prime block overflows, the TPFDF product copies the current prime block to the specified tape or sequential data set). The TPFDF product then initializes the original prime block by inserting a new standard TPFDF header and adds the new LREC to this prime block.

This parameter is useful when you are logging data to a real-time tape.

Note:
B+Tree files cannot be opened using the TAPE parameter.

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

Ensure that the subfile you open was previously defined in a DSECT macro and in a DBDEF macro by your database administrator.

Normal Return

The address of the SW00SR slot.

Error Return

The error indicators in the SW00RTN field of the SW00SR slot have no meaning for this macro.

Programming Considerations

Examples

The following example opens two different subfiles and then later accesses one of them.

DBOPN REF=GR00SR01,ALG==C'A'
DBOPN REF=GR00SR02,ALG==C'B'

  ·
  ·
  ·
DBRED REF=GR00SR01

Related Macros

DBCLS-Close a Subfile.