A Primer for
ISPF Skeletons
BY DENNIS BECK
File tailoring allows the creation
of generic JCL streams that
can be configured on-the-fly
and reused without destroying
the original template. File
tailoring has definite advantages
to creating JCL PROCEDURES
as it allows substitution within
in-stream data statements
and true conditional include
processing.
TECHNICAL SUPPORT January ‘99
WHEN confronted with a routine
request such as creating a new
generation dataset group (GDG), many of
us dig through our control datasets and look
for JCL and control statements from the
last time we were given such a task. Taking
the previous JCL and using it as a template,
we change the pertinent arguments, in both
JCL and IDCAMS control statements, and
submit the job. Generally, we don’t forget
any changes, but when once in awhile we
do, we correct the JCL and re-submit. At
other times, a user asks for an example of
some utility function and we dig through
our JCL to find something close to the
request, edit the JCL and give the user the
(hopefully) correct example. This article
suggests a better approach to these kinds
of problems.
ISPF has a powerful feature available for
the novice to advanced user. This feature of
Dialog Manager, called file tailoring,
allows the creation of generic JCL streams
that can be configured on-the-fly and
reused without destroying the original
template. File tailoring has a definite
advantage to creating JCL PROCEDURES
as it allows substitution within in-stream
data statements and true conditional
include processing.
Use of file tailoring is fairly simple to
anyone having knowledge of the JCL
parameter substitution process and some
simple REXX programming experience.
This article introduces file tailoring using
an example that creates a generation dataset
group (GDG) with the IDCAMS utility.
SKELETON FILE DATASET FORMAT
Skeleton files are the templates that file
tailoring uses as input. Skeleton files
©1999 Technical Enterprises, Inc. Reproduction of this document without permission is prohibited.
reside as members in a PDS and can be
either fixed or variable length records of up
to 255 characters. Fixed length records
have the last eight characters reserved for
sequence numbers. Blank lines are
removed during the output substitution
process — blank lines may be added
using the )BLANK control card explained
in the references. Input cards may be
continued by using a “?” as the last char-
acter. Further information about skeleton
file format can be found in the references
at the end of this article.
SKELETON FILE PROCESSING
The input skeleton is read one record at
a time and scanned for control cards and
substitution processing. The right parenthesis
in the first column followed by a non-blank
character identifies a file tailoring control
statement, as shown in the examples below.
Control statements allow the user to do
the following:
1. Define alternate control character values
using the )DEFAULT control statement.
2. Conditionally process input statements
using the )SEL and )ENDSEL control
statements.
3. Include other files (with or without
substitution) using the )IM control
statement.
4. Set file tailoring variables using the
)SET control statement.
5. Use ISPF tables to substitute variables
during iterations using the )DOT and
)ENDDOT control statements.
 S Y S T E M S
6. Define Tab standard positions using the )TB control statement Figure 1: GDGGEN REXX EXEC
or alternate tab positions using the )TBA control statement.
/* rexx exec to delete/define MVS GDG */

7. Insert blank lines by using the )BLANKcontrol statement. /* arguments are */

/* The GDG name to be defined */
/* fully qualified, without quotes */
8. Allow commenting of the file skeleton using the )CM
/* The number of GDG generations to be */
control statement. /* kept at one time */
/* A flag to allow the dataset to be */
An invalid control statement will cause the file tailoring process /* edited rather than submitted */
/* Further IDCAMS CREATE GDG options */
to be aborted. Control statements, except for comments, are scanned /* see the IDCAMS manual for the */
for variable substitution. Statements not beginning with a ) followed /* syntax of the DEFINE GDG statement */
by a non-blank character are data statements. Data statements are arg GDGNAME GDGLIMIT SUBMIT OPTIONS
also scanned for variable substitution. We will only be doing
/* error if missing GDG name */
simple variable substitution and conditional input card processing. if (GDGNAME = ‘’) then do
For further information about the file tailoring process, consult the say “Missing GDG name”
resources listed. exit
end

CONTROL CHARACTERS /* Default of 20 generations if not */

File tailoring defines several control characters, all of which can /* specified */
be overridden using the )DEFAULT statement. For the purpose of if (GDGLIMIT = ‘’) then do
GDGLIMIT = 20
this article, we will assume the default characters are being used. end
Further information about overriding the control characters may be
found in the references. The ampersand (&) indicates the start of a /* verify GDG limit value */
if verify(GDGLIMIT,’0123456789’, ‘N’) \= 0 |,
variable name. Blanks, the cent sign, the not sign and <(+|&!*);- GDGLIMIT < 1 | GDGLIMIT > 255 then do
/,%_>:/’=” all delimit the end of a variable name. A period (.) say ‘GDG limit must be between 1 and 255’
following a variable causes the period not to be copied to the output, exit
just as in JCL. The exclamation point (!) serves as a tab character end

in the )TBA control statement (which we also not be covering). The /* see if the current dataset exists */
less than (<) and greater than (>) characters define a conditional /* if so set flag to include delete */
substitution string (which we will also not be covering). /* before define */
x = outtrap(“listcat.”); m = msg(‘off’)
Two consecutive control characters in the input record result in “listcat ent(‘“GDGNAME”’)”
one control character in the output record. The default control if listcat.0 \= 0 then do
characters are & ! < | >. This means that if you are using skeletons if listcat.1 = ‘GDG BASE ———’,
for JCL processing, all ampersands in the JCL must be replaced GDGNAME then
DEFINED = ‘YES’
with double ampersands. end
x = outtrap(“OFF”);m = msg(m)
THE SUBSTITUTION PROCESS
/* Look first in the current CLIST */
The substitution process used in file tailoring is almost exactly
/* dataset for skeletons */
like the process used in variable substitution used by JCL, including “ispexec libdef ispslib library id(sysproc)”
the use of ampersands and periods.
Every statement, except )CM statements, in the skeleton file is /* open the skeleton and output to */
/* temporary dataset */
scanned for the variable substitution start character, which defaults “ispexec ftopen temp”
to an ampersand. The characters following a variable start character
are interpreted as a variable name unless another ampersand follows, /* include and substitute the skeleton */
“ispexec ftincl GDGGENS”
which causes a single ampersand to be produced on the output
record. Variables are delimited on the right by blanks, the cent sign, /* close the output */
< ( + | & ! * ) ; ^ - / , % _ > : ‘ = and “. The variable is then looked “ispexec ftclose”
up, first in the local function pool, then in the shared variable pool,
/* after skeleton processing the ZTEMPF */
and finally the profile variable pool. After the variable’s value has /* shared variable contains the */
been determined, its value is substituted for the variable. Lines are /* temporary dataset name */
only scanned once for variable substitution. “ispexec vget (ztempf) shared”
ISPF supplies several useful built-in variables such as the USERID
/* if submit flag then just allow edit */
(ZUSER), current date (ZDATE), and time (ZTIME), which we will if (submit = ‘NO’) then
use in our example. File tailoring treats an ampersand blank combi- “ispexec edit dataset(‘“ztempf”’)”
nation as an invalid variable name. When a period is used to delimit a else /* submit the job */
“submit ‘“ztempf”’”
character string, the period is not copied to the output stream. In order
to have a period following a substitution variable in the output stream, exit 0 /* we are done
two periods must follow the variable in the input file skeleton.

©1999 Technical Enterprises, Inc. Reproduction of this document without permission is prohibited. January ‘99 TECHNICAL SUPPORT
S Y S T E M S
Figure 2: GDGGENS File Tailoring Skeleton
//&ZUSER.A JOB (ACCT,XXXX),’MAKE GDG’,
// CLASS=A,TIME=10,
// MSGCLASS=M,NOTIFY=&&SYSUID
//*******************************************
//* CREATE A GENERATION DATASET GROUP (GDG)
//* GENERATED BY &ZUSER ON &ZDATE AT &ZTIME
//*******************************************
//IDCAMS EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
)SEL &DEFINED = YES
/* DELETE &GDGNAME
DELETE (&GDGNAME) +
*/
GENERATIONDATAGROUP
SET MAXCC = 0
)ENDSEL
/* DEFINE THE GDG &GDGNAME */
/* WITH A LIMIT OF &GDGLIMIT GENERATIONS */
DEFINE GENERATIONDATAGROUP( +
NAME(&GDGNAME) +
LIMIT(&GDGLIMIT) +
&OPTIONS)
/*
CREATION OF THE JCL SKELETON
The easiest way to create a skeleton is to use an existing JCL
member and modify it:
1. First, replace the use of any & ! < | > characters with double
characters. File tailoring will replace any of these duplicate
sequences with their single character equivalent, unless the
control characters are overridden with a )DEFAULT statement.
This is very important in JCL. The common use of USERID=
&SYSUID, if unaltered, will produce USERID= because
&SYSUID has no value in ISPF.
2. Replace any existing parameters with substitution variables;
for example, USERID and dataset name.
3. Follow each substitute variable with a period if a character string
immediately follows the variable. For example, ‘&ZUSER.X’
would result in ABCDEX if your USERID was ABCDE. If
you wish to have a period following a substitution variable,
use two periods.
GENERATION DATASET GROUP DEFINITION EXAMPLE
Figure 1 shows a REXX EXEC and a skeleton file that will create
a job stream to define an MVS generation dataset group (GDG).
Although you can store the skeleton file anywhere, the example
expects the file-tailoring skeleton to be in the same dataset as the
REXX EXEC by using the ISPF LIBDEF service.
THE REXX EXEC
We start the REXX EXEC with a comment containing “REXX”
to differentiate the EXEC from a CLIST. We then comment the
arguments that are going to be passed to this EXEC. The ARG
statement parses the command line and assigns values to the
variables GDGNAME (the generation dataset group name),
GDGLIMIT (the maximum number of generations to be kept),
SUBMITS (a flag to inhibit automatic JCL submission), and
TECHNICAL SUPPORT January ‘99 ©1999 Technical Enterprises, Inc. Reproduction of this document without permission is prohibited.
OPTIONS (additional parameters for the DEFINE GDG statement).
These variables have the same names as those used for variable
substitution in the skeleton file, as all variables are retrieved from
the local function pool.
The GDG example shows that the file-tailoring
facility is fairly easy to use and understand.
The usual method of cloning JCL from other
individuals and modifying it to meet individual
requirements could easily be replaced with a
more maintainable method using file skeletons
and a small investment of time and effort.
We then do some simple argument verification. First, the GDG-
NAME is tested to ensure that it, at least, has been specified. Next,
the GDGLIMIT parameter is tested to ensure that it is a valid num-
ber and has a range between one and 255.
Next, the TSO LISTCAT command is used to query if the GDG-
NAME that was passed exists. We use the LISTCAT command
because the SYSDSN function will not produce the proper
information for GDG datasets. We first direct the output of TSO
commands to a stem variable LISTCAT. (which functions as an
array) by using the OUTTRAP function, and we then turn message
display off with the MSG function. Next, we issue the LISTCAT
TSO command. The OUTTRAP function we used puts the number
of lines of output into the variable LISTCAT.0 and the first line of
command output into LISTCAT.1. We then test the LISTCAT.1
variable for the proper output by displaying a GDG base. If we get
the expected output from the LISTCAT command, the GDG
already exists, and a flag is set to include a delete of the existing
GDG base before defining the new GDG. The delete step could be
included unconditionally, but it serves as a good example for
conditional file tailoring. More elaborate variable validation could
be done but would only obscure the example.
After variable verification a LIBDEF command is issued to have
the skeleton file(s) retrieved from the same PDS that the REXX
EXEC resides in. The skeleton need not reside in this library but
could have a library of its own.
The ISPEXEC FTOPEN function is invoked with the TEMP
option. This starts the file tailoring process and directs the output to
a temporary dataset. The file tailoring output could be directed to a
permanent file by allocating a file to the ISPFILE and using the
FTCLOSE NAME(member) option.
Next, the FTINCL GDGGENS command gets the GDGGENS
skeleton file and processes it into a temporary file. This is where
the variable substitution happens and when skeleton file errors
could occur. An FTCLOSE finalizes the dataset. We get the
ZTEMPF variable from the shared pool that contains the temporary
dataset name. We can then either edit the file-tailored dataset or
submit the file depending on the state of the submit flag. For
 S Y S T E M S
Figure 3: Output of Command GDGGEN MY.GDG 20 (SC28-1273-01) http://ppdbooks.pok.ibm.com/cgi-bin/bookmgr/
bookmgr.cmd/BOOKS/ISPDGD01/CCONTENTS
//BECKDENA JOB (ACCT,XXXX),’MAKE GDG’,
// CLASS=A,TIME=10,
// MSGCLASS=M,NOTIFY=&SYSUID OS/390 V1R3.0 ISPF Services Guide (SC28- 1272-01) http://ppd-
//********************************************
//* CREATE A GENERATION DATASET GROUP (GDG)
books.pok.ibm.com/cgi-bin/bookmgr/bookmgr.cmd/BOOKS/
//* GENERATED BY BECKDEN ON 99/01/01 AT 19:19 ISPSER01/CCONTENTS
//********************************************
//IDCAMS EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=* OS/390 V1R2.0 TSO/E REXX Reference (SC28-1975-00) http://ppd-
//SYSIN DD * b o o k s . p o k . i b m . c o m / c g i - b i n / b o o k m g r / b o o k m g r. c m d /
/* DELETE MY.GDG */
DELETE (MY.GDG) + BOOKS/IKJ3A300/CCONTENTS ts
GENERATIONDATAGROUP
/* DEFINE THE GDG MY.GDG */
/* WITH A LIMIT OF 20 GENERATIONS */
DEFINE GENERATIONDATAGROUP( +
NAME(MY.GDG) +
LIMIT(20) +
)
/*

debugging purposes, it is probably best to edit the output dataset NaSPA member Dennis Beck is a contract IBM systems programmer in the East Bay
rather than submit unconditionally. Area of San Francisco, Calif. He began his career 19 years ago as a 370 assembler
programmer, and has worked in a variety of industries including health care, retail,
THE SKELETON FILE wholesale, insurance, and at a software house. Currently, he has more than 11 years
The file GDGGENS shown in Figure 2 starts with a job card. as an IBM mainframe systems programmer in VTAM, NETVIEW, CICS, TCP/IP, and
Notice the use of the &ZUSER built-in variable to substitute the JES2. He can be reached at beckden@yahoo.com.
USERID into the JOBNAME. Also notice that the &SYSUID variable
has && preceding the JCL substitution variable so that one & will © 1999 Technical Enterprises, Inc. For reprints of this document
be copied to the output. contact editor@naspa.net.
We generate a JCL comment containing the user id, time, and
date of the file tailoring to give us some tracking. Notice how this
comment, which when following the normal method would
probably not be kept up to date, becomes easily maintainable when
using file tailoring. Also, if we go into an edit session after file
tailoring, we could save this JCL for the future and have a record
of when it was generated.
The )SEL command is used to conditionally include an
IDCAMS DELETE GENERATIONDATAGROUP depending on
the state of the &DEFINED variable. The &DEFINED variable
was set in the REXX EXEC if the GDG to be defined shows up in
a LISTCAT command.
Next, we create a comment in case we want to save the file
tailoring output. It is easy to be verbose when there is no possibility
of typing mistakes. Finally, we define the generation data group,
inserting the dataset name, the limit of generations to be kept and
any user-supplied options. Figure 3 shows the output of the file
skeleton process given the command “GDGGEN MY.GDG 20”;
note that if you are entering this from the command line, you must
prefix the command with “TSO”.

CONCLUSION
The GDG example shows that the file-tailoring facility is
fairly easy to use and understand. The usual method of cloning
JCL from other individuals and modifying it to meet individual
requirements could easily be replaced with a more maintain-
able method using file skeletons and a small investment of time
and effort.

REFERENCES
OS/390 V1R3.0 ISPF Dialog Developer’s Guide and Reference

www.naspa.net January ‘99 TECHNICAL SUPPORT