VSAM support in TSO, ISPF, REXX and CLIST

This document presents a quick overview of VSAM data set support available in the TSO, ISPF, REXX and CLIST environments of the MVS/ESA, OS/390 and z/OS operating systems. The most important element referenced in this document is BR which allows you to BROWSE a VSAM data set in the TSO/ISPF environment.

TSO

Most IDCAMS commands such as DELETE, DEFINE, ALTER, BLDINDEX and REPRO are also available as TSO commands. The syntax of TSO commands is the same as the syntax of the corresponding IDCAMS commands, although the rules for abbreviating key-words are somewhat different. Note that Dynamic Allocation may use different defaults in TSO and in batch; a cluster DEFINEd in TSO may be allocated on a different volume than if it had been DEFINED in an IDCAMS batch job.

Example of a DEFINE command for a KSDS, using system defaults for VOLUME, SPACE and RECSIZE:

 DEFINE CL(NAME(TEST.KSDS) KEYS(8 0))

Example of a DELETE command, using CLUSTER and NOPURGE default options:

 DELETE TEST.KSDS

The TSO/E ALLOCATE and FREE commands fully support VSAM. In particular, ALLOCATE provide the same capability to allocate a VSAM cluster as exists in the JCL; here is an example:

 ALLOC DS(TEST.KSDS) SHR 
 ALLOC DS(TEST.KSDS) RECORG(KS) LRECL(500) KEYLEN(8) NEW

The FREE command can be used to unallocate previously allocated VSAM data set; with the DELETE option, the FREE command is similar to DELETE:

 FREE DS(TEST.KSDS)  
 FREE DS(TEST.KSDS) DELETE

The following VSAM-related TSO commands are available on the CBT Tape.

REVIEW is a free TSO command currently maintained by Greg Price; REVIEW allows the user to display all sorts of data sets (including VSAM and SMF) in full-screen mode. The source code for REVIEW can be found in file 134 of the CBT Tape, and the load-module in file 135.
INITKSDS is a free TSO command written in assembler which initialises a newly-defined KSDS by writing a dummy record into it, then deleting it. INITKSDS is part of the author's contribution to the CBT Tape.

The TSO RENAME command does not support VSAM data sets. The ALTER command can be used to rename a CLUSTER, an AIX, or a PATH, and their DATA and INDEX components. RENAMECL is a REXX exec which can rename a CLUSTER and its DATA and INDEX components; the new names of the DATA and INDEX components are automatically calculated, as they are by the standard DEFINE CLUSTER command. For example, RENAMECL OLD.NAME NEW.NAME issues ALTER commands to rename the cluster to NEW.NAME, and its DATA and INDEX components to NEW.NAME.DATA and NEW.NAME.INDEX. When the new name is too long, new DATA and INDEX names are similar to what would result from a DEFINE CLUSTER command.

The TSO EDIT command does not support VSAM data sets.

ISPF

VSAM support in native ISPF is very limited; in particular, the EDIT, VIEW and BROWSE services do not support VSAM data sets. The VSAM Utilities (accessed via the 3.2.V option) is a multiple-panel ISPF dialog introduced in ISPF V4 which only supports the DELETE, DEFINE and LISTCAT commands. The Delete (D) function in other ISPF utility functions (such as option 3.2, Data Set Utility or option 3.4, Data Set List) do not support VSAM; however, the TSO command DELETE (DEL) can be used as a line command on a Data Set List (option 3.4 or 11) to delete a VSAM data set.

Free software provides additional VSAM support in ISPF; in particular, the author's contribution to the CBT Tape includes the following:

BR - a VSAM and BDAM browser
VSAMVIEW - a VSAM viewer
LC - a full-screen LISTCAT command

Two free VSAM browsers can be found in the Xephon Archives: VBROWSE and VSAM File Display.

Several vendors offer VSAM editors which also provide a Browse capability; the ones I know about are:

Note: Starting with ISPF 4.8 and OS/390 R8, the ISPF configuration table can specify the name of TSO commands that should be invoked to Browse, Edit or View VSAM data sets. How to make ISPF/PDF aware of the BR command is briefly described here.

REXX

The REXX language does not include any particular support for VSAM, and EXECIO does not support it. LISTDSI does not support VSAM either and only returns a minimal amount of information; for some reason, SMS information (which is not VSAM-specific) is not returned for a VSAM data set. Here are the variables set by rc = LISTDSI('IBMUSER.TESTKSDS' 'SMSINFO') in the TSO/E 2.6 environment:

	RC=4
	SYSDATACLASS=
	SYSDSNAME=IBMUSER.TESTKSDS
	SYSDSORG=VS
	SYSDSSMS=
	SYSMGMTCLASS=
	SYSMSGLVL1=IKJ58418I PARTIAL DATA SET INFORMATION NOT OBTAINED.
	SYSMSGLVL2=IKJ58412I VSAM DATA SETS ARE NOT SUPPORTED.
	SYSREASON=0012
	SYSSTORCLASS=
	SYSUNIT=3390
	SYSVOLUME=PRIM10

Using the REPRO command and a temporary non-VSAM data set, a REXX exec can use EXECIO to retrieve and update VSAM data, as shown in this example:

	"ALLOCATE DD(TEMPDD) NEW SPACE(1) TRACKS DSORG(PS) LRECL(4095) RECFM(V B)"
	"REPRO IDS(TESTKSDS) OFILE(TEMPDD) FROMKEY('98040') COUNT(1)"
	"EXECIO 1 DISKR TEMPDD"
	PULL Record
	"EXECIO 0 DISKR (FINIS"
	"FREE DD(TEMPDD)"
	  <process data in "record" variable>

By combining the PRINT command and the OUTTRAP function, a REXX exec can retrieve VSAM records into a stem variable, as shown in the following example:

	x=OUTTRAP('rec.')
	"PRINT IDS(TESTKSDS) FROMKEY('98040') COUNT(5) CHAR"
	x=OUTTRAP('off')
	DO i=1 to rec.0
	  IF LEFT(rec.i,13) \= 'KEY OF RECORD' THEN
	    SAY rec.i
	END

If REPRO and PRINT do not satisfy your VSAM access needs, you may use RXVSAM, a REXX function package that provides VSAM record-level functions. Here is a REXX code fragment that invokes RXVSAM to write a single record into an ESDS:

	"ALLOCATE FILE(VSAMDD) DSNAME('"dsn"') SHR"
	rc = RXVSAM('OPENOUTPUT','VSAMDD','ESDS')
	record = 'Record 1'
	rc = RXVSAM('WRITE','VSAMDD',,'record')
	rxvsam_result = RXVSAM('CLOSE','VSAMDD')

Several RXVSAM programs are available, all of them are free:

Written and supported by Mark Winges, in file 268 of the CBT Tape.
Written and supported by Steven Scott, found here.
There is a read-only VSAM function package, also called RXVSAM, in the VSAM section of the Xephon archives.

The EXECIOVS program, found on the HiLMAs web site, provides an EXECIO-like interface to VSAM data sets in REXX.

Several vendor products contain a VSAM function package for the REXX environment; the ones I know about are:

MAX/REXX (MAX Software, now CA)
REXX Language eXtensions - RLX (Relational Architects)
REXXTOOLS (Open Software Technologies)
IBM File Manager For z/OS VX and XV REXX Functions

The STEMEDIT program can be invoked in REXX to display stems using the BROWSE, EDIT or VIEW services of ISPF/PDF. STEMEDIT and several REXX execs which use it are distributed in FILE 183. The following REXX execs can be used to issue LISTCAT and PRINT commands under ISPF/PDF :

LC - LISTCAT
VP - VSAM PRINT

CLIST

The CLIST language does not include any particular support for VSAM; in particular, the CLIST file I/O facility (OPENFILE, READFILE, etc) does not support VSAM data sets. However, like a REXX exec, a CLIST can use the REPRO or PRINT commands to load VSAM records into variables; see examples in the REXX section, above.

&SYSDSN works fine with a VSAM data set, but LISTDSI suffers the same lack of VSAM support as REXX (see above).

SuperC

Starting with ISPF 4.8 and OS/390 V2R8, the SuperC utility (ISRSUPC) supports VSAM data sets.

Check the CBT Tape and the VSAM section of the Xephon Update archives for more free software for the TSO environment.

Search key-words: IBM MVS OS/390 OS390 z/OS zOS TSO SPF ISPF PDF VSAM editor VSAM browser VSAM viewer CLIST REXX EDIT BROWSE VIEW RXVSAM dataset datasets browsing viewing editing files filemarvel