System Intelligence

Advanced Data Set Information

Chapter 3: Mainframe Utilities

Mainframe Express has a number of utility programs which emulate the functions of many commonly-used mainframe batch utilities. You can invoke these utilities in a JCL jobstream, TSO CLIST or REXX exec by using the same program names, data sets and commands as on the mainframe. The mainframe utilities that are emulated by Mainframe Express are:

• IDCAMS, to manage VSAM data sets

• DFSORT and SORT, to perform sort/merge operations

• IEBGENER, to copy sequential data sets

• IEFBR14, to replace a program that does not exist on the PC with a dummy program

• DFSRRC00, to dispatch applications that use IMS

• IKJEFT01, to submit TSO commands in batch mode

• IRXJCL, to run a REXX exec in MVS batch mode

These names are defined as aliases for the equivalent Mainframe Express utility. You can see the list of programs and aliases by selecting the Aliases page of the Project Settings dialog box from the Project menu. This chapter describes the special considerations that apply when you use these utilities in a Mainframe Express environment. For more information, please refer to the mainframe documentation for the utility.

3.1 VSAM Access Method Services (MFJAMS)

MFJAMS emulates the main functions of the IDCAMS mainframe utility. It provides the following management services for VSAM key-sequenced data sets (KSDS), entry-sequenced data sets (ESDS) and relative-record data sets (RRDS).

• DEFINE ALTERNATEINDEX, to define alternate indices for a VSAM data set

• DEFINE CLUSTER, to define a new VSAM data set

• DEFINE PATH, to support path data sets

• DELETE, to delete data sets

• LISTCAT, to list catalog entries

• PRINT, to print a data set

• REPRO, to copy a data set

• SET, to change the condition code

• VERIFY, to verify a VSAM data set

You can use some of these services for sequential data sets, partitioned data sets and generation data groups. All abbreviations of these commands and their parameters that are valid on the mainframe are supported by MFJAMS.

You can execute MFJAMS via a JCL jobstream, TSO CLIST or REXX exec. You can also use it interactively via the Mainframe Express IDE Tools menu.

For more information on VSAM access method services, see the IBM manual DFSMS/MVS Access Method Services for VSAM, SC26-4905.

3.1.1 File Structure

Unlike the mainframe, a VSAM KSDS or ESDS data set is represented on the PC by two files - a data file, which contains the actual data records for the VSAM data set, and an index file, which contains the primary and alternate key data. These files usually have filename extensions of .dat and .idx respectively.

Although the two-file structure affects the way that IDCAMS commands are processed, it does not change the final outcome of the commands. The results of executing commands on the PC is the same as the mainframe. MFJAMS ignores those parts of a command that have no relevance on a PC. For example, because the VSAM file structure on a PC does not provide CI or CA sizes to manipulate, these command parameters are ignored.

3.1.2 JCL Statements

This section describes the JCL statements used with the MFJAMS utility.

3.1.2.1 EXEC Statement

In the EXEC statement you need to specify the program name MFJAMS or its alias IDCAMS. For example:

//STEPEXEC PGM=IDCAMS,.......

3.1.2.2 DD Statements

The following DD statements are required for all uses of MFJAMS:

• SYSIN, for the data set that contains the input commands. It can be an in-stream data set.

• SYSPRINT, for the output listing data set. It must have an LRECL value of at least 121.

The following DD statements are used by some commands:

• For the data sets that are used for input to the PRINT, REPRO and VERIFY commands. The DD statement can have any valid dd-name, such as INFILE.

• For the data sets that are used for output from the PRINT and REPRO commands. The DD statement can have any valid dd-name, such as OUTFILE.

3.1.3 Commands

This section describes the MFJAMS commands.

3.1.3.1 DEFINE ALTERNATEINDEX

The DEFINE ALTERNATEINDEX command creates an alternate index for an existing VSAM data set. It also automatically reindexes the data set to maintain consistency between the data and index files on the PC. The alternate index is contained within the same file as the primary index.

MFJAMS uses the parameters described in the following table. All other parameters are ignored.

Notes:

• UNIQUEKEY and NONUNIQUEKEY are mutually exclusive. NONUNIQUEKEY is the default.

• Because MFJAMS automatically reindexes the data set, the BLDINDEX parameter is assumed even if it is not specified.

• You can create up to seven alternate indices in one invocation of MFJAMS. Enter separate commands for each index. MFJAMS performs a single reindexing operation for all the alternate indices.

• MFJAMS does not support the Micro Focus split-key and key-compression features. Mainframe Express cannot open a VSAM data set that uses either of these features.

3.1.3.2 DEFINE CLUSTER

The DEFINE CLUSTER command creates a new VSAM data set. It creates the data and index files on the PC and catalogs the data set name.

MFJAMS uses the parameters described in the following table. All other parameters are ignored.

Notes:

• INDEXED, NONINDEXED and NUMBERED are mutually exclusive. INDEXED is the default.

• MFJAMS does not allow duplicate entries of the primary key.

• KEYS and RECORDSIZE override the values obtained from MODEL.

• MFJAMS does not support the Micro Focus split-key and key-compression features. Mainframe Express cannot open a VSAM data set that uses either of these features.

//DEFCLUS  JOB  CLASS=A
//IDCSTEP  EXEC PGM=IDCAMS
//SYSPRINT DD   SYSOUT=*
//SYSIN    DD   *
DEFINE CLUSTER(NAME(TEST.KSDS.DUMMY) KEYS(5,0) -
       RECORDSIZE(80,80))

3.1.3.3 DEFINE PATH

The DEFINE PATH command causes MFJAMS to create a dummy path data set so that any DD statement that refers to the data set will not fail. The data set is not needed for any other purpose because MFJAMS implements this function in a different way to the mainframe.

MFJAMS uses the parameters described in the following table. All other parameters are ignored.

3.1.3.4 DELETE

The DELETE command deletes up to 99 data sets. It can be used for both VSAM and non-VSAM data sets. It deletes the PC files associated with the data set and removes the entry from the catalog.

MFJAMS uses the parameters described in the following table. All other parameters are ignored.

Note:

• FORCE and NOFORCE are mutually exclusive. NOFORCE is the default.

3.1.3.5 LISTCAT

The LISTCAT command lists the data set names contained in the catalog.

MFJAMS uses the parameters described in the following table. All other parameters are ignored.

Note:

• ENTRIES and LEVEL are mutually exclusive; you can specify only one of them. LEVEL(*) is the default if neither is specified.

3.1.3.6 PRINT

The PRINT command prints the contents of both VSAM and non-VSAM data sets. It prints a complete data set or part of a data set in character format, hexadecimal format or both formats.

MFJAMS uses the parameters described in the following table. All other parameters are ignored.

Notes:

• INFILE and INDATASET are mutually exclusive. You must specify one of them.

• FROMKEY and SKIP are mutually exclusive. If you specify neither, printing starts at the first physical record.

• TOKEY and COUNT are mutually exclusive. If you specify neither, printing ends at end of file.

• CHARACTER, HEX and DUMP are mutually exclusive. DUMP is the default.

• MFJAMS converts key values to EBCDIC if necessary.

• MFJAMS pads partial keys with spaces.

3.1.3.7 REPRO

The REPRO command copies the contents of one data set to another. The data sets can have either VSAM or sequential organization. Thus the REPRO command can:

• Load a sequential data set to a VSAM data set.

• Load a VSAM data set to a VSAM data set, optionally replacing records that have the same primary key values as the input records.

• Copy a VSAM data set to a sequential data set.

• Copy a sequential data set to a sequential data set.

MFJAMS uses the parameters described in the following table. All other parameters are ignored.

Notes:

• INFILE and INDATASET are mutually exclusive. You must specify one of them.

• OUTFILE and OUTDATASET are mutually exclusive. You must specify one of them.

• REPLACE and NOREPLACE are mutually exclusive. NOREPLACE is the default.

• MFJAMS automatically adds alternate key entries to the output data set if they have been previously defined.

3.1.3.8 SET

The SET command alters a condition code set by previous MFJAMS commands in this job step. MFJAMS uses only the MAXCC and LASTCC parameters, as described below. All other parameters are ignored.

Note: In both cases, the highest valid value is 16. If you specify a higher value, MFJAMS sets the condition code to 16.

3.1.3.9 VERIFY

The VERIFY command attempts to open a VSAM data set in order to verify that it can be read and that the index is usable. The data set is assumed to be readable if it can be opened without error or if it is locked to another process.

If the index is found to be unusable, the VERIFY command rebuilds the index by creating a new index file for the primary key and all alternate keys. The data portion of the data set is not changed.

MFJAMS uses the parameters described in the following table. All other parameters are ignored.

Note:

• FILE and DATASET are mutually exclusive. You must specify one of them.

3.2 Sort/Merge Operations (MFJSORT)

MFJSORT emulates the DFSORT and SORT mainframe utilities. It provides the following sort/merge operations for sequential data sets:

• Sorting data sets by ascending or descending keys

• Merging data sets by ascending or descending keys

• Copying data sets

• Selecting the records to be processed

• Rearranging the fields in the records

• Correctly processing two-digit year fields

• Transforming two-digit year fields to four-digit fields

• Summing numeric fields in records with duplicate keys

• Creating multiple output data sets

• Using an alternate collating sequence

• Executing E15 and E35 exit programs.

3.2.1 JCL Statements

This section describes the JCL statements used with the MFJSORT utility.

3.2.1.1 EXEC Statement

In the EXEC statement you need to specify the program named MFJSORT or its alias DFSORT or SORT. For example:

//STEPEXEC PGM=DFSORT,......

3.2.1.2 DD Statements

The following DD statements are required for all uses of MFJSORT:

• SYSIN, for the data set that contains the program control statements. It can be an in-stream data set

• SYSPRINT, for the output listing data set. It must have an LRECL value of at least 132

• SORTIN, for the input data sets. You can concatenate up to 16 data sets for SORTIN

• SORTOUT, for the output data set. It is not required if you use SORTOFnn.

The following DD statements are optional:

• SORTINnn, for multiple input data sets. nn begins with 01 and increases by 1 up to a maximum of 16. SORTINnn and SORTIN are mutually exclusive.

• SORTOFnn, for multiple output data sets. nn begins with 01 and increases by 1 up to a maximum of 16. SORTOFnn is used by the OUTFIL statement.

3.2.2 Program Control Statements

The program control statements supported by MFJSORT are listed below, together with any restrictions. The rules for coding the statements are identical to the mainframe utility.

3.2.3 Exits

MFJSORT, like its mainframe counterpart, invokes user exit programs for the E15 read exit and the E35 write exit. The exit programs should be written in COBOL and compiled by the Micro Focus syntax checker. They can be executed normally or debugged like any other COBOL program. Please refer to the mainframe documentation for instructions on writing and testing exit programs.

3.2.3.1 Linkage Areas

MFJSORT provides a standard linkage area to the E15 and E35 exit program. It is compatible with the mainframe utility and should be defined as follows:

3.2.3.2 Return Codes

MFJSORT recognizes the same return codes from exit programs as the mainframe utility, as listed in the following table:

3.3 Copy Sequential Data Sets (MFJGENER)

MFJGENER emulates the basic copy operations of the IEBGENER mainframe utility for sequential data sets (that is, PS or PSU data sets, or members of PO or POU data sets.) It ignores commands specified in the SYSIN data set.

3.3.1 JCL Statements

This section describes the JCL statements used with the MFJGENER utility.

3.3.1.1 EXEC Statement

In the EXEC statement you need to specify the program name MFJGENER or its alias IEBGENER. For example:

//STEPEXEC PGM=IEBGENER,......

3.3.1.2 DD Statements

The following DD statements are required:

• SYSUT1, for the input data sets. You can concatenate up to 16 data sets for SYSUT1.

• SYSUT2, for the output data set.

The following DD statements, which are used by the mainframe utility, are ignored by MFJGENER:

• SYSPRINT, for the output listing data set.

• SYSIN, for the command input data set.

3.4 Dummy Program (MFJBR14)

MFJBR14 emulates the IEFBR14 mainframe utility. It provides a dummy program facility by simply returning to the caller. It can be used, for example, in a job step to delete data sets at the appropriate time. You can also use it to replace a program that does not have a version on the PC, so that you can still test data set allocation and disposition for the job step.

3.4.1 JCL Statements

This section describes the JCL statements used with the MFJBR14 utility.

3.4.1.1 EXEC Statement

In the EXEC statement you need to specify the program name MFJBR14 or its alias IEFBR14. For example:

//STEPEXEC PGM=IEFBR14,......

3.5 IMS Dispatcher (MFJIMS)

MFJIMS emulates some of the functions of the DFSRRC00 mainframe utility. It invokes the IMS Option batch run-time facility for a specific PSB name in order to dispatch a COBOL application that uses IMS.

MFJIMS does not allocate IMS databases; you should use the IMS Option of Mainframe Express to do this.

3.5.1 JCL Statements

This section describes the JCL statements used with the MFJIMS utility.

3.5.1.1 EXEC Statement

In the EXEC statement you need to specify the program name MFJIMS or an alias. DFSRRC00 is defined as a generic alias. You could also define the commonly-used aliases DLIBATCH, DBBBATCH, IMSBATCH and IMSFP for different forms of IMS executions.

You also need to specify in the PARM field several parameters that are passed to IMS Option when it is invoked. For example:

//STEPEXEC PGM=DFSRRC00,PARM=(parameter-list),...

The PARM parameters required by IMS Option are listed below. Any other parameters which are used by the mainframe utility are ignored.

Examples of valid parameter lists are:

//STEPEXEC PGM=DLIBATCH,PARM=(DLI,PROGNAME,PSBNAME,p4,p5,p6,p7,CHKPTID)

//STEPEXEC PGM=DBBBATCH,PARM=(DBB,PROGNAME,PSBNAME,p4,p5,p6,p7,CHKPTID)

//STEPEXEC PGM=IMSBATCH,PARM=(BMP,PROGNAME,PSBNAME,p4,p5,p6,p7,p8,CHKPTID)

//STEPEXEC PGM=IMSFP,PARM=(IFP,PROGNAME,PSBNAME,p4,p5,p6,p7,p8,CHKPTID)

3.5.1.2 DD Statements

DD statements for system data sets (DFSRESLB, DFSVSAMP, IMS, etc.) and IMS databases, which are normally required in a mainframe environment, are checked for validity. They are not required by IMS Option.

You must still include DD statements for non-IMS data sets and any GSAM databases that are accessed by the processing program.

3.5.2 SQL ATTACH

MFJIMS supports the execution of programs that contain SQL statements, using mechanisms similar to those used on the mainframe. To use this function, specify in the PARM parameters:

• DLI as the program type.

• DSNMTV01 as the program name.

• The actual PSB name.

For example:

//IMSSQL EXEC PGM=DLIBATCH,PARM=(DLI,DSNMTV01,psb-name)

Then include a DD statement, with dd-name DDITV02, that defines a data set containing the parameter list for DSNMTV01. Specify the actual processing program name as the ninth parameter in this list. For example:

//DDITV02 DD *
p1,p2,p3,p4,p5,p6,p7,p8,program-name

3.6 Executing TSO Commands in Batch Mode (IDAEFT01)

IDAEFT01 emulates the IKJEFT01 mainframe utility program. It starts a TSO session in batch, and the TSO session executes the TSO commands contained in the data set defined by the SYSTSIN DD statement. These commands are listed in the chapter TSO Support.

Although the SYSTSIN data set can contain any of the TSO and DB2 commands supported by Mainframe Express, IDAEFT01 is typically used to run DB2/TSO applications in batch mode. Input for such applications is, at a minimum:

DSN SYSTEM(system)
 RUN PROGRAM(name) PARM(parm-string)
 ....
END

3.6.1 JCL Statements

This section describes the JCL statements used with the IDAEFT01 utility.

3.6.1.1 EXEC Statement

In the EXEC statement you need to specify the program name IDAEFT01 or its alias IKJEFT01. For example:

//STEPEXEC PGM=IKJEFT01,PARM='initial-command',.......

3.6.1.2 DD Statements

The following DD statement is required:

• SYSTSIN, for the input data set that contains the TSO commands. It can be an instream data set.

You must also include any DD statements for sequential and VSAM data sets that are accessed by the application program.

//STEPEXEC PGM=IRXJCL,PARM='REXXEXEC'

3.8 Writing Your Own Utility Programs

You might need to write your own utility programs or obtain them from other software vendors. Mainframe Express passes a standard MVS parameter area to these programs when they are invoked by TSO commands or JCL statements.

For a COBOL program, the parameter area has the following definition:

   01 PARM.
      03 PARM-LENGTH         PIC 9(4)COMP.
      03 PARM-DATA.
         05 PARM-DATA-ARRAY  PIC X OCCURS 100.

PARM-DATA contains the data specified in the parameter field of the TSO command or JCL statement. Mainframe Express converts it to the default data representation defined for your system - ANSI or EBCDIC. The utility program should inspect the parameter data, determine its data representation and convert it, if necessary, to the representation used by the program.

Note: The utility program must be compiled within Mainframe Express to ensure that all interactions with the system are handled correctly.

System Intelligence

Advanced Data Set Information