DBCRE: Create a subfile

Use this general macro to create a new subfile, an empty pool subfile, or an empty indexed pool subfile with its corresponding index file. You can subsequently add logical records (LRECs) to the empty detail subfile as required.

Last updated

  • Changed in 2022 (information only; no code change).
  • Changed in 2020 (information only; no code change).
  • Changed for PUT10.
  • Changed for PUT07.
  • Changed for PUT06.
  • Changed for PUT05.
  • Changed for PUT02.
  • Changed for PUT00.

Format

Read syntax diagramSkip visual syntax diagramDBCRE REF= dsectvvREF= refname,FILE= dsectFILE= dsect,R3= address,AMODE= amodedef,AMODE=3164,ALG= algarg,INDEX,CHKA= rcc,ERROR= spmlbl,ERRORA= asmlbl,NOPGM,PATH=pathnumALL,POOLTYP=012type,REG= register,SUFFIX= char
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.
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.

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 (R3) will be loaded with this address. If R3 already contains the address of the SW00SR slot before this macro is called, you do not need to specify the R3 parameter.
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.
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.
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.
INDEX
Creates an indexed subfile and inserts an index LREC referencing this subfile into the related index file (or files) defined by the database administrator. Specify the index key as the ALG parameter.

If you specify this parameter, the algorithm defined for the new subfile must be #TPFDBFF.

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.
NOPGM
Specifies not to change the program stamp in a block when filing it.
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 the 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.

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

REG=register
Specifies a register that is used to return the address of the header of the prime block of the created subfile.
SUFFIX=char
Allows you to use the same DSECT to map two different areas of storage, where char is the suffix character.

Entry requirements

None.

Return conditions

  • The address of the header of the prime block of the subfile that is created is placed in the SW00REC field of the SW00SR slot. If you specify the REG parameter, this address is placed in the specified register.
  • For information about how to check the error indicators, see Identifying return indicators and errors.

Programming considerations

  • For information about macro register conventions, see Assembler program register conventions.
  • If register R8 is not used as a base register, its contents are unknown upon return from this macro. If R8 is used as a base register, its contents are unchanged.
  • All data, address reference fields, and storage areas that are passed to the z/TPFDF product assembler macros must reside below 2 GB in storage unless otherwise noted.
  • If a literal value is specified as a parameter, the program must have a base register.
  • The optional 2-character version on the REF parameter allows you to access more than one subfile in the same file at the same time. For example, you can code REF=IR71DF01,ALG==C"A" to access subfile A and REF=IR71DF02,ALG==C"B" to access subfile B.
  • A DBADD macro creates a subfile, if one does not exist, before it adds the LREC.
  • For programming considerations when you use this macro with data event processing, see z/TPFDF API programming considerations for data event processing.

Examples

  • The following example creates an indexed subfile and adds a new LREC to that subfile. 
      DBCRE REF=GR45DF,ALG=EBW001,INDEX
  DBADD REF=GR45DF,NEWLREC=EBW000
  • The following example creates a new subfile, creates the index reference to that subfile, and adds an LREC to the subfile. 
    DBCRE REF=GR23DF
DBIDX REF=GR23DF,ALG=EBW0044
DBADD REF=GR23DF