What's an API?

By Richard K. Goran

Application Programming Interfaces
Frequently the need arises to do some task from a REXX program that the language itself doesn't support. For example, accessing a data base like dBase III or dBase IV or Btrieve files; or performing a TCP/IP or LAN function. That's when you are told to find the API for the desired task. Quite simply APIs are code modules that support interfacing to other code modules or devices. One API that almost all OS/2 REXX programs use that could be considered an API is rexxutil.dll that provides OS/2 system service functions. Almost any DLL that is REXX-aware, meaning that it can be called from a REXX program, is an API. The purpose of this column is simply to make the reader aware of a number of APIs that exist; whether they are freeware, shareware, or commercially available products. Including an API in this column does not constitute an endorsement of the package. In many cases the author has not actually used many of the APIs that are listed. My main purpose is simply to make the OS/2 REXX user aware of some of the facilities that are available and where they may be obtained.

One of the first places to look for REXX APIs is Hobbes. Hobbes is actually an FTP site located on a computer at New Mexico State University that serves as one of the largest repositories of OS/2 software in the world. Their FTP server supports anonymous log in so anyone may download files from this site. Table 1 contains a list of some of the REXX packages available on Hobbes in at the time of this writing. Since Hobbes changes on a daily basis, I recommend that you get a new list periodically. You do this by connecting to the Internet via a provider of your choice and starting an FTP session, either via FTP-PM, from an OS/2 command line, or with any of the third-party FTP programs available for OS/2. (You'll find a slew of FTP alternatives on Hobbes also.) Once you're logged in to Hobbes, change to the os2/dev32/rexx directory for their latest REXX APIs. Another Internet site for free OS/2 REXX APIs is located at http://www.quercus-sys.com/rexxfree.htm.

Two of the more popular commercial REXX API are REXX SuperSet/2 from SoftTouch Systems and REXXLIB from Quercus Systems. These packages contain general purpose, system related functions that allow access to information and functions that are operating system related. Quercus also markets REXXTERM, a full-featured asynchronous communication program for OS/2 that provides extensive support for user customization and script writing with REXX. Other major features include multiple dialing directories, built-in text editor, host mode, flexible keyboard configuration, VT102 and VT52 terminal emulation, and Xmodem, Ymodem, Zmodem, Kermit, and CompuServe-B file transfer protocols.

IBM provides InterfloX, a programmer's toolkit which provides a REXX application program interface (API) to Lotus Notes. It enables an OS/2 REXX program to access, modify, create, and delete Lotus Notes databases and documents. This toolkit allows the creation of complex applications and the automation of routine tasks. It also makes possible the connection of Lotus Notes to host systems and other databases such as DB2/2. Further details on InterfloX can be found at http://www2.hursley.ibm.com/rexx/rexxflox.htm.

OS/2 Warp in its various flavours includes APIs that you can use - if you can decipher their accompanying documentation. For example, MMPM/2 comes with mciapi.dll, an API that allows you to use various multimedia devices including the digital audio, digital video, and MIDI players from within a REXX program. Sparse documentation for using the MCIAPI is included in your Multimedia folder. Full documentation for the MCIAPI interface is included with the toolkit found on IBM's DevCon CD-ROMs. For those that don't have access to an OS/2 Toolkit, you can download a list of the MCIAPI error messages via anonymous FTP. I have also created a [#sample sample program] that will play all of the .wav files specified in the System Setup / Sound configuration note on each OS/2 system where MMPM/2 is installed. The sequential line numbers are for explanatory use only and are included in brackets. The full program, [9605ls01.cmd], can be downloaded.

The MCI interface is different from the typical API you find for use with REXX since it requires command strings which include the variable names which will be assigned any return data for the function being called. Because of a known fallacy in DLL registration using the RxFuncAdd function, it is necessary to monitor for a syntax trap when first referencing mciapi.dll [0098-0136].

The MMPM initialization routine uses the info command to obtain the kind of sound card used to play wave audio files and displays that value [0124-0128]. The sound card product name is returned in a field provided within the command string rather than being returned by the function call itself as is frequently the case. The program obtains the list of wave audio file from \mmos2\mmpm.ini [0030-0058], displays each of the files with the Workplace Shell function that the sound is associated with [0060-0062], and plays the sound file [078-0087].

OS/2 Warp Connect contains REXX-aware DLLs that you can use. \tcpip\dll\rxftp.dll and \tcpip\dll\rxsocket.dll provide FTP and socket support respectively. Each is accompanied by a corresponding .inf file in the \tcpip\doc subdirectory.

OS/2 Warp Server adds another REXX API named netutil.dll. Like those APIs found on OS/2 Warp Connect, NETUTIL is accompanied by netutil.inf</tt>.

Innoval Systems Solutions, Inc., of PostRoad Mail fame, has released Surf'nRexx which contains numerous functions which allow a REXX program to perform a multitude of Internet related functions. These include FTPCOPY, FTPNEW, FTPSEND, GETMAIL, MAILNEW, NEWSPOST, REUTERS, SENDNOTE, WEBCOPY, WEBNEW, WEBCRAWL.

Table 1 - Hobbes files

9605ls01.cmd