Miscellaneous Utilities

This chapter describes other miscellaneous OpenFrame/HiDB utilities.

1. Overview

The following describes miscellaneous HiDB utilities. Details about each utility are given in each corresponding section.

Program Description

DFSDDLT0

Makes DL/I calls independently of application programs.

DFSMVRC0

Executes a control region of OpenFrame OSI.

DFSRRC00

Executes another OpenFrame/HiDB utility or a batch application compiled into a shared object by using additional parameters.

IIUSTART

Manages HiDB secondary index segment table.

2. DFSDDLT0

The DFSDDLT0 utility is an application program test utility that performs the following tasks:

  • Makes calls to IMS based on control statement information.

  • Makes DL/I calls independently of application programs.

The HiDB DFSDDLT0 utility is a counterpart to the DFSDDLT0 utility of IBM IMS DB.

2.1. EXEC Statements

The following shows how to specify the EXEC statement.

PGM=DFSRRC00,PARM='DLI,DFSDDLT0,PSB'
Item Description

PGM

DFSDDLT0 is invoked through DFSRRC00, a utility that runs applications that use IMS/DB.

PARM

Executes the DFSDDLT0 utility from the utility region.

2.2. DD Statements

The following describes each DD statement.

Item Description

PRINTDD DD

Displays DFSDDLT0 messages. (Required)

SYSIN DD

Specifies the data set that contains input control statements. (Required)

2.3. Control Statements

The following statements in SYSIN DD are interpreted differently depending on the column number. This section describes only supported parameters.

  1. STATUS Statement

  2. COMMENT Statement

    • Conditional COMMENT Statement

    • Unconditional COMMENT Statement

  3. CALL Statement

STATUS Statement

Column Description

1

STATUS statement can be used to set print options and name the PCB that you want subsequent calls to be issued against.

  • S: STATUS statement

2

Output device option.

  • Blank: uses PRINTDD. If DD statement is provided, it is ignored.

3

Comment print option.

  • Blank: do not print.

  • 1: print.

  • 2: print only the difference. (Unsupported)

4

AIB print option.

  • Blank: do not print.

  • 1: print for each call. (Unsupported)

  • 2: print only the difference. (Unsupported)

5

CALL print option.

  • Blank: do not print.

  • 1: print function called via CALL FUNCTION statement.

  • 2: print only the difference. (Unsupported)

6

Blank

7

COMPARE print option.

  • Blank: do not print.

  • 1: print for each call. (Unsupported)

  • 2: print only the difference. (Unsupported)

8

Blank

9

PCB print option.

  • Blank: do not print.

  • 1: print for each call.

  • 2: print only the difference. (Unsupported)

10

Blank

11

Segment print option.

  • Blank: do not print.

  • 1: print for each call.

  • 2: print only the difference. (Unsupported)

12

Set task time (Unsupported)

13-14

Blank

15

PCB selection option.

  • Blank: select based on columns 16-23.

  • 1: PCB name specified in columns 16-23 (Unsupported)

  • 2: DBD name specified in columns 16-23

  • 3: Relative DB PCB specified in columns 16-23 (Unsupported)

  • 4: DB PCB specified in columns 16-23 (Unsupported)

16-23

PCB selection option.

The default PCB is the first database PCB in the PSB. (Supported only when column 15 is set to 2)

  • Blank: current PCB is used.

  • DBDNAME: must be the name of a database DBD in the PSB.

24

Status print option.

  • Blank: do not print.

25-28

PCB processing option.

  • Unsupported.

29

Blank

30-32

AIB interface.

  • AIB: AIB interface is used and AIB is passed. (Unsupported)

33

Blank

37-72

Blank

73-80

Comment or sequence indication, but this is ignored in OpenFrame.

COMMENT Statement

Prints comments in the output data.

  • Conditional COMMENT statement

    • 5 conditional COMMENT statements per call are allowed.

    • Continuation mark is not needed in column 72.

    • You can control whether or not to print conditional comments with column 3 of the STATUS statement.

  • Unconditional COMMENT statement

    • You can use any number of unconditional COMMENT statements.

Column Description

1

T or U.

  • T: conditional COMMENT statement.

  • U: unconditional COMMENT statement.

2-72

Comment.

73-80

Comment or sequence indication, but this is ignored in OpenFrame.

CALL FUNCTION Statement

Specifies DL/I call function, segment search arguments (SSAs). SSA must follow the IMS standards.

Column Description

1

  • L: CALL FUNCTION statement

2

Blank

3

Blank

4

Blank

5-8

Repeat count. (Unsupported)

  • Blank: defaults to 1.

  • nnnn: number of times to repeat the call. (Range: 1-9999)

10-13

DL/I CALL identifier.

  • Blank: use the function from the previous CALL statement.

  • XXXX: DL/I call function, such as ISRT, DLET, or GU.

  • CONT:

    • Continuation indicator for SSAs that are too long for a single CALL FUNCTION statement.

    • Column 72 of the preceding CALL FUNCTION statement must have an entry.

    • The next CALL statement must have CONT in columns 10-13 and the SSA must continue in column 16.

14-15

Blank

16-23

SSA name.

  • This is required when SSA is specified in the CALL.

24

Blank

25

SSA start character.

  • (: required when SSA is specified in the CALL.

26-33

SSA field name.

  • Field name: required when SSA is specified in the CALL.

34

Blank

35-36

DL/I Call Operator.

  • Comparison operator: required when SSA is specified in the CALL.

37

Blank

38-nn

Field value.

  • Field value: required when SSA is specified in the CALL. You cannot use '5D' or ')' in the field value.

nn+1

SSA ending character.

  • ): required when SSA is specified in the CALL.

72

Continuation column.

  • Blank: no continuations.

  • x: indicates that SSA is continued on the next line. CONT in columns 10-13 of the next statement indicates that SSA is continued beginning in column 16 of the following statement.

73-80

Comment or sequence indication, but this is ignored in OpenFrame.

CALL DATA Statement

  • CALL DATA statement provides IMS with information normally provided in the I/O area for the call function.

  • CALL DATA statement must come after the last CALL FUNCTION statement.

  • You must enter an L in column 1, the keyword DATA in columns 10-13, and specify the necessary data in columns 16-71.

  • You can continue data by entering a non-blank character in column 72.

  • On the continuation statement, columns 1-15 are blank and the data resumes in column 16.

Column Description

1

  • L: CALL DATA statement

2

  • K: add 2500 bytes to the length of data in columns 5-8. (Unsupported)

3

Unsupported

4

Format option. (Unsupported)

  • Blank: not a variable-length segment.

  • V

  • M

  • P

  • Z

  • U

5-8

Segment data length (Unsupported)

  • nnnn: length of data in the segment.

9

Blank

10-13

CALL DATA statement identifier.

  • DATA: identifies CALL DATA statement.

14-15

Blank

16-71

DATA area.

  • xxxx: specify the data that goes into the I/O area.

72

Continuation column.

  • Blank: there is no more data.

  • x: there is more data to continue to the next line.

73-80

Comment or sequence indication, but this is ignored in OpenFrame.

2.4. Call Results

If the call is successful, the result is printed through the PRINTDD statement based on the print options set in the STATUS statement.

DFSDDLT0 Version 7.2.0(2) bmahn@:ofsrc7/ims(#1) 2018-01-29 23:27:45
191223 M DLT0001M =====< DFSDDLT0 EXECUTION BEGINS >=====
 THIS IS TEST SAMPLE SAMPLE

******************************************************************************************
                           PRINT CALL FUNTION INFORMATION



  <<< CALL FUNCTION INFORMATION >>>

   FUNCTION    : GU
   SSA         : COL2    (COL2KEY = COL205)


  <<< PCB INFORMATION >>>

  DBPCB
          D D L T D B D   0 2  G E A       p . . .  C O L 2         . .  . . . . . . C O L 1  0 0 . . . . . . . .
          44444C54444244203032 4745412020207008F0FF 434F4C32202020200000 000605000000434F4C31 30300000000000000000
          . . . . . . . . . .  . . . . . . . . . .  . . . . . . . . . .  . . . . . . . . . .  . . . . . . . . . .
          00000000000000000000 00000000000000000000 00000000000000000000 00000000000000000000 00000000000000000000
          . . .
          000000


  <<< RESULT INFORMATION >>>

          COL2      STATUS CODE=GE(4745) L=000032 LEV=02 FC=GU


                               END OF THIS CALL FUNCTION
******************************************************************************************

2.5. Examples

The following example gets COL2 segment whose COL2KEY is COL205 from a database whose DBD is DDLTDBD and PSB is DDLTPSB.

//DFSDDLT0    JOB   MSGLEVEL=1,MSGCLASS=X,CLASS=A,REGION=4096K
//TESTGU   EXEC PGM=DFSRRC00,PARM='DLI,DFSDDLT0,DDLTPSB'
//IMS      DD  DSN=IMS.PSBLIB,DISP=SHR
//         DD  DSN=IMS.DBDLIB,DISP=SHR
//PRINTDD  DD SYSOUT=*
//SYSOUT   DD SYSOUT=*
//SYSIN    DD *
S 1 1 1 1 1    DDLTDBD                                                  10000000
T THIS IS TEST GET UNIQUE                                               20000000
L        GU    COL2     (COL2KEY  =  COL205)                            30000000
L        GN    COL2                                                     40000000
U GET NEXT TEST                                                         50000000
/*

The following example inserts data calling the ISRT function on a database whose DBD is DDLTDBD and PSB is DDLTPSB.

//DFSDDLT0    JOB   MSGLEVEL=1,MSGCLASS=X,CLASS=A,REGION=4096K
//TEST01  EXEC PGM=DFSRRC00,PARM='DLI,DFSDDLT0,DDLTPSB'
//PRINTDD  DD SYSOUT=*
//SYSOUT   DD SYSOUT=*
//SYSIN    DD *
S 1 1 1 1 1    DDLTDBD                                                  10000000
T THIS IS TEST SAMPLE                                                   20000000
L        ISRT  COL1                                                     30000000
L        DATA  COL100KKKK1234567890123456789012345678                   40000000
L        ISRT  COL2                                                     50000000
L        DATA  COL200HHHHAAAA123456789012345678                         60000000
L        ISRT  COL2                                                     70000000
L        DATA  COL201TTTTLLLL123456789012345678                         80000000
L        ISRT  COL3                                                     90000000
L        DATA  COL300ZZZZCCCC12                                         11000000
L        ISRT  COL3                                                     12000000
L        DATA  COL301PZPZQNQN34                                         13000000
L        ISRT  COL4                                                     14000000
L        DATA  COL400BBBB123456789012345678SSSS                         15000000
U TEST DATA INSERT SUCCESSFUL                                           16000000
/*

2.6. Return Codes

The DFSDDLT0 utility returns the following codes.

  • If program call is successful

    Returns 0.

  • If an error occurs

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

    The following is the DFSDDLT0 error code.

    Code Description

    8

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

    • Initializing OpenFrame system library has failed.

    • An error occurred in DFSDDLT0 utility program.

3. DFSMVRC0

The DFSMVRC0 utility is used to execute a control region of OpenFrame OSI. With the name of a OpenFrame OSI region specified, the utility starts the schedule server and the command server of the specified region.

HiDB’s DFSMVRC0 utility is a counterpart to the DFSMVRC0 utility, IBM DCCTL’s entry module.

3.1. EXEC Statements

The following shows how to specify the EXEC statement.

EXEC PGM=DFSMVRC0, PARM=(regiontype, rgsuf, imsid)

The following describes each parameter.

Item Description

regiontype

Must be set to 'CTL' to execute a control region. Any value other than 'CTL' indicates an unknown region and results in an error.

rgsuf

Specifies the suffix for DFSPB***. IBM supports DBC, DCC, and IMS, but OpenFrame OSI supports only IMS. This parameter is parsed for internal coherence only.

imsid

Specifies the 1-4 byte ID of an OpenFrame OSI control region in the format of 'IMSID=id'.

3.2. DD Statements

Item Description

MODBLKSA,

MODBLKSB

Specifies the name of a staging library that contains settings of various resources supported in OpenFrame OSI.

IMSACBA,

IMSACBB

Specifies the name of a staging library that contains ACBs.

DFSRESLB

Specifies a library that contains the MDA information needed to dynamically allocate a data set that OpenFrame OSI uses.

MATRIXA,

MATRIXB

Specifies the name of a staging library that contains security information supported in OpenFrame OSI.

FORMATA,

FORMATB

Specifies the name of the staging library that holds MFS.

STEPLIB

Specifies a data set that contains executable, user-written programs in the form of shared object.

QBLKS

Specifies the name of a message queue (MQ) data set to be used by OpenFrame.

MODSTAT

Specifies a data set that has the information about the current ACT data set, for which dynamic allocation can be used.

SYSPRINT DD

Specifies the output data set.

4. DFSRRC00

The DFSRRC00 utility is used to execute another HiDB utility or a batch application that has been compiled into a shared object. With this utility, you can specify additional parameters. All programs that access HiDB in the Batch environment are executed with the DFSRRC00 utility.

The HiDB DFSRRC00 utility is a counterpart to the IBM IMS DB’s DFSRRC00 utility.

4.1. EXEC Statements

The following shows how to specify the EXEC statement.

  • When -mode= Other than BMP

    EXEC PGM=DFSRRC00, PARM=(mode, mbr, psb, buf, spie/test/excpvr/rst, prld, srch,
    ckptid,mon, loga, fmto, imsid, swap, dbrc, irlm, irlmnm, bko, iob, ssm,
    'aparm', lockmax, gsgname, tminame, rrs, imsplex, rgsuf, dfsdf, 'parm1',
    'parm2')

  • When -mode=BMP

    EXEC PGM=DFSRRC00, PARM=(BMP, mbr, psb, in, out, opt/spie/test/dirca, prld,
    stimer, ckptid, pardli, cputime, nba, oba, imsid, agn, ssm, preinit,
    altid, 'aparm', lockmax, environ, jvmopmas)

The following describes each parameter.

Item Description

mode

Specifies the HiDB access environment for an application program you want to execute, such as DLI, MPP, ULU, UPB, and UDR if -mode= other than BMP.

mbr

Name of an application program.

psb

Name of the PSB that an application program references.

ckptid

Checkpoint ID used for symbolic checkpoint calls and extended restart.

Other parameters not described in this manual are not supported in HiDB.

4.2. DD Statements

The DFSRRC00 utility is used to execute other utilities and application programs, and hence it supports only the following general DD statements.

Item Description

IMS DD

Specifies the basic information about the HiDB database, such as IMS.DBDLIB, IMS.PSBLIB, and GSAM data sets.

STEPLIB

Specifies a data set that contains executable, user-written programs in the form of shared object.

DFSRESLB

Specifies a library that contains the MDA information needed to dynamically allocate a data set that OpenFrame OSI uses.

SYSABEND, SYSUDUMP DD

Specifies the dump data set. If both SYSABEND and SYSUDUMP DDs are specified, the one that comes after the other is used.

SYSIN DD

Specifies the input data set.

SYSPRINT DD

Specifies the output data set.

5. IIUSTART

The IIUSTART utility manages HiDB secondary index table.

  • Secondary index inserts data into the index segment table of the segments in the target DBD.

  • You can insert data into index segment table by specifying the index names.

The HiDB IIUSTART utility is a counterpart to the IBM IMS DB’s IIUSTART utility.

IBM IMS DB IIUSTART creates and manages all indexes, but HiDB IIUSTART only manages secondary index table.

5.1. EXEC Statements

The following shows how to specify the EXEC statement.

PGM=IIUSTART

5.2. DD Statements

The following describes each DD statement.

Item Description

IIUPRINT DD

Displays IIUSTART messages. (Required)

IIUIN DD

Specifies the data set with the input control statement. (Required)

5.3. Control Statements

The IIUSTART inserts data into the index segment table using the input control statement specified in IIUIN.

Item Description

PROC Statement

Specifies the index processing type.

INDEX Statement

Specifies an index to process.

PROC Statement

The PROC statement specifies the index processing type. The IIUSTART supports only the BLD_SECONDARY option for secondary index inserts. BLD_PRIMARY and BLD_ILDS are unsupported.

PROC BLD_SECONDARY,dbname1,{ALL|SELECT}

INDEX Statement

The INDEX statement specifies an index for processing.

You must specify SELECT option in the PROC statement. If you specify ALL option in the PROC statement, the INDEX statement is ignored. You can specify up to 32 indexnames.

INDEX indexname[,indexname[,...]]

5.4. Call Results

If the call is successful, the result is printed through the IIUPRINT DD statement.

IIUSTART Version 7.2.0(1) oftest@:ofsrc7/ims(#1) 2018-01-29 23:27:45
172116 M IST0001M =====< IIUSTART EXECUTION BEGINS >=====
----#1: SEG1(1:SEG111)
----#2: SEG2(1:SEG211)
----#3: SEG3(1:SEG311)
----#4: SEG3(2:SEG312)
----#5: SEG4(1:SEG411)
----#6: SEG2(2:SEG212)
----#7: SEG3(3:SEG313)
----#8: SEG3(4:SEG314)
----#9: SEG4(2:SEG412)
----#10: SEG4(3:SEG413)
----#11: SEG5(1:SEG511)
----#12: SEG1(2:SEG121)
----#13: SEG2(3:SEG221)
----#14: SEG3(5:SEG321)
----#15: SEG5(2:SEG521)
----#16: SEG1(3:SEG131)
----#17: SEG2(4:SEG231)
----#18: SEG5(3:SEG531)
----#19: SEG1(4:SEG141)
----#20: SEG2(5:SEG241)
----#21: SEG5(4:SEG541)
----#22: SEG1(5:SEG151)
----#23: SEG2(6:SEG251)
----#24: SEG5(5:SEG551)

******************************************************************************************

              SUCCESS BUILD SECONDARY INDEX - DBDNAME is 'EXHIDAM'

******************************************************************************************

172116 M IST0002M =====< IIUSTART EXECUTION ENDS >=====

5.5. Examples

The following example inserts data into the secondary index table of the secondary index source segment in EXHIDAM DBD.

//IIUALL   JOB
//STEP01   EXEC PGM=IIUSTART
//IIUPRINT   DD SYSOUT=*
//IIUIN    DD *
  PROC BLD_SECONDARY,EXHIDAM,ALL
/*

The following example inserts data into the indexes EXHIIX2 and EXHIIX5 of the secondary index table of the secondary index source segment in EXHIDAM DBD.

//IIUALL   JOB
//STEP01   EXEC PGM=IIUSTART
//IIUPRINT   DD SYSOUT=*
//IIUIN    DD *
  PROC BLD_SECONDARY,EXHIDAM,SELECT
  INDEX EXHIIX2,EXHIIX5
/*

5.6. Return Codes

The IIUSTART utility returns the following codes.

  • If program call is successful

    Returns 0.

  • If an error occurs

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

    The following is the IIUSTART error code.

    Code Description

    8

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

    • Initializing OpenFrame system library has failed.

    • An error occurred in IIUSTART utility program.