Search

Domino Upgrade

VersionSupport end
5.0
6.0
6.5
7.0
8.0
8.5
Upgrade to 9.x now!
(see the full Lotus lifcyle) To make your upgrade a success use the Upgrade Cheat Sheet.
Contemplating to replace Notes? You have to read this! (also available on Slideshare)

Languages

Other languages on request.

Twitter

Useful Tools

Get Firefox
Use OpenDNS
The support for Windows XP has come to an end . Time to consider an alternative to move on.

About Me

I am the "IBM Collaboration & Productivity Advisor" for IBM Asia Pacific. I'm based in Singapore.
Reach out to me via:
Follow notessensei on Twitter
(posts)
Skype
Sametime
IBM
Facebook
LinkedIn
XING
Amazon Store
Amazon Kindle
NotesSensei's Spreadshirt shop
profile for stwissel on Stack Exchange, a network of free, community-driven Q&A sites

15/08/2012

Identifying platform dependent code in your Domino application

QuickImage Category  
Domino runs on many platforms, so you have the freedom of choice what to use. My personal favorite currently is zLinux 64Bit, the mainframe I/O capabilites are delightful. However you might have limited your choices by the way you developed your applications. Luckily LotusScript is case insensitive on all platforms, so you only have to pay attention to pieces of code that interact with the world around you. In specific you need to watch out for:
  • DECLARE: where in LotusScript you refer to OS level DLLs that most likely won't be available on other platforms
  • Execute: There could be anything inside, you don't know
  • Evaluate (and @Eval): Again there could be anything inside
  • SHELL: Executing OS level calls
  • Anything that reads/writes a file: NotesStream, Standard file I/O etc.
  • @DBCommand (and the other @DB functions): When using ODBC that driver must be on the new platform. @DBCommand also allows you to actually call a DLL (a very little known extension point) when you use a keyword other than "Domino" or "ODBC". That DLL needs to be available on the target platform
  • All statements that need attention: ActivateApp, ChDir, ChDrive, CreateObject, CurDir, CurDir$, CurDrive, CurDrive$, Date, Date$, Declare, Dir, Dir$, FileLen, Len, LenB, LenBP, LOF, GetFileAttr, GetObject, Input #, Input, Input$, InputB, InputB$, Line Input, Print, Write #, IsObject, IsUnknown, Open, Lock, Unlock, SendKeys, SetFileAttr, Shell, Time, Time$
Now when you are tasked with evaluating a server move to a different platform, you can use DXLMagic to get an idea how many problem areas you might deal with. These are the steps:
  1. Export your databases using the GUI:
    Export NSF
    Make sure you checked the option "Create metric files"
  2. In your target directory you will find 2 files com.ibm.sg.dxlmagic.DocumentDesignMetrics.properties and com.ibm.sg.dxlmagic.DocumentDesignTags.properties. The first one determines what goes into the CSV file, the second one generates additional tags based on code fragments. You can edit both files and run the extraction from the command line (much faster than the initial export) to get the "how much to pay attention to" report. Edit the com.ibm.sg.dxlmagic.DocumentDesignTags.properties and change it to the following content
    #***** Platform investigation ******
    Declare\ =C_CALL
    ActivateApp=OLE_CALL
    GetObject=OLE_CALL
    CreateObject=OLE_CALL
    IsObject=OLE_CALL
    IsUnknown=OLE_CALL
    ChDrive=DRIVE_OP
    CurDrive=DRIVE_OP
    ChDir=DIR_OP
    CurDir=DIR_OP
    Dir=DIR_OP
    FileLen=FILE_IO
    Len=FILE_IO
    LenB=FILE_IO
    LenBP=FILE_IO
    LOF=FILE_IO
    GetFileAttr=FILE_IO
    SetFileAttr=FILE_IO
    Input\ \#=FILE_IO
    Input=FILE_IO
    InputB=FILE_IO
    Line\ Input=FILE_IO
    Write\ \#=FILE_IO
    Open=FILE_IO
    Lock=FILE_IO
    Unlock=FILE_IO
    NotesStream=FILE_IO
    Print=PRINT
    Date=TIME_OP
    Time=TIME_OP
    Shell=SHELL_CALL
    SendKeys=SHELL_CALL
    @dialogbox=UI_formula
    @prompt=UI_formula
    .dialogbox=UI_script
    as\ notesui=UI_script
    source\ as=UI_event
    @db=DB_formula
    

    Then edit the com.ibm.sg.dxlmagic.DocumentDesignMetrics.properties file and add the new tags (you can keep the existing ones if you want):
    C_CALL
    OLE_CALL
    DRIVE_OP
    DIR_OP
    FILE_IO
    PRINT
    TIME_OP
    SHELL_CALL
    DB_formula
    LOC_formula
    LOC_java
    LOC_javascript
    LOC_lotusscript
    UI_event
    UI_formula
    UI_script
    action
    agent
    button
    column
    field
    form
    formula
    java
    javascript
    lotusscript
    par
    role
    sharedcolumn
    sharedfield
    subform
    view
    

    (you might want to skip the PRINT statement since it is often used in web agents and there nothing is special)
  3. Run DXLMagic from the Command Line to extract and document based on the new property files. The result will be a new CSV file with extra columns
    java com.ibm.sg.dxlmagic.DocumentDesignTags [DirectoryWithTheDXL]
    java com.ibm.sg.dxlmagic.DocumentDesignMetrics [DirectoryWithTheDXL] CsvFileName
Just to be clear: this steps show you how many instances are there, but not where or if changes are required. Most likely all PRINT and @db commands will be just fine. But it is a fast method to get a first impression. Based on the DXL you could devise an XSLT report to show the problem spots in detail.
As usual YMMV

29/07/2009

Self Assessment and Strategy Guide for Migrating from Domino Document Manager

Category
The draft version of the Redbook Self Assessment and Strategy Guide for Migrating from Domino Document Manager has been published. I contributed to the book mainly in Chapter 11. Analyzing Customizations. Part of the effort is an upgrade to DXLMagic which now sports a GUI (build with Thinlet and a module that can compare two Notes database designs, not limited to DDM templates. The comparison report is a start but (for my taste) far from perfect. Give it a spin and compare some databases and let me know in which sequence I should improve what.

25/07/2009

What reports would you like to see in DXLMagic?

Category
The new DXLMagic UI is making progress. One of the features I'm working on are reports included into the JAR file, so you can pick them from the internal list easily. I'm planning to have reports for @Formula, Fields, HideWhen and actions. What reports would you like to see in that list?

17/07/2009

DXLMagic UI coming soon

Category
It has been a while since the last update. There are a number of interesting enhancements coming soon to DXLMagic. While the command line interface is still available for your automation projects there will be a GUI and other enhancements:
DXL Magic has a GUI now
  • GUI for Export, Import, Injection, Reports (Transformation) and Server Documentation
  • Graphical Installer for Windows (Mac/Linux maybe later)
  • A list of build in reports
  • New Function: Compare 2 databases
  • New Function: Brute Force View Tuning (article coming soon)
Stay tuned.

11/04/2009

DXLMagic - using the DesignExtractor

QuickImage Category   
I'll show you to take full advantage of the DXLMagic Tools one post at a time. You have exported your database application using the DesignExporter. Now you can run reports, transform the XML, edit it etc. When you are planning to work on individual element using the full DXL is a bit cumbersome, especially when you plan to write back just some parts of it later on. To split your file into multiple files you use the DesignExtractor. It will extract parts of your DXL based on an XPath expression. If XPath is still a mystery for you, this would be the time for a tutorial, Jeni's Introduction or Michael's Reference. Since you typically want to extract more than one sort of element, DesignExtractor uses a command file with instructions.
The syntax for DesignExtractor is:
java com.ibm.sg.dxlmagic.DesignExtractor [PathToDXL] [ResultPath] [CommandFile]
In the latest version of the DXLMagic.jar I have updated the path parameter, so you now can use "." for the current directory instead of specifying absolute path names. [PathToDXL] must point to a DXL File. I currently don't process all DXL files in one directory (Maybe I should think about such an option), so you have to point it to one DXL file. [ResultPath] is where your individual files go. You will see in a second, that you can specify subdirectories for individual results. The interesting part is the command file. The command file executes one extraction per line (empty lines or line with # at the beginning are ignored) and needs 3 parameters:
  1. File Prefix: The extractor tries to name the file using a name or alias found in the result from the XPath expression. If it can't find something it uses a running number. It appends this to the file prefix. If your file prefix contains a directory separator it will write that file into that subdirectory (and create it if needed). So the full name for any file is composed out of [ResultPath]+[File Prefix]+[Name that the Extractor figured out]. A typical value for File Prefix would be "forms/form"
  2. Export Mode: The extractor can write the result of the XPath expression into one summary file or into one file each for every result node. If you want one summary file you use "summary", for individual files use "single".
  3. XPath expression: The heart of the extractor. An XPath expression is evaluated and returns a note-set. You can do whatever you fancy including using the extractor against other XML files (you might struggle with the name spaces a little bit then). To make your live easier with the XPath, the DXL namespace is abbreviated "d:". Typically you would extract high level elements like forms, views, libraries, agents etc.. However you are not limited to that. You could e.g. extract all fields to feed them into a cross-reference system. Getting started is easy: Extracting all views is this expression "/d:/database/d:view".
The command file you typically will want to use looks like this:
forms/form,single,/d:database/d:form
forms/subform,single,/d:database/d:subform
forms/page,single,/d:database/d:page
misc/frameset,single,/d:database/d:frameset
views/view,single,/d:database/d:view
views/folder,single,/d:database/d:folder
sharedstuff/field,single,/d:database/d:sharedfield
sharedstuff/action,single,/d:database/d:sharedactions
resources/image,single,/d:database/d:imageresource
resources/applet,single,/d:database/d:appletresource
code/agent,single,/d:database/d:agent
code/webservice,single,/d:database/d:webservice
code/scribtlibrary,single,/d:database/d:scriptlibrary
sharedstuff/column,single,/d:database/d:sharedcolumn
misc/outline,single,/d:database/d:outline
code/databasescript,single,/d:database/d:databasescript
misc/helpusingdocument,single,/d:database/d:helpusingdocument
misc/helpaboutdocument,single,/d:database/d:helpaboutdocument
resources/dataconnection,single,/d:database/d:dataconnection
resources/fileresource,single,/d:database/d:fileresource
resources/stylesheetresource,single,/d:database/d:stylesheetresource
resources/db2accessview,single,/d:database/d:db2accessview
Happy extracting. I'll continue that series with some of the stylesheets we have written. Stylesheets are not only good for reports, but also to whip your code into shape. Stay tuned.

20/02/2009

Setting up DXLMagic to run from the command line

Category  
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.

18/02/2009

DXLMagic 0.1 released

Category  
I finally made it. The DXLMagic 0.1 release is available on OpenNTF. It contains the database to generate the job files and the Java executables. I need to cleanup the XSLT stylesheets, they will follow soon.

03/02/2009

AD215 - Slides Online Now

Category  
Also check the project on OpenNTF.

Disclaimer

This site is in no way affiliated, endorsed, sanctioned, supported, nor enlightened by Lotus Software nor IBM Corporation. I may be an employee, but the opinions, theories, facts, etc. presented here are my own and are in now way given in any official capacity. In short, these are my words and this is my site, not IBM's - and don't even begin to think otherwise. (Disclaimer shamelessly plugged from Rocky Oliver)
© 2003 - 2017 Stephan H. Wissel - some rights reserved as listed here: Creative Commons License
Unless otherwise labeled by its originating author, the content found on this site is made available under the terms of an Attribution/NonCommercial/ShareAlike Creative Commons License, with the exception that no rights are granted -- since they are not mine to grant -- in any logo, graphic design, trademarks or trade names of any type. Code samples and code downloads on this site are, unless otherwise labeled, made available under an Apache 2.0 license. Other license models are available on written request and written confirmation.