home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Professional / OS2PRO194.ISO / os2 / prgramer / rexx / rexxfunc / ezrxfunc / readme < prev    next >
Text File  |  1993-07-28  |  9KB  |  205 lines
  1.  
  2. ============================================================================
  3. EZRXFUNC -- An example of how to build REXX/VX-REXX external functions in C.
  4. ----------------------------------------------------------------------------
  5.  
  6.                                                                Eric Giguere
  7.                                                        WATCOM International
  8.                                                        giguere@watcom.on.ca
  9.  
  10. ============================================================================
  11.  
  12.  
  13. Description
  14. -----------
  15.  
  16.     This package shows you how to write external REXX functions in C and
  17. package them into a DLL.  These functions will then be available for use
  18. by your REXX and VX-REXX programs.  Makefiles are included for use with
  19. WATCOM C 8.5 and up and IBM's C Set/2.
  20.  
  21.     The information contained herein is not specific to VX-REXX, but if
  22. you want more information on VX-REXX (a visual development environment
  23. for OS/2 that adds Presentation Manager support to your REXX programs),
  24. contact WATCOM (see info at the end of this file).
  25.  
  26.  
  27. Installation
  28. ------------
  29.  
  30. From an OS/2 command line, do this:
  31.  
  32.     WATCOM C:  Run install.cmd, type 'W' and press ENTER.  This copies
  33.                the two files MAKE.CMD and MAKEPROD.CMD from the watcom
  34.                subdirectory.  If your WATCOM environment variable is not
  35.                set, set it now, as in:
  36.  
  37.                           set WATCOM=c:\watcom
  38.  
  39.                (Point it to wherever you installed WATCOM C.)  Now type
  40.                'make' to make a debug version of the EZRXFUNC.DLL.  Typing
  41.                'makeprod' makes a production (non-debug) version.  WATCOM
  42.                C 9.5 also assumes you have the TOOLKIT environment variable
  43.                defined.
  44.  
  45.     C Set/2:   Run install.cmd, type 'C' and press ENTER.  This copies
  46.                the two files MAKE.CMD and MAKEPROD.CMD from the cset
  47.                subdirectory.  Make sure all the appropriate CSET environment
  48.                variables have been set, and that the Toolkit is installed
  49.                and in your path.
  50.  
  51. If you are running WATCOM C 9.5, you also have to edit the watcom\makefile.mak
  52. file and replace the "clibdl3r" file in the $(LIBS) macro with "clib3r".
  53.  
  54. Now type 'make' to make a debug version of the EZRXFUNC.DLL.  Typing
  55. 'makeprod' makes a production (non-debug) version.
  56.  
  57. Header files are in the 'h' subdirectory, C files in the 'c' subdirectory,
  58. makefiles and associated junk in either the 'watcom' or 'cset' subdirs.
  59. Object files will be placed in the 'o' and 'oprod' subdirs.
  60.  
  61.  
  62. Testing the DLL
  63. ---------------
  64.  
  65. After the make, you will see the file 'EZRXFUNC.DLL' in the current
  66. directory.  You may test the functions in this by typing 'start testdll'.
  67. If you type 'testdll' instead of 'start testdll', you will have to exit
  68. the current OS/2 session to properly unload the DLL.  It is start a new
  69. session and exit it.
  70.  
  71.  
  72. How the DLL Works
  73. -----------------
  74.  
  75. The DLL defines four exported functions that REXX can call.  These functions
  76. are defined using the System calling convention and a fixed number of
  77. arguments.  Take a look at the file func1.c to see an example of this.
  78.  
  79. To call any of these functions, you must first tell REXX about them.  You
  80. do this using the RXFuncAdd function, as in:
  81.  
  82.          call RXFuncAdd 'EZLoadFuncs', 'EZRXFUNC', 'EZLoadFuncs'
  83.  
  84. This tells REXX that when it sees a call to the function 'EZLoadFuncs',
  85. it should load the DLL called 'EZRXFUNC' and call the entry point
  86. called 'EZLoadFuncs'.  The entry point and the function name may be different,
  87. but are often the same.  After this call, you can do this:
  88.  
  89.          call EZLoadFuncs
  90.  
  91. and this calls the external function.
  92.  
  93. It is customary when building an external function DLL to have a function
  94. to automatically register all the other functions in a DLL and a function
  95. to deregister these functions.  By convention, those functions should
  96. be called '<prefix>LoadFuncs' and '<prefix>DropFuncs'.  So after the call
  97. to EZLoadFuncs above, the functions EZFunc1, EZFunc2 and EZFunc3 will
  98. also be available.
  99.  
  100. Note that when you register a function, it becomes available to _every_
  101. REXX program in the system.  Similarly, if you drop a function it becomes
  102. inaccessible to _every_ REXX program.  You may find it convenient to
  103. register your DLLs in OS/2's STARTUP.CMD file.  You will rarely (usually
  104. never) drop functions.
  105.  
  106.  
  107. Building Your Own DLL
  108. ---------------------
  109.  
  110. You can build your own external function DLL based on the skeleton that
  111. EZRXFUNC provides.  The following steps outline the process:
  112.  
  113.     1. Decide on a name for your DLL, up to 8 characters long.  Say
  114.        you call it 'MYDLL'.  Edit the makefile.mak file for your compiler
  115.        and change the macros that refer to 'EZRXFUNC'.  You must also
  116.        change the module name, which is defined in the makefile for WATCOM C
  117.        and as a separate .DEF file for C Set/2.
  118.  
  119.     2. Choose a prefix to use for your functions.  It's a good idea to start
  120.        all your functions with the same prefix to prevent name conflicts
  121.        with other external functions.  Say you choose 'My' as the prefix.
  122.  
  123.     3. Edit the file funcload.c.  Change the functions names for EZLoadFuncs
  124.        and EZDropFuncs to use the new prefix.  Also change the names in the
  125.        table.  Since these names are also exported, you must change the
  126.        exports as well (in the makefile for WATCOM C, in the .DEF file for
  127.        C Set/2).
  128.  
  129.     4. Write your new functions based on the examples shown in func1.c
  130.        and func2.c.  For each function, add an entry to the table in
  131.        funcload.c and update the exports for the DLL.
  132.  
  133.     5. If you have special initialization and/or termination issues, you
  134.        can add code to the __dll_initialize and __dll_terminate functions
  135.        in initterm.c.  These functions are called whenever a process loads
  136.        or unloads the DLL.
  137.  
  138.     6. Note that the DLL is defined so that data segments are nonshared
  139.        and per-process -- in other words, every process that accesses the
  140.        DLL will get its own copy of global & static data, just like
  141.        an executable file.  You can change this if you want.
  142.  
  143. That's all there is to it...
  144.  
  145.  
  146. Notes 
  147. -----
  148.  
  149.     1. There are two valid return codes for your functions: 0 or 40.  The
  150.        former means everything's OK, and the latter tells REXX to halt
  151.        because of an invalid function call.  If you return 0, always make
  152.        sure you set the result string to something that makes sense, even
  153.        if it's just a null string.
  154.  
  155.     2. Never try to free the result string pointer that REXX passes you.
  156.        This is a pointer to a fixed-length buffer allocated by the
  157.        interpreter.  If you don't have enough room in that buffer, just
  158.        set the pointer to a new buffer that was allocated with the
  159.        DosAllocMem function.  Take a look at what CopyResult does in
  160.        the rxsutils.c file.
  161.  
  162.     3. Be prepared for multiple threads.  VX-REXX programs can easily
  163.        run multiple threads of execution, so your REXX function may be
  164.        called simultaneously be two different threads.  Use the usual
  165.        synchronization methods that are available under OS/2 to protect
  166.        global & static data.
  167.  
  168.     4. Don't modify any of the RXSTRINGs that REXX passes to your function
  169.        except for the result string.
  170.  
  171.     5. You can register multiple functions with the same entry point. Use
  172.        the "name" argument to distinguish between them.
  173.  
  174.     6. A bunch of useful utility functions are found in rxsutils.c for
  175.        doing various RXSTRING-to-type conversions.  These functions were
  176.        written for WATCOM C primarily, but will probably compile with C Set
  177.        if you have the migration library installed.  If you want to try
  178.        compiling them with a compiler other than WATCOM's, you must remove
  179.        the #ifdef __WATCOMC__.
  180.  
  181.     7. What's an RXSTRING?  See the file <rexxsaa.h> for a definition.
  182.        It's just a struct with two fields:  a pointer and a length.  Remember,
  183.        strings in REXX are not null-terminated.  However, the arguments
  184.        that are passed to your function by REXX are null-terminated, so in
  185.        most cases it's OK to use strcmp() and similar functions.  But watch
  186.        out for embedded nulls!
  187.  
  188.  
  189. ----------------------------------------------------------------------------
  190.  
  191. North America:                                  Europe:
  192. -------------                                   ------
  193.  
  194. WATCOM International                            WATCOM Europe
  195. 415 Phillip Street                              PO Box 64
  196. Waterloo, Ontario                               Livingston
  197. Canada N2L 3X2                                  West Lothian
  198.                                                 EH54 7AE
  199. Toll free in North America: (800) 265-4555      United Kingdom
  200.  
  201. Phone: (519) 886-3700                           Phone: (44) 506 460112
  202. FAX: (519) 747-4971                             FAX: (44) 506 460115
  203.  
  204. Email: tech@watcom.on.ca
  205.