What's an API?
Автор: Richard K. Goran
Дата: May, 1996
Источник: EDM/2
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 API's 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 https://www.quercus-sys.com/rexxfree.htm.
Two of the more popular commercial REXX API are [www.softouch.com 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 https://www2.hursley.ibm.com/rexx/rexxflox.htm.
OS/2 Warp in its various flavors 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, [../pub/9605ls01.zip 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.
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
| base64.zip | Encode/decode files in Base64 |
| cmdline1.zip | Powerful data input routine for REXX |
| colordlg.zip | A simple color selection dialog for VX-Rexx |
| datergf1.zip | REXX procedures for working with sorted dates |
| etools.zip | a collection of REXX cmd files and misc tools |
| filerx.zip | Filerexx, file and device I/O routines for Rexx |
| filerx11.zip | FileRexx v1.1, deal with binary files in Rexx |
| ft.zip | Routine which changes file type EAs |
| gbj100.zip | Wptools, WPS object settings library for REXX |
| grfxrexx.zip | REXX utils to fetch information from graphics files |
| grxsum.zip | SoftTouch Systems REXX SuperSet/2 info |
| icrexx.zip | IBM Continuous Speech REXX Interface |
| mkbko021.zip | Make Book Object, script that creates icons for .INFs |
| mnrexx10.zip | Get access to WPS objects from Rexx |
| pds.zip | Panel Display System, user interface system for REXX |
| rexmenu2.zip | Parse text file for menu selection |
| rexvim.zip | Vendor Independent Message (VIM) access for REXX |
| rexxbtrv.zip | Rexx Interface for OS/2 Btrieve |
| rexxlib.zip | Quercus systems REXXLIB REXX function package |
| rexxmath.zip | Math functions for REXX w/source |
| rexxobjv.zip | REXX samples for use with OS/2 Object Vision |
| rexxtool.zip | Rexx Tools - toolkit for Rexx development |
| rox.zip | REXX function package for OO programming |
| rxasyn20.zip | RXASYNC v1.5, asynchronous communications API for REXX |
| rxbas206.zip | RexxBase v2.06, REXX functions for dBase III/IV files |
| rxcls.zip | Compile REXX programs into standalone executables |
| rxdate20.zip | RexxDate v2.0, date function package for REXX |
| rxdlg10.zip | Rexx Dialog, add full PM interface to rexx programs |
| rxdlg11.zip | Rexx Dialog, use PM dialogs in Rexx |
| rxfnset.zip | RXFNSET, Rexx-callable DLL with system functions |
| rxgwa1.zip | EBCDIC to ASCII REXX functions |
| rxipc.zip | Basic Interprocess Communication for REXX |
| rxlogin.zip | Rexx procedure that asks for a password |
| rxmulch1.zip | Replaces/counts strings in files (REXX) |
| rxset211.zip | RxFnSet v2.11, Rexx callable DLL w/task & process API |
| rxu19.zip | RXU v1.9, rich set of Rexx functions for OS/2 API |
| rxusmp17.zip | PI2 - displays process status information |
| rxvimd.zip | RexxVIM, VIM toolkit for Rexx |
| rxx19.zip | Extra REXX functions for REXX, VX-REXX and VP-REXX |
| seldel.zip | Selectively delete applets that come with OS/2 |
| textfilt.zip | Collection of text filter scripts (REXX) |
| watool10.zip | REXX Interface w/Comm. Manager/2 3270/5250 sessions |
9605ls01.cmd
/*-------------------------------------------------*\
| 9605LS01.CMD - Play system sounds from MMPM.INI |
\*-------------------------------------------------*/
call MMPM_INITIALIZATION /* register MCIAPI.DLL */ /* 0005 */
/* 0006 */
/*-----------------------------*\ /* 0007 */
| Find ?:\MMOS2\MMPM.INI file | /* 0008 */
\*-----------------------------*/ /* 0009 */
MMPM_path = VALUE( 'MMBASE',, 'OS2ENVIRONMENT' ) /* from environment */
MMPM_path = STRIP( MMPM_path, 'T', ';' ) /* remove trailing semicolon */
MMPM_path = STRIP( MMPM_path, 'T', '\' ) || '\' /* assure trailing \ */
/* 0013 */
call SysFileTree MMPM_path || 'MMPM.INI', 'MMPM_stem', 'O' /* 0014 */
if MMPM_stem.0 = 1 then /* 0015 */
do /* 0016 */
MMPM_INI_file = MMPM_stem.1 /* 0017 */
end /* 0018 */
else /* 0019 */
do /* 0020 */
say ' Unable to locate ' || MMPM_path || 'MMPM.INI' /* 0021 */
call MMPM_CLOSE /* 0022 */
exit /* 0023 */
end /* 0024 */
/* 0025 */
/*------------------------------------------------*\ /* 0026 */
| Build table of all MMPM2_AlarmSounds key names | /* 0027 */
\*------------------------------------------------*/ /* 0028 */
app = 'MMPM2_AlarmSounds' /* 0029 */
call SysIni MMPM_INI_file, app, 'ALL:', 'key_stem' /* 0030 */
if key_stem.0 = 0 then /* 0031 */
do /* 0032 */
say ' Unable to locate any keys in ' ||, /* 0033 */
app ||, /* 0034 */
' within ' ||, /* 0035 */
MMPM_INI_file /* 0036 */
call MMPM_CLOSE /* 0037 */
exit /* 0038 */
end /* 0039 */
/* 0040 */
/*------------------------------------------------------------*\ /* 0041 */
| Each entry contains: | /* 0042 */
| wave file path || # || description || # || volume level | /* 0043 */
\*------------------------------------------------------------*/ /* 0044 */
/* List entries & play file */ /* 0045 */
say ' Sound files found in ' || MMPM_INI_file || ' include:' /* 0046 */
do k = 1 to key_stem.0 /* 0047 */
/* 0048 */
key_value =, /* 0049 */
STRIP( SysIni( MMPM_INI_file, app, key_stem.k ), 'T', '00'x )
/* 0051 */
parse value key_value with, /* 0052 */
wave_path_and_file_name, /* 0053 */
'#', /* 0054 */
wave_description, /* 0055 */
'#', /* 0056 */
wave_volume, /* 0057 */
'00'x /* 0058 */
/* 0059 */
say COPIES( ' ', 6 ) ||, /* 0060 */
LEFT( wave_description, 28 ) ||, /* 0061 */
wave_path_and_file_name /* 0062 */
/* 0063 */
if wave_path_and_file_name = '' then /* 0064 */
do /* 0065 */
iterate k /* 0066 */
end /* 0067 */
/* 0068 */
/*-----------------------------*\ /* 0069 */
| Load .WAV file if it exists | /* 0070 */
\*-----------------------------*/ /* 0071 */
confirmed_path_and_file_name =, /* 0072 */
STREAM( wave_path_and_file_name, 'C', 'QUERY EXISTS' ) /* 0073 */
if confirmed_path_and_file_name = '' then /* 0074 */
do /* 0075 */
iterate k /* 0076 */
end /* 0077 */
load_string =, /* 0078 */
'load' DAPlayer_name '"'confirmed_path_and_file_name'"' 'wait'
call mciRxSendString load_string, 'load_return', '0', '0' /* 0080 */
/* 0081 */
/*----------------*\ /* 0082 */
| Play .WAV file | /* 0083 */
\*----------------*/ /* 0084 */
play_string =, /* 0085 */
'play' DAPlayer_name 'wait' /* 0086 */
call mciRxSendString play_string, 'play_return', '0', '0' /* 0087 */
end /* 0088 */
/* 0089 */
call MMPM_CLOSE /* 0090 */
exit /* 0091 */
/* 0092 */
/*------------------------------------------------------------------------*\
| |
| call mciRxInit with possibility of syntax trap |
| |
\*------------------------------------------------------------------------*/
MMPM_INITIALIZATION: /* 0098 */
/* 0099 */
SIGNAL ON SYNTAX name MMPM_NOT_PRESENT /* 0100 */
/* 0101 */
if RxFuncQuery( 'mciRxInit' ) \= 0 then /* 0102 */
do /* 0103 */
call RxFuncAdd 'mciRxInit', 'MCIAPI', 'mciRxInit' /* 0104 */
if RESULT \= 0 then /* 0105 */
do /* 0106 */
say ' Unable to RxFuncAdd MCIAPI' /* 0107 */
exit /* 0108 */
end /* 0109 */
end /* 0110 */
call mciRxInit /* will trap on syntax if MCIAPI.DLL not available */
/* 0112 */
DAPlayer_name = 'DAPlayer' /* 0113 */
open_string =, /* 0114 */
'open waveaudio alias' DAPlayer_name 'shareable wait' /* 0115 */
open_rc =, /* 0116 */
mciRxSendString( open_string, 'DeviceID', '0', '0' ) /* 0117 */
/* 0118 */
if open_rc = 0 then /* 0119 */
do /* 0120 */
/*---------------------------*\ /* 0121 */
| Get device identification | /* 0122 */
\*---------------------------*/ /* 0123 */
info_string =, /* 0124 */
'info' DAPlayer_name 'product' /* 0125 */
info_rc = mciRxSendString( info_string, 'info_return', '0', '0' )
/* 0127 */
say ' Sound card is ' || info_return /* 0128 */
end /* 0129 */
else /* 0130 */
do /* 0131 */
say ' Open returned error code ' || open_rc /* 0132 */
exit /* 0133 */
end /* 0134 */
/* 0135 */
SIGNAL OFF SYNTAX /* 0136 */
return '' /* 0137 */
/* 0138 */
/*---------------------------------------*\ /* 0139 */
| Signal on SYNTAX comes here if no DLL | /* 0140 */
\*---------------------------------------*/ /* 0141 */
MMPM_NOT_PRESENT: /* 0142 */
/* 0143 */
say ' MCIAPI.DLL not present, program will not run' /* 0144 */
/* 0145 */
exit /* 0146 */
/* 0147 */
/*------------------------------------------------------------------------*\
| |
| Close MMPM device and issue mciRxExit |
| |
\*------------------------------------------------------------------------*/
MMPM_CLOSE: /* 0153 */
/* 0154 */
close_string = 'close' DAPlayer_name /* 0155 */
/* 0156 */
if open_rc = 0 then /* 0157 */
do /* 0158 */
call mciRxSendString close_string, 'close_return', '0', '0'
call mciRxExit /* 0160 */
end /* 0161 */
/* 0162 */
return /* 0163 */
/*--------- � REXX Cross Reference � - Created: 02/19/96 8:49pm ----------*\
K:\OS2-MAG\9605LS01.CMD - Directory time stamp 2/19/96 8:48p
---- VARIABLES ----
DAPlayer_name 0079 0086 0113< 0115 0125 0155
MMPM_INI_file 0017< 0030 0036 0046 0050
MMPM_NOT_PRESENT 0100
MMPM_path 0010< 0011< 0011 0012< 0012 0014 0021
MMPM_stem.0 0015
MMPM_stem.1 0017
RESULT 0105
app 0029< 0030 0034 0050
close_string 0155< 0159
confirmed_path_and_file_name
0072< 0074 0079
info_rc 0126<
info_return 0128
info_string 0124< 0126
k 0047 0066 0076
key_stem.0 0031 0047
key_stem.k 0050
key_value 0049< 0052
load_string 0078< 0080
name 0100
open_rc 0116< 0119 0132 0157
open_string 0114< 0117
play_string 0085< 0087
wave_description 0055 0061
wave_path_and_file_name
0053 0062 0064 0073
wave_volume 0057
with 0052
x 0050 0058
---- LABELS ----
MMPM_CLOSE 0022 0037 0090 0153:
MMPM_INITIALIZATION
0005 0098:
MMPM_NOT_PRESENT 0142:
RxFuncAdd 0104
SYNTAX 0100 0136
mciRxExit 0160
mciRxInit 0111
mciRxSendString 0080 0087 0159
---- FUNCTIONS ----
COPIES 0060
LEFT 0061
RxFuncQuery 0102
STREAM 0073
STRIP 0011 0012 0050
SysFileTree 0014
SysIni 0030 0050
VALUE 0010
mciRxSendString 0117 0126
\*------------------- � End of REXX Cross Reference � -------------------*/