14.3 Moving your applications from Windows to Linux

---

14.3 Moving your applications from Windows to Linux

If your applications function today on Domino server running Windows NT or Windows 2000, they will also work on a Domino for Linux server.

Domino databases are platform-independent, meaning that you can copy files from NT to UNIX and open the database without any kind of change to the file format. However, there are a few considerations to bear in mind due to the differences in the environment.

The Decommission Server Analysis Tool gives you detailed information about the connections, databases, and other items two servers have in common. It can be used as a starting point for migrating your servers to your zSeries system. The Decommission Server Analysis Tool can be found in the admin client, on the Server>Analysis tab, under the Analyze tool. This tool allows you to do the following:

• Create an inventory of your existing Domino applications and include such items as replicas (on which servers), database properties, clustered, ACL settings, size, path, last used, inherits design from, is template.

• Find out who is responsible for the application, and if it is still needed.

• Find out how important the application is for your organization and how much workload it will generate on the server. This information is important for deciding when, and onto which server, to migrate the application.

• Archive and delete old and unused applications.

• Analyze the remaining applications for possible incompatibilities, such as dependencies on third party products, external data source as DB2 or Oracle, or specific hardware (such as a fax modem). Check the application using the design synopsis feature of the Notes Designer client or other designer (for example, Teamstudio) and appropriate filter rules (R4-R6, R5-6).

• Make the appropriate changes to the design of the database.

• Test the application on the new platform.

• Plan the distribution of your applications (which server, which directory, cluster).

• Transfer the databases to the target server.

• Notify the users and the Notes clients of the new database location.

• Monitor the migration process

14.3.1 Key migration questions

To ensure that your application will be compatible, consider the following questions before moving an application from Windows NT or Windows 2000 to Linux.

• Is your Domino application "self-contained"?

• Did you use Computer Aided Software Engineering (CASE) tools?

• Does your application use OS platform exploitation?

Is your Domino application "self-contained"?

A self-contained application runs entirely inside the Domino server, without any explicit references to files, without external calls, and without importing or exporting data. An explicit reference to a file, such as c:\domino\data\NAMES.NSF, will not work on Linux and needs to be replaced with /domino/data/names.nsf.

Linux does not support the \ character for specifying paths, and uses the / character. Linux is case sensitive when specifying paths and filenames, while NT is not. Case sensitivity can also be a problem anywhere an external script call, link, or hot spot is used; be sure to verify that the correct case is used.

Did you use CASE tools?

While CASE tools may be helpful, many of these tools were created with non-UNIX operating systems in mind, and their output code may not be compatible with Linux. Be sure to check with the manufacturer for compatibility before using these tools.

Does your application use OS platform exploitation?

Anything in the application that might be platform-specific could fail in the Linux environment. NT-specific services, NT Registry Sync for user registrations, Active-X controls, or compilers that rely on platform-specific libraries to compile the application will cause problems when the application is moved to Linux.

14.3.2 Moving the application to the Linux server

Transferring the files from Windows NT or Windows 2000 to UNIX can be done using many methods: FTP, transfer via CDRW, Iomega Jazz drives, or other media and PCNFS can all be used. For this example we used FTP, since it is the most common tool used in the field.

Since FTP servers are installed by default on the UNIX side and not on the NT side, it is usually easier to open an FTP session from the NT box and connect to the UNIX box. This example uses NT 4.0:

1. From the NT box, open an MSDOS command prompt by selecting Start -> Programs -> MSDOS.

   1. Change directory to the server's data directory:

       cd \lotus\notes\data 

   2. Start an FTP session:

       ftp servername 

2. Change directory on the UNIX box to the data directory:

       cd /local/notesdata 

3. Switch to binary transfer mode:

       bin 

4. Transfer the databases:

       put names.nsf 

   Or, transfer multiple files at once using wildcards with the mput command:

       mput *.nsf 

   Important: 

   Never add or remove databases from the OS level while the Domino server is up and running. Domino caches the data directory listing, and unpredictable behavior can occur if you modify the data directory while the server is running. This could result in a server crash or hang.

Ensuring permissions are correct

After the transfer is complete, make certain that permissions are correct on the UNIX machine. Log in to the UNIX machine and change to the data directory (cd /local/notesdata) and check the permissions on the transferred file:

    ls -l *.nsf 

Following is an example of the permissions line:

 -rwxrwxrwx  1 nadmsup notes  1589248 Feb 22 09:34 log.nsf 

Interpret this record as follows:

• The first column shows the permissions. The leftmost letter indicates whether this is a file or a directory. A dash (-) in the left position indicates it is a file; a letter d in the left position indicates it is a directory.

  The next nine letters indicate the access rights to the file for the owner, group, and world, given in 3-character segments.

  From left to right, the permissions in each segment are read access, write access, and execute access. Therefore, an entry of rwx means that read, write, and execute access is granted. If any of the letters has a dash (-) in its place, then that permission is not allowed. For example, r-x means that read and execute access is given, but write access is not.

• The owner is the user ID that owns the file, which is indicated by the third column in ls -l. In this case, it is "nadmsup." The owner's permissions are read from the first three permission characters in column 1 (following the file or directory indicator).

• The group is identified in the fourth column. In this case, it is the "notes" group. The group's permissions are identified in the next three characters in column 1.

• The world is anyone else who has login access to this system. Their permissions are specified in the last three characters of column 1.

Since the Domino server is the only one that should be changing or directly reading the databases, and databases are not executable programs, the permissions for databases should be:

 -rw———-  1 nadmsup notes  1589248 Feb 22 09:34 log.nsf 

If the permissions are not correct, you can issue the command:

    chmod 600 filename 

where filename is the name of the file on which you wish to change the permissions. This will give read and write access to the database for the Notes user, but will not allow anyone else to view it. Since the Domino server runs under the Notes user account and makes all of the read and write calls on behalf of the clients, most organizations will want to keep the access to the files restricted to the Notes user account.

Checking for case sensitivity

In NT, filenames are not case sensitive, but in UNIX they are. If your scripts call for the file log.nsf and the file is listed as LOG.NSF at the OS, the file will not be found when the script runs. After the FTP completes, check to ensure that the filenames are in lowercase unless your application is specifying otherwise.

 ls -l -rw———-  1 nadmsup notes  1589248 Feb 22 09:34 LOG.NSF mv LOG.NSF log.nsf ls -l -rw———-  1 nadmsup notes  1589248 Feb 22 09:34 log.nsf 

Note 

You should always type: bin on the FTP command line to ensure that you are in binary mode before transferring any databases or templates.

14.3.3 Other information for migrating Domino applications

In the following sections, we describe changes that have been made in Domino 6 for which you should check your applications.

The default fonts in Notes 6 have changed

In Notes 6, the default fonts have changed. If you have developed your current applications using the default fonts in Release 5 and earlier releases, you should check for screen corruption in the display of various parts of your application with Notes 6.

Formula language has been rewritten in Notes 6

In order to improve performance and maintainability, Notes Formula language has been rewritten in Notes 6. Emphasis has been placed on making sure that the new code provides 100 per cent compatibility. Therefore, no application changes are required. While performing migration testing, however, be sure to exercise all applications that use Formula language.

MQSeries® Lotus Script Extension (MQLSX) incompatible with Domino 6

MQLSX is not supported (although that does not mean MQLSX does not work) with Domino 6. It is also unsupported by Lotus after December 31, 2004. You should carefully test all applications that use MQLSX. We recommend that you rework those applications which use MQLSX. Developers should modify their applications to convert LotusScript to a Java API prior to their application servers being upgraded to Domino 6.

Strict Date/Time field interpretation has been restored in Notes 6

In Release 5, "robust" interpretation of date/time fields was introduced. Prior to Release 5, if an end user entered an incomplete or invalid date in a date/time field, they would be presented with an appropriate error message and would need to correct the date.

In Release 5, this capability was changed so that if an end user entered an incomplete or invalid date, Notes would make an educated guess as to what the date should be and not present the user with an error message. However, the resulting date could be one that the end user did not intend. For example, if you enter "24/06/2001" in a date field and press TAB, Notes guesses that you mean "Sat 06/24/2001" and changes it as such.

In Notes 6, the behavior that was prevalent prior to Release 5 is restored as the default behavior. Users may change to the Release 5 behavior by unchecking the new User Preference "Strict Date/Time Input". This preference may be changed in User Preferences on the Basic tab in "Advanced Options". There is no need to change applications. However, your users may experience differences on how date or time fields are evaluated, depending on what client they are using. You may want to consider additional documentation or validation processes to make sure that your users have entered the dates they intended.

Some JavaScript events have been changed in Notes 6

The implementation of JavaScript events that are common to Notes clients and Web clients has changed in Notes 6. In Release 5, support for JavaScript events was introduced in the Domino Designer. For Web applications, this meant that you could easily specify the code required for any JavaScript event. A subset of JavaScript events were also implemented for the Notes client. For events that were common to both the Notes and Web client, you could specify code once in the event, and it would work the same in both environments.

In Lotus Domino Designer 6, you can now specify separate behaviors for the common events, dependent on where it will execute (Notes client or Web). This allows applications to tailor their capabilities to the client that is being used, without having to use conditional code in the event logic.

The Notes client version of the event will now let you use LotusScript or Formula Language, in addition to JavaScript. One key question is how do you migrate designs between R5 and Notes 6. In addition, Notes client events that are the equivalents for JavaScript events are being "deprecated". This means that application programs should eventually move code in the deprecated Notes Client event to the JavaScript equivalent.

The Notes Client events that are being deprecated and their equivalent JavaScript events are listed in Table 14-1.

Table 14-1: JavaScript events

"Deprecated" Notes Client event	Equivalent JavaScript event
Post Open	onLoad
Field Entering	onFocus
Field Exiting	onBlur
Click	onClick
QuerySave	onSubmitt
QueryClose	onUnload

In Domino Designer Help, you find the following descriptions:

Forward Compatibility:

R5 applications running in the Notes 6 client behave the same. Those JavaScript events that worked in the Notes client continue to work on both the Web and the client. The deprecated events continue to work. When an R5 application is saved in Domino Designer 6, JavaScript events are moved into their corresponding Web and (where applicable) Client events. The deprecated events are also moved. For example, the onBlur event is moved into the onBlur - Web and onBlur - Client events, and the Exiting event is moved into the Exiting (deprecated) event.

Backwards Compatibility:

Notes 6 applications running in the R5 client behave the same as in the Notes 6 client as long as they are not recompiled in R5. Those events designed to run on the client run on the client and those events designed to run on the Web do not run on the client. The deprecated events work. If a Notes 6 application is recompiled in R5 Domino Designer, Web events are moved into their corresponding JavaScript events but client events are lost. The deprecated events are moved.

We suggest that developers take the following actions as appropriate:

Forward Compatibility:

For the JavaScript events that run on both the Notes client and the Web, where you use conditional code to modify the behavior for one environment or the other: instead use two routines, one for the client and one for the Web. For the deprecated events: move the code to the corresponding "on" client event.

Backward Compatibility:

If you continue to design in both R5 and Notes 6, you should keep the deprecated events and use the same code in the client "on" events as in the Web event.

@Command([ToolsUserLogoff]) and password prompt

@Command([ToolsUserLogoff]) can produce a different user experience when used to force password prompt. In R5, some applications use the @Command([ToolsUserLogoff]) to force the user into a password prompt situation.

This scenario might be applicable in cases where an application wants the user to specify a password before submitting a form. The application would issue the @Command([ToolsUserLogoff) command followed by some other processing (such as document Save) which would force the password prompt dialog to be displayed to the user.

In Notes 6, there is new user preference called "Clear screen on Logout". If an user has this preference enabled and the @Command([ToolsUserLogoff]) is issued followed by processing such as a document Save, the user's screen is cleared and the password dialog is displayed.

In R5 (or if the preference is disabled), only the password dialog is displayed. The application still works correctly. You do not need to change your applications, but you might consider additional user documentation or perhaps a different implementation that does not involve @Command([ToolsUserLogoff]).

More information about the changes between R5 and Domino 6 can be found in Domino Designer Help and at the following Web site:

• http://www.lotus.com/ldd/today.nsf/lookup/designer_rnext_technical_overview

Note 

Check for filesystem references, servernames, and so on in your applications and customized templates

In Table 14-2 on page 336, we list commands and @functions that may cause problems during a migration from R4 to Domino 6. Some of these commands should also be double-checked if you migrate from Wintel to an UNIX platform.

Table 14-2: @functions and commands to check for

	File handling	Shell calls	External Data access	External Programs	Date Time format
Lotus script	Access, Append, ChDir, ChDrive, Close, CurDir, CurDir$, CurDrive, CurDrive$, Dir, Dir$, EOF, FileAttr, FileCopy, FileDateTime, FileLen, FreeFile, Get, GetFileAttr, Input, Input$, InputB, InputB$, InputBP, InputBP$, Kill, Loc, LOF, MkDir, Name, Open, Output, Put, Random, Read, Reset, RmDir, Seek, SetFileAttr, Shared, Width, Write	ActivateApp, Command, Command$, Execute, Shell, Yield	Environ, Environ$, GetThreadInfo, IMESetMode, IMEStatus, Line, LMBCS, SendKeys	Alias, Any, Declare, Lib, UseLSX	Date$, DateValue, Format, Format$, Time, Time$
@ Function	AttachmentDetachAll, AttachmentLaunch, AttachmentProperties, AttachmentView, EditInsertFileAttachment, EditInsertObject, FileExport, FileImport	Execute	@DDEExecuted, @DDEInitiate, @DDEPoke, @Environment, @SetEnvironment	@DBCommand

14.3.4 Migration considerations for mailservers

The migration of an existing messaging infrastructure from multiple Domino servers to a central Domino platform presents a project team with a number of challenging tasks. A stable system platform with all proper disciplines must be provided, and the successful migration on the Domino level itself must be accomplished. IBM Global Services (IGS) can provide tools and assistance during migrations such as these.

The following tasks should be performed for a successful mail migration:

• Identify the users you want to migrate in this step by one or more of the following criteria:

  • Organizational affiliation

  • Home- or mail server

  • Individual selection

  • Mailfile sizes

• Generate a balanced distribution of mail databases on the target Domino server according to several criteria:

  • Maximum size of a directory

  • Number of databases per directory

  • Number of directories per server

  • Number of servers

• Transfer the databases using FTP or Domino replication:

  • Assure of a reliable data transfer

  • Log progress of the data transfer

• Adapt the Domino Directory

  • Convert the relevant person documents

  • Convert the relevant mailin-database documents

• Adapt the essential parameters in the client's location documents

  • Select the relevant location documents by type or name

  • Adjust calendar entries if daylight saving time (DST) settings have changed

  • Adjust the DST parameter

    Note 

    DST might be an issue, especially when you migrate from R4.

  • Adjust the agent "ProcessOutOfOffice" to the new server

  • Add the new icon to the users workspace, or add the new bookmark list entry

  • Log the progress of the migration

• A migration is a good time to clean up your mail environment, in terms of:

  • Standardizing naming conventions on a filename level

  • Reassessing reference inconsistencies in the Domino Directory

  • Monitoring the size-distribution of all mailfiles

  • Imposing Quotas for the mail databases

  • Defining meaningful mail server groups and cleaning up access groups

  • Setting the user access to Editor (the default Domino 6.5 ACL setting for mail databases)

Figure 14-3 on page 339 summarizes the basic tasks during a migration or server consolidation:

Figure 14-3: Migration steps

The steps shown in Figure 14-3 indicate the following:

1. Plan for a well-balanced distribution of the databases (server and directory), and define the filesystem on your new Domino server.

2. Transfer the databases from the old servers to the new Domino server.

3. Redirect the Notes Client to the new server. Also customize other client settings to meet the requirements for the new Domino server version and platform.

---