Domino R5 on iSeries
Version 2.0
© Logicalis Group
Introduction
Domino on the iSeries
Work Management and performance
Security considerations
Save/restore considerations
Automating and monitoring Domino backups
Handling new versions and fixes
Differences to look out for
compared with Domino on NT platform
Options for integration with DB2
Hints and tips
Questions and AOB
Domino on the iSeries
iSeries as a Domino server platform
Libraries and IFS locations
Subsystems and jobs
Working with, starting and stopping Domino servers
Configuration of Domino servers
TCP/IP considerations, SMTP and HTTP servers
Java considerations
Domino on iSeries: strengths
Scalability
Up to 150,000 NotesBench mail users
Easy addition of disk space
Flexible use of resources
Domino partitioning
Multiple workloads
Resilience and manageability
Automatic restart following errors
Notes Admin client, green screen and iNav interfaces
Full CL command set for scripted configuration and management
Availability
Save-while-active (if BRMS installed)
Security
Domino security + OS/400 security
DB2 integration
without ODBC
Probably the
perfect
Domino
mail server
Domino on iSeries: challenges
Domino applications
Calls to DLLs
Lack of platform awareness among vendors
Not always the perfect
Domino application server
(or Web server)
Potential for performance problems

Applications that write a lot to the file system


ASCII<->EBCDIC translation


Integrated Filing System not as fast as NTFS
Issues with code pages – see later
Use of capped partial processors (e.g. on ‘slugged’ entry level system without
Accelerator)
Integrated Filing System
One integrated structure
QSYS.LIB = libraries, objects and members
QDLS = traditional 8.3 folder/document tree
QNTC = Windows Network client – sees contents of your NT servers
QFILESVR.400 = Remote IFS – sees contents of other iSeriess
QOPT = your iSeries’ CD drive
Qxxx used by other IBM products
Other root folders
use Unix naming conventions, e.g. case-sensitive
used by Domino on iSeries
Save with SAV command
Restore with RST command
Libraries and IFS locations
QNOTES library
IBM-supplied licensed program objects
QUSRNOTES library
Configuration objects

Subsystem descriptions, classes

Created for you by CFGDOMSVR
IFS
One tree per server

Typically /<myserver>/notes/data

Specified on CFGDOMSVR
Names are case sensitive
notes.ini will be in the data directory
WRKLNK, iSeries Navigator or mapped drive

But be careful … see later
Recommendation
You’ll need it one day in an emergency … so make sure you configure, and
know how to start and use, NetServer to map network drives to the IFS
Configure through iNav

Set it to use ‘normal’ iSeries host name to avoid DNS problems – this is not the
default, for some unknown reason

Set up share for each Domino server (or root share if security policies allow it)
Start NetServer with STRTCPSVR *NETSVR or through iNav
Map drives from Windows in the normal way

Use normal iSeries user profile/password
Subsystems and jobs
One subsystem per Domino server
Typically DOMINOnn
Name can be specified on CFGDOMSVR
One job per Domino task
SERVER, HTTP, SMTP, AMGR, …
May be started, and should be stopped, only from Domino

Resist the temptation to end Domino tasks from WRKACTJOB

End Domino using ENDDOMSVR (unless you enjoy waiting for consistency checks)
QNNINSTS is the autostart and controlling job
Working with, starting and stopping Domino servers
WRKDOMSVR
STRDOMSVR <myserver>
Automatically starts the relevant Domino subsystem
ENDDOMSVR <myserver>
N.B. this does not usually end the relevant Domino subsystem
Configuration of Domino servers
Create
CFGDOMSVR
Change
CHGDOMSVR
Remove
CFGDOMSVR OPTION(*REMOVE)
N.B. deletes the data directory!!
Some CFGDOMSVR hints and tips
If you don’t specify ADVSRV(*PARTITION) you will never be able to create a
second server
Specify MAIL(*NONE) (even if you want to use SMTP) if the iSeries native
SMTP server is running, otherwise CFGDOMSVR will fail
You can configure and run Domino SMTP in the normal way later – all the code
will be present – and each can be bound to a specific IP address to avoid
conflicts
Never use SMTP(*MSF), as this option will be withdrawn in a later Domino
release
More CFGDOMSVR hints and tips
If you don’t want synchronisation with the iSeries system directory, specify
DIRSRV(*NONE)
Otherwise you will have additional, pointless, work to do whenever you
upgrade Domino
If *SYSVAL QTIME is routinely changed when the clocks change, and if
*SYSVAL QUTCOFFSET is kept set to +00:00, then, if you use TIMEZONE(GMT)
and DAYSAVTIME(*YES), you should be OK
Make sure all country-specific system values are set how you want them
before you run the first CFGDOMSVR
Changing them later will result in code page problems
Code pages
All iSeries jobs have a CCSID attribute
DSPJOB to see it
All iSeries *FILE objects and IFS files have a CCSID attribute
DSPFD for *FILE objects, WRKLNK option 8 for IFS files
If they match, or *FILE CCSID is 65535, no translation occurs
If they do not match, automatic translation occurs
Automatic translation = unnecessary processing
US EBCDIC (37) and UK EBCDIC (285) count as a mismatch just as EBCDIC and ASCII do
Domino’s rich text handling is particularly badly affected by translation related performance
problems
So … get it right for all Domino databases you deploy
If you want to get optimum performance, also check and fix notes.ini and all IBM-supplied databases
and templates
If Domino jobs have the wrong CCSID
Check the LOCALE on the QNOTES user profile
Check the CCSID of the user profile used to start Domino
Editing notes.ini
Recommended:
Option 13 from WRKDOMSVR
Alternatively (harder):
iSeries Navigator, or
map drive and use WordPad
Populating the data directory
FTP or restore from another iSeries
If from non-iSeries platform, should use replication, to avoid code page
problems
Remember that this means none of your indexes will have been built!
Alternatively, FTP or use mapped drive and then run special program (e.g. as
shipped with IFSTOOL freeware tools) to change code pages
TCP/IP considerations
Recommendation:
Use of separate IP address for each Domino server

Should also be different from that/those used for other applications
Configuration:

Allocate IP address and add to DNS

Use CFGTCP to add and start new IP interface

Add line like this to notes.ini:


TCPIP_TCPIPADDRESS=0,172.17.1.9
Restart server
DNS
iSeries systems are frequently configured without DNS
If routing and replication don’t work, check your hosts table (CFGTCP option
10) and try a ping
Domino+physically remote DNS+*REMOTE lookups before
*LOCAL=appalling performance
SMTP listener
Watch out for clashes with iSeries SMTP server (outward SMTP Domino
mail routing not affected)
Can run both listeners simultaneously:
Via iSeries Navigator, bind iSeries SMTP listener to single IP address
Domino SMTP listener automatically picks up its parent Domino server’s
binding to a specific IP address
HTTP
Watch out for clashes with other iSeries-based HTTP servers (e.g. Apache
server within licensed program 5722DG1)
Existing non-Domino HTTP server will need to be bound to a specific IP
address
Method depends on the type of server
Domino HTTP server will need to be bound to the IP address of its parent
Domino server
This is done in Domino
Java considerations
Take advantage of the iSeries’s high performance Java Virtual Machine:
As far as possible, install all jars in the iSeries IFS
Pull only those Java classes into the Domino Java agent that are essential for it
to compile
Add the jars to this line in notes.ini (note colon separators):

JavaUserClasses=/<path1>/<myjar>.jar:/<path2>/<myjar2>.jar
Optimise the jars to level 40 with CRTJVAPGM
Together these steps will make a gigantic difference to the performance of
Domino Java agents
Work Management and performance
Domino likes memory and disk
Unless running HTTP, Java or a very complex app, CPW is not normally a big
issue, because the majority of the processing usually happens in the client
Typically, if Domino goes slowly, it is lacking main storage
However …
There is no alternative to careful sizing using the Workload Estimator
Domino does not run well on a capped partial processor (e.g. ‘slugged’ entry
level system without Accelerator)
Note that the ‘percentage consecutive users’ in the Workload Estimator will
almost certainly be 100, because this is the percentage of users concurrently
connected to the server, whether they are doing anything or not
iSeries work management is in charge
Do not fear - run as many AMGR’s as your application will let you
Recommendation
Run each Domino server in a pool of its own
Don’t let the pool start too small

Only the memory available at startup will be used optimally
Private pool can be a good option, or (better) use WRKSHRPOOL to set shared
pool minimum size appropriately (Domino should not be a reason to switch off
QPFRADJ)
Also…
Check code pages are correct
The only symptom of incorrect code pages is bad performance
Usual Domino performance rules apply, e.g.
Limit number and size of full text indexes
Don’t run unnecessary Domino tasks
There is an excellent and essential IBM Lotus Domino for iSeries
Performance and Tuning document
http://www.redbooks.ibm.com/redpapers/pdfs/redp3843.pdf
Security considerations
All Domino IFS objects must be owned by QNOTES
Public *RWX access will not do
If you copy Notes databases around using FTP or NetServer, ownership will be
wrong unless you use QNOTES user profile to do it (not really recommended)
If ownership wrong, use CHGOWN command, or WRKLNK option 9 then F19
QNOTES user profile password expiry should be switched off
Otherwise one day Domino will not start … and it will be very hard to work out
why
Set INLPGM(*NONE) INLMNU(*SIGNOFF) to prevent misuse
Backing up Domino
QNOTES is licensed program code – doesn’t need regular save
QUSRNOTES requires saving only if Domino configuration changes
Domino IFS trees require regular backup via SAV command
Save considerations
Unless BRMS is installed, must end Domino server to back up
Name and Address Book and log database (possibly others) will not save
cleanly otherwise
Always safest, and recommended, to end server even if just saving selected
mail or application database(s)
BRMS does allow save-while-active
Restore considerations
RST command
When restoring over existing directories/files, you will get cleaner results
if you delete the existing ones first
It is recommended that you restore to original location (rather than restore
elsewhere and then move/copy across)
Otherwise you are in danger of upsetting the file’s ownership and/or
authorities, and therefore preventing Domino from accessing the file properly
IFS save/restore examples
Save/restore (IFS directory, restored to different place, using savefile):
SAV DEV('/qsys.lib/shawm.lib/testifssav.file') OBJ(('/intranet'))
OUTPUT(*print)
RST DEV('/qsys.lib/shawm.lib/testifssav.file') OBJ(('/intranet'
*INCLUDE '/shawm4'))
To save to tape, example DEV parameter is
DEV('/QSYS.LIB/TAP02.DEVD')
Automating and monitoring Domino backups - example
/* End LEAD DOMINO server */
ENDDOMSVR LEAD
MONMSG CPF0000
DLYJOB DLY(900) /* In case not closed down properly-wait and zap.*/
ENDDOMSVR LEAD *IMMED
MONMSG CPF0000
DLYJOB DLY(300) /* GIVE IT TIME TO CLOSE FULLY.*/
/* IFS save - replace tap02 by appropriate device */
SAV DEV('/qsys.lib/tap02.devd') +
OBJ(('/lead')) CLEAR(*AFTER) /* +
Lead */
MONMSG CPF0000 EXEC(CHGVAR &NOTESERROR '1')
/* Start LEAD DOMINO SERVER */
STRDOMSVR LEAD
Handling new versions and fixes
Check the prerequisites
If it says Java 1.1.8, it means it – if only 1.3 is installed, it will not work
New Domino versions do not require an IPL, but their prerequisites may
need one
Follow the installation instructions explicitly
If running directory synchronisation, switch it off before the upgrade, and
remember to switch it on again afterwards
Differences to look out for
File system syntax
Forward slashes
No drive letter
ODBC and LC LSX considerations
Notes client ODBC applications use ODBC as usual
But server-based ODBC uses DRDA

Web applications

Server-based agents

WRKRDBDIRE to configure
Server-based code can only talk to non-DB2 databases if either

a DRDA gateway is available, or

you use Java instead of LotusScript
Direct modem attach to Notes server
Only supported via PPP using iSeries comms cable
Not recommended
Miscellaneous useful information
iSeries DB2 integration options
Dedicated Server for Domino
iSeries DB2 integration options
Lotus Enterprise Integrator (LEI)
Domino Enterprise Connection Services (DECS)
ODBC and LC LSX
JDBC and iSeries Toolbox for Java
Lotus Enterprise Integration (LEI) – What is it?
Previously called NotesPump.
Allows synchronisation of data between Domino databases and a relational
database (either may be the master copy).
Synchronisation may work on a schedule or may be real-time.
Configured via a point-and-click interface from a Notes client.
RDBMS access uses an SQL Interface, allowing joins, row and column
selection, etc.
Data may be processed automatically during synchronisation, using a Notes
agent at the Domino side or a stored procedure at the RDBMS side.
LEI – Where is it useful?
Presentation of iSeries data to the user via a Notes application.
Download of iSeries data into Notes applications (e.g. sales force
automation).
Upload of Domino data into an iSeries application, with appropriate iSeries
processing of information transferred (e.g. order posting).
LEI - Example
Population of Logicalis’ DB2/400-based data warehouse from our Dominobased CRM system, on a schedule and with some transformation of data.
Business intelligence from Domino data
Lotus Enterprise
Integrator
Domino applications
LEI
Slice-and-dice
analysis
DB2 UDB
Point-and-click
administration
Billing Year
2002
Billing Month
09
Employee Type Permanent
1.00
0.00
0.00
1.00
1.00
0.00
0.00
0.00
0.00
0.00
0.00
0.00
Grand Total
0.00
0.13
0.00
0.00
2.27
0.00
Team
Management
Sickness
0.00 17.53
0.00 0.00
0.00 0.00
0.00 0.00
0.00 0.00
0.00 6.00
Quality & Audits
0.00
0.00
0.00
0.00
0.00
0.00
Notability IPR
1.00
0.00
3.00
10.00
2.00
2.00
IT Support
(Notability)
0.00
0.00
0.00
0.00
0.00
0.00
Management
reporting
Internal Projects
(Notability)
0.00
0.33
0.27
0.00
0.00
0.40
Holidays (paid)
0.00
0.00
0.00
0.00
0.00
0.00
Education and
R&D
0.00
0.00
6.33
0.00
4.13
0.87
Downtime
0.00
0.00
0.00
0.00
0.00
0.00
Departmental
Infrastructure
Support
(Notability)
0.00
0.00
0.00
0.00
0.00
0.00
Customer
Support
Contracts
0.00
11.77
8.67
9.60
3.60
4.13
Customer
Presales
0.00
0.00
0.00
2.40
0.00
0.00
Customer Fixed
Price
0.00
3.20
1.80
0.00
1.67
1.67
Customer
Chargeable
Consultant
Consultant 1
Consultant 2
Consultant 3
Consultant 4
Consultant 5
Consultant 6
Customer Agreed
Free of Charge
Cost Centre
BPCS Services
Type Administration
Number of
Days
19.53
15.43
20.07
23.00
14.67
15.07
LEI – Comments
Separately chargeable product
Suitable for many applications
Very easy to configure
Requires no special Domino coding techniques
Connectivity from Domino server to iSeries works as for LC LSX, below
Domino Enterprise Connection Services (DECS) – What is it?
Allows a Domino application to access a relational database transparently
to the Notes programmer and to the user (rows fetched from the database
simply look like Domino documents).
Documents may be ‘virtual’ only, or may be copied at run time into the
Domino database so that the latest version is available even when the
connection is inactive (i.e. allows offline use).
DECS is configured using a point-and-click interface from a Notes client.
Key limitation is need for ‘stub documents’ – making it considerably less
useful than LEI in practice.
DECS – Where is it useful?
Applications where the number of documents, and the values to be taken
by unique key field(s), are always known, so that ‘stub documents’ with
only the key field(s) populated can be created in advance
Applications where Domino simply needs to write new records into an
iSeries database table
DECS - Example
Used by Logicalis in an customer application that reformats an iSeries spool
file and presents the values to users via a Domino application – values are
predictable enough to allow pre-creation of the stub documents by a
Domino agent.
DECS - Comments
Not chargeable, shipped with base Domino
Suitable in a limited range of applications
Very easy to configure
Requires no special Domino coding techniques
Connectivity from Domino server to iSeries works as for LC LSX, below
ODBC (formula language, LC LSX) – What is it?
ODBC calls programmed into the Domino application
ODBC from formula language, or LC LSX from LotusScript
ODBC – Where is it useful?
Transactions and/or enquiries into legacy applications from Web browser
client or Domino server-based agent.
NOT recommended for use from Notes client application, for desktop
maintenance and security reasons related to necessary presence of ODBC
driver on desktop.
ODBC - Comments
Not chargeable, shipped with base Domino
Use of formula language ODBC calls not recommended – complex to code
and very difficult to debug
LC LSX is used from LotusScript, very similar to Visual Basic SQL CLI coding
Performs very well
Functionality limited compared with JDBC (see below), so ODBC is not
recommended for new implementations
ODBC and LC LSX - Connectivity
If using Windows-based Domino server, Web browser clients and serverbased agents use ODBC running on the Domino server
If using iSeries-based Domino server, ‘ODBC’ connectivity in fact uses
DRDA and can thus run over either SNA or TCP/IP (connections local to this
iSeries are of course also supported). Use of DRDA support does impose
some design limitations
JDBC – What is it?
From Java agent or servlet.
JDBC calls programmed into the Domino application.
JDBC – Where is it useful?
Transactions and/or enquiries into legacy applications from Web browser
client or Domino server-based agent.
JDBC – Example 1
B2B Domino Web application developed by Logicalis for online ordering,
interfaced with the customer’s existing iSeries back end application using
stored procedures written in RPG
JDBC – Example 2
Used within Logicalis’ CRM system to extract management information from
audit history field and write it to an iSeries database table:
/* JDBC import */
import java.sql.*;
/* Variables for DB2/400 connection */
Connection conn = null;
PreparedStatement out = null;
/* Connect to DB2/400 (DRDA JDBC driver for performance) */
Class.forName("com.ibm.db2.jdbc.app.DB2Driver");
conn = DriverManager.getConnection("jdbc:db2:cat32",
“<user>“,“<password>");
/* Prepare INSERT statement (executed once only) */
out = conn.prepareStatement("INSERT INTO MAXDW.ONECALLADJ
(LEIUNID, NARRATIVEDATE,
NARRATIVETIME, NARRATIVE)
VALUES(?, ?, ?, ?)");
/* Use INSERT statement (executed once per record) */
out.setString(1,leiUnid);
out.setString(2,narrativeDate);
out.setString(3,narrativeTime);
out.setString(4,narrative);
out.execute();
/* Disconnect from DB2/400 */
conn.close();
JDBC – Comments
Not chargeable, shipped with base Domino
Open standards solution
Acquired skills would be compatible with any future WebSphere
deployment
Allows use of any available JDBC driver
Performs very well (for iSeries Domino server, it does require careful Java
optimisation)
Greater flexibility than LC LSX option
iSeries database JDBC drivers
Native DRDA
iSeries Toolbox for Java JDBC driver
Native DRDA JDBC driver
Runs over SNA or TCP/IP
Very fast, resilient and secure
Really only useful where the Domino server is running on iSeries
Does have some JDBC support limitations
No need to add to classpath
Some optimisation required for optimal performance
Can only test on server
iSeries Toolbox for Java JDBC driver
100% pure Java, allowing it to run on any platform
Fewer design limitations than the DRDA driver
Not quite so fast or resilient as the DRDA driver (longer code path)
although improving all the time
Will only run over TCP/IP
Needs adding to classpath
Needs a lot more careful optimisation than DRDA driver
or use /QIBM/ProdData/Java400/jt400ntv.jar, which is shipped preoptimised
Client-based testing feasible
iSeries Toolbox also provides classes for direct access to iSeries
functionality, e.g. Remote Command. Here is an example:
/* Java import for Toolbox */
import com.ibm.as400.access.*;
/* AS400 connection and command invoker */
private AS400 dominoServer = null;
dominoServer = new AS400(“<system>", “<user>", “<password>");
CommandCall cc = new CommandCall(dominoServer);
/* Set up command */
cmd = "RMVLNK OBJLNK('/QFileSvr.400/MYAS400/QDLS/MYFOLDER/" +
this.folderName + File.separator + files[i] + "')";
/* Run command - this will generate a Java exception if
OS/400 returns an exception */
cc.run(cmd);
/* Get messages returned and put in Notes log */
AS400Message[] msgList = cc.getMessageList();
for (int i=0; i < msgList.length; i++)
{
System.out.println(msgList[i].getText());
}