CONTENTS Title Page Copyright Page Preface Acknowledgment 1 Overview of VAX DSM System Overview VAX DSM Language DSM Application Environment Data Management Precompiler Input/Output Processing External Routine Interface Callable Interface Application Interlocking Journaling Library and System Utilities VAX DSM Shareable Images VAX DSM Background Processes Shared Areas of Memory 2 VAX DSM Command Line Getting Started VAX DSM User Modes Running VAX DSM in Programmer Mode Exiting from Programmer Mode Programmer Mode Defaults Running VAX DSM in Application Mode DSM Command Syntax VAX DSM Command Line Qualifiers Command Line Qualifier Syntax Description of Command Line Qualifiers 3 Developing VAX DSM Applications in a VMS Environment Logical Names in a VAX DSM Environment Programming Techniques Running DSM from a DCL Command Procedure Executing a Routine in a Detached Process Using the JOB Command Using Sequential Files to Store Routines Saving a Routine in a Sequential File Restoring a Routine from a Sequential File Printing a Routine Saving and Restoring Globals ( ^%GTI and ^%GTO ) Using the VAX DEC/Code Management System ( ^%CMS ) Introduction to CMS Routine and Global Naming Conventions Used by ^%CMS Running the ^%CMS Utility 4 Parameter Passing and Extrinsic Functions DO Command and Parameter Passing Extrinsic Functions Rules for Extrinsic Function Calls Passing Arrays to Extrinsic Functions 5 Using the VAX DSM Debugger Overview Enabling and Disabling the VAX DSM Debugger Breakpoints Setting Breakpoints with the $ZBREAK Special Variable Setting Breakpoints with the BREAK Command Setting XECUTE String Breakpoints Setting Breakpoint Action Strings Examining Breakpoints Clearing Breakpoints Watchpoints Setting Watchpoints with the $ZWATCH Special Variable Setting Watchpoint Action Strings Examining Watchpoints Clearing Watchpoints Continuing Execution After a Breakpoint or a Watchpoint Debugging Utilities Using the ^%STACK Utility Using the ^%TRACE Utility 6 Using Error Processing Types of Errors Overview of Error Processing Error-Processing Variables and Commands Establishing an Error Handler Call Stacks and DO Frames Error Processing and the Call Stack Exiting from an Error Handler Forcing an Error CTRAP I/O Option ZTRAP Command Using Error Handlers 7 VAX DSM Library Utilities Overview Library Utility Conventions Running the VAX DSM Library Utilities CMS Utility ( ^%CMS ) Conversion Utilities Date and Time Converter ( ^%H ) Numeric Conversion Utilities Decimal to Hex ( ^%DH ) Decimal to Octal ( ^%DO ) Hex to Decimal ( ^%HD ) Hex to Octal ( ^%HO ) Octal to Decimal ( ^%OD ) Octal to Hex ( ^%OH ) Debugger Utilities DSM Information Utilities Devices ( IO^%STAT ) Directories ( ^%DIRSHO ) Job Monitor ( ^%JOB ) System Status ( ^%SY ) Terminals ( TERM^%STAT ) $ZCALLs ( ^%CD ) Volume Set Global Utilities Block Mode Restore ( ^%GBR ) Block Mode Save ( ^%GBS ) Copy ( ^%GC ) Directory ( ^%GD ) Directory (Extended) ( ^%EGD ) Directory (Library) ( LIB^%GD ) Edit ( ^%GEDIT ) Efficiency ( ^%GE ) Journaling ( SETJRN^%GLOMAN ) List ( ^%G ) Management ( ^%GLOMAN ) Protection ( SETPRO^%GLOMAN ) Sequential Restore ( ^%GTI ) Sequential Save ( ^%GTO ) Translation Display ( ^%TRAN ) Miscellaneous Utilities Additional Utility Help ( HELP^%INF ) Error Trapping Error Trapping ( ^%ET ) Error Trapping ( ^%ER ) Global Select ( ^%GSEL ) DSM Help ( ^%HELP ) Device Select ( ^%IOS ) Magtape Status ( ^%MTCHK ) Routine Recompile ( ^%REPLACE ) Routine Select ( ^%RSEL ) Close Devices ( IO^%CLOSE ) Date ( ^%D ) Help List ( ^%HELPLIS ) Menu List ( ^%MENULIS ) Spawn ( ^%SPAWN ) Time ( ^%T ) Routine Utilities Change Every ( ^%RCE ) Compare ( ^%RCMP ) Copy ( ^%RCOPY ) Delete ( ^%RPURGE ) Directory ( ^%RD ) Directory (Extended) ( ^%RDX ) Directory (Library) ( LIB^%RD ) EDT Edit ( ^%EDT ) First Line List ( ^%FL ) Restore ( ^%RR ) Save ( ^%RS ) Search ( ^%RSE ) Size ( ^%RSIZE ) Syntax Check ( ^%ERRCHK ) TPU Edit ( ^%TPU ) VMS Information Utilities Device ( ^%GETDVI ) File ( ^%GETFILE ) General ( VMS^%STAT ) Message ( ^%GETMSG ) Process ( ^%GETJPI ) System ( ^%GETSYI ) Extrinsic Functions DSM Process Information Function DSM Job Table Information Function DSM Command Line Qualifier Options Information Function 8 Introduction to Input/Output Processing Overview Accessing Devices and Files I/O Command Syntax I/O Device Specifiers Device or File Type Recognition Principal I/O Device I/O Commands I/O Special Variables 9 Input/Output Processing for Terminals Setting Terminal Characteristics Terminal Commands OPEN Command USE Command Screen Management Facility and Foreign Terminal Support CLOSE Command READ Command READ * Command WRITE Command WRITE * Command Optimizing Terminal Output Recognition of Ctrl/c and Ctrl/y Escape-Sequence Processing $ZB Special Variable in Escape-Sequence Processing VT200 and VT300 Function Key Support Terminal Status and Error Conditions Local Area Transport Support for Terminals Logging In to a VMS System Using LAT Server and Port Names Printers and Host-Initiated Connections Modifying LAT Terminal Characteristics 10 Input/Output for DSM Magnetic Tape Magnetic Tape Commands OPEN Command USE Command CLOSE Command WRITE and ZPRINT Commands WRITE * Command READ and ZLOAD Commands Magnetic Tape Operations VIEW Buffer Mode Tape Labels and Multiple File Structures Data Formats Magnetic Tape Error Conditions Modifying the ASCII/EBCDIC Conversion Tables VAX DSM Utility Support for DSM Magnetic Tape 11 Input/Output Processing for RMS Files, VMS Mailboxes, and Network Devices Using RMS Files File Organization File Access Methods Record I/O Block I/O Creating and Opening Files Positioning Files Overview of Writing and Reading Records File Sharing Sequential Files on Disk Sequential File Commands OPEN Command for Sequential Files USE Command for Sequential Files CLOSE Command for Sequential Files READ Command for Sequential Files READ * Command for Sequential Files WRITE Command for Sequential Files WRITE * Command for Sequential Files ZPRINT Command for Sequential Files ZLOAD Command for Sequential Files Sequential File Status and Error Conditions Sequential Files on Magnetic Tape RMS Magnetic Tape Operations RMS Magnetic Tape Access Modes Accessing File-Structured Tapes Accessing Non-File-Structured Tapes RMS Magnetic Tape Status and Error Conditions RMS Magnetic Tape Commands OPEN Command for RMS Magnetic Tape USE Command for RMS Magnetic Tape CLOSE Command for RMS Magnetic Tape READ and WRITE Commands for RMS Magnetic Tape Indexed Files Indexed File Commands OPEN Command for Indexed Files USE Command for Indexed Files CLOSE Command for Indexed Files READ Command for Indexed Files WRITE Command for Indexed Files Record Locking for Indexed Files Indexed File Status and Error Conditions Relative Files Relative File Commands OPEN Command for Relative Files USE Command for Relative Files CLOSE Command for Relative Files READ Command for Relative Files WRITE Command for Relative Files Relative File Record Locking Relative File Status and Error Conditions Using Mailboxes Creating Mailboxes Mailbox Logical Names Mailbox Commands OPEN Command for Mailboxes OPEN Command Timeout USE Command for Mailboxes CLOSE Command for Mailboxes READ Command for Mailboxes WRITE Command for Mailboxes Mailbox Status and Error Conditions Communicating with Remote Computers Using DECnet Software Limitations on Operations Across the Network Reading and Writing Files Across the Network DECnet Task-to-Task Communication Across the Network Defining a DECnet Object Writing a Network Command Procedure Writing DSM Programs Using Mailboxes Across the Network TCP/IP Network Communication 12 VAX DSM Supplied $ZCALLs Overview ZCALL Directory Utility ( ^%CD ) VMS Related $ZCALLs VMS Services Mathematical Functions Text-Manipulation Functions File-Related Functions VAX DSM Functions Alphabetical Listing of Supplied $ZCALLs %ARCCOS %ARCSIN %ARCTAN %ASCEBC %ATTACH %BASEDIT %CDATASC %CDATNUM %COS %CRC %CRELOG %CTIMASC %CTIMNUM %CURRENCY %CVMSHOR %DAYS %DEJRNL %DELLOG %DELSYM %DES %DIGISEP %DIRECTORY %DISABLCTRL %DISMOUNT %EBCASC %EDT %ENABLCTRL %EXP %FDLCREATE %GETDVI %GETFILE %GETJPI %GETMSG %GETSYI %GETSYM %GETUAI %HIBER %LOG %LOG10 %LPC %LPLINES %MAX %MIN %MOUNT %OPCOM %PARSE %POWER %PRINT %RADIXPT %RTNSET %RTNTYPE %SECMAP %SECSHOW %SETPRI %SETPRN %SETSYM %SETUCI %SIN %SPAWN %SQRT %SUBMIT %SYSFAO %TAN %TPU %TRANSLATE %TRNLOG %UCI %UPCASE %UPCASEQ %VIEWASSIGN %VIEWBUFFER %VOLSET %WAKE Memory Management $ZCALLs Block Allocation/Deallocation $ZCALLs Block Writing $ZCALLs Block Reading $ZCALLs BLOCK INPUT Line Keyword 13 Writing ZCALLs to Invoke External Procedures Overview $ZCALL Development Process Creating the ZCALL Routine Table Argument List Argument-Passing Mechanisms Data Types for Argument Passing Format of the ZCALL Routine Table ROUTINE Line RETURN Line INPUT Lines OUTPUT Lines ZCALL Error Processing Creating the External ZCALL Procedure Writing an External ZCALL Procedure in VAX MACRO Returning String Output Arguments to VAX DSM Writing an External ZCALL Procedure in VAX FORTRAN Additional ZCALL Examples Building ZCALL Packages Creating and Linking the ZCALL Images Running DSM$ZCALL_EXAMPLE_BUILD.COM Debugging External ZCALL Procedures Recompiling Stored Routines Complete $ZCALL Example Calling Back to VAX DSM from External ZCALL Procedures A VAX DSM Error Messages Error Message Format Level 2 Errors Level 4 Errors Error Messages B Modifying the DSM Error Message File EXAMPLES 13-1 Running the DSM$ZCALL_EXAMPLE_BUILD Command Procedure FIGURES 6-1 Frames on a Call Stack 6-2 Error-Processing Routines 6-3 Flow of Error Processing with ZQUIT 9-1 Ethernet Network with a Single DECserver 10-1 Legal Format Switch Combinations 10-2 IBM Standard EBCDIC Label 10-3 Variable-Length Record Format 12-1 VIEW Buffer Window 13-1 ZCALL Images and Components 13-2 Argument-Passing Mechanisms for Procedures 13-3 DSM.EXE Calling DSM$SHARE.EXE 13-4 DSM$SHARE.EXE Being Activated TABLES 9-1 WRITE Format Control Characters 9-2 Function Key Codes 9-3 Auxiliary Key Codes 9-4 $ZA and $ZB Assignments for Terminal I/O 10-1 Magnetic Tape Format Switches 10-2 Magnetic Tape Control Codes Used with WRITE 10-3 Magnetic Tape Device $ZA Status Bit Assignments 11-1 VAX DSM Record Access Methods 11-2 WRITE Command Format Control Characters 11-3 $ZA and $ZB Assignments for Sequential File I/O 11-4 File-Sharing Options and RMS Access Privileges 11-5 $ZA and $ZB Assignments for Indexed File I/O 11-6 $ZA and $ZB Assignments for Relative File I/O 11-7 VMS Privileges for Creating Mailboxes 11-8 $ZA and $ZB Assignments for Mailbox I/O 12-1 Block Allocation and Deallocation Functions 12-2 Block Reading Functions 13-1 ROUTINE Line Keywords 13-2 RETURN Line Keywords 13-3 INPUT Line Keywords 13-4 OUTPUT Line Keywords