OS/2 REXX: From Bark to Byte Document Number GG24-4199-00 December 1993 International Technical Support Organization Boca Raton Center Take Note! Before using this information and the product it supports, be sure to read the general information under “Special Notices” on page xix. First Edition (December 1993) This edition applies to OS/2 2.1. Order publications through your IBM representative or the IBM branch office serving your locality. Publications are not stocked at the address given below. An ITSO Technical Bulletin Evaluation Form for reader′s feedback appears facing Chapter 1. If the form has been removed, comments may be addressed to: IBM Corporation, International Technical Support Organization Dept. 91J, Building 235-2 Internal Zip 4423 901 NW 51st Street Boca Raton, Florida 33431-1328 When you send information to IBM, you grant IBM a non-exclusive right to use or distribute the information in any way it believes appropriate without incurring any obligation to you. Copyright International Business Machines Corporation 1993. All rights reserved. Note to U.S. Government Users — Documentation related to restricted rights — Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp. Abstract This document describes OS/2 REXX from a usage and application scenario basis. It includes OS/2 REXX interfaces to CM/2, DB2/2 and MMPM/2. This document is intended for IBM system engineers, IBM technical advisors, IBM authorized dealers, IBM customers and others who require a knowledge of OS/2 2.1 REXX and its interfaces. A working knowledge of OS/2 2.1 and REXX is assumed. PS (336 pages) Copyright IBM Corp. 1993 iii iv OS/2 REXX Contents Abstract . iii Figures . xiii Tables . xvii Special Notices . xix Preface . xxi How This Document is Organized ....................... xxi Related Publications . xxii International Technical Support Organization Publications ........ xxiii Acknowledgments . xxiii Chapter 1. Why REXX? . 1 1.1 Power of OS/2 2.1 REXX ............................ 2 1.2 Example . 5 1.2.1 Sample 1 FAH2CEL.CMD ......................... 5 Chapter 2. OS/2 REXX Specifics ......................... 9 2.1 Calling from a REXX Procedure ....................... 9 2.1.1 The REXX Call Instruction ....................... 10 2.1.2 Calling OS/2 .EXE or Command Files ................ 11 2.1.3 Multitasking with START and DETACH ............... 15 2.2 File I/O with OS/2 REXX ........................... 18 2.2.1 Charin(name,start,length) . 19 2.2.2 Charout(name,string,start) . 20 2.2.3 Chars(name) . 20 2.2.4 Linein(name,line,count) . 21 2.2.5 Lineout(name,string,line) . 21 2.2.6 Lines(name) . 22 2.2.7 Stream(name,operation,streamcommand) . 22 2.2.8 Examples . 23 2.3 RxQueue . 25 2.3.1 PUSH . 25 2.3.2 QUEUE . 25 2.3.3 Private Queues Using RXQUEUE ................... 26 2.3.4 LIFO, FIFO and CLEAR ......................... 38 2.4 Printing . 38 2.4.1 PRINT Command . 39 Copyright IBM Corp. 1993 v 2.4.2 Lineout and Charout .......................... 39 2.4.3 Printer Objects . 39 2.5 PMREXX, REXXTRY and RxMessageBox ................ 42 2.5.1 PMREXX . 42 2.5.2 REXXTRY ................................. 46 2.5.3 RxMessageBox . 47 Chapter 3. External Functions . 49 3.1 Usefulness . 49 3.2 How to Register External Functions ................... 50 3.3 Example - Accessing User Profile Management Services ...... 51 3.4 Some Established External Function Packages ............. 52 Chapter 4. REXX Utilities External Function Package (REXXUTIL) .... 53 4.1 Drives, Directories and Files ........................ 54 4.1.1 SysDriveMap . 54 4.1.2 SysDriveInfo . 56 4.1.3 SysFileDelete . 58 4.1.4 SysFileTree . 58 4.1.5 SysFileSearch . 58 4.1.6 SysMkDir . 60 4.1.7 SysSearchPath . 60 4.2 Workplace Shell Objects .......................... 60 4.2.1 SysCreateObject . 61 4.2.2 SysSetObjectData . 62 4.3 Miscalleneus Functions . 64 4.3.1 SysCls . 65 4.3.2 SysCurPos . 65 4.3.3 SysCurState . 65 4.3.4 SysGetKey . 66 4.3.5 SysSleep . 66 4.3.6 SysTextScreenRead . 67 4.3.7 SysTextScreenSize . 67 Chapter 5. The Workplace Shell and REXX .................. 69 5.1 Objects and Object Classes ........................ 69 5.1.1 WPFileSystem . 71 5.1.2 WPAbstract . 71 5.1.3 WPTransient . 71 5.2 Creating Objects . 72 5.2.1 Creating a Folder Object ........................ 72 5.2.2 Creating a Program Object ...................... 74 5.2.3 Creating a Shadow Object ....................... 75 vi OS/2 REXX 5.2.4 Creating a Program Object in the Startup Folder ......... 76 5.3 Creating Drag and Drop REXX Programs ................ 77 5.4 Creating (Shadow) Objects Associated With Data Files ........ 78 5.5 Modifying Workplace Shell Objects .................... 79 5.5.1 Object IDs . 79 5.5.2 RC Files . 79 5.5.3 User INI File ............................... 80 5.5.4 SysSetObjectData . 81 5.6 Moving Objects . 84 5.7 SysIni . 84 5.7.1 Using SysIni to Change System Settings .............. 85 5.7.2 Using SysIni to Read INI Data ..................... 87 5.8 Extended Attributes . 89 Chapter 6. REXX and C ............................. 93 6.1 Creating C Functions for REXX ...................... 93 6.1.1 RXSTRING . 94 6.1.2 Writing the C Function ......................... 94 6.1.3 Parameter Handling . 97 6.2 Creating DLLs Callable by REXX Programs ............... 100 6.3 Calling REXX from C (REXXSTART Function) .............. 101 Chapter 7. Multimedia REXX . 105 7.1 MMPM/2 Installation . 106 7.2 Using MCI from REXX ............................ 106 7.2.1 Registering MMPM/2 Functions .................... 106 7.2.2 Checking if MMPM/2 is Installed ................... 106 7.2.3 Opening a Media Device ........................ 107 7.2.4 Error Checking . 108 7.2.5 MCI Commands . 108 7.2.6 ACQUIRE . 109 7.2.7 CAPABILITY . 109 7.2.8 CLOSE object . 110 7.2.9 CONNECTOR . 110 7.2.10 INFO . 111 7.2.11 Load . 111 7.2.12 PAUSE . 112 7.2.13 PLAY . 112 7.2.14 RECORD . 113 7.2.15 RELEASE . 113 7.2.16 RESUME . 113 7.2.17 SAVE . 114 7.2.18 SEEK . 114 Contents vii 7.2.19 SET . 114 7.2.20 STATUS . 115 7.2.21 STOP . 115 7.3 RXPLAY.EXE . 115 Chapter 8. REXX Interfaces to CM/2 EHLLAPI ................ 125 8.1 EHLLAPI Uses . 125 8.2 Calling EHLLAPI Functions from REXX Programs ........... 126 8.3 Connecting and Disconnecting Host Sessions ............. 127 8.4 Reading the Host Screen .......................... 128 8.4.1 How to Obtain the Presentation Space Dimensions ........ 128 8.4.2 Copying the Presentation Space ................... 129 8.4.3 Searching the Presentation Space .................. 130 8.5 Sending Keystrokes to the Host Session ................ 131 8.6 Determining Host Availability ....................... 131 8.6.1 Using Screen Changes to Manage Host Availability ....... 132 8.6.2 Query Host Update Function ..................... 134 8.6.3 Pause Function . 135 8.6.4 Wait Function ............................... 136 8.6.5 A Sample Host Checking Algorithm ................. 136 8.7 A Sample EHLLAPI Program - EHLRDR.CMD .............. 137 8.8 Sending and Receiving Files ........................ 145 8.8.1 Example - EHLSF.CMD ......................... 145 8.8.2 Example - EHLRECV.CMD ....................... 147 8.9 Manipulating the Presentation Space Window ............. 150 Chapter 9. REXX Interfaces to DB2/2 ..................... 151 9.1 DB2/2 Installation and Setup ........................ 151 9.2 How to Register DB2/2 Functions ..................... 152 9.3 User Profile Management (UPM) ..................... 153 9.4 DB2/2 Database Administration ...................... 154 9.4.1 Server Workstation Database Administration ........... 154 9.4.2 Client Workstation Database Administration ............ 159 9.5 Embedding Structured Query Language (SQL) Statements in REXX Programs . 163 9.5.1 Static vs. Dynamic SQL ........................ 163 9.5.2 SELECT Statement . ..