1 SOAP::Lite for COM interface 2 ============================ 3 4SOAP::Lite for COM interface gives you ability to access SOAP services 5from your COM applications. Examples in Visual Basic, Excel/VBA, Perl, 6JavaScript and ASP are provided. 7 8Interface comes in two versions: standalone and minimal. 9Both versions were tested on Windows 2K and XP, but should work on 10Windows 9x/Me/NT/2K/XP. 11Minimal version requires Perl installation, but comes in a small size. 12Standalone version doesn't require ANYTHING (including Perl), but comes 13as one big dll. Both libraries are compiled using the latest version of 14ActivePerl available (5.8.6 build 811). 15 16Standalone: http://www.soaplite.com/download/SOAP-Lite-COM-standalone-latest.zip 17Minimal (Perl required): http://www.soaplite.com/download/SOAP-Lite-COM-minimal-latest.zip 18 19You may create your own version (all source code and batch files are provided), 20but it'll require PerlCtrl utility that comes with Perl Development Kit 21from ActiveState (http://activestate.com/). Batch files are written for the 22latest PDK version (v6). The library can ONLY be created on Windows NT, 2K, or 23XP, but will work on any Windows platform. 24 25INSTALLATION 26 27To register library: 28 29 regsvr32 Lite.dll 30 31You can now try out the example programs. 32 33To unregister library: 34 35 regsvr32 /u Lite.dll 36 37VISUAL BASIC EXAMPLES 38 39remote.vbs and temper.vbs connect to remote services, delayed stock 40quotes and temperature conversion. 41 42local.vbs connects to local ASP server. 43 44VISUAL BASIC, PERL AND JAVASCRIPT EXAMPLE 45 46These examples (states.vbs, states.pl, states.html) connect to the local 47SOAP server and call service that will return name of the state. 48 49C# EXAMPLE 50 51remote.cs example connects to remote service (XMethod.com) which echoes 52back string 'Hello'. 53 54MICROSOFT EXCEL EXAMPLE 55 56Open the Excel (states.xls) document. Be warned, this document contains 57macroses, so you can get the warning. 58If you want to run examples you need to enable macroses. For those who 59don't trust anybody code of macroses is provided in states.vba file, so 60they can disable macroses and add them from this file. 61 62By default this example will connect to local SOAP server 63(see VISUAL BASIC SERVER EXAMPLE). You may alter the address by 64changing parameter for proxy() method. 65 66Supply a number of state and click 'Get State Name' button. 67 68VISUAL BASIC SERVER EXAMPLE 69 70You may start local SOAP server by running soap.vbs script. By default 71server will accept requests on 'http://localhost/', but you can modify 72this URL. Probably you'll also need to modify dispatch_to() parameters 73where you can specify path to your Perl modules. 74 75ASP SERVER EXAMPLE (VBScript and PerlScript) 76 77Example of ASP SOAP server is provided. This implementation doesn't 78require ROPE or MSXML dlls, so all that you need is register Lite.dll 79and put soap.asp and/or soap_perl.asp in appropriate place (for example, 80c:\inetpub\wwwroot\). 81 82Now you can direct your SOAP requests to http://localhost/soap.asp 83(VBScript) or http://localhost/soap_perl.asp (PerlScript). 84 85XML-RPC examples (VBScript) 86 87Example of XML-PRC client is provided. You can use XML-RPC in a way you 88use SOAP protocol, only instead of new() method xmlrpc() method should 89be called to create an object. For example: 90 91 MsgBox CreateObject("SOAP.Lite").xmlrpc( _ 92 "proxy", "http://betty.userland.com/RPC2" _ 93 ).call("examples.getStateName", 25).result 94 95ISSUES AND LIMITATIONS 96 97HASHES 98 99Since not all languages have primitive data type that is equivalent to Perl's 100hashes, hashes don't map neatly between Perl and languages like Visual Basic 101and Visual C++. However, SOAP::Lite derived a way to move hashes around. 102hash() method allow you create hash and manipulate it. 103If your Perl program returns a hash reference, it'll be wrapped in object 104around it. This wrapper object allows you to manipulate the hash in the 105host language. 106 107Set hash = CreateObject("SOAP.Lite").hash("a", 1, "b", 2) 108hash.c = 3 109 110See hash.vbs for example that moves hashes around. 111 112See hashecho.cvs for hash of hash example. 113 114ARRAYS 115 116COM interface provides a simple way of returning arrays to the host language. 117Instead of returning an array, return an array reference (such as \@myarray 118instead of @myarray). when you return an array reference from a subroutine, 119it is automatically converted into an array in the host language. 120 121Although an array can be passed to a SOAP::Lite COM interface, a reference to 122the array can not be passed. Therefore any manipulation of the array elements 123must be returned to the caller. 124 125REFERENCES 126 127When you pass a reference (to an array, scalar, or hash) to, or return a 128reference from a COM interface, a copy of your data is passed, not a true 129reference to your data. Thus, when you manipulate the data from within a 130COM interface, you are not manipulating the calling script's data. 131The ability to use references in a traditional manner will be addressed 132in a future versions. 133 134CONTEXT 135 136How do I call a method in a list/array context? 137 138You can coerce any method call into a list context. Instead of invoking: 139 140Dim arrayFoo 141arrayFoo = myPerlObj.some_method() 142 143Use the List property to invoke the method: 144 145Dim arrayFoo 146arrayFoo = myPerlObj.List.some_method() 147 148How do I call a method in a scalar context? 149 150By default, methods are invoked in a scalar context. If, for some reason, 151you find that you need to explicitly invoke a method in a scalar context, 152you can invoke the method on the Scalar property of the object. Instead of: 153 154cntFoo = myPerlObj.some_method() 155 156Use the Scalar property to invoke the method: 157 158cntFoo = myPerlObj.Scalar.some_method() 159 160MORE INFORMATION 161 162For more information, see http://aspn.activestate.com/ASPN/docs/PDK/6.0/PerlCtrl_overview.html 163