Module 04
Schema, subschema, DMCL & the dictionary
This database keeps three separate definitions: what the data is, what a given program is allowed to see of it, and where the bytes physically live. Knowing which is which is how you find the metadata you need to build your target database — and how you avoid building it from the wrong one.
Finding the blueprint. Somewhere on that machine is a machine-readable description of every record, every field, every field’s exact format and every relationship. That description is the thing you generate your target tables from, so you are not transcribing anything by hand.
The trap this module exists to prevent: there are three descriptions, and two of them are the wrong answer. One is deliberately incomplete (it is a per-program view), and one describes only files and disk sizes. Build your model from the wrong one and you will be missing columns that nobody notices for months.
New words on this page, one line each
- schema
- The complete blueprint: every kind of record, every field, every relationship. This is the one you want.
- subschema
- A restricted view of that blueprint handed to one program — deliberately partial.
- DMCL
- The physical half: which files hold what, how big pages are, where the change log lives. No business content.
- dictionary (IDD)
- A database describing the database. You can ask it to print the whole schema as text.
- DDL
- The statements that define structure, as opposed to reading or changing data.
- copybook
- A generated file of field definitions that programs include, giving the exact byte layout of a record.
- LRF
- A pre-built flattened view that joins several records together. If one exists, someone already did that design work.
- ASF
- User-created tables inside the database that a DBA never defined. Real data, usually missing from every diagram.
- version
- Blueprints are versioned and several versions coexist. Always record which one you took.
Three separate definitions, and which one you want
Roughly: the schema is your full DDL, the subschema is a view plus grants for one application, and the DMCL is tablespaces, page size and shared_buffers.
The reason they are separate is worth noting. You can resize a cache or move a file to another disk with no program change at all. Add one field to a record, and every affected program must be regenerated and rebuilt. Physical tuning is cheap here; logical change is expensive.
This is the ANSI/SPARC three-schema architecture, implemented for real in 1970s software, and IDMS follows it more literally than most modern databases do.
Schema DDL, clause by clause
A schema has four kinds of statement. Here is a complete, if small, schema — read it as the authoritative statement of the logical design.
ADD SCHEMA NAME IS EMPSCHM VERSION IS 100
SCHEMA DESCRIPTION IS 'PERSONNEL AND PAYROLL'
ASSIGN RECORD IDS FROM 400.
ADD AREA NAME IS EMP-DEMO-REGION.
ADD AREA NAME IS ORG-DEMO-REGION.
ADD RECORD NAME IS DEPARTMENT
RECORD ID IS 410
LOCATION MODE IS CALC USING ( DEPT-ID-0410 )
DUPLICATES ARE NOT ALLOWED
WITHIN ORG-DEMO-REGION AREA.
02 DEPT-ID-0410 PIC 9(4).
02 DEPT-NAME-0410 PIC X(45).
02 DEPT-HEAD-ID-0410 PIC 9(4).
ADD RECORD NAME IS EMPLOYEE
RECORD ID IS 415
LOCATION MODE IS CALC USING ( EMP-ID-0415 )
DUPLICATES ARE NOT ALLOWED
WITHIN EMP-DEMO-REGION AREA.
02 EMP-ID-0415 PIC 9(4).
02 EMP-NAME-0415.
03 EMP-FIRST-NAME-0415 PIC X(10).
03 EMP-LAST-NAME-0415 PIC X(15).
02 STATUS-0415 PIC X(2).
02 START-DATE-0415 PIC 9(8).
ADD SET NAME IS DEPT-EMPLOYEE
ORDER IS SORTED
MODE IS CHAIN LINKED TO PRIOR
OWNER IS DEPARTMENT
NEXT DBKEY POSITION IS 1
PRIOR DBKEY POSITION IS 2
MEMBER IS EMPLOYEE
OPTIONAL AUTOMATIC
NEXT DBKEY POSITION IS 1
PRIOR DBKEY POSITION IS 2
LINKED TO OWNER
OWNER DBKEY POSITION IS 3
ASCENDING KEY IS ( EMP-LAST-NAME-0415 )
DUPLICATES ARE LAST.
VALIDATE.The clauses that carry real meaning
| Clause | What it decides | Downstream consequence |
|---|---|---|
RECORD ID | The numeric identity of the record type, stamped into every occurrence and into journal images. | How a capture agent knows what record type a change belongs to. |
LOCATION MODE | CALC / VIA / DIRECT placement. | Whether a natural key exists, and how expensive access is. |
WITHIN … AREA | Which area the occurrences live in. | Locking, recovery and extract boundaries. |
DBKEY POSITION | Which slot in the record prefix holds each pointer. | Fixes the physical prefix layout; changing it is an unload/reload. |
LINKED TO PRIOR / OWNER | Whether prior and owner pointers exist at all. | Whether OBTAIN LAST and OBTAIN OWNER are one hop or a full walk. |
ASCENDING/DESCENDING KEY | The sort key of a sorted set. | Often the only natural ordering — and, with DUPLICATES NOT ALLOWED, the only uniqueness constraint you get. |
MANDATORY/OPTIONAL AUTOMATIC/MANUAL | Membership semantics. | Your NOT NULL and cascade decisions. |
EMPSCHM VERSION 100 and EMPSCHM VERSION 101 are different objects that can
coexist in the dictionary. Programs bind a specific version. When you extract metadata, always record the
version you took it from — "we modelled from the schema" is not a reproducible statement.
Lab — make the physical design decisions yourself
Subschemas: a per-program view, and a warning
A subschema is deliberately incomplete. Fields left out of it are still on disk and still changing — the program simply cannot see them.
So if a helpful developer sends you “the definition” and it is a subschema, and you generate your target tables from it, you will be missing real columns. Nothing will error. You find out when someone asks a business question the data cannot answer.
A subschema names a subset of the schema that a program is allowed to use. Unlike an SQL view, it restricts not only what data but what operations and what navigation paths exist.
ADD SUBSCHEMA NAME IS EMPSS01
OF SCHEMA NAME IS EMPSCHM VERSION IS 100
DESCRIPTION IS 'PAYROLL UPDATE VIEW'.
ADD AREA NAME IS EMP-DEMO-REGION
DEFAULT USAGE IS PROTECTED UPDATE.
ADD AREA NAME IS ORG-DEMO-REGION
DEFAULT USAGE IS RETRIEVAL.
ADD RECORD NAME IS EMPLOYEE
ELEMENTS ARE ( EMP-ID-0415 EMP-NAME-0415 STATUS-0415 ).
ADD RECORD NAME IS EMPOSITION.
ADD RECORD NAME IS DEPARTMENT.
ADD SET NAME IS DEPT-EMPLOYEE.
ADD SET NAME IS EMP-EMPOSITION.
GENERATE.A subschema controls:
- Which record types exist for the program. Anything omitted returns "not in subschema" (
0305) at runtime. - Which elements of each record are visible. Omitted elements do not appear in the generated record layout at all — the program cannot even see the bytes.
- Which sets are navigable. Omit a set and its traversal verbs stop working, even though the pointers are physically there.
- Default and maximum area usage modes. A retrieval-only subschema cannot be coerced into updating.
- Logical records, if LRF is used — see below.
How a program learns the shape of a record
The subschema compiler generates COBOL copybooks — one per record, plus the IDMS communication block. A
COBOL program includes them and the precompiler turns DML verbs into CALLs.
DATA DIVISION.
WORKING-STORAGE SECTION.
COPY IDMS SUBSCHEMA-CONTROL. *> the communication block
COPY IDMS SUBSCHEMA-NAMES. *> literal names for BIND
COPY IDMS RECORD EMPLOYEE. *> generated 01 EMPLOYEE ...
COPY IDMS RECORD EMPOSITION.
PROCEDURE DIVISION.
BIND RUN-UNIT.
BIND EMPLOYEE.
BIND EMPOSITION.
READY EMP-DEMO-REGION USAGE PROTECTED UPDATE.
SUBSCHEMA-CONTROL — usually referred to as the IDMS communication block — is where
ERROR-STATUS, DBKEY, RECORD-NAME, AREA-NAME and the
other feedback fields live. Every DML call updates it. Module 05 uses it constantly.
The physical definition: files, sizes, caches
ADD SEGMENT NAME IS EMPDEMO
PAGE GROUP IS 0
MAXIMUM RECORDS PER PAGE IS 255.
ADD FILE NAME IS EMPFILE
ASSIGN TO EMPFILE
PAGE SIZE IS 4276
PAGE RANGE IS 71001 THRU 71100.
ADD AREA NAME IS EMP-DEMO-REGION
PRIMARY SPACE MANAGEMENT INTERVAL IS 32
PAGE RESERVE IS 200 CHARACTERS
WITHIN FILE EMPFILE FROM 71001 THRU 71100.
ADD DMCL NAME IS EMPDMCL
DESCRIPTION IS 'PRODUCTION DMCL'
INCLUDE SEGMENT EMPDEMO
INCLUDE BUFFER DEFAULT-BUFFER PAGES 200
INCLUDE JOURNAL J1JRNL
INCLUDE JOURNAL J2JRNL.
GENERATE.The DMCL is where buffer pools are sized, journals are declared, and — importantly for anyone planning a migration — where you can see how many physical files you are actually dealing with and whether areas share them.
The dictionary: a database that describes the database
The dictionary can print the entire blueprint as text: every record, every field, every picture clause, every relationship and its rules.
That output is parseable. It means your target tables can be generated and regenerated whenever the source changes, rather than typed out once and slowly drifting. Ask for it on day one.
It also answers “what breaks if this record changes?”, because it records which programs use which records.
The IDD is an IDMS database whose contents describe the installation: schemas, subschemas, record and element definitions, programs, modules, users, and the relationships between them. It is queried with DDL statements and reported on with dictionary utilities.
SIGNON USER 'DBA01' DICTNAME APPLDICT.
ADD ELEMENT NAME IS EMP-ID-0415
PICTURE IS 9(4)
DESCRIPTION IS 'UNIQUE EMPLOYEE NUMBER'.
DISPLAY RECORD NAME IS EMPLOYEE VERSION 1 WITH ALL.
DISPLAY SCHEMA NAME IS EMPSCHM VERSION 100 WITH ALL.
DISPLAY SUBSCHEMA NAME IS EMPSS01 OF SCHEMA EMPSCHM.
DISPLAY ALL PROGRAMS WHICH USE RECORD EMPLOYEE.
That last one — which programs use this record — is the impact-analysis query, and it is the reason the dictionary matters to you. The dictionary knows the dependency graph. Use it to answer "what breaks if this record changes" before you propose any change.
DISPLAY SCHEMA … WITH ALL punched to a dataset gives you every record, every element, every
picture clause, every set, every membership option — machine-readable enough to drive target DDL
generation instead of transcribing copybooks by hand. Ask for it on day one.
Compilers and utilities by name
| Tool | Purpose |
|---|---|
IDMSCHEM / schema compiler | Compiles schema DDL into the dictionary. |
IDMSUBSC / subschema compiler | Compiles subschema DDL and generates load modules and copybooks. |
| DMCL compiler | Compiles the physical definitions and generates the DMCL load module. |
IDMSDDDL | The dictionary DDL compiler — general ADD/MODIFY/DISPLAY processing. |
IDMSBCF | Batch Command Facility — runs SQL and utility commands from batch. |
IDMSRPTS | Dictionary reporting — cross-reference and documentation reports. |
IDMSDBAN | Database analysis: chain lengths, space, fragmentation, broken pointers. |
Exact program names and invocation differ between releases and between z/OS and z/VSE. Treat the list above as a vocabulary, and confirm against your site's runbooks before writing JCL.
Logical records: joins somebody already designed for you
The Logical Record Facility lets a subschema define a flattened record assembled from several physical
records, plus path groups describing the navigation needed to build it. The program then
issues OBTAIN NEXT <logical-record> WHERE … and the DBMS runs the path.
*> in the subschema
ADD LOGICAL RECORD NAME IS EMP-JOB-LR
ELEMENTS ARE ( EMPLOYEE EMPOSITION JOB ).
ADD PATH-GROUP NAME IS OBTAIN EMP-JOB-LR
SELECT FOR FIELDNAME-EQ EMP-ID-0415
OBTAIN CALC EMPLOYEE
OBTAIN FIRST EMPOSITION WITHIN EMP-EMPOSITION
OBTAIN OWNER WITHIN JOB-EMPOSITION.
*> in the program
OBTAIN FIRST EMP-JOB-LR WHERE EMP-ID-0415 EQ WS-EMP-ID.If your source system already has logical records covering the entities you need, someone has already done the join design and validated it against production. Read them before designing your own.
Tables nobody told you about
Someone in the finance department was allowed to add their own filing cabinet to the warehouse, without asking the warehouse manager. The cards in it are real, people rely on them, and the cabinet appears on no floor plan.
When you take inventory, ask explicitly whether any of these exist in the areas you are copying.
The Automatic System Facility lets end users define and populate tables inside IDMS without DBA involvement. ASF generates the underlying schema objects itself. The data is real, it is in the database, and it is frequently absent from every architecture diagram and every scoping document.
When taking inventory, ask specifically: are there ASF-defined tables in the areas we are replicating, and does anyone depend on them?
What this means for replication
- Model from the schema, not a subschema. Subschemas hide elements that still change on disk.
- Punch the dictionary and generate. Hand-transcribing copybooks introduces errors that survive to production; generate target DDL from dictionary output and diff it when the schema changes.
- Record IDs are your record-type discriminator. A journal image carries a record ID; keep a mapping from record ID to target table, versioned alongside the schema version.
- Watch for schema version drift. If the source adds an element mid-project, your generated model must be regenerated and the change staged. Build that regeneration into the pipeline rather than doing it by hand once.
- LRF path groups are free design work. They encode joins that the business already trusts.
- ASF and LRF are in scope until proven otherwise. Both hide data from a naive schema-only survey.
Exercise 4.1 — Metadata request list
Draft the exact artefacts you will ask the DBA for. A complete request looks like this:
DISPLAY SCHEMA <name> VERSION <n> WITH ALL, punched to a dataset, for every schema in scope.- The same for each subschema actually used by an in-scope program, so you can see which elements are live.
- The DMCL source, for page sizes, page groups, radix, area-to-file mapping and journal configuration.
- A cross-reference of programs to records (
DISPLAY ALL PROGRAMS WHICH USE RECORD …). - A list of logical records and path groups.
- A list of ASF-defined tables in the in-scope areas.
- The schema and subschema version numbers as of the extract date, recorded in your own repository.