What's an API?

From EDM2
Jump to: navigation, search

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 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 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 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 | -------------------*/