OpenFrame/HiDB Definition Tools

This chapter describes the definitions tools supported by OpenFrame/HiDB.

1. Overview

The following is a list of programs that define the OpenFrame/HiDB (hereafter HiDB) database schema or the access method used by applications.

Program Description

acbgen

Stores the metadata of application control blocks (ACB) to enhance application execution performance.

dbdgen

Stores a HiDB schema in a meta table and creates objects using the schema.

hidbinit

Creates a meta table used for operating HiDB.

hidbmgr

Deletes or initializes objects created with the dbdgen tool and removes their PSB metadata from the meta table.

imsdaloc

Defines dynamic allocation blocks (DAB) to enable dynamic allocation of the target database.

psbgen

Stores the logical structure and data communication interface block and their metadata and creates objects using them.

2. acbgen

The acbgen tool enhances the application performance and optimizes memory usage. The tool takes metadata of DBD and PSB that are created using a database definition utility and access definition utility and stores the metadata in separate meta tables.

In HiDB guides, the metadata created by the acbgen tool is referred to as the ACB metadata. To use the HiDB database in an online application, you must create the ACB metadata before starting the online server.

Usage

The following is how to execute the acbgen.

Usage: acbgen command [options] operand
  • [options]

    Option Description

    [-p psblib]

    Name of the PDS data set associated with PSB. (Example: IMS.DBDLIB)

    [-d dbdlib]

    Name of the PDS data set associated with DBD. (Example: IMS.PSBLIB)

    [-l acblib]

    Name of the PDS data set associated with ACB. (Example: IMS.ACBLIB)

    [-f]

    Deletes the stored data when running a build command.

  • Parameters

    Parameter Description

    command

    Command to run.

    • build: creates the ACB metadata.

    • delete: deletes ACB metadata.

    • copy: makes a copy of the ACB metadata (this command is added to support the feature with which you could copy the ACB in ACBLIB to ACBLIBA and ACBLIBB in the previous version of OpenFrame/HiDB).

    operand

    Operand.

    • PSB=ALL: targets all PSB metadata within PSBLIB (this option is used only in a build command).

    • PSB=psbname: targets the metadata of the specified PSB

    • DBD=dbdname: targets the metadata of the specified DBD.

    • BLDPSB={YES|NO}: if set to YES, it creates the metadata of the PSB that refers to the metadata of the specified DBD (this option can be used with the DBD operand in a build command). The default is YES.

Examples

The following is an example of creating the ACB metadata that refers to the metadata of a PSB named EXHIDAM.

$ acbgen build PSB=EXHIDAMA

When you execute the tool, the following message appears.

acbgen version 7.2.0(0) oframe@oframe:ofsrc7/ims(#1) 2017-11-28 12:48:04
Application Control Block Generation Program

ACBGEN COMMAND=BUILD,OPERAND=(PSB=EXHIDAMA),ACBLIB=IMS.ACBLIB
------------------------------------------------------------
*** ACBGEN BUILD PSB=EXHIDAMA
------------------------------------------------------------
*** BUILDING PSB BLOCK....... PSBNAME=EXHIDAMA
*** BUILDING DBD BLOCK....... DBDNAME=EXHIDAM
------------------------------------------------------------
PROGRAM COMPLETED SUCCESSFULLY.

The following is an example of deleting the ACB metadata that refers to the metadata of DBD named EXHIDAM.

$ acbgen delete DBD=EXIHDAM

When you execute the tool, the following message appears.

acbgen version 7.2.0(0) oframe@oframe:ofsrc7/ims(#1) 2017-11-28 12:48:04
Application Control Block Generation Program

ACBGEN COMMAND=DELETE,OPERAND=(DBD=EXHIDAM),ACBLIB=IMS.ACBLIB
------------------------------------------------------------
*** ACBGEN DELETE DBD=EXHIDAM
------------------------------------------------------------
*** DELETING DBD BLOCK....... DBDNAME=EXHIDAM
------------------------------------------------------------
PROGRAM COMPLETED SUCCESSFULLY.

The following is an example of moving copies of the ACB metadata in ACBLIB to ACBLIBA and ACBLIBB.

This feature is added to support the previous version’s Linux and Unix copy command with which you could copy and move all ACBs in IMS.ACBLIB PDS to IMS.ACBLIBA and IMS.ACBLIBB. In the current version of OpenFrame/HiDB, you only need to specify the copy command without the operand. This command deletes the existing metadata associated with ACBLIBA and ACBLIBB, makes copies of the metadata associated with the LIB_NAME ACBLIB, and moves the copies to LIB_NAMEs ACBLIBA and ACBLIBB.

$ acbgen copy

When you execute the acbgen tool, the following message appears.

acbgen version 7.2.0(0) oframe@oframe:ofsrc7/ims(#1) 2017-11-28 12:48:04
Application Control Block Generation Program

ACBGEN COMMAND=COPY,OPERAND=(),ACBLIB=IMS.ACBLIB
------------------------------------------------------------
*** ACBGEN DELETE PSB=ALL
------------------------------------------------------------
*** ACBGEN DELETE PSB=ALL SUCCESS
------------------------------------------------------------
------------------------------------------------------------
*** ACBGEN COPY PSB=ALL
------------------------------------------------------------
ACBGEN COPY SUCCESS
------------------------------------------------------------
PROGRAM COMPLETED SUCCESSFULLY.
Configuration
  • If an output PDS data set is not separately specified, the acbgen tool returns the output to the default ACBLIB PDS specified in the VALUE of the ACBLIB_NAME key in the IMS_DEFAULT section of the ims subject under OpenFrame Configuration.

    $ ofconfig list -s ims -sec IMS_DEFAULT -k ACBLIB_NAME
    
    ==================================================================================
      SUBJECT   |     SECTION      |        KEY         |             VALUE
    ==================================================================================
        ims     |   IMS_DEFAULT    |    ACBLIB_NAME     |           IMS.ACBLIB
    ==================================================================================
  • If the PSBLIB data set or DBDLIB data set is not specified, the acbgen tool uses the default PSBLIB or default DBDLIB data set specified in the VALUE of the PSBLIB_NAME and DBDLIB_NAME keys in the IMS_DEFAULT section of the ims subject under OpenFrame Configuration. Note that no metadata is stored in either the PSBLIB PDS or DBDLIB PDS.

    $ ofconfig list -s ims -sec IMS_DEFAULT
    
    ==================================================================================
      SUBJECT   |     SECTION      |        KEY         |             VALUE
    ==================================================================================
        ims     |   IMS_DEFAULT    |    DBDLIB_NAME     |           IMS.DBDLIB
                |                  |    PSBLIB_NAME     |           IMS.PSBLIB
          :              :                   :                           :
    ==================================================================================

For more information about OpenFrame Configuration, refer to OpenFrame Configuration Guide.

3. dbdgen

The dbdgen tool is used to define the HiDB database schema.

With this tool, you can execute the DBDGEN utility directly from the Unix shell without running it as a job.

If you execute the dbdgen tool, it stores the database schema information from the DBD script in meta tables created by using the hidbinit tool.

Usage

The following is how to execute the dbdgen.

Usage: dbdgen [options] filename...
  • [options]

    Option Description

    [-f ]

    Deletes the existing DBD metadata and objects and creates new ones.

  • Parameters

    Parameter Description

    filename

    Name of a file that contains DBD control statements. When there are multiple files to process, enter the file names one after another.

Examples

The following is an example of storing the DBD metadata derived from the DBD control statements of the EXHIDAM file.

$ dbdgen EXHIDAM

When you execute the dbdgen tool, the following message appears.

dbdgen version 7.2.0(0) oframe@oframe:ofsrc7/ims(#4) 2017-11-28 21:51:38
Database Description Block Generation Program

DBDGEN FCOUNT=1
------------------------------------------------------------
*** Processing DBD script "EXHIDAM"
------------------------------------------------------------

>>>>> Processing DBD "EXHIDAM"
>>>>> Successfully processed DBD "EXHIDAM"

PROGRAM COMPLETED SUCCESSFULLY. Total : [1]
Configuration

If a PDS data set is not explicitly specified, dbdgen tool uses the default DBDLIB PDS specified in the VALUE of the DBDLIB_NAME key in the IMS_DEFAULT section of the ims subject under OpenFrame Configuration.

$ ofconfig list -s ims -sec IMS_DEFAULT -k DBDLIB_NAME

==================================================================================
  SUBJECT   |     SECTION      |         KEY         |             VALUE
==================================================================================
    ims     |   IMS_DEFAULT    |     DBDLIB_NAME     |           IMS.DBDLIB
==================================================================================

For more information about OpenFrame Configuration, refer to OpenFrame Configuration Guide.

4. hidbinit

To get started with HiDB, you must run the hidbinit tool before running any other tool. The hidbinit tool creates meta tables required to operate the database.

Usage

The following is how to execute the hidbinit.

Usage: hidbinit command [options]
  • Parameters

    Parameter Description

    command

    Command to run.

    • create: creates a meta table.

    • drop: deletes a meta table.

    • truncate: removes all metadata from a meta table.

  • [options]

    Option Description

    [-t tablespace]

    Name of a table space. This name is used only when you are creating a meta table (required for Tibero and Oracle).

Examples

The following is an example of how to create a meta table by using the create command.

$ hidbinit create SYS1_ODBC -t DEFVOL

The following is an example of how to delete a meta table by using the drop command.

$ hidbinit drop

The following is an example of how to delete metadata from a meta table by using the truncate command.

$ hidbinit truncate
Configuration

You should specify the database connection to use when running the hidbinit tool (If you have installed OpenFrame/Base, the database connection may be already specified. You can use this connection or specify a new one).

<dbconn.conf>

[SYS1_HIDB]
    DATABASE=tb_tibero
    USERNAME=oframe
    ENPASSWD=...

5. hidbmgr

The hidbmgr tool manages HiDB metadata, user data, and libraries used at HiDB startup.

hidbmgr performs the following functions:

  • Displays or deletes DBD metadata, which was processed by using dbdgen, or creates DLI library to use for data loading.

  • Displays or deletes PSB metadata, which was processed by using psbgen, or creates DLI library to use in HiDB programs.

  • Creates, deletes, or initializes tables for DBD segments.

Usage
  • Managing DBD and PSB

    You can use the hidbmgr tool to manage DBD and PSB as follows:

    Usage: hidbmgr <dbd|psb> <command> <dbd_name|psb_name> [options]
    • Parameters

      Parameter Description

      <dbd|psb>

      Control block type (DBD or PSB).

      command

      Command to run.

      • display: shows information about the control block.

      • dligen: creates DLI library to load the control block or use in a program. A .pc file is created in the path set in the HIDB_OBJECT_DIR key of the HIDB_DEFAULT section in hidb subject in OpenFrame configuration.You must make the dlilibs directory in the path to add the library created when you build the pc file.

      • delete: deletes metadata of the control block.

      dbd_name

      Control block name.

    • [options]

      Option Description

      [-vr dbd_ver]

      DBD version. This is only applicable for DBDs (default: 0).

      [-l lib_name]

      DBD or PSB library name.

      Default: name set in the DBDLIB_NAME or PSBLIB_NAME key in the IMS_DEFUALT section of ims subject of OpenFrame configuration.

      [-bi buffer_count]

      Valid only for the dligen command for PSB with the index DBD and the procedure option (PROCOPT) indicated as LSB. It specifies the number of rows to buffer when bulk insert is used.

  • Managing User Data Tables (Segment Tables)

    You can use the hidbmgr tool to manage user data tables (segment tables) as follows:

    Usage: hidbmgr segm <command> <dbd_name> [options]
    • Parameters

      Parameter Description

      command

      Command to run.

      • create: creates DB objects, including tables, views, indexes, and sequences, related to the DBD segments.

      • drop: deletes DB objects related to the DBD segments.

      • truncate: initializes DB objects related to the DBD segments.

      dbd_name

      DBD name.

    • [options]

      Option Description

      [-vr dbd_ver]

      DBD version. This is only applicable for DBDs (default: 0).

      [-l lib_name]

      DBD library name.

      Default: name set in the DBDLIB_NAME key of the IMS_DEFUALT section in ims subject of OpenFrame configuration.

      [-a]

      Valid only for create command. Creates tables of DBD and index DBD.

      [-f]

      Option to first delete database objects before executing create on the DBD.

      [-i]

      Valid only for the create command. Drops and recreates the index of target DBD tables.

      [-id]

      Valid only for the create command. Drops the index on the target DBD tables.

      [-fk]

      Valid only for the create command. Adds a foreign key constraint to the paired segment table.

      [-fkd]

      Valid only for the create command. Removes a foreign key constraint on a paired segment table.

      [-t tablespace_name]

      Valid only for the create command. Specifies the tablespace name for creating target DBD tables.

For more information about OpenFrame Configuration, refer to OpenFrame Configuration Guide.

Examples

The following example runs the dbd delete command to delete the metadata of the EXHIDAM DBD.

$ hidbmgr dbd delete EXHIDAM

hidbmgr version 7.2.0(0) oframe@:ofsrc7/ims(#2) 2017-11-29 09:50:54
Managing OpenFrame HiDB metadata tables and segment tables

hidbmgr: deleting DBD IMS.DBDLIB.EXHIDAM(ver.0) metadata

hidbmgr: successfully processed the request

The following example runs the psb dligen command to create the DLI library file to use to access EXHIDAML PSB.

$ hidbmgr psb dligen EXHIDAML

hidbmgr version 7.2.0(0) oframe@:ofsrc7/ims(#2) 2017-11-29 09:50:54
Managing OpenFrame HiDB metadata tables and segment tables

hidbmgr: creating PSB IMS.PSBLIB.EXHIDAML DLI libraries
hidbmgr: processing PCB# 0(EXHIDAML_0)

hidbmgr: successfully processed the request

The following example runs the segm created command to create objects related to the EXHIDAM version 1 DBD segments.

$ hidbmgr segm create EXHIDAM -vr 1

hidbmgr version 7.2.0(0) oframe@:ofsrc7/ims(#2) 2017-11-29 09:50:54
Managing OpenFrame HiDB metadata tables and segment tables

hidbmgr: creating DBD IMS.DBDLIB.EXHIDAM(ver.1) objects
hidbmgr: generating schema objects for the DBD segment SEG1
hidbmgr: generating schema objects for the DBD segment SEG2
hidbmgr: generating schema objects for the DBD segment SEG3
hidbmgr: generating schema objects for the DBD segment SEG4
hidbmgr: generating schema objects for the DBD segment SEG5

hidbmgr: successfully processed the request
Configuration

The hidbmgr tool uses the connection information set in the dbconn.conf.

If a PDS data set is not specified, this tool references the DBDLIB and PSBLIB values of the DBDLIB_NAME and PSBLIB_NAME keys in the IMS_DEFAULT section of the ims subject under OpenFrame Configuration.

$ ofconfig list -s ims -sec IMS_DEFAULT

==================================================================================
  SUBJECT   |     SECTION      |        KEY         |             VALUE
==================================================================================
    ims     |   IMS_DEFAULT    |    DBDLIB_NAME     |           IMS.DBDLIB
            |                  |    PSBLIB_NAME     |           IMS.PSBLIB
      :              :                   :                           :
==================================================================================

6. imsdaloc

The imsdaloc tool defines the DD name, data set name, and disposition to enable dynamic allocation or deletion of a target database. Information regarding dynamic allocation is stored in the system library as a dynamic allocation block (DAB).

The imsdaloc tool supports compatibility with the DFSMDA macro commands in the IBM mainframe IMSDALOC procedure. With the imsdaloc tool, you can execute the DFSMDA commands in OpenFrame without additional settings.

Usage

The following is how to execute the imsdaloc.

Usage: imsdaloc [options] filename...
  • [options]

    Option Description

    [-l reslib]

    Name of the output PDS data set (example: IMS.RESLIB).

    [-v volume]

    RESLIB volume serial number (before the RESLIB is cataloged).

  • Parameters

    Parameter Description

    filename

    Name of the file that contains the DFSMDA macro commands. When there are multiple files to process, enter the file names one after another.

Examples

The following example illustrates how to create a DAB block by running the imsdaloc tool with the DFSMDA1 file that contains the DFSMDA macro command.

$ imsdaloc DFSMDA1

When you execute the imsdaloc tool, the following message appears.

imsdaloc version 7.2.0(0) oframe@oframe:ofsrc7/ims(#2) 2017-11-28 21:51:38
Dynamic Allocation Block Generation Program

IMSDALOC FCOUNT=1,RESLIB=IMS.RESLIB,VOLSER=100000
------------------------------------------------------------
*** processing filepath="DFSMDA1"
------------------------------------------------------------
mdaparser: *** dfsmda_statement matched!
mdaparser: *** dfsmda_statement matched!
mdaparser: *** dfsmda_statement matched!
mdaparser: *** dfsmda_statement matched!
mdaparser: *** dfsmda_statement matched!
mdaparser: *** dfsmda_statement matched!
mdaparser: *** dfsmda_statement matched!
mdaparser: *** dfsmda_statement matched!
mdaparser: *** dfsmda_statement matched!
mdaparser: *** dfsmda_statement matched!
mdaparser: *** dfsmda_statement matched!
mdaparser: *** dfsmda_statement matched!
mdaparser: *** dfsmda_statement matched!
mdaparser: *** end_statement matched!
mdaparser: *** mda_generation finished!!!
------------------------------------------------------------
*** ims_parse_mda("DFSMDA1") success.
------------------------------------------------------------
  MDA TYPE=DATABASE,DBNAME=DI41M101
    DATASET TYPE=DATASET,DDNAME=M1I3I1,DSNAME=IMSQA.M1I3I1,DISP=
    DATASET TYPE=DATASET,DDNAME=M1I3O1,DSNAME=IMSQA.M1I3O1,DISP=
------------------------------------------------------------
*** ims_print_mda("DI41M101") success.
------------------------------------------------------------
  MDA TYPE=DATABASE,DBNAME=DX41SK03
    DATASET TYPE=DATASET,DDNAME=DXSK0301,DSNAME=IMSQA.DB5H111,DISP=SHR
    DATASET TYPE=DATASET,DDNAME=DXSK0302,DSNAME=IMSQA.DB5H222,DISP=SHR
    DATASET TYPE=DATASET,DDNAME=DHSK0301,DSNAME=IMSQA.DB5H333,DISP=SHR
------------------------------------------------------------
*** ims_print_mda("DX41SK03") success.
------------------------------------------------------------
  MDA TYPE=DATABASE,DBNAME=DH41SK03
    DATASET TYPE=DATASET,DDNAME=DDSK0101,DSNAME=IMSQA.DB4D111,DISP=SHR
    DATASET TYPE=DATASET,DDNAME=DDSK0102,DSNAME=IMSQA.DB4D222,DISP=SHR
    DATASET TYPE=DFSDCMON,DDNAME=IMSMON,DSNAME=I115T237.IMSMON,DISP=
------------------------------------------------------------
*** ims_print_mda("DH41SK03") success.
------------------------------------------------------------
PROGRAM COMPLETED SUCCESSFULLY.
Configuration

If an output PDS data set is not separately specified, the imsdaloc tool returns the output to the data set specified in the VALUE of the RESLIB_NAME key in the IMS_DEFAULT section of the ims subject under OpenFrame Configuration.

$ ofconfig list -s ims -sec IMS_DEFAULT  -k RESLIB_NAME

==================================================================================
  SUBJECT   |     SECTION      |        KEY         |             VALUE
==================================================================================
    ims     |   IMS_DEFAULT    |    RESLIB_NAME     |           IMS.RESLIB
==================================================================================

For more information about OpenFrame Configuration, refer to OpenFrame Configuration Guide.

7. psbgen

The psbgen tool defines the logical structure of the HiDB database from the application perspective.

The DBD referenced by the PSB must configure the metadata in advance with the dbdgen tool. When the psbgen is executed, it stores the PSB and PCB information described in the PSB script in a meta table. For more information about the dbdgen tool, refer to dbdgen.

Usage

The following is how to execute the psbgen.

Usage: psbgen [options] filename...
  • [options]

    Option Description

    [-f ]

    Deletes the existing PSB metadata and objects and stores new ones.

  • Parameters

    Parameter Description

    filename

    Name of a file that contains PSB control scripts. When there are multiple files to process, enter the file names one after another.

Examples

The following is an example of storing the PSB metadata in EXHIDAM and creating the DML for each meta table by using the psbgen tool.

$ psbgen EXHIDAMA

When you execute the pdsgen tool, the following message appears.

psbgen version 7.2.0(0) oframe@oframe:ofsrc7/ims(#4) 2017-11-28 21:51:38
Program Specification Block Generation Program

PSBGEN FCOUNT=1ă…‡
------------------------------------------------------------
*** Processing PSB script "EXHIDAMA"
------------------------------------------------------------

>>>>> Processing PSB "EXHIDAMA"
--Removing existing PSB EXHIDAMA metadata
 ### Processing PCB# 0(EXHIDAMA_0)
>>>>> Successfully processed PSB "EXHIDAMA"

PROGRAM COMPLETED SUCCESSFULLY. Total : [1]
Configuration

If a PDS data set is not specified, the psbgen uses the default PSBLIB PDS specified in the VALUE of the PSBLIB_NAME and DBDLIB_NAME keys in the IMS_DEFAULT section of the ims subject under OpenFrame Configuration. If a DBDLIB is not specified either, the default value of DBDLIB PDS under the same section is referenced instead.

$ ofconfig list -s ims -sec IMS_DEFAULT

==================================================================================
  SUBJECT   |     SECTION      |        KEY         |             VALUE
==================================================================================
    ims     |   IMS_DEFAULT    |    DBDLIB_NAME     |           IMS.DBDLIB
            |                  |    PSBLIB_NAME     |           IMS.PSBLIB
      :              :                   :                           :
==================================================================================

For more information about OpenFrame Configuration, refer to OpenFrame Configuration Guide.