HiDB Definition Utilities

This chapter describes utilities used to define the OpenFrame HiDB database.

1. Overview

OpenFrame HiDB utility programs are provided with the OpenFrame HiDB engine and are executed as batch jobs through JCL. These Utility programs are used to maintain compatibility with database utility programs used on mainframes, and support database definition, reorganization, and initialization.

The following lists the utility programs used to define OpenFrame HiDB database. Details about each utility are given in each corresponding section.

Program Description

DBDGEN

Defines the OpenFrame HiDB database schema in the system.

PSBGEN

Defines the logical structure of the database and the DC interface block.

2. DBDGEN

The DBDGEN utility is used to define the OpenFrame HiDB database schema in the system. The schema information is composed of database definition (DBD) blocks and saved in a system library.

The DBDGEN utility allows you to define the following types of databases:

  • HSAM database (including SHSAM)

  • HISAM database (including SHISAM)

  • HDAM database

  • HIDAM database

  • DEDB database

  • INDEX database

  • LOGICAL DATABASE

The following example shows the contents of the DBDGEN procedure that executes the DBDGENC0 and the DFSILNK0 programs. It consists of two steps.

//       PROC  MBR=TEMPNAME,SOUT=A,RGN=4M,SYS2=
//C      EXEC  PGM=DBDGENC0,REGION=&RGN,PARM='OBJECT,NODECK'
//SYSLIB   DD  DSN=IMS.&SYS2MACLIB,DISP=SHR
//SYSLIN   DD  UNIT=SYSDA,DISP=(,PASS),
//             SPACE=(80,(100,100),RLSE),
//             DCB=(BLKSIZE=80,RECFM=F,LRECL=80)
//SYSPRINT DD  SYSOUT=&SOUT,DCB=BLKSIZE=1089,
//             SPACE=(121,(300,300),RLSE,,ROUND)
//SYSUT1   DD  UNIT=SYSDA,DISP=(,DELETE),
//             SPACE=(CYL,(10,5))
//L      EXEC  PGM=DFSILNK0,PARM='XREF,LIST',COND=(0,LT,C)
//SYSLIN   DD  DSN=*.C.SYSLIN,DISP=(OLD,DELETE)
//SYSPRINT DD  SYSOUT=&SOUT,DCB=BLKSIZE=1089,
//             SPACE=(121,(90,90),RLSE)
//SYSLMOD  DD  DSN=IMS.&SYS2DBDLIB(&MBR),DISP=SHR
//SYSUT1   DD  UNIT=SYSDA,DISP=(,DELETE),
//             SPACE=(1024,(100,10),RLSE)

The first step of the DBDGEN procedure in this example, the C step, is a compile step that runs the DBDGENC0 utility to compile the OpenFrame HiDB database definition script and generate an object module. The second step, the L step, is a link-edit step that runs the DFSILNK0 utility and copies the object module generated in the previous compilation step to the system library.

2.1. DD Statements

The following describes each DD statement.

Item Description

SYSIN DD

Specifies an input data set containing the OpenFrame HiDB database definition script.

SYSLMOD DD

Specifies a PDS data set for storing DBD blocks such as IMS.DBDLIB.

2.2. JCL Parameters

The following describes the JCL parameters.

Item Description

MBR

Specifies the name of the DBD to be created. This name must be identical to that specified in the NAME parameter of the DBD statement.

SOUT

Specifies the class to be assigned to the SYSOUT DD statement. (Default: 'A')

SYS2

Specifies the second qualifier of the IMS system data set. (Example: SYS2='IMSA.')

2.3. Control Statements

The DBDGEN utility uses DBD control statements to define the database schema.

The following describes each DBD control statement.

Item Description

DBD Statement

Specifies general information about the database.

DATASET Statement

Specifies the data set information that makes up the database.

AREA Statement

Specifies data set information for DEDB databases.

SEGM Statement

Specifies segment information included in the data set defined by the preceding DATASET statement.

LCHILD Statement

Specifies logical child segment information for the segment defined by the preceding SEGM statement.

FIELD Statement

Specifies field information for the segment defined by the preceding SEGM statement.

XDFLD Statement

Specifies segment search field information used in secondary index relationships.

DBDGEN Statement

Indicates the end of the database definition.

END Statement

Indicates the end of the control statement.

FINISH Statement

(Optional) Retained for compatibility.

DBD control statements must be written based on the following rules:

  • The DBD statement must be placed at the beginning of the DBD control statement.

  • A DATASET statement must be written after the DBD statement. (In the case of DEDB, use the AREA statement instead of the DATASET statement.)

  • A DBD statement must be followed by at least one DATASET, SEGM, or FIELD statement. However, the logical database definition must not contain any FIELD or LCHILD statements.

  • XDFLD statements must not be present in database definitions other than HDAM, HIDAM, and HISAM (SHISAM).

  • The FIELD statement must not be specified after the LCHILD statement that defines a secondary index relationship.

  • An LCHILD statement specifying the primary index or logical relationship must not be specified after an LCHILD statement that defines a secondary index relationship.

The following is the structure of DBD control statements.

DBD ...................... Start of database definition
  DATASET ................ Data set information
    SEGM ................. Segment information
      FIELD .............. Field information
      LCHILD ............. Logical child information
      XDFLD .............. Segment search field
    SEGM
      FIELD
    SEGM
      FIELD
DBDGEN ................... End of database definition
END ...................... End of control statement
DBD Statement

The DBD statement specifies the name of the database being described and provides DL/I information about its structure. A database definition script can contain only one DBD statement.

  • HSAM (SHSAM) Database

    The following is a DBD statement for an HSAM (SHSAM) database.

    DBD NAME=dbname1,ACCESS={HSAM|SHSAM}

  • HISAM (SHISAM) Database

    The following is a DBD statement for a HISAM (SHISAM) database.

    DBD NAME=dbname1,ACCESS=({HISAM|SHISAM}[,VSAM])
  [,PASSWD={NO|YES}]
  [,VERSION='n']

  • HDAM Database

    The following is a DBD statement for an HDAM database.

    DBD NAME=dbname1,ACCESS=(HDAM,{VSAM|OSAM})
   ,RMNAME=(mod[,anch,rbn,bytes])
  [,PASSWD={NO|YES}]
  [,VERSION='n']

  • HIDAM Database

    The following is a DBD statement for a HIDAM database.

    DBD NAME=dbname1,ACCESS=(HIDAM,{VSAM|OSAM})
  [,PASSWD={NO|YES}]
  [,VERSION='n']

  • DEDB Database

    The following is a DBD statement for a DEDB database.

    DBD NAME=dbname1,ACCESS=DEDB
   ,RMNAME=(mod,...XCI)
  [,VERSION='n']

  • INDEX Database

    The following is a DBD statement for an INDEX database.

    DBD NAME=(dbname1[,dbname2]),ACCESS=(INDEX,VSAM)
  [,PASSWD={NO|YES}]

  • LOGICAL Database

    The following is a DBD statement for a LOGICAL database.

    DBD NAME=dbname1,ACCESS=LOGICAL

The following describes each parameter used in a DBD statement.

Item Description

NAME

Specifies the DBD name of the database being described. However, the name cannot be the same as the PSB name.

ACCESS

Specifies the DL/I and data set access methods used in this database.

The following access methods can be used:

  • HSAM: Hierarchical sequential access method (HSAM).

  • SHSAM: Simple HSAM (SHSAM). This database type can only have one segment type and does not require a segment prefix when storing data.

  • HISAM: Hierarchical index sequential access method (HISAM).

  • SHISAM: SHISAM is used as an access method. This database type can only have one segment type and does not require a segment prefix when storing data.

  • HDAM: Hierarchical direct access method (HDAM).

  • HIDAM: Hierarchical indexed direct access method (HIDAM).

  • DEDB: Data entry database (DEDB).

  • INDEX: Defines the primary index for a HIDAM database or the secondary index for an HDAM or HIDAM database.

  • LOGICAL: Specifies that the database currently being described is a logical database.

PASSWD

Determines whether to use the DBD name as the VSAM password. (Default: NO)

VERSION

Specifies a string used to identify the DBD. (Up to 255 characters)

RMNAME

When the database access type is set to HDAM or DEDB, this specifies information for managing the data stored in the database.

This parameter determines how the randomizer module operates.

OpenFrame HiDB does not use VSAM passwords.
DATASET Statement

The DATASET statement defines a data set group within a database.

  • HSAM (SHSAM) database

    The following is a DATASET statement for an HSAM (SHSAM) database.

    DATASET DD1=ddname1,DD2=ddname2
      [,BLOCK=(blkfact1,blkfact2)]
      [,RECORD=(reclen1,reclen2)]

  • HISAM (SHISAM) database

    The following is a DATASET statement for a HISAM (SHISAM) database.

    DATASET DD1=ddname1,OVFLW=ddname3
      [,BLOCK=(blkfact1,blkfact2)]
      [,SIZE=(size1,size2)]
      [,RECORD=(reclen1,reclen2)]

    The SHISAM database does not define OVFLW.

  • HDAM/HIDAM database

    The following is a DATASET statement for an HDAM or HIDAM database.

    DATASET DD1=ddname1
      [,BLOCK=size0]
      [,SIZE=(,size1)]
      [,SCAN=cyls]
      [,FRSPC=(fbff,fspf)]
      [,SEARCHA=0|1|2]

  • INDEX database

    The following is a DATASET statement for an INDEX database.

    DATASET DD1=ddname1,OVFLW=ddname3
      [,BLOCK=(blkfact1,blkfact2)]
      [,SIZE=(size1,size2)]
      [,RECORD=(reclen1,reclen2)]

  • LOGICAL DATABASE

    The following is a DATASET statement for a LOGICAL database.

    DATASET LOGICAL

The following describes each parameter used in a DATASET statement.

Item Description

DD1

Specifies the DD name of the first data set in the data set group.

Depending on the type of database, this parameter has the following meaning:

  • HSAM: Specifies the DD name of the input data set.

  • SHSAM: Specifies the DD name of the input data set.

  • HISAM: Specifies the DD name of the primary data set.

  • SHISAM: Specifies the DD name of the primary data set.

  • HDAM: Specifies the DD name of the data set.

  • HIDAM: Specifies the DD name of the data set.

  • INDEX: Specifies the DD name of the primary data set.

  • LOGICAL: Invalid parameter.

DD2

Specifies the DD name of the output data set in the HSAM (SHSAM) database type.

OVFLW

Specifies the DD name of the overflow data set in a HISAM database or INDEX database type.

BLOCK

Specifies blocking factors. For further details, refer to the table in the next section.

RECORD

(Optional) Specifies the logical record length. For further details, refer to the table in the next section.

SIZE

Redefines the control interval size for VSAM in the DBDGEN procedure.

SCAN

Specifies the number of device cylinders to search for available space when inserting a segment. OpenFrame HiDB checks only the syntax, but the functionality is not supported.

FRSPC

Specifies the percentage of free space to maintain in HDAM or HIDAM database types.

SEARCHA

Specifies the type of algorithm used to search for available space when inserting a segment. OpenFrame HiDB checks only the syntax, but the functionality is not supported.

LOGICAL

Indicates that a LOGICAL database is being defined.

The following provides detailed information about the BLOCK and RECORD parameters described earlier.

  • HSAM (SHSAM) Database

    HSAM (SHSAM) uses unblocked I/O. Therefore, the LRECL and BLKSIZE must be set to the same value.

    Parameter Description

    BLOCK

    • blkfact1: The blocking factor for the input data set. (Always 1)

    • blkfact2: The blocking factor for the output data set. (Always 1)

    RECORD

    • reclen1: The record length of the input data set.

    • reclen2: The record length of the output data set.

  • HISAM (SHISAM) and INDEX Databases

    Parameter Description

    BLOCK

    • blkfact1: Specifies the block factor for the base data set.

    • blkfact2: Specifies the block factor for the overflow data set.

    RECORD

    • reclen1: Specifies the record size of the basic data set.

    • reclen2: Specifies the record size for the overflow data set.

  • HDAM/HIDAM Database

    Parameters Description

    BLOCK

    Specifies the VSAM control interval size excluding overhead in size0. The default overhead value for VSAM data sets is 5.

    RECORD

    Ignored even if specified.
AREA Statement

A DEDB database uses the AREA statement to define the data set area where data will be stored. When writing a DBDGEN script that defines a DEDB, all AREA statements must be placed between the DBD statement and the first SEGM statement.

The following is an AREA statement for a DEDB database.

AREA DD1=ddname1
   [,DEVICE=nnnn]
    ,SIZE=size1
    ,UOW=(number1,overflow1)
    ,ROOT=(number2,overflow2)
Item Description

DD1

Specifies the DD name of the defined area.

DEVICE

Specifies the device type of the physical storage device.

If no parameter is specified, the default is 3380.

SIZE

Specifies the control interval size. (Valid values: 512 Bytes, 1 KB, 2 KB, 4 KB, 8 KB, and 28 KB)

This must match the control interval size defined for the VSAM data set.

UOW

Specifies the number of control intervals used for a unit of work (UOW).

  • number1: The number of control intervals used for a single UOW. (Range: 2 to 32767)

  • overflow1: The number of overflow control intervals within the same UOW. It must be less than the number specified in number1.

ROOT

Defines properties for a DEDB area.

  • number2: Number of UOWs to be used in the DEDB area.

  • overflow2: Number of UOWs to be used for independent overflow.
SEGM Statement

The SEGM statement defines a segment in a database. It defines the hierarchy of segments within the database, physical properties of the segment, and its relationships with other segments.

  • HSAM (SHSAM) Database

    The following is a SEGM statement for an HSAM (SHSAM) database.

    SEGM NAME=segname1
    ,PARENT=segname2
    ,BYTES=max_bytes
   [,FREQ=frequency]

  • HISAM (SHISAM) Database

    The following is a SEGM statement for a HISAM (SHISAM) database.

    SEGM NAME=segname1
    ,PARENT=(segname2[(lpsegname,[{VIRTUAL|PHYSICAL}],dbname1)])
    ,BYTES=max_bytes[,min_bytes]
   [,FREQ=frequency]
   [,POINTER|PTR={LPARNT|CTR|PAIRED}]
   [,RULES=([{L|P|V}{L|P|V|B}{L|P|V}],[{LAST|FIRST|HERE}])]

  • HDAM or HIDAM Database

    The following is a SEGM statement for an HDAM or HIDAM database.

    SEGM NAME=segname1
    ,PARENT=(segname2[,{SNGL|DBLE}][,(lpsegname,[{VIRTUAL|PHYSICAL}],dbname1)])
    ,BYTES=max_bytes[,min_bytes]
   [,POINTER|PTR={HIER|HIERBWD|TWIN|TWINBWD|NOTWIN}
                ,{LTWIN|LTWINBWD},{LPARNT|CTR|PAIRED}]
   [,RULES=([{L|P|V}{L|P|V|B}{L|P|V}],[{LAST|FIRST|HERE}])]

  • DEDB Database

    The following is a SEGM statement for a DEDB database.

    SEGM NAME=segname1
    ,PARENT=(segname2[,{SNGL|DBLE}])
    ,BYTES=max_bytes,min_bytes,TYPE={DIR|SEQ}
   [,RULES={HERE|LAST|FIRST}]

  • INDEX Database

    The following is a SEGM statement for an INDEX database.

    SEGM NAME=segname1
   [,PARENT=0]
    ,BYTES=max_bytes

The following describes each parameter used in a SEGM statement.

Item Description

NAME

Specifies the name of the segment being defined.

PARENT

Specifies the physical and logical parents of the segment type being defined.

BYTE[S]

Specifies the length of the data portion of a segment. (Maximum value: 32760)

  • max_bytes: The maximum data length of the segment. This must be specified regardless of whether the segment is fixed-length or variable-length.

  • min_bytes: The minimum data length of the segment. This is only defined for variable-length segments, and it must be different from the value specified for max_bytes to be processed as a variable-length segment.

FREQ

Specifies an estimate of the average number of child segment instances per instance of the parent segment.

POINTER

Specifies the pointers to be stored in the prefix of the segment type that is being defined. These pointers relate the current segment instance to its parent segments or twin segments.

The following describes each pointer type:

  • HIER [H]: Contains a 4-byte hierarchic forward pointer.

  • HIERBWD [HB]: Contains a 4-byte hierarchic forward pointer and a 4-byte hierarchic backward pointer. The hierarchic backward pointer improves delete performance.

  • TWIN [T]: Contains a 4-byte physical twin forward pointer.

  • TWINBWD [TB]: Contains a 4-byte physical twin forward pointer and a 4-byte physical twin backward pointer. The twin backward pointer improves delete performance.

  • NOTWIN [NT]: Prevents the use of physical twin forward pointers. NOTWIN can be used if a physical parent segment does not have more than one child segment.

  • LTWIN [LT]: Defines a real logical child segment. It has a 4-byte logical twin forward pointer and a 4-byte logical twin backward pointer. It provides increased performance when deleting logical child segments.

  • LPARNT [LP]: Contains a 4-byte logical parent pointer.

  • CTR [C]: Contains a 4-byte counter field. A counter is required for the logical parent segment in a HISAM database that is not linked by a pointer.

  • PAIRED: Indicates that this segment is involved in a bidirectional logical relationship.

RULES

Specifies rules to be followed when performing insert, delete, or replace commands on a segment.

  • FIRST: A new segment instance is inserted before all existing physical twin segments.

  • LAST: A new segment instance is inserted after all existing physical twin segments.

  • HERE: A new segment instance is inserted immediately before the current physical twin segment.

TYPE

Determines the type of DEDB dependent segment.

One of the following types must be specified:

  • SEQ: Specifies the current segment as a sequential dependent segment.

  • DIR: Specifies the current segment as a direct dependent segment.

SOURCE

This parameter is used for the following two purposes:

  • To identify the real logical child segment when defining a virtual logical child segment.

  • To identify the corresponding segment in physical databases when defining a segment in a logical database.
LCHILD Statement

The LCHILD statement defines a logical relationship between two segments or specifies the HIDAM primary index or secondary index between two segments.

  • HISAM (SHISAM) Database

    The following is an LCHILD statement for a HISAM (SHISAM) database.

    LCHILD NAME=(segname1,dbname)
     [,POINTER|PTR={DBLE|NONE|SYMB}]
     [,PAIR=segname2]
     [,RULES={LAST|FIRST|HERE}]

  • HDAM or HIDAM Database

    The following is an LCHILD statement for an HDAM or HIDAM database.

    LCHILD NAME=(segname1,dbname)
     [,POINTER|PTR={DBLE|NONE|INDX|SYMB}]
     [,PAIR=segname2]
     [,RULES={LAST|FIRST|HERE}]

  • INDEX Database

    The following is an LCHILD statement for an INDEX database.

    LCHILD NAME=(segname1,dbname)
     [,POINTER|PTR={SNGL|SYMB}]
      ,INDEX=fldname

The following describes each parameter used in an LCHILD statement.

Item Description

NAME

Specifies the name of the logical child, index pointer, or index target in segname1. The dbname is the name of the database in which the segment specified in segname1 is defined.

POINTER

Specifies a pointer used in logical or index relationships.

  • SNGL: A 4-byte first pointer to the logical child. Used in logical or index relationships.

  • DBLE: Stores a 4-byte first and a 4-byte last pointer to the logical child in the logical parent segment.

  • NONE: No logical child pointer is stored in the logical parent segment.

  • INDX: Used in a HIDAM database to link a specific segment to a secondary index or a root segment to a primary index.

  • SYMB: Establishes secondary index relationships in HISAM, HDAM, and HIDAM databases. It must also be specified in the LCHILD statement of the target index DBD.

PAIR

Used to specify a physical or virtual paired segment in a bidirectional logical relationship.

RULES

Determines the order in which logical child twins are sequenced in a logical relationship.

  • FIRST: The new logical instance is inserted before all logical twin instances.

  • LAST: The new logical instance is inserted after all logical twin instances.

  • HERE : A new logical instance is inserted immediately before the current logical twin instance.

INDEX

Used in the LCHILD statements of an INDEX database.

The fldname parameter specifies the root segment of a HIDAM primary index or represents the XDFLD of a HIDAM secondary index.
FIELD Statement

The FIELD statement defines a field within a segment.

  • HSAM (SHSAM) Database

    The following is a FIELD statement for an HSAM (SHSAM) database.

    FIELD NAME=(fldname1[,SEQ,{U|M}])
     ,BYTES=bytes
     ,START=startpos
    [,TYPE={C|X|P}]

  • HISAM (SHISAM), HDAM, and HIDAM Databases

    The following is a FIELD statement for HISAM (SHISAM), HDAM, and HIDAM databases.

    FIELD NAME={(fldname1[,SEQ,{U|M}])|systrelfldname}
     ,BYTES=bytes
     ,START=startpos
    [,TYPE={C|X|P}]

  • DEDB Database

    The following is a FIELD statement for a DEDB database.

    FIELD NAME=(fldname1[,SEQ,U])
     ,BYTES=bytes
     ,START=startpos
    [,TYPE={C|X|P}]

  • INDEX Database

    The following is a FIELD statement for an INDEX database.

    FIELD NAME=(fldname1[,SEQ,{U|M}])
     ,BYTES=bytes
     ,START=startpos
    [,TYPE={C|X|P}]

The following describes each parameter used in a FIELD statement.

Item Description

NAME

Specifies the name of a field defined within a segment.

  • SEQ: Indicates that the field being defined is a sequence field.

  • U, M: Specifies the sequence type. The parameter U indicates that only unique values are stored in the sequence field, and the parameter M means that items with the same value are allowed in the sequence field.

  • systrelfldname: Defines a system-related field. It is used to ensure the uniqueness of a key for secondary indexing and supports CK and SK types.

BYTE[S]

Specifies the length of the field being defined.

START

Specifies the starting position of the field being defined.

TYPE

Specifies the data type of the field being defined.

The following constants can be used:

  • C: Alphanumeric data or a combination of types of data (Default)

  • P: Packed decimal data

  • X: Hexadecimal data
XDFLD Statement

The XDFLD statement defines index fields used in secondary index relationships.

The following is an XDFLD statement for a HISAM (SHISAM), HDAM, or HIDAM database.

XDFLD NAME=fldname
    [,SEGMENT=segname]
    [,CONST=char]
     ,SRCH=list1
    [,SUBSEQ=list2]
    [,DDATA=list3]
    [,NULLVAL=value1]
Item Description

NAME

Specifies the name of the indexed data field.

SEGMENT

Specifies the name of the index source segment.

SRCH

Specifies a list of fields in the index source segment.

SUBSEQ

Specifies the subsequence field of a secondary index.

DDATA

Specifies the duplicate data field of a secondary index.

OpenFrame HiDB does not support CONST and NULLVAL parameters in XDFLD statements.
DBDGEN, END, FINISH Statements

There are three additional control statements used in DBD generation.

Statement Description

DBDGEN Statement

Indicates the end of the DBD generation control statement.

END Statement

Indicates the end of the input statements to the assembler.

FINISH Statement

(Optional) Retained for compatibility.

The DBDGEN and END statements are mandatory, while the FINISH statement is optional.

2.4. Examples

The following is a JCL example that defines a HIDAM database using the DBDGEN procedure.

//DBDGEN  JOB MSGLEVEL=1
//       EXEC DBDGEN,MBR=SKILLINV
//C.SYSIN  DD *
       DBD     NAME=SKILLINV,ACCESS=HIDAM
       DATASET   DD1=SKLHIDAM,BLOCK=1648,SCAN=5
*
       SEGM  NAME=SKILL,BYTES=31,PTR=T,PARENT=0
       LCHILD NAME=(INDE,INDEXDB),PTR=INDX
*
       FIELD NAME=(TYPE,SEQ,U),BYTES=21,START=1,TYPE=C
       FIELD NAME=SDCODE,BYTES=10,START=22,TYPE=C
*
       SEGM  NAME=NAME,BYTES=20,PTR=T,PARENT=((SKILL,SNGL))
       FIELD NAME=(STDCLEVL,SEQ,U),BYTES=20,START=1,TYPE=C
*
       SEGM  NAME=EXPR,BYTES=20,PTR=T,PARENT=((NAME,SNGL))
       FIELD NAME=PREVJOB,BYTES=10,START=1,TYPE=C
       FIELD NAME=CLASSIF,BYTES=10,START=11,TYPE=C
*
       SEGM  NAME=EDUC,BYTES=75,PTR=T,PARENT=((NAME,SNGL))
       FIELD NAME=GRADLEVL,BYTES=10,START=1,TYPE=C
       FIELD NAME=SCHOOL,BYTES=65,START=11,TYPE=C
*
       DBDGEN
       FINISH
       END
/*

2.5. Return Codes

The DBDGEN utility returns the following codes.

  • If program call is successful

    Returns 0.

  • If an error occurs

    SYSPRINT DD displays the error message and returns the error code.

    The following is the DBDGEN error codes.

    Code Description

    12

    Indicates an unrecoverable error that may have occurred for the following reasons:

    • SYSLIN DD or SYSLMOD DD was not provided.

    • The type of SYSLIN DD or SYSLMOD DD is invalid.

    • A syntax error occurred in the SYSIN DD script statement.

    16

    Indicates a system error that may have occurred for the following reasons:

    • OpenFrame system library initialization has failed.

    • An OPEN error occurred for SYSLIN DD or SYSLMOD DD.

    • A read error occurred for SYSIN DD or SYSLIN DD.

3. PSBGEN

The PSBGEN utility defines the logical structure of the HiDB database as accessed by applications, along with interface blocks for data communication. The defined program access specification blocks are stored in the system library.

The following is an example of a PSBGEN procedure that executes the PSBGENC0 and DFSILNK0 programs. It consists of the following two steps:

//       PROC  MBR=TEMPNAME,SOUT=A,RGN=4M,SYS2=
//C      EXEC  PGM=PSBGENC0,REGION=&RGN,PARM='OBJECT,NODECK'
//SYSLIB   DD  DSN=IMS.&SYS2MACLIB,DISP=SHR
//SYSLIN   DD  UNIT=SYSDA,DISP=(,PASS),
//             SPACE=(80,(100,100),RLSE),
//             DCB=(BLKSIZE=80,RECFM=F,LRECL=80)
//SYSPRINT DD  SYSOUT=&SOUT,DCB=BLKSIZE=1089,
//             SPACE=(121,(300,300),RLSE,,ROUND)
//SYSUT1   DD  UNIT=SYSDA,DISP=(,DELETE),
//             SPACE=(CYL,(10,5))
//L      EXEC  PGM=DFSILNK0,PARM='XREF,LIST',COND=(0,LT,C)
//SYSLIN   DD  DSN=*.C.SYSLIN,DISP=(OLD,DELETE)
//SYSPRINT DD  SYSOUT=&SOUT,DCB=BLKSIZE=1089,
//             SPACE=(121,(90,90),RLSE)
//SYSLMOD  DD  DSN=IMS.&SYS2PSBLIB(&MBR),DISP=SHR
//SYSUT1   DD  UNIT=SYSDA,DISP=(,DELETE),
//             SPACE=(1024,(100,10),RLSE)

In this PSBGEN procedure, the first step (step C) is the compile step. It uses the PSBGENC0 utility to compile the PSB definition script provided through SYSIN and generates an object module. The second step (step L) is the link-edit step, which runs the DFSILNK0 utility to copy the object module generated in the previous step to the system library.

3.1. DD Statements

The following describes each DD statement.

Item Description

SYSIN DD

Specifies the input data set for the PSB script to be compiled by the PSB compiler.

SYSLMOD DD

Specifies a PDS data set for storing PSB blocks such as IMS.PSBLIB.

3.2. JCL Parameters

The following describes the JCL parameters.

Item Description

MBR

Specifies the name of the PSB to be created. This name must be identical to that specified in the PSBNAME parameter of the PSBGEN statement.

SOUT

Specifies the class to be assigned to the SYSOUT DD statement. (Default: 'A')

SYS2

Specifies the second qualifier of the IMS system data set. (Example: SYS2='IMSA.')

3.3. Control Statements

The PSBGEN utility uses PSB control statements to generate PSB blocks.

The following is the structure of the PSB control statement when using the PSBGEN utility.

PCB TYPE=TP .............. Logical terminal PCB information
PCB TYPE=DB .............. Database PCB information
  SENSEG
    SENFLD
    SENFLD
PCB TYPE=DB
  SENSEG
  SENSEG
PSBGEN ................... End of PSB block definition
END ...................... End of control statement

The following describes the PSB control statements used with the PSBGEN utility.

Item Description

Alternate PCB Statement

Describes a destination other than the source of the current input message (when using the PSBGEN utility).

Database PCB Statement

Describes a PCB for a DL/I or FastPath database.

SENSEG Statement

Declare the database segments used by the application.

SENFLD Statement

Specifies the fields used by the application in the segment defined by the SENSEG statement.

PSBGEN Statement

Specifies the end of the definition for a PSB block.

END Statement

Specifies the end of a control statement.

Alternate PCB Statement

The alternate PCB statement describes a destination other than the source of the current input message (when using the PSBGEN utility).

The format of the alternate PCB statement is as follows:

PCB TYPE=TP
  [,LTERM|NAME=name]
  [,ALTRESP={NO|YES}]
  [,SAMETRM={NO|YES}]
  [,MODIFY={NO|YES}]
  [,EXPRESS={NO|YES}]
  [,PCBNAME=pcbname]
  [,LIST={YES|NO}]
Item Description

TYPE

Required parameter for all alternate PCBs.

LTERM

Specifies the logical terminal name or transaction code where the message will be output.

ALTRESP

Specifies whether an alternate PCB can be used instead of an I/O PCB.

SAMETRM

Specifies whether a logical terminal is assigned to an actual physical terminal.

MODIFY

Specifies whether the alternate PCB can be changed within the application.

EXPRESS

Specifies whether messages from the alternate PCB should be sent to the destination terminal or removed when the application abends.

PCBNAME

Specifies the PCB name. This can be replaced with an assembler label.

LIST

Determines whether the list will be included in the list of PCBs passed to the application entry point when the application runs.
Database PCB Statement

The database PCB statement describes a PCB for a DL/I or FastPath database.

The format of the database PCB statement is as follows:

PCB TYPE=DB
   ,DBDNAME|NAME=name
  [,PCBNAME=pcbname]
  [,PROCOPT=nnnn]
  [,SB={NO|COND}]
   ,KEYLEN=value
  [,POS={SINGLE|MULTIPLE}]
  [,PROCSEQ=index_dbname]
  [,VIEW=MSDB]
  [,LIST={YES|NO}]
Item Description

TYPE

Required parameter for all DL/I database PCBs.

DBDNAME

The physical database name.

PCBNAME

Name of the PCB. This can be replaced with an assembler label.

PROCOPT

Specifies PCB processing parameters.

You can set up to 4 alphabetic characters with the following options:

  • G: Get function.

  • I: Insert function. (Do not specify in HSAM/SHSAM)

  • R: Replace function. (Includes Get. Cannot be specified in HSAM/SHSAM)

  • D: Delete function. (Includes Get. Cannot be specified in HSAM/SHSAM)

  • A: Includes four functions (Get, Insert, Replace, and Delete).

    (Default. Cannot be specified in HSAM/SHSAM)

  • L: Loads the database. (Not applicable to HIDAM)

  • GS: Retrieves segments in ascending order. (Only applicable to HSAM/SHSAM)

  • LS: Loads segments in ascending order. (Only applicable to HIDAM)

  • O: Allows application programs to access the database in read-only mode. Even if a segment is being held or updated by another program, it can be accessed immediately. However, the program cannot hold or update a segment and must be specified with the G option.

  • N: If a read-only applications retains information about a segment that has been updated or deleted by another program, it may result in invalid references due to incorrect pointers. By default, this causes an abnormal termination. However, if the N option is specified, the program can decide whether to terminate or continue processing by returning status code GG to the program instead of terminating abnormally. This option must be specified together with the O option.

SB

Determines whether to use the sequential buffering technique. (Currently not supported)

KEYLEN

Specifies the length of the longest chain key (1 to 3825).

POS

Specifies whether one or more positionings are supported in the logical data structure.

The following abbreviations can be used:

  • SINGLE: Maintains only one position for the most recently accessed segment.

    When a new segment is queried, the information for the previous segment position is discarded. (Default)

  • MULTIPLE: Maintains positions for all segments in each hierarchical path of the segment being accessed. When retrieving segments from hierarchical paths in parallel, there is no need to issue GU calls to reestablish position in each path. (Not supported for HSAM; Supported only in HDAM and HIDAM.)

PROCSEQ

Specifies the name of a secondary index for accessing the database.

VIEW

Provides the MSDB commit view. (Currently not supported)

LIST

Determines whether the PCB is included in the list of PCBs passed to the application’s entry point.

For more information on multiple positioning, refer to the "Multiple Processing" section of the IBM manual IMS Application Programming: Database Manager.
SENSEG Statement

The SENSEG statement is used to define hierarchically linked data segments. When specifying a sensitive segment, all segments at higher levels in the hierarchical path must also be defined as sensitive segments.

The format of the SENSEG statement is as follows:

SENSEG NAME=name
      ,PARENT=name
     [,PROCOPT=nnnn]
     [,INDICES|SIENTRY=list1]
Item Description

NAME

Name of the segment defined by a SEGM statement during DBD generation.

PARENT

Name of the parent of the current segment.

PROCOPT

Specifies processing parameters for the segment to be used by associated applications.

This parameter can restrict read or modification for specific segments for database security. It can be specified as a combination of up to 4 characters.

If omitted, the default follows the value of the PROCOPT in the PCB statement.

  • G: Get function.

  • I: Insert function. (Cannot be specified in HSAM/SHSAM)

  • R: Replace function. (Including Get. Cannot be specified in HSAM/SHSAM)

  • D: Delete function. (Including Get. Cannot be specified in HSAM/SHSAM)

  • A: Includes four functions: Get, Insert, Replace, and Delete.

    (Default. Cannot be specified in HSAM/SHSAM)

  • L: Loads the database. (Except HIDAM)

  • LS: Loads segments in ascending order. (HIDAM only)

INDICES

Specifies which secondary indexes contain the search fields for the indexed segment.
SENFLD Statement

The SENFLD statement is used with the SENSEG statement to specify which fields can be used by the application. However, if a SENFLD statement is specified for a segment, DLET, REPL, and ISRT calls cannot be issued for the segment.

The format of the SENFLD statement is as follows:

SENFLD NAME=name,
       START=startpos
     [,REPLACE|REPL={YES|NO}]
Item Description

NAME

Name of the field defined through a FIELD statement during DBD generation

START

Specifies the starting position of the field within the user’s I/O area.

NOTE:

  • The sum of starting position and field length must not exceed 32,767.

  • Field areas in different SENFLD statements must not overlap. If they do, data corruption may occur in the application’s data area.

REPLACE

Specifies whether the field can be changed through a REPLACE call.
PSBGEN Statement

The PSBGEN statement specifies properties of an application.

The format of the PSBGEN statement is as follows:

PSBGEN PSBNAME=name
     [,LANG={COBOL|PL/I|ASSEM|PASCAL|blank}]
     [,MAXQ={0|nr}]
     [,CMPAT={NO|YES}]
     [,IOASIZE=value]
     [,SSASIZE=value]
     [,IOEROPN={n|(n,WTOR)}]
     [,OLIC={NO|YES}]
     [,GSROLBOK={NO|YES}]
     [,LOCKMAX={0|n}]
Item Description

PSBNAME

Name of the PSB block being defined.

LANG

Indicates the compiler language in which the message program or batch program is written.

The following abbreviations can be used:

  • ASSEMBLY: A or ASSEM

  • COBOL: C

  • PL/I: P or PLI

MAXQ

Maximum number of database calls including Qx command codes.

CMPAT

Provides compatibility between BMP programs or message programs. If set to YES, the PSB is assumed to contain an I/O PCB at the beginning.

IOASIZE

Specifies the maximum size of the I/O area used by the application.

SSASIZE

Specifies the maximum length of the SSA used by the application.

LOCKMAX

Specifies the maximum number of locks that an application can acquire at one time.

OpenFrame HiDB does not support the IOEROPN, OLIC, and GSROLBOK parameters of the PSBGEN statement.
END Statement

The END statement specifies the end of the control statements.

3.4. Examples

The following is a JCL example that generates a PSB block using the PSBGEN procedure.

//PSBGEN  JOB MSGLEVEL=1
//       EXEC PSBGEN,MBR=APPLPGM1
//C.SYSIN  DD *
       PCB    TYPE=TP,NAME=OUTPUT1,PCBNAME=OUTPCB1
       PCB    TYPE=TP,NAME=OUTPUT2,PCBNAME=OUTPCB2
       PCB    TYPE=DB,DBDNAME=PARTMSTR,PROCOPT=A,KEYLEN=100
       SENSEG NAME=PARTMAST,PARENT=0,PROCOPT=A
       SENSEG NAME=CPWS,PARNET=PARTMAST,PROCOPT=A
       SENSEG NAME=POLN,PARENT=PARTMAST,PROCOPT=A
       SENSEG NAME=OPERTON,PARENT=PARTMAST,PROCOPT=A
       SENSEG NAME=INVSTAT,PARENT=OPERTON,PROCOPT=A
       SENSEG NAME=OPERSGMT,PARENT=OPERTON
       PSBGEN LANG=COBOL,PSBNAME=APPLPGM1
       END
/*

3.5. Return Codes

The PSBGEN utility returns the following codes

  • If program call is successful

    Returns 0.

  • If an error occurs

    SYSPRINT DD displays the error message and returns the error code.

    The following is the PSBGEN error codes.

    Code Description

    12

    Indicates an unrecoverable error that may have occurred for the following reasons:

    • SYSLIN DD or SYSLMOD DD was not provided.

    • The type of SYSLIN DD or SYSLMOD DD is invalid.

    • A syntax error occurred in the SYSIN DD script statement.

    16

    Indicates a system error that may have occurred for the following reasons:

    • OpenFrame system library initialization has failed.

    • An OPEN error occurred for SYSLIN DD or SYSLMOD DD.

    • A read error occurred for SYSIN DD or SYSLIN DD.