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.
- 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:
- 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.
- 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:
- When you are using fullfile processing, each subfile in turn is put in
detac mode, not the entire file.
- 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:
- An absolute value. For example,
DBOPN REF=GR36DF,SPACE=(400,R5)
- The length of a label. For example,
DBOPN REF=GR36DF,SPACE=(L'GR36REC,R5)
This provides space that is the same length as the field.
- The label of a field. For example,
DBOPN REF=GR36DF,SPACE=(EBW002,R5)
The space is determined by the 2 bytes of data beginning at the specified
label.
- 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).
Ensure that the subfile you open was previously defined in a DSECT macro
and in a DBDEF macro by your database administrator.
The error indicators in the SW00RTN field of the SW00SR slot have no
meaning for this macro.
The following example opens two different subfiles and then later accesses
one of them.