This text is taken from UD GridMP installation media. Upon request, ACS will make the SDK kit available to Georgia State University GridMP users. Contact ACS via HelpDesk or directly.

Grid MP Platform SDK v5.4.0

Overview

This chapter discusses the example applications contained in the SDK. An example application ("OIC") is presented in multiple implementations in different programming language environments.

SDK Contents

Protocols

The interfaces to the MGSI service are implemented using SOAP, XML-RPC, and HTTP.

The RPC interface consists of a set of individual function calls. These functions are implemented using SOAP and XML-RPC. Both interfaces support scalar values, structures (sets of name-value pairs), and arrays.

SOAP

The SOAP interface is the preferred MGSI interface, because it supports the full Unicode character set. The interface is specified in the udmgsi.wsdl file.

XML-RPC

The XML-RPC interface is a somewhat simpler interface than SOAP, but only some implementations support Unicode characters. This interface should only be used if the ability to use SOAP is not available. There is no formal specification for this MGSI interface.

HTTP

The plain HTTP protocol is used for interaction with the File Server. Most programming environments have the ability to execute GET and POST HTTP requests.

Interface Classes

Because the MGSI service is implemented using standard SOAP web services, many programming environments can call MGSI functions directly, with or without the udmgsi.wsdl file.

In many situations it is desirable to have a small extra layer of functionality on the client side. In particular, for programs that expect to run for more than one hour, care must be taken to renew the MGSI authentication token when necessary. The MGSI authentication token is only good for one hour from the time the login function is called.

The client side interface classes automatically call the login function whenever it is necessary to do so. This relieves the calling code from having to catch and handle this common type of exception. However, the calling code should always handle exceptions that might be thrown from MGSI functions. Failure to handle such exceptions will cause an immediate program abort in most programming environments.

Experience has shown that the easiest programming language to use when writing an MGSI client is Java. Java is available on virtually every platform and supports the SOAP web services model well.

Java

The Java interface library is provided in the com.ud.mgsi package. The majority of the classes in this package are created automatically using the Apache Axis tools. The one class that is not automatically generated by Axis is the com.ud.mgsi.Retry class.

The com.ud.mgsi.Retry class provides a transparent layer on top of the generated Axis interface. Normal use of the Axis interface is something like this:

UdMgsiPortType mgsi = new UdMgsiLocator().getUdMgsiPort(new URL(address));

To use the Retry class, change this as follows:

UdMgsiPortType mgsi = *(UdMgsiPortType)new Retry(*                         new UdMgsiLocator().getUdMgsiPort(new URL(address)),                         *UdMgsiPortType.class).create()*; 

To take advantage of the automatic relogin feature, pass null to the auth parameter of each MGSI function. If you pass a non-null authentication token value, that value will be explicitly used and not refreshed even if it has expired. If you pass a null value, the authentication token obtained from the last successfull call to login (or login2) will be used, and refreshed if necessary.

.NET

The .NET interface library is provided in the com.ud.mgsi.dll file. All the classes in this package are created automatically using the wsdl.exe tool.

To use the UdMgsi? class, use code such as the following:

using com.ud;  UdMgsi mgsi = new UdMgsi(); mgsi.Url = address; 

This class currently does not provide automatic relogin features.

Perl

Some of the tools in the SDK use a small bit of Perl code that provides automatic an automatic reauthentication feature. This code is not packaged in a Perl module but is instead included at the end of a script that uses it. For convenience, the code is reproduced here:

package MgsiAuthenticator;  use vars qw($AUTOLOAD);  sub new {     my ($class, $server) = @_;     my $r = {server => $server};     return bless($r, $class); }  sub call {     my $self = shift;     my $f = shift;     my $r;     if ($f !~ /^login/) {         splice(@_, 0, 0, $self->{auth});         $r = $self->{server}->call($f, @_);         if ($r->fault && $r->faultstring =~ /^\(-1\)/) {             my $rr = $self->{server}->call("login", @{$self->{loginparams}});             if ($rr->fault) {                 return $r;             }             $self->{auth} = $rr->result;             $_[0] = $self->{auth};             $r = $self->{server}->call($f, @_);         }     } else {         $r = $self->{server}->call($f, @_);         $self->{loginparams} = \@_;         if ($f eq 'login') {             $self->{auth} = $r->result;         } elsif ($f eq 'login2') {             $self->{auth} = $r->result->{auth};         }     }     return $r; }  sub AUTOLOAD {     my $self = shift;     my $f = $AUTOLOAD;     $f =~ s/.*:://;     return if $f eq 'DESTROY';     return call($self, $f, @_); } 

Normal use of the Perl SOAP::Lite module looks like this:

my $mgsi = new SOAP::Lite     -> uri('urn://ud.com/mgsi')     -> proxy(address); 

To use the MgsiAuthenticator? layer, change this as follows:

my $mgsi = *new MgsiAuthenticator(* new SOAP::Lite     -> uri('urn://ud.com/mgsi')     -> proxy(address) *)*; 

When calling MGSI functions using this class, do not include the first auth parameter. This parameter will automatically be added by the MgsiAuthenticator? class.

C++

C++ does not offer standard support for SOAP, so we have provided a helper library that uses the third party EasySoap++ library for communications. This helper library takes care of the details of interfacing with the EasySoap? library, and provides a C++ interface to MGSI.

Experience has shown that it is sometimes difficult to set up a build environment that correctly compiles and links all the required C++ code. Although the C++ interface library is supported, another option such as Java might be a better choice.

The udmgsi library interface is provided in two header files:

#include  #include  

The MgsiClient? class is constructed with a factory method. It is destroyed with a call to the standard C++ delete operator.

static MgsiClient *MgsiClient::create(const char *url);

The MgsiClient? class provides two management methods:

// Get the current authentication token std::string getAuthToken() const;  // Get the URL used to initialize this instance std::string getUrl() const; 

There is an automatic retry feature in the udmgsi library. In case of a transient network failure, it will automatically try to contact the server a short time later without returning an exception to the caller. The default number of retries is 3, with a default maximum time between retries of 60 seconds. The following methods modify the retry parameters:

// Set the maximum number of times to retry a failed call. // Use a negative value to indicate infinite retries. void setRetryLimit(int retries);  // Get the current retry limit. int getRetryLimit() const;  // Set the maximum time between retry attempts. bool setRetryDelay(int seconds);  // Get the current maximum retry delay. int getRetryDelay() const; 

Data structures from the MGSI are implemented as C structures, and fields in a MGSI structure are members of these C structures. Arrays are implemented with std::vector. MGSI functions are implemented as member functions of the MgsiClient? class (see mgsi-reference.html for a complete list).

The MgsiClient? functions will throw a MgsiException? exception when a MGSI exception is returned from the server. The Code and String members will be filled with the numeric error code and a descriptive error message. You should be sure to catch these exceptions, because an uncaught exception in C++ will cause an immediate program abort.

When a connection is lost, either due to SSL keepalive timeouts (in https mode) or transient network errors (in either http or https), EasySoap? will cause a SIGPIPE to be sent to the program. This signal should be ignored when possible. See OIC in UDsdk_v5.4.0/examples/oic/as-cpp for an example of this. Additionally, be sure to set the MgsiClient? retry limit to something greater than zero if you want your program to recover.

Simple code example:

#include "mgsi_client.h"  int main()  {     ud::mgsi::MgsiClient *mgsi = ud::mgsi::MgsiClient::create(         "https://server:18443/mgsi/rpc_soap.cgi"     );      std::string auth = mgsi->login("username", "password");      ud::mgsi::Job myjob;     // Fill in myjob here     ud::uuid job_gid = mgsi->createJob(myjob);      std::vector jobsteps = mgsi->getJobStepsByJob(job_gid);     // Add work here     delete mgsi; } 

The MgsiFileTransfer? class constructor takes an url to the file service and a pointer to an existing MgsiClient? :

MgsiFileTransfer(const std::string &url, MgsiClient *mgsi);

There are two methods for downloading data. One writes data directly to disk, and the other uses a user allocated buffer:

// Only one of "tarfile" or "subfile" can be non-empty at a time. // The file is transfered directly to a file named "file_name". void download_file(const std::string &file_name,                     const std::string &hash,                     const std::string &subfile="",                     const std::string &tarfile="");  // Only one of "tarfile" or "subfile" can be non-empty at a time. // The caller allocates buffer, which must be at least len bytes. void download_data(char *buffer,                     size_t len,                     const std::string &hash,                     const std::string &subfile="",                     const std::string &tarfile=""); 

The difference between tarfile and subfile is that subfile will look in the pmf.xml for files and possibly uncompress it, whereas tarfile will just obtain the file directly from the tarball. For example, if you have a pmf.xml line like:

then you can retrieve the compressed foofile.bz2 through the tarfile option, and the uncompressed foofile through the subfile option. The tarfile option is particularly useful for retrieving the pmf.xml file itself.

The methods for uploading return a Response struct with the hash of the data and its size.

struct Response {     std::string hash;     off_t size; };  // Reads from a file named "file_name". Response upload_file(const std::string &file_name, const std::string &hash = "");  // Reads "len" bytes from "buffer". Response upload_data(const char *buffer, size_t len, const std::string &hash = ""); 

The "hash" parameter is the SHA1 of the uploaded file. Normally you can leave this empty and the file server will automatically compute the hash and return it in the response. If you already know the hash, passing it here will help ensure that the file arrives intact at the server.

If you specify a hash value that does not match that of the file being uploaded, one of two things will happen:

1. If the file server does not already have the file, the file will be uploaded and the hash checked. The hash will not match, so the server will return an error and will not accept the file.
2. If the file server already has a file identified by the given hash, then the server will return success before the actual file data is uploaded. In this case the server does not have an opportunity to check the file hash.

Due to this behaviour, the caller must either ensure that the specified hash actually matches the file being uploaded, or omit the hash and let the server compute it. The optional ability to specify the hash is provided as a way for the server to avoid the file transfer overhead if the server already has the file.

Building SDK Examples

Prerequisites

The following versions of software packages are the minimum required:

• Java version 1.4.1
• .NET SDK version 1.1
• Perl version 5.6.1
• gcc version 3.2
• GNU make (some OS-supplied make programs, such as the one supplied with AIX, are not sufficient)

Configuration

All the SDK example programs are supplied with 'make' scripts that automate the building process for each example. Since many of the build steps refer to files in other directories in the SDK, the environment variable UD_SDK_HOME is used to indicate where the root of the SDK is. For example, if the SDK is extracted into /home/mpuser (Linux) or c:\home\mpuser (Windows), then the UD_SDK_HOME environment variable would be set as follows:

Linux:

export UD_SDK_HOME=/home/mpuser/UDsdk_v5.4.0

Windows:

set UD_SDK_HOME=c:\home\mpuser\UDsdk_v5.4.0

The next step needs to be done for non-Windows platforms only. There is a setup.sh script that creates symlinks for platform-specific versions of precompiled binaries.

Linux:

cd $UD_SDK_HOME sh setup.sh

The next step is to build the third-party libraries included in the SDK. To do this, change to the 'external' directory and run:

Linux:

cd $UD_SDK_HOME/external sh build.sh

Windows:

cd %UD_SDK_HOME%\external build.cmd

This step may take a few minutes and will build the necessary third-party libraries. The last line printed should be: external build successful.

The next step is to build the udmgsi library (this is only required if you intend to use C++ examples). Change to the 'mgsi/cpp' directory and run:

Linux:

cd $UD_SDK_HOME/mgsi/cpp sh build.sh

Windows:

cd %UD_SDK_HOME%\mgsi\cpp build.cmd

If all goes well, the libudmgsi.so or udmgsi.dll library will be installed in mgsi/cpp/lib. On Windows, a udmgsid.dll debug version of the library will also be built, which will be required when building a debug version of an application that uses this library.

Upgrading

Each release of the Grid MP platform comes with a new SDK. Because new features are added in each release, MGSI structures and functions are subject to change. SDK releases are not binary compatible with one another, that is, it is not possible to simply replace the binary SDK components (udmgsi.dll, udmgsi.jar) with a new version without also recompiling source code that uses these libraries.

The Grid MP Server components can usually be upgraded without affecting existing MGSI client programs. However, occasionally there may be major changes to the server that require changes to the client programs. Such changes will be clearly announced.

When upgrading a client program to a newer version of the SDK, the client program must be recompiled. Every effort is made to ensure source compatibility so that source changes are not required.

The OIC Example

All the functionality of the examples are based around the Ordered Item Count (OIC) application. OIC is a simple application designed to illustrate most of the aspects of developing distributed applications for the Grid MP platform.

OIC accepts a text file as input, and counts the number of times each word occurs in the input file. The output is a list of all words encountered in the input file, with the number of times each word is seen, sorted by frequency. To demonstrate workload splitting, a large text file can be split into smaller fragments, each fragment processed on a separate device, and the result combined later after each fragment has been processed. Additionally, an exclusion list allows selected words to be omitted from the count.

The postprocessing functionality demonstrates how the MGSI is used to submit work into the system and retrieve results.

OIC Program Module

The OIC program module is the core of the OIC functionality. It is an executable program that accepts its arguments on the command line, reads its input from disk files, and writes its output to a disk file. It performs the work of tokenizing the input file into individual words and counting the number of times each word occurs.

The general command line format of the OIC program module is:

oic textfile outputfile exclusionsfile [sleep [-r]]

The input file 'textfile' is the file containing text whose words will be counted. The output file 'outputfile' is the file where the output will be written. The file 'exclusionsfile' is a list of words, one to a line, that will be excluded from the final count. The 'sleep' parameter is the number of seconds to wait between lines of the input file. The '-r' option reverses the sense of the exclusion file, so that it becomes an inclusion file and only the words appearing in that file will be counted.

OIC Application Service

The OIC application service manages the submission of work into the system, splitting of input files into smaller workunits, collection of results, and combining of result files.

The example application services are in two parts - submitjob and retrievejob. The submitjob portion reads the input file, and splits it into smaller files for each device to work on. A job is created to represent the work needed by a single large input file. Each portion of the input file is created as an individual workunit inside the job. The retrievejob portion gets the results for each workunit within the job, and assembles a single output file. This output file represents the same output file that would be produced by a single run of oic against the original input file.

Each workunit consists of a portion of the original input file, plus the complete exclusion list.

OIC Program Module

There are three different versions of the OIC program module in the SDK examples. Two of them are the same program implemented in different programming languages: C++ and C#. The third is a C++ example that uses the Message Passing Interface (MPI) for parallel computation.

C++

The C++ implementation of OIC is found in the examples/oic/program/cpp directory. To build this example, change to the examples/oic/program/cpp directory and run:

Linux:

cd $UD_SDK_HOME/examples/oic/program/cpp make -fMakefile.gcc

Windows:

cd %UD_SDK_HOME%\examples\oic\program\cpp nmake -fMakefile.vc

Cygwin:

cd $UD_SDK_HOME/examples/oic/program/cpp make -fMakefile.cyg

This will make the file "oic-module" (or "oic-module.exe") which is the program module ready for uploading into the platform.

C# .NET

The C# implementation of OIC is found in the examples/oic/program/dotnet directory. To build this example, change to the examples/oic/program/dotnet directory and run:

Windows:

cd %UD_SDK_HOME%\examples\oic\program\dotnet nmake

This will make the file "oic_wrapped_dotnet.exe" which is the program module ready for uploading into the platform.

MPI

The MPI implementation of OIC is also found in the examples/oic/program/cpp directory. Before building this program, your PATH environment variable must include the directory containing the mpiCC compiler. For example,

Linux:

export PATH=/usr/local/UD/mpich/bin:$PATH

Windows:

set PATH=c:\mpich\bin;%PATH%

To build this example, change to the examples/oic/program/cpp directory and run:

Linux:

cd $UD_SDK_HOME/examples/oic/program/cpp make -fMakefile.gcc oic-mpi

Windows:

cd %UD_SDK_HOME%\examples\oic\program\cpp nmake -fMakefile.vc oic-mpi.exe

This will make the file "oic-mpi" (or "oic-mpi.exe") which is suitable for use with ud_mpirun.

OIC Application Service

There are four different versions of the OIC application service in the SDK examples. They are implemented in three different programming languages: C++ (command line), C++ (MFC), Java, and Perl.

Java

The Java application service implementation is found in the examples/oic/appserv/java directory. To build this example, change to the examples/oic/appserv/java directory and run:

Linux:

cd $UD_SDK_HOME/examples/oic/appserv/java make

Windows:

cd %UD_SDK_HOME%\examples\oic\appserv\java nmake -fMakefile.win32

The Java MGSI library uses the Axis library, which uses the standard Java HTTP classes. When connecting to an HTTPS server with SSL, the Java HTTP classes require that the server certificate be trusted in order to connect successfully. This certificate must be imported into a local "keystore" file. To do this, execute a command such as the following:

Linux:

keytool -import -alias mpserver -file /usr/local/UD/inetpub/etc/ssl/crt/mpservice.crt -keystore ~/.cacerts     [ enter any password to create a new keystore file ] 

Windows:

[ copy mpservice.crt file from MGSI server computer ] keytool -import -alias mpserver -file mpservice.crt -keystore cacerts     [ enter any password to create a new keystore file ] 

The cacerts (or ~/.cacerts for Linux) file will now contain a trusted copy of the server certificate. The oic script will use this file when connecting to the HTTPS server so that the connection will succeed.

Note that in order for the connection to succeed, the address used by the client must match the DNS name of the server computer. This means that the client should not be configured to use an IP address (for example, https://192.168.0.1:18443/mgsi/rpc_soap.cgi), but should use a specific DNS name instead (for example, https://mgsiserver.grid.example.com/mgsi/rpc_soap.cgi).

To execute the oic sample, change to the examples/oic/appserv/java directory and run:

Linux:

./oic SubmitJob ./oic RetrieveJob 

Windows:

set OIC_CERTFILE=\path\to\cacerts oic SubmitJob oic RetrieveJob 

C# .NET

The C# application service implementation is found in the examples/oic/appserv/dotnet directory. To build this example, change to the examples/oic/appserv/dotnet directory and run:

Linux:

cd $UD_SDK_HOME/examples/oic/appserv/dotnet make -fMakefile.mono

Windows:

cd %UD_SDK_HOME%\examples\oic\appserv\dotnet nmake -fMakefile.win32

For Windows platforms, the use of the Microsoft .NET SDK is recommended. For non-Windows platforms, the use of the mono .NET framework is recommended. Note that mono is a product that is in continuing development, and we have experienced occasional difficulties using mono in automated test environments (it may hang for no apparent reason). Although mono is useful for development, we do not recommend using it in a production environment at this time.

To execute the oic sample, change to the examples/oic/appserv/dotnet directory and run:

Linux:

mono SubmitJob.exe mono RetrieveJob.exe 

Windows:

SubmitJob RetrieveJob 

Perl

The Perl application service implementation is found in the examples/oic/appserv/perl directory. To run this example, change to the examples/oic/appserv/perl directory and run:

Linux:

cd $UD_SDK_HOME/examples/oic/appserv/perl perl oic-submitjob.pl perl oic-retrievejob.pl 

Windows:

cd %UD_SDK_HOME%\examples\oic\appserv\perl perl oic-submitjob.pl perl oic-retrievejob.pl 

C++ (command line)

The C++ command line application service implementation is found in the examples/oic/appserv/cpp directory. To build this example, change to the examples/oic/appserv/cpp directory and run:

Linux:

cd $UD_SDK_HOME/examples/oic/appserv/cpp make -fMakefile.gcc

Windows:

cd %UD_SDK_HOME%\examples\oic\appserv\cpp nmake -fMakefile.vc

This example requires the use of shared libraries at runtime. To run this executable, use:

Linux:

export LD_LIBRARY_PATH=$UD_SDK_HOME/external/install/lib:$UD_SDK_HOME/mgsi/cpp/lib ./oic-submitjob 

Windows:

set PATH=%UD_SDK_HOME%\mgsi\cpp\lib;%PATH% oic-submitjob 

C++ (MFC)

The C++ MFC application service implementation is found in the examples/oic/appserv/mfc directory. To build this example, change to the examples/oic/appserv/mfc directory and run:

Windows, MSVC 6:

cd %UD_SDK_HOME%\examples\oic\appserv\mfc msdev gui.dsp /make

Windows, MSVC 7:

cd %UD_SDK_HOME%\examples\oic\appserv\mfc devenv gui.dsp     [ follow the prompts to convert the project, then exit devenv and save the gui.sln file when prompted ] devenv gui.sln /build release 

For the real work, the GUI delegates the work to the oic-retrievejob.exe and oic-submitjob.exe (SDK location UDsdk_v5.4.0\examples\oic\appserv\cpp). Their location, and several other parameters, must be set through environment variables prior to launching the oicgui.exe executable. These environment variables are:

oic_submit_exe

specified the location fo the oic-submitjob.exe utility (defaults to .\oic-submitjob.exe)

oic_retrieve_exe

specified the location fo the oic-retrievejob.exe utility (defaults to .\oic-retrievejob.exe)

buildpkg

specifies the location of the buildpkg.exe utility (defaults to .\buildpkg.exe)

Also, for execution, the udmgsi.dll library must be present in either the directory where oicgui.exe is located, or in a directory in the %PATH%.

Start the GUI by typing "oicgui.exe".

Fill out the correct MGSI constants, such as rpc url, fileserver url, username and password. Then click "Login".

If the login was successful, the Application pulldown list will contain all applications in your Grid MP installation.

You can now Submit a job by filling out the relevant fields in the 'Submit Job' area, and press submit. At that point, control will be passed to the oic-submitjob.exe utility, and its output will be displayed in a window.

You can monitor jobs and retrieve the results for jobs through the "Monitor Jobs" area. Click "Update now" to refresh the list of jobs for your application, or click "Start" to automatically refresh the list. Highlight a job and click "View" to retrieve the results for that job and display them in notepad.exe. Highlight a job and click "Delete" to delete that job.

Clicking "Exit" will exit the GUI Application.

• appdev-guide.pdf: Application Developer's Guide

• appuser-quickguide.pdf: Application User's Quick Guide

• mgsi-reference.html: MGSI Reference

• TestAgent.html: Test Agent