Menu

Search

« Find and optionally correct erroneous file names on your drive | Main| If you expect mail from Voith's CODE, please ensure vcode.no is allowed in your spam filters whitelist! »

Troubleshooting Import Image 2 Lotus Notes (II2LN) agents on Domino servers

Category Import Image 2 Lotus Notes
This article will teach you how to get Import Image 2 Lotus Notes (II2LN) agents running on your Lotus Domino server
II2LN can run both on Notes clients and on Domino servers. The ability to run II2LN on a server is convenient for reasons such as;
  • You want to use II2LN in your web applications, hosted on your Domino server.
  • You don't want to install II2LN locally on each Notes client for your Notes applications. Central administration of II2LN is ensured
  • You want to be able to process images at non-peak hours
  • You want to batch process huge numbers of images, without locking the users Notes clients for hours
  • You don't want to lock your Notes applications and forcing users to be logged on to process images.

    Below you find a birds-view point-by-point list on what to check in order to get II2LN agents running on a server;
  • Install II2LN on the server. Pay extra attention to the installation if you have multiple Domino server installations on a single server ("partitioned servers") or if you have one or more Notes clients installed on the server. The later was very common some years ago, in order to have a Notes client to perform administration tasks when working on the server. These days, that need is completely gone, as we can do all our administration tasks from the Notes Administrator-client. If you fall into the "old" category ( :-)) and do have a Notes client on the server, you must refer to the User's Guide found on the II2LN homepage. The technical reason for this is that the II2LN components must be installed into specific directories in order to work.
  • Remember that II2LN is a 32-bit component, and thus will only run on 32-bit Domino Servers. This is true even if the 32-bit Domino server runs on a 64-bit Windows OS. Thus II2LN will not run on a native 64-bit Domino server!
  • If you have a server- or site license for II2LN, install that too on the server. The license is delivered as a .reg file and you should verify that it contains two registry hive settings, such as;

    REGEDIT4

    [HKEY_CURRENT_USER\Software\Voith's CODE\Import Image 2 Lotus Notes]
    "Key"="Bla bla super long key here"

    [HKEY_USERS\.DEFAULT\Software\Voith's CODE\Import Image 2 Lotus Notes]
    "Key"="Bla bla super long key here"

    The reason for this is that the first registration key will install the license to the current session, while the second registration key will install the key to the default session, meaning that also that Domino servers running as a NTSERVICE, will pick up the license correctly.

    Remember that II2LN can run on the server without a license, but then all images will be watermarked with the Voith's CODE logo.
  • If you have installed the II2LN on the server, and/or installed the license for the first time, please reboot the server. The reason for this is so the Domino server picks up the correct path settings, and optionally also picks up the license, no matter how the Domino server has been installed. For the really technically savvy Domino administrator, there are ways to avoid a complete reboot, but you really have to know how to stop and restart services and so forth in order to pick up environment settings. It is just easier (and often much quicker) to reboot the server!
  • Create a test database on the server. The idea is to have a database which runs an agent on the server  in order to report back to you whether the II2LN was successful or not.
  • You can name the agent anything you want, in my sample I have called it "Verify II2LN installation on the server".

    A picture named M2

    Ensure that the agent is running on a schedule, and click that Schedule-button  to set the server-name;

    A picture named M3

    Set a schedule you feel comfortable with... and do remember to turn off the agent after you have received your information! You don't want to waste server cycles on a spinning non-important agent!!!
  • Now, you must set the agent's Runtime Security Level, to level 2 or 3. For example;

    A picture named M4

    This is very important, as you agent will need to access the server's local file system in order to load the II2LN DLL file. Without the setting above, your server log will contain entries like this;

    01.10.2009 13:15:13   AMgr: Agent ('Verify II2LN installation on server' in 'Notes data\Projects\Voith's CODE\II2LN\VCIMGLIB2.Nsf') printing: II2LN: INITIALIZE error: 201 Operation is disallowed in this session, (line # 9) in sub/function 'INITIALIZE'

    Also note. You have to have high enough rights  on your server to set this option in an agent. If you - or your Domino Administrator, verify whether your current user id is specified in the server document's Security-field "Sign or run restricted LotusScript/Java agents";

    A picture named M5

    Your user id must either be explicitly be specified here, or you must be a member of one of the groups specified in this field. By the way; the user id you are working with right now, is the so-called signer id of the agent. Often corporations have separate so-called agent signer ids, which has the sole purpose of signing trusted agents and databases within your organization. Hereby highly advised to use agent signer ids!
  • Enter some LotusScript code to your agent (I have attached the complete agent at the end of this article if you don't want to type!). The (Options) section should contain these lines;

    Option Public
    Option Explicit

    %REM
    This agent will try to load the II2LN DLL and use it's 4 identification function. If this doesn't work, you know
    something is wrong with the II2LN installation on the server!
    https://www.vcode.no/ii2ln
    %END REM
  • The (Declarations) section contain the lines which declare the functions to use in the II2LN DLL. Those lines are the actual connection between LotusScript and II2LN DLL when the agent is run. By the way, not how the DLL is just specified as "VCII2LN.DLL". This means that Domino will find the VCII2LN.DLL in a directory specified by the system environment variable PATH on your server (do you now see why we have to reboot the server?). You could  specify a full path here to the VCII2LN.DLL, but then you must be very specific about other installation issues. Refer to the User's Guide if interested! Below you see the Declarations lines;

    Declare Function GetII2LNMajorVersion Lib "VCII2LN.DLL" () As Integer
    Declare Function GetII2LNMinorVersion Lib "VCII2LN.DLL" () As Integer
    Declare Function GetII2LNBuildNumber Lib "VCII2LN.DLL" () As Integer
    Declare Function GetII2LNVersion Lib "VCII2LN.DLL" (_
    Byval strOutBuf As String, _
    Byval iLenOfOutBuf As Integer) As Integer
  • Now it's time to enter the real code in the Initialize-section. The lines look like this and hopefully they are pretty self-explanatory;

    ' The first and foremost check is whether the II2LN DLL will load at all. I use standard LotusScript exception handling
    ' to catch this issue

    On Error Goto ErrorHandler

    Dim iMajorVersion As Integer
    iMajorVersion = GetII2LNMajorVersion()

    Print "Yiiha, II2LN *is* installed on the server! The Major Version is " & Cstr(        iMajorVersion)

    Dim iMinorVersion As Integer
    iMinorVersion = GetII2LNMinorVersion()

    Print "II2LN Minor Version is " & Cstr(iMinorVersion)

    Dim iBuildNumber As Integer
    iBuildNumber = GetII2LNBuildNumber()
    Print "II2LN Build Number is " & Cstr(iBuildNumber)

    Dim strVersionBuf As String * 255 ' Make a string large enough for the version string
    Dim strTmp As String
    Dim iLenOfReturnedBuf As Integer ' Hold the length of the returned buffer
    iLenOfReturnedBuf = GetII2LNVersion(strVersionBuf, 255)
    strTmp = Left$(strVersionBuf, iLenOfReturnedBuf) ' Strip of trailing blanks

    Print "II2LN Complete Build String is " & strTmp & ". II2LN seems to be working fine!"

    Exit Sub

    ErrorHandler:
    Dim strErrMsg As String
    strErrMsg = |II2LN: | & Getthreadinfo(1) & " error: " & Err & " " & Error(Err) & ", (line # " & Erl & ") in sub/function '" & Lsi_info(2) & "'"
    Print strErrMsg
    Exit Sub
  • Save the agent and enable it on the server. Note that this agent only use Print-statements to report back to you. On a Domino server, print-statements end up in the servers log database. You you can just wait.

    If you take a look on the agent's log from time to time (right click on the agents name, within the Lotus Designer), you can see whether it has run or not.

    A picture named M6

    If the agent hasn't run yet, you will see this message;

    A picture named M7

    And if it has run, it will look something like this!

    A picture named M8

    This means its time to head over to the servers log database (typically named log.nsf in the root directory of your server)
  • Open the log-database on the server (again, you must probably have enough rights to access this database). If you can't see the results, then ask your Domino Administrator to look for you;

    A picture named M9

    The response will be in the Miscellaneous Events  view.
  • The log will contain entries like the ones below if your II2LN is successful!

    01.10.2009 14:24:21   AMgr: Agent ('Verify II2LN installation on server' in 'Notes data\Projects\Voith's CODE\II2LN\VCIMGLIB2.Nsf') printing: Yiiha, II2LN *is* installed on the server! The Major Version is 1
    01.10.2009 14:24:21   AMgr: Agent ('Verify II2LN installation on server' in 'Notes data\Projects\Voith's CODE\II2LN\VCIMGLIB2.Nsf') printing: II2LN Minor Version is 6
    01.10.2009 14:24:21   AMgr: Agent ('Verify II2LN installation on server' in 'Notes data\Projects\Voith's CODE\II2LN\VCIMGLIB2.Nsf') printing: II2LN Build Number is 0
    01.10.2009 14:24:21   AMgr: Agent ('Verify II2LN installation on server' in 'Notes data\Projects\Voith's CODE\II2LN\VCIMGLIB2.Nsf') printing: II2LN Complete Build String is 1.6.0.0. II2LN seems to be working fine!

    If you have a problem with the II2LN installation, the exception handler in the LotusScript code above will kick in and show you a message similar to this;

    01.10.2009 14:29:13   AMgr: Agent ('Verify II2LN installation on server' in 'Notes data\Projects\Voith's CODE\II2LN\VCIMGLIB2.Nsf') printing: II2LN: INITIALIZE error: 48     Error in loading DLL, (line # 9) in sub/function 'INITIALIZE'
  • Hey, I have don't all the stuff above, but still the images won't process!!!! First, take a look at the always present log field VCII2LN_Log  in the processed documents. If you see some error message such as;

    ERROR: Current document analyse: Error during DXL processing. Message from DXL processor are 'A user name must be specified for applications running on a Domino server'.

    This means that we need to use the     ImpersonateAs import option too. You could for example use your server's name in the format CN=MyServerName/O=MyOrganizationName.
    Hopefully you now have a fully working II2LN installation on your server!

    Please find the complete agent attached too here!

Updated On 10.21.2012 |