home *** CD-ROM | disk | FTP | other *** search
/ PC Plus SuperCD 24 / PCPLUS115.iso / install / extern.pak / DBEXTERN.PRG < prev    next >
Encoding:
Text File  |  1994-08-02  |  13.2 KB  |  419 lines
  1. *******************************************************************************
  2. *
  3. *  PROGRAM:      dbextern.prg
  4. *
  5. *  WRITTEN BY:   Borland Samples Group
  6. *
  7. *  DATE:         1/94
  8. *
  9. *  UPDATED:      3/94
  10. *
  11. *  VERSION:      Field Test March 94
  12. *
  13. *  DESCRIPTION:  Examples that shows how the EXTERN system can be used.
  14. *
  15. *  PARAMETERS:   Number of example to execute, 0 for all.
  16. *
  17. *  CALLS:        Windows functions and calls to dbextern.dll
  18. *
  19. *  USAGE:        DO dbextern with <example#>
  20. *                Where <example#> can be from 1 to 11, or 0 for all.
  21. *
  22. *
  23. *******************************************************************************
  24.  
  25. *******************************************************************************
  26. *
  27. * Introduction:
  28. * The EXTERN system is an extension of dBASE for Windows that allows
  29. * dBASE programs to interface with DLL's written in Windows compatible
  30. * languages.  Exported functions from a DLL can be called from a dBASE 
  31. * program and those DLL functions can call back into dBASE using the
  32. * mechanism of setting and executing codeblocks.
  33. * DLL functions can be called with arguments of simple type, like numeric,
  34. * float, and character, but with the inclusion of the "dbasevar.h" file
  35. * more complex dBASE variables can be passed to functions in a DLL and 
  36. * caught in "DBaseVar" variables.  Through these DBaseVar variables the
  37. * DLL can access and manipulate dBASE variables.
  38. *
  39. * General format to declare an EXTERN function:
  40. *
  41. * EXTERN [<callconvention>] <returntype> <funcname> | <user defined funcname>
  42. *        ([parameters]) [<path>] <dllname> [FROM <expC> | <expN>]
  43. * where: 
  44. * <callconvention> = CDECL or nothing for implied PASCAL.
  45. * <returntype> = One of CVOID | CSTRING | CWORD | CLONG | CLOGICAL | 
  46. *                       CDOUBLE | CHANDLE | CINT | CVAR.
  47. * <funcname> = Name of the function you want to call.    
  48. * <user defined funcname> = Name you give to the function. Required if
  49. *                           using the FROM option.
  50. * <parameters> = parameters of the types CSTRING | CWORD | CLONG |
  51. *                CDOUBLE | CPTR | CVAR | CHANDLE | ... | CINT | CVOID |
  52. *                CLOGICAL.
  53. * <path> = Optional path to DLL, defaults to Windows DLL search path.
  54. * <dllname> = Name of the DLL that contains the function.
  55. * FROM <expC> | <expN> = name of the function in the DLL or the ordinal #
  56. *                        of the function in the DLL if you rename the
  57. *                        function above in <user defined funcname>.
  58. *
  59. * NOTE: the CVAR and ... options apply only to DLL's that are written
  60. *       for dBASE using the dbasevar.h file.
  61. *
  62. * After the EXTERN statement you can use the function just like any
  63. * other function in your dBASE statements.
  64. * 
  65. *
  66. * Following are examples that show different ways to use the 
  67. * EXTERN system.  Most examples have a C/C++ counterpart in the
  68. * dbextern.cpp file so look there to see how things work in the DLL.
  69. *
  70. * Look in the dbasevar.h header file for more information about how
  71. * dBASE variables are declared and used on the DLL side.
  72. *
  73. *******************************************************************************
  74.  
  75. parameters whichone
  76.  
  77. set talk off
  78.  
  79.  * Check parameters
  80.  
  81. tellusage = 1
  82.  
  83.  * Any parameters at all?
  84. IF pcount() > 0
  85.     * Parameter numeric?
  86.    IF type( "whichone" ) = "N"
  87.         * Parameter in range?
  88.        IF whichone <= 11 .AND. whichone >= 0
  89.            tellusage = 0
  90.        ENDIF
  91.    ENDIF
  92. ENDIF
  93.  
  94. IF tellusage = 1  
  95.    ? "Usage: do dbextern with <example#>"
  96.    ? "Where <example#> can be from 1 to 11, or 0 for all."
  97.    return
  98. ENDIF
  99.  
  100. *******************************************************************************
  101. *
  102. * Example # 1.
  103. *
  104. * Some simple examples using the different types.  Also demonstrates how
  105. * to use the FROM option using the name of a PASCAL function.
  106. * 
  107. *******************************************************************************
  108.  
  109. IF whichone = 1 .or. whichone = 0
  110.  
  111.    EXTERN CLOGICAL TypeTest1( CSTRING,CWORD,CDOUBLE ) dbextern.dll 
  112.    EXTERN CLOGICAL T1( CSTRING,CWORD,CDOUBLE ) dbextern.dll FROM "TypeTest1"
  113.    EXTERN CDECL CDOUBLE TypeTest2( CPTR, CLONG, CVAR ) dbextern.dll 
  114.  
  115.    ? "TypeTest1( should be .T. ) =", TypeTest1( "string", 123, 321.123 )
  116.    ? "T1( should be .T. ) =", T1( "string", 123, 321.123 )
  117.    d1 = 234.4
  118.    ? "TypeTest2( should be 857.50 ) =", TypeTest2( "123.1", 500, d1 )
  119.  
  120. ENDIF
  121.  
  122. *******************************************************************************
  123. *
  124. * Example # 2.
  125. *
  126. * Execute Windows API functions:
  127. * 
  128. *******************************************************************************
  129.  
  130. IF whichone = 2 .or. whichone = 0
  131.  
  132.    EXTERN CWORD MessageBox( CWORD, CSTRING, CSTRING, CWORD ) user.exe
  133.    EXTERN CWORD GetFocus() user.exe
  134.  
  135.    MessageBox( GetFocus(), "Hello", "Message", 0 )
  136.  
  137. ENDIF
  138.  
  139. *******************************************************************************
  140. *
  141. * Example # 3.
  142. *
  143. * The dBASE objects you send as CVAR's can be of various types.
  144. * In the DLL you can get the type of the object with Type().
  145. * 
  146. *******************************************************************************
  147.  
  148. IF whichone = 3 .or. whichone = 0
  149.  
  150.    EXTERN CSTRING WhichType( CVAR ) dbextern.dll
  151.  
  152.    o = .T.
  153.    ? ".T.:", WhichType( o )
  154.    o = 123.4
  155.    ? "123.4:", WhichType( o )
  156.    o = 1234
  157.    ? "1234:", WhichType( o )
  158.    o = "hello"
  159.    ? "'hello':", WhichType( o )
  160.    o = new object()
  161.    ? "new object():", WhichType( o )
  162.    o = {|a| a=a }
  163.    ? "{|a| a=a}:", WhichType( o )
  164.  
  165. ENDIF
  166.  
  167. *******************************************************************************
  168. *
  169. * Example # 4.
  170. *
  171. * dBASE variables are passed by reference and are caught on the 
  172. * DLL side with a DBaseVar *.  This makes it possible to modify
  173. * dBASE objects in the DLL.  This example also demonstrates how
  174. * to use the CVAR type as the return type of functions.  In the
  175. * source code of the DLL there are some hints on how to set up
  176. * the prototypes for the corresponding C/C++ functions.
  177. * 
  178. *******************************************************************************
  179.  
  180. IF whichone = 4 .or. whichone = 0
  181.  
  182.        * We'll do a CDECL and a PASCAL function.
  183.    EXTERN CDECL CVAR ModifyAndAdd1( CVAR, CVAR ) dbextern.dll
  184.    EXTERN CVAR ModifyAndAdd2( CVAR, CVAR ) dbextern.dll
  185.  
  186.    d1 = 2.5
  187.    d2 = 3
  188.    result = .F.
  189.    result = ModifyAndAdd1( d1, d2 )
  190.    ? "d1 before 2.5,     after", d1
  191.    ? "d2 before 3,       after", d2
  192.    ? "result before .F., after", result
  193.  
  194.    d1 = 2.5
  195.    d2 = 3
  196.    result = .F.
  197.    result = ModifyAndAdd2( d1, d2 )
  198.    ? "d1 before 2.5,     after", d1
  199.    ? "d2 before 3,       after", d2
  200.    ? "result before .F., after", result
  201.  
  202. ENDIF
  203.  
  204. *******************************************************************************
  205. *
  206. * Example # 5.
  207. *
  208. * Members of a class object passed to a DLL are also accessible.
  209. * This leads to one way to execute Windows API functions that require 
  210. * structs as parameters.  Here we call into a DLL that translates the 
  211. * dBASE class object into a C struct and does the actual calling. The
  212. * result of the call is piped back into a dBASE object.
  213. *
  214. *******************************************************************************
  215.  
  216. IF whichone = 5 .or. whichone = 0
  217.  
  218.    EXTERN CDECL CVOID WSetRect( CVAR,CWORD,CWORD,CWORD,CWORD ) dbextern.dll
  219.    EXTERN CVOID WIntersectRect( CVAR,CVAR,CVAR ) dbextern.dll
  220.  
  221.    r1 = new Rect()
  222.    r2 = new Rect()
  223.    r3 = new Rect()
  224.    WSetRect( r1, 10,20,100,200 )
  225.    WSetRect( r2, 50,60,150,260 )
  226.    WIntersectRect( r3, r1, r2 )
  227.    ? "Rect after intersect:"
  228.    ? r3.left, r3.top, r3.right, r3.bottom
  229.  
  230. ENDIF
  231.  
  232. *******************************************************************************
  233. *
  234. * Example # 6.
  235. *
  236. * Through the use of code blocks dBASE code can be executed on the fly
  237. * from inside the DLL.  This example passes 2 objects and through code
  238. * blocks the objects are compared and changed in the DLL.
  239. *
  240. *******************************************************************************
  241.  
  242. IF whichone = 6 .or. whichone = 0
  243.  
  244.    EXTERN CSTRING CheckAndChange( CVAR, CVAR ) dbextern.dll
  245.  
  246.    a = 5; b = 5
  247.    ? CheckAndChange( a, b )
  248.    ? "a and b =", a, b
  249.  
  250. ENDIF
  251.  
  252. *******************************************************************************
  253. *
  254. * Example # 7.
  255. *
  256. * dBASE arrays can be accessed in the DLL.  This example computes the
  257. * average of the members of an array created on the dBASE side.
  258. * The DLL function is called without any parameters.  To be able to
  259. * get at the array, the DLL function is executed through a function
  260. * pointer that is a member of the same object as the array.  Inside
  261. * the DLL you can get the "this" pointer of the object the calling
  262. * functionptr belongs to, and through that "this" pointer you can 
  263. * access the array members.
  264. * Normally ofcourse you can just pass the array as a CVAR.
  265. *
  266. *******************************************************************************
  267.  
  268. IF whichone = 7 .or. whichone = 0
  269.  
  270.    EXTERN CDECL CDOUBLE ComputeAverage() dbextern.dll
  271.  
  272.    d = new array( 5 )
  273.    d.average = ComputeAverage
  274.    d[1] = 1.1
  275.    d[2] = 2.2
  276.    d[3] = 3.3
  277.    d[4] = 4.4
  278.    ? "Computed average:", d.average()
  279.  
  280. ENDIF
  281.  
  282. *******************************************************************************
  283. *
  284. * Example # 8.
  285. *
  286. * This example puts into "practice" a majority of the available 
  287. * memberfunctions of the DBaseVar class.  Not much to see on this side, 
  288. * but check out the corresponding function in the DLL.
  289. * 
  290. *******************************************************************************
  291.  
  292. IF whichone = 8 .or. whichone = 0
  293.  
  294.    EXTERN CLONG TestABunch( CVAR ) dbextern.dll
  295.  
  296.    p = new object()
  297.    ? "TestABunch Errors:", TestABunch( p )
  298.    ? "row one of array p:", p[1,1], p[1,2], p[1,3]
  299.    ? "row two of array p:", p[2,1], p[2,2], p[2,3]
  300.  
  301. ENDIF
  302.  
  303. *******************************************************************************
  304. *
  305. * Example # 9.
  306. *
  307. * If a DLL is written in a language that can talk to DOS, you can take
  308. * advantage of that.  This example gets the complete DOS environment in
  309. * one big string.  The FROM option using ordinals is also used. Ordinal
  310. * 14 refers to GetEnvString as can be seen in the dbextern.def file. 
  311. *
  312. *******************************************************************************
  313.  
  314. IF whichone = 9 .or. whichone = 0
  315.  
  316.    EXTERN CDECL CVOID GetEnvString( CVAR ) dbextern.dll 
  317.    EXTERN CDECL CVOID Getit( CVAR ) dbextern.dll FROM 14
  318.  
  319.    q1 = new object()
  320.    GetEnvString( q1 )
  321.    q2 = new object()
  322.    Getit( q2 )
  323.    ? "First 40 chars of environment:"
  324.    ? substr( q1,1,20 ) + substr( q2,21,20 )
  325.  
  326. ENDIF
  327.  
  328. *******************************************************************************
  329. *
  330. * Example # 10.
  331. *
  332. * This example shows how variable number of parameters can be implemented
  333. * for CDECL functions, and how the FROM option works with CDECL functions.
  334. *
  335. *******************************************************************************
  336.  
  337. IF whichone = 10 .or. whichone = 0
  338.  
  339.    EXTERN CDECL CDOUBLE AddNumbers(...) dbextern.dll
  340.    EXTERN CDECL CDOUBLE AddThem(...) dbextern.dll FROM "_AddNumbers"
  341.  
  342.    a = 1.1
  343.    b = 2.2
  344.    c = 3.3
  345.    ? "AddNumber(...) should be 6.60:",AddNumbers( a, b, c )
  346.  
  347.    a = 2.1
  348.    b = 3.2
  349.    c = 4.3
  350.    ? "AddThem(...) should be 9.60:",AddThem( a, b, c )
  351.  
  352. ENDIF
  353.  
  354. *******************************************************************************
  355. *
  356. * Example # 11.
  357. *
  358. * This example shows how a dBASE object can be combined with an "hidden"
  359. * C++ sister object.  Each dBASE object has its own unique C++ object.
  360. * This allows a dBASE object to "remember and store" its own details 
  361. * specific to the DLL in the C++ object instead of having to save it
  362. * in the dBASE object. Examples are the storing of filehandles, and 
  363. * filepointers when the DLL is servicing files.
  364. * Another possibility is a form of late binding where at the time of 
  365. * creation of the C++ part a choice can be made from several derived 
  366. * classes based on a common parent object. 
  367. *
  368. *******************************************************************************
  369.  
  370. IF whichone = 11 .or. whichone = 0
  371.  
  372.    EXTERN CWORD DLLObjectInit( CWORD ) dbextern.dll
  373.    EXTERN CSTRING Doit() dbextern.dll
  374.    EXTERN CVOID Release() dbextern.dll
  375.  
  376.     * Create 2 objects that bind with the same C++ class.
  377.    foo1 = new dBASEObject()
  378.    foo2 = new dBASEObject()
  379.    foo1.init( 1 )
  380.    foo2.init( 1 )
  381.     * One more object that binds with a different C++ class.
  382.    bar = new dBASEObject()
  383.    bar.init( 2 )
  384.  
  385.     * The first 2 object have different information stored but
  386.     * behave similarly.
  387.    ? "foo1.doit():", foo1.doit()
  388.    ? "foo2.doit():", foo2.doit()
  389.  
  390.     * The last one has different info AND behaves differently.
  391.    ? "bar.doit():", bar.doit()
  392.  
  393.    foo1.release()
  394.    foo2.release()
  395.    bar.release()
  396.  
  397. ENDIF
  398.  
  399. *******************************************************************************
  400. *
  401. * Class definitions.
  402. *
  403. *******************************************************************************
  404.  
  405. class Rect
  406.     this.left=0
  407.     this.top=0
  408.     this.right=0
  409.     this.bottom=0
  410. endclass
  411.  
  412. class dBASEObject
  413.    this.init = DLLObjectInit
  414.    this.doit = Doit
  415.    this.release = Release
  416. endclass
  417.  
  418. ********************* End of dbextern.prg ************************************
  419.