1. Grail Interface and Code Ramón Creager

2. What is Grail? Like the Roman god Janus, Grail provides two faces to two different worlds: From the outside, a SOAP interface to the GBT M&C System. From the M&C perspective, it is an Ygor client: SOAP Requests Callbacks Ygor (RPC++) PanelRemote Monitor Recipient

3. Lifetime of a Grail Request Start Make connection Device found? Pass request To Device Return results Close connection Create new DeviceClient Device created? Return error Place Device In Map End Grail requests are made to devices, which include managers, sub- managers, coordinators, etc. These are specified by major.minor name format. Monitor requests are made to the device that hosts the sampler Connections to Grail currently share the lifetime of the requests; that is, every new request creates a new connection. No Yes No Yes

4. Lifetime of a Grail Callback Start Process M&C callback Registered? Open connection To Client SOAP Server Close connection Service M&C req. (recipient) No Yes NoYes Connection success? Encode and Transmit param Or sampler. Unregister all callbacks that use this SOAP client. Schedule callback client for deletion. Grail callbacks are registered and unregistered through a Grail Request. Grail callbacks are handled by the RPC++/M&C task. Currently, all parameters for a particular device are registered automatically with the M&C device for Manager callbacks to Grail. Registering a parameter only extends the callback to the client. Unlike parameters, samplers are not registered with the Manager unless registered by the Grail Client. Parameters should follow the sampler convention to reduce overhead at the Manager level.

5. Some remaining Grail functional issues Grail registers all a manager’s parameters for callbacks. Perhaps these should be registered as needed by the client. Some parameters returned incorrectly the very first time they are accessed. Grail does not return parameter flags and a time-stamp with the parameter/sampler structures. Grail does not currently accept entire parameter structures. Parameters must be set field by field. Thread synchronization issues remain between the two Grail threads. Addressing these would improve Grail reliability. PanelRemote deadlock issue. Grail is a Solaris application, will not work as written under Linux due to RPC++ and threading issues. Also, it cannot be properly compiled by the Linux hosted Solaris cross-compiler.

6. Grail Application Architecture Grail gSOAP server task GBT M&C DeviceClient Collection SOAP Grail Client Recipient/Monitor task gSOAP client RPC SOAP RPC SOAP serverSOAP client DeviceClient

7. The Code Grail is written in 100% pure C++ Grail relies heavily on the gSOAP code generator for its SOAP interfaces Grail relies heavily on Ygor for M&C interfaces Grail is found in the CVS repository at: ygor/user/Grail ≈ 20% of Grail code is hand coded, the rest is generated by the gSOAP code generator.

8. Grail directory structure Grail is the main source directory. Grail is compiled from this directory. DeviceClient hosts the DeviceClient, GenericRecipient and Parameter classes. These could reside in Grail but have their own directory for historical reasons. Grail-RPC contains grailstatus.x. rpcgen is run on this file, and the generated code needed by grail copied to Grail. Grail-gSOAP contains the gSOAP interface definition file Grail.h. soapcpp2 is run on this file to generate the SOAP server code, and the needed code is copied to Grail. GrailCB-gSOAP contains the gSOAP interface definition file GrailCB.h. Like Grail-gSOAP, but defines the callback client interface. Env-gSOAP contains env.h, the gSOAP interface definition file that generates the code common to the Server and Client. ygor/user/Grail Grail DeviceClient Grail-RPC Grail-gSOAP GrailCB-gSOAP Env-gSOAP sparc-solaris

9. SOAP, and gSOAP Why SOAP? –SOAP (Simple Object Access Protocol) is an XML and text based RPC and Messaging protocol. –Because of this, it is language and architecture neutral. Libraries for SOAP exist for all major programming languages. Giving the M&C system a SOAP portal opens up the M&C system to user level programming on any architecture using any language with a SOAP library. Why gSOAP? –gSOAP is an Open Source SOAP toolkit for C/C++. It is SOAP 1.1 compliant and is exceptionally well supported and complete. It has a fairly large user community with an active mailing list. –gSOAP is part library, part code generator. The code generator handles enough of the SOAP details that one could conceivably make use of it without actually understanding SOAP. –Grail was written in C++ because the M&C system interface consists of a library of C++ classes. Thus gSOAP was a natural tool to use for Grail.

10. Calc, a simple gSOAP example SOAP calc server Add(a, b) Subtract(a, b) Sqrt(a) SOAP calc client Concept: XML gSOAP input (calc.h): //gsoap ns schema namespace: urn:calc typedef double xsd__double; typedef char *xsd__string; int ns__add(xsd__double a, xsd__double b, xsd__double &result); int ns__sub(xsd__double a, xsd__double b, xsd__double &result); int ns__sqrt(xsd__double a, xsd__double &result);

11. Calc, a simple gSOAP example (continued) I:\rc\gSOAPexamples\calc_server\temp \\samba-gb\rcreager $soapcpp2 calc.h ** The gSOAP Stub and Skeleton Compiler for C and C++ 2.3 rev 3 ** Copyright (C) 2001-2003 Genivia inc. & FSU. All Rights Reserved. ** This product is provided "as is", without any warranty Saving soapStub.h Saving soapH.h Saving soapC.cpp Saving soapClient.cpp Saving soapServer.cpp Saving soapClientLib.cpp Saving soapServerLib.cpp Saving ns.wsdl Web Service description Saving soapProxy.h client proxy Saving soapObject.h server object Saving ns.add.req.xml sample SOAP/XML request Saving ns.add.res.xml sample SOAP/XML response Saving ns.sub.req.xml sample SOAP/XML request Saving ns.sub.res.xml sample SOAP/XML response Saving ns.sqrt.req.xml sample SOAP/XML request Saving ns.sqrt.res.xml sample SOAP/XML response Saving ns.nsmap namespace mapping table Saving ns.xsd XML schema description Compilation successful

12. Calc, a simple gSOAP example: Server functions int ns__add(struct soap *se, double a, double b, double &result) { result = a + b; return SOAP_OK; } int ns__sub(struct soap *se, double a, double b, double &result) { result = a - b; return SOAP_OK; } int ns__sqrt(struct soap *se, double a, double &result) { if (a >= 0) { result = sqrt(a); return SOAP_OK; } else { soap_fault(se); se->fault->faultstring = "Square root of negative number"; se->fault->detail = "I can only take the square root of a non-negative number"; return SOAP_FAULT; }

13. Calc, a simple gSOAP example: Server loop #include "soapH.h" int main(int /*argc*/, char **/*argv*/) { struct soap se; int m, s; // master and slave sockets char name[200]; soap_init(&se); gethostname(name, 199); m = soap_bind(&se, name, 18083, 100); if (m < 0) { soap_print_fault(&se, stderr); return -1; } while (1) { s = soap_accept(&se); if (s < 0) { soap_print_fault(&se, stderr); return -1; } soap_serve(&se); // process RPC skeletons soap_end(&se); // clean up everything and close socket }

14. Calc, a simple gSOAP example: Client #include "soapH.h" int main(int argc, char **argv) { soap se; double a, b, result = 0; char host[300]; snprintf(host, 299, "http://%s:18083", argv[1]); a = atof(argv[2]); b = atof(argv[3]); soap_init(&se); if (soap_call_ns__add(&se, host, "", a, b, result) != SOAP_OK) { soap_print_fault(&se, stderr); } return 1; }

15. Calc, a simple gSOAP example: on the wire <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:ns="http://titan:18083"> 2.0 3.0 <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:ns="http://titan:18083"> 5.0

16. Grail Device Classes DeviceClientMapDeviceClient * PanelRemote GenericRecipientRecipient RecipientServerMonitor 1 1 1 _parameter: std::vector operator[]() _sampler: std::vector Parameter::Visitor DeviceClient::Callback ParameterToSoapVisitor GrailCallback 0..n Operator()()