Chapter 17: JCL Support

This chapter describes the support for JCL provided within Mainframe Express.

Introduction

Mainframe Express enables you to build and test an MVS mainframe application on your PC up to the point where it is ready to be transferred to your mainframe system for final testing and production. You can also perform any subsequent maintenance of the application at a PC.

An important part of an MVS application is the JCL jobstream that controls its execution. Mainframe Express provides facilities to support the use of batch JCL jobstreams on the PC or UNIX workstation. Within the integrated development environment (IDE) of Mainframe Express you can:

Download jobstreams from the mainframe to the network server or PC
Create new jobstreams in Mainframe Express
Scan the jobstreams for syntax errors and dependencies
Submit the jobstreams for running on the PC and view the spool output files
Submit the jobstreams for running on the mainframe and view the spool output files

All mainframe operations require you to have installed and configured the relevant mainframe access products.

A major objective of the JCL support is to keep the operations on the PC as similar as possible to those done on the mainframe. Thus on your PC, you can:

Use mainframe data set names in the jobstream, even though the data is held in a file on the PC
Process jobstreams as if they were being run on the mainframe
View and process the SYSOUT listing and any other printed output produced by the jobstream
View the spool output files in the same way irrespective of whether the jobs were run on Mainframe Express or the mainframe
Use the functions of the many mainframe batch utilities

Much of the information in the chapter Running a TSO Session also applies to JCL support. We recommend that you read that chapter before using JCL. In addition, you need to understand more about the following topics:

JCL jobstreams
Data sets
Application programs

Each of these topics is discussed below.

JCL Jobstreams

You can run the same JCL jobstreams on the PC as you can on the mainframe. Mainframe Express checks the JCL statements for errors as far as possible. Several parameters, especially on DD statements, have no meaning in a PC environment and are ignored. This section describes the differences that apply when using JCL jobstreams in the Mainframe Express environment instead of the MVS mainframe environment.

Mainframe Express supports both MVS JCL and VSE JCL. The following sections describe the levels of support for MVS JCL and VSE JCL.

MVS JCL Support

The following sections outline the features and statements in MVS JCL that are supported by Mainframe Express.

MVS JCL Features

Mainframe Express supports the following MVS JCL features:

Instream procedures
Cataloged procedures
Symbolic parameters
EXEC statement overrides
DD statement overrides
Conditional execution (specified by IF, THEN, ELSE, and ENDIF statements)
Job restart after execution failure
Concatenated data sets
Instream data sets (preceded by a DD * or DD DATA statement)
Partitioned data sets
Generation data groups
Temporary data sets
Comments (indicated by //*)
Normal mainframe nesting limits (that is, 15 levels of nested procedures and 15 levels of nested INCLUDE statements)

Mainframe Express does not support the following MVS JCL features:

Multiple jobs in one jobstream
Program control statements (enclosed by CNTL and ENDCNTL statements)
JOBLIB and STEPLIB DD statements
All system DD statements used by IMS Option
Other special DD statements that are not relevant to the PC or that are implemented differently by Mainframe Express. These statements have the following DD names:
- JOBCAT
- STEPCAT
- SYSABEND
- SYSMDUMP
- SYSUDUMP
- SYSCHK
- SYSCKEOV

More information about the MVS JCL statements supported by Mainframe Express is given later in this section.

Mainframe Express supports the running of MVS JCL jobstreams either directly or via the TSO SUBMIT command and the Micro Focus extension ASUBMIT. You can run these TSO commands in a TSO session and with the IKJEFT01 utility.

Files containing MVS JCL jobstreams and cataloged procedures can be downloaded from the mainframe or created on the PC. Cataloged procedures should be stored as members of partitioned data sets, known as procedure libraries. The procedure libraries are defined to Mainframe Express in two different ways:

The libraries defined in the JCLLIB statement, for a single job
The libraries defined to Mainframe Express, for all jobs. These libraries can be defined using Add Dependency Folder on the Workgroup View. Right-click the Dependency Libraries folder to see this.

Mainframe Express searches these libraries in the order specified above.

The jobstream is processed at various stages:

When you click Done, after adding one or more MVS JCL files to a project, Mainframe Express scans the MVS JCL statements to resolve any dependencies on other files (such as cataloged procedures and statements included by INCLUDE statements).
During a Build operation Mainframe Express scans the MVS JCL statements to construct the jobstream, find any errors and extract the information that it requires to run the job. You can perform a Build operation:
- Explicitly, by selecting Scan or Rebuild All on the Build menu
- Implicitly, when you request debugging, if a Build has not already been performed on the current version of the file
During a Debug operation, if the Build was successful, Mainframe Express runs each job step, taking into account any conditional statements (IF, THEN, ELSE) or conditional parameters (COND) that apply.

In addition, when the job is submitted for running (that is, when you request debugging), the effect depends on the setting of the TYPRUN parameter to the JOB statement as shown below:

TYPRUN=SCAN	The syntax is scanned
TYPRUN=COPY	The job stream is copied to a SYSOUT data set
TYPRUN=HOLD	Holding of the job until explicitly released for execution
No TYPRUN	The job is executed immediately, assuming resources are available

MVS JCL Statements

For a full description of MVS JCL statements, please refer to your IBM OS/390 MVS JCL Reference manual.

Mainframe Express supports the following MVS JCL statements:

Statement	Description
DD	Defines the allocation and disposition of a data set
EXEC	Defines a job step, including the program or cataloged procedure to be run
IF THEN ELSE ENDIF	Specifies conditional execution of MVS JCL statements
INCLUDE	Specifies where pre-defined MVS JCL statements are to be included in the jobstream
JCLLIB	Specifies procedure libraries and their search order
JOB	Defines a job. Mainframe Express supports only one job per jobstream
JOBLIB	Specifies private libraries to be searched for programs identified in EXEC statements
PROC	Defines the start of an instream MVS JCL procedure
PEND	Defines the end of an instream MVS JCL procedure
SET	Defines the values to be assigned to symbolic parameters
STEPLIB	Specifies private libraries to be searched for programs identified in EXEC statements
OUTPUT	Specifies the processing options that the job entry subsystem is to use for printing a SYSOUT data set. Mainframe Express supports only the following parameters: BURST CHARS COPIES DEST FLASH FORMS UCS

Mainframe Express does not support the following MVS JCL statements. They are checked only for correct syntax.

Statement	Description
COMMAND	Issues commands to MVS and JES2
CNTL	Defines the start of a set of program control statements
ENDCNTL	Defines the end of a set of program control statements
XMIT	Transmits records from JES3

VSE JCL Support

The following sections outline the support for VSE JCL in Mainframe Express.

Restrictions

The following list describes some general restrictions that apply to Mainframe Express's support for VSE JCL. For information on the support for individual statements, see the sections VSE JCL and POWER Statements and POWER Statements.

There is no TAPE support.
There is no VSE development environment (such as ICCF, DITTO or LIBR).
JCL statements can only be executed as part of a submitted file; that is, you cannot enter VSE JCL statements dynamically at the operator console.
There is no support for VSE BACKGROUND / FOREGRAND / STATIC / DYNAMIC partitions.
All JCL commands except continuations must start with //.
COBOL executables are generated in the usual Micro Focus way. There is no support for Compile/Link or Compile/Go via JCL.
DD’s cannot persist across a Job Boundary, except for Standard labels.
Output listings, such as joblog, do not have a VSE look and feel.

VSE JCL and POWER Statements

The following table shows the level of support available for VSE JCL and POWER statements. For each statement, the "Support Level" column indicates whether that statement is fully processed or only parsed to check for correct syntax. Any VSE JCL and POWER statement not listed in this table is not supported.

Statement	Parameters	Support Level
// ASSGN	SYSxxx	Parse
	",Device"	Parse
	"[,TEMP\|PERM]]"	Parse
	"[,VOL-volser]"	Parse
// ASSGN	SYSxxx	Process
	",Device"	Process
	"[,TEMP\|PERM]]"	Process
// ASSGN	SYSxxx	Parse
	",Device"	Parse
	"[,mode\|ALT]"	Parse
	"[,TEMP\|PERM]]"	Parse
	"[,VOL-volser]"	Parse
// DATE	mm/dd/yy or dd/mm/yy depending on system settings	Parse
//DLBL	filename	Process
	",’fileid’"	Process
	"[,date]"	Parse
	"[,code]"	Parse
	"[,DSF]"	Parse
	"[,BLKSIZE=n]"	Process
	"[,CISIZE=n]"	Parse
//DLBL	filename	Process
	",’fileid’"	Process
	"[,exp-date]"	Parse
	"[,VSAM]"	Process
	"[,DSF]"	Parse
	"[,BUFSP=n]"	Parse
	"[,BUFND=n]"	Parse
	[BUFNI=n]	Parse
	"[,CAT=catname]"	Parse
	"[,DISP=(disp,disp,disp)]"	Process
	"[,RECORDS=primary,secondary]"	Parse
	"[,CISIZE=n]"	Parse
// EXEC	PROC=procname	Process
	"[,parms]"	Process
// EXEC	[PGM=]progname	Process
	"[,REAL]"	Parse
	"[,SIZE=size]"	Parse
	"[,GO]"	Parse
	"[,PARM=’value’]"	Process
// EXTENT	[logical-unit]	Parse
	",[volser]"	Parse
	",[type]"	Parse
	",[seqnumber]"	Parse
	",[location]"	Parse
	",[quantity]"	Parse
	",[split-cylinder-track]"	Parse
// GOTO	[label \| $EOJ]	Process
// IF	{ $RC \| $MRC \| parameter-name }	Process (except for parameter-name, which is parsed only)
	operator	Process
	value	Process
	[OR\|AND]	Process
	{ $RC \| $MRC \| parameter-name }	Process
	operator	Process
	value	Process
	THEN	Process
// JOB	jobname	Process
	[accounting info]	Process
// LIBDEF	type	Process
	"[,SEARCH=(lib1,slib1,…lib15,slib15)]"	Process
	"[,CATALOG=lib.slib]"	Process
	"[,TEMP\|PERM]"	Parse
// LIBDEF	type	Parse
	"[,SEARCH=(lib1,slib1,…lib15,slib15)]"	Parse
	"[,CATALOG=lib.slib]"	Parse
	"[,TEMP\|PERM]"	Parse
// LIBDROP	type	Process
	"[,definition-type]"	Process
	"[,TEMP\|PERM]"	Parse
// LIBDROP	type	Parse
	"[,definition-type]"	Parse
	"[,TEMP\|PERM]"	Parse
// LIBLIST	type	Process
	"[,partition]"	Parse
	"[,SYSxxxx]"	Parse
// LISTIO	type	Process
	"[,partition]"	Parse
	"[,outdev]"	Parse
// LIBSERV	Send requests to tape library server	Parse
// LOG and // NOLOG		Parse
// MTC	operation	Parse
	"[,device]"	Parse
// ON	{$RC operator n \| $CANCEL \|$ABEND }	Process
	[{OR\|AND} condition]	Process
	{$RC operator n \| $CANCEL \|$ABEND }	Process
	[GOTO label \| CONTINUE]	Process
// OPTION	parm	Parse
	"[,parm2,…….]"	Parse
// PAUSE	Comment data	Parse
// PROC	[parm=value]	Process
// PWR	PRELEASE [operands] !]	Process
	PHOLD[operands	Parse
// RESET	type	Process
// SETPARM	Parm=value	Process
	"[,parm=value,………]"	Process
// SETPFIX		Parse
// STDOPT	"Option[,option2…]"	Parse
// TLBL	filename	Process
	",’fileid’"	Process
	"[,date]"	Parse
	"[,volser]"	Parse
	"[,volseq]"	Parse
	"[,fileseq]"	Parse
	"[,generation]"	Parse
	"[,version]"	Parse
// UPSI	nnnnnnnn	Process
// ZONE	EAST/hh/mm or WEST/hh/mm	Parse
/. label		Process
/*		Process
./		Process
*		Process
/+		Process

POWER Statements

The following table shows the level of support available for POWER statements. For each statement, the "Support Level" column indicates whether that statement is fully processed or only parsed to check for correct syntax. Any POWER statement not listed in this table is not supported.

Statement	Parameters	Support Level
* $$ JOB	JNM=jobname	Process
	[,DISP=disp]	Parse
	[,PRI-pri]	Parse
	[,CLASS=class]	Parse
	[,NTFY=ntfy-option]	Parse
	[,USER='user info'}	Parse
	FROM=user_id	Parse
	LOG=x	Parse
	BRTNC=xxx	Parse
	DUETIME=options	Parse
	[,BLDG=x]	Parse
	[,DEPT=x]	Parse
	[,ROOM=x]	Parse
	[,EOJMSG=YES]	Parse
	[,PWD=x]	Parse
	[,PROGR=x]	Parse
	SYSID=(node_id,user_id)	Parse
	NETACCT=account_no	Parse
	XDEST=(node_id,user_id)	Parse
	LDEST=(node_id,user_id)	Parse
	PDEST=(node_id,user_id)	Parse
	SEC=(user_id,password)	Parse
* $$ LST	[,DISP=disp]	Parse
	[,PRI-pri]	Parse
	[,CLASS=class]	Parse
	[,UNIT=addr]	Parse
	[,LST=SYSxxx]	Parse
	[,FNO=xxx]	Parse
	[,FCB=xxxxxx]	Parse
	[,JSSEP=x]	Parse
	[,RBS=nnnn]	Parse
	RBM=(norbm1,norbm2)	Parse
	RBC=norbc	Parse
	BRTNC=xxx	Parse
	PURGE=nnn	Parse
	DEST=(node_id,user_id,subsystem)	Parse
	PRMODE=value	Parse
	REMOTE=remote_id	Parse
	CMPACT=name	Parse
	SYSID=n	Parse
	DIST=distcode	Parse
	TADDR=(tapeaddr,mode)	Parse
	USER=user_info	Parse
	PWD=password	Parse
	BURST=x	Parse
	CHARS=tablename	Parse
	COPYG=(groupvalue)	Parse
	DLFT=x	Parse
	FLASH=(overlayname,count)	Parse
	MODIFY=(copymodname,tablename)	Parse
	[,PAGEDEF=xxx]	Parse
	[,FORMDEF=xxxx]	Parse
* $$ PUN		Process
	JNM=jobname	Process
	CLASS=class	Process
	DISP=disposition \| D \| T	Process
	PRI=priority	Process
	PUN=punchaddr	Process
	COPY=n	Process
	FNO=formno	Process
	RBS=norbs	Process
	RBM=(norbm1,norbm2)	Process
	RBC=norbc	Process
	JSEP=(n,option)	Process
	BRTNC=YES \| NO	Process
	PURGE=NO \| nnnn	Process
	DEST=(node_id,user_id,subsystem)	Process
	PRMODE==x	Process
	SYSID=n	Process
	DIST=distcode	Process
	USER=userinfo	Process
	PWD=password	Process
* $$ SLI
	MEM-membername	Parse
	,[.type]	Parse
	,S=lib1.sublib,lib2.sublib2]	Parse
	Sublib.	Parse
	bookname	Parse
* $$ SLI
	ICCF=membername,	Process
	LIB=(libnumber,password)	Process
* $$ DATA	name	Parse
* $$ CTL	CLASS=class	Parse
* $$ EOJ		Process

VSE JCL Configuration Files

At system start-up, VSE can set a number of values that are available to any job run on the system until shut down. Mainframe Express emulates this behavior with the use of a configuraiton file. You can use the configuration file to specify information about the following:

Devices. These can be designated as Printers, Punches, Tapes, Readers or Disks.
Logical Units. SYSxxx (where xxx is a 3 digit number) or one of the standard logical devices SYSIPT, SYSLST etc.
Standard labels. Commonly-used file names and the associated data sets can be set so that no DLBL statement for this filename/data set name is necessary in the JCL decks; the file is automatically allocated.

Mainframe Express reads the configuration file at the start of each job, so if you run a job then modify the configuration file, running the job again will pick up the modified configuration file.

Structure of a VSE JCL Configuration File

A VSE JCL configuration file is a text file that contains a number of name-value pair entries, with each entry on a separate line. Blank lines or lines beginning with an asterisk (*) are treated as comment lines.

The format of the name-value pair entries are shown below.

For devices:

device_id      id
device_type    type

where:

id	is a three-digit code specifying the device address
type	is one of PRINTER, READER, PUNCH, DISK or TAPE.

For logical units:

assgn_lu        lu
assgn_device    device

where:

lu	is the logical unit to use.
device	is the device to assign to the logical unit lu.

For standard labels:

dlbl_dd         dd
dlbl_dsn        dsn

where:

dd	is the label to use.
dsn	is the data set name to assign to the label dd.

Note: There is an addtional name-value pair entry for defining partitions, but specifying it has no effect.

Specifying the Location of the VSE JCL Configuration File

To make a VSE JCL configuration file available to Mainframe Express you specify its location using the VSE_STARTUP_CFG environment variable. For example, if you create the configuration file in c:\setup\vseconfg.cfg, you would set VSE_STARTUP_CFG as follows:

SET VSE_STARTUP_CFG=c:\setup\vseconfg.cfg

Example VSE JCL Configuration File

* ==================================================================
* =     VSE SYSTEM START-UP                                        =
* ==================================================================
partition        BG
* ==================================================================
* =     devices                                                    =
* ==================================================================
device_id        02A
device_type      PRINTER 
* 
device_id        02B
device_type      PRINTER 
* 
device_id        02C
device_type      PRINTER 
* 
device_id        02D
device_type      PRINTER 
*
device_id        02E
device_type      PUNCH
*
device_id        02F
device_type      READER 
* 
device_id        42E
device_type      PRINTER 
* 
device_id        43E
device_type      PRINTER 
* 
device_id        44E
device_type      PRINTER 
* 
device_id        45E
device_type      PRINTER 
* 
device_id        46E
device_type      PRINTER 
* 
device_id        020
device_type      DISK 
* ==================================================================
* =     permanent assignments                                      =
* ==================================================================
*
assgn_lu         SYSIPT
assgn_device     02F
*
assgn_lu         SYSLST
assgn_device     02A
*
assgn_lu         SYS001 
assgn_device     02B    
*
assgn_lu         SYS002
assgn_lu_2       SYS001
*
assgn_lu         SYS002
assgn_lu_2       SYSLST
* ==================================================================
* =     standard labels                                            =
* ==================================================================
dlbl_dd          CMAST 
dlbl_dsn         CUSTOMER.MASTER.FILE

Special Characters in JCL Program-names

Mainframe Express validates JCL program-names using IBM's list of valid characters. Valid characters in this list are @ # and $, although in some codepages the conversion of these characters causes incompatibilities with the name validation. If you experience problems using any of these special characters in the name of a JCL program, you should report these to Micro Focus.

Running a Job on the Mainframe

You can submit to the mainframe jobs that you have created on the PC. Any JCL procedures used by the job must reside in a procedure library on the mainframe and you should include a suitable //PROC statement in the jobstream, such as:

//PROC JCLLIB ORDER=procedure-library

Any application programs used by the job must reside in a load library on the mainframe and you should include a suitable //JOBLIB statement in the jobstream, such as:

//JOBLIB DD DSN=load-library,DISP=SHR

If you have configured Mainframe Access so that Mainframe Express has access to more than one mainframe node, you can include //JOBLIB statements that refer to any of the defined nodes. For information on configuring Mainframe Access in this way, see the chapter Accessing Mainframe Files in your Administrator's Guide.

Data Sets

Mainframe Express supports most mainframe data set organizations and record formats, as described in the chapter Advanced Data Set Information in your IDE Technical Guide.

Mainframe Express also supports temporary data sets and in-stream data sets included in the jobstream.

Application Programs

Mainframe Express emulates the interface between application programs and MVS in order to allocate data sets and pass parameters. These facilities are described below for COBOL programs. Similar rules apply to Assembler programs.

Allocating Data Sets

MVS provides a direct connection between the filename used in the program and the corresponding data set name used in the JCL. For example, for SYSUT1 in a COBOL program:

SELECT INFILE ASSIGN TO UT-S-SYSUT1

connects to

//SYSUT1 DD DSN=DSNAME1,DISP=OLD

and allocates to the program the PC file representing the data set named DSNAME1.

And, for SYSUT2:

SELECT OUTFILE ASSIGN TO UT-S-SYSUT2

connects to

//SYSUT2 DD DSN=DSNAME2,DISP=(NEW,CATLG),...

and allocates to the program a PC file representing the data set named DSNAME2. The file is created and cataloged automatically when the jobstream is run.

Passing Parameters

Parameters specified in the JCL PARM parameter are passed to the program using the same rules as the mainframe. Options specified in the parameters string are separated from any application parameters by a slash (/) character. For example:

PARMS(application-parameters/run-time-options)

For information on the linkage area that is used when passing parameters, see the section Passing Parameters in the chapter Running a TSO Session.

Enabling JOBLIB DD and STEPLIB DD Processing

These statements specify directories that will be searched for the programs named in EXEC statements.

To enable JOBLIB/STEPLIB processing do the following:

Create a dynamic PDS that represents each of the PC subdirectories where your .gnt and .int files will reside. We recommend that you segregate .gnt and .int files into different subdirectories.
Execute your JCL using JOBLIB and/or STEPLIB statements that reference the subdirectories you created in STEP1. The search order will be STEPLIB, JOBLIB, then the paths specified by Mainframe Express's workgrouping settings.

If the partitioned data set referenced in a particular STEPLIB or JOBLIB statement exists as a catalog entry, the DD is allocated. Where there are multiple partitioned data sets referenced in a STEPLIB or JOBLIB concatenation, only those data sets that exist are mapped as part of the JOBLIB or STEPLIB concatenation.

Any job that has a STEPLIB and/or JOBLIB statement continues to run unmodified.