DBOPN: Open a subfile

This macro is the first z/TPFDF macro that you use with any z/TPFDF files, except automatically opened files. 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.

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

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

A⁄refname

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

Note: Do not use this and the FILE parameter; they are provided only for migration purposes. Use the REF parameter to specify the file that you want to access.

NODUMP

Specifies that the z/TPFDF product does not issue system errors with return while the z/TPFDF product is processing this macro.

Note: If you specify the NODUMP parameter, the z/TPFDF product does not issue system errors that indicate a critical problem.

AMODE

Specifies the addressing mode that is being used when the macro is called. Specify one of the following values:

amodedef

The value that is specified by the AMODE parameter on the BEGIN macro. If the AMODE parameter is not specified on the BEGIN macro, the default value is 31.

31

Indicates that 31-bit addressing mode is in use.

64

Indicates that 64-bit addressing mode is in use.

ERROR=spmlbl

Branches to the specified location if a serious error is detected when processing the macro, where spmlbl is a z/TPFDF structured program macro (SPM) label defined with the #LOCA macro. For more information about serious errors, see Identifying return indicators and errors. For more information about the #LOCA macro, see z/TPF and z/TPFDF Structured Programming Macros.

ERRORA=asmlbl

Branches to the specified location if a serious error is detected when processing the macro, where asmlbl is an assembler label. For more information about serious errors, see Identifying return indicators and errors.

ALG=algarg

Identifies the subfile that you want to access, where algarg specifies an algorithm argument.

The z/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 z/TPFDF product uses the algorithm argument to locate the subfile. For more information about how the z/TPFDF product uses the algorithm argument to locate the subfile, see z/TPFDF Database Administration.

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

  The label of a field that contains the algorithm argument.

  A⁄algarg

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

Note: The area of storage that contains the algorithm argument must not be modified and must be accessible to the z/TPFDF product until the subfile is closed and the SW00SR is released.

FADDR=faddr

Identifies the subfile that you want to access, where faddr is one of the following:

faddr

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

A⁄faddr

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

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

A⁄faddr8

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

The label of a 4-byte field that contains the ordinal number of the subfile.

A⁄ordnum

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 z/TPFDF product, on a subsequent read, copies user data from the index LREC referencing the index file that you are accessing, where arealbl is one of the following:

arealbl

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

A/arealbl

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

Rx

A register that contains the storage address of the field to which the user data will be copied.

This action occurs on the corresponding index LREC while accessing the index file.

The user data is defined in the DBDEF macro of the index file. See data extraction parameter information in z/TPFDF Database Administration for more information about defining this user data.

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 z/TPFDF macros with the FULLFILE parameter with this file, the z/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 z/TPFDF product processes the subfiles in order 3, 4, 0, 1, 2, then indicates end of file.

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.

NOCHK

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

DETAC

Opens the subfile in detac mode. When the subfile is in detac mode, all accessed blocks are saved in main storage. No modified 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, but not the entire file.
• The z/TPF system issues a 000010 system error if an application program does not give up control in the time allotted by the application timeout counter. When processing in detac mode, a z/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.
• If you use this macro with a W-type file, overflow pools can be written to DASD unless the DETAC parameter is specified when the subfile is opened.

HOLD

Potentially holds the subfile that you are accessing and prevents two or more application programs from modifying the subfile at the same time. The subfile is held on the following z/TPFDF call that accesses the subfile if bits 4 and 5 in the &SW00OP2 global set symbol in the DSECT macro, or the OP2, PRIMEHLD, or CHAINHLD parameter in the DBDEF macro, have been set appropriately. Subsequent z/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.

For information about how bits 4 and 5 in the &SW00OP2 global set symbol in the DSECT macro, or the OP2, PRIMEHLD, and CHAINHLD parameters in the DBDEF macro, affect hold processing, see Global DSECT override parameters.

If you use this parameter to concurrently update multiple subfiles in the same ECB, you must issue the DBOPN macro in the same order across all ECBs to avoid a deadlock condition.

Note: If you use this macro with a W-type file, the HOLD parameter is the default. For more information about W-type files, see z/TPFDF Database Administration.

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.

Note: If you use this macro with a W-type file, the HOLD parameter is the default. See z/TPFDF Database Administration for more information about W-type files.

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

Holds the index files that reference the subfiles that you are accessing.

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:

intrlvnum

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. For more information about interleaves, see z/TPFDF Database Administration.

PARTITN

Specifies the partition that you want to use. Specify one of the following values:

partitnum

One of the following conditions:

• 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. For more information about partitions, see z/TPFDF Database Administration.

Notes:

• Do not use this parameter with the #TPFDB0F algorithm. This algorithm computes the partition used from the algorithm argument.
• If you specify PARTITN when opening an indexed detail file (#TPFDBFF algorithm), the partition value will be used in combination with the algorithm argument (ALG parameter) to retrieve the appropriate fixed file record.

For more information about algorithms, see z/TPFDF Database Administration.

KEYn

Specifies the key parameters that you want to use with this macro, where n is a number in the range 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. For more information about how to do this, see Specifying file organization with keyn parameters. 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

The name of a field defined in the DSECT for the LREC; for example:

… KEY1=(PKY=#GR00K80),KEY2=(R=GR00FLD,S=EBW000)

label1

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

A halfword literal containing the displacement into the LREC; for example:

… KEY1=(PKY=#GR00K80),KEY2=(R==H'2',S=EBW000,L==H'4')

flddisp

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:

Table 1. S and PKY parameter conditions

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:

Table 2. M and D parameter conditions

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

  The label of the search argument.

  A⁄searcharg

  The label of a 4-byte field that contains the storage address of the search argument.

  P⁄searcharg

  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.

Notes:

• When you use this parameter, you cannot specify the core block reference word (CBRW) or file address reference word (FARW) fields in an ECB.
• Do not use literals with the S parameter. For example, do not code the following statement:

   S==AL2(#MYVALUE)

  If a literal is used and subsequent processing in the same ECB attempts to reuse the key information in a different program, the key information might be inaccessible and a system error may occur.

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 the following:

AUTO

Specifies automatic SW00SR allocation.

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

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.

For more information about path numbers, see z/TPFDF Database Administration.

POOLTYP

Selects the pool type to use when a subfile is created, where:

0

Uses the pool type that is defined by the PF0 parameter of the DBDEF macro.

1

Uses the pool type that is defined by the PF1 parameter of the DBDEF macro.

2

Uses the pool type that is defined by the PF2 parameter of the DBDEF macro.

type

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

The POOLTYP parameter determines the pool type that is used by prime blocks in newly created pool subfiles. New chain blocks on existing pool subfiles use the pool type of the subfile's prime block. New chain blocks on fixed file subfiles use the pool type that is defined by the PF0 parameter of the DBDEF macro.

This parameter is ignored for W-type files. Use the POOLTYP parameter as directed by the database administrator.

PREFETCH=PRIME

Specifies that a find macro is issued for the prime block. If you specify this parameter, a WAITC macro is issued only when the HOLD parameter is specified and the current ECB is not the owner of the record hold. Before you issue any other z/TPFDF macros (except the DBIFB macro) that access the returned SW00SR slot, you must issue the DBWAIT macro to complete the outstanding I/O operations.

Before you issue the DBWAIT macro, you can issue multiple DBOPN macros with this parameter specified to open multiple subfiles and to process the underlying I/O operations in parallel.

Notes:

• You cannot specify this parameter to open the following files:
  • A detail file or mid-level index file when the ALG parameter is specified. A detail file or mid-level index file is a file that uses the #TPFDBFF algorithm.
  • A W-type file.
• If you specify this parameter, the DBOPN macro might internally issue a WAITC macro. The DBWAIT macro returns any errors from WAITC macro processing.

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

The number of bytes of space that you want, which can be a maximum of 4069 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

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 label that references the name in one of the following formats:

tapename

The 3-character symbolic tape name.

location

The label of a 3-character field that contains the symbolic tape name. The label (location) must be at least 4 characters long.

A/location

The label of a 4-byte field that contains the storage address of the 3-character symbolic tape name.

Notes:

• When you specify this parameter, if you are adding LRECs and the prime block overflows, the z/TPFDF product copies the current prime block to the specified tape or sequential data set. The z/TPFDF product then initializes the original prime block by inserting a new standard z/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.
• You cannot use the TAPE parameter to open B⁺Tree files.
• You cannot use the TAPE parameter to open files that have REMOTEALLOW=YES specified on the DBDEF macro.

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

For information about the &SW00OP2 global set symbol in the DSECT macro, see z/TPFDF Database Administration.