CONTENTS

  Title Page

  Copyright Page

  Preface

  1      Overview of VAX PL/I

  2      Developing VAX PL/I Programs at the DCL Command Level

  2.1     DCL Commands for Program Development

  2.2     Creating a VAX PL/I Program
    2.2.1      Using VAX EDT
    2.2.2      Using VAX LSE
    2.2.3      Using VAXTPU
      2.2.3.1      The EVE Interface
      2.2.3.2      The EDT Keypad Emulator Interface

  2.3     Compiling a VAX PL/I Program
    2.3.1      PLI Command
    2.3.2      PLI Command Qualifiers
    2.3.3      VAX PL/I Preprocessor
      2.3.3.1      Preprocessor Compilation Control
      2.3.3.2      Preprocessor Procedures
    2.3.4      Compiler Error Messages
    2.3.5      Compiler Listings

  2.4     Linking a VAX PL/I Program
    2.4.1      LINK Command
    2.4.2      LINK Command Qualifiers
    2.4.3      Linker Input Files
    2.4.4      Linker Output Files
    2.4.5      Object Module Libraries
    2.4.6      Linker Error Messages

  2.5     Running a VAX PL/I Program

  3      Using the VMS Debugger

  3.1     Overview

  3.2     Features of the Debugger

  3.3     Getting Started with the Debugger
    3.3.1      Compiling and Linking a Program to Prepare for Debugging
    3.3.2      Starting and Terminating a Debugging Session
    3.3.3      Issuing Debugger Commands
    3.3.4      Viewing Your Source Code
      3.3.4.1      Noscreen Mode
      3.3.4.2      Screen Mode
    3.3.5      Controlling and Monitoring Program Execution
      3.3.5.1      Starting and Resuming Program Execution
      3.3.5.2      Determining the Current Value of the Program Counter
      3.3.5.3      Suspending Program Execution
      3.3.5.4      Tracing Program Execution
      3.3.5.5      Monitoring Changes in Variables
    3.3.6      Examining and Manipulating Data
      3.3.6.1      Displaying the Values of Variables
      3.3.6.2      Changing the Values of Variables
      3.3.6.3      Evaluating Expressions
      3.3.6.4      Notes on Debugger Support for VAX PL/I
    3.3.7      Controlling Symbol References
      3.3.7.1      Module Setting
      3.3.7.2      Resolving Multiply Defined Symbols

  3.4     Sample Debugging Session

  3.5     Debugger Command Summary
    3.5.1      Starting and Terminating a Debugging Session
    3.5.2      Controlling and Monitoring Program Execution
    3.5.3      Examining and Manipulating Data
    3.5.4      Controlling Type Selection and Symbolization
    3.5.5      Controlling Symbol Lookup
    3.5.6      Displaying Source Code
    3.5.7      Using Screen Mode
    3.5.8      Editing Source Code
    3.5.9      Defining Symbols
    3.5.10     Using Keypad Mode
    3.5.11     Using Command Procedures and Log Files
    3.5.12     Using Control Structures
    3.5.13     Additional Commands

  4      The File System

  4.1     File Control

  4.2     Using the VMS File System for I/O
    4.2.1      PL/I Files and VMS File Specifications
    4.2.2      Using the TITLE Option
    4.2.3      Using Logical Names
    4.2.4      Using the DEFAULT_FILE_NAME Option
    4.2.5      Expanding File Specifications

  4.3     Error Handling
    4.3.1      Values Returned by PL/I Built-In Functions for Error Handling
    4.3.2      Writing an Error Handler
    4.3.3      Default Error Handling for the File System

  5      Stream Input/Output

  6      Record Input/Output

  6.1     File Organizations

  6.2     Access Modes
    6.2.1      Sequential Access
    6.2.2      Random Access
    6.2.3      Random and Sequential Access
    6.2.4      Block Input/Output
    6.2.5      Access by Record Identification

  6.3     Record Formats
    6.3.1      Fixed-Length Records
    6.3.2      Variable-Length Records
    6.3.3      Variable-Length Records with a Fixed-Length Control Area

  6.4     Carriage Control

  6.5     Sequential Files
    6.5.1      Creating a Sequential File
    6.5.2      Using Magnetic Tape Files
    6.5.3      Allocated and Spooled Devices

  6.6     Relative Files
    6.6.1      Relative File Organization
    6.6.2      Creating a Relative File
    6.6.3      Using Relative Files
    6.6.4      Error Handling

  6.7     Indexed Sequential Files
    6.7.1      Indexed File Organization
    6.7.2      Defining and Creating an Indexed Sequential File
      6.7.2.1      Using EDIT/FDL
      6.7.2.2      Using a PL/I Program
    6.7.3      Defining Keys
    6.7.4      Using Indexed Sequential Files

  7      Options of the ENVIRONMENT Attribute

  7.1     Specifying and Using ENVIRONMENT Options
    7.1.1      Arguments for ENVIRONMENT Options
      7.1.1.1      Expressions
      7.1.1.2      Variable References
      7.1.1.3      Boolean Values
    7.1.2      Interpretation of ENVIRONMENT Options for Existing Files
    7.1.3      Determining ENVIRONMENT Options
    7.1.4      Device Independence of ENVIRONMENT Options
    7.1.5      Conflicting and Invalid ENVIRONMENT Options

  7.2     Summary of ENVIRONMENT Options
    7.2.1      APPEND Option
    7.2.2      BACKUP_DATE Option
    7.2.3      BATCH Option
    7.2.4      BLOCK_BOUNDARY_FORMAT Option
    7.2.5      BLOCK_IO Option
    7.2.6      BLOCK_SIZE Option
    7.2.7      BUCKET_SIZE Option
    7.2.8      CARRIAGE_RETURN_FORMAT Option
    7.2.9      CONTIGUOUS Option
    7.2.10     CONTIGUOUS_BEST_TRY Option
    7.2.11     CREATION_DATE Option
    7.2.12     CURRENT_POSITION Option
    7.2.13     DEFAULT_FILE_NAME Option
    7.2.14     DEFERRED_WRITE Option
    7.2.15     DELETE Option
    7.2.16     EXPIRATION_DATE Option
    7.2.17     EXTENSION_SIZE Option
    7.2.18     FILE_ID Option
    7.2.19     FILE_ID_TO Option
    7.2.20     FILE_SIZE Option
    7.2.21     FIXED_CONTROL_SIZE Option
    7.2.22     FIXED_CONTROL_SIZE_TO Option
    7.2.23     FIXED_LENGTH_RECORDS Option
    7.2.24     GROUP_PROTECTION Option
    7.2.25     IGNORE_LINE_MARKS Option
    7.2.26     INDEX_NUMBER Option
    7.2.27     INDEXED Option
    7.2.28     INITIAL_FILL Option
    7.2.29     MAXIMUM_RECORD_NUMBER Option
    7.2.30     MAXIMUM_RECORD_SIZE Option
    7.2.31     MULTIBLOCK_COUNT Option
    7.2.32     MULTIBUFFER_COUNT Option
    7.2.33     NO_SHARE Option
    7.2.34     OWNER_GROUP Option
    7.2.35     OWNER_ID Option
    7.2.36     OWNER_MEMBER Option
    7.2.37     OWNER_PROTECTION Option
    7.2.38     PRINTER_FORMAT Option
    7.2.39     READ_AHEAD Option
    7.2.40     READ_CHECK Option
    7.2.41     RECORD_ID_ACCESS Option
    7.2.42     RETRIEVAL_POINTERS Option
    7.2.43     REVISION_DATE Option
    7.2.44     REWIND_ON_CLOSE Option
    7.2.45     REWIND_ON_OPEN Option
    7.2.46     SCALARVARYING Option
    7.2.47     SHARED_READ Option
    7.2.48     SHARED_WRITE Option
    7.2.49     SPOOL Option
    7.2.50     SUPERSEDE Option
    7.2.51     SYSTEM_PROTECTION Option
    7.2.52     TEMPORARY Option
    7.2.53     TRUNCATE Option
    7.2.54     USER_OPEN Option
    7.2.55     WORLD_PROTECTION Option
    7.2.56     WRITE_BEHIND Option
    7.2.57     WRITE_CHECK Option

  7.3     ENVIRONMENT Options for File Protection and File Sharing
    7.3.1      File Protection
      7.3.1.1      Defining a File's Ownership
      7.3.1.2      Defining a File's Protection
    7.3.2      File Sharing
      7.3.2.1      Specifying File Sharing
      7.3.2.2      File Locking
      7.3.2.3      Record Locking
      7.3.2.4      Examples of File Sharing

  7.4     ENVIRONMENT Options for I/O Optimization

  8      Input/Output Statement Options

  8.1     Option Format

  8.2     Summary of Input/Output Statement Options
    8.2.1      CANCEL_CONTROL_O Option
    8.2.2      FAST_DELETE Option
    8.2.3      FIXED_CONTROL_FROM Option
    8.2.4      FIXED_CONTROL_TO Option
    8.2.5      INDEX_NUMBER Option
    8.2.6      LOCK_ON_READ Option
    8.2.7      LOCK_ON_WRITE Option
    8.2.8      MANUAL_UNLOCKING Option
    8.2.9      MATCH_NEXT Option
    8.2.10     MATCH_NEXT_EQUAL Option
    8.2.11     NO_ECHO Option
    8.2.12     NO_FILTER Option
    8.2.13     NOLOCK Option
    8.2.14     NONEXISTENT_RECORD Option
    8.2.15     PROMPT Option
    8.2.16     PURGE_TYPE_AHEAD Option
    8.2.17     READ_REGARDLESS Option
    8.2.18     RECORD_ID Option
    8.2.19     RECORD_ID_TO Option
    8.2.20     TIMEOUT_PERIOD Option
    8.2.21     WAIT_FOR_RECORD Option

  9      File-Handling Built-In Subroutines

  9.1     DISPLAY Built-In Subroutine

  9.2     EXTEND Built-In Subroutine

  9.3     FLUSH Built-In Subroutine

  9.4     FREE Built-In Subroutine

  9.5     NEXT_VOLUME Built-In Subroutine

  9.6     RELEASE Built-In Subroutine

  9.7     REWIND Built-In Subroutine

  9.8     SPACEBLOCK Built-In Subroutine

  10     Error Handling

  10.1    RESIGNAL Built-In Subroutine

  10.2    ON-Unit Actions
    10.2.1     Handling the Condition
    10.2.2     Resignaling the Condition
    10.2.3     Unwinding the Call Stack
    10.2.4     Stopping the Program

  10.3    Relationship of VMS Condition Handlers to PL/I ON-Units

  10.4    Search Path for ON-Units
    10.4.1     Default Handling for Main Procedures
    10.4.2     Default Handling for Non-Main Procedures
    10.4.3     Multiple Conditions

  10.5    Scope of ON-Units

  10.6    ON-Unit Examples

  10.7    Condition-Handling Built-In Functions
    10.7.1     ONARGSLIST Built-In Function
    10.7.2     ONCODE Built-In Function
    10.7.3     ONFILE Built-In Function
    10.7.4     ONKEY Built-In Function

  11     Using VAX PL/I in the Common Language Environment

  11.1    The VAX Procedure Calling and Condition Handling Standard
    11.1.1     Register and Stack Usage
    11.1.2     Return of the Function Value
    11.1.3     The Argument List

  11.2    Parameter-Passing Mechanisms
    11.2.1     Passing Parameters by Reference
      11.2.1.1     Using the ANY Attribute
      11.2.1.2     Dummy Arguments for Arguments Passed by Reference
      11.2.1.3     Using Pointer Values for Arguments Passed by Reference
      11.2.1.4     Passing Arrays to a FORTRAN Routine by Reference
    11.2.2     Passing Parameters by Descriptor
      11.2.2.1     Passing Character Strings
      11.2.2.2     Passing Varying Character Strings
      11.2.2.3     Using ANY CHARACTER( * )
      11.2.2.4     Using ANY DESCRIPTOR
      11.2.2.5     Passing an Actual Descriptor
    11.2.3     Passing Parameters by Value
      11.2.3.1     Dummy Arguments for Arguments Passed by Value
    11.2.4     Special Parameter Attributes
      11.2.4.1     LIST Attribute
      11.2.4.2     OPTIONAL Attribute
      11.2.4.3     TRUNCATE Attribute
    11.2.5     Summary of Rules for Passing Parameters

  11.3    VMS Run-Time Library Routines

  11.4    VMS System Service Routines

  11.5    VMS Utility Routines
    11.5.1     VMS SORT/MERGE Routines

  11.6    Calling Routines
    11.6.1     Determining the Type of Call
    11.6.2     Declaring an External Routine and Its Arguments
    11.6.3     Calling the External Routine
    11.6.4     Calling System Routines
      11.6.4.1     Declaring System Routines
      11.6.4.2     System Routine Arguments
      11.6.4.3     Symbol Definitions

  11.7    Condition Values
    11.7.1     Testing for Specific Condition Values
    11.7.2     Setting and Displaying Fields Within a Status Value

  11.8    Examples of Calling System Routines
    11.8.1     Logical Name Translation
    11.8.2     Mailbox Services
      11.8.2.1     Creating the Mailbox
      11.8.2.2     Deleting the Mailbox
    11.8.3     Timer and Time Conversion Routines
      11.8.3.1     Obtaining a Time Value in System Format
      11.8.3.2     Setting the Timer
    11.8.4     A Ctrl/c-Handling Routine
      11.8.4.1     Establishing a Ctrl/c-Handling Routine
      11.8.4.2     Ctrl/c Routine
      11.8.4.3     Testing the Ctrl/c Routine
    11.8.5     Obtaining Job/Process Information
    11.8.6     Using SORT Routines

  12     Global Symbols

  12.1    Using Global Symbols in PL/I Procedures
    12.1.1     The GLOBALDEF Attribute
    12.1.2     The GLOBALREF Attribute
    12.1.3     Defining Global Symbols in PL/I
    12.1.4     Using MACRO Global Symbols with Multiple Definitions

  12.2    The READONLY and VALUE Attributes
    12.2.1     The READONLY Attribute
    12.2.2     The VALUE Attribute

  12.3    Obtaining Definitions for System Global Symbols

  13     Mailboxes

  13.1    Using Mailboxes
    13.1.1     System Information
    13.1.2     Applications
    13.1.3     Effects of the OPEN Statement
    13.1.4     Effects of the CLOSE Statement

  13.2    Mailbox Input/Output
    13.2.1     Synchronous Input/Output
    13.2.2     Asynchronous Input/Output

  14     Accessing Files on a Network

  14.1    Remote File Access

  14.2    Task-to-Task Communication

  15     Storage Allocation

  15.1    Program Sections
    15.1.1     Attributes of Program Sections
    15.1.2     Program Sections Created by PL/I
    15.1.3     Sharing Program Sections with FORTRAN Procedures

  15.2    Addressability

  A   PL/I Messages

  A.1     Compiler Messages

  A.2     Run-Time Messages

  A.3     %DICTIONARY Error Messages

  B   Correspondence of PL/I and RMS

  C   Optional Programming Productivity Tools

  C.1     Using LSE with VAX PL/I
    C.1.1      Entering Source Code Using Tokens and Placeholders
    C.1.2      Compiling Source Code
    C.1.3      Examples
    C.1.4      DO Statement
    C.1.5      IF Statement
    C.1.6      Assignment Statement
    C.1.7      DECLARE Statement
    C.1.8      SUBSTR Expression
    C.1.9      %PROCEDURE Statement

  C.2     Using the VAX Source Code Analyzer
    C.2.1      Multimodular Development
    C.2.2      Setting Up an SCA Environment
      C.2.2.1      Creating an SCA Library
      C.2.2.2      Generating the Data Analysis Files
      C.2.2.3      Loading Data Analysis Files into a Local Library
      C.2.2.4      Selecting an SCA Library
    C.2.3      Using SCA for Cross-Referencing

  D   Rules for Conversion of Data

  D.1     Assignments to Arithmetic Variables
    D.1.1      Arithmetic to Arithmetic Conversions
    D.1.2      Pictured to Arithmetic Conversions
    D.1.3      Bit-String to Arithmetic Conversions
    D.1.4      Character String to Arithmetic Conversions

  D.2     Assignments to Bit-String Variables
    D.2.1      Arithmetic and Pictured to Bit-String Conversions
    D.2.2      Character-String to Bit-String Conversions

  D.3     Assignments to Character-String Variables
    D.3.1      Arithmetic to Character-String Conversions
      D.3.1.1      Conversion from Fixed-Point Binary or Decimal
      D.3.1.2      Conversion from Floating-Point Binary or Decimal
    D.3.2      Pictured to Character-String Conversions
    D.3.3      Bit-String to Character-String Conversions

  D.4     Assignments to Pictured Variables

  D.5     Conversions Between Offsets and Pointers

  E   The VAX Common Data Dictionary

  E.1     PL/I and CDDL Data Types

  E.2     Creating CDD Structure Declarations

  E.3     Using the CDD

  EXAMPLES

  2-1        Default Compiler Listing

  2-2        Compiler Storage Map

  2-3        Compiler Performance Statistics

  2-4        Machine Code Listing

  2-5        Preprocessor Compiler Listing

  6-1        Creating a Relative File

  7-1        Explicit Carriage Control

  10-1       Resignaling the Condition

  10-2       Unwinding the Call Stack

  10-3       Execution of an ON-Unit

  10-4       Search for an ON-Unit

  10-5       Multiple Conditions

  10-6       Displaying Arguments Passed to a Condition Handler

  11-1       Writing a Character-String Descriptor

  11-2       Translating a Logical Name

  11-3       Creating a Mailbox

  11-4       Deleting a Mailbox

  11-5       Obtaining a System Time Value

  11-6       Setting a Timer

  11-7       Establishing a Ctrl/c Routine

  11-8       Ctrl/c Handler

  11-9       Testing the Ctrl/c Routine

  11-10      TIMRE and TIMRB

  11-11      Sorting Files

  11-12      A Record Sort

  13-1       Synchronous Mailbox Input/Output

  13-2       Asynchronous Mailbox Input/Output

  14-1       A PL/I Network Source Task

  14-2       A PL/I Target Task

  FIGURES

  2-1        DCL Commands for Developing Programs

  3-1        Debugger Keypad Key Functions

  6-1        A Relative File

  6-2        An Indexed Sequential File

  6-3        Creating a Data File

  10-1       Resignaling a Condition

  10-2       Unwinding the Call Stack

  10-3       Execution of an ON-Unit

  10-4       Search for an ON-Unit

  10-5       Effect of Multiple Conditions

  10-6       The Argument List Passed to an ON-Unit

  11-1       The Call Stack

  11-2       Structure of a VAX Argument List

  11-3       Example of a VAX Argument List

  11-4       Argument Passing by Reference

  11-5       Passing a Pointer Value as an Argument

  11-6       Argument Passing by Descriptor

  11-7       Argument Passing by Immediate Value

  11-8       Condition Value Fields

  C-1        Use of SCA for Multimodular Development

  TABLES

  2-1        Alignment for RISC Data

  2-2        Compiler Optimization Options

  2-3        Compiler Listing Options

  4-1        Default Process Logical Names

  6-1        Attributes and Access Modes for Record Files

  6-2        Key Data Types

  7-1        Summary of ENVIRONMENT Options

  7-2        Printer File Format Carriage Control

  7-3        Effects of File-Sharing Options

  7-4        ENVIRONMENT Options for Optimized Disk File Creation

  7-5        ENVIRONMENT Options for Run-Time Optimization of Input/Output

  8-1        Summary of Input/Output Statement Options

  9-1        Summary of File-Handling Built-In Subroutines

  9-2        ENVIRONMENT Option Values Returned by DISPLAY

  9-3        File Attribute Information Returned by DISPLAY

  9-4        Device Information Returned by DISPLAY

  10-1       ONCODE Values for PL/I ON Conditions

  11-1       VAX Register Usage

  11-2       Run-Time Library Facilities

  11-3       System Services

  11-4       VMS Utilities

  11-5       VAX PL/I Implementation of VMS Usages

  12-1       Comparison of Global Symbols and External Variables

  15-1       Program Section Attributes

  15-2       Program Sections for PL/I Variables

  A-1        CRX Error Messages

  B-1        RMS Fields for PL/I ENVIRONMENT Options