CONTENTS Title Page Copyright Page Preface New and Changed Features Developing VAX C Programs on VMS Systems 1 Developing VAX C Programs at the DCL Command Level 1.1 DCL Commands for Program Development 1.2 Creating a VAX C Program 1.2.1 Using VAXTPU 1.2.1.1 The EVE Interface 1.3 Compiling a VAX C Program 1.3.1 The CC Command 1.3.2 The CC Command Qualifiers 1.3.2.1 Using the /DEFINE and /UNDEFINE Qualifiers 1.3.3 Compiler Error Messages 1.4 Linking a VAX C Program 1.4.1 The LINK Command 1.4.2 LINK Command Qualifiers 1.4.3 Linker Input Files 1.4.4 Linker Output Files 1.4.5 Linking Against Object Module Libraries and Shareable Images 1.4.5.1 Object Module Libraries 1.4.5.2 Linking Against the RTL Object Libraries 1.4.5.3 Linking Against the RTL Shareable Images 1.4.6 Linker Error Messages 1.5 Running a VAX C Program 2 Using the VMS Debugger 2.1 Overview 2.2 Features of the Debugger 2.3 Getting Started with the Debugger 2.3.1 Compiling and Linking a Program to Prepare for Debugging 2.3.2 Starting and Terminating a Debugging Session 2.3.3 Aborting Program Execution or Debugger Commands 2.3.4 Entering Debugger Commands 2.3.5 Viewing Your Source Code 2.3.5.1 Noscreen Mode 2.3.5.2 Screen Mode 2.3.6 Controlling and Monitoring Program Execution 2.3.6.1 Starting and Resuming Program Execution 2.3.6.2 Determining Where Execution Is Suspended-SHOW CALLS 2.3.6.3 Suspending Program Execution 2.3.6.4 Tracing Program Execution 2.3.6.5 Monitoring Changes in Variables 2.3.7 Examining and Manipulating Data 2.3.7.1 Displaying the Values of Variables 2.3.7.2 Changing the Values of Variables 2.3.7.3 Evaluating Expressions 2.4 Notes on Debugger Support for VAX C 2.4.1 Debugger Command-Line Options 2.4.2 Accessing Scalar Variables 2.4.3 Accessing Arrays 2.4.4 Accessing Character Strings 2.4.5 Accessing Structures and Unions 2.5 Controlling Symbol References 2.5.1 Module Setting 2.5.2 Resolving Multiply Defined Symbols 2.6 Sample Debugging Session 3 VAX C Support for Parallel Processing 3.1 Overview of Parallel Processing 3.2 Preparing Programs for Parallel Processing 3.3 Conditions That Inhibit Parallel Processing 3.4 Data-Dependency Analysis 3.4.1 Array Variable References 3.4.2 Function Calls 3.4.2.1 math.h Function Calls 3.4.3 Pointer Variable References 3.4.4 Scalar Variable References 3.5 Rewriting Code to Resolve Dependencies 3.5.1 Loop Alignment 3.5.2 Code Replication 3.5.3 Loop Distribution 3.6 Storage Classes and Parallel Processing 3.7 Decomposition Pragmas 3.7.1 The ignore_dependency Decomposition Pragma 3.7.2 The safe_call Decomposition Pragma 3.7.3 The sequential_loop Decomposition Pragma 3.8 Memory-Management Functions 3.9 Tuning Issues Related to Parallel Processing 3.9.1 Customizing the Parallel-Processing Run-Time Environment 3.9.1.1 Controlling the Number of Processes (FOR$PROCESSES) 3.9.1.2 Controlling Internal Spin Waits (FOR$SPIN_WAIT) 3.9.1.3 Controlling the State of a Process (FOR$STALL_WAIT) 3.9.2 System Parameters Set with the SYSGEN Utility 3.9.2.1 Global Section Descriptor Count (GBLSECTIONS) 3.9.2.2 Global Page Table Entry Count (GBLPAGES) 3.9.2.3 Global Page File Limit (GBLPAGFIL) 3.9.3 User Parameters Set with the AUTHORIZE Utility 3.9.4 Other Tuning Considerations VAX C Programming Concepts 4 VAX C Tutorial 4.1 C Programming Language Overview 4.2 VAX C Programming Language Overview 4.3 Writing a Program 4.4 Producing Input/Output (I/O) 4.5 Conditional Execution of Code 4.5.1 The if Statement 4.5.2 The switch Statement 4.5.3 Loops 4.6 Values, Addresses, and Pointers 4.7 Aggregates 4.7.1 Arrays and Character Strings 4.7.2 Structures and Unions 5 Program Structure 5.1 Function Definitions 5.1.1 Main Function and Function Identifiers 5.1.2 Parameter List Declarations 5.1.3 Function Return Data Types 5.1.4 Variable-Length Parameter Lists 5.2 Function Declarations 5.3 Function Prototypes 5.3.1 Using Function Prototypes 5.4 Using Parameters and Arguments 5.4.1 Function and Array Identifiers as Arguments 5.4.2 Passing Arguments to the main Function 5.5 Identifiers 5.6 Language Keywords 5.7 Blocks 5.8 Comments 5.9 LINT-Like Functionality 6 Statements 6.1 Control Flow Statements 6.1.1 The null Statement 6.1.2 The goto Statement 6.1.3 The label Statement 6.2 Expressions and Blocks as Statements 6.2.1 The expression Statement 6.2.2 The compound Statement 6.3 Conditional Statements 6.3.1 The if Statement 6.3.2 The switch Statement 6.3.2.1 Declarations Within a switch Statement 6.4 Looping Statements 6.4.1 The for Statement 6.4.2 The while Statement 6.4.3 The do Statement 6.5 Interrupting Statements 6.5.1 The break Statement 6.5.2 The continue Statement 6.5.3 The return Statement 7 Expressions and Operators 7.1 lvalues and rvalues 7.2 Primary Expressions and Operators 7.2.1 Parenthetical Expressions 7.2.2 Function Calls 7.2.3 Array References 7.2.4 Structure and Union References 7.3 Overview of the VAX C Operators 7.4 Unary Expressions and Operators 7.4.1 Negating Arithmetic and Logical Expressions 7.4.2 Incrementing and Decrementing Variables 7.4.3 Computing Addresses and Dereferencing Pointers 7.4.4 Calculating a One's Complement 7.4.5 Forcing Conversions to a Specific Type 7.4.6 Calculating Sizes of Variables and Data Types 7.5 Binary Expressions and Operators 7.5.1 Additive Operators 7.5.2 Multiplication Operators 7.5.3 Equality Operators 7.5.4 Relational Operators 7.5.5 Bitwise Operators 7.5.6 Logical Operators 7.5.7 Shift Operators 7.6 Conditional Operator 7.7 Assignment Expressions and Operators 7.8 Comma Expression and Operator 7.9 Data-Type Conversions 7.9.1 Converting Operands 7.9.2 Converting Function Arguments 8 Data Types and Declarations 8.1 Constants 8.2 Variables 8.2.1 Classification of Variables 8.2.1.1 Data-Type Keywords 8.2.1.2 Format of a Variable Declaration 8.3 Integers (int, long, short, char, and unsigned) 8.3.1 Integer Constants 8.3.2 Character Constants 8.3.3 Escape Sequences 8.4 Floating-Point Numbers (float and double) 8.4.1 Floating-Point Constants 8.5 Pointers 8.5.1 void Pointers 8.6 Enumerated Types (enum) 8.7 Arrays ([ ]) 8.7.1 Initializing Arrays 8.8 Character-String Variables (char * and char [ ]) 8.8.1 Character-String Constants 8.9 Structures and Unions (struct and union) 8.9.1 Declaring a Structure or Union 8.9.2 Referencing Members of Structures or Unions 8.9.3 Initializing Structures and Unions 8.9.4 Variant Structures and Unions 8.9.5 Bit Fields 8.10 The void Keyword 8.11 The typedef Keyword 8.12 Interpreting Declarations 9 Storage Classes and Allocation 9.1 The Scope of an Identifier 9.1.1 The Compilation and Linking Process 9.1.2 Position of the Declaration 9.1.3 Lexical Scope and Link-Time Scope 9.1.4 Program Example 9.2 Storage Allocation 9.3 Internal Storage Classes 9.3.1 The auto Specifier 9.3.2 The register Specifier 9.4 Static Storage Class 9.5 External Storage Class 9.6 Global Storage Classes 9.6.1 The globaldef and globalref Specifiers 9.6.1.1 Comparing the Global and the External Storage Classes 9.6.2 The globalvalue Specifier 9.6.3 Global Enumerated Types 9.7 Data-Type Modifiers 9.7.1 The const Modifier 9.7.2 The volatile Modifier 9.8 Storage-Class Modifiers 9.8.1 The noshare Modifier 9.8.2 The readonly Modifier 9.8.3 The _align Modifier 10 Preprocessor Directives 10.1 Macro Definitions (#define and #undef) 10.1.1 Constant Identifiers 10.1.2 Canceling Definitions (#undef) 10.1.3 Macro Parameters 10.1.4 Listing Substituted Lines 10.2 Common Data Dictionary Extraction (#dictionary) 10.2.1 Using the #dictionary Directive 10.2.2 Support for CDD Data Types 10.3 Conditional Compilation (#if, #ifdef, #ifndef, #else, #elif, and #endif) 10.3.1 The defined Operator 10.4 File Inclusion (#include) 10.4.1 Inclusion Using Angle Brackets 10.4.2 Inclusion Using Quotation Marks ( " " ) 10.4.3 Inclusion of Text Modules 10.4.4 Macro Substitution in #include Directives 10.5 Specifying Line Numbers (#line and #) 10.6 Specifying the Module Name and Identification (#module) 10.7 Implementation-Specific Preprocessor Directive (#pragma) 10.7.1 #pragma [no]builtins Directive 10.7.2 #pragma ignore_dependency Directive 10.7.3 #pragma [no]inline 10.7.3.1 Restrictions on Inline Expansion 10.7.4 #pragma [no]member_alignment 10.7.5 #pragma safe_call Directive 10.7.6 #pragma sequential_loop Directive 10.7.7 #pragma [no]standard Directive 11 Predefined Macros and Built-In Functions 11.1 Predefined Macros 11.1.1 CC$gfloat (G_Floating Identification Macro) 11.1.2 CC$parallel (Parallel-Processing Identification Macro) 11.1.3 The _ _DATE_ _ Macro 11.1.4 The _ _FILE_ _ Macro 11.1.5 The _ _LINE_ _ Macro 11.1.6 The _ _TIME_ _ Macro 11.1.7 vax, vms, vaxc, and vax11c (System-Identification Macros) 11.2 Built-In Functions 11.2.1 Add Aligned Word Interlocked (_ADAWI) 11.2.2 Branch on Bit Clear-Clear Interlocked (_BBCCI) 11.2.3 Branch on Bit Set-Set Interlocked (_BBSSI) 11.2.4 Find First Clear Bit (_FFC) 11.2.5 Find First Set Bit (_FFS) 11.2.6 Halt (_HALT) 11.2.7 Insert Entry into Queue at Head Interlocked (_INSQHI) 11.2.8 Insert Entry into Queue at Tail Interlocked (_INSQTI) 11.2.9 Insert Entry in Queue (_INSQUE) 11.2.10 Load Process Context (_LDPCTX) 11.2.11 Locate Character (_LOCC) 11.2.12 Move from Processor Register (_MFPR) 11.2.13 Move Character 3 Operand (_MOVC3) 11.2.14 Move Character 5 Operand (_MOVC5) 11.2.15 Move from Processor Status Longword (_MOVPSL) 11.2.16 Move to Processor Register (_MTPR) 11.2.17 Probe Read Accessibility (_PROBER) 11.2.18 Probe Write Accessibility (_PROBEW) 11.2.19 Read General-Purpose Register (_READ_GPR) 11.2.20 Remove Entry from Queue at Head Interlocked (_REMQHI) 11.2.21 Remove Entry from Queue at Tail Interlocked (_REMQTI) 11.2.22 Remove Entry from Queue (_REMQUE) 11.2.23 Scan Characters (_SCANC) 11.2.24 Simple Read (_SIMPLE_READ) 11.2.25 Simple Write (_SIMPLE_WRITE) 11.2.26 Skip Character (_SKPC) 11.2.27 Span Characters (_SPANC) 11.2.28 Save Process Context (_SVPCTX) 11.2.29 Write General-Purpose Register (_WRITE_GPR) Using VAX C Features on VMS Systems 12 Using VAX Record Management Services 12.1 RMS File Organization 12.1.1 Sequential File Organization 12.1.2 Relative File Organization 12.1.3 Indexed File Organization 12.2 Record Access Modes 12.3 RMS Record Formats 12.4 RMS Functions 12.5 Writing VAX C Programs Using RMS 12.5.1 Initializing File Access Blocks 12.5.2 Initializing Record Access Blocks 12.5.3 Initializing Extended Attribute Blocks 12.5.4 Initializing Name Blocks 12.6 RMS Example Program 13 Using VAX C in the Common Language Environment 13.1 The VAX Procedure Calling and Condition Handling Standard 13.1.1 Register and Stack Usage 13.1.2 Return of the Function Value 13.1.3 The Argument List 13.2 Specifying Parameter-Passing Mechanisms 13.2.1 Passing Arguments by Immediate Value 13.2.2 Passing Arguments by Reference 13.2.3 Passing Arguments by Descriptor 13.2.4 VAX C Default Parameter-Passing Mechanisms 13.3 Interlanguage Calling 13.3.1 Calling VAX FORTRAN 13.3.2 Calling VAX MACRO 13.3.3 Calling VAX BASIC 13.3.4 Calling VAX Pascal 13.4 Sharing Global Data 13.4.1 Sharing Program Sections with FORTRAN Common Blocks 13.4.2 Sharing Program Sections with PL/I Externals 13.4.3 Sharing Program Sections with MACRO Programs 13.5 VMS Run-Time Library Routines 13.6 VMS System Services Routines 13.7 Calling Routines 13.7.1 Determining the Type of Call 13.7.2 Declaring an External Routine and Its Arguments 13.7.3 Calling the External Routine 13.7.4 System Routine Arguments 13.7.5 Symbol Definitions 13.7.6 Condition Values 13.7.7 Checking System Service Return Values 13.8 Variable-Length Argument Lists in System Services 13.9 Return Status Values 13.9.1 Format of Return Status Values 13.9.2 Manipulating Return Status Values 13.9.3 Testing for Success or Failure 13.9.4 Testing for Specific Return Status Values 13.10 Examples of Calling System Routines 14 VAX C Implementation Notes 14.1 Program Sections 14.1.1 Attributes of Program Sections (Psects) 14.1.2 Program Sections Created by VAX C A VAX C Definition Modules B VAX C Compiler Messages C Optional Programming/ Productivity Tools C.1 Using VAX LSE with VAX C C.1.1 Entering Source Code Using Tokens and Placeholders C.1.2 Compiling Source Code C.1.2.1 Pragma Insertions and Decomposition C.1.3 Examples C.1.3.1 Preprocessor Lines C.1.3.2 External Definition C.1.3.3 Function Definition C.1.3.4 Block Declaration C.1.3.5 Statements and Expressions 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 Selecting an SCA Library C.2.2.4 Loading Data Analysis Files into a Local Library C.2.3 Using SCA for Cross-Referencing D Language Summary D.1 The CC Command D.2 The LINK Command D.3 Data-Type Keywords D.4 Precedence of Operators D.5 Statements D.6 Conversion Rules D.7 Escape Sequences D.8 Preprocessor Directives D.9 Record Management Services (RMS) E Working with the Multiprocess Debugging Configuration E.1 Getting Started E.1.1 Establishing a Multiprocess Debugging Configuration E.1.2 Invoking the Debugger E.1.3 The Visible Process and Process-Specific Commands E.1.4 Obtaining Information About Processes E.1.5 Bringing a Spawned Process Under Debugger Control E.1.6 Broadcasting Commands to Selected Processes E.1.7 Controlling Execution E.1.7.1 Controlling Execution with SET MODE NOINTERRUPT E.1.7.2 Putting Selected Processes on Hold E.1.8 Changing the Visible Process E.1.9 Dynamic Process Setting E.1.10 Monitoring the Termination of Images E.1.11 Terminating the Debugging Session E.1.12 Releasing Selected Processes from Debugger Control E.1.13 Aborting Debugger Commands and Interrupting Program Execution E.2 Supplemental Information E.2.1 Specifying Processes in Debugger Commands E.2.2 Monitoring Process Activation and Termination E.2.3 Interrupting the Execution of an Image to Connect It to the Debugger E.2.3.1 Using the CTRL/Y-DEBUG Sequence to Invoke the Debugger E.2.3.2 Using the CONNECT Command to Interrupt an Image E.2.4 Screen Mode Features for Multiprocess Debugging E.2.5 Setting Watchpoints in Global Sections E.2.6 Compatibility of Multiprocess Commands with the Default Configuration E.3 Sample Multiprocess Debugging Session E.4 Considerations for Multiprocess Debugging E.4.1 User Quotas E.4.2 System Resources VAX C Glossary EXAMPLES 1-1 Symbol Cross-References in a Compiler Listing 2-1 Debugging Sample Program SCALARS.C 2-2 Debugging Sample Program ARRAY.C 2-3 Debugging Sample Program STRING.C 2-4 Debugging Sample Program STRUCT.C 2-5 Debugging Sample Program ARSTRUCT.C 2-6 Debugging Sample Program POWER.C 2-7 A Sample Debugging Session 3-1 Using the #pragma ignore_dependency Directive 3-2 Using the #pragma ignore_dependency Directive 3-3 Using the #pragma safe_call Directive 3-4 Using the #pragma sequential_loop Directive 4-1 Simple Addition in VAX C 4-2 Output of Information 4-3 Output Using the Newline Character 4-4 Conditional Execution Using the if Statement 4-5 Conditional Execution Using the switch Statement 4-6 Looping Using the do Statement 4-7 Looping Using the for Statement 4-8 Character-String Constants and Arrays 4-9 Single Storage Allocation of Unions 4-10 Structures 5-1 Case Conversion Program 5-2 Declaring Functions 5-3 Declaring Functions Passed as Arguments 5-4 Echo Program Using Command-Line Arguments 5-5 Scope of Variable Declarations in Nested Blocks 6-1 Using switch to Count Blanks, Tabs, and Newlines 8-1 Rules for Initialization of Structures 9-1 Scope and Externally Defined Variables 9-2 Reinitializing Two auto Variables 9-3 Using Global Variables 9-4 Using the globalvalue Specifier 10-1 Nested Substitution Directives 12-1 External Data Declarations and Definitions 12-2 Main Program Section 12-3 Function Initializing RMS Data Structures 12-4 Internal Functions 12-5 Utility Function: Adding Records 12-6 Utility Function: Deleting Records 12-7 Utility Function: Typing the File 12-8 Utility Function: Printing the File 12-9 Utility Function: Updating the File 13-1 Passing Floating-Point Arguments by Immediate Value 13-2 Passing Arguments by Reference 13-3 Passing Arguments by Descriptor 13-4 Passing Compile-Time String Descriptors 13-5 VAX C Function Calling a VAX FORTRAN Subprogram 13-6 VAX FORTRAN Subprogram Calling a VAX C Function 13-7 VAX C Function Emulating a VAX FORTRAN CHARACTER * ( * ) Function 13-8 VAX MACRO Program Calling a VAX C Function 13-9 VAX C Program Calling a VAX MACRO Program 13-10 VAX C Function Calling a VAX BASIC Function 13-11 VAX BASIC Program Calling a VAX C Function 13-12 VAX C Function Calling a VAX Pascal Routine 13-13 VAX Pascal Program Calling a VAX C Function 13-14 Sharing Data with a FORTRAN Program in Named Program Sections 13-15 Sharing Data with a FORTRAN Program in a VAX C Structure 13-16 Sharing Data with a PL/I Program in Named Program Sections 13-17 Sharing Data with a PL/I Program in a VAX C Structure 13-18 Sharing Data with a MACRO Program in a VAX C Structure 13-19 Checking System Service Return Values 13-20 Using Variable-Length Argument Lists 13-21 Testing for Success 13-22 Testing for Specific Return Status Values 13-23 Passing Arguments to System Services 13-24 Determining $QIO Completion 13-25 Using Time Routines E-1 VAX C Program Used for Multiprocess Debugging Session E-2 Sample Multiprocess Debugging Session FIGURES 1-1 DCL Commands for Developing Programs 2-1 Debugger Keypad Key Functions 3-1 Sequential and Parallel Loop Execution Across Time 3-2 Program Cycle Using Decomposition 4-1 rvalues, lvalues, and Assigning Pointers 4-2 The Indirection Operator in Assignments 7-1 Boolean Algebra and the Bitwise Operators 8-1 Alignment of Structure Members 13-1 The Call Stack 13-2 Structure of a VAX Argument List 13-3 Example of a VAX Argument List 13-4 Passing Arguments by Immediate Value 13-5 Bit Fields Within a Return Status Value 13-6 Internal Representation of a Status Value C-1 Use of SCA for Multimodular Development TABLES 1-1 Debugger Compilation Options 1-2 /MACHINE_CODE Qualifier Options 1-3 /[NO]OPTIMIZE Qualifier Options 1-4 /SHOW Qualifier Options 1-5 /WARNINGS Qualifier Options 1-6 VMS Linker Default File Types for Input Files 2-1 Supported Operators 2-2 Unsupported Operators 3-1 VAX C Parallel-Processing Support Mechanisms 3-2 VAX C Decomposition Pragmas 3-3 Logical Names Used for Run-Time Tuning 3-4 Sysgen Parameters Requiring Changes for Parallel Processing 5-1 VAX C Keywords 5-2 VAX C Features Similar to the LINT Utility 7-1 VAX C Operators 7-2 Precedence of VAX C Operators 8-1 VAX C Data-Type Keywords 8-2 Size and Range of VAX C Integers 8-3 VAX C Escape Sequences 9-1 VAX C Storage Classes and Storage-Class Specifiers 9-2 Scope and the Storage-Class Specifiers 9-3 The Variables in Example 9-1 and Their Storage Classes 9-4 Location, Lifetime, and the Storage-Class Keywords 9-5 Predefined Alignment Constants 10-1 Mapping Between CDD and VAX C Data Types 12-1 Common RMS Run-Time Processing Functions 12-2 VAX C RMS #include Modules 12-3 RMS Prototype Data Structures 13-1 VAX Register Usage 13-2 Status Values of SYS$SETEF 13-3 Status Values of SYS$READEF 13-4 Valid Class Codes 13-5 Atomic Data Types 13-6 Valid Parameter-Passing Mechanisms in VAX C 13-7 Default Passing Mechanisms 13-8 Run-Time Library Facilities 13-9 System Services 13-10 VAX C Implementation 13-11 Possible Severity Values 13-12 Facility Codes 14-1 Program Section Attributes 14-2 Combinations of Storage-Class Specifiers and Modifiers 14-3 Combination Attributes A-1 VAX C Definition Modules C-1 LSE Placeholders C-2 Commands to Manipulate Tokens and Placeholders C-3 LSE Commands to Review and Examine Source Code C-4 SCA Commands to Use Within LSE D-1 Precedence of Operators D-2 Escape Sequences D-3 RMS Module Names D-4 RMS Templates E-1 Debugging States E-2 Process Specifications E-3 Changed and New Keypad Key Functions