How to...MSS has a number of utility programs. Many of these emulate the functions of commonly-used mainframe batch utilities. You can invoke these utilities in a JCL jobstream or REXX exec.
There are two types of utility program:
This chapter also describes how, if required, you can write your own utility program; see the section Writing Your Own Utility Programs for details.
This section describes the mainframe emulation utilities. You can invoke these utilities in a JCL jobstream or REXX exec by using the same program names, data sets and commands as on the mainframe. The mainframe utilities emulated by MSS are:
These names are defined as aliases for the equivalent MSS utility.
This section describes the special considerations that apply when you use these utilities in a MSS environment. It does not include information on behavior that is the same in mainframe and MSS environments. For full information on the mainframe utilities referred to in this section, see the relevant IBM documentation.
Note: If you wish to debug programs invoked by IKJEFT01, you must specify its equivalent MSS utility, IDAEFT01, as the program to debug.
MFJSORT emulates the DFSORT and SORT mainframe utilities. It provides the following sort/merge operations for sequential data sets:
This section describes the JCL statements used with the MFJSORT utility.
In the EXEC statement you need to specify the program named MFJSORT or its alias DFSORT or SORT. For example:
//STEPEXEC PGM=DFSORT,......
The following DD statements are required for all uses of MFJSORT:
The following DD statements are optional:
You can create a statistical report in the form of ASCII spool output by adding the following command to your JCL statement://MFJSTATS DD SYSOUT=*
If your sort is not running under mainframe emulation, you can create a statistical report by using the MFJSTATS environment variable. For more information, see Environment Variables Summary.
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.
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.
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:
| COBOL Statements | Value |
|---|---|
| RECORD-FLAGS PIC 9(8) COMP. | 0 indicates the first record passed. 4 indicates subsequent records passed. 8 indicates the last record passed. |
| ENTRY-BUFFER PIC X(n). | Contents of the input record. Do not change this area. |
| EXIT-BUFFER PIC X(n). | Contents of the new or altered record provided by the exit. |
| UNUSED-ENTRY PIC 9(8) COMP. | Not used |
| UNUSED-ENTRY PIC 9(8) COMP. | Not used |
| ENTRY-RECORD-LENGTH PIC 9(8) COMP. | Length of the input record. |
| EXIT-RECORD-LENGTH PIC 9(8) COMP. | Length of the new or altered record provided by the exit. |
| UNUSED-ENTRY PIC 9(8) COMP. | Not used |
| EXIT-AREA-LENGTH PIC 9(4) COMP. | Length of the exit area scratchpad. Do not change this field. |
| EXIT-AREA PIC X(n). | Exit area scratchpad used by the exit to maintain variables between calls to the exit program. |
MFJSORT recognizes the same return codes from exit programs as the mainframe utility, as listed in the following table:
| Return Code | Meaning |
|---|---|
| 0 | No action required. |
| 4 | Delete the current record. For E15, the record is not sorted. For E35, the record is not written to the output data set. |
| 8 | Do not call this exit again; exit processing is no longer required. |
| 12 | Insert the current record. For E15, the record is inserted for sorting. For E35, the record is written to the output data set. |
| 16 | Terminate MFJSORT. The job step is terminated with the condition code set to 16. |
| 20 | Alter the current record. For E15, the altered record is passed to the sort. For E35, the altered record is written to the output data set. |
MSS also provides limited emulation of SYNCSORT behavior. The behavior for SYNCSORT emulation is essentially the same as for DFSORT emulation, with the following exceptions:
To specify that you want to use SYNCSORT, set the environment variable MFJSENGINE=SYNCSORT in Configuration Information on the Server > Properties > General page for the enterprise server you are using
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).
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 or REXX exec.
For more information on VSAM access method services, see the IBM manual DFSMS/MVS Access Method Services for VSAM, SC26-4905.
Unlike the mainframe, a VSAM KSDS or ESDS data set is usually represented under Windows 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. The exception is where IDXFORMAT8 files are in use; these have just a .dat file.
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 in a non-mainframe environment is the same as on the mainframe. MFJAMS ignores those parts of a command that have no relevance in a non-mainframe environment. For example, because the VSAM file structure under Windows does not provide CI or CA sizes to manipulate, these command parameters are ignored.
This section describes the JCL statements used with the MFJAMS utility.
In the EXEC statement you need to specify the program name MFJAMS or its alias IDCAMS. For example:
//STEPEXEC PGM=IDCAMS,.......
The following DD statements are required for all uses of MFJAMS:
The following DD statements are used by some commands:
This section describes the MFJAMS commands.
The ALTER command changes the attributes of an MVS data set.
MFJAMS uses the parameters described in the following table. All other parameters are ignored.
| data-set-name | Name of the data set to be renamed. This parameter is required. |
| NEWNAME(data-set-name) | The new name for the data set. This parameter is required. |
You cannot use * as a qualifier to rename a number of data sets with one command. For example, ABC.*.FILE is not permitted.
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.
| NAME(data-set-name) | Name of the data set. This parameter is required. |
| KEYS(length offset) | Length and offset, relative to 0, of the alternate key field. The offset must be within the first 4,096 bytes of the record. Length plus offset must not exceed the maximum length of the record. The default is KEYS(64 0) |
| UNIQUEKEY | Each alternate key value in the records is unique |
| NONUNIQUEKEY | The alternate key values may contain duplicates |
| RELATE(data-set-name) | Name of a cataloged VSAM data set to which the alternate index is to be related |
The DEFINE CLUSTER command creates a new VSAM data set. It creates the data and index files on the local machine and catalogs the data set name.
MFJAMS uses the parameters described in the following table. All other parameters are ignored.
| NAME(data-set-name) | Name of the VSAM data set. This parameter is required |
| INDEXED | That a KSDS data set is being defined |
| NONINDEXED | That an ESDS data set is being defined |
| NUMBERED | That an RRDS data set is being defined |
| KEYS(length offset) | Length and offset, relative to 0, of the primary key field for a KSDS data set. The offset must be within the first 4096 bytes of the record. length plus offset must not exceed the maximum length of the record. The default is KEYS(64 0) |
| RECORDSIZE(average maximum) | Average and maximum lengths of the records, expressed in decimal format. If the lengths are the same, a fixed-length format is assumed. If the lengths are different, a variable-length format is assumed. The default is RECORDSIZE(4089 4089) |
| MODEL(data-set-name) | Name of a cataloged VSAM data set that has the same KEYS and RECORDSIZE parameters as this new data set. It is an alternative to specifying the parameters explicitly |
Here is a typical job to define a cluster:
//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))
Note the use of the continuation character (-) in the DEFINE CLUSTER statement.
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.
| NAME(data-set-name) | Name of the path data set. This parameter is required. |
The DELETE command deletes up to 99 data sets. It can be used for both VSAM and non-VSAM data sets. It deletes the local 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.
| data-set-names | Names of the data sets to be deleted. This parameter is required. You can specify a list of names separated by blanks and enclosed in parentheses. You can also specify generic names by using '*' as a qualifier. For example, a generic data set name of ABC.*.FILE means all data sets with ABC as the first qualifier, any value as the second qualifier, and FILE as the third and last qualifier |
| FORCE | All GDG data sets will be deleted in addition to the GDG catalog entry |
| NOFORCE | The GDG catalog entry will not be deleted if any GDG data sets exist |
FORCE and NOFORCE are mutually exclusive. NOFORCE is the default.
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.
| ENTRIES(data-set-names) | Names of the data sets to be listed. You can specify a list of names separated by blanks. You can also specify generic names by using '*' as a qualifier. For example, a generic data set name of ABC.*.FILE means all data sets with ABC as the first qualifier, any value as the second qualifier and FILE as the third and last qualifier |
| LEVEL(level) | Prefix qualifier of the data sets to be listed. For example, a level of ABC means all data sets with ABC as the first, high-level, qualifier |
ENTRIES and LEVEL are mutually exclusive; you can specify only one of them. LEVEL(*) is the default if neither is specified.
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.
| INFILE(ddname) | Name of the DD statement, contained in the JCL for this job step, that provides the name of the data set that is to be printed. |
| INDATASET(data-set-name) | Name of the data set that is to be printed. |
| OUTFILE(ddname) | Name of the DD statement for the printed output. The data set must have an LRECL value of at least 121. If you omit OUTFILE, the SYSPRINT DD statement is assumed. |
| FROMKEY(key) | For a VSAM KSDS data set only, the key of the first record to print. Printing starts at the record with the same primary key, or the record with the nearest higher key if an exact match does not occur. Alternate indices are not used. |
| TOKEY(key) | For a VSAM KSDS data set only, the key of the last record to print. Printing ends at the record with the same primary key, the record with the nearest higher key if an exact match does not occur, or end of file. Alternate indices are not used. |
| SKIP(number) | The number of records to skip before printing starts |
| COUNT(number) | The number of records to print |
| CHARACTER | Records are to be printed in character format. MFJAMS converts EBCDIC data sets to ANSI. Unprintable characters are printed as periods. |
| HEX | Records are to be printed in hexadecimal format. MFJAMS prints each byte in the record as a two-byte hexadecimal value |
| DUMP | Records are to be printed as a storage dump, in both hexadecimal and character format. MFJAMS converts EBCDIC data sets to ANSI. Unprintable characters are printed as periods. |
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:
MFJAMS uses the parameters described in the following table. All other parameters are ignored.
| INFILE(ddname) | Name of the DD statement, contained in the JCL for this job step, that provides the name of the data set that is to be used for input. |
| INDATASET(data-set-name) | Name of the data set that is to be used for input |
| OUTFILE(ddname) | Name of the DD statement, contained in the JCL for this job step, that provides the name of the data set that is to be used for output. |
| OUTDATASET(data-set-name) | Name of the data set that is to be used for output |
| FROMKEY(key) | For a VSAM KSDS only, the key of the first record to copy. Copying starts at the record with the same primary key, or the record with the nearest higher key if an exact match does not occur. Alternate indices are not used. |
| TOKEY(key) | For a VSAM KSDS only, the key of the last record to copy. Copying ends at the record with the same primary key, the record with the nearest higher key if an exact match does not occur, or end of file. Alternate indices are not used. |
| SKIP(number) | The number of records to skip before copying starts |
| COUNT(number) | The number of records to copy |
| REPLACE | For VSAM files only, the record in the input data set replaces any record in the output data set that has the same primary key |
| NOREPLACE | For VSAM files only, the record in the input data set does not replace any record in the output data set that has the same primary key |
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.
| MAXCC=number | Value that is to be set for the maximum condition code that was produced by all previous MFJAMS commands. |
| LASTCC=number | Value that is to be set for the last condition code that was produced by a MFJAMS command. |
In both cases, the highest valid value is 16. If you specify a higher value, MFJAMS sets the condition code to 16.
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.
| FILE(ddname) | Name of the DD statement, contained in the JCL for this job step, that provides the name of the data set that is to be verified. |
| DATASET(data-set-name) | Name of the data set |
FILE and DATASET are mutually exclusive. You must specify one of them.
To compare two sequential or partitioned data sets you can use the MFJMATCH utility. MFJMATCH works in two modes, depending on the EXEC statement you use to invoke it:
| EXEC Statement | Description |
|---|---|
| PGM=IEBCOMPR | MFJMATCH emulates the IEBCOMPR mainframe utility. |
| PGM=MFJMATCH | MFJMATCH performs a data set comparison but does not emulate the IEBCOMPR mainframe utility. |
This section describes how to use MFJMATCH to emulate the IEBCOMPR mainframe utility. For information on using the non-IEBCOMPR version of MFJMATCH, see the section Comparing Data Sets (MFJMATCH).
This section describes the JCL statements used with the MFJMATCH utility.
In the EXEC statement you need to specify MFJMATCH's alias, IEBCOMPR. For example:
//STEPEXEC PGM=IEBCOMPR, ...
Note: Specifying MFJMATCH instead of IEBCOMPR in the EXEC statement causes MFJMATCH to behave as described in the section Comparing Data Sets (MFJMATCH).
The following DD statements are required for all uses of MFJMATCH:
The following DD statement is optional:
The following control statements are parsed but not processed:
MFJCOPY emulates the operation of the IEBCOPY mainframe utility for copying and merging partitioned data sets.
This section describes the JCL statements used with the MFJCOPY utility.
In the EXEC statement you need to specify the program name MFJCOPY or its alias IEBCOPY. For example:
//STEPEXEC PGM=IEBCOPY, ...
The following DD statements are required for all uses of MFJCOPY:
The following DD statement is optional:
The following DD statements, which are used by the mainframe utility, are ignored by MFJCOPY:
The following control statements are parsed but not processed:
Additional differences between behavior on the mainframe and in MSS are as follows:
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.
This section describes the JCL statements used with the MFJGENER utility.
In the EXEC statement you need to specify the program name MFJGENER or its alias IEBGENER. For example:
//STEPEXEC PGM=IEBGENER,......
The following DD statements are required:
The following DD statement, which is used by the mainframe utility, is ignored by MFJGENER:
The following list describes how MFJGENER processes control statements differently than IEBGENER:
MFJUPDTE emulates the IEBUPDTE mainframe utility for creating or modifying sequential or partitioned data sets.
This section describes the JCL statements used with the MFJUPDTE utility.
In the EXEC statement, you need to specify the program name MFJUPDTE or its alias IEBUPDTE. For example:
//STEPEXEC PGM=IEBUPDTE, ...
The following DD statements are required:
The following control statements are parsed but not processed:
The following sub-operands for the function statement (ADD, CHANGE, REPL or REPRO) are parsed but not processed:
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 local machine, so that you can still test data set allocation and disposition for the job step.
This section describes the JCL statements used with the MFJBR14 utility.
In the EXEC statement you need to specify the program name MFJBR14 or its alias IEFBR14. For example:
//STEPEXEC PGM=IEFBR14,......
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.
Although the SYSTSIN data set can contain any of the TSO and DB2 commands supported by MSS, 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
| Parameter | Description |
|---|---|
| SYSTEM(system) | Specifies the name of the DB2 system. |
| PROGRAM(name) | Specifies the name of the program to be executed. IDAEFT01 can execute any application program that is compiled within your COBOL development system, provided you have set the necessary directives. |
| PARM(parm-string) | Specifies the parameter string that is to be passed to the program through the standard linkage area. |
If you are running a DB2 application, you need to define an XA Resource for the database manager. You can do this in either ES Admin or ESMAC:
This section describes the JCL statements used with the IDAEFT01 utility.
In the EXEC statement you need to specify the program name IDAEFT01 or its alias IKJEFT01. For example:
//STEPEXEC PGM=IKJEFT01,PARM='initial-command',.......
The following DD statement is required:
You must also include any DD statements for sequential and VSAM data sets that are accessed by the application program.
MFIRXJCL emulates the IRXJCL mainframe utility program. It starts an MVS session in batch mode and runs the REXX exec specified in the PARM parameter. For more information about the REXX support in MSS see the chapter REXX Support.
This section describes the JCL statements used with the MFIRXJCL utility.
In the EXEC statement you need to specify the program name MFIRXJCL, or its alias IRXJCL, and the name of the REXX exec as the first word in the PARM parameter. For example:
//STEPEXEC PGM=IRXJCL,PARM='REXXEXEC'
The following DD statements may be required:
You must also include any DD statements for data sets that are accessed by the exec.
MFJDG emulates the IEBDG mainframe utility for creating test data.
This section describes the JCL statements used with the MFJDG utility.
In the EXEC statement, you need to specify the program-name MFJDG or IEBDG. For example:
//STEPEXEC PGM=IEBDG, ...
Any PARM on the exec statement is ignored.
The following DD statements are required:
The following sub-operands are parsed but not processed:
This section describes the Micro Focus utility, MFJMATCH.
The MFJMATCH utility compares two MVS data sets. It accepts any record format, record length or data set organization supported by your COBOL development system. If the data sets match, it ends with a return code of 0. If the two data sets do not match, when the MFJMATCH utility finds the first mismatch it writes the two records that differ to a third data set (with asterisks under the columns that differ), then ends with a return code of 12. Records following the first mismatch are not compared.
Note:
You can also use the MFJMATCH utility to emulate the IEBCOMPR mainframe utility. For information on doing this, see the section Comparing Data Sets (MFJMATCH - IEBCOMPR).
If the data sets being compared are EBCDIC, the MFJMATCH utility also writes the hexadecimal representation.
This section describes the JCL statements used with the MFJMATCH utility.
In the EXEC statement you need to specify the program name MFJMATCH. For example:
//STEPEXEC PGM=MFJMATCH
The following DD statements are required:
The program control statements supported by MFJMATCH are listed below. The program control statements define search criteria that limit matching to a particular range of records and to portions of the record.
| Program Control Statements | Description | ||||
|---|---|---|---|---|---|
| KEY=(start,length) | Defines a key field for
use by FROMKEY and TOKEY program control statements. This statement can only
occur once. The parameters are:
For VSAM keyed files, the KEY defaults to the actual key, although, as the files are processed sequentially, any field can be defined as the key for the purpose of specifying a range for record matching. |
||||
| INCLUDE | Compare records only
in the ranges defined by FROMKEY TOKEY or FROMREC COUNT
SKIP and INCLUDE are mutually exclusive. |
||||
| SKIP | Ignore records in the
ranges defined by FROMKEY TOKEY or FROMREC COUNT.
SKIP and INCLUDE are mutually exclusive. |
||||
| FROMKEY='value1' TOKEY='value2' | Defines a range of records. value1 specifies the first record in the range, while value2 specifies the last record in the range. Hexadecimal values can be specified as x'hhhhhh', where hhhhhh is a hexadecimal number. | ||||
| FROMREC=x COUNT=y | Defines a range of record numbers, from record number x for the next y records | ||||
| FD=(start,length) | Defines a field to be ignored when comparing records -used with INCLUDE only |
In the following example:
//SYSIN DD * KEY=(1,10) INCLUDE FROMKEY='AAAAAAAAAA' TOKEY='BBBBBBBBBB' INCLUDE FROMKEY='WWWWWWWWWW' TOKEY='YYYYYYYYYY' FD=(11,5) FD=(21,5)
You might need to write your own utility programs or obtain them from other software vendors. MSS 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. MSS 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 your COBOL development system to ensure that all interactions with the system are handled correctly.
Copyright © 2008 Micro Focus (IP) Ltd. All rights reserved.