Z/OS JCL in the Batch Runtime Environment

This chapter contains the following topics:

•	Introduction to z/OS JCL in the Batch Runtime Environment

•	z/OS JCL Cards in the Batch Runtime Environment

•	Sort Utilities

•	DB2 Utilities

•	COBOL Runtime

Introduction to z/OS JCL in the Batch Runtime Environment

This section describes how to find equivalents for z/OS JCL statements in the target environment. Some of these equivalents point to the Batch Runtime functions, other equivalents may rely directly on UNIX or Tuxedo features. In some cases, there may be no equivalent and a work-around solution may be necessary.

It is not the purpose of this document to describe z/OS JCL, for any explanation of JCL statements, please see the z/OS Internet Library.

z/OS JCL Cards in the Batch Runtime Environment

The following tables lists the JCL card parameters and the related command in the Batch Runtime:

In the column “status”, the following abbreviations are used:

N.R. means “not relevant”

N.S. means “not supported”

JCL Card Equivalence Table

 

Table 2‑1 JCL Card Equivalences

JCL Card	Parameter	Equivalent in Target Environment	Status
//*		Comments	supported
/*		In-stream data delimiter	supported
//		End of job	supported
COMMAND			N.S.
CNTL/ENDCNTL			N.R.
DD	*	m_FileAssign -i	supported
	ACCODE		N.R.
	AMP		N.R.
	AVGREC		N.R.
	BLKSIZE		N.R.
	BLKSZLIM		N.R.
	CCSID		N.R.
	CHKPT		N.S.
	CNTL		N.R.
	DATA	m_FileAssign	supported
	DATACLAS	see DATACLAS Parameter of DD Statement	supported
	DCB	see DCB Parameter of DD Statement	supported
	DISP	m_FileAssign -d <DISP option>	supported
	DLM	m_FileAssign -D <delimiter>	supported
	DSID		N.R.
	DSNAME	m_FileAssign	supported
DD (continued)	DSNTYPE		N.S.
	DUMMY	m_FileAssign with /dev/null	supported
	DYNAM	m_FileAssign with /dev/null	supported
	EXPDT	m_FileAssign -e	supported
	FILEDATA		N.R.
	FREE		N.R.
	KEYLEN	m_FileAssign -k	supported
	KEYOFF	m_FileAssign -k	supported
	LABEL		N.R.
	LGSTREAM		N.R.
	LIKE	m_FileAssign -s	supported
	LRECL	m_FileAssign -r	supported
	MGMTCLAS		N.R.
	MSVGP		N.R.
	PATH	m_FileAssign -U	N.R.
	PATHDISP		N.R.
	PATHMODE	m_FileAssign -M	N.R.
	PATHOPTS	m_FileAssign -O	N.R.
	PROTECT		N.R.
	QNAME		N.R.
	RECFM	m_FileAssign -r	supported
	RECORG	m_FileAssign -t	supported
DD (continued)	REFDD		N.S.
	RETPD	m_FileAssign -e	supported
	RLS		N.R.
	SECMODEL		N.R.
	SPACE		N.R.
	STORCLAS		N.R.
	SUBSYS		N.S.
	TERM		N.R.
	UNIT		N.R.
	VOLUME	m_FileAssgin -v	supported
DD : Printing parameters	BURST		N.S.
	CCSID		N.R.
	CHARS		N.S.
	COPIES	m_OutputAssign -c	supported
	DEST	m_OutputAssign -d	supported
	FCB		N.S.
	FLASH		N.S.
	HOLD	m_OutputAssign -H	supported
	MODIFY		N.S.
	OUTLIM		N.S.
	OUTPUT	m_OutputAssign -o	supported
	SEGMENT		N.R.
	SPIN		N.S.
	SYSOUT	see SYSOUT Parameter of DD Statement	supported
	UCS		N.S.
DD: Special statements	JOBLIB	m_JobLibset	supported
	STEPLIB	m_StepLibset	supported
	SYSABEND		N.S.
	SYSMDUMP		N.S.
	SYSUDUMP		N.S.
	SYSCHK		N.S.
	SYSIN	m_FileAssign	supported
	SYSCKEOV		N.S.
EXEC	ACCT		N.S.
	ADDRSPC		N.R.
	CCSID		N.R.
	COND	m_CondExec	supported
	DPRTY		N.R.
	DYNAMNBR		N.R.
	MEMLIMIT		N.R.
	PARM	m_ProgramExec	supported
	PERFORM		N.R.
	PGM	m_ProgramExec	supported
	PROC		supported
	RD		N.S.
	REGION		N.R.
	RLSTMOUT		N.R.
	TIME		N.S.
IF THEN ELSE END		m_CondIf   m_CondElse m_CondEndif	supported
INCLUDE	MEMBER	m_ShellInclude
JCLLIB	ORDER	m_JclLibSet
JOB	<jobname>	m_JobBegin	supported
	<accounting>		N.S.
	<prog. name>		N.S.
	ADDRSPC		N.R.
	BYTES		N.S.
	CARDS		N.R.
	CCSID		N.S.
	CLASS	m_JobBegin -c (with TuxJES).	supported
	COND	m_JobBegin -C	supported
	GROUP		N.R.
	JESLOG		N.S.
	LINES		N.S.
	MEMLIMIT		N.R.
	MSGCLASS		N.S.
	MSGLEVEL		N.S.
	NOTIFY		N.S.
	PAGES		N.S.
	PASSWORD		N.R.
	PERFORM		N.R.
	PRTY	m_JobBegin -p (with TuxJES).	supported
JOB	RD		N.S.
	REGION		N.R.
	RESTART	see RESTART Parameter of JOB Statement	Partially supported
	SECLABEL		N.R.
	SCHENV		N.R.
	TIME		N.S.
	TYPRUN	m_JobBegin -t (with TuxJES)	supported
	USER		N.S.
OUTPUT	ADDRESS		N.S.
	AFPSTATS		N.S.
	BUILDING		N.S.
	BURST		N.S.
	CHARS		N.S.
	CKPTLINE		N.S.
	CKPTPAGE		N.S.
	CKPTSEC		N.S.
	CLASS	m_OutputSet -c	supported
	COLORMAP		N.S.
	COMPACT		N.S.
	COMSETUP		N.S.
	CONTROL		N.S.
	COPIES	m_OutputSet -n	supported
	DATACK		N.S.
	DEFAULT	m_OutputSet -D	supported
	DEPT		N.S.
	DEST	m_OutputSet -d	supported
OUTPUT (continued)	DPAGELBL		N.S.
	DUPLEX		N.S.
	FCB		N.S.
	FLASH		N.S.
	FORMDEF		N.S.
	FORMLEN		N.S.
	FORMS	m_OutputSet -f	supported
	FSSDATA		N.S.
	GROUPID		N.S.
	INDEX		N.S.
	INTRAY		N.S.
	JESDS		N.S.
	LINDEX		N.S.
	LINECT		N.S.
	MAILBCC		N.S.
	MAILCC		N.S.
	MAILFILE		N.S.
	MAILFROM		N.S.
	MAILTO		N.S.
	MODIFY		N.S.
	NAME		N.S.
	NOTIFY		N.S.
	OFFSETXB		N.S.
OUTPUT (continued)	OFFSETXF		N.S.
	OFFSETYB		N.S.
	OFFSETYF		N.S.
	OUTBIN		N.S.
	OUTDISP		N.S.
	OVERLAYB		N.S.
	OVERLAYF		N.S.
	OVFL		N.S.
	PAGEDEF		N.S.
	PIMSG		N.S.
	PORTNO		N.S.
	PRMODE		N.S.
	PRTATTRS		N.S.
	PRTERROR		N.S.
	PRTOPTNS		N.S.
	PRTQUEUE		N.S.
	PRTY	m_OutputSet -p	supported
	REPLYTO		N.S.
	RESFMT		N.S.
	RETAINF		N.S.
	RETAINS		N.S.
	RETRYL		N.S.
	RETRYT		N.S.
OUTPUT (continued)	ROOM		N.S.
	SYSAREA		N.S.
	THRESHLD		N.S.
	TITLE		N.S.
	TRC		N.S.
	UCS		N.S.
	USERDATA		N.S.
	USERLIB		N.S.
	USERPATH		N.S.
	WRITER	m_OutputSet -w	supported
PROC		m_ProcInclude	supported
in-stream PROC		m_ProcBegin	supported
in-stream PEND		m_ProcEnd	supported
SET		m_SymbolSet	supported
XMIT (Records)			N.S.
XMIT (JOB)		m_SetJobExecLocation	supported
XEQ		m_SetJobExecLocation	supported
ROUTE	PRINT	Share with NFS	supported
	PUNCH	Share with NFS	supported
	XEQ	m_SetJobExecLocation	supported

DCB Parameter of DD Statement

 

Table 2‑2 DCB Parameter of DD Statement

DCB parameter	Equivalent in Target Environment	Status
BFANL		N.R.
BFTEK		N.R.
BLKSIZE		N.R.
BUFIN		N.R.
BUFL		N.R.
BUFMAX		N.R.
BUFNO		N.R.
BUFOFF		N.R.
BUFOUT		N.R.
BUFSIZE		N.R.
CPRI		N.R.
CYLOFL		N.R.
DEN		N.R.
DIAGNS		N.R.
DSORG	m_FileAssign -t	supported
EROPT		N.R.
FUNC		N.R.
GNCP		N.R.
INTVL		N.R.
IPLTXID		N.R.
KEYLEN	m_FileAssign -k	supported
LIMCT		N.R.
LRECL	m_FileAssign -r	supported
MODE		N.R.
NCP		N.R.
NTM		N.R.
OPTCD		N.R.
PCI		N.R.
PRTSP		N.R.
RECFM	m_FileAssign -r	supported
RESERVE		N.R.
RKP	m_FileAssign -t	supported
STACK		N.R.
TRESH		N.R.
TRTCH		N.R.

SYSOUT Parameter of DD Statement

 

Table 2‑3 SYSOUT Parameter of DD Statement

SYSOUT parameter	Usage	Equivalent in Target Environment	Status
First parameter	Class	m_OutputAssign -c	supported
Second parameter	INTRDR	m_OutputAssign -w	supported
	SMTP	m_OutputAssign -w	supported
	<writer>	m_OutputAssign -w	supported
Third parameter	Form name	m_OutputAssign -f	supported
	Code name		N.S.

DATACLAS Parameter of DD Statement

The DATACLAS parameter is taken into account at WB JCL level only.

Using the DATACLASS informations, extracted from z/OS, the WB JCL updates the m_FileAssign function (or m_FileBuild from DATACLAS parameter in IDCAMS DEFINE commands).

RESTART Parameter of JOB Statement

Only the Deferred Step Restart type is managed.

The other types, Automatic Restart (Step or Checkpoint) and Deferred Checkpoint Restart, are not managed.

A deferred step restart of a job is caused by coding the function m_JobBegin with the -r parameter containing a job step and by submiting the job again.

In-Stream File

The in-stream files are supported using the m_FileAssign function with the -i parameter.

Concatenation of Files

The concatenation of files (or in-stream files) is supported using the m_FileAssign function with the -C parameter.

Override of Files

The overriding feature is supported.

Use the m_FileOverride function for the files managed by the m_FileAssign function.

Use the m_OutputOverride function for the files managed by the m_OutputAssign function.

Execution of External Sysin

Use the m_UtilityExec function in order to execute commands stored in a file.

Network Job Entry (NJE)

The following table describes the supported JES2 control statements and parameters in Oracle Tuxedo Application Rehosting Workbench and Batch Runtime.

 

Table 2‑4 Supported Parameters

Statement	Supported Parameter
/*XEQ	/*XEQ nodename
/*ROUTE	/*ROUTE PRINT LOCAL /*ROUTE PRINT nodename /*ROUTE PUNCH nodename /*ROUTE XEQ nodename
/*XMIT	/*XMIT nodename

ABEND Routine

Captures terminations abnormally or normally from user program. It provides three COBOL programs, ILBOABN0, CEE3ABD and ART3ABD, which can be called in specific conditions to ABEND the program by itself. When the ABEND routine calls stop run, stop run terminates the process after Batch Runtime performs necessary cleanup.

•	ILBOABN0 abcode

abcode: the ABEND code.

•	CEE3ABD abcode, clean-up

abcode: the ABEND code.

•	clean-up(input)

The possible values are:

0: Issue the ABEND. Batch Runtime will capture ABEND and do clean-up work. Job failed.

1: Issue the ABEND. Batch Runtime will capture ABEND and store a system dump in a file, then do clean-up work. Job failed.

•	ART3ABD abcode

abcode: the ABEND code.

The ILBOABN0.cbl source is in the Batch_RT/ejr/SAMPLE directory.

Note:

For Micro Focus COBOL, Batch Runtime provides two ABEND-handling routines, ILBOABN0 and ART3ABD, that are called to force ABEND. Micro Focus COBOL provides its own ABEND-handling routine, CEE3ABD. It works as defined by Micro Focus COBOL.

For COBOL-IT COBOL, Batch Runtime provides two ABEND routines, ILBOABN0 and CEE3ABD.

General Utility Commands Equivalence Table

 

Table 2‑5 General Utility Commands Equivalences

Utility	Command	Equivalent in Target Environment	Status
IDCAMS (modal commands)	IF/THEN/ELSE		supported
	SET		supported
	CANCEL		N.S.
	DO/END		N.S.
	MAXCC		supported
	LASTCC		supported
IDCAMS	ALLOCATE (main parameters)	m_FileBuild	supported
	ALTER NEWNAME	m_FileRename	supported Note: Renaming for VSAM RDB files is not supported.
	ALTER LIBRARYENTRY		N.R.
	ALTER VOLUMEENTRY		N.R.
	BLDINDEX		N.R.
	CREATE LIBRARYENTRY		N.R.
	CREATE VOLUMEENTRY		N.R.
	DCOLLECT		N.S.
	DEFINE ALIAS		N.S.
	DEFINE AIX	m_FileBuild -K	supported
	DEFINE CLUSTER	m_FileBuild	supported
	DEFINE GDG	m_GenDefine	supported
	DEFINE NONVSAM		N.S.
	DEFINE PAGESPACE		N.R.
	DEFINE PATH		N.R.
	DEFINE USERCATALOG		N.R.
	DELETE ALAIS		N.S.
	DELETE AIX	m_FileBuild -R	supported
	DELETE CLUSTER	m_FileDelete	supported
	DELETE GDG	m_FileDelete	supported
	DELETE LIBRARYENTRY		N.R.
	DELETE NONVSAM	m_FileDelete	supported
IDCAMS (continued)	DELETE NVR		N.S.
	DELETE PAGESPACE		N.R.
	DELETE PATH		N.R.
	DELETE TRUENAME		N.S.
	DEL USERCATALOG		N.R.
	DELETE VOLUMEENTRY		N.R.
	DELETE VVR		N.R.
	DIAGNOSE		N.S.
	EXAMINE		N.S.
	EXPORT		N.S.
	EXPORT DISCONNECT		N.R.
	IMPORT		N.S.
	IMPORT CONNECT		N.R.
	LISTCAT	m_FileListcat	supported
	LISTDATA		N.S.
	PRINT	m_FilePrint	supported
	REPRO	m_FileRepro	supported
	SETCACHE		N.R.
	SHCDS		N.R.
	VERIFY		N.S.
IEBCOPY	ALTERMOD		N.R.
	COPY	m_DirCopy	supported
	COPYGRP		N.R.
	COPYMOD		N.R.
	EXCLUDE	m_DirCopy -e	supported
	SELECT	m_DirCopy -s	supported
IEBGENER	With SYSIN DUMMY	m_FileLoad	supported
	GENERATE MEMBER		N.S.
	GENERATE RECORD	m_FileSort	supported
IEFBR14		m_ProgramExec IEFBR14	supported
IEFBR15		m_ProgramExec IEFBR15	supported
PKZIP	Main parameters	m_Pkzip	supported
PKUNZIP	Main parameters	m_Pkunzip	supported
SMTP		m_Smtp	supported
XMITIP		m_SendMail	supported
ZIP390	ACTION : ZIP	m_Pkzip	supported
	ACTION : UNZIP	m_Pkunzip	supported
	ENCRYPT		N.S.
	IFILE		supported
	OFILE		supported
	ARCHIVE		supported
	OVERWRITE		supported

 

Sort Utilities

Sort Utilities Equivalence Tables

SORT, SORTD, DFSORT, ICEMAN, SYNCSORTT

 

Table 2‑6 Sort Utilities Equivalences

Sort Statement	Parameter	Equivalent in Target Environment	MFSORT	SyncSort
SORT		m_FileSort	Supported	Supported
MERGE		m_FileSort	Supported	Supported
OPTION		m_FileSort
	COPY		Supported	Supported
	SKIPREC		Supported	Supported
	STOPAFT		Supported	Supported
	INCLUDE		Supported	Supported
	OMIT		Supported	Supported
	OUTFILE		Supported	Supported
	OUTREC		Supported	Supported
	END		Supported	Supported
	RECORD		Supported	Supported
	SUM		Supported	Supported

ICETOOL

 

Table 2‑7 ICETOOL Equivalences

Sort Statement	Equivalent in Target Environment	MFSORT	SyncSort
SORT	m_FileSort	supported	supported
COPY	m_FileSort	supported	supported
MERGE	m_FileSort	supported	supported

Sort Limitations

when using syncsort utility, there are some limitations:

•	DFSORT (DATE3) format has no equivalent on syncsort.

•	DFSORT statements (outrec, inrec) are not fully suppported in the following situations:

•	If a key or a filed definition of an outrec field cut a field constant type, an error shows up (MT_ERROR in SYSIN translation) and :#PHX in ksh.

•	If a key or a field definition of an outrec field is not included in the inrec, an error shows up.

•	Cases with SUM are not handled.

DB2 Utilities

Only DB2 Connect 9.7 or above is supported.

 

Table 2‑8 DB2 Utilities

Command	Parameter	Equivalent in Target Environment	0racle	DB2LUW
DSNTEP2	SQL	m_ExecSQL	supported	supported
DSNTEP4	SQL	m_ExecSQL	supported	supported
DSNTIAD	SQL	m_ExecSQL	supported	supported
DSNTIAUL	SQL	m_ExecSQL	supported	supported
	“Unload”	m_DBTableUnload	supported	supported
DSNUTILB	EXEC SQL	m_ExecSQL	supported	supported
	LOAD	m_DBTableLoad	supported	supported
	UNLOAD	m_DBTableUnload	supported	supported

DSNTIAUL

On mainframe, DSNTIAUL program is used to unload data from DB2 tables into sequential data sets. The data is copied to the data sets and is not deleted from the table.

To unload data from Oracle Database tables, Batch runtime provides you DSNTIAUL utility, which has the same functionality as DSNTIAUL program on mainframe with DB2.

The following table shows the supported DB2 data types and their conversion to the Oracle Database target.

 

Table 2‑9 Supported Data Types

Data Type in DB2 on Mainframe	Mapped Data Type in Oracle Database
DECIMAL(p)	NUMBER(p)
DECIMAL(p,s)	NUMBER(p,s)
CHAR(n)	CHAR(n)
VARCHAR(n)	VARCHAR2(n)
TIMESTAMP Note: Only supports the default format "YYYY-MM-DD-HH24.MI.SS.FF6".	TIMESTAMP
TIME Note: Only supports the default format "HH24.MI.SS".	DATE
DATE Note: Only supports the default format "YYYY-MM-DD".	DATE
real	BINARY_DOUBLE
Float(n) (1<=n<=21)	BINARY_DOUBLE
Float(n) (22<=n<=53)	BINARY_DOUBLE
Double	BINARY_DOUBLE

DSNTIAUL Limitations

•	When applying equivalent SQL functions in select statement for the same database table column, the data type that Batch runtime DSNTIAUL outputs for Oracle Database may be different from the data type that mainframe DSNTIAUL outputs for DB2.

•

For real, Float(n) (1<=n<=21), Float(n) (22<=n<=53), and Double data types in DB2, they are converted to BINARY_DOUBLE data type (with eight bytes) in Oracle Database. You can retrieve the field in target file to COMP-2 variable in COBOL program by using Micro Focus COBOL (COBOL-IT COBOL may produce incorrect results).

•	The output file should be a fixed-width sequential file.

DSNTIAUL Configuration

Do the followings to configure Batch Runtime DSNTIAUL.

1.	Set up environment variables for your Batch Runtime.

For more information, see Setting Environment Variables in Oracle Tuxedo Application Runtime for Batch User Guide.

2.	Enable Batch Runtime built-in DB2-to-Oracle SQL Converter.

To enable it, you can either use export MT_DB_SQL_PREPROCESS="${JESDIR}/tools/sql/oracle/BatchSQLConverter.sh" or configure MT_DB_SQL_PREPROCESS in $JESDIR/ejr/CONF/BatchRT.conf.

3.	Configure MT_DSNTIAUL=Y.

The default value of MT_DSNTIAUL is "Y". For more information, see Setting Environment Variables in Oracle Tuxedo Application Runtime for Batch User Guide.

4.	Set DATE, TIMESTAMP, TIMESTAMP WITH TIME ZONE and TIMESTAMP WITH LOCAL TIME ZONE formats.

•	Environment "DSNTIAUL_DATE_FORMAT" defines date format. If it is not set, use the default value "YYYY-MM-dd HH24:MI:SS".

•	Environment "DSNTIAUL_TIMESTAMP_FORMAT" defines timestamp format. If it is not set, use the default value "YYYY-MM-DD-HH24.MI.SS.FF6".

•	Environment "DSNTIAUL_TIMESTAMP_TZ_FORMAT" defines timestamp with time zone format. If it is not set, use the default value "YYYY-MM-DD-HH24.MI.SS.FF6".

•	Environment "DSNTIAUL_TIMESTAMP_LTZ_FORMAT" defines timestamp with local time zone format. If it is not set, use the default value "YYYY-MM-DD-HH24.MI.SS.FF6".

5.	Set language and territory.

Environment variable "NLS_LANG" defines language and territory. If it is not set, use the default value "American".

DSNUTILB

DSNUTILB

On mainframe, DSNUTILB specifies a utility control program. Batch runtime provides you DSNUTILB utility to unload data from Oracle tables into a variable-length sequential data set and load data from a sequential data set to Oracle table.

DSNUTILB Configuration

•	Set DATE, TIMESTAMP, TIMESTAMP WITH TIME ZONE and TIMESTAMP WITH LOCAL TIME ZONE formats.

•	Environment "DSNUTILB_DATE_FORMAT" defines date format. If it is not set, use the default value "YYYY-MM-dd HH24:MI:SS".

•	Environment "DSNUTILB_TIMESTAMP_FORMAT" defines timestamp format. If it is not set, use the default value "YYYY-MM-DD-HH24.MI.SS.FF6".

•	Environment "DSNUTILB_TIMESTAMP_TZ_FORMAT" defines timestamp with time zone format. If it is not set, use the default value "YYYY-MM-DD-HH24.MI.SS.FF6".

•	Environment "DSNUTILB_TIMESTAMP_LTZ_FORMAT" defines timestamp with local time zone format. If it is not set, use the default value "YYYY-MM-DD-HH24.MI.SS.FF6".

•	Set DSNUTILB_CLEAN_TABLE.

•	Environment "DSNUTILB_CLEAN_TABLE" chooses the way to delete records in a table when REPLACE option is set for load process in DSNUTILB. Valid values are 1, 2, and 3. If it is not set or set incorrectly, use the default value 1.

•	1: Use stored procedure. Batch runtime provides SQL script $JESDIR/util/DSNUTILBPKG.sql to create DSNUTILB_PKG package, which contains a procedure to truncate specific table.

•	2: Use statement truncate.

•	3: Use statement DELETE.

•	Set language and territory.

Environment variable "NLS_LANG" defines language and territory. If it is not set, use the default value "American".

COBOL Runtime

A COBOL runtime, runb, is provided to initialize the execution context of a user COBOL program before the call for its execution. This runtime is used instead of the standard COBOL runtime.

Oracle Tuxedo Application Runtime for Batch Purpose

•	Abort trapping procedure definition (standard: std_proc_error and database: dba_proc_error). The standard procedure traps COBOL errors and traces them in a log file. The Database procedure executes a rollback function to insure data integrity.

•	Database access function tracing management (mw_dbstat).

•	Database Connection and Disconnection and data integrity control (COMMIT and ROLLBACK).

•	COBOL program execution.

DataBase Interaction Management

Oracle Tuxedo Application Runtime for Batch takes care of the Database context usage:

•

Initialization: The runtime command, runb, connects it to the database according to the MT_DB_LOGIN environment variable . It must have the correct value (user name, password and Oracle instance, at least "/"). It can be used in the TuxJES Security Configuration file and specified when submitting jobs or set as an environment variable. If the configuration file is not specified, the environment variable MT_DB_LOGIN value is used.

•	Termination: Depending on the program return code, the Batch Runtime executes a COMMIT (if program return code is less than MT_PROG_RC_ABORT) or a ROLLBACK (if program return code is greater than or equal to MT_PROG_RC_ABORT), then disconnects from the database.

Access Supervisor Call - svc99()

•	Description

•	SVC99 Parameters

•	SVC99 Program

•

Appendix

Description

On mainframe, svc99() is a function that provides access to SVC99 on z/OS, which provides ability to

•	Dynamically allocate or deallocate a resource

•	Dynamically concatenate or deconcatenate data sets

•	Dynamically retrieve information on data sets

ART for Batch provides you these functionalities:

•	Dynamically allocate or deallocate a resource

•	Dynamically retrieve information on data sets

Syntax

int svc99(__S99parms *string);

This table shows elements contained by __S99parms.

 

Table 2‑10 __S99parms Elements

Field	Value Stored	Supported
__S99RBLN	SVC99 length of request block	Yes
__S99VERB	SVC99 verb code	Yes
__S99FLAG1	SVC99 Flags 1 field	Ignored
__S99ERROR	SVC99 error code field	Yes
__S99INFO	SVC99 information code	Yes
__S99TXTPP	SVC99 pointer to a list of text unit pointers	Yes
__S99S99X	SVC99 pointer to the Request Extension Block	Ignored
__S99FLAG2	SVC99 Flags 2 field for APF authorized programs	Ignored

Data type definition in C program is as below:

Listing 2‑1 Data Type Definition in C Program

struct __S99struc {

unsigned char __S99RBLN; /* Length of the request block */

unsigned char __S99VERB; /* Action verb */

unsigned short __S99FLAG1; /* Flags 1 field */

unsigned short __S99ERROR; /* Error Code */

unsigned short __S99INFO; /* Info Code */

struct S99TU** __S99TXTPP; /* Pointer to text pointer array */

void ** __S99S99X; / * Pointer to the Request Extension Block */

unsigned int __S99FLAG2; /* FLags 2 field for APF authorized programs */

};

typedef struct __S99struc __S99parms;

 

Data type definition in COBOL program is as below:

Listing 2‑2 Data Type Definition in COBOL Program

01 s99rb.

03 s99rb-len pic x(1).

03 s99rb-verb pic x(1).

03 s99rb-flag11 pic x(1).

03 s99rb-flag12 pic x(1).

03 s99rb-error pic 9(4) comp-5.

03 s99rb-info pic 9(4) comp-5.

03 s99rb-s99tu-array-ptr pointer.

03 s99rb-rbx pointer.

03 s99rb-flag21 pic x(1).

03 s99rb-flag22 pic x(1).

03 s99rb-flag23 pic x(1).

03 s99rb-flag24 pic x(1).

 

Return Code

Return codes are:

 

Table 2‑11 Return Code

Return Code	Meaning and Action
-1	Internal error.
0	Successful completion. An information reason code will be returned in S99INFO if a non-terminating error occurred during request processing.
4	An error occurs.
8	The installation validation routine denies this request.
12	The parameter list is not valid. The system will return a Class 3 error reason code in S99ERROR.

If svc99() encounters a non-terminating error during processing, the system places an information reason code in the field __S99INFO.

 

Table 2‑12 Error Code

Error Code (_S99ERROR)	Meaning
892	Invalid LEN specified in text unit.
896	Mutually exclusive key specified. Two keys that cannot be used together are used in the request.
904	Required key not specified.
1040	Specified ddname unavailable.
1080	Specified ddname not found.

SVC99 Parameters

__S99RBLN

A one-byte field containing the length of the request block.

__S99VERB

A one-byte field that identifies the dynamic allocation functions to be performed. The verb codes and the functions they represent are listed below:

 

Table 2‑13 Verb Code

Verb Code	Description	Supported
0x01	Request for dsname allocation	Yes
0x02	Request for deallocation (based on dsname or ddname)	Yes (Support to de-allocate data set based on ddname)
0x03	Request for concatenation	No
0x04	Request for deconcatenation	No
0x05	Request for removing the in-use attribute based on task-ID	No
0x06	Request for ddname allocation	No
0x07	Request for information retrieval	Yes

__S99ERROR

A two-byte field into which the system returns error reason codes when API svc99 has completed processing.

__S99INFO

A two-byte field that contains information reason codes when API svc99 has completed processing.

__S99TXTPP

The __S99TXTPP element points to addressable storage containing an array of text unit pointers. The following figure shows the format of text unit pointer lists and text units.

Note:

On mainframe, the last entry in the text unit pointer list has the high-order bit is set to one; however, on Linux, this setting is unworkable. Therefore, the last entry in the text unit pointer list has the value of 0xffffffffffffffff.

 

Table 2‑14 Text Units

Offset	Length	Description
+0	2	Text unit key. The key identifies the type of information contained in the text unit.
+2	2	Number. The number field contains the number of length-data pairs that follow. Most of the text units have only one length and one data field.
+4	2	Length. The first of perhaps many length fields. The length value includes only the length of the data field immediately following it.
+6	n	Data. The first of perhaps many data fields. The data field contains the parameter information being passed.
+(8+n)		Second length-data entry if the number field indicates more than one entry is present.

Data type definition in C program is as below:

Listing 2‑3 Data Type Definition in C Program

struct S99TU { /* Array of text units */

unsigned short key; /* Key for type of parameter */

unsigned short number; /* Number of len/parm pairs to follow */

struct {

unsigned short len; /* Length of the following parm */

char parm[MAXTULEN]; /* Parameter value */

} ent;

};

 

Data type definition in COBOL program is as below:

Listing 2‑4 Data Type Definition in COBOL Program

01 tu-ptr-list.

03 tu-ptr-xxx pointer.

……

03 pic x(8) value x'ffffffffffffffff'.

 

* Text Unit for allocate DSN - Data Set Name

01 ws-aldsn-TU-xxx.

03 ws-aldsn-TU-xxx-key pic 9(4) comp-5.

03 ws-aldsn-TU-xxx-num pic 9(4) comp-5.

03 ws-aldsn-TU-xxx-ent-len pic 9(4) comp-5.

03 ws-aldsn-TU-xxx-ent-txt pic x(80).

……

set tu-ptr-xxx to address of ws-aldsn-TU-xxx.

set s99rb-s99tu-array-ptr to address of tu-ptr-list.

 

SVC99 Program

SVC99 program is supported to dynamically allocate and deallocate data sets, and retrieve information on data sets.

•	Allocating a Data Set

•	Deallocating a Data Set

•	Retrieving Information on Data Sets

Allocating a Data Set

Use verb code 01 and the text units listed below for the dsname allocation function. All unsupported text unit keys are not listed.

 

Table 2‑15 Text Units for Dsname Allocation Function

Text Unit Key	Mnemonic	Description	Supported
0x0001	DALDDNAM	ddname	YES
0x0002	DALDSNAM	Fully qualified data-set name	YES
0x0004	DALSTATS	Data Set status. Values are: __DISP_OLD, __DISP_NEW, __DISP_MOD, and __DISP_SHR	YES Note: When you code DALSTATS, LEN must be 1.
0x0005	DALNDISP	Specifies the normal disposition of a data set. Values are: __DISP_CATLG, __DISP_UNCATLG, __DISP_DELETE, and __DISP_KEEP	YES Note: When you code DALNDISP, LEN must be 1.
0x0006	DALCDISP	Specifies the conditional disposition of a data set. Values are: __DISP_CATLG, __DISP_UNCATLG, __DISP_DELETE, and __DISP_KEEP	YES Note: When you code DALCDISP, LEN must be 1.
0x0010	DALVLSER	Volume serial number of the device a data set will reside on	YES
0x003C	DALDSORG	Data Set organization of a data set. Values are: __DSORG_unknown Unknown __DSORG_VSAM VSAM __DSORG_GS Graphics __DSORG_PO Partitioned organization __DSORG_POU Partitioned organization unmovable __DSORG_DA Direct access __DSORG_DAU Direct access unmovable __DSORG_PS Physical sequential __DSORG_PSU Physical sequential unmovable.	YES (Support the value of __DSORG_PO and __DSORG_PS) Note: When you code DALDSORG, LEN must be 2.
0x0049	DALRECFM	Record format of a data set. The values are: _M_ Machine-code printer-control characters _A_ ASA printer-control characters _S_ Standard fixed, spanned variable _B_ Blocked _D_ Variable ASCII records _V_ Variable _F_ Fixed _U_ Undefined _FB_ Fixed blocked _VB_ Variable blocked _FBS_ Fixed blocked standard _VBS_ Variable blocked standard.	YES (Support the value of _FB_ and _VB_) Note: When you code DALRECFM, LEN must be 1.
0x0042	DALLRECL	Record length of a data set	YES Note: When you code DALLRECL, LEN must be 2.
0x800B	DALRECO	Specifies the record organization of a VSAM data set. Values are: __KS, __ES, __RR, __LS.	YES Note: When you code DALRECO, LEN must be 1.
0x800C	DALKEYO	Specifies the key offset. The position of the first byte of the key in records of the specified VSAM data set.	YES Note: When you code DALKEYO, LEN must be 4.
0x0040	DALKYLEN	Specifies the length in bytes of the keys used in the data set.	YES Note: When you code DALKYLEN, LEN must be 1.

Notes:

•	The combination of DALRECFM and DALRECO is not allowed because the DALRECFM keyword only applies to non-VSAM data sets, while the KS, ES, RR, and LS values of the DALRECO keyword only apply to VSAM data sets.

•	The combination of DALDSORG and DALRECO is not allowed.

•	It is not supported to allocate a variable-length VSAM data set.

Deallocating a Data Set

Use verb code 02 and the text unit keys listed below and described as follows to request dynamic deallocation processing. To deallocate a data set, you must specify DUNDDNAM key.

 

Table 2‑16 Text Units to Request Dynamic Deallocation Processing

Text Unit Key	Mnemonic	Description	Supported
0x0001	DUNDDNAM	Specifies the ddname of the resource to be deallocated.	YES
0x0002	DUNDSNAM	Specifies the data set to be deallocated.	No
0x0003	DUNMEMBR	Specifies the PDS member to be deallocated.	No
0x0005	DUNOVDSP	Specifies an overriding disposition for the data set to be unallocated.	No
0x0007	DUNUNALC	Specifies deallocation even if the resource has the permanently allocated attribute.	No
0x0008	DUNREMOV	Specifies removal of the “in-use” attribute, even if the resource does not have the permanently allocated attribute.	No
0x000A	DUNOVSNH	Specifies “nohold” status for a deallocated SYSOUT data set and overrides previous “hold” specification.	No
0x0018	DUNOVCLS	Specifies an overriding SYSOUT class.	No
0x0058	DUNOVSUS	Specifies an overriding destination to which the SYSOUT data set being deallocated is to be routed.	No
0x0059	DUNOVSHQ	Specifies “hold” status for a deallocated SYSOUT data set and overrides previous “nohold” specifications.	No
0x0063	DUNOVUID	Specifies an overriding destination user ID to which the SYSOUT data set being deallocated is to be routed.	No
0x8013	DUNSPIN	Specifies an overriding decision that determines whether the output for the SYSOUT data set is to be printed immediately, or at the end of the job.	No
0x8017	DUNPATH	Specifies the pathname of the z/OS® UNIX file to be deallocated.	No
0x801A	DUNOVPDS	Specifies an overriding disposition for the file to be deallocated.	No

Retrieving Information on Data Sets

Use verb code 07 and the text units listed in the following table and described as follows to request that dynamic allocation return certain information about the allocated resources. You must specify the DINDDNAM key, the DINDSNAM key, the DINPATH key, or the DINRELNO key to request information retrieval.

Keys X'0001', X'0002', and X'000F', and X'8017' are input keys. You use them to supply information to the system. The remaining keys are output keys, which the system uses to return the information you requested.

If you request the system return information that does not exist, the system sets the length field for that parameter to zero, and there will be no data field for that parameter.

 

Table 2‑17 Text Units for Retrieving Information on Data Sets

Text Unit Key	Mnemonic	Description	Supported
0x0001	DINDDNAM	Specifies the ddname identifier of the requested information.	YES
0x0002	DINDSNAM	Specifies the data set for which the information is requested.	YES
0x0004	DINRTDDN	Requests the associated ddname.	YES
0x0005	DINRTDSN	Requests the data set name.	YES
0x0006	DINRTMEM	Requests the PDS member name.	No
0x0007	DINRTSTA	Requests the data set's status.	YES
0x0008	DINRTNDP	Requests the data set's normal disposition.	YES
0x0009	DINRTCDP	Requests of the data set's conditional disposition.	YES
0x000A	DINRTORG	Requests the data set's organization.	YES
0x000B	DINRTLIM	Requests the number of resources that must be deallocated before making a new allocation.	No
0x000E	DINRTTYP	Requests the data set's type (terminal or dummy).	No
0x000F	DINRELNO	Specifies the desired allocation information retrieval by relative request number.	No
0x0010	DINRTVOL	Requests the return of the first volume serial number associated with the specified allocation.	YES
0x8017	DINPATH	Specifies the pathname of the z/OS® UNIX file for which information is requested.	No
0xC003	DINRCNTL	Requests the JCL CNTL statement reference.	No
0xC004	DINRSTCL	Requests the storage class of a new SMS-managed data set.	No
0xC005	DINRMGCL	Requests the management class of a new SMS-managed data set.	No
0xC006	DINRDACL	Requests the data class of a new data set.	No
0xC00B	DINRRECO	Requests the organization of a new VSAM data set.	YES
0xC00C	DINRKEYO	Requests the key offset of a new VSAM data set.	YES
0xC00D	DINRREFD	Requests the DD name specified by the REFDD parameter of the DD statement.	No
0xC00E	DINRSECM	Requests the name of the RACF® security data set profile.	No
0xC00F	DINRLIKE	Requests the data set name on the LIKE parameter.	No
0xC010	DINRAVGR	Requests the value of the unit of allocation for a data set.	No
0xC012	DINRDSNT	Requests the data set type, such as PDS.	No
0xC013	DINRSPIN	Requests the spin data set specification.	No
0xC014	DINRSEGM	Requests the number of logical, line-mode pages (the segment) to be produced for a SYSOUT data set before the segment becomes eligible for immediate printing.	No
0xC017	DINRPATH	Requests the return of the z/OS UNIX file path specification.	No
0xC018	DINRPOPT	Requests the return of the z/OS UNIX file options.	No
0xC019	DINRPMDE	Requests the return of z/OS UNIX file access attributes.	No
0xC01A	DINRPNDS	Requests the return of the disposition of the z/OS UNIX file during normal step termination.	No
0xC01B	DINRPCDS	Requests the return of the disposition of the z/OS UNIX file during abnormal step termination.	No
0xC01D	DINRFDAT	Requests the return of the organization of a z/OS UNIX file.	No
0xC02A	DINRSPI2	Requests the SPIN interval specification.	No
0xC02B	DINRSYML	Requests the SYMLIST specification.	No
0xC02C	DINRDSNV	Requests the DSNTYPE version.	No
0xC02D	DINRMAXG	When you have applied APAR OA42358, requests the value of MAXGENS.	No
0xC02E	DINRGDGO	Requests the return of the order in which the individual generation data sets (GDSs) are concatenated.	No

Appendix

•	Data Set Status

•	Data Set Normal/Conditional Disposition

•	Data Set Organization

•	Data Set Record Organization

Data Set Status

Data set status can contain one of the following values:

 

X'01'	OLD
X'02'	MOD
X'04'	NEW
X'08'	SHR

Data Set Normal/Conditional Disposition

Data set normal/conditional disposition for data set allocation can contain one of the following values:

 

X'01'	UNCATLG
X'02'	CATLG
X'04'	DELETE
X'08'	KEEP

Data set normal/conditional disposition for retrieving information data set can contain one of the following values:

 

X'01'	UNCATLG
X'02'	CATLG
X'04'	DELETE
X'08'	KEEP
X’10’	PASS

Data Set Organization

Data set organization can contain one of the following values:

 

X’0008’	VSAM
X’0080’	Graphics(GS)
X’0200’	Partitioned organization (PO)
X’0300’	Partitioned organization unmovable (POU)
X’0400’	Government of message transfer to or from a telecommunications message processing queue (MQ)
X’0800’	Direct access message queue (CQ)
X’1000’	Communication line group (CX)
X’2000’	Direct access (DA)
X’2100’	Direct access unmovable (DAU)
X’4000’	Physical sequential (PS)
X’4100’	Physical sequential unmovable (PSU)

Data Set Record Organization

Data set record organization can contain one of the following values:

 

X'80'	VSAM key-sequenced data set (KS)
X'40'	VSAM entry-sequenced data set(ES)
X'20'	VSAM relative record data set(RR)
X'10'	VSAM linear space data set(LS)