VAX APL User's Guide

This document is the VAX APL User's Guide, dated June 1991, for VAX APL Version 4.0 running on VMS Version 5.4. It serves as a comprehensive manual describing the VAX APL interpreter and its operating environment.

The guide is primarily intended for experienced APL programmers and covers a wide range of topics:

1. VAX APL Operating Environment: Details terminal support (APL and non-APL terminals, various character sets like ASCII, Composite, and Multinational), how to start and end an APL session (including initialization files, command-line qualifiers, and order of processing), APL's immediate and function-definition modes, keyboard editing, and the management of APL workspaces (types, naming conventions, passwords, size, and the state indicator).

2. VAX APL Language Concepts: Explains fundamental APL concepts such as array types (simple, enclosed, homogeneous, heterogeneous, numeric, character) and their structure (rank, shape, depth). It covers array manipulation functions like reshape and depth, the principles of scalar product and singleton extension, and the handling of empty arrays and fill items. It also describes APL expressions, identifiers (variables, labels, system functions), the use of wildcards, numeric and character constants, vector notation, evaluation rules (right-to-left, binding strength), and various methods of indexing arrays. Error handling, including error messages and custom error trapping, is also discussed.

3. User-Defined VAX APL Operations: Focuses on how to define, edit, and manage user-defined functions and operators. This includes structuring operations with headers and bodies, understanding local and global symbolic names, implementing branching (unconditional and conditional), adding comments, and locking operations. Debugging tools such as trace and stop vectors, suspending operations, and examining the state indicator are detailed.

4. The Report Formatter: Describes the ◊FMT system function used for combining and reformatting character and numeric data into a character matrix for report generation. It explains format phrases, their parameters (repetition, qualifiers, width, digits), and various qualifiers and decorators (e.g., blank when zero, insert commas, scale factor, zero fill, negative/positive/background decorators).

5. VAX APL Input and Output: Covers terminal input/output using quad functions (◊, ⎕, ⍞, ⍴), and extensive file input/output capabilities. This includes different file organizations (ASCII sequential, internal sequential, direct-access, relative, keyed) and access methods (sequential, random). It explains how to associate files with channels, query file assignments, and the concept of "pure data records" and data type conversion for interoperability with other languages. Advanced I/O techniques like file sharing, event flags, and mailboxes are also presented.

6. Calling External Routines: Explains how to integrate and call routines written in other languages (e.g., FORTRAN, C) and VMS system services from within APL. This involves linking external routines into VMS shared images, mapping them into the APL environment, defining data type characteristics for parameter passing, and debugging external calls. Numerous examples are provided for calling routines like RTL MTH$DACOSD, LIB$ERASE_PAGE, VMS SORT, VAX FORTRAN, VAX DATATRIEVE, and SMG$ Routines.

The document also includes an Appendix on the VAX APL Workspace Interchange Standard (WSIS), detailing how to convert workspaces to and from a standard format for transfer between APL implementations, along with associated error messages and warnings.

Overall, this guide serves as a comprehensive technical reference for APL programmers to understand, develop, and manage applications within the VAX/VMS environment, emphasizing language features, system interaction, and interoperability.