SVC 26
and
What It Can Do
Peter Sawyer
National Advanced Systems
MVS SCP Project
Session O327
March 3, 1989
Table of Contents
Overview and Disclaimer. . . . . . . . . . . . . . . . . . . . 1
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2
The OS/360 Catalog. . . . . . . . . . . . . . . . . . . . 3
CAMLST functions. . . . . . . . . . . . . . . . . . . . . 4
OS Catalogs in MVS (with SU8) . . . . . . . . . . . . . . 5
VSAM Catalogs (including ICF) . . . . . . . . . . . . . . 5
The Catalog Parameter List (CTGPL) . . . . . . . . . . . . . . 6
The Catalog Field Vector Table (CTGFV) . . . . . . . . . . . . 8
The Catalog Field List (CTGFL) . . . . . . . . . . . . . . . . 10
CTGFL Dictionary of Names for Define. . . . . . . . . . . 11
The DELETE Function. . . . . . . . . . . . . . . . . . . . . . 12
EXPORT DISCONNECT . . . . . . . . . . . . . . . . . . . . 12
Information Retrieval - VSAM LOCATE. . . . . . . . . . . . . . 13
SUPERLOCATE. . . . . . . . . . . . . . . . . . . . . . . . . . 14
GENERIC LOCATE . . . . . . . . . . . . . . . . . . . . . . . . 15
LSPACE - Available Space Report. . . . . . . . . . . . . . . . 16
Creating Catalog Entries - The DEFINE Function . . . . . . . . 17
DEFINE NONVSAM. . . . . . . . . . . . . . . . . . . . . . 17
IMPORT CONNECT . . . . . . . . . . . . . . . . . . . 17
DEFINE GENERATIONDATAGROUP. . . . . . . . . . . . . . . . 18
DEFINE CLUSTER/ALTERNATEINDEX . . . . . . . . . . . . . . 18
DEFINE PATH . . . . . . . . . . . . . . . . . . . . . . . 20
DEFINE ALIAS. . . . . . . . . . . . . . . . . . . . . . . 20
DEFINE SPACE. . . . . . . . . . . . . . . . . . . . . . . 21
Modifying Catalog Information - ALTER. . . . . . . . . . . . . 22
DIAGNOSTIC TIPS & HOW TO LEARN MORE. . . . . . . . . . . . . . 23
Testing AMS Under TSO . . . . . . . . . . . . . . . . . . 23
Testing AMS In The Background . . . . . . . . . . . . . . 23
Data Area Descriptions . . . . . . . . . . . . . . . . . . . . 25
CTGPL . . . . . . . . . . . . . . . . . . . . . . . . . . 26
CTGFV . . . . . . . . . . . . . . . . . . . . . . . . . . 29
CTGFL . . . . . . . . . . . . . . . . . . . . . . . . . . 31
CTGWA . . . . . . . . . . . . . . . . . . . . . . . . . . 32
CTGVL . . . . . . . . . . . . . . . . . . . . . . . . . . 33
CTGCV . . . . . . . . . . . . . . . . . . . . . . . . . . 34
AMDSB . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Overview and Disclaimer
This is a discussion of the SVC 26 interface in MVS. It includes
support for ICF catalogs where appropriate, as well as a
description of the CVOL processor support. Except as noted, all
references to VSAM catalogs include ICF catalogs as well.
The intended audience is an experienced system programmer, with a
working knowledge of Catalog Management externals, including Access
Method Services. This is not a tutorial on catalog management, but
a detailed exploration of the internals.
The information is based upon personal observation, test cases,
tracing, fiche reading, etcetera. It is not exhaustive, and has
not been subjected to any formal testing by the author.
Nonetheless, the author believes it to be correct and useful. In
no circumstances will the author be liable for any damages arising
from its use.
Introduction
The catalog function, like much of MVS, has its origins in the
original design of OS/360. It has been enhanced several times
since. The first version was limited to associating a list of
volumes with a dataset name. This was adequate for the needs of
OS. The information was stored in a DASD dataset named SYSCTLG on
the system residence volume, in a tree structure based on index
levels in the dataset name. One of the first improvements was the
ability to have more than one SYSCTLG, and to chain them together.
The search would still begin on sysres, but the first level could
be a pointer to another volume, known as a Control Volume Pointer
Entry (CVPE). The CVPE had the serial number of the volume to be
searched. Alternatively, the caller could provide the serial
number of the Control Volume in the CAMLST. It is interesting to
note that the OS/360 term "Control Volume" (CVOL for short) refers
to the volume containing the SYSCTLG dataset, and not the dataset
itself. Hereafter, we will use the vernacular CVOL to refer to a
SYSCTLG dataset. Other changes were made to improve the OS catalog
over time. The CAMLST functions were documented externally in a
manual, the last version of which was titled "Data Management for
System Programmers."
The first major change was the introduction of VSAM as part of
OS/VS1 and OS/VS2 SVS. Both of these systems retained the OS
catalog structure intact, but added a parallel structure for VSAM.
A new format of request was defined for SVC 26, used for VSAM
requests. IBM did not document this new interface, claiming that
to do so would impair their ability to make changes to it. The
author believes that perhaps the real reason is that the new
interface is so clumsy and awkward they sought to avoid public
ridicule by concealing the mess. One day, history will judge this.
At any rate, the need for documentation does not diminish, hence
this work.
With the introduction of MVS, the two parallel catalog structures
were combined in what was, at best, a shotgun marriage. All
searches would begin with the VSAM master catalog. From there, the
high level qualifier could redirect the activity to either a VSAM
usercatalog, or to an OS catalog. The use of an alternate
usercatalog was possible either by specifying the catalog as a
parameter to SVC 26, or through the use of STEPCAT. There was no
way to select a CVOL other than the one connected via the master
catalog. Neither was there support for generation data groups
(GDGs) in CVOL catalogs. There was a new layer of software
introduced, known as the catalog controller. The controller became
the first load of SVC 26, and translated CAMLST format requests
into VSAM Catalog Parameter Lists (CTGPLs). If later processing
determined that the target catalog was indeed a CVOL catalog, then
the CTGPL was translated to a CAMLST, and the CVOL processor
called. After CVOL processing, the CAMLST was again translated to
CTGPL format if required.
The VSAM catalog (prior to ICF) was less than perfect, and users
demanded full OS catalog support in MVS. They got it in MVS 3.7
with SU8. SU8 reinstated all the code for CVOL functions that had
been in SVS. Now, the catalog controller had to recognize CAMLST
requests which specified a CVOL, and pass them directly to the CVOL
processor untranslated. The possibility still existed for all of
the translations described above as well.
The latest major change was the introduction of ICF catalogs in the
ill fated Data Facility/Extended Function product. DF/EF had severe
reliability problems in its early life. It has since been
superseded by the Data Facility Product (DFP). There now were
three catalog types: OS CVOL, VSAM catalog, and ICF catalog.
Fortunately the parameter lists for VSAM and ICF catalogs are
compatible with minor exceptions, so the mapping functions of the
catalog controller are not changed.
Our purpose here is to understand the CTGPL format of request, and
how it applies to the various catalog types. First, however, a
brief chat about CVOL functions.
The OS/360 Catalog
The original catalog was a BSAM type dataset with 256 byte records
having 8 byte hardware keys. This is the same format as the
directory for a partitioned data set, and in OS some of the code
was shared. BLDL was branch entered to search catalogs, and
catalog management was entered (via SVC 28) to format PDS
directories. Enough esoteric trivia.
For a seemingly simple function, the internal complexity is
surprising. If you think this is bad, just wait until I get to
VSAM.
There were 10 types of entries in the catalog:
AE Alias entry, provides a substitute high qualifier
CVPE CVOL pointer entry, points to another OS catalog
DSPE Dataset pointer entry (five or less volumes)
GIPE Generation index pointer entry (GDG base)
ICE Index control entry, an intermediate tree node
ILE Index link entry, to chain to another ICE
IPE Index pointer entry, points to the ICE at the next
lower level
VCB Volume Control Block, holds up to 20 volumes
VCBPE Volume Control Block pointer entry (more than 5
volumes)
VICE Volume index control entry, first block of SYSCTLG
All requests were made with the CAMLST format. On entry to SVC 26,
register 1 contains the address of the CAMLST, which is 3 to 5
words in length. The first word of the CAMLST is a group of flags
and control fields to identify the request. Bit 23 of this word is
always zero to identify CAMLST format. The next two to four words
are pointers to data. In general, word two points to the dataset
or index name, and word three is zero or the address of the CVOL
specification. Word four points to a second name, volume
information, or a work area for LOCATE. Word five is used only
when a DSCB pointer is passed for a single volume dataset.
There were 14 CAMLST functions available:
BLDA Build an alias for a high level index
BLDG Build a generation index
BLDX Build index (other than a GDG index)
BLOCK LOCATE by TTR
CAT Catalog a dataset when index levels exist
CATBX Catalog a dataset creating required index levels
DLTA Delete an alias for a high level index
DLTX Delete an index (index must be empty)
DRPX Disconnect control volumes
LNKX Connect two control volumes
NAME LOCATE by name
RECAT Recatalog a dataset
UCATDX Uncatalog and remove empty index levels
UNCAT Uncatalog and retain index levels
Word one of the CAMLST indicated the function as follows:
BLDA ..00 0.0. .001 0000 0... ...0 .... .... 0010 0000
BLDG ..00 0.0. .010 0000 0... ...0 .... .... 0020 0000
BLDX ..00 0.0. .100 0000 0... ...0 .... .... 0040 0000
BLOCK ..00 0.1. .000 0000 0... ...0 .... .... 0200 0000
CAT ..10 0.0. .000 0000 0... ...0 .... .... 2000 0000
CATBX ..10 0.0. .100 0000 0... ...0 .... .... 2040 0000
DLTA ..00 0.0. .000 0001 0... ...0 .... .... 0001 0000
DLTX ..00 0.0. .000 0100 0... ...0 .... .... 0004 0000
DRPX ..00 0.0. .000 0000 1... ...0 .... .... 0000 8000
LNKX ..00 0.0. .000 1000 0... ...0 .... .... 0008 0000
NAME ..00 0.0. .000 0000 0... ...0 .... .... 0000 0000
RECAT ..01 0.0. .000 0000 0... ...0 .... .... 1000 0000
UCATDX ..00 1.0. .000 0100 0... ...0 .... .... 0804 0000
UNCAT ..00 1.0. .000 0000 0... ...0 .... .... 0800 0000
Bit 0 is set on if the user has specified a CVOL. Naturally, BLOCK
is not meaningful without a CVOL specification. In this case word
three is the address of the CVOL serial number. Bits 1 and 5 are
not used by SVC 26, but the CAMLST macro always generates them as
one. This makes locate by name appear as 44000000, for example.
OS Catalogs in MVS (with SU8)
MVS changes the rules for OS catalogs slightly. Index levels are
always handled automatically in MVS, so that CAT and UNCAT are
treated as CATBX and UCATDX respectively. BLDX is supported, but
is redundant, and DLTX is needed only for a GDG. Requests which
are meaningful only in a CVOL are accepted only if the required
CVOL is specified. This affects BLDA, BLOCK, DLTA, DRPX and LNKX.
Any request requiring a specific OS catalog is passed to the CVOL
processor (IGG0CLCA) unchanged. Others are mapped to equivalent
VSAM requests, and passed to the VSAM catalog processor (IGG0CLA1).
If later processing determines that a CTGPL request is directed to
an OS catalog, then most requests are rejected as not supported.
The ones that can be handled are VSAM LOCATE, SUPERLOCATE, Generic
LOCATE, and DELETE.
It is a peculiarity that a CAMLST CATBX can be handled by any
catalog, but the analogous DEFINE NONVSAM is rejected by the CVOL
processor. Furthermore, when working with GDGs, the request must
match the catalog type. There is no remapping for BLDG/DLTX, or
for DEFINE/DELETE GDG.
VSAM Catalogs (including ICF)
The primary support for these catalogs is via the VSAM catalog
parameter list (CTGPL). This is the undocumented interface, used
primarily between Access Method Services (AMS) and the catalog
management component. All requests are issued in the form of an
SVC 26. This interface is much more complex than the CAMLST
interface.
There are basically only four functions from the user's point of
view. DEFINE is used to create catalog entries, DELETE to remove
them, ALTER to change them, and LOCATE to read them.
There are several flavors of retrieval requests. The obvious one
is SUPERLOCATE, which is used by the scheduler to retrieve catalog
information about a specific entity. For some unknown reason,
SUPERLOCATE is restricted to authorized programs only. VSAM LOCATE
extracts selected fields from a catalog entry. LSPACE returns
space information. Generic LOCATE returns a list of dataset names,
but if you want to know what volumes they are on, you must do
individual calls for that. Authorized callers would use
SUPERLOCATE, but mere mortals must use the more clumsy VSAM LOCATE.
LISTCAT can also be used to read sequentially through a catalog.
Other functions, which are beyond the scope of this document,
include UPDATE, used by VSAM to maintain descriptive information,
and CONVERTV, used only with MSS. With MVS/XATM DFP Version 2,
there are additional functions for communication with the catalog
address space, and there is something new in XA DFP 2.3 called GFL
about which nothing is yet known.
The Catalog Parameter List (CTGPL)
For all VSAM requests, register 1 at entry to SVC 26 holds the
address of the CTGPL. At present, the CTGPL and all data areas
pointed to it are required to reside below the 16Mb line, however
all the pointers are fullwords, and the high order bytes must
always be zero. IEZCTGPL is the mapping for the CTGPL.
The CTGPL is distinguished from a CAMLST by bit 23 of the first
word (CTGAM0) being on. The CTGPL has a base portion 28 bytes
long, and may have additional 4-byte pointers at the end for
certain functions. The basic function is identified in the high-
order three bits of byte 2 of the parameter list (this is the same
byte (CTGOPTN3) that contains CTGAM0). A value of B'100' means
catalog management services (CMS) request. For a CMS request, the
high order five bits of CTGDSORG indicate the specific request.
To clear some of the fog, consider this table:
Function CTGOPTN3 CTGDSORG
SUPERLOCATE 000 n/a with CTGSUPLT set on
GENERIC LOCATE 000 n/a with CTGSUPLT & CTGGENLD on
LOCATE 001 n/a
LSPACE 010 n/a
UPDATE 011 n/a
DEFINE 100 00001
ALTER 100 00010
DELETE 100 00011
LISTCAT 100 00100
CONVERTV 100 00110
GFL 101 n/a
Most functions require a work area to be provided by the caller.
Even if none is required, it does no harm to provide one. The word
CTGWKA in the CTGPL points to the work area. Except for
SUPERLOCATE, the first halfword is the length of the workarea,
including the halfword itself. The second halfword contains the
number of bytes of the workarea actually in use, and should
normally be initialized to zero. On return, the content is the
number of bytes used, including the header. The workarea itself
should also be cleared to zeros, although it is not clear what the
effect of not doing so would be. Catalog management uses the work
area to return information to the caller. For DEFINE, generated
fields such as component names are built here. For SUPERLOCATE,
the workarea is special, and is described later.
DFP levels of catalog management will also accept a "Format-2"
workarea, in which the two fields at the beginning are fullwords
rather than halfwords, permitting a work area of more than 32K.
Such a work area is used only for a generic locate. In a format-2
workarea, the second header field includes the length of the
header, so it must be initialized to 8. Use of a Format-2 work
area is indicated by setting bit CTGF2WKA on in CTGDSORG.
In the event that the workarea is too small, catalog management
will return the required size in the second header field, and give
return code 40. This enables the caller to obtain a sufficient
work area, and retry. If the return code is 44-8 then the caller
supplied a format-1 workarea, but more than 64K is required (this
can only happen on a generic locate).
The CTGPL contains an optional pointer to specify which catalog to
use. This word (CTGCAT) can be the address of a pointer to the
catalog's ACB if CTGCNAME=0, or the 44-byte catalog name if
CTGCNAME=1.
There are several useful flags which modify processing. They
include:
CTGBYPSS Bypass security checking (key 0 or supervisor state
only)
CTGDOCAT Do not open or allocate the needed catalog
CTGSRH Search only the master catalog
CTGTIOT Caller owns SYSZTIOT exclusive (authorized callers)
If catalog management finds fault with the request, a return code
is given in register 15. Note that a branch table cannot be used,
as the return code may not be divisible by four. There will be a
reason code stored in the halfword CTGFDBK, and the last 2
characters of the detecting catalog management module will be
stored at CTGMODID. For a list of return and reason codes, refer
to the description of message IDC3009I in the System Messages
manual for MVS.
If the request was processed in an ICF catalog, the bit CTGICFC
will be turned on by the system to indicate this to the caller.
The Catalog Field Vector Table (CTGFV)
This data area is used only with the DEFINE and ALTER functions.
If you are reading this for the first time, skip this until you
understand the simpler stuff, and then come back.
The CTGFV is the basic unit for describing to catalog management
the form of an entity to be created in a VSAM or ICF catalog. It
is mapped by IEZCTGFV. The CTGFV for the principal entity (eg.
cluster) is pointed to by the CTGPL field CTGFVT. Additional
CTGFVs (if required) are chained from the first one.
The Field Vector Table is always 100 (X'64') bytes long. Byte zero
is the type code for the entity being described (eg. "B" for a GDG
base). Bytes one and three are option flags. Byte two is not
understood by the author. The following 24 fullwords are pointers.
Not all of these pointers will be used at one time. Indeed, it is
valid to have a CTGFV with a type code of "V" followed by 99 bytes
of zeros!
Most of the pointers contain addresses of Catalog Field Lists
(CTGFLs). Don't panic yet, we'll describe them shortly. Others
point directly to the data itself. At this time, we will look at
a few key pointers only.
CTGFVENT contains the address of the 44-byte component name, or
zero. If zeros are passed when defining a Data, Index, or Space
component, then catalog management will generate a name, place the
name in the catalog workarea, and place the address in CTGFVENT.
Generated names in the workarea are actually 45 bytes, with the
first byte being the type code, and the address in CTGFVENT being
that of the second byte. Other types (cluster, nonvsam, etc),
always require that a name be provided.
Data and index components are always associated with a cluster (or
alternateindex) record. The CTGFV for these components are pointed
to by the fields CTGFVDCH and CTGFVICH of the primary entity during
define.
Space (type "V") is meaningful only for old style VSAM catalogs.
ICF catalogs do not use this entity type. Space may be requested
alone, as in DEFINE SPACE, in which case the primary CTGFV is type
V and is the only one. Space may also be requested as part of
another request, such as DEFINE UCAT or DEFINE CLUSTER UNIQUE, in
which case the type "V" CTGFV is chained from the primary CTGFV via
field CTGFVVCH. When the SPACE CTGFV is secondary, it is provided
as a feedback area only, and should be binary zeros except for the
type code. CTGFVVCH is ignored when processing in an ICF catalog.
When creating any entity except space (V), optional ownerid,
creation date and expiry date CTGFLs may be provided via CTGFVOWN,
CTGFVCRE, and CTGFVEXP, respectively. AMS always provides a create
date, but it is not required. Curiously, on TSO AMS provides the
users dataset prefix (not his userid) as the default ownerid.
As a graphic illustration of the worst case CTGFV structure
(defining a unique KSDS), observe:
CTGPL
+----------+
| |
| | CTGFV
+----------+ +---------------+ +-------------+
| CTGFVT |------>| C3 00 00 00 | +-------->| "D" CTGFV |
+----------+ +---------------+ | | |
| | | CTGFVDCH |--------+ | |
| . . . | +---------------+ +-------------+
| | | CTGFVICH |--------------> | "I" CTGFV |
+----------+ +---------------+ | |
| CTGFVVCH |-----+ | |
+---------------+ | +-------------+
| | +----> | "V" CTGFV |
| . . . | | |
| | | |
+---------------+ | . . . |
| |
+-------------+
Remember that the "C", "D" and "I" field vectors also point to
other data, including catalog field lists.
The Catalog Field List (CTGFL)
The Catalog Field List (CTGFL) consists of a 16-byte fixed portion,
and zero or more 8-byte variable fields. The CTGFL is mapped by
IEZCTGFL. This data area is used with retrieval functions, update,
and with DEFINE and ALTER. The format is similar, but differs.
When used with DEFINE or ALTER, the CTGFL is pointed to by one of
the fields in a CTGFV. The type of data must be consistent with
the pointer used. For this usage, CTGFLDNO will be one (or zero,
to explicitly omit a field). CTGFLDNM will point to an 8-byte
EBCDIC field name (see dictionary below). Other header fields will
be zero. The data pointer pair (CTGFLDAT) describes the data
pointed to. CTGFLNG has the length, which must match the defined
length for the field (eg. 7 bytes for space), and CTGFLPT has the
address of the actual data.
When used for UPDATE or information retrieval, the CTGPL points to
the CTGFL, which describes the field to be retrieved. CTGNOFLD
(when nonzero) indicates the number of fullword CTGFL pointers
which are found beginning at CTGFIELD (CTGPL offset X'1C'). When
used in this manner, the field name is the only indication of the
type of data being referred to.
For selective retrieval, the CTGFLCHN field in the retrieval CTGFL
points to another CTGFL (a "TEST" CTGFL) which describes the test.
It is through the use of this type of CTGFL that selective LISTCAT
by entity type is implemented. In this case, there may be more than
one length/address pair describing alternative values. In
addition, CTGFLDCD will contain a code indicating what type of
result is required (eg. equal, less than, etc.) The CTGFLCHN field
may chain a series of TEST CTGFLs together, in which case retrieval
proceeds if any test is successful.
The length and address pair point to the data retrieved for LISTCAT
or LOCATE, to the new data for ALTER, DEFINE or UPDATE, and to
comparison data in a test CTGFL.
For example, this diagram illustrates the CTGFL used by DEFINE for
a space request of CYLINDERS(5,3):
+----------------+
+0 | 01 00 00 00 | +---> C'SPACPARM'
+----------------+ |
| 0 | |
+----------------+ |
| CTGFLDNM |-----+
+----------------+ =---> X'000005,000003,C0'
| 0 | |
+----------------+ |
+10 | 00 00 00 07 | |
+----------------+ |
| CTGFLPT |--------------+
+----------------+
CTGFL Dictionary of Names for Define
Anchor
Name Length Description CTGFV---
Types
PASSWALL 52+ Security fields STY
CDGIR
OWNERID 8 Owner identification OWN
ABCDGIR
DSETEXDT 3 Expiration date EXP
ABCDGIR
DSETCRDT 3 Creation date CRE
ABCDGIR
DEVTYP 12 Device Type (left justified EBCDIC) DVT
A
SPACPARM 7 Space quantity and format SPC
CDGIV
AMDSBCAT 96 Copy of the AMDSB control block AMD
DI
FILESEQ 2 File Sequence FSN
A
DSATTR 2 Cluster attributes ATR
DI
BUFSIZE 4 Buffer size BUF
D
LRECL 4 Average record length LRS
D
RGATTR 1 Path/Alternate Index attribute UPG
GR
The DELETE Function
We will examine the DELETE function first. This is because it is
relatively simple, and provides a good way to get our feet wet.
DELETE requires a 28-byte CTGPL, with the function codes in
CTGOPTN3 and CTGDSORG being 100 and 00011 respectively. CTGENT must
point to the 44-byte name of the entity to be deleted, and CTGNAME
in CTGOPTN1 must be on to indicate use of a name rather than an
RBA. To restrict the operation to s specific entity type, insert
the type code (eg. "P" for pagespace) in CTGTYPE, otherwise leave
CTGTYPE binary zero. Set CTGSCR on unless you want NOSCRATCH.
Despite the name, EXPORT DISCONNECT is a form of DELETE. CTGDISC
should be turned on to signal export disconnect (as opposed to
delete usercatalog), and the type in CTGTYP should be "U" for
usercat.
That's it for a basic DELETE. Options which may be specified
include:
CTGPURG To ignore the expiry date of the entity
CTGERASE To overwrite the object with zeros on deletion
CTGDELRC Specifies the RECOVERY option for deleting a BCS
CTGOVRID To override the ERASE attribute in the catalog
CTGSCR Set OFF (0) for NOSCRATCH
DELETE SPACE is funny. For a delete space, the catalog owning the
volume must be specified via CTGCAT (unless it is the master
catalog), and CTGENT points to the six character volume serial
followed by 38 bytes of binary zeros.
Information Retrieval - VSAM LOCATE
We now examine the VSAM LOCATE request. Unlike the CAMLST LOCATE,
which returns a complete record, VSAM LOCATE retrieves fields from
within the record. This isolates the caller from the actual record
format, but he must still be aware of the format of individual
fields and groups of fields.
VSAM LOCATE requires a work area large enough to hold the record
being read. AMS seems happy with 1024 bytes. The CTGPL will have
function code 001, and should have CTGBOTH set on. CTGENT points
to the 44-byte name, and CTGNAME is on to so indicate. The list of
CTGFL pointers begins at CTGFIELD, and the number of them is stored
in CTGNOFLD.
For each field wanted, a CTGFL must be built, with one
length/address pair. The name pointed to by CTGFLDNM indicates
what data is wanted. Catalog management will place the data in the
workarea, and insert the length and address into the CTGFL.
The dictionary of fields is voluminous, and is not included here.
See Catalog Management Logic manual for a list, or refer to the
microfiche for IGG0CLAY. Some of the "fields" are in fact derived
information not residing in the catalog, for example, the catalog
ACB address.
Most information can be had without any problems, but to receive
security information you must either (1) be authorized and not turn
on a "check password" bit, or (2) supply the master password by
pointing CTGPSWD to it.
Actually, the whole record will likely be put in the workarea
(minus passwords in most cases), but it would be unwise to depend
on that.
SUPERLOCATE
SUPERLOCATE was designed for use by device allocation (the
scheduler subcomponent), and is restricted to authorized callers.
You must provide a 28-byte CTGPL, with the function code in
CTGOPTN3 being 000. CTGNAME and CTGSUPLT must be turned on.
A special form of workarea is required for SUPERLOCATE. CTGWKA
points to the 16-byte area, called the Catalog Work Area (CTGWA),
and mapped by IEZCTGWA. The CTGWA in turn points to the variable
length work area where volume information is returned.
The CTGWA should be zero, except for two fields. CTGWAVL points to
the area for the volume list, and CTGWALV holds the length. The
system will return the actual number of volumes in CTGWAVCT.
Returned information is scattered across three places. In the
CTGPL, there are flags returned in CTGFDBK, and organization
information is in CTGDSORG (it is only meaningful in terms of VSAM
versus nonVSAM). Bit CTGGDGB will be on if a GDG base was located.
In the CTGWA, the number of volumes will be returned in CTGWAVCT,
and the minimum number of concurrent volumes required will be
returned in CTGWAUCT. If CTGGDGB is on, then CTGWAGCT contains the
number of generations catalogued. A generation number is returned
in CTGWAGB, if CTGGDGL was on the original CTGPL.
Volume information is returned in the area pointed to by CTGWAVL.
Each volume occupies 12 bytes. Warning to CAMLST users: The
format is different for superlocate. The order of the data
returned from superlocate is Volume Serial, Device Type code, and
File Sequence (IEZCTGVL maps the volume list). For a single volume
dasd dataset, the TTR of the format-1 DSCB is returned in bytes
12-15, otherwise zeros appear in those bytes. For a multivolume
dataset, the three fields are repeated as many times as indicated
in CTGWAVCT.
An insufficient size of volume area will result in a return code 40
with the required size returned in CTGFDBK.
GENERIC LOCATE
GENERIC LOCATE is a form of SUPERLOCATE, but does not require
authorization. It requires a 28-byte CTGPL, with the function code
in CTGOPTN3 being 000. You must turn on CTGNAME, CTGSUPLT, and
CTGGENLD to further define the function. CTGENT points to the 44-
byte name of the entity to be located.
A large work area is typically required. Catalog information is
returned here, and 45 bytes are required for each entry.
Input to the function is provided by CTGENT. This field points to
a 1-byte length, followed by a variable length character string
(maximum 43 characters). Generic locate will find all catalog
entries matching the partial name. A period at the end of the
string is your responsibility, if needed. If the string has no
periods at all, then the master catalog is implied, otherwise the
first qualifier implies the catalog in the usual way. For example,
to find all datasets whose first qualifier is DEPT27, you would
provide AL1(7),C'DEPT27.' (if you omit the period, you get entries
from the mastercat, including the alias DEPT27.)
Information is returned in the workarea, beginning at the first
available byte after the header. If there is already data in the
workarea, then the new data is added to the existing data. The
second header field contains the number of bytes returned, which is
45 times the number of names (plus the length of the header, either
4 or 8). Each name consists of a 1-byte type code followed by a
44-byte component name. If more information is required, then you
must make another call, using VSAM LOCATE, SUPERLOCATE, or OS
LOCATE to get it.
Optionally, flag bit CTGRCATN may be turned on to have the name of
the catalog returned as well. If this is done, then the first name
in the workarea will be the name of the catalog from which the
other information was retrieved. The type code byte for the
catalog name will be '0' (X'F0').
An catalog may be specified by pointing CTGCAT at its name, and
turning on CTGCNAME, in which case only that catalog will be
searched.
LSPACE - Available Space Report
The LSPACE function is used only with old style VSAM catalogs. It
is not applicable to ICF (you get a rude return code). LSPACE
searches the data spaces on a volume, and reports on the free space
within them, in a manner similar to the DADSM LSPACE function
provided by SVC 78.
When LSPACE is invoked, the catalog owning the volume must be
specified via CTGCAT (unless it is the master catalog), and CTGENT
points to the six character volume serial followed by 38 bytes of
binary zeros.
LSPACE will return a 30 byte character string of the form
"SPACE=CCCC,TTTT,AAAA/cccc,tttt" in the caller's work area,
describing free VSAM suballocate space on the volume. If the
CTGSMF bit is on, an SMF 69 record is also written
Creating Catalog Entries - The DEFINE Function
Now, let us look at DEFINE. This is quite complex, and requires
that we use the Catalog Field Vector (CTGFV) and Catalog Field List
(CTGFL). If you have not already read the descriptions of those
data areas, do so now before continuing.
DEFINE is used to create one or more entities in the catalog. Even
if the type is nonVSAM, the request can be processed only in a VSAM
catalog.
DEFINE requires a 28-byte CTGPL, with the function codes in
CTGOPTN3 and CTGDSORG being 100 and 00001 respectively. CTGNAME in
CTGOPTN1 must be on to indicate use of a name rather than an RBA.
A work area is mandatory, and a size of 512 bytes is sufficient for
all known requests. The address of the primary CTGFV must be
placed in CTGFVT.
The primary CTGFV will contain the type of entity being defined in
CTGFVTYP, which will be one of:
A nonVSAM entity
B generation data group (GDG) base
C cluster, pagespace, usercatalog, or mastercatalog
G alternate index
R path
V space (ie, DEFINE SPACE for VSAM suballocation)
X alias (either nonVSAM or catalog)
In addition, the field CTGFVENT will have the address of the name
for all types except space (V). If the entity being created is a
pagespace or catalog, then CTGTYPE in the CTGPL is set to "P" or
"U", while CTGFVTYP is "C". Otherwise, CTGTYPE is binary zeros.
For compatibility, SVC26 will accept a value of "M" in CTGTYPE and
will treat it as "U".
Cluster, alternate index, catalog and pagespace requests are quite
similar. We will examine the various types in turn.
DEFINE NONVSAM
The creation of an "alien" (A) record requires a single CTGFV.
CTGFVENT points to the name of the data set. The device type is
passed in EBCDIC using a CTGFL anchored at CTGFVDVT. The volume
list is pointed to directly by CTGFVVLT. It consists of a halfword
length, followed by a series of 8-byte entries. Each entry
consists of two bytes of binary zeros, followed by the six
character volume serial number. The length field does not include
itself, eg. for one volume: H'8',XL2'0',CL6'VOL001'. Optionally
a file sequence number CTGFL may be provided via CTGFVFSN. Also
optionally, CTGFVTTR may point to a 3-byte TTR of the format-1
DSCB.
Believe it or not, the connection of a usercatalog, known as IMPORT
CONNECT, is a form of DEFINE NONVSAM. The parameters are set up as
described, with a type "A" CTGFV. CTGFVENT, CTGFVVLT and CTGFVDVT
are the only fields used, and CTGTYP (in the CTGPL) must be "U" to
indicate a catalog. No workarea is needed. Nothing in the catalog
connector record indicates whether the catalog is an ICF catalog.
DEFINE GENERATIONDATAGROUP
Like nonVSAM, creation of a GDG base (B) requires a single CTGFV.
CTGFVENT points to the name of the object. A work area of 256
bytes is adequate. GTFFVLMT points to the one byte binary limit
value. CTGFVGAT points to an attribute byte, where bit 0 means
EMPTY and bit 1 means SCRATCH.
DEFINE CLUSTER/ALTERNATEINDEX
The creation of clusters (C), alternate indices (G), pagespaces
(P), and catalogs (U/M) is very similar. We shall use "cluster"
loosely to mean all of these, except as noted. These requests
require multiple CTGFVs to complete. The primary CTGFV is pointed
to from the CTGPL. In the primary CTGFV, CTGFVDCH points to the
CTGFV for the data (D) component. CTGFVICH points to the CTGFV for
the index (I) component, if one exists. CTGFVVCH points to the
CTGFV for space (V), if any. If a space CTGFV exists, it is empty
except for the type code of V. Such a CTGFV is always present for
a catalog, but is optional for other types, and denotes "UNIQUE".
ICF catalogs ignore the space CTGFV.
The following table illustrates the general relationships among the
various data ares for defining each specific type of object:
Entity CTGFVTYP CTGTYPE Data Index Space Other
KSDS C X'00' Yes Yes Opt
ESDS C X'00' Yes No Opt
RRDS C X'00' Yes No Opt
LDS C X'00' Yes No ?? ?Linear?
AIX G X'00' Yes Yes Opt
ICF Cat C U/M Yes Yes Yes CTGICFOR=1
VSAM Cat C U/M Yes Yes Yes CTGICFOR=0
PAGESPACE C P Yes No Opt CTGSWAP=0
SWAPSPACE C P Yes No Opt CTGSWAP=1
The data and index components (if present) will always each have an
AMDSB. Flags in the data AMDSB distinguish between ESDS, RRDS, and
linear objects. The AMDSB is mapped by IDAAMDSB, and is described
by a CTGFL anchored from the related CTGFVAMD field. The AMDSB is
updated by catalog management to fill in additional information.
Also in the AMDSB are found: CI size, maximum record size, key
position and length, numbers of buffers, IMBED, REPLICATE, spanned
record indicator, writecheck flag, and MSS staging information.
Not all information is applicable to all component types.
As a minimum, you must fill in AMDSBID and AMDLEN in every AMDSB.
If the entity is not an ESDS, then one of AMDRRDS, AMDDST, or
AMDLDS must be set. In the AMDSB for the data component, you must
provide maximum record length in AMDLRECL (the average length is
passed separately).
The caller can specify names for all components when defining a
pagespace, cluster, or alternate index. Names for catalog
components are always constructed by catalog management. The
effect of giving the data component of a VVDS a user-provided name
has not been studied. When names are generated, they are placed in
the workarea as described in the CTGFV section above.
Data and index components require allocation information. A DD
statement must exist for the volume, and CTGFVIND must point to the
DDNAME. Field lists for volumes and space are required. This
information may be provided at the component level, or the cluster
level. If both are specified, then the component level information
overrides the cluster level.
The space field list anchored at CTGFVSPC is named SPACPARM, and
points to a 7-byte field. The first three bytes contain the
primary quantity in binary. The next three bytes contain the
secondary quantity, or zero if there is no secondary space desired.
The seventh byte is a space format indicator, where X'C0' denotes
cylinders, X'80' means tracks, and X'40' requests records. If
records are requested, then the LRECL CTGFL must be present via
CTGFVLRS to provide a fullword average record length. AMS provides
a default of 4089 for unspanned records, and 4086 for spanned.
When defining a non-ICF catalog, if space is specified at both the
cluster level and data component level, then a dataspace is created
based on the cluster space request, and the data suballocated with
the data space request. The leftover space is available for
allocation of other clusters.
To create an ICF catalog, turn on CTGICFOR in the CTGPL, and
CTGFVICF in the CTGFV. For creation of a VSAM catalog, these bits
must be off.
When a pagespace is created, the setting of CTGSWAP determines a
swap dataset versus a normal page dataset. The space request for
a pagespace must be at the data component level, and must have zero
as the secondary quantity. Contiguous space will be allocated.
Defining the pagespace does not format it, and it cannot be used
until formatted. AMS formats the new pagespace by dynamically
allocating it, opening it, and closing it. Apparently VSAM is
clever enough to format it during open.
When creating an alternate index, the name of the related cluster
must be supplied by pointing CTGFVNAM of the "G" CTGFV to it.
The volume list is pointed to directly by CTGFVVLT. It consists of
a halfword length, followed by a series of 8-byte entries. Each
entry consists of two bytes of binary zeros, followed by the six
character volume serial number. The length field does not include
itself, eg. for one volume: H'8',XL2'0',CL6'VOL001'. All of the
volumes in the list must be of the same type, but different
components may use different lists.
The optional security information CTGFL is pointed to by CTGFVSTY.
The list is named PASSWALL. The data addressed is at least 52
bytes long, as follows:
+0 8-byte master password
+8 8-byte control interval password
+10 8-byte update password
+18 8-byte read password
+20 8-byte code word
+28 2-byte binary attempts count
+2A 8-byte user security verification module name
+32 2-byte user data length (min 0, max 256)
+34 optional user data string (up to 256 bytes)
Unused fields are set to binary ones (X'FF').
CTGFVATR points to the attributes field list named DSATTR. The
data is two bytes long:
1... .... .... .... Speed
.1.. .... .... .... Unique
..1. .... .... .... Reusable
...1 .... .... .... Erase
.... 1... .... .... This catalog is recoverable (non
ICF only)
.... .1.. .... .... Inhibit update
.... ...1 .... .... Track overflow (pagespaces only)
.... .... XX.. .... Cross-Region share options 00=1,
01=2, etc
.... .... ..XX .... Cross-System share options 10=3,
11=4
.... ..x. .... xxxx Reserved, must be zero
For an alternate index only, CTGFVUPG points to the RGATTR field
list, which addresses a flag byte, bit 0 of which is on for
upgrade.
For a define with recatalog, turn on CTGFVRCT. You must be
authorized for this function.
DEFINE PATH
A path (R) is like an alias for VSAM of sorts. In the single
CTGFV, CTGFVENT points to the 44-byte path name. CTGFVNAM points
directly to the 44-byte path entry name, ("true name"). CTGFVUPG
points to the RGATTR field list, which addresses a flag byte, bit
0 of which is on for upgrade. CTGFVSTY may point to a CTGFL with
password information if desired (see define cluster for format).
DEFINE ALIAS
An alias (X) requires a single CTGFV. CTGFVENT points to the alias
name being defined, and CTGFVNAM points directly to the 44-byte
true name. The referenced true name must be of type (A) or (U).
DEFINE SPACE
Space, when requested alone, applies only to non-ICF catalogs. It
is the only entity for which no name need be provided. An
allocation must exist to the volume, and CTGFVIND must point to the
DDNAME. Volume and space information are required in the same
format as described under DEFINE CLUSTER. A name will be
generated, and returned in the workarea.
Modifying Catalog Information - ALTER
Alter shares a lot with define, so you should be familiar with the
description of define before continuing.
The setup for alter is always a single CTGFV which refers to the
component being altered. To alter the share options for an entire
cluster, you would alter the cluster, data, and index components in
separate requests. Also, alter replaces whole fields in the
catalog. To change STRNO, for example, you must provide a complete
AMDSB replacement. This means you must first use VSAM LOCATE to
obtain a copy of the existing AMDSB.
The CTGFV will only require pointers to the fields being changed.
All other pointers (except CTGFVENT) will be zero. CTGFVENT, of
course, points to the 44-byte name of the object being altered.
CTGFVTYP should contain the type code of the entity, but I don't
know if this is required.
ALTER NEWNAME is a special case, in that the new name is pointed to
by CTGNEWNM in the CTGPL, and the CTGFV is all zeros (even
CTGFVTYP) except for CTGFVENT. Attempting ALTER NEWNAME on a
catalog or one of its components will fail with return code 48,
reason 8. If the entity being renamed is type A, D or I, then
CTGFVIND should provide a DD as the VTOC will require updating.
ALTER REMOVEVOLUMES, for the volume cleanup function, requires that
CTGFVENT point to the name of the master catalog, CTGFVIND must
point to the DDNAME to be used, and CTGFVRVL must be on.
DIAGNOSTIC TIPS & HOW TO LEARN MORE
Much information about the parameter lists was found through the
examination of the parameters created by AMS. Two techniques are
useful, one for TSO and the other for background testing.
Processing for both TSO and background mode involves the mainline
load module IDCAMS identifying the command. Depending on the
request, one of several functional modules will be entered from the
mainline, but control always passes back to a common "System
Adapter" to perform the actual catalog management call. The
adapter we are interested in is named IDCSACA, and entry point in
module IDCSA02, load module IDCAMS. On entry to IDCSA02, register
1 points to a two word parameter list. The second word is the
address of the pointer to the CTGPL. In TEST-ese, the CTGPL is
located at 1R%+4%%. Other data may be found chained from the
CTGPL.
Testing AMS Under TSO
All TSO requests begin at module IDCAM01, which resides in CMDLIB
and has an alias for each AMS command. Most levels of AMS also
have module IDCAM02, which is identical to IDCAM01, and is used to
avoid the limit of 16 aliases per load module. (Note, PARM and
CNVTCAT are not available under TSO). IDCAM01 passes control via
LINK to the AMS mainline IDCSATO (an alias of IDCAMS).
By running AMS under test, and setting a breakpoint at the entry to
IDCSACA, we can examine (and modify!) the parameters to study them
and their effect.
The following MVS/XATM CLIST has been useful to the author (it
requires slight modification for use with MVS/370):
10 PROC 1 VERB
20 WRITE ENTER OPERANDS FOR &VERB COMMAND
30 READ
40 TEST 'SYS1.CMDLIB(&VERB)' CP
50 &VERB &SYSDVAL
60 AT IDCSATO.IDCSACA +
70 (EQ CTGPL 1R%+4%% L(28);L CTGPL;EQ CTGFV CTGPL+4% L(100);L CTGFV; +
80 EQ AFTER 14R%;AT AFTER (OFF AFTER)) DEFER
90 GO
In MVS/370, you must find the offset of label IDCSACA in module
IDCSA02 (with AMBLIST, for example), and change line 60 to AT
IDCSATO.IDCSA02.+xx, since TEST in 370 mode will not accept an
external symbol which is not a CSECT name.
Testing AMS In The Background
Testing in the background is accomplished through the use of AMS
own built in debugging facility. AMS provides a generous number of
dump points within the logic flow. The most useful one is called
ZZCA, which is located in IDCSACA and is hit before and after each
call (ie. twice per request). The trap is activated by the AMS
command " PARM TEST(FULL(ZZCA,n,m)", where n (default 1) indicates
when dumping is to begin, and m (default 1) indicates how many
dumps are to be taken.
ALTER usually requires a locate, followed by an alter call. To
trace the before and after status of an ALTER, without tracing the
locate call, you might use:
PARM TEST(FULL(ZZCA,3,2)) /* ACTIVATE TRAP */
ALTER entity-name STRNO(8)
PARM TEST(OFF) /* DEACTIVATE TRAP */
The dumps are taken to the AMSDUMP DD statement. Each dump is
assigned an ID number, and messages in SYSPRINT relate the dumps to
the logic flow. Each pass through the active trap point will be
traced on SYSPRINT, even if no dump is produced.
Data Area Descriptions
The following pages contain descriptions of the major data areas
discussed in this paper. They are based upon assembler language
mapping macros which are not generally available. Some of the
mappings are available on the optional materials tape for the Data
Facility Product (DFP), as component AAPVT, however (except for
the CTGPL), they are PL/S mappings only. In order to produce these
mappings, the PL/S descriptions have been manually translated into
assembler language.
Offsets are shown in hex, and for equated bit settings, the
assembled values are shown in hex.
--------------------------------
Author's note, September 4, 2004
--------------------------------
The original paper distributed through SHARE had mappings of several
control blocks included at this point. A small font was used in the
paper, but the lines are too wide to fit in 80-character lines. They
are not included here in order to fit the record size in the CBT file.
The mappings are included in file 689 in a member named PRINT, which
is in TSO XMIT format. To expand on an MVS system, execute the TSO
command:
RECEIVE INDS(xxxx.FILE689.PDS(PRINT))
and you'll get an FB-133 file which contains the correctly formatted
data.
Alternatively, the macros to map these data areas are in file 689.
You can just run an assembly to expand them. Member CATMAP in this
data set is a source module which can be assembled to do just that.
Peter Sawyer