home *** CD-ROM | disk | FTP | other *** search
-
- ΓòÉΓòÉΓòÉ 1. Organization of this document ΓòÉΓòÉΓòÉ
-
- o Organization of this document
- o Notices
- o About This Book
- o Part 1. Getting Started
- o Overview
- o Installing and Customizing APL2/2
- o Invoking APL2/2
- o Part 2. Using APL2
- o General Information
- o Using the Session Manager
- o Editors
- o Using APL2 across Systems
- o Part 3. Application Guide
- o Associated Processors
- o Supplied External Routines
- o Supplied Workspaces
- o Supplied Auxiliary Processors
- o Part 4. Advanced Topics
- o Writing Your Own External Routines
- o Writing Your Own Auxiliary Processors
- o SVP Trace Facility
- o APL2/2 Presentation Manager Services
- o Appendixes
- o Implementation Limits
- o Deviations from APL2 Programming: Language Reference
- o APL2/2 Directory Structure
- o Bibliography
-
-
- ΓòÉΓòÉΓòÉ 2. Notices ΓòÉΓòÉΓòÉ
-
- References in this publication to IBM products, programs, or services do not
- imply that IBM intends to make these available in all countries in which IBM
- operates. Any reference to an IBM product, program, or service is not intended
- to state or imply that only IBM's product, program, or service may be used. Any
- functionally equivalent product, program, or service that does not infringe any
- of IBM's intellectual property rights may be used instead of the IBM product,
- program, or service. Evaluation and verification of operation in conjunction
- with other products, except those expressly designated by IBM, are the user's
- responsibility.
-
- IBM may have patents or pending patent applications covering subject material
- in this document. The furnishing of this document does not give you any license
- to these patents. You can send license inquiries, in writing, to the IBM
- Director of Commercial Relations, IBM Corporation, Purchase, NY 10577.
-
- o Programming Interface Information
- o Trademarks
-
-
- ΓòÉΓòÉΓòÉ 2.1. Programming Interface Information ΓòÉΓòÉΓòÉ
-
- This user's guide is intended to help programmers code APL2 applications in
- APL2/2. This book documents General-Use Programming Interface and Associated
- Guidance Information provided by APL2.
-
- General-use programming interfaces allow the customer to write programs that
- obtain the services of APL2.
-
-
- ΓòÉΓòÉΓòÉ 2.2. Trademarks ΓòÉΓòÉΓòÉ
-
- The following terms, denoted by an asterisk (*) in this publication, are
- trademarks of the IBM Corporation in the United States or other countries or
- both:
-
-
- AIX/6000 IBM
- APL2 Operating System/2
- APL2/6000 OS/2
- CUA Presentation Manager
- DATABASE 2 System/370
- DB2 System/390
-
- The following terms, denoted by a double asterisk (**) in this publication, are
- trademarks of other companies:
-
- PostScript Adobe Systems, Inc.
- Sun Sun Microsystems, Inc.
- Solaris Sun Microsystems, Inc.
-
-
- ΓòÉΓòÉΓòÉ 3. About This Book ΓòÉΓòÉΓòÉ
-
- This book describes IBM APL2 for OS/2 (APL2/2).
-
- This User's Guide is intended to help you use APL2/2. It contains a collection
- of tables and descriptions giving full details of installation, operation,
- supplied workspaces, and external interfaces.
-
- | CAUTION: Many parts of this document (including the |
- | "Conventions" section listed below) use APL characters. |
- | You must have the "APL2 Info" font installed before |
- | viewing those pages. The font is not installed |
- | automatically. If you have not yet installed it, |
- | please see the installation instructions. (If you are |
- | not sure, you could try looking at the "Conventions" |
- | section now. If the window disappears and you see a |
- | system error message, you will know why. Don't worry, |
- | no permanent damage will have occurred.) |
- | |
- | By the way, there are no APL characters in the |
- | installation section. (We wouldn't do that to you!) |
-
- o APL2 Publications
- o Conventions Used in This Book
-
-
- ΓòÉΓòÉΓòÉ 3.1. APL2 Publications ΓòÉΓòÉΓòÉ
-
- APL2 Publications lists the books in the APL2 library. This table shows the
- books and how they can help you with specific tasks.
-
- For the titles and order numbers of other related publications, see the
- Bibliography.
-
-
- ΓòÉΓòÉΓòÉ 3.1.1. APL2 Publications - Part 1 ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Type of Information and Titles
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Publication Number
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- General product
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- APL2 Fact Sheet
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- GH21-1090
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- Warranty
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- APL2/370 Application Environment Licensed Program Specifications
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- GH21-1063
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- APL2/370 Licensed Program Specifications
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- GH21-1070
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- APL2 for AIX/6000 Licensed Program Specifications
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- GC23-3054
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- APL2 for OS/2 Licensed Program Specifications
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- GC26-3358
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- APL2 for Sun Solaris Licensed Program Specifications
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- GC26-3359
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- Introductory language material
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- APL2 Programming: An Introduction to APL2
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- SH21-1073
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- MORE...
-
-
- ΓòÉΓòÉΓòÉ 3.1.2. APL2 Publications - Part 2 ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Type of Information and Titles
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Publication Number
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- Common reference material
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- APL2 Programming: Language Reference
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- SH21-1061
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- APL2 Reference Summary
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- SX26-3999
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- System interface
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- APL2/370 Programming: System Services Reference
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- SH21-1056
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- APL2/370 Programming: Using the Supplied Routines
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- SH21-1054
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- APL2/370 Programming: Processor Interface Reference
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- SH21-1058
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- APL2 for OS/2: User's Guide
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- SH21-1091
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- APL2 for Sun Solaris: User's Guide
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- SH21-1092
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- APL2 for AIX/6000: User's Guide
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- SC23-3051
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- APL2 GRAPHPAK: User's Guide and Reference
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- SH21-1074
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- APL2 Programming: Using Structured Query Language
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- SH21-1057
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- MORE...
-
-
- ΓòÉΓòÉΓòÉ 3.1.3. APL2 Publications - Part 3 ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Type of Information and Titles
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Publication Number
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- APL2 Migration Guide
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- SH21-1069
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- Mainframe system programming
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- APL2/370 Installation and Customization under CMS
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- SH21-1062
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- APL2/370 Installation and Customization under TSO
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- SH21-1055
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- APL2/370 Messages and Codes
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- SH21-1059
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- APL2/370 Diagnosis Guide
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- LY27-9601
-
-
- ΓòÉΓòÉΓòÉ 3.2. Conventions Used in This Book ΓòÉΓòÉΓòÉ
-
- The notations used in this user's guide and their meanings are:
-
- lower Lowercase italicized words in syntax represent values you must
- provide.
-
- UPPER In syntax blocks, uppercase words in an APL character set represent
- keywords that you must enter exactly as shown.
-
- [] Usually, brackets are used to delimit optional portions of syntax;
- however, where APL2 function editor commands or fragments of code
- are shown, brackets are part of the syntax.
-
- [AΓöéBΓöéC] A list of options separated by Γöé and enclosed in brackets indicates
- that you can select one of the listed options. Here, for example,
- you could specify either A, B, C, or none of the options.
-
- {AΓöéBΓöéC} Braces enclose a list of options (separated by Γöé), one of which you
- must select. Here, for example, you would specify either A, B, or
- C.
-
- ... An ellipsis indicates that the preceding syntactic item can be
- repeated.
-
- {}... An ellipsis following syntax that is enclosed in braces indicates
- that the enclosed syntactic item can be repeated.
-
- Γò£Γòò Used to mean "is equivalent to." It does not denote an APL2
- operation.
- The following APL2 names are used throughout this user's guide:
-
- Z Result name
- F Function name
- L Left argument name
- R Right argument name
- MOP Monadic operator name
- DOP Dyadic operator name
- LO Left operand name
- RO Right operand name
-
- The term workstation refers to all platforms where APL2 is implemented except
- those based on System/370* and System/390* architecture.
-
- Throughout this book, the following product names apply: See Product names.
-
-
- ΓòÉΓòÉΓòÉ 3.2.1. Product names ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Product Name
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Platform
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- APL2/2
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- OS/2
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- APL2 for Sun** Solaris**
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Sun Solaris
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- APL2/6000*
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- AIX/6000*
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- APL2/370
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- MVS or VM
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- APL2/PC
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- DOS
-
-
- ΓòÉΓòÉΓòÉ 4. Overview ΓòÉΓòÉΓòÉ
-
- This chapter contains an overview of APL2, including:
-
- o Why Should You Learn APL2?
- o What is IBM APL2/2?
- o Required Hardware
- o Required Software
-
-
- ΓòÉΓòÉΓòÉ 4.1. Why Should You Learn APL2? ΓòÉΓòÉΓòÉ
-
- Learning a programming language requires an investment of your most precious
- resources-time and effort. Why should you invest your time in APL2 in
- preference to any of the others? There are programming languages you can learn
- faster than APL2. But a tool is worth what you invest in it. Roman numerals
- were easier to use than Arabic numerals for most computations of Roman times.
- They were, however, impossible to extend for use in more sophisticated
- mathematics. Arabic numerals are harder to learn but are clearly a superior
- notation for mathematics.
-
- On the surface, some other programming languages are easier to learn because
- APL2 contains so much advanced function. However, you do not need to learn all
- of APL2 in order to use it effectively. You can learn a subset of APL2 first,
- leaving more advanced function for later.
-
- APL2 is extremely concise. A significant computation can fit in one page of
- code or even a few lines. One reason APL2 programs are so compact is that
- operations are represented by symbols, not English words. This has the
- advantage of being international, but may look intimidating. If you have paged
- through this manual, you have probably noticed that some of the symbols used
- come from the Greek alphabet. This leads some to say that APL2 looks like
- Greek. Just remember that Greek looks like Greek yet there are children who can
- read and write it fluently. It is a question not of difficulty, but of
- familiarity. Just as you can read the symbols used for international road signs
- once you know what they mean, you quickly become comfortable with APL2 symbols
- and appreciate the conciseness of the notation. Think of APL2 as the
- international road signs of programming.
-
-
- ΓòÉΓòÉΓòÉ 4.2. What is IBM APL2/2? ΓòÉΓòÉΓòÉ
-
- APL is a general-purpose language that enjoys wide use in such diverse
- applications as commercial data processing, system design, mathematical and
- scientific computation, and the teaching of mathematics and other subjects. It
- has proved particularly useful in database applications, where its
- computational power, user-friendliness, and communication facilities combine to
- increase the productivity of both application programmers and end users.
-
- When implemented as a computing system, the user types statements that specify
- the work to be done, and the computer responds by displaying the result of the
- work at a device such as a video display or a printer. In addition to work
- purely at the keyboard and its associated display, entries can also specify the
- use of printers, disk files, or other remote devices.
-
- A programming language should be relevant. That is, you should have to write
- only what is logically necessary to specify the job you want done. This may
- seem an obvious point, but many of the earlier programming languages forced you
- to be concerned as much with the internal requirements of the machine as with
- your own statement of the problem. APL takes care of these internal
- considerations automatically.
-
- A programming language needs both power and simplicity. By power, we mean the
- ability to handle large or complicated tasks. By simplicity, we mean the
- ability to state what must be done briefly and neatly, in a way that is easy to
- read and easy to write. You might think that power and simplicity are competing
- requirements, so that if you have one, you can not have the other, but that is
- not necessarily so. Simplicity means not that the computer is limited to doing
- simple tasks, but that the user has a simple way to write instructions to the
- computer. The power of APL as a programming language comes in part from its
- simplicity.
-
- The letters "APL" originated with the initials of a book written by K. E.
- Iverson, A Programming Language (New York: Wiley, 1962). Dr. Iverson first
- worked on the language at Harvard University, and then continued its
- development at IBM with the collaboration of Adin Falkoff and others at the IBM
- T. J. Watson Research Center. The term APL now refers to the language that is
- an outgrowth of that work. APL is the language, and APL2 is the brand name of
- IBM's extended version of APL. IBM APL2 for OS/2 is the name of a particular
- implementation of the APL2 language. This implementation, hereafter called
- APL2/2, has the following features:
-
- o APL2/2 is highly compatible with the other members of the APL2 family. It
- uses the same APL2 Programming: Language Reference. APL2 allows the
- transporting of workspaces, in transfer file format, between APL2 platforms.
- EBCDIC-ASCII translation is performed automatically where required, and is
- transparent to the user.
-
- o The APL2/2 session manager is common user access (CUA*) conforming and has a
- similar look and feel to the session managers of the other products in the
- APL2 family, with the added benefit of Presentation Manager* features such as
- window movement, window resizing, scroll bars, font specification, and the
- use of icons. It provides scrolling capability, permanent session logs,
- stacked input, color control, function key support, keyboard redefinition,
- and national language support.
-
- o APL2/2 provides many of the auxiliary processors available with the APL2/370
- or other workstation products:
-
- - AP 100 (host system command processor)
- - AP 101 (alternative input (stack) processor)
- - AP 119 (socket interface processor)
- - AP 124 (text display processor)
- - AP 127 (SQL relational database processor for DB2*)
- - AP 207 (universal graphics processor)
- - AP 210 (file I/O processor)
- - AP 211 (APL2 common object library processor)
-
- o APL2/2 also includes AP 145, which provides a programmable interface to the
- OS/2 services.
-
- o APL2/2 provides many of the common distributed workspaces and functions that
- are currently available on the System/370 or workstation products.
-
- o APL2/2 provides national language support. It provides external command and
- message translation tables that can be modified to support other countries,
- or individual user preferences.
-
-
- ΓòÉΓòÉΓòÉ 4.3. Required Hardware ΓòÉΓòÉΓòÉ
-
- The following hardware is the minimum required for APL2/2:
-
- o A personal computer running OS/2 Version 2.0 or higher.
-
- Note: For more information on the OS/2 machine requirements, refer to IBM
- OS/2 Information and Planning Guide.
-
- o At least 8 MB of hard disk space above that required by OS/2.
-
- o At least 2 MB of memory above that required by OS/2.
-
- All displays and printers supported by OS/2 are supported for APL2/2.
-
-
- ΓòÉΓòÉΓòÉ 4.4. Required Software ΓòÉΓòÉΓòÉ
-
- The following software is the minimum required to run APL2/2:
-
- o OS/2 Version 2.0 or later
-
- APL2/2 runs under OS/2 2.0 or any later release of OS/2. However, OS/2 2.0
- has some deficiencies that impose restrictions on APL2. This section lists
- the known problems for running APL2 on OS/2 2.0.
-
- - The PostScript** print driver in the base level of OS/2 2.0 builds
- unusable print job files when APL fonts are used. In order to overcome
- this problem, select the Printer Specific option in the Queue Options for
- the printer. Selecting the Printer Specific option produces print job
- files that print properly, but they are very large and are very slow to
- produce since the print driver generates code to draw each character
- rather than downloading the APL font.
-
- - The 16-bit Graphics Engine provided with the base level OS/2 2.0 is quite
- slow when PostScript fonts are used on display devices. The performance on
- some machines may be unacceptable.
-
- - The OS/2 facility used to save and restore the position and size of the
- SVP Trace window does not work reliably on some levels of OS/2 2.0.
-
- - The font used for AP 124 might not display the entire APL character set
- when using the base level of OS/2 2.0.
-
- o DB2/2 1.0 or later for AP 127
- o TCP/IP 2.0 or later for AP 119
- o IBM Developer's Toolkit for OS/2 for using PMTOOL's dialog-building functions
-
-
- ΓòÉΓòÉΓòÉ 5. Installing and Customizing APL2/2 ΓòÉΓòÉΓòÉ
-
- This chapter contains information about the installation of APL2/2.
-
- o The APL2/2 Package
- o Installation Overview
- o Installing APL2/2 on Your Workstation
- o APL2 Keyboard Support
- o Customizing APL2/2
-
-
- ΓòÉΓòÉΓòÉ 5.1. The APL2/2 Package ΓòÉΓòÉΓòÉ
-
- The APL2/2 program is supplied on 3╨╗-inch diskettes. It must be loaded onto the
- hard disk of a machine capable of running OS/2 Version 2.0 or later. Read this
- entire chapter before proceeding with the installation of APL2/2.
-
-
- ΓòÉΓòÉΓòÉ 5.2. Installation Overview ΓòÉΓòÉΓòÉ
-
- APL2 for OS/2 uses the IBM Software Installer for installation. Installation is
- supported from either diskette or a Local Area Network (LAN) server.
- Context-sensitive help is available at all times during the install process.
-
-
- ΓòÉΓòÉΓòÉ 5.3. Installing APL2/2 on Your Workstation ΓòÉΓòÉΓòÉ
-
- This section contains information that you need for:
-
- o Installing APL2/2 from a Diskette Drive
- o Setting Up and Installing from a LAN Server
- o Installing the APL2 Fonts
- o Accessing the Online Documentation
- o Changing CONFIG.SYS
- o Binding the APL2 to DB2 Interface
-
-
- ΓòÉΓòÉΓòÉ 5.3.1. Installing APL2/2 from a Diskette Drive ΓòÉΓòÉΓòÉ
-
- To install APL2/2 from a diskette drive:
-
- 1. Insert disk #1 into a diskette drive (in this example drive A is used).
-
- 2. Type the following on the OS/2 command line:
-
- A:\INSTALL
-
- 3. Press Enter.
-
- 4. Follow the on-screen prompts.
-
-
- ΓòÉΓòÉΓòÉ 5.3.2. Setting Up and Installing from a LAN Server ΓòÉΓòÉΓòÉ
-
- If you have purchased multiple licenses of APL2/2, you might want to consider
- placing it on a LAN server for easier access. To do this, perform the following
- steps:
-
- 1. Create a directory on the LAN server to store the APL2/2 files. For
- example:
-
- mkdir j:\apl2inst
-
- 2. Copy each APL2/2 diskette into this directory. You can do this using the
- OS/2 xcopy command. For example:
-
- xcopy a: j:\apl2inst /s
-
- 3. Repeat step 2 for each diskette.
-
- 4. Give all licensed users access to the LAN drive you copied the diskettes to
- (in this example, the J drive).
-
- After performing these steps, users with access to the LAN drive can access
- the alias drive\directory and install APL2/2 by typing:
-
- INSTALL
-
- Your LAN users are now ready to use APL2/2.
-
-
- ΓòÉΓòÉΓòÉ 5.3.3. Installing the APL2 Fonts ΓòÉΓòÉΓòÉ
-
- The installation tool does not install the APL2 fonts. You must install these
- yourself.
-
- The font files reside in the FONTS subdirectory of the directory into which you
- installed the product. The files are called:
-
- o APL2INFO.FON
- o COURAPL.AFM
- o COURAPLB.AFM
- o APL2ITAL.AFM
- o APL2NORM.AFM
- o COURAPL.PFB
- o COURAPLB.PFB
- o APL2ITAL.PFB
- o APL2NORM.PFB
-
- APL2INFO.FON is a bitmap font used for the online documentation. The
- APL2xxxx.AFM files are PostScript Type 1 fonts and are used by the session
- manager, editor, and print services. The APL2xxxx.PFB files are part of the
- PostScript fonts; you do not install them separately.
-
- The installation procedure is as follows:
-
- 1. Open the Font Palette that is found in the System Setup folder inside the
- OS/2 System folder.
- 2. Select Edit font...
- 3. Select Add.
- 4. Enter the path where the font can be found, that is, C:\APL2OS2\FONTS
- 5. Select Add....
- 6. The Add New Font dialog appears, with the .FON and .AFM files listed. Of
- the fonts you see, select all except AP124FNT.FON.
- 7. The directory to copy the font files to should default to the correct
- directory. Do not change it.
- 8. Select Add.
- 9. Exit the font palette Edit Font dialog. The fonts are not available until
- you have exited.
-
- Note: Under OS/2 2.0 you may need to install the fonts one at a time. Simply
- repeat the Add New Font portion of the procedure for each file.
-
-
- ΓòÉΓòÉΓòÉ 5.3.4. Accessing the Online Documentation ΓòÉΓòÉΓòÉ
-
- When you install APL2/2, the online documentation is automatically installed in
- the HELP subdirectory of the main installation directory. See the read.me file
- for a complete list of the documentation provided. You can access this
- information from either the Desktop or from the OS/2 command line.
-
- To access the information from the Desktop, double-click on the APL2/2 folder
- to open it, and then double-click on a document object.
-
- Note: The APL2INFO.FON font must be installed before viewing the online
- documents or you cannot display APL characters.
-
-
- ΓòÉΓòÉΓòÉ 5.3.5. Changing CONFIG.SYS ΓòÉΓòÉΓòÉ
-
- If you choose not to have the install program modify your CONFIG.SYS file, you
- need to make the following changes for APL2/2 to run correctly. The examples
- assume a top-level directory of C:\APL2OS2.
-
- 1. Add the following directory to your LIBPATH: C:\APL2OS2\DLL
- 2. Add the following directory to your PATH: C:\APL2OS2\BIN
- 3. Add the following directory to your DPATH: C:\APL2OS2\FONTS
- 4. Add the following directory to your HELP: C:\APL2OS2\HELP
- 5. Add the following directory to your BOOKSHELF: C:\APL2OS2\HELP
-
-
- ΓòÉΓòÉΓòÉ 5.3.6. Binding the APL2 to DB2 Interface ΓòÉΓòÉΓòÉ
-
- If APL2 is to be used to communicate with DB2, the APL2 packages must be bound
- to DB2.
-
- A command file, apldb2.cmd, is provided to do the bind processing. It requires
- that DB2 be started, and that the three APL2 bind files (apldb2cs.bnd,
- apldb2rr.bnd, and apldb2ur.bnd) be in the current directory. apldb2.cmd and the
- bind files are placed in the APL2 \bin directory during the APL2 install.
-
- apldb2.cmd must be run once for each DB2 database that is accessed by APL2. The
- database name is passed as the argument to apldb2.cmd. Note that it is assumed
- that the DB2 file sqlbind.exe is in the user's current path. If this is not the
- case, the command file can be modified to add path information to the bind
- commands.
-
-
- ΓòÉΓòÉΓòÉ 5.4. APL2 Keyboard Support ΓòÉΓòÉΓòÉ
-
- This section describes the keyboard support provided for APL2/2. For more
- information about how to customize your keyboard, see Using the Session
- Manager.
-
- o APL2/2 Keyboard Layouts
- o Keyboard Keycaps
- o Keyboard Decals
-
-
- ΓòÉΓòÉΓòÉ 5.4.1. APL2/2 Keyboard Layouts ΓòÉΓòÉΓòÉ
-
- Several standard APL2 keyboard layouts are provided with this product. You can
- choose one of these or design your own. The keyboard layout can be changed
- during your APL2 session, and is retained across sessions.
-
- To select a keyboard layout, choose "Select Keyboard" from the session manager
- "Options" menu. Both standard (APL on/off) and union keyboard layouts are
- available, and the defaults are dynamically reconfigured based on your keyboard
- and OS/2 country and code page settings.
-
- To see the key assignments, or to modify them, choose "Modify Keyboard" from
- the session manager "Options" menu. The layout displayed by default is your
- currently selected one, but all others are available in the "Layout name"
- drop-down combo box.
-
- Union keyboard layouts provide standard ASCII characters in the unshifted and
- Shift keyboard states, and special APL characters on the Ctrl and Alt shifts.
- This permits intermixed keying of APL and non-APL characters.
-
- Traditional APL keyboards include an APL on/off key which switches the keyboard
- between an APL mode and an ASCII mode. In APL mode, ASCII characters are
- available only if they are also used by APL, and they appear (by default) on
- the keys traditionally used by APL keyboards, which are usually different from
- the normal OS/2 assignments.
-
- APL2/2 uses Ctrl-Backspace as the APL on/off key. Ctrl-Backspace still switches
- APL on or off when using a union keyboard, but that basically indicates only
- whether all characters, or only the non-APL subset, should be accepted from the
- keyboard. European users should note, however, that in all layouts "dead" keys
- are disabled when the keyboard is in APL mode.
-
- For reference information on the positions of characters in the APL2 character
- set, see APL2 Programming: Language Reference. For full details of keyboard
- layouts and key assignments, see the "Modify Keyboard" dialog accessible via
- "Options" from the session manager window.
-
- See APL2/2 Presentation Manager Services for more information about APL2/2's
- keyboard handler.
-
-
- ΓòÉΓòÉΓòÉ 5.4.2. Keyboard Keycaps ΓòÉΓòÉΓòÉ
-
- You can order sets of plastic replacement keycaps that correspond to the
- APL2/PC version of your keyboard layout. The keycaps work on 101- and
- 102-version keyboards. The keycaps are: See Keycap ordering information.
-
- The base set, part number 1395624, is needed to complete each of the upgrade
- sets; part numbers 1397152, 1397153, and 1397154 are supplemental to the US/UK
- base set.
-
-
- ΓòÉΓòÉΓòÉ 5.4.2.1. Keycap ordering information ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Item
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Form Number
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Part Number
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- APL2 Keycaps, US/UK base set
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- SX80-0270
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 1395624
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- APL2 Keycaps, German upgrade
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- SX23-0452
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 1397152
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- APL2 Keycaps, French upgrade
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- SX23-0453
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 1397153
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- APL2 Keycaps, Italian upgrade
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- SX23-0454
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 1397154
-
-
- ΓòÉΓòÉΓòÉ 5.4.3. Keyboard Decals ΓòÉΓòÉΓòÉ
-
- Decals with the APL2 character set for IBM keyboards are included with this
- product. Carefully peel each decal away from the backing sheet and place it on
- the appropriate key. Note that some decals (those for Alternate-shift
- characters) go on the fronts of the keys, and that not all the decals are
- needed for some keyboards. For a French keyboard layout, which has the numeric
- keys in the shifted position, you need to cut the decals for these keys to move
- the APL2 characters to the lowercase position.
-
- Note: Additional sets of decal sheets can be ordered from IBM as APL2 Keyboard
- Decals, SC33-0604.
-
-
- ΓòÉΓòÉΓòÉ 5.5. Customizing APL2/2 ΓòÉΓòÉΓòÉ
-
- This section describes how you can customize your APL2 session during
- installation.
-
- o APL2.CMD
- o The APL2/2 SVP Parameter File
- o The SVP Profile
- o Modifying the APL2/2 Desktop Object
- o APL2/2 and TCP/IP
-
-
- ΓòÉΓòÉΓòÉ 5.5.1. APL2.CMD ΓòÉΓòÉΓòÉ
-
- The installation program for APL2/2 builds a REXX command file. Assuming a
- default install directory of C:\APL2OS2, the following is an example of what
- the file contains with a description added for each line: See REXX command
- file.
-
- If you want to specify additional parameters on every invocation of APL2/2,
- they can be added to this file in the following ways:
-
- o The environment variable that represents the parameter can be set in this
- file. For example, to specify an initial workspace size of 10M, add the
- following line:
-
- 'SET APLWS=10M'
-
- o The parameter can be added to the line that invokes APL2/2. Using the example
- of workspace size mentioned above, modify the line as follows:
-
- 'aosapl2.exe -ws 10m' parms
-
- Be sure to retain the REXX variable parms at the end of the line to allow any
- extra parameters to be specified on the command line (see also Modifying the
- APL2/2 Desktop Object).
-
- Note: If you have chosen not to install the REXX component of OS/2, you need
- to convert this file to standard OS/2 batch language syntax.
-
-
- ΓòÉΓòÉΓòÉ 5.5.1.1. REXX command file ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- /* APL2 Invocation command file */
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Identifies this as REXX
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- '@echo off'
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Suppresses echoing of lines
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- arg parms
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Captures command line arguments
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 'SET APL00001=C:\APL2OS2\WSLIB1'
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Sets up public workspace library 1
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 'SET APL00002=C:\APL2OS2\WSLIB2'
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Sets up public workspace library 2
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 'SET APL01001=.\'
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Sets default private library
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 'SET APLP11=C:\APL2OS2\BIN\APLNM011.NAM'
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Sets default processor 11 NAMES file
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 'aosapl2.exe 'parms
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Invokes APL2/2 with any args
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- exit
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ 5.5.2. The APL2/2 SVP Parameter File ΓòÉΓòÉΓòÉ
-
- The APL2/2 Shared Variable Processor (SVP) uses a parameter file to set some
- initialization options. The APL2SVPPARMS environment variable can be used to
- specify the name and, optionally, the location of this file. If this
- environment variable is not set, the default file name is apl2svp.prm. This
- file is searched for in the following sequence:
-
- 1. In the path supplied along with the file name in the APL2SVPPARMS
- environment variable.
-
- 2. In the current directory used by the SVP. This is either the directory from
- which APL2/2 was invoked, or the directory from which the SVP Trace window
- or any independent processor was invoked, whichever was started first.
-
- 3. In the list of directories specified in the DPATH environment variable.
-
- The file uses the following syntax:
-
- keyword=value [value...]
-
- Blank lines or lines with an asterisk in the first column are ignored. In the
- case of keywords that accept more than one value, the values can be separated
- by a comma, by spaces, or by both.
-
- The keywords that can be specified are:
-
- PROCS Specifies the maximum number of processors that can be signed on to
- the SVP at one time.
-
- VARS Specifies the maximum number of variables that can be shared at one
- time.
-
- MAXSM Specifies the maximum amount of memory, in bytes, that can be used
- for shared variable data.
-
- MAXSV Specifies the maximum amount of memory, in bytes, that can be used
- for any single shared variable.
-
- NOTRACE Specifies a list of processor IDs that are not traced by the SVP
- trace facility. An asterisk may be specified to signify that all
- processors are not traced.
-
- The default file apl2svp.prm is provided as follows:
-
- * Sample svp parms file
- PROCS=100
- VARS=100
- MAXSM=10000000
- MAXSV=1000000
- NOTRACE=1 101 120
- *
-
- Notes:
-
- 1. Although there is no enforced maximum allowed value for MAXSM, this can be
- limited by the size of memory or the OS/2 swapper space available.
-
- 2. If the SVP parms file is not found, defaults for PROCS, VARS, MAXSM, and
- MAXSV are set as noted in the sample file above and all processors are
- traced.
-
-
- ΓòÉΓòÉΓòÉ 5.5.3. The SVP Profile ΓòÉΓòÉΓòÉ
-
- For information about customizing the SVP profile, see Processor Profile
- Structure.
-
-
- ΓòÉΓòÉΓòÉ 5.5.4. Modifying the APL2/2 Desktop Object ΓòÉΓòÉΓòÉ
-
- The install program creates a desktop object in the APL2 for OS/2 folder that
- can be used to invoke APL2/2. You might want to customize this object as
- follows:
-
- 1. Open the Settings notebook for the object by clicking mouse button 2 on the
- icon, then clicking mouse button 1 on the arrow next the word Open, then
- selecting Settings.
-
- 2. On the Program page of the Settings notebook, you might want to add APL2/2
- invocation parameters in the Parameters field. You can also specify "[ ]"
- if you want to be prompted for additional parameters.
-
- 3. On the Session page, you may want to click on the box labeled Start
- minimized if you want the APL2/2 interpreter window to be minimized on
- invocation.
-
- 4. On the Window page, you might want to click on the box labeled: Create new
- window under Object open behavior. This allows you to use the object to
- start multiple concurrent APL2/2 sessions.
-
-
- ΓòÉΓòÉΓòÉ 5.5.5. APL2/2 and TCP/IP ΓòÉΓòÉΓòÉ
-
- APL2/2 uses TCP/IP for OS/2 to provide cooperative processing facilities. The
- Shared Variable Processor (SVP) contains references to certain TCP/IP socket
- calls necessary for this function. The SVP routines are supplied in the form of
- a dynamic link library (DLL). Because this DLL has a load-time dependency on
- TCP/IP, two versions are shipped with APL2/2 and copied to the \dll
- subdirectory where APL2/2 was installed. The two versions are named
- apl2svpt.dll (TCP/IP enabled) and apl2svpn.dll (TCP/IP disabled). The install
- program tries to detect whether TCP/IP has been installed, and makes a copy of
- the appropriate version, which is then named apl2svp.dll. If for some reason
- the install program incorrectly detects the presence of TCP/IP, or if you later
- install or uninstall TCP/IP on your system, you might need to copy the
- appropriate SVP DLL file. For example, if you install TCP/IP after installing
- APL2/2, you could do the following:
-
- 1. Change directory to the \dll subdirectory where APL2/2 was installed:
-
- cd c:\apl2os2\dll
-
- 2. Issue the following OS/2 command:
-
- copy apl2svpt.dll apl2svp.dll
-
- This enables APL2/2 to use the cooperative processing features (see Cooperative
- Processing).
-
-
- ΓòÉΓòÉΓòÉ 6. Invoking APL2/2 ΓòÉΓòÉΓòÉ
-
- This chapter describes the APL2 environment created on your OS/2 desktop,
- techniques you can use to create that environment, options you can pass to the
- APL2 product, and environment variables that affect the way it behaves.
-
- An "APL2 for OS/2" folder was created on your desktop when you installed the
- product. When you open that folder, you find documentation and program icons.
- APL2 is normally started by opening the "APL2/2" program icon.
-
- o OS/2 Windows Opened by APL2
- o Invocation Syntax and Environment Variables
-
-
- ΓòÉΓòÉΓòÉ 6.1. OS/2 Windows Opened by APL2 ΓòÉΓòÉΓòÉ
-
- When APL2 is started, three windows are typically created, though this can be
- affected by the way that you start the product. The windows are included in the
- system Window List, and may or may not be displayed on the desktop:
-
- o An APL2 session manager window is normally displayed. See Using the Session
- Manager for details of its usage. This window is not created if the default
- -sm on invocation option is overridden.
-
- o The interpreter window is opened unless you have issued the APL2 command
- directly from another OS/2 command window. (In that case, the original
- command window has the behavior discussed here.) The interpreter window is
- normally used only to display output from OS/2 commands invoked through )HOST
- or AP 100. If APL2 is invoked with -sm off, but the input or output have not
- been redirected, then APL session input or output goes through this window.
- Certain severe error messages are also displayed here. Ctrl-Break can be used
- from this window to interrupt the interpreter. Closing the window terminates
- the APL2 session. (But normally signals and session termination are
- controlled from the session manager window.)
-
- o The SVP Trace window is opened if the SVP was not already active. This window
- can be used to monitor APL2 shared variable activity, to obtain information
- about processors and shared variables, initiate the programs used for
- cooperative processing, and to clean up after processors that may not have
- terminated normally. See the help provided within the window for details of
- its usage. For more information, see SVP Trace Facility.
-
- Both the interpreter window and the SVP Trace window are often minimized or
- hidden in normal usage. When APL2 is started from the APL2/2 folder, that
- folder restores the interpreter window to its last known state. The SVP trace
- window is always reopened in the state it was in when it was last closed.
-
- Additional windows can be opened by applications that are started automatically
- when APL2 is invoked.
-
-
- ΓòÉΓòÉΓòÉ 6.2. Invocation Syntax and Environment Variables ΓòÉΓòÉΓòÉ
-
- Most interpreter options can be specified as either operating system
- environment variables or parameters on the command that starts APL2.
-
- o Parameter keywords can be entered in uppercase, lowercase, or mixed case, and
- must be marked with a leading slash or hyphen, followed immediately by the
- keyword.
-
- o Environment variable names match the parameter keywords, but with a prefix of
- APL. Environment variables must be set before invoking APL2/2.
-
- Where parameters are specified they override the corresponding environment
- variables.
-
- Note: All APL2 invocation parameters and environment variables are also passed
- to any dependent auxiliary processors. Dependent auxiliary processors are
- auto-started as children of the APL2 interpreter session when the first share
- offer is made to the auxiliary processor. All command line parameters are
- passed unmodified to the auxiliary processor, with the exception of the -id
- parameter, the value of which is adjusted to identify the processor number of
- the auxiliary processor, followed by the processor number of the parent
- interpreter session.
-
- o Invocation Syntax
- o Environment Variables
- o System Dependent Environment Variables
- o Examples of APL2/2 Invocation
- o Running APL2/2 in Batch Mode
-
-
- ΓòÉΓòÉΓòÉ 6.2.1. Invocation Syntax ΓòÉΓòÉΓòÉ
-
- apl2 [optional parameters]
- where optional parameters are:
-
- Invocation
-
- Keyword Description
-
- -id procid[,parentid[,pparentid]]
- Sets user ID number, as reported by РAI and used when sharing
- variables with the session. Is also used to specify a parent and
- grandparent ID for APL sessions that are to be subordinate to others.
- -id can be set to 1 to 3 positive integers (separated by commas), but
- is normally a single integer.
-
- The use of IDs of 1000 or less is not advised unless the session is
- being used as an auxiliary processor. The default is the first unused
- number above 1000.
-
- -input " 'line1' ['line2']..."
- Defines the initial lines of input used when APL2 is invoked. Each
- line of input is enclosed in single quotation marks and the group of
- one or more lines of input is enclosed in double quotes.
-
- All displayable characters can be included within the quoted lines.
- Use two single quote marks for each one that is to be treated as part
- of the input.
-
- -lx {on|off}
- Indicates whether the latent expression, РLX, should be executed when
- a workspace is )LOADed.
-
- -nlt filename
- Specifies which national language to use for system commands and
- messages. Can be set to the character name of the file that contains
- the National Language messages. The default is en_us.nlt (US English).
- Other options are:
-
- en_uk.nlt (UK English)
- gr_gr.nlt (German)
- fr_fr.nlt (French)
- it_it.nlt (Italian)
-
- -quiet {on|off}
- Suppresses display of interpreter output until input is requested.
-
- Input requests satisfied by the APL2 input stack do not reset -quiet
- on. Data is placed on the APL2 input stack either by the -input option
- or through AP 101.
-
- -sm {on|off|piped|n}
- Indicates whether a session manager is to be used. If a number is
- specified, a variable is offered to the indicated processor. off would
- be used for line-by-line I/O devices, or programs which emulate that
- behavior, such as typing directly into an OS/2 window. piped is used
- for batch processing, whether the session is driven by a file or by
- another process.
-
- -svplisten {on|off}
- Enables automatic startup of the port server.
-
- -svptrace {on|off|log|both}
- Enables display and logging of SVP trace events.
-
- -ws initial[,maximum[,increment]]
- Workspace size. This can be either a single value for a static size,
- or up to three values to request an expandable workspace.
-
- Each of the values provided are of the form:
-
- integer[k|m]
-
- where k and m indicate kilobytes and megabytes, respectively.
-
- If increment, or both maximum and increment, are omitted, they default
- to initial. The default for initial is 2M. The system increases any
- initial value less than 32K.
-
- Here are some examples:
-
- -ws 5m
-
- The session is run with a 5 megabyte workspace. WS FULL is reported if
- this is not enough.
-
- -ws 2m,7m
-
- The session begins with a 2 megabyte workspace. Since the increment
- defaults to the initial value, this is expanded to 4 megabytes, 6
- megabytes, and finally 7 megabytes as needed to avoid WS FULL.
-
- -ws 500k,1m,100k
-
- The session begins with a 500 kilobyte workspace. This is expanded as
- needed, 100 kilobytes at a time, but never exceeding 1 megabyte.
-
- Note: The maximum size specified or defaulted should never exceed the
- available free space on the drive that contains SWAPPER.DAT.
-
-
- ΓòÉΓòÉΓòÉ 6.2.2. Environment Variables ΓòÉΓòÉΓòÉ
-
- Environment variables can be set prior to invoking APL2 to control certain
- aspects of the session. To set an environment variable, enter the following:
-
- SET variable=value
- Where variable is the name of the environment variable and Value is the
- assigned content. Environment variables under OS/2 are always folded to
- uppercase, but the values are case sensitive. Any auxiliary processors that are
- automatically started by the APL2/2 session inherit the environment variables
- set by the parent. SET commands can be issued from the OS/2 command line in the
- OS/2 session where APL2/2 is invoked. They can also be added to the apl2.cmd
- invocation file (see Customizing APL2/2).
-
- In addition to the variables listed here, the interpreter invocation options
- can be specified as environment variables. The variable names match the
- parameter keywords, but with a prefix of APL. Where parameters are specified,
- they override the corresponding environment variable.
-
- APL2SMKEY Name of the shared variable key. This value is used to build
- unique names for the resources used by the Shared Variable
- Processor. The default is apl2svp.
-
- APL2SVPLOG Name of the Shared Variable Processor trace file. This can be a
- simple file name or a fully qualified path and file name. The
- default is apl2svp.trc.
-
- APL2SVPPARMS Name of the file that contains the Shared Variable Processor
- initialization parameters. This can be a simple file name or a
- fully qualified path and file name. The default is apl2svp.prm.
-
- APL2SVPPRF Name of the SVP profile. This file contains entries that
- identify and authorize remote processors and independent local
- processors. This can be a simple file name or a fully qualified
- path and file name. The default is apl2svp.prf.
-
- APL207FL Path to the AP 207 vector font files.
-
- APLnnnnn Where nnnnn is a five-digit number such as 01234. Used to
- resolve library numbers with the system commands. A separate
- environment variable must be defined for each library accessed
- by number. Is set to a directory path specification.
-
- For more information, see Library Specification and the LIBS
- function in The OS2 Workspace.
-
- APLP11 Name of the default processor 11 NAMES file.
-
-
- ΓòÉΓòÉΓòÉ 6.2.3. System Dependent Environment Variables ΓòÉΓòÉΓòÉ
-
- The following list describes the operating system environment variables on
- which APL2 depends.
-
- DPATH Sequence of directories used to search for nonexecutable data
- files
-
- HOSTNAME TCP/IP hostname used for cooperative processing
-
- PATH Sequence of directories used to search for an executable file or
- command
-
- TZ Time zone in effect
-
-
- ΓòÉΓòÉΓòÉ 6.2.4. Examples of APL2/2 Invocation ΓòÉΓòÉΓòÉ
-
- The following sections provide examples of how to invoke APL2/2.
-
- o From the OS/2 Desktop, Using a Mouse
- o From the OS/2 Desktop, Using the Keyboard
- o From an OS/2 Window
- o To Drive an APL Application from the Desktop
-
-
- ΓòÉΓòÉΓòÉ 6.2.4.1. From the OS/2 Desktop, Using a Mouse ΓòÉΓòÉΓòÉ
-
- 1. Double-click mouse button 1 on the "APL2 for OS/2" icon on the desktop.
- This opens the APL2/2 folder.
-
- 2. Double-click mouse button 1 on the "APL2/2" icon within that folder.
- This starts an APL2 session using any previously assigned options. To change
- those options, single-click mouse button 2 on the "APL2/2" icon and select
- Settings.
-
-
- ΓòÉΓòÉΓòÉ 6.2.4.2. From the OS/2 Desktop, Using the Keyboard ΓòÉΓòÉΓòÉ
-
- 1. Alt+Shift+Tab followed by Ctrl+\ takes you to the desktop and deselects all
- objects.
-
- 2. Use the Arrow keys to move focus to the "APL2 for OS/2" icon, then the
- Enter key to open it.
-
- 3. Use the Arrow keys to move focus to the "APL2/2" program icon, then the
- Enter key to open it.
- This starts an APL2 session using any previously assigned options. To change
- those options, press Shift-F10 while the "APL2/2" icon has focus, then
- Right-arrow and Enter to open the Settings notebook.
-
-
- ΓòÉΓòÉΓòÉ 6.2.4.3. From an OS/2 Window ΓòÉΓòÉΓòÉ
-
- 1. Switch to the drive and directory that you want to use as the working
- directory during the APL2 session. Typically this is the directory where
- your private workspaces are stored. For example:
-
- [C:\]d:
- [D:\]cd wslib
- [D:\WSLIB]
-
- 2. Set any needed environment variables that are not already set (perhaps by
- CONFIG.SYS) and are not set automatically by the command file you are going
- to use. (You cannot change these after entering APL2.) The following
- example defines APL libraries 50 and 1002, pointing library 1002 to the
- current directory.
-
- [D:\WSLIB]set apl00050=e:\lib50
- [D:\WSLIB]set apl01002=.\
- [D:\WSLIB]
-
- 3. Start the APL2 session, providing any needed options. This example sets a
- workspace size of 5 megabytes and suppresses automatic execution of РLX
- expressions in workspaces that are loaded:
-
- [D:\WSLIB]apl2 /ws 5m /lx off
-
-
- ΓòÉΓòÉΓòÉ 6.2.4.4. To Drive an APL Application from the Desktop ΓòÉΓòÉΓòÉ
-
- The provider of the application can do the following:
-
- 1. Create a program icon. You can copy an existing one or drag the system's
- program template to another directory.
-
- 2. Fill in the full path and file name of the APL2 program. This is
- AOSAPL2.EXE in the \BIN subdirectory of the directory where the APL2
- product was installed.
-
- 3. Select a working directory based on any needs the application may have.
-
- 4. Provide optional parameters as needed. For example:
-
- -quiet on -sm off -ws 4m -input "')LOAD ''applic.APL'''"
-
- Note that the OS/2 filename form of the )LOAD command is used in the -input
- option. Using this form avoids any dependencies on environment variables.
- Drive and directory information can be included if the workspace is not
- stored in the working directory.
-
- Assuming that the workspace contains a latent expression, it begins executing
- automatically when the user opens the program object.
-
-
- ΓòÉΓòÉΓòÉ 6.2.5. Running APL2/2 in Batch Mode ΓòÉΓòÉΓòÉ
-
- Batch mode enables you to redirect APL2/2 session input and output. In this
- mode, input is redirected from text files containing what would normally be the
- keyboard input during an interactive session. The resulting output can then be
- redirected to another file or process. For example, suppose that the file
- session.in contains the following input lines:
-
- 2+2
- )OFF
-
- Suppose APL2 is invoked with this as redirected input, and the output is
- redirected to a file called session.out, using:
-
- apl2 -sm piped < session.input > session.output
-
- The session.out file then contains the session manager output:
-
- ...
- CLEAR WS
- 2+2
- 4
-
- If the input file ends before an )OFF or )CONTINUE command is encountered in
- the input file, the session is terminated with an )OFF command.
-
-
- ΓòÉΓòÉΓòÉ 7. General Information ΓòÉΓòÉΓòÉ
-
- This chapter discusses how to use APL2.
-
- o The APL2 Interpreter
- o An Example of the Use of APL2
- o Characteristics of APL2
- o Workspaces and Libraries
-
-
- ΓòÉΓòÉΓòÉ 7.1. The APL2 Interpreter ΓòÉΓòÉΓòÉ
-
- The APL2 interpreter takes one APL2 statement at a time, converts it to machine
- instructions (the computer's internal language), executes it, and then proceeds
- to the next line. In contrast to program compilers that convert an entire
- program to machine language before executing any statements, APL2 allows you a
- high degree of interaction with the computer. If something you enter is
- invalid, you get quick feedback on the problem before you go any further. This
- also yields high productivity gains.
-
-
- ΓòÉΓòÉΓòÉ 7.2. An Example of the Use of APL2 ΓòÉΓòÉΓòÉ
-
- A statement entered at the keyboard can contain numbers or symbols, such as + -
- ї Ў, or names formed from valid combinations of letters (as described in APL2
- Programming: Language Reference). The numbers and special symbols stand for the
- primitive objects and functions of APL2-primitive in the sense that their
- meanings are permanently fixed, and therefore understood by the APL2 system
- without further definition. A name, however, has no significance until a
- meaning has been assigned to it.
-
- Names are used for two major categories of objects. Names can be used for
- collections of data that are composed of numbers or characters; such a named
- collection is called a variable. Names can also be used for programs made up of
- sequences of APL2 statements; such programs are called defined functions and
- operators. Once they have been established, names of variables and defined
- operations can be used in statements by themselves or in conjunction with
- primitive functions and objects.
-
- o An Isolated Calculation
- o Storing Functions and Data
-
-
- ΓòÉΓòÉΓòÉ 7.2.1. An Isolated Calculation ΓòÉΓòÉΓòÉ
-
- If the work to be done can be adequately specified simply by typing a statement
- made up of numbers and symbols, names are not required; entering the expression
- to be evaluated causes the result to be displayed. For example, suppose you
- want to compare the rates of return on money at a fixed interest rate but with
- different compounding intervals. For 1000 units at 6% compounded annually,
- quarterly, monthly, or daily for 10 years, the entry and response for the
- transaction (assuming a printing precision (РPP) equal to 6) looks like this:
-
- РPP╜6
- 1000ї(1+0.06Ў1 4 12 365)*10ї1 4 12 365
- 1790.85 1814.02 1819.4 1822.03
-
- (The largest gain is apparently obtained in going from annual to quarterly
- compounding; after that the differences are relatively insignificant.)
-
- This example illustrates several characteristic features of APL2: familiar
- symbols such as + - ї Ў are used where possible; symbols are introduced where
- necessary (as the * for the power function); and a group of numbers can be
- worked on together.
-
-
- ΓòÉΓòÉΓòÉ 7.2.2. Storing Functions and Data ΓòÉΓòÉΓòÉ
-
- Although many problems can be solved by typing the appropriate numbers and
- symbols, the greatest benefits of using APL2 occur when named functions and
- data are used. Because a single name can refer to a large array of data, using
- the name is far simpler than typing all of its numbers. Similarly, a defined
- function, specified by entering its name, can be composed of many individual
- APL2 statements that would be burdensome to type again and again.
-
- Once a function has been defined, or data collected under a name, it is usually
- desirable to retain the significance of the names for some period of
- time-perhaps for just a few minutes, but more often for much longer, possibly
- months or years. For this reason APL2 systems are organized around the idea of
- a workspace, which might be thought of as a notebook in which all the data
- items needed during some piece of work are recorded together. An APL2 workspace
- thus contains defined functions, data structures, and a state indicator.
-
-
- ΓòÉΓòÉΓòÉ 7.3. Characteristics of APL2 ΓòÉΓòÉΓòÉ
-
- APL2 Programming: Language Reference describes APL2 in detail, giving the
- meaning of each symbol and discussing the various features of APL2. These
- details should be considered in light of the major characteristics of APL2,
- which can be summarized as follows:
-
- o The primitive objects of the language are arrays (lists, tables, lists of
- tables, and so on). For example, A + B is meaningful for any conformable
- arrays A and B, the size of an array (цA) is a primitive function, and arrays
- can be indexed by arrays, as in A[3 1 4 2].
-
- o The syntax is simple:
-
- - There are only three statement types: name assignment, branch, or
- neither).
- - There is no function precedence hierarchy.
- - Functions have either one, two, or no arguments.
- - Primitive functions and defined functions (programs) are treated alike.
-
- o The semantic rules are few:
-
- - The definitions of primitive functions are independent of the
- representations of data to which they apply.
- - All scalar functions are extended to other arrays in the same way-that is,
- item by item.
- - Primitive functions have no hidden effects (so-called side-effects).
-
- o The sequence control is simple: one statement type embraces all types of
- branches (conditional, unconditional, computed, and so on), and the
- completion of the execution of any function always returns control to the
- point of use.
-
- o External communications are established by means of variables, which are
- shared between an APL2 session and other processors. These processors can be
- APL or non-APL programs running on the same system or on another system.
- Shared variables are treated both syntactically and semantically like other
- variables. A subclass of shared variables-system variables-provides
- convenient communications between APL2 programs and their environment.
-
- o The usefulness of the primitive functions is vastly expanded by operators,
- which modify their behavior in a systematic manner. For example, the
- primitive operator, reduction (denoted by /) modifies a function to apply
- over all elements of a list, as in +/L for summation of the items of L. The
- remaining primitive operators are:
-
- - Scan (running totals, running maxima, and so on)
- - The axis operator, which, for example, makes it possible to apply
- reduction and scan over a specified axis (rows or columns) of a table
- - The each operator, which applies a function to each of the elements of its
- arguments
- - The outer product, which produces tables of values as in RATE┬░.*YEARS for
- an interest table
- - The inner product, a generalization of matrix product.
-
- o The number of primitive functions and operators is sufficiently small that
- each is represented by a single, easily-read and easily-written symbol, yet
- the set of primitives embraces operations from simple addition to grading
- (sorting) and formatting.
-
-
- ΓòÉΓòÉΓòÉ 7.4. Workspaces and Libraries ΓòÉΓòÉΓòÉ
-
- The common unit of storage in an APL2 system is the workspace. When in use, a
- workspace is said to be active, and is in main storage. Part of each workspace
- is set aside to serve the internal workings of the system; the rest is used, as
- required, to store items of information and to hold transient information
- generated during a computation.
-
- The names of variables (data items) and defined functions or operators
- (programs) used in calculations always refer to objects known by those names in
- the active workspace; information about the progress of program execution is
- maintained in the state indicator of the active workspace, and control
- information affecting the form of output is held within the active workspace.
-
- Inactive workspaces are stored in libraries (that are OS/2 directories), where
- they are identified by arbitrary names. The inactive workspaces are typically
- stored in WSNAME.apl. When required, copies of stored workspaces can be made
- active, or (if they are stored in an appropriate form) selected information can
- be copied from them into an active workspace.
-
- Transfer files provide a way to store and transport APL objects outside of
- workspaces. They are particularly useful when transferring workspace objects
- between different APL2 implementations, because all APL2 products can read
- transfer files created by any other APL2 product. Transfer files are also used
- as an alternative to inactive workspaces. Transfer files can have arbitrary
- names, but the form FILENAME.atf is typically used.
-
- Workspaces, libraries, and transfer files are managed by system commands, as
- described in APL2 Programming: Language Reference.
-
- o Library Specification
- o Explicit File Specifications
-
-
- ΓòÉΓòÉΓòÉ 7.4.1. Library Specification ΓòÉΓòÉΓòÉ
-
- APL2/2 uses environment variables to define the location of workspaces and
- transfer files. These variables have the form APLnnnnn, where nnnnn is the
- library number (left-padded to 5 digits with zeros). The APL2 command file sets
- the following defaults for libraries unless a different directory structure was
- selected during installation.
-
- o APL00001=C:\APL2OS2\WSLIB1
- o APL00002=C:\APL2OS2\WSLIB2
- o APL01001=.\
-
- Other APLnnnnn environment variables can be defined to support additional paths
- containing workspaces. These definitions can be added to apl2.cmd. For example,
- specifying:
-
- APL02001=d:\hal\wkspaces
-
- Causes APL2/2 to use the \hal\wkspaces directory whenever a library number of
- 2001 is used. Then:
-
- )WSID 2001 PLOT
- )SAVE
-
- Saves the active workspace in file d:\hal\wkspaces\plot.apl.
-
- When system commands are specified with no explicit library number, a default
- library is determined as follows:
-
- 1. If an environment variable APLnnnnn exists, where "nnnnn" matches the first
- element of РAI, its value is used as the workspace directory.
-
- 2. Else, if the environment variable APL01001 is defined, its value is used.
-
- 3. Else, the APL01001 environment variable is automatically set to point to
- the current directory, which becomes the default library.
-
- The LIBS function (from the OS2 workspace described in The OS2 Workspace) can
- be used to query the current library definitions and their associated paths.
- Library definitions cannot be changed from APL2/2. To change library
- definitions, you must exit APL2/2 and change the APLnnnnn environment variable.
-
-
- ΓòÉΓòÉΓòÉ 7.4.2. Explicit File Specifications ΓòÉΓòÉΓòÉ
-
- As an alternative to library definitions, you can also specify a file name
- enclosed in single quotes in place of the workspace name and optional library
- number. For example:
-
- )LOAD 'd:\hal\wkspaces\plot.apl'
-
- Notes:
-
- 1. If a fully-qualified name is set for the active workspace with )LOAD or
- )WSID, then a subsequent )WSID without parameters returns the full name
- (including the quotes).
-
- 2. The maximum length for a fully-qualified name is 248 characters (including
- the quotes).
-
-
- ΓòÉΓòÉΓòÉ 8. Using the Session Manager ΓòÉΓòÉΓòÉ
-
- The APL2/2 session manager is a Presentation Manager-based application that
- allows you to carry on an interactive session with an APL2 interpreter. You can
- enter APL2 expressions and the results of their evaluation are displayed.
-
- The session manager maintains a log of your input expressions and the
- interpreter's results. The log is retained from one APL session to the next.
- You can scroll forward and backward in the log, modify old expressions, and
- type new expressions.
-
- The session manager provides facilities that let you:
-
- o Open, rename, save, and change the size of the log
- o Print all or portions of the log
- o Cut, copy, and paste text between the clipboard and the log
- o Search and optionally replace text in the log
- o Select from a list of workspace objects and open edit windows
- o Signal the interpreter to suppress output or halt
- o Turn the APL keyboard on and off
- o Select, create, and modify keyboard layouts
- o Select different name, size, and style fonts
- o Change the colors of different types of interpreter output
- o Set function key definitions
- o Control whether interpreter output is displayed immediately
- o Control whether stacked input lines are displayed
- o Select from a list of edit windows that have been opened
- o Control a remote interpreter
-
- The session manager includes an editor that can be used to edit character
- matrixes, functions, and operators. You can double-click on an object name in
- the log or use the Open Object window to select an object for editing. The APL2
- Window List displays the list of edit windows opened from the session manager.
- This feature cannot be used when you have issued a Γòû-edit or )HOST request
- which has not yet completed.
-
- To enable you to type the APL characters, the session manager redefines each of
- the alphanumeric keys on the keyboard. The Select Keyboard and Modify Keyboard
- windows enable you to select, display, create, and modify keyboard layouts.
-
- The session manager includes extensive online help. To display contextual help
- on any menu item or window, press F1. Use the choices on the Help menu to
- display:
-
- o General help about the session manager
- o Information about the keys the session manager supports
- o An index of help topics
- o Information about using Help
-
- o Session Manager Keys
- o Running a Remote Session Manager
-
-
- ΓòÉΓòÉΓòÉ 8.1. Session Manager Keys ΓòÉΓòÉΓòÉ
-
- The session manager supports the following:
-
- o Action Keys
- o Cursor Movement and Scrolling Keys
- o Text Modification Keys
- o Editing Keys
- o Other Keys
- o Edit Window Keys
-
-
- ΓòÉΓòÉΓòÉ 8.1.1. Action Keys ΓòÉΓòÉΓòÉ
-
- Enter or NewLine
- Sends any modified lines to the interpreter.
-
- Ctrl+Backspace
- Switches APL keyboard support on and off.
-
- Pause
- Suppresses interpreter output.
-
- Break
- Sends an Attention signal to the interpreter.
-
- Shift+Alt+F
- Opens or closes the Find window
-
-
- ΓòÉΓòÉΓòÉ 8.1.2. Cursor Movement and Scrolling Keys ΓòÉΓòÉΓòÉ
-
- Ctrl+NewLine
- Moves the cursor to the beginning of the next line.
-
- Left Arrow
- Moves the cursor left one character.
-
- Right Arrow
- Moves the cursor right one character.
-
- Down Arrow
- Moves the cursor down one line.
-
- Up Arrow
- Moves the cursor up one line.
-
- Alt+Left Arrow
- Scrolls the log left one column.
-
- Alt+Right Arrow
- Scrolls the log right one column.
-
- Alt+Down Arrow
- Scrolls the log down one line.
-
- Alt+Up Arrow
- Scrolls the log up one line.
-
- Tab
- Moves the cursor to the next tab stop.
-
- Note: Tabs stops are set every 6 columns
-
- BackTab (Shift+Tab)
- Moves the cursor to the previous tab stop.
-
- Page Up
- Scrolls the log up one page
-
- Page Down
- Scrolls the log down one page
-
- Ctrl+Page Up
- Scrolls the log left one page
-
- Ctrl+Page Down
- Scrolls the log right one page
-
- Home
- Moves the cursor to the beginning of the current line.
-
- End
- Moves the cursor to the end of the current line.
-
- Ctrl+Home
- Moves the cursor to the beginning of the log.
-
- Ctrl+End
- Moves the cursor to the end of the log.
-
- Alt+Home
- Moves the cursor to the upper left corner of the window.
-
- Alt+End
- Moves the cursor to the lower right corner of the window.
-
-
- ΓòÉΓòÉΓòÉ 8.1.3. Text Modification Keys ΓòÉΓòÉΓòÉ
-
- ESC
- Selects a line for input or undo changes to the line. Lines selected for
- input are identified by a mark next to the line in the left border of the
- window.
-
- Backspace
- Deletes the previous character.
-
- Delete
- Deletes the current character.
-
-
- ΓòÉΓòÉΓòÉ 8.1.4. Editing Keys ΓòÉΓòÉΓòÉ
-
- Shift+Delete
- Moves the marked text to the clipboard.
-
- Ctrl+Insert
- Copies the marked text to the clipboard.
-
- Shift+Insert
- Copies the data on the clipboard after the current line.
-
- Ctrl+Delete
- Deletes to the end of the line
-
- Ctrl+Spacebar
- Marks or unmarks the line
-
- Shift+Up Arrow
- Marks or unmarks the previous line
-
- Shift+Down Arrow
- Marks or unmarks the next line
-
- Ctrl+Shift+Home
- Marks or unmarks all lines to the top of the text
-
- Ctrl+Shift+End
- Marks or unmarks all lines to the bottom of the text
-
-
- ΓòÉΓòÉΓòÉ 8.1.5. Other Keys ΓòÉΓòÉΓòÉ
-
- The alphanumeric keys can be controlled to produce any character in the current
- font. Use Select Keyboard and the Modify Keyboard options to select or modify a
- keyboard layout.
-
- Use the Function Keys window to define text to be entered when a function key
- is pressed.
-
- Note: By itself, the Alt key has no effect. This is different from the OS/2
- default, which selects the menu bar.
-
-
- ΓòÉΓòÉΓòÉ 8.1.6. Edit Window Keys ΓòÉΓòÉΓòÉ
-
- Edit windows support the same keys as the session manager with the following
- differences:
-
- F2
- Saves the definition
-
- F3
- Closes the edit window
-
- F4
- Saves the definition and closes the edit window
-
- Newline
- Inserts a line if insert mode is active
-
- ESC
- Undoes modifications to modified lines.
-
- Enter
- Removes the modification marks from all lines without undoing the
- modifications.
-
- Ctrl+Break
- Has no effect
-
- Pause
- Has no effect
-
- F Keys
- F keys can not be defined in edit windows.
-
-
- ΓòÉΓòÉΓòÉ 8.2. Running a Remote Session Manager ΓòÉΓòÉΓòÉ
-
- The session manager is usually started automatically when the APL2 for OS/2
- interpreter is invoked. In this case, the session manager and the interpreter
- run on the same machine.
-
- The session manager can also be used to control a remote interpreter. In this
- way, an interactive session can be conducted with an interpreter on another
- machine across the room or around the world.
-
- The session manager is implemented as auxiliary processor 120. Rather than
- providing applications with the ability to execute session manager commands, AP
- 120 processes requests that conform to the shared variable interpreter
- interface. The session manager shares a variable with the interpreter through
- which the session is conducted. The session manager's Open Object and Edit
- windows also share variables with the interpreter.
-
- When attempting to use the session manager to control a remote session, the
- session manager should be manually started and run independently rather than
- automatically and dependently by an interpreter. The name of the program to run
- is AP120.EXE. The processor number that the session manager should use to sign
- on to the SVP should be passed as an argument. For example:
-
- [c:] ap120 -id 1120
-
- The session manager window appears with the word Unconnected in the title bar.
- The session manager waits for any interpreter to offer it a variable. When the
- session manager is offered and accepts a variable, the word Unconnected is
- replaced with the ID of the interpreter.
-
- In order to establish a shared variable connection with a remote interpreter,
- processor identification, and authorization entries are required for both the
- interpreter and the session manager. These entries are placed in the SVP
- profile file. This file is called apl2svp.prf and can be found in the
- \apl2os2\bin directory. For more information, see Processor Profile Structure.
-
- Before shares can be established, the SVP port server must be running. The port
- server can be started either from the Processors menu in the SVP Trace window,
- or when starting the trace window by using the -listen on invocation option, or
- when starting APL2 or AP 120 by using the -svplisten on APL2 and AP 120
- invocation option.
-
- o Workstation Interpreters
- o APL2/370 Interpreters
-
-
- ΓòÉΓòÉΓòÉ 8.2.1. Workstation Interpreters ΓòÉΓòÉΓòÉ
-
- When communicating with a remote workstation interpreter, the session manager
- actually shares a variable with processor 1, which runs under the interpreter.
- The session manager's processor profile entries might look like this:
-
- :svopid.7001
- :address.234.45.65.78
- :userid.JohnDoe
- :processor.1,1001
- :procauth.1120
- :rsvopid.7001
-
- For more information about processor profile entries, see Processor Profile
- Structure.
-
- These entries would allow the session manager, running as processor 1120, to
- share variables with processor 1 running under interpreter 1001 on John Doe's
- machine. The session manager displays 7001 in the title bar when it receives an
- offer from the processor identified by the :svopid.7001 tag.
-
- The remote workstation interpreter's processor profile entries would look like
- this:
-
- :svopid.9120
- :address.146.75.44.12
- :userid.JaneSmith
- :processor.1120
- :procauth.1,1001
- :rsvopid.9120
-
- These entries allow the processor 1 running under the interpreter 1001 to share
- variables with the session manager, running as processor 1120, on Jane Smith's
- machine.
-
- To invoke a workstation interpreter and have it be controlled by a remote
- session manager, use the -sm invocation option to specify the processor
- identification number of the session manager that the interpreter should extend
- an offer to. For example:
-
- apl2 -svplisten on -sm 9120
-
-
- ΓòÉΓòÉΓòÉ 8.2.2. APL2/370 Interpreters ΓòÉΓòÉΓòÉ
-
- When communicating with an APL2/370 interpreter, the session manager shares a
- variable directly with the interpreter. The APL2/370 products do not include an
- auxiliary processor 1. The session manager's processor profile entries might
- look like this:
-
- :svopid.7001
- :address.234.45.65.78
- :userid.JohnDoe
- :processor.1001
- :procauth.1120
- :rsvopid.7001
-
- These entries allow the session manager, running as processor 1120, to share a
- variable with interpreter 1001 running on John Doe's user ID. The session
- manager displays 7001 in the title bar when it receives an offer from the
- processor identified by the :svopid.7001 tag.
-
- The APL2/370 interpreter's processor profile entries would look like this:
-
- :svopid.9120
- :address.146.75.44.12
- :userid.JaneSmith
- :processor.1120
- :procauth.1001
- :rsvopid.9120
-
- These entries allow interpreter 1001 to share a variable with the session
- manager, running as processor 1120, on Jane Smith's machine.
-
- To invoke an APL2/370 interpreter and have it be controlled by a remote session
- manager, use the sm invocation option to specify the processor identification
- number of the session manager that the interpreter should extend an offer to.
- For example:
-
- apl2 apnames(ap2x119(listen(0))) sm(9120)
-
- Note: Because the APL2/370 products do not include an auxiliary processor 1,
- the session manager Open Object and Edit windows are not be able to share
- variables with the processor. These facilities are not supported when
- controlling an APL2/370 interpreter.
-
-
- ΓòÉΓòÉΓòÉ 9. Editors ΓòÉΓòÉΓòÉ
-
- APL2/2 provides facilities for editing APL objects and OS/2 text files.
-
- The editing facilities include:
-
- o Opening objects from the session manager
- o The interpreter's Line Editor
- o The Apledit program
- o The EDITOR_2 and EDIT functions in the EDIT workspace
- o The APLEDIT and EDIT functions in the PMTOOLS workspace
-
- APL functions and operators, and variables containing character matrixes can be
- edited.
-
- The following objects can not be edited:
-
- o Variables containing numeric, mixed, or nested arrays
- o Locked functions and operators
- o External functions
- o System variables and functions
-
- o Opening and Editing Objects
- o The Line Editor
- o The Apledit Program
- o EDIT Workspace Functions
- o PMTOOLS Workspace Functions
-
-
- ΓòÉΓòÉΓòÉ 9.1. Opening and Editing Objects ΓòÉΓòÉΓòÉ
-
- Objects in the active workspace can be opened for editing from the session
- manager. When an object is opened, the session manager opens a window for
- editing the object. Editor windows can be left open while you continue to
- interact with the interpreter. Objects can be opened while the interpreter is
- running.
-
- Session manager and editor windows all include the Edit menu choice Open
- Object. Use Open Object to display a list of the objects in the active
- workspace. Use the Type of Object buttons to list either the variables,
- functions, or operators in the workspace. Type or select an object name and
- press OK to open the object. If the object does not exist, the object is opened
- with the selected name class.
-
- To open an object directly from a session manager or editor window, double
- click on the object's name. Only objects that already exist can be opened in
- this way.
-
- Session manager and editor windows all include the Windows menu choice APL2
- Windows List. Use APL2 Windows List to display a list of the editor windows
- opened from the session manager. The list also includes the session manager
- window. Double click on a window name to switch to the window.
-
- Editor windows support the same keys as the session manager with the following
- differences:
-
- F2 Saves the object.
-
- F3 Closes the editor window.
-
- F4 Saves the object and closes the editor window.
-
- Newline Inserts a line if insert mode is active.
-
- ESC Undoes modifications to modified lines.
-
- Enter Removes the modification marks from all lines without undoing the
- modifications.
-
- Ctrl+Break Has no effect.
-
- Pause Has no effect.
-
- Function Keys Function keys cannot be defined in editor windows.
-
- For further information about opening objects from the session manager, consult
- the online help.
-
- Editor windows have the following restrictions:
-
- o If an object is open and you attempt to open the object again, another editor
- window is not opened. The editor window displaying the object is given focus.
-
- o If an object is open, changes made to the object by the Line Editor, a system
- editor, or by execution of an APL expression are not displayed in the editor
- window. To display the changes made to the object, close and reopen the
- object.
-
- o If an object has more than 32000 rows or columns, it can not be opened.
-
-
- ΓòÉΓòÉΓòÉ 9.2. The Line Editor ΓòÉΓòÉΓòÉ
-
- The Line Editor can be used to edit functions and operators.
-
- To use the Line Editor to edit an object, first select the Line Editor for use
- as APL's editor, and then use Γòû followed by an object name or header. For
- example:
-
- )EDITOR 1
- ΓòûNAME
-
- For further information about the Line Editor consult APL2 Programming:
- Language Reference.
-
-
- ΓòÉΓòÉΓòÉ 9.3. The Apledit Program ΓòÉΓòÉΓòÉ
-
- The Apledit program can be used to edit text files containing APL characters.
-
- To invoke Apledit to edit a file, enter:
-
- [c:] apledit filename
- or from APL2:
-
- )HOST apledit filename
-
- To use Apledit to edit a function or operator, first select Apledit for use as
- the system editor, and then use Γòû followed by the object name. For example:
-
- )EDITOR APLEDIT
- ΓòûNAME
-
- Apledit has the following restrictions:
-
- o The file can not contain more than 32000 records.
- o No record can contain more than 32000 characters.
-
- Apledit provides online help that can be consulted for further information.
-
- For further information about the APL2's system editor interface, consult APL2
- Programming: Language Reference.
-
-
- ΓòÉΓòÉΓòÉ 9.4. EDIT Workspace Functions ΓòÉΓòÉΓòÉ
-
- The EDITOR_2 function emulates the APL2/370 full-screen )EDITOR 2.
-
- The EDIT function can be used to edit functions and operators.
-
- For further information about the EDIT workspace, see The EDIT Workspace.
-
-
- ΓòÉΓòÉΓòÉ 9.5. PMTOOLS Workspace Functions ΓòÉΓòÉΓòÉ
-
- The APLEDIT function can be used to edit functions and operators. APLEDIT
- writes a copy of the object's definition to a file and invokes the Apledit
- program to edit the file.
-
- The EDIT function can be used to edit character matrixes. EDIT does not support
- matrixes that contain more than 64000 characters.
-
- For further information about the PMTOOLS workspace, see The PMTOOLS Workspace.
-
-
- ΓòÉΓòÉΓòÉ 10. Using APL2 across Systems ΓòÉΓòÉΓòÉ
-
- This chapter describes how to communicate between APL2 sessions on different
- systems, and how to transfer programs and data between systems.
-
- o Cooperative Processing
- o Transferring Workspaces
- o Transferring Files
-
-
- ΓòÉΓòÉΓòÉ 10.1. Cooperative Processing ΓòÉΓòÉΓòÉ
-
- APL2 sessions can communicate either with each other or with other non-APL
- programs across a Transmission Control Protocol/Internet Protocol (TCP/IP)
- network.
-
- There are three major facilities within APL2/2's support for cooperative
- processing:
-
- o Cross-System Shared Variables
-
- This facility allows a user to share variables with other processors on a
- TCP/IP network using normal APL2 shared variable techniques. It provides
- APL2's most convenient program-to-program cross network communication path.
-
- o Shared Variable Interpreter Interface
-
- This interface provides a set of protocols whereby an APL2 interpreter can be
- controlled through a shared variable. It provides a way for a program to
- control a remote session.
-
- o TCP/IP Auxiliary Processor (AP 119)
-
- This processor allows users and applications to make direct requests to
- TCP/IP. It provides APL2's most flexible program-to-program cross network
- communication path. The interface can also be used for communication between
- APL2 and non-APL programs across a network.
-
- o Processor Network Identification
- o Processor Profile Structure
- o Using the Port Server
- o Sending a Share Offer
- o Receiving a Share Offer
- o Processor Profile Syntax
- o Processor Profile Examples
-
-
- ΓòÉΓòÉΓòÉ 10.1.1. Processor Network Identification ΓòÉΓòÉΓòÉ
-
- An APL2 session consists of a collection of processors. From the point of view
- of an APL2 program, each processor is identified by a single nonnegative
- integer. The APL2 user is identified with a processor number greater than 1000.
- Other processors in the session are called auxiliary processors (APs) and are
- normally identified with a processor number less than 1000.
-
- A single integer is not enough to address processors in multiple sessions and
- processors in sessions on a network. Therefore a Processor Profile provides a
- cross reference between the single processor number used by APL2 programs and a
- processor network identification.
-
- The file name of the processor profile is specified in the environment variable
- APL2SVPPRF. If this variable is not defined, the name apl2svp.prf is used.
-
- The profile is used for both outgoing offers from a processor and for incoming
- offers from other processors. It is read for each offer and can be dynamically
- modified.
-
- Every processor on the network has a unique name consisting of the following
- parts:
-
- IP_address user_id processor_number[,parent[,grandparent]]
- For example:
-
- 123.45.6.78 BROWN 1002
- 123.45.6.78 BROWN 127,1001
-
- A processor named with only an IP address, user ID, and processor number is
- called an independent processor. In the first example above, 1002 is an
- independent processor. Normally, the APL2 interpreter runs as an independent
- processor.
-
- A processor with a parent (or any ancestor) is called a dependent processor. A
- dependent processor is notified when its immediate ancestor signs off. In the
- second example above, 127 depends on 1001 and 1001 is independent. Normally,
- the APL2 interpreter runs as an independent processor with its auxiliary
- processors dependent on it. This scheme allows processor 127 to be informed
- (and normally to terminate itself) when the APL2 session ends.
-
- A third level of dependency is defined if a processor is started with a
- grandparent processor number. This scheme allows APL applications to serve as
- dependent auxiliary processors, since they in turn need to use other dependent
- auxiliary processors. Longer sequences of ancestors would be meaningful but are
- not supported.
-
-
- ΓòÉΓòÉΓòÉ 10.1.2. Processor Profile Structure ΓòÉΓòÉΓòÉ
-
- Each line in the processor profile can contain one or more tags and its
- associated data. Tags can be written in uppercase, lowercase, or mixed case.
- Any line starting with the character "*" is ignored.
-
- Each processor entry must begin with either an :svopid tag or a :procauth tag
- and continues to the next occurrence of one of these tags or to the end of the
- profile. A processor entry beginning with an :svopid tag is known as an
- identification or ID entry. Here is an example of an ID entry that defines
- 33586 as a remote user signed on as ID 1002 under BROWN at 123.45.6.78.
-
- * user BROWN at STLAPL
- :svopid.33586
- :address.123.45.6.78
- :userid.BROWN
- :processor.1002
-
- A processor entry beginning with a :procauth tag is known as an authorization
- entry. Here is an example of an entry that authorizes the remote processor
- identified by an svopid of 33586 to share with a local processor 100, which is
- a dependent of processor 1001:
-
- * AP100 authorization
- :procauth.100,1001
- :rsvopid.33586
-
-
- ΓòÉΓòÉΓòÉ 10.1.3. Using the Port Server ΓòÉΓòÉΓòÉ
-
- The APL2 port server must be active for cross-system sharing to be possible.
- The APL2/2 port server can be started in several different ways:
-
- o Specifying the -svplisten on parameter when invoking APL2/2 or any other
- independent processor.
-
- o Setting the environment variable APLSVPLISTEN to on before invoking APL2/2.
-
- o Specifying the -listen on parameter when starting the SVP Trace window
- program.
-
- o Selecting Cross System/Start from the Actions menu of the SVP Trace window.
- (For more information about the SVP Trace window, see SVP Trace Facility.)
-
- Note: No matter how the port server is started, TCP/IP must have been started
- before starting the SVP.
-
-
- ΓòÉΓòÉΓòÉ 10.1.4. Sending a Share Offer ΓòÉΓòÉΓòÉ
-
- When a shared variable offer is extended, the processor number from the left of
- РSVO is matched against the data in :svopid tags in the processor profile. If a
- match is found, the offer is extended to the processor described by the tag's
- :processor value and, if present, by the :address and :userid values.
-
- If no match is found, and the processor number is greater than 1000, the offer
- is extended to an independent processor identified by the given processor
- number, within the same SVP domain as the offerer (same IP address and user
- ID).
-
- If the processor number is less than 1001, the offer is assumed to be to a
- processor dependent on the offerer. The parent is taken to be the offerer's
- processor number and the grandparent is taken to be the offerer's parent, if
- any. If this processor is not running an attempt is made to start the
- processor. For example, if you are processor 1001 and issue the following
- share:
-
- 127 РSVO 'VAR'
-
- and 127 is not found in the processor profile, the offer is made to a processor
- 127 that is dependent on 1001. If processor 127 is not signed on, an executable
- named ap127 is searched for and started automatically, if found. Therefore an
- APL2 session can communicate with its dependent auxiliary processors without
- using the processor profile; dependent auxiliary processors are started
- automatically as needed. Independent auxiliary processors must either use a
- processor number above 1000 or be identified in the processor profile.
-
-
- ΓòÉΓòÉΓòÉ 10.1.5. Receiving a Share Offer ΓòÉΓòÉΓòÉ
-
- When receiving an offer to share, the processor profile serves to identify the
- remote processor and to authorize the share. First, the processor
- identification of the processor originating the share is matched against the
- :address, user ID, and :processor tags of each ID entry in the processor
- profile. Limited "wildcard" support is provided as discussed in Processor
- Profile Syntax.
-
- If a matching entry is found, the svopid of this entry must be identified in
- the :rsvopid tag of an authorization entry for the local processor with whom
- the caller is trying to share. If this is true, the share is allowed to
- proceed.
-
-
- ΓòÉΓòÉΓòÉ 10.1.6. Processor Profile Syntax ΓòÉΓòÉΓòÉ
-
- Each line in the processor profile can contain one or more tags and its
- associated data. Tags can be written in uppercase, lowercase, or mixed case.
- Any line starting with the character "*" is ignored.
-
- o Identification Entries
- o Authorization Entries
-
-
- ΓòÉΓòÉΓòÉ 10.1.6.1. Identification Entries ΓòÉΓòÉΓòÉ
-
- Each processor ID entry must begin with a :svopid tag and continues to the next
- occurrence of a :svopid or :procauth tag or to the end of the profile.
-
- :svopid.id
-
- This tag identifies the beginning of an entry and is required. It specifies the
- number to be used in the left argument of РSVO when sharing with the processor
- described by this entry. For incoming offers its value is returned by РSVQ. It
- must be a positive number. This value can be coded as 0 to allow incoming
- offers to be assigned a unique processor number. Such an entry could not,
- however, be used to initiate an offer.
-
- :processor.id[,id[,id]]
-
- This tag gives one, two, or three processor numbers separated by commas and is
- required. These numbers represent the actual procid, parent and grandparent of
- the share partner.
-
- Because offers to processors with procids less than 1000 are considered to be
- offers to dependent processors, a profile ID entry is required to share with a
- processor running independently on the same machine and user ID. In this case,
- the svopid can be the same or different than the actual procid of the
- independent processor. Note that if the same number is used, it is impossible
- to share with a dependent processor using that number as its procid.
-
- id can be coded as "*" in which case the entry identifies any remote processor
- with the corresponding :svopid.
-
- :address.addr
-
- This tag gives the IP address of the partners machine in IP "dotted decimal"
- notation consisting of four decimal numbers between 0 and 255 separated by
- periods and is optional.
-
- addr can be coded as "*" in which case the entry identifies processors from any
- address with the corresponding :svopid.
-
- :userid.userid
-
- This tag gives the character identification of the user ID of the partner and
- is optional. It can be one to eight characters and is case sensitive.
-
- userid can be coded as "*" in which case the entry identifies processors from
- any user ID with the corresponding :svopid.
-
- Here is an example of a processor entry that defines РSVO argument 33586 as a
- remote user.
-
- * user BROWN at STLAPL
- :svopid.33586
- :address.123.45.6.78
- :userid.BROWN
- :processor.1002
-
-
- ΓòÉΓòÉΓòÉ 10.1.6.2. Authorization Entries ΓòÉΓòÉΓòÉ
-
- Each processor authorization entry must begin with a :procauth tag and
- continues to the next occurrence of a :procauth or :svopid tag, or to the end
- of the profile.
-
- :procauth.id[,id[,id]]
-
- This tag identifies the procid, parent and pparent that is authorized to
- receive shares and is required. id can be coded as "*" in which case the entry
- serves to authorize all local processors.
-
- :rsvopid.id[,id[,...]]
-
- This tag lists the svopid numbers that identify remote processors that are
- authorized to share with the processor named in the corresponding :procauth
- tag. Multiple numbers can be listed separated by commas.
-
- id can be coded as "*" in which case the entry authorizes any remote processor
- to share with the corresponding :procauth.
-
- Here is an example of an entry that authorizes the processor identified by
- :svopid.33586 to share with a local processor 100 dependent on processor 1001:
-
- * AP100 authorization
- :procauth.100,1001
- :rsvopid.33586
-
-
- ΓòÉΓòÉΓòÉ 10.1.7. Processor Profile Examples ΓòÉΓòÉΓòÉ
-
- The technical reference material you need to share variables between processors
- running on different machines was presented in Processor Network Identification
- and Processor Profile Structure. This section provides examples of how to code
- processor profile entries for some typical application needs.
-
- For the purposes of these examples, assume that there are three users running
- interpreters on three different machines. Each interpreter process is
- identified with a unique IP address, user ID, and processor number. The
- processor numbers correspond to ╞РAI as reported by the interpreters
- themselves.
-
- For clarity, these sample interpreters are referred to as Users 1, 2, and 3.
- You need the following information: See Profile Information.
-
- o User to User Shared Variables
- o User to Auxiliary Processor Shared Variables
- o Using Asterisks in Processor Profile Entries
-
-
- ΓòÉΓòÉΓòÉ 10.1.7.1. Profile Information ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- User
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Address
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- User ID
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- ╞РAI
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 1
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 9.10.11.123
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- BARB
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 1001
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 2
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 9.10.11.222
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- jsmith
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 32739
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 3
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 123.45.6.77
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- djones
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 6666
-
-
- ΓòÉΓòÉΓòÉ 10.1.7.2. User to User Shared Variables ΓòÉΓòÉΓòÉ
-
- Assume that User 1 wants to share variables with User 2. The information needed
- is as follows:
-
- 1. In order to offer to share a variable with another processor, you need to
- identify that processor with some number. A processor profile entry is then
- used to associate that number with the user's network information.
-
- Assume that User 1 wants to refer to User 2 with the number 777. The
- following entry is required in User 1's profile:
-
- :svopid.777
- :address.9.10.11.222
- :userid.jsmith
- :processor.32739
-
- This entry allows User 1 to extend an offer to User 2.
-
- 2. User 1 needs to authorize User 2 to share variables. User 2 is already
- identified as 777 with the :svopid tag, and it is known that User 1 is
- running as processor 1001, so the following entry can be used:
-
- :procauth.1001
- :rsvopid.777
-
- This authorizes remote processor 777 to share variables with local
- processor 1001.
-
- Remember that there are always two sides to every share. User 2 also needs a
- number to use to refer to User 1. Assume that User 2 wants to use the number
- 3456. The following entry is required in User 2's profile:
-
- :svopid.3456
- :address.9.10.11.123
- :userid.BARB
- :processor.1001
-
- User 2 also needs to authorize User 1:
-
- :procauth.32739
- :rsvopid.3456
-
- Note that the :rsvopid values correspond to the :svopid values shown above, and
- the :procauth values correspond to the processor numbers of the interpreters as
- reported by ╞РAI.
-
- If Users 1 and 3 also wanted to share variables, they would have to code
- identification and authorization entries just as Users 1 and 2 did. However,
- when coding the authorization entry, User 1 can take either of two approaches.
- First, User 1 could simply add another authorization entry. Assume User 3 has
- been identified as processor 8888:
-
- :procauth.1001
- :rsvopid.8888
-
- You can have as many authorization entries in your processor profile as you
- want, but there is another way. The :rsvopid. tag can provide a list of
- processors. So, User 1 could add User 3's number to the existing entry like
- this:
-
- :procauth.1001
- :rsvopid.777,8888
-
- This entry authorizes the remote users associated with the numbers 777 and 8888
- to share variables with User 1's 1001 processor.
-
- User 1 could authorize more users by adding more entries or by just adding
- numbers to the :rsvopid tag.
-
-
- ΓòÉΓòÉΓòÉ 10.1.7.3. User to Auxiliary Processor Shared Variables ΓòÉΓòÉΓòÉ
-
- For another example, assume that User 1 wants to share a variable with AP 127,
- which is running under interpreter processor 6666 on User 3's machine. This
- might be useful if User 3's machine contained a database that User 1 needed
- access to.
-
- User 1 needs to add another identification entry to associate a number with the
- remote processor 127. Assume that User 1 wants to use the number 9127 to refer
- to the remote processor. The entry is as follows:
-
- :svopid.9127
- :address.123.45.6.77
- :userid.djones
- :processor.127,6666
-
- Notice the :processor tag now lists two processor numbers. This indicates that
- AP 127 is a dependent of processor 6666.
-
- User 1 also needs to authorize shares with the remote processor 127 so the
- authorization entry becomes:
-
- :procauth.1001
- :rsvopid.777,8888,9127
-
- If Users 1 and 3 are set up for user to user sharing, User 3 already has
- identification entry for User 1. However, AP 127 is a new processor on User 3's
- machine, and is sharing variables, so another authorization entry needs to be
- added for User 3. Assuming User 3 has identified User 1 as 2229:
-
- :procauth.127,6666
- :rsvopid.2229
-
- Like the :processor. tag shown above, the :procauth. tag in this authorization
- entry lists two numbers. In this case, however, it does not refer to two
- separate processors. Only a single processor (in this case 127, dependent of
- 6666) can be listed in a :procauth tag. The exception to this rule is the use
- of an asterisk as mentioned below.
-
-
- ΓòÉΓòÉΓòÉ 10.1.7.4. Using Asterisks in Processor Profile Entries ΓòÉΓòÉΓòÉ
-
- The examples shown demonstrate how to identify specific remote processors and
- authorize them to establish shares with specific local processors. Sometimes
- however, it is not possible to identify all the potential share partners.
- Similarly, sometimes you want to give one or more share partners access to all
- your processors. Asterisks are used as wildcards in processor profile entries
- to provide general identification and authorization
-
- Suppose that User 1 is writing a server; there is no way to know who the
- server's potential clients might be. It is not possible to code separate
- identification entries for each client. In this case, User 1 can code this
- identification entry:
-
- :svopid.0
- :address.*
- :userid.*
- :processor.*
-
- In effect, this entry identifies any remote processor as number 0. This number
- is used for a special reason. A remote processor is always known to the APL2
- session by the number used in the :svopid tag. When the number 0 is seen by the
- APL2 shared variable processor, a new unique number is automatically assigned.
-
- You have now handled the problem of identifying unknown processors, and can now
- deal with authorization. An asterisk can also be used in the :rsvopid tag like
- this:
-
- :procauth.1001
- :rsvopid.*
-
- This authorizes shares from any processor.
-
- Finally, assume that User 1 not only wanted to authorize remote users to share
- with processor 1001, but with any processor. The following entry can be used:
-
- :procauth.*
- :rsvopid.*
-
- This entry authorizes all remote processors, indicated by the asterisk in the
- :rsvopid. tag, to establish shares with any processor on the machine, indicated
- by the asterisk in the :procauth. tag.
-
-
- ΓòÉΓòÉΓòÉ 10.2. Transferring Workspaces ΓòÉΓòÉΓòÉ
-
- Workspaces are easily transferred between APL2 systems. Transfer file formats
- have been defined to permit exchange of workspace objects among all IBM APL2
- implementations. Additional tools are provided for migration of the older VS
- APL format to APL2.
-
- o Workspace Transfer Between APL2 Systems
- o Migration of TryAPL2 Workspaces
- o Migration of VS APL Workspaces
-
-
- ΓòÉΓòÉΓòÉ 10.2.1. Workspace Transfer Between APL2 Systems ΓòÉΓòÉΓòÉ
-
- In general, APL2 workspaces must be sent to other APL2 systems as transfer form
- files. On workstation platforms, these files have an extension of .atf. On
- mainframe platforms, these files have an extension of .apltf. Note that on some
- workstations the names of transfer files and workspaces and their extensions
- are case sensitive.
-
- The APL2 commands used to create and read transfer form files are )OUT, )IN,
- and )PIN. To transfer a workspace, start APL2 on the system where the workspace
- resides, and issue the following commands:
-
- )LOAD wsid
- )SIC (or )RESET)
- )OUT filename
-
- A transfer file is created by the )OUT command.
-
- Once the transfer file is created, it then must be moved to the target APL2
- system. The techniques for physically moving files from one system to another
- can vary depending on the types of systems and what connections exist between
- them.
-
- o One key issue is that some systems (for example MVS/TSO and VM/CMS) use an
- EBCDIC character encoding, while others (for example OS/2 and AIX/6000) use
- an ASCII encoding. Both ASCII and EBCDIC transfer file formats are defined,
- and all IBM APL2 systems accept both formats. No data conversion should be
- attempted within the file itself when transferring it from one system to
- another. The receiving APL2 system performs any necessary conversion. If the
- transfer is done electronically through a network connection, the programs
- controlling that transfer must be told that this is a "binary" rather than
- "character" file. (The exact terminology used may vary depending on the
- system and network control programs being used.)
-
- o Some systems use "record-oriented" files while others use stream files. If
- stream files are being transferred to a system that expects record-oriented
- files, an arbitrary record length may be used, but the existing record
- separators ("LF" or "CR/LF") must be retained. Conversely, separators should
- not be inserted when record-oriented files are being transferred to a system
- that expects stream files. Again, the receiving APL2 system adjusts to these
- differences.
-
- o Within these constraints, standard data transmission commands appropriate to
- the system such as "ftp put", "SEND", "SENDFILE", or "TRANSMIT" can be used
- for network transmission, with corresponding commands such as "ftp get" or
- "RECEIVE" as appropriate to the receiving system.
-
- o Because the receiving APL2 system performs all necessary conversions, it is
- also possible to use shared DASD, remote file systems, removable media, or
- other such facilities to transport the data.
-
- When the file has been transferred to the target system, it can then be read
- into APL2 and saved as a workspace:
-
- )CLEAR
- )IN filename
- )SAVE wsid
-
- Note: Though it is possible to run APL2/PC on the same system where you have
- installed APL2/2, the workspace formats used by the programs are all different.
- Workspaces must be migrated between APL2/PC and APL2/2 using .atf files as
- described above.
-
-
- ΓòÉΓòÉΓòÉ 10.2.2. Migration of TryAPL2 Workspaces ΓòÉΓòÉΓòÉ
-
- Workspaces saved under TryAPL2 can also be read by APL2/2, APL2/6000, and APL2
- for Sun Solaris. The function TRYLOAD in the FILE workspace can be used to read
- these files.
-
-
- ΓòÉΓòÉΓòÉ 10.2.3. Migration of VS APL Workspaces ΓòÉΓòÉΓòÉ
-
- VS APL workspaces can be migrated to the workstation platforms using the VSCOPY
- function from the MIGRATE workspace (described in The MIGRATE Workspace).
-
- The saved VS APL workspaces should have a clear state indicator. This can be
- ensured before you )SAVE the workspace by using the )SI command to check the
- state indicator, and entering Γòò one time for each * in the display from )SI.
-
- Download each saved workspace in binary form to a file. The VSCOPY function
- assumes that the file extension used for downloaded VS APL workspaces is .VWS
- (renamed from .VSAPLWS on VS APL). Then, run the VSCOPY function against each
- workspace:
-
- )CLEAR
- )COPY 2 MIGRATE VSCOPY
- VSCOPY 'filename'
- )ERASE VSCOPY
- )SAVE wsid
-
-
- ΓòÉΓòÉΓòÉ 10.3. Transferring Files ΓòÉΓòÉΓòÉ
-
- Files created by the APL2 file processors, AP 210 and AP 211, can also be
- transferred across systems, or accessed on shared media.
-
- o AP 210 Files
- o AP 211 Files
-
-
- ΓòÉΓòÉΓòÉ 10.3.1. AP 210 Files ΓòÉΓòÉΓòÉ
-
- Files created by AP 210 are portable between APL2/2, APL2/6000, and APL2 for
- Sun Solaris. Files should be transmitted in binary mode.
-
- In addition, files created by AP 210 on APL2/PC can be read by APL2/2,
- APL2/6000, and APL2 for Sun Solaris. Writing back to these files is allowed,
- but is not recommended for code A files. The format used for code A files is
- different from APL2/PC, and objects take a different amount of storage. File
- corruption is likely. In order to create a writable file, each object in the
- APL2/PC file should be read and rewritten to a new file.
-
-
- ΓòÉΓòÉΓòÉ 10.3.2. AP 211 Files ΓòÉΓòÉΓòÉ
-
- Files created by AP 211 are portable between APL2/370, APL2/2, APL2/6000, and
- APL2 for Sun Solaris. The files must be transferred in binary mode. The
- receiving APL2 system performs all necessary conversions of data. Files to be
- uploaded to the mainframe must be uploaded as fixed format files, with a record
- length equal to the AP 211 blocksize for the file. The blocksize can be
- obtained by issuing an AP 211 USE command against the file.
-
- In addition, files created by AP 211 on APL2/PC can be read by APL2/2,
- APL2/6000, and APL2 for Sun Solaris. Writing back to these files is not
- allowed. The function REBUILD211 in the public workspace 2 FILE can be used to
- permanently convert the APL2/PC file to the new format if desired.
-
-
- ΓòÉΓòÉΓòÉ 11. Associated Processors ΓòÉΓòÉΓòÉ
-
- Names are used in APL expressions to identify variables, defined functions and
- operators, and constants (such as labels). When APL encounters names during the
- execution of expressions, it passes control to the appropriate routines in the
- interpreter for evaluation.
-
- Through the use of РNA, and by associating a name with a specific processor, an
- APL application program can cause that name to be processed by routines in the
- specified associated processor instead of the APL interpreter. Associated
- processors provide an alternate mechanism for handling the evaluation of APL
- names.
-
- o Applications of External Names
- o Processor 11-Accessing External Routines
-
-
- ΓòÉΓòÉΓòÉ 11.1. Applications of External Names ΓòÉΓòÉΓòÉ
-
- A name associated with a processor is called an external name.
-
- External names have a variety of uses in building production applications. By
- giving you additional options in the ways in which you process information from
- APL, external names help improve productivity. Some of the reasons you might
- use external names are:
-
- o Reuse of Existing Programs
-
- A principal objective of external names is to permit you to reuse many
- existing programs without any need to modify them. APL2 provides mechanisms
- by which you describe where the programs exist and what data structures they
- require in arguments. This information is provided to APL2 in a file. Once
- the information has been provided, you can then use external names to access
- these programs from your workspace just as if they were APL functions.
-
- o Synchronous Access to System Information
-
- Sometimes an application needs easy access to information about the host
- system or from another application subsystem. Since host information can vary
- widely between platforms, it is impractical for APL to provide it directly.
- You can use external names, however, to temporarily "escape" APL, access the
- information, and bring back the results to the workspace for use by the
- application.
-
- o Improve Performance
-
- It is common for an application to have a uniquely tailored data structure or
- algorithm that is used widely by the application's own functions. This
- application-specific feature often assumes a fundamental, what APL might term
- "primitive", nature and frequently becomes the bottleneck that limits either
- the capacity or performance of the application. External objects can be used
- to overcome such problems by permitting you to enclose the definition in
- compiled code. Because external objects are syntactically equivalent to the
- APL object from which they were derived, you need only replace the APL
- definition in the workspace with the external name association; much like
- copying an object. The remainder of the application is unmodified.
-
-
- ΓòÉΓòÉΓòÉ 11.2. Processor 11-Accessing External Routines ΓòÉΓòÉΓòÉ
-
- Processor 11 provides facilities that allow access to objects outside the
- active workspace that are routines written in languages other than APL2.
- Non-APL routines can be functions and can be niladic or monadic. Once access to
- a routine is established through processor 11, the routine is treated like a
- locked APL function.
-
- APL2 and processor 11 manage the necessary housekeeping, and argument and
- result conversion, based upon descriptive information provided for each routine
- by the user.
-
- o Processor 11 Overview
- o QuadNA Left Argument Syntax
- o NAMES File Syntax for Processor 11
- o Array Patterns
-
-
- ΓòÉΓòÉΓòÉ 11.2.1. Processor 11 Overview ΓòÉΓòÉΓòÉ
-
- Processor 11 manages the interface between the APL2 active workspace and
- non-APL routines outside the workspace. Processor 11 has the responsibility to
- load the non-APL routine, translate arguments from the APL2 workspace to a form
- the non-APL routine can work with, call the non-APL routine, and translate the
- routine's results to a form the APL2 interpreter can work with.
-
- Conceptually, non-APL routines are merely called by processor 11. Every time
- the user executes an expression that mentions the non-APL program, processor 11
- is called by the APL2 interpreter and it in turn calls the routine. Processor
- 11 requires several types of information to perform this task.
-
- Processor 11 needs to know about the arguments and results for each routine it
- calls. Since processor 11 translates arguments from APL2 workspace format to
- the non-APL routine's format, it needs to know what format the routine is
- expecting. Likewise, when the routine returns results, processor 11 needs to
- understand their format to be able to translate them to a workspace format.
- This information is provided in a NAMES file (see NAMES File Syntax for
- Processor 11).
-
- Before processor 11 can call a routine, it must locate the routine. Routines
- reside in DLLs.
-
-
- ΓòÉΓòÉΓòÉ 11.2.2. QuadNA Left Argument Syntax ΓòÉΓòÉΓòÉ
-
- The APL2 system function РNA is used to establish an association between a
- workspace name and an external program that processor 11 manages. The syntax of
- the РNA expression can take three forms.
-
- The first form causes processor 11 to use the APL2 product's environment
- variable to locate the NAMES file.
-
- 3 11 РNA 'object'
-
- This form directs processor 11 to use its default search order to locate a
- NAMES file entry for object. The search order progresses as follows:
-
- 1. Processor 11 looks for the default environment variable that is named
- APLP11. This variable is usually set by the APL2 invocation command file.
- If the environment variable is not found, the system proceeds as if it
- contained the simple name aplnm011.nam.
-
- The environment variable contains the file name of a NAMES file. The file
- name can be fully qualified. When APL2 is installed, the default for the
- NAMES file is aplnm011.nam.
-
- 2. Processor 11 attempts to open the specified file using standard operating
- system facilities.
-
- For OS/2, it searches the current directory and then the directories
- specified in the DPATH variable if the file cannot be found otherwise.
-
- If the NAMES file is not found, the association fails.
-
- 3. Processor 11 searches the NAMES file for an entry for object. If an entry
- is not found, the association fails.
-
- The second РNA form causes processor 11 to use an environment variable other
- than APLP11 to locate the NAMES file.
-
- '(envvar)' 11 РNA object
- This form directs processor 11 to use the environment variable named envvar.
- The search follows the same progression using the environment variable envvar
- rather than APLP11.
-
- The third РNA form supplies processor 11 with the file name of the NAMES file
- directly.
-
- '<filename>' 11 РNA 'object'
-
- This form directs processor 11 to use the NAMES file filename. The search for
- filename follows the same progression bypassing the use of an environment
- variable.
-
-
- ΓòÉΓòÉΓòÉ 11.2.3. NAMES File Syntax for Processor 11 ΓòÉΓòÉΓòÉ
-
- This section discusses the format and contents of the NAMES file.
-
- NAMES files are text files that contain comment records (an "*" in column 1)
- and case insensitive keywords (that start with a ":" and end with ".") and
- descriptive information (anything following the keyword, up to the next keyword
- or end of record, except for trailing blanks). The maximum record length
- allowed is 254 characters. The syntax of each noncomment record is:
- :keyword.Descriptive text. More than one keyword/text pair can be on each
- noncomment line.
-
- The description of each routine is located by a :NICK. keyword with the
- descriptive information being the name by which processor 11 knows it, and ends
- at the next :NICK. keyword or the end of the file.
-
- The descriptive text for each keyword can contain colons and periods provided
- that they cannot be interpreted as keywords. It is not valid to use any
- sequence consisting of a colon, a letter, optionally one or more additional
- letters or numbers, and finally a period.
-
- Certain arguments, however, require patterns of more than 254 characters. To
- accommodate this requirement, the argument can be described in successive
- records in a NAMES file, each of which is prefixed with an appropriate argument
- keyword. The total length for all the descriptive text associated with a
- keyword is 511 characters. (Use preceding blanks in additional descriptive text
- if blanks are required between phrases.) For example:
-
- :RARG.(G0 1 3) (1 E8 *)
- :RARG.(I4 2 * 10)
- :RARG.(I4 2 10 *)
-
- o Routine Descriptor Keywords
-
-
- ΓòÉΓòÉΓòÉ 11.2.3.1. Routine Descriptor Keywords ΓòÉΓòÉΓòÉ
-
- This section describes the routine descriptor keywords and the :MACRO. facility
- that enables you to substitute portions of a line with a macro.
-
- The :MACRO. facility is a one-line shorthand notation. Once a macro name is
- defined, all the subsequent instances of $(name) in the same file are replaced
- with the definition portion of the line. The syntax for :MACRO. is:
-
- :MACRO.name definition
- For example, a macro defined as:
-
- :MACRO.CHARP (G4 0) (S1 1 *)
-
- Can be used later on as:
-
- :RSLT. $(CHARP) This is the same as :RSLT. (G4 0) (S1 1 *)
-
- Macros must be defined before the first :NICK. keyword, and are invoked by
- $(name). The :MACRO. facility allows 20 levels of nested macros. Any keywords
- appearing in the definition are treated as normal text. Leading and trailing
- spaces are ignored.
-
- External Routine Descriptor Keywords describes the external routine descriptor
- keywords.
-
-
- ΓòÉΓòÉΓòÉ 11.2.3.1.1. External Routine Descriptor Keywords - Part 1 ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Keyword
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Use
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- :NICK.name
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Specifies the name of the external routine. The same name must be specified in
- the right argument of РNA. This keyword is used to associate the routine
- description following the keyword with the specified name.
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- :LINK.type
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Specifies the type of program linkage to be used when calling the routine. The
- following value is valid:
- :link.SYSTEM
-
- This describes the default linkage supported by most languages. For OS/2, this
- is _System.
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- MORE...
-
-
- ΓòÉΓòÉΓòÉ 11.2.3.1.2. External Routine Descriptor Keywords - Part 2 ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Keyword
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Use
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- :DESC.description
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Allows inclusion of descriptive text in a routine description. Where the
- descriptive text exceeds the record length of a NAMES file, multiple records of
- text can be included, but each must be prefixed by a :DESC. keyword. Comments
- can also be included in the NAMES file by placing an asterisk in column 1 of
- comment records.
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- :RARG.pattern
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Specifies a pattern for the right argument of the external routine. See Array
- Patterns for details.
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- :RSLT.pattern
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Specifies a pattern for the result of the external routine. > cannot be used in
- a :RSLT. pattern. See Result Patterns for details.
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- MORE...
-
-
- ΓòÉΓòÉΓòÉ 11.2.3.1.3. External Routine Descriptor Keywords - Part 3 ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Keyword
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Use
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- :VALENCE.er fv ov
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Specifies the valences of the routine. It becomes 1 РAT for the routine.
-
- er specifies whether the routine produces an explicit result. If er is 0, the
- routine does not produce an explicit result. If er is 1, the routine produces
- an explicit result.
-
- fv specifies whether the routine is niladic or monadic. If fv is 0, the routine
- is niladic. If fv is 1, the routine is monadic.
-
- ov must be 0.
-
- This keyword is optional. It defaults to :VALENCE.1 1 0.
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- MORE...
-
-
- ΓòÉΓòÉΓòÉ 11.2.3.1.4. External Routine Descriptor Keywords - Part 4 ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Keyword
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Use
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- :LIB.file
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Names the executable file that contains the entry point listed in the :PROC.
- keyword. The name can be fully qualified. This must be a DLL.
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- :PROC.entrypoint
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Contains the entry point in the executable file named in the :LIB. keyword. The
- entry point name is case sensitive.
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- :PATH.fullpath
- :PATH.(envvar)partialpath
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Path used to locate the executable file specified in the :LIB. keyword. If the
- path begins with "(" it is evaluated as the name of an environment variable
- that gives a path to locate the executable.
-
-
- ΓòÉΓòÉΓòÉ 11.2.4. Array Patterns ΓòÉΓòÉΓòÉ
-
- The :RARG. and :RSLT. keywords are used to specify the expected arguments and
- results for an external routine.
-
- When an external name is encountered during the execution of an APL expression,
- APL compares the actual arguments against the patterns provided in the
- routine's description. If possible, APL converts the actual arguments to match
- the patterns so the external routine receives its argument data in an expected
- and predictable form. If it is not possible to accomplish the conversion, or if
- an inconsistency is found between the actual arguments and the patterns, APL
- issues an appropriate error message.
-
- When the external routine completes, if the :RSLT. keyword has been used, APL
- uses the pattern specified in the :RSLT. keyword to convert the data returned
- by the routine to an APL2 array.
-
- An array pattern is a keyword value or character vector that describes the
- structure and type of an array. In addition to using array patterns to describe
- routine arguments and results, array patterns are used with several external
- functions supplied with APL2. Array patterns are given as the left argument of
- the external functions RTA and ATR, and are produced by the external function
- PFA.
-
- o Array Item Patterns
- o Nested or Mixed Arrays
- o Array Patterns for Non-APL Programs
- o Array Patterns for ATR, PFA, and RTA
-
-
- ΓòÉΓòÉΓòÉ 11.2.4.1. Array Item Patterns ΓòÉΓòÉΓòÉ
-
- The general form of an array item within an array pattern is as follows:
-
- ([count][>]type rank[shape])
-
- Where:
-
- ( An optional indicator for readability. Inclusion or omission
- has no effect on processing.
-
- count An optional integer or *, indicating the number of items in
- the array. This field can be omitted if the number of items
- is fully specified by the shape below. It can be coded as *
- if the number of items is fully specified by the shape, or if
- a variable number of items is permitted.
-
- > An optional update indicator of an argument that is set by
- the function. Such an argument is passed by name, as seen by
- the caller. The data provided by the calling program must be
- a character vector containing the name of an APL array. The
- content of that array is passed to the called program, and
- any updates to its argument are returned in that variable.
-
- Note: The "result indicator" (<) defined for APL2/TSO and
- APL2/CMS is not implemented on any other platforms.
-
- type A required data representation indicator. The following codes
- are supported:
-
- B1 Boolean - one bit per item
- B8 Integer byte (unsigned) - one byte per item
- I2 Integer halfword - 2 bytes per item
- I4 Integer fullword - 4 bytes per item
- E4 Real single precision - 4 bytes per item
- E8 Real double precision - 8 bytes per item
- J8 Complex single precision - 8 bytes per item
- J16 Complex double precision - 16 bytes per item
- S1 Null terminated character string - variable length
- C1 Character byte - one byte per item
- C2 Character halfword - 2 bytes per item
- C4 Character fullword - 4 bytes per item
- X0 Skipped data - one byte per item
- G0 General object
- G4 General object - pointer type
-
- rank A required integer showing the number of dimensions.
-
- shape A set of integers, one per dimension (empty if rank is zero).
- If varying shapes are accepted, one or more items of the
- shape can be specified as * in the :RARG. keyword.
-
- ) A readability indicator that must be provided if, and only
- if, the corresponding "(" was used.
-
- The elements of the pattern must be separated from one another by one or more
- blanks or parentheses.
-
- o Array Item Pattern Examples
-
-
- ΓòÉΓòÉΓòÉ 11.2.4.1.1. Array Item Pattern Examples ΓòÉΓòÉΓòÉ
-
- The following are examples of arrays with the array item patterns that describe
- them.
-
- Array Array Pattern
-
- 'ABC' (3 C1 1 3)
- C1 1 3
-
- 2 3 4 (3 I4 1 3)
- I4 1 3
-
-
- ΓòÉΓòÉΓòÉ 11.2.4.2. Nested or Mixed Arrays ΓòÉΓòÉΓòÉ
-
- The pattern for a nested or mixed array is a recursive structure in which the
- first subpattern has type = G0 or G4 (general object). Each subpattern can be
- surrounded by parentheses to make it easier to read. Parentheses do not
- indicate nesting; nesting can only be designated by using a G0 or G4 type. Each
- subpattern can be either an array item pattern or a group of items as defined
- here.
-
- o Nested or Mixed Array Pattern Examples
-
-
- ΓòÉΓòÉΓòÉ 11.2.4.2.1. Nested or Mixed Array Pattern Examples ΓòÉΓòÉΓòÉ
-
- The following are examples of arrays with nested or mixed array patterns:
-
- 'ABCD',2 3 4 (7 G0 1 7)(C1 0)(C1 0)(C1 0)(C1 0)(I4 0)(I4 0)(I4 0)
- 7 G0 1 7 C1 0 C1 0 C1 0 C1 0 I4 0 I4 0 I4 0
- 'ABCD' (2 3 4) (2 G0 1 2)(4 C1 1 4)(3 I4 1 3)
- G0 1 2 C1 1 4 I4 1 3
-
- As is shown in the examples above, a general object implies a recursive pattern
- where the first item is of type G0 (or G4). The count field in that item
- determines the number of additional array patterns that must follow.
-
- Note: The functions ATR, PFA, and RTA do not permit all the forms of array
- patterns. See Supplied External Routines for restrictions that apply.
-
-
- ΓòÉΓòÉΓòÉ 11.2.4.3. Array Patterns for Non-APL Programs ΓòÉΓòÉΓòÉ
-
- Array patterns are most frequently used to define the interface to a program
- written in some language other than APL. These patterns are provided in NAMES
- files, as discussed in QuadNA Left Argument Syntax.
-
- If a single pattern descriptor is used, the APL array is converted as necessary
- to match the specified data format, and then passed directly to the program as
- unstructured data.
-
- Processor 11 uses argument patterns for two purposes:
-
- o Conformability checks on a routine's argument
- o To determine how to pass the argument to the external routine
-
- It is useful to start by thinking of how arguments are passed to the external
- routine and to work backward from there to argument patterns and finally to the
- APL data structure needed to satisfy the patterns.
-
- Consider first a routine that accepts a 4-byte integer and a 4-byte floating
- point number as arguments. To write the pattern for this, begin by saying that
- there are two arguments, and then list them:
-
- :RARG. (2 G0 ...) (1 I4 ...) (1 E4 ...)
-
- Focus on the type descriptors (G0, I4, and E4) and the number to their left,
- which is the number of items being described. The numbers to the right of the
- type descriptor deal with the data as viewed by APL.
-
- Now consider what happens if the second parameter is an array of floating point
- numbers. Some languages make it possible to pass such an array directly, but
- more typically it is passed as a pointer to the array. Here is the pattern for
- a parameter list containing the integer as before, but also including a pointer
- to an array of 6 floating point numbers:
-
- :RARG.(2 G0 ...) (1 I4 ...) (1 G4 ...) (6 E4 ...)
-
- The first pattern descriptor still says there are two parameters, but the
- second parameter is now a G descriptor. Every G descriptor is followed by, and
- includes, as many subdescriptors as the number of items it defines.
-
- Some languages treat "string" as a special data type, but both APL and C treat
- it essentially as an array of characters. Like other arrays it is most commonly
- pointed to rather than passed directly. In this example, a character string and
- a floating point array are passed:
-
- :RARG.(2 G0 ...) (1 G4 ...) (20 S1 ... ) (1 G4 ...) (6 E4 ...)
-
- Because the S1 is subordinate to the first G4, the two of them together count
- for only one of the two items defined by the initial G0.
-
- An argument being passed can also be a structure. Such structures are typically
- pointed to rather than being passed directly. A G0 is used to define the
- structure, but a G4 is also used (as above) to specify the pointer to it.
- Consider a program that expects a single argument, which is a pointer to a
- structure containing an integer and an 8-character name:
-
- :RARG.(1 G0 ...) (1 G4 ...) (2 G0 ...) (1 I4 ... ) (8 C1 ...)
-
- You cannot replace the (1 G4) followed by the (2 G0) with a single (2 G4). (2
- G4) implies two pointers, rather than a single pointer to two items.
-
- Structures can contain pointers to other structures, which are represented by
- G4 entries within the structure definition, or they can contain other
- structures imbedded within them. In the next example, the 8-character name has
- been replaced by a date composed of day (within the month), a 3-character
- abbreviated month name, and a year. The day and year are both expressed as
- 2-byte integers. Assume that the program is expecting the year to start on an
- even-byte boundary, so there is an unused byte in front of it:
-
- :RARG.1 G0... 1 G4... 2 G0... 1 I4... 3 G0... 1 I2... 3 C1... 1 X0... 1 I2...
-
- These examples can help you generate patterns for any interface definition you
- might encounter; except for all those unexplained periods.
-
- The first number after the type descriptor is always the rank as seen by the
- APL program, and is normally set to whatever is most natural for the APL
- programmer. For data entries (all except G0 or G4) this is completely
- determined by the nature of the data.
-
- For G0 entries, this is always a vector (rank 1), except that when a single
- parameter is being passed the first G0 is often more conveniently defined as a
- scalar (rank 0). G4 entries usually represent a single pointer, and can best be
- represented as scalars. The exception is an array of pointers, which is of
- whatever rank is most appropriate to the data (usually rank 1).
-
- Given the rank and the total number of items, you can deduce the shape
- information. Revisiting the examples above, all multi-item pattern descriptors
- are most naturally represented as vectors except for the 6-item floating point
- array, which could be a matrix. It is assumed to be a 2 by 3 matrix below. The
- first example becomes:
-
- :RARG. (G0 1 2) (I4 0) (E4 0)
-
- The numbers used earlier to the left of the type descriptor are optional,
- because they can be computed from the information on the right, so they have
- been omitted here for brevity. Viewed from the APL standpoint this is a 2-item
- vector, each item being a number. APL programs make no distinction between
- integers and floating point numbers, so this is a simple numeric vector (depth
- 1).
-
- The second example (viewed beginning with the G0) is also a 2-item vector, but
- this time the second item is an array. Here is what the completed pattern looks
- like along with sample data for the call:
-
- :RARG.(G0 1 2) (I4 0) (G4 0) (E4 2 2 3)
- 75 (т2 3ц1.2 2.3 3.4 4.3 3.2 2.1)
-
- Note: The array needs to be enclosed because the G4 0 tells APL to expect a
- scalar.
-
- The third example is very similar. Note in the sample data below that only 11
- characters are passed even though the field was defined as 20 bytes long. This
- is permitted for null-terminated strings.
-
- Note: There must be room at the end of the data for the null terminator. So at
- most 19 characters can be passed in this 20-byte string.
-
- For null-delimited strings that are not updated by the non-APL program, there
- is no need to set a specific size ahead of time. Such strings are often defined
- with a length of "*".
-
- :RARG.(G0 1 2) (G4 0) (S1 1 20) (G4 0) (E4 2 2 3)
- func (т'Hello there')(т2 3ц1.2 2.3 3.4 4.3 3.2 2.1)
-
- The G4 implies not only a pointer as seen by the non-APL program, but also a
- level of nesting as seen from APL. But rules in this area can be a bit
- slippery, as the next example shows. Two changes have been introduced: a
- structure and a single parameter. Assume for the moment that the initial G0
- specifies a 1-item vector:
-
- :RARG.(G0 1 1) (G4 0) (G0 1 2) (I4 0) (C1 1 8)
-
- You might want to say that the following is valid data:
-
- 13 'Thomas '
-
- But this is a two-item array, and the pattern calls for a single item. Data
- such as that is appropriate for a routine that expected two arguments rather
- than one, so the data needs to be enclosed. That yields to a scalar value, and
- the pattern calls for a 1-item vector. Thus, given the pattern as assumed,
- correct data is:
-
- :RARG.(G0 1 1) (G4 0) (G0 1 2) (I4 0) (C1 1 8)
- ,тт13 'Thomas '
-
- Now the reason for the earlier comment about a scalar G0 becomes clear. A
- simpler form of the interface is:
-
- :RARG.(G0 0) (G4 0) (G0 1 2) (I4 0) (C1 1 8)
- тт13 'Thomas '
-
- It is typical of single-parameter interfaces that the APL program needs to
- explicitly enclose the data.
-
- A simple case requiring an explicit enclose is that of a routine that accepts a
- pointer to a character string as its only parameter:
-
- :RARG.(G0 0) (G4 0) (S1 1 *)
- тт'string'
-
- Although the first enclose of the character string seems reasonable, because it
- implies "pointer to," the second enclose seems a bit unnatural, and is due to
- the strict conformance to the rule used so far in the examples: The argument
- descriptor is started with a G0 tag that identifies the number of parameters.
-
- In the case of single-parameter arguments, it is often desirable to completely
- elide the (G0 0) descriptor from the :RARG. tags:
-
- :RARG.(G4 0) (S1 1 *)
- т'string'
-
- This simplification is most commonly seen in the case of a single parameter
- that is a simple number. For example:
-
- :RARG.(G0 0) (I4 0)
-
- Is simplified to:
-
- :RARG.I4 0
-
- o Updated Arguments
- o Result Patterns
- o Explicit Results and Function Valence
-
-
- ΓòÉΓòÉΓòÉ 11.2.4.3.1. Updated Arguments ΓòÉΓòÉΓòÉ
-
- Routines in some compiled languages typically do not distinguish between input
- arguments and results. They are passed a list of pointers to the values that
- may represent input arguments, values to be updated, or preallocated space for
- results. APL functions, on the other hand, take arguments that are never
- updated and produce explicit results that were not previously passed as
- arguments to the function. For example:
-
- ΓòûRESULTΓò£COMPUTE ARG
- [1] RESULT╜2їARG
- [2] Γòû
- COMPUTE 10
- 20
-
- APL requires that functions that update argument data in place be called with
- the names of the arguments rather than their values. For example:
-
- ΓòûUPDATE ARG
- [1] пARG,'╜2ї',ARG
- [2] Γòû
- NUMBERΓò£10
- UPDATE 'NUMBER'
- NUMBER
- 20
-
- Both approaches are supported by processor 11. Argument items that are to be
- updated in place are indicated with the symbol > preceding the representation
- type in the argument pattern. For example, a non-APL routine that expects two
- integer vectors as arguments, the second of which is to be updated in place,
- would be described:
-
- :RARG.(G4 1 2) (I4 1 3) (>I4 1 3)
-
- As with APL functions, such routines must be called with the names of the
- arguments to be updated rather than their values:
-
- RESULT╜3ц0
- COMPUTE (1 2 3) 'RESULT'
-
- APL checks to ensure that arguments updated with the > symbol are names and not
- values. If names are not found when the function call occurs, an error results.
- Items that are to be updated must always be passed using a pointer, so there
- must always be a G4 level ahead of any descriptor that contains a ">".
-
- If an external routine misbehaves, for example by writing beyond the end of an
- argument that is able to be updated, workspace damage and possibly SYSTEM ERROR
- may occur. It is essential that valid argument patterns be constructed before
- calling an external function.
-
-
- ΓòÉΓòÉΓòÉ 11.2.4.3.2. Result Patterns ΓòÉΓòÉΓòÉ
-
- The :RSLT. keyword can be specified on routines with an explicit result to
- describe the form of the supplied result.
-
- If supplied, :RSLT. must be specified with a pattern. The pattern takes the
- same form as argument patterns described above, with the following exceptions:
-
- o "*" cannot be used in the pattern.
- o The ">" optional update indicator cannot be used in the pattern.
-
- If the routine produces an explicit result and a :RSLT. keyword is supplied,
- the pattern is used to format the routine's result. If a :RSLT. keyword is not
- supplied, the right argument is returned. The indirect values in the argument
- might have been updated.
-
- If the routine does not produce an explicit result, the :RSLT. keyword is
- ignored.
-
-
- ΓòÉΓòÉΓòÉ 11.2.4.3.3. Explicit Results and Function Valence ΓòÉΓòÉΓòÉ
-
- This section discusses:
-
- o Explicit results
- o Function valence
-
-
- ΓòÉΓòÉΓòÉ 11.2.4.3.3.1. Explicit Results ΓòÉΓòÉΓòÉ
-
- The first value of the :VALENCE. keyword is used to specify whether the routine
- returns an explicit result. This value is used to specify what 1 РAT should
- return when it is used to query the valence of the routine.
-
- If the valence tag specifies that the routine returns an explicit result and no
- :RSLT. tag is supplied, then the right argument is returned as the result. The
- routine may have updated the argument.
-
- If the valence keyword specifies that the routine does not return an explicit
- result, then the :RSLT. keyword is ignored.
-
-
- ΓòÉΓòÉΓòÉ 11.2.4.3.3.2. Function Valence ΓòÉΓòÉΓòÉ
-
- Function valence is controlled by the second value coded in the :VALENCE.
- keyword.
-
- Niladic functions do not accept arguments. If a :RARG. keyword is supplied for
- a niladic routine, it is ignored.
-
- Monadic functions require a :RARG. keyword.
-
-
- ΓòÉΓòÉΓòÉ 11.2.4.4. Array Patterns for ATR, PFA, and RTA ΓòÉΓòÉΓòÉ
-
- ATR, PFA, and RTA
-
- External routines ATR and RTA accept array patterns as arguments, and external
- routine PFA returns an array pattern as its result. See Supplied External
- Routines for the definition of these functions.
-
- The following restrictions apply to patterns used as arguments to these
- routines:
-
- o A G0 descriptor can be used as needed, but the G4 descriptor is not
- supported.
-
- o The ">" optional update indicator is not permitted.
-
- o A single "*" can appear in either the count or shape field if its value can
- be computed from the other field. (count is the product of values in shape.)
-
- Patterns returned by PFA also meet these restrictions, and always have count
- and shape fully specified.
-
-
- ΓòÉΓòÉΓòÉ 12. Supplied External Routines ΓòÉΓòÉΓòÉ
-
- The following external routines are supplied with APL2/2.
-
- o ATR
- o FILE
- o GETENV
- o PFA
- o RTA
-
- The external routines discussed in this chapter are called with processor 11,
- and depend on the default file, aplnm011.nam. For example:
-
- 3 11 РNA 'FILE'
- 1
- AΓò£FILE 'data.bin'
-
- o ATR
- o FILE
- o GETENV
- o PFA
- o RTA
-
-
- ΓòÉΓòÉΓòÉ 12.1. ATR ΓòÉΓòÉΓòÉ
-
- record Γò£ pattern ATR array
-
- This function converts an APL array into a character vector containing
- structured data, based on a pattern that describes the desired format. It can
- be used to map APL arrays into records or structures expected by other
- languages, or expected by services called through AP 145.
-
- array An APL2 array whose structure and data types should be
- compatible with the pattern.
-
- Note: The internal APL storage form need not match the
- pattern exactly, so long as it is possible to convert it to
- the pattern format using APL system tolerance.
-
- pattern A character vector containing a formalized description of the
- fields within the record. Array patterns are defined in Array
- Patterns. The pattern may not contain a * unless it can be
- resolved to an integer based on other information in the item
- description. The pattern may not contain the > or < marks.
-
- record A character vector produced by converting the data in the
- array according to the pattern. DOMAIN ERROR is signalled if
- an impossible conversion is implied by the pattern.
- Incompatible data structures result in LENGTH ERROR or RANK
- ERROR.
-
- Note: External function RTA is the inverse of ATR.
-
-
- ΓòÉΓòÉΓòÉ 12.2. FILE ΓòÉΓòÉΓòÉ
-
- data Γò£ FILE filespec
- rc Γò£ data FILE filespec
-
- This function reads or writes a system file in binary mode. The monadic form
- reads a file, while the dyadic form writes it. FILE is a stream read/write
- function. It is not record-oriented, and it does not perform data conversion.
-
- filespec A character vector that identifies a file. It may be a simple
- file name, or may include a path specification.
-
- data The content of the file as a simple character vector. Any
- line or record separators are retained as they existed in the
- file.
-
- Any error conditions encountered while reading a file are
- reported by returning a numeric result in place of the data.
-
- rc The return code from writing a file; normally zero. Nonzero
- return codes are system dependent.
-
- Hint You can use the APL membership (ю) and partition (т) functions to parse
- an ASCII text file into a vector of vectors.
-
-
- ΓòÉΓòÉΓòÉ 12.3. GETENV ΓòÉΓòÉΓòÉ
-
- vector Γò£ GETENV env_variable
-
- This function returns the value of an environment variable as a character
- vector.
-
- env_variable An enclosed character vector that identifies the environment
- variable. Depending on the platform, environment variable
- names can be case sensitive. For maximum application
- portability, use the exact case for the name of the
- environment variable.
-
- vector An enclosed character vector that represents the value of the
- environment variable. If the environment variable is not set,
- then vector is ть0.
-
-
- ΓòÉΓòÉΓòÉ 12.4. PFA ΓòÉΓòÉΓòÉ
-
- pattern Γò£ PFA array
-
- This function creates an array pattern from an array.
-
- array Any APL array.
-
- pattern A character vector containing a formalized description of the
- fields within the record. Array patterns are defined in Array
- Patterns. The patterns produced by PFA always contain the
- optional parentheses and the count field. They never contain
- the > or < markers or an *.
-
- PFA may be used as a tutorial on how to write patterns. Because the types
- selected in the pattern reflect the internal storage mechanism in use at the
- moment, the same array may give different patterns at different times or on
- different platforms.
-
-
- ΓòÉΓòÉΓòÉ 12.5. RTA ΓòÉΓòÉΓòÉ
-
- array Γò£ pattern RTA record
-
- This function converts a character vector containing structured data into an
- APL array, based on a pattern that describes the format of the data. It can be
- used to map records or structures produced by other languages, or expected by
- services called through AP 145, into APL arrays of any required depth.
-
- record A character vector containing data in the form that it was
- stored by some other program. No check is made for incorrect
- lengths. The result is unpredictable if the record is shorter
- than the structure described in the pattern.
-
- pattern A character vector containing a formalized description of the
- fields within the record. Array patterns are defined in Array
- Patterns. The pattern may not contain an asterisk (*) unless
- it can be resolved to an integer based on other information
- in the item description. The pattern may not contain the > or
- < marks.
-
- array An APL2 array whose format is determined by the pattern, and
- whose content is taken from the record.
-
- Note: External function ATR is the inverse of RTA.
-
-
- ΓòÉΓòÉΓòÉ 13. Supplied Workspaces ΓòÉΓòÉΓòÉ
-
- IBM APL2/2 supplies a number of workspaces to perform various tasks, and many
- of these are common to other supported APL2 environments. These workspaces
- contain functions that you can call from your programs. The functions listed
- can also be used as examples of how to program with the corresponding auxiliary
- processors in the APL2/2 system. For example:
-
- o FILE uses the file auxiliary processors (AP 210 and AP 211)
-
- o The OS2 workspace uses the OS/2 host command auxiliary processor (AP 100)
-
- o The DEMO124 workspace demonstrates some of the capabilities of the
- full-screen auxiliary processor (AP 124)
-
- o The DEMO145 workspace demonstrates some of the capabilities of the OS/2
- services auxiliary processor (AP 145)
-
- o The DEMO207 workspace demonstrates some of the capabilities of the Universal
- Graphics auxiliary processor (AP 207)
-
- o The EDIT and EDITOR_2 functions in the EDIT workspace and the AP124 workspace
- use the text display auxiliary processor (AP 124)
-
- Each public workspace contains variables with information about the workspace.
- These variables are: ABSTRACT, DESCRIBE, and HOW.
-
- The workspaces distributed with APL2/2 are assigned to either library 1 or
- library 2, as is shown in Workspace Library Assignments.
-
- o The AP124 Workspace
- o The DEMO124 Workspace
- o The DEMO145 Workspace
- o The DEMO207 Workspace
- o The DISPLAY Workspace
- o The EDIT Workspace
- o The EXAMPLES Workspace
- o The FILE Workspace
- o The GRAPHPAK Workspace
- o The IDIOMS Workspace
- o The MATHFNS Workspace
- o The MIGRATE Workspace
- o The OS2 Workspace
- o The PMTOOLS Workspace
- o The PMWIN Workspace
- o The PRINTWS Workspace
- o The SQL Workspace
- o The TIME Workspace
- o The UTILITY Workspace
-
-
- ΓòÉΓòÉΓòÉ 13.1. Workspace Library Assignments - Part 1 ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Name
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Library Number
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Function
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- AP124
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 2
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Aids in building text display applications
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- DEMO124
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 2
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Demonstrations of some of the capabilities of the text display auxiliary
- processor (AP 124)
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- DEMO145
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 2
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Demonstrations of some of the capabilities of the OS/2 services auxiliary
- processor (AP 145)
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- DEMO207
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 2
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Demonstrations of some of the capabilities of the universal graphics auxiliary
- processor (AP 207)
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- DISPLAY
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 1
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Display of array data structure
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- EDIT
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 1
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Compatibility editors
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- EXAMPLES
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 1
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Usage examples of APL2
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- FILE
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 2
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Tools for accessing OS/2 files
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- MORE...
-
-
- ΓòÉΓòÉΓòÉ 13.2. Workspace Library Assignments - Part 2 ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Name
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Library Number
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Function
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- GRAPHPAK
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 2
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Business and analytic graphics
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- IDIOMS
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 1
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Catalog of common APL2 phrases
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- MATHFNS
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 1
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Mathematical functions
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- MIGRATE
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 2
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Conversion of applications migrated from other systems
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- OS2
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 2
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Tools to access OS/2 functions, commands, or files
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- PMTOOLS
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 2
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- A toolkit for writing OS/2 Presentation Manager applications
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- PMWIN
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 2
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- A collection of variables with the values defined in the OS/2 Developer's
- Toolkit header files
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- PRINTWS
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 2
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Printing workspace contents
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- SQL
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 2
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Tools for using relational database auxiliary processors
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- TIME
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 1
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Monitor performance
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- UTILITY
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 1
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Manipulations and services beyond those provided by primitive operations
-
-
- ΓòÉΓòÉΓòÉ 13.3. The AP124 Workspace ΓòÉΓòÉΓòÉ
-
- This workspace contains a set of cover functions to assist in the use of the
- text display auxiliary processor, AP 124, in an application. A screen
- definition facility makes it possible to define a screen as a set of fields,
- each one with its own name or number, where information can be sent or
- retrieved by means of appropriate functions.
-
- o Fundamentals
- o Building a Menu
- o Primary Functions
- o Additional Functions
- o AP124 Internal Operation and Global Variables
-
-
- ΓòÉΓòÉΓòÉ 13.3.1. Fundamentals ΓòÉΓòÉΓòÉ
-
- The window you are using on your display should be regarded as a character
- array for the purposes of the following discussion.
-
- The size of this array defaults to 25 by 80, but the window can be resized
- using normal OS/2 Desktop facilities. This area can be subdivided into smaller
- rectangular sections that are more convenient to your data processing needs.
- These rectangular areas are called fields. The text display auxiliary
- processor, AP 124, works only in terms of fields. Functions in the AP124
- workspace perform actions to a field or a group of fields.
-
- Every field has a type, which determines how it can be acted upon. There are
- three basic types of fields:
-
- Input/output Allowing input from the keyboard to be typed and displayed
-
- Numeric input only/any output Allowing only numbers to be input from the
- keyboard, but allowing any characters to be displayed
-
- Output only Capable of receiving data from an APL2 function but not from the
- keyboard.
-
- Fields also have attributes that define how the information contained in the
- fields is to be displayed. An attribute is expressed as an integer value,
- depending on the actual display to be used, and defines the color of the field.
-
-
- ΓòÉΓòÉΓòÉ 13.3.2. Building a Menu ΓòÉΓòÉΓòÉ
-
- As an example of the use of the AP124 workspace, a sample screen is defined,
- containing some information and requesting data from a user. The AP124
- workspace includes functions enabling you to define menus quickly, and making
- it easy to maintain them.
-
- Assume the menu you wish to define is for an overtime payment system. You
- should collect and process the following data:
-
- o Employee serial number
- o Employee name
- o Number of overtime hours worked each day (Monday to Sunday)
- o Per-day overtime rate. This is fixed at the moment, but can be adjusted at a
- later date.
-
- Now we have to step though some simple decisions to design the screen. The
- following is a representation of the desired menu:
-
- 00000000011111111112222222222333333333344444444445555555555666666666677777777778
- 12345678901234567890123456789012345678901234567890123456789012345678901234567890
- 01 APL2 Overtime System
- 02--------------------------------------------------------------------------------
- 03
- 04
- 05 Input the following data, press Enter:
- 06
- 07 Employee Number XXXXXXX
- 08 Employee Name XXXXXXXXXXXXXXX
- 09
- 10 Mon Tue Wed Thu Fri Sat Sun
- 11 Hours X.XX X.XX X.XX X.XX X.XX X.XX X.XX
- 12 Rate 1.25 1.25 1.25 1.25 1.25 1.50 2.00
- 13
- 14
- 15
- 16
- 17
- 18
- 19
- 20--------------------------------------------------------------------------------
- 21 The following options can also be used:
- 22
- 23 F1 - Help F3 - Exit
- 24
- 25
-
- The row and column numbers at the top and left of the diagram are included just
- for clarity.
-
- A name is needed for the screen. Use the name OVERTIME.
-
- Now that everything is planned and ready, we will look at the AP124 workspace
- functions we need to build the menu.
-
- o FSDEF - Define fields
- o FSSHOW - Display a panel
-
-
- ΓòÉΓòÉΓòÉ 13.3.2.1. FSDEF - Define fields ΓòÉΓòÉΓòÉ
-
- FSDEF 'Menu_Name'
-
- the first time it is used, and:
-
- Field_Def FSDEF 'Field_Data'
-
- once per field to be defined.
-
- Menu_Name defines the name by which this screen is to be known. This name
- should begin with an uppercase or lowercase letter, the delta (Γòó) character or
- the delta underbar (ў) character; it can continue with any of these, plus the
- digits 0-9, overbar (¤) or underbar (_).
-
- Field_Def is a vector containing four, five, or six elements with the following
- information:
-
- 1. Start row of the field
-
- 2. Start column of the field
-
- 3. Field height
-
- 4. Field width
-
- The fifth and sixth elements of the vector are optional, and are defined
- as:
-
- 5. Field type:
-
- 0 - Input/output/selectable
- 1 - Numeric input only/any output/selectable
- 2 - Output only (the default)
- 3 - Output only/selectable
-
- 6. Field Attribute: an integer between 0 and 255. The default field attribute
- is 1, which normally gives blue characters on a black background. The
- following diagram shows the meanings of the bits of the display attribute
- byte on color display adapters:
-
- 7 6 5 4 3 2 1 0
- ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
- Γöé Γöé
- Γöé ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ Foreground color (4 bits)
- Γöé
- ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ Background color (4 bits)
-
- The combinations of colors available are: See AP 124 colors.
-
- If the field width is given as 0, the width is automatically derived from the
- value of Field_Data. This is the data to be written on the field at initial
- menu usage. It must be a character vector.
-
- Alternatively, the following field definition format can be used to assign a
- name to the field being defined:
-
- Field_Def FSDEF 'Field_Name' FSDEF 'Field_Data'
-
- Field_Def and Field_Data are the same as above. Field_Name is the name you wish
- to assign to this field. This name should consist of upper or lowercase
- letters, digits, delta (╢), delta underbar (ў), overbar (¤) or underbar (_).
-
- You can also use FSDEF to define a group of fields so that they can be referred
- to collectively. This is especially useful for reading or writing a set of
- fields or for changing the attribute of a complete set of fields, or for
- switching the type of a set of fields from input/output to output only, or vice
- versa. This is done in the following way:
-
- 'Group_Name' FSDEF Number_of_Fields
-
- Number_of_Fields is the number of fields defined immediately before the
- execution of this line that are to be included in the group. You can define
- nonconsecutive fields as a group of fields by issuing this call with the same
- group name after each individual field or after each consecutive group of
- fields. Groups must be exclusive. Each field can be defined as being in only
- one group.
-
- If workspace is at a premium, any repeated items in the screen definition
- variables can be converted to aliases of the first unique occurrence of each
- item by using FSDEF with an empty character right argument:
-
- FSDEF ''
-
- You can use this after each (or the last) menu is defined, and after you have
- copied menus into the active workspace, using the )IN, )PIN, )COPY, or )PCOPY
- system commands.
-
-
- ΓòÉΓòÉΓòÉ 13.3.2.1.1. AP 124 colors ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Code
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Bits
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Color
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Code
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Bits
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Color
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 0
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 0 0 0 0
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Black
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 8
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 1 0 0 0
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Light Gray
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 1
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 0 0 0 1
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Blue
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 9
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 1 0 0 1
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Light Blue
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 2
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 0 0 1 0
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Green
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 10
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 1 0 1 0
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Light Green
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 3
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 0 0 1 1
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Cyan
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 11
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 1 0 1 1
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Light Cyan
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 4
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 0 1 0 0
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Red
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 12
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 1 1 0 0
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Light Red
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 5
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 0 1 0 1
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Magenta
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 13
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 1 1 0 1
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Light Magenta
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 6
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 0 1 1 0
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Yellow
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 14
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 1 1 1 0
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Brown
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 7
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 0 1 1 1
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Gray
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 15
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 1 1 1 1
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- White
-
-
- ΓòÉΓòÉΓòÉ 13.3.2.2. FSSHOW - Display a panel ΓòÉΓòÉΓòÉ
-
- FSSHOW 'Menu_Name'
-
- FSSHOW can be used to display a menu after it has been completely defined.
-
- The following example is a function written to define our sample menu and
- display it on the screen.
-
- Γòû
- [0] DEFINE;A
- [1] FSDEF 'OVERTIME'
- [2] 1 30 1 20 2 7 FSDEF 'APL2 Overtime System'
- [3] 2 1 1 80 2 7 FSDEF 80ц'-'
- [4] AΓò£'Input the following data, press Enter:'
- [5] 5 21 1 0 2 7 FSDEF 'PROMPT' FSDEF A
- [6] 7 24 1 16 2 7 FSDEF 'Employee Number'
- [7] 8 24 1 16 2 7 FSDEF 'Employee Name'
- [8] 7 42 1 7 0 7 FSDEF 'Emp_No' FSDEF ''
- [9] 8 42 1 15 0 7 FSDEF 'Emp_Name' FSDEF ''
- [10] AΓò£'Mon Tue Wed Thu Fri Sat Sun'
- [11] 10 27 1 0 2 7 FSDEF A
- [12] 11 21 1 0 2 7 FSDEF 'Hours'
- [13] 12 21 1 0 2 7 FSDEF 'Rate'
- [14] 11 27 1 4 0 7 FSDEF 'Hours_Mon' FSDEF ''
- [15] 11 32 1 4 0 7 FSDEF 'Hours_Tue' FSDEF ''
- [16] 11 37 1 4 0 7 FSDEF 'Hours_Wed' FSDEF ''
- [17] 11 42 1 4 0 7 FSDEF 'Hours_Thu' FSDEF ''
- [18] 11 47 1 4 0 7 FSDEF 'Hours_Fri' FSDEF ''
- [19] 11 52 1 4 0 7 FSDEF 'Hours_Sat' FSDEF ''
- [20] 11 57 1 4 0 7 FSDEF 'Hours_Sun' FSDEF ''
- [21] 'Hours' FSDEF 7
- [22] 12 27 1 4 0 7 FSDEF 'Rate_Mon' FSDEF '1.25'
- [23] 12 32 1 4 0 7 FSDEF 'Rate_Tue' FSDEF '1.25'
- [24] 12 37 1 4 0 7 FSDEF 'Rate_Wed' FSDEF '1.25'
- [25] 12 42 1 4 0 7 FSDEF 'Rate_Thu' FSDEF '1.25'
- [26] 12 47 1 4 0 7 FSDEF 'Rate_Fri' FSDEF '1.25'
- [27] 12 52 1 4 0 7 FSDEF 'Rate_Sat' FSDEF '1.50'
- [28] 12 57 1 4 0 7 FSDEF 'Rate_Sun' FSDEF '2.00'
- [29] 'Rates' FSDEF 7
- [30] 18 21 1 40 2 7 FSDEF 'Msg_Area' FSDEF ''
- [31] 20 1 1 80 2 7 FSDEF 80ц'-'
- [32] AΓò£'The following options can also be used:'
- [33] 21 10 1 0 2 7 FSDEF A
- [34] AΓò£'F1 - Help F3 - Exit'
- [35] 23 23 1 0 2 7 FSDEF A
- [36] FSDEF ''
- [37] FSSHOW 'OVERTIME'
- Γòû
-
- Notice that some of the fields have been named. These are the ones the example
- operates with. Also observe that an extra field, called Msg_Area, has been
- defined, where the program can output any errors found in input validation, or
- any other system message.
-
- Ordinarily a function is written like this for each panel in the system. Each
- of these panel definition functions then needs to be executed only once in
- order to create the global variables that are used by other functions in this
- workspace. (They would have to be re-executed if you change the panels by
- editing the appropriate panel definition function.)
-
-
- ΓòÉΓòÉΓòÉ 13.3.3. Primary Functions ΓòÉΓòÉΓòÉ
-
- Look at the next stage of combining the screen with the function that drives
- the input-output operation (a "driver"). The following cover functions can be
- used in the driver:
-
- o FSUSE - Initialize a panel
- o FSSETCURSOR - Position the cursor
- o FSWRITE - Put data into fields
- o FSWAIT - Wait for a user response
- o FSREAD/FSREADV - Read field contents
-
-
- ΓòÉΓòÉΓòÉ 13.3.3.1. FSUSE - Initialize a panel ΓòÉΓòÉΓòÉ
-
- ZΓò£FSUSE 'Menu_Name'
-
- This function initializes the menu named Menu_Name. This is the basic call used
- to allow you to start using a menu. It shares variables with AP124, loads the
- indicated predefined menu, and leaves you ready to use it. The result is 0 if
- successful, 1 if the function failed.
-
-
- ΓòÉΓòÉΓòÉ 13.3.3.2. FSSETCURSOR - Position the cursor ΓòÉΓòÉΓòÉ
-
- ZΓò£Cursor_Offset FSSETCURSOR Field
-
- This call sets the cursor in a specific field or at any position on the screen.
- The left argument can be omitted, and the cursor offset is defaulted to the
- first position in that field. Field can be either a character vector containing
- the name you selected for the field during definition of the menu, or an
- integer field number. The result is 0 if successful, 1 if the function failed.
-
-
- ΓòÉΓòÉΓòÉ 13.3.3.3. FSWRITE - Put data into fields ΓòÉΓòÉΓòÉ
-
- ZΓò£Data FSWRITE Field
-
- This function writes Data to the field or fields identified by Field. Field can
- be either a character scalar or vector to identify a single field, or a
- character matrix of names or a vector of names to identify several fields.
- Field can also be a numeric scalar or a vector of field numbers. If one field
- is being written, Data should be a character scalar, a vector, or a one-row
- matrix. If more than one field is being written, Data must be a character
- matrix with the corresponding number of rows or a vector of character arrays
- with the corresponding number of elements. The result is 0 if successful, 1 if
- the function failed.
-
-
- ΓòÉΓòÉΓòÉ 13.3.3.4. FSWAIT - Wait for a user response ΓòÉΓòÉΓòÉ
-
- ZΓò£FSWAIT
-
- This function displays the active menu, and waits for user input. When a user
- presses a certain key (see below), control returns to APL2, and the result, Z,
- of function FSWAIT is the following:
-
- o Z[1] - Return code: 0 if successful, otherwise 1.
-
- o Z[2 3] - Key pressed to complete the call:
-
- 0 0 - Enter
- 1 n - An F Key, where n is the key number (1 to 48)
- 4 1 - Esc
- 6 1 - Home
- 6 2 - End
- 6 3 - PageUp
- 6 4 - PageDown
- 6 5 - Ctrl-PageUp
- 6 6 - Ctrl-PageDown
- 6 7 - Ctrl-Left
- 6 8 - Ctrl-Right
- 6 9 - Ctrl-Up
- 6 10 - Ctrl-Down
-
- o Z[4] - Field number where cursor was located at return to APL2, or zero if
- it was outside all the fields.
-
- o Z[5 6] - Cursor offset (row/column) into that field. If field was zero, then
- offset is from the top-left corner of the screen.
-
- o Z[7...] - List of fields updated during this FSWAIT request.
-
- The list of updated fields that is returned enables you to optimize the panel
- processing time. In general, it is necessary to read and validate only those
- fields, rather than to read back and check all of the fields, which, for a very
- large screen, could be a very long process.
-
-
- ΓòÉΓòÉΓòÉ 13.3.3.5. FSREAD/FSREADV - Read field contents ΓòÉΓòÉΓòÉ
-
- ZΓò£FSREAD Field
-
- This function reads data from the field or fields identified by Field. Field
- can be either a character scalar or vector to identify a single field, or a
- character matrix of names or a vector of names to identify several fields.
- Field can also be a numeric scalar or a vector of field numbers.
-
- If the result, Z, is numeric, it is a return code indicating that the operation
- has failed. Otherwise, Z is a character matrix containing the requested field
- data.
-
- ZΓò£FSREADV Field
-
- This function reads data from a field or a group of fields. If the result is
- numeric, it is a return code indicating that the operation failed. Otherwise,
- the result is a nested vector of character or numeric arrays containing the
- requested field or group field data.
-
-
- ΓòÉΓòÉΓòÉ 13.3.4. Additional Functions ΓòÉΓòÉΓòÉ
-
- The following functions assist in the use of the screen.
-
- ZΓò£FSAPLOFF
- ZΓò£FSAPLON
-
- FSAPLOFF and FSAPLON turn the keyboard from APL2 to National mode (FSAPLOFF),
- and vice versa (FSAPLON). The result is 0 if successful, 1 if the function
- failed.
-
- ZΓò£FSBEEP
-
- FSBEEP sets the beep flag. A beep sounds at the next read and wait call
- (FSWAIT). The result is 0 if successful, 1 if the function failed.
-
- ZΓò£FSCLEAR
-
- Clears the display. The result is 0 if successful, 1 if the function failed.
-
- ZΓò£FSCLOSE
-
- FSCLOSE retracts the AP124 shared variables and expunges all global variables
- associated with the AP124 full-screen functions (except the 'fsf',Name panel
- definition variables). It should be used at the end of your session. The result
- is 0 if successful, 1 if the function failed.
-
- ZΓò£FSCOPY
-
- Returns the current screen contents as a matrix.
-
- ZΓò£FSFIELD Field_Name
- ZΓûáFSFIELD Field_Number
-
- This function translates a field name to the corresponding field number, or
- vice versa.
-
- ZΓò£FSFORMAT
-
- Returns, in Z, the active format array. If this is used immediately after an
- FSOPEN, it returns a format array of one field completely covering the screen.
- You can use this to determine how many rows and columns are available for
- display on the screen.
-
- ZΓò£FSINKEY
-
- Returns the next keyboard scan code. The result is a 6-element vector like the
- first 6 elements returned by FSWAIT, except that if the second element is zero
- then the third element may be either zero (for the Enter or New-line key), or
- any of the codes shown in AP 124 Extended Function Codes, and if the third
- element is zero then the second element may be either zero (for the Enter or
- New-line key), or a 0-origin РAV index of the character entered.
-
- ZΓò£Data FSIWRITE Field
-
- Immediate write of Data to the selected fields on the display. It is used in
- the same way as the FSWRITE function, described in FSWRITE - Put data into
- fields.
-
- ZΓò£FSMODE 'mode'
-
- Clears the screen and establishes display mode indicated (APL2/PC
- compatibility). The result is 0 if successful, 1 if the function failed.
-
- ZΓò£FSOPEN
-
- Shares variables with AP124. This function is used internally by FSUSE. The
- result is 0 if successful, 1 if the function failed.
-
- ZΓò£FSSCAN
-
- Scan for a key pressed. The result is a 6-element vector like that returned by
- FSINKEY, except that if no key had been pressed, Z[2 3] will be ¤1 ¤1.
-
- ZΓò£FSSCREEN
-
- Return the contents of the screen.
-
- ZΓò£A FSSETFI Field
-
- Changes the attribute of a field or a group of fields to A. The result is 0 if
- successful, 1 if the function failed.
-
- ZΓò£T FSSETFT Field
-
- Changes the type of a field or a group of fields to T. The result is 0 if
- successful, 1 if the function failed.
-
- ZΓò£FSSTATUS
-
- Returns the status of the session:
-
- Z[1] - Return code of the AP124 status call (normally 0)
- Z[2] - Keyboard mode (0 = national mode, 1 = APL2 mode)
- Z[3] - Reserved; always 0
- Z[4] - Reserved; always 1
- Z[5] - Beep request pending (1 = beep pending)
- Z[6] - Reserved; always 0
- Z[7] - Cursor mode (0 = normal, 1 = field)
-
- ZΓò£FSTITLE Title
-
- Sets the title bar on the AP 124 window to the character string named in Title.
- The result is 0 if successful, 1 if the function failed.
-
- Note: The title bar cannot be set until after at least one field has been
- formatted (FSUSE or FSSHOW functions).
-
- o Example Driver Function
-
-
- ΓòÉΓòÉΓòÉ 13.3.4.1. Example Driver Function ΓòÉΓòÉΓòÉ
-
- The following is an example of a driver function that uses the menu defined
- above:
-
- [0] DRIVER;R;A
- [1] Γòò(FSOPEN)/E124
- [2] Γòò(FSUSE 'OVERTIME')/E124
- [3] Γòò(FSSETCURSOR 'Hours_Mon')/E124
- [4] ASK:Γòò(Γò₧RΓò£FSWAIT)/E124
- [5] Γòò(1=R[2])/FK
- [6] ф Examine fields changed
- [7] ф These are listed by 6╟R
- [8] AΓò£FSREAD 'Emp_No' 'Emp_Name' 'Hours' 'Rates'
- [9] ....
- [..] FK:....
- [..] E124:'Full-screen error in driver'
-
-
- ΓòÉΓòÉΓòÉ 13.3.5. AP124 Internal Operation and Global Variables ΓòÉΓòÉΓòÉ
-
- The FSOPEN function shares variables called Cfs and Dfs with AP124. It also
- creates a two-element numeric variable, called fss, containing the number of
- rows and columns that can be displayed.
-
- The FSDEF function creates a screen definition variable with the name
- 'fsf',Name, where Name is the menu name. The screen definition is stored as a
- three- or four-column nested matrix with one row for each field defined. The
- columns are:
-
- 1. Field format (six-element numeric vector)
- 2. Field contents (character vector)
- 3. Field name (character vector-empty vector for no name)
- 4. Group name that this field belongs to (character vector-empty vector if not
- defined as a group member). This column is not present if no groups are
- defined.
-
- The FSUSE function calls FSOPEN if the AP124 variables are not already shared,
- and then copies the group definition 'fsf',Name to variable fsf. It also adds
- an extra column to fsf containing the field numbers for each group definition.
-
-
- ΓòÉΓòÉΓòÉ 13.4. The DEMO124 Workspace ΓòÉΓòÉΓòÉ
-
- This workspace is designed to give the user a sample of the capabilities of the
- AP 124 auxiliary processor.
-
- The demonstration provides an online reference to the various calls to AP 124,
- and shows some sample applications.
-
- The demonstration can be run by entering:
-
- )LOAD 2 DEMO124
- DEMO
-
-
- ΓòÉΓòÉΓòÉ 13.5. The DEMO145 Workspace ΓòÉΓòÉΓòÉ
-
- This workspace contains functions that demonstrate the use of AP 145, the OS/2
- services processor.
-
- The demonstration illustrates how to use the dialog functions from the PMTOOLS
- workspace to process Presentation Manager dialogs. The demonstration also
- illustrates using the APL2 print object cover functions from PMTOOLS.
-
- The demonstration can be run by entering:
-
- )LOAD 2 DEMO145
- DEMO
-
-
- ΓòÉΓòÉΓòÉ 13.6. The DEMO207 Workspace ΓòÉΓòÉΓòÉ
-
- This workspace is designed to give the user a sample of the capabilities of the
- Universal Graphics auxiliary processor, AP 207.
-
- The demonstration provides an online view of text characters in various sizes
- and orientations. It displays various geometric shapes that can be used in
- business graphics along with the possible colors and symbols available. An
- image is also displayed as part of the demonstration.
-
- The demonstration can be run by entering:
-
- )LOAD 2 DEMO207
- DEMO
-
-
- ΓòÉΓòÉΓòÉ 13.7. The DISPLAY Workspace ΓòÉΓòÉΓòÉ
-
- This workspace contains DISPLAY, DISPLAYC, and DISPLAYG, which are functions
- useful in showing the structure of nested and mixed arrays.
-
- ZΓò£DISPLAY X
- ZΓò£DISPLAYC X
- ZΓò£DISPLAYG X
-
- Z is a character matrix representing the array X.
-
- DISPLAY and DISPLAYG use box characters. DISPLAYG is identical to DISPLAY and
- is included for compatibility with the DISPLAY workspace distributed with
- APL2/370. DISPLAYC uses characters that display on all implementations. This is
- functionally equivalent to the DISPLAY function in the APL2/370 DISPLAY
- workspace.
-
- The following characters are used to convey shape information:
-
- Γòò or Γòƒ Indicates a dimension of at least one.
- щ or ш Indicates an axis of length zero. If an array is empty,
- its prototype is displayed.
- (None of the above) Indicates no dimension (a rank 0 array).
-
- The following characters are used to convey type information:
-
- ~ Indicates numeric.
- + Indicates mixed.
- ю Indicates nested.
- _ Indicates a scalar character that is at the same depth
- as nonscalar arrays.
- (None of the above) Indicates a character array that is not a simple scalar.
-
- To use each of the DISPLAY functions:
-
- )PCOPY 1 DISPLAY DISPLAY DISPLAYC DISPLAYG
- SAVED ...
- (DISPLAY ь5) (DISPLAYC ь5) (DISPLAYG ь5)
- ΓöîΓòòΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ .Γòò--------. ΓöîΓòòΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
- Γöé1 2 3 4 5Γöé Γöé1 2 3 4 5Γöé Γöé1 2 3 4 5Γöé
- Γöö~ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ '~--------' Γöö~ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
-
- X╜ть5
- (DISPLAY X) (DISPLAYC X) (DISPLAYG X)
- ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ .-------------. ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
- Γöé ΓöîΓòòΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ Γöé Γöé .Γòò--------. Γöé Γöé ΓöîΓòòΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ Γöé
- Γöé Γöé1 2 3 4 5Γöé Γöé Γöé Γöé1 2 3 4 5Γöé Γöé Γöé Γöé1 2 3 4 5Γöé Γöé
- Γöé Γöö~ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ Γöé Γöé '~--------' Γöé Γöé Γöö~ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ Γöé
- └ю────────────┘ 'ю------------' └ю────────────┘
-
- X╜(тть4)(2 2ц'ABCD')(2 2ц'42' 'IS' 'THE' 'ANSWER')
- DISPLAY X
- ΓöîΓòòΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
- Γöé ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ ΓöîΓòòΓöÇΓöÉ ΓöîΓòòΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ Γöé
- Γöé Γöé ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ Γöé ΓòƒABΓöé Γòƒ ΓöîΓòòΓöÇΓöÉ ΓöîΓòòΓöÇΓöÉ Γöé Γöé
- Γöé Γöé Γöé ΓöîΓòòΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ Γöé Γöé ΓöéCDΓöé Γöé Γöé42Γöé ΓöéISΓöé Γöé Γöé
- Γöé Γöé Γöé Γöé1 2 3 4Γöé Γöé Γöé ΓööΓöÇΓöÇΓöÿ Γöé ΓööΓöÇΓöÇΓöÿ ΓööΓöÇΓöÇΓöÿ Γöé Γöé
- Γöé Γöé Γöé Γöö~ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ Γöé Γöé Γöé ΓöîΓòòΓöÇΓöÇΓöÉ ΓöîΓòòΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ Γöé Γöé
- │ │ └ю──────────┘ │ │ │THE│ │ANSWER│ │ │
- │ └ю──────────────┘ │ └───┘ └──────┘ │ │
- │ └ю───────────────┘ │
- └ю──────────────────────────────────────────┘
-
- цX
- 3
- ц■X
- 2 2 2 2
- DISPLAY ц■X
- ΓöîΓòòΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
- │ ┌щ┐ ┌╕──┐ ┌╕──┐ │
- Γöé Γöé0Γöé Γöé2 2Γöé Γöé2 2Γöé Γöé
- Γöé Γöö~Γöÿ Γöö~ΓöÇΓöÇΓöÿ Γöö~ΓöÇΓöÇΓöÿ Γöé
- └ю────────────────┘
-
- DISPLAYC X
- .Γòò------------------------------------------.
- Γöé .---------------. .Γòò-. .Γòò---------------. Γöé
- Γöé Γöé .-----------. Γöé ΓòƒABΓöé Γòƒ .Γòò-. .Γòò-. Γöé Γöé
- Γöé Γöé Γöé .Γòò------. Γöé Γöé ΓöéCDΓöé Γöé Γöé42Γöé ΓöéISΓöé Γöé Γöé
- Γöé Γöé Γöé Γöé1 2 3 4Γöé Γöé Γöé '--' Γöé '--' '--' Γöé Γöé
- Γöé Γöé Γöé '~------' Γöé Γöé Γöé .Γòò--. .Γòò-----. Γöé Γöé
- │ │ 'ю----------' │ │ │THE│ │ANSWER│ │ │
- │ 'ю--------------' │ '---' '------' │ │
- │ 'ю---------------' │
- 'ю------------------------------------------'
-
- цX
- 3
- ц■X
- 2 2 2 2
- DISPLAY ц■X
- .Γòò----------------.
- │ .щ. .╕--. .╕--. │
- Γöé Γöé0Γöé Γöé2 2Γöé Γöé2 2Γöé Γöé
- Γöé '~' '~--' '~--' Γöé
- 'ю----------------'
-
-
- ΓòÉΓòÉΓòÉ 13.8. The EDIT Workspace ΓòÉΓòÉΓòÉ
-
- This workspace contains two alternative editors.
-
- o EDIT
- o EDITOR_2 (APL2/370-Compatible Full-Screen Editor)
-
-
- ΓòÉΓòÉΓòÉ 13.8.1. EDIT ΓòÉΓòÉΓòÉ
-
- This is a simple, limited-function APL2 full-screen editor for editing defined
- functions and operators. It uses the text display auxiliary processor, AP 124.
-
- This editor can be used to create new defined functions or operators and to
- modify existing ones.
-
- To edit an APL2 function or operator with the editor, copy the EDIT workspace
- into your active workspace with the command:
-
- )PCOPY 1 EDIT EDIT
-
- If the name of the function you want to create or edit is FN1, enter:
-
- EDIT 'FN1'
-
- After you invoke the editor, a window pops up and the function is displayed-or
- as much of it as can fit into the available screen area. Up to 24 lines of the
- function or operator are displayed; one line is reserved for definitions of
- function keys.
-
- You can now move the cursor, using the four arrow keys on the numeric keypad,
- change any character in the lines displayed, insert characters (with the Ins
- key), delete characters (with the Del key), delete to the end of a line (with
- the Ctrl-End key combination), delete to the beginning of a line (with the
- Ctrl-Home key combination), and move the cursor to the beginning of the next
- line (by pressing the Tab key). Also, you can use the function keys as
- indicated in the lowest line of the screen. The full purpose of these, and
- other special keys, is described below:
-
- F3 QUIT - Cancels function definition. No changes are kept. The function
- remains as it was at the beginning of the edit session. If you have
- made changes, you are prompted to confirm the intention to quit.
-
- F4 FILE - Ends function definition. All modifications to the function
- are kept and the new definition of the function is established in the
- active workspace. If this process fails, the bottom line of the
- display is updated with an error message to indicate the line number
- found to be in error.
-
- F5 TOP - Displays the first or top page of the function.
-
- F6 BOT - Displays the last or bottom portion of the function, with room
- to add additional lines.
-
- F7 LINE - Clears the screen and displays only the line pointed to by the
- current cursor position. You can use this to edit lines longer than
- the screen width. The maximum line length this method allows is 800
- characters.
-
- F8 INS - Inserts a new line after the current cursor position.
-
- Shift-F8 DEL - Deletes the line pointed to by the cursor.
-
- F9 EXEC - Executes the line pointed to by the cursor. The line is
- executed under the control of РEA, so that any error that occurs does
- not suspend the execution of EDIT.
-
- F10 COPY - Copies a line. Move the cursor to the line you want to be
- copied, and press F10. The F10 definition on the bottom line of the
- screen is now highlighted. The system is now in "copy" state. Then
- move the cursor to the line after which the indicated line is to be
- copied (possibly on another page). Finally, press F10 again to cause
- the copy to take place. The highlighting of the F10 definition is
- then removed, and the system is no longer in "copy" state.
-
- All other function keys are ignored.
-
- Other Special Keys:
-
- Tab Moves the cursor to the beginning of the next line.
-
- Shift-Tab Moves the cursor to the beginning of the preceding line.
-
- PageDown Displays the next page.
-
- PageUp Displays the preceding page.
-
- End Moves the cursor to the end of the current line (unless that line
- is wider than the screen).
-
- Home Moves the cursor to the start of the current line.
-
- Enter Moves the cursor down one line at a time. If the cursor is in the
- last displayed line when this key is pressed, the whole function
- is scrolled up one line.
-
- Esc Provides a limited "UNDO" facility. All changes made since the
- last press of the Enter key or a function key are removed, and the
- changed lines revert to their original state. Esc does not
- interrupt execution of EDIT.
-
- Locked functions or operators cannot be edited with this function.
-
- If you use EDIT to edit an APL2 function that is already suspended in the
- active workspace, you create a new version of the function. The suspended
- version remains unaltered, but disappears once execution is complete, or the
- state indicator is cleared.
-
- You can also use this editor to copy a function to a new name, leaving the old
- version intact. Just invoke EDIT for the original function, change the name in
- the header line, and press FILE (F4).
-
-
- ΓòÉΓòÉΓòÉ 13.8.2. EDITOR_2 (APL2/370-Compatible Full-Screen Editor) ΓòÉΓòÉΓòÉ
-
- EDITOR_2 is functionally equivalent to Editor 2 (available through )EDITOR 2)
- of APL2/370. Editor 2 is fully described in the APL2 Programming: Language
- Reference.
-
- To use this function, copy it into the active workspace, and then invoke it
- with a right argument of the name of the object to be edited:
-
- )PCOPY 1 EDIT EDITOR_2
- EDITOR_2 'object_name'
-
- This is equivalent to entering the APL2/370 commands:
-
- )EDITOR 2
- Γòûobject_name
-
-
- ΓòÉΓòÉΓòÉ 13.9. The EXAMPLES Workspace ΓòÉΓòÉΓòÉ
-
- This section describes the EXAMPLES workspace.
-
- o Introduction
- o Mathematical Calculations
- o Miscellaneous Utility Functions
- o The Group GPAPL2
-
-
- ΓòÉΓòÉΓòÉ 13.9.1. Introduction ΓòÉΓòÉΓòÉ
-
- The functions in this workspace are examples of ways to use APL2 in solving
- problems. The functions are brief, often no more than one or two statements,
- but they illustrate some of the ways in which APL2, with relatively few
- statements, can do calculations that require many more statements in other
- programming languages. These functions are not necessarily the best way, or the
- only way, to solve the problem. Rather, they illustrate ways to use APL2 that
- are not always obvious. We encourage you to examine the listings of all
- functions and operators in the workspace. Some of them are very simple.
-
- The examples fall into three categories: scientific, miscellaneous, and special
- examples of the new capabilities of APL2. There are also a few of interest to
- programmers, such as decimal-hexadecimal conversions and hexadecimal
- arithmetic.
-
-
- ΓòÉΓòÉΓòÉ 13.9.2. Mathematical Calculations ΓòÉΓòÉΓòÉ
-
- Scientific and Mathematical functions are as follows:
-
- ASSOC Associativity of putative arithmetic tables
- BIN Binomial coefficients
- COMB FC LFC Combinations
- GCD Greatest common divisor
- HILB Hilbert matrix
- PALL PER PERM Permutations
- PO POL POLY POLYB Polynomials
- TRUTH Truth tables
- ZERO Roots of a function
-
- o ASSOC - Associativity
- o BIN - Binomial coefficients
- o COMB/FC/LFC - Combinations
- o GCD - Greatest common divisor
- o HILB - Hilbert matrix
- o PALL/PER/PERM - Permutations
- o PO/POL/POLY/POLYB - Polynomials
- o TRUTH - Truth tables
- o ZERO - Roots of a function
-
-
- ΓòÉΓòÉΓòÉ 13.9.2.1. ASSOC - Associativity ΓòÉΓòÉΓòÉ
-
- Z╜ASSOC M ф ASSOCiativity
-
- The function ASSOC tests any putative group multiplication table M (assuming
- group elements in ьццM) for associativity and yields a value of 1 if it is
- associative, 0 otherwise.
-
- MULTTABLE╜5 5ц(6ц1),(4ц2),(ь3),(2ц3),(ь4),4,ь5
- MULTTABLE
- 1 1 1 1 1
- 1 2 2 2 2
- 1 2 3 3 3
- 1 2 3 4 4
- 1 2 3 4 5
- ASSOC MULTTABLE
- 1
- MULTTABLE[3;3]Γò£1
- MULTTABLE
- 1 1 1 1 1
- 1 2 2 2 2
- 1 2 1 3 3
- 1 2 3 4 4
- 1 2 3 4 5
- ASSOC MULTTABLE
- 0
-
-
- ΓòÉΓòÉΓòÉ 13.9.2.2. BIN - Binomial coefficients ΓòÉΓòÉΓòÉ
-
- Z╜BIN N ф BINomial
-
- The function BIN produces all binomial coefficients up to order N.
-
- BIN 7
- 1 0 0 0 0 0 0 0
- 1 1 0 0 0 0 0 0
- 1 2 1 0 0 0 0 0
- 1 3 3 1 0 0 0 0
- 1 4 6 4 1 0 0 0
- 1 5 10 10 5 1 0 0
- 1 6 15 20 15 6 1 0
- 1 7 21 35 35 21 7 1
-
-
- ΓòÉΓòÉΓòÉ 13.9.2.3. COMB/FC/LFC - Combinations ΓòÉΓòÉΓòÉ
-
- ZΓò£COMB N
- ZΓò£FC N
- ZΓò£LFC N
-
- The function COMB uses recursive definition to produce a 2!N by 2 matrix of all
- possible pairs of elements from ьN.
-
- COMB 5
- 1 2
- 1 3
- 2 3
- 1 4
- 2 4
- 3 4
- 1 5
- 2 5
- 3 5
- 4 5
-
- The function FC shows an alternative method that yields the same pairs but in a
- different order.
-
- FC 5
- 1 2
- 1 3
- 1 4
- 1 5
- 2 3
- 2 4
- 2 5
- 3 4
- 3 5
- 4 5
-
- The function LFC uses FC to generate letter pairs.
-
- LFC 5
- AB
- AC
- AD
- AE
- BC
- BD
- BE
- CD
- CE
- DE
-
-
- ΓòÉΓòÉΓòÉ 13.9.2.4. GCD - Greatest common divisor ΓòÉΓòÉΓòÉ
-
- Z╜L GCD R ф Greatest Common Divisor
-
- The function GCD uses the Euclidean algorithm to produce the greatest common
- divisor.
-
- 30 GCD 40
- 10
- GCD/ 30 40
- 10
- GCD/ 30 40 45
- 5
- GCD/ 30 40 39 45
- 1
- GCD/ 30 42 39 45
- 3
-
-
- ΓòÉΓòÉΓòÉ 13.9.2.5. HILB - Hilbert matrix ΓòÉΓòÉΓòÉ
-
- Z╜HILB N ф HILBert matrix
-
- The function HILB produces a Hilbert matrix of order N.
-
-
- ΓòÉΓòÉΓòÉ 13.9.2.6. PALL/PER/PERM - Permutations ΓòÉΓòÉΓòÉ
-
- ZΓò£PALL N
- ZΓò£PER N
- ZΓò£PERM N
-
- The function PALL produces the matrix of all permutations of order N. Its
- subfunction PERM produces the B-th permutation of order N.
-
- The function PER uses recursive definition. It produces all permutations by a
- method much faster than that used in the function PALL. The permutations are
- not produced in the same order as those produced by PALL.
-
- PALL 3
- 1 2 3
- 1 3 2
- 2 1 3
- 2 3 1
- 3 1 2
- 3 2 1
-
- PER 3
- 1 3 2
- 2 3 1
- 1 2 3
- 2 1 3
- 3 2 1
- 3 1 2
-
-
- ΓòÉΓòÉΓòÉ 13.9.2.7. PO/POL/POLY/POLYB - Polynomials ΓòÉΓòÉΓòÉ
-
- Z╜C POLY X ф Scalar right argument only
- Z╜C POL X ф Scalar right argument only
- ф (uses inner product)
- Z╜C POLYB X ф Scalar right argument only
- ф (uses base value)
- Z╜C PO X ф Scalar or vector right argument
-
- The functions POLY, POL, PO, and POLYB each evaluate a polynomial or
- polynomials whose coefficients are determined by the left argument, and whose
- point or points of evaluation are determined by the right argument. The
- coefficients are in ascending order of associated powers.
-
- ¤1 0 1 PO ¤2 ¤1 0 1 2
- 3 0 ¤1 0 3
- ¤1 0 1 POL 2
- 3
- ¤1 0 1 POLY 1
- 0
- ¤1 0 1 POLYB ¤1
- 0
-
- To find the zeros of polynomials, see the POLYZ function from the MATHFNS
- workspace, described in Roots of Polynomials.
-
-
- ΓòÉΓòÉΓòÉ 13.9.2.8. TRUTH - Truth tables ΓòÉΓòÉΓòÉ
-
- ZΓò£TRUTH N
-
- The function TRUTH produces the matrix of arguments of the truth table of N
- logical variables.
-
- TRUTH 3
- 0 0 0
- 0 0 1
- 0 1 0
- 0 1 1
- 1 0 0
- 1 0 1
- 1 1 0
- 1 1 1
-
-
- ΓòÉΓòÉΓòÉ 13.9.2.9. ZERO - Roots of a function ΓòÉΓòÉΓòÉ
-
- ZΓò£TOL (F ZERO) R
-
- The operator ZERO uses the bisection method to determine, within a tolerance
- TOL, a root of the function F lying between the bounds R[1] and R[2]. F(R[1])
- and F(R[2]) must have opposite signs. ZERO should be applied only to continuous
- functions.
-
- РFX 'Z╜SIN X' 'Z╜1ъX'
- SIN
- .1 SIN ZERO ¤1 1
- 0
- .1 SIN ZERO 1 4
- 3.0625
- .001 SIN ZERO 1 4
- 3.141601563
-
-
- ΓòÉΓòÉΓòÉ 13.9.3. Miscellaneous Utility Functions ΓòÉΓòÉΓòÉ
-
- o PACK/UNPACK - Illustration of Base and Representation
- o DEC2HEX/HEX2DEC/HEX - Hexadecimal arithmetic and conversions
- o SORTLIST - Sort with collating sequence
- o TIME - Provide CPU time used
-
-
- ΓòÉΓòÉΓòÉ 13.9.3.1. PACK/UNPACK - Illustration of Base and Representation ΓòÉΓòÉΓòÉ
-
- ZΓò£PACK X
- ZΓò£UNPACK X
-
- The functions PACK and UNPACK illustrate the use of the Ш and Э functions in
- transforming between a four-number encoding of SERIAL NUMBER (1 to 9999),
- MONTH, DAY, and YEAR, and a single number encoding of the same data.
-
- PACK 117 1 1 84
- 4315283
- UNPACK 4315283
- 117 1 1 84
-
-
- ΓòÉΓòÉΓòÉ 13.9.3.2. DEC2HEX/HEX2DEC/HEX - Hexadecimal arithmetic and conversions ΓòÉΓòÉΓòÉ
-
- ZΓò£DEC2HEX R
- ZΓò£HEX2DEC R
- ZΓò£L(F HEX)R
-
- The functions DEC2HEX and HEX2DEC work with nonnegative hexadecimal numbers
- represented as strings of characters selected from '0123456789ABCDEF'. The HEX
- operator performs an arithmetic function F on hexadecimal arguments, and
- returns a (character) hexadecimal result. The arguments presented to a function
- derived by the HEX operator must have a depth no greater than two.
-
- DEC2HEX Converts decimal to hexadecimal
- HEX2DEC Converts hexadecimal to decimal
- + HEX Performs hexadecimal addition
- - HEX Performs hexadecimal subtraction
- ... and so on
-
- 'FF' +HEX '1'
- 100
- (ьHEX '5')°.їHEX(ьHEX 'C')
- 1 2 3 4 5 6 7 8 9 A B C
- 2 4 6 8 A C E 10 12 14 16 18
- 3 6 9 C F 12 15 18 1B 1E 21 24
- 4 8 C 10 14 18 1C 20 24 28 2C 30
- 5 A F 14 19 1E 23 28 2D 32 37 3C
-
-
- ΓòÉΓòÉΓòÉ 13.9.3.3. SORTLIST - Sort with collating sequence ΓòÉΓòÉΓòÉ
-
- ZΓò£SORTLIST R
- R is a character matrix. Z is R with its rows sorted according to the collating
- sequence defined in DCS, a global variable.
-
-
- ΓòÉΓòÉΓòÉ 13.9.3.4. TIME - Provide CPU time used ΓòÉΓòÉΓòÉ
-
- ZΓò£TIME
-
- The function TIME yields the amount (in minutes, seconds, and milliseconds) of
- CPU time used since its previous execution. It is useful in measuring the
- execution times of other functions. The global variable TIMER is assigned the
- value of the cumulative CPU time at each execution of the function TIME.
-
-
- ΓòÉΓòÉΓòÉ 13.9.4. The Group GPAPL2 ΓòÉΓòÉΓòÉ
-
- The group GPAPL2 consists of various functions and operators designed to show
- some of the capabilities of APL2.
-
- o Workspace Information Functions
- o Miscellaneous Functions
- o Operators to Conform Arguments
- o Operators for Debugging
- o Operators to Handle Depth
- o Operators for Program Control
- o Miscellaneous Operators
-
-
- ΓòÉΓòÉΓòÉ 13.9.4.1. Workspace Information Functions ΓòÉΓòÉΓòÉ
-
- EXAMPLE R
-
- This function executes the examples found in the leading comments of the
- program named in R.
-
- EXAMPLES
-
- This function executes the examples found in the leading comments of all the
- programs in the workspace.
-
-
- ΓòÉΓòÉΓòÉ 13.9.4.2. Miscellaneous Functions ΓòÉΓòÉΓòÉ
-
- Z╜L IOTAU R ф IOTA Underbar
-
- This is the Find Index function from the APL2 Installed User Program. R and L
- may be any arrays. Z is an integer matrix containing the starting positions (in
- row major order) where pattern R begins in the array L.
-
- ц'A' IOTAU 'A'
- 0 1
- 'ABABABA' IOTAU 'AB'
- 1
- 3
- 5
- 1 (2 3) (4 5) 2 3 4 5 IOTAU 2 3
- 4
- L╜4 5ц'ABCABA'
- L
- ABCAB
- AABCA
- BAABC
- ABAAB
- L IOTAU 'BA'
- 3 1
- 4 2
- L IOTAU 2 1ц'BA'
- 1 2
- 1 5
- 2 3
- 3 1
- 3 4
-
- ZΓò£L REPLICATE R
- ZΓò£L EXPAND R
-
- These functions are identical to their primitive counterparts, Replicate and
- Expand, respectively represented by "/" and "\", except that the primitive
- versions are operators, so you cannot apply operators to them. The defined
- REPLICATE and EXPAND really are functions, so you can apply operators to them.
-
- (1 0 1)(0 3) REPLICATEΓûá 'ABC' 'DE'
- AC EEE
- REPLICATE/ 5 '*'
- *****
- (1 0 1)(0 1 0) EXPANDΓûá (2 4) 6
- 2 0 4 0 6 0
-
- ZΓò£L ENLISTA R
-
- Return (in Z) the array L with each item of the enlist of L (юL) replaced by
- the corresponding item from R. By using this, you can replace the selective
- specification (юL)╜R with L╜L ENLISTA R.
-
- ZΓò£EXPUNGE NL
-
- Expunge the objects listed in NL. NL may be a character matrix with one name
- per row, or a character vector with names separated by blanks. If a name is
- enclosed in parentheses, it is assumed to be the name of a character array
- (rank not greater than 2) containing a list of objects to be expunged. Unlike
- the )ERASE system command, this expunges the local copy of an object that is
- localized in a pendent or suspended function or operator.
-
- Z╜REP R ф REPresentation
-
- Z is a "representation" of the array, function, or operator named in R.
- Specifically, Z is пR or РCR, whichever is appropriate. This is an example of
- the ELSE operator in this group.
-
- ZΓò£TYPE R
-
- Z is a scalar zero if R is numeric, and a scalar blank if it is character. This
- function is compatible with a VS APL library function of the same name. It is
- not meant to be applied to mixed or nested arguments.
-
- ZΓò£UNIQUE R
-
- R is a vector. Z is a vector containing the elements of R with duplicates
- eliminated.
-
- UNIQUE 'THE ANTS WERE HERE'
- THE ANSWR
- UNIQUE 'GUFFAW' 17 (ь4) 'GUFFAW'
- GUFFAW 17 1 2 3 4
-
-
- ΓòÉΓòÉΓòÉ 13.9.4.3. Operators to Conform Arguments ΓòÉΓòÉΓòÉ
-
- Z╜L (F CR) R ф Conform Ranks
- ZΓò£L (F PAD) R
- Z╜L (F TRUNC) R ф TRUNCate
-
- The CR operator "conforms the ranks" of L and R and then applies the function
- F. The PAD operator conforms the axes of L and R by overtake. The TRUNC
- operator conforms the axes of L and R by undertake.
-
- (4 4ц'WE THEYUS OURS') ^.(=PAD) э 2 3ц'WE OUR'
- 1 0
- 0 0
- 0 0
- 0 0
- (4 4ц'WE THEYUS OURS') ^.(=TRUNC) э 2 3ц'WE OUR'
- 1 0
- 0 0
- 0 0
- 0 1
- (2 3 4ць24) +PAD CR 5 6ц100їь30
- 101 202 303 404 500 600
- 705 806 907 1008 1100 1200
- 1309 1410 1511 1612 1700 1800
- 1900 2000 2100 2200 2300 2400
- 2500 2600 2700 2800 2900 3000
- 13 14 15 16 0 0
- 17 18 19 20 0 0
- 21 22 23 24 0 0
- 0 0 0 0 0 0
- 0 0 0 0 0 0
-
-
- ΓòÉΓòÉΓòÉ 13.9.4.4. Operators for Debugging ΓòÉΓòÉΓòÉ
-
- ZΓò£L (F TRACE) R ZΓò£(F TRACE) R
- TRACE traces the execution of F. It is most useful when the derived function is
- passed to another operator. Every time F is called, the derived function
- displays its argument(s) and the result.
-
- +TRACE\ 1 4 9 ф Expression as entered
- 1 4 ф TRACE output
- 5 ф :
- 4 9 ф :
- 13 ф :
- 1 13 ф :
- 14 ф TRACE output
- 1 5 14 ф Final result
- 2 +TRACE\ 1 2 3 4 ф Expression as entered
- 1 2 ф TRACE output
- 3 ф :
- 2 3 ф :
- 5 ф :
- 3 4 ф :
- 7 ф TRACE output
- 3 5 7 ф Final result
-
- ZΓò£L (F TRAP) R ZΓò£(F TRAP) R
-
- The derived function (F TRAP) is just like F, except that if an error occurs
- during the execution of F, the enclosed error message becomes the result.
-
- 2 ЎTRAP 0
- DOMAIN ERROR
- L F R
- ^
- цу2 ЎTRAP 0
- 3 12
-
-
- ΓòÉΓòÉΓòÉ 13.9.4.5. Operators to Handle Depth ΓòÉΓòÉΓòÉ
-
- Z╜L (F EL) R ф Each Left
- Z╜L (F ER) R Z╜(F ER) R ф Each Right
-
- These operators are like the Each operator (Γûá), except that EL applies Each
- only on the left argument, and ER applies Each only on the right argument.
-
- (2 2 3)(4 3)(2 6) цEL ь12
- 1 2 3 1 2 3 1 2 3 4 5 6
- 4 5 6 4 5 6 7 8 9 10 11 12
- 7 8 9
- 7 8 9 10 11 12
- 10 11 12
- 2 3 цER 4 5 6
- 4 4 4 5 5 5 6 6 6
- 4 4 4 5 5 5 6 6 6
-
- Z╜L (F PL) R ф Pervasive Left
- Z╜L (F PR) R Z╜(F PR) R ф Pervasive Right
-
- PL causes F to be treated as pervasive down to depth 1 (simple arrays) on its
- left argument, and PR causes F to be treated as pervasive down to depth 1 on
- its right argument.
-
- 1 (2 3)цPL ь6
- 1 1 2 3
- 4 5 6
- 3 цPR 1,т2,т3 4
- 1 1 1 2 2 2 3 4 3
- (цPR 'A' 'BC' ('DEF' 'HIJK')) ц PL 'Р'
- Р РР РРР РРРР
-
-
- ΓòÉΓòÉΓòÉ 13.9.4.6. Operators for Program Control ΓòÉΓòÉΓòÉ
-
- ZΓò£C (F ELSE G) R
-
- If C is 1, then Z is F R. If C is 0, then Z is G R.
-
- ZΓò£(F IF C) R
-
- If C is 1, then Z is F R. Otherwise, Z is R.
-
-
- ΓòÉΓòÉΓòÉ 13.9.4.7. Miscellaneous Operators ΓòÉΓòÉΓòÉ
-
- ZΓò£L (F AND G) R ZΓò£(F AND G) R
-
- The AND operator applies two functions to the same argument(s).
-
- 3 +ANDї 5
- 8 15
- +AND- 5
- 5 ¤5
- (ь4) (°.ї)AND(°.+) (ь4)
- 1 2 3 4 2 3 4 5
- 2 4 6 8 3 4 5 6
- 3 6 9 12 4 5 6 7
- 4 8 12 16 5 6 7 8
-
- ZΓò£L (F COMMUTE) R
-
- The COMMUTE operator switches the arguments of the function to which it is
- applied.
-
- 0.5 *COMMUTE 9
- 3
-
- Z╜L (F FAROUT) R ф FAr Reaching OUTer product
-
- This operator applies outer product to all levels of the arrays L and R.
-
- (10 20)(30 40 50) +FAROUT (1 2)(3 4 5)
- 11 12 13 14 15
- 21 22 23 24 25
- 31 32 33 34 35
- 41 42 43 44 45
- 51 52 53 54 55
-
- Z╜L (F NOP) R Z╜(F NOP) R ф No OPeration
-
- The derived function (F NOP) is just F. This operation is useful for separating
- the array right operand of an operator from the right argument of the derived
- function. It sometimes eliminates one layer of parentheses.
-
- ф Compare with the next example.
- ц POWER 2 NOP 2 3 4ць24
- 3
-
- ZΓò£(F POWER N) R
-
- POWER applies F monadically N times.
-
- ф Parentheses are redundant here.
- (ц POWER 2) 2 3 4ць24
- 3
-
-
- ΓòÉΓòÉΓòÉ 13.10. The FILE Workspace ΓòÉΓòÉΓòÉ
-
- The FILE workspace has been designed to help you work with OS/2 files.
-
- o The Function Groups
- o AP 210 Group
- o AP 211 Group
- o Delta Group
- o Transfer Group
-
-
- ΓòÉΓòÉΓòÉ 13.10.1. The Function Groups ΓòÉΓòÉΓòÉ
-
- The FILE workspace contains the following groups of functions:
-
- o AP 210 group
- o AP 211 group
- o Delta group
- o Transfer group
-
- A list of the main functions in each group is presented in a captioned figure
- at the beginning of each section.
-
-
- ΓòÉΓòÉΓòÉ 13.10.2. AP 210 Group ΓòÉΓòÉΓòÉ
-
- The functions in this group aid in manipulating OS/2 files. This group allows
- either sequential or random access. It uses the file auxiliary processor, AP
- 210. This workspace enables you to create a file, write into it, and read from
- it. To do so, you WOPEN an old or new file, and WRITE data into it. You then
- CLOSE the file to save it on disk. If you only want to read data from an old
- file, without writing any more data into it, on the next access simply OPEN the
- file and READ in records, either randomly or sequentially.
-
- To use the functions described here, you must copy the FILE workspace into your
- active workspace by entering:
-
- )PCOPY 2 FILE
-
- If this command executes successfully, the following set of functions is loaded
- into your active workspace.
-
- o Terminology
- o OPEN - Open a file for read/only
- o WOPEN - Open a file for read/write
- o CLOSE - Close a file
- o EBCDIC - Set up an EBCDIC translation table
- o SIZE - Return file size in bytes
- o READ - Read a record
- o READD - Read designated bytes
- o READV - Read a variable-length record
- o READVS - Read a record, stripping EOL
- o WRITE - Write a record
- o WRITED - Write designated bytes
- o WRITEV - Write a variable-length record
- o APPENDFILEV - Append to a variable-length record file
- o COMPARE - Compare two files
- o DELETE - Delete a file
- o RENAME - Rename a file
- o READFILEV - Read a file of variable-length records
- o TYPE - Display the contents of a file
- o WRITEFILEV - Write a file of variable-length records
- o Auxiliary functions
- o Example of Use
-
-
- ΓòÉΓòÉΓòÉ 13.10.2.1. Terminology ΓòÉΓòÉΓòÉ
-
- The following terms are used in the descriptions of the syntax for the
- functions:
-
- Brackets indicate that a parameter is optional.
-
- "code" can be any of the following characters:
-
- A (APL) The records in the file are APL2 objects and their headers in APL2
- internal form. Arrays of arbitrary rank and depth can be stored and
- recovered. Different records of a file can contain objects of different
- types (for example, characters, integers, or real numbers). An APL2 object
- in a record can occupy up to the actual record length (not necessarily the
- same number of bytes), but the header fills a part of that area.
-
- B (Bool) The records in the file contain strings of bits with no header
- (packed eight bits per byte). The equivalent APL2 object is a Boolean
- vector. In this case, all records must be equal to the selected record
- length.
-
- C (Char) The contents of the record is a string of characters in ASCII,
- with no header. All records must be equal to the selected record length,
- with each character occupying one byte. Variable-length records are not
- supported.
-
- D (ASCII) The contents of the record is a string of characters in ASCII
- code, with no header. Each character occupies one byte. Variable-length
- records are supported.
-
- T (Translate) The contents of the record is a string of characters, with no
- header, translated according to the AP 210 translate table defined as
- described in Establishing the AP 210 Translate Table. All records must be
- equal to the selected record length except when variable-length operations
- are being performed.
-
- "file_no" is a positive integer that you define for future reference to a file
- when you open it.
-
- "filespec" must be in the following OS/2 syntax:
-
- [C:\path\]filename
-
- Errors encountered during the execution of these functions can cause a message
- containing an AP 210 return code to be displayed. The meanings of these return
- codes are listed in AP 210 Return Codes.
-
-
- ΓòÉΓòÉΓòÉ 13.10.2.2. OPEN - Open a file for read/only ΓòÉΓòÉΓòÉ
-
- [file_no] OPEN 'filespec[,code]'
-
- This function opens the specified OS/2 file for read-only sequential or random
- access.
-
- If no file by that name exists in the indicated drive or directory, an error
- results; see AP 210 Return Codes for a list of all possible return codes. If
- "file_no" is omitted, 1 is assumed. If "code" is omitted, A (APL) is assumed.
-
- OPEN creates three global variables, with the following names:
-
- 'CZ',╨╛file_no - Control shared variable
- 'DZ',╨╛file_no - Data shared variable
- 'EZ',╨╛file_no - File size in bytes
-
- OPENing a file_no without having closed the corresponding file causes the
- current file to be closed, and then re-opened according to the new request.
-
-
- ΓòÉΓòÉΓòÉ 13.10.2.3. WOPEN - Open a file for read/write ΓòÉΓòÉΓòÉ
-
- [file_no] WOPEN 'filespec[,code]'
-
- This function opens the specified OS/2 file for reading or writing, with
- sequential or random access.
-
- If no file of this name exists, a new file is created. If "file_no" is omitted,
- 1 is assumed. If "code" is omitted, A (APL) is assumed.
-
- WOPEN creates three global variables, with the following names:
-
- 'CZ',╨╛file_no - Control shared variable
- 'DZ',╨╛file_no - Data shared variable
- 'EZ',╨╛file_no - File size in bytes
-
- WOPENing a file_no without having closed the corresponding file causes the
- current file to be closed, and then re-opened according to the new request.
-
-
- ΓòÉΓòÉΓòÉ 13.10.2.4. CLOSE - Close a file ΓòÉΓòÉΓòÉ
-
- CLOSE file_no
-
- This function closes a file that has been opened with (W)OPEN. The previously
- assigned file_no is now available for reuse. (If you (W)OPEN a file_no without
- having closed the corresponding file, the current file is closed and then
- re-opened according to the new request.)
-
-
- ΓòÉΓòÉΓòÉ 13.10.2.5. EBCDIC - Set up an EBCDIC translation table ΓòÉΓòÉΓòÉ
-
- EBCDIC file_no
-
- The EBCDIC function defines an APL2-EBCDIC translation table to AP 210. This
- can be used after opening an AP 210 file with code T.
-
- The file_no matches the number you defined in (W)OPENing the file.
-
-
- ΓòÉΓòÉΓòÉ 13.10.2.6. SIZE - Return file size in bytes ΓòÉΓòÉΓòÉ
-
- ZΓò£SIZE file_no
-
- This function returns the size of a file when it was last opened.
-
- SIZE can only be used after the file has been OPENed or WOPENed successfully.
-
-
- ΓòÉΓòÉΓòÉ 13.10.2.7. READ - Read a record ΓòÉΓòÉΓòÉ
-
- ZΓò£READ file_no [record_no [record_size]]
-
- This function reads an OS/2 data file, sequentially or randomly, that was
- opened by using (W)OPEN.
-
- "file_no" matches the number that you specified in (W)OPENing the file.
-
- If no "record_no" is specified, the default is sequential access to the file.
- Under sequential access, the first record (record 0) is accessed by either a
- READ or WRITE command immediately after the (W)OPEN; the second record (record
- 1) is accessed on the next command, and so on. The READ, READD, READV, WRITE,
- WRITED, and WRITEV functions work from the same access point, meaning that the
- access point is advanced sequentially to the next record each time any of these
- commands is issued.
-
- Random access is designated by specifying a particular record. "record_size"
- can only be specified when using random access. If the record_size is not
- specified, the default is the record_size specified in the previous operation.
- If the record_size is not specified on the first READ or WRITE, the default is
- 128 bytes.
-
-
- ΓòÉΓòÉΓòÉ 13.10.2.8. READD - Read designated bytes ΓòÉΓòÉΓòÉ
-
- ZΓò£READD file_no [byte_no [record_size]]
-
- This function reads an OS/2 data file, sequentially or randomly, that was
- opened using (W)OPEN.
-
- "file_no" matches the number that you specified in (W)OPENing the file.
-
- "file_no", "byte_no" and "record_size" must all be integer.
-
- If byte_no is not specified, the default is sequential access to the file.
- Random access is designated by specifying a particular "byte_no" position in
- the file (0єbyte_no). "record_size" can be specified only when you are using
- random-access.
-
-
- ΓòÉΓòÉΓòÉ 13.10.2.9. READV - Read a variable-length record ΓòÉΓòÉΓòÉ
-
- ZΓò£READV file_no [record_no [scan_length]]
-
- This function sequentially reads a variable-length record APL2 or ASCII
- character file that was previously opened by using (W)OPEN.
-
- The file_no matches the number that you defined in (W)OPENing the file.
-
- If no "record_no" is specified, the default is sequential access to the file.
-
- If no "scan_length" is specified, the default is the scan_length specified in
- the previous operation. If the scan_length is not specified on the first READV,
- the default is 128 bytes. This parameter defines the maximum distance for which
- AP 210 scans the file for a line-feed character, and should be set to the
- maximum record length that you expect to read.
-
- This function can be used only if the file was opened with codes A, D, or T.
-
- If the file was opened with codes D or T, the record returned by READV includes
- the delimiting line-feed character, which can be removed with a ¤1╟ operation.
-
-
- ΓòÉΓòÉΓòÉ 13.10.2.10. READVS - Read a record, stripping EOL ΓòÉΓòÉΓòÉ
-
- ZΓò£READVS file_no [record_no [scan_length]]
-
- This function is the same as READV, except that trailing CR/LF or LF indicators
- are stripped from the record.
-
-
- ΓòÉΓòÉΓòÉ 13.10.2.11. WRITE - Write a record ΓòÉΓòÉΓòÉ
-
- [file_no [rec_no [rec_size]]] WRITE DATA
-
- This function writes to an OS/2 data file, either sequentially or randomly,
- that has been opened by using WOPEN. (Trying to WRITE to a file opened by OPEN
- results in an error; see AP 210 Return Codes for a list of all possible return
- codes.) When the WRITE function is issued, it writes over any existing data in
- the currently accessed record.
-
- "file_no" matches the number arbitrarily defined when the file was WOPENed. If
- no number is given, 1 is assumed.
-
- If the rec_no is not specified on the first READ or WRITE, the default is
- sequential access to the file. Under sequential access, the first record
- (record 0) is accessed by either a READ or a WRITE command immediately after
- the (W)OPEN; the second record (record 1) is accessed on the next command, and
- so on. The READ, READD, READV, WRITE, WRITED, and WRITEV functions work from
- the same access point; that is, the access point is advanced sequentially to
- the next record each time any of these commands are issued.
-
- Random access is designated by specifying a particular record. If the record
- size, rec_size, is not specified, the default is the rec_size specified on the
- previous READ or WRITE
-
- If the rec_size has not been specified, the default is 128 bytes.
-
-
- ΓòÉΓòÉΓòÉ 13.10.2.12. WRITED - Write designated bytes ΓòÉΓòÉΓòÉ
-
- [file_no [byte_no [rec_size]]] WRITED DATA
-
- This function writes to an OS/2 data file, either sequentially or randomly,
- that has been opened by using WOPEN. (Trying to WRITED to a file opened by OPEN
- results in an error; see AP 210 Return Codes for a list of all possible
- errors.) When the WRITED function is issued, it writes over any existing data
- in the currently accessed record.
-
- "file_no" matches the number that you arbitrarily defined in WOPENing the file.
- If not given, 1 is assumed.
-
- "file_no", "byte_no" and "rec_size" must all be integer.
-
- If "byte_no" is not specified, the default is sequential access to the file.
- Random access is designated by specifying a particular "byte_no" (0єbyte_no).
-
- If the record size, rec_size, has not been specified, the default is 128 bytes.
-
-
- ΓòÉΓòÉΓòÉ 13.10.2.13. WRITEV - Write a variable-length record ΓòÉΓòÉΓòÉ
-
- [file_no [rec_no]] WRITEV DATA
-
- This function sequentially writes a variable-length record APL2 or ASCII
- character file that has been opened by using WOPEN.
-
- The file_no matches the number that you defined in WOPENing the file. If none
- was given, 1 is assumed.
-
- This function can be used only if the file was opened with code A, D, or T.
-
- If rec_no is not given, sequential operation is performed. (This gives the
- fastest operation, because the file is scanned from the beginning, in search of
- the requested record, whenever rec_no is specified.) If rec_no is greater than
- the number of records currently in the file, the record is appended to the end
- of the file.
-
- If the file was opened with code D or code T, a line-feed character is appended
- to the end of each record as expected by OS/2 for sequential files. If the
- record already has a line-feed character (РTC[РIO+2]) appended, no additional
- line-feed is added.
-
-
- ΓòÉΓòÉΓòÉ 13.10.2.14. APPENDFILEV - Append to a variable-length record file ΓòÉΓòÉΓòÉ
-
- 'filespec' APPENDFILEV vector_of_charvectors
-
- This function accepts a vector of character vectors as its right argument and a
- file name as its left argument; it then appends each vector in
- "vector_of_charvectors" as code D (ASCII) variable-length records to the file
- "filespec". To write a single character vector as one record, enclose (т) the
- right argument.
-
-
- ΓòÉΓòÉΓòÉ 13.10.2.15. COMPARE - Compare two files ΓòÉΓòÉΓòÉ
-
- [record_size] COMPARE filespec_matrix
-
- This function compares two files. The right argument is a two-row character
- matrix, each row containing the filespec of one of the files to be compared,
- followed by a comma, followed by the code with which the file is to be read.
- The optional left argument, record_size, specifies the record length with which
- the files are to be read. If this left argument is not specified, the files are
- assumed to contain variable-length records.
-
- If the files are identical, the COMPARE function gives no output. Otherwise, it
- lists the pairs of corresponding records that differ. It also indicates which
- of the files is shorter, if applicable. For example:
-
- 80 COMPARE у'FILE1,D' 'FILE2,D'
-
- This example compares files, FILE1 and FILE2, both of which are read as 80-byte
- fixed-length record ASCII files.
-
-
- ΓòÉΓòÉΓòÉ 13.10.2.16. DELETE - Delete a file ΓòÉΓòÉΓòÉ
-
- DELETE 'filespec'
-
- This function deletes an OS/2 file. (Files can also be erased in OS/2 by using
- the "del" command.)
-
-
- ΓòÉΓòÉΓòÉ 13.10.2.17. RENAME - Rename a file ΓòÉΓòÉΓòÉ
-
- 'new_filespec' RENAME 'old_filespec'
-
- This function changes the name of the file specified in the right argument to
- the name and extension specified in the left argument. The left argument
- directory (or APL2 library number) must be specified. If a different
- subdirectory is specified, a move is performed instead of a rename.
-
-
- ΓòÉΓòÉΓòÉ 13.10.2.18. READFILEV - Read a file of variable-length records ΓòÉΓòÉΓòÉ
-
- ZΓò£READFILEV 'filespec'
-
- This function reads a code A (APL), code D (ASCII), or code T (Translate)
- variable-length record file and returns each record as an element of a vector
- of arrays.
-
- If no code is specified with filespec, the file is assumed to be an ASCII (code
- D) file with line-feed characters delimiting records.
-
- Also, the ΓòóFV function, described in Delta Group, provides a similar facility
- and is independent of other functions in this workspace.
-
-
- ΓòÉΓòÉΓòÉ 13.10.2.19. TYPE - Display the contents of a file ΓòÉΓòÉΓòÉ
-
- [record_size [n]] TYPE 'filespec[,code]'
-
- This function displays the contents of an OS/2 file.
-
- The file with the specified filespec is displayed at the terminal.
-
- "record_size", if given, specifies the record length of a fixed-record-length
- file, whose first n characters are to be typed. If n is not given, the full
- record_size is typed. If record_size is not given, the file is assumed to
- contain variable-length records. In this case code must be either A (APL2) or D
- (ASCII); if it is not specified, code D is used.
-
-
- ΓòÉΓòÉΓòÉ 13.10.2.20. WRITEFILEV - Write a file of variable-length records ΓòÉΓòÉΓòÉ
-
- 'filespec' WRITEFILEV vector_of_arrays
-
- This function accepts a vector of arrays as its right argument and a file name
- as its left argument; it then writes each vector in "vector_of_arrays" as code
- A (APL2), code D (ASCII), or code T (Translate) variable-length records in the
- file "filespec".
-
- If no code is specified with filespec, the file is written as an ASCII (code D)
- file with line-feed characters delimiting records. For code D or code T,
- vector_of_arrays must be a vector of character vectors. To write a single array
- as one record, enclose (т) the right argument.
-
- Also see the ΓòóFV function, described in Delta Group, which provides a similar
- facility and is independent of other functions in this workspace.
-
-
- ΓòÉΓòÉΓòÉ 13.10.2.21. Auxiliary functions ΓòÉΓòÉΓòÉ
-
- A ΓòóCHK N
-
- Translates return codes. A is optional and, if included, contains a specific
- list of return codes to check. N identifies the file number.
-
- ΓòóSH N
-
- Shares a pair of variables with AP 210. Uses N as a variable suffix.
-
-
- ΓòÉΓòÉΓòÉ 13.10.2.22. Example of Use ΓòÉΓòÉΓòÉ
-
- The following is an example of how to use some of the OS/2 file-handling
- functions contained in the FILE workspace:
-
- )LOAD 2 FILE
-
- First create a new file. The records contain strings of ASCII character data.
- The file number is set to 1:
-
- 1 WOPEN 'NAMEFILE,D'
-
- The first record (record 0) is a variable-length record written to file number
- 1. Line feed characters are added automatically as record separators:
-
- 1 0 WRITEV 'Jane Doe, Megabyte System, 555-5555'
-
- Writes the second record to file 1:
-
- 1 1 WRITEV 'Jim Diaz, Success Inc., 555-9999'
-
- Close the file:
-
- CLOSE 1
-
- Open the same file for read-only operations, with the same file number:
-
- OPEN 'NAMEFILE,D'
-
- Read the second record first with the line-feed character stripped off:
-
- READVS 1 1
- Jim Diaz, Success Inc., 555-9999
-
- Now request the first record, again removing the line-feed separator:
-
- READVS 1 0
- Jane Doe, Megabyte Systems, 555-5555
-
- Close the file:
-
- CLOSE 1
-
- Delete the file:
-
- DELETE 'NAMEFILE'
-
-
- ΓòÉΓòÉΓòÉ 13.10.3. AP 211 Group ΓòÉΓòÉΓòÉ
-
-
- FILE: AP 211 Functions
-
- REBUILD211 Rebuild an AP 211 file
- TRYLOAD Loads a workspace saved under TryAPL2
-
- [R] REBUILD211 F
-
- Rebuild AP 211 file F. The optional left argument, R, specifies the record
- length to be used. If no left argument is supplied, the record size of F is
- used. The resulting file has data stored in contiguous records and uses the
- minimum space on the disk.
-
- TRYLOAD 'filename'
-
- This function loads a workspace saved under TryAPL2. filename is the name of
- the file to be rebuilt. The extension .TRY is added to the name.
-
-
- ΓòÉΓòÉΓòÉ 13.10.4. Delta Group ΓòÉΓòÉΓòÉ
-
-
- FILE: Delta Functions
-
- ΓòóFM Read or write a file with fixed-length records
- ΓòóFV Read or write a file with variable-length records
-
- ZΓò£[array] ΓòóFM 'filespec'
- ZΓò£[array] ΓòóFV 'filespec'
-
- These two functions emulate the ΓòóFM and ΓòóFV external functions of APL2/370.
-
- o Reading files:
-
- RΓò£ΓòóFM 'filespec'
-
- Reads the file "filespec" and returns a character matrix. Records are padded
- on the right with blanks to the length of the longest record.
-
- RΓò£ΓòóFV 'filespec'
-
- Reads the file "filespec" and returns a vector of character vectors. Trailing
- blanks in any records are deleted.
-
- o Writing files:
-
- RΓò£array ΓòóFM 'filespec'
-
- Writes the data from the matrix or vector of vectors "array" to the file
- "filespec". If "array" is a character matrix, all records are padded with
- blanks to the full width of the array.
-
- RΓò£array ΓòóFV 'filespec'
-
- Writes the data from the matrix or vector of vectors "array" to the file
- "filespec". A file with variable-length records is created. Trailing blanks
- in each record are deleted.
-
- ΓòóFM and ΓòóFV return a character matrix or a vector of vectors if the file is
- successfully read, or a numeric return code if the operation results in an AP
- 210 error. If these functions are being used to write a file, a return code of
- 0 is returned if the operation is successful.
-
- If the left argument of ΓòóFM or ΓòóFV is empty, the file specified by the right
- argument is erased, if it exists, and a return code of 0 is returned. If the
- file does not exist, a return code of 2 is given.
-
- These functions can be used to read and write files that can be interchanged
- with other OS/2 applications.
-
- Note: These functions can handle either the CR/LF or LF end-of-line
- indicators. They automatically write the correct indicator for the running
- system, and can read files with either type of indicator.
-
-
- ΓòÉΓòÉΓòÉ 13.10.5. Transfer Group ΓòÉΓòÉΓòÉ
-
- Simulated )IN
-
- ZΓò£[NL] IN 'filespec'
- ZΓò£ IN 'filespec names'
-
- This function imitates the )IN command under the control of AP 210. It can be
- called from another APL2 function, thus effectively providing a powerful IN
- facility. The size of arrays that can be handled, however, is restricted by the
- implementation limit of РTF. See Implementation Limits for further details.
-
- You can call this function in two different ways:
-
- o To copy a whole file into your active workspace, call the IN function in the
- following way:
-
- IN 'filespec'
-
- where filespec is the name of the file you want to copy. This can include an
- extension. If no extension is specified, a default extension of ".atf" is
- initially used. The result is 1 if the file exists or 0 if it does not.
-
- Example:
-
- IN 'MYFILE'
-
- This line copies the whole APL2 transfer file, MYFILE.atf, into your active
- workspace.
-
- o To copy only part of a file (for example, some particular operators,
- functions, or variables) into your active workspace, call the IN function in
- either of the following ways:
-
- namelist IN 'filespec'
- or,
-
- IN 'filespec names'
-
- In namelist_matrix, you give the names of the operators, functions, and
- variables (APL2 objects) you want to copy. If there is more than one object,
- each name must be given as a row of a character matrix, as an element of a
- vector of character vectors, or in a character vector with each name
- separated by one or more blanks. Alternatively, the names can follow the
- filespec, separated from one another by one or more blanks. If a name is
- enclosed in parentheses, it is assumed to be the name of a character array
- (rank not greater than 2) containing a list of objects to be copied. For
- filespec, see above. Only the indicated objects are copied into the active
- workspace. The function returns a logical vector result-a 1 for each object
- copied and 0 for each object not copied.
-
- Example:
-
- (2 3ц'FUNVAR') IN 'MYFILE'
-
- The left argument of the IN function in this example is a 2-by-3 character
- matrix, in which the first row is FUN and the second is VAR. This line copies
- into your active workspace the objects (which can be operators, functions, or
- variables), FUN and VAR, from MYFILE.atf.
- Simulated )OUT
-
- ZΓò£[NL] OUT 'filespec'
- ZΓò£ OUT 'filespec names'
-
- This function emulates the )OUT command under the control of AP 210, and can be
- called from another APL2 function, thus effectively providing a powerful OUT
- facility. You can call this function in two different ways:
-
- o To copy your entire active workspace (all operators, functions, and
- variables) into an .atf file (that is, a transfer file), call the OUT
- function in the following way:
-
- OUT 'filespec'
-
- where filespec is the name of the transfer file. This can include an
- extension. If no extension is specified, a default extension of ".atf" will
- be used. The result is 1 if the operation is successful, or 0 otherwise.
-
- Example:
-
- OUT 'MYFILE'
-
- This line copies all operators, functions, and variables of your active
- workspace into the file MYFILE.atf.
-
- o To copy only part of your workspace (some particular operators, functions or
- variables) into a file, call the OUT function in either of the following
- ways:
-
- namelist OUT 'filespec'
- or,
-
- OUT 'filespec names'
-
- In namelist, you give the names of the operators, functions, and variables
- (APL2 objects) you want to copy. If there is more than one object, each name
- must be given as a row of a character matrix, as an element of a vector of
- character vectors, or in a character vector with each name separated by one
- or more blanks. Alternatively, the names can follow the filespec, separated
- from one another by one or more blanks. If a name is enclosed in parentheses,
- it is assumed to be the name of a character array (rank not greater than two)
- containing a list of objects to be copied. For filespec, see above. Only the
- indicated objects are included in the file. The function returns a logical
- vector result-1 for each object copied and 0 for each object not copied.
-
- Example:
-
- (2 3ц'FUNVAR') OUT 'MYFILE'
-
- The left argument of the OUT function in the preceding example is a 2-by-3
- character matrix, in which the first row is FUN and the second is VAR. This
- line creates a transfer file called MYFILE.atf and writes into it the objects
- FUN and VAR in the transfer form.
- Simulated )PIN
-
- ZΓò£[NL] PIN 'filespec'
- ZΓò£ PIN 'filespec names'
-
- This function imitates the )PIN command under the control of AP 210. It
- performs a protected IN, which works like IN except that an object is copied
- only if the object name in the active workspace has no current value.
-
-
- ΓòÉΓòÉΓòÉ 13.11. The GRAPHPAK Workspace ΓòÉΓòÉΓòÉ
-
- The GRAPHPAK workspace distributed with the APL2/2 product uses the AP 207
- Universal Graphics auxiliary processor to display results in an OS/2 window.
-
- GRAPHPAK is a powerful general-purpose graphical library. For a full
- description of GRAPHPAK, refer to APL2 GRAPHPAK: User's Guide and Reference.
-
- Users should be aware of the following differences between the APL2/2 AP 207
- version of GRAPHPAK, and GRAPHPAK as implemented under APL2/370:
-
- o Area fill may not fill some areas (such as a torus) in exactly the same way
- as the APL2/370 or APL2/PC versions of GRAPHPAK. In general, when multiple
- polygons are used, the fill is compatible, but when images include arcs or
- sectors, there may be discernible differences.
-
- o APL2/2 GRAPHPAK generates "stroked" characters as its default.
-
- o The SMFIELD function is not implemented.
-
- o APL2/2 permits the use of a mouse in addition to certain function keys when
- using the READ function discussed in the APL2 GRAPHPAK: User's Guide and
- Reference. When the left argument of READ is a null, and the intent is to do
- freehand drawings within the graphics window, the mouse buttons offer an easy
- alternative to the use of the cursor. Each button produces a different color.
- To draw freehand, place the mouse pointer where you wish to start and press a
- mouse button, then release it and move to the next position, and again press
- one of the mouse buttons. Alternatively, function keys may be used to draw
- the line, in a variety of colors and patterns. Repeat this procedure until
- you are finished, then press Enter.
-
- The APL2/2 GRAPHPAK workspace includes seven groups that form a set of
- functions implemented compatibly across all APL2 platforms.
-
- The seven groups are:
-
- GPBASE Contains the fundamental drawing and writing functions. This
- workspace contains the base code to use the AP 207 Universal
- Graphics auxiliary processor.
-
- GPCHT Contains functions for drawing charts.
-
- GPCONT Contains functions for drawing contour maps.
-
- GPDEMO Contains functions illustrating various aspects of GRAPHPAK. To
- start the demonstration, type DEMO.
-
- GPFIT Contains functions for curve fitting.
-
- GPGEOM Contains descriptive geometry functions.
-
- GPPLOT Contains plotting functions.
-
- The functions in each of these groups are described in the following sections:
-
- o GPBASE
- o GPCHT
- o GPCONT
- o GPDEMO
- o GPFIT
- o GPGEOM
- o GPPLOT
-
-
- ΓòÉΓòÉΓòÉ 13.11.1. GPBASE ΓòÉΓòÉΓòÉ
-
- This group contains the fundamental drawing and writing functions, and is
- required by all other GRAPHPAK workspaces. It contains the following functions:
-
- COLOR Changes the current color
-
- DRAW Draws lines between points
-
- ERASE Clears the screen
-
- FILL Fills a polygon
-
- FIXVP Sets the viewport
-
- GRFIELD Sets the graphics field
-
- INTO Used in coordinate transformations
-
- MODE Changes the current line mode (not functional, included for
- compatibility only)
-
- READ Reads coordinates or character data from the screen
-
- SMFIELD Sets the session manager field
-
- STYLE Changes the current fill or line style
-
- USE Permanently changes the current attributes (color and width)
-
- USING Temporarily changes the current attributes (color and width)
-
- VIEW Displays the current contents of the graphics field
-
- VIEWPORT Returns the coordinates of the corners of the current
- clipping viewport
-
- WIDTH Changes the current line mode
-
- WRITE Writes text on the current graphics field
-
- XFM Used in coordinate transformations
-
-
- ΓòÉΓòÉΓòÉ 13.11.2. GPCHT ΓòÉΓòÉΓòÉ
-
- This group contains functions for drawing charts. It requires GPBASE and
- GPPLOT, and the following functions are available:
-
- CHART Draws a bar or column chart
-
- FREQ Plots a frequency chart
-
- HCHART Plots a hierarchical chart
-
- PIECHART Draws a pie chart
-
- PIELABEL Labels a pie chart
-
- SAXES Plots all three default axes on a surface or skyscraper chart
-
- SAXISX Plots the X axis of a surface or skyscraper chart with
- definable labels and annotation
-
- SAXISY Plots the Y axis of a surface or skyscraper chart with
- definable labels and annotation
-
- SAXISZ Plots the Z axis of a surface or skyscraper chart with
- definable labels and annotation
-
- SLABEL Writes the default labels on the axes of a surface or
- skyscraper chart.
-
- SLBLX Places definable labels on the X axis of a surface or
- skyscraper chart
-
- SLBLY Places definable labels on the Y axis of a surface or
- skyscraper chart
-
- SLBLZ Places definable labels on the Z axis of a surface or
- skyscraper chart
-
- SS Plots a skyscraper chart
-
- STEP Plots a step chart
-
- STITLE Adds a title to a surface or skyscraper chart
-
- SURFACE Plots a surface chart
-
- SXFM Maps three-dimensional coordinates into a screen window
-
- WITH Formats data for use with PIECHART
-
-
- ΓòÉΓòÉΓòÉ 13.11.3. GPCONT ΓòÉΓòÉΓòÉ
-
- This group contains functions for drawing contour maps. It requires GPBASE and
- GPPLOT, and contains the following functions:
-
- BY Used to structure the input to CONTOUR
-
- CONTOUR Draws a contour map
-
- OF Used to structure the input to CONTOUR
-
-
- ΓòÉΓòÉΓòÉ 13.11.4. GPDEMO ΓòÉΓòÉΓòÉ
-
- This group contains functions illustrating many aspects of the APL2/2 version
- of GRAPHPAK. The demonstration can be started with the DEMO function, and it
- cycles through the complete set of demonstrations.
-
- The individual demonstration functions contained in this workspace are:
-
- APPLE Shows the use of DRAW to create a picture
-
- ATTRIBUTES Shows the various line type and fill options available
-
- BLI Shows the use of DRAW to create a picture
-
- CAYUGAPLOT Shows the use of PLOT to create line graphs
-
- DEMO Cycles through all the demo functions in the workspace
-
- FLAG Shows the use of DRAW to create a picture
-
- FSTAR Shows the use of DRAW to create a picture
-
- HEALTH Shows the use of CHART to produce a column chart
-
- IBMF Draws the IBM logo
-
- MILERUN Shows the use of CHART to produce a bar chart
-
- NHIST Shows the use of CHART to produce a step chart
-
- PIES Shows the use of CHART to produce a pie chart
-
- REVB Shows the use of CHART to produce a simple bar chart
-
- REVC Shows the use of CHART to produce a simple column chart
-
- REVENUES Shows the use of PLOT to create line graphs
-
- SKYSCRAPER Shows the use of SS to produce a skyscraper chart
-
- SPIRAL Shows the use of SKETCH, THREEVIEWS, and PERSPECTIVE to
- create pictures
-
- WAVEGUIDE Shows the use of SURFACE to produce a surface chart
-
- WGCONT Shows the use of SURFACE to produce a contour chart
-
-
- ΓòÉΓòÉΓòÉ 13.11.5. GPFIT ΓòÉΓòÉΓòÉ
-
- This group contains functions for curve fitting. It requires GPBASE and GPPLOT,
- and contains the following functions:
-
- AVG Prepares data for FIT to plot the average Y value
-
- CLEAR Clears the display screen
-
- FIT Draws a line graph through data points prepared by AVG, SL,
- POLY, EXP, LOG, POWER, LOGLOG, or SPLINE
-
- EXP Prepares data for FIT to plot the best log-linear fit on
- linear axes
-
- FITFUN Executes the last function plotted
-
- LOG Prepares data for FIT to plot the best log-linear fit on
- log-linear axes
-
- LOGLOG Prepares data for FIT to plot the best log-log fit on log-log
- axes
-
- POLY Prepares data for FIT to plot the best polynomial of
- specified degree
-
- POWER Prepares data for FIT to plot the best log-log fit on linear
- axes
-
- SCRATCH Erases points from a data array
-
- SL Prepares data from which FIT can plot the best straight-line
- fit
-
- SPLINE Prepares data for FIT to use in plotting a cubic spline
- through specified points
-
-
- ΓòÉΓòÉΓòÉ 13.11.6. GPGEOM ΓòÉΓòÉΓòÉ
-
- This group contains descriptive geometry functions. It requires GPBASE and
- GPPLOT, and contains the following functions:
-
- ISOMETRIC Restructures data so that SKETCH produces an isometric
- projection
-
- MAGNIFY Transforms a data array so that the object represented is
- magnified in size
-
- OBLIQUE Restructures data so that SKETCH produces an oblique
- projection
-
- PERSPECTIVE Restructures data so that SKETCH produces a perspective
- drawing
-
- RETICLE Draws an outline of the clipping viewport and a pair of axes,
- showing the extent of the window into problem space
-
- ROTATE Transforms a data array so that the object represented is
- rotated
-
- SCALE Scales all elements of a data array so that the largest lies
- within set bounds
-
- SKETCH Produces an orthogonal projection
-
- STEREO Produces a stereo pair of images of an object
-
- THREEVIEWS Produces three views of an object, projected into the planes
- of the axes
-
- TRANSLATE Transforms a data array so that the object represented is
- moved
-
-
- ΓòÉΓòÉΓòÉ 13.11.7. GPPLOT ΓòÉΓòÉΓòÉ
-
- This group contains plotting functions. It is required by GPFIT, GPCONT, and
- GPCHT, and requires GPBASE. It contains the following functions:
-
- AND Aids in formatting input for PLOT or SPLOT
-
- ANNX Draws an annotated horizontal axis with definable label
- positions
-
- ANNY Draws an annotated vertical axis with definable label
- positions
-
- AXES Draws default axes
-
- AXIS Draws definable axes
-
- HOR Draws an annotated horizontal axis with default label
- positions
-
- LABEL Produces the default labels for the X and Y axes
-
- LBLX Produces definable labels for the X axis
-
- LBLY Produces definable labels for the Y axis
-
- PLOT Plots a line graph
-
- RESTORE Restores all attribute and plotting variables to their
- default values
-
- SPLOT Similar to PLOT, but allows more user control over plotting
- characteristics
-
- TITLE Adds a title to the graph
-
- VER Draws an annotated vertical axis with default label positions
-
- VS Aids in formatting input for PLOT or SPLOT.
-
- To run the demonstration contained in the GRAPHPAK workspace, enter:
-
- )LOAD 2 GRAPHPAK
- DEMO
-
-
- ΓòÉΓòÉΓòÉ 13.12. The IDIOMS Workspace ΓòÉΓòÉΓòÉ
-
- APL2 is a very powerful and concise language. Although experienced APL2
- programmers can produce working solutions to complex problems in a very short
- time, learning the APL2 language can take years. The novice is usually
- entranced with the power of APL2, but may have a hard time thinking in vector
- notation. APL2 algorithms are not always obvious!
-
- In order to speed up the learning process of APL2, IDIOMS was developed. With
- over 600 distinct APL2 phrases, sorted into 24 general categories, IDIOMS
- represents a fairly complete list of solutions to common application problems
- and lets you take advantage of algorithms that many others have developed.
-
- Since this list is in soft copy, you can access it directly from your workspace
- and dynamically insert the idioms into your own code.
-
- o Executing the IDIOMS Function
-
-
- ΓòÉΓòÉΓòÉ 13.12.1. Executing the IDIOMS Function ΓòÉΓòÉΓòÉ
-
- ZΓò£IDIOMS
-
- Copy the IDIOMS function into your active workspace and then execute it:
-
- )PCOPY 1 IDIOMS IDIOMS
- IDIOMS
-
- You can run this program from your own workspace, because it does not overwrite
- any programs you use. All the subroutines are local functions loaded from the
- AP 211 object file, IDIOMS.aof. The IDIOMS function, as supplied, assumes that
- this IDIOMS.aof file is in the same directory as the library 1 workspaces. If
- this is not the case, edit the IDIOMS function to specify the appropriate
- directory.
-
- Selections are stored in a file called IDIOMS.asf, which is created
- automatically if it does not already exist. This is ordinarily created in the
- default home directory, but you can edit the IDIOMS function to specify the
- required directory.
-
- Once IDIOMS is executing, a full-screen interface gives you control over all
- the facilities available. The following keys can be used from the main screen.
- Use the F1 (Help) key to get assistance on the Window or Group screen.
-
- F1 Help - Display a series of screens that give assistance for the
- current screen.
-
- F2 Window - Display a window of previous searches. Move the cursor
- to the desired item and press Enter to select a search, which
- appears on the main screen. Press F3 to return to the main
- screen.
-
- F3 Return - Return to the APL2 session, passing any idioms selected
- with F9 to the workspace as an explicit result.
-
- F4 Function - Save the APL2 idiom identified by the cursor as a
- function called IDIOM_LIST. If IDIOM_LIST already exists, the
- selected idiom is appended as a new line to the end of the
- function. This function can be a prototype for a new program
- using the selected expressions to accomplish the desired task.
-
- F5 Local Search - Search the displayed group of idioms for the
- search argument. This can be used to narrow the search to a
- particular group of idioms.
-
- F6 Group - Display a list of each group of idioms. Place the cursor
- beside the desired group and press F6 again to select that
- group. Press F3 to return to the main screen without selecting a
- group.
-
- F7 PageUp - Scroll one screen toward the top.
-
- F8 PageDown - Scroll one screen toward the bottom.
-
- F9 Result - Append the idiom identified by the cursor to the result
- of the IDIOMS function. Using the session manager, you can place
- these lines in your function by entering function definition
- mode and then inserting a line number [n] at the beginning of
- each desired idiom.
-
- F10 Environment - Cycle environment for which appropriate idioms are
- displayed. Note that idioms selected from other than the
- workstation environment may not work on APL2/2.
-
- Shift-F7 Home - Scroll to the top.
-
- Shift-F8 End - Scroll to the bottom.
-
- PageUp Scroll one screen toward the top.
-
- PageDown Scroll one screen toward the bottom.
-
- Home Scroll to the top.
-
- End Scroll to the bottom.
-
- Enter Search through all the idioms for the search argument.
-
- The idioms are available in either index origin. The IDIOMS program lets you
- select the index origin preferred for the code you are writing. To change the
- origin, overtype the displayed value with the desired index origin and press
- Enter.
-
- To trace the searches that you generate, IDIOMS calls itself recursively. You
- can do multiple searches, without losing the results of any intermediate
- search.
-
- o Categories
- o Naming Conventions
-
-
- ΓòÉΓòÉΓòÉ 13.12.1.1. Categories ΓòÉΓòÉΓòÉ
-
- To facilitate fast selection of idioms, they are grouped into categories, as
- follows:
-
- 1 - Assignment algorithms
- 2 - Boolean selection algorithms
- 3 - Boolean tests general algorithms
- 4 - Boolean tests numeric algorithms
- 5 - Computational algorithms
- 6 - Conversion algorithms
- 7 - Date and time algorithms
- 8 - External name routine algorithms
- 9 - Financial algorithms
- 10 - Formatting algorithms
- 11 - Function algorithms
- 12 - Manipulating characters algorithms
- 13 - Manipulating numbers algorithms
- 14 - Numeric range algorithms
- 15 - Numerical geometry algorithms
- 16 - Selecting positions algorithms
- 17 - Sorting algorithms
- 18 - Statistics descriptive algorithms
- 19 - Statistics distribution algorithms
- 20 - Structural algorithms
- 21 - Text arrangement algorithms
- 22 - Text selection and change algorithms
- 23 - Trigonometry algorithms
- 24 - Vectorizing algorithms
-
-
- ΓòÉΓòÉΓòÉ 13.12.1.2. Naming Conventions ΓòÉΓòÉΓòÉ
-
- A consistent naming convention is used throughout the list. The names used are:
-
- These are combined in various ways to identify the type of object. For example:
-
-
- ΓòÉΓòÉΓòÉ 13.12.1.2.1. IDIOMS Naming convention ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Rank
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Type
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Usage
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- A
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Array
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- B
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Boolean
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- G
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Graded or grouped
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- M
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Matrix
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- C
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Character
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- L
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Lengths
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- O
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- One item vector
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- F
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Floating point
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- P
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Positions
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- S
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Scalar or one item vector
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- I
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Integer
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- U
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Unique
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- V
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Vector
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- N
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Numeric
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- X
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Extension
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Z
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Complex
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Y
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Extension
-
-
- ΓòÉΓòÉΓòÉ 13.12.1.2.2. IDIOMS Name Examples ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Name
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Contents
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Name
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Contents
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- A,AX,AY
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- General arrays
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- IM
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Integer matrix
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- BM
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Boolean matrix
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- N,NX,NY
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Numeric vectors
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- BS
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Boolean scalar
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- PAV
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Position array of vectors
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- CA
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Character array
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- PS
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Position scalar
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- C,CX,CY
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Character vectors
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- UM
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Unique matrix
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- GAF
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Graded array of floating point
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- VM
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Vector of matrices
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- GI
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Graded integer vector
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- VV
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Vector of vectors
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- GM
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Graded matrix
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- V,X,Y
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- General vectors
-
-
- ΓòÉΓòÉΓòÉ 13.13. The MATHFNS Workspace ΓòÉΓòÉΓòÉ
-
- The functions in this workspace are described below.
-
- o Matrix Inverse and Matrix Divide
- o Eigenvalues and Eigenvectors
- o Factorial and Binomial
- o Fast Fourier Transform
- o Formatting Complex Numbers
- o Roots of Polynomials
-
-
- ΓòÉΓòÉΓòÉ 13.13.1. Functions in the MATHFNS Workspace ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- DOMINO Computes matrix inverse or matrix divide
- DOMINOF Computes matrix inverse or matrix divide (fast)
- EIGEN Computes eigenvalues and eigenvectors
- EIGENVALUES Computes eigenvalues
- FACTORIAL Computes factorials and binomials
- FFT Computes fast Fourier transform
- FMTPD Formats in polar form with angular measure in degrees
- FMTPR Formats in polar form with angular measure in radians
- IFFT Computes inverse fast Fourier transform
- POLYZ Computes the zeros of polynomials
-
-
- ΓòÉΓòÉΓòÉ 13.13.2. Matrix Inverse and Matrix Divide ΓòÉΓòÉΓòÉ
-
- Z╜ DOMINO R ф Matrix inverse
- Z╜L DOMINO R ф Matrix divide
- Z╜ DOMINOF R ф Matrix inverse (fast)
- Z╜L DOMINOF R ф Matrix divide (fast)
-
- These two functions provide a direct replacement for the matrix inverse and
- matrix divide (Т) primitive when applied to arguments containing complex
- numbers. DOMINO is a direct APL2 implementation of the algorithm used by the
- primitive Т function of APL2/370. By applying the primitive Т function of
- APL2/2 to combinations of the real and imaginary parts of its arguments,
- DOMINOF produces results equivalent to those given by the DOMINO function. This
- is usually faster than DOMINO, but the intermediate applications of the
- primitive APL2/2 Т function may fail for some arguments.
-
-
- ΓòÉΓòÉΓòÉ 13.13.3. Eigenvalues and Eigenvectors ΓòÉΓòÉΓòÉ
-
- ZΓò£ EIGEN R
- ZΓò£L EIGEN R
-
- The right argument R must be a simple square matrix of real numbers. Z is a
- simple real or complex matrix of shape 1 0+цR containing the eigenvalues and
- the eigenvectors of R. If R has shape N by N, then Z has N+1 rows and N
- columns. The first row of Z contains the eigenvalues of R, and the remaining
- rows of Z contain the corresponding right eigenvectors of R. That is, each
- column of Z contains an eigenvalue and its corresponding right eigenvector.
-
- EIGEN 2 2ц1 0 0 2
- 1 2
- 1 0
- 0 1
-
- The eigenvalues X and the right eigenvectors V can be obtained by:
-
- ZΓò£EIGEN R
- XΓò£Z[1;]
- VΓò£1 0ΓòƒZ
-
- These statements obey the identity:
-
- Xї[2]V ╜╕ R+.їV
-
- The eigenvalues X and the left eigenvectors V can be obtained by:
-
- Z╜э EIGEN эR
- XΓò£Z[;1]
- VΓò£0 1ΓòƒZ
-
- They obey the identity:
-
- Xї[1]V ╜╕ V+.їR
-
- In the dyadic case, L is also a simple square matrix of real numbers, and цL
- equals цR. Z is a simple real or complex matrix of shape 1 0+цR containing the
- solution to the generalized eigenvalue problem for L and R:
-
- ZΓò£L EIGEN R
- XΓò£Z[1;]
- VΓò£1 0ΓòƒZ
-
- They obey the identity:
-
- (L+.їX)ї[2]V ╜╕ R+.їV
-
- The eigenvalues and eigenvectors are computed by using the "QZ Algorithm". (See
- "An Algorithm for Generalized Matrix Eigenvalue Problems" by C.B. Moler and
- G.W. Stewart, SIAM Journal of Numerical Analysis, 10: 241-256, 1973.) The
- numerical accuracy of the result depends upon the "condition" of the matrix of
- eigenvectors. In particular, accuracy may be degraded if there are repeated
- eigenvalues.
-
- ZΓò£ EIGENVALUES R
- ZΓò£L EIGENVALUES R
-
- This function takes the same arguments as EIGEN but returns only the
- eigenvalues. It is faster than the EIGEN function for the same inputs, and can
- be used whenever the full result is not required.
-
-
- ΓòÉΓòÉΓòÉ 13.13.4. Factorial and Binomial ΓòÉΓòÉΓòÉ
-
- Z╜ FACTORIAL R ф Factorial
- Z╜L FACTORIAL R ф Binomial
-
- This function provides a direct replacement for the primitive factorial or
- binomial (!) function when applied to arguments containing complex numbers.
- FACTORIAL is a direct APL2 implementation of the algorithm used by the
- primitive ! function of APL2/370.
-
-
- ΓòÉΓòÉΓòÉ 13.13.5. Fast Fourier Transform ΓòÉΓòÉΓòÉ
-
- Z╜FFT R ф Fast Fourier Transform
-
- This function computes the discrete Fourier transform of a set of numbers R.
-
- The right argument R is a simple vector of 2*N complex or real numbers where N
- is a positive integer. The result Z is a simple vector of 2*N complex numbers
- with the discrete Fourier transform of R.
-
- The result of the FFT function corresponds to that of the discrete Fourier
- transform as defined by SC23-0526, Engineering and Scientific Subroutine
- Library, Guide and Reference:
-
- Z╜IFFT R ф Inverse Fast Fourier Transform
-
- This function computes the inverse Fourier transform of a set of numbers R.
-
- R Γò£Γòò IFFT FFT R
-
- The right argument R is a simple vector of 2*N complex or real numbers where N
- is a positive integer. The result Z is a simple vector of 2*N complex numbers
- with the inverse discrete Fourier transform of R.
-
- The IFFT function differs only in scale and phase.
-
- For example:
-
- IFFT 2 0J1 0 0J¤1
- 0.5 1 0.5 0
- IFFT 2 1 0 1
- 1 0.5 0 0.5
-
-
- ΓòÉΓòÉΓòÉ 13.13.6. Formatting Complex Numbers ΓòÉΓòÉΓòÉ
-
- Z╜FMTPD R ф ForMaT Polar Degrees
-
- This function formats complex numbers in the right argument R in polar form,
- with angular measure in degrees. Z is a simple character array.
-
- Z╜FMTPR R ф ForMaT Polar Radians
-
- This function formats complex numbers in the right argument R in polar form,
- with angular measure in radians. Z is a simple character array.
-
-
- ΓòÉΓòÉΓòÉ 13.13.7. Roots of Polynomials ΓòÉΓòÉΓòÉ
-
- Z╜POLYZ R ф POLYnomial Zeros
-
- The right argument R must be a simple nonempty vector of real or complex
- numbers, and must not contain leading zeros. R represents a polynomial with
- coefficients in decreasing order of powers (constant on the right). Z is a
- simple vector of shape ¤1+цR, containing the zeros of the polynomial R.
-
- If F is the polynomial represented by R, and F(x) = + + Cx + D, then R is the
- vector (A B C D). If the result Z is the vector (P Q R), then F(x) =
- (x-P)(x-Q)(x-R). If R is real, and the length of R is even, then Z contains at
- least one real number.
-
- POLYZ ¤ 2 1
- 0 . 5
- POLYZ 2 0J1
- 0J ¤ 0 . 5
- POLYZ 1 ¤ 2 1
- 1 1
- POLYZ 1 0 1
- 0J1 0J ¤ 1
- POLYZ 1 ¤ 6 11 ¤ 6
- 1 2 3
- POLYZ 1 ¤ 20 154 ¤ 584 1153 ¤ 1124 420
- 1 1 . 999999978 2 . 000000022 3 5 7
-
- The zeros are computed using the Jenkins and Traub algorithms. The accuracy of
- the solution depends on the "condition" of the polynomial. In particular,
- accuracy can be degraded if there are repeated zeros. Also, numerical roundoff
- can cause a pair of equal real zeros to appear as a complex conjugate pair.
-
- POLYZ uses subroutines POLYZC and POLYZF.
-
-
- ΓòÉΓòÉΓòÉ 13.14. The MIGRATE Workspace ΓòÉΓòÉΓòÉ
-
- The MIGRATE workspace contains functions useful in migrating workspaces from
- other APL2 platforms.
-
- ATFUSTOLC A
-
- Takes the name of a transfer form file that has been binary downloaded from
- APL2/370, and changes all the underbarred letters to the equivalent lowercase
- characters.
-
- This differs from using CASE(1) or CASE(2) on the host before creating and
- downloading a transfer file, in that this converts underbarred letters even in
- literal constants, function or operator comments, and arrays.
-
- VSCOPY A
-
- VSCOPY is a function that makes it possible for objects from a VS APL workspace
- (saved with the VS APL )SAVE command as a CMS file or a TSO data set, and then
- binary downloaded to an OS/2 file) to be copied directly into the active
- workspace of APL2/2. The full syntax of VSCOPY is:
-
- VSCOPY 'wsname [object_list]'
-
- where:
-
- wsname The workspace name. If no extension is given, a default
- extension of .VWS is appended. If the name contains one or
- more dots or is enclosed in quotes, it is used exactly as
- given.
-
- object_list The list of names of objects to be copied. This may be
- omitted, in which case all objects in the workspace are
- copied.
-
- Groups are copied in as character arrays, with each name represented as a row
- in the array. The names of all groups copied are added into the variable grps.
-
- Object names may be prefixed by an asterisk ("*"):
-
- *function_name Causes the function to be left in its canonical form
-
- *group_name Causes the group definition, but not its contents to be
- copied
-
- *variable_name Causes the variable to be left untranslated
-
-
- ΓòÉΓòÉΓòÉ 13.15. The OS2 Workspace ΓòÉΓòÉΓòÉ
-
- The OS2 workspace uses AP 100 to invoke some useful OS/2 commands. Except where
- noted, these are monadic functions. All functions return either 0 or data if
- successful. They return a numeric error code if an error occurs. The functions
- available are:
-
- ZΓò£DIR path
-
- DIR returns a directory list. This is equivalent to the OS/2 "DIR" command. The
- right argument, path, is the path leading to the directory whose contents are
- to be displayed.
-
- ZΓò£ERASE FN
-
- ERASE erases a file. The right argument, FN, has the form 'filename', where
- 'filename' is the name of the file to be erased, and can include a path
- definition.
-
- ZΓò£HOST 'cmd'
-
- Issues command "cmd" to OS/2 through AP 100. When HOST '' is executed on
- APL2/2, it returns "OS/2", which can be used to identify the operating system.
-
- ZΓò£LIBS
-
- Returns a character matrix giving the definition of each valid library number.
-
- ZΓò£MKDIR path
-
- MKDIR creates a new subdirectory.
-
- ZΓò£CMD PIPE DATA
-
- The PIPE function provides a means to pipe APL2 data to an OS/2 command and
- returns any output generated by the command.
-
- The right argument, DATA, must be either a simple character vector, a character
- matrix, or a vector of character vectors specifying the input to be passed to
- the command as "stdin" (standard input). If this is an empty vector, no input
- is passed to the command. The left argument, CMD, must be a simple character
- vector specifying the command to be executed. The result is a vector of vectors
- containing the output "stdout" (standard output) generated by executing the
- command. Some examples of the use of the PIPE function:
-
- To get names of APL workspaces and transfer files, sorting by date:
-
- у'dir /b/od *.atf *.apl' PIPE ''
-
- To run batch scripts through the interpreter:
-
- JOB1Γò£')LOAD 1 DISPLAY' 'DISPLAY ''APL2'' 123'
- JOB2╜')LOAD 2 OS2' '╖PIPE[Р]╖'
- OUTPUT╜(т'apl2 -sm piped -quiet on')PIPE■JOB1 JOB2
-
- ZΓò£RENAME ONFN ZΓò£OFN RENAME NFN
-
- RENAME renames a file. The right argument, ONFN, has the form 'oldname newname'
- where oldname is the name of the file to be renamed (and may include a path
- definition), and newname is the new name by which the file is to be known.
- RENAME can also be used dyadically, with the old name as the left argument and
- the new name as the right argument.
-
- ZΓò£RMDIR path
-
- RMDIR removes the subdirectory pointed to by path.
-
-
- ΓòÉΓòÉΓòÉ 13.16. The PMTOOLS Workspace ΓòÉΓòÉΓòÉ
-
- This workspace contains tools for building Presentation Manager applications.
- The general classes of functions are:
-
- o Dialog building functions
- o DLL and dialog processing functions
- o Printing functions
- o Utility functions
-
- o Dialog Building Functions
- o DLL and Dialog Processing Functions
- o Printing Functions
- o Utility Functions
-
-
- ΓòÉΓòÉΓòÉ 13.16.1. Dialog Building Functions ΓòÉΓòÉΓòÉ
-
- The dialog building functions provide an interface from APL2 to the dialog
- editor, linkage editor, and resource compiler that are included in the OS/2
- Developer's Toolkit product.
-
- DLGEDIT NAME
- Invokes the dialog editor on resource file NAME
-
- CREATEDLL NAME
- Creates dynamic link library NAME
-
- COMPILERES NAME
- Compiles resource file NAME into DLL NAME
-
-
- ΓòÉΓòÉΓòÉ 13.16.2. DLL and Dialog Processing Functions ΓòÉΓòÉΓòÉ
-
- The DLL and dialog processing functions allow an application to easily access
- dialog resources in DLLs.
-
- HMODULEΓò£LOADDLL NAME
- Loads DLL NAME and returns its handle, HMODULE.
-
- HANDLEΓò£HMODULE LOADDLG ID
- Loads dialog ID from loaded DLL HMODULE; returns dialog HANDLE
-
- DESTROYDLG HANDLE
- Destroys dialog HANDLE
-
- FREEDLL HMODULE
- Frees loaded DLL HMODULE
-
- RESULTΓò£ID TESTDLG NAME
- Loads and processes dialog ID from DLL NAME. Returns value established
- by WinDismissDlg.
-
- HWND MOVEWINDOW XY
- Moves window with handle HWND to coordinates XY.
-
-
- ΓòÉΓòÉΓòÉ 13.16.3. Printing Functions ΓòÉΓòÉΓòÉ
-
- The printing functions allow applications to produce printed documents.
-
- The functions correspond to the messages that APL2 print objects process. APL2
- print objects are documented in the APL2 Presentation Manager Services section.
-
- CREATE_PRINTER
- Creates a logical printer
-
- SELECT_PRINTER
- Displays the print queue selection dialog
-
- OPEN_DOCUMENT
- Starts a print job
-
- PRINT_SENTENCE
- Adds a sentence to a print job
-
- SET_COLOR
- Sets the color of the body of the document
-
- SET_FONT
- Sets the font for a section of the document
-
- SET_INDENT
- Sets the indentation amount
-
- SET_MARGIN
- Sets the inside margin (used when output is duplex)
-
- SET_WORDBREAK
- Enables or disables wordbreak
-
- SET_LINESPACE
- Enables or disables interline spacing
-
- SET_HEADING
- Sets the running heading
-
- SET_FOOTING
- Sets the running footing
-
- SET_PAGENUMBERS
- Enables or disables page numbering
-
- NEWLINE
- Starts a new line
-
- NEWPAGE
- Starts a new page
-
- CLOSE_DOCUMENT
- Completes a print job
-
- CANCEL_DOCUMENT
- Cancels a print job
-
- DESTROY_PRINTER
- Destroys a logical printer
-
- QUERY_PAGENUMBER
- Returns the current page number
-
- QUERY_LENGTH
- Returns the length, in points, of a string
-
-
- ΓòÉΓòÉΓòÉ 13.16.4. Utility Functions ΓòÉΓòÉΓòÉ
-
- The utility functions perform common user interface tasks.
-
- APLEDIT 'NAME'
- Uses Apledit to edit a function or operator
-
- APLEXECPGM CMD
- Executes an OS/2 command
-
- RESPONSEΓò£PROMPT TEXT
- Displays prompt TEXT and returns the user's response.
-
- SELECTIONΓò£SELECT_1 MATRIX
- Prompts the user to select one item from a matrix
-
- SELECTIONΓò£SELECT_SOME MATRIX
- Prompts the user to make selections from a matrix
-
- EDITEDMATRIXΓò£EDIT MATRIX
- Allows the user to edit a character matrix
-
-
- ΓòÉΓòÉΓòÉ 13.17. The PMWIN Workspace ΓòÉΓòÉΓòÉ
-
- This workspace contains variables corresponding to the constants defined in the
- OS/2 Developer's Toolkit header files. These constants are used by Presentation
- Manager applications and refer to message identifiers and codes, and OS/2
- service flags.
-
- Variables corresponding to the messages and flags used with the APL2
- Presentation Manager services are also provided.
-
-
- ΓòÉΓòÉΓòÉ 13.18. The PRINTWS Workspace ΓòÉΓòÉΓòÉ
-
- The PRINTWS workspace provides a means for printing the contents of the active
- workspace. It produces a listing of all the variables, functions, and operators
- in the workspace.
-
- The only function in the workspace is called PRINTWS. To use it:
-
- )LOAD your workspace
- )PCOPY 2 PRINTWS PRINTWS
- PRINTWS
- You are prompted to select a printer and to set the print job properties.
-
- PRINTWS creates and uses an APL print object. Print objects are described in
- APL2/2 Presentation Manager Services. Cover functions for using print objects
- are provided in the PMTOOLS workspace described in The PMTOOLS Workspace.
-
- o Limitations of PRINTWS
-
-
- ΓòÉΓòÉΓòÉ 13.18.1. Limitations of PRINTWS ΓòÉΓòÉΓòÉ
-
- The PRINTWS function has the following limitations:
-
- o This function does not print objects with names that begin with ў_. It is
- implemented this way to prevent conflicts with the names that are used within
- PRINTWS.
-
- o Output generated by the PRINTWS function does not include a display of its
- own code.
-
- o PRINTWS requires that the PMTOOLS workspace be installed in library 2.
-
-
- ΓòÉΓòÉΓòÉ 13.19. The SQL Workspace ΓòÉΓòÉΓòÉ
-
- The SQL workspace enables you to execute SQL statements or retrieve information
- from AP 127. The following section lists the functions provided with the SQL
- workspace. For additional information about the SQL workspace, see APL2
- Programming: Using Structured Query Language.
-
- o Functions
-
-
- ΓòÉΓòÉΓòÉ 13.19.1. Functions ΓòÉΓòÉΓòÉ
-
- SQL Workspace Functions summarizes the SQL workspace functions and the defined
- operator (UNTIL). It gives their syntax and indicates the equivalent AP 127
- operations if they exist.
-
-
- ΓòÉΓòÉΓòÉ 13.19.1.1. SQL Workspace Functions - Part 1 ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Function Name and Syntax
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- AP 127 Operation
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- CALL name [values]
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 'CALL'
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- CLOSE name
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 'CLOSE'
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- COMMIT
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 'COMMIT'
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- CONNECT 'RESET'Γöédatabase ['SHARE'Γöé'EXCLUSIVE']
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 'CONNECT'
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- f DATE t
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- DECLARE name ['HOLD']
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 'DECLARE'
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- DESC name [type]
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 'DESCRIBE'
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- EVAL data
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- EVALSIM data
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- EXEC stmt
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 'EXEC'
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- FETCH name [options..]
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 'FETCH'
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- GETOPT
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 'GETOPT'
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- IN
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 'IN'
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- ISOL setting
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 'ISOL'
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- MORE...
-
-
- ΓòÉΓòÉΓòÉ 13.19.1.2. SQL Workspace Functions - Part 2 ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Function Name and Syntax
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- AP 127 Operation
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- MESSAGE rcode
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 'MSG'
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- NAMES
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 'NAMES'
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- OFFER
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- OPEN name [values]
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 'OPEN'
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- PREP name stmt
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 'PREP'
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- PURGE name
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 'PURGE'
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- QUE stack
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- QUERY name [values]
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- RESUME stack
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- ROLLBACK
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 'ROLLBACK'
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- SETOPT options..
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 'SETOPT'
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- SHOW result
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- SQL stmt [values]
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- SQLCA
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 'SQLCA'
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- SQLSTATE
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 'SQLSTATE'
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- MORE...
-
-
- ΓòÉΓòÉΓòÉ 13.19.1.3. SQL Workspace Functions - Part 3 ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Function Name and Syntax
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- AP 127 Operation
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- STATE name
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 'STATE'
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- STMT name
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 'STMT'
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- f TIME t
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- TIMESTAMP t
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- (F UNTIL) stack
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ 13.20. The TIME Workspace ΓòÉΓòÉΓòÉ
-
- The TIME workspace contains the TIME function, to assist with the performance
- monitoring and tuning of APL2 code.
-
- The performance monitoring facility provides the capability to measure a
- running application and determine the CPU time used by each defined program,
- each line within each defined program, or both.
-
- The facility works by associating with each line of each defined program, a
- pair of counters to record the number of times the line is executed and the
- total CPU time consumed by the line.
-
- Typically, timing information can be obtained for an application as follows:
-
- )LOAD workspace
- )PCOPY 1 TIME TIME ф To gain access to the facility
- TIME 0 ф To enable and zero counters
- ф (Run application here)
- TIME 1 ф To see times for program run
- ф (Analyze timing information here)
- TIME 2 ф To see times for each line
- ф (Analyze timing information here)
- )CLEAR ф When time analysis is complete
-
- Use of the timing facility requires space in the workspace for the counters and
- also increases running time by some small amount. Thus, in general you should
- not )SAVE after doing a time analysis.
-
- ZΓò£TIME N
-
- TIME 0 Enable timing and create counters for all lines in all unlocked
- programs. The counters are set to zero.
-
- TIME 1 Fetch times for all programs for which timing has been gathered
- and return a matrix containing for each function or operator
- actually executed, the number of times the function or operator
- was executed, the total CPU time used by the function or operator,
- the percentage of the CPU time used by the function or operator,
- and the name of the program. If column headings are desired, the
- following may be used:
-
- HD1Γò£'COUNT' 'TIME' '%' 'PROGRAM'
- HD1,[РIO] TIME 1
-
- Three heading vectors-HD1, HD2, and HD3-are already defined in the
- workspace, with the values shown here.
-
- The figure given for the number of times each program is executed
- is based on the assumption that this count is the same as that for
- the first executable (noncomment) line of the program.
-
- TIME 2 Fetch times for all lines of all programs for which timing has
- been accumulated. The result is a matrix of the same format as
- TIME1 except the line from the function or operator is also
- listed. If column headings are desired, the following may be used:
-
- HD2Γò£'COUNT' 'TIME' '%' 'PROGRAM' 'STMT'
- HD2,[РIO] TIME 2
-
- Each of the above uses of TIME also accepts an optional left argument that must
- be a character list of names. If provided, the left argument limits the scope
- of TIME to the programs named in the left argument.
-
- Additional uses of the TIME function are:
-
- TIME 3 Fetch times for all lines of all programs even if no timing has
- been accumulated. The result is a matrix of the same columnar
- format as TIME 2 and is sequenced by line within each function or
- operator. A left argument can be used to obtain the timing for the
- specified programs. If column headings are desired, the following
- can be used:
-
- HD3Γò£'COUNT' 'TIME' '%' 'PROGRAM' 'STMT'
- HD3,[РIO] TIME 3
-
- TIME ¤1 Enable timing. If timing has been disabled, timing is resumed. A
- left argument is not allowed for TIME ¤1.
-
- TIME ¤2 Disable timing. Stops the accumulation of timing data. A left
- argument is not allowed for TIME ¤2.
-
- TIME ¤3 Deletes the space used by the counters. A name list left argument
- is allowed and can be used to delete the timing data for selected
- functions and operators.
-
- Use of the timing facility increases space utilization and execution time.
- Reported timings are approximate and should only be used for relative
- comparisons, not absolute times.
-
- When a program is erased, its counters are deleted. When a program is created
- or changed, its counters are not preserved.
-
- o Performance Analysis Using the TIME Function
-
-
- ΓòÉΓòÉΓòÉ 13.20.1. Performance Analysis Using the TIME Function ΓòÉΓòÉΓòÉ
-
- The theory behind performance tuning through the TIME facility is that very
- often a small amount of code within an application consumes the majority of CPU
- cycles. By quickly identifying these "hot spots", the programmer can focus his
- attention on optimizations that provide the greatest effect in reducing overall
- application CPU time. The following APL2/2 session demonstrates the use of
- TIME:
-
- )LOAD COSTEST
- SAVED 1993-09-19 14.13.20 COSTEST
- )PCOPY 1 TIME TIME ф Fetch TIME function
- SAVED 1993-12-02 12.00.00 TIME
- TIME 0 ф Zero time counters
- ESTIMATE 10 ф Run the application
- COMPLETED... SEE ΓûáCOST_REPORTΓûá
- Р╜T╜TIME 1 ф Fetch time summary
- 500 31.19 72.83469164 PRODCOST
- 500 7.4 17.28043341 CHARGE
- 10 3.627 8.469747566 CALC
- 500 0.208 0.4857202905 EVAL
- 10 0.196 0.457697966 PC
- 10 0.103 0.2405249515 STORE
- 1 0.05 0.1167596852 ESTIMATE
- 1 0.044 0.102748523 TIME
- 10 0.004 0.009340774817 FINDMAX
- 10 0.001 0.002335193704 GETNEXT
- 1 0 0 CLOSE
- 1 0 0 OPEN
- +/T[;2] ф Compute total CPU time
- 42.823
- 'PRODCOST' TIME 2 ф Fetch time detail
- 500 31.028 99.48060276 PRODCOST[2] PCOST╜SCHG°.їьWEEKS
- 500 0.162 0.5193972427 PRODCOST[1] SCHGΓò£CHARGE N
-
- The TIME 1 report identifies the function PRODCOST as the major CPU consumer,
- attributable to about 73% of the total CPU time (31.19 of the total CPU 42.823
- seconds for this small sample run). Further analysis of the PRODCOST function
- with the TIME 2 report shows that the mathematical calculation performed in
- line 2 is the best target for potential performance improvement.
-
-
- ΓòÉΓòÉΓòÉ 13.21. The UTILITY Workspace ΓòÉΓòÉΓòÉ
-
- This section describes the UTILITY workspace.
-
- o Introduction
- o GPDATACV: Converting Between External and Internal Representations
- o GPMISC: Miscellaneous Utility Functions
- o GPSTRIP: Removing Comments
- o GPSVP: Controlling Communication through SVP
- o GPTEXT: Manipulating Text
- o GPTRACE: Setting and Removing Trace and Stop Vectors
- o GPXLATE: Translating from One Character Representation to Another
-
-
- ΓòÉΓòÉΓòÉ 13.21.1. Introduction ΓòÉΓòÉΓòÉ
-
- The UTILITY workspace is made up of defined functions organized into groups of
- functions. The groups are listed in the next section and described in the
- sections that follow.
-
- The two major ways in which you are likely to find the UTILITY workspace useful
- are:
-
- o Functional
- o Instructional
-
- The functional use is relatively straightforward:
-
- o Copy the objects you need from the UTILITY workspace into the active
- workspace
- o Use the UTILITY functions as "pseudo-primitives" in your own defined
- functions.
-
- The instructional use may not be as obvious but may be even more important.
- Instructionally, you can use the UTILITY workspace to:
-
- o Acquire familiarity with APL2 by experimenting with the functions in the
- UTILITY workspace, listing and reading them, trying to deduce what each
- statement does and why you might choose that particular way to do it.
-
- o Develop your APL2 programming skills by modifying the functions to improve
- their efficiency or to add features you need.
-
- o Extend your programming skills by adding complementary utility functions that
- you find useful.
-
- This workspace is of most use to you if you try to use it for both functional
- and instructional purposes.
-
-
- ΓòÉΓòÉΓòÉ 13.21.2. GPDATACV: Converting Between External and Internal Representations ΓòÉΓòÉΓòÉ
-
- o LI/LO - Boolean (Logical)
- o II/IO - System/370 Integer
- o PCII/PCIO - IBM PC Integer
- o FI/FO - System/370 Floating Point
- o IEEEFI/IEEEFO - IEEE Floating Point
- o PCFI/PCFO - IBM PC Floating Point
- o PDI/PDO - Packed Decimal
-
-
- ΓòÉΓòÉΓòÉ 13.21.2.1. LI/LO - Boolean (Logical) ΓòÉΓòÉΓòÉ
-
- Z╜LI R ф Logical In
-
- R is a simple character array whose last axis contains IBM PC or System/370
- logical data; that is, a string of bits.
-
- Z is a numeric array consisting of zeros and ones representing the logical data
- in R. The rank of Z is the same as the rank of R, but the last axis is 8 times
- as long as the last axis of R. A scalar value for R produces an 8-element
- vector.
-
- цZ ╜╕ (¤1╟цR),8ї¤1╞1,цR
-
- Z╜LO R ф Logical Out
-
- R is a simple numeric array consisting of only zeros and ones. The length of
- its last axis must be a multiple of 8.
-
- Z is a character array whose last axis contains the IBM PC or System/370
- representation of the logical data in the last axis of R. The rank of Z is the
- same as the rank of R, but the length of the last axis of Z is one-eighth of
- the last axis of R.
-
- цZ ╜╕ (¤1╟цR),(¤1╞цR)Ў8
-
-
- ΓòÉΓòÉΓòÉ 13.21.2.2. II/IO - System/370 Integer ΓòÉΓòÉΓòÉ
-
- Z╜II R ф Integers In
-
- R is a simple character array whose last axis must have a length of between 1
- and 7 inclusive, and which contains the System/370 binary representations of
- integers.
-
- Z is an array of integers representing the binary numbers in R. The rank of Z
- is one less than the rank of R.
-
- цZ ╜╕ ¤1╟цR
-
- Z╜L IO R ф Integers Out
-
- R is a simple array of integers. L is an integer scalar not greater than 7. It
- gives the number of bytes in which each integer is to be represented. L must be
- large enough to represent the largest magnitude of the integers in R.
-
- Z is a character array whose last axis contains the System/370 binary
- representation of the integers in R. The rank of Z is one greater than the rank
- of R.
-
- цZ ╜╕ (цR),L
-
-
- ΓòÉΓòÉΓòÉ 13.21.2.3. PCII/PCIO - IBM PC Integer ΓòÉΓòÉΓòÉ
-
- Z╜PCII R ф PC Integers In
-
- R is a simple character array whose last axis must have a length of 1, 2 or 4,
- and which contains the IBM PC (reversed) binary representations of integers.
-
- Z is an array of integers representing the binary numbers in R. The rank of Z
- is one less than the rank of R.
-
- цZ ╜╕ ¤1╟цR
-
- Z╜L PCIO R ф PC Integers Out
-
- R is a simple array of integers. L is an integer scalar with a value of 1, 2 or
- 4, and gives the number of bytes in which each integer is to be represented. L
- must be large enough to represent the largest magnitude of the integers in R.
-
- Z is a character array whose last axis contains the IBM PC (reversed) binary
- representation of the integers in R. The rank of Z is one greater than the rank
- of R.
-
- цZ ╜╕ (цR),L
-
-
- ΓòÉΓòÉΓòÉ 13.21.2.4. FI/FO - System/370 Floating Point ΓòÉΓòÉΓòÉ
-
- Z╜FI R ф Floating In
-
- R is a simple character array, the last axis of which must have a length of 4
- or 8. The last axis thus represents either single- or double-precision
- System/370 floating-point numbers.
-
- Z is an array of numbers equivalent to the floating-point representations in R.
- The rank of Z is one less than the rank of R.
-
- цZ ╜╕ ¤1╟цR
-
- Z╜FO R ф Floating Out
-
- R is a simple numeric array. Z is a character array whose last axis has length
- 8, and which contains the System/370 double-precision floating-point
- representations of the numbers in R. The rank of Z is one greater than the rank
- of R. If single precision is required, then drop the last four columns of the
- result.
-
- цZ ╜╕ (цR),8
-
-
- ΓòÉΓòÉΓòÉ 13.21.2.5. IEEEFI/IEEEFO - IEEE Floating Point ΓòÉΓòÉΓòÉ
-
- Z╜IEEEFI R ф IEEE Floating In
-
- R is a simple character array, the last axis of which must have a length of 4
- or 8. The last axis thus represents either single- or double-precision IEEE
- floating-point numbers.
-
- Z is an array of numbers equivalent to the floating-point representations in R.
- The rank of Z is one less than the rank of R.
-
- цZ ╜╕ ¤1╟цR
-
- Z╜L IEEEFO R ф IEEE Floating Out
-
- R is a simple numeric array. L is an integer scalar with a value of 4 or 8. A
- value of 4 for L gives single-precision floating point representation, and a
- value of 8 gives double precision. Z is a character array whose last axis has
- length L, and which contains the IEEE single or double-precision floating-point
- representations of the numbers in R. The rank of Z is one greater than the rank
- of R.
-
- цZ ╜╕ (цR),L
-
-
- ΓòÉΓòÉΓòÉ 13.21.2.6. PCFI/PCFO - IBM PC Floating Point ΓòÉΓòÉΓòÉ
-
- Z╜PCFI R ф PC Floating In
-
- R is a simple character array, the last axis of which must have a length of 4
- or 8. The last axis thus represents either single- or double- precision IBM PC
- (reversed) IEEE floating-point numbers.
-
- Z is an array of numbers equivalent to the floating-point representations in R.
- The rank of Z is one less than the rank of R.
-
- цZ ╜╕ ¤1╟цR
-
- Z╜L PCFO R ф PC Floating Out
-
- R is a simple numeric array. L is an integer scalar with a value of 4 or 8. A
- value of 4 for L gives single precision floating point representation, and a
- value of 8 gives double precision. Z is a character array whose last axis has
- length L, and which contains the IBM PC (reversed) IEEE single- or
- double-precision floating-point representations of the numbers in R. The rank
- of Z is one greater than the rank of R.
-
- цZ ╜╕ (цR),L
-
-
- ΓòÉΓòÉΓòÉ 13.21.2.7. PDI/PDO - Packed Decimal ΓòÉΓòÉΓòÉ
-
- Z╜PDI R ф Packed Decimal In
-
- R is a simple character array whose last axis must have a length of between 1
- and 16 inclusive, and which contains valid System/370 packed decimal
- representations of numbers.
-
- Z is an array of integers representing the packed decimal numbers in R. The
- rank of Z is one less than the rank of R.
-
- цZ ╜╕ ¤1╟цR
-
- Note that if the length of the packed decimal number is greater than 9 bytes, a
- loss of precision can result.
-
- Z╜L PDO R ф Packed Decimal Out
-
- R is a simple array of integers. L is an integer scalar not greater than 16. It
- gives the number of bytes in which each integer of R is to be represented. L
- must be large enough to represent the largest magnitude of the integers in R.
-
- Z is a character array whose last axis contains the System/370 packed decimal
- representations of the integers in R. The rank of Z is one greater than the
- rank of R.
-
- цZ ╜╕ (цR),L
-
-
- ΓòÉΓòÉΓòÉ 13.21.3. GPMISC: Miscellaneous Utility Functions ΓòÉΓòÉΓòÉ
-
- o ANNOTATE - Add comments to lines
- o ASSIGN - Specify values for a set of names
- o CASE - Gives case attribute of active workspace
- o CODECOUNT - Count lines in all workspace programs
- o CONCEAL - Make a function nonsuspendable
- o DATETIME - Format date and time
- o EXPAND - Function version of \
- o FNHEADS - List headers for a set of functions
- o FRAME - Put a border around a character matrix
- o HEXDUMP - Produce character+hex display of data
- o LINECOUNT - Count lines in a list of programs
- o LIST - Convert an arbitrary array to a vector
- o MASKCONV - Splits numbers into n-bit fields
- o MESH - Mesh two or more vectors as prescribed by a mask
- o NAMEREFS - Find all names in a defined program
- o NAMES - Find all names in a string
- o NHEAD - Produce character representations of index vectors
- o REPLICATE - Function version of /
- o REVEAL - Make a function suspendable
- o TYPE - Determine if array is alphabetic or numeric
- o UNIQUE - Remove duplicates
-
-
- ΓòÉΓòÉΓòÉ 13.21.3.1. ANNOTATE - Add comments to lines ΓòÉΓòÉΓòÉ
-
- ZΓò£L ANNOTATE R
-
- R is a simple character matrix and L is a numeric scalar. Z is R with rows
- padded or truncated to length L and with comments interactively appended to
- each row.
-
-
- ΓòÉΓòÉΓòÉ 13.21.3.2. ASSIGN - Specify values for a set of names ΓòÉΓòÉΓòÉ
-
- L ASSIGN R
-
- L is a character matrix of names. R is a character matrix of valid APL2
- expressions. Each row of L is evaluated and its value given the name in the
- corresponding row of R.
-
-
- ΓòÉΓòÉΓòÉ 13.21.3.3. CASE - Gives case attribute of active workspace ΓòÉΓòÉΓòÉ
-
- ZΓò£CASE
-
- Z is the case attribute of the active workspace. In APL2/2, Z always has a
- value of 2 to indicate that lowercase characters are used in object names.
-
-
- ΓòÉΓòÉΓòÉ 13.21.3.4. CODECOUNT - Count lines in all workspace programs ΓòÉΓòÉΓòÉ
-
- ZΓò£CODECOUNT
-
- This function counts the function and operator lines in the workspace, and
- returns a 2-element numeric vector. Z[1] is the total number of lines in the
- workspace that contain something other than a comment. Z[2] is the total number
- of lines that consist only of a comment. CODECOUNT does not count its own
- lines. See also LINECOUNT in LINECOUNT - Count lines in a list of programs.
-
-
- ΓòÉΓòÉΓòÉ 13.21.3.5. CONCEAL - Make a function nonsuspendable ΓòÉΓòÉΓòÉ
-
- CONCEAL R
-
- Make the function named by R nonsuspendable.
-
-
- ΓòÉΓòÉΓòÉ 13.21.3.6. DATETIME - Format date and time ΓòÉΓòÉΓòÉ
-
- ZΓò£DATETIME
-
- Z is the date and time in the form of mm/dd/yy hh:mm:ss.
-
- DATETIME
- 06/27/85 10:00:42
-
-
- ΓòÉΓòÉΓòÉ 13.21.3.7. EXPAND - Function version of \ ΓòÉΓòÉΓòÉ
-
- ZΓò£L EXPAND R
-
- R is any array. L is a Boolean vector. Z is L\R. See Miscellaneous Functions
- for a discussion of this function.
-
-
- ΓòÉΓòÉΓòÉ 13.21.3.8. FNHEADS - List headers for a set of functions ΓòÉΓòÉΓòÉ
-
- Z╜FNHEADS R ф FuNction HEADerS
-
- R is a character matrix of function or operator names. Z is a character matrix
- of corresponding function and operator headers, exclusive of explicit local
- variables.
-
-
- ΓòÉΓòÉΓòÉ 13.21.3.9. FRAME - Put a border around a character matrix ΓòÉΓòÉΓòÉ
-
- ZΓò£FRAME R
-
- R is a simple character scalar, vector, or matrix. Z is R bordered by straight
- lines.
-
-
- ΓòÉΓòÉΓòÉ 13.21.3.10. HEXDUMP - Produce character+hex display of data ΓòÉΓòÉΓòÉ
-
- ZΓò£HEXDUMP R
-
- R is a simple character array. Z is a four row matrix with one column for each
- element of ,R. The first row of Z is R; the second is РAF ,R; the third row
- contains the hexadecimal representations of the numbers in the second row; and
- the fourth row contains characters that mark off character positions by fives.
-
-
- ΓòÉΓòÉΓòÉ 13.21.3.11. LINECOUNT - Count lines in a list of programs ΓòÉΓòÉΓòÉ
-
- ZΓò£LINECOUNT R
-
- R is a character scalar, simple vector or matrix, or a vector or vectors.
- LINECOUNT counts the lines of the functions and operators named in R and
- returns a 2-element numeric vector. Z[1] is the number of lines containing
- something other than a comment; Z[2] is the total number of lines that consist
- only of a comment. This function does not count its own lines. See also
- CODECOUNT in CODECOUNT - Count lines in all workspace programs.
-
-
- ΓòÉΓòÉΓòÉ 13.21.3.12. LIST - Convert an arbitrary array to a vector ΓòÉΓòÉΓòÉ
-
- ZΓò£LIST R
-
- This function creates a vector or scalar out of R. R may be any array. If R is
- a simple scalar, then Z is ,R. If R is a simple vector, then Z is ,тR. If R is
- a nested scalar or vector, then Z is R. Otherwise, Z is R enclosed along all
- axes but the first, which forms a nested vector.
-
-
- ΓòÉΓòÉΓòÉ 13.21.3.13. MASKCONV - Splits numbers into n-bit fields ΓòÉΓòÉΓòÉ
-
- Z╜L MASKCONV R ф MASK CONVert
-
- MASKCONV encodes the number (or numbers) R to the base 2*L. It is primarily
- useful in analyzing sections of storage defined by fields of varying lengths
- from one bit to a full word.
-
- 1 2 1 4 24 MASKCONV ¤1+2*32
- 1 3 1 15 16777215
-
-
- ΓòÉΓòÉΓòÉ 13.21.3.14. MESH - Mesh two or more vectors as prescribed by a mask ΓòÉΓòÉΓòÉ
-
- ZΓò£L MESH R
-
- L is a mask and R is a concatenation of the vectors to be meshed. If the mask L
- consists of 0s and 1s, the elements of R are placed, in order of occurrence, in
- the positions of Z corresponding to 0s; after these have been filled, the
- remaining elements are placed in the positions corresponding to 1s. If R is a
- catenation of vectors of lengths equal to the number of 0s and the numbers of
- 1s respectively, the result is to "mesh" them. This can be generalized to any
- number of vectors by providing masks with elements of 0, 1, 2, ...
-
- 00122233333333'
- ΓòƒΓòƒΓòƒΓòƒΓòƒΓòƒΓòƒΓòƒΓòƒΓòƒΓòƒΓòƒΓòƒΓòƒ
- 0 2 2 1 3 3 3 3 3 2 3 0 3 3 MESH 'HE IS WORDSMAN'
- HIS WORDS MEAN
- Γò₧Γò₧Γò₧Γò₧Γò₧Γò₧Γò₧Γò₧Γò₧Γò₧Γò₧Γò₧Γò₧Γò₧
- 02213333323033
-
- In the example above, 0 selects the first two characters ('HE') and puts them
- in the first and twelfth positions of the result; 1 puts a blank in the fourth
- position; 2 puts 'IS ' in positions 2, 3, 10; and 3 puts the remainder.
-
-
- ΓòÉΓòÉΓòÉ 13.21.3.15. NAMEREFS - Find all names in a defined program ΓòÉΓòÉΓòÉ
-
- ZΓò£NAMEREFS R
-
- R is the name of a function or operator. Z is a character matrix containing a
- list of all the names that occur in R.
-
-
- ΓòÉΓòÉΓòÉ 13.21.3.16. NAMES - Find all names in a string ΓòÉΓòÉΓòÉ
-
- ZΓò£NAMES R
-
- R is a character vector. Z is a matrix of all the names in R.
-
-
- ΓòÉΓòÉΓòÉ 13.21.3.17. NHEAD - Produce character representations of index vectors ΓòÉΓòÉΓòÉ
-
- Z╜L NHEAD R ф Numeric HEADers
-
- L and R are integers. Z is a character array giving ьR in column form if L is 0
- and row form if it is not.
-
- 0 NHEAD 5
- 1
- 2
- 3
- 4
- 5
- 1 NHEAD 5
- 12345
- 1 NHEAD 40
- 1111111111222222222233333333334
- 1234567890123456789012345678901234567890
-
-
- ΓòÉΓòÉΓòÉ 13.21.3.18. REPLICATE - Function version of / ΓòÉΓòÉΓòÉ
-
- ZΓò£L REPLICATE R
-
- R is any array. L is a vector of integers. Z is L/R. See Miscellaneous
- Functions for a discussion of this function.
-
-
- ΓòÉΓòÉΓòÉ 13.21.3.19. REVEAL - Make a function suspendable ΓòÉΓòÉΓòÉ
-
- REVEAL R
-
- If possible, make the function named by R suspendable.
-
-
- ΓòÉΓòÉΓòÉ 13.21.3.20. TYPE - Determine if array is alphabetic or numeric ΓòÉΓòÉΓòÉ
-
- ZΓò£TYPE R
-
- Z is a scalar zero if R is numeric, and a scalar blank if it is character. This
- function is compatible with a VS APL library function of the same name. It is
- not meant to be applied to mixed or nested arguments.
-
-
- ΓòÉΓòÉΓòÉ 13.21.3.21. UNIQUE - Remove duplicates ΓòÉΓòÉΓòÉ
-
- ZΓò£UNIQUE R
-
- R is a vector. Z is a vector containing the elements of R with duplicates
- eliminated.
-
- UNIQUE 'THE ANTS WERE HERE'
- THE ANSWR
- UNIQUE 'GUFFAW' 17 (ь4) 'GUFFAW'
- GUFFAW 17 1 2 3 4
-
-
- ΓòÉΓòÉΓòÉ 13.21.4. GPSTRIP: Removing Comments ΓòÉΓòÉΓòÉ
-
- DECOMMENT
-
- This function removes comment lines from all unlocked functions and operators
- in the active workspace. Running decommented functions requires less storage.
- When using this function, you should keep a backup copy of the workspace.
-
- STRIP R
-
- STRIP removes comments from all unlocked functions and operators named in R. R
- is a simple character matrix, a nested vector of names, or a simple string of
- names separated by blanks.
-
- ZΓò£L WORDS R
-
- WORDS is a function to split a character vector into nested pieces, and is
- equivalent to the APL2/370 external function DAN (Delete And Nest). R is a
- character vector. L is a scalar or vector of delimiter characters. Z is a
- character vector, each of whose elements is a vector of the elements of R lying
- between occurrences of the delimiters L in R. Consecutive occurrences of
- delimiters in R are ignored.
-
- See WORDS: Extracting Words from Character Vectors for an example using WORDS.
-
-
- ΓòÉΓòÉΓòÉ 13.21.4.1. WORDS: Extracting Words from Character Vectors ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- ZΓò£'And what exactly ARE the commercial '
- ZΓò£Z,'possibilities of ovine aviation?'
- цZ
- 68
- ZΓò£' ' WORDS Z
- цZ
- 10
- уZ
- And
- what
- exactly
- ARE
- the
- commercial
- possibilities
- of
- ovine
- aviation?
- ц■Z
- 3 4 7 3 3 10 13 2 5 9
-
-
- ΓòÉΓòÉΓòÉ 13.21.5. GPSVP: Controlling Communication through SVP ΓòÉΓòÉΓòÉ
-
- APSERVER R
-
- APSERVER is the general AP server for implementing auxiliary processors using a
- client-server protocol over a single shared variable interface. For more
- information about APSERVER, see Writing Auxiliary Processors Using APSERVER.
-
- ZΓò£L ID R
-
- Convert enclosed character processor IDs to large integers and vice versa.
- Typically used with the SVP profile (apl2svp.prf) in support of cross-system
- SVP shares for cooperative processing.
-
- ZΓò£L SVOFFER R
-
- Offer shared variables, named in right argument, to SVP processors identified
- by numbers in the left argument. Returns the final degree of coupling for each
- shared variable. The function delays up to 15 seconds for shares to be accepted
- by the partner. It sets standard access control to inhibit a double set or use.
-
- R is a character scalar, vector, matrix, or vector of vectors containing the
- name or names of the shared variables to be offered to an auxiliary processor.
- Surrogate names for shared variables can also be used. L is a numeric scalar or
- vector containing the processor ID (the number) of the AP. Z is the degree of
- coupling for the shared variable; a 2 indicates that the corresponding variable
- is fully shared with the AP.
-
- 211 SVOFFER 'S1' 'S2'
- 2 2
-
- ZΓò£L SVOPAIR R
-
- Offer shared variables, named in right argument, to SVP processors identified
- by numbers in the left argument. This function is used for auxiliary processors
- that support a two-variable interface, where the control variable begins with
- "C" or "CTL," and the data variable begins with "D" or "DAT" (that is, AP 124,
- AP 210).
-
- ZΓò£L ΓòóSVO R
-
- РSVO extension to support enclosed character vectors as processor IDs.
- Typically used with the SVP profile (apl2svp.prf) in support of cross-system
- SVP shares for cooperative processing.
-
- ZΓò£L ΓòóSVQ R
-
- РSVQ extension to support enclosed character vectors as processor IDs.
- Typically used with the SVP profile (apl2svp.prf) in support of cross-system
- SVP shares for cooperative processing.
-
-
- ΓòÉΓòÉΓòÉ 13.21.6. GPTEXT: Manipulating Text ΓòÉΓòÉΓòÉ
-
- Note: Many "text" functions also work on other kinds of data.
-
- o DOUBLE - Replace selected characters with pairs
- o FIND - Search for text in all workspace programs
- o GATHER - Collect parsed and delimited fields
- o GVCAT - Catenate rows to arrays of any rank
- o HCAT - Catenate matrixes by columns
- o INBLANKS - Separate characters by blanks
- o LADJ - Left adjust
- o LINEFOLD - Fold and indent line as specified
- o MAT - Make a matrix out of any array
- o MATFOLD - Fold and indent matrix lines as specified
- o NOQUOTES - Remove quoted substrings
- o OBLANKS - Remove outer blanks
- o QREPLACE - Replace ? occurrences by character strings
- o RADJ - Right adjust
- o RCNUM - Produce numerical headings for rows and columns
- o REPLACE - Replace substrings in character strings
- o RTBLANKS - Remove trailing blanks
- o VCAT - Catenate matrixes by rows
- o XBLANKS - Remove all excess blanks
-
-
- ΓòÉΓòÉΓòÉ 13.21.6.1. DOUBLE - Replace selected characters with pairs ΓòÉΓòÉΓòÉ
-
- ZΓò£L DOUBLE R
-
- DOUBLE replaces each occurrence of the scalar L in the vector R by a pair of
- scalars L.
-
- VΓò£'ABC''DEFGH''IJK'
- V
- ABC'DEFGH'IJK'
- '''' DOUBLE V
- ABC''DEFGH''IJK
-
-
- ΓòÉΓòÉΓòÉ 13.21.6.2. FIND - Search for text in all workspace programs ΓòÉΓòÉΓòÉ
-
- [namelist] FIND 'text' ['newtext']
-
- Gives a listing of all functions and operators in the active workspace that
- contain the indicated text.
-
- If 'newtext' is specified, this function replaces 'text' in the objects listed
- in namelist with the new text.
-
-
- ΓòÉΓòÉΓòÉ 13.21.6.3. GATHER - Collect parsed and delimited fields ΓòÉΓòÉΓòÉ
-
- ZΓò£L GATHER R
-
- L is a scalar or one or two element vector, for example '()'. R is any array.
- GATHER searches the rows of R for a sequence "enclosed" within the first and
- second elements of L and ravels them into a vector. If L is a scalar or one
- element vector then it is used as the trailing delimiter also. A blank is
- inserted at each point where the resulting vector crosses a row boundary in R.
-
-
- ΓòÉΓòÉΓòÉ 13.21.6.4. GVCAT - Catenate rows to arrays of any rank ΓòÉΓòÉΓòÉ
-
- Z╜L GVCAT R ф Generalized Vertical CATenation
-
- L and R Z is the result of catenating L to R along the first coordinate of the
- array of higher rank.
-
-
- ΓòÉΓòÉΓòÉ 13.21.6.5. HCAT - Catenate matrixes by columns ΓòÉΓòÉΓòÉ
-
- Z╜L HCAT R ф Horizontal CATenation
-
- HCAT catenates columns: given two matrixes, it places them side-by-side. L and
- R should not be of rank greater than 2. Z is always of rank 2.
-
-
- ΓòÉΓòÉΓòÉ 13.21.6.6. INBLANKS - Separate characters by blanks ΓòÉΓòÉΓòÉ
-
- ZΓò£L INBLANKS R
-
- If characters in L are contained in R, separate them with blanks.
-
-
- ΓòÉΓòÉΓòÉ 13.21.6.7. LADJ - Left adjust ΓòÉΓòÉΓòÉ
-
- Z╜LADJ R ф Left ADJust
-
- R can be any array. Z is that array with nonblank characters shifted to the
- left as far as possible.
-
-
- ΓòÉΓòÉΓòÉ 13.21.6.8. LINEFOLD - Fold and indent line as specified ΓòÉΓòÉΓòÉ
-
- ZΓò£L LINEFOLD R
-
- This function "folds" the line R so that it is no greater than the length
- specified by the first (or only) element in L. If L has a second element, then
- this specifies the number of blanks to be used in offsetting the second and all
- following rows in the output Z. Z is always of rank 2.
-
-
- ΓòÉΓòÉΓòÉ 13.21.6.9. MAT - Make a matrix out of any array ΓòÉΓòÉΓòÉ
-
- Z╜MAT R ф MATrix
-
- Z is an array of rank 2 containing all the elements of R.
-
-
- ΓòÉΓòÉΓòÉ 13.21.6.10. MATFOLD - Fold and indent matrix lines as specified ΓòÉΓòÉΓòÉ
-
- Z╜L MATFOLD R ф MATrix FOLD
-
- L has one or two integer components. R may be any array. Z is a matrix with a
- number of columns equal to the first (or only) component of L. Any lines longer
- than this width are "folded" as in LINEFOLD.
-
-
- ΓòÉΓòÉΓòÉ 13.21.6.11. NOQUOTES - Remove quoted substrings ΓòÉΓòÉΓòÉ
-
- ZΓò£NOQUOTES R
-
- R is a character vector. Z is the same vector with all quoted substrings
- removed.
-
-
- ΓòÉΓòÉΓòÉ 13.21.6.12. OBLANKS - Remove outer blanks ΓòÉΓòÉΓòÉ
-
- Z╜OBLANKS R ф Outer BLANKS
-
- Remove "outer blanks". R is a vector. Z is R with all leading and trailing
- blanks removed.
-
-
- ΓòÉΓòÉΓòÉ 13.21.6.13. QREPLACE - Replace ? occurrences by character strings ΓòÉΓòÉΓòÉ
-
- Z╜L QREPLACE R ф Question mark REPLACEment
-
- R is a vector containing one or more question marks. L is a character vector
- containing one or more subvectors to be substituted for the question marks. The
- first character of L is a delimiter used to identify the substitution vectors.
- This delimiter must also be the last character of L. Z is R with the
- substitutions made.
-
-
- ΓòÉΓòÉΓòÉ 13.21.6.14. RADJ - Right adjust ΓòÉΓòÉΓòÉ
-
- Z╜RADJ R ф Right ADJust
-
- Z is R "right-adjusted", so that the rightmost character of each row is not
- blank unless all the characters of the row are blank. R can be an array; the
- rows are "right-adjusted" individually.
-
-
- ΓòÉΓòÉΓòÉ 13.21.6.15. RCNUM - Produce numerical headings for rows and columns ΓòÉΓòÉΓòÉ
-
- Z╜RCNUM R ф Row and Column NUMbers
-
- R is a matrix. Z is R with column numbers across the top and row numbers along
- the left side.
-
-
- ΓòÉΓòÉΓòÉ 13.21.6.16. REPLACE - Replace substrings in character strings ΓòÉΓòÉΓòÉ
-
- ZΓò£L REPLACE R
-
- R may be any array. Z is R with every occurrence of a "seek" string replaced by
- a "replace" string. L is a two element vector, each of whose elements is a
- scalar or vector. The first element is the "seek" string and the second element
- is the "replace" string.
-
- REPLACEV is a subfunction of REPLACE.
-
- TEXT╜4 4ц'HEREIS SOMETEXT'
- REPLACE/' _' ('HERE' 'THERE') TEXT
- THERE
- IS___
- SOME_
- TEXT_
-
-
- ΓòÉΓòÉΓòÉ 13.21.6.17. RTBLANKS - Remove trailing blanks ΓòÉΓòÉΓòÉ
-
- Z╜RTBLANKS R ф Remove Trailing BLANKS
-
- R is a simple array. Z is R with trailing blanks or trailing blank columns
- removed.
-
-
- ΓòÉΓòÉΓòÉ 13.21.6.18. VCAT - Catenate matrixes by rows ΓòÉΓòÉΓòÉ
-
- Z╜L VCAT R ф Vertical CATenation
-
- L and R are arrays of rank 2 or less. Z is a matrix. Its width is that of the
- wider of L or R. L is at the top of Z and R is at the bottom.
-
-
- ΓòÉΓòÉΓòÉ 13.21.6.19. XBLANKS - Remove all excess blanks ΓòÉΓòÉΓòÉ
-
- Z╜XBLANKS R ф remove eXtra BLANKS
-
- Remove "extra blanks". R must be a vector. Z is R with leading and trailing
- blanks removed and intermediate blank sequences reduced to a single blank.
-
-
- ΓòÉΓòÉΓòÉ 13.21.7. GPTRACE: Setting and Removing Trace and Stop Vectors ΓòÉΓòÉΓòÉ
-
- The functions in this group can be used in debugging your defined APL2
- operations by establishing trace and stop vectors when you're checking the
- operations out, and removing them when you're finished.
-
- STOPALL
-
- STOPALL creates stop vectors for all the lines of all the functions and
- operators in the active workspace.
-
- STOPOFF
-
- This function cancels all the stop vectors in the active workspace.
-
- STOPONE
-
- STOPONE creates stop vectors for the first statements of all the functions and
- operators in the active workspace.
-
- TRACEALL
-
- TRACEALL creates trace vectors for all the statements of all the functions and
- operators in the active workspace.
-
- TRACEBR R ф TRACE BRanch
-
- This function creates a trace vector for every branch statement of the function
- or operator named in R. R is a single name.
-
- TRACELIST R
-
- This function creates trace vectors for all the statements in the functions and
- operators named in R. R is a simple scalar, vector, or matrix, or a vector of
- vectors.
-
- TRACEOFF
-
- This function cancels all the trace vectors in the active workspace.
-
- TRACEONE
-
- TRACEONE creates trace vectors for the first statements of all the functions
- and operators in the active workspace.
-
-
- ΓòÉΓòÉΓòÉ 13.21.8. GPXLATE: Translating from One Character Representation to Another ΓòÉΓòÉΓòÉ
-
- GPXLATE contains three functions and two global variables. The variables are
- used as translate-tables by the functions LCTRANS (which converts from
- uppercase to lowercase), and UCTRANS (which converts from lowercase to
- uppercase).
-
- The third function, TRANSLATE, is a general-purpose translate function that
- requires a translate table as its left argument.
-
- The use of the uppercase and lowercase translate functions is demonstrated in
- Examples of Lowercase and Uppercase Translation. Constructing and Using a
- Translate Table shows how the lowercase translate table was constructed.
-
- Notes for the figure:
-
- (1) Since translation requires selecting values from tables, it is important
- to establish a known index origin. The first action is to set the origin
- to 0, because 0 is more useful then 1 for translating purposes.
-
- (2) The indexes of the lowercase letters in РAV are determined by the use of
- РAF.
-
- (3) Similarly for uppercase.
-
- (4) The lowercase translate table is initialized as РAV.
-
- (5) The lowercase letters replace the uppercase letters in the translate
- table.
-
- (6), (7), and (8) Show how the index sets and the translate table are
- interconnected.
-
- (9) Is a canonical representation of the LCTRANS function, showing how it
- does lowercase translation.
-
-
- ΓòÉΓòÉΓòÉ 13.21.8.1. Examples of Lowercase and Uppercase Translation ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- CVΓò£'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'
- UCTRANS CV
- ABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZ
- LCTRANS CV
- abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz
-
-
- ΓòÉΓòÉΓòÉ 13.21.8.2. Constructing and Using a Translate Table ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Constructing the Lowercase Translate Table
-
- (1) РIO╜0
- (2) LOWERINDICES╜РAF 'abcdefghijklmnopqrstuvwxyz'
- (3) UPPERINDICES╜РAF 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
- (4) LCTt╜РAV
- (5) LCTt[UPPERINDICES]╜РAF LOWERINDICES
- (6) LOWERINDICES
- 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112
- 113 114 115 116 117 118 119 120 121 122
- (7) UPPERINDICES
- 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84
- 85 86 87 88 89 90
- (8) РAF LCTt[UPPERINDICES]
- 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112
- 113 114 115 116 117 118 119 120 121 122
- (9) РCR 'LCTRANS'
-
- AΓò£LCTRANS B
- ф A is B with uppercase letters translated to lowercase
- letters.
- A╜LCTt[РIO+РAF B]
-
-
- ΓòÉΓòÉΓòÉ 14. Supplied Auxiliary Processors ΓòÉΓòÉΓòÉ
-
- The auxiliary processors (APs) supplied with IBM APL2/2 and discussed in this
- chapter are:
-
- o AP 100-OS/2 host command interface
- o AP 101-Alternate input
- o AP 119-Socket interface
- o AP 124-Text display
- o AP 127-SQL interface for DB2
- o AP 145-OS/2 services interface
- o AP 207-Universal graphics
- o AP 210-OS/2 file management
- o AP 211-APL2 object library management
-
- Note: All APL2 invocation parameters and environment variables are also passed
- to any dependent auxiliary processors. Dependent auxiliary processor's are
- auto-started as children of the APL2 interpreter session when the first share
- offer is made to the auxiliary processor. All command line parameters are
- passed unmodified to the auxiliary processor, with the exception of the -id
- parameter, the value of which is adjusted to identify the processor number of
- the auxiliary processor, followed by the processor number of the parent
- interpreter session.
-
- To use an auxiliary processor requires a shared variable, or for some auxiliary
- processors, a pair of shared variables, to pass commands and data between the
- APL2 application and the auxiliary processor. Since auxiliary processors can
- run asynchronously with the APL2 interpreter, applications must follow a proper
- Shared Variable Processor (SVP) protocol when establishing shared variable
- communication with an auxiliary processor, to avoid potential timing problems
- with the two processes running in parallel. For a complete description of the
- SVP system functions, refer to APL2 Programming: Language Reference.
-
- o Using the Share-Offer Utilities
- o AP 100-The OS/2 Host Command Auxiliary Processor
- o AP 101-The Alternate Input (Stack) Auxiliary Processor
- o AP 119-Socket Interface Processor
- o AP 124-The Text Display Auxiliary Processor
- o AP 127-SQL Processor
- o AP 145-The OS/2 Services Interface Auxiliary Processor
- o AP 207-The Universal Graphics Auxiliary Processor
- o AP 210-The File Auxiliary Processor
- o AP 211-The APL2 Object Library Auxiliary Processor
-
-
- ΓòÉΓòÉΓòÉ 14.1. Using the Share-Offer Utilities ΓòÉΓòÉΓòÉ
-
- To simplify the establishment of fully-coupled shares, and to ensure that the
- necessary access control is set for typical communication with an auxiliary
- processor, two functions are distributed in the library 1 UTILITY workspace for
- application developers. The two functions are SVOFFER and SVOPAIR. SVOFFER is
- for use with auxiliary processors employing a single shared variable interface.
- SVOPAIR is used for auxiliary processors such as AP 124 and AP 210 that require
- a control and a data variable for communication.
-
- The SVOFFER function must return a "degree of coupling" of 2 for each variable
- offered, before the shared variable can be used to pass commands and data. This
- indicates that the auxiliary processor has accepted the share offer. An
- indeterminate amount of time is required for the auxiliary processor to accept
- the offer. Typically, an auxiliary processor accepts the shared variable offer
- immediately, but the SVOFFER function queries the degree of coupling for a
- maximum of 15 seconds before exiting with a result of 1 indicating that the
- auxiliary processor has not matched the offer.
-
- The SVOPAIR function is used for auxiliary processors that support a
- two-variable interface, where the control variable name begins with "C" or
- "CTL" and the data variable name begins with "D" or "DAT". SVOPAIR waits up to
- 15 seconds for all control variable offers to be accepted. It returns the final
- degree of coupling for all variables offered. The expected coupling for the
- control variables is 2 (fully coupled), and the data variables can properly
- return either 1 or 2, depending on the auxiliary processor.
-
- Prior to sending commands to an auxiliary processor, shared variable access
- control should be set to ensure that the SVP maintains the necessary sequencing
- of sets and references of the shared variable by both the APL2 application
- program and the auxiliary processor. SVOFFER and SVOPAIR set the necessary
- access controls for typical auxiliary processor communication. SVOFFER sets
- access control on all of the variables offered, and SVOPAIR sets access control
- only on the variables with names starting with the letter "C" (that is, control
- variables only-no access control is applied to data variables). The access
- control applied is 1 0 1 0, which prevents two successive sets of the variable
- by the application without an intervening access by the auxiliary processor,
- and also ensures that the auxiliary processor sets a new value in the variable
- between successive uses by the APL2 application. This is the most common access
- protocol used for shared variable communication with the auxiliary processors.
-
- o Example 1
- o Example 2
-
-
- ΓòÉΓòÉΓòÉ 14.1.1. Example 1 ΓòÉΓòÉΓòÉ
-
- ф Single offer to host auxiliary processor
- 100 SVOFFER 'CMD'
- 2
- ф Offer multiple variables to one AP
- 100 SVOFFER 'V1' 'V2'
- 2 2
- ф Offer multiple variables to multiple APs
- 100 211 SVOFFER 'V100' 'V211'
- 2 2
- ф Check degree of coupling for multiple variables
- SVOFFER 'V100' 'V211'
- 2 2
- ф Invalid shared variable offer
- 211 SVOFFER 'BAD+NAME'
- 0
- ф Offer and trap errors
- РES (2ы.ЇAP SVOFFER VARS)/'Share offer unaccepted by AP',оAP
-
-
- ΓòÉΓòÉΓòÉ 14.1.2. Example 2 ΓòÉΓòÉΓòÉ
-
- ф Offer a set of variables to the fullscreen processor
- 124 SVOPAIR 'CTL124' 'DAT124'
- 2 2
- ф Offer using surrogates
- 124 SVOPAIR 'Control C' 'Data D'
- 2 2
- ф Note: Access control set for control, not data
- РSVC■ 'Control' 'Data'
- 1 0 1 1 0 0 0 0
- ф Check degree of coupling
- SVOPAIR 'Control' 'Data'
- 2 2
- ф Offer improper control variable
- 210 SVOPAIR 'A1' 'D1'
- 1 1
-
-
- ΓòÉΓòÉΓòÉ 14.2. AP 100-The OS/2 Host Command Auxiliary Processor ΓòÉΓòÉΓòÉ
-
- AP 100 is an auxiliary processor that allows OS/2 commands or programs to be
- executed. AP 100 itself imposes no specific limit on the number of concurrent
- shared variables that you can use. It accepts a shared variable of any name.
- For example:
-
- 100 SVOFFER 'SHR100'
- 2
-
- offers variable SHR100 to AP 100 and sets access control. See Using the
- Share-Offer Utilities for a description of the SVOFFER function (from the 1
- UTILITY workspace).
-
- After sharing is established, a valid OS/2 command or program can be executed
- by assigning the command to the shared variable. For example, to list the files
- in the current directory:
-
- SHR100Γò£'DIR'
-
- Notes:
-
- 1. If AP 100 is started automatically by the interpreter (the default), then
- any output generated by the execution of the command appears in the window
- associated with the interpreter. This window is often minimized, because it
- is not normally used for APL2 session input and output.
-
- 2. If an empty vector ('' or ь0) is given as the command, the shared variable
- returns with the characters 'OS/2'.
-
- 3. Commands issued through AP 100 do not affect the interpreter environment.
- For example, issuing a change directory command through either AP 100, or
- through )HOST, does not change the directory that your current APL2 session
- is using.
-
- o AP 100 Return Codes
-
-
- ΓòÉΓòÉΓòÉ 14.2.1. AP 100 Return Codes ΓòÉΓòÉΓòÉ
-
- Code Meaning
- 0 - Success
- 1 - Invalid OS/2 command
- 444 - Invalid shared variable value
-
- Other error codes are those returned as the exit status of the called routine.
-
-
- ΓòÉΓòÉΓòÉ 14.3. AP 101-The Alternate Input (Stack) Auxiliary Processor ΓòÉΓòÉΓòÉ
-
- The alternate input (stack) processor (AP 101) can be used to create a stack of
- programmable input to APL2.
-
- Conceptually, the alternate-input stack is a vector of character vectors. Each
- item is one stacked input line of variable length.
-
- Although any one instance of APL2/2 can maintain only one stack, several shared
- variables can be used to add entries to the stack. Entries are stacked in
- first-in, first-out (FIFO) order (the default) or last-in, first-out (LIFO)
- order.
-
- An input stack is normally created within a defined function. The top entry
- (the first item) in the stack is used when the APL2 interpreter requests input.
- This occurs when:
-
- o An APL2 statement prompts for user input (Р or С)
- o The APL2 Editor 1 (selected by )EDITOR 1) prompts for input
- o APL2 opens the keyboard for immediate execution
- o APL2 execution is suspended as a result of an error or stop control (SΓòó)
-
- Share a variable with AP 101. For example:
-
- 101 SVOFFER 'SHR101'
- 2
-
- offers variable SHR101 to AP 101 and sets access control. See Using the
- Share-Offer Utilities for a description of the SVOFFER function.
-
- After sharing is established, entries can be added to the stack by assigning
- the text to the shared variable (SHR101 in this example):
-
- SHR101Γò£'any character string'
-
- The string can contain new-line characters (РTC[РIO+1]), which causes each
- portion of the string delimited by a new-line to be treated as a separate entry
- on the stack.
-
- o AP 101 Commands
- o AP 101 Return Codes
-
-
- ΓòÉΓòÉΓòÉ 14.3.1. AP 101 Commands ΓòÉΓòÉΓòÉ
-
- The stack can be purged of all or some entries, and the order (LIFO/FIFO) in
- which the entries are used can be selected with the following commands:
-
- o SHR101Γò£0 - Purges the entire stack.
-
- o SHR101Γò£0,n - Purges n entries from the stack. If n>0 these are dropped from
- the LIFO end, and if n<0 these are dropped from the FIFO end.
-
- o SHR101Γò£10 - Queries the state of the stack (LIFO/FIFO)
-
- o SHR101Γò£10 1 - Sets the stack to LIFO
-
- o SHR101╜10 ¤1 - Sets the stack to FIFO (the default)
-
- The maximum size of the stack is 1000 entries.
-
-
- ΓòÉΓòÉΓòÉ 14.3.2. AP 101 Return Codes ΓòÉΓòÉΓòÉ
-
- Code Meaning
- 0 - Success
- 12 - Stack overflow
- 444 - Invalid object
-
-
- ΓòÉΓòÉΓòÉ 14.4. AP 119-Socket Interface Processor ΓòÉΓòÉΓòÉ
-
- The socket interface processor is used to pass requests to the Transmission
- Control Protocol/Internet Protocol (TCP/IP) product. TCP/IP provides
- communication facilities across networks. See TCP/IP for OS/2 Programmer's
- Reference for more information about TCP/IP.
-
- Notes:
-
- 1. Commands are passed as nested vectors. The first element of the value
- assigned to the variable determines the type of commands being issued. For
- the workstation, the command is 'TCPIP' for commands to TCP/IP.
-
- 2. The general form of the result is a three-element vector:
-
- o An AP 119 return code
- o A TCP/IP return code
- o Data returned by the command
-
- 3. No AP invocation options are required or defined.
-
- o Blocking
- o Using AP 119-The TCPIP commands
- o Sample AP 119 Session Using the APL2 Socket API
- o AP 119 Return Codes
-
-
- ΓòÉΓòÉΓòÉ 14.4.1. Blocking ΓòÉΓòÉΓòÉ
-
- Some socket calls may not return control until a condition is satisfied. For
- example, the READ and RECV calls may not return control until data is available
- to receive. The default state of a socket is blocking mode, which means that
- these calls do not return control immediately.
-
- Using the APL2 socket interface with sockets in the default mode, AP 119 does
- not receive control back from TCP/IP until blocking calls complete. Since AP
- 119 does not have control, it is not able to set the shared variable until the
- blocking condition is satisfied. A reference of the variable causes a shared
- variable interlock until the blocking call completes.
-
- A socket can be set to nonblocking mode with the FCNTL socket call. If this is
- done, AP 119 receives control on subsequent calls and returns the EWOULDBLOCK
- return code.
-
-
- ΓòÉΓòÉΓòÉ 14.4.2. Using AP 119-The TCPIP commands ΓòÉΓòÉΓòÉ
-
- The TCPIP commands provide a means to make calls to TCP/IP. The AP 119 TCP/IP
- interface closely matches the TCP/IP C socket interface. The following sections
- describe the APL2 syntax used for making TCP/IP calls through AP 119.
-
- o ACCEPT
- o BIND
- o CLOSE
- o CONNECT
- o FCNTL
- o GETHOSTID
- o GETHOSTNAME
- o GETPEERNAME
- o GETSOCKNAME
- o GETSOCKOPT
- o LISTEN
- o READ
- o RECV
- o RECVFROM
- o SELECT
- o SEND
- o SENDTO
- o SETSOCKOPT
- o SHUTDOWN
- o SOCKET
- o WRITE
-
-
- ΓòÉΓòÉΓòÉ 14.4.2.1. ACCEPT ΓòÉΓòÉΓòÉ
-
- Accepts a connection request. This call accepts the first connection on its
- queue of pending connections. A new socket number is returned for the
- connection and the original socket remains available to accept more connection
- requests. This call blocks if there are no pending connections, and the socket
- is in blocking mode.
-
- SV119Γò£'TCPIP' 'ACCEPT' sn
- (APRC TCPIPRC CMDRC)Γò£SV119
- (ns rp ra)Γò£CMDRC
-
- Where:
-
- sn Is the socket number.
- ns Is the new socket number assigned by TCP/IP.
- rp Is the port number of the remote process that connected with you.
- ra Is the IP address of the remote process that connected with you.
-
- Example:
-
- SV119Γò£'TCPIP' 'ACCEPT' 3
- (APRC TCPIPRC CMDRC)Γò£SV119
- CMDRC
- 4 1023 9.113.12.92
-
-
- ΓòÉΓòÉΓòÉ 14.4.2.2. BIND ΓòÉΓòÉΓòÉ
-
- Associates a local IP address and port with a socket number.
-
- SV119Γò£'TCPIP' 'BIND' sn lp la
- (APRC TCPIPRC CMDRC)Γò£SV119
-
- Where:
-
- sn Is the socket number.
-
- lp Is the local port number. If this number is 0, TCP/IP assigns an
- unused port number.
-
- la Is the local IP address. If this address is '0.0.0.0', the socket can
- be used with any local network.
-
- CMDRC Is 0
-
- Example:
-
- SV119Γò£'TCPIP' 'BIND' 3 1023 '9.112.12.92'
- SV119
- 0 0 0
-
-
- ΓòÉΓòÉΓòÉ 14.4.2.3. CLOSE ΓòÉΓòÉΓòÉ
-
- Shuts down a socket. If the socket is associated with an open TCP connection,
- the connection is closed.
-
- SV119Γò£'TCPIP' 'CLOSE' sn
- (APRC TCPIPRC CMDRC)Γò£SV119
-
- Where:
-
- sn Is the socket number.
-
- CMDRC Is 0.
-
- Example:
-
- SV119Γò£'TCPIP' 'CLOSE' 4
- SV119
- 0 0 0
-
-
- ΓòÉΓòÉΓòÉ 14.4.2.4. CONNECT ΓòÉΓòÉΓòÉ
-
- Completes the binding necessary for a socket if BIND has not been issued and
- establishes a connection to a socket in listening mode. If the socket is in
- blocking mode, this call blocks until the connection is complete or an error is
- returned.
-
- SV119Γò£'TCPIP' 'CONNECT' sn rp ra
- (APRC TCPIPRC CMDRC)Γò£SV119
-
- Where:
-
- sn Is the socket number.
-
- rp Is the remote port number
-
- ra Is the remote IP address
-
- CMDRC Is 0.
-
- Example:
-
- SV119Γò£'TCPIP' 'CONNECT' 3 1002 '9.113.14.90'
- SV119
- 0 0 0
-
-
- ΓòÉΓòÉΓòÉ 14.4.2.5. FCNTL ΓòÉΓòÉΓòÉ
-
- Allows an application to change the operating characteristics of a socket.
-
- SV119Γò£'TCPIP' 'FCNTL' sn cmd cdata
- (APRC TCPIPRC CMDRC)Γò£SV119
-
- Where:
-
- sn Is the socket number.
- cmd Is the command (see below).
- cdata Is the data associated with the command (see below).
- CMDRC Is 0 (if setting the status) or the status flags (if getting the
- status).
-
- Note: If the cmd is 'F_GETFL', the, cdata parameter is ignored.
-
- The possible values for cmd are 'F_GETFL' and 'F_SETFL'.
-
- The possible values for cdata are 0 and 'FNDELAY'.
-
- Example:
-
- SV119Γò£'TCPIP' 'FCNTL' 3 'F_SETFL' 'FNDELAY'
- SV119
- 0 0 0
-
-
- ΓòÉΓòÉΓòÉ 14.4.2.6. GETHOSTID ΓòÉΓòÉΓòÉ
-
- Returns the IP address for the host. If the host has more than one IP address,
- the primary one is returned.
-
- SV119Γò£'TCPIP' 'GETHOSTID'
- (APRC TCPIPRC ia)Γò£SV119
-
- Where:
-
- ia Is the primary host IP address.
-
- Example:
-
- SV119Γò£'TCPIP' 'GETHOSTID'
- (APRC TCPIPRC CMDRC)Γò£SV119
- CMDRC
- 9.113.12.92
-
-
- ΓòÉΓòÉΓòÉ 14.4.2.7. GETHOSTNAME ΓòÉΓòÉΓòÉ
-
- Returns the name of the host processor on which the user is running.
-
- SV119Γò£'TCPIP' 'GETHOSTNAME'
- (APRC TCPIPRC hn)Γò£SV119
-
- Where:
-
- hn Is the name of the host.
-
- Example:
-
- SV119Γò£'TCPIP' 'GETHOSTNAME'
- (APRC TCPIPRC CMDRC)Γò£SV119
- CMDRC
- STLVM20
-
-
- ΓòÉΓòÉΓòÉ 14.4.2.8. GETPEERNAME ΓòÉΓòÉΓòÉ
-
- Returns the family, port and IP address of a peer connected to a given socket.
-
- SV119Γò£'TCPIP' 'GETPEERNAME' sn
- (APRC TCPIPRC CMDRC)Γò£SV119
- (fm rp ra)Γò£CMDRC
-
- Where:
-
- sn Is the socket number.
- fm Is the family.
- rp Is the remote port.
- ra Is the remote IP address
-
- Example:
-
- SV119Γò£'TCPIP' 'GETPEERNAME' 3
- (APRC TCPIPRC CMDRC)Γò£SV119
- CMDRC
- 2 1002 9.113.14.90
-
-
- ΓòÉΓòÉΓòÉ 14.4.2.9. GETSOCKNAME ΓòÉΓòÉΓòÉ
-
- Returns the family, port and IP address of a given socket.
-
- SV119Γò£'TCPIP' 'GETSOCKNAME' sn
- (APRC TCPIPRC CMDRC)Γò£SV119
- (fm lp la)Γò£CMDRC
-
- Where:
-
- sn Is the socket number.
- fm Is the family.
- lp Is the local port.
- la Is the local IP address.
-
- Example:
-
-
-
-
- 2 1023 9.113.12.92
-
-
- ΓòÉΓòÉΓòÉ 14.4.2.10. GETSOCKOPT ΓòÉΓòÉΓòÉ
-
- Gets options associated with a socket.
-
- SV119Γò£'TCPIP' 'GETSOCKOPT' sn lv op
- (APRC TCPIPRC ov)Γò£SV119
-
- Where:
-
- sn Is the socket number.
- lv Is the communication level.
- op Is the option name
- ov Is the option value.
-
- TCP/IP Socket Options provides some of the values and levels that are defined
- for the GETSOCKOPT and SETSOCKOPT calls. The subset listed includes those
- values that are compatible with AP 119 on the APL2/370 platform. OS/2 TCP/IP
- supports additional options that can be used by applications when
- cross-platform portability is not a stringent requirement.
-
- Example:
-
- LEVΓò£'SOL_SOCKET'
- OPTΓò£'SO_BROADCAST'
- SV119Γò£'TCPIP' 'GETSOCKOPT' 4 LEV OPT
- SV119
- 0 0 1
-
- Note: If the option specified is SO_LINGER, the third item is a vector of 2
- integers, representing the timeout value in seconds and micro-seconds,
- respectively. For all other options, the third item is a single integer.
-
-
- ΓòÉΓòÉΓòÉ 14.4.2.10.1. TCP/IP Socket Options ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Option
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Level
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- SO_BROADCAST
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- SOL_SOCKET
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- SO_DONTROUTE
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- SOL_SOCKET
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- SO_ERROR
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- SOL_SOCKET
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- SO_LINGER
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- SOL_SOCKET
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- SO_OOBINLINE
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- SOL_SOCKET
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- SO_REUSEADDR
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- SOL_SOCKET
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- SO_TYPE
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- SOL_SOCKET
-
-
- ΓòÉΓòÉΓòÉ 14.4.2.11. LISTEN ΓòÉΓòÉΓòÉ
-
- Waits for a connection to a given socket if BIND has not been issued, and
- creates a connection request queue.
-
- SV119Γò£'TCPIP' 'LISTEN' sn bl
- (APRC TCPIPRC CMDRC)Γò£SV119
-
- Where:
-
- sn Is the socket number.
-
- bl Is the length of the request queue.
-
- Example:
-
- SV119Γò£'TCPIP' 'LISTEN' 3 5
- SV119
- 0 0 0
-
-
- ΓòÉΓòÉΓòÉ 14.4.2.12. READ ΓòÉΓòÉΓòÉ
-
- Reads data from a given socket. If the socket is in blocking mode and no data
- is available to read, this call blocks.
-
- SV119Γò£'TCPIP' 'READ' sn type
- (APRC TCPIPRC CMDRC)Γò£SV119
-
- Where:
-
- sn Is the socket number.
-
- type Is one of:
-
- 'B' No conversion of data
- 'E' Translate character data from EBCDIC to native format
- 'A' Translate character data from ASCII to native format
-
- Note: Because OS/2's native format is ASCII, no translation is
- done for option 'A'.
-
- CMDRC Is the data read from the socket.
-
- Example:
-
- SV119Γò£'TCPIP' 'READ' 4 'B'
- (APRC TCPIPRC CMDRC)Γò£SV119
- CMDRC
- (data sent by partner)
-
-
- ΓòÉΓòÉΓòÉ 14.4.2.13. RECV ΓòÉΓòÉΓòÉ
-
- Receives data from a given socket. If the socket is in blocking mode and no
- data is available to receive, this call blocks.
-
- SV119Γò£'TCPIP' 'RECV' sn flg tp
- (APRC TCPIPRC CMDRC)Γò£SV119
-
- Where:
-
- sn Is the socket number.
-
- flg is receive option parameters (see below).
-
- tp Is the type and is one of:
-
- 'B' No conversion of data
- 'E' Translate character data from EBCDIC to native format
- 'A' Translate character data from ASCII to native format
-
- Note: Because OS/2's native format is ASCII, no translation is
- done for option 'A'.
-
- Possible flag values are 0, 1 (MSG_OOB) or 2 (MSG_PEEK)
-
- Example:
-
- SV119Γò£'TCPIP' 'RECV' 4 0 'B'
- (APRC TCPIPRC CMDRC)Γò£SV119
- CMDRC
- (data sent by partner)
-
-
- ΓòÉΓòÉΓòÉ 14.4.2.14. RECVFROM ΓòÉΓòÉΓòÉ
-
- Receives data from a socket and identifies the source of the data.
-
- SV119Γò£'TCPIP' 'RECVFROM' sn flg tp
- (APRC TCPIPRC CMDRC)Γò£SV119
- (dat add)Γò£CMDRC
- (fam rp ra)Γò£add
-
- Where:
-
- sn Is the socket number.
-
- flg Is the recvfrom option parameters (see RECV above).
-
- tp Is the type and is one of:
-
- 'B' No conversion of data
- 'E' Translate character data from EBCDIC to native format
- 'A' Translate character data from ASCII to native format
-
- Note: Because OS/2's native format is ASCII, no translation is
- done for option 'A'.
-
- dat Is the data received from the socket.
-
- fam Is the family (always 2 - AF_INET).
-
- rp Is the remote port.
-
- ra Is the remote IP address.
-
- Example:
-
- SV119Γò£'TCPIP' 'RECVFROM' 4 0 'B'
- (APRC TCPIPRC CMDRC)Γò£SV119
- CMDRC
- (data sent by partner) 2 1003 9.113.14.90
-
-
- ΓòÉΓòÉΓòÉ 14.4.2.15. SELECT ΓòÉΓòÉΓòÉ
-
- Monitors activity on a set of sockets as specified by three masks. The first
- argument indicates how many sockets to check. This would normally be 1 plus the
- largest socket number allocated. The masks must be at least as long as this
- value. A one in the mask specifies a corresponding socket to check. Three masks
- are returned as soon as something happens on a selected socket. For example,
- the read mask has a one if the corresponding socket has data ready to read. If
- the connection to a listening socket is completed, the read mask is set to
- indicate that a connection has been made to the socket and an ACCEPT call can
- be made. A socket is normally always ready to write. The except mask is set if
- out of band data is received. The timeout value specifies the number of seconds
- to wait for the call to complete. A value of zero means to wait indefinitely.
-
- SV119Γò£'TCPIP' 'SELECT' ns rm wm xm to
- (APRC TCPIPRC CMDRC)Γò£SV119
- (rm wm xm)Γò£CMDRC
-
- Where:
-
- ns Is the number of sockets to check.
-
- rm Is a read mask
-
- wm Is a write mask
-
- xm Is an exception mask
-
- to Is the timeout value
-
- Example:
-
- R_MASKΓò£0 0 0 1 1
- W_MASKΓò£0 0 0 0 0
- X_MASKΓò£0 0 0 0 0
- SV119Γò£'TCPIP' 'SELECT' 5 R_MASK W_MASK X_MASK 0
- (APRC TCPIPRC CMDRC)Γò£SV119
- DATA
- 0 0 0 1 0 0 0 0 0 0 0 0 0 0 0
-
-
- ΓòÉΓòÉΓòÉ 14.4.2.16. SEND ΓòÉΓòÉΓòÉ
-
- Transmits data to a remote user whose remote address and port have been bound
- to the socket. If the socket is in blocking mode, this call blocks until TCP/IP
- can send the data.
-
- SV119Γò£'TCPIP' 'SEND' sn flg tp dat
- (APRC TCPIPRC CMDRC)Γò£SV119
-
- Where:
-
- sn Is the socket number.
-
- flg Is the send option parameters (0 or 1 - MSG_OOB).
-
- tp Is the type and is one of:
-
- 'B' No conversion of data
- 'E' Translate character data from native format to EBCDIC
- 'A' Translate character data from native format to ASCII
-
- Note: Because OS/2's native format is ASCII, no translation is
- done for option 'A'.
-
- dat the data to be sent.
-
- CMDRC Is the number of characters sent
-
- Example:
-
- SV119Γò£'TCPIP' 'SEND' 3 0 'B' 'CHARACTERS'
- (APRC TCPIPRC CMDRC)Γò£SV119
- 0 0 10
-
-
- ΓòÉΓòÉΓòÉ 14.4.2.17. SENDTO ΓòÉΓòÉΓòÉ
-
- Transmits data to a remote user whose remote address and port are specified in
- the command. For APL2, the family is normally 2.
-
- SV119Γò£'TCPIP' 'SENDTO' sn fl tp dat fm rp ra
- (APRC TCPIPRC CMDRC)Γò£SV119
-
- Where:
-
- sn Is the socket number.
-
- fl Is the sendto option parameters (0 or 1 - MSG_OOB).
-
- tp Is one of:
-
- 'B' No conversion of data
- 'E' Translate character data from native format to EBCDIC
- 'A' Translate character data from native format to ASCII
-
- Note: Because OS/2's native format is ASCII, no translation is
- done for option 'A'.
-
- dat the data to be sent.
-
- fm Is the family (always 2 - AF_INET)
- rp Is the remote port number
- ra Is the remote IP address
-
- CMDRC Is the number of characters sent
-
- Example:
-
- (FAM R_PORT R_ADDR)Γò£2 '9.113.12.92' 1002
- DATAΓò£'These are characters.'
- SV119Γò£'TCPIP' 'SENDTO' 3 0 'B' DATA FAM R_PORT R_ADDR
- SV119
- 0 0 23
-
-
- ΓòÉΓòÉΓòÉ 14.4.2.18. SETSOCKOPT ΓòÉΓòÉΓòÉ
-
- Sets options associated with a socket.
-
- SV119Γò£'TCPIP' 'SETSOCKOPT' sn lv op o1 [o2]
- (APRC TCPIPRC CMDRC)Γò£SV119
-
- Where:
-
- sn Is the socket number.
- lv Is the level of communication.
- op Is the option name.
- o1 Is the option value.
- o2 Is the optional second option value. This is used only if op is
- SO_LINGER.
-
- TCP/IP Socket Options provides the values and levels that are defined for the
- GETSOCKOPT and SETSOCKOPT calls.
-
- Example:
-
- LEVΓò£'SOL_SOCKET'
- OPTΓò£'SO_BROADCAST'
- SV119Γò£'TCPIP' 'SETSOCKOPT' 4 LEV OPT 1
- SV119
- 0 0 0
-
-
- ΓòÉΓòÉΓòÉ 14.4.2.19. SHUTDOWN ΓòÉΓòÉΓòÉ
-
- Shuts down all or part of a duplex connection.
-
- SV119Γò£'TCPIP' 'SHUTDOWN' sn how
- (APRC TCPIPRC CMDRC)Γò£SV119
-
- Where:
-
- sn Is the socket number.
-
- how Is type of shutdown (0, 1 or 2)
-
- Example:
-
- SV119Γò£'TCPIP' 'SHUTDOWN' 4 1
- SV119
- 0 0 0
-
-
- ΓòÉΓòÉΓòÉ 14.4.2.20. SOCKET ΓòÉΓòÉΓòÉ
-
- Creates an endpoint for communication. A socket number is allocated for use in
- other socket calls.
-
- SV119Γò£'TCPIP' 'SOCKET'
- (APRC TCPIPRC CMDRC)Γò£SV119
-
- Where:
-
- CMDRC Is the socket number allocated.
-
- Example:
-
- SV119Γò£'TCPIP' 'SOCKET'
- SV119
- 0 0 3
-
-
- ΓòÉΓòÉΓòÉ 14.4.2.21. WRITE ΓòÉΓòÉΓòÉ
-
- Writes data to a given socket.
-
- SV119Γò£'TCPIP' 'WRITE' sn tp dat
- (APRC TCPIPRC CMDRC)Γò£SV119
-
- Where:
-
- sn Is the socket number.
-
- tp Is one of:
-
- 'B' No conversion of data
- 'E' Translate character data from native format to EBCDIC
- 'A' Translate character data from native format to ASCII
-
- Note: Because OS/2's native format is ASCII, no translation is
- done for option 'A'.
-
- dat Is the data to be sent
-
- CMDRC Is the number of characters written.
-
- Example:
-
- SV119Γò£'TCPIP' 'WRITE' 3 'B' 'Many characters'
- SV119
- 0 0 15
-
-
- ΓòÉΓòÉΓòÉ 14.4.3. Sample AP 119 Session Using the APL2 Socket API ΓòÉΓòÉΓòÉ
-
- In this example, one user shares the variable A and the other user shares
- variable B.
-
- ф User 1 shares a variable with AP 119
- 119 РSVO'A'
- 1
- 0 0 1 1 РSVC 'A'
- 0 0 1 1
- ф User 1 allocates a socket
- AΓò£'TCPIP' 'SOCKET'
- A
- 0 0 3
-
- The return code shows that socket number 3 has been allocated. This is a stream
- socket that is allocated to the user but not bound to a particular port or
- address and is not connected.
-
- ф User 1 binds socket to a port
- AΓò£'TCPIP' 'BIND' 3 1023 '0.0.0.0'
- A
- 0 0 0
-
- Notice that a zero IP address was specified. If a machine is connected to more
- than one network (and therefore has more than one IP address), you can bind to
- a particular network, or specify '0.0.0.0' as the address meaning that you
- accept a connection to any network. Using '0.0.0.0' as the IP address helps
- maintain the portability of your application.
-
- Port number 1023 is an arbitrary number agreed upon by both users. If the port
- number is being used by anyone else on the local system, an EADDRINUSE error is
- returned and the BIND is not successful.
-
- ф User 1 listens for a connection
- AΓò£'TCPIP' 'LISTEN' 3 5
- A
- 0 0 0
-
- ? User 2 shares a variable with AP 119
- 119 РSVO 'B'
- 1
- 0 0 1 1 РSVC 'B'
- 0 0 1 1
- ф Allocates a socket
- BΓò£'TCPIP' 'SOCKET'
- B
- 0 0 3
- ф Binds it to user 1's port and address
- BΓò£'TCPIP' 'BIND' 3 1055 '0.0.0.0'
- B
- 0 0 0
-
- Although user 2 also gets socket number 3, this has no relationship with the
- socket allocated to user 1.
-
- ф User 2 connects to user 1
- BΓò£'TCPIP' 'CONNECT' 3 1023 '9.113.14.90'
- B
- 0 0 0
-
- ф User 1 accepts the connection
- AΓò£'TCPIP' 'ACCEPT' 3
- A
- 0 0 4 1055 9.113.14.90
-
- When user 1 does an ACCEPT, a new socket is allocated (4 in this case) and the
- connection is completed using the new socket. The original socket (3 in this
- case) remains listening for new connections.
-
- There is now an established connection between the two users The result from
- the ACCEPT call has as it's third item the new socket number allocated and user
- 2's port number and IP address.
-
- ф User 1 sends data to user 2
- AΓò£'TCPIP' 'SEND' 4 0 'A' 'SOME DATA'
- A
- 0 0 0
-
- The A means that ASCII characters are being sent. In this case, specifying type
- A is the same as type B since both sides are already using ASCII. If the
- receiving side was EBCDIC-based then type E on the SEND would cause translation
- to EBCDIC before the data is sent.
-
- Note that you can send noncharacter data so long as you and your partner agree
- on formats. In this case, you should always use the B type option. When the
- data is received by the partner, it is received as characters and the external
- function RTA can be used to restore the data to the expected format.
-
- ф User 2 receives the data
- BΓò£'TCPIP' 'RECV' 3 0 'A'
- B
- 0 0 SOME DATA
-
- In this case, all the data was received at once but this may not always be the
- case. Stream socket protocol does not guarantee that data that was sent is
- received in one RECV call. It is up to the users to agree on a convention for
- saying how much data is sent so that the partner can tell when all data has
- been received.
-
- ф Since a user cannot predict when data
- ф arrives, it is not known when a
- ф receive should be done. User 1 issues
- ф a SELECT that requests that he be
- ф informed when data arrives.
- R_MASKΓò£0 0 0 0 1
- W_MASKΓò£0 0 0 0 0
- X_MASKΓò£0 0 0 0 0
- AΓò£'TCPIP' 'SELECT' 5 R_MASK W_MASK X_MASK
-
- Because the largest socket is 4, you must specify 5 as the number of of sockets
- and provide three length 5 masks. The one in the first mask says that user 1
- wants to be informed when socket 4 is ready to read. You can specify more than
- one socket by specifying more than one 1.
-
- Since RECV is a blocking call, if user 1 now references A, execution stops
- until data arrives. Alternately user 1 can do other computing. The user can use
- РSVS 'A' and check for 0 1 0 1 to see if AP 119 has assigned data to the
- variable. The user can use РSVE to wait for an event on any of his shared
- variables or until a specified amount of time has passed whichever comes first.
-
- ф User 2 sends some data
- BΓò£'TCPIP' 'SEND' 3 0 'A' 'DATA BACK TO YOU'
- B
- 0 0 0
-
- ф User 1 notices that data is available
- РSVS 'A'
- 0 1 0 1
- A
- 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0 0 0
-
- The 1 in the read mask means that socket 4 is ready to read. The masks returned
- from the SELECT may have zero or more 1 bits on but never more than originally
- specified in the SELECT call.
-
- ф User 1 reads the data
- AΓò£'TCPIP' 'RECV' 4 0 'A'
- A
- 0 0 DATA BACK TO YOU
- ф User 1 closes all his connections
- AΓò£'TCPIP' 'CLOSE' 4
- A
- 0 0 0
- AΓò£'TCPIP' 'CLOSE' 3
- A
- 0 0 0
-
- ф User 2 closes his connection
- BΓò£'TCPIP' 'CLOSE' 3
- B
- 0 0 0
-
-
- ΓòÉΓòÉΓòÉ 14.4.4. AP 119 Return Codes ΓòÉΓòÉΓòÉ
-
- Code Meaning
- 0 - Success
- 1 - Incorrect command
- 2 - Wrong type
- 3 - Wrong rank
- 4 - Wrong shape
- 5 - Item is wrong type
- 6 - Item is wrong rank
- 7 - Item is wrong shape
- 8 - Item data is wrong
- 11 - TCP/IP error occurred. Second element of result is TCP/IP return
- code.
-
-
- ΓòÉΓòÉΓòÉ 14.5. AP 124-The Text Display Auxiliary Processor ΓòÉΓòÉΓòÉ
-
- AP 124 enables you to control a window from within an APL2 defined function. It
- enables your application to:
-
- o Write to the formatted screen
- o Read from the formatted screen
- o Produce colors, highlighting, reverse video, and so on
- o Control the keyboard translation
- o Enter "Inkey" mode to monitor all keyboard activity
- o Define up to 255 fields
-
- o AP 124 Operation
- o Understanding Screen Management
- o AP 124 Commands
- o AP 124 Return Codes
-
-
- ΓòÉΓòÉΓòÉ 14.5.1. AP 124 Operation ΓòÉΓòÉΓòÉ
-
- AP 124 requires two shared variables: a data variable and a control variable.
- They can be offered in any order. The name of the data variable must always
- begin with the letter "D" or the letters "DAT", and the control variable must
- begin with the letter "C" or the letters "CTL". The remaining characters in
- both names (possibly none) must be the same, because the coupling of both
- variables is recognized by their name. Examples of valid pairs are: C and D,
- C1 and D1, and CXjj and DXjj. Also accepted as valid pairs (for compatibility
- with APL2/370) are names such as CTL and DAT or CTL1 and DAT1. The control
- variable is used to select the operation to perform and to control each
- input/output operation. For example:
-
- 124 SVOPAIR 'C124' 'D124'
- 2 2
-
- offers variables C124 and D124 to the auxiliary processor. See Using the
- Share-Offer Utilities for a description of the SVOPAIR function (from the 1
- UTILITY workspace).
-
-
- ΓòÉΓòÉΓòÉ 14.5.2. Understanding Screen Management ΓòÉΓòÉΓòÉ
-
- To use the Text Display auxiliary processor, you should understand the screen
- and its attributes. This section gives an overview of how the auxiliary
- processor logically views the screen.
-
- o AP 124 Usage
- o Screen Size
- o Screen Fields
- o Field Types and Attributes
-
-
- ΓòÉΓòÉΓòÉ 14.5.2.1. AP 124 Usage ΓòÉΓòÉΓòÉ
-
- In the following, the "physical screen" refers to what is actually displayed in
- an OS/2 window. The "logical screen" is a buffered image of that window stored
- in memory. Operations are normally performed on the logical screen. The
- information stored in the logical screen is transferred to the physical screen
- (the physical screen is refreshed) by certain calls ("Read and Wait" and
- "Immediate Write").
-
-
- ΓòÉΓòÉΓòÉ 14.5.2.2. Screen Size ΓòÉΓòÉΓòÉ
-
- The physical screen (window) size can be controlled by the application program,
- by use of an AP 124 command code, and by the application user through standard
- interactive window resizing techniques supported by the system window manager.
- The default size of the window at the time of the initial open is 25 by 80. The
- size of the active window can be queried or set at any time by the application
- program, by use of command code 14 (see Set Window Attributes).
-
-
- ΓòÉΓòÉΓòÉ 14.5.2.3. Screen Fields ΓòÉΓòÉΓòÉ
-
- The text display auxiliary processor views the screen in terms of rectangular
- areas called screen fields. You can enter or display data only in these areas.
- Each screen field has a starting location, a width, and a height that you
- define when you format the screen. The starting position of each field is the
- row and column address of the upper left-hand character in the field. (The
- upper left-hand position of the screen is row 1 column 1.)
-
-
- ΓòÉΓòÉΓòÉ 14.5.2.4. Field Types and Attributes ΓòÉΓòÉΓòÉ
-
- Each screen field has associated with it, a field type and a field attribute
- that qualify its content. For instance, a field type may indicate that a field
- is to contain alphabetic or numeric data or that user input to the field is to
- be allowed, and the field attribute may specify that the field is to be
- displayed as red characters on a white background.
-
-
- ΓòÉΓòÉΓòÉ 14.5.3. AP 124 Commands ΓòÉΓòÉΓòÉ
-
- The following section describes each AP 124 command in detail. The commands are
- summarized in Summary of AP 124 Commands.
-
- Each time the command-control variable ("C124" in the following examples) is
- set, AP 124 attempts to perform the requested operation and resets the
- command-control variable to indicate the degree of success or failure. A value
- of 0 indicates that the operation was successful; anything else indicates that
- a problem has been encountered-these values are listed in AP 124 Return Codes.
-
- o Clear Screen
- o Format the Screen into Fields
- o Reformat the Screen
- o Push Format Array
- o Pop Format Array
- o Immediate Write of Data to Screen
- o Read and Wait or Read and Test
- o Delayed Write of Data to Screen
- o Get Data from the Logical Screen (as a Matrix)
- o Update Field Types
- o Update Field Attributes
- o Control and Information Request
- o Get Format Table
- o Get the Current Logical Screen
- o Sound a Beep to Alert User
- o Set the Cursor
- o Set Window Attributes
- o Query Window Attributes
- o Get Data from the Logical Screen (as a Vector)
- o Get Field Attributes
- o Clear Screen (VS APL Compatible)
- o Set Title Bar Text
-
-
- ΓòÉΓòÉΓòÉ 14.5.3.1. Clear Screen ΓòÉΓòÉΓòÉ
-
- Syntax:
-
- C124Γò£0
-
- This request clears both the physical screen and the logical field contents on
- the next operation requiring a screen update.
-
-
- ΓòÉΓòÉΓòÉ 14.5.3.2. Format the Screen into Fields ΓòÉΓòÉΓòÉ
-
- Syntax:
-
- D124Γò£numeric_format_array
- C124Γò£1
-
- This call permits you to divide your logical screen into rectangular "fields".
- Each field is defined in terms of its offset from the top left-hand corner of
- the screen, its depth, and its width. You can also indicate whether the field
- is output only or input/output; and its display "attribute".
-
- numeric_format_array is a four-, five-, or six-column numeric matrix with one
- row for each field to be formatted. If only one field is to be formatted, a
- numeric vector can be passed, and is treated as a one row matrix. The first or
- only row of the matrix defines the first field, the second row defines the
- second field, and so on.
-
- The first four elements of each row of the matrix (assigned to D124) are
- defined as:
-
- 1. Start row of the field
-
- 2. Start column of the field
-
- 3. Field height
-
- 4. Field width
-
- The fifth and sixth elements of each row of the matrix are optional and are
- defined as:
-
- 5. Field type:
-
- 0 - Input/output/selectable
- 1 - Numeric input only/any output/selectable
- 2 - Output only (the default)
- 3 - Output only/selectable
-
- See the description of the call to Set the Cursor for the meaning of the
- "selectable" attribute.
-
- 6. Field attribute: An integer between 0 and 255. The default field attribute
- is 1, which normally gives blue characters on a black background. The
- following diagram shows the meanings of the bits of the display attribute
- byte on color display adapters:
-
- 7 6 5 4 3 2 1 0
- ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
- Γöé Γöé
- Γöé ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ Foreground color (4 bits)
- Γöé
- ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ Background color (4 bits)
-
- See AP 124 colors for the combinations of colors available.
-
- The format request clears any previously defined fields and establishes a new
- screen definition with one field for each row of the format array given in
- D124. These fields are given field numbers, starting from one, corresponding to
- the row number of the field in the format array. These field numbers are used
- to identify each individual field in subsequent calls to AP 124.
-
- Example:
-
- D124╜1 6ц10 5 1 6 0 7
- C124Γò£1
-
- defines a field in the tenth row, fifth column, one high, six wide. The field
- has a type of input/output/selectable (0) and the attribute (7) specifies gray
- characters on a black background.
-
- Notes:
-
- 1. A row in the format array can be all zeros. This can be used as a place
- holder, and the corresponding field can be defined later with a reformat
- screen request (C124Γò£1,Field_number(s)) as described below.
-
- 2. Initially, the display screen contains only one field that covers the
- entire screen area.
-
-
- ΓòÉΓòÉΓòÉ 14.5.3.2.1. AP 124 colors ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Code
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Bits
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Color
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Code
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Bits
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Color
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 0
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 0 0 0 0
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Black
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 8
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 1 0 0 0
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Light Gray
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 1
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 0 0 0 1
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Blue
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 9
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 1 0 0 1
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Light Blue
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 2
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 0 0 1 0
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Green
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 10
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 1 0 1 0
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Light Green
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 3
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 0 0 1 1
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Cyan
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 11
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 1 0 1 1
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Light Cyan
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 4
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 0 1 0 0
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Red
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 12
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 1 1 0 0
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Light Red
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 5
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 0 1 0 1
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Magenta
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 13
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 1 1 0 1
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Light Magenta
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 6
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 0 1 1 0
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Yellow
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 14
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 1 1 1 0
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Brown
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 7
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 0 1 1 1
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Gray
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 15
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 1 1 1 1
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- White
-
-
- ΓòÉΓòÉΓòÉ 14.5.3.3. Reformat the Screen ΓòÉΓòÉΓòÉ
-
- Syntax:
-
- D124Γò£numeric_format_array
- C124Γò£1,Field_number(s)
-
- The reformat screen request modifies one or more existing field definitions.
- The number of rows given in the format array (D124) must be the same as the
- number of Field_number(s) given in the control variable (C124).
-
- numeric_format_array is a four-, five-, or six-column numeric matrix with one
- row for each field to be formatted.
-
-
- ΓòÉΓòÉΓòÉ 14.5.3.4. Push Format Array ΓòÉΓòÉΓòÉ
-
- Syntax:
-
- D124Γò£numeric_format_array
- C124╜1 ¤1
-
- The push current format array request saves the current screen format and data
- on a last-in first-out (LIFO) stack. Any areas of the screen not defined in the
- new format array retain their previous contents.
-
- numeric_format_array is a four-, five-, or six-column numeric matrix with one
- row for each field to be formatted.
-
-
- ΓòÉΓòÉΓòÉ 14.5.3.5. Pop Format Array ΓòÉΓòÉΓòÉ
-
- Syntax:
-
- C124╜1 ¤2 -Pop last pushed format array
- C124╜1 ¤2,n -Pop last n format arrays
-
- The pop format array request restores the last saved format and screen data
- from the stack. If n is specified, this process is repeated n times. If the
- stack is empty, the current format and data are retained and no error is given.
-
-
- ΓòÉΓòÉΓòÉ 14.5.3.6. Immediate Write of Data to Screen ΓòÉΓòÉΓòÉ
-
- Syntax:
-
- D124Γò£array_of_character_data
- C124Γò£2,Field_number(s)
-
- This call permits you to write data to the logical screen, which is then
- immediately transferred to the physical screen.
-
- The array can be either a matrix with one row for each field listed, or a
- vector of character vectors with one vector for each field listed. If a field
- has a height of more than 1, the data to be written to the field must be
- ravelled to form the corresponding row or vector of D124. If however, a single
- field is being updated, the data can be passed either as a character matrix or
- ravelled to form a character vector.
-
-
- ΓòÉΓòÉΓòÉ 14.5.3.7. Read and Wait or Read and Test ΓòÉΓòÉΓòÉ
-
- In normal operation, the physical screen is refreshed. Then, either the
- auxiliary processor waits for a certain key to be pressed, or it returns to
- APL2 with information on whether a key was pressed.
-
- Syntax Description
- C124Γò£3
- C124Γò£3 0 Allow interactive input and return to APL2 when a special key is
- pressed. (See table below for D124 key codes.) Assigning the control
- variable a scalar value of 3, or the two element vector 3 0, are
- completely equivalent.
- C124Γò£3 1 Return to APL2 when any key is pressed.
- C124Γò£3 2 Test for a key pressed, and return immediately.
- C124Γò£3 3 Return to APL2 when any key except a cursor movement key is pressed.
- ("Semi-inkey" mode.)
- C124Γò£3 4 Test for a key pressed, and return immediately. If a normal
- (non-special) key has been pressed, it will be echoed to the display,
- and the field containing it will be marked as having been updated.
-
- If any of the above calls has three elements, this instructs the auxiliary
- processor not to refresh the physical screen. (The value of the third element
- is ignored.)
-
- After the return code is checked in C124, the D124 variable contains a vector
- of five or more elements. They are:
-
- D124[1 2] For calls 3, (3 0), and (3 4), a code indicating the special
- key pressed to return to APL. For calls (3 1), (3 2), and (3
- 3), the character code and extended function code returned by
- the APL2/2 keyboard routine. For call (3 2), if no key has been
- pressed, return is (¤1 ¤1). Similarly, for call (3 4), if no
- special key has been pressed, return is (¤1 ¤1).
-
- D124[3] Field number where the cursor was located at return to APL2, or
- 0 if the cursor was not in a defined field.
-
- D124[4 5] Cursor position (row,column) within that defined field. If
- field number is 0, these elements give the offset from top-left
- of the logical screen. Positions are given in origin one, for
- example, 1 1 specifies the top-left corner of the field.
-
- D124[6...] List of fields updated during this call.
-
- AP124 Special Keys and Key Return Codes lists codes returned for the 3, (3 0),
- and (3 4) cases:
-
- While AP 124 is in the (3 0) "Read and Wait" state, you can type on the screen.
- The cursor movement keys can be used in the normal way. Three other keys have
- special functions:
-
- Ctrl-Backspace Toggles the keyboard between APL2 and national modes.
-
- Ctrl-End Clears to the end of the field. However, if the field has less
- than 80 columns, only the current line is cleared to its end.
-
- Ctrl-Home Clears from the cursor to the start of the field. However, if
- the field has less than 80 columns, only the current line is
- cleared to its beginning.
-
- AP 124 Extended Function Codes shows the extended function codes returned in
- D124[2] for commands: (3 1), (3 2), and (3 3). D124[1] is set to 0 when these
- extended function codes are returned. If D124[2] is 0, then D124[1] is the
- 0-origin РAV index of the character corresponding to the key pressed.
-
-
- ΓòÉΓòÉΓòÉ 14.5.3.7.1. AP124 Special Keys and Key Return Codes ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Code
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Description
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 0 0
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Enter (New-line key)
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 1,N
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- F-key (Where "N" (1єNє48) is the number of the key that was depressed. 1-12:
- normal F-keys; 13-24: F-keys in shift mode; 25-36: F-keys in Ctrl mode; 37-48
- F-keys in Alt mode)
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 4 1
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Esc
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 6 1
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Home
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 6 2
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- End
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 6 3
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- PageUp
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 6 4
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- PageDown
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 6 5
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Ctrl-PageUp
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 6 6
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Ctrl-PageDown
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 6 7
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Ctrl-Left
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 6 8
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Ctrl-Right
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 6 9
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Ctrl-Up
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 6 10
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Ctrl-Down
-
-
- ΓòÉΓòÉΓòÉ 14.5.3.7.2. AP 124 Extended Function Codes - Part 1 ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Code
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Description
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 0
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Ctrl-Break or Ctrl-Backspace
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 3
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Null character
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 15
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Shift-Tab
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 16-25
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Alt-q, w, e, r, t, y, u, i, o, p (national keyboard only)
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 30-38
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Alt-a, s, d, f, g, h, j, k, l (national keyboard only)
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 44-50
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Alt-z, x, c, v, b, n, m (national keyboard only)
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 59-68
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Function keys 1-10
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 71
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Home
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 72,73
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Cursor Up, PageUp
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 75,77
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Cursor Left, Right
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 79
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- End
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 80,81
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Cursor Down, PageDown
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 82,83
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Insert, Delete
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 84-93
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Shift-Function keys 1-10
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 94-103
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Ctrl-Function keys 1-10
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- MORE...
-
-
- ΓòÉΓòÉΓòÉ 14.5.3.7.3. AP 124 Extended Function Codes - Part 2 ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Code
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Description
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 104-113
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Alt-Function keys 1-10
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 114
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Ctrl-PrintScreen
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 115,116
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Ctrl-Cursor Left, Right
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 117,118
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Ctrl-End, Ctrl-PageDown
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 119
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Ctrl-Home
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 120-131
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Alt-1, 2, 3, 4, 5, 6, 7, 8, 9, 0, -, = (national keyboard only)
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 132
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Ctrl-PageUp
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 133,134
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Function keys 11, 12
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 135,136
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Shift-Function keys 11, 12
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 137,138
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Ctrl-Function keys 11, 12
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 139,140
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Alt-Function keys 11, 12
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 141,142
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Ctrl-Cursor Up, Ctrl-Keypad -
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 143,144
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Ctrl-Enter, Ctrl-Keypad +
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 145,146
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Ctrl-Cursor Down, Ctrl-Insert
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 147,148
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Ctrl-Delete, Ctrl-Tab
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- MORE...
-
-
- ΓòÉΓòÉΓòÉ 14.5.3.7.4. AP 124 Extended Function Codes - Part 3 ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Code
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Description
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 149,150
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Ctrl-Keypad /, Ctrl-Keypad *
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 151,152
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Alt-Home, Alt-Cursor Up
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 153
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Alt-PageUp
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 155,157
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Alt-Cursor Left, Right
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 159,160
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Alt-End, Alt-Cursor Down
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 161
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Alt-PageDown
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 162,163
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Alt-Insert, Alt-Delete
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 164,165
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Alt-Keypad /, Alt-Tab
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 166
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Alt-Enter
-
-
- ΓòÉΓòÉΓòÉ 14.5.3.8. Delayed Write of Data to Screen ΓòÉΓòÉΓòÉ
-
- Syntax:
-
- D124Γò£array_of_character_data
- C124Γò£4,Field_number(s)
-
- This call permits you to write data to the logical screen, which is displayed
- at the next refresh of the physical screen.
-
- In all other respects, this service is identical to the immediate write service
- (see Immediate Write of Data to Screen).
-
-
- ΓòÉΓòÉΓòÉ 14.5.3.9. Get Data from the Logical Screen (as a Matrix) ΓòÉΓòÉΓòÉ
-
- Syntax:
-
- C124Γò£5,Field_number(s)
-
- Returns a matrix with one row for each data field requested. If a field
- contains more than one row, its data is raveled into a single row of the
- matrix. If multiple fields are requested, the data from each is padded to the
- length of the longest.
-
- Return: D124 is a character array with as many rows as the number of fields
- requested, and as many columns as the maximum field length (field length is the
- total number of characters in a field).
-
- This call enables you to read data from the logical screen.
-
-
- ΓòÉΓòÉΓòÉ 14.5.3.10. Update Field Types ΓòÉΓòÉΓòÉ
-
- Syntax:
-
- D124Γò£New_field_type(s)
- C124Γò£6,Field_number(s)
-
- where each item of New_field_type is a number:
-
- 0 - Field is input/output (selectable)
- 1 - Field is numeric input only/any output (selectable)
- 2 - Field is output only (nonselectable)
- 3 - Field is output only (selectable)
- See the description of the call to Set the Cursor for the meaning of the
- "selectable" attribute.
-
- This call updates column five of the format array previously specified for the
- indicated fields.
-
-
- ΓòÉΓòÉΓòÉ 14.5.3.11. Update Field Attributes ΓòÉΓòÉΓòÉ
-
- Syntax:
-
- D124Γò£Attribute(s)
- C124Γò£7,Field_number(s)
-
- Each item of Attribute is an integer from 0 to 255 as defined in Format the
- Screen into Fields.
-
- It is also possible to define the attributes for each character position of a
- field. To do this, the D124 variable is set to a vector of attributes, and only
- a single Field_number is specified. A value of ¤1 in the vector of attributes
- specifies that this character position is to use the currently-defined field
- attribute.
-
-
- ΓòÉΓòÉΓòÉ 14.5.3.12. Control and Information Request ΓòÉΓòÉΓòÉ
-
- Syntax:
-
- C124Γò£8 - Set to APL2 keyboard
- C124Γò£8 0 - Set to APL2 keyboard (same as C124Γò£8)
- C124Γò£8 1 - Set to national keyboard
- C124Γò£8 2 - Return status
-
- Returns in D124:
-
- D124[1] - Keyboard in APL2 mode
- D124[2] - Reserved (always 0)
- D124[3] - Reserved (always 1)
- D124[4] - Beep request pending
- D124[5] - Reserved (always 0)
- D124[6] - Cursor mode (0 = normal, 1 = field)
-
-
- ΓòÉΓòÉΓòÉ 14.5.3.13. Get Format Table ΓòÉΓòÉΓòÉ
-
- Syntax:
-
- C124Γò£9
-
- Return: D124 is a n by 6 numeric matrix, where n is the current number of
- fields defined.
-
- This call returns the current format array stored by AP 124.
-
- If no format array currently exists then D124 is set to:
-
- 1 1, No_of_rows, No_of_columns, 2 1
-
- This feature can be used to determine the number of rows and columns that the
- window is capable of displaying. Note, however, that this is a dummy field that
- may not be used and a new format array must be defined before any input or
- output can be performed. (This is incompatible with the host VS APL version of
- AP 124 that allowed the initial default field to be used for output.)
-
-
- ΓòÉΓòÉΓòÉ 14.5.3.14. Get the Current Logical Screen ΓòÉΓòÉΓòÉ
-
- Syntax:
-
- C124Γò£10 1 - Return logical screen as a character matrix in the D124 variable
-
-
- ΓòÉΓòÉΓòÉ 14.5.3.15. Sound a Beep to Alert User ΓòÉΓòÉΓòÉ
-
- Syntax:
-
- C124Γò£11 - Delayed Beep
-
- C124Γò£11 0 - Delayed Beep (Same as C124Γò£11)
-
- C124Γò£11 1 - Immediate Beep
-
- C124Γò£11 2 - Cancel previous delayed Beep
-
- If the beep is delayed, it occurs at the next "Read and Wait" or "Read and
- Test" operation. To find out whether a beep is pending, specify call 8 2 and
- examine the fourth element.
-
-
- ΓòÉΓòÉΓòÉ 14.5.3.16. Set the Cursor ΓòÉΓòÉΓòÉ
-
- Syntax:
-
- D124Γò£Field_no, Row_offset, Column_offset
- C124Γò£12
-
- Sets the cursor to a specific screen location. Field_no is the number of a
- defined field. If it is zero, then row and column are considered as coordinates
- from the top left corner of the screen. D124 must be a three element numeric
- vector. Positions are given in origin one, for example, 1 1 specifies the
- top-left corner of the field.
-
- C124Γò£12 0
-
- Sets cursor type to normal (the default).
-
- C124Γò£12 1
-
- Sets cursor type to field. Any fields with a field type that is "selectable"
- (field types 0, 1 or 3) are displayed in reverse video whenever the cursor is
- situated within the field.
-
-
- ΓòÉΓòÉΓòÉ 14.5.3.17. Set Window Attributes ΓòÉΓòÉΓòÉ
-
- The following section describes the syntax for setting window attributes.
-
- o Set Background Color
- o Set Window Size and Placement
-
-
- ΓòÉΓòÉΓòÉ 14.5.3.17.1. Set Background Color ΓòÉΓòÉΓòÉ
-
-
- Syntax:
-
- C124Γò£14,color
-
- Sets the screen background (all areas of the window not currently defined by
- any field in the format array during the previous "reformat screen" operation)
- to the color specified. For example:
-
- C124Γò£14 16
-
- Sets the background to blue.
-
-
- ΓòÉΓòÉΓòÉ 14.5.3.17.2. Set Window Size and Placement ΓòÉΓòÉΓòÉ
-
-
- Syntax:
-
- C124Γò£14,row,column,height,width
-
- Requests the window size and placement, through standard negotiation with the
- window manager. Logical fields defined totally outside the window are not
- displayed, and fields that exceed the window boundaries are clipped. Any
- parameter can be specified with a value of ¤1 to request default handling. The
- row and column positions are 0-origin offsets from the top left corner of the
- Desktop window.
-
-
- ΓòÉΓòÉΓòÉ 14.5.3.18. Query Window Attributes ΓòÉΓòÉΓòÉ
-
- Syntax:
-
- C124Γò£14
-
- Returns a 5-element integer vector in D124:
-
- background_color, row, column, height, width
-
-
- ΓòÉΓòÉΓòÉ 14.5.3.19. Get Data from the Logical Screen (as a Vector) ΓòÉΓòÉΓòÉ
-
- Syntax:
-
- C124Γò£15,Field_number(s)
-
- Returns a matrix with one row for each data field requested. If a field
- contains more than one row, its data is raveled into a single row of the
- matrix. If multiple fields are requested, the data from each is padded to the
- length of the longest.
-
- Return: D124 is a character array with as many rows as the number of fields
- requested, and as many columns as the maximum field length (field length is the
- total number of characters in a field).
-
- This call enables you to read data from the logical screen.
-
-
- ΓòÉΓòÉΓòÉ 14.5.3.20. Get Field Attributes ΓòÉΓòÉΓòÉ
-
- Syntax:
-
- C124Γò£17,Field_number(s)
-
- Returns in D124, a character matrix (one row for each Field_number specified)
- containing the attribute character for each character position of the field.
- The РAV system variable can be used to convert these attribute characters to
- the equivalent attribute integers.
-
-
- ΓòÉΓòÉΓòÉ 14.5.3.21. Clear Screen (VS APL Compatible) ΓòÉΓòÉΓòÉ
-
- Syntax:
-
- C124Γò£20
-
- This is the same as call 0, and is provided purely for compatibility with the
- VS APL AP 124.
-
-
- ΓòÉΓòÉΓòÉ 14.5.3.22. Set Title Bar Text ΓòÉΓòÉΓòÉ
-
- Syntax:
-
- D124Γò£'text'
- C124Γò£21 1
-
- Sets the title bar of the AP 124 window to the specified text.
-
-
- ΓòÉΓòÉΓòÉ 14.5.3.22.1. Summary of AP 124 Commands - Part 1 ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Operation
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Control Variable
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Data Variable
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Response in Data Variable
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Clear screen
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 0
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Reformat screen
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 1
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- format
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Push format array
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 1 ¤1
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- format
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Pop format array
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 1 ¤2 [,n]
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- format
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Reformat fields
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 1,field_nos
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- format
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Immediate write to screen
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 2,field_nos
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- data
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Read and wait
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 3
- 3 0
- 3 1
- 3 3
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- key, cursor, field_no
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- MORE...
-
-
- ΓòÉΓòÉΓòÉ 14.5.3.22.2. Summary of AP 124 Commands - Part 2 ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Operation
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Control Variable
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Data Variable
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Response in Data Variable
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Read and test
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 3 2
- 3 4
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- key, cursor, field_no
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Delayed write to screen
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 4,field_nos
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- data
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Get data
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 5,field_nos
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- data
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Update field type
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 6,field_nos
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- type
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Update field attribute
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 7,field_nos
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- attribute
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Set to APL2 keyboard
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 8
- 8 0
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Set to national keyboard
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 8 1
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Return status
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 8 2
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- keyboard, beep, cursor
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Get format table
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 9
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- format
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Get the current logical screen
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 10 1
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- data
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- MORE...
-
-
- ΓòÉΓòÉΓòÉ 14.5.3.22.3. Summary of AP 124 Commands - Part 3 ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Operation
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Control Variable
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Data Variable
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Response in Data Variable
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Sound a delayed beep
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 11
- 11 0
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Sound an immediate beep
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 11 1
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Cancel a delayed beep
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 11 2
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Set the cursor
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 12
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- position
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Set cursor type to normal
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 12 0
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Set cursor type to field
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 12 1
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Query window attributes
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 14
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- attributes
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Set window background color
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 14,color
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Set window placement and size
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 14,row,column,
- height,width
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Data as a vector of arrays
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 15,field_nos
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- MORE...
-
-
- ΓòÉΓòÉΓòÉ 14.5.3.22.4. Summary of AP 124 Commands - Part 4 ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Operation
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Control Variable
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Data Variable
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Response in Data Variable
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Get field attributes
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 17,field_nos
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- attributes
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Clear screen
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 20
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Set title bar text
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 21 1
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- data
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ 14.5.4. AP 124 Return Codes ΓòÉΓòÉΓòÉ
-
- Code Meaning
- 0 - Success
- 11 - Control variable rank error
- 12 - Control variable length error
- 13 - Control variable domain error
- 14 - Invalid call
- 15 - Request to position cursor in an undefined field
- 21 - Data variable rank error
- 22 - Data variable length error
- 23 - Data variable domain error
- 24 - Data variable not shared
- 25 - Data variable value error
- 26 - Data variable too large
- 30 - Invalid field number
- 32 - Defined field extends beyond the window
- 33 - Reference outside field definition
- 37 - Invalid field type
- 38 - Invalid attribute
- 41 - Data variable has not been specified in the correct sequence
- 42 - Data variable has not been referenced in the correct sequence
- 53 - Required storage not available
- 89 - Data variable interlocked
-
-
- ΓòÉΓòÉΓòÉ 14.6. AP 127-SQL Processor ΓòÉΓòÉΓòÉ
-
- AP 127 allows you to use the Structured Query Language (SQL) to access IBM
- DATABASE 2* (DB2).
-
- Supplied workspace SQL simplifies the use of AP 127. See The SQL Workspace for
- more information about SQL.
-
- See APL2 Programming: Using Structured Query Language for more information
- about AP 127. Where APL2 Programming: Using Structured Query Language indicates
- syntax that differs between operating systems, the syntax for DB2 (TSO) should
- be used.
-
- o AP 127 Commands
- o AP 127 Return Codes
-
-
- ΓòÉΓòÉΓòÉ 14.6.1. AP 127 Commands ΓòÉΓòÉΓòÉ
-
- This subsection shows the syntax of the AP 127 commands. In this subsection,
- DAT represents a variable that is shared with AP 127.
-
- DAT Γò£ 'CALL' name [values]
-
- Executes defined SQL statement name which was previously processed by a PREP
- operation. AP 127 substitutes each item of values for the column index in name.
-
- DAT Γò£ 'CLOSE' name
-
- Closes cursor (SELECT) statement name.
-
- DAT Γò£ 'COMMIT' ['RELEASE']
-
- Makes permanent all the changes you made to the data base since you shared the
- variable or since the most recent COMMIT or ROLLBACK operation.
-
- DAT Γò£ 'CONNECT' ['RESET'Γöédatabase['SHARE'Γöé'EXCLUSIVE']]
-
- Specifies database name.
-
- DAT Γò£ 'DECLARE' name ['HOLD'Γöé'NOHOLD']
-
- Declares a cursor name with hold attribute.
-
- DAT Γò£ 'DESCRIBE' ['NAMES'Γöé'LABELS'Γöé'ANY'Γöé'BOTH']
-
- Returns information about an open statement.
-
- DAT Γò£ 'EXEC' statement
-
- Immediately executes statement.
-
- DAT Γò£ 'FETCH' name [options]
-
- Returns new result table data as the second item of the shared variable result.
-
- DAT Γò£ 'GETOPT'
-
- Returns the values of the AP 127 options.
-
- DAT Γò£ 'ISOL' [level]
-
- Sets or returns isolation level. If level is 'RR', 'CS', or 'UR', sets
- isolation level to indicate setting. If level is omitted, returns current
- isolation level.
-
- DAT Γò£ 'MSG' rcode
-
- Returns the error message text associated with return code rcode.
-
- DAT Γò£ 'NAMES'
-
- Returns the names of all statements known to AP 127.
-
- DAT Γò£ 'OPEN' name [values]
-
- Opens previously prepared statement name.
-
- DAT Γò£ 'PREP' name statement
-
- Prepares SQL statement name for later execution by a CALL or OPEN operation.
-
- DAT Γò£ 'PURGE' name
-
- Removes statement name from the list of active names in AP 127; if name is
- empty, all statements are removed from the list.
-
- DAT Γò£ 'ROLLBACK' ['RELEASE']
-
- Undoes all the changes you made to the database since you shared the variable
- with AP 127 or since the most recent COMMIT or ROLLBACK operation.
-
- DAT Γò£ 'SETOPT' options
-
- Sets the values of the AP 127 options.
-
- DAT Γò£ 'SQLCA'
-
- Returns the contents of the SQLCA control block.
-
- DAT Γò£ 'SQLSTATE'
-
- Returns the current value of SQLSTATE.
-
- DAT Γò£ 'STATE' name
-
- Yields the current state of SQL statement name.
-
- DAT Γò£ 'STMT' name
-
- Yields SQL statement name.
-
- DAT Γò£ 'TRACE' (n1 n2)
-
- Yields an event trace of functions within AP 127; n1 specifies the AP 127
- module number and n2 specifies the trace level.
-
-
- ΓòÉΓòÉΓòÉ 14.6.2. AP 127 Return Codes ΓòÉΓòÉΓòÉ
-
- Code Meaning
- 0 0 0 0 0 Normal return.
- 0 1 0 n m Normal return, but a warning message has been issued.
- 0 0 1 0 0 Normal return, but a result table might not have been completely
- retrieved.
- 1 1 0 n m Transaction backout; all changes made to tables since the last
- COMMIT or ROLLBACK operation are discarded.
- 1 0 0 1 m Error in AP 127; m is the number of the AP 127 error message.
- 1 0 0 2 m Error in DB2; m is the message number.
- 1 0 0 3 m Error in an SQL workspace function; m is the message number.
-
-
- ΓòÉΓòÉΓòÉ 14.7. AP 145-The OS/2 Services Interface Auxiliary Processor ΓòÉΓòÉΓòÉ
-
- Auxiliary processor 145 provides access to OS/2 services, including many
- Presentation Manager and Control Program services. APL services are also
- provided for accessing memory outside the workspace and managing Presentation
- Manager messages.
-
- The supplied workspace PMTOOLS includes utilities for performing common tasks
- in Presentation Manager. The supplied workspace PMWIN includes variables
- corresponding to the constants defined in the C language pmwin.h header files.
- The supplied workspace DEMO145 demonstrates using AP 145.
-
- For more information about the supplied workspaces, see Supplied Workspaces.
-
- o AP 145 Service Requests
- o AP 145 Return Codes
- o AP 145 Online Help
-
-
- ΓòÉΓòÉΓòÉ 14.7.1. AP 145 Service Requests ΓòÉΓòÉΓòÉ
-
- Services are requested by assigning a nested array to the shared variable. The
- first element of the array is the service name. Subsequent elements are the
- service's parameters. Each parameter must be either a scalar or vector.
-
- The general form of the result is a three-element vector. The first element is
- the AP 145 return code. The second element is the service result. The third
- element is the service request with any updates applied by the service to the
- parameters. For example:
-
- AΓò£'WinAlarm' HWND_DESKTOP WA_ERROR
- (APRC OSRC CMD)Γò£A
- APRC
- 0
- OSRC
- 1
- CMD
- 'WinAlarm' 2
-
-
- ΓòÉΓòÉΓòÉ 14.7.2. AP 145 Return Codes ΓòÉΓòÉΓòÉ
-
- The following return codes are used by AP 145.
-
- Code Meaning
- 0 Success
- 1 Invalid array
- 2 Unsupported service name
- 3 Incorrect number of parameters
- 4 Invalid parameter
-
-
- ΓòÉΓòÉΓòÉ 14.7.3. AP 145 Online Help ΓòÉΓòÉΓòÉ
-
- AP 145 provides online help. The online help is accessed using the AplHelp
- service.
-
- To display the general help for AP 145, enter the following command:
-
- AΓò£'AplHelp' 'General'
-
-
- ΓòÉΓòÉΓòÉ 14.8. AP 207-The Universal Graphics Auxiliary Processor ΓòÉΓòÉΓòÉ
-
- AP 207 enables you to generate fast, high-quality graphics and text, easily and
- quickly. It accepts an easy-to-learn command syntax that has been designed for
- both simplicity of use and high performance. It has built-in support for the
- OS/2 services, giving high-quality graphics combined with the flexibility of a
- powerful window management facility. It works with a single shared variable to
- control each graphics window. There are no special name restrictions for the
- shared variables. The following basic functions are supported:
-
- o Representation of graphic information either as line segments or as
- higher-level structures, such as arcs or sectors of a circle
-
- o Generation of text characters in various sizes and orientations, using
- external image, vector, or PostScript fonts
-
- o Definition of a world coordinate system
-
- o Definition of clipping and scissoring rectangles
-
- o AP 207 Interface
- o AP 207 Commands
- o Multiple-Call Sequences
- o Defining World Coordinates with Correct Aspect Ratio
- o Image and Vector Font Support
- o AP 207 Return Codes
-
-
- ΓòÉΓòÉΓòÉ 14.8.1. AP 207 Interface ΓòÉΓòÉΓòÉ
-
- AP 207 requires a single variable to be shared for each new window. A variable
- is shared with AP 207. For example:
-
- 207 SVOFFER 'SHR207'
- 2
-
- offers variable SHR207 to AP 207 and sets access control. See Using the
- Share-Offer Utilities for a description of the SVOFFER function.
-
- Once the variable has been shared and the appropriate access control
- established, commands can then be passed to AP 207 in the form of a two-element
- vector, the first element of which is the name of the command and the second
- contains the parameters required by the command. For example:
-
- SHR207Γò£'OPEN' 0
- DISPLAY Р╜SHR207
- 0 1
- ΓöîΓòòΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
- Γöé ΓöîΓòòΓöÉ Γöé
- Γöé 0 Γöé1Γöé Γöé
- Γöé Γöö~Γöÿ Γöé
- └ю──────┘
- SHR207Γò£'DRAW' (1 100 100)
- DISPLAY Р╜SHR207
- 0
- ΓöîΓòòΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
- │ ┌щ┐ │
- Γöé 0 Γöé0Γöé Γöé
- Γöé Γöö~Γöÿ Γöé
- └ю──────┘
-
- This opens an OS/2 window, and then issues command DRAW with parameters
- 1 100 100.
-
- Most commands return a two-element vector. The first element is the numeric
- return code for the call, and the second contains any parameters returned by
- the call (as an enclosed array). Wherever possible, if a parameter is given
- outside of the valid range of values, the closest possible available value is
- chosen.
-
- You can issue more than one command in a single call. This is explained later,
- in Multiple-Call Sequences.
-
- Command names can be entered in any combination of uppercase or lowercase
- letters.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2. AP 207 Commands ΓòÉΓòÉΓòÉ
-
- Commands
-
- Command Description
- ARC Draw arc
- BEGAREA Begin filled area
- BITMAP Read/write bitmap files
- BOX Draw box
- CLEAR or ERASE Clear the graphics window
- CLOSE Close device
- COLMAP Define color mapping
- COLOR Set color
- CURSOR Enable or disable pointer cursor
- DRAW Draw a line
- ENDAREA End filled area
- ESCAPE Send escape sequence to device
- FONT Select image or vector font characteristics
- FONTDEF Define image or vector font
- IMAGE Display or read an image
- LINETYPE Set line type
- LOAD Load a device driver
- MARKER Write marker
- MIX Set mix mode
- MOVE Move to new point
- OPEN Open a device
- PALETTE Set color palette
- PATTERN Set area fill pattern
- POINTER Activate pointer device
- PRINT Print graphics window
- QUERY Query driver parameters
- QWRITE Query position and size of string
- SCISSOR Set scissoring rectangle
- SECTOR/WEDGE Draw a sector
- SETPEL Set one or more pels on
- USE Select a driver
- VIEW View graphics
- WAIT Wait for an event
- WINDOW Define window
- WRITE Write a character string
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.1. Arc-Description: ΓòÉΓòÉΓòÉ
-
- Draws an arc, an ellipse, or a circle.
-
- If used between BEGAREA and ENDAREA calls, each arc is filled independently.
-
- The current position is set to the end point of the arc.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.1.1. ARC-Syntax: ΓòÉΓòÉΓòÉ
-
- CΓò£'ARC' (X Y X_RAD Y_RAD START_ANG END_ANG)
-
- where:
-
- X,Y give the center of the arc
-
- X_RAD,Y_RAD give the radius of the arc along the x and y axes
-
- START_ANG,END_ANG give the starting and ending angles of the arc in
- degrees.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.2. BEGAREA-Description: ΓòÉΓòÉΓòÉ
-
- Start collecting points to define an area to fill. The ENDAREA call ends the
- collection of points and fills any polygons defined since the previous BEGAREA
- call.
-
- The following commands are not allowed between BEGAREA and ENDAREA commands:
-
- BITMAP LINE
- CLOSE LINETYPE
- COLMAP MIX
- COLOR OPEN
- FONT PALETTE
- FONTDEF PATTERN
- IMAGE PRINT
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.2.1. BEGAREA-Syntax: ΓòÉΓòÉΓòÉ
-
- CΓò£'BEGAREA' ''
-
- (Null string)
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.3. BITMAP-Description: ΓòÉΓòÉΓòÉ
-
- This command reads a file and writes the bitmap in a window.
-
- Note: This command is not portable across platforms.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.3.1. BITMAP-Syntax: ΓòÉΓòÉΓòÉ
-
- CΓò£'BITMAP' 'FILESPEC'
-
- Reads the bitmap file and returns the size in pels of the bitmap as defined in
- the bitmap file.
-
- CΓò£'BITMAP' ('FILESPEC' WIDTH HEIGHT')
-
- Writes the bitmap to the window at the current position. The bitmap is scaled
- to fit the width and height requested. Colors are mapped to the logical color
- table on a best fit basis. Returns the size of the bitmap as defined in the
- bitmap file.
-
- CΓò£'FILESPEC' XLEFT YBOTTOM XRIGHT XTOP
-
- Writes an area in world coordinates to the filespec in a bitmap 2.0 format. The
- area bounded by the world coordinates must be visible on the screen as the data
- is read directly from the display. The resultant size and resolution of the
- bitmap is dependent on the current window scale. For completely repeatable
- results, the window size, the world coordinates, and the view coordinates
- should all be the same. Returns a character array comparable to the 'IMAGE'
- read command.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.4. BOX-Description: ΓòÉΓòÉΓòÉ
-
- This command draws a rectangular box.
-
- Note: This command is not portable across platforms.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.4.1. BOX-Syntax: ΓòÉΓòÉΓòÉ
-
- CΓò£'BOX' (XCORNER YCORNER HAXIS VAXIS)
-
- Draws a rectangular box from the current position to the corner at
- xCorner,yCorner with the corners rounded by the ellipse on the horizontal full
- axis of hAxis and the vertical full axis of vAxis. Values of 0,0 on hAxis,vAxis
- give a rectangular box. This primitive does not alter the current position.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.5. CLEAR OR ERASE-Description: ΓòÉΓòÉΓòÉ
-
- Clears the graphics window and optionally sets the initial window color.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.5.1. CLEAR/ERASE-Syntax ΓòÉΓòÉΓòÉ
-
- CΓò£'CLEAR' 'COLOR_NAME'
-
- Clears the graphics window and fills the window with color COLOR_NAME.
- COLOR_NAME is one of: BACKGROUND, BLACK, BLUE, BROWN, CYAN, DBLUE, DCYAN,
- DGRAY (or DGREY), DGREEN, DMAGENTA, DRED, GRAY (or GREY) GREEN, MAGENTA,
- NEUTRAL, RED, WHITE or YELLOW. The closest matching color from the color map
- array is selected. Any color beginning with a "D" is a dark version of the
- specified color. Returns the color map row number used. CΓò£'CLEAR' COLOR_NO
-
- Clears the graphics window and fills the window with color COLOR_NO. COLOR_NO
- is 0 to 255 and specifies the (0-origin) row number of the color map array, as
- defined by the COLMAP call. Returns the color map row number used.
-
- CΓò£'CLEAR' (R,G,B)
-
- Clears the graphics window and fills the window with the color that is the best
- possible match available in the current color map array. R, G, and B are
- numbers in the range 0 to 1000 and specify the desired level of red, green, and
- blue. Returns the color map row number used.
-
- CΓò£'CLEAR' ''
-
- Clears the graphics window and sets the window to the background color. Returns
- the color map row number used.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.6. CLOSE-Description: ΓòÉΓòÉΓòÉ
-
- Close the active device.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.6.1. CLOSE-Syntax ΓòÉΓòÉΓòÉ
-
- CΓò£'CLOSE' ''
-
- Closes the currently active device.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.7. COLMAP-Description: ΓòÉΓòÉΓòÉ
-
- Defines the mapping between the color numbers used with the COLOR call and the
- actual palette entry used. The R, G, and B values are numbers in the range 0 to
- 1000 and specify the desired level of red, green and blue.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.7.1. COLMAP-Syntax ΓòÉΓòÉΓòÉ
-
- C╜'COLMAP' ((N,3)цR1,G1,B1,...,RN,GN,BN)
-
- Sets the color map table for entries 0 to N-1 with the color that is the best
- possible match available in the current palette. CΓò£'COLMAP'
- ((N,4)цINDEX1,R1,G1,B1,...,RN,GN,BN)
-
- INDEXN,RN,GN,BN Sets the color map table for the entries specified in the first
- column with the color that is the best possible match available in the current
- palette. CΓò£'COLMAP' (INDEX,R,G,B)
-
- Set the color map table entry INDEX with the color that is the best possible
- match available in the current palette. CΓò£'COLMAP' (INDEX 'COLOR_NAME')
-
- Set the color map table entry INDEX to the closest matching color available in
- the current palette. COLOR_NAME is one of: BACKGROUND, BLACK, BLUE, BROWN,
- CYAN, DBLUE, DCYAN, DGRAY (or DGREY), DGREEN, DMAGENTA, DRED, GRAY (or GREY),
- GREEN, MAGENTA, NEUTRAL, RED, WHITE, or YELLOW. CΓò£'COLMAP' INDEX
-
- Returns the current setting for the color map table entry INDEX as a 1-by-5
- matrix. C╜'COLMAP' ¤1
-
- Resets the color map table to match the current palette colors. CΓò£'COLMAP' ('')
-
- Returns the current color map table as a 256ї5 matrix, each row of which
- contains the color map table row index, the corresponding row of the palette
- table and the r, g, b values for this row.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.8. COLOR-Description: ΓòÉΓòÉΓòÉ
-
- Sets a new foreground color. If called within a BEGAREA-ENDAREA sequence, this
- call forces the polygon defined by the points already established to be filled
- with the previous color, and any new points are filled with the new color.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.8.1. COLOR-Syntax ΓòÉΓòÉΓòÉ
-
- CΓò£'COLOR' 'COLOR_NAME'
-
- Sets the active foreground color to COLOR_NAME. COLOR_NAME is one of:
- BACKGROUND, BLACK, BLUE, BROWN, CYAN, DBLUE, DCYAN, DGRAY (or DGREY), DGREEN,
- DMAGENTA, DRED, GRAY (or GREY), GREEN, MAGENTA, NEUTRAL, RED, WHITE, or YELLOW.
- The closest matching color from the color map is selected. Any color beginning
- with a "D" is a dark version of the specified color. Returns the color map row
- number selected. CΓò£'COLOR' COLOR_NO
-
- Sets the active foreground color to COLOR_NO, where COLOR_NO is 0 to 255 and
- specifies the (0-origin) row number of the color map array, as defined by the
- COLMAP call. Returns the color map row number selected. CΓò£'COLOR' (R,G,B)
-
- Sets the active foreground color to the best possible match available in the
- current color map. R, G, and B are numbers in the range 0 to 1000 and specify
- the desired level of red, green, and blue. Returns the color map row number
- selected. CΓò£'COLOR' ('')
-
- Returns the current color map row number of the active foreground color.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.9. CURSOR-Description: ΓòÉΓòÉΓòÉ
-
- Activates the pointer cursor.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.9.1. CURSOR-Syntax ΓòÉΓòÉΓòÉ
-
- CΓò£'CURSOR' 0
-
- Selects the default state for the cursor. In APL2/2 the cursor is permanently
- enabled and this selects the default cursor.
-
- CΓò£'CURSOR' 1
-
- Enables the display of the cross-hair cursor.
-
- CΓò£'CURSOR' ('')
-
- Queries the current state of the cursor.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.10. DRAW-Description: ΓòÉΓòÉΓòÉ
-
- Move or draw ("MD") to a specified point. The line is drawn with the active
- foreground color and current linetype. The current position is set to the last
- coordinate given.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.10.1. DRAW-Syntax ΓòÉΓòÉΓòÉ
-
- CΓò£'DRAW' (X,Y)
-
- Draws a line from the current position to (X,Y).
-
- CΓò£'DRAW' (MD,X,Y)
-
- Moves to (X,Y) if MD=0, or draws a line to (X,Y) if MD=1.
-
- C╜'DRAW' ((N,2)цX1,Y1,...,XN,YN)
-
- Performs a move to (X1,Y1), and then draws to each (X,Y) coordinate given in
- subsequent rows of the matrix.
-
- C╜'DRAW' ((N,3)цMD1,X1,Y1,...,MDN,XN,YN)
-
- Performs successive moves (MD=0) or draws (MD=1) to the X and Y coordinate
- given in each row of the matrix.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.11. ENDAREA-Description: ΓòÉΓòÉΓòÉ
-
- Signal the end of a polygon to fill. This ends the collection of points and
- fills any polygons defined since the previous BEGAREA call.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.11.1. ENDAREA-Syntax ΓòÉΓòÉΓòÉ
-
- CΓò£'ENDAREA' ('')
-
- Fill all polygons defined since the previous BEGAREA call.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.12. ESCAPE-Description: ΓòÉΓòÉΓòÉ
-
- Send a device-driver-dependent string to the driver. An application using this
- is not portable between systems.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.12.1. ESCAPE-Syntax ΓòÉΓòÉΓòÉ
-
- CΓò£'ESCAPE' (PARAMETERS)
-
- As defined by device driver.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.13. FONT-Description: ΓòÉΓòÉΓòÉ
-
- Specifies the characteristics of the image or vector font.
-
- Sets the font direction, size, horizontal alignment, vertical alignment, and
- various other parameters.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.13.1. FONT-Syntax ΓòÉΓòÉΓòÉ
-
- CΓò£'FONT' ('FONTNAME' SIZE ANGLE XJUST YJUST DIRECTION SHEAR XMAG NOPARSE)
-
- FONTNAME name of the font as defined with the FONTDEF call, or 0 for built-in
- image font
- SIZE uppercase character height in world coordinate system units (ignored
- for image font for display; on printers, this is scaled depending on
- the print driver)
- ANGLE specifies the text baseline angle (must be 0 for an image font)
- XJUST 0 (left justify), 1 (center) or 2 (right justify)
- YJUST 0 (character baseline), 1 (center), 2 (uppercase character top), 3
- (character box bottom), or 4 (character box top)
- DIRECTION (reserved-set to 0)
- SHEAR angle (in degrees) to shear vector characters in order to produce
- effects such as italics (must be 0 for image font)
- XMAG magnification to be applied to x-axis of characters to produce
- effects like stretched characters (must be 1 for image font)
- NOPARSE (reserved-set to 0).
-
- Any parameters that are not supplied default to 0 except XMAG defaults to 1 and
- SIZE defaults to the size defined by the font. Many parameters have no effect
- on image characters. Portable applications should use vector fonts since these
- can be reproduced consistently on various devices.
-
- CΓò£'FONT' ('')
-
- Returns current font parameters. This has four elements in addition to those
- defined above:
-
- BOX_HEIGHT the total character box height
- DESCENDER_HEIGHT the distance from the baseline to the bottom of the character
- box
- MAX_WIDTH the maximum width of any character in the font
- FONT_TYPE 0 for an image font and 1 for a vector font
-
- Note: (This parameter may not be used in a multiple-call sequence.)
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.14. FONTDEF-Description: ΓòÉΓòÉΓòÉ
-
- Specifies the name of an image or vector font file.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.14.1. FONTDEF-Syntax ΓòÉΓòÉΓòÉ
-
- CΓò£'FONTDEF' ('FONTNAME' 'FILENAME')
-
- Loads font specified and adds FONTNAME to AP 207 font table. The maximum
- length of FONTNAME is 12 characters. This command loads the font file from path
- if possible. It then searches the current directory, followed by paths listed
- in environment variables "APL207FL", "DPATH", and "PATH".
-
- To use the supplied APL2 vector fonts, note that FILENAME must include the
- ".AVF" extension.
-
- C╜'FONTDEF' ('FONTNAME' ¤1)
-
- Removes FONTNAME from AP 207 font table.
-
- CΓò£'FONTDEF' ('')
-
- Returns current AP 207 font table. This is returned as three character arrays:
-
- o Font status-a two-column matrix. The first column contains "A" if the font is
- active or a blank otherwise. The second column contains "V" for a vector
- font, "I" for an OS/2 system image font, "P" for an OS/2 system PostScript
- font, or a blank if no font is defined for this row.
-
- o A matrix of font names (as specified on FONTDEF call).
-
- o A matrix of file names.
-
- Note: (This parameter may not be used in a multiple-call sequence.)
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.15. IMAGE-Description: ΓòÉΓòÉΓòÉ
-
- Display a character image array, or read an image.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.15.1. IMAGE-Syntax ΓòÉΓòÉΓòÉ
-
- CΓò£'IMAGE' (IMAGE)
-
- Displays image with lower-left corner placed at the current position, as set by
- a previous move call. IMAGE is a character matrix, each element of which is the
- РAF of the (0-origin) row number in the color map array to be used for the
- corresponding world coordinates. Image is scaled as necessary.
-
- You receive an error message if you specify color indexes that are not defined
- in the color map.
-
- Returns the coordinates of the lower-left and upper-right corners of the image,
- in world coordinates.
-
- CΓò£'IMAGE' (X1,Y1,X2,Y2)
-
- Reads an image within the rectangle defined by the world coordinates specified;
- the coordinates identify either pair of diagonally-opposite corners. Returns a
- character matrix, each element of which is the РAF of the (0-origin) row number
- in the color map array that is the closest match to the color of the
- corresponding pel.
-
- Note: (This may not be used in a multiple-call sequence.)
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.16. LINETYPE-Description: ΓòÉΓòÉΓòÉ
-
- Set the line attributes.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.16.1. LINETYPE-Syntax ΓòÉΓòÉΓòÉ
-
- CΓò£'LINETYPE' (WIDTH,STYLE)
-
- Sets line type parameters. WIDTH is 1 to maximum, STYLE is 1 to maximum. The
- number of available line widths and styles is given by the QUERY call. A value
- of 0 for either parameter gives the default attribute for that parameter (thin,
- solid line). Returns the selected line type parameters.
-
- CΓò£'LINETYPE' ('')
-
- Returns the current line type parameters.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.17. LOAD-Description: ΓòÉΓòÉΓòÉ
-
- Load a device driver into the auxiliary processor.
-
- Note: This command is ignored by APL2/2.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.17.1. LOAD-Syntax ΓòÉΓòÉΓòÉ
-
- CΓò£'LOAD' DEVICE_NAME
-
- Loads the device driver with name DEVICE_NAME, assigning a device handle (an
- integer value that can be used by the USE call) to the driver.
-
- CΓò£'LOAD' ('')
-
- Returns the device names of the available drivers, along with their device
- handles or a ¤1 if the driver is available but not loaded.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.18. MARKER-Description: ΓòÉΓòÉΓòÉ
-
- Write one or more markers centered at given positions.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.18.1. MARKER-Syntax ΓòÉΓòÉΓòÉ
-
- CΓò£'MARKER' MARKER
-
- Selects marker type MARKER. MARKER is 1 to maximum. A value of 0 gives the
- default marker that is a cross. The number of available markers is given by the
- QUERY call. Returns the marker selected.
-
- CΓò£'MARKER' (X,Y)
-
- Writes current marker centered at position (X,Y).
-
- C╜'MARKER' ((N,2)цX1,Y1,...,XN,YN)
-
- Writes current marker centered at the X and Y coordinates given by each row of
- the matrix.
-
- C╜'MARKER' ((N,3)цMD1,X1,Y1,...,MDN,XN,YN)
-
- Writes current marker centered at the X and Y coordinates of the ends of each
- line segment that would be drawn by a DRAW call with the same array. (MD
- indicates move or draw. A marker is drawn on all rows where MD=1 and on rows
- where MD=0 precedes a row where MD=1.)
-
- CΓò£'MARKER' ('')
-
- Returns the current marker type.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.19. MIX-Description: ΓòÉΓòÉΓòÉ
-
- Sets the color mixing mode.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.19.1. MIX-Syntax ΓòÉΓòÉΓòÉ
-
- CΓò£'MIX' 0
-
- Pels to be written directly replace existing pels. This is the default.
-
- CΓò£'MIX' 1
-
- Pels to be written are ANDed with existing pels.
-
- CΓò£'MIX' 2
-
- Pels to be written are ORed with existing pels. This gives a color mixing
- effect.
-
- CΓò£'MIX' 3
-
- Pels to be written are exclusive-ORed with existing pels. This can be used to
- move objects around, since writing the same object back into the same position
- in this mode restores the original screen, making the object disappear. Returns
- the mixing mode selected.
-
- CΓò£'MIX' ('')
-
- Returns the current mixing mode.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.20. MOVE-Description: ΓòÉΓòÉΓòÉ
-
- Move to a specified point. The current position is set to the coordinate given.
- No line is drawn.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.20.1. MOVE-Syntax ΓòÉΓòÉΓòÉ
-
- CΓò£'MOVE' X,Y
-
- Moves to (X,Y). Returns the new x,y position.
-
- CΓò£'MOVE' ('')
-
- Returns the current x,y position.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.21. OPEN-Description: ΓòÉΓòÉΓòÉ
-
- Open the Presentation Manager window into a state of readiness for graphics.
-
- Note: Open performs an implicit close if an open device exists.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.21.1. OPEN-Syntax ΓòÉΓòÉΓòÉ
-
- CΓò£'OPEN' (VIDEO_MODE 'TITLE' WIDTH HEIGHT XPOS YPOS)
-
- The only VIDEO_MODE supported by the OS/2 services device driver is 1. This can
- also be selected by specifying a parameter of 0 which is preferred since this
- allows AP 207 code to be portable between different implementations. TITLE is
- the name that appears on the title bar of the window and in the icon for this
- window. If not specified, the title is "AP207". WIDTH and HEIGHT specify the
- width and height of the initial window in device units (pels) and default to
- 640 and 480 respectively. XPOS and YPOS specify the initial x and y position of
- the window. If these are not given, interactive window placement is used.
-
- CΓò£'OPEN' ('')
-
- Returns the current video mode, which is 0 if an OPEN has not yet been issued.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.22. PALETTE-Description: ΓòÉΓòÉΓòÉ
-
- This command is synonymous with COLMAP. For more information, see COLMAP-Define
- Color Mapping.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.22.1. PALETTE-Syntax ΓòÉΓòÉΓòÉ
-
- Note: see "COLMAP-Define Color Mapping"
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.23. PATTERN-Description: ΓòÉΓòÉΓòÉ
-
- Sets the active fill pattern. If issued within a BEGAREA-ENDAREA sequence, this
- call forces the polygon defined by the points already established to be filled
- with the previous pattern and any new points are filled with the new pattern.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.23.1. PATTERN-Syntax ΓòÉΓòÉΓòÉ
-
- CΓò£'PATTERN' PATTERN
-
- Sets the active fill pattern to PATTERN. PATTERN is 1 to maximum. A value of 0
- gives the default fill pattern that is a solid fill. The number of available
- patterns is given by the QUERY call. Returns the pattern selected.
-
- CΓò£'PATTERN' ('')
-
- Returns the current fill pattern number.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.24. POINT-Description: ΓòÉΓòÉΓòÉ
-
- Activate the graphics pointer device.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.24.1. POINT-Syntax ΓòÉΓòÉΓòÉ
-
- CΓò£'POINT' (0[,X_INITIAL,Y_INITIAL])
-
- Activates the graphics pointer device, pointing initially at (X_INITIAL,
- Y_INITIAL), or the current position if an initial position is not given.
- Returns 1,X_FINAL,Y_FINAL,BUTTON_NO when a mouse button is released, or
- 2,X_FINAL,Y_FINAL,C,S when a keyboard key is pressed. C and S are the character
- code and scan code as returned by the AP 124 calls (3 1), (3 2), and (3 3) as
- described for AP 124 under Read and Wait or Read and Test.
-
- CΓò£'POINT' (1[,X_START,Y_START[,X_INITIAL, Y_INITIAL]])
-
- Activates the graphics pointer device, pointing initially at (X_INITIAL,
- Y_INITIAL) or the current position if an initial position is not given. Draws a
- "rubber band" line from (X_START,Y_START) (or the current position if not
- given) to the location of the pointer. Returns the same data as for the 0 case.
-
- CΓò£'POINT' (2,X_START,Y_START[,X_END,Y_END [,X_INITIAL,Y_INITIAL]])
-
- Activates the graphics pointer device, pointing initially at (X_INITIAL,
- Y_INITIAL) or the current position if an initial position is not given. Draws a
- "rubber band" line from (X_START,Y_START) to (X_END,Y_END) (or the current
- position if not given) as two line segments via the location of the pointer.
- Returns the same data as for the 0 case.
-
- CΓò£'POINT' (3,X_START,Y_START[,X_END,Y_END [,X_INITIAL,Y_INITIAL]])
-
- Same as for 2 option, but an additional line is drawn to form a "rubber band"
- triangle between (X_START,Y_START), (X_END,Y_END) and the current pointer
- location. Returns the same data as for the 0 case.
-
- CΓò£'POINT' (4[,X_START,Y_START[,X_INITIAL, Y_INITIAL]])
-
- Same as for 1 option, but draws a "rubber band" rectangle with one corner at
- (X_START,Y_START) and the opposite corner at (X_INITIAL,Y_INITIAL) or the
- current position if an initial position is not given. Returns the same data as
- for the 0 case.
-
- CΓò£'POINT' ('')
-
- Immediately returns the graphics pointer position and mouse button status.
- Returns 0,X_POINTER,Y_POINTER[,BUTTON_NOS]. If the pointer lies outside of the
- AP 207 window, X_POINTER and Y_POINTER are still relative to the lower-left
- corner; therefore, negative values are possible. BUTTON_NOS are the numbers of
- any mouse buttons currently pressed.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.25. PRINT-Description: ΓòÉΓòÉΓòÉ
-
- Dumps the graphic window contents to the currently-selected printer.
-
- Notes:
-
- 1. The Printer Setup menu item gives access to change the default printer and
- job properties.
-
- 2. Metafiles and print files that contain bitmap or image data may require the
- printer-specific job property to be on, or the spooler to be disabled.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.25.1. PRINT-Syntax ΓòÉΓòÉΓòÉ
-
- CΓò£'PRINT' 'FILESPEC'
-
- Creates an OS/2 metafile if no file by that name currently exists. The metafile
- can be dropped on any printer object.
-
- CΓò£'PRINT' ('')
-
- Prints the window contents on the default printer.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.26. QUERY-Description: ΓòÉΓòÉΓòÉ
-
- Queries driver parameters. Returns the active Presentation Manager display as
- driver 1. This is the only driver supported for OS/2.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.26.1. QUERY-Syntax ΓòÉΓòÉΓòÉ
-
- CΓò£'QUERY' ('')
-
- Returns: DRIVER_NAME,PARMS
-
- The default driver name is ""OS/2 Presentation Manager"." PARMS is a numeric
- matrix, each row of which is:
-
- [;1] Video mode. Only one mode (mode 1) is supported by the OS/2 services
- driver.
- [;2] Width of screen in pels
- [;3] Height of screen in pels
- [;4] Number of different colors displayable
- [;5] Number of different line styles available
- [;6] Number of different line widths available
- [;7] Number of different fill patterns available
- [;8] Number of different markers available
- [;9 10] Aspect ratio. The ratio of these two numbers (Ў/PARMS[;9 10]) gives the
- x size of a pel divided by the y size of a pel.
-
- The width and height of screen are given as the total physical screen size
- before an OPEN call is issued, and are given as the current AP 207 window size
- after an OPEN call.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.27. QWRITE-Description: ΓòÉΓòÉΓòÉ
-
- Returns the position and size of the character string specified.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.27.1. QWRITE-Syntax ΓòÉΓòÉΓòÉ
-
- CΓò£'QWRITE' 'TEXT'
-
- Returns six elements specifying the x and y coordinates of the lower-left,
- upper-left and the lower-right corners of the text box assuming it is placed at
- the current x and y location. The coordinates of the remaining corner
- (upper-right) can be readily calculated from the three given.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.28. SCISSOR-Description: ΓòÉΓòÉΓòÉ
-
- Defines the rectangular area within which graphics can be drawn. Any parts of a
- graphics object falling outside of this rectangle are clipped at the boundary.
- Initially, the scissoring rectangle is set to the window boundary.
-
- Setting the system window to (0 0 0 0) turns off scissoring. The default is
- off.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.28.1. SCISSOR-Syntax ΓòÉΓòÉΓòÉ
-
- CΓò£'SCISSOR' (X1,Y1,X2,Y2)
-
- Defines the lower-left and upper-right corners of the scissoring rectangle in
- world coordinate units. Returns the new scissoring rectangle selected.
-
- CΓò£'SCISSOR' ('')
-
- Returns the current scissoring rectangle.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.29. SECTOR/WEDGE-Description: ΓòÉΓòÉΓòÉ
-
- Draw a sector of an ellipse or a circle. If used between a BEGAREA and an
- ENDAREA, each sector is filled independently.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.29.1. SECTOR/WEDGE-Syntax ΓòÉΓòÉΓòÉ
-
- CΓò£'SECTOR/WEDGE' (X,Y,X_RAD,Y_RAD,START_ANG,END_ANG)
-
- Where
-
- X,Y give the center of the sector
- X_RAD,Y_RAD give the radius of the sector along the x and y axes
- START_ANG,END_ANG give the starting and ending angles of the sector in degrees
- The current position is set to the coordinate of the center of the sector.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.30. SETPEL-Description: ΓòÉΓòÉΓòÉ
-
- Sets one or more pels to the specified color.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.30.1. SETPEL-Syntax ΓòÉΓòÉΓòÉ
-
- CΓò£'SETPEL' (COLOR,X,Y)
-
- Sets the pel at (X,Y) to the color defined by the row COLOR in the color map
- array.
-
- C╜'SETPEL' ((N,3)цCOLOR1,X1,Y1,...,COLORN,XN,YN)
-
- Sets the pel at each X,Y location to the corresponding color in the color map
- array.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.31. USE-Description: ΓòÉΓòÉΓòÉ
-
- Select a driver for subsequent use by AP 207.
-
- Note: This command is ignored by APL2/2.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.31.1. USE-Syntax ΓòÉΓòÉΓòÉ
-
- CΓò£'USE' 0
-
- Device 0 is the internal OS/2 services driver. This is automatically used when
- AP 207 is started and need not be explicitly specified.
-
- CΓò£'USE' ('')
-
- Returns the name of the current driver.
-
- Note: May not be used in a multiple-call sequence.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.32. VIEW-Description: ΓòÉΓòÉΓòÉ
-
- View the graphics and wait for a user input.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.32.1. VIEW-Syntax ΓòÉΓòÉΓòÉ
-
- CΓò£'VIEW' ('')
-
- Makes the AP 207 window the active window. This is the only portable VIEW
- syntax.
-
- CΓò£'VIEW' ('ON')
-
- Makes the AP 207 window the active window. The handle of the program that was
- active when this command was issued is saved for use.
-
- CΓò£'VIEW' ('OFF')
-
- Restores the active status to the window saved by the previous ON command.
-
- CΓò£'VIEW' (XLEFT,YBOTTOM,XRIGHT,YTOP)
-
- Sets the area of interest to be displayed in the window. When the window is
- sized, the contents of the window are scaled as needed to maintain aspect
- ratio.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.33. WAIT-Description: ΓòÉΓòÉΓòÉ
-
- Wait for a user input or other event.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.33.1. WAIT-Syntax ΓòÉΓòÉΓòÉ
-
- CΓò£'WAIT' N
-
- Waits for N seconds. If N is 0, it returns immediately. Returns:
-
- 0,TIME,X,Y if no event occurred during the specified interval
- 1,TIME,X,Y,BUTTON_NO,BPR if a mouse button was either pressed or released
- 2,TIME,X,Y,C,S if a keyboard key was pressed
-
- TIME is the time (in seconds) that the event was detected. X and Y give the
- current graphic pointer position. X or Y may be negative if the cursor is
- outside of the AP 207 window. BUTTON_NO is the number of the mouse button that
- was pressed or released, and BPR is 1 if the button has been pressed, or 0 if
- the button has been released. C and S are the character code and scan code as
- returned by the AP124 calls (3 1), (3 2), and (3 3) as described for AP 124
- under Read and Wait or Read and Test.
-
- To clear all queued events, use the expression: ╕(0Ї╞1╟SHR207,SHR207╜'WAIT'
- 0)/РLC
-
- CΓò£'WAIT' ('')
-
- Waits indefinitely for an event. Returns the same data as above, except that
- the 0 time-out case is never returned.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.34. WINDOW-Description: ΓòÉΓòÉΓòÉ
-
- Define a window on the device for graphics and establish a world coordinate
- system to be mapped into this window. See Defining World Coordinates with
- Correct Aspect Ratio for details of using this call to preserve screen aspect
- ratios.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.34.1. WINDOW-Syntax ΓòÉΓòÉΓòÉ
-
- CΓò£'WINDOW' (WINDOW,VIEWPORT)
-
- WINDOW=WX1,WY1,WX2,WY2-Specifies the bottom left and top right of the display
- window box in device (pel) coordinates. VIEWPORT=VX1,VY1,VX2,VY2-Specifies
- world coordinates corresponding to the bottom left and top right of the window.
-
- CΓò£'WINDOW' ('')
-
- Returns the current window and viewport parameters. The window defaults to the
- entire screen, and the viewport defaults to the device (pel) coordinates.
-
- Note: (This parameter may not be used in a multiple-call sequence.)
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.35. WRITE-Description: ΓòÉΓòÉΓòÉ
-
- Write some text in the current setting of color, font, and position.
-
-
- ΓòÉΓòÉΓòÉ 14.8.2.35.1. WRITE-Syntax ΓòÉΓòÉΓòÉ
-
- CΓò£'WRITE' 'TEXT'
-
- Writes text at the current position. Returns eight elements specifying the x
- and y coordinates of the lower-left, upper-left, lower-right and upper-right
- corners of the text box.
-
-
- ΓòÉΓòÉΓòÉ 14.8.3. Multiple-Call Sequences ΓòÉΓòÉΓòÉ
-
- Several commands can be issued to AP 207 in a single call. This requires the
- calls to be catenated into an even-length vector with alternating commands and
- parameters. The result is one longer than the number of commands. Its first
- element is the highest return code encountered in all the calls issued,
- followed by the return codes from each individual call. For example:
-
- SHR207Γò£'COLOR' 'BLUE' 'ARC' (100 100 50 50 0 360)
- DISPLAY Р╜SHR207
- 0 0 1 0
- ΓöîΓòòΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
- Γöé ΓöîΓòòΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ ΓöîΓòòΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ ΓöîΓòòΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ Γöé
- │ │ ┌щ┐ │ │ ┌╕┐ │ │ ┌щ┐ │ │
- Γöé Γöé 0 Γöé0Γöé Γöé Γöé 0 Γöé1Γöé Γöé Γöé 0 Γöé0Γöé Γöé Γöé
- Γöé Γöé Γöö~Γöÿ Γöé Γöé Γöö~Γöÿ Γöé Γöé Γöö~Γöÿ Γöé Γöé
- │ └ю──────┘ └ю──────┘ └ю──────┘ │
- └ю──────────────────────────────┘
-
- This enables you to use the expression 0Ї╞╞SHR207 to establish whether or not
- an error occurred in any of the calls issued.
-
-
- ΓòÉΓòÉΓòÉ 14.8.4. Defining World Coordinates with Correct Aspect Ratio ΓòÉΓòÉΓòÉ
-
- To get the aspect ratio for a particular mode after a window has been opened
- (using the OPEN command):
-
- РIO╜1
- SHR207Γò£'OPEN' ''
- (RC MODE)Γò£SHR207
- MODEΓò£Γò₧MODE
- SHR207Γò£'QUERY' ''
- (RC DRIVER PARMS)Γò£SHR207
- PARMS╜уPARMS ф Data for supported modes
- Q╜,(PARMS[;1]=''цMODE)ЁPARMS ф Q is data for this mode
- AR_PEL╜Ў/Q[9 10] ф Ratio of pel x to y size
- AR_SCRN╜Ў/Q[2 3]їQ[9 10] ф Screen aspect ratio.
-
- Usually you want to define a set of world coordinates that are independent of
- the actual pel coordinates on the screen. This is done by using the WINDOW call
- to AP 207. In many cases, the world coordinates should preserve aspect ratio;
- that is, one unit in world coordinates in the x direction should be the same
- physical size on the device as one unit in world coordinates in the y
- direction. The following example is useful in defining a world coordinate
- system that preserves aspect ratio. To map the whole screen to world
- coordinates ranging from 0 to 1000 in x and pick the maximum y world coordinate
- to preserve aspect ratio:
-
- WIN_PARMS╜0 0,(Q[2 3]-1),0 0 1000,¤1+╛0.5+1001ЎAR_SCRN
- SHR207Γò£'WINDOW' WIN_PARMS
-
-
- ΓòÉΓòÉΓòÉ 14.8.5. Image and Vector Font Support ΓòÉΓòÉΓòÉ
-
- AP 207 can use either external image (bitmap) or vector font files in writing
- text. This support provides for rapid display of characters from any of a
- variety of fonts.
-
- Image (bitmap) fonts are easy to read in small sizes since they are mapped
- directly to the pels on the screen. They differ in appearance on different
- displays and in printed copies. The minimum size may also be larger than
- desired.
-
- Vector fonts can be scaled to any size and rotated, sheared, or stretched as
- desired. They are device-independent, although they may be somewhat distorted
- on low-resolution displays.
-
- The vector fonts supplied with APL2/2 are listed below. Most of the fonts
- consist of straight-line segments only. Thus the space between the vectors may
- become visible for characters in larger sizes. Fonts labeled as "Filled" use
- the AP 207 area filling routines to fill the character interiors. These
- characters look better in large sizes, although they are slower to draw and may
- not look as good in small sizes.
-
- o AP 207 Vector Fonts Supplied
- o AP 207 Vector Font File Format
- o Font Index
- o Font Width Table
- o Font Character Definition Data
-
-
- ΓòÉΓòÉΓòÉ 14.8.5.1. AP 207 Vector Fonts Supplied ΓòÉΓòÉΓòÉ
-
- See Supplied vector fonts.
-
-
- ΓòÉΓòÉΓòÉ 14.8.5.1.1. Supplied vector fonts - Part 1 ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Font file name
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Description
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- GOTENG.AVF
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Gothic English
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- GOTGER.AVF
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Gothic German
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- GOTITA.AVF
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Gothic Italian
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- GRESER.AVF
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Greek Serif (with some mathematical symbols)
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- GRESIM.AVF
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Greek Simplex (with some mathematical symbols)
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- MARKERS.AVF
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Markers (correspond to image markers from MARKERS call)
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- MODSIM.AVF
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Modern Simplex
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- ROMDUP.AVF
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Roman Duplex
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- ROMDUPF.AVF
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Roman Duplex Filled
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- ROMITA.AVF
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Roman Italic
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- ROMITAB.AVF
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Roman Italic Bold
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- ROMSER.AVF
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Roman Serif
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- ROMSERB.AVF
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Roman Serif Bold
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- ROMSIM.AVF
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Roman Simplex (contains full set of code page 910 characters)
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- MORE...
-
-
- ΓòÉΓòÉΓòÉ 14.8.5.1.2. Supplied vector fonts - Part 2 ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Font file name
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Description
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- ROMSIMM.AVF
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Roman Simplex Monospace (monospace version of ROMSIM.AVF)
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- SANSER.AVF
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Sans Serif
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- SANSERF.AVF
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Sans Serif Filled
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- SCRIPT.AVF
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Script
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- THKRNDF.AVF
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Thick Round Filled
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- THKRNDO.AVF
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Thick Round Outlined
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- THKSQUF.AVF
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Thick Square Filled
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- THKSQUO.AVF
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Thick Square Outlined
-
-
- ΓòÉΓòÉΓòÉ 14.8.5.2. AP 207 Vector Font File Format ΓòÉΓòÉΓòÉ
-
- AP 207 vector fonts are stored in files with a file extension of ".AVF" (APL
- Vector Font.) Each file defines 256 vector characters. Code page 910 is used to
- assign the characters to the code points except for fonts consisting of special
- characters not included in code page 910. The files consist of four parts
- described in more detail below: See Vector font format. See Font header format.
-
-
- ΓòÉΓòÉΓòÉ 14.8.5.2.1. Vector font format ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Start byte
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Length
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Description
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 0
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 32
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Font header
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 32
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 514
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Font index
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 546
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 512
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Font width table
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 1058
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Variable
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Font character definitions
-
-
- ΓòÉΓòÉΓòÉ 14.8.5.2.2. Font header format - Part 1 ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Start byte
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Length
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Description
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 0
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 4
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Total number of bytes in the file
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 4
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 2
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Font type:
-
- 1: 2-byte vector font (this is the only type currently allowed)
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 6
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 2
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Flags (bit 0 is low-order bit):
-
- Bit 0: 0 = Monospace font
- 1 = Proportionally spaced font
- Bits 1-15: Reserved
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 8
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 2
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Maximum character width in the font
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 10
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 2
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Height of capital letters
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- MORE...
-
-
- ΓòÉΓòÉΓòÉ 14.8.5.2.3. Font header format - Part 2 ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Start byte
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Length
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Description
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 12
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 2
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Recommended vertical spacing between lines (height of the character box)
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 14
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 2
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Distance from baseline (y=0) to bottom of the character box
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 16
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 16
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Reserved (must be 0)
-
-
- ΓòÉΓòÉΓòÉ 14.8.5.3. Font Index ΓòÉΓòÉΓòÉ
-
- These 514 bytes consist of 257 two-byte unsigned integers that give the offset
- from the beginning of the font character definitions of the definition of each
- of the 256 characters. These offsets are in units of two bytes since each
- coordinate is stored in two bytes (see below). These 256 integers are followed
- by an integer that contains the total number of byte pairs of font character
- definition data. The first of the 257 integers must always be 0 since the
- definition of the first character is always at offset 0. If a character in the
- font is not defined, two successive entries in the index are the same.
-
-
- ΓòÉΓòÉΓòÉ 14.8.5.4. Font Width Table ΓòÉΓòÉΓòÉ
-
- The next 512 bytes consist of 256 two-byte signed integers containing the
- widths of each of the 256 characters in the font. If a character is undefined,
- its width must be 0. For a monospace font, all the entries are equal to the
- number in the maximum character width field in the file header.
-
-
- ΓòÉΓòÉΓòÉ 14.8.5.5. Font Character Definition Data ΓòÉΓòÉΓòÉ
-
- The remaining bytes consist of the vector data for the characters in the font.
- Each coordinate is stored in two bytes; the first contains the x coordinate
- information, and the second contains the y information. The high-order bit of x
- contains the beam-blanking information: a vector is drawn to this point with
- the beam on if this bit is 1, and off if it is 0. The high-order bit of y
- contains information on filled areas. When this bit changes from 0 to 1, a
- BEGAREA call is generated before the vector is drawn. When it changes from 1 to
- 0, an ENDAREA call is generated before the vector is drawn.
-
- The remaining seven bits for x and y are interpreted as unsigned integers, and
- 64 is subtracted to obtain a pair of integers (x and y) in the range -64 to 63.
- These give the relative length of the vector to be drawn in x and y. All
- characters start at coordinate (0,0), and the last vector must end at y=0. The
- character baseline (bottom of "A") is at y=0.
-
- The following APL2 function extracts the character definition for single
- character C from the font data stored as a global character vector called
- FONTDATA, which can be read in as one long record using AP 210's Code C.
-
- Γòû
- [0] Z╜GETFONT C;BEAM;FDATA;FHEADER;FILL;FINDEX;XY;РIO
- [1] РIO╜1
- [2] ф FONTDATA is the font data in byte format.
- [3] ф It contains a 32-byte header, 514-byte index,
- [4] ф 512-byte width table, and font definition data.
- [5] FHEADER╜256Ээ16 2цРAF 32╞FONTDATA
- [6] FINDEX╜256Ээ257 2цРAF 32╟546╞FONTDATA
- [7] FDATA╜((¤1╞FINDEX),2)ц1058╟FONTDATA
- [8] C╜РAF ''цC
- [9] ф Get rows of FDATA which describe character C
- [10] Z╜РAF FDATA[FINDEX[1+C]+ь-/FINDEX[2 1+C];]
- [11] BEAM╜Z[;1]Є128
- [12] FILL╜Z[;2]Є128
- [13] XY╜+ё¤64+128│Z
- [14] ф Z is a 4-column matrix: beam off/on,
- [15] ф fill off/on, x coord, y coord
- [16] ZΓò£BEAM,FILL,XY
- Γòû
-
-
- ΓòÉΓòÉΓòÉ 14.8.6. AP 207 Return Codes ΓòÉΓòÉΓòÉ
-
- AP 207 return codes are returned as the first element of the two elements
- returned for each call.
-
- Code Meaning
- 0 - Success
- 1 - Unexpected driver or subsystem error
- 30 - Display mode not supported by this driver
- 31 - Invalid command
- 32 - Shared variable domain error
- 33 - Shared variable length error
- 34 - Shared variable rank error
- 35 - Invalid device handle
- 36 - No device currently selected
- 37 - Call not available with this driver or in this mode
- 38 - Call not permitted in multiple-call sequence
- 39 - Invalid parameter
- 40 - Scissor boundary outside window
- 41 - Attempt to place point outside of window
- 42 - Conflicting window-viewport definition
- 50 - Invalid video mode for this driver
- 51 - Device was not opened
- 52 - No fill area started
- 53 - Insufficient space for fill point storage
- 54 - Printer not ready
- 55 - Incorrect escape command
- 56 - Device not available
- 57 - Error while loading device driver
- 58 - Invalid device driver
- 60 - Font table is full
- 61 - Requested font not in font table
- 62 - Unable to load requested font
- 99 - Command not implemented
- ¤26 - Insufficient space
-
-
- ΓòÉΓòÉΓòÉ 14.9. AP 210-The File Auxiliary Processor ΓòÉΓòÉΓòÉ
-
- The file auxiliary processor, AP 210, is used to read from, or write to, fixed-
- or variable-length OS/2 disk files under control of the OS/2 file system. The
- reading and writing can be either sequential or random.
-
- Two shared variables are required to process a file: a data variable and a
- control variable. The control variable must be offered first. AP 210 then
- matches the earliest pending corresponding data variable offered by the partner
- (after the control variable). This occurs the first time it is required to
- satisfy an AP 210 command.
-
- The name of the data variable must always begin with the letter "D" or the
- letters "DAT", and the control variable must begin with the letter "C" or the
- letters "CTL". The remaining characters in both names (possibly none) must be
- the same, because the coupling of both variables is recognized by their name.
- Examples of valid pairs are: C and D, C1 and D1, and CXjj and DXjj. Also
- accepted as valid pairs (for compatibility with APL2/370) are CTL and DAT or
- CTL1 and DAT1. The control variable is used to select the operation to perform
- and to control each input/output operation. For example:
-
- 210 SVOPAIR 'C210' 'D210'
- 2 1
-
- offers two shared variables to AP 210 and sets access control. See Using the
- Share-Offer Utilities for a description of the SVOPAIR function (from the 1
- UTILITY workspace).
-
- o Control Commands
- o Control Subcommands
- o Establishing the AP 210 Translate Table
- o AP 210 Return Codes
- o Example of Use
-
-
- ΓòÉΓòÉΓòÉ 14.9.1. Control Commands ΓòÉΓòÉΓòÉ
-
- Once the control variable has been shared and the appropriate access control
- established, the first value you assign to it should be a character vector,
- which is considered to be a command that describes the file name and specifies
- the function to be performed. The following commands are accepted: 25i'.
-
- IR,filespec[,code] Open for read-only
- IW,filespec[,code] Open for read/write
- DL,filespec Delete file
- RN,filespec,filespec Rename file
-
- where filespec is the OS/2 file identification, of the form:
-
- [path]filename
-
- path is a valid OS/2 path and filename is a valid OS/2 file name.
-
- code is a single letter selecting a given interpretation of the file data. Five
- different interpretations are supported.
-
- Code Interpretation of Data
-
- A (APL2) The records in the file contain APL2 objects, with their
- headers. Arrays of arbitrary rank and depth can be stored and
- recovered. Different records of a file can contain objects of
- different types (for example, characters, integers, or real
- numbers). An APL2 object in a record may occupy up to the actual
- record length (not necessarily the same number of bytes), but
- the header fills a part of that area.
-
- B (Bool) The records in the file contain strings of bits without any
- header (packed eight bits per byte). The equivalent APL2 object
- is a Boolean vector. In this case, all records must be equal to
- the selected record length.
-
- C (Char) The contents of the record is a string of characters in ASCII,
- with no header. All records must be equal to the selected record
- length with each character occupying one byte. Variable-length
- records are not supported.
-
- D (ASCII) The contents of the record is a string of characters in ASCII
- code, with no header. Each character occupies one byte.
- Variable-length records are supported.
-
- T (Translate) The contents of the record is a string of characters, without
- any header, translated according to the AP 210 translate table
- defined as described in Establishing the AP 210 Translate Table.
- All records must be equal to the selected record length except
- when variable-length operations are being performed.
-
- If the code is not stated explicitly, code A is the default.
-
- The IR command opens the file for read-only operations. If the operation is
- successful, the control variable passes into the subcommand state. You must
- then specify which data transfer operation you want to perform. (See Control
- Subcommands.) The IW command works in a similar way, but the file is opened for
- both read and write operations. If the file cannot be opened, the control
- variable remains in the command state.
-
- When the DL command is received, the file with the specified filespec is
- erased. Then the control variable returns to the command state.
-
- When the RN command is received, the name of the file specified in the first
- parameter is changed to the name given in the second parameter. If a different
- path is given in the second parameter, a move is performed instead of a rename.
- After this command has been executed, the control variable returns to the
- command state.
-
- Once a command has been received and executed, a return code is passed back to
- APL2 through the control variable, indicating whether or not the command was
- executed successfully and, if not, the reason for the failure.
-
- If an IR or IW command executes successfully (giving a return code of 0 in the
- control variable), the data variable is set to the size, in bytes, of the file
- just opened.
-
-
- ΓòÉΓòÉΓòÉ 14.9.2. Control Subcommands ΓòÉΓòÉΓòÉ
-
- Once a file has been opened for input (command IR) or input/output (command
- IW), the control variable passes into the subcommand state. It now accepts the
- assignment of numeric vectors specifying the operation to perform, with the
- following structure:
-
- C210Γò£op[,rn[,rs]]
-
- The following are valid operations:
-
- 0 - Read a fixed-length record. Record size is defaulted to 128 unless
- specified by the rs operand or by a previous subcommand. Files are
- considered as being divided into fixed size records. rn is the record
- number. If not given, sequential operation is assumed.
-
- 1 - Write a fixed-length record. Record size is defaulted to 128 unless
- specified by the rs operand or by a previous subcommand. Files are
- considered as being divided into fixed size records. rn is the record
- number. If not given, sequential operation is assumed.
-
- 2 - Direct read from a file. Record size is defaulted to 128 unless specified
- by the rs operand or by a previous subcommand. Files are considered as
- being continuous strings of data. rn is the starting byte. If not given,
- sequential operation is assumed.
-
- 3 - Direct write to a file. Record size is defaulted to 128 unless specified
- by the rs operand or by a previous subcommand. Files are considered as
- being continuous strings of data. rn is the starting byte. If not given,
- sequential operation is assumed.
-
- 4 - Read a variable-length record. This command can only be used if the file
- was opened with codes A, D, or T. rs is the scan distance. For codes D and
- T, the LF character is searched for within the first rs bytes of a record.
- If rs is not given, the LF character is searched for within the first 128
- bytes, unless rs has been specified by a previous subcommand. If LF cannot
- be located, the record is not read, and a return code ¤44 is issued. rn is
- the record number. If not given, sequential operation is assumed. If rn is
- given but does not specify the next record in sequence, the file is
- scanned from the beginning in search of the requested record. Either
- specifying rn in sequence, or not specifying it at all, gives fastest
- execution.
-
- If reading with either code D or code T, the record returned in the data
- variable includes any record delimiter characters (LF or CR/LF depending
- on the origin of the file).
-
- 5 - Write a variable-length record. This command can only be used if the file
- was opened with codes A, D, or T. rn is the record number. If not given,
- sequential operation is assumed. If rn is given but does not specify the
- next record in sequence, the file is scanned from the beginning in search
- of the requested record. Either specifying rn in sequence, or not
- specifying it at all, gives fastest execution. If rn is greater than the
- number of records currently in the file, the record is appended to the end
- of the file.
-
- Direct write of variable-length records is allowed, but should be done
- with great care. Records should be replaced by others with exactly the
- same length. If this is not done, the whole file, starting at the replaced
- record, can be damaged.
-
- If the file was opened with either code D or code T, the CR/LF delimiters
- are appended to the end of each record as expected by OS/2 for sequential
- files. If the record already has a LF character (РTC[РIO+2]) appended, no
- additional delimiters are added.
-
- Code A files have no need for the LF record separator, as each record
- includes its own length, which makes each record self-describing, allowing
- AP 210 to skip through the file to the requested record.
-
- 6 - Operation 6 has the same syntax and behavior as operation 4, but
- end-of-line indicators (either CR/LF or LF) are removed from the data.
-
- rn is always defined in zero origin (the first record in a file is record 0;
- the first byte in a file is byte 0). If not specifically stated, the first
- value of rn after opening a file is 0 (that is, the first record or byte
- position in the file).
-
- Write operations are not allowed if the subcommand state was entered through
- the IR command.
-
- If the control variable is assigned an empty vector while in the subcommand
- state, the file is closed and the control variable reverts to the command
- state.
-
- Retracting the shared variables, either explicitly, with РSVR, or implicitly,
- by erasing the variables ()ERASE, РEX, or, if the variables have been
- localized, by exiting the function), clearing the workspace ()CLEAR), loading a
- new workspace ()LOAD) or ending the session ()OFF) causes AP 210 to close the
- appropriate files automatically.
-
- Once an operation has been requested, the data variable is used as a buffer,
- where the actual transfer of records takes place. If the operation is a read,
- the value of the record can be found in the data variable after the successful
- completion of the requested operation (confirmed by the return code passed
- through the control variable). If the desired operation is a write, the value
- of the record must be assigned to the data variable before the corresponding
- subcommand is assigned to the control variable.
-
-
- ΓòÉΓòÉΓòÉ 14.9.3. Establishing the AP 210 Translate Table ΓòÉΓòÉΓòÉ
-
- AP 210 can be supplied with a translate table for use with files opened with
- code T. Each file opened can have its own translate table. If no table has been
- defined, the data is not translated. The table can be defined or redefined, at
- any time, by:
-
- C210╜2 256цREAD_TABLE,WRITE_TABLE
-
- where READ_TABLE is applied to the data read as:
-
- D210╜READ_TABLE[РAF DATA_READ]
-
- and WRITE_TABLE is applied to the data written as:
-
- DATA_WRITTEN╜WRITE_TABLE[РAF D210]
-
- Both READ_TABLE and WRITE_TABLE must be 256-element character vectors.
-
-
- ΓòÉΓòÉΓòÉ 14.9.4. AP 210 Return Codes ΓòÉΓòÉΓòÉ
-
- The following table lists the AP 210 return codes:
-
- Code Meaning
- 0 - Success
- 1 - Invalid command
- 2 - File not found
- ¤18 - Insufficient User Authority
- ¤26 - No space available
- ¤29 - Invalid APL2 object
- ¤31 - Control variable domain error
- ¤32 - Control variable rank error
- ¤33 - Control variable length error
- ¤36 - Invalid file translation code
- ¤37 - Data variable value error
- ¤38 - Data variable domain error
- ¤39 - Data variable interlocked
- ¤40 - Data variable not shared
- ¤41 - File is not open, issue a primary command
- ¤44 - LF not found in scan length
- ¤45 - End of file
- ¤46 - Incomplete record, padded with nulls
- ¤47 - Invalid subcommand
- ¤48 - Record only partially written (file system full)
- ¤49 - Data variable size exceeds record size for fixed or variable replace
-
-
- ΓòÉΓòÉΓòÉ 14.9.5. Example of Use ΓòÉΓòÉΓòÉ
-
- Starting with a clear workspace, offer variables C1 and D1 to share with AP 210
- using the SVOPAIR function from the 1 UTILITY workspace:
-
- )CLEAR
- CLEAR WS
- )COPY 1 UTILITY SVOPAIR
- SAVED ...
- 210 SVOPAIR 'C1' 'D1'
- 2 1
-
- Attempt to create a file called FILE. Records contain APL2 objects with header
- (default code):
-
- C1Γò£'IW,FILE'
- C1
- 0
-
- We are now in subcommand mode. The first record is a vector of elements from 1
- to 10, so assign this to D1:
-
- D1╜ь10
-
- Now issue the subcommand to write the first record in the file. The default
- record number is 0.
-
- C1Γò£5
- C1
- 0
-
- Second record is a matrix of 2 rows, 3 columns, of elements from 1 to 6:
-
- D1╜2 3ць6
-
- Issue subcommand to write this record sequentially to the file:
-
- C1Γò£5
- C1
- 0
-
- An empty vector closes the file and puts the control variable into command
- mode:
-
- C1Γò£''
-
- Open the same file for read-only operation:
-
- C1Γò£'IR,FILE'
- C1
- 0
-
- Read the second record first:
-
- C1Γò£4 1
- C1
- 0
- D1
- 1 2 3
- 4 5 6
-
- Read the first record:
-
- C1Γò£4 0
- C1
- 0
- D1
- 1 2 3 4 5 6 7 8 9 10
-
- Close the file and go into command state:
-
- C1╜ь0
-
- Rename the file to NEWFILE:
-
- C1Γò£'RN,FILE,NEWFILE'
- C1
- 0
-
- Delete the file:
-
- C1Γò£'DL,NEWFILE'
- C1
- 0
-
- Finally, retract the shared variables:
-
- РSVR 2 2ц'C1D1'
- 2 2
-
-
- ΓòÉΓòÉΓòÉ 14.10. AP 211-The APL2 Object Library Auxiliary Processor ΓòÉΓòÉΓòÉ
-
- AP 211 provides a facility for storing APL2 arrays in an object library.
-
- AP 211 uses a single shared variable of any name to control access to a
- library.
-
- The following description of the commands accepted by AP 211 assumes that a
- variable called SHR211 has been shared with AP 211. For example:
-
- 211 SVOFFER 'SHR211'
- 2
-
- offers the shared variable to AP 211 and sets access control. See Using the
- Share-Offer Utilities for a description of the SVOFFER function.
-
- o Commands
- o AP 211 Return Codes
- o Example of Use
-
-
- ΓòÉΓòÉΓòÉ 14.10.1. Commands ΓòÉΓòÉΓòÉ
-
- AP 211 accepts the following commands:
-
- o CREATE
- o DROP
- o USE
- o RELEASE
- o SET
- o GET
- o RENAME
- o ERASE
- o LIST
-
-
- ΓòÉΓòÉΓòÉ 14.10.1.1. CREATE ΓòÉΓòÉΓòÉ
-
- This command creates an AP 211 object library and must be issued before APL2
- arrays can be assigned to a given library file.
-
- SHR211Γò£'CREATE' filename [rec_size]
-
- Where rec_size specifies the record size used to store APL2 objects in the
- file. APL2 objects stored in the library use one or more records depending on
- size. Objects smaller than the record size still use a full record and any
- excess space is wasted. Therefore, you should carefully select an optimum size
- for your APL2 objects to reduce the amount of wasted space in the file.
-
- The number of blocks that are used is given by: йobject_sizeЎrec_size
-
- where object_size can be obtained by: ╞4 РAT object_name
-
- AP 211 uses a default record size of 1024 if none is specified. The record size
- must be in the range 128 to 32704 bytes. If the record size is not an exact
- multiple of 64 bytes, it is rounded up to the next multiple of 64 bytes.
-
- An error is given if the file already exists. It is the responsibility of the
- application developer to check that the name is not already in use and to erase
- the file if necessary.
-
-
- ΓòÉΓòÉΓòÉ 14.10.1.2. DROP ΓòÉΓòÉΓòÉ
-
- This command deletes an entire APL2 object library from disk.
-
- SHR211Γò£'DROP' filename
-
-
- ΓòÉΓòÉΓòÉ 14.10.1.3. USE ΓòÉΓòÉΓòÉ
-
- This command opens an already-existing AP 211 library file. It must be issued
- before using the SET, GET, ERASE, and LIST commands.
-
- Γò£-----Access Control------Γòò
- SHR211Γò£'USE' filename [user_id] Γöé ['READ'Γöé'UPDATE'Γöé'PRIVATE']
-
- user_id is a scalar integer, which can be used to implement an audit trail of
- updates, particularly where the file is shared between many users. The default
- value is ╞РAI, as specified in APLID environment variable (set by the -id
- invocation parameter).
-
- Access Control Parameters:
-
- o UPDATE opens the file for shared READ/WRITE access.
- o READ opens the file for shared READ/ONLY access.
- o PRIVATE opens the file for nonshared READ/WRITE access.
-
- READ or UPDATE should be specified when accessing AP 211 files that require
- simultaneous multiuser READ/WRITE access. When running in this mode, AP 211
- enables an internal locking procedure, which ensures file integrity, but
- impacts performance for file updates. If you do not require shared access,
- opening the file using PRIVATE provides a significant performance improvement
- for file writes.
-
- PRIVATE opens the file for exclusive READ/WRITE access. A file that is already
- open cannot be opened as PRIVATE, and once opened PRIVATE, cannot be opened by
- anyone else until a RELEASE is issued or the shared variable is retracted.
-
- If the USE command is issued without any of the optional Access Control
- parameters, the file is opened with the maximum access authority permitted, for
- exclusive use if possible or shared access if the file is already opened.
-
- USE returns a two-element vector containing a return code and the record size.
-
-
- ΓòÉΓòÉΓòÉ 14.10.1.4. RELEASE ΓòÉΓòÉΓòÉ
-
- Releases the object library that was allocated to a shared variable. This
- command is issued implicitly when retracting or erasing the shared variable, or
- if a subsequent USE or CREATE are specified to the same shared variable.
-
- SHR211Γò£'RELEASE'
-
-
- ΓòÉΓòÉΓòÉ 14.10.1.5. SET ΓòÉΓòÉΓòÉ
-
- Allows you to associate a name in the object library with an APL2 array. The
- command requires a three-element vector:
-
- SHR211Γò£'SET' name APL2_object
-
- The maximum permitted length of name is 31 characters.
-
- If the name is already in use, the old definition is deleted, and the new
- definition added to the object library. The space taken by the old definition
- is freed for later use.
-
-
- ΓòÉΓòÉΓòÉ 14.10.1.6. GET ΓòÉΓòÉΓòÉ
-
- This returns the array (if any) associated with a given name.
-
- SHR211Γò£'GET' name
- (return_code APL2_object)ΓûáSHR211
-
- The response to this command is a two-element vector: the first item is the
- return code, the second is the APL2_object array, if found.
-
-
- ΓòÉΓòÉΓòÉ 14.10.1.7. RENAME ΓòÉΓòÉΓòÉ
-
- Renames an object stored in an AP 211 file.
-
- SHR211Γò£'RENAME' oldname newname
-
-
- ΓòÉΓòÉΓòÉ 14.10.1.8. ERASE ΓòÉΓòÉΓòÉ
-
- This command allows you to remove an APL2 array from an object library, and
- makes its storage available for other updates. Note, however, that the overall
- size of the file remains unchanged.
-
- SHR211Γò£'ERASE' name
-
-
- ΓòÉΓòÉΓòÉ 14.10.1.9. LIST ΓòÉΓòÉΓòÉ
-
- This command allows you to list the contents of the current library:
-
- SHR211Γò£'LIST' 'NAMES'
- цР╜SHR211
- Object1
- Object2
- Object3
- 3 31
- SHR211Γò£'LIST' 'ATTS'
- цР╜SHR211
- 1 1001 1991 1 2 12 30 14 12
- 2 1001 1991 1 2 12 30 14 12
- 1 1001 1991 1 2 12 30 14 12
- 3 9
-
- The information returned is:
-
- o The number of records used for this object
- o User ID number (as specified on USE command) of user who last updated this
- object
- o The date and time the object was updated (in РTS format)
-
- Note: The time is listed in Greenwich Mean Time.
-
- Each row in this list corresponds to the equivalent row in the list of object
- names.
-
-
- ΓòÉΓòÉΓòÉ 14.10.2. AP 211 Return Codes ΓòÉΓòÉΓòÉ
-
- The following table lists the AP 211 return codes.
-
- Code Meaning
- 0 - Success
- 2 - File not found
- ¤1 - Old format file (access restricted to read only)
- ¤2 - Rank error
- ¤3 - Length error
- ¤4 - Type error
- ¤7 - Invalid command
- ¤8 - Invalid block size
- ¤9 - Invalid library file
- ¤10 - No library file accessed
- ¤11 - Name has no value
- ¤12 - Invalid name specified
- ¤13 - Error encountered during set operation
- ¤14 - Invalid file name
- ¤15 - Invalid access mode
- ¤16 - Invalid user ID
- ¤17 - Filename already in use
- ¤18 - Insufficient user authority
- ¤19 - Name already exists
- ¤20 - Unsupported data format
- ¤21 - Temporary interlock
- ¤22 - Unexpected SVP return code
- ¤24 - Media full
- ¤26 - No space available
-
-
- ΓòÉΓòÉΓòÉ 14.10.3. Example of Use ΓòÉΓòÉΓòÉ
-
- First share a variable with AP 211:
-
- 211 РSVO 'SHR211'
- 1
- РSVO 'SHR211'
- 2
-
- Then create a new file called FILE:
-
- SHR211Γò£'CREATE' 'FILE'
- SHR211
- 0
-
- An empty file has now been created. Before we can go any further, the file must
- be opened for access:
-
- SHR211Γò£'USE' 'FILE'
-
- SHR211
-
- 0 1024
-
- The 1024 returned by this call shows that the default record size was used when
- the file was created. Now we can place data into the file:
-
- SHR211╜'SET' 'ABC' (ь10)
-
- SHR211
-
- 0
-
- SHR211╜'SET' 'DEF' (3 5ц'AP211IS EASY!')
-
- SHR211
-
- 0
-
- This has placed two objects into the file. We can determine the names of
- objects stored on the file with:
-
- SHR211Γò£'LIST' 'NAMES'
-
- SHR211
-
- ABC
-
- DEF
-
- At any time, we can retrieve any objects stored in the file:
-
- SHR211Γò£'GET' 'DEF'
-
- SHR211
-
- 0 AP211
-
- IS
-
- EASY!
-
- Note that a length two result is given by the SET call. Normally we want to
- separate the return code (the first item) and the data array (the second item)
- into two variables. Vector assignment provides a simple way to do this:
-
- SHR211Γò£'GET' 'DEF'
-
- (RC ARR)Γò£SHR211
-
- RC
-
- 0
-
- ARR
-
- AP211
-
- IS
-
- EASY!
-
- When we have finished with the file, we can release it:
-
- SHR211Γò£'RELEASE'
-
- SHR211
-
- 0
-
- And finally, if we have no further need for the file, we can delete it:
-
- SHR211Γò£'DROP' 'FILE'
-
- SHR211
-
- 0
-
-
- ΓòÉΓòÉΓòÉ 15. Writing Your Own External Routines ΓòÉΓòÉΓòÉ
-
- This chapter discusses how to write your own external routines to be called
- through processor 11. For more information about processor 11, see Processor
- 11-Accessing External Routines.
-
- o Creating a Callable Subroutine
- o Using Prebuilt DLLs (Runtime Libraries)
- o Debugging External Functions
-
-
- ΓòÉΓòÉΓòÉ 15.1. Creating a Callable Subroutine ΓòÉΓòÉΓòÉ
-
- Write your subroutine as a 32-bit object using system linkage. For example:
-
- /* C-Set/2 example */
- #include <stdlib.h>
- #include <stdio.h>
- #include <errno.h>
- #include <math.h>
- int _System MyFunction(char *string)
- {
- return strlen(string);
- }
-
- Create a names file entry in P011.NAM as described in NAMES File Syntax for
- Processor 11:
-
- :nick.MY :link.SYSTEM :lib.my :proc.MyFunction
- :valence.1 1 0
- :rarg. (G4 0)(S1 1 *)
- :rslt. (I4 0)
- :desc.Returns the length of a character vector to the first null.
-
- Create a MY.DEF file as described in the OS/2 Toolkit documentation:
-
- LIBRARY my INITINSTANCE TERMINSTANCE
- PROTMODE
- DATA MULTIPLE NONSHARED
- EXPORTS
- _DLL_InitTerm
- MyFunction
-
- Compile the program. For example, using the IBM C/C++ product:
-
- icc /Ti /Gd- /Ge- /Gt- /O- /B"/noe /noi" my.c my.def
-
- Put the files MY.DLL and P011.NAM in the directry you start apl from.
-
- Execute the РNA:
-
- '<C:\APL2OS2\P011.NAM>' 11 РNA 'MY'
-
- Test the function:
-
- MY т 'sssss',(РAF 0),'ttttt'
- 5
-
-
- ΓòÉΓòÉΓòÉ 15.2. Using Prebuilt DLLs (Runtime Libraries) ΓòÉΓòÉΓòÉ
-
- Many 32-bit DLLs can be called directly by processor 11. These DLLs can be part
- of a subroutine library or program product. To use them directly, you must
- ensure that they can be called with the OS/2-defined 32-bit _System linkage. If
- the DLL was meant to be called with Optlink, Pascal, or some other linkage
- convention, then an intervening stub program is needed. Refer to the
- documentation received with the library for parameter lists and linkage
- conventions.
-
- For _System linkage DLLs, you need only create a NAMES file for the entries you
- wish to access. Here is an example of a description for DosSearchPath in the
- OS/2 C-Set++ Tools 2.0 _DOSCALL.DLL.
-
- :nick.DOSPATH :link.SYSTEM :lib._doscall :proc.DosSearchPath
- :valence.1 1 0
- :rslt.(1 I4 0)
- :rarg.(5 G0 1 5)(1 I4 *)
- :rarg. (G4 0)(S1 1 *)
- :rarg. (G4 0)(S1 1 *)
- :rarg. (G4 0)(>S1 1 *)
- :rarg. (1 I4 *)
- :desc.APIRET DosSearchPath(ULONG uControl
- :desc. ,PSZ pszPathRef
- :desc. ,PSZ pszFileName
- :desc. ,PBYTE pbResultBuffer
- :desc. ,ULONG ulResultBufferLen)
-
- This example uses a 5-element depth 3 array to pass the data. Each character
- vector is an enclosed element. The fourth item has a pass by name indicator and
- its value is a character vector that contains the name of an APL object having
- the desired size and type.
-
- A╜3 ф search environment
- D╜т■'PATH' 'CONFIG.SYS' 'DD' ф and current directory
- DD╜ (255ц'+') ф named variable
- DOSPATH A,D,1+цDD ф here is the call
- 0
-
- The result value as indicated by the :RSLT. keyword is the integer scalar
- return code. The value of DD has been updated in place. DD must be large enough
- to hold the result.
-
- DD ф here is the updated variable
- C:\OS2\INSTALL\CONFIG.SYS
-
-
- ΓòÉΓòÉΓòÉ 15.3. Debugging External Functions ΓòÉΓòÉΓòÉ
-
- External functions can be debugged by any debugger that allows you to halt on
- DLL LOAD to set break points in the DLL. IPMD, which is provided as part of
- C-Set++ Tool, allows this.
-
- To debug your functions via IPMD, (provided with C-Set/2 ), include debug
- information in your objects and DLL, then run APL2 under IPMD by typing 'IPMD
- aosapl2 -ws 784k'. Before starting APL2:
-
- 1. Click on Breakpoints.
- 2. Click on Load Occurrence.
- 3. Click on Enter.
- 4. Click on the name of your DLL.
- 5. Click on OK.
-
- After setting the "break" on DLL LOAD, continue running APL2. IPMD gains
- control and stops APL when you РNA to your routine. (Processor 11 loads your
- DLL after it has found the NAMES file entry for the routine and located the
- DLL. Processor 11 loads a DLL at first reference and unloads it at the last
- reference. To cause a reload of the DLL, issue a )CLEAR and then reassociate
- your routine.)
-
- The debugger stops when it first loads your DLL. At the Debug Main Task window,
- you see an entry for your DLL. Click on the + button and then on the desired
- function. When it is open, you can set any breakpoints you wish. After you have
- set all the needed breakpoints you can then restart APL2. It processes until
- one of your breakpoints is hit.
-
-
- ΓòÉΓòÉΓòÉ 16. Writing Your Own Auxiliary Processors ΓòÉΓòÉΓòÉ
-
- This chapter discusses how to write your own auxiliary processors. Auxiliary
- processors can be written either in APL or in C.
-
- o The basic interface for communicating between an APL auxiliary processor and
- the shared variable processor is the set of shared variable system functions
- and variables (РSVC, РSVE, РSVO, РSVQ, РSVR, and РSVS) defined in APL2
- Programming: Language Reference.
-
- o The basic interface for communicating between a C auxiliary processor and the
- shared variable processor is a set of service calls and structure definitions
- defined in SVP Programming Interface.
-
- o A higher level APSERVER interface to the shared variable processor is also
- available for auxiliary processors written in either APL or C. This is
- defined in Writing Auxiliary Processors Using APSERVER.
-
- o If your AP is written in APL and uses the basic interface, you should read
- the material on starting APL auxiliary processors that is in APSERVER-APL2
- Programming Interface.
-
- o Writing Auxiliary Processors Using APSERVER
- o SVP Programming Interface
- o Common Data Representation
-
-
- ΓòÉΓòÉΓòÉ 16.1. Writing Auxiliary Processors Using APSERVER ΓòÉΓòÉΓòÉ
-
- The Shared Variable Processor (SVP) is a general purpose communication facility
- that can support various protocols, including peer-to-peer, client-server, full
- or half duplex, or uni-directional data flow for device drivers or
- instrumentation. However, the most common type of auxiliary processor (AP) is
- the server, which accepts requests from one or more client processors, performs
- some action, and returns a response.
-
- The purpose of the APSERVER API (application program interface) is to simplify
- the implementation of server APs by handling all of the SVP communication and
- process control, leaving you to concentrate on just the AP-specific service
- routine. Both an APL2 function call interface and a C function call interface
- are provided so client-server APs can be easily written in either APL or in
- compiled languages such as C or Fortran.
-
- Although the APSERVER can be used to implement dual-variable APs (typically a
- control and data variable), IBM recommends that a single variable interface be
- used for simplicity. By using APL2's general array support, it is easy to pass
- control information and its accompanying data through a single variable.
- APSERVER provides access to client processor information and shared variable
- name to support share restrictions when appropriate.
-
- A server AP can run as either a dependent or independent processor, local or
- remote, and can be automatically started on the first incoming share offer.
- When using the C API, each incoming share spawns a separate execution thread to
- achieve the maximum benefit of multitasking or multiprocessing.
-
- APSERVER allows common APs to be written to run on different operating systems
- (for example, OS/2, AIX, or Sun Solaris) by handling platform-dependent
- functions, such as process threading and event handling.
-
- o APSERVER-APL2 Programming Interface
- o APSERVER-C Programming Interface
-
-
- ΓòÉΓòÉΓòÉ 16.1.1. APSERVER-APL2 Programming Interface ΓòÉΓòÉΓòÉ
-
- To use the APSERVER function to implement an AP written in APL2, first copy the
- function from the distributed library:
-
- )COPY 1 UTILITY APSERVER
- The APSERVER function uses a registered callback interface, where you choose to
- supply a minimum of zero (for the default "echo" AP) to a maximum of four
- callback function names. The syntax of the APSERVER call is:
-
- APSERVER 'Init_fn' 'Wait_fn' 'Process_fn' 'Exit_fn'
-
- If a callback function is not provided, the corresponding item in the 4 element
- general array argument should contain an empty character vector.
-
- The first name in the argument list is the name of the initialization function
- that gets called by APSERVER when a new share offer arrives. The syntax of the
- 'Init_fn' is:
-
- RCΓò£Init_fn PID SVNAME
-
- APSERVER passes to the initialization function the SVP processor number of the
- client and the name of the shared variable being offered. If the AP chooses to
- accept the share, it returns an explicit result of 1. To reject the share
- offer, a 0 is returned.
-
- The initialization function can be used to open files, establish shares with
- other APs, or to initialize global variables. Since the AP runs as a single
- task, care should be taken to avoid blocking on a shared variable access within
- the callback functions if the AP is designed to support multiple shares or
- multiple clients.
-
- The second name in the APSERVER argument list is the name of the wait callback
- function. If no wait routine is supplied the default action of the APSERVER is
- to enter a РSVE wait for any shared variable event, then scan for new offers,
- new client requests, or shared variable retractions. The Wait_fn function, if
- provided, must be a niladic function with no explicit result. You may wish to
- provide your own wait function to issue РSVE so that you can check the state of
- other shared variables used for your own purposes, or so that you can provide a
- time-out on the РSVE wait (for example, to do some administrative work such as
- journaling). When you supply wait routine exits, the APSERVER performs the
- usual checking for client events.
-
- The third item in the APSERVER argument list is the name of the process
- function-the meat of the AP. The syntax is:
-
- RESULTΓò£(PID SVNAME) Process_fn REQUEST
-
- The right argument is the APL2 array representing the client request. The
- APSERVER provides the client processor ID and shared variable name in the left
- argument. Provide the necessary code in the process routine to service the
- client request, and then return, as the explicit result of the function, the
- APL2 array that is to be sent back to the client in response to the request. If
- the process callback is elided, the default action of the APSERVER is to echo
- the request back to the client.
-
- The fourth item in the APSERVER argument list is the name of the exit callback
- function. The syntax is:
-
- Exit_fn PID SVNAME
-
- The APSERVER again passes the client processor ID and shared variable name in
- the right argument. The exit function is called when the client retracts the
- shared variable. The exit function is often used as the inverse to the
- initialization function, to close files, retract other associated shares, and
- expunge global variables. When the APSERVER gets control back from the exit
- routine, it completes the retraction from the server side.
-
- Note: A current restriction of APs written in APL2 using the APSERVER
- client-server protocol is that the client must reference all return values sent
- by the server, prior to issuing another request. Failure to do so could result
- in a request being lost due to a race condition.
-
- o An AP Example Using APSERVER
-
-
- ΓòÉΓòÉΓòÉ 16.1.1.1. An AP Example Using APSERVER ΓòÉΓòÉΓòÉ
-
- )CLEAR
- CLEAR WS
- )COPY 1 UTILITY APSERVER
- SAVED 1993-08-07 19.14.31 (GMT-4)
- Γòûap555
- [1] ф Sample AP using 'init' and 'exit' callbacks. This AP uses AP207
- [2] ф to create a window where client requests are randomly displayed.
- [3] ф Returns 'OK' if write to window was successful, or 'OOPS' if not.
- [4] APSERVER 'INIT555' '' 'PROC555' 'EXIT555'
- [5] Γòû
- ΓòûRΓò£INIT555 SVinfo;N;PID;SVNAME
- [1] (PID SVNAME)Γò£SVinfo
- [2] Γòò(~RΓò£2=Γò₧207 SVOFFER NΓò£SVNAME,'207')/0
- [3] пN,'╜''OPEN'' (0 ''',(оюID PID),' ',SVNAME,''' ',(о200+?4ц300),')'
- [4] ╨┐N,'Γò£''COLOR'' ''CYAN'''
- [5] ╕(R╜0=╞пN)/0
- [6] N╜РEX N
- [7] Γòû
- ΓòûRΓò£SVinfo PROC555 String;N;PID;SVNAME
- [1] (PID SVNAME)Γò£SVinfo
- [2] NΓò£SVNAME,'207'
- [3] пN,'╜''MOVE'' (?2ц150)'
- [4] ╨┐N,'Γò£''WRITE'' ''',String,''''
- [5] R╜ю╞(0=╞пN)╟'OOPS' 'OK'
- [6] Γòû
- ΓòûEXIT555 SVinfo;N;PID;SVNAME
- [1] (PID SVNAME)Γò£SVinfo
- [2] NΓò£SVNAME,'207'
- [3] ╨┐N,'Γò£''CLOSE'' '''''
- [4] N╜РEX N
- [5] Γòû
- )COPY 1 UTILITY SVOFFER
- SAVED 1993-08-07 19.14.31 (GMT-4)
- )FNS
- APSERVER EXIT555 INIT555 PROC555 SVOFFER ap555
- )SAVE ap555
- SAVED 1993-08-24 21.36.05 (GMT-4)
- )LOAD 2 FILE
- SAVED 1993-08-06 18.55.12 (GMT-4)
- Licensed Materials - Property of IBM
- 5621-430, 5765-012 (C) Copyright IBM Corp. 1983, 1993.
- (шС С С С)╢FV 'AP555.CMD'
- /* REXX command file to start AP 555 */
- Parse Arg parms
- lines = "')LOAD AP555' 'AP555' ')OFF'"
- 'aosapl2 /sm piped /input "'lines'"' parms '>ap555.log'
- 0
- )CLEAR
- CLEAR WS
- 555 РSVO 'X'
- 1
- РSVO 'X'
- 2
- РSVC 'X'
- 0 0 0 1
- 1 0 1 0 РSVC 'X'
- 1 0 1 1
- XΓò£'SAY HI'
- X
- OK
- РSVR 'X'
- 2
-
-
- ΓòÉΓòÉΓòÉ 16.1.2. APSERVER-C Programming Interface ΓòÉΓòÉΓòÉ
-
- The APSERVER uses a registered callback interface, where you choose to supply a
- minimum of zero (for default "echo" AP) to a maximum of four callback function
- names. The definition of the APSERVER function call is:
-
- int apserver(int argc, char ** argv, int(*initfn)(void *),
- int(*waitfn)(void *),
- int(*procfn)(void *),
- int(*exitfn)(void *));
-
- The first two arguments passed to APSERVER are the argc and argv parameters
- that were passed to the AP main routine. The APSERVER uses this information to
- determine the processor identification for signing on to the SVP. It scans for
- the keyword -id followed by one to three numeric values, with the form
- id[,pid[,ppid]], representing the ID and, optionally, the parent and
- grandparent IDs for dependent processors. If no -id parameter is found,
- APSERVER uses the numeric portion of the executable module's name (of the form
- "apNNN") to determine the default processor number.
-
- The next four arguments are the names of your supplied callback functions.
- These callback routines are described as follows:
-
- initfn AP initialization (prior to accepting client's share)
- waitfn Multiple event wait and non-SVP event handling
- procfn Process a client request (the meat of the AP)
- exitfn AP clean-up (just prior to retraction of the share)
-
- Each of these callback routines receives a single argument that is a pointer to
- an SRVTOKEN structure. This token is used by subsequent APSERVER service
- routines that are described later. All callback functions return an integer
- return code, with zero indicating success.
-
- In each case, if no callback routine is supplied, a NULL pointer must be
- provided instead. If a NULL value is specified for all four callback functions,
- the APSERVER functions as an echo AP, reflecting the client processor's request
- value back to the client as the server's response value.
-
- For example, the following C function represents the simplest form of a fully
- functional AP (default echo AP), supporting multiple clients, multiple shares,
- and multitasking on a per-share basis:
-
- /* ap555 - echo AP (source module: ap555.c, executable module: ap555) */
- #include "apserver.h"
- int main(int argc, char **argv) {
- return(apserver(argc, argv, NULL, NULL, NULL, NULL)); }
-
- If the executable ap555 module is placed in the search path for an APL2
- session, the first share offer to processor 555 causes the AP to be
- auto-started as a dependent AP of the APL2 session. Alternatively, the AP could
- be started explicitly and may run as an independent processor. Optionally, by
- use of the TCP/IP processor profile, the server AP can also be accessed by
- remote client processors.
-
- o Defining the Process Callback Function
- o Defining the Init Callback Function
- o Defining the Exit Callback Function
- o Defining the Wait Callback Function
- o Execution Environment and Exception Handling
- o An AP Example Using APSERVER
-
-
- ΓòÉΓòÉΓòÉ 16.1.2.1. Defining the Process Callback Function ΓòÉΓòÉΓòÉ
-
- To be of more practical use, an AP should serve as more than just a reflector
- of client requests. That is where the "process" callback function comes into
- play. The process routine name is passed as the fifth argument to APSERVER. On
- entry to the process routine, the client's request value is stored in a shared
- variable buffer that is accessed by two APSERVER macros: SRVBUF and SRVBUFL.
- Note that when passing APL2 arrays, SRVBUFL is typically not required because
- the size of the array is defined in the self-describing array header (see
- Common Data Representation).
-
- All APSERVER macros take the SRVTOKEN as an argument. A brief summary of the
- service macros follows:
-
- (void *)SRVBUF(srvtoken) - pointer to shared variable buffer
- (unsigned long)SRVBUFL(srvtoken) - length of shared variable buffer
- (struct xid *)SRVPXID(srvtoken) - pointer to client's SVP ID
- (char *)SRVNAME(srvtoken) - pointer to shared variable name
- (unsigned long)SRVNTOK(srvtoken) - SVP event notification token
- (void *)SRVUTOK(srvtoken) - user token (for your use)
- (struct srb *)SRVSRBP(srvtoken) - pointer to SVP share request block
-
- On return from the process routine, the AP stores the result of the client's
- request in the shared variable buffer. If the size of the buffer on entry is
- not large enough for the result, the AP can request reallocation of storage via
- the srv_alloc service routine. The syntax of the srv_alloc call is:
-
- void * srv_alloc(void * srvtoken, unsigned long size);
-
- The first argument is the SRVTOKEN pointer and the second is the number bytes
- of storage required. The SRVTOKEN pointer is returned. Note that srv_alloc does
- not preserve the previous contents of the buffer, so if the client request data
- is to be used later, a copy must be made. The SRVBUF macro is used to get
- addressability to the newly-allocated buffer. A NULL pointer is returned by
- SRVBUF if the allocation failed.
-
- To calculate the storage requirement for an APL2 array, the service routine
- aplobjsize can be called. The definition of aplobjsize is:
-
- unsigned long aplobjsize(unsigned char type, unsigned char rank,
- unsigned long nelm);
-
- See Common Data Representation for a description of the valid argument values.
- The function returns the number of bytes of storage required.
-
- Since srv_alloc only reallocates shared memory when necessary, you do not need
- to keep track of the buffer size to achieve optimum performance, but can simply
- call srv_alloc to request space for the result at any time.
-
- If the AP process routine enters a potentially long wait (for example, due to a
- blocking read), it should release the lock that is implicitly held on the
- shared memory buffer. This is done by calling the srv_free service routine,
- which has the following definition:
-
- srv_free(void * srvtoken);
-
- After the srv_free service call, the buffer is no longer addressable and SRVBUF
- returns a NULL pointer.
-
- For best performance in nonblocking AP process routines that return a response
- to the client, srv_free should not be called. The AP holds the lock on the
- shared variable between the reference of the request and the setting of the
- result value.
-
- You can also write an AP server that accepts client requests, performs some
- action, but does not send a response back to the client. In this case, srv_free
- is called prior to return from the process callback routine, with no
- intervening srv_alloc calls.
-
-
- ΓòÉΓòÉΓòÉ 16.1.2.2. Defining the Init Callback Function ΓòÉΓòÉΓòÉ
-
- While practical APs can be written using only the process callback routine,
- three other callbacks are provided for additional flexibility: init, wait, and
- exit. The init routine is called by APSERVER prior to accepting a new share
- from a client processor.
-
- Using the SRVNAME and SRVPXID macros, the AP can determine the name of the
- shared variable and the identity of the client. By setting the return code
- SRV_REJECT_SHARE, the AP init routine can instruct the APSERVER to ignore the
- incoming share. A return code of 0 results in the accepting of the incoming
- share to complete the coupling with the client processor.
-
- Typical things done in an init routine are file opens, environment
- initialization, and allocation of global data structures. The APSERVER
- maintains a user token for you to use as an anchor to a malloc'd data area. The
- SRVUTOK macro can be used to store and retrieve the user token.
-
-
- ΓòÉΓòÉΓòÉ 16.1.2.3. Defining the Exit Callback Function ΓòÉΓòÉΓòÉ
-
- The exit callback routine usually provides the inverse function of the init
- routine. It is called by APSERVER just prior to retraction of the shared
- variable and termination of the execution thread. Using SRVUTOK to get the user
- token, which is typically the pointer to malloc'd storage, the exit routine can
- be used to close open files and windows, and to free any dynamic storage that
- was allocated in the init routine.
-
-
- ΓòÉΓòÉΓòÉ 16.1.2.4. Defining the Wait Callback Function ΓòÉΓòÉΓòÉ
-
- The wait callback function is used only for special APs that need to wait on
- multiple events. If no wait routine is provided, the default action of the
- APSERVER is to wait for a client specification or retraction of the shared
- variable.
-
- APSERVER obtains a separate event notification token for each shared variable
- as it spawns a new execution thread. The SRVNTOK macro can be used to retrieve
- the SVP event notification token. For APs that need to monitor additional file
- or window handles, the SVP notification token can be included in a multi-wait
- call (for example, select, poll, or muxwait). After handling non-SVP events,
- the wait routine should return to allow processing of the next client request.
-
-
- ΓòÉΓòÉΓòÉ 16.1.2.5. Execution Environment and Exception Handling ΓòÉΓòÉΓòÉ
-
- One of the goals of the APSERVER is to assume responsibility for most of the
- exception handling required for a robust auxiliary processor, including
- interrupt or termination signal trapping, redispatching of SVP requests in the
- case of temporary shared variable interlocks, and the orderly signoff and
- shutdown of the processor, including cases of severe error conditions.
-
- In the case of an unrecoverable error on a shared variable SVP call, the
- APSERVER issues an error message with return code information, then calls the
- exit registered callback function prior to retracting the shared variable and
- terminating the execution thread. The execution states of threads associated
- with other shared variables are generally unaffected by the one share failure.
-
- When the APSERVER is started, it immediately defines a signal handler to
- capture SIGTERM (software termination request) and SIGINT (interrupt signal).
- The signal handler is the same function that handles normal SVP-broadcast
- SHUTDOWN events. It issues a standard SVP processor SIGNOFF request before
- termination of the auxiliary processor.
-
- When a child process is spawned for each shared variable, the SIGTERM and
- SIGINT signals are reset to the default handlers. The auxiliary processor's
- init registered callback function can be used to establish the desired
- exception handling environment for the main "process" routine.
-
- In the unlikely event of an unrecoverable SVP error while monitoring the
- processor event queue, an error message is issued and an attempt is made to
- complete a normal processor SIGNOFF. During a normal processor SIGNOFF, the
- parent (dispatcher) process waits up to a maximum of 15 seconds for the child
- threads to complete a normal retraction of the associated shared variables and
- terminate.
-
-
- ΓòÉΓòÉΓòÉ 16.1.2.6. An AP Example Using APSERVER ΓòÉΓòÉΓòÉ
-
- /*-P-ap999--------------------------------------------------------------------
- *
- * Module Name: ap999.c
- *
- * Descriptive Name: Auxiliary Processor 999
- *
- * Function: Sample Auxiliary Processor implementing client-server
- * protocol. For hard working programmers with deadlines,
- * this sample server will "catch some ZZZZZZ's" for a
- * client who has no time to sleep for himself.
- *
- * Entry-point: main
- *
- *-Z------------------------------------------------------------------------*/
- #include <stdlib.h>
- #include <string.h>
- #include "aplobj.h"
- #include "apserver.h"
- #define INVALID_REQ -1 /* catch-all rc for unfriendly AP */
- #define SYSTEM_LIMIT -2 /* requested space is unavailable */
- int sleep_init(void *); /* AP Server "init" callback fn */
- int sleep_server(void *); /* AP Server "process" callback fn */
- int sleep_exit(void *); /* AP Server "exit" callback fn */
- static int error_code(void *, int); /* error handler */
-
- /*-F-main---------------------------------------------------------------------
- *
- * Purpose: Auxiliary Processor 999 - main routine runs the general
- * AP Server with standard callback to one or more of the 4
- * AP Server callback routines identified in the parameter list.
- * The 4 callback routines are named in parms 3-6 of apserver, and
- * provide the following function:
- * 1. AP initialization, prior to accepting the client share
- * 2. multiple event wait and non-SVP event handling
- * 3. process a client request (passed in shared variable)
- * 4. AP exit cleanup on retraction of the share
- * (Note: if a callback function is not provided, set parm to NULL)
- *
- * Arguments: int argc Number of elements in argv
- * char ** argv Argument pointer array
- * char ** envp Environment pointer array
- *
- * Results: int Exit Return Code
- *
- *--------------------------------------------------------------------------*/
- int main(int argc, char **argv, char **envp) {
- return(apserver(argc, argv, sleep_init, NULL, sleep_server, sleep_exit));
- /* init wait process exit */
- }
-
- /*-F-sleep_init---------------------------------------------------------------
- *
- * Purpose: Server initialization callback - called by the AP
- * Server prior to accepting the share to fully couple
- * with the client. The typical things done by an AP
- * here are to open files, allocate global storage,
- * initialize a global data structure and store its
- * address in the user token field of the srvtoken, etc...
- * Via SRVPXID and SRVNAME, the AP can examine the client's
- * fully-qualified SVP identification and the name of
- * the share. If the AP decides not to accept the share,
- * it returns from this init routine with return code
- * SRV_REJECT_SHARE.
- *
- * Arguments: void * srvtoken pointer to AP Server token
- *
- * SRVUTOK(srvtoken) macro returns user token (AP defined)
- * SRVNAME(srvtoken) macro returns shared variable name
- * SRVPXID(srvtoken) macro returns partner's extended ID
- * SRVSRBP(srvtoken) macro returns SVP share request block ptr
- *
- * Results: int Return Code
- * 0 = success
- * SRV_REJECT_SHARE = AP Server just quietly ends thread
- * other = error condition (Server message & end thread)
- *
- *--------------------------------------------------------------------------*/
- int sleep_init(void * srvtoken) {
- SRVUTOK(srvtoken) = malloc(8); /* fake control block as an example */
- if (SRVUTOK(srvtoken) == NULL)
- return(SRV_REJECT_SHARE); /* reject share if malloc failed */
- memset(SRVUTOK(srvtoken),'Z',8); /* initialize fake control block */
- return(0);
- }
-
- /*-F-sleep_server-------------------------------------------------------------
- *
- * Purpose: Auxiliary processor 999 is a sample server AP which
- * uses the general AP Server interface (apserver.c) to
- * implement a client-server type protocol through the
- * Shared Variable Processor. It uses a single shared
- * variable interface, with no name restrictions, and
- * runs each share request stream asynchronously under
- * a separate process (AIX, UNIX) or separate thread (OS/2).
- *
- * AP999 accepts 2 element integer vectors, where the first
- * value is the number of milliseconds to sleep, and the second
- * element is the size of the resulting character vector to
- * return. To demonstrate the handling of short versus long
- * requests, AP999 uses a fast path through the SVP for a
- * sleep of 1 second or less (holding the shared variable
- * lock from pre-ref until post-spec), while releasing the
- * lock (via srv_free call) for longer requests.
- *
- * Arguments: void * srvtoken pointer to AP Server token
- *
- * SRVBUF(srvtoken) macro returns ptr to shared var buffer
- * SRVBUFL(srvtoken) macro returns shared var buffer length
- * SRVUTOK(srvtoken) macro returns user token (AP defined)
- * SRVNAME(srvtoken) macro returns shared variable name
- * SRVPXID(srvtoken) macro returns partner's extended ID
- * SRVSRBP(srvtoken) macro returns SVP share request block ptr
- *
- * Results: int Return Code
- * 0 = success
- * other = error condition (Server retracts & exits)
- *
- * On return, the AP stores the result of the client's request
- * in the shared variable buffer, enlarging it if necessary (or
- * reallocating it if freed with srv_free) using the srv_alloc
- * callback to the AP Server. Note that srv_alloc will NOT
- * preserve the previous contents of the buffer, and SRVBUF
- * must be used to get addressability to the buffer after the
- * call to srv_alloc.
- *
- *--------------------------------------------------------------------------*/
-
- int sleep_server(void * srvtoken) {
- int rc = 0;
- APLOBJ *obj = (APLOBJ *) SRVBUF(srvtoken); /* request is an APL2 object */
- int objsize;
- int msecs = obj->dim[1]; /* 1st item of request is sleep time*/
- int shape = obj->dim[2]; /* 2nd is shape of char array result*/
- if ((obj->type != INTEGER && obj->type != BOOLEAN) ||
- obj->rank != VECTOR || obj->dim[0] != 2) {
- rc = error_code(srvtoken, INVALID_REQ); /* generate error return code*/
- return rc;
- }
- if (obj->type == BOOLEAN) { /* if boolean, convert to integer */
- msecs = ((unsigned long)obj->dim[1]) >> ((8*sizeof(long))-1);
- shape = (((unsigned long)obj->dim[1]) << 1) >> ((8*sizeof(long))-1);
- }
- if (msecs <= 1000) { /* short wait - OK to hold the lock */
- if (msecs > 0) {
- svsleep(msecs);
- }
- }
- else { /* long wait */
- srv_free(srvtoken); /* AP Server releases space, unlocks*/
- obj = NULL; /* no longer have addressability */
- if (msecs <= 60000) { /* bypass sleep if more than 60 */
- svsleep(msecs); /* seconds in this sample AP */
- }
- }
- objsize = aplobjsize(CHARACTER, VECTOR, shape); /* result size? */
- obj = (APLOBJ *) SRVBUF(srv_alloc(srvtoken, objsize)); /* ask for space*/
- if (obj == NULL) { /* if allocation failed, */
- rc = error_code(srvtoken, SYSTEM_LIMIT); /* set error return code */
- return rc;
- }
- obj->ptr = CDRID; /* build the CDR header for result */
- obj->nb = objsize;
- obj->nelm = shape;
- obj->type = CHARACTER;
- obj->rank = VECTOR;
- obj->dim[0] = shape;
- memset(&obj->dim[1], 'Z', shape); /* return some Z's for sleepy client*/
- return rc;
- }
-
- /*-F-error_code---------------------------------------------------------------
- *
- * Purpose: Return an error return code to client for this request
- *
- * Arguments: void * srvtoken pointer to AP Server token
- * int rc AP return code
- *
- * Results: int Return Code (from this function)
- * 0 = success
- * -1 = error condition (srv_alloc failed)
- *
- *--------------------------------------------------------------------------*/
- int error_code(void * srvtoken, int rc) {
- APLOBJ *obj; /* ptr to APL2 object in CDR format */
- int objsize;
- objsize = aplobjsize(INTEGER, SCALAR, 1); /* result size? */
- obj = (APLOBJ *) SRVBUF(srv_alloc(srvtoken, objsize)); /* ask for space*/
- if (obj == NULL) { /* we're in trouble if we */
- return (-1); /* can't get 32 bytes - die!*/
- }
- obj->ptr = CDRID; /* construct result header */
- obj->nb = objsize;
- obj->nelm = 1;
- obj->type = INTEGER;
- obj->rank = SCALAR;
- obj->dim[0] = rc;
- return (0);
- }
-
- /*-F-sleep_exit---------------------------------------------------------------
- *
- * Purpose: Server exit callback - called by the AP Server prior to
- * shared variable retraction and termination of this process
- * thread. Typical use by the AP is for freeing any dynamic
- * storage it allocated, closing files and pipes, etc.
- *
- * Arguments: void * srvtoken pointer to AP Server token
- *
- * SRVUTOK(srvtoken) macro returns user token (AP defined)
- *
- * Results: int Return Code
- * 0 = success
- * other = error condition (Server prints error msg)
- *
- *--------------------------------------------------------------------------*/
- int sleep_exit(void * srvtoken) {
- free(SRVUTOK(srvtoken)); /* free the fake control block */
- return(0);
- }
-
- /*==========================================================================*/
- /* The following wait callback routine is not used in this sample AP, but */
- /* is provided for documentation purposes. */
- /*==========================================================================*/
- /*-F-multi_wait---------------------------------------------------------------
- *
- * Purpose: Server callback to allow wait on multiple file descriptors,
- * semaphores, or message queues, including the shared variable
- * event queue.
- *
- * Return from this function allows the AP Server to handle
- * shared variable (SVP) events. Typically an AP will wait on the
- * notification token along with window, file, or pipe descriptors.
- * The AP handles non-SVP events, and simply returns from this
- * function when it wants the AP Server to process SVP events
- * (which normally result in a call-back to the AP "process" exit
- * function to handle the client request).
- *
- * Arguments: void * srvtoken pointer to AP Server token
- *
- * SRVNTOK(srvtoken) macro returns shared variable event
- * notification token (system dependent)
- * SRVUTOK(srvtoken) macro returns user token (AP defined)
- *
- * Results: int Return Code
- * 0 = success
- * other = error condition (Server retracts & ends)
- *
- *--------------------------------------------------------------------------*/
- int multi_wait(void * srvtoken) {
- #ifdef __OS2__
- unsigned long semh = SRVNTOK(srvtoken); /* semaphore handle for sv event */
- #else
- unsigned long mqid = SRVNTOK(srvtoken); /* message queue id for sv event */
- #endif
- /* AP typically does poll/select (AIX/UNIX) or muxwait (OS/2) at this point */
- /* and continues processing non-SVP events in a while loop until the only */
- /* event outstanding is an SVP event, at which time it simply returns */
- /* to the AP Server to read the share event queue and handle the event. */
- return(0);
- }
-
-
- ΓòÉΓòÉΓòÉ 16.2. SVP Programming Interface ΓòÉΓòÉΓòÉ
-
- Interface to the SVP is by C function call. There are three entry points based
- on the service desired. The following sections describe the structures used on
- these calls:
-
- int _System svpp(struct prb *); for SIGNON and SIGNOFF
-
- int _System svpe(struct wrb *); for SVEVENT (for example, wait)
-
- int _System svps(struct srb *); for all other SVP requests
-
- Notes:
-
- 1. The APL2/2 interpreter passes all of its command line arguments to any
- auxiliary processor that is started automatically. An auxiliary processor
- should be prepared to receive arguments that might not be applicable. The
- auxiliary processor should, however, always look for an -id parameter and
- use the information from the values given when issuing an SVSIGNON. If no
- -id parameter is found, the auxiliary processor should sign on with its own
- default processor number, and no parent or grandparent.
-
- 2. The ntoken returned on an SVSIGNON and SVSHARE is the handle of an OS/2
- event semaphore. Normally this token is only used on an SVEVENT call, but
- it can be waited on directly or added to a MuxWait semaphore. It should
- never be posted or reset by the auxiliary processor.
-
- 3. A SHUTDOWN event is posted to a dependent processor by the SVP when the
- parent issues an SVSIGNOFF, or when the SHUTDOWN option is selected from
- Options/Info/Processors menu item of the SVP Trace window. It is the
- responsibility of the auxiliary processor to retract all variables and
- issue an SVSIGNOFF when this signal is received.
-
- o PRB Requests
- o WRB Requests
- o SRB Requests
- o SVP Control Blocks
-
-
- ΓòÉΓòÉΓòÉ 16.2.1. PRB Requests ΓòÉΓòÉΓòÉ
-
- o SVSIGNON - Sign on to the SVP
- o SVSIGNOFF - Sign off from the SVP
-
-
- ΓòÉΓòÉΓòÉ 16.2.1.1. SVSIGNON - Sign on to the SVP ΓòÉΓòÉΓòÉ
-
- prb.req = SVSIGNON
-
- Sign on to the Shared Variable Processor. The following additional prb fields
- must be provided:
-
- prb.xid.pparent Grandparent processor number.
-
- prb.xid.parent Parent processor number.
-
- prb.xid.pparent Processor ID of caller.
-
- The following fields are optional:
-
- prb.user An arbitrary token returned on SVEVENT for incoming offers or
- shutdown.
-
- prb.emask Event conditions to be masked (not signalled). See WRB Requests for
- names of the events.
-
- prb.PRBFNPOST If true, disable posting to event queue.
-
- prb.PRBFNOTRC If true, disable tracing of SVP events for this processor.
-
- The following prb fields are returned:
-
- prb.rc Set to one of the following values:
-
- SVP_OK Success
- SVP_UNAVAILABLE SVP not available
- SVP_ERROR_INVARG Argument error
- SVP_ERROR_ASO Already signed on as xid
- SVP_ERROR_PUSED Another process signed on as xid
-
- prb.PRBFOFFS TRUE if one or more offers exist.
-
- prb.ntoken Token used for waiting on SVP events.
-
- prb.pcbx Processor token that must be used on all subsequent SVP calls.
-
- Note: If the SVP shared memory control area has not been initialized, this
- call automatically starts the process that establishes and owns that area.
-
-
- ΓòÉΓòÉΓòÉ 16.2.1.2. SVSIGNOFF - Sign off from the SVP ΓòÉΓòÉΓòÉ
-
- prb.req = SVSIGNOFF
-
- Sign off from the Shared Variable Processor. The following additional prb field
- must be provided:
-
- prb.pcbx The processor token that was returned by SVSIGNON.
-
- prb.rc Set to one of the following values:
-
- SVP_OK Success
- SVP_UNAVAILABLE SVP not available
- SVP_ERROR_INVARG Argument error
- SVP_ERROR_NSO Processor not signed on
-
- Notes:
-
- 1. If the SVP was automatically started by a signon, a usage count of
- processors is maintained and the SVP process is shut down when that count
- reaches 0.
-
- 2. The SVP retracts all variables shared with or offered from the processor
- during signoff.
-
-
- ΓòÉΓòÉΓòÉ 16.2.2. WRB Requests ΓòÉΓòÉΓòÉ
-
- wrb.req = SVEVENT
-
- Wait for an SVP event. This can be either a processor event (such as an
- incoming offer) or a shared variable event (such as variable set by partner).
- The following additional wrb fields must be provided:
-
- wrb.pcbx The processor token that was returned by SVSIGNON.
-
- wrb.ntoken A notification token returned by either SVSIGNON or SVSHARE.
-
- wrb.timeout Maximum time to wait in milliseconds if nonnegative. Use -1 to wait
- indefinitely for an event.
-
- The following flag is optional:
-
- wrb.WRBFFLUSH If true, causes the event queue to be flushed on return.
-
- The following wrb fields are filled in on return:
-
- wrb.rc One of the following return codes:
-
- SVP_OK Success
- SVP_UNAVAILABLE SVP not available
- SVP_ERROR_NSO Processor not signed on
- SVP_ERROR_INVARG Invalid argument
- SVP_ERROR_NOEVENT No event found before time expired
- SVP_ERROR_TIMEOUT Timeout occurred with no event
-
- wrb.user For SVP_EVENT_SHUTDOWN or SVP_EVENT_OFFEREX this is the value
- provided in prb.user at SVSIGNON. For all other events it is the
- value provided in srb.user at SVSHARE.
-
- wrb.event One of the following event codes:
-
- SVP_EVENT_SHUTDOWN SVP shutdown
- SVP_EVENT_OFFEREX Offer extended
- SVP_EVENT_OFFERAC Offer accepted
- SVP_EVENT_SMAVAIL Shared memory available
- SVP_EVENT_PRETRACT Partner retracted
- SVP_EVENT_PSETACV Partner set ACV
- SVP_EVENT_PSPEC Partner specified
- SVP_EVENT_PREF Partner referenced
- SVP_EVENT_FSPEC Partner failed specified
- SVP_EVENT_FREF Partner failed reference
- SVP_EVENT_PRELEASE Partner released variable
-
- wrb.scbx (except for SVP_EVENT_SHUTDOWN) For SVP_EVENT_OFFEREX, a variable
- token that can be used for a matching SVSHARE. For other events,
- the variable token that was used when sharing the variable.
-
- wrb.osn (SVP_EVENT_OFFEREX only) A sequence number that can be used for a
- matching SVSHARE to verify that the offer being reported is still
- outstanding.
-
- Note: Only one event is returned. The auxiliary processor should continue to
- make calls (to retrieve all events) until SVP_ERROR_NOEVENT is received.
-
-
- ΓòÉΓòÉΓòÉ 16.2.3. SRB Requests ΓòÉΓòÉΓòÉ
-
- The following sections discuss the SRB requests.
-
- o Offering and Retracting Variables
- o Setting and Using Data in Variables
- o Obtaining or Setting Information about Variables
-
-
- ΓòÉΓòÉΓòÉ 16.2.3.1. Offering and Retracting Variables ΓòÉΓòÉΓòÉ
-
- o SVSHARE - Offer a variable
- o SVSHARE - Match an offer
- o SVRETRACT - Retract a share
-
-
- ΓòÉΓòÉΓòÉ 16.2.3.1.1. SVSHARE - Offer a variable ΓòÉΓòÉΓòÉ
-
- srb.req = SVSHARE srb.scbx = 0
-
- Use this services to offer a new variable to some processor. The following
- additional srb fields must be provided:
-
- srb.pcbx The processor token that was returned by SVSIGNON.
-
- srb.pxid.procid The identification number of the partner to whom the offer is
- made.
-
- srb.scbx Must be zero to indicate a new offer.
-
- The following fields are optional:
-
- srb.osn Offer sequence number. Only offers with osn greater than this can
- be used to match the offer.
-
- srb.user User field, returned on SVEVENT.
-
- srb.acv Access control (see SVP Control Blocks).
-
- srb.name Variable name (up to 255 chars).
-
- srb.SRBFNEWQ True to request a separate event queue to be used for this
- variable. If false, the processor event queue is used for all
- events.
-
- srb.SRBFNPOST True to request that no events be signalled for this variable.
-
- srb.SRBFNOFFR True to disable automatic reoffer on partner's retract. It is
- recommended that all auxiliary processors turn this flag on.
-
- The following srb fields are filled in on return:
-
- srb.rc One of the following return codes:
-
- SVP_OK Success
- SVP_UNAVAILABLE SVP not available
- SVP_ERROR_NSO Processor not signed on
- SVP_ERROR_SHRSLF Offer to self
- SVP_ERROR_INVARG Invalid argument
-
- srb.pxid Extended ID of corresponding offer, if found.
-
- srb.osn Offer sequence number.
-
- srb.scbx A token associated with this share, that must be used on all
- subsequent requests.
-
- srb.ntoken A signalling token. This is unique to the variable if srb.SRBFNEWQ
- was set, otherwise the processor ntoken is returned.
-
- srb.acv Access control (see SVP Control Blocks).
-
- srb.state Shared variable state.
-
- srb.coupling Degree of coupling.
-
- Note: If a share request is made and no corresponding offer is found, a search
- is made for a file named apnnn, where nnn is the srb.procid. If this file is
- found, it is executed.
-
-
- ΓòÉΓòÉΓòÉ 16.2.3.1.2. SVSHARE - Match an offer ΓòÉΓòÉΓòÉ
-
- srb.req = SVSHARE srb.scbx = variable_token
-
- Match an offer that has already been made to this processor. This service
- requires information (including srb.scbx) that has been provided by SVSCAN or
- SVEVENT. The following additional srb fields must be provided:
-
- srb.pcbx The processor token that was returned by SVSIGNON.
-
- srb.scbx As returned by SVSCAN or SVEVENT.
-
- srb.osn Offer sequence number. If not zero, only an offer with the same
- OSN can be used to match the offer.
-
- srb.user User field, returned on SVEVENT.
-
- srb.acv Access control (see SVP Control Blocks).
-
- srb.SRBFNEWQ True to request a separate event queue to be used for this
- variable. If false, the processor event queue is used for all
- events.
-
- srb.SRBFNPOST True to request no event queue to be used for this variable.
-
- The following srb fields are filled in on return:
-
- srb.rc One of the following return codes:
-
- SVP_OK Success
- SVP_UNAVAILABLE SVP not available
- SVP_ERROR_NSO Processor not signed on
- SVP_ERROR_SHRSLF Offer to self
- SVP_ERROR_INVARG Invalid argument (including OSN mismatch)
- SVP_ERROR_NOOFFER No offer found
-
- srb.pxid Extended ID of corresponding offer, if found.
-
- srb.ntoken A signalling token. This is unique to the variable if
- srb.SRBFNEWQ was set, otherwise the processor ntoken is
- returned.
-
- srb.acv Access control (see SVP Control Blocks).
-
- srb.state Shared variable state.
-
- srb.coupling Degree of coupling.
-
-
- ΓòÉΓòÉΓòÉ 16.2.3.1.3. SVRETRACT - Retract a share ΓòÉΓòÉΓòÉ
-
- srb.req = SVRETRACT
-
- Retract a shared variable or share offer. The following additional srb fields
- must be provided:
-
- srb.pcbx The processor token that was returned by SVSIGNON.
-
- srb.scbx The variable token that was returned or used by SVSHARE.
-
- The following srb fields are filled in on return:
-
- srb.rc One of the following return codes:
-
- SVP_OK Success
- SVP_UNAVAILABLE SVP not available
- SVP_ERROR_NSO Processor not signed on
- SVP_ERROR_INVARG Invalid argument
-
- srb.coupling Degree of coupling.
-
-
- ΓòÉΓòÉΓòÉ 16.2.3.2. Setting and Using Data in Variables ΓòÉΓòÉΓòÉ
-
- In order to gain access to shared variable data, a processor must obtain a
- temporary lock, so that the partner does not attempt to update the data or
- change the variable's state during the accessing process. The processor
- commonly gets a lock implicitly through an SVPREREF or SVPRESPEC request. It is
- also possible to issue any of the SVPREREF or SVPRESPEC requests when the
- variable's lock is already held. Eventually, the processor must issue
- SVRELEASE, or more typically SVREF or SVSPEC, to release the lock. Applications
- should minimize the time that they hold the lock. No count is maintained, so a
- single unlocking request unlocks the variable no matter how many lock requests
- were issued.
-
- The second function provided by the locking requests is to give the calling
- program access to a data buffer. When SVPREREF is used, this buffer contains
- the current value of the variable. For SVPRESPEC, a buffer is provided of a
- caller-specified size. In either case, the buffer is available only until the
- next locking or unlocking request is issued.
-
- The three unlocking requests differ only in the effects they have on the access
- state of the variable. The system does not check for any correspondence between
- the locking request and the subsequent unlocking request. The normal sequence
- is, of course, to use SVPREREF followed by SVREF to reference a variable, and
- SVPRESPEC followed by SVSPEC to specify a new value for a variable. However,
- other sequences that can be useful on occasion include:
-
- o SVPREREF or SVRELEASE to peek at a value set by your partner without actually
- referencing it.
-
- o SVPREREF, SVPRESPEC, or SVSPEC to look at a value set by your partner and
- then replace it without losing the lock between reference and specification.
-
- o SVPREREF or SVSPEC to update part of the value in place, and inform your
- partner that the change has occurred.
-
- o SVRELEASE to look at the last value assigned to a variable even though you
- have already referenced it.
-
- o SVPREREF - Start variable reference
- o SVREF - Finish variable reference
- o SVPRESPEC - Start variable assignment
- o SVSPEC - Finish variable assignment
- o SVRELEASE - Release a preRef or preSpec
-
-
- ΓòÉΓòÉΓòÉ 16.2.3.2.1. SVPREREF - Start variable reference ΓòÉΓòÉΓòÉ
-
- srb.req = SVPREREF
-
- First stage of referencing (obtaining the current value of) a variable. This
- call provides a pointer to the variable's value, and locks the variable until
- SVREF is issued. The partner cannot issue further requests against the variable
- until it is unlocked by an SVSPEC, SVREF, or SVRELEASE. The following
- additional srb fields must be provided:
-
- srb.pcbx The processor token that was returned by SVSIGNON.
-
- srb.scbx The variable token that was returned or used by SVSHARE.
-
- The following srb fields are filled in on return:
-
- srb.rc One of the following return codes:
-
- SVP_OK Success
- SVP_UNAVAILABLE SVP not available
- SVP_ERROR_NSO Processor not signed on
- SVP_ERROR_NONV No new value
- SVP_ERROR_INVARG Invalid argument
-
- srb.vlen Size of object.
-
- srb.value Pointer to object.
-
- srb.acv Access control (see SVP Control Blocks).
-
- srb.state Shared variable state.
-
- srb.coupling Degree of coupling.
-
-
- ΓòÉΓòÉΓòÉ 16.2.3.2.2. SVREF - Finish variable reference ΓòÉΓòÉΓòÉ
-
- srb.req = SVREF
-
- Second stage of referencing (obtaining the current value of) a variable. This
- call notifies the SVP that the value has been extracted, and unlocks the
- variable. The value pointed to by srb.value on return from SVPREREF can no
- longer be accessed after issuing this call. The following additional srb fields
- must be provided:
-
- srb.pcbx The processor token that was returned by SVSIGNON.
-
- srb.scbx The variable token that was returned or used by SVSHARE.
-
- The following srb fields are filled in on return:
-
- srb.rc One of the following return codes:
-
- SVP_OK Success
- SVP_UNAVAILABLE SVP not available
- SVP_ERROR_NSO Processor not signed on
- SVP_ERROR_INVARG Invalid argument
-
- srb.acv Access control (see SVP Control Blocks).
-
- srb.state Shared variable state.
-
- srb.coupling Degree of coupling.
-
-
- ΓòÉΓòÉΓòÉ 16.2.3.2.3. SVPRESPEC - Start variable assignment ΓòÉΓòÉΓòÉ
-
- srb.req = SVPRESPEC
-
- First stage of specifying a value for a variable. This call provides a pointer
- to a location where the new value for the variable is to be placed, and locks
- the variable until SVSPEC is issued. The partner cannot issue further requests
- against the variable until it is unlocked. The following additional srb fields
- must be provided:
-
- srb.pcbx The processor token that was returned by SVSIGNON.
-
- srb.scbx The variable token that was returned or used by SVSHARE.
-
- srb.vlen Size of object.
-
- srb.SRBFIGNV True to ignore any unreferenced value.
-
- The following srb fields are filled in on return:
-
- srb.rc One of the following return codes:
-
- SVP_OK Success
- SVP_UNAVAILABLE SVP not available
- SVP_ERROR_NSO Processor not signed on
- SVP_ERROR_INVARG Invalid argument
- SVP_SMNOSPACE Space not available
- SVP_INTERLOCK Variable interlocked
- SVP_ERROR_VOS Partner's value not read
-
- srb.acv Access control (see SVP Control Blocks).
-
- srb.state Shared variable state.
-
- srb.value Pointer to area to write object.
-
- srb.coupling Degree of coupling.
-
-
- ΓòÉΓòÉΓòÉ 16.2.3.2.4. SVSPEC - Finish variable assignment ΓòÉΓòÉΓòÉ
-
- srb.req = SVSPEC
-
- Second stage of specifying a value for a variable. This call notifies the SVP
- that the new value is in place, and unlocks the variable. The value pointed to
- by srb.value on return from SVPRESPE can no longer be accessed after issuing
- this call. The following additional srb fields must be provided:
-
- srb.pcbx The processor token that was returned by SVSIGNON.
-
- srb.scbx The variable token that was returned or used by SVSHARE.
-
- The following srb fields are filled in on return:
-
- srb.rc One of the following return codes:
-
- SVP_OK Success
- SVP_UNAVAILABLE SVP not available
- SVP_ERROR_NSO Processor not signed on
- SVP_ERROR_INVARG Invalid argument
-
- srb.acv Access control (see SVP Control Blocks).
-
- srb.state Shared variable state.
-
- srb.coupling Degree of coupling.
-
-
- ΓòÉΓòÉΓòÉ 16.2.3.2.5. SVRELEASE - Release a preRef or preSpec ΓòÉΓòÉΓòÉ
-
- srb.req = SVRELEASE
-
- Release a variable previously locked by SVPREREF or SVPRESPEC without changing
- its state. The area pointed to by srb.value on return from the locking call can
- no longer be accessed after issuing this call. The following additional srb
- fields must be provided:
-
- srb.pcbx The processor token that was returned by SVSIGNON.
-
- srb.scbx The variable token that was returned or used by SVSHARE.
-
- The following srb fields are filled in on return:
-
- srb.rc One of the following return codes:
-
- SVP_OK Success
- SVP_UNAVAILABLE SVP not available
- SVP_ERROR_NSO Processor not signed on
- SVP_ERROR_INVARG Invalid argument
-
- srb.acv Access control (see SVP Control Blocks).
-
- srb.state Shared variable state.
-
- srb.coupling Degree of coupling.
-
-
- ΓòÉΓòÉΓòÉ 16.2.3.3. Obtaining or Setting Information about Variables ΓòÉΓòÉΓòÉ
-
- o SVSHARE - Inquire about a share offer
- o SVSCAN - Scan for a share offer
- o SVSEEACV - Query access control
- o SVSETACV - Set access control
- o SVSTATE - Query variable state
-
-
- ΓòÉΓòÉΓòÉ 16.2.3.3.1. SVSHARE - Inquire about a share offer ΓòÉΓòÉΓòÉ
-
- srb.req = SVSHARE srb.scbx = variable_token
-
- Obtain information about a previous share offer. The following additional srb
- fields must be provided:
-
- srb.pcbx The processor token that was returned by SVSIGNON.
-
- srb.pxid Partner extended ID, or zero. If zero, this value is returned.
-
- srb.scbx Variable token from original offer.
-
- The following srb fields are filled in on return:
-
- srb.rc One of the following return codes:
-
- SVP_OK Success
- SVP_UNAVAILABLE SVP not available
- SVP_ERROR_NSO Processor not signed on
- SVP_ERROR_INVARG Invalid argument
- SVP_ERROR_NOOFFER No offer found
-
- srb.pxid Extended ID of partner.
-
- srb.acv Access control (see SVP Control Blocks).
-
- srb.state Shared variable state.
-
- srb.coupling Degree of coupling.
-
-
- ΓòÉΓòÉΓòÉ 16.2.3.3.2. SVSCAN - Scan for a share offer ΓòÉΓòÉΓòÉ
-
- srb.req = SVSCAN
-
- Scan for an incoming shared variable offer. The following additional srb fields
- must be provided:
-
- srb.pcbx The processor token that was returned by SVSIGNON.
-
- srb.pxid If pxid.procid is zero, scan for offers from any processor.
- Otherwise, only offers from the specified processor are checked.
-
- srb.osn Offer sequence number. If nonzero, and srb.scbx=0, only offers
- with a sequence number greater than that specified are checked.
- This allows the scan to be repeated to search for additional
- offers, and also assists in rotating limited resources among
- requestors.
-
- If both srb.osn and srb.scbx=0 are nonzero, the osn value is
- used as a verification against the offer identified by the scbx.
-
- srb.name A null-delimited character string. If a nonempty name is
- specified, only offers for this variable name are checked.
-
- srb.scbx Normally must be zero, but can be set to identify a specific
- partner.
-
- The following srb fields are filled in on return:
-
- srb.rc One of the following return codes:
-
- SVP_OK Success
- SVP_UNAVAILABLE SVP not available
- SVP_ERROR_NSO Processor not signed on
- SVP_ERROR_INVARG Invalid argument
- SVP_ERROR_NOOFFER No offer found
-
- srb.pxid Extended ID of corresponding offer, if found.
-
- srb.osn Offer sequence number.
-
- srb.scbx SCB index of offer.
-
- srb.name Variable name.
-
-
- ΓòÉΓòÉΓòÉ 16.2.3.3.3. SVSEEACV - Query access control ΓòÉΓòÉΓòÉ
-
- srb.req = SVSEEACV
-
- Query access control. The following additional srb fields must be provided:
-
- srb.pcbx The processor token that was returned by SVSIGNON.
-
- srb.scbx The variable token that was returned or used by SVSHARE.
-
- The following srb fields are filled in on return:
-
- srb.rc One of the following return codes:
-
- SVP_OK Success
- SVP_UNAVAILABLE SVP not available
- SVP_ERROR_NSO Processor not signed on
- SVP_ERROR_INVARG Invalid argument
-
- srb.acv Access control (see SVP Control Blocks).
-
- srb.state Shared variable state.
-
- srb.coupling Degree of coupling.
-
-
- ΓòÉΓòÉΓòÉ 16.2.3.3.4. SVSETACV - Set access control ΓòÉΓòÉΓòÉ
-
- srb.req = SVSETACV
-
- Set access control. The following additional srb fields must be provided:
-
- srb.pcbx The processor token that was returned by SVSIGNON.
-
- srb.scbx The variable token that was returned or used by SVSHARE.
-
- srb.acv Access control desired (see SVP Control Blocks).
-
- The following srb fields are filled in on return:
-
- srb.rc One of the following return codes:
-
- SVP_OK Success
- SVP_UNAVAILABLE SVP not available
- SVP_ERROR_NSO Processor not signed on
- SVP_ERROR_INVARG Invalid argument
-
- srb.acv Access control (see SVP Control Blocks).
-
- srb.state Shared variable state.
-
- srb.coupling Degree of coupling.
-
-
- ΓòÉΓòÉΓòÉ 16.2.3.3.5. SVSTATE - Query variable state ΓòÉΓòÉΓòÉ
-
- srb.req = SVSTATE
-
- Query shared variable state. The following additional srb fields must be
- provided:
-
- srb.pcbx The processor token that was returned by SVSIGNON.
-
- srb.scbx The variable token that was returned or used by SVSHARE.
-
- The following srb fields are filled in on return:
-
- srb.rc One of the following return codes:
-
- SVP_OK Success
- SVP_UNAVAILABLE SVP not available
- SVP_ERROR_NSO Processor not signed on
- SVP_ERROR_INVARG Invalid argument
-
- srb.acv Access control (see SVP Control Blocks).
-
- srb.state Shared variable state.
-
- srb.coupling Degree of coupling.
-
- Notes:
-
- 1. In addition to the return codes listed, SVP_ERROR_SYSTEM can be returned if
- the SVP receives an error from an OS/2 system call. If this return code is
- received, prb.reason (or srb.reason or wrb.reason) provides an additional
- reason code. (See SVP Reason Codes for a listing of these reason codes
- beginning with SVP_ERRSYS_xxx.)
-
- 2. Similarly, if the SVP_ERROR_INVARG return code is received, the reason code
- is set to one of the SVP_ARGERR_xxx values.
-
-
- ΓòÉΓòÉΓòÉ 16.2.4. SVP Control Blocks ΓòÉΓòÉΓòÉ
-
- The control blocks shown here are defined in C include file aplap.h. See also
- Common Data Representation.
-
- o Extended ID Structure
- o Processor Request Block
- o Share Request Block
- o Wait Request Block
- o SVP Requests
- o SVP Return Codes
- o SVP Reason Codes
- o SVP Event Codes
- o Function Prototypes
-
-
- ΓòÉΓòÉΓòÉ 16.2.4.1. Extended ID Structure ΓòÉΓòÉΓòÉ
-
- struct xid { /* Extended ID structure */
- unsigned long pparent; /* Parent's Parent ID */
- unsigned long parent; /* Parent ID */
- unsigned long procid; /* Processor ID */
- unsigned long hostid; /* Host ID (TCP/IP address) */
- unsigned long res1; /* Reserved */
- unsigned long res2; /* Reserved */
- char userid[8]; /* User ID */
- char surrid[8]; /* Surrogate ID */
- };
- struct flags {
- unsigned int b1:1;
- unsigned int b2:1;
- unsigned int b3:1;
- unsigned int b4:1;
- unsigned int b5:1;
- unsigned int b6:1;
- unsigned int b7:1;
- unsigned int b8:1;
- unsigned int b9:1;
- unsigned int b10:1;
- unsigned int b11:1;
- unsigned int b12:1;
- unsigned int b13:1;
- unsigned int b14:1;
- unsigned int b15:1;
- unsigned int b16:1;
- unsigned int b17:1;
- unsigned int b18:1;
- unsigned int b19:1;
- unsigned int b20:1;
- unsigned int b21:1;
- unsigned int b22:1;
- unsigned int b23:1;
- unsigned int b24:1;
- unsigned int b25:1;
- unsigned int b26:1;
- unsigned int b27:1;
- unsigned int b28:1;
- unsigned int b29:1;
- unsigned int b30:1;
- unsigned int b31:1;
- unsigned int b32:1;
- };
-
-
- ΓòÉΓòÉΓòÉ 16.2.4.2. Processor Request Block ΓòÉΓòÉΓòÉ
-
- struct prb {
- short req; /* Request code */
- short rc; /* Return code */
- short reason; /* Reason code */
- short res1; /* Reserved */
- struct xid xid; /* Extended ID */
- void *user; /* User field */
- unsigned long emask; /* Event mask */
- unsigned long ntoken; /* Notification token */
- unsigned long pcbx; /* PCB index */
- unsigned long socket; /* Socket number */
- char ** argv; /* Command line args ptr */
- int argc; /* Count of args */
- void *res2; /* Reserved */
- struct flags prbflags; /* Processor flags */
- char reserved[32]; /* Reserved */
- };
- #define PRBFOFFS prbflags.b1 /* Offers outstanding */
- #define PRBFNPOST prbflags.b3 /* Don't post */
- #define PRBFNOTRC prbflags.b4 /* Don't trace */
-
-
- ΓòÉΓòÉΓòÉ 16.2.4.3. Share Request Block ΓòÉΓòÉΓòÉ
-
- struct srb {
- short req; /* Request code */
- short rc; /* Return code */
- short reason; /* Reason code */
- short res1; /* Reserved */
- void *user; /* User field */
- unsigned long ntoken; /* Notification token */
- unsigned long pcbx; /* PCB index */
- unsigned long scbx; /* SCB index */
- struct xid pxid; /* Extended Partner ID */
- long osn; /* Offer sequence number */
- long vlen; /* Length of value */
- void *value; /* Pointer to value */
- unsigned long pvrba; /* Reserved */
- unsigned short acv; /* Access control */
- unsigned short state; /* State */
- unsigned short coupling; /* Coupling */
- unsigned short res2; /* Reserved */
- struct flags srbflags; /* Flags */
- unsigned long socket; /* socket number */
- unsigned long socksem; /* socket send sem-id (UNIX) */
- char reserved[32]; /* Reserved */
- char name[256]; /* Variable name */
- };
- #define SRBFIGNV srbflags.b1 /* Ignore value waiting */
- #define SRBFNEWQ srbflags.b2 /* Request new event queue */
- #define SRBFNPOST srbflags.b4 /* Don't post */
- #define SRBFNOFFR srbflags.b5 /* No offer back on retract */
-
-
- ΓòÉΓòÉΓòÉ 16.2.4.4. Wait Request Block ΓòÉΓòÉΓòÉ
-
- struct wrb {
- short req; /* Request code */
- short rc; /* Return code */
- short reason; /* Reason code */
- short res1; /* Reserved */
- void *user; /* User field */
- unsigned long ntoken; /* Notification token */
- unsigned long pcbx; /* PCB index */
- unsigned long scbx; /* SCB index */
- unsigned long osn; /* offer sequence number */
- long timeout; /* Timeout value */
- unsigned long event; /* Event code */
- struct flags wrbflags; /* Flags */
- char reserved[16]; /* Reserved */
- };
- #define WRBFFLUSH wrbflags.b1 /* Flush event queue */
-
-
- ΓòÉΓòÉΓòÉ 16.2.4.5. SVP Requests ΓòÉΓòÉΓòÉ
-
- #define SVINIT 0
- #define SVSIGNON 1
- #define SVSIGNOFF 2
- #define SVSCAN 3
- #define SVSHARE 4
- #define SVSEEACV 5
- #define SVSETACV 6
- #define SVREF 7
- #define SVSPEC 8
- #define SVRELEASE 11
- #define SVRETRACT 12
- #define SVSTATE 13
- #define SVQUERY 14
- #define SVPREREF 15
- #define SVPRESPEC 16
- #define SVEVENT 17
- #define SVPOST 18
- #define SVGETTOKEN 19
-
-
- ΓòÉΓòÉΓòÉ 16.2.4.6. SVP Return Codes ΓòÉΓòÉΓòÉ
-
- #define SVP_ERROR_SYSTEM - 3 /* System Error */
- #define SVP_SMNOSPACE - 2 /* No space for object */
- #define SVP_INTERLOCK - 1 /* variable interlocked */
- #define SVP_OK 0 /* A-OK */
- #define SVP_UNAVAILABLE 1 /* SVP is unavailable */
- #define SVP_ERROR_PROTEXCP 2 /* Protection exception */
- #define SVP_ERROR_NSO 3 /* Not signed on */
- #define SVP_ERROR_ASO 4 /* Already signed on */
- #define SVP_ERROR_PUSED 5 /* Processor in use */
- #define SVP_ERROR_SHRSELF 8 /* Share with self */
- #define SVP_ERROR_VTL 10 /* Value too large */
- #define SVP_ERROR_NOVALUE 11 /* No value */
- #define SVP_ERROR_NOOFFER 12 /* No offer found */
- #define SVP_ERROR_INVREQ 13 /* Invalid request */
- #define SVP_ERROR_VOS 14 /* Unread value exists */
- #define SVP_ERROR_INVARG 15 /* Invalid argument */
- #define SVP_ERROR_NOEVENT 16 /* No event found */
- #define SVP_ERROR_TIMEOUT 17 /* Timeout on SVEVENT */
- #define SVP_ERROR_INTERRUPT 18 /* Interrupt on wait */
-
-
- ΓòÉΓòÉΓòÉ 16.2.4.7. SVP Reason Codes ΓòÉΓòÉΓòÉ
-
- #define SVP_ERRSYS_GETNMEM 100 /* Error getting named sh mem */
- #define SVP_ERRSYS_FREEMEM 101 /* Error freeing sh mem */
- #define SVP_ERRSYS_SUBFREE 102 /* Error freeing pcb/scb space */
- #define SVP_ERRSYS_NOPCBS 103 /* Unable to obtain new PCB */
- #define SVP_ERRSYS_NOSCBS 104 /* Unable to obtain new SCB */
- #define SVP_ERRSYS_GETESEM 105 /* Error creating event sem */
- #define SVP_ERRSYS_POSTQUEUE 106 /* Error on post of queue */
- #define SVP_ERRSYS_WAITESEM 107 /* Error on wait for semaphore */
- #define SVP_ERRSYS_RESETESEM 108 /* Reset semaphore error */
- #define SVP_ERRSYS_OPENSEM 109 /* Error opening a semaphore */
- #define SVP_ERRSYS_REQSEM 110 /* Error requesting sm semaphore */
- #define SVP_ERRSYS_RELSEM 111 /* Error releasing sm semaphore */
- #define SVP_ERRSYS_CREATESEM 112 /* Error creating sm semaphore */
- #define SVP_ERRSYS_GETXID 113 /* Error in side file lookup */
- #define SVP_ERRSYS_GETQUEUE 114 /* Error creating msg queue */
- #define SVP_ERRSYS_FREESEM 115 /* Error freeing semaphore */
- #define SVP_ERRSYS_FREEQUEUE 116 /* Error freeing queue */
- #define SVP_ERRSYS_WAITQUEUE 117 /* Error waiting on queue */
- #define SVP_ERRSYS_PEEKQUEUE 118 /* Error peeking queue */
- #define SVP_ERRSYS_OPENFAIL 119 /* Error opening file */
- #define SVP_ERRSYS_QEMPTY 120 /* Error queue is empty */
- #define SVP_ERRSYS_PURGEQUE 121 /* Error purging queue */
- #define SVP_ERRPRF_FNF 201 /* Profile not found */
- #define SVP_ERRPRF_SNF 202 /* Svopid not found */
- #define SVP_ERRPRF_INVF 203 /* Invalid file */
- #define SVP_ERRPRF_IOERR 204 /* I/O Error */
- #define SVP_ERRPRF_INVWC 205 /* Invalid wild card */
- #define SVP_ERRPRF_NOAUTH 206 /* Authorization failed */
- #define SVP_ARGERR_INVPCBX 301 /* Invalid PCB Index */
- #define SVP_ARGERR_INVSCBX 302 /* Invalid SCB Index */
- #define SVP_ARGERR_INVNAME 303 /* Invalid Variable name */
- #define SVP_ARGERR_NOLOCK 304 /* Lock not held on post-op */
- #define SVP_ARGERR_INVTOKEN 305 /* Invalid token on SVEVENT */
- #define SVP_ARGERR_INVPARENT 306 /* Parent not signed on */
-
-
- ΓòÉΓòÉΓòÉ 16.2.4.8. SVP Event Codes ΓòÉΓòÉΓòÉ
-
- #define SVP_EVENT_OFFEREX 0x01 /* Offer extended */
- #define SVP_EVENT_OFFERAC 0x02 /* Offer accepted */
- #define SVP_EVENT_SMAVAIL 0x04 /* Shared Memory Available */
- #define SVP_EVENT_PRETRACT 0x08 /* Partner retracted */
- #define SVP_EVENT_PSETACV 0x10 /* Partner set ACV */
- #define SVP_EVENT_PSPEC 0x20 /* Partner specified */
- #define SVP_EVENT_PREF 0x40 /* Partner referenced */
- #define SVP_EVENT_FSPEC 0x80 /* Partner failed spec */
- #define SVP_EVENT_FREF 0x100 /* Partner failed ref */
- #define SVP_EVENT_SHUTDOWN 0x200 /* SVP shutdown */
- #define SVP_EVENT_PRELEASE 0x400 /* Partner released var */
-
-
- ΓòÉΓòÉΓòÉ 16.2.4.9. Function Prototypes ΓòÉΓòÉΓòÉ
-
- int svpp(struct prb *);
- int svps(struct srb *);
- int svpe(struct wrb *);
- void svsleep(unsigned long);
- long aplobjsize(char, char, long);
- char * GetEnvOpt(char *, int, char **);
- #ifdef __OS2__
- #define BeginThread(x,y,z) _beginthread(x,NULL,65536,y)
- #else
- long BeginThread(void (*fn)(void *), void *, unsigned long);
- #endif
- /* sv state */
- #define INITSTATE 0x03
- #define PARTSPEC 0x05
- #define USERSPEC 0x0A
- /* sv coupling */
- #define ISSHARED 0x02
- #define ISOFFER 0x01
- #define ISNTSHAR 0x00
- /* sv acv */
- #define ACVMYSET 0x08
- #define ACVPARTSET 0x04
- #define ACVMYUSE 0x02
- #define ACVPARTUSE 0x01
-
-
- ΓòÉΓòÉΓòÉ 16.3. Common Data Representation ΓòÉΓòÉΓòÉ
-
- Data passed from APL2 to an auxiliary processor, and data passed back to APL2,
- must be in a special format. If you pass invalid data to APL2, unpredictable
- errors may occur.
-
- Each APL2 object contains information that describes its data type, shape,
- size, and origin. This information is called its header, and is located at the
- beginning of the object. The header consists of the following fields (defined
- in C include file aplobj.h):
-
- typedef struct aplobj {
- unsigned long ptr ;
- unsigned long nb ;
- unsigned long nelm ;
- unsigned char type ;
- unsigned char rank ;
- unsigned char fill[2] ;
- unsigned long dim[1] ;
- } APLOBJ ;
-
- ptr An identifier that indicates the system on which the object was built.
- The valid values are indicated by a set of C #define's:
-
- #define CDRid6000 0x40400000
-
- indicates a 32-bit system without numeric byte reversal (AIX, Solaris).
-
- #define CDRidOS2 0x00002020
-
- indicates a 32-bit system with numeric byte reversal (OS/2).
-
- Auxiliary processors should set the value of this field for objects
- they create. The constant CDRID provides the correct value for the
- running system.
-
- #ifdef __OS2__
- #define CDRID CDRidOS2
- #else
- #define CDRID CDRid6000
- #endif
-
- nb The number of bytes in this APL2 object. If the datatype of this object
- is that of a nested array the byte count must include this object and
- all of its subitems. The length of each object must be rounded to an
- even multiple of 16.
-
- nelm The number of elements in this APL2 object.
-
- type APL2 object type:
-
- 0 Boolean (1 bit per item)
- 1 Integer (4 bytes per item)
- 2 Real (8 bytes per item)
- 3 Complex (16 bytes per item)
- 4 ASCII Character (1 byte per item)
- 5 Unicode Character (4 bytes per item)
- 6 Integer Progression Vector (8 bytes)
- 7 General array (4 bytes per item)
-
- rank Rank of object (0-63).
-
- fill Unused; should be set to 0.
-
- dim[] Length of each dimension (number of elements in dim = rank)
-
- Immediately following the header for each object is the data associated with
- the object. The length of the data for each type is shown above. If the object
- has more than one dimension, its elements are stored in row order (as if the
- APL2 primitive Ravel had been applied to the variable).
-
- Immediately following the data are enough fill bytes to make the length of the
- object an even multiple of 16.
-
- o Special Notes for General Arrays
- o Byte Reversal
-
-
- ΓòÉΓòÉΓòÉ 16.3.1. Special Notes for General Arrays ΓòÉΓòÉΓòÉ
-
- 1. General arrays (type 7) have a recursive structure. Their data section
- consists of one 4-byte word per item, each containing the offset from the
- beginning of the general object to the corresponding subitem. The subitems
- (each of which can also be a general array) follow in left-list order.
-
- 2. General arrays that are empty (nelm=0) must have a prototype definition, so
- their data section consists of a single 4-byte offset field, which is the
- offset from the beginning of the general array to the beginning of the
- object that contains the prototype.
-
-
- ΓòÉΓòÉΓòÉ 16.3.2. Byte Reversal ΓòÉΓòÉΓòÉ
-
- On systems where numbers are stored in byte-reversed order, all numeric 4-byte
- header fields (nb, nelm, and dim) and all numeric data are expected to be
- stored in the object in byte-reversed order. However, note that Boolean data is
- stored as 1 bit per element, 8 bits per byte. It is not stored in byte-reversed
- order.
-
-
- ΓòÉΓòÉΓòÉ 17. SVP Trace Facility ΓòÉΓòÉΓòÉ
-
- The APL2/2 SVP Trace window displays information about shared variable
- processor requests. It also includes dialogs which provide statistics of SVP
- usage, information about processors that are signed on to the SVP, and
- variables that are shared by those processors. The dialogs can also be used to
- control tracing selectively and to send shutdown or kill requests to
- processors. There is never more than one trace window active at a time, and it
- shows events for all processors on the system that are using the SVP. Menu
- items are also provided to start, stop, and issue commands to the APL2/2 port
- server (used for cooperative processing).
-
- Note: You might want to start the SVP Trace window manually to avoid the
- overhead of SVP initialization when invoking APL2/2. If you have TCP/IP
- installed, the SVP Trace window must be started after TCP/IP is fully
- initialized.
-
- o Starting the SVP Trace Facility
- o Description
- o Menu Options
-
-
- ΓòÉΓòÉΓòÉ 17.1. Starting the SVP Trace Facility ΓòÉΓòÉΓòÉ
-
- If the SVP Trace window is not active when an APL interpreter or processor
- attempts to sign on to the SVP, it is started automatically. In this case it
- also automatically shuts down when the last processor signs off. The SVP Trace
- window can also be started by clicking on the "APL2/2 SVP Trace" icon or by
- invoking apl2svp.exe from the OS/2 command line.
-
- The syntax is:
-
- aplsvp [optional parameters]
-
- The following invocation options can be used:
-
- -trace [on|off|log|both]
- Enables display and logging of trace events.
-
- -listen [on|off]
- Listen on automatically starts the APL2/2 port server and TCP/IP
- server.
-
- All of the options can be specified by environment variable settings. The
- environment variables correspond to the invocation options with the character
- "aplsvp" prefix. For example:
-
- set APLSVPTRACE=on
-
- is equivalent to starting aplsvp with the -trace on option.
-
-
- ΓòÉΓòÉΓòÉ 17.2. Description ΓòÉΓòÉΓòÉ
-
- In most cases, SVP requests generate two trace messages; one on entry to the
- service and one on exit. If the exit return code is not 0, an additional
- message can be generated. During initialization the trace window displays the
- time and date that the SVP was started, and the amount of shared memory
- allocated for processor and variable control blocks.
-
- The trace window also, on request, logs the trace information. This log is
- always cleared when it is opened, so it shows trace information from only one
- instance of the trace window.
-
- When the SVP Trace window is closed, the size, position, current font, and
- background color are saved and used for the next invocation. To change the font
- of the trace messages, select a font from the OS/2 Font Palette and drop it on
- the SVP Trace window. To change the background color of the trace window,
- select a color from the OS/2 Color Palette and drop it on the window. The color
- of the messages cannot be changed.
-
- SVP trace messages are color coded as follows:
-
- Blue SVP initialization
- Black SVP trace
- Red SVP error
- Green APL2/2 port server
- Light Cyan APL2/2 TCP/IP server
- Dark Cyan Cross-system SVP trace messages
-
-
- ΓòÉΓòÉΓòÉ 17.3. Menu Options ΓòÉΓòÉΓòÉ
-
- This section describes each of the menu options available on the SVP Trace
- window.
-
- o File
- o Options
- o Actions
- o Info
- o Help
-
-
- ΓòÉΓòÉΓòÉ 17.3.1. File ΓòÉΓòÉΓòÉ
-
- The File menu contains choices to select a printer and print the SVP trace
- queue. It also contains a choice to shut down the SVP.
-
- Printer Setup Presents a dialog to select the OS/2 printer queue to which
- output should be sent.
-
- Print Prints the contents of the SVP trace queue.
-
- Exit Shuts down the SVP Trace window.
-
- Note: If the trace window is shut down while processors are
- still signed on, the SVP continues to operate, but the trace
- window cannot be restarted until all processors are signed off.
-
- A dialog is displayed if you attempt to shut down the SVP trace window while
- processors are still signed on.
-
- Select Yes, Shutdown to continue with the shutdown of the SVP trace window.
-
- Select No, Cancel to resume normal operation.
-
-
- ΓòÉΓòÉΓòÉ 17.3.2. Options ΓòÉΓòÉΓòÉ
-
- The Options menu allows you to control the display of SVP trace messages. The
- following choices appear in the Options menu:
-
- Trace on Toggle for displaying SVP trace entries in the trace window.
-
- Logging on Toggle for writing SVP trace entries to a file. The default file
- name is apl2svp.trc in the current directory. This can be
- changed by setting environment variable APL2SVPLOG.
-
- Timestamp on Toggle for including timestamps with SVP trace entries.
-
- Save Options Saves currently selected options for next invocation.
-
-
- ΓòÉΓòÉΓòÉ 17.3.3. Actions ΓòÉΓòÉΓòÉ
-
- The Actions menu contains choices that you use to affect the behavior of the
- Shared Variable Processor. The following choices appear in the Action menu:
-
- Cross System Starts and stops the APL2/2 port server and APL2/2 TCP/IP
- server. These programs must be started to use cooperative
- processing with a remote system.
-
- Port Server Issues the CLEAR or LIST commands to the APL2 port server.
-
- Purge Queue Empties the SVP trace queue. This does not effect the log file,
- if any.
-
- A dialog appears while starting the cross system programs. The Port Server is
- used to identify processors by their TCP/IP port number. You can select the
- TCP/IP port number that it uses for itself. (The default is 31415.)
-
-
- ΓòÉΓòÉΓòÉ 17.3.4. Info ΓòÉΓòÉΓòÉ
-
- The Info menu contains choices that display information about processors using
- the SVP.
-
- o Statistics
- o Processors
-
-
- ΓòÉΓòÉΓòÉ 17.3.4.1. Statistics ΓòÉΓòÉΓòÉ
-
- This dialog displays the following information:
-
- o Processors signed on
-
- The total number of processors currently signed on to the SVP.
-
- o Variables in use
-
- The total number of variables currently shared or offered.
-
- o Shared memory (bytes)
-
- The total amount of memory used by shared variables for data.
-
-
- ΓòÉΓòÉΓòÉ 17.3.4.2. Processors ΓòÉΓòÉΓòÉ
-
- This dialog displays a list of processors that are signed on to the SVP.
- Dependent processors have their parent processor and grandparent processor (if
- any) displayed in parentheses after the processor number. For example:
-
- 120 (1001)
-
- This refers to processor 120, which is a child of processor 1001.
-
- If a processor is selected in the list, the following buttons are activated:
-
- Info Displays information about the selected processor.
-
- Variables Displays a dialog listing the variables currently shared with,
- offered to, or offered from the selected processor.
-
- Shutdown Sends an SVP Shutdown signal to the selected processor. See SVP
- Programming Interface for more information.
-
- Kill Removes all information about the processor from the SVP and sends a
- kill signal to the process associated with the selected processor.
- This should only be attempted as a last resort. The SVP is not always
- able to clean up properly after an auxiliary processor has been
- killed.
-
- Selecting Done ends the dialog.
-
-
- ΓòÉΓòÉΓòÉ 17.3.5. Help ΓòÉΓòÉΓòÉ
-
- This menu contains the standard help choices:
-
- o Help Index
- o General Help
- o Using Help
- o Keys Help
- o Product Information
-
-
- ΓòÉΓòÉΓòÉ 18. APL2/2 Presentation Manager Services ΓòÉΓòÉΓòÉ
-
- In addition to the services provided by AP 145, APL2/2 includes a library of C
- services that are helpful when writing more complicated Presentation Manager
- programs. This chapter describes the programming interfaces for these services.
-
- The services support various types of operations:
-
- o The AplExec service allows an application to execute OS/2 commands and
- control the window within which the command is executed.
-
- o The keyboard handler supports APL input through Presentation Manager windows
- and dialog controls.
-
- o Print objects support integrating APL2's printing facilities with
- Presentation Manager applications.
-
- o The window byte services support associating storage with Presentation
- Manager windows.
-
- The APL2 Presentation Manager services are generally only used directly by
- experienced Presentation Manager programmers. It is recommended that users
- familiarize themselves with Presentation Manager programming concepts before
- attempting to use these services directly.
-
- Higher level APL2 cover functions for executing OS/2 commands and using the
- print services are provided in the PMTOOLS workspace.
-
- The APL2 Presentation Manager services reside in a dynamic link library (DLL)
- called aplpm.dll.
-
- o Using Presentation Manager Services from APL2
- o Using Presentation Manager Services from C
- o Executing OS/2 Commands
- o Keyboard Handler
- o Print Objects
- o Window Bytes
-
-
- ΓòÉΓòÉΓòÉ 18.1. Using Presentation Manager Services from APL2 ΓòÉΓòÉΓòÉ
-
- In order to access APL Presentation Manager services directly from APL2, the
- aplpm.dll file must be loaded and then the service to be used must be located
- within the loaded DLL. When an application finishes using the services, the DLL
- file should be freed. AP 145 is used to call the OS/2 services required to
- perform these operations. The following OS/2 Control Program services are used:
-
- DosLoadModule To load aplpm.dll
-
- DosQueryProcAddr To locate the service within the dll
-
- DosFreeModule To free aplpm.dll
-
- The PMTOOLS workspace contains cover functions for executing OS/2 commands and
- building print jobs. The workspace also contains utility functions that use the
- keyboard handler.
-
- The PMWIN workspace contains variables with names that correspond to the
- messages and flags used by the AplPm services.
-
-
- ΓòÉΓòÉΓòÉ 18.2. Using Presentation Manager Services from C ΓòÉΓòÉΓòÉ
-
- The aplpm.h header file contains prototypes for the functions and procedures in
- aplpm.dll. The header file also includes defined constants for the messages and
- flags used by the services.
-
- The aplpm.lib should be used to resolve references to services in the aplpm.dll
- file when link-editing C applications. The aplpm.dll services should not be
- statically linked with applications.
-
-
- ΓòÉΓòÉΓòÉ 18.3. Executing OS/2 Commands ΓòÉΓòÉΓòÉ
-
- AplExec is a C function used to execute OS/2 commands.
-
- Each command is executed in a new OS/2 session that inherits the caller's
- environment and file handles. The session can occur in a visible or invisible
- window and the session can be automatically terminated or left active when the
- command completes. The session can be cancelled by posting a semaphore.
-
- o Arguments
- o Return Codes
- o APL2 Syntax
- o C Syntax
-
-
- ΓòÉΓòÉΓòÉ 18.3.1. Arguments ΓòÉΓòÉΓòÉ
-
- PSZ Command Command to execute
-
- PULONG CmdRc Address of ULONG to receive command's return code
-
- BOOL Visible Controls whether the window in which the command is executed
- is visible
-
- BOOL Leave Controls whether the window in which the command is executed
- is left open after the command completes
-
- HEV HevCancel Shared event semaphore handle. If this semaphore is posted,
- the command is cancelled.
-
-
- ΓòÉΓòÉΓòÉ 18.3.2. Return Codes ΓòÉΓòÉΓòÉ
-
- AplExec issues the following return codes. The return code of the executed
- command is placed in the CmdRc argument.
-
- 0 Success
- 1 Command cancelled
- 2 OS/2 service error
-
-
- ΓòÉΓòÉΓòÉ 18.3.3. APL2 Syntax ΓòÉΓòÉΓòÉ
-
- The AP 145 service AplExecPgm supplies an event semaphore for AplExec. The
- command is cancelled if the shared variable is retracted before the command
- completes. For example:
-
- )LOAD 2 PMTOOLS
- APLEXECPGM 'APL2'
- 0
- 145 SHARE 'SV145'
- 2
- VISIBLEΓò£0
- LEAVEΓò£0
- SV145Γò£'AplExecPgm' 'APL2' 0 VISIBLE LEAVE
- SV145
- 0 0 AplExec APL2 0 0 0
-
-
- ΓòÉΓòÉΓòÉ 18.3.4. C Syntax ΓòÉΓòÉΓòÉ
-
- #include "aplpm.h"
- ULONG ExecRc ;
- PSZ Command ;
- ULONG CmdRc ;
- BOOL Visible ;
- BOOL Leave ;
- HEV HevCancel ;
- Command = "APL2" ;
- Visible = FALSE ;
- Leave = FALSE ;
- DosCreateEventSem(NULL,&HevCancel,DC_SEM_SHARED,FALSE) ;
- ExecRc = AplExec(Command,&CmdRc,Visible,Leave,HevCancel) ;
- DosCloseEventSem(HevCancel) ;
-
-
- ΓòÉΓòÉΓòÉ 18.4. Keyboard Handler ΓòÉΓòÉΓòÉ
-
- The keyboard handler is used to provide APL keyboard support for Presentation
- Manager windows. The AplKey service is a window procedure that is used to
- subclass an input window. The procedure processes WM_CHAR messages generated by
- the keyboard and translates them to the characters indicated by the user's
- selected keyboard layout.
-
- All applications that are currently using the keyboard handler share the same
- keyboard layout.
-
- o Enabling Keyboard Handler
- o Return Codes
- o C Syntax
- o Online Help
-
-
- ΓòÉΓòÉΓòÉ 18.4.1. Enabling Keyboard Handler ΓòÉΓòÉΓòÉ
-
- The parameters for all APLKEY_MSG messages are reserved and should be 0.
-
- The keyboard handler supports the following messages:
-
- APLKEY_MSG_INIT Initializes the keyboard handler.
- APLKEY_MSG_SELECT Opens the keyboard layout selection window.
- APLKEY_MSG_MODIFY Opens the keyboard layout modification window.
- APLKEY_MSG_TERM Terminates the keyboard handler.
-
- To enable APL keyboard support for a window:
-
- 1. Subclass the window with the AplKey service.
- 2. Send the window an APLKEY_MSG_INIT message
- 3. Enable the window.
-
- To disable APL keyboard support for a window:
-
- 1. Send the window an APLKEY_MSG_TERM message
- 2. Unsubclass the window.
-
- To temporarily disable APL keyboard support for a window, (perhaps to enable
- access to the current codepage's definition of the keyboard), your application
- can unsubclass the window. However, your application must resubclass the window
- and send the APLKEY_MSG_TERM message before destroying the window.
-
- Note: If you also need to subclass your window with your own window procedure,
- you must either subclass the window with the AplKey procedure first or
- use the APL window bytes services to place the address of the next
- window procedure at offset APLKEY_BYTES_OFFSET in the window's bytes.
- Unpredictable results occur otherwise.
-
-
- ΓòÉΓòÉΓòÉ 18.4.2. Return Codes ΓòÉΓòÉΓòÉ
-
- The keyboard handler returns 0 for all successfully processed APLKEY_MSG
- messages. If an error occurs, 1 is returned
-
-
- ΓòÉΓòÉΓòÉ 18.4.3. C Syntax ΓòÉΓòÉΓòÉ
-
- #include "aplpm.h"
- AplAllocWindowBytes(Hwnd,APLKEY_BYTES_LENGTH) ;
- AplSetWindowPtr(Hwnd,APLKEY_BYTES_OFFSET,
- (PVOID)WinSubclassWindow(Hwnd,AplKey)) ;
- WinSendMsg(Hwnd,APLKEY_MSG_INIT,NULL,NULL) ;
- /* Process application here */
- WinSendMsg(Hwnd,APLKEY_MSG_TERM,NULL,NULL) ;
- WinSubclassWindow(Hwnd,
- (PFNWP)AplQueryWindowPtr(Hwnd,APLKEY_BYTES_OFFSET)) ;
- AplFreeWindowBytes(Hwnd) ;
-
-
- ΓòÉΓòÉΓòÉ 18.4.4. Online Help ΓòÉΓòÉΓòÉ
-
- The keyboard handler's windows include their own online help. Applications do
- not need to perform any processing to enable this help. However, the help file
- must be available. It is called aplkey.hlp and should either be in the current
- directory or a directory listed in the HELP environment variable.
-
-
- ΓòÉΓòÉΓòÉ 18.5. Print Objects ΓòÉΓòÉΓòÉ
-
- The print facilities are implemented as an object window procedure. An
- application creates a print object and then sends messages to the object to
- build documents for printing. The AplPrintObject procedure processes messages
- for print objects.
-
- Print objects support a set of high-level functions that are printer
- independent.
-
- o Messages
- o Fonts and Colors
- o Return Codes
- o APL2 Syntax
- o C Syntax
- o Online Help
-
-
- ΓòÉΓòÉΓòÉ 18.5.1. Messages ΓòÉΓòÉΓòÉ
-
- Unless otherwise specified, all parameters for APLPRT messages are reserved and
- should be NULL.
-
- Print objects process the following messages:
-
- APLPRT_SELECT_PRINTER
- Display a print queue selection dialog.
-
- If this message has not been sent before a document has been opened,
- the user's default print queue is used.
-
- APLPRT_OPEN_DOCUMENT
- Open a print document.
-
- This message starts a new document on the selected print queue.
- Running headings and footings are reset to null. All font settings
- are reset to 10 point Courier. Word break and indentation are turned
- off. The page number and margin width are reset to zero.
-
- The message uses two parameters. If the first parameter is nonzero,
- it is the address of a null terminated string that is used as the
- title of the print job.
-
- The second parameter is two unsigned short integers. The first
- integer controls whether the document is printed duplex or not; 0
- indicates duplex is off; 1 indicates duplex is on. Duplex controls
- the use of margins and the placement of running headings and
- footings. The second integer controls whether a cancel print window
- is displayed. If it is 0, a cancel window is displayed. If it is
- other than zero, a cancel window is not displayed.
-
- The cancel window stays visible until the document is closed,
- cancelled, or the user pushes the cancel button. If the user pushes
- the cancel button, the printer object cancels the document and send
- it's owner a WM_CONTROL message with the APLPRT_PRINT_CANCELLED code.
- Subsequent attempts to add information to the document result in 1
- return codes.
-
- To maintain the responsiveness of the system, C applications should
- send APLPRT_PRINT_SENTENCE messages from a secondary thread.
-
- APLPRT_PRINT_SENTENCE
- Append a sentence to the document.
-
- The message requires two parameters. The first parameter is the
- address of a null terminated string.
-
- The second parameter is two Boolean shorts.
-
- The first short controls whether long lines are truncated or wrapped.
- If it is 1, lines are wrapped.
-
- The second short controls whether the text is printed monospaced or
- proportionally. If it is 1, text is printed monospaced.
-
- A new page is started if necessary to print the sentence or any
- wrapped portion of the sentence.
-
- If indenting is on, the sentence and any wrapped portions of the
- sentence are indented by the current indentation amount.
-
- The page number, heading, and footing are added to the page if they
- have not already been added and if they are enabled.
-
- APLPRT_NEWLINE
- Start a new line.
-
- The page number, heading, and footing are added to the page if they
- have not already been added and if they are enabled.
-
- A new page is started if necessary.
-
- APLPRT_NEWPAGE
- Conditionally start a new page.
-
- This message allows an application to either start a new page or
- conditionally start a new page depending on how much space is left at
- the bottom of the current page.
-
- If the first parameter is zero, a new page is started.
-
- If the first parameter is not zero, it specifies a number of points.
- The print object calculates the number of vertical points between the
- bottom of the last text in the body of the page and the bottom of the
- page. If the number of points specified in the parameter is greater
- than or equal to the number of points left on the page, a new page is
- started.
-
- Before calculating the amount of space left on the page, the print
- object adds the page number, heading, and footing if they have not
- already been added and if they are enabled.
-
- There are 72 points per inch. There are approximately 3.5 points per
- millimeter.
-
- APLPRT_CLOSE_DOCUMENT
- Close the document
-
- The document is sent to the print queue.
-
- APLPRT_CANCEL_DOCUMENT
- Close the document
-
- The document is discarded.
-
- APLPRT_SET_MARGIN
- Enable or disable an inside margin.
-
- The first parameter is reserved and must be zero. The second
- parameter is the width of the inside margin. The margin is only used
- if duplex is on. The margin width is specified in points.
-
- There are 72 points per inch. There are approximately 3.5 points per
- millimeter.
-
- APLPRT_SET_INDENT
- Enable or disable indentation.
-
- The first parameter is the indentation amount in points. Subsequently
- printed sentences are indented by the specified amount.
-
- There are 72 points per inch. There are approximately 3.5 points per
- millimeter.
-
- APLPRT_QUERY_LENGTH can be used to determine the length of a
- character string.
-
- APLPRT_SET_WORDBREAK
- Enable or disable word breaks.
-
- The first parameter is a Boolean short. If it is 1 and wrapping is
- enabled, lines are wrapped at blank delimited words.
-
- APLPRT_SET_LINESPACE
- Enable or disable interline spacing.
-
- A print object's default behavior is to insert 2 points of blank
- space between lines. In general this improves readability of text.
- However, this interline spacing can interfere with applications that
- use box drawing characters. This message can be used to disable, or
- enable, the insertion of interline spaces.
-
- The first parameter is a Boolean short. If it is 0 spacing is
- disabled. If it is 1 spacing is enabled.
-
- APLPRT_SET_HEADING
- Set the text of the running heading.
-
- The first parameter is a character string to be used as the running
- heading. If the parameter is 0 or a null string, headings are
- disabled.
-
- The maximum length of a running heading is 60 characters.
-
- APLPRT_SET_FOOTING
- Set the text of the running footing.
-
- The first parameter is a character string to be used as the running
- footing. If the parameter is 0 or a null string, footings are
- disabled.
-
- The maximum length of a running footing is 60 characters.
-
- APLPRT_SET_PAGENUMBERS
- Enable or disable page numbering.
-
- The first parameter is a Boolean short. If it is 1 a page number is
- placed on each page. If it is 0 page numbering is suppressed.
-
- APLPRT_QUERY_PAGENUMBER
- Query the current page number.
-
- This message returns the current page number.
-
- APLPRT_QUERY_LENGTH
- Query the length of a string.
-
- This message returns the length of a string in points. The font
- specified with APLPRT_FONT_BODY is used to calculate the string
- length.
-
- The first parameter is a character string whose length is to be
- determined. The maximum number of characters in the string is 256
- characters.
-
- If an error occurs, 0 is returned.
-
- Running headings, footings, and page numbers are added to a page of a document
- when the first sentence or new line is added to the page. Once a heading,
- footing, or page numbers has been added, changes to the headings and footings
- and enabling or disabling page numbering do not take effect until the next page
- is started.
-
-
- ΓòÉΓòÉΓòÉ 18.5.2. Fonts and Colors ΓòÉΓòÉΓòÉ
-
- Print objects support two messages for setting the font and color to be used in
- a document: APLPRT_SET_FONT and APLPRT_SET_COLOR. When either setting is
- changed, the new value is used for subsequent text until the setting is
- changed.
-
- APLPRT_SET_COLOR
- Set the color to use for text in the body of the document.
-
- This message requires one parameter. The parameter is an RGB color.
- If the parameter is 0 the color is reset to the default which is
- black.
-
- Running headings, footings, and page numbers are always printed in
- black.
-
- APLPRT_SET_FONT
- Set the font to use for a part of the document.
-
- This message requires two parameters. The first parameter specifies
- the part of the document for which to set the font. It can have the
- following values:
-
- APLPRT_FONT_BODY
- Use the font for text in the body of the document.
-
- APLPRT_FONT_PAGENUMBERS
- Use the font for the page numbers.
-
- APLPRT_FONT_HEADINGS
- Use the font for running headings.
-
- APLPRT_FONT_FOOTINGS
- Use the font for running footings.
-
- The second parameter is a character string specifying the point size
- and font. For example: '10.Helvetica'. If the parameter is 0 or a
- null string, the font is reset to the default. The default font is 10
- point Courier.
-
- When you set a font, the printer object looks for a scalable font
- with the specified facename. If no scalable font is found, the
- printer object looks for a bitmap font with the specified facename,
- pointsize, and that is designed for the selected printer's
- resolution. If no suitable font is found, the font is reset to 10
- point Courier.
-
- The following scalable fonts are supplied with OS/2:
-
- o Times New Roman
- o Times New Roman Bold
- o Times New Roman Bold Italic
- o Times New Roman Italic
- o Helvetica
- o Helvetica Bold
- o Helvetica Bold Italic
- o Helvetica Italic
- o Courier
- o Courier Bold
- o Courier Bold Italic
- o Courier Italic
- o Symbol Set
-
- The following scalable fonts are supplied with APL2/2:
-
- o Courier APL2
- o Courier APL2 Bold
- o APL2
- o APL2 Italic
-
- APLPRT_SET_FONT issues the following return codes:
-
- 0 Success. The font is changed.
-
- 1 Font not found. The font is reset to the default and the document is left
- open.
-
- 2 OS/2 service error. The document is cancelled.
-
- 3 Invalid font name. The font is not changed and the document is left open.
-
- Note: APLPRT_NEWLINE messages increment the line by the size of the current
- font. Therefore, in order to ensure that the current write point is
- moved down the correct amount, change to the new font before sending a
- newline message.
-
-
- ΓòÉΓòÉΓòÉ 18.5.3. Return Codes ΓòÉΓòÉΓòÉ
-
- Print objects return 0 for all successfully processed APLPRT messages except
- APLPRT_QUERY_PAGENUMBER and APLPRT_QUERY_LENGTH. 1 is returned if an error
- occurs.
-
-
- ΓòÉΓòÉΓòÉ 18.5.4. APL2 Syntax ΓòÉΓòÉΓòÉ
-
- The PMTOOLS workspace contains functions that correspond to each of the
- messages that print objects use. In addition, it contains functions to create
- and destroy print objects.
-
- If the user has cancelled the print job, SET_FONT and PRINT_SENTENCE return a
- 1.
-
- )LOAD 2 PMTOOLS
- CREATE_PRINTER
- SELECT_PRINTER
- OPEN_DOCUMENT 'Job Title'
- SET_FONT '10.Tms Rmn'
- 0
- PRINT_SENTENCE 'This is a sample sentence.'
- 0
- CLOSE_DOCUMENT
- DESTROY_PRINTER
-
-
- ΓòÉΓòÉΓòÉ 18.5.5. C Syntax ΓòÉΓòÉΓòÉ
-
- In C you must register the print object class before you can create a print
- object. The class must have at least APLPRT_RESERVED bytes of bytes allocated
- for it.
-
- Since print object windows do not display, use HWND_OBJECT as the parent.
-
- If your application should receive a message when the user cancels printing,
- specify an application window as the print object's owner. The print object
- also notifies your applications of cancellations using message return codes.
-
- If your application should not receive a message when the user cancels
- printing, specify HWND_DESKTOP as the owner.
-
- #include "aplpm.h"
- CHAR * ClassName ;
- PFNWP ClassPfnwp ;
- ULONG ClassStyle ;
- ULONG ClassWords ;
- HWND Printer ;
- HWND Parent ;
- PSZ Text ;
- ULONG Style ;
- LONG XCoord ;
- LONG YCoord ;
- LONG Width ;
- LONG Height ;
- HWND Owner ;
- HWND Behind ;
- ULONG ID ;
- PVOID BarData ;
- PVOID PresParam ;
- PSZ FontSizeName ;
- BOOL Wrap ;
- BOOL Fixed ;
- ClassName = (PSZ)APLPRT_CLASS ;
- ClassPfnwp = AplPrintObject ;
- ClassStyle = CS_SIZEREDRAW | CS_CLIPCHILDREN ;
- ClassWords = APLPRT_RESERVED ;
- WinRegisterClass(Hab,ClassName,ClassPfnwp,ClassStyle,ClassWords) ;
- Parent = HWND_OBJECT ;
- ClassName = (PSZ)APLPRT_CLASS ;
- Text = "" ;
- Style = 0 ;
- XCoord = 0 ;
- YCoord = 0 ;
- Width = 0 ;
- Height = 0 ;
- Owner = HWND_DESKTOP ;
- Behind = HWND_TOP ;
- ID = 0 ;
- BarData = NULL ;
- PresParam = NULL ;
- Printer = WinCreateWindow(Parent,ClassName,Text,Style,
- XCoord,YCoord,Width,Height,Owner,Behind,ID,BarData,PresParam) ;
- WinSendMsg(Printer,APLPRT_SELECT_PRINTER,0,0) ;
- WinSendMsg(Printer,APLPRT_OPEN_DOCUMENT,MPFROMP("Job Title"),NULL) ;
- FontSizeName = "10.Helvetica" ;
- WinSendMsg(Printer,APLPRT_SET_FONT,
- MPFROM1SHORT(APLPRT_FONT_BODY),
- MPFROMP(FontSizeName)) ;
- Wrap = TRUE ;
- Fixed = FALSE ;
- WinSendMsg(Printer,APLPRT_PRINT_SENTENCE,
- MPFROMP("This is a sample sentence."),
- MPFROM2SHORT(Wrap,Fixed)) ;
- WinSendMsg(Printer,APLPRT_CLOSE_DOCUMENT,0,0) ;
- WinDestroyWindow(Printer) ;
-
-
- ΓòÉΓòÉΓòÉ 18.5.6. Online Help ΓòÉΓòÉΓòÉ
-
- Print object windows include their own online help. Application do not need to
- perform any processing to enable this help. However, the help file must be
- available. It is called aplprint.hlp and should either be in the current
- directory or a directory listed in the HELP environment variable.
-
-
- ΓòÉΓòÉΓòÉ 18.6. Window Bytes ΓòÉΓòÉΓòÉ
-
- The window bytes services let you allocate and associate storage with a window
- handle. Unlike storage allocated by Presentation Manager during window
- creation, Apl window bytes can be allocated at any time after the window has
- been created. This is useful for those cases where the amount of storage is not
- known at the time the class is registered and when the storage at offset
- QWL_USER must be reserved for other programs.
-
- Window bytes should be freed before the window is destroyed.
-
- o AplAllocWindowBytes
- o AplSetWindowPtr
- o AplQueryWindowPtr
- o AplFreeWindowBytes
- o Return Codes
- o C Syntax
-
-
- ΓòÉΓòÉΓòÉ 18.6.1. AplAllocWindowBytes ΓòÉΓòÉΓòÉ
-
- Parameters:
-
- HWND The handle of the window to allocate bytes for
-
- ULONG The number of bytes to allocate
-
- If the window already has bytes allocated for it, 0 is returned.
-
-
- ΓòÉΓòÉΓòÉ 18.6.2. AplSetWindowPtr ΓòÉΓòÉΓòÉ
-
- Parameters:
-
- HWND The handle of the window in whose bytes to write
-
- ULONG The offset into the window's bytes to write the pointer
-
- PVOID A pointer to write into the window's bytes
-
- If the window does not have bytes allocated, 0 is returned.
-
-
- ΓòÉΓòÉΓòÉ 18.6.3. AplQueryWindowPtr ΓòÉΓòÉΓòÉ
-
- Parameters:
-
- HWND The handle of the window whose bytes to query
-
- ULONG The offset into the window's bytes from which to retrieve the
- pointer.
-
- The result is the pointer stored at the offset in the window's bytes
-
-
- ΓòÉΓòÉΓòÉ 18.6.4. AplFreeWindowBytes ΓòÉΓòÉΓòÉ
-
- Parameters:
-
- HWND The handle of the window whose bytes to free
-
- If the window does not have bytes allocated, 0 is returned.
-
-
- ΓòÉΓòÉΓòÉ 18.6.5. Return Codes ΓòÉΓòÉΓòÉ
-
- Window byte services return 1 if successful, 0 otherwise.
-
-
- ΓòÉΓòÉΓòÉ 18.6.6. C Syntax ΓòÉΓòÉΓòÉ
-
- #include "aplpm.h"
- ULONG Length ;
- ULONG Offset ;
- PVOID Pvoid ;
- Length = 4 ;
- AplAllocWindowBytes(Hwnd,Length) ;
- Offset = 0 ;
- Pvoid = 37 ;
- AplSetWindowPtr(Hwnd,Offset,Pvoid) ;
- Offset = 0 ;
- Pvoid = AplQueryWindowPtr(Hwnd,Offset)) ;
- AplFreeWindowBytes(Hwnd) ;
-
-
- ΓòÉΓòÉΓòÉ 19. Implementation Limits ΓòÉΓòÉΓòÉ
-
- The APL2 interpreter has the following implementation limits. See Limitations
- by System.
-
-
- ΓòÉΓòÉΓòÉ 19.1. Limitations by System - Part 1 ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Limitation
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Workstations (excluding APL2/PC)
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- APL2/370
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Largest and smallest representable numbers in an array
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 1.7976931348E308 ¤1.7976931348E308
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 7.2370055773E75 ¤7.2370055773E75
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Most infinitesimal (near 0) representable numbers in an array
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 2.2250738585E¤308 ¤2.2250738585E¤308
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 5.397605346934E¤79 ¤5.397605346934E¤79
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Maximum rank of an array
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 63
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 64
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Maximum length of any axis in an array
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- ¤1+2*31 (2147483647)
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- ¤1+2*31 (2147483647)
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Maximum product of all dimensions in an array
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- ¤1+2*31 (2147483647)
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- ¤1+2*31 (2147483647)
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Maximum depth of an array applied with the primitive functions depth (ΓòºR) and
- match (LΓòºR)
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 181
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 181
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- MORE...
-
-
- ΓòÉΓòÉΓòÉ 19.2. Limitations by System - Part 2 ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Limitation
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Workstations (excluding APL2/PC)
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- APL2/370
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Maximum depth of a shared variable
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 181
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 181
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Maximum depth of a copied variable
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 181
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 181
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Maximum number of characters in the name of a shared variable
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 255
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 255
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Maximum number of characters in a comment (minus leading blanks)
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 4090
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 32764
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Maximum length of line
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 8190
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- N/A
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Maximum number of lines in a defined function or operator
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- ¤1+2*15 (32767)
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- ¤1+2*31 (2147483647)
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- MORE...
-
-
- ΓòÉΓòÉΓòÉ 19.3. Limitations by System - Part 3 ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Limitation
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Workstations (excluding APL2/PC)
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- APL2/370
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Maximum number of labels in a defined function or operator
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Limited by number of lines
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 32767
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Maximum number of local names (excluding labels) in a defined function or
- operator
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Limited by lengths of lines and names
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 32767
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Maximum number of slots in the internal symbol table. A slot is required for
- each unique name, each unique constant, and each ill-formed constant in the
- workspace.
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- N/A
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 32767
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- MORE...
-
-
- ΓòÉΓòÉΓòÉ 19.4. Limitations by System - Part 4 ΓòÉΓòÉΓòÉ
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Limitation
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Workstations (excluding APL2/PC)
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- APL2/370
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Maximum value of РPW
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 254
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 390
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Maximum value of РPP
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 16
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 18
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- Maximum number of users with whom a user can share cross systems variables
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- N/A
-
-
- ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
-
- 59
-
-
- ΓòÉΓòÉΓòÉ 20. Deviations from APL2 Programming: Language Reference ΓòÉΓòÉΓòÉ
-
- This appendix describes the areas in which the implementation of APL2/2 differs
- from the APL2 language as defined in APL2 Programming: Language Reference.
-
- o General Language Differences
- o APL2 Statement Entry
- o APL2 Error Reporting
- o Display of Output
- o System Functions and Variables
- o Function Editor-Editor 1
- o System Commands
-
-
- ΓòÉΓòÉΓòÉ 20.1. General Language Differences ΓòÉΓòÉΓòÉ
-
- o
-
- Deviations
-
- o Disclose, expand, and replicate applied to rank 2 (or higher) arrays may give
- different results, because these functions use the prototype of the first
- element of the array as a fill item. APL2/370 uses the prototype of each row
- or column to extend rows or columns. For example, in APL2/2:
-
- у[2]1 'AB' 'ABC'
-
- gives:
-
- 1 0 0
- A B 0
- A B C
-
- instead of:
-
- 1 0 0
- A B
- A B C
-
- Application of these functions to vectors give fully-compatible results,
- because all platforms use the prototype of the first element.
-
- o Overtake of an array of rank 2 (or higher) can give a different result.
- APL2/2 uses the prototype of the first element of each row (if one exists) or
- the first element of the array (if you are forming a new row) when extending
- rows or columns. APL2/370 uses the prototype of each individual row or
- column, and this may lead to a different result when columns are extended.
- For example:
-
- 3 3╞2 2ц1 'A' 'B' 2
-
- gives:
-
- 1 A 0
- B 2
- 0 0 0
-
- instead of:
-
- 1 A 0
- B 2
- 0 0
-
- Extension of vectors gives fully-compatible results.
-
- o Partition with a scalar left argument and an empty right argument produces a
- one-element vector containing the empty argument. APL2/370 returns an empty
- vector with the empty argument as its prototype. For example:
-
- ц1ть0
- 1
- ╧1ть0
- 2
-
- instead of:
-
- ц1ть0
- 0
- ╧1ть0
- 2
-
- o Reduction of a scalar always returns a scalar, regardless of the valence of
- the function applied in reduction. For example:
-
- ╨┐/'A'
- A
-
- In APL2/370, this gives a VALENCE ERROR.
-
- o Complex numbers with a small imaginary part are not considered to be
- equivalent to a real number having the same real part, when used in
- comparisons. For example:
-
- 1.1╧1.1J1E¤20
-
- gives 0 in APL2/2 and 1 in APL2/370.
-
- o
-
- Restrictions
-
- o Factorial, binomial, matrix inverse, and matrix divide functions are not
- implemented for complex number arguments. For example:
-
- Т1J1
-
- gives DOMAIN ERROR. See the MATHFNS workspace in The MATHFNS Workspace for
- details of functions to perform these operations.
-
- o No fill function is implemented for the Each operator. For example:
-
- DISPLAYC Т■0цт2 3ц0
- .щ--------.
- Γöé .Γòò----. Γöé
- Γöé Γòƒ0 0 0Γöé Γöé
- Γöé Γöé0 0 0Γöé Γöé
- Γöé '~----' Γöé
- 'ю--------'
-
- instead of:
-
- .щ------.
- Γöé .Γòò--. Γöé
- Γöé Γòƒ0 0Γöé Γöé
- Γöé Γöé0 0Γöé Γöé
- Γöé Γöé0 0Γöé Γöé
- Γöé '~--' Γöé
- 'ю------'
-
- o No identity items for primitive dyadic scalar functions are implemented when
- the function is used symbolically in a defined operator. For example:
-
- РFX 'R╜(FN RED) A' 'R╜FN/A'
- +REDь0
-
- gives DOMAIN ERROR.
-
- o Identity functions for primitive dyadic nonscalar functions are not
- implemented. For example:
-
- ,/''
-
- gives DOMAIN ERROR.
-
- o While redundant parentheses can be used for clarity, they are not allowed
- around operators with axis specification. For example:
-
- 1(,[0.5])2
- (+/[1])1 2
-
- give SYNTAX ERROR.
-
- o Axis specification is not supported with inner and outer product. For
- example:
-
- 1 2 +.ї[1] 3
- 0 1 ┬░.,[0.5] 2
- 1 2 ,.,[0.5] 2 2ць4
-
- all give AXIS ERROR.
-
- o Selective specification is not implemented for all cases available in
- APL2/370. For example:
-
- (юV)╜A
- (L0ΓûáV)Γò£A
-
- give DOMAIN ERROR. Also, selective specification of a shared variable gives a
- SYNTAX ERROR. (The ENLISTA function, described in Miscellaneous Functions,
- provides a function that can be used to replace the use of selective
- specification with enlist.)
-
-
- ΓòÉΓòÉΓòÉ 20.2. APL2 Statement Entry ΓòÉΓòÉΓòÉ
-
- o
-
- System Dependency
-
- o Exact fidelity of statements is not maintained. APL2/2 tokenizes function and
- operator statement lines, and when redisplayed, these may not appear exactly
- as entered. This can cause redundant spaces to be removed and the display
- format of numbers to be changed.
-
-
- ΓòÉΓòÉΓòÉ 20.3. APL2 Error Reporting ΓòÉΓòÉΓòÉ
-
- o
-
- Deviation
-
- o Where multiple errors occur in an operation, APL2/2 may report a different
- error message than APL2/370. For example:
-
- 'AB'ш3 3ць9 ф APL2/2
- DOMAIN ERROR
- 'AB'ш3 3ць9
- ^ ^
- 'AB'ш3 3ць9 ф APL2/370
- LENGTH ERROR
- 'AB'ш3 3ць9
- ^ ^
-
-
- ΓòÉΓòÉΓòÉ 20.4. Display of Output ΓòÉΓòÉΓòÉ
-
- o
-
- Deviations
-
- o Mixed arrays containing characters not in РAV may not be displayed.
-
- A╜1,РUCS 20000
- A
- gives DOMAIN ERROR.
-
- o An array that exceeds the printing width (РPW) is wrapped line by line,
- rather than being folded plane by plane.
-
- o Display of columns of data of an array of mixed type gives different results.
- APL2/370 formats a column that contains mixed data types with the character
- items right-justified, and numeric items aligned on the decimal point.
- However, APL2/2 formats a column of an array of mixed type with the character
- items right-justified, and numeric items left-justified, so that:
-
- 3 2ц'APL2' 2 (ъ1)
-
- gives:
-
- APL2 2
- 3.141592654 APL2
- 2 3.141592654
-
- instead of:
-
- APL2 2
- 3.141592654 APL2
- 2 3.141592654
-
- o Dyadic format with negative left argument leaves additional spaces to allow
- for an exponent containing up to three digits, and a negative sign. For
- example:
-
- цР╜¤1о1 1
-
- gives:
-
- 1E0 1E0
- 14
-
- instead of:
-
- 1E0 1E0
- 8
- Also:
-
- 5 ¤1о1
-
- gives:
-
- DOMAIN ERROR
- 5 ¤1о1
- ^ ^
-
- instead of:
-
- 5 ¤1о1
- 1E0
-
- o Dyadic format of a nested array with rank higher than two returns a result
- with the same rank. APL2/370 always returns a rank two result for higher rank
- nested arrays. For example:
-
- цо1 1 1цт'APL2'
-
- gives:
-
- 1 1 6
-
- instead of:
-
- 1 6
-
- o Complex numbers are always displayed with both the real part and the
- imaginary part, even when one differs from the other by more than РPP orders
- of magnitude. APL2/370 does not display the real or imaginary part of a
- complex number when it is less than the other by more than РPP orders of
- magnitude (unless РPP is at its maximum). For example:
-
- 3E45J2
- 3E45J2
-
- instead of
-
- 3E45J2
- 3E45
-
- o
-
- Restriction
-
- o Dyadic format gives DOMAIN ERROR if formatting an element of an array gives a
- long result. This occurs when the formatting of a number results in more than
- 255 characters. For example:
-
- 0╨╛1E255
- DOMAIN ERROR
- 0╨╛1E255
- ^
-
-
- ΓòÉΓòÉΓòÉ 20.5. System Functions and Variables ΓòÉΓòÉΓòÉ
-
- o
-
- Deviation
-
- o If РFC is set to anything other than a character vector, a РFC ERROR is
- reported at the time of the assignment.
-
- o
-
- Restrictions
-
- o РL and РR are not recognized; they return VALUE ERROR.
-
- o РNLT can be referenced, but not set. National language is set with the -nlt
- invocation option.
-
- o РPW is not regarded as a session variable, and is reset by a )CLEAR or a
- )LOAD command.
-
- o The contents of РAI are incorrect after they reach 2*31. This can occur for
- sessions active longer than 24 days.
-
- o General shared variable offers are not supported.
-
-
- ΓòÉΓòÉΓòÉ 20.6. Function Editor-Editor 1 ΓòÉΓòÉΓòÉ
-
- o
-
- Deviation
-
- o The header line (line 0) of a function does not accept a comment. Any comment
- given is ignored, and no error is generated. For example:
-
- ╖TEST ф COMMENT
- [1] LINE 1
- [2] [Р]
- [0] TEST
- [1] LINE 1
- [2]
-
- o
-
- Restrictions
-
- o Recursive editing and entry of system commands while editing are not allowed.
-
- o Editing of a line removes stop (SΓòó) and trace (TΓòó) controls for that line.
-
- o The header line (line 0) of a function must not end with a semicolon (;).
- System variable names are the only names beginning with a quad (Р) that can
- be localized in the header line. An attempt to localize a system function
- name or an undefined name beginning with a quad is rejected with a DEFN
- ERROR.
-
-
- ΓòÉΓòÉΓòÉ 20.7. System Commands ΓòÉΓòÉΓòÉ
-
- o
-
- Deviations
-
- o )DROP accepts a suffix in a quoted filename format for deleting transfer form
- files.
-
- o )DROP of a workspace or transfer file displays the time and date that the
- file was saved, rather than the current time and date.
-
- o )ERASE erases and )COPY replaces the most local, rather than the global,
- referent of an object.
-
- o )FNS, )VARS, )OPS, )NMS, and )LIB allow specification of multiple ranges of
- names on one command, where the language defines only one range per command.
- The syntax for specification of multiple ranges is:
-
- [[firstΓöéfirst-last][...] Workstation implementation
-
- [first][-][last] APL2/370 implementation
-
- o The )SYMBOLS command gives a different report: size of table (bytes), number
- of bytes in use, number of symbols.
-
- o )SYMBOLS n contracts or expands symbol table to n bytes. )SYMBOLS n works
- only if there are no objects defined yet.
-
- o )OUT of a full workspace with a nonempty stack is not allowed, and the error
- reports SI WARNING and NOT SAVED are given.
-
- o
-
- Restrictions
-
- o Comments are not allowed after system commands. For example,
- )WSID ф Query workspaceid is accepted by APL2/370, but not by APL2/2.
-
- o Indirect )COPY and )ERASE are not implemented. See the EXPUNGE function in
- the EXAMPLES workspace (described in Miscellaneous Functions) for details of
- a function that supports indirect name lists.
-
- o )EDITOR 2 is not implemented. See the EDITOR_2 function, described in The
- EDIT Workspace, for details of a defined function that is equivalent to the
- APL2/370 Editor 2.
-
- o )EDITOR name is implemented with some restrictions. It enables a system
- editor to be invoked, and allows Γòûname to be used to edit a function,
- operator or a simple character matrix. The restrictions are the same as those
- imposed by "РFX РCR name"; for instance, stop (S╢) and trace (T╢) controls on
- the function are removed, and if the function is suspended, the suspended
- copy is not modified.
-
- o )MORE always displays "NO MORE INFORMATION".
-
- o
-
- System Dependencies
-
- o )IN accepts a library number.
-
- )IN [libno] filename [obj1 {obj2}...]
-
- o )PIN accepts a library number.
-
- )PIN [libno] filename [obj1 {obj2}...]
-
- o )LIB accepts a different syntax and lists OS/2 files. The syntax is:
-
- )LIB [libno] [initials] [{.aplΓöé.atf}]
-
- This displays files with names that start with any of the character's
- initials and that have an extension of .apl or .atf in the indicated library
- libno.
-
- )LIB [libno] [first] - [last] [{.aplΓöé.atf}]
-
- This displays files with names that fall alphabetically between first and
- last, and have an extension of .apl or .atf in the indicated library libno.
- If either first or last is omitted, that end of the range is unbounded.
-
- If neither initials nor first-last are given, all files are listed that meet
- the other qualifications.
-
- For both syntax variations, if no library number is given, the files for
- library ╞РAI are listed. This is normally defined as being the directory from
- which APL2 is invoked. If neither .apl nor .atf are specified, both are
- assumed.
-
- Examples:
-
- )LIB 1 Lists all .apl and .atf files in library 1
- )LIB 2 AP Lists all .apl and .atf files with names beginning with
- "AP" in library 2
- )LIB AP.apl Lists all .apl files with names beginning with "AP"
- )LIB -C Lists all .apl and .atf files beginning with letters A
- through C
- )LIB C- Lists all .apl and .atf files beginning with letters C
- through z
- )LIB A-C Lists all .apl and .atf files beginning with letters A
- through C
- )LIB A C Lists all .apl and .atf files beginning with letters A and
- C
-
- o )OUT accepts a library number.
-
- )PIN [libno] filename [obj1 {obj2}...]
-
-
- ΓòÉΓòÉΓòÉ 21. APL2/2 Directory Structure ΓòÉΓòÉΓòÉ
-
- When the product is installed, a directory is created as the top level
- installation directory. The default name is 'C:\APL2OS2\'. It contains the
- installation control file and a read.me file that has important information
- about the product. All other directories in the table below are created under
- this main installation directory. Following each directory is a brief
- description.
-
- bin Binary executable files
- dll Dynamic link libraries
- fonts APL2 fonts (session manager, AP 124, and AP 207)
- help Online help files and documentation
- include C Include files for user-written auxiliary procesors
- lib C libraries for user-written auxiliary processors
- samples Sample programs
- wslib1 Distributed workspaces )LIB 1
- wslib2 Distributed workspaces )LIB 2
-
-
- ΓòÉΓòÉΓòÉ 22. Bibliography ΓòÉΓòÉΓòÉ
-
- o APL2 Publications
- o Other Books You Might Need
-
-
- ΓòÉΓòÉΓòÉ 22.1. APL2 Publications ΓòÉΓòÉΓòÉ
-
- o APL2 Fact Sheet, GH21-1090
- o APL2/370 Application Environment Licensed Program Specifications, GH21-1063
- o APL2/370 Licensed Program Specifications, GH21-1070
- o APL2 for AIX/6000 Licensed Program Specifications, GC23-3058
- o APL2 for OS/2 Licensed Program Specifications, GC26-3358
- o APL2 for Sun Solaris Licensed Program Specifications, GC26-3359
- o APL2/370 Installation and Customization under CMS, SH21-1062
- o APL2/370 Installation and Customization under TSO, SH21-1055
- o APL2 Migration Guide, SH21-1069
- o APL2 Programming: Language Reference, SH21-1061
- o APL2/370 Programming: Processor Interface Reference, SH21-1058
- o APL2 Reference Summary, SX26-3999
- o APL2 Programming: An Introduction to APL2, SH21-1073
- o APL2 for AIX/6000: User's Guide, SC23-3051
- o APL2 for OS/2: User's Guide, SH21-1091
- o APL2 for Sun Solaris: User's Guide, SH21-1092
- o APL2 for the IBM PC: User's Guide, SC33-0600
- o APL2 GRAPHPAK: User's Guide and Reference, SH21-1074
- o APL2 Programming: Using Structured Query Language, SH21-1057
- o APL2/370 Programming: Using the Supplied Routines, SH21-1056
- o APL2/370 Programming: System Services Reference, SH21-1054
- o APL2/370 Diagnosis Guide, LY27-9601
- o APL2/370 Messages and Codes, SH21-1059
-
-
- ΓòÉΓòÉΓòÉ 22.2. Other Books You Might Need ΓòÉΓòÉΓòÉ
-
- The following book is recommended:
-
- o APL2 at a Glance, by James Brown, Sandra Pakin, and Raymond Polivka,
- published by Prentice-Hall, ISBN 0-13-038670-7 (1988). (Copies can be ordered
- from IBM as SC26-4676.)
-
- Sets of keyboard keycaps are available from IBM as:
-
- o APL2 Keycaps (US and UK base set), SX80-0270
- o APL2 Keycaps, German upgrade to SX80-0270, SX23-0452
- o APL2 Keycaps, French upgrade to SX80-0270, SX23-0453
- o APL2 Keycaps, Italian upgrade to SX80-0270, SX23-0454.
-
- Two sets of APL2 Keyboard Decals, SC33-0604, are included with this product.
- Additional sets of these decal sheets can be ordered from IBM.
-
- The following publications may also be of use, and can be ordered from IBM:
-
- o IBM OS/2 Information and Planning Guide, G326-0160.
-
- o IBM OS/2 Command Reference, S71G-4112.
-
- o IBM OS/2 Keyboards and Code Pages, S10G-6312.
-
- o TCP/IP for OS/2 Programmer's Reference, SC31-6077.
-
-
- ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ
-
- TCP/IP must have been started before starting the SVP for cross-system sharing
- to work.