= Wrapper Script Basics = Topics covered: 1. What is a Wrapper Script? 2. Basic Format of a Wrapper Script. 3. Hands On Example 4. Wrapper Script Examples == What is a wrapper script? == A wrapper script is a file used to process the data traveling between the Rappture GUI and the science portion of a project. Most applications do not need a wrapper script because the Rappture libary calls can be embedded directly into the source code, yet still separate from the science code. Typically, wrapper scripts are written in a scripting language such as Tcl, Python, or Perl. Here are a few cases when you should consider using a wrapper script instead of embedding the Rappture library calls into the source code: 1. If the code is considered a legacy application where there is little new development and it just needs a graphical user interface. 2. If the original source code is considered an industry standard and there is no advantage to changing it. 3. You do not have access/permission to the original source to add Rappture library calls If your project is still under development or otherwise does not fit into one of the previously definded conditions, you should seriously consider embedding the library calls into your application. == Basic Format of a Wrapper Script == Generally wrapper scripts are written in a scripting language such as Tcl, Python, or Perl. This is because scripting languages make it easy to do string manipulation, external application calls, and creation of files. While these activities can be done in languages like C/C++ or Fortran, its just easier and more convenient to use a scripting language. If you don't know a scripting language, then this is an excellent time to learn one. Tcl, Python and Perl are all pretty easy to learn and understand, especially if you already know another programming language. All wrapper scripts follow the same basic format: 1. Open a Rappture library object by sending it an xml file 2. "get" inputs that the user specified, from the Rappture object 3. Create an input file for your science code 4. Call your science code 5. Parse the output files from the science code 6. "put" the interesting output back into the Rappture library object 7. Call the result function to tell Rappture graphical user interface that the wrapper script is complete. Let's take a closer look at some examples of what each step would look like in Tcl and Python code. || Step || Explanation || Tcl Example Code || Python Example Code || || 1 || Here we open the Rappture library with the first command line argument || '''set opt [Rappture::library [lindex $argv 0]]''' || '''lib = Rappture.library(sys.argv![1])''' || || 2 || Pay attention to all lines that use the "get" function. They are grabbing information from the Rappture library. If you are confused by the path argument (the input.blah stuff) check out our page on [wiki:FAQ_XmlPathNames Reading XML Paths] || '''$opt get input.(structure).(p_node).current''' || '''inputType = lib.get('input.loader.current')''' || || 3 || Look for the appending of information to a variable, and the writing of variables to files || '''append deck ...''' [[BR]] '''set deckfile "pdr[pid]"''' [[BR]] '''set fid [open $deckfile w]''' [[BR]] '''puts $fid $deck '''[[BR]] '''close $fid''' || '''outFileName = 'inputDeck.' + getDriverId(inDeckName)''' [[BR]] '''fh = open(outFileName, 'w')''' [[BR]] '''if fh != None:''' [[BR]] '''fh.write(writeData)''' [[BR]] '''fh.close()''' || || 4 || Look for the Rappture::exec call. That is how to execute external programs in Tcl || '''set status [catch {Rappture::exec $program $deckfile} out]''' || '''dirpath = os.path.dirname(sys.argv![0])''' [[BR]] '''Rappture.tools.getCommandOutput('%s/sineIt.py %s' % (dirpath,outFileName))''' || || 5 || Generally the code right after the Rappture::exec function call deals with parsing the output || ?? || ?? || || 6 || Anywhere you see the "put" function being used, you know we are trying to put information back into the Rappture library. || '''$opt put output.log $out''' || '''lib.put('output.curve(sin_data).about.label','sin curve')''' || || 7 || This line tells the rappture graphical user interface that the wrapper script has completed and that it can start rendering plots. Sometimes in old tcl scripts you see a line like this: [[BR]] puts "=RAPPTURE-RUN=>$oname" [[BR]] This is the old way to end a program and should not be used. || '''Rappture::result $opt $status''' || '''Rappture.result(lib)''' || Note that in the Python example code, two user defined functions were used: ''getDriverId(...)'' and ''getCommandOutput(...)''. These functions are not currently part of the Rappture distribution and the code for these functions can be found in the python example wrapper script provided in the link below. Check out the Wrapper Script Examples listed below. While examining each script, try to find where the developer takes care of each step listed above. == Hands On Example == == Wrapper Script Examples == There are a number of previously written wrapper scripts you can look at or use as a starting place for your own script. Check out these examples from other projects: 1. [https://developer.nanohub.org/projects/app-molctoy/file/trunk/rappture/molcwr MolCToy Wrapper Script] (tcl) 2. [https://developer.nanohub.org/projects/app-pntoy/file/trunk/rappture/padrewr Padre Wrapper Script] (tcl) 3. [https://developer.nanohub.org/projects/app-cntbands/file/trunk/rappture/cntbandswr CNTBands Wrapper Script] (tcl) 4. [wiki:FAQ_LoaderUpDownload Rappture Upload Wrapper Script Example] (python) [wiki:FAQ Back to Frequently Asked Questions]