PERL API REFERENCE QUESTIONS/COMMENTS/BUGS: michaelcollins@ivorycity.com DOWNLOAD: PService-1.0.4.tar.gz METHOD SUMMARY: PService::new PService::set_hostname_context PService::set_application_context PService::set_file_context PService::set_object_context PService::get_errmsg OVERVIEW: PService is the client interface to mod_perlservice. You may construct as many PService objects in your application as you wish and in many cases this is the appropriate thing to do. To you, the programmer, the interface is simple and powerful. Think of each instance of a PService as the interface to a particular package in some file as part of an application on a server somewhere. Therefore, as the PService implementor, you are only concerned with four properties -- hostname, application, file and package (object). After defining these, you're ready to start calling sub routines in your package on the server. It's as simple as that. Here's the crux: my $svce = new PService("www.somehost.com","someperlapp","somefile","somepackage"); my $rslt = $svce->somemethod("arg1","arg2"); Now, after only two lines of code, you've called somemethod on the server, your arguments have been encoded and pushed into somemethod's @_, and you've stored somemethod's return value back in $rslt. PService::new Construct a new PService object. USAGE my $service = new PService(hostname,application,file,object); ARGUMENTS hostname The fully qualified domain name or ip of the server running apache and mod_perlservice application The alias name of the application you wish to use, see mod_perlservice docs for more. file The name of the file that contains the code you want to use. object The object you want to call methods on. This can be "main" if the methods are not part of an object. PService::{name of remote sub} Call the sub routine on the server using the pre-set server, application, file and object contexts and get the return value. You may pass as many arguments as you wish and they will be encoded and sent along with your request. One of the most useful and important features of this system is the ability to pass complex nested data structures as arguments and recieve the same as return values. For instance you may pass arrays of hashes or hashes mixed with arrays, scalars, and hashes. Unfortunately glob values are not currently supported, but we may figure this out in the future. You can use the following types however: strings, integers, numbers (float), arrays, and hashes. The same can be received as return values. If an error occurs during the call, the function returns undef and an error message is set, see PService::get_errmsg. USAGE my $retval = $service->somemethod(); my $retval = $service->somemethod("This is my string"); my $retval = $service->somemethod(42.42); my $retval = $service->somemethod(["Automobile",32,"Aston Martin"]); my $retval = $service->somemethod({user=>"Tom Bombadil", password=>"Goldberry"}); my $retval = $service->somemethod({   matrix1=>[ [8,221,64], [66,88,128], [11,22,33] ],   matrix2=>[ [1,245,45], [11,64,198], [24,56,19] ] }); ARGUMENTS User defined. Strings, integers, numbers (float), arrays, and hashes are allowed. PService::set_host_context Change the name of the host where mod_perlservice can be found. Now, when you call a remote method, PService will connect to the new server. USAGE $service->set_host_context(newhostname); ARGUMENTS newhostname: The domain name or IP address of the server where your application files can be found. PService::set_application_context Change the name of the application you're using. The application is basically the working directory where your files are found. USAGE $service->set_application_context(newappname); ARGUMENTS newappname: The name of the application you want to start using. PService::set_file_context Change the name of the file you're using. The file contains the packages/objects and methods you want to use. USAGE $service->set_file_context(newfilename); ARGUMENTS newfilename: The file you want to start using. PService::set_object_context Change the name of the package where your methods can be found. Now method calls will access methods in the new package. USAGE $service->set_object_context(newpackagename); ARGUMENTS newpackagename: The package where your methods can be found. PService::get_errmsg In the event that a remote method call fails, the return value will be undef and an error message will be set. Use get_errmsg to get a text representation of the error. USAGE my $retval = $service->hello(); if( $retval==undef ){ print $service->get_errmsg(); } ARGUMENTS None.

Copyright 2004 Michael W. Collins, Ivory City Systems.
You have permission to modify and redistribute this document so long as it retains this original copyright.