Monday, March 8, 2010

4. The DD statement

A DD (Data Definition_ statement must appear in a step when the executing program expects to read from or write to a dataset. In other words DD statement describes the dataset. The DD statement is the most complicated of all the JCL statements.
The maximum number of DD statements in a step is 3273 . The DD statement can be coded in any order and always appear after the EXEC statement with the exeception of
JOBLIB, JOBCAT, PROCLIB DD statement.

The DSN Parameter

The DSN (or DSNAME) parameter identifies the name of the dataset to be created or retreived.

General Syntax

DSN=name| referback keyword parameter

Name - It could be a qualified name. This name consists of two or more simple name separated by periods for a maximum of 44 characters.
E.g 1 DSN=da0001t.pcs.empfile

E.g.2 DSN=da0001t.pcs.cobol(ass1) identifies a library (da0001t.pcs.cobol) and a particular member. This notation describes a sequential dataset.

e.g.3 DSN=&&name
A simple name preceded by two ampersands identifies a temporary dataset. Temporary because it is not retained beyond job termination.
The system generates a name with the following format :
SYSyyddd.Thh.mm.ss.RV001.jobname.name
Yyddd – Julian Calender;
hhmmss – uses 24 hour clock ;
RV001 –system provided information in reference to the reader;
jobname – as it appears in the JOB statement ;
Name – whatever is coded after &&.



For e.g DSN=&&temp
SYS00173.T090000.RV001.da0001ta.temp

Remark :
If the DSN name is omitted from a DD statement (except DD * , SYSOUT and DUMMY) also indicates a temporary dataset. However the system generates a name with the following format :
SYSyyddd.Thhmmss.RV001.jobname.R0000001
//SORTWK1 DD UNIT=SYSDA,SPACE=(TRK,(1,2),RLSE)

SYS00173.T100000.RV001.da0001ta.R0000001

This form is basically used when a step requires a work dataset (a dataset created at the beginning of the step’s exeution and deleted at the end). Mostly by utilities.


Most utility uses this form

Referback : This can have three formats :
- *.stepname.ddname – Requests that the dataset name be copied from DD statement “ddname “ found in a previous step “stepname”.

e.g : DSN=*.step1.dd1

- *.ddname – Requests that the dataset name be copied from a previous DD statement “ddname “ found in the same step “stepname”.

e.g : DSN=*.dd1

- *.procexec.stepname.ddname – Requests that the dataset name be copied from DD statement “ddname “ found in a previous step “stepname” found within procedure “procexec”. (name of EXEC statement invokinh the procedure)
e.g : DSN=*.ps1.step1.dd1

The DISP Parameter

The DISP parameter specifies :
- if the dataset is to be created or retreived
- how to dispose of the dataset when the step terminates (normally or abnormally)

General Syntax

NEW ,DELETE ,DELETE
OLD ,KEEP ,KEEP
DISP= ( SHR ,CATLG ,CATLG ) keyword parameter
MOD ,UNCATLG ,UNCATG;
,PASS


DISP=(status-field,normal-disp-field,abnormal-disp-field)
The status-field : This field tells the system whether the dataset is to be created or retrieved.

NEW – Indicates that the dataset will be created in this step

OLD - Indicates that an existing dataset will be retrieved and demands exclusive control.

SHR - Indicates that an existing dataset will be retrieved. It also indicates that this dataset ,if on disk, can be shared with one or more other users.

MOD - This subparameter has two possible meanings :
Indicates that an existing dataset will be retrieved . This will be true if
• The dataset is either cataloged or passed
• The DD statement contains either VOL=SER or VOL=REF (a VOL VOL=REF referring to a DD statement, which is a nonspecific request for a new dataset, is not included)
Indicates that the dataset will be created. This is true if :
• The DD statement contains neither VOL=SER nor VOL=REF and it describes a dataset which is neither cataloged nor passed.
• The DD statement contains VOL=REF referring to a DD statement which is nonspecific request for a new dataset.

e.g. 1 //dd1 dd dsn=da0001t.empfile,disp=(mod,catlg),
// unit=tape

Explanation:
1. The system assumes da0001t.empfile to be an existing dataset, since the DD statement contains neither VOL=SER or VOL=REF. The system searches the catalog and gets volume informatiom from the catalog entry. The volume have been found. This dataset will be treted as existing dataset.
2. Had the dataset been neither cataloged nor passed. The systen would have been unable to find the volume information and MOD will default to new.

e.g 2 //dd1 dd dsn=da0001t.empfile,disp=(mod,catlg),
// unit=sysda,vol=ser=bs3003,space=(trk,(1,2))

Explanation: Since VOL=SER is specified, the fate of MOD is sealed, whether or not it exists. It will be treated as OLD (with appropriate positioning). If the dataset exists on that volume no problem, however, if it does not exist the result will be S213-04 ABEND failure (i.e dataset does not exists)

Note :When UNIT and VOL=SER is specified the system does not search the catalog to locate the dataset.

The normal disposition field : This field is used to tell the system how to dispose of the dataset when the step terminates normally (without an ABEND).
DELETE – indicates that the dataset is to be deleted when the step terminates. For an existing dataset, OLD, SHR or MOD (not defaulting to NEW), the dataset will also be uncataloged, if the catalog were used while retreiving the dataset. It will only delete if the catalog were not used during the retrieval. This means that for a cataloged dataset, if you specify UNIT and VOL=SER the system does not search the catalog.

Note :
1 When a tape dataset is deleted, nothing happens. A tape dataset cannot be deleted through the DISP parameter. It is effectively deleted when the dataset is written over.
2 A VSAM cluster cannot be deleted by coding DISP=(OLD,DELETE) as it defaults to DISP=(OLD,KEEP).
3 A member of PDS cannot be deleted, as DISP applies to the entire PDS, and as result it deletes the entire PDS. Use either TSO or IEHPROGM utility.
4 The system always issues a message indicating “ DELETED’ or “NOT DELETED N” N indicates the reason for failing.

KEEP – Indicates that the dataset is to be kept when the step terminates. The system takes no action and issues a message indicating the dataset was kept. Again, the system issues a message “KEPT”. Note that “NOT KEPT” message does not exists.

Note : KEEP does not imply CATLG. As a result, DISP=(NEW,KEEP) should be rarely used because next time you retrieve the dataset, you need to specify UNIT and VOL=SER.

CATLG – Indicates that the dataset is to be kept and an entry for it placed in the catalog when the step terminates.

Note :
1. If cataloging is successful, the system issues “CATALOGED”
2. If cataloging fails for a NEW dataset, the message will “NOT CATLGD n”
(n indicates the reason for failing).
3. If the dataset to be catologed is OLD or MOD , which was opened but did extend into additional volume(s), the message will “RECATALOGED n”
4. If the dataset to be cataloged is OLD or MOD and has extended into additional volume(s), the message will be “recataloged”
5. CATLG implies KEEP. DISP=(NEW,CATLG,DELETE) is a very common parameter.

When an attempt to catalog fails ?
Explanation: Under certain conditions, the attempt to catalog a new entry fails. The step termination routines normally issue a message to inform the user :
IEF287I dataset name
IEF287I VOL=SER=BS3001, BS3003 NOT CATLGD n
Followed by the message identifing the user catalog where the attempt to add the entry was made.
IEF285I user catalog name
IEF285I VOL=SER=vol serial KEPT
“n” identifies the reason for which the cataloging operation failed.
Often, n is 2. There are several reasons for failing to catalog a dataset. Most of them are seldom encountered. For instance, the failure could be due to an I/O error or an out-of-space condition in the catalog, both extremely rare. The one that is common is illustrated by means of an example.

//dd1 dd dsn=da0001t.empfile,disp=(new,catlg,delete),
// space=(trk,(1,2)),unit=sysda,
// dcb=(lrecl=80,recfm=fb,blksize=800)

If an entry for DA0001T.EMPFILE already exists in the catalog, the step termination routines will not replace the existing entry with the new one, however it keeps the dataset and issues the appropriate message. Unfortunately, “NOT CATLGD 2 “ is just a warning, operator tend to ignore.
Whenever, you get this message. The existing entry must be removed before the one with the same one is added. Use IEHPROGM or any other utility to remove the catalog before adding a new one.
What are the implications of ignoring this warning ? Assume that the existing catalog entry for dataset points to BS3001, which may or may not contain such a dataset. As a result of DD statement DD1 the dataset by the same name has been created and kept on different volume say BS3008 while the catalog entry remains unaltered.
Later, the user, who did not notice the “NOT CATLGD 2” message submits a job containing a DD statement.
//infile dd dsn=da0001t.emfile,disp=shr

The system will search the catalog, retrieves the dataset residing on volume BS3001, with no outward appearance of failure. If the dataset by that name does not exist, the result is S213-04 ABEND failure.
Note that an attempt to add a dulpicate entry in the volume encounters a “DULPCIPATE NAME ON DIRECT ACCESS VOLUME” JCL error.
This problem is not encountered in MVS/ESA, because the system deletes the dataset as well as uncatalog.

PASS – Indicates that an entry for the dataset (containing dsn, volume and unit information) be placed on a table in storage (Passed Dataset Queue). This entry is to be used in a subsequent step to “receive the passed dataset”. A message will appear “PASSED”.

The abnormal (or conditional) disposition field : This field is used to tell the systen how to dispose of the dataset when the step terminates abnormally (ABENDs). It is required only if this disposition is different from the normal disposition.
DELETE,KEEP,CATLG, and UNCATLG have the same meaning they do in the normal disposition. Note that PASS is not permitted in the abnormal disposition field.
The best example of using the abnormal disposition field is DISP=(NEW,CATLG,DELETE). If there is ABEND, the dataset is to be deleted. This eliminates future manual intervention to delete and uncatalog the dataset in order to restart.

Defaults: Some defaults in the DISP parameter are fixed and others variable.
• If the DISP parameter is omitted, the default is always (NEW,DELETE.
//sysut1 dd unit=sysda,space=(trk,(1,2))
//* (NEW,DELETE) IS THE DEFAULT

• If the status is omitted, the default is always NEW
DISP=(,CATLG) is same as DISP=(NEW,CATLG)

• If the normal disposition field is omitted
- If the status field is NEW, the default is DELETE
- If the status field is OLD or SHR and the dataset name non temporary
If the DD statement is not receiving a passed dataset, the default is KEEP.
//dd1 dd dsn=da0001t.empfile,disp=shr

• If a DD statement is receiving a passed dataset, which was created during the execution of the job and was never given a permanent disposition, the default is DELETE.

• If a DD statement is receiving a passed dataset, which was created during the execution of the job but was given permanent disposition since being created, the default is KEEP.


• If a DD statement is receiving a passed dataset which existed before the job began execution, the default is KEEP.

• If the status field is OLD or SHR and the dataset name temporary, the default is pass.
//dd1 dd dsn=old,dsn=&&temp
DISP=OLD defaults to DISP=(OLD,PASS) and the message will appear in the output –“INVALID DISP FIELD – PASS SUBSTITUTED”

• If the abnormal disposition field is omitted, the default is the normal disposition field.

The UNIT Parameter

The UNIT parameter identifies :
The device type or device address where the volume is mounted. The volume is the one where the dataset resides (or will reside if DISP=NEW).
• The number of devices to be allocated to the dataset.

• When the mount message is to be shown to the operator.

General Syntax

device address
UNIT =( generic device name ,device count ,DEFER ) Keyword parameter
generated device name

device address – Identifies the exact device address. This notation is almost never used.

Generic device name – Identifies the device type using a universal system-supplied name.
e.g : UNIT=3390 ; UNIT=3400-5 ; UNIT=3480

generated device name – Identifies the device type using an installation-defined name.

UNIT=SYSDA ; UNIT=DISK ; UNIT=TAPE
The generated names can be made to mean whatever an installation wishes them to mean. For example, UNIT=SYSDA can mean all 3380 devices of any density, or single density only, or a subset of double density devices or a combination of 3380 and 3390 device. Their definition can vary from installation to installation. Our GE machine has UNIT=SYSALLDA.

Of the three, the generated name is far the most commonly used.

Device count – Specifies the number of devices to be allocated for the dataset. The limit is 59 devices. If omitted default is 1 except when DD statement describes a disk multivolume dataset. In such case, device count=number of volumes.
E.g. 1 UNIT=(SYSDA,5) ; UNIT=(TAPE,2)

E.g. 2 UNIT=SYSDA is same as UNIT=(SYSDA,1) because of default

E.g. 3 //dd1 dd dsn=da0001t.empfile,disp=(,catlg,delete),
// unit=sysda,vol=ser=(bs3001,bs3002,bs3003),
// space=(trk,(1,2)),dcb=(lrecl=80,recfm=fb,
// blksize=800)

In this example UNIT =SYSDA defaults to UNIT=(SYSDA,3)

Note : UNIT=(,2) can also be used if the device is being supplied by the catalog.

DEFER : Requests that the mount message to the operator not be issued by the allocation routines but by the open routines when, and, if the dataset is opened.
Note : DEFER must never be used with disk. Generally, used for tapes.
There is no default for device name. If it is not coded in the UNIT parameter and it is also not supplied by the catalog, the Passed dataset Queue, the result will be allocation JCL error . The message is
“IEF210I JOBNAME STEPNAME DDANAME –UNIT FIELD SPECIFIES INCORRECT DEVICE NAME”, which is misleading. It means that the device name was needed but not coded.

The VOL Parameter

The main function of the VOL (or VOLUME) is to identify the volume(s) by serial number where an existing dataset resides or where a new dataset will reside.
General Syntax

vol ,SER=(vol1 [,vol2]…….
Volume =( ,REF=referback
,REF=dsname

SER=(vol1,vol2….) – Specifies the serial number(s) of the volume(s) to be used. The maximum number of volumes is 255.

A volume serial is a combination of alphabetic , numeric, and national characters ($ @ #) up to 6. A hyphen is also permitted. In a real (or production) environment, the number of characters is almost never less than 6.

e.g VOL=SER=BS3001 OR VOLUME=SER=BS3001
VOL=SER=(BS3013,BS3014)

REF=referback
Referback – This can have three formats :
*.stepname.ddname - Requests that the volume be the same as for DD statement “ddname” found in the previous step “stepname”.

VOL=REF=*.STEP2.DD1

*.ddname - Requests that the volume be the same as for previous DD statement “ddname” found in the same step “stepname”.

VOL=REF=*.DD1

*.procexec.stepname.ddname - Requests that the volume be the same as for DD statement “ddname” found in the previous step “stepname” found within a procecure “procexec” (name of EXEC statement invoking the procedure.

VOL=REF=*.PR1.STEP2.DD1

Remark:
Referbacks are not encouraged. They should be used only when they are necessary. A referback with a “stepname” will cause a JCL error if the referenced step does not execute. Such referbacks must be avoided where restart is required.

REF=dsname – Requests that the volume be the same as the one where dataset “dsname” resides on. The dataset must be cataloged or Passed. The dataset does not even have to exist, as long as it is cataloged or passed. The name of the referenced dataset need not appear anywhere else in the job.

e.g : VOL=REF=DA0001T.EMPFILE

Remark:
When VOL=REF (referback or dsname) is used, the system supplies the volume as well as the unit information. Therefore, the UNIT parameter is usually unnecessary.

The SPACE Parameter

The SPACE parameter must be included in a DD statement when :
• A new disk dataset is created.

• An old dataset needs to alter its entitlement to additional space. i.e., Request additional disk space for an old dataset when available space is exausted.

• An old disk dataset must free up all unused space.

General Syntax

TRK,
SPACE=( CYL, (prim-alloc [,sec-alloc] [,directory]) [,RLSE])
Blksize,
TRK – Requests that space be allocated in tracks.
CYL – Requests that space be allocated in cylinders.
Blksize – Specifies the average blocksize of the dataset. The system will translate it to tracks.
Prim-alloc. Primary allocation or primary quantity. It identifies the number of tracks (if TRK is coded) or cylinders (if CYL is coded) or the number of blocks (if blksize is coded) that must be allocated during the allocation process for a new dataset before the step begins execution. The system will allocate the requested space in one extent. If this is not possible (and CONTIG is not coded), two extents will be used, then three and so on up to five extents. If as many as five extents still cannot satisy the request, the result will be a allocation JCL error :

IEF257I jobname stepname ddname –SPACE REQUESTED NOT AVAILABLE.
If the request is nonspecific (no VOL=SER or VOL=REF), needing a storage volume, the JCL error message will be different :

IEF257I jobname stepname ddname –INSUFFICIENT SPACE ON STORAGE VOLUMES.

Remark :
The system will always allocate the primary quantity in the least number of extents possible on a single volume. The primary quantity cannot be split over multiple volumes. The primary allocation cannot be omitted (coding 0 is allowed). It is ignored if the dataset is old.
e.g 1 SPACE=(TRK,3)
e.g 2 SPACE=(CYL,4)
e.g 3 SPACE=(23440,100)
e.g 5 SPACE=(TRK,0)

sec-alloc - Secondary allocation or secondary quantity. It identifies the number of tracks (if TRK is coded) or cylinders (if CYL is coded) or the number of blocks (if blksize is coded) that are to be allocated when all available space is exhausted while writing to a dataset. The system will allocate the secondary quantity in the least number of extents possible, and just like the primary quantity, it can be given in as many as five extents, if necessary.
The system will always supply the specified secondary allocation when one is needed unless one of the two events occurs :
• The allocated volume does not have enough space to satisfy the secondary allocation and no other volumes are allocated.

• The needed secondary allocation, if granted, will cause the dataset to exceed 16 extents on the volumes and no other volumes are allocated.


If either of these two conditions arises, the result will be a SB37-04 ABEND failure (normally for a sequential dataset). For a PDS, the ABEND, can also be SE37-04. Please note that a PDS is confined to a single volume, ehile a sequential dataset can extend into a maximum of 59 volumes. The 16-extent-per-volume limit for a dataset is system-supplied and cannot be altered.
The secondary allocation is optional. If omitted, defaults to 0. When no secondary allocation is coded and the primary allocation is exhausted, the result is an SD37-04 ABEND failure.

Remark :
The secondary allocation can be used for new as well as old datasets. The secondary allocation requested when the dataset is created is recorded in the dataset’s DSCB (VTOC entry). If space is exhausted when the dataset is retrieved as OLD and extended, the system attempts to provide secondary allocation appearing in the DSCB. If ,however, a SPACE parameter is included in the DD statement, the secondary allocation will be based on what is coded in this SPACE parameter rather than what appears in the dataset’s DSCB.

E.g 1 SPACE=(TRK,(1,2))
E.g 2 SPACE=(CYL,(7,4))
E.g 3 SPACE=(23440,(200,100))

directory – Specifies the number of directory blocks (256 bytes each) to be assigned to the directory of a PDS.
The directory quantity, if not coded, defaults to zero; therefore, the directory quantity must be specified for a new PDS. If it is, not S013-14 ABEND failure will occur if an attempt is made to add the first member to a PDS.

Remark :
The directory quantity is taken away from the beginning of the primary allocation if TRK or CYL is coded in the SPACE parameter. When blksize is coded, the system adds the directory blocks to the data blocks and then computes the amount of primary space.

E.g 1 SPACE=(TRK,(20,5,5)) OR SPACE=(TRK,(20,,5)) if no secondary
E.g 2 SPACE=(CYL,(20,5,5)) OR SPACE=(CYL,(20,,5)) if no secondary
E.g 3 SPACE=(23440,(200,50,5)) OR SPACE=(23440,(200,,5)) if no secondary

RLSE –Requests that any unused space be freed when the dataset is closed. This works for both new and old datasets, provided they were opened for output. Space will be released on the boundary used in the SPACE parameter. If tracks (or cylinders) were allocated, unused tracks (or cylinders), will be released.

Remark :
Using RLSE is highly recommended for datasets not intended for future expansions. Temporary datasets are ideal candidates. For datasets that expand in future runs, RLSE can result in a larger number of extents, and, possibly, a premature SB37-04 ABEND failure. RLSE will be ignored if the dataset is opened by another user (or shared by another job) ot the step ABEND’s.

e.g: SPACE=(TRK,(5,1),RLSE)

The LABEL Parameter

The LABEL parameter can specify :
• The sequence of a tape dataset on a volume.

• The type of label of the dataset.

General Syntax

LABEL=([seq-no][,type]) keyword parameter

Seq-no – Identifies the sequence number of the dataset on a tape volume. 1 to 4 digits. If omitted, it defaults to 1. If 0 is coded, it defaults to 1. Maximum : 9999
e.g LABEL=3

type – Identifies the type of label for the dataset.
There are many types of labels. To name a few, which are important from project perspective.
SL – Indicates IBM standard label. If the subparameter is omitted, SL is the default.

NL – Indicates no labels are used. NL is not commonly used. Normally, NL is used for a tape coming from or going to another installation which has no SL capabilities.

BLP – Bypass Label Processing : Indicates that labels will not be recognized and will be treated as ordinary files. BLP is used as a last resort when neither SL nor NL can accomplish what is required.

Label Verification : When retrieving an SL tape dataset, both the volume serial and the dataset name will be verified. When creating an SL tape dataset with VOL=SER or VOL=REF, only the volume serial will be verified.

When retrieving an NL tape dataset, neither the volume serial nor dataset name can be verified. However, only an NL tape volume can be mounted. An SL volume will be rejected.

Defaults : If omitted, the LABEL parameter defaults to (1,SL). There are four ways to supply the same information.
• Omit the LABEL parameter

• Code LABEL=(,SL) 1 is the default

• Code LABEL=1 SL is the default
SL
VOL HDR1 HDR2 TM SL DATA SET # 1 TM EOF1 EOF2 TM TM
NL
NL DATASET #1 TM NL DATASET #2 TM TM

TM – Tape Mark

The DCB Parameter

The DCB parameter specifies values to be used to complete the Data Control Block (DCB) when a dataset is opened. A DCB is constructed by the language processor (compiler or assembler), based on the appropriate instructions of the language being used, and resides inside the code of the program. The compiler, collects this information and defaults from various parts of the program (For e.g In COBOL, RECORD CONTAINS 80 CHARACTERS; BLOCK CONTAINS 10 RECORDS and so on ) and constructs the DCB. Note that the DCB exists only for non VSAM datasets and is checked by the OPEN routines (for input or output). Certain values must be “hard-coded” in the DCB by the program. Others can can be left out, giving the user the option of supplying these values via the DCB parameter( as well as other means).

There are three suppliers of DCB information :
• Values supplied by the program, referred to as hard-coded. When a value is hard-coded, it cannot be changed unless the program is changed.

• Values coded in the DCB parameter of the DD statement. These values will be ignored if they are already hard-coded.

• Values from the standard label of the dataset. The values supplied by the label are limited to : BLKSIZE,LRECL, RECFM, DSORG etc. Values from the label will not be used if they are hard-coded inside the program or coded in the DCB parameter.

General Syntax

DCB=([referback] | [model][,subparameter],…… keyword parameter

Referback – This can have three formats :
*.stepname.ddname - Requests that the DCB parameter be copied from the DD statement “ddname” found in the previous step “stepname”.
DCB=*.STEP2.DD1

*.ddname - Requests that the DCB parameter be copied from a previous DD statement “ddname” found in the same step “stepname”.
DCB=*.DD1

*.procexec.stepname.ddname - Requests that the DCB parameter be copied from DD statement “ddname” found in the previous step “stepname” found within a procecure “procexec” (name of EXEC statement invoking the procedure.
DCB=*.PR1.STEP2.DD1

Remark :
The DCB referback copies the DCB parameter as opposed to the DSN and VOL=REF referbacks which acquire the dataset name and the volser respectively, whether or not the DSN and VOL parameters are present in the referenced DD statement. If the DCB referback refers to a DD statement which contains no DCB, nothing is copied and no message appears.

Model – specifies the name of the dataset which :
• Must be cataloged. If it is not, the result will be a JCL error : IEF2121 jobname stepname ddname –DATASET NOT FOUND

• Must be on disk (Tapes not allowed)


• Must reside on a volume that is accessible (online)

This dataset is called a model DSCB. The DCB information from the label of the model is extracted and can be used.

E.g 1. DCB=DA0001T.EMPFILE
E.g 2. In case you want to override some of the subparameters, the overriding subparameters must follow the DSCB model dataset name.

DCB=(DA0001T.EMPFILE,LRECL=100,BLKSIZE=800)

Models, are generally used, during the creations of GDG’s and dummying the PDS.

Subparameters : There is vast number of subparameters, the great majority of which are seldom or never used.
• BLKSIZE -Specifies the size of the block (also known as the physical record). For RECFM=FB, the blocksize must be multiple of the logical record length, and it identifies the exact size of the block. For RECFM=VB, the blocksize can be any value up to the limit but atleast 4 bytes larger than the logical record length. For RECFM=U, the blocksize can be any value up to the limit
Remark : There is no default for BLKSIZE. Coding BLKSIZE=0, the system will compute the optimum blocksize based on the device type.

E.g DCB=BLKSIZE=800

LRECL – Specifies the size of the logical record. The maximum size is 32,760, and it cannot be larger than blocksize, unless RECFM=VBS is used.

E.g. DCB=(LRECL=80,BLKSIZE=800)

RECFM –Specifies the record format. There are several values (or combinations of values) that can be coded.
• F - All blocks and all logical records are fixed in size.

• V - Blocks as well as logical records are of variable size. The first 4 bytes of each block (and logical record) describes its length.

• B – One or more logical records reside in each block. B cannot be coded alone. It is used in conjunction with F or V. For example FB or VB.

• U – Blocks are of variable size. There are no logical records. Mainly used with Load Library.

• S- For fixed-size records, it indicates that no short blocks are permitted anywhere but the end of the data. For variable-size records, it indicates that a logical record can span more than one block. S cannot be coded alone. It must follow F,V,FB or VB.

• A – Indicates that the first character of each record is an ANSI control character to be used for printer carriage control. A cannot be coded alone. It must follow F,V,FB,VB or U.


E.g DCB=(LRECL=80,RECFM=FB,BLKSIZE=800)

If RECFM is not supplied through any means, U is the default.

DEN – Identifies the density of the tape. DEN=3(or 4) indicates 1600 (or 6250 ) BPI density.

BUFNO – Identifies the number of buffers to be allocated in virtual storage by the OPEN routines, which will contain the blocks to be rean in or written out. If omitted, default is 5. The maximum is 255. Coding for BUFNO a number greater than 5 may require that the REGION parameter be increased.

EROPT – Specifies what action to take if an unrecoverable I/O error occurs while reading or writing a block.
• ABE – Cause an ABEND failure (S001-1).

• SKP – Skip the block containing the error.

• ACC – Accept the block containing the error

The default is ABE

DSORG – Identifies the organization of the dataset
• PS – Specifies physical sequential organization. Mostly QSAM and sometimes BSAM.

• PO - Specifies partitioned organization (or BPAM)

• DA- Specifies direct organization (or BDAM)

• IS – Specifies indexed sequential organization(or ISAM)

ABEND failures due to inconsistent DCB values :
• S013-20 ABEND when RECFM=FB is used but the BLKSIZE is not an exact multiple of LRECL. Note that SYSOUT is an exception.

• S013-34 ABEND when RECFM=FB is used and the LRECL is greater than the BLKSIZE.

• S013-34 ABEND when RECFM=VB is used and the LRECL is greater than the BLKSIZE-4.

Remark :
If values for BLKSIZE or LRECL are not supplied by any source (hard-coded or the DCB parameter or DSCB), the result will be an S013-34 ABEND failure.

• S001-04 ABEND when BLKSIZE in the DCB parameter is smaller than the actual blocksize and is a multiple of the LRECL in the DSCB of the dataset.

It is important to understand which of these often-used parameters are normally hard-coded and which are not :
• BLKSIZE - Seldom hard-coded. The BLKSIZE is unrelated to the logic of the program and hard-coding its value would cause unnecessary changes whenever the BLKSIZE is changed. In COBOL, BLOCK CONTAINS 0 RECORDS must be coded to avoid hard-coding the BLKSIZE. Omitting this clause will cause a default of 1 to be used. The result will be a hard-coded BLKSIZE is equal to LRECL. Many installation standards disallow hard-coding the BLKSIZE for sequential and partitioned datasets.

• LRECL – Frequently hard-coded. The logic of any ordinary program is dependent on the LRECL and, as a result, the LRECL cannot be changed without changing the logic of the program. Many high-level languages like COBOL always hard-code the LRECL.

• RECFM – Frequently hard-coded. The logic of any ordinary program is dependent on the RECFM and, as a result, the RECFM cannot be changed without changing the logic of the program. Many high-level languages like COBOL always hard-code the RECFM.

Instream Data

The input stream submitted to the system for execution consists of two possible parts :
• JCL mandatory part of the input stream

• Data mixed in with JCL in the input stream. This data is known as sysin data or input stream data. It is optional part of the input stream and always has a logical record length of 80. Any records encountered in the input stream which are not JCL statements will be treated as sysin data.

Sysin data must be preceded by a DD statement such as :
//name dd *
data
/*

Sysin data encountered by JES2 or JES3 following a DD * statement will be saved on the SPOOL volume for future use. This is known as input spooling The sysin is delimited (the spooling stops) by :
• A /* (delimiter) statement found.
• A valid JCL statement.
• An end-of-file condition on reading device.

The asterisk (*) is a positional parameter. The DD * is a special statement which is under complete JES2 or JES3 control.

SYSIN is a very common ddname used by many vendor-written programs to pass control information to the utility. E.g SORT,IEBGENER,IDCAMS utilities.

In user writtem programs, if you use COBOL ACCEPT statement. In your run JCL one of the DD statements will be SYSIN dd statement.
//sysin dd *
1234
/*

With the above type of DD statement, one complication arises if the sysin data must consist of JCL statement. Because any JCL statement delimits sysin data. To accomplish this, DD DATA instead of DD * must be used.

//sysut1 dd data
1234
abcd
//dd1 dd dsn=da0001t.empfile,disp=shr
/*

A /* must be used to delimit a DD DATA statement. A word of caution: Failure to supply a /* will cause serious problems. JCL statements following DD DATA will unintentionally become part of sysin data. However, If you want /* to be part of sysin data, code DLM parameter.

//sysut1 dd data,dlm=’)(‘
1234
abcd
//dd1 dd dsn=da0001t.empfile,disp=shr
/*
xyz
)(

The two characters that are coded in the DLM parameter (apostrophes must be used for special characters) will act as a delimiter and /* will be treated as data. Any two characters can be used. However, characters that are likely to appear in the first two positions of any record must be avoided to prevent premature delimiting sysin data.

DD parameter Function
* For reading data without // or /* in columns 1 and 2.
DATA For reading data with // but not /* in columns 1 and 2 containing JCL or statements.
DLM For reading data with either // or /* in columns 1 and 2.

* and DATA are positional parameters whereas DLM is a keyword parameter.

Remark :
If sysin data is not preceded by DD *, the system will generate a statement and place it in front of the sysin data .



E.g
//da0001ta job la2719,…..
//s1 exec pgm=ass1
//steplib dd …
1234
//dd1 dd …

is equivalent to

//da0001ta job la2719,…..
//s1 exec pgm=ass1
//steplib dd …
//sysin dd * (generated statement)
1234
//dd1 dd …

Note : A line with blanks is the most common offender. It is invisible to the user but it will be treated as data by the system This may or may not cause problem. Let us look at the following example.
//da0001ta job la2719,…..
//s1 exec pgm=ass1

//steplib dd …
//sysin dd *
1234
//dd1 dd …

The system will interpret the above JCL in the following way :
//da0001ta job la2719,…..
//s1 exec pgm=ass1
//sysin dd *

//steplib dd …
//sysin dd * (generated statement)
1234
//dd1 dd …

Conclusion : If there are two or more DD statements by the same name in the same step. This is not an error condition. When the program opens for SYSIN the first of the two be used. The other will be allocated and ignored.

Remark :
Generically, each DD statement must have a unique ddname except in special cases viz concatenation. In JES2, if a step contains identical ddnames, the system allocates devices and space and does disposition processing for both the DD statements. However, the systen directs all references to the first DD statement with that name in the step. In JES3, if a step contains identical ddnames, the job ABEND’S during allocation.

The SYSOUT Parameter

Print records generated by a program are not normally routed directly to a physical printer(theoretically it is possible, but in practice it is seldom done). Instead, they are written on the SPOOL pack and saved there for later viewing on a terminal or printing (or both). This is called output spooling, and is under the control of JES2 or JES3 which later can use one of their print routines to print the dataset. These print routines must schedule the datasets for printing, and msgclasses are used for this purpose. All print routines (called printers or writers) are associated with one or more classes (in all 36 classes) and each dataset to printed must also be assigned classes. The printer routines selects datasets for printing in a very similar way as initiators selects jobs for executions. Use S.ST option of ISPF menu to view the output dataset.

The SYSOUT parameter can assign this class, known as sysout or output class, to a dataset. Such datasets are called sysout or output datsets.

General Syntax

SYSOUT=(class| *) keyword parameter

Class – Identifies the sysout class of the dataset from A to Z and 0 to 9.
*- Indicates that the same class used in the MSGCLASS parameter of the JOB statement (or the installation-defined default, if MSGCLASS parameter is omitted) is to be used.
E.g 1. sysout=a
E.g 2 //sysprint dd sysout=*

This DD statement is used for printing system messages generated by JES2 or JES3. Each step must have SYSPRINT DD statement. Absence will cause “ SYSPRINT DD STATEMENT MISSING” message in the sysout.

E.g 3 //sysout dd sysout=* (or any sysout class may be assigned)
This DD statement is used when you have COBOL DISPLAY clause in your program.

Concatenation

Concatenating Datasets

At times, program may have to read in sequence several input datasets as if they were one. This can accomplished without physically putting the data in one datasets. This is done by concatenating the datasets in JCL code with comparable DCB characteristics without programming changes.

Note that only sequential and partitioned datasets can be concatenated. For sequential datasets, the maximum number of concatenations is 255 and for PDS it is 16. Concatenation has meaning only for sequential processing.

E.g 1. Concatenation of physical sequential files.

//dd1 dd dsn=da0001t.pcs.group1,disp=shr
// dd dsn=da0001t.pcs.group2,disp=shr
// dd dsn=da0001t.pcs.group3,disp=shr


E.g 2. Concatenation of partitioned datasets.

//dd1 dd dsn=da0001t.pds1.group1,disp=shr
// dd dsn=da0001t.pds2.group2,disp=shr
// dd dsn=da0001t.pds3.group3,disp=shr

There are number of rules and restrictions for concatenations :
1. The first concatenation is the only one with a ddname.
2. The logical record length and the record format of concatenated datasets must be the same. However, the blocksizes need not be.
3. The blocksize of the first concatenation must be greater than or equal to blocksizes of all subsequent concatenation. Violation of this rule results in S001-04 ABEND failure. This is true for DFP Version 2.3. For version DFP 2.4, one can concatenate datasets in any sequence, but for the first concatenation code the DCB parameter with the largest blocksize of all the concatenations.

E.g. Assume that in the JCL below, the first concatenation has a blocsize of 800, the second a blocksize of 800- and the third a blocksize of 23400.
//infile dd dsn=da0001t.pcs.group1,disp=shr,dcb=23400
// dd dsn=da0001t.pcs.group2,disp=shr
// dd dsn=da0001t.pcs.group3,disp=shr

4. Both sequential datasets and partitioned datasets can be concatenated, but not with each other – sequential with sequential and partitioned with partitioned only. Member of a PDS is treated as sequential dataset and thus can be concatenated with sequential dataset.
E.g
//in dd dsn=da0001t.empfile,disp=shr
// dd dsn=da0001t.pcs.data(emp),disp=shr

5. Disk as well as tape datasets can be concatenated but not with each other. Only like devices should be concatenated, disk with disk and tape with tape.

DUMMY Parameter

The DUMMY parameter is a positional parameter. At times, one might want to execute a program but suppress read or write operations in certain jobs, For example., not print a report. At other times, one might want to test a program without actually processing data.

The DUMMY parameter specifies that :
• No device or external storage be allocated.

• No disposition processing is performed.

• No input or output operations are performed for sequential access methods.





Remark :
1 DCB information is established. Generally used during testing process and in procedures. Instead of using DUMMY, one may use DSN=NULLFILE. It differs from DUMMY by virtue of its position. It is a keyword parameter.
E.g //DD1 DD DSN=NULLFILE

2 When an attempt to dummy a PDS is made will cause an S013-64 ABEND failure.

3 The DCB parameter may be required while coding DUMMY. Failure to do so may cause an S013-10 ABEND failure.

4 DUMMY provides a safe way to eliminate I/O activity when required.

The JOBLIB DD Statement

The JOBLIB statement identifies the program library (load library) where the programs to be executed throughout the job resides. It must be placed between the JOB and the first EXEC statement.
E.g :
//da0001ta job,la2719,……
//joblib dd dsn=da0001t.lib.loadlib,disp=shr
//s1 exec pgm=proga
//s2 exec pgm=progb

Expanation : PROGA (and PROGB) is expected to reside in DA0001T.LIB.LOADLIB as a member of a library and the system searches the directory. If not found will search certain predefined libraries and the S806-04 ABEND failure occurs.

Remark :
A JOBLIB DD statement can have several concatenations (max: 16)
E.g
//da0001ta job,la2719,……
//joblib dd dsn=da0001t.lib.loadlib,disp=shr
// dd dsn=da0001t.lib1.loadlib,disp=shr
// dd dsn=da0001t.prod.loadlib,disp=shr
//s1 exec pgm=proga

Explanation : All concatenations may be searched to locate a program. If, however, the program is found in a concatenation other than the last one, other concatenations will not be used. Note that, if a duplicate names exist in different concatenations, the user can decide which one is to be executed by determining the sequence of the concatenations.

The STEPLIB STATEMENT

The STEPLIB statement identifies the program library (load library) where the program to be executed for the step where STEPLIB resides. It can be placed anywhere after the EXEC statement.



E.g 1:
//da0001ta job,la2719,……
//s1 exec pgm=proga
//steplib dd dsn=da0001t.lib.loadlib,disp=shr
//s2 exec pgm=progb
//steplib dd dsn=da0001t.lib.loadlib1,disp=shr

Explanation : Program PROGA is expected to reside in DA0001TA.LIB.LOADLIB as a member of the library. If not found, will search certain predefined libraries and the S806-04 ABEND failure occurs.

E.g 2:
//da0001ta job,la2719,……
//joblib dd dsn=da0001t.lib.loadlib1,disp=shr
//s1 exec pgm=proga
//s2 exec pgm=progb
//steplib dd dsn=da0001t.lib.loadlib,disp=shr
//s3 exec pgm=progc

A STEPLIB DD statement has the effect of negating the JOBLIB DD statement for a particular step.

STORAGE DUMP

When a step encounters an ABEND failure, it is often advantageous to request a virtual storage dump, which can then be helpful in determining the cause of an ABEND. To request a storage dump, one of the following three DD statements must be included in the step :
• A SYSUDUMP DD statement

• A SYSMDUMP DD statement

• A SYSABEND DD statement

//sysudump dd sysout=*

All virtual storage allocated to your program i.e user region of job’s address space. It is a formatted dump. SYSUDUMP usually writes to sysout. It can, however, write to a disk dataset, providing a way to preserve the SYSUDUMP information for later viewing and analysis.

//sysudump dd dsn=da0001t.dumpfile,space=(trk,(0,5),rlse),
// disp=(,delete,catlg),unit=sysda

No DCB is required.

Remark :
SYSUDUMP DD statement is more often used.


//sysmudump dd sysout=*

This is same as SYSUDUMP DD statement except for the fact that the dump is nonformatted. This type of dump is very difficult to analyze unless it is saved on a disk and then processed by the PRDUMP service aid.
SYSMDUMP is seldom used.

//sysabend dd sysout=*

When a SYSUDUMP DD statement is included in a step which ABEND’s, a formatted virtual storage dump will be provided. This dump will also include information about the failed step, as well as most of the MVS storage-resident information which is of no use to the average user. SYSABEND is intended for system programmer.

Remark :
1 If neither a SYSUDUMP nor a SYSMDUMP nor a SYSABEND statement is coded wihin a JCL of an ABENDing step, a small amount of information is provided. This information is seldom useful in resolving the problem that caused the ABEND failure.

2 If more than one of the above statements is included in the JCL of a step, only the last one will be used. The previous ones will be ignored.

//s1 exec pgm=ass1
//sysabend dd sysout=*
//sysudump dd sysout=*

Note that SYSUDUMP will be in use.

Back to JCL Index
Back to home page

No comments: