Setting up DXLMagic to run from the command line

It is a little hidden in the slide deck. These are the steps for setting up the DXLMagic environment to be useable. You need to replace [AppDir] with the path to your Notes application (typically something like C:\Notes, C:\Program Files\IBM\Lotus Notes, /applications/lotus/notes or /opt/ibm/lotus/notes, depending on your platform. You also will need to set [DataDir]: the place where your nsf live and [JarDir] where you copied the DXLMagic.jar file (can be in the Notes directory, up to you). So here are the steps:

1. Install and configure Java 6 (It should work with Java 5, but I haven't tested it)
2. Copy the DXLMagic.jar file into the [JarDir]
3. Edit your environment to include Notes on the path and the Jar files on the classpath and add an environment parameter LD_LIBRARY:
   • Windows: notepad c:\autoexec.bat and add these lines:
     SET PATH=%PATH%;[AppDir]
     SET CLASSPATH=.;[AppDir]\jvm\lib\ext\*;[JarDir]\DXLMagic.jar
     SET LD_LIBRARY=[AppDir] (Reminder: if you have spaces in your path you need to put the path in quotes)
   • Linux: sudo nano /etc/environment and add/edit these lines:
     PATH="[whatever was there]:[AppDir]"
     CLASSPATH=".:[AppDir]/jvm/lib/ext/*:[JarDir]/DXLMagic.jar"
     LD_LIBRARY="[AppDir]"
   • Mac: vi ~/.profile and add/edit these lines:
     export DYLD_LIBRARY_PATH=[AppDir]/Contents/MacOS (where AppDir is going to look something like: /Applications/Notes.app)
     export CLASSPATH=$CLASSPATH$:.:[AppDir]/Contents/MacOS/jvm/lib/ext/*:[JarDir]/DXLMagic.jar"
     (Thx Luis)

Update: Fixed the classpath to ...ext/*
Now you are ready to go. Lets have a look at the available commands.You invoke all of them from the command line: java [name of the command] [parameters]. All commands use at least one parameter. Directories need to have the trailing (back)slashes.

• com.ibm.sg.dxlmagic.DesignExporter [Outputpath including trailing / or \] [PathToDatabase relative to the data directory] [optional server]
  Exports the entire design of a database into one DXL file in the working directory (some path stuff needs fixing, so it might end-up somewhere else ). Depending on your template you might get some interesting error messages or even a JVM crash.
• com.ibm.sg.dxlmagic.DesignExtractor [Path to DXL file] [Outputpath including trailing / or \] [PathToCommandFile]
  Takes an exported DXL file and extracts elements you are interested in. Ability to split into multiple files. The command file determines what should happen. The format of the command file is easy: a # sign is a comment, other lines need to have a structure: [output file name],[Mode: sinlge|multiple],[XPath expression e.g. /d:database/d:form for all forms. Typically you use the extractor to create working files to later be used in the DesignInjector.
• com.ibm.sg.dxlmagic.DesignImporter [PathToSource.dxl] optional [create] to create a new nsf (aborts if one exists) optional [smart] to import only design elements that have changed from the existing ones. optional [single] import elements one by one. If one fails the others still get imported.
  Imports a DXL into an existing or new NSF. When smart or single is selected failing elements will not prevent the whole operation from failing. LotusScript does*not* get recompiled. I recommend to use a compile all to be sure everything is fine.
• com.ibm.sg.dxlmagic.DesignInjector [PathToCommandFile] [PathToNsf relative to data directory] [Path to directory with source files to be injected]
  Takes snippets of code an injects them into an existing database. The database must be local. Injection is smart and only updates design elements that have been changed. all commands in a command file are executed before the result is written back. LotusScript is not recompiled. The injector uses the DesignExporter and DesignImporter to read/write nsf. Structure of a command file: # is a comment line, no inline comments possible. [FileName for Snippet to insert relative to Path given above], [Insertion Method], [XPath Expression]. The insertion methods are:
  • BEFORE: Adds the fragment as sibling before each node found by the XPath expression.
  • AFTER: Adds the fragment as sibling after each node found by the XPath expression.
  • REPLACE: Replaces each node found by the XPath expression with the fragment.
  • FIRSTCHILD: Adds the fragment as first child of each node found by the XPath expression.
  • LASTCHILD: Adds the fragment as last child of each node found by the XPath expression.
  • REMOVE: Ignores the content in the fragment file and removes each node found by the XPath expression.
  • BEGINNING: Adds the text content of the file into the text of each node found by the XPath expression at the beginning. Used for LotusScript insertion. Takes care of Sub/Function at the beginning.
  • END: Adds the text content of the file into the text of each node found by the XPath expression at the beginning. Used for LotusScript insertion. Takes care of End Sub/End Function at the end.
  The injector executes the XPath and inserts the code based on the insertion method chosen. Except for LotusScript code snippets the source file needs to contain a valid XML fragment (most likely created by the DesignExtractor and then edited/transformed).
• com.ibm.sg.dxlmagic.TransformXML [SourceXMLFile] [StyleXSLTFile] [TargetFile] optional [parameter=value] ...
  Runs an XSLT transformation.
• com.ibm.sg.dxlmagic.DocumentServer [OutputPath with trailing / or \ ] [ServerName (Use "local" for local)]
  Exports all databases that are a template or that don't have a template specified. Runs the DocumentDesignTags and DocumentDesignMetrics to generate a CSV file for estimation of spent effort of any given environment.
• com.ibm.sg.dxlmagic.ViewTuner [Path To Nsf relative to data directory] (coming soon)
  Executes a radical simplification of view selection formulas into "fieldname=1" and injects subform, agent and script library to keep documents updated. A separate article will describe that in detail.

More details and XSLT stylesheets will follow soon.