) Kednos PL/I for OpenVMS Systems User Manual Order Number: AA-H951E-TM November 2003 This manual provides an overview of the PL/I programming language. It explains programming with Kednos PL/I on OpenVMS VAX Systems and OpenVMS Alpha Systems. It also describes the operation of the Kednos PL/I compilers and the features of the operating systems that are important to the PL/I programmer. Revision/Update Information: This revised manual supersedes the PL/I User’s Manual for VAX VMS, Order Number AA-H951D-TL. Operating System and Version: For Kednos PL/I for OpenVMS VAX: OpenVMS VAX Version 5.5 or higher For Kednos PL/I for OpenVMS Alpha: OpenVMS Alpha Version 6.2 or higher Software Version: Kednos PL/I Version 3.8 for OpenVMS VAX Kednos PL/I Version 4.4 for OpenVMS Alpha Published by: Kednos Corporation, Pebble Beach, CA, www.Kednos.com First Printing, August 1980 Revised, November 1983 Updated, April 1985 Revised, April 1987 Revised, January 1992 Revised, May 1992 Revised, November 1993 Revised, April 1995 Revised, October 1995 Revised, November 2003 Kednos Corporation makes no representations that the use of its products in the manner described in this publication will not infringe on existing or future patent rights, nor do the descriptions contained in this publication imply the granting of licenses to make, use, or sell equipment or software in accordance with the description. Possession, use, or copying of the software described in this publication is authorized only pursuant to a valid written license from Kednos Corporation or an anthorized sublicensor. No responsibility is assumed for the use or reliability of software on equipment that is not listed as supported in the Product Description. Copyright Kednos Corporation 1980-2003. All rights reserved. Copyright ©1980-2003 The following are trademarks of Hewlett-Packard: Alpha AXP, AXP, DEC, DEC 4000, DECchip, DECnet, DECtalk, DECUS, Digital, MicroVAX,OpenVMS, OpenVMS AXP, RMS, RMS-11, RX50, TK50, VAX, VAX Ada, VAX BASIC, VAX BLISS, VMScluster, VAX CDD/Plus, VAX COBOL, VAX DATATRIEVE, VAX DIBOL, VAX DOCUMENT, VAX FORTRAN, VAXinfo, VAX MACRO, VAX Pascal, VAX SCAN, VAXset, VAXTPU, VMS, the AXP logo, and the DIGITAL logo. The Reader’s Comments form at the end of this manual requests your critical evaluation to assist in preparing future documentation. 1 Contents PREFACE xix CHAPTER 1 OVERVIEW 1–1 CHAPTER 2 DEVELOPING PL/I PROGRAMS AT THE DCL COMMAND LEVEL 2–1 2.1 DCL COMMANDS FOR PROGRAM DEVELOPMENT 2–1 2.2 CREATING A PL/I PROGRAM 2–2 2.2.1 Using EDT 2–2 2.2.2 Using LSE 2–3 2.2.3 Using DECTPU 2–4 2.2.3.1 The EVE Interface • 2–4 2.2.3.2 The EDT Keypad Emulator Interface • 2–5 2.3 COMPILING A PL/I PROGRAM 2–5 2.3.1 PLI Command 2–5 2.3.2 PLI Command Qualifiers 2–7 2.3.3 PL/I Preprocessor 2–18 2.3.3.1 Preprocessor Compilation Control • 2–18 2.3.3.2 Preprocessor Procedures • 2–19 2.3.4 Compiler Error Messages 2–21 2.3.5 Kednos PL/I for OpenVMS VAX Compiler Listing 2–23 2.3.6 Kednos PL/I for OpenVMS Alpha Compiler Listing 2–31 2.4 LINKING A PL/I PROGRAM 2–40 2.4.1 LINK Command 2–40 2.4.2 LINK Command Qualifiers 2–41 2.4.3 Linker Input Files 2–42 2.4.4 Linker Output Files 2–43 2.4.5 Object Module Libraries 2–43 2.4.6 Linker Error Messages 2–44 2.5 RUNNING A PL/I PROGRAM 2–45 iii Contents CHAPTER 3 USING THE OPENVMS DEBUGGER 3–1 3.1 OVERVIEW 3–1 3.2 FEATURES OF THE DEBUGGER 3–2 3.3 GETTING STARTED WITH THE DEBUGGER 3–4 3.3.1 Compiling and Linking a Program to Prepare for Debugging 3–4 3.3.2 Starting and Terminating a Debugging Session 3–5 3.3.3 Issuing Debugger Commands 3–6 3.3.4 Viewing Your Source Code 3–6 3.3.4.1 Noscreen Mode • 3–7 3.3.4.2 Screen Mode • 3–8 3.3.5 Controlling and Monitoring Program Execution 3–9 3.3.5.1 Starting and Resuming Program Execution • 3–9 3.3.5.2 Determining the Current Value of the Program Counter • 3–11 3.3.5.3 Suspending Program Execution • 3–11 3.3.5.4 Tracing Program Execution • 3–13 3.3.5.5 Monitoring Changes in Variables • 3–14 3.3.6 Examining and Manipulating Data 3–16 3.3.6.1 Displaying the Values of Variables • 3–16 3.3.6.2 Changing the Values of Variables • 3–18 3.3.6.3 Evaluating Expressions • 3–18 3.3.6.4 Notes on Debugger Support for PL/I • 3–19 3.3.7 Controlling Symbol References 3–20 3.3.7.1 Module Setting • 3–20 3.3.7.2 Resolving Multiply Defined Symbols • 3–21 3.4 SAMPLE DEBUGGING SESSION 3–22 3.5 DEBUGGER COMMAND SUMMARY 3–24 3.5.1 Starting and Terminating a Debugging Session 3–24 3.5.2 Controlling and Monitoring Program Execution 3–25 3.5.3 Examining and Manipulating Data 3–25 3.5.4 Controlling Type Selection and Symbolization 3–25 3.5.5 Controlling Symbol Lookup 3–26 3.5.6 Displaying Source Code 3–26 3.5.7 Using Screen Mode 3–26 3.5.8 Editing Source Code 3–27 3.5.9 Defining Symbols 3–27 3.5.10 Using Keypad Mode 3–27 iv Contents 3.5.11 Using Command Procedures and Log Files 3–27 3.5.12 Using Control Structures 3–28 3.5.13 Additional Commands 3–28 CHAPTER 4 THE FILE SYSTEM 4–1 4.1 FILE CONTROL 4–1 4.2 USING THE OPENVMS FILE SYSTEM FOR I/O 4–2 4.2.1 PL/I Files and OpenVMS File Specifications 4–2 4.2.2 Using the TITLE Option 4–3 4.2.3 Using Logical Names 4–4 4.2.4 Using the DEFAULT_FILE_NAME Option 4–6 4.2.5 Expanding File Specifications 4–7 4.3 ERROR HANDLING 4–9 4.3.1 Values Returned by PL/I Built-In Functions for Error Handling 4–9 4.3.2 Writing an Error Handler 4–10 4.3.3 Default Error Handling for the File System 4–10 CHAPTER 5 STREAM INPUT/OUTPUT 5–1 CHAPTER 6 RECORD INPUT/OUTPUT 6–1 6.1 FILE ORGANIZATIONS 6–1 6.2 ACCESS MODES 6–3 6.2.1 Sequential Access 6–4 6.2.2 Random Access 6–4 6.2.3 Random and Sequential Access 6–5 6.2.4 Block Input/Output 6–5 6.2.5 Access by Record Identification 6–5 6.3 RECORD FORMATS 6–6 v Contents 6.3.1 Fixed-Length Records 6–6 6.3.2 Variable-Length Records 6–7 6.3.3 Variable-Length Records with a Fixed-Length Control Area 6–7 6.4 CARRIAGE CONTROL 6–8 6.5 SEQUENTIAL FILES 6–8 6.5.1 Creating a Sequential File 6–8 6.5.2 Using Magnetic Tape Files 6–9 6.5.3 Allocated and Spooled Devices 6–12 6.6 RELATIVE FILES 6–13 6.6.1 Relative File Organization 6–13 6.6.2 Creating a Relative File 6–14 6.6.3 Using Relative Files 6–17 6.6.4 Error Handling 6–19 6.7 INDEXED SEQUENTIAL FILES 6–20 6.7.1 Indexed File Organization 6–21 6.7.2 Defining and Creating an Indexed Sequential File 6–22 6.7.2.1 Using EDIT/FDL • 6–23 6.7.2.2 Using a PL/I Program • 6–26 6.7.3 Defining Keys 6–28 6.7.4 Using Indexed Sequential Files 6–32 CHAPTER 7 OPTIONS OF THE ENVIRONMENT ATTRIBUTE 7–1 7.1 SPECIFYING AND USING ENVIRONMENT OPTIONS 7–1 7.1.1 Arguments for ENVIRONMENT Options 7–1 7.1.1.1 Expressions • 7–2 7.1.1.2 Variable References • 7–2 7.1.1.3 Boolean Values • 7–2 7.1.2 Interpretation of ENVIRONMENT Options for Existing Files 7–2 7.1.3 Determining ENVIRONMENT Options 7–3 7.1.4 Device Independence of ENVIRONMENT Options 7–3 7.1.5 Conflicting and Invalid ENVIRONMENT Options 7–3 7.2 SUMMARY OF ENVIRONMENT OPTIONS 7–3 vi Contents 7.2.1 APPEND Option 7–9 7.2.2 BACKUP_DATE Option 7–9 7.2.3 BATCH Option 7–10 7.2.4 BLOCK_BOUNDARY_FORMAT Option 7–10 7.2.5 BLOCK_IO Option 7–11 7.2.6 BLOCK_SIZE Option 7–12 7.2.7 BUCKET_SIZE Option 7–12 7.2.8 CARRIAGE_RETURN_FORMAT Option 7–14 7.2.9 CONTIGUOUS Option 7–14 7.2.10 CONTIGUOUS_BEST_TRY Option 7–15 7.2.11 CREATION_DATE Option 7–15 7.2.12 CURRENT_POSITION Option 7–16 7.2.13 DEFAULT_FILE_NAME Option 7–16 7.2.14 DEFERRED_WRITE Option 7–17 7.2.15 DELETE Option 7–18 7.2.16 EXPIRATION_DATE Option 7–18 7.2.17 EXTENSION_SIZE Option 7–19 7.2.18 FILE_ID Option 7–19 7.2.19 FILE_ID_TO Option 7–20 7.2.20 FILE_SIZE Option 7–20 7.2.21 FIXED_CONTROL_SIZE Option 7–21 7.2.22 FIXED_CONTROL_SIZE_TO Option 7–22 7.2.23 FIXED_LENGTH_RECORDS Option 7–22 7.2.24 GROUP_PROTECTION Option 7–23 7.2.25 IGNORE_LINE_MARKS Option 7–24 7.2.26 INDEX_NUMBER Option 7–24 7.2.27 INDEXED Option 7–25 7.2.28 INITIAL_FILL Option 7–25 7.2.29 MAXIMUM_RECORD_NUMBER Option 7–26 7.2.30 MAXIMUM_RECORD_SIZE Option 7–26 7.2.31 MULTIBLOCK_COUNT Option 7–27 7.2.32 MULTIBUFFER_COUNT Option 7–28 7.2.33 NO_SHARE Option 7–29 7.2.34 OWNER_GROUP Option 7–30 7.2.35 OWNER_ID Option 7–31 7.2.36 OWNER_MEMBER Option 7–32 7.2.37 OWNER_PROTECTION Option 7–32 7.2.38 PRINTER_FORMAT Option 7–33 7.2.39 READ_AHEAD Option 7–36 7.2.40 READ_CHECK Option 7–37 7.2.41 RECORD_ID_ACCESS Option 7–37 7.2.42 RETRIEVAL_POINTERS Option 7–38 7.2.43 REVISION_DATE Option 7–38 vii Contents 7.2.44 REWIND_ON_CLOSE Option 7–39 7.2.45 REWIND_ON_OPEN Option 7–39 7.2.46 SCALARVARYING Option 7–40 7.2.47 SHARED_READ Option 7–41 7.2.48 SHARED_WRITE Option 7–41 7.2.49 SPOOL Option 7–42 7.2.50 SUPERSEDE Option 7–42 7.2.51 SYSTEM_PROTECTION Option 7–43 7.2.52 TEMPORARY Option 7–44 7.2.53 TRUNCATE Option 7–45 7.2.54 USER_OPEN Option 7–45 7.2.55 WORLD_PROTECTION Option 7–47 7.2.56 WRITE_BEHIND Option 7–48 7.2.57 WRITE_CHECK Option 7–48 7.3 ENVIRONMENT OPTIONS FOR FILE PROTECTION AND FILE SHARING 7–49 7.3.1 File Protection 7–49 7.3.1.1 Defining a File’s Ownership • 7–49 7.3.1.2 Defining a File’s Protection • 7–50 7.3.2 File Sharing 7–51 7.3.2.1 Specifying File Sharing • 7–51 7.3.2.2 File Locking • 7–53 7.3.2.3 Record Locking • 7–54 7.3.2.4 Examples of File Sharing • 7–55 7.4 ENVIRONMENT OPTIONS FOR I/O OPTIMIZATION 7–56 CHAPTER 8 INPUT/OUTPUT STATEMENT OPTIONS 8–1 8.1 OPTION FORMAT 8–1 8.2 SUMMARY OF INPUT/OUTPUT STATEMENT OPTIONS 8–1 8.2.1 CANCEL_CONTROL_O Option 8–3 8.2.2 FAST_DELETE Option 8–4 8.2.3 FIXED_CONTROL_FROM Option 8–4 8.2.4 FIXED_CONTROL_TO Option 8–5 8.2.5 INDEX_NUMBER Option 8–6 8.2.6 LOCK_ON_READ Option 8–6 8.2.7 LOCK_ON_WRITE Option 8–7 8.2.8 MANUAL_UNLOCKING Option 8–7 viii Contents 8.2.9 MATCH_NEXT