home *** CD-ROM | disk | FTP | other *** search
/ The Developer Connection…ice Driver Kit for OS/2 3 / DEV3-D1.ISO / devtools / apl2 / apl2osug.in_ / apl2osug.inf (.txt)
Encoding:
OS/2 Help File  |  1993-12-17  |  521.3 KB  |  19,334 lines

  1.  
  2. ΓòÉΓòÉΓòÉ 1. Organization of this document ΓòÉΓòÉΓòÉ
  3.  
  4. o Organization of this document 
  5. o Notices 
  6. o About This Book 
  7. o Part 1. Getting Started 
  8. o Overview 
  9. o Installing and Customizing APL2/2 
  10. o Invoking APL2/2 
  11. o Part 2. Using APL2 
  12. o General Information 
  13. o Using the Session Manager 
  14. o Editors 
  15. o Using APL2 across Systems 
  16. o Part 3. Application Guide 
  17. o Associated Processors 
  18. o Supplied External Routines 
  19. o Supplied Workspaces 
  20. o Supplied Auxiliary Processors 
  21. o Part 4. Advanced Topics 
  22. o Writing Your Own External Routines 
  23. o Writing Your Own Auxiliary Processors 
  24. o SVP Trace Facility 
  25. o APL2/2 Presentation Manager Services 
  26. o Appendixes 
  27. o Implementation Limits 
  28. o Deviations from APL2 Programming: Language Reference 
  29. o APL2/2 Directory Structure 
  30. o Bibliography 
  31.  
  32.  
  33. ΓòÉΓòÉΓòÉ 2. Notices ΓòÉΓòÉΓòÉ
  34.  
  35. References in this publication to IBM products, programs, or services do not 
  36. imply that IBM intends to make these available in all countries in which IBM 
  37. operates. Any reference to an IBM product, program, or service is not intended 
  38. to state or imply that only IBM's product, program, or service may be used. Any 
  39. functionally equivalent product, program, or service that does not infringe any 
  40. of IBM's intellectual property rights may be used instead of the IBM product, 
  41. program, or service. Evaluation and verification of operation in conjunction 
  42. with other products, except those expressly designated by IBM, are the user's 
  43. responsibility. 
  44.  
  45. IBM may have patents or pending patent applications covering subject material 
  46. in this document. The furnishing of this document does not give you any license 
  47. to these patents. You can send license inquiries, in writing, to the IBM 
  48. Director of Commercial Relations, IBM Corporation, Purchase, NY 10577. 
  49.  
  50. o Programming Interface Information 
  51. o Trademarks 
  52.  
  53.  
  54. ΓòÉΓòÉΓòÉ 2.1. Programming Interface Information ΓòÉΓòÉΓòÉ
  55.  
  56. This user's guide is intended to help programmers code APL2 applications in 
  57. APL2/2. This book documents General-Use Programming Interface and Associated 
  58. Guidance Information provided by APL2. 
  59.  
  60. General-use programming interfaces allow the customer to write programs that 
  61. obtain the services of APL2. 
  62.  
  63.  
  64. ΓòÉΓòÉΓòÉ 2.2. Trademarks ΓòÉΓòÉΓòÉ
  65.  
  66. The following terms, denoted by an asterisk (*) in this publication, are 
  67. trademarks of the IBM Corporation in the United States or other countries or 
  68. both: 
  69.  
  70.  
  71.  AIX/6000                                           IBM
  72.  APL2                                               Operating System/2
  73.  APL2/6000                                          OS/2
  74.  CUA                                                Presentation Manager
  75.  DATABASE 2                                         System/370
  76.  DB2                                                System/390
  77.  
  78. The following terms, denoted by a double asterisk (**) in this publication, are 
  79. trademarks of other companies: 
  80.  
  81. PostScript     Adobe Systems, Inc. 
  82. Sun            Sun Microsystems, Inc. 
  83. Solaris        Sun Microsystems, Inc. 
  84.  
  85.  
  86. ΓòÉΓòÉΓòÉ 3. About This Book ΓòÉΓòÉΓòÉ
  87.  
  88. This book describes IBM APL2 for OS/2 (APL2/2). 
  89.  
  90. This User's Guide is intended to help you use APL2/2. It contains a collection 
  91. of tables and descriptions giving full details of installation, operation, 
  92. supplied workspaces, and external interfaces. 
  93.  
  94. | CAUTION: Many parts of this document (including the     |
  95. | "Conventions" section listed below) use APL characters. |
  96. | You must have the "APL2 Info" font installed before     |
  97. | viewing those pages.  The font is not installed         |
  98. | automatically.  If you have not yet installed it,       |
  99. | please see the installation instructions.  (If you are  |
  100. | not sure, you could try looking at the "Conventions"    |
  101. | section now.  If the window disappears and you see a    |
  102. | system error message, you will know why.  Don't worry,  |
  103. | no permanent damage will have occurred.)                |
  104. |                                                         |
  105. | By the way, there are no APL characters in the          |
  106. | installation section.  (We wouldn't do that to you!)    |
  107.  
  108. o APL2 Publications 
  109. o Conventions Used in This Book 
  110.  
  111.  
  112. ΓòÉΓòÉΓòÉ 3.1. APL2 Publications ΓòÉΓòÉΓòÉ
  113.  
  114. APL2 Publications lists the books in the APL2 library. This table shows the 
  115. books and how they can help you with specific tasks. 
  116.  
  117. For the titles and order numbers of other related publications, see the 
  118. Bibliography. 
  119.  
  120.  
  121. ΓòÉΓòÉΓòÉ 3.1.1. APL2 Publications - Part 1 ΓòÉΓòÉΓòÉ
  122.  
  123.  
  124. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  125.  
  126. Type of Information and Titles 
  127.  
  128.  
  129. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  130.  
  131. Publication Number 
  132.  
  133.  
  134. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  135.  
  136.  
  137. General product 
  138.  
  139.  
  140. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  141.  
  142.  
  143. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  144.  
  145. APL2 Fact Sheet 
  146.  
  147.  
  148. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  149.  
  150. GH21-1090 
  151.  
  152.  
  153. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  154.  
  155.  
  156. Warranty 
  157.  
  158.  
  159. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  160.  
  161.  
  162. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  163.  
  164. APL2/370 Application Environment Licensed Program Specifications 
  165.  
  166.  
  167. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  168.  
  169. GH21-1063 
  170.  
  171.  
  172. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  173.  
  174.  APL2/370 Licensed Program Specifications 
  175.  
  176.  
  177. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  178.  
  179. GH21-1070 
  180.  
  181.  
  182. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  183.  
  184.  APL2 for AIX/6000 Licensed Program Specifications 
  185.  
  186.  
  187. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  188.  
  189. GC23-3054 
  190.  
  191.  
  192. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  193.  
  194.  APL2 for OS/2 Licensed Program Specifications 
  195.  
  196.  
  197. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  198.  
  199. GC26-3358 
  200.  
  201.  
  202. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  203.  
  204.  APL2 for Sun Solaris Licensed Program Specifications 
  205.  
  206.  
  207. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  208.  
  209. GC26-3359 
  210.  
  211.  
  212. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  213.  
  214.  
  215. Introductory language material 
  216.  
  217.  
  218. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  219.  
  220.  
  221. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  222.  
  223. APL2 Programming: An Introduction to APL2 
  224.  
  225.  
  226. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  227.  
  228. SH21-1073 
  229.  
  230.  
  231. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  232.  
  233. MORE... 
  234.  
  235.  
  236. ΓòÉΓòÉΓòÉ 3.1.2. APL2 Publications - Part 2 ΓòÉΓòÉΓòÉ
  237.  
  238.  
  239. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  240.  
  241. Type of Information and Titles 
  242.  
  243.  
  244. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  245.  
  246. Publication Number 
  247.  
  248.  
  249. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  250.  
  251.  
  252. Common reference material 
  253.  
  254.  
  255. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  256.  
  257.  
  258. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  259.  
  260. APL2 Programming: Language Reference 
  261.  
  262.  
  263. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  264.  
  265. SH21-1061 
  266.  
  267.  
  268. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  269.  
  270.  APL2 Reference Summary 
  271.  
  272.  
  273. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  274.  
  275. SX26-3999 
  276.  
  277.  
  278. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  279.  
  280.  
  281. System interface 
  282.  
  283.  
  284. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  285.  
  286.  
  287. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  288.  
  289. APL2/370 Programming: System Services Reference 
  290.  
  291.  
  292. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  293.  
  294. SH21-1056 
  295.  
  296.  
  297. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  298.  
  299.  APL2/370 Programming: Using the Supplied Routines 
  300.  
  301.  
  302. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  303.  
  304. SH21-1054 
  305.  
  306.  
  307. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  308.  
  309.  APL2/370 Programming: Processor Interface Reference 
  310.  
  311.  
  312. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  313.  
  314. SH21-1058 
  315.  
  316.  
  317. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  318.  
  319.  APL2 for OS/2: User's Guide 
  320.  
  321.  
  322. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  323.  
  324. SH21-1091 
  325.  
  326.  
  327. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  328.  
  329.  APL2 for Sun Solaris: User's Guide 
  330.  
  331.  
  332. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  333.  
  334. SH21-1092 
  335.  
  336.  
  337. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  338.  
  339.  APL2 for AIX/6000: User's Guide 
  340.  
  341.  
  342. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  343.  
  344. SC23-3051 
  345.  
  346.  
  347. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  348.  
  349.  APL2 GRAPHPAK: User's Guide and Reference 
  350.  
  351.  
  352. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  353.  
  354. SH21-1074 
  355.  
  356.  
  357. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  358.  
  359.  APL2 Programming: Using Structured Query Language 
  360.  
  361.  
  362. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  363.  
  364. SH21-1057 
  365.  
  366.  
  367. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  368.  
  369. MORE... 
  370.  
  371.  
  372. ΓòÉΓòÉΓòÉ 3.1.3. APL2 Publications - Part 3 ΓòÉΓòÉΓòÉ
  373.  
  374.  
  375. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  376.  
  377. Type of Information and Titles 
  378.  
  379.  
  380. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  381.  
  382. Publication Number 
  383.  
  384.  
  385. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  386.  
  387.  APL2 Migration Guide 
  388.  
  389.  
  390. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  391.  
  392. SH21-1069 
  393.  
  394.  
  395. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  396.  
  397.  
  398. Mainframe system programming 
  399.  
  400.  
  401. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  402.  
  403.  
  404. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  405.  
  406. APL2/370 Installation and Customization under CMS 
  407.  
  408.  
  409. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  410.  
  411. SH21-1062 
  412.  
  413.  
  414. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  415.  
  416.  APL2/370 Installation and Customization under TSO 
  417.  
  418.  
  419. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  420.  
  421. SH21-1055 
  422.  
  423.  
  424. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  425.  
  426.  APL2/370 Messages and Codes 
  427.  
  428.  
  429. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  430.  
  431. SH21-1059 
  432.  
  433.  
  434. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  435.  
  436.  APL2/370 Diagnosis Guide 
  437.  
  438.  
  439. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  440.  
  441. LY27-9601 
  442.  
  443.  
  444. ΓòÉΓòÉΓòÉ 3.2. Conventions Used in This Book ΓòÉΓòÉΓòÉ
  445.  
  446. The notations used in this user's guide and their meanings are: 
  447.  
  448. lower       Lowercase italicized words in syntax represent values you must 
  449.             provide. 
  450.  
  451. UPPER       In syntax blocks, uppercase words in an APL character set represent 
  452.             keywords that you must enter exactly as shown. 
  453.  
  454. []          Usually, brackets are used to delimit optional portions of syntax; 
  455.             however, where APL2 function editor commands or fragments of code 
  456.             are shown, brackets are part of the syntax. 
  457.  
  458. [AΓöéBΓöéC]     A list of options separated by Γöé and enclosed in brackets indicates 
  459.             that you can select one of the listed options. Here, for example, 
  460.             you could specify either A, B, C, or none of the options. 
  461.  
  462. {AΓöéBΓöéC}     Braces enclose a list of options (separated by Γöé), one of which you 
  463.             must select. Here, for example, you would specify either A, B, or 
  464.             C. 
  465.  
  466. ...         An ellipsis indicates that the preceding syntactic item can be 
  467.             repeated. 
  468.  
  469. {}...       An ellipsis following syntax that is enclosed in braces indicates 
  470.             that the enclosed syntactic item can be repeated. 
  471.  
  472. Γò£Γòò          Used to mean "is equivalent to." It does not denote an APL2 
  473.             operation. 
  474. The following APL2 names are used throughout this user's guide: 
  475.  
  476. Z           Result name 
  477. F           Function name 
  478. L           Left argument name 
  479. R           Right argument name 
  480. MOP         Monadic operator name 
  481. DOP         Dyadic operator name 
  482. LO          Left operand name 
  483. RO          Right operand name 
  484.  
  485. The term workstation refers to all platforms where APL2 is implemented except 
  486. those based on System/370* and System/390* architecture. 
  487.  
  488. Throughout this book, the following product names apply: See Product names. 
  489.  
  490.  
  491. ΓòÉΓòÉΓòÉ 3.2.1. Product names ΓòÉΓòÉΓòÉ
  492.  
  493.  
  494. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  495.  
  496. Product Name 
  497.  
  498.  
  499. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  500.  
  501. Platform 
  502.  
  503.  
  504. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  505.  
  506. APL2/2 
  507.  
  508.  
  509. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  510.  
  511. OS/2 
  512.  
  513.  
  514. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  515.  
  516. APL2 for Sun** Solaris** 
  517.  
  518.  
  519. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  520.  
  521. Sun Solaris 
  522.  
  523.  
  524. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  525.  
  526. APL2/6000* 
  527.  
  528.  
  529. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  530.  
  531. AIX/6000* 
  532.  
  533.  
  534. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  535.  
  536. APL2/370 
  537.  
  538.  
  539. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  540.  
  541. MVS or VM 
  542.  
  543.  
  544. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  545.  
  546. APL2/PC 
  547.  
  548.  
  549. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  550.  
  551. DOS 
  552.  
  553.  
  554. ΓòÉΓòÉΓòÉ 4. Overview ΓòÉΓòÉΓòÉ
  555.  
  556. This chapter contains an overview of APL2, including: 
  557.  
  558. o Why Should You Learn APL2? 
  559. o What is IBM APL2/2? 
  560. o Required Hardware 
  561. o Required Software 
  562.  
  563.  
  564. ΓòÉΓòÉΓòÉ 4.1. Why Should You Learn APL2? ΓòÉΓòÉΓòÉ
  565.  
  566. Learning a programming language requires an investment of your most precious 
  567. resources-time and effort. Why should you invest your time in APL2 in 
  568. preference to any of the others? There are programming languages you can learn 
  569. faster than APL2. But a tool is worth what you invest in it. Roman numerals 
  570. were easier to use than Arabic numerals for most computations of Roman times. 
  571. They were, however, impossible to extend for use in more sophisticated 
  572. mathematics. Arabic numerals are harder to learn but are clearly a superior 
  573. notation for mathematics. 
  574.  
  575. On the surface, some other programming languages are easier to learn because 
  576. APL2 contains so much advanced function. However, you do not need to learn all 
  577. of APL2 in order to use it effectively. You can learn a subset of APL2 first, 
  578. leaving more advanced function for later. 
  579.  
  580. APL2 is extremely concise. A significant computation can fit in one page of 
  581. code or even a few lines. One reason APL2 programs are so compact is that 
  582. operations are represented by symbols, not English words. This has the 
  583. advantage of being international, but may look intimidating. If you have paged 
  584. through this manual, you have probably noticed that some of the symbols used 
  585. come from the Greek alphabet. This leads some to say that APL2 looks like 
  586. Greek. Just remember that Greek looks like Greek yet there are children who can 
  587. read and write it fluently. It is a question not of difficulty, but of 
  588. familiarity. Just as you can read the symbols used for international road signs 
  589. once you know what they mean, you quickly become comfortable with APL2 symbols 
  590. and appreciate the conciseness of the notation. Think of APL2 as the 
  591. international road signs of programming. 
  592.  
  593.  
  594. ΓòÉΓòÉΓòÉ 4.2. What is IBM APL2/2? ΓòÉΓòÉΓòÉ
  595.  
  596. APL is a general-purpose language that enjoys wide use in such diverse 
  597. applications as commercial data processing, system design, mathematical and 
  598. scientific computation, and the teaching of mathematics and other subjects. It 
  599. has proved particularly useful in database applications, where its 
  600. computational power, user-friendliness, and communication facilities combine to 
  601. increase the productivity of both application programmers and end users. 
  602.  
  603. When implemented as a computing system, the user types statements that specify 
  604. the work to be done, and the computer responds by displaying the result of the 
  605. work at a device such as a video display or a printer. In addition to work 
  606. purely at the keyboard and its associated display, entries can also specify the 
  607. use of printers, disk files, or other remote devices. 
  608.  
  609. A programming language should be relevant. That is, you should have to write 
  610. only what is logically necessary to specify the job you want done. This may 
  611. seem an obvious point, but many of the earlier programming languages forced you 
  612. to be concerned as much with the internal requirements of the machine as with 
  613. your own statement of the problem. APL takes care of these internal 
  614. considerations automatically. 
  615.  
  616. A programming language needs both power and simplicity. By power, we mean the 
  617. ability to handle large or complicated tasks. By simplicity, we mean the 
  618. ability to state what must be done briefly and neatly, in a way that is easy to 
  619. read and easy to write. You might think that power and simplicity are competing 
  620. requirements, so that if you have one, you can not have the other, but that is 
  621. not necessarily so. Simplicity means not that the computer is limited to doing 
  622. simple tasks, but that the user has a simple way to write instructions to the 
  623. computer. The power of APL as a programming language comes in part from its 
  624. simplicity. 
  625.  
  626. The letters "APL" originated with the initials of a book written by K. E. 
  627. Iverson, A Programming Language (New York:  Wiley, 1962). Dr. Iverson first 
  628. worked on the language at Harvard University, and then continued its 
  629. development at IBM with the collaboration of Adin Falkoff and others at the IBM 
  630. T. J. Watson Research Center. The term APL now refers to the language that is 
  631. an outgrowth of that work. APL is the language, and APL2 is the brand name of 
  632. IBM's extended version of APL. IBM APL2 for OS/2 is the name of a particular 
  633. implementation of the APL2 language. This implementation, hereafter called 
  634. APL2/2, has the following features: 
  635.  
  636. o APL2/2 is highly compatible with the other members of the APL2 family. It 
  637.   uses the same APL2 Programming: Language Reference. APL2 allows the 
  638.   transporting of workspaces, in transfer file format, between APL2 platforms. 
  639.   EBCDIC-ASCII translation is performed automatically where required, and is 
  640.   transparent to the user. 
  641.  
  642. o The APL2/2 session manager is common user access (CUA*) conforming and has a 
  643.   similar look and feel to the session managers of the other products in the 
  644.   APL2 family, with the added benefit of Presentation Manager* features such as 
  645.   window movement, window resizing, scroll bars, font specification, and the 
  646.   use of icons. It provides scrolling capability, permanent session logs, 
  647.   stacked input, color control, function key support, keyboard redefinition, 
  648.   and national language support. 
  649.  
  650. o APL2/2 provides many of the auxiliary processors available with the APL2/370 
  651.   or other workstation products: 
  652.  
  653.    - AP 100 (host system command processor) 
  654.    - AP 101 (alternative input (stack) processor) 
  655.    - AP 119 (socket interface processor) 
  656.    - AP 124 (text display processor) 
  657.    - AP 127 (SQL relational database processor for DB2*) 
  658.    - AP 207 (universal graphics processor) 
  659.    - AP 210 (file I/O processor) 
  660.    - AP 211 (APL2 common object library processor) 
  661.  
  662. o APL2/2 also includes AP 145, which provides a programmable interface to the 
  663.   OS/2 services. 
  664.  
  665. o APL2/2 provides many of the common distributed workspaces and functions that 
  666.   are currently available on the System/370 or workstation products. 
  667.  
  668. o APL2/2 provides national language support. It provides external command and 
  669.   message translation tables that can be modified to support other countries, 
  670.   or individual user preferences. 
  671.  
  672.  
  673. ΓòÉΓòÉΓòÉ 4.3. Required Hardware ΓòÉΓòÉΓòÉ
  674.  
  675. The following hardware is the minimum required for APL2/2: 
  676.  
  677. o A personal computer running OS/2 Version 2.0 or higher. 
  678.  
  679.   Note:  For more information on the OS/2 machine requirements, refer to IBM 
  680.   OS/2 Information and Planning Guide. 
  681.  
  682. o At least 8 MB of hard disk space above that required by OS/2. 
  683.  
  684. o At least 2 MB of memory above that required by OS/2. 
  685.  
  686. All displays and printers supported by OS/2 are supported for APL2/2. 
  687.  
  688.  
  689. ΓòÉΓòÉΓòÉ 4.4. Required Software ΓòÉΓòÉΓòÉ
  690.  
  691. The following software is the minimum required to run APL2/2: 
  692.  
  693. o OS/2 Version 2.0 or later 
  694.  
  695.   APL2/2 runs under OS/2 2.0 or any later release of OS/2. However, OS/2 2.0 
  696.   has some deficiencies that impose restrictions on APL2. This section lists 
  697.   the known problems for running APL2 on OS/2 2.0. 
  698.  
  699.    - The PostScript** print driver in the base level of OS/2 2.0 builds 
  700.      unusable print job files when APL fonts are used. In order to overcome 
  701.      this problem, select the Printer Specific option in the Queue Options for 
  702.      the printer. Selecting the Printer Specific option produces print job 
  703.      files that print properly, but they are very large and are very slow to 
  704.      produce since the print driver generates code to draw each character 
  705.      rather than downloading the APL font. 
  706.  
  707.    - The 16-bit Graphics Engine provided with the base level OS/2 2.0 is quite 
  708.      slow when PostScript fonts are used on display devices. The performance on 
  709.      some machines may be unacceptable. 
  710.  
  711.    - The OS/2 facility used to save and restore the position and size of the 
  712.      SVP Trace window does not work reliably on some levels of OS/2 2.0. 
  713.  
  714.    - The font used for AP 124 might not display the entire APL character set 
  715.      when using the base level of OS/2 2.0. 
  716.  
  717. o DB2/2 1.0 or later for AP 127 
  718. o TCP/IP 2.0 or later for AP 119 
  719. o IBM Developer's Toolkit for OS/2 for using PMTOOL's dialog-building functions 
  720.  
  721.  
  722. ΓòÉΓòÉΓòÉ 5. Installing and Customizing APL2/2 ΓòÉΓòÉΓòÉ
  723.  
  724. This chapter contains information about the installation of APL2/2. 
  725.  
  726. o The APL2/2 Package 
  727. o Installation Overview 
  728. o Installing APL2/2 on Your Workstation 
  729. o APL2 Keyboard Support 
  730. o Customizing APL2/2 
  731.  
  732.  
  733. ΓòÉΓòÉΓòÉ 5.1. The APL2/2 Package ΓòÉΓòÉΓòÉ
  734.  
  735. The APL2/2 program is supplied on 3╨╗-inch diskettes. It must be loaded onto the 
  736. hard disk of a machine capable of running OS/2 Version 2.0 or later. Read this 
  737. entire chapter before proceeding with the installation of APL2/2. 
  738.  
  739.  
  740. ΓòÉΓòÉΓòÉ 5.2. Installation Overview ΓòÉΓòÉΓòÉ
  741.  
  742. APL2 for OS/2 uses the IBM Software Installer for installation. Installation is 
  743. supported from either diskette or a Local Area Network (LAN) server. 
  744. Context-sensitive help is available at all times during the install process. 
  745.  
  746.  
  747. ΓòÉΓòÉΓòÉ 5.3. Installing APL2/2 on Your Workstation ΓòÉΓòÉΓòÉ
  748.  
  749. This section contains information that you need for: 
  750.  
  751. o Installing APL2/2 from a Diskette Drive 
  752. o Setting Up and Installing from a LAN Server 
  753. o Installing the APL2 Fonts 
  754. o Accessing the Online Documentation 
  755. o Changing CONFIG.SYS 
  756. o Binding the APL2 to DB2 Interface 
  757.  
  758.  
  759. ΓòÉΓòÉΓòÉ 5.3.1. Installing APL2/2 from a Diskette Drive ΓòÉΓòÉΓòÉ
  760.  
  761. To install APL2/2 from a diskette drive: 
  762.  
  763.  1. Insert disk #1 into a diskette drive (in this example drive A is used). 
  764.  
  765.  2. Type the following on the OS/2 command line: 
  766.  
  767.         A:\INSTALL
  768.  
  769.  3. Press Enter. 
  770.  
  771.  4. Follow the on-screen prompts. 
  772.  
  773.  
  774. ΓòÉΓòÉΓòÉ 5.3.2. Setting Up and Installing from a LAN Server ΓòÉΓòÉΓòÉ
  775.  
  776. If you have purchased multiple licenses of APL2/2, you might want to consider 
  777. placing it on a LAN server for easier access. To do this, perform the following 
  778. steps: 
  779.  
  780.  1. Create a directory on the LAN server to store the APL2/2 files. For 
  781.     example: 
  782.  
  783.         mkdir j:\apl2inst
  784.  
  785.  2. Copy each APL2/2 diskette into this directory. You can do this using the 
  786.     OS/2 xcopy command. For example: 
  787.  
  788.         xcopy a: j:\apl2inst /s
  789.  
  790.  3. Repeat step 2 for each diskette. 
  791.  
  792.  4. Give all licensed users access to the LAN drive you copied the diskettes to 
  793.     (in this example, the J drive). 
  794.  
  795.     After performing these steps, users with access to the LAN drive can access 
  796.     the alias drive\directory and install APL2/2 by typing: 
  797.  
  798.         INSTALL
  799.  
  800.     Your LAN users are now ready to use APL2/2. 
  801.  
  802.  
  803. ΓòÉΓòÉΓòÉ 5.3.3. Installing the APL2 Fonts ΓòÉΓòÉΓòÉ
  804.  
  805. The installation tool does not install the APL2 fonts. You must install these 
  806. yourself. 
  807.  
  808. The font files reside in the FONTS subdirectory of the directory into which you 
  809. installed the product. The files are called: 
  810.  
  811. o APL2INFO.FON 
  812. o COURAPL.AFM 
  813. o COURAPLB.AFM 
  814. o APL2ITAL.AFM 
  815. o APL2NORM.AFM 
  816. o COURAPL.PFB 
  817. o COURAPLB.PFB 
  818. o APL2ITAL.PFB 
  819. o APL2NORM.PFB 
  820.  
  821. APL2INFO.FON is a bitmap font used for the online documentation. The 
  822. APL2xxxx.AFM files are PostScript Type 1 fonts and are used by the session 
  823. manager, editor, and print services. The APL2xxxx.PFB files are part of the 
  824. PostScript fonts; you do not install them separately. 
  825.  
  826. The installation procedure is as follows: 
  827.  
  828.  1. Open the Font Palette that is found in the System Setup folder inside the 
  829.     OS/2 System folder. 
  830.  2. Select Edit font... 
  831.  3. Select Add. 
  832.  4. Enter the path where the font can be found, that is, C:\APL2OS2\FONTS 
  833.  5. Select Add.... 
  834.  6. The Add New Font dialog appears, with the .FON and .AFM files listed. Of 
  835.     the fonts you see, select all except AP124FNT.FON. 
  836.  7. The directory to copy the font files to should default to the correct 
  837.     directory. Do not change it. 
  838.  8. Select Add. 
  839.  9. Exit the font palette Edit Font dialog. The fonts are not available until 
  840.     you have exited. 
  841.  
  842. Note:  Under OS/2 2.0 you may need to install the fonts one at a time. Simply 
  843.        repeat the Add New Font portion of the procedure for each file. 
  844.  
  845.  
  846. ΓòÉΓòÉΓòÉ 5.3.4. Accessing the Online Documentation ΓòÉΓòÉΓòÉ
  847.  
  848. When you install APL2/2, the online documentation is automatically installed in 
  849. the HELP subdirectory of the main installation directory. See the read.me file 
  850. for a complete list of the documentation provided. You can access this 
  851. information from either the Desktop or from the OS/2 command line. 
  852.  
  853. To access the information from the Desktop, double-click on the APL2/2 folder 
  854. to open it, and then double-click on a document object. 
  855.  
  856. Note:  The APL2INFO.FON font must be installed before viewing the online 
  857. documents or you cannot display APL characters. 
  858.  
  859.  
  860. ΓòÉΓòÉΓòÉ 5.3.5. Changing CONFIG.SYS ΓòÉΓòÉΓòÉ
  861.  
  862. If you choose not to have the install program modify your CONFIG.SYS file, you 
  863. need to make the following changes for APL2/2 to run correctly. The examples 
  864. assume a top-level directory of C:\APL2OS2. 
  865.  
  866.  1. Add the following directory to your LIBPATH: C:\APL2OS2\DLL 
  867.  2. Add the following directory to your PATH: C:\APL2OS2\BIN 
  868.  3. Add the following directory to your DPATH: C:\APL2OS2\FONTS 
  869.  4. Add the following directory to your HELP: C:\APL2OS2\HELP 
  870.  5. Add the following directory to your BOOKSHELF: C:\APL2OS2\HELP 
  871.  
  872.  
  873. ΓòÉΓòÉΓòÉ 5.3.6. Binding the APL2 to DB2 Interface ΓòÉΓòÉΓòÉ
  874.  
  875. If APL2 is to be used to communicate with DB2, the APL2 packages must be bound 
  876. to DB2. 
  877.  
  878. A command file, apldb2.cmd, is provided to do the bind processing. It requires 
  879. that DB2 be started, and that the three APL2 bind files (apldb2cs.bnd, 
  880. apldb2rr.bnd, and apldb2ur.bnd) be in the current directory. apldb2.cmd and the 
  881. bind files are placed in the APL2 \bin directory during the APL2 install. 
  882.  
  883. apldb2.cmd must be run once for each DB2 database that is accessed by APL2. The 
  884. database name is passed as the argument to apldb2.cmd. Note that it is assumed 
  885. that the DB2 file sqlbind.exe is in the user's current path. If this is not the 
  886. case, the command file can be modified to add path information to the bind 
  887. commands. 
  888.  
  889.  
  890. ΓòÉΓòÉΓòÉ 5.4. APL2 Keyboard Support ΓòÉΓòÉΓòÉ
  891.  
  892. This section describes the keyboard support provided for APL2/2. For more 
  893. information about how to customize your keyboard, see Using the Session 
  894. Manager. 
  895.  
  896. o APL2/2 Keyboard Layouts 
  897. o Keyboard Keycaps 
  898. o Keyboard Decals 
  899.  
  900.  
  901. ΓòÉΓòÉΓòÉ 5.4.1. APL2/2 Keyboard Layouts ΓòÉΓòÉΓòÉ
  902.  
  903. Several standard APL2 keyboard layouts are provided with this product. You can 
  904. choose one of these or design your own. The keyboard layout can be changed 
  905. during your APL2 session, and is retained across sessions. 
  906.  
  907. To select a keyboard layout, choose "Select Keyboard" from the session manager 
  908. "Options" menu. Both standard (APL on/off) and union keyboard layouts are 
  909. available, and the defaults are dynamically reconfigured based on your keyboard 
  910. and OS/2 country and code page settings. 
  911.  
  912. To see the key assignments, or to modify them, choose "Modify Keyboard" from 
  913. the session manager "Options" menu. The layout displayed by default is your 
  914. currently selected one, but all others are available in the "Layout name" 
  915. drop-down combo box. 
  916.  
  917. Union keyboard layouts provide standard ASCII characters in the unshifted and 
  918. Shift keyboard states, and special APL characters on the Ctrl and Alt shifts. 
  919. This permits intermixed keying of APL and non-APL characters. 
  920.  
  921. Traditional APL keyboards include an APL on/off key which switches the keyboard 
  922. between an APL mode and an ASCII mode. In APL mode, ASCII characters are 
  923. available only if they are also used by APL, and they appear (by default) on 
  924. the keys traditionally used by APL keyboards, which are usually different from 
  925. the normal OS/2 assignments. 
  926.  
  927. APL2/2 uses Ctrl-Backspace as the APL on/off key. Ctrl-Backspace still switches 
  928. APL on or off when using a union keyboard, but that basically indicates only 
  929. whether all characters, or only the non-APL subset, should be accepted from the 
  930. keyboard. European users should note, however, that in all layouts "dead" keys 
  931. are disabled when the keyboard is in APL mode. 
  932.  
  933. For reference information on the positions of characters in the APL2 character 
  934. set, see APL2 Programming: Language Reference. For full details of keyboard 
  935. layouts and key assignments, see the "Modify Keyboard" dialog accessible via 
  936. "Options" from the session manager window. 
  937.  
  938. See APL2/2 Presentation Manager Services for more information about APL2/2's 
  939. keyboard handler. 
  940.  
  941.  
  942. ΓòÉΓòÉΓòÉ 5.4.2. Keyboard Keycaps ΓòÉΓòÉΓòÉ
  943.  
  944. You can order sets of plastic replacement keycaps that correspond to the 
  945. APL2/PC version of your keyboard layout. The keycaps work on 101- and 
  946. 102-version keyboards. The keycaps are: See Keycap ordering information. 
  947.  
  948. The base set, part number 1395624, is needed to complete each of the upgrade 
  949. sets; part numbers 1397152, 1397153, and 1397154 are supplemental to the US/UK 
  950. base set. 
  951.  
  952.  
  953. ΓòÉΓòÉΓòÉ 5.4.2.1. Keycap ordering information ΓòÉΓòÉΓòÉ
  954.  
  955.  
  956. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  957.  
  958.  Item 
  959.  
  960.  
  961. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  962.  
  963. Form Number 
  964.  
  965.  
  966. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  967.  
  968. Part Number 
  969.  
  970.  
  971. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  972.  
  973. APL2 Keycaps, US/UK base set 
  974.  
  975.  
  976. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  977.  
  978. SX80-0270 
  979.  
  980.  
  981. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  982.  
  983. 1395624 
  984.  
  985.  
  986. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  987.  
  988. APL2 Keycaps, German upgrade 
  989.  
  990.  
  991. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  992.  
  993. SX23-0452 
  994.  
  995.  
  996. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  997.  
  998. 1397152 
  999.  
  1000.  
  1001. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  1002.  
  1003. APL2 Keycaps, French upgrade 
  1004.  
  1005.  
  1006. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  1007.  
  1008. SX23-0453 
  1009.  
  1010.  
  1011. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  1012.  
  1013. 1397153 
  1014.  
  1015.  
  1016. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  1017.  
  1018. APL2 Keycaps, Italian upgrade 
  1019.  
  1020.  
  1021. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  1022.  
  1023. SX23-0454 
  1024.  
  1025.  
  1026. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  1027.  
  1028. 1397154 
  1029.  
  1030.  
  1031. ΓòÉΓòÉΓòÉ 5.4.3. Keyboard Decals ΓòÉΓòÉΓòÉ
  1032.  
  1033. Decals with the APL2 character set for IBM keyboards are included with this 
  1034. product. Carefully peel each decal away from the backing sheet and place it on 
  1035. the appropriate key. Note that some decals (those for Alternate-shift 
  1036. characters) go on the fronts of the keys, and that not all the decals are 
  1037. needed for some keyboards. For a French keyboard layout, which has the numeric 
  1038. keys in the shifted position, you need to cut the decals for these keys to move 
  1039. the APL2 characters to the lowercase position. 
  1040.  
  1041. Note:  Additional sets of decal sheets can be ordered from IBM as APL2 Keyboard 
  1042.        Decals, SC33-0604. 
  1043.  
  1044.  
  1045. ΓòÉΓòÉΓòÉ 5.5. Customizing APL2/2 ΓòÉΓòÉΓòÉ
  1046.  
  1047. This section describes how you can customize your APL2 session during 
  1048. installation. 
  1049.  
  1050. o APL2.CMD 
  1051. o The APL2/2 SVP Parameter File 
  1052. o The SVP Profile 
  1053. o Modifying the APL2/2 Desktop Object 
  1054. o APL2/2 and TCP/IP 
  1055.  
  1056.  
  1057. ΓòÉΓòÉΓòÉ 5.5.1. APL2.CMD ΓòÉΓòÉΓòÉ
  1058.  
  1059. The installation program for APL2/2 builds a REXX command file. Assuming a 
  1060. default install directory of C:\APL2OS2, the following is an example of what 
  1061. the file contains with a description added for each line: See REXX command 
  1062. file. 
  1063.  
  1064. If you want to specify additional parameters on every invocation of APL2/2, 
  1065. they can be added to this file in the following ways: 
  1066.  
  1067. o The environment variable that represents the parameter can be set in this 
  1068.   file. For example, to specify an initial workspace size of 10M, add the 
  1069.   following line: 
  1070.  
  1071.        'SET APLWS=10M'
  1072.  
  1073. o The parameter can be added to the line that invokes APL2/2. Using the example 
  1074.   of workspace size mentioned above, modify the line as follows: 
  1075.  
  1076.        'aosapl2.exe -ws 10m' parms
  1077.  
  1078.   Be sure to retain the REXX variable parms at the end of the line to allow any 
  1079.   extra parameters to be specified on the command line (see also Modifying the 
  1080.   APL2/2 Desktop Object). 
  1081.  
  1082. Note:  If you have chosen not to install the REXX component of OS/2, you need 
  1083. to convert this file to standard OS/2 batch language syntax. 
  1084.  
  1085.  
  1086. ΓòÉΓòÉΓòÉ 5.5.1.1. REXX command file ΓòÉΓòÉΓòÉ
  1087.  
  1088.  
  1089. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  1090.  
  1091.  
  1092. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  1093.  
  1094.  
  1095. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  1096.  
  1097. /* APL2 Invocation command file */ 
  1098.  
  1099.  
  1100. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  1101.  
  1102. Identifies this as REXX 
  1103.  
  1104.  
  1105. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  1106.  
  1107. '@echo off' 
  1108.  
  1109.  
  1110. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  1111.  
  1112. Suppresses echoing of lines 
  1113.  
  1114.  
  1115. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  1116.  
  1117. arg parms 
  1118.  
  1119.  
  1120. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  1121.  
  1122. Captures command line arguments 
  1123.  
  1124.  
  1125. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  1126.  
  1127. 'SET APL00001=C:\APL2OS2\WSLIB1' 
  1128.  
  1129.  
  1130. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  1131.  
  1132. Sets up public workspace library 1 
  1133.  
  1134.  
  1135. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  1136.  
  1137. 'SET APL00002=C:\APL2OS2\WSLIB2' 
  1138.  
  1139.  
  1140. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  1141.  
  1142. Sets up public workspace library 2 
  1143.  
  1144.  
  1145. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  1146.  
  1147. 'SET APL01001=.\' 
  1148.  
  1149.  
  1150. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  1151.  
  1152. Sets default private library 
  1153.  
  1154.  
  1155. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  1156.  
  1157. 'SET APLP11=C:\APL2OS2\BIN\APLNM011.NAM' 
  1158.  
  1159.  
  1160. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  1161.  
  1162. Sets default processor 11 NAMES file 
  1163.  
  1164.  
  1165. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  1166.  
  1167. 'aosapl2.exe 'parms 
  1168.  
  1169.  
  1170. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  1171.  
  1172. Invokes APL2/2 with any args 
  1173.  
  1174.  
  1175. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  1176.  
  1177. exit 
  1178.  
  1179.  
  1180. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  1181.  
  1182.  
  1183. ΓòÉΓòÉΓòÉ 5.5.2. The APL2/2 SVP Parameter File ΓòÉΓòÉΓòÉ
  1184.  
  1185. The APL2/2 Shared Variable Processor (SVP) uses a parameter file to set some 
  1186. initialization options. The APL2SVPPARMS environment variable can be used to 
  1187. specify the name and, optionally, the location of this file. If this 
  1188. environment variable is not set, the default file name is apl2svp.prm. This 
  1189. file is searched for in the following sequence: 
  1190.  
  1191.  1. In the path supplied along with the file name in the APL2SVPPARMS 
  1192.     environment variable. 
  1193.  
  1194.  2. In the current directory used by the SVP. This is either the directory from 
  1195.     which APL2/2 was invoked, or the directory from which the SVP Trace window 
  1196.     or any independent processor was invoked, whichever was started first. 
  1197.  
  1198.  3. In the list of directories specified in the DPATH environment variable. 
  1199.  
  1200. The file uses the following syntax: 
  1201.  
  1202. keyword=value [value...]
  1203.  
  1204. Blank lines or lines with an asterisk in the first column are ignored. In the 
  1205. case of keywords that accept more than one value, the values can be separated 
  1206. by a comma, by spaces, or by both. 
  1207.  
  1208. The keywords that can be specified are: 
  1209.  
  1210. PROCS     Specifies the maximum number of processors that can be signed on to 
  1211.           the SVP at one time. 
  1212.  
  1213. VARS      Specifies the maximum number of variables that can be shared at one 
  1214.           time. 
  1215.  
  1216. MAXSM     Specifies the maximum amount of memory, in bytes, that can be used 
  1217.           for shared variable data. 
  1218.  
  1219. MAXSV     Specifies the maximum amount of memory, in bytes, that can be used 
  1220.           for any single shared variable. 
  1221.  
  1222. NOTRACE   Specifies a list of processor IDs that are not traced by the SVP 
  1223.           trace facility. An asterisk may be specified to signify that all 
  1224.           processors are not traced. 
  1225.  
  1226. The default file apl2svp.prm is provided as follows: 
  1227.  
  1228.     * Sample svp parms file
  1229.     PROCS=100
  1230.     VARS=100
  1231.     MAXSM=10000000
  1232.     MAXSV=1000000
  1233.     NOTRACE=1 101 120
  1234.     *
  1235.  
  1236. Notes: 
  1237.  
  1238.  1. Although there is no enforced maximum allowed value for MAXSM, this can be 
  1239.     limited by the size of memory or the OS/2 swapper space available. 
  1240.  
  1241.  2. If the SVP parms file is not found, defaults for PROCS, VARS, MAXSM, and 
  1242.     MAXSV are set as noted in the sample file above and all processors are 
  1243.     traced. 
  1244.  
  1245.  
  1246. ΓòÉΓòÉΓòÉ 5.5.3. The SVP Profile ΓòÉΓòÉΓòÉ
  1247.  
  1248. For information about customizing the SVP profile, see Processor Profile 
  1249. Structure. 
  1250.  
  1251.  
  1252. ΓòÉΓòÉΓòÉ 5.5.4. Modifying the APL2/2 Desktop Object ΓòÉΓòÉΓòÉ
  1253.  
  1254. The install program creates a desktop object in the APL2 for OS/2 folder that 
  1255. can be used to invoke APL2/2. You might want to customize this object as 
  1256. follows: 
  1257.  
  1258.  1. Open the Settings notebook for the object by clicking mouse button 2 on the 
  1259.     icon, then clicking mouse button 1 on the arrow next the word Open, then 
  1260.     selecting Settings. 
  1261.  
  1262.  2. On the Program page of the Settings notebook, you might want to add APL2/2 
  1263.     invocation parameters in the Parameters field. You can also specify "[ ]" 
  1264.     if you want to be prompted for additional parameters. 
  1265.  
  1266.  3. On the Session page, you may want to click on the box labeled Start 
  1267.     minimized if you want the APL2/2 interpreter window to be minimized on 
  1268.     invocation. 
  1269.  
  1270.  4. On the Window page, you might want to click on the box labeled: Create new 
  1271.     window under Object open behavior. This allows you to use the object to 
  1272.     start multiple concurrent APL2/2 sessions. 
  1273.  
  1274.  
  1275. ΓòÉΓòÉΓòÉ 5.5.5. APL2/2 and TCP/IP ΓòÉΓòÉΓòÉ
  1276.  
  1277. APL2/2 uses TCP/IP for OS/2 to provide cooperative processing facilities. The 
  1278. Shared Variable Processor (SVP) contains references to certain TCP/IP socket 
  1279. calls necessary for this function. The SVP routines are supplied in the form of 
  1280. a dynamic link library (DLL). Because this DLL has a load-time dependency on 
  1281. TCP/IP, two versions are shipped with APL2/2 and copied to the \dll 
  1282. subdirectory where APL2/2 was installed. The two versions are named 
  1283. apl2svpt.dll (TCP/IP enabled) and apl2svpn.dll (TCP/IP disabled). The install 
  1284. program tries to detect whether TCP/IP has been installed, and makes a copy of 
  1285. the appropriate version, which is then named apl2svp.dll. If for some reason 
  1286. the install program incorrectly detects the presence of TCP/IP, or if you later 
  1287. install or uninstall TCP/IP on your system, you might need to copy the 
  1288. appropriate SVP DLL file. For example, if you install TCP/IP after installing 
  1289. APL2/2, you could do the following: 
  1290.  
  1291.  1. Change directory to the \dll subdirectory where APL2/2 was installed: 
  1292.  
  1293.            cd c:\apl2os2\dll
  1294.  
  1295.  2. Issue the following OS/2 command: 
  1296.  
  1297.            copy apl2svpt.dll apl2svp.dll
  1298.  
  1299. This enables APL2/2 to use the cooperative processing features (see Cooperative 
  1300. Processing). 
  1301.  
  1302.  
  1303. ΓòÉΓòÉΓòÉ 6. Invoking APL2/2 ΓòÉΓòÉΓòÉ
  1304.  
  1305. This chapter describes the APL2 environment created on your OS/2 desktop, 
  1306. techniques you can use to create that environment, options you can pass to the 
  1307. APL2 product, and environment variables that affect the way it behaves. 
  1308.  
  1309. An "APL2 for OS/2" folder was created on your desktop when you installed the 
  1310. product. When you open that folder, you find documentation and program icons. 
  1311. APL2 is normally started by opening the "APL2/2" program icon. 
  1312.  
  1313. o OS/2 Windows Opened by APL2 
  1314. o Invocation Syntax and Environment Variables 
  1315.  
  1316.  
  1317. ΓòÉΓòÉΓòÉ 6.1. OS/2 Windows Opened by APL2 ΓòÉΓòÉΓòÉ
  1318.  
  1319. When APL2 is started, three windows are typically created, though this can be 
  1320. affected by the way that you start the product. The windows are included in the 
  1321. system Window List, and may or may not be displayed on the desktop: 
  1322.  
  1323. o An APL2 session manager window is normally displayed. See Using the Session 
  1324.   Manager for details of its usage. This window is not created if the default 
  1325.   -sm on invocation option is overridden. 
  1326.  
  1327. o The interpreter window is opened unless you have issued the APL2 command 
  1328.   directly from another OS/2 command window. (In that case, the original 
  1329.   command window has the behavior discussed here.) The interpreter window is 
  1330.   normally used only to display output from OS/2 commands invoked through )HOST 
  1331.   or AP 100. If APL2 is invoked with -sm off, but the input or output have not 
  1332.   been redirected, then APL session input or output goes through this window. 
  1333.   Certain severe error messages are also displayed here. Ctrl-Break can be used 
  1334.   from this window to interrupt the interpreter. Closing the window terminates 
  1335.   the APL2 session. (But normally signals and session termination are 
  1336.   controlled from the session manager window.) 
  1337.  
  1338. o The SVP Trace window is opened if the SVP was not already active. This window 
  1339.   can be used to monitor APL2 shared variable activity, to obtain information 
  1340.   about processors and shared variables, initiate the programs used for 
  1341.   cooperative processing, and to clean up after processors that may not have 
  1342.   terminated normally. See the help provided within the window for details of 
  1343.   its usage. For more information, see SVP Trace Facility. 
  1344.  
  1345. Both the interpreter window and the SVP Trace window are often minimized or 
  1346. hidden in normal usage. When APL2 is started from the APL2/2 folder, that 
  1347. folder restores the interpreter window to its last known state. The SVP trace 
  1348. window is always reopened in the state it was in when it was last closed. 
  1349.  
  1350. Additional windows can be opened by applications that are started automatically 
  1351. when APL2 is invoked. 
  1352.  
  1353.  
  1354. ΓòÉΓòÉΓòÉ 6.2. Invocation Syntax and Environment Variables ΓòÉΓòÉΓòÉ
  1355.  
  1356. Most interpreter options can be specified as either operating system 
  1357. environment variables or parameters on the command that starts APL2. 
  1358.  
  1359. o Parameter keywords can be entered in uppercase, lowercase, or mixed case, and 
  1360.   must be marked with a leading slash or hyphen, followed immediately by the 
  1361.   keyword. 
  1362.  
  1363. o Environment variable names match the parameter keywords, but with a prefix of 
  1364.   APL. Environment variables must be set before invoking APL2/2. 
  1365.  
  1366. Where parameters are specified they override the corresponding environment 
  1367. variables. 
  1368.  
  1369. Note:  All APL2 invocation parameters and environment variables are also passed 
  1370. to any dependent auxiliary processors. Dependent auxiliary processors are 
  1371. auto-started as children of the APL2 interpreter session when the first share 
  1372. offer is made to the auxiliary processor. All command line parameters are 
  1373. passed unmodified to the auxiliary processor, with the exception of the -id 
  1374. parameter, the value of which is adjusted to identify the processor number of 
  1375. the auxiliary processor, followed by the processor number of the parent 
  1376. interpreter session. 
  1377.  
  1378. o Invocation Syntax 
  1379. o Environment Variables 
  1380. o System Dependent Environment Variables 
  1381. o Examples of APL2/2 Invocation 
  1382. o Running APL2/2 in Batch Mode 
  1383.  
  1384.  
  1385. ΓòÉΓòÉΓòÉ 6.2.1. Invocation Syntax ΓòÉΓòÉΓòÉ
  1386.  
  1387.    apl2 [optional parameters]
  1388. where optional parameters are: 
  1389.  
  1390. Invocation 
  1391.  
  1392. Keyword  Description 
  1393.  
  1394. -id procid[,parentid[,pparentid]] 
  1395.          Sets user ID number, as reported by ╨áAI and used when sharing 
  1396.          variables with the session. Is also used to specify a parent and 
  1397.          grandparent ID for APL sessions that are to be subordinate to others. 
  1398.          -id can be set to 1 to 3 positive integers (separated by commas), but 
  1399.          is normally a single integer. 
  1400.  
  1401.          The use of IDs of 1000 or less is not advised unless the session is 
  1402.          being used as an auxiliary processor. The default is the first unused 
  1403.          number above 1000. 
  1404.  
  1405. -input " 'line1' ['line2']..." 
  1406.          Defines the initial lines of input used when APL2 is invoked. Each 
  1407.          line of input is enclosed in single quotation marks and the group of 
  1408.          one or more lines of input is enclosed in double quotes. 
  1409.  
  1410.          All displayable characters can be included within the quoted lines. 
  1411.          Use two single quote marks for each one that is to be treated as part 
  1412.          of the input. 
  1413.  
  1414. -lx {on|off} 
  1415.          Indicates whether the latent expression, ╨áLX, should be executed when 
  1416.          a workspace is )LOADed. 
  1417.  
  1418. -nlt filename 
  1419.          Specifies which national language to use for system commands and 
  1420.          messages. Can be set to the character name of the file that contains 
  1421.          the National Language messages. The default is en_us.nlt (US English). 
  1422.          Other options are: 
  1423.  
  1424.    en_uk.nlt (UK English) 
  1425.    gr_gr.nlt (German) 
  1426.    fr_fr.nlt (French) 
  1427.    it_it.nlt (Italian) 
  1428.  
  1429. -quiet {on|off} 
  1430.          Suppresses display of interpreter output until input is requested. 
  1431.  
  1432.          Input requests satisfied by the APL2 input stack do not reset -quiet 
  1433.          on. Data is placed on the APL2 input stack either by the -input option 
  1434.          or through AP 101. 
  1435.  
  1436. -sm {on|off|piped|n} 
  1437.          Indicates whether a session manager is to be used. If a number is 
  1438.          specified, a variable is offered to the indicated processor. off would 
  1439.          be used for line-by-line I/O devices, or programs which emulate that 
  1440.          behavior, such as typing directly into an OS/2 window. piped is used 
  1441.          for batch processing, whether the session is driven by a file or by 
  1442.          another process. 
  1443.  
  1444. -svplisten {on|off} 
  1445.          Enables automatic startup of the port server. 
  1446.  
  1447. -svptrace {on|off|log|both} 
  1448.          Enables display and logging of SVP trace events. 
  1449.  
  1450. -ws initial[,maximum[,increment]] 
  1451.          Workspace size. This can be either a single value for a static size, 
  1452.          or up to three values to request an expandable workspace. 
  1453.  
  1454.          Each of the values provided are of the form: 
  1455.  
  1456.                    integer[k|m]
  1457.  
  1458.          where k and m indicate kilobytes and megabytes, respectively. 
  1459.  
  1460.          If increment, or both maximum and increment, are omitted, they default 
  1461.          to initial. The default for initial is 2M. The system increases any 
  1462.          initial value less than 32K. 
  1463.  
  1464.          Here are some examples: 
  1465.  
  1466.                   -ws 5m
  1467.  
  1468.          The session is run with a 5 megabyte workspace. WS FULL is reported if 
  1469.          this is not enough. 
  1470.  
  1471.                   -ws 2m,7m
  1472.  
  1473.          The session begins with a 2 megabyte workspace. Since the increment 
  1474.          defaults to the initial value, this is expanded to 4 megabytes, 6 
  1475.          megabytes, and finally 7 megabytes as needed to avoid WS FULL. 
  1476.  
  1477.                   -ws 500k,1m,100k
  1478.  
  1479.          The session begins with a 500 kilobyte workspace. This is expanded as 
  1480.          needed, 100 kilobytes at a time, but never exceeding 1 megabyte. 
  1481.  
  1482.          Note:  The maximum size specified or defaulted should never exceed the 
  1483.          available free space on the drive that contains SWAPPER.DAT. 
  1484.  
  1485.  
  1486. ΓòÉΓòÉΓòÉ 6.2.2. Environment Variables ΓòÉΓòÉΓòÉ
  1487.  
  1488. Environment variables can be set prior to invoking APL2 to control certain 
  1489. aspects of the session. To set an environment variable, enter the following: 
  1490.  
  1491.     SET variable=value
  1492. Where variable is the name of the environment variable and Value is the 
  1493. assigned content. Environment variables under OS/2 are always folded to 
  1494. uppercase, but the values are case sensitive. Any auxiliary processors that are 
  1495. automatically started by the APL2/2 session inherit the environment variables 
  1496. set by the parent. SET commands can be issued from the OS/2 command line in the 
  1497. OS/2 session where APL2/2 is invoked. They can also be added to the apl2.cmd 
  1498. invocation file (see Customizing APL2/2). 
  1499.  
  1500. In addition to the variables listed here, the interpreter invocation options 
  1501. can be specified as environment variables. The variable names match the 
  1502. parameter keywords, but with a prefix of APL. Where parameters are specified, 
  1503. they override the corresponding environment variable. 
  1504.  
  1505. APL2SMKEY      Name of the shared variable key. This value is used to build 
  1506.                unique names for the resources used by the Shared Variable 
  1507.                Processor. The default is apl2svp. 
  1508.  
  1509. APL2SVPLOG     Name of the Shared Variable Processor trace file. This can be a 
  1510.                simple file name or a fully qualified path and file name. The 
  1511.                default is apl2svp.trc. 
  1512.  
  1513. APL2SVPPARMS   Name of the file that contains the Shared Variable Processor 
  1514.                initialization parameters. This can be a simple file name or a 
  1515.                fully qualified path and file name. The default is apl2svp.prm. 
  1516.  
  1517. APL2SVPPRF     Name of the SVP profile. This file contains entries that 
  1518.                identify and authorize remote processors and independent local 
  1519.                processors. This can be a simple file name or a fully qualified 
  1520.                path and file name. The default is apl2svp.prf. 
  1521.  
  1522. APL207FL       Path to the AP 207 vector font files. 
  1523.  
  1524. APLnnnnn       Where nnnnn is a five-digit number such as 01234. Used to 
  1525.                resolve library numbers with the system commands. A separate 
  1526.                environment variable must be defined for each library accessed 
  1527.                by number. Is set to a directory path specification. 
  1528.  
  1529.                For more information, see Library Specification and the LIBS 
  1530.                function in The OS2 Workspace. 
  1531.  
  1532. APLP11         Name of the default processor 11 NAMES file. 
  1533.  
  1534.  
  1535. ΓòÉΓòÉΓòÉ 6.2.3. System Dependent Environment Variables ΓòÉΓòÉΓòÉ
  1536.  
  1537. The following list describes the operating system environment variables on 
  1538. which APL2 depends. 
  1539.  
  1540. DPATH          Sequence of directories used to search for nonexecutable data 
  1541.                files 
  1542.  
  1543. HOSTNAME       TCP/IP hostname used for cooperative processing 
  1544.  
  1545. PATH           Sequence of directories used to search for an executable file or 
  1546.                command 
  1547.  
  1548. TZ             Time zone in effect 
  1549.  
  1550.  
  1551. ΓòÉΓòÉΓòÉ 6.2.4. Examples of APL2/2 Invocation ΓòÉΓòÉΓòÉ
  1552.  
  1553. The following sections provide examples of how to invoke APL2/2. 
  1554.  
  1555. o From the OS/2 Desktop, Using a Mouse 
  1556. o From the OS/2 Desktop, Using the Keyboard 
  1557. o From an OS/2 Window 
  1558. o To Drive an APL Application from the Desktop 
  1559.  
  1560.  
  1561. ΓòÉΓòÉΓòÉ 6.2.4.1. From the OS/2 Desktop, Using a Mouse ΓòÉΓòÉΓòÉ
  1562.  
  1563.  1. Double-click mouse button 1 on the "APL2 for OS/2" icon on the desktop. 
  1564.     This opens the APL2/2 folder. 
  1565.  
  1566.  2. Double-click mouse button 1 on the "APL2/2" icon within that folder. 
  1567. This starts an APL2 session using any previously assigned options. To change 
  1568. those options, single-click mouse button 2 on the "APL2/2" icon and select 
  1569. Settings. 
  1570.  
  1571.  
  1572. ΓòÉΓòÉΓòÉ 6.2.4.2. From the OS/2 Desktop, Using the Keyboard ΓòÉΓòÉΓòÉ
  1573.  
  1574.  1. Alt+Shift+Tab followed by Ctrl+\ takes you to the desktop and deselects all 
  1575.     objects. 
  1576.  
  1577.  2. Use the Arrow keys to move focus to the "APL2 for OS/2" icon, then the 
  1578.     Enter key to open it. 
  1579.  
  1580.  3. Use the Arrow keys to move focus to the "APL2/2" program icon, then the 
  1581.     Enter key to open it. 
  1582. This starts an APL2 session using any previously assigned options. To change 
  1583. those options, press Shift-F10 while the "APL2/2" icon has focus, then 
  1584. Right-arrow and Enter to open the Settings notebook. 
  1585.  
  1586.  
  1587. ΓòÉΓòÉΓòÉ 6.2.4.3. From an OS/2 Window ΓòÉΓòÉΓòÉ
  1588.  
  1589.  1. Switch to the drive and directory that you want to use as the working 
  1590.     directory during the APL2 session. Typically this is the directory where 
  1591.     your private workspaces are stored. For example: 
  1592.  
  1593.         [C:\]d:
  1594.         [D:\]cd wslib
  1595.         [D:\WSLIB]
  1596.  
  1597.  2. Set any needed environment variables that are not already set (perhaps by 
  1598.     CONFIG.SYS) and are not set automatically by the command file you are going 
  1599.     to use. (You cannot change these after entering APL2.) The following 
  1600.     example defines APL libraries 50 and 1002, pointing library 1002 to the 
  1601.     current directory. 
  1602.  
  1603.         [D:\WSLIB]set apl00050=e:\lib50
  1604.         [D:\WSLIB]set apl01002=.\
  1605.         [D:\WSLIB]
  1606.  
  1607.  3. Start the APL2 session, providing any needed options. This example sets a 
  1608.     workspace size of 5 megabytes and suppresses automatic execution of ╨áLX 
  1609.     expressions in workspaces that are loaded: 
  1610.  
  1611.         [D:\WSLIB]apl2 /ws 5m /lx off
  1612.  
  1613.  
  1614. ΓòÉΓòÉΓòÉ 6.2.4.4. To Drive an APL Application from the Desktop ΓòÉΓòÉΓòÉ
  1615.  
  1616. The provider of the application can do the following: 
  1617.  
  1618.  1. Create a program icon. You can copy an existing one or drag the system's 
  1619.     program template to another directory. 
  1620.  
  1621.  2. Fill in the full path and file name of the APL2 program. This is 
  1622.     AOSAPL2.EXE in the \BIN subdirectory of the directory where the APL2 
  1623.     product was installed. 
  1624.  
  1625.  3. Select a working directory based on any needs the application may have. 
  1626.  
  1627.  4. Provide optional parameters as needed. For example: 
  1628.  
  1629.         -quiet on -sm off -ws 4m -input "')LOAD ''applic.APL'''"
  1630.  
  1631.     Note that the OS/2 filename form of the )LOAD command is used in the -input 
  1632.     option. Using this form avoids any dependencies on environment variables. 
  1633.     Drive and directory information can be included if the workspace is not 
  1634.     stored in the working directory. 
  1635.  
  1636. Assuming that the workspace contains a latent expression, it begins executing 
  1637. automatically when the user opens the program object. 
  1638.  
  1639.  
  1640. ΓòÉΓòÉΓòÉ 6.2.5. Running APL2/2 in Batch Mode ΓòÉΓòÉΓòÉ
  1641.  
  1642. Batch mode enables you to redirect APL2/2 session input and output. In this 
  1643. mode, input is redirected from text files containing what would normally be the 
  1644. keyboard input during an interactive session. The resulting output can then be 
  1645. redirected to another file or process. For example, suppose that the file 
  1646. session.in contains the following input lines: 
  1647.  
  1648. 2+2
  1649. )OFF
  1650.  
  1651. Suppose APL2 is invoked with this as redirected input, and the output is 
  1652. redirected to a file called session.out, using: 
  1653.  
  1654. apl2 -sm piped < session.input > session.output
  1655.  
  1656. The session.out file then contains the session manager output: 
  1657.  
  1658.  ...
  1659. CLEAR WS
  1660.       2+2
  1661. 4
  1662.  
  1663. If the input file ends before an )OFF or )CONTINUE command is encountered in 
  1664. the input file, the session is terminated with an )OFF command. 
  1665.  
  1666.  
  1667. ΓòÉΓòÉΓòÉ 7. General Information ΓòÉΓòÉΓòÉ
  1668.  
  1669. This chapter discusses how to use APL2. 
  1670.  
  1671. o The APL2 Interpreter 
  1672. o An Example of the Use of APL2 
  1673. o Characteristics of APL2 
  1674. o Workspaces and Libraries 
  1675.  
  1676.  
  1677. ΓòÉΓòÉΓòÉ 7.1. The APL2 Interpreter ΓòÉΓòÉΓòÉ
  1678.  
  1679. The APL2 interpreter takes one APL2 statement at a time, converts it to machine 
  1680. instructions (the computer's internal language), executes it, and then proceeds 
  1681. to the next line. In contrast to program compilers that convert an entire 
  1682. program to machine language before executing any statements, APL2 allows you a 
  1683. high degree of interaction with the computer. If something you enter is 
  1684. invalid, you get quick feedback on the problem before you go any further. This 
  1685. also yields high productivity gains. 
  1686.  
  1687.  
  1688. ΓòÉΓòÉΓòÉ 7.2. An Example of the Use of APL2 ΓòÉΓòÉΓòÉ
  1689.  
  1690. A statement entered at the keyboard can contain numbers or symbols, such as + - 
  1691. ╤ù ╨Ä, or names formed from valid combinations of letters (as described in APL2 
  1692. Programming: Language Reference). The numbers and special symbols stand for the 
  1693. primitive objects and functions of APL2-primitive in the sense that their 
  1694. meanings are permanently fixed, and therefore understood by the APL2 system 
  1695. without further definition. A name, however, has no significance until a 
  1696. meaning has been assigned to it. 
  1697.  
  1698. Names are used for two major categories of objects. Names can be used for 
  1699. collections of data that are composed of numbers or characters; such a named 
  1700. collection is called a variable. Names can also be used for programs made up of 
  1701. sequences of APL2 statements; such programs are called defined functions and 
  1702. operators. Once they have been established, names of variables and defined 
  1703. operations can be used in statements by themselves or in conjunction with 
  1704. primitive functions and objects. 
  1705.  
  1706. o An Isolated Calculation 
  1707. o Storing Functions and Data 
  1708.  
  1709.  
  1710. ΓòÉΓòÉΓòÉ 7.2.1. An Isolated Calculation ΓòÉΓòÉΓòÉ
  1711.  
  1712. If the work to be done can be adequately specified simply by typing a statement 
  1713. made up of numbers and symbols, names are not required; entering the expression 
  1714. to be evaluated causes the result to be displayed. For example, suppose you 
  1715. want to compare the rates of return on money at a fixed interest rate but with 
  1716. different compounding intervals. For 1000 units at 6% compounded annually, 
  1717. quarterly, monthly, or daily for 10 years, the entry and response for the 
  1718. transaction (assuming a printing precision (╨áPP) equal to 6) looks like this: 
  1719.  
  1720.       ╨áPPΓò£6
  1721.       1000╤ù(1+0.06╨Ä1 4 12 365)*10╤ù1 4 12 365
  1722. 1790.85 1814.02 1819.4 1822.03
  1723.  
  1724. (The largest gain is apparently obtained in going from annual to quarterly 
  1725. compounding; after that the differences are relatively insignificant.) 
  1726.  
  1727. This example illustrates several characteristic features of APL2: familiar 
  1728. symbols such as + - ╤ù ╨Ä are used where possible; symbols are introduced where 
  1729. necessary (as the * for the power function); and a group of numbers can be 
  1730. worked on together. 
  1731.  
  1732.  
  1733. ΓòÉΓòÉΓòÉ 7.2.2. Storing Functions and Data ΓòÉΓòÉΓòÉ
  1734.  
  1735. Although many problems can be solved by typing the appropriate numbers and 
  1736. symbols, the greatest benefits of using APL2 occur when named functions and 
  1737. data are used. Because a single name can refer to a large array of data, using 
  1738. the name is far simpler than typing all of its numbers. Similarly, a defined 
  1739. function, specified by entering its name, can be composed of many individual 
  1740. APL2 statements that would be burdensome to type again and again. 
  1741.  
  1742. Once a function has been defined, or data collected under a name, it is usually 
  1743. desirable to retain the significance of the names for some period of 
  1744. time-perhaps for just a few minutes, but more often for much longer, possibly 
  1745. months or years. For this reason APL2 systems are organized around the idea of 
  1746. a workspace, which might be thought of as a notebook in which all the data 
  1747. items needed during some piece of work are recorded together. An APL2 workspace 
  1748. thus contains defined functions, data structures, and a state indicator. 
  1749.  
  1750.  
  1751. ΓòÉΓòÉΓòÉ 7.3. Characteristics of APL2 ΓòÉΓòÉΓòÉ
  1752.  
  1753. APL2 Programming: Language Reference describes APL2 in detail, giving the 
  1754. meaning of each symbol and discussing the various features of APL2. These 
  1755. details should be considered in light of the major characteristics of APL2, 
  1756. which can be summarized as follows: 
  1757.  
  1758. o The primitive objects of the language are arrays (lists, tables, lists of 
  1759.   tables, and so on). For example, A + B is meaningful for any conformable 
  1760.   arrays A and B, the size of an array (╤åA) is a primitive function, and arrays 
  1761.   can be indexed by arrays, as in A[3 1 4 2]. 
  1762.  
  1763. o The syntax is simple: 
  1764.  
  1765.    - There are only three statement types: name assignment, branch, or 
  1766.      neither). 
  1767.    - There is no function precedence hierarchy. 
  1768.    - Functions have either one, two, or no arguments. 
  1769.    - Primitive functions and defined functions (programs) are treated alike. 
  1770.  
  1771. o The semantic rules are few: 
  1772.  
  1773.    - The definitions of primitive functions are independent of the 
  1774.      representations of data to which they apply. 
  1775.    - All scalar functions are extended to other arrays in the same way-that is, 
  1776.      item by item. 
  1777.    - Primitive functions have no hidden effects (so-called side-effects). 
  1778.  
  1779. o The sequence control is simple: one statement type embraces all types of 
  1780.   branches (conditional, unconditional, computed, and so on), and the 
  1781.   completion of the execution of any function always returns control to the 
  1782.   point of use. 
  1783.  
  1784. o External communications are established by means of variables, which are 
  1785.   shared between an APL2 session and other processors. These processors can be 
  1786.   APL or non-APL programs running on the same system or on another system. 
  1787.   Shared variables are treated both syntactically and semantically like other 
  1788.   variables. A subclass of shared variables-system variables-provides 
  1789.   convenient communications between APL2 programs and their environment. 
  1790.  
  1791. o The usefulness of the primitive functions is vastly expanded by operators, 
  1792.   which modify their behavior in a systematic manner. For example, the 
  1793.   primitive operator, reduction (denoted by /) modifies a function to apply 
  1794.   over all elements of a list, as in +/L for summation of the items of L. The 
  1795.   remaining primitive operators are: 
  1796.  
  1797.    - Scan (running totals, running maxima, and so on) 
  1798.    - The axis operator, which, for example, makes it possible to apply 
  1799.      reduction and scan over a specified axis (rows or columns) of a table 
  1800.    - The each operator, which applies a function to each of the elements of its 
  1801.      arguments 
  1802.    - The outer product, which produces tables of values as in RATE┬░.*YEARS for 
  1803.      an interest table 
  1804.    - The inner product, a generalization of matrix product. 
  1805.  
  1806. o The number of primitive functions and operators is sufficiently small that 
  1807.   each is represented by a single, easily-read and easily-written symbol, yet 
  1808.   the set of primitives embraces operations from simple addition to grading 
  1809.   (sorting) and formatting. 
  1810.  
  1811.  
  1812. ΓòÉΓòÉΓòÉ 7.4. Workspaces and Libraries ΓòÉΓòÉΓòÉ
  1813.  
  1814. The common unit of storage in an APL2 system is the workspace. When in use, a 
  1815. workspace is said to be active, and is in main storage. Part of each workspace 
  1816. is set aside to serve the internal workings of the system; the rest is used, as 
  1817. required, to store items of information and to hold transient information 
  1818. generated during a computation. 
  1819.  
  1820. The names of variables (data items) and defined functions or operators 
  1821. (programs) used in calculations always refer to objects known by those names in 
  1822. the active workspace; information about the progress of program execution is 
  1823. maintained in the state indicator of the active workspace, and control 
  1824. information affecting the form of output is held within the active workspace. 
  1825.  
  1826. Inactive workspaces are stored in libraries (that are OS/2 directories), where 
  1827. they are identified by arbitrary names. The inactive workspaces are typically 
  1828. stored in WSNAME.apl. When required, copies of stored workspaces can be made 
  1829. active, or (if they are stored in an appropriate form) selected information can 
  1830. be copied from them into an active workspace. 
  1831.  
  1832. Transfer files provide a way to store and transport APL objects outside of 
  1833. workspaces. They are particularly useful when transferring workspace objects 
  1834. between different APL2 implementations, because all APL2 products can read 
  1835. transfer files created by any other APL2 product. Transfer files are also used 
  1836. as an alternative to inactive workspaces. Transfer files can have arbitrary 
  1837. names, but the form FILENAME.atf is typically used. 
  1838.  
  1839. Workspaces, libraries, and transfer files are managed by system commands, as 
  1840. described in APL2 Programming: Language Reference. 
  1841.  
  1842. o Library Specification 
  1843. o Explicit File Specifications 
  1844.  
  1845.  
  1846. ΓòÉΓòÉΓòÉ 7.4.1. Library Specification ΓòÉΓòÉΓòÉ
  1847.  
  1848. APL2/2 uses environment variables to define the location of workspaces and 
  1849. transfer files. These variables have the form APLnnnnn, where nnnnn is the 
  1850. library number (left-padded to 5 digits with zeros). The APL2 command file sets 
  1851. the following defaults for libraries unless a different directory structure was 
  1852. selected during installation. 
  1853.  
  1854. o APL00001=C:\APL2OS2\WSLIB1 
  1855. o APL00002=C:\APL2OS2\WSLIB2 
  1856. o APL01001=.\ 
  1857.  
  1858. Other APLnnnnn environment variables can be defined to support additional paths 
  1859. containing workspaces. These definitions can be added to apl2.cmd. For example, 
  1860. specifying: 
  1861.  
  1862. APL02001=d:\hal\wkspaces
  1863.  
  1864. Causes APL2/2 to use the \hal\wkspaces directory whenever a library number of 
  1865. 2001 is used. Then: 
  1866.  
  1867.       )WSID 2001 PLOT
  1868.       )SAVE
  1869.  
  1870. Saves the active workspace in file d:\hal\wkspaces\plot.apl. 
  1871.  
  1872. When system commands are specified with no explicit library number, a default 
  1873. library is determined as follows: 
  1874.  
  1875.  1. If an environment variable APLnnnnn exists, where "nnnnn" matches the first 
  1876.     element of ╨áAI, its value is used as the workspace directory. 
  1877.  
  1878.  2. Else, if the environment variable APL01001 is defined, its value is used. 
  1879.  
  1880.  3. Else, the APL01001 environment variable is automatically set to point to 
  1881.     the current directory, which becomes the default library. 
  1882.  
  1883. The LIBS function (from the OS2 workspace described in The OS2 Workspace) can 
  1884. be used to query the current library definitions and their associated paths. 
  1885. Library definitions cannot be changed from APL2/2. To change library 
  1886. definitions, you must exit APL2/2 and change the APLnnnnn environment variable. 
  1887.  
  1888.  
  1889. ΓòÉΓòÉΓòÉ 7.4.2. Explicit File Specifications ΓòÉΓòÉΓòÉ
  1890.  
  1891. As an alternative to library definitions, you can also specify a file name 
  1892. enclosed in single quotes in place of the workspace name and optional library 
  1893. number. For example: 
  1894.  
  1895.       )LOAD 'd:\hal\wkspaces\plot.apl'
  1896.  
  1897. Notes: 
  1898.  
  1899.  1. If a fully-qualified name is set for the active workspace with )LOAD or 
  1900.     )WSID, then a subsequent )WSID without parameters returns the full name 
  1901.     (including the quotes). 
  1902.  
  1903.  2. The maximum length for a fully-qualified name is 248 characters (including 
  1904.     the quotes). 
  1905.  
  1906.  
  1907. ΓòÉΓòÉΓòÉ 8. Using the Session Manager ΓòÉΓòÉΓòÉ
  1908.  
  1909. The APL2/2 session manager is a Presentation Manager-based application that 
  1910. allows you to carry on an interactive session with an APL2 interpreter. You can 
  1911. enter APL2 expressions and the results of their evaluation are displayed. 
  1912.  
  1913. The session manager maintains a log of your input expressions and the 
  1914. interpreter's results. The log is retained from one APL session to the next. 
  1915. You can scroll forward and backward in the log, modify old expressions, and 
  1916. type new expressions. 
  1917.  
  1918. The session manager provides facilities that let you: 
  1919.  
  1920. o Open, rename, save, and change the size of the log 
  1921. o Print all or portions of the log 
  1922. o Cut, copy, and paste text between the clipboard and the log 
  1923. o Search and optionally replace text in the log 
  1924. o Select from a list of workspace objects and open edit windows 
  1925. o Signal the interpreter to suppress output or halt 
  1926. o Turn the APL keyboard on and off 
  1927. o Select, create, and modify keyboard layouts 
  1928. o Select different name, size, and style fonts 
  1929. o Change the colors of different types of interpreter output 
  1930. o Set function key definitions 
  1931. o Control whether interpreter output is displayed immediately 
  1932. o Control whether stacked input lines are displayed 
  1933. o Select from a list of edit windows that have been opened 
  1934. o Control a remote interpreter 
  1935.  
  1936. The session manager includes an editor that can be used to edit character 
  1937. matrixes, functions, and operators. You can double-click on an object name in 
  1938. the log or use the Open Object window to select an object for editing. The APL2 
  1939. Window List displays the list of edit windows opened from the session manager. 
  1940. This feature cannot be used when you have issued a Γòû-edit or )HOST request 
  1941. which has not yet completed. 
  1942.  
  1943. To enable you to type the APL characters, the session manager redefines each of 
  1944. the alphanumeric keys on the keyboard. The Select Keyboard and Modify Keyboard 
  1945. windows enable you to select, display, create, and modify keyboard layouts. 
  1946.  
  1947. The session manager includes extensive online help. To display contextual help 
  1948. on any menu item or window, press F1. Use the choices on the Help menu to 
  1949. display: 
  1950.  
  1951. o General help about the session manager 
  1952. o Information about the keys the session manager supports 
  1953. o An index of help topics 
  1954. o Information about using Help 
  1955.  
  1956. o Session Manager Keys 
  1957. o Running a Remote Session Manager 
  1958.  
  1959.  
  1960. ΓòÉΓòÉΓòÉ 8.1. Session Manager Keys ΓòÉΓòÉΓòÉ
  1961.  
  1962. The session manager supports the following: 
  1963.  
  1964. o Action Keys 
  1965. o Cursor Movement and Scrolling Keys 
  1966. o Text Modification Keys 
  1967. o Editing Keys 
  1968. o Other Keys 
  1969. o Edit Window Keys 
  1970.  
  1971.  
  1972. ΓòÉΓòÉΓòÉ 8.1.1. Action Keys ΓòÉΓòÉΓòÉ
  1973.  
  1974. Enter or NewLine 
  1975.    Sends any modified lines to the interpreter. 
  1976.  
  1977. Ctrl+Backspace 
  1978.    Switches APL keyboard support on and off. 
  1979.  
  1980. Pause 
  1981.    Suppresses interpreter output. 
  1982.  
  1983. Break 
  1984.    Sends an Attention signal to the interpreter. 
  1985.  
  1986. Shift+Alt+F 
  1987.    Opens or closes the Find window 
  1988.  
  1989.  
  1990. ΓòÉΓòÉΓòÉ 8.1.2. Cursor Movement and Scrolling Keys ΓòÉΓòÉΓòÉ
  1991.  
  1992. Ctrl+NewLine 
  1993.    Moves the cursor to the beginning of the next line. 
  1994.  
  1995. Left Arrow 
  1996.    Moves the cursor left one character. 
  1997.  
  1998. Right Arrow 
  1999.    Moves the cursor right one character. 
  2000.  
  2001. Down Arrow 
  2002.    Moves the cursor down one line. 
  2003.  
  2004. Up Arrow 
  2005.    Moves the cursor up one line. 
  2006.  
  2007. Alt+Left Arrow 
  2008.    Scrolls the log left one column. 
  2009.  
  2010. Alt+Right Arrow 
  2011.    Scrolls the log right one column. 
  2012.  
  2013. Alt+Down Arrow 
  2014.    Scrolls the log down one line. 
  2015.  
  2016. Alt+Up Arrow 
  2017.    Scrolls the log up one line. 
  2018.  
  2019. Tab 
  2020.    Moves the cursor to the next tab stop. 
  2021.  
  2022.    Note:  Tabs stops are set every 6 columns 
  2023.  
  2024. BackTab (Shift+Tab) 
  2025.    Moves the cursor to the previous tab stop. 
  2026.  
  2027. Page Up 
  2028.    Scrolls the log up one page 
  2029.  
  2030. Page Down 
  2031.    Scrolls the log down one page 
  2032.  
  2033. Ctrl+Page Up 
  2034.    Scrolls the log left one page 
  2035.  
  2036. Ctrl+Page Down 
  2037.    Scrolls the log right one page 
  2038.  
  2039. Home 
  2040.    Moves the cursor to the beginning of the current line. 
  2041.  
  2042. End 
  2043.    Moves the cursor to the end of the current line. 
  2044.  
  2045. Ctrl+Home 
  2046.    Moves the cursor to the beginning of the log. 
  2047.  
  2048. Ctrl+End 
  2049.    Moves the cursor to the end of the log. 
  2050.  
  2051. Alt+Home 
  2052.    Moves the cursor to the upper left corner of the window. 
  2053.  
  2054. Alt+End 
  2055.    Moves the cursor to the lower right corner of the window. 
  2056.  
  2057.  
  2058. ΓòÉΓòÉΓòÉ 8.1.3. Text Modification Keys ΓòÉΓòÉΓòÉ
  2059.  
  2060. ESC 
  2061.    Selects a line for input or undo changes to the line. Lines selected for 
  2062.    input are identified by a mark next to the line in the left border of the 
  2063.    window. 
  2064.  
  2065. Backspace 
  2066.    Deletes the previous character. 
  2067.  
  2068. Delete 
  2069.    Deletes the current character. 
  2070.  
  2071.  
  2072. ΓòÉΓòÉΓòÉ 8.1.4. Editing Keys ΓòÉΓòÉΓòÉ
  2073.  
  2074. Shift+Delete 
  2075.    Moves the marked text to the clipboard. 
  2076.  
  2077. Ctrl+Insert 
  2078.    Copies the marked text to the clipboard. 
  2079.  
  2080. Shift+Insert 
  2081.    Copies the data on the clipboard after the current line. 
  2082.  
  2083. Ctrl+Delete 
  2084.    Deletes to the end of the line 
  2085.  
  2086. Ctrl+Spacebar 
  2087.    Marks or unmarks the line 
  2088.  
  2089. Shift+Up Arrow 
  2090.    Marks or unmarks the previous line 
  2091.  
  2092. Shift+Down Arrow 
  2093.    Marks or unmarks the next line 
  2094.  
  2095. Ctrl+Shift+Home 
  2096.    Marks or unmarks all lines to the top of the text 
  2097.  
  2098. Ctrl+Shift+End 
  2099.    Marks or unmarks all lines to the bottom of the text 
  2100.  
  2101.  
  2102. ΓòÉΓòÉΓòÉ 8.1.5. Other Keys ΓòÉΓòÉΓòÉ
  2103.  
  2104. The alphanumeric keys can be controlled to produce any character in the current 
  2105. font. Use Select Keyboard and the Modify Keyboard options to select or modify a 
  2106. keyboard layout. 
  2107.  
  2108. Use the Function Keys window to define text to be entered when a function key 
  2109. is pressed. 
  2110.  
  2111. Note:  By itself, the Alt key has no effect. This is different from the OS/2 
  2112. default, which selects the menu bar. 
  2113.  
  2114.  
  2115. ΓòÉΓòÉΓòÉ 8.1.6. Edit Window Keys ΓòÉΓòÉΓòÉ
  2116.  
  2117. Edit windows support the same keys as the session manager with the following 
  2118. differences: 
  2119.  
  2120. F2 
  2121.    Saves the definition 
  2122.  
  2123. F3 
  2124.    Closes the edit window 
  2125.  
  2126. F4 
  2127.    Saves the definition and closes the edit window 
  2128.  
  2129. Newline 
  2130.    Inserts a line if insert mode is active 
  2131.  
  2132. ESC 
  2133.    Undoes modifications to modified lines. 
  2134.  
  2135. Enter 
  2136.    Removes the modification marks from all lines without undoing the 
  2137.    modifications. 
  2138.  
  2139. Ctrl+Break 
  2140.    Has no effect 
  2141.  
  2142. Pause 
  2143.    Has no effect 
  2144.  
  2145. F Keys 
  2146.    F keys can not be defined in edit windows. 
  2147.  
  2148.  
  2149. ΓòÉΓòÉΓòÉ 8.2. Running a Remote Session Manager ΓòÉΓòÉΓòÉ
  2150.  
  2151. The session manager is usually started automatically when the APL2 for OS/2 
  2152. interpreter is invoked. In this case, the session manager and the interpreter 
  2153. run on the same machine. 
  2154.  
  2155. The session manager can also be used to control a remote interpreter. In this 
  2156. way, an interactive session can be conducted with an interpreter on another 
  2157. machine across the room or around the world. 
  2158.  
  2159. The session manager is implemented as auxiliary processor 120. Rather than 
  2160. providing applications with the ability to execute session manager commands, AP 
  2161. 120 processes requests that conform to the shared variable interpreter 
  2162. interface. The session manager shares a variable with the interpreter through 
  2163. which the session is conducted. The session manager's Open Object and Edit 
  2164. windows also share variables with the interpreter. 
  2165.  
  2166. When attempting to use the session manager to control a remote session, the 
  2167. session manager should be manually started and run independently rather than 
  2168. automatically and dependently by an interpreter. The name of the program to run 
  2169. is AP120.EXE. The processor number that the session manager should use to sign 
  2170. on to the SVP should be passed as an argument. For example: 
  2171.  
  2172.       [c:] ap120 -id 1120
  2173.  
  2174. The session manager window appears with the word Unconnected in the title bar. 
  2175. The session manager waits for any interpreter to offer it a variable. When the 
  2176. session manager is offered and accepts a variable, the word Unconnected is 
  2177. replaced with the ID of the interpreter. 
  2178.  
  2179. In order to establish a shared variable connection with a remote interpreter, 
  2180. processor identification, and authorization entries are required for both the 
  2181. interpreter and the session manager. These entries are placed in the SVP 
  2182. profile file. This file is called apl2svp.prf and can be found in the 
  2183. \apl2os2\bin directory. For more information, see Processor Profile Structure. 
  2184.  
  2185. Before shares can be established, the SVP port server must be running. The port 
  2186. server can be started either from the Processors menu in the SVP Trace window, 
  2187. or when starting the trace window by using the -listen on invocation option, or 
  2188. when starting APL2 or AP 120 by using the -svplisten on APL2 and AP 120 
  2189. invocation option. 
  2190.  
  2191. o Workstation Interpreters 
  2192. o APL2/370 Interpreters 
  2193.  
  2194.  
  2195. ΓòÉΓòÉΓòÉ 8.2.1. Workstation Interpreters ΓòÉΓòÉΓòÉ
  2196.  
  2197. When communicating with a remote workstation interpreter, the session manager 
  2198. actually shares a variable with processor 1, which runs under the interpreter. 
  2199. The session manager's processor profile entries might look like this: 
  2200.  
  2201.    :svopid.7001
  2202.       :address.234.45.65.78
  2203.       :userid.JohnDoe
  2204.       :processor.1,1001
  2205.    :procauth.1120
  2206.       :rsvopid.7001
  2207.  
  2208. For more information about processor profile entries, see Processor Profile 
  2209. Structure. 
  2210.  
  2211. These entries would allow the session manager, running as processor 1120, to 
  2212. share variables with processor 1 running under interpreter 1001 on John Doe's 
  2213. machine. The session manager displays 7001 in the title bar when it receives an 
  2214. offer from the processor identified by the :svopid.7001 tag. 
  2215.  
  2216. The remote workstation interpreter's processor profile entries would look like 
  2217. this: 
  2218.  
  2219.    :svopid.9120
  2220.       :address.146.75.44.12
  2221.       :userid.JaneSmith
  2222.       :processor.1120
  2223.    :procauth.1,1001
  2224.       :rsvopid.9120
  2225.  
  2226. These entries allow the processor 1 running under the interpreter 1001 to share 
  2227. variables with the session manager, running as processor 1120, on Jane Smith's 
  2228. machine. 
  2229.  
  2230. To invoke a workstation interpreter and have it be controlled by a remote 
  2231. session manager, use the -sm invocation option to specify the processor 
  2232. identification number of the session manager that the interpreter should extend 
  2233. an offer to. For example: 
  2234.  
  2235.       apl2 -svplisten on -sm 9120
  2236.  
  2237.  
  2238. ΓòÉΓòÉΓòÉ 8.2.2. APL2/370 Interpreters ΓòÉΓòÉΓòÉ
  2239.  
  2240. When communicating with an APL2/370 interpreter, the session manager shares a 
  2241. variable directly with the interpreter. The APL2/370 products do not include an 
  2242. auxiliary processor 1. The session manager's processor profile entries might 
  2243. look like this: 
  2244.  
  2245.    :svopid.7001
  2246.       :address.234.45.65.78
  2247.       :userid.JohnDoe
  2248.      :processor.1001
  2249.    :procauth.1120
  2250.       :rsvopid.7001
  2251.  
  2252. These entries allow the session manager, running as processor 1120, to share a 
  2253. variable with interpreter 1001 running on John Doe's user ID. The session 
  2254. manager displays 7001 in the title bar when it receives an offer from the 
  2255. processor identified by the :svopid.7001 tag. 
  2256.  
  2257. The APL2/370 interpreter's processor profile entries would look like this: 
  2258.  
  2259.    :svopid.9120
  2260.       :address.146.75.44.12
  2261.       :userid.JaneSmith
  2262.       :processor.1120
  2263.    :procauth.1001
  2264.       :rsvopid.9120
  2265.  
  2266. These entries allow interpreter 1001 to share a variable with the session 
  2267. manager, running as processor 1120, on Jane Smith's machine. 
  2268.  
  2269. To invoke an APL2/370 interpreter and have it be controlled by a remote session 
  2270. manager, use the sm invocation option to specify the processor identification 
  2271. number of the session manager that the interpreter should extend an offer to. 
  2272. For example: 
  2273.  
  2274.       apl2 apnames(ap2x119(listen(0))) sm(9120)
  2275.  
  2276. Note:  Because the APL2/370 products do not include an auxiliary processor 1, 
  2277. the session manager Open Object and Edit windows are not be able to share 
  2278. variables with the processor. These facilities are not supported when 
  2279. controlling an APL2/370 interpreter. 
  2280.  
  2281.  
  2282. ΓòÉΓòÉΓòÉ 9. Editors ΓòÉΓòÉΓòÉ
  2283.  
  2284. APL2/2 provides facilities for editing APL objects and OS/2 text files. 
  2285.  
  2286. The editing facilities include: 
  2287.  
  2288. o Opening objects from the session manager 
  2289. o The interpreter's Line Editor 
  2290. o The Apledit program 
  2291. o The EDITOR_2 and EDIT functions in the EDIT workspace 
  2292. o The APLEDIT and EDIT functions in the PMTOOLS workspace 
  2293.  
  2294. APL functions and operators, and variables containing character matrixes can be 
  2295. edited. 
  2296.  
  2297. The following objects can not be edited: 
  2298.  
  2299. o Variables containing numeric, mixed, or nested arrays 
  2300. o Locked functions and operators 
  2301. o External functions 
  2302. o System variables and functions 
  2303.  
  2304. o Opening and Editing Objects 
  2305. o The Line Editor 
  2306. o The Apledit Program 
  2307. o EDIT Workspace Functions 
  2308. o PMTOOLS Workspace Functions 
  2309.  
  2310.  
  2311. ΓòÉΓòÉΓòÉ 9.1. Opening and Editing Objects ΓòÉΓòÉΓòÉ
  2312.  
  2313. Objects in the active workspace can be opened for editing from the session 
  2314. manager. When an object is opened, the session manager opens a window for 
  2315. editing the object. Editor windows can be left open while you continue to 
  2316. interact with the interpreter. Objects can be opened while the interpreter is 
  2317. running. 
  2318.  
  2319. Session manager and editor windows all include the Edit menu choice Open 
  2320. Object. Use Open Object to display a list of the objects in the active 
  2321. workspace. Use the Type of Object buttons to list either the variables, 
  2322. functions, or operators in the workspace. Type or select an object name and 
  2323. press OK to open the object. If the object does not exist, the object is opened 
  2324. with the selected name class. 
  2325.  
  2326. To open an object directly from a session manager or editor window, double 
  2327. click on the object's name. Only objects that already exist can be opened in 
  2328. this way. 
  2329.  
  2330. Session manager and editor windows all include the Windows menu choice APL2 
  2331. Windows List. Use APL2 Windows List to display a list of the editor windows 
  2332. opened from the session manager. The list also includes the session manager 
  2333. window. Double click on a window name to switch to the window. 
  2334.  
  2335. Editor windows support the same keys as the session manager with the following 
  2336. differences: 
  2337.  
  2338. F2          Saves the object. 
  2339.  
  2340. F3          Closes the editor window. 
  2341.  
  2342. F4          Saves the object and closes the editor window. 
  2343.  
  2344. Newline     Inserts a line if insert mode is active. 
  2345.  
  2346. ESC         Undoes modifications to modified lines. 
  2347.  
  2348. Enter       Removes the modification marks from all lines without undoing the 
  2349.             modifications. 
  2350.  
  2351. Ctrl+Break  Has no effect. 
  2352.  
  2353. Pause       Has no effect. 
  2354.  
  2355. Function Keys Function keys cannot be defined in editor windows. 
  2356.  
  2357. For further information about opening objects from the session manager, consult 
  2358. the online help. 
  2359.  
  2360. Editor windows have the following restrictions: 
  2361.  
  2362. o If an object is open and you attempt to open the object again, another editor 
  2363.   window is not opened. The editor window displaying the object is given focus. 
  2364.  
  2365. o If an object is open, changes made to the object by the Line Editor, a system 
  2366.   editor, or by execution of an APL expression are not displayed in the editor 
  2367.   window. To display the changes made to the object, close and reopen the 
  2368.   object. 
  2369.  
  2370. o If an object has more than 32000 rows or columns, it can not be opened. 
  2371.  
  2372.  
  2373. ΓòÉΓòÉΓòÉ 9.2. The Line Editor ΓòÉΓòÉΓòÉ
  2374.  
  2375. The Line Editor can be used to edit functions and operators. 
  2376.  
  2377. To use the Line Editor to edit an object, first select the Line Editor for use 
  2378. as APL's editor, and then use Γòû followed by an object name or header. For 
  2379. example: 
  2380.  
  2381.    )EDITOR 1
  2382.    ΓòûNAME
  2383.  
  2384. For further information about the Line Editor consult APL2 Programming: 
  2385. Language Reference. 
  2386.  
  2387.  
  2388. ΓòÉΓòÉΓòÉ 9.3. The Apledit Program ΓòÉΓòÉΓòÉ
  2389.  
  2390. The Apledit program can be used to edit text files containing APL characters. 
  2391.  
  2392. To invoke Apledit to edit a file, enter: 
  2393.  
  2394.    [c:] apledit filename
  2395. or from APL2: 
  2396.  
  2397.    )HOST apledit filename
  2398.  
  2399. To use Apledit to edit a function or operator, first select Apledit for use as 
  2400. the system editor, and then use Γòû followed by the object name. For example: 
  2401.  
  2402.    )EDITOR APLEDIT
  2403.    ΓòûNAME
  2404.  
  2405. Apledit has the following restrictions: 
  2406.  
  2407. o The file can not contain more than 32000 records. 
  2408. o No record can contain more than 32000 characters. 
  2409.  
  2410. Apledit provides online help that can be consulted for further information. 
  2411.  
  2412. For further information about the APL2's system editor interface, consult APL2 
  2413. Programming: Language Reference. 
  2414.  
  2415.  
  2416. ΓòÉΓòÉΓòÉ 9.4. EDIT Workspace Functions ΓòÉΓòÉΓòÉ
  2417.  
  2418. The EDITOR_2 function emulates the APL2/370 full-screen )EDITOR 2. 
  2419.  
  2420. The EDIT function can be used to edit functions and operators. 
  2421.  
  2422. For further information about the EDIT workspace, see The EDIT Workspace. 
  2423.  
  2424.  
  2425. ΓòÉΓòÉΓòÉ 9.5. PMTOOLS Workspace Functions ΓòÉΓòÉΓòÉ
  2426.  
  2427. The APLEDIT function can be used to edit functions and operators. APLEDIT 
  2428. writes a copy of the object's definition to a file and invokes the Apledit 
  2429. program to edit the file. 
  2430.  
  2431. The EDIT function can be used to edit character matrixes. EDIT does not support 
  2432. matrixes that contain more than 64000 characters. 
  2433.  
  2434. For further information about the PMTOOLS workspace, see The PMTOOLS Workspace. 
  2435.  
  2436.  
  2437. ΓòÉΓòÉΓòÉ 10. Using APL2 across Systems ΓòÉΓòÉΓòÉ
  2438.  
  2439. This chapter describes how to communicate between APL2 sessions on different 
  2440. systems, and how to transfer programs and data between systems. 
  2441.  
  2442. o Cooperative Processing 
  2443. o Transferring Workspaces 
  2444. o Transferring Files 
  2445.  
  2446.  
  2447. ΓòÉΓòÉΓòÉ 10.1. Cooperative Processing ΓòÉΓòÉΓòÉ
  2448.  
  2449. APL2 sessions can communicate either with each other or with other non-APL 
  2450. programs across a Transmission Control Protocol/Internet Protocol (TCP/IP) 
  2451. network. 
  2452.  
  2453. There are three major facilities within APL2/2's support for cooperative 
  2454. processing: 
  2455.  
  2456. o Cross-System Shared Variables 
  2457.  
  2458.   This facility allows a user to share variables with other processors on a 
  2459.   TCP/IP network using normal APL2 shared variable techniques. It provides 
  2460.   APL2's most convenient program-to-program cross network communication path. 
  2461.  
  2462. o Shared Variable Interpreter Interface 
  2463.  
  2464.   This interface provides a set of protocols whereby an APL2 interpreter can be 
  2465.   controlled through a shared variable. It provides a way for a program to 
  2466.   control a remote session. 
  2467.  
  2468. o TCP/IP Auxiliary Processor (AP 119) 
  2469.  
  2470.   This processor allows users and applications to make direct requests to 
  2471.   TCP/IP. It provides APL2's most flexible program-to-program cross network 
  2472.   communication path. The interface can also be used for communication between 
  2473.   APL2 and non-APL programs across a network. 
  2474.  
  2475. o Processor Network Identification 
  2476. o Processor Profile Structure 
  2477. o Using the Port Server 
  2478. o Sending a Share Offer 
  2479. o Receiving a Share Offer 
  2480. o Processor Profile Syntax 
  2481. o Processor Profile Examples 
  2482.  
  2483.  
  2484. ΓòÉΓòÉΓòÉ 10.1.1. Processor Network Identification ΓòÉΓòÉΓòÉ
  2485.  
  2486. An APL2 session consists of a collection of processors. From the point of view 
  2487. of an APL2 program, each processor is identified by a single nonnegative 
  2488. integer. The APL2 user is identified with a processor number greater than 1000. 
  2489. Other processors in the session are called auxiliary processors (APs) and are 
  2490. normally identified with a processor number less than 1000. 
  2491.  
  2492. A single integer is not enough to address processors in multiple sessions and 
  2493. processors in sessions on a network. Therefore a Processor Profile provides a 
  2494. cross reference between the single processor number used by APL2 programs and a 
  2495. processor network identification. 
  2496.  
  2497. The file name of the processor profile is specified in the environment variable 
  2498. APL2SVPPRF. If this variable is not defined, the name apl2svp.prf is used. 
  2499.  
  2500. The profile is used for both outgoing offers from a processor and for incoming 
  2501. offers from other processors. It is read for each offer and can be dynamically 
  2502. modified. 
  2503.  
  2504. Every processor on the network has a unique name consisting of the following 
  2505. parts: 
  2506.  
  2507.   IP_address user_id processor_number[,parent[,grandparent]]
  2508. For example: 
  2509.  
  2510.   123.45.6.78 BROWN 1002
  2511.   123.45.6.78 BROWN 127,1001
  2512.  
  2513. A processor named with only an IP address, user ID, and processor number is 
  2514. called an independent processor. In the first example above, 1002 is an 
  2515. independent processor. Normally, the APL2 interpreter runs as an independent 
  2516. processor. 
  2517.  
  2518. A processor with a parent (or any ancestor) is called a dependent processor. A 
  2519. dependent processor is notified when its immediate ancestor signs off. In the 
  2520. second example above, 127 depends on 1001 and 1001 is independent. Normally, 
  2521. the APL2 interpreter runs as an independent processor with its auxiliary 
  2522. processors dependent on it. This scheme allows processor 127 to be informed 
  2523. (and normally to terminate itself) when the APL2 session ends. 
  2524.  
  2525. A third level of dependency is defined if a processor is started with a 
  2526. grandparent processor number. This scheme allows APL applications to serve as 
  2527. dependent auxiliary processors, since they in turn need to use other dependent 
  2528. auxiliary processors. Longer sequences of ancestors would be meaningful but are 
  2529. not supported. 
  2530.  
  2531.  
  2532. ΓòÉΓòÉΓòÉ 10.1.2. Processor Profile Structure ΓòÉΓòÉΓòÉ
  2533.  
  2534. Each line in the processor profile can contain one or more tags and its 
  2535. associated data. Tags can be written in uppercase, lowercase, or mixed case. 
  2536. Any line starting with the character "*" is ignored. 
  2537.  
  2538. Each processor entry must begin with either an :svopid tag or a :procauth tag 
  2539. and continues to the next occurrence of one of these tags or to the end of the 
  2540. profile. A processor entry beginning with an :svopid tag is known as an 
  2541. identification or ID entry. Here is an example of an ID entry that defines 
  2542. 33586 as a remote user signed on as ID 1002 under BROWN at 123.45.6.78. 
  2543.  
  2544. * user BROWN at STLAPL
  2545. :svopid.33586
  2546.           :address.123.45.6.78
  2547.           :userid.BROWN
  2548.           :processor.1002
  2549.  
  2550. A processor entry beginning with a :procauth tag is known as an authorization 
  2551. entry. Here is an example of an entry that authorizes the remote processor 
  2552. identified by an svopid of 33586 to share with a local processor 100, which is 
  2553. a dependent of processor 1001: 
  2554.  
  2555. * AP100 authorization
  2556. :procauth.100,1001
  2557.           :rsvopid.33586
  2558.  
  2559.  
  2560. ΓòÉΓòÉΓòÉ 10.1.3. Using the Port Server ΓòÉΓòÉΓòÉ
  2561.  
  2562. The APL2 port server must be active for cross-system sharing to be possible. 
  2563. The APL2/2 port server can be started in several different ways: 
  2564.  
  2565. o Specifying the -svplisten on parameter when invoking APL2/2 or any other 
  2566.   independent processor. 
  2567.  
  2568. o Setting the environment variable APLSVPLISTEN to on before invoking APL2/2. 
  2569.  
  2570. o Specifying the -listen on parameter when starting the SVP Trace window 
  2571.   program. 
  2572.  
  2573. o Selecting Cross System/Start from the Actions menu of the SVP Trace window. 
  2574.   (For more information about the SVP Trace window, see SVP Trace Facility.) 
  2575.  
  2576. Note:  No matter how the port server is started, TCP/IP must have been started 
  2577. before starting the SVP. 
  2578.  
  2579.  
  2580. ΓòÉΓòÉΓòÉ 10.1.4. Sending a Share Offer ΓòÉΓòÉΓòÉ
  2581.  
  2582. When a shared variable offer is extended, the processor number from the left of 
  2583. ╨áSVO is matched against the data in :svopid tags in the processor profile. If a 
  2584. match is found, the offer is extended to the processor described by the tag's 
  2585. :processor value and, if present, by the :address and :userid values. 
  2586.  
  2587. If no match is found, and the processor number is greater than 1000, the offer 
  2588. is extended to an independent processor identified by the given processor 
  2589. number, within the same SVP domain as the offerer (same IP address and user 
  2590. ID). 
  2591.  
  2592. If the processor number is less than 1001, the offer is assumed to be to a 
  2593. processor dependent on the offerer. The parent is taken to be the offerer's 
  2594. processor number and the grandparent is taken to be the offerer's parent, if 
  2595. any. If this processor is not running an attempt is made to start the 
  2596. processor. For example, if you are processor 1001 and issue the following 
  2597. share: 
  2598.  
  2599.       127 ╨áSVO 'VAR'
  2600.  
  2601. and 127 is not found in the processor profile, the offer is made to a processor 
  2602. 127 that is dependent on 1001. If processor 127 is not signed on, an executable 
  2603. named ap127 is searched for and started automatically, if found. Therefore an 
  2604. APL2 session can communicate with its dependent auxiliary processors without 
  2605. using the processor profile; dependent auxiliary processors are started 
  2606. automatically as needed. Independent auxiliary processors must either use a 
  2607. processor number above 1000 or be identified in the processor profile. 
  2608.  
  2609.  
  2610. ΓòÉΓòÉΓòÉ 10.1.5. Receiving a Share Offer ΓòÉΓòÉΓòÉ
  2611.  
  2612. When receiving an offer to share, the processor profile serves to identify the 
  2613. remote processor and to authorize the share. First, the processor 
  2614. identification of the processor originating the share is matched against the 
  2615. :address, user ID, and :processor tags of each ID entry in the processor 
  2616. profile. Limited "wildcard" support is provided as discussed in Processor 
  2617. Profile Syntax. 
  2618.  
  2619. If a matching entry is found, the svopid of this entry must be identified in 
  2620. the :rsvopid tag of an authorization entry for the local processor with whom 
  2621. the caller is trying to share. If this is true, the share is allowed to 
  2622. proceed. 
  2623.  
  2624.  
  2625. ΓòÉΓòÉΓòÉ 10.1.6. Processor Profile Syntax ΓòÉΓòÉΓòÉ
  2626.  
  2627. Each line in the processor profile can contain one or more tags and its 
  2628. associated data. Tags can be written in uppercase, lowercase, or mixed case. 
  2629. Any line starting with the character "*" is ignored. 
  2630.  
  2631. o Identification Entries 
  2632. o Authorization Entries 
  2633.  
  2634.  
  2635. ΓòÉΓòÉΓòÉ 10.1.6.1. Identification Entries ΓòÉΓòÉΓòÉ
  2636.  
  2637. Each processor ID entry must begin with a :svopid tag and continues to the next 
  2638. occurrence of a :svopid or :procauth tag or to the end of the profile. 
  2639.  
  2640.   :svopid.id 
  2641.  
  2642. This tag identifies the beginning of an entry and is required. It specifies the 
  2643. number to be used in the left argument of ╨áSVO when sharing with the processor 
  2644. described by this entry. For incoming offers its value is returned by ╨áSVQ. It 
  2645. must be a positive number. This value can be coded as 0 to allow incoming 
  2646. offers to be assigned a unique processor number. Such an entry could not, 
  2647. however, be used to initiate an offer. 
  2648.  
  2649.   :processor.id[,id[,id]] 
  2650.  
  2651. This tag gives one, two, or three processor numbers separated by commas and is 
  2652. required. These numbers represent the actual procid, parent and grandparent of 
  2653. the share partner. 
  2654.  
  2655. Because offers to processors with procids less than 1000 are considered to be 
  2656. offers to dependent processors, a profile ID entry is required to share with a 
  2657. processor running independently on the same machine and user ID. In this case, 
  2658. the svopid can be the same or different than the actual procid of the 
  2659. independent processor. Note that if the same number is used, it is impossible 
  2660. to share with a dependent processor using that number as its procid. 
  2661.  
  2662. id can be coded as "*" in which case the entry identifies any remote processor 
  2663. with the corresponding :svopid. 
  2664.  
  2665.   :address.addr 
  2666.  
  2667. This tag gives the IP address of the partners machine in IP "dotted decimal" 
  2668. notation consisting of four decimal numbers between 0 and 255 separated by 
  2669. periods and is optional. 
  2670.  
  2671. addr can be coded as "*" in which case the entry identifies processors from any 
  2672. address with the corresponding :svopid. 
  2673.  
  2674.   :userid.userid 
  2675.  
  2676. This tag gives the character identification of the user ID of the partner and 
  2677. is optional. It can be one to eight characters and is case sensitive. 
  2678.  
  2679. userid can be coded as "*" in which case the entry identifies processors from 
  2680. any user ID with the corresponding :svopid. 
  2681.  
  2682. Here is an example of a processor entry that defines ╨áSVO argument 33586 as a 
  2683. remote user. 
  2684.  
  2685. * user BROWN at STLAPL
  2686. :svopid.33586
  2687.           :address.123.45.6.78
  2688.           :userid.BROWN
  2689.           :processor.1002
  2690.  
  2691.  
  2692. ΓòÉΓòÉΓòÉ 10.1.6.2. Authorization Entries ΓòÉΓòÉΓòÉ
  2693.  
  2694. Each processor authorization entry must begin with a :procauth tag and 
  2695. continues to the next occurrence of a :procauth or :svopid tag, or to the end 
  2696. of the profile. 
  2697.  
  2698.   :procauth.id[,id[,id]] 
  2699.  
  2700. This tag identifies the procid, parent and pparent that is authorized to 
  2701. receive shares and is required. id can be coded as "*" in which case the entry 
  2702. serves to authorize all local processors. 
  2703.  
  2704.   :rsvopid.id[,id[,...]] 
  2705.  
  2706. This tag lists the svopid numbers that identify remote processors that are 
  2707. authorized to share with the processor named in the corresponding :procauth 
  2708. tag. Multiple numbers can be listed separated by commas. 
  2709.  
  2710. id can be coded as "*" in which case the entry authorizes any remote processor 
  2711. to share with the corresponding :procauth. 
  2712.  
  2713. Here is an example of an entry that authorizes the processor identified by 
  2714. :svopid.33586 to share with a local processor 100 dependent on processor 1001: 
  2715.  
  2716. * AP100 authorization
  2717. :procauth.100,1001
  2718.           :rsvopid.33586
  2719.  
  2720.  
  2721. ΓòÉΓòÉΓòÉ 10.1.7. Processor Profile Examples ΓòÉΓòÉΓòÉ
  2722.  
  2723. The technical reference material you need to share variables between processors 
  2724. running on different machines was presented in Processor Network Identification 
  2725. and Processor Profile Structure. This section provides examples of how to code 
  2726. processor profile entries for some typical application needs. 
  2727.  
  2728. For the purposes of these examples, assume that there are three users running 
  2729. interpreters on three different machines. Each interpreter process is 
  2730. identified with a unique IP address, user ID, and processor number. The 
  2731. processor numbers correspond to Γò₧╨áAI as reported by the interpreters 
  2732. themselves. 
  2733.  
  2734. For clarity, these sample interpreters are referred to as Users 1, 2, and 3. 
  2735. You need the following information: See Profile Information. 
  2736.  
  2737. o User to User Shared Variables 
  2738. o User to Auxiliary Processor Shared Variables 
  2739. o Using Asterisks in Processor Profile Entries 
  2740.  
  2741.  
  2742. ΓòÉΓòÉΓòÉ 10.1.7.1. Profile Information ΓòÉΓòÉΓòÉ
  2743.  
  2744.  
  2745. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  2746.  
  2747. User 
  2748.  
  2749.  
  2750. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  2751.  
  2752. Address 
  2753.  
  2754.  
  2755. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  2756.  
  2757. User ID 
  2758.  
  2759.  
  2760. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  2761.  
  2762. Γò₧╨áAI 
  2763.  
  2764.  
  2765. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  2766.  
  2767.  
  2768.  
  2769. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  2770.  
  2771. 9.10.11.123 
  2772.  
  2773.  
  2774. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  2775.  
  2776. BARB 
  2777.  
  2778.  
  2779. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  2780.  
  2781. 1001 
  2782.  
  2783.  
  2784. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  2785.  
  2786.  
  2787.  
  2788. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  2789.  
  2790. 9.10.11.222 
  2791.  
  2792.  
  2793. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  2794.  
  2795. jsmith 
  2796.  
  2797.  
  2798. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  2799.  
  2800. 32739 
  2801.  
  2802.  
  2803. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  2804.  
  2805.  
  2806.  
  2807. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  2808.  
  2809. 123.45.6.77 
  2810.  
  2811.  
  2812. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  2813.  
  2814. djones 
  2815.  
  2816.  
  2817. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  2818.  
  2819. 6666 
  2820.  
  2821.  
  2822. ΓòÉΓòÉΓòÉ 10.1.7.2. User to User Shared Variables ΓòÉΓòÉΓòÉ
  2823.  
  2824. Assume that User 1 wants to share variables with User 2. The information needed 
  2825. is as follows: 
  2826.  
  2827.  1. In order to offer to share a variable with another processor, you need to 
  2828.     identify that processor with some number. A processor profile entry is then 
  2829.     used to associate that number with the user's network information. 
  2830.  
  2831.     Assume that User 1 wants to refer to User 2 with the number 777. The 
  2832.     following entry is required in User 1's profile: 
  2833.  
  2834.                     :svopid.777
  2835.                        :address.9.10.11.222
  2836.                        :userid.jsmith
  2837.                        :processor.32739
  2838.  
  2839.     This entry allows User 1 to extend an offer to User 2. 
  2840.  
  2841.  2. User 1 needs to authorize User 2 to share variables. User 2 is already 
  2842.     identified as 777 with the :svopid tag, and it is known that User 1 is 
  2843.     running as processor 1001, so the following entry can be used: 
  2844.  
  2845.                    :procauth.1001
  2846.                        :rsvopid.777
  2847.  
  2848.     This authorizes remote processor 777 to share variables with local 
  2849.     processor 1001. 
  2850.  
  2851. Remember that there are always two sides to every share. User 2 also needs a 
  2852. number to use to refer to User 1. Assume that User 2 wants to use the number 
  2853. 3456. The following entry is required in User 2's profile: 
  2854.  
  2855.             :svopid.3456
  2856.                :address.9.10.11.123
  2857.                :userid.BARB
  2858.                :processor.1001
  2859.  
  2860. User 2 also needs to authorize User 1: 
  2861.  
  2862.             :procauth.32739
  2863.                :rsvopid.3456
  2864.  
  2865. Note that the :rsvopid values correspond to the :svopid values shown above, and 
  2866. the :procauth values correspond to the processor numbers of the interpreters as 
  2867. reported by Γò₧╨áAI. 
  2868.  
  2869. If Users 1 and 3 also wanted to share variables, they would have to code 
  2870. identification and authorization entries just as Users 1 and 2 did. However, 
  2871. when coding the authorization entry, User 1 can take either of two approaches. 
  2872. First, User 1 could simply add another authorization entry. Assume User 3 has 
  2873. been identified as processor 8888: 
  2874.  
  2875.             :procauth.1001
  2876.                :rsvopid.8888
  2877.  
  2878. You can have as many authorization entries in your processor profile as you 
  2879. want, but there is another way. The :rsvopid. tag can provide a list of 
  2880. processors. So, User 1 could add User 3's number to the existing entry like 
  2881. this: 
  2882.  
  2883.             :procauth.1001
  2884.                :rsvopid.777,8888
  2885.  
  2886. This entry authorizes the remote users associated with the numbers 777 and 8888 
  2887. to share variables with User 1's 1001 processor. 
  2888.  
  2889. User 1 could authorize more users by adding more entries or by just adding 
  2890. numbers to the :rsvopid tag. 
  2891.  
  2892.  
  2893. ΓòÉΓòÉΓòÉ 10.1.7.3. User to Auxiliary Processor Shared Variables ΓòÉΓòÉΓòÉ
  2894.  
  2895. For another example, assume that User 1 wants to share a variable with AP 127, 
  2896. which is running under interpreter processor 6666 on User 3's machine. This 
  2897. might be useful if User 3's machine contained a database that User 1 needed 
  2898. access to. 
  2899.  
  2900. User 1 needs to add another identification entry to associate a number with the 
  2901. remote processor 127. Assume that User 1 wants to use the number 9127 to refer 
  2902. to the remote processor. The entry is as follows: 
  2903.  
  2904.             :svopid.9127
  2905.                :address.123.45.6.77
  2906.                :userid.djones
  2907.                :processor.127,6666
  2908.  
  2909. Notice the :processor tag now lists two processor numbers. This indicates that 
  2910. AP 127 is a dependent of processor 6666. 
  2911.  
  2912. User 1 also needs to authorize shares with the remote processor 127 so the 
  2913. authorization entry becomes: 
  2914.  
  2915.             :procauth.1001
  2916.                :rsvopid.777,8888,9127
  2917.  
  2918. If Users 1 and 3 are set up for user to user sharing, User 3 already has 
  2919. identification entry for User 1. However, AP 127 is a new processor on User 3's 
  2920. machine, and is sharing variables, so another authorization entry needs to be 
  2921. added for User 3. Assuming User 3 has identified User 1 as 2229: 
  2922.  
  2923.             :procauth.127,6666
  2924.                :rsvopid.2229
  2925.  
  2926. Like the :processor. tag shown above, the :procauth. tag in this authorization 
  2927. entry lists two numbers. In this case, however, it does not refer to two 
  2928. separate processors. Only a single processor (in this case 127, dependent of 
  2929. 6666) can be listed in a :procauth tag. The exception to this rule is the use 
  2930. of an asterisk as mentioned below. 
  2931.  
  2932.  
  2933. ΓòÉΓòÉΓòÉ 10.1.7.4. Using Asterisks in Processor Profile Entries ΓòÉΓòÉΓòÉ
  2934.  
  2935. The examples shown demonstrate how to identify specific remote processors and 
  2936. authorize them to establish shares with specific local processors. Sometimes 
  2937. however, it is not possible to identify all the potential share partners. 
  2938. Similarly, sometimes you want to give one or more share partners access to all 
  2939. your processors. Asterisks are used as wildcards in processor profile entries 
  2940. to provide general identification and authorization 
  2941.  
  2942. Suppose that User 1 is writing a server; there is no way to know who the 
  2943. server's potential clients might be. It is not possible to code separate 
  2944. identification entries for each client. In this case, User 1 can code this 
  2945. identification entry: 
  2946.  
  2947.             :svopid.0
  2948.                :address.*
  2949.                :userid.*
  2950.                :processor.*
  2951.  
  2952. In effect, this entry identifies any remote processor as number 0. This number 
  2953. is used for a special reason. A remote processor is always known to the APL2 
  2954. session by the number used in the :svopid tag. When the number 0 is seen by the 
  2955. APL2 shared variable processor, a new unique number is automatically assigned. 
  2956.  
  2957. You have now handled the problem of identifying unknown processors, and can now 
  2958. deal with authorization. An asterisk can also be used in the :rsvopid tag like 
  2959. this: 
  2960.  
  2961.             :procauth.1001
  2962.                :rsvopid.*
  2963.  
  2964. This authorizes shares from any processor. 
  2965.  
  2966. Finally, assume that User 1 not only wanted to authorize remote users to share 
  2967. with processor 1001, but with any processor. The following entry can be used: 
  2968.  
  2969.             :procauth.*
  2970.                :rsvopid.*
  2971.  
  2972. This entry authorizes all remote processors, indicated by the asterisk in the 
  2973. :rsvopid. tag, to establish shares with any processor on the machine, indicated 
  2974. by the asterisk in the :procauth. tag. 
  2975.  
  2976.  
  2977. ΓòÉΓòÉΓòÉ 10.2. Transferring Workspaces ΓòÉΓòÉΓòÉ
  2978.  
  2979. Workspaces are easily transferred between APL2 systems. Transfer file formats 
  2980. have been defined to permit exchange of workspace objects among all IBM APL2 
  2981. implementations. Additional tools are provided for migration of the older VS 
  2982. APL format to APL2. 
  2983.  
  2984. o Workspace Transfer Between APL2 Systems 
  2985. o Migration of TryAPL2 Workspaces 
  2986. o Migration of VS APL Workspaces 
  2987.  
  2988.  
  2989. ΓòÉΓòÉΓòÉ 10.2.1. Workspace Transfer Between APL2 Systems ΓòÉΓòÉΓòÉ
  2990.  
  2991. In general, APL2 workspaces must be sent to other APL2 systems as transfer form 
  2992. files. On workstation platforms, these files have an extension of .atf. On 
  2993. mainframe platforms, these files have an extension of .apltf. Note that on some 
  2994. workstations the names of transfer files and workspaces and their extensions 
  2995. are case sensitive. 
  2996.  
  2997. The APL2 commands used to create and read transfer form files are )OUT, )IN, 
  2998. and )PIN. To transfer a workspace, start APL2 on the system where the workspace 
  2999. resides, and issue the following commands: 
  3000.  
  3001.    )LOAD wsid
  3002.    )SIC   (or )RESET)
  3003.    )OUT filename
  3004.  
  3005. A transfer file is created by the )OUT command. 
  3006.  
  3007. Once the transfer file is created, it then must be moved to the target APL2 
  3008. system. The techniques for physically moving files from one system to another 
  3009. can vary depending on the types of systems and what connections exist between 
  3010. them. 
  3011.  
  3012. o One key issue is that some systems (for example MVS/TSO and VM/CMS) use an 
  3013.   EBCDIC character encoding, while others (for example OS/2 and AIX/6000) use 
  3014.   an ASCII encoding. Both ASCII and EBCDIC transfer file formats are defined, 
  3015.   and all IBM APL2 systems accept both formats. No data conversion should be 
  3016.   attempted within the file itself when transferring it from one system to 
  3017.   another. The receiving APL2 system performs any necessary conversion. If the 
  3018.   transfer is done electronically through a network connection, the programs 
  3019.   controlling that transfer must be told that this is a "binary" rather than 
  3020.   "character" file. (The exact terminology used may vary depending on the 
  3021.   system and network control programs being used.) 
  3022.  
  3023. o Some systems use "record-oriented" files while others use stream files. If 
  3024.   stream files are being transferred to a system that expects record-oriented 
  3025.   files, an arbitrary record length may be used, but the existing record 
  3026.   separators ("LF" or "CR/LF") must be retained. Conversely, separators should 
  3027.   not be inserted when record-oriented files are being transferred to a system 
  3028.   that expects stream files. Again, the receiving APL2 system adjusts to these 
  3029.   differences. 
  3030.  
  3031. o Within these constraints, standard data transmission commands appropriate to 
  3032.   the system such as "ftp put", "SEND", "SENDFILE", or "TRANSMIT" can be used 
  3033.   for network transmission, with corresponding commands such as "ftp get" or 
  3034.   "RECEIVE" as appropriate to the receiving system. 
  3035.  
  3036. o Because the receiving APL2 system performs all necessary conversions, it is 
  3037.   also possible to use shared DASD, remote file systems, removable media, or 
  3038.   other such facilities to transport the data. 
  3039.  
  3040. When the file has been transferred to the target system, it can then be read 
  3041. into APL2 and saved as a workspace: 
  3042.  
  3043.    )CLEAR
  3044.    )IN filename
  3045.    )SAVE wsid
  3046.  
  3047. Note:  Though it is possible to run APL2/PC on the same system where you have 
  3048. installed APL2/2, the workspace formats used by the programs are all different. 
  3049. Workspaces must be migrated between APL2/PC and APL2/2 using .atf files as 
  3050. described above. 
  3051.  
  3052.  
  3053. ΓòÉΓòÉΓòÉ 10.2.2. Migration of TryAPL2 Workspaces ΓòÉΓòÉΓòÉ
  3054.  
  3055. Workspaces saved under TryAPL2 can also be read by APL2/2, APL2/6000, and APL2 
  3056. for Sun Solaris. The function TRYLOAD in the FILE workspace can be used to read 
  3057. these files. 
  3058.  
  3059.  
  3060. ΓòÉΓòÉΓòÉ 10.2.3. Migration of VS APL Workspaces ΓòÉΓòÉΓòÉ
  3061.  
  3062. VS APL workspaces can be migrated to the workstation platforms using the VSCOPY 
  3063. function from the MIGRATE workspace (described in The MIGRATE Workspace). 
  3064.  
  3065. The saved VS APL workspaces should have a clear state indicator. This can be 
  3066. ensured before you )SAVE the workspace by using the )SI command to check the 
  3067. state indicator, and entering Γòò one time for each * in the display from )SI. 
  3068.  
  3069. Download each saved workspace in binary form to a file. The VSCOPY function 
  3070. assumes that the file extension used for downloaded VS APL workspaces is .VWS 
  3071. (renamed from .VSAPLWS on VS APL). Then, run the VSCOPY function against each 
  3072. workspace: 
  3073.  
  3074.    )CLEAR
  3075.    )COPY 2 MIGRATE VSCOPY
  3076.    VSCOPY 'filename'
  3077.    )ERASE VSCOPY
  3078.    )SAVE wsid
  3079.  
  3080.  
  3081. ΓòÉΓòÉΓòÉ 10.3. Transferring Files ΓòÉΓòÉΓòÉ
  3082.  
  3083. Files created by the APL2 file processors, AP 210 and AP 211, can also be 
  3084. transferred across systems, or accessed on shared media. 
  3085.  
  3086. o AP 210 Files 
  3087. o AP 211 Files 
  3088.  
  3089.  
  3090. ΓòÉΓòÉΓòÉ 10.3.1. AP 210 Files ΓòÉΓòÉΓòÉ
  3091.  
  3092. Files created by AP 210 are portable between APL2/2, APL2/6000, and APL2 for 
  3093. Sun Solaris. Files should be transmitted in binary mode. 
  3094.  
  3095. In addition, files created by AP 210 on APL2/PC can be read by APL2/2, 
  3096. APL2/6000, and APL2 for Sun Solaris. Writing back to these files is allowed, 
  3097. but is not recommended for code A files. The format used for code A files is 
  3098. different from APL2/PC, and objects take a different amount of storage. File 
  3099. corruption is likely. In order to create a writable file, each object in the 
  3100. APL2/PC file should be read and rewritten to a new file. 
  3101.  
  3102.  
  3103. ΓòÉΓòÉΓòÉ 10.3.2. AP 211 Files ΓòÉΓòÉΓòÉ
  3104.  
  3105. Files created by AP 211 are portable between APL2/370, APL2/2, APL2/6000, and 
  3106. APL2 for Sun Solaris. The files must be transferred in binary mode. The 
  3107. receiving APL2 system performs all necessary conversions of data. Files to be 
  3108. uploaded to the mainframe must be uploaded as fixed format files, with a record 
  3109. length equal to the AP 211 blocksize for the file. The blocksize can be 
  3110. obtained by issuing an AP 211 USE command against the file. 
  3111.  
  3112. In addition, files created by AP 211 on APL2/PC can be read by APL2/2, 
  3113. APL2/6000, and APL2 for Sun Solaris. Writing back to these files is not 
  3114. allowed. The function REBUILD211 in the public workspace 2 FILE can be used to 
  3115. permanently convert the APL2/PC file to the new format if desired. 
  3116.  
  3117.  
  3118. ΓòÉΓòÉΓòÉ 11. Associated Processors ΓòÉΓòÉΓòÉ
  3119.  
  3120. Names are used in APL expressions to identify variables, defined functions and 
  3121. operators, and constants (such as labels). When APL encounters names during the 
  3122. execution of expressions, it passes control to the appropriate routines in the 
  3123. interpreter for evaluation. 
  3124.  
  3125. Through the use of ╨áNA, and by associating a name with a specific processor, an 
  3126. APL application program can cause that name to be processed by routines in the 
  3127. specified associated processor instead of the APL interpreter. Associated 
  3128. processors provide an alternate mechanism for handling the evaluation of APL 
  3129. names. 
  3130.  
  3131. o Applications of External Names 
  3132. o Processor 11-Accessing External Routines 
  3133.  
  3134.  
  3135. ΓòÉΓòÉΓòÉ 11.1. Applications of External Names ΓòÉΓòÉΓòÉ
  3136.  
  3137. A name associated with a processor is called an external name. 
  3138.  
  3139. External names have a variety of uses in building production applications. By 
  3140. giving you additional options in the ways in which you process information from 
  3141. APL, external names help improve productivity. Some of the reasons you might 
  3142. use external names are: 
  3143.  
  3144. o Reuse of Existing Programs 
  3145.  
  3146.   A principal objective of external names is to permit you to reuse many 
  3147.   existing programs without any need to modify them. APL2 provides mechanisms 
  3148.   by which you describe where the programs exist and what data structures they 
  3149.   require in arguments. This information is provided to APL2 in a file. Once 
  3150.   the information has been provided, you can then use external names to access 
  3151.   these programs from your workspace just as if they were APL functions. 
  3152.  
  3153. o Synchronous Access to System Information 
  3154.  
  3155.   Sometimes an application needs easy access to information about the host 
  3156.   system or from another application subsystem. Since host information can vary 
  3157.   widely between platforms, it is impractical for APL to provide it directly. 
  3158.   You can use external names, however, to temporarily "escape" APL, access the 
  3159.   information, and bring back the results to the workspace for use by the 
  3160.   application. 
  3161.  
  3162. o Improve Performance 
  3163.  
  3164.   It is common for an application to have a uniquely tailored data structure or 
  3165.   algorithm that is used widely by the application's own functions. This 
  3166.   application-specific feature often assumes a fundamental, what APL might term 
  3167.   "primitive", nature and frequently becomes the bottleneck that limits either 
  3168.   the capacity or performance of the application. External objects can be used 
  3169.   to overcome such problems by permitting you to enclose the definition in 
  3170.   compiled code. Because external objects are syntactically equivalent to the 
  3171.   APL object from which they were derived, you need only replace the APL 
  3172.   definition in the workspace with the external name association; much like 
  3173.   copying an object. The remainder of the application is unmodified. 
  3174.  
  3175.  
  3176. ΓòÉΓòÉΓòÉ 11.2. Processor 11-Accessing External Routines ΓòÉΓòÉΓòÉ
  3177.  
  3178. Processor 11 provides facilities that allow access to objects outside the 
  3179. active workspace that are routines written in languages other than APL2. 
  3180. Non-APL routines can be functions and can be niladic or monadic. Once access to 
  3181. a routine is established through processor 11, the routine is treated like a 
  3182. locked APL function. 
  3183.  
  3184. APL2 and processor 11 manage the necessary housekeeping, and argument and 
  3185. result conversion, based upon descriptive information provided for each routine 
  3186. by the user. 
  3187.  
  3188. o Processor 11 Overview 
  3189. o QuadNA Left Argument Syntax 
  3190. o NAMES File Syntax for Processor 11 
  3191. o Array Patterns 
  3192.  
  3193.  
  3194. ΓòÉΓòÉΓòÉ 11.2.1. Processor 11 Overview ΓòÉΓòÉΓòÉ
  3195.  
  3196. Processor 11 manages the interface between the APL2 active workspace and 
  3197. non-APL routines outside the workspace. Processor 11 has the responsibility to 
  3198. load the non-APL routine, translate arguments from the APL2 workspace to a form 
  3199. the non-APL routine can work with, call the non-APL routine, and translate the 
  3200. routine's results to a form the APL2 interpreter can work with. 
  3201.  
  3202. Conceptually, non-APL routines are merely called by processor 11. Every time 
  3203. the user executes an expression that mentions the non-APL program, processor 11 
  3204. is called by the APL2 interpreter and it in turn calls the routine. Processor 
  3205. 11 requires several types of information to perform this task. 
  3206.  
  3207. Processor 11 needs to know about the arguments and results for each routine it 
  3208. calls. Since processor 11 translates arguments from APL2 workspace format to 
  3209. the non-APL routine's format, it needs to know what format the routine is 
  3210. expecting. Likewise, when the routine returns results, processor 11 needs to 
  3211. understand their format to be able to translate them to a workspace format. 
  3212. This information is provided in a NAMES file (see NAMES File Syntax for 
  3213. Processor 11). 
  3214.  
  3215. Before processor 11 can call a routine, it must locate the routine. Routines 
  3216. reside in DLLs. 
  3217.  
  3218.  
  3219. ΓòÉΓòÉΓòÉ 11.2.2. QuadNA Left Argument Syntax ΓòÉΓòÉΓòÉ
  3220.  
  3221. The APL2 system function ╨áNA is used to establish an association between a 
  3222. workspace name and an external program that processor 11 manages. The syntax of 
  3223. the ╨áNA expression can take three forms. 
  3224.  
  3225. The first form causes processor 11 to use the APL2 product's environment 
  3226. variable to locate the NAMES file. 
  3227.  
  3228.    3 11 ╨áNA 'object'
  3229.  
  3230. This form directs processor 11 to use its default search order to locate a 
  3231. NAMES file entry for object. The search order progresses as follows: 
  3232.  
  3233.  1. Processor 11 looks for the default environment variable that is named 
  3234.     APLP11. This variable is usually set by the APL2 invocation command file. 
  3235.     If the environment variable is not found, the system proceeds as if it 
  3236.     contained the simple name aplnm011.nam. 
  3237.  
  3238.     The environment variable contains the file name of a NAMES file. The file 
  3239.     name can be fully qualified. When APL2 is installed, the default for the 
  3240.     NAMES file is aplnm011.nam. 
  3241.  
  3242.  2. Processor 11 attempts to open the specified file using standard operating 
  3243.     system facilities. 
  3244.  
  3245.     For OS/2, it searches the current directory and then the directories 
  3246.     specified in the DPATH variable if the file cannot be found otherwise. 
  3247.  
  3248.     If the NAMES file is not found, the association fails. 
  3249.  
  3250.  3. Processor 11 searches the NAMES file for an entry for object. If an entry 
  3251.     is not found, the association fails. 
  3252.  
  3253. The second ╨áNA form causes processor 11 to use an environment variable other 
  3254. than APLP11 to locate the NAMES file. 
  3255.  
  3256.    '(envvar)' 11 ╨áNA object
  3257. This form directs processor 11 to use the environment variable named envvar. 
  3258. The search follows the same progression using the environment variable envvar 
  3259. rather than APLP11. 
  3260.  
  3261. The third ╨áNA form supplies processor 11 with the file name of the NAMES file 
  3262. directly. 
  3263.  
  3264.    '<filename>' 11 ╨áNA 'object'
  3265.  
  3266. This form directs processor 11 to use the NAMES file filename. The search for 
  3267. filename  follows the same progression bypassing the use of an environment 
  3268. variable. 
  3269.  
  3270.  
  3271. ΓòÉΓòÉΓòÉ 11.2.3. NAMES File Syntax for Processor 11 ΓòÉΓòÉΓòÉ
  3272.  
  3273. This section discusses the format and contents of the NAMES file. 
  3274.  
  3275. NAMES files are text files that contain comment records (an "*" in column 1) 
  3276. and case insensitive keywords (that start with a ":" and end with ".") and 
  3277. descriptive information (anything following the keyword, up to the next keyword 
  3278. or end of record, except for trailing blanks). The maximum record length 
  3279. allowed is 254 characters. The syntax of each noncomment record is: 
  3280. :keyword.Descriptive text. More than one keyword/text pair can be on each 
  3281. noncomment line. 
  3282.  
  3283. The description of each routine is located by a :NICK. keyword with the 
  3284. descriptive information being the name by which processor 11 knows it, and ends 
  3285. at the next :NICK. keyword or the end of the file. 
  3286.  
  3287. The descriptive text for each keyword can contain colons and periods provided 
  3288. that they cannot be interpreted as keywords. It is not valid to use any 
  3289. sequence consisting of a colon, a letter, optionally one or more additional 
  3290. letters or numbers, and finally a period. 
  3291.  
  3292. Certain arguments, however, require patterns of more than 254 characters. To 
  3293. accommodate this requirement, the argument can be described in successive 
  3294. records in a NAMES file, each of which is prefixed with an appropriate argument 
  3295. keyword. The total length for all the descriptive text associated with a 
  3296. keyword is 511 characters. (Use preceding blanks in additional descriptive text 
  3297. if blanks are required between phrases.) For example: 
  3298.  
  3299.       :RARG.(G0 1 3) (1 E8 *)
  3300.       :RARG.(I4 2 * 10)
  3301.       :RARG.(I4 2 10 *)
  3302.  
  3303. o Routine Descriptor Keywords 
  3304.  
  3305.  
  3306. ΓòÉΓòÉΓòÉ 11.2.3.1. Routine Descriptor Keywords ΓòÉΓòÉΓòÉ
  3307.  
  3308. This section describes the routine descriptor keywords and the :MACRO. facility 
  3309. that enables you to substitute portions of a line with a macro. 
  3310.  
  3311. The :MACRO. facility is a one-line shorthand notation. Once a macro name is 
  3312. defined, all the subsequent instances of $(name) in the same file are replaced 
  3313. with the definition portion of the line. The syntax for :MACRO. is: 
  3314.  
  3315.    :MACRO.name definition
  3316. For example, a macro defined as: 
  3317.  
  3318.    :MACRO.CHARP (G4 0) (S1 1 *)
  3319.  
  3320. Can be used later on as: 
  3321.  
  3322.    :RSLT. $(CHARP)    This is the same as :RSLT. (G4 0) (S1 1 *)
  3323.  
  3324. Macros must be defined before the first :NICK. keyword, and are invoked by 
  3325. $(name). The :MACRO. facility allows 20 levels of nested macros. Any keywords 
  3326. appearing in the definition are treated as normal text. Leading and trailing 
  3327. spaces are ignored. 
  3328.  
  3329. External Routine Descriptor Keywords describes the external routine descriptor 
  3330. keywords. 
  3331.  
  3332.  
  3333. ΓòÉΓòÉΓòÉ 11.2.3.1.1. External Routine Descriptor Keywords - Part 1 ΓòÉΓòÉΓòÉ
  3334.  
  3335.  
  3336. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  3337.  
  3338. Keyword 
  3339.  
  3340.  
  3341. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  3342.  
  3343. Use 
  3344.  
  3345.  
  3346. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  3347.  
  3348. :NICK.name 
  3349.  
  3350.  
  3351. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  3352.  
  3353. Specifies the name of the external routine. The same name must be specified in 
  3354. the right argument of ╨áNA. This keyword is used to associate the routine 
  3355. description following the keyword with the specified name. 
  3356.  
  3357.  
  3358. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  3359.  
  3360. :LINK.type 
  3361.  
  3362.  
  3363. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  3364.  
  3365. Specifies the type of program linkage to be used when calling the routine. The 
  3366. following value is valid: 
  3367. :link.SYSTEM 
  3368.  
  3369. This describes the default linkage supported by most languages. For OS/2, this 
  3370. is _System. 
  3371.  
  3372.  
  3373. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  3374.  
  3375. MORE... 
  3376.  
  3377.  
  3378. ΓòÉΓòÉΓòÉ 11.2.3.1.2. External Routine Descriptor Keywords - Part 2 ΓòÉΓòÉΓòÉ
  3379.  
  3380.  
  3381. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  3382.  
  3383. Keyword 
  3384.  
  3385.  
  3386. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  3387.  
  3388. Use 
  3389.  
  3390.  
  3391. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  3392.  
  3393. :DESC.description 
  3394.  
  3395.  
  3396. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  3397.  
  3398. Allows inclusion of descriptive text in a routine description. Where the 
  3399. descriptive text exceeds the record length of a NAMES file, multiple records of 
  3400. text can be included, but each must be prefixed by a :DESC. keyword. Comments 
  3401. can also be included in the NAMES file by placing an asterisk in column 1 of 
  3402. comment records. 
  3403.  
  3404.  
  3405. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  3406.  
  3407. :RARG.pattern 
  3408.  
  3409.  
  3410. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  3411.  
  3412. Specifies a pattern for the right argument of the external routine. See Array 
  3413. Patterns for details. 
  3414.  
  3415.  
  3416. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  3417.  
  3418. :RSLT.pattern 
  3419.  
  3420.  
  3421. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  3422.  
  3423. Specifies a pattern for the result of the external routine. > cannot be used in 
  3424. a :RSLT. pattern. See Result Patterns for details. 
  3425.  
  3426.  
  3427. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  3428.  
  3429. MORE... 
  3430.  
  3431.  
  3432. ΓòÉΓòÉΓòÉ 11.2.3.1.3. External Routine Descriptor Keywords - Part 3 ΓòÉΓòÉΓòÉ
  3433.  
  3434.  
  3435. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  3436.  
  3437. Keyword 
  3438.  
  3439.  
  3440. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  3441.  
  3442. Use 
  3443.  
  3444.  
  3445. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  3446.  
  3447. :VALENCE.er fv ov 
  3448.  
  3449.  
  3450. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  3451.  
  3452. Specifies the valences of the routine. It becomes 1 ╨áAT for the routine. 
  3453.  
  3454. er specifies whether the routine produces an explicit result. If er is 0, the 
  3455. routine does not produce an explicit result. If er is 1, the routine produces 
  3456. an explicit result. 
  3457.  
  3458. fv specifies whether the routine is niladic or monadic. If fv is 0, the routine 
  3459. is niladic. If fv is 1, the routine is monadic. 
  3460.  
  3461. ov must be 0. 
  3462.  
  3463. This keyword is optional. It defaults to :VALENCE.1 1 0. 
  3464.  
  3465.  
  3466. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  3467.  
  3468. MORE... 
  3469.  
  3470.  
  3471. ΓòÉΓòÉΓòÉ 11.2.3.1.4. External Routine Descriptor Keywords - Part 4 ΓòÉΓòÉΓòÉ
  3472.  
  3473.  
  3474. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  3475.  
  3476. Keyword 
  3477.  
  3478.  
  3479. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  3480.  
  3481. Use 
  3482.  
  3483.  
  3484. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  3485.  
  3486. :LIB.file 
  3487.  
  3488.  
  3489. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  3490.  
  3491. Names the executable file that contains the entry point listed in the :PROC. 
  3492. keyword. The name can be fully qualified. This must be a DLL. 
  3493.  
  3494.  
  3495. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  3496.  
  3497. :PROC.entrypoint 
  3498.  
  3499.  
  3500. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  3501.  
  3502. Contains the entry point in the executable file named in the :LIB. keyword. The 
  3503. entry point name is case sensitive. 
  3504.  
  3505.  
  3506. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  3507.  
  3508. :PATH.fullpath 
  3509. :PATH.(envvar)partialpath 
  3510.  
  3511.  
  3512. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  3513.  
  3514. Path used to locate the executable file specified in the :LIB. keyword. If the 
  3515. path begins with "(" it is evaluated as the name of an environment variable 
  3516. that gives a path to locate the executable. 
  3517.  
  3518.  
  3519. ΓòÉΓòÉΓòÉ 11.2.4. Array Patterns ΓòÉΓòÉΓòÉ
  3520.  
  3521. The :RARG. and :RSLT. keywords are used to specify the expected arguments and 
  3522. results for an external routine. 
  3523.  
  3524. When an external name is encountered during the execution of an APL expression, 
  3525. APL compares the actual arguments against the patterns provided in the 
  3526. routine's description. If possible, APL converts the actual arguments to match 
  3527. the patterns so the external routine receives its argument data in an expected 
  3528. and predictable form. If it is not possible to accomplish the conversion, or if 
  3529. an inconsistency is found between the actual arguments and the patterns, APL 
  3530. issues an appropriate error message. 
  3531.  
  3532. When the external routine completes, if the :RSLT. keyword has been used, APL 
  3533. uses the pattern specified in the :RSLT. keyword to convert the data returned 
  3534. by the routine to an APL2 array. 
  3535.  
  3536. An array pattern is a keyword value or character vector that describes the 
  3537. structure and type of an array. In addition to using array patterns to describe 
  3538. routine arguments and results, array patterns are used with several external 
  3539. functions supplied with APL2. Array patterns are given as the left argument of 
  3540. the external functions RTA and ATR, and are produced by the external function 
  3541. PFA. 
  3542.  
  3543. o Array Item Patterns 
  3544. o Nested or Mixed Arrays 
  3545. o Array Patterns for Non-APL Programs 
  3546. o Array Patterns for ATR, PFA, and RTA 
  3547.  
  3548.  
  3549. ΓòÉΓòÉΓòÉ 11.2.4.1. Array Item Patterns ΓòÉΓòÉΓòÉ
  3550.  
  3551. The general form of an array item within an array pattern is as follows: 
  3552.  
  3553. ([count][>]type rank[shape]) 
  3554.  
  3555. Where: 
  3556.  
  3557. (                 An optional indicator for readability. Inclusion or omission 
  3558.                   has no effect on processing. 
  3559.  
  3560. count             An optional integer or *, indicating the number of items in 
  3561.                   the array. This field can be omitted if the number of items 
  3562.                   is fully specified by the shape below. It can be coded as * 
  3563.                   if the number of items is fully specified by the shape, or if 
  3564.                   a variable number of items is permitted. 
  3565.  
  3566. >                 An optional update indicator of an argument that is set by 
  3567.                   the function. Such an argument is passed by name, as seen by 
  3568.                   the caller. The data provided by the calling program must be 
  3569.                   a character vector containing the name of an APL array. The 
  3570.                   content of that array is passed to the called program, and 
  3571.                   any updates to its argument are returned in that variable. 
  3572.  
  3573.                   Note:  The "result indicator" (<) defined for APL2/TSO and 
  3574.                   APL2/CMS is not implemented on any other platforms. 
  3575.  
  3576. type              A required data representation indicator. The following codes 
  3577.                   are supported: 
  3578.  
  3579.    B1    Boolean - one bit per item 
  3580.    B8    Integer byte (unsigned) - one byte per item 
  3581.    I2    Integer halfword - 2 bytes per item 
  3582.    I4    Integer fullword - 4 bytes per item 
  3583.    E4    Real single precision - 4 bytes per item 
  3584.    E8    Real double precision - 8 bytes per item 
  3585.    J8    Complex single precision - 8 bytes per item 
  3586.    J16   Complex double precision - 16 bytes per item 
  3587.    S1    Null terminated character string - variable length 
  3588.    C1    Character byte - one byte per item 
  3589.    C2    Character halfword - 2 bytes per item 
  3590.    C4    Character fullword - 4 bytes per item 
  3591.    X0    Skipped data - one byte per item 
  3592.    G0    General object 
  3593.    G4    General object - pointer type 
  3594.  
  3595. rank              A required integer showing the number of dimensions. 
  3596.  
  3597. shape             A set of integers, one per dimension (empty if rank is zero). 
  3598.                   If varying shapes are accepted, one or more items of the 
  3599.                   shape can be specified as * in the :RARG. keyword. 
  3600.  
  3601. )                 A readability indicator that must be provided if, and only 
  3602.                   if, the corresponding "(" was used. 
  3603.  
  3604. The elements of the pattern must be separated from one another by one or more 
  3605. blanks or parentheses. 
  3606.  
  3607. o Array Item Pattern Examples 
  3608.  
  3609.  
  3610. ΓòÉΓòÉΓòÉ 11.2.4.1.1. Array Item Pattern Examples ΓòÉΓòÉΓòÉ
  3611.  
  3612. The following are examples of arrays with the array item patterns that describe 
  3613. them. 
  3614.  
  3615. Array                         Array Pattern 
  3616.  
  3617. 'ABC'                         (3 C1 1 3) 
  3618.                               C1 1 3 
  3619.  
  3620. 2 3 4                         (3 I4 1 3) 
  3621.                               I4 1 3 
  3622.  
  3623.  
  3624. ΓòÉΓòÉΓòÉ 11.2.4.2. Nested or Mixed Arrays ΓòÉΓòÉΓòÉ
  3625.  
  3626. The pattern for a nested or mixed array is a recursive structure in which the 
  3627. first subpattern has type = G0 or G4 (general object). Each subpattern can be 
  3628. surrounded by parentheses to make it easier to read. Parentheses do not 
  3629. indicate nesting; nesting can only be designated by using a G0 or G4 type. Each 
  3630. subpattern can be either an array item pattern or a group of items as defined 
  3631. here. 
  3632.  
  3633. o Nested or Mixed Array Pattern Examples 
  3634.  
  3635.  
  3636. ΓòÉΓòÉΓòÉ 11.2.4.2.1. Nested or Mixed Array Pattern Examples ΓòÉΓòÉΓòÉ
  3637.  
  3638. The following are examples of arrays with nested or mixed array patterns: 
  3639.  
  3640. 'ABCD',2 3 4   (7 G0 1 7)(C1 0)(C1 0)(C1 0)(C1 0)(I4 0)(I4 0)(I4 0)
  3641.                7 G0 1 7 C1 0 C1 0 C1 0 C1 0 I4 0 I4 0 I4 0
  3642. 'ABCD' (2 3 4)     (2 G0 1 2)(4 C1 1 4)(3 I4 1 3)
  3643.                    G0 1 2 C1 1 4 I4 1 3
  3644.  
  3645. As is shown in the examples above, a general object implies a recursive pattern 
  3646. where the first item is of type G0 (or G4). The count field in that item 
  3647. determines the number of additional array patterns that must follow. 
  3648.  
  3649. Note:  The functions ATR, PFA, and RTA do not permit all the forms of array 
  3650. patterns. See Supplied External Routines for restrictions that apply. 
  3651.  
  3652.  
  3653. ΓòÉΓòÉΓòÉ 11.2.4.3. Array Patterns for Non-APL Programs ΓòÉΓòÉΓòÉ
  3654.  
  3655. Array patterns are most frequently used to define the interface to a program 
  3656. written in some language other than APL. These patterns are provided in NAMES 
  3657. files, as discussed in QuadNA Left Argument Syntax. 
  3658.  
  3659. If a single pattern descriptor is used, the APL array is converted as necessary 
  3660. to match the specified data format, and then passed directly to the program as 
  3661. unstructured data. 
  3662.  
  3663. Processor 11 uses argument patterns for two purposes: 
  3664.  
  3665. o Conformability checks on a routine's argument 
  3666. o To determine how to pass the argument to the external routine 
  3667.  
  3668. It is useful to start by thinking of how arguments are passed to the external 
  3669. routine and to work backward from there to argument patterns and finally to the 
  3670. APL data structure needed to satisfy the patterns. 
  3671.  
  3672. Consider first a routine that accepts a 4-byte integer and a 4-byte floating 
  3673. point number as arguments. To write the pattern for this, begin by saying that 
  3674. there are two arguments, and then list them: 
  3675.  
  3676.   :RARG. (2 G0 ...) (1 I4 ...) (1 E4 ...)
  3677.  
  3678. Focus on the type descriptors (G0, I4, and E4) and the number to their left, 
  3679. which is the number of items being described. The numbers to the right of the 
  3680. type descriptor deal with the data as viewed by APL. 
  3681.  
  3682. Now consider what happens if the second parameter is an array of floating point 
  3683. numbers. Some languages make it possible to pass such an array directly, but 
  3684. more typically it is passed as a pointer to the array. Here is the pattern for 
  3685. a parameter list containing the integer as before, but also including a pointer 
  3686. to an array of 6 floating point numbers: 
  3687.  
  3688.   :RARG.(2 G0 ...) (1 I4 ...) (1 G4 ...) (6 E4 ...)
  3689.  
  3690. The first pattern descriptor still says there are two parameters, but the 
  3691. second parameter is now a G descriptor. Every G descriptor is followed by, and 
  3692. includes, as many subdescriptors as the number of items it defines. 
  3693.  
  3694. Some languages treat "string" as a special data type, but both APL and C treat 
  3695. it essentially as an array of characters. Like other arrays it is most commonly 
  3696. pointed to rather than passed directly. In this example, a character string and 
  3697. a floating point array are passed: 
  3698.  
  3699.   :RARG.(2 G0 ...) (1 G4 ...) (20 S1 ... ) (1 G4 ...) (6 E4 ...)
  3700.  
  3701. Because the S1 is subordinate to the first G4, the two of them together count 
  3702. for only one of the two items defined by the initial G0. 
  3703.  
  3704. An argument being passed can also be a structure. Such structures are typically 
  3705. pointed to rather than being passed directly. A G0 is used to define the 
  3706. structure, but a G4 is also used (as above) to specify the pointer to it. 
  3707. Consider a program that expects a single argument, which is a pointer to a 
  3708. structure containing an integer and an 8-character name: 
  3709.  
  3710.   :RARG.(1 G0 ...) (1 G4 ...) (2 G0 ...) (1 I4 ... ) (8 C1 ...)
  3711.  
  3712. You cannot replace the (1 G4) followed by the (2 G0) with a single (2 G4). (2 
  3713. G4) implies two pointers, rather than a single pointer to two items. 
  3714.  
  3715. Structures can contain pointers to other structures, which are represented by 
  3716. G4 entries within the structure definition, or they can contain other 
  3717. structures imbedded within them. In the next example, the 8-character name has 
  3718. been replaced by a date composed of day (within the month), a 3-character 
  3719. abbreviated month name, and a year. The day and year are both expressed as 
  3720. 2-byte integers. Assume that the program is expecting the year to start on an 
  3721. even-byte boundary, so there is an unused byte in front of it: 
  3722.  
  3723.   :RARG.1 G0... 1 G4... 2 G0... 1 I4... 3 G0... 1 I2... 3 C1... 1 X0... 1 I2...
  3724.  
  3725. These examples can help you generate patterns for any interface definition you 
  3726. might encounter; except for all those unexplained periods. 
  3727.  
  3728. The first number after the type descriptor is always the rank as seen by the 
  3729. APL program, and is normally set to whatever is most natural for the APL 
  3730. programmer. For data entries (all except G0 or G4) this is completely 
  3731. determined by the nature of the data. 
  3732.  
  3733. For G0 entries, this is always a vector (rank 1), except that when a single 
  3734. parameter is being passed the first G0 is often more conveniently defined as a 
  3735. scalar (rank 0). G4 entries usually represent a single pointer, and can best be 
  3736. represented as scalars. The exception is an array of pointers, which is of 
  3737. whatever rank is most appropriate to the data (usually rank 1). 
  3738.  
  3739. Given the rank and the total number of items, you can deduce the shape 
  3740. information. Revisiting the examples above, all multi-item pattern descriptors 
  3741. are most naturally represented as vectors except for the 6-item floating point 
  3742. array, which could be a matrix. It is assumed to be a 2 by 3 matrix below. The 
  3743. first example becomes: 
  3744.  
  3745.   :RARG. (G0 1 2) (I4 0) (E4 0)
  3746.  
  3747. The numbers used earlier to the left of the type descriptor are optional, 
  3748. because they can be computed from the information on the right, so they have 
  3749. been omitted here for brevity. Viewed from the APL standpoint this is a 2-item 
  3750. vector, each item being a number. APL programs make no distinction between 
  3751. integers and floating point numbers, so this is a simple numeric vector (depth 
  3752. 1). 
  3753.  
  3754. The second example (viewed beginning with the G0) is also a 2-item vector, but 
  3755. this time the second item is an array. Here is what the completed pattern looks 
  3756. like along with sample data for the call: 
  3757.  
  3758.   :RARG.(G0 1 2) (I4 0) (G4 0) (E4 2 2 3)
  3759.        75 (╤é2 3╤å1.2 2.3 3.4 4.3 3.2 2.1)
  3760.  
  3761. Note:  The array needs to be enclosed because the G4 0 tells APL to expect a 
  3762. scalar. 
  3763.  
  3764. The third example is very similar. Note in the sample data below that only 11 
  3765. characters are passed even though the field was defined as 20 bytes long. This 
  3766. is permitted for null-terminated strings. 
  3767.  
  3768. Note:  There must be room at the end of the data for the null terminator. So at 
  3769. most 19 characters can be passed in this 20-byte string. 
  3770.  
  3771. For null-delimited strings that are not updated by the non-APL program, there 
  3772. is no need to set a specific size ahead of time. Such strings are often defined 
  3773. with a length of "*". 
  3774.  
  3775.   :RARG.(G0 1 2) (G4 0) (S1 1 20) (G4 0) (E4 2 2 3)
  3776. func (╤é'Hello there')(╤é2 3╤å1.2 2.3 3.4 4.3 3.2 2.1)
  3777.  
  3778. The G4 implies not only a pointer as seen by the non-APL program, but also a 
  3779. level of nesting as seen from APL. But rules in this area can be a bit 
  3780. slippery, as the next example shows. Two changes have been introduced: a 
  3781. structure and a single parameter. Assume for the moment that the initial G0 
  3782. specifies a 1-item vector: 
  3783.  
  3784.   :RARG.(G0 1 1) (G4 0) (G0 1 2) (I4 0) (C1 1 8)
  3785.  
  3786. You might want to say that the following is valid data: 
  3787.  
  3788.       13 'Thomas  '
  3789.  
  3790. But this is a two-item array, and the pattern calls for a single item. Data 
  3791. such as that is appropriate for a routine that expected two arguments rather 
  3792. than one, so the data needs to be enclosed. That yields to a scalar value, and 
  3793. the pattern calls for a 1-item vector. Thus, given the pattern as assumed, 
  3794. correct data is: 
  3795.  
  3796.   :RARG.(G0 1 1) (G4 0) (G0 1 2) (I4 0) (C1 1 8)
  3797.       ,╤é╤é13 'Thomas  '
  3798.  
  3799. Now the reason for the earlier comment about a scalar G0 becomes clear. A 
  3800. simpler form of the interface is: 
  3801.  
  3802.   :RARG.(G0 0) (G4 0) (G0 1 2) (I4 0) (C1 1 8)
  3803.       ╤é╤é13 'Thomas  '
  3804.  
  3805. It is typical of single-parameter interfaces that the APL program needs to 
  3806. explicitly enclose the data. 
  3807.  
  3808. A simple case requiring an explicit enclose is that of a routine that accepts a 
  3809. pointer to a character string as its only parameter: 
  3810.  
  3811.   :RARG.(G0 0) (G4 0) (S1 1 *)
  3812.          ╤é╤é'string'
  3813.  
  3814. Although the first enclose of the character string seems reasonable, because it 
  3815. implies "pointer to," the second enclose seems a bit unnatural, and is due to 
  3816. the strict conformance to the rule used so far in the examples: The argument 
  3817. descriptor is started with a G0 tag that identifies the number of parameters. 
  3818.  
  3819. In the case of single-parameter arguments, it is often desirable to completely 
  3820. elide the (G0 0) descriptor from the :RARG. tags: 
  3821.  
  3822.   :RARG.(G4 0) (S1 1 *)
  3823.          ╤é'string'
  3824.  
  3825. This simplification is most commonly seen in the case of a single parameter 
  3826. that is a simple number. For example: 
  3827.  
  3828.   :RARG.(G0 0) (I4 0)
  3829.  
  3830. Is simplified to: 
  3831.  
  3832.   :RARG.I4 0
  3833.  
  3834. o Updated Arguments 
  3835. o Result Patterns 
  3836. o Explicit Results and Function Valence 
  3837.  
  3838.  
  3839. ΓòÉΓòÉΓòÉ 11.2.4.3.1. Updated Arguments ΓòÉΓòÉΓòÉ
  3840.  
  3841. Routines in some compiled languages typically do not distinguish between input 
  3842. arguments and results. They are passed a list of pointers to the values that 
  3843. may represent input arguments, values to be updated, or preallocated space for 
  3844. results. APL functions, on the other hand, take arguments that are never 
  3845. updated and produce explicit results that were not previously passed as 
  3846. arguments to the function. For example: 
  3847.  
  3848.       ΓòûRESULTΓò£COMPUTE ARG
  3849. [1]   RESULTΓò£2╤ùARG
  3850. [2]   Γòû
  3851.       COMPUTE 10
  3852. 20
  3853.  
  3854. APL requires that functions that update argument data in place be called with 
  3855. the names of the arguments rather than their values. For example: 
  3856.  
  3857.       ΓòûUPDATE ARG
  3858. [1]    ╨┐ARG,'Γò£2╤ù',ARG
  3859. [2]   Γòû
  3860.       NUMBERΓò£10
  3861.       UPDATE 'NUMBER'
  3862.       NUMBER
  3863. 20
  3864.  
  3865. Both approaches are supported by processor 11. Argument items that are to be 
  3866. updated in place are indicated with the symbol > preceding the representation 
  3867. type in the argument pattern. For example, a non-APL routine that expects two 
  3868. integer vectors as arguments, the second of which is to be updated in place, 
  3869. would be described: 
  3870.  
  3871.       :RARG.(G4 1 2) (I4 1 3) (>I4 1 3)
  3872.  
  3873. As with APL functions, such routines must be called with the names of the 
  3874. arguments to be updated rather than their values: 
  3875.  
  3876.       RESULTΓò£3╤å0
  3877.       COMPUTE (1 2 3) 'RESULT'
  3878.  
  3879. APL checks to ensure that arguments updated with the > symbol are names and not 
  3880. values. If names are not found when the function call occurs, an error results. 
  3881. Items that are to be updated must always be passed using a pointer, so there 
  3882. must always be a G4 level ahead of any descriptor that contains a ">". 
  3883.  
  3884. If an external routine misbehaves, for example by writing beyond the end of an 
  3885. argument that is able to be updated, workspace damage and possibly SYSTEM ERROR 
  3886. may occur. It is essential that valid argument patterns be constructed before 
  3887. calling an external function. 
  3888.  
  3889.  
  3890. ΓòÉΓòÉΓòÉ 11.2.4.3.2. Result Patterns ΓòÉΓòÉΓòÉ
  3891.  
  3892. The :RSLT. keyword can be specified on routines with an explicit result to 
  3893. describe the form of the supplied result. 
  3894.  
  3895. If supplied, :RSLT. must be specified with a pattern. The pattern takes the 
  3896. same form as argument patterns described above, with the following exceptions: 
  3897.  
  3898. o "*" cannot be used in the pattern. 
  3899. o The ">" optional update indicator cannot be used in the pattern. 
  3900.  
  3901. If the routine produces an explicit result and a :RSLT. keyword is supplied, 
  3902. the pattern is used to format the routine's result. If a :RSLT. keyword is not 
  3903. supplied, the right argument is returned. The indirect values in the argument 
  3904. might have been updated. 
  3905.  
  3906. If the routine does not produce an explicit result, the :RSLT. keyword is 
  3907. ignored. 
  3908.  
  3909.  
  3910. ΓòÉΓòÉΓòÉ 11.2.4.3.3. Explicit Results and Function Valence ΓòÉΓòÉΓòÉ
  3911.  
  3912. This section discusses: 
  3913.  
  3914. o Explicit results 
  3915. o Function valence 
  3916.  
  3917.  
  3918. ΓòÉΓòÉΓòÉ 11.2.4.3.3.1. Explicit Results ΓòÉΓòÉΓòÉ
  3919.  
  3920. The first value of the :VALENCE. keyword is used to specify whether the routine 
  3921. returns an explicit result. This value is used to specify what 1 ╨áAT should 
  3922. return when it is used to query the valence of the routine. 
  3923.  
  3924. If the valence tag specifies that the routine returns an explicit result and no 
  3925. :RSLT. tag is supplied, then the right argument is returned as the result. The 
  3926. routine may have updated the argument. 
  3927.  
  3928. If the valence keyword specifies that the routine does not return an explicit 
  3929. result, then the :RSLT. keyword is ignored. 
  3930.  
  3931.  
  3932. ΓòÉΓòÉΓòÉ 11.2.4.3.3.2. Function Valence ΓòÉΓòÉΓòÉ
  3933.  
  3934. Function valence is controlled by the second value coded in the :VALENCE. 
  3935. keyword. 
  3936.  
  3937. Niladic functions do not accept arguments. If a :RARG. keyword is supplied for 
  3938. a niladic routine, it is ignored. 
  3939.  
  3940. Monadic functions require a :RARG. keyword. 
  3941.  
  3942.  
  3943. ΓòÉΓòÉΓòÉ 11.2.4.4. Array Patterns for ATR, PFA, and RTA ΓòÉΓòÉΓòÉ
  3944.  
  3945. ATR, PFA, and RTA 
  3946.  
  3947. External routines ATR and RTA accept array patterns as arguments, and external 
  3948. routine PFA returns an array pattern as its result. See Supplied External 
  3949. Routines for the definition of these functions. 
  3950.  
  3951. The following restrictions apply to patterns used as arguments to these 
  3952. routines: 
  3953.  
  3954. o A G0 descriptor can be used as needed, but the G4 descriptor is not 
  3955.   supported. 
  3956.  
  3957. o The ">" optional update indicator is not permitted. 
  3958.  
  3959. o A single "*" can appear in either the count or shape field if its value can 
  3960.   be computed from the other field. (count is the product of values in shape.) 
  3961.  
  3962. Patterns returned by PFA also meet these restrictions, and always have count 
  3963. and shape fully specified. 
  3964.  
  3965.  
  3966. ΓòÉΓòÉΓòÉ 12. Supplied External Routines ΓòÉΓòÉΓòÉ
  3967.  
  3968. The following external routines are supplied with APL2/2. 
  3969.  
  3970. o ATR 
  3971. o FILE 
  3972. o GETENV 
  3973. o PFA 
  3974. o RTA 
  3975.  
  3976. The external routines discussed in this chapter are called with processor 11, 
  3977. and depend on the default file, aplnm011.nam. For example: 
  3978.  
  3979.       3 11 ╨áNA 'FILE'
  3980. 1
  3981.       AΓò£FILE 'data.bin'
  3982.  
  3983. o ATR 
  3984. o FILE 
  3985. o GETENV 
  3986. o PFA 
  3987. o RTA 
  3988.  
  3989.  
  3990. ΓòÉΓòÉΓòÉ 12.1. ATR ΓòÉΓòÉΓòÉ
  3991.  
  3992.      record Γò£ pattern ATR array
  3993.  
  3994. This function converts an APL array into a character vector containing 
  3995. structured data, based on a pattern that describes the desired format. It can 
  3996. be used to map APL arrays into records or structures expected by other 
  3997. languages, or expected by services called through AP 145. 
  3998.  
  3999. array             An APL2 array whose structure and data types should be 
  4000.                   compatible with the pattern. 
  4001.  
  4002.                   Note:  The internal APL storage form need not match the 
  4003.                   pattern exactly, so long as it is possible to convert it to 
  4004.                   the pattern format using APL system tolerance. 
  4005.  
  4006. pattern           A character vector containing a formalized description of the 
  4007.                   fields within the record. Array patterns are defined in Array 
  4008.                   Patterns. The pattern may not contain a * unless it can be 
  4009.                   resolved to an integer based on other information in the item 
  4010.                   description. The pattern may not contain the > or < marks. 
  4011.  
  4012. record            A character vector produced by converting the data in the 
  4013.                   array according to the pattern. DOMAIN ERROR is signalled if 
  4014.                   an impossible conversion is implied by the pattern. 
  4015.                   Incompatible data structures result in LENGTH ERROR or RANK 
  4016.                   ERROR. 
  4017.  
  4018. Note:  External function RTA is the inverse of ATR. 
  4019.  
  4020.  
  4021. ΓòÉΓòÉΓòÉ 12.2. FILE ΓòÉΓòÉΓòÉ
  4022.  
  4023.     data Γò£ FILE filespec
  4024.     rc Γò£ data FILE filespec
  4025.  
  4026. This function reads or writes a system file in binary mode. The monadic form 
  4027. reads a file, while the dyadic form writes it. FILE is a stream read/write 
  4028. function. It is not record-oriented, and it does not perform data conversion. 
  4029.  
  4030. filespec          A character vector that identifies a file. It may be a simple 
  4031.                   file name, or may include a path specification. 
  4032.  
  4033. data              The content of the file as a simple character vector. Any 
  4034.                   line or record separators are retained as they existed in the 
  4035.                   file. 
  4036.  
  4037.                   Any error conditions encountered while reading a file are 
  4038.                   reported by returning a numeric result in place of the data. 
  4039.  
  4040. rc                The return code from writing a file; normally zero. Nonzero 
  4041.                   return codes are system dependent. 
  4042.  
  4043. Hint  You can use the APL membership (╤Ä) and partition (╤é) functions to parse 
  4044. an ASCII text file into a vector of vectors. 
  4045.  
  4046.  
  4047. ΓòÉΓòÉΓòÉ 12.3. GETENV ΓòÉΓòÉΓòÉ
  4048.  
  4049.      vector Γò£ GETENV env_variable
  4050.  
  4051. This function returns the value of an environment variable as a character 
  4052. vector. 
  4053.  
  4054. env_variable      An enclosed character vector that identifies the environment 
  4055.                   variable. Depending on the platform, environment variable 
  4056.                   names can be case sensitive. For maximum application 
  4057.                   portability, use the exact case for the name of the 
  4058.                   environment variable. 
  4059.  
  4060. vector            An enclosed character vector that represents the value of the 
  4061.                   environment variable. If the environment variable is not set, 
  4062.                   then vector is ╤é╤î0. 
  4063.  
  4064.  
  4065. ΓòÉΓòÉΓòÉ 12.4. PFA ΓòÉΓòÉΓòÉ
  4066.  
  4067.      pattern Γò£ PFA array
  4068.  
  4069. This function creates an array pattern from an array. 
  4070.  
  4071. array             Any APL array. 
  4072.  
  4073. pattern           A character vector containing a formalized description of the 
  4074.                   fields within the record. Array patterns are defined in Array 
  4075.                   Patterns. The patterns produced by PFA always contain the 
  4076.                   optional parentheses and the count field. They never contain 
  4077.                   the > or < markers or an *. 
  4078.  
  4079. PFA may be used as a tutorial on how to write patterns. Because the types 
  4080. selected in the pattern reflect the internal storage mechanism in use at the 
  4081. moment, the same array may give different patterns at different times or on 
  4082. different platforms. 
  4083.  
  4084.  
  4085. ΓòÉΓòÉΓòÉ 12.5. RTA ΓòÉΓòÉΓòÉ
  4086.  
  4087.      array Γò£ pattern RTA record
  4088.  
  4089. This function converts a character vector containing structured data into an 
  4090. APL array, based on a pattern that describes the format of the data. It can be 
  4091. used to map records or structures produced by other languages, or expected by 
  4092. services called through AP 145, into APL arrays of any required depth. 
  4093.  
  4094. record            A character vector containing data in the form that it was 
  4095.                   stored by some other program. No check is made for incorrect 
  4096.                   lengths. The result is unpredictable if the record is shorter 
  4097.                   than the structure described in the pattern. 
  4098.  
  4099. pattern           A character vector containing a formalized description of the 
  4100.                   fields within the record. Array patterns are defined in Array 
  4101.                   Patterns. The pattern may not contain an asterisk (*) unless 
  4102.                   it can be resolved to an integer based on other information 
  4103.                   in the item description. The pattern may not contain the > or 
  4104.                   < marks. 
  4105.  
  4106. array             An APL2 array whose format is determined by the pattern, and 
  4107.                   whose content is taken from the record. 
  4108.  
  4109. Note:  External function ATR is the inverse of RTA. 
  4110.  
  4111.  
  4112. ΓòÉΓòÉΓòÉ 13. Supplied Workspaces ΓòÉΓòÉΓòÉ
  4113.  
  4114. IBM APL2/2 supplies a number of workspaces to perform various tasks, and many 
  4115. of these are common to other supported APL2 environments. These workspaces 
  4116. contain functions that you can call from your programs. The functions listed 
  4117. can also be used as examples of how to program with the corresponding auxiliary 
  4118. processors in the APL2/2 system. For example: 
  4119.  
  4120. o FILE uses the file auxiliary processors (AP 210 and AP 211) 
  4121.  
  4122. o The OS2 workspace uses the OS/2 host command auxiliary processor (AP 100) 
  4123.  
  4124. o The DEMO124 workspace demonstrates some of the capabilities of the 
  4125.   full-screen auxiliary processor (AP 124) 
  4126.  
  4127. o The DEMO145 workspace demonstrates some of the capabilities of the OS/2 
  4128.   services auxiliary processor (AP 145) 
  4129.  
  4130. o The DEMO207 workspace demonstrates some of the capabilities of the Universal 
  4131.   Graphics auxiliary processor (AP 207) 
  4132.  
  4133. o The EDIT and EDITOR_2 functions in the EDIT workspace and the AP124 workspace 
  4134.   use the text display auxiliary processor (AP 124) 
  4135.  
  4136. Each public workspace contains variables with information about the workspace. 
  4137. These variables are: ABSTRACT, DESCRIBE, and HOW. 
  4138.  
  4139. The workspaces distributed with APL2/2 are assigned to either library 1 or 
  4140. library 2, as is shown in Workspace Library Assignments. 
  4141.  
  4142. o The AP124 Workspace 
  4143. o The DEMO124 Workspace 
  4144. o The DEMO145 Workspace 
  4145. o The DEMO207 Workspace 
  4146. o The DISPLAY Workspace 
  4147. o The EDIT Workspace 
  4148. o The EXAMPLES Workspace 
  4149. o The FILE Workspace 
  4150. o The GRAPHPAK Workspace 
  4151. o The IDIOMS Workspace 
  4152. o The MATHFNS Workspace 
  4153. o The MIGRATE Workspace 
  4154. o The OS2 Workspace 
  4155. o The PMTOOLS Workspace 
  4156. o The PMWIN Workspace 
  4157. o The PRINTWS Workspace 
  4158. o The SQL Workspace 
  4159. o The TIME Workspace 
  4160. o The UTILITY Workspace 
  4161.  
  4162.  
  4163. ΓòÉΓòÉΓòÉ 13.1. Workspace Library Assignments - Part 1 ΓòÉΓòÉΓòÉ
  4164.  
  4165.  
  4166. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4167.  
  4168. Name 
  4169.  
  4170.  
  4171. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4172.  
  4173. Library  Number 
  4174.  
  4175.  
  4176. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4177.  
  4178. Function 
  4179.  
  4180.  
  4181. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4182.  
  4183. AP124 
  4184.  
  4185.  
  4186. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4187.  
  4188.  
  4189.  
  4190. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4191.  
  4192. Aids in building text display applications 
  4193.  
  4194.  
  4195. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4196.  
  4197. DEMO124 
  4198.  
  4199.  
  4200. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4201.  
  4202.  
  4203.  
  4204. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4205.  
  4206. Demonstrations of some of the capabilities of the text display auxiliary 
  4207. processor (AP 124) 
  4208.  
  4209.  
  4210. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4211.  
  4212. DEMO145 
  4213.  
  4214.  
  4215. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4216.  
  4217.  
  4218.  
  4219. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4220.  
  4221. Demonstrations of some of the capabilities of the OS/2 services auxiliary 
  4222. processor (AP 145) 
  4223.  
  4224.  
  4225. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4226.  
  4227. DEMO207 
  4228.  
  4229.  
  4230. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4231.  
  4232.  
  4233.  
  4234. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4235.  
  4236. Demonstrations of some of the capabilities of the universal graphics auxiliary 
  4237. processor (AP 207) 
  4238.  
  4239.  
  4240. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4241.  
  4242. DISPLAY 
  4243.  
  4244.  
  4245. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4246.  
  4247.  
  4248.  
  4249. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4250.  
  4251. Display of array data structure 
  4252.  
  4253.  
  4254. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4255.  
  4256. EDIT 
  4257.  
  4258.  
  4259. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4260.  
  4261.  
  4262.  
  4263. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4264.  
  4265. Compatibility editors 
  4266.  
  4267.  
  4268. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4269.  
  4270. EXAMPLES 
  4271.  
  4272.  
  4273. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4274.  
  4275.  
  4276.  
  4277. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4278.  
  4279. Usage examples of APL2 
  4280.  
  4281.  
  4282. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4283.  
  4284. FILE 
  4285.  
  4286.  
  4287. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4288.  
  4289.  
  4290.  
  4291. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4292.  
  4293. Tools for accessing OS/2 files 
  4294.  
  4295.  
  4296. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4297.  
  4298. MORE... 
  4299.  
  4300.  
  4301. ΓòÉΓòÉΓòÉ 13.2. Workspace Library Assignments - Part 2 ΓòÉΓòÉΓòÉ
  4302.  
  4303.  
  4304. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4305.  
  4306. Name 
  4307.  
  4308.  
  4309. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4310.  
  4311. Library  Number 
  4312.  
  4313.  
  4314. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4315.  
  4316. Function 
  4317.  
  4318.  
  4319. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4320.  
  4321. GRAPHPAK 
  4322.  
  4323.  
  4324. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4325.  
  4326.  
  4327.  
  4328. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4329.  
  4330. Business and analytic graphics 
  4331.  
  4332.  
  4333. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4334.  
  4335. IDIOMS 
  4336.  
  4337.  
  4338. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4339.  
  4340.  
  4341.  
  4342. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4343.  
  4344. Catalog of common APL2 phrases 
  4345.  
  4346.  
  4347. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4348.  
  4349. MATHFNS 
  4350.  
  4351.  
  4352. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4353.  
  4354.  
  4355.  
  4356. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4357.  
  4358. Mathematical functions 
  4359.  
  4360.  
  4361. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4362.  
  4363. MIGRATE 
  4364.  
  4365.  
  4366. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4367.  
  4368.  
  4369.  
  4370. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4371.  
  4372. Conversion of applications  migrated from other systems 
  4373.  
  4374.  
  4375. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4376.  
  4377. OS2 
  4378.  
  4379.  
  4380. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4381.  
  4382.  
  4383.  
  4384. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4385.  
  4386. Tools to access OS/2 functions, commands, or files 
  4387.  
  4388.  
  4389. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4390.  
  4391. PMTOOLS 
  4392.  
  4393.  
  4394. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4395.  
  4396.  
  4397.  
  4398. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4399.  
  4400. A toolkit for writing OS/2 Presentation Manager applications 
  4401.  
  4402.  
  4403. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4404.  
  4405. PMWIN 
  4406.  
  4407.  
  4408. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4409.  
  4410.  
  4411.  
  4412. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4413.  
  4414. A collection of variables with the values defined in the OS/2 Developer's 
  4415. Toolkit header files 
  4416.  
  4417.  
  4418. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4419.  
  4420. PRINTWS 
  4421.  
  4422.  
  4423. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4424.  
  4425.  
  4426.  
  4427. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4428.  
  4429. Printing workspace contents 
  4430.  
  4431.  
  4432. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4433.  
  4434. SQL 
  4435.  
  4436.  
  4437. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4438.  
  4439.  
  4440.  
  4441. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4442.  
  4443. Tools for using relational database auxiliary processors 
  4444.  
  4445.  
  4446. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4447.  
  4448. TIME 
  4449.  
  4450.  
  4451. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4452.  
  4453.  
  4454.  
  4455. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4456.  
  4457. Monitor performance 
  4458.  
  4459.  
  4460. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4461.  
  4462. UTILITY 
  4463.  
  4464.  
  4465. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4466.  
  4467.  
  4468.  
  4469. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4470.  
  4471. Manipulations and services beyond those provided by primitive operations 
  4472.  
  4473.  
  4474. ΓòÉΓòÉΓòÉ 13.3. The AP124 Workspace ΓòÉΓòÉΓòÉ
  4475.  
  4476. This workspace contains a set of cover functions to assist in the use of the 
  4477. text display auxiliary processor, AP 124, in an application. A screen 
  4478. definition facility makes it possible to define a screen as a set of fields, 
  4479. each one with its own name or number, where information can be sent or 
  4480. retrieved by means of appropriate functions. 
  4481.  
  4482. o Fundamentals 
  4483. o Building a Menu 
  4484. o Primary Functions 
  4485. o Additional Functions 
  4486. o AP124 Internal Operation and Global Variables 
  4487.  
  4488.  
  4489. ΓòÉΓòÉΓòÉ 13.3.1. Fundamentals ΓòÉΓòÉΓòÉ
  4490.  
  4491. The window you are using on your display should be regarded as a character 
  4492. array for the purposes of the following discussion. 
  4493.  
  4494. The size of this array defaults to 25 by 80, but the window can be resized 
  4495. using normal OS/2 Desktop facilities. This area can be subdivided into smaller 
  4496. rectangular sections that are more convenient to your data processing needs. 
  4497. These rectangular areas are called fields. The text display auxiliary 
  4498. processor, AP 124, works only in terms of fields. Functions in the AP124 
  4499. workspace perform actions to a field or a group of fields. 
  4500.  
  4501. Every field has a type, which determines how it can be acted upon. There are 
  4502. three basic types of fields: 
  4503.  
  4504. Input/output Allowing input from the keyboard to be typed and displayed 
  4505.  
  4506. Numeric input only/any output Allowing only numbers to be input from the 
  4507.          keyboard, but allowing any characters to be displayed 
  4508.  
  4509. Output only Capable of receiving data from an APL2 function but not from the 
  4510.          keyboard. 
  4511.  
  4512. Fields also have attributes that define how the information contained in the 
  4513. fields is to be displayed. An attribute is expressed as an integer value, 
  4514. depending on the actual display to be used, and defines the color of the field. 
  4515.  
  4516.  
  4517. ΓòÉΓòÉΓòÉ 13.3.2. Building a Menu ΓòÉΓòÉΓòÉ
  4518.  
  4519. As an example of the use of the AP124 workspace, a sample screen is defined, 
  4520. containing some information and requesting data from a user. The AP124 
  4521. workspace includes functions enabling you to define menus quickly, and making 
  4522. it easy to maintain them. 
  4523.  
  4524. Assume the menu you wish to define is for an overtime payment system. You 
  4525. should collect and process the following data: 
  4526.  
  4527. o Employee serial number 
  4528. o Employee name 
  4529. o Number of overtime hours worked each day (Monday to Sunday) 
  4530. o Per-day overtime rate. This is fixed at the moment, but can be adjusted at a 
  4531.   later date. 
  4532.  
  4533. Now we have to step though some simple decisions to design the screen. The 
  4534. following is a representation of the desired menu: 
  4535.  
  4536.   00000000011111111112222222222333333333344444444445555555555666666666677777777778
  4537.   12345678901234567890123456789012345678901234567890123456789012345678901234567890
  4538. 01                             APL2 Overtime System
  4539. 02--------------------------------------------------------------------------------
  4540. 03
  4541. 04
  4542. 05                    Input the following data, press Enter:
  4543. 06
  4544. 07                       Employee Number   XXXXXXX
  4545. 08                       Employee Name     XXXXXXXXXXXXXXX
  4546. 09
  4547. 10                          Mon  Tue  Wed  Thu  Fri  Sat  Sun
  4548. 11                    Hours X.XX X.XX X.XX X.XX X.XX X.XX X.XX
  4549. 12                    Rate  1.25 1.25 1.25 1.25 1.25 1.50 2.00
  4550. 13
  4551. 14
  4552. 15
  4553. 16
  4554. 17
  4555. 18
  4556. 19
  4557. 20--------------------------------------------------------------------------------
  4558. 21                  The following options can also be used:
  4559. 22
  4560. 23                      F1 - Help             F3 - Exit
  4561. 24
  4562. 25
  4563.  
  4564. The row and column numbers at the top and left of the diagram are included just 
  4565. for clarity. 
  4566.  
  4567. A name is needed for the screen. Use the name OVERTIME. 
  4568.  
  4569. Now that everything is planned and ready, we will look at the AP124 workspace 
  4570. functions we need to build the menu. 
  4571.  
  4572. o FSDEF - Define fields 
  4573. o FSSHOW - Display a panel 
  4574.  
  4575.  
  4576. ΓòÉΓòÉΓòÉ 13.3.2.1. FSDEF - Define fields ΓòÉΓòÉΓòÉ
  4577.  
  4578. FSDEF 'Menu_Name' 
  4579.  
  4580. the first time it is used, and: 
  4581.  
  4582. Field_Def FSDEF 'Field_Data' 
  4583.  
  4584. once per field to be defined. 
  4585.  
  4586. Menu_Name defines the name by which this screen is to be known. This name 
  4587. should begin with an uppercase or lowercase letter, the delta (Γòó) character or 
  4588. the delta underbar (╤₧) character; it can continue with any of these, plus the 
  4589. digits 0-9, overbar (┬ñ) or underbar (_). 
  4590.  
  4591. Field_Def is a vector containing four, five, or six elements with the following 
  4592. information: 
  4593.  
  4594.  1. Start row of the field 
  4595.  
  4596.  2. Start column of the field 
  4597.  
  4598.  3. Field height 
  4599.  
  4600.  4. Field width 
  4601.  
  4602.     The fifth and sixth elements of the vector are optional, and are defined 
  4603.     as: 
  4604.  
  4605.  5. Field type: 
  4606.  
  4607.    0 - Input/output/selectable 
  4608.    1 - Numeric input only/any output/selectable 
  4609.    2 - Output only (the default) 
  4610.    3 - Output only/selectable 
  4611.  
  4612.  6. Field Attribute: an integer between 0 and 255. The default field attribute 
  4613.     is 1, which normally gives blue characters on a black background. The 
  4614.     following diagram shows the meanings of the bits of the display attribute 
  4615.     byte on color display adapters: 
  4616.  
  4617.         7   6   5   4   3   2   1   0
  4618.         ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ   ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  4619.               Γöé               Γöé
  4620.               Γöé               ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ Foreground color (4 bits)
  4621.               Γöé
  4622.               ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ Background color (4 bits)
  4623.  
  4624.     The combinations of colors available are: See AP 124 colors. 
  4625.  
  4626. If the field width is given as 0, the width is automatically derived from the 
  4627. value of Field_Data. This is the data to be written on the field at initial 
  4628. menu usage. It must be a character vector. 
  4629.  
  4630. Alternatively, the following field definition format can be used to assign a 
  4631. name to the field being defined: 
  4632.  
  4633. Field_Def FSDEF 'Field_Name' FSDEF 'Field_Data' 
  4634.  
  4635. Field_Def and Field_Data are the same as above. Field_Name is the name you wish 
  4636. to assign to this field. This name should consist of upper or lowercase 
  4637. letters, digits, delta (Γòó), delta underbar (╤₧), overbar (┬ñ) or underbar (_). 
  4638.  
  4639. You can also use FSDEF to define a group of fields so that they can be referred 
  4640. to collectively. This is especially useful for reading or writing a set of 
  4641. fields or for changing the attribute of a complete set of fields, or for 
  4642. switching the type of a set of fields from input/output to output only, or vice 
  4643. versa. This is done in the following way: 
  4644.  
  4645. 'Group_Name' FSDEF Number_of_Fields 
  4646.  
  4647. Number_of_Fields is the number of fields defined immediately before the 
  4648. execution of this line that are to be included in the group. You can define 
  4649. nonconsecutive fields as a group of fields by issuing this call with the same 
  4650. group name after each individual field or after each consecutive group of 
  4651. fields. Groups must be exclusive. Each field can be defined as being in only 
  4652. one group. 
  4653.  
  4654. If workspace is at a premium, any repeated items in the screen definition 
  4655. variables can be converted to aliases of the first unique occurrence of each 
  4656. item by using FSDEF with an empty character right argument: 
  4657.  
  4658. FSDEF ''
  4659.  
  4660. You can use this after each (or the last) menu is defined, and after you have 
  4661. copied menus into the active workspace, using the )IN, )PIN, )COPY, or )PCOPY 
  4662. system commands. 
  4663.  
  4664.  
  4665. ΓòÉΓòÉΓòÉ 13.3.2.1.1. AP 124 colors ΓòÉΓòÉΓòÉ
  4666.  
  4667.  
  4668. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4669.  
  4670. Code 
  4671.  
  4672.  
  4673. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4674.  
  4675. Bits 
  4676.  
  4677.  
  4678. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4679.  
  4680. Color 
  4681.  
  4682.  
  4683. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4684.  
  4685.  
  4686. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4687.  
  4688. Code 
  4689.  
  4690.  
  4691. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4692.  
  4693. Bits 
  4694.  
  4695.  
  4696. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4697.  
  4698. Color 
  4699.  
  4700.  
  4701. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4702.  
  4703.  
  4704.  
  4705. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4706.  
  4707. 0 0 0 0 
  4708.  
  4709.  
  4710. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4711.  
  4712. Black 
  4713.  
  4714.  
  4715. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4716.  
  4717.  
  4718. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4719.  
  4720.  
  4721.  
  4722. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4723.  
  4724. 1 0 0 0 
  4725.  
  4726.  
  4727. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4728.  
  4729. Light Gray 
  4730.  
  4731.  
  4732. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4733.  
  4734.  
  4735.  
  4736. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4737.  
  4738. 0 0 0 1 
  4739.  
  4740.  
  4741. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4742.  
  4743. Blue 
  4744.  
  4745.  
  4746. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4747.  
  4748.  
  4749. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4750.  
  4751.  
  4752.  
  4753. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4754.  
  4755. 1 0 0 1 
  4756.  
  4757.  
  4758. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4759.  
  4760. Light Blue 
  4761.  
  4762.  
  4763. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4764.  
  4765.  
  4766.  
  4767. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4768.  
  4769. 0 0 1 0 
  4770.  
  4771.  
  4772. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4773.  
  4774. Green 
  4775.  
  4776.  
  4777. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4778.  
  4779.  
  4780. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4781.  
  4782. 10 
  4783.  
  4784.  
  4785. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4786.  
  4787. 1 0 1 0 
  4788.  
  4789.  
  4790. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4791.  
  4792. Light Green 
  4793.  
  4794.  
  4795. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4796.  
  4797.  
  4798.  
  4799. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4800.  
  4801. 0 0 1 1 
  4802.  
  4803.  
  4804. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4805.  
  4806. Cyan 
  4807.  
  4808.  
  4809. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4810.  
  4811.  
  4812. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4813.  
  4814. 11 
  4815.  
  4816.  
  4817. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4818.  
  4819. 1 0 1 1 
  4820.  
  4821.  
  4822. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4823.  
  4824. Light Cyan 
  4825.  
  4826.  
  4827. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4828.  
  4829.  
  4830.  
  4831. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4832.  
  4833. 0 1 0 0 
  4834.  
  4835.  
  4836. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4837.  
  4838. Red 
  4839.  
  4840.  
  4841. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4842.  
  4843.  
  4844. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4845.  
  4846. 12 
  4847.  
  4848.  
  4849. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4850.  
  4851. 1 1 0 0 
  4852.  
  4853.  
  4854. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4855.  
  4856. Light Red 
  4857.  
  4858.  
  4859. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4860.  
  4861.  
  4862.  
  4863. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4864.  
  4865. 0 1 0 1 
  4866.  
  4867.  
  4868. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4869.  
  4870. Magenta 
  4871.  
  4872.  
  4873. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4874.  
  4875.  
  4876. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4877.  
  4878. 13 
  4879.  
  4880.  
  4881. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4882.  
  4883. 1 1 0 1 
  4884.  
  4885.  
  4886. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4887.  
  4888. Light Magenta 
  4889.  
  4890.  
  4891. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4892.  
  4893.  
  4894.  
  4895. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4896.  
  4897. 0 1 1 0 
  4898.  
  4899.  
  4900. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4901.  
  4902. Yellow 
  4903.  
  4904.  
  4905. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4906.  
  4907.  
  4908. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4909.  
  4910. 14 
  4911.  
  4912.  
  4913. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4914.  
  4915. 1 1 1 0 
  4916.  
  4917.  
  4918. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4919.  
  4920. Brown 
  4921.  
  4922.  
  4923. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4924.  
  4925.  
  4926.  
  4927. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4928.  
  4929. 0 1 1 1 
  4930.  
  4931.  
  4932. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4933.  
  4934. Gray 
  4935.  
  4936.  
  4937. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4938.  
  4939.  
  4940. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4941.  
  4942. 15 
  4943.  
  4944.  
  4945. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4946.  
  4947. 1 1 1 1 
  4948.  
  4949.  
  4950. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  4951.  
  4952. White 
  4953.  
  4954.  
  4955. ΓòÉΓòÉΓòÉ 13.3.2.2. FSSHOW - Display a panel ΓòÉΓòÉΓòÉ
  4956.  
  4957. FSSHOW 'Menu_Name'
  4958.  
  4959. FSSHOW can be used to display a menu after it has been completely defined. 
  4960.  
  4961. The following example is a function written to define our sample menu and 
  4962. display it on the screen. 
  4963.  
  4964.     Γòû
  4965. [0]  DEFINE;A
  4966. [1]   FSDEF 'OVERTIME'
  4967. [2]   1 30 1 20 2 7 FSDEF 'APL2 Overtime System'
  4968. [3]   2 1 1 80 2 7 FSDEF 80╤å'-'
  4969. [4]   AΓò£'Input the following data, press Enter:'
  4970. [5]   5 21 1 0 2 7 FSDEF 'PROMPT' FSDEF A
  4971. [6]   7 24 1 16 2 7 FSDEF 'Employee Number'
  4972. [7]   8 24 1 16 2 7 FSDEF 'Employee Name'
  4973. [8]   7 42 1 7 0 7 FSDEF 'Emp_No' FSDEF ''
  4974. [9]   8 42 1 15 0 7 FSDEF 'Emp_Name' FSDEF ''
  4975. [10]  AΓò£'Mon  Tue  Wed  Thu  Fri  Sat  Sun'
  4976. [11]  10 27 1 0 2 7 FSDEF A
  4977. [12]  11 21 1 0 2 7 FSDEF 'Hours'
  4978. [13]  12 21 1 0 2 7 FSDEF 'Rate'
  4979. [14]  11 27 1 4 0 7 FSDEF 'Hours_Mon' FSDEF ''
  4980. [15]  11 32 1 4 0 7 FSDEF 'Hours_Tue' FSDEF ''
  4981. [16]  11 37 1 4 0 7 FSDEF 'Hours_Wed' FSDEF ''
  4982. [17]  11 42 1 4 0 7 FSDEF 'Hours_Thu' FSDEF ''
  4983. [18]  11 47 1 4 0 7 FSDEF 'Hours_Fri' FSDEF ''
  4984. [19]  11 52 1 4 0 7 FSDEF 'Hours_Sat' FSDEF ''
  4985. [20]  11 57 1 4 0 7 FSDEF 'Hours_Sun' FSDEF ''
  4986. [21]  'Hours' FSDEF 7
  4987. [22]  12 27 1 4 0 7 FSDEF 'Rate_Mon' FSDEF '1.25'
  4988. [23]  12 32 1 4 0 7 FSDEF 'Rate_Tue' FSDEF '1.25'
  4989. [24]  12 37 1 4 0 7 FSDEF 'Rate_Wed' FSDEF '1.25'
  4990. [25]  12 42 1 4 0 7 FSDEF 'Rate_Thu' FSDEF '1.25'
  4991. [26]  12 47 1 4 0 7 FSDEF 'Rate_Fri' FSDEF '1.25'
  4992. [27]  12 52 1 4 0 7 FSDEF 'Rate_Sat' FSDEF '1.50'
  4993. [28]  12 57 1 4 0 7 FSDEF 'Rate_Sun' FSDEF '2.00'
  4994. [29]  'Rates' FSDEF 7
  4995. [30]  18 21 1 40 2 7 FSDEF 'Msg_Area' FSDEF ''
  4996. [31]  20 1 1 80 2 7 FSDEF 80╤å'-'
  4997. [32]  AΓò£'The following options can also be used:'
  4998. [33]  21 10 1 0 2 7 FSDEF A
  4999. [34]  AΓò£'F1 - Help             F3 - Exit'
  5000. [35]  23 23 1 0 2 7 FSDEF A
  5001. [36]  FSDEF ''
  5002. [37]  FSSHOW 'OVERTIME'
  5003.     Γòû
  5004.  
  5005. Notice that some of the fields have been named. These are the ones the example 
  5006. operates with. Also observe that an extra field, called Msg_Area, has been 
  5007. defined, where the program can output any errors found in input validation, or 
  5008. any other system message. 
  5009.  
  5010. Ordinarily a function is written like this for each panel in the system. Each 
  5011. of these panel definition functions then needs to be executed only once in 
  5012. order to create the global variables that are used by other functions in this 
  5013. workspace. (They would have to be re-executed if you change the panels by 
  5014. editing the appropriate panel definition function.) 
  5015.  
  5016.  
  5017. ΓòÉΓòÉΓòÉ 13.3.3. Primary Functions ΓòÉΓòÉΓòÉ
  5018.  
  5019. Look at the next stage of combining the screen with the function that drives 
  5020. the input-output operation (a "driver"). The following cover functions can be 
  5021. used in the driver: 
  5022.  
  5023. o FSUSE - Initialize a panel 
  5024. o FSSETCURSOR - Position the cursor 
  5025. o FSWRITE - Put data into fields 
  5026. o FSWAIT - Wait for a user response 
  5027. o FSREAD/FSREADV - Read field contents 
  5028.  
  5029.  
  5030. ΓòÉΓòÉΓòÉ 13.3.3.1. FSUSE - Initialize a panel ΓòÉΓòÉΓòÉ
  5031.  
  5032. ZΓò£FSUSE 'Menu_Name'
  5033.  
  5034. This function initializes the menu named Menu_Name. This is the basic call used 
  5035. to allow you to start using a menu. It shares variables with AP124, loads the 
  5036. indicated predefined menu, and leaves you ready to use it. The result is 0 if 
  5037. successful, 1 if the function failed. 
  5038.  
  5039.  
  5040. ΓòÉΓòÉΓòÉ 13.3.3.2. FSSETCURSOR - Position the cursor ΓòÉΓòÉΓòÉ
  5041.  
  5042. ZΓò£Cursor_Offset FSSETCURSOR Field
  5043.  
  5044. This call sets the cursor in a specific field or at any position on the screen. 
  5045. The left argument can be omitted, and the cursor offset is defaulted to the 
  5046. first position in that field. Field can be either a character vector containing 
  5047. the name you selected for the field during definition of the menu, or an 
  5048. integer field number. The result is 0 if successful, 1 if the function failed. 
  5049.  
  5050.  
  5051. ΓòÉΓòÉΓòÉ 13.3.3.3. FSWRITE - Put data into fields ΓòÉΓòÉΓòÉ
  5052.  
  5053. ZΓò£Data FSWRITE Field
  5054.  
  5055. This function writes Data to the field or fields identified by Field. Field can 
  5056. be either a character scalar or vector to identify a single field, or a 
  5057. character matrix of names or a vector of names to identify several fields. 
  5058. Field can also be a numeric scalar or a vector of field numbers. If one field 
  5059. is being written, Data should be a character scalar, a vector, or a one-row 
  5060. matrix. If more than one field is being written, Data must be a character 
  5061. matrix with the corresponding number of rows or a vector of character arrays 
  5062. with the corresponding number of elements. The result is 0 if successful, 1 if 
  5063. the function failed. 
  5064.  
  5065.  
  5066. ΓòÉΓòÉΓòÉ 13.3.3.4. FSWAIT - Wait for a user response ΓòÉΓòÉΓòÉ
  5067.  
  5068. ZΓò£FSWAIT
  5069.  
  5070. This function displays the active menu, and waits for user input. When a user 
  5071. presses a certain key (see below), control returns to APL2, and the result, Z, 
  5072. of function FSWAIT is the following: 
  5073.  
  5074. o Z[1]   - Return code: 0 if successful, otherwise 1. 
  5075.  
  5076. o Z[2 3] - Key pressed to complete the call: 
  5077.  
  5078.    0 0  -     Enter 
  5079.    1 n  -     An F Key, where n is the key number (1 to 48) 
  5080.    4 1  -     Esc 
  5081.    6 1  -     Home 
  5082.    6 2  -     End 
  5083.    6 3  -     PageUp 
  5084.    6 4  -     PageDown 
  5085.    6 5  -     Ctrl-PageUp 
  5086.    6 6  -     Ctrl-PageDown 
  5087.    6 7  -     Ctrl-Left 
  5088.    6 8  -     Ctrl-Right 
  5089.    6 9  -     Ctrl-Up 
  5090.    6 10 -     Ctrl-Down 
  5091.  
  5092. o Z[4]   - Field number where cursor was located at return to APL2, or zero if 
  5093.   it was outside all the fields. 
  5094.  
  5095. o Z[5 6] - Cursor offset (row/column) into that field. If field was zero, then 
  5096.   offset is from the top-left corner of the screen. 
  5097.  
  5098. o Z[7...] - List of fields updated during this FSWAIT request. 
  5099.  
  5100. The list of updated fields that is returned enables you to optimize the panel 
  5101. processing time. In general, it is necessary to read and validate only those 
  5102. fields, rather than to read back and check all of the fields, which, for a very 
  5103. large screen, could be a very long process. 
  5104.  
  5105.  
  5106. ΓòÉΓòÉΓòÉ 13.3.3.5. FSREAD/FSREADV - Read field contents ΓòÉΓòÉΓòÉ
  5107.  
  5108. ZΓò£FSREAD Field
  5109.  
  5110. This function reads data from the field or fields identified by Field. Field 
  5111. can be either a character scalar or vector to identify a single field, or a 
  5112. character matrix of names or a vector of names to identify several fields. 
  5113. Field can also be a numeric scalar or a vector of field numbers. 
  5114.  
  5115. If the result, Z, is numeric, it is a return code indicating that the operation 
  5116. has failed. Otherwise, Z is a character matrix containing the requested field 
  5117. data. 
  5118.  
  5119. ZΓò£FSREADV Field
  5120.  
  5121. This function reads data from a field or a group of fields. If the result is 
  5122. numeric, it is a return code indicating that the operation failed. Otherwise, 
  5123. the result is a nested vector of character or numeric arrays containing the 
  5124. requested field or group field data. 
  5125.  
  5126.  
  5127. ΓòÉΓòÉΓòÉ 13.3.4. Additional Functions ΓòÉΓòÉΓòÉ
  5128.  
  5129. The following functions assist in the use of the screen. 
  5130.  
  5131. ZΓò£FSAPLOFF
  5132. ZΓò£FSAPLON
  5133.  
  5134. FSAPLOFF and FSAPLON turn the keyboard from APL2 to National mode (FSAPLOFF), 
  5135. and vice versa (FSAPLON). The result is 0 if successful, 1 if the function 
  5136. failed. 
  5137.  
  5138. ZΓò£FSBEEP
  5139.  
  5140. FSBEEP sets the beep flag. A beep sounds at the next read and wait call 
  5141. (FSWAIT). The result is 0 if successful, 1 if the function failed. 
  5142.  
  5143. ZΓò£FSCLEAR
  5144.  
  5145. Clears the display. The result is 0 if successful, 1 if the function failed. 
  5146.  
  5147. ZΓò£FSCLOSE
  5148.  
  5149. FSCLOSE retracts the AP124 shared variables and expunges all global variables 
  5150. associated with the AP124 full-screen functions (except the 'fsf',Name panel 
  5151. definition variables). It should be used at the end of your session. The result 
  5152. is 0 if successful, 1 if the function failed. 
  5153.  
  5154. ZΓò£FSCOPY
  5155.  
  5156. Returns the current screen contents as a matrix. 
  5157.  
  5158. ZΓò£FSFIELD Field_Name
  5159. ZΓûáFSFIELD Field_Number
  5160.  
  5161. This function translates a field name to the corresponding field number, or 
  5162. vice versa. 
  5163.  
  5164. ZΓò£FSFORMAT
  5165.  
  5166. Returns, in Z, the active format array. If this is used immediately after an 
  5167. FSOPEN, it returns a format array of one field completely covering the screen. 
  5168. You can use this to determine how many rows and columns are available for 
  5169. display on the screen. 
  5170.  
  5171. ZΓò£FSINKEY
  5172.  
  5173. Returns the next keyboard scan code. The result is a 6-element vector like the 
  5174. first 6 elements returned by FSWAIT, except that if the second element is zero 
  5175. then the third element may be either zero (for the Enter or New-line key), or 
  5176. any of the codes shown in AP 124 Extended Function Codes, and if the third 
  5177. element is zero then the second element may be either zero (for the Enter or 
  5178. New-line key), or a 0-origin ╨áAV index of the character entered. 
  5179.  
  5180. ZΓò£Data FSIWRITE Field
  5181.  
  5182. Immediate write of Data to the selected fields on the display. It is used in 
  5183. the same way as the FSWRITE function, described in FSWRITE - Put data into 
  5184. fields. 
  5185.  
  5186. ZΓò£FSMODE 'mode'
  5187.  
  5188. Clears the screen and establishes display mode indicated (APL2/PC 
  5189. compatibility). The result is 0 if successful, 1 if the function failed. 
  5190.  
  5191. ZΓò£FSOPEN
  5192.  
  5193. Shares variables with AP124. This function is used internally by FSUSE. The 
  5194. result is 0 if successful, 1 if the function failed. 
  5195.  
  5196. ZΓò£FSSCAN
  5197.  
  5198. Scan for a key pressed. The result is a 6-element vector like that returned by 
  5199. FSINKEY, except that if no key had been pressed, Z[2 3]  will be ┬ñ1 ┬ñ1. 
  5200.  
  5201. ZΓò£FSSCREEN
  5202.  
  5203. Return the contents of the screen. 
  5204.  
  5205. ZΓò£A FSSETFI Field
  5206.  
  5207. Changes the attribute of a field or a group of fields to A. The result is 0 if 
  5208. successful, 1 if the function failed. 
  5209.  
  5210. ZΓò£T FSSETFT Field
  5211.  
  5212. Changes the type of a field or a group of fields to T. The result is 0 if 
  5213. successful, 1 if the function failed. 
  5214.  
  5215. ZΓò£FSSTATUS
  5216.  
  5217. Returns the status of the session: 
  5218.  
  5219. Z[1] -     Return code of the AP124 status call (normally 0) 
  5220. Z[2] -     Keyboard mode (0 = national mode, 1 = APL2 mode) 
  5221. Z[3] -     Reserved; always 0 
  5222. Z[4] -     Reserved; always 1 
  5223. Z[5] -     Beep request pending (1 = beep pending) 
  5224. Z[6] -     Reserved; always 0 
  5225. Z[7] -     Cursor mode (0 = normal, 1 = field) 
  5226.  
  5227. ZΓò£FSTITLE Title
  5228.  
  5229. Sets the title bar on the AP 124 window to the character string named in Title. 
  5230. The result is 0 if successful, 1 if the function failed. 
  5231.  
  5232. Note:  The title bar cannot be set until after at least one field has been 
  5233. formatted (FSUSE or FSSHOW functions). 
  5234.  
  5235. o Example Driver Function 
  5236.  
  5237.  
  5238. ΓòÉΓòÉΓòÉ 13.3.4.1. Example Driver Function ΓòÉΓòÉΓòÉ
  5239.  
  5240. The following is an example of a driver function that uses the menu defined 
  5241. above: 
  5242.  
  5243. [0]  DRIVER;R;A
  5244. [1]   Γòò(FSOPEN)/E124
  5245. [2]   Γòò(FSUSE 'OVERTIME')/E124
  5246. [3]   Γòò(FSSETCURSOR 'Hours_Mon')/E124
  5247. [4]  ASK:Γòò(Γò₧RΓò£FSWAIT)/E124
  5248. [5]   Γòò(1=R[2])/FK
  5249. [6]  ╤ä Examine fields changed
  5250. [7]  ╤ä These are listed by 6ΓòƒR
  5251. [8]   AΓò£FSREAD 'Emp_No' 'Emp_Name' 'Hours' 'Rates'
  5252. [9]   ....
  5253. [..] FK:....
  5254. [..] E124:'Full-screen error in driver'
  5255.  
  5256.  
  5257. ΓòÉΓòÉΓòÉ 13.3.5. AP124 Internal Operation and Global Variables ΓòÉΓòÉΓòÉ
  5258.  
  5259. The FSOPEN function shares variables called Cfs and Dfs with AP124. It also 
  5260. creates a two-element numeric variable, called fss, containing the number of 
  5261. rows and columns that can be displayed. 
  5262.  
  5263. The FSDEF function creates a screen definition variable with the name 
  5264. 'fsf',Name, where Name is the menu name. The screen definition is stored as a 
  5265. three- or four-column nested matrix with one row for each field defined. The 
  5266. columns are: 
  5267.  
  5268.  1. Field format (six-element numeric vector) 
  5269.  2. Field contents (character vector) 
  5270.  3. Field name (character vector-empty vector for no name) 
  5271.  4. Group name that this field belongs to (character vector-empty vector if not 
  5272.     defined as a group member). This column is not present if no groups are 
  5273.     defined. 
  5274.  
  5275. The FSUSE function calls FSOPEN if the AP124 variables are not already shared, 
  5276. and then copies the group definition 'fsf',Name to variable fsf. It also adds 
  5277. an extra column to fsf containing the field numbers for each group definition. 
  5278.  
  5279.  
  5280. ΓòÉΓòÉΓòÉ 13.4. The DEMO124 Workspace ΓòÉΓòÉΓòÉ
  5281.  
  5282. This workspace is designed to give the user a sample of the capabilities of the 
  5283. AP 124 auxiliary processor. 
  5284.  
  5285. The demonstration provides an online reference to the various calls to AP 124, 
  5286. and shows some sample applications. 
  5287.  
  5288. The demonstration can be run by entering: 
  5289.  
  5290.       )LOAD 2 DEMO124
  5291.       DEMO
  5292.  
  5293.  
  5294. ΓòÉΓòÉΓòÉ 13.5. The DEMO145 Workspace ΓòÉΓòÉΓòÉ
  5295.  
  5296. This workspace contains functions that demonstrate the use of AP 145, the OS/2 
  5297. services processor. 
  5298.  
  5299. The demonstration illustrates how to use the dialog functions from the PMTOOLS 
  5300. workspace to process Presentation Manager dialogs. The demonstration also 
  5301. illustrates using the APL2 print object cover functions from PMTOOLS. 
  5302.  
  5303. The demonstration can be run by entering: 
  5304.  
  5305.       )LOAD 2 DEMO145
  5306.       DEMO
  5307.  
  5308.  
  5309. ΓòÉΓòÉΓòÉ 13.6. The DEMO207 Workspace ΓòÉΓòÉΓòÉ
  5310.  
  5311. This workspace is designed to give the user a sample of the capabilities of the 
  5312. Universal Graphics auxiliary processor, AP 207. 
  5313.  
  5314. The demonstration provides an online view of text characters in various sizes 
  5315. and orientations. It displays various geometric shapes that can be used in 
  5316. business graphics along with the possible colors and symbols available. An 
  5317. image is also displayed as part of the demonstration. 
  5318.  
  5319. The demonstration can be run by entering: 
  5320.  
  5321.       )LOAD 2 DEMO207
  5322.       DEMO
  5323.  
  5324.  
  5325. ΓòÉΓòÉΓòÉ 13.7. The DISPLAY Workspace ΓòÉΓòÉΓòÉ
  5326.  
  5327. This workspace contains DISPLAY, DISPLAYC, and DISPLAYG, which are functions 
  5328. useful in showing the structure of nested and mixed arrays. 
  5329.  
  5330. ZΓò£DISPLAY X
  5331. ZΓò£DISPLAYC X
  5332. ZΓò£DISPLAYG X
  5333.  
  5334. Z is a character matrix representing the array X. 
  5335.  
  5336. DISPLAY and DISPLAYG use box characters. DISPLAYG is identical to DISPLAY and 
  5337. is included for compatibility with the DISPLAY workspace distributed with 
  5338. APL2/370. DISPLAYC uses characters that display on all implementations. This is 
  5339. functionally equivalent to the DISPLAY function in the APL2/370 DISPLAY 
  5340. workspace. 
  5341.  
  5342. The following characters are used to convey shape information: 
  5343.  
  5344. Γòò or Γòƒ                 Indicates a dimension of at least one. 
  5345. ╤ë or ╤ê                 Indicates an axis of length zero. If an array is empty, 
  5346.                        its prototype is displayed. 
  5347. (None of the above)    Indicates no dimension (a rank 0 array). 
  5348.  
  5349. The following characters are used to convey type information: 
  5350.  
  5351. ~                      Indicates numeric. 
  5352. +                      Indicates mixed. 
  5353. ╤Ä                      Indicates nested. 
  5354. _                      Indicates a scalar character that is at the same depth 
  5355.                        as nonscalar arrays. 
  5356. (None of the above)    Indicates a character array that is not a simple scalar. 
  5357.  
  5358. To use each of the DISPLAY functions: 
  5359.  
  5360.       )PCOPY 1 DISPLAY DISPLAY DISPLAYC DISPLAYG
  5361. SAVED ...
  5362.     (DISPLAY ╤î5)   (DISPLAYC ╤î5)   (DISPLAYG ╤î5)
  5363.   ΓöîΓòòΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ  .Γòò--------.  ΓöîΓòòΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  5364.   Γöé1 2 3 4 5Γöé  Γöé1 2 3 4 5Γöé  Γöé1 2 3 4 5Γöé
  5365.   Γöö~ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ  '~--------'  Γöö~ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  5366.  
  5367.        XΓò£╤é╤î5
  5368.        (DISPLAY X) (DISPLAYC X) (DISPLAYG X)
  5369.   ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ  .-------------.  ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  5370.   Γöé ΓöîΓòòΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ Γöé  Γöé .Γòò--------. Γöé  Γöé ΓöîΓòòΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ Γöé
  5371.   Γöé Γöé1 2 3 4 5Γöé Γöé  Γöé Γöé1 2 3 4 5Γöé Γöé  Γöé Γöé1 2 3 4 5Γöé Γöé
  5372.   Γöé Γöö~ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ Γöé  Γöé '~--------' Γöé  Γöé Γöö~ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ Γöé
  5373.   Γöö╤ÄΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ  '╤Ä------------'  Γöö╤ÄΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  5374.  
  5375.        XΓò£(╤é╤é╤î4)(2 2╤å'ABCD')(2 2╤å'42' 'IS' 'THE' 'ANSWER')
  5376.        DISPLAY X
  5377.  ΓöîΓòòΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  5378.  Γöé ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ ΓöîΓòòΓöÇΓöÉ ΓöîΓòòΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ Γöé
  5379.  Γöé Γöé ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ Γöé ΓòƒABΓöé Γòƒ ΓöîΓòòΓöÇΓöÉ  ΓöîΓòòΓöÇΓöÉ     Γöé Γöé
  5380.  Γöé Γöé Γöé ΓöîΓòòΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ Γöé Γöé ΓöéCDΓöé Γöé Γöé42Γöé  ΓöéISΓöé     Γöé Γöé
  5381.  Γöé Γöé Γöé Γöé1 2 3 4Γöé Γöé Γöé ΓööΓöÇΓöÇΓöÿ Γöé ΓööΓöÇΓöÇΓöÿ  ΓööΓöÇΓöÇΓöÿ     Γöé Γöé
  5382.  Γöé Γöé Γöé Γöö~ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ Γöé Γöé      Γöé ΓöîΓòòΓöÇΓöÇΓöÉ ΓöîΓòòΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ Γöé Γöé
  5383.  Γöé Γöé Γöö╤ÄΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ Γöé      Γöé ΓöéTHEΓöé ΓöéANSWERΓöé Γöé Γöé
  5384.  Γöé Γöö╤ÄΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ      Γöé ΓööΓöÇΓöÇΓöÇΓöÿ ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ Γöé Γöé
  5385.  Γöé                        Γöö╤ÄΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ Γöé
  5386.  Γöö╤ÄΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  5387.  
  5388.        ╤åX
  5389.  3
  5390.        ╤åΓûáX
  5391.     2 2  2 2
  5392.        DISPLAY ╤åΓûáX
  5393.  ΓöîΓòòΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  5394.  Γöé Γöî╤ëΓöÉ ΓöîΓòòΓöÇΓöÇΓöÉ ΓöîΓòòΓöÇΓöÇΓöÉ Γöé
  5395.  Γöé Γöé0Γöé Γöé2 2Γöé Γöé2 2Γöé Γöé
  5396.  Γöé Γöö~Γöÿ Γöö~ΓöÇΓöÇΓöÿ Γöö~ΓöÇΓöÇΓöÿ Γöé
  5397.  Γöö╤ÄΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  5398.  
  5399.        DISPLAYC X
  5400.  .Γòò------------------------------------------.
  5401.  Γöé .---------------. .Γòò-. .Γòò---------------. Γöé
  5402.  Γöé Γöé .-----------. Γöé ΓòƒABΓöé Γòƒ .Γòò-.  .Γòò-.     Γöé Γöé
  5403.  Γöé Γöé Γöé .Γòò------. Γöé Γöé ΓöéCDΓöé Γöé Γöé42Γöé  ΓöéISΓöé     Γöé Γöé
  5404.  Γöé Γöé Γöé Γöé1 2 3 4Γöé Γöé Γöé '--' Γöé '--'  '--'     Γöé Γöé
  5405.  Γöé Γöé Γöé '~------' Γöé Γöé      Γöé .Γòò--. .Γòò-----. Γöé Γöé
  5406.  Γöé Γöé '╤Ä----------' Γöé      Γöé ΓöéTHEΓöé ΓöéANSWERΓöé Γöé Γöé
  5407.  Γöé '╤Ä--------------'      Γöé '---' '------' Γöé Γöé
  5408.  Γöé                        '╤Ä---------------' Γöé
  5409.  '╤Ä------------------------------------------'
  5410.  
  5411.        ╤åX
  5412.  3
  5413.        ╤åΓûáX
  5414.     2 2  2 2
  5415.        DISPLAY ╤åΓûáX
  5416.  .Γòò----------------.
  5417.  Γöé .╤ë. .Γòò--. .Γòò--. Γöé
  5418.  Γöé Γöé0Γöé Γöé2 2Γöé Γöé2 2Γöé Γöé
  5419.  Γöé '~' '~--' '~--' Γöé
  5420.  '╤Ä----------------'
  5421.  
  5422.  
  5423. ΓòÉΓòÉΓòÉ 13.8. The EDIT Workspace ΓòÉΓòÉΓòÉ
  5424.  
  5425. This workspace contains two alternative editors. 
  5426.  
  5427. o EDIT 
  5428. o EDITOR_2 (APL2/370-Compatible Full-Screen Editor) 
  5429.  
  5430.  
  5431. ΓòÉΓòÉΓòÉ 13.8.1. EDIT ΓòÉΓòÉΓòÉ
  5432.  
  5433. This is a simple, limited-function APL2 full-screen editor for editing defined 
  5434. functions and operators. It uses the text display auxiliary processor, AP 124. 
  5435.  
  5436. This editor can be used to create new defined functions or operators and to 
  5437. modify existing ones. 
  5438.  
  5439. To edit an APL2 function or operator with the editor, copy the EDIT workspace 
  5440. into your active workspace with the command: 
  5441.  
  5442.       )PCOPY 1 EDIT EDIT
  5443.  
  5444. If the name of the function you want to create or edit is FN1, enter: 
  5445.  
  5446. EDIT 'FN1'
  5447.  
  5448. After you invoke the editor, a window pops up and the function is displayed-or 
  5449. as much of it as can fit into the available screen area. Up to 24 lines of the 
  5450. function or operator are displayed; one line is reserved for definitions of 
  5451. function keys. 
  5452.  
  5453. You can now move the cursor, using the four arrow keys on the numeric keypad, 
  5454. change any character in the lines displayed, insert characters (with the Ins 
  5455. key), delete characters (with the Del key), delete to the end of a line (with 
  5456. the Ctrl-End key combination), delete to the beginning of a line (with the 
  5457. Ctrl-Home key combination), and move the cursor to the beginning of the next 
  5458. line (by pressing the Tab key). Also, you can use the function keys as 
  5459. indicated in the lowest line of the screen. The full purpose of these, and 
  5460. other special keys, is described below: 
  5461.  
  5462. F3        QUIT - Cancels function definition. No changes are kept. The function 
  5463.           remains as it was at the beginning of the edit session. If you have 
  5464.           made changes, you are prompted to confirm the intention to quit. 
  5465.  
  5466. F4        FILE - Ends function definition. All modifications to the function 
  5467.           are kept and the new definition of the function is established in the 
  5468.           active workspace. If this process fails, the bottom line of the 
  5469.           display is updated with an error message to indicate the line number 
  5470.           found to be in error. 
  5471.  
  5472. F5        TOP - Displays the first or top page of the function. 
  5473.  
  5474. F6        BOT - Displays the last or bottom portion of the function, with room 
  5475.           to add additional lines. 
  5476.  
  5477. F7        LINE - Clears the screen and displays only the line pointed to by the 
  5478.           current cursor position. You can use this to edit lines longer than 
  5479.           the screen width. The maximum line length this method allows is 800 
  5480.           characters. 
  5481.  
  5482. F8        INS - Inserts a new line after the current cursor position. 
  5483.  
  5484. Shift-F8  DEL - Deletes the line pointed to by the cursor. 
  5485.  
  5486. F9        EXEC - Executes the line pointed to by the cursor. The line is 
  5487.           executed under the control of ╨áEA, so that any error that occurs does 
  5488.           not suspend the execution of EDIT. 
  5489.  
  5490. F10       COPY - Copies a line. Move the cursor to the line you want to be 
  5491.           copied, and press F10. The F10 definition on the bottom line of the 
  5492.           screen is now highlighted. The system is now in "copy" state. Then 
  5493.           move the cursor to the line after which the indicated line is to be 
  5494.           copied (possibly on another page). Finally, press F10 again to cause 
  5495.           the copy to take place. The highlighting of the F10 definition is 
  5496.           then removed, and the system is no longer in "copy" state. 
  5497.  
  5498. All other function keys are ignored. 
  5499.  
  5500. Other Special Keys: 
  5501.  
  5502. Tab          Moves the cursor to the beginning of the next line. 
  5503.  
  5504. Shift-Tab    Moves the cursor to the beginning of the preceding line. 
  5505.  
  5506. PageDown     Displays the next page. 
  5507.  
  5508. PageUp       Displays the preceding page. 
  5509.  
  5510. End          Moves the cursor to the end of the current line (unless that line 
  5511.              is wider than the screen). 
  5512.  
  5513. Home         Moves the cursor to the start of the current line. 
  5514.  
  5515. Enter        Moves the cursor down one line at a time. If the cursor is in the 
  5516.              last displayed line when this key is pressed, the whole function 
  5517.              is scrolled up one line. 
  5518.  
  5519. Esc          Provides a limited "UNDO" facility. All changes made since the 
  5520.              last press of the Enter key or a function key are removed, and the 
  5521.              changed lines revert to their original state. Esc does not 
  5522.              interrupt execution of EDIT. 
  5523.  
  5524. Locked functions or operators cannot be edited with this function. 
  5525.  
  5526. If you use EDIT to edit an APL2 function that is already suspended in the 
  5527. active workspace, you create a new version of the function. The suspended 
  5528. version remains unaltered, but disappears once execution is complete, or the 
  5529. state indicator is cleared. 
  5530.  
  5531. You can also use this editor to copy a function to a new name, leaving the old 
  5532. version intact. Just invoke EDIT for the original function, change the name in 
  5533. the header line, and press FILE (F4). 
  5534.  
  5535.  
  5536. ΓòÉΓòÉΓòÉ 13.8.2. EDITOR_2 (APL2/370-Compatible Full-Screen Editor) ΓòÉΓòÉΓòÉ
  5537.  
  5538. EDITOR_2 is functionally equivalent to Editor 2 (available through )EDITOR 2) 
  5539. of APL2/370. Editor 2 is fully described in the APL2 Programming: Language 
  5540. Reference. 
  5541.  
  5542. To use this function, copy it into the active workspace, and then invoke it 
  5543. with a right argument of the name of the object to be edited: 
  5544.  
  5545. )PCOPY 1 EDIT EDITOR_2
  5546. EDITOR_2 'object_name'
  5547.  
  5548. This is equivalent to entering the APL2/370 commands: 
  5549.  
  5550.    )EDITOR 2
  5551.    Γòûobject_name
  5552.  
  5553.  
  5554. ΓòÉΓòÉΓòÉ 13.9. The EXAMPLES Workspace ΓòÉΓòÉΓòÉ
  5555.  
  5556. This section describes the EXAMPLES workspace. 
  5557.  
  5558. o Introduction 
  5559. o Mathematical Calculations 
  5560. o Miscellaneous Utility Functions 
  5561. o The Group GPAPL2 
  5562.  
  5563.  
  5564. ΓòÉΓòÉΓòÉ 13.9.1. Introduction ΓòÉΓòÉΓòÉ
  5565.  
  5566. The functions in this workspace are examples of ways to use APL2 in solving 
  5567. problems. The functions are brief, often no more than one or two statements, 
  5568. but they illustrate some of the ways in which APL2, with relatively few 
  5569. statements, can do calculations that require many more statements in other 
  5570. programming languages. These functions are not necessarily the best way, or the 
  5571. only way, to solve the problem. Rather, they illustrate ways to use APL2 that 
  5572. are not always obvious. We encourage you to examine the listings of all 
  5573. functions and operators in the workspace. Some of them are very simple. 
  5574.  
  5575. The examples fall into three categories: scientific, miscellaneous, and special 
  5576. examples of the new capabilities of APL2. There are also a few of interest to 
  5577. programmers, such as decimal-hexadecimal conversions and hexadecimal 
  5578. arithmetic. 
  5579.  
  5580.  
  5581. ΓòÉΓòÉΓòÉ 13.9.2. Mathematical Calculations ΓòÉΓòÉΓòÉ
  5582.  
  5583. Scientific and Mathematical functions are as follows: 
  5584.  
  5585. ASSOC                       Associativity of putative arithmetic tables 
  5586. BIN                         Binomial coefficients 
  5587. COMB FC LFC                 Combinations 
  5588. GCD                         Greatest common divisor 
  5589. HILB                        Hilbert matrix 
  5590. PALL PER PERM               Permutations 
  5591. PO POL POLY POLYB           Polynomials 
  5592. TRUTH                       Truth tables 
  5593. ZERO                        Roots of a function 
  5594.  
  5595. o ASSOC - Associativity 
  5596. o BIN - Binomial coefficients 
  5597. o COMB/FC/LFC - Combinations 
  5598. o GCD - Greatest common divisor 
  5599. o HILB - Hilbert matrix 
  5600. o PALL/PER/PERM - Permutations 
  5601. o PO/POL/POLY/POLYB - Polynomials 
  5602. o TRUTH - Truth tables 
  5603. o ZERO - Roots of a function 
  5604.  
  5605.  
  5606. ΓòÉΓòÉΓòÉ 13.9.2.1. ASSOC - Associativity ΓòÉΓòÉΓòÉ
  5607.  
  5608. ZΓò£ASSOC M  ╤ä ASSOCiativity
  5609.  
  5610. The function ASSOC tests any putative group multiplication table M (assuming 
  5611. group elements in ╤î╤å╤åM) for associativity and yields a value of 1 if it is 
  5612. associative, 0 otherwise. 
  5613.  
  5614.       MULTTABLEΓò£5 5╤å(6╤å1),(4╤å2),(╤î3),(2╤å3),(╤î4),4,╤î5
  5615.       MULTTABLE
  5616. 1 1 1 1 1
  5617. 1 2 2 2 2
  5618. 1 2 3 3 3
  5619. 1 2 3 4 4
  5620. 1 2 3 4 5
  5621.       ASSOC MULTTABLE
  5622. 1
  5623.       MULTTABLE[3;3]Γò£1
  5624.       MULTTABLE
  5625. 1 1 1 1 1
  5626. 1 2 2 2 2
  5627. 1 2 1 3 3
  5628. 1 2 3 4 4
  5629. 1 2 3 4 5
  5630.       ASSOC MULTTABLE
  5631. 0
  5632.  
  5633.  
  5634. ΓòÉΓòÉΓòÉ 13.9.2.2. BIN - Binomial coefficients ΓòÉΓòÉΓòÉ
  5635.  
  5636. ZΓò£BIN N   ╤ä BINomial
  5637.  
  5638. The function BIN produces all binomial coefficients up to order N. 
  5639.  
  5640.       BIN 7
  5641. 1 0  0  0  0  0 0 0
  5642. 1 1  0  0  0  0 0 0
  5643. 1 2  1  0  0  0 0 0
  5644. 1 3  3  1  0  0 0 0
  5645. 1 4  6  4  1  0 0 0
  5646. 1 5 10 10  5  1 0 0
  5647. 1 6 15 20 15  6 1 0
  5648. 1 7 21 35 35 21 7 1
  5649.  
  5650.  
  5651. ΓòÉΓòÉΓòÉ 13.9.2.3. COMB/FC/LFC - Combinations ΓòÉΓòÉΓòÉ
  5652.  
  5653. ZΓò£COMB N
  5654. ZΓò£FC N
  5655. ZΓò£LFC N
  5656.  
  5657. The function COMB uses recursive definition to produce a 2!N by 2 matrix of all 
  5658. possible pairs of elements from ╤îN. 
  5659.  
  5660.       COMB 5
  5661. 1 2
  5662. 1 3
  5663. 2 3
  5664. 1 4
  5665. 2 4
  5666. 3 4
  5667. 1 5
  5668. 2 5
  5669. 3 5
  5670. 4 5
  5671.  
  5672. The function FC shows an alternative method that yields the same pairs but in a 
  5673. different order. 
  5674.  
  5675.       FC 5
  5676. 1 2
  5677. 1 3
  5678. 1 4
  5679. 1 5
  5680. 2 3
  5681. 2 4
  5682. 2 5
  5683. 3 4
  5684. 3 5
  5685. 4 5
  5686.  
  5687. The function LFC uses FC to generate letter pairs. 
  5688.  
  5689.       LFC 5
  5690. AB
  5691. AC
  5692. AD
  5693. AE
  5694. BC
  5695. BD
  5696. BE
  5697. CD
  5698. CE
  5699. DE
  5700.  
  5701.  
  5702. ΓòÉΓòÉΓòÉ 13.9.2.4. GCD - Greatest common divisor ΓòÉΓòÉΓòÉ
  5703.  
  5704. ZΓò£L GCD R  ╤ä Greatest Common Divisor
  5705.  
  5706. The function GCD uses the Euclidean algorithm to produce the greatest common 
  5707. divisor. 
  5708.  
  5709.       30 GCD 40
  5710. 10
  5711.       GCD/ 30 40
  5712. 10
  5713.       GCD/ 30 40 45
  5714. 5
  5715.       GCD/ 30 40 39 45
  5716. 1
  5717.       GCD/ 30 42 39 45
  5718. 3
  5719.  
  5720.  
  5721. ΓòÉΓòÉΓòÉ 13.9.2.5. HILB - Hilbert matrix ΓòÉΓòÉΓòÉ
  5722.  
  5723. ZΓò£HILB N  ╤ä HILBert matrix
  5724.  
  5725. The function HILB produces a Hilbert matrix of order N. 
  5726.  
  5727.  
  5728. ΓòÉΓòÉΓòÉ 13.9.2.6. PALL/PER/PERM - Permutations ΓòÉΓòÉΓòÉ
  5729.  
  5730. ZΓò£PALL N
  5731. ZΓò£PER N
  5732. ZΓò£PERM N
  5733.  
  5734. The function PALL produces the matrix of all permutations of order N. Its 
  5735. subfunction PERM produces the B-th permutation of order N. 
  5736.  
  5737. The function PER uses recursive definition. It produces all permutations by a 
  5738. method much faster than that used in the function PALL. The permutations are 
  5739. not produced in the same order as those produced by PALL. 
  5740.  
  5741.       PALL 3
  5742. 1 2 3
  5743. 1 3 2
  5744. 2 1 3
  5745. 2 3 1
  5746. 3 1 2
  5747. 3 2 1
  5748.  
  5749.       PER 3
  5750. 1 3 2
  5751. 2 3 1
  5752. 1 2 3
  5753. 2 1 3
  5754. 3 2 1
  5755. 3 1 2
  5756.  
  5757.  
  5758. ΓòÉΓòÉΓòÉ 13.9.2.7. PO/POL/POLY/POLYB - Polynomials ΓòÉΓòÉΓòÉ
  5759.  
  5760. ZΓò£C POLY  X  ╤ä Scalar right argument only
  5761. ZΓò£C POL  X  ╤ä Scalar right argument only
  5762.        ╤ä (uses inner product)
  5763. ZΓò£C POLYB X  ╤ä Scalar right argument only
  5764.        ╤ä (uses base value)
  5765. ZΓò£C PO   X  ╤ä Scalar or vector right argument
  5766.  
  5767. The functions POLY, POL, PO, and POLYB each evaluate a polynomial or 
  5768. polynomials whose coefficients are determined by the left argument, and whose 
  5769. point or points of evaluation are determined by the right argument. The 
  5770. coefficients are in ascending order of associated powers. 
  5771.  
  5772.       ┬ñ1 0 1 PO ┬ñ2 ┬ñ1 0 1 2
  5773. 3 0 ┬ñ1 0 3
  5774.       ┬ñ1 0 1 POL 2
  5775. 3
  5776.       ┬ñ1 0 1 POLY 1
  5777. 0
  5778.       ┬ñ1 0 1 POLYB ┬ñ1
  5779. 0
  5780.  
  5781. To find the zeros of polynomials, see the POLYZ function from the MATHFNS 
  5782. workspace, described in Roots of Polynomials. 
  5783.  
  5784.  
  5785. ΓòÉΓòÉΓòÉ 13.9.2.8. TRUTH - Truth tables ΓòÉΓòÉΓòÉ
  5786.  
  5787. ZΓò£TRUTH N
  5788.  
  5789. The function TRUTH produces the matrix of arguments of the truth table of N 
  5790. logical variables. 
  5791.  
  5792.       TRUTH 3
  5793. 0 0 0
  5794. 0 0 1
  5795. 0 1 0
  5796. 0 1 1
  5797. 1 0 0
  5798. 1 0 1
  5799. 1 1 0
  5800. 1 1 1
  5801.  
  5802.  
  5803. ΓòÉΓòÉΓòÉ 13.9.2.9. ZERO - Roots of a function ΓòÉΓòÉΓòÉ
  5804.  
  5805. ZΓò£TOL (F ZERO) R
  5806.  
  5807. The operator ZERO uses the bisection method to determine, within a tolerance 
  5808. TOL, a root of the function F lying between the bounds R[1] and R[2]. F(R[1]) 
  5809. and F(R[2]) must have opposite signs. ZERO should be applied only to continuous 
  5810. functions. 
  5811.  
  5812.       ╨áFX 'ZΓò£SIN X' 'ZΓò£1╤èX'
  5813. SIN
  5814.       .1 SIN ZERO ┬ñ1 1
  5815. 0
  5816.       .1 SIN ZERO 1 4
  5817. 3.0625
  5818.       .001 SIN ZERO 1 4
  5819. 3.141601563
  5820.  
  5821.  
  5822. ΓòÉΓòÉΓòÉ 13.9.3. Miscellaneous Utility Functions ΓòÉΓòÉΓòÉ
  5823.  
  5824. o PACK/UNPACK - Illustration of Base and Representation 
  5825. o DEC2HEX/HEX2DEC/HEX - Hexadecimal arithmetic and conversions 
  5826. o SORTLIST - Sort with collating sequence 
  5827. o TIME - Provide CPU time used 
  5828.  
  5829.  
  5830. ΓòÉΓòÉΓòÉ 13.9.3.1. PACK/UNPACK - Illustration of Base and Representation ΓòÉΓòÉΓòÉ
  5831.  
  5832. ZΓò£PACK X
  5833. ZΓò£UNPACK X
  5834.  
  5835. The functions PACK and UNPACK illustrate the use of the ╨¿ and ╨¡ functions in 
  5836. transforming between a four-number encoding of SERIAL NUMBER (1 to 9999), 
  5837. MONTH, DAY, and YEAR, and a single number encoding of the same data. 
  5838.  
  5839.       PACK 117 1 1 84
  5840. 4315283
  5841.       UNPACK 4315283
  5842. 117 1 1 84
  5843.  
  5844.  
  5845. ΓòÉΓòÉΓòÉ 13.9.3.2. DEC2HEX/HEX2DEC/HEX - Hexadecimal arithmetic and conversions ΓòÉΓòÉΓòÉ
  5846.  
  5847. ZΓò£DEC2HEX R
  5848. ZΓò£HEX2DEC R
  5849. ZΓò£L(F HEX)R
  5850.  
  5851. The functions DEC2HEX and HEX2DEC work with nonnegative hexadecimal numbers 
  5852. represented as strings of characters selected from '0123456789ABCDEF'. The HEX 
  5853. operator performs an arithmetic function F on hexadecimal arguments, and 
  5854. returns a (character) hexadecimal result. The arguments presented to a function 
  5855. derived by the HEX operator must have a depth no greater than two. 
  5856.  
  5857. DEC2HEX      Converts decimal to hexadecimal 
  5858. HEX2DEC      Converts hexadecimal to decimal 
  5859. + HEX        Performs hexadecimal addition 
  5860. - HEX        Performs hexadecimal subtraction 
  5861. ...          and so on 
  5862.  
  5863.       'FF' +HEX '1'
  5864. 100
  5865.       (╤îHEX '5')┬░.╤ùHEX(╤îHEX 'C')
  5866. 1 2 3 4  5  6  7  8  9  A  B  C
  5867. 2 4 6 8  A  C  E  10 12 14 16 18
  5868. 3 6 9 C  F  12 15 18 1B 1E 21 24
  5869. 4 8 C 10 14 18 1C 20 24 28 2C 30
  5870. 5 A F 14 19 1E 23 28 2D 32 37 3C
  5871.  
  5872.  
  5873. ΓòÉΓòÉΓòÉ 13.9.3.3. SORTLIST - Sort with collating sequence ΓòÉΓòÉΓòÉ
  5874.  
  5875. ZΓò£SORTLIST R
  5876. R is a character matrix. Z is R with its rows sorted according to the collating 
  5877. sequence defined in DCS, a global variable. 
  5878.  
  5879.  
  5880. ΓòÉΓòÉΓòÉ 13.9.3.4. TIME - Provide CPU time used ΓòÉΓòÉΓòÉ
  5881.  
  5882. ZΓò£TIME
  5883.  
  5884. The function TIME yields the amount (in minutes, seconds, and milliseconds) of 
  5885. CPU time used since its previous execution. It is useful in measuring the 
  5886. execution times of other functions. The global variable TIMER is assigned the 
  5887. value of the cumulative CPU time at each execution of the function TIME. 
  5888.  
  5889.  
  5890. ΓòÉΓòÉΓòÉ 13.9.4. The Group GPAPL2 ΓòÉΓòÉΓòÉ
  5891.  
  5892. The group GPAPL2 consists of various functions and operators designed to show 
  5893. some of the capabilities of APL2. 
  5894.  
  5895. o Workspace Information Functions 
  5896. o Miscellaneous Functions 
  5897. o Operators to Conform Arguments 
  5898. o Operators for Debugging 
  5899. o Operators to Handle Depth 
  5900. o Operators for Program Control 
  5901. o Miscellaneous Operators 
  5902.  
  5903.  
  5904. ΓòÉΓòÉΓòÉ 13.9.4.1. Workspace Information Functions ΓòÉΓòÉΓòÉ
  5905.  
  5906. EXAMPLE R
  5907.  
  5908. This function executes the examples found in the leading comments of the 
  5909. program named in R. 
  5910.  
  5911. EXAMPLES
  5912.  
  5913. This function executes the examples found in the leading comments of all the 
  5914. programs in the workspace. 
  5915.  
  5916.  
  5917. ΓòÉΓòÉΓòÉ 13.9.4.2. Miscellaneous Functions ΓòÉΓòÉΓòÉ
  5918.  
  5919. ZΓò£L IOTAU R  ╤ä IOTA Underbar
  5920.  
  5921. This is the Find Index function from the APL2 Installed User Program. R and L 
  5922. may be any arrays. Z is an integer matrix containing the starting positions (in 
  5923. row major order) where pattern R begins in the array L. 
  5924.  
  5925.       ╤å'A' IOTAU 'A'
  5926. 0 1
  5927.       'ABABABA' IOTAU 'AB'
  5928. 1
  5929. 3
  5930. 5
  5931.       1 (2 3) (4 5) 2 3 4 5 IOTAU 2 3
  5932. 4
  5933.       LΓò£4 5╤å'ABCABA'
  5934.       L
  5935. ABCAB
  5936. AABCA
  5937. BAABC
  5938. ABAAB
  5939.       L IOTAU 'BA'
  5940. 3 1
  5941. 4 2
  5942.       L IOTAU 2 1╤å'BA'
  5943. 1 2
  5944. 1 5
  5945. 2 3
  5946. 3 1
  5947. 3 4
  5948.  
  5949. ZΓò£L REPLICATE R
  5950. ZΓò£L EXPAND R
  5951.  
  5952. These functions are identical to their primitive counterparts, Replicate and 
  5953. Expand, respectively represented by "/" and "\", except that the primitive 
  5954. versions are operators, so you cannot apply operators to them. The defined 
  5955. REPLICATE and EXPAND really are functions, so you can apply operators to them. 
  5956.  
  5957.       (1 0 1)(0 3) REPLICATEΓûá 'ABC' 'DE'
  5958.  AC EEE
  5959.       REPLICATE/ 5 '*'
  5960.  *****
  5961.       (1 0 1)(0 1 0) EXPANDΓûá (2 4) 6
  5962.  2 0 4  0 6 0
  5963.  
  5964. ZΓò£L ENLISTA R
  5965.  
  5966. Return (in Z) the array L with each item of the enlist of L (╤ÄL) replaced by 
  5967. the corresponding item from R. By using this, you can replace the selective 
  5968. specification (╤ÄL)Γò£R with LΓò£L ENLISTA R. 
  5969.  
  5970. ZΓò£EXPUNGE NL
  5971.  
  5972. Expunge the objects listed in NL. NL may be a character matrix with one name 
  5973. per row, or a character vector with names separated by blanks. If a name is 
  5974. enclosed in parentheses, it is assumed to be the name of a character array 
  5975. (rank not greater than 2) containing a list of objects to be expunged. Unlike 
  5976. the )ERASE system command, this expunges the local copy of an object that is 
  5977. localized in a pendent or suspended function or operator. 
  5978.  
  5979. ZΓò£REP R   ╤ä REPresentation
  5980.  
  5981. Z is a "representation" of the array, function, or operator named in R. 
  5982. Specifically, Z is ╨┐R or ╨áCR, whichever is appropriate. This is an example of 
  5983. the ELSE operator in this group. 
  5984.  
  5985. ZΓò£TYPE R
  5986.  
  5987. Z is a scalar zero if R is numeric, and a scalar blank if it is character. This 
  5988. function is compatible with a VS APL library function of the same name. It is 
  5989. not meant to be applied to mixed or nested arguments. 
  5990.  
  5991. ZΓò£UNIQUE R
  5992.  
  5993. R is a vector. Z is a vector containing the elements of R with duplicates 
  5994. eliminated. 
  5995.  
  5996.       UNIQUE 'THE ANTS WERE HERE'
  5997. THE ANSWR
  5998.       UNIQUE 'GUFFAW' 17 (╤î4) 'GUFFAW'
  5999.  GUFFAW 17  1 2 3 4
  6000.  
  6001.  
  6002. ΓòÉΓòÉΓòÉ 13.9.4.3. Operators to Conform Arguments ΓòÉΓòÉΓòÉ
  6003.  
  6004. ZΓò£L (F CR) R   ╤ä Conform Ranks
  6005. ZΓò£L (F PAD) R
  6006. ZΓò£L (F TRUNC) R  ╤ä TRUNCate
  6007.  
  6008. The CR operator "conforms the ranks" of L and R and then applies the function 
  6009. F. The PAD operator conforms the axes of L and R by overtake. The TRUNC 
  6010. operator conforms the axes of L and R by undertake. 
  6011.  
  6012.       (4 4╤å'WE  THEYUS  OURS') ^.(=PAD) ╤ì 2 3╤å'WE OUR'
  6013. 1 0
  6014. 0 0
  6015. 0 0
  6016. 0 0
  6017.       (4 4╤å'WE  THEYUS  OURS') ^.(=TRUNC) ╤ì 2 3╤å'WE OUR'
  6018. 1 0
  6019. 0 0
  6020. 0 0
  6021. 0 1
  6022.       (2 3 4╤å╤î24) +PAD CR 5 6╤å100╤ù╤î30
  6023.  101  202  303  404  500  600
  6024.  705  806  907 1008 1100 1200
  6025. 1309 1410 1511 1612 1700 1800
  6026. 1900 2000 2100 2200 2300 2400
  6027. 2500 2600 2700 2800 2900 3000
  6028.   13   14   15   16    0    0
  6029.   17   18   19   20    0    0
  6030.   21   22   23   24    0    0
  6031.    0    0    0    0    0    0
  6032.    0    0    0    0    0    0
  6033.  
  6034.  
  6035. ΓòÉΓòÉΓòÉ 13.9.4.4. Operators for Debugging ΓòÉΓòÉΓòÉ
  6036.  
  6037. ZΓò£L (F TRACE) R       ZΓò£(F TRACE) R
  6038. TRACE traces the execution of F. It is most useful when the derived function is 
  6039. passed to another operator. Every time F is called, the derived function 
  6040. displays its argument(s) and the result. 
  6041.  
  6042.       +TRACE\ 1 4 9      ╤ä Expression as entered
  6043. 1 4                      ╤ä TRACE output
  6044. 5                        ╤ä    :
  6045. 4 9                      ╤ä    :
  6046. 13                       ╤ä    :
  6047. 1 13                     ╤ä    :
  6048. 14                       ╤ä TRACE output
  6049. 1 5 14                   ╤ä Final result
  6050.       2 +TRACE\ 1 2 3 4  ╤ä Expression as entered
  6051. 1 2                      ╤ä TRACE output
  6052. 3                        ╤ä    :
  6053. 2 3                      ╤ä    :
  6054. 5                        ╤ä    :
  6055. 3 4                      ╤ä    :
  6056. 7                        ╤ä TRACE output
  6057. 3 5 7                    ╤ä Final result
  6058.  
  6059. ZΓò£L (F TRAP) R       ZΓò£(F TRAP) R
  6060.  
  6061. The derived function (F TRAP) is just like F, except that if an error occurs 
  6062. during the execution of F, the enclosed error message becomes the result. 
  6063.  
  6064.       2 ╨ÄTRAP 0
  6065.  DOMAIN ERROR
  6066.        L F R
  6067.        ^
  6068.       ╤å╤â2 ╨ÄTRAP 0
  6069. 3 12
  6070.  
  6071.  
  6072. ΓòÉΓòÉΓòÉ 13.9.4.5. Operators to Handle Depth ΓòÉΓòÉΓòÉ
  6073.  
  6074. ZΓò£L (F EL) R           ╤ä Each Left
  6075. ZΓò£L (F ER) R     ZΓò£(F ER) R  ╤ä Each Right
  6076.  
  6077. These operators are like the Each operator (Γûá), except that EL applies Each 
  6078. only on the left argument, and ER applies Each only on the right argument. 
  6079.  
  6080.       (2 2 3)(4 3)(2 6) ╤åEL ╤î12
  6081.   1  2  3     1  2  3   1 2 3  4  5  6
  6082.   4  5  6     4  5  6   7 8 9 10 11 12
  6083.               7  8  9
  6084.   7  8  9    10 11 12
  6085.  10 11 12
  6086.       2 3 ╤åER 4 5 6
  6087.  4 4 4   5 5 5   6 6 6
  6088.  4 4 4   5 5 5   6 6 6
  6089.  
  6090. ZΓò£L (F PL) R           ╤ä Pervasive Left
  6091. ZΓò£L (F PR) R     ZΓò£(F PR) R  ╤ä Pervasive Right
  6092.  
  6093. PL causes F to be treated as pervasive down to depth 1 (simple arrays) on its 
  6094. left argument, and PR causes F to be treated as pervasive down to depth 1 on 
  6095. its right argument. 
  6096.  
  6097.       1 (2 3)╤åPL ╤î6
  6098.  1   1 2 3
  6099.      4 5 6
  6100.       3 ╤åPR 1,╤é2,╤é3 4
  6101.  1 1 1   2 2 2   3 4 3
  6102.       (╤åPR 'A' 'BC' ('DEF' 'HIJK')) ╤å PL '╨á'
  6103.  ╨á ╨á╨á   ╨á╨á╨á ╨á╨á╨á╨á
  6104.  
  6105.  
  6106. ΓòÉΓòÉΓòÉ 13.9.4.6. Operators for Program Control ΓòÉΓòÉΓòÉ
  6107.  
  6108. ZΓò£C (F ELSE G) R
  6109.  
  6110. If C is 1, then Z is F R. If C is 0, then Z is G R. 
  6111.  
  6112. ZΓò£(F IF C) R
  6113.  
  6114. If C is 1, then Z is F R. Otherwise, Z is R. 
  6115.  
  6116.  
  6117. ΓòÉΓòÉΓòÉ 13.9.4.7. Miscellaneous Operators ΓòÉΓòÉΓòÉ
  6118.  
  6119. ZΓò£L (F AND G) R       ZΓò£(F AND G) R
  6120.  
  6121. The AND operator applies two functions to the same argument(s). 
  6122.  
  6123.       3 +AND╤ù 5
  6124. 8 15
  6125.       +AND- 5
  6126. 5 ┬ñ5
  6127.       (╤î4) (┬░.╤ù)AND(┬░.+) (╤î4)
  6128.  1 2  3  4   2 3 4 5
  6129.  2 4  6  8   3 4 5 6
  6130.  3 6  9 12   4 5 6 7
  6131.  4 8 12 16   5 6 7 8
  6132.  
  6133. ZΓò£L (F COMMUTE) R
  6134.  
  6135. The COMMUTE operator switches the arguments of the function to which it is 
  6136. applied. 
  6137.  
  6138.       0.5 *COMMUTE 9
  6139. 3
  6140.  
  6141. ZΓò£L (F FAROUT) R   ╤ä FAr Reaching OUTer product
  6142.  
  6143. This operator applies outer product to all levels of the arrays L and R. 
  6144.  
  6145.       (10 20)(30 40 50) +FAROUT (1 2)(3 4 5)
  6146.  11 12   13 14 15
  6147.  21 22   23 24 25
  6148.  31 32   33 34 35
  6149.  41 42   43 44 45
  6150.  51 52   53 54 55
  6151.  
  6152. ZΓò£L (F NOP) R     ZΓò£(F NOP) R  ╤ä No OPeration
  6153.  
  6154. The derived function (F NOP) is just F. This operation is useful for separating 
  6155. the array right operand of an operator from the right argument of the derived 
  6156. function. It sometimes eliminates one layer of parentheses. 
  6157.  
  6158.       ╤ä Compare with the next example.
  6159.       ╤å POWER 2 NOP 2 3 4╤å╤î24
  6160. 3
  6161.  
  6162. ZΓò£(F POWER N) R
  6163.  
  6164. POWER applies F monadically N times. 
  6165.  
  6166.       ╤ä Parentheses are redundant here.
  6167.       (╤å POWER 2) 2 3 4╤å╤î24
  6168. 3
  6169.  
  6170.  
  6171. ΓòÉΓòÉΓòÉ 13.10. The FILE Workspace ΓòÉΓòÉΓòÉ
  6172.  
  6173. The FILE workspace has been designed to help you work with OS/2 files. 
  6174.  
  6175. o The Function Groups 
  6176. o AP 210 Group 
  6177. o AP 211 Group 
  6178. o Delta Group 
  6179. o Transfer Group 
  6180.  
  6181.  
  6182. ΓòÉΓòÉΓòÉ 13.10.1. The Function Groups ΓòÉΓòÉΓòÉ
  6183.  
  6184. The FILE workspace contains the following groups of functions: 
  6185.  
  6186. o AP 210 group 
  6187. o AP 211 group 
  6188. o Delta group 
  6189. o Transfer group 
  6190.  
  6191. A list of the main functions in each group is presented in a captioned figure 
  6192. at the beginning of each section. 
  6193.  
  6194.  
  6195. ΓòÉΓòÉΓòÉ 13.10.2. AP 210 Group ΓòÉΓòÉΓòÉ
  6196.  
  6197. The functions in this group aid in manipulating OS/2 files. This group allows 
  6198. either sequential or random access. It uses the file auxiliary processor, AP 
  6199. 210. This workspace enables you to create a file, write into it, and read from 
  6200. it. To do so, you WOPEN an old or new file, and WRITE data into it. You then 
  6201. CLOSE the file to save it on disk. If you only want to read data from an old 
  6202. file, without writing any more data into it, on the next access simply OPEN the 
  6203. file and READ in records, either randomly or sequentially. 
  6204.  
  6205. To use the functions described here, you must copy the FILE workspace into your 
  6206. active workspace by entering: 
  6207.  
  6208.       )PCOPY 2 FILE
  6209.  
  6210. If this command executes successfully, the following set of functions is loaded 
  6211. into your active workspace. 
  6212.  
  6213. o Terminology 
  6214. o OPEN - Open a file for read/only 
  6215. o WOPEN - Open a file for read/write 
  6216. o CLOSE - Close a file 
  6217. o EBCDIC - Set up an EBCDIC translation table 
  6218. o SIZE - Return file size in bytes 
  6219. o READ - Read a record 
  6220. o READD - Read designated bytes 
  6221. o READV - Read a variable-length record 
  6222. o READVS - Read a record, stripping EOL 
  6223. o WRITE - Write a record 
  6224. o WRITED - Write designated bytes 
  6225. o WRITEV - Write a variable-length record 
  6226. o APPENDFILEV - Append to a variable-length record file 
  6227. o COMPARE - Compare two files 
  6228. o DELETE - Delete a file 
  6229. o RENAME - Rename a file 
  6230. o READFILEV - Read a file of variable-length records 
  6231. o TYPE - Display the contents of a file 
  6232. o WRITEFILEV - Write a file of variable-length records 
  6233. o Auxiliary functions 
  6234. o Example of Use 
  6235.  
  6236.  
  6237. ΓòÉΓòÉΓòÉ 13.10.2.1. Terminology ΓòÉΓòÉΓòÉ
  6238.  
  6239. The following terms are used in the descriptions of the syntax for the 
  6240. functions: 
  6241.  
  6242. Brackets indicate that a parameter is optional. 
  6243.  
  6244. "code" can be any of the following characters: 
  6245.  
  6246. A    (APL)  The records in the file are APL2 objects and their headers in APL2 
  6247.      internal form. Arrays of arbitrary rank and depth can be stored and 
  6248.      recovered. Different records of a file can contain objects of different 
  6249.      types (for example, characters, integers, or real numbers). An APL2 object 
  6250.      in a record can occupy up to the actual record length (not necessarily the 
  6251.      same number of bytes), but the header fills a part of that area. 
  6252.  
  6253. B    (Bool)  The records in the file contain strings of bits with no header 
  6254.      (packed eight bits per byte). The equivalent APL2 object is a Boolean 
  6255.      vector. In this case, all records must be equal to the selected record 
  6256.      length. 
  6257.  
  6258. C    (Char)  The contents of the record is a string of characters in ASCII, 
  6259.      with no header. All records must be equal to the selected record length, 
  6260.      with each character occupying one byte. Variable-length records are not 
  6261.      supported. 
  6262.  
  6263. D    (ASCII)  The contents of the record is a string of characters in ASCII 
  6264.      code, with no header. Each character occupies one byte. Variable-length 
  6265.      records are supported. 
  6266.  
  6267. T    (Translate)  The contents of the record is a string of characters, with no 
  6268.      header, translated according to the AP 210 translate table defined as 
  6269.      described in Establishing the AP 210 Translate Table. All records must be 
  6270.      equal to the selected record length except when variable-length operations 
  6271.      are being performed. 
  6272.  
  6273. "file_no" is a positive integer that you define for future reference to a file 
  6274. when you open it. 
  6275.  
  6276. "filespec" must be in the following OS/2 syntax: 
  6277.  
  6278.       [C:\path\]filename
  6279.  
  6280. Errors encountered during the execution of these functions can cause a message 
  6281. containing an AP 210 return code to be displayed. The meanings of these return 
  6282. codes are listed in AP 210 Return Codes. 
  6283.  
  6284.  
  6285. ΓòÉΓòÉΓòÉ 13.10.2.2. OPEN - Open a file for read/only ΓòÉΓòÉΓòÉ
  6286.  
  6287. [file_no] OPEN 'filespec[,code]'
  6288.  
  6289. This function opens the specified OS/2 file for read-only sequential or random 
  6290. access. 
  6291.  
  6292. If no file by that name exists in the indicated drive or directory, an error 
  6293. results; see AP 210 Return Codes for a list of all possible return codes. If 
  6294. "file_no" is omitted, 1 is assumed. If "code" is omitted, A (APL) is assumed. 
  6295.  
  6296. OPEN creates three global variables, with the following names: 
  6297.  
  6298. 'CZ',╨╛file_no -         Control shared variable 
  6299. 'DZ',╨╛file_no -         Data shared variable 
  6300. 'EZ',╨╛file_no -         File size in bytes 
  6301.  
  6302. OPENing a file_no without having closed the corresponding file causes the 
  6303. current file to be closed, and then re-opened according to the new request. 
  6304.  
  6305.  
  6306. ΓòÉΓòÉΓòÉ 13.10.2.3. WOPEN - Open a file for read/write ΓòÉΓòÉΓòÉ
  6307.  
  6308. [file_no] WOPEN 'filespec[,code]'
  6309.  
  6310. This function opens the specified OS/2 file for reading or writing, with 
  6311. sequential or random access. 
  6312.  
  6313. If no file of this name exists, a new file is created. If "file_no" is omitted, 
  6314. 1 is assumed. If "code" is omitted, A (APL) is assumed. 
  6315.  
  6316. WOPEN creates three global variables, with the following names: 
  6317.  
  6318. 'CZ',╨╛file_no -         Control shared variable 
  6319. 'DZ',╨╛file_no -         Data shared variable 
  6320. 'EZ',╨╛file_no -         File size in bytes 
  6321.  
  6322. WOPENing a file_no without having closed the corresponding file causes the 
  6323. current file to be closed, and then re-opened according to the new request. 
  6324.  
  6325.  
  6326. ΓòÉΓòÉΓòÉ 13.10.2.4. CLOSE - Close a file ΓòÉΓòÉΓòÉ
  6327.  
  6328. CLOSE file_no
  6329.  
  6330. This function closes a file that has been opened with (W)OPEN. The previously 
  6331. assigned file_no is now available for reuse. (If you (W)OPEN a file_no without 
  6332. having closed the corresponding file, the current file is closed and then 
  6333. re-opened according to the new request.) 
  6334.  
  6335.  
  6336. ΓòÉΓòÉΓòÉ 13.10.2.5. EBCDIC - Set up an EBCDIC translation table ΓòÉΓòÉΓòÉ
  6337.  
  6338. EBCDIC file_no
  6339.  
  6340. The EBCDIC function defines an APL2-EBCDIC translation table to AP 210. This 
  6341. can be used after opening an AP 210 file with code T. 
  6342.  
  6343. The file_no matches the number you defined in (W)OPENing the file. 
  6344.  
  6345.  
  6346. ΓòÉΓòÉΓòÉ 13.10.2.6. SIZE - Return file size in bytes ΓòÉΓòÉΓòÉ
  6347.  
  6348. ZΓò£SIZE file_no
  6349.  
  6350. This function returns the size of a file when it was last opened. 
  6351.  
  6352. SIZE can only be used after the file has been OPENed or WOPENed successfully. 
  6353.  
  6354.  
  6355. ΓòÉΓòÉΓòÉ 13.10.2.7. READ - Read a record ΓòÉΓòÉΓòÉ
  6356.  
  6357. ZΓò£READ file_no [record_no [record_size]]
  6358.  
  6359. This function reads an OS/2 data file, sequentially or randomly, that was 
  6360. opened by using (W)OPEN. 
  6361.  
  6362. "file_no" matches the number that you specified in (W)OPENing the file. 
  6363.  
  6364. If no "record_no" is specified, the default is sequential access to the file. 
  6365. Under sequential access, the first record (record 0) is accessed by either a 
  6366. READ or WRITE command immediately after the (W)OPEN; the second record (record 
  6367. 1) is accessed on the next command, and so on. The READ, READD, READV, WRITE, 
  6368. WRITED, and WRITEV functions work from the same access point, meaning that the 
  6369. access point is advanced sequentially to the next record each time any of these 
  6370. commands is issued. 
  6371.  
  6372. Random access is designated by specifying a particular record. "record_size" 
  6373. can only be specified when using random access. If the record_size is not 
  6374. specified, the default is the record_size specified in the previous operation. 
  6375. If the record_size is not specified on the first READ or WRITE, the default is 
  6376. 128 bytes. 
  6377.  
  6378.  
  6379. ΓòÉΓòÉΓòÉ 13.10.2.8. READD - Read designated bytes ΓòÉΓòÉΓòÉ
  6380.  
  6381. ZΓò£READD file_no [byte_no [record_size]]
  6382.  
  6383. This function reads an OS/2 data file, sequentially or randomly, that was 
  6384. opened using (W)OPEN. 
  6385.  
  6386. "file_no" matches the number that you specified in (W)OPENing the file. 
  6387.  
  6388. "file_no", "byte_no" and "record_size" must all be integer. 
  6389.  
  6390. If byte_no is not specified, the default is sequential access to the file. 
  6391. Random access is designated by specifying a particular "byte_no" position in 
  6392. the file (0╤öbyte_no). "record_size" can be specified only when you are using 
  6393. random-access. 
  6394.  
  6395.  
  6396. ΓòÉΓòÉΓòÉ 13.10.2.9. READV - Read a variable-length record ΓòÉΓòÉΓòÉ
  6397.  
  6398. ZΓò£READV file_no [record_no [scan_length]]
  6399.  
  6400. This function sequentially reads a variable-length record APL2 or ASCII 
  6401. character file that was previously opened by using (W)OPEN. 
  6402.  
  6403. The file_no matches the number that you defined in (W)OPENing the file. 
  6404.  
  6405. If no "record_no" is specified, the default is sequential access to the file. 
  6406.  
  6407. If no "scan_length" is specified, the default is the scan_length specified in 
  6408. the previous operation. If the scan_length is not specified on the first READV, 
  6409. the default is 128 bytes. This parameter defines the maximum distance for which 
  6410. AP 210 scans the file for a line-feed character, and should be set to the 
  6411. maximum record length that you expect to read. 
  6412.  
  6413. This function can be used only if the file was opened with codes A, D, or T. 
  6414.  
  6415. If the file was opened with codes D or T, the record returned by READV includes 
  6416. the delimiting line-feed character, which can be removed with a ┬ñ1Γòƒ operation. 
  6417.  
  6418.  
  6419. ΓòÉΓòÉΓòÉ 13.10.2.10. READVS - Read a record, stripping EOL ΓòÉΓòÉΓòÉ
  6420.  
  6421. ZΓò£READVS file_no [record_no [scan_length]]
  6422.  
  6423. This function is the same as READV, except that trailing CR/LF or LF indicators 
  6424. are stripped from the record. 
  6425.  
  6426.  
  6427. ΓòÉΓòÉΓòÉ 13.10.2.11. WRITE - Write a record ΓòÉΓòÉΓòÉ
  6428.  
  6429. [file_no [rec_no [rec_size]]] WRITE DATA
  6430.  
  6431. This function writes to an OS/2 data file, either sequentially or randomly, 
  6432. that has been opened by using WOPEN. (Trying to WRITE to a file opened by OPEN 
  6433. results in an error; see AP 210 Return Codes for a list of all possible return 
  6434. codes.) When the WRITE function is issued, it writes over any existing data in 
  6435. the currently accessed record. 
  6436.  
  6437. "file_no" matches the number arbitrarily defined when the file was WOPENed. If 
  6438. no number is given, 1 is assumed. 
  6439.  
  6440. If the rec_no is not specified on the first READ or WRITE, the default is 
  6441. sequential access to the file. Under sequential access, the first record 
  6442. (record 0) is accessed by either a READ or a WRITE command immediately after 
  6443. the (W)OPEN; the second record (record 1) is accessed on the next command, and 
  6444. so on. The READ, READD, READV, WRITE, WRITED, and WRITEV functions work from 
  6445. the same access point; that is, the access point is advanced sequentially to 
  6446. the next record each time any of these commands are issued. 
  6447.  
  6448. Random access is designated by specifying a particular record. If the record 
  6449. size, rec_size, is not specified, the default is the rec_size specified on the 
  6450. previous READ or WRITE 
  6451.  
  6452. If the rec_size has not been specified, the default is 128 bytes. 
  6453.  
  6454.  
  6455. ΓòÉΓòÉΓòÉ 13.10.2.12. WRITED - Write designated bytes ΓòÉΓòÉΓòÉ
  6456.  
  6457. [file_no [byte_no [rec_size]]] WRITED DATA
  6458.  
  6459. This function writes to an OS/2 data file, either sequentially or randomly, 
  6460. that has been opened by using WOPEN. (Trying to WRITED to a file opened by OPEN 
  6461. results in an error; see AP 210 Return Codes for a list of all possible 
  6462. errors.) When the WRITED function is issued, it writes over any existing data 
  6463. in the currently accessed record. 
  6464.  
  6465. "file_no" matches the number that you arbitrarily defined in WOPENing the file. 
  6466. If not given, 1 is assumed. 
  6467.  
  6468. "file_no", "byte_no" and "rec_size" must all be integer. 
  6469.  
  6470. If "byte_no" is not specified, the default is sequential access to the file. 
  6471. Random access is designated by specifying a particular "byte_no" (0╤öbyte_no). 
  6472.  
  6473. If the record size, rec_size, has not been specified, the default is 128 bytes. 
  6474.  
  6475.  
  6476. ΓòÉΓòÉΓòÉ 13.10.2.13. WRITEV - Write a variable-length record ΓòÉΓòÉΓòÉ
  6477.  
  6478. [file_no [rec_no]] WRITEV DATA
  6479.  
  6480. This function sequentially writes a variable-length record APL2 or ASCII 
  6481. character file that has been opened by using WOPEN. 
  6482.  
  6483. The file_no matches the number that you defined in WOPENing the file. If none 
  6484. was given, 1 is assumed. 
  6485.  
  6486. This function can be used only if the file was opened with code A, D, or T. 
  6487.  
  6488. If rec_no is not given, sequential operation is performed. (This gives the 
  6489. fastest operation, because the file is scanned from the beginning, in search of 
  6490. the requested record, whenever rec_no is specified.) If rec_no is greater than 
  6491. the number of records currently in the file, the record is appended to the end 
  6492. of the file. 
  6493.  
  6494. If the file was opened with code D or code T, a line-feed character is appended 
  6495. to the end of each record as expected by OS/2 for sequential files. If the 
  6496. record already has a line-feed character (╨áTC[╨áIO+2]) appended, no additional 
  6497. line-feed is added. 
  6498.  
  6499.  
  6500. ΓòÉΓòÉΓòÉ 13.10.2.14. APPENDFILEV - Append to a variable-length record file ΓòÉΓòÉΓòÉ
  6501.  
  6502. 'filespec' APPENDFILEV vector_of_charvectors
  6503.  
  6504. This function accepts a vector of character vectors as its right argument and a 
  6505. file name as its left argument; it then appends each vector in 
  6506. "vector_of_charvectors" as code D (ASCII) variable-length records to the file 
  6507. "filespec". To write a single character vector as one record, enclose (╤é) the 
  6508. right argument. 
  6509.  
  6510.  
  6511. ΓòÉΓòÉΓòÉ 13.10.2.15. COMPARE - Compare two files ΓòÉΓòÉΓòÉ
  6512.  
  6513. [record_size] COMPARE filespec_matrix
  6514.  
  6515. This function compares two files. The right argument is a two-row character 
  6516. matrix, each row containing the filespec of one of the files to be compared, 
  6517. followed by a comma, followed by the code with which the file is to be read. 
  6518. The optional left argument, record_size, specifies the record length with which 
  6519. the files are to be read. If this left argument is not specified, the files are 
  6520. assumed to contain variable-length records. 
  6521.  
  6522. If the files are identical, the COMPARE function gives no output. Otherwise, it 
  6523. lists the pairs of corresponding records that differ. It also indicates which 
  6524. of the files is shorter, if applicable. For example: 
  6525.  
  6526.       80 COMPARE ╤â'FILE1,D' 'FILE2,D'
  6527.  
  6528. This example compares files, FILE1 and FILE2, both of which are read as 80-byte 
  6529. fixed-length record ASCII files. 
  6530.  
  6531.  
  6532. ΓòÉΓòÉΓòÉ 13.10.2.16. DELETE - Delete a file ΓòÉΓòÉΓòÉ
  6533.  
  6534. DELETE 'filespec'
  6535.  
  6536. This function deletes an OS/2 file. (Files can also be erased in OS/2 by using 
  6537. the "del" command.) 
  6538.  
  6539.  
  6540. ΓòÉΓòÉΓòÉ 13.10.2.17. RENAME - Rename a file ΓòÉΓòÉΓòÉ
  6541.  
  6542. 'new_filespec' RENAME 'old_filespec'
  6543.  
  6544. This function changes the name of the file specified in the right argument to 
  6545. the name and extension specified in the left argument. The left argument 
  6546. directory (or APL2 library number) must be specified. If a different 
  6547. subdirectory is specified, a move is performed instead of a rename. 
  6548.  
  6549.  
  6550. ΓòÉΓòÉΓòÉ 13.10.2.18. READFILEV - Read a file of variable-length records ΓòÉΓòÉΓòÉ
  6551.  
  6552. ZΓò£READFILEV 'filespec'
  6553.  
  6554. This function reads a code A (APL), code D (ASCII), or code T (Translate) 
  6555. variable-length record file and returns each record as an element of a vector 
  6556. of arrays. 
  6557.  
  6558. If no code is specified with filespec, the file is assumed to be an ASCII (code 
  6559. D) file with line-feed characters delimiting records. 
  6560.  
  6561. Also, the ΓòóFV function, described in Delta Group, provides a similar facility 
  6562. and is independent of other functions in this workspace. 
  6563.  
  6564.  
  6565. ΓòÉΓòÉΓòÉ 13.10.2.19. TYPE - Display the contents of a file ΓòÉΓòÉΓòÉ
  6566.  
  6567. [record_size [n]] TYPE 'filespec[,code]'
  6568.  
  6569. This function displays the contents of an OS/2 file. 
  6570.  
  6571. The file with the specified filespec is displayed at the terminal. 
  6572.  
  6573. "record_size", if given, specifies the record length of a fixed-record-length 
  6574. file, whose first n characters are to be typed. If n is not given, the full 
  6575. record_size is typed. If record_size is not given, the file is assumed to 
  6576. contain variable-length records. In this case code must be either A (APL2) or D 
  6577. (ASCII); if it is not specified, code D is used. 
  6578.  
  6579.  
  6580. ΓòÉΓòÉΓòÉ 13.10.2.20. WRITEFILEV - Write a file of variable-length records ΓòÉΓòÉΓòÉ
  6581.  
  6582. 'filespec' WRITEFILEV vector_of_arrays
  6583.  
  6584. This function accepts a vector of arrays as its right argument and a file name 
  6585. as its left argument; it then writes each vector in "vector_of_arrays" as code 
  6586. A (APL2), code D (ASCII), or code T (Translate) variable-length records in the 
  6587. file "filespec". 
  6588.  
  6589. If no code is specified with filespec, the file is written as an ASCII (code D) 
  6590. file with line-feed characters delimiting records. For code D or code T, 
  6591. vector_of_arrays must be a vector of character vectors. To write a single array 
  6592. as one record, enclose (╤é) the right argument. 
  6593.  
  6594. Also see the ΓòóFV function, described in Delta Group, which provides a similar 
  6595. facility and is independent of other functions in this workspace. 
  6596.  
  6597.  
  6598. ΓòÉΓòÉΓòÉ 13.10.2.21. Auxiliary functions ΓòÉΓòÉΓòÉ
  6599.  
  6600. A ΓòóCHK N
  6601.  
  6602. Translates return codes. A is optional and, if included, contains a specific 
  6603. list of return codes to check. N identifies the file number. 
  6604.  
  6605. ΓòóSH N
  6606.  
  6607. Shares a pair of variables with AP 210. Uses N as a variable suffix. 
  6608.  
  6609.  
  6610. ΓòÉΓòÉΓòÉ 13.10.2.22. Example of Use ΓòÉΓòÉΓòÉ
  6611.  
  6612. The following is an example of how to use some of the OS/2 file-handling 
  6613. functions contained in the FILE workspace: 
  6614.  
  6615.       )LOAD 2 FILE
  6616.  
  6617. First create a new file. The records contain strings of ASCII character data. 
  6618. The file number is set to 1: 
  6619.  
  6620.       1 WOPEN 'NAMEFILE,D'
  6621.  
  6622. The first record (record 0) is a variable-length record written to file number 
  6623. 1. Line feed characters are added automatically as record separators: 
  6624.  
  6625.       1 0 WRITEV 'Jane Doe, Megabyte System, 555-5555'
  6626.  
  6627. Writes the second record to file 1: 
  6628.  
  6629.       1 1 WRITEV 'Jim Diaz, Success Inc., 555-9999'
  6630.  
  6631. Close the file: 
  6632.  
  6633.       CLOSE 1
  6634.  
  6635. Open the same file for read-only operations, with the same file number: 
  6636.  
  6637.       OPEN 'NAMEFILE,D'
  6638.  
  6639. Read the second record first with the line-feed character stripped off: 
  6640.  
  6641.       READVS 1 1
  6642. Jim Diaz, Success Inc., 555-9999
  6643.  
  6644. Now request the first record, again removing the line-feed separator: 
  6645.  
  6646.       READVS 1 0
  6647. Jane Doe, Megabyte Systems, 555-5555
  6648.  
  6649. Close the file: 
  6650.  
  6651.       CLOSE 1
  6652.  
  6653. Delete the file: 
  6654.  
  6655.       DELETE 'NAMEFILE'
  6656.  
  6657.  
  6658. ΓòÉΓòÉΓòÉ 13.10.3. AP 211 Group ΓòÉΓòÉΓòÉ
  6659.  
  6660.  
  6661. FILE: AP 211 Functions 
  6662.  
  6663. REBUILD211               Rebuild an AP 211 file 
  6664. TRYLOAD                  Loads a workspace saved under TryAPL2 
  6665.  
  6666. [R] REBUILD211 F
  6667.  
  6668. Rebuild AP 211 file F. The optional left argument, R, specifies the record 
  6669. length to be used. If no left argument is supplied, the record size of F is 
  6670. used. The resulting file has data stored in contiguous records and uses the 
  6671. minimum space on the disk. 
  6672.  
  6673. TRYLOAD 'filename'
  6674.  
  6675. This function loads a workspace saved under TryAPL2. filename is the name of 
  6676. the file to be rebuilt. The extension  .TRY is added to the name. 
  6677.  
  6678.  
  6679. ΓòÉΓòÉΓòÉ 13.10.4. Delta Group ΓòÉΓòÉΓòÉ
  6680.  
  6681.  
  6682. FILE: Delta Functions 
  6683.  
  6684. ΓòóFM                      Read or write a file with fixed-length records 
  6685. ΓòóFV                      Read or write a file with variable-length records 
  6686.  
  6687. ZΓò£[array] ΓòóFM 'filespec'
  6688. ZΓò£[array] ΓòóFV 'filespec'
  6689.  
  6690. These two functions emulate the ΓòóFM and ΓòóFV external functions of APL2/370. 
  6691.  
  6692. o Reading files: 
  6693.  
  6694.     RΓò£ΓòóFM 'filespec'
  6695.  
  6696.   Reads the file "filespec" and returns a character matrix. Records are padded 
  6697.   on the right with blanks to the length of the longest record. 
  6698.  
  6699.     RΓò£ΓòóFV 'filespec'
  6700.  
  6701.   Reads the file "filespec" and returns a vector of character vectors. Trailing 
  6702.   blanks in any records are deleted. 
  6703.  
  6704. o Writing files: 
  6705.  
  6706.     RΓò£array ΓòóFM 'filespec'
  6707.  
  6708.   Writes the data from the matrix or vector of vectors "array" to the file 
  6709.   "filespec". If "array" is a character matrix, all records are padded with 
  6710.   blanks to the full width of the array. 
  6711.  
  6712.     RΓò£array ΓòóFV 'filespec'
  6713.  
  6714.   Writes the data from the matrix or vector of vectors "array" to the file 
  6715.   "filespec". A file with variable-length records is created. Trailing blanks 
  6716.   in each record are deleted. 
  6717.  
  6718. ΓòóFM and ΓòóFV return a character matrix or a vector of vectors if the file is 
  6719. successfully read, or a numeric return code if the operation results in an AP 
  6720. 210 error. If these functions are being used to write a file, a return code of 
  6721. 0 is returned if the operation is successful. 
  6722.  
  6723. If the left argument of ΓòóFM or ΓòóFV is empty, the file specified by the right 
  6724. argument is erased, if it exists, and a return code of 0 is returned. If the 
  6725. file does not exist, a return code of 2 is given. 
  6726.  
  6727. These functions can be used to read and write files that can be interchanged 
  6728. with other OS/2 applications. 
  6729.  
  6730. Note:  These functions can handle either the CR/LF or LF end-of-line 
  6731. indicators. They automatically write the correct indicator for the running 
  6732. system, and can read files with either type of indicator. 
  6733.  
  6734.  
  6735. ΓòÉΓòÉΓòÉ 13.10.5. Transfer Group ΓòÉΓòÉΓòÉ
  6736.  
  6737. Simulated )IN 
  6738.  
  6739. ZΓò£[NL] IN 'filespec'
  6740. ZΓò£   IN 'filespec names'
  6741.  
  6742. This function imitates the )IN command under the control of AP 210. It can be 
  6743. called from another APL2 function, thus effectively providing a powerful IN 
  6744. facility. The size of arrays that can be handled, however, is restricted by the 
  6745. implementation limit of ╨áTF. See Implementation Limits for further details. 
  6746.  
  6747. You can call this function in two different ways: 
  6748.  
  6749. o To copy a whole file into your active workspace, call the IN function in the 
  6750.   following way: 
  6751.  
  6752.           IN 'filespec'
  6753.  
  6754.   where filespec is the name of the file you want to copy. This can include an 
  6755.   extension. If no extension is specified, a default extension of ".atf" is 
  6756.   initially used. The result is 1 if the file exists or 0 if it does not. 
  6757.  
  6758.   Example: 
  6759.  
  6760.           IN 'MYFILE'
  6761.  
  6762.   This line copies the whole APL2 transfer file, MYFILE.atf, into your active 
  6763.   workspace. 
  6764.  
  6765. o To copy only part of a file (for example, some particular operators, 
  6766.   functions, or variables) into your active workspace, call the IN function in 
  6767.   either of the following ways: 
  6768.  
  6769.           namelist IN 'filespec'
  6770.   or, 
  6771.  
  6772.           IN 'filespec names'
  6773.  
  6774.   In namelist_matrix, you give the names of the operators, functions, and 
  6775.   variables (APL2 objects) you want to copy. If there is more than one object, 
  6776.   each name must be given as a row of a character matrix, as an element of a 
  6777.   vector of character vectors, or in a character vector with each name 
  6778.   separated by one or more blanks. Alternatively, the names can follow the 
  6779.   filespec, separated from one another by one or more blanks. If a name is 
  6780.   enclosed in parentheses, it is assumed to be the name of a character array 
  6781.   (rank not greater than 2) containing a list of objects to be copied. For 
  6782.   filespec, see above. Only the indicated objects are copied into the active 
  6783.   workspace. The function returns a logical vector result-a 1 for each object 
  6784.   copied and 0 for each object not copied. 
  6785.  
  6786.   Example: 
  6787.  
  6788.           (2 3╤å'FUNVAR') IN 'MYFILE'
  6789.  
  6790.   The left argument of the IN function in this example is a 2-by-3 character 
  6791.   matrix, in which the first row is FUN and the second is VAR. This line copies 
  6792.   into your active workspace the objects (which can be operators, functions, or 
  6793.   variables), FUN and VAR, from MYFILE.atf. 
  6794. Simulated )OUT 
  6795.  
  6796. ZΓò£[NL] OUT 'filespec'
  6797. ZΓò£   OUT 'filespec names'
  6798.  
  6799. This function emulates the )OUT command under the control of AP 210, and can be 
  6800. called from another APL2 function, thus effectively providing a powerful OUT 
  6801. facility. You can call this function in two different ways: 
  6802.  
  6803. o To copy your entire active workspace (all operators, functions, and 
  6804.   variables) into an .atf file (that is, a transfer file), call the OUT 
  6805.   function in the following way: 
  6806.  
  6807.           OUT 'filespec'
  6808.  
  6809.   where filespec is the name of the transfer file. This can include an 
  6810.   extension. If no extension is specified, a default extension of ".atf" will 
  6811.   be used. The result is 1 if the operation is successful, or 0 otherwise. 
  6812.  
  6813.   Example: 
  6814.  
  6815.           OUT 'MYFILE'
  6816.  
  6817.   This line copies all operators, functions, and variables of your active 
  6818.   workspace into the file MYFILE.atf. 
  6819.  
  6820. o To copy only part of your workspace (some particular operators, functions or 
  6821.   variables) into a file, call the OUT function in either of the following 
  6822.   ways: 
  6823.  
  6824.           namelist OUT 'filespec'
  6825.   or, 
  6826.  
  6827.           OUT 'filespec names'
  6828.  
  6829.   In namelist, you give the names of the operators, functions, and variables 
  6830.   (APL2 objects) you want to copy. If there is more than one object, each name 
  6831.   must be given as a row of a character matrix, as an element of a vector of 
  6832.   character vectors, or in a character vector with each name separated by one 
  6833.   or more blanks. Alternatively, the names can follow the filespec, separated 
  6834.   from one another by one or more blanks. If a name is enclosed in parentheses, 
  6835.   it is assumed to be the name of a character array (rank not greater than two) 
  6836.   containing a list of objects to be copied. For filespec, see above. Only the 
  6837.   indicated objects are included in the file. The function returns a logical 
  6838.   vector result-1 for each object copied and 0 for each object not copied. 
  6839.  
  6840.   Example: 
  6841.  
  6842.           (2 3╤å'FUNVAR') OUT 'MYFILE'
  6843.  
  6844.   The left argument of the OUT function in the preceding example is a 2-by-3 
  6845.   character matrix, in which the first row is FUN and the second is VAR. This 
  6846.   line creates a transfer file called MYFILE.atf and writes into it the objects 
  6847.   FUN and VAR in the transfer form. 
  6848. Simulated )PIN 
  6849.  
  6850. ZΓò£[NL] PIN 'filespec'
  6851. ZΓò£   PIN 'filespec names'
  6852.  
  6853. This function imitates the )PIN command under the control of AP 210. It 
  6854. performs a protected IN, which works like IN except that an object is copied 
  6855. only if the object name in the active workspace has no current value. 
  6856.  
  6857.  
  6858. ΓòÉΓòÉΓòÉ 13.11. The GRAPHPAK Workspace ΓòÉΓòÉΓòÉ
  6859.  
  6860. The GRAPHPAK workspace distributed with the APL2/2 product uses the AP 207 
  6861. Universal Graphics auxiliary processor to display results in an OS/2 window. 
  6862.  
  6863. GRAPHPAK is a powerful general-purpose graphical library. For a full 
  6864. description of GRAPHPAK, refer to APL2 GRAPHPAK: User's Guide and Reference. 
  6865.  
  6866. Users should be aware of the following differences between the APL2/2 AP 207 
  6867. version of GRAPHPAK, and GRAPHPAK as implemented under APL2/370: 
  6868.  
  6869. o Area fill may not fill some areas (such as a torus) in exactly the same way 
  6870.   as the APL2/370 or APL2/PC versions of GRAPHPAK. In general, when multiple 
  6871.   polygons are used, the fill is compatible, but when images include arcs or 
  6872.   sectors, there may be discernible differences. 
  6873.  
  6874. o APL2/2 GRAPHPAK generates "stroked" characters as its default. 
  6875.  
  6876. o The SMFIELD function is not implemented. 
  6877.  
  6878. o APL2/2 permits the use of a mouse in addition to certain function keys when 
  6879.   using the READ function discussed in the APL2 GRAPHPAK: User's Guide and 
  6880.   Reference. When the left argument of READ is a null, and the intent is to do 
  6881.   freehand drawings within the graphics window, the mouse buttons offer an easy 
  6882.   alternative to the use of the cursor. Each button produces a different color. 
  6883.   To draw freehand, place the mouse pointer where you wish to start and press a 
  6884.   mouse button, then release it and move to the next position, and again press 
  6885.   one of the mouse buttons. Alternatively, function keys may be used to draw 
  6886.   the line, in a variety of colors and patterns. Repeat this procedure until 
  6887.   you are finished, then press Enter. 
  6888.  
  6889. The APL2/2 GRAPHPAK workspace includes seven groups that form a set of 
  6890. functions implemented compatibly across all APL2 platforms. 
  6891.  
  6892. The seven groups are: 
  6893.  
  6894. GPBASE      Contains the fundamental drawing and writing functions. This 
  6895.             workspace contains the base code to use the AP 207 Universal 
  6896.             Graphics auxiliary processor. 
  6897.  
  6898. GPCHT       Contains functions for drawing charts. 
  6899.  
  6900. GPCONT      Contains functions for drawing contour maps. 
  6901.  
  6902. GPDEMO      Contains functions illustrating various aspects of GRAPHPAK. To 
  6903.             start the demonstration, type DEMO. 
  6904.  
  6905. GPFIT       Contains functions for curve fitting. 
  6906.  
  6907. GPGEOM      Contains descriptive geometry functions. 
  6908.  
  6909. GPPLOT      Contains plotting functions. 
  6910.  
  6911. The functions in each of these groups are described in the following sections: 
  6912.  
  6913. o GPBASE 
  6914. o GPCHT 
  6915. o GPCONT 
  6916. o GPDEMO 
  6917. o GPFIT 
  6918. o GPGEOM 
  6919. o GPPLOT 
  6920.  
  6921.  
  6922. ΓòÉΓòÉΓòÉ 13.11.1. GPBASE ΓòÉΓòÉΓòÉ
  6923.  
  6924. This group contains the fundamental drawing and writing functions, and is 
  6925. required by all other GRAPHPAK workspaces. It contains the following functions: 
  6926.  
  6927. COLOR             Changes the current color 
  6928.  
  6929. DRAW              Draws lines between points 
  6930.  
  6931. ERASE             Clears the screen 
  6932.  
  6933. FILL              Fills a polygon 
  6934.  
  6935. FIXVP             Sets the viewport 
  6936.  
  6937. GRFIELD           Sets the graphics field 
  6938.  
  6939. INTO              Used in coordinate transformations 
  6940.  
  6941. MODE              Changes the current line mode (not functional, included for 
  6942.                   compatibility only) 
  6943.  
  6944. READ              Reads coordinates or character data from the screen 
  6945.  
  6946. SMFIELD           Sets the session manager field 
  6947.  
  6948. STYLE             Changes the current fill or line style 
  6949.  
  6950. USE               Permanently changes the current attributes (color and width) 
  6951.  
  6952. USING             Temporarily changes the current attributes (color and width) 
  6953.  
  6954. VIEW              Displays the current contents of the graphics field 
  6955.  
  6956. VIEWPORT          Returns the coordinates of the corners of the current 
  6957.                   clipping viewport 
  6958.  
  6959. WIDTH             Changes the current line mode 
  6960.  
  6961. WRITE             Writes text on the current graphics field 
  6962.  
  6963. XFM               Used in coordinate transformations 
  6964.  
  6965.  
  6966. ΓòÉΓòÉΓòÉ 13.11.2. GPCHT ΓòÉΓòÉΓòÉ
  6967.  
  6968. This group contains functions for drawing charts. It requires GPBASE and 
  6969. GPPLOT, and the following functions are available: 
  6970.  
  6971. CHART             Draws a bar or column chart 
  6972.  
  6973. FREQ              Plots a frequency chart 
  6974.  
  6975. HCHART            Plots a hierarchical chart 
  6976.  
  6977. PIECHART          Draws a pie chart 
  6978.  
  6979. PIELABEL          Labels a pie chart 
  6980.  
  6981. SAXES             Plots all three default axes on a surface or skyscraper chart 
  6982.  
  6983. SAXISX            Plots the X axis of a surface or skyscraper chart with 
  6984.                   definable labels and annotation 
  6985.  
  6986. SAXISY            Plots the Y axis of a surface or skyscraper chart with 
  6987.                   definable labels and annotation 
  6988.  
  6989. SAXISZ            Plots the Z axis of a surface or skyscraper chart with 
  6990.                   definable labels and annotation 
  6991.  
  6992. SLABEL            Writes the default labels on the axes of a surface or 
  6993.                   skyscraper chart. 
  6994.  
  6995. SLBLX             Places definable labels on the X axis of a surface or 
  6996.                   skyscraper chart 
  6997.  
  6998. SLBLY             Places definable labels on the Y axis of a surface or 
  6999.                   skyscraper chart 
  7000.  
  7001. SLBLZ             Places definable labels on the Z axis of a surface or 
  7002.                   skyscraper chart 
  7003.  
  7004. SS                Plots a skyscraper chart 
  7005.  
  7006. STEP              Plots a step chart 
  7007.  
  7008. STITLE            Adds a title to a surface or skyscraper chart 
  7009.  
  7010. SURFACE           Plots a surface chart 
  7011.  
  7012. SXFM              Maps three-dimensional coordinates into a screen window 
  7013.  
  7014. WITH              Formats data for use with PIECHART 
  7015.  
  7016.  
  7017. ΓòÉΓòÉΓòÉ 13.11.3. GPCONT ΓòÉΓòÉΓòÉ
  7018.  
  7019. This group contains functions for drawing contour maps. It requires GPBASE and 
  7020. GPPLOT, and contains the following functions: 
  7021.  
  7022. BY                Used to structure the input to CONTOUR 
  7023.  
  7024. CONTOUR           Draws a contour map 
  7025.  
  7026. OF                Used to structure the input to CONTOUR 
  7027.  
  7028.  
  7029. ΓòÉΓòÉΓòÉ 13.11.4. GPDEMO ΓòÉΓòÉΓòÉ
  7030.  
  7031. This group contains functions illustrating many aspects of the APL2/2 version 
  7032. of GRAPHPAK. The demonstration can be started with the DEMO function, and it 
  7033. cycles through the complete set of demonstrations. 
  7034.  
  7035. The individual demonstration functions contained in this workspace are: 
  7036.  
  7037. APPLE             Shows the use of DRAW to create a picture 
  7038.  
  7039. ATTRIBUTES        Shows the various line type and fill options available 
  7040.  
  7041. BLI               Shows the use of DRAW to create a picture 
  7042.  
  7043. CAYUGAPLOT        Shows the use of PLOT to create line graphs 
  7044.  
  7045. DEMO              Cycles through all the demo functions in the workspace 
  7046.  
  7047. FLAG              Shows the use of DRAW to create a picture 
  7048.  
  7049. FSTAR             Shows the use of DRAW to create a picture 
  7050.  
  7051. HEALTH            Shows the use of CHART to produce a column chart 
  7052.  
  7053. IBMF              Draws the IBM logo 
  7054.  
  7055. MILERUN           Shows the use of CHART to produce a bar chart 
  7056.  
  7057. NHIST             Shows the use of CHART to produce a step chart 
  7058.  
  7059. PIES              Shows the use of CHART to produce a pie chart 
  7060.  
  7061. REVB              Shows the use of CHART to produce a simple bar chart 
  7062.  
  7063. REVC              Shows the use of CHART to produce a simple column chart 
  7064.  
  7065. REVENUES          Shows the use of PLOT to create line graphs 
  7066.  
  7067. SKYSCRAPER        Shows the use of SS to produce a skyscraper chart 
  7068.  
  7069. SPIRAL            Shows the use of SKETCH, THREEVIEWS, and PERSPECTIVE to 
  7070.                   create pictures 
  7071.  
  7072. WAVEGUIDE         Shows the use of SURFACE to produce a surface chart 
  7073.  
  7074. WGCONT            Shows the use of SURFACE to produce a contour chart 
  7075.  
  7076.  
  7077. ΓòÉΓòÉΓòÉ 13.11.5. GPFIT ΓòÉΓòÉΓòÉ
  7078.  
  7079. This group contains functions for curve fitting. It requires GPBASE and GPPLOT, 
  7080. and contains the following functions: 
  7081.  
  7082. AVG               Prepares data for FIT to plot the average Y value 
  7083.  
  7084. CLEAR             Clears the display screen 
  7085.  
  7086. FIT               Draws a line graph through data points prepared by AVG, SL, 
  7087.                   POLY, EXP, LOG, POWER, LOGLOG, or SPLINE 
  7088.  
  7089. EXP               Prepares data for FIT to plot the best log-linear fit on 
  7090.                   linear axes 
  7091.  
  7092. FITFUN            Executes the last function plotted 
  7093.  
  7094. LOG               Prepares data for FIT to plot the best log-linear fit on 
  7095.                   log-linear axes 
  7096.  
  7097. LOGLOG            Prepares data for FIT to plot the best log-log fit on log-log 
  7098.                   axes 
  7099.  
  7100. POLY              Prepares data for FIT to plot the best polynomial of 
  7101.                   specified degree 
  7102.  
  7103. POWER             Prepares data for FIT to plot the best log-log fit on linear 
  7104.                   axes 
  7105.  
  7106. SCRATCH           Erases points from a data array 
  7107.  
  7108. SL                Prepares data from which FIT can plot the best straight-line 
  7109.                   fit 
  7110.  
  7111. SPLINE            Prepares data for FIT to use in plotting a cubic spline 
  7112.                   through specified points 
  7113.  
  7114.  
  7115. ΓòÉΓòÉΓòÉ 13.11.6. GPGEOM ΓòÉΓòÉΓòÉ
  7116.  
  7117. This group contains descriptive geometry functions. It requires GPBASE and 
  7118. GPPLOT, and contains the following functions: 
  7119.  
  7120. ISOMETRIC         Restructures data so that SKETCH produces an isometric 
  7121.                   projection 
  7122.  
  7123. MAGNIFY           Transforms a data array so that the object represented is 
  7124.                   magnified in size 
  7125.  
  7126. OBLIQUE           Restructures data so that SKETCH produces an oblique 
  7127.                   projection 
  7128.  
  7129. PERSPECTIVE       Restructures data so that SKETCH produces a perspective 
  7130.                   drawing 
  7131.  
  7132. RETICLE           Draws an outline of the clipping viewport and a pair of axes, 
  7133.                   showing the extent of the window into problem space 
  7134.  
  7135. ROTATE            Transforms a data array so that the object represented is 
  7136.                   rotated 
  7137.  
  7138. SCALE             Scales all elements of a data array so that the largest lies 
  7139.                   within set bounds 
  7140.  
  7141. SKETCH            Produces an orthogonal projection 
  7142.  
  7143. STEREO            Produces a stereo pair of images of an object 
  7144.  
  7145. THREEVIEWS        Produces three views of an object, projected into the planes 
  7146.                   of the axes 
  7147.  
  7148. TRANSLATE         Transforms a data array so that the object represented is 
  7149.                   moved 
  7150.  
  7151.  
  7152. ΓòÉΓòÉΓòÉ 13.11.7. GPPLOT ΓòÉΓòÉΓòÉ
  7153.  
  7154. This group contains plotting functions. It is required by GPFIT, GPCONT, and 
  7155. GPCHT, and requires GPBASE. It contains the following functions: 
  7156.  
  7157. AND               Aids in formatting input for PLOT or SPLOT 
  7158.  
  7159. ANNX              Draws an annotated horizontal axis with definable label 
  7160.                   positions 
  7161.  
  7162. ANNY              Draws an annotated vertical axis with definable label 
  7163.                   positions 
  7164.  
  7165. AXES              Draws default axes 
  7166.  
  7167. AXIS              Draws definable axes 
  7168.  
  7169. HOR               Draws an annotated horizontal axis with default label 
  7170.                   positions 
  7171.  
  7172. LABEL             Produces the default labels for the X and Y axes 
  7173.  
  7174. LBLX              Produces definable labels for the X axis 
  7175.  
  7176. LBLY              Produces definable labels for the Y axis 
  7177.  
  7178. PLOT              Plots a line graph 
  7179.  
  7180. RESTORE           Restores all attribute and plotting variables to their 
  7181.                   default values 
  7182.  
  7183. SPLOT             Similar to PLOT, but allows more user control over plotting 
  7184.                   characteristics 
  7185.  
  7186. TITLE             Adds a title to the graph 
  7187.  
  7188. VER               Draws an annotated vertical axis with default label positions 
  7189.  
  7190. VS                Aids in formatting input for PLOT or SPLOT. 
  7191.  
  7192. To run the demonstration contained in the GRAPHPAK workspace, enter: 
  7193.  
  7194.       )LOAD 2 GRAPHPAK
  7195.       DEMO
  7196.  
  7197.  
  7198. ΓòÉΓòÉΓòÉ 13.12. The IDIOMS Workspace ΓòÉΓòÉΓòÉ
  7199.  
  7200. APL2 is a very powerful and concise language. Although experienced APL2 
  7201. programmers can produce working solutions to complex problems in a very short 
  7202. time, learning the APL2 language can take years. The novice is usually 
  7203. entranced with the power of APL2, but may have a hard time thinking in vector 
  7204. notation. APL2 algorithms are not always obvious! 
  7205.  
  7206. In order to speed up the learning process of APL2, IDIOMS was developed. With 
  7207. over 600 distinct APL2 phrases, sorted into 24 general categories, IDIOMS 
  7208. represents a fairly complete list of solutions to common application problems 
  7209. and lets you take advantage of algorithms that many others have developed. 
  7210.  
  7211. Since this list is in soft copy, you can access it directly from your workspace 
  7212. and dynamically insert the idioms into your own code. 
  7213.  
  7214. o Executing the IDIOMS Function 
  7215.  
  7216.  
  7217. ΓòÉΓòÉΓòÉ 13.12.1. Executing the IDIOMS Function ΓòÉΓòÉΓòÉ
  7218.  
  7219. ZΓò£IDIOMS
  7220.  
  7221. Copy the IDIOMS function into your active workspace and then execute it: 
  7222.  
  7223.       )PCOPY 1 IDIOMS IDIOMS
  7224.       IDIOMS
  7225.  
  7226. You can run this program from your own workspace, because it does not overwrite 
  7227. any programs you use. All the subroutines are local functions loaded from the 
  7228. AP 211 object file, IDIOMS.aof. The IDIOMS function, as supplied, assumes that 
  7229. this IDIOMS.aof file is in the same directory as the library 1 workspaces. If 
  7230. this is not the case, edit the IDIOMS function to specify the appropriate 
  7231. directory. 
  7232.  
  7233. Selections are stored in a file called IDIOMS.asf, which is created 
  7234. automatically if it does not already exist. This is ordinarily created in the 
  7235. default home directory, but you can edit the IDIOMS function to specify the 
  7236. required directory. 
  7237.  
  7238. Once IDIOMS is executing, a full-screen interface gives you control over all 
  7239. the facilities available. The following keys can be used from the main screen. 
  7240. Use the F1 (Help) key to get assistance on the Window or Group screen. 
  7241.  
  7242. F1             Help - Display a series of screens that give assistance for the 
  7243.                current screen. 
  7244.  
  7245. F2             Window - Display a window of previous searches. Move the cursor 
  7246.                to the desired item and press Enter to select a search, which 
  7247.                appears on the main screen. Press F3 to return to the main 
  7248.                screen. 
  7249.  
  7250. F3             Return - Return to the APL2 session, passing any idioms selected 
  7251.                with F9 to the workspace as an explicit result. 
  7252.  
  7253. F4             Function - Save the APL2 idiom identified by the cursor as a 
  7254.                function called IDIOM_LIST. If IDIOM_LIST already exists, the 
  7255.                selected idiom is appended as a new line to the end of the 
  7256.                function. This function can be a prototype for a new program 
  7257.                using the selected expressions to accomplish the desired task. 
  7258.  
  7259. F5             Local Search - Search the displayed group of idioms for the 
  7260.                search argument. This can be used to narrow the search to a 
  7261.                particular group of idioms. 
  7262.  
  7263. F6             Group - Display a list of each group of idioms. Place the cursor 
  7264.                beside the desired group and press F6 again to select that 
  7265.                group. Press F3 to return to the main screen without selecting a 
  7266.                group. 
  7267.  
  7268. F7             PageUp - Scroll one screen toward the top. 
  7269.  
  7270. F8             PageDown - Scroll one screen toward the bottom. 
  7271.  
  7272. F9             Result - Append the idiom identified by the cursor to the result 
  7273.                of the IDIOMS function. Using the session manager, you can place 
  7274.                these lines in your function by entering function definition 
  7275.                mode and then inserting a line number [n] at the beginning of 
  7276.                each desired idiom. 
  7277.  
  7278. F10            Environment - Cycle environment for which appropriate idioms are 
  7279.                displayed. Note that idioms selected from other than the 
  7280.                workstation environment may not work on APL2/2. 
  7281.  
  7282. Shift-F7       Home - Scroll to the top. 
  7283.  
  7284. Shift-F8       End - Scroll to the bottom. 
  7285.  
  7286. PageUp         Scroll one screen toward the top. 
  7287.  
  7288. PageDown       Scroll one screen toward the bottom. 
  7289.  
  7290. Home           Scroll to the top. 
  7291.  
  7292. End            Scroll to the bottom. 
  7293.  
  7294. Enter          Search through all the idioms for the search argument. 
  7295.  
  7296. The idioms are available in either index origin. The IDIOMS program lets you 
  7297. select the index origin preferred for the code you are writing. To change the 
  7298. origin, overtype the displayed value with the desired index origin and press 
  7299. Enter. 
  7300.  
  7301. To trace the searches that you generate, IDIOMS calls itself recursively. You 
  7302. can do multiple searches, without losing the results of any intermediate 
  7303. search. 
  7304.  
  7305. o Categories 
  7306. o Naming Conventions 
  7307.  
  7308.  
  7309. ΓòÉΓòÉΓòÉ 13.12.1.1. Categories ΓòÉΓòÉΓòÉ
  7310.  
  7311. To facilitate fast selection of idioms, they are grouped into categories, as 
  7312. follows: 
  7313.  
  7314.  1  - Assignment algorithms 
  7315.  2  - Boolean selection algorithms 
  7316.  3  - Boolean tests general algorithms 
  7317.  4  - Boolean tests numeric algorithms 
  7318.  5  - Computational algorithms 
  7319.  6  - Conversion algorithms 
  7320.  7  - Date and time algorithms 
  7321.  8  - External name routine algorithms 
  7322.  9  - Financial algorithms 
  7323. 10  - Formatting algorithms 
  7324. 11  - Function algorithms 
  7325. 12  - Manipulating characters algorithms 
  7326. 13  - Manipulating numbers algorithms 
  7327. 14  - Numeric range algorithms 
  7328. 15  - Numerical geometry algorithms 
  7329. 16  - Selecting positions algorithms 
  7330. 17  - Sorting algorithms 
  7331. 18  - Statistics descriptive algorithms 
  7332. 19  - Statistics distribution algorithms 
  7333. 20  - Structural algorithms 
  7334. 21  - Text arrangement algorithms 
  7335. 22  - Text selection and change algorithms 
  7336. 23  - Trigonometry algorithms 
  7337. 24  - Vectorizing algorithms 
  7338.  
  7339.  
  7340. ΓòÉΓòÉΓòÉ 13.12.1.2. Naming Conventions ΓòÉΓòÉΓòÉ
  7341.  
  7342. A consistent naming convention is used throughout the list. The names used are: 
  7343.  
  7344. These are combined in various ways to identify the type of object. For example: 
  7345.  
  7346.  
  7347. ΓòÉΓòÉΓòÉ 13.12.1.2.1. IDIOMS Naming convention ΓòÉΓòÉΓòÉ
  7348.  
  7349.  
  7350. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7351.  
  7352.  
  7353. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7354.  
  7355. Rank 
  7356.  
  7357.  
  7358. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7359.  
  7360.  
  7361. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7362.  
  7363. Type 
  7364.  
  7365.  
  7366. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7367.  
  7368.  
  7369. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7370.  
  7371. Usage 
  7372.  
  7373.  
  7374. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7375.  
  7376.  
  7377.  
  7378. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7379.  
  7380. Array 
  7381.  
  7382.  
  7383. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7384.  
  7385.  
  7386.  
  7387. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7388.  
  7389. Boolean 
  7390.  
  7391.  
  7392. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7393.  
  7394.  
  7395.  
  7396. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7397.  
  7398. Graded or grouped 
  7399.  
  7400.  
  7401. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7402.  
  7403.  
  7404.  
  7405. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7406.  
  7407. Matrix 
  7408.  
  7409.  
  7410. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7411.  
  7412.  
  7413.  
  7414. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7415.  
  7416. Character 
  7417.  
  7418.  
  7419. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7420.  
  7421.  
  7422.  
  7423. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7424.  
  7425. Lengths 
  7426.  
  7427.  
  7428. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7429.  
  7430.  
  7431.  
  7432. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7433.  
  7434. One item vector 
  7435.  
  7436.  
  7437. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7438.  
  7439.  
  7440.  
  7441. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7442.  
  7443. Floating point 
  7444.  
  7445.  
  7446. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7447.  
  7448.  
  7449.  
  7450. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7451.  
  7452. Positions 
  7453.  
  7454.  
  7455. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7456.  
  7457.  
  7458.  
  7459. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7460.  
  7461. Scalar or one item vector 
  7462.  
  7463.  
  7464. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7465.  
  7466.  
  7467.  
  7468. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7469.  
  7470. Integer 
  7471.  
  7472.  
  7473. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7474.  
  7475.  
  7476.  
  7477. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7478.  
  7479. Unique 
  7480.  
  7481.  
  7482. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7483.  
  7484.  
  7485.  
  7486. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7487.  
  7488. Vector 
  7489.  
  7490.  
  7491. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7492.  
  7493.  
  7494.  
  7495. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7496.  
  7497. Numeric 
  7498.  
  7499.  
  7500. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7501.  
  7502.  
  7503.  
  7504. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7505.  
  7506. Extension 
  7507.  
  7508.  
  7509. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7510.  
  7511.  
  7512. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7513.  
  7514.  
  7515. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7516.  
  7517.  
  7518.  
  7519. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7520.  
  7521. Complex 
  7522.  
  7523.  
  7524. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7525.  
  7526.  
  7527.  
  7528. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7529.  
  7530. Extension 
  7531.  
  7532.  
  7533. ΓòÉΓòÉΓòÉ 13.12.1.2.2. IDIOMS Name Examples ΓòÉΓòÉΓòÉ
  7534.  
  7535.  
  7536. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7537.  
  7538. Name 
  7539.  
  7540.  
  7541. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7542.  
  7543. Contents 
  7544.  
  7545.  
  7546. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7547.  
  7548. Name 
  7549.  
  7550.  
  7551. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7552.  
  7553. Contents 
  7554.  
  7555.  
  7556. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7557.  
  7558. A,AX,AY 
  7559.  
  7560.  
  7561. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7562.  
  7563. General arrays 
  7564.  
  7565.  
  7566. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7567.  
  7568. IM 
  7569.  
  7570.  
  7571. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7572.  
  7573. Integer matrix 
  7574.  
  7575.  
  7576. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7577.  
  7578. BM 
  7579.  
  7580.  
  7581. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7582.  
  7583. Boolean matrix 
  7584.  
  7585.  
  7586. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7587.  
  7588. N,NX,NY 
  7589.  
  7590.  
  7591. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7592.  
  7593. Numeric vectors 
  7594.  
  7595.  
  7596. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7597.  
  7598. BS 
  7599.  
  7600.  
  7601. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7602.  
  7603. Boolean scalar 
  7604.  
  7605.  
  7606. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7607.  
  7608. PAV 
  7609.  
  7610.  
  7611. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7612.  
  7613. Position array of vectors 
  7614.  
  7615.  
  7616. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7617.  
  7618. CA 
  7619.  
  7620.  
  7621. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7622.  
  7623. Character array 
  7624.  
  7625.  
  7626. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7627.  
  7628. PS 
  7629.  
  7630.  
  7631. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7632.  
  7633. Position scalar 
  7634.  
  7635.  
  7636. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7637.  
  7638. C,CX,CY 
  7639.  
  7640.  
  7641. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7642.  
  7643. Character vectors 
  7644.  
  7645.  
  7646. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7647.  
  7648. UM 
  7649.  
  7650.  
  7651. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7652.  
  7653. Unique matrix 
  7654.  
  7655.  
  7656. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7657.  
  7658. GAF 
  7659.  
  7660.  
  7661. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7662.  
  7663. Graded array of floating point 
  7664.  
  7665.  
  7666. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7667.  
  7668. VM 
  7669.  
  7670.  
  7671. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7672.  
  7673. Vector of matrices 
  7674.  
  7675.  
  7676. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7677.  
  7678. GI 
  7679.  
  7680.  
  7681. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7682.  
  7683. Graded integer vector 
  7684.  
  7685.  
  7686. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7687.  
  7688. VV 
  7689.  
  7690.  
  7691. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7692.  
  7693. Vector of vectors 
  7694.  
  7695.  
  7696. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7697.  
  7698. GM 
  7699.  
  7700.  
  7701. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7702.  
  7703. Graded matrix 
  7704.  
  7705.  
  7706. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7707.  
  7708. V,X,Y 
  7709.  
  7710.  
  7711. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7712.  
  7713. General vectors 
  7714.  
  7715.  
  7716. ΓòÉΓòÉΓòÉ 13.13. The MATHFNS Workspace ΓòÉΓòÉΓòÉ
  7717.  
  7718. The functions in this workspace are described below. 
  7719.  
  7720. o Matrix Inverse and Matrix Divide 
  7721. o Eigenvalues and Eigenvectors 
  7722. o Factorial and Binomial 
  7723. o Fast Fourier Transform 
  7724. o Formatting Complex Numbers 
  7725. o Roots of Polynomials 
  7726.  
  7727.  
  7728. ΓòÉΓòÉΓòÉ 13.13.1. Functions in the MATHFNS Workspace ΓòÉΓòÉΓòÉ
  7729.  
  7730.  
  7731. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  7732.  
  7733. DOMINO             Computes matrix inverse or matrix divide 
  7734. DOMINOF            Computes matrix inverse or matrix divide (fast) 
  7735. EIGEN              Computes eigenvalues and eigenvectors 
  7736. EIGENVALUES        Computes eigenvalues 
  7737. FACTORIAL          Computes factorials and binomials 
  7738. FFT                Computes fast Fourier transform 
  7739. FMTPD              Formats in polar form with angular measure in degrees 
  7740. FMTPR              Formats in polar form with angular measure in radians 
  7741. IFFT               Computes inverse fast Fourier transform 
  7742. POLYZ              Computes the zeros of polynomials 
  7743.  
  7744.  
  7745. ΓòÉΓòÉΓòÉ 13.13.2. Matrix Inverse and Matrix Divide ΓòÉΓòÉΓòÉ
  7746.  
  7747. ZΓò£  DOMINO R   ╤ä Matrix inverse
  7748. ZΓò£L DOMINO R   ╤ä Matrix divide
  7749. ZΓò£  DOMINOF R  ╤ä Matrix inverse (fast)
  7750. ZΓò£L DOMINOF R  ╤ä Matrix divide (fast)
  7751.  
  7752. These two functions provide a direct replacement for the matrix inverse and 
  7753. matrix divide (╨ó) primitive when applied to arguments containing complex 
  7754. numbers. DOMINO is a direct APL2 implementation of the algorithm used by the 
  7755. primitive ╨ó function of APL2/370. By applying the primitive ╨ó function of 
  7756. APL2/2 to combinations of the real and imaginary parts of its arguments, 
  7757. DOMINOF produces results equivalent to those given by the DOMINO function. This 
  7758. is usually faster than DOMINO, but the intermediate applications of the 
  7759. primitive APL2/2 ╨ó function may fail for some arguments. 
  7760.  
  7761.  
  7762. ΓòÉΓòÉΓòÉ 13.13.3. Eigenvalues and Eigenvectors ΓòÉΓòÉΓòÉ
  7763.  
  7764. ZΓò£  EIGEN R
  7765. ZΓò£L EIGEN R
  7766.  
  7767. The right argument R must be a simple square matrix of real numbers. Z is a 
  7768. simple real or complex matrix of shape 1 0+╤åR containing the eigenvalues and 
  7769. the eigenvectors of R. If R has shape N by N, then Z has N+1 rows and N 
  7770. columns. The first row of Z contains the eigenvalues of R, and the remaining 
  7771. rows of Z contain the corresponding right eigenvectors of R. That is, each 
  7772. column of Z contains an eigenvalue and its corresponding right eigenvector. 
  7773.  
  7774.       EIGEN 2 2╤å1 0 0 2
  7775. 1 2
  7776. 1 0
  7777. 0 1
  7778.  
  7779. The eigenvalues X and the right eigenvectors V can be obtained by: 
  7780.  
  7781.       ZΓò£EIGEN R
  7782.       XΓò£Z[1;]
  7783.       VΓò£1 0ΓòƒZ
  7784.  
  7785. These statements obey the identity: 
  7786.  
  7787.       X╤ù[2]V Γò£Γòò R+.╤ùV
  7788.  
  7789. The eigenvalues X and the left eigenvectors V can be obtained by: 
  7790.  
  7791.       ZΓò£╤ì EIGEN ╤ìR
  7792.       XΓò£Z[;1]
  7793.       VΓò£0 1ΓòƒZ
  7794.  
  7795. They obey the identity: 
  7796.  
  7797.       X╤ù[1]V Γò£Γòò V+.╤ùR
  7798.  
  7799. In the dyadic case, L is also a simple square matrix of real numbers, and ╤åL 
  7800. equals ╤åR. Z is a simple real or complex matrix of shape 1 0+╤åR containing the 
  7801. solution to the generalized eigenvalue problem for L and R: 
  7802.  
  7803.       ZΓò£L EIGEN R
  7804.       XΓò£Z[1;]
  7805.       VΓò£1 0ΓòƒZ
  7806.  
  7807. They obey the identity: 
  7808.  
  7809.       (L+.╤ùX)╤ù[2]V Γò£Γòò R+.╤ùV
  7810.  
  7811. The eigenvalues and eigenvectors are computed by using the "QZ Algorithm". (See 
  7812. "An Algorithm for Generalized Matrix Eigenvalue Problems" by C.B. Moler and 
  7813. G.W. Stewart, SIAM Journal of Numerical Analysis, 10: 241-256, 1973.) The 
  7814. numerical accuracy of the result depends upon the "condition" of the matrix of 
  7815. eigenvectors. In particular, accuracy may be degraded if there are repeated 
  7816. eigenvalues. 
  7817.  
  7818. ZΓò£  EIGENVALUES R
  7819. ZΓò£L EIGENVALUES R
  7820.  
  7821. This function takes the same arguments as EIGEN but returns only the 
  7822. eigenvalues. It is faster than the EIGEN function for the same inputs, and can 
  7823. be used whenever the full result is not required. 
  7824.  
  7825.  
  7826. ΓòÉΓòÉΓòÉ 13.13.4. Factorial and Binomial ΓòÉΓòÉΓòÉ
  7827.  
  7828. ZΓò£  FACTORIAL R  ╤ä Factorial
  7829. ZΓò£L FACTORIAL R  ╤ä Binomial
  7830.  
  7831. This function provides a direct replacement for the primitive factorial or 
  7832. binomial (!) function when applied to arguments containing complex numbers. 
  7833. FACTORIAL is a direct APL2 implementation of the algorithm used by the 
  7834. primitive ! function of APL2/370. 
  7835.  
  7836.  
  7837. ΓòÉΓòÉΓòÉ 13.13.5. Fast Fourier Transform ΓòÉΓòÉΓòÉ
  7838.  
  7839. ZΓò£FFT R   ╤ä Fast Fourier Transform
  7840.  
  7841. This function computes the discrete Fourier transform of a set of  numbers R. 
  7842.  
  7843. The right argument R is a simple vector of 2*N complex or real numbers where N 
  7844. is a positive integer. The result Z is a simple vector of 2*N complex numbers 
  7845. with the discrete Fourier transform of R. 
  7846.  
  7847. The result of the FFT function corresponds to that of the discrete Fourier 
  7848. transform as defined by SC23-0526, Engineering and Scientific Subroutine 
  7849. Library, Guide and Reference: 
  7850.  
  7851. ZΓò£IFFT R   ╤ä Inverse Fast Fourier Transform
  7852.  
  7853. This function computes the inverse Fourier transform of a set of  numbers R. 
  7854.  
  7855.       R Γò£Γòò IFFT FFT R
  7856.  
  7857. The right argument R is a simple vector of 2*N complex or real numbers where N 
  7858. is a positive integer. The result Z is a simple vector of 2*N complex numbers 
  7859. with the inverse discrete Fourier transform of R. 
  7860.  
  7861. The IFFT function differs only in scale and phase. 
  7862.  
  7863. For example: 
  7864.  
  7865.       IFFT 2 0J1 0 0J┬ñ1
  7866. 0.5 1 0.5 0
  7867.       IFFT 2 1 0 1
  7868. 1 0.5 0 0.5
  7869.  
  7870.  
  7871. ΓòÉΓòÉΓòÉ 13.13.6. Formatting Complex Numbers ΓòÉΓòÉΓòÉ
  7872.  
  7873. ZΓò£FMTPD R  ╤ä ForMaT Polar Degrees
  7874.  
  7875. This function formats complex numbers in the right argument R in polar form, 
  7876. with angular measure in degrees. Z is a simple character array. 
  7877.  
  7878. ZΓò£FMTPR R  ╤ä ForMaT Polar Radians
  7879.  
  7880. This function formats complex numbers in the right argument R in polar form, 
  7881. with angular measure in radians. Z is a simple character array. 
  7882.  
  7883.  
  7884. ΓòÉΓòÉΓòÉ 13.13.7. Roots of Polynomials ΓòÉΓòÉΓòÉ
  7885.  
  7886. ZΓò£POLYZ R  ╤ä POLYnomial Zeros
  7887.  
  7888. The right argument R must be a simple nonempty vector of real or complex 
  7889. numbers, and must not contain leading zeros. R represents a polynomial with 
  7890. coefficients in decreasing order of powers (constant on the right). Z is a 
  7891. simple vector of shape ┬ñ1+╤åR, containing the zeros of the polynomial R. 
  7892.  
  7893. If F is the polynomial represented by R, and F(x) =  +  + Cx + D, then R is the 
  7894. vector (A B C D). If the result Z is the vector (P Q R), then F(x) = 
  7895. (x-P)(x-Q)(x-R). If R is real, and the length of R is even, then Z contains at 
  7896. least one real number. 
  7897.  
  7898.       POLYZ  ┬ñ 2  1
  7899. 0 . 5
  7900.       POLYZ  2  0J1
  7901. 0J ┬ñ 0 . 5
  7902.       POLYZ  1  ┬ñ 2  1
  7903. 1  1
  7904.       POLYZ  1  0  1
  7905. 0J1  0J ┬ñ 1
  7906.       POLYZ  1  ┬ñ 6  11  ┬ñ 6
  7907. 1  2  3
  7908.       POLYZ  1  ┬ñ 20  154  ┬ñ 584  1153  ┬ñ 1124  420
  7909. 1  1 . 999999978  2 . 000000022  3  5  7
  7910.  
  7911. The zeros are computed using the Jenkins and Traub algorithms. The accuracy of 
  7912. the solution depends on the "condition" of the polynomial. In particular, 
  7913. accuracy can be degraded if there are repeated zeros. Also, numerical roundoff 
  7914. can cause a pair of equal real zeros to appear as a complex conjugate pair. 
  7915.  
  7916. POLYZ uses subroutines POLYZC and POLYZF. 
  7917.  
  7918.  
  7919. ΓòÉΓòÉΓòÉ 13.14. The MIGRATE Workspace ΓòÉΓòÉΓòÉ
  7920.  
  7921. The MIGRATE workspace contains functions useful in migrating workspaces from 
  7922. other APL2 platforms. 
  7923.  
  7924. ATFUSTOLC A
  7925.  
  7926. Takes the name of a transfer form file that has been binary downloaded from 
  7927. APL2/370, and changes all the underbarred letters to the equivalent lowercase 
  7928. characters. 
  7929.  
  7930. This differs from using CASE(1) or CASE(2) on the host before creating and 
  7931. downloading a transfer file, in that this converts underbarred letters even in 
  7932. literal constants, function or operator comments, and arrays. 
  7933.  
  7934. VSCOPY A
  7935.  
  7936. VSCOPY is a function that makes it possible for objects from a VS APL workspace 
  7937. (saved with the VS APL )SAVE command as a CMS file or a TSO data set, and then 
  7938. binary downloaded to an OS/2 file) to be copied directly into the active 
  7939. workspace of APL2/2. The full syntax of VSCOPY is: 
  7940.  
  7941.       VSCOPY 'wsname [object_list]'
  7942.  
  7943. where: 
  7944.  
  7945. wsname            The workspace name. If no extension is given, a default 
  7946.                   extension of .VWS is appended. If the name contains one or 
  7947.                   more dots or is enclosed in quotes, it is used exactly as 
  7948.                   given. 
  7949.  
  7950. object_list       The list of names of objects to be copied. This may be 
  7951.                   omitted, in which case all objects in the workspace are 
  7952.                   copied. 
  7953.  
  7954. Groups are copied in as character arrays, with each name represented as a row 
  7955. in the array. The names of all groups copied are added into the variable grps. 
  7956.  
  7957. Object names may be prefixed by an asterisk ("*"): 
  7958.  
  7959. *function_name         Causes the function to be left in its canonical form 
  7960.  
  7961. *group_name            Causes the group definition, but not its contents to be 
  7962.                        copied 
  7963.  
  7964. *variable_name         Causes the variable to be left untranslated 
  7965.  
  7966.  
  7967. ΓòÉΓòÉΓòÉ 13.15. The OS2 Workspace ΓòÉΓòÉΓòÉ
  7968.  
  7969. The OS2 workspace uses AP 100 to invoke some useful OS/2 commands. Except where 
  7970. noted, these are monadic functions. All functions return either 0 or data if 
  7971. successful. They return a numeric error code if an error occurs. The functions 
  7972. available are: 
  7973.  
  7974. ZΓò£DIR path
  7975.  
  7976. DIR returns a directory list. This is equivalent to the OS/2 "DIR" command. The 
  7977. right argument, path, is the path leading to the directory whose contents are 
  7978. to be displayed. 
  7979.  
  7980. ZΓò£ERASE FN
  7981.  
  7982. ERASE erases a file. The right argument, FN, has the form 'filename', where 
  7983. 'filename' is the name of the file to be erased, and can include a path 
  7984. definition. 
  7985.  
  7986. ZΓò£HOST 'cmd'
  7987.  
  7988. Issues command "cmd" to OS/2 through AP 100. When HOST '' is executed on 
  7989. APL2/2, it returns "OS/2", which can be used to identify the operating system. 
  7990.  
  7991. ZΓò£LIBS
  7992.  
  7993. Returns a character matrix giving the definition of each valid library number. 
  7994.  
  7995. ZΓò£MKDIR path
  7996.  
  7997. MKDIR creates a new subdirectory. 
  7998.  
  7999. ZΓò£CMD PIPE DATA
  8000.  
  8001. The PIPE function provides a means to pipe APL2 data to an OS/2 command and 
  8002. returns any output generated by the command. 
  8003.  
  8004. The right argument, DATA, must be either a simple character vector, a character 
  8005. matrix, or a vector of character vectors specifying the input to be passed to 
  8006. the command as "stdin" (standard input). If this is an empty vector, no input 
  8007. is passed to the command. The left argument, CMD, must be a simple character 
  8008. vector specifying the command to be executed. The result is a vector of vectors 
  8009. containing the output "stdout" (standard output) generated by executing the 
  8010. command. Some examples of the use of the PIPE function: 
  8011.  
  8012. To get names of APL workspaces and transfer files, sorting by date: 
  8013.  
  8014.       ╤â'dir /b/od *.atf *.apl' PIPE ''
  8015.  
  8016. To run batch scripts through the interpreter: 
  8017.  
  8018.       JOB1Γò£')LOAD 1 DISPLAY' 'DISPLAY ''APL2'' 123'
  8019.       JOB2Γò£')LOAD 2 OS2' 'ΓòûPIPE[╨á]Γòû'
  8020.       OUTPUTΓò£(╤é'apl2 -sm piped -quiet on')PIPEΓûáJOB1 JOB2
  8021.  
  8022. ZΓò£RENAME ONFN       ZΓò£OFN RENAME NFN
  8023.  
  8024. RENAME renames a file. The right argument, ONFN, has the form 'oldname newname' 
  8025. where oldname is the name of the file to be renamed (and may include a path 
  8026. definition), and newname is the new name by which the file is to be known. 
  8027. RENAME can also be used dyadically, with the old name as the left argument and 
  8028. the new name as the right argument. 
  8029.  
  8030. ZΓò£RMDIR path
  8031.  
  8032. RMDIR removes the subdirectory pointed to by path. 
  8033.  
  8034.  
  8035. ΓòÉΓòÉΓòÉ 13.16. The PMTOOLS Workspace ΓòÉΓòÉΓòÉ
  8036.  
  8037. This workspace contains tools for building Presentation Manager applications. 
  8038. The general classes of functions are: 
  8039.  
  8040. o Dialog building functions 
  8041. o DLL and dialog processing functions 
  8042. o Printing functions 
  8043. o Utility functions 
  8044.  
  8045. o Dialog Building Functions 
  8046. o DLL and Dialog Processing Functions 
  8047. o Printing Functions 
  8048. o Utility Functions 
  8049.  
  8050.  
  8051. ΓòÉΓòÉΓòÉ 13.16.1. Dialog Building Functions ΓòÉΓòÉΓòÉ
  8052.  
  8053. The dialog building functions provide an interface from APL2 to the dialog 
  8054. editor, linkage editor, and resource compiler that are included in the OS/2 
  8055. Developer's Toolkit product. 
  8056.  
  8057. DLGEDIT NAME 
  8058.         Invokes the dialog editor on resource file NAME 
  8059.  
  8060. CREATEDLL NAME 
  8061.         Creates dynamic link library NAME 
  8062.  
  8063. COMPILERES NAME 
  8064.         Compiles resource file NAME into DLL NAME 
  8065.  
  8066.  
  8067. ΓòÉΓòÉΓòÉ 13.16.2. DLL and Dialog Processing Functions ΓòÉΓòÉΓòÉ
  8068.  
  8069. The DLL and dialog processing functions allow an application to easily access 
  8070. dialog resources in DLLs. 
  8071.  
  8072. HMODULEΓò£LOADDLL NAME 
  8073.         Loads DLL NAME and returns its handle, HMODULE. 
  8074.  
  8075. HANDLEΓò£HMODULE LOADDLG ID 
  8076.         Loads dialog ID from loaded DLL HMODULE; returns dialog HANDLE 
  8077.  
  8078. DESTROYDLG HANDLE 
  8079.         Destroys dialog HANDLE 
  8080.  
  8081. FREEDLL HMODULE 
  8082.         Frees loaded DLL HMODULE 
  8083.  
  8084. RESULTΓò£ID TESTDLG NAME 
  8085.         Loads and processes dialog ID from DLL NAME. Returns value established 
  8086.         by WinDismissDlg. 
  8087.  
  8088. HWND MOVEWINDOW XY 
  8089.         Moves window with handle HWND to coordinates XY. 
  8090.  
  8091.  
  8092. ΓòÉΓòÉΓòÉ 13.16.3. Printing Functions ΓòÉΓòÉΓòÉ
  8093.  
  8094. The printing functions allow applications to produce printed documents. 
  8095.  
  8096. The functions correspond to the messages that APL2 print objects process. APL2 
  8097. print objects are documented in the APL2 Presentation Manager Services section. 
  8098.  
  8099. CREATE_PRINTER 
  8100.         Creates a logical printer 
  8101.  
  8102. SELECT_PRINTER 
  8103.         Displays the print queue selection dialog 
  8104.  
  8105. OPEN_DOCUMENT 
  8106.         Starts a print job 
  8107.  
  8108. PRINT_SENTENCE 
  8109.         Adds a sentence to a print job 
  8110.  
  8111. SET_COLOR 
  8112.         Sets the color of the body of the document 
  8113.  
  8114. SET_FONT 
  8115.         Sets the font for a section of the document 
  8116.  
  8117. SET_INDENT 
  8118.         Sets the indentation amount 
  8119.  
  8120. SET_MARGIN 
  8121.         Sets the inside margin (used when output is duplex) 
  8122.  
  8123. SET_WORDBREAK 
  8124.         Enables or disables wordbreak 
  8125.  
  8126. SET_LINESPACE 
  8127.         Enables or disables interline spacing 
  8128.  
  8129. SET_HEADING 
  8130.         Sets the running heading 
  8131.  
  8132. SET_FOOTING 
  8133.         Sets the running footing 
  8134.  
  8135. SET_PAGENUMBERS 
  8136.         Enables or disables page numbering 
  8137.  
  8138. NEWLINE 
  8139.         Starts a new line 
  8140.  
  8141. NEWPAGE 
  8142.         Starts a new page 
  8143.  
  8144. CLOSE_DOCUMENT 
  8145.         Completes a print job 
  8146.  
  8147. CANCEL_DOCUMENT 
  8148.         Cancels a print job 
  8149.  
  8150. DESTROY_PRINTER 
  8151.         Destroys a logical printer 
  8152.  
  8153. QUERY_PAGENUMBER 
  8154.         Returns the current page number 
  8155.  
  8156. QUERY_LENGTH 
  8157.         Returns the length, in points, of a string 
  8158.  
  8159.  
  8160. ΓòÉΓòÉΓòÉ 13.16.4. Utility Functions ΓòÉΓòÉΓòÉ
  8161.  
  8162. The utility functions perform common user interface tasks. 
  8163.  
  8164. APLEDIT 'NAME' 
  8165.         Uses Apledit to edit a function or operator 
  8166.  
  8167. APLEXECPGM CMD 
  8168.         Executes an OS/2 command 
  8169.  
  8170. RESPONSEΓò£PROMPT TEXT 
  8171.         Displays prompt TEXT and returns the user's response. 
  8172.  
  8173. SELECTIONΓò£SELECT_1 MATRIX 
  8174.         Prompts the user to select one item from a matrix 
  8175.  
  8176. SELECTIONΓò£SELECT_SOME MATRIX 
  8177.         Prompts the user to make selections from a matrix 
  8178.  
  8179. EDITEDMATRIXΓò£EDIT MATRIX 
  8180.         Allows the user to edit a character matrix 
  8181.  
  8182.  
  8183. ΓòÉΓòÉΓòÉ 13.17. The PMWIN Workspace ΓòÉΓòÉΓòÉ
  8184.  
  8185. This workspace contains variables corresponding to the constants defined in the 
  8186. OS/2 Developer's Toolkit header files. These constants are used by Presentation 
  8187. Manager applications and refer to message identifiers and codes, and OS/2 
  8188. service flags. 
  8189.  
  8190. Variables corresponding to the messages and flags used with the APL2 
  8191. Presentation Manager services are also provided. 
  8192.  
  8193.  
  8194. ΓòÉΓòÉΓòÉ 13.18. The PRINTWS Workspace ΓòÉΓòÉΓòÉ
  8195.  
  8196. The PRINTWS workspace provides a means for printing the contents of the active 
  8197. workspace. It produces a listing of all the variables, functions, and operators 
  8198. in the workspace. 
  8199.  
  8200. The only function in the workspace is called PRINTWS. To use it: 
  8201.  
  8202. )LOAD your workspace
  8203. )PCOPY 2 PRINTWS PRINTWS
  8204. PRINTWS
  8205. You are prompted to select a printer and to set the print job properties. 
  8206.  
  8207. PRINTWS creates and uses an APL print object. Print objects are described in 
  8208. APL2/2 Presentation Manager Services. Cover functions for using print objects 
  8209. are provided in the PMTOOLS workspace described in The PMTOOLS Workspace. 
  8210.  
  8211. o Limitations of PRINTWS 
  8212.  
  8213.  
  8214. ΓòÉΓòÉΓòÉ 13.18.1. Limitations of PRINTWS ΓòÉΓòÉΓòÉ
  8215.  
  8216. The PRINTWS function has the following limitations: 
  8217.  
  8218. o This function does not print objects with names that begin with ╤₧_. It is 
  8219.   implemented this way to prevent conflicts with the names that are used within 
  8220.   PRINTWS. 
  8221.  
  8222. o Output generated by the PRINTWS function does not include a display of its 
  8223.   own code. 
  8224.  
  8225. o PRINTWS requires that the PMTOOLS workspace be installed in library 2. 
  8226.  
  8227.  
  8228. ΓòÉΓòÉΓòÉ 13.19. The SQL Workspace ΓòÉΓòÉΓòÉ
  8229.  
  8230. The SQL workspace enables you to execute SQL statements or retrieve information 
  8231. from AP 127. The following section lists the functions provided with the SQL 
  8232. workspace. For additional information about the SQL workspace, see APL2 
  8233. Programming: Using Structured Query Language. 
  8234.  
  8235. o Functions 
  8236.  
  8237.  
  8238. ΓòÉΓòÉΓòÉ 13.19.1. Functions ΓòÉΓòÉΓòÉ
  8239.  
  8240. SQL Workspace Functions summarizes the SQL workspace functions and the defined 
  8241. operator (UNTIL). It gives their syntax and indicates the equivalent AP 127 
  8242. operations if they exist. 
  8243.  
  8244.  
  8245. ΓòÉΓòÉΓòÉ 13.19.1.1. SQL Workspace Functions - Part 1 ΓòÉΓòÉΓòÉ
  8246.  
  8247.  
  8248. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8249.  
  8250. Function Name and Syntax 
  8251.  
  8252.  
  8253. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8254.  
  8255. AP 127 Operation 
  8256.  
  8257.  
  8258. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8259.  
  8260. CALL name [values] 
  8261.  
  8262.  
  8263. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8264.  
  8265. 'CALL'
  8266.  
  8267.  
  8268. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8269.  
  8270. CLOSE name 
  8271.  
  8272.  
  8273. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8274.  
  8275. 'CLOSE'
  8276.  
  8277.  
  8278. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8279.  
  8280. COMMIT 
  8281.  
  8282.  
  8283. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8284.  
  8285. 'COMMIT'
  8286.  
  8287.  
  8288. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8289.  
  8290. CONNECT 'RESET'Γöédatabase ['SHARE'Γöé'EXCLUSIVE'] 
  8291.  
  8292.  
  8293. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8294.  
  8295. 'CONNECT'
  8296.  
  8297.  
  8298. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8299.  
  8300. f DATE t 
  8301.  
  8302.  
  8303. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8304.  
  8305.  
  8306. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8307.  
  8308. DECLARE name ['HOLD'] 
  8309.  
  8310.  
  8311. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8312.  
  8313. 'DECLARE'
  8314.  
  8315.  
  8316. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8317.  
  8318. DESC name [type] 
  8319.  
  8320.  
  8321. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8322.  
  8323. 'DESCRIBE'
  8324.  
  8325.  
  8326. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8327.  
  8328. EVAL data 
  8329.  
  8330.  
  8331. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8332.  
  8333.  
  8334. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8335.  
  8336. EVALSIM data 
  8337.  
  8338.  
  8339. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8340.  
  8341.  
  8342. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8343.  
  8344. EXEC stmt 
  8345.  
  8346.  
  8347. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8348.  
  8349. 'EXEC'
  8350.  
  8351.  
  8352. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8353.  
  8354. FETCH name [options..] 
  8355.  
  8356.  
  8357. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8358.  
  8359. 'FETCH'
  8360.  
  8361.  
  8362. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8363.  
  8364. GETOPT
  8365.  
  8366.  
  8367. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8368.  
  8369. 'GETOPT'
  8370.  
  8371.  
  8372. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8373.  
  8374. IN 
  8375.  
  8376.  
  8377. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8378.  
  8379. 'IN' 
  8380.  
  8381.  
  8382. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8383.  
  8384. ISOL setting 
  8385.  
  8386.  
  8387. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8388.  
  8389. 'ISOL'
  8390.  
  8391.  
  8392. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8393.  
  8394. MORE... 
  8395.  
  8396.  
  8397. ΓòÉΓòÉΓòÉ 13.19.1.2. SQL Workspace Functions - Part 2 ΓòÉΓòÉΓòÉ
  8398.  
  8399.  
  8400. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8401.  
  8402. Function Name and Syntax 
  8403.  
  8404.  
  8405. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8406.  
  8407. AP 127 Operation 
  8408.  
  8409.  
  8410. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8411.  
  8412. MESSAGE rcode 
  8413.  
  8414.  
  8415. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8416.  
  8417. 'MSG'
  8418.  
  8419.  
  8420. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8421.  
  8422. NAMES 
  8423.  
  8424.  
  8425. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8426.  
  8427. 'NAMES'
  8428.  
  8429.  
  8430. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8431.  
  8432. OFFER
  8433.  
  8434.  
  8435. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8436.  
  8437.  
  8438. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8439.  
  8440. OPEN name [values] 
  8441.  
  8442.  
  8443. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8444.  
  8445. 'OPEN'
  8446.  
  8447.  
  8448. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8449.  
  8450. PREP name stmt 
  8451.  
  8452.  
  8453. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8454.  
  8455. 'PREP'
  8456.  
  8457.  
  8458. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8459.  
  8460. PURGE name 
  8461.  
  8462.  
  8463. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8464.  
  8465. 'PURGE' 
  8466.  
  8467.  
  8468. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8469.  
  8470. QUE stack 
  8471.  
  8472.  
  8473. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8474.  
  8475.  
  8476. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8477.  
  8478. QUERY name [values] 
  8479.  
  8480.  
  8481. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8482.  
  8483.  
  8484. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8485.  
  8486. RESUME stack 
  8487.  
  8488.  
  8489. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8490.  
  8491.  
  8492. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8493.  
  8494. ROLLBACK
  8495.  
  8496.  
  8497. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8498.  
  8499. 'ROLLBACK'
  8500.  
  8501.  
  8502. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8503.  
  8504. SETOPT options.. 
  8505.  
  8506.  
  8507. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8508.  
  8509. 'SETOPT'
  8510.  
  8511.  
  8512. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8513.  
  8514. SHOW result 
  8515.  
  8516.  
  8517. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8518.  
  8519.  
  8520. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8521.  
  8522. SQL stmt [values] 
  8523.  
  8524.  
  8525. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8526.  
  8527.  
  8528. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8529.  
  8530. SQLCA 
  8531.  
  8532.  
  8533. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8534.  
  8535. 'SQLCA' 
  8536.  
  8537.  
  8538. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8539.  
  8540. SQLSTATE 
  8541.  
  8542.  
  8543. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8544.  
  8545. 'SQLSTATE' 
  8546.  
  8547.  
  8548. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8549.  
  8550. MORE... 
  8551.  
  8552.  
  8553. ΓòÉΓòÉΓòÉ 13.19.1.3. SQL Workspace Functions - Part 3 ΓòÉΓòÉΓòÉ
  8554.  
  8555.  
  8556. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8557.  
  8558. Function Name and Syntax 
  8559.  
  8560.  
  8561. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8562.  
  8563. AP 127 Operation 
  8564.  
  8565.  
  8566. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8567.  
  8568. STATE name 
  8569.  
  8570.  
  8571. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8572.  
  8573. 'STATE'
  8574.  
  8575.  
  8576. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8577.  
  8578. STMT name 
  8579.  
  8580.  
  8581. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8582.  
  8583. 'STMT'
  8584.  
  8585.  
  8586. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8587.  
  8588. f TIME t 
  8589.  
  8590.  
  8591. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8592.  
  8593.  
  8594. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8595.  
  8596. TIMESTAMP t 
  8597.  
  8598.  
  8599. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8600.  
  8601.  
  8602. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8603.  
  8604. (F UNTIL) stack 
  8605.  
  8606.  
  8607. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  8608.  
  8609.  
  8610. ΓòÉΓòÉΓòÉ 13.20. The TIME Workspace ΓòÉΓòÉΓòÉ
  8611.  
  8612. The TIME workspace contains the TIME function, to assist with the performance 
  8613. monitoring and tuning of APL2 code. 
  8614.  
  8615. The performance monitoring facility provides the capability to measure a 
  8616. running application and determine the CPU time used by each defined program, 
  8617. each line within each defined program, or both. 
  8618.  
  8619. The facility works by associating with each line of each defined program, a 
  8620. pair of counters to record the number of times the line is executed and the 
  8621. total CPU time consumed by the line. 
  8622.  
  8623. Typically, timing information can be obtained for an application as follows: 
  8624.  
  8625.     )LOAD workspace
  8626.     )PCOPY 1 TIME TIME ╤ä To gain access to the facility
  8627.     TIME 0             ╤ä To enable and zero counters
  8628.     ╤ä (Run application here)
  8629.     TIME 1             ╤ä To see times for program run
  8630.     ╤ä (Analyze timing information here)
  8631.     TIME 2             ╤ä To see times for each line
  8632.     ╤ä (Analyze timing information here)
  8633.     )CLEAR             ╤ä When time analysis is complete
  8634.  
  8635. Use of the timing facility requires space in the workspace for the counters and 
  8636. also increases running time by some small amount. Thus, in general you should 
  8637. not )SAVE after doing a time analysis. 
  8638.  
  8639. ZΓò£TIME N
  8640.  
  8641. TIME 0       Enable timing and create counters for all lines in all unlocked 
  8642.              programs. The counters are set to zero. 
  8643.  
  8644. TIME 1       Fetch times for all programs for which timing has been gathered 
  8645.              and return a matrix containing for each function or operator 
  8646.              actually executed, the number of times the function or operator 
  8647.              was executed, the total CPU time used by the function or operator, 
  8648.              the percentage of the CPU time used by the function or operator, 
  8649.              and the name of the program. If column headings are desired, the 
  8650.              following may be used: 
  8651.  
  8652.                               HD1Γò£'COUNT' 'TIME' '%' 'PROGRAM'
  8653.                               HD1,[╨áIO] TIME 1
  8654.  
  8655.              Three heading vectors-HD1, HD2, and HD3-are already defined in the 
  8656.              workspace, with the values shown here. 
  8657.  
  8658.              The figure given for the number of times each program is executed 
  8659.              is based on the assumption that this count is the same as that for 
  8660.              the first executable (noncomment) line of the program. 
  8661.  
  8662. TIME 2       Fetch times for all lines of all programs for which timing has 
  8663.              been accumulated. The result is a matrix of the same format as 
  8664.              TIME1 except the line from the function or operator is also 
  8665.              listed. If column headings are desired, the following may be used: 
  8666.  
  8667.                               HD2Γò£'COUNT' 'TIME' '%' 'PROGRAM' 'STMT'
  8668.                               HD2,[╨áIO] TIME 2
  8669.  
  8670. Each of the above uses of TIME also accepts an optional left argument that must 
  8671. be a character list of names. If provided, the left argument limits the scope 
  8672. of TIME to the programs named in the left argument. 
  8673.  
  8674. Additional uses of the TIME function are: 
  8675.  
  8676. TIME 3       Fetch times for all lines of all programs even if no timing has 
  8677.              been accumulated. The result is a matrix of the same columnar 
  8678.              format as TIME 2 and is sequenced by line within each function or 
  8679.              operator. A left argument can be used to obtain the timing for the 
  8680.              specified programs. If column headings are desired, the following 
  8681.              can be used: 
  8682.  
  8683.                               HD3Γò£'COUNT' 'TIME' '%' 'PROGRAM' 'STMT'
  8684.                               HD3,[╨áIO] TIME 3
  8685.  
  8686. TIME ┬ñ1      Enable timing. If timing has been disabled, timing is resumed. A 
  8687.              left argument is not allowed for TIME ┬ñ1. 
  8688.  
  8689. TIME ┬ñ2      Disable timing. Stops the accumulation of timing data. A left 
  8690.              argument is not allowed for TIME ┬ñ2. 
  8691.  
  8692. TIME ┬ñ3      Deletes the space used by the counters. A name list left argument 
  8693.              is allowed and can be used to delete the timing data for selected 
  8694.              functions and operators. 
  8695.  
  8696. Use of the timing facility increases space utilization and execution time. 
  8697. Reported timings are approximate and should only be used for relative 
  8698. comparisons, not absolute times. 
  8699.  
  8700. When a program is erased, its counters are deleted. When a program is created 
  8701. or changed, its counters are not preserved. 
  8702.  
  8703. o Performance Analysis Using the TIME Function 
  8704.  
  8705.  
  8706. ΓòÉΓòÉΓòÉ 13.20.1. Performance Analysis Using the TIME Function ΓòÉΓòÉΓòÉ
  8707.  
  8708. The theory behind performance tuning through the TIME facility is that very 
  8709. often a small amount of code within an application consumes the majority of CPU 
  8710. cycles. By quickly identifying these "hot spots", the programmer can focus his 
  8711. attention on optimizations that provide the greatest effect in reducing overall 
  8712. application CPU time. The following APL2/2 session demonstrates the use of 
  8713. TIME: 
  8714.  
  8715.       )LOAD COSTEST
  8716. SAVED 1993-09-19 14.13.20 COSTEST
  8717.       )PCOPY 1 TIME TIME   ╤ä Fetch TIME function
  8718. SAVED 1993-12-02 12.00.00 TIME
  8719.       TIME 0               ╤ä Zero time counters
  8720.       ESTIMATE 10          ╤ä Run the application
  8721. COMPLETED... SEE ΓûáCOST_REPORTΓûá
  8722.       ╨áΓò£TΓò£TIME 1           ╤ä Fetch time summary
  8723. 500 31.19    72.83469164 PRODCOST
  8724. 500   7.4    17.28043341 CHARGE
  8725.  10 3.627    8.469747566 CALC
  8726. 500 0.208   0.4857202905 EVAL
  8727.  10 0.196    0.457697966 PC
  8728.  10 0.103   0.2405249515 STORE
  8729.   1  0.05   0.1167596852 ESTIMATE
  8730.   1 0.044    0.102748523 TIME
  8731.  10 0.004 0.009340774817 FINDMAX
  8732.  10 0.001 0.002335193704 GETNEXT
  8733.   1     0              0 CLOSE
  8734.   1     0              0 OPEN
  8735.       +/T[;2]              ╤ä Compute total CPU time
  8736. 42.823
  8737.       'PRODCOST' TIME 2    ╤ä Fetch time detail
  8738. 500 31.028  99.48060276 PRODCOST[2] PCOSTΓò£SCHG┬░.╤ù╤îWEEKS
  8739. 500  0.162 0.5193972427 PRODCOST[1] SCHGΓò£CHARGE N
  8740.  
  8741. The TIME 1 report identifies the function PRODCOST as the major CPU consumer, 
  8742. attributable to about 73% of the total CPU time (31.19 of the total CPU 42.823 
  8743. seconds for this small sample run). Further analysis of the PRODCOST function 
  8744. with the TIME 2 report shows that the mathematical calculation performed in 
  8745. line 2 is the best target for potential performance improvement. 
  8746.  
  8747.  
  8748. ΓòÉΓòÉΓòÉ 13.21. The UTILITY Workspace ΓòÉΓòÉΓòÉ
  8749.  
  8750. This section describes the UTILITY workspace. 
  8751.  
  8752. o Introduction 
  8753. o GPDATACV: Converting Between External and Internal Representations 
  8754. o GPMISC: Miscellaneous Utility Functions 
  8755. o GPSTRIP: Removing Comments 
  8756. o GPSVP: Controlling Communication through SVP 
  8757. o GPTEXT: Manipulating Text 
  8758. o GPTRACE: Setting and Removing Trace and Stop Vectors 
  8759. o GPXLATE: Translating from One Character Representation to Another 
  8760.  
  8761.  
  8762. ΓòÉΓòÉΓòÉ 13.21.1. Introduction ΓòÉΓòÉΓòÉ
  8763.  
  8764. The UTILITY workspace is made up of defined functions organized into groups of 
  8765. functions. The groups are listed in the next section and described in the 
  8766. sections that follow. 
  8767.  
  8768. The two major ways in which you are likely to find the UTILITY workspace useful 
  8769. are: 
  8770.  
  8771. o Functional 
  8772. o Instructional 
  8773.  
  8774. The functional use is relatively straightforward: 
  8775.  
  8776. o Copy the objects you need from the UTILITY workspace into the active 
  8777.   workspace 
  8778. o Use the UTILITY functions as "pseudo-primitives" in your own defined 
  8779.   functions. 
  8780.  
  8781. The instructional use may not be as obvious but may be even more important. 
  8782. Instructionally, you can use the UTILITY workspace to: 
  8783.  
  8784. o Acquire familiarity with APL2 by experimenting with the functions in the 
  8785.   UTILITY workspace, listing and reading them, trying to deduce what each 
  8786.   statement does and why you might choose that particular way to do it. 
  8787.  
  8788. o Develop your APL2 programming skills by modifying the functions to improve 
  8789.   their efficiency or to add features you need. 
  8790.  
  8791. o Extend your programming skills by adding complementary utility functions that 
  8792.   you find useful. 
  8793.  
  8794. This workspace is of most use to you if you try to use it for both functional 
  8795. and instructional purposes. 
  8796.  
  8797.  
  8798. ΓòÉΓòÉΓòÉ 13.21.2. GPDATACV: Converting Between External and Internal Representations ΓòÉΓòÉΓòÉ
  8799.  
  8800. o LI/LO - Boolean (Logical) 
  8801. o II/IO - System/370 Integer 
  8802. o PCII/PCIO - IBM PC Integer 
  8803. o FI/FO - System/370 Floating Point 
  8804. o IEEEFI/IEEEFO - IEEE Floating Point 
  8805. o PCFI/PCFO - IBM PC Floating Point 
  8806. o PDI/PDO - Packed Decimal 
  8807.  
  8808.  
  8809. ΓòÉΓòÉΓòÉ 13.21.2.1. LI/LO - Boolean (Logical) ΓòÉΓòÉΓòÉ
  8810.  
  8811. ZΓò£LI R      ╤ä Logical In
  8812.  
  8813. R is a simple character array whose last axis contains IBM PC or System/370 
  8814. logical data; that is, a string of bits. 
  8815.  
  8816. Z is a numeric array consisting of zeros and ones representing the logical data 
  8817. in R. The rank of Z is the same as the rank of R, but the last axis is 8 times 
  8818. as long as the last axis of R. A scalar value for R produces an 8-element 
  8819. vector. 
  8820.  
  8821. ╤åZ Γò£Γòò (┬ñ1Γòƒ╤åR),8╤ù┬ñ1Γò₧1,╤åR
  8822.  
  8823. ZΓò£LO R      ╤ä Logical Out
  8824.  
  8825. R is a simple numeric array consisting of only zeros and ones. The length of 
  8826. its last axis must be a multiple of 8. 
  8827.  
  8828. Z is a character array whose last axis contains the IBM PC or System/370 
  8829. representation of the logical data in the last axis of R. The rank of Z is the 
  8830. same as the rank of R, but the length of the last axis of Z is one-eighth of 
  8831. the last axis of R. 
  8832.  
  8833. ╤åZ Γò£Γòò (┬ñ1Γòƒ╤åR),(┬ñ1Γò₧╤åR)╨Ä8
  8834.  
  8835.  
  8836. ΓòÉΓòÉΓòÉ 13.21.2.2. II/IO - System/370 Integer ΓòÉΓòÉΓòÉ
  8837.  
  8838. ZΓò£II R      ╤ä Integers In
  8839.  
  8840. R is a simple character array whose last axis must have a length of between 1 
  8841. and 7 inclusive, and which contains the System/370 binary representations of 
  8842. integers. 
  8843.  
  8844. Z is an array of integers representing the binary numbers in R. The rank of Z 
  8845. is one less than the rank of R. 
  8846.  
  8847. ╤åZ Γò£Γòò ┬ñ1Γòƒ╤åR
  8848.  
  8849. ZΓò£L IO R     ╤ä Integers Out
  8850.  
  8851. R is a simple array of integers. L is an integer scalar not greater than 7. It 
  8852. gives the number of bytes in which each integer is to be represented. L must be 
  8853. large enough to represent the largest magnitude of the integers in R. 
  8854.  
  8855. Z is a character array whose last axis contains the System/370 binary 
  8856. representation of the integers in R. The rank of Z is one greater than the rank 
  8857. of R. 
  8858.  
  8859. ╤åZ Γò£Γòò (╤åR),L
  8860.  
  8861.  
  8862. ΓòÉΓòÉΓòÉ 13.21.2.3. PCII/PCIO - IBM PC Integer ΓòÉΓòÉΓòÉ
  8863.  
  8864. ZΓò£PCII R     ╤ä PC Integers In
  8865.  
  8866. R is a simple character array whose last axis must have a length of 1, 2 or 4, 
  8867. and which contains the IBM PC (reversed) binary representations of integers. 
  8868.  
  8869. Z is an array of integers representing the binary numbers in R. The rank of Z 
  8870. is one less than the rank of R. 
  8871.  
  8872. ╤åZ Γò£Γòò ┬ñ1Γòƒ╤åR
  8873.  
  8874. ZΓò£L PCIO R    ╤ä PC Integers Out
  8875.  
  8876. R is a simple array of integers. L is an integer scalar with a value of 1, 2 or 
  8877. 4, and gives the number of bytes in which each integer is to be represented. L 
  8878. must be large enough to represent the largest magnitude of the integers in R. 
  8879.  
  8880. Z is a character array whose last axis contains the IBM PC (reversed) binary 
  8881. representation of the integers in R. The rank of Z is one greater than the rank 
  8882. of R. 
  8883.  
  8884. ╤åZ Γò£Γòò (╤åR),L
  8885.  
  8886.  
  8887. ΓòÉΓòÉΓòÉ 13.21.2.4. FI/FO - System/370 Floating Point ΓòÉΓòÉΓòÉ
  8888.  
  8889. ZΓò£FI R      ╤ä Floating In
  8890.  
  8891. R is a simple character array, the last axis of which must have a length of 4 
  8892. or 8. The last axis thus represents either single- or double-precision 
  8893. System/370 floating-point numbers. 
  8894.  
  8895. Z is an array of numbers equivalent to the floating-point representations in R. 
  8896. The rank of Z is one less than the rank of R. 
  8897.  
  8898. ╤åZ Γò£Γòò ┬ñ1Γòƒ╤åR
  8899.  
  8900. ZΓò£FO R      ╤ä Floating Out
  8901.  
  8902. R is a simple numeric array. Z is a character array whose last axis has length 
  8903. 8, and which contains the System/370 double-precision floating-point 
  8904. representations of the numbers in R. The rank of Z is one greater than the rank 
  8905. of R. If single precision is required, then drop the last four columns of the 
  8906. result. 
  8907.  
  8908. ╤åZ Γò£Γòò (╤åR),8
  8909.  
  8910.  
  8911. ΓòÉΓòÉΓòÉ 13.21.2.5. IEEEFI/IEEEFO - IEEE Floating Point ΓòÉΓòÉΓòÉ
  8912.  
  8913. ZΓò£IEEEFI R    ╤ä IEEE Floating In
  8914.  
  8915. R is a simple character array, the last axis of which must have a length of 4 
  8916. or 8. The last axis thus represents either single- or double-precision IEEE 
  8917. floating-point numbers. 
  8918.  
  8919. Z is an array of numbers equivalent to the floating-point representations in R. 
  8920. The rank of Z is one less than the rank of R. 
  8921.  
  8922. ╤åZ Γò£Γòò ┬ñ1Γòƒ╤åR
  8923.  
  8924. ZΓò£L IEEEFO R   ╤ä IEEE Floating Out
  8925.  
  8926. R is a simple numeric array. L is an integer scalar with a value of 4 or 8. A 
  8927. value of 4 for L gives single-precision floating point representation, and a 
  8928. value of 8 gives double precision. Z is a character array whose last axis has 
  8929. length L, and which contains the IEEE single or double-precision floating-point 
  8930. representations of the numbers in R. The rank of Z is one greater than the rank 
  8931. of R. 
  8932.  
  8933. ╤åZ Γò£Γòò (╤åR),L
  8934.  
  8935.  
  8936. ΓòÉΓòÉΓòÉ 13.21.2.6. PCFI/PCFO - IBM PC Floating Point ΓòÉΓòÉΓòÉ
  8937.  
  8938. ZΓò£PCFI R     ╤ä PC Floating In
  8939.  
  8940. R is a simple character array, the last axis of which must have a length of 4 
  8941. or 8. The last axis thus represents either single- or double- precision IBM PC 
  8942. (reversed) IEEE floating-point numbers. 
  8943.  
  8944. Z is an array of numbers equivalent to the floating-point representations in R. 
  8945. The rank of Z is one less than the rank of R. 
  8946.  
  8947. ╤åZ Γò£Γòò ┬ñ1Γòƒ╤åR
  8948.  
  8949. ZΓò£L PCFO R    ╤ä PC Floating Out
  8950.  
  8951. R is a simple numeric array. L is an integer scalar with a value of 4 or 8. A 
  8952. value of 4 for L gives single precision floating point representation, and a 
  8953. value of 8 gives double precision. Z is a character array whose last axis has 
  8954. length L, and which contains the IBM PC (reversed) IEEE single- or 
  8955. double-precision floating-point representations of the numbers in R. The rank 
  8956. of Z is one greater than the rank of R. 
  8957.  
  8958. ╤åZ Γò£Γòò (╤åR),L
  8959.  
  8960.  
  8961. ΓòÉΓòÉΓòÉ 13.21.2.7. PDI/PDO - Packed Decimal ΓòÉΓòÉΓòÉ
  8962.  
  8963. ZΓò£PDI R      ╤ä Packed Decimal In
  8964.  
  8965. R is a simple character array whose last axis must have a length of between 1 
  8966. and 16 inclusive, and which contains valid System/370 packed decimal 
  8967. representations of numbers. 
  8968.  
  8969. Z is an array of integers representing the packed decimal numbers in R. The 
  8970. rank of Z is one less than the rank of R. 
  8971.  
  8972. ╤åZ Γò£Γòò ┬ñ1Γòƒ╤åR
  8973.  
  8974. Note that if the length of the packed decimal number is greater than 9 bytes, a 
  8975. loss of precision can result. 
  8976.  
  8977. ZΓò£L PDO R     ╤ä Packed Decimal Out
  8978.  
  8979. R is a simple array of integers. L is an integer scalar not greater than 16. It 
  8980. gives the number of bytes in which each integer of R is to be represented. L 
  8981. must be large enough to represent the largest magnitude of the integers in R. 
  8982.  
  8983. Z is a character array whose last axis contains the System/370 packed decimal 
  8984. representations of the integers in R. The rank of Z is one greater than the 
  8985. rank of R. 
  8986.  
  8987. ╤åZ Γò£Γòò (╤åR),L
  8988.  
  8989.  
  8990. ΓòÉΓòÉΓòÉ 13.21.3. GPMISC: Miscellaneous Utility Functions ΓòÉΓòÉΓòÉ
  8991.  
  8992. o ANNOTATE - Add comments to lines 
  8993. o ASSIGN - Specify values for a set of names 
  8994. o CASE - Gives case attribute of active workspace 
  8995. o CODECOUNT - Count lines in all workspace programs 
  8996. o CONCEAL - Make a function nonsuspendable 
  8997. o DATETIME - Format date and time 
  8998. o EXPAND - Function version of \ 
  8999. o FNHEADS - List headers for a set of functions 
  9000. o FRAME - Put a border around a character matrix 
  9001. o HEXDUMP - Produce character+hex display of data 
  9002. o LINECOUNT - Count lines in a list of programs 
  9003. o LIST - Convert an arbitrary array to a vector 
  9004. o MASKCONV - Splits numbers into n-bit fields 
  9005. o MESH - Mesh two or more vectors as prescribed by a mask 
  9006. o NAMEREFS - Find all names in a defined program 
  9007. o NAMES - Find all names in a string 
  9008. o NHEAD - Produce character representations of index vectors 
  9009. o REPLICATE - Function version of / 
  9010. o REVEAL - Make a function suspendable 
  9011. o TYPE - Determine if array is alphabetic or numeric 
  9012. o UNIQUE - Remove duplicates 
  9013.  
  9014.  
  9015. ΓòÉΓòÉΓòÉ 13.21.3.1. ANNOTATE - Add comments to lines ΓòÉΓòÉΓòÉ
  9016.  
  9017. ZΓò£L ANNOTATE R
  9018.  
  9019. R is a simple character matrix and L is a numeric scalar. Z is R with rows 
  9020. padded or truncated to length L and with comments interactively appended to 
  9021. each row. 
  9022.  
  9023.  
  9024. ΓòÉΓòÉΓòÉ 13.21.3.2. ASSIGN - Specify values for a set of names ΓòÉΓòÉΓòÉ
  9025.  
  9026. L ASSIGN R
  9027.  
  9028. L is a character matrix of names. R is a character matrix of valid APL2 
  9029. expressions. Each row of L is evaluated and its value given the name in the 
  9030. corresponding row of R. 
  9031.  
  9032.  
  9033. ΓòÉΓòÉΓòÉ 13.21.3.3. CASE - Gives case attribute of active workspace ΓòÉΓòÉΓòÉ
  9034.  
  9035. ZΓò£CASE
  9036.  
  9037. Z is the case attribute of the active workspace. In APL2/2, Z always has a 
  9038. value of 2 to indicate that lowercase characters are used in object names. 
  9039.  
  9040.  
  9041. ΓòÉΓòÉΓòÉ 13.21.3.4. CODECOUNT - Count lines in all workspace programs ΓòÉΓòÉΓòÉ
  9042.  
  9043. ZΓò£CODECOUNT
  9044.  
  9045. This function counts the function and operator lines in the workspace, and 
  9046. returns a 2-element numeric vector. Z[1] is the total number of lines in the 
  9047. workspace that contain something other than a comment. Z[2] is the total number 
  9048. of lines that consist only of a comment. CODECOUNT does not count its own 
  9049. lines. See also LINECOUNT in LINECOUNT - Count lines in a list of programs. 
  9050.  
  9051.  
  9052. ΓòÉΓòÉΓòÉ 13.21.3.5. CONCEAL - Make a function nonsuspendable ΓòÉΓòÉΓòÉ
  9053.  
  9054. CONCEAL R
  9055.  
  9056. Make the function named by R nonsuspendable. 
  9057.  
  9058.  
  9059. ΓòÉΓòÉΓòÉ 13.21.3.6. DATETIME - Format date and time ΓòÉΓòÉΓòÉ
  9060.  
  9061. ZΓò£DATETIME
  9062.  
  9063. Z is the date and time in the form of mm/dd/yy    hh:mm:ss. 
  9064.  
  9065.       DATETIME
  9066. 06/27/85    10:00:42
  9067.  
  9068.  
  9069. ΓòÉΓòÉΓòÉ 13.21.3.7. EXPAND - Function version of \ ΓòÉΓòÉΓòÉ
  9070.  
  9071. ZΓò£L EXPAND R
  9072.  
  9073. R is any array. L is a Boolean vector. Z is L\R. See Miscellaneous Functions 
  9074. for a discussion of this function. 
  9075.  
  9076.  
  9077. ΓòÉΓòÉΓòÉ 13.21.3.8. FNHEADS - List headers for a set of functions ΓòÉΓòÉΓòÉ
  9078.  
  9079. ZΓò£FNHEADS R    ╤ä FuNction HEADerS
  9080.  
  9081. R is a character matrix of function or operator names. Z is a character matrix 
  9082. of corresponding function and operator headers, exclusive of explicit local 
  9083. variables. 
  9084.  
  9085.  
  9086. ΓòÉΓòÉΓòÉ 13.21.3.9. FRAME - Put a border around a character matrix ΓòÉΓòÉΓòÉ
  9087.  
  9088. ZΓò£FRAME R
  9089.  
  9090. R is a simple character scalar, vector, or matrix. Z is R bordered by straight 
  9091. lines. 
  9092.  
  9093.  
  9094. ΓòÉΓòÉΓòÉ 13.21.3.10. HEXDUMP - Produce character+hex display of data ΓòÉΓòÉΓòÉ
  9095.  
  9096. ZΓò£HEXDUMP R
  9097.  
  9098. R is a simple character array. Z is a four row matrix with one column for each 
  9099. element of ,R. The first row of Z is R; the second is ╨áAF ,R; the third row 
  9100. contains the hexadecimal representations of the numbers in the second row; and 
  9101. the fourth row contains characters that mark off character positions by fives. 
  9102.  
  9103.  
  9104. ΓòÉΓòÉΓòÉ 13.21.3.11. LINECOUNT - Count lines in a list of programs ΓòÉΓòÉΓòÉ
  9105.  
  9106. ZΓò£LINECOUNT R
  9107.  
  9108. R is a character scalar, simple vector or matrix, or a vector or vectors. 
  9109. LINECOUNT counts the lines of the functions and operators named in R and 
  9110. returns a 2-element numeric vector. Z[1] is the number of lines containing 
  9111. something other than a comment; Z[2] is the total number of lines that consist 
  9112. only of a comment. This function does not count its own lines. See also 
  9113. CODECOUNT in CODECOUNT - Count lines in all workspace programs. 
  9114.  
  9115.  
  9116. ΓòÉΓòÉΓòÉ 13.21.3.12. LIST - Convert an arbitrary array to a vector ΓòÉΓòÉΓòÉ
  9117.  
  9118. ZΓò£LIST R
  9119.  
  9120. This function creates a vector or scalar out of R. R may be any array. If R is 
  9121. a simple scalar, then Z is ,R. If R is a simple vector, then Z is ,╤éR. If R is 
  9122. a nested scalar or vector, then Z is R. Otherwise, Z is R enclosed along all 
  9123. axes but the first, which forms a nested vector. 
  9124.  
  9125.  
  9126. ΓòÉΓòÉΓòÉ 13.21.3.13. MASKCONV - Splits numbers into n-bit fields ΓòÉΓòÉΓòÉ
  9127.  
  9128. ZΓò£L MASKCONV R  ╤ä MASK CONVert
  9129.  
  9130. MASKCONV encodes the number (or numbers) R to the base 2*L. It is primarily 
  9131. useful in analyzing sections of storage defined by fields of varying lengths 
  9132. from one bit to a full word. 
  9133.  
  9134.       1 2 1 4 24 MASKCONV ┬ñ1+2*32
  9135. 1 3 1 15 16777215
  9136.  
  9137.  
  9138. ΓòÉΓòÉΓòÉ 13.21.3.14. MESH - Mesh two or more vectors as prescribed by a mask ΓòÉΓòÉΓòÉ
  9139.  
  9140. ZΓò£L MESH R
  9141.  
  9142. L is a mask and R is a concatenation of the vectors to be meshed. If the mask L 
  9143. consists of 0s and 1s, the elements of R are placed, in order of occurrence, in 
  9144. the positions of Z corresponding to 0s; after these have been filled, the 
  9145. remaining elements are placed in the positions corresponding to 1s. If R is a 
  9146. catenation of vectors of lengths equal to the number of 0s and the numbers of 
  9147. 1s respectively, the result is to "mesh" them. This can be generalized to any 
  9148. number of vectors by providing masks with elements of 0, 1, 2, ... 
  9149.  
  9150.                                         00122233333333'
  9151.                                         ΓòƒΓòƒΓòƒΓòƒΓòƒΓòƒΓòƒΓòƒΓòƒΓòƒΓòƒΓòƒΓòƒΓòƒ
  9152.       0 2 2 1 3 3 3 3 3 2 3 0 3 3 MESH 'HE IS WORDSMAN'
  9153. HIS WORDS MEAN
  9154. Γò₧Γò₧Γò₧Γò₧Γò₧Γò₧Γò₧Γò₧Γò₧Γò₧Γò₧Γò₧Γò₧Γò₧
  9155. 02213333323033
  9156.  
  9157. In the example above, 0 selects the first two characters ('HE') and puts them 
  9158. in the first and twelfth positions of the result; 1 puts a blank in the fourth 
  9159. position; 2 puts 'IS ' in positions 2, 3, 10; and 3 puts the remainder. 
  9160.  
  9161.  
  9162. ΓòÉΓòÉΓòÉ 13.21.3.15. NAMEREFS - Find all names in a defined program ΓòÉΓòÉΓòÉ
  9163.  
  9164. ZΓò£NAMEREFS R
  9165.  
  9166. R is the name of a function or operator. Z is a character matrix containing a 
  9167. list of all the names that occur in R. 
  9168.  
  9169.  
  9170. ΓòÉΓòÉΓòÉ 13.21.3.16. NAMES - Find all names in a string ΓòÉΓòÉΓòÉ
  9171.  
  9172. ZΓò£NAMES R
  9173.  
  9174. R is a character vector. Z is a matrix of all the names in R. 
  9175.  
  9176.  
  9177. ΓòÉΓòÉΓòÉ 13.21.3.17. NHEAD - Produce character representations of index vectors ΓòÉΓòÉΓòÉ
  9178.  
  9179. ZΓò£L NHEAD R    ╤ä Numeric HEADers
  9180.  
  9181. L and R are integers. Z is a character array giving ╤îR in column form if L is 0 
  9182. and row form if it is not. 
  9183.  
  9184.       0 NHEAD 5
  9185. 1
  9186. 2
  9187. 3
  9188. 4
  9189. 5
  9190.       1 NHEAD 5
  9191. 12345
  9192.       1 NHEAD 40
  9193.          1111111111222222222233333333334
  9194. 1234567890123456789012345678901234567890
  9195.  
  9196.  
  9197. ΓòÉΓòÉΓòÉ 13.21.3.18. REPLICATE - Function version of / ΓòÉΓòÉΓòÉ
  9198.  
  9199. ZΓò£L REPLICATE R
  9200.  
  9201. R is any array. L is a vector of integers. Z is L/R. See Miscellaneous 
  9202. Functions for a discussion of this function. 
  9203.  
  9204.  
  9205. ΓòÉΓòÉΓòÉ 13.21.3.19. REVEAL - Make a function suspendable ΓòÉΓòÉΓòÉ
  9206.  
  9207. REVEAL R
  9208.  
  9209. If possible, make the function named by R suspendable. 
  9210.  
  9211.  
  9212. ΓòÉΓòÉΓòÉ 13.21.3.20. TYPE - Determine if array is alphabetic or numeric ΓòÉΓòÉΓòÉ
  9213.  
  9214. ZΓò£TYPE R
  9215.  
  9216. Z is a scalar zero if R is numeric, and a scalar blank if it is character. This 
  9217. function is compatible with a VS APL library function of the same name. It is 
  9218. not meant to be applied to mixed or nested arguments. 
  9219.  
  9220.  
  9221. ΓòÉΓòÉΓòÉ 13.21.3.21. UNIQUE - Remove duplicates ΓòÉΓòÉΓòÉ
  9222.  
  9223. ZΓò£UNIQUE R
  9224.  
  9225. R is a vector. Z is a vector containing the elements of R with duplicates 
  9226. eliminated. 
  9227.  
  9228.       UNIQUE 'THE ANTS WERE HERE'
  9229. THE ANSWR
  9230.       UNIQUE 'GUFFAW' 17 (╤î4) 'GUFFAW'
  9231.  GUFFAW 17  1 2 3 4
  9232.  
  9233.  
  9234. ΓòÉΓòÉΓòÉ 13.21.4. GPSTRIP: Removing Comments ΓòÉΓòÉΓòÉ
  9235.  
  9236. DECOMMENT
  9237.  
  9238. This function removes comment lines from all unlocked functions and operators 
  9239. in the active workspace. Running decommented functions requires less storage. 
  9240. When using this function, you should keep a backup copy of the workspace. 
  9241.  
  9242. STRIP R
  9243.  
  9244. STRIP removes comments from all unlocked functions and operators named in R. R 
  9245. is a simple character matrix, a nested vector of names, or a simple string of 
  9246. names separated by blanks. 
  9247.  
  9248. ZΓò£L WORDS R
  9249.  
  9250. WORDS is a function to split a character vector into nested pieces, and is 
  9251. equivalent to the APL2/370 external function DAN (Delete And Nest). R is a 
  9252. character vector. L is a scalar or vector of delimiter characters. Z is a 
  9253. character vector, each of whose elements is a vector of the elements of R lying 
  9254. between occurrences of the delimiters L in R. Consecutive occurrences of 
  9255. delimiters in R are ignored. 
  9256.  
  9257. See WORDS: Extracting Words from Character Vectors for an example using WORDS. 
  9258.  
  9259.  
  9260. ΓòÉΓòÉΓòÉ 13.21.4.1. WORDS: Extracting Words from Character Vectors ΓòÉΓòÉΓòÉ
  9261.  
  9262.  
  9263. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  9264.  
  9265.    ZΓò£'And what exactly ARE the commercial '
  9266.    ZΓò£Z,'possibilities of ovine aviation?'
  9267.    ╤åZ
  9268. 68
  9269.    ZΓò£' ' WORDS Z
  9270.    ╤åZ
  9271. 10
  9272.    ╤âZ
  9273. And
  9274. what
  9275. exactly
  9276. ARE
  9277. the
  9278. commercial
  9279. possibilities
  9280. of
  9281. ovine
  9282. aviation?
  9283.    ╤åΓûáZ
  9284.  3  4  7  3  3  10  13  2  5  9
  9285.  
  9286.  
  9287. ΓòÉΓòÉΓòÉ 13.21.5. GPSVP: Controlling Communication through SVP ΓòÉΓòÉΓòÉ
  9288.  
  9289. APSERVER R
  9290.  
  9291. APSERVER is the general AP server for implementing auxiliary processors using a 
  9292. client-server protocol over a single shared variable interface. For more 
  9293. information about APSERVER, see Writing Auxiliary Processors Using APSERVER. 
  9294.  
  9295. ZΓò£L ID R
  9296.  
  9297. Convert enclosed character processor IDs to large integers and vice versa. 
  9298. Typically used with the SVP profile (apl2svp.prf) in support of cross-system 
  9299. SVP shares for cooperative processing. 
  9300.  
  9301. ZΓò£L SVOFFER R
  9302.  
  9303. Offer shared variables, named in right argument, to SVP processors identified 
  9304. by numbers in the left argument. Returns the final degree of coupling for each 
  9305. shared variable. The function delays up to 15 seconds for shares to be accepted 
  9306. by the partner. It sets standard access control to inhibit a double set or use. 
  9307.  
  9308. R is a character scalar, vector, matrix, or vector of vectors containing the 
  9309. name or names of the shared variables to be offered to an auxiliary processor. 
  9310. Surrogate names for shared variables can also be used. L is a numeric scalar or 
  9311. vector containing the processor ID (the number) of the AP. Z is the degree of 
  9312. coupling for the shared variable; a 2 indicates that the corresponding variable 
  9313. is fully shared with the AP. 
  9314.  
  9315.       211 SVOFFER 'S1' 'S2'
  9316. 2 2
  9317.  
  9318. ZΓò£L SVOPAIR R
  9319.  
  9320. Offer shared variables, named in right argument, to SVP processors identified 
  9321. by numbers in the left argument. This function is used for auxiliary processors 
  9322. that support a two-variable interface, where the control variable begins with 
  9323. "C" or "CTL," and the data variable begins with "D" or "DAT" (that is, AP 124, 
  9324. AP 210). 
  9325.  
  9326. ZΓò£L ΓòóSVO R
  9327.  
  9328. ╨áSVO extension to support enclosed character vectors as processor IDs. 
  9329. Typically used with the SVP profile (apl2svp.prf) in support of cross-system 
  9330. SVP shares for cooperative processing. 
  9331.  
  9332. ZΓò£L ΓòóSVQ R
  9333.  
  9334. ╨áSVQ extension to support enclosed character vectors as processor IDs. 
  9335. Typically used with the SVP profile (apl2svp.prf) in support of cross-system 
  9336. SVP shares for cooperative processing. 
  9337.  
  9338.  
  9339. ΓòÉΓòÉΓòÉ 13.21.6. GPTEXT: Manipulating Text ΓòÉΓòÉΓòÉ
  9340.  
  9341. Note:  Many "text" functions also work on other kinds of data. 
  9342.  
  9343. o DOUBLE - Replace selected characters with pairs 
  9344. o FIND - Search for text in all workspace programs 
  9345. o GATHER - Collect parsed and delimited fields 
  9346. o GVCAT - Catenate rows to arrays of any rank 
  9347. o HCAT - Catenate matrixes by columns 
  9348. o INBLANKS - Separate characters by blanks 
  9349. o LADJ - Left adjust 
  9350. o LINEFOLD - Fold and indent line as specified 
  9351. o MAT - Make a matrix out of any array 
  9352. o MATFOLD - Fold and indent matrix lines as specified 
  9353. o NOQUOTES - Remove quoted substrings 
  9354. o OBLANKS - Remove outer blanks 
  9355. o QREPLACE - Replace ? occurrences by character strings 
  9356. o RADJ - Right adjust 
  9357. o RCNUM - Produce numerical headings for rows and columns 
  9358. o REPLACE - Replace substrings in character strings 
  9359. o RTBLANKS - Remove trailing blanks 
  9360. o VCAT - Catenate matrixes by rows 
  9361. o XBLANKS - Remove all excess blanks 
  9362.  
  9363.  
  9364. ΓòÉΓòÉΓòÉ 13.21.6.1. DOUBLE - Replace selected characters with pairs ΓòÉΓòÉΓòÉ
  9365.  
  9366. ZΓò£L DOUBLE R
  9367.  
  9368. DOUBLE replaces each occurrence of the scalar L in the vector R by a pair of 
  9369. scalars L. 
  9370.  
  9371.       VΓò£'ABC''DEFGH''IJK'
  9372.       V
  9373. ABC'DEFGH'IJK'
  9374.       '''' DOUBLE V
  9375. ABC''DEFGH''IJK
  9376.  
  9377.  
  9378. ΓòÉΓòÉΓòÉ 13.21.6.2. FIND - Search for text in all workspace programs ΓòÉΓòÉΓòÉ
  9379.  
  9380. [namelist] FIND 'text' ['newtext']
  9381.  
  9382. Gives a listing of all functions and operators in the active workspace that 
  9383. contain the indicated text. 
  9384.  
  9385. If 'newtext' is specified, this function replaces 'text' in the objects listed 
  9386. in namelist with the new text. 
  9387.  
  9388.  
  9389. ΓòÉΓòÉΓòÉ 13.21.6.3. GATHER - Collect parsed and delimited fields ΓòÉΓòÉΓòÉ
  9390.  
  9391. ZΓò£L GATHER R
  9392.  
  9393. L is a scalar or one or two element vector, for example '()'. R is any array. 
  9394. GATHER searches the rows of R for a sequence "enclosed" within the first and 
  9395. second elements of L and ravels them into a vector. If L is a scalar or one 
  9396. element vector then it is used as the trailing delimiter also. A blank is 
  9397. inserted at each point where the resulting vector crosses a row boundary in R. 
  9398.  
  9399.  
  9400. ΓòÉΓòÉΓòÉ 13.21.6.4. GVCAT - Catenate rows to arrays of any rank ΓòÉΓòÉΓòÉ
  9401.  
  9402. ZΓò£L GVCAT R    ╤ä Generalized Vertical CATenation
  9403.  
  9404. L and R Z is the result of catenating L to R along the first coordinate of the 
  9405. array of higher rank. 
  9406.  
  9407.  
  9408. ΓòÉΓòÉΓòÉ 13.21.6.5. HCAT - Catenate matrixes by columns ΓòÉΓòÉΓòÉ
  9409.  
  9410. ZΓò£L HCAT R    ╤ä Horizontal CATenation
  9411.  
  9412. HCAT catenates columns: given two matrixes, it places them side-by-side. L and 
  9413. R should not be of rank greater than 2. Z is always of rank 2. 
  9414.  
  9415.  
  9416. ΓòÉΓòÉΓòÉ 13.21.6.6. INBLANKS - Separate characters by blanks ΓòÉΓòÉΓòÉ
  9417.  
  9418. ZΓò£L INBLANKS R
  9419.  
  9420. If characters in L are contained in R, separate them with blanks. 
  9421.  
  9422.  
  9423. ΓòÉΓòÉΓòÉ 13.21.6.7. LADJ - Left adjust ΓòÉΓòÉΓòÉ
  9424.  
  9425. ZΓò£LADJ R     ╤ä Left ADJust
  9426.  
  9427. R can be any array. Z is that array with nonblank characters shifted to the 
  9428. left as far as possible. 
  9429.  
  9430.  
  9431. ΓòÉΓòÉΓòÉ 13.21.6.8. LINEFOLD - Fold and indent line as specified ΓòÉΓòÉΓòÉ
  9432.  
  9433. ZΓò£L LINEFOLD R
  9434.  
  9435. This function "folds" the line R so that it is no greater than the length 
  9436. specified by the first (or only) element in L. If L has a second element, then 
  9437. this specifies the number of blanks to be used in offsetting the second and all 
  9438. following rows in the output Z. Z is always of rank 2. 
  9439.  
  9440.  
  9441. ΓòÉΓòÉΓòÉ 13.21.6.9. MAT - Make a matrix out of any array ΓòÉΓòÉΓòÉ
  9442.  
  9443. ZΓò£MAT R      ╤ä MATrix
  9444.  
  9445. Z is an array of rank 2 containing all the elements of R. 
  9446.  
  9447.  
  9448. ΓòÉΓòÉΓòÉ 13.21.6.10. MATFOLD - Fold and indent matrix lines as specified ΓòÉΓòÉΓòÉ
  9449.  
  9450. ZΓò£L MATFOLD R   ╤ä MATrix FOLD
  9451.  
  9452. L has one or two integer components. R may be any array. Z is a matrix with a 
  9453. number of columns equal to the first (or only) component of L. Any lines longer 
  9454. than this width are "folded" as in LINEFOLD. 
  9455.  
  9456.  
  9457. ΓòÉΓòÉΓòÉ 13.21.6.11. NOQUOTES - Remove quoted substrings ΓòÉΓòÉΓòÉ
  9458.  
  9459. ZΓò£NOQUOTES R
  9460.  
  9461. R is a character vector. Z is the same vector with all quoted substrings 
  9462. removed. 
  9463.  
  9464.  
  9465. ΓòÉΓòÉΓòÉ 13.21.6.12. OBLANKS - Remove outer blanks ΓòÉΓòÉΓòÉ
  9466.  
  9467. ZΓò£OBLANKS R    ╤ä Outer BLANKS
  9468.  
  9469. Remove "outer blanks". R is a vector. Z is R with all leading and trailing 
  9470. blanks removed. 
  9471.  
  9472.  
  9473. ΓòÉΓòÉΓòÉ 13.21.6.13. QREPLACE - Replace ? occurrences by character strings ΓòÉΓòÉΓòÉ
  9474.  
  9475. ZΓò£L QREPLACE R  ╤ä Question mark REPLACEment
  9476.  
  9477. R is a vector containing one or more question marks. L is a character vector 
  9478. containing one or more subvectors to be substituted for the question marks. The 
  9479. first character of L is a delimiter used to identify the substitution vectors. 
  9480. This delimiter must also be the last character of L. Z is R with the 
  9481. substitutions made. 
  9482.  
  9483.  
  9484. ΓòÉΓòÉΓòÉ 13.21.6.14. RADJ - Right adjust ΓòÉΓòÉΓòÉ
  9485.  
  9486. ZΓò£RADJ R     ╤ä Right ADJust
  9487.  
  9488. Z is R "right-adjusted", so that the rightmost character of each row is not 
  9489. blank unless all the characters of the row are blank. R can be an array; the 
  9490. rows are "right-adjusted" individually. 
  9491.  
  9492.  
  9493. ΓòÉΓòÉΓòÉ 13.21.6.15. RCNUM - Produce numerical headings for rows and columns ΓòÉΓòÉΓòÉ
  9494.  
  9495. ZΓò£RCNUM R     ╤ä Row and Column NUMbers
  9496.  
  9497. R is a matrix. Z is R with column numbers across the top and row numbers along 
  9498. the left side. 
  9499.  
  9500.  
  9501. ΓòÉΓòÉΓòÉ 13.21.6.16. REPLACE - Replace substrings in character strings ΓòÉΓòÉΓòÉ
  9502.  
  9503. ZΓò£L REPLACE R
  9504.  
  9505. R may be any array. Z is R with every occurrence of a "seek" string replaced by 
  9506. a "replace" string. L is a two element vector, each of whose elements is a 
  9507. scalar or vector. The first element is the "seek" string and the second element 
  9508. is the "replace" string. 
  9509.  
  9510. REPLACEV is a subfunction of REPLACE. 
  9511.  
  9512.    TEXTΓò£4 4╤å'HEREIS  SOMETEXT'
  9513.    REPLACE/' _' ('HERE' 'THERE') TEXT
  9514. THERE
  9515. IS___
  9516. SOME_
  9517. TEXT_
  9518.  
  9519.  
  9520. ΓòÉΓòÉΓòÉ 13.21.6.17. RTBLANKS - Remove trailing blanks ΓòÉΓòÉΓòÉ
  9521.  
  9522. ZΓò£RTBLANKS R   ╤ä Remove Trailing BLANKS
  9523.  
  9524. R is a simple array. Z is R with trailing blanks or trailing blank columns 
  9525. removed. 
  9526.  
  9527.  
  9528. ΓòÉΓòÉΓòÉ 13.21.6.18. VCAT - Catenate matrixes by rows ΓòÉΓòÉΓòÉ
  9529.  
  9530. ZΓò£L VCAT R    ╤ä Vertical CATenation
  9531.  
  9532. L and R are arrays of rank 2 or less. Z is a matrix. Its width is that of the 
  9533. wider of L or R. L is at the top of Z and R is at the bottom. 
  9534.  
  9535.  
  9536. ΓòÉΓòÉΓòÉ 13.21.6.19. XBLANKS - Remove all excess blanks ΓòÉΓòÉΓòÉ
  9537.  
  9538. ZΓò£XBLANKS R    ╤ä remove eXtra BLANKS
  9539.  
  9540. Remove "extra blanks". R must be a vector. Z is R with leading and trailing 
  9541. blanks removed and intermediate blank sequences reduced to a single blank. 
  9542.  
  9543.  
  9544. ΓòÉΓòÉΓòÉ 13.21.7. GPTRACE: Setting and Removing Trace and Stop Vectors ΓòÉΓòÉΓòÉ
  9545.  
  9546. The functions in this group can be used in debugging your defined APL2 
  9547. operations by establishing trace and stop vectors when you're checking the 
  9548. operations out, and removing them when you're finished. 
  9549.  
  9550. STOPALL
  9551.  
  9552. STOPALL creates stop vectors for all the lines of all the functions and 
  9553. operators in the active workspace. 
  9554.  
  9555. STOPOFF
  9556.  
  9557. This function cancels all the stop vectors in the active workspace. 
  9558.  
  9559. STOPONE
  9560.  
  9561. STOPONE creates stop vectors for the first statements of all the functions and 
  9562. operators in the active workspace. 
  9563.  
  9564. TRACEALL
  9565.  
  9566. TRACEALL creates trace vectors for all the statements of all the functions and 
  9567. operators in the active workspace. 
  9568.  
  9569. TRACEBR R    ╤ä TRACE BRanch
  9570.  
  9571. This function creates a trace vector for every branch statement of the function 
  9572. or operator named in R. R is a single name. 
  9573.  
  9574. TRACELIST R
  9575.  
  9576. This function creates trace vectors for all the statements in the functions and 
  9577. operators named in R. R is a simple scalar, vector, or matrix, or a vector of 
  9578. vectors. 
  9579.  
  9580. TRACEOFF
  9581.  
  9582. This function cancels all the trace vectors in the active workspace. 
  9583.  
  9584. TRACEONE
  9585.  
  9586. TRACEONE creates trace vectors for the first statements of all the functions 
  9587. and operators in the active workspace. 
  9588.  
  9589.  
  9590. ΓòÉΓòÉΓòÉ 13.21.8. GPXLATE: Translating from One Character Representation to Another ΓòÉΓòÉΓòÉ
  9591.  
  9592. GPXLATE contains three functions and two global variables. The variables are 
  9593. used as translate-tables by the functions LCTRANS (which converts from 
  9594. uppercase to lowercase), and UCTRANS (which converts from lowercase to 
  9595. uppercase). 
  9596.  
  9597. The third function, TRANSLATE, is a general-purpose translate function that 
  9598. requires a translate table as its left argument. 
  9599.  
  9600. The use of the uppercase and lowercase translate functions is demonstrated in 
  9601. Examples of Lowercase and Uppercase Translation. Constructing and Using a 
  9602. Translate Table shows how the lowercase translate table was constructed. 
  9603.  
  9604. Notes for the figure: 
  9605.  
  9606. (1)   Since translation requires selecting values from tables, it is important 
  9607.       to establish a known index origin. The first action is to set the origin 
  9608.       to 0, because 0 is more useful then 1 for translating purposes. 
  9609.  
  9610. (2)   The indexes of the lowercase letters in ╨áAV are determined by the use of 
  9611.       ╨áAF. 
  9612.  
  9613. (3)   Similarly for uppercase. 
  9614.  
  9615. (4)   The lowercase translate table is initialized as ╨áAV. 
  9616.  
  9617. (5)   The lowercase letters replace the uppercase letters in the translate 
  9618.       table. 
  9619.  
  9620. (6), (7), and (8) Show how the index sets and the translate table are 
  9621.       interconnected. 
  9622.  
  9623. (9)   Is a canonical representation of the LCTRANS function, showing how it 
  9624.       does lowercase translation. 
  9625.  
  9626.  
  9627. ΓòÉΓòÉΓòÉ 13.21.8.1. Examples of Lowercase and Uppercase Translation ΓòÉΓòÉΓòÉ
  9628.  
  9629.  
  9630. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  9631.  
  9632.    CVΓò£'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'
  9633.    UCTRANS CV
  9634. ABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZ
  9635.    LCTRANS CV
  9636. abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz
  9637.  
  9638.  
  9639. ΓòÉΓòÉΓòÉ 13.21.8.2. Constructing and Using a Translate Table ΓòÉΓòÉΓòÉ
  9640.  
  9641.  
  9642. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  9643.  
  9644. Constructing the Lowercase Translate Table 
  9645.  
  9646. (1)      ╨áIOΓò£0 
  9647. (2)      LOWERINDICESΓò£╨áAF 'abcdefghijklmnopqrstuvwxyz' 
  9648. (3)      UPPERINDICESΓò£╨áAF 'ABCDEFGHIJKLMNOPQRSTUVWXYZ' 
  9649. (4)      LCTtΓò£╨áAV 
  9650. (5)      LCTt[UPPERINDICES]Γò£╨áAF LOWERINDICES 
  9651. (6)      LOWERINDICES 
  9652.       97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 
  9653.          113 114 115 116 117 118 119 120 121 122 
  9654. (7)      UPPERINDICES 
  9655.       65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 
  9656.          85 86 87 88 89 90 
  9657. (8)      ╨áAF LCTt[UPPERINDICES] 
  9658.       97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 
  9659.          113 114 115 116 117 118 119 120 121 122 
  9660. (9)      ╨áCR 'LCTRANS' 
  9661.  
  9662.             AΓò£LCTRANS B
  9663.             ╤ä A is B with uppercase letters translated to lowercase
  9664.                letters.
  9665.             AΓò£LCTt[╨áIO+╨áAF B]
  9666.  
  9667.  
  9668. ΓòÉΓòÉΓòÉ 14. Supplied Auxiliary Processors ΓòÉΓòÉΓòÉ
  9669.  
  9670. The auxiliary processors (APs) supplied with IBM APL2/2 and discussed in this 
  9671. chapter are: 
  9672.  
  9673. o AP 100-OS/2 host command interface 
  9674. o AP 101-Alternate input 
  9675. o AP 119-Socket interface 
  9676. o AP 124-Text display 
  9677. o AP 127-SQL interface for DB2 
  9678. o AP 145-OS/2 services interface 
  9679. o AP 207-Universal graphics 
  9680. o AP 210-OS/2 file management 
  9681. o AP 211-APL2 object library management 
  9682.  
  9683. Note:  All APL2 invocation parameters and environment variables are also passed 
  9684. to any dependent auxiliary processors. Dependent auxiliary processor's are 
  9685. auto-started as children of the APL2 interpreter session when the first share 
  9686. offer is made to the auxiliary processor. All command line parameters are 
  9687. passed unmodified to the auxiliary processor, with the exception of the -id 
  9688. parameter, the value of which is adjusted to identify the processor number of 
  9689. the auxiliary processor, followed by the processor number of the parent 
  9690. interpreter session. 
  9691.  
  9692. To use an auxiliary processor requires a shared variable, or for some auxiliary 
  9693. processors, a pair of shared variables, to pass commands and data between the 
  9694. APL2 application and the auxiliary processor. Since auxiliary processors can 
  9695. run asynchronously with the APL2 interpreter, applications must follow a proper 
  9696. Shared Variable Processor (SVP) protocol when establishing shared variable 
  9697. communication with an auxiliary processor, to avoid potential timing problems 
  9698. with the two processes running in parallel. For a complete description of the 
  9699. SVP system functions, refer to APL2 Programming: Language Reference. 
  9700.  
  9701. o Using the Share-Offer Utilities 
  9702. o AP 100-The OS/2 Host Command Auxiliary Processor 
  9703. o AP 101-The Alternate Input (Stack) Auxiliary Processor 
  9704. o AP 119-Socket Interface Processor 
  9705. o AP 124-The Text Display Auxiliary Processor 
  9706. o AP 127-SQL Processor 
  9707. o AP 145-The OS/2 Services Interface Auxiliary Processor 
  9708. o AP 207-The Universal Graphics Auxiliary Processor 
  9709. o AP 210-The File Auxiliary Processor 
  9710. o AP 211-The APL2 Object Library Auxiliary Processor 
  9711.  
  9712.  
  9713. ΓòÉΓòÉΓòÉ 14.1. Using the Share-Offer Utilities ΓòÉΓòÉΓòÉ
  9714.  
  9715. To simplify the establishment of fully-coupled shares, and to ensure that the 
  9716. necessary access control is set for typical communication with an auxiliary 
  9717. processor, two functions are distributed in the library 1 UTILITY workspace for 
  9718. application developers. The two functions are SVOFFER and SVOPAIR. SVOFFER is 
  9719. for use with auxiliary processors employing a single shared variable interface. 
  9720. SVOPAIR is used for auxiliary processors such as AP 124 and AP 210 that require 
  9721. a control and a data variable for communication. 
  9722.  
  9723. The SVOFFER function must return a "degree of coupling" of 2 for each variable 
  9724. offered, before the shared variable can be used to pass commands and data. This 
  9725. indicates that the auxiliary processor has accepted the share offer. An 
  9726. indeterminate amount of time is required for the auxiliary processor to accept 
  9727. the offer. Typically, an auxiliary processor accepts the shared variable offer 
  9728. immediately, but the SVOFFER function queries the degree of coupling for a 
  9729. maximum of 15 seconds before exiting with a result of 1 indicating that the 
  9730. auxiliary processor has not matched the offer. 
  9731.  
  9732. The SVOPAIR function is used for auxiliary processors that support a 
  9733. two-variable interface, where the control variable name begins with "C" or 
  9734. "CTL" and the data variable name begins with "D" or "DAT". SVOPAIR waits up to 
  9735. 15 seconds for all control variable offers to be accepted. It returns the final 
  9736. degree of coupling for all variables offered. The expected coupling for the 
  9737. control variables is 2 (fully coupled), and the data variables can properly 
  9738. return either 1 or 2, depending on the auxiliary processor. 
  9739.  
  9740. Prior to sending commands to an auxiliary processor, shared variable access 
  9741. control should be set to ensure that the SVP maintains the necessary sequencing 
  9742. of sets and references of the shared variable by both the APL2 application 
  9743. program and the auxiliary processor. SVOFFER and SVOPAIR set the necessary 
  9744. access controls for typical auxiliary processor communication. SVOFFER sets 
  9745. access control on all of the variables offered, and SVOPAIR sets access control 
  9746. only on the variables with names starting with the letter "C" (that is, control 
  9747. variables only-no access control is applied to data variables). The access 
  9748. control applied is 1 0 1 0, which prevents two successive sets of the variable 
  9749. by the application without an intervening access by the auxiliary processor, 
  9750. and also ensures that the auxiliary processor sets a new value in the variable 
  9751. between successive uses by the APL2 application. This is the most common access 
  9752. protocol used for shared variable communication with the auxiliary processors. 
  9753.  
  9754. o Example 1 
  9755. o Example 2 
  9756.  
  9757.  
  9758. ΓòÉΓòÉΓòÉ 14.1.1. Example 1 ΓòÉΓòÉΓòÉ
  9759.  
  9760.  ╤ä Single offer to host auxiliary processor
  9761.        100 SVOFFER 'CMD'
  9762.  2
  9763.  ╤ä Offer multiple variables to one AP
  9764.        100 SVOFFER 'V1' 'V2'
  9765.  2 2
  9766.  ╤ä Offer multiple variables to multiple APs
  9767.        100 211 SVOFFER 'V100' 'V211'
  9768.  2 2
  9769.  ╤ä Check degree of coupling for multiple variables
  9770.        SVOFFER 'V100' 'V211'
  9771.  2 2
  9772.  ╤ä Invalid shared variable offer
  9773.        211 SVOFFER 'BAD+NAME'
  9774.  0
  9775.  ╤ä Offer and trap errors
  9776.        ╨áES (2╤ï.╨çAP SVOFFER VARS)/'Share offer unaccepted by AP',╨╛AP
  9777.  
  9778.  
  9779. ΓòÉΓòÉΓòÉ 14.1.2. Example 2 ΓòÉΓòÉΓòÉ
  9780.  
  9781.  ╤ä Offer a set of variables to the fullscreen processor
  9782.        124 SVOPAIR 'CTL124' 'DAT124'
  9783.  2 2
  9784.  ╤ä Offer using surrogates
  9785.        124 SVOPAIR 'Control C' 'Data D'
  9786.  2 2
  9787.  ╤ä Note: Access control set for control, not data
  9788.        ╨áSVCΓûá 'Control' 'Data'
  9789.   1 0 1 1  0 0 0 0
  9790.  ╤ä Check degree of coupling
  9791.        SVOPAIR 'Control' 'Data'
  9792.  2 2
  9793.  ╤ä Offer improper control variable
  9794.        210 SVOPAIR 'A1' 'D1'
  9795.  1 1
  9796.  
  9797.  
  9798. ΓòÉΓòÉΓòÉ 14.2. AP 100-The OS/2 Host Command Auxiliary Processor ΓòÉΓòÉΓòÉ
  9799.  
  9800. AP 100 is an auxiliary processor that allows OS/2 commands or programs to be 
  9801. executed. AP 100 itself imposes no specific limit on the number of concurrent 
  9802. shared variables that you can use. It accepts a shared variable of any name. 
  9803. For example: 
  9804.  
  9805.       100 SVOFFER 'SHR100'
  9806. 2
  9807.  
  9808. offers variable SHR100 to AP 100 and sets access control. See Using the 
  9809. Share-Offer Utilities for a description of the SVOFFER function (from the 1 
  9810. UTILITY workspace). 
  9811.  
  9812. After sharing is established, a valid OS/2 command or program can be executed 
  9813. by assigning the command to the shared variable. For example, to list the files 
  9814. in the current directory: 
  9815.  
  9816.       SHR100Γò£'DIR'
  9817.  
  9818. Notes: 
  9819.  
  9820.  1. If AP 100 is started automatically by the interpreter (the default), then 
  9821.     any output generated by the execution of the command appears in the window 
  9822.     associated with the interpreter. This window is often minimized, because it 
  9823.     is not normally used for APL2 session input and output. 
  9824.  
  9825.  2. If an empty vector ('' or ╤î0) is given as the command, the shared variable 
  9826.     returns with the characters 'OS/2'. 
  9827.  
  9828.  3. Commands issued through AP 100 do not affect the interpreter environment. 
  9829.     For example, issuing a change directory command through either AP 100, or 
  9830.     through )HOST, does not change the directory that your current APL2 session 
  9831.     is using. 
  9832.  
  9833. o AP 100 Return Codes 
  9834.  
  9835.  
  9836. ΓòÉΓòÉΓòÉ 14.2.1. AP 100 Return Codes ΓòÉΓòÉΓòÉ
  9837.  
  9838. Code      Meaning 
  9839.   0 -     Success 
  9840.   1 -     Invalid OS/2 command 
  9841. 444 -     Invalid shared variable value 
  9842.  
  9843. Other error codes are those returned as the exit status of the called routine. 
  9844.  
  9845.  
  9846. ΓòÉΓòÉΓòÉ 14.3. AP 101-The Alternate Input (Stack) Auxiliary Processor ΓòÉΓòÉΓòÉ
  9847.  
  9848. The alternate input (stack) processor (AP 101) can be used to create a stack of 
  9849. programmable input to APL2. 
  9850.  
  9851. Conceptually, the alternate-input stack is a vector of character vectors. Each 
  9852. item is one stacked input line of variable length. 
  9853.  
  9854. Although any one instance of APL2/2 can maintain only one stack, several shared 
  9855. variables can be used to add entries to the stack. Entries are stacked in 
  9856. first-in, first-out (FIFO) order (the default) or last-in, first-out (LIFO) 
  9857. order. 
  9858.  
  9859. An input stack is normally created within a defined function. The top entry 
  9860. (the first item) in the stack is used when the APL2 interpreter requests input. 
  9861. This occurs when: 
  9862.  
  9863. o An APL2 statement prompts for user input (╨á or ╨í) 
  9864. o The APL2 Editor 1 (selected by )EDITOR 1) prompts for input 
  9865. o APL2 opens the keyboard for immediate execution 
  9866. o APL2 execution is suspended as a result of an error or stop control (SΓòó) 
  9867.  
  9868. Share a variable with AP 101. For example: 
  9869.  
  9870.       101 SVOFFER 'SHR101'
  9871. 2
  9872.  
  9873. offers variable SHR101 to AP 101 and sets access control. See Using the 
  9874. Share-Offer Utilities for a description of the SVOFFER function. 
  9875.  
  9876. After sharing is established, entries can be added to the stack by assigning 
  9877. the text to the shared variable (SHR101 in this example): 
  9878.  
  9879.       SHR101Γò£'any character string'
  9880.  
  9881. The string can contain new-line characters (╨áTC[╨áIO+1]), which causes each 
  9882. portion of the string delimited by a new-line to be treated as a separate entry 
  9883. on the stack. 
  9884.  
  9885. o AP 101 Commands 
  9886. o AP 101 Return Codes 
  9887.  
  9888.  
  9889. ΓòÉΓòÉΓòÉ 14.3.1. AP 101 Commands ΓòÉΓòÉΓòÉ
  9890.  
  9891. The stack can be purged of all or some entries, and the order (LIFO/FIFO) in 
  9892. which the entries are used can be selected with the following commands: 
  9893.  
  9894. o SHR101Γò£0 - Purges the entire stack. 
  9895.  
  9896. o SHR101Γò£0,n - Purges n entries from the stack. If n>0 these are dropped from 
  9897.   the LIFO end, and if n<0 these are dropped from the FIFO end. 
  9898.  
  9899. o SHR101Γò£10 - Queries the state of the stack (LIFO/FIFO) 
  9900.  
  9901. o SHR101Γò£10 1 - Sets the stack to LIFO 
  9902.  
  9903. o SHR101Γò£10 ┬ñ1 - Sets the stack to FIFO (the default) 
  9904.  
  9905. The maximum size of the stack is 1000 entries. 
  9906.  
  9907.  
  9908. ΓòÉΓòÉΓòÉ 14.3.2. AP 101 Return Codes ΓòÉΓòÉΓòÉ
  9909.  
  9910. Code      Meaning 
  9911.   0 -     Success 
  9912.  12 -     Stack overflow 
  9913. 444 -     Invalid object 
  9914.  
  9915.  
  9916. ΓòÉΓòÉΓòÉ 14.4. AP 119-Socket Interface Processor ΓòÉΓòÉΓòÉ
  9917.  
  9918. The socket interface processor is used to pass requests to the Transmission 
  9919. Control Protocol/Internet Protocol (TCP/IP) product. TCP/IP provides 
  9920. communication facilities across networks. See TCP/IP for OS/2 Programmer's 
  9921. Reference for more information about TCP/IP. 
  9922.  
  9923. Notes: 
  9924.  
  9925.  1. Commands are passed as nested vectors. The first element of the value 
  9926.     assigned to the variable determines the type of commands being issued. For 
  9927.     the workstation, the command is 'TCPIP' for commands to TCP/IP. 
  9928.  
  9929.  2. The general form of the result is a three-element vector: 
  9930.  
  9931.    o An AP 119 return code 
  9932.    o A TCP/IP return code 
  9933.    o Data returned by the command 
  9934.  
  9935.  3. No AP invocation options are required or defined. 
  9936.  
  9937. o Blocking 
  9938. o Using AP 119-The TCPIP commands 
  9939. o Sample AP 119 Session Using the APL2 Socket API 
  9940. o AP 119 Return Codes 
  9941.  
  9942.  
  9943. ΓòÉΓòÉΓòÉ 14.4.1. Blocking ΓòÉΓòÉΓòÉ
  9944.  
  9945. Some socket calls may not return control until a condition is satisfied. For 
  9946. example, the READ and RECV calls may not return control until data is available 
  9947. to receive. The default state of a socket is blocking mode, which means that 
  9948. these calls do not return control immediately. 
  9949.  
  9950. Using the APL2 socket interface with sockets in the default mode, AP 119 does 
  9951. not receive control back from TCP/IP until blocking calls complete. Since AP 
  9952. 119 does not have control, it is not able to set the shared variable until the 
  9953. blocking condition is satisfied. A reference of the variable causes a shared 
  9954. variable interlock until the blocking call completes. 
  9955.  
  9956. A socket can be set to nonblocking mode with the FCNTL socket call. If this is 
  9957. done, AP 119 receives control on subsequent calls and returns the EWOULDBLOCK 
  9958. return code. 
  9959.  
  9960.  
  9961. ΓòÉΓòÉΓòÉ 14.4.2. Using AP 119-The TCPIP commands ΓòÉΓòÉΓòÉ
  9962.  
  9963. The TCPIP commands provide a means to make calls to TCP/IP. The AP 119 TCP/IP 
  9964. interface closely matches the TCP/IP C socket interface. The following sections 
  9965. describe the APL2 syntax used for making TCP/IP calls through AP 119. 
  9966.  
  9967. o ACCEPT 
  9968. o BIND 
  9969. o CLOSE 
  9970. o CONNECT 
  9971. o FCNTL 
  9972. o GETHOSTID 
  9973. o GETHOSTNAME 
  9974. o GETPEERNAME 
  9975. o GETSOCKNAME 
  9976. o GETSOCKOPT 
  9977. o LISTEN 
  9978. o READ 
  9979. o RECV 
  9980. o RECVFROM 
  9981. o SELECT 
  9982. o SEND 
  9983. o SENDTO 
  9984. o SETSOCKOPT 
  9985. o SHUTDOWN 
  9986. o SOCKET 
  9987. o WRITE 
  9988.  
  9989.  
  9990. ΓòÉΓòÉΓòÉ 14.4.2.1. ACCEPT ΓòÉΓòÉΓòÉ
  9991.  
  9992. Accepts a connection request. This call accepts the first connection on its 
  9993. queue of pending connections. A new socket number is returned for the 
  9994. connection and the original socket remains available to accept more connection 
  9995. requests. This call blocks if there are no pending connections, and the socket 
  9996. is in blocking mode. 
  9997.  
  9998.       SV119Γò£'TCPIP' 'ACCEPT' sn
  9999.       (APRC TCPIPRC CMDRC)Γò£SV119
  10000.       (ns rp ra)Γò£CMDRC
  10001.  
  10002. Where: 
  10003.  
  10004. sn        Is the socket number. 
  10005. ns        Is the new socket number assigned by TCP/IP. 
  10006. rp        Is the port number of the remote process that connected with you. 
  10007. ra        Is the IP address of the remote process that connected with you. 
  10008.  
  10009. Example: 
  10010.  
  10011.       SV119Γò£'TCPIP' 'ACCEPT' 3
  10012.       (APRC TCPIPRC CMDRC)Γò£SV119
  10013.       CMDRC
  10014. 4 1023  9.113.12.92
  10015.  
  10016.  
  10017. ΓòÉΓòÉΓòÉ 14.4.2.2. BIND ΓòÉΓòÉΓòÉ
  10018.  
  10019. Associates a local IP address and port with a socket number. 
  10020.  
  10021.       SV119Γò£'TCPIP' 'BIND' sn lp la
  10022.       (APRC TCPIPRC CMDRC)Γò£SV119
  10023.  
  10024. Where: 
  10025.  
  10026. sn        Is the socket number. 
  10027.  
  10028. lp        Is the local port number. If this number is 0, TCP/IP assigns an 
  10029.           unused port number. 
  10030.  
  10031. la        Is the local IP address. If this address is '0.0.0.0', the socket can 
  10032.           be used with any local network. 
  10033.  
  10034. CMDRC     Is 0 
  10035.  
  10036. Example: 
  10037.  
  10038.       SV119Γò£'TCPIP' 'BIND' 3 1023 '9.112.12.92'
  10039.       SV119
  10040. 0 0 0
  10041.  
  10042.  
  10043. ΓòÉΓòÉΓòÉ 14.4.2.3. CLOSE ΓòÉΓòÉΓòÉ
  10044.  
  10045. Shuts down a socket. If the socket is associated with an open TCP connection, 
  10046. the connection is closed. 
  10047.  
  10048.       SV119Γò£'TCPIP' 'CLOSE' sn
  10049.       (APRC TCPIPRC CMDRC)Γò£SV119
  10050.  
  10051. Where: 
  10052.  
  10053. sn        Is the socket number. 
  10054.  
  10055. CMDRC     Is 0. 
  10056.  
  10057. Example: 
  10058.  
  10059.       SV119Γò£'TCPIP' 'CLOSE' 4
  10060.       SV119
  10061. 0 0 0
  10062.  
  10063.  
  10064. ΓòÉΓòÉΓòÉ 14.4.2.4. CONNECT ΓòÉΓòÉΓòÉ
  10065.  
  10066. Completes the binding necessary for a socket if BIND has not been issued and 
  10067. establishes a connection to a socket in listening mode. If the socket is in 
  10068. blocking mode, this call blocks until the connection is complete or an error is 
  10069. returned. 
  10070.  
  10071.       SV119Γò£'TCPIP' 'CONNECT' sn rp ra
  10072.       (APRC TCPIPRC CMDRC)Γò£SV119
  10073.  
  10074. Where: 
  10075.  
  10076. sn        Is the socket number. 
  10077.  
  10078. rp        Is the remote port number 
  10079.  
  10080. ra        Is the remote IP address 
  10081.  
  10082. CMDRC     Is 0. 
  10083.  
  10084. Example: 
  10085.  
  10086.       SV119Γò£'TCPIP' 'CONNECT' 3 1002 '9.113.14.90'
  10087.       SV119
  10088. 0 0 0
  10089.  
  10090.  
  10091. ΓòÉΓòÉΓòÉ 14.4.2.5. FCNTL ΓòÉΓòÉΓòÉ
  10092.  
  10093. Allows an application to change the operating characteristics of a socket. 
  10094.  
  10095.       SV119Γò£'TCPIP' 'FCNTL' sn cmd cdata
  10096.       (APRC TCPIPRC CMDRC)Γò£SV119
  10097.  
  10098. Where: 
  10099.  
  10100. sn        Is the socket number. 
  10101. cmd       Is the command (see below). 
  10102. cdata     Is the data associated with the command (see below). 
  10103. CMDRC     Is 0 (if setting the status) or the status flags (if getting the 
  10104.           status). 
  10105.  
  10106. Note:  If the cmd is 'F_GETFL', the, cdata parameter is ignored. 
  10107.  
  10108. The possible values for cmd are 'F_GETFL' and  'F_SETFL'. 
  10109.  
  10110. The possible values for cdata are 0 and 'FNDELAY'. 
  10111.  
  10112. Example: 
  10113.  
  10114.       SV119Γò£'TCPIP' 'FCNTL' 3 'F_SETFL' 'FNDELAY'
  10115.       SV119
  10116. 0 0 0
  10117.  
  10118.  
  10119. ΓòÉΓòÉΓòÉ 14.4.2.6. GETHOSTID ΓòÉΓòÉΓòÉ
  10120.  
  10121. Returns the IP address for the host. If the host has more than one IP address, 
  10122. the primary one is returned. 
  10123.  
  10124.       SV119Γò£'TCPIP' 'GETHOSTID'
  10125.       (APRC TCPIPRC ia)Γò£SV119
  10126.  
  10127. Where: 
  10128.  
  10129. ia        Is the primary host IP address. 
  10130.  
  10131. Example: 
  10132.  
  10133.       SV119Γò£'TCPIP' 'GETHOSTID'
  10134.       (APRC TCPIPRC CMDRC)Γò£SV119
  10135.       CMDRC
  10136. 9.113.12.92
  10137.  
  10138.  
  10139. ΓòÉΓòÉΓòÉ 14.4.2.7. GETHOSTNAME ΓòÉΓòÉΓòÉ
  10140.  
  10141. Returns the name of the host processor on which the user is running. 
  10142.  
  10143.       SV119Γò£'TCPIP' 'GETHOSTNAME'
  10144.       (APRC TCPIPRC hn)Γò£SV119
  10145.  
  10146. Where: 
  10147.  
  10148. hn        Is the name of the host. 
  10149.  
  10150. Example: 
  10151.  
  10152.       SV119Γò£'TCPIP' 'GETHOSTNAME'
  10153.       (APRC TCPIPRC CMDRC)Γò£SV119
  10154.       CMDRC
  10155. STLVM20
  10156.  
  10157.  
  10158. ΓòÉΓòÉΓòÉ 14.4.2.8. GETPEERNAME ΓòÉΓòÉΓòÉ
  10159.  
  10160. Returns the family, port and IP address of a peer connected to a given socket. 
  10161.  
  10162.       SV119Γò£'TCPIP' 'GETPEERNAME' sn
  10163.       (APRC TCPIPRC CMDRC)Γò£SV119
  10164.       (fm rp ra)Γò£CMDRC
  10165.  
  10166. Where: 
  10167.  
  10168. sn        Is the socket number. 
  10169. fm        Is the family. 
  10170. rp        Is the remote port. 
  10171. ra        Is the remote IP address 
  10172.  
  10173. Example: 
  10174.  
  10175.       SV119Γò£'TCPIP' 'GETPEERNAME' 3
  10176.       (APRC TCPIPRC CMDRC)Γò£SV119
  10177.       CMDRC
  10178. 2 1002  9.113.14.90
  10179.  
  10180.  
  10181. ΓòÉΓòÉΓòÉ 14.4.2.9. GETSOCKNAME ΓòÉΓòÉΓòÉ
  10182.  
  10183. Returns the family, port and IP address of a given socket. 
  10184.  
  10185.       SV119Γò£'TCPIP' 'GETSOCKNAME' sn
  10186.       (APRC TCPIPRC CMDRC)Γò£SV119
  10187.       (fm lp la)Γò£CMDRC
  10188.  
  10189. Where: 
  10190.  
  10191. sn        Is the socket number. 
  10192. fm        Is the family. 
  10193. lp        Is the local port. 
  10194. la        Is the local IP address. 
  10195.  
  10196. Example: 
  10197.  
  10198.  
  10199.  
  10200.  
  10201. 2 1023  9.113.12.92
  10202.  
  10203.  
  10204. ΓòÉΓòÉΓòÉ 14.4.2.10. GETSOCKOPT ΓòÉΓòÉΓòÉ
  10205.  
  10206. Gets options associated with a socket. 
  10207.  
  10208.       SV119Γò£'TCPIP' 'GETSOCKOPT' sn lv op
  10209.       (APRC TCPIPRC ov)Γò£SV119
  10210.  
  10211. Where: 
  10212.  
  10213. sn        Is the socket number. 
  10214. lv        Is the communication level. 
  10215. op        Is the option name 
  10216. ov        Is the option value. 
  10217.  
  10218. TCP/IP Socket Options provides some of the values and levels that are defined 
  10219. for the GETSOCKOPT and SETSOCKOPT calls. The subset listed includes those 
  10220. values that are compatible with AP 119 on the APL2/370 platform. OS/2 TCP/IP 
  10221. supports additional options that can be used by applications when 
  10222. cross-platform portability is not a stringent requirement. 
  10223.  
  10224. Example: 
  10225.  
  10226.       LEVΓò£'SOL_SOCKET'
  10227.       OPTΓò£'SO_BROADCAST'
  10228.       SV119Γò£'TCPIP' 'GETSOCKOPT' 4 LEV OPT
  10229.       SV119
  10230. 0 0 1
  10231.  
  10232. Note:  If the option specified is SO_LINGER, the third item is a vector of 2 
  10233. integers, representing the timeout value in seconds and micro-seconds, 
  10234. respectively. For all other options, the third item is a single integer. 
  10235.  
  10236.  
  10237. ΓòÉΓòÉΓòÉ 14.4.2.10.1. TCP/IP Socket Options ΓòÉΓòÉΓòÉ
  10238.  
  10239.  
  10240. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  10241.  
  10242. Option 
  10243.  
  10244.  
  10245. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  10246.  
  10247. Level 
  10248.  
  10249.  
  10250. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  10251.  
  10252. SO_BROADCAST 
  10253.  
  10254.  
  10255. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  10256.  
  10257. SOL_SOCKET 
  10258.  
  10259.  
  10260. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  10261.  
  10262. SO_DONTROUTE 
  10263.  
  10264.  
  10265. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  10266.  
  10267. SOL_SOCKET 
  10268.  
  10269.  
  10270. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  10271.  
  10272. SO_ERROR 
  10273.  
  10274.  
  10275. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  10276.  
  10277. SOL_SOCKET 
  10278.  
  10279.  
  10280. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  10281.  
  10282. SO_LINGER 
  10283.  
  10284.  
  10285. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  10286.  
  10287. SOL_SOCKET 
  10288.  
  10289.  
  10290. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  10291.  
  10292. SO_OOBINLINE 
  10293.  
  10294.  
  10295. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  10296.  
  10297. SOL_SOCKET 
  10298.  
  10299.  
  10300. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  10301.  
  10302. SO_REUSEADDR 
  10303.  
  10304.  
  10305. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  10306.  
  10307. SOL_SOCKET 
  10308.  
  10309.  
  10310. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  10311.  
  10312. SO_TYPE 
  10313.  
  10314.  
  10315. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  10316.  
  10317. SOL_SOCKET 
  10318.  
  10319.  
  10320. ΓòÉΓòÉΓòÉ 14.4.2.11. LISTEN ΓòÉΓòÉΓòÉ
  10321.  
  10322. Waits for a connection to a given socket if BIND has not been issued, and 
  10323. creates a connection request queue. 
  10324.  
  10325.       SV119Γò£'TCPIP' 'LISTEN' sn bl
  10326.       (APRC TCPIPRC CMDRC)Γò£SV119
  10327.  
  10328. Where: 
  10329.  
  10330. sn        Is the socket number. 
  10331.  
  10332. bl        Is the length of the request queue. 
  10333.  
  10334. Example: 
  10335.  
  10336.       SV119Γò£'TCPIP' 'LISTEN' 3 5
  10337.       SV119
  10338. 0 0 0
  10339.  
  10340.  
  10341. ΓòÉΓòÉΓòÉ 14.4.2.12. READ ΓòÉΓòÉΓòÉ
  10342.  
  10343. Reads data from a given socket. If the socket is in blocking mode and no data 
  10344. is available to read, this call blocks. 
  10345.  
  10346.       SV119Γò£'TCPIP' 'READ' sn type
  10347.       (APRC TCPIPRC CMDRC)Γò£SV119
  10348.  
  10349. Where: 
  10350.  
  10351. sn        Is the socket number. 
  10352.  
  10353. type      Is one of: 
  10354.  
  10355.    'B'       No conversion of data 
  10356.    'E'       Translate character data from EBCDIC to native format 
  10357.    'A'       Translate character data from ASCII to native format 
  10358.  
  10359.              Note:  Because OS/2's native format is ASCII, no translation is 
  10360.              done for option 'A'. 
  10361.  
  10362. CMDRC     Is the data read from the socket. 
  10363.  
  10364. Example: 
  10365.  
  10366.       SV119Γò£'TCPIP' 'READ' 4 'B'
  10367.       (APRC TCPIPRC CMDRC)Γò£SV119
  10368.       CMDRC
  10369. (data sent by partner)
  10370.  
  10371.  
  10372. ΓòÉΓòÉΓòÉ 14.4.2.13. RECV ΓòÉΓòÉΓòÉ
  10373.  
  10374. Receives data from a given socket. If the socket is in blocking mode and no 
  10375. data is available to receive, this call blocks. 
  10376.  
  10377.       SV119Γò£'TCPIP' 'RECV' sn flg tp
  10378.       (APRC TCPIPRC CMDRC)Γò£SV119
  10379.  
  10380. Where: 
  10381.  
  10382. sn        Is the socket number. 
  10383.  
  10384. flg       is receive option parameters (see below). 
  10385.  
  10386. tp        Is the type and is one of: 
  10387.  
  10388.    'B'       No conversion of data 
  10389.    'E'       Translate character data from EBCDIC to native format 
  10390.    'A'       Translate character data from ASCII to native format 
  10391.  
  10392.              Note:  Because OS/2's native format is ASCII, no translation is 
  10393.              done for option 'A'. 
  10394.  
  10395. Possible flag values are 0, 1 (MSG_OOB) or 2 (MSG_PEEK) 
  10396.  
  10397. Example: 
  10398.  
  10399.       SV119Γò£'TCPIP' 'RECV' 4 0 'B'
  10400.       (APRC TCPIPRC CMDRC)Γò£SV119
  10401.       CMDRC
  10402. (data sent by partner)
  10403.  
  10404.  
  10405. ΓòÉΓòÉΓòÉ 14.4.2.14. RECVFROM ΓòÉΓòÉΓòÉ
  10406.  
  10407. Receives data from a socket and identifies the source of the data. 
  10408.  
  10409.       SV119Γò£'TCPIP' 'RECVFROM' sn flg tp
  10410.       (APRC TCPIPRC CMDRC)Γò£SV119
  10411.       (dat add)Γò£CMDRC
  10412.       (fam rp ra)Γò£add
  10413.  
  10414. Where: 
  10415.  
  10416. sn        Is the socket number. 
  10417.  
  10418. flg       Is the recvfrom option parameters (see RECV above). 
  10419.  
  10420. tp        Is the type and is one of: 
  10421.  
  10422.    'B'       No conversion of data 
  10423.    'E'       Translate character data from EBCDIC to native format 
  10424.    'A'       Translate character data from ASCII to native format 
  10425.  
  10426.              Note:  Because OS/2's native format is ASCII, no translation is 
  10427.              done for option 'A'. 
  10428.  
  10429. dat       Is the data received from the socket. 
  10430.  
  10431. fam       Is the family (always 2 - AF_INET). 
  10432.  
  10433. rp        Is the remote port. 
  10434.  
  10435. ra        Is the remote IP address. 
  10436.  
  10437. Example: 
  10438.  
  10439.       SV119Γò£'TCPIP' 'RECVFROM' 4 0 'B'
  10440.       (APRC TCPIPRC CMDRC)Γò£SV119
  10441.       CMDRC
  10442. (data sent by partner) 2 1003 9.113.14.90
  10443.  
  10444.  
  10445. ΓòÉΓòÉΓòÉ 14.4.2.15. SELECT ΓòÉΓòÉΓòÉ
  10446.  
  10447. Monitors activity on a set of sockets as specified by three masks. The first 
  10448. argument indicates how many sockets to check. This would normally be 1 plus the 
  10449. largest socket number allocated. The masks must be at least as long as this 
  10450. value. A one in the mask specifies a corresponding socket to check. Three masks 
  10451. are returned as soon as something happens on a selected socket. For example, 
  10452. the read mask has a one if the corresponding socket has data ready to read. If 
  10453. the connection to a listening socket is completed, the read mask is set to 
  10454. indicate that a connection has been made to the socket and an ACCEPT call can 
  10455. be made. A socket is normally always ready to write. The except mask is set if 
  10456. out of band data is received. The timeout value specifies the number of seconds 
  10457. to wait for the call to complete. A value of zero means to wait indefinitely. 
  10458.  
  10459.       SV119Γò£'TCPIP' 'SELECT' ns rm wm xm to
  10460.       (APRC TCPIPRC CMDRC)Γò£SV119
  10461.       (rm wm xm)Γò£CMDRC
  10462.  
  10463. Where: 
  10464.  
  10465. ns        Is the number of sockets to check. 
  10466.  
  10467. rm        Is a read mask 
  10468.  
  10469. wm        Is a write mask 
  10470.  
  10471. xm        Is an exception mask 
  10472.  
  10473. to        Is the timeout value 
  10474.  
  10475. Example: 
  10476.  
  10477.       R_MASKΓò£0 0 0 1 1
  10478.       W_MASKΓò£0 0 0 0 0
  10479.       X_MASKΓò£0 0 0 0 0
  10480.       SV119Γò£'TCPIP' 'SELECT' 5 R_MASK W_MASK X_MASK 0
  10481.       (APRC TCPIPRC CMDRC)Γò£SV119
  10482.       DATA
  10483. 0 0 0 1 0   0 0 0 0 0   0 0 0 0 0
  10484.  
  10485.  
  10486. ΓòÉΓòÉΓòÉ 14.4.2.16. SEND ΓòÉΓòÉΓòÉ
  10487.  
  10488. Transmits data to a remote user whose remote address and port have been bound 
  10489. to the socket. If the socket is in blocking mode, this call blocks until TCP/IP 
  10490. can send the data. 
  10491.  
  10492.       SV119Γò£'TCPIP' 'SEND' sn flg tp dat
  10493.       (APRC TCPIPRC CMDRC)Γò£SV119
  10494.  
  10495. Where: 
  10496.  
  10497. sn        Is the socket number. 
  10498.  
  10499. flg       Is the send option parameters (0 or 1 - MSG_OOB). 
  10500.  
  10501. tp        Is the type and is one of: 
  10502.  
  10503.    'B'       No conversion of data 
  10504.    'E'       Translate character data from native format to EBCDIC 
  10505.    'A'       Translate character data from native format to ASCII 
  10506.  
  10507.              Note:  Because OS/2's native format is ASCII, no translation is 
  10508.              done for option 'A'. 
  10509.  
  10510. dat       the data to be sent. 
  10511.  
  10512. CMDRC     Is the number of characters sent 
  10513.  
  10514. Example: 
  10515.  
  10516.       SV119Γò£'TCPIP' 'SEND' 3 0 'B' 'CHARACTERS'
  10517.       (APRC TCPIPRC CMDRC)Γò£SV119
  10518. 0 0 10
  10519.  
  10520.  
  10521. ΓòÉΓòÉΓòÉ 14.4.2.17. SENDTO ΓòÉΓòÉΓòÉ
  10522.  
  10523. Transmits data to a remote user whose remote address and port are specified in 
  10524. the command. For APL2, the family is normally 2. 
  10525.  
  10526.       SV119Γò£'TCPIP' 'SENDTO' sn fl tp dat fm rp ra
  10527.       (APRC TCPIPRC CMDRC)Γò£SV119
  10528.  
  10529. Where: 
  10530.  
  10531. sn        Is the socket number. 
  10532.  
  10533. fl        Is the sendto option parameters (0 or 1 - MSG_OOB). 
  10534.  
  10535. tp        Is one of: 
  10536.  
  10537.    'B'       No conversion of data 
  10538.    'E'       Translate character data from native format to EBCDIC 
  10539.    'A'       Translate character data from native format to ASCII 
  10540.  
  10541.              Note:  Because OS/2's native format is ASCII, no translation is 
  10542.              done for option 'A'. 
  10543.  
  10544. dat        the data to be sent. 
  10545.  
  10546.    fm        Is the family (always 2 - AF_INET) 
  10547.    rp        Is the remote port number 
  10548.    ra        Is the remote IP address 
  10549.  
  10550. CMDRC     Is the number of characters sent 
  10551.  
  10552. Example: 
  10553.  
  10554.       (FAM R_PORT R_ADDR)Γò£2 '9.113.12.92' 1002
  10555.       DATAΓò£'These are characters.'
  10556.       SV119Γò£'TCPIP' 'SENDTO' 3 0 'B' DATA FAM R_PORT R_ADDR
  10557.       SV119
  10558. 0 0 23
  10559.  
  10560.  
  10561. ΓòÉΓòÉΓòÉ 14.4.2.18. SETSOCKOPT ΓòÉΓòÉΓòÉ
  10562.  
  10563. Sets options associated with a socket. 
  10564.  
  10565.       SV119Γò£'TCPIP' 'SETSOCKOPT' sn lv op o1 [o2]
  10566.       (APRC TCPIPRC CMDRC)Γò£SV119
  10567.  
  10568. Where: 
  10569.  
  10570. sn        Is the socket number. 
  10571. lv        Is the level of communication. 
  10572. op        Is the option name. 
  10573. o1        Is the option value. 
  10574. o2        Is the optional second option value. This is used only if op is 
  10575.           SO_LINGER. 
  10576.  
  10577. TCP/IP Socket Options provides the values and levels that are defined for the 
  10578. GETSOCKOPT and SETSOCKOPT calls. 
  10579.  
  10580. Example: 
  10581.  
  10582.       LEVΓò£'SOL_SOCKET'
  10583.       OPTΓò£'SO_BROADCAST'
  10584.       SV119Γò£'TCPIP' 'SETSOCKOPT' 4 LEV OPT 1
  10585.       SV119
  10586. 0 0 0
  10587.  
  10588.  
  10589. ΓòÉΓòÉΓòÉ 14.4.2.19. SHUTDOWN ΓòÉΓòÉΓòÉ
  10590.  
  10591. Shuts down all or part of a duplex connection. 
  10592.  
  10593.       SV119Γò£'TCPIP' 'SHUTDOWN' sn how
  10594.       (APRC TCPIPRC CMDRC)Γò£SV119
  10595.  
  10596. Where: 
  10597.  
  10598. sn        Is the socket number. 
  10599.  
  10600. how       Is type of shutdown (0, 1 or 2) 
  10601.  
  10602. Example: 
  10603.  
  10604.       SV119Γò£'TCPIP' 'SHUTDOWN' 4 1
  10605.       SV119
  10606. 0 0 0
  10607.  
  10608.  
  10609. ΓòÉΓòÉΓòÉ 14.4.2.20. SOCKET ΓòÉΓòÉΓòÉ
  10610.  
  10611. Creates an endpoint for communication. A socket number is allocated for use in 
  10612. other socket calls. 
  10613.  
  10614.       SV119Γò£'TCPIP' 'SOCKET'
  10615.       (APRC TCPIPRC CMDRC)Γò£SV119
  10616.  
  10617. Where: 
  10618.  
  10619. CMDRC     Is the socket number allocated. 
  10620.  
  10621. Example: 
  10622.  
  10623.       SV119Γò£'TCPIP' 'SOCKET'
  10624.       SV119
  10625. 0 0 3
  10626.  
  10627.  
  10628. ΓòÉΓòÉΓòÉ 14.4.2.21. WRITE ΓòÉΓòÉΓòÉ
  10629.  
  10630. Writes data to a given socket. 
  10631.  
  10632.       SV119Γò£'TCPIP' 'WRITE' sn tp dat
  10633.       (APRC TCPIPRC CMDRC)Γò£SV119
  10634.  
  10635. Where: 
  10636.  
  10637. sn        Is the socket number. 
  10638.  
  10639. tp        Is one of: 
  10640.  
  10641.    'B'       No conversion of data 
  10642.    'E'       Translate character data from native format to EBCDIC 
  10643.    'A'       Translate character data from native format to ASCII 
  10644.  
  10645.              Note:  Because OS/2's native format is ASCII, no translation is 
  10646.              done for option 'A'. 
  10647.  
  10648. dat       Is the data to be sent 
  10649.  
  10650. CMDRC     Is the number of characters written. 
  10651.  
  10652. Example: 
  10653.  
  10654.       SV119Γò£'TCPIP' 'WRITE' 3 'B' 'Many characters'
  10655.       SV119
  10656. 0 0 15
  10657.  
  10658.  
  10659. ΓòÉΓòÉΓòÉ 14.4.3. Sample AP 119 Session Using the APL2 Socket API ΓòÉΓòÉΓòÉ
  10660.  
  10661. In this example, one user shares the variable A and the other user shares 
  10662. variable B. 
  10663.  
  10664.     ╤ä User 1 shares a variable with AP 119
  10665.    119 ╨áSVO'A'
  10666. 1
  10667.    0 0 1 1 ╨áSVC 'A'
  10668. 0 0 1 1
  10669.    ╤ä User 1 allocates a socket
  10670.    AΓò£'TCPIP' 'SOCKET'
  10671.    A
  10672. 0 0 3
  10673.  
  10674. The return code shows that socket number 3 has been allocated. This is a stream 
  10675. socket that is allocated to the user but not bound to a particular port or 
  10676. address and is not connected. 
  10677.  
  10678.     ╤ä User 1 binds socket to a port
  10679.    AΓò£'TCPIP' 'BIND' 3 1023 '0.0.0.0'
  10680.    A
  10681. 0 0 0
  10682.  
  10683. Notice that a zero IP address was specified. If a machine is connected to more 
  10684. than one network (and therefore has more than one IP address), you can bind to 
  10685. a particular network, or specify '0.0.0.0' as the address meaning that you 
  10686. accept a connection to any network. Using '0.0.0.0' as the IP address helps 
  10687. maintain the portability of your application. 
  10688.  
  10689. Port number 1023 is an arbitrary number agreed upon by both users. If the port 
  10690. number is being used by anyone else on the local system, an EADDRINUSE error is 
  10691. returned and the BIND is not successful. 
  10692.  
  10693.     ╤ä User 1 listens for a connection
  10694.    AΓò£'TCPIP' 'LISTEN' 3 5
  10695.    A
  10696. 0 0 0
  10697.  
  10698.    ? User 2 shares a variable with AP 119
  10699.    119 ╨áSVO 'B'
  10700. 1
  10701.    0 0 1 1 ╨áSVC 'B'
  10702. 0 0 1 1
  10703.    ╤ä Allocates a socket
  10704.    BΓò£'TCPIP' 'SOCKET'
  10705.    B
  10706. 0 0 3
  10707.    ╤ä Binds it to user 1's port and address
  10708.    BΓò£'TCPIP' 'BIND' 3  1055 '0.0.0.0'
  10709.    B
  10710. 0 0 0
  10711.  
  10712. Although user 2 also gets socket number 3, this has no relationship with the 
  10713. socket allocated to user 1. 
  10714.  
  10715.     ╤ä User 2 connects to user 1
  10716.    BΓò£'TCPIP' 'CONNECT' 3 1023 '9.113.14.90'
  10717.    B
  10718. 0 0 0
  10719.  
  10720.    ╤ä User 1 accepts the connection
  10721.    AΓò£'TCPIP' 'ACCEPT' 3
  10722.    A
  10723.  0 0  4 1055 9.113.14.90
  10724.  
  10725. When user 1 does an ACCEPT, a new socket is allocated (4 in this case) and the 
  10726. connection is completed using the new socket. The original socket (3 in this 
  10727. case) remains listening for new connections. 
  10728.  
  10729. There is now an established connection between the two users The result from 
  10730. the ACCEPT call has as it's third item the new socket number allocated and user 
  10731. 2's port number and IP address. 
  10732.  
  10733.     ╤ä User 1 sends data to user 2
  10734.    AΓò£'TCPIP' 'SEND' 4 0 'A' 'SOME DATA'
  10735.    A
  10736. 0 0 0
  10737.  
  10738. The A means that ASCII characters are being sent. In this case, specifying type 
  10739. A is the same as type B since both sides are already using ASCII. If the 
  10740. receiving side was EBCDIC-based then type E on the SEND would cause translation 
  10741. to EBCDIC before the data is sent. 
  10742.  
  10743. Note that you can send noncharacter data so long as you and your partner agree 
  10744. on formats. In this case, you should always use the B type option. When the 
  10745. data is received by the partner, it is received as characters and the external 
  10746. function RTA can be used to restore the data to the expected format. 
  10747.  
  10748.     ╤ä User 2 receives the data
  10749.    BΓò£'TCPIP' 'RECV' 3 0 'A'
  10750.    B
  10751.  0 0 SOME DATA
  10752.  
  10753. In this case, all the data was received at once but this may not always be the 
  10754. case. Stream socket protocol does not guarantee that data that was sent is 
  10755. received in one RECV call. It is up to the users to agree on a convention for 
  10756. saying how much data is sent so that the partner can tell when all data has 
  10757. been received. 
  10758.  
  10759.     ╤ä Since a user cannot predict when data
  10760.    ╤ä arrives, it is not known when a
  10761.    ╤ä receive should be done.  User 1 issues
  10762.    ╤ä a SELECT that requests that he be
  10763.    ╤ä informed when data arrives.
  10764.    R_MASKΓò£0 0 0 0 1
  10765.    W_MASKΓò£0 0 0 0 0
  10766.    X_MASKΓò£0 0 0 0 0
  10767.    AΓò£'TCPIP' 'SELECT' 5 R_MASK W_MASK X_MASK
  10768.  
  10769. Because the largest socket is 4, you must specify 5 as the number of of sockets 
  10770. and provide three length 5 masks. The one in the first mask says that user 1 
  10771. wants to be informed when socket 4 is ready to read. You can specify more than 
  10772. one socket by specifying more than one 1. 
  10773.  
  10774. Since RECV is a blocking call, if user 1 now references A, execution stops 
  10775. until data arrives. Alternately user 1 can do other computing. The user can use 
  10776. ╨áSVS 'A' and check for 0 1 0 1 to see if AP 119 has assigned data to the 
  10777. variable. The user can use ╨áSVE to wait for an event on any of his shared 
  10778. variables or until a specified amount of time has passed whichever comes first. 
  10779.  
  10780.     ╤ä User 2 sends some data
  10781.    BΓò£'TCPIP' 'SEND' 3 0 'A' 'DATA BACK TO YOU'
  10782.    B
  10783. 0 0 0
  10784.  
  10785.    ╤ä User 1 notices that data is available
  10786.    ╨áSVS 'A'
  10787. 0 1 0 1
  10788.    A
  10789.  0 0  0 0 0 0 1  0 0 0 0 0  0 0 0 0 0
  10790.  
  10791. The 1 in the read mask means that socket 4 is ready to read. The masks returned 
  10792. from the SELECT may have zero or more 1 bits on but never more than originally 
  10793. specified in the SELECT call. 
  10794.  
  10795.     ╤ä User 1 reads the data
  10796.    AΓò£'TCPIP' 'RECV' 4 0 'A'
  10797.    A
  10798.  0 0 DATA BACK TO YOU
  10799.    ╤ä User 1 closes all his connections
  10800.    AΓò£'TCPIP' 'CLOSE' 4
  10801.    A
  10802. 0 0 0
  10803.    AΓò£'TCPIP' 'CLOSE' 3
  10804.    A
  10805. 0 0 0
  10806.  
  10807.    ╤ä User 2 closes his connection
  10808.    BΓò£'TCPIP' 'CLOSE' 3
  10809.    B
  10810. 0 0 0
  10811.  
  10812.  
  10813. ΓòÉΓòÉΓòÉ 14.4.4. AP 119 Return Codes ΓòÉΓòÉΓòÉ
  10814.  
  10815. Code      Meaning 
  10816.   0 -     Success 
  10817.   1 -     Incorrect command 
  10818.   2 -     Wrong type 
  10819.   3 -     Wrong rank 
  10820.   4 -     Wrong shape 
  10821.   5 -     Item is wrong type 
  10822.   6 -     Item is wrong rank 
  10823.   7 -     Item is wrong shape 
  10824.   8 -     Item data is wrong 
  10825.  11 -     TCP/IP error occurred. Second element of result is TCP/IP return 
  10826.           code. 
  10827.  
  10828.  
  10829. ΓòÉΓòÉΓòÉ 14.5. AP 124-The Text Display Auxiliary Processor ΓòÉΓòÉΓòÉ
  10830.  
  10831. AP 124 enables you to control a window from within an APL2 defined function. It 
  10832. enables your application to: 
  10833.  
  10834. o Write to the formatted screen 
  10835. o Read from the formatted screen 
  10836. o Produce colors, highlighting, reverse video, and so on 
  10837. o Control the keyboard translation 
  10838. o Enter "Inkey" mode to monitor all keyboard activity 
  10839. o Define up to 255 fields 
  10840.  
  10841. o AP 124 Operation 
  10842. o Understanding Screen Management 
  10843. o AP 124 Commands 
  10844. o AP 124 Return Codes 
  10845.  
  10846.  
  10847. ΓòÉΓòÉΓòÉ 14.5.1. AP 124 Operation ΓòÉΓòÉΓòÉ
  10848.  
  10849. AP 124 requires two shared variables: a data variable and a control variable. 
  10850. They can be offered in any order. The name of the data variable must always 
  10851. begin with the letter "D" or the letters "DAT", and the control variable must 
  10852. begin with the letter "C" or the letters "CTL". The remaining characters in 
  10853. both names (possibly none) must be the same, because the coupling of both 
  10854. variables is recognized by their name. Examples of valid pairs are:  C and D, 
  10855. C1 and D1, and CXjj and DXjj. Also accepted as valid pairs (for compatibility 
  10856. with APL2/370) are names such as CTL and DAT or CTL1 and DAT1. The control 
  10857. variable is used to select the operation to perform and to control each 
  10858. input/output operation. For example: 
  10859.  
  10860.       124 SVOPAIR 'C124' 'D124'
  10861. 2 2
  10862.  
  10863. offers variables C124 and D124 to the auxiliary processor. See Using the 
  10864. Share-Offer Utilities for a description of the SVOPAIR function (from the 1 
  10865. UTILITY workspace). 
  10866.  
  10867.  
  10868. ΓòÉΓòÉΓòÉ 14.5.2. Understanding Screen Management ΓòÉΓòÉΓòÉ
  10869.  
  10870. To use the Text Display auxiliary processor, you should understand the screen 
  10871. and its attributes. This section gives an overview of how the auxiliary 
  10872. processor logically views the screen. 
  10873.  
  10874. o AP 124 Usage 
  10875. o Screen Size 
  10876. o Screen Fields 
  10877. o Field Types and Attributes 
  10878.  
  10879.  
  10880. ΓòÉΓòÉΓòÉ 14.5.2.1. AP 124 Usage ΓòÉΓòÉΓòÉ
  10881.  
  10882. In the following, the "physical screen" refers to what is actually displayed in 
  10883. an OS/2 window. The "logical screen" is a buffered image of that window stored 
  10884. in memory. Operations are normally performed on the logical screen. The 
  10885. information stored in the logical screen is transferred to the physical screen 
  10886. (the physical screen is refreshed) by certain calls ("Read and Wait" and 
  10887. "Immediate Write"). 
  10888.  
  10889.  
  10890. ΓòÉΓòÉΓòÉ 14.5.2.2. Screen Size ΓòÉΓòÉΓòÉ
  10891.  
  10892. The physical screen (window) size can be controlled by the application program, 
  10893. by use of an AP 124 command code, and by the application user through standard 
  10894. interactive window resizing techniques supported by the system window manager. 
  10895. The default size of the window at the time of the initial open is 25 by 80. The 
  10896. size of the active window can be queried or set at any time by the application 
  10897. program, by use of command code 14 (see Set Window Attributes). 
  10898.  
  10899.  
  10900. ΓòÉΓòÉΓòÉ 14.5.2.3. Screen Fields ΓòÉΓòÉΓòÉ
  10901.  
  10902. The text display auxiliary processor views the screen in terms of rectangular 
  10903. areas called screen fields. You can enter or display data only in these areas. 
  10904. Each screen field has a starting location, a width, and a height that you 
  10905. define when you format the screen. The starting position of each field is the 
  10906. row and column address of the upper left-hand character in the field. (The 
  10907. upper left-hand position of the screen is row 1 column 1.) 
  10908.  
  10909.  
  10910. ΓòÉΓòÉΓòÉ 14.5.2.4. Field Types and Attributes ΓòÉΓòÉΓòÉ
  10911.  
  10912. Each screen field has associated with it, a field type and a field attribute 
  10913. that qualify its content. For instance, a field type may indicate that a field 
  10914. is to contain alphabetic or numeric data or that user input to the field is to 
  10915. be allowed, and the field attribute may specify that the field is to be 
  10916. displayed as red characters on a white background. 
  10917.  
  10918.  
  10919. ΓòÉΓòÉΓòÉ 14.5.3. AP 124 Commands ΓòÉΓòÉΓòÉ
  10920.  
  10921. The following section describes each AP 124 command in detail. The commands are 
  10922. summarized in Summary of AP 124 Commands. 
  10923.  
  10924. Each time the command-control variable ("C124" in the following examples) is 
  10925. set, AP 124 attempts to perform the requested operation and resets the 
  10926. command-control variable to indicate the degree of success or failure. A value 
  10927. of 0 indicates that the operation was successful; anything else indicates that 
  10928. a problem has been encountered-these values are listed in AP 124 Return Codes. 
  10929.  
  10930. o Clear Screen 
  10931. o Format the Screen into Fields 
  10932. o Reformat the Screen 
  10933. o Push Format Array 
  10934. o Pop Format Array 
  10935. o Immediate Write of Data to Screen 
  10936. o Read and Wait or Read and Test 
  10937. o Delayed Write of Data to Screen 
  10938. o Get Data from the Logical Screen (as a Matrix) 
  10939. o Update Field Types 
  10940. o Update Field Attributes 
  10941. o Control and Information Request 
  10942. o Get Format Table 
  10943. o Get the Current Logical Screen 
  10944. o Sound a Beep to Alert User 
  10945. o Set the Cursor 
  10946. o Set Window Attributes 
  10947. o Query Window Attributes 
  10948. o Get Data from the Logical Screen (as a Vector) 
  10949. o Get Field Attributes 
  10950. o Clear Screen (VS APL Compatible) 
  10951. o Set Title Bar Text 
  10952.  
  10953.  
  10954. ΓòÉΓòÉΓòÉ 14.5.3.1. Clear Screen ΓòÉΓòÉΓòÉ
  10955.  
  10956. Syntax: 
  10957.  
  10958. C124Γò£0 
  10959.  
  10960. This request clears both the physical screen and the logical field contents on 
  10961. the next operation requiring a screen update. 
  10962.  
  10963.  
  10964. ΓòÉΓòÉΓòÉ 14.5.3.2. Format the Screen into Fields ΓòÉΓòÉΓòÉ
  10965.  
  10966. Syntax: 
  10967.  
  10968. D124Γò£numeric_format_array 
  10969. C124Γò£1 
  10970.  
  10971. This call permits you to divide your logical screen into rectangular "fields". 
  10972. Each field is defined in terms of its offset from the top left-hand corner of 
  10973. the screen, its depth, and its width. You can also indicate whether the field 
  10974. is output only or input/output; and its display "attribute". 
  10975.  
  10976. numeric_format_array is a four-, five-, or six-column numeric matrix with one 
  10977. row for each field to be formatted. If only one field is to be formatted, a 
  10978. numeric vector can be passed, and is treated as a one row matrix. The first or 
  10979. only row of the matrix defines the first field, the second row defines the 
  10980. second field, and so on. 
  10981.  
  10982. The first four elements of each row of the matrix (assigned to D124) are 
  10983. defined as: 
  10984.  
  10985.  1. Start row of the field 
  10986.  
  10987.  2. Start column of the field 
  10988.  
  10989.  3. Field height 
  10990.  
  10991.  4. Field width 
  10992.  
  10993.     The fifth and sixth elements of each row of the matrix are optional and are 
  10994.     defined as: 
  10995.  
  10996.  5. Field type: 
  10997.  
  10998.    0 -    Input/output/selectable 
  10999.    1 -    Numeric input only/any output/selectable 
  11000.    2 -    Output only (the default) 
  11001.    3 -    Output only/selectable 
  11002.  
  11003.     See the description of the call to Set the Cursor for the meaning of the 
  11004.     "selectable" attribute. 
  11005.  
  11006.  6. Field attribute: An integer between 0 and 255. The default field attribute 
  11007.     is 1, which normally gives blue characters on a black background. The 
  11008.     following diagram shows the meanings of the bits of the display attribute 
  11009.     byte on color display adapters: 
  11010.  
  11011.         7   6   5   4   3   2   1   0
  11012.         ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ   ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  11013.               Γöé               Γöé
  11014.               Γöé               ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ Foreground color (4 bits)
  11015.               Γöé
  11016.               ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ Background color (4 bits)
  11017.  
  11018.     See AP 124 colors for the combinations of colors available. 
  11019.  
  11020. The format request clears any previously defined fields and establishes a new 
  11021. screen definition with one field for each row of the format array given in 
  11022. D124. These fields are given field numbers, starting from one, corresponding to 
  11023. the row number of the field in the format array. These field numbers are used 
  11024. to identify each individual field in subsequent calls to AP 124. 
  11025.  
  11026. Example: 
  11027.  
  11028.   D124Γò£1 6╤å10 5 1 6 0 7
  11029.   C124Γò£1
  11030.  
  11031. defines a field in the tenth row, fifth column, one high, six wide. The field 
  11032. has a type of input/output/selectable (0) and the attribute (7) specifies gray 
  11033. characters on a black background. 
  11034.  
  11035. Notes: 
  11036.  
  11037.  1. A row in the format array can be all zeros. This can be used as a place 
  11038.     holder, and the corresponding field can be defined later with a reformat 
  11039.     screen request (C124Γò£1,Field_number(s)) as described below. 
  11040.  
  11041.  2. Initially, the display screen contains only one field that covers the 
  11042.     entire screen area. 
  11043.  
  11044.  
  11045. ΓòÉΓòÉΓòÉ 14.5.3.2.1. AP 124 colors ΓòÉΓòÉΓòÉ
  11046.  
  11047.  
  11048. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11049.  
  11050. Code 
  11051.  
  11052.  
  11053. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11054.  
  11055. Bits 
  11056.  
  11057.  
  11058. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11059.  
  11060. Color 
  11061.  
  11062.  
  11063. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11064.  
  11065.  
  11066. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11067.  
  11068. Code 
  11069.  
  11070.  
  11071. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11072.  
  11073. Bits 
  11074.  
  11075.  
  11076. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11077.  
  11078. Color 
  11079.  
  11080.  
  11081. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11082.  
  11083.  
  11084.  
  11085. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11086.  
  11087. 0 0 0 0 
  11088.  
  11089.  
  11090. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11091.  
  11092. Black 
  11093.  
  11094.  
  11095. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11096.  
  11097.  
  11098. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11099.  
  11100.  
  11101.  
  11102. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11103.  
  11104. 1 0 0 0 
  11105.  
  11106.  
  11107. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11108.  
  11109. Light Gray 
  11110.  
  11111.  
  11112. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11113.  
  11114.  
  11115.  
  11116. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11117.  
  11118. 0 0 0 1 
  11119.  
  11120.  
  11121. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11122.  
  11123. Blue 
  11124.  
  11125.  
  11126. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11127.  
  11128.  
  11129. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11130.  
  11131.  
  11132.  
  11133. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11134.  
  11135. 1 0 0 1 
  11136.  
  11137.  
  11138. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11139.  
  11140. Light Blue 
  11141.  
  11142.  
  11143. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11144.  
  11145.  
  11146.  
  11147. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11148.  
  11149. 0 0 1 0 
  11150.  
  11151.  
  11152. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11153.  
  11154. Green 
  11155.  
  11156.  
  11157. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11158.  
  11159.  
  11160. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11161.  
  11162. 10 
  11163.  
  11164.  
  11165. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11166.  
  11167. 1 0 1 0 
  11168.  
  11169.  
  11170. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11171.  
  11172. Light Green 
  11173.  
  11174.  
  11175. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11176.  
  11177.  
  11178.  
  11179. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11180.  
  11181. 0 0 1 1 
  11182.  
  11183.  
  11184. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11185.  
  11186. Cyan 
  11187.  
  11188.  
  11189. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11190.  
  11191.  
  11192. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11193.  
  11194. 11 
  11195.  
  11196.  
  11197. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11198.  
  11199. 1 0 1 1 
  11200.  
  11201.  
  11202. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11203.  
  11204. Light Cyan 
  11205.  
  11206.  
  11207. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11208.  
  11209.  
  11210.  
  11211. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11212.  
  11213. 0 1 0 0 
  11214.  
  11215.  
  11216. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11217.  
  11218. Red 
  11219.  
  11220.  
  11221. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11222.  
  11223.  
  11224. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11225.  
  11226. 12 
  11227.  
  11228.  
  11229. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11230.  
  11231. 1 1 0 0 
  11232.  
  11233.  
  11234. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11235.  
  11236. Light Red 
  11237.  
  11238.  
  11239. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11240.  
  11241.  
  11242.  
  11243. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11244.  
  11245. 0 1 0 1 
  11246.  
  11247.  
  11248. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11249.  
  11250. Magenta 
  11251.  
  11252.  
  11253. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11254.  
  11255.  
  11256. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11257.  
  11258. 13 
  11259.  
  11260.  
  11261. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11262.  
  11263. 1 1 0 1 
  11264.  
  11265.  
  11266. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11267.  
  11268. Light Magenta 
  11269.  
  11270.  
  11271. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11272.  
  11273.  
  11274.  
  11275. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11276.  
  11277. 0 1 1 0 
  11278.  
  11279.  
  11280. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11281.  
  11282. Yellow 
  11283.  
  11284.  
  11285. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11286.  
  11287.  
  11288. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11289.  
  11290. 14 
  11291.  
  11292.  
  11293. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11294.  
  11295. 1 1 1 0 
  11296.  
  11297.  
  11298. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11299.  
  11300. Brown 
  11301.  
  11302.  
  11303. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11304.  
  11305.  
  11306.  
  11307. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11308.  
  11309. 0 1 1 1 
  11310.  
  11311.  
  11312. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11313.  
  11314. Gray 
  11315.  
  11316.  
  11317. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11318.  
  11319.  
  11320. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11321.  
  11322. 15 
  11323.  
  11324.  
  11325. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11326.  
  11327. 1 1 1 1 
  11328.  
  11329.  
  11330. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11331.  
  11332. White 
  11333.  
  11334.  
  11335. ΓòÉΓòÉΓòÉ 14.5.3.3. Reformat the Screen ΓòÉΓòÉΓòÉ
  11336.  
  11337. Syntax: 
  11338.  
  11339. D124Γò£numeric_format_array 
  11340. C124Γò£1,Field_number(s) 
  11341.  
  11342. The reformat screen request modifies one or more existing field definitions. 
  11343. The number of rows given in the format array (D124) must be the same as the 
  11344. number of Field_number(s) given in the control variable (C124). 
  11345.  
  11346. numeric_format_array is a four-, five-, or six-column numeric matrix with one 
  11347. row for each field to be formatted. 
  11348.  
  11349.  
  11350. ΓòÉΓòÉΓòÉ 14.5.3.4. Push Format Array ΓòÉΓòÉΓòÉ
  11351.  
  11352. Syntax: 
  11353.  
  11354. D124Γò£numeric_format_array 
  11355. C124Γò£1 ┬ñ1 
  11356.  
  11357. The push current format array request saves the current screen format and data 
  11358. on a last-in first-out (LIFO) stack. Any areas of the screen not defined in the 
  11359. new format array retain their previous contents. 
  11360.  
  11361. numeric_format_array is a four-, five-, or six-column numeric matrix with one 
  11362. row for each field to be formatted. 
  11363.  
  11364.  
  11365. ΓòÉΓòÉΓòÉ 14.5.3.5. Pop Format Array ΓòÉΓòÉΓòÉ
  11366.  
  11367. Syntax: 
  11368.  
  11369. C124Γò£1 ┬ñ2   -Pop last pushed format array 
  11370. C124Γò£1 ┬ñ2,n  -Pop last n format arrays 
  11371.  
  11372. The pop format array request restores the last saved format and screen data 
  11373. from the stack. If n is specified, this process is repeated n times. If the 
  11374. stack is empty, the current format and data are retained and no error is given. 
  11375.  
  11376.  
  11377. ΓòÉΓòÉΓòÉ 14.5.3.6. Immediate Write of Data to Screen ΓòÉΓòÉΓòÉ
  11378.  
  11379. Syntax: 
  11380.  
  11381. D124Γò£array_of_character_data 
  11382. C124Γò£2,Field_number(s) 
  11383.  
  11384. This call permits you to write data to the logical screen, which is then 
  11385. immediately transferred to the physical screen. 
  11386.  
  11387. The array can be either a matrix with one row for each field listed, or a 
  11388. vector of character vectors with one vector for each field listed. If a field 
  11389. has a height of more than 1, the data to be written to the field must be 
  11390. ravelled to form the corresponding row or vector of D124. If however, a single 
  11391. field is being updated, the data can be passed either as a character matrix or 
  11392. ravelled to form a character vector. 
  11393.  
  11394.  
  11395. ΓòÉΓòÉΓòÉ 14.5.3.7. Read and Wait or Read and Test ΓòÉΓòÉΓòÉ
  11396.  
  11397. In normal operation, the physical screen is refreshed. Then, either the 
  11398. auxiliary processor waits for a certain key to be pressed, or it returns to 
  11399. APL2 with information on whether a key was pressed. 
  11400.  
  11401. Syntax    Description 
  11402. C124Γò£3 
  11403. C124Γò£3 0  Allow interactive input and return to APL2 when a special key is 
  11404.           pressed. (See table below for D124 key codes.) Assigning the control 
  11405.           variable a scalar value of 3, or the two element vector 3 0, are 
  11406.           completely equivalent. 
  11407. C124Γò£3 1  Return to APL2 when any key is pressed. 
  11408. C124Γò£3 2  Test for a key pressed, and return immediately. 
  11409. C124Γò£3 3  Return to APL2 when any key except a cursor movement key is pressed. 
  11410.           ("Semi-inkey" mode.) 
  11411. C124Γò£3 4  Test for a key pressed, and return immediately. If a normal 
  11412.           (non-special) key has been pressed, it will be echoed to the display, 
  11413.           and the field containing it will be marked as having been updated. 
  11414.  
  11415. If any of the above calls has three elements, this instructs the auxiliary 
  11416. processor not to refresh the physical screen. (The value of the third element 
  11417. is ignored.) 
  11418.  
  11419. After the return code is checked in C124, the D124 variable contains a vector 
  11420. of five or more elements. They are: 
  11421.  
  11422. D124[1 2]       For calls 3, (3 0), and (3 4), a code indicating the special 
  11423.                 key pressed to return to APL. For calls (3 1), (3 2), and (3 
  11424.                 3), the character code and extended function code returned by 
  11425.                 the APL2/2 keyboard routine. For call (3 2), if no key has been 
  11426.                 pressed, return is (┬ñ1 ┬ñ1). Similarly, for call (3 4), if no 
  11427.                 special key has been pressed, return is (┬ñ1 ┬ñ1). 
  11428.  
  11429. D124[3]         Field number where the cursor was located at return to APL2, or 
  11430.                 0 if the cursor was not in a defined field. 
  11431.  
  11432. D124[4 5]       Cursor position (row,column) within that defined field. If 
  11433.                 field number is 0, these elements give the offset from top-left 
  11434.                 of the logical screen. Positions are given in origin one, for 
  11435.                 example, 1 1 specifies the top-left corner of the field. 
  11436.  
  11437. D124[6...]      List of fields updated during this call. 
  11438.  
  11439. AP124 Special Keys and Key Return Codes lists codes returned for the 3, (3 0), 
  11440. and (3 4) cases: 
  11441.  
  11442. While AP 124 is in the (3 0) "Read and Wait" state, you can type on the screen. 
  11443. The cursor movement keys can be used in the normal way. Three other keys have 
  11444. special functions: 
  11445.  
  11446. Ctrl-Backspace  Toggles the keyboard between APL2 and national modes. 
  11447.  
  11448. Ctrl-End        Clears to the end of the field. However, if the field has less 
  11449.                 than 80 columns, only the current line is cleared to its end. 
  11450.  
  11451. Ctrl-Home       Clears from the cursor to the start of the field. However, if 
  11452.                 the field has less than 80 columns, only the current line is 
  11453.                 cleared to its beginning. 
  11454.  
  11455. AP 124 Extended Function Codes shows the extended function codes returned in 
  11456. D124[2] for commands: (3 1), (3 2), and (3 3). D124[1] is set to 0 when these 
  11457. extended function codes are returned. If D124[2] is 0, then D124[1] is the 
  11458. 0-origin ╨áAV index of the character corresponding to the key pressed. 
  11459.  
  11460.  
  11461. ΓòÉΓòÉΓòÉ 14.5.3.7.1. AP124 Special Keys and Key Return Codes ΓòÉΓòÉΓòÉ
  11462.  
  11463.  
  11464. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11465.  
  11466. Code 
  11467.  
  11468.  
  11469. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11470.  
  11471. Description 
  11472.  
  11473.  
  11474. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11475.  
  11476. 0 0 
  11477.  
  11478.  
  11479. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11480.  
  11481. Enter (New-line key) 
  11482.  
  11483.  
  11484. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11485.  
  11486. 1,N 
  11487.  
  11488.  
  11489. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11490.  
  11491. F-key (Where "N" (1╤öN╤ö48) is the number of the key that was depressed. 1-12: 
  11492. normal F-keys; 13-24: F-keys in shift mode; 25-36: F-keys in Ctrl mode; 37-48 
  11493. F-keys in Alt mode) 
  11494.  
  11495.  
  11496. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11497.  
  11498. 4 1 
  11499.  
  11500.  
  11501. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11502.  
  11503. Esc 
  11504.  
  11505.  
  11506. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11507.  
  11508. 6 1 
  11509.  
  11510.  
  11511. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11512.  
  11513. Home 
  11514.  
  11515.  
  11516. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11517.  
  11518. 6 2 
  11519.  
  11520.  
  11521. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11522.  
  11523. End 
  11524.  
  11525.  
  11526. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11527.  
  11528. 6 3 
  11529.  
  11530.  
  11531. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11532.  
  11533. PageUp 
  11534.  
  11535.  
  11536. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11537.  
  11538. 6 4 
  11539.  
  11540.  
  11541. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11542.  
  11543. PageDown 
  11544.  
  11545.  
  11546. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11547.  
  11548. 6 5 
  11549.  
  11550.  
  11551. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11552.  
  11553. Ctrl-PageUp 
  11554.  
  11555.  
  11556. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11557.  
  11558. 6 6 
  11559.  
  11560.  
  11561. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11562.  
  11563. Ctrl-PageDown 
  11564.  
  11565.  
  11566. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11567.  
  11568. 6 7 
  11569.  
  11570.  
  11571. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11572.  
  11573. Ctrl-Left 
  11574.  
  11575.  
  11576. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11577.  
  11578. 6 8 
  11579.  
  11580.  
  11581. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11582.  
  11583. Ctrl-Right 
  11584.  
  11585.  
  11586. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11587.  
  11588. 6 9 
  11589.  
  11590.  
  11591. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11592.  
  11593. Ctrl-Up 
  11594.  
  11595.  
  11596. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11597.  
  11598. 6 10 
  11599.  
  11600.  
  11601. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11602.  
  11603. Ctrl-Down 
  11604.  
  11605.  
  11606. ΓòÉΓòÉΓòÉ 14.5.3.7.2. AP 124 Extended Function Codes - Part 1 ΓòÉΓòÉΓòÉ
  11607.  
  11608.  
  11609. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11610.  
  11611. Code 
  11612.  
  11613.  
  11614. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11615.  
  11616. Description 
  11617.  
  11618.  
  11619. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11620.  
  11621.  
  11622.  
  11623. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11624.  
  11625. Ctrl-Break or Ctrl-Backspace 
  11626.  
  11627.  
  11628. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11629.  
  11630.  
  11631.  
  11632. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11633.  
  11634. Null character 
  11635.  
  11636.  
  11637. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11638.  
  11639. 15 
  11640.  
  11641.  
  11642. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11643.  
  11644. Shift-Tab 
  11645.  
  11646.  
  11647. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11648.  
  11649. 16-25 
  11650.  
  11651.  
  11652. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11653.  
  11654. Alt-q, w, e, r, t, y, u, i, o, p (national keyboard only) 
  11655.  
  11656.  
  11657. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11658.  
  11659. 30-38 
  11660.  
  11661.  
  11662. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11663.  
  11664. Alt-a, s, d, f, g, h, j, k, l (national keyboard only) 
  11665.  
  11666.  
  11667. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11668.  
  11669. 44-50 
  11670.  
  11671.  
  11672. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11673.  
  11674. Alt-z, x, c, v, b, n, m (national keyboard only) 
  11675.  
  11676.  
  11677. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11678.  
  11679. 59-68 
  11680.  
  11681.  
  11682. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11683.  
  11684. Function keys 1-10 
  11685.  
  11686.  
  11687. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11688.  
  11689. 71 
  11690.  
  11691.  
  11692. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11693.  
  11694. Home 
  11695.  
  11696.  
  11697. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11698.  
  11699. 72,73 
  11700.  
  11701.  
  11702. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11703.  
  11704. Cursor Up, PageUp 
  11705.  
  11706.  
  11707. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11708.  
  11709. 75,77 
  11710.  
  11711.  
  11712. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11713.  
  11714. Cursor Left, Right 
  11715.  
  11716.  
  11717. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11718.  
  11719. 79 
  11720.  
  11721.  
  11722. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11723.  
  11724. End 
  11725.  
  11726.  
  11727. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11728.  
  11729. 80,81 
  11730.  
  11731.  
  11732. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11733.  
  11734. Cursor Down, PageDown 
  11735.  
  11736.  
  11737. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11738.  
  11739. 82,83 
  11740.  
  11741.  
  11742. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11743.  
  11744. Insert, Delete 
  11745.  
  11746.  
  11747. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11748.  
  11749. 84-93 
  11750.  
  11751.  
  11752. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11753.  
  11754. Shift-Function keys 1-10 
  11755.  
  11756.  
  11757. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11758.  
  11759. 94-103 
  11760.  
  11761.  
  11762. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11763.  
  11764. Ctrl-Function keys 1-10 
  11765.  
  11766.  
  11767. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11768.  
  11769. MORE... 
  11770.  
  11771.  
  11772. ΓòÉΓòÉΓòÉ 14.5.3.7.3. AP 124 Extended Function Codes - Part 2 ΓòÉΓòÉΓòÉ
  11773.  
  11774.  
  11775. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11776.  
  11777. Code 
  11778.  
  11779.  
  11780. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11781.  
  11782. Description 
  11783.  
  11784.  
  11785. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11786.  
  11787. 104-113 
  11788.  
  11789.  
  11790. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11791.  
  11792. Alt-Function keys 1-10 
  11793.  
  11794.  
  11795. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11796.  
  11797. 114 
  11798.  
  11799.  
  11800. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11801.  
  11802. Ctrl-PrintScreen 
  11803.  
  11804.  
  11805. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11806.  
  11807. 115,116 
  11808.  
  11809.  
  11810. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11811.  
  11812. Ctrl-Cursor Left, Right 
  11813.  
  11814.  
  11815. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11816.  
  11817. 117,118 
  11818.  
  11819.  
  11820. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11821.  
  11822. Ctrl-End, Ctrl-PageDown 
  11823.  
  11824.  
  11825. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11826.  
  11827. 119 
  11828.  
  11829.  
  11830. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11831.  
  11832. Ctrl-Home 
  11833.  
  11834.  
  11835. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11836.  
  11837. 120-131 
  11838.  
  11839.  
  11840. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11841.  
  11842. Alt-1, 2, 3, 4, 5, 6, 7, 8, 9, 0, -, = (national keyboard only) 
  11843.  
  11844.  
  11845. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11846.  
  11847. 132 
  11848.  
  11849.  
  11850. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11851.  
  11852. Ctrl-PageUp 
  11853.  
  11854.  
  11855. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11856.  
  11857. 133,134 
  11858.  
  11859.  
  11860. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11861.  
  11862. Function keys 11, 12 
  11863.  
  11864.  
  11865. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11866.  
  11867. 135,136 
  11868.  
  11869.  
  11870. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11871.  
  11872. Shift-Function keys 11, 12 
  11873.  
  11874.  
  11875. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11876.  
  11877. 137,138 
  11878.  
  11879.  
  11880. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11881.  
  11882. Ctrl-Function keys 11, 12 
  11883.  
  11884.  
  11885. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11886.  
  11887. 139,140 
  11888.  
  11889.  
  11890. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11891.  
  11892. Alt-Function keys 11, 12 
  11893.  
  11894.  
  11895. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11896.  
  11897. 141,142 
  11898.  
  11899.  
  11900. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11901.  
  11902. Ctrl-Cursor Up, Ctrl-Keypad - 
  11903.  
  11904.  
  11905. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11906.  
  11907. 143,144 
  11908.  
  11909.  
  11910. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11911.  
  11912. Ctrl-Enter, Ctrl-Keypad + 
  11913.  
  11914.  
  11915. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11916.  
  11917. 145,146 
  11918.  
  11919.  
  11920. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11921.  
  11922. Ctrl-Cursor Down, Ctrl-Insert 
  11923.  
  11924.  
  11925. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11926.  
  11927. 147,148 
  11928.  
  11929.  
  11930. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11931.  
  11932. Ctrl-Delete, Ctrl-Tab 
  11933.  
  11934.  
  11935. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11936.  
  11937. MORE... 
  11938.  
  11939.  
  11940. ΓòÉΓòÉΓòÉ 14.5.3.7.4. AP 124 Extended Function Codes - Part 3 ΓòÉΓòÉΓòÉ
  11941.  
  11942.  
  11943. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11944.  
  11945. Code 
  11946.  
  11947.  
  11948. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11949.  
  11950. Description 
  11951.  
  11952.  
  11953. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11954.  
  11955. 149,150 
  11956.  
  11957.  
  11958. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11959.  
  11960. Ctrl-Keypad /, Ctrl-Keypad * 
  11961.  
  11962.  
  11963. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11964.  
  11965. 151,152 
  11966.  
  11967.  
  11968. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11969.  
  11970. Alt-Home, Alt-Cursor Up 
  11971.  
  11972.  
  11973. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11974.  
  11975. 153 
  11976.  
  11977.  
  11978. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11979.  
  11980. Alt-PageUp 
  11981.  
  11982.  
  11983. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11984.  
  11985. 155,157 
  11986.  
  11987.  
  11988. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11989.  
  11990. Alt-Cursor Left, Right 
  11991.  
  11992.  
  11993. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11994.  
  11995. 159,160 
  11996.  
  11997.  
  11998. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  11999.  
  12000. Alt-End, Alt-Cursor Down 
  12001.  
  12002.  
  12003. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12004.  
  12005. 161 
  12006.  
  12007.  
  12008. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12009.  
  12010. Alt-PageDown 
  12011.  
  12012.  
  12013. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12014.  
  12015. 162,163 
  12016.  
  12017.  
  12018. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12019.  
  12020. Alt-Insert, Alt-Delete 
  12021.  
  12022.  
  12023. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12024.  
  12025. 164,165 
  12026.  
  12027.  
  12028. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12029.  
  12030. Alt-Keypad /, Alt-Tab 
  12031.  
  12032.  
  12033. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12034.  
  12035. 166 
  12036.  
  12037.  
  12038. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12039.  
  12040. Alt-Enter 
  12041.  
  12042.  
  12043. ΓòÉΓòÉΓòÉ 14.5.3.8. Delayed Write of Data to Screen ΓòÉΓòÉΓòÉ
  12044.  
  12045. Syntax: 
  12046.  
  12047. D124Γò£array_of_character_data 
  12048. C124Γò£4,Field_number(s) 
  12049.  
  12050. This call permits you to write data to the logical screen, which is displayed 
  12051. at the next refresh of the physical screen. 
  12052.  
  12053. In all other respects, this service is identical to the immediate write service 
  12054. (see Immediate Write of Data to Screen). 
  12055.  
  12056.  
  12057. ΓòÉΓòÉΓòÉ 14.5.3.9. Get Data from the Logical Screen (as a Matrix) ΓòÉΓòÉΓòÉ
  12058.  
  12059. Syntax: 
  12060.  
  12061. C124Γò£5,Field_number(s) 
  12062.  
  12063. Returns a matrix with one row for each data field requested. If a field 
  12064. contains more than one row, its data is raveled into a single row of the 
  12065. matrix. If multiple fields are requested, the data from each is padded to the 
  12066. length of the longest. 
  12067.  
  12068. Return: D124 is a character array with as many rows as the number of fields 
  12069. requested, and as many columns as the maximum field length (field length is the 
  12070. total number of characters in a field). 
  12071.  
  12072. This call enables you to read data from the logical screen. 
  12073.  
  12074.  
  12075. ΓòÉΓòÉΓòÉ 14.5.3.10. Update Field Types ΓòÉΓòÉΓòÉ
  12076.  
  12077. Syntax: 
  12078.  
  12079. D124Γò£New_field_type(s) 
  12080. C124Γò£6,Field_number(s) 
  12081.  
  12082. where each item of New_field_type is a number: 
  12083.  
  12084. 0 - Field is input/output (selectable) 
  12085. 1 - Field is numeric input only/any output (selectable) 
  12086. 2 - Field is output only (nonselectable) 
  12087. 3 - Field is output only (selectable) 
  12088. See the description of the call to Set the Cursor for the meaning of the 
  12089. "selectable" attribute. 
  12090.  
  12091. This call updates column five of the format array previously specified for the 
  12092. indicated fields. 
  12093.  
  12094.  
  12095. ΓòÉΓòÉΓòÉ 14.5.3.11. Update Field Attributes ΓòÉΓòÉΓòÉ
  12096.  
  12097. Syntax: 
  12098.  
  12099. D124Γò£Attribute(s) 
  12100. C124Γò£7,Field_number(s) 
  12101.  
  12102. Each item of Attribute is an integer from 0 to 255 as defined in Format the 
  12103. Screen into Fields. 
  12104.  
  12105. It is also possible to define the attributes for each character position of a 
  12106. field. To do this, the D124 variable is set to a vector of attributes, and only 
  12107. a single Field_number is specified. A value of ┬ñ1 in the vector of attributes 
  12108. specifies that this character position is to use the currently-defined field 
  12109. attribute. 
  12110.  
  12111.  
  12112. ΓòÉΓòÉΓòÉ 14.5.3.12. Control and Information Request ΓòÉΓòÉΓòÉ
  12113.  
  12114. Syntax: 
  12115.  
  12116. C124Γò£8   - Set to APL2 keyboard 
  12117. C124Γò£8 0 - Set to APL2 keyboard (same as C124Γò£8) 
  12118. C124Γò£8 1 - Set to national keyboard 
  12119. C124Γò£8 2 - Return status 
  12120.  
  12121. Returns in D124: 
  12122.  
  12123. D124[1] - Keyboard in APL2 mode 
  12124. D124[2] - Reserved (always 0) 
  12125. D124[3] - Reserved (always 1) 
  12126. D124[4] - Beep request pending 
  12127. D124[5] - Reserved (always 0) 
  12128. D124[6] - Cursor mode (0 = normal, 1 = field) 
  12129.  
  12130.  
  12131. ΓòÉΓòÉΓòÉ 14.5.3.13. Get Format Table ΓòÉΓòÉΓòÉ
  12132.  
  12133. Syntax: 
  12134.  
  12135. C124Γò£9 
  12136.  
  12137. Return:  D124 is a n by 6 numeric matrix, where n is the current number of 
  12138. fields defined. 
  12139.  
  12140. This call returns the current format array stored by AP 124. 
  12141.  
  12142. If no format array currently exists then D124 is set to: 
  12143.  
  12144. 1 1, No_of_rows, No_of_columns, 2 1 
  12145.  
  12146. This feature can be used to determine the number of rows and columns that the 
  12147. window is capable of displaying. Note, however, that this is a dummy field that 
  12148. may not be used and a new format array must be defined before any input or 
  12149. output can be performed. (This is incompatible with the host VS APL version of 
  12150. AP 124 that allowed the initial default field to be used for output.) 
  12151.  
  12152.  
  12153. ΓòÉΓòÉΓòÉ 14.5.3.14. Get the Current Logical Screen ΓòÉΓòÉΓòÉ
  12154.  
  12155. Syntax: 
  12156.  
  12157. C124Γò£10 1 - Return logical screen as a character matrix in the D124 variable 
  12158.  
  12159.  
  12160. ΓòÉΓòÉΓòÉ 14.5.3.15. Sound a Beep to Alert User ΓòÉΓòÉΓòÉ
  12161.  
  12162. Syntax: 
  12163.  
  12164. C124Γò£11   - Delayed Beep 
  12165.  
  12166. C124Γò£11 0 - Delayed Beep (Same as C124Γò£11) 
  12167.  
  12168. C124Γò£11 1 - Immediate Beep 
  12169.  
  12170. C124Γò£11 2 - Cancel previous delayed Beep 
  12171.  
  12172. If the beep is delayed, it occurs at the next "Read and Wait" or "Read and 
  12173. Test" operation. To find out whether a beep is pending, specify call 8 2 and 
  12174. examine the fourth element. 
  12175.  
  12176.  
  12177. ΓòÉΓòÉΓòÉ 14.5.3.16. Set the Cursor ΓòÉΓòÉΓòÉ
  12178.  
  12179. Syntax: 
  12180.  
  12181. D124Γò£Field_no, Row_offset, Column_offset 
  12182. C124Γò£12 
  12183.  
  12184. Sets the cursor to a specific screen location. Field_no is the number of a 
  12185. defined field. If it is zero, then row and column are considered as coordinates 
  12186. from the top left corner of the screen. D124 must be a three element numeric 
  12187. vector. Positions are given in origin one, for example, 1 1 specifies the 
  12188. top-left corner of the field. 
  12189.  
  12190. C124Γò£12 0 
  12191.  
  12192. Sets cursor type to normal (the default). 
  12193.  
  12194. C124Γò£12 1 
  12195.  
  12196. Sets cursor type to field. Any fields with a field type that is "selectable" 
  12197. (field types 0, 1 or 3) are displayed in reverse video whenever the cursor is 
  12198. situated within the field. 
  12199.  
  12200.  
  12201. ΓòÉΓòÉΓòÉ 14.5.3.17. Set Window Attributes ΓòÉΓòÉΓòÉ
  12202.  
  12203. The following section describes the syntax for setting window attributes. 
  12204.  
  12205. o Set Background Color 
  12206. o Set Window Size and Placement 
  12207.  
  12208.  
  12209. ΓòÉΓòÉΓòÉ 14.5.3.17.1. Set Background Color ΓòÉΓòÉΓòÉ
  12210.  
  12211.  
  12212. Syntax: 
  12213.  
  12214. C124Γò£14,color 
  12215.  
  12216. Sets the screen background (all areas of the window not currently defined by 
  12217. any field in the format array during the previous "reformat screen" operation) 
  12218. to the color specified. For example: 
  12219.  
  12220. C124Γò£14 16 
  12221.  
  12222. Sets the background to blue. 
  12223.  
  12224.  
  12225. ΓòÉΓòÉΓòÉ 14.5.3.17.2. Set Window Size and Placement ΓòÉΓòÉΓòÉ
  12226.  
  12227.  
  12228. Syntax: 
  12229.  
  12230. C124Γò£14,row,column,height,width 
  12231.  
  12232. Requests the window size and placement, through standard negotiation with the 
  12233. window manager. Logical fields defined totally outside the window are not 
  12234. displayed, and fields that exceed the window boundaries are clipped. Any 
  12235. parameter can be specified with a value of ┬ñ1 to request default handling. The 
  12236. row and column positions are 0-origin offsets from the top left corner of the 
  12237. Desktop window. 
  12238.  
  12239.  
  12240. ΓòÉΓòÉΓòÉ 14.5.3.18. Query Window Attributes ΓòÉΓòÉΓòÉ
  12241.  
  12242. Syntax: 
  12243.  
  12244. C124Γò£14 
  12245.  
  12246. Returns a 5-element integer vector in D124: 
  12247.  
  12248. background_color, row, column, height, width 
  12249.  
  12250.  
  12251. ΓòÉΓòÉΓòÉ 14.5.3.19. Get Data from the Logical Screen (as a Vector) ΓòÉΓòÉΓòÉ
  12252.  
  12253. Syntax: 
  12254.  
  12255. C124Γò£15,Field_number(s) 
  12256.  
  12257. Returns a matrix with one row for each data field requested. If a field 
  12258. contains more than one row, its data is raveled into a single row of the 
  12259. matrix. If multiple fields are requested, the data from each is padded to the 
  12260. length of the longest. 
  12261.  
  12262. Return: D124 is a character array with as many rows as the number of fields 
  12263. requested, and as many columns as the maximum field length (field length is the 
  12264. total number of characters in a field). 
  12265.  
  12266. This call enables you to read data from the logical screen. 
  12267.  
  12268.  
  12269. ΓòÉΓòÉΓòÉ 14.5.3.20. Get Field Attributes ΓòÉΓòÉΓòÉ
  12270.  
  12271. Syntax: 
  12272.  
  12273. C124Γò£17,Field_number(s) 
  12274.  
  12275. Returns in D124, a character matrix (one row for each Field_number specified) 
  12276. containing the attribute character for each character position of the field. 
  12277. The ╨áAV system variable can be used to convert these attribute characters to 
  12278. the equivalent attribute integers. 
  12279.  
  12280.  
  12281. ΓòÉΓòÉΓòÉ 14.5.3.21. Clear Screen (VS APL Compatible) ΓòÉΓòÉΓòÉ
  12282.  
  12283. Syntax: 
  12284.  
  12285. C124Γò£20 
  12286.  
  12287. This is the same as call 0, and is provided purely for compatibility with the 
  12288. VS APL AP 124. 
  12289.  
  12290.  
  12291. ΓòÉΓòÉΓòÉ 14.5.3.22. Set Title Bar Text ΓòÉΓòÉΓòÉ
  12292.  
  12293. Syntax: 
  12294.  
  12295. D124Γò£'text' 
  12296. C124Γò£21 1 
  12297.  
  12298. Sets the title bar of the AP 124 window to the specified text. 
  12299.  
  12300.  
  12301. ΓòÉΓòÉΓòÉ 14.5.3.22.1. Summary of AP 124 Commands - Part 1 ΓòÉΓòÉΓòÉ
  12302.  
  12303.  
  12304. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12305.  
  12306. Operation 
  12307.  
  12308.  
  12309. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12310.  
  12311. Control Variable 
  12312.  
  12313.  
  12314. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12315.  
  12316. Data Variable 
  12317.  
  12318.  
  12319. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12320.  
  12321. Response in Data Variable 
  12322.  
  12323.  
  12324. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12325.  
  12326.  Clear screen 
  12327.  
  12328.  
  12329. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12330.  
  12331.  0 
  12332.  
  12333.  
  12334. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12335.  
  12336.  
  12337. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12338.  
  12339.  
  12340. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12341.  
  12342.  Reformat screen 
  12343.  
  12344.  
  12345. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12346.  
  12347.  1 
  12348.  
  12349.  
  12350. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12351.  
  12352.  format 
  12353.  
  12354.  
  12355. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12356.  
  12357.  
  12358. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12359.  
  12360. Push format array 
  12361.  
  12362.  
  12363. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12364.  
  12365. 1 ┬ñ1 
  12366.  
  12367.  
  12368. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12369.  
  12370. format 
  12371.  
  12372.  
  12373. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12374.  
  12375.  
  12376. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12377.  
  12378. Pop format array 
  12379.  
  12380.  
  12381. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12382.  
  12383. 1 ┬ñ2 [,n] 
  12384.  
  12385.  
  12386. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12387.  
  12388. format 
  12389.  
  12390.  
  12391. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12392.  
  12393.  
  12394. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12395.  
  12396.  Reformat fields 
  12397.  
  12398.  
  12399. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12400.  
  12401.  1,field_nos 
  12402.  
  12403.  
  12404. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12405.  
  12406.  format 
  12407.  
  12408.  
  12409. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12410.  
  12411.  
  12412. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12413.  
  12414.  Immediate write to screen 
  12415.  
  12416.  
  12417. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12418.  
  12419.  2,field_nos 
  12420.  
  12421.  
  12422. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12423.  
  12424.  data 
  12425.  
  12426.  
  12427. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12428.  
  12429.  
  12430. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12431.  
  12432.  Read and wait 
  12433.  
  12434.  
  12435. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12436.  
  12437.  3 
  12438. 3 0 
  12439. 3 1 
  12440. 3 3 
  12441.  
  12442.  
  12443. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12444.  
  12445.  
  12446. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12447.  
  12448.  key, cursor, field_no 
  12449.  
  12450.  
  12451. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12452.  
  12453. MORE... 
  12454.  
  12455.  
  12456. ΓòÉΓòÉΓòÉ 14.5.3.22.2. Summary of AP 124 Commands - Part 2 ΓòÉΓòÉΓòÉ
  12457.  
  12458.  
  12459. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12460.  
  12461. Operation 
  12462.  
  12463.  
  12464. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12465.  
  12466. Control Variable 
  12467.  
  12468.  
  12469. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12470.  
  12471. Data Variable 
  12472.  
  12473.  
  12474. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12475.  
  12476. Response in Data Variable 
  12477.  
  12478.  
  12479. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12480.  
  12481.  Read and test 
  12482.  
  12483.  
  12484. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12485.  
  12486.  3 2 
  12487. 3 4 
  12488.  
  12489.  
  12490. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12491.  
  12492.  
  12493. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12494.  
  12495.  key, cursor, field_no 
  12496.  
  12497.  
  12498. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12499.  
  12500.  Delayed write to screen 
  12501.  
  12502.  
  12503. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12504.  
  12505.  4,field_nos 
  12506.  
  12507.  
  12508. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12509.  
  12510.  data 
  12511.  
  12512.  
  12513. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12514.  
  12515.  
  12516. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12517.  
  12518.  Get data 
  12519.  
  12520.  
  12521. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12522.  
  12523.  5,field_nos 
  12524.  
  12525.  
  12526. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12527.  
  12528.  
  12529. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12530.  
  12531.  data 
  12532.  
  12533.  
  12534. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12535.  
  12536.  Update field type 
  12537.  
  12538.  
  12539. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12540.  
  12541.  6,field_nos 
  12542.  
  12543.  
  12544. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12545.  
  12546.  type 
  12547.  
  12548.  
  12549. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12550.  
  12551.  
  12552. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12553.  
  12554.  Update field attribute 
  12555.  
  12556.  
  12557. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12558.  
  12559.  7,field_nos 
  12560.  
  12561.  
  12562. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12563.  
  12564.  attribute 
  12565.  
  12566.  
  12567. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12568.  
  12569.  
  12570. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12571.  
  12572.  Set to APL2 keyboard 
  12573.  
  12574.  
  12575. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12576.  
  12577.  8 
  12578. 8 0 
  12579.  
  12580.  
  12581. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12582.  
  12583.  
  12584. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12585.  
  12586.  
  12587. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12588.  
  12589.  Set to national keyboard 
  12590.  
  12591.  
  12592. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12593.  
  12594.  8 1 
  12595.  
  12596.  
  12597. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12598.  
  12599.  
  12600. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12601.  
  12602.  
  12603. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12604.  
  12605.  Return status 
  12606.  
  12607.  
  12608. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12609.  
  12610.  8 2 
  12611.  
  12612.  
  12613. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12614.  
  12615.  
  12616. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12617.  
  12618.  keyboard, beep, cursor 
  12619.  
  12620.  
  12621. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12622.  
  12623.  Get format table 
  12624.  
  12625.  
  12626. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12627.  
  12628.  9 
  12629.  
  12630.  
  12631. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12632.  
  12633.  
  12634. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12635.  
  12636.  format 
  12637.  
  12638.  
  12639. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12640.  
  12641.  Get the current logical screen 
  12642.  
  12643.  
  12644. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12645.  
  12646.  10 1 
  12647.  
  12648.  
  12649. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12650.  
  12651.  
  12652. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12653.  
  12654.  data 
  12655.  
  12656.  
  12657. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12658.  
  12659. MORE... 
  12660.  
  12661.  
  12662. ΓòÉΓòÉΓòÉ 14.5.3.22.3. Summary of AP 124 Commands - Part 3 ΓòÉΓòÉΓòÉ
  12663.  
  12664.  
  12665. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12666.  
  12667. Operation 
  12668.  
  12669.  
  12670. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12671.  
  12672. Control Variable 
  12673.  
  12674.  
  12675. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12676.  
  12677. Data Variable 
  12678.  
  12679.  
  12680. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12681.  
  12682. Response in Data Variable 
  12683.  
  12684.  
  12685. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12686.  
  12687.  Sound a delayed beep 
  12688.  
  12689.  
  12690. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12691.  
  12692.  11 
  12693. 11 0 
  12694.  
  12695.  
  12696. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12697.  
  12698.  
  12699. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12700.  
  12701.  
  12702. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12703.  
  12704.  Sound an immediate beep 
  12705.  
  12706.  
  12707. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12708.  
  12709.  11 1 
  12710.  
  12711.  
  12712. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12713.  
  12714.  
  12715. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12716.  
  12717.  
  12718. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12719.  
  12720.  Cancel a delayed beep 
  12721.  
  12722.  
  12723. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12724.  
  12725.  11 2 
  12726.  
  12727.  
  12728. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12729.  
  12730.  
  12731. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12732.  
  12733.  
  12734. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12735.  
  12736.  Set the cursor 
  12737.  
  12738.  
  12739. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12740.  
  12741.  12 
  12742.  
  12743.  
  12744. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12745.  
  12746.  position 
  12747.  
  12748.  
  12749. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12750.  
  12751.  
  12752. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12753.  
  12754.  Set cursor type to normal 
  12755.  
  12756.  
  12757. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12758.  
  12759.  12 0 
  12760.  
  12761.  
  12762. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12763.  
  12764.  
  12765. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12766.  
  12767.  
  12768. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12769.  
  12770.  Set cursor type to field 
  12771.  
  12772.  
  12773. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12774.  
  12775.  12 1 
  12776.  
  12777.  
  12778. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12779.  
  12780.  
  12781. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12782.  
  12783.  
  12784. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12785.  
  12786. Query window attributes 
  12787.  
  12788.  
  12789. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12790.  
  12791. 14 
  12792.  
  12793.  
  12794. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12795.  
  12796.  
  12797. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12798.  
  12799. attributes 
  12800.  
  12801.  
  12802. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12803.  
  12804. Set window background color 
  12805.  
  12806.  
  12807. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12808.  
  12809. 14,color 
  12810.  
  12811.  
  12812. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12813.  
  12814.  
  12815. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12816.  
  12817.  
  12818. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12819.  
  12820. Set window placement and size 
  12821.  
  12822.  
  12823. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12824.  
  12825. 14,row,column, 
  12826. height,width 
  12827.  
  12828.  
  12829. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12830.  
  12831.  
  12832. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12833.  
  12834.  
  12835. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12836.  
  12837. Data as a vector of arrays 
  12838.  
  12839.  
  12840. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12841.  
  12842. 15,field_nos 
  12843.  
  12844.  
  12845. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12846.  
  12847.  
  12848. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12849.  
  12850.  
  12851. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12852.  
  12853. MORE... 
  12854.  
  12855.  
  12856. ΓòÉΓòÉΓòÉ 14.5.3.22.4. Summary of AP 124 Commands - Part 4 ΓòÉΓòÉΓòÉ
  12857.  
  12858.  
  12859. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12860.  
  12861. Operation 
  12862.  
  12863.  
  12864. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12865.  
  12866. Control Variable 
  12867.  
  12868.  
  12869. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12870.  
  12871. Data Variable 
  12872.  
  12873.  
  12874. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12875.  
  12876. Response in Data Variable 
  12877.  
  12878.  
  12879. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12880.  
  12881.  Get field attributes 
  12882.  
  12883.  
  12884. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12885.  
  12886.  17,field_nos 
  12887.  
  12888.  
  12889. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12890.  
  12891.  
  12892. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12893.  
  12894.  attributes 
  12895.  
  12896.  
  12897. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12898.  
  12899. Clear screen 
  12900.  
  12901.  
  12902. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12903.  
  12904. 20 
  12905.  
  12906.  
  12907. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12908.  
  12909.  
  12910. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12911.  
  12912.  
  12913. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12914.  
  12915. Set title bar text 
  12916.  
  12917.  
  12918. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12919.  
  12920. 21 1 
  12921.  
  12922.  
  12923. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12924.  
  12925. data 
  12926.  
  12927.  
  12928. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  12929.  
  12930.  
  12931. ΓòÉΓòÉΓòÉ 14.5.4. AP 124 Return Codes ΓòÉΓòÉΓòÉ
  12932.  
  12933. Code      Meaning 
  12934.   0 -     Success 
  12935.  11 -     Control variable rank error 
  12936.  12 -     Control variable length error 
  12937.  13 -     Control variable domain error 
  12938.  14 -     Invalid call 
  12939.  15 -     Request to position cursor in an undefined field 
  12940.  21 -     Data variable rank error 
  12941.  22 -     Data variable length error 
  12942.  23 -     Data variable domain error 
  12943.  24 -     Data variable not shared 
  12944.  25 -     Data variable value error 
  12945.  26 -     Data variable too large 
  12946.  30 -     Invalid field number 
  12947.  32 -     Defined field extends beyond the window 
  12948.  33 -     Reference outside field definition 
  12949.  37 -     Invalid field type 
  12950.  38 -     Invalid attribute 
  12951.  41 -     Data variable has not been specified in the correct sequence 
  12952.  42 -     Data variable has not been referenced in the correct sequence 
  12953.  53 -     Required storage not available 
  12954.  89 -     Data variable interlocked 
  12955.  
  12956.  
  12957. ΓòÉΓòÉΓòÉ 14.6. AP 127-SQL Processor ΓòÉΓòÉΓòÉ
  12958.  
  12959. AP 127 allows you to use the Structured Query Language (SQL) to access IBM 
  12960. DATABASE 2* (DB2). 
  12961.  
  12962. Supplied workspace SQL simplifies the use of AP 127. See The SQL Workspace for 
  12963. more information about SQL. 
  12964.  
  12965. See APL2 Programming: Using Structured Query Language for more information 
  12966. about AP 127. Where APL2 Programming: Using Structured Query Language indicates 
  12967. syntax that differs between operating systems, the syntax for DB2 (TSO) should 
  12968. be used. 
  12969.  
  12970. o AP 127 Commands 
  12971. o AP 127 Return Codes 
  12972.  
  12973.  
  12974. ΓòÉΓòÉΓòÉ 14.6.1. AP 127 Commands ΓòÉΓòÉΓòÉ
  12975.  
  12976. This subsection shows the syntax of the AP 127 commands. In this subsection, 
  12977. DAT represents a variable that is shared with AP 127. 
  12978.  
  12979. DAT Γò£ 'CALL' name [values] 
  12980.  
  12981. Executes defined SQL statement name which was previously processed by a PREP 
  12982. operation. AP 127 substitutes each item of values for the column index in name. 
  12983.  
  12984. DAT Γò£ 'CLOSE' name 
  12985.  
  12986. Closes cursor (SELECT) statement name. 
  12987.  
  12988. DAT Γò£ 'COMMIT' ['RELEASE'] 
  12989.  
  12990. Makes permanent all the changes you made to the data base since you shared the 
  12991. variable or since the most recent COMMIT or ROLLBACK operation. 
  12992.  
  12993. DAT Γò£ 'CONNECT' ['RESET'Γöédatabase['SHARE'Γöé'EXCLUSIVE']] 
  12994.  
  12995. Specifies database name. 
  12996.  
  12997. DAT Γò£ 'DECLARE' name ['HOLD'Γöé'NOHOLD'] 
  12998.  
  12999. Declares a cursor name with hold attribute. 
  13000.  
  13001. DAT Γò£ 'DESCRIBE' ['NAMES'Γöé'LABELS'Γöé'ANY'Γöé'BOTH'] 
  13002.  
  13003. Returns information about an open statement. 
  13004.  
  13005. DAT Γò£ 'EXEC' statement 
  13006.  
  13007. Immediately executes statement. 
  13008.  
  13009. DAT Γò£ 'FETCH' name [options] 
  13010.  
  13011. Returns new result table data as the second item of the shared variable result. 
  13012.  
  13013. DAT Γò£ 'GETOPT' 
  13014.  
  13015. Returns the values of the AP 127 options. 
  13016.  
  13017. DAT Γò£ 'ISOL' [level] 
  13018.  
  13019. Sets or returns isolation level. If level is 'RR', 'CS', or 'UR', sets 
  13020. isolation level to indicate setting. If level is omitted, returns current 
  13021. isolation level. 
  13022.  
  13023. DAT Γò£ 'MSG' rcode 
  13024.  
  13025. Returns the error message text associated with return code rcode. 
  13026.  
  13027. DAT Γò£ 'NAMES' 
  13028.  
  13029. Returns the names of all statements known to AP 127. 
  13030.  
  13031. DAT Γò£ 'OPEN' name [values] 
  13032.  
  13033. Opens previously prepared statement name. 
  13034.  
  13035. DAT Γò£ 'PREP' name statement 
  13036.  
  13037. Prepares SQL statement name for later execution by a CALL or OPEN operation. 
  13038.  
  13039. DAT Γò£ 'PURGE' name 
  13040.  
  13041. Removes statement name from the list of active names in AP 127; if name is 
  13042. empty, all statements are removed from the list. 
  13043.  
  13044. DAT Γò£ 'ROLLBACK' ['RELEASE'] 
  13045.  
  13046. Undoes all the changes you made to the database since you shared the variable 
  13047. with AP 127 or since the most recent COMMIT or ROLLBACK operation. 
  13048.  
  13049. DAT Γò£ 'SETOPT' options 
  13050.  
  13051. Sets the values of the AP 127 options. 
  13052.  
  13053. DAT Γò£ 'SQLCA' 
  13054.  
  13055. Returns the contents of the SQLCA control block. 
  13056.  
  13057. DAT Γò£ 'SQLSTATE' 
  13058.  
  13059. Returns the current value of SQLSTATE. 
  13060.  
  13061. DAT Γò£ 'STATE' name 
  13062.  
  13063. Yields the current state of SQL statement name. 
  13064.  
  13065. DAT Γò£ 'STMT' name 
  13066.  
  13067. Yields SQL statement name. 
  13068.  
  13069. DAT Γò£ 'TRACE' (n1 n2) 
  13070.  
  13071. Yields an event trace of functions within AP 127; n1 specifies the AP 127 
  13072. module number and n2 specifies the trace level. 
  13073.  
  13074.  
  13075. ΓòÉΓòÉΓòÉ 14.6.2. AP 127 Return Codes ΓòÉΓòÉΓòÉ
  13076.  
  13077. Code           Meaning 
  13078. 0 0 0 0 0      Normal return. 
  13079. 0 1 0 n m      Normal return, but a warning message has been issued. 
  13080. 0 0 1 0 0      Normal return, but a result table might not have been completely 
  13081.                retrieved. 
  13082. 1 1 0 n m      Transaction backout; all changes made to tables since the last 
  13083.                COMMIT or ROLLBACK operation are discarded. 
  13084. 1 0 0 1 m      Error in AP 127; m is the number of the AP 127 error message. 
  13085. 1 0 0 2 m      Error in DB2; m is the message number. 
  13086. 1 0 0 3 m      Error in an SQL workspace function; m is the message number. 
  13087.  
  13088.  
  13089. ΓòÉΓòÉΓòÉ 14.7. AP 145-The OS/2 Services Interface Auxiliary Processor ΓòÉΓòÉΓòÉ
  13090.  
  13091. Auxiliary processor 145 provides access to OS/2 services, including many 
  13092. Presentation Manager and Control Program services. APL services are also 
  13093. provided for accessing memory outside the workspace and managing Presentation 
  13094. Manager messages. 
  13095.  
  13096. The supplied workspace PMTOOLS includes utilities for performing common tasks 
  13097. in Presentation Manager. The supplied workspace PMWIN includes variables 
  13098. corresponding to the constants defined in the C language pmwin.h header files. 
  13099. The supplied workspace DEMO145 demonstrates using AP 145. 
  13100.  
  13101. For more information about the supplied workspaces, see Supplied Workspaces. 
  13102.  
  13103. o AP 145 Service Requests 
  13104. o AP 145 Return Codes 
  13105. o AP 145 Online Help 
  13106.  
  13107.  
  13108. ΓòÉΓòÉΓòÉ 14.7.1. AP 145 Service Requests ΓòÉΓòÉΓòÉ
  13109.  
  13110. Services are requested by assigning a nested array to the shared variable.  The 
  13111. first element of the array is the service name. Subsequent elements are the 
  13112. service's parameters. Each parameter must be either a scalar or vector. 
  13113.  
  13114. The general form of the result is a three-element vector. The first element is 
  13115. the AP 145 return code. The second element is the service result. The third 
  13116. element is the service request with any updates applied by the service to the 
  13117. parameters. For example: 
  13118.  
  13119.    AΓò£'WinAlarm' HWND_DESKTOP WA_ERROR
  13120.    (APRC OSRC CMD)Γò£A
  13121.    APRC
  13122. 0
  13123.    OSRC
  13124. 1
  13125.    CMD
  13126. 'WinAlarm' 2
  13127.  
  13128.  
  13129. ΓòÉΓòÉΓòÉ 14.7.2. AP 145 Return Codes ΓòÉΓòÉΓòÉ
  13130.  
  13131. The following return codes are used by AP 145. 
  13132.  
  13133. Code    Meaning 
  13134.  0      Success 
  13135.  1      Invalid array 
  13136.  2      Unsupported service name 
  13137.  3      Incorrect number of parameters 
  13138.  4      Invalid parameter 
  13139.  
  13140.  
  13141. ΓòÉΓòÉΓòÉ 14.7.3. AP 145 Online Help ΓòÉΓòÉΓòÉ
  13142.  
  13143. AP 145 provides online help. The online help is accessed using the AplHelp 
  13144. service. 
  13145.  
  13146. To display the general help for AP 145, enter the following command: 
  13147.  
  13148.       AΓò£'AplHelp' 'General'
  13149.  
  13150.  
  13151. ΓòÉΓòÉΓòÉ 14.8. AP 207-The Universal Graphics Auxiliary Processor ΓòÉΓòÉΓòÉ
  13152.  
  13153. AP 207 enables you to generate fast, high-quality graphics and text, easily and 
  13154. quickly. It accepts an easy-to-learn command syntax that has been designed for 
  13155. both simplicity of use and high performance. It has built-in support for the 
  13156. OS/2 services, giving high-quality graphics combined with the flexibility of a 
  13157. powerful window management facility. It works with a single shared variable to 
  13158. control each graphics window. There are no special name restrictions for the 
  13159. shared variables. The following basic functions are supported: 
  13160.  
  13161. o Representation of graphic information either as line segments or as 
  13162.   higher-level structures, such as arcs or sectors of a circle 
  13163.  
  13164. o Generation of text characters in various sizes and orientations, using 
  13165.   external image, vector, or PostScript fonts 
  13166.  
  13167. o Definition of a world coordinate system 
  13168.  
  13169. o Definition of clipping and scissoring rectangles 
  13170.  
  13171. o AP 207 Interface 
  13172. o AP 207 Commands 
  13173. o Multiple-Call Sequences 
  13174. o Defining World Coordinates with Correct Aspect Ratio 
  13175. o Image and Vector Font Support 
  13176. o AP 207 Return Codes 
  13177.  
  13178.  
  13179. ΓòÉΓòÉΓòÉ 14.8.1. AP 207 Interface ΓòÉΓòÉΓòÉ
  13180.  
  13181. AP 207 requires a single variable to be shared for each new window. A variable 
  13182. is shared with AP 207. For example: 
  13183.  
  13184.       207 SVOFFER 'SHR207'
  13185. 2
  13186.  
  13187. offers variable SHR207 to AP 207 and sets access control. See Using the 
  13188. Share-Offer Utilities for a description of the SVOFFER function. 
  13189.  
  13190. Once the variable has been shared and the appropriate access control 
  13191. established, commands can then be passed to AP 207 in the form of a two-element 
  13192. vector, the first element of which is the name of the command and the second 
  13193. contains the parameters required by the command. For example: 
  13194.  
  13195.       SHR207Γò£'OPEN' 0
  13196.       DISPLAY ╨áΓò£SHR207
  13197.  0  1
  13198. ΓöîΓòòΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  13199. Γöé   ΓöîΓòòΓöÉ Γöé
  13200. Γöé 0 Γöé1Γöé Γöé
  13201. Γöé   Γöö~Γöÿ Γöé
  13202. └ю──────┘
  13203.       SHR207Γò£'DRAW' (1 100 100)
  13204.       DISPLAY ╨áΓò£SHR207
  13205.  0
  13206. ΓöîΓòòΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  13207. Γöé   Γöî╤ëΓöÉ Γöé
  13208. Γöé 0 Γöé0Γöé Γöé
  13209. Γöé   Γöö~Γöÿ Γöé
  13210. └ю──────┘
  13211.  
  13212. This opens an OS/2 window, and then issues command DRAW with parameters 
  13213. 1 100 100. 
  13214.  
  13215. Most commands return a two-element vector. The first element is the numeric 
  13216. return code for the call, and the second contains any parameters returned by 
  13217. the call (as an enclosed array). Wherever possible, if a parameter is given 
  13218. outside of the valid range of values, the closest possible available value is 
  13219. chosen. 
  13220.  
  13221. You can issue more than one command in a single call. This is explained later, 
  13222. in Multiple-Call Sequences. 
  13223.  
  13224. Command names can be entered in any combination of uppercase or lowercase 
  13225. letters. 
  13226.  
  13227.  
  13228. ΓòÉΓòÉΓòÉ 14.8.2. AP 207 Commands ΓòÉΓòÉΓòÉ
  13229.  
  13230. Commands 
  13231.  
  13232. Command             Description 
  13233. ARC                 Draw arc 
  13234. BEGAREA             Begin filled area 
  13235. BITMAP              Read/write bitmap files 
  13236. BOX                 Draw box 
  13237. CLEAR or ERASE      Clear the graphics window 
  13238. CLOSE               Close device 
  13239. COLMAP              Define color mapping 
  13240. COLOR               Set color 
  13241. CURSOR              Enable or disable pointer cursor 
  13242. DRAW                Draw a line 
  13243. ENDAREA             End filled area 
  13244. ESCAPE              Send escape sequence to device 
  13245. FONT                Select image or vector font characteristics 
  13246. FONTDEF             Define image or vector font 
  13247. IMAGE               Display or read an image 
  13248. LINETYPE            Set line type 
  13249. LOAD                Load a device driver 
  13250. MARKER              Write marker 
  13251. MIX                 Set mix mode 
  13252. MOVE                Move to new point 
  13253. OPEN                Open a device 
  13254. PALETTE             Set color palette 
  13255. PATTERN             Set area fill pattern 
  13256. POINTER             Activate pointer device 
  13257. PRINT               Print graphics window 
  13258. QUERY               Query driver parameters 
  13259. QWRITE              Query position and size of string 
  13260. SCISSOR             Set scissoring rectangle 
  13261. SECTOR/WEDGE        Draw a sector 
  13262. SETPEL              Set one or more pels on 
  13263. USE                 Select a driver 
  13264. VIEW                View graphics 
  13265. WAIT                Wait for an event 
  13266. WINDOW              Define window 
  13267. WRITE               Write a character string 
  13268.  
  13269.  
  13270. ΓòÉΓòÉΓòÉ 14.8.2.1. Arc-Description: ΓòÉΓòÉΓòÉ
  13271.  
  13272. Draws an arc, an ellipse, or a circle. 
  13273.  
  13274. If used between BEGAREA and ENDAREA calls, each arc is filled independently. 
  13275.  
  13276.  The current position is set to the end point of the arc. 
  13277.  
  13278.  
  13279. ΓòÉΓòÉΓòÉ 14.8.2.1.1. ARC-Syntax: ΓòÉΓòÉΓòÉ
  13280.  
  13281. CΓò£'ARC' (X Y X_RAD Y_RAD START_ANG END_ANG) 
  13282.  
  13283. where: 
  13284.  
  13285. X,Y                      give the center of the arc 
  13286.  
  13287. X_RAD,Y_RAD              give the radius of the arc along the x and y axes 
  13288.  
  13289. START_ANG,END_ANG        give the starting and ending angles of the arc in 
  13290.                          degrees. 
  13291.  
  13292.  
  13293. ΓòÉΓòÉΓòÉ 14.8.2.2. BEGAREA-Description: ΓòÉΓòÉΓòÉ
  13294.  
  13295. Start collecting points to define an area to fill. The ENDAREA call ends the 
  13296. collection of points and fills any polygons defined since the previous BEGAREA 
  13297. call. 
  13298.  
  13299. The following commands are not allowed between BEGAREA and ENDAREA commands: 
  13300.  
  13301. BITMAP                   LINE 
  13302. CLOSE                    LINETYPE 
  13303. COLMAP                   MIX 
  13304. COLOR                    OPEN 
  13305. FONT                     PALETTE 
  13306. FONTDEF                  PATTERN 
  13307. IMAGE                    PRINT 
  13308.  
  13309.  
  13310. ΓòÉΓòÉΓòÉ 14.8.2.2.1. BEGAREA-Syntax: ΓòÉΓòÉΓòÉ
  13311.  
  13312. CΓò£'BEGAREA'  '' 
  13313.  
  13314. (Null string) 
  13315.  
  13316.  
  13317. ΓòÉΓòÉΓòÉ 14.8.2.3. BITMAP-Description: ΓòÉΓòÉΓòÉ
  13318.  
  13319. This command reads a file and writes the bitmap in a window. 
  13320.  
  13321. Note:  This command is not portable across platforms. 
  13322.  
  13323.  
  13324. ΓòÉΓòÉΓòÉ 14.8.2.3.1. BITMAP-Syntax: ΓòÉΓòÉΓòÉ
  13325.  
  13326. CΓò£'BITMAP' 'FILESPEC' 
  13327.  
  13328. Reads the bitmap file and returns the size in pels of the bitmap as defined in 
  13329. the bitmap file. 
  13330.  
  13331. CΓò£'BITMAP' ('FILESPEC' WIDTH HEIGHT') 
  13332.  
  13333. Writes the bitmap to the window at the current position. The bitmap is scaled 
  13334. to fit the width and height requested. Colors are mapped to the logical color 
  13335. table on a best fit basis. Returns the size of the bitmap as defined in the 
  13336. bitmap file. 
  13337.  
  13338. CΓò£'FILESPEC' XLEFT YBOTTOM XRIGHT XTOP 
  13339.  
  13340. Writes an area in world coordinates to the filespec in a bitmap 2.0 format. The 
  13341. area bounded by the world coordinates must be visible on the screen as the data 
  13342. is read directly from the display. The resultant size and resolution of the 
  13343. bitmap is dependent on the current window scale. For completely repeatable 
  13344. results, the window size, the world coordinates, and the view coordinates 
  13345. should all be the same. Returns a character array comparable to the 'IMAGE' 
  13346. read command. 
  13347.  
  13348.  
  13349. ΓòÉΓòÉΓòÉ 14.8.2.4. BOX-Description: ΓòÉΓòÉΓòÉ
  13350.  
  13351. This command draws a rectangular box. 
  13352.  
  13353. Note:  This command is not portable across platforms. 
  13354.  
  13355.  
  13356. ΓòÉΓòÉΓòÉ 14.8.2.4.1. BOX-Syntax: ΓòÉΓòÉΓòÉ
  13357.  
  13358. CΓò£'BOX' (XCORNER YCORNER HAXIS VAXIS) 
  13359.  
  13360. Draws a rectangular box from the current position to the corner at 
  13361. xCorner,yCorner with the corners rounded by the ellipse on the horizontal full 
  13362. axis of hAxis and the vertical full axis of vAxis. Values of 0,0 on hAxis,vAxis 
  13363. give a rectangular box. This primitive does not alter the current position. 
  13364.  
  13365.  
  13366. ΓòÉΓòÉΓòÉ 14.8.2.5. CLEAR OR ERASE-Description: ΓòÉΓòÉΓòÉ
  13367.  
  13368. Clears the graphics window and optionally sets the initial window color. 
  13369.  
  13370.  
  13371. ΓòÉΓòÉΓòÉ 14.8.2.5.1. CLEAR/ERASE-Syntax ΓòÉΓòÉΓòÉ
  13372.  
  13373. CΓò£'CLEAR' 'COLOR_NAME' 
  13374.  
  13375. Clears the graphics window and fills the window with color COLOR_NAME. 
  13376. COLOR_NAME is one of:  BACKGROUND, BLACK, BLUE, BROWN, CYAN, DBLUE, DCYAN, 
  13377. DGRAY (or DGREY), DGREEN, DMAGENTA, DRED, GRAY (or GREY) GREEN, MAGENTA, 
  13378. NEUTRAL, RED, WHITE or YELLOW. The closest matching color from the color map 
  13379. array is selected. Any color beginning with a "D" is a dark version of the 
  13380. specified color. Returns the color map row number used. CΓò£'CLEAR' COLOR_NO 
  13381.  
  13382. Clears the graphics window and fills the window with color COLOR_NO. COLOR_NO 
  13383. is 0 to 255 and specifies the (0-origin) row number of the color map array, as 
  13384. defined by the COLMAP call. Returns the color map row number used. 
  13385.  
  13386. CΓò£'CLEAR' (R,G,B) 
  13387.  
  13388. Clears the graphics window and fills the window with the color that is the best 
  13389. possible match available in the current color map array. R, G, and B are 
  13390. numbers in the range 0 to 1000 and specify the desired level of red, green, and 
  13391. blue. Returns the color map row number used. 
  13392.  
  13393. CΓò£'CLEAR' '' 
  13394.  
  13395. Clears the graphics window and sets the window to the background color. Returns 
  13396. the color map row number used. 
  13397.  
  13398.  
  13399. ΓòÉΓòÉΓòÉ 14.8.2.6. CLOSE-Description: ΓòÉΓòÉΓòÉ
  13400.  
  13401. Close the active device. 
  13402.  
  13403.  
  13404. ΓòÉΓòÉΓòÉ 14.8.2.6.1. CLOSE-Syntax ΓòÉΓòÉΓòÉ
  13405.  
  13406. CΓò£'CLOSE' '' 
  13407.  
  13408. Closes the currently active device. 
  13409.  
  13410.  
  13411. ΓòÉΓòÉΓòÉ 14.8.2.7. COLMAP-Description: ΓòÉΓòÉΓòÉ
  13412.  
  13413. Defines the mapping between the color numbers used with the COLOR call and the 
  13414. actual palette entry used. The R, G, and B values are numbers in the range 0 to 
  13415. 1000 and specify the desired level of red, green and blue. 
  13416.  
  13417.  
  13418. ΓòÉΓòÉΓòÉ 14.8.2.7.1. COLMAP-Syntax ΓòÉΓòÉΓòÉ
  13419.  
  13420. CΓò£'COLMAP' ((N,3)╤åR1,G1,B1,...,RN,GN,BN) 
  13421.  
  13422. Sets the color map table for entries 0 to N-1 with the color that is the best 
  13423. possible match available in the current palette. CΓò£'COLMAP' 
  13424. ((N,4)╤åINDEX1,R1,G1,B1,...,RN,GN,BN) 
  13425.  
  13426. INDEXN,RN,GN,BN Sets the color map table for the entries specified in the first 
  13427. column with the color that is the best possible match available in the current 
  13428. palette. CΓò£'COLMAP' (INDEX,R,G,B) 
  13429.  
  13430. Set the color map table entry INDEX with the color that is the best possible 
  13431. match available in the current palette. CΓò£'COLMAP' (INDEX 'COLOR_NAME') 
  13432.  
  13433. Set the color map table entry INDEX to the closest matching color available in 
  13434. the current palette. COLOR_NAME is one of:  BACKGROUND, BLACK, BLUE, BROWN, 
  13435. CYAN, DBLUE, DCYAN, DGRAY (or DGREY), DGREEN, DMAGENTA, DRED, GRAY (or GREY), 
  13436. GREEN, MAGENTA, NEUTRAL, RED, WHITE, or YELLOW. CΓò£'COLMAP' INDEX 
  13437.  
  13438. Returns the current setting for the color map table entry INDEX as a 1-by-5 
  13439. matrix. CΓò£'COLMAP' ┬ñ1 
  13440.  
  13441. Resets the color map table to match the current palette colors. CΓò£'COLMAP' ('') 
  13442.  
  13443. Returns the current color map table as a 256╤ù5 matrix, each row of which 
  13444. contains the color map table row index, the corresponding row of the palette 
  13445. table and the r, g, b values for this row. 
  13446.  
  13447.  
  13448. ΓòÉΓòÉΓòÉ 14.8.2.8. COLOR-Description: ΓòÉΓòÉΓòÉ
  13449.  
  13450. Sets a new foreground color. If called within a BEGAREA-ENDAREA sequence, this 
  13451. call forces the polygon defined by the points already established to be filled 
  13452. with the previous color, and any new points are filled with the new color. 
  13453.  
  13454.  
  13455. ΓòÉΓòÉΓòÉ 14.8.2.8.1. COLOR-Syntax ΓòÉΓòÉΓòÉ
  13456.  
  13457. CΓò£'COLOR' 'COLOR_NAME' 
  13458.  
  13459. Sets the active foreground color to COLOR_NAME. COLOR_NAME is one of: 
  13460. BACKGROUND, BLACK, BLUE, BROWN, CYAN, DBLUE, DCYAN, DGRAY (or DGREY), DGREEN, 
  13461. DMAGENTA, DRED, GRAY (or GREY), GREEN, MAGENTA, NEUTRAL, RED, WHITE, or YELLOW. 
  13462. The closest matching color from the color map is selected. Any color beginning 
  13463. with a "D" is a dark version of the specified color. Returns the color map row 
  13464. number selected. CΓò£'COLOR' COLOR_NO 
  13465.  
  13466. Sets the active foreground color to COLOR_NO, where COLOR_NO is 0 to 255 and 
  13467. specifies the (0-origin) row number of the color map array, as defined by the 
  13468. COLMAP call. Returns the color map row number selected. CΓò£'COLOR' (R,G,B) 
  13469.  
  13470. Sets the active foreground color to the best possible match available in the 
  13471. current color map. R, G, and B are numbers in the range 0 to 1000 and specify 
  13472. the desired level of red, green, and blue. Returns the color map row number 
  13473. selected. CΓò£'COLOR' ('') 
  13474.  
  13475. Returns the current color map row number of the active foreground color. 
  13476.  
  13477.  
  13478. ΓòÉΓòÉΓòÉ 14.8.2.9. CURSOR-Description: ΓòÉΓòÉΓòÉ
  13479.  
  13480. Activates the pointer cursor. 
  13481.  
  13482.  
  13483. ΓòÉΓòÉΓòÉ 14.8.2.9.1. CURSOR-Syntax ΓòÉΓòÉΓòÉ
  13484.  
  13485. CΓò£'CURSOR' 0 
  13486.  
  13487. Selects the default state for the cursor. In APL2/2 the cursor is permanently 
  13488. enabled and this selects the default cursor. 
  13489.  
  13490. CΓò£'CURSOR' 1 
  13491.  
  13492. Enables the display of the cross-hair cursor. 
  13493.  
  13494. CΓò£'CURSOR' ('') 
  13495.  
  13496. Queries the current state of the cursor. 
  13497.  
  13498.  
  13499. ΓòÉΓòÉΓòÉ 14.8.2.10. DRAW-Description: ΓòÉΓòÉΓòÉ
  13500.  
  13501. Move or draw ("MD") to a specified point. The line is drawn with the active 
  13502. foreground color and current linetype. The current position is set to the last 
  13503. coordinate given. 
  13504.  
  13505.  
  13506. ΓòÉΓòÉΓòÉ 14.8.2.10.1. DRAW-Syntax ΓòÉΓòÉΓòÉ
  13507.  
  13508. CΓò£'DRAW' (X,Y) 
  13509.  
  13510. Draws a line from the current position to (X,Y). 
  13511.  
  13512. CΓò£'DRAW' (MD,X,Y) 
  13513.  
  13514. Moves to (X,Y) if MD=0, or draws a line to (X,Y) if MD=1. 
  13515.  
  13516. CΓò£'DRAW' ((N,2)╤åX1,Y1,...,XN,YN) 
  13517.  
  13518. Performs a move to (X1,Y1), and then draws to each (X,Y) coordinate given in 
  13519. subsequent rows of the matrix. 
  13520.  
  13521. CΓò£'DRAW' ((N,3)╤åMD1,X1,Y1,...,MDN,XN,YN) 
  13522.  
  13523. Performs successive moves (MD=0) or draws (MD=1) to the X and Y coordinate 
  13524. given in each row of the matrix. 
  13525.  
  13526.  
  13527. ΓòÉΓòÉΓòÉ 14.8.2.11. ENDAREA-Description: ΓòÉΓòÉΓòÉ
  13528.  
  13529. Signal the end of a polygon to fill. This ends the collection of points and 
  13530. fills any polygons defined since the previous BEGAREA call. 
  13531.  
  13532.  
  13533. ΓòÉΓòÉΓòÉ 14.8.2.11.1. ENDAREA-Syntax ΓòÉΓòÉΓòÉ
  13534.  
  13535. CΓò£'ENDAREA' ('') 
  13536.  
  13537. Fill all polygons defined since the previous BEGAREA call. 
  13538.  
  13539.  
  13540. ΓòÉΓòÉΓòÉ 14.8.2.12. ESCAPE-Description: ΓòÉΓòÉΓòÉ
  13541.  
  13542. Send a device-driver-dependent string to the driver. An application using this 
  13543. is not portable between systems. 
  13544.  
  13545.  
  13546. ΓòÉΓòÉΓòÉ 14.8.2.12.1. ESCAPE-Syntax ΓòÉΓòÉΓòÉ
  13547.  
  13548. CΓò£'ESCAPE' (PARAMETERS) 
  13549.  
  13550. As defined by device driver. 
  13551.  
  13552.  
  13553. ΓòÉΓòÉΓòÉ 14.8.2.13. FONT-Description: ΓòÉΓòÉΓòÉ
  13554.  
  13555. Specifies the characteristics of the image or vector font. 
  13556.  
  13557. Sets the font direction, size, horizontal alignment, vertical alignment, and 
  13558. various other parameters. 
  13559.  
  13560.  
  13561. ΓòÉΓòÉΓòÉ 14.8.2.13.1. FONT-Syntax ΓòÉΓòÉΓòÉ
  13562.  
  13563. CΓò£'FONT' ('FONTNAME' SIZE ANGLE XJUST YJUST DIRECTION SHEAR XMAG NOPARSE) 
  13564.  
  13565. FONTNAME  name of the font as defined with the FONTDEF call, or 0 for built-in 
  13566.           image font 
  13567. SIZE      uppercase character height in world coordinate system units (ignored 
  13568.           for image font for display; on printers, this is scaled depending on 
  13569.           the print driver) 
  13570. ANGLE     specifies the text baseline angle (must be 0 for an image font) 
  13571. XJUST     0 (left justify), 1 (center) or 2 (right justify) 
  13572. YJUST     0 (character baseline), 1 (center), 2 (uppercase character top), 3 
  13573.           (character box bottom), or 4 (character box top) 
  13574. DIRECTION (reserved-set to 0) 
  13575. SHEAR     angle (in degrees) to shear vector characters in order to produce 
  13576.           effects such as italics (must be 0 for image font) 
  13577. XMAG      magnification to be applied to x-axis of characters to produce 
  13578.           effects like stretched characters (must be 1 for image font) 
  13579. NOPARSE   (reserved-set to 0). 
  13580.  
  13581. Any parameters that are not supplied default to 0 except XMAG defaults to 1 and 
  13582. SIZE defaults to the size defined by the font. Many parameters have no effect 
  13583. on image characters. Portable applications should use vector fonts since these 
  13584. can be reproduced consistently on various devices. 
  13585.  
  13586. CΓò£'FONT' ('') 
  13587.  
  13588. Returns current font parameters. This has four elements in addition to those 
  13589. defined above: 
  13590.  
  13591. BOX_HEIGHT  the total character box height 
  13592. DESCENDER_HEIGHT the distance from the baseline to the bottom of the character 
  13593.             box 
  13594. MAX_WIDTH   the maximum width of any character in the font 
  13595. FONT_TYPE   0 for an image font and 1 for a vector font 
  13596.  
  13597. Note:  (This parameter may not be used in a multiple-call sequence.) 
  13598.  
  13599.  
  13600. ΓòÉΓòÉΓòÉ 14.8.2.14. FONTDEF-Description: ΓòÉΓòÉΓòÉ
  13601.  
  13602. Specifies the name of an image or vector font file. 
  13603.  
  13604.  
  13605. ΓòÉΓòÉΓòÉ 14.8.2.14.1. FONTDEF-Syntax ΓòÉΓòÉΓòÉ
  13606.  
  13607. CΓò£'FONTDEF' ('FONTNAME' 'FILENAME') 
  13608.  
  13609.  Loads font specified and adds FONTNAME to AP 207 font table. The maximum 
  13610. length of FONTNAME is 12 characters. This command loads the font file from path 
  13611. if possible. It then searches the current directory, followed by paths listed 
  13612. in environment variables "APL207FL", "DPATH", and "PATH". 
  13613.  
  13614. To use the supplied APL2 vector fonts, note that FILENAME must include the 
  13615. ".AVF" extension. 
  13616.  
  13617. CΓò£'FONTDEF' ('FONTNAME' ┬ñ1) 
  13618.  
  13619. Removes FONTNAME from AP 207 font table. 
  13620.  
  13621. CΓò£'FONTDEF' ('') 
  13622.  
  13623. Returns current AP 207 font table. This is returned as three character arrays: 
  13624.  
  13625. o Font status-a two-column matrix. The first column contains "A" if the font is 
  13626.   active or a blank otherwise. The second column contains "V" for a vector 
  13627.   font, "I" for an OS/2 system image font, "P" for an OS/2 system PostScript 
  13628.   font, or a blank if no font is defined for this row. 
  13629.  
  13630. o A matrix of font names (as specified on FONTDEF call). 
  13631.  
  13632. o A matrix of file names. 
  13633.  
  13634. Note:  (This parameter may not be used in a multiple-call sequence.) 
  13635.  
  13636.  
  13637. ΓòÉΓòÉΓòÉ 14.8.2.15. IMAGE-Description: ΓòÉΓòÉΓòÉ
  13638.  
  13639. Display a character image array, or read an image. 
  13640.  
  13641.  
  13642. ΓòÉΓòÉΓòÉ 14.8.2.15.1. IMAGE-Syntax ΓòÉΓòÉΓòÉ
  13643.  
  13644. CΓò£'IMAGE' (IMAGE) 
  13645.  
  13646. Displays image with lower-left corner placed at the current position, as set by 
  13647. a previous move call. IMAGE is a character matrix, each element of which is the 
  13648. ╨áAF of the (0-origin) row number in the color map array to be used for the 
  13649. corresponding world coordinates. Image is scaled as necessary. 
  13650.  
  13651. You receive an error message if you specify color indexes that are not defined 
  13652. in the color map. 
  13653.  
  13654. Returns the coordinates of the lower-left and upper-right corners of the image, 
  13655. in world coordinates. 
  13656.  
  13657. CΓò£'IMAGE' (X1,Y1,X2,Y2) 
  13658.  
  13659. Reads an image within the rectangle defined by the world coordinates specified; 
  13660. the coordinates identify either pair of diagonally-opposite corners. Returns a 
  13661. character matrix, each element of which is the ╨áAF of the (0-origin) row number 
  13662. in the color map array that is the closest match to the color of the 
  13663. corresponding pel. 
  13664.  
  13665. Note:  (This may not be used in a multiple-call sequence.) 
  13666.  
  13667.  
  13668. ΓòÉΓòÉΓòÉ 14.8.2.16. LINETYPE-Description: ΓòÉΓòÉΓòÉ
  13669.  
  13670. Set the line attributes. 
  13671.  
  13672.  
  13673. ΓòÉΓòÉΓòÉ 14.8.2.16.1. LINETYPE-Syntax ΓòÉΓòÉΓòÉ
  13674.  
  13675. CΓò£'LINETYPE' (WIDTH,STYLE) 
  13676.  
  13677. Sets line type parameters. WIDTH is 1 to maximum, STYLE is 1 to maximum. The 
  13678. number of available line widths and styles is given by the QUERY call. A value 
  13679. of 0 for either parameter gives the default attribute for that parameter (thin, 
  13680. solid line). Returns the selected line type parameters. 
  13681.  
  13682. CΓò£'LINETYPE' ('') 
  13683.  
  13684. Returns the current line type parameters. 
  13685.  
  13686.  
  13687. ΓòÉΓòÉΓòÉ 14.8.2.17. LOAD-Description: ΓòÉΓòÉΓòÉ
  13688.  
  13689. Load a device driver into the auxiliary processor. 
  13690.  
  13691. Note:  This command is ignored by APL2/2. 
  13692.  
  13693.  
  13694. ΓòÉΓòÉΓòÉ 14.8.2.17.1. LOAD-Syntax ΓòÉΓòÉΓòÉ
  13695.  
  13696. CΓò£'LOAD' DEVICE_NAME 
  13697.  
  13698. Loads the device driver with name DEVICE_NAME, assigning a device handle (an 
  13699. integer value that can be used by the USE call) to the driver. 
  13700.  
  13701. CΓò£'LOAD' ('') 
  13702.  
  13703. Returns the device names of the available drivers, along with their device 
  13704. handles or a ┬ñ1 if the driver is available but not loaded. 
  13705.  
  13706.  
  13707. ΓòÉΓòÉΓòÉ 14.8.2.18. MARKER-Description: ΓòÉΓòÉΓòÉ
  13708.  
  13709. Write one or more markers centered at given positions. 
  13710.  
  13711.  
  13712. ΓòÉΓòÉΓòÉ 14.8.2.18.1. MARKER-Syntax ΓòÉΓòÉΓòÉ
  13713.  
  13714. CΓò£'MARKER' MARKER 
  13715.  
  13716. Selects marker type MARKER. MARKER is 1 to maximum. A value of 0 gives the 
  13717. default marker that is a cross. The number of available markers is given by the 
  13718. QUERY call. Returns the marker selected. 
  13719.  
  13720. CΓò£'MARKER' (X,Y) 
  13721.  
  13722. Writes current marker centered at position (X,Y). 
  13723.  
  13724. CΓò£'MARKER' ((N,2)╤åX1,Y1,...,XN,YN) 
  13725.  
  13726. Writes current marker centered at the X and Y coordinates given by each row of 
  13727. the matrix. 
  13728.  
  13729. CΓò£'MARKER' ((N,3)╤åMD1,X1,Y1,...,MDN,XN,YN) 
  13730.  
  13731. Writes current marker centered at the X and Y coordinates of the ends of each 
  13732. line segment that would be drawn by a DRAW call with the same array. (MD 
  13733. indicates move or draw. A marker is drawn on all rows where MD=1 and on rows 
  13734. where MD=0 precedes a row where MD=1.) 
  13735.  
  13736. CΓò£'MARKER' ('') 
  13737.  
  13738. Returns the current marker type. 
  13739.  
  13740.  
  13741. ΓòÉΓòÉΓòÉ 14.8.2.19. MIX-Description: ΓòÉΓòÉΓòÉ
  13742.  
  13743. Sets the color mixing mode. 
  13744.  
  13745.  
  13746. ΓòÉΓòÉΓòÉ 14.8.2.19.1. MIX-Syntax ΓòÉΓòÉΓòÉ
  13747.  
  13748. CΓò£'MIX' 0 
  13749.  
  13750. Pels to be written directly replace existing pels. This is the default. 
  13751.  
  13752. CΓò£'MIX' 1 
  13753.  
  13754. Pels to be written are ANDed with existing pels. 
  13755.  
  13756. CΓò£'MIX' 2 
  13757.  
  13758. Pels to be written are ORed with existing pels. This gives a color mixing 
  13759. effect. 
  13760.  
  13761. CΓò£'MIX' 3 
  13762.  
  13763. Pels to be written are exclusive-ORed with existing pels. This can be used to 
  13764. move objects around, since writing the same object back into the same position 
  13765. in this mode restores the original screen, making the object disappear. Returns 
  13766. the mixing mode selected. 
  13767.  
  13768. CΓò£'MIX' ('') 
  13769.  
  13770. Returns the current mixing mode. 
  13771.  
  13772.  
  13773. ΓòÉΓòÉΓòÉ 14.8.2.20. MOVE-Description: ΓòÉΓòÉΓòÉ
  13774.  
  13775. Move to a specified point. The current position is set to the coordinate given. 
  13776. No line is drawn. 
  13777.  
  13778.  
  13779. ΓòÉΓòÉΓòÉ 14.8.2.20.1. MOVE-Syntax ΓòÉΓòÉΓòÉ
  13780.  
  13781. CΓò£'MOVE' X,Y 
  13782.  
  13783. Moves to (X,Y). Returns the new x,y position. 
  13784.  
  13785. CΓò£'MOVE' ('') 
  13786.  
  13787. Returns the current x,y position. 
  13788.  
  13789.  
  13790. ΓòÉΓòÉΓòÉ 14.8.2.21. OPEN-Description: ΓòÉΓòÉΓòÉ
  13791.  
  13792. Open the Presentation Manager window into a state of readiness for graphics. 
  13793.  
  13794. Note:  Open performs an implicit close if an open device exists. 
  13795.  
  13796.  
  13797. ΓòÉΓòÉΓòÉ 14.8.2.21.1. OPEN-Syntax ΓòÉΓòÉΓòÉ
  13798.  
  13799. CΓò£'OPEN' (VIDEO_MODE 'TITLE' WIDTH HEIGHT XPOS YPOS) 
  13800.  
  13801. The only VIDEO_MODE supported by the OS/2 services device driver is 1. This can 
  13802. also be selected by specifying a parameter of 0 which is preferred since this 
  13803. allows AP 207 code to be portable between different implementations. TITLE is 
  13804. the name that appears on the title bar of the window and in the icon for this 
  13805. window. If not specified, the title is "AP207". WIDTH and HEIGHT specify the 
  13806. width and height of the initial window in device units (pels) and default to 
  13807. 640 and 480 respectively. XPOS and YPOS specify the initial x and y position of 
  13808. the window. If these are not given, interactive window placement is used. 
  13809.  
  13810. CΓò£'OPEN' ('') 
  13811.  
  13812. Returns the current video mode, which is 0 if an OPEN has not yet been issued. 
  13813.  
  13814.  
  13815. ΓòÉΓòÉΓòÉ 14.8.2.22. PALETTE-Description: ΓòÉΓòÉΓòÉ
  13816.  
  13817. This command is synonymous with COLMAP. For more information, see COLMAP-Define 
  13818. Color Mapping. 
  13819.  
  13820.  
  13821. ΓòÉΓòÉΓòÉ 14.8.2.22.1. PALETTE-Syntax ΓòÉΓòÉΓòÉ
  13822.  
  13823. Note:  see "COLMAP-Define Color Mapping" 
  13824.  
  13825.  
  13826. ΓòÉΓòÉΓòÉ 14.8.2.23. PATTERN-Description: ΓòÉΓòÉΓòÉ
  13827.  
  13828. Sets the active fill pattern. If issued within a BEGAREA-ENDAREA sequence, this 
  13829. call forces the polygon defined by the points already established to be filled 
  13830. with the previous pattern and any new points are filled with the new pattern. 
  13831.  
  13832.  
  13833. ΓòÉΓòÉΓòÉ 14.8.2.23.1. PATTERN-Syntax ΓòÉΓòÉΓòÉ
  13834.  
  13835. CΓò£'PATTERN' PATTERN 
  13836.  
  13837. Sets the active fill pattern to PATTERN. PATTERN is 1 to maximum. A value of 0 
  13838. gives the default fill pattern that is a solid fill. The number of available 
  13839. patterns is given by the QUERY call. Returns the pattern selected. 
  13840.  
  13841. CΓò£'PATTERN' ('') 
  13842.  
  13843. Returns the current fill pattern number. 
  13844.  
  13845.  
  13846. ΓòÉΓòÉΓòÉ 14.8.2.24. POINT-Description: ΓòÉΓòÉΓòÉ
  13847.  
  13848. Activate the graphics pointer device. 
  13849.  
  13850.  
  13851. ΓòÉΓòÉΓòÉ 14.8.2.24.1. POINT-Syntax ΓòÉΓòÉΓòÉ
  13852.  
  13853. CΓò£'POINT' (0[,X_INITIAL,Y_INITIAL]) 
  13854.  
  13855. Activates the graphics pointer device, pointing initially at (X_INITIAL, 
  13856. Y_INITIAL), or the current position if an initial position is not given. 
  13857. Returns 1,X_FINAL,Y_FINAL,BUTTON_NO when a mouse button is released, or 
  13858. 2,X_FINAL,Y_FINAL,C,S when a keyboard key is pressed. C and S are the character 
  13859. code and scan code as returned by the AP 124 calls (3 1), (3 2), and (3 3) as 
  13860. described for AP 124 under Read and Wait or Read and Test. 
  13861.  
  13862. CΓò£'POINT' (1[,X_START,Y_START[,X_INITIAL, Y_INITIAL]]) 
  13863.  
  13864. Activates the graphics pointer device, pointing initially at (X_INITIAL, 
  13865. Y_INITIAL) or the current position if an initial position is not given. Draws a 
  13866. "rubber band" line from (X_START,Y_START) (or the current position if not 
  13867. given) to the location of the pointer. Returns the same data as for the 0 case. 
  13868.  
  13869. CΓò£'POINT' (2,X_START,Y_START[,X_END,Y_END [,X_INITIAL,Y_INITIAL]]) 
  13870.  
  13871. Activates the graphics pointer device, pointing initially at (X_INITIAL, 
  13872. Y_INITIAL) or the current position if an initial position is not given. Draws a 
  13873. "rubber band" line from (X_START,Y_START) to (X_END,Y_END) (or the current 
  13874. position if not given) as two line segments via the location of the pointer. 
  13875. Returns the same data as for the 0 case. 
  13876.  
  13877. CΓò£'POINT' (3,X_START,Y_START[,X_END,Y_END [,X_INITIAL,Y_INITIAL]]) 
  13878.  
  13879. Same as for 2 option, but an additional line is drawn to form a "rubber band" 
  13880. triangle between (X_START,Y_START), (X_END,Y_END) and the current pointer 
  13881. location. Returns the same data as for the 0 case. 
  13882.  
  13883. CΓò£'POINT' (4[,X_START,Y_START[,X_INITIAL, Y_INITIAL]]) 
  13884.  
  13885. Same as for 1 option, but draws a "rubber band" rectangle with one corner at 
  13886. (X_START,Y_START) and the opposite corner at (X_INITIAL,Y_INITIAL) or the 
  13887. current position if an initial position is not given. Returns the same data as 
  13888. for the 0 case. 
  13889.  
  13890. CΓò£'POINT' ('') 
  13891.  
  13892. Immediately returns the graphics pointer position and mouse button status. 
  13893. Returns 0,X_POINTER,Y_POINTER[,BUTTON_NOS]. If the pointer lies outside of the 
  13894. AP 207 window, X_POINTER and Y_POINTER are still relative to the lower-left 
  13895. corner; therefore, negative values are possible. BUTTON_NOS are the numbers of 
  13896. any mouse buttons currently pressed. 
  13897.  
  13898.  
  13899. ΓòÉΓòÉΓòÉ 14.8.2.25. PRINT-Description: ΓòÉΓòÉΓòÉ
  13900.  
  13901. Dumps the graphic window contents to the currently-selected printer. 
  13902.  
  13903. Notes: 
  13904.  
  13905.  1. The Printer Setup menu item gives access to change the default printer and 
  13906.     job properties. 
  13907.  
  13908.  2. Metafiles and print files that contain bitmap or image data may require the 
  13909.     printer-specific job property to be on, or the spooler to be disabled. 
  13910.  
  13911.  
  13912. ΓòÉΓòÉΓòÉ 14.8.2.25.1. PRINT-Syntax ΓòÉΓòÉΓòÉ
  13913.  
  13914. CΓò£'PRINT' 'FILESPEC' 
  13915.  
  13916. Creates an OS/2 metafile if no file by that name currently exists. The metafile 
  13917. can be dropped on any printer object. 
  13918.  
  13919. CΓò£'PRINT' ('') 
  13920.  
  13921. Prints the window contents on the default printer. 
  13922.  
  13923.  
  13924. ΓòÉΓòÉΓòÉ 14.8.2.26. QUERY-Description: ΓòÉΓòÉΓòÉ
  13925.  
  13926. Queries driver parameters. Returns the active Presentation Manager display as 
  13927. driver 1. This is the only driver supported for OS/2. 
  13928.  
  13929.  
  13930. ΓòÉΓòÉΓòÉ 14.8.2.26.1. QUERY-Syntax ΓòÉΓòÉΓòÉ
  13931.  
  13932. CΓò£'QUERY' ('') 
  13933.  
  13934. Returns:  DRIVER_NAME,PARMS 
  13935.  
  13936. The default driver name is ""OS/2 Presentation Manager"." PARMS is a numeric 
  13937. matrix, each row of which is: 
  13938.  
  13939. [;1]    Video mode. Only one mode (mode 1) is supported by the OS/2 services 
  13940.         driver. 
  13941. [;2]    Width of screen in pels 
  13942. [;3]    Height of screen in pels 
  13943. [;4]    Number of different colors displayable 
  13944. [;5]    Number of different line styles available 
  13945. [;6]    Number of different line widths available 
  13946. [;7]    Number of different fill patterns available 
  13947. [;8]    Number of different markers available 
  13948. [;9 10] Aspect ratio. The ratio of these two numbers (╨Ä/PARMS[;9 10]) gives the 
  13949.         x size of a pel divided by the y size of a pel. 
  13950.  
  13951. The width and height of screen are given as the total physical screen size 
  13952. before an OPEN call is issued, and are given as the current AP 207 window size 
  13953. after an OPEN call. 
  13954.  
  13955.  
  13956. ΓòÉΓòÉΓòÉ 14.8.2.27. QWRITE-Description: ΓòÉΓòÉΓòÉ
  13957.  
  13958. Returns the position and size of the character string specified. 
  13959.  
  13960.  
  13961. ΓòÉΓòÉΓòÉ 14.8.2.27.1. QWRITE-Syntax ΓòÉΓòÉΓòÉ
  13962.  
  13963. CΓò£'QWRITE' 'TEXT' 
  13964.  
  13965. Returns six elements specifying the x and y coordinates of the lower-left, 
  13966. upper-left and the lower-right corners of the text box assuming it is placed at 
  13967. the current x and y location. The coordinates of the remaining corner 
  13968. (upper-right) can be readily calculated from the three given. 
  13969.  
  13970.  
  13971. ΓòÉΓòÉΓòÉ 14.8.2.28. SCISSOR-Description: ΓòÉΓòÉΓòÉ
  13972.  
  13973. Defines the rectangular area within which graphics can be drawn. Any parts of a 
  13974. graphics object falling outside of this rectangle are clipped at the boundary. 
  13975. Initially, the scissoring rectangle is set to the window boundary. 
  13976.  
  13977. Setting the system window to (0 0 0 0) turns off scissoring. The default is 
  13978. off. 
  13979.  
  13980.  
  13981. ΓòÉΓòÉΓòÉ 14.8.2.28.1. SCISSOR-Syntax ΓòÉΓòÉΓòÉ
  13982.  
  13983. CΓò£'SCISSOR' (X1,Y1,X2,Y2) 
  13984.  
  13985. Defines the lower-left and upper-right corners of the scissoring rectangle in 
  13986. world coordinate units. Returns the new scissoring rectangle selected. 
  13987.  
  13988. CΓò£'SCISSOR' ('') 
  13989.  
  13990. Returns the current scissoring rectangle. 
  13991.  
  13992.  
  13993. ΓòÉΓòÉΓòÉ 14.8.2.29. SECTOR/WEDGE-Description: ΓòÉΓòÉΓòÉ
  13994.  
  13995. Draw a sector of an ellipse or a circle. If used between a BEGAREA and an 
  13996. ENDAREA, each sector is filled independently. 
  13997.  
  13998.  
  13999. ΓòÉΓòÉΓòÉ 14.8.2.29.1. SECTOR/WEDGE-Syntax ΓòÉΓòÉΓòÉ
  14000.  
  14001. CΓò£'SECTOR/WEDGE' (X,Y,X_RAD,Y_RAD,START_ANG,END_ANG) 
  14002.  
  14003. Where 
  14004.  
  14005. X,Y       give the center of the sector 
  14006. X_RAD,Y_RAD give the radius of the sector along the x and y axes 
  14007. START_ANG,END_ANG give the starting and ending angles of the sector in degrees 
  14008. The current position is set to the coordinate of the center of the sector. 
  14009.  
  14010.  
  14011. ΓòÉΓòÉΓòÉ 14.8.2.30. SETPEL-Description: ΓòÉΓòÉΓòÉ
  14012.  
  14013. Sets one or more pels to the specified color. 
  14014.  
  14015.  
  14016. ΓòÉΓòÉΓòÉ 14.8.2.30.1. SETPEL-Syntax ΓòÉΓòÉΓòÉ
  14017.  
  14018. CΓò£'SETPEL' (COLOR,X,Y) 
  14019.  
  14020. Sets the pel at (X,Y) to the color defined by the row COLOR in the color map 
  14021. array. 
  14022.  
  14023. CΓò£'SETPEL' ((N,3)╤åCOLOR1,X1,Y1,...,COLORN,XN,YN) 
  14024.  
  14025. Sets the pel at each X,Y location to the corresponding color in the color map 
  14026. array. 
  14027.  
  14028.  
  14029. ΓòÉΓòÉΓòÉ 14.8.2.31. USE-Description: ΓòÉΓòÉΓòÉ
  14030.  
  14031. Select a driver for subsequent use by AP 207. 
  14032.  
  14033. Note:  This command is ignored by APL2/2. 
  14034.  
  14035.  
  14036. ΓòÉΓòÉΓòÉ 14.8.2.31.1. USE-Syntax ΓòÉΓòÉΓòÉ
  14037.  
  14038. CΓò£'USE' 0 
  14039.  
  14040. Device 0 is the internal OS/2 services driver. This is automatically used when 
  14041. AP 207 is started and need not be explicitly specified. 
  14042.  
  14043. CΓò£'USE' ('') 
  14044.  
  14045. Returns the name of the current driver. 
  14046.  
  14047. Note:  May not be used in a multiple-call sequence. 
  14048.  
  14049.  
  14050. ΓòÉΓòÉΓòÉ 14.8.2.32. VIEW-Description: ΓòÉΓòÉΓòÉ
  14051.  
  14052. View the graphics and wait for a user input. 
  14053.  
  14054.  
  14055. ΓòÉΓòÉΓòÉ 14.8.2.32.1. VIEW-Syntax ΓòÉΓòÉΓòÉ
  14056.  
  14057. CΓò£'VIEW' ('') 
  14058.  
  14059. Makes the AP 207 window the active window. This is the only portable VIEW 
  14060. syntax. 
  14061.  
  14062. CΓò£'VIEW' ('ON') 
  14063.  
  14064. Makes the AP 207 window the active window. The handle of the program that was 
  14065. active when this command was issued is saved for use. 
  14066.  
  14067. CΓò£'VIEW' ('OFF') 
  14068.  
  14069. Restores the active status to the window saved by the previous ON command. 
  14070.  
  14071. CΓò£'VIEW' (XLEFT,YBOTTOM,XRIGHT,YTOP) 
  14072.  
  14073. Sets the area of interest to be displayed in the window. When the window is 
  14074. sized, the contents of the window are scaled as needed to maintain aspect 
  14075. ratio. 
  14076.  
  14077.  
  14078. ΓòÉΓòÉΓòÉ 14.8.2.33. WAIT-Description: ΓòÉΓòÉΓòÉ
  14079.  
  14080. Wait for a user input or other event. 
  14081.  
  14082.  
  14083. ΓòÉΓòÉΓòÉ 14.8.2.33.1. WAIT-Syntax ΓòÉΓòÉΓòÉ
  14084.  
  14085. CΓò£'WAIT' N 
  14086.  
  14087. Waits for N seconds. If N is 0, it returns immediately. Returns: 
  14088.  
  14089. 0,TIME,X,Y if no event occurred during the specified interval 
  14090. 1,TIME,X,Y,BUTTON_NO,BPR if a mouse button was either pressed or released 
  14091. 2,TIME,X,Y,C,S if a keyboard key was pressed 
  14092.  
  14093.  TIME is the time (in seconds) that the event was detected. X and Y give the 
  14094. current graphic pointer position. X or Y may be negative if the cursor is 
  14095. outside of the AP 207 window. BUTTON_NO is the number of the mouse button that 
  14096. was pressed or released, and BPR is 1 if the button has been pressed, or 0 if 
  14097. the button has been released. C and S are the character code and scan code as 
  14098. returned by the AP124 calls (3 1), (3 2), and (3 3) as described for AP 124 
  14099. under Read and Wait or Read and Test. 
  14100.  
  14101. To clear all queued events, use the expression: Γòò(0╨çΓò₧1ΓòƒSHR207,SHR207Γò£'WAIT' 
  14102. 0)/╨áLC 
  14103.  
  14104. CΓò£'WAIT' ('') 
  14105.  
  14106. Waits indefinitely for an event. Returns the same data as above, except that 
  14107. the 0 time-out case is never returned. 
  14108.  
  14109.  
  14110. ΓòÉΓòÉΓòÉ 14.8.2.34. WINDOW-Description: ΓòÉΓòÉΓòÉ
  14111.  
  14112. Define a window on the device for graphics and establish a world coordinate 
  14113. system to be mapped into this window. See Defining World Coordinates with 
  14114. Correct Aspect Ratio for details of using this call to preserve screen aspect 
  14115. ratios. 
  14116.  
  14117.  
  14118. ΓòÉΓòÉΓòÉ 14.8.2.34.1. WINDOW-Syntax ΓòÉΓòÉΓòÉ
  14119.  
  14120. CΓò£'WINDOW' (WINDOW,VIEWPORT) 
  14121.  
  14122. WINDOW=WX1,WY1,WX2,WY2-Specifies the bottom left and top right of the display 
  14123. window box in device (pel) coordinates. VIEWPORT=VX1,VY1,VX2,VY2-Specifies 
  14124. world coordinates corresponding to the bottom left and top right of the window. 
  14125.  
  14126. CΓò£'WINDOW' ('') 
  14127.  
  14128. Returns the current window and viewport parameters. The window defaults to the 
  14129. entire screen, and the viewport defaults to the device (pel) coordinates. 
  14130.  
  14131. Note:  (This parameter may not be used in a multiple-call sequence.) 
  14132.  
  14133.  
  14134. ΓòÉΓòÉΓòÉ 14.8.2.35. WRITE-Description: ΓòÉΓòÉΓòÉ
  14135.  
  14136. Write some text in the current setting of color, font, and position. 
  14137.  
  14138.  
  14139. ΓòÉΓòÉΓòÉ 14.8.2.35.1. WRITE-Syntax ΓòÉΓòÉΓòÉ
  14140.  
  14141. CΓò£'WRITE' 'TEXT' 
  14142.  
  14143. Writes text at the current position. Returns eight elements specifying the x 
  14144. and y coordinates of the lower-left, upper-left, lower-right and upper-right 
  14145. corners of the text box. 
  14146.  
  14147.  
  14148. ΓòÉΓòÉΓòÉ 14.8.3. Multiple-Call Sequences ΓòÉΓòÉΓòÉ
  14149.  
  14150. Several commands can be issued to AP 207 in a single call. This requires the 
  14151. calls to be catenated into an even-length vector with alternating commands and 
  14152. parameters. The result is one longer than the number of commands. Its first 
  14153. element is the highest return code encountered in all the calls issued, 
  14154. followed by the return codes from each individual call. For example: 
  14155.  
  14156.       SHR207Γò£'COLOR' 'BLUE' 'ARC' (100 100 50 50 0 360)
  14157.       DISPLAY ╨áΓò£SHR207
  14158.   0      0  1    0
  14159. ΓöîΓòòΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  14160. Γöé ΓöîΓòòΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ ΓöîΓòòΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ ΓöîΓòòΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ Γöé
  14161. Γöé Γöé   Γöî╤ëΓöÉ Γöé Γöé   ΓöîΓòòΓöÉ Γöé Γöé   Γöî╤ëΓöÉ Γöé Γöé
  14162. Γöé Γöé 0 Γöé0Γöé Γöé Γöé 0 Γöé1Γöé Γöé Γöé 0 Γöé0Γöé Γöé Γöé
  14163. Γöé Γöé   Γöö~Γöÿ Γöé Γöé   Γöö~Γöÿ Γöé Γöé   Γöö~Γöÿ Γöé Γöé
  14164. Γöé Γöö╤ÄΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ Γöö╤ÄΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ Γöö╤ÄΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ Γöé
  14165. └ю──────────────────────────────┘
  14166.  
  14167. This enables you to use the expression 0╨çΓò₧Γò₧SHR207 to establish whether or not 
  14168. an error occurred in any of the calls issued. 
  14169.  
  14170.  
  14171. ΓòÉΓòÉΓòÉ 14.8.4. Defining World Coordinates with Correct Aspect Ratio ΓòÉΓòÉΓòÉ
  14172.  
  14173. To get the aspect ratio for a particular mode after a window has been opened 
  14174. (using the OPEN command): 
  14175.  
  14176. РIO╜1
  14177. SHR207Γò£'OPEN' ''
  14178. (RC MODE)Γò£SHR207
  14179. MODEΓò£Γò₧MODE
  14180. SHR207Γò£'QUERY' ''
  14181. (RC DRIVER PARMS)Γò£SHR207
  14182. PARMSΓò£╤âPARMS                  ╤ä Data for supported modes
  14183. QΓò£,(PARMS[;1]=''╤åMODE)╨üPARMS  ╤ä Q is data for this mode
  14184. AR_PELΓò£╨Ä/Q[9 10]              ╤ä Ratio of pel x to y size
  14185. AR_SCRNΓò£╨Ä/Q[2 3]╤ùQ[9 10]      ╤ä Screen aspect ratio.
  14186.  
  14187. Usually you want to define a set of world coordinates that are independent of 
  14188. the actual pel coordinates on the screen. This is done by using the WINDOW call 
  14189. to AP 207. In many cases, the world coordinates should preserve aspect ratio; 
  14190. that is, one unit in world coordinates in the x direction should be the same 
  14191. physical size on the device as one unit in world coordinates in the y 
  14192. direction. The following example is useful in defining a world coordinate 
  14193. system that preserves aspect ratio. To map the whole screen to world 
  14194. coordinates ranging from 0 to 1000 in x and pick the maximum y world coordinate 
  14195. to preserve aspect ratio: 
  14196.  
  14197. WIN_PARMSΓò£0 0,(Q[2 3]-1),0 0 1000,┬ñ1+Γò¢0.5+1001╨ÄAR_SCRN
  14198. SHR207Γò£'WINDOW' WIN_PARMS
  14199.  
  14200.  
  14201. ΓòÉΓòÉΓòÉ 14.8.5. Image and Vector Font Support ΓòÉΓòÉΓòÉ
  14202.  
  14203. AP 207 can use either external image (bitmap) or vector font files in writing 
  14204. text. This support provides for rapid display of characters from any of a 
  14205. variety of fonts. 
  14206.  
  14207. Image (bitmap) fonts are easy to read in small sizes since they are mapped 
  14208. directly to the pels on the screen. They differ in appearance on different 
  14209. displays and in printed copies. The minimum size may also be larger than 
  14210. desired. 
  14211.  
  14212. Vector fonts can be scaled to any size and rotated, sheared, or stretched as 
  14213. desired. They are device-independent, although they may be somewhat distorted 
  14214. on low-resolution displays. 
  14215.  
  14216. The vector fonts supplied with APL2/2 are listed below. Most of the fonts 
  14217. consist of straight-line segments only. Thus the space between the vectors may 
  14218. become visible for characters in larger sizes. Fonts labeled as "Filled" use 
  14219. the AP 207 area filling routines to fill the character interiors. These 
  14220. characters look better in large sizes, although they are slower to draw and may 
  14221. not look as good in small sizes. 
  14222.  
  14223. o AP 207 Vector Fonts Supplied 
  14224. o AP 207 Vector Font File Format 
  14225. o Font Index 
  14226. o Font Width Table 
  14227. o Font Character Definition Data 
  14228.  
  14229.  
  14230. ΓòÉΓòÉΓòÉ 14.8.5.1. AP 207 Vector Fonts Supplied ΓòÉΓòÉΓòÉ
  14231.  
  14232. See Supplied vector fonts. 
  14233.  
  14234.  
  14235. ΓòÉΓòÉΓòÉ 14.8.5.1.1. Supplied vector fonts - Part 1 ΓòÉΓòÉΓòÉ
  14236.  
  14237.  
  14238. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14239.  
  14240. Font file name 
  14241.  
  14242.  
  14243. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14244.  
  14245. Description 
  14246.  
  14247.  
  14248. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14249.  
  14250. GOTENG.AVF 
  14251.  
  14252.  
  14253. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14254.  
  14255. Gothic English 
  14256.  
  14257.  
  14258. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14259.  
  14260. GOTGER.AVF 
  14261.  
  14262.  
  14263. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14264.  
  14265. Gothic German 
  14266.  
  14267.  
  14268. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14269.  
  14270. GOTITA.AVF 
  14271.  
  14272.  
  14273. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14274.  
  14275. Gothic Italian 
  14276.  
  14277.  
  14278. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14279.  
  14280. GRESER.AVF 
  14281.  
  14282.  
  14283. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14284.  
  14285. Greek Serif (with some mathematical symbols) 
  14286.  
  14287.  
  14288. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14289.  
  14290. GRESIM.AVF 
  14291.  
  14292.  
  14293. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14294.  
  14295. Greek Simplex (with some mathematical symbols) 
  14296.  
  14297.  
  14298. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14299.  
  14300. MARKERS.AVF 
  14301.  
  14302.  
  14303. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14304.  
  14305. Markers (correspond to image markers from MARKERS call) 
  14306.  
  14307.  
  14308. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14309.  
  14310. MODSIM.AVF 
  14311.  
  14312.  
  14313. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14314.  
  14315. Modern Simplex 
  14316.  
  14317.  
  14318. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14319.  
  14320. ROMDUP.AVF 
  14321.  
  14322.  
  14323. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14324.  
  14325. Roman Duplex 
  14326.  
  14327.  
  14328. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14329.  
  14330. ROMDUPF.AVF 
  14331.  
  14332.  
  14333. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14334.  
  14335. Roman Duplex Filled 
  14336.  
  14337.  
  14338. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14339.  
  14340. ROMITA.AVF 
  14341.  
  14342.  
  14343. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14344.  
  14345. Roman Italic 
  14346.  
  14347.  
  14348. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14349.  
  14350. ROMITAB.AVF 
  14351.  
  14352.  
  14353. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14354.  
  14355. Roman Italic Bold 
  14356.  
  14357.  
  14358. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14359.  
  14360. ROMSER.AVF 
  14361.  
  14362.  
  14363. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14364.  
  14365. Roman Serif 
  14366.  
  14367.  
  14368. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14369.  
  14370. ROMSERB.AVF 
  14371.  
  14372.  
  14373. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14374.  
  14375. Roman Serif Bold 
  14376.  
  14377.  
  14378. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14379.  
  14380. ROMSIM.AVF 
  14381.  
  14382.  
  14383. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14384.  
  14385. Roman Simplex (contains full set of code page 910 characters) 
  14386.  
  14387.  
  14388. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14389.  
  14390. MORE... 
  14391.  
  14392.  
  14393. ΓòÉΓòÉΓòÉ 14.8.5.1.2. Supplied vector fonts - Part 2 ΓòÉΓòÉΓòÉ
  14394.  
  14395.  
  14396. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14397.  
  14398. Font file name 
  14399.  
  14400.  
  14401. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14402.  
  14403. Description 
  14404.  
  14405.  
  14406. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14407.  
  14408. ROMSIMM.AVF 
  14409.  
  14410.  
  14411. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14412.  
  14413. Roman Simplex Monospace (monospace version of ROMSIM.AVF) 
  14414.  
  14415.  
  14416. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14417.  
  14418. SANSER.AVF 
  14419.  
  14420.  
  14421. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14422.  
  14423. Sans Serif 
  14424.  
  14425.  
  14426. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14427.  
  14428. SANSERF.AVF 
  14429.  
  14430.  
  14431. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14432.  
  14433. Sans Serif Filled 
  14434.  
  14435.  
  14436. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14437.  
  14438. SCRIPT.AVF 
  14439.  
  14440.  
  14441. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14442.  
  14443. Script 
  14444.  
  14445.  
  14446. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14447.  
  14448. THKRNDF.AVF 
  14449.  
  14450.  
  14451. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14452.  
  14453. Thick Round Filled 
  14454.  
  14455.  
  14456. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14457.  
  14458. THKRNDO.AVF 
  14459.  
  14460.  
  14461. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14462.  
  14463. Thick Round Outlined 
  14464.  
  14465.  
  14466. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14467.  
  14468. THKSQUF.AVF 
  14469.  
  14470.  
  14471. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14472.  
  14473. Thick Square Filled 
  14474.  
  14475.  
  14476. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14477.  
  14478. THKSQUO.AVF 
  14479.  
  14480.  
  14481. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14482.  
  14483. Thick Square Outlined 
  14484.  
  14485.  
  14486. ΓòÉΓòÉΓòÉ 14.8.5.2. AP 207 Vector Font File Format ΓòÉΓòÉΓòÉ
  14487.  
  14488. AP 207 vector fonts are stored in files with a file extension of ".AVF" (APL 
  14489. Vector Font.) Each file defines 256 vector characters. Code page 910 is used to 
  14490. assign the characters to the code points except for fonts consisting of special 
  14491. characters not included in code page 910. The files consist of four parts 
  14492. described in more detail below: See Vector font format. See Font header format. 
  14493.  
  14494.  
  14495. ΓòÉΓòÉΓòÉ 14.8.5.2.1. Vector font format ΓòÉΓòÉΓòÉ
  14496.  
  14497.  
  14498. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14499.  
  14500. Start byte 
  14501.  
  14502.  
  14503. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14504.  
  14505. Length 
  14506.  
  14507.  
  14508. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14509.  
  14510. Description 
  14511.  
  14512.  
  14513. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14514.  
  14515.  
  14516.  
  14517. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14518.  
  14519. 32 
  14520.  
  14521.  
  14522. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14523.  
  14524. Font header 
  14525.  
  14526.  
  14527. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14528.  
  14529. 32 
  14530.  
  14531.  
  14532. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14533.  
  14534. 514 
  14535.  
  14536.  
  14537. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14538.  
  14539. Font index 
  14540.  
  14541.  
  14542. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14543.  
  14544. 546 
  14545.  
  14546.  
  14547. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14548.  
  14549. 512 
  14550.  
  14551.  
  14552. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14553.  
  14554. Font width table 
  14555.  
  14556.  
  14557. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14558.  
  14559. 1058 
  14560.  
  14561.  
  14562. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14563.  
  14564. Variable 
  14565.  
  14566.  
  14567. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14568.  
  14569. Font character definitions 
  14570.  
  14571.  
  14572. ΓòÉΓòÉΓòÉ 14.8.5.2.2. Font header format - Part 1 ΓòÉΓòÉΓòÉ
  14573.  
  14574.  
  14575. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14576.  
  14577. Start byte 
  14578.  
  14579.  
  14580. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14581.  
  14582. Length 
  14583.  
  14584.  
  14585. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14586.  
  14587. Description 
  14588.  
  14589.  
  14590. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14591.  
  14592.  
  14593.  
  14594. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14595.  
  14596.  
  14597.  
  14598. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14599.  
  14600. Total number of bytes in the file 
  14601.  
  14602.  
  14603. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14604.  
  14605.  
  14606.  
  14607. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14608.  
  14609.  
  14610.  
  14611. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14612.  
  14613. Font type: 
  14614.  
  14615. 1:   2-byte vector font (this is the only type currently allowed) 
  14616.  
  14617.  
  14618. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14619.  
  14620.  
  14621.  
  14622. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14623.  
  14624.  
  14625.  
  14626. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14627.  
  14628. Flags (bit 0 is low-order bit): 
  14629.  
  14630. Bit 0: 0 = Monospace font 
  14631.        1 = Proportionally spaced font 
  14632. Bits 1-15: Reserved 
  14633.  
  14634.  
  14635. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14636.  
  14637.  
  14638.  
  14639. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14640.  
  14641.  
  14642.  
  14643. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14644.  
  14645. Maximum character width in the font 
  14646.  
  14647.  
  14648. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14649.  
  14650. 10 
  14651.  
  14652.  
  14653. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14654.  
  14655.  
  14656.  
  14657. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14658.  
  14659. Height of capital letters 
  14660.  
  14661.  
  14662. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14663.  
  14664. MORE... 
  14665.  
  14666.  
  14667. ΓòÉΓòÉΓòÉ 14.8.5.2.3. Font header format - Part 2 ΓòÉΓòÉΓòÉ
  14668.  
  14669.  
  14670. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14671.  
  14672. Start byte 
  14673.  
  14674.  
  14675. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14676.  
  14677. Length 
  14678.  
  14679.  
  14680. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14681.  
  14682. Description 
  14683.  
  14684.  
  14685. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14686.  
  14687. 12 
  14688.  
  14689.  
  14690. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14691.  
  14692.  
  14693.  
  14694. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14695.  
  14696. Recommended vertical spacing between lines (height of the character box) 
  14697.  
  14698.  
  14699. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14700.  
  14701. 14 
  14702.  
  14703.  
  14704. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14705.  
  14706.  
  14707.  
  14708. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14709.  
  14710. Distance from baseline (y=0) to bottom of the character box 
  14711.  
  14712.  
  14713. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14714.  
  14715. 16 
  14716.  
  14717.  
  14718. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14719.  
  14720. 16 
  14721.  
  14722.  
  14723. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  14724.  
  14725. Reserved (must be 0) 
  14726.  
  14727.  
  14728. ΓòÉΓòÉΓòÉ 14.8.5.3. Font Index ΓòÉΓòÉΓòÉ
  14729.  
  14730. These 514 bytes consist of 257 two-byte unsigned integers that give the offset 
  14731. from the beginning of the font character definitions of the definition of each 
  14732. of the 256 characters. These offsets are in units of two bytes since each 
  14733. coordinate is stored in two bytes (see below). These 256 integers are followed 
  14734. by an integer that contains the total number of byte pairs of font character 
  14735. definition data. The first of the 257 integers must always be 0 since the 
  14736. definition of the first character is always at offset 0. If a character in the 
  14737. font is not defined, two successive entries in the index are the same. 
  14738.  
  14739.  
  14740. ΓòÉΓòÉΓòÉ 14.8.5.4. Font Width Table ΓòÉΓòÉΓòÉ
  14741.  
  14742. The next 512 bytes consist of 256 two-byte signed integers containing the 
  14743. widths of each of the 256 characters in the font. If a character is undefined, 
  14744. its width must be 0. For a monospace font, all the entries are equal to the 
  14745. number in the maximum character width field in the file header. 
  14746.  
  14747.  
  14748. ΓòÉΓòÉΓòÉ 14.8.5.5. Font Character Definition Data ΓòÉΓòÉΓòÉ
  14749.  
  14750. The remaining bytes consist of the vector data for the characters in the font. 
  14751. Each coordinate is stored in two bytes; the first contains the x coordinate 
  14752. information, and the second contains the y information. The high-order bit of x 
  14753. contains the beam-blanking information: a vector is drawn to this point with 
  14754. the beam on if this bit is 1, and off if it is 0. The high-order bit of y 
  14755. contains information on filled areas. When this bit changes from 0 to 1, a 
  14756. BEGAREA call is generated before the vector is drawn. When it changes from 1 to 
  14757. 0, an ENDAREA call is generated before the vector is drawn. 
  14758.  
  14759. The remaining seven bits for x and y are interpreted as unsigned integers, and 
  14760. 64 is subtracted to obtain a pair of integers (x and y) in the range -64 to 63. 
  14761. These give the relative length of the vector to be drawn in x and y. All 
  14762. characters start at coordinate (0,0), and the last vector must end at y=0. The 
  14763. character baseline (bottom of "A") is at y=0. 
  14764.  
  14765. The following APL2 function extracts the character definition for single 
  14766. character C from the font data stored as a global character vector called 
  14767. FONTDATA, which can be read in as one long record using AP 210's Code C. 
  14768.  
  14769.     Γòû
  14770. [0]  ZΓò£GETFONT C;BEAM;FDATA;FHEADER;FILL;FINDEX;XY;╨áIO
  14771. [1]   ╨áIOΓò£1
  14772. [2]  ╤ä FONTDATA is the font data in byte format.
  14773. [3]  ╤ä It contains a 32-byte header, 514-byte index,
  14774. [4]  ╤ä 512-byte width table, and font definition data.
  14775. [5]   FHEADERΓò£256╨¡╤ì16 2╤å╨áAF 32Γò₧FONTDATA
  14776. [6]   FINDEXΓò£256╨¡╤ì257 2╤å╨áAF 32Γòƒ546Γò₧FONTDATA
  14777. [7]   FDATAΓò£((┬ñ1Γò₧FINDEX),2)╤å1058ΓòƒFONTDATA
  14778. [8]   CΓò£╨áAF ''╤åC
  14779. [9]  ╤ä Get rows of FDATA which describe character C
  14780. [10]  ZΓò£╨áAF FDATA[FINDEX[1+C]+╤î-/FINDEX[2 1+C];]
  14781. [11]  BEAMΓò£Z[;1]╨ä128
  14782. [12]  FILLΓò£Z[;2]╨ä128
  14783. [13]  XYΓò£+╤æ┬ñ64+128ΓöéZ
  14784. [14] ╤ä Z is a 4-column matrix:  beam off/on,
  14785. [15] ╤ä fill off/on, x coord, y coord
  14786. [16]  ZΓò£BEAM,FILL,XY
  14787.     Γòû
  14788.  
  14789.  
  14790. ΓòÉΓòÉΓòÉ 14.8.6. AP 207 Return Codes ΓòÉΓòÉΓòÉ
  14791.  
  14792. AP 207 return codes are returned as the first element of the two elements 
  14793. returned for each call. 
  14794.  
  14795. Code      Meaning 
  14796.   0 -     Success 
  14797.   1 -     Unexpected driver or subsystem error 
  14798.  30 -     Display mode not supported by this driver 
  14799.  31 -     Invalid command 
  14800.  32 -     Shared variable domain error 
  14801.  33 -     Shared variable length error 
  14802.  34 -     Shared variable rank error 
  14803.  35 -     Invalid device handle 
  14804.  36 -     No device currently selected 
  14805.  37 -     Call not available with this driver or in this mode 
  14806.  38 -     Call not permitted in multiple-call sequence 
  14807.  39 -     Invalid parameter 
  14808.  40 -     Scissor boundary outside window 
  14809.  41 -     Attempt to place point outside of window 
  14810.  42 -     Conflicting window-viewport definition 
  14811.  50 -     Invalid video mode for this driver 
  14812.  51 -     Device was not opened 
  14813.  52 -     No fill area started 
  14814.  53 -     Insufficient space for fill point storage 
  14815.  54 -     Printer not ready 
  14816.  55 -     Incorrect escape command 
  14817.  56 -     Device not available 
  14818.  57 -     Error while loading device driver 
  14819.  58 -     Invalid device driver 
  14820.  60 -     Font table is full 
  14821.  61 -     Requested font not in font table 
  14822.  62 -     Unable to load requested font 
  14823.  99 -     Command not implemented 
  14824. ┬ñ26 -     Insufficient space 
  14825.  
  14826.  
  14827. ΓòÉΓòÉΓòÉ 14.9. AP 210-The File Auxiliary Processor ΓòÉΓòÉΓòÉ
  14828.  
  14829. The file auxiliary processor, AP 210, is used to read from, or write to, fixed- 
  14830. or variable-length OS/2 disk files under control of the OS/2 file system. The 
  14831. reading and writing can be either sequential or random. 
  14832.  
  14833. Two shared variables are required to process a file: a data variable and a 
  14834. control variable. The control variable must be offered first. AP 210 then 
  14835. matches the earliest pending corresponding data variable offered by the partner 
  14836. (after the control variable). This occurs the first time it is required to 
  14837. satisfy an AP 210 command. 
  14838.  
  14839. The name of the data variable must always begin with the letter "D" or the 
  14840. letters "DAT", and the control variable must begin with the letter "C" or the 
  14841. letters "CTL". The remaining characters in both names (possibly none) must be 
  14842. the same, because the coupling of both variables is recognized by their name. 
  14843. Examples of valid pairs are:  C and D, C1 and D1, and CXjj and DXjj. Also 
  14844. accepted as valid pairs (for compatibility with APL2/370) are CTL and DAT or 
  14845. CTL1 and DAT1. The control variable is used to select the operation to perform 
  14846. and to control each input/output operation. For example: 
  14847.  
  14848.       210 SVOPAIR 'C210' 'D210'
  14849. 2 1
  14850.  
  14851. offers two shared variables to AP 210 and sets access control. See Using the 
  14852. Share-Offer Utilities for a description of the SVOPAIR function (from the 1 
  14853. UTILITY workspace). 
  14854.  
  14855. o Control Commands 
  14856. o Control Subcommands 
  14857. o Establishing the AP 210 Translate Table 
  14858. o AP 210 Return Codes 
  14859. o Example of Use 
  14860.  
  14861.  
  14862. ΓòÉΓòÉΓòÉ 14.9.1. Control Commands ΓòÉΓòÉΓòÉ
  14863.  
  14864. Once the control variable has been shared and the appropriate access control 
  14865. established, the first value you assign to it should be a character vector, 
  14866. which is considered to be a command that describes the file name and specifies 
  14867. the function to be performed. The following commands are accepted: 25i'. 
  14868.  
  14869.  IR,filespec[,code] Open for read-only 
  14870.  IW,filespec[,code] Open for read/write 
  14871.  DL,filespec Delete file 
  14872.  RN,filespec,filespec Rename file 
  14873.  
  14874. where filespec is the OS/2 file identification, of the form: 
  14875.  
  14876.  [path]filename
  14877.  
  14878. path is a valid OS/2 path and filename is a valid OS/2 file name. 
  14879.  
  14880. code is a single letter selecting a given interpretation of the file data. Five 
  14881. different interpretations are supported. 
  14882.  
  14883. Code           Interpretation of Data 
  14884.  
  14885. A (APL2)       The records in the file contain APL2 objects, with their 
  14886.                headers. Arrays of arbitrary rank and depth can be stored and 
  14887.                recovered. Different records of a file can contain objects of 
  14888.                different types (for example, characters, integers, or real 
  14889.                numbers). An APL2 object in a record may occupy up to the actual 
  14890.                record length (not necessarily the same number of bytes), but 
  14891.                the header fills a part of that area. 
  14892.  
  14893. B (Bool)       The records in the file contain strings of bits without any 
  14894.                header (packed eight bits per byte). The equivalent APL2 object 
  14895.                is a Boolean vector. In this case, all records must be equal to 
  14896.                the selected record length. 
  14897.  
  14898. C (Char)       The contents of the record is a string of characters in ASCII, 
  14899.                with no header. All records must be equal to the selected record 
  14900.                length with each character occupying one byte. Variable-length 
  14901.                records are not supported. 
  14902.  
  14903. D (ASCII)      The contents of the record is a string of characters in ASCII 
  14904.                code, with no header. Each character occupies one byte. 
  14905.                Variable-length records are supported. 
  14906.  
  14907. T (Translate)  The contents of the record is a string of characters, without 
  14908.                any header, translated according to the AP 210 translate table 
  14909.                defined as described in Establishing the AP 210 Translate Table. 
  14910.                All records must be equal to the selected record length except 
  14911.                when variable-length operations are being performed. 
  14912.  
  14913. If the code is not stated explicitly, code A is the default. 
  14914.  
  14915. The IR command opens the file for read-only operations. If the operation is 
  14916. successful, the control variable passes into the subcommand state. You must 
  14917. then specify which data transfer operation you want to perform. (See Control 
  14918. Subcommands.) The IW command works in a similar way, but the file is opened for 
  14919. both read and write operations. If the file cannot be opened, the control 
  14920. variable remains in the command state. 
  14921.  
  14922. When the DL command is received, the file with the specified filespec is 
  14923. erased. Then the control variable returns to the command state. 
  14924.  
  14925. When the RN command is received, the name of the file specified in the first 
  14926. parameter is changed to the name given in the second parameter. If a different 
  14927. path is given in the second parameter, a move is performed instead of a rename. 
  14928. After this command has been executed, the control variable returns to the 
  14929. command state. 
  14930.  
  14931. Once a command has been received and executed, a return code is passed back to 
  14932. APL2 through the control variable, indicating whether or not the command was 
  14933. executed successfully and, if not, the reason for the failure. 
  14934.  
  14935. If an IR or IW command executes successfully (giving a return code of 0 in the 
  14936. control variable), the data variable is set to the size, in bytes, of the file 
  14937. just opened. 
  14938.  
  14939.  
  14940. ΓòÉΓòÉΓòÉ 14.9.2. Control Subcommands ΓòÉΓòÉΓòÉ
  14941.  
  14942. Once a file has been opened for input (command IR) or input/output (command 
  14943. IW), the control variable passes into the subcommand state. It now accepts the 
  14944. assignment of numeric vectors specifying the operation to perform, with the 
  14945. following structure: 
  14946.  
  14947. C210Γò£op[,rn[,rs]] 
  14948.  
  14949. The following are valid operations: 
  14950.  
  14951. 0 -  Read a fixed-length record.  Record size is defaulted to 128 unless 
  14952.      specified by the rs operand or by a previous subcommand. Files are 
  14953.      considered as being divided into fixed size records. rn is the record 
  14954.      number. If not given, sequential operation is assumed. 
  14955.  
  14956. 1 -  Write a fixed-length record.  Record size is defaulted to 128 unless 
  14957.      specified by the rs operand or by a previous subcommand. Files are 
  14958.      considered as being divided into fixed size records. rn is the record 
  14959.      number. If not given, sequential operation is assumed. 
  14960.  
  14961. 2 -  Direct read from a file. Record size is defaulted to 128 unless specified 
  14962.      by the rs operand or by a previous subcommand. Files are considered as 
  14963.      being continuous strings of data. rn is the starting byte. If not given, 
  14964.      sequential operation is assumed. 
  14965.  
  14966. 3 -  Direct write to a file. Record size is defaulted to 128 unless specified 
  14967.      by the rs operand or by a previous subcommand. Files are considered as 
  14968.      being continuous strings of data. rn is the starting byte. If not given, 
  14969.      sequential operation is assumed. 
  14970.  
  14971. 4 -  Read a variable-length record. This command can only be used if the file 
  14972.      was opened with codes A, D, or T. rs is the scan distance. For codes D and 
  14973.      T, the LF character is searched for within the first rs bytes of a record. 
  14974.      If rs is not given, the LF character is searched for within the first 128 
  14975.      bytes, unless rs has been specified by a previous subcommand. If LF cannot 
  14976.      be located, the record is not read, and a return code ┬ñ44 is issued. rn is 
  14977.      the record number. If not given, sequential operation is assumed. If rn is 
  14978.      given but does not specify the next record in sequence, the file is 
  14979.      scanned from the beginning in search of the requested record. Either 
  14980.      specifying rn in sequence, or not specifying it at all, gives fastest 
  14981.      execution. 
  14982.  
  14983.      If reading with either code D or code T, the record returned in the data 
  14984.      variable includes any record delimiter characters (LF or CR/LF depending 
  14985.      on the origin of the file). 
  14986.  
  14987. 5 -  Write a variable-length record. This command can only be used if the file 
  14988.      was opened with codes A, D, or T. rn is the record number. If not given, 
  14989.      sequential operation is assumed. If rn is given but does not specify the 
  14990.      next record in sequence, the file is scanned from the beginning in search 
  14991.      of the requested record. Either specifying rn in sequence, or not 
  14992.      specifying it at all, gives fastest execution. If rn is greater than the 
  14993.      number of records currently in the file, the record is appended to the end 
  14994.      of the file. 
  14995.  
  14996.      Direct write of variable-length records is allowed, but should be done 
  14997.      with great care. Records should be replaced by others with exactly the 
  14998.      same length. If this is not done, the whole file, starting at the replaced 
  14999.      record, can be damaged. 
  15000.  
  15001.      If the file was opened with either code D or code T, the CR/LF delimiters 
  15002.      are appended to the end of each record as expected by OS/2 for sequential 
  15003.      files. If the record already has a LF character (╨áTC[╨áIO+2]) appended, no 
  15004.      additional delimiters are added. 
  15005.  
  15006.      Code A files have no need for the LF record separator, as each record 
  15007.      includes its own length, which makes each record self-describing, allowing 
  15008.      AP 210 to skip through the file to the requested record. 
  15009.  
  15010. 6 -  Operation 6 has the same syntax and behavior as operation 4, but 
  15011.      end-of-line indicators (either CR/LF or LF) are removed from the data. 
  15012.  
  15013. rn is always defined in zero origin (the first record in a file is record 0; 
  15014. the first byte in a file is byte 0). If not specifically stated, the first 
  15015. value of rn after opening a file is 0 (that is, the first record or byte 
  15016. position in the file). 
  15017.  
  15018. Write operations are not allowed if the subcommand state was entered through 
  15019. the IR command. 
  15020.  
  15021. If the control variable is assigned an empty vector while in the subcommand 
  15022. state, the file is closed and the control variable reverts to the command 
  15023. state. 
  15024.  
  15025. Retracting the shared variables, either explicitly, with ╨áSVR, or implicitly, 
  15026. by erasing the variables ()ERASE, ╨áEX, or, if the variables have been 
  15027. localized, by exiting the function), clearing the workspace ()CLEAR), loading a 
  15028. new workspace ()LOAD) or ending the session ()OFF) causes AP 210 to close the 
  15029. appropriate files automatically. 
  15030.  
  15031. Once an operation has been requested, the data variable is used as a buffer, 
  15032. where the actual transfer of records takes place. If the operation is a read, 
  15033. the value of the record can be found in the data variable after the successful 
  15034. completion of the requested operation (confirmed by the return code passed 
  15035. through the control variable). If the desired operation is a write, the value 
  15036. of the record must be assigned to the data variable before the corresponding 
  15037. subcommand is assigned to the control variable. 
  15038.  
  15039.  
  15040. ΓòÉΓòÉΓòÉ 14.9.3. Establishing the AP 210 Translate Table ΓòÉΓòÉΓòÉ
  15041.  
  15042. AP 210 can be supplied with a translate table for use with files opened with 
  15043. code T. Each file opened can have its own translate table. If no table has been 
  15044. defined, the data is not translated. The table can be defined or redefined, at 
  15045. any time, by: 
  15046.  
  15047.       C210Γò£2 256╤åREAD_TABLE,WRITE_TABLE
  15048.  
  15049. where READ_TABLE is applied to the data read as: 
  15050.  
  15051.       D210Γò£READ_TABLE[╨áAF DATA_READ]
  15052.  
  15053. and WRITE_TABLE is applied to the data written as: 
  15054.  
  15055.       DATA_WRITTENΓò£WRITE_TABLE[╨áAF D210]
  15056.  
  15057. Both READ_TABLE and WRITE_TABLE must be 256-element character vectors. 
  15058.  
  15059.  
  15060. ΓòÉΓòÉΓòÉ 14.9.4. AP 210 Return Codes ΓòÉΓòÉΓòÉ
  15061.  
  15062. The following table lists the AP 210 return codes: 
  15063.  
  15064. Code      Meaning 
  15065.   0 -     Success 
  15066.   1 -     Invalid command 
  15067.   2 -     File not found 
  15068. ┬ñ18 -     Insufficient User Authority 
  15069. ┬ñ26 -     No space available 
  15070. ┬ñ29 -     Invalid APL2 object 
  15071. ┬ñ31 -     Control variable domain error 
  15072. ┬ñ32 -     Control variable rank error 
  15073. ┬ñ33 -     Control variable length error 
  15074. ┬ñ36 -     Invalid file translation code 
  15075. ┬ñ37 -     Data variable value error 
  15076. ┬ñ38 -     Data variable domain error 
  15077. ┬ñ39 -     Data variable interlocked 
  15078. ┬ñ40 -     Data variable not shared 
  15079. ┬ñ41 -     File is not open, issue a primary command 
  15080. ┬ñ44 -     LF not found in scan length 
  15081. ┬ñ45 -     End of file 
  15082. ┬ñ46 -     Incomplete record, padded with nulls 
  15083. ┬ñ47 -     Invalid subcommand 
  15084. ┬ñ48 -     Record only partially written (file system full) 
  15085. ┬ñ49 -     Data variable size exceeds record size for fixed or variable replace 
  15086.  
  15087.  
  15088. ΓòÉΓòÉΓòÉ 14.9.5. Example of Use ΓòÉΓòÉΓòÉ
  15089.  
  15090. Starting with a clear workspace, offer variables C1 and D1 to share with AP 210 
  15091. using the SVOPAIR function from the 1 UTILITY workspace: 
  15092.  
  15093.       )CLEAR
  15094. CLEAR WS
  15095.       )COPY 1 UTILITY SVOPAIR
  15096. SAVED ...
  15097.       210 SVOPAIR 'C1' 'D1'
  15098. 2 1
  15099.  
  15100. Attempt to create a file called FILE. Records contain APL2 objects with header 
  15101. (default code): 
  15102.  
  15103.       C1Γò£'IW,FILE'
  15104.       C1
  15105. 0
  15106.  
  15107. We are now in subcommand mode. The first record is a vector of elements from 1 
  15108. to 10, so assign this to D1: 
  15109.  
  15110.       D1Γò£╤î10
  15111.  
  15112. Now issue the subcommand to write the first record in the file. The default 
  15113. record number is 0. 
  15114.  
  15115.       C1Γò£5
  15116.       C1
  15117. 0
  15118.  
  15119. Second record is a matrix of 2 rows, 3 columns, of elements from 1 to 6: 
  15120.  
  15121.       D1Γò£2 3╤å╤î6
  15122.  
  15123. Issue subcommand to write this record sequentially to the file: 
  15124.  
  15125.       C1Γò£5
  15126.       C1
  15127. 0
  15128.  
  15129. An empty vector closes the file and puts the control variable into command 
  15130. mode: 
  15131.  
  15132.       C1Γò£''
  15133.  
  15134. Open the same file for read-only operation: 
  15135.  
  15136.       C1Γò£'IR,FILE'
  15137.       C1
  15138. 0
  15139.  
  15140. Read the second record first: 
  15141.  
  15142.       C1Γò£4 1
  15143.       C1
  15144. 0
  15145.       D1
  15146.  1 2 3
  15147.  4 5 6
  15148.  
  15149. Read the first record: 
  15150.  
  15151.       C1Γò£4 0
  15152.       C1
  15153. 0
  15154.       D1
  15155. 1 2 3 4 5 6 7 8 9 10
  15156.  
  15157. Close the file and go into command state: 
  15158.  
  15159.       C1Γò£╤î0
  15160.  
  15161. Rename the file to NEWFILE: 
  15162.  
  15163.       C1Γò£'RN,FILE,NEWFILE'
  15164.       C1
  15165. 0
  15166.  
  15167. Delete the file: 
  15168.  
  15169.       C1Γò£'DL,NEWFILE'
  15170.       C1
  15171. 0
  15172.  
  15173. Finally, retract the shared variables: 
  15174.  
  15175.       ╨áSVR 2 2╤å'C1D1'
  15176. 2 2
  15177.  
  15178.  
  15179. ΓòÉΓòÉΓòÉ 14.10. AP 211-The APL2 Object Library Auxiliary Processor ΓòÉΓòÉΓòÉ
  15180.  
  15181. AP 211 provides a facility for storing APL2 arrays in an object library. 
  15182.  
  15183. AP 211 uses a single shared variable of any name to control access to a 
  15184. library. 
  15185.  
  15186. The following description of the commands accepted by AP 211 assumes that a 
  15187. variable called SHR211 has been shared with AP 211. For example: 
  15188.  
  15189.       211 SVOFFER 'SHR211'
  15190. 2
  15191.  
  15192. offers the shared variable to AP 211 and sets access control. See Using the 
  15193. Share-Offer Utilities for a description of the SVOFFER function. 
  15194.  
  15195. o Commands 
  15196. o AP 211 Return Codes 
  15197. o Example of Use 
  15198.  
  15199.  
  15200. ΓòÉΓòÉΓòÉ 14.10.1. Commands ΓòÉΓòÉΓòÉ
  15201.  
  15202. AP 211 accepts the following commands: 
  15203.  
  15204. o CREATE 
  15205. o DROP 
  15206. o USE 
  15207. o RELEASE 
  15208. o SET 
  15209. o GET 
  15210. o RENAME 
  15211. o ERASE 
  15212. o LIST 
  15213.  
  15214.  
  15215. ΓòÉΓòÉΓòÉ 14.10.1.1. CREATE ΓòÉΓòÉΓòÉ
  15216.  
  15217. This command creates an AP 211 object library and must be issued before APL2 
  15218. arrays can be assigned to a given library file. 
  15219.  
  15220.       SHR211Γò£'CREATE' filename [rec_size]
  15221.  
  15222. Where rec_size specifies the record size used to store APL2 objects in the 
  15223. file. APL2 objects stored in the library use one or more records depending on 
  15224. size. Objects smaller than the record size still use a full record and any 
  15225. excess space is wasted. Therefore, you should carefully select an optimum size 
  15226. for your APL2 objects to reduce the amount of wasted space in the file. 
  15227.  
  15228. The number of blocks that are used is given by:  ╨╣object_size╨Ärec_size 
  15229.  
  15230. where object_size can be obtained by: Γò₧4 ╨áAT object_name 
  15231.  
  15232. AP 211 uses a default record size of 1024 if none is specified. The record size 
  15233. must be in the range 128 to 32704 bytes. If the record size is not an exact 
  15234. multiple of 64 bytes, it is rounded up to the next multiple of 64 bytes. 
  15235.  
  15236. An error is given if the file already exists. It is the responsibility of the 
  15237. application developer to check that the name is not already in use and to erase 
  15238. the file if necessary. 
  15239.  
  15240.  
  15241. ΓòÉΓòÉΓòÉ 14.10.1.2. DROP ΓòÉΓòÉΓòÉ
  15242.  
  15243. This command deletes an entire APL2 object library from disk. 
  15244.  
  15245.       SHR211Γò£'DROP' filename
  15246.  
  15247.  
  15248. ΓòÉΓòÉΓòÉ 14.10.1.3. USE ΓòÉΓòÉΓòÉ
  15249.  
  15250. This command opens an already-existing AP 211 library file. It must be issued 
  15251. before using the SET, GET, ERASE, and LIST commands. 
  15252.  
  15253.                                     Γò£-----Access Control------Γòò
  15254.   SHR211Γò£'USE' filename [user_id] Γöé ['READ'Γöé'UPDATE'Γöé'PRIVATE']
  15255.  
  15256. user_id is a scalar integer, which can be used to implement an audit trail of 
  15257. updates, particularly where the file is shared between many users. The default 
  15258. value is Γò₧╨áAI, as specified in APLID environment variable (set by the -id 
  15259. invocation parameter). 
  15260.  
  15261. Access Control Parameters: 
  15262.  
  15263. o UPDATE opens the file for shared READ/WRITE access. 
  15264. o READ opens the file for shared READ/ONLY access. 
  15265. o PRIVATE opens the file for nonshared READ/WRITE access. 
  15266.  
  15267. READ or UPDATE should be specified when accessing AP 211 files that require 
  15268. simultaneous multiuser READ/WRITE access. When running in this mode, AP 211 
  15269. enables an internal locking procedure, which ensures file integrity, but 
  15270. impacts performance for file updates. If you do not require shared access, 
  15271. opening the file using PRIVATE provides a significant performance improvement 
  15272. for file writes. 
  15273.  
  15274. PRIVATE opens the file for exclusive READ/WRITE access. A file that is already 
  15275. open cannot be opened as PRIVATE, and once opened PRIVATE, cannot be opened by 
  15276. anyone else until a RELEASE is issued or the shared variable is retracted. 
  15277.  
  15278. If the USE command is issued without any of the optional Access Control 
  15279. parameters, the file is opened with the maximum access authority permitted, for 
  15280. exclusive use if possible or shared access if the file is already opened. 
  15281.  
  15282. USE returns a two-element vector containing a return code and the record size. 
  15283.  
  15284.  
  15285. ΓòÉΓòÉΓòÉ 14.10.1.4. RELEASE ΓòÉΓòÉΓòÉ
  15286.  
  15287. Releases the object library that was allocated to a shared variable. This 
  15288. command is issued implicitly when retracting or erasing the shared variable, or 
  15289. if a subsequent USE or CREATE are specified to the same shared variable. 
  15290.  
  15291.       SHR211Γò£'RELEASE'
  15292.  
  15293.  
  15294. ΓòÉΓòÉΓòÉ 14.10.1.5. SET ΓòÉΓòÉΓòÉ
  15295.  
  15296. Allows you to associate a name in the object library with an APL2 array. The 
  15297. command requires a three-element vector: 
  15298.  
  15299.       SHR211Γò£'SET' name APL2_object
  15300.  
  15301. The maximum permitted length of name is 31 characters. 
  15302.  
  15303. If the name is already in use, the old definition is deleted, and the new 
  15304. definition added to the object library. The space taken by the old definition 
  15305. is freed for later use. 
  15306.  
  15307.  
  15308. ΓòÉΓòÉΓòÉ 14.10.1.6. GET ΓòÉΓòÉΓòÉ
  15309.  
  15310. This returns the array (if any) associated with a given name. 
  15311.  
  15312.       SHR211Γò£'GET' name
  15313.       (return_code APL2_object)ΓûáSHR211
  15314.  
  15315. The response to this command is a two-element vector: the first item is the 
  15316. return code, the second is the APL2_object array, if found. 
  15317.  
  15318.  
  15319. ΓòÉΓòÉΓòÉ 14.10.1.7. RENAME ΓòÉΓòÉΓòÉ
  15320.  
  15321. Renames an object stored in an AP 211 file. 
  15322.  
  15323.       SHR211Γò£'RENAME' oldname newname
  15324.  
  15325.  
  15326. ΓòÉΓòÉΓòÉ 14.10.1.8. ERASE ΓòÉΓòÉΓòÉ
  15327.  
  15328. This command allows you to remove an APL2 array from an object library, and 
  15329. makes its storage available for other updates. Note, however, that the overall 
  15330. size of the file remains unchanged. 
  15331.  
  15332.       SHR211Γò£'ERASE' name
  15333.  
  15334.  
  15335. ΓòÉΓòÉΓòÉ 14.10.1.9. LIST ΓòÉΓòÉΓòÉ
  15336.  
  15337. This command allows you to list the contents of the current library: 
  15338.  
  15339.       SHR211Γò£'LIST' 'NAMES'
  15340.       ╤å╨áΓò£SHR211
  15341. Object1
  15342. Object2
  15343. Object3
  15344. 3 31
  15345.       SHR211Γò£'LIST' 'ATTS'
  15346.       ╤å╨áΓò£SHR211
  15347. 1 1001 1991 1 2 12 30 14 12
  15348. 2 1001 1991 1 2 12 30 14 12
  15349. 1 1001 1991 1 2 12 30 14 12
  15350. 3 9
  15351.  
  15352. The information returned is: 
  15353.  
  15354. o The number of records used for this object 
  15355. o User ID number (as specified on USE command) of user who last updated this 
  15356.   object 
  15357. o The date and time the object was updated (in ╨áTS format) 
  15358.  
  15359.   Note:  The time is listed in Greenwich Mean Time. 
  15360.  
  15361. Each row in this list corresponds to the equivalent row in the list of object 
  15362. names. 
  15363.  
  15364.  
  15365. ΓòÉΓòÉΓòÉ 14.10.2. AP 211 Return Codes ΓòÉΓòÉΓòÉ
  15366.  
  15367. The following table lists the AP 211 return codes. 
  15368.  
  15369. Code      Meaning 
  15370.   0 -     Success 
  15371.   2 -     File not found 
  15372.  ┬ñ1 -     Old format file (access restricted to read only) 
  15373.  ┬ñ2 -     Rank error 
  15374.  ┬ñ3 -     Length error 
  15375.  ┬ñ4 -     Type error 
  15376.  ┬ñ7 -     Invalid command 
  15377.  ┬ñ8 -     Invalid block size 
  15378.  ┬ñ9 -     Invalid library file 
  15379. ┬ñ10 -     No library file accessed 
  15380. ┬ñ11 -     Name has no value 
  15381. ┬ñ12 -     Invalid name specified 
  15382. ┬ñ13 -     Error encountered during set operation 
  15383. ┬ñ14 -     Invalid file name 
  15384. ┬ñ15 -     Invalid access mode 
  15385. ┬ñ16 -     Invalid user ID 
  15386. ┬ñ17 -     Filename already in use 
  15387. ┬ñ18 -     Insufficient user authority 
  15388. ┬ñ19 -     Name already exists 
  15389. ┬ñ20 -     Unsupported data format 
  15390. ┬ñ21 -     Temporary interlock 
  15391. ┬ñ22 -     Unexpected SVP return code 
  15392. ┬ñ24 -     Media full 
  15393. ┬ñ26 -     No space available 
  15394.  
  15395.  
  15396. ΓòÉΓòÉΓòÉ 14.10.3. Example of Use ΓòÉΓòÉΓòÉ
  15397.  
  15398. First share a variable with AP 211: 
  15399.  
  15400.       211 ╨áSVO 'SHR211'
  15401. 1
  15402.       ╨áSVO 'SHR211'
  15403. 2
  15404.  
  15405. Then create a new file called FILE: 
  15406.  
  15407.       SHR211Γò£'CREATE' 'FILE'
  15408.       SHR211
  15409. 0
  15410.  
  15411. An empty file has now been created. Before we can go any further, the file must 
  15412. be opened for access: 
  15413.  
  15414.       SHR211Γò£'USE' 'FILE'
  15415.  
  15416.       SHR211
  15417.  
  15418. 0 1024
  15419.  
  15420. The 1024 returned by this call shows that the default record size was used when 
  15421. the file was created. Now we can place data into the file: 
  15422.  
  15423.       SHR211Γò£'SET' 'ABC' (╤î10)
  15424.  
  15425.       SHR211
  15426.  
  15427. 0
  15428.  
  15429.       SHR211Γò£'SET' 'DEF' (3 5╤å'AP211IS   EASY!')
  15430.  
  15431.       SHR211
  15432.  
  15433. 0
  15434.  
  15435. This has placed two objects into the file. We can determine the names of 
  15436. objects stored on the file with: 
  15437.  
  15438.       SHR211Γò£'LIST' 'NAMES'
  15439.  
  15440.       SHR211
  15441.  
  15442. ABC
  15443.  
  15444. DEF
  15445.  
  15446. At any time, we can retrieve any objects stored in the file: 
  15447.  
  15448.       SHR211Γò£'GET' 'DEF'
  15449.  
  15450.       SHR211
  15451.  
  15452.  0   AP211
  15453.  
  15454.      IS
  15455.  
  15456.      EASY!
  15457.  
  15458. Note that a length two result is given by the SET call. Normally we want to 
  15459. separate the return code (the first item) and the data array (the second item) 
  15460. into two variables. Vector assignment provides a simple way to do this: 
  15461.  
  15462.       SHR211Γò£'GET' 'DEF'
  15463.  
  15464.       (RC ARR)Γò£SHR211
  15465.  
  15466.       RC
  15467.  
  15468. 0
  15469.  
  15470.       ARR
  15471.  
  15472. AP211
  15473.  
  15474. IS
  15475.  
  15476. EASY!
  15477.  
  15478. When we have finished with the file, we can release it: 
  15479.  
  15480.       SHR211Γò£'RELEASE'
  15481.  
  15482.       SHR211
  15483.  
  15484. 0
  15485.  
  15486. And finally, if we have no further need for the file, we can delete it: 
  15487.  
  15488.       SHR211Γò£'DROP' 'FILE'
  15489.  
  15490.       SHR211
  15491.  
  15492. 0
  15493.  
  15494.  
  15495. ΓòÉΓòÉΓòÉ 15. Writing Your Own External Routines ΓòÉΓòÉΓòÉ
  15496.  
  15497. This chapter discusses how to write your own external routines to be called 
  15498. through processor 11. For more information about processor 11, see Processor 
  15499. 11-Accessing External Routines. 
  15500.  
  15501. o Creating a Callable Subroutine 
  15502. o Using Prebuilt DLLs (Runtime Libraries) 
  15503. o Debugging External Functions 
  15504.  
  15505.  
  15506. ΓòÉΓòÉΓòÉ 15.1. Creating a Callable Subroutine ΓòÉΓòÉΓòÉ
  15507.  
  15508. Write your subroutine as a 32-bit object using system linkage. For example: 
  15509.  
  15510. /* C-Set/2  example  */
  15511. #include <stdlib.h>
  15512. #include <stdio.h>
  15513. #include <errno.h>
  15514. #include <math.h>
  15515. int _System MyFunction(char *string)
  15516. {
  15517.   return strlen(string);
  15518. }
  15519.  
  15520. Create a names file entry in P011.NAM as described in NAMES File Syntax for 
  15521. Processor 11: 
  15522.  
  15523. :nick.MY        :link.SYSTEM :lib.my  :proc.MyFunction
  15524.                 :valence.1 1 0
  15525.                 :rarg. (G4 0)(S1 1 *)
  15526.                 :rslt. (I4 0)
  15527. :desc.Returns the length of a character vector to the first null.
  15528.  
  15529. Create a MY.DEF file as described in the OS/2 Toolkit documentation: 
  15530.  
  15531. LIBRARY my INITINSTANCE TERMINSTANCE
  15532. PROTMODE
  15533. DATA MULTIPLE NONSHARED
  15534. EXPORTS
  15535.     _DLL_InitTerm
  15536.     MyFunction
  15537.  
  15538. Compile the program. For example, using the IBM C/C++ product: 
  15539.  
  15540. icc /Ti /Gd- /Ge- /Gt- /O- /B"/noe /noi" my.c my.def
  15541.  
  15542. Put the files MY.DLL and P011.NAM in the directry you start apl from. 
  15543.  
  15544. Execute the ╨áNA: 
  15545.  
  15546.    '<C:\APL2OS2\P011.NAM>' 11 ╨áNA 'MY' 
  15547.  
  15548. Test the function: 
  15549.  
  15550.       MY ╤é 'sssss',(╨áAF 0),'ttttt'
  15551. 5
  15552.  
  15553.  
  15554. ΓòÉΓòÉΓòÉ 15.2. Using Prebuilt DLLs (Runtime Libraries) ΓòÉΓòÉΓòÉ
  15555.  
  15556. Many 32-bit DLLs can be called directly by processor 11. These DLLs can be part 
  15557. of a subroutine library or program product. To use them directly, you must 
  15558. ensure that they can be called with the OS/2-defined 32-bit _System linkage. If 
  15559. the DLL was meant to be called with Optlink, Pascal, or some other linkage 
  15560. convention, then an intervening stub program is needed. Refer to the 
  15561. documentation received with the library for parameter lists and linkage 
  15562. conventions. 
  15563.  
  15564. For _System linkage DLLs, you need only create a NAMES file for the entries you 
  15565. wish to access. Here is an example of a description for DosSearchPath in the 
  15566. OS/2 C-Set++ Tools 2.0 _DOSCALL.DLL. 
  15567.  
  15568. :nick.DOSPATH   :link.SYSTEM :lib._doscall  :proc.DosSearchPath
  15569.                 :valence.1 1 0
  15570.                 :rslt.(1 I4 0)
  15571.                 :rarg.(5 G0 1 5)(1 I4 *)
  15572.                 :rarg.          (G4 0)(S1 1 *)
  15573.                 :rarg.          (G4 0)(S1 1 *)
  15574.                 :rarg.          (G4 0)(>S1 1 *)
  15575.                 :rarg.          (1 I4 *)
  15576.                 :desc.APIRET DosSearchPath(ULONG uControl
  15577.                 :desc.                    ,PSZ pszPathRef
  15578.                 :desc.                    ,PSZ pszFileName
  15579.                 :desc.                    ,PBYTE pbResultBuffer
  15580.                 :desc.                    ,ULONG ulResultBufferLen)
  15581.  
  15582. This example uses a 5-element depth 3 array to pass the data. Each character 
  15583. vector is an enclosed element. The fourth item has a pass by name indicator and 
  15584. its value is a character vector that contains the name of an APL object having 
  15585. the desired size and type. 
  15586.  
  15587.       AΓò£3                                 ╤ä search environment
  15588.       DΓò£╤éΓûá'PATH' 'CONFIG.SYS' 'DD'        ╤ä and current directory
  15589.       DDΓò£ (255╤å'+')                       ╤ä named variable
  15590.                     DOSPATH  A,D,1+╤åDD    ╤ä here is the call
  15591.  0
  15592.  
  15593. The result value as indicated by the :RSLT. keyword is the integer scalar 
  15594. return code. The value of DD has been updated in place. DD must be large enough 
  15595. to hold the result. 
  15596.  
  15597.       DD                   ╤ä here is the updated variable
  15598. C:\OS2\INSTALL\CONFIG.SYS
  15599.  
  15600.  
  15601. ΓòÉΓòÉΓòÉ 15.3. Debugging External Functions ΓòÉΓòÉΓòÉ
  15602.  
  15603. External functions can be debugged by any debugger that allows you to halt on 
  15604. DLL LOAD to set break points in the DLL. IPMD, which is provided as part of 
  15605. C-Set++ Tool, allows this. 
  15606.  
  15607. To debug your functions via IPMD, (provided with C-Set/2 ), include debug 
  15608. information in your objects and DLL, then run APL2 under IPMD by typing 'IPMD 
  15609. aosapl2 -ws 784k'. Before starting APL2: 
  15610.  
  15611.  1. Click on Breakpoints. 
  15612.  2. Click on Load Occurrence. 
  15613.  3. Click on Enter. 
  15614.  4. Click on the name of your DLL. 
  15615.  5. Click on OK. 
  15616.  
  15617. After setting the "break" on DLL LOAD, continue running APL2. IPMD gains 
  15618. control and stops APL when you ╨áNA to your routine. (Processor 11 loads your 
  15619. DLL after it has found the NAMES file entry for the routine and located the 
  15620. DLL. Processor 11 loads a DLL at first reference and unloads it at the last 
  15621. reference. To cause a reload of the DLL, issue a )CLEAR and then reassociate 
  15622. your routine.) 
  15623.  
  15624. The debugger stops when it first loads your DLL. At the Debug Main Task window, 
  15625. you see an entry for your DLL. Click on the + button and then on the desired 
  15626. function. When it is open, you can set any breakpoints you wish. After you have 
  15627. set all the needed breakpoints you can then restart APL2. It processes until 
  15628. one of your breakpoints is hit. 
  15629.  
  15630.  
  15631. ΓòÉΓòÉΓòÉ 16. Writing Your Own Auxiliary Processors ΓòÉΓòÉΓòÉ
  15632.  
  15633. This chapter discusses how to write your own auxiliary processors. Auxiliary 
  15634. processors can be written either in APL or in C. 
  15635.  
  15636. o The basic interface for communicating between an APL auxiliary processor and 
  15637.   the shared variable processor is the set of shared variable system functions 
  15638.   and variables (╨áSVC, ╨áSVE, ╨áSVO, ╨áSVQ, ╨áSVR, and ╨áSVS) defined in APL2 
  15639.   Programming: Language Reference. 
  15640.  
  15641. o The basic interface for communicating between a C auxiliary processor and the 
  15642.   shared variable processor is a set of service calls and structure definitions 
  15643.   defined in SVP Programming Interface. 
  15644.  
  15645. o A higher level APSERVER interface to the shared variable processor is also 
  15646.   available for auxiliary processors written in either APL or C. This is 
  15647.   defined in Writing Auxiliary Processors Using APSERVER. 
  15648.  
  15649. o If your AP is written in APL and uses the basic interface, you should read 
  15650.   the material on starting APL auxiliary processors that is in APSERVER-APL2 
  15651.   Programming Interface. 
  15652.  
  15653. o Writing Auxiliary Processors Using APSERVER 
  15654. o SVP Programming Interface 
  15655. o Common Data Representation 
  15656.  
  15657.  
  15658. ΓòÉΓòÉΓòÉ 16.1. Writing Auxiliary Processors Using APSERVER ΓòÉΓòÉΓòÉ
  15659.  
  15660. The Shared Variable Processor (SVP) is a general purpose communication facility 
  15661. that can support various protocols, including peer-to-peer, client-server, full 
  15662. or half duplex, or uni-directional data flow for device drivers or 
  15663. instrumentation. However, the most common type of auxiliary processor (AP) is 
  15664. the server, which accepts requests from one or more client processors, performs 
  15665. some action, and returns a response. 
  15666.  
  15667. The purpose of the APSERVER API (application program interface) is to simplify 
  15668. the implementation of server APs by handling all of the SVP communication and 
  15669. process control, leaving you to concentrate on just the AP-specific service 
  15670. routine. Both an APL2 function call interface and a C function call interface 
  15671. are provided so client-server APs can be easily written in either APL or in 
  15672. compiled languages such as C or Fortran. 
  15673.  
  15674. Although the APSERVER can be used to implement dual-variable APs (typically a 
  15675. control and data variable), IBM recommends that a single variable interface be 
  15676. used for simplicity. By using APL2's general array support, it is easy to pass 
  15677. control information and its accompanying data through a single variable. 
  15678. APSERVER provides access to client processor information and shared variable 
  15679. name to support share restrictions when appropriate. 
  15680.  
  15681. A server AP can run as either a dependent or independent processor, local or 
  15682. remote, and can be automatically started on the first incoming share offer. 
  15683. When using the C API, each incoming share spawns a separate execution thread to 
  15684. achieve the maximum benefit of multitasking or multiprocessing. 
  15685.  
  15686. APSERVER allows common APs to be written to run on different operating systems 
  15687. (for example, OS/2, AIX, or Sun Solaris) by handling platform-dependent 
  15688. functions, such as process threading and event handling. 
  15689.  
  15690. o APSERVER-APL2 Programming Interface 
  15691. o APSERVER-C Programming Interface 
  15692.  
  15693.  
  15694. ΓòÉΓòÉΓòÉ 16.1.1. APSERVER-APL2 Programming Interface ΓòÉΓòÉΓòÉ
  15695.  
  15696. To use the APSERVER function to implement an AP written in APL2, first copy the 
  15697. function from the distributed library: 
  15698.  
  15699.       )COPY 1 UTILITY APSERVER
  15700. The APSERVER function uses a registered callback interface, where you choose to 
  15701. supply a minimum of zero (for the default "echo" AP) to a maximum of four 
  15702. callback function names. The syntax of the APSERVER call is: 
  15703.  
  15704.       APSERVER 'Init_fn' 'Wait_fn' 'Process_fn' 'Exit_fn'
  15705.  
  15706. If a callback function is not provided, the corresponding item in the 4 element 
  15707. general array argument should contain an empty character vector. 
  15708.  
  15709. The first name in the argument list is the name of the initialization function 
  15710. that gets called by APSERVER when a new share offer arrives. The syntax of the 
  15711. 'Init_fn' is: 
  15712.  
  15713.       RCΓò£Init_fn PID SVNAME
  15714.  
  15715. APSERVER passes to the initialization function the SVP processor number of the 
  15716. client and the name of the shared variable being offered. If the AP chooses to 
  15717. accept the share, it returns an explicit result of 1. To reject the share 
  15718. offer, a 0 is returned. 
  15719.  
  15720. The initialization function can be used to open files, establish shares with 
  15721. other APs, or to initialize global variables. Since the AP runs as a single 
  15722. task, care should be taken to avoid blocking on a shared variable access within 
  15723. the callback functions if the AP is designed to support multiple shares or 
  15724. multiple clients. 
  15725.  
  15726. The second name in the APSERVER argument list is the name of the wait callback 
  15727. function. If no wait routine is supplied the default action of the APSERVER is 
  15728. to enter a ╨áSVE wait for any shared variable event, then scan for new offers, 
  15729. new client requests, or shared variable retractions. The Wait_fn function, if 
  15730. provided, must be a niladic function with no explicit result. You may wish to 
  15731. provide your own wait function to issue ╨áSVE so that you can check the state of 
  15732. other shared variables used for your own purposes, or so that you can provide a 
  15733. time-out on the ╨áSVE wait (for example, to do some administrative work such as 
  15734. journaling). When you supply wait routine exits, the APSERVER performs the 
  15735. usual checking for client events. 
  15736.  
  15737. The third item in the APSERVER argument list is the name of the process 
  15738. function-the meat of the AP. The syntax is: 
  15739.  
  15740.       RESULTΓò£(PID SVNAME) Process_fn REQUEST
  15741.  
  15742. The right argument is the APL2 array representing the client request. The 
  15743. APSERVER provides the client processor ID and shared variable name in the left 
  15744. argument. Provide the necessary code in the process routine to service the 
  15745. client request, and then return, as the explicit result of the function, the 
  15746. APL2 array that is to be sent back to the client in response to the request. If 
  15747. the process callback is elided, the default action of the APSERVER is to echo 
  15748. the request back to the client. 
  15749.  
  15750. The fourth item in the APSERVER argument list is the name of the exit callback 
  15751. function. The syntax is: 
  15752.  
  15753.       Exit_fn PID SVNAME
  15754.  
  15755. The APSERVER again passes the client processor ID and shared variable name in 
  15756. the right argument. The exit function is called when the client retracts the 
  15757. shared variable. The exit function is often used as the inverse to the 
  15758. initialization function, to close files, retract other associated shares, and 
  15759. expunge global variables. When the APSERVER gets control back from the exit 
  15760. routine, it completes the retraction from the server side. 
  15761.  
  15762. Note:  A current restriction of APs written in APL2 using the APSERVER 
  15763. client-server protocol is that the client must reference all return values sent 
  15764. by the server, prior to issuing another request. Failure to do so could result 
  15765. in a request being lost due to a race condition. 
  15766.  
  15767. o An AP Example Using APSERVER 
  15768.  
  15769.  
  15770. ΓòÉΓòÉΓòÉ 16.1.1.1. An AP Example Using APSERVER ΓòÉΓòÉΓòÉ
  15771.  
  15772.       )CLEAR
  15773. CLEAR WS
  15774.       )COPY 1 UTILITY APSERVER
  15775. SAVED 1993-08-07 19.14.31 (GMT-4)
  15776.       Γòûap555
  15777. [1]   ╤ä Sample AP using 'init' and 'exit' callbacks.  This AP uses AP207
  15778. [2]   ╤ä to create a window where client requests are randomly displayed.
  15779. [3]   ╤ä Returns 'OK' if write to window was successful, or 'OOPS' if not.
  15780. [4]    APSERVER 'INIT555' '' 'PROC555' 'EXIT555'
  15781. [5]   Γòû
  15782.       ΓòûRΓò£INIT555 SVinfo;N;PID;SVNAME
  15783. [1]    (PID SVNAME)Γò£SVinfo
  15784. [2]    Γòò(~RΓò£2=Γò₧207 SVOFFER NΓò£SVNAME,'207')/0
  15785. [3]    ╨┐N,'Γò£''OPEN'' (0 ''',(╨╛╤ÄID PID),' ',SVNAME,''' ',(╨╛200+?4╤å300),')'
  15786. [4]    ╨┐N,'Γò£''COLOR'' ''CYAN'''
  15787. [5]    Γòò(RΓò£0=Γò₧╨┐N)/0
  15788. [6]    NΓò£╨áEX N
  15789. [7]   Γòû
  15790.       ΓòûRΓò£SVinfo PROC555 String;N;PID;SVNAME
  15791. [1]    (PID SVNAME)Γò£SVinfo
  15792. [2]    NΓò£SVNAME,'207'
  15793. [3]    ╨┐N,'Γò£''MOVE'' (?2╤å150)'
  15794. [4]    ╨┐N,'Γò£''WRITE'' ''',String,''''
  15795. [5]    RΓò£╤ÄΓò₧(0=Γò₧╨┐N)Γòƒ'OOPS' 'OK'
  15796. [6]   Γòû
  15797.       ΓòûEXIT555 SVinfo;N;PID;SVNAME
  15798. [1]    (PID SVNAME)Γò£SVinfo
  15799. [2]    NΓò£SVNAME,'207'
  15800. [3]    ╨┐N,'Γò£''CLOSE'' '''''
  15801. [4]    NΓò£╨áEX N
  15802. [5]   Γòû
  15803.       )COPY 1 UTILITY SVOFFER
  15804. SAVED 1993-08-07 19.14.31 (GMT-4)
  15805.       )FNS
  15806. APSERVER EXIT555  INIT555  PROC555  SVOFFER  ap555
  15807.       )SAVE ap555
  15808. SAVED 1993-08-24 21.36.05 (GMT-4)
  15809.       )LOAD 2 FILE
  15810. SAVED 1993-08-06 18.55.12 (GMT-4)
  15811. Licensed Materials - Property of IBM
  15812. 5621-430, 5765-012 (C) Copyright IBM Corp. 1983, 1993.
  15813.       (╤ê╨í ╨í ╨í ╨í)ΓòóFV 'AP555.CMD'
  15814. /* REXX command file to start AP 555 */
  15815. Parse Arg parms
  15816. lines = "')LOAD AP555' 'AP555' ')OFF'"
  15817. 'aosapl2 /sm piped /input "'lines'"' parms '>ap555.log'
  15818. 0
  15819.       )CLEAR
  15820. CLEAR WS
  15821.       555 ╨áSVO 'X'
  15822. 1
  15823.       ╨áSVO 'X'
  15824. 2
  15825.       ╨áSVC 'X'
  15826. 0 0 0 1
  15827.       1 0 1 0 ╨áSVC 'X'
  15828. 1 0 1 1
  15829.       XΓò£'SAY HI'
  15830.       X
  15831. OK
  15832.       ╨áSVR 'X'
  15833. 2
  15834.  
  15835.  
  15836. ΓòÉΓòÉΓòÉ 16.1.2. APSERVER-C Programming Interface ΓòÉΓòÉΓòÉ
  15837.  
  15838. The APSERVER uses a registered callback interface, where you choose to supply a 
  15839. minimum of zero (for default "echo" AP) to a maximum of four callback function 
  15840. names. The definition of the APSERVER function call is: 
  15841.  
  15842. int apserver(int argc, char ** argv, int(*initfn)(void *),
  15843.                                      int(*waitfn)(void *),
  15844.                                      int(*procfn)(void *),
  15845.                                      int(*exitfn)(void *));
  15846.  
  15847. The first two arguments passed to APSERVER are the argc and argv parameters 
  15848. that were passed to the AP main routine. The APSERVER uses this information to 
  15849. determine the processor identification for signing on to the SVP. It scans for 
  15850. the keyword -id followed by one to three numeric values, with the form 
  15851. id[,pid[,ppid]], representing the ID and, optionally, the parent and 
  15852. grandparent IDs for dependent processors. If no -id parameter is found, 
  15853. APSERVER uses the numeric portion of the executable module's name (of the form 
  15854. "apNNN") to determine the default processor number. 
  15855.  
  15856. The next four arguments are the names of your supplied callback functions. 
  15857. These callback routines are described as follows: 
  15858.  
  15859. initfn   AP initialization (prior to accepting client's share) 
  15860. waitfn   Multiple event wait and non-SVP event handling 
  15861. procfn   Process a client request (the meat of the AP) 
  15862. exitfn   AP clean-up (just prior to retraction of the share) 
  15863.  
  15864. Each of these callback routines receives a single argument that is a pointer to 
  15865. an SRVTOKEN structure. This token is used by subsequent APSERVER service 
  15866. routines that are described later. All callback functions return an integer 
  15867. return code, with zero indicating success. 
  15868.  
  15869. In each case, if no callback routine is supplied, a NULL pointer must be 
  15870. provided instead. If a NULL value is specified for all four callback functions, 
  15871. the APSERVER functions as an echo AP, reflecting the client processor's request 
  15872. value back to the client as the server's response value. 
  15873.  
  15874. For example, the following C function represents the simplest form of a fully 
  15875. functional AP (default echo AP), supporting multiple clients, multiple shares, 
  15876. and multitasking on a per-share basis: 
  15877.  
  15878. /* ap555 - echo AP (source module: ap555.c, executable module: ap555) */
  15879. #include "apserver.h"
  15880. int main(int argc, char **argv) {
  15881. return(apserver(argc, argv, NULL, NULL, NULL, NULL)); }
  15882.  
  15883. If the executable ap555 module is placed in the search path for an APL2 
  15884. session, the first share offer to processor 555 causes the AP to be 
  15885. auto-started as a dependent AP of the APL2 session. Alternatively, the AP could 
  15886. be started explicitly and may run as an independent processor. Optionally, by 
  15887. use of the TCP/IP processor profile, the server AP can also be accessed by 
  15888. remote client processors. 
  15889.  
  15890. o Defining the Process Callback Function 
  15891. o Defining the Init Callback Function 
  15892. o Defining the Exit Callback Function 
  15893. o Defining the Wait Callback Function 
  15894. o Execution Environment and Exception Handling 
  15895. o An AP Example Using APSERVER 
  15896.  
  15897.  
  15898. ΓòÉΓòÉΓòÉ 16.1.2.1. Defining the Process Callback Function ΓòÉΓòÉΓòÉ
  15899.  
  15900. To be of more practical use, an AP should serve as more than just a reflector 
  15901. of client requests. That is where the "process" callback function comes into 
  15902. play. The process routine name is passed as the fifth argument to APSERVER. On 
  15903. entry to the process routine, the client's request value is stored in a shared 
  15904. variable buffer that is accessed by two APSERVER macros: SRVBUF and SRVBUFL. 
  15905. Note that when passing APL2 arrays, SRVBUFL is typically not required because 
  15906. the size of the array is defined in the self-describing array header (see 
  15907. Common Data Representation). 
  15908.  
  15909. All APSERVER macros take the SRVTOKEN as an argument. A brief summary of the 
  15910. service macros follows: 
  15911.  
  15912.        (void *)SRVBUF(srvtoken)  - pointer to shared variable buffer
  15913. (unsigned long)SRVBUFL(srvtoken) - length of shared variable buffer
  15914.  (struct xid *)SRVPXID(srvtoken) - pointer to client's SVP ID
  15915.        (char *)SRVNAME(srvtoken) - pointer to shared variable name
  15916. (unsigned long)SRVNTOK(srvtoken) - SVP event notification token
  15917.        (void *)SRVUTOK(srvtoken) - user token (for your use)
  15918.  (struct srb *)SRVSRBP(srvtoken) - pointer to SVP share request block
  15919.  
  15920. On return from the process routine, the AP stores the result of the client's 
  15921. request in the shared variable buffer. If the size of the buffer on entry is 
  15922. not large enough for the result, the AP can request reallocation of storage via 
  15923. the srv_alloc service routine. The syntax of the srv_alloc call is: 
  15924.  
  15925. void * srv_alloc(void * srvtoken, unsigned long size);
  15926.  
  15927. The first argument is the SRVTOKEN pointer and the second is the number bytes 
  15928. of storage required. The SRVTOKEN pointer is returned. Note that srv_alloc does 
  15929. not preserve the previous contents of the buffer, so if the client request data 
  15930. is to be used later, a copy must be made. The SRVBUF macro is used to get 
  15931. addressability to the newly-allocated buffer. A NULL pointer is returned by 
  15932. SRVBUF if the allocation failed. 
  15933.  
  15934. To calculate the storage requirement for an APL2 array, the service routine 
  15935. aplobjsize can be called. The definition of aplobjsize is: 
  15936.  
  15937. unsigned long aplobjsize(unsigned char type, unsigned char rank,
  15938.                          unsigned long nelm);
  15939.  
  15940. See Common Data Representation for a description of the valid argument values. 
  15941. The function returns the number of bytes of storage required. 
  15942.  
  15943. Since srv_alloc only reallocates shared memory when necessary, you do not need 
  15944. to keep track of the buffer size to achieve optimum performance, but can simply 
  15945. call srv_alloc to request space for the result at any time. 
  15946.  
  15947. If the AP process routine enters a potentially long wait (for example, due to a 
  15948. blocking read), it should release the lock that is implicitly held on the 
  15949. shared memory buffer. This is done by calling the srv_free service routine, 
  15950. which has the following definition: 
  15951.  
  15952. srv_free(void * srvtoken);
  15953.  
  15954. After the srv_free service call, the buffer is no longer addressable and SRVBUF 
  15955. returns a NULL pointer. 
  15956.  
  15957. For best performance in nonblocking AP process routines that return a response 
  15958. to the client, srv_free should not be called. The AP holds the lock on the 
  15959. shared variable between the reference of the request and the setting of the 
  15960. result value. 
  15961.  
  15962. You can also write an AP server that accepts client requests, performs some 
  15963. action, but does not send a response back to the client. In this case, srv_free 
  15964. is called prior to return from the process callback routine, with no 
  15965. intervening srv_alloc calls. 
  15966.  
  15967.  
  15968. ΓòÉΓòÉΓòÉ 16.1.2.2. Defining the Init Callback Function ΓòÉΓòÉΓòÉ
  15969.  
  15970. While practical APs can be written using only the process callback routine, 
  15971. three other callbacks are provided for additional flexibility: init, wait, and 
  15972. exit. The init routine is called by APSERVER prior to accepting a new share 
  15973. from a client processor. 
  15974.  
  15975. Using the SRVNAME and SRVPXID macros, the AP can determine the name of the 
  15976. shared variable and the identity of the client. By setting the return code 
  15977. SRV_REJECT_SHARE, the AP init routine can instruct the APSERVER to ignore the 
  15978. incoming share. A return code of 0 results in the accepting of the incoming 
  15979. share to complete the coupling with the client processor. 
  15980.  
  15981. Typical things done in an init routine are file opens, environment 
  15982. initialization, and allocation of global data structures. The APSERVER 
  15983. maintains a user token for you to use as an anchor to a malloc'd data area. The 
  15984. SRVUTOK macro can be used to store and retrieve the user token. 
  15985.  
  15986.  
  15987. ΓòÉΓòÉΓòÉ 16.1.2.3. Defining the Exit Callback Function ΓòÉΓòÉΓòÉ
  15988.  
  15989. The exit callback routine usually provides the inverse function of the init 
  15990. routine. It is called by APSERVER just prior to retraction of the shared 
  15991. variable and termination of the execution thread. Using SRVUTOK to get the user 
  15992. token, which is typically the pointer to malloc'd storage, the exit routine can 
  15993. be used to close open files and windows, and to free any dynamic storage that 
  15994. was allocated in the init routine. 
  15995.  
  15996.  
  15997. ΓòÉΓòÉΓòÉ 16.1.2.4. Defining the Wait Callback Function ΓòÉΓòÉΓòÉ
  15998.  
  15999. The wait callback function is used only for special APs that need to wait on 
  16000. multiple events. If no wait routine is provided, the default action of the 
  16001. APSERVER is to wait for a client specification or retraction of the shared 
  16002. variable. 
  16003.  
  16004. APSERVER obtains a separate event notification token for each shared variable 
  16005. as it spawns a new execution thread. The SRVNTOK macro can be used to retrieve 
  16006. the SVP event notification token. For APs that need to monitor additional file 
  16007. or window handles, the SVP notification token can be included in a multi-wait 
  16008. call (for example, select, poll, or muxwait). After handling non-SVP events, 
  16009. the wait routine should return to allow processing of the next client request. 
  16010.  
  16011.  
  16012. ΓòÉΓòÉΓòÉ 16.1.2.5. Execution Environment and Exception Handling ΓòÉΓòÉΓòÉ
  16013.  
  16014. One of the goals of the APSERVER is to assume responsibility for most of the 
  16015. exception handling required for a robust auxiliary processor, including 
  16016. interrupt or termination signal trapping, redispatching of SVP requests in the 
  16017. case of temporary shared variable interlocks, and the orderly signoff and 
  16018. shutdown of the processor, including cases of severe error conditions. 
  16019.  
  16020. In the case of an unrecoverable error on a shared variable SVP call, the 
  16021. APSERVER issues an error message with return code information, then calls the 
  16022. exit registered callback function prior to retracting the shared variable and 
  16023. terminating the execution thread. The execution states of threads associated 
  16024. with other shared variables are generally unaffected by the one share failure. 
  16025.  
  16026. When the APSERVER is started, it immediately defines a signal handler to 
  16027. capture SIGTERM (software termination request) and SIGINT (interrupt signal). 
  16028. The signal handler is the same function that handles normal SVP-broadcast 
  16029. SHUTDOWN events. It issues a standard SVP processor SIGNOFF request before 
  16030. termination of the auxiliary processor. 
  16031.  
  16032. When a child process is spawned for each shared variable, the SIGTERM and 
  16033. SIGINT signals are reset to the default handlers. The auxiliary processor's 
  16034. init registered callback function can be used to establish the desired 
  16035. exception handling environment for the main "process" routine. 
  16036.  
  16037. In the unlikely event of an unrecoverable SVP error while monitoring the 
  16038. processor event queue, an error message is issued and an attempt is made to 
  16039. complete a normal processor SIGNOFF. During a normal processor SIGNOFF, the 
  16040. parent (dispatcher) process waits up to a maximum of 15 seconds for the child 
  16041. threads to complete a normal retraction of the associated shared variables and 
  16042. terminate. 
  16043.  
  16044.  
  16045. ΓòÉΓòÉΓòÉ 16.1.2.6. An AP Example Using APSERVER ΓòÉΓòÉΓòÉ
  16046.  
  16047. /*-P-ap999--------------------------------------------------------------------
  16048.  *
  16049.  * Module Name: ap999.c
  16050.  *
  16051.  * Descriptive Name: Auxiliary Processor 999
  16052.  *
  16053.  * Function: Sample Auxiliary Processor implementing client-server
  16054.  *           protocol.  For hard working programmers with deadlines,
  16055.  *           this sample server will "catch some ZZZZZZ's" for a
  16056.  *           client who has no time to sleep for himself.
  16057.  *
  16058.  * Entry-point: main
  16059.  *
  16060.  *-Z------------------------------------------------------------------------*/
  16061. #include <stdlib.h>
  16062. #include <string.h>
  16063. #include "aplobj.h"
  16064. #include "apserver.h"
  16065. #define INVALID_REQ  -1                 /* catch-all rc for unfriendly AP   */
  16066. #define SYSTEM_LIMIT -2                 /* requested space is unavailable   */
  16067. int sleep_init(void *);                 /* AP Server "init" callback fn     */
  16068. int sleep_server(void *);               /* AP Server "process" callback fn  */
  16069. int sleep_exit(void *);                 /* AP Server "exit" callback fn     */
  16070. static int error_code(void *, int);     /* error handler                    */
  16071.  
  16072. /*-F-main---------------------------------------------------------------------
  16073.  *
  16074.  * Purpose:    Auxiliary Processor 999 - main routine runs the general
  16075.  *             AP Server with standard callback to one or more of the 4
  16076.  *             AP Server callback routines identified in the parameter list.
  16077.  *             The 4 callback routines are named in parms 3-6 of apserver, and
  16078.  *             provide the following function:
  16079.  *                1. AP initialization, prior to accepting the client share
  16080.  *                2. multiple event wait and non-SVP event handling
  16081.  *                3. process a client request (passed in shared variable)
  16082.  *                4. AP exit cleanup on retraction of the share
  16083.  *             (Note: if a callback function is not provided, set parm to NULL)
  16084.  *
  16085.  * Arguments:  int      argc        Number of elements in argv
  16086.  *             char **  argv        Argument pointer array
  16087.  *             char **  envp        Environment pointer array
  16088.  *
  16089.  * Results:    int                  Exit Return Code
  16090.  *
  16091.  *--------------------------------------------------------------------------*/
  16092. int main(int argc, char **argv, char **envp) {
  16093.    return(apserver(argc, argv, sleep_init, NULL, sleep_server, sleep_exit));
  16094. /*                             init        wait  process       exit        */
  16095. }
  16096.  
  16097. /*-F-sleep_init---------------------------------------------------------------
  16098.  *
  16099.  * Purpose:    Server initialization callback - called by the AP
  16100.  *             Server prior to accepting the share to fully couple
  16101.  *             with the client.  The typical things done by an AP
  16102.  *             here are to open files, allocate global storage,
  16103.  *             initialize a global data structure and store its
  16104.  *             address in the user token field of the srvtoken, etc...
  16105.  *             Via SRVPXID and SRVNAME, the AP can examine the client's
  16106.  *             fully-qualified SVP identification and the name of
  16107.  *             the share.  If the AP decides not to accept the share,
  16108.  *             it returns from this init routine with return code
  16109.  *             SRV_REJECT_SHARE.
  16110.  *
  16111.  * Arguments:  void * srvtoken       pointer to AP Server token
  16112.  *
  16113.  *             SRVUTOK(srvtoken)   macro returns user token (AP defined)
  16114.  *             SRVNAME(srvtoken)   macro returns shared variable name
  16115.  *             SRVPXID(srvtoken)   macro returns partner's extended ID
  16116.  *             SRVSRBP(srvtoken)   macro returns SVP share request block ptr
  16117.  *
  16118.  * Results:    int    Return Code
  16119.  *                    0 = success
  16120.  *                    SRV_REJECT_SHARE = AP Server just quietly ends thread
  16121.  *                    other = error condition (Server message & end thread)
  16122.  *
  16123.  *--------------------------------------------------------------------------*/
  16124. int sleep_init(void * srvtoken) {
  16125.    SRVUTOK(srvtoken) = malloc(8);       /* fake control block as an example */
  16126.    if (SRVUTOK(srvtoken) == NULL)
  16127.       return(SRV_REJECT_SHARE);         /* reject share if malloc failed    */
  16128.    memset(SRVUTOK(srvtoken),'Z',8);     /* initialize fake control block    */
  16129.    return(0);
  16130. }
  16131.  
  16132. /*-F-sleep_server-------------------------------------------------------------
  16133.  *
  16134.  * Purpose:    Auxiliary processor 999 is a sample server AP which
  16135.  *             uses the general AP Server interface (apserver.c) to
  16136.  *             implement a client-server type protocol through the
  16137.  *             Shared Variable Processor.  It uses a single shared
  16138.  *             variable interface, with no name restrictions, and
  16139.  *             runs each share request stream asynchronously under
  16140.  *             a separate process (AIX, UNIX) or separate thread (OS/2).
  16141.  *
  16142.  *             AP999 accepts 2 element integer vectors, where the first
  16143.  *             value is the number of milliseconds to sleep, and the second
  16144.  *             element is the size of the resulting character vector to
  16145.  *             return.  To demonstrate the handling of short versus long
  16146.  *             requests, AP999 uses a fast path through the SVP for a
  16147.  *             sleep of 1 second or less (holding the shared variable
  16148.  *             lock from pre-ref until post-spec), while releasing the
  16149.  *             lock (via srv_free call) for longer requests.
  16150.  *
  16151.  * Arguments:  void * srvtoken      pointer to AP Server token
  16152.  *
  16153.  *             SRVBUF(srvtoken)     macro returns ptr to shared var buffer
  16154.  *             SRVBUFL(srvtoken)    macro returns shared var buffer length
  16155.  *             SRVUTOK(srvtoken)    macro returns user token (AP defined)
  16156.  *             SRVNAME(srvtoken)    macro returns shared variable name
  16157.  *             SRVPXID(srvtoken)    macro returns partner's extended ID
  16158.  *             SRVSRBP(srvtoken)    macro returns SVP share request block ptr
  16159.  *
  16160.  * Results:    int            Return Code
  16161.  *                            0 = success
  16162.  *                        other = error condition (Server retracts & exits)
  16163.  *
  16164.  *             On return, the AP stores the result of the client's request
  16165.  *             in the shared variable buffer, enlarging it if necessary (or
  16166.  *             reallocating it if freed with srv_free) using the srv_alloc
  16167.  *             callback to the AP Server.  Note that srv_alloc will NOT
  16168.  *             preserve the previous contents of the buffer, and SRVBUF
  16169.  *             must be used to get addressability to the buffer after the
  16170.  *             call to srv_alloc.
  16171.  *
  16172.  *--------------------------------------------------------------------------*/
  16173.  
  16174. int sleep_server(void * srvtoken) {
  16175.    int rc = 0;
  16176.    APLOBJ *obj = (APLOBJ *) SRVBUF(srvtoken);  /* request is an APL2 object */
  16177.    int objsize;
  16178.    int msecs = obj->dim[1];             /* 1st item of request is sleep time*/
  16179.    int shape = obj->dim[2];             /* 2nd is shape of char array result*/
  16180.    if ((obj->type != INTEGER && obj->type != BOOLEAN) ||
  16181.         obj->rank != VECTOR || obj->dim[0] != 2) {
  16182.       rc = error_code(srvtoken, INVALID_REQ);  /* generate error return code*/
  16183.       return rc;
  16184.       }
  16185.    if (obj->type == BOOLEAN) {          /* if boolean, convert to integer   */
  16186.       msecs = ((unsigned long)obj->dim[1]) >> ((8*sizeof(long))-1);
  16187.       shape = (((unsigned long)obj->dim[1]) << 1) >> ((8*sizeof(long))-1);
  16188.       }
  16189.    if (msecs <= 1000) {                 /* short wait - OK to hold the lock */
  16190.       if (msecs > 0) {
  16191.          svsleep(msecs);
  16192.          }
  16193.       }
  16194.    else {                               /* long wait                        */
  16195.       srv_free(srvtoken);               /* AP Server releases space, unlocks*/
  16196.       obj = NULL;                       /* no longer have addressability    */
  16197.       if (msecs <= 60000) {             /* bypass sleep if more than 60     */
  16198.          svsleep(msecs);                /*    seconds in this sample AP     */
  16199.          }
  16200.       }
  16201.    objsize = aplobjsize(CHARACTER, VECTOR, shape);          /* result size? */
  16202.    obj = (APLOBJ *) SRVBUF(srv_alloc(srvtoken, objsize));   /* ask for space*/
  16203.    if (obj == NULL) {                              /* if allocation failed, */
  16204.       rc = error_code(srvtoken, SYSTEM_LIMIT);     /* set error return code */
  16205.       return rc;
  16206.       }
  16207.    obj->ptr = CDRID;                    /* build the CDR header for result  */
  16208.    obj->nb = objsize;
  16209.    obj->nelm = shape;
  16210.    obj->type = CHARACTER;
  16211.    obj->rank = VECTOR;
  16212.    obj->dim[0] = shape;
  16213.    memset(&obj->dim[1], 'Z', shape);    /* return some Z's for sleepy client*/
  16214.    return rc;
  16215. }
  16216.  
  16217. /*-F-error_code---------------------------------------------------------------
  16218.  *
  16219.  * Purpose:    Return an error return code to client for this request
  16220.  *
  16221.  * Arguments:  void * srvtoken       pointer to AP Server token
  16222.  *             int        rc         AP return code
  16223.  *
  16224.  * Results:    int            Return Code (from this function)
  16225.  *                            0 = success
  16226.  *                           -1 = error condition (srv_alloc failed)
  16227.  *
  16228.  *--------------------------------------------------------------------------*/
  16229. int error_code(void * srvtoken, int rc) {
  16230.    APLOBJ *obj;                         /* ptr to APL2 object in CDR format */
  16231.    int objsize;
  16232.    objsize = aplobjsize(INTEGER, SCALAR, 1);                /* result size? */
  16233.    obj = (APLOBJ *) SRVBUF(srv_alloc(srvtoken, objsize));   /* ask for space*/
  16234.    if (obj == NULL) {                           /* we're in trouble if we   */
  16235.       return (-1);                              /* can't get 32 bytes - die!*/
  16236.       }
  16237.    obj->ptr = CDRID;                            /* construct result header  */
  16238.    obj->nb = objsize;
  16239.    obj->nelm = 1;
  16240.    obj->type = INTEGER;
  16241.    obj->rank = SCALAR;
  16242.    obj->dim[0] = rc;
  16243.    return (0);
  16244. }
  16245.  
  16246. /*-F-sleep_exit---------------------------------------------------------------
  16247.  *
  16248.  * Purpose:    Server exit callback - called by the AP Server prior to
  16249.  *             shared variable retraction and termination of this process
  16250.  *             thread.  Typical use by the AP is for freeing any dynamic
  16251.  *             storage it allocated, closing files and pipes, etc.
  16252.  *
  16253.  * Arguments:  void * srvtoken       pointer to AP Server token
  16254.  *
  16255.  *             SRVUTOK(srvtoken)     macro returns user token (AP defined)
  16256.  *
  16257.  * Results:    int             Return Code
  16258.  *                             0 = success
  16259.  *                         other = error condition (Server prints error msg)
  16260.  *
  16261.  *--------------------------------------------------------------------------*/
  16262. int sleep_exit(void * srvtoken) {
  16263.    free(SRVUTOK(srvtoken));             /* free the fake control block      */
  16264.    return(0);
  16265. }
  16266.  
  16267. /*==========================================================================*/
  16268. /*   The following wait callback routine is not used in this sample AP, but */
  16269. /*   is provided for documentation purposes.                                */
  16270. /*==========================================================================*/
  16271. /*-F-multi_wait---------------------------------------------------------------
  16272.  *
  16273.  * Purpose:    Server callback to allow wait on multiple file descriptors,
  16274.  *             semaphores, or message queues, including the shared variable
  16275.  *             event queue.
  16276.  *
  16277.  *             Return from this function allows the AP Server to handle
  16278.  *             shared variable (SVP) events.  Typically an AP will wait on the
  16279.  *             notification token along with window, file, or pipe descriptors.
  16280.  *             The AP handles non-SVP events, and simply returns from this
  16281.  *             function when it wants the AP Server to process SVP events
  16282.  *             (which normally result in a call-back to the AP "process" exit
  16283.  *             function to handle the client request).
  16284.  *
  16285.  * Arguments:  void * srvtoken       pointer to AP Server token
  16286.  *
  16287.  *             SRVNTOK(srvtoken)     macro returns shared variable event
  16288.  *                                   notification token (system dependent)
  16289.  *             SRVUTOK(srvtoken)     macro returns user token (AP defined)
  16290.  *
  16291.  * Results:    int             Return Code
  16292.  *                             0 = success
  16293.  *                         other = error condition (Server retracts & ends)
  16294.  *
  16295.  *--------------------------------------------------------------------------*/
  16296. int multi_wait(void * srvtoken) {
  16297. #ifdef __OS2__
  16298.    unsigned long semh = SRVNTOK(srvtoken); /* semaphore handle for sv event */
  16299. #else
  16300.    unsigned long mqid = SRVNTOK(srvtoken); /* message queue id for sv event */
  16301. #endif
  16302. /* AP typically does poll/select (AIX/UNIX) or muxwait (OS/2) at this point */
  16303. /* and continues processing non-SVP events in a while loop until the only   */
  16304. /* event outstanding is an SVP event, at which time it simply returns       */
  16305. /* to the AP Server to read the share event queue and handle the event.     */
  16306.    return(0);
  16307. }
  16308.  
  16309.  
  16310. ΓòÉΓòÉΓòÉ 16.2. SVP Programming Interface ΓòÉΓòÉΓòÉ
  16311.  
  16312. Interface to the SVP is by C function call. There are three entry points based 
  16313. on the service desired. The following sections describe the structures used on 
  16314. these calls: 
  16315.  
  16316. int _System svpp(struct prb *); for SIGNON and SIGNOFF 
  16317.  
  16318. int _System svpe(struct wrb *); for SVEVENT (for example, wait) 
  16319.  
  16320. int _System svps(struct srb *); for all other SVP requests 
  16321.  
  16322. Notes: 
  16323.  
  16324.  1. The APL2/2 interpreter passes all of its command line arguments to any 
  16325.     auxiliary processor that is started automatically. An auxiliary processor 
  16326.     should be prepared to receive arguments that might not be applicable. The 
  16327.     auxiliary processor should, however, always look for an -id parameter and 
  16328.     use the information from the values given when issuing an SVSIGNON. If no 
  16329.     -id parameter is found, the auxiliary processor should sign on with its own 
  16330.     default processor number, and no parent or grandparent. 
  16331.  
  16332.  2. The ntoken returned  on an SVSIGNON and SVSHARE is the handle of an OS/2 
  16333.     event semaphore. Normally this token is only used on an SVEVENT call, but 
  16334.     it can be waited on directly or added to a MuxWait semaphore. It should 
  16335.     never be posted or reset by the auxiliary processor. 
  16336.  
  16337.  3. A SHUTDOWN event is posted to a dependent processor by the SVP when the 
  16338.     parent issues an SVSIGNOFF, or when the SHUTDOWN option is selected from 
  16339.     Options/Info/Processors menu item of the SVP Trace window. It is the 
  16340.     responsibility of the auxiliary processor to retract all variables and 
  16341.     issue an SVSIGNOFF when this signal is received. 
  16342.  
  16343. o PRB Requests 
  16344. o WRB Requests 
  16345. o SRB Requests 
  16346. o SVP Control Blocks 
  16347.  
  16348.  
  16349. ΓòÉΓòÉΓòÉ 16.2.1. PRB Requests ΓòÉΓòÉΓòÉ
  16350.  
  16351. o SVSIGNON - Sign on to the SVP 
  16352. o SVSIGNOFF - Sign off from the SVP 
  16353.  
  16354.  
  16355. ΓòÉΓòÉΓòÉ 16.2.1.1. SVSIGNON - Sign on to the SVP ΓòÉΓòÉΓòÉ
  16356.  
  16357.  prb.req = SVSIGNON 
  16358.  
  16359. Sign on to the Shared Variable Processor. The following additional prb fields 
  16360. must be provided: 
  16361.  
  16362. prb.xid.pparent Grandparent processor number. 
  16363.  
  16364. prb.xid.parent Parent processor number. 
  16365.  
  16366. prb.xid.pparent Processor ID of caller. 
  16367.  
  16368. The following fields are optional: 
  16369.  
  16370. prb.user    An arbitrary token returned on SVEVENT for incoming offers or 
  16371.             shutdown. 
  16372.  
  16373. prb.emask   Event conditions to be masked (not signalled). See WRB Requests for 
  16374.             names of the events. 
  16375.  
  16376. prb.PRBFNPOST If true, disable posting to event queue. 
  16377.  
  16378. prb.PRBFNOTRC If true, disable tracing of SVP events for this processor. 
  16379.  
  16380. The following prb fields are returned: 
  16381.  
  16382. prb.rc      Set to one of the following values: 
  16383.  
  16384.    SVP_OK                        Success 
  16385.    SVP_UNAVAILABLE               SVP not available 
  16386.    SVP_ERROR_INVARG              Argument error 
  16387.    SVP_ERROR_ASO                 Already signed on as xid 
  16388.    SVP_ERROR_PUSED               Another process signed on as xid 
  16389.  
  16390. prb.PRBFOFFS TRUE if one or more offers exist. 
  16391.  
  16392. prb.ntoken  Token used for waiting on SVP events. 
  16393.  
  16394. prb.pcbx    Processor token that must be used on all subsequent SVP calls. 
  16395.  
  16396. Note:  If the SVP shared memory control area has not been initialized, this 
  16397. call automatically starts the process that establishes and owns that area. 
  16398.  
  16399.  
  16400. ΓòÉΓòÉΓòÉ 16.2.1.2. SVSIGNOFF - Sign off from the SVP ΓòÉΓòÉΓòÉ
  16401.  
  16402.  prb.req = SVSIGNOFF 
  16403.  
  16404. Sign off from the Shared Variable Processor. The following additional prb field 
  16405. must be provided: 
  16406.  
  16407. prb.pcbx    The processor token that was returned by SVSIGNON. 
  16408.  
  16409. prb.rc      Set to one of the following values: 
  16410.  
  16411.    SVP_OK                        Success 
  16412.    SVP_UNAVAILABLE               SVP not available 
  16413.    SVP_ERROR_INVARG              Argument error 
  16414.    SVP_ERROR_NSO                 Processor not signed on 
  16415.  
  16416. Notes: 
  16417.  
  16418.  1. If the SVP was automatically started by a signon, a usage count of 
  16419.     processors is maintained and the SVP process is shut down when that count 
  16420.     reaches 0. 
  16421.  
  16422.  2. The SVP retracts all variables shared with or offered from the processor 
  16423.     during signoff. 
  16424.  
  16425.  
  16426. ΓòÉΓòÉΓòÉ 16.2.2. WRB Requests ΓòÉΓòÉΓòÉ
  16427.  
  16428.  wrb.req = SVEVENT 
  16429.  
  16430. Wait for an SVP event. This can be either a processor event (such as an 
  16431. incoming offer) or a shared variable event (such as variable set by partner). 
  16432. The following additional wrb fields must be provided: 
  16433.  
  16434. wrb.pcbx    The processor token that was returned by SVSIGNON. 
  16435.  
  16436. wrb.ntoken  A notification token returned by either SVSIGNON or SVSHARE. 
  16437.  
  16438. wrb.timeout Maximum time to wait in milliseconds if nonnegative. Use -1 to wait 
  16439.             indefinitely for an event. 
  16440.  
  16441. The following flag is optional: 
  16442.  
  16443. wrb.WRBFFLUSH If true, causes the event queue to be flushed on return. 
  16444.  
  16445. The following wrb fields are filled in on return: 
  16446.  
  16447. wrb.rc      One of the following return codes: 
  16448.  
  16449.    SVP_OK                        Success 
  16450.    SVP_UNAVAILABLE               SVP not available 
  16451.    SVP_ERROR_NSO                 Processor not signed on 
  16452.    SVP_ERROR_INVARG              Invalid argument 
  16453.    SVP_ERROR_NOEVENT             No event found before time expired 
  16454.    SVP_ERROR_TIMEOUT             Timeout occurred with no event 
  16455.  
  16456. wrb.user    For SVP_EVENT_SHUTDOWN or SVP_EVENT_OFFEREX this is the value 
  16457.             provided in prb.user at SVSIGNON. For all other events it is the 
  16458.             value provided in srb.user at SVSHARE. 
  16459.  
  16460. wrb.event   One of the following event codes: 
  16461.  
  16462.    SVP_EVENT_SHUTDOWN            SVP shutdown 
  16463.    SVP_EVENT_OFFEREX             Offer extended 
  16464.    SVP_EVENT_OFFERAC             Offer accepted 
  16465.    SVP_EVENT_SMAVAIL             Shared memory available 
  16466.    SVP_EVENT_PRETRACT            Partner retracted 
  16467.    SVP_EVENT_PSETACV             Partner set ACV 
  16468.    SVP_EVENT_PSPEC               Partner specified 
  16469.    SVP_EVENT_PREF                Partner referenced 
  16470.    SVP_EVENT_FSPEC               Partner failed specified 
  16471.    SVP_EVENT_FREF                Partner failed reference 
  16472.    SVP_EVENT_PRELEASE            Partner released variable 
  16473.  
  16474. wrb.scbx    (except for SVP_EVENT_SHUTDOWN) For SVP_EVENT_OFFEREX, a variable 
  16475.             token that can be used for a matching SVSHARE. For other events, 
  16476.             the variable token that was used when sharing the variable. 
  16477.  
  16478. wrb.osn     (SVP_EVENT_OFFEREX only) A sequence number that can be used for a 
  16479.             matching SVSHARE to verify that the offer being reported is still 
  16480.             outstanding. 
  16481.  
  16482. Note:  Only one event is returned. The auxiliary processor should continue to 
  16483. make calls (to retrieve all events) until SVP_ERROR_NOEVENT is received. 
  16484.  
  16485.  
  16486. ΓòÉΓòÉΓòÉ 16.2.3. SRB Requests ΓòÉΓòÉΓòÉ
  16487.  
  16488. The following sections discuss the SRB requests. 
  16489.  
  16490. o Offering and Retracting Variables 
  16491. o Setting and Using Data in Variables 
  16492. o Obtaining or Setting Information about Variables 
  16493.  
  16494.  
  16495. ΓòÉΓòÉΓòÉ 16.2.3.1. Offering and Retracting Variables ΓòÉΓòÉΓòÉ
  16496.  
  16497. o SVSHARE - Offer a variable 
  16498. o SVSHARE - Match an offer 
  16499. o SVRETRACT - Retract a share 
  16500.  
  16501.  
  16502. ΓòÉΓòÉΓòÉ 16.2.3.1.1. SVSHARE - Offer a variable ΓòÉΓòÉΓòÉ
  16503.  
  16504.  srb.req = SVSHARE  srb.scbx = 0 
  16505.  
  16506. Use this services to offer a new variable to some processor. The following 
  16507. additional srb fields must be provided: 
  16508.  
  16509. srb.pcbx    The processor token that was returned by SVSIGNON. 
  16510.  
  16511. srb.pxid.procid The identification number of the partner to whom the offer is 
  16512.             made. 
  16513.  
  16514. srb.scbx    Must be zero to indicate a new offer. 
  16515.  
  16516. The following fields are optional: 
  16517.  
  16518. srb.osn     Offer sequence number. Only offers with osn greater than this can 
  16519.             be used to match the offer. 
  16520.  
  16521. srb.user    User field, returned on SVEVENT. 
  16522.  
  16523. srb.acv     Access control (see SVP Control Blocks). 
  16524.  
  16525. srb.name    Variable name (up to 255 chars). 
  16526.  
  16527. srb.SRBFNEWQ True to request a separate event queue to be used for this 
  16528.             variable. If false, the processor event queue is used for all 
  16529.             events. 
  16530.  
  16531. srb.SRBFNPOST True to request that no events be signalled for this variable. 
  16532.  
  16533. srb.SRBFNOFFR True to disable automatic reoffer on partner's retract. It is 
  16534.             recommended that all auxiliary processors turn this flag on. 
  16535.  
  16536. The following srb fields are filled in on return: 
  16537.  
  16538. srb.rc      One of the following return codes: 
  16539.  
  16540.    SVP_OK                        Success 
  16541.    SVP_UNAVAILABLE               SVP not available 
  16542.    SVP_ERROR_NSO                 Processor not signed on 
  16543.    SVP_ERROR_SHRSLF              Offer to self 
  16544.    SVP_ERROR_INVARG              Invalid argument 
  16545.  
  16546. srb.pxid    Extended ID of corresponding offer, if found. 
  16547.  
  16548. srb.osn     Offer sequence number. 
  16549.  
  16550. srb.scbx    A token associated with this share, that must be used on all 
  16551.             subsequent requests. 
  16552.  
  16553. srb.ntoken  A signalling token. This is unique to the variable if srb.SRBFNEWQ 
  16554.             was set, otherwise the processor ntoken is returned. 
  16555.  
  16556. srb.acv     Access control (see SVP Control Blocks). 
  16557.  
  16558. srb.state   Shared variable state. 
  16559.  
  16560. srb.coupling Degree of coupling. 
  16561.  
  16562. Note:  If a share request is made and no corresponding offer is found, a search 
  16563. is made for a file named apnnn, where nnn is the srb.procid. If this file is 
  16564. found, it is executed. 
  16565.  
  16566.  
  16567. ΓòÉΓòÉΓòÉ 16.2.3.1.2. SVSHARE - Match an offer ΓòÉΓòÉΓòÉ
  16568.  
  16569.  srb.req = SVSHARE  srb.scbx = variable_token 
  16570.  
  16571. Match an offer that has already been made to this processor. This service 
  16572. requires information (including srb.scbx) that has been provided by SVSCAN or 
  16573. SVEVENT. The following additional srb fields must be provided: 
  16574.  
  16575. srb.pcbx       The processor token that was returned by SVSIGNON. 
  16576.  
  16577. srb.scbx       As returned by SVSCAN or SVEVENT. 
  16578.  
  16579. srb.osn        Offer sequence number. If not zero, only an offer with the same 
  16580.                OSN can be used to match the offer. 
  16581.  
  16582. srb.user       User field, returned on SVEVENT. 
  16583.  
  16584. srb.acv        Access control (see SVP Control Blocks). 
  16585.  
  16586. srb.SRBFNEWQ   True to request a separate event queue to be used for this 
  16587.                variable. If false, the processor event queue is used for all 
  16588.                events. 
  16589.  
  16590. srb.SRBFNPOST  True to request no event queue to be used for this variable. 
  16591.  
  16592. The following srb fields are filled in on return: 
  16593.  
  16594. srb.rc         One of the following return codes: 
  16595.  
  16596.    SVP_OK                        Success 
  16597.    SVP_UNAVAILABLE               SVP not available 
  16598.    SVP_ERROR_NSO                 Processor not signed on 
  16599.    SVP_ERROR_SHRSLF              Offer to self 
  16600.    SVP_ERROR_INVARG              Invalid argument (including OSN mismatch) 
  16601.    SVP_ERROR_NOOFFER             No offer found 
  16602.  
  16603. srb.pxid       Extended ID of corresponding offer, if found. 
  16604.  
  16605. srb.ntoken     A signalling token. This is unique to the variable if 
  16606.                srb.SRBFNEWQ was set, otherwise the processor ntoken is 
  16607.                returned. 
  16608.  
  16609. srb.acv        Access control (see SVP Control Blocks). 
  16610.  
  16611. srb.state      Shared variable state. 
  16612.  
  16613. srb.coupling   Degree of coupling. 
  16614.  
  16615.  
  16616. ΓòÉΓòÉΓòÉ 16.2.3.1.3. SVRETRACT - Retract a share ΓòÉΓòÉΓòÉ
  16617.  
  16618.  srb.req = SVRETRACT 
  16619.  
  16620. Retract a shared variable or share offer. The following additional srb fields 
  16621. must be provided: 
  16622.  
  16623. srb.pcbx       The processor token that was returned by SVSIGNON. 
  16624.  
  16625. srb.scbx       The variable token that was returned or used by SVSHARE. 
  16626.  
  16627. The following srb fields are filled in on return: 
  16628.  
  16629. srb.rc         One of the following return codes: 
  16630.  
  16631.    SVP_OK                        Success 
  16632.    SVP_UNAVAILABLE               SVP not available 
  16633.    SVP_ERROR_NSO                 Processor not signed on 
  16634.    SVP_ERROR_INVARG              Invalid argument 
  16635.  
  16636. srb.coupling   Degree of coupling. 
  16637.  
  16638.  
  16639. ΓòÉΓòÉΓòÉ 16.2.3.2. Setting and Using Data in Variables ΓòÉΓòÉΓòÉ
  16640.  
  16641. In order to gain access to shared variable data, a processor must obtain a 
  16642. temporary lock, so that the partner does not attempt to update the data or 
  16643. change the variable's state during the accessing process. The processor 
  16644. commonly gets a lock implicitly through an SVPREREF or SVPRESPEC request. It is 
  16645. also possible to issue any of the SVPREREF or SVPRESPEC requests when the 
  16646. variable's lock is already held. Eventually, the processor must issue 
  16647. SVRELEASE, or more typically SVREF or SVSPEC, to release the lock. Applications 
  16648. should minimize the time that they hold the lock. No count is maintained, so a 
  16649. single unlocking request unlocks the variable no matter how many lock requests 
  16650. were issued. 
  16651.  
  16652. The second function provided by the locking requests is to give the calling 
  16653. program access to a data buffer. When SVPREREF is used, this buffer contains 
  16654. the current value of the variable. For SVPRESPEC, a buffer is provided of a 
  16655. caller-specified size. In either case, the buffer is available only until the 
  16656. next locking or unlocking request is issued. 
  16657.  
  16658. The three unlocking requests differ only in the effects they have on the access 
  16659. state of the variable. The system does not check for any correspondence between 
  16660. the locking request and the subsequent unlocking request. The normal sequence 
  16661. is, of course, to use SVPREREF followed by SVREF to reference a variable, and 
  16662. SVPRESPEC followed by SVSPEC to specify a new value for a variable. However, 
  16663. other sequences that can be useful on occasion include: 
  16664.  
  16665. o SVPREREF or SVRELEASE to peek at a value set by your partner without actually 
  16666.   referencing it. 
  16667.  
  16668. o SVPREREF, SVPRESPEC, or SVSPEC to look at a value set by your partner and 
  16669.   then replace it without losing the lock between reference and specification. 
  16670.  
  16671. o SVPREREF or SVSPEC to update part of the value in place, and inform your 
  16672.   partner that the change has occurred. 
  16673.  
  16674. o SVRELEASE to look at the last value assigned to a variable even though you 
  16675.   have already referenced it. 
  16676.  
  16677. o SVPREREF - Start variable reference 
  16678. o SVREF - Finish variable reference 
  16679. o SVPRESPEC - Start variable assignment 
  16680. o SVSPEC - Finish variable assignment 
  16681. o SVRELEASE - Release a preRef or preSpec 
  16682.  
  16683.  
  16684. ΓòÉΓòÉΓòÉ 16.2.3.2.1. SVPREREF - Start variable reference ΓòÉΓòÉΓòÉ
  16685.  
  16686.  srb.req = SVPREREF 
  16687.  
  16688. First stage of referencing (obtaining the current value of) a variable. This 
  16689. call provides a pointer to the variable's value, and locks the variable until 
  16690. SVREF is issued. The partner cannot issue further requests against the variable 
  16691. until it is unlocked by an SVSPEC, SVREF, or SVRELEASE. The following 
  16692. additional srb fields must be provided: 
  16693.  
  16694. srb.pcbx       The processor token that was returned by SVSIGNON. 
  16695.  
  16696. srb.scbx       The variable token that was returned or used by SVSHARE. 
  16697.  
  16698. The following srb fields are filled in on return: 
  16699.  
  16700. srb.rc         One of the following return codes: 
  16701.  
  16702.    SVP_OK                        Success 
  16703.    SVP_UNAVAILABLE               SVP not available 
  16704.    SVP_ERROR_NSO                 Processor not signed on 
  16705.    SVP_ERROR_NONV                No new value 
  16706.    SVP_ERROR_INVARG              Invalid argument 
  16707.  
  16708. srb.vlen       Size of object. 
  16709.  
  16710. srb.value      Pointer to object. 
  16711.  
  16712. srb.acv        Access control (see SVP Control Blocks). 
  16713.  
  16714. srb.state      Shared variable state. 
  16715.  
  16716. srb.coupling   Degree of coupling. 
  16717.  
  16718.  
  16719. ΓòÉΓòÉΓòÉ 16.2.3.2.2. SVREF - Finish variable reference ΓòÉΓòÉΓòÉ
  16720.  
  16721.  srb.req = SVREF 
  16722.  
  16723. Second stage of referencing (obtaining the current value of) a variable. This 
  16724. call notifies the SVP that the value has been extracted, and unlocks the 
  16725. variable. The value pointed to by srb.value on return from SVPREREF can no 
  16726. longer be accessed after issuing this call. The following additional srb fields 
  16727. must be provided: 
  16728.  
  16729. srb.pcbx       The processor token that was returned by SVSIGNON. 
  16730.  
  16731. srb.scbx       The variable token that was returned or used by SVSHARE. 
  16732.  
  16733. The following srb fields are filled in on return: 
  16734.  
  16735. srb.rc         One of the following return codes: 
  16736.  
  16737.    SVP_OK                        Success 
  16738.    SVP_UNAVAILABLE               SVP not available 
  16739.    SVP_ERROR_NSO                 Processor not signed on 
  16740.    SVP_ERROR_INVARG              Invalid argument 
  16741.  
  16742. srb.acv        Access control (see SVP Control Blocks). 
  16743.  
  16744. srb.state      Shared variable state. 
  16745.  
  16746. srb.coupling   Degree of coupling. 
  16747.  
  16748.  
  16749. ΓòÉΓòÉΓòÉ 16.2.3.2.3. SVPRESPEC - Start variable assignment ΓòÉΓòÉΓòÉ
  16750.  
  16751.  srb.req = SVPRESPEC 
  16752.  
  16753. First stage of specifying a value for a variable. This call provides a pointer 
  16754. to a location where the new value for the variable is to be placed, and locks 
  16755. the variable until SVSPEC is issued. The partner cannot issue further requests 
  16756. against the variable until it is unlocked. The following additional srb fields 
  16757. must be provided: 
  16758.  
  16759. srb.pcbx       The processor token that was returned by SVSIGNON. 
  16760.  
  16761. srb.scbx       The variable token that was returned or used by SVSHARE. 
  16762.  
  16763. srb.vlen       Size of object. 
  16764.  
  16765. srb.SRBFIGNV   True to ignore any unreferenced value. 
  16766.  
  16767. The following srb fields are filled in on return: 
  16768.  
  16769. srb.rc         One of the following return codes: 
  16770.  
  16771.    SVP_OK                        Success 
  16772.    SVP_UNAVAILABLE               SVP not available 
  16773.    SVP_ERROR_NSO                 Processor not signed on 
  16774.    SVP_ERROR_INVARG              Invalid argument 
  16775.    SVP_SMNOSPACE                 Space not available 
  16776.    SVP_INTERLOCK                 Variable interlocked 
  16777.    SVP_ERROR_VOS                 Partner's value not read 
  16778.  
  16779. srb.acv        Access control (see SVP Control Blocks). 
  16780.  
  16781. srb.state      Shared variable state. 
  16782.  
  16783. srb.value      Pointer to area to write object. 
  16784.  
  16785. srb.coupling   Degree of coupling. 
  16786.  
  16787.  
  16788. ΓòÉΓòÉΓòÉ 16.2.3.2.4. SVSPEC - Finish variable assignment ΓòÉΓòÉΓòÉ
  16789.  
  16790.  srb.req = SVSPEC 
  16791.  
  16792. Second stage of specifying a value for a variable. This call notifies the SVP 
  16793. that the new value is in place, and unlocks the variable. The value pointed to 
  16794. by srb.value on return from SVPRESPE can no longer be accessed after issuing 
  16795. this call. The following additional srb fields must be provided: 
  16796.  
  16797. srb.pcbx       The processor token that was returned by SVSIGNON. 
  16798.  
  16799. srb.scbx       The variable token that was returned or used by SVSHARE. 
  16800.  
  16801. The following srb fields are filled in on return: 
  16802.  
  16803. srb.rc         One of the following return codes: 
  16804.  
  16805.    SVP_OK                        Success 
  16806.    SVP_UNAVAILABLE               SVP not available 
  16807.    SVP_ERROR_NSO                 Processor not signed on 
  16808.    SVP_ERROR_INVARG              Invalid argument 
  16809.  
  16810. srb.acv        Access control (see SVP Control Blocks). 
  16811.  
  16812. srb.state      Shared variable state. 
  16813.  
  16814. srb.coupling   Degree of coupling. 
  16815.  
  16816.  
  16817. ΓòÉΓòÉΓòÉ 16.2.3.2.5. SVRELEASE - Release a preRef or preSpec ΓòÉΓòÉΓòÉ
  16818.  
  16819.  srb.req = SVRELEASE 
  16820.  
  16821. Release a variable previously locked by SVPREREF or SVPRESPEC without changing 
  16822. its state. The area pointed to by srb.value on return from the locking call can 
  16823. no longer be accessed after issuing this call. The following additional srb 
  16824. fields must be provided: 
  16825.  
  16826. srb.pcbx       The processor token that was returned by SVSIGNON. 
  16827.  
  16828. srb.scbx       The variable token that was returned or used by SVSHARE. 
  16829.  
  16830. The following srb fields are filled in on return: 
  16831.  
  16832. srb.rc         One of the following return codes: 
  16833.  
  16834.    SVP_OK                        Success 
  16835.    SVP_UNAVAILABLE               SVP not available 
  16836.    SVP_ERROR_NSO                 Processor not signed on 
  16837.    SVP_ERROR_INVARG              Invalid argument 
  16838.  
  16839. srb.acv        Access control (see SVP Control Blocks). 
  16840.  
  16841. srb.state      Shared variable state. 
  16842.  
  16843. srb.coupling   Degree of coupling. 
  16844.  
  16845.  
  16846. ΓòÉΓòÉΓòÉ 16.2.3.3. Obtaining or Setting Information about Variables ΓòÉΓòÉΓòÉ
  16847.  
  16848. o SVSHARE - Inquire about a share offer 
  16849. o SVSCAN - Scan for a share offer 
  16850. o SVSEEACV - Query access control 
  16851. o SVSETACV - Set access control 
  16852. o SVSTATE - Query variable state 
  16853.  
  16854.  
  16855. ΓòÉΓòÉΓòÉ 16.2.3.3.1. SVSHARE - Inquire about a share offer ΓòÉΓòÉΓòÉ
  16856.  
  16857.  srb.req = SVSHARE  srb.scbx = variable_token 
  16858.  
  16859. Obtain information about a previous share offer. The following additional srb 
  16860. fields must be provided: 
  16861.  
  16862. srb.pcbx       The processor token that was returned by SVSIGNON. 
  16863.  
  16864. srb.pxid       Partner extended ID, or zero. If zero, this value is returned. 
  16865.  
  16866. srb.scbx       Variable token from original offer. 
  16867.  
  16868. The following srb fields are filled in on return: 
  16869.  
  16870. srb.rc         One of the following return codes: 
  16871.  
  16872.    SVP_OK                        Success 
  16873.    SVP_UNAVAILABLE               SVP not available 
  16874.    SVP_ERROR_NSO                 Processor not signed on 
  16875.    SVP_ERROR_INVARG              Invalid argument 
  16876.    SVP_ERROR_NOOFFER             No offer found 
  16877.  
  16878. srb.pxid       Extended ID of partner. 
  16879.  
  16880. srb.acv        Access control (see SVP Control Blocks). 
  16881.  
  16882. srb.state      Shared variable state. 
  16883.  
  16884. srb.coupling   Degree of coupling. 
  16885.  
  16886.  
  16887. ΓòÉΓòÉΓòÉ 16.2.3.3.2. SVSCAN - Scan for a share offer ΓòÉΓòÉΓòÉ
  16888.  
  16889.  srb.req = SVSCAN 
  16890.  
  16891. Scan for an incoming shared variable offer. The following additional srb fields 
  16892. must be provided: 
  16893.  
  16894. srb.pcbx       The processor token that was returned by SVSIGNON. 
  16895.  
  16896. srb.pxid       If pxid.procid is zero, scan for offers from any processor. 
  16897.                Otherwise, only offers from the specified processor are checked. 
  16898.  
  16899. srb.osn        Offer sequence number. If nonzero, and srb.scbx=0, only offers 
  16900.                with a sequence number greater than that specified are checked. 
  16901.                This allows the scan to be repeated to search for additional 
  16902.                offers, and also assists in rotating limited resources among 
  16903.                requestors. 
  16904.  
  16905.                If both srb.osn and srb.scbx=0 are nonzero, the osn value is 
  16906.                used as a verification against the offer identified by the scbx. 
  16907.  
  16908. srb.name       A null-delimited character string. If a nonempty name is 
  16909.                specified, only offers for this variable name are checked. 
  16910.  
  16911. srb.scbx       Normally must be zero, but can be set to identify a specific 
  16912.                partner. 
  16913.  
  16914. The following srb fields are filled in on return: 
  16915.  
  16916. srb.rc         One of the following return codes: 
  16917.  
  16918.    SVP_OK                        Success 
  16919.    SVP_UNAVAILABLE               SVP not available 
  16920.    SVP_ERROR_NSO                 Processor not signed on 
  16921.    SVP_ERROR_INVARG              Invalid argument 
  16922.    SVP_ERROR_NOOFFER             No offer found 
  16923.  
  16924. srb.pxid       Extended ID of corresponding offer, if found. 
  16925.  
  16926. srb.osn        Offer sequence number. 
  16927.  
  16928. srb.scbx       SCB index of offer. 
  16929.  
  16930. srb.name       Variable name. 
  16931.  
  16932.  
  16933. ΓòÉΓòÉΓòÉ 16.2.3.3.3. SVSEEACV - Query access control ΓòÉΓòÉΓòÉ
  16934.  
  16935. srb.req = SVSEEACV 
  16936.  
  16937. Query access control. The following additional srb fields must be provided: 
  16938.  
  16939. srb.pcbx       The processor token that was returned by SVSIGNON. 
  16940.  
  16941. srb.scbx       The variable token that was returned or used by SVSHARE. 
  16942.  
  16943. The following srb fields are filled in on return: 
  16944.  
  16945. srb.rc         One of the following return codes: 
  16946.  
  16947.    SVP_OK                        Success 
  16948.    SVP_UNAVAILABLE               SVP not available 
  16949.    SVP_ERROR_NSO                 Processor not signed on 
  16950.    SVP_ERROR_INVARG              Invalid argument 
  16951.  
  16952. srb.acv        Access control (see SVP Control Blocks). 
  16953.  
  16954. srb.state      Shared variable state. 
  16955.  
  16956. srb.coupling   Degree of coupling. 
  16957.  
  16958.  
  16959. ΓòÉΓòÉΓòÉ 16.2.3.3.4. SVSETACV - Set access control ΓòÉΓòÉΓòÉ
  16960.  
  16961.  srb.req = SVSETACV 
  16962.  
  16963. Set access control. The following additional srb fields must be provided: 
  16964.  
  16965. srb.pcbx       The processor token that was returned by SVSIGNON. 
  16966.  
  16967. srb.scbx       The variable token that was returned or used by SVSHARE. 
  16968.  
  16969. srb.acv        Access control desired (see SVP Control Blocks). 
  16970.  
  16971. The following srb fields are filled in on return: 
  16972.  
  16973. srb.rc         One of the following return codes: 
  16974.  
  16975.    SVP_OK                        Success 
  16976.    SVP_UNAVAILABLE               SVP not available 
  16977.    SVP_ERROR_NSO                 Processor not signed on 
  16978.    SVP_ERROR_INVARG              Invalid argument 
  16979.  
  16980. srb.acv        Access control (see SVP Control Blocks). 
  16981.  
  16982. srb.state      Shared variable state. 
  16983.  
  16984. srb.coupling   Degree of coupling. 
  16985.  
  16986.  
  16987. ΓòÉΓòÉΓòÉ 16.2.3.3.5. SVSTATE - Query variable state ΓòÉΓòÉΓòÉ
  16988.  
  16989.  srb.req = SVSTATE 
  16990.  
  16991. Query shared variable state. The following additional srb fields must be 
  16992. provided: 
  16993.  
  16994. srb.pcbx       The processor token that was returned by SVSIGNON. 
  16995.  
  16996. srb.scbx       The variable token that was returned or used by SVSHARE. 
  16997.  
  16998. The following srb fields are filled in on return: 
  16999.  
  17000. srb.rc         One of the following return codes: 
  17001.  
  17002.    SVP_OK                        Success 
  17003.    SVP_UNAVAILABLE               SVP not available 
  17004.    SVP_ERROR_NSO                 Processor not signed on 
  17005.    SVP_ERROR_INVARG              Invalid argument 
  17006.  
  17007. srb.acv        Access control (see SVP Control Blocks). 
  17008.  
  17009. srb.state      Shared variable state. 
  17010.  
  17011. srb.coupling   Degree of coupling. 
  17012.  
  17013. Notes: 
  17014.  
  17015.  1. In addition to the return codes listed, SVP_ERROR_SYSTEM can be returned if 
  17016.     the SVP receives an error from an OS/2 system call. If this return code is 
  17017.     received, prb.reason (or srb.reason or wrb.reason) provides an additional 
  17018.     reason code. (See SVP Reason Codes for a listing of these reason codes 
  17019.     beginning with SVP_ERRSYS_xxx.) 
  17020.  
  17021.  2. Similarly, if the SVP_ERROR_INVARG return code is received, the reason code 
  17022.     is set to one of the SVP_ARGERR_xxx values. 
  17023.  
  17024.  
  17025. ΓòÉΓòÉΓòÉ 16.2.4. SVP Control Blocks ΓòÉΓòÉΓòÉ
  17026.  
  17027. The control blocks shown here are defined in C include file aplap.h. See also 
  17028. Common Data Representation. 
  17029.  
  17030. o Extended ID Structure 
  17031. o Processor Request Block 
  17032. o Share Request Block 
  17033. o Wait Request Block 
  17034. o SVP Requests 
  17035. o SVP Return Codes 
  17036. o SVP Reason Codes 
  17037. o SVP Event Codes 
  17038. o Function Prototypes 
  17039.  
  17040.  
  17041. ΓòÉΓòÉΓòÉ 16.2.4.1. Extended ID Structure ΓòÉΓòÉΓòÉ
  17042.  
  17043. struct xid {                 /* Extended ID structure               */
  17044.     unsigned long pparent;   /*  Parent's Parent ID                 */
  17045.     unsigned long parent;    /*  Parent ID                          */
  17046.     unsigned long procid;    /*  Processor ID                       */
  17047.     unsigned long hostid;    /*  Host ID (TCP/IP address)           */
  17048.     unsigned long res1;      /*  Reserved                           */
  17049.     unsigned long res2;      /*  Reserved                           */
  17050.     char userid[8];          /*  User ID                            */
  17051.     char surrid[8];          /*  Surrogate ID                       */
  17052.     };
  17053. struct flags {
  17054.     unsigned int b1:1;
  17055.     unsigned int b2:1;
  17056.     unsigned int b3:1;
  17057.     unsigned int b4:1;
  17058.     unsigned int b5:1;
  17059.     unsigned int b6:1;
  17060.     unsigned int b7:1;
  17061.     unsigned int b8:1;
  17062.     unsigned int b9:1;
  17063.     unsigned int b10:1;
  17064.     unsigned int b11:1;
  17065.     unsigned int b12:1;
  17066.     unsigned int b13:1;
  17067.     unsigned int b14:1;
  17068.     unsigned int b15:1;
  17069.     unsigned int b16:1;
  17070.     unsigned int b17:1;
  17071.     unsigned int b18:1;
  17072.     unsigned int b19:1;
  17073.     unsigned int b20:1;
  17074.     unsigned int b21:1;
  17075.     unsigned int b22:1;
  17076.     unsigned int b23:1;
  17077.     unsigned int b24:1;
  17078.     unsigned int b25:1;
  17079.     unsigned int b26:1;
  17080.     unsigned int b27:1;
  17081.     unsigned int b28:1;
  17082.     unsigned int b29:1;
  17083.     unsigned int b30:1;
  17084.     unsigned int b31:1;
  17085.     unsigned int b32:1;
  17086.     };
  17087.  
  17088.  
  17089. ΓòÉΓòÉΓòÉ 16.2.4.2. Processor Request Block ΓòÉΓòÉΓòÉ
  17090.  
  17091. struct prb {
  17092.     short req;                 /*  Request code              */
  17093.     short rc;                  /*  Return code               */
  17094.     short reason;              /*  Reason code               */
  17095.     short res1;                /*  Reserved                  */
  17096.     struct xid xid;            /*  Extended ID               */
  17097.     void *user;                /*  User field                */
  17098.     unsigned long emask;       /*  Event mask                */
  17099.     unsigned long ntoken;      /*  Notification token        */
  17100.     unsigned long pcbx;        /*  PCB index                 */
  17101.     unsigned long socket;      /*  Socket number             */
  17102.     char ** argv;              /*  Command line args ptr     */
  17103.     int argc;                  /*  Count of args             */
  17104.     void *res2;                /*  Reserved                  */
  17105.     struct flags prbflags;     /*  Processor flags           */
  17106.     char reserved[32];         /*  Reserved                  */
  17107.     };
  17108. #define PRBFOFFS  prbflags.b1  /*  Offers outstanding        */
  17109. #define PRBFNPOST prbflags.b3  /*  Don't post                */
  17110. #define PRBFNOTRC prbflags.b4  /*  Don't trace               */
  17111.  
  17112.  
  17113. ΓòÉΓòÉΓòÉ 16.2.4.3. Share Request Block ΓòÉΓòÉΓòÉ
  17114.  
  17115. struct srb {
  17116.     short req;                 /*  Request code              */
  17117.     short rc;                  /*  Return code               */
  17118.     short reason;              /*  Reason code               */
  17119.     short res1;                /*  Reserved                  */
  17120.     void *user;                /*  User field                */
  17121.     unsigned long ntoken;      /*  Notification token        */
  17122.     unsigned long pcbx;        /*  PCB index                 */
  17123.     unsigned long scbx;        /*  SCB index                 */
  17124.     struct xid pxid;           /*  Extended Partner ID       */
  17125.     long osn;                  /*  Offer sequence number     */
  17126.     long vlen;                 /*  Length of value           */
  17127.     void *value;               /*  Pointer to value          */
  17128.     unsigned long pvrba;       /*  Reserved                  */
  17129.     unsigned short acv;        /*  Access control            */
  17130.     unsigned short state;      /*  State                     */
  17131.     unsigned short coupling;   /*  Coupling                  */
  17132.     unsigned short res2;       /*  Reserved                  */
  17133.     struct flags srbflags;     /*  Flags                     */
  17134.     unsigned long socket;      /*  socket number             */
  17135.     unsigned long socksem;     /*  socket send sem-id (UNIX) */
  17136.     char reserved[32];         /*  Reserved                  */
  17137.     char name[256];            /*  Variable name             */
  17138.     };
  17139. #define SRBFIGNV  srbflags.b1  /*  Ignore value waiting      */
  17140. #define SRBFNEWQ  srbflags.b2  /*  Request new event queue   */
  17141. #define SRBFNPOST srbflags.b4  /*  Don't post                */
  17142. #define SRBFNOFFR srbflags.b5  /*  No offer back on retract  */
  17143.  
  17144.  
  17145. ΓòÉΓòÉΓòÉ 16.2.4.4. Wait Request Block ΓòÉΓòÉΓòÉ
  17146.  
  17147. struct wrb {
  17148.    short req;                  /* Request code               */
  17149.    short rc;                   /* Return code                */
  17150.    short reason;               /* Reason code                */
  17151.    short res1;                 /* Reserved                   */
  17152.    void *user;                 /* User field                 */
  17153.    unsigned long ntoken;       /* Notification token         */
  17154.    unsigned long pcbx;         /* PCB index                  */
  17155.    unsigned long scbx;         /* SCB index                  */
  17156.    unsigned long osn;          /* offer sequence number      */
  17157.    long timeout;               /* Timeout value              */
  17158.    unsigned long event;        /* Event code                 */
  17159.    struct flags wrbflags;      /* Flags                      */
  17160.    char reserved[16];          /* Reserved                   */
  17161.    };
  17162. #define WRBFFLUSH wrbflags.b1  /*  Flush event queue         */
  17163.  
  17164.  
  17165. ΓòÉΓòÉΓòÉ 16.2.4.5. SVP Requests ΓòÉΓòÉΓòÉ
  17166.  
  17167. #define SVINIT         0
  17168. #define SVSIGNON       1
  17169. #define SVSIGNOFF      2
  17170. #define SVSCAN         3
  17171. #define SVSHARE        4
  17172. #define SVSEEACV       5
  17173. #define SVSETACV       6
  17174. #define SVREF          7
  17175. #define SVSPEC         8
  17176. #define SVRELEASE      11
  17177. #define SVRETRACT      12
  17178. #define SVSTATE        13
  17179. #define SVQUERY        14
  17180. #define SVPREREF       15
  17181. #define SVPRESPEC      16
  17182. #define SVEVENT        17
  17183. #define SVPOST         18
  17184. #define SVGETTOKEN     19
  17185.  
  17186.  
  17187. ΓòÉΓòÉΓòÉ 16.2.4.6. SVP Return Codes ΓòÉΓòÉΓòÉ
  17188.  
  17189. #define SVP_ERROR_SYSTEM  - 3     /* System Error                  */
  17190. #define SVP_SMNOSPACE     - 2     /* No space for object           */
  17191. #define SVP_INTERLOCK     - 1     /* variable interlocked          */
  17192. #define SVP_OK              0     /* A-OK                          */
  17193. #define SVP_UNAVAILABLE     1     /* SVP is unavailable            */
  17194. #define SVP_ERROR_PROTEXCP  2     /* Protection exception          */
  17195. #define SVP_ERROR_NSO       3     /* Not signed on                 */
  17196. #define SVP_ERROR_ASO       4     /* Already signed on             */
  17197. #define SVP_ERROR_PUSED     5     /* Processor in use              */
  17198. #define SVP_ERROR_SHRSELF   8     /* Share with self               */
  17199. #define SVP_ERROR_VTL       10    /* Value too large               */
  17200. #define SVP_ERROR_NOVALUE   11    /* No value                      */
  17201. #define SVP_ERROR_NOOFFER   12    /* No offer found                */
  17202. #define SVP_ERROR_INVREQ    13    /* Invalid request               */
  17203. #define SVP_ERROR_VOS       14    /* Unread value exists           */
  17204. #define SVP_ERROR_INVARG    15    /* Invalid argument              */
  17205. #define SVP_ERROR_NOEVENT   16    /* No event found                */
  17206. #define SVP_ERROR_TIMEOUT   17    /* Timeout on SVEVENT            */
  17207. #define SVP_ERROR_INTERRUPT 18    /* Interrupt on wait             */
  17208.  
  17209.  
  17210. ΓòÉΓòÉΓòÉ 16.2.4.7. SVP Reason Codes ΓòÉΓòÉΓòÉ
  17211.  
  17212. #define SVP_ERRSYS_GETNMEM   100   /* Error getting named sh mem    */
  17213. #define SVP_ERRSYS_FREEMEM   101   /* Error freeing sh mem          */
  17214. #define SVP_ERRSYS_SUBFREE   102   /* Error freeing pcb/scb space   */
  17215. #define SVP_ERRSYS_NOPCBS    103   /* Unable to obtain new PCB      */
  17216. #define SVP_ERRSYS_NOSCBS    104   /* Unable to obtain new SCB      */
  17217. #define SVP_ERRSYS_GETESEM   105   /* Error creating event sem      */
  17218. #define SVP_ERRSYS_POSTQUEUE 106   /* Error on post of queue        */
  17219. #define SVP_ERRSYS_WAITESEM  107   /* Error on wait for semaphore   */
  17220. #define SVP_ERRSYS_RESETESEM 108   /* Reset semaphore error         */
  17221. #define SVP_ERRSYS_OPENSEM   109   /* Error opening a semaphore     */
  17222. #define SVP_ERRSYS_REQSEM    110   /* Error requesting sm semaphore */
  17223. #define SVP_ERRSYS_RELSEM    111   /* Error releasing sm semaphore  */
  17224. #define SVP_ERRSYS_CREATESEM 112   /* Error creating sm semaphore   */
  17225. #define SVP_ERRSYS_GETXID    113   /* Error in side file lookup     */
  17226. #define SVP_ERRSYS_GETQUEUE  114   /* Error creating msg queue      */
  17227. #define SVP_ERRSYS_FREESEM   115   /* Error freeing semaphore       */
  17228. #define SVP_ERRSYS_FREEQUEUE 116   /* Error freeing queue           */
  17229. #define SVP_ERRSYS_WAITQUEUE 117   /* Error waiting on queue        */
  17230. #define SVP_ERRSYS_PEEKQUEUE 118   /* Error peeking queue           */
  17231. #define SVP_ERRSYS_OPENFAIL  119   /* Error opening file            */
  17232. #define SVP_ERRSYS_QEMPTY    120   /* Error queue is empty          */
  17233. #define SVP_ERRSYS_PURGEQUE  121   /* Error purging queue           */
  17234. #define SVP_ERRPRF_FNF       201   /* Profile not found             */
  17235. #define SVP_ERRPRF_SNF       202   /* Svopid not found              */
  17236. #define SVP_ERRPRF_INVF      203   /* Invalid file                  */
  17237. #define SVP_ERRPRF_IOERR     204   /* I/O Error                     */
  17238. #define SVP_ERRPRF_INVWC     205   /* Invalid wild card             */
  17239. #define SVP_ERRPRF_NOAUTH    206   /* Authorization failed          */
  17240. #define SVP_ARGERR_INVPCBX   301   /* Invalid PCB Index             */
  17241. #define SVP_ARGERR_INVSCBX   302   /* Invalid SCB Index             */
  17242. #define SVP_ARGERR_INVNAME   303   /* Invalid Variable name         */
  17243. #define SVP_ARGERR_NOLOCK    304   /* Lock not held on post-op      */
  17244. #define SVP_ARGERR_INVTOKEN  305   /* Invalid token on SVEVENT      */
  17245. #define SVP_ARGERR_INVPARENT 306   /* Parent not signed on          */
  17246.  
  17247.  
  17248. ΓòÉΓòÉΓòÉ 16.2.4.8. SVP Event Codes ΓòÉΓòÉΓòÉ
  17249.  
  17250. #define SVP_EVENT_OFFEREX     0x01     /* Offer extended           */
  17251. #define SVP_EVENT_OFFERAC     0x02     /* Offer accepted           */
  17252. #define SVP_EVENT_SMAVAIL     0x04     /* Shared Memory Available  */
  17253. #define SVP_EVENT_PRETRACT    0x08     /* Partner retracted        */
  17254. #define SVP_EVENT_PSETACV     0x10     /* Partner set ACV          */
  17255. #define SVP_EVENT_PSPEC       0x20     /* Partner specified        */
  17256. #define SVP_EVENT_PREF        0x40     /* Partner referenced       */
  17257. #define SVP_EVENT_FSPEC       0x80     /* Partner failed spec      */
  17258. #define SVP_EVENT_FREF        0x100    /* Partner failed ref       */
  17259. #define SVP_EVENT_SHUTDOWN    0x200    /* SVP shutdown             */
  17260. #define SVP_EVENT_PRELEASE    0x400    /* Partner released var     */
  17261.  
  17262.  
  17263. ΓòÉΓòÉΓòÉ 16.2.4.9. Function Prototypes ΓòÉΓòÉΓòÉ
  17264.  
  17265. int svpp(struct prb *);
  17266. int svps(struct srb *);
  17267. int svpe(struct wrb *);
  17268. void svsleep(unsigned long);
  17269. long aplobjsize(char, char, long);
  17270. char * GetEnvOpt(char *, int, char **);
  17271. #ifdef __OS2__
  17272. #define BeginThread(x,y,z) _beginthread(x,NULL,65536,y)
  17273. #else
  17274. long BeginThread(void (*fn)(void *), void *, unsigned long);
  17275. #endif
  17276. /* sv state    */
  17277. #define INITSTATE      0x03
  17278. #define PARTSPEC       0x05
  17279. #define USERSPEC       0x0A
  17280. /* sv coupling */
  17281. #define ISSHARED       0x02
  17282. #define ISOFFER        0x01
  17283. #define ISNTSHAR       0x00
  17284. /* sv acv      */
  17285. #define ACVMYSET       0x08
  17286. #define ACVPARTSET     0x04
  17287. #define ACVMYUSE       0x02
  17288. #define ACVPARTUSE     0x01
  17289.  
  17290.  
  17291. ΓòÉΓòÉΓòÉ 16.3. Common Data Representation ΓòÉΓòÉΓòÉ
  17292.  
  17293. Data passed from APL2 to an auxiliary processor, and data passed back to APL2, 
  17294. must be in a special format. If you pass invalid data to APL2, unpredictable 
  17295. errors may occur. 
  17296.  
  17297. Each APL2 object contains information that describes its data type, shape, 
  17298. size, and origin. This information is called its header, and is located at the 
  17299. beginning of the object. The header consists of the following fields (defined 
  17300. in C include file aplobj.h): 
  17301.  
  17302.    typedef struct aplobj {
  17303.      unsigned long  ptr      ;
  17304.      unsigned long  nb       ;
  17305.      unsigned long  nelm     ;
  17306.      unsigned char  type     ;
  17307.      unsigned char  rank     ;
  17308.      unsigned char  fill[2]  ;
  17309.      unsigned long  dim[1]   ;
  17310.    } APLOBJ ;
  17311.  
  17312. ptr     An identifier that indicates the system on which the object was built. 
  17313.         The valid values are indicated by a set of C #define's: 
  17314.  
  17315.                        #define CDRid6000 0x40400000
  17316.  
  17317.         indicates a 32-bit system without numeric byte reversal (AIX, Solaris). 
  17318.  
  17319.                       #define CDRidOS2  0x00002020
  17320.  
  17321.         indicates a 32-bit system with numeric byte reversal (OS/2). 
  17322.  
  17323.         Auxiliary processors should set the value of this field for objects 
  17324.         they create. The constant CDRID provides the correct value for the 
  17325.         running system. 
  17326.  
  17327.                         #ifdef __OS2__
  17328.                          #define CDRID CDRidOS2
  17329.                         #else
  17330.                          #define CDRID CDRid6000
  17331.                         #endif
  17332.  
  17333. nb      The number of bytes in this APL2 object. If the datatype of this object 
  17334.         is that of a nested array the byte count must include this object and 
  17335.         all of its subitems. The length of each object must be rounded to an 
  17336.         even multiple of 16. 
  17337.  
  17338. nelm    The number of elements in this APL2 object. 
  17339.  
  17340. type    APL2 object type: 
  17341.  
  17342.                    0   Boolean           (1 bit per item)
  17343.                    1   Integer           (4 bytes per item)
  17344.                    2   Real             (8 bytes per item)
  17345.                    3   Complex           (16 bytes per item)
  17346.                    4   ASCII Character       (1 byte per item)
  17347.                    5   Unicode Character      (4 bytes per item)
  17348.                    6   Integer Progression Vector  (8 bytes)
  17349.                    7   General array        (4 bytes per item)
  17350.  
  17351. rank    Rank of object  (0-63). 
  17352.  
  17353. fill    Unused; should be set to 0. 
  17354.  
  17355. dim[]   Length of each dimension  (number of elements in dim = rank) 
  17356.  
  17357. Immediately following the header for each object is the data associated with 
  17358. the object. The length of the data for each type is shown above. If the object 
  17359. has more than one dimension, its elements are stored in row order (as if the 
  17360. APL2 primitive Ravel had been applied to the variable). 
  17361.  
  17362. Immediately following the data are enough fill bytes to make the length of the 
  17363. object an even multiple of 16. 
  17364.  
  17365. o Special Notes for General Arrays 
  17366. o Byte Reversal 
  17367.  
  17368.  
  17369. ΓòÉΓòÉΓòÉ 16.3.1. Special Notes for General Arrays ΓòÉΓòÉΓòÉ
  17370.  
  17371.  1. General arrays (type 7) have a recursive structure. Their data section 
  17372.     consists of one 4-byte word per item, each containing the offset from the 
  17373.     beginning of the general object to the corresponding subitem. The subitems 
  17374.     (each of which can also be a general array) follow in left-list order. 
  17375.  
  17376.  2. General arrays that are empty (nelm=0) must have a prototype definition, so 
  17377.     their data section consists of a single 4-byte offset field, which is the 
  17378.     offset from the beginning of the general array to the beginning of the 
  17379.     object that contains the prototype. 
  17380.  
  17381.  
  17382. ΓòÉΓòÉΓòÉ 16.3.2. Byte Reversal ΓòÉΓòÉΓòÉ
  17383.  
  17384. On systems where numbers are stored in byte-reversed order, all numeric 4-byte 
  17385. header fields (nb, nelm, and dim) and all numeric data are expected to be 
  17386. stored in the object in byte-reversed order. However, note that Boolean data is 
  17387. stored as 1 bit per element, 8 bits per byte. It is not stored in byte-reversed 
  17388. order. 
  17389.  
  17390.  
  17391. ΓòÉΓòÉΓòÉ 17. SVP Trace Facility ΓòÉΓòÉΓòÉ
  17392.  
  17393. The APL2/2 SVP Trace window displays information about shared variable 
  17394. processor requests. It also includes dialogs which provide statistics of SVP 
  17395. usage, information about processors that are signed on to the SVP, and 
  17396. variables that are shared by those processors. The dialogs can also be used to 
  17397. control tracing selectively and to send shutdown or kill requests to 
  17398. processors. There is never more than one trace window active at a time, and it 
  17399. shows events for all processors on the system that are using the SVP. Menu 
  17400. items are also provided to start, stop, and issue commands to the APL2/2 port 
  17401. server (used for cooperative processing). 
  17402.  
  17403. Note:  You might want to start the SVP Trace window manually to avoid the 
  17404. overhead of SVP initialization when invoking APL2/2. If you have TCP/IP 
  17405. installed, the SVP Trace window must be started after TCP/IP is fully 
  17406. initialized. 
  17407.  
  17408. o Starting the SVP Trace Facility 
  17409. o Description 
  17410. o Menu Options 
  17411.  
  17412.  
  17413. ΓòÉΓòÉΓòÉ 17.1. Starting the SVP Trace Facility ΓòÉΓòÉΓòÉ
  17414.  
  17415. If the SVP Trace window is not active when an APL interpreter or processor 
  17416. attempts to sign on to the SVP, it is started automatically. In this case it 
  17417. also automatically shuts down when the last processor signs off. The SVP Trace 
  17418. window can also be started by clicking on the "APL2/2 SVP Trace" icon or by 
  17419. invoking apl2svp.exe from the OS/2 command line. 
  17420.  
  17421. The syntax is: 
  17422.  
  17423. aplsvp [optional parameters]
  17424.  
  17425. The following invocation options can be used: 
  17426.  
  17427. -trace [on|off|log|both] 
  17428.         Enables display and logging of trace events. 
  17429.  
  17430. -listen [on|off] 
  17431.         Listen on automatically starts the APL2/2 port server and TCP/IP 
  17432.         server. 
  17433.  
  17434. All of the options can be specified by environment variable settings. The 
  17435. environment variables correspond to the invocation options with the character 
  17436. "aplsvp" prefix. For example: 
  17437.  
  17438.     set APLSVPTRACE=on
  17439.  
  17440. is equivalent to starting aplsvp with the -trace on option. 
  17441.  
  17442.  
  17443. ΓòÉΓòÉΓòÉ 17.2. Description ΓòÉΓòÉΓòÉ
  17444.  
  17445. In most cases, SVP requests generate two trace messages; one on entry to the 
  17446. service and one on exit. If the exit return code is not 0, an additional 
  17447. message can be generated. During initialization the trace window displays the 
  17448. time and date that the SVP was started, and the amount of shared memory 
  17449. allocated for processor and variable control blocks. 
  17450.  
  17451. The trace window also, on request, logs the trace information. This log is 
  17452. always cleared when it is opened, so it shows trace information from only one 
  17453. instance of the trace window. 
  17454.  
  17455. When the SVP Trace window is closed, the size, position, current font, and 
  17456. background color are saved and used for the next invocation. To change the font 
  17457. of the trace messages, select a font from the OS/2 Font Palette and drop it on 
  17458. the SVP Trace window. To change the background color of the trace window, 
  17459. select a color from the OS/2 Color Palette and drop it on the window. The color 
  17460. of the messages cannot be changed. 
  17461.  
  17462. SVP trace messages are color coded as follows: 
  17463.  
  17464. Blue           SVP initialization 
  17465. Black          SVP trace 
  17466. Red            SVP error 
  17467. Green          APL2/2 port server 
  17468. Light Cyan     APL2/2 TCP/IP server 
  17469. Dark Cyan      Cross-system SVP trace messages 
  17470.  
  17471.  
  17472. ΓòÉΓòÉΓòÉ 17.3. Menu Options ΓòÉΓòÉΓòÉ
  17473.  
  17474. This section describes each of the menu options available on the SVP Trace 
  17475. window. 
  17476.  
  17477. o File 
  17478. o Options 
  17479. o Actions 
  17480. o Info 
  17481. o Help 
  17482.  
  17483.  
  17484. ΓòÉΓòÉΓòÉ 17.3.1. File ΓòÉΓòÉΓòÉ
  17485.  
  17486. The File menu contains choices to select a printer and print the SVP trace 
  17487. queue. It also contains a choice to shut down the SVP. 
  17488.  
  17489. Printer Setup  Presents a dialog to select the OS/2 printer queue to which 
  17490.                output should be sent. 
  17491.  
  17492. Print          Prints the contents of the SVP trace queue. 
  17493.  
  17494. Exit           Shuts down the SVP Trace window. 
  17495.  
  17496.                Note:  If the trace window is shut down while processors are 
  17497.                still signed on, the SVP continues to operate, but the trace 
  17498.                window cannot be restarted until all processors are signed off. 
  17499.  
  17500. A dialog is displayed if you attempt to shut down the SVP trace window while 
  17501. processors are still signed on. 
  17502.  
  17503. Select Yes, Shutdown to continue with the shutdown of the SVP trace window. 
  17504.  
  17505. Select No, Cancel to resume normal operation. 
  17506.  
  17507.  
  17508. ΓòÉΓòÉΓòÉ 17.3.2. Options ΓòÉΓòÉΓòÉ
  17509.  
  17510. The Options menu allows you to control the display of SVP trace messages. The 
  17511. following choices appear in the Options menu: 
  17512.  
  17513. Trace on       Toggle for displaying SVP trace entries in the trace window. 
  17514.  
  17515. Logging on     Toggle for writing SVP trace entries to a file. The default file 
  17516.                name is apl2svp.trc in the current directory. This can be 
  17517.                changed by setting environment variable APL2SVPLOG. 
  17518.  
  17519. Timestamp on   Toggle for including timestamps with SVP trace entries. 
  17520.  
  17521. Save Options   Saves currently selected options for next invocation. 
  17522.  
  17523.  
  17524. ΓòÉΓòÉΓòÉ 17.3.3. Actions ΓòÉΓòÉΓòÉ
  17525.  
  17526. The Actions menu contains choices that you use to affect the behavior of the 
  17527. Shared Variable Processor. The following choices appear in the Action menu: 
  17528.  
  17529. Cross System   Starts and stops the APL2/2 port server and APL2/2 TCP/IP 
  17530.                server. These programs must be started to use cooperative 
  17531.                processing with a remote system. 
  17532.  
  17533. Port Server    Issues the CLEAR or LIST commands to the APL2 port server. 
  17534.  
  17535. Purge Queue    Empties the SVP trace queue. This does not effect the log file, 
  17536.                if any. 
  17537.  
  17538. A dialog appears while starting the cross system programs. The Port Server is 
  17539. used to identify processors by their TCP/IP port number. You can select the 
  17540. TCP/IP port number that it uses for itself. (The default is 31415.) 
  17541.  
  17542.  
  17543. ΓòÉΓòÉΓòÉ 17.3.4. Info ΓòÉΓòÉΓòÉ
  17544.  
  17545. The Info menu contains choices that display information about processors using 
  17546. the SVP. 
  17547.  
  17548. o Statistics 
  17549. o Processors 
  17550.  
  17551.  
  17552. ΓòÉΓòÉΓòÉ 17.3.4.1. Statistics ΓòÉΓòÉΓòÉ
  17553.  
  17554. This dialog displays the following information: 
  17555.  
  17556. o Processors signed on 
  17557.  
  17558.   The total number of processors currently signed on to the SVP. 
  17559.  
  17560. o Variables in use 
  17561.  
  17562.   The total number of variables currently shared or offered. 
  17563.  
  17564. o Shared memory (bytes) 
  17565.  
  17566.   The total amount of memory used by shared variables for data. 
  17567.  
  17568.  
  17569. ΓòÉΓòÉΓòÉ 17.3.4.2. Processors ΓòÉΓòÉΓòÉ
  17570.  
  17571. This dialog displays a list of processors that are signed on to the SVP. 
  17572. Dependent processors have their parent processor and grandparent processor (if 
  17573. any) displayed in parentheses after the processor number. For example: 
  17574.  
  17575.   120 (1001)
  17576.  
  17577. This refers to processor 120, which is a child of processor 1001. 
  17578.  
  17579. If a processor is selected in the list, the following buttons are activated: 
  17580.  
  17581. Info      Displays information about the selected processor. 
  17582.  
  17583. Variables Displays a dialog listing the variables currently shared with, 
  17584.           offered to, or offered from the selected processor. 
  17585.  
  17586. Shutdown  Sends an SVP Shutdown signal to the selected processor. See SVP 
  17587.           Programming Interface for more information. 
  17588.  
  17589. Kill      Removes all information about the processor from the SVP and sends a 
  17590.           kill signal to the process associated with the selected processor. 
  17591.           This should only be attempted as a last resort. The SVP is not always 
  17592.           able to clean up properly after an auxiliary processor has been 
  17593.           killed. 
  17594.  
  17595. Selecting Done ends the dialog. 
  17596.  
  17597.  
  17598. ΓòÉΓòÉΓòÉ 17.3.5. Help ΓòÉΓòÉΓòÉ
  17599.  
  17600. This menu contains the standard help choices: 
  17601.  
  17602. o Help Index 
  17603. o General Help 
  17604. o Using Help 
  17605. o Keys Help 
  17606. o Product Information 
  17607.  
  17608.  
  17609. ΓòÉΓòÉΓòÉ 18. APL2/2 Presentation Manager Services ΓòÉΓòÉΓòÉ
  17610.  
  17611. In addition to the services provided by AP 145, APL2/2 includes a library of C 
  17612. services that are helpful when writing more complicated Presentation Manager 
  17613. programs. This chapter describes the programming interfaces for these services. 
  17614.  
  17615. The services support various types of operations: 
  17616.  
  17617. o The AplExec service allows an application to execute OS/2 commands and 
  17618.   control the window within which the command is executed. 
  17619.  
  17620. o The keyboard handler supports APL input through Presentation Manager windows 
  17621.   and dialog controls. 
  17622.  
  17623. o Print objects support integrating APL2's printing facilities with 
  17624.   Presentation Manager applications. 
  17625.  
  17626. o The window byte services support associating storage with Presentation 
  17627.   Manager windows. 
  17628.  
  17629. The APL2 Presentation Manager services are generally only used directly by 
  17630. experienced Presentation Manager programmers. It is recommended that users 
  17631. familiarize themselves with Presentation Manager programming concepts before 
  17632. attempting to use these services directly. 
  17633.  
  17634. Higher level APL2 cover functions for executing OS/2 commands and using the 
  17635. print services are provided in the PMTOOLS workspace. 
  17636.  
  17637. The APL2 Presentation Manager services reside in a dynamic link library (DLL) 
  17638. called aplpm.dll. 
  17639.  
  17640. o Using Presentation Manager Services from APL2 
  17641. o Using Presentation Manager Services from C 
  17642. o Executing OS/2 Commands 
  17643. o Keyboard Handler 
  17644. o Print Objects 
  17645. o Window Bytes 
  17646.  
  17647.  
  17648. ΓòÉΓòÉΓòÉ 18.1. Using Presentation Manager Services from APL2 ΓòÉΓòÉΓòÉ
  17649.  
  17650. In order to access APL Presentation Manager services directly from APL2, the 
  17651. aplpm.dll file must be loaded and then the service to be used must be located 
  17652. within the loaded DLL. When an application finishes using the services, the DLL 
  17653. file should be freed. AP 145 is used to call the OS/2 services required to 
  17654. perform these operations. The following OS/2 Control Program services are used: 
  17655.  
  17656. DosLoadModule         To load aplpm.dll 
  17657.  
  17658. DosQueryProcAddr      To locate the service within the dll 
  17659.  
  17660. DosFreeModule         To free aplpm.dll 
  17661.  
  17662. The PMTOOLS workspace contains cover functions for executing OS/2 commands and 
  17663. building print jobs. The workspace also contains utility functions that use the 
  17664. keyboard handler. 
  17665.  
  17666. The PMWIN workspace contains variables with names that correspond to the 
  17667. messages and flags used by the AplPm services. 
  17668.  
  17669.  
  17670. ΓòÉΓòÉΓòÉ 18.2. Using Presentation Manager Services from C ΓòÉΓòÉΓòÉ
  17671.  
  17672. The aplpm.h header file contains prototypes for the functions and procedures in 
  17673. aplpm.dll. The header file also includes defined constants for the messages and 
  17674. flags used by the services. 
  17675.  
  17676. The aplpm.lib should be used to resolve references to services in the aplpm.dll 
  17677. file when link-editing C applications. The aplpm.dll services should not be 
  17678. statically linked with applications. 
  17679.  
  17680.  
  17681. ΓòÉΓòÉΓòÉ 18.3. Executing OS/2 Commands ΓòÉΓòÉΓòÉ
  17682.  
  17683. AplExec is a C function used to execute OS/2 commands. 
  17684.  
  17685. Each command is executed in a new OS/2 session that inherits the caller's 
  17686. environment and file handles. The session can occur in a visible or invisible 
  17687. window and the session can be automatically terminated or left active when the 
  17688. command completes. The session can be cancelled by posting a semaphore. 
  17689.  
  17690. o Arguments 
  17691. o Return Codes 
  17692. o APL2 Syntax 
  17693. o C Syntax 
  17694.  
  17695.  
  17696. ΓòÉΓòÉΓòÉ 18.3.1. Arguments ΓòÉΓòÉΓòÉ
  17697.  
  17698. PSZ Command       Command to execute 
  17699.  
  17700. PULONG CmdRc      Address of ULONG to receive command's return code 
  17701.  
  17702. BOOL Visible      Controls whether the window in which the command is executed 
  17703.                   is visible 
  17704.  
  17705. BOOL Leave        Controls whether the window in which the command is executed 
  17706.                   is left open after the command completes 
  17707.  
  17708. HEV HevCancel     Shared event semaphore handle. If this semaphore is posted, 
  17709.                   the command is cancelled. 
  17710.  
  17711.  
  17712. ΓòÉΓòÉΓòÉ 18.3.2. Return Codes ΓòÉΓòÉΓòÉ
  17713.  
  17714. AplExec issues the following return codes. The return code of the executed 
  17715. command is placed in the CmdRc argument. 
  17716.  
  17717. 0   Success 
  17718. 1   Command cancelled 
  17719. 2   OS/2 service error 
  17720.  
  17721.  
  17722. ΓòÉΓòÉΓòÉ 18.3.3. APL2 Syntax ΓòÉΓòÉΓòÉ
  17723.  
  17724. The AP 145 service AplExecPgm supplies an event semaphore for AplExec. The 
  17725. command is cancelled if the shared variable is retracted before the command 
  17726. completes. For example: 
  17727.  
  17728.       )LOAD 2 PMTOOLS
  17729.       APLEXECPGM 'APL2'
  17730. 0
  17731.       145 SHARE 'SV145'
  17732. 2
  17733.       VISIBLEΓò£0
  17734.       LEAVEΓò£0
  17735.       SV145Γò£'AplExecPgm' 'APL2' 0 VISIBLE LEAVE
  17736.       SV145
  17737.  0 0   AplExec APL2 0 0 0
  17738.  
  17739.  
  17740. ΓòÉΓòÉΓòÉ 18.3.4. C Syntax ΓòÉΓòÉΓòÉ
  17741.  
  17742. #include "aplpm.h"
  17743. ULONG ExecRc ;
  17744. PSZ   Command ;
  17745. ULONG CmdRc ;
  17746. BOOL  Visible ;
  17747. BOOL  Leave ;
  17748. HEV   HevCancel ;
  17749. Command = "APL2" ;
  17750. Visible = FALSE ;
  17751. Leave   = FALSE ;
  17752. DosCreateEventSem(NULL,&HevCancel,DC_SEM_SHARED,FALSE) ;
  17753. ExecRc = AplExec(Command,&CmdRc,Visible,Leave,HevCancel) ;
  17754. DosCloseEventSem(HevCancel) ;
  17755.  
  17756.  
  17757. ΓòÉΓòÉΓòÉ 18.4. Keyboard Handler ΓòÉΓòÉΓòÉ
  17758.  
  17759. The keyboard handler is used to provide APL keyboard support for Presentation 
  17760. Manager windows. The AplKey service is a window procedure that is used to 
  17761. subclass an input window. The procedure processes WM_CHAR messages generated by 
  17762. the keyboard and translates them to the characters indicated by the user's 
  17763. selected keyboard layout. 
  17764.  
  17765. All applications that are currently using the keyboard handler share the same 
  17766. keyboard layout. 
  17767.  
  17768. o Enabling Keyboard Handler 
  17769. o Return Codes 
  17770. o C Syntax 
  17771. o Online Help 
  17772.  
  17773.  
  17774. ΓòÉΓòÉΓòÉ 18.4.1. Enabling Keyboard Handler ΓòÉΓòÉΓòÉ
  17775.  
  17776. The parameters for all APLKEY_MSG messages are reserved and should be 0. 
  17777.  
  17778. The keyboard handler supports the following messages: 
  17779.  
  17780. APLKEY_MSG_INIT         Initializes the keyboard handler. 
  17781. APLKEY_MSG_SELECT       Opens the keyboard layout selection window. 
  17782. APLKEY_MSG_MODIFY       Opens the keyboard layout modification window. 
  17783. APLKEY_MSG_TERM         Terminates the keyboard handler. 
  17784.  
  17785. To enable APL keyboard support for a window: 
  17786.  
  17787.  1. Subclass the window with the AplKey service. 
  17788.  2. Send the window an APLKEY_MSG_INIT message 
  17789.  3. Enable the window. 
  17790.  
  17791. To disable APL keyboard support for a window: 
  17792.  
  17793.  1. Send the window an APLKEY_MSG_TERM message 
  17794.  2. Unsubclass the window. 
  17795.  
  17796. To temporarily disable APL keyboard support for a window, (perhaps to enable 
  17797. access to the current codepage's definition of the keyboard), your application 
  17798. can unsubclass the window. However, your application must resubclass the window 
  17799. and send the APLKEY_MSG_TERM message before destroying the window. 
  17800.  
  17801. Note:  If you also need to subclass your window with your own window procedure, 
  17802.        you must either subclass the window with the AplKey procedure first or 
  17803.        use the APL window bytes services to place the address of the next 
  17804.        window procedure at offset APLKEY_BYTES_OFFSET in the window's bytes. 
  17805.        Unpredictable results occur otherwise. 
  17806.  
  17807.  
  17808. ΓòÉΓòÉΓòÉ 18.4.2. Return Codes ΓòÉΓòÉΓòÉ
  17809.  
  17810. The keyboard handler returns 0 for all successfully processed APLKEY_MSG 
  17811. messages. If an error occurs, 1 is returned 
  17812.  
  17813.  
  17814. ΓòÉΓòÉΓòÉ 18.4.3. C Syntax ΓòÉΓòÉΓòÉ
  17815.  
  17816. #include "aplpm.h"
  17817. AplAllocWindowBytes(Hwnd,APLKEY_BYTES_LENGTH) ;
  17818. AplSetWindowPtr(Hwnd,APLKEY_BYTES_OFFSET,
  17819.    (PVOID)WinSubclassWindow(Hwnd,AplKey)) ;
  17820. WinSendMsg(Hwnd,APLKEY_MSG_INIT,NULL,NULL) ;
  17821. /* Process application here */
  17822. WinSendMsg(Hwnd,APLKEY_MSG_TERM,NULL,NULL) ;
  17823. WinSubclassWindow(Hwnd,
  17824.    (PFNWP)AplQueryWindowPtr(Hwnd,APLKEY_BYTES_OFFSET)) ;
  17825. AplFreeWindowBytes(Hwnd) ;
  17826.  
  17827.  
  17828. ΓòÉΓòÉΓòÉ 18.4.4. Online Help ΓòÉΓòÉΓòÉ
  17829.  
  17830. The keyboard handler's windows include their own online help. Applications do 
  17831. not need to perform any processing to enable this help. However, the help file 
  17832. must be available. It is called aplkey.hlp and should either be in the current 
  17833. directory or a directory listed in the HELP environment variable. 
  17834.  
  17835.  
  17836. ΓòÉΓòÉΓòÉ 18.5. Print Objects ΓòÉΓòÉΓòÉ
  17837.  
  17838. The print facilities are implemented as an object window procedure. An 
  17839. application creates a print object and then sends messages to the object to 
  17840. build documents for printing. The AplPrintObject procedure processes messages 
  17841. for print objects. 
  17842.  
  17843. Print objects support a set of high-level functions that are printer 
  17844. independent. 
  17845.  
  17846. o Messages 
  17847. o Fonts and Colors 
  17848. o Return Codes 
  17849. o APL2 Syntax 
  17850. o C Syntax 
  17851. o Online Help 
  17852.  
  17853.  
  17854. ΓòÉΓòÉΓòÉ 18.5.1. Messages ΓòÉΓòÉΓòÉ
  17855.  
  17856. Unless otherwise specified, all parameters for APLPRT messages are reserved and 
  17857. should be NULL. 
  17858.  
  17859. Print objects process the following messages: 
  17860.  
  17861. APLPRT_SELECT_PRINTER 
  17862.           Display a print queue selection dialog. 
  17863.  
  17864.           If this message has not been sent before a document has been opened, 
  17865.           the user's default print queue is used. 
  17866.  
  17867. APLPRT_OPEN_DOCUMENT 
  17868.           Open a print document. 
  17869.  
  17870.           This message starts a new document on the selected print queue. 
  17871.           Running headings and footings are reset to null. All font settings 
  17872.           are reset to 10 point Courier. Word break and indentation are turned 
  17873.           off. The page number and margin width are reset to zero. 
  17874.  
  17875.           The message uses two parameters. If the first parameter is nonzero, 
  17876.           it is the address of a null terminated string that is used as the 
  17877.           title of the print job. 
  17878.  
  17879.           The second parameter is two unsigned short integers. The first 
  17880.           integer controls whether the document is printed duplex or not; 0 
  17881.           indicates duplex is off; 1 indicates duplex is on. Duplex controls 
  17882.           the use of margins and the placement of running headings and 
  17883.           footings. The second integer controls whether a cancel print window 
  17884.           is displayed. If it is 0, a cancel window is displayed. If it is 
  17885.           other than zero, a cancel window is not displayed. 
  17886.  
  17887.           The cancel window stays visible until the document is closed, 
  17888.           cancelled, or the user pushes the cancel button. If the user pushes 
  17889.           the cancel button, the printer object cancels the document and send 
  17890.           it's owner a WM_CONTROL message with the APLPRT_PRINT_CANCELLED code. 
  17891.           Subsequent attempts to add information to the document result in 1 
  17892.           return codes. 
  17893.  
  17894.           To maintain the responsiveness of the system, C applications should 
  17895.           send APLPRT_PRINT_SENTENCE messages from a secondary thread. 
  17896.  
  17897. APLPRT_PRINT_SENTENCE 
  17898.           Append a sentence to the document. 
  17899.  
  17900.           The message requires two parameters. The first parameter is the 
  17901.           address of a null terminated string. 
  17902.  
  17903.           The second parameter is two Boolean shorts. 
  17904.  
  17905.           The first short controls whether long lines are truncated or wrapped. 
  17906.           If it is 1, lines are wrapped. 
  17907.  
  17908.           The second short controls whether the text is printed monospaced or 
  17909.           proportionally. If it is 1, text is printed monospaced. 
  17910.  
  17911.           A new page is started if necessary to print the sentence or any 
  17912.           wrapped portion of the sentence. 
  17913.  
  17914.           If indenting is on, the sentence and any wrapped portions of the 
  17915.           sentence are indented by the current indentation amount. 
  17916.  
  17917.           The page number, heading, and footing are added to the page if they 
  17918.           have not already been added and if they are enabled. 
  17919.  
  17920. APLPRT_NEWLINE 
  17921.           Start a new line. 
  17922.  
  17923.           The page number, heading, and footing are added to the page if they 
  17924.           have not already been added and if they are enabled. 
  17925.  
  17926.           A new page is started if necessary. 
  17927.  
  17928. APLPRT_NEWPAGE 
  17929.           Conditionally start a new page. 
  17930.  
  17931.           This message allows an application to either start a new page or 
  17932.           conditionally start a new page depending on how much space is left at 
  17933.           the bottom of the current page. 
  17934.  
  17935.           If the first parameter is zero, a new page is started. 
  17936.  
  17937.           If the first parameter is not zero, it specifies a number of points. 
  17938.           The print object calculates the number of vertical points between the 
  17939.           bottom of the last text in the body of the page and the bottom of the 
  17940.           page. If the number of points specified in the parameter is greater 
  17941.           than or equal to the number of points left on the page, a new page is 
  17942.           started. 
  17943.  
  17944.           Before calculating the amount of space left on the page, the print 
  17945.           object adds the page number, heading, and footing if they have not 
  17946.           already been added and if they are enabled. 
  17947.  
  17948.           There are 72 points per inch. There are approximately 3.5 points per 
  17949.           millimeter. 
  17950.  
  17951. APLPRT_CLOSE_DOCUMENT 
  17952.           Close the document 
  17953.  
  17954.           The document is sent to the print queue. 
  17955.  
  17956. APLPRT_CANCEL_DOCUMENT 
  17957.           Close the document 
  17958.  
  17959.           The document is discarded. 
  17960.  
  17961. APLPRT_SET_MARGIN 
  17962.           Enable or disable an inside margin. 
  17963.  
  17964.           The first parameter is reserved and must be zero. The second 
  17965.           parameter is the width of the inside margin. The margin is only used 
  17966.           if duplex is on. The margin width is specified in points. 
  17967.  
  17968.           There are 72 points per inch. There are approximately 3.5 points per 
  17969.           millimeter. 
  17970.  
  17971. APLPRT_SET_INDENT 
  17972.           Enable or disable indentation. 
  17973.  
  17974.           The first parameter is the indentation amount in points. Subsequently 
  17975.           printed sentences are indented by the specified amount. 
  17976.  
  17977.           There are 72 points per inch. There are approximately 3.5 points per 
  17978.           millimeter. 
  17979.  
  17980.           APLPRT_QUERY_LENGTH  can be used to determine the length of a 
  17981.           character string. 
  17982.  
  17983. APLPRT_SET_WORDBREAK 
  17984.           Enable or disable word breaks. 
  17985.  
  17986.           The first parameter is a Boolean short. If it is 1 and wrapping is 
  17987.           enabled, lines are wrapped at blank delimited words. 
  17988.  
  17989. APLPRT_SET_LINESPACE 
  17990.           Enable or disable interline spacing. 
  17991.  
  17992.           A print object's default behavior is to insert 2 points of blank 
  17993.           space between lines.  In general this improves readability of text. 
  17994.           However, this interline spacing can interfere with applications that 
  17995.           use box drawing characters. This message can be used to disable, or 
  17996.           enable, the insertion of interline spaces. 
  17997.  
  17998.           The first parameter is a Boolean short. If it is 0 spacing is 
  17999.           disabled. If it is 1 spacing is enabled. 
  18000.  
  18001. APLPRT_SET_HEADING 
  18002.           Set the text of the running heading. 
  18003.  
  18004.           The first parameter is a character string to be used as the running 
  18005.           heading. If the parameter is 0 or a null string, headings are 
  18006.           disabled. 
  18007.  
  18008.           The maximum length of a running heading is 60 characters. 
  18009.  
  18010. APLPRT_SET_FOOTING 
  18011.           Set the text of the running footing. 
  18012.  
  18013.           The first parameter is a character string to be used as the running 
  18014.           footing. If the parameter is 0 or a null string, footings are 
  18015.           disabled. 
  18016.  
  18017.           The maximum length of a running footing is 60 characters. 
  18018.  
  18019. APLPRT_SET_PAGENUMBERS 
  18020.           Enable or disable page numbering. 
  18021.  
  18022.           The first parameter is a Boolean short. If it is 1 a page number is 
  18023.           placed on each page. If it is 0 page numbering is suppressed. 
  18024.  
  18025. APLPRT_QUERY_PAGENUMBER 
  18026.           Query the current page number. 
  18027.  
  18028.           This message returns the current page number. 
  18029.  
  18030. APLPRT_QUERY_LENGTH 
  18031.           Query the length of a string. 
  18032.  
  18033.           This message returns the length of a string in points. The font 
  18034.           specified with APLPRT_FONT_BODY is used to calculate the string 
  18035.           length. 
  18036.  
  18037.           The first parameter is a character string whose length is to be 
  18038.           determined. The maximum number of characters in the string is 256 
  18039.           characters. 
  18040.  
  18041.           If an error occurs, 0 is returned. 
  18042.  
  18043. Running headings, footings, and page numbers are added to a page of a document 
  18044. when the first sentence or new line is added to the page. Once a heading, 
  18045. footing, or page numbers has been added, changes to the headings and footings 
  18046. and enabling or disabling page numbering do not take effect until the next page 
  18047. is started. 
  18048.  
  18049.  
  18050. ΓòÉΓòÉΓòÉ 18.5.2. Fonts and Colors ΓòÉΓòÉΓòÉ
  18051.  
  18052. Print objects support two messages for setting the font and color to be used in 
  18053. a document: APLPRT_SET_FONT and APLPRT_SET_COLOR. When either setting is 
  18054. changed, the new value is used for subsequent text until the setting is 
  18055. changed. 
  18056.  
  18057. APLPRT_SET_COLOR 
  18058.           Set the color to use for text in the body of the document. 
  18059.  
  18060.           This message requires one parameter. The parameter is an RGB color. 
  18061.           If the parameter is 0 the color is reset to the default which is 
  18062.           black. 
  18063.  
  18064.           Running headings, footings, and page numbers are always printed in 
  18065.           black. 
  18066.  
  18067. APLPRT_SET_FONT 
  18068.           Set the font to use for a part of the document. 
  18069.  
  18070.           This message requires two parameters. The first parameter specifies 
  18071.           the part of the document for which to set the font. It can have the 
  18072.           following values: 
  18073.  
  18074.    APLPRT_FONT_BODY 
  18075.              Use the font for text in the body of the document. 
  18076.  
  18077.    APLPRT_FONT_PAGENUMBERS 
  18078.              Use the font for the page numbers. 
  18079.  
  18080.    APLPRT_FONT_HEADINGS 
  18081.              Use the font for running headings. 
  18082.  
  18083.    APLPRT_FONT_FOOTINGS 
  18084.              Use the font for running footings. 
  18085.  
  18086.           The second parameter is a character string specifying the point size 
  18087.           and font. For example: '10.Helvetica'. If the parameter is 0 or a 
  18088.           null string, the font is reset to the default. The default font is 10 
  18089.           point Courier. 
  18090.  
  18091.           When you set a font, the printer object looks for a scalable font 
  18092.           with the specified facename. If no scalable font is found, the 
  18093.           printer object looks for a bitmap font with the specified facename, 
  18094.           pointsize, and that is designed for the selected printer's 
  18095.           resolution. If no suitable font is found, the font is reset to 10 
  18096.           point Courier. 
  18097.  
  18098.           The following scalable fonts are supplied with OS/2: 
  18099.  
  18100.    o Times New Roman 
  18101.    o Times New Roman Bold 
  18102.    o Times New Roman Bold Italic 
  18103.    o Times New Roman Italic 
  18104.    o Helvetica 
  18105.    o Helvetica Bold 
  18106.    o Helvetica Bold Italic 
  18107.    o Helvetica Italic 
  18108.    o Courier 
  18109.    o Courier Bold 
  18110.    o Courier Bold Italic 
  18111.    o Courier Italic 
  18112.    o Symbol Set 
  18113.  
  18114.           The following scalable fonts are supplied with APL2/2: 
  18115.  
  18116.    o Courier APL2 
  18117.    o Courier APL2 Bold 
  18118.    o APL2 
  18119.    o APL2 Italic 
  18120.  
  18121. APLPRT_SET_FONT issues the following return codes: 
  18122.  
  18123. 0   Success. The font is changed. 
  18124.  
  18125. 1   Font not found. The font is reset to the default and the document is left 
  18126.     open. 
  18127.  
  18128. 2   OS/2 service error. The document is cancelled. 
  18129.  
  18130. 3   Invalid font name. The font is not changed and the document is left open. 
  18131.  
  18132. Note:  APLPRT_NEWLINE messages increment the line by the size of the current 
  18133.        font. Therefore, in order to ensure that the current write point is 
  18134.        moved down the correct amount, change to the new font before sending a 
  18135.        newline message. 
  18136.  
  18137.  
  18138. ΓòÉΓòÉΓòÉ 18.5.3. Return Codes ΓòÉΓòÉΓòÉ
  18139.  
  18140. Print objects return 0 for all successfully processed APLPRT messages except 
  18141. APLPRT_QUERY_PAGENUMBER and APLPRT_QUERY_LENGTH. 1 is returned if an error 
  18142. occurs. 
  18143.  
  18144.  
  18145. ΓòÉΓòÉΓòÉ 18.5.4. APL2 Syntax ΓòÉΓòÉΓòÉ
  18146.  
  18147. The PMTOOLS workspace contains functions that correspond to each of the 
  18148. messages that print objects use. In addition, it contains functions to create 
  18149. and destroy print objects. 
  18150.  
  18151. If the user has cancelled the print job, SET_FONT and PRINT_SENTENCE return a 
  18152. 1. 
  18153.  
  18154.       )LOAD 2 PMTOOLS
  18155.       CREATE_PRINTER
  18156.       SELECT_PRINTER
  18157.       OPEN_DOCUMENT 'Job Title'
  18158.       SET_FONT '10.Tms Rmn'
  18159. 0
  18160.       PRINT_SENTENCE 'This is a sample sentence.'
  18161. 0
  18162.       CLOSE_DOCUMENT
  18163.       DESTROY_PRINTER
  18164.  
  18165.  
  18166. ΓòÉΓòÉΓòÉ 18.5.5. C Syntax ΓòÉΓòÉΓòÉ
  18167.  
  18168. In C you must register the print object class before you can create a print 
  18169. object. The class must have at least APLPRT_RESERVED bytes of bytes allocated 
  18170. for it. 
  18171.  
  18172. Since print object windows do not display, use HWND_OBJECT as the parent. 
  18173.  
  18174. If your application should receive a message when the user cancels printing, 
  18175. specify an application window as the print object's owner. The print object 
  18176. also notifies your applications of cancellations using message return codes. 
  18177.  
  18178. If your application should not receive a message when the user cancels 
  18179. printing, specify HWND_DESKTOP as the owner. 
  18180.  
  18181. #include "aplpm.h"
  18182. CHAR  * ClassName  ;
  18183. PFNWP   ClassPfnwp ;
  18184. ULONG   ClassStyle ;
  18185. ULONG   ClassWords ;
  18186. HWND    Printer   ;
  18187. HWND    Parent    ;
  18188. PSZ     Text      ;
  18189. ULONG   Style     ;
  18190. LONG    XCoord    ;
  18191. LONG    YCoord    ;
  18192. LONG    Width     ;
  18193. LONG    Height    ;
  18194. HWND    Owner     ;
  18195. HWND    Behind    ;
  18196. ULONG   ID        ;
  18197. PVOID   BarData   ;
  18198. PVOID   PresParam ;
  18199. PSZ     FontSizeName ;
  18200. BOOL    Wrap      ;
  18201. BOOL    Fixed     ;
  18202. ClassName       = (PSZ)APLPRT_CLASS ;
  18203. ClassPfnwp      = AplPrintObject ;
  18204. ClassStyle      = CS_SIZEREDRAW | CS_CLIPCHILDREN ;
  18205. ClassWords      = APLPRT_RESERVED ;
  18206. WinRegisterClass(Hab,ClassName,ClassPfnwp,ClassStyle,ClassWords) ;
  18207. Parent    = HWND_OBJECT ;
  18208. ClassName = (PSZ)APLPRT_CLASS ;
  18209. Text      = "" ;
  18210. Style     = 0 ;
  18211. XCoord    = 0 ;
  18212. YCoord    = 0 ;
  18213. Width     = 0 ;
  18214. Height    = 0 ;
  18215. Owner     = HWND_DESKTOP ;
  18216. Behind    = HWND_TOP ;
  18217. ID        = 0 ;
  18218. BarData   = NULL ;
  18219. PresParam = NULL ;
  18220. Printer = WinCreateWindow(Parent,ClassName,Text,Style,
  18221.    XCoord,YCoord,Width,Height,Owner,Behind,ID,BarData,PresParam) ;
  18222. WinSendMsg(Printer,APLPRT_SELECT_PRINTER,0,0) ;
  18223. WinSendMsg(Printer,APLPRT_OPEN_DOCUMENT,MPFROMP("Job Title"),NULL) ;
  18224. FontSizeName = "10.Helvetica" ;
  18225. WinSendMsg(Printer,APLPRT_SET_FONT,
  18226.    MPFROM1SHORT(APLPRT_FONT_BODY),
  18227.    MPFROMP(FontSizeName)) ;
  18228. Wrap  = TRUE ;
  18229. Fixed = FALSE ;
  18230. WinSendMsg(Printer,APLPRT_PRINT_SENTENCE,
  18231.    MPFROMP("This is a sample sentence."),
  18232.    MPFROM2SHORT(Wrap,Fixed)) ;
  18233. WinSendMsg(Printer,APLPRT_CLOSE_DOCUMENT,0,0) ;
  18234. WinDestroyWindow(Printer) ;
  18235.  
  18236.  
  18237. ΓòÉΓòÉΓòÉ 18.5.6. Online Help ΓòÉΓòÉΓòÉ
  18238.  
  18239. Print object windows include their own online help. Application do not need to 
  18240. perform any processing to enable this help. However, the help file must be 
  18241. available.  It is called aplprint.hlp and should either be in the current 
  18242. directory or a directory listed in the HELP environment variable. 
  18243.  
  18244.  
  18245. ΓòÉΓòÉΓòÉ 18.6. Window Bytes ΓòÉΓòÉΓòÉ
  18246.  
  18247. The window bytes services let you allocate and associate storage with a window 
  18248. handle. Unlike storage allocated by Presentation Manager during window 
  18249. creation, Apl window bytes can be allocated at any time after the window has 
  18250. been created. This is useful for those cases where the amount of storage is not 
  18251. known at the time the class is registered and when the storage at offset 
  18252. QWL_USER must be reserved for other programs. 
  18253.  
  18254. Window bytes should be freed before the window is destroyed. 
  18255.  
  18256. o AplAllocWindowBytes 
  18257. o AplSetWindowPtr 
  18258. o AplQueryWindowPtr 
  18259. o AplFreeWindowBytes 
  18260. o Return Codes 
  18261. o C Syntax 
  18262.  
  18263.  
  18264. ΓòÉΓòÉΓòÉ 18.6.1. AplAllocWindowBytes ΓòÉΓòÉΓòÉ
  18265.  
  18266. Parameters: 
  18267.  
  18268. HWND      The handle of the window to allocate bytes for 
  18269.  
  18270. ULONG     The number of bytes to allocate 
  18271.  
  18272. If the window already has bytes allocated for it, 0 is returned. 
  18273.  
  18274.  
  18275. ΓòÉΓòÉΓòÉ 18.6.2. AplSetWindowPtr ΓòÉΓòÉΓòÉ
  18276.  
  18277. Parameters: 
  18278.  
  18279. HWND      The handle of the window in whose bytes to write 
  18280.  
  18281. ULONG     The offset into the window's bytes to write the pointer 
  18282.  
  18283. PVOID     A pointer to write into the window's bytes 
  18284.  
  18285. If the window does not have bytes allocated, 0 is returned. 
  18286.  
  18287.  
  18288. ΓòÉΓòÉΓòÉ 18.6.3. AplQueryWindowPtr ΓòÉΓòÉΓòÉ
  18289.  
  18290. Parameters: 
  18291.  
  18292. HWND      The handle of the window whose bytes to query 
  18293.  
  18294. ULONG     The offset into the window's bytes from which to retrieve the 
  18295.           pointer. 
  18296.  
  18297. The result is the pointer stored at the offset in the window's bytes 
  18298.  
  18299.  
  18300. ΓòÉΓòÉΓòÉ 18.6.4. AplFreeWindowBytes ΓòÉΓòÉΓòÉ
  18301.  
  18302. Parameters: 
  18303.  
  18304. HWND      The handle of the window whose bytes to free 
  18305.  
  18306. If the window does not have bytes allocated, 0 is returned. 
  18307.  
  18308.  
  18309. ΓòÉΓòÉΓòÉ 18.6.5. Return Codes ΓòÉΓòÉΓòÉ
  18310.  
  18311. Window byte services return 1 if successful, 0 otherwise. 
  18312.  
  18313.  
  18314. ΓòÉΓòÉΓòÉ 18.6.6. C Syntax ΓòÉΓòÉΓòÉ
  18315.  
  18316. #include "aplpm.h"
  18317. ULONG Length ;
  18318. ULONG Offset ;
  18319. PVOID Pvoid ;
  18320. Length = 4 ;
  18321. AplAllocWindowBytes(Hwnd,Length) ;
  18322. Offset = 0 ;
  18323. Pvoid = 37 ;
  18324. AplSetWindowPtr(Hwnd,Offset,Pvoid) ;
  18325. Offset = 0 ;
  18326. Pvoid = AplQueryWindowPtr(Hwnd,Offset)) ;
  18327. AplFreeWindowBytes(Hwnd) ;
  18328.  
  18329.  
  18330. ΓòÉΓòÉΓòÉ 19. Implementation Limits ΓòÉΓòÉΓòÉ
  18331.  
  18332. The APL2 interpreter has the following implementation limits. See Limitations 
  18333. by System. 
  18334.  
  18335.  
  18336. ΓòÉΓòÉΓòÉ 19.1. Limitations by System - Part 1 ΓòÉΓòÉΓòÉ
  18337.  
  18338.  
  18339. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18340.  
  18341. Limitation 
  18342.  
  18343.  
  18344. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18345.  
  18346. Workstations (excluding APL2/PC) 
  18347.  
  18348.  
  18349. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18350.  
  18351. APL2/370 
  18352.  
  18353.  
  18354. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18355.  
  18356. Largest and smallest representable numbers in an array 
  18357.  
  18358.  
  18359. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18360.  
  18361. 1.7976931348E308 ┬ñ1.7976931348E308 
  18362.  
  18363.  
  18364. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18365.  
  18366. 7.2370055773E75 ┬ñ7.2370055773E75 
  18367.  
  18368.  
  18369. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18370.  
  18371. Most infinitesimal (near 0) representable numbers in an array 
  18372.  
  18373.  
  18374. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18375.  
  18376. 2.2250738585E┬ñ308 ┬ñ2.2250738585E┬ñ308 
  18377.  
  18378.  
  18379. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18380.  
  18381. 5.397605346934E┬ñ79 ┬ñ5.397605346934E┬ñ79 
  18382.  
  18383.  
  18384. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18385.  
  18386. Maximum rank of an array 
  18387.  
  18388.  
  18389. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18390.  
  18391. 63 
  18392.  
  18393.  
  18394. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18395.  
  18396. 64 
  18397.  
  18398.  
  18399. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18400.  
  18401. Maximum length of any axis in an array 
  18402.  
  18403.  
  18404. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18405.  
  18406. ┬ñ1+2*31 (2147483647) 
  18407.  
  18408.  
  18409. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18410.  
  18411. ┬ñ1+2*31 (2147483647) 
  18412.  
  18413.  
  18414. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18415.  
  18416. Maximum product of all dimensions in an array 
  18417.  
  18418.  
  18419. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18420.  
  18421. ┬ñ1+2*31 (2147483647) 
  18422.  
  18423.  
  18424. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18425.  
  18426. ┬ñ1+2*31 (2147483647) 
  18427.  
  18428.  
  18429. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18430.  
  18431. Maximum depth of an array applied with the primitive functions depth (ΓòºR) and 
  18432. match (LΓòºR) 
  18433.  
  18434.  
  18435. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18436.  
  18437. 181 
  18438.  
  18439.  
  18440. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18441.  
  18442. 181 
  18443.  
  18444.  
  18445. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18446.  
  18447. MORE... 
  18448.  
  18449.  
  18450. ΓòÉΓòÉΓòÉ 19.2. Limitations by System - Part 2 ΓòÉΓòÉΓòÉ
  18451.  
  18452.  
  18453. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18454.  
  18455. Limitation 
  18456.  
  18457.  
  18458. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18459.  
  18460. Workstations (excluding APL2/PC) 
  18461.  
  18462.  
  18463. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18464.  
  18465. APL2/370 
  18466.  
  18467.  
  18468. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18469.  
  18470. Maximum depth of a shared variable 
  18471.  
  18472.  
  18473. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18474.  
  18475. 181 
  18476.  
  18477.  
  18478. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18479.  
  18480. 181 
  18481.  
  18482.  
  18483. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18484.  
  18485. Maximum depth of a copied variable 
  18486.  
  18487.  
  18488. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18489.  
  18490. 181 
  18491.  
  18492.  
  18493. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18494.  
  18495. 181 
  18496.  
  18497.  
  18498. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18499.  
  18500. Maximum number of characters in the name of a shared variable 
  18501.  
  18502.  
  18503. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18504.  
  18505. 255 
  18506.  
  18507.  
  18508. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18509.  
  18510. 255 
  18511.  
  18512.  
  18513. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18514.  
  18515. Maximum number of characters in a comment (minus leading blanks) 
  18516.  
  18517.  
  18518. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18519.  
  18520. 4090 
  18521.  
  18522.  
  18523. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18524.  
  18525. 32764 
  18526.  
  18527.  
  18528. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18529.  
  18530. Maximum length of line 
  18531.  
  18532.  
  18533. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18534.  
  18535. 8190 
  18536.  
  18537.  
  18538. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18539.  
  18540. N/A 
  18541.  
  18542.  
  18543. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18544.  
  18545. Maximum number of lines in a defined function or operator 
  18546.  
  18547.  
  18548. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18549.  
  18550. ┬ñ1+2*15 (32767) 
  18551.  
  18552.  
  18553. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18554.  
  18555. ┬ñ1+2*31 (2147483647) 
  18556.  
  18557.  
  18558. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18559.  
  18560. MORE... 
  18561.  
  18562.  
  18563. ΓòÉΓòÉΓòÉ 19.3. Limitations by System - Part 3 ΓòÉΓòÉΓòÉ
  18564.  
  18565.  
  18566. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18567.  
  18568. Limitation 
  18569.  
  18570.  
  18571. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18572.  
  18573. Workstations (excluding APL2/PC) 
  18574.  
  18575.  
  18576. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18577.  
  18578. APL2/370 
  18579.  
  18580.  
  18581. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18582.  
  18583. Maximum number of labels in a defined function or operator 
  18584.  
  18585.  
  18586. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18587.  
  18588. Limited by number of lines 
  18589.  
  18590.  
  18591. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18592.  
  18593. 32767 
  18594.  
  18595.  
  18596. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18597.  
  18598. Maximum number of local names (excluding labels) in a defined function or 
  18599. operator 
  18600.  
  18601.  
  18602. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18603.  
  18604. Limited by lengths of lines and names 
  18605.  
  18606.  
  18607. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18608.  
  18609. 32767 
  18610.  
  18611.  
  18612. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18613.  
  18614. Maximum number of slots in the internal symbol table. A slot is required for 
  18615. each unique name, each unique constant, and each ill-formed constant in the 
  18616. workspace. 
  18617.  
  18618.  
  18619. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18620.  
  18621. N/A 
  18622.  
  18623.  
  18624. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18625.  
  18626. 32767 
  18627.  
  18628.  
  18629. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18630.  
  18631. MORE... 
  18632.  
  18633.  
  18634. ΓòÉΓòÉΓòÉ 19.4. Limitations by System - Part 4 ΓòÉΓòÉΓòÉ
  18635.  
  18636.  
  18637. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18638.  
  18639. Limitation 
  18640.  
  18641.  
  18642. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18643.  
  18644. Workstations (excluding APL2/PC) 
  18645.  
  18646.  
  18647. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18648.  
  18649. APL2/370 
  18650.  
  18651.  
  18652. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18653.  
  18654. Maximum value of ╨áPW 
  18655.  
  18656.  
  18657. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18658.  
  18659. 254 
  18660.  
  18661.  
  18662. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18663.  
  18664. 390 
  18665.  
  18666.  
  18667. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18668.  
  18669. Maximum value of ╨áPP 
  18670.  
  18671.  
  18672. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18673.  
  18674. 16 
  18675.  
  18676.  
  18677. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18678.  
  18679. 18 
  18680.  
  18681.  
  18682. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18683.  
  18684. Maximum number of users with whom a user can share cross systems variables 
  18685.  
  18686.  
  18687. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18688.  
  18689. N/A 
  18690.  
  18691.  
  18692. ΓòÉΓòÉΓòÉ <hidden> not printable ΓòÉΓòÉΓòÉ
  18693.  
  18694. 59 
  18695.  
  18696.  
  18697. ΓòÉΓòÉΓòÉ 20. Deviations from APL2 Programming: Language Reference ΓòÉΓòÉΓòÉ
  18698.  
  18699. This appendix describes the areas in which the implementation of APL2/2 differs 
  18700. from the APL2 language as defined in APL2 Programming: Language Reference. 
  18701.  
  18702. o General Language Differences 
  18703. o APL2 Statement Entry 
  18704. o APL2 Error Reporting 
  18705. o Display of Output 
  18706. o System Functions and Variables 
  18707. o Function Editor-Editor 1 
  18708. o System Commands 
  18709.  
  18710.  
  18711. ΓòÉΓòÉΓòÉ 20.1. General Language Differences ΓòÉΓòÉΓòÉ
  18712.  
  18713.  
  18714.   Deviations 
  18715.  
  18716. o Disclose, expand, and replicate applied to rank 2 (or higher) arrays may give 
  18717.   different results, because these functions use the prototype of the first 
  18718.   element of the array as a fill item. APL2/370 uses the prototype of each row 
  18719.   or column to extend rows or columns. For example, in APL2/2: 
  18720.  
  18721.           ╤â[2]1 'AB' 'ABC'
  18722.  
  18723.   gives: 
  18724.  
  18725.     1 0 0
  18726.     A B 0
  18727.     A B C
  18728.  
  18729.   instead of: 
  18730.  
  18731.     1 0 0
  18732.     A B
  18733.     A B C
  18734.  
  18735.   Application of these functions to vectors give fully-compatible results, 
  18736.   because all platforms use the prototype of the first element. 
  18737.  
  18738. o Overtake of an array of rank 2 (or higher) can give a different result. 
  18739.   APL2/2 uses the prototype of the first element of each row (if one exists) or 
  18740.   the first element of the array (if you are forming a new row) when extending 
  18741.   rows or columns. APL2/370 uses the prototype of each individual row or 
  18742.   column, and this may lead to a different result when columns are extended. 
  18743.   For example: 
  18744.  
  18745.           3 3Γò₧2 2╤å1 'A' 'B' 2
  18746.  
  18747.   gives: 
  18748.  
  18749.     1 A 0
  18750.     B 2
  18751.     0 0 0
  18752.  
  18753.   instead of: 
  18754.  
  18755.     1 A 0
  18756.     B 2
  18757.     0   0
  18758.  
  18759.   Extension of vectors gives fully-compatible results. 
  18760.  
  18761. o Partition with a scalar left argument and an empty right argument produces a 
  18762.   one-element vector containing the empty argument. APL2/370 returns an empty 
  18763.   vector with the empty argument as its prototype. For example: 
  18764.  
  18765.           ╤å1╤é╤î0
  18766.     1
  18767.           Γòº1╤é╤î0
  18768.     2
  18769.  
  18770.   instead of: 
  18771.  
  18772.           ╤å1╤é╤î0
  18773.     0
  18774.           Γòº1╤é╤î0
  18775.     2
  18776.  
  18777. o Reduction of a scalar always returns a scalar, regardless of the valence of 
  18778.   the function applied in reduction. For example: 
  18779.  
  18780.           ╨┐/'A'
  18781.     A
  18782.  
  18783.   In APL2/370, this gives a VALENCE ERROR. 
  18784.  
  18785. o Complex numbers with a small imaginary part are not considered to be 
  18786.   equivalent to a real number having the same real part, when used in 
  18787.   comparisons. For example: 
  18788.  
  18789.           1.1Γòº1.1J1E┬ñ20
  18790.  
  18791.   gives 0 in APL2/2 and 1 in APL2/370. 
  18792.  
  18793.  
  18794.   Restrictions 
  18795.  
  18796. o Factorial, binomial, matrix inverse, and matrix divide functions are not 
  18797.   implemented for complex number arguments. For example: 
  18798.  
  18799.           ╨ó1J1
  18800.  
  18801.   gives DOMAIN ERROR. See the MATHFNS workspace in The MATHFNS Workspace for 
  18802.   details of functions to perform these operations. 
  18803.  
  18804. o No fill function is implemented for the Each operator. For example: 
  18805.  
  18806.             DISPLAYC ╨óΓûá0╤å╤é2 3╤å0
  18807.       .╤ë--------.
  18808.       Γöé .Γòò----. Γöé
  18809.       Γöé Γòƒ0 0 0Γöé Γöé
  18810.       Γöé Γöé0 0 0Γöé Γöé
  18811.       Γöé '~----' Γöé
  18812.       '╤Ä--------'
  18813.  
  18814.   instead of: 
  18815.  
  18816.       .╤ë------.
  18817.       Γöé .Γòò--. Γöé
  18818.       Γöé Γòƒ0 0Γöé Γöé
  18819.       Γöé Γöé0 0Γöé Γöé
  18820.       Γöé Γöé0 0Γöé Γöé
  18821.       Γöé '~--' Γöé
  18822.       '╤Ä------'
  18823.  
  18824. o No identity items for primitive dyadic scalar functions are implemented when 
  18825.   the function is used symbolically in a defined operator. For example: 
  18826.  
  18827.           ╨áFX 'RΓò£(FN RED) A' 'RΓò£FN/A'
  18828.           +RED╤î0
  18829.  
  18830.   gives DOMAIN ERROR. 
  18831.  
  18832. o Identity functions for primitive dyadic nonscalar functions are not 
  18833.   implemented. For example: 
  18834.  
  18835.           ,/''
  18836.  
  18837.   gives DOMAIN ERROR. 
  18838.  
  18839. o While redundant parentheses can be used for clarity, they are not allowed 
  18840.   around operators with axis specification. For example: 
  18841.  
  18842.           1(,[0.5])2
  18843.           (+/[1])1 2
  18844.  
  18845.   give SYNTAX ERROR. 
  18846.  
  18847. o Axis specification is not supported with inner and outer product. For 
  18848.   example: 
  18849.  
  18850.           1 2 +.╤ù[1] 3
  18851.           0 1 ┬░.,[0.5] 2
  18852.           1 2 ,.,[0.5] 2 2╤å╤î4
  18853.  
  18854.   all give AXIS ERROR. 
  18855.  
  18856. o Selective specification is not implemented for all cases available in 
  18857.   APL2/370. For example: 
  18858.  
  18859.           (╤ÄV)Γò£A
  18860.           (L0ΓûáV)Γò£A
  18861.  
  18862.   give DOMAIN ERROR. Also, selective specification of a shared variable gives a 
  18863.   SYNTAX ERROR. (The ENLISTA function, described in Miscellaneous Functions, 
  18864.   provides a function that can be used to replace the use of selective 
  18865.   specification with enlist.) 
  18866.  
  18867.  
  18868. ΓòÉΓòÉΓòÉ 20.2. APL2 Statement Entry ΓòÉΓòÉΓòÉ
  18869.  
  18870.  
  18871.   System Dependency 
  18872.  
  18873. o Exact fidelity of statements is not maintained. APL2/2 tokenizes function and 
  18874.   operator statement lines, and when redisplayed, these may not appear exactly 
  18875.   as entered. This can cause redundant spaces to be removed and the display 
  18876.   format of numbers to be changed. 
  18877.  
  18878.  
  18879. ΓòÉΓòÉΓòÉ 20.3. APL2 Error Reporting ΓòÉΓòÉΓòÉ
  18880.  
  18881.  
  18882.   Deviation 
  18883.  
  18884. o Where multiple errors occur in an operation, APL2/2 may report a different 
  18885.   error message than APL2/370. For example: 
  18886.  
  18887.           'AB'╤ê3 3╤å╤î9      ╤ä APL2/2
  18888.     DOMAIN ERROR
  18889.           'AB'╤ê3 3╤å╤î9
  18890.           ^   ^
  18891.           'AB'╤ê3 3╤å╤î9      ╤ä APL2/370
  18892.     LENGTH ERROR
  18893.           'AB'╤ê3 3╤å╤î9
  18894.           ^   ^
  18895.  
  18896.  
  18897. ΓòÉΓòÉΓòÉ 20.4. Display of Output ΓòÉΓòÉΓòÉ
  18898.  
  18899.  
  18900.   Deviations 
  18901.  
  18902. o Mixed arrays containing characters not in ╨áAV may not be displayed. 
  18903.  
  18904.           AΓò£1,╨áUCS 20000
  18905.           A
  18906.   gives DOMAIN ERROR. 
  18907.  
  18908. o An array that exceeds the printing width (╨áPW) is wrapped line by line, 
  18909.   rather than being folded plane by plane. 
  18910.  
  18911. o Display of columns of data of an array of mixed type gives different results. 
  18912.   APL2/370 formats a column that contains mixed data types with the character 
  18913.   items right-justified, and numeric items aligned on the decimal point. 
  18914.   However, APL2/2 formats a column of an array of mixed type with the character 
  18915.   items right-justified, and numeric items left-justified, so that: 
  18916.  
  18917.           3 2╤å'APL2' 2 (╤è1)
  18918.  
  18919.   gives: 
  18920.  
  18921.     APL2                  2
  18922.     3.141592654 APL2
  18923.               2 3.141592654
  18924.  
  18925.   instead of: 
  18926.  
  18927.            APL2 2
  18928.     3.141592654        APL2
  18929.     2           3.141592654
  18930.  
  18931. o Dyadic format with negative left argument leaves additional spaces to allow 
  18932.   for an exponent containing up to three digits, and a negative sign. For 
  18933.   example: 
  18934.  
  18935.           ╤å╨áΓò£┬ñ1╨╛1 1
  18936.  
  18937.   gives: 
  18938.  
  18939.      1E0    1E0
  18940.     14
  18941.  
  18942.   instead of: 
  18943.  
  18944.      1E0 1E0
  18945.     8
  18946.   Also: 
  18947.  
  18948.           5 ┬ñ1╨╛1
  18949.  
  18950.   gives: 
  18951.  
  18952.     DOMAIN ERROR
  18953.           5 ┬ñ1╨╛1
  18954.           ^   ^
  18955.  
  18956.   instead of: 
  18957.  
  18958.           5 ┬ñ1╨╛1
  18959.     1E0
  18960.  
  18961. o Dyadic format of a  nested array with rank higher than two returns a result 
  18962.   with the same rank. APL2/370 always returns a rank two result for higher rank 
  18963.   nested arrays. For example: 
  18964.  
  18965.           ╤å╨╛1 1 1╤å╤é'APL2'
  18966.  
  18967.   gives: 
  18968.  
  18969.     1 1 6
  18970.  
  18971.   instead of: 
  18972.  
  18973.     1 6
  18974.  
  18975. o Complex numbers are always displayed with both the real part and the 
  18976.   imaginary part, even when one differs from the other by more than ╨áPP orders 
  18977.   of magnitude. APL2/370 does not display the real or imaginary part of a 
  18978.   complex number when it is less than the other by more than ╨áPP orders of 
  18979.   magnitude (unless ╨áPP is at its maximum). For example: 
  18980.  
  18981.           3E45J2
  18982.     3E45J2
  18983.  
  18984.   instead of 
  18985.  
  18986.           3E45J2
  18987.     3E45
  18988.  
  18989.  
  18990.   Restriction 
  18991.  
  18992. o Dyadic format gives DOMAIN ERROR if formatting an element of an array gives a 
  18993.   long result. This occurs when the formatting of a number results in more than 
  18994.   255 characters. For example: 
  18995.  
  18996.           0╨╛1E255
  18997.     DOMAIN ERROR
  18998.           0╨╛1E255
  18999.           ^
  19000.  
  19001.  
  19002. ΓòÉΓòÉΓòÉ 20.5. System Functions and Variables ΓòÉΓòÉΓòÉ
  19003.  
  19004.  
  19005.   Deviation 
  19006.  
  19007. o If ╨áFC is set to anything other than a character vector, a ╨áFC ERROR is 
  19008.   reported at the time of the assignment. 
  19009.  
  19010.  
  19011.   Restrictions 
  19012.  
  19013. o ╨áL and ╨áR are not recognized; they return VALUE ERROR. 
  19014.  
  19015. o ╨áNLT can be referenced, but not set. National language is set with the -nlt 
  19016.   invocation option. 
  19017.  
  19018. o ╨áPW is not regarded as a session variable, and is reset by a )CLEAR or a 
  19019.   )LOAD command. 
  19020.  
  19021. o The contents of ╨áAI are incorrect after they reach 2*31. This can occur for 
  19022.   sessions active longer than 24 days. 
  19023.  
  19024. o General shared variable offers are not supported. 
  19025.  
  19026.  
  19027. ΓòÉΓòÉΓòÉ 20.6. Function Editor-Editor 1 ΓòÉΓòÉΓòÉ
  19028.  
  19029.  
  19030.   Deviation 
  19031.  
  19032. o The header line (line 0) of a function does not accept a comment. Any comment 
  19033.   given is ignored, and no error is generated. For example: 
  19034.  
  19035.           ΓòûTEST ╤ä COMMENT
  19036.     [1]   LINE 1
  19037.     [2]   [╨á]
  19038.     [0]  TEST
  19039.     [1]   LINE 1
  19040.     [2]
  19041.  
  19042.  
  19043.   Restrictions 
  19044.  
  19045. o Recursive editing and entry of system commands while editing are not allowed. 
  19046.  
  19047. o Editing of a line removes stop (SΓòó) and trace (TΓòó) controls for that line. 
  19048.  
  19049. o The header line (line 0) of a function must not end with a semicolon (;). 
  19050.   System variable names are the only names beginning with a quad (╨á) that can 
  19051.   be localized in the header line. An attempt to localize a system function 
  19052.   name or an undefined name beginning with a quad is rejected with a DEFN 
  19053.   ERROR. 
  19054.  
  19055.  
  19056. ΓòÉΓòÉΓòÉ 20.7. System Commands ΓòÉΓòÉΓòÉ
  19057.  
  19058.  
  19059.   Deviations 
  19060.  
  19061. o )DROP accepts a suffix in a quoted filename format for deleting transfer form 
  19062.   files. 
  19063.  
  19064. o )DROP of a workspace or transfer file displays the time and date that the 
  19065.   file was saved, rather than the current time and date. 
  19066.  
  19067. o )ERASE erases and )COPY replaces the most local, rather than the global, 
  19068.   referent of an object. 
  19069.  
  19070. o )FNS, )VARS, )OPS, )NMS, and )LIB allow specification of multiple ranges of 
  19071.   names on one command, where the language defines only one range per command. 
  19072.   The syntax for specification of multiple ranges is: 
  19073.  
  19074.           [[firstΓöéfirst-last][...]     Workstation implementation
  19075.  
  19076.           [first][-][last]             APL2/370 implementation
  19077.  
  19078. o The )SYMBOLS command gives a different report: size of table (bytes), number 
  19079.   of bytes in use, number of symbols. 
  19080.  
  19081. o )SYMBOLS n contracts or expands symbol table to n bytes. )SYMBOLS n works 
  19082.   only if there are no objects defined yet. 
  19083.  
  19084. o )OUT of a full workspace with a nonempty stack is not allowed, and the error 
  19085.   reports SI WARNING and NOT SAVED are given. 
  19086.  
  19087.  
  19088.   Restrictions 
  19089.  
  19090. o Comments are not allowed after system commands. For example, 
  19091.   )WSID ╤ä Query workspaceid is accepted by APL2/370, but not by APL2/2. 
  19092.  
  19093. o Indirect )COPY and )ERASE are not implemented. See the EXPUNGE function in 
  19094.   the EXAMPLES workspace (described in Miscellaneous Functions) for details of 
  19095.   a function that supports indirect name lists. 
  19096.  
  19097. o )EDITOR 2 is not implemented. See the EDITOR_2 function, described in The 
  19098.   EDIT Workspace, for details of a defined function that is equivalent to the 
  19099.   APL2/370 Editor 2. 
  19100.  
  19101. o )EDITOR name is implemented with some restrictions. It enables a system 
  19102.   editor to be invoked, and allows Γòûname to be used to edit a function, 
  19103.   operator or a simple character matrix. The restrictions are the same as those 
  19104.   imposed by "╨áFX ╨áCR name"; for instance, stop (SΓòó) and trace (TΓòó) controls on 
  19105.   the function are removed, and if the function is suspended, the suspended 
  19106.   copy is not modified. 
  19107.  
  19108. o )MORE always displays "NO MORE INFORMATION". 
  19109.  
  19110.  
  19111.   System Dependencies 
  19112.  
  19113. o )IN accepts a library number. 
  19114.  
  19115.   )IN [libno] filename [obj1 {obj2}...] 
  19116.  
  19117. o )PIN accepts a library number. 
  19118.  
  19119.   )PIN [libno] filename [obj1 {obj2}...] 
  19120.  
  19121. o )LIB accepts a different syntax and lists OS/2 files. The syntax is: 
  19122.  
  19123.     )LIB [libno] [initials] [{.aplΓöé.atf}]
  19124.  
  19125.   This displays files with names that start with any of the character's 
  19126.   initials and that have an extension of .apl or .atf in the indicated library 
  19127.   libno. 
  19128.  
  19129.     )LIB [libno] [first] - [last] [{.aplΓöé.atf}]
  19130.  
  19131.   This displays files with names that fall alphabetically between first and 
  19132.   last, and have an extension of .apl or .atf in the indicated library libno. 
  19133.   If either first or last is omitted, that end of the range is unbounded. 
  19134.  
  19135.   If neither initials nor first-last are given, all files are listed that meet 
  19136.   the other qualifications. 
  19137.  
  19138.   For both syntax variations, if no library number is given, the files for 
  19139.   library Γò₧╨áAI are listed. This is normally defined as being the directory from 
  19140.   which APL2 is invoked. If neither .apl nor .atf are specified, both are 
  19141.   assumed. 
  19142.  
  19143.   Examples: 
  19144.  
  19145.    )LIB 1            Lists all .apl and .atf files in library 1 
  19146.    )LIB 2 AP         Lists all .apl and .atf files with names beginning with 
  19147.                      "AP" in library 2 
  19148.    )LIB AP.apl       Lists all .apl files with names beginning with "AP" 
  19149.    )LIB -C           Lists all .apl and .atf files beginning with letters A 
  19150.                      through C 
  19151.    )LIB C-           Lists all .apl and .atf files beginning with letters C 
  19152.                      through z 
  19153.    )LIB A-C          Lists all .apl and .atf files beginning with letters A 
  19154.                      through C 
  19155.    )LIB A C          Lists all .apl and .atf files beginning with letters A and 
  19156.                      C 
  19157.  
  19158. o )OUT accepts a library number. 
  19159.  
  19160.   )PIN [libno] filename [obj1 {obj2}...] 
  19161.  
  19162.  
  19163. ΓòÉΓòÉΓòÉ 21. APL2/2 Directory Structure ΓòÉΓòÉΓòÉ
  19164.  
  19165. When the product is installed, a directory is created as the top level 
  19166. installation directory. The default name is 'C:\APL2OS2\'. It contains the 
  19167. installation control file and a read.me file that has important information 
  19168. about the product. All other directories in the table below are created under 
  19169. this main installation directory. Following each directory is a brief 
  19170. description. 
  19171.  
  19172. bin       Binary executable files 
  19173. dll       Dynamic link libraries 
  19174. fonts     APL2 fonts (session manager, AP 124, and AP 207) 
  19175. help      Online help files and documentation 
  19176. include   C Include files for user-written auxiliary procesors 
  19177. lib       C libraries for user-written auxiliary processors 
  19178. samples   Sample programs 
  19179. wslib1    Distributed workspaces )LIB 1 
  19180. wslib2    Distributed workspaces )LIB 2 
  19181.  
  19182.  
  19183. ΓòÉΓòÉΓòÉ 22. Bibliography ΓòÉΓòÉΓòÉ
  19184.  
  19185. o APL2 Publications 
  19186. o Other Books You Might Need 
  19187.  
  19188.  
  19189. ΓòÉΓòÉΓòÉ 22.1. APL2 Publications ΓòÉΓòÉΓòÉ
  19190.  
  19191. o APL2 Fact Sheet, GH21-1090 
  19192. o APL2/370 Application Environment Licensed Program Specifications, GH21-1063 
  19193. o APL2/370 Licensed Program Specifications, GH21-1070 
  19194. o APL2 for AIX/6000 Licensed Program Specifications, GC23-3058 
  19195. o APL2 for OS/2 Licensed Program Specifications, GC26-3358 
  19196. o APL2 for Sun Solaris Licensed Program Specifications, GC26-3359 
  19197. o APL2/370 Installation and Customization under CMS, SH21-1062 
  19198. o APL2/370 Installation and Customization under TSO, SH21-1055 
  19199. o APL2 Migration Guide, SH21-1069 
  19200. o APL2 Programming: Language Reference, SH21-1061 
  19201. o APL2/370 Programming: Processor Interface Reference, SH21-1058 
  19202. o APL2 Reference Summary, SX26-3999 
  19203. o APL2 Programming: An Introduction to APL2, SH21-1073 
  19204. o APL2 for AIX/6000: User's Guide, SC23-3051 
  19205. o APL2 for OS/2: User's Guide, SH21-1091 
  19206. o APL2 for Sun Solaris: User's Guide, SH21-1092 
  19207. o APL2 for the IBM PC: User's Guide, SC33-0600 
  19208. o APL2 GRAPHPAK: User's Guide and Reference, SH21-1074 
  19209. o APL2 Programming: Using Structured Query Language, SH21-1057 
  19210. o APL2/370 Programming: Using the Supplied Routines, SH21-1056 
  19211. o APL2/370 Programming: System Services Reference, SH21-1054 
  19212. o APL2/370 Diagnosis Guide, LY27-9601 
  19213. o APL2/370 Messages and Codes, SH21-1059 
  19214.  
  19215.  
  19216. ΓòÉΓòÉΓòÉ 22.2. Other Books You Might Need ΓòÉΓòÉΓòÉ
  19217.  
  19218. The following book is recommended: 
  19219.  
  19220. o APL2 at a Glance, by James Brown, Sandra Pakin, and Raymond Polivka, 
  19221.   published by Prentice-Hall, ISBN 0-13-038670-7 (1988). (Copies can be ordered 
  19222.   from IBM as SC26-4676.) 
  19223.  
  19224. Sets of keyboard keycaps are available from IBM as: 
  19225.  
  19226. o APL2 Keycaps (US and UK base set), SX80-0270 
  19227. o APL2 Keycaps, German upgrade to SX80-0270, SX23-0452 
  19228. o APL2 Keycaps, French upgrade to SX80-0270, SX23-0453 
  19229. o APL2 Keycaps, Italian upgrade to SX80-0270, SX23-0454. 
  19230.  
  19231. Two sets of APL2 Keyboard Decals, SC33-0604, are included with this product. 
  19232. Additional sets of these decal sheets can be ordered from IBM. 
  19233.  
  19234. The following publications may also be of use, and can be ordered from IBM: 
  19235.  
  19236. o IBM OS/2 Information and Planning Guide, G326-0160. 
  19237.  
  19238. o IBM OS/2 Command Reference, S71G-4112. 
  19239.  
  19240. o IBM OS/2 Keyboards and Code Pages, S10G-6312. 
  19241.  
  19242. o TCP/IP for OS/2 Programmer's Reference, SC31-6077. 
  19243.  
  19244.  
  19245. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  19246.  
  19247. TCP/IP must have been started before starting the SVP for cross-system sharing 
  19248. to work.