Other Utilities

This chapter describes other utilities provided for user convenience.

1. Overview

The following is a list of other utilities. Each utility is described in detail in the following sections.

Program Name Description

ADAPT

Manipulates data sets with simple commands.

DSDIFF

Shows the differences between data set records.

EZTPA00

Executes CA-Easytrieve Plus scripts entered as SYSIN from JCL.

FTP

Transfers data sets from a batch JOB to a remote host, or receives data from a remote host and stores it in a data set.

ICETOOL

Uses SORT to output multiple data sets in a single JOB STEP.

IEFBR14

Checks the execution status of a JCL script.

IKJEFT01

Connects to the database system on behalf of a JCL batch program that requires access to the database.

ISRSUPC

Compares two data sets, or searches for a string in a data set.

PGMRTS00

Runtime environment control utility program. It is indirectly executed by the OpenFrame batch engine module, JCL Runner, when running a shared object of the batch application in JCL.

2. ADAPT

The utility manipulates data sets with simple commands.

ADAPT includes the copy (COPY), edit (EDIT), comparison (COMP), print (PRINT), dump (LIST), alteration (ALTER), addition (INSERT), and check (CHECK) functions. Currently only COPY, EDIT, and ALTER are supported.

2.1. DD Statements

The following describes each DD statement.

Statement Description

SYSIN DD

Specifies the ADAPT commands.

SYSPRINT DD or

SYSOUT DD

Displays the messages issued while ADAPT is executed.

Arbitrary DD

Specifies the input or output data set for ADAPT. Can be used by specifying INPUT, OUTPUT and OUT2(ddname) in SYSIN.

2.2. Command Usage

You can specify a command or multiple commands in the following order in SYSIN DD. For the usage of each command, refer to the description of each section.

  1. Function control commands: COPY, EDIT, ALTER

  2. Condition control commands: KEY, K, R, ED, A

When setting the commands, note the following:

  • A command should begin with a blank or a slash character(/).

  • A command cannot be longer than 70 characters.

  • Text following a blank after a command, is processed as a comment.

COPY

The command extracts, deletes, and classifies records depending on a given condition.

The syntax of COPY is as follows:

COPY OUTPUT,INPUT[,OUT2(ddname)]
Parameter Description

OUTPUT

Specifies a DD name of the output data set.

INPUT

Specifies a DD name of the input data set.

OUT2

Specifies a DD name of the data set for classification in ddname.If OUT2 is specified, a record that does not satisfy a condition for extraction is printed as a DD name specified in OUT2.
EDIT

The command extracts a record depending on a given condition, and edits the contents of the record to output it. Non-extracted records are not output, but skipped.

The syntax of EDIT is as follows:

EDIT OUTPUT,INPUT
Parameter Description

OUTPUT

Specifies the DD name of the output data set.

INPUT

Specifies the DD name of the input data set.
ALTER

The command extracts a record depending on a given condition, and alters its contents with specified contents. It is possible to print the altered contents. Non-altered records are outputted as they are.

The syntax of ALTER is as follows:

ALT[ER] OUTPUT,INPUT
Parameter Description

OUTPUT

Specifies the DD name of the output data set.

INPUT

Specifies the DD name of the input data set.
KEY

The command specifies conditions such as I/O record formats.

The syntax of KEY is as follows:

KEY keypos,keylen,keyfmt[,keypos,keylen,keyfmt,...]
Parameter Description

keypos

Specifies a starting position of a key field.

keylen

Specifies the length of a key field.

keyfmt

Specifies a format of a key field as follows:

  • X: Character

  • 9: Decimal

  • P: Packed Decimal

  • H: Hex Decimal

  • HL: Binary

Currently, only X and P are available.
K

The command specifies contents of a record for the extraction conditions. Currently, only COPY and ALTER commands are available.

The syntax of K is as follows:

KEY keynum,operator,value[,keynum,operator,value,...]
Parameter Description

keynum

Specifies the key number described in the KEY statement.

operator

Specifies relational operators.

  • G or >: data > value

  • L or <: data < value

  • E or =: data = value

  • NG or N>: data <= value

  • NL or N<: data >= value

  • NE or N=: data != value

value

Specifies data to be compared. A string between single quotation marks(' ') or an integer value can be specified.
R

The command specifies the number of records for the extraction conditions. Currently, ALTER command is available.

The syntax of R is as follows:

R startnum[,endnum]
Parameter Description

startnum

Specifies the first record’s number.

endnum

Specifies the last record’s number. To process the entire record, specify EOF, if this parameter is not specified, only the first record is processed.
ED

The command specifies edit conditions. This command is available only for the EDIT function command.

The syntax of ED is as follows:

ED recvnum=sendnum
Parameter Description

recvnum

Specifies the key number to be edited. The key number is specified in the KEY statement.

sendnum

Specifies the number of the key containing the contents to be edited. The key number is specified in the KEY statement.
A

The command specifies items to be altered by ALTER.

The syntax of A is as follows:

A keypos,keylen,keyfmt,value
Parameter Description

keypos

This parameter specifies the starting position for alteration.

keylen

This parameter specifies the length of the item to be altered.

keyfmt

This parameter specifies the format of the item to be altered. The format is the same as keyfmt in the KEY command.

value

This parameter specifies what to be altered. A string between single quotation marks(' ') or an integer value can be specified.

2.3. Examples

The following example copies the OPENFRAME.ADAPT.U01 data set to the OPENFRAME. ADAPT.U11 data set. The record whose eighth character is '4,' and 225th character is '2' is copied, and otherwise copied to the OPENFRAME.ADAPT.U10 data set.

//JOB01    JOB CLASS=A,MSGCLASS=X,MSGLEVEL=(1,1)
//COPY     EXEC PGM=ADAPT
//U01      DD DSN=OPENFRAME.ADAPT.U01,DISP=SHR
//U10      DD DSN=OPENFRAME.ADAPT.U10,DISP=SHR
//U11      DD DSN=OPENFRAME.ADAPT.U11,DISP=SHR
//SYSOUT   DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
/      COPY    U11,U01,OUT2(U10)
/      KEY     8,1,X,225,1,X
/      K       1,E,'4'
/      K       2,E,'2'
/*

The following example edits the OPENFRAME.ADAPT.U01 data set, and stores it in the OPENFRAME.ADAPT.U02 data set. The string whose length starting from the 179th character is 3 is replaced by the one that starts from the 147th character and is as long as 3.

//JOB02    JOB CLASS=A,MSGCLASS=X,MSGLEVEL=(1,1)
//COPY     EXEC PGM=ADAPT
//U01      DD DSN=OPENFRAME.ADAPT.U01,DISP=SHR
//U02      DD DSN=OPENFRAME.ADAPT.U02,DISP=SHR
//SYSOUT   DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
/      EDIT    U02,U01
/      KEY     147,3,X,179,3,X
/      ED      2=1
/*

The following is an example of altering the OPENFRAME.ADAPT.U01 data set, and storing it in the OPENFRAME.ADAPT.U10 data set. If the record includes a string '498830' whose length starting from the 144th character is 6, and also contains another string '100' whose length starting from the 8th character is 3, a string that starts from the 169th character and is as long as 5 is altered to '00100,' and the one that starts from the 179th character and is as long as 6 is altered to '001000.'

If the record includes a string '498830' whose length starting from the 144th character is 6, and also contains another string '101' whose length starting from the 8th character is 3, a string that starts from the 169th character and is as long as 5 is altered to '00200,' and the one that starts from the 179th character and is as long as 6 is altered to '002000.'

//JOB03    JOB CLASS=A,MSGCLASS=X,MSGLEVEL=(1,1)
//COPY     EXEC PGM=ADAPT
//U01      DD DSN=OPENFRAME.ADAPT.U01,DISP=SHR
//U10      DD DSN=OPENFRAME.ADAPT.U10,DISP=SHR
//SYSOUT   DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
/      ALTER   U10,U01
/      KEY     144,6,X,8,3,X
/      K       1,E,'498830',2,E,'100'
/      A       169,5,X,'00100'
/      A       179,6,X,'001000'
/      K       1,E,'498830',2,E,'101'
/      A       169,5,X,'00200'
/      A       179,6,X,'002000'
/*

2.4. Return Codes

The result of executing ADAPT is as follows:

  • Upon success:

    It returns the return code (0), and in other cases, returns code 10.

  • In the case of an error:

    • The error message is displayed to SYSPRINT DD, and the error code 8 is returned. In other cases, the error code 50 is returned.

    • If a fatal error occurs, the error code 12 is returned, and in other cases, the error code 50 is returned.

3. DSDIFF

The utility shows the differences between data set records.

Once OpenFrame is installed or utility modules and library modules are updated, DSDIFF is used as a verification tool to check if the new data sets are correctly created.

3.1. DD Statements

The following describes each DD statement.

Statement Description

SYSIN DD

Specifies the ddname list of data sets to compare.

Use a comma (,) as the separator in the list.

e.g. 'AA,BB,CC' compares AA, BB, and CC.

TARGET DD

Specifies the data set to compare. The comparison data set must be included in the list of ddnames described in SYSIN DD.

3.2. Command Usage

The syntax of the data set list described in SYSIN DD is as follows:

ddname,ddname[ddname,....]

There is no parameter required for DSDIFF.

3.3. Examples

The following example shows the differences between the EXPECTED, INREC, and SUM DD records.

//JOB01    JOB CLASS=A,MSGCLASS=X,MSGLEVEL=(1,1)
//DSDIFF   EXEC PGM=DSDIFF,REGION=2M
//SYSIN    DD  *
EXPECTED,INREC,SUM
/*
//SYSOUT   DD SYSOUT=*
//EXPECTED DD  DSN=OFTEST.SORT.OUT01.EXPECTED,DISP=OLD
//INREC    DD  DSN=OFTEST.SORT.OUT01.INREC,DISP=OLD
//SUM      DD  DSN=OFTEST.SORT.OUT01.SUM,DISP=OLD

3.4. Return Codes

Regardless of their content, if the record lengths are different, DSDIFF marks the records as different.

The DSDIFF utility program shows the following batch execution results:

  • Upon success:

    It returns the return code from the batch program.

  • In the case of an error:

    Error messages are printed to SYSPRINT DD and corresponding return codes are returned.

    The following errors may occur in DSDIFF.

    Code Description

    4

    One or more differences in the records.

    16

    OpenFrame or UNIX error (The DDNAME specified in SYSIN does not exist, or there is a data set I/O error).

4. EZTPA00

The utility executes CA-Easytrieve Plus scripts entered as SYSIN from JCL.

To execute the script, an external program, TmaxSoft’s ProTrieve, is used. Configuration for the program is needed. Data set input/output, data processing, and report creation can be performed using the CA-Easytrieve Plus script.

The following figure illustrates how EZTPA00 operates. The CA-Easytrieve Plus script is transferred to ProTrieve and executed.

figure eztpa00 2
EZTAP00 Operation

For more about the CA-Easytrieve Plus script, refer to ProTrieve Guide.

4.1. DD Statements

The following describes each DD statement.

Usage Description

SYSIN DD

Specifies the input data set of the CA-Easytrieve Plus script.

SYSPRINT DD

Specifies the output data set of a message specified as DISPLAY or the report created as a result of CA-Easytrieve Plus.

SYSOUT DD

Specifies the output data set of a message that occurred in EZTPA00 and ProTrieve while operating CA-Easytrieve Plus.

anyname DD

Specifies the data set used to handle FILE in the CA-Easytrieve Plus statements. The DD name must have the same name as the CA-Easytrieve Plus script.

4.2. Examples

The following example copies data from FILEA to FILEB using EZTPA00.

//SAMPLE   JOB  CLASS=A,MSGCLASS=X,MSGLEVEL=(1,1)
//EZPLUS   EXEC PGM=EZTPA00
//SYSPRINT DD SYSOUT=*
//SYSOUT   DD SYSOUT=*
//FILEA    DD DSN=OPENFRAME.EZPLUS.FILEA,DISP=SHR
//FILEB    DD DSN=OPENFRAME.EZPLUS.FILEB,DISP=(NEW,CATLG),
//         DCB=(RECFM=FB,LRECL=1024,BLKSIZE=10240)
//SYSIN DD *
FILE FILEA
    RECA        1             1024  A
FILE FILEB
    RECB        1             1024  A
*
JOB INPUT FILEA
    MOVE FILEA TO FILEB
    PUT FILEB
/*

In the above example, if SYSOUT DD does not exist, a message that occurred while running the utility is printed to SYSPRINT and the desired output result cannot be obtained.

4.3. Environment Configuration

The configuration file for running EZTPA00 is set in ezplus subject sections in OpenFrame configuration.

For more about ezplus subject configuration, refer to OpenFrame Configuration Guide.

4.4. Return Codes

The result of executing EZTPA00 is as follows:

  • Upon success:

    It returns the return code 0 from an external program.

  • In the case of an error:

    Error messages are printed to SYSPRINT DD and return code 16 is returned.

5. FTP

The utility transfers data sets to a remote host, or to receive data from a remote host and store the data to data sets from a batch JOB.

5.1. DD Statements

The following describes each DD statement.

Statement Description

INPUT DD or

SYSIN DD

Specifies the FTP utility control statement.

SYSPRINT DD

Specifies the output data set to be used for message output.

OUTPUT DD

Specifies the output data set to be used to output messages generated in Unix/Linux FTP programs.

If OUTPUT DD is specified, messages generated in Unix/Linux FTP programs are output to OUTPUT DD, and messages generated in the FTP utility are output to SYSPRINT DD.

If OUTPUT DD is not specified, all messages are output to SYSPRINT DD.

5.2. Command Usage

Sets the JCL EXEC statement as follows to execute FTP:

//STEP  EXEC  PGM=FTP

Specify the FTP control statement in INPUT DD (or SYSIN DD). The STEP EXEC command has the following parameters:

Parameter Description

connect_ip

Sets the IP address of the FTP. This is the first statement in INPUT DD.

user_id password

Sets the FTP User ID and password for FTP server authentication. This parameter must follow connect_ip in INPUT DD.

KSC5601(NOTYPE | BIN | ASC)

Sets the FTP transfer format to binary or ASCII.

SJISKANJI (NOTYPE | BIN | ASC)

Sets the FTP transfer format to binary or ASCII.

BINARY | BIN

Changes the transfer format to binary.

ASCII | ASC

Changes the transfer format to ASCII.

STAT

Displays the current status of a remote host.

This option is not supported if the VALUE item of the SECURE_FTP key of OPTION section and the ftp subject in the OpenFrame environment setting is set to YES.

CLOSE

Closes the connection with a remote host.

DIR

Displays the current directory information of a remote host.

QUIT

Quits the FTP program.

LS

Searches the current directory information of a remote host.

PWD

Displays the current directories of a remote host.

LOCSITE

Changes the record format and length of the data set on the local host by additionally specifying RECFM, LRECL, BLKSIZE, and so on.

QUOTE

Sends an arbitrary FTP command to remote host.

CD

Changes a directory of a remote host.

LCD

Changes a directory of a local host.

DELETE | ERASE

Deletes a file from a remote host.

RENAME | REN

Changes a file name on a remote host.

RMDIR

Deletes a directory of a remote host.

MKDIR

Creates a directory of a remote host.

SET MAXCC

Specifies a return code when an error occurs.

PUT

Transfers files or data sets from a local host to a remote host. If transferring a data set, enclose the data set name in single quotation marks.

GET(REPLACE)

Transfers files from a remote host to a local host.

If transferring a data set, enclose the data set name in single quotation marks. Data transfer is performed in binary mode by default. If using ASCII mode, each line of the file is read and written to the data set.

If the file to be transferred is on the local host, the operation depends on the setting of the REPLACE option.

  • If the REPLACE option is specified, a warning message is displayed and the file is overwritten.

  • If the REPLACE option is not specified, an error occurs.

If the VALUE item of the SECURE_FTP key of the ftp subject and OPTION section in the OpenFrame environment setting is set to YES, the REPLACE option is not supported.

For more about the additional operation processing according to the value of the FTP_HANDLE_DATASET key of the OPTION section and ftp subject in the OpenFrame environment setting, refer to the corresponding setting.

APPEND

Appends additional data to an existing file in a remote host. If the specified file does not exist in the remote host, a new file is created.

This option is not supported if the VALUE item of the SECURE_FTP key of OPTION section and the ftp subject in the OpenFrame environment setting is set to YES.

//DD:ddname

Specifies '//DD:' followed by the ddname instead of the data set name to identify the data set of a DD statement in JCL.

SENDSITE

This parameter is officially supported to prevent errors from occurring.

MDELETE

Deletes multiple files from a remote host.

PROMPT

Sets the interactive or noninteractive mode.

This option is not supported if the VALUE item of the SECURE_FTP key of OPTION section and the ftp subject in the OpenFrame environment setting is set to YES.

TYPE(I|i|A|a)

Specifies the data transfer type.(If the command is not used, the default type is determined by Unix/Linux FTP mode.)

  • I | i: binary.

  • A | a: ASCII.

For more about setting ftp subejct in OpenFrame configuration, refer to OpenFrame Configuration Guide.

5.3. Examples

The following example connects to an FTP server at 127.0.0.1 and uploads the FTPTEST01.txt file to the home/ftptest/temp directory.

//FTP01    JOB CLASS=A,MSGCLASS=X,MSGLEVEL=(1,1)
//PMFTP    EXEC PGM=FTP,PARM='(EXIT'
//INPUT    DD *
  127.0.0.1
 ftptest ftptest
 KSC5601 (NOTYPE
 CD /home/ftptest/temp/
 PUT 'FTPTEST01'   /home/ftptest/temp/FTPTEST01.TXT
 QUIT
/*
//SYSPRINT DD SYSOUT=*
/*

The following example connects to an FTP server at 127.0.0.1 and downloads the FTPTEST02.txt file from the home/ftptest/temp directory to the OFTEST.FTP.GET01 data set on the local host.

//FTP02    JOB CLASS=A,MSGCLASS=X,MSGLEVEL=(1,1)
//PMFTP    EXEC PGM=FTP
//DD1      DD DSN=OFTEST.FTP.GET01,DISP=(NEW,CATLG,DELETE),DCB=(RECFM=FB,LRECL=80)
//INPUT    DD *
  127.0.0.1
 ftptest ftptest
 KSC5601 (NOTYPE
 GET /home/ftptest/temp/FTPTEST02.TXT //DD:DD1
 QUIT
/*
//SYSPRINT DD SYSOUT=*
/*

5.4. Environment Configuration

The FTP program uses information of the ftp and ofsys subjects to locate temporary files or to distinguish error codes from the FTP server. Also, the information of the ds subject is used to determine whether the authority is authenticated.

When FTP executes a GET command, if the path of the target data set does not exist in the GET command, the file is downloaded to the temporary directory path of the ofsys subject. In addition, the directory information of the ftp subject is used as a directory for creating temporary files generated during FTP utility execution.

For more about the environment configuration, refer to OpenFrame Configuration Guide.

6. ICETOOL

The utility uses SORT to output multiple data sets in a single JOB STEP. The data set can be manipulated in various ways. The method for manipulating the output data sets is set in the TOOLIN DD statement.

The ICETOOL utility program performs the following tasks:

  • Creates a copy of sorted input data sets.

  • Creates a copy of modified or unmodified input data sets.

  • Prints the record count of modified or unmodified input data sets.

  • Creates an output data set with highly customized filtering criteria carried out on the input data set. For example, the input data set can be selected based on the number of characters, numerical values, or unique values.

  • Combines record fields that have different formats, and prints them into one or more records.

6.1. DD Statements

The following describes each DD statement.

Usage Description

TOOLMSG

Stores output messages from ICETOOL.

DFSMSG

Stores output messages that are generated while ICETOOL internally uses SORT.

TOOLIN

Sets commands of ICETOOL.

indd

Sets the input data set for ICETOOL. indd is specified using the FROM (indd) command in TOOLIN.

outdd

Sets the output data set for the COPY, SELECT, and SORT tasks in ICETOOL. outdd is specified using the TO (outdd) command in TOOLIN.

savedd

Sets the output data set for the SELECT task in ICETOOL. savedd is specified using the DISCARD (savedd) command in TOOLIN.

countdd

Sets the output data set to be used for the COUNT task of ICETOOL.

xxxxCNTL

Sets commands of SORT to be used in ICETOOL. xxxxCNTL DD is specified using the USING xxxx command in TOOLIN.

6.2. Command Usage

This section describes the commands that can be set in ICETOOL.

COPY

Copies an input data set specified in indd to one or more outdds. The USING xxxxCNTL statement can be used in conjunction to perform SORT as well.

The syntax of the COPY command is as follows:

COPY FROM(indd)
      TO(outdd,[outdd,...]) | USING(xxxx) | {TO(outdd,[outdd,....])
      USING(xxxx)} [VSAMTYPE(x)] [SERIAL]
Parameter Description

FROM

Sets the input data set where the COPY command is to be performed.

TO

Sets the output data set where the result of the COPY command is stored. outdd stores all the same results. Either TO or USING must be specified, it is possible to set both.

USING

Sets commands of SORT to be used by COPY. If USING is specified, it is required to set the xxxxCNTL DD. If TO is not specified, it is required to set the output data set as OUTFIL in the xxxxCNTL DD.

VSAMTYPE

This parameter is officially supported to prevent errors from occurring.

SERIAL

This parameter is officially supported to prevent errors from occurring.
COUNT

Prints the record count of the input data set. If USING is specified, it outputs the count of reformatted records.

The syntax of the COUNT command is as follows:

COUNT FROM(indd) [USING(xxxx)]
    [RC4] [EMPTY] [EQUAL(v)] [WRITE(countdd)] [TEXT('string')]
    [DIGITS(d)]
Parameter Description

FROM

Sets the input data set where the COUNT command is performed.

USING

Sets commands of SORT to be used by COUNT.

RC4

If RC4 is specified, and the conditions of EMPTY, NOTEMPTY, HIGHER(x), LOWER(y), EQUAL(v), or NOTEQUAL(w) are satisfied, RC=4 is returned. In OpenFrame, only the EMPTY condition is supported. The default value is RC=12.

EMPTY

If the input data set is empty, RC=12 (RC=4 if RC4 is specified) is returned. If the input data set is not empty, RC=0 is returned.

EQUAL(v)

Returns RC=12 (RC=4 if RC4 is specified) as a result of the COUNT statement if the record count is v.

WRITE(countdd)

Sets countdd. countdd means the ddname of the data set that outputs the record count. The format of countdd DD can be specified only with FB.

TEXT('string')

Prints strings to the countdd data set. The record count is outputted after the corresponding string. TEXT can be used only when WRITE is specified.

DIGITS(d)

Sets the number of digits of the record count. If DIGITS is not specified, 15 is set by default.
DISPLAY

Prints the values of the input data set, indd, in the specified format.

The syntax of the DISPLAY command is as follows:

DISPLAY FROM(indd)
        LIST(listdd) ON(p,m,f)[ ON(p,m,f) ...]
        ON(p,m,f,E'pattern')[ ON(p,m,f,E'pattern') ...] ON(VLEN)
        ON(NUM) TITLE('string1') PAGE DATE(abcd) TIME(abc)
        BLANK HEADER('string1') [HEADER('string1') ...]
        LINES(n) COUNT('string') WIDTH(n) BETWEEN(n)
Parameter Description

FROM

Specifies input data set.

LIST

Specifies the list data set name to be displayed.

ON(p,m,f)

Specifies the field to which the DISPLAY command applies. The DISPLAY command is applied under an 'f' format, with a minimum and maximum number of bytes 'p' and 'm', respectively. For more information about available 'f' formats, refer to the description for "OUTREC | BUILD" from "Chapter 2.12. OUTFIL" in OpenFrame SORT Utility Reference Guide.

ON(p,m,f,E’pattern')

Specifies the field to which the DISPLAY command applies. The DISPLAY command is converted into an 'f' format, with a minimum and maximum number of bytes 'p' and 'm', respectively, and then applied as specified in 'pattern'. For more information about available 'f' formats, refer to the description for "OUTREC | BUILD" from "Chapter 2.12. OUTFIL" in OpenFrame SORT Utility Reference Guide.

ON(VLEN)

Specifies the record length for variable length record (VB). Equivalent to ON(1,2,BI). Default value:16 byte.

ON(NUM)

Prints the record number starting at 1 and incrementing by 1 for each record.

TITLE('string1')

Prints the title (string1) on the title line, which is the first line of the list data set.

PAGE

Prints the current page on the title line.

DATE(abcd)

Prints the current date in the specified format on the title line.

  • abc: A combination of M(month), D(date), Y(year), or 4. Y prints the year in two digits and 4 in four digits.

  • d: Date separator of any character.

TIME(abc)

Displays the current time on the title line.

  • ab: 12 or 24 hour time format

  • c: Time separator of any character.

BLANK

Displays as space for leading zeros in a numeric field.

HEADER('string1')

Prints a heading for the corresponding field specified with ON. HEADER and ON field are matched in the order in which they are specified.

LINES(n)

Number of lines to print per page. n must be a value between 10 and 999. (Default value: 58)

COUNT('string')

Prints 'string' followed by the record count.

WIDTH(n)

Specifies row length limit of the list data set.

BETWEEN(n)

Specifies the number of empty columns for the data set to be printed. n must be a value between 0 and 50. (Default value: 3)
OCCUR(S)

Displays the set field and how many times the field appears.

The syntax of the OCCUR command is as follows:

OCCUR(S) FROM(indd)
      LIST(listdd) ON(p,m,f)[ ON(p,m,f) ...] ON(VLEN) ON(VALCNT) ON(VALCNT,Ndd)
      TITLE('string1') DATE(abcd) TIME(abc) BLANK HEADER('string1') [
      HEADER('string1') ...] NOHEADER LINES(n)
Parameter Description

FROM

Specifies the input data set.

LIST

Specifies the list data set name to be displayed.

ON(p,m,f)

Specifies the fields where the OCCUR statement is applied. The OCCUR statement is applied from p bytes by m bytes in the f format.

ON(VLEN)

Displays the record length when the input record is a variable length record (VB). Same with ON(1,2,BI). The VLEN field length is 16 bytes by default.

ON(VALCNT)

Displays the number of times that the field set by ON(p,m,f) appears. The VALCNT field length is 15 bytes by default.

ON(VALCNT,Ndd)

Displays the number of times that the field set by ON(p,m,f) appears. The VALCNT field length is 'dd' bytes.

TITLE('string1')

Displays the title (string1) of the title line. The title line is displayed in the first line of list data set.

DATE(abcd)

Displays the current date in the title line.

  • abc: Combination of M(month), D(date), Y(year) or 4. Y and 4 displays the year as 2 digits and 4 digits respectively.

  • d: Any character can be used as a separator.

TIME(abc)

Displays the current time in the title line.

  • ab: Represents time. 12 (12 hour format) or 24 (24 hour format) can be used.

  • c: Any character can be used as a separator.

BLANK

Displays leading zeros as blank spaces in a number field.

HEADER('string1')

Displays the title according to the corresponding ON field. HEADER operands and ON fields correspond one-to-one according to the order that they are specified.

NOHEADER

Does not display the HEADER.

LINES(n)

Displays the number of lines per page. n must be a value between 10 and 999. (Default value: 58)
SELECT

Filters the input data given in indd by the condition given in SELECT command. The filtered result is stored in todd and data that failed to pass the filter is stored in savedd.

The syntax of the SELECT command is as follows:

SELECT FROM(indd) TO(outdd)
      | DISCARD(savedd) | {TO(outdd) DISCARD(savedd)}
      ON(p,m,f)[ ON(p,m,f)...]
      ALLDUPS | NODUPS | HIGHER(x) | LOWER(x) | EQUAL(x) | FIRST | LAST |
      FIRSTDUP | LASTDUP [VSAMTYPE(x)] [UZERO] [USING(xxxx)]
Parameter Description

FROM

Specifies the input data set.

TO

Specifies the output data set where filtered records are stored.

DISCARD

Specifies the output data set where records to be discarded upon filtering are stored.

ON

Specifies the fields where the SELECT command is applied. The SELECT command is applied from p bytes by m bytes in the f format.

ALLDUPS

Stores only the data set records that have duplicate values in the fields specified in the ON parameter.

NODUPS

Stores only the data set records that do not have duplicate values in the fields specified in the ON parameter.

HIGHER

Stores only the records where the field value in the ON parameter occurs more than x times.

LOWER

Stores only the records where the field value in the ON parameter occurs less than x times.

EQUAL

Stores only the records where the field value in the ON parameter occurs x times.

FIRST

Stores only the first record among records in the input data set that are duplicate with values in the fields specified in the ON parameter.

LAST

Stores only the last record among records in the input data set that are duplicate with values in the fields specified in the ON parameter.

FIRSTDUP

Stores only the first record from the list of duplicate records where the field values in the ON parameter are the same.

LASTDUP

Stores only the last record from the list of duplicate records where the field values in the ON parameter are the same.

VSAMTYPE

This parameter is officially supported to prevent errors from occurring.

UZERO

This parameter is officially supported to prevent errors from occurring.

USING

Sets commands of SORT to be used by SELECT.
SORT

Sorts the input data set, and outputs it to one or more data sets. It calls the SORT utility to sort and reformat the input data set.

The syntax of the SORT command is as follows:

SORT FROM(indd) USING(xxxx)
    [TO(outdd,[outdd,...])] [VSAMTYPE(x)] [SERIAL]
Parameter Description

FROM

Sets the input data set where the SORT command is performed.

USING

Sets commands of SORT to be used by SORT. For SORT, USING must be specified, and the xxxxCNTL DD statement should include the SORT command.

TO

Sets the output data set where the result of the SORT command is stored. outdd stores all the same results.

VSAMTYPE

This parameter is officially supported to prevent errors from occurring.

SERIAL

This parameter is officially supported to prevent errors from occurring.
SPLICE

Overwrites base records with matching overlay record fields. It enables different-type input records to be integrated into a single output record containing various information.

Record matching can be checked with ON. The first matching record becomes a base record, and the others become overlay records. (If no option is specified, the last matching record is an overlay record.) The WITH field of the base record is replaced by the one that is specified in WITH of the overlay record. The other fields of the base record are kept the same. The output record consists of a combination of the base record and overlay records.

SPLICE FROM(indd) TO(outdd)
    ON(p,m,f)[ ON(p,m,f) ...] WITH(p,m)[ WITH(p,m) ...] [WITHALL] [WITHEACH]
   [KEEPNODUPS] [KEEPBASE][USING(xxxx)]
Parameter Description

FROM

Specifies the input data set.

TO

Specifies the output data set where integrated records are stored.

ON

Specifies the fields where record matching is applied. The record matching is applied from p bytes by m bytes in the f format.

WITH

Replaces the base record according to the position and the length specified in the overlay record. Multiple fields can be replaced by using WITH several times.

WITHALL

All overlay records are used to overlay the base record. If WITHALL is not specified, only the last overlay record is used to replace the base record.

WITHEACH

nth overlay records are used to overlay the base record of the nth WITH field. If there are more overlay records than the number of WITH fields, the records are not overlaid.

KEEPNODUPS

Sets that non-matching records are not deleted, and can be output. If KEEPNODUPS is not specified, non-matching records are removed.

KEEPBASE

Does not delete and outputs matching records specified in the BASE data set (data set specified in FROM). If KEEPBASE is not specified, matching records specified in the BASE data set are deleted.

USING

Sets commands of SORT to be used by SPLICE.
DATASORT

Copies one or more header records and one or more trailer records to outdd in their original input record order. You can also run the SORT utility using xxxxCNTL through the USING clause.

The syntax of the DATASORT command is as follows:

DATASORT FROM(indd) TO(outdd) USING(xxxx)
      | [HEADER] | [FIRST] | [HEADER(u)] | [FIRST(u)]| [TRAILER] | [LAST] | [TRAILER(v)] | [LAST(v)] | [VSAMTYPE(x)]
Parameter Description

FROM

Specifies the input data set where the DATASORT command is performed.

TO

Specifies the output data set where the DATASORT command is performed.

USING(xxxx)

Specifies commands of SORT to be used by DATASORT. A xxxxCNTL DD command should be supplied when you specify the USING clause.

HEADER

Operates the same as HEADER(1).

FIRST

Operates the same as HEADER(1).

HEADER(u)

The first u records of the data set are copied directly to the output data set without going through the SORT utility, and the remaining records are sent to the SORT utility.

FIRST(u)

Operates the same as HEADER(u).

TRAILER

Operates the same as TRAILER(1).

LAST

Operates the same as TRAILER(1).

TRAILER(v)

The last v records of the data set are copied directly to the output data set without going through the SORT utility, and the remaining records are sent to the SORT utility.

LAST(v)

Operates the same as TRAILER(v).

VSAMTYPE is officially supported to prevent errors from occurring.

6.3. Examples

The following example copies OFTEST.ICETOOL.IN00 to OFTEST.ICETOOL.OUT00.COPY as instructed in the SORT script given in CPY1CNTL DD.

//JOB01    JOB CLASS=A,MSGCLASS=X,MSGLEVEL=(1,1)
//ICECOPY  EXEC PGM=ICETOOL,REGION=2M
//ICEIN    DD DSN=OFTEST.ICETOOL.IN00,
//         DISP=(OLD,KEEP,KEEP),RECFM=FB,LRECL=80
//ICEOUT   DD DSN=OFTEST.ICETOOL.OUT00.COPY,
//         DISP=(NEW,CATLG,DELETE),RECFM=FB,LRECL=80
//TOOLMSG  DD SYSOUT=*
//DFSMSG   DD SYSOUT=*
//SYSOUT   DD SYSOUT=*
//TOOLIN   DD *
 COPY FROM(ICEIN) TO(ICEOUT) USING(CPY1)
/*
//CPY1CNTL DD *
 SORT FIELDS=COPY
/*

The following example reformats OFTEST.ICETOOL.IN00 as instructed in the SORT script given in CPY1CNTL DD, and outputs the record count to OFTEST.ICETOOL.OUT01.COUNT.

The record count is output as a nine-digit number after 'OUTPUT RECORD COUNT = '. If a record satisfying the condition does not exist, RC=4 is returned, and if such records exist, RC=0 is returned.

//JOB02    JOB CLASS=A,MSGCLASS=X,MSGLEVEL=(1,1)
//ICECOUNT EXEC PGM=ICETOOL,REGION=2M
//ICEIN    DD DSN=OFTEST.ICETOOL.IN00,
//         DISP=(OLD,KEEP,KEEP),RECFM=FB,LRECL=80
//CNTDD    DD DSN=OFTEST.ICETOOL.OUT01.COUNT,
//         DISP=(NEW,CATLG,DELETE),RECFM=FB,LRECL=80
//TOOLMSG  DD SYSOUT=*
//DFSMSG   DD SYSOUT=*
//SYSOUT   DD SYSOUT=*
//TOOLIN   DD *
 COUNT FROM(ICEIN) USING(CPY1) WRITE(CNTDD) -
 TEXT('OUTPUT RECORD COUNT = ') DIGITS(9) -
 EMPTY RC4
//CPY1CNTL DD *
 SORT FIELDS=COPY
 INCLUDE COND=(16,2,CH,EQ,C'08')
/*

The following example copies OFTEST.ICETOOL.IN01 to OFTEST.ICETOOL.OUT01.ICECPY1 and OFTEST.ICETOOL.OUT01.ICECPY2 as instructed in the SORT script given in CPY1CNTL DD.

The 2 bytes in the 16th to 17th byte location in the OFTEST.ICETOOL.OUT01.ICECPY2 record are set as character keys. If there are records with duplicate character keys, save to OFTEST.ICETOOL.OUT01.ICETO. Otherwise, save to OFTEST.ICETOOL.OUT01.ICESAVE.

//JOB03    JOB CLASS=A,MSGCLASS=X,MSGLEVEL=(1,1)
//ICECOPY  EXEC PGM=ICETOOL,REGION=2M
//ICEIN    DD DSN=OFTEST.ICETOOL.IN01,
//         DISP=(OLD,KEEP,KEEP),RECFM=FB,LRECL=80
//ICECPY1  DD DSN=OFTEST.ICETOOL.OUT01.ICECPY1,
//         DISP=(NEW,CATLG,DELETE),RECFM=FB,LRECL=80
//ICECPY2  DD DSN=OFTEST.ICETOOL.OUT01.ICECPY2,
//         DISP=(NEW,CATLG,DELETE),RECFM=FB,LRECL=80
//ICETO    DD DSN=OFTEST.ICETOOL.OUT01.ICETO,
//         DISP=(NEW,CATLG,DELETE),RECFM=FB,LRECL=80
//ICESAVE  DD   DSN=OFTEST.ICETOOL.OUT01.ICESAVE,
//         DISP=(NEW,CATLG,DELETE),RECFM=FB,LRECL=80
//TOOLMSG  DD SYSOUT=*
//DFSMSG   DD SYSOUT=*
//SYSOUT   DD SYSOUT=*
//TOOLIN   DD *
 COPY FROM(ICEIN) TO(ICECPY1,ICECPY2) USING(CPY1)
 SELECT FROM(ICECPY2) TO(ICETO) DISCARD(ICESAVE) ON(16,2,CH) NODUPS
/*
//CPY1CNTL DD *
 SORT FIELDS=COPY
/*

The following example is the result of executing DISPLAY on OFTEST.ICETOOL.IN01 to print the output as OFTEST.ICETOOL.OUT01.

//JOB04    JOB CLASS=A,MSGCLASS=X,MSGLEVEL=(1,1)
//DISPLAY  EXEC PGM=ICETOOL,REGION=2M
//ICEIN    DD DSN=OFTEST.ICETOOL.IN01,
//         DISP=(OLD,KEEP,KEEP),RECFM=FB,LRECL=80
//ICEOUT   DD DSN=OFTEST.ICETOOL.OUT01,
//         DISP=(NEW,CATLG,DELETE),RECFM=FB,LRECL=80
//TOOLMSG  DD SYSOUT=*
//DFSMSG   DD SYSOUT=*
//SYSOUT   DD SYSOUT=*
//TOOLIN   DD *
   DISPLAY LINES(50) FROM(ICEIN) LIST(ICEOUT) -
   TITLE('TITLE') DATE(DM4.) TIME PAGE -
   HEADER('HEADER1') ON(10,3,CH) -
   BLANK -
   COUNT('COUNT')
/*

The following example reformats OFTEST.ICETOOL.IN01 and OFTEST.ICETOOL.IN02 by using CTL1CNTL DD and CTL2CNTL DD respectively, and stores them in OFTEST.ICETOOL.TEMP01. It, then, splices them to OFTEST.ICETOOL.OUT01.COMBINE.

In CTL3CNTL DD, records whose 15th character is not '1' in OFTEST.ICETOOL.TEMP, are separately stored in OFTEST.ICETOOL.OUT01.FILTERED.

//JOB05    JOB CLASS=A,MSGCLASS=X,MSGLEVEL=(1,1)
//SPLICE   EXEC PGM=ICETOOL,REGION=2M
//IN1      DD DSN=OFTEST.ICETOOL.IN01,DISP=(OLD,KEEP,KEEP)
//IN2      DD DSN=OFTEST.ICETOOL.IN02,DISP=(OLD,KEEP,KEEP)
//TEMP     DD DSN=OFTEST.ICETOOL.TEMP,DISP=(MOD,PASS)
//COMBINE  DD DSN=OFTEST.ICETOOL.OUT01.COMBINE,DISP=(NEW,CATLG,DELETE)
//FILTERED DD DSN=OFTEST.ICETOOL.OUT01.FILTERED,DISP=(NEW,CATLG,DELETE)
//TOOLMSG  DD SYSOUT=*
//DFSMSG   DD SYSOUT=*
//SYSOUT   DD SYSOUT=*
//TOOLIN   DD *
 COPY FROM(IN1) TO(TEMP) USING(CTL1)
 COPY FROM(IN2) TO(TEMP) USING(CTL2)
 SPLICE FROM(TEMP) TO(COMBINE) ON(5,5,ZD) WITH(15,17) USING(CTL3)
/*
//CTL1CNTL DD *
 SORT FIELDS=COPY
 OUTREC FIELDS=(1,14,31:X)
/*
//CTL2CNTL DD *
 SORT FIELDS=COPY
 OUTREC FIELDS=(5:1,5,15:7,15,30:33,2)
/*
//CTL3CNTL DD *
 OUTFIL FNAMES=FILTERED,OMIT=(15,1,CH,EQ,C'1')

The following example copies 2 records from the start of OFTEST.ICETOOL.IN00 and the last 1 record to OFTEST.ICETOOL.OUT00.DATS, and then copy the remaining records to OFTEST.ICETOOL.OUT00.DATS using the SORT script given in DATSCNTL DD.

//JOB01    JOB CLASS=A,MSGCLASS=X,MSGLEVEL=(1,1)
//ICECOPY  EXEC PGM=ICETOOL,REGION=2M
//ICEIN    DD DSN=OFTEST.ICETOOL.IN00,
//         DISP=(OLD,KEEP,KEEP),RECFM=FB,LRECL=80
//ICEOUT   DD DSN=OFTEST.ICETOOL.OUT00.DATS,
//         DISP=(NEW,CATLG,DELETE),RECFM=FB,LRECL=80
//TOOLMSG  DD SYSOUT=*
//DFSMSG   DD SYSOUT=*
//SYSOUT   DD SYSOUT=*
//TOOLIN   DD *
 DATASORT FROM(ICEIN) TO(ICEOUT) HEADER(2) TRAILER USING(DATS)
/*
//DATSCNTL DD *
 SORT FIELDS=(1,8,CH,A)
/*

6.4. Return Codes

The utility program shows the following batch execution results:

  • Upon success:

    It returns the return code from the batch program.

  • In the case of an error:

    Error messages are output to SYSPRINT DD and the return code 16, is returned.

7. IEFBR14

The utility is a test utility program used to check the execution status of a JCL script. Internally, it does not generate any other tasks.

IEFBR14 can only check for the execution status after the completion of the following process. A JCL script is sent to JCL and the JOB is executed in the JOB queue. Then tjclrun must be activated in order to allocate the data set specified in the JCL DD statement.

7.1. DD Statments

There is no DD statement required for the IEFBR14 utility program.

7.2. Command Usage

There is no command statement required for the IEFBR14 utility program.

7.3. Examples

The following example creates DATASET1 and deletes DATASET2, once JCL is executed.

//LISTPDS  JOB CLASS=A,MSGCLASS=X,MSGLEVEL=(1,1)
//STEP01   EXEC PGM=IEFBR14
//NEW      DD DSNAME=DATASET1,DISP=(NEW,KEEP),
//            DCB=(RECFM=FB,LRECL=100,BLKSIZE=1000)
//DELETE   DD DSNAME=DATASET2,DISP=(OLD,DELETE)
//SYSPRINT DD SYSOUT=*
//SYSIN    DD DUMMY

7.4. Return codes

Once the IEFBR14 utility program successfully executes a batch program, it returns the return code from the batch program.

8. IKJEFT01

The utility connects to the database system before the application is executed when the batch application using the database is executed with JCL.

All information required to access the database system is specified in the input script of the IKJEFT01 utility program without coding information such as the system name, user name, and password required to access the database system in the source of the business COBOL application that uses the database.

The PROGRAM defined in the PROGRAM option of the TSO script used in the IKJEFT01 utility program must be compiled in the form of Shared Object.

The mainframe uses the TSO Attachment Facility to connect to DB2 and then executes the DB2 application. The TSO Attachment Facility is a DB2 module that allows a TSO terminal or batch program to access DB2. IKJEFT01 utility program is an OpenFrame database access utility program that allows you to process batch jobs using TSO commands.

The IKJEFT01 utility program provided by OpenFrame provides only the connection function to the database for executing the Batch application (PROGRAM defined in the PROGRAM option of the TSO script), and the DB2 system commands are ignored.

For information on how to compile a Batch application, refer to OpenFrame Migration Guide.

8.1. DD Statements

The following describes each DD statement.

Statement Description

SYSTSPRT DD

Results and error messages are printed to SYSTSPRT. If there are error messages before SYSTSPRT is ready, messages are output to SYSOUT DD.

SYSTSIN DD

Sets the IKJEFT01 input script.

8.2. PARM Statement

IKJEFT01 can execute TSO commands through the PARM statement. Specify a TSO command to be executed in the PARM statement. Here, the TSO command must be enclosed with single quotation marks. Also, the operands for the TSO command must be enclosed with two (for each side) single quotation marks. The maximum allowable length of a TSO command is limited to 100 characters.

The following JCL example executes CLIST through the PARM statement, to pass a required parameter.

//PARMEXAM JOB
//STEP010  EXEC PGM=IKJEFT01,
//         PARM='EXEC ''SYS1.TSOLIB(CLIST01)'' ''FIRST'' ''SECOND'''
//SYSTSIN  DD DUMMY
//SYSTSPRT DD DUMMY
//SYSOUT   DD SYSOUT=*

The following is the CLIST to be executed in the previous example.

PROC 2 ARG01 ARG02
WRITE &ARG01 MESSAGE
WRITE &ARG02 MESSAGE

The following shows the SYSOUT content from the results of the previous JCL.

FIRST MESSAGE
SECOND MESSAGE

8.3. Command Usage

This section describes the IKJEFT01 commands.

DSN

The syntax of the DSN command is as follows:

DSN [SYSTEM(DSN|subsystem-name)]
    [RETRY(0|integer)]
Parameter Description

SYSTEM

Specifies the name of the database subsystem.

If a value is not specified, SYSTEM(DSN) is used by default, and for the specified database subsystem name, the ikjeft01 subject of the environment setting table and the VALUE item of the subkeys of the SYSTEM:{system} section must be set. For more information, refer to OpenFrame Configuration Guide.

RETRY

Specifies the number of attempts to make a connection to the database subsystem.

If nothing is set, 0 is used by default. The value 0 will set the number of attempts to the maximum value, 120. The connection retry interval is 30 seconds.

DSN is a TSO command which starts a new DSN (DB2 Command Processor) session and supports the following subcommands:

Command Description

RUN

Executes user applications.

END

Disconnects from the database and returns to TSO.

Currently, the DSN command of the IKJEFT01 utility only supports the following subcommands formally so as not to generate an error.

Command Description

ABEND

Quits DSN session and returns ABEND code.

BIND

Creates application package or plan.

DCLGEN

Creates SQL statements and definition tables.

FREE

Deletes application package or plan.

REBIND

Recreates application package or plan.

SPUFI

Executes SQL statements from an SQL file.

Both database commands and comments can be entered while a DSN session is connected. A database command starts with a hyphen (-), and a comment starts with an asterisk (*).

The following database commands can be used in OpenFrame while a DSN session is connected:

Command Description

DISPLAY

Outputs detailed information to the database.

START

Starts the selected database.

STOP

Starts the selected database.

Database commands frequently used in Mainframe are also defined in OpenFrame. However, some of their functionalities are not yet implemented to prevent errors from occurring within OpenFrame.
RUN

RUN is a subcommand of DSN that executes programs which include SQL statements.

The syntax of the RUN subcommand is as follows:

RUN PROGRAM(program-name)
    [PLAN(plan-name)]
    [LIBRARY(library-name)]
    [PARMS(parameter-string)]

RUN [LIBRARY(library-name)]
    [PARMS(parameter-string)]
Parameter Description

PROGRAM

Specifies the name of the program to execute.

PLAN

The IKJEFT01 utility supports not to generate an error for the corresponding parameter.

LIBRARY

Specifies the name of the PDS data set containing the application. (Abbreviation: LIB)

PARMS

Specifies a list of parameters that need to be passed to the application. (Abbreviation: PARM)
END

END is a subcommand for DSN which terminates the DSN session and returns to TSO.

The syntax of the END subcommand is as follows:

END

8.4. Examples

The following example creates a DSN session to a MYDB database system. If a DSN session cannot be created, reconnection is attempted every 30 seconds up to a maximum of 5 times.

DSN SYSTEM (MYDB) RETRY (5)

The next example connects to a DSN database system and executes the COBTEST1 program which is located in the 'TEST.RUNLIB.LOAD' library.

DSN SYSTEM (DSN)
RUN PROGRAM (COBTEST1) LIB ('TEST.RUNLIB.LOAD')

The following is an example of connecting to the DSN system, executing the COBTEST2 program in the 'TEST.RUNLIB.LOAD' library, and passing '1234567890' as a parameter of the COBTEST2 program.

DSN SYSTEM (DSN)
RUN PROGRAM (COBTEST2) PLAN (COBTEST2) -
     LIB ('TEST.RUNLIB.LOAD') PARMS ('1234567890')

8.5. Environment Configuration

You can set the database system name and authentication information to ikjeft01 subject.

  1. For more about ikjeft01 subject environment configuration, refer to OpenFrame Configuration Guide.

  2. The similar utility programs are PGMRTS00 (Runtime Environment Control Program) and DFSRRC00 (HiDB Region Control Program).

8.6. Other Considerations

The IKJEFT01 utility program must designate the TSO script in SYSTSIN DD, and at this time, the PROGRAM defined in the 'PROGRAM' option among the TSO scripts must be in the Shared Object format. Currently, the IKJEFT01 utility program does not support shell script or executable objects.

When the DSN command and the DSN subcommand are used together, the following parsing rule applies.

  • Use a hyphen (-) at the end of each line if more than one line is required to complete the command.

The following example shows how you can call multiple subcommands on multiple lines.

RUN PROGRAM(TECA251) -
PLAN(TECA251) -
LIB('MI.PROG.CLINK') -
PARM('2')

The IKJEFT01 utility program shows the following batch execution results:

  • Upon success:

    It returns the return code from the batch program.

  • In the case of an error:

    Error messages are output to SYSTSPRT DD and corresponding return codes are returned. If SYSTSPRT DD is not ready, error messages are redirected to SYSOUT DD.

    The following errors may occur in IKJEFT01:

    Code Description

    12

    Unrecoverable error. The cases include:

    • Data set authentication related errors

    • SYSTSIN DD is not provided

    • SYSTSPRT DD is not provided

    • SYSTSIN DD file cannot be found

    • SYSTSIN DD cannot support the binary type

    • SYSTSIN DD script parsing error

    • Not suitable TSO command

    • PROGRAM is not specified in RUN command

    • PROGRAM specified in RUN command cannot be found

    • Application cannot be found

    • Application binary error

    • Cannot connect to database

    • Dynamic memory cannot be opened (dlopen)

    • Entry point search failure (dlsym)

    16

    System fault. The cases include:

    • OpenFrame system library initialization failure

    • SYSTSPRT DD cannot be opened

    • SYSTSIN DD binary check error

    • SYSTSIN DD cannot be opened

    • Temporary file cannot be created

    • SYSTSIN DD read error

    • Application binary error

    • Database system configuration read error

    • Process fork failed

    • Input/Output redirect failed

9. ISRSUPC

The utility compares two data sets, and searches for a certain string in a data set. According to the process option specified in PARM and the process statement described in SYSIN, various functions are supported.

9.1. DD Statements

The following describes each DD statement.

Statement Description

OLDDD DD

Specifies the input data set to be compared. This DD is not used to search for a particular string in a data set.

NEWDD DD

Specifies the input data set to compare.

OUTDD DD

Stores outputs of ISRSUPC. (OUTDD is supported only for SYSOUT or Non-VSAM data sets.)

SYSIN DD

Specifies commands of ISRSUPC.

SYSPRINT DD or SYSOUT DD

Displays error messages issued while executing ISRSUPC.

9.2. Options Set in PARM

The following options can be used for PARM of a JCL EXEC statement:

Option Description

ANYC

Does not distinguish lower case letters from capital letters when comparing two data sets or searching for a string in a data set.

DELTA or DELTAL

When printing data set comparison results, only lines with different comparison results are printed to OUTDD. Currently, only DELTA or DELTAL is supported.

LINECMP

Compares data sets line by line. Currently, only LINECMP is supported.

SRCHCMP

Searches for a certain string in a data set.

9.3. Command Usage

The following commands can be set through SYSIN DD:

CMPCOLM

Specifies the column in the line of the data set to be compared.

The syntax of the CMPCOLM command is as follows:

CMPCOLM start-colm[:stop-colm][,...]
Parameter Description

start-colm

Specifies a starting position for comparison in the column.

stop-colm

Specifies an end position for comparison in the column. If not specified, only one character from start-colm is compared.
SRCHFOR or SRCHFORC

When searching for a specific string in one data set, you can specify the search string and the search range. In the case of SRCHFORC, the string is searched only in the line in which the string is found in the previous SRCHFOR or SRCOFORC syntax.

The syntax of the SRCHFOR or SRCHFORC command is as follows:

SRCHFOR 'string'[,srch-type][,start-colm[:stop-colm]]
SRCHFORC 'string'[,srch-type][,start-colm[:stop-colm]]
Parameter Description

string

Sets a string to search for.

srch-type

Sets the type of the string to search for. P, S, or W can be selected.

  • P: Specifies the prefix. All the strings including the given string in their first part are also searched.

    (e.g. When searching for 'test', 'test1', 'test-type', and 'test' are all searched.)

  • S: Specifies the suffix. All the strings including the given string in their last part are also searched.

    (e.g. When searching for 'test', 'pretest', 'sample-test', and 'test' are all searched.)

  • W: Specifies the word. Strings which are identical to the given string are searched.

    (e.g. When searching for 'test', only 'test' is searched.)

start-colm

Sets a starting position for the search.

stop-colm

Sets an end position for the search. If even one character of the given string is within stop-colm, the string can be searched. For instance, if stop-colm is specified to 70, and 't' of the given string 'test' is located on column 70, the string including the 't' can be searched.

9.4. Examples

The following example compares the OPENFRAME.ISRSUPC.OLD data set and the OPENFRAME.ISRSUPC.NEW data set. For the comparison, lower case letters are not distinguished from upper case letters. In each line, column 3 through 40 are compared, and it is also compared if column 75 is the same on each line.

//JOB01    JOB CLASS=A,MSGCLASS=X,MSGLEVEL=(1,1)
//DIFF     EXEC PGM=ISRSUPC,PARM='DELTA,LINECMP,ANYC'
//OLDDD    DD DSN=OFRAME.ISRSUPC.OLD,DISP=SHR
//NEWDD    DD DSN=OFRAME.ISRSUPC.NEW,DISP=SHR
//SYSOUT   DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//OUTDD    DD SYSOUT=A
//SYSIN    DD *
 CMPCOLM 3:40,75
/*

The next example searches for string 'test' within column 1 to 72 in the OPENFRAME.ISRSUPC.NEW data set. Small letters are not distinguished from capital letters.

//JOB02    JOB CLASS=A,MSGCLASS=X,MSGLEVEL=(1,1)
//SRCH     EXEC PGM=ISRSUPC,PARM='SRCHCMP,ANYC'
//NEWDD    DD DSN=OFRAME.ISRSUPC.NEW,DISP=SHR
//SYSOUT   DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//OUTDD    DD SYSOUT=A
//SYSIN    DD *
 SRCHFOR 'test',1:72
/*

9.5. Return Codes

The ISRSUPC utility program shows the following execution results:

  • Upon success:

    Code Description

    0

    Means that there is no differences between data sets, or that no string has been found.

    1

    Means that there are differences between data sets, or that the string has been found.

  • In the case of an error:

    The error message is printed to SYSPRINT DD or SYSOUT DD. To check relevant error messages when an error occurs, the DD should be set in JCL.

    The following error codes can be issued in the ISRSUPC utility program:

    Code Description

    8

    Error in processing the OLDDD data set.

    10

    SYSIN DD command syntax error.

    16

    Error in processing the NEWDD data set

    24

    Error in processing the OUTDD data set

    32

    Memory error. Insufficient memory.

10. PGMRTS00

It is an execution environment control utility program that is indirectly executed by JCL Runner, an OpenFrame/Batch engine module, when running a batch application compiled as Shared Object with JCL.

To be more specific, the shared object is specified in the PGM parameter of the JCL EXEC statement, which then triggers the JCL Runner to launch PGMRTS00. PGMRTS00 dynamically loads the shared objects to the memory, finds the entry point, and then executes the batch application.

The following figure depicts the work flow of the PGMRTS00 utility program.

figure 5 1
Workflow of PGMRTS00

  1. The JCL Runner checks the binary format of the batch application.

  2. If the binary format of the batch application is a shared object, the JCL Runner executes PGMRTS00 and dynamically runs the batch system.

  3. If the binary format of the batch application is not a shared object, the JCL Runner runs the batch application without PGMRTS00.

10.1. DD Statements

There is no DD configuration specific to the PGMRTS00 utility program. DD is configured only for the batch application.

10.2. Command Usage

There are no commands specific to the PGMRTS00 utility program.

10.3. Examples

PGMRTS00 is never executed directly from JCL. Therefore, there are no JCL examples.

10.4. Environment Configuration

The contents of the PGMRTS00 utility program of JCL Runner can be set in the tjclrun subject. To enable the batch application made of shared object to be executed directly in JCL, set the VALUE item of the USE_PGMRTS00 key in the PGM section and the tjclrun subject in the OpenFrame environment setting to YES.

  1. For more about tjclrun subject in environment configuration, refer to OpenFrame Configuration Guide.

  2. The similar utility programs are IKJEFT01 (TSO Terminal Monitoring Program) and DFSRRC00(HiDB Region Control Program).

10.5. Return Codes

The PGMRTS00 utility program shows the following batch execution results:

  • Upon success:

    It returns the return code from the batch program.

  • In the case of an error:

    Error messages are printed to SYSPRINT DD and corresponding return codes are returned.

    The following errors may occur in the PGMRTS00 utility program:

    Code Description

    12

    Unrecoverable error. The causes include:

    • Data set authentication preprocessing failure

    • Error in number of program parameters

    • Cannot find target application

    • Unsupported application binary format

    • Failure to load dynamic memory (dlopen)

    • Failure to search entry points (dlsym)

    16

    System fault. The causes include:

    • OpenFrame system library initialization failure

    • Error from application binary format check

    • Process fork failure

    • Input/Output redirect failure