SC24 5286 0_VM_SP_CMS_for_System_Programming_Release_5_Dec86 0 VM SP CMS For System Programming Release 5 Dec86
User Manual: SC24-5286-0_VM_SP_CMS_for_System_Programming_Release_5_Dec86
Open the PDF directly: View PDF .
Page Count: 450
Download | ![]() |
Open PDF In Browser | View PDF |
-- --..---- ----. ---------~-,- Virtual Machine/ System Product eMS forr Slfs~em rP>rrog]rrammoD1lg Release 5 SC24-5286-0 I", ,,' ," .,'I! I",i,,:.l r,' " I 1 , 1 •• ,1',(',. First Edition (December 1986) This edition, SC24-5286-0, applies to Release 5 of IBM Virtual Machine/System Product (VM/SP) (program number 5664-167) unless otherwise indicated in new editions or Technical Newsletters. It contains material formerly found in the VM/SP System Programmers Guide, SC19-6203 and the VM/SP eMS User's Guide, SC19-6210. Changes are made periodically to the information herein; before using this publication in connection with the operation of IBM systems, consult the latest IBM System/370, 30xx, and 4300 Processors Bibliography, GC20-0001, for the editions that are applicable and current. Summary of Changes For a detailed list of changes, see page "Summary of Changes" on page 379. Changes or additions to the text and illustrations are indicated by a vertical line to the left of the change. References in this publication to IBM products, programs, or services do not imply that IBM intends to make these available in all countries in which IBM operates. Any reference to an IBM licensed program in this publication is not intended to state or imply that only IBM's licensed program may be used. Any functionally equivalent program may be used instead. Ordering Publications Requests for copies of IBM publications should be made to your IBM representative or to the IBM branch office serving your locality. Publications are not stocked at the address given below. A form for readers' comments is provided at the back of this publication. If the form has been removed, comments may be addressed to IBM Corporation, Information Development, Dept. G60, P.O. Box 6, Endicott, New York, U.S.A. 13760. IBM may use or distribute whatever information you supply in any way it believes appropriate without incurring any obligation to you. © Copyright International Business Machines Corporation 1986 - ,. ':'-") l')r '-"'l',""'1 (!";"--.J 1 U \..jUl.. This publication describes reference information about the functions of the Conversational Monitor System (CMS) component of VM/SP. The information is intended for system programmers, system analysts, and programming personnel. Knowledge of Basic Assembler language and experience with programming concepts and techniques are prerequisites to using this publication. This publication is one of a set of reference manuals for VM/SP system programmers. The other books in the set include: o o o o o VM/ SP CP for System Programming VM/ SP Group Control System Command and Macro Reference VM/ SP Transparent Services Access Facility Reference VM System Facilities for Programming VM Diagnosis Guide The order numbers for these books and related publication can be found under "Bibliography" in the back of this manual. Some of the topics discussed in this publication are: o o o o o o o o o o o o o o o Processing abends Handling interrupts Using storage Developing and executing programs Linkage conventions Updating programs Developing commands and messages Developing as programs Developing VSE programs Using VSAM functions Tailoring your CMS system Using the batch facility U sing auxiliary directories Understanding assembler virtual storage requirements CMS macro library After the appendices, the following sections are available to help you use this manual more easily: o o o o "Summary of Changes" "Glossary of Terms and Abbreviations" "Bibliography" "Index" Preface 111 1v VM/SP eMS for System Programming Chapter 1. IntrouucinG crllS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The CMS Command Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The File System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Preferred Filetypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Program Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. 1 1 2 3 4 Chapter 2. Proccooill[J Abcndo . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Abend Exit Routine Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 CMS Abend Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 Chapter 3. Handline Int3i'rupto in CIH8 . . . . . . . . . . . . . . . . . . . . . D SVC Interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Internal Linkage SVCs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Other SVCs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Input/Output Interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Terminal Interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Reader/Punch/Printer Interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 User-Controlled Device Interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 Program Interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 External Interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Machine Check Interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Chapter 1. Using StoraGe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Structure of CMS Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. Structure of DMSNUC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . User and Transient Program Areas . . . . . . . . . . . . . . . . . . . . . . . . . . Managing CMS Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . GETMAIN Free Storage Management . . . . . . . . . . . . . . . . . . . . . . . . DMSFRE Free Storage Management . . . . . . . . . . . . . . . . . . . . . . . . . DMSFRE Service Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Error Codes from DMSFREE, DMSFRES, and DMSFRET ......... Storage Protection Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CMS Handling of PSW Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 15 21 23 23 Chapter 5. DevelopinG Pror:;rnn:ls under CI1;IS •.......•••....•• Program Linkage (SVC Handling) .........'.................... Register Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ,......... Parameter LIsts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Common SVC Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Search Hierarchy for SVC 202 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Dynamic Linkage/SUBCOM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Returning to the Calling Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . The CMS Subset Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Assembling Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Executing Programs .......... "............................. Executing TEXT Files ...... : . . . . . . . . . . . . . . . . . . . . . . . . . . . . . '.13 43 43 46 48 54 59 61 64 65 66 67 Contents V 24 27 35 37 38 39 Resolving External References .............................. Controlling the CMS Loader ............................... Creating Program Modules ................................. The Transient Program Area ............................... Creating EXEC Procedures ................................. CMS Macro Instructions .................................... Disk File Manipulation ................................... Terminal Communications ................................. Unit Record and Tape I/O .................................. Handling Interrupts ...................................... System Product Editor Interface to Access Files in Storage .......... CMS Interface for Display Terminals ........................... The CONSOLE Macro .................................... The DISPW Macro ....................................... 68 68 71 '72 73 75 75 84 85 85 86 88 90 93 Chapter G. Updating Source Profjrnms Using Cn1S •••••••••••• 95 The UPDATE Philosophy .................................. 95 Update Files ............................................ 96 Sequencing Output Records ................................ 99 Multiple Updates ....................................... 102 Multiple Updates with XEDIT ............................. 107 The VMFASM EXEC Procedure ............................ 109 Updating EXECs and Macros ............................. . 110 The STK Option ....................................... . 111 vi 113 Chapter 7. Developincr Commando and n·1emJage Files . . . . . . . . Using the Parsing Facility ................................. Advantages of the Parsing Facility ......................... Advantages of DLCS .................................... Overview ............................................. Supported CMS Commands ............................... Coding Your Own Command Syntax with DLCS .............. DBCS and the Parsing Facility ............................ Examples: Using the Parsing Facility ....................... Creating and Distributing Your Own CMS Commands .......... Using Message Repository Files ............................. Overview of Creating and Using a Message Repository ......... Rules for Making Your Own Repository ..................... Substitution in Messages ................................ Dictionary Substitution ................................. Creating Your Own CMS Messages ........................ Creating Your Own HELP Files ........................... Making Your Messages Available to Others .................. Creating Immediate Commands ............................. . . . . . . . . . . . . . . . . . . . Chapter fl. Developing OS Programs under cn~s ............ Using OS Data Sets in CMS ................................ OS Simulated Data Sets ............ ~ .................... Restrictions for Reading OS Data Sets ...................... The ACCESS Command ................................. The FILEDEF Command ................................ Creating CMS Files from OS Data Sets ..................... Using CMS Libraries ..................................... . 157 VM/SP eMS for System Programming . . . . . . . 113 113 113 114 116 117 130 131 144 145 146 148 151 151 153 154 154 154 159 160 161 161 162 169 171 / Macro Libraries (MACLIBs) ............................... TEXT Libraries (TXTLIBs) ................................ OS Module Libraries and CMS LOADLIBS ................... The LKED Command .................................... OS Data Management Simulation ............................. Handling Files that Reside on CMS Disks .................... Handling Files that Reside on OS Disks ...................... Simulating OS Supervisor Calls ............................ OS Macros ............................................ Access Method Support .................................. Reading OS Data Sets Using OS Macros ..................... OS Tape Volume Switching ................................. 172 181 183 186 188 188 189 189 191 199 203 204 Chapter D. Developing VSE ProgrnmG under Cll,lS . . . . . . . . . . . . Entering the CMS/DOS Environment .......................... DL/I in the CMS/DOS Environment ......................... Using DOS Files on DOS Disks .............................. Reading DOS Files ...................................... Creating CMS Files from DOS Libraries ..................... The ASSGN Command ..................................... Assigning System Logical Units ............................ Compiler I/O Assignments ................................ Manipulating Device Assignments .......................... Listing I/O Assignments .................................. Virtual Machine Assignments ............................. The DLBL Command ...................................... Entering File Identifications .............................. Clearing and Displaying File Definitions ..................... Using DOS Libraries in CMS/DOS ............................ The SSERV Command ................................... The RSERV Command ................................... The PSERV Command ................................... The ESERV Command ................................... The DSERV Command ................................... The DOSLKED Command ................................. DOS Core Image Libraries ................................ Using Macro Libraries ..................................... Creating CMS MACLIBs ................................. The MACLIB Command .................................. Manipulating MACLIB Members ........................... The MACLIST Command ................................. The GLOBAL Command .................................. System MACLIBs ....................................... VSE Assembler Language Macros Supported .................... Assembling Source Programs ................................ Link-editing Programs in CMS/DOS ........................... Linkage Editor Input .................................... Linkage Editor Output: CMS DOSLIBs ...................... Executing Programs in CMS/DOS ............................ Executing DOS Phases ................................... Search Order for Executable Phases ......................... Making I/O Device Assignments ............................ Specifying a Virtual Partition Size .......................... Setting the UPSI Byte ................................... 207 208 210 211 212 213 214 215 216 217 217 218 218 219 220 220 221 222 222 223 224 225 225 225 225 227 230 231 235 235 236 238 240 241 242 243 244 244 245 246 247 Contents VB Debugging Programs in CMS/DOS ......................... U sing EXEC Procedures in CMS/DOS ...................... Hardware Devices Supported ............................... VSE Supervisor and I/O Macros Supported by CMS/DOS ......... Supervisor Macros .............................. ; ...... Declarative Macros (Sequential Access Method I/O Macros) ..... Imperative Macros (Sequential Access Method I/O Macros) ..... VSE Transient Routines ................. ~ ................. EXCP Support in CMS/DOS .................... ~ ........... VSE Supervisor Control Blocks Simulated by CMS/DOS .......... CMS/DOS User Considerations and Responsibilities ............. VSE System Generation and Updating Considerations .......... VM/SP Directory Entries ................................ When the VSE System Must be Online ...................... Performance .......................................... Execution Considerations and Restrictions . . . . . . . . . . . . . . . Chapter 10. U sine; 11cCCSG n~ethod Serviccs and VSArlI under CDfl:S nnd eMS/DOS ....•..... Executing VSAM Programs Under CMS ........ The AMSERV Command ............................ AMSERV Output Listings ............................... . Controlling AMSERV Command Listings ............ Manipulating OS and DOS Disks for Use with AMSERV ...... Data and Master Catalog Sharing ......... '................ . Disk Compatibility ................................ Allocating Space ....................................... . Using VM/SP Minidisks ................................. . The LISTDS Command ........................... Using Temporary Disks ................................. . Defining DOS Input and Output Files ................... Using VSAM Catalogs .................................. . Using Job Catalogs ............................ Catalog Passwords ...................................... . Verifying A Catalog Structure ............................ . Defining and Allocating Space for VSAM files ................ . Using Tape Input and Output ............................ Defining OS Input and Output Files .......................... . Allocating Extents on OS Disks and Minidisks ............... . Using VSAM Catalogs .................................. . U sing a Job Catalog ..................................... . Catalog Passwords .......................... Verifying a Catalog Structure ............................ . Defining and Allocating Space for VSAM files .. '.............. . U sing Tape Input and Output ............................. . Using AMSERV under CMS ................................ . The DEFINE and DELETE Functions .............. The REPRO, IMPORT, and EXPORT (or EXPORTRA/IMPORTRA) Functions ........................... '................ . Writing EXECs for AMSERV and VSAM ............. ISAM Interface Program (TIP) .............................. . VSE/VSAM Macros Supported .............................. . Obtaining the VSE/VSAM Macros ............. 0 0 •••••••••• 0 •• 0 0 •••• 0 •••• ••••••• 0 0 0 •• •••• 0 •• ••••• 0 •• 0 0 0 •••• ••••• •••• 0 0 0 •••••• 0 •• ••••• ••••••••• 0 0 ••••••••••• 0 •••••••• 0 0 viii VM/SP eMS for System Programming • •• 0 ••••••• •••• 0 •••• 247 247 249 249 250 258 267 268 269 269 270 270 271 271 272 272 273 274 276 277 277 278 279 280 280 281 281 283 284 285 288 289 289 290 292 294 295 296 299 299 300 300 303 304 305 307 309 310 311 311 I I I I I· I I I I I I I I I VSE Supervisor Macros and Logical Transients Support for VSAM OSjVSAM Macros Supported in CMS ......................... OSjVSAM Error Codes ................................... Hardware Devices Supported ................................ 312 312 316 319 Ch:'lptCl' 11. r.l'~lilol'h1~ Your Crl18 Syotcnl . . . . . . . . . . . . . . . . . . . Saving the CMS System .................................... Saved System Restrictions for CMS ......................... Using the System Profile, SYSPROF EXEC, for Tailoring .......... What the System Profile Does ............................. Invoking the IPL CMS Command ........................... How to Save a Named System .............................. How to Create or Change SYSPROF EXEC ................... How to Bypass the System Profile .......................... Setting Up a Protected Application Environment ............... What the System Profile Can Do for Installations .............. Sharing File Directory Information ........................... The SAVEFD Command .................................. Putting File Directory Information into Shared Storage ......... Usage Notes ........................................... Messages and Return Codes ............................... Sharing EXECs and Editor Macros ........................... 321 Chaptc~:...· 12. uoinG th'c CE.J8 Batch :i?acility . . . . . . . . . . . . . . . . . . Install,ing the CMS Batch Machine ........................... Resetting the CMS Batch Facility System Limits ................. Writing Routines To Handle Special Installation Input ............ BATEXIT1: Processing User-Specified Control Language ........ BATEXIT2: Processing the Batch Facility jJOB Control Card ..... EXEC Procedures for the Batch Facility Virtual Machine .......... Data Security under the Batch Facility ........................ Improved IPL Performance Using a Saved System ................ 333 334 335 335 335 335 336 336 336 .ch~l::r(;:)r 1:3. ULiinC; l .. u::iliary Directories ................... Adding an Auxiliary Directory ............................... Generating the Auxiliary Directory ......................... Initializing the Auxiliary Directory ......................... Establishing the Proper Linkage ........................... Creating an Auxiliary Directory .............................. 339 339 339 340 341 342 321 322 322 322 323 325 325 327 327 328 328 329 330 330 331 331 CIU121tCl' Id. Vntlcl'st.:uulin[; ASSc.Glbler Virtual Storage ~:Jqt-!il'C111ClltG • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • 345 Overlay Structures ........................................ 345 Pre structured Overlay ................................... 346 Dynamic Load Overlay ................................... 347 APP:JIUli::8S i:.PPclldi:: iL ,::;1',;18 Ivlam.'o Library Appcndi:: n. . . . . . . . . . . . . . . . . . • . . . . . . . 351 Snn1plc Tcrnlinal Session for as Progralnlners A::'lL:Jcndi:: C. Sarnplc ri'ol.·lnillul Session for DOS Pl'ogl'UInn'lerS ... 355 .. 3Gl Contents IX Appendhr D. Sample Terminal Session Using Access r/lethod Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369 Summary of Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Structural Changes ...................................... Technical Changes for VM System Facilities for Programming .... Summary of Changes for the VMjSP System Programmer's Guide .. 379 379 381 383 Glossary of Terms anel Abbreviations . . . . . . . . . . . . . . . . . . . . . arm Abbreviations ............................................ 389 Glossary ................................................ 391 BibliograIlhy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . aD5 Indel: . . • . . . . . . . . . . . . . . . . . . . • . . . . . . . . . . . . . . . . • . . . . . . .::101 x VM/SP C:r\1:S for System Programming 1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12. 13. 14. 15. 16. 17. 18. 19. 20. 21. 22. 23. 24. 25. 26. 27. 28. 29. 30. 31. 32. 33. 34. 35. 36. 37. 38. 39. 40. CMS Storage Map 1 .................................... 18 CMS Storage Map 2 .................................... 19 CMS Storage Map 3 .................................... 20 Devices Supported by a CMS Virtual Machine ............... 22 Register Contents When Called Routine Starts ............... 45 PSW Fields When Called Routine Starts .................... 45 SVC 202 High-Order Byte Values of Register 1 ............... 49 CMS Command Processing ............................... 57 SVC 202 Processing .................................... 58 FSCB Format ......................................... 75 A Sample Listing of a Program that Uses CMS Macros ......... 83 Updating Source Files with the UPDATE Command .......... 100 An Update with a Control File ........................... 106 Sample REXX Program 1 ............................... 135 Sample REXX Program 2 ................................ 136 Sample Assembler Program 1 ............................ 138 Sample Assembler Program 2 ............................ 140 as Terms and CMS Equivalents ......................... 158 CMS Commands that Recognize as Data Sets on as Disks ..... 159 Creating CMS Files from as Data Sets .................... 171 Sample MACLlST Screen ............................... 177 Simulated as Supervisor Calls ........................... 189 CMS/DOS Commands and CMS Commands with Special Operands 209 Sample MACLlST Screen ............................... 232 VSE Macros Supported by CMS .......................... 237 Physical laCS Macros Supported by CMS/DOS .............. 250 SVC Support Routines and Their Operation ................ 250 CMS/DOS Support of DTFCD Macro ...................... 259 CMS/DOS Support of DTFCN macro ...................... 261 CMS/DOS Support of DTFDl Macro ...................... 261 CMS/DOS Support of DTFMT Macro ...................... 263 CMS/DOS Support of DTFPR Macro ...................... 264 CMS/DOS Support of DTFSD Macro ...................... 265 Options of OS/VSAM Macros Supported in CMS ............. 313 VSE/VSAM to OS/VSAM Error and Return Code Mapping for OPEN Errors ........................................ 316 VSE/VSAM to OS/VSAM Error and Return Code Mapping for CLOSE Errors ....................................... 318 DATA Management Request Error Return Code Mapping ...... 319 Parameters Passed to SYSPROF EXEC .................... 326 An Overlay Structure .................................. 346 New VM/SP System Programming Manuals for VM/SP Release 5 380 Figures Xl Xll VM/SP eMS for System Programming I I r. ---------- ------- ---- - - - - - --- - - -- ----------------------------.------------------ l The Conversational Monitor System (CMS), the major subsystem of VM/SP, provides a comprehensive set of conversational facilities to the user. Several copies of CMS may run under CP, thus providing several users with their own time sharing system. CMS is designed specifically for the VM/SP virtual machine environment. Each copy of CMS supports a single user. This means that the storage area contains only the data pertaining to that user. Likewise, each CMS user has his own machine configuration and his own files. This makes debugging simpler because the files and storage area are protected from other users. Programs can be debugged from the terminal. The terminal is used as a printer to examine limited amounts of data. After examining program data, the user can enter commands on the terminal that will alter the program. This is the most common method used to debug programs that run in CMS. CMS, operating with the VM/SP Control Program (CP), is a time sharing system suitable for problem solving, program development, and general work. It includes several programming language processors, file manipulation commands, utilities, and debugging aids. Additionally, CMS provides facilities to simplify the operation of other operating systems in a virtual machine environment when controlled from a remote terminal. For example, CMS creates and modifies job streams and analyzes virtual printer output. Part of the CMS environment is related to the virtual machine environment created by CPo Each user is completely isolated from the activities of all other users, and each machine where CMS executes has virtual storage available to it and virtual storage managed for it by CPo The CP commands are recognized by CMS. For example, the commands allow messages to be sent to the operator or to other users and allow virtual devices to be dynamically detached from the virtual machine configuration. The eMS Command Language The CMS command language offers terminal users a wide range of functions. It supports a variety of programming languages, service functions, file manipulation, program execution control, and general system control. The CMS commands that are useful in debugging are discussed in the VM Diagnosis Guide manual. For detailed information on all other CMS commands, refer to the VM/SP CMS Command Reference. Chapter 1. Introducing CMS 1 ~[juHu~0)C)Jt:.D~UfJllCj G~v~8 c:::::-:-_===-----:=:-~_ .... _._ ...... _. ~=-==--===-=-.~:~~=:.~= . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . _. . . ._. . . . . . . - - - - - . - - - - - - - - - . . J The File System The Conversational Monitor System interfaces with virtual disks, tapes, and unit record equipment. The CMS residence device is a read-only, shared system disk. Permanent user files may be accessed from up to 25 active disks. CMS controls logical access to these virtual disks while CP facilities manage the device sharing and virtual-to-real mapping. User files in CMS are identified with three designators: o A filename o A filetype implying specific file characteristics to the CMS file management routines. o A filemode describing the location and access mode of the file. User files can be created and changed directly from the terminal with the VM/SP System Product Editor (XEDIT). XEDIT provides extensive context editing services. File characteristics such as record length, record format, tab locations, and serialization options can be specified. See VM/ SP System Product Editor Command and Macro Reference for more information on XEDIT. The size of user files is determined by the blocksize (BLKSIZE). For disks with a blocksize of 800 bytes, a single user file is limited to a maximum of 65,533 records and must reside on one virtual disk. The file management system limits the number of files on the virtual disk to 3400. When a blocksize of 512, 1024, 2048, or 4096 bytes is specified, a single user file is limited to a maximum of 231_1 CMS records and must reside on one virtual disk. The maximum number of data blocks available in a variable format file on a 512-byte blocksize mini disk is about 15 times less than 231_1. This number is the maximum number of data blocks that can be accessed by the CMS file system due to the 5 level tree structure. The maximum number of files on anyone disk is limited by the file management system to 231_1. However, the actual number of files on a disk is limited by the available disk space and the size of the user's files. When you access a read-only disk, a hyperblock mapping table (HYPMAP) is built. When you access a read/write disk, a hash table complex (HASHTAB) is built. (For further details on HYPMAP and HASHTAB, see the VJ\lI/SP Data Areas and Control Block Logic Volume 2 (CMS) manual.) These two tables decrease the paging overhead when searching for files. However, the hyperblock mapping table is not built if the hyperblocks for the disk do not span three or more pages. The hash table is not built if the hyperblocks for the disk do not span two or more pages. CMS automatically allocates compiler work files at the beginning of command execution on whichever active disk has the greatest amount of available space, and CMS deallocates them at completion. Compiler object decks and listing files are normally allocated on the same disk as the input source file or on the primary read/write disk, and are identified by 2 VM/SP eMS for System Programming combining the input filename with the filetypes TEXT and LISTING. These disk locations may be overridden by the user. Virtual disks may be shared by CMS users. This capability is provided by VM/SP to all virtual machines. Specific files may be spooled between virtual machines to accomplish file transfer between users. Commands allow such file manipulations as writing from an entire disk or from a specific disk file to a tape, printer, punch, or the terminal. Other commands write from a tape or virtual card reader to disk, rename files, copy files, and erase files. Special macro libraries and text or program libraries are provided by CMS, and special commands are provided to update and use them. CMS files can be written onto and restored from unlabeled tapes via CMS commands. Caution: Multiple write access under CMS can produce unpredictable results. Problem programs that execute in CMS can create files on unlabeled tapes using any record length and blocksize; the record format can be fixed, variable, or undefined. IPreierred FileRl'pes CMS has a list of preferred filetypes. This list consists of filetypes that are frequently searched for, but rarely found on your disk. The list of preferred file types is as follows: EXEC MODULE CMSUTl AUTOSAVE XEDTEMP XEDIT SYSUTl TEXT The active disk table (ADT) contains a byte signalling which preferred filetypes are on the disk. Before scanning the file management tables for a file, this byte is examined to see if any files of the desired type are present on the disk. This process avoids searching for a file that is not on the disk; therefore, improving system performance. For example, if you are looking for a file with one of the preferred filetypes and the byte in the ADT indicates that the filetype is not on the disk, then you will avoid searching the disk for the file. Performance may be improved by keeping preferred filetypes together on separate disks. Chapter 1. Introducing CMS 3 ~u-u~~1QJ(~QJcnuuCj C~~JJ~) . . .. [.~:~ ~:: -:--~ . . -...--:--:--:--._-------_._._-_.-_. _--_.__. _ ._-_._._-_. _---..__. _ ._ . . ---. _.- -. _. . _._._ . ._ . -._-. -_._- . -_._. . _._. . __. . . -------.-.. . _. _-_._-_. _._. ._--_._--""] --.-.-~.=.- Program Development The Conversational Monitor System includes commands to create, compile, modify, and correct source programs; to build test files; to execute test programs; and to debug from the terminal. The commands of CMS are especially useful for OS and VSE program development, but the commands also may be used in combination with other operating systems to provide a virtual machine program development tool. eMS uses the OS and VSE compilers via interface modules. The compilers themselves normally are not changed. To provide suitable interfaces, CMS includes a certain degree of OS and VSE simulation. For OS, the sequential, direct, and partitioned access methods are logically simulated. The data records are physically kept in the chained fixed-length blocks, and they are processed internally to simulate OS data set characteristics. For VSE, the sequential access method is supported. CMS supports VSAM catalogs, data spaces, ~nd files on OS and DOS disks using the Access Method Services portion of VSE/VSAM. OS Supervisor Call functions such as GETMAIN/FREEMAIN and TIME are simulated. The simulation restrictions concerning what types of OS object programs can be executed under CMS are primarily related to the OS/PCP, MFT, and MVT Indexed Sequential Access Method (ISAM) and the telecommunications access methods. Functions related to multitasking in OS and VSE are ignored by CMS. For more information, see "OS Data Management Simulation" on page 188 and "Chapter 9. Developing VSE Programs under CMS" on page 207. 4 VM/SP eMS for System Programming When CMS abnormally terminates, the following steps are taken: 1. After checking for any SPIE, STXIT PC, STAE, or STXIT AB exits that apply, CMS calls DMSABN, the abend recovery routine. 2. Before typing out any abend message at the terminal, DMSABN, the abend recovery routine, checks for any abend exit routines, set by the ABNEXIT macro. 3. If a list of exit routines exists, the current abend exit routine (that is, the last one set) gains control. If no abend exit. routines exist, CMS abend recovery occurs. Abend E,dt Routine Processing An abend exit routine may be established to intercept abends before CMS abend recovery begins. You must provide the proper entry and exit linkage for this abend exit routine. See the ABNEXIT macro in the VM/SP eMS Macros and Functions Reference for details on the register contents when the routine receives control. The abend exit routine receives control with the nucleus protect key and is disabled for interrupts. Information about the abend is available to the exit routine in the DMSABW CSECT in DMSNUC. The address of this area is passed to the exit routine via register 1. In addition to the information currently available in DMSABW, a fullword specified on the ABNEXIT macro contains information for the exit's own purposes. ABUWRD is the name of the fullword containing the information the user enters in the UWORD parameter of the ABNEXIT macro. An abend exit routine may choose to avoid CMS abend recovery and continue processing normally. To do this, the exit must issue the ABNEXIT RESET macro. This tells CMS to clear the abend condition. The exit routine may also return to CMS to continue abend processing. If the exit routine returns to CMS and another abend exit routine exists, it is given control next. Each exit on the list is given control in sequence until all the exits have been given control or until an exit chooses to avoid CMS abend recovery, by issuing ABNEXIT RESET, and continues processing. If a program check occurs in the exit routine and ABNEXIT RESET was not issued in this exit routine, DMSABN gives control to the next exit Chapter 2. Processing Abends 5 .._..... _.....:~-=-J routine on the list. If no other exit routine exists, CMS abend recovery occurs. You cannot set or clear abend exit routines in an abend exit routine. You can reset an abend exit routine only in an exit routine. eMS Abend Recovery If no abend exit routine exists or if the abend exit routine returns to CMS to continue abend processing, DMSABN types out the abend message followed by the line: eMS This line indicates to you that the next command can be entered. Options available to you are: o Issue the DEBUG command. DMSABN passes control to DMSDBG to make the facilities of DEBUG available. DEBUG's PSW and registers are as they were at the time the recovery routine was invoked. In DEBUG mode, you may alter the PSW or registers. Then, type GO to continue processing, or type RETURN to return to DMSABN·. DMSABN continues the abend recovery. o Issue any command (other than DEBUG). DMSABN performs its abend recovery function and passes control to DMSINT to execute the command that was typed in. The abend recovery function performs the following, in sequence: 1. Clears the console input buffer and program stack. 2. Terminates all VMCF activity. 3. Reinitializes the work area stack for reentrant CMS nucleus modules. 6 4. Reinitializes the SVC handler, DMSITS, and frees all stacked save areas. 5. Clears the auxiliary directories, if any. Invokes "FINIS * * *", to close all files, and to update the master file directory. 6. Frees storage, if the DMSEXT module is in virtual storage. 7. Zeroes out the MACLIB directory pointers. 8. Frees the CMS work area, if the CMS subset was active. 9. Frets the RLDDATA buffer, used by the CMS loader to retain relocation information for the GENMOD process, if it is still allocated. VM/SP eMS for System Programming ./ 10. Issues the STAE, SPIE, TTIMER, and STAX macros to cancel any outstanding OS exit routines. Frees any TXTLIB, MACLIB, or LINK tables. 11. Calls with a purge PLIST, all nucleus extensions that have the "SERVICE" attribute defined. 12. Drops all nucleus extensions that do not have the "SYSTEM" attribute. Also drops any nucleus extensions that are in type user storage. 13. Drops all SUB COM SCBLOCKS that do not have the "SYSTEM" attribute. 14. Frees console path and device entry control blocks. 15. Drops all storage resident execs that do not have the "SYSTEM" attribute. 16. Clears all immediate commands that are not nucleus extensions with the "SYSTEM" attribute; returns all associated free storage. 17. Calls DMSCLN to zero out the userword of the SRPI command. 18. Calls DMSWITAB to delete all windows and vscreens that do not have the "SYSTEM" attributes. 19. Resets the storage keys for the whole virtual machine, except the nonshared pages, according to FREETAB. Saves the setting for KEYPROTECT. 20. Zeroes out all FCB, DOSCB, and LABSECT pointers. 21. Frees all storage of type user. 22. Restores the setting for KEYPROTECT. 23. Zeroes out all interrupt handler pointers in IOSECT. 24. Turns the SVCTRACE command off. 25. Closes the virtual punch and printer; closes the virtual reader with the HOLD option. 26. Reinitializes the VSE lock table used by CMS/DOS and CMS/VSAM. 27. Zeroes out all OS loader blocks, and frees the FETCH work area. 28. Cleans up the CMS IUCV environment based on the existence of the CMS id block. 29. Clears all ABNEXIT set and returns storage. Chapter 2. Processing Abends 7 __-._-.. -. L~._-_-_---_--_-----------------------------.-_._-_-_- ------------------------------------~ 30. Computes the amount of system free storage that should be allocated and compares this amount with the amount of free storage actually allocated. Types a message to the user if the two amounts are unequal. 31. Issues a STRINIT and releases any pages remaining in the flush list via a call to DMSPAGFL, if all storage is accounted for. After abend recovery has completed, control passes to DMSINT at entry point DMSINTAB to process the next command. 8 VM/SP eMS for System Programming r----.--.--.--..--- ---.---.--..-.----..--.---.-.-- -.- --- . --.--.------.--.-..--.--.-.. -..--------- -..-.----.. --.--..--------------..---------.-----.. ---..-0-.--.-.-------..-.---------------.-II L CMS receives virtual SYC, input/output, program, machine, and external interruptions and passes control to the appropriate handling program. SVC Inierrupts The Conversational Monitor System is SYC (supervisor call) driven. SYC interruptions are handled by the DMSITS resident routines. Two types of SYCs are processed by DMSITS: internal linkage SYC 202 and 203, and any other SYCs. The internal linkage SVC is issued by the command and function programs of the system when they require the services of other CMS programs. (Commands entered by the user from the terminal are converted to the internal linkage SVC by DMSINT). The OS SYCs are issued by the processing programs (for example, the Assembler). Internal Lin!cage SVCs When DMSITS receives control as a result of an internal linkage SYC (202 or 203), it saves the contents of the general purpose registers, floating-point registers, and the SYC old PSW, establishes the normal and error return addresses, and passes control to the specified routine. (The routine is specified by the first 8 bytes of the parameter list whose address is passed in register 1 for SYC 202 or by a halfword code following SYC 203.) For SYC 202, if the called program is not found in the internal function table of nucleus (resident) routines, then DMSITS tries to call in a module (a CMS file with filetype MODULE) of this name via the LOADMOD command. If the program was not found in the function table, nor was a module successfully loaded, DMSITS returns an error code to the caller. To return from the called program, DMSITS restores the calling program's registers, and makes the appropriate normal or error return as defined by the calling program. See pages 48 and 52 for more details on SYC 202 and SYC 203. Chapter 3. Handling Interrupts in CMS 9 Other SVCs The general approach taken by DMSITS to process other SVCs supported under CMS is essentially the same as that taken for the internal linkage SVCs. However, rather than passing control to a command or function program, as is the case with the internal linkage SVC, DMSITS passes control to the appropriate routine. The SVC number determines the appropriate routine. In handling non-CMS SVC calls, DMSITS refers first to a user-defined SVC table (if one has been set up by the DMSHDS program). If the user-defined SVC table is present, any SVC number (other than 202 or 203) is looked for in that table. If it is found, control is transferred to the routine at the specified address. If the SVC number is not found in the user-defined SVC table (or if the table is nonexistent), DMSITS either transfers control to the CMSDOS shared segment (if SET DOS ON has been issued), or the standard, system table (contained in DMSSVT) of OS calls is searched for that SVC number. If the SVC number is found, control is transferred to the corresponding address in the usual manner. If the SVC is not in either table, then the supervisor call is treated as an abend call. The DMSHDS initialization program sets up the user-defined SVC table. The user can provide his own SVC routines by using the HNDSVC macro. Input/Output Interrupts All input/output interruptions are received by the I/O interrupt handler, DMSITI. DMSITI saves the I/O old PSW and the CSW (channel status word). It then determines the status and requirements of the device causing the interruption and passes control to the routine that processes interruptions from that device. DMSITI scans console facility device entries (CDEV) until it finds one containing the device address that is the same as the interrupting device. If a matching device is found and a CONSOLE 'path' is waiting for an interrupt: 1. The wait field is cleared in the device entry, 2. The wait bit is turned off in the I/O old PSW, and 3. DMSITI returns control to the console facility by loading the I/O old PSW. If no path is waiting, the interrupt is considered unsolicited and DMSITI checks for a user-defined interrupt handling routine. If DMSITI finds one, it passes control to the routine. Otherwise, if the device also exists in a console CDEV entry, DMSITI checks if any I/O was done and if an EXIT 10 VM/SP eMS for System Programming ,/ l_·_.._._. .=-=:::'=-=":'~:":~~":':"~-=~~=~::':~.':"-'-"::":"":.::':~::"'=:_~' ....-- -.-- --.. -.-_.. _ . -.-_.. -_.-_ ...._ ... _.. ..-.....-.. -.-.. -- --...---.-.----....--.-------..- - - - - - - -.. --.. - ..-.- ----::J routine is specified. If an EXIT can be called, DMSITI turns off the PSW wait bit, loads the PSW, and exits. If no console path performed I/O or no exits were called, the interrupt for the virtual console is passed to the system routine (DMSCITA) found in the CMS device table (DEVTAB). For dialed devices, the unsolicited interrupt is ignored. If fulls ere en CMS is on, attention interrupts for the virtual console are passed to a fullscreen read routine instead of DMSCIT A. The device table (DEVTAB) contains an entry for each device in the system. Each entry for a particular device contains, among other things, the address of the program that processes interruptions from that device. When the appropriate interrupt handling routine completes its processing, it returns control to DMSITI. At this point, DMSITI tests the wait bit in the saved I/O old PSW. If this bit is off, the interruption was probably caused by a terminal (asynchronous) I/O operation. DMSITI then returns control to the interrupted program by loading the I/O old PSW. If the wait bit is on, the interruption was probably caused by a nonterminal (synchronous) I/O operation. The program that initiated the operation most likely called the DMSIOW function routine to wait for a particular type of interruption (usually a device end). In this case, DMSITI checks the pseudo-wait bit in the device table entry for the interrupting device. If this bit is off, the system is waiting for some event other than the interruption from the interrupting device; DMSITI returns to the wait state by loading the saved I/O old PSW. (This PSW has the wait bit on.) If the pseudo-wait bit is on, the system is waiting for an interruption from that particular device. If this interruption is not the one being waited for, DMSITI loads the saved I/O old PSW. This again places the machine in the wait state. Thus, the program that is waiting for a particular interruption is kept waiting until that interruption occurs. If the interruption is the one being waited for, DMSITI resets both the pseudo-wait bit in the device table entry and the wait bit in the I/O old PSW. It then loads that PSW. This causes control to be returned to the DMSIOW function routine, which, in turn, returns control to the program that called it to wait for the interruption. Terminal Interrupts Terminal input/output interruptions are handled by the DMSCIT module. All interruptions other than those containing device end, channel end, attention, or unit exception status are ignored. If device end status is present with attention and a write CCW was terminated, its buffer is unstacked. An attention interrupt causes a read to be issued to the terminal, unless attention exits have been queued via the ST AX macro. The attention exit with the highest priority is given control at each attention until the queue is exhausted, then a read is issued. Chapter 3. Handling Interrupts in CMS 11 Device end status indicates that the last I/O operation has been completed. If the last I/O operation was a write, the line is deleted from the output buffer and the next write, if any, is started. If the last I/O operation was a normal read, the buffer is put on the finished read list and the next operation is started. If the read is caused by an attention interrupt, the line is first checked to see if it is an immediate command (user-defined or built-in). If it is a user-defined immediate command, control is passed to a user specified exit, if one exists. Upon completion, the exit returns to DMSCIT. If it is a built-in immediate command (HX, for example), appropriate processing is performed by DMSCIT. Unit exception indicates a canceled read. The read is reissued, unless it had been issued with ATTREST = NO, in which case unit exception is treated as device end. Reader/Punch/Printer !nterrupts Interruptions from these devices are handled by the routines that actually issue the corresponding I/O operations. When an interruption from any of these devices occurs, control passes to DMSITI. Then DMSITI passes control to DMSIOW, which returns control to the routine that issued the I/O operation. This routine can then analyze the cause of the interruption. User-Controlled Device Interrupis Interrupts from devices under user control are serviced the same as CMS devices except that DMSIOW and DMSITI manipulate a user-created device table, and DMSITI passes control to any user-written interrupt processing routine specified in the user device table. Otherwise, the processing program regains control directly. To handle unsolicited device interrupts, you may specify the EXIT parameter for the OPEN request of the CONSOLE macro instruction. If you specify this parameter, do NOT define an interruption routine via the HNDINT macro for the same device. Use of the CONSOLE macro with the use of HNDINT should be mutually exclusive. If for some reason there is both a CONSOLE EXIT and an HNDINT routine for the same device, the HNDINT routine overrides a CONSOLE EXIT only in the case of an unsolicited interrupt. The console facility supports multiple applications for a single device whereas HNDINT only allows one application to handle all interrupts from a specific device. Because it is difficult to tell what application is doing I/O last, the console facility helps CMS keep track of what application is doing I/O or what application handled interrupts last. 12 VM/SP eMS for System Programming ,~.~-.- I ---------..------------.-.--.-----------.-. __._--------_._-------_. .•... __ _---------------_ .. ...... _-- .- .] The CONSOLE macro supersedes an HNDINT routine when the interrupt is solicited. In most cases, a CONSOLE WAIT and CONSOLE READ can be issued instead of coding an HNDINT routine to handle all interrupts. Therefore, if you want to perform I/O to a 3270 device, you should use the CONSOLE macro instead of the HNDINT macro. Program Interrupts The program interruption handler, DMSITP, receives control when a program interruption occurs. When DMSITP gets control, it stores the program old PSW and the contents of the registers 14, 15, 0, 1, and 2 into the program interruption element (PIE). (The routine that handles the SPIE macro instruction has already placed the address of the program interruption control area (PICA) into PIE.) DMSITP then determines whether or not the event that caused the interruption was one of those selected by a SPIE macro instruction. If it was not, DMSITP passes control to the DMSABN abend recovery routine. If the cause of the interruption was one of those selected in a SPIE macro instruction, DMSITP picks up the exit routine address from the PICA and passes control to the exit routine. Upon return from the exit routine, DMSITP returns to the interrupted program by loading the original program check old PSW. The address field of the PSW was modified by a SPIE exit routine in the PIE. External Interrupts An external interruption causes control to be passed to the external interrupt handler DMSITE. If CMS IUCV support is active in the virtual machine and an IUCV external interrupt occurs, control is passed to the user exit specified on the HNDIUCV or CMSIUCV macro. If the user has issued the HNDEXT macro to trap external interrupts, DMSITE passes control to the user's exit routine. If the interrupt was caused by the timer, DMSITE resets the timer and types the BLIP character at the terminal. The standard BLIP timer setting is two seconds, and the standard BLIP character is uppercase, followed by the lowercase (it moves the typeball without printing). Otherwise, control is passed to the DEBUG routine. Machine Check Interrupts Hard machine check interruptions on the real processor are not reflected to a CMS virtual user by CPo A message prints on the console indicating the failure. The user is then disabled and must IPL CMS again to continue. Chapter 3. Handling Interrupts in CMS 13 14 VM/SP OMS for System Programming ,---------- ©-~~~~r ri!I' (~§"lnJJ,1 @(~Jr~~' L . _ - - - - The most important thing to remember about eMS, from a debugging standpoint, is that it is a one-user system. The supervisor manages only one user and keeps track of only one user's file and storage chains. Thus, everything in a dump of a particular machine relates only to that virtual machine's activity. Stor~ge Structure of Cf.1S Figures 1, 2, and 3 on pages 18, 19, and 20 describe how CMS uses its virtual storage. The pointers indicated (MAINSTRT, MAINHIGH, and FREELOWE) are all found in NUCON (the nucleus constant area). The sections of CMS storage have the following uses: o DMSNUC (X'OOOOO' to ANUCEND). This is the nucleus constant area. It contains system control blocks, pointers, flags, and other data updated by the various system routines. .. Low-Storage DMSFREE User Free Storage Area (ANUCEND to X'OEOOO'). This area is a free storage area where user requests to DMSFREE are allocated. o Transient Program Area (X'OEOOO' to X'lOOOO'). Since it is not essential to keep all nucleus functions resident in storage all the time, some of them are made "transient." This means that when nucleus functions are needed, they are loaded from the disk into the transient program area. Such programs may not be longer than two pages because that is the size of the transient area. (A page is 4096 bytes of virtual storage.) All transient routines must be serially reusable since they are not read in each time they are needed. See "User and Transient Program Areas" on page 23 for more details on the transient program area. • Low-Storage DMSFREE Nucleus Free Storage Area (X'lOOOO' to X'20000'). This area is a free storage area where nucleus requests to DMSFREE are allocated. The top part of this area contains the dummy hyperblocks for the S- and Y-disk. Each block is 48 bytes long. This area may be followed by the file status tables for the S2 filemode files of the system disk. If there is enough room, the FREETAB table also occupies this area, just below the file status tables, if they are there. Each entry in the Chapter 4. Using Storage 15 L FREETAB table is one byte long. Each byte represents one page (4K or 4096 bytes) of defined storage. • User Program Area (X'20000' to Loader Tables or CMS Nucleus, whichever has the lower value). User programs are loaded into this area by the LOAD command for text decks or by the LOADMOD command for modules. Storage allocated by means of the GETMAIN macro instruction is taken from this area, starting from the high address of the user program. In addition, this storage area can be allocated from the top down by DMSFREE, if there is not enough storage available in the low DMSFREE storage area. Thus, the usable size of the user program area is reduced by the amount of free storage that has been allocated from it by DMSFREE. See "User and Transient Program Areas" on page 23 for details on the user program area. o Loader Tables (Top pages of storage). The top of storage is occupied by the loader tables, which are required by the CMS loader. These tables indicate which modules are currently loaded in the user program area (and the transient program area after a LOAD command). The size of the loader tables can be varied by the SET LDRTBLS command. However, to successfully change the size of the loader tables, the SET LDRTBLS command should be issued immediately after IPL. If SET LDRTBLS is not issued immediately, high storage may be fragmented. G CMS Nucleus (NUCALPHA to NUCOMEGA). The CMS nucleus contains the reentrant code for the eMS nucleus routines and the system S-STAT and Y-STAT. If there is not sufficient room to contain the S-STAT in this area, it is placed in low DMSFREE nucleus storage. If there is not sufficient room to contain the Y-STAT in this area, the Y-disk is accessed using the ACCESS command. If the size of the user's virtual machine is defined below the end of the CMS nucleus (refer to label NUCSIGMA in Figure 1 on page 18), it is not possible to IPL by device name. You cannot IPL by device name because the CMS nucleus is too large to be loaded into the user's virtual storage. Therefore, the user can only IPL by system name (such as, IPL CMS). The loader table is placed immediately below the CMS nucleus. On the other hand, if the size of the user's virtual machine is defined above the ending location of the CMS nucleus (refer to Figure 2 on page 19 and Figure 3 on page 20), the user may IPL by either device name or system name. IPLing by device name: The S-STAT, Y-STAT, and the loader table are placed above the CMS nucleus. If there is not enough room to contain the' S-ST AT above the CMS nucleus (NUCSIGMA), it is placed in low storage. Likewise, if there is not sufficient room for the loader table above the CMS nucleus (NUCSIGMA), the loader table is placed below the nucleus. Any leftover free space above the nucleus is placed on the high DMSFREE chain. 16 VMjSP eMS for System Programming (c~tfJ8 8·~@G'8[JG ------------------------------------------ ---] r-------------------- IPLing by system name: The shared copy of the S-STAT, Y-STAT, and nucleus is used~ If there is sufficient room, the loader table is placed above the S-ST AT and Y-STAT (NUCOMEGA). If there is insufficient room to place the loader table above the S- and Y-STAT, the loader table is placed below the nucleus. Any leftover free space above the S- and Y-STAT (NUCOMEGA) is placed on the high DMSFREE chain. Chapter 4. Using Storage 17 Virtual Storage I I NUCOMEGA S-STAT and V-STAT (Shard) NUCSIGMA _... CMS Nucleus (Shared) -- OS Simulation, EXEC, EXEC 2, AEXX, XEDIT, CMS interrupt handlers, file system, free storage management, loader, device I/O, debug. Storage Key" X'O' NUCALPHA End of Storage ~-------------------------------------, System Loader Table VMSIZE (Size Determined by SET LDRTBLS command) Storage Key = X'F' ·1 DMSFAEE requests when no more low'storage is available Storllge Key = X'E' or X'F' FAEELOWE _ ...... [ - ~se:;,o:on:f ~er-;o;:m:re:- - -- -~ .\ " ~~. -~ - - - Storage Key = X'E' - - -- -- GETMAIN requests MAINHIGH - MAINSTAT ---------------- " ~'ser Storllge Key .. X'E' Storage Key DECB I The User's Progrllm (Program is locllted viII the LOAD command) X '20000' Control Blocks in Free Storage Proi}ra'm Area·" CMSSAVE II LDAST II CMSCB II II AFT II FSTB I ADT =X'E' Low Storage DMSFREE Nucleus Free Storage Area. The upper part of this area may contain the S-STAT followed by the FREETAB, If there Is enough room, I Storage Key = X'F' .• X'l0000' Transient Program Area Storage Key = X'E' X'EOOO' Low Storage DMSFREE User Free 5torllge Area I $torllge Key .. X'E' ANUCEND DMSNUC System Control Blocks, flags constants, and pointers Storage Key =X'F' • X'O' • The page starting at DMSNUCU containing OPSECT, SUBSECT, DBGSECT, DMSERL, TSOBLKS, USERSECT, and free storage has a Storage Key'" X'E'. Figure 1. 18 eMS Storage Map 1. CMS virtual storage usage when the eMS nucleus is larger than the user's virtual storage. In this case, you must IPL by system name (VMSIZE is less than NUCSIGMA). The arrows indicate that MAINHIGH is extended upward and FREELOWE is extended downward. VM/SP CMS for System Programming Virtual Storage \ S-STATa~d NUCOMEGA (VM SIZE) V-STAT (Shared - if IPL'i by system name) NUCSIGMA CMS Nucleus (Shared - if IPL'd by system name) .1- OS simulation, EXEC, EXEC 2, REXX, XEDIT, CMS interrupt handlers, file system, free storage management, loader, device I/O, debug. .... Storage Key - X'O' System Loader Table (Size Determined by SET LDRTBLS command) Storage Key .. X'F' NUCALPHA . r- DMSFREE requests when no more low storage is available FREELOWE -~ MAINHIGH ~ Storage Key .. X'E' or X'F' ---:1'- , ------------------::;-pO::;u:,:':,::.~ Storage Key" X'E' GETMAIN requests ' USe'r PrOgram Area \, r- Storage Key = X'E' MAINSTRT I Control Blocks in Free Storaae - DECB ICMSSAVE ~-------------------. The User's Program II LDRST II AFT II II CMSCB II FSTB I ADT I (Program is located via the LOAD command) Storage Key" X'E' X'20000' X'l0000' 'Low Storage DMSFREE Nucleus Free Storage Area. The upper part of this area may contain the S-STAT followed by the FREETAB.lf there Is enough room. Storage Key = X'F' 1,:/// Transient Program Area Storage Key .. X'E' X'EOOO' Low Storage DMSFREE User Free Storage Are'a ANUCEND Storage Key" X'E' DMSNUC System Control Blocks, flags, constants, and pointers X'O' Storage Key .. X'F' • • The page starting at DMSNUCU containing OPSECT. SUBSECT. DBGSECT. DMSERL. TSOBLKS. USERSECT. and free storage has a Storage Key • X'E'. Figure 2. eMS Storage Map 2. Virtual storage usage when the user's virtual storage is equal to the eMS nucleus. The user may IPL by system name or device. In addition, this figure shows the case where there is insufficient room to place the loader table above S-STAT and Y-STAT. The arrows indicate that MAINHIGH is extended upward and FREELOWE is extended downward. Chapter 4. Using Storage 19 ...... ". . .". , .. "._.... ___________________._____ ..........._._ .......__ ........... __ ....... _. __..____. ___-=-______. ________________1 L Virtual Storage VM SIZE System Loader Table (Size Determined by SET LDRTBLS command) ~ _____________ ~~~~~2: DMSFREE requests I Storage Key" X'E' or X'F' NUCOMEGA I S-STAT and Y -STAT (Shared - if IPL'd by system name) ... J NUCSIGMA .- CMS Nucleus (Shared - if IPL'd by system name) OS simulation, EXEC, EXEC 2, REXX, XEDIT, CMS interrupt handlers, file system, free storage management, loader, device I/O, debug. .1.0 Storage Key .. X'O' NUCALPHA DMSFREE requests when no more low storage is available __________ FREELOWE . MAINHIGH ~t~a2! ~y..:X":;'.!!r!'!' Unused portion of User Program Area -- --------------------Storage Key" X 'E' GETMAIN requests MAINSTRT User Progr;::m Area -------------------Storage Key = X'E' The User's Program (Program is located via the LOAD command) Storage Key X '20000' Control Blocks in Free Storage LDRST II AFT II ICMSSAVEII CMSCB II FSTB I DECB II ADT = X'E' Low Storaga DMSFREE Nucleus Free Storage Area. The upper part of this area may contain the S-STAT followed by the FREETAB,lf there Is enough room. Storage Key = X'F' X'l0000' Transient Program Area X'EOOO' Storage Key = X'E' Low Storage DMSFREE User Free Storage Area ANUCEND Storage Key = X 'E' DMSNUC System Control Blocks, flags, constants, and pointers Storage Key = X'F' • X'O' • The page starting at DMSNUCU containing OPSECT, SUBSECT, DBGSECT, DMSERL, TSOBLKS, USERSECT, and free storage has a Storage Key = X'E', Figure 3. 20 eMS Storage Map 3. eMS virtual storage usage when the user's virtual storage is larger than the eMS nucleus. The user may IPL by system name or device. In addition, this figure shows the case where there is sufficient room to place the loader table above S-STAT and Y-STAT. The arrows indicate that MAINHIGH is extended upward and FREELOWE is extended downward. VMjSP eMS for System Programming /' Structure of DMSNUC DMSNUC is the portion of storage in a CMS virtual machine that contains system control blocks, flags, constants, and pointers. The CSECTs in DMSNUC contain only symbolic references. This means that an update or modification to CMS, which changes a CSECT in DMSNUC, does not automatically force all CMS modules to be recompiled. Only those modules that refer to the area that was redefined must be recompiled. USERSECT (User Area) The USERSECT CSECT defines space that is not used by CMS. A modification or update to CMS can use the 18 fullwords defined for USERSECT. There is a pointer (AUSER) in the NUCON area to the user space. DEVTAB (Device Table) The DEVTAB CSECT is a table describing the devices available for the CMS system. The table contains the following entries· 0 0 0 0 0 0 0 1 console 26 disks 1 reader 1 punch 1 printer 16 tapes 1 dummy You can change some existing entries in DEVTAB. Each device table entry contains the following information: o o o o o Virtual device address Device flags Device types Symbol device name Address of the interrupt processing routine (for the console). The virtual address of the console is defined at logon time. The ACCESS command can dynamically alter the virtual address of the user disks in DEVTAB. The virtual address of a tape can be reassigned to any of the addresses given in DEVTAB (TAPO - TAPF) by using CMS commands and/or macros. Changing the virtual addresses of the reader, printer, or punch in DEVTAB has no effect. Figure 4 describes the devices supported by eMS. Chapter 4. Using Storage 21 C~v~8 8~fJ)l/ogG L ....-=:-:-........................ ____ ._._._.____ ._. _____ ... ___ .__ ._~.===_:===~.::_=-::-:-~~~.:::=~._--~~::~: ...~:~.-~:.- ..~.::-. _:_.:.~~--.--.~:_:~-~::J Virtual IEI'll: Device Type 3210, 3215, 1052, 3066, 3270 2314, 2319, 3310, 3330, 3340, 3350, 3370, 3375, 3380 2540, 2540, 1403, 3211, 4245, 2401, 2415, 3411, 3480, 2501, 3525 1443, 3262, 4248, 2402, 2420, 3420, 8809, Figure 4. 22 3505 3203, 3800, 3289-4 2403, 3410, 3430, 3422 Virtual Acldrcnn\": cuu! Symbolic Nnn1.c (defuult) CON1 Device Une System console 190 1912 cuu cuu 192 cuu cuu cuu 19E cuu cuu cuu cuu cuu cuu cuu cuu cuu cuu cuu cuu cuu cuu cuu cuu cuu OOC OOD OOE DSKO DSK1 DSK2 DSK3 DSK4 DSK5 DSK6 DSK7 DSK8 DSK9 DSKH DSKI DSKJ DSKK DSKL DSKM DSKN DSKO DSKP DSKQ DSKR DSKT DSKU DSKV DSKW DSKX RDR1 PCH1 PRN1 CMS System disk (read-only) Primary disk (user files) Minidisk (user files) Minidisk (user files) Minidisk (user files) Minidisk (user files) Minidisk (user files) Minidisk (user files) Minidisk (user files) Minidisk (user files) Minidisk (user files) Minidisk (user files) Minidisk (user files) Minidisk (user files) Minidisk (user files) Minidisk (user files) Minidisk (user files) Minidisk (user files) Minidisk (user files) Minidisk (user files) Minidisk (user files) Minidisk (user files) Minidisk (user files) Minidisk (user files) Minidisk (user files) Minidisk (user files) Virtual reader Virtual punch Line printer 180 - 187, 288 - 28F TAPO - TAP7, TAP8-TAPF Tape drives Devices Supported by a eMS Virtual Machine * The device addresses shown are preas sembled into the CMS resident device table. These need only be modified and a new device table made resident to change the addresses. 1 The virtual address of the system console may be any valid multiplexer address. 2 191 is the default user-accessed A-disk unless it is dynamically changed by an ACCESS at CMS initial program load (IPL). VM/SP eMS for System Programming L __ .__ ._._ User and Transient Program Areas Two areas hold programs that are loaded from disk. These areas are called the user program area and the transient program area, as discussed on page 15. (See Figures 1, 2, and 3 on pages 18, 19, and 20 for a description of CMS storage use.) A summary of CMS modules and their attributes, including whether they reside in the user program area or the transient area, is contained in the VM/ SP CMS Command Reference. The user program area starts at location X'20000' and extends upward to the loader tables. Generally, all user programs and certain system commands are executed in the user program area. Because only one program can be executing in the user program area at anyone time, it is impossible (without unpredictable results) for one program executing in the user program area to invoke, by means of SYC 202, a module that will also be executed in the user program area. The transient program area is two pages long, extending from location X'EOOO' to location X'FFFF'. It provides an area for system commands that may also be invoked from the user program area by means of an SYC 202 call. When a transient module is called by an SYC, it is normally executed with the PSW system mask disabled for I/O and external interrupts. A program executing in the transient program area may not invoke another program intended to execute in the transient program area. Thus, a program executing in the transient program area may not invoke the TYPE command. DMSITS starts the programs to be executed in the user program area enabled for all interrupts, but DMSITS starts the programs to be executed in the transient program area disabled for all interrupts. The individual programs may have to use the SSM (Set System Mask) instruction to change the current status of its system mask. Managing eMS Storage You can allocate free storage by issuing the GETMAIN or DMSFREE macros. Storage allocated by the GETMAIN macro is taken from the user program area, starting after the high address of the user program. Storage allocated by the DMSFREE macro can be taken from several areas. First, DMSFREE requests are allocated from the low address free storage area. Otherwise, DMSFREE requests are satisfied from the unused portion of the user program area. There are two types of DMSFREE requests for free storage: requests for USER storage and NUCLEUS storage, specified in the TYPE parameter of the DMSFREE macro. These two types of storage are kept in separate 4K pages. It is possible for storage of one type to be available in low storage, while no storage of the other type is available. Chapter 4. Using Storage 23 C-. ------------.-------'--:._':::--~-:-.:_:-~=.~-'------ . -,--------------.-,._-------,-----.---,--------.-------~~-.~~::::_::=_~-~. GETMAIN Free Storage Management All GETMAIN storage is allocated in the user program area, starting after the end of the user's actual program. Allocation begins at the location pointed to by the NUCON pointer MAINSTRT. The location MAINHIGH in NUCON points to the highest address of GETMAIN storage. The STRINIT function initializes pointers used by CMS for simulation of OS GETMAIN/FREEMAIN storage management. In the usual CMS environment, that is, when execution is initiated by the LOAD and START commands, CMS calls the STRINIT macro as part of the LOAD preparation for execution. In an OS environment established by CMS, such as OSRUN, CMS' executes the STRINIT function. This should not be done by the user program. In any case, the STRINIT macro should be issued only once in the OS environment, preceding the initial GETMAIN request. In addition, the STRINIT function makes any pages that were allocated by GETMAIN available to be released by the CMS page manager. The STRINIT Macro The format of the STRINIT macro is: [label] STRINIT [TYPCALL = {~XrR} 1 where: label is any valid assembler language label. TYPCALL ={SVC } BALR indicates how control is passed to DMSSTG, the routine that processes the STRINIT macro. Since DMSSTG is a nucleus-resident routine, other nucleus-resident routines can branch directly to it (TYPCALL = BALR). Routines that are not nucleus-resident must use SVC linkage (TYPCALL = SVC) . .If no operands are specified, the default is TYPCALL = SVC. When the STRINIT macro is executed, both MAINSTRT and MAINHIGH are initialized to the end of the user's program in the user program area. The end of the user's program is the upper boundary of the load module created by the CMS LOAD and INCLUDE commands. This upper boundary value is stored in the NUCON field LOCCNT. When the user's program begins execution, the STRINIT macro is executed and the LOCCNT value is used to initialize MAINSTRT and MAINHIGH. During execution of the user's program, the LOCCNT field is used in CMS to pass starting and ending addresses of files loaded by OS simulation (see Notes below). As storage is allocated from the user program area to satisfy GETMAIN 24 VM/SP eMS for Sys'tem Programming 'J' "\ ,1':,[ \ J~.)~ ~''')':~'II)LJ~ 'J' " .• 'J LJ.J I,.. ' .. _ " _ l._ ~_ L....:...--.:_. . _ . . __ . _._...___. ____ ._____.____ . __ __ ____ ._.__ ___ .. . . _. __.__, ' :~ ~~ ~ ~ ~ _.~_ '-..J , _ _.. _ __ _ _' ,: ____ . .____ :~_J requests, the MAINHIGH pointer is adjusted upward. Such adjustments are always in multiples of doublewords, so that this pointer is always on a double word boundary. As the allocated storage is returned, the MAINHIGH pointer is adjusted downward. The pointer MAINHIGH can never be higher than FREELOWE. FREELOWE is the pointer to the lowest address of DMSFREE storage allocated in the user program area. If a GETMAIN request cannot be satisfied without extending MAINHIGH above FREELOWE, GETMAIN takes an error exit, indicating that insufficient storage is available to satisfy the request. The area between MAINSTRT and MAINHIGH may contain blocks of storage that are not allocated but are available for allocation by a GETMAIN instruction. These blocks are chained together, and the first block is pointed to by the NUCON location MAINLIST. Refer to Figures 1, 2, and 3 on pages 18, 19, and 20 for a description of CMS virtual storage usage. Notes: 1. Reissuing the STRINIT macro during execution of an OS program, or issuing the STRINIT macro without having done a CMS LOAD is not advised. The value in LOCCNT has not been appropriately set. This may cause a storage management failure. 2. A high level language may issue a STRINIT. In this case, a user should not issue an additional STRINIT. The format of an element on the GETMAIN free element chain is as follows: 0(0) 4(4) FREPTR -- pointer to next free element in the chain, or a if there is no next element FRELEN -- length, in bytes, of this element Remainder of this free element The maximum amount of storage that can be obtained via the GETMAIN macro is determined by one of the following formulas: VMSIZE < 512K: (largest block of the user program area available) - 10 pages VMSIZE > = 512K: Chapter 4. Using Storage 25 r,-';,.rVJD \:.::;7Lv ~) nr'r:-")r"1n(-~('\ I:.~)~c.lu Cj~J'-; (largest block of the user program area available) - (12 pages + 2 additional pages for each 256K of virtual storage over 512K) Releasing Storage Storage allocated by the GETMAIN macro instruction may be released in any of the following ways: 1. A specific block of such storage may be released by means of the FREE MAIN macro instruction. 2. Whenever any user routine or eMS command abends (so that the routine DMSABN is entered) and the abend recovery facility of the system is invoked, all GETMAIN storage pointers are reset. 3. Issuing a STRINIT macro releases all allocated GETMAIN storage. 26 VM/SP eMS for System Programming (~L~;]8 8'~«)[j'CJ~J(J ~--- . --.. -- . --.-.--- . -.----. -. --------.--~. ------ -----~. . . --.--~ . -.. :---.-----~.- . ,.--:.....-~. - .. -'"~=--==~-=::~~~~:..:.:..:..=-:...:..:=-:..:...:.:--~~~--. . -"'-~ I DMSFRE Free Storage Management The DMSFREE Macro The DMSFREE macro allocates CMS free storage. The format of the DMSFREE macro is: DMSFREE [ label] DWORDS= { n } (0) [,TYPE = {USER [ ,MIN = { (~) } ] }] NUCLEUS [,ERR= {la~dr}] [,AREA = {~?ci1}] [,TYPCALL= {~x~R}l where: label is any valid assembler language label. DWORDS={ n} (0) is the number of double words of free storage requested. DWORDS = n specifies the number of doublewords directly and DWORDS = (0) indicates that register 0 contains the number of doublewords requested. Do not specify any register other than register O. The register number for register 0 cannot be expressed as an equated symbol. CMS returns, in register 0, the number of doublewords allocated and, in register 1, the address of the first byte of allocated storage. MIN= {(~)} indicates a variable request for free storage. If the exact number of double words indicated by DWORDS operand is not available, then the largest block of storage greater than or equal to the minimum is requested. MIN = n specifies the minimum number of doublewordsof free storage directly. MIN = (1) indicates that the minimum is in register 1. Do not specify any register other than register 1. The Chapter 4. Using Storage 27 C~JJ~) 8~C)r8[jG r--:- . actual amount of free storage allocated is returned to the requestor by general register O. TYPE = {" USER "} " NUCLEUS indicates the type of CMS storage requested: USER or NUCLEUS ERR = {~addr} is the return address if any error occurs. laddr is any address that can be referred to in an LA (load address) instruction. The error return is taken if there is a macro coding error or if there is not enough free storage available to fill the request. If the asterisk (*) is specified for the return address, the error return is the same as a normal return. There is no default for this operand. If it is omitted and an error occurs, the system abends. AREA= "{LOW} HIGH indicates the area of CMS free storage requested. LOW indicates any free storage below the user areas, depending on the storage requested. HIGH indicates DMSFREE storage above the user area. If AREA is not specified, storage is allocated wherever it is available. TYPCALL ={ SVC } BALR indicates how control is passed to DMSFREE. Since DMSFREE is a nucleus-resident routine, other nucleus-resident routines can branch directly to it (TYPCALL = BALR). Routines that are not nucleus-resident must use SVC linkage (TYPCALL = SVC). The FREELOWE pointer in NUCON indicates the amount of storage that DMSFREE has allocated from the high portion of the user program area. These pointers are initialized to the beginning of the loader tables. The pointer FREELOWE is the pointer to the lowest address of DMSFREE storage in the user program area. As storage is allocated from the user program area to satisfy DMSFREErequests, the pointer FREELOWE is adjusted downward. As the allocated storage is returned, this pointer is adjusted upward. Such adjustments are always in multiples of 4K bytes so the pointer is always on a 4K boundary. The pointer FREEL OWE can never be lower than MAINHIGH. MAIN HIGH is the pointer to the highest address of GETMAIN storage. If a DMSFREE request cannot be satisfied without extending FREELOWE below MAINHIGH, DMSFREE takes an error exit, indicating that insufficient storage is available to satisfy the request. Figures 1, 2, and 3 on pages 18, 19, and 20 show the relationship of these storage areas. The FREETAB free storage table is usually kept in nucleus low FREE storage. However, the FREETAB may be located at the top of the user 28 VM/SP eMS for System Programming «~~lfJS ~~'~O[/8~G - -] program area. This table contains a code indicating the use of that page of virtual storage. The codes in this table are as follows: USERCODE (X'Ol') The page is assigned to user storage. NUCCODE (X'02') The page is assigned to nucleus storage. TRNCODE (X'03') The page is part of the transient program area. USARCODE (X'04') The page is an unassigned page in the user program area. SYSCODE (X'05') The page is none of the above. The page is assigned to system storage, system code, or the loader tables. Other DMSFREE storage pointers are maintained in the DMSFRT CSECT, in NUCON. The four chain header blocks are the most important fields in DMSFRT. The four chains of unallocated elements are: o o o o The The The The low storage nucleus chain low storage user chain high storage nucleus chain high storage user chain For each of these chains of unallocated elements, there is a control block consisting of four words with the following format: 0(0) POINTER -- pointer to the first FBD (free block descriptor) in a cache of FBDs used to describe the first "nll free blocks of storage for the particular chain. 4(4) NUM -- the number of elements on the chain. 8(8) MAX -- a value equal to or rreater than the size of the argest element on the chain. 12(C) FLAGS- SKEYFlag Storage byte key TCODEFREETAB code Unused where: POINTER points to the first FBD (file block descriptor) in a cache of FBDs used to describe the first "n" free blocks of storage for the particular chain. "n" is 10 for the high user chain, 9 for the high nucleus chain, 6 for the low user chain, and 6 for the low nucleus chain. Chapter 4. Using Storage 29 NUM contains the number of elements on this chain of free elements. If there are no elements on this free chain, this field contains all zeroes. MAX is used to avoid searches that will fail. It contains a number not exceeding the size, in bytes, of the largest element on the free chain. Thus, a search for an element of a given size is not made if that size exceeds the MAX field. However, this number may actually be larger than the size of the largest free element on the chain. FLAGS The following flags are used: FLCLN (X'80') -- Clean-up flag. This flag is set if the chain must be updated. This is necessary in the following circumstances: o If one of the two high-storage chains contains a 4K page that is pointed to by FREELOWE, that page can be removed from the chain and FREELOWE can be increased. o All completely unallocated 4K pages are kept on the user chain, by convention. Thus, if one of the nucleus chains (low-storage or high-storage) contains a full page, this page must be transferred to the corresponding user chain. FLCLB (X'40') -- Destroyed flag. Set if the chain has been destroyed. FLHC (X'20') -- High-storage chain. Set for both the nucleus and user high-storage chains. FLUN (X'lO') -- Nucleus chain. Set for both the low-storage and high-storage chains. FLPA (X'08') -- Page available. Set if there is a full 4K page available on the chain. This flag may be set even if there is no such page available. SKEY contains the one-byte storage key assigned to storage on this chain. TCODE contains the one-byte FREETAB table code for storage on this chain. There are four caches of FBDs, one for each of the chains. The FBDs are chained together at initialization time from the head pointers found in the DMSFRT CSECT described above. Each of the FBDs in the cache has the following format: 30 VM/SP eMS for System Programming _ .J ~------- 4 bytes 0(0) POINTER -- pointer to the next FBD in the chain unless it is the last FBD in the cache in which case it points to the next block of free storage in the chain or is zero. 4(4) SIZE -- size of the free block in bytes 8(8) FBDFREE -- pointer to the free block that this FBD is describing. The FBDs in the cache always remain chained together, and when they do not describe a free block, the fields SIZE and FBDFREE are zero. When the cache is full, the forward pointer POINTER in the last FBD in the cache points to the next free block that contains the following fields:8 An unexpected and unexplained error has occurred in the free storage management routine. Storage Protection Keys In general, the following rule for storage protection keys applies: system storage is assigned the storage key of X ' FO ' , while user storage is assigned the storage key of X ' EO '. This is the storage key associated with the protected areas of storage, not to be confused with the PSW or CAW key used to acc~ss that storage. The specific key assignments are as follows: o The NUCON area is assigned the key of X'FO', with the exception of the last page containing the OPSECT and TSOBLOKS areas and user free storage, which have a key of X'EO'. o Free storage allocated by DMSFREE is broken up into user storage and nucleus storage. The user storage has a protection key of X'EO', while the nucleus storage has a key of X'FO'. o The transient program area has a key of X'EO'. o The CMS nucleus code has a storage key of X'OO'. In saved systems, this entire segment is protected by CP from modification even by the CMS system, and so must be entirely reentrant. o The user program area is assigned the storage key of X'EO', except for those pages which contain nucleus DMSFREE storage. These latter pages are assigned the key of X'FO'. o The loader tables are assigned the key of X'FO'. The SET KEYPROTECT Command The SET KEYPROTECT command controls the resetting of user keys, X'EO', when a DMSFRET occurs. The format of the SET KEYPROTECT command is: SET 38 VM/SP eMS for System Programming KEYPROTect {ON } OFF ((~M8 8'l(Ou~E1[JG ___ r-.----=~:__=:._=~-~=_.:=_--~ _ ~:_~~_~_:.~=__~~~~=:~~~ _=__~==~~-~~~-=_-=-~==_~-.::===~_==:::__==~_._____________ ---.------------=--=-.J When you issue SET KEYPROTECT ON, the storage keys for the whole virtual machine, except the non shared pages, are reset according to FREETAB. Then whenever a DMSFRET occurs, the user keys are reset. SET KEYPROTECT OFF does not cause the user keys to be reset when a DMSFRET occurs. (SET KEYPROTECT OFF is the default setting.) If an ABEND occurs, the storage keys of the virtual machine are reset according to FREETAB and the setting for KEYPROTECT is maintained. To check the setting of KEYPROTECT, issue: QUERY KEYPROTECT Note: If user programs set keys, they must restore the keys to their original settings. If there are programs that depend on CMS resetting user keys, SET KEYPROTECT ON to insure that the user keys are set properly. eMS Handling of PSW Keys The CMS nucleus protection scheme protects the CMS nucleus from inadvertent destruction by a user program. This mechanism, however, does not prevent you from writing in system storage intentionally. Because you can execute privileged instructions, you can issue a LOAD PSW (LPSW) instruction and load any PSW key you wish. If this occurs, there is nothing to prevent your program from: o o o Modifying nucleus code Modifying a table or constant area Losing files by modifying a CMS file directory In general, user programs and disk-resident CMS commands are executed with a PSW key of X'E', while nucleus code is executed with a PSW key of X'O'. There are, however, some exceptions to this rule. Certain disk-resident CMS commands run with a PSW key of X'O', because they have a constant need to modify nucleus pointers and storage. The nucleus routines called by the GET, PUT, READ, and WRITE macros run with a user PSW key of X'E' to increase efficiency. Two macros, DMSKEY and DMSEXS, are available to any routine that wishes to change its PSW key. The DMSKEV Macro The DMSKEY macro may be used to change the PSW key to the user value or the nucleus value. The format of the DMSKEY macro is: Chapter 4. Using Storage 39 [ label] DMSKEY {NUCLEUS [,NOSTACKJ I USER [,NOSTACK ] I LASTUSER [,NOSTACK] RESET} I where: label is any valid assembler language label. NUCLEUS causes the nucleus storage protection key to be placed In the PSW, and the old contents of the second byte of the PSW are saved in a stack. This option allows the program to store into system storage, which is ordinarily protected. USER causes the user storage protection key to be placed in the PSW, and the old contents of the second byte of the PSW are saved in a stack. This option prevents the program from inadvertently modifying nucleus storage, which is protected. LASTUSER The SVC handler traces back through its system save areas for the active user routine closest to the top of the stack. The storage key in effect for that routine is placed in the PSW. The old contents of the second byte of the PSW are saved in a stack. This option should be used only by system routines that should enter a user exit routine. (OS macro simulation routines use this option when they want to enter a user-supplied exit routine. The exit routine is entered with the PSW key of the last user routine on the SVC system save area stack.) NOSTACK This option may be used with any of the above options to prevent the system from saving the second byte of the current PSW in a stack. If this is done, then no DMSKEY RESET need be issued later. RESET The second byte of the PSW is changed to the value at the top of the DMSKEY stack and removed from the stack. Thus, the effect of the last DMSKEY NUCLEUS, DMSKEY USER, or DMSKEY LASTUSER request is reversed. However, if the NOSTACK option was specified on the DMSKEY macro, the RESET option should not be used. A DMSKEY RESET macro must be executed for each DMSKEY NUCLEUS, DMSKEY USER, or DMSKEY LASTUSER macro that was executed and that did not specify the NOSTACK option. Failure to observe this rule results in program abnormal termination. CMS requires that the DMSKEY stack be empty when a routine terminates. 40 VM/SP eMS for System Programming L -________ ___ ._______________ .______ ._._ . . __ __ .__ ___ . . .:.___ ____ __ _~.~ ~. ~~. ~~ ~_~ ~~ I,G~~'J~j G'~\Qu'Cl~J\J __ __ _____.__.___ .~~:~:.:._- ~~_~ ~:_.:.._-~ ~:_J Note: The DMSKEY key stack has a current maximum depth of seven for each routine. In this context, a "routine" is anything invoked by an SVC call. The DMSE}(S Macro The DMSEXS, "execute in system mode," macro allows a routine executed with a user PSW key to execute a single instruction with a nucleus PSW key. The single instruction may be specified as the argument to the DMSEXS macro, and that instruction is executed with a nucleus PSW key. This macro can be used instead of two DMSKEY macros. The format of the DMSEXS macro is: [label] DMSEXS op-code ,operands The op-code and the operands of the Basic Assembler Language instruction to be executed must be given as arguments to the DMSEXS macro. For example, execution of the sequence, USING NUCON,O DMSEXS OI,OSSFLAGS,COMPSWT causes the 01 instruction to be executed with a zero protect key in the PSW. This sequence turns on the COMPSWT flag in the nucleus. It is reset with DMSEXS NI,OSSFLAGS,255-COMPSWT The instruction to be executed may be an EX instruction. Note: Programs that modify or manipulate bits in CMS control blocks, however, may hinder the operation of eMS causing it to function ineffectively. Register 1 cannot be used in any way in the instruction being executed. Whenever possible, CMS commands are executp.d with a user protect key. This protects the CMS nucleus in cases where there is an error in the system command that would otherwise destroy the nucleus. If the command must execute a single instruction or small group of instructions that modify nucleus storage, then the DMSKEY or DMSEXS macros are used so that the system PSW key is used for as short a period of time as possible. Chapter 4. Using Storage 41 (G~JJ8 §~Q)L~@OG L___ ._~ ___________________ .__________________.__-__. ________________.__________ . _____ 42 VM/SP eMS for System Programming -==-_-:--::--==-=--==-===--:J Program lin~(age (SVC Handling) Program linkages, in CMS, are made by a supervisor call instruction, SVC 202. DMSITS (INTSVC) is the CMS system SVC handling routine. The general operation of DMSITS is as follows: 1. The SVC new PSW (low-storage location X'60') contains, in the address field, the address of DMSITS1. The DMSITS module is entered whenever a supervisor call is executed. 2. DMSITS allocates a system save area and user save area. The user save area is a register save area (or work area) used by the routine, which is invoked later as a result of the SVC call. 3. The called routine is called (via a LPSW or BALR). 4. Upon return from the invoked routine, the save areas are released. 5. Control is returned to the caller (the routine that originally made the SVC call). Register Usage When calling a CMS routine, Rl must point to a valid parameter list (PLIST) for that program. On return, RO mayor may not contain meaningful information. For example, on return from a call to FILEDEF with no change, RO contains a negative address if a new FCB (file control block) was set up. Otherwise, RO contains a positive address of the already existing FCB. R15 contains the return code, if any. The use of registers 0 and 2 through 11 varies. When a command or routine is called by SVC 202, the registers contain the following information: Chapter 5. Developing Programs under CMS 43 Register Contents o Points to an extended PLIST if the command is: e o • o called from the terminal, called from a REXX program, called from an EXEC 2 EXEC, or an Enhanced Connectivity Facilities on VM/SP call (see SENDREQ in the VM/ SP IBM Programmer's Guide to the Server-Requester Programming Interface for VM/SP, SC24-5291). The EPLIST contains addresses referring to the extended command as it was initially entered by the user. 1 Points to a parameter list of successive doublewords. The first entry in the list is the name of the called routine or program. Any successive doublewords may contain arguments passed to the program. 13 Contains the address of a 24-fullword save area, which you can use to save your caller's registers. This save area satisfies standard OS and DOS linkage conventions. You do not need to use it in CMS, since the SVC routines save the registers. 14 Contains the return address of the SVC handling routines. You must return control to this address when you exit from your program. 12 and 15 Contain your program's entry point address. You can use this address to establish immediate addressability in your program. Most CMS routines use R12 as a base register. You should not use R15 as a base address, since all CMS SVCs use it to communicate with your programs. On return from a routine, register 15 contains: Return Code Meaning No error occurred <0 Called routine not found >0 Error occurred o If a CMS routine is called by an SVC 202, CMS saves and restores registers o through 14. Figure 5 shows how registers are set up when the called routine is entered. 44 VM/SP eMS for System Programming ___ '-:.J Ren-istel'G TIer:;istQr 2 Same as See note caller 1 Rcr.;iGtel'G nc~iGter Register RegiGtcl' Rcaister 3 - 11 12 13 1,1 15 Not defined Address of called routine Address of user save area Return address to DMSITS Address of called routine sve 203 Same as caller Not defined Not defined Address of called routine See note 2 Address of called routine Other Same as caller Same as caller Same as caller Address of called routine Address of user save area Return address to DMSITS Return address to DMSITS Type sve 202 Figure 5. 0-1 Same as caller Register Contents When Called Routine Starts Notes: 1. If a nucleus extension or subcommand processor, register 2 has address of SCBLOCK. 2. Depends on the function being invoked. Figure 6 show how the PSW fields are set up when the called routine is entered. Cnlletl Type sve 202 or 203 -Nucleus Resident sve 202-Nucleus Extension Module sve 202 or 203 -Transient Area Module sve 202 or 203 -User Area Module U ser-handled OS-VSE -Nucleus resident OS-VSE -Transient area module SYStClll lVIasli:: Storage ICey Disabled System Pl'oblClll Bit Off See note 1 See note 1 Off Disabled See note 2 Off Enabled See note 2 Off Enabled Disabled User System Off Disabled System Off Off Figure 6.PSW Fields When Called Routine Starts Chapter 5. Developing Programs under CMS 45 [D)G\JG~(Q)[])UuuQJ rrQ[D~~8uuuG ~%U(~G~' CWJS r_._____._______. __. .___.__. __.__.____.____.____________:____._______. .__ . __. _______. _. . . . . . . Notes: 1. User defined by using the NUCEXT function. 2. User defined by using the CMS GENMOD command or the CMS SET PROTECT command. Parameter Lists Tokenized PLiST For a tokenized parameter list, the symbolic name of the function being called (B-character string, padded with blank characters on the right if needed) is followed by extra arguments depending on the actual routine or command being called. These arguments must be "tokenized." Every parenthesis is considered an individual argument, and each argument may have a maximum length of eight characters. However, no error condition results. R1 contains the address of this parameter list. eMS commands look for a token of eight X'FF's to find the end of the PLIST. See page 51 for an example of a tokenized PLIST. Extended PLiST For an extended parameter list (EPLIST), no restriction is put on the structure of the argument list passed to the called routine or command. The first non-blank character, left parenthesis, or right parenthesis following the command is treated as a delimiter. This delimiter determines where the pointer to the start of the argument is. An extended PLIST has two forms, as illustrated below. The First Form of the Extended PLIST: In the first form, RO points to the following parameter list: (a) (b) (c) (d) DC DC DC DC A(COMVERB) A(BEGARGS) A(ENDARGS) A( 0) where the first three addresses are defined by: COMVERB EQU * DC C'cmdname' BEGARGS EQU * DC C' ENDARGS EQU * name of command argument list and where: (a) 46 is the beginning address of the command. VM/SP eMS for System Programming ... ·1 (b) (c) is the beginning address of the argument list. is the address of the byte immediately following the end of the argument list. may be used to pass any additional information required by individual called programs. If this word is not used to pass additional information, it should be zero so that programs receiving optional information via this word may detect that none is provided in this call. (d) See page 51 for an example of an extended PLIST. Notes: 1. These four words can be moved to some location convenient for the command resolution routines or convenient for some other program executed between the caller's sve 202 and entry to the program that the parameter list is intended. For this reason, the called program may not assume additional words following word 4, or the called program may not assume that the storage address of these 4 words bears any relationship to other data addresses. 2. For function calls in the System Product Interpreter, two additional words are available. See the VM/ SP System Product Interpreter Reference for more information on function calls and the two additional words. The Second Form of the Extended PLIST: The second form of an extended PLIST is used by Enhanced Connectivity Facilities on VM/SP (see SENDREQ in the VM/SP IBM Programmer's Guide to the Server-Requester Programming Interface for VM/SP, SC24-5291). The second form provides a way for a routine to: o Pass up to 64K-1 bytes of arbitrary data and 32K-5 bytes of parameters to another routine o Receive up to 64K-1 bytes of arbitrary data and 32K-5 parameters from another routine. In the second form, RO points to the following parameter list: (a) (b) (c) (d) DC DC DC DC A(commandname) F (reserved) F (reserved) A(CPRB) where: (a) is (b) is (c) is (d) is the address of the name of the program being called unused unused the address of the connectivity program request block (CPRB). If your routine is being called by another routine, you can verify that your routine is being called using the second form of an extended PLIST. Check Chapter 5. Developing Programs under CMS 47 r::-:-_-==~· ____ ...................... the contents of A(CPRB) CPRB. + 4. This address should contain the characters If you want to call another routine using the second form of an extended PLIST, see SENDREQ in the VM/SP IBM Programmer's Guide to the Server-Requester Programming Interface for VM/ SP, SC24-5291. Common SVC Calls SVC conventions are important to any discussion of CMS because the system is driven by SVCs (supervisor calls). SVCs 202 and 203 are the most common CMS SVCs. SVC 202 SVC 202 is the most commonly used SVC in the CMS system. It is used for calling nucleus-resident routines, nucleus extensions, and routines written as commands (for example, disk resident modules). A typical coding sequence for an SVC 202 call is the following: LA SVC DC Rl,PLIST 202 AL4(ERRADD) First, load the address of the parameter list into Rl and then issue an SVC. The "DC AL4(address)" instruction following the SVC 202 is optional and may be omitted if you do not expect any errors to occur in the routine or command being called. If the DC statement is included and the return code (RI5) contains a nonzero value after returning from the SVC call, control passes to the address specified in the DC unless the address is equal to 1. In the above example, control would go to the instruction at the label ERRADD. If the address is 1, return is made to the instruction following the "DC AL4(1)" instruction. DMSITS determines whether this DC was inserted by examining the byte following the SVC call. If the byte is nonzero, the statement following the SVC 202 is an instruction. If the byte is zero, the statement following the SVC 202 is either "DC AL4(address)" or "DC AL4(1)". If you want to ignore errors, you can use the sequence: LA SVC DC Rl,PLIST 202 AL4(l) Whenever an SVC 202 is issued, the contents of general purpose registers 0 and 1 (RO and Rl) are passed to the called routine. Rl points to an 8-character string, which may be the start of a tokenized PLIST. This character string contains the symbolic name of the routine or command being called. The called routine decides whether to use the tokenized 48 VM/SP eMS for System Programming / , :J-').('" II"(-.)~J\:.ln~;), r'-j' Ul ~rj\'-J r<)r,"!'':'-Jf'h'''}r ',cJ ,_1' \ .-,U '_ J u u ,.1 l.J ~_, u l l .J u \".__ '-. .. [:=_::.~~-=:~-:-:~.-.,,:-_ _~:::-:-~: :::~~::-=~~-~~_'~~~:~~~.:~:=-=~:':'_:'='~'':'''~: __ --':_ :~_ ,._~:,_"._ n nr',')" 1. ',,\f 1 ;I~:\.'J(.~) ',_J.Jl \ _J',.-'U ' • ...JLJ'J " __ .... _. __.__':'.~_"':_,_:.:__.. __.. __ ..___ .._:~_.. _. __._. ___ ,:. . . .::,_ .. __..___. ,... ____ .. __ ., .,_" __.___ ,. ,_ .. ____ J PLIST or the extended PLIST (one of two forms) by examining the high-order byte of Rl. The SVC handler only examines the name and the high-order byte of Rl. Note: Although an extended PLIST is provided, the called routine might not be set up to use it. When a program gets control, it checks the value of the the high-order byte of RI to determine what environment (EXEC, command line, etc.) it was called from and if an extended PLIST is available. Then the program may take appropriate action. CMS only places these values in the high-order byte for the convenience of the program. The following values may be found in the high-order byte of register 1: E::tl3!!d~~l PLIST Pointer in llcfjiGter O? Value IVlcnninG X'OO' The call did not originate from an EXEC file or a command typed at the terminal. (The SVC handler translates the value X'04' to X'OO' before entering the called program.) Either the call is from an EXEC 2 EXEC or the System Product Interpreter when "ADDRESS COMMAND" is specified, or the call is an Enhanced Connectivity Facilities on VMjSP call (see SENDREQ in the VMj SP IBM Programmer's Guide to the Server-Requester Programming Interface for VMj SP, SC24-5291). You can tell by checking the form of the extended PLIST, see "Extended PLIST" on page 46. (The SVC handler translates the value X'03' to X'OI' before entering the called program.) See "Dynamic LinkagejSUBCOM" on page 59. Used by the System Product Interpreter for external function calls. The command was invoked as an immediate command. This setting should never occur with SVC 202. The command was called as a result of its name being typed at the terminal, by the CMDCALL command to invoke the command from EXEC 2, or from a System Product Interpreter EXEC when "ADDRESS CMS" is specified. X'OI' X'02' X'05' X'06' X'OB' Figure 7 (Part 1 of 2). No Yes Yes Yes Yes Yes SVC 202 High-Order Byte Values of Register 1 Chapter 5. Developing Programs under CMS 49 E:::rtended PLIST Pointer in Register O? Value MeaninrJ X'OC' The call is the result of a command invoked from a CMS EXEC file with "&CONTROL" set to something other than "NOMSG" or "MSG". The call is the result of a command invoked from a CMS EXEC file with "&CONTROL MSG" in effect (indicates that messages are to be displayed at the terminal). The call is the result of a command invoked from an CMS EXEC file with "&CONTROL NOMSG" in effect. This is an end-of-command call from DMSINT (CMS console command handler). See the NUCEXT function in the VM/ SP CMS Macros and Functions Reference for details. This is a service call from DMSABN (abend) or from NUCXDROP. See the NUCEXT function in the VM/ SP CMS Macros and Functions Reference for details. X'OD' X'OE' X'FE' X'FF' Figure 7 (Part 2 of 2). No No No No No SVC 202 High-Order Byte Values of Register 1 Some CMS commands work differently when called from different environments. An assembler language program can simulate the various environments (listed in Figure 7 under "Meaning") by using the appropriate high-order byte. For example, to call the ERASE command from an assembler program and to suppress error messages, the program uses a high-order byte of X'OE'. This simulates a call from a CMS EXEC with "&CONTROL NOMSG" in effect. Some CMS commands can take advantage of an extended PLIST if it is supplied. For example, the FILEDEF command uses the extended parameter list when processing the DSN qual1[.qual2 ... ] parameter. The following program shows how to set up an extended parameter list and call FILEDEF. The high-order byte, X'OI', in the program example simulates a call from an EXEC2 EXEC or the System Product Interpreter when "ADDRESS COMMAND" is specified. 50 VMjSP eMS for System Programming ~jGi'J(3~O[')OuuU [Ju'(0UuJ~luullG o..~u··ucJ~)uJ (G~tfJ~) _ c====-==-=-=..:-=--:::=...:_-_=.~~~=~~~..:.:==~-_~=~=-·:..:_~=::::·~=~:~~~·~ ..:_-_--._::=:~=_==-_~:=.=:=-:= .===~":'::==-=~=":~~~~~. ~~:~=~_":':~~==":':":=--:J SAMPLE CSECT * * * ISSUE 'FILEDEF SYSIN DISK A A A DSN G.TEMP.DATA.LIBRARY' PLIST * * * EPLIST COMVERB BEGARGS ENDARGS * * REGEQU USING *,R12 LR R12,R15 LA RO,EPLIST LA RI,PLIST ICM RI,B'IOOO' ,=X'OI' SVC 202 AL4(l) DC BR R14 DS OF DC CLS'FILEDEF ' CLS'SYSIN' DC DC CLS'DISK' DC CLS'A' DC CLS'A' CLS'A' DC CLS'DSN' DC CLS'G.TEMP.D' NOTICE THAT THIS IS TRUNCATED DC BUT FILEDEF WILL USE THE EXTENDED PARAMETER LIST BELOW. 2F'-1' DC A (COMVERB) DC A(BEGARGS) DC DC A(ENDARGS) A(O) DC DC C'FILEDEF ' EQU * DC C'DISK A A A DSN G.TEMP.DATASET.LIBRARY' ENDARG POINTS ONE CHARACTER * EQU PAST THE END OF THE PARAMETER LIST. END Refer to page 43 for a description of the contents of R12, R13, R14, and R15. BVC 202 Return Codes: On return from SVC processing, register 15 contains one of the following return codes: o No errors occurred. -1 A CP command with this name was not found. -2 An attempt was made to execute a CMS command while in CMS subset mode. This would have caused the module to be loaded in the user area. -3 A CMS command issued from EXEC was not found with this name, or an invalid function occurred when the SET or QUERY command was issued from EXEC with IMPCP active. -4 The LOADMOD failed. Chapter 5. Developing Programs under CMS 51 r~.J)c:'?\7c~~CDLJ)Duu£D [;)rOQW'f:luuuD ~.%ll(~Q~~ (~l~~QS:) . --.-------..-.------.--.--.. - . -.-.-~::-:-::=.===~::-=~- -5 -.---------.---.:---:.::-:-~'-:---.-.-- . -.--.--..-------." ·'·1 A LOADMOD was issued in the wrong environment (for example, the module was generated by the GENMOD command with the as option, and LOADMOD was attempted with DOS = ON specifi~d). SVC 203 sve 203 is called by eMS macros to perform various internal system functions. It is used to define sve calls when no parameter list is provided. For example, DMSFREE parameters are passed in registers 0 and 1. A typical calling sequence for an sve 203 call is: SVC DC 203 H'code' The halfword decimal code following the sve 203 indicates the specific routine being called. DMSITS examines this halfword code taking the absolute value of the code using a LPR instruction. The first byte of the result is ignored, and the second byte of the resulting halfword is used as an index into a branch table. The address of the correct routine is loaded, and control is transferred to it. It is possible for the address in the sve 203 index table to be zero. In this case, the index entry contains an 8-byte routine or command name, which is handled in the same way as the 8-byte name passed in the parameter list to an sve 202. The sign of the halfword code indicates whether the programmer expects an error return. If an error return is expected, the code is negative. If the code is positive, no error return is made. The sign of the halfword code has no effect on determining the routine called since DMSITS takes the absolute value of the code to determine the routine called. Since only the second byte of the absolute value of the code is examined by DMSITS, seven bits (bits 1-7) are available as flags or for other uses. For example, DMSFREE uses these seven bits to indicate such things as conditional requests and variable requests. Therefore, DMSITS considers the codes X'3' and X'259' to be identical and handles them the same as X'-3' and X'-259', except for error returns. When an sve 203 is invoked, DMSITS stores the halfword code into the NUeON location eODE203 so the called routine can examine the seven bits made available to it. All calls made by sve 203 should be made by macros with the macro expansion computing and specifying the correct halfword code. 52 VM/SP eMS for System Programming [DG'\JG~I1)~)Uu·~u [~=--.:.:==~.:.~_. [Ju'CGUu'c}u·u·uS _.. __._.-_.._____.______-_. . _..._.--_. _. . -_.-._.-_-_-.-_--.--.---.... __ ~ ::.-.:~. ~~~. __..:_._. -.:.~_~..: .. [L%l)(LJG~· _.~~~ .. ___ .(CLtJS ._. _. . .~~=_ ~ ~J User-Handled SVCs The programmer may use the HNDSVC macro to specify the address of a routine that processes any SVC call for SVC numbers 0 through 200 and 206 through 255. If the HNDSVC macro is used, the linkage conventions are as required by the user-specified SVC-handling routine. You cannot specify a normal or error return from a user-handled SVC routine. OS and VSE Macro Simulation SVC Calls CMS supports selected SVC calls generated by OS and VSE macros by simulating the effect of these macro calls. DMSITS is the initial SVC interrupt handler. If the SET DOS command has been issued, a flag in NUCON indicates that VSE macro simulation is to be used. Control is then passed to DMSDOS. Otherwise, OS macro simulation is assumed and Dr.1SITS passes control to the appropriate OS simulation routine. DMSDOS acquires the specified SVC code from the OLDPSW field of the current SVC save area. Using this code, DMSDOS computes the address of the routine where the SVC is to be handled. Many CMS/DOS routines (including DMSDOS) are contained in a discontiguous shared segment (DCSS). Most SVC codes are executed within DMSDOS, but some are in separate modules external to DMSDOS. If the SVC code requested is external to DMSDOS, its address is computed using a table called DCSSTAB. If the code requested is executed within DMSDOS, the table SVCTAB is used to compute the address of the code to handle the sve. Invalid SVC Calls There are several types of invalid SVC calls recognized by DMSITS. 1. Invalid sve number. If the SVC number does not fit into any of the classes described above, it is not handled by DMSITS. An error message is displayed on your terminal, and control is returned directly to the caller. 2. Invalid routine name in SVC 202 parameter list. If the routine named in the SVC 202 parameter list is invalid or cannot be found, DMSITS handles the situation in the same way as it handles an error return from a legitimate SVC routine. You receive an error code of -3. 3. Invalid sve 203 code. If an invalid code follows SVC 203 inline, an error message is displayed on your terminal and the abend routine is called to terminate execution. Chapter 5. Developing Programs under CMS 53 Search Hierarchy for SVC 202 SVC 202 Entered from a Program When a program issues SVC 202 and passes a routine or command name in the parameter list, DMSITS searches for the specified routine or command. (In the case of SVC 203 with a zero in the table entry for the specified index, the same logic must be applied.) As soon as the routine or command name is found, the search stops and the routine or command is executed. Figure 9 on page 58 and the following list describe the search order. 1. DMSITS determines if the specified name is known dynamically to CMS through the SUBCOM function. This step is executed only if the high-order byte of Rl contains X'02'. 2. DMSITS searches for a nucleus extension routine with the specified name. Note: This step is skipped if the high-order byte of register 1 contains X'03' or X'04'. X'03' indicates that an extended PLIST is provided. X'04' indicates that a tokenized PLIST is provided. X'03' and X'04' are translated to X'Ol' and X'OO', respectively, by the SVC interrupt handler before the called program is entered. 3. DMSITS searches for a routine with the specified name in the transient area. 4. DMSITS searches for a nucleus-resident command with the specified name. 5. DMSITS searches currently accessed disks for a file with the specified name and a filetype MODULE. CMS uses the standard search order (A through Z). If this search is successful, the specified module is loaded (via the LOADMOD command) and control is passed to the storage location now occupied by the command. The table of active (open) disk files is searched first. An open file may be used ahead of a file that resides on a disk earlier in the· search order. 6. DMSITS calls a. DMSPKT to search the translation tables for the specified name. If found, DMSITS searches for a routine with the valid translation by repeating steps 2 through 5. Note: This step is skipped if this SVC call is not from DMSINT or DMSCSF. 54 VM/SP eMS for System Programming L_~~. ___ .____.__ .____ ._.: __ .. _~.__ .__ .~__.___ .. _.. _ ..__... -':"" __ ._'. __ ~:'... _.___._ ......._. " ... _... _. __ ... _.... ____ ~__.__ ._: __ ~~_~~~_.~ __.~_::._:=~~:: __-_.::~. __. _- _:. __ .__.__ ~:~::~-':'J b. DMSINA to search the synonym tables for the specified name. If found, DMSITS searches for a routine with the valid synonym by repeating steps 2 through 5. If all searches fail, then an error code of -3 is issued. Commands Entered from the Terminal When a command is entered from the terminal, DMSINT processes the command line and calls the scan routine to convert it into a parameter list consisting of 8-byte entries. As soon as the command name is found, the search stops and the command is executed. Figure 8 on page 57 and the following list describe the search order. 1. Search for an EXEC with the specified command name: 1 a. DMSINT searches for an EXEC in storage. If an EXEC with this name is found, DMSINT determines whether the EXEC has a USER, SYSTEM, or SHARED attribute. If the EXEC has the USER or SYSTEM attribute, it is executed. If the EXEC has the SHARED attribute, the INSTSEG setting is checked. When INSTSEG is ON, all accessed disks are searched and the access mode of the Installation Discontiguous Shared Segment (DCSS) is compared to the mode of an EXEC with that name that resides on disk. If the access mode of the DCSS is equal to or higher than the disk mode, the EXEC is executed. Otherwise, the EXEC on disk is executed. b. 2. DMSINT searches accessed disks for a file with the specified name and filetype· EXEC. The table of active (open) disk files is searched first. An open file may be used ahead of a file that resides on a disk earlier in the search order. DMSINT calls a. DMSPKT to search the translation tables for the specified name. If found, DMSINT searches for a routine with the valid translation by repeating step 1. b. DMSINA to search the synonym tables for the specified name. If found, DMSINT searches for a routine with the valid synonym by repeating step 1. 3. DMSINT executes SVC 202, passing the scanned tokenized parameter list, with the command name in the first eight bytes of the PLIST pointed to by register 1 and the extended PLIST address in register O. If implied EXEC is not in effect (SET IMPEX OFF), skip steps 1 and 2. Chapter 5. Developing Programs under CMS 55 M8vG~(i)~d)UfJuf:~ [JrOCJG'ouuuG QJr;uC~GfJ1 CL1!JS . [------.=-::-::-~==:==-==:=====-=-=.~.~.~==.==-:::::::.=.:=~ ~~:::~=:--~~:~=::-.::=-=.:::=~~==---==-=:-.--.--. _._.. "-"'- .__ .- . DMSITS performs the search for SVC 202 as described above in "SVC 202 Entered from a Program." 4. DMSINT searches for a CP command with the specified name, using the CP DIAGNOSE instruction. 2 5. If all of these searches fail, DMSINT displays the error message: Unknown CP/CMS Command 2 If implied CP is not in effect (SET IMPCP OFF), skip step 4. 56 VM/SP CMS for System Programming [--_....- ... _-- - - . - -- --- ._-- Read line from terminal ("name ... ") Expand the line b inserting EXEC in front of the command name; ie. 'EXEC name' name is now a real name from a translation or synonym table No Issue SVC 202 (See SVC 202 subroutine) Notes: 1. If the command SET IMPEX OFF hos been executed, implied EXEC is not in effect. 2. This EXEC must exist in storage or on DASD. Poss line to CP for processing No No 3. A -3 return code indicates SVC 202 processing did not find the command. 4. If the command SET IMPCP OFF has been executed, implied CP is not in effect. Display UNKNOWN CP/CMS COMMAND Yes Display Ready ~------------------------------------------------~ ~~~~a~:dew;:h RC~-O Figure 8. CMS Command Processing Chapter 5. Developing Programs under CMS 57 Figure 9. SVC 202 Processing Command Search Function SUBCOM provides a function that lets you invoke a command (from a program) that is resolved according to the CMS command search hierarchy. That is, the command is resolved just as though the command was entered from the terminal. This SUBCOM function is named CMS. This command search function checks the IMPEX and IMPCP settings of CMS SET. 58 VM/SP eMS for System Programming [-- The CMS SUBCOM function is defined during system initialization at IPL and remains defined during the entire CMS session. To pass a command to the CMS SUBCOM function, the user should define PLISTs as follows: PLIST EXPLIST BEGARGS ENDARGS DS DC DS DC DC DC DC OF CL8'CMS' OF A(PLIST) A(BEGARGS) A(ENDARGS) DS DC EQU OF C'command to be invoked' A( 0) * Register 1 must contain the address of PLIST and a high order byte of X'02'. Register 0 must contain the address of the extended PLIST. Having established the PLIST and register information the user issues an SVC 202. The X'02' in the high order byte of register 1 indicates that this is a call to a previously defined SUBCOM. Dynamic Linkage/SUBCOM It is possible for a program that is already loaded from disk to become dynamically known by name to CMS for the duration of the current command; such a program can be called via SVC 202. In addition, this program can also make other programs dynamically known if the first program can supply the entry points of the other programs. To become known dynamically to CMS, a program or routine invokes the create function of SUBCOM. To invoke SUBCOM, issue the following calling sequence from an assembler language program: LA SVC DC R1,PLIST 202 AL4(ERROR) SUBCNAME SUBCPSW DS DC DC DC OF CL8'SUBCOM' CL8'narne' XL2'0000' SUBCADDR DC DC AL2(O) A(O) DC A(O) PLIST COMMAND NAME SYSTEM MASK, STORAGE KEY, ETC. RESERVED ENTRY ADDRESS, -1 FOR QUERY PLIST USER WORD SUBCOM creates an SCBLOCK control block containing the information specified in the SUBCOM parameter list. SVC 202 uses this control block to locate the specified routine. All non-system SUBCOM SCBLOCKS are released at the completion of a command (that is, when CMS displays the ready message). A SUBCOM environment may be defined as a system SUBCOM by setting a X'80' in the first byte of the interruption code field of Chapter 5. Developing Programs under CMS 59 the PLIST. See VM/SP Data Areas and Control Block Logic Volume 2 (eMS) for a description of the SCBLOCK control block. When a program issues an SVC 202 call to a program that has become known to CMS via SUBCOM, it places X'02' in the high-order byte of register 1. Control passes to the called program at the address specified by the called program when it invoked SUBCOM. The PSW in the SCBLOCK specifies the system mask, the PSW key to be used, the program mask (and initial condition code), and the starting address for execution. The problem-state bit and machine-check bit may be set. The machine-check bit has no effect in CMS under CPo The EC-mode bit and wait-state bit cannot be set. They are always forced to zero. Also, one 4-byte, user-defined word can be associated with the SUBCOM entry point and referred to when the entry point is subsequently called. When control passes to the specified entry point, the register contents are: R2 RI2 RIa RI4 RI5 Address of SCBLOCK for this entry point. Entry point address. 24-word save area address. Return address (CMSRET). Entry point address. You can also use SUBCOM to delete the potential linkage to a program or routine's SCBLOCK, or you can use SUBCOM to determine if an SCBLOCK exists for a program or routine. To delete a program or routine's SCBLOCK, issue: DC DC DC CL8'SUBCOM' CL8'program or routine name' 8X'OO' To determine if an SCBLOCK exists for a program or routine, issue: DC DC DC DC CL8'SUBCOM' CL8'program or routine name' A(O) SCBLOCK addressed as a returned value 4X'FF' Note that if 'SUBCOM name' is called from an EXEC file, the QUERY PLIST is the form of PLIST that is issued. To query the chain anchor, issue: DC DS DS CL8'SUBCOM' CL8 AL4 DC AL4(l) (contents not relevant) Will receive chain anchor contents from NUCSCBLK Indicates request for anchor Note that the anchor is equal to F'O' if there are no SCBLOCKs on the chain. 60 VM/SP eMS for System Programming /' L_.-. ____ ...~ .. _._____ .. __. __ ... 1 Note: If you create SCBLOCKS for several programs or routines with the same name, they are all remembered, but SUBCOM uses the last one created. A SUBCOM delete request for that name eliminates only the most recently created SCBLOCK making active the next most recently created SCBLOCK with the same name. When control returns to CMS after a console input command has terminated, the entire SUBCOM chain of SCBLOCKs is released. None of the subcommands established during that command are carried forward to be available during execution of the next console command. SUBCOM Function Return Codes Return codes from the SUBCOM function are: o Successful completion. A new SCBLOCK was created, the specified SCBLOCK was deleted, or the specified program or routine has an SCBLOCK. 1 No SCBLOCK exists for the specified program or routine. This is the return code for a delete or a query. 25 No more free storage available. SCBLOCK cannot be created for the specified program or routine. Returning to the Calling Routine When the called routine finishes processing, it returns control to DMSITS. Then DMSITS returns control to the calling routine. Return Location The return is accomplished by loading the original SVC old PSW, which was saved at the time DMSITS was first entered, after possibly modifying the address field. The address field modification depends upon the type of SVC call and upon whether the called routine indicated an error return. For SVC 202 and 203, the called routine places a zero in register 15 indicating a normal return and a nonzero code in register 15 indicating an error return. If the called routine indicates a normal return, DMSITS makes a normal return to the calling routine. If the called routine indicates an error return, DMSITS passes the error return address to the calling routine, if one was specified. If no error return address was specified, DMSITS abnormally terminates. For an SVC 202 not followed by "DC AL4(address)" or "DC AL4(1)", a normal return is made to the instruction following the SVC instruction and an error return causes an abend. For an SVC 202 followed by "DC AL4(address)", a normal return is made to the instruction following the DC and an error return is made to the address specified in the DC, unless the address is equal to 1. If the address is 1, return is made to the next Chapter 5. Developing Programs under CMS 61 [Q)Gt'7G~(i)~]UUu[j ~"2)~1~g!r8UuuG n.mucJG[j" ~L0~S) c=.___ ._____.____________._______._.__________.____________._._________._____._.__________________________ ~:::==========_==J instruction after the "DC AL4(1)" instruction. In either case, register 15 contains the return code passed back by the called routine. For an SVC 203 with a positive halfword code, a normal return is made to the instruction following the halfword code and an error return causes an abend. For an SVC 203 with a negative halfword code, both normal and error returns are made to the instruction following the halfword code. In any case, register 15 contains the return code passed back by the called routine. For OS macro simulation SVC calls and user-handled SVC calls, no error return is recognized by DMSITS. As a result, DMSITS always returns to the calling routine by loading the SVC old PSW that was saved when DMSITS was first entered. Register Restoration Upon entry to DMSITS, all registers are saved as they were when the SVC instruction was first executed. Upon exiting from DMSITS, all registers are restored to the values that were saved at entry. The exception to this is register 15 for SVC 202 and 203. Upon return to the calling routine, register 15 always contains the value that was in register 15 when the called routine returned to DMSITS after it had completed processing. Modification of the System Save Area If the called routine has system status so that it runs with a PSW storage protect key of 0, it may store new values into the system save area. If the called routine wishes to modify the location where control is to be returned, it must modify the following fields: o For SVC 202 and 203, the called routine must modify the NRMRET and ERRET (normal and error return address) fields. o For other SVCs, the called routine must modify the address field of OLDPSW. To modify the registers that are returned to the calling routine, the fields EGPR1, EGPR2, through EGPR15 must be modified. If this action is taken by the called routine, the SVCTRACE facility may print misleading information, since SVCTRACE assumes that these fields are exactly as they were when DMSITS was first entered. Whenever an SVC call is made, DMSITS allocates two save areas for that particular SVC call. Save areas are allocated as needed. For each SVC call, a system and user save area are needed. When the SVC-called routine returns, the save areas are not released. They are kept for the next SVC. If the routine invoked by the SVC called the parsing facility, any storage allocated by the parsing facility for parsing 62 VM/SP eMS for System Programming L..:........____ _ _ _ ...._..._... _... _... _. ~ results is released upon return. At the completion of each command, all SVC save areas allocated by that command are released. DMSITS uses the system save area to save the .value of the SVC old PSW at the time of the SVC call, the calling routine's registers at the time of the call, and any other necessary control information. Since SVC calls can be nested, there can be several of these save areas at one time. The system save area is allocated in protected free storage. The user save area (DSECT EXTUAREA) contains 12 doublewords (24 words) allocated in unprotected free storage. DMSITS does not use this area at all. It simply passes a pointer to this area (via register 13). The called routine can use this area as a temporary work area or as a register save area. Each system save area has one user save area. The USAVEPTR field in the system save area points to the user save area. The exact format of the system save area can be found in the VMj SP Data Areas and Control Block Logic Volume 2 (CMS). The most important fields and their uses are as follows: Field Usage CALLER (Full word) The address of the SVC instruction that resulted in this call. CALLEE (Doubleword) 8-byte symbolic name of the called routine. For OS and user-handled SVC calls, this field contains a character string of the form SVC nnn, where nnn is the SVC number in decimal. CODE (Halfword) For SVC 203, this field contains the halfword code following the SVC instruction line. OLDPSW (Doubleword) The SVC old PSW at the time that DMSITS was entered. NRMRET (Fullword) The address of the calling routine where control is passed in case of a normal return from the called routine. ERRET (Fullword) The address of the calling routine where control is passed in case of an error return from the called routine. EGPRS (16 Fullwords, separately labeled EGPRO, EGPRl, EGPR2, EGPR3, ... , EGPRI5) The entry registers. The contents of the general purpose registers at entry to DMSITS are stored in these fields. EFPRS (4 Doublewords, separately labeled EFPRO, EFPR2, EFPR4, EFPR6) The entry floating-point registers. The contents of the floating-point registers at entry to DMSITS are stored in these fields. ,. Chapter 5. Developing Programs under CMS 63 SSAVENXT (Fullword) The address of the next system save area in the chain. This points to the system save area being used, or will be used, for any SVC call nested in relation to the current one. SSAVEPRV (Full word) The address of the previous system save area in the chain. This points to the system save area for the SVC call in relation to where the current call is nested. USAVEPTR (Full word) Pointer to the user save area for this SVC call. The eMS Subset Environment When you issue the XEDIT subcommand: ems the editor responds: eMS subset and your virtual machine is in CMS subset mode. When in subset mode, you can issue any valid CMS subset command, that is, a CMS command that is allowed in CMS subset mode. The commands that are not allowed in the CMS subset environment are commands that execute in the user area. You can also issue CP commands. To return to edit mode, you use the special CMS subset command, RETURN. If you enter the Immediate command HX, your editing session terminates abnormally and your virtual machine returns to the CMS environment. When entering CMS subset mode either for a single command or until the string 'RETURN' is entered, the following processing is done to ensure that the previous environment is preserved. Upon entry to subset, a check is made to determine if this entry would constitute a recursion, if so, return code 1 is returned. 1. ST AE, SPIE, and STAX information is saved and then cleared. 2. The OS environment settings are saved and then cleared so that any module that issues an OSRESET based on these flags will not do so. 3. The read and write pointers from any currently opened files are saved. 4. All files are then closed by a 'FINIS * * *', but files with a filemode of 3 are not erased. 5. Any FSTs that were built by a previous call to STATE are saved. If the entry to subset was just for the execution of a single command, the entry message is suppressed and the next command is executed immediately. But, if the request was to enter CMS subset for an indefinite duration, an 64 VM/SP OMS for System Programming [ _ _ _ . _ _ _ _ •••. _ _ ••••• u ................_ .••.••. ~._ ...•_ .......... _ . • • • • . _ •. _ •••. _ • . h _ . • . • _ _ _ • • . _ _ • _ _ _ . • _ • • • • • • • _ _ . _ . _ _ _ •• _ . _ •• _ . _ _ _ _ _ _ _ _ _ • _ _ . _ . _ _ • _ _ _ • announcement of entry to the CMS subset environment is made. This is done so that a strict differentiation from the strict command environment is given. The principle difference in subset is the restriction that any command executed may not use any storage other than DMSFREE storage and the transient area. This protects programs which may be running in the USER AREA. Also, any ready message issued from subset is in the abbreviated form (i.e. identical to SET RDYMSG SMSG) so that program timing information is not affected for the command currently in progress at the time of subset entry. Upon termination of CMS subset mode any settings or values that were saved upon entry to subset are restored. Assembiing Programs To assemble assembler language source programs into object module format, you can use the ASSEMBLE command, .and specify assembler options on the command line. For example: assemble myfile (print assembles a source program named MYFILE ASSEMBLE and directs the output listing to the printer. All of the ASSEMBLE command options are listed in the VM/SP CMS Command Reference. When you invoke the ASSEMBLE command specifying a file with the filetype of ASSEMBLE, CrdS searches all of your accessed disks, using the standard search order, until it locates the specified file. When the assembler creates its output listing and text deck, it creates files with filetypes of LISTING and TEXT, and writes them onto disk according to the following priorities: 1. If the source file is on a read/write disk, the TEXT and LISTING files are written onto that disk. 2. If the source file is on a read-only extension of a read/write disk, the TEXT and LISTING files are written onto the parent disk. 3. If the source file is on any other read-only disk, the TEXT and LISTING files are written onto the A-disk. 4. If none of the above choices are available, the command is terminated. In all of the above cases, the TEXT and LISTING files have a filename that is the same as the input ASSEMBLE file. The input and output files used by the assembler are assigned by FILEDEF commands that CMS issues internally when the assembler is invoked. If you issue a FILEDEF command using one of the assembler ddnames before Chapter 5. Developing Programs under CMS 65 you issue the ASSEMBLE command, you can override the default file definitions. The ddname for the source input file (SYSIN) is ASSEMBLE. If you enter: filedef assemble reader assemble sample then the assembler reads your input file from your card reader and assigns the filename SAMPLE to the output TEXT and LISTING files. You could assemble a source file directly from an as disk by entering: filedef assemble disk myfile assemble b4 dsn os source file assemble myfile In this example, the CMS file identifier MYFILE ASSEMBLE is assigned to the data set OS.SOURCE.FILE and then assembled. LISTING and TEXT are the ddnames assigned to the SYSPRINT and SYSLIN output of the assembler. You might assign file definitions to override these defaults as follows: fi1edef listing disk assemble listfile a flledef text disk assemble textfile a assemble myfile In this example, output from the assembly of the file, myfile ASSEMBLE, is written to the files, ASSEMBLE LISTFILE and ASSEMBLE TEXTFILE. The ddnames PUNCH and CMSLIB are used forSYSPUNCH and SYSLIB data sets. PUNCH output is produced when you use the DECK option of the ASSEMBLE command. The default file definition for CMSLIB is the macro library CMSLIB MACLIB, but you must still issue the GLOBAL command if you want to use it. Executing Programs After you have assembled or compiled a source program, you can execute the TEXT files that were produced by the assembly or compilation. You may not, however, be able to ~xecute all ,your as programs directly in CMS. There are a number of execution-time restrictions placed on your virtual machine by VM/SP. You cannot execute a program that uses: • • • • • 66 Multitasking More than one partition Teleprocessing IS AM macros to read or write files The PSW EC mode bit VM/SP eMS for System Programming The above is only a partial list of restrictions you might be concerned with. For a complete list of restrictions, see the VMjSP Planning Guide and Reference. Executing TEXT Files TEXT files, in CMS, are relocatable and can be executed simply by loading them into virtual storage with the LOAD command and using the START command to begin execution. For example, if you have assembled a source program named CREATE, you have a file named CREATE TEXT. You can issue the command: load create that loads the relocatable object file into storage. Then, to execute it, you can issue the START command: start In the case of a simple program, as in the above example, you can load and begin execution with a single command line, using the START option of the LOAD command: load create (start When you issue the START command or LOAD command with the START option, control is passed to the first entry point in your program. If you have more than one entry point and you want to begin execution at an entry point other than the first, you can specify the alternate entry point or CSECT name on the START command: start create2 When you issue the LOAD command specifying the filename of a TEXT file, CMS searches all of your accessed disks for the specified file. If your program expects a parameter list to be passed (via register 1), you can specify the arguments on the START command line. If you enter arguments, you must specify the entry point: start * narnel When you specify the entry point as an asterisk (*), it indicates that you want to use the default entry point. Defining Input and Output Flies You can issue the FILEDEF command to define input and output files any time before you begin program execution. You can issue all your file definitions before loading any TEXT files, or you can issue them during the loading process. You can find out what file definitions are currently in effect by issuing the FILEDEF command with no operands. You can also use the FILEDEF operand of the QUERY command. Chapter 5. Developing Programs under CMS 67 ~1r:~\7~)~O[-vDUl}fj fDL"O['JG 8uu'Uf) ~nuucJc~G~ Gr\~s 1 . .. ....--:-:---.--:--:1 [::~~:.:~~~~~::-"- ~-:-:~~:~~-==_~===::-::~~=~===.~:=~~"'::"=-'::-~~-=" ~=:~~~----.-.-.----.-.~-.----~---- Resolving External References The CMS loader loads files into storage as a result of a LOAD or INCLUDE command. When a file is loaded, the loader checks for unresolved references. If there are any, the loader searches your disks for TEXT files with filenames that match the external entry name. When it finds a match, it loads the TEXT file into storage. If a TEXT file is not found, the loader searches any available TXTLIBs for members that match. If a match is found, it loads the member; If there are still unresolved references, for example, if you load a program that calls routines PRINT and ANALYZE but the loader cannot locate them, you receive the message: The following names are undefined: PRINT ANALYZE You can issue the INCLUDE command to load additional TEXT files or TXTLIB members into storage so die loader can resolve any remaining references. For example, if you did not identify the TXTLIB that contains the routines you want to call, you may enter the GLOBAL command followed by the INCLUDE command: global txtlib newlib include print analyze (start A failure to resolve external references might occur if you have TEXT files with filenames that are different from either the CSECT names or the entry names. You must explicitly issue LOAD and INCLUDE commands for these files. At execution time, if there are still any unresolved references, their addresses are all set to 0 by the loader; so any attempt to address them in a program may result in a program check. Controlling the CMS Loader The LOAD and INCLUDE Commands The INCLUDE command has the same format and option list (with one exception) as the LOAD command. The main difference is that when you issue the INCLUDE command the loader tables are not reset. If you issue two LOAD commands in succession, the second LOAD command cancels the effect of the first and the pointers to the files loaded are lost. Conversely, the INCLUDE command, which you must issue when you want to load additional files into storage, should not be used unless you have just issued a LOAD command. You may specify as many INCLUDE commands as necessary following a LOAD command to load files into storage. /' 68 VM/SP eMS for System Programming ~ lDGuG~co~)a~u~ ~·)G'(o~UG·'C:1ulnG QJu'~(Jc::[j' !(~~\fJ~~ . __ ___ . -.. ---- . --..-..----.-. ------.--.---------------------.. -----.---.-----.---... -..---. --.--.--.. -.---.. .- ~._-:.~: _.=_~.=- ~::_=~=._:.~-:-~-~:-:::~=~ =~_:..= ~:'::~J The LOAD and INCLUDE commands allow you to specify a number of options. You can: o Change the entry point to which control is to be passed when execution begins (RESET option). o Specify the location in virtual storage at which you want the files to be loaded (ORIGIN option). o Control how CMS resolves references and handles duplicate CSECT names (AUTO, LIBE, and DUP options). o Clear storage to binary zeros before loading files (CLEAR option). Otherwise, CMS does not clear user storage. o Save the relocation information from the text files (RLDSAVE option). If the RLDSAVE option is not specified on the LOAD and INCLUDE commands, the relocation information will not be saved for the fi~es being loaded into storage. o Save history information from the text files (HIST option). If the HIST option is not specified on the LOAD or INCLUDE commands, history information (comments) is not saved for the files being loaded into storage. When the LOAD and INCLUDE commands execute, they produce a load map, indicating the entry points loaded and their virtual storage locations. You may find this load map useful in debugging your programs. If you do not specify the NOMAP option, the load map is written onto your A-disk in a file named LOAD MAP A5. Each time you issue the LOAD command, the old file LOAD MAP is erased and the new load map replaces it. If you do not want to produce a load map, specify the NOMAP option. You can find details about these options under the LOAD command in the VM/ SP CMS Command Reference. Loader Control Statements In addition to the options provided with the LOAD and INCLUDE commands that assist you in controlling the execution of TEXT files, you can also use loader control statements. These can be inserted in TEXT files, using the CMS editor. The loader control statements allow you to: o Set the location counter to specify the address where the next TEXT file is to be loaded (SLC statement). o Modify instructions and constants in a TEXT file, and change the length of the TEXT file to accommodate modifications (Replace and Include Control Section statements). o Change the entry point (ENTRY statement). Chapter 5. Developing Programs under CMS 69 L . ___ .______ ._____ _ • Nullify an external reference so that it does not receive control when it is called, and you do not receive an error message when it is encountered (LIBRARY statement). These statements are also described under the LOAD command in the VM/ SP eMS Command Reference. Determining Program Entry Points When you load a single TEXT file or a TXTLIB member into storage for execution, the default entry point is the first CSECT name in the object file loaded. You can start execution at a different entry point by specifying the entry point on the LOAD (or INCLUDE) command with the RESET option. load myprog (reset beta where BETA is the alternate entry poin~ of your program, or you can specify the ~ntry point on the START command line: start beta When you load multiple TEXT files (either explicitly or implicitly by allowing the loader to resolve external references), you also have the option of specifying the entry point on the LOAD, INCLUDE, or START command lines. If you do not specifically name an entry point, the loader determines the entry point for you according to the following hierarchy: 1. An entry point specified on the START command 2. The last entry specified with the RESET option on a LOAD or INCLUDE command 3. The name on the last ENTRY statement that was read 4. The name on the last LDT statement that contained an entry name that was read 5. The name on the first assembler- or compiler-produced END statement that was read 6. The first byte of the first control section loaded. For example, if you load a series of TEXT files that contain no control statements and do not specify an entry point on the LOAD, INCLUDE, or START commands, execution begins with the first file that you loaded. If you want to control the execution of program subroutines, you should be aware of this hierarchy when you load programs or when you place them in TXTLIBs. An area of particular concern is when you issue a dynamic load (with the OS LINK, LOAD, or XCTL macros) from a program, and you call members 70 VM/SP eMS for System Programming [)GUG~6~)Duu~ ~J[['(QtJ[iC}uX;)8 L_.:: ~~._~-_ .____ ._._~. ____._n.__________...: . ---.... ------ ~~ =~-=-===~~=--=---====-==..::~=:::~:::= ~-- -.------.--~--- o.auuCC]8r/ ----.----------.. . .-.-_- C~JJ8 u._ --.---.-- --- -----, of CMS TXTLIBs. The CMS loader determines the entry point of the called program and returns the entry point to your program. If a TXTLIBmember that you load has a VCON to another TXT LIB member, the LDT card from the second member may be the last LDT card read by the loader. If this LDT card specifies the name of the second member, CMS may return that entry point address to your program rather than the address of the first member. Creating Program Modules When your programs are debugged and tested, you can use the LOAD and INCLUDE commands, in conjunction with the GENMOD command, to create program modules. A module is a file whose external references have been resolved. In CMS, these files must have a filetype of MODULE. To create a nonrelocatable module file, load the TEXT files or TXTLIB members into storage and issue the GENMOD command: load create analyze print genmod process The module is generated at the virtual storage address where it is loaded. In this example, PROCESS is the name of the module file, and it has a filetype of MODULE. You could use any name; if you use the name of an existing MODULE file, the old one is replaced. To execute the program composed of the source files CREATE, ANALYZE, and PRINT, enter: process If PROCESS requires input and/or output files, you have to define these files before PROCESS can execute properly. If PROCESS expects arguments passed to it, you can enter them following the MODULE name. For example, process testl If you want to call your own programs or CMS program modules using SVC 202 instructions, you must be careful not to execute a module that uses the same area of storage that your program occupies. If you want to call a module that executes at location X'20000', you can load the calling program at a higher location. For example, load create (origin 30000 As long as the MODULE file called by CREATE is no longer than X'lOOOO' bytes, it will not overlay your program. You can also use the LOAD and GENMOD commands to create a relocatable CMS module file. However, you must specify the RLDSA VE option in the LOAD command: Chapter 5. Developing Programs under CMS 71 []G\7G~(D[]IDuuS~l [)~1V[~[i18[jlruEi ~ . %U(~G[' (~~v18 r-----------.-----:~=_=_=~~.-----:-~.-.----------~_:_:_:=. ~ . . :.:~_~:.:.:... :.:~:::~:.:~:._.=~~_====.~==____ ===::_:_==___:~-=-:-::-~=.==_====._._._ ..J load progone (RLDSAVE genmod progtwo The relocatable CMS module file may now be established as a nucleus extension by issuing the NUCXLOAD command: nucxload progtwo Relocatable CMS module files may also be used with the LOADMOD command (for example, when issued as a command from the console). No relocation is performed when the LOADMOD command is used. Relocation is performed only when loaded by NUCXLOAD. You can use the LOAD, INCLUDE, and GENMOD commands to create a module that includes history information (comments) from the text file used. For example: load progone (HIST include progtwo (HIST genmod The generated module contains the comments that were in the text files progone and progtwo. Note: Many CMS disk-resident command modules execute in the user program area. That is, if you call a CMS command that runs in the user program area, you must be certain that it does not overlay your own program. Some CMS command modules issue the STRINIT macro or were created using the STR option of the GENMOD command. Both cause the user area storage pointers to be reset. The reset condition may cause errors upon return to the original program (for example, when OS GETMAIN/FREEMAIN macros are issued in the user program). The CMS commands that execute in the user program area or that reset the user area storage pointers are identified in the VM/ SP CMS Command Reference. The Transient Program Area To avoid overlaying programs executing in the user program area, you can generate program modules to run in the CMS transient area, which is a two-page area of storage reserved for the execution of programs that are called frequently. Many CMS commands run in this area, which is located at X'EOOO'. Programs that execute in this area run disabled. To generate a module to run in the transient area, use the ORIGIN TRANS option when you load the TEXT file into storage, then issue the GENMOD command. For example, load myprog (origin trans genmod setup (str 72 VM/SP eMS for System Programming L~_' .--.- -.. -----=:~.~: ___________________ . __._. ___ .. _._. ______ .____..:_. . _... __...-. ________ "" _.:: __________ __:___________ __ ~ ~ ~_:_. ____ .~_~-~_:...._=_~~=:=.~.:J Note: If a program running in the user area calls a transient routine in which a module was generated using the GENMOD command with the STR option, the user area storage pointers are reset. This reset condition could cause errors upon return to the original program (for example, when OS GETMAIN/FREEMAIN macros are issued in the user program). The two restrictions placed on command modules executing in the transient area are: 1. They may have a maximum size of 8192 bytes (the size of the transient area). 2. They must be serially reusable. When a program is called by an SVC 202 and if it is already loaded into the transient area, it is not reloaded. The CMS commands that execute in the transient area are identified in the VM/SP CMS Command Reference. Creating EXEC Procedures Depending on how you code your programs and EXECs, you can choose whether or not they will be recognized for translation into other languages. CMS only recognizes translations for commands entered from the command line (or with ADDRESS CMS from REXX or &PRESUME &SUBCOMMAND CMS from EXEC 2). CMS does not translate your command name or keywords if you SET TRANSLATE OFF or if you invoke the command from another program using SVC 202 (or with ADDRESS COMMAND from REXX or &PRESUME &COMMAND CMS from EXEC 2). For more information on command translation, refer to "Chapter 7. Developing Commands and Message Files" on page 113. During your program development and testing cycle, you may want to create EXEC procedures to contain sequences of CMS commands that you execute frequently. For example, if you need a number of MACLIBs, TXTLIBs, and file definitions to execute a particular program, you might have an EXEC procedure as follows: Chapter 5. Developing Programs under CMS 73 L ___________________._______ __________._______________________. _ _ ~. -::~~ =_===~_:::=J /* EXEC to set up environment to run program TESTA */ signal on error 'GLOBAL MACLIB TESTLIB OSMACRO OSMACR01' 'ASSEMBLE TESTA' 'PRINT TESTA "LISTING' 'GLOBAL TXTLIB TESTLIB PROGLIB' 'ACCESS 200 E' push 'OS.TEST3.STREAM.BETA' 'FILEDEF INDD1 E DSN ?' 'FILEDEF INDD2 READER' 'FILEDEF OUTFILE DISK TEST DATA A1' signal off error 'LOAD TESTA (START' select when rc = 100 then do end when rc 200 then do end otherwise exit rc end Error: say 'Error occurred on line' sigl':' sourceline(sigl) exit rc The "signal on error" control statement in the EXEC procedure ensures that if an error occurs during any part of the EXEC, the remainder of the EXEC does not execute, and the "Error:" displays the line number where the error occurred as well as the actual command which gave the error. Note: For the FILEDEF command entered with the DSN ? operand, you must stack the response (using "push") before issuing the FILEDEF command. When your program is finished executing, the REXX special variable RC indicates the contents of general register 15 at the time the program exited (the "Return Code"). You can use this value to perform additional steps in your EXEC procedure. Additional steps are indicated in the preceding example by ellipses. 74 VM/SP eMS for System Programming ~JGt7(3~([)~")auutJ ~·Ju·OUu·8u-lru8 c-----------------·... ---·--·_----·--------.-·----··-.-.-.------------.-----. ---.--.. ---_-._-.--_"_ __ QJu"u([JGu J G~U'JS - .--.. - ----------.----.::.:::1 eMS Macro Instruciions There are a number of assembler language macros distributed with the CMS system that you can use when you are writing programs to execute in the CMS environment. These macros are in the macro libraries CMSLIB MACLIB and DMSSP MACLIB, which are normally located on the system disk. o o CMSLIB MACLIB contains macros from VM/370. DMSSP MACLIB contains macros that are new or changed in VM/SP. Note: When assembling programs that use CMS macros, both of these libraries should be identified via the GLOBAL command. DMSSP should precede CMSLIB in the search order. There are macros to manipulate CMS disk files, to handle terminal communications, to manipulate unit record and tape input/output, and to trap interruptions. These macros are discussed in general terms here. For complete format descriptions, see the VMj SP eMS Macros and Functions Reference. Disk File Manipulation Disk files are described in CMS by means of a file system control block (FSCB). The CMS macro instructions that manipulate disk files use FSCBs to identify and describe the files. When you want to manipulate a CMS file, you can refer to the file by its file identifier, specifying 'filename filetype filemode' in quotation marks, or you can refer to the FSCB for the file, specifying FSCB = fscb, where fscb is the label on an FSCB macro. To establish an FSCB for a file, use the FSCB macro instruction specifying a file identifier. For example, INFILE FSCB 'INPUT TEST AI' You can also provide, on the FSCB macro instruction, descriptive information to be used by the input and output macros. If you do not code an FSCB macro instruction for a file, an FSCB is created in-line (following the macro instruction) when you code an FSREAD, FSWRITE, or FSOPEN macro instruction. The format of an FSCB and a description of each of the fields are listed below. Label FSCBCOMM DC CL8' Figure 10 (Part 1 of 2). , Description File system command FSCB Format Chapter 5. Developing Programs under CMS 75 L ____________________________________ _._ .. _.. J Label , , , FSCBFN DC CL8' FSCBFT DC CL8' FSCBFM DC CL2' FSCBITNO DC H'O' FSCBBUFF DC A'O' FSCBSIZE DC F'O' FSCBFV DC CL2'F' FSCBFLG EQU FSCBFV+l FSCBNOIT DC H'l' FSCBNORD DC AL4(O) FSCBAITN DC AL4(O) FSCBANIT DC AL4(l) FSCBWPTR DC AL4(O) FSCBRPTR DC AL4(O) Figure 10 (Part 2 of 2). Description Filename Filetype Filemode Relative record number (RECNO) Address of buffer (BUFFER) Number of bytes to read or write (BSIZE) Record format - F or V (RECFM) Flag byte Number of records to read or write (NOREC) Number of bytes actually read Extended FSCB relative record number Extended FSCB relative number of records Extended FSCB relative write pointer Extended FSCB relative read pointer FSCB Format The FSCBAITN, FSCBANIT, FSCBWPTR, and FSCBRPTR fields are only generated in the FSCB when the extended format FSCB is requested (FORM = E is coded on the FSCB macro instruction). In this case, the FSCBITNO and FSCBNOIT fields are reserved fields. Extended format FSCBs must be used to manipulate files larger than 65,533 items. The labels shown above are not generated by the FSCB macro. To reference fields within the FSCB by these labels, you must use the FSCBD macro instruction to generate a DSECT. FSCBCOMM: When the FSCBFN, FSCBFT, and FSCBFM fields are filled in, you can fill in the FSCBCOMM field with the name of a CMS command and use the FSCB as a parameter list for an SVC 202 instruction. (You must place a delimiter to mark the end of the command line.) FSCBFN, FSCBFT, FSCBFM: The filename, filetype, and filemode fields identify the CMS file to be read or written. You can code the fileid on a macro line in the format 'filename filetype filemode', or you can use register notation. If you use register notation, the register you specify must point to an IS-byte field in the format: FILEID 76 DC DC DC VM/SP eMS for System Programming CL8'filename' CL8'filetype' CL2'filemode' [Dc:rJG~([)~JDuuO l")u~V&Ju'8ulJuG (~=-=~~:~--=-=~=~=--=~~.=--.=-=:~.:.-:..:~~:~--==-~--=-=.::~~==--==:~ GJDucJeu' G~v'JS . _-- . - -.. _- --.- - - - - - - - - - - - - - ------------------' The fileid must be specified either in the FSCB for a file or on the FSREAD, FSWRITE, FSOPEN, or FSERASE macro instruction that references the file. FSCBITNO: For an FSCB without the FORM = E option, the record or item number indicates the relative record number of the next record to be read or written. It can be changed with the RECNO option. The default value for this field is O. When you are reading a file, a 0 indicates that records are to be read sequentially beginning with the first record in the file. When you are writing a file and the file already exist, a 0 indicates that records are to be written sequentially beginning at the first record following the end of the file. If the file is a new file, begin writing at record 1. For an FSCB generated with the FORM = E option, the FSCBAITN field contains the record or item number. The FSCBITNO field is reserved. Whenever you read discontiguous files in CMS (that is, files with missing records), the input buffer will be filled with the appropriate number of bytes. Be aware that the flag byte in the FSCB may not reflect whether the input buffer contains generated data items from RDBUF. FSCBB UFF: The buffer address, specified in the BUFFER option, indicates the label of the buffer where the record is to be written from or where the record is to be read into. You should always supply a buffer large enough to accommodate the longest record you expect to read or write. This field must be specified either in the FSCB or on the FSREAD or FSWRITE macro instruction. FSCBSIZE: This field indicates the number of bytes that are read or written with each read or write operation. The default value is O. If the buffer that you use represents the full length of the records you are going to be reading or writing, you can use the BSIZE option to set this field equal to your buffer length. When you are writing variable-length records, use the BSIZE operand to indicate the length of each record you write. This field must be specified. FSCBFV: This two-character field indicates the record format (RECFM) of the file. The default value is F (fixed). FSCBFLG: The flag byte is X'20' indicating an extended FSCB is generated when the FORM = E option is coded on the FSCB macro instruction. FSCBNOIT: For an FSCB without the FORM = E option, this field contains the number of whole records to be read or written in each read or write operation. You can use the NOREC option with the BSIZE option to block and deblock records. For an FSCB generated with the FORM = E option, the FSCBANIT field contains the number of whole records to be read or written. The FSCBNOIT field is reserved. Chapter 5. Developing Programs under CMS 77 FSCBNORD: Following a read operation, this field contains the number of bytes actually read, so if you are reading a variable-length file, you can determine the size of the last record read. The FSREAD macro instruction places the information from this field into register O. FSCBAITN: The alternate record or item number indicates the 'relative record number of the next record to be read or written in an extended FSCB format. See the description of the FSCBITNO field for the usage of this field. FSCBANIT: This field contains the alternate number of whole records in an extended FSCB format. See the description of the FSCBNOIT field for the usage of this field. FSCB WPTR: The FSPOINT macro instruction uses this field to contain the alternate write pointer for an extended FSCB during a POINT operation. FSCBRPTR: The FSPOINT macro instruction uses this field to contain the alternate read pointer for an extended FSCB during a POINT operation. Using the File System Control Block (FSCB) The following example shows you how to code an FSCB macro instruction to define various file and buffer characteristics and how to use the same FSCB to refer to different files: FSREAD 'INPUT FILE Al' ,FSCB=COMMON,FORM=E FSWRITE 'OUTPUT FILE Al',FSCB=COMMON,FORM=E COMMON SHARE FSCB DS BUFFER=SHARE,RECFM=V,BSIZE=200,FORM=E CL200 In the above example, the fileid specifications on the FSREAD and FSWRITE macro instructions modify the FSCB at the label COMMON each time a read or write operation is performed. You can also modify an FSCB directly by referring to fields by a displacement off the beginning of the FSCB. For example, MVC FSCB+8,=CL8'NEWNAME' moves the name NEWNAME into the filename field of the FSCB at the label FSCBFN. As an alternative, you can use the FSCBD macro instruction to generate a DSECT and refer to the labels in the DSECT to modify the FSCB. For example, 78 VM/SP eMS for System Programming · '---'-"'--'~~ LA RS,INFSCB USING FSCBD,RS MVC INFSCB NEWNAME FSCBFN,NEWNAME FSCB 'INPUT TEST AI' , FORM=E DC CL8'OUTPUT' FSCBD In the above example, the MVC instruction places the filename OUTPUT into the FSCBFN (filename) field of the FSCB. The next time this FSCB is referenced, the file OUTPUT TEST is the file that is manipulated. Reading and Writing eMS Disk Files CMS disk files are sequential files. When you use CMS macros to read and write these files, you can access them sequentially with the FSREAD and FSWRITE macros. However, you may also refer to records in a CMS file by their relative record numbers. So you can, in effect, access records using a direct access method. If you know the record you want to read or write, you can specify the RECNO option on the FSCB macro instruction or on the FSOPEN, FSREAD, or FSWRITE macro instructions. When you use the RECNO option on the FSCB macro instruction, you must specify the exact record number. For the FSOPEN, FSREAD, or FSWRITE macro instructions, you may either specify the exact record number: WRITE FSWRITE FSCB=WFSCB,RECNO=IO,FORM=E or specify the register containing the record to be read: WRITE FSWRITE FSCB=WFSCB,RECNO=(S),FORM=E When you want to access files sequentially, the FSCBITNO field of the FSCB must be 0 for an FSCB without the FORM = E option. For an extended FSCB, the FSCBAITN field must be o. This is the default value. When you are reading files with the FSREAD macro instruction, reading begins with record number 1. When you are writing records to an existing file with the FSWRITE macro, writing begins following the last record in the file. To begin reading or writing files sequentially beginning at a specific record number, you must specify the RECNO option twice: once to specify the relative record number where you want to begin reading, and a second time to specify RECNO = 0 so reading or writing will continue sequentially beginning after the record just read or written. You can specify the RECNO option on the FSREAD or FSWRITE macro instruction, or you may change the FSCBITNO or FSCBAITN field in the FSCB for the file, as necessary for the FSCB form. For example, to read the first record and then the 50th record of a file, you could code the following: Chapter 5. Developing Programs under CMS 79 ..___________ .__ ._._.__ . ___.__.____._._.. _.. ____ ~_._.~______ ...__ . .__.______._..___ ._J READl READ50 RFSCB WFSCB COMMON FSREAD FSCB=RFSCB,FORM=E FSWRITE FSCB=WFSCB,FORM=E LA 5,RFSCB USING FSCBD,5 MVC FSCBAITN,=F'50' FSREAD FSCB=RFSCB,FORM=E FSWRITE FSCB=WFSCB,FORM=E FSCB 'INPUT FILE Al',BUFFER=COMMON,BSIZE=120,FORM=E FSCB 'OUTPUT FILE Al' ,BUFFER=COMMON,BSIZE=120,FORM=E OS CL120 FSCBD In this example, the statements at the label READI write record I from the file INPUT FILE Al to the file OUTPUT FILE AI. Then, using the DSECT generated by the FSCBD macro, the FSCBITNO field is changed because an extended FSCB is being used. FSCBAITN field is changed because an extended FSCB is being used and record 50 is read from the input file and written into the output file. The "update-in-place" facility allows you to write blocks back to their previous location on disk. The "update-in-place" attribute of a CMS file is indicated by the filemode number 6. Reading and Writing Variable Length Records When you read or write variable-length records, you must specify RECFM = V either in the FSCB for the file or on the FSWRITE or FSREAD macro instruction. The read/write buffer should be large enough to accommodate the largest record you are going to read or write. To write variable-length records, use the BSIZE = option on the FSWRITE macro instruction to indicate the record length for each record you write. To read variable-length records, register 0 contains, on return from FSREAD, the length of the record read. The following example shows how you could read and write a variable-length file: READ FSREAD 'DATA CHECK Al' ,BUFFER=SHARE,BSIZE=130, ERROR=OUT,FORM=E FSWRITE 'COPY DATA Al' ,BUFFER=SHARE,BSIZE=(O),FORM=E B READ When you update files of variable-length records, the replacement record must be the same length as the origin.al record. An attempt to write a record shorter or longer than the original record results in truncation of the file at the specified record number. No error return code is given. 80 VM/SP eMS for System Programming r.-.u. . ----.. . . -... -.. -.----..... ~ End-ol-File Checldng You can specify the ERROR = operand with the FSREAD or FSWRITE macro instruction so an error handling routine receives control in case of an error. In CMS, when an end of file occurs during a read request, it is treated as an error condition. The return code is always 12. If you specify an error handling routine on the FSREAD macro instruction, the first thing this routine can do is check for a 12 in register 15. Your error handling routine may also check for other types of errors. See the macro description in the VMjSP eMS Macros and Functions Reference for details on the possible errors and the associated return codes. Opening and Closing Files Usually, CMS opens a file whenever an FSREAD or FSWRITE macro instruction is issued for the file. When control returns to CMS from a calling program, all files accidentally left open are closed by CMS. Therefore, you do not have to close files at the end of a program. For a minidisk in 512-, lK-, 2K-, or 4K-byte block format, a file may be open for concurrent read and write operations and an FSCLOSE need not be issued when switching from reading to writing, or vice versa. For example: LA READ 3,2 FSREAD FSCB=UPDATE,RECNO=(3),ERROR=READERR,FORM=E FSWRITE FSCB=UPDATE,RECNO=(3) ,ERROR=WRITERR,FORM=E LA 3,1(3) B READ UPDATE FSCB 'UPDATE FILE A1' ,BUFFER=BUF1,BSIZE=80,FORM=E When you are running long running applications or running disconnected, include several FSCLOSE macros to each file referenced. This insures that changes to the file are reflected on the disk in the event that the user is forced off the system. This consideration is important when running on 512-, lK-, 2K-, or 4K-byte block disks since the disk directory is not updated until all of the files on the disk are closed. If you want to read and write records from the same file on an 800-byte block format minidisk, you must issue an FSCLOSE macro instruction to close the file whenever you switch from reading to writing. For example: Chapter 5. Developing Programs unde'r CMS 81 READ LA 3,2 FSREAD FSCB=UPDATE,RECNO=(3),ERROR=READERR FSCLOSE FSCB=UPDATE FSWRITE FSCB=UPDATE,RECNO=(3),ERROR=WRITERR FSCLOSE FSCB=UPDATE LA 3,1(3) B READ UPDATE FSCB 'UPDATE FILE Al' ,BUFFER=BUF1,BSIZE=80 To execute a loop to read, update, and rewrite records, you must read a record, close the file, write a record, close the file, and so on. Since closing a file repositions the read pointer to the beginning of the file and the write pointer at the end of the file, you must specify the relative record number (RECNO) for each reaq and write operation. In the above example, register 3 is used to contain the relative record number. It is initialized to begin reading with the second record in the file and is increased by one following each write operation. When you use an EXEC to execute a program to read or write a file, the file is not closed by CMS until the EXEC completes execution. Therefore, if you read or write the same file more than once during the EXEC procedure, you must use an FSCLOSE macro instruction to close the file after using it in each program, or you must use the FSOPEN macro instruction to open it before each use. Otherwise, the read or write pointer is positioned as it was when the previous program completed execution. Creating New Files When you want to begin writing a new file using CMS data management macros, there are two ways to ensure that the file you want to create does not already exist. One way is to issue the FSST ATE macro instruction to verify the existence of the file. A second way to ensure that a file does not already exist is to issue an FSERASE macro instruction to erase the file. If the file does not exist, register 15 returns with a code of 28. If the file does exist, it is erased. See Figure lIon page 83 for an illustration of a sample program using CMS data management macros. 82 VM/SP eMS for System Programming [JG~JG~([D~3au1[J ~)u'O[Jr/8Uliu9 [~Ju'u(JGu~ C~JS c --.------------.-----.. ---- .. --- -.. -.-.-.-.-.- . --.-- ---.-- -.---.-----.---.------.-.-.. ---..-.. LINE ~~.-.-.--.-------._=_----------------.---=.--------------1 SOURCE STATEMENT BEGIN CSECT PRINT NOGEN USING *,12 ESTABLISH ADDRESSABILITY LR 12,15 ST 14,SAVE LA 2,8(,1) R2=ADDR OF INPUT FILEID IN PLIST LA 3,32(,1) R3=ADDR OF OUTPUT FILEID IN PLIST * DETERMINE IF INPUT FILE EXISTS FSSTATE (2),ERROR=ERR1,FORM=E 2 * * READ A RECORD FROM INPUT FILE AND WRITE ON OUTPUT FILE RD FSREAD (2),ERROR=EOF,BUFFER=BUFF1,BSIZE=80,FORM=E FSWRITE (3),ERROR=ERR2,BUFFER=BUFF1,BSIZE=80,FORM=E B RD LOOP BACK FOR NEXT RECORD ** COME HERE IF ERROR READING INPUT FILE 4 EOF 15,=F'12' END OF FILE ? C ERROR IF NOT BNE ERR3 15,0 ALL O.K. - ZERO OUT R15 LA EXIT GO EXIT B * IF INPUT FILE DOES NOT EXIST ERR1 WRTERM 'FILE NOT FOUND' ,EDIT=YES EXIT B ** IF ERROR WRITING FILE ERR2 LR 10,15 SAVE RET CODE IN REG 10 5 LINEDIT TEXT='ERROR CODE .... IN WRITING FILE' ,SUB=(DEC,(10)) B EXIT * * IF READING ERROR WAS NOT NORMAL END OF FILE ERR3 LR 10,15 SAVE RET CODE IN REG 10 5 LINEDIT TEXT='ERROR CODE .... IN READING FILE',SUB=(DEC,(10))· * 14,SAVE LOAD RETURN ADDRESS EXIT L RETURN TO CALLER BR 14 * BUFF1 DS CL80 SAVE DS F END Figure 11 (Part 1 of 2). A Sample Listing of a Program that Uses eMS Macros Chapter 5. Developing Programs unde-r CMS 83 L. ........_____ .____ .__._ _ _.______ ... __ ......... _._ . · _...._........ J Notes: The program might be invoked with a parameter list in the format: progname INPUT FILE Al OUTPUT FILE AI. This line is placed in a parameter list by CMS routines and addressed by register 1 (see note 2). 2 The parameter list is a series of doublewords, each containing one of the words entered on the command line. Thus, 8 bytes past register 1 is the beginning of the input fileid. 24 bytes beyond that is the beginning of the second fileid. 3 The FSREAD and FSWRITE macros cause the files to be opened. No open macro is necessary. CMS routines close all open files when a program completes execution (except CMS EXEC files). 4 The return code in register 15 is tested for the value 12, indicating an end-of-file condition. If it is the end of the file, the program exits. Otherwise, it writes an error message. The dots in the LINEDIT macro are substituted, during execution, register 10. . Figure 11 (Part 2 of 2). with the decimal value in A Sample Listing of a Program that Uses eMS Macros Terminal Communications There are four CMS macros you can use to write interactive, terminal-oriented programs. They are RDTERM, WRTERM, LINEDIT, and WAITT. RDTERM and WRTERM only require a read/write buffer for sending and receiving lines from the terminal. The third, LINEDIT, has a substitution and translation capability. When you use the WRTERM macro to write a line to your terminal you can specify the actual text line in the macro instruction, for example: DISPLAY WRTERM 'GOOD MORNING' You can also specify the message text by referring to a buffer that contains the message. The RDTERM macro accepts a line from the terminal and reads it into a buffer you specify. You could use the RDTERM and WRTERM macros together, as follows: WRITE READ 84 REWRITE WRTERM 'ENTER LINE' RDTERM BUFFER LR 3,0 WRTERM BUFFER, (3) BUFFER DS VM/SP eMS for System Programming CL130 UJGUG~(D~)DuuCJ ~)u'ogG'~]U'~lS rr.~uue]G[i· (- -- - - -_. -. --- - _.- _. -.-.- - _. -: : ---------..- - - - - - - - -_.- _._- . -.- -..- - - - -_.- - ~. .-==-~~-.--- (GWJS . -.- -._._ . _. - ---_._.- -_._-_._- -_._._.- -_. _-_._ . _.- - -. ---_._- - -_._-_. _._.- .--~-] In this example, the WRTERM macro results in a prompting message. Then the RDTERM macro accepts a line from the terminal and places it in the buffer BUFFER. The length of the line read, contained in register 0 on return from the RDTERM macro, is saved in register 3. When you specify a buffer address on the WRTERM macro instruction, you must specify the length of the line to be written. Here, register notation is used to indicate that the length is contained in register 3. The LINEDIT macro converts decimal and hexadecimal data into EBCDIC, and places the converted value into a specified field in an output line. There are list and execute forms of the macro instruction, which you can use in writing reentrant code. Another option allows you to write lines to the offline printer. The LINEDIT macro is described, with examples, in VM/SP eMS Macros and Functions Reference. Figure 11 on page 83 shows how you might use the LINEDIT macro to convert and display CMS return codes. The WAITT (wait terminal) macro instruction can help you to synchronize input and output to the terminal. If you are executing a program that reads and writes to the terminal frequently, you may want to issue a WAITT macro instruction to halt execution of the program until all terminal I/O has completed. Unit Record and Tape 1/0 CMS provides macros to simplify reading and punching cards (RDCARD and PUNCHC), and creating printer files (PRINTL). When you use either the PUNCHC or PRINTL macros to write or punch output files while a program is executing, you should remember to issue a CLOSE command for your virtual printer or punch when you are finished. You can do this either after your program returns control to CMS, by entering: cp close e or -cp close d or you can set up a parameter list with the command line CP CLOSE E or CP CLOSE D and issue an SVC 202. The tape control macros, RDT APE, WRTAPE and T APECTL, can read and write CMS files from tape, or control the positioning of a tape. Handling Interrupts You can set up routines in your programs to handle interruptions caused by . I/O devices, by SVCs, or by external interruptions using the HNDINT, HNDSVC, or HNDEXT macro instructions. With the HNDINT macro instruction, you can specify addresses that are to receive control when an interruption occurs for a specified device. If the Chapter 5. Developing Programs under CMS 85 [iJ)G~G~(iJ)[J)Hn1@J ~fi1Q)QW'@rruus MUuC0]en ~M§ 1 c _________ .____________ =-:======-_._____.__._________. _____ ______. . _____. _______________._.___.______=:::J ~. WAIT option is used for a device specified in the HNDINT macro , instruction, then the interruption handling routine specified for the device does not receive control until after the WAITD macro instruction is issued for the device. You can use the HNDSVC macro instruction to trap supervisor call instructions of particular numbers, if, for example, you want to perform some additional function before passing control or you do not want any SVCs of the specified number to be executed. The CP EXTERNAL command simulates external interruptions in your virtual machine; if you want to be able to pass control to a particular internal routine in the event of an external interruption, you can use the HNDEXT macro instruction. System Product Editor Interface to Access Files in Storage CMS uses the SUBCOM facility to allow a number of CMS commands to use an XEDIT interface to access files in storage. Applications can read or write specific records without having to go to disk or use the program stack to transfer the data to or from XEDIT. This improves performance. CMS uses the XEDIT interface for processing the FILELIST, HELP, MACLIST, PEEK, and SENDFILE commands. The interface is invoked by specifying the XEDIT option on the LISTFILE, MACLIB, or NAMEFIND commands. This option may only be specified from the XEDIT environment. When using this interface from an application program, only the extended parameter list can be used, and the high-order byte of of register 1 must contain X'02' to indicate SUBCOM is being used. The application can invoke this interface via SVC 202 or via a BALR instruction. Because XEDIT is a nucleus-resident routine, other nucleus-resident routines can branch directly to it while routines that do not reside in the nucleus use SVC linkage. When using an SVC 202, register 1 must point to the FSCB where the name of the routine being invoked is the first token. The high-order byte of register 1 must also be X'02'. When usingBALR, the calling program can determine the entry point it wants by using SUBCOM. In this case, register 1 points to the FSCB and register 2 points to the SCBLOCK. The address of the the SCBLOCK has been returned from SUBCOM. The routines available, their entry point names, and error return codes are: o DMSXFLST - This routine returns the characteristics of a file (RECFM, LRECL, etc). It also ensures that the file is in the XEDIT ring. The return codes are: o 24 86 File is in the XEDIT ring Incomplete fileid specified VM/SP eMS for System Programming c--_·_·__· __ ·_· · __· : . . . ._...... -............. --_._._._ ............ _. . -.__.. . 28 [~~GU(:;~C)~JUur~~J lJu1tDOu"c:lu'ul1S llJu!)[JSG' G~uJS . -. :..-=:~~=~:==-==::.~:~::.===:-=:..:~==-::.=::.::.:.===~~===-=~~.=~.=:-:-.=J File is not in the XEDIT ring Note: Return codes are similar to those for EST ATE. • DMSXFLRD - This routine transfers one record from XEDIT storage to the calling program. If RECFM = F, it may transfer more than one record. The return codes are: o 1 2 5 7 8 11 12 READ performed File is not in the XEDIT ring Invalid buffer address Number of items equals zero RECFM is not 'F' or 'V' Buffer is too small (records truncated) Number of items is not equal to one for V-file End of file Note: Return codes are similar to those for FSREAD. o DMSXFLWR - This routine transfers one record from the calling program to XEDIT storage. If RECFM = F, it may transfer more than one record. The return codes are: o 2 7 8 11 13 14 15 16 18 28 WRITE performed User buffer address equals zero Skip over unwritten records Number of bytes is not specified RECFM is not 'F' or 'V' No more space is available Number of bytes is not integrally divisible by the number of item Item length is not the same as previous RECFM of 'F' or 'V' is not the same as previous Number of items is not equal to one for V-file File is not in the XEDIT ring Note: Return codes are similar to those for FSWRITE. o DMSXFLPT - This routine moves the current line pointer to a record specified by the calling program. If you specify the read and write pointer as all ones (X'FFFFFFFFX'), the current line pointer is returned in the FSCB. The return codes are: o 1 2 POINT performed File not found Invalid FSCB Note: Return codes are similar to those for FSPOINT. When the interface is used, XEDIT determines if a file is in the XEDIT ring (active in storage) and does the processing required. The files in the XEDIT ring are always open. New files may be added to the ring with the XEDIT subcommand. Files in the ring may be closed with the FILE or QUIT subcommands. Chapter 5. Developing Programs under CMS 87 The current line pointer serves the function of both the read and write pointers of the CMS file system. If RECNO = 0 is specified in a call to DMSXFLRD, the data is transferred to the calling program starting at the current line pointer. Transfer is stopped when the specified number of lines has been transferred or when end-of-file is reached. The current line pointer is advanced by one for each record transferred to the calling program. If the current line pointer was at the end-of-file when DMSXFLRD was called, no data is transferred and an end-of-file condition is returned. If RECNO = 0 is specified in a call to DMSXFLWR, new records are written starting at the line pointed to by the current line pointer. These new records replace any existing records or add new records if at the end-of-file. The current line pointer is advanced to the line following the last line written at the end of the operation. Note that writing to a record in the middle of a V-format file does not result in truncation of the file from that point as it would in the CMS file system. Truncation (or spilling when SET SPILL ONIWORD) may occur if the file is in V-format and the LRECL of the file is less than the length of the record(s) being written. No message is issued and the return code is o. eMS Interface for Display Terminals CMS has an interface allowing it to display large amounts of data in a very rapid fashion. This interface for 3270 display terminals (also 3138, 3148, and 3158) is much faster and has less overhead than the normal write because it displays up to 1760 characters in one operation instead of issuing 22 individual writes of 80 characters each (that is, one write per line on a display terminal). Data displayed in the screen output area with this interface is not placed in the console spool file. The console facility provides a CMS macro interface to full-screen I/O that: o C) provides screen coordination and provides an architecturally independent I/O interface. Use the console facility instead of the DIAGNOSE code X'58' interface or the DISPW macro. The console facility provides improved usability for writing 3270 I/O applications. The CONSOLE macro performs I/O operations such as: • • • • building the channel command word (CCW), issuing DIAGNOSE code X'58' or Start I/O (SIO) instruction, waiting for the I/O to complete, and checking any error status from the device. Applications must construct a valid 3270 data stream to write to the screen, and a 3270 data stream is returned when a CONSOLE READ is performed. 88 VM/SP eMS for System Programming r . ... _.- --- ------_ . __. _--_._-- .----- ---. _. __.- ~-:. lOc:r~e~O[JQJ J[J LJ~\)Uu'(Ju~ruS ~Ju'ilck~GJ (GGtJ~3 ---. - -------, --------~:-~---.:-~~~:~- -~-.-:.:..-~-.~~--=:..:::--~:=~--~::.:~~~.=-.~. The CONSOLE macro allows programs to open 'paths' to a display device. A path is a unique name that distinguishes one application from another and allows the console facility to coordinate the use of the screen. For example, if an application is writing to the screen, the CONSOLE macro tells it that another 'path' has updated the screen lastly, and, therefore, the screen must be reformatted. Because of this, full-screen applications do not have to rewrite the entire screen every time a write is done. Screen coordination can be done only for applications using the console facility. Because some application still issue their own DIAGNOSE code X'58', you must reformat the screen. This avoids mixing data from two different applications on the screen. Refer to "The CONSOLE Macro" on page 90 for more details. The CONSOLE macro provides the following functions: o OPEN/CLOSE - Opening and closing a specific path to the console. o READ/WRITE - Reading and writing buffers that have 3270 data streams built by the application. In order to write to the screen, applications must construct a valid 3270 data stream. When a read is performed, the data is returned in the user's buffer. The CMS console facility issues the DIAGNOSE code X'58' for the virtual console or a Start I/O (SIO) for dialed devices, builds the CCW for READ and WRITE requests, tests conditions after I/O, and gives the result of the I/O operation to the application. o EXCP - Performing READ or WRITE I/O operations using CCWs that applications supply. An application must supply its own CCW if it uses the EXCP function. This function is intended for use with dialed devices. o WAIT - Wait for an I/O interrupt from the console device. o QUERY - Getting information about the device attributes (DIAGNOSE code X'24' and DIAGNOSE code X'8C'), or if the path is opened, getting information about a specific path and its associated device. The user should provide a buffer for this information and then map the information using the CQYSECT mapping macro. For information about the CQYSECT macro, refer to The four formats of the CONSOLE macro instruction are: Standard format It is not reentrant. List format (MF = L) Generates a parameter list, but does not generate code to execute the function. The parameter list is generated in-line and usually register notation cannot be used. Chapter 5. Developing Programs under CMS 89 [Q)GnJG~(»[]DuuQJ ru (Q)gu C}uuuS tDuu(JGu CLlfJ8 1 1 1 L __________ . _____._._. _.~_______________.__.______.__. _.._. ___.____ ..._. . ______. _. ____ .___ . . ______. Complex List format (MF = (L,addr[,label])) Generates a parameter list, but does not generated code to execute the function. The parameter list is generated in an area that you specify. Execute format (MF = (E,addr)) Generates code to execute the function. Note: For the detailed formats of the CONSOLE macro, see VM/ SP eMS Macros and Functions Reference. The CONSOLE Macro An Example of Using the Console Facility • OPEN a path with the optional BUFFER parameter. o Get information about the device from the buffer. o Build a 3270 data stream. e Issue the CONSOLE WRITE with the EW option. • Issue the READ with the WAIT option. o Check the return code. • If the return code from READ or WRITE is not 0, issue a QUERY to determine what happened. • CLOSE the path. Opening a Path In order to use the CMS console facility for I/O, you must first open a 'path'. You can do this by issuing the OPEN parameter of the CONSOLE macro. When you open a path, the console facility allocates storage containing information about I/O activity for the application. A path entry is associated with a device when you specify the CONSOLE OPEN parameter. If the device does not already have paths opened to it, storage is allocated for a new device entry and any existing device entries are linked to it. 90 VM/SP eMS for System Programming r-·-·---······ .. ·..--··--·-·-··-------·-·---·-·--·--·---------.-.-------.--.--------.. -.-.......-.-----.--.-..----.---.-.-------------] Querying a Path You can use the CONSOLE QUERY to obtain information about a path and its associated device or to obtain information about a virtual device even if paths are not opened to it. To do this, you must also specify the BUFFER parameter. You can map the information returned by the CQYSECT macro. (See VM/SP Data Areas and Control Block Logic Volume 2 (CMS) for more information.) CQYSECT contains length equates that an application can use to obtain the size buffer needed. Initially, when an application opens a path, it can specify a buffer that contains path and device information and is mapped by CQYSECT. This information is very useful at initialization time since it contains DIAGNOSE code X'24' information, and, depending on the device, it contains DIAGNOSE code X'8C' information. Then, the application can obtain the device type and characteristics and can use the appropriate routines to build data streams. Writing to and Reading from a Path The console facility keeps track of the application that owns the screen by keeping a field in the device entry (CDEV) for the address of the path entry that performed the last I/O operation. If one application currently owns the screen and another application wants to perform I/O, the second application must gain control of the screen by reformatting it with an erase/write (EW), an erase/write alternate (EWA), or, in some cases, a write structure field (WSF). Therefore, applications should begin I/O processing with one of these operations. Warning: Until all applications use the console facility instead of issuing a DIAGNOSE code X'58', there is a possibility of seeing data from two different applications mixed on the screen. An erase/write (EW) must be issued so that the current application can gain total ownership of the screen. If CP breaks in and writes a screen or if another application using the console facility writes a screen, the console facility can detect this situation and issues return code 32. If you get return code 32, issue an erase/write or an erase/write alternate. However, the console facility can not always detect who wrote to the screen when applications modify PSW s in low storage and issue their own DIAGNOSE X'58'. In this case, if you get mixed data on the screen, you will have to press the CLEAR key or issue a command that causes an erase/write. The VMFCLEAR command can be issued by an application before exiting their program to accomplish this. Another alternative for applications running in full-screen CMS would be to write an EXEC to issue a SET FULLSCREEN SUSPEND command, then invoke their full-screen program, and when processing completes they can resume fullscreen CMS by issuing SET FULLSCREEN RESUME. Most full-screen applications will wait for input and then read the data. To accomplish this, you can issue a CONSOLE READ with the WAIT option, o~ you can issue a CONSOLE WAIT followed by a CONSOLE READ. The Chapter 5. Developing Programs under CMS 91 []GtlG~(iJ)rr]DrUQJ rro~~~@~UuS (LBUUC)JG~1 C~~8 c _____________________________________ _ _______________________.--1 CONSOLE READ with the WAIT option has a performance advantage because it issues only one Supervisor Call (SVC) instead of two. If you receive a return code 1 on an I/O operation, you should issue an explicit WAIT. Do not specify a READ with the WAIT option. A disconnect is detected before any READ options are checked. When you specify a READ with the WAIT option, a WAIT is not issued and control is immediately returned to the application with return code 1. If an application performs linemode I/O or calls routines that perform linemode I/O, it should issue a CMS WAITT macro to coordinate linemode and full-screen I/O. This allows the I/O to complete before issuing any console full-screen operations. 1/0 Advantages Applications can become much less dependent on low-level device architecture by using the console facility. In the past, applications not only had to construct data streams, but they had to build the channel command word (CCW), determine the type of device (dialed or virtual console) and set up for DIAGNOSE code X'58' or 3270 SIO, and check the channel status word (CSW) to determine what action should be taken. In addition, the applications would have to change whenever new devices were introduced. With the console facility, the application only needs to: o build a data stream, o issue a CONSOLE call, and • check a return code. The CSW error checking and retrying of I/O is much more elaborate in the console facility than what many applications do today. This gives applications a better chance for completing a successful I/O options. Building Your Own CCW The CONSOLE EXCP parameter allows applications that still want to build their own CCWs to do so. However, no CCW error checking is performed so the CONSOLE module cannot determine the type of I/O requested and cannot coordinate the use of the screen as effectively as with the READ or WRITE functions. The EXCP parameter is not recommended for the virtual console since the application has to know the internal I/O processing performed in the CONSOLE module. However, if you use this function carefully, you can chain several CCWs. The first CCW in the string should be an EW, EWA, or WSF to reformat and to gain control of the screen. 92 VM/SP eMS for System Programming ,/ · -.- .__ . - -------_. ---_. __ .._.- _._._--_. __ .. _._-._ .. -_..... --- -~~::-] Completing an 1/0 Operation When the console facility returns control to the application after an I/O operation, the application can check the return code and continue processing. If more information is needed about the I/O just performed, a CONSOLE QUERY can be issued. The CONSOLE QUERY shows the CSW after I/O, the sense data (if any), the last CCW executed, and all the device information obtained by DIAGNOSE code X'24' and DIAGNOSE code X'8C'. Closing a Path Before exiting your program, paths that are no longer needed should be closed. Close processing releases storage for the path entry. If this was the only path opened to the associated device, the device entry storage is released as well. When releasing a device entry, a CP RESET command is only issued for dialed devices. The DISPW Macro Although the CONSOLE macro is the preferred interface for full-screen I/O, the DISPW macro may be used to generate a calling sequence for the CMS display terminal interface module, DMSGIO. DMSGIO creates a channel program and issues a DIAGNOSE code X'58' to display the data. DMSGIO is a TEXT file that must be loaded to use DISPW. The format of the CMS DISPW macro is: [ label] DISPW bufad [ ,LINE = {~ }][ ,BYTES ={;~;;} 1 [ ,ERASE = YES] [,CANCEL=YES] where: label is an optional macro statement label. bufad is the address of a buffer containing the data to be written to the display terminal. LINE= {~} is the number of the line, 0 to 23, on the display terminal that is to be written. Line number 0 is the default. Chapter 5. Developing Programs under CMS 93 [D)Gt7G;~(][~)O~u§~ [JL"(])[jr@~uuD L~ullCJ0[j' (~rJJ8 L=-:"~==-~_~=~_~=~:::' _________.__.____._ . "._._, __. _ ._, _._._ "_ , ._"" _ . __ ._._. __.===-.-__ ~._.,, BYTES = =====_==-_=~-=---==-=-_._._. _ ._._. ._. ____.] {nnnn} 1760 is the number of bytes (0 to 1760) to be written on the display terminal. 1760 bytes is the default. ERASE=YES specifies that the display screen is to be erased before the current data is written. The screen is erased regardless of the line or number of bytes to be displayed. Specifying ERASE = YES causes the screen to go into "MORE" status. CANCEL=YES causes the CANCEL operation to be performed. The output area is erased. Note: It is advisable for the user to save registers before issuing the DISPW macro and to restore them after the macro because the modules called by the DISPW macro do not save the user's registers. The DISPW macro saves and restores register 13. 94 VM/SP eMS for System Programming 1-------------------..---.---..--.-.----. -.- . -.. - - - -.--- -.- - . - - .- ---.-.-.-.---' .-.-. -.---.------.--.-----------------..----.------.--.---.- . --.--..-.-.-.- . -----..--------. --------..---.----- L (c:ln~ri'n~i (~, IU\p(~~irfri~1 ~(o\o,;(c(:, 1:'\i(oI2';~fii~~, IU~::-flii~1 (CllVil~ As you test and modify programs, you may want to keep backup copies of the source programs. Then you can always return to a certain level of a program in case you have an error. eMS provides several approaches to the problem of program backup. The method you choose depends on the complexity of your project, the changes you want to make, and the size of your programs. The simplest method is to make a copy of the current source file under a new name. You can do this using either the COPYFILE command or the editor. The UPDATE Philosophy While the procedures outlined above for modifying programs are suitable for many applications, they may not be adequate in a situation where several programmers are applying changes to the same source code. These procedures also have the drawback of not providing you with a record of what has been changed. After using the editor, you do not have a recordof the lines that have been deleted, added, replaced, and so on, unless you manually add comments to the code, insert special characters in the serialization column, or use some technique that records program activity. The UPDATE command and the XEDIT UPDATE option provide a way for you to modify a source program without affecting the original. UPDATE produces an update log, indicating the changes that have been made. Both UPDATE and XEDIT have the capability of combining multiple updates at one time, so that changes made by different programmers or changes made at different times can be combined into a single output file. The UPDATE command and the XEDIT UPDATE option are the basic elements of the VM/SP updating scheme. Although the input filetypes used by the UPDATE command default to ASSEMBLE file characteristics, neither the UPDATE command nor the XEDIT UPDATE option is limited to assembler language programs. Also, is it not limited to system programming applications. You can use it to modify and update any fixed-length, 80-character file that does not have data in columns 73 through 80. Chapter 6. Updating Source Programs Using CMS 95 L ._......_. ____.____..__ ._._____.. ___.._..__ .___ . ____ .... _._..___ ._._ . ....___. _._. ___ ._._. _. . _. _____ .__.___., ______._,__ :~==_:_..::.=_~_=:... ________. ___________.____ ., .._, ____.__ . ___._________.__ .___1 Update Files A simple update involves two input files: o The source file, which is the program you want to update o An update file, usually created by XEDIT, containing control statements describing the changes you want to make. The control statement file usually has a filetype of UPDATE. For convenience, you can give it the same filename as your source file. For example, if you want to update the file SAMPLE ASSEMBLE, you would create a file named SAMPLE UPDATE using the XEDIT UPDATE option. To apply the changes in the update file, you issue the command: update sample The default values used by the UPDATE command are filetypes of ASSEMBLE and UPDATE for the source and update files, respectively. If you are updating a COBOL source program named READY COBOL with an update file named READY UPDATE, you would issue the command: update ready cobol a ready update a After an UPDATE command completes processing, the input files are not changed; two new files are created. One of them contains the updated source file, with a filename that is the same as the original source file but preceded by a dollar sign ($). Another file, containing a record of updates is also created; it has a filename that is the same as the source file and a filetype of UPDLOG. For example: Source Files Output Files SAMPLE ASSEMBLE $SAMPLE ASSEMBLE SAMPLE UPDATE SAMPLE UPDLOG READY COBOL $READY COBOL READY UPDATE READY UPDLOG Now, you can assemble or compile the new source file created by the UPDATE command. Creating an Update File You can create an update file using the XEDIT UPDATE option. Using XEDIT, you do not need to enter the control statements in the UPDATE file. They are generated automatically by the editor. For example: xedit ready cobol a (upd 96 VM/SP eMS for System Programming -.. _--- --'--' ._- --.. -.-.-.. r------- UJ[Jc]c:.1'~au·uo 8oQJuy~e [)u'OOG'C1uuuS -- _._- ---.- ---------~:==--.--- --:-=-~~:::-.::::~-==:-------------=-=-~::::~=:.==] specifies that a file called READY COBOL is to be edited and all updates to the file are placed in a separate file called READY UPDATE along with the appropriate control statements. The XEDIT UPDATE option expects source files to have sequence numbers in columns 73 through 80. Before you can create an UPDATE file you must use the XEDIT SERIAL subcommand to sequence your files. To generate these sequence numbers, you should issue: serial all prior to issuing a FILE or SAVE subcommand when you are editing a file. Alternately, you can preface sequence numbers with a three character identifier, usually the first three characters of the filename. If you issue: serial on XEDIT writes sequence numbers in columns 76 through 80 of your file. Columns 73 through 75 contain the first three characters of the filename. If SERIAL ON is specified, you must also specify the NOSEQ8 option on the XEDIT command to tell the editor to expect a sequence of numbers only in columns 75 through 80. For example: xedit ready cobol a (upd noseq8 Using an Existing Update File If an update file already exists for a given source file and you wish to either: 1. browse the source file with the updates applied or 2. continue updating the source file issue the same XEDIT command that you entered when you created the update file. For example: xedit ready cobol a (upd applies all updates contained in READY UPDATE to the source file READY COBOL and displays the resulting file on the screen. Any updates created during this editing session are added to those already contained in READY UPDATE. Again, all control statements are automatically generated by XEDIT. More information about the XEDIT UPDATE option can be found in the VM/SP CMS Command Reference. UPDATE Control Statements The control statements used by the UPDATE command are similar to those used by the as IEBUPDTE utility program or the DOS MAINT program UPDATE function. Each UPDATE statement must have the characters ./ in columns one and two, followed by one or more blanks. The statements are described below. Chapter 6. Updating Source Programs Using eMS 97 .-.....___ . ___ . _._._.........._.._........ _..._.._._.. _.___.________:J SEQUENCE Statement: This statement tells the UPDATE command you want to number or renumber the records in a file. Sequence numbers are written in columns 73 through 80. For example, the statement: ./ S 1000 indicates that you want sequence numbering to be done in increments of 1000 with the first statement numbered 1000. The SEQUENCE statement is convenient if you want to apply updates to a file that does not already have sequence numbers. In this case, you may want to use the REP (replace) option of the UPDATE command, so that instead of creating a new file ($filename), the original source file is replaced: update sample (rep INSERT Statement: This statement precedes new records that you want to add to a source file. The INSERT statement tells the UPDATE command where to add the new records. For example, the lines: ./ I 1600 TEST2 TM BNO HOLIDAY,X'02' VACATION HOLIDAY? NOPE VACATION 0 0 0 insert two lines of code, following the statement numbered 00001600, into the output file. The inserted lines are flagged with asterisks in columns 73 through 80. The INSERT statement also allows you to request that new statements be sequenced. See "Sequencing Output Records" on page 99. DELETE Statement: This statement tells the UPDATE command which records to delete from the source file. If your update file contains: 0/ D 2500 then only the record 00002500 is deleted. If the file contains 0/ D 2500 2800 then all the statements from 2500 through 2800 are deleted from the source file. REPLACE Statement: The REPLACE statement replaces one or more records in the source file. It precedes the new records you want to add. It is a combination of the DELETE and INSERT statements. For example, the lines 0/ R 38000 38500 PLIST DS OD DC CL8'TYPE' DC CL8" DC CL8'FILE' DC CL8'A1' DC 8X'FF' replace the existing statements numbered 38000 through 38500 with the new lines of code. As with the INSERT statement, new lines are not automatically resequenced. 98 VM/SP eMS for System Programming /' COMMENT Statement: Use this statement when you want to place comments in the update log file. For example, the line: oj * Changes by John Jo Programmer is not processed by the UPDATE command when it creates the new source file, but it is written into the update log file. Sequencing Output Records The UPDATE command expects source files to have sequence numbers in columns 73 through 80. If you use the XEDIT subcommand SET SERIAL to sequence your files, the sequence numbers are usually written in columns 76 through 80; columns 73 through 75 contain a three-character identifier that is usually the first three characters of the filename. If you want an eight-character sequence number and you are editing the file, you must use the subcommand: serial all prior to issuing a FILE or SAVE subcommand. Or, you can create an UPDATE file with the single record: oj S and issue the UPDATE command to sequence the file. If you use the UPDATE command with a file that has been sequenced using the default values of XEDIT, you must use the NOSEQ8 option. Otherwise, the UPDATE command cannot process your input file. The command: update sample (noseq8 tells UPDATE to use only columns 76 through 80 when it looks for sequence numbers. Figure 12 shows the four files involved in a simple update. Chapter 6. Updating Source Programs Using CMS 99 L_ ... _. ______ ._._______ .__. __ ... __ .. ______ .... The Source File, SAMPLE ASSEMBLE SAMPLE CSECT 00000100 USING SAMPLE,R12 00000200 LR R12,R15 00000300 ST R14,SAVRET 00000400 LINEDIT TEXT='PLEASE ENTER YOUR NAME' 00000500 RDTERM NAME 00000600 LINEDIT TEXT='PLEASE ENTER YOUR AGE' 00000700 RDTERM AGE OOOOOSOO LINEDIT TEXT='HI, •••••••••• , YOU JUST TOLD HE YOU ARE ••••• ',x00000900 SUB=(CHARA,NAHE,CHARA,AGE),RENT=NO 00001000 L R14,SAVRET 00001100 BR R14 00001200 EJECT 00001300 NAME DC CL130" 00001400 DC CL 130' , AGE 00001500 SAVRET 00001600 DC F'O' REGEQU 00001700 ~_______________________________________________________________________________ EUD 00001800 - - - - J The Update File, SAMPLE UPDATE ./ * SAM00010 REVISION BY DLC ./ R 500 SA800020 SA800030 LINEDIT TEXT='HHAT"S YOUR NAHE?',DOT=NO . / p. 700 1000 S1M00040 xSAM00050 LINEDIT TEXT='HI, •••••••••• , ENTER THE DOCNAHE', 51M00060 SUB= (CHARA, NAME) 51M00070 RDTERH nAME 5AM00080 HVC DOCFN,NAHE 51M00090 LA 1,PLIST 5AM00100 SVC 202 5A"00110 DC AL4 (ERROR) 5AM00120 RETURN EQU * 51M00130 . / I 1200 51800140 ERROR EQU * 5AM00150 WRTERH 'FILE NOT FOUND' 51M00160 B RETURN 5A800170 ./ D 1500 5A800180 . / I 1600 5A"00190 PLIST DS OD 5A800200 DC eL8'TYPE' CL8' , 51800210 DOCFll DC SAM00220 CLS'FILE' DC 5A800230 DC CL8' Al ' 5A800240 - - - - J L-________________________________________________________________________________ DC 8X'FF' Figure 12 (Part 1 of 2). 100 Updating Source Files with the UPDATE Command VM/SP eMS for System Programming lLDr)JJlJ~U[(UCJ 8@GJu'c(;) ~)[j-'(fj)~[j'8uuuG c·-· .--.-...-..--.......----.. -.... ----...-----......-----.-.-.-.---.. ----.--.. --......--.--.-.. -.. --- ..-.--.. --.-------... --..----.. -.- ..-... --..--.--.---.---.---------.-------=:1 The Record of Updates Pile, SAMPLE UPDLOG -, UPDATING 'SAMPLE ASSEMBLE Al' WITH 'SAMPLE OPDATE OPDATE LOG -- PAGE Al' 11 . / • REVISION BY DLC 1 . / R 500 1 DELETING ••• LINEDIT TEXT='PLEASE ENTER YOUR NAME' 000005t) 01 INSERTING ••• LINEDIT TEXT='WHAT"S YOUR NAHE1',DOT=NO . / R 700 1000 DELETING ••• LINEDIT TEXT='PLEASE ENTER YOUR AGE' 000007001 RDTERM AGE 000008001 LINEDIT TEXT='BI, •••••••••• , YOO JUST TOLD HE YOO ARE ••••• ·,x00000900' SUB=(CHARA,NAHE,CBARA,AGE),RENT=NO 00001000, INSERTING ••• LINEDIT TEXT='BI, •••••••••• , ENTER THE DOCNAME', x········1 SOB= (CBAHA, NAME) RDTERM NAME HVC DOCPN,NAHE LA 1,PLIST SVC 202 DC AL4 (ERROR) EQO • RETORN • / I 1200 INSERTING... ERROR EQO • WRTERM 'PILE NOT POUND' B RETORN . / D 1500 DELETING... AGE 00001500, DC CL 130' • . / I 1600 INSERTING... PLIST DS OD DC CLa'TYPE' CLa' , DOCPN DC DC CLa'PILE' DC CLa'Al' ax'pp' DC ........,, ········1, ........ ........ , ········1, ........ ........ ,, ........ , ........ , .········1 .......,, , ........ , ........ ,, ........ ........ ,, ........ ........, The Opdated Output Pile, $SAHPLE ASSEMBLE SAMPLE RETORN ERROR NAHE SAVRET PLIST DOCPN CSECT USING SAMPLE,R12 LR R12,R15 ST R14,SAVRET LINEDIT TEXT='WHAT"S YOUR NAME1',DOT=NO RDTERH NAME LINEDIT TEXT='HI, •••••••••• , ENTER TH~ DOCNAME', SUB=(CHARA,NAME) RDTERM NAME MVC DOCPH,NAME LA 1,PLIST SVC 202 DC AL4(ERROR) EQU • L R14,SAVRET BR R14 EQU • WRTERM 'PILE NOT POUND' B RETURN EJECT DC CL130" DC plOt DS OD DC CLa'TYPE' DC CLa" DC CLa'PILE' DC CLa l Al' DC aXlpp' REGEQU END Figure 12 (Part 2 of 2). 000001001 00000200, 00000300, 00000400, ........, x········, ........ , ........ , ........ , ........ , ........ ,, ........ ........, ........ ,, ........ ........, ........ ,, ........ ........ ,, ........ ........, 00000600, 00001100, 00001200, 00001300, 00001400, 00001600, ········1 00001700, 00001800, , Updating Source Files with the UPDATE Command Chapter 6. Updating Source Programs Using CMS 101 (lJl [»vJClliD ~uQ1 S(Q)M ~~CG r ~"(Q)QJ ~1@Uu\)S L ...__._______. --_.:.._------_._ _._--_._--_._J The INSERT and REPLACE statements allow you to control the numbering increment of records that you add to a source file. Notice, in Figure 12 on page 100 that inserted records have the character string '********' in columns 73 through 80. If you want sequence numbers on the inserted records, you must do two things: 1. Include a dollar sign ($) on the INSERT or REPLACE statement, optionally followed by operands indicating how the records should be sequenced. 2. Use the INC option on the UPDATE command line. If you use the CTL option, you do not have to specify the INC option. The CTL option is described below, under "Multiple Updates." For example, to sequence the records added in Figure 12 on page 100 the control statements would appear as: .j .j .j .j R R I I 509 $ 700 1000 $ 1200 $ 1600 $ and you would issue the UPDATE command: update sample (inc The UPDATE command sequences inserted records by increments of 10. If you want to control the numbering (for example, inserting more than 9 statements between two existing statements), you can specify an alternate sequencing scheme: .j I 1800 $ 1805 5 Records introduced following this INSERT statement are numbered 00001805, 00001810, 00001815, and so on. (If the NOSEQ8 option is in effect, then the records would be xxx01805, xxx01810, and so on, where xxx is the three-character identifier used in columns 73 through 75.) Multiple Updates If you have several UPDATE files to apply to the same source, you may apply them in a series of UPDATE commands. For example, if you have updates named FICA UPDTUP1, FICA UPDTUP2, and FICA UPDTUP3 to apply to the source file FICA PLIOPT, you could do the following: 1. Update the source file with FICA UPDr;rUP1: update fica pliopt a fica updtup1 2. 102 Update the source file produced by the above command with the FICA UPDTUP2: VM/SP eMS for System Programming ,,.,,," lD~j(~E)'~auru~ S()~~uJC:3 ~-J[j~O~[/C1UlrilS [L--_.-_--_-_-_--_.-_.--_-_._.-.-_ ...._.-._ _-_-.. -....-- ----.----.---.. ----.-..... --. -..--. .... ......... ..-=~=-=~:=:.~~.::..=.:..~=-~::~.~.:::.::.:.:..::.-::..-=::.~.:..=.=-==-_==.:..~~.:...::.::::.::=:::--==.::~~=:J update $fica pliopt a fica updtup2 3. Update the new source file with FICA UPDTUP3: update $$fica pliopt a fica updtup3 This final UPDATE command produces the file $$$FICA PLIOPT, which is now the fully updated source file. This method is cumbersome, however, particularly if you have many updates to apply. They must be applied in a particular order. Therefore, the UPDATE command provides a multilevel update scheme, which you can use to apply many updates at one time, in a specified order. To apply multilevel updates, you must have a control file, which by convention has a filetype of CNTRL and a filename that is the same as the source input file. Therefore, to apply the three update files to FICA PLIOPT, you should create a file named FICA CNTRL. The Control File A control file is actually a list. It does not contain any actual update control statements (INSERT, DELETE, and so on), but rather it indicates what update files should be applied, and in what order. In the case of a multilevel update, all the update files must have the same filename as the source file. Therefore, only the file types need be specified in the control file to uniquely identify the update file. In fact, since all your update files specified in a control file must have filetypes beginning with the characters UPDT, you need only specify the unique part of the filetype. The control file for FICA PLIOPT, named FICA CNTRL, may typically look like the following: TEXT MACS PLILIB FICA3 UP3 FICA2 UP2 FICAI UPI The first non-commentary record in the control file must be a MACS record. The second field in this record must be "MACS", and it may be followed by up to 29 macro library names (subject to the character limit of the line). Every record in the control file must have an "update level identifier." In this example, the update level identifiers are TEXT on the MACS record, FICA1 for the UP1 record, and so on. The update level identifier may have a maximum of five characters. See the "The STK Option" on page 111 for more details about the "update level identifier." The UPDATE command only uses the MACS record and the update level identifier under special circumstances. These are described later under "The VMFASM EXEC Procedure" on page 109. For now, you only need to know that these things must be in a control file in order for the UPDATE command to execute properly. Then, to update FICA PLIOPT, issue the UPDATE command as follows: update fica pliopt (ctl Chapter 6. Updating Source Programs Using CMS 103 c=._______.____ .___._. ___. _. . ________ .__._________._. __.__ _______. ~ ._-_._-------------_._----J When you use the CTL option and you do not specify the name of a control file, the UPDATE command looks for a control file with the filetype of CNTRL and a filename the same as the source file. From the control file, it reads the filetypes of the updates to be applied. In this example, the UPDATE command searches for the file FICA UPDTUPl and if found, applies the updates; then UPDATE searches for FICA UPDTUP2, and applies those updates, if any. Last it searches for FICA UPDTUP3, and applies those updates. Notice that the updates are applied from the bottom of the control file, toward the top. This becomes important when an update is dependent on a previous update. For example, if you add some lines to a file in FICA UPDTUP1, then modify one of those lines in FICA UPDTUP2, it is important that UPDTUPl was applied first. Alternate Ways of Naming the Control Files The example above, showing FICA CNTRL and UPDTxxxx files, illustrates a naming scheme using the UPDATE command defaults. You can override the defaults for the control file's filename and filetype. For example, if you name a control file GROUPA CNTRL, you can specify the name of the control file on the UPDATE command line. Then to update FICA PLIOPT using the GROUPA CNTRL control file, issue the following UPDATE command: update fica pliopt a groupa cntrl (ctl AUX Files The two levels of update processing shown so far may be adequate for your applications. There is, however, an additional level or step in the update structure that the VM/SP procedures use and that you may want to use also. These techniques may be useful when you have more than one set of updates to apply to a source program. For example, you may have two groups of programmers who are working on different sets of changes for the same source file. Each group may create several update files and have a unique control file. When you combine these changes, you could create one control file or you can use what are known as auxiliary control files. The updating structure for auxiliary control files is based on conventions for assigning filenames and filetypes. If a control file contains an entry that begins with the characters "AUX", the UPDATE command assumes that the file "fn AUXnnnn" contains a list of filetypes, not UPDATE control statements. For example, if the file SAMPLE ASSEMBLE is being updated with a control file that contains the record: TESTl AUXLIST 104 VM/SP eMS for System Programming [!JJ~jiJcT~Uu'uU SOQj[j'CG fJ [j"QJO[jIE1ulfuG c=----.-----.-.. -.. ----.----.--.---..--... ---.. -.......----....-.---..-..--... -.. -.......-.. -. - ...-..... -..--.. --....--... :.:.: ........---.-.. --.-..--... ---.. -- ------... ------- .-_.. ----. -- ....... ----......._ . . -......--] Then SAMPLE AUXLIST does not contain UPDATE control statements. It contains entries indicating the {iletypes of the update files, all of which must have the same filename, SAMPLE. Let's expand the example to see how this structure works. We have the source file, SAMPLE ASSEMBLE. The file SAMPLE CNTRL contains the entries: TEXT MACS 3676 AUXLIST The file, SAMPLE AUXLIST may look like the following: TESTI FIXLOOP BYPASS The files: SAMPLE TESTI SAMPLE FIXLOOP SAMPLE BYPASS all contain UPDATE control statements (INSERT, DELETE, and so on) to be, applied to the file SAMPLE ASSEMBLE. As with control file processing, the updates are applied from the bottom of the AUX file, so the updates in SAMPLE BYPASS are applied first, then the updates in SAMPLE FIXLOOP are applied, and so on. For an illustration of a set of update files, see Figure 13 on page 106. Chapter 6. Updating Source Programs Using CMS 105 ___. _______._____===__________.__________.____. ___________.____.___.______________1 REPORT CNTRL TEXT UP2 LIST UP1 TEXT MACS UPDTPROC AUXLlST UPDTREP1 AUXFIX REPORT UPDTPROC REPORT UPDTREP1 LU ll .. . . /R .. . ./0 .. . REPORT AUXLlST REPORT AUXFIX W /I ••• ./0 .. . ./R .. . REPORT RTNB REPORT FIXIN LU ll ... . /R ... . /0... "W '" WII. . W/I ... REPORT FIXOUT ./R ..• ./0 ... update report assemble a (ctl) UPDATING 'REPORT ASSEMBLE A1' WITH 'REPORT RTNA A1'. UPDATING WITH 'REPORT RTNB A1'. UPDATING WITH 'REPORT UPDTREP1 A1'. UPDATING WITH 'REPORT FIXOUT A1'. UPDATING WITH 'REPORT FIXIN A1'. UPDATING WITH 'REPORT UPDTPROC A1'. R; Figure 13. An Update with a Control File 106 VM/SP eMS for System Programming REPORT RTNA . /R... ./R .. . ./0... ./0 .. . QJ~3[~ci~Ouu[J S~~(!Ju'cGe ~Ju~([)qjG'clrrtfMJ c=----.--.---.---..-----.-.--.. ---..-..-... ----.- . ---.-------------.-----.-.-....--.----.. .---.-------.. -.. --.... -.... _. _... n_._ ...___. ___. ____ . __.__.____ ] Since the updating scheme uses only filetypes to uniquely identify update files, it is possible to use the same control file to update different source input files. For example, issue the following command when using the control file REPORT CNTRL shown in Figure 13 on page 106: update fica pliopt a report cntrl (ctl The UPDATE command begins searching for updates to apply to FICA PLIOPT, based on the entries in REPORT CNTRL. It searches for FICA AUXFIX, which may contain entries pointing to update files; then it searches for FICA UPDTREPl, and so on. As long as all updates and auxiliary files associated with a source file have the same filename as the source file, the updates are uniquely identifiable. Therefore, the same control file can be used to update various source files. VMjSP takes advantage of this capability in its own updating procedures. By maintaining strict naming conventions, updates to various CP and CMS modules are easily controlled and identified. A control file may point to many AUX files in addition to many UPDT files. You can modify a control file when you want to control which updates are applied to a program. You may have several control files, and specify the name of the control file you want to use on the UPDATE command line. There is a lot of flexibility in the UPDATE command processing. You can implement procedures and conventions for your individual applications. Multiple Updates with XEDIT The XEDIT CTL option creates multiple updates to a source file. First, create a control file listing the updates to be applied to a source file. Initially, you might have only the MACS record and one UPDATE filetype specified. For example, you can create a file called FICA CNTRL that contains: TEXT MACS PLILIB FICAl UPDTUPl Next, specify the control file name that you have created after the XEDIT CTL option. For example: xedit fica pliopt (ctl fica The editor searches for an update file called FICA UPDTUPI and applies all updates contained in this file. If the update file does not exist, XEDIT creates a file called FICA UPDTUPI which will contain all changes made to the source file during the editing session in addition to the required control statements. If you wish to add another level of updates to your source file, insert a new update filetype in your control file after the MACS record, for example: TEXT MACS PLILIB FICA2 UPDTUP2 FICAl UPDTUPl Chapter 6. Updating Source Programs Using CMS 107 L _ _ _. __.___________ .__.____ ._.__.___._______.___ ._______.__._--_._._--J Then, XEDIT your source file again, specifying the CTL option, for example: xedit fica pliopt (ctl fica XEDIT applies all updates contained in FICA UPDTUPI to the source file FICA PLIOPT. After the resulting file is displayed, any additional updates and the necessary control statements are automatically inserted in another update file called FICA UPDTUP2, consistent with control file processing from the bottom up. Auxiliary control files can also be used with XEDIT. You can make your control file point to AUX files that contain the filetypes of the actual update files, or you can combine AUX files and update files in a single control file. XEDIT begins applying updates from the bqttom up in the control file and references the AUX files indicated. Any updates to the source file produced during the editing session are inserted in the topmost update filetype specified in either the control file or in the last AUX file encountered using the 'bottom up' processing rule. More information about the XEDIT CTL option can be found in the VM/SP System Product Editor Command and Macro Reference. Preferred Level Updating There may exist more than one version of an update, each applicable to different versions of the same module. For example, you may need one version of an update for an unmodified base source module and another version of that update if that module has been modified by a licensed program. The AUX file used to update a particular module must then be selected ,based on whether or not a licensed program modifies that module. The AUX files listing the updates applicable to modules modified by a / licensed program are called "preferred AUX files" because they must be used if they exist rather than the mutually exclusive updates applicable to unmodified modules. Using this preferred AUX file concept, every module in a component can be assembled using the one CNTRL file applicable to a user's configuration. A single AUX file entry in a CNTRL file can specify more than one filetype. The first filetype indicates a file that UPDATE uses only on one condition: the files that the second and subsequent filetypes indicate do not exist. If they do exist, this AUX file entry is ignored and no updating is done. The files that the second and subsequent filetypes indicate are preferred because UPDATE does not use the file that the first filetype indicates. Usually, the preferred files appear later in the CNTRL file in a format that causes them to be used for updating. UPDATE scans each CNTRL file entry until a preferred filetype is found, until there are no more filetypes on the entry, or until a comment is found. (A character string less than four or more than eight characters is assumed to be a comment.) 108 VM/SP eMS for Systein Programming [---------_._-- ._._. -.---_. __ . --'---'-.-.---------------.-.--.. ...._. . _._-_._. . _-_.__._-_. __.-=-.-._-----------_._._ . _.-, --------~-------=-.:::-----------------------_ The VMFASM EXEC Procedure If you are an assembler language programmer and you are using the UPDATE command to update source programs you may want to use the VMFASM EXEC procedure. VMFASM is a VM/SP update procedure. It invokes the UPDATE command and uses the ASSEMBLE command to assemble the updated source file. If you are not an assembler language programmer, you may wish to create an EXEC similar to VMFASM that calls one of the language compilers to compile an updated source file, instead of calling the assembler. When you use VMFASM, you specify the source filename, the filename of the control file, and optionally, parameters for the assembler. (The control file for VMFASM must have a filetype of CNTRL). For example, if you use the file GENERAL CNTRL to update SAMPLE ASSEMBLE, you enter the command line: vmfasm sample general The VMFASM EXEC uses the MACS card and the update level identifiers in the control file. It reads the MACS card to determine which macro libraries (MACLIBs) should be searched by the assembler. Then VMFASM issues the GLOBAL MACLIB command specifying the MACLIBs you name on the MACS card. VMFASM uses the update level identifier to name the output text file produced by the assembly. If the update level identifier of the most recent update file (the last one located and applied) is anything other than TEXT, the update level identifier is prefixed with the characters TXT to form the filetype. For example, if the file GENERAL CNTRL contains the records: TEXT MACS CMSLIB MYLIB OSMACRO UP2 FIX2 UPl FIXl TEXT AUXLIST and updates the file SAMPLE ASSEMBLE, then: o If the file SAMPLE UPDTFIX2 is found and the updates applied, VMFASM names the .output text deck SAMPLE TXTUP2. o If the file SAMPLE UPDTFIXI is found and the updates applied but no SAMPLE UPDTFIX2 is found, the text deck is named SAMPLE TXT UP 1. • If the file SAMPLE AUXLIST is found but no SAMPLE UPDTFIXI or SAMPLE UPDTFIX2 files are found, the text deck is named SAMPLE TEXT. 4» If no files are found, the update level identifier on the MACS card is used and the text deck is named SAMPLE TEXT. Chapter 6. Updating Source Programs Using CMS 109 ________ =oJ The new fn TEXT or fn TXTxxxxx resides on the A-disk. Because the UPDATE command works from the bottom of a control file toward the top, it is logical that the text filename be taken from the identifier of the last update applied. The VMFASM EXEC does not produce an updated source file, but leaves the original source intact. VMFASM produces two output files: • A printed output listing that shows update activity • The text file that contains the update log as well as the actual object code. If you use the CMS LOAD command to load a text file produced by VMFASM, records from the update log are flagged as invalid, but the LOAD operation is not impaired. Updating EXECs and Macros If you wish to use the update facility to track changes to EXECs or macros written for the System Product Interpreter, you need to use the EXECUPDT command. The EXECUPDT command applies updates to an EXEC source file (using the UPDATE command) and removes the sequence numbers from the updated file to produce an executable version of the file. Using EXECUPDT is very similar to using the VMFASM EXEC to apply updates to an assembler language source and to assemble it. Source files for the EXECUPDT command are fixed-length, 80-character files with sequence numbers just like those for assembler language or COBOL. The filetype of the EXEC source file has a '$' prefixed to the normal filetype. For example, SAMPLE $EXEC could be the source for an EXEC procedure and READY $XEDIT could be a source file for an XEDIT macro. Updates to the EXEC source are created using XEDIT in the same manner as updates to programs in other languages. To apply the updates to the source, use the EXECUPDT command. For a single level update, issue the command: execupdt sample exec Note that the '$' in the filetype is not included in the fiJetype specified on the EXECUPDT command. To do a multi-level update, you may use the CTL option of EXECUPDT. For example: execupdt sample exec (ctl general 110 VM/Sp· eMS for System Programming ___ r - - - - --------- ~-U----------h-----------U-------------] The STI( Option If you are interested in writing your own EXEC procedure to invoke the UPDATE command, you may wish to use the STK option. The STK (stack) option is valid only with the CTL option and is meaningful only when the UPDATE command is invoked within an EXEC procedure. When the STK option is specified, UPDATE stacks the following data lines in the console stack: first line: second line: * * update level identifier library list from MACS record The update level identifier is the identifier of the most recent update that was found and applied. For example, an EXEC 2 EXEC that invokes the UPDATE command and then the ASSEMBLE command may contain the lines: &TRACE ALL UPDATE &1 ASSEMBLE * &2 CNTRL * (STK CTL &READ VARS &STAR &TX &READ VARS &STAR &LIBl &LIB2 &LIB3 &LIB4 &LIB5 &LIB6 &LIB7 &LIB8 GLOBAL MACLIB &LIBl &LIB2 &LIB3 &LIB4 &LIB5 &LIB6 &LIB7 &LIB8 &IF &TX NE TEXT FILEDEF TEXT DISK &1 TXT&TX Al ASSEMBLE &1 &3 &4 &5 &6 &7 &8 &9 &10 ERASE $&1 ASSEMBLE Below is a System Product Interpreter program that invokes the UPDATE command and then the ASSEMBLE command: /* Sample System Product Interpreter program to */ /* Update and Assemble a source program */ trace a parse arg filename cntrlfile options 'UPDATE' filename 'ASSEMBLE *' cntrlfile 'cntrl * (STK CTL' parse pull star tx parse pull star libl lib2 lib3 lib4 lib5 lib6 lib7 lib8 'GLOBAL MACLIB' libl lib2 lib3 lib4 lib5 lib6 lib7 lib8 if tx ,= TEXT then 'FILEDEF TEXT DISK' filename 'TXT'tx 'Al' 'ASSEMBLE $'filename options 'ERASE $'filename 'ASSEMBLE' If the EXEC that you use is named UPASM EXEC, it is invoked with the line: upasm fica fica (print noxref and the file FICA CNTRL contains: MAC MACS CMSLIB OSMACRO MYTEST FIXl UPDTFIX LIST AUXLIST Chapter 6. Updating Source Programs Using CMS 111 ~----------------------------------------------------------------------------~ then the EXEC 2 EXEC executes the following commands: UPDATE FICA ASSEMBLE * FICA CNTRL * (STK CTL GLOBAL MACLIB CMSLIB OSMACRO MYTEST FILEDEF TEXT DISK FICA TXTFIXl Al ASSEMBLE $FICA (PRINT NOXREF ERASE $FICA ASSEMBLE The System Product Interpreter program executes the following: /* Update FICA ASSEMBLE using FICA CNTRL */ 'UPDATE FICA ASSEMBLE * FICA CNTRL * (STK CTL' 'GLOBAL MACLIB CMSLIB OSMACRO MYTEST' 'FILEDEF TEXT DISK FICA TXTFIXl Al' 'ASSEMBLE $FICA (PRINT NOXREF' 'ERASE $FICA ASSEMBLE' The above examples assume that the update file FICA UPDTFIX was found and applied. 112 VM/SP eMS for System Programming ,-- ----._--------------•. _---._- • Using the Parsing Facility The CMS parsing facility parses and translates command arguments. Your programs can use the parsing facility to see if the user specifies the proper arguments on invocation and to see what the arguments are. For a list of CMS commands that use the parsing facility, see "Supported CMS Commands" on page 116. Advantages of the Parsing Facility When you use the parsing facility, programming commands is simpler because: o The parsing facility detects invalid command arguments. o All keyword abbreviations are expanded for you. o Command syntax is defined separately from your program and can be translated into different national languages. o When a national language is in use, keywords in that language are translated into the language recognized by your program. o You do not have to write scanning code. o The address and length of each token is provided. o Validation codes are provided to identify the type of each token. Advantages of DLCS To use the parsing facility, you must define command syntax in a special language, the definition language for command syntax (DLCS). Keep the DLCS definitions in CMS files. A file can contain more than one DLCS definition. The parsing facility parses a specified command by checking whether all operands, options, keywords, and so on, are specified according to the DLCS definition for that command. Chapter 7. Developing Commands and Message' Files 113 Defining command syntax in a DLCS file and using the parsing facility has the following advantages: • Syntax checking is unnecessary in your program. o If you want to invoke your program in another national language, you just have to modify your DLCS file. Refer to "Coding Your Own Command Syntax with DLCS" on page 117 for details on using DLCS. Overview To have the parsing facility do this checking, do the following: 1. Write DLCS statements. 2. Check for any DLCS coding errors using the CHECK option of the CONVERT COMMANDS command. 3. Issue the CONVERT COMMANDS command to put your syntax file into a machine readable form the parsing facility can use. 4. Issue the SET LANGUAGE command to enable the user's DLCS definitions. 5. Issue the P ARSECMD command from a REXX program or EXEC 2 EXEC or the P ARSECMD macro from an assembler program to invoke the parsing facility and to obtain the parsed and translated parameter lists. Coding DLCS Statements To show how DLCS statements work, here is a standard CMS command string format: command_name [operands ... ] [(options ... ] DLCS has the following statements: :CMD :OPR :OPT for a command name for an operand for an option A few other statements you can use in DLCS include: :SYN :KW.n :* to define synonyms for command name modifiers to specify comments For example, the RDRLIST command has the following format: RDRLIST [( [PROFile fn] 114 VM/SP eMS for System Programming [Append] [)]] --.----- =:J Here is how the syntax for RDRLIST is coded in DLCS: :CMD D9K.RDRLIST RDRLIST RDRLIST 4 :SYN RLIST 2 : i :OPT KWL( ) FCN(FN) :OPT KWL( ) : i .f :i The section, "Coding Your Own Command Syntax with DLCS" on page 117, describes DLCS statements in detail. Converting Your DLCS File When you are ready to use the DLCS file, you first have to convert the DLCS file into an machine readable form the parsing facility can use. Use the CONVERT COMMANDS command to do this. You can use the CHECK option of CONVERT COMMANDS to make sure your DLCS syntax descriptions are correct. In addition, you can issue CONVERT COMMANDS with the CHECK option while you XEDIT the DLCS file to help remove errors. Next, use the SET LANGUAGE command to put the new DLCS definitions into effect. Refer to the VM/SP CMS Command Reference for a complete description of CONVERT COMMANDS and SET LANGUAGE. Setting Command Name Synonyms and Translations Use the SET TRANSLATE command to set user translation synonyms, user translations, system translation synonyms, and system translations on or off. Use the QUERY TRANSLATE command to display the contents of the system synonym tables, system translate tables, user synonym tables, and user translate tables. These commands work similarly to the CMS SYNONYM and QUERY SYNONYM commands. (Refer to the VM/ SP CMS Command Reference for descriptions of SET TRANSLATE, QUERY TRANSLATE, SYNONYM, and QUERY SYNONYM.) Invoicing the Parsing Facility You can invoke the parsing facility in two ways: 1. From EXEC 2 EXECs or REXX programs, use the P ARSECMD command. The P ARSECMD command uses the EXECCOMM interface and creates EXEC variables that describe the translated command string. See Figure 14 on page 135 for an example using the PARSECMD command. Refer to the VM/ SP CMS Command Reference for a description of the PARSECMD command. Chapter 7. Developing Commands and Message Files 115 2. From assembler programs, use the P ARSECMD macro. The P ARSECMD macro call should be in the beginning of the program. Upon return from the parsing facility, the syntax of the command is verified and detailed information on the translated command string is available. See Figure 16 on page 138 for an example using the P ARSECMD macro. Refer to the VM/ SP eMS Macros and Functions Reference for a description 6f the P ARSECMD macro. Command keywords are uppercased according to the national language uppercase table for the active application. If one is not found, the CMS national language table is used. o Supported CMS Commands The following commands use the parsing facility: ACCESS ALARM CLEAR COMPARE CONVERT COPYFILE CURSOR DEFAULTS DEFINE DELETE DISK DROP ERASE EXECDROP EXECLOAD EXECMAP EXECSTAT3 FILELIST FORMAT GENMSG I I I' I I I I I I I I I I I I I I I I I GET HELP HELPCONV3 HIDE IDENTIFY LANGGEN LANGMERG LIST FILE MACLIST MAXIMIZE MINIMIZE MODMAP MOREHELP NAMES NOTE NUCXDROP NUCXLOAD NUCXMAP PARSECMD PEEK POP POSITION PRINT PUNCH PUT QUERY RDR RDRLIST READ CARD RECEIVE REFRESH RELEASE RENAME RESERVE RESTORE ROUTE SCROLL SENDFILE SET SHOW SIZE SORT STATE SVCTRACE SYNONYM TAPE TELL TXTLIB TYPE UPDATE WAITREAD WAITT WRITE XEDIT4 XMITMSG These commands do not have parameters requiring translation, but the command name itself can be translated. 4 116 XEDIT subcommands are not supported. VM/SP eMS for System Programming [0)'3'Ue~8~)aOuO ~~~IDuuuu-Jll8uJt:JG 80~~J ~YJC::GD(](JC0L) [--------_._- - - --------------------------------------------=~====--=~..:..-----------=--=~-=--=~~=-=--=-..:==.:=-=-~=-~~=-=~=~~] Coding Your Own Command SyntaJc with DLCS Rules to Remember Some rules to remember while coding in DLCS are: o Use special characters: < > and' in your data tokens (keyword names, function names, or function values) only if they are enclosed in single quotes. The quotes are not counted as part of the token. o Do not use lowercase characters to specify your keyword names, function names, or function values. Specify these exactly as they appear after the command line is uppercased by the system at execution time with the language in effect. o Only the first 72 characters of any line of the DLCS file are used. Any characters beyond 72 are ignored. You can use as many blanks as you want between tokens, and you can continue DLCS statements on the following line. o Only one system and one user DLCS file for an application can be made active at any time. When both a user file and a system file are active, the definitions in the user file override the definitions in the system file. If no syntax definition is found in the user file, the definition in the system file is used. o Your DLCS file must be merged with your user file for the application you currently have. You can have only one user table; therefore, if you have another command or receive a command from someone, you have to merge it with the other commands in the user table. (For example, if you want the CMS search order to find your command, define the command in a DMS file.) o You can define the translation of some keywords to be the same as the keyword the command recognizes. For more information on translation, see the VM/ SP eMS User's Guide. Defining Your Command Define each command as follows: 1. Start with a CMD statement to specify the name of the command and its national language equivalent. 2. Define any synonyms using SYN statements immediately following the CMD statement. 3. Define a two word command using the first word as the command name and using the KW.l statement to define the second word. If the command is a three word command, use the KW.2 statement to define the third word. (The second and third words are command name Chapter 7. Developing Commands and Message Files 117 modifiers.) You can also have a four word command, a five word command, etc. 4. Define the syntax for the command with zero or more OPR statements followed by zero or more OPT statements. 5. Use ':;' to specify the end of a statement. SPECIFYING THE APPLICATION AND NATIONAL LANGUAGE DLCS Statement: Use the DLCS statement to define the application where commands in the DLCS file are parsed, to specify whether the commands are system or user commands, and to specify the national language for the file. The format of the DLCS statement is: :DLCS applid System IUser langid ..., where: applid is an application identifier. It must be three alphanumeric characters, and the first character must be alphabetic (e.g., DMS, DMK, OFS, AGW, DKK, etc ... ). SystemlUser specifies whether the file contains system or user syntax definition statements. (Only the first letter is significant.) langid is the identifier for the language you are working in. It must be one to five alphanumeric characters (e.g., FRNCH, AMENG, etc ... ). Notes: 1. The DLCS statement must be the first non-comment statement in the DLCS file, and it must be the only DLCS statement in the file. 2. The CMS command search order uses translations and translation synonyms defined in DLCS files with an application identifier of DMS. 3. The DLCS statement determines the filename and filetype of the output files. DEFINING THE COMMAND NAME, SYNONYMS, AND MODIFIERS 118 VM/SP eMS for System Programming CMD Statement: Use the CMD statement to define the name of a command as the system sees it and as the language sees it. The format of the CMD statement is: :CMD unique-id sl-name [nl-name n ] :; where: I I I I l unique-id identifies the syntax definition for the command within the DLCS file. This is required, and it must be unique for each syntax definition. When you invoke the parsing facility, unique-id is matched to the one you specify in the P ARSECMD. unique-id is any combination of up to 16 characters. For quick access to the syntax definitions, the first one or two characters are used as an index. If the first two characters of unique-id are valid hexadecimal digits, their value is used as the index. Otherwise, the EBCDIC value of the first character is used. For example, unique-ids D9xxx and Rxxx both have the same index value of 217. CMS can find syntax definitions faster if you use as many of the 256 index values as possible. sl-name is the command name as CMS sees it. nl-name is the command name as a national language user sees it. Defaults to s1-name. n is the minimum number of characters that must be entered for nl-name to be accepted. Defaults to the length of sl-name. Notes: 1. A new command syntax begins each time a CMD statement is encountered .. 2. All uniqueids used for IBM commands have a period as the fourth character. Do not use a period as the fourth character in the the uniqueid for your own commands. 3. A uniqueid of all blanks is reserved to let you define more than one translation for a command. When this uniqueid is found, no syntax information is stored. You can only code the :CMD and :SYN statements in this case. Chapter 7. Developing Commands and Message Files 119 4. The minimum length for abbreviations of command name translations cannot be more than eight or HELP does not recognize them. 5. nl-name is only used by the CMS search order if the application identifier of this DLCS file is DMS. 6. The SET TRANSLATE command enables or disables nl-name. 7. If SET ABBREV OFF is in effect, you must use the full nl-name. SYN Statement: Use the SYN statement to define translation synonyms for the command name defined on the :CMD statement. The format of the SYN statement is: :SYN newnamel nl [newname2 n2 ] :; where: newname is the synonym you are assigning to the command name. n is the minimum number of characters you must enter for the synonym to be accepted by CMS. Notes: 120 1. The SYN statement is valid only for the first word of a command name (not the command name modifiers). 2. All of the SYN statements for a command must immediately follow the CMD statement. 3. Only SYN statements defined in a DLCS file with an application identifier of DMS are used by the CMS command search order. 4. The SET TRANSLATE command enables and disables translation synonyms defined by the :SYN statement. 5. Using multiple names on a single SYN statement has the same effect as specifying a single name on many SYN statements. Order is not important. 6. If SET ABBREV OFF is in effect, you must use the full newnamel. VMjSP eMS for System Programming KW.n Statement: Use the KW.n statement to define command name modifiers keywords that modify the syntax used for parsing the remaining parameters. For example, a command to manipulate a simple data base can require different operands-- a filename for an open request, an option for a close request, and other operands for update requests. The KW.n statement lets you define a different syntax for each. The format of the KW.n statement is: :KW.n sl-name sl-abbrev [nl-name nl-abbrevJ ., where: n is the number of the level. It defines the nth modifier after the command name. sl-name is the name as the command sees it. sl-abbrev is the minimum number of characters that must be entered for sl-name to be accepted by CMS. nl-name is the name as the national language user enters it. Defaults to sl-name. nl-abbrev is the minimum number of characters that must be entered for nl-name to be accepted by CMS. Defaults to sl-abbrev. Use the following form of the :KW.n statement to indicate that a string of characters not defined by any :KW.n statement is accepted as an arbitrary modifier. :KW.n ., Note: This form may not be used as the first :KW.n statement on a level, and only applies to :KW.n statements on the same level. No further syntax information may follow this statement, that is, no :OPR, :OPT, or :KW.n statements with a larger value for n. When the parsing facility finds an arbitrary modifier it will process that remainder of the argument string as one text string. Chapter 7. Developing Commands and Message Files 121 ( ------Example: Suppose the format of a database command is: DATABASE OPEN UPDATE UPDATE CLOSE filename ROW row number COLUMN column-name [(REPLACE [)]] When the DLCS for t,his command is coded, instead of defining OPEN, UPDATE, and CLOSE as operand keywords, they are coded as modifiers (because they modify the syntax) using the KW.n statement. Because each is the first modifier following the command name, the modifier level (the n part of KW.n) is 1. In this way, you can define a command with many modifiers at the same level. You can define the remaining operands and options differently for OPEN, UPDATE, and CLOSE. The DLCS definition so far is: :CMD DATABASE DATABASE ., : KW . 1 OPEN 4 :; : OPR FCN ( FN) :; :KW.1 UPDATE :; :KW.1 CLOSE 5 :; :OPT KWL«REPLACE 3» :; The keywords ROWand COLUMN can only follow UPDATE, and they modify the syntax further. Each is the second modifier after the command name, so they are coded as a second level modifier following UPDATE. Each KW.2 statement on this second level may be followed by either a third level or operand and option definitions, and so on. These KW.2 statements nest after the previous KW.l statement so that ROW or COLUMN are only recognized after UPDATE. The complete DLCS definition for the database command is: :CMD DATABASE DATABASE., :* A sample syntax :KW.1 OPEN 4 :; :OPR FCN(FN):; :* filename :KW.1 UPDATE :; : KW . 2 ROW 3 :; :OPR FCN(PINTEGER)., :* row-number :KW.2 COLUMN 3 :; :OPR FCN(STRING):; :* column-name :KW.1 CLOSE 5 :; :OPT KWL«REPLACE 3» :; DEFINING OPERANDS OPR Statement: Use the OPR statement to define the syntax of each operand of the command. The format of the OPR statement is: 122 VM/SP eMS for System Programming :OPR KWL( kwdef1 [kwdef2 ... ] ) [ OPTIONAL I STOP] :OPR FCN( fcndef1 [fcndef2 ... ] FCN( [kwdef2 fcndef1 ... ] ..., [ REPEAT] ., ) [ OPTIONAL I STOP] :OPR KWL( kwdef1 [ REPEAT] ) [fcndef2 [ OPTIONAL I STOP] ... ] ) [REPEAT] ., where: KWL defines the keyword when an operand (or option when defining an option) is defined to be a keyword. FCN defines functions to be used to validate the value of an operand. KWLFCN defines a keyword-value pair using the kwdef and fcndef expressions. The kwdef and fcndef expressions are defined on pages 124 and 125. OPTIONAL indicates the operand can optionally be specified. STOP specifies that if the operand is not specified then parsing of the operands stops at that point and no more operands can be specified. REPEAT indicates the operand can be specified one or more times. Notes: 1. Specify aPR statements in the order the operands are specified on the command. 2. Specify the aPR statement after the CMD statement and present SYN statements or after appropriate KW.n statements. 3. If both OPTIONAL (or STOP) and REPEAT are specified, the operand can be specified zero or more times. Chapter 7. Developing Commands and Message Files 123 D)Gt7G~Q)~J)DuuQJ CC})uu'iluuuE.lliu0]S @Eu(;] Me9D@gC:;9 c::--_~ __ -- 4. ---.---.--.-.-----.---------~ If no options are specified, the operand is a required operand that can be specified only once. DEFINING OPTIONS OPT Statement: Use the OPT statement to define the syntax of the options for the command. The format of the OPT statement is: J) :OPT KWL( kwdefl [ kwdef2 ... :OPT KWL( kwdefl [ kwdef2 ... ] ) FCN ( fcndefl :; [fcndef2 ••• ] ) ., where: KWL defines the keyword when an option (or operand when defining an operand) is defined to be a keyword. KWLFCN defines a keyword-value pair using the kwdef and fcndef expressions. The kwdef and fcndef expressions are defined below. Note: OPT statements must follow the last aPR statement, if any were used, for that command. Order of the OPT statements is not important. ,/ kwdef EXPRESSION The format of kwdef is: [ < sl-name sl-abbrev [nl-name nl-abbrevJ > where: sl-name is the keyword known by your command. 124 VM/SP eMS for System Programming ] _..... _._._ .... ----_ .. _-_ ....-_.--_._-------_ .. _--------_._--------_.. [" _ ..-._-_._----_._--_.__.--_._] sl-abbrev is the minimum number of characters that must be entered for sl-name to be accepted. nl-name is the keyword known by a national language user. Defaults to sl-name. nl-abbrev is the minimum number of characters that must be entered for nl-name to be accepted. Defaults to sl-abbrev. fcndef EXPRESSION fcndef can be anyone of the system functions listed below. In addition, fcndef can be a user function. See "User Functions" on page 127 for more information. System Functions Syntax Description ALPHANUM any alphanumeric string APPLID any three character alphanumeric string with the first alphabetic CHAR any single nonblank character CUU any hex number between 001 and FFF (assumes leading zeros) DIGITS any unsigned number made up of digits 0-9 FN (filename) any string with the following characters: A-Z,a-z,0-9,$,#,@, + ,-,:, and _ FT (filetype) any string with the following characters: A-Z,a-z,0-9,$,#,@, + ,-,:, and _ FM (filemode) first character: A-Z, a-z; optional second character: 0-6 EFN same as FN with ,*, or '%' also a valid character EFT same as FT with ,*, or '%' also a valid character EXECNAME any string that d'oes not contain the following characters: = ,*,(,),' " and X'FF' Chapter 7. Developing Commands and Message Files 125 EXECTYPE any string that does not contain the following characters: = ,* ,(,),' " and X'FF' HEX any hexadecimal number INTEGER any decimal whole number (can have NINTEGER any decimal negative whole number PINTEGER any decimal positive whole number (can have + sign) MODE any alphabetic character STRING any nonblank character string TEXT any character string INVALID no valid values + or - signs) Notes: I- 1. You can specify function definitions with a subset of valid values. Only items in the subset are valid. For example, if you specify STRING(MONDAY, TUESDAY, WEDNESDAY), MONDAY, TUESDA Y, and WEDNESDA Yare the only valid values. 2. If a list of functions is specified for fendef, the parsing facility validates an operand or option value with the functions in the order they are specified. The first function the value is valid for determines the validation code of the value in PVCENTRY. Refer to the VM/SP CMS Macros and Functions Reference for more information on the PVCENTRY macro. 3. Input to the parsing facility is uppercased according to current language before it is provided to system or use'7- functions for validation. 4. If a value is not valid according to any of the functions in the list, the first one is used to determine which message, if any, is issued. If an error message based on the first function is not appropriate, place the INVALID function first in the list. For example: I I I :OPR FCN(INVALID, INTEGER(2,4,6), MODE) :i The invalid function never accepts a value as valid, but a general error message is issued when a value is not valid according to the rest of the functions in the list. 5. Because some functions will validate tokens that are also valid for other functions, you should be careful to list the most restrictive functions first. For example, an operand defined as: :OPR FCN(STRING, DIGITS, FN):i 126 VM/SP eMS for System Programming c-·-·····--- ----.--... --- ....-.-.-.... -- . ---.. ---. .. -...--_. -.-.......... -.-....-.-.. --.....----.--- -.--_. ---..----.....-..----.----.. ---.-----------.--.. -.-..--.-.. -..--.- . ---.-. -.-.---.. . -] will always be validated as a string, while the syntax: :OPR FCN(FN) REPEAT:; :OPR FCN(DIGITS):; can never be satisfied because the required digits operand will be validated as part of the list of filenames. 6. The TEXT function cannot be specified in a list with any other function. User Functions In addition to the system functions listed above, you can also make your own functions for the parser to use to check if a token is valid. For instance, you could make a function VOWEL that considers only alphabetic characters A,E,I,O and U valid. After you make your program for your function, assemble it, load it with the RLDSA VE option, and use the GENMOD command. Then install the MODULE file of this assembled program as a nucleus extension. Next, include the name of your function in the DLCS for your command exactly as you would any other function. The function is invoked by the parsing facility with an SVC 202. The entry point name of the module must be the same as the function name (fcndef) in your DLCS file. Your function is passed the following parameters: o An eight byte area containing the function name o token-addr: a fullword containing the address of the token to be validated. The token is already uppercased according to the current language. o token-length: a full word containing the number of characters in the token. o validation code: a byte containing the number interpreted by the parser as the validation code of the user function. If the token is valid, this field should be set by the user function. Upon return from the parsing facility, you can check this validation code to see if your token is valid. On entry to the program, Rl contains the address of the control block containing the parameters described above. Use the assembler macro P ARSERUF to generate a mapping of this control block. Your program must pass back a return code in R15 that determines the outcome of the function. A return code of zero specifies the token was valid; a non-zero return code specifies the token was not valid. You can use any non-zero return code except -3; this return code would be interpreted to mean the function did not exist.· Chapter 7. Developing Commands and Message Files 127 [J)GvGUO[J)Uuu[j COuliuuu'ilC}uu0JS C}uu0J ~JJG9888GS c:::: __________________.__ ._____._______________________ ~:=~_==_=_==_ _________ __. _. Notes: 1. User functions do not override system functions with the same name (system functions come first in the search order). 2. When you use CONVERT COMMANDS to process your DLCS file, specify the ALL or USER options for user functions to be accepted. 3. When coding user functions in your CDSL file, you can enclose specific values in parentheses as you can with any system functions and only those values are accepted. DEFINING ROUTINES AND KEYWORDS Note: The :RTN and :KWD statements are reserved for IBM use. You may not use them in writing your own commands in DLCS. They are only shown here so that if you need to make your own translation of eMS commands you can do so without introducing errors into the syntax or its definition. RTN Statements: Use the RTN statement to define the routine responsible for parsing the command. The format of the RTN statement is: :RTN routine-name ..., where: routine-name is a eMS defined name. Notes: I 1. When the :RTN and :KWD statements are used, they replace (and are nutually exclusive with) the :OPR and :OPT statements. There is one :RTN statement followed by any number of :KWD statements. 2. When you are translating a CMS command that uses routine parsing, you should only changed the nl-name and nl-abbr fields on the :KWD statement. You must not add or delete :KWD statements or change the routine and system language names. I' I 128 VM/SP eMS for System Programming ~J(:;UG~(G[)Uu'uCJ (GOu·u'uuullc)ullQ.JS c}u-ll(~] ~UJr3GS~]~]::)n ------ ----- -------- -----------_____ __ _. __.. L_::" _._~_~~~~:~~~~_~~~~~_-~-=:_=:.._...::===~-.-- --~:::...~__=:.::.:.:::.:_==_=~_=:=.::.::...~~ ~ :._.::._:~ _~--J KWD Statements: Use the KWD statement to define the keywords that the command contains for translation purposes. The format of the KWD statement is: :KWD sl-name sl-abbrev [nl-name nl-abbrev] ., where: sl-name is the CMS defined keyword name. sl-abbrev is the minimum number of characters that must be entered for sl-name to be accepted by CMS. nl-name is the keyword as a national language user enters it. nl-abbrev is the minimuni number of characters that must be entered for nl-name to be accepted by CMS. Notes: 1. When the :RTN and :KWD statements are used, they replace (and are nutually exclusive with) the :OPR and :OPT statements. There is one :RTN statement followed by any number of :KWD statements. 2. When you are translating a eMS command that uses routine parsing, you should only changed the nl-name and nl-abbr fields on the :KWD statement. You must not add or delete :KWD statements or change the routine and system language names. Writing Comments Comments: Use the characters :* to specify that a line or the remaining characters of a line are to be ignored. Use this to put comments and explanations in your DLCS file. The format of a comment is: [DLCS statements or parts of a statement] ...'t comment Chapter 7. Developing Commands and Message' Files 129 ............... _,...._.___ ._. __.~~_:::.:~_:=:J where: comment is any comment Creating a DLCS File For examples of creating a DLCS file, see "Creating a DLCS File" on page 131 and "Creating a DLCS File with National Language Translations" on page 132. What the Parser Does Not Flag 1. 2. The parser does not flag the following situations: o Dependent options and operands. The MAP operand of the MACLIB command gives an example. Refer to the VM/ SP eMS Command Reference. o Mutually exclusive options or operands. This is where you have a pair of operands or options. You must specify one or the other -you cannot specify neither or both. The ACK and NOACK operands of the NOTE command give an example. Refer to the VM/ SP CMS Command Reference. Most commands that have mutually exclusive options or operands ignore the condition and use the last operand or option you specify. Some IBM supplied commands also use the RTN and KWD statements for special purposes. Do not use these statements for your own commands. oecs and the Parsing Facility This section lists rules to remember when the current language is a double-byte character set (DBCS) language. In DLCS and CONVERT COMMANDS 130 o You can use DBCS characters only in keyword, modifier, and command names. o You can mix single byte and DBCS characters in a name in the DLCS, but CONVERT COMMANDS only recognizes single byte characters as DLCS delimiters. o Shift-out and shift-in characters are always recognized as DBCS delimiters in a DLCS definition regardless of the current language. o A double byte character is treated as a single logical character. When you specify the minimum length for abbreviations of synonyms or translations, count double byte characters and EBCDIC characters as single logical characters and ignore shift-out and shift-in characters. VM/SP eMS for System Programming [------------------------_.. _------_._----- For example, if you have the keyword 'abcd rru k1k2k3 mefg', setting the minimum abbreviation of four allows 'abcd' as the shortest abbreviation. Setting the minimum abbreviation of five, would allow 'abcd ~ k1m ' as the shortest abbreviation. Setting the minimum abbreviation of six allows 'abcdrru k1k2 as the shortest abbreviation, and so on. ill ' o If you use DBCS characters when adding translations and translation synonyms to a DLCS file, you can issue CONVERT COMMANDS and SET LANGUAGE on these translations. However, you can only use these commands if the language you are using is set up as a double-byte language. From CMS o DBCS or mixed DBCS command names and keywords are accepted. DBCS strings cannot be specified for operand and option values such as filename, filetype, filemode, cuu, and so on. o Each token in the tokenized PLIST is resolved to be a complete DBCS string. In other words, one of these tokens can contain no more than three double byte characters. o When you invoke CMS commands, you can use DBCS EBCDIC to specify CMS delimiters such as blanks or parentheses. Examples: Using the Parsing Facility Creating a DLCS File You have two commands, MYCMD1 and YOURCMD. MYCMD1 has the following syntax: MYCmdl fn ft [ ( [DlskIPRint] [NUMrecs nnn] [)] ] YOURCMD has the following syntax: YOURcmd string [ (TYPE [)] ] Instead of coding syntax checking into your program, you plan to invoke the parsing facility for these commands. So you have to create a DLCS file to contain both syntax definitions. You can create a CMS file called TEST DLCS to contain the statements for these commands that could look like this: Chapter 7. Developing Commands and Message 'Files 131 L_.____ . 1 2 3 4 5 6 7 8 9 10 11 12 :DLCS DMS USER AMENG : i :* The first command :CMD MMYCMD1 MYCMD1 MYCMD1 3 0' :SYN MY1 3 : i :OPR FCN(FN) : i : OPR FCN ( FT ) : i :OPT KWL«DISK 2> 0 I/O performed by AUXPROC routine with residual count in GPR15. DMSSEB returns normally. GPR15 = 65,536 I/O performed by AUXPROC routine with zero residual count. Chapter 8. Developing as Programs under CMS 167 _________._. _.___.__:::J L.:~ .... Passing Information to the DMSTVI Routine: An interface routine, DMSTVI, can be used to give control to a different multivolume switching routine than the one supplied with VM (DMSTVS) or a tape management system. Use the new SYSPARM option to pass information not included on the FILEDEF or LABELDEF command to the DMSTVI routine. When DMSTVI is called, the general-purpose registers contain the following information: GPR1 GPR 14 GPR 15 = Address of a parameter list defined by the TVISECT DSECT = Return address = Entry point address The calling routine saves and restores the register contents. When DMSTVI'gets control, it must check the call function keyword in the register 1 PLIST. The call function keyword identifies the function being processed when DMSTVI is called. DMSTVI should use the information in the PLIST to build a command or to invoke the tape volume switching routine or tape management system. When DMSTVI is called during FILEDEF processing, only the call function (SYSP ARM) and the SYSPARM string address and length field are filled in. The other fields are set to zeroes. Because DMSTVI gets control during OPEN macro processing before any I/O is done, you do not have to mount a tape before OPEN is issued. The interface routine can mount the tape before returning control to OPEN macro processing. If you specify only the first volid of a multivolume tape and the end of the first volume is reached, DMSTVI gets control with a call function of 'EOV' and a volid of SCRATC. The tape management system can mount the next volume if it knows what tape is currently mounted on the drive and the volid of the next volume in the series. A 44 character fileid can now be entered with the LABELDEF command. The 44 character fileid is passed to DMSTVI during OPEN, EOV, and CLOSE macro processing. DMSTVI should check the TVISCRAT field in the register 1 PLIST to determine if a tape was requested from the tape management system. DMSTVI checks the TVISCRAT field by giving a fileid. If the TVISCRAT field contains 'SCRATCH', a scratch tape was requested. If this field contains 'NOSCRATC', a scratch was not requested -- 'SCRATC' was put in TVIVOLID as a default. If a fileid is also specified (TVIFILID), a tape containing this fileid was requested. If you want to mount a tape by specifying just the fileid, you should not specify any volid on FILEDEF or LABELDEF (including 'SCRATCH'). 168 VM/SP eMS for System Programming ITJGnJ0)~(0[)Uu uU 08 [JutGJOu'c:lu'u'uG c-------.. . --...--. -.-.---------..----------.---.----..--------.-------..--...---.--.----.----.. ----.----.-----.--.--.-.. -.-.- . -.----------- ---.-_==-:::.::.:~ If no fileid is specified on the LABELDEF command, the TVIFID field in the register 1 PLIST contains all zeros. The system uses the ddname (TVIFILE) as the default. DMSTVI must return to the calling routine when processing is complete. Creating eMS Files from OS Data Sets If you have data sets on OS disks, on tapes, or on cards, you can copy them into CMS files so that you can edit, modify, or manipulate them with CMS commands. The CMS MOVEFILE command copies OS (or CMS) files from one device to another. You can move data sets from any valid input device to any valid output device. Before using the MOVEFILE command, you must define the input and output data sets or files and assign them ddnames using the FILEDEF command. If you use the ddnames INMOVE and OUTMOVE, then you do not need to specify the ddnames when you issue the MOVEFILE command. For example, the following sequence of commands copies a CMS disk file into your virtual card punch: filedef inmove disk diskin file al filedef outrnove punch rnovefile The result of these commands is effectively the same as if you had issued the command: punch diskin file (noheader The example does, however, illustrate the basic relationship between the FILEDEF and MOVEFILE commands. In addition to the MOVEFILE command, if the OS input data set is on tape or cards, you can use the TAPPDS or READCARD command to create CMS files. These are also discussed below. Note: The MOVEFILE command does not support data containing spanned records. In addition, when copying a variable length data set (RECFM = V or VB) from an OS disk to a CMS disk, the logical record length (LRECL) of the file that is created on the CMS disk is equal to the size of the largest record in the data set being copied. If the file that is being created has a filemode of 4, the logical record length will be equal to the LRECL of the largest record plus 8 bytes. The actual LRECL of the new file can be determined by using the CMS LISTFILE command. Copying Sequential Data Sets from Disk The MOVEFILE command copies a sequential OS disk data set from a read-only OS disk into an integral CMS file on a CMS read/write disk. You use FILEDEF commands to identify the input file disk mode and data set name: filedef inmove cl dsn sales.manual Chapter 8. Developing as Programs under CMS 169 l ____.___._ __ . ____._____....._._.__ .__ . ___. ___________ . ._.___.____... _. ______. _. __., _______.__._.~. . __ =:=J the CMS output file's disk location and fileid: filedef outmove disk sales manual al and then you issue the MOVEFILE command: movefile Copying Partitioned Data Sets From Disk The MOVEFILE command can copy partitioned data sets (PDS) into CMS disk files and create separate CMS files for each member of the data set. You can have the' entire data set copied, or you can copy only a selected member. For example, if you have a partitioned data set named ASSEMBLE.SOURCE whose members are individual assembler language source files, your input file definition might be: filedef inmove cl dsn assemble source or filedef inmove cl dsn assemble. source To create individual CMS ASSEMBLE files, you would issue the output file definition as: filedef outmove disk qprint assemble al Then use the PDS option of the MOVEFILE command: movefile (pds When the CMS files are created, the filetype on the output file definition is used for the filetype and the member names are used instead of the eMS filename you specified. If you want to copy only a single member, you can use the MEMBER option of the FILEDEF command: filedef inmove disk assemble source c (member qprint and omit the PDS option on the MOVEFILE command: movefile The following figure summarizes the' various ways that you can create CMS files from OS data sets. 170 VM/SP eMS for System Programming r'" -.... --.- ... _- . .---.. - . --.-.. . .- _. _._. . _n_ -.- --.. -.- --------.------.-----.-----.- .--.--._-- -.--.------....- . -- Input File: An as "_'" ._._._. _. _ _ _ _ _ _ . . . . . . . ._ Sequential Data Set Named: ....._ ... __ .. _ .. _ CMS Output File Disk: OS RIO C-disk filedef indd c1 dsn compute test records filedef outdd disk compute records a1 movefile indd outdd COMPUTE RECORDS A1 Tape: 181 filedef inmove tap1 (Irecl 80 filedef outmove disk test records a1 movefile TEST RECORDS A1 tappds newtest compute (nopds NEWTEST COMPUTE A1 filedef cardin reader filedef diskout disk compute cards a1 movefile cardin diskout COMPUTE CARDS A1 readcard compute test COMPUTE TEST A1 Input file: Disk: OS RIO C-disk Tape: 182 Figure 20. _ . . . . . . _ _ . . . . . . . . . . . . . . . . " ' " ' ' • _ _ ._ ... __ • __ . _ _ ... " _ .. n _ . . . . . . . . _ _ ... _ _ .. ] COMPUTE.TEST.RECORDS CMS Command Examples Cards: ... _ . as Partitioned Data Set Named: TEST.CASES Members named: SIMPLE, COMPLEX, MIXED CMS Command Examples CMS Output File(s) filedef infile c1 dsn test cases filedef outfile disk new testcase a1 movefile infile outfile (pds SIMPLE TESTCASE A1 COMPLEX TESTCASE A1 MIXED TESTCASE filedef in c1 dsn test cases (member sim'ple filedef run disk movefile in run FILE RUN A1 tappds * test run (tap2 SIMPLE TESTRUN A1 COMPLEX TESTRUN A1 MIXED TESTRUN A1 Creating CMS Files from OS Data Sets Using eMS libraries CMS provides three types of libraries to aid in OS program development: o Macro libraries contain macro definitions and/or copy files. o Text, or program libraries contain relocatable object programs (compiler output). o LOADLIB libraries contain link edit files (load modules). These CMS libraries are like as partitioned data sets; each has a directory and members. Since they are not like other CMS files, you create, update, and use them differently than you do other CMS files. Although these library files are similar in function to as partitioned data sets, as macros Chapter 8. Developing as Programs under CMS 171 [Q)Q'\7G~@L3Uuu~ r...::.~~=-_. 08 LJ~1(Q)f~C10Uu\)O __________. ________ _____.____.___. ______. _____. _____ .______ . _______._. ________.__________. . . ~ should not be used to update them. Macro libraries are discussed below; text libraries are discussed under "TEXT Libraries (TXTLIBs)" on page 181, and LOADLIB libraries are discussed under "OS Module Libraries and CMS LOADLIBS" on page 183. Macro Libraries (MACLIBs) A CMS macro library has a filetype of MACLIB. You can create a MACLIB from files with filetypes of MACRO or COPY. A MACRO file may contain macro definitions. COpy files contain predefined source statements. The MACLIB Command The MACLIB command performs a variety of functions. You use it to: o o o o Create the MACLIB (GEN function). Add, replace, or delete members (ADD, REP, and DEL functions). Compress the MACLIB (COMP function). List the contents of the MACLIB (MAP function). Descriptions of these MACLIB command functions follow. Creating a Macro Library: The GEN (generate) function creates a CMS macro library from input files specified on the command line. The input files must have filetypes of either MACRO or COPY. For example: mac lib gen osmac access time put regequ creates a macro library with the file identifier OSMAC MACLIB Al from macros existing in the files with the file identifiers: ACCESS {MACRO} , TIME { MACRO} , PU.T {MACRO}, and REGEQU {MACRO}. COPY COpy . COpy . COpy If a file named OSMAC MACLIB Al already exists, it is erased. Assume that the files ACCESS MACRO, TIME COPY, PUT MACRO, and REGEQU COpy exist and contain macros in the following form: ACCESS MACRO GET PUT COpy PUT MACRO REGEOU COpy *COPY TTIMER TTIMER *COPY STIMER STIMER PUT XREG YREG The resulting file, OSMAC MACLIB AI, contains the members: GET PUT TTIMER 172 STIMER PUT REGEQU VM/SP eMS for System Programming [D)G\'Je~(Q~)Uuut1 r----.--- ________________ m _________ ([DS ~~u"@[jU"8uJ~S ----------- - - - - - - - - - - - - - - - - - - - - - - . - - - - - - - - . - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ) The PUT macro, which appears twice in the input to the command, also appears twice in the output. The MACLIB command does not check for duplicate macro names. If, at a later time, the PUT macro is requested from OSMAC MACLIB, the first PUT macro encountered in the directory is used. When COpy files are added to MACLIBs, the name of the library member is taken from the name of the COPY file or from the *COPY statement, as in the file TIME COPY, above. Note: Although the file REGEQU COpy contained two macros, they were both included in the MACLIB with the name REGEQU. When the input file is a MACRO file, the member name(s) are taken from macro prototype statements in the MACRO file. Adding a Member to a Macro Library: The ADD function appends new members to an existing macro library. For example, assume that OSMAC MACLIB Al exists as created in the example in the explanation of the GEN function and the file DCB COpy exists as follows: *eopy DeB DeB macro definition *eOpy DeBD DeBD macro definition If you issue the command: maclib add osmac deb the resulting OSMAC MACLIB Al contains the members: GET PUT TTIMER STIMER PUT REGEQU DeB DeBD Replacing a Member of a Macro Library: The REP (replace) function deletes the directory entry for the macro definition in the files specified. It then appends new macro definitions to the macro library and creates new directory entries. For example, assume that a macro library MYMAC MACLIB contains the members ALPHA, BETA, and SIGMA, and that the following command is entered: maclib rep mymac alpha sigma The files represented by file identifiers ALPHA MACRO and SIGMA MACRO each have one macro definition. After execution of the command, MYMAC MACLIB contains members with the same names as before, but the contents of ALPHA and SIGMA are different. Chapter 8. Developing as Programs under OMS 173 [liG~rrG~(Q)[:vnuuQJ c=-.__ =-_____, 08 [Ju'QQJr@u1u6 ____ . . __ ~~_._.~.__ ._.___J Deleting a Member of a Macro Library: The DEL (delete) function removes members from the macro library directory and compresses the directory so there are no unused entries. The macro definition still occupies space in the library, but since no directory entry exists, it cannot be accessed or retrieved. If you attempt to delete a macro for which two macro definitions exist in the macro library, only the first one encountered is deleted. For example: mac lib del osmac get put ttimer deb deletes macro names GET, PUT, TTIMER, and DCB from the directory of the macro library named OSMAC MACLIB. Assume that OSMAC exists as in the ADD function example. After the above command, OSMAC MACLIB contains the following members: STIMER PUT REGEQU DeBD Compressing a Macro Library: Execution of a MACLIB command with the DEL or REP functions can leave unused space within a macro library. The COMP (compress) function removes any macros that do not have directory entries. This function uses a temporary file named MACLIB CMSUTl. For example, the command: maclib comp mymac compresses the library MYMAC MACLIB. Listing Information about Members of a Macro Library: The MAP function creates a list containing the name of each macro in the directory, the size of the macro, and its position within the macro library. If you want to display a list of the members of a MACLIB at the terminal, enter the command: maclib map mylib (term The default option, DISK, creates a file on your A-disk, which has a filetype of MAP and a filename corresponding to the filename of the MACLIB. If you specify the PRINT option, the list is spooled to your virtual printer as well as being written onto disk. Note: The DISK, PRINT, and TERM options erase the old MAP file. You can also retrieve information for specific members of the library by indicating the member names following the MAP operand. For example: mac lib map mylib swerve yield returns the MAP output for only members SWERVE and YIELD of MYLIB MACLIB. If you want to place that information in the program stack, use the STACK option of the MAP operand. The information can be stacked FIFO (first-in 174 VM/SP eMS for System Programming c=. . .-.. "....''.--.-.-----.-.''--''''-.. -..-.-''. . -_._''-...__.''-_-..-_"-_. ,,_ ..-_-._.. -_ _",,-_...-_--_... -_.-_._. . -._.". _. . ._--_. -_.-._--., _-._-._ ..-_-"_-_-"_-". _. .-_-".-_. -_. _-."."........... ,,- .. - . . _._ ...._·... _._· .. " " h n . _ · ·• • _ •••....•..•••••• - , first-out} or LIFO (last-in first-out). The default order when STACK is specified alone is FIFO. The options STACK, STACK FIFO, and FIFO are equivalent. The options STACK LIFO and LIFO are equivalent. For example: maclib map mylib neutral reverse (stack fifo stacks in the program stack, the MAP output for the NEUTRAL and REVERSE members of MYLIB in first-in first-out order. See "The MAC LIST Command" on page 176 for more information on listing members of a MAC~IB. Manipulating MACLIB Members The following CMS commands recognize MACLIBs and have a MEMBER option: o o o o o XEDIT (to create and/or edit a specific member). PUNCH (to punch a member) FILEDEF (to establish a file definition for a member) PRINT (to print a member) TYPE (to display a member at the terminal) You can use the editor to create MACRO and COpy files and then use the MACLIB command to place the files in a library. Once they are in a library, you can erase the original files, or you can edit a member of a CMS library using the XEDIT command with the MEMBER option. For example, entering the command: xedit mylib maclib al {member swerve If the SWERVE member does not exist in that library, a new file is created with a fileid of SWERVE MEMBER Al. If SWERVE is an existing member of MYLIB MACLIB, you can edit the file. You can also select members of a specific CMS library to edit from your MACLIST (invoked by the MACLIST command). Note: You cannot create a new MACLIB using the MEMBER option of the XEDIT command. You must use the MACLIB command with the GEN option to create a new MACLIB. To extract a member from a macro library, you can use either the PUNCH or the MOVEFILE command. If you use the PUNCH command, you can spool your virtual card punch to your own virtual reader: cp spool punch to * Then punch the member: punch testmac maclib {member get noheader and read it back onto disk: Chapter 8. Developing OS Programs under CMS 175 r-c-.- . -.. -....-._-....-...-... _-_.-.. _-.__-.._-___-_-.-_.::-_.____ -=-=.:.=_=--=:=-_-.-_=.~=__.._._-_._-.. .::.___--_~_=_.:.-...._-._".-.".-"..- . . -.. . .-"...... _-._.. -._..-: .. . .. ........... ___ . _"""_,,,.,,,._,.__ '_' ._.• ____._..J readcard get macro In the above example, the member was punched with the NOHEADER option of the PUNCH command, so that a name could be assigned on the READ CARD command line. If a header card had been created for the file, it would have indicated the filename and file type as GET MEMBER. If you use the MOVEFILE command, you must issue a file definition for the input member name and the output macro or copy name before entering the MOVEFILE command: filedef inmove disk testcopy maclib (member enter filedef outmove disk enter copy a movefile This example copies the member ENTER from the ·macro library TESTCOPY MACLIB into a CMS file named ENTER COPY. When you use the PUNCH or MOVEFILE commands to extract members from CMS MACLIBs, each member is. followed by a / / record, which is a MACLIB delimiter. You can edit the file and use the DELETE subcommand to delete the / / record. If you want to move the complete MACLIB to another file, use the COPYFILE command. To print asingle member or all members of a macro library, use the CMS PRINT command with the MEMBER option. To display on the terminal a single member or all members of a macro library, use the CMS TYPE command with the MEMBER option. The MACLIST Command The MACLIST command displays a list of all members in a specified macro library. MACLIST provides you with an easy way to select and edit CMS maclib members. CMS commands can be issued against the members directly from the displayed list. The commands execute when you press the ENTER key. In the MACLIST environment, information that is normally provided by the MACLIB command (with the MAP option) is displayed under the control of the System Product editor. You can use XEDIT subcommands to manipulate the list itself. The following MACLIST screen was created by issuing the MACLIST command as follows: maclist mylib Note that the members are sorted alphabetically by member name. Members with the same name are then sorted by index number (least to greatest). 176 VM/SP eMS for System Programming r FARRELL MACLIST AO V 130 Trunc=130 Size=18 Line=l Col=l Alt=O Cmd Member name Index Records Library name Library type Mode CAUTION 190 6 MYLIB MACLIB Al FAST 240 25 MYLIB MACLIB Al FORWARD 613 57 MYLIB MACI.IB Al GO 197 25 MYLIB MACLIB Al GO 615 25 MYLIB MACLIB Al LTURN 546 MYLIB MACLIB Al 55 NEUTRAL 266 MYLIB MACLIB Al 5 PARK 602 4 MYLIB MACLIB Al REVERSE 272 118 MYLIB MACLIB Al RTURN 524 21 MYLIB MACLIB Al SKID 391 43 MYLIB MACLIB Al SLOW 671 61 MYLIB MACLIB Al SLOWER 435 5 MYLIB MACLIB Al SLOWEST 441 82 MYLIB MACLIB Al SPEED 2 132 MYLIB MACLIB Al STOP 607 MYLIB MACLIB Al 5 SWERVE 223 16 MYLIB MACLIB Al YIELD MYLIB 135 54 MACLIB Al 2= Refresh 3= Quit 1= Help 4= Sort(name) 5= Sort(index) 6= Sort(size) 7= Backward 8= Forward 9= FL In 10= 11= XEDIT 12= Cursor ====> XED I T 1 File \. Figure 21. '" ~ Sample MACLIST Screen Finding Members in Your MACLIST List: If there are many members in the maclib, the list may take up more than one screen. To find a member in your MACLIST list, you can do any of the following: o o Scroll through the list using the PF keys. PF7 Scrolls backward one full screen. PF8 Scrolls forward one full screen. Rearrange the list using one of the following PF keys: PF4 Sorts the list by member name. This is how the list is initially arranged. PF5 Sorts the list by index (largest first). The most recently updated members have a greater number. PF6 Sorts the list by size (largest to smallest). o Use the XEDIT subcommand LOCATE if you know the member name that you are looking for. o Rearrange the list by entering one of the following synonyms on the command line: SINDEX Sorts the list by index (greatest to least) within a library. Chapter 8. Developing as Programs under' CMS 177 r .......... _.._.. ___.____.....__~_ ....__. . __.__._._._ ._.. __.. __ ._________ . _.__ ._._._....... _.._._ ..... _......._. __ ..1 SLIB Sorts the list alphabetically by library fileid. SNAME Sorts the list alphabetically by member name. This is how the list is initially arranged. SSIZE Sorts the list by member size (number of records, greatest to least). Entering Commands in the MACLIST Environment: You can type commands that operate on member names in the list directly on the lines of the MACLIST display. When you press the ENTER key, all commands typed on the lines in the file displayed on the current screen are executed. Symbols can be used to represent operands in the command to be executed. Symbols are needed if the command to be executed has operands or options that follow the fileid. For example to issue the PRINT command for this member of your MACLIST: NEUTRAL 266 5 MYLIB MACLIB Al type directly on the line that contains this member as follows: print /EUTRAL 266 5 MYLIB MACLIB Al and then press the ENTER key. Refer to the MACLIST command in the VM/ SP CMS Command Reference for more information about using symbols in MACLIST. Another way to issue commands that make use of member names displayed is to move the current line to the first (or only) member you want the command to use. Then issue an EXECUTE command (in the form "EXECUTE lines command") from the XEDIT command line. This method may be used on both display and typewriter terminals. You can also enter commands from the MACLIST command line. Editing a Maclib Member: The MACLIST command allows you to select and edit a CMS maclib member from the list. To edit a member, position the cursor on the line that contains the member to be edited and press the PFl1 key. Otherwise, you can edit a CMS maclib member by using the XEDIT command with the MEMBER option. For example, to edit the SWERVE member of MYLIB maclib, enter: xedit mylib mac lib al (member swerve If the SWERVE member did not exist in MYLIB MACLIB, a new file is created with a fileid of SWERVE MEMBER AI. 178 VM/SP eMS for System Programming ~JG~G~O~JUuuO oS lJ[jJOUGJcJOI~G __ . =-':=-=:":":'=":"::_-=--=':"::"-=:=-:_==-'-~:~-='-'-~.:~~~'-~_:~:': ==~==~~ =~_~~ ===--::~.-:=-~~~~=--=--=========-~~-==-=:==-~=~.=-~= =-=::.==~~~_~~...:..:..~_-.:~_=J Adding and Replacing Maclib Members: When the MEMBER option is specified for the XEDIT command for a member that does not exist in the library, a new file is created with the fileid of "membername MEMBER fm." If the MEMBER option is specified on the XEDIT command for an existing member of a library, the member is read into a file called "membername MEMBER fm" for you to edit. When you issue FILE or SAVE for the new or changed member, the library directory is updated. The new or changed member and the updated library directory are added to the end of the library. If the directory already contains a member with the same name as the one being saved, the old entry is blanked out, so that the updated member replaces the old version. Deleting Maclib Members: Use the DISCARD command to delete a member from a library. DISCARD is equivalent to the CMS command MACLIB DEL. DISCARD can either be typed in the command area of the line that describes the member you want discarded, or it can be entered from the command line (at the bottom of the screen). DISCARD can only be used while in the FILELIST, RDRLIST, MACLIST, and PEEK command environments. Setting MACLIST Defaults: When XEDIT is invoked by the MACLIST command to display the list, the default XEDIT macro, PROFMLST XEDIT, is executed. If you want to invoke a different XEDIT macro, you can specify the PROFILE option with the MACLIST command. For example, to invoke MACLIST with the MYMCLST XEDIT macro, enter maclist mylib (profile mymclst You can do the same with the COMPACT and NOCOMP ACT options of the MACLIST command. If you are using an alternate profile most of the time, you may change the default profile with the DEFAULTS command. For example: defaults set maclist profile mymclst Entering the DEFAULTS command with no options provides you with the status of defaults currently in effect. For example, entering defaults after changing the XEDIT macro, returns the following information: Chapter 8. Developing OS Programs under CMS 179 L _______. _. _._. __ ._______._.__________________.__________ ._. ______. __________. ___ .. _. __.______ . . ___._.____.___.J The following default options have been set: Filelist options = PROFILE PROFFLST NOFILELIST Help options = SCREEN BRIEF ALL Maclist options = PROFILE MYMCLST NOCOMPACT Note options = PROFILE PROFNOTE SHORT LOG NOACK NOTEBOOK ALL Peek options = PROFILE PROFPEEK FROM 1 FOR 200 Rdrlist options = PROFILE PROFRLST Receive options = LOG OLDDATE NOTEBOOK ALL Sendfile options = NEW TYPE NOFILELIST LOG NOACK Tell options = MSGCMD MSG To change any default options enter DEFAULTS Set Cmdname Optl The GLOBAL Command When you want to assemble or compile a source program that uses macro or copy definitions, you must ensure that the library containing the code is identified before you invoke the assembler. Otherwise, the library is not searched. Yo'u identify libraries to be searched using the GLOBAL command. For example, if you have two MACLIBs that contain your private macros and copy files whose names are TESTMAC MACLIB and TESTCOPY MACLIB, you would issue the command: global maclib testmac testcopy The libraries you specify on a GLOBAL command line are searched in the order you specify them. A GLOBAL command remains in effect for the remainder of your terminal session, until you issue another GLOBAL MACLIB command or IPL CMS again. To find out what macro libraries are currently available for searching, issue the command:' query mac lib You can reset the libraries or the search order by reissuing the GLOBAL command. System MACLIBs The macro libraries that are on the system disk contain CMS and OS assembler language macros you may want to use in your programs. The MACLIBs are: o CMSLIB MACLIB contains the CMS macros from VM/370. o DMSSP MACLIB contains the macros that are new or changed in VM/SP. Note: When assembling programs that use CMS macros, both of these libraries should be identified via the GLOBAL command. DMSSP should precede CMSLIB in the search order. o 180 OSMACRO MACLIB contains the OS macros that CMS supports or simulates or those that require no CMS support. VM/SP eMS for System Programming o OSMACROI MACLIB contains the macros CMS does not support or simulate. (You can assemble programs in CMS that contain these macros, but you must execute them in an OS virtual machine.) o OSVSAM MACLIB contains the subset of supported OS/VSAM macros. o TSOMAC MACLIB contains TSO macros. o DOSMACRO MACLIB contains macros used internally in CMS/DOS. Note: The DOSMACRO MACLIB contains macros used internally by CMS/DOS system routines. These macros should not be used in user written programs. To obtain a list of macros in any of these libraries, use either the MACLIST command or the MACLIB command with the MAP function. In the MACLIST environment, you can issue CMS commands against the members directly from the displayed list. You can find more information about the MACLIST command in the VM/ SP CMS Command Reference. TEXT Libraries (TXTLIBs) You may want to keep your TEXT files in text libraries. These files have a filetype of TXTLIB. You can create a TXT LIB from files with a filetype of TEXT. Like MACLIBs, TXTLIBs have a directory and members. The TXTLIB Command TXTLIBs are created and modified by the TXTLIB command, which has functions similar to the MACLIB command: o o o o Create the TXTLIB (GEN function). Add members to the TXTLIB (ADD function). Delete members of the TXTLIB and compress the TXTLIB (DEL function). List the members of the TXTLIB (MAP function). There is no REP function. You must use a DEL followed by an ADD to replace an existing member. Creating a TXTLIB: The TXTLIB command with the FILENAME option specified reads the object files as it writes them into the library and creates a directory entry for each filename. If you have a TEXT file named MYPROG, which has an entry point named BEGIN, create the TXT LIB named TESTLIB as follows: txtlib gen testlib myprog (filename TESTLIB contains a member name MYPROG with an entry point BEGIN. Specify the member name MYPROG to reference this TXT LIB member. If you do not specify the FILENAME option, TESTLIB will contain no entry Chapter 8. Developing as Programs under CMS 181 L__ ......... ___.~_, ................ '_H'" O. ___ .. . _.H_ . _...... _... _· . ~ __.___._____._ _ _ _ _ _ ~ __ .~_ ....~_ . ____ .~:._:.:. __~-=-I·: . . ____ . . . ~~ __ ~_. ____ ~._ ....... _..... ~. _....._. . ~_ .. ___ ._____. .____ . _.H._J for the name MYPROG. You will have to specify the member name BEGIN to reference this TXTLIB member. Loading and Executing TXTLIBs: When you want to load members of TXTLIBs into storage to execute them Gust as you execute TEXT files), you must issue the GLOBAL command to identify the TXTLIB: global txtlib testlib load begin (start When you specify more than one TXTLIB on the GLOBAL command line, the order of search is established for the TXTLIBs. However, if the AUTO option of the LOAD and INCLUDE commands is in effect (it is the default), CMS searches for TEXT files before searching active TXTLIBs. When the TXTLIB command processes a TEXT file, it writes an LDT (loader terminate) card at the end of the TEXT file so that when a load request is issued for a TXTLIB member loading terminates at the end of the member. If" you add OS linkage editor control statements to the TEXT file (using the CMS editor) before you issue the TXTLIB command to add the file to a TXTLIB, the control statements are processed as follows: NAME Statement: A NAME statement causes the TXTLIB command to create the directory entry for the member using the specified name. Thereafter, when you want to load that member into storage or delete it from the TXTLIB you must refer to it by the name specified on the NAME statement. Note: The FILename option overrides any name card found in a text file. The name card functions as before, but the specified file name becomes the membername in the TXTLIB. The name card is the only entry within that membername of the TXTLIB. The loader does not use name cards to resolve entry points. It is important that the name on the name card be the same as the name on the CSECT or entry card. This will ensure that the loader will find the correct text deck and loader tables (any external references) will be resolved with the entry point. If the names differ, the loader will load the text deck based on the name card (or file name). However, the loader tables will be set up according to entry or CSECT cards encountered during the load. Any external reference using the name from the name card will be resolved as zeros. ENTRY Statement: If you use an ENTRY statement, the entry point you specify is validated and checked for a duplicate. If the entry point name is valid and there are no duplicates in the TEXT file, the entry name is written in the LDT card. Otherwise, an error message is issued. When this member is loaded, execution begins at the entry point specified. 182 VM/SP eMS for System Programming 0 1r"1 [1'11"-")117("') n,'\ [~J nr'l (,', ((~;\ (~ ['J r',l '-.~ ,,'1 r r "',) '"-' 1:._) ~ U ~ J C. ,j :1 u~..J b . . _} L•.J '-'::'" 'J ...:... U1(.':; ~ . ~ Uu L_. __._"_. __~_~~_. __ .:....__._.. _._ ...._.... ~"':"__ ~ ____ ~'..~ .~.~._._. _____ ...:.._. ___ ~~ __ ._~._.. __ .~...:....:.~~~~~ =~.:~:.: .....:~~. ~:..:.:.:~:.:~._. __ ~ ____.. '_ ~:::. ~:.:~~:~:.~-] ALIAS Name: An entry is created in the directory for the ALIAS name you specify. A maximum of 16 alias names can be used in a single text deck. You may load the single member and execute it by referring to the alias name, but you cannot use the alias name as the object of V-type address constant (VCON) because the address of the member cannot be resolved. SETSSI Card: TXTLIB command information you specify on the SETSSI card is written in bytes 26 through 33 of the LDT card. All other OS linkage editor control statements and commands are ignored by the TXTLIB command and written into the TXT LIB member. When you attempt to load the member, the CMS loader flags these cards as invalid. These cards may be added as history information to a module if you specify the HIST option on the LOAD or INCLUDE commands and then issue a subsequent GENMOD command. Manipulating TXTLIB Members The following CMS commands recognize TXTLIBs and have a MEMBER option: o o o PUNCH PRINT TYPE Use the CMS PUNCH command with the MEMBER option to punch a single member or all members of a TXTLIB. Use the CMS PRINT command with the MEMBER option to print a single member or all members of a TXTLIB. Use the CMS TYPE command with the MEMBER option to display on the terminal a single member or all members of a TXTLIB. OS Module Libraries and eMS LOADLIBS The OS relocating loader allows the user to load a member of a CMS LOAD LIB or an OS module library on an OS formatted disk. The OS LINK, LOAD, ATTACH, and XCTL macros are supported. In addition, the OSRUN command (which generates a LINK SVC) loads and executes members directly from the console. For the LINK, LOAD, ATTACH, and XCTL macros, the libraries specified in the LOADLIB global list are searched. If the requested member is not found, CMS looks for a TEXT file by that name. Then, if still not found, the TXTLIBs specified in the TXTLIB global list are searched for the member name. For the OSRUN command, the libraries specified in the LOADLIB global list are searched. If the member is not found and the user has a $SYSLIB LOADLIB file, it is searched for the member name. (TEXT files and TXTLIBs are not considered by OSRUN.) Chapter 8. Developing OS Programs under CMS lS3" l-'~-------------~- Executing OS Module Libraries If the module to be executed resides in an OS module library on an OS formatted disk, the disk must be accessed and the library must be defined (via the FILEDEF command) to make it known to CMS. For example, access the OS disk as a B-disk at the address 250: ACCESS 250 B Suppose SYSl.TESTLIB is an OS module library on the OS disk and contains the member TESTl. Use the FILEDEF command to relate SYSl. TESTLIB to the CMS LOADLIB called OSLIB LOADIB: FILEDEF $SYSLIB DISK OSLIB LOADLIB B DSN SYSl TESTLIB (DSORG PO RECFM U BLOCK 7294 Now you can refer to the OS module library, SYS1.TESTLIB, by using the CMS file identifier OSLIB LOADLIB. Before you try to execute TESTl, use the GLOBAL command to identify the CMS LOADLIBs to be searched. For example, GLOBAL LOADLIB OSLIB Then, the OSRUN command searches OSLIB LOADLIB for the member, TESTl, to load and execute. For example, OSRUN TESTl The DDNAME specified on the FILEDEF command must be $SYSLIB. The filename (OSLIB), specified on the FILEDEF command, can be any name, but it must correspond to the name stated in the GLOBAL command. The filetype must be LOADLIB. Creating and Executing CMS LOADLIBs If the program to be executed resides on a CMS disk, use the LKED command. The LKED command creates a CMS LOAD LIB from a CMS TEXT file. For example: LKED TESTFILE takes the CMS TEXT file, TESTFILE TEXT, and creates the CMS LOADLIB, TESTFILE LOADLIB. For more information on input to the LKED command refer to "The LKED Command" on page 186. The CMS LOADLIB created by the LKED command is an OS simulated partitioned data set (PDS) namedTESTFILE LOADLIB and contains one member named TESTFILE. Before executing TESTFILE, use the GLOBAL command to identify the LOADLIB to be searched: GLOBAL LOADLIB TESTFILE 184 VMjSP eMS for System Programming . ______ .___ .:. :____. _. _. :. . . :_ . _ _ ._. _.. : . . _ .. _. _..... ....._. _ .__ . _. ._. _ ... .:. :. _.:. ___ . __. _._____ [~_=-===-~~ _...:_~ _~. .~_~_ ~.: ~_:.::.._ ..._. . .. :_._ _.___ ~_ .~~...:~_~ __J Then the OSRUN command loads, relocates, and executes the TESTFILE member of TESTFILE LOADLIB: OS RUN TESTFILE Maintaining CMS LOADLIBs The LOADLIB command provides the utility necessary to maintain the CMS LOADLIBs. The following functions are provided: COpy Copy members from one LOAD LIB to another Merge complete.LOADLIBs Copy with SELECT or EXCLUDE COMPRESS Compress a CMS LOADLIB LIST LIST members of a CMS LOADLIB For more detailed information on the LKED, GLOBAL, OSRUN, and LOADLIB commands, refer to the VM/ SP CMS Command Reference. Concatenating Files To define more than one library with the same DDNAME, use the CONCAT option of the FILEDEF command. You can concatenate the LOADLIB files on OS disks with each other and/or with CMS LOADLIB files. Any library to be searched must be specified in the GLOBAL LOADLIB statement. The data set with the largest block size should be specified first (both in the FILEDEF and in the GLOBAL list). CMS files do not require a file definition. But, if used, the file with the largest block size should be specified first. The GLOBAL list determines the order in which the libraries are searched. For example, search two OS files and a CMS LOADLIB for the member, THETA, using the following commands: ACCESS 250 B (if 250 FILEDEF $SYSLIB DISK (DSORG PO RECFM FILEDEF $SYSLIB DISK GLOBAL LOADLIB OSLIB OSRUN THETA is the address of the OS disk) OSLIB LOADLIB DSN SYSl LIBl U BLOCK 7294) MYLIB LOADLIB B DSN SYSl LIB2 (CONCAT) MYLIB CMSLIB Note: The first FILEDEF command for $SYSLIB must describe the first library filename in the GLOBAL list. Its attribute will be used when the libraries are searched. It is advisable not to code the CONCAT option on the first FILEDEF command so that it clears all previous FILEDEFs for that ddname. Chapter 8. Developing OS Programs under CMS 185 ~)0)t'7G~O[))Uuu[~ 08 [?[j~eC:Ju'OuuuD c=:::=--=..-___ _________.______________ ::::..-==:::J The LKED Command The LKED command uses the OS Linkage Editor for the actual link of the TEXT file to the LOADLIB as an executable module. In order to link edit CMS files, you can issue the FILEDEF command to identify input to the OS Linkage Editor. Primary LKED input is a data set known to the linkage editor as SYSLIN, which can be described in the FNAME operand of the LKED command. The filetype of the input file named in the command line must be TEXT. Optionally, you can override the FNAME operand by issuing a FILEDEF that defines SYSLIN as the ddname of an alternate primary input source. If your alternate input is a CMS file, the choice of filetype is unrestricted. The contents of the SYSLIN dataset may be: 1. 2. 3. Object text such as assembler or compiler output Linkage editor control statements A combination of object text and control statements. Linkage editor control statements can be inserted before, between, and after object modules and other control statements. Editing procedures can be used to construct files to meet your requirements. Linkage editor INCLUDE statements may be used to designate explicitly the following files or file members as secondary linkage editor input: 1. 2. 3. 4. 5. CMS TEXT files Members of CMS TXTLIB files Members of CMS LOADLIB files Members of OS object libraries Members of OS load libraries. A FILEDEF must be issued before the LKED command to define a unique ddname for each file to be included as secondary linkage editor input. An INCLUDE statement in the SYSLIN dataset must specify the ddname assigned to the file by your FILEDEF. For library files, the statement must also specify all members of the library that are to be included as input. The use of all FILEDEF commands and INCLUDE statements to identify input files is shown in the following examples. CMS commands: FILEDEF LIBDEF DISK MYLIB TXTLIB B FILEDEF TXTDEF DISK MYFILE TEXT C SYSLIN input: INCLUDE LIBDEF(CSECT1,CSECT2) INCLUDE TXTDEF INCLUDE statements must begin in column 2. The applicable statement formats are described in the 08/ VB Linkage Editor and Loader. When SYSLIN input to the LKED command is an assembled object file in fixed-block format residing on an OS disk, the RECFM FBS option of the FILEDEF command must be specified. The following example shows 186 VM/SP eMS for System Programming ~j(Y\JG~(O~)UU·l1~j c= . .-.-.--..-.. -----... -- . . ----.-.--... -... --..---.-.-..------------..-.----.--.-.. -.. -_.. _ ..._ ..-._.--_. --_-.. .._... U - ••• - . -.--..-. '.-.:... nuo •••• - .• - - - . - . - . - - . - «JS ~JuJ()tJu'(Ju {MJ . - - • • • • • • . - - - . - - . -•• - - • .- - - . - - - - - - .• - • . . • • - •. - .~.- . - •.•• - . - ) FILEDEF commands and SYSLIN input to identify a member of an OS object library and a CMS TXTLIB. CMS commands: FILEDEF OSOBJ DISK OBJECT FILE Q DSN SYS1 FEOBJ (RECFM FBS LRECL 80 BLOCK 3120 FILEDEF TXTDEF DISK NEWLIB TXTLIB B SYSLIN input: INCLUDE OSOBJ(MEMBER1) INCLUDE TXTDEF(CSECT1) Automatic library search is available for either CMS or OS type library members if the FILEDEF for the dataset to be searched specifies SYSLIB as the ddname. Additional libraries can be selected for automatic search by placing linkage editor LIBRARY statements in your SYSLIN input file. Each library statement must contain the associated ddname and a list of members within the library to be included in the search. A FILEDEF must be issued before the LKED command to assign a unique ddname to each dataset to be searched. The library search conducted during a single linkage editor execution is limited to either object-type or load-type modules and may not combine both types. The CONCAT option of the FILEDEF command is not valid for LKED input datasets. To expand the use of the automatic SYSLIB search, the user may combine the members of several CMS libraries into a single composite library. The automatic search facility applies to CMS TXTLIBs and LOADLIBs and to OS object libraries and LOAD libraries. The following example shows FILEDEF commands and SYSLIN input for an automatic library search. CMS commands: FILEDEF SYSLIB DISK SEARCH1 TXTLIB B FILEDEF LIBDEFA DISK SEARCH2 TXTLIB C FILEDEF LIBDEFB DISK OSTEXT LIBRARY D DSN OBJMODS SYSLIN input: LIBRARY LIBDEFA(CSECT1,CSECT2) LIBRARY LIBDEFB(MEMBER1,MEMBER2) LIBRARY statements must begin in column 2. The GLOBAL command is not needed to identify linkage editor input libraries. For LOADLIB input to the linkage editor, the RECFM U option of the FILEDEF command must be specified. The default FILEDEF commands issued by the LKED command for the ddnames presented to the Linkage Editor are as follows: Chapter 8. Developing as Programs under CMS 187 [DQvG~CV[vO~u0J O~~ L")U'80u~ClG1uS ...._.__ ...... c::~~:~~==-._==-~:=:=======--:-:-:~ FILEDEF FILEDEF -orFILEDEF FILEDEF FILEDEF -orFILEDEF -orFILEDEF .. _... _._ . _______.____...._. _____._._. ___.______ .___ .._. __.___._____ ._._. __ ._ ._.________ ._ .. _.::-.:J SYSLIN DISK FNAME TEXT * (RECFM F BLOCK 80 NOCHANGE SYSLMOD DISK fname LOADLIB Al (RECFM U BLOCK 260 NOCHANGE SYSLMOD DISK libname LOADLIB Al (RECFM U BLOCK 260 NOCHANGE SYSUTI DISK fname SYSUTI * SYSPRINT DISK fname LKEDIT Al SYSPRINT PRINTER SYSPRINT DUMMY At the completion of the LKED command, all FILEDEFs that do not have the PERM option are erased. OS Data Management Simulation The disk format and data base organization of eMS are different from those of OS. A eMS file produced by an OS program running under eMS and written on a eMS disk has a different format from that of an OS data set produced by the same OS program running under OS and written on an OS disk. The data is exactly the same, but its format is different. (An OS disk is one that has been formatted by an OS program, such as the Device Support Facility.) eMS does not support multi-buffering for unit record devices. There is one DeB per device, not per file. Handling Files that Reside on eMS Disks eMS can read, write, or update any OS data that resides on a eMS disk. By simulating OS macros, eMS simulates the following access methods so that OS data organized by these access methods can reside on eMS disks: o BDAM (direct) -- identifying a record by a key or by its relative position within the data set. o BPAM (partitioned) -- seeking a named member within data set. Note: Two BPAM files with the same filetype cannot be updated at the same time. o BSAM/QSAM (sequential) -- accessing a record in a sequence in relation to preceding or following records. o VSAM (direct or sequential) -- accessing a record sequentially or directly by key or address. Note: eMS support of OS VSAM files is based on VSE/VSAM. Therefore, the OS user is restricted to those functions available under VSE/VSAM. See the section "eMS Support for OS and VSE/VSAM Functions" for details. 188 VM/SP eMS for System Programming [jJGt7G~GJ~)DuutJ _ __--_------:- ------------ ---:_ l ___ ~,~ _____.__________.___ _ OS lJu'IDU[j'cJu u-~G ~===-=~~~=~~~ ___ ~=_~~~~~:::":~~~_~_~_:::':::J Refer to Figure 22 on page 189 and "OS Macros" on page 191, then read "Access Method Support" on page 199 to see how CMS handles these access methods. Since CMS does not simulate the indexed sequential access method (ISAM), no OS program using ISAM can execute under CMS. Therefore, no program can write an indexed sequential data set on a CMS disk. Handling Files that Reside on OS Disks By simulating OS macros, CMS can read, but not write or update~ OS sequential and partitioned data sets that reside on OS disks. However, an OS sequential or partitioned data set that resides on an OS disk can be written or updated only by an OS program running in an OS system. CMS can execute programs that read and write VSAM files from OS programs written in the VS BASIC, COBOL, PL/I, VS/APL, and VS FORTRAN programming languages. eMS also supports VSAM for use with DOS/VS SORT/MERGE. This CMS support is based on the VSE/VSAM Program Product and, therefore, the OS user is limited to those VSAM functions that are available under VSE/VSAM. Simulating OS Supervisor Calls IH~Cl'O SVC N'anlC NUl11.ber Function XDAP EXCP 00 00 WAIT POST EXIT/RETURN GETMAIN FREEMAIN GETPOOL FREEPOOL LINK XCTL LOAD DELETE GETMAIN/FREEMAIN TIME 01 02 03 04 05 Reads or writes direct access volumes Executes graphic channel programs for graphic access method (GAM) Waits for an I/O completion Posts the I/O completion Returns from a called phase Conditionally acquires user storage Releases user-acquired storage Simulates as SVC 10 Simulates as SVC 10 Links control to another phase Deletes, then links control to another load phase Reads a phase into storage Deletes a loaded phase Manipulates user free storage Gets the time of day Figure 22 (Part 1 of 3). 06 07 08 09 10 11 Simulated OS Supervisor Calls Chapter 8. Developing as Programs under CMS 189 [Q)G~C~~(Q)~])U~ll[j 08 fV~1(Q)fDu1@uuuG [ •. _._. __....._. __ ...____ ._. __. _____ ._. _____ .______. _ _ _ _ _ _ _ _ _._._1.._ _ __ Macro Name ABEND SPIE SVC RESTORE BLDL FIND OPEN CLOSE STOW OPENJ TCLOSE DEVTYPE TRKBAL FEOV WTO/WTOR EXTRACT IDENTIFY ATTACH CHAP TTIMER STIMER DEQ SNAP ENQ FREEDBUF STAE 17 18 18 19 20 21 22 23 24 25 31 35 40 41 42 44 46 47 48 51 56 57 60 DETACH CHKPT RDJFCB SYNAD SYNADAF SYNADRLS BSP TGET/TPUT TCLEARQ 62 63 64 Number 13 14 68 68 69 93 94 Function Terminates processing Allows processing program to handle program interrupts Effective NOP Builds a directory for a partitioned data set Locates a member of a partitioned data set Activates a data file Deactivates a data file Manipulates partitioned directories Activates a data file Temporarily deactivates a data file Gets device-type physical characteristics Effective NOP Sets forced EOV error code Communicates with the terminal Effective NOP Adds entry to loader table Effective LINK Effective NOP Accesses or cancels timer Sets timer interval and timer exit routine Effective NOP Dumps specified areas of storage Effective NOP Releases a free storage buffer Allows processing program to decipher abend conditions Effective NOP Effective NOP Obtains information from FILEDEF command Handles data set error conditions Provides SYNAD analysis function Releases SYNADAF message and save areas Backs up a record on a tape or disk Reads or writes a terminal line Clears terminal input queue Figure 22 (Part 2 of 3). Simulated OS Supervisor Calls 190 VM/SP eMS for System Programming -_. . __ ._--_. _---------_ .... _--_.. _._._-_.__._-----J '_---__ ~~~_-_- ~ ____ . .:. . . . __ --.:.~_=______________________:. . . ___________________ _ C=~:,:,~=_,_' 1I.t1ncro I'Tame STAX SVC PGRLSE CALL 112 SAVE RETURN - GET/PUT READ WRITE NOTE/POINT CHECK DCB DCBD Figure 22 (Part 3 of 3). NUlllbel' 96 - - - Function Updates a queue of CMTAXEs that creates an attention exit block Releases storage contents Transfers control to a control section at a specified entry Saves program registers Returns from a subroutine Reads/Writes system-blocked data (QSAM) Accesses system-record data Write system-record data Manages data set positioning Verifies READ/WRITE completion Constructs a data control block Generates a DSECT for a data control block Simulated OS Supervisor Calls as Macros Because CMS has its own file system and is a single-user system operating in a virtual machine with virtual storage, there are certain restrictions for the simulated as function in CMS. For example, HIARCHY options and options that are used only by as multitasking systems are ignored by CMS. Due to the design of the CMS loader, an XCTL from the explicitly loaded phase, followed by a LINK by succeeding phases, may cause unpredictable results. Listed below are descriptions of all the as macro functions that are simulated by CMS as seen by the programmer. Implementation and program results that differ from those given in as Data Management Macro Instructions and as Supervisor Services and Macro Instructions are stated. HIARCHY options and those used only by as multitasking systems are ignored by CMS. Validity checking is not performed within the simulation routines. The entry point name in LINK, XCTL, and LOAD (SVC 6,7,8) must be a member name or alias in a LOADLIB directory or in a TXTLIB directory unless the COMPSWT is set to on. If the COMPSWT is on, SVC 6,7, and 8 must specify a module name. This switch is turned on and off by using the COMPSWT macro. See the VM/SP eMS Macros and Functions Reference for descriptions of all CMS user macros. XDAP-SVC 0 The TYPE option must be R or W; the V, I, and K options are not supported. The BLKREF-ADDR must point to an item number acquired by a NOTE macro. Other options associated with V, I, or K are not supported. Chapter 8. Developing as Programs under CMS 191 L . __ ..-___..._. . .______ ._. __.___. __._______ . _.__. . __...__ .____. ____._ _ _ _ _ _ _ _ .._____ . __._._." .... _......... __. __ ............ _....._.... _._ ........ _ ...___ ..._..... ___.._._. .0._.••• _ . _ ] EXCP-SVC 0 The EXCP macro is supported by CMS. The EXCP macro executes graphic channel programs for graphic access method (GAM). WAIT-SVC 1 All options of WAIT are supported. The WAIT routine waits for the completion bit to be set in the specified ECBs. POST-SVC 2 All options of POST are supported. POST sets a completion code and a completion bit in the specified ECB. EXIT/RETURN-SVC 3 Depending upon whether this is an exit or return from a linked or an attached routine, SVC 3 processing does the following: posts ECB, executes end of task routines, releases phase storage, unchains and frees latest request block, and restores registers. Do not use EXIT/RETURN to exit from an explicitly LOADed phase. If EXIT/RETURN is used for this purpose, CMS issues abend code AOA. GETMAIN-SVC 4 All options of GETMAIN are supported except SP, BNDRY=, HIARCHY, LC, and LU. SP, BNDRY=, and HIARCHY are ignored by CMS. LC and LU result in abnormal termination if used. GETMAIN gets blocks of free storage. FREEMAIN-SVC 5 All options of FREEMAIN are supported except SP and L. SP is ignored by CMS, and L results in abnormal termination if used. FREEMAIN frees blocks of storage acquired by GETMAIN. GETPOOL/FREEPOOL All the options of GETPOOL and FREEPOOL are supported. GETPOOL constructs a buffer pool and stores the address of a buffer pool control block in the DCB. FREEPOOL frees a buffer pool constructed by GETPOOL. 192 LINK-SVC 6 The DCB and HIARCHY options are ignored by CMS. All other options of LINK are supported. LINK loads the specified program into storage (if necessary) and passes control to the specified entry point. XCTL-SVC 7 The DCB and HIARCHY options are ignored by CMS. All other options of XCTL are supported. XCTL loads the specified program into storage (if necessary) and passes control to the specified entry point. LOAD-SVC 8 The DCB and HIARCHY options are ignored by CMS. All other options of LOAD are supported. LOAD loads the specified program into storage (if necessary) and returns the address of the specified entry point in register O. If VM/SP eMS for System Programming loading a subroutine is required when SVC 8 is issued, CMS searches directories for a TXTLIB member containing the entry point or for a TEXT file with a matching filename. An entry name in an unloaded TEXT file will not be found unless the filename matches the entry name. After the subroutine is loaded, CMS tries to resolve external references within the subroutine, and may return another entry point address. To insure a correct address in register 0, the user should bring such subroutines into storage either by the CMS LOAD/INCLUDE commands or by a VCON in the user program. DELETE-SVC 9 All the options of DELETE are supported. DELETE decreases the use count by one and, if the result is zero, frees the corresponding virtual storage. Code 4 is returned in register 15 if the phase is not found. GETMAIN/FREEMAIN-SVC 10 All the options of GETMAIN and FREEMAIN are supported except SP and HIARCHY, which are ignored by CMS. TIME-SVC 11 CMS supports only the DEC, BIN, TU, and MIC parameters of the TIME macro instruction. TIME returns the time of day to the calling program. However, the time value that CMS returns is only accurate to the nearest second and is converted to the proper unit. ABEND-SVC 13 The completion code parameter is supported. The DUMP parameter is not. If a STAE request is outstanding, control is given to the proper STAE routine. If a STAE routine is not outstanding, a message indicating that an abend has occurred is printed on the terminal along with the completion code. SPIE-SVC 14 All the options of SPIE are supported. The SPIE routine specifies interruption exit routines and program interruption types that cause the exit routine to receive control. RESTORE-SVC 17 The RESTORE routine in CMS is a NOP. It returns control to the user. BLDL-SVC 18 BLDL is an effective NOP for LINKLIBs and JOBLIBs. For TXTLIBs and MACLIBs, item numbers are filled in the TTR field of the BLDL list. The K, Z, and user data fields, as described in DS/VS Data Management Macro Instructions, are set to zeroes. The "alias" bit of the C field is supported, and the remaining bits in the C field are set to zero. Chapter 8. Developing OS Programs under CMS 193 FIND-SVC 18 All the options of FIND are supported. FIND sets the read/write pointer to the item number of the specified member. STOW-SVC 21 All the options of STOW are supported. The "alias" bit is supported, but the user data field is not stored in the MACLIB directory since CMS MACLIBs do not contain user data fields. When using the STOW macro's ADD directory function without closing and reopening the data set after each new member is added, the CLOSE macro must be issued within each multiple of 256 new members. The existing number of entries does not need to be known before the ADD function is started. OPEN/OPENJ-SVC 19/22 All the options of OPEN and OPENJ are supported except for the DISP, EXTEND, and RDBACK options, which are ignored. OPEN creates a CMSCB (if necessary), completes the DCB, and merges necessary fields of the DCB and CMSCB. CLOSE/TCLOSE(CLOSE TYPE = T)-SVC 20/23 All the options of CLOSE and TCLOSE are supported except for the DISP option, which is ignored. The DCB is restored to its condition before OPEN. If the device type is disk, the file is closed. If the device type is tape, the REREAD option is treated as a REWIND. For TCLOSE, the REREAD option is REWIND, followed by a forward space file for tapes with standard labels. DEVTYPE-SVC 24 With the exception of the RPS option, which CMS ignores, CMS accepts all options of the DEVTYPE macro instruction. In supporting this macro instruction, CMS groups all devices of a particular type into the same class. For example, all printers are grouped into the printer class, all tape drives into the tape drive class, and so forth. In response to the DEVTYPE macro instruction, CMS provides the same device characteristics for all devices in a particular class. Thus, all devices in a particular class appear to be the same device type. The device type characteristics CMS returns for each class are: 194 Class Device Characteristics Printer Virtual reader Console 1403 2540 1052 VM/SP eMS for System Programming [G GY\J 0 ~ (u ~~) uu-u ~J . ____ ___: " __ [_~ _~ ~: ~~ __ .__ ___ ~~ __ .~.~_~::..,~:-:,====~_,::=_~==:,,:~~~~~~,:,, =-_,:,,~_. Tape drive DASD Virtual punch DUMMY unassigned ([) ~~ ~J U'QJ U[j"tJ ljU"J rJ _'"_.~~-___ " '_-=~~-~-=~':'~~-==~.~~-':_' __ J 2400 (9 track) 2314 2540 2314 2314 TRKBAL-SVC 25 The TRKBAL routine in CMS is a NOP. It returns control to the user. FEOV-SVC 31 Control is returned to CMS with an error code of 4 in register 15. WTO/WTOR-SVC 35 All options of WTO and WTOR are supported except those options concerned with multiple console support. WTO displays a message at the operator's console. WTOR displays a message at the operator's console, waits for a reply, moves the reply to the specified area, sets a completion bit in the specified ECB, and returns. There is no check made to determine if the operator provides a reply that is too long. The reply length parameter of the WTOR macro instruction specifies the maximum length of the reply. The WTOR macro instruction reads only this amount of data. EXTRACT-SVC 40 The EXTRACT routine in CMS is essentially a NOP. The user-provided answer area is set to zeroes and control is returned to the user with a return code of 4 in register 15. IDENTIFY-SVC 41 The IDENTIFY routine in CMS adds a REQUEST block to the load request chain for the requested name and address. ATTACH-SVC 42 All the options of ATTACH are supported in CMS as in OS PCP. The following options are ignored by CMS: DCB, LPMOD, DPMOD, HIARCHY, GSPV, GSPL, SHSPV, SHSPL, SZERO, PURGE, ASYNCH, and TASKLIB. ATTACH passes control to the routine specified, fills in an ECB completion bit if an ECB is specified, passes control to an exit routine if one is specified, and returns control to the instruction following the ATTACH. Since CMS is not a multitasking system, a phase requested by the ATTACH macro must return to CMS. CHAP-SVC 44 The CHAP routine in eMS is a NOP. It returns control to the user. Chapter 8. Developing OS Programs under CMS 195 EJ)Gt'1G~(})~]DUilQl 08 L]~'(i)G~U1@fJuuS r------TTIMER-SVC 46 All the options of TTIMER are supported. STIMER-SVC 47 All options of STIMER are supported except for TASK and WAIT. The TASK option is treated as if the REAL option had been specified, and the WAIT option is treated as a Nap; it returns control to the user. The maximum time interval allowed is X'7FFFFFOO' timer units (or 15 hours, 32 minutes, and 4 seconds in decimal). If the time interval is greater than the maximum, it is set to the maximum. If an STIMER is issued and later the virtual machine is put into a wait state, the virtual timer is not updated unless prior to this the CP command SET TIMER REAL was issued or the REALTIMER option was specified in the VM/SP directory entry of the virtual machine. Note: If running in the CMSBATCH environment, issuing the STIMER or TTIMER macro affects the CMSBATCH time limit. Depending on the frequency, number, and duration of STIMERs and/or TTIMERs issued, the CMSBATCH limit may never expire. DEQ-SVC 48 The DEQ routine in CMS is a Nap. It returns control to the user. SNAP-SVC 51 Except for SDATA, PDATA, and DCB, all options of the SNAP macro are processed normally. SDATA and PDATA are ignored. Processing for the DCB option is as follows. The DBC address specified with SNAP is used to verify that the file associated with the DCB is open. If it is not open, control is returned to the caller with a return code of 4. If the file is open, then storage is dumped (unless the FCB indicates a DUMMY device type). SNAP always dumps output to the printer. The dump contains the PSW, the registers, and the storage specified. ENQ-SVC 56 The ENQ routine in CMS is a Nap. It returns control to the user. FREEDBUF-SVC 57 All the options of FREEDBUF are supported. FREEDBUF returns a buffer to the buffer pool assigned to the specified DCB. STAE-SVC 60 196 VM/SP eMS for System Programming All the options of ST AE are supported except for the XCTL option, which is set to XCTL=YES; the PURGE option, which is set to HALT; and the ASYNCH option, which is set to NO. STAE creates, overlays, or cancels a STAE control block as requested. STAE retry is not supported. " " .; ~J " ] DETACH-SVC 62 The DETACH routine in CMS is a Nap. It returns control to the user. CHKPT-SVC 63 The CHKPT routine is a Nap. It returns control to the user. RDJFCB-SVC 64 All the options of RDJFCB are supported. RDJFCB causes a job file control block (JFCB) to be read from a CMS control block (CMSCB) into real storage for each data control block specified. FILEDEF commands create CMSCBs. Additional information regarding CMS 'as Simulation' of RDJFCB follows: o The DCBs specified in the RDJFCB PARAMETER LIST are processed sequentially as they appear in the parameter list. o On return to the caller, a return code of zero is always placed in register 15. If an abend occurs, control is not returned to the caller. o Abend 240 occurs if zero is specified as the address of the area into which the JFCB is to be placed. o Abend 240 occurs if a JFCB EXIT LIST ENTRY (Entry type X'07') is not present in the DCB EXIT LIST for any one of the DCBs specified in the RDJFCB PARAMETER LIST. o If a DCB is encountered in the parameter list with zero specified as the DCB EXIT LIST ('EXLST') address, the RDJFCB immediately returns with return code zero in register 15. Except for this situation, all of the DCBs specified in the RDJFCB PARAMETER LIST are processed, unless an abend occurs. o For a DCB that is not open, a search is done for the corresponding FILEDEF or DLBL. If one is not found, a test is done to determine if a file exists with a filename of 'FILE', a filetype of the DDNAME from DCB, and a filemode of 'AI'. If such a file does exist, then X'40' is placed in the JFCB at displacement X'57' (FLAG' JFCOLD IN FIELD' JFCBIND2'). If such a file does not exist then X'CO' (FLAG 'JFCNEW') will be in field 'JFCBIND2'. o For a file that is not open, but for which a DLBL has been specified, X'OB' is placed in the JFCB at Chapter 8. Developing as Programs under CMS. 197 L _._._....____.____• - - - - - . - ( J ' . - - - -..---.---.. - - - - - - -..------------------.--___ J displacement X'63' (field 'JFCDSORG' byte 2) to indicate that it is a VSAM file. SYNADAF-SVC 68 All the options of SYNADAF are supported. SYNADAF analyzes an I/O error and creates an error message in a work buffer. SYNADRLS-SVC 68 All the options of SYNADRLS are supported. SYNADRLS frees the work area acquired by SYNAD and deletes the work area from the save area chain. BSP-SVC 69 All the options of BSP are supported. BSP decrements the item pointer by one block. TGET/TPUT-SVC 93 TGET and TPUT operate as if EDIT and WAIT were coded. TGET reads a terminal line. TPUT writes a terminal line. TCLEARQ-SVC 94 TCLEARQ in CMS clears the input terminal queue and returns control to the user. STAX-SVC 96 The only option of STAX that is supported is EXIT ADDRESS. STAX updates a queue of CMTAXEs each of which defines an attention exit level. PGRLSE-SVC 112 Release all complete pages (4K bytes) associated with the area of storage specified. CALL The CALL macro is supported by CMS. The CALL macro transfers control to a control section at a specified entry. NOTE All the options of NOTE are supported. NOTE returns the item number of the last block read or written. POINT All the options of POINT are supported. POINT causes the control program to start processing the next read or write operation at the specified item number. The TTR field in the block address is used as an item number. CHECK All the options of CHECK are supported. CHECK tests the I/O operation for errors and exceptional conditions. DCB The following fields of a DCB may be specified relative to the particular access method indicated: / 198 VM/SP eMS for System Programming lDG\JG~Of)~uuU 08 ~Ju·OOU·8Ul{~S ----"-"._-"-----.....:~~=-====.:....-==:-----.-] r- _.. -. ----.- --.. _._-- Operand BDAM BPAM BSAM QSAM BFALN BLKSIZE BUFCB BUFL BUFNO DDNAME DSORG EODAD EXLST KEYLEN5 LIMCT LRECL MACRF OPTCD RECFM SYNAD NCP F,D n(number) a(address) n n s(symbol) DA F,D n a n n s PO a a F,D n a n n s PS a a n F,D n a n n s PS a a n R,W n R,W,P n G,P,L,M J J F,V,B,S,A,M,U a n F,V,B,U,A,M,S a a n n R,W A,E,F,R F,V,U a F,V,U, a n Access Method Support An access method governs the manipulation of data. To facilitate the execution of as code under CMS, the processing program must see data as as would present it. For instance, when the processors expect an access method to acquire input source cards sequentially, CMS invokes specially written routines that simulate the as sequential access method and pass data to the processors in the format that the as access methods would have produced. Therefore, data appears in storage as if it had been manipulated using an as access method. For example, block descriptor words (BDW), buffer pool management, and variable records are updated in storage as if an as access method had processed the data. The actual writing to and reading from the I/O device is handled by CMS file management. Note that the character string X'61FFFF61' is interpreted by CMS as an end of file indicator. The essential work of the volume table of contents (VTOC) and the data set control block (DSCB) is done in CMS by a master file directory (MFD) and a file status table (FST). A MFD updates the disk contents, and a FST describes each data file. All disks are formatted in physical blocks of 512, 800, 1024, 2048, or 4096 bytes. CMS continues to update the as format, within its own format, on the auxiliary device for files whose filemode number is 4. That is, the block and record descriptor words (BDW and RDW) are written along with the data. If a data set consists of blocked records, the data is written to and read from the I/O device in physical blocks rather than logical records. CMS also simulates the specific methods of manipulating data sets. 5 If an input data set is not a BDAM data set, zero is the only value that should be specified for KEYLEN. This applies to the user exit lines as well as to the DCB macro instruction. Chapter 8. Developing OS Programs under CMS 199 , Ej\Q t7C' ~ Q'lr XED I T 1 File \. ....,. 1 "" .J Figure 24. Sample MACLIST Screen Finding Members in Your MACLIST List If there are many members in the maclib, the list may take up more than one screen. To find a member in your MACLIST list, you can do any of the following: o o 232 Scroll through the list using the PF keys. PF7 Scrolls backward one full screen. PF8 Scrolls forward one full screen. Rearrange the list using one of the following PF keys: PF4 Sorts the list by member name. This is how the list is initially arranged. PF5 Sorts the list by index (largest first). The most recently updated members will have a greater number. PF6 Sorts the list by size (largest to smallest). • Use the XEDIT subcommand LOCATE if you know the member name that you are looking for. e Rearrange the list by entering one of the following synonyms on the command line. VM/SP eMS for System Programming _ _ __' C=~== :_~=_' [G~J'U(J~C:.")~-)~u-uCJ \'J8L~ lJ[j'I~CJU1[}O~~O _'~=~=_,~:,:~=~~_~::,:,~:~~",:~~~~~~::,:, __~,:"-,,,:. . ___ ~=~~,,~:_~:~===.~.=~~=:'::=~:::==-'-:-~,~=~=~:::"::'~=.::J SINDEX Sorts the list by index (greatest to least) within a library. SLIB Sorts the list alphabetically by library fileid. SNAME Sorts the list alphabetically by member name. This is how the list is initially arranged. SSIZE Sorts the list by member size (number of records, greatest to least). Entering Commands In the MACLIST Environment You can type commands that operate on member names in the list directly on the lines of the MACLIST display. When you press the ENTER key, all commands typed on the lines in the file displayed on the current screen are executed. Symbols can be used to represent operands in the command to be executed. Symbols are needed if the command to be executed has operands or options that follow the fileid. For example to issue the PRINT command for this member of your MACLIST: NEUTRAL 266 5 MYLIB MACLIB Al type directly on the line that contains this member as follows: print /EUTRAL 266 5 MYLIB MACLIB Al and then press the ENTER key. Refer to the MACLIST command in the VM/ SP CMS Command Reference for more information about using symbols in MACLIST. Another way to issue commands that make use of member names displayed is to move the current line to the first (or only) member you want the command to use. Then issue EXECUTE (in the form "EXECUTE lines command") from the XEDIT command line. This method may be used on both display and typewriter terminals. You can also enter commands from the MACLIST command line. Editing a Maclib Member: The MACLIST command allows you to select and edit a CMS maclib member from the list. To edit a member, position the cursor on the line that contains the member to be edited and press the PFll key. Otherwise, you can edit a CMS maclib member by using the XEDIT command with the MEMBER option. For example, to edit the SWERVE member of MYLIB maclib, enter: xedit mylib maclib al (member swerve If the SWERVE member did not exist in MYLIB MACLIB, a new file is created with a fileid of SWERVE MEMBER AI. Chapter 9. Developing VSE Programs under eMS 233 l Adding and Replacing Maclib Members: When the MEMBER option is specified for the XEDIT command for a member that does not exist in the library, a new file is created with the fileid of "membername MEMBER fm". If the MEMBER option is specified on the XEDIT command for an existing member of a library, the member is read into a file called "membername MEMBER fm" for you to edit. When you issue FILE or SAVE for the new or changed member, the library directory is updated. The new or changed member and the updated library directory are added to the end of the library. If the directory already contains a member with the same name as the one being saved, the old entry is blanked out, so that the updated member replaces the old version. Deleting Maclib Members: Use the DISCAED command to delete a member from a library. DISCARD is equivalent to the CMS command MACLIB DEL. DISCARD can either be typed in the command area of the line that describes the member you want discarded, or it can be entered from the command line (at the bottom of the screen). DISCARD can only be used while in the FILELIST, RDRLIST, MACLIST, and PEEK command environments. Setting MACLIST Defaults: When XEDIT is invoked by the MACLIST command to display the list, the default XEDIT macro, PROFMLST XEDIT, is executed. If you want to invoke a different XEDIT macro, you can specify the PROFILE option with the MACLIST command. For example, to invoke MACLIST with the MYMCLST XEDIT macro, enter rnaclist rnylib (profile rnyrnclst You can do the same with the COMPACT and NOCOMPACT options of the MACLIST command. If you are using an alternate profile most of the time, you may change the default profile with the DEFAULTS command. For example: defaults set rnaclist profile rnymclst Entering the DEFAULTS command with no options provides you with the status of defaults currently in effect. For example, entering defaults after changing the XEDIT macro, returns the following information: 234 VMjSP OMS for System Programming [GGU8~O~)DuJ[J VGl: c . -.-.---- . -.. -...-.-------:-.-----.-.--------.....-_. __.____.____ u_.._..________ .___.__ ...____ ..__ .__ . _____ ·.·_u· ____ ········ __ ·... -... ----.--.-.- ...- ~-)G~O[Ju'c1ulr~G ... - ......... --.- .... --.-..... -.-....... -.. - .... ] The following default options have been set: Filelist options = PROFILE PROFFLST NOFILELIST Help options = SCREEN BRIEF ALL Maclist options = PROFILE MYMCLST NOCOMPACT Note options = PROFILE PROFNOTE SHORT LOG NOACK NOTEBOOK ALL Peek options = PROFILE PROFPEEK FROM 1 FOR 200 Rdrlist options = PROFILE PROFRLST Receive options = LOG OLDDATE NOTEBOOK ALL Sendfile options = NEW TYPE NOFILELIST LOG NOACK Tell options = MSGCMD MSG To change any default options enter DEFAULTS Set Cmdname Optl The GLOBAL Command When you want to assemble a source program that uses macro or copy definitions, you must ensure that the library containing the code is identified before you invoke the assembler. Otherwise, the library is not searched. You identify libraries to be searched using the GLOBAL command. For example, if you have two MACLIBs that contain your private macros and copy files whose names are TESTMAC MACLIB and TESTCOPY MACLIB, you would issue the command: global mac lib testmac testcopy The libraries you specify on a GLOBAL command line are searched in the order you specify them. A GLOBAL command remains in effect for the remainder of your terminal session, until you issue another GLOBAL MACLIB command or until you IPL CMS. To find out what macro libraries are currently available for searching, issue the command: query maclib You can reset the libraries or the search order by reissuing the GLOBAL command. System MACLIBs The macro libraries that are on the system disk contain CMS and OS assembler language macros you may want to use in your programs. The MACLIBs are: o CMSLIB MACLIB contains the CMS macros from VM/370. o DMSSP MACLIB contains macros that are new or changed in VM/SP. Note: When assembling programs that use CMS macros, both of these libraries should be identified via the GLOBAL command. DMSSP should precede CMSLIB in the search order. o DOSMACRO MACLIB contains macros used internally by CMS/DOS. Chapter 9. Developing VSE Programs under CMS 235 c:-______ .___.._. _ _ . . . _.......". _._ ......_"_____ ~==::-:=:-:-~~:=~.-~'.- - . _-_. .-._---------------_. __ . _----_._. -._---_._-.._-----_._--_._._------_._J Note: These macros should not be used in user written programs. To assemble programs that use VSE macros, you should follow the procedures as previously described in this chapter. o OSMACRO MACLIB, OSMACROI MACLIB, and TSOMAC MACLIB are used by OS programmers. o DMKSP MACLIB contains macros that support CPo o OSVSAM MACLIB contains the subset of supported OS/VSAM macros. To obtain a list of macros in any of these libraries, use either the MACLIST command or the MACLIB command with the MAP function. In the MACLIST environment, you can issue CMS commands against the members directly from the displayed list. You can find the MACLIST command description in the VM/ SP CMS Command Reference. When you use VSAM on CMS and write programs using VSE/VSAM macros, you can build a VSE/VSAM maclib by issuing the CMS VSEVSAM command. The maclib contains the supported VSE/VSAM macros and the following VSE macros: CDLOAD CLOSE CLOSER GET OPEN OPENR PUT Refer to the VM/ SP Installation Guide for the CMS VSEVSAM command documentation. VSE Assembler Language Macros Supported Figure 25 on page 237 lists the VSE assembler language macros supported by CMS/DOS. You can assemble source programs that contain these macros under CMS/DOS, provided that you have the macros available in either your own or a shared CMS macro library. The macros whose functions are described in the "Function" column with the term "no-op" are supported for assembly only; when you execute programs that contain these macros, the VSE functions are not performed. To accomplish the macro function you must execute the program on a real VSE system. 236 VM/SP eMS for System Programming [_ . . _..___ . _. _._..... _... _ . .___.........___ .n__ ... ____. _._. . _. .__ ._. r,:I~cro NunllJm' CANCEL CDLOAD 06 65 CHECK DEQ DTFxx DUMP ENQ EOJ ERET EXCP EXIT PC EXIT AB EXTRACT FCEPGOUT FETCH FREE FREEVIS GENL GET GETFLD/ MODFLD GETVCE GETVIS GETIME JDUMP LOAD LOCK/ UNLOCK MVCOM .. . -.. .'_'_.'____ . ." __'_' __"_'__.-- ._. ___. .__. ._. _ .._. __ ... _. . ~-_--._ ---:.:...~__.-_.n~=::._- . __.~.~~_ .:....~ svc NnnlC CALL CLOSEt CLOSER CNTRL COMRG' ..-._. _... _~~~~:.:_ 33 41 42 14 00 17 95 98 86 01 02 36 62 107 99 61 34 Ii'unction Pass control to another program Terminate processing Load a VSAM phase Verify completion of a read or write operation Deactivate a data file Control a physical device Return address of background partition communication region no-op Establish file definitions Dump storage and registers and terminate processing no-op Terminate processing normally Provide an error routine Execute a channel program Return from program check routine Return from abnormal termination routine Retrieve PUB, storage boundaries, or CPUID information no-op Load and pass control to a phase Load and pass control to a logical transient no-op Release user free storage Generate a phase directory list Access a sequential file Provide macro interface support for system information retrieval. Return requested device information to output area. Obtain user free storage Get the time of day Dump storage and registers and terminate processing 04 110 Resource control 05 Modify bytes in the partition communication region NOTE OPEN/OPENR Figure 25 (Part 1 of 2). Load a phase into storage Manage data set access Activate a data file VSE Macros Supported by eMS Chapter 9. Developing VSE Programs under CMS 237 Macro Name PAGEIN PDUMP PFIX PFREE POINTR POINTS POINTW POST PRTOV PUT PUTR READ RELPAG RELSE RETURN RUNMODE SECTVAL SETIME SETPFA STXIT AB STXIT PC STXIT IT STXIT OC SUB SID TRUNC TTIMER WAIT WRITE xxMOD SVC Number 87 67 68 40 85 66 75 10/24 71 37 16 20 18 105 52 07 Figure 25 (Part 2 of 2). Function no-op Dump storage and registers and continue processing no-op no-op Position a file for reading Reposition a file to its beginning Position a file for writing Post the event control block Control printer overflow Write to a sequential file Communicate with the system operator Access a sequential file no-op Skip to begin reading next block Return control to calling program Check if program is running real or virtual Obtain a sector number no-op no-op Provide or terminate linkage to abnormal ending routine Provide or terminate linkage to program check routine no-op no-op Retrieve information on supervisor subsystem Skip to begin writing next block Return a 0 in Register 0 (effectively a no-op) Wait for the completion of I/O Write to a sequential file Create Logical IOCS routine in line VSE Macros Supported by eMS Assembling Source Programs If you are a DOS assembler language programmer using CMS/DOS, you should be aware that the assembler used is the VM/SP assembler, not the DOS assembler. The major difference is that the VM/SP assembler, invoked by the ASSEMBLE command, is designed for interactive use. Therefore, when you assemble a program, error messages are displayed at your terminal when compilation is completed, and you do not have to wait for a 238 VM/SP eMS for System Programming lDeve~@rjnu1)~ ~§~ ~~)U~(Q)DUAC1u~uS c -------------------------------- ----------------------] printed listing to see the results. You can correct your source file and reassemble it immediately. Then you can print the listing error free. To specify options to be used during the assembly, you enter them on the ASSEMBLE command line. So, for example, if you do not want the output LISTING file placed on disk, you can direct it to the printer: assemble myfile (print All of the ASSEMBLE command options are listed in VM/ SP CMS Command Reference. When you invoke the ASSEMBLE command specifying a file with a filetype of ASSEMBLE, CMS searches all of your accessed disks, using the standard search order, until it locates the file. When the assembler creates the output LISTING and TEXT files, it writes them onto disk according to the following priorities: 1. If the source file is on a read/write disk, the TEXT and LISTING files are written onto the same disk. 2. If the source file is on a read-only disk that is an extension of a read/write disk, the TEXT and LISTING files are written onto the parent disk. 3. If the source is on any other read-only disk, the TEXT and LISTING files are written onto the A-disk. In all of the above cases, the filenames assigned to the TEXT and LISTING files are the same as the filename of the input file. The output files used by the assembler are defined via FILEDEF commands issued by CMS when it calls the assembler. If you issue a FILEDEF command using one of the assembler ddnames before you issue the ASSEMBLE command, you can override the default file definitions. The ddname for the source input file is ASSEMBLE. If you enter: filedef assemble reader assemble sample then the assembler reads your input file from your card reader, and assigns the filename SAMPLE to the output TEXT and LISTING files. You can use this method to assemble programs directly from DOS sequential files on DOS disks. For example, to assemble a source file named DOSPROG from a DOS disk accessed as a C-disk, you could enter: filedef assemble c dsn dosprog (recfm f lrecl 80 assemble dosprog Again, the name you assign on the ASSEMBLE command may be anything. The assembler uses this name to assign filenames to the TEXT and LISTING output files. Chapter 9. Developing VSE Programs under CMS 239 D)O\7G~0)fVUDufj V8~ [)U @0jltG1mO 1 --_.-._-.-::--:--:-1 r- LISTING and TEXT are the ddnames assigned to the SYSLST and SYSPCH output of the assembler. You might issue file definitions to override these defaults as follows: filedef listing disk assemble listfile a filedef text disk assemble textfile a assemble source When these commands are executed, the output from the assembly of the file SOURCE ASSEMBLE is written to the disk files ASSEMBLE LISTFILE and ASSEMBLE TEXTFILE. Link-editing Programs in eMS/DOS When the assembler or one of the language compilers executes, the object module produced is written to a CMS disk in a file with a filetype of TEXT. The filename is always the same as that of the input source file. These TEXT files (sometimes referred to as decks, although they are not real card decks) can be used as input to the linkage editor or can be used with an INCLUDE linkage editor control statement. You can invoke the CMS/DOS linkage editor with the DOSLKED command, for example: doslked test testlib where TEST is the filename of either a DOSLNK or TEXT file (that is, a file with a filetype of either DOSLNK or TEXT) or the name of a relocatable module in a system or privaterelocatable library. TESTLIB indicates the name of the output file which, in CMS/DOS, is a phase library with a filetype of DOSLIB. When you issue the DOSLKED command: 1. CMS first searches for a file with the specified name and a filetype of DOSLNK. 2. If none is found, CMS searches the private relocatable library, if you have assigned one. You must issue an ASSGN command for SYSRLB and use the ddname IJSYSRL in a DLBL statement. 3. If the module is still not found, CMS searches all of your accessed disks for a file with the specified name and a filetype of TEXT. 4. 240 Last, CMS searches the system relocatable library, if it is available. You must enter the CMS/DOS environment specifying the mode letter of the DOS system residence if you want to access the system libraries. VM/SP eMS for System Programming L· .. Linftage Editor Input You can place the linkage editor control statements ACTION, PHASE, INCLUDE, and ENTRY in a CMS file with a filetype of DOSLNK. When you use the INCLUDE statement, you may specify the filename of a CMS TEXT file or the name of a module in a DOS relocatable library: INCLUDE XYZ or you may use the INCLUDE control statement to indicate that the object code follows: INCLUDE (CMS TEXT file) A typical DOSLNK file, named CONTROL DOSLNK, might contain the following: ACTION REL PHASE PROGMAIN,S INCLUDE SUBA PHASE PROGA,* INCLUDE SUBB When you issue the command: doslked control the linkage editor searches the following for the object files SUBA and SUBB: o A DOS private relocatable library, provided you have issued the ASSGN and DLBL commands to identify it: assgn sysrlb d dlbl ijsysrl d dsn ? (sysrlb o Your CMS disks for files with filenames SUB A and SUBB and a filetype of TEXT o The system relocatable library located on the DOS system residence volume (if it is available). Unlc-editing TEXT Files When you want to link-edit individual CMS TEXT files, you can insert linkage editor control statements in the file using the editor and then issue the DOSLKED command: xed it rtnb text input include rtnc file doslked rtnb mydoslib When the above DOSLKED command is executed, the CMS file RTNB TEXT is used as linkage editor input, as long as there is no file named Chapter 9. Developing VSE Programs under' eMS 241 RTNB DOSLNK. The ACTION statement, however, is not recognized in TEXT files. You can also link-edit relocatable modules directly from a DOS system or private relocatable library, provided that you have identified the library. If you do this, however, you cannot directly provide control statements for the linkage editor. To link-edit a relocatable module from a DOS private library and add linkage editor control statements to it, you could use this procedure: 1. Identify the library and use the RSERV command to copy the relocatable module into a CMS TEXT file. In this example, the module RTNC is to be copied from the library OBJ.MODS: assgn sysrlb e dlbl ijsysrl e dsn obj mods (sysrlb rserv rtnc 2. Create a DOSLNK file, insert the linkage editor control statements, and copy the TEXT file created in step 1 into it using the GET subcommand: xedit rtnc doslnk input action reI get rtnc text a file 3. Invoke the linkage editor with the DOSLKED command: doslked rtnc mydoslib Alternatively, you could create a DOSLNK file with the following records: DOSLNK file ACTION REL INCLUDE RTNC and link-edit the module directly from the relocatable library. If you do not need a copy of the module on a CMS disk, you might want to use this method to conserve disk space. When the linkage editor is reading modules, it may encounter a blank card at the end of a file or a * (comment) card at the beginning of a file. In either case, the linkage editor issues a warning message indicating an invalid card, but it continues to complete the link-edit. Linkage Editor Output: eMS DOSLIBs The CMS/DOS linkage editor always places the link-edited executable phase in a CMS library with a filetype of DOSLIB. You should specify the filename of the DOSLIB when you enter the DOSLKED command: doslked progO temp lib 242 VM/SP eMS for System Programming _ _ _ ""- .. -:_""._".""_~_""_" ____.::_. ____ ~".___"__ .:....:..:.:.:.._.:. __ ..:....:_. __ ... ____"~~"_""_. ___ ":~_~~~':'::__.~.J where PROGO is the relocatable module you are link-editing and TEMPLIB is the filename of the DOSLIB. If you do not specify the name of a DOSLIB, the output is placed in a DOSLIB that has the same name as the DOSLNK or TEXT file being link-edited. In the above example, a CMS DOSLIB is created named TEMPLIB DOSLIB, or, if the file TEMPLIB DOSLIB already exists, the phase PROGO is added to it. DOSLIBs can contain relocatable core image phases suitable for execution in CMS/DOS. Before you can access phases in them, you must identify them to CMS with the GLOBAL command: global doslib temp lib permlib When CMS is searching for executable phases, it searches all DOSLIBs specified on the last GLOBAL DOSLIB command. If you have named a number of DOSLIBs or if any particular DOSLIB is very large, the time required for CMS to fetch and execute the phase increases. You should use separate DOSLIBs for executable phases, whenever possible. Then specify only the DOSLIBs you need on the GLOBAL command. When you link-edit a module into a DOSLIB that already contains a phase with the same name, the directory entry is updated to point to the new phase. However, the space that was occupied by the old phase is not reclaimed. You should periodically issue the command: doslib comp temp lib to compress the DOSLIB and delete unused space. TEMPLIB is the filename of the DOSLIB. Linlcage Editor Maps The DOSLKED command also produces a linkage editor map. It writes into a CMS file with a filename specified on the DOSLKED command line and a filetype of MAP. The filemode is always A5. If you do not want a linkage editor map, use the NOMAP option on the ACTION statement in a DOSLNK file. EJtecuiing Programs in eMS/toOS After you have assembled or compiled a source program and link-edited the TEXT files, you can execute the phases in your CMS virtual machine. You may not, however, be able to execute all your DOS programs directly in CMS. There are a number of execution-time restrictions placed on CMS/DOS programs. You cannot execute a program that uses: o o o o Multi tasking More than one partition Teleprocessing ISAM macros to read or write files Chapter 9. Developing VSE Programs under CMS 243 [Q)GUG~(i]f.uo~ug V~~ [Du1@~?JU~@uuuG c_._.__________ ._~:.._..... ______.________._.________.____. __ .__ ... • • ......-.. -..._. _. . --- . ----_.._. . _. _.... __._---_ . . _--------------J CMS module files created by DOS programs EC mode PSW s. The above is only a partial list representing those restrictions with which you might be concerned. For a complete list of restrictions, see the VM/SP Planning Guide and Reference. See also the usage notes of the FETCH command in the VM/ SP CMS Command Reference. Executing DOS Phases You can load executable phases into your CMS virtual machine using the FETCH command. Phases must be link-edited with ACTION REL before you load them. When you issue the FETCH command, you specify the name of the phase to be loaded: fetch myprog Then you can begin executing the program by issuing the START command: start Or, you can fetch a phase and begin executing it with a single command: fetch prog2 (start When you use the FETCH command without the START option, CMS issues a message telling you at what virtual storage address the phase is loaded: PHASE PROG2 ENTRY POINT AT LOCATION 020000 Location X'20000' is the starting address of the user program area for CMS. Relocatable phases are always loaded starting at this address unless you specify a different address using the ORIGIN option of the FETCH command: fetch prog3 (origin 22000 start The program PROG3 executes beginning at location 22000 in the CMS user program area. Search Order for Executable Phases When you execute the FETCH command, CMS searches for the phase name you specify in the following places: 1. In a DOS private core image library on a DOS disk. If you have a private library you want searched for phases, you must identify it using the ASSGN and DLBL commands using the logical unit SYSCLB: assgn sysclb d dlbl ijsyscl d dsn ? (sysclb 244 VM/SP eMS for System Programming [i··~C:YUC;~~)~)UO·JCJ \,!/S~ lJu'(GOu'~1U'"~JG l~~.~ __ '::':~_·_·-_.':~:":'::'~:':.=_~_~._ ... __ ~:.':'_.:: ___ .__ ":':":':=_-':' __~'::':-=- __ . _-, .__. ___ :':"_~~':'_._":_~:_~~_._ __ --.------- .----.-----.---.-. ..:.:.:.:..:.=~ ------------.=.J When you enter the DLBL command with the? operand, you are prompted to enter the DOS file-ide 2. In CMS DOSLIBs on CMS disks. If you want DOSLIBs searched for phases, you must use the GLOBAL command to identify the DOSLIBs to CMS/DOS: global doslib temp lib mylib You can specify up to 63 DOSLIBs on the GLOBAL command line. 3. On the DOS system residence core image library. If you want the system core image library searched you must have entered the CMS/DOS environment specifying the mode letter of the system residence: set dos on z When you want to fetch a core image phase that has copies in both the core image library and a DOSLIB, and you want to fetch the copy from the CMS DOSLIB, you can bypass the core image library by entering the command: assgn sysclb ua When you need to use the core image library, enter: assgn sysclb c where C is the mode letter of the system residence volume. You do not need to reissue the DLBL command to identify the library. Making 110 Device Assignments If you are executing a program that performs I/O, you can use the ASSGN command to relate a system or programmer logical unit to a real I/O device: assgn syslst printer assgn sys052 reader In this example, your program is going to read input data from your virtual card reader. The output print file is directed to your virtual printer. If you want to reassign these units to different devices, you must be sure that the files have been defined as device independent. If you assign a logical unit to a disk, you should identify the file by using the DLBL command. On the DLBL command, you must always relate the DLBL to the system or programmer logical unit previously specified in an ASSGN command: assgn sys015 b dlbl myfile b dsn ? (sysOlS When you enter the DLBL command with the? operand you are prompted to enter the DOS file-ide Chapter 9. Developing VSE Programs under CMS 245 c:::______ --------------------------------------- ______________________.__:::J You must issue all of the ASSGN and DLBL commands necessary for your program's 1/0 before you issue the FETCH command to load the program phase and to begin executing. Specifying a Virtual Partition Size For most of the programs that you execute in CMS, you do not need to specify how large a partition you want those programs to execute in. When you issue the START command or use the START option on the FETCH command, CMS calculates how much storage is available in your virtual machine and sets a partition size. CMS calculates how much storage is available in the following manner: FREELOWE - (MAINHIGH + (4096 * FRERESPG» where: FREELOWE equals the low extent of allocated storage obtained from the top of virtual storage downwards via the DMSFREE system request. MAINHIGH equals the high extent of allocated storage obtained from the low virtual storage upwards via the GETVIS user request for storage. FRERESPG equals the amount of storage to be reserved for subsequent system requests, in pages. In some instances, you may want to control the partition size: o For performance considerations o Because the default may not leave enough free storage to satisfy the GETVIS requests issued by the DOS program or the access method services function being executed. You can set the partition size with the DOSP ART operand of the SET command. For example, after you enter the command: set dospart 300k all programs that you subsequently execute during this session execute in a 300K partition. In this way you can: 246 • Set a smaller partition size for programs that run better in smaller parti tions. o Set a smaller partition size to leave more free storage. If the reduction of the DOS partition does not free enough storage for the GETVIS requests, a larger virtual machine must be defined. If you enter: VM/SP eMS for System Programming ~ .. set dospart off CMS calculates a partition size when you execute a program. This is the default setting. Note: The CMS partition, unlike the DOS partition, is used only for the loading and executing of programs invoked by the FETCH or LOAD commands. Areas allocated by GETVIS are assigned addresses outside the partition but within the user's virtual machine. Setting the UPSI Byte If your program uses the user program switch indicator (UPSI) byte, you can set it by using the UPSI operand of the CMS SET command. The UPSI byte is initially binary zeros. To set it to ones, enter: set upsi 11111111 To reset it to zeros, enter: set upsi off Any value you set remains in effect for the duration of your terminal session unless you reload CMS (with the IPL command). Debugging Programs in CMS/DOS You can debug your DOS programs in CMS/DOS using the facilities of CP and CMS. By executing your programs interactively, you can determine the cause of an error or program abend, correct it, and attempt to execute a program again. The CP and CMS debugging facilities are described in VM Diagnosis Guide. Using EXEC Procedures in CMS/DOS During your program development and testing cycle, you may want to create EXEC procedures to contain sequences of CMS commands that you execute frequently. For example, if you need a number of MACLIBs, DOSLIBs, and DLBL definitions to execute a particular program, you might have an EXEC procedure as follows: Chapter 9. Developing VSE Programs under CMS 247 ITJ)QUG~@IT»U~uB ~f§~ [Jr(Q)~1~18mrils c==:~:-::=~====-_-=-...::: ___.__. __. _._. . _. _._. _. _._._._ ._ . ___._ . . __.__ . _._. ._. _________. ______. __ . _. . . ___ , _____. .__________.____________..____._."__._. . . .__.____J /* EXEC to set up environment to run program TESTA */ signal on error global maclib testlib dosmac assemble testa print testa listing doslked testa testlib global doslib test lib proglib access 200 e assgn sys010 e push dos.test3.stream.beta dlbl inddl e dsn ? '('sys010 assgn sysOll punch cp spool punch to '*' assgn sys012 a dlbl outfile a cms test data' ('sys012 signal off error fetch testa' ('start select when rc = 100 then do end when rc 200 then do end otherwise exit rc end Error: say 'Error occurred on line' sigl':' sourceline(sigl) exit rc The 'signal on error' control statement in the EXEC procedure ensures that if an error occurs during any part of the EXEC, the remainder of the EXEC does not execute, and the 'Error' displays the line number where the error occurred as well as the actual command which gave the error. Note: For the DLBL command entered with the DSN ? operand, you must stack the response (using 'push') before issuing the DLBL command. When your program is finished executing, the REXX special variable RC indicates the contents of general register 15 at the time the program exited (the 'Return Code'). You can use this value to perform additional steps in your EXEC procedure. Additional steps are indicated in the preceding example by ellipses. 248 VM/SP eMS for System Programming (0)C:YvG~~jIT)null[J -- ---_._._--_.- -- - --- -- -- - -- . - --- - -... ..- - ..- l18l2 [J u'\00u [}uJilG -- -- _. -- - .. - -- --- ... l ' -- --- ... -.-.......... -.- .... -._.......... _- -.--.:::~ Hardware Devices Supported CMS/DOS routines can read real DOS disks containing VSE data files and VSE private and system libraries. This read support is limited to the following disks supported by VSE: o o o o o o o o o o o IBM IBM IBM IBM IBM IBM IBM IBM IBM IBM IBM 2314 2319 3310 3330 3330 3340 3344 3350 3370 3375 3380 Direct Access Storage Facility Disk Storage Direct Access Storage Disk Storage, Models 1 and 2 Disk Storage, Model 11 Direct Access Storage Facility Direct Access Storage Direct Access Storage Direct Access Storage, Models AI, A2, B1, and B2 Direct Access Storage Direct Access Storage The following devices, which are supported by VSE, are not supported by CMS/DOS: o Card Readers: 1442, 2560P, 2560S, 2596, 3504, 5425P, and 5425S o Printers: 2560P, 2560S, 3203 Models 1 and 2,3525, 5203, 5425P, and 5425S o Disks: 2311. Also, CMS uses the CP spooling facilities and does not support dedicated unit record devices. Each CMS virtual machine supports only one virtual console, one reader, one punch, one printer, four tapes, and 26 disks. Programs that are executed in CMS/DOS are limited to the number of devices supported by CMS. VSE Supervisor and I/O Macros Supported by eMS/DOS CMS/DOS supports the VSE Supervisor macros and the SAM and VSAM I/O macros to the extent necessary to execute the DOS/VS COBOL . Compiler, the DOS PL/I Optimizing Compiler, and DOS/VS RPG II Compiler under CMS/DOS. CMS/DOS supports VSE Supervisor macros described in the publication VSE Macro Reference. Since eMS is a single-user system executing in a virtual machine with virtual storage, VSE operations, such as multi-tasking, that cannot be simulated in CMS' are ignored. The following information deals with the type of support that CMS/DOS provides in. the simulation of VSE Supervisor and Sequential Access Method I/O macros. For a discussion of VSAM macros, see the section "CMS Support for OS and VSE/VSAM Functions." Chapter 9. Developing VSE Programs under CMS 249 [IJ)G\7e~Q)~]UUU~l ~8~ ru fJ)fjr Dr . ~ [,\ r\n(~[-;;C)\\r; 0'1 \\fC:' r'Cl ~),~,,")UL ll[J ·,I[l\;l]l:,.. · ._.".,L~l \} LlU U\'.J \, lC.J" .\lJ\./l. "-.-~ ..-.---.-.. ---.-__:_---_::-----. . . . . -.. . . _. . . ._._._. _--===_.] recommended}. The actual disk used is not important as long as the macros are available when VSEVSAM is issued. 3. Issue the CMS VSEVSAM command. Respond to the questions when you are prompted. The seven VSE macros can be erased from the disk after the MACLIB is created because the macros will be in the MACLIB. Once you have created the MACLIB, you are able to assemble your VSAM assembler applications using the VSE/VSAM assembler macros in the MACLIB. The VSEVSAM EXEC is documented in the VM/ SP Installation Guide. VSE Supervisor Macros and Logical Transients Support for VSAM VSE supervisor macros required by VSE/VSAM are supported by CMS. See Figure 25 on page 237 for a complete list of supervisor macros supported. CMS distributes the VSE transients that are needed in the VSAM support. Thus, OS users do not need to have the VSE system pack on-line when they are compiling and executing VSAM programs. CMS uses all of the VSE B-transients except those that build and release extent blocks. The extent block is not supported in CMS and, thus, neither are the B-transients that control extent blocks. The CMSDOS shared segment contains the B-transients that are simulated for VSE support in CMS. The B-transients pertaining only to VSAM are included in the VSAM saved segment. Other VSE routines required by VSE/VSAM are contained in the CMSBAM shared segment. This includes the common VTOC handler routines, SAM data management, and the VSAM look-aside function. OS/VSAM Macros Supported in eMS A subset of the OS/VSAM macros are supported for use in CMS. The macros are at an MVS 3.8 level and they are contained in the OSVSAM MACLIB that is shipped with VM/SP. The macros are: ACB CHECK ENDREQ ERASE EXLST GENCB MODCB POINT RPL SHOWCB TESTCB Some options of the OS/VSAM macros do not work in CMS because OS/VSAM macro requests are executed using VSE/VSAM code. Figure 34 lists the OS/VSAM macros and the supported options. / 312 VMjSP eMS for System Programming OS/VSAM IVlacro Supporteu Options ACB AM=VSAM BUFND = number BUFNI = number BUFSP = number DDNAME = ddname MACRF=ADR, CNV, KEY, NOF, DIR, SEQ, SKP, IN, OUT, NRMIAIX, NRSIRST, NSR, NUB1UBF, CHECK RPL = address ENDREQ RPL = address ERASE RPL = address EXLST AM=VSAM EODAD = address JRNAD = address LERAD = address SYNAD = address GENCB BLK=ACB EXLST = address BUFND=number BUFNI = number BUFSP = number COPIES = number DDNAME = ddname MACRF=ADR, CNV, KEY, NOF, DIR, SEQ, SKP, IN, OUT, NRMIAIX, NRSIRST, NSR, NUBIUBF, LENGTH = number MAREA = address MLEN=number P ASSWD = address STRNO=number WAREA = address GENCB BLK=EXLST EODAD = address JRNAD = address LERAD = address SYNAD = address COPIES = number LENGTH = number WAREA = address GENCB BLK=RPL ACB = address AREA = address AREALEN = number ARG = address COPIES = number OPTCD =ADRICNVIKEY, DIRlsEQISKP, AROILRD, FwoIBWD, ASYlsYN, NSPINUpIUPD, KEQIKGE, ~KsIGEN, LOCIMVE, ECB = address KEYLEN = number LENGTH = number NXTRPL = address RECLEN = number Figure 34 (Part 1 of 3). EXLST = address MAREA = address MLEN = number P ASSWD = address STRNO=number WAREA~number Options of OS/VSAM Macros Supported in eMS Chapter 10. Using Access Method Services and VSAM under CMS and CMS/DOS 313 L __._______ _ __ _ _ _ _ _ _ _ _ _ _ _ _==:J OS/VSAM Macro Supported Options GET RPL = address MODCBACB BUFND=number BUFNI = number BUFSP = number DDNAME = ddname MACRF=ADR, CNV, KEY, NDF, DIR, SEQ, SKP, IN, OUT, NRMIAIX, NRSIRST, NSR, NUBIUBF, MODCB EXLST EODAD = address JRNAD = address LERAD = address SYNAD = address MODCBRPL ACB = address AREA = address AREALEN = number ARG = address OPTCD =ADRICNVIKEY, DIRISEQISKP, ARDILRD, FWDIBWD, ASYISYN, NSPINUPIUPD, KEQIKGE, FKSIGEN, LOCIMVE POINT RPL = address RPL ARG = address ECB = address KEYLEN=number NXTRPL = address RECLEN = number SHOWCBACB ACB = address AM=VSAM AREA = address AREALEN = number OPTCD=ADRICNVIKEY, DIRlsEOISKP, ARDILRD, FWDIBWD, ASYISYN, NSPINUpIUPD, KEOIKGE, FKSIGEN, LOCIMVE, AREA = address FIELDS = ACBLEN, AVSPAC, BUFND, BUFNI, BUFNO, BUFSP, CINV, DDNAME, ERROR, EXLST, FS, KEYLEN, LRECL, MAREA, MLEN, NCIS, NDELR, NEXCP, NEXT, NINSR, NIXL, NLOGR, NRETR, NSSS, NUPDR, PASSWD, RKP, STMST, STRMAX, STRNO SHOWCB EXLST AREA = address LENGTH = number EXLST = address MAREA = address MLEN = address P ASSWD = address STRNO=number ECB = address KEYLEN = number NXTRPL = address RECLEN = number OBJECT = DATAIINDEX LENGTH = number Figure 34 (Part 2 of 3). Options of OS/VSAM Macros Supported in eMS 314 VM/SP eMS for System Programming [----_._-----_._. __ ._--------------------_. - - - - - - - . - - _.. __ . __ ... _--_.- ..... - ----, Supported Options OS/VSAM Macro FIELDS = EODAD, EXLLEN, JRNAD,LERAD,SYNAD SHOWCBRPL AREA = address FIELDS=ACB, AIXPC, AREA, AREALEN,ARG,ECB,FDBK, FTNCD, KEYLEN, NXTRPL, RBA,RECLEN, RPLLEN LENGTH = number TESTCB ACB ERET = address OBJECT = DATAl INDEX ATRB=UNQ OFLAGS = OPEN OPENOBJ = PATHIBASEIAIX ACBLEN = number AVSPAC=number BUFND=number BUFNI = number BUFNO=number BUFSP = number CINV = number DDNAME = ddname ERROR = number EXLST = address FS=number KEYLEN = number ATRB=ESDS, KSDS, REPL, RRDS, SPAN, SSWD, WCK LRECL = number MAREA = address MLEN = number NelS = number NDELR = number NEXCP = number NEXT = number NINSR = number NIXL = number NLOGR=number NRETR=number NSSS = number NUPDR=number P ASSWD = address RKP=number STMST = address STRNO=number MACRF= ADR, AIX, CNV, DIR, IN, KEY, NDF, NRM, NRS, NSR, NUB, OUT, RST, SEQ, SKP,UBF TESTCB EXLST ERET = address EODAD = address JRNAD = address LERAD = address SYNAD = address EXLLEN=number TESTCB RPL ERET = address AIXFLAG = AIXPKP AIXPC=number FTNCD = number I/O = COMPLETE ACB = address AREA = address AREALEN = number OPTCD=ADR, ARD, ASY, BWD, CNV, DIR, FKS, FWD, GEN, KEQ, KEY, KGE, LOC, LRD, MVE, NSP, NUP, SEQ, SKP, SYN, UPD ARG = address ECB = address FDBK = number KEYLEN = number NXTRPL = address RBA=number RECLEN = number RPLLEN = number Figure 34 (Part 3 of3). Options of OS/VSAM Macros Supported in eMS Chapter 10. Using Access Method Services and VSAM under CMS and CMS/DOS 315 ~1J D 0uu Cj f\ L0J 8 [E L;~ V [~-==:::-=.::::==:::.== ElfJ'u c~ \f ~~ f':. ~tfJ ____ ._.__.__.______________.____.___.___._:. _____________________________===::::J OS/VSAM Error Codes Error codes returned by VSE/VSAM in response to OPEN, CLOSE, and Data Management Request macro errors are mapped to the appropriate OS/VSAM error codes. • Figure 35 lists the error codes returned by VSE/VSAM in response to OPEN errors. • Figure 36 on page 318 lists the error codes returned by VSE/VSAM in response to CLOSE errors. o Figure 37 on page 319 lists the error codes returned by VSE/VSAM in response to Data Management Request macro errors. If a VSE/VSAM error code cannot be mapped to any OS/VSAM error code, a CMS error message and an ABEND 35 are issued except for the cases indicated by an "*". The following table lists the VSE/VSAM to OS/VSAM error code mapping for OPEN errors: VSEjVSAI\(I Error Code 2 4 14 15 17 18 19 32 34 40 48 50 64 65 66 67 CIV1S Error IVlessage or OSjVSAM Error Code DMSVIP779E 4 DMSVIP782E DMSVIP782E DMSVIP782E DMSVIP782E DMSVIP782E DMSVIP782E DMSVIP782E* DMSVIP778E 168 DMSVIP782E 188 DMSVIP779E DMSVIP782E DMSVIP782E Figure 35 (Part 1 of 3). 316 VM/SP eMS for System Programming VSEjVSAlVl Return Code 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 OSjVSAM Return Code 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 VSE/VSAM to OS/VSAM Error and Return Code Mapping for OPEN Errors r-·-----·---------- ----------.----.---- ----. --- ...-.. -------.-- .-...... -... -..-.. "- --.- -----... -. ---. --.- . . VSE/VSAIVI Error Code 68 69 70 71 72 78 79 80 92 96 100 104 108 110 113 114 115 116 117 118 128 132 136 144 148 152 160 161 165 166 167 168 180 188 .---.. --- --..------.----.- ..--.------.. -..-... - -J CMS Error Message or OS/VSAM Error Code 168 DMSVIP782E DMSVIP782E DMSVIP782E 148 DMSVIP782E DMSVIP782E DMSVIP778E DMSVIP779E 96 100 104 108 160 144 DMSVIP781E DMSVIP781E 116 DMSVIP782E 0 128 132 136 144 148 152 160 160 DMSVIP782E DMSVIP782E DMSVIP782E 168 180 DMSVIP782E Figure 35 (Part 2 of 3). VSE/VSAM Return Code OS/VSAM Return Code 8 8 8 8 8 8 8 8 8 4 4 4 4 8 0 0 8 4 8 8 8 8 8 8 8 8 8 8 4 4 4 4 8 4 4 0 8 8 8 8 8 8 8 8 8 '8 8 8 8 8 8 4 8 0 8 8 8 8 8 8 8 8 8 8 8 8 8 8 VSE/VSAM to OS/VSAM Error and Return Code Mapping for OPEN Errors Chapter 10. Using Access Method Services and VSAM under CMS and eMS/DOS 317 l'J8Dul1~ AM8[E~V c.Hi)(~ V§AM c---'--- _____ :::J VSE/VSAM Error Code 192 196 212 216 220 228 232 248 254 255 CMS Error Message or OS/VSAIVI Error Code VSE/VSAIVI Return Code OS/VSAIVI Return Code 192 196 212 216 220 228 232 DMSVIP782E DMSVIP782E 144 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 8 Figure 35 (Part 3 of 3). 8 8 8 VSE/VSAM to OS/VSAM Error and Return Code Mapping for OPEN Errors The following table lists the VSE/VSAM to OS/VSAM error code mapping for CLOSE errors: VSE/VSAM Error Code C:M:S Error Message or OS/VSAM Error Code VSE/VSAM Return Code OS/VSAM Return Code 2 4 76 136 144 165 166 167 184 188 228 252 254 255 DMSVIP783E 4 DMSVIP784 136 144 DMSVIP784 DMSVIP784 DMSVIP784 184 0 DMSVIP783 DMSVIP784 DMSVIP784 148 non-zero non-zero non-zero non-zero non-zero non-zero non-zero non-zero non-zero non-zero non-zero non-zero non-zero non-zero 4 4 4 4 4 4 4 4 Figure 36. 318 4 4 4 4 4 4 VSE/VSAM to OS/VSAM Error and Return Code Mapping for CLOSE Errors VM/SP eMS for System Programming For Data Management Request errors, all VSE/VSAM error codes are returned to the OS/VSAM user since the VSE/VSAM and OS/VSAM error codes are equivalent, with the following exceptions: VSE/VSAlVI Error Code 32 48 52 56 128 208 212 216 Figure 37. eMS Error Message or OS/VSAM Error Code DMSVIP785E 40 Abend 52* Abend 56* DMSVIP786E DMSVIP786E DMSVIP786E DMSVIP785E VSE/VSAr/l Return Code 0 8 8 8 8 8 8 8 OS/VSAIVl Return Code 0 8 8 8 8 8 8 8 DATA Management Request Error Return Code Mapping Hardware De"ices Supported eMS support of VSAM data sets is based on VSE/VSAM. In its support of VSAM data sets, eMS uses RPS (rotational position sensing) wherever possible. eMS does not use RPS for 2314/2319 devices or for 3340 devices that do not have the feature. Except for the 3380, only disks supported by VSE can be used for VSAM data sets in eMS. These disks are: o o o o o o o Q o Q Q IBM IBM IBM IBM IBM IBM IBM IBM IBM IBM IBM 2314 Direct Access Storage Facility 2319 Disk Storage 3310 Direct Access Storage 3330 Disk Storage, Models 1 and 2 3330 Disk Storage, Model 11 3340 Direct Access Storage Facility 3344 Direct Access Storage 3350 Direct Access Storage 3370 Direct Access Storage, Models AI, A2, B1, and B2 3375 Direct Access Storage 3380 Direct Access Storage eMS disk files used as input to or output from Access Method Services may reside on any disk supported by eMS. Chapter 10. Using Access Method Services and VSAM under CMS and CMS/DOS 319 ____________________________________________________________________________________________ =:J /' 320 VM/SP eMS for System Programming Saving the eMS System Only named systems can be saved. The NAMESYS macro must be used to name a system. A discussion on creating a named system is found in the VM/ SP Planning Guide and Reference. The DMKSNT file must have been configured (by coding the NAMESYS macro) when CP was generated. The DMKSNT file contains the system name, size of the system, and its real disk location. The CMS system may be saved by: o Providing a positive response to the following message (message 729R): Do you want to save the system? (enter l=YES or O=NO) o Modifying the DEFNUC MACRO to include a positive response to the SAVESYS parameter, or o Issuing the IPL command with the "SAVESYS systemname" parameter. The "systemname" is the name assigned to the saved system. This is the same system name specified in the DMKSNT file. The CMS S-disk must be mounted and attached to the virtual machine creating the saved system before the SAVESYS function is invoked. This ensures that CMS file directories are saved correctly. However, in addition to the S-disk, you need the Y-disk to save the shared Y-disk directory. Note: Any updates to the CMS S-disk or Y-disk require saving the CMS system again. In VM/SP, the CMS system is designed to be used as a saved system. Its location may be modified by an installation for its particular requirements but should be shared among CMS users. Chapter 11. Tailoring Your CMS System 321 IT E)U ~Q)~~u~uqJ VQ~~%~ CL{~8 817s~emru r:====-.~=~:-:-_~-.~.=:::~.~.'~-:::-.~~_:='~.~:_-:: .. ':'~~::'-~==-=~__.: ________ ._ ....___. ___________. ___ ._______. . _. _______. _______. . ___. . _________._. __.____. _._.___.___. ____.__ 1 :oJ Saved System Restrictions for eMS Several coding restrictions must be imposed on CMS if it is to run as a saved system. If the key specified in the CAW for a SIO instruction is zero, the data area for input may not cross the boundary between two pages with different storage keys. If you intend to modify a shared CMS system, be sure that all code that is shared resides in the shared segments of the CMS nucleus. You can use the USERSECT area of DMSNUC to contain nonshared instructions. If you want to have a system profile EXEC, or if you want to use the NOSPROF, INSTSEG, or SAVESYS parameters of the IPL command, you must have: PARMRGS=(O,15) in the NAMESYS macro for the CMS named system. I Using the System Profile, SYSPROF EXEC, for Tailoring V'Jhat the System Profile Does The system profile is an EXEC that performs some of the CMS initialization function previously done in a module. You, the system programmer, can tailor the CMS environment that users see at initialization time by modifying this EXEC. You can do such things as access additional system disks or bring up application programs automatically. Decisions on tailoring the environment can be made on the basis of userid, responses to prompting, CMS parameters on the IPL command, or any other conditions defined by your installation. You can also bypass the system profile. The system profile is not meant to force users into an environment. Instead, it enables you to change the default CMS environment established by DMSINS without modifying a CMS module and rebuilding CMS. You can modify the EXEC to make it as secure as your installation requires. The CMS initialization module, DMSINS, calls SYSPROF EXEC and executes it from a DCSS (discontiguous shared segment) or the system disk or the system disk extension. This is done before any user disks are accessed. When you enter the IPL CMS command, SYSPROF EXEC is executed unless you: 322 • Specify the NOSPROF parameter on the command line, or o IPL a non-DASD virtual device, such as a reader, or VM/SP eMS for System Programming ,/ savearea lr r13,r15 space *open files and check that they opened okay space la r3,0 initially set return code open (indata,outdata,(output)) open files using ihadcb,rlO get dsect to check files la rlO,indata prepare to check output file tm dcboflgs,x'lO' everything ok? bnz checkout .. . continue r3,100 set return code la b exit ... exit checkout la rlO,outdata check output file dcboflgs,x'lO' is it okay? tm bnz process r3,200 la set return code b exit space process equ * indata read a record from input file get lr r2,rl save address of record put outdata, (2) move it to output process continue until end-of-file b space exit equ * close (indata"outdata) close files r13,savearea+4 addr of caller's save area 1 lr r15,r3 load return code 1 r14,12(r13) get return address 1m rO,r12,20(r13) restore regs br r14 bye ... space savearea dc lBf'O' ddname=indd,macrf=gl,dsorg=ps,recfm=f,lrecl=BO, indata dcb 356 VM/SP eMS for System Programming * 2 saveninput Input mode: outdata codad=c::i t deb ddname=outdd,macrf=pm,dsorg=ps dcbd space end 3 4 S 6 file Ready; global maclib osmacro Ready; assemble ostest ASSEMBLER DONE OST00230 23 LA R3,0 INITIALLY SET RETURN CODE IF0188 R3 IS AN UNDEFINED SYMBOL OST00240 24 OPEN (INDATA/OUTDATA/(~UTPUT)) OPEN FILES 4000000 27+ 12,*** IHB002 INVALID OPTION OPERAND SPECIFIED-OUTDATA IF0197 *** MNOTE *** OST00290 32 LA R3,100 SET RETURN CODE IF0188 R3 IS AN UNDEFINED SYMBOL OST00340 37 LA R3,200 SET RETURN CODE IF0188 R3 IS AN UNDEFINED SYMBOL OST00460 63 LR RIS,R3 LOAD RETURN CODE IF0188 R3 IS AN UNDEFINED SYMBOL NUMBER OF STATEMENTS FLAGGED IN THIS ASSEMBLY S Ready(00012) i 2 Before continuing to enter input lines, the EDIT subcommand SAVE is issued to write what has already been written onto disk. The CP logical line end symbol (#) separates the SAVE and INPUT subcommands. 3 A null line returns you to edit mode. You may wish, at this point, to proofread your input file before issuing the FILE subcommand to write the ASSEMBLE file onto disk. 4 Since this assembler program uses OS macros, you must issue the GLOBAL command to identify the CMS niacro library, OSMACRO MACLIB, before you can invoke the assembler. 5 The ASSEMBLE command invokes the VMjSP assembler to assemble the source file. 6 The assembler displays errors encountered during assembly. Depending on how accurately you copied the program in this sample session, you mayor may not receive some of these messages; you may also have received additional messages. Appendix B. Sample Terminal Session for OS Programmers 357 7 xedit ostest assemble locate Ir2 R2 EQU 2 i r3 equ 3 lopen *OPEN FILES AND CHECK THAT THEY OPENED OKAY lopen OPEN (INDATA,OUTDATA,(OUTPOT)) c 1,1,,1 8 9 10 11 12 OPEN (INDATA"OUTDATA,(OUTPUT)) file Ready; assemble ostcst ASSEMBLER DONE NO STATEMENTS FLAGGED IN THIS ASSEMBLY Ready; filedef indd disk test data a Ready; filedef outdd punch Ready; cp spool punch to * Ready; OPEN FILES OPEN FILES 7 You must edit the file OSTEST ASSEMBLE and correct any errors in it. The errors placed in the example included a missing comma on the OPEN macro and the omission of an EQU statement for a general register. These changes are made as shown. The CMS Editor accepts a diagonal (/) as a LOCATE subcommand. S After all the changes have been made to the ASSEMBLE file, you can issue the FILE subcommand to replace the existing copy on disk and then reassemble it. 9 This time the assembler completes without encountering any errors. If your ASSEMBLE file still has errors, you should use the editor to correct them. 10 The FILEDEF command is used to define the input and output files used in this program. The ddnames INDD and OUTDD, defined in the DCBs in the program, must have a file definition in CMS. To execute this program, you should have a file on your A-disk named TEST DATA, which must have fixed-length, SO-character records. If you have no such file, you can make a copy of your ASSEMBLE file as follows: copyfile ostest assemble a test data a 11 The output file is defined as a punch file so that it will be written to your virtual card punch. 12 The CP SPOOL command is issued, using the CP function, to spool your virtual punch to your virtual card reader. / 358 VM/SP eMS for System Programming 13 14 15 16 17 18 19 load ostest Ready; start DMSLI0740I Execution begins ... DMSSOP036E Open error code 04 on OUTDD. Ready(00200); filedef INDD DISK TEST DATA A1 OUTDD PUNCH Ready; filedef outdd punch (lrecl 80 recfm f Ready; cp query reader all NO RDR FILES Ready; load ostest (start DMSLT0740I Execution begins ... PUN FILE 6198 TO BILBO COpy 01 NOHOLD Ready; 13 The LOAD command loads the TEXT file produced by the assembly into virtual storage. The START command begins program execution. 14 An open error is encountered during program execution. The CMS ready message indicates a return code of 200, which is the value placed in it by your program. 15 The FILEDEF command, with no operands, results in a display of the current file definitions in effect. 16 Error code 4 on an open request means that no RECFM or LRECL information is available. An examination of the program listing would reveal that the DeB for OUTDD does not contain any information about the file format; you must supply it on the FILEDEF command. Re-enter the FILEDEF command. 17 You can use the CP QUERY command to determine whether there are any files in your card reader. It should be empty; if not, determine whether they might be files you need and, if so, read them into your virtual machine; otherwise, purge them. 18 Use the LOAD command to execute the program again; this time, use the START option of the LOAD command to begin the program execution. 19 The PUN FILE message indicates that a file has been transferred to your virtual card reader. The ready message indicates that your program executed successfully. Appendix B. Sample Terminal Session for as Programmers 359 20 21 22 23 fi indd reader Ready; fi Qutdd disk new osfile a4 (recfm fb block 1600 lrecl 80 Ready; listfile new osfile a4 (label DMSLST002E File not found. Ready(00028); run: ostest Execution begins ... Ready; listfile new osfile a4 (label FILENAME FILETYPE FM FORMAT LRECL RECS BLOCKS DATE NEW OSFILE A4 F 1600 5 10 9/30/75 Ready; TIME 8:26:14 LABEL PAT198 20 For the next execution of this program, you are going to read the file back out of your card reader and create a new CMS disk file in OS simulated data set format. FI is an acceptable system truncation for the command named FILEDEF. 21 The LISTFILE command is issued to check that the file NEW OSFILE does not exist. 22 The RUN command (which is an EXEC procedure) is used instead of the LOAD and START commands to load and execute the program. The ready message indicates that the program completed execution. 23 The LIST FILE command is issued again, and the file NEW OSFILE is listed. (If you issue another CP QUERY READER command, you will also see that the file is no longer in your card reader.) 360 VM/SP eMS for System Programming The following terminal session shows how you might create an assembler language program in CMS, assemble it, correct assembler errors and execute it. All the lines in blue are lines that you should enter at the terminal. The other lines represent the system responses that you should receive when you enter the command. The input data lines in the example are aligned in the proper columns for the assembler; if you are using a typewriter terminal, you should set your terminal's tab stops at columns 10, 16, 31, 36, 41 and 46, and use the Tab key when you want to enter text in these columns. If you are using a display terminal, when you use a PF key or an input character defined as a tab, the line image is expanded as it is placed in the screen output area. Note: The assembler, in CMS, cannot read macros from VSE/AF libraries. This sample terminal session shows how to copy macros from VSE/ AF libraries and create CMS MACLIB files. Ordinarily, the macros you need should already be available in a system MACLIB file. You do not have to create a MACLIB each time you want to assemble a program. There are some errors in the terminal session so that you can see how to correct errors in CMS. 1 2 cp link dosres 130 130 rr linkdos DASD 130 LINKED RIO Ready; access 130 z Z (130) RIO - DOS Ready; set dos on z Ready; 1 Use the CP LINK command to link to the DOS system residence volume and the ACCESS command to access it. In this example, the system residence is at virtual address 130 and is accessed as the Z-disk. 2 Enter the CMS/DOS environment specifying the mode letter at which the DOS/VS (VSE/AF) system residence is accessed. Appendix C. Sample Terminal Session for DOS Programmers 361 3 4 xedit dostest assemble Creating new file: input Input mode: begpgm csect balr 12,0 using *,12 la 13,savearea open infile,outfile loop get infile put outfile b loop eodad equ * close infile,outfile eoj eject CL80' , buffer dc infile dtfdi modname=shrmod,ioarea1=buffer,devaddr=sysipt, save#input Input mode: eofaddr=eodad,recsize=80 outfile dtfdi modname=shrmod,ioareal=buffer,devaddr=syspch, save#input Input mode: recsize=81 shrmod dimod typefle=output ,'t endpgm equ end * * 3 Use the EDIT command to create a file named DOSTEST ASSEMBLE. Since the file does not exist, the editor indicates that it is a new file and you can use the INPUT subcommand to enter input mode and begin entering the input lines. 4 Before continuing to enter input lines, the XEDIT subcommand SAVE is issued to write what has already been written onto disk. The logical line end symbol (#) separates the SAVE and INPUT subcommands. Another continuation character is needed. 362 VM/SP eMS for System Programming 5 6 7 8 9 10 file Ready; xedit getrnacs eserv Creating new file: tabs 2 72 input Input mode: punch open,close,get,put,dimod,dtfdi file Ready; assgn sysipt a Ready; eserv getrnacs Ready; listfile getmacs * GETMACS ESERV Al GETMACS MACRO Al GETMACS LISTING Al Ready; maclib gen dosmac getmacs Ready; erase getmacs * Ready; 5 A null line returns you to edit mode. You may want, at this point, to proofread your input file before issuing the FILE subcommand to write the ASSEMBLE file on disk. 6 To obtain the macros you need to assemble this file, use the editor to create an ESERV file. By setting the logical tabs at columns 2 and 72, you can protect yourself from entering data in column 1. 7 PUNCH is an ESERV program control statement that copies and de-edits macros from source statement libraries; in this case, the system source statement library. The output is directed to the SYSPCH device, which the CMS/DOS ESERV EXEC assigns by default to your A-disk. 8 You must assign the logical unit SYSIPT before you invoke the ESERV command. GETMACS is the filename of the ESERV file containing the ESERV control statements. 9 After the ESERV EXEC completes execution, you have three files. You may want to examine the LISTING file to check the ESERV program listing. The MACRO file contains the punch (SYSPCH) output. 10 The MACLIB command creates a macro library named DOSMAC MACLIB. Since the MACLIB command completed successfully, you can erase the files GETMACS ESERV, GETMACS LISTING and GETMACS MACRO; an asterisk in the filetype field of the ERASE command indicates that all files with the filename of GETMACS should be erased. Appendix C. Sample Terminal Session for DOS Programmers 363 11 12 13 14 15 16 global mac lib dosmac Ready; assemble dostest ASSEMBLER DONE DOS00040 4 LA 13,SAVEAREA IF0188 SAVEAREA IS AN UNDEFINED SYMBOL DOSOOII0 35 EOJ IF0078 UNDEFINED OP CODE NUMBER OF STATEMENTS FLAGGED IN THIS ASSEMBLY Ready(00008); xedit dotest assemble locate /buffer/ BUFFER DC CL80" input savearea ds 9d file Ready; xed it eoj eserv Creating new file: i punch eoj file . Ready; listio sysipt SYSIPT DISK A Ready; eserv eoj Ready; 2 11 Before you can invoke the assembler, you have to identify the macro library that contains the macros; use the GLOBAL command specifying DOSlvIAC MACLIB. 12 The ASSEMBLE command invokes the VM/SP assembler to assemble the source file. 13 The assembler displays errors encountered during assembly. Depending on how accurately you copied the program in this sample session, you mayor may not receive some of these messages; you may also have received additional messages. 14 To correct the first error, which was the omission of a DS statement for SAVEAREA, edit the file DOSTEST ASSEMBLE and insert the missing line. 15 The second error indicates that the macro EOJ is not available since it was not copied from the source statement library. Create another ESERV file to punch this macro. 16 Use the LISTIO command to check that SYSIPT is still assigned to your A-disk so that you do not have to issue the ASSGN command again. Then issue the ESERV command again, this time specifying the filename EOJ. 364 VM/SP eMS for System Programming 17 18 19 20 21 maclib add dosmac eoj Ready; maclib map dosmac (term INDEX SIZE MACRO 2 OPEN 43 CLOSE 46 43 90 GET 56 147 PUT 93 241 DIMOD 647 889 DTFDI 284 1174 EOJ 6 Ready; erase eoj ~I: Ready; assemble dostest ASSEMBLER DONE NO STATEMENTS FLAGGED IN THIS ASSEMBLY Ready; listfile dostest * DOSTEST ASSEMBLE Al DOSTEST LISTING Al DOSTEST TEXT Al Ready; print dostest listing Ready; doslked dostest Ready; 17 Use the ADD function of the MACLIB command to add the macro EOJ to DOSMAC MACLIB. Then issue the MACLIB command again using the MAP function and the TERM option to display a list of the macros in the library. 18 Erase the EOJ files. You should always remember to erase files that you do not need any longer. Reassemble the program. 19 This time the assembler completes without encountering any errors. If you ASSEMBLE file still has errors, you should use the editor to correct them. 20 Use the LIST FILE command to check for DOSTEST files. The assembler created the files DOSTEST LISTING and DOSTEST TEXT. The TEXT file contains the object module. You can print the program listing if you want a printer copy. Then you may want to erase it. 21 Use the DOSLKED command to link-edit the TEXT file into an executable phase and write it into a DOSLIB. Since this program has no external references, you do not need to add any linkage editor control statements. Appendix C. Sample Terminal Session for DOS Programmers 365 22 23 24 25 22 listfile dostest * DOS TEST ASSEMBLE A1 DOSTEST DOSLIB A1 DOSTEST TEXT A1 DOSTEST LISTING A1 DOSTEST MAP A5 Ready; cp spool punch to * Ready; punch test data a PUN FILE 0100 TO BILBO COPY 01 NOHOLD Ready; cp query reader all Ready; ORIGINID FILE CLASS RECDS CPY HOLD DATE TIME NAME PATTI 5840 A PUN 000097 01 NONE 09/29 15:00:39 TEST assgn sysipt reader Ready; assgn syspch a Ready; dlbl outfile a cms punch output (syspch Ready; state punch output a DMSSTT002E File not found. Ready(00028); TYPE DATA DIST BIN211 Now you have a DOSTEST DOSLIB containing the link-edited phase and a MAP file containing the linkage editor map. You can display the linkage editor map with the TYPE command or use the PRINT command if you want a printer copy. 23 To execute this program in CMS/DOS, punch a file that _has fixed- length, 80-character records into your virtual card punch. If you do not have any files that have fixed-length, 80-character records, you can create a file named TEST DATA with the CMS Editor or by copying your ASSEMBLE source file with the COPYFILE command as' follows: copyfile dostest assemble a test data a Use the CP SPOOL command to spool the punch to your own virtual machine, then use the PUNCH command to punch the file. The PUN FILE message indicates that the file is in your card reader. Use the CP QUERY command to check that it is the first or only file in your reader. 24 Use the ASSGN command to assign SYSIPT to your card reader and SYSPCH to your A-disk. 25 366 When you assign a logical unit to a disk mode, you must issue the DLBL command to identify the disk file to CMS. For this program execution, you are creating a CMS file named PUNCH OUTPUT. The STATE command ensures that the file does not already exist. If it does exist, rename it or else use another filename or filetype on the DLBL command. VM/SP eMS for System Programming 26 27 28 global doslib dostast Ready; fetch dostest DMSFET710I Phase DOSTEST entry point at location 020000. Ready; start DMSLI0740I Execution begins ... Ready; listfile punch output a (label FILENAME FILETYPE FM FORMAT LRECL RECS BLOCKS DATE TIME PUNCH OUTPUT Al F 80 97 10 9/29/79 14:50:55 Ready; cp query reader all Ready; NO RDR FILES assgn sysipt a Ready; dlbl infile a cms punch output (sysipt Ready; assgn syspch punch Ready; LABEL BBB191 26 Use the GLOBAL command to identify the DOSLIB, DOSTEST if you want to search for executable phases; then issue the FETCH command specifying the phase name. The FETCH command loads the executable phase into storage. When the FETCH command is executed without the START option, a message is displayed indicating the entry point location of the program loaded. 27 The START command begins program execution. The CMS ready message indicates that your program completed successfully. You can check the input and output activity by using the LISTFILE command to list the file PUNCH OUTPUT. If you use the CP QUERY command, you can see that the file is no longer in your virtual card reader. 28 If you want to execute this program again, you can assign SYSIPT and SYSPCH to different devices; in this example, the input disk file PUNCH OUTPUT is written to the virtual punch. You do not need to reissue the GLOBAL DOSLIB command; it remains in effect until you reissue it or IPL CMS again. Appendix C. Sample Terminal Session for DOS Programmers 367 29 30 fetch dostest (start DMSLI0740I Execution begins ... PUN FILE 5829 TO BILBO COpy 01 NOHOLD Ready; reud punch2 output Ready; listfile punch2 output a (label FILENAME FILETYPE FM FORMAT LRECL RECS BLOCKS PUNCH2 OUTPUT A1 F 80 97 10 Ready; DATE TIME 9/29/75 14:50:59 LABEL BBB191 29 This time the program execution starts immediately because the START option is specified on the FETCH command. 30 Again, the PUN FILE message indicates that a file has been received in your virtual card reader. You can use the CMS command READ CARD to read it onto disk and assign it a filename and filetype; in this example, PUNCH2 OUTPUT. / 368 VM/SP eMS for System Programming n i\ r,-,r~\ lrr-J(]ii [li"" ,I" U.. :,. "ja ;. ,lL/~'):"'~u C::',]rr--:lrl"":\n(-\ "U'~"(\r:--'7Infi'7l'Jn (~l\0("">"Uri\lrT':'l nJl~nfi'7l(i'~ /\(22"")'--', r\rJr",;;,~,(i'~"il r.,)l.., UUU~)U .J-'U UUuUUUl.. U 0.:,) ..H);,.) ."I,.,;;uu ~ .....,Uuu,.J .. :l,_'~;J' ..I\" ' - U'.I ,..,II,;,:.IU'-j .. ~~)O U'\] ~ G_~~)C,) This sample terminal session shows you how to use access method services under eMS. You should have an understanding of VSAM and access method services before you use this terminal session. The terminal session uses a number of eMS files, which you may create during the course of the terminal session; or, you may prefer to create all of the files that you need beforehand. Within the sample terminal session, the file that you should create is displayed prior to the commands that use it. This terminal session is for both eMS as VSAM programmers and eMS/DOS VSAM programmers. All entries in blue are entries you (a eMS as VSAM programmer or a eMS/DOS VSAM programmer) should enter. The entries in blue and shaded are only for eMS/DOS programmers. Notes: 1. This terminal session assumes that you have, to begin with, a read/write eMS A-disk. This is the only disk required. Additional disks used in this exercise are temporary disks, formatted with the Device Support Facility program. If you have OS or DOS disks available, you should use them, and remember to supply the proper volume and virtual device address information, where appropriate. The number of cylinders available to users for temporary disk space varies among installations; if you cannot acquire ample disk space, see your system support personnel for assistance. 2. Output listings created by A MSER V take up disk space, so if your A-disk does not have a lot of space on it, you may want to erase the LISTING files created after each AMSERV step. 3. If any of the A MSER V commands that you execute during this sample terminal session issue a nonzero return code,· for example: Ready(00012); You should edit the LISTING file to examine the access method services error messages. The publication VSE/ VSAM Messages and Codes contains the return codes and reason codes issued by access method services. You should determine the cause of the error, examine the DLBL commands and AMSER V files you used, correct any errors, and retry the command. Appendix D. Sample Terminal Session Using Access Method Services 369 1 2 cp define t3330 200 10 Ready; DASD 200 DEFINED cp query virtual 200 Ready; DASD 200 3330 (TEMP) R/W 10 CYL cp define t3330 300 10 Ready; DASD 300 DEFINED cp query virtual 300 Ready; DASD 300 3330 (TEMP) R/W 10 CYL cp define t3330 400 10 Ready; DASD 400 DEFINED cp query virtual 400 Ready; DASD 400 3330 (TEMP) R/W 10 CYL File: PUNCH DSF INIT UNIT(200) DEVTYP(3330) NVFY VOLID(222222) DVTOC(O,l,l) MIMIC(MINI(10» INIT UNIT(300) DEVTYP(3330) NVFY VOLID(333333) DVTOC(O,l,l) MIMIC(MINI(10» INIT UNIT(400) DEVTYP(3330) NVFY VOLID(444444) DVTOC(O,l,l) MIMIC(MINI(10» 3 - File: DSF EXEC /* EXEC to Invoke Device Support Facility */ arg cntrl . address command 'CP CLOSE READER' 'CP PURGE READER CLASS I' 'CP SPOOL PUNCH CONT TO * CLASS I' 'PUNCH IPL DSF S ( NOH' 'PUNCH' cntrl 'DSF ( NOH' 'CP SPOOL PUNCH NOCONT CLOSE' 'CP SPOOL READER CLASS I NOHOLD' 'CP IPL OOC CLEAR ATTN' 1 These commands define temporary 3330 mini disks at virtual addresses 200,300 and 400. 2 This file contains control statements for the Device Support Facility program, which initializes disks for use by VSAM. These disks are labelled 222222, 333333 and 444444. 3 This file contains the commands necessary to use the Device Support Facility program in a virtual machine. 370 VM/SP eMS for System Programming 4 5 exec dsf punch NO FILES PURGED PUN FILE nnnn TO CAMPBEL COpy 001 NOHOLD ICK005E DEFINE INPUT DEVICE, REPLY 'DDDD,CUU' or 'CONSOLE' ENTER INPUT/COMMAND: 6 2540,OOc 2540,00C ICK006E DEFINE OUTPUT DEVICE, REPLY 'DDDD,CUU' or 'CONSOLE' ENTER INPUT/COMMAND: 7 console CONSOLE ICKDSF - SA DEVICE SUPPORT FACILITIES 5.0 TIME20:26:00 03/09/82 INIT UNIT(200) DEVTYP(3330) NVFY VOLID(222222) DVTOC(O,l,l) MIMIC(MINI(10» ICK00700I 200 BEING PROCESSED AS LOGICAL DEVICE = 3330 PHYSICAL DEVICE = 3330-11 ICK003D REPLY U TO ALTER VOLUME 200 CONTENTS, ELSE T ENTER INPUT/COMMAND: 8 PAGE 1 u U ICK01314I VTOC IS LOCATED AT CCHH=X'OOOO 0001' AND IS 1 TRACKS. ICK00001I FUNCTION COMPLETED, HIGHEST CONDITION CODE WAS 0 INIT UNIT(300) DEVTYP(3330) NVFY VOLID(333333) DVTOC(O,l,l) MIMIC(MINI(10» ICK00700I 300 BEING PROCESSED AS LOGICAL DEVICE = 3330 PHYSICAL DEVICE = 3330-11 ICK003D REPLY U TO ALTER VOLUME 300 CONTENTS, ELSE T ENTER INPUT/COMMAND: u U ICK01314I VTOC IS LOCATED AT CCHH=X'OOOO 0001' AND IS 1 TRACKS. ICK00001I FUNCTION COMPLETED, HIGHEST CONDITION CODE WAS 0 INIT UNIT(400) DEVTYP(3330) NVFY VOLID(444444) DVTOC(O,l,l) MIMIC(MINI(10» ICK00700I 400 BEING PROCESSED AS LOGICAL DEVICE = 3330 PHYSICAL DEVICE = 3330-11 4 Execute the DSF EXEC, specifying that the Device Support Facility control statements contained in the file 'PUNCH DSF' should be appended to the standalone Device Support Facility program. 5 These messages are issued by the Device Support Facility standalone program. 6 Since the Device Support Facility control statements reside in the virtual card reader, you must indicate to Device Support Facility the device type and the address of your virtual reader. 7 This response tells Device Support Facility to output all run time information to your virtual machine console. 8 This response gives Device Support Facility permission to proceed with the initialization of the disk. Appendix D. Sample Terminal Session Using Access Method Services 371 ICK003D REPLY U TO ALTER VOLUME 400 CONTENTS, ELSE T ENTER INPUT/COMMAND: u U ICK01314I VTOC IS LOCATED AT CCHH=X'OOOO 0001' AND IS 1 TRACKS. ICK00001I FUNCTION COMPLETED, HIGHEST CONDITION CODE WAS 0 ICKDSF MAXIMUM STORAGE USED = 278968 BYTES (FIXED = 258120, DYNAMIC = 020848) ICK00002I ICKDSF PROCESSING COMPLETE. MAXIMUM CONDITION CODE WAS 0 cp ipl cms parm autocr Ready; CMS VM/SP5.0 SL 000 Ready; 9 10 cp link vseaf 350 350 rr pass=read DASD 350 LINKED R/O; R/W BY GANDALF access 350 z DMSACC723I Z (350) R/O - DOS Ready; ; set dos on z ( vsam , Ready; 11 access 200 DMSACC723I Ready; access 300 DMSACC723I Ready; access 400 DMSACC723I Ready; b B (200) R/W - DOS c C (300) R/W - DOS d D (400) R/W - DOS -----------9 You must re-IPL CMS after all Device Support Facility processing has completed. 10 If you are a CMS/DOS user, you must access the VSE/AF SYSRES disk and issue the 'SET DOS ON fIn (VSAM' command. If you have not previously linked to the VSE/AF SYSRES, you must use the CP LINK command before you issue the ACCESS command. Another method is to have the operator ATTACH the SYSRES disk to your virtual machine. Consult with your system programmer for the procedure to use at your installation. 11 ACCESS the three newly formatted disks as your B-, C- and D-disks. ,/ 372 VM/SP eMS for System Programming 12 query search PLC191 191 222222 200 333333 300 444444 400 MNT190 190 MNT191 190 VSERES 350 Ready; A B C D S Y/S Z R/W R/W R/W R/W R/O R/O R/O - DOS - DOS - DOS - DOS 13 File: MASTCAT AMSERV DEFINE MASTERCATALOG ( NAME (MASTCAT) VOLUME (222222) CYL (4) UPDATEPW (GAZELLE) FILE (IJSYSCT) ) DATA (CYL(l)) 14 assgn syscat b Ready; dlbl ij sysct b dsn mastcat (syscat perm extent DMSDLB331R Enter extent specifications: 19 171 15 Ready; 16 amserv mastcat Ready; 12 You can issue the QUERY SEARCH command to verify the status of all disks you currently have accessed. The 350 disk will be listed only if DOS is set on. 13 The file MASTCAT AMSERV defines the VSAM master catalog that you are going to use and provides space for suballocated clusters. 14 Identify the master catalog volume, and use the EXTENT option on the DLBL command so that you can enter the extents. For this extent, specify 171 tracks (9 cylinders) for the master catalog. Since 4 cylinders are specified in the AMSERV file, the remaining 5 cylinders will be used for suballocation by VSAM. 15 You must enter a null line to indicate that you have finished entering extent information. 16 Issue the AMSERV command specifying the MASTCAT file. The ready message indicates that the master catalog is created. Appendix D. Sample Terminal Session Using Access Method Services 373 17 File: CLUSTER AMSERV DEFINE CLUSTER ( NAME (BOOK. LIST ) VOLUMES (222222) TRACKS (20) KEYS (14 r 0) RECORDSIZE (120,132) ) DATA (NAME (BOOK. LIST. DATA) ) INDEX (NAME (BOOK.LIST.INDEX ) ) A 18 amserv cluster 4221A ATTEMPT 1 OF 2. ENTER PASSWORD FOR JOB AMSERV gazelle Ready; 19 File: REPRO AMSERV REPRO INFILE (BFILE ENV ( RECORDFORMAT(F) BLOCKSIZE(120) PDEV (3330) ) ) OUTFILE (BOOK) 20 assgn sysOOl a Ready; copyfile test data a (recfm f lrecl 120 Ready; sort test data a book file a DMSSRT604R Enter sort fields: 1 14 Ready; dlbl bfile a cms book file (sysOOl Ready; assgn sys002 b Ready; dlbl book b dsn book. list (vsam sys002 Ready; amserv repro Ready; 21 FILE MASTCAT 17 Define a suballocated cluster. This cluster is for a key-sequenced data set named BOOK.LIST. 18 No DLBL command is necessary when you define a suballocated cluster. Not that since the password was not provided in the AMSERV file, access method services prompts you to enter the password of the catalog, which is defined as GAZELLE. 19 Use the access method services REPRO command to copy a CMS data file into the cluster that you just defined. 20 You must identify the ddnames for the input and output files for the REPRO function. BFILE is a eMS file, which must be a fixed-length, 120-character file, and it must be sorted alphameric ally in columns 1 through 14. The COPYFILE command can copy any existing file that you have to the proper record format; the SORT command sorts the records on the proper fields. 21 The output file is the VSAM cluster, so you must use the VSAM option on this DLBL command. 374 VM/SP eMS for System Programming 22 23 24 25 22 File: SPACE AMSERV DEFINE SPACE ( FILE (SPACE) TRACKS (57) VOLUME (333333) assgn sys003 c Ready; dlbl space c (extent sys003 DMSDLB331R Enter extent specifications: 19 57 Ready; amserv space 4221A ATTEMPT 1 OF 2. ENTER PASSWORD FOR JOB AMSERV gazelle Ready; File: UNIQUE AMSERV DEFINE CLUSTER( NAME (UNIQUE.FILE) UNIQUE ) DATA ( CYL (3) FILE (KDATA) RECORDSIZE (100 132) KEYS(12,0) VOLUMES (333333 ) ) INDEX (CYL (1)FILE (KINDEX) VOLUMES (333333) FILE MASTCAT Create an AMSERV file to define additional space for the master catalog on the volume labelled 333333. 23 Again, use the EXTENT option on the DLBL command so that you can enter extent information and a null line to indicate that you have finished entering extents. 24 Issue the AMSERV command. Again, you are prompted to enter the password of the master catalog. 25 This AMSERV file defines a unique cluster, with data and index components. Appendix D. Sample Terminal Session Using Ac·cess Method Services 375 26 dlbl kdata c (extent sys003 DMSDLB331R Enter extent specifications: 76 57 Ready; dlbl kindex c (extent sys003 DMSDLB331R Enter extent specifications: 76 76 27 28 Ready; amserv unique 4221A ATTEMPT 1 OF 2. ENTER PASSWORD FOR JOB AMSERV FILE MASTCAT gazelle Ready; File: USERCAT AMSERV DEFINE USERCATALOG ( CYL (8) FILE (IJSYSUC) NAME (PRIVATE.CATALOG) VOLUME (444444) UPDATEPW (UNICORN) ATTEMPTS (2) ) DATA (CYL (3) )INDEX ( CYL (1) ) CATALOG (MASTCAT/GAZELLE assgn sys006 d Ready; dlbl ij sysuc d dsn private. catalog (extent sys006 perm DMSDLB331R Enter extent specifications: 19 152 Ready; amserv usercat * Ready; 26 You must enter DLBL command and extent information for both the data and index components of the unique cluster. 27 Next, define a private (user) catalog for the volume 444444. This catalog is named PRIVATE.CATALOG and has a password of UNICORN. Again, as in step 13, space is made available for suballocation. 28 When you define a user catalog that you are going to use as the job catalog for a terminal session, you should use the ddname IJSYSUC. /' 376 VM/SP eMS for System Programming 29 Tape 181 attached 30 File: EXPORT AMSERV EXPORT BOOK. LIST INFILE (BOOK) OUTFILE (TEMP ENV (PDEV (2400) REWIND NOLABEL ) ) dlbl book b dsn book list (cat ij sysct sys002 Ready; amserv export (tapout 181 DMSAMS367R Enter tape output DDNAMEs: temp Ready; File: IMPORT AMSERV 31 32 33 IMPORT 34 CATALOG (PRIVATE.CATALOG/UNICORN) INFILE (TEMP ENV (PDEV (2400) REWIND NOLABEL» OBJECTS (BOOK.LIST VOL (444444» amserv import (tapin 181 DMSAMS367R Enter tape input DDNAMEs: temp Ready; - 29 You may want to try an EXPORT!IMPORT function, if you can obtain a scratch tape from the operator. When the tape is attached to your virtual machine, you receive this message. 30 The file that is being exported is the cluster BOOK.LIST created above. If you do not have access to a tape, you can export the file to you CMS A-disk. R~member to change the PDEV parameter to reflect the appropriate device type. 31 You must reissue the DLBL for BOOK.LIST because there is a job catalog in effect, and the file is cataloged in the master catalog. Use the CAT option to override the job catalog. 32 There is no default tape value when you are using tapes with the AMSERV command. You must specify the TAPIN or TAP OUT option and indicate the virtual address of the tape. You are prompted to enter the ddname, which for this file is TEMP. 33 The last AMSERV file imports the cluster BOOK.LIST to the user catalog PRIVATE.CATALOG. 34 Read the tape in as input. Appendix D. Sample Terminal Session Using Access Method Services 377 / 378 VM/SP eMS for System Programming Structural Changes This book contains material formerly found in the VMjSP System Programmer's Guide, SCI9-6203. Figure 40 on page 380 shows the Release 4 books now obsolete by this reorganization, the new system programming books, and the topics these new books contain. To obtain editions of the VMj SP System Programmer's Guide, you must order using the pseudo-number assigned to the respective edition. For: VMjSP Release 4, order STOO-1578 VMjSP Release 3, order STOO-1352 VMjSP Release 2, order SQ19-6203 VMjSP Release 1, order STI9-6203. Summary of Changes 379 Release 4 Introduction to CP Program States Processor Resources Storage Protection Virtual Storage Preservation 'vN 110 Managemen t Spooling Functions CP Corrmands Interrupt Handling Accounting Records Saved System. DCSSs. Shared Segs CP Conventions Journa ling Suppressing Passwords Performance 3850 MSS Timers CP in AP/MP Mode Print Buffers and Forms Control 3800 Printing Subsystem Release 5 VM/SP CP For System Prograrrming VM/SP. SC24-5285 VM/SP HPO, SC23-0341 Introduct ion to CMS Abend Processing Interrupt Handling in CMS Functional Information OS Macro Simulation VSE Support CMS'Support for OS and VSE/VSAM Saving CMS CMS Batch Fac i,1 i ty Auxi liary Directories Assembler Virt Stor Requirements CMS Macro Library VM/SP CMS For System Prograrrming System Programmer's Guide SC24-5286 VMCF lUCY SNA CCS *MSG *BLOCKIO *SIGNAL Special Message Faci lity Single Console Image Faci lity Logical Device Support Faci lity DIAGNOSE Instruction and Codes Using *BLOCKIO from OMS CMS lUCY Prograrrmable Operator Faci lity VM/SP, SC19-6203 VM/SP HPO, SC19-6224 VM System Facilities For progra'i VM/SP GCS Guide • I SC24-5249-1 I SC24-5288 VM Diagnosis Guide { Introduction to Debugging Debugging the Virtual Machine Debugging CP Debugging CMS Debugging GCS Debugging Using IPCS Using DUMPSCAN Subcommands LY24-5241 SC24-5260-0 Figure 40. New VM/SP System Programming Manuals for VM/SP Release 5 / 380 VM/SP eMS for System Programming Technical Changes for VM System Facilitieo for Programming Summary of Changes for SC24-5286-0 for VM/SP Release 5 VM/SP Enhanced Usability VM/SP now has the following usability enhancements: o o o window functions full-screen environment for CMS a CONSOLE macro. When CMS is in full-screen mode, the user can enter commands from anywhere on the physical screen, scroll through data, and log data into files. The CONSOLE macro performs 3270 I/O operations. New CMS Commands SET TRANSLATE Command The SET TRANSLATE command specifies whether to use the User National Language Translation Tables and/or the System National Language Translation Tables. This command also suppresses translations and translation synonyms of command names for a language. SET LANGUAGE Command The SET LANGUAGE command changes the current language of your CMS session and any application running on CMS that uses national language support. P ARSECMD Command The P ARSECMD command invokes the parsing facility from an EXEC. New CMS Macros All new CMS macros are listed in Appendix A, "CMS Macro Library" on page 351. Modified CMS Commands GLOBAL Command The enhanced GLOBAL command· allows you to list up to 63 (formerly 8) libraries from one of the supported library types (MACLIB, TXTLIB, DOSLIB, or LOADLIB) to be searched for macros, copy files, subroutines,' VSE executable phrases, or OS load modules when processing subsequent CMS commands. TXTLIB Command The FILENAME option of the TXTLIB command creates a directory entry in the TXTLIB for each filename of the TEXT files specified. Summary of Changes 381 LOAD Command The HIST option of the LOAD command lets you add comments from TEXT files into MODULE files. INCLUDE Command The HIST option of the LOAD command lets you add comments from TEXT files into MODULE files. Enhancements for EXECs in Storage VM/SP now has an optional Installation Discontiguous Shared Segement (DCSS) to contain frequently used EXECs and Editor Macros that your installation provides. All users can access the DCSS and share the same executing copy of the EXECs. Enhanced Interactive Facility/System Profile The system profile is an EXEC that performs some CMS initialization function previously done in a module. By modifying this EXEC, the system programmer will be able to tailor the CMS environment to suit the installation's needs. Parsing Facility The CMS parsing facility parses and translat,es command name arguments. This lets users enter commands in national languages supported by VM/SP. These languages are: American English, KANJI, Uppercase English, French, German. To use the parsing facility, you must define command syntax in a special language, the Definition Language for Command Syntax (DLCS). The parsing facility parses a specified command by checking whether command arguments are specified according to the DLCS definition for that command. Defining command syntax in a DLCS file and using the parsing facility has the following advantages: 1. Syntax checking is unnecessary in programs. 2. Users can invoke programs in their own national language by modifying the DLCS file. Creating Message Files VM/SP now lets you store any message text in one central file. This file is called' a respository file. Some advantages of having a repository file are: 382 • message text will not clutter your program • message text can be translated to another language easily VM/SP eMS for System Programming Enhanced Connectivity Facilities on VM/SP This part of CMS supports IBM Systemj370 to IBM Personal Computer Enhanced Connectivity Facilities on a VMjSP system. For detailed information about Enhanced Connectivity Facilities on VMjSP, refer to the IBM VMjSP Programmer's Guide to the Server-Requester Programming Interface for VMj SP, SC24-5291. Miscellaneous Most CMS messages and responses are now in mixed case. Minor technical and editorial changes have been made throughout this publication. Summary of Changes for the VM/SP System Programmer's Guide The following "Summary of Changes" reflect the changes made to the VMj SP System Programmer's Guide, Release 4 and Release 3. Summary of Changes for SC19-6203-3 for VM/SP Release 4 Group Control System (VM/SP GCS) This new component of VMjSP is a virtual machine supervisor that provides simulated MVS services and supports a multitasking environment. For more information on the Group Control System (GCS), refer to the VMj SP Group Control System Guide - (Discontinued), SC24-5249. Signal System Service This new CP system service allows virtual machines in a Virtual Machine Group to signal each other. The Signal System Service can only be used by virtual machines in a Virtual Machine Group. Saved System 8M Byte Limit Removal With the addition of this support, the SAVESYS, VMSAVE, and IPL functions have been enhanced to allow a page image copy of up to a 16M byte virtual machine to be saved and restored. CPFRETTrap The CP FRET Trap can be used as an aid in solving problems caused by improper use of CP storage and to solve many storage overlay problems. Summary of Changes 383 VMDUMP Enhancements DIAGNOSE code X'94' is available to allow a virtual machine to request dumping of its virtual storage. Also, the three address range restriction has been removed from the VMDUMP command. DIAGNOSE code X'98' Using DIAGNOSE code X'98' a virtual machine can lock and unlock virtual pages, and execute its own real channel programs. The Programmable Operator Facility The Programmable Operator Facility has been enhanced to support distributed operations in an SNA network through an interface, the Programmable Operator/NCCF Message Exchange (PMX), with the Network Communications Control Facility (N'CCF). The VM/SP Release 4 programmable operator: o Allows an NCCF operator to be identified to the programmable operator so that any messages intended for the logical operator may be routed to that NCCF operator. o Allows an NCCF operator to issue programmable operator commands and re,ceive responses. o Provides the LGLOPR command for assigning, releasing and replacing the logical operator during operation. CPTRAP Enhancements CPTRAP is a major service aid used in problem determination. Enhancements to the CPTRAP command provide two additional functions, GROUPID and WRAP, and one additional entry type, X'3D'. Enhancements to TRAPRED makes reviewing the trap data easier by providing more selectivity for X'3D', X'3E', and X'3F' entries and by providing a way to display formatted output of the trapped data. Information on CPTRAP has been rewritten and reorganized for ease-of-use. It has also been moved to the Part 3, the debugging section, since it is a debugging tool. Interactive Problem Control System (VM/SP IPCS) VlVl/SP Release 4 has been enhanced to include IPCS as a component of VM/SP. VM/SP IPCS is equivalent to the VM/lnteractive Problem Control System Extension (VM/IPCS/E) Program Product (5748-SAl). Inter-User Communications Vehicle (IUCV) Enhancements IUCV now supports the movement of data on the SEND, RECEIVE, and REPLY functions from discontiguous buffers. The modified IUCV macro handles the new BUFLIST = parameter on SEND and RECEIVE 384 VM/SP eMS for System Programming functions and the new ANSLIST = parameter on the SEND and REPLY functions. Expansion of User Classes The DIRECT command has been enhanced and the OVERRIDE command has been added to provide the user with more than the seven IBM defined user classes. You can now choose from 32 user classes, A Z, and 1 - 6. Remote Spooling Communications Subsystem Networking Version 2 With the release of the Remote Spooling Communications Subsystem Networking Version 2 Program Product (5664-188), any reference to RSCS in this manual applies to RSCS Version 2. Information pertaining to RSCS can be found in the VM/ SP Remote Spooling Communications Subsystem Version 2 General Information, GH24-5055. Miscellaneous IOCP Support Enhancements This support adds new MSSF command words to DIAGNOSE code X'80'. Integration of Functional Enhancements to VM/SP Release 3 Information has been added to support: o The 3290 Information Panel o The 3370 Direct Access Storage Model o The 4248 Printer o The 4361 Model Groups 3, 4, and 5 Processor o The 4381 Model Groups 1 and 2 Processor o VM/SP 3800 Model 3 Compatibility Support Compatibility support allows VM/SP users to access the 3800 Model 3 Printing Subsystem. Existing programs designed to produce 3800 Model 1 printer output may produce output for the 3800 Model 3 printer with little or no program change. Use of this support provides improved print quality (240 x 240 pel resolution) and the addition of a 10 lines-per-inch (LPI) vertical space option. DIAGNOSE code X'8C' DIAGNOSE code X'8C' has been enhanced to allow a user to access all of the data returned by CP's WRITE STRUCTURED FIELD QUERY. Summary of Changes 385 DMKFRE/DMKFRT Split The module DMKFRE has been split into two modules, DMKFRE and DMKFRT. DMKFRE handles all requests for free storage as well as calls to DMKFRET to rel~ase free storage. DMKFRT handles all requests to return free storage thqt cannot be handled by the microcoded CP assist FRET function. Minor technical and editorial changes have been made throughout this publication. Summary of Changes for SC19-6203-2 for VM/SP Release 3 Programmable Operator Facility Several enhancements to the programmable operator facility added are: • Message routing with nicknames • Remote node availability e Enhanced text comparison • EXEC action routines • LOG recording and error handling PER Problem determination capability is greatly extended and enhanced by the new CP command, PER. DASD Block I/O System Service The DASD Block I/O System Service allows a virtual machine fast, device-independent asynchronous access to fixed size blocks on CMS formatted virtual DASD I/O devices. lUCY Inter-User Communication Vehicle (IUCV) extensions provide: • SEND and REPLY extensions • An extended mask capability for control interrupts • An expanded trace capability to record all IUCV operations • A macro option to initialize the parameter list / • 386 Support for the DASD block I/O system service. VM/SP eMS for System Programming The IBM 3088 Multisystem COInmunications Unit The IBM 3088 Multisystem Communications Unit interconnects multiple systems using block multiplexer channels. The 3088 uses an unshared subchannel for each unique address and is fully compatible with existing channel-to-channel adapter protocol. CMS IUCV Support Support for IUCV communication has been introduced into CMS. This support allows multiple programs within a virtual machine to use IUCV functions. Included is the ability to initialize a CMS machine for lUCY communication and to invoke IUCV functions via new CMS macros. These macros also allow the user to specify path-specific exits for IUCV external interrupts. CMS Abend Exits A general CMS abnormal exit capability is provided so that user programs may specify the address of a routine to get control before CMS abend recovery begins. An exit is established and cleared through a new CMS macro. Enhanced Immediate Command Support The immediate command capability of CMS is extended by allowing users to define their own immediate commands. Enhanced VSAM Support CMS supports VSE/VSAM Release 3 which includes significant enhancements designed to improve catalog reliability and integrity while providing additional serviceability and usability. VSE/VSAM Release 2 is not supported. Miscellaneous Changes to the DIAGNOSE code X'OO' interface provide the time zone differential from Greenwich Mean Time. DIAGNOSE code X'8C' allows a virtual machine to access device dependent information without having to issue a WRITE STRUCTURE FIELD QUERY REPLY. CMSSEG has been eliminated and the code was merged into the CMS l':luc1eus. The Remote Spooling Communications Subsystem (RSCS) section of this manual has been removed as it pertained to RSCS as a component of VM/370. Now, any reference to RSCS in this 'manual applies to the RSCS Networking Programming Product, and information can be found in the VM/ SP Remote Spooling Communications Subsystem Networking Program ReferelPce and Operations Manual, SH24-5005. Summary of Changes 387 A newly added appendix lists and describes the eMS macros applicable to VM/SP. Minor technical and editorial changes have been made throughout this publication. 388 VM/SP eMS for System Programming can appreciably expand the capabilities of this component in a VM/SP system by installing RSCS Networking Version 2 (5664-188). Abbreviations Some of the following terms and abbreviations are used throughout this publication for convenience: VSE Unless otherwise noted, VM/SP refers to the VM/SP program package when y~¥ use it in conjunction with VM/370 Release 6. CP refers to the VM/370 Control Program component enhanced by the functions included in the VM/SP package. CMS refers to the VM/370 Conversational Monitor System component enhanced by the functions included in the VM/SP package. GCS refers to the Group Control System component of VM/SP. See the Group Control System Command and Macro Reference, SC24-5250, for details of GCS. IPCS refers to the VM/370 Interactive Problem Control System component enhanced by the functions included in the VM/SP package. The IPCS component of VM/SP replaces the unmodified VM/370 interactive problem control system. Details describing this component are found in the VM Diagnosis Guide, LY24-5241. RSCS unless otherwise noted, refers to the RSCS Networking Version 2 Program Product (5664-188). When you install and use VM/SP in conjunction with the VM/370 Release 6 System Control Program (SCP), it becomes a functional operating system that provides extended features to the Control Program (CP) and Conversational Monitor System (CMS) components of VM/370 Release 6. VM/SP adds no additional functions to the Remote Spooling Communications Subsystem (RSCS) component of VM/370. However, you refers to the combination of the DOS/VSE system control program and the VSE/Advanced Functions Program Product. "DOS", in certain cases, is still used as a generic term. For example, disk packs initialized for use with VSE or any predecessor DOS or DOS/V~E system may be referred to as DOS disks. CMS/DOS refers to the DOS-like simulation environment provided under the eMS component of the VM/SP. EXEC refers to EXECs using the System Product Interpreter (REXX), EXEC 2, or CMS EXEC languages. System/370 applies to the 4300 and 303X series of processors. The following terms in this publication refer to the indicated support devices: 3066 refers to the IBM 3066 System Console. 3088 refers to the IBM 3088 Multisystem Communications Unit (MCU) Models 1 and 2. 3262 refers to the IBM 3262 Printer, Models 1, 5, and 11. 3262 Models 3 and 13 are supported remotely as 3287 printers. 3270 refers to a series of display devices, namely, the IBM 3275, 3276 (referred to as a Controller Display Station), 3277, 3278, and 3279 Display Stations, and the 3290 Information Panel. A specific device type is used only when a distinction is required between device types. Information about display terminal use also applies to the IBM 3138, 3148, and 3158 Display Consoles when used in display mode, unless otherwise noted. Glossary of Terms and Abbreviations 389 3285 or 3286 printer references also pertain to the IBM 3287, 3288, and 3289 printers, unless otherwise noted. 3330 refers to the IBM 3330 Disk Storage, Models 1,2, or 11; the IBM 3333 Disk Storage and Control, Models 1 or 11; and the 3350 Direct Access Storage operating in 3330 compatibility mode. 3480 refers to the IBM 3480 Magnetic Tape Subsystem. 3430 refers to the IBM 3430 Magnetic Tape Subsystem. 3800 refers to the IBM 3800 Printing Subsystems, Models 1, 3, and 8. A specific device type is used only when a distinction is required between device types. References to the 3800 Model 3 apply to both Models 3 and 8 unless otherwise explicitly stated. The IBM 3800 Model 8 is available only in selected world trade countries. 3340 refers to the IBM 3340 Direct Access Storage Facility and the 3344 Direct Access Storage. 3350 refers to the IBM 3350 Direct Access Storage Device when used in native mode. 4245 refers to the IBM 4245 Line Printer. 3370 refers to the IBM 3370 Direct Access Storage Model. 4248 refers to the IBM 4248 Printer. 3375 refers to the IBM 3375 Direct Access Device. 4250 refers to the IBM 4250 Printer. 3380 refers to the IBM 3380 Direct Access Storage. The Speed Matching Buffer Feature (No. 6550) for the 3380 supports the use of extended count-key-data channel programs. 4361 refers to the IBM 4361 Model Groups 3, 4, and 5 Processor. 4381 refers to the IBM 4381 Model Groups 1 and 2 Processor. 3422 refers to IBM 3422 Magnetic Tape Subsystem. 390 VM/SP eMS for System Programming Glossary CMS commands. The CMS system disk can have extensions, usually the Y-disk. This glossary defines new terms and all-capital abbreviations related to the VM/SP. This glossary is especially oriented for readers of the VM/ SP eMS for System Programming. Therefore, some terms already defined in the VM/SP Library Guide, Glossary, and Master Index, SC19-6207, do not appear here or may be defined slightly differently. Another glossary you may refer to is the IBM Vocabulary for Data Processing, Telecommunications, and Office Systems. Count-Key-Data. Those DASD devices whose architecture defines variable size records consisting of count, key, and data fields. CSW. channel status word DAT. dynamic address translation. DCSS. discontiguous shared segments. auxiliary storage. Data storage other than main storage; in VM/SP, auxiliary storage is usually a direct access device. CAW. channel address word CCW. channel command word channel address word (CAW). An area in storage that specifies the location in main storage at which a channel program begins. channel command word (CCW). A double word at the location in main storage specified by the channel address word. One or more CCWs make up the channel program that directs data channel operations. channel status word (CSW). An area in storage that proyides information about the termination of input/output operations. Channel-to-Channel Adapter. A hardware device that can be used to connect two channels on the same computing system or on different systems. deadline priority. An algorithm for determining when a virtual machine receives the next time slice. directory. For VM/SP, a CP disk file that defines each virtual machine's normal configuration: the userid, password, normal and maximum allowable virtual storage, CP command privilege class or classes allowed, dispatching priority, logical editing symbols to be used, account number, and CP options desired. discontiguous shared segments (DCSS). Synonymous with discontiguous segment. discontiguous segment. A 64K segment of storage that was previously loaded and saved and assigned a unique name. The segment(s) can be shared among virtual machines if the segment(s) contain reentrant code. DPA. dynamic paging area dynamic address translation. In System/370 virtual storage systems, the change of a virtual address to a real storage address during execution of an instruction. dynamic paging area (DPA). An area of real storage that CP uses for virtual machine pages and pageable CP modules. CKD. Count-Key-Data concurrently. Concerning a mode of operation that includes the performance of two or more operations within a given interval of time. CMS system disk. The virtual disk (S-disk) that contains the CMS nucleus and the disk-resident FBA. Fixed-block architecture. file status table (FST). A table that describes the attributes of a file on a CMS disk, including filename, filetype, filemode, date last written, and other status information. Glossary of Terms and Abbreviations 391 Fixed-Block Architecture (FBA). Those DASD devices whose architecture uses fixed blocks or records of 512 bytes. FST. file status table GCS. Group Control System facility minidisk. Synonym for virtual disk. missing interrupt handler (MIH). A facility of VM/SP that detects incomplete I/O conditions by monitoring I/O activity. It also tries to correct incomplete I/O conditions without operator intervention. Group Control System. An operating envi'ronment that provides a problem state OS subtasking environment with common storage access for members of a virtual machine group. guest virtual machine. A virtual machine in which an operating system is running. named system. A collection of saved pages a user can IPL or load by name. native mode. A mode in which an operating system is run stand-alone on the real machine instead of under VM/SP. in-queue virtual machines. A virtual machine on the run list waiting to be dispatched. A virtual machine is added to the run list if its projected working set size is less than or equal to the number of real page frames available for allocation in the dynamic paging area. An in-queue virtual machine may be, but is not necessarily, runnable. interactive. (1) An application in which each user entry calls forth a response from a system or program. (2) The classification given to a virtual machine depending on this virtual machine's processing characteristics. When a virtual machine uses less than its allocated time slice because of terminal I/O, the virtual machine is classified as being interactive. See also non-interactive. Interactive Problem Control System (IPCS or VM/SP IPCS). A component of VM/SP that permits on-line problem management, interactive problem diagnosis, on-line debugging for disk-related CP or virtual machine abend dumps, problem tracking, and problem reporting. noninteractive. The classification given to a virtual machine depending on this virtual machine's processing characteristics. When a virtual machine usually uses all its allocated time slice, it is classified as being noninteractive or compute bound. See also interactive. non-resident pages. Pages whose contents are on DASD but not in real storage. A page is considered nonresident when an attempt to load its real address returns a nonzero condition code. I;l L:J page frame. A block of 4096 bytes of real storage. page table. A table in CP that indicates whether a page is in real storage and matches virtual addresses with real storage addresses. preferred paging area. A special area of auxiliary storage where frequently used pages are paged out. It provides high speed paging. prefix storage area (PSA). a page zero of real storage that contains machine-used data areas and CP global data. logon. The procedure by which a user begins a terminal session. logoff. The procedure by which a user ends a terminal session. 392 VM/SP CMS for System Programming program status word (PSW). An area in storage used to indicate the order in which instructions are executed, and to hold and indicate the status of the computer system. Synonymous with processor status word. segments. Each entry indicates the length, location, and availability of a corresponding page table. program temporary fix (PTF). A temporary solution or by-pass of a problem diagnosed by IBM field engineering as the result of a defect in a current unaltered release of the program. shadow page table. A table that maps real storage allocations (first level storage) to a virtual machine's virtual storage (third level storage) for use by the real machine in its paging operations. PSA. Prefix storage area. spool, spooled, spooling. Relates to the reading of input data streams and the writing of output data streams on auxiliary storage devices. PSW. Program status word, or processor status word. PTF. Program temporary fix. queue-add. The action by the system scheduler, DMKSCH, of placing a runnable virtual machine on the list of virtual machines that can be given control of a processor. queue-drop. The action by the system scheduler, DMKSCH, of removing a virtual machine from the list of virtual machines that can be given control of a processor. standalone dump. A program used to print the contents of storage that runs in a virtual machine not under control of an operating system such as CMS. system profile. The system profile is an EXEC, SYSPROF EXEC, that resides in a DCSS (discontiguous saved segment) or on a system disk and is called by CMS initialization. It contains some initialization function and provides a means for installations to override the default CMS environment by tailoring the EXEC to suit the installation. time sharing. Sharing of computer time and resources. real machine. The actual processor, channels, storage, and I/O devices required for operation of VM/SP. virtual address. An address that refers to virtual storage or a virtual I/O device address. It must, therefore, be translated into a real storage or I/O device address when it is used. S-disk. See CMS system disk. S-STAT. A block of storage that contains the file status tables (FSTs) associated with the S-disk. The FSTs are sorted so that a binary search can be used to search for files. The S-STAT usually resides in the CMS nucleus so it can be shared. Only files with filemode of 2 will have their associated FSTs in the S-STAT. segment. A contiguous 64K area of virtual storage (not necessarily contiguous in real storage) that is allocated to virtual m~chine or CPo segment table. A table used in dynamic address translation to control user access to virtual storage virtual disk. A logical subdivision (or all) of a physical disk storage device that has its own address, consecutive storage space for data, and an index or description of the stored data so that the data can be accessed. A virtual disk is also called a minidisk. virtual machine. A functional simulation of a computer and its associated devices. Virtual Machine Communication Facility (VMCF). A CP function that provides a method of communication and data transfer between virtual machines operating under the same VM/SP systems: Glossary of Terms and Abbreviations 393 virtual storage. Storage space that can be regarded as addressable main storage by the user of a computer system in which virtual addresses are mapped into real addresses. The size of virtual storage is limited by the addressing scheme of the computing system and by the amount of auxiliary storage available, and not by the actual number of main storage locations. Y -disk. An extension of the eMS system disk. Y-STAT. A block of storage that contains the file status tables (FSTs) associated with the V-disk. The FSTs are sorted so that a binary search can be used to search for files. The Y-STAT usually resides in the eMS nucleus so it can be shared. Only files with filemode of 2 will have their associated FSTs in the Y-STAT. / 394 VM/SP eMS for System Programming Here is a list of IBM books that can help you use your system. If you don't see the book you want in this list, you might want to check the IBM System/370, 30xx, and 4300 Processors Bibliography, GC20-0001. o Prerequisite Publications IBM System/360 Principles of Operation, GA22-6821 IBM System/370 Principles of Operation, GA22-7000. Q Books About VM/SP Virtual Machine/System Product: CP for System Programming, SC24-5285 Transparent Services Access Facility Reference, SC24-5287 General Information, GC20-1838 Introduction, GC19-6200 CMS Command Reference, SC19-6209 CMS User's Guide, SC19-6210 Installation Guide, SC24-5237 System Messages and Codes, SC19-6204 OLTSEP and Error Recording Guide, SC19-6205 Terminal Reference, SC19-6206 Library Guide, Glossary, and Master Index, SC19-6207 Operator's Guide, SC19-6202 EXEC 2 Reference, SC24-5219 System Product Editor User's Guide, SC24-5220 System Product Editor Command and Macro Reference, SC24-5221 System Product Interpreter User's Guide, SC24-5238 System Product Interpreter Reference, SC24-5239 Virtual Machine System Facilities for Programming, SC24-5288 Bibliography 395 Diagnosis Guide, LY24-5241 Running Guest Operating Systems, 8C19-6212 Note: The V1'.l/SP Library Guide, Glossary, and Master Index, GC19-6207 describes all the VM/8P books and contains an e~panded glossary and master index to all the books in the VM/8P library. • Other Publications IBM VM/SP Programmer's Guide to the Server-Requester Programming Interface for VM/ SP, 8C24-5291 IBM 3211 Printer, 3216 Interchangeable Train Cartridge, and 3811 Printer Control Unit Component Description and Operator's Guide, GA24-3543 IBM 3262 Printers 1 and 11 Component Description, GA24-3733 IBM 3270 Information Display System Library User's Guide, GA23-0058 IBM Virtual Machine Facility/B70: Performance/Monitor Analysis Program,8B21-2101 ACF/VTAM VTAM General Information (for VM), GC30-3246 Network Program Products Planning, 8C23-0110 VTAM Installation and Resource Definition, 8C23-0111 VTAM Customization, 8C23-0112 VTAM Operation, 8C23-0113. VM/8P Remote 8pooling Communications 8ubsystem Networking (R8C8 Networking) Version 2 Planning and Installation, 8H24-5057 Operation and Use, 8H24-5058 Diagnosis Reference, L Y24-5228 VM/SP Data Areas and Control Block Logic, Volume 2 Conversational Monitor System (CMS), LY24-5221 VM/ SP System Logic and Problem Determination, Volume 2 Conversational Monitor System (CMS), L Y20-0893 OS/ VS Data Management Macro Instructions, GC26-3793 OS/VS Supervisor Service and Macro Instructions,GC27-6979 If you use the IBM 3767 Communication Terminal as a virtual machine console, the IBM 3767 Operator's Guide, GA18-2000 may also be helpful. 396 VM/8P eM8 for 8ystem Programming Note: References in text to titles of corequisite VMjSP Entry and VM/SP publications are given in abbreviated form. Bibliography 397 The VM/SP Library (Part 1 of 3) Evaluation Index Z '/ /' General Information GC20-1838 Introduction V GC19-6200 Library Guide, Glossary, and Master Index GC19-6207 V Installation Planning '/ /' Planning Guide and Reference SC19-6201 Running Guest Operating Systems V /' /' GC19-6212 Distributed Data Processing Guide Release 5 Guide I SC24-5290 /' ~ SC24-5241 Installation Guide SC24-5237 I /' '/ Application Development Guide SC24-5247 /' Operator's Guide Programmer's Guide to the SRPI for VM/SP I I Operation Applications SC24-5291 SC19-6202 I Reference Summaries 398 V V To order all of the Reference Summaries. use order number SBOF-3242 Commands (General User) Commands (Other than General User) SP Editor Command Reference Summary EXEC 2 Reference Summary Sys.Prod Interpreter Reference Summary SX20-4401 SX20-4402 SX24-5122 SX24-5124 SX24-5126 CMS Primer Summary of Commands CMS Primer Line-Oriented Summary of Commands Problem Reporting Summary (Poster) Summary of End Use Tasks and Commands (Poster) SX24-5151 SX24-5159 VM/SP eMS for System Programming SX24-5171 SX24-5173 ,/ Tho "r~~/slP library (IPQr~ 2 of 3) End Use '/ /' Terminal Reference GC19-6206 SC24-5236 V /' System Product Editor Command and Macro Reference SC24-5221 SC24-5220 V /' CMS Primer for LineOriented Terminals SC24-5242 I /' System Product Editor User's Guide '/' /' CMS Primer CMS User's Guide SC19-6210 V '/ SC24-5238 I SC19-6209 I System Product Interpreter Reference SC24-5239 V CMS Macros and Functions Reference SC24-5284 I L '/ System Product Interpreter User's Guide /' CMS Command Reference I '/ CP Command Reference EXEC 2 Reference SC24-5219 V SC19-6211 V V '/ Quick Reference SX20-4400 I Diagnosis /' /' System Messages and Codes SC19-6204 II L SC24-5264 Service Routines Program Logic V /' Problem Determination Vol. 1 (CP) LY20-0892 / LY24-5220 LY20-0890 Problem Reporting Guide I '/ Data Areas and Control Blocks Vol. 1 (CP) LY20-0893 SC24-5282 LY24-5221 LY24-5241 V GCS Diagnosis Reference V LY24-5239 V /' Data Areas and Control Blocks Vol. 2 (CMS) V /' VM Diagnosis Guide /' Problem Determination Vol. 2 (CMS) IJ '/ /' /' System Messages CrossReference OLTSEP and Error Recording Guide IJ SC19-6205 VM Problem Determination Reference Information LX23-0347 I VM CP Internal Trace Table (Poster) LX24-5202 Bibliography 399 The Vrtll!SP Llbrsry (Psrt 3 of 3) Administration /' ~ VM System Facilities for Programming /' CP for System Programming SC24-5288 SC24-5285 I SC24-5286 I '/ /' CMS for System Programming GCS Command and Macro Reference TSAF Reference SC24-5287 V V SC24-5250 I Auxiliary Communication Support ~ /' /' /' VTAM Installation and Resource Definition VTAM Customization VTAM Operation VTAM Messages and Codes SC23-0111 SC23-0112 SC23-0113 SC23-0114 VTAM Reference Summary SC23-0135 I /' V "/ SC23-0115 V /' SC23-0116 /' RSCS Noh-/orking Version 2 General Information RSCS Networking Version 2 Planning and Installation GH24-5055 V SH24-5057 VM/PassThrough Facility General Information VM/PassThrough Facility Guide and Reference VTAM Data Areas (VM) VTAM Diagnosis Reference V LY30-5582 I "/ "/ VTAM Diagnosis Guide VTAM Programming V V LY30-5583 V "/ /' RSCS Networking Version 2 Operation and Use RSCS Networking Version 2 Ref. Summary RSCS Networking Version 2 Diagnosis Reference SX24-5135 I "/ SH24-5058 V LY24-5228 I /' GC24-5206 V SC24-5208 ..rl ,L..-_ _ _ _ VM/PassThrough Facility Logic LY24-5208 ,1--_ _ _ _ -11 ,/ 400 VM/SP eMS for System Programming ISpecial Characters I + and - subcommands of DUMPS CAN command See DIAG &name subcommand of DUMPS CAN command See DIAG $$BCLOSE transient 268 $$BDUMP transient 268 $$BOPEN transient 268 $$BOPENR transient 268 $$BOPNLB transient 268 $$BOPNR2 transient 268 $$BOPNR3 transient 268 $$BOSVLT transient 269 $LISTIO EXEC file 217 *BLOCKIO (DASD Block I/O System Service) See SFPROG *CCS (SNA Console Communication Services) See SFPROG *LOGREC (Error Logging System Service) See SFPROG *MSG (Message System Service) See SFPROG *MSGALL (Message All System Service) See SFPROG *NCCF See SFPROG *SIGNAL (Signal System Service) See SFPROG *SPL (Spool System Service See SFPROG / / record 176, 231 /JOB control cards 335 ? subcommand of DUMPSCAN command See DIAG abend (abnormal termination) clearing file definitions 166 CMS abend exit routine processing, CMS processing 5 recovery 6 DMSABW CSECT 5 information available 5 5 releasing storage 26 ABEND macro See DIAG ABEND macro (SVC 13) 193 abend messages See DIAG abend recovery process 6 abend, reason for See DIAG ABENDs See also DIAG CMS abend exit routine processing, CMS 5 processing 5 recovery 6 ABNEXIT macro 5, 351 abnormal termination (abend) See abend (abnormal termination) abnormal termination procedures See DIAG ACCEPT, IUCV and logical device support facility See SFPROG ACCESS command accessing OS data sets 161 format of 162 modules included in resident directory 339 response when you access VSAM disks 278 used with OS disks 159 access device dependent information DIAGNOSE code X'8C' See SFPROG access diagnostic information saved for protected application facility users DIAGNOSE code X'BO' See SFPROG access method services (AMS) control statements, executing 276 DEFINE CLUSTER statement 305 DEFINE control statement 305 DEFINE USERCATALOG 287 defining a master catalog 286 defining OS input/output files 294 DELETE control statement 305 executing in CMS, examples 304 functions EXPORT 307 IMPORT 307 REPRO 307 in CMS 273 in CMS/DOS 284 restrictions on using for OS and VSE users 274 These symbols are used in the index to refer to other VM and VM/SP books: ... . CPPROG-VM/SP CP for System Programming SFPROG-VM System FaclhtIes for Programmmg DIAG-VM Diagnosis Guide Index 401 return codes 277 terminal sessions 369 using tape input/output 292, 303 access method supported by OS 199 accessing access method services 276 directories of VSE libraries 224 DOS disks 211 OS disks 159 VSE system residence volume 208 accounting See CPPROG ACF/VTAM, VM/SP SNA support See SFPROG· action routines See SFPROG ACTION, VSE linkage editor control statement 241 activating the TOD-clock accounting interface DIAGNOSE code X'70' See SFPROG active disk table (ADT) 341 signalling preferred filetypes 3 ADDENTRY macro 351 adding language information for an application See SFPROG member to MACLIBs 173,228 ADSTOP command See DIAG ADT (active disk table) 341 signalling preferred filetypes 3 ALL subcommand of TRAPRED command See DIAG allocating 27 extents on OS disks 295 space for VSAM files (CMS/DOS) 290 space for VSAM files (OS) 300 storage 32 VSAM extents on OS disks and minidisks 295 alter contents of storage See DIAG altering storage contents See DIAG alternate userid DIAGNOSE code X'D4' See SFPROG AMS (access method services) control statements, executing 276 DEFINE CLUSTER statement 305 DEFINE control statement 305 DEFINE USERCATALOG 287 defining a master catalog 286 defining OS input/output files 294 DELETE control statement 305 executing in CMS, examples 304 functions EXPORT 307 IMPORT 307 REPRO 307 in CMS 273 402 VM/SP CMS for System Programming in CMS/DOS 284 restrictions on using for OS and VSE users 274 return codes 277 terminal sessions 369 using tape input/output 292, 303 AMSERV command creating tape files 303 files, examples 276 filetype 276 format of 276 functions under CMS 304 output listings 277 using to read tapes 303 APAR command See DIAG APARs (Authorized Program Analysis Reports) See DIAG APPC/VM synchronous event (type X'DC') entry See DIAG appending data to existing files 166 APPLMSG macro 351 AREGS subcommand of DUMPSCAN command See DIAG ARIOBLOK subcommand of DUMPSCAN command See DIAG ASSEMBLE command example of 66 output files produced 239 assembler language macros supported by VSE 236 assembler programs OS programs in CMS 65 overriding default definitions using ddnames 65 programs in CMS/DOS 238 source files, from OS disks 65 VSAM programs in CMS 274 assembler virtual storage requirements 345 ASSGN command assigning programmer logical unit 214 description 209 using to assign logical units 214 assigning disk devices 218 entering before program execution 245 physical devices 218 to a virtual device 218 ATTACH macro (SVC 42) 195 attached processor mode (AP) See CPPROG AUTHORIZE VMCF function See SFPROG auxiliary directories adding 339 creating 340 DMSLADAD entry point 341 establishing linkage 341 GENDIRT command 340 generating 339 initializing 340 saving resources 339 usage 339 auxiliary files description of 104 preferred 108 auxiliary processing routine to receive control during I/O operation 167 AUXPROC option of FILEDEF command 167 batch facility /JOB control cards 335 BATEXIT1 routine 335 BATEXIT2 routine 335 BATLIMIT MACRO file 335 data security 336 description 333 EXEC procedures 336 installation input 335 installing 334 IPL performance 336 resetting system limits 334 system limits 334 user-specified control language 335 BATEXIT1 routine 335 BATEXIT2 routine 335 BATLIMIT macro 335,351 BDAM restrictions on 202 support of 188, 200 BEGIN command See DIAG BLDL macro (SVC 18) 193 BLIP character 13 BLKSIZE (blocksize) 512, 1024, 2048, 4096 bytes 2 800 bytes 2 BLOCK option of FILEDEF command 165 *BLOCKIO See SFPROG blocksize (BLKSIZE) See BLKSIZE (blocksize) books copied from DOS/VSE source statement libraries 220 BOTTOM subcommand of TRAPRED command See DIAG BPAM support of 188, 200 branch entry Freemain (type X'OB') entry See DIAG branch entry Getmain (type X'OA') entry See DIAG breakpoint setting See DIAG BSAM/QSAM support of 188, 200 BSP macro (SVC 69) 198 buffers used by FSCB 78 BUFSP option in CMS/DOS 285 of the DLBL command 295 C subcommand of DUMPS CAN command See DIAG calculating storage available in your virtual machine 246 CALL command 237 CALL macro 198 calling IBM for assistance, data needed See DIAG CANCEL command 237 CANCEL VMCF function See SFPROG canceling DLBL definitions 220 user-written immediate commands 155 CAT option 285 of the DLBL command 295 catalogs clearing 289 defining in CMS/DOS 286 identifying in CMS/DOS 287 IJSUC ddname 288 job 288, 299 master 297 passwords 289, 299 sharing 279 user 298 user in CMS/DOS 287 verifying a structure 289, 300 VSAM 285, 289, 296 catalogued procedures in OS equivalent in CMS 158 CATCHECK command verifying a catalog structure 289, 300 *CCS See SFPROG CHAIN subcommand of DUMPSCAN command See DIAG changes, summary of 379 channel program modification DIAGNOSE code X'28' See SFPROG CHAP macro (SVC 44) 195 CHECK macro 198 CHKPT macro (SVC 63) 197 class override file These symbols are used in the index to refer to other VM and VM/SP books: CPPROG-VM/SP CP for System Programming SFPROG-VM System Facilities for Programming DIAG-VM Diagnosis Guide Index 403 See CPPROG classes of user privilege See CPPROG clean-up after virtual IPL by device DIAGNOSE code X'40' See SFPROG clear error recording DIAGNOSE code X'lC' See SFPROG clearing DLBL definitions 220 effect on FILEDEF definitions 166 FILEDEF definitions 166 job catalogs in CMS/DOS 289 job catalogs in OS 299 CLOSE function for SPOOL system service See SFPROG . CLOSE/TCLOSE macro (SVC 20/23) 194 closing CMS files after reading or writing 81 virtual unit record devices 85 clusters defining 305, 306 deleting 306 suballocated 305 unique 306 . CMD command used by programmable operator See SFPROG CMD option of the PER command See DIAG CMS (Conversational Monitor System) See also Conversational Monitor System (CMS) abnormal termination exit routine processing 5 processing 5 recovery 6 batch facility 333 called routine modifications to system area 62 command language 1 command processing 56 command search function 58 commands ACCESS 161 GENDIRT 340 IPL 323 OS program development 4 used with OS data sets 159 VSE program development 4 description of . 1 devices supported 21 DEVTAB (device table) 21 DISPW macro 93 DMSNUC 21 EXECs opening and closing files 81 to execute OS programs 73 file system 2 filemode 2 filename 2 filetype 2 free storage management 23 404 VM/SP CMS for System Programming function of 1 how to save it 3~1 initialization 322 interface with display terminals 88 interrupt handling 9 introduction 1 loader tables 16 macros ABNEXIT 5 DISPW 93 DMSEXS 41 DMSFREE 15, 27 DMSFRES 35 DMSFRET 33 DMSFST 339 DMSKEY 39 examples 84 FS.CB 75 GETMAIN 16 list of 351 STRINIT 24 usage· 75 managing files 2 modules DMSABN 5 DMSINA 54 DMSINT 55 DMSIOW 11 DMSITE 13 DMSITI 10 DMSITP 13 DMSITS 9,43 DMSLAD 341 DMSPAGE 34 nucleus 16 OS simulation 157 OS support 273 overlay structures 345 program development 3 PSW keys 39 register restoration 62 register usage 43 returning to called routine 61 saved system restrictions 321 simulation of VSE functions 249 storage DMSEXS macro 41 DMSFREEmacro 15 DMSFRES macro· 35 DMSFRET macro 33 DMSKEY macro 39 map 17 STRINIT macro 24 structure 15 using 15 SUB COM func'tion 59 support for OS 273 support for VSAM 273 SVC handling 43 / symbol references 21 system save area modification 62 tape volume switching 204 transient area 15 transient program area 23 user program area 23 USERSECT (user area) 21 using as compilers 4 using as data sets 159 using VSE compilers 4 VSAM support 273 VSE macros 250 VSE simulation 207 what it provides 1 XEDIT 2 CMS abend dump reading See DIAG CMS abend recovery function See DIAG CMS control block relationship SeerDIAG CMS d~bugging See DIAG CMS dump file printing See DIAG eMS IUCV See SFPROG CMS loader, controlling 68 CMS subcommand of DUMPS CAN command See DIAG CMS/DOS commands 209 considerations for execution 272 control blocks simulated by 269 DOSLKED command 240 DTFCD macro 259 DTFCN macro 261 DTFDI macro 261 DTFMT macro 262 DTFPR macro 264 DTFSD macro 265 entering the environment 208 EXCP support 269 extents 291 generating 270 invoking linkage editor 240 libraries 270 library volume directory entries 271 options BUFSP 285 CAT 285 EXTENT 285 MULT 285 VSAM 285 performance 272 physical IOCS macros 250 program development using 207 relationship to CMS and VSE 207 restrictions 272 SVC support routines 250 terminology 207 user responsibilities 270 using tape input/output 292 VM/SP directory entries 271 VSE I/O macros 249 VSE supervisor macros 249 VSE transients simulation 268 VSE volumes needed 271 VSE/VSAM macros supported 311 CMSDEV macro 351 CMSIUCV macro 351 See also SFPROG CMSLEVEL macro 351 CMSLIB MACLIB 180 CMSPOINT subcommand of DUMPS CAN command See DIAG Goding conventions See CPPROG collecting CP data See DIAG collecting virtual machine data See DIAG command access in CP See CPPROG command language, CMS 1 command syntax files, updating See SFPROG commands ACCESS 159 AMSERV 276 ASSEMBLE 65 ASSGN 209 CALL 237 CANCEL 237 CMS/DOS 209 DDR 159 developing 113 DLBL 159 DLBL command 209 DOSLIB 209 DOSLKED 209 DOSPLI 209 DSERV 209 entered from a terminal 55 ESERV 209,223 FCOBOL 209 FETCH 209 FILEDEF 159 GENMOD 209 GLOBAL 209 IPL 323 LISTDS 159 LISTIO 209 LKED 159 LOADMOD 209 MOVEFILE 159 These symbols are used in the index to refer to other VM and VMjSP books: CPPROG-VMjSP CP for System Programming SFPROG-VM System Facilities for Programming DIAG-VM Diagnosis Guide Index 405 OPTION 209 processing 54, 56 PSERV 209, 222 QUERY 210 RELEASE 159 RSERV 210, 222 SAVEFD 328 search function 58 search hierarchy for 54 SET 210 SSERV 210, 221 STATE 159 COMMENT statement 98 compilers devices assigned 216 input/output assignments 216 compressing DOSLIB files 243 members of a MACLIB 174,229 COMPSWT macro 351 configuration file for GCS See DIAG CONNECT IUCV function See SFPROG connection complete external interrupt in IUCV See SFPROG connection pending external interrupt in IUCV See SFPROG connection quiesced external interrupt in IUCV See SFPROG connection resumed external interrupt in IUCV See SFPROG connection severed external interrupt in IUCV See SFPROG console facility 88 CONSOLE function I/O interrupts 10 CONSOLE macro 12, 88, 90, 351 control blocks simulated by CMS/DOS 269 types VSE supervisor 269 used by CMS/DOS routines 269 control file description 103 for a national language See SFPROG updating example 106 control register allocation See DIAG control registers See DIAG control statements COMMENT statement 99 DELETE statement 98 in AMSERV file 276 INSERT statement 98 REPLACE statement 98 SEQUENCE statement 98 used by UPDATE command 97 406 VM/SP CMS for System Programming controlling PA2 program function key DIAGNOSE code X'54' See SFPROG Conversational Monitor System (CMS) See also CMS (Conversational Monitor System) abnormal termination exit routine processing 5 processing 5 recovery 6 batch facility 333 called routine modifications to system area 62 command language 1 command processing 56 command search function 58 commands ACCESS 161 GENDIRT 340 IPL 323,324 OS program development 4 used with OS data sets 159 VSE program development 4 description of 1 devices supported 21 DEVTAB (device table) 21 DISPW macro 93 DMSNUC 21 EXECs opening and closing files 81 to execute OS programs 73 file system 2 filemode 2 filename 2 filetype 2 free storage management 23 function of 1 how to save it 321 initialization 322 interface with display terminals 88 interrupt handling 9 introduction 1 loader tables 16 macros ABNEXIT 5 DISPW 93 DMSEXS 41 DMSFREE 15, 27 DMSFRES 35 DMSFRET 33 DMSFST 339 DMSKEY 39 examples 84 FSCB 75 GETMAIN 16 list of 351 STRINIT 24 usage 75 managing files 2 modules DMSABN 5 DMSINA 54 DMSINT 55 DMSIOW 11 DMSITE 13 DMSITI 10 DMSITP 13 DMSITS 9,43 DMSLAD 341 DMSPAGE 34 nucleus 16 OS simulation 157 OS support 273 overlay structures 345 program development 3 PSW keys 39 register restoration 62 register usage 43 returning to called routine 61 saved system restrictions 321 simulation of VSE functions 249 storage DMSEXS macro 41 DMSFREE macro 15 DMSFRES macro 35 DMSFRET macro 33 DMSKEY macro 39 map 17 STRINIT macro 24 structure 15 using 15 SUBCOM function 59 support for OS 273 support for VSAM 273 SVC handling 43 symbol references 21 system save area modification 62 tape volume switching 204 transient area 15 transient program area 23 user program area 23 USERSECT (user area) 21 using OS compilers 4 using OS data sets 159 using VSE compilers 4 VSAM support 273 VSE macros 250 VSE simulation 207 what it provides 1 XEDIT 2 CONVERT command See DIAG CONVIPCS EXEC See DIAG COpy files adding to MACLIBs 173, 228 copying books from VSE source statement libraries DOS cataloged procedure 222 DOS files into CMS files 213 220 macros from VSE libraries to add to CMS MACLIB 228 members of MACLIBs 176 members of OS partitioned data set with FILEDEF 170 modules from VSE library or SYSIN tapes 213 modules from VSE relocatable libraries 222 OS data sets into CMS files 169 VSAM files into CMS disk files 307 core image libraries, using in CMS/DOS 225 on a DOS disk 244 VSE libraries 270 CORTABLE subcommand of DUMPSCAN command See DIAG COUNT subcommand of the PER command See DIAG CP (Control Program) See CPPROG CP abend dumps, reading See DIAG CP data, recording See DIAG CP debugging' See DIAG CP FRET Trap See DIAG CP internal trace table See DIAG CP message repository See SFPROG CP SET DUMP command See DIAG CP system services See SFPROG CP trace table entries, recording See DIAG CPEREP program See DIAG CPPROG See VM/SP CP for System Programming CPRB macro 351 CPTRAP command See DIAG CPTRAP facility See DIAG CQYSECT macro 351 creating CMS files from DOS libraries 213 DOSLIB files 242 file from DOS disks and tapes 213 immediate commands 154 macro libraries example in CMS/DOS 226 from a DOS library 226 modules from VSE library or SYSIN tapes 213 CSIYTD control program See DIAG These symbols are used in the index to refer to other VM and VMjSP books: CPPROG-VMjSP CP for System Programming SFPROG-VM System Facilities for Programming DIAG-VM Diagnosis Guide Index 407 CSMRETCD macro 351 CUSTOMER PROFILE file See DIAG CVTSECT (CMS Communications Vector Table) See DIAG cylinder on 2314/2319 disk 296 on 3330 disk 297 DASD Block I/O System Service See SFPROG DASD Dump/Restore (DDR) program See DIAG data catalog sharing 279 data control block (DCB) See DCB (data control block) data extraction routine See DIAG data management See DIAG data needed before calling IBM for assistance See DIAG data security in batch facility 336 Data Set Control Block (DSCB) 199 data sets creating files 170 format of 160 identify VSAM 294 OS 159 reading, OS 161, 203 specifying a member name 166 VSAM, compatibility considerations 312 data sheet, problem inquiry See DIAG DCB (data control block) exit 165 relationship to FILEDEF command 162 DCB macro 198 DCP command See DIAG DCSS (discontiguous shared segment) . file directory information for shared disk 328 installation 55 placing Editor macros in 331 placing EXECs in 331 ddnames IJSCT 296 IJSUC 288, 299 IJSYSCT 285 in OS VSAM programs, restricted to seven characters in CMS 284 specifying with FILEDEF command 162 used when assembling source programs 238 DDR command 159 DDR program 408 VM/SP CMS for System Programming See DIAG de-edi ting VSE macros 223 DEBUG command 6 debugging a dump See DIAG debugging an AP/MP system See DIAG debugging CMS See DIAG debugging CP See DIAG debugging GCS See DIAG debugging the virtual machine See DIAG debugging tools summary See DIAG debugging TSAF See DIAG debugging, introduction See DIAG declarative macros DTFCD 259 DTFCN 261 DTFDI 261 DTFMT 262 DTFPR 264 DTFSD 265 DECLARE BUFFER IUCV function See SFPROG default DLBL definitions 220 FILEDEF definition 164 of MAC LIB MAP command 174 DEFINE control statement 305 defining cluster for VSAM space 305 clusters 306 DOS input files 284 DOS output files 284 OS data sets 159 OS input/output files 294 space for VSAM files in CMS/DOS 290 space for VSAM files in OS 300 unique clusters 306 user catalogs 298 VSAM master catalog in CMS/DOS 286 VSAM master catalog in OS 297 definition language for command syntax (DLCS» See DLCS (definition language for command syntax) DELENTRY macro 351 DELETE command 98 DELETE control statement 305 DELETE macro (SVC 9) 193 deleting a national language See SFPROG access method services function 306 members of a MACLIB 174,228 VSAM catalogs 306 VSAM clusters 306 VSAM spaces 306 DEQ macro (SVC 48) 196 DESCRIBE IUCV function See SFPROG DETACH macro (SVC 62) 197 determine virtual machine storage size DIAGNOSE code X'60' See SFPROG developing commands 113 message files 145 OS programs 4 programs 4 VSE programs 4 Device Support Facility 371 formatting temporary disks 283 device table (DEVTAB) 21 device type and features DIAGNOSE code X'24' See SFPROG device type class and values See DIAG devices assignments in CMS/DOS 214 for CMS system 21 I/O assignments 245 interrupts 12 output, restrictions in CMS/DOS 218 specifying type with FILEDEF command 163 supported by CMS 21 supported, for VSAM under CMS 319 devices, disks, cylinders, and tracks 295 DEVTAB (device table) 21 DEVTYPE macro (SVC 24) 194 DIAG See VM Diagnosis Guide DIAGNOSE code interface with a discontiguous shared segment (DCCS) See CPPROG DIAGNOSE code interface with named segments See CPPROG DIAGNOSE codes See SFPROG DIAGNOSE instruction See SFPROG diagnosing problems See DIAG directory entries 271 entries for CMS/DOS library volumes 271 directory update in-place DIAGNOSE code X'84' See SFPROG discontiguous shared segment (DCSS) See CPPROG See SFPROG Disk Operating System (DOS) core image library 244 creating CMS files 213 declarative macros DTFCD 259 DTFCN 261 DTFDI 261 DTFMT 262 DTFPR 264 DTFSD 265 disks accessing 211 compatibility with OS disks 280 determining free space 281 formatting using DSF 283 using with AMSERV 278 files used in CMS 211 for transient routines 268 hardware devices supported 249 imperative macros 267 libraries executing phases from 244 link-editing modules from 241 size considerations 243 macros supported in CMS 236 restrictions on reading in CMS 212 simulation in CMS 208 support of physical IOCS macros 250 terminal sessions 360 VSE macros under CMS 249 disks extents 295 read-only, exporting VSAM files from 307 sharing 3 temporary 283 DISP MOD option of FILEDEF command 166 dispatcher (type X'Ol') entry See DIAG dispatching virtual machines See CPPROG DISPLAY command See DIAG display data on 3270 console screen DIAGNOSE code X'58' See SFPROG display real CP data See DIAG DISPLAY subcommand of DUMPS CAN command See DIAG display terminals, CMS interface 88 display virtual data See DIAG displaying a MACLIB member 230 directories of VSE libraries 224 DLBL definitions 220 lines at terminal, WRTERM macro 84 listings from access method services 277 DISPW macro These symbols are used in the fndex to refer to other VM and VM/SP books: CPPROG-VM/SP CP for System Programming SFPROG-VM System Facilities for Programming DIAG-VM Diagnosis Guide Index 409 description of 351 format of 93 distributed system use of the programmable ~~~~ . See SFPROG DL/I programs in CMS/DOS 210 restrictions 211 DLBL command CMS operand 220 default file definitions 220 description of 209 DSN ? operand 248 entering before program execution 245 how to use in CMS/DOS 218 identifying VSAM data sets 294 identifying VSAM data sets on CMS/DOS 284 IJSYSCT ddname 285 options BUFSP 295 CAT 295 EXTENT 291,295 MULT 295 VSAM 295 relationship to ASSGN command 218 specifying extents in CMS/DOS 291 specifying multiple extents 301 SYSxxx option 218 DLBL definitions entering in a CMS EXEC procedure 247 using the HX command 220 DLCS (definition language for command syntax) coding command syntax 117, 144 coding statements 114 converting a DLCS file 115 creating a DLCS file 130, 132 description of 113 DLCS statement 118 example 115 types of statements 114 DMKSP MACLIB 236 DMMTAB communication table See DIAG DMSABN 6 DMSABN macro 5, 351 See also DIAG DMSABW CSECT 5 DMSEXS macro description of 351 formatof 41 DMSFRE service routines 35 DMSFREE macro allocating nucleus free storage 32 allocating storage 27 allocating user free storage 32 description of 351 error codes 37 format of 27 free storage management 27 nucleus free storage 15, 23 storage pointers 29 410 VM/SP CMS for System Programming TYPE = NUCLEUS parameter 32 TYPE = USER parameter 32 user free storage 15, 23 DMSFRES macro error codes 37 format of 35 DMSFRET macro description of 351 error codes 37 format of 33 releasing storage 33 DMSFRT CSECT 29 DMSFST macro description of 351 format of 339 DMSINA module 54 DMSINT module 6, 55 DMSIOW module 11 DMSITE module 13 DMSITI module 10 DMSITP module 13 DMSITP routine See DIAG DMSITS module 9, 43, 63 DMSKEY macro description of 351 format of 39 DMSLAD module 341 DMSNUC DEVTAB (device table) 21 structure of 21 USERSECT (user area) 21 within CMS storage 15 DMSPAG module 34 DMSSP MACLIB 180, 235 DMSTVS module 204 DMSXFLPT XEDIT routine 87 DMSXFLRD XEDIT routine 87 DMSXFLST XEDIT routine 86 DMSXFLWR XEDIT routine 87 DOS (Disk Operating System) core image library 244 creating CMS files 213 declarative macros DTFCD 259 DTFCN 261 DTFDI 261 DTFMT 262 DTFPR 264 DTFSD 265 disks accessing 211 compatibility with OS disks 280 determining free space 281 formatting using DSF 283 using with AMSERV 278 files used in CMS - 211 for transient routines 268 hardware devices supported 249 imperative macros 267 libraries executing phases from 244 link-editing modules from 241 size considerations 243 macros supported in CMS 236 restrictions on reading in CMS 212 simulation in CMS 208 support of physical IOCS macros 250 terminal sessions 360 VSE macros under CMS 249 DOSLIB command compressing DOSLIBs 242 description of 209 DOSLKED command description of 209 using 225, 240 DOSLNK files used by DOSLKED command 241 used in CMS/DOS 241 DOSMACRO MACLIB 181 DOSPLI command 209 DOSPOINT subcommand of DUMPS CAN command See DIAG DOWN subcommand of TRAPRED command See DIAG DSCB (Data Set Control Block) 199 DSERV command creating MAP files 224 description of 209 examples 224 DSN operand of DLBL command 219 DSORG option of FILEDEF command 165 DTFCD macro 259 DTFCN macro 261 DTFDI macro 261 DTFMT macro 262 DTFPR macro 264 DTFSD macro 265 dummy data set name specified on FILEDEF command 163 DUMP command See DIAG dump debugging See DIAG dump, used in problem determination See DIAG DUMPID subcommand of DUMPS CAN command See DIAG dumping to DASD See DIAG dumping to printer See DIAG dumping to tape See DIAG DUMPSCAN command and sub commands See DIAG DUMPSCAN scroll interface See DIAG dynamic linkage 59 dynamic load over lay 347 dynamic loading . TXTLIB members 70 editing error messages DIAGNOSE code X'5C' See SFPROG END subcommand of DUMPS CAN command See DIAG end, abnormal See abend (abnormal termination) ENQ macro (SVC 56) 196 entering DLBL definitions in CMS EXEC procedure 247 file identifications 163 lines at terminal, during program execution 84 entry points determining for program execution 70 displayed following FETCH command 244 specified using OS entry statement 182 EPLIST (extended PLIST) first form 46 second form 47 EPLIST macro· 351 error codes DMSFREE 37 DMSFRES 37 DMSFRET 37 Error Logging System Service See·SFPROG error messages editing DIAGNOSE code X'5C' See SFPROG ESERV command adding MACRO files created by ESERV program 223 description of 209 examples 223 using 223 ETRACE command See DIAG ETRACE GROUP See DIAG examine real storage· DIAGNOSE code X'04' See SFPROG examining output listings from access method services 277 EXCP macro (SVC 0) 192 EXCP supported by CMS/DOS 269 EXEC action routines See SFPROG EXEC procedures entering FILEDEF defintions 73 These symbols are used in the fndex to refer to other VM and VMjSP books: CPPROG-V~jSP C.P for. System Programming SFPROG-VM System Facilities for Programming DIAG-VM DIagnosIs GUIde Index 411 for AMSERV 309 for CMS batch 336 for VSAM 309 in CMS/DOS 247 register contents 248 to execute VSE programs 247 using 73 executing access method services in EXEC procedure 309 DOS phases 244 DSF programs 283 OS program restrictions 66 phases from core image 244 programs 66 programs in CMS/DOS 243 restrictions DL/I programs in CMS/DOS 211 OS programs in CMS 66 TEXT files 66, 67 VSAM programs 274 VSE procedures 220 exit routine processing 5 EXIT/RETURN macro (SVC 3) 192 EXPORT access method services function 307 exporting VSAM data sets 307 extended control PSW description See DIAG extended PLIST (EPLIST) See EPLIST (extended PLIST) EXTENT option of DLBL command 285, 295 extents allocating on OS disks and minidisk 295 availability of 281 determining for VSAM functions 282 entering in CMS/DOS 291 information when defining VSAM master catalog 286 multiple in CMS/DOS 291 multiple in OS 301 multivolume 291, 301 External Attribute Buffer (XAB) See SFPROG external interrupt (type X'02') entry See DIAG external interrupts See also CPPROG BLIP character 13 HNDEXT macro 13 timer 13 external interrupts in IUCV See SFPROG external references, resolving 68 external tracing facilities, GCS See DIAG extra references resolving 68 EXTRACT macro (SVC 40) 195 extracting a member from a MACLIB 175 412 VM/SP CMS for System Programming FBD (file block descriptor) 30, 31 FCB (file control block) 43 FCOBOL command 209 FDISPLAY subcommand of DUMPS CAN command See DIAG FEEDBACK command used by programmable operator See SFPROG feedback file See SFPROG FEOV macro (SVC 31) 195 FETCH command description of 209 loading phases in CMS/DOS 225 START option 244 fetching core image phases for execution in CMS/DOS 244 file block descriptor (FBD) 30, 31 file control block (FCB) 43 file directory information 328 file status table (FST) See FST (file status table) file system 2 file system control block (FSCB) See FSCB (file system control block) FILEDEF command AUXPROC option 167 BLOCK option 165 default definition 164 device type, specifying 163 DISP MOD option 166 DSORG option 165 dummy data set name specified 163 entering file identifications 163 establishing a file definition for a member 230 file format, specifying 165 guidelines for entering 162 how to use 162 issued by assembler, overriding 238 MEMBER option 166 options AUXPROC 167 BLOCK 165 DISP MOD 166 DSORG 165 MEMBER 166 PERM 166 RECFM 165 SYSPARM 168 override default file definitions 65 PERM option 166 RECFM option 165 SYSPARM option" 168 used with OS data sets 159 FILEDEF defintions clearing 166 displaying 67 making with FILEDEF command 162 filemode 2 filename 2 files auxiliary 104 blocksize (BLKSIZE) 2 closing 81 creating from DOS libraries 213 creating from OS data sets 170 defining 284 defining and allocating space 300 defining OS input and output 294 deleting records 98 described by FSCB 75 DOS 211 format information 165 format, specifying on FILEDEF command 165 handling OS data residing on CMS disks 188 handling OS data residing on OS disks 189 identification 2, 219 inserting records 98 management, CMS 2 manipulating 3, 75 multivolume identification 292, 302 opening 81 output produced by ASSEMBLE command 239 reading 79 reading VSAM tape 294 replacing records 98 sequence numbers in source files 97 size, determining 2 support of OS format 199 VSAM, allocating 290 VSAM, defining 290 writing 79 filetype preferred 3 used in file identification 2 FIND macro (SVC 18) 194 finding discontiguous shared segment DIAGNOSE code X'64' See SFPROG FINDSYS function See SFPROG FOB (font offset buffer) See CPPROG foreign languages See SFPROG FORMAT subcommand of TRAPRED command See DIAG formatting files 165 OS and DOS disks 283 temporary disks 283 free chain element format 31 free storage DMSFREE macro- 27 GETMAIN macro 24 managing 23 nucleus 23 user 23 FREEDBUF macro (SVC 56) 196 FREELOWE 246 FREEMAIN macro releasing storage 26 FREEMAIN macro (SVC 5) 192 Freemain via SVC (type X'09') entry See DIAG FREETAB storage table 28 FREEWORK (DMKFRE and DMKFRT save area) See DIAG FRERESPG 246 FSCB (file system control block) creating 75 fields defined 75 format of 75 modifying for read/write operations 78, 79 using 78 using with I/O macros 79 FSCB macro creating 75 description of 352 FSCBD macro description of 352 generating DSECT for FSCB 80 FSCLOSE macro description of 352 example 81 FSERASE macro description of 352 usage 82 FSOPEN macro 352 FSPOINT macro 352 FSREAD macro description of 352 example 79 reading disk files 79 FSST ATE macro 352 FST (file status table) 158, 339 FSWRITE macro description of 352 example 80 writing disk files 79 full-screen console service 88 G subcommand of DUMPS CAN command See DIAG GCS configuration file See DIAG GCS debugging These symbols are" used in the index to refer to other VM and VM/SP books: CPPROG-VM/SP CP for System Programming SFPROG-VM System Facilities for Programming DIAG-VM Diagnosis Guide Index 413 See DIAG GCS dumping facilities See DIAG GCS dumps, analyzing See DIAG GCS dumps, initiating See DIAG GCS external tracing facilities See DIAG GCS internal trace table See DIAG GCS internal trace table formats See DIAG GDUMP command See DIAG GENDIRT command creating auxiliary directories 342 format of 340 general I/O DIAGNOSE code X'20' See SFPROG generate accounting records for the virtual user DIAGNOSE code X'4C' See SFPROG generating CMS/DOS 270 VSE system 270 GENIMAGE command See CPPROG GENIMAGE service program See CPPROG GENMOD command See also DIAG creating .program modules 71 creating user-written CMS command 71 description of 209 GET command used by programmable operator See SFPROG GET macro 201 GETMAIN macro free element chain 25 storage management 16, 24 storage maximum 25 GETMAIN macro (SVC 4) 192 Getmain via SVC (type X'08') entry See DIAG GETPOOL/FREEPOOL macro 192 getting national languages on your system See SFPROG GLOBAL command identify TXTLIBs 182 in CMS/DOS 209 used to identify DOSLIBs 243 used to identify macro libraries 180 used to identify macro libraries in CMS/DOS 226 used to identify TXTLIBs 181 GTF header See DIAG GTRACE (type X'OE') entry See DIAG 414 VM/SP CMS for System Programming GTRACE macro See DIAG GUESTR option of PER command See DIAG GUESTV option of PER command See DIAG hash table complex (HASHTAB) See HASHTAB (hash table complex) HASHTAB (hash table complex) 2 HELP files HELP subcommand of DUMPS CAN command See DIAG HEX subcommand of TRAPRED command See DIAG history information, saving 69, 72, 183 HNDEXT macro 13, 352 HNDINT macro 352 HNDIUCV macro 352 See also SFPROG HNDSVC macro 352 HOSTCHK statement See SFPROG HX (Halt Execution) immediate command effect on DLBL definitions 220 HX subcommand of DUMPS CAN command See DIAG hyperblock mapping table (HYPMAP) See HYPMAP (hyperblock mapping table) HYPMAP (hyperblock mapping table) 2 I/O (input/output) assignments 216, 217 defining files 67 defining VSAM files 284 device assignments in CMS/DOS 214, 245 files, defining 67 interrupt handler in DMSITI module 10 interrupts 10 listing assignments 217 macros 249 tape 292 tapes 303 I/O interrupt (type X'03') entry See DIAG IDENTIFY macro (SVC 41) 195 IDENTIFY VMCF function See SFPROG identifying macro libraries 180 macro libraries to search in CMS/DOS 226 master catalog for VSAM in CMS/DOS 286 multivolume VSAM files in CMS/DOS 292 multivolume VSAM files in OS 302 VSAM master catalog in OS 297 lIP (ISAM Interface Program) 310 IJSYSCL ddname defined in CMS/DOS 219 IJSYSCT ddname 296 IJSYSRL ddname defined in CMS/DOS 219 IJSYSSL ddname defined in CMS/DOS 219 IMMBLOK macro 352 IMM CMD macro 352 immediate commands created by user 154 imperative macros 267 IMPORT access method services function 307 importing VSAM data sets 307 INCLUDE command creating program modules 71 issuing 68 options AUTO 69 CLEAR 69 DUP 69 HIST 69 LIBE 69 ORIGIN 69 RESET 69 RLDSAVE 69 VSE linkage editor control statement, specifying in 242 INDICATE command See DIAG INITIATE logical device support facility function See SFPROG input spool file manipulation DIAGNOSE code X'14'. See SFPROG input/output (I/O) See I/O (input/output) INSERT statement 98 Installation Discontiguous Shared Segment (DCSS) 55 installing CMS batch machine 334 installing the programmable operator facility See SFPROG Inter-User Communications Vehicle (IUCV) See SFPROG Interactive Problem Control System (IPCS) See DIAG internal trace table formats, GCS See DIAG internal trace table, CP See DIAG internal trace table, GCS See DIAG internal trace table, TSAF See DIAG internal tracing facilities, GCS See DIAG interrupt handler, DMSITI module 10 interrupt handling See CPPROG interrupts CMS macros for handling 85 DMSIOW module 11 DMSITE module 13 DMSITI module 10 DMSITP module 13 DMSITS module 9 external interrupts 13 input/output interrupts 10 machine check interrupts 13 printer interrupts 12 program interrupts 13 punch interrupts 12 reader interrupts 12 SVC SVC interrupts 9, 43 terminal interrupts 11 user-controlled device interrupts 12 INTSVC for SVC handling routine CMS SVCs 10 internal linkage SVC 9 invoking the programmable operator facility See SFPROG IPCS (Interactive Problem Control System) See DIAG IPCS interface files See DIAG IPCS variables See DIAG IPCSDUMP command See DIAG IPCSMAP subcommand of DUMPS CAN command See DIAG IPL (Initial Program Load) See CPPROG IPL command BATCH parameter 333 description of 323 format of 324 NOSPROF parameter 333 SAVESYS parameter 324 IPL performance using saved system 336 ISAM CMS restriction 161 CMS/DOS restriction 212 ISAM Interface Program (lIP)) 310 issue SVC 76 from a second level virtual machine DIAGNOSE code X'48' See SFPROG ITRACE command See DIAG IUCV (Inter-User Communications Vehicle) See SFPROG IUCV functions These symbols are used in the index to refer to other VM and VM/SP books: CPPROG-VM/SP CP for System Programming SFPROG-VM Sy~tem Facilities for Programming DIAG-VM Diagnosis Guide Index 415 See SFPROG IUCV macro instruction See SFPROG IUCV subcommand of DUMPSCAN command See DIAG job control cards (fJOB) 335 job control language equivalent in CMS journaling See CPPROG 158 keys DMSEXS macro 41 DMSKEY macro 39 PSW 39 keys, storage protection 38 label DOS disks 286 OS VSAM disks, determining for AMSERV 297 using VSAM tapes in CMS/DOS 294 using VSAM tapes in OS 303 LANGBLK macro 352 LANGGEN command See SFPROG LANGMERG command See SFPROG language, CMS command 1 languages, national See SFPROG LGLOPR statement See SFPROG libraries CMS/DOS 270 copying modules from 222 DOS core image 225 DOS libraries in CMS/DOS 2~0 DOS/VSE source statement used in CMS 221 programs, CMS/DOS 271 types LOADLIBs 171 MACLIBs 171 TXTLIBs 171 using directories 224 volumes for CMS/DOS directory entries 271 LINEDIT macro 352 416 VM/SP CMS for System Programming LINERD macro 352 LINEWRT macro 352 LINK command See CPPROG link edit in CMS/DOS 240 modules form DOS relocatable libraries 242 output 242 specifying control statements 241 TEXT files 241 LINK macro (SVC 6) 192 linkage OS control statements supported by TXT LIB command 181 linkage editor map created by DOS/VSE linkage editor 243 option of VSE ACTION control statement, effect in CMS/DOS 243 LIOCS routines suppo.cted by CMS/DOS 268 LISTCAT access methods services function 277 LISTCRA access methods services function 277 LISTDS command listing DOS files 211 extents occupied by VSAM files 281 free space extents 281 OS and DOS disks 281 OS and DOS files 281 used with OS data sets 159 listing information about MACLIB members 229 input/output assignments 217 listing members of a MACLIB 176 logical unit assignments in CMS/DOS 217 MACLIB members 231 LISTING file changing filename 278 created by AMSERV command 277 created by assembler, output filemode 65 created by ESERV command 223 LISTIO command 209 listing device assignments 217 LKED command description 159 specifying input to 186 using 186 LOAD command See also DIAG creating program modules 71 issuing 68 loading TEXT files 67 options AUTO 69 CLEAR 69 DUP 69 HIST 69 LIBE 69 ORIGIN 69 RESET 69 RLDSAVE 69 START 67 LOAD macro (SVC 8) 192 load map generation See DIAG load maps See also DIAG created by CMS loader 69 produced by LOAD and INCLUDE commands 69 loader control statements 69 controlling the CMS loader 68 loader tables in CMS 16 loader terminate (LDT) control statement usage 182 loading core image phases into storage for execution 244 discontiguous shared segment DIAGNOSE code X'64' See SFPROG programs into storage 71 LOADLIBs 171 LOADMOD command 209 LOADSYS function See SFPROG LOADTBL command used by programmable operator See SFPROG LOCATE (UP) subcommand of DUMPS CAN command See DIAG LOG command used by programmable operator See SFPROG log file See also SFPROG updating 99 LOGGING statement See SFPROG logical device support facility See SFPROG logical device support facility DIAGNOSE code X'7C' See SFPROG logical operator See SFPROG logical record length of FILEDEF command 165 logical units assigning in CMS/DOS 214 LOGON command See CPPROG *LOGREC See SFPROG loop procedures See DIAG looping programs See DIAG machine check See CPPROG machine check interrupts 13 MACLIB command ADD function 173, 228 CaMP function 174, 229 DEL function 174, 228 description 172 example 228 GEN function 172, 227 MAP function 174, 229 REP function 173, 228 using 227 MACLIBs adding a member 173, 228 adding COpy files 173, 228 CMS commands that recognize MACLIBs 175 compressing 174, 229 copying members 176 creating 172, 226, 227 deleting a member 173, 174, 228 example 173 extracting a member 175 finding out about MACLIB members 180,229 lis ting con ten ts 174 listing information about members 180, 229 manipulating members 230 moving members into other files 176 querying in CMS/DOS 235 replacing a member 173, 228 system 180, 235 using 225 VSE assembler language restricted use in CMS/DOS 238 MACLIST command listing members of a MACLIB 176 sample screen 231 using 176, 231 macro libraries adding a member 173, 228 adding COpy files 173, 228 CMS commands that recognize MACLIBs 175 compressing 174, 229 copying members 176 creating 172, 226, 227 deleting a member 173, 174, 228 example 173 extracting a member 175 finding out about MACLIB members 180, 229 listing contents 174 listing information about members 180, 229 manipulating members 230 These symbols are used in the index to refer to other VM and VMjSP books: CPPROG-V~jSP C.P for. System Programming SFPROG-VM System Facilities for Programming DIAG-VM DiagnOSIS GUIde Index 417 moving members into other files 176 querying in CMS/DOS 235 replacing a member 173, 228 system 235 using 225 VSE assembler language restricted use in CMS/DOS 238 macro libraries (MACLIBs) See MACLIBs macro library in CMS 351 macros ABNEXIT 5 CMS 351 declarative -258 DMSEXS 41 DMSFREE 15, 27 DMSFRES 35 DMSFRET 33 DMSKEY 39 examples 75 FSCB 75 GETMAIN 16 GETMAIN/FREEMAIN (SVC 10) 193 HNDEXT 13 imperative 267 list of 351 manipulating disk files 75 OPEN 165 OS 188 OS simulation 191 SAM 258,267 STRINIT 24 supervisor 250 using 75 VSAM, supported under CMS 312 VSE assembler language macros supported in CMS 236 VSE macros supported by CMS/DOS 249 MAINHIGH 246 management of data See DIAG management of problems See DIAG manipulating members of a MACLIB 175 MAP command See DIAG map compressing routine See DIAG MAP files created by DOSLKED command 243 created by DSERV command 224 MAP option ofGENMOD command See DIAG MAP option of LOAD command See DIAG MAPA subcommand of DUMPS CAN command See DIAG MAPN subcommand of DUMPS CAN command See DIAG master catalog sharing 279 418 VM/SP CMS for System Programming MEMBER option of FILEDEF command 166 Message All System Service See SFPROG message complete external interrupt in IUCV See SFPROG MESSAGE function for SPOOL system service See SFPROG message pending external interrupt in lUCY See SFPROG message repository See SFPROG message repository files creating 146 creating HELP files 154 creating your own messages 153 rules for creating 148 using 145 using dictionary substitution 151 using substitution 151 Message System Service See SFPROG messages creating 153 minidisks extents 295 file directory of 328 restriction on using EXPORT/IMPORT with VSAM 307 shared, EDF R/O 328 temporary 283 transporting to OS system after using with CMS VSAM 281 using with VSAM data sets 281 mixed environment use of the programmable operator See SFPROG MODMAP command See DIAG module load map See DIAG modules DMSABN 5 DMSINA 54 DMSINT 55 DMSIOW 11 DMSITE 13 DMSITI 10 DMSITP 13 DMSITS 9,43 DMSPAG 34 DOS/VSE relocatable, copying into CMS files 222 relocatable, link-editing in CMS/DOS 241 MONITOR command See DIAG MONITOR START command See DIAG MOVEFILE command copying OS data sets 169 extracting a member from a MACLIB 230 options PDS 170 PDS option 170 used with OS data sets 159 MREGS subcommand of DUMPS CAN command See DIAG MRIOBLOK subcommand of DUMPS CAN command See DIAG *MSG See SFPROG *MSGALL See SFPROG MSS (Mass Storage System) See CPPROG MSS communication DIAGNOSE code X'78' See SFPROG MSSF SCPINFO command See SFPROG MSSFCALL DIAGNOSE code X'80' See SFPROG MULT option in CMS/DOS 285 of the DLBL command 295 multiple address stops See DIAG multiple extents 291, 301 multiple updates CTL option of XEDIT command 107 using UPDATE command 102 multiprocessor See CPPROG multiprocessor mode (MP) See CPPROG multivolume extents 291, 301 named segments, finding, loading, purging See SFPROG NAMESYS macro 321 national languages See SFPROG native languages See SFPROG *NCCF See SFPROG NCCF (Network Communications Control Facility) See SFPROG NCCF logical operator See SFPROG NCPDUMP command See DIAG NCPDUMP service program See DIAG NETWORK command See DIAG Network Communications Control Facility (NCCF) See SFPROG network dump operations See DIAG non-recoverable machine check See DIAG nonrelocatable modules creating 71 NOTE macro 198 NOTIFY function for SPOOL system service See SFPROG NUCALPHA 16 nucleus free storage allocating 32 description of 15 nucleus load map See DIAG nucleus, CMS 16 NUCOMEGA 16 NUCON macro 352 NUCSIGMA 17 OPEN macro 165 OPEN/OPENJ macro (SVC 19/22) 194 opening CMS files 81 Operating System (OS) access method support 199 CMS support for 4, 273 compilers, CMS usage 4 data management simulation 188 data sets 159 disks compatibility with DOS disks 280 determining free space 281 extents 295 formatting using DSF 283 using with AMSERV 278 files handling files on CMS disks 188 handling files on OS disks 189 formatted files 199 FREEMAIN macro 26 GETMAIN macro 24 linkage editor control statements read by TXTLIB command 181 macro simulation 159 macros 188, 191 ABEND 193 ATTACH 195 BLDL 193 BSP 198 These symbols are used in the index to refer to other VM and VM/SP books: CPPROG-VM/SP CP for System Programming SFPROG-VM System Facilities for Programming DIAG-VM Diagnosis Guide Index 419 CALL 198 CHAP 195 CHECK 198 CHKPT 197 CLOSE/TCLOSE 194 DCB 198 DELETE 193 DEQ 196 DETACH 197 DEVTYPE 194 ENQ 196 EXCP 192 EXIT/RETURN 192 EXTRACT 195 FEOV 195 FIND 194 FREEDBUF 196 FREEMAIN 192 GET 201 GETMAIN (SVC 4) 192 GETMAIN/FREEMAIN 193 GETPOOL/FREEPOOL 192 IDENTIFY 195 LINK 192 LOAD 192 NOTE 198 OPEN/OPENJ 194 PGRLSE 198 POINT 198 POST 192 PUT 201 PUTX 201 RDJFCB 197 READ 202 RESTORE 193 SNAP 196 SPIE 193 STAE 196 STAX 198 STIMER 196 STOW 194 SYNADAF 198 SYNADRLS 198 TCLEARQ 198 TGET/TPUT 198 TIME 193 TRKBAL 195 TTIMER 196 WAIT 192 WRITE 202 WTO/WTOR 195 XCTL 192 XDAP 191 reading data sets 161 simulated data sets 160 Isimulated OS supervisor calls 189 /simulation in CMS 157 supervisor calls 189 tape volume switching 204 terminal sessions 353 420 VM/SP CMS for System Programming TXTLIBs 181 OPTION command 209 OS (Operating System) access method support 199 CMS support for 4, 273 compilers, CMS usage 4 data management simulation 188 data sets 159, 203 disks compatibility with DOS disks 280 determining free space 281 extents 295 formatting using DSF 283 using with AMSERV 278 files handling files on CMS disks 188 handling files on OS disks 189 formatted files 199 FREEMAIN macro 26 GETMAIN macro 24 linkage editor control statements read by TXTLIB command 181 macro simulation 159 macros 188, 191 ABEND 193 ATTACH 195 BLDL 193 BSP 198 CALL 198 CHAP 195 CHECK 198 CHKPT 197 CLOSE/TCLOSE 194 DCB 198 DELETE 193 DEQ 196 DETACH 197 DEVTYPE 194 ENQ 196 EXCP 192 EXIT/RETURN 192 EXTRACT 195 FEOV 195 FIND 194 FREEDBUF 196 FREEMAIN 192 GET 201 GETMAIN (SVC 4) 192 GETMAIN/FREEMAIN 193 GETPOOL/FREEPOOL 192 IDENTIFY 195 LINK 192 LOAD 192 NOTE 198 OPEN/OPENJ 194 PGRLSE 198 POINT 198 POST 192 PUT 201 PUTX 201 RDJFCB 197 READ 202 RESTORE 193 SNAP 196 SPIE 193 STAE 196 STAX 198 STIMER 196 STOW 194 SYNADAF 198 SYNADRLS 198 TCLEARQ 198 TGET/TPUT 198 TIME 193 TRKBAL 195 TTIMER 196 WAIT 192 WRITE 202 WTO/WTOR 195 XCTL 192 XDAP 191 reading data sets 161 simulated data sets 160 simulated OS supervisor calls 189 simulation in CMS 157 supervisor calls 189 tape volume switching 204 terminal sessions 353 TXTLIBs 181 OS linkage editor control statement ALIAS statement 183 assigning entry point names 182 ENTRY statement 182 NAME statement 182 SETSSI card 183 OS/VSAM macros ACB 312 CHECK 312 ENDREQ 312 ERASE 312 OSMACRO MACLIB 180, 236 OSMACR01 MACLIB 180, 236 OSPOINT subcommand of DUMPS CAN command See DIAG OSRUN command 184 OSVSAM MACLIB 181, ~36 output controlling the filename 278 devices restricted in CMS/DOS 218 file produced by ASSEMBLE command 239 linkage edit CMS DOSLIBs 242 listings from AMSERV command 277 printed access method service listing 277 records, sequencing 98 overlay structures description 345 dynamic load 347 example 346 prestructured 346 page management 34 page release function DIAGNOSE code X'10' See SFPROG pageable module, identify and locate See DIAG paging hash table complex (HASHTAB) 2 hyperblock mapping table (HYPMAP) 2 ways to control 2 parameter list (PLIST) See PLIST (parameter list) parameter lists of IUCV functions See SFPROG P ARSECMD macro 352 P ARSERCB macro 352 P ARSERUF macro 352 parsing facility 113 partition size specified for execution in CMS/DOS 246 partitioned data s~t (PDS) copying into CMS files 170 specifying members with FILEDEF command 170 password defining for VSAM catalogs 289 for VSAM catalogs in CMS/DOS 289 for VSAM catalogs in OS 299 passwords See CPPROG paths, IUCV See SFPROG PA2 program function key controlling DIAGNOSE code X'54' See SFPROG PER command See DIAG performance of virtual machines See CPPROG ' . PERM option of FILEDEF command 165, 166 PGRLSE macro (SVC 112) 198 PLIST (parameter 1i~t) 43, 46 extended '46 tokenized . 46 using FSCB 83 PLU (programmer logical units) assigned in CMS/DOS 214 PMX (Programmable Operator/NCCF Message Exchange) See SFPROG These symbols are used in the index to refer to other VM and VMjSP books: , CPPROG-V~jSP C.p for. System Programming . SPPRQO:-VM System Facilities for Programming DIAG-VM DiagnOSIS GUIde Index 421 POINT macro 198 POST macro (SVC 2) 192 poster, CP internal trace table See DIAG PRB command See DIAG PRBnnnnn aaaaaaaa file See DIAG PRBnnnnn dump file See DIAG PRBnnnnn report See DIAG PRBnnnnn report file See DIAG PRB00003 report file with status updates added See DIAG preferred auxiliary files 108 preferred filetypes 3 preferred level updating 108 PRESENT logical device support facility function See SFPROG prestructured overlays 346 PRINT access methods services function 277 PRINT subcommand of DUMPS CAN command See DIAG printer See CPPROG printer interrupts 12 PRINTER subcommand of TRAPRED command See DIAG printing a MACLIB member 230 access method services listings 277 printing tape dump See DIAG PRINTL macro description 352 PRINTL macro usage 85 privilege classes for a user See CPPROG PROB command See DIAG problem analysis See DIAG problem diagnosis See DIAG problem exist? See DIAG problem identification See DIAG problem inquiry data sheet See DIAG problem management See DIAG problem number assignment See DIAG problem report file (PRBnnnnn REPORT) See DIAG problem reporting See DIAG problem types 422 VM/SP CMS for System Programming See DIAG procedures, DOS/VSE, copying into CMS files 222 processor See CPPROG PROFILE EXEC file CMS/DOS VSAM user 286 OS VSAM user 296 program check debugging See DIAG program exceptions See DIAG program interrupt (type X'04') entry See DIAG program interrupts 13 program modules, creating 71 Program Support Representative (PSR) See DIAG program temporary fix (PTF) See DIAG programmable operator facility See SFPROG Programmable Operator/NCCF Message Exchange (PMX) See SFPROG programs developing 4 executing 66 input and output files, identifying 162 interrupts 13 libraries 171 specifying virtual partition size 246 updating, with XEDIT UPDATE option 95 PROPCHK statement See SFPROG PROPRTCV for converting routing tables See SFPROG protected application facility DIAGNOSE code X'BO' See SFPROG PRTDUMP command See DIAG PSA (Prefix Storage Area) See CPPROG PSERV command description of 209 using 222 pseudo timer DIAGNOSE code X'OC' See SFPROG PSR (Program Support Representative) See DIAG PSW (program status word) DMSEXS macro 41 DMSKEY macro 39 keys 39 storage protection keys 38 PTF (program temporary fix) See DIAG punch interrupts 12 PUNCHC macro description of 352 usage 85 punching a MACLIB member 230 PURGE IUCV and VMCF functions See SFPROG PURGESYS function See SFPROG purging discontiguous shared segment DIAGNOSE code X'64' See SFPROG PUT macro 201 PUTX macro 201 PVCENTRY macro 353 QUERY command description of 210 MACLIBs available 235 QUERY IUCV function See SFPROG QUERY SRM command See DIAG QUIESCE IUCV and VMCF functions See SFPROG QUIT subcommand of DUMPSCAN command See DIAG QUIT subcommand of TRAPRED command See DIAG RDCARD macro 353 RDJFCB macro (SVC 64) 197 RDTAPE macro 353 RDTERM macro 353 READ functions for SPOOL system service See SFPROG read LOGREC data DIAGNOSE code X'30' See SFPROG READ macro 202 read system dump spool file DIAGNOSE code X'34' See SFPROG read system symbol table DIAGNOSE code X'38' See SFPROG read/write operation 82 reader interrupts 12 reading CMS disk files 79 DOS files 212 OS data sets 203 restrictions OS data sets 161 SAM files 212 SAM files 212 tapes 303 variable length records 80 VSAM tape files 294 Ready; message CPU times displayed 46 real channel program support DIAGNOSE code X'98' See SFPROG real storage See CPPROG RECEIVE IUCV and VMCF function See SFPROG RECFM option of FILEDEF command 165 record format DOS files 213 program input and output files 165 records, accounting See CPPROG records, sequencing 98 recovery, CMS abend 6 references, resolving unresolved 68 REGEQU macro 353 register contents after CMS command execution 44 restoration 62 usage 43 REGS subcommand of DUMPSC}\.N command See DIAG REJECT IUCV and VMCF functions See SFPROG relative record number 77 RELEASE command used with OS disks 159 releasing storage allocated by DMSFREE 33 allocated by GETMAIN 26 by ab'~nds 33 by an abend 26 by DMSFRET 34 by DMSPAG 34 by FREEMAIN macro 26 by the STRINIT macro 26 relocatable files modules, link-editing in CMS/DOS 241 object files, loading into storage for execution 67 using the LOAD and START commands 67 repetitive output See DIAG REPLACE statement 98 replacing member of a MACLIB in CMS/DOS 228 member of a MACLIB in OS 173 REPLY IUCV and VMCF function See SFPROG reporting problems These symbols are used in the index to refer to other VM and VM/SP books: CPPROG-VM/SP CP for System Programming SFPROG-VM System Facilities for Programming DIAG-VM Diagnosis Guide Index 423 See DIAG repository files creating message 146 message 145 REPRO access method services function 307 Resource Access Control Facility (RACF) See CPPROG responding to prompting messages from AMSERV in an EXEC 309 responsibilities of user for CMS/DOS 270 RESTORE macro (SVC 17) 193 restrictions BDAM 202 eMS/DOS 272 CMS, saved system 321 ddnames in OS VSAM programs 294 executing OS programs in CMS 66 programs executing in transient area 73 reading OS data sets 161 SAM files 212 using DOS macro libraries in CMS/DOS 225 minidisks with VSAM data sets 281 OS programs in CMS/DOS 208 RESUME IUCV and VMCF function See SFPROG retrieve a group name DIAGNOSE code X'AO' See SFPROG RETRIEVE BUFFER IUCV function See SFPROG return codes displayed in ready message 46 DMSXFLPT 87 DMSXFLRD 87 DMSXFLST 86 DMSXFLWR 87 from access method services 277 from SUBCOM function 61 passed by register 15 46 REUSE subcommand of DUMPS CAN command See DIAG RIOBLOK subcommand of DUMPS CAN command See DIAG ROUTE statement See SFPROG routing table (RTABLE) See SFPROG RSERV command description of 210 examples 222 RTABLE (routing table) See SFPROG 424 VM/SP CMS for System Programming S-STAT 16 SAD MACRO See DIAG SADGEN ASSEMBLE file See DIAG SADGEN TEXT file See DIAG SADUMP EXEC See DIAG SAM (sequential access method) declarative macros 258, 267 I/O macros 258, 267 reading 212 sample terminal sessions for DOS programmers 360 for OS programmers 353 using access method services 369 save the 370X control program image DIAGNOSE code X'50' See SFPROG saved system See also CPPROG restrictions for CMS 321 SAVEFD command 328 saving CMS 321 history information 69, 72, 183 saving or loading a 3800 named system DIAGNOSE code X'74' See SFPROG saving the CP message repository DIAGNOSE code X'CC' See SFPROG SCBLOCK control block created by SUBCOM 59 SCBLOCK macro 353 scheduling virtual machines See CPPROG SCIF (Single Console Image Facility) See SFPROG SCPINFO command See SFPROG screen management VM/SP SNA support See SFPROG SCRIPT command execution restrictions in CMS/DOS 208 scroll interface, DUMPS CAN See DIAG SCROLL subcommand of DUMPSCAN command See DIAG SDUMP command See DIAG search order for executable phases in CMS/DOS 244 for routines or commands in CSMMS 54 for TEXT files and TXTLIB members 182 /' used by ASSEMBLE command 239 searching libraries 180 SELECT function for SPOOL system service See SFPROG SEND IUCV and VMCF functions See SFPROG SEND/RECV VMCF function See SFPROG SENDREQ macro 353 SENDX VMCF function See SFPROG SEQUENCE statement 97 sequencing , output records 99 using XEDIT SERIAL subcommand 97 sequential access method (SAM) See SAM (sequential access method) service routines 34 SET command description 210 DOSPART operand 246 SET command used by programmable operator See SFPROG SET CONTROL MASK IUCV function See SFPROG SET DOS command used to enter or exit DOS environment 208 set languages DIAGNOSE code X'C8' See SFPROG SET MASK IUCV function See SFPROG setting UPS I byte 247 SEVER IUCV function See SFPROG SFPROG See VM System Facilities for Programming shadow table maintenance DIAGNOSE code X'6C' See SFPROG shared segments See CPPROG shared storage 328 sharing virtual disks 3 SHVBLOCK macro 353 *SIGNAL See SFPROG Signal System Service See SFPROG simulated OS supervisor calls 189 simulation of VSE functions by CMS 249 OS macro 159 Single Console Image Facility (SCIF) See SFPROG single processor mode See CPPROG single system use of the programmable operator See SFPROG SIO (type X'06') entry See DIAG SNA (System Network Architecture) See SFPROG SNAP macro (SVC 51) 196 sorting directories of DOS/VSE private libraries 224 source files adding comments 99 deleting records 98 inserting records 98 multiple updates to using CTL option of XEDIT 107 replacing records 98 sample using UPDATE command 100 spanned records, usage 201 Special Message Facility See SFPROG SPIE macro (SVC 14) 193 *SPL See SFPROG spool file See CPPROG spool file external attribute buffer manipulation DIAGNOSE code X'B8' See SFPROG SPOOL System Service See SFPROG spooling See CPPROG SSERV command description of 210 examples 221 using 221 STAE macro (SVC 60) 196 stand-alone dump facility See DIAG stanqard DASD I/O DIAGNOSE code X'18' See SFPROG START command executing a file 67 executing TEXT files 67 used with FETCH command 244 start of LOGREC area DIAGNOSE code X'2C' See SFPROG starting, program execution in CMS 67 STAT command See DIAG statall local file See DIAG STATE command used with OS data sets 159 status file See DIAG STAX macro (SVC 96) 198 STCP command See DIAG STIMER macro (SVC 47) 196 STOP command used by programmable operator See SFPROG These symbols are used in the index to refer to other VM and VM/SP books: CPPROG-VM/SP CP for System Programming SFPROG-VM System Facilities for Programming DIAG-VM Diagnosis Guide Index 425 stop execution See DIAG storage allocation of 27, 32 assembler requirements 345 CMS nucleus 16 DMSFREE macro 15 DMSFREE management 27 DMSNUC 15, 21 free storage 23 loader tables 16 managing 23 map, CMS 17 nucleus free 15, 23 protection keys 38 releasing 26, 34 shared 328 structure of 15 transient program area 15, 23 user free 15, 23 user program area 16, 23 storage available in your virtual machine calculated by CMS 246 storage contents, altering See DIAG storage protection See CPPROG STORE command See DIAG store extended-identification code DIAGNOSE code X'OO' See SFPROG store real CP data See DIAG store virtual data See DIAG STOW macro (SVC 21) 194 STRINIT macro description of 24, "353 format of 24 initializing pointers for storage management releasing storage 26 structure of CMS storage 15 structured data base (SDB) See DIAG suballocated VSAM cluster, defining 305 SUBCOM function calling routines dynamically 59 command search function 58 register 1 contents 49 return codes 61 summary of changes 379 summary record file See DIAG supervisor calls 189 SVC CMS/DOS support routines 250 DMSITS module 9 handling routine DMSITS 43 426 VM/SP CMS for System Programming 24 INTSVC 43 interrupts 9 linkage 48 types 48 invalid SVCs 53 as and VSE SVC simulation 53 SVC 202 48 SVC 203 52 user-handled 53 SVC interrupt (type X'05') entry See DIAG SVC interrupts CMS SVCs 10 description of 9 internal linkage SVC 9 SVC save area (SVCSAVE) See DIAG SVC 199 services See DIAG SVC 202 9 description of 48 entered from a program 54 extended PLIST 46 processing 57 return codes 51 search hierarchy 54 tokenized PLIST 46 SVC 203 9,52 SVCTRACE command See DIAG switching, CMS tape volume 204 SYMP subcommand of DUMPSCAN command See DIAG symptom records See DIAG symptom summary file See DIAG symptom summary file conversion See DIAG SYNADAF macro (SVC 68) 198 SYNADRLS macro (SVC 68) 198 SYSCAT system logical unit assigning in CMS/DOS 285 SYSCLB system logical unit assigning in CMS/DOS 216 unassigning 245 SYSCOR macro See DIAG SYSIN system logical unit assigning in CMS.DOS 215 input for ESERV command 223 SYSIPT system logical unit 215 SYSLOG system logical unit 215 SYSLST system logical unit assigning in CMS/DOS 215 output from ESERV program 223 SYSOPR macro See DIAG SYSPCH system logical unit " ----~ assigning in CMS/DOS 215 output from ESERV program 223 SYSPROF EXEC description of 322 functions of 323 SYSRDR system logical unit 215 SYSRLB system logical units assigned in CMS/DOS 216 SYSSLB system logical units assigned in CMS/DOS 216 system abend See DIAG system information, collect and analyze See DIAG system logical units SYSCLB 216 SYSIN 215 SYSIPT 215 SYSLOG 215 SYSLST 215 SYSPCH 216 SYSRDR 215 SYSRLB 216 SYSSLB 216 system MACLIBs 180 CMS macros 235 CMSLIB 180 DMSSP 180 DOSMACRO 181 OS macros 235 OSMACRO 180 OSMACR01 180 OSVSAM 181 TSOMAC 181 System Network Architecture (SNA) See SFPROG System Product Editor (XED IT) See XEDIT (System Product Editor) system profile 321 bypassing 327 creating 325 description of 322 functions of 328 system save area format of 63 modifications of 62 system security See CPPROG system service, CP See SFPROG SYSxxx (programmer logical units) programmer logical units, assigning 214 TACTIVE subcommand of DUMPSCAN command See DIAG tailoring your system 321 tape volume switching in CMS 204 TAPECTL macro 353 tapes considerations for CMS/DOS 214 input 303 output 303 reading 303 used for AMSERV input and output 292 T APESL macro 353 TCLEARQ macro (SVC 94) 198 temporary disks formatting using DSF 283 using for VSAM data sets 283 TEOVEXIT macro 353 terminal interrupts 11 terminals CMS interface 88 macros for communication 84 sample sessions for DOS programmers 360 sample sessions for OS programmers 353 sample sessions using access method services 369 TERMINATE ALL logical device support facility function See SFPROG TERMINATE logical device support facility function See SFPROG termination, abnormal See abend (abnormal termination) terminology CMS/DOS 207 OS 158 TEST COMPLETION IUCV function See SFPROG TEST MESSAGE IUCV function See SFPROG TEVC (trace entry verification code) See DIAG TEXT files adding as linkage editor control statements 182 created by assembler, output filemode 65 executing 66 link-editing in CMS/DOS 241 loading 67 TEXTSYM statement See SFPROG TGET/TPUT macro (SVC 93) 198 TIME macro (SVC 11) 193 timers These symbols are used in the index to refer to other VM and VM/SP books: CPPROG-VM/SP CP for System Programming SFPROG-VM System Facilities for Programming DIAG-VM Diagnosis Guide Index 427 See CPPROG TLOADL subcommand of DUMPSCAN command See DIAG TOD-clock accounting interface See SFPROG tokenized PLIST 46 TOP subcommand of TRAPRED command See DIAG TRACCURR (current CP internal trace table entry) See DIAG TRACE command See CPPROG See DIAG trace entry verification code (TEVC) See DIAG trace execution See DIAG trace real machine events See DIAG TRACE subcommand of DUMPSCAN command See DIAG trace table, CP See CPPROG TRACEND (end of CP internal trace table) See DIAG· tracing See DIAG tracing capabilities in EXECs See DIAG tracing storage alteration using PER See DIAG tracking number per cylinder on disk devices 296 TRACSTRT (start of CP internal trace table) See DIAG transient program area creating modules to execute in 72 description of 23 location in virtual storage 72 restrictions on modules executing in 72 transient program area 15 transient routines $$BCLOSE 268 $$BDUMP 268 $$BOPEN 268 $$BOPENR 268 $$BOPNLB 268 $$BOPNR2 268 $$BOPNR3 268 $$BOSVLT 269 supported by CMS/DOS 268 transporting VSAM data sets 281 TRANTBL macro 353 TRAPRED command format See DIAG TRAPRED facility See DIAG TRAPRED subcommands See DIAG TRKBAL macro (SVC 25) 195 TSAB subcommand of DUMPS CAN command 428 VM/SP CMS for System Programming See DIAG TSAF console log sample See DIAG TSAF debugging See DIAG TSAF dumps See DIAG TSAF internal trace table See DIAG TSAF QUERY command See DIAG TSAF SET ETRACE command See DIAG TSAFIPCS MAP See DIAG TSOMAC MACLIB 181, 236 TTIMER macro (SVC 46) 196 TVSPARMS macro 353 TXTLIB command creating 181 description 181 ENTRY statement 182 executing 182 FILENAME option 181 GEN function 181 loading 182 members, creating a directory entry for 182 OS linkage editor control statements supported 181 SETSSI card 183 specify an alias name 183 usage 181 TXTLIBs TYPE subcommand of TRAPRED command See DIAG TYPEBACK subcommand of TRAPRED command See DIAG typenum subcommand of TRAPRED command See DIAG UCS (Universal Character Set) See CPPROG UCSB (Universal Character Set Buffer) See CPPROG unassigning logical unit assignments in CMS/DOS 217 UNAUTHORIZE VMCF function See SFPROG unexpected results procedures See DIAG unique clusters, defining 306 UP subcommand of TRAPRED command See DIAG UPDATE command control statement usage updating 97 multiple 102 preferred level 108 programs 95 source file, using CTL option of XEDIT 107 UPDATE command 95 VMFASM EXEC 109 VSE 270 updating problem report See DIAG updating VM/SP directory DIAGNOSE code X'3C' See SFPROG UPSI (user program switch indicator) byte, setting in CMS/DOS 247 operand, of CMS SET command, example 247 setting 247 user area (USERSECT) 21 user free storage allocating 32 DMSFREE requests 15, 23 user privilege classes See CPPROG user program area description of 16, 23 GETMAIN macro 24 over laying programs in 72 user program switch indicator (UPS I) See UPSI (user program switch indicator) user responsibilities for CMS/DOS 270 user save area 63 user-controlled device interrupts 12 user-written commands creating 71, 73 USERMAP subcommand of DUMPS CAN command See DIAG USERSECT (user area) 21 USERSECT macro 353 variable length record reading using FSREAD macro 80 writing using FSWRITE macro 80 VIOBLOK subcommand of DUMPSCAN command See DIAG virtual console function DIAGNOSE" code X'08' See SFPROG virtual machine See CPPROG virtual machine assignments 218 virtual machine assist feature See CPPROG Virtual Machine Communication Facility (VMCF) See SFPROG virtual machine data, recording See DrAG virtual machine debugging See DIAG virtual machine storage size DIAGNOSE code X'60' See SFPROG Virtual Machine/System Product (VM/SP) See also VM/SP (Virtual Machine/System Product) CMS subsystem 1 virtual printer external attribute buffer manipulation DIAGNOSE code X'B4' See SFPROG virtual storage assembler requirements 345 overlaying during program execution 72 specifying locations for program execution 72 Virtual Storage Access Method (VSAM) catalog defining in CMS/DOS 285, 296 sharing 279 structure 289 CMS support for 273 compiling and executing in CMS 274 data sets compatibility considerations 312 exporting 307 identifying 294 importing 307 manipulating with AMSERV command 273 defining catalogs in CMS/DOS 286 clusters 305 master catalog in OS 297 unique clusters 306 user catalogs in CMS/DOS 287 devices supported under CMS 319 disks 281 extent, multiple, information in CMS/DOS 291 extent, multivolume, information in CMS/DOS 291 files in CMS/DOS 290 in OS 300 identifying multivolume files in CMS/DOS 292 in OS 302 macros supported under CMS 312 master catalogs 286 multivolume extents 301 programs identifying before executing programs 275 reading tape files 294 support of 188, 200 using in CMS 273 writing EXECs 309 virtual storage preservation See CPPROG virtual storage, altering See DIAG VM/SP (Virtual Machine/System Product) These symbols are" used in the index to refer to other VM and VM/SP books: CPPROG-VM/SP CP for System Programming SFPROG-VM System Facilities for Programming DIAG-VM Diagnosis Guide Index 429 CMS 1 CMS subsystem 1 directory entries, for VSE 271 VM/SP directory updating DIAGNOSE code X'3C' See SFPROG VM/VCNA, VM/SP SNA support See SFPROG VM/VTAM, VM/SP SNA support See SFPROG VMBLOK subcommand of DUMPS CAN command See DIAG VMCF (Virtual Machine Communication Facility) See SFPROG VMDUMP command See DIAG VMDUMP function See SFPROG VMDUMP Function DIAGNOSE code X'94' See SFPROG VMFASM EXEC description 109 VMFDOS command 213 VMLOADL subcommand of DUMPS CAN command See DIAG Volume Table of Contents (VTOC) 199 VSAM (Virtual Storage Access Method) catalog defining in CMS/DOS 285, 296 sharing 279 structure 289 CMS support for 273 compiling and executing in CMS 274 data sets compatibility considerations 312 exporting 307 identifying 294 importing 307 manipulating with AMSERV command 273 defining catalogs in CMS/DOS 286 clusters 305 master catalog in OS 297 unique clusters 306 user catalogs in CMS/DOS 287 devices supported under eMS 319 disks 281 extent, multiple, information in CMS/DOS 291 extent, multivolume, information in CMS/DOS 291 files in CMS/DOS 290 in OS 300 identifying multivolume files in CMS/DOS 292 in OS 302 macros supported under CMS 312 master catalogs 286 multivolume extents 301 programs identifying before executing programs 275 430 VM/SP CMS for System Programming reading tape files 294 support of 188, 200 using in CMS 273 writing EXECs 309 VSAM dumping information See DIAG VSAM option of DLBL command 295 of DLBL command in CMS/DOS 285 VSCS printing formatted control blocks See DIAG VSCS, VM/SP SNA support See SFPROG VSE assembler language macros supported in CMS 236 CMS support for 4 compilers, CMS usage 4 hardware devices supported 249 I/O macros 249 libraries 270 macros supported under CMS 249 macros, supervisor 250 supervisor control blocks simulated 269 supervisor macros 249, 250 system residence volume, using in CMS/DOS 208 transient routines 268 transients simulated by CMS/DOS 268 VM/SP directory entries 271 VSE/VSAM macros ACB 311 BLDVRP 311 DLVRP 311 ENDREQ 311 ERASE 311 VSE macros supported by CMS 312 VSEVSAM command prompting 312 VTAM printing formatted control blocks See DIAG VTAM service machine VM/SP SNA support See SFPROG VTOC (Volume Table of Contents) 199 wait bit, modifying See DIAG WAIT macro (SVC 1) 192 wait state procedures See DIAG WAITD macro 353 W AITECB macro 353 WAITT macro description of 353 usage 84 WRITE macro 202 writing CMS disk files 79 lines to terminal 84 specific records in CMS file 80 variable length records 80 WRTAPE macro 353 WRTERM macro description of 353 examples 84 WTO/WTOR macro (SVC 35) 195 X'64' -- finding, loading, purging named segments See CPPROG XAB (External Attribute Buffer) See SFPROG XCTL macro (SVC 7) 192 XDAP macro (SVC 0) 191 XEDIT (System Product Editor) changing files 2 creating files 2 CTL option, creating multiple updates to source file 107 DMSXFLPT 87 DMSXFLRD 87 DMSXFLST 86 DMSXFLWR 87 interface to access files in storage 86 XEDIT command changing files 2 creating files 2 editing a MACLIB member 230 Y-STAT 16 ZAP command See DIAG ZAPTEXT command See DIAG I Numerics I 3081 processor MSSFCALL - DIAGNOSE code X'80' See SFPROG 3203 See CPPROG 3270 virtual console interface DIAGNOSE code X'58' See SFPROG 3480 tape volume serial support DIAGNOSE code X'DO' See SFPROG 37XX Control Program See CPPROG See SFPROG 370X dump processing See DIAG 3800 printer See CPPROG These symbols are used in the index to refer to other VM and VM/SP books: CPPROG-VM/SP CP for System Programming SFPROG-VM System Facilities for Programming DIAG-VM Diagnosis Guide Index 431 International Business Machines Corporation P.O. Box 6 Endicott, New York 13760 File No. S370/4300-36 Printed in U.S.A. SC24-5286-0 --==--_--::::::::iI - . . ----= ---_ _ _ .a::=- ==='" 1::1 1::1 1::1 ===""" 1::1 t:::= c::::II &::::::I Y ® READER'S COMMENT FORM VM/SP CMS for System Programming Order No. SC24-5286-0 Is there anything you especially like or dislike about this book? Feel free to comment on specific errors or omissions, accuracy, organization, or completeness of this book. If you use this form to comment on the online HELP facility, please copy the top line of the HELP screen. ____ Help Information line of IBM may use or distribute whatever information you supply in any way it believes appropriate without incurring any obligation to you, and all such information will be considered non confidential. Note: Do not use this form to report system problems or to request copies of publications. Instead, contact your IBM representative or the IBM branch office serving you. Would you like a reply? _YES _NO Please print your name, company name, and address: IBM Branch Office serving you: Thank you for your cooperation. You can either mail this form directly to us or give this form to an IBM representative who will forward it to us. SC24-5286-0 Reader's Comment Form CUT OR FOLD ALONG LINE Please Do Not Staple Fold and tape Fold and tape NO POSTAGE NECESSARY IF MAILED IN THE UNITED STATES BUSINESS REPLY MAIL FIRST-CLASS MAIL PERMIT NO. 40 ARMONK, NY POSTAGE WILL BE PAID BY ADDRESSEE: _ _ _ _ ...... _ _ _ ~_J "'tr~-~...:.......... .f''''..... ,•• '.""'" ----- --- -- -------------_.- .... ~ - '" INTERNATIONAL BUSINESS MACHINES CORPORATION DEPARTMENT G60 PO BOX 6 ENDICOTT NY 13760-9987 1"111 .. 11111111111,,111111.111111'11 .. 1111111111111 Fold and tape ---------- --- -- , -® - -- Please Do Not Staple - ,~- 1 ~-~~-'~ Fold and tape READER'S COMMENT FORM VMjSP CMS for System Programming Order No. SC24-5286-0 Is there anything you especially like or dislike about this book? Feel free to comment on specific errors or omissions, accuracy, organization, or completeness of this book. If you use this form to comment on the online HELP facility, please copy the top line of the HELP screen. ____ Help Information line __ of __ IBM may use or distribute whatever information you supply in any way it believes appropriate without incurring any obligation to you, and all such information will be considered non confidential. Note: Do not use this form to report system problems or to request copies of publications. Instead, contact your IBM representative or the IBM branch office serving you. Would you like a reply? _YES _NO Please print your name, company name, and address: IBM Branch Office serving you: Thank you for your cooperation. You can either mail this form directly to us or give this form to an IBM representative who will forward it to us. SC24-5286-0 Reader's Comment Form CUT OR FOLD ALONG LINE Please Do Not Staple Fold and tape BUSINESS REPLY MAIL FIRST-CLASS MAIL PERMIT NO. 40 Fold and tape NO POSTAGE NECESSARY IF MAILED IN THE UNITED STATES ARMONK, NY POSTAGE WILL BE PAID BY ADDRESSEE: -------- --- -- ----------_.INTERNATIONAL BUSINESS MACHINES CORPORATION DEPARTMENT G60 PO BOX 6 ENDICOTT NY 13760-9987 1••• 11 •• 1i .1 ••• 1.11 •• 11 ••• 1.1 •• 1.1 •• 1•• 1.1 ••• 11111.1 Please Do Not Staple Fold and tape --..--- ----- ----,® Fold and tape / I' If .. SC24-5286-00
Source Exif Data:
File Type : PDF File Type Extension : pdf MIME Type : application/pdf PDF Version : 1.3 Linearized : No XMP Toolkit : Adobe XMP Core 4.2.1-c043 52.372728, 2009/01/18-15:56:37 Producer : Adobe Acrobat 9.31 Paper Capture Plug-in Modify Date : 2010:03:20 15:49:52-08:00 Create Date : 2010:03:20 15:49:52-08:00 Metadata Date : 2010:03:20 15:49:52-08:00 Format : application/pdf Document ID : uuid:f5c35172-77c0-4421-bbfd-36a044fd80ac Instance ID : uuid:56a57aea-c2b9-4255-8cf5-28882b84d04c Page Layout : SinglePage Page Mode : UseNone Page Count : 450EXIF Metadata provided by EXIF.tools