z/VMVersion 7 Release 1

CMS Application Development Guidefor Assembler

IBM

SC24-6257-00

Note:

Before you use this information and the product it supports, read the information in “Notices” on page503.

This edition applies to version 7, release 1, modification 0 of IBM® z/VM® (product number 5741-A09) and to allsubsequent releases and modifications until otherwise indicated in new editions.

Last updated: 2018-09-12© Copyright International Business Machines Corporation 1990, 2018.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract withIBM Corp.

Contents

List of Figures..................................................................................................... xiiiList of Tables........................................................................................................xv

About This Document......................................................................................... xviiIntended Audience................................................................................................................................... xviiWhere to Find More Information.............................................................................................................. xvii

Links to Other Documents and Websites........................................................................................... xviiHow to Send Your Comments to IBM....................................................................xixSummary of Changes for z/VM CMS Application Development Guide for

Assembler....................................................................................................... xxSC24-6257-00, z/VM Version 7 Release 1................................................................................................xxSC24-6163-02, z/VM Version 6 Release 4................................................................................................xx

Part 1. Introduction.............................................................................................. 1

Chapter 1. The CMS Programming Interface.............................................................................................. 3Overview of the CMS Programming Interface....................................................................................... 3

CMS Virtual Machine Environments................................................................................................. 3CMS Programming Interface Groups..................................................................................................... 4CMS Preferred Interface.........................................................................................................................5

CMS Preferred Macros...................................................................................................................... 5CMS Preferred Routines....................................................................................................................9CMS Preferred Functions.................................................................................................................. 9

CMS Compatibility Interface................................................................................................................ 10CMS Compatibility Macros and Suggested Replacements............................................................ 10CMS Compatibility Functions and Suggested Replacements........................................................11Simulated OS/MVS Macros.............................................................................................................11

Chapter 2. CMS Operating Characteristics................................................................................................15Overview of CMS Operating Characteristics........................................................................................ 15CMS Command Search Order...............................................................................................................15CMS Runs in Supervisor State..............................................................................................................16How CMS Command Processing Works...............................................................................................16

Explicitly Releasing Resources.......................................................................................................16The CMS Command Loop................................................................................................................17SVC Levels....................................................................................................................................... 17Abend Processing........................................................................................................................... 18

Determining When CMS Reclaims Resources..................................................................................... 18Saving Resources across Boundaries.................................................................................................. 20Using Macro Libraries...........................................................................................................................21

Coding CMS Macros........................................................................................................................ 21How CMS Macros Work...................................................................................................................22CMS Macro Formats........................................................................................................................22

Chapter 3. Architecture............................................................................................................................. 23ESA/XC, ESA/XA, 370-XA, and System/370 Architecture.................................................................. 23ESA/XC, 370-XA, and System/370 PSWs............................................................................................2331-Bit Addressing................................................................................................................................ 24

Conventions for 31-Bit Programs...................................................................................................24Bimodal Addressing........................................................................................................................25

iii

I/O Considerations..........................................................................................................................28CMS Preferred Interface I/O Support.............................................................................................28Using Diagnose Codes for I/O.........................................................................................................29I/O Instructions.............................................................................................................................. 29

Assembler Instructions That Work Differently....................................................................................30Instructions That Are Sensitive to Addressing Mode.................................................................... 31

Part 2. Using CMS Services..................................................................................33

Chapter 4. Program Invocation - Direct Branch Linkage.......................................................................... 35Overview of Direct Branch Linkage...................................................................................................... 35Using BAL/BALR with AMODE ANY Programs..................................................................................... 35Switching the Addressing Mode...........................................................................................................35

AMODESW Formats........................................................................................................................ 36Using AMODESW - Examples......................................................................................................... 36

Chapter 5. Program Invocation - Supervisor Assisted Linkage................................................................ 39Overview of CMS Supervisor Assisted Linkage....................................................................................39Supervisor Assisted Linkage — An Overview....................................................................................... 39Setting Up a Parameter List................................................................................................................. 41

Using the SCAN Macro.................................................................................................................... 41Making the Call................................................................................................................................43Call Charts....................................................................................................................................... 45

Receiving Control..................................................................................................................................46Register Usage................................................................................................................................ 46USERSAVE Control Block................................................................................................................48SVC 202 Call Type Values............................................................................................................... 49Return Codes...................................................................................................................................50

Returning To a Program........................................................................................................................51Example 1 — A Simple Return........................................................................................................ 51Example 2 — Setting a Return Code............................................................................................... 51Example 3 — Returning Register Contents.....................................................................................52

Chapter 6. Using Free Storage...................................................................................................................53Overview of Free Storage..................................................................................................................... 53CMSSTOR and SUBPOOL Macros.........................................................................................................53

CMS Storage Layout........................................................................................................................53Obtaining Free Storage.........................................................................................................................56

Where CMSSTOR Gets Storage.......................................................................................................56Creating Subpools................................................................................................................................ 57

Types of Subpools...........................................................................................................................57Releasing Free Storage........................................................................................................................ 59

Examples of Releasing Free Storage..............................................................................................60Determining How Much Free Storage Is Available.............................................................................. 61

Using the STORMAP Command...................................................................................................... 61Using the SUBPMAP Command......................................................................................................62

Debugging Storage Problems...............................................................................................................63Using the STORMAP Command...................................................................................................... 63Using the SUBPMAP Command......................................................................................................66Using the STDEBUG Command...................................................................................................... 67

Obtaining and Releasing Storage above 2 GB..................................................................................... 74

Chapter 7. Using Saved Segments............................................................................................................ 75Physical and Logical Saved Segments................................................................................................. 75Using the SEGMENT Macro.................................................................................................................. 75

Loading a Saved Segment...............................................................................................................76Finding the Starting and Ending Address of a Saved Segment......................................................76

iv

Purging a Saved Segment............................................................................................................... 77How CMS Locates Saved Segments............................................................................................... 77How CMS Handles Objects in Logical Saved Segments.................................................................78

Using the SEGMENT Command........................................................................................................... 78Reserving Storage Space for Saved Segments.............................................................................. 78Releasing Segment Storage Spaces...............................................................................................79Assigning Logical Saved Segments to Physical Saved Segments................................................. 79

Displaying Information about Saved Segments.................................................................................. 79

Chapter 8. Console and Terminal I/O........................................................................................................83Performing 3270 Full-Screen I/O Operations..................................................................................... 83

CONSOLE Macro Functions.............................................................................................................83Opening a Path to a Console...........................................................................................................83Modifying Parameters of a CONSOLE OPEN.................................................................................. 85Writing to and Reading from a Console..........................................................................................85Obtaining Information about a Console Path.................................................................................87Disconnecting and Reconnecting................................................................................................... 88Writing Your Own Channel Programs............................................................................................. 88Closing a Console Path................................................................................................................... 89A Sample Program.......................................................................................................................... 90

APPLMSG.............................................................................................................................................. 92Example of a Message Repository..................................................................................................92

LINERD and LINEWRT Macros............................................................................................................. 94Example.......................................................................................................................................... 94Reading and Writing Multiple Lines................................................................................................ 94Example of Creating a Panel...........................................................................................................99

Considerations for Writing Applications in Full-Screen CMS............................................................ 104

Chapter 9. CMS File System.................................................................................................................... 107Overview of the CMS File System...................................................................................................... 107

What Is a CMS File?...................................................................................................................... 107What is a BFS File?........................................................................................................................108What File Information Does CMS Maintain?................................................................................ 108Manipulating CMS Files................................................................................................................ 113Manipulating BFS Files in CMS..................................................................................................... 116Application Interfaces.................................................................................................................. 117Committing Changes.................................................................................................................... 125Mixing CSL and Non-CSL Statements.......................................................................................... 125Using XEDIT to Access Files in Storage....................................................................................... 128Example........................................................................................................................................ 130

Chapter 10. Using the File System Macros............................................................................................. 131File I/O Using FS Macros — A Typical Scenario................................................................................. 131Creating a File System Control Block................................................................................................ 132

Contents of the File System Control Block.................................................................................. 133Mapping the File System Control Block....................................................................................... 134Modifying Fields in the File System Control Block.......................................................................135Using the File System Control Block............................................................................................ 135

Opening CMS Files............................................................................................................................. 136Reading and Writing CMS Files.......................................................................................................... 137

Single Reads and Writes...............................................................................................................137Multiple Reads and Writes to a Fixed File....................................................................................137Variable Length Records...............................................................................................................137

Closing Files and Committing Changes............................................................................................. 139Note For EXEC Writers..................................................................................................................139

Erasing Files....................................................................................................................................... 139Sample Programs............................................................................................................................... 139

Nonreentrant................................................................................................................................ 139

v

Reentrant...................................................................................................................................... 141

Chapter 11. Unit Record Devices and Tapes...........................................................................................147Printing............................................................................................................................................... 147

Determining How Many Bytes You Can Print............................................................................... 147Using PRINTL................................................................................................................................148

Punching.............................................................................................................................................150Reading...............................................................................................................................................150

Using the CMS Internal I/O Buffer............................................................................................... 150Tape Handling Macros........................................................................................................................151Tape Labels in CMS............................................................................................................................ 151

Limitations.................................................................................................................................... 151Initiating Label Processing........................................................................................................... 151Label Processing in OS Simulation...............................................................................................152Label Processing in CMS/DOS...................................................................................................... 164Label Processing Using CMS Macros and Commands................................................................. 166Error Processing............................................................................................................................169

Using Tape Library Dataservers under CMS OS Simulation.............................................................. 170

Chapter 12. Interrupt Handling...............................................................................................................173Manipulating the PSW Interrupt Mask...............................................................................................173

Converting from the SSM Instruction to ENABLE........................................................................ 173External Interrupt Handling...............................................................................................................174

External Interrupt Handling Overview......................................................................................... 174The CMS Default External Interrupt Handler...............................................................................176Handling Specific External Interrupts..........................................................................................176Creating Your Own Default Handler............................................................................................. 179Deleting an External Interrupt Handler....................................................................................... 179

Handling I/O Interrupts..................................................................................................................... 179I/O Interrupt Handling — An Overview........................................................................................ 180First-Level I/O Interrupt Processing............................................................................................ 180Second-Level I/O Interrupt Processing....................................................................................... 181Defining an I/O Interrupt Handling Procedure............................................................................ 181Second-Level Handler Returns to First-Level.............................................................................. 185

SVC Interrupts....................................................................................................................................186Creating SVC Handlers................................................................................................................. 186Deleting SVC Handlers..................................................................................................................187

Machine Check Interrupts................................................................................................................. 187Data Space Machine Checks........................................................................................................ 188

Program Interrupt Handling...............................................................................................................188CMS First-Level Program Interrupt Processing........................................................................... 188Defining Program Interrupt Handlers.......................................................................................... 189

Chapter 13. Nucleus Extensions and Commands.................................................................................. 191Nucleus Extensions............................................................................................................................191

The NUCEXT Macro.......................................................................................................................191Should Your Program Be a Nucleus Extension?...........................................................................191Defining Nucleus Extensions........................................................................................................191Other Parameters You Can Specify on NUCEXT.......................................................................... 192Defining Nucleus Extensions in Logical Saved Segments........................................................... 193Obtaining the Anchor Point of the SCBLOCK List.........................................................................194Deleting Nucleus Extensions........................................................................................................194Obtaining Information about Nucleus Extensions.......................................................................194Renaming Nucleus Extensions.....................................................................................................194

ANCHOR Words..................................................................................................................................195The ANCHOR Macro......................................................................................................................195What Types of Programs Should Use the ANCHOR Macro?........................................................ 195Using ANCHOR..............................................................................................................................196

vi

Subcommand Environments..............................................................................................................197SUBCOM Macro.............................................................................................................................197Defining Subcommands............................................................................................................... 197Defining Subcommands in Logical Saved Segments................................................................... 199Deleting Subcommand Processors.............................................................................................. 199Determining if a Subcommand Processor Is Defined..................................................................199Obtaining the Anchor Point of the SCBLOCK List.........................................................................199

Immediate Commands...................................................................................................................... 200Creating Immediate Commands.................................................................................................. 200

Using NUCEXT to Create Immediate Commands............................................................................. 200Using the IMMCMD Macro to Create Immediate Commands..................................................... 200Entry Conditions........................................................................................................................... 200Defining Immediate Commands in Logical Saved Segments......................................................201Deleting Immediate Commands.................................................................................................. 202Obtaining Information about Immediate Commands................................................................. 202

Chapter 14. Abend Processing................................................................................................................203Overview of CMS Abend Processing.................................................................................................. 203

Macros That Define Abend Exit Routines.....................................................................................203Abend Exit Routine Search Order.................................................................................................203What You Can Save Across a CMS Abend.................................................................................... 204

Creating Abend Exit Routines............................................................................................................ 204Creating Abend Exits.................................................................................................................... 204Deleting Abend Exits.................................................................................................................... 205

Abending a Program (DMSABN Macro)............................................................................................. 205Examples...................................................................................................................................... 206

Part 3. Managing CMS Programs........................................................................ 209

Chapter 15. Program Packaging..............................................................................................................211Program Packaging Considerations...................................................................................................211Program Packaging Overview............................................................................................................ 211

Program Packaging — A Simple Scenario.................................................................................... 212Program Life - Determining How Long Your Program Stays in Storage............................................ 212Addressing and Residency Modes.....................................................................................................214

When You Can Set Addressing and Residency Modes.................................................................214

Chapter 16. Assembling, Loading, and Executing Programs..................................................................217Assembling Programs........................................................................................................................ 217

Example 1..................................................................................................................................... 217Example 2..................................................................................................................................... 218

Identifying Files..................................................................................................................................218Default File Definitions................................................................................................................. 218Determining What File Definitions Are in Effect.......................................................................... 219Identifying Libraries......................................................................................................................220Macro Libraries............................................................................................................................. 220Loading and Executing Text Files................................................................................................. 221File Loading Techniques............................................................................................................... 221Loading Text Files into Storage.................................................................................................... 222Other LOAD and INCLUDE Options.............................................................................................. 224Executing TEXT Files.................................................................................................................... 224Example — Loading and Starting a Program................................................................................ 224Example — Starting a Program at a Specific Entry Point............................................................. 224Example — Passing a Parameter List on the START Command...................................................225Resolving External References.....................................................................................................225Loader Control Statements.......................................................................................................... 226Text File Libraries (TXTLIBs)........................................................................................................ 227

vii

Generating and Executing Modules...................................................................................................227Relocatable Modules.................................................................................................................... 227Creating a Module to Run in the Transient Program Area........................................................... 228Specifying Addressing and Residency Modes for a Module........................................................ 228Restricting a Module to a Specific Virtual Machine Mode........................................................... 228Saving History Information for Modules...................................................................................... 229Loading Modules...........................................................................................................................229Loading a MODULE into a Saved Segment................................................................................... 229

Displaying Information about Programs in Storage.......................................................................... 229The NUCXMAP Command.............................................................................................................229

Chapter 17. Creating and Using a Callable Services Library.................................................................. 231CSL Routines...................................................................................................................................... 231Writing CSL Routines..........................................................................................................................232

Using Macros When Writing CSL Routines................................................................................... 232Rules for Coding CSL Routines..................................................................................................... 234Types of Data Supported.............................................................................................................. 234Creating Template Files................................................................................................................235Defining Parameters with Scalar Data Types...............................................................................238Specifying Parameter Lengths..................................................................................................... 239Declaring Multi-Value Data Types in Template Files................................................................... 240Defining Return Parameters for OPENVM Routines.................................................................... 243Creating a Callable Services Library.............................................................................................243Invoking CSL Routines..................................................................................................................261

CSL Summary and Example...............................................................................................................262CALC: Example CSL Assembler Routine #1.................................................................................262

Chapter 18. Using Auxiliary Directories.................................................................................................. 273Overview of an Auxiliary Directory.....................................................................................................273Adding an Auxiliary Directory............................................................................................................ 273

Generating the Auxiliary Directory...............................................................................................273Initializing the Auxiliary Directory................................................................................................273Establishing the Proper Linkage...................................................................................................273

Creating an Auxiliary Directory.......................................................................................................... 274

Part 4. Connectivity Programming in CMS.......................................................... 277

Chapter 19. CMS Support of IUCV.......................................................................................................... 279Using IUCV in CMS to Communicate Between Two Virtual Machines..............................................281Understanding Exit Routines............................................................................................................. 283Guidelines for Using the CMS Support of IUCV................................................................................. 283

Chapter 20. APPC/VM Assembler Interface........................................................................................... 287Overview of APPC/VM Assembler Interface..................................................................................... 287Basics of APPC/VM.............................................................................................................................287

APPC/VM Paths.............................................................................................................................288APPC/VM States........................................................................................................................... 288APPC/VM Interrupts..................................................................................................................... 288

Invoking APPC/VM Communication Functions................................................................................. 290Using Basic APPC/VM Functions....................................................................................................... 291

Starting a Conversation................................................................................................................ 291Sending and Receiving Data on the Conversation....................................................................... 291Ending a Conversation.................................................................................................................. 292

Using the CMS Interface to APPC/VM............................................................................................... 292Errors and Interrupts for APPC/VM in CMS..................................................................................293Guidelines for Using the CMS Interface to APPC/VM.................................................................. 294

Managing a Resource......................................................................................................................... 295

viii

Revoking a Resource.......................................................................................................................... 295Scenario 1: Request for Global Resource..........................................................................................296Scenario 2: Request for Private Resource......................................................................................... 299

Virtual Machine Preparations....................................................................................................... 300Program Functions........................................................................................................................301

How APPC/VM Relates to General IUCV........................................................................................... 303CMS Support of APPC/VM............................................................................................................ 305

Summary of APPC/VM Assembler Macro Functions......................................................................... 305

Chapter 21. Using Advanced APPC/VM Functions................................................................................. 307Requesting Confirmation................................................................................................................... 307Signaling an Error............................................................................................................................... 307Requesting to Send............................................................................................................................ 307Sending and Receiving Early Information......................................................................................... 308Using Synchronous Functions............................................................................................................308Synchronizing Updates to Multiple Resources..................................................................................309

Determining When a Sever Requires a Rollback..........................................................................310Scenario 3: Coordinating Resources............................................................................................ 311

Part 5. OS/MVS Simulation................................................................................ 315

Chapter 22. Developing OS/MVS Programs under CMS......................................................................... 317OS/MVS Simulation History............................................................................................................... 317

How CMS Performs OS/MVS Simulation...................................................................................... 317Using OS/MVS Macros in CMS Programs — Some Considerations................................................... 318

OS/MVS Macro Libraries............................................................................................................... 319OS/MVS Macros That CMS Simulates................................................................................................ 319

MVS/XA Data Management Macros............................................................................................. 320OS/MVS Macros for Assembly Only................................................................................................... 337OS/MVS Resource Management........................................................................................................ 337

Cleaning Up GETMAIN Storage.................................................................................................... 338Using CMS Libraries........................................................................................................................... 342

OS/MVS Module Libraries and CMS LOADLIBS............................................................................342The LKED Command.....................................................................................................................344

OS/MVS and CMS Terminology.......................................................................................................... 347

Chapter 23. Using OS/MVS Simulated Data Sets in CMS....................................................................... 349Overview of OS/MVS Simulated Data Sets........................................................................................ 349Data Set Organization........................................................................................................................ 349Record Formats in OS Simulation...................................................................................................... 350

Fixed-Length Records...................................................................................................................350Variable-Length Records.............................................................................................................. 352Variable-Length ANSI Records.....................................................................................................353Variable Spanned Records........................................................................................................... 353Variable Spanned ANSI Records.................................................................................................. 355

Identifying I/O Files and Devices to OS Simulation.......................................................................... 357Specifying the ddname.................................................................................................................358Specifying the Device Type...........................................................................................................358Entering File Identifications......................................................................................................... 359Specifying CMS Tape Label Processing........................................................................................360Specifying Options........................................................................................................................360

Using OS/MVS Simulated Data Sets in CMS...................................................................................... 363Storing OS/MVS Data in CMS Format DASD Files........................................................................ 364Storing OS/MVS Data in OS/MVS Simulated DASD Files............................................................. 365Considerations for Files in Shared File System Directories.........................................................367

Using OS/MVS Data Sets in CMS........................................................................................................368CMS Commands You Can Use with OS/MVS Data Sets............................................................... 368

ix

Accessing OS/MVS Data Sets....................................................................................................... 369Using OS Format Disks on CMS..........................................................................................................369

Listing Information about OS Disks with the LISTDS Command.................................................369Using the GLOBAL Command with OS Files.................................................................................370Using XEDIT with OS Files............................................................................................................370Creating CMS Files from OS/MVS Data Sets................................................................................ 370Copying Sequential Data Sets from Disk......................................................................................371Copying Partitioned Data Sets from Disk..................................................................................... 371Summary.......................................................................................................................................372

Accessing Data through OS/MVS Simulation.................................................................................... 372Accessing Data with OS/MVS Macros.......................................................................................... 373BDAM Restrictions........................................................................................................................ 374

Using the OS/MVS Simulated Buffering Techniques......................................................................... 375Obtaining I/O Buffers....................................................................................................................375Determining the Minimum Buffer Size......................................................................................... 375Segment Interface........................................................................................................................375Logical Record Interface.............................................................................................................. 376

Opening Data Sets..............................................................................................................................378Specifying an Input Data File....................................................................................................... 378

Reading Data...................................................................................................................................... 382Reading OS/MVS Simulated Data Sets.........................................................................................382Reading OS/MVS Data Sets.......................................................................................................... 384Restrictions for Reading OS/MVS Data Sets................................................................................ 384

Writing OS/MVS Simulated Data Sets................................................................................................386Using the WRITE Macro................................................................................................................386

Closing Data Files...............................................................................................................................387Exit Routines...................................................................................................................................... 387

End-of-Data-Set Exit Routine (EODAD)....................................................................................... 388Synchronous Error Routine Exit (SYNAD).................................................................................... 388Exit List (EXLST)............................................................................................................................388DCB Abend Exit (DCB EXLST Entry Code X'11')...........................................................................390

End-of-Volume Processing................................................................................................................ 394Forced End-of-Volume Support................................................................................................... 395Error Handling during FEOV Processing.......................................................................................396OS/MVS Tape Volume Switching.................................................................................................. 397Passing Information to the DMSTVI Routine............................................................................... 399

Part 6. DOS/VSE, Access Method Services, and VSAM........................................ 401

Chapter 24. Developing VSE Programs under CMS................................................................................ 403Overview of CMS/DOS........................................................................................................................403Entering the CMS/DOS Environment................................................................................................. 403

DL/I in the CMS/DOS Environment.............................................................................................. 406Using DOS Files on DOS Disks........................................................................................................... 406

Reading DOS Files.........................................................................................................................407Creating CMS Files from DOS Libraries........................................................................................ 407

The ASSGN Command....................................................................................................................... 409Assigning System Logical Units....................................................................................................409Compiler I/O Assignments........................................................................................................... 410Manipulating Device Assignments............................................................................................... 410Listing I/O Assignments............................................................................................................... 411Virtual Machine Assignments.......................................................................................................411

The DLBL Command...........................................................................................................................412Entering File Identifications......................................................................................................... 412Clearing and Displaying File Definitions.......................................................................................413

Using DOS Libraries in CMS/DOS....................................................................................................... 413The SSERV Command...................................................................................................................413

x

The RSERV Command...................................................................................................................414The PSERV Command...................................................................................................................415The ESERV Command...................................................................................................................415The DSERV Command.................................................................................................................. 416The DOSLKED Command..............................................................................................................416DOS Core Image Libraries............................................................................................................ 416

Using Macro Libraries.........................................................................................................................416Creating CMS MACLIBs.................................................................................................................417

VSE Assembler Language Macros Supported................................................................................... 418Assembling Source Programs............................................................................................................420Link-Editing Programs in CMS/DOS................................................................................................... 421

Linkage Editor Input..................................................................................................................... 421Linkage Editor Output: CMS DOSLIBs.......................................................................................... 423

Executing Programs in CMS/DOS.......................................................................................................423Executing DOS Phases..................................................................................................................424Search Order for Executable Phases............................................................................................424Making I/O Device Assignments.................................................................................................. 425Specifying a Virtual Partition Size................................................................................................ 425Setting the UPSI Byte................................................................................................................... 426Debugging Programs in CMS/DOS................................................................................................426Using Exec Procedures in CMS/DOS............................................................................................ 426

Hardware Devices Supported............................................................................................................ 427VSE Supervisor and I/O Macros Supported by CMS/DOS................................................................. 428

Supervisor Macros........................................................................................................................ 428Declarative Macros (Sequential Access Method I/O Macros)..................................................... 435Imperative Macros (Sequential Access Method I/O Macros)......................................................442

EXCP Support in CMS/DOS................................................................................................................ 443CMS/DOS User Considerations and Responsibilities........................................................................ 443

VSE System Generation and Updating Considerations............................................................... 443z/VM Directory Entries..................................................................................................................443When the VSE System Must Be Online.........................................................................................444Execution Considerations and Restrictions................................................................................. 444

Chapter 25. Using Access Method Services and VSAM..........................................................................445Overview of VSAM under CMS........................................................................................................... 445Executing VSAM Programs under CMS..............................................................................................446The AMSERV Command..................................................................................................................... 446

AMSERV Output Listings...............................................................................................................447Controlling AMSERV Command Listings...................................................................................... 448Calling AMS from an Application Program................................................................................... 448

Manipulating OS and DOS Disks for Use with AMSERV.....................................................................449Data and Master Catalog Sharing.................................................................................................449Disk Compatibility.........................................................................................................................450Allocating Space........................................................................................................................... 450Using Minidisks............................................................................................................................. 450The LISTDS Command..................................................................................................................451Using Temporary Disks................................................................................................................. 452

Defining DOS Input and Output Files................................................................................................ 453Using VSAM Catalogs....................................................................................................................454Using Job Catalogs....................................................................................................................... 456Catalog Passwords....................................................................................................................... 456Verifying a Catalog Structure........................................................................................................457Defining and Allocating Space for VSAM files..............................................................................457Using Tape Input and Output....................................................................................................... 459

Defining OS Input and Output Files...................................................................................................460Allocating Extents on OS Disks and Minidisks............................................................................. 461Using VSAM Catalogs....................................................................................................................461Using a Job Catalog...................................................................................................................... 463

xi

Catalog Passwords....................................................................................................................... 464Verifying a Catalog Structure........................................................................................................464Defining and Allocating Space for VSAM files..............................................................................464Using Tape Input and Output....................................................................................................... 466

Using AMSERV under CMS................................................................................................................. 466The DEFINE and DELETE Functions.............................................................................................467Using Data Compression Services................................................................................................469The REPRO, IMPORT, and EXPORT Functions............................................................................. 470Writing Execs for AMSERV and VSAM.......................................................................................... 471

VSE/VSAM Functions Not Supported in CMS.................................................................................... 472Access Method Services Not Supported in CMS............................................................................... 473ISAM Interface Program (IIP)............................................................................................................474VSE/VSAM Macros Supported........................................................................................................... 474

VSE Supervisor Macros and Logical Transients Support............................................................. 475OS/VSAM Macros Supported in CMS................................................................................................. 475VSAM Macro Options Not Supported in CMS.................................................................................... 475

OS/VSAM Error Codes.................................................................................................................. 476Hardware Devices Supported............................................................................................................ 480Interface to an Alternate VSAM Emulator......................................................................................... 480

Appendix A. Sample Terminal Session for OS Programmers................................ 483

Appendix B. Sample Terminal Session for DOS Programmers.............................. 487

Appendix C. Sample Terminal Session Using Access Method Services................. 493

Appendix D. TSO Macros Simulated in CMS.........................................................501Notices..............................................................................................................503

Programming Interface Information.......................................................................................................504Trademarks.............................................................................................................................................. 504Terms and Conditions for Product Documentation................................................................................ 504IBM Online Privacy Statement................................................................................................................ 505

Bibliography...................................................................................................... 507Where to Get z/VM Information.............................................................................................................. 507z/VM Base Library....................................................................................................................................507z/VM Facilities and Features................................................................................................................... 509Prerequisite Products.............................................................................................................................. 510

Index................................................................................................................ 511

xii

List of Figures

1. CMS Boundary Relationships......................................................................................................................202. How CMS Macros Work............................................................................................................................... 223. ESA/XC PSW or ESA/XA PSW,..................................................................................................................... 244. 370-XA PSW................................................................................................................................................ 245. System/370 BC-Mode PSW........................................................................................................................ 246. How CMS Interprets the AMODE Attribute.................................................................................................257. How RMODE Affects Where CMS Loads Programs.....................................................................................268. CMSCALL for AMODE ANY/AMODE 31 Programs....................................................................................... 409. CMSCALL for AMODE 24 Programs.............................................................................................................4010. SCAN Macro Parameter List Format......................................................................................................... 4111. Determining Storage for PLISTs................................................................................................................4212. Determining Storage for PLISTs................................................................................................................4213. SCAN Macro Example............................................................................................................................... 4314. USERSAVE DSECT..................................................................................................................................... 4915. Storage Configuration for a Virtual Machine Less Than 15 MB................................................................5416. Storage Configuration for a Virtual Machine Equal to 20 MB...................................................................5517. Storage Configuration for a Virtual Machine Greater than 20 MB........................................................... 5518. Sample Repository - RUBUME REPOS......................................................................................................9219. Sample Program — JEWEL ASSEMBLE.....................................................................................................9320. A Sample Program That Reads and Writes One Line of Data...................................................................9421. Chain of Output Descriptors..................................................................................................................... 9522. Format of Information Returned by LINERD Macro.................................................................................9623. LINERD Descriptor Mapping..................................................................................................................... 9924. Using the XEDIT Interface to Access Files in Storage........................................................................... 13025. Valid ASA Control Characters................................................................................................................. 14826. Basic Tape Layout for ANSI and IBM Standard Labels.......................................................................... 15227. Basic Tape Layout................................................................................................................................... 15328. Positioning for BLP..................................................................................................................................16029. CSLCNTRL File Example......................................................................................................................... 25130. LIBMAP MYLIB........................................................................................................................................25231. SEGMAP MYLIB.......................................................................................................................................25232. MYLIB CSLCNTRL Expanded.................................................................................................................. 25333. LIBMAP MYLIB........................................................................................................................................25334. SEGMAP MYLIB.......................................................................................................................................25435. CSLCNTRL Example................................................................................................................................ 25436. LIBMAP Omitting NOAUTO..................................................................................................................... 25537. CSLCNTRL with INCLUDE Statements....................................................................................................25538. LIBMAP with NOAUTO and INCLUDE..................................................................................................... 25639. LOAD Sequence When NOAUTO is Not Used......................................................................................... 256

xiii

40. LOAD Sequence When NOAUTO is Used................................................................................................25641. LOAD Sequence When FILETYPE TXT is Used....................................................................................... 25742. LIBMAP with FILETYPE TXT................................................................................................................... 25743. CSLCNTRL Example with File Types Specified.......................................................................................25744. LOAD Sequence File Types in the Control File Are Used....................................................................... 25845. LIBMAP with FILETYPE TXT................................................................................................................... 25846. CSLCNTRL................................................................................................................................................25847. LIBMAP with NOAUTO............................................................................................................................ 25948. CSLCNTRL with INCLUDE Statements....................................................................................................25949. Example of Template Library (TEST TEMPLATE)................................................................................... 26150. A FORTRAN Program Called APPL1....................................................................................................... 26951. A FORTRAN Program Called APPL2....................................................................................................... 27052. Sample Run of APPL1............................................................................................................................. 27053. Sample Run of APPL2............................................................................................................................. 27154. Sequence of Instructions in Virtual Machine to Virtual Machine Communication................................28155. Updating Three SFS Files Using Coordinated Resource Recovery........................................................ 31156. OS/MVS Exit Availability and Clean-Up Behavior...................................................................................34157. Fixed-Length Records.............................................................................................................................35058. Fixed-Length ANSI Records................................................................................................................... 35159. Nonspanned, Format-V Records............................................................................................................ 35260. Nonspanned, Format-D Records for ANSI Tapes...................................................................................35361. Variable Spanned Records......................................................................................................................35562. Variable Spanned ANSI Records............................................................................................................ 35663. OS Simulated Block vs. CMS Record...................................................................................................... 36664. Using the BUILDRCD Macro and the Logical Record Interface............................................................. 37665. DCB Abend Exit (X'11') Parameter List.................................................................................................. 39066. FEOV LEAVE Positioning for ANSI and IBM Standard Labels................................................................ 39567. TVSPARMS Field Default values............................................................................................................. 39868. DOSTEST ASSEMBLE.............................................................................................................................. 48769. GETMACS ESERV, an ESERV file you need to assemble........................................................................ 487

xiv

List of Tables

1. Comparison of CMS Virtual Machine Architectures......................................................................................42. CMS Preferred Macros...................................................................................................................................63. CMS Preferred Functions............................................................................................................................ 104. CMS Compatibility Macros and Suggested Replacements........................................................................ 105. CMS Functions and Suggested Replacements........................................................................................... 116. Simulated OS/MVS Macros......................................................................................................................... 117. CMS Preferred Interface I/O Macros.......................................................................................................... 298. System/370, 370-XA, and ESA/XC I/O Commands................................................................................... 309. Program Invocation Call Type Options....................................................................................................... 4410. CMSCALL Call Chart.................................................................................................................................. 4511. SVC 202 Call Chart.................................................................................................................................... 4612. Register Contents When Called Routine Starts........................................................................................4813. Settings When A Called Routine Starts.................................................................................................... 4814. USECTYP Values........................................................................................................................................4915. Types of Subpools..................................................................................................................................... 5816. How CMS Releases Free Storage..............................................................................................................6017. Return Codes for SEGMENT LOAD Macro.................................................................................................7618. Return Codes for SEGMENT FIND Macro................................................................................................. 7719. Return Codes for SEGMENT PURGE Macro.............................................................................................. 7720. Maximum Data Bytes You Can Print....................................................................................................... 14721. Parameter List Layout............................................................................................................................. 16122. Replacing SSM Instructions with ENABLE Macros................................................................................ 17323. Macros and the Resource the SYSTEM Parameter Saves......................................................................20424. Program Attribute Default Values...........................................................................................................21525. Where CMS Loads Programs...................................................................................................................22226. Contents of registers...............................................................................................................................28327. Summary of APPC/VM Assembler Macro Functions..............................................................................30528. MVS/XA Data Management Macros That CMS Simulates......................................................................32029. MVS/XA Supervisor Macros That CMS Simulates.................................................................................. 32830. TSO Macros That CMS Simulates........................................................................................................... 33431. Simulated OS/MVS Supervisor Calls...................................................................................................... 33532. SET STORECLR Command Setting..........................................................................................................33833. SET GETMAIN Storage Setting............................................................................................................... 33934. OS/MVS Terms and CMS Equivalents..................................................................................................... 34735. Segment Control Code for SDW..............................................................................................................35436. CMS Commands that Recognize OS/MVS Data Sets on OS/MVS Disks.................................................36837. Input File................................................................................................................................................. 37238. Input File................................................................................................................................................. 37239. Default Values for the Record Area........................................................................................................ 377

xv

40. Positioning of Files Opened and Closed with RDBACK..........................................................................37841. Determining BLKSIZE and LRECL on CMS DASD when either LRECL or BLKSIZE, or both, are

specified................................................................................................................................................... 38042. Determining BLKSIZE and LRECL on CMS DASD when neither LRECL nor BLKSIZE is specified........ 38143. OS/MVS Exit Routines Simulated in CMS............................................................................................... 38744. Format and Contents of an Exit List....................................................................................................... 38845. CMS/DOS Commands and CMS Commands with Special Operands.....................................................40446. VSE Macros Supported by CMS.............................................................................................................. 41847. Physical IOCS Macros Supported by CMS/DOS..................................................................................... 42848. SVC Support Routines and Their Operation........................................................................................... 42949. CMS/DOS Support of DTFCD Macro........................................................................................................43550. CMS/DOS Support of DTFCN macro....................................................................................................... 43651. CMS/DOS Support of DTFDI Macro........................................................................................................ 43752. CMS/DOS Support of DTFMT Macro....................................................................................................... 43853. CMS/DOS Support of DTFPR Macro........................................................................................................43954. CMS/DOS Support of DTFSD Macro........................................................................................................44055. OS Access Method Service Operands NOT Supported in CMS..............................................................47356. VSE Macros Normally Used with VSAM Macros..................................................................................... 47457. Unsupported Options of OS/VSAM Macros............................................................................................47558. VSE/VSAM to OS/VSAM Error and Return Code Mapping for OPEN Errors........................................... 47759. VSE/VSAM to OS/VSAM Error and Return Code Mapping for CLOSE Errors..........................................47960. DATA Management Request Error Return Code Mapping......................................................................480

xvi

About This Document

This document describes how you can use the facilities of the IBM® z/VM® Conversational Monitor System(z/VM CMS) to develop and manage assembler application programs.

Intended AudienceThis information is for assembler language application and system programmers who want to developprograms in the ESA/390™ or ESA/XC environment.

This information assumes that the reader has experience writing and running assembler languageprograms and that the reader is familiar with z/VM CMS. It also assumes the reader is somewhat familiarwith ESA/XC architecture, which is defined in z/VM: ESA/XC Principles of Operation.

Where to Find More InformationFor information about related publications, see the “Bibliography” on page 507.

Links to Other Documents and WebsitesThe PDF version of this document contains links to other documents and websites. A link from thisdocument to another document works only when both documents are in the same directory or database,and a link to a website works only if you have access to the Internet. A document link is to a specificedition. If a new edition of a linked document has been published since the publication of this document,the linked document might not be the latest edition.

© Copyright IBM Corp. 1990, 2018 xvii

xviii z/VM: CMS Application Development Guide for Assembler

How to Send Your Comments to IBM

We appreciate your input on this publication. Feel free to comment on the clarity, accuracy, andcompleteness of the information or give us any other feedb