.:idlwrapper:home

From ADPAA
Jump to navigation Jump to search

IDL Virtual Machine Wrapper Setup

This procedure can be used to make *.sav files from SODA IDL code so that they can be run using the IDL virtual machine without an IDL license.

These files can be found in ${ADPAA_DIR}/src/linkage_soda. Each project will have its own directory, hereafter referred to as script_name. The name of the script that runs this code generally matches the name of this directory. This directory will contain the following files (some of which will need to be created): script_name (a bash script that can be used to run the IDL code, whether in licensed IDL or the IDL virtual machine), script_name_compile.idl, script_name_recompile.idl, create_script_name_sav_file, create_script_name_sav_file.idl, and any *.pro files that are used in the execution of the program, including the start script that is generally named start_script_name.pro and any modules specifically needed for the execution of this program.

The .pro files should not need to be modified, but the other programs will be need to be edited as described below. The Makefile in ${ADPAA_DIR}/src/build will also need to be modified. Example templates for each program are also provided. Further examples can be obtained from imagedump or calc_spectra_parameters in src/linkage_soda.

script_name

The general format of this script is as follows: 

 Syntax message
 Check for command line arguments
 Determine which version of IDL to run and run the program

The primary edits to this file are as follows:

  • If necessary, add the virtual machine option to the syntax message. Example Syntax message:
 Syntax ()
 {
   echo 'SYNTAX: script_name [-h] [--verbose] [-vm] other_args'
   echo 
   echo ' Purpose: to make statistics about the lwc and largest particle size in the spectra '
   echo '   for the given time period. '
   echo 
   echo ' spec_file    - file containing the spectra for the parameters to be computed from.'
   echo ' verbose (-v) - keyword to print out auxillary runtime information to the screen.'
   echo ' -V           - No output (verbose=0).'
   echo ' -vm          - Execute code using IDL virtual machine.'
   echo 
   echo '  System Variables: '
   echo '  verbose_mode     - Set equal to 1 to use verbose output.'
   echo '  virtural_machine - Set equal to 1 to use the IDL virtual machine.'
 }
  • If necessary, add a check for -vm in the command line argument check.
 # Get the current working directory.
   currentdir=`pwd`
 # Redefine to use \ as escape characters for all spaces.
   directory=`echo "${currentdir// /\\ }"`
 # Define variables incase envirnmental variables are not set.
   if [ "${verbose_mode}" = "" ]; then
     verbose_mode=0
   fi
   if [ "${virtual_machine}" = "" ]; then
     virtual_machine=0
   fi
 if [ $# -gt 0 ]; then
   for index in "$@"; do
     # Need the "$index" to make sure we are not talking about a file (.i.e -d)
       if [[ "$index" == "help" || "$index" == "h" || "$index" == "-h" || "$index" == "-help" || "$index" == "--help" ]]; then
         Syntax
         exit 0
       fi
     if [ "$index" == "-nvm" ]; then
       virtual_machine=0
     fi
     if [ "$index" == "-V" ]; then
       verbose_mode=0
     fi
     if [[ "$index" == "verbose" || "$index" == "-v" || "$index" == "-verbose" || "$index" == "/verbose" ]]; then
       verbose_mode=1
     fi
     if [ "$index" == "-vm" ]; then
       virtual_machine=1
     fi
     if [ "$index" == "--compile" ]; then
       virtual_machine=0
     fi
   done
 else
   echo "Invalid number of arguments"
   Syntax
   exit 1
 fi
  • Create a variable with the command line arguments so they can be used by the IDL program
 # Store passed arguments in the IDL_ARG environmental variable so they can be used later.
   IDL_ARG="directory = ${directory} $@"
   export IDL_ARG
  • Check if Xvfb and xte are installed and, if so, run the no-click option (this can be combined with the following step).
  • Add an if-else block to decide whether to run the .sav file in the virtual machine or to use the licensed IDL code.
 # Compile the IDL code before running.
   if [ $verbose_mode -eq "1" ]; then
     if [ $virtual_machine -eq "1" ]; then
       if [ -e "/usr/bin/Xvfb" ] && [ -e "/usr/bin/xte" ] && [ "${png}" = "1" ]; then
         # Don't want to use noclick if not in text mode.
         # Text mode requires more than 1 parameter.
         if [ $# -gt 1 ]; then
           noclick_idlvm $ADPAA_DIR/sav/script_name.sav 10 0 1
         else
           idl -vm=${ADPAA_DIR}/sav/script_name.sav
         fi
       else
         idl -vm=${ADPAA_DIR}/sav/script_name.sav
       fi
     else
       idl ${ADPAA_DIR}/src/linkage_soda/script_name/script_name_compile.idl 
     fi
   else
     if [ $virtual_machine -eq "1" ]; then
       if [ -e "/usr/bin/Xvfb" ] && [ -e "/usr/bin/xte" ] && [ "${png}" = "1" ]; then
         # Don't want to use noclick if not in text mode.
         # Text mode requires more than 1 parameter.
         if [ $# -gt 1 ]; then
           noclick_idlvm $ADPAA_DIR/sav/script_name.sav 10 0 1
         else
           idl -vm=${ADPAA_DIR}/sav/script_name.sav >& /dev/null
         fi
       else
         idl -vm=${ADPAA_DIR}/sav/script_name.sav >& /dev/null
       fi
     else
       idl ${ADPAA_DIR}/src/linkage_soda/script_name/script_name_compile.idl >& /dev/null
     fi
   fi
  • Exit the program.
 # Exit the program and return error 
   exit ${status}

script_name_compile.idl

The general format of this script is as follows:

  • Modify the path to include the locations of any needed IDL modules (at the very least, this likely includes the current directory, linkage_soda/linkage_lib, and possibly src/idl_lib)
 ADPAA_Path = STRSPLIT(GETENV('ADPAA_DIR'), ' ',/EXTRACT)
 CoPAS_Path = STRSPLIT(GETENV('CoPAS_DIR'), ' ',/EXTRACT)
 !path = expand_path(ADPAA_Path + '/src/linkage_soda/script_name') + ':' + $
         expand_path(ADPAA_Path + '/src/linkage_soda/linkage_lib') + ':' + $
         expand_path(ADPAA_Path + '/src/idl_lib') + ':' + $
         expand_path('/usr/local/soda2/trunk/script_name/') + ':' + $
         expand_path(CoPAS_Path + '/SODA') + ':' + !path
  • Compile the recompile files (@script_name_recompile.idl, @soda_recompile.idl, etc.)
 @constants_recompile.idl
 @script_name_recompile.idl
 @soda_recompile.idl
  • Call the .pro file that starts the program
 START_SCRIPT_NAME
  • Exit from IDL
 exit, STATUS=!ERROR_STATE.CODE

script_name_recompile.idl

The general format of this script is as follows:

  • Compile the main program and any other needed modules (.rnew is preferred over .compile, although either can be used)
 .rnew start_script_name
 .rnew script_name

create_script_name_sav_file.idl

The general format of this script is as follows:

  • Modify the paths as in script_name_compile.idl
 ADPAA_Path = STRSPLIT(GETENV('ADPAA_DIR'), ' ',/EXTRACT)
 CoPAS_Path = STRSPLIT(GETENV('CoPAS_DIR'), ' ',/EXTRACT)
 !path = expand_path(ADPAA_Path + '/src/linkage_soda/script_name') + ':' + $
         expand_path(ADPAA_Path + '/src/linkage_soda/linkage_lib') + ':' + $
         expand_path(ADPAA_Path + '/src/idl_lib') + ':' + $
         expand_path(CoPAS_Path + '/SODA') + ':' + !path
  • Compile the IDL recompile modules
 @script_name.idl
 @soda_recompile.idl
  • Optional secondary check to make sure all routines have been compiled.
 RESOLVE_ALL,/CONTINUE_ON_ERROR
  • Save the binary code.
 SAVE,/ROUTINE,FILENAME="script_name.sav"
  • Exit from IDL
 IF (!VERSION.OS_FAMILY EQ 'unix') THEN exit

create_script_name_sav_file

The general format of this script is as follows:

  • Syntax message
 Syntax ()
 {
   echo 'SYNTAX:  create_script_name_sav_file'
 }
  • Check for command line arguments
 if [ $# -gt 0 ]; then
   for index in "$@"; do
     # Need the "$index" to make sure we are not talking about a file (.i.e -d)
       if [[ "$index" == "help" || "$index" == "h" || "$index" == "-h" || "$index" == "-help" ]]; then
         Syntax
         exit 0
       fi
   done
 fi
  • Create a variable with the command line arguments so they can be used by the IDL program
 IDL_ARG="$@"
  • Run the IDL code that creates the .sav file
 idl $ADPAA_DIR/src/linkage_soda/script_name/create_script_name_sav_file.idl
  • Exit the program
 # Exit the program.
 exit 0

Makefile

In ${ADPAA_DIR}/src/build/Makefile, add the following lines in the target install_linkage_soda (make sure that the white spaces are tabs): 

 	cd $(BASEDIR)/linkage_soda/script_name && $(BASEDIR)/linkage_soda/script_name/create_script_name_sav_file
 	install $(INSTOPT) $(BASEDIR)/linkage_soda/script_name/script_name.sav $(PREFIX)/sav/script_name.sav

Testing and Committing Changes

If possible, add the data used to test the file to the ADTAE repository. Once the code has been tested, add any new files to ADPAA, and commit the changes with SVN.

IDL Wrapper Code

To produce a wrap around code it is necessary to identify which program is being modified to produce the new program. For simplicity and the sake of this example, assume the program being modified is old_program and the program being produced is titled new_program.

  • Create directory for new_program.
        ex. mkdir /usr/local/ADPAA/Level_2/new_program
  • Copy all needed files from old_program into the new_program directory. Files of particular interest are:
 old_program
 old_program_compile.idl
 old_program_recompile.idl 
 start_old_program.
  • The old_program file must be modified.
  1. Make sure the name of the copied file is changed to new_program.
  2. Edit new_program by changing all instances of old_program to new_program.
  3. Modify the new_program comment section and meta-data appropriately.
  4. Make sure the code calls new_program_compile.idl
  • Create new_program_compile.idl
  1. Copy old_program_compile.idl to new_program directory and rename it.
    * ex. cp /usr/local/ADPAA/src/Level2/old_program/old_program_compile.idl/usr/local/ADPAA/src/Level2/new_program/new_program_compile.idl
  2. Edit new_program_compile.idl using the same directions followed previously in step 2 of modifying old_program.
  3. Edit new_program_compile.idl comments and header information appropriately.
  4. Make sure the code calls new_program_recompile.idl and START_NEW_PROGRAM.
  • Modify new_program_recompile.idl
  1. Copy old_program_recompile.idl to new_program directory and rename it.
    * ex. cp /usr/local/ADPAA/src/Level2/old_program/old_program_recompile.idl/usr/local/ADPAA/src/Level2/new_program/new_program_recompile.idl//
  2. Modify code by changing instances where old_program exists with new_program.
  3. This specific subroutine is responsible for compiling all IDL code used by the new_program.
  4. This subroutine consists primarily of .rnew lines and one .run line. Remove each of them and look in the new_program directory. For every *.pro file, type a .rnew line and list the files alphabetically. Also make sure a .run start_new_program line is present at the end of the program. This will be the next program to be edited.
  • Repeat above procedure regarding the deleting of all instances where old_program appears and change it to new_program. Make sure all files called by START_NEW_PROGRAM are modified appropriately.
  • Test and debug new_program.
Retrieved from "http://adpaa.sourceforge.net/wiki/index.php?title=.:idlwrapper:home&oldid=30524"