Installing and Managing Domino for AS/400

Transcription

1 Installing and Managing Domino for AS/400 R E L E A S E

2 COPYRIGHT Under the copyright laws, neither the documentation nor the software maybe copied, photocopied, reproduced, translated, or reduced to any electronic medium or machine-readable form, in whole or in part, without the prior written consent of Lotus Development Corporation, except in the manner described in the documentation. (c) Copyright 1998 Lotus Development Corporation 55 Cambridge Parkway Cambridge, MA All rights reserved. First edition printed Printed in the United States. Domino, Lotus Notes Desktop, Notes, Notes Desktop, Notes HiTest, and NotesPump are trademarks and Lotus, Lotus Notes, Lotus Organizer, LotusScript, and Notes Mail are registered trademarks of Lotus Development Corporation. cc:mail is a trademark of cc:mail, Inc., a wholly owned subsidiary of Lotus Development Corporation. Client Access and PowerPC are trademarks and AIX, AS/400, DB2, IBM, OS/2, OS/400, and VisualAge are registered trademarks of International Business Machines Corporation. Other product and company names mentioned herein may be the trademarks or registered trademarks of their respective owners.

3 Contents About Lotus Domino and AS/ The Internet/intranet solution... 1 Powerful tool for sharing information About the Domino and Notes documentation... 2 Administration... 2 Application development... 3 End-users... 4 About the license types... 5 Lotus Notes Mail licenses... 7 Lotus Notes Desktop licenses... 8 Lotus Notes Designer for Domino licenses... 8 About AS/ About the AS/400 user interface... 9 AS/400 Control Language and commands... 9 The AS/400 graphical user interface About AS/400 jobs and subsystems About AS/400 security About AS/400 messages Displaying messages Getting help with messages Responding to messages About the AS/400 system distribution directory About AS/400 storage management AS/400 disk storage AS/400 memory About the AS/400 integrated file system The root file system The QSYS.LIB file system About the AS/400 object-based architecture.. 17 About AS/400 documentation Installing Domino for AS/ About Lotus Domino for AS/400 system requirements Required hardware and software for Domino server Optional software for Domino server Supported networks and protocols Supported Notes workstations Additional requirements for the Notes administrator workstation About installing Domino on AS/ Overview of preparing AS/400 for Domino.. 24 Verifying the AS/400 authorities to install Domino Verifying the AS/400 hardware and software Verifying the AS/400 TCP/IP setup and status Installing the Domino software Choosing a setup method Overview of setting up the first Domino server on AS/ Deciding what to specify for server characteristics Using the CFGDOMSVR command to set up the first server What happens during first server setup Setting up the administrator workstation for the server Overview of setting up an additional Domino server on AS/ Registering the additional server Verifying the TCP/IP connections to AS/ Contents iii

4 Copying the ID file for the additional server to AS/ Using the CFGDOMSVR command to set up an additional server About changing a Domino server Extending Domino for AS/ About adding Operations Navigator to your administrator workstation Setting up Operations Navigator for Domino on a workstation About the Domino Web server Avoiding conflicts between the AS/400 HTTP server and Domino Serving documents from the QSYS.LIB file system Handling case-sensitive URLs Setting up CGI-BIN programs Creating SSL key ring files About the SMTP/MIME MTA Setting up the SMTP/MIME MTA for Domino on AS/ Considerations for the Domino SMTP MTA on AS/ About partitioned servers AS/400 requirements for partitioned servers Configuring partitioned servers for the TCP/IP network Managing the Domino Server.. 63 Ways of managing a Domino server on AS/ AS/400 authority requirements for Domino administrators Overview of using AS/400 commands to manage a Domino server Starting a Domino server on AS/ Stopping a Domino server on AS/ Using the Domino console on AS/ Displaying Domino server activities on AS/ Determining if the Domino server is active Editing the NOTES.INI file on AS/ Deleting a Domino server from AS/ Deleting Domino software from AS/ Overview of using Operations Navigator to manage a Domino server Determining the status of a Domino server Using Domino administrative functions About automatic Domino server restarts About copying files to the data directory Overview of managing the Domino SMTP/MIME MTA Starting the SMTP/MIME MTA Verifying that the SMTP/MIME MTA is operational Stopping the SMTP/MIME MTA Managing Domino Users About Domino for AS/400 users Setting up Domino for AS/400 users Using Operations Navigator to add users Viewing a user About directory synchronization Directory synchronization concepts Preparing for directory synchronization Directory synchronization tips Creating a directory synchronization configuration Enabling directory synchronization Disabling or suspending directory synchronization What happens when a directory synchronization configuration is enabled Managing Backup and Recovery About backing up a Domino for AS/400 server Libraries and directories for the Domino for AS/400 product Backing up Domino programs and product files iv Installing and Managing Domino for AS/400

5 Backing up all Domino databases Backing up mail databases Backing up specific databases Backing up changed objects from your Domino for AS/400 server Recovery of Domino for AS/ Recovering an entire Domino for AS/400 server Recovering Domino Public Address Books Recovering Domino mail Recovering Domino databases Recovering changed objects to a Domino for AS/400 server About user-defined file systems and availability Planning Security for Database Integration About the QNOTES user profile About AS/400 support for Domino access control About authority when Domino applications access DB2/ About authority when AS/400 programs access Domino databases About security recommendations for Domino for AS/ Setting Up the Application Development Environment General considerations for using C, C++, HiTest C, and Java APIs Running under the QNOTES user profile Restrictions for thread safety Setting the Path environment variable Starting server add-ins Restriction on APIs in exception or cancel handlers Restriction on using global operators Using API handles About ASCII-to-EBCDIC conversion Where to find the header files on AS/ About enabling the C++ compiler to access the header files Considerations for C APIs Compiler requirements for C Ensuring ASCII compilation for C APIs Accessing the C header files Compiling the C program on AS/ Compiling and linking the C program from a client Considerations for C++ APIs Compiler requirements for C Accessing the C++ header files Compiling and linking the C++ program. 149 Differences and restrictions for C Considerations for HiTest APIs Compiler requirements for HiTest C Accessing the HiTest C header files Compiling HiTest C programs on AS/ Compiling and linking HiTest C programs from a client Differences and restrictions for HiTest C Considerations for Java AS/400 software requirements for Java Setup required to run Java programs Restrictions and requirements for running Java agents Considerations for LotusScript Accessing the LotusScript support Differences and restrictions for LotusScript Considerations for LotusScript Extensions Installation Agreement Requirements for LSX Preparing for LSX development Creating an LSX Running the LSX Differences for LSX About integrating Notes and DB2/400 data General requirements and differences for LS:DO functions Differences for LS:DO Contents v

6 Remote connection differences Where to find error messages Where to find information about Domino application development Appendix A: Using Operations Navigator to Install Domino About AS/400 Operations Navigator for Domino Overview of using Operations Navigator to set up a Domino server Install Domino software on AS/ About setting up the administrator workstation Tasks involved in setting up the administrator workstation Preparing your workstation before you install Lotus Notes Installing and setting up Notes 4.6 Designer on your workstation Installing AS/400 Operations Navigator for Domino About the Domino server setup program Choosing first or additional server Ensuring full message logging Overview of using Operations Navigator to set up the first Domino server Creating a separate directory for the ID files Setting up your first Domino server About what happens during first server setup Completing server setup Overview of using Operations Navigator to set up an additional Domino server Registering the additional Domino server Verifying the TCP/IP connection to AS/ Copying the ID file for the additional server to AS/ Setting up an additional Domino server using Operations Navigator About additional Domino server setup Completing Step 1: Create an additional Domino server Completing Step 2: Select a Setup method Completing Step 3: Server audience Completing Step 4: Administration settings Completing server setup About additional Domino server advanced setup Appendix B: Setting Up Communications from an AS/400 Domino Server to an Integrated PC Server About Domino servers on AS/400 and an Integrated PC server Overview of changing the home AS/400 TCP/IP configuration Recording TCP/IP information for the Integrated PC Server on the *INTERNAL LAN Changing the home AS/400 TCP/IP host name search options Adding an AS/400 TCP/IP host table entry for the Integrated PC Server on the *INTERNAL LAN Adding an AS/400 TCP/IP routing entry for the *INTERNAL LAN Verifying communications over the *INTERNAL LAN Index Index-1 vi Installing and Managing Domino for AS/400

7 About Lotus Domino and AS/400 The Lotus Domino server, powered by Lotus Notes, combines Web server technology with the proven messaging, groupware, and application development capabilities of Notes. The Internet/intranet solution By extending the power of Notes to anyone with a Web browser, Domino is the premier interactive Web applications server for creating and hosting Internet and intranet sites. Domino bridges the open networking environment of Internet standards and protocols with powerful application development facilities. And by using Domino, any Web client can participate in applications securely. There is no better technology for Web publishing, Web browsing, and Internet/intranet applications than Domino. Only Domino offers replication, authentication, messaging, and security services fully integrated with Internet protocols in a single package. With the Domino Mail Access license, non-notes mail clients can access Domino servers for mail. And because Domino is cross-platform, it is the software solution for extending business applications to the Internet. Powerful tool for sharing information Domino is the central access point for finding and sharing information you need, whether it s located in , relational databases, or host-based systems; in your favorite desktop application; or on the World Wide Web. The Notes database provides a secure, reliable, and scalable means to store, manage, and distribute business information. Three powerful technologies come together to make Domino the industry s strongest client/server application development and deployment platform: a powerful, flexible compound-document database, a rich applications development environment, and a sophisticated messaging system. A powerful, flexible compound-document database The Lotus Notes document database is a robust object storage facility through which users can access, track, store, and organize a wealth of information. Documents can contain any number of objects and data types, including text, rich text, numerical text, structured data, images, graphics, sound, and motion picture images. A Notes database also contains forms for entering information into the documents, views for accessing the 1

8 information, and rich application development tools to automate processes related to the application. Integration between Notes databases and traditional databases dramatically enhances the value of an organization s information assets. A rich application development environment With Lotus Domino, both end-users and professional developers can create effective cross-platform client/server applications. Lotus provides ready-to-run application templates for the most common groupware applications including team management, customer service, meeting tracking, status reporting, reservation scheduling, and more. Customers can use these templates right out of the box, or customize them to meet specific needs. Or they can build applications from scratch using forms, fields, and views the basic building blocks of a Notes database. A sophisticated messaging system Every Notes user can send and receive , and every Notes application is automatically mail-enabled. Customers can exchange mail across a variety of mail systems, including cc:mail TM and MHS, and use prevailing standards, such as SMTP and X.400. Moreover, customers can build messaging and routing applications to automate the flow of work and information throughout their organization. Use the Lotus Domino 4.6 Mail server as the backbone of your messaging system. About the Domino and Notes documentation The Notes workstation and Domino server come with online documentation databases and printed books for many specialized tasks and individual situations. The following list will help you determine which documentation to read. Administration Lotus Domino 4.6 Administrator s Roadmap provides an overview of Domino administration documentation. Lotus Domino 4.6 Planning the Domino System provides information for planning, deploying, and integrating a Domino system in all types of organizations. It also discusses Internet, intranet, and extranet strategies for Domino. Lotus Domino 4.6 Configuring the Domino Network shows network administrators how to configure specific network operating systems to work with Domino, and how to configure Domino to work with their network operating systems. 2 Installing and Managing Domino for AS/400

9 Lotus Domino 4.6 Install Guide lists platform-specific instructions on installing and setting up Domino servers. The Domino Install Guide is also available online as a database file named SRVINST.NSF. Lotus Domino 4.6 Getting Started with Domino explains how to roll out and set up Domino servers and users. It also covers security, replication, the Public Address Book, server connections, server commands, and other administration-related topics. Lotus Domino 4.6 Extending the Domino System explains how to set up Notes mail, Internet mail, Web server features, calendar and scheduling functionality, Advanced Services, and other administration-related topics. Lotus Domino 4.6 Maintaining the Domino System explains how to manage and maintain Domino servers, users, databases, and tools, and other administration-related topics. The Release 4.6 Administration Help database provides online help and documentation for system and server administration tasks, deployment planning, and network configuration. The What s New view lists new features for administrators who are already familiar with Release 3.x. The information is also available in Planning the Domino System, Getting Started with Domino, Extending the Domino System, Maintaining the Domino System, and Configuring the Domino Network. The online database file name for Release 4.6 Administration Help is HELPADMN.NSF. Lotus Domino 4.6 Release Notes provides end-of-release information about new Domino features, software platform requirements, known limitations and restrictions, interoperability issues, and updates for the documentation set. The online database file name for the Release Notes is READMES.NSF. Application development Application Developer s Roadmap provides a task-oriented overview of the Notes application development documentation. Lotus Notes Designer for Domino 4.6 Application Developer s Guide provides guidelines for new and experienced application developers on how to plan, create, and test a Notes application. Lotus Notes 4.5 Database Manager s Guide focuses on the tasks involved in managing Notes databases: rolling out new databases, managing the access control list, setting up replication, and monitoring database activity. Lotus Notes Designer for Domino 4.6 Programmer s Guide Part I and Part II provides guidelines for writing scripts and formulas. This book also contains a complete reference for the Notes and LotusScript Notes classes. About Lotus Domino and AS/400 3

10 Lotus Notes Designer for Domino 4.6 Java Programmer s Guide provides guidelines for using the Java programming language to interact with Notes applications and databases. LotusScript Programmer s Guide provides guidelines for programming in the LotusScript language. LotusScript Language Reference Manual provides a complete reference for the LotusScript language. Lotus Notes 4.6 Install Guide lists platform-specific instructions on installing and setting up Notes workstations for Lotus Notes Mail, Lotus Notes Desktop TM, and Lotus Notes Designer for Domino. The Install Guide is also available online as a database file named WKSINST.NSF. Lotus Notes Designer for Domino 4.6 Release Notes provides end-of-release information about new Notes features, software platform requirements, known limitations and restrictions, interoperability issues, and updates for the documentation set. The online database file name for the Notes Release Notes is READMEC.NSF. End-users Lotus Notes 4.5 Step-By-Step is a beginner s guide for learning how to perform common tasks. Notes Help is a Notes database that provides context-sensitive information on all Notes client features, including information on designing and managing databases and using LotusScript. This information is also available in the Programmer s Guide, the Application Developer s Guide, and the Database Manager s Guide. The database file name for Help is HELP4.NSF. Notes Help Lite is a Notes database that provides context-sensitive information on most Notes client features. This database is a subset of Notes Help and is intended for mobile Notes users or users with limited disk space. The database file name for Help Lite is HELPLT4.NSF. 4 Installing and Managing Domino for AS/400

11 About the license types There are six Domino server license types and four client license types. Domino server license types Lotus Domino Mail Server for Single Processor Lotus Domino Mail Server for MultiProcessor Lotus Domino Server for Single Processor Lotus Domino Server for MultiProcessor Lotus Domino SMP (Symmetric Multi-Processor) Services Lotus Domino Advanced Services Note AS/400 does not support the Lotus Domino Mail Server for Single Processor and the Lotus Domino Mail Server for MultiProcessor. The Lotus Domino Mail server lets you run messaging for your organization with Domino. The Lotus Domino server includes the full messaging functionality of the Domino Mail server and adds application development capabilities. You must acquire one copy of the Software for each server on which the software will be installed. A server is defined as a central processing unit (CPU), or group of CPUs, that accesses its or their own individual non-cache Random Access Memory (RAM). The Domino Server for Single Processor may only be used on a server with one CPU. The Lotus Domino Mail Server for Single Processor license entitles you to host only those predefined templates which are installed with the Domino Mail Server (including chat, discussion, calendaring and scheduling, and messaging applications). The Lotus Domino Server for Single Processor entitles you to host all applications included with the Domino Server, as well as any custom or third-party applications which are available to you. The Domino Server for MultiProcessor may be used on any server. You may use the client features of the Lotus Domino Server to perform installation and administrative tasks; if you want to customize or create applications you must acquire a copy of the Lotus Notes Client software. If you wish to use a Domino Server product on a server with multiple CPUs, you must purchase the Domino Server for Single Processor and Domino SMP Services. You must first acquire a copy of either Domino Server or Domino Mail Server in order to run Domino SMP Services. You can use the Lotus Domino Advanced Services license with either a single processor or a multiprocessor computer. With the Lotus Domino Advanced Services license, you gain three primary server enhancements: clustering, the ability to connect several servers together to provide About Lotus Domino and AS/400 5

12 maximum accessibility and synchronization; partitioned servers, enabling one computer to host up to six servers; and billing capabilities for tracking and storing information about system usage. You must first acquire a copy of the Domino server for Single Processor, the Domino server for MultiProcessor, the Domino Mail server for Single Processor, or Domino Mail server for MultiProcessor to run Domino Advanced Services. You must acquire a Domino Advanced Services license for each server on which you wish to run the software. Client license types Lotus Domino Mail Access Lotus Notes Mail Lotus Notes Desktop Lotus Notes Designer for Domino You must acquire one copy of the software for each unique Notes User ID that is issued The software may also be installed on a home and/or laptop computer, but only the authorized user may access the software. You may create user IDs only for the specific Lotus Notes Client version (e.g., Notes Desktop TM Client) purchased. You are not required to acquire additional copies of the software when you create Lotus Notes IDs for scheduling applications such as Lotus Organizer. For the Lotus Notes Designer for Domino license, you must acquire one copy of the software for each application developer. In addition to using the software to design, develop and test your software application products, you may also use the software as your Lotus Notes client. The software also gives you the right to use Lotus Bean Machine (according to the terms set forth above under Domino server license types) and Lotus Notes Global Designer. The Lotus Domino Mail Access license allows customers using non-notes mail clients to access Domino 4.6 servers for mail. You must first acquire a copy of either Domino Server or Domino Mail Server in order to use Domino Mail Access. You must pay an access fee for each user who accesses a unique mail file on your server. You are not required to pay an access fee for (i) users who access the mail file with a Lotus client, or (ii) users who access non-mail databases or the replica of an already paid for mail file. The purchase of any Notes client includes the Domino Mail Access license. The Notes client licenses differ from each other in one or both of the following ways: The types of databases and database templates to which you have access. The extent to which you may modify the design of a database and perform administrative tasks. 6 Installing and Managing Domino for AS/400

13 A database is a collection of data. Many of the databases that come with Notes are documentation databases; that is, databases that contain information on using Notes. A database template is a skeleton database design that doesn t contain any data. You create a database by copying the database template and then adding data to the copy. For example, you can copy the Discussion database template and then add to the copy the information you want to discuss for example, brainstorming ideas for a new product. Design features are features that let you modify the design of a database. For example, the design features let you change the appearance and structure of all the documents in a database. Administration features are features that allow you to perform administrative tasks such as registering new Notes users. All license types have access to the Lotus Business Partner Catalog database, the most complete source of information on Business Partner products and services worldwide. This database can help you identify products and services that will maximize your Lotus technology investments. The following sections describe the three Notes client licenses. For more information, see your Lotus Software Agreement. Lotus Notes Mail licenses With a Lotus Notes Mail license, you have access to the following types of databases: A client/server mail database, which stores your mail. Domino creates this database for you automatically from the mail database template. Communication and collaboration databases, which help you work with others in your workgroup. You create these databases using the communications and collaboration database templates. Documentation databases, which are online books provided for your information. Lotus Notes Mail does not include any design or administration features. For more information on available database templates, see Appendix G of Getting Started with Domino. About Lotus Domino and AS/400 7

14 Lotus Notes Desktop licenses The Lotus Notes Desktop license provides unrestricted access to all Notes databases and database templates, including any custom or third-party databases and templates that are available to you. The Lotus Notes Desktop license does not provide access to design and administration features. For more information on available database templates, see Appendix G of Getting Started with Domino. Lotus Notes Designer for Domino licenses The Lotus Notes Designer for Domino license allows unrestricted access to all types of Notes templates and databases. In addition, you can create a blank database or use an existing database or database template as a starting point, to design your own applications. With a Lotus Notes Designer for Domino license, you can also perform administrative functions such as registering new Notes users. A summary of the client functionality is below. Functionality Domino Mail Access Notes Mail Notes Desktop Notes Designer for Domino Send/Receive Mail X X X X Client/Server X X X X Messaging Mobile X X X Personal Web X X X Navigator Web Agents X X X Calendar and X X X Scheduling Rich Text X X X Run Custom Apps X X Develop Apps X 8 Installing and Managing Domino for AS/400

15 About AS/400 For those who are new to AS/400, here is some general information to help you get started with your new system. Excellent educational offerings are available both for classroom education and for online education to help you learn more about your AS/400. For more information about AS/400 education, visit the Web site at Note If you re already familiar with AS/400, you can skip this information. About the AS/400 user interface Like many systems today, AS/400 offers two user interfaces for system functions: A system menu and command interface, which is often preferred by experienced users. A graphical interface, which is usually preferred by the less experienced, casual users. AS/400 Control Language and commands Control Language (CL) is the language of OS/400 (the AS/400 operating system). CL consists of a set of commands for performing system functions. You enter CL commands from a command line on any system display. The command line usually appears at the bottom of the display and has an arrow to prompt you, like this: ===> You can enter commands to run interactively that is, while you wait. You can submit commands to run in batch that is, in the background. You can also compile a set of commands into a CL program that you can run either interactively or as a batch job. Command names consist of a verb and a subject. For example, to display information about your current job on the system, use the DSPJOB (Display Job) command. DSP is the verb. JOB is the subject. Similarly, to create a user on the system, use the CRTUSRPRF (Create User Profile) command. CRT is the verb. USRPRF is the subject. Finding commands You will soon become accustomed to the AS/400 command abbreviations for verbs and subjects. However, you do not need to remember them. OS/400 provides a set of system menus to help you find the correct About Lotus Domino and AS/400 9

16 command for the system function that you want to perform. To access the primary system menu, called MAIN, go to any command line prompt (==>) and use the following command: go main The MAIN menu lists the major groups of system functions, such as User Tasks and Problem Handling. Selecting a menu option takes you to a submenu or a list of commands with their descriptions. When you find the function that you want, simply select the menu option to run the command. Alternatively, use one of these fast paths to find the command you need: Press F4 (Prompt) from the MAIN menu to display an alphabetical listing of all AS/400 commands. Use the verb menu to display a list of all the commands for a verb. For example, to display a list of copy commands, use the following: go cmdcpy Use the subject menu to display a list of all the commands for a subject. For example, to display a list of user profile commands, use the following: go cmdusrprf Entering commands To use an AS/400 command, you need the command name and one or more parameters. For example, to print the user profile for JDOE, you use the following command: dspusrprf usrprf(jdoe) output(*print) A parameter, such as USRPRF(JOE) consists of a keyword (USRPRF) and a value (JDOE). Sometimes the value is simply a character string, such as JDOE. The value may also be a system-specified option, such as *PRINT. System-specified options always begin with an asterisk (*). You do not need to memorize command names, command syntax, or parameters. OS/400 includes prompting and extensive online help. To access the prompting facility, type the command name and then immediately press F4 (instead of pressing ENTER). The resulting display lists each parameter for the command. You can type values for each parameter on the display. To get online help for a parameter, position the cursor on that parameter and press F1 (Help). A window displays with an explanation of all available choices for the parameter. Note When you select a command from a system menu, the system automatically prompts you for the parameters (as if you pressed F4). 10 Installing and Managing Domino for AS/400

17 Sometimes, a command has more parameters than the system can display on a single panel. When the prompting for the command requires more than one panel, you see More... at the bottom of the display. Use the page down function to see additional parameters for the command. Using common function keys Function keys are available on OS/400 system displays, command prompt displays, and menus to provide single-keystroke shortcuts. Following are the common function keys and their purpose: F9 - Retrieves the previous command that you entered, so that you can view it or repeat it. F12 - Cancels the current display and returns to the previous display. F3 - Exits the current display and returns to the previous menu. F5 - Refreshes the current display. For example, if you are displaying all the active jobs on the system (with the WRKACTJOB (Work with Active Jobs) command), press F5 to update the list. The AS/400 graphical user interface The graphical user interface for AS/400 is called Operations Navigator. It is available on Microsoft Windows 95 and Microsoft Windows NT workstations that have Client Access for AS/400 installed. (Client Access provides a set of AS/400 connectivity functions for connected workstations, including workstation emulation, printer emulation, and file transfer.) Operations Navigator provides a navigation path for each AS/400 for which the workstation has a connection defined. The navigation path groups system functions by object (such as Jobs or Users and Groups). By selecting an object, you can perform common system functions associated with the object. For example, you can create a user, change the characteristics of a user, assign the user to a group, or register the user for a Domino server. For an introduction to operations navigator, visit the Web site at and select the Operations Navigator topic. About AS/400 jobs and subsystems AS/400 is designed to be a multi-user system. OS/400 supports many active tasks with full sharing of system resources, including memory, printers, and database files. To keep track of all the work that is active on the system, OS/400 uses a concept called a job. When a work request enters the system, OS/400 creates a job for the work request. It assigns an identifier to the job and builds a structure that it uses to associate resources with the job. For About Lotus Domino and AS/400 11

18 example, when you sign onto your AS/400 from a workstation emulation session or with TELNET, the system starts a job for you. The job contains information about your work environment, such as performance characteristics and the destination for your print requests. The job remains active until you sign off. To balance the workload on the system, OS/400 provides the capability to define different working environments called subsystems. System resources, such as memory, are logically divided among the active subsystems. When you set up your AS/400 system, the system automatically defines a set of subsystems. The system also creates a subsystem for each Domino server that you configure. A Domino subsystem includes a set of jobs that start automatically to allocate resources for the various Domino server tasks. The book AS/400 Work Management (SC ) provides more information about subsystems, jobs, and the working environment for your AS/400 system. About AS/400 security The OS/400 operating system includes integrated security. OS/400 security has four major components: System-wide security policy. You can set AS/400 system values to establish security policies that affect all AS/400 users. For example, you can specify what the system does when an interactive AS/400 session is inactive for a period of time. You can specify composition rules for AS/400 passwords, such as requiring that passwords contain at least one digit. User profiles. Every AS/400 user has a profile that defines the user s security and environment characteristics. For example, the special authorities value in a user profile specifies whether the user can perform system functions such as controlling jobs or setting up new users. The output queue value in a user profile specifies the default location for the user s print requests. Not all Domino for AS/400 users need an AS/400 user profile. Resource security. For every object on an AS/400 system, you can specify which users have authority to access the object. Conceptually, AS/400 resource security is similar to access control lists in Lotus Notes. Security auditing. AS/400 has the capability to audit security-relevant events that occur on the system and to audit access to specific objects. Security auditing is defined with system values. Audit entries are captured in a security audit journal and journal receivers. 12 Installing and Managing Domino for AS/400

19 For more information about AS/400 security, see the book Tips and Tools for Securing Your AS/400 (SC ). About AS/400 messages OS/400 includes a basic messaging function. You can use this message function to send simple messages to other users (with the SNDMSG (Send Message) command). OS/400 also uses the messaging function to inform system operators and system users of events that occur. Messages on AS/400 are stored in message queues. You might think of a message queue as a message log. When you create a user profile, the system automatically creates a message queue for the user. Each workstation device on the system also has an associated message queue. System-level messages (such as communications errors or information about subsystems starting and stopping) are sent to the QSYSOPR message queue. Displaying messages To display the messages in a message queue, use the Display Message (DSPMSG) command. To display the message queue for your user profile and for your workstation device (one after the other), enter the following command: dspmsg Note The first parameter for the DSPMSG command is the name of the message queue. The default is to display your own message queue (and the message queue for your workstation), so you do not need to specify the parameter. To display the message queue for system messages, enter the following command: dspmsg msgq(qsysopr) or simply: dspmsg qsysopr Note Some parameters for commands are positional (usually the first, most commonly used parameters). If you specify the positional parameter values in the expected order, you do not need to specify the keyword names. When in doubt, specify the keyword names or use F4 to prompt. Getting help with messages When you display a message queue, you see one line of description for each message. If you need more information about the message, position your About Lotus Domino and AS/400 13

20 cursor on the message text and press F1 (Help). You see an Additional Message Information display that describes possible reasons for the message and appropriate responses. Responding to messages Some messages are informational. Other messages require a response. For example, the system sends a message to a printer s message queue when the printer is out of paper. After loading new paper, you need to tell the system to resume printing. When a message requires a response, you see a line in the message queue for the reply (immediately following the message text). A reply is a single character, such as c for continue or i for ignore. To find out what the allowable responses mean, press F1 (Help) to display additional information about the message. Then type your response after the reply prompt. The book Basic System Operation, Administration, and Problem Handling (SC ) provides more information about working with messages on your system About the AS/400 system distribution directory The AS/400 system distribution directory is a system-wide directory of names and locations for users, similar to the Domino Public Address Book. For a user, the system distribution directory defines the type of that the user has (such as Domino, POP3, or OV/400). Wild card (*ANY) entries in the system distribution directory support routing mail to other systems in the network. You can use the directory synchronization function that is part of Domino for AS/400 to maintain the information in the AS/400 system distribution directory and the Domino Public Address Book from a single source. You choose which of the two is your primary method for maintaining users. About AS/400 storage management The unique architecture of AS/400 is built on a concept called single-level store. You do not need to worry about managing storage (memory or disk) on your system. OS/400 (the operating system for AS/400) and the system licensed internal code handle it for you. 14 Installing and Managing Domino for AS/400

21 AS/400 disk storage If you are accustomed to other operating systems, you will notice one OS/400 difference immediately. When you specify a path name on AS/400, you do not specify a drive letter. For example, the path for your Domino server might be /NOTES/DATA. Because of AS/400 single-level store, all the drives on your AS/400 system are logically a single large drive. This is true whether you have one disk unit or 100 disk units. OS/400 takes care of placing new objects on physical disk units to balance both the use of space and the use of disk arms for system performance. You do, of course, still need to monitor the total use of disk storage on your system to ensure that you have enough capacity to store all of your data. You can use the Work with System Status (WRKSYSSTS) command to find out what percentage of your total auxiliary (disk) storage is used. AS/400 memory AS/400 is designed to run many jobs at the same time. To run multiple jobs efficiently, OS/400 and the licensed internal code take care of managing the use of memory by both system and user programs. Concepts like high memory and extended memory do not exist on AS/400. All memory is treated the same. As an AS/400 administrator or operator, you have the option to allocate the total memory on your system into logical pools of memory. You assign these pools to working environments called subsystems. However, most of this configuration work is done for you automatically. For example, when you configure a Domino server, the system automatically creates a subsystem (work environment) for the server and all its associated jobs. By default, AS/400 automatically adjusts the memory allocations between subsystems periodically by analyzing system performance. About the AS/400 integrated file system The OS/400 integrated file system provides multiple ways to store and view information. The integrated file system supports stream input and output operations. It provides storage management methods that are similar to (and compatible with) personal computer and UNIX operating systems. These file systems provide varying approaches to object management and integration, depending on the underlying purpose of each file system. Keep in mind that these file systems are logical, not physical. OS/400 takes responsibility for allocating and managing the underlying physical disk storage (as described in the Storage Management topic). You can safely run multiple file systems and diverse applications on the same server without worrying about incompatible demands on your storage resources. About Lotus Domino and AS/400 15

22 For more information about the integrated file system, see the IBM Integrated File System Introduction (SC ). The root file system The root file system provides the umbrella over all file systems on AS/400. You can think of the root file system as the top level in the hierarchical directory tree. The directory for your Domino server (such as /NOTES/DATA) is a subdirectory in the root file system. When you specify a path name in the root file system on AS/400, use a forward slash (/NOTES/DATA) instead of a backward slash. The root directory is not case-sensitive. You can type either /notes/data or /NOTES/DATA. The QSYS.LIB file system AS/400 programs and the integrated DB2/400 relational database are in the QSYS.LIB file system. The QSYS.LIB system uses a flat library structure to organize objects (instead of a hierarchical directory structure). When you are working within the QSYS.LIB file system (such as entering commands from a command line), you identify objects by library and object name, like this: library-name/object-name. For example, to run a program called YREND in the ACCTSREC library, you type this command: call acctsrec/yrend Note The QSYS.LIB file system is not case-sensitive. You can enter commands and their parameters in uppercase, lowercase, or a mixture. All executable programs on AS/400 run from the QSYS.LIB file system. The programs for Domino for AS/400 are in the QNOTES library in the QSYS.LIB file system. Using the path name for QSYS.LIB objects When you are in the root file system, you can access objects in the QSYS.LIB system. The full path name for an object in the QSYS.LIB file system includes extensions for the type of object you want to access. Following is an example of the path name for the YREND program in the ACCTSREC library: '/qsys.lib/acctsrec.lib/yrend.pgm' Chapter 5 has many examples of the syntax for specifying path names in the root file system. The book Integrated File System Introduction (SC ) provides detailed information about path names and links to objects in the integrated file system. 16 Installing and Managing Domino for AS/400

23 About the AS/400 object-based architecture AS/400 is an object-based system. The operating system treats a program differently from a file or a message queue, for example. Each object type on the system has many built-in functions, some of which are unique for the object type. When you want to use an object, you need to identify it to the system by location (name and library or directory) and by type. OS/400 has commands that specify both a verb (such as display or copy) and a subject (such as user profile or message queue). The system displays a user profile in a different format than it uses to display a message queue. As part of the integrated file system, OS/400 provides generic commands like CPY and MOV that do not include an object type as part of the command. When you use these generic commands, OS/400 performs the necessary validation and transformation to satisfy the underlying object-based architecture. Even when you use a generic command, you cannot, for example, copy a file and make it become a program. The object-based architecture of AS/400 makes it virus-resistant. Because AS/400 instructions are unique for each object type, a program cannot pretend to be a file or vice versa. Although AS/400 can be a carrier of viruses among connected workstations (like any server), OS/400 and the objects that it controls have proven immune to viruses. To take full advantage of AS/400 virus-resistance, your system should use security level 40, which is the default (shipped) value. To find out more about AS/400 security, see the IBM book Tips and Tools for Securing Your AS/400 (SC ). About AS/400 documentation Your AS/400 system arrives with a basic set of books, including the following: Getting Your AS/400 Working for You (SC ) provides information to help the new AS/400 administrator get the system up and running. Welcome Center (CD-ROM) provides an easy way to get started, for the first-time AS/400 administrator. Getting to Know Your System (CD-ROM) provides introductory education for the first-time AS/400 user or administrator. Software Installation (SC ) provides step-by-step instructions for installing the OS/400 operating system and IBM-supplied licensed programs (such as Client Access and TCP/IP). About Lotus Domino and AS/400 17

24 Basic System Operation, Administration, and Problem Handling (SC ) provides fast-path descriptions of common operator tasks, such as starting and stopping the printer, responding to messages, working with printers, and problem determination. It also provides basic information about security, backup and recovery, and system management. Tips and Tools for Securing Your AS/400 (SC ) describes techniques for securing your system, particularly in a networked environment. It also includes a description of the integrated AS/400 security tools. Backup and Recovery (SC ) provides planning information and step-by-step instructions for saving information off-line and restoring it in the correct sequence. AS/400 softcopy library (CD-ROM) provides the entire AS/400 library of publications in a format that you can display and search at your workstation. The AS/400 library of publications is also available on the Web at 18 Installing and Managing Domino for AS/400

25 Chapter 1 Installing Domino for AS/400 This chapter describes how to install the Domino software on AS/400 and set up a Domino server. It also describes what you need to do to set up a Notes administrator workstation for the server. About Lotus Domino for AS/400 system requirements Before you install Domino, install the AS/400 hardware and software that Domino requires. When possible, use the recommended equipment, rather than the minimum required, to improve performance and make maintenance easier. Required hardware and software for Domino server The Lotus Domino server for AS/400 requires the following hardware and software: An AS/400 that is based on PowerPC TM (RISC) technology Although a Domino server can run on any PowerPC model of AS/400, the AS/400 server models are optimized for client/server applications such as Domino. Operating System/400 (OS/400), 5769SS1, Version 4 Release 2 or later TCP/IP Connectivity Utilities for AS/400, 5769TC1 128MB base memory 0.5MB memory for each active mail user 490MB disk space for Domino executables and data (such as data directories and help files) 50MB disk space for each registered and active mail user (varies, depending on how much information each user stores) Note The memory and disk space requirements are based on results from a test environment. Use these values as general guidelines for minimum memory and disk space. The requirements for your environment may be different. 19

26 For instructions on how to check the AS/400 hardware and software or install AS/400 software, see Verifying the AS/400 hardware and software in this chapter. Optional software for Domino server Operations Navigator for Domino requires the following AS/400 options: OS/400 Host servers, 5769SS1 option 12 Client Access for Windows 95/NT, 5769XD1 AS/400 Client Access, 5763XD1, V3R1M3 Cumulative Service Pack AS/400 Client Access Family for Windows, 5769XW1 For more information, see About adding Operations Navigator to your administrator workstation in Chapter 2 or Installing AS/400 Operations Navigator for Domino in Appendix A. Java requires the following AS/400 options: OS/400 - Qshell Interpreter option, 5769SS1 option 30 AS/400 Developer Kit for Java, 5769JV1 Supported networks and protocols The Domino server for AS/400 runs with the TCP/IP network protocol. Supported Notes workstations The Domino for AS/400 server can connect to Lotus Notes Release 4.6 clients running on the following operating systems: AIX or HP-UX Sun Solaris Intel Edition 2.5.1, or Sun SPARC Solaris Microsoft Windows 95 or Microsoft Windows NT Version 4.0 Earlier versions of Notes Release 4 clients can also connect to the Domino server. These earlier versions support additional operating systems, in particular OS/2 and Microsoft Windows 3.1. However, some AS/400 administration functions require the Notes 4.6 client. Additional requirements for the Notes administrator workstation You must have at least one Notes client workstation in your organization to manage a Domino server on AS/400. The software requirements for that workstation depend on which administrator functions you use to manage the server. 20 Installing and Managing Domino for AS/400

27 Notes administrator functions only If you plan to use only the Lotus Notes administrator functions to manage the Domino server, you must have the following software on the workstation: An operating system supported by the Lotus Notes 4 client TCP/IP installed and configured Lotus Notes 4.1 client or later, including all administration functions AS/400 Operations Navigator If you plan to use the AS/400 Operations Navigator to manage the Domino server, you must have the following software on the workstation: A Microsoft Windows 95 or Microsoft Windows NT operating system IBM Client Access support for Windows 95/NT TCP/IP configured Notes 4.5 with full administrator functions or Notes 4.6 with Notes Designer AS/400 directory synchronization If you plan to use the AS/400 directory synchronization function to help manage Notes users, you must have one of the following on the workstation: A Microsoft Windows 95 or Windows NT operating system with TCP/IP configured Lotus Notes 4.5 client with all administration functions or Notes 4.6 client with Notes Designer An OS/2 operating system with TCP/IP installed and configured Lotus Notes client with all administrative functions Note If the workstation has a VGA display, use more than 16 colors. For more information on directory synchronization, see About directory synchronization in Chapter 4. About installing Domino on AS/400 A Domino server on AS/400 is part of a Domino network that includes one or more Domino servers and Notes clients. The way you use the Domino server in the network may affect the options you choose when you install the Domino software and set up the Domino server on AS/400. Therefore, before installing Domino, consider how you will use the AS/400 Domino server in the network. For more information, see Planning the Domino System. Chapter 1: Installing Domino for AS/400 21

28 Getting a Domino server installed and running on AS/400 involves a combination of tasks: Prepare an AS/400 environment for the Domino server. Set up the Domino server to run on AS/400. Set up a Notes administrator workstation for the Domino server. Prepare an AS/400 environment for the Domino server Preparing the AS/400 environment involves tasks such as: Verifying that the AS/400 system has the hardware and software needed for Domino Verifying that your AS/400 user profile satisfies the AS/400 security requirements to install and set up Domino Verifying that TCP/IP communications are set up and active on AS/400 Installing the Domino software that is needed to set up and use a Domino server on AS/400 Once you have the AS/400 environment ready for the Domino server, you must choose a method for setting up the server. Set up the Domino server The Domino server on AS/400 may be the first server or an additional server in a Domino domain. A Domino domain consists of one or more Domino servers and the Notes workstations that use the servers. Typically, a Domino domain contains the servers for a company or an organization or location within a company. If you do not have a Domino domain in your company, create a new domain by setting up the Domino server as the first server. If you already have a Domino domain with one or more existing servers, you may want to add the Domino server on AS/400 as an additional server. Before you set up an additional server, you must first register it with an existing server in the domain. Otherwise, the way you set up the additional server is essentially the same as the first server. You can use either of two methods to set up a Domino server on AS/400: Use the AS/400 Configure Domino Server (CFGDOMSVR) command. Use this method if you do not have an existing Notes network. This method provides the simplest way to set up the Domino server and verify that it is working before you set up the administrator workstation and the Notes network. Use the AS/400 Operations Navigator from a Notes client workstation. Operations Navigator sets up the Domino server through a Notes setup database. If you use this method to set up your first server, you must set up a Windows 95 or Windows NT workstation with Client Access and a Notes client before setting up the server. 22 Installing and Managing Domino for AS/400

29 You may prefer to use this method if you already have a Notes network set up and are using a Windows 95 or Windows NT workstation to administer the network. Once you set up Operations Navigator on a Notes administrator workstation, you can use the Operations Navigator to manage both the AS/400 system and the Domino server. After you decide which method to use to set up the Domino server, you decide whether you want to set up the Domino server as a first server or an additional server. Based on your choice of setup method in combination with your choice of either first server or additional server, you choose one of the following setup procedures: Using the CFGDOMSVR command to set up a first server Using the CFGDOMSVR command to set up an additional server Using Operations Navigator to set up a first server Using Operations Navigator to set up an additional server The method you use to set up the Domino server also affects the way you set up a Notes administrator workstation for the server. Set up the administrator workstation Typically, a computer used for a Domino server is both a server and a Notes client workstation. The AS/400 is a pure server in that it does not provide a local client workstation. Therefore, to use the capabilities of a workstation to administer the Domino server, you must connect a workstation to the AS/400 and set up the Notes client on the workstation. The workstation that you use to administer a Domino server must contain the Certifier ID file and administrator ID file that are created when you set up the server. If you use the CFGDOMSVR command to set up the server, the Certifier ID and administrator ID files are stored on the AS/400. You must copy the files to the administrator workstation. If you use the Operations Navigator to set up the Domino server, you must already have a Notes administrator workstation with Operations Navigator. Even if you do not set up the Domino server through Operations Navigator, you may want to add Operations Navigator to the administrator workstation later. Operations Navigator provides special capabilities in setting up Domino and AS/400 users. Where to find more information about setting up Domino for AS/400 If you are new to AS/400, we recommend that you begin by using the AS/400 Welcome Center CD. This CD provides many of the answers to questions new users have. You can find similar information in the book Getting Your AS/400 Working for You (SC ), which is included with each AS/400. Chapter 1: Installing Domino for AS/400 23

30 The Welcome Center CD and the Getting Your AS/400 Working for You book contain information about setting up TCP/IP on AS/400. Even if you do not use AS/400 Client Access, you may want to refer to the book Client Access for Windows 95/NT-Setup (SC ) for useful information on setting up TCP/IP on a workstation. The Client Access and the Installing Licensed Programs sections of the Welcome Center CD contain directions on setting up Client Access for Windows 95/NT. The book Client Access for Windows 95/NT-Setup contains similar information. The AS/400 Technical Studio Web page contains helpful information on setting up TCP/IP, Client Access, and Operations Navigator. The Technical Studio is at Note You can display or download any AS/400 book from the AS/400 Online Library Web site at Overview of preparing AS/400 for Domino Preparing an AS/400 environment for a Domino server involves these tasks: 1. Make sure you have the AS/400 authorities that are required to install and set up the Domino server. 2. Make sure the required hardware and software components are in place and working. 3. Make sure TCP/IP is set up and active on AS/ Install the Domino software on AS/400. You use the AS/400 Load and Run (LODRUN) command to install the software. Verifying the AS/400 authorities to install Domino AS/400 has extensive security restrictions to prevent unauthorized access to AS/400 functions and data. The person who installs the Domino software and sets up the Domino server must sign on the AS/400 using a user ID (user profile) that has broad special authorities. To install AS/400 software, you must have the following special authorities: *ALLOBJ (access to all AS/400 objects) *SECADM (security administration) To install the Domino software, you must have the following special authorities: *ALLOBJ (access to all AS/400 objects) *SECADM (security administration) 24 Installing and Managing Domino for AS/400

31 To set up the Domino server, you must have the following special authorities: *ALLOBJ (access to all AS/400 objects) *IOSYSCFG (device and communications configuration) *JOBCTL (job control) *SECADM (security administration) The AS/400 security officer has the required authorities. If you are not the security officer, use the Display User Profile (DSPUSRPRF) command to determine if your user profile has the required authorities: 1. Enter the AS/400 command dspusrprf user-id where user-id is your user ID (the name of your user profile). 2. Press the PAGE DOWN key to display the special authorities for the user profile. If your user profile does not have the required authorities, ask the security officer to either run the commands or use the Change User Profile (CHGUSRPRF) command to add the required authorities to your user profile. Verifying the AS/400 hardware and software For information on the required hardware and software, see About Lotus Domino for AS/400 system requirements at the beginning of this chapter. Use the Display Hardware Resources (DSPHDWRSC) and Display Software Resources (DSPSFWRSC) commands to display hardware and software currently installed on AS/400. Use the Display System Status (DSPSYSSTS) command to display the available disk space on your AS/400. Tip You can enter an AS/400 command on any AS/400 display that has a command line. The command line is the underlined area that follows the ===> symbol. To display the memory installed on your AS/400, enter this command: dsphdwrsc *prc To display the total disk space for your AS/400 and the amount used, enter this command: dspsyssts To display all software installed on your AS/400, enter this command: dspsfwrsc Press the F11 key to see the version and release of the software. Chapter 1: Installing Domino for AS/400 25

32 If OS/400 (5769SS1) Version 4 Release 2 or later is not currently installed on your AS/400, you must upgrade your system to the later release before proceeding. If you do not have any of the other required or optional software installed, you can install it now or wait until directed to install it in later instructions. To install AS/400 software: 1. Insert the CD or tape that contains the software to be installed. 2. Enter the following AS/400 command: go licpgm 3. On the resulting menu, enter an 11 to install licensed programs. 4. On the Installed Licensed Programs display, type a 1 beside each software option you want to install and press ENTER. 5. On the Install Options display, enter the name of the installation device in which you inserted the CD or tape. For example: opt01 Verifying the AS/400 TCP/IP setup and status The Domino server on AS/400 communicates with Notes workstations and other external resources, such as the Internet, through TCP/IP. For the Domino server to work properly, TCP/IP must be set up and active on your AS/400. Determining if TCP/IP is set up TCP/IP may already be set up on your AS/400. To verify that it is set up as needed for the Domino server: 1. Enter this AS/400 command: cfgtcp 2. On the resulting Configure TCP/IP menu, enter a 1 to display TCP/IP interface information. 3. Look for an Internet address that does not have a line description of *LOOPBACK. If you do not see an Internet address other than the address associated with *LOOPBACK, you must set up TCP/IP. For more information, see one of the following: The AS/400 Welcome Center CD. The book Getting Your AS/400 Working for You (SC ), which is included with each AS/ Installing and Managing Domino for AS/400

33 The LANs topic of the AS/400 Technical Studio on the Web. You can access the Technical Studio at If you see an Internet address other than the address associated with *LOOPBACK, TCP/IP is already configured. Continue to the following procedure. Determining the Internet address and host name to use for Domino 1. Record the Internet address that is not associated with *LOOPBACK. Internet address: Tip If there is more than one Internet address, choose one of the addresses to use for your Domino server. 2. Find the host name that is associated with the Internet address: If you are using a Domain Name Service (DNS), look in the DNS server for the host name that is associated with the Internet address. If you are using host tables for your TCP/IP network, use the TCP/IP host table entries on your AS/400 to find the host name that is associated with the Internet address. Use the CFGTCP command to display the Configure TCP/IP menu and then enter a 10 to display the TCP/IP host table entries. Use this TCP/IP host name for the name of the Domino server. Record the name here: Host name: By using the AS/400 host name and Internet address for the Domino server, you can take advantage of the existing TCP/IP configuration and avoid additional configuration. Starting TCP/IP Once TCP/IP is set up for your AS/400, make sure TCP/IP is started: 1. Enter this AS/400 command: go tcpadm 2. On the resulting menu, enter a 3 to start TCP/IP. If TCP/IP is already started, the system responds with a message that indicates TCP/IP is currently active. Installing the Domino software Installing the Domino software on AS/400 involves these tasks: 1. Decide which software you want to install. 2. Use the LODRUN command to install the software. Chapter 1: Installing Domino for AS/400 27

34 3. (Optional) Use the DSPSFWRSC command to verify that the software is installed. Deciding which software to install When you install the Domino server software, you can also install AS/400 integration software and application development software. Decide which of the following product options you want to install. You can install the integration or application development software later if you are not sure you need it. Domino Server (*BASE option) contains the programs, data, and template files needed to run a Domino server. You must select this option to run a Domino server on your AS/400. This option includes the SMTP/MIME MTA and all Domino help databases. AS/400 Integration (option 1) contains AS/400 programs and objects that allow you to synchronize the AS/400 directory with the Domino Public Address Book and to control the Domino server through a workstation graphical interface (Operations Navigator). You must select this option to use directory synchronization or the Operations Navigator support. Directory synchronization also requires the HiTest C API (option 6). For more information on directory synchronization, see About directory synchronization in Chapter 4. C API (option 3) contains the header files and modules for creating Notes C applications that can run on a Domino server on AS/400. C++ API (option 4) contains the header files, modules, and service program for creating and running C++ applications for the Domino server on AS/400. LotusScript Extension Toolkit (option 5) contains the source code, program, and files for creating LotusScript Extension applications that can run on a Domino server on AS/400. HiTest C API (option 6) contains the header files, modules, and service programs for creating and running Notes HiTest C applications for the Domino server on AS/400. Advanced Services (option 7) contains the files necessary to install the following Domino capabilities: Server clusters to connect up to 16 Domino servers together for maximum availability Partitioned servers to run up to 16 Domino servers on the same AS/400 Billing features to track and record server usage To use Domino Advanced Services, you must pay an additional fee. 28 Installing and Managing Domino for AS/400

35 Using the LODRUN command to install the Domino software The installation takes between 20 and 30 minutes. We recommend installing the software during periods when the system is not heavily loaded to minimize the effect on system users. 1. Insert the Domino for AS/400 CD in the AS/400 CD-ROM drive. 2. Enter the following AS/400 command: lodrun dev(*opt) dir('/os400/') 3. If the CD contains more than one language version of the software, you must first select a language. Type a 1 beside the language that you want to use and press ENTER. 4. Type a 1 beside each product option that you want to install and press ENTER. Verifying the Domino software is installed 1. Enter the following AS/400 command to display a list of installed software: dspsfwrsc 2. Look for items that have a Resource ID of 5769LNT. There should be at least one item with this Resource ID for each product option that you installed. What happens when the Domino software is installed AS/400 objects, such as programs (*PGM) and service programs (*SRVPGM), are put in the QNOTES library. Domino-related resource files are put in the /QIBM/PRODDATA/LOTUS/NOTES directory in the AS/400 integrated file system. The integrated file system provides a directory structure similar to PC operating systems (DOS, Windows) or UNIX operating systems. Files that contain symbolic links to the programs, service programs, and other objects in the QNOTES library are created in the /QIBM/USERDATA/LOTUS/NOTES directory in the integrated file system. These symbolic links provide access to the objects in the QNOTES library from the integrated file system. The QNOTES user profile is created for use by Domino and Notes application programs that run on AS/400. This user profile is intended for system functions and for integration with the underlying AS/400 security mechanisms. Therefore, it does not have a password. Individual users cannot use the QNOTES user profile to sign on the AS/400. Chapter 1: Installing Domino for AS/400 29

36 Choosing a setup method Choose one of these procedures for setting up the Domino server: Use the AS/400 CFGDOMSVR command to set up a first server. Use the AS/400 CFGDOMSVR command to set up an additional server. Use Operations Navigator from a workstation to set up a first server. Use Operations Navigator from a workstation to set up an additional server. For information about the merits of using the CFGDOMSVR command or Operations Navigator to set up the Domino server, see About installing Domino on AS/400 near the beginning of this chapter. For more information about using the CFGDOMSVR command to set up a first server or additional server, see Overview of setting up the first Domino server on AS/400 or Overview of setting up an additional Domino server on AS/400 in this chapter. For more information about using Operations Navigator to set up a first server or additional server, see Appendix A. Overview of setting up the first Domino server on AS/400 Use this procedure if the Domino server is the first server in a new Domino domain, such as the first Domino server in your company. Setting up the first Domino server involves these tasks: 1. Make sure you have prepared the AS/400 environment for the Domino server. 2. Decide what to specify when you set up the Domino server. 3. Use the CFGDOMSVR command to set up the server. 4. Set up a Notes administrator workstation for managing the Domino server on AS/400. Deciding what to specify for server characteristics When you set up the first Domino server, you must provide information that defines the key characteristics of the server. These characteristics include the name of the server, the location of the server s data directory, the name of your organization, and details about the person who is the server administrator. Before you run the CFGDOMSVR command, decide what to use for those key characteristics. Here are some recommendations. For more information, see Planning the Domino System. 30 Installing and Managing Domino for AS/400

37 Server name To avoid additional TCP/IP configuration, use the TCP/IP host name of your AS/400 as the server name. Each Domino server has a unique name that is maintained in its own ID file. Domino creates the server ID automatically during the server setup processing. For more information about setting up TCP/IP, see the previous discussion of Verifying the AS/400 TCP/IP setup and status in this chapter. Data directory The data directory contains files used by the Domino server and users of the server. On a PC-based platform, the data directory typically has the directory path: x:\notes\data where x is the drive letter. On AS/400, the files are stored in the integrated file system, which supports a directory structure similar to DOS or Windows. To make the path easy to remember, specify a similar directory path on AS/400. For example: /notes/data Notice that you use a forward slash (/) to specify a path in the AS/400 integrated file system. Each server must have its own data directory. Therefore, if you set up more than one Domino server (partitioned servers) on your AS/400, use a unique directory path for the second and subsequent servers. For example: /servername/notes/data where servername is the name of the second or subsequent Domino server. Note If you use an existing directory as the data directory, make sure that you set up the necessary authorities to the directory. The QNOTES user profile must have *RWX data authority as well as *OBJEXIST and *OBJMGT object authority to the directory. The owner of the data directory and subdirectories must have *OBJEXIST and *OBJMGT authority to the directory. Organization Typically, the organization name is the name of your company or a major division within your company. Each organization has a Certifier ID that is stored in a file named CERT.ID. During the server setup processing, Domino creates the organization Certifier ID automatically using the organization name you specify and an optional country code. When you register new users or servers, Domino uses Chapter 1: Installing Domino for AS/400 31

38 the Certifier ID to certify each user or server. You also use the organization Certifier ID when you create organizational unit certifiers for a hierarchical name scheme. Administrator The administrator can perform operations on the Domino server, such as starting and stopping the server. Although you only need to provide a last name, use a first name and, if needed, a middle initial to make sure the administrator s name is unique. Make sure you keep a record of the name and password that you specify for the administrator. Domino creates a user ID for the administrator during the setup processing. Some Domino server options are not automatically set up. You must request them through fields in the CFGDOMSVR command. For example: Web browsers Use this option to set up the HTTP Web server. Internet mail packages Use this option to set up mail support such as POP3 or SMTP/MIME MTA. Advanced services If you installed the Domino Advanced Services, use this option to include one or more Advanced Services features, such as setting up the Domino server as a partitioned server or as part of a server cluster. For more information about the HTTP Web server, the SMTP/MIME MTA, or partitioned servers, see Chapter 2. Using the CFGDOMSVR command to set up the first server Note The following procedure runs the CFGDOMSVR command interactively. The server setup processing takes 15 to 20 minutes to complete. Set up the server during periods when the system is not heavily loaded to minimize the effect on system users. If you prefer, you can run the CFGDOMSVR command in a batch job by using the Submit Job (SBMJOB) command. 1. On any AS/400 command line (indicated by the ===> symbol), type: cfgdomsvr 2. Press the F4 key. 3. On the resulting display, provide these details: Server name Type the name of the Domino server. If possible, use the TCP/IP host name of your AS/400 as the server name. While the cursor is on this field, you can press the HELP (or F1) key to display more information about what you can specify for the name. 32 Installing and Managing Domino for AS/400

39 Option Use *FIRST to indicate that you are setting up the first server in a Domino domain. 4. Press ENTER. 5. The display expands to request more details about the server. Use the PAGE DOWN key to display additional fields. Use the default value (*GEN) that is shown in the Certifier ID, Administrator ID, and Server ID fields. This value tells Domino to generate the required ID files for you. You must provide information for the following fields: Data directory (for example, /NOTES/DATA) Organization name Administrator name and password Time zone (press the F4 key to display a list of valid values) For information about what to specify for each field, position the cursor on the field and press the HELP (or F1) key. 6. When you have completed all fields, press ENTER to set up the server. While the CFGDOMSVR command is running, you see a message that indicates the command is in progress. Then, the AS/400 opens a terminal session and displays a series of messages that describe the setup activities. When the setup is complete, a message tells you to press ENTER to end the terminal session. 7. To verify that the Domino server was set up successfully, try to start the server and display its console. To start the server, enter the AS/400 command: strdomsvr servername where servername is the name of the Domino server you just set up. Once you have entered the command to start the server, display the server console to see what is happening. Enter the following command to display the console: wrkdomcsl servername For details on how to use AS/400 commands to start the Domino server or display the server console, see Chapter 3. The Domino server setup is complete. However, you still need to set up an administrator workstation for the server and copy the ID files from your AS/400 to the workstation. For more information about the administrator workstation, see the description of Setting up the administrator workstation for the server in this chapter. Chapter 1: Installing Domino for AS/400 33

40 What happens during first server setup The first server setup does the following: Creates a new domain for the Domino servers. Enables the appropriate network and serial ports. Creates the Public Address Book for the domain. The setup program creates the Public Address Book in the same directory you choose for Domino data files and gives it the default name NAMES.NSF. Creates a Certifier ID for your organization. The setup program saves the Certifier ID in the same directory you choose for Domino data files and gives it the default name CERT.ID. Creates a Certifier document in the Public Address Book. This document describes the Certifier ID. Creates a server ID for the new server. The setup program saves the server ID in the same directory you choose for Domino data files and gives it the default name SERVER.ID. The setup program creates the server ID with no password. If needed later, you can require a password for the server ID. Certifies the server ID with the organization Certifier ID. Creates a Server document in the Public Address Book. This document describes the first server based on information that you specify during setup. Creates a Person document in the Public Address Book for the Domino administrator specified during setup. Creates a user ID and a password for the Domino administrator and attaches it as a file named USER.ID to the administrator s Person document in the Public Address Book. Certifies the administrator s user ID with the organization Certifier ID. Adds the administrator s name and the server s name as managers in the access control list of the Public Address Book. Adds the server name to the LocalDomainServers group in the Public Address Book. Creates the log file for the server in the same directory you specify for Domino data files and gives it the default name LOG.NSF. Creates a mail directory in the Domino data directory and a mail file in that directory for the Domino administrator. 34 Installing and Managing Domino for AS/400

41 Sets up the Web server, if you specified that the Web server should be included. Sets up the SMTP MTA, if you specified that the SMTP MTA should be included. Setting up the administrator workstation for the server To use the capabilities of a Lotus Notes workstation to administer the Domino server, you must set up the workstation with the Certifier ID and administrator ID. These IDs are created when you set up the Domino server. You must copy these IDs to the administrator workstation. The following procedure assumes that the Notes client is not installed on the workstation. If Notes is already installed, skip the tasks that are already done. 1. Determine the hardware and operating system requirements for the release of Notes 4 you plan to install on the workstation. Refer to the installation documentation for that release of Notes. For example: For Notes 4.5, see the Lotus Notes Install Guide for Workstations. For Notes 4.6, see the Lotus Notes Install Guide. 2. Install and set up the operating system on the workstation, if you have not already done so. 3. Connect the workstation so it can communicate with the AS/ Install and set up TCP/IP on the workstation. For instructions, see the documentation for the TCP/IP product you installed on the workstation. Tip If you are using Microsoft Windows 95 or Windows NT, you may want to refer to the AS/400 book Client Access for Windows 95/NT - Setup (SC ). This book contains a helpful chapter on configuring Microsoft TCP/IP for Windows 95 or Windows NT. You can access this book from the AS/400 Online Library Web site at 5. Verify the TCP/IP connection to the AS/400. Open a DOS prompt window on the workstation and enter the following: ping hostname where hostname is the TCP/IP host name for the AS/400. You determined this host name when you verified the TCP/IP setup for AS/400. Chapter 1: Installing Domino for AS/400 35

42 If the name of the Domino server is different from the TCP/IP host name for the AS/400, also enter the following: ping servername where servername is the name of the Domino server. If the PING is successful, the workstation is communicating with the server and AS/400. If the PING is not successful, review the steps you followed to set up TCP/IP on the workstation and AS/ Install the Lotus Notes client software on the workstation. Make sure you install the full set of administrative functions (called Notes Designer for Notes 4.6). Do not start Lotus Notes yet. 7. If you already have a \NOTES\DATA directory on your workstation that contains a Certifier ID (CERT.ID) or administrator ID (USER.ID) file, take precautions to avoid replacing those files. Create a separate directory for the ID files that you will copy from the AS/400. For example, create this new directory: \notes\idfiles\servername where servername is the name of the Domino server you just set up on AS/ Copy the Certifier ID (CERT.ID) and the administrator s user ID (USER.ID) files from the Domino server to the workstation. Copy the files in binary format. Use any method that you typically use to copy files between the AS/400 and a workstation. For example, you can copy the files by using: The TCP/IP File Transfer Protocol (FTP). The Windows Network Neighborhood in combination with either AS/400 Client Access TM or AS/400 NetServer support to map a network drive between the workstation and AS/400. Then you can copy the file by using any method that copies files from one directory to another on the workstation. To use either method, you must have TCP/IP communications set up and active between the workstation and AS/ Start Lotus Notes on the workstation and fill in the information requested: Select Network configuration (Via LAN). Click the box that indicates Your user ID has been supplied to you in a file. This user ID is the administrator ID that you copied to the workstation. 36 Installing and Managing Domino for AS/400

43 Provide the location of the administration ID on the workstation. For example: c:\notes\data\user.id Provide the password for the administrator. You specified the password when you set up the Domino server. Indicate that the Domino server is your home server. You have completed setting up a Domino server and an administrator workstation for the server. Examples: Using FTP to copy the ID files to the administrator workstation Tip FTP is sensitive to the way you enter each instruction. If you see a response that you do not expect, the simplest way to recover is to end the FTP session and try the procedure again. To end FTP, enter: quit 1. As needed, create a separate directory on your workstation for the ID files. For example, if the name of the Domino server on AS/400 is SERVER1, you might create the IDFILES and IDFILES\SERVER1 subdirectories in the NOTES directory on your workstation. Change to the root directory: cd \ Create the two subdirectories: mkdir notes\idfiles mkdir notes\idfiles\server1 2. Change to the directory on your workstation where you want to put the ID files. For example: cd notes\idfiles\server1 3. Start an FTP session with the AS/400 that has the Domino server. For example, if the TCP/IP host name of your AS/400 is SYSTEM1, enter: ftp system1 You see one or more messages indicating that FTP connected to the AS/400, followed by a message that requests your user name. 4. Enter your AS/400 user ID; that is, the name of your AS/400 user profile: my-user-id A message requests your password. Chapter 1: Installing Domino for AS/400 37

44 5. Enter your AS/400 password: my-password If you entered your user ID and password correctly, you see the following message: my-user-id logged on Note If you see a message that indicates your login failed, you can repeat the login process by entering your user ID again: user my-user-id 6. Change to binary format: binary 7. Change your session to use the AS/400 integrated file system by entering: cd / You see the following messages: NAMEFMT set to 1 Current directory changed to / 8. Change to the AS/400 directory that contains the CERT.ID and USER.ID files. For example: cd /notes/data 9. Copy the CERT.ID file to your workstation: get cert.id You should see a message that indicates the file transfer completed successfully. 10. Copy the USER.ID file to your workstation: get user.id You should see a message that indicates the file transfer completed successfully. 11. Exit FTP: quit 12. Verify that the files are on your workstation: dir *.id After you copy the files to the administrator workstation, make sure you start Notes and complete the final step in setting up the workstation. See Setting up the administrator workstation for the server. 38 Installing and Managing Domino for AS/400

45 Overview of setting up an additional Domino server on AS/400 Use this procedure if you want to add another Domino server to an existing Domino domain. When you add a Domino server to a Domino domain, the additional server uses the same Public Address Book as other servers in the Domain. For example, set up the Domino server as an additional server if: You already have a Domino server on another system and you want the Domino server on AS/400 to use the same Public Address Book. You already have a Domino server on an Integrated PC Server in your AS/400 and you want the Domino server on AS/400 to use the same Public Address Book. You already have a Domino server set up on your AS/400 and you want to add a second server that uses the same Public Address Book. Note If you set up more than one Domino server on the same AS/400, you must install the Lotus Advanced Services feature and set up all Domino servers on the AS/400 as partitioned servers. Setting up an additional Domino server involves these tasks: 1. Prepare the AS/400 environment for the Domino server. If you previously set up your first Domino server on the same AS/400, you already set up the AS/400 environment. For more information, see Overview of preparing AS/400 for Domino in this chapter. 2. Use an existing server in the Domino domain to register the additional server. 3. Verify the TCP/IP connection from the registration server and its administrator workstation to the AS/ Copy the server ID file for the additional server to the AS/400, if you saved the server ID in a file when you registered the server. 5. Use the CFGDOMSVR command to set up the additional server on AS/400. Registering the additional server Before adding a Domino server to an existing Domino domain, you must register the additional server in the domain. When you register the server, specify the AS/400 TCP/IP host name as the server name, unless you already have a Domino server that uses the AS/400 TCP/IP host name. Using the same name avoids additional TCP/IP configuration. For instructions on determining the AS/400 TCP/IP host name, see Verifying the TCP/IP setup and status in this chapter. Chapter 1: Installing Domino for AS/400 39

46 1. Select an existing server in the Domino domain and use that server (the registration server) to register the additional server. For information about registering the additional server, see Getting Started with the Domino Server or the Administrator Help database (HELPADMN.NSF). The server registration process creates a Server document in the Public Address Book of the registration server and creates a server ID. Unless you specify differently, the server ID is encrypted and attached to the Server document in the Public Address Book. You have the option of storing the server ID in a file. If you store the server ID in the Public Address Book, you must provide a password. Keep a record of the password in a secure place. When you run the CFGDOMSVR command to configure the additional server, you must provide the password. Domino copies the Public Address Book, including the server ID, to the new server during the setup processing. You must also specify the password every time you start the additional server. Therefore, after you issue the start request, you must start the Domino server console (using the AS/400 WRKDOMCSL command) and enter the password. If you store the server ID in a file, you must manually copy the file to the AS/400 where you plan to set up the additional server. You must copy the server ID file before you run the CFGDOMSVR command. 2. Record the following information: The full hierarchical name of the registration server and the additional server that you registered. For example, here is a full hierarchical name: Server2/Chicago/Acme. Registration server: Additional server: The TCP/IP host name of the registration server. This host name is usually the same as the server name. Registration server TCP/IP host name: The location of the server ID file, if you chose to store the server ID in a file. Directory path and file name of new server ID: 40 Installing and Managing Domino for AS/400

47 Verifying the TCP/IP connections to AS/400 When you set up the additional Domino server on AS/400, Domino copies the Public Address Book from the registration server to the new server. Therefore, the AS/400 must have an active TCP/IP connection to the registration server. Similarly, the administrator workstation for the domain must be able to communicate with the AS/400. Verifying the TCP/IP connection between the registration server and AS/ Make sure the registration server is started. 2. From any AS/400 command line, enter this command: ping registration-server-host-name where registration-server-host-name is the TCP/IP host name of the registration server. You recorded this host name as part of the procedure to register the additional server. The host name of the registration server may be different from the TCP/IP host name of the system on which the registration server is running. If the registration server responds to the PING, the TCP/IP connection between the registration server and AS/400 is operational. If the PING is not successful, verify the TCP/IP configuration on the AS/400 and the system containing the registration server. Also verify that the AS/400 and the other system are properly connected to the network and that the network is operational. Note If the registration server for the domain is running on an Integrated PC Server in the same AS/400 as the additional server, you may need to do additional configuration. For more information on using a Domino for AS/400 server in the same domain as a Domino server on an Integrated PC Server, see Appendix B. Verifying the TCP/IP connection between the workstation and AS/400 To manage the additional server from your current administrator workstation, you must be able to communicate with the AS/400 through TCP/IP. If you are using a network protocol other than TCP/IP to administer your current servers, you must set up TCP/IP on the workstation. 1. Install and set up TCP/IP on the workstation. For instructions, see the documentation for the TCP/IP product. Tip If you are using Microsoft Windows 95 or Windows NT, you may want to refer to the AS/400 book Client Access for Windows 95/NT - Setup (SC ). This book contains a helpful chapter on configuring Chapter 1: Installing Domino for AS/400 41

48 Microsoft TCP/IP for Windows 95 or Windows NT. You can access this book from the AS/400 Online Library Web site at 2. Verify the TCP/IP connection to the AS/400. Open a DOS prompt window on the workstation and enter the following: ping hostname where hostname is the TCP/IP host name of the AS/400. If the PING is successful, the workstation is communicating with the AS/400. If the PING is not successful, review the steps you followed to set up TCP/IP on the workstation and AS/400. Copying the ID file for the additional server to AS/400 If you stored the server ID in a file, you must copy the file to the AS/400 where you plan to set up the additional server. Skip this procedure if you stored the server ID in the Public Address Book. 1. Make sure you are working from the system (server or workstation) that contains the server ID file. 2. Change to the directory that contains the server ID file. You recorded the directory path as part of the procedure to register the additional server. 3. Copy the server ID file to the AS/400 where you plan to set up the additional server. Use any method that you typically use to copy files between systems. For example, you can use: The TCP/IP File Transfer Protocol (FTP). The Windows Network Neighborhood in combination with either AS/400 Client Access or AS/400 NetServer support to map a network drive between systems. Then you can copy the file by using any method that copies files from one directory to another on the same system. To use either method, you must have TCP/IP communications set up and active between the workstation and AS/ Change the AS/400 authorities to secure the server ID file but still allow the Domino server to access the file: Change the public authority (*PUBLIC) for the file to *EXCLUDE. Use the Work with Object Links (WRKLNK) command to find the file path and then use option 9 to work with the authorities for the file (press F23 to display option 9). Change the owner of the file to QNOTES. Use the Change Owner (CHGOWN) command to change the owner. 42 Installing and Managing Domino for AS/400

49 Examples: Copying the server ID file to AS/400 Do all of the following steps on the system (server or workstation) that has the server ID file. Tip FTP is sensitive to the way you enter each instruction. If you see a response that you do not expect, the simplest way to recover is to end the FTP session and try the procedure again. To end FTP, enter: quit 1. Change to the directory that contains the server ID file. For example: cd serverid 2. Start an FTP session with the AS/400 where you want to set up the additional server: ftp systemname where systemname is the host name or the Internet address of the AS/ FTP requests your user ID and then your password. Make sure you enter your AS/400 user ID and password. 4. Change to binary format: binary 5. Change your session to use the AS/400 integrated file system by entering: cd / You see the following messages: NAMEFMT set to 1 Current directory changed to / 6. Create a directory for the server ID file on the AS/400. For example: mkdir serverid 7. Change to the directory you created. For example: cd serverid 8. Copy the server ID file to your AS/400. Enter the following command, substituting the actual file name for server-id-name: put server-id-name.id You should see a message that indicates the file transfer completed successfully. 9. Exit FTP: quit Chapter 1: Installing Domino for AS/400 43

50 10. Verify that the file was correctly copied. Enter the following two AS/400 commands: cd '/serverid' wrklnk The file should appear in the AS/400 directory ( /serverid). Using the CFGDOMSVR command to set up an additional server Note The following procedure runs the CFGDOMSVR command interactively. The server setup processing takes 15 to 20 minutes to complete. Set up the server during periods when the system is not heavily loaded to minimize the effect on system users. If you prefer, you can run the CFGDOMSVR command in a batch job by using the Submit Job (SBMJOB) command. 1. On any AS/400 command line, type: cfgdomsvr 2. Press the F4 key. 3. On the resulting display, provide the following: Server name Type the full hierarchical name of the Domino server. For example: Server2/Chicago/Acme Option Specify *ADD to indicate that you are adding this Domino server to an existing domain. 4. Press ENTER. 5. The display expands to request more details about the server. Use the PAGE DOWN key to display additional fields. You must provide information for the following fields: Data directory If you only have one server, specify: /notes/data NAB server name Type the name of the registration server. For example: Server1 You recorded this name in the procedure to register the additional server. Additional server ID ID file If you stored the server ID in the Public Address Book, use the default value of *NAB. If you copied the server ID to a file on this AS/400, type the file name. 44 Installing and Managing Domino for AS/400

51 ID file s password If you stored the server ID in the Public Address Book, type the password that you specified when you registered the additional server. Time zone Press the F4 key to display a list of valid values. For information about what to specify for each field, position the cursor on the field and press the HELP (or F1) key. 6. When you have completed all fields, press ENTER to set up the server. While the CFGDOMSVR command is running, you see a message that indicates the command is in progress. Then, the AS/400 opens a terminal session and displays a series of messages that describe the setup activities. When the setup is complete, a message tells you to press ENTER to end the terminal session. 7. To verify that the Domino server was set up successfully, try to start the server and display its console. To start the server, enter the AS/400 command: strdomsvr servername where servername is the name of the Domino server you just set up. Once you have entered the command to start the server, display the server console to see what is happening. Enter the following command to display the console: wrkdomcsl servername For details on how to use AS/400 commands to start the Domino server or display the server console, see Chapter 3. About changing a Domino server After you set up a Domino server on AS/400, you may find it necessary to change a particular characteristic of the server. For example, you may need to change from a nonpartitioned server to a partitioned server or you may want to add other capabilities such as billing or the SMTP MTA. You can reconfigure the Domino server by using the same procedure you used originally to set up the server. When you reconfigure the server, use the same values, except: Specify the exact location of the existing Certifier ID, administrator ID, and server ID files for the server. Specifying the location of the ID files avoids creating new ID files. Specify *NO in the Replace configuration field. Specify any values you want to add or change. Chapter 1: Installing Domino for AS/400 45

52 For example, to reconfigure a Domino server as a partitioned server, run the CFGDOMSVR command again and specify the same values you did originally, except for the following: Certifier ID /notes/data/cert.id Administrator ID /notes/data/user.id Server ID /notes/data/server.id Replace configuration..... *no Advanced services *partition In this example, the ID files are in the /NOTES/DATA directory on the AS/400. Caution Make sure that you make backup copies of your critical Domino files, such as your ID files, Public Address Book, and Domino databases, before you begin the reconfiguration process. For more information about the SMTP MTA or partitioned servers, see Chapter 2. For more information about backing up Domino information, see Chapter Installing and Managing Domino for AS/400

53 Chapter 2 Extending Domino for AS/400 This chapter includes information you need to know to extend the capabilities of Domino servers on AS/400 or the administrator workstation for those Domino servers. About adding Operations Navigator to your administrator workstation Even if you use AS/400 commands to set up a Domino server on AS/400, you may want to add Operations Navigator to your Notes administrator workstation. The graphical user interface of Operations Navigator provides some special capabilities in managing Domino servers and Domino users. These special capabilities allow you to: Easily determine the status of Domino servers on AS/400 Add a Domino user and an AS/400 user in one operation View and edit the NOTES.INI file for Domino servers on AS/400 For more information, see About Installing Domino on AS/400 in Chapter 1 and Ways of managing a Domino server on AS/400 in Chapter 3. Setting up Operations Navigator for Domino on a workstation Use the following procedure to add Operations Navigator to your Notes administrator workstation: 1. Install and set up Client Access support on your AS/400 and the workstation. For more information about Client Access, see one of the following: The Client Access documentation; for example, Client Access for Windows 95/NT-Setup (SC ) The Welcome Center CD that is provided with your AS/400 The AS/400 Technical Studio Web page at 2. Double-click the IBM AS/400 Client Access shortcut on your desktop. 3. Double-click the Accessories icon. 47

54 4. Double-click the Selective Setup icon. The selective setup window appears. 5. Click Next. 6. The Selective Setup Options dialog appears. Choose the Use managing system radio button. 7. Click Next. The message Checking for components available on managing system appears. 8. If you are not already signed on your AS/400, sign on now. 9. The Component Selection panel appears. Select the components you want. (As a minimum component selection, choose AS/400 Operations Navigator.) 10. Click the Change button. The Select Sub-Components dialog box appears. If you already have Operations Navigator installed, you still need to click the change button to add the sub-component Lotus Domino. 11. Select Operations Navigator Base Support (if not already installed) and Lotus Domino. 12. Click Continue. 13. Click Next. Click Next again on the Start Copying files panel. The preparing to install dialog box appears at the bottom right-hand corner. 14. The Install Completed panel appears. Click Next. The Readme - Notepad file appears. 15. The Setup Complete dialog appears. Click the radio button Yes, I want to restart my computer now If you are installing Operations Navigator for the first time, restart your workstation. You do not need to restart your workstation to use Lotus Domino support in Operations Navigator. 16. Click Finish. Note After you restart your workstation and select Operations Navigator, you may see a dialog about scanning for new Client Access components. If this dialog appears, click Scan Now. 48 Installing and Managing Domino for AS/400

55 About the Domino Web server The Domino server includes HTTP server technology that transforms Domino into a Web applications server. In general, you set up and use a Domino Web server on AS/400 the same as a Domino Web server on any other platform. However, there are some issues you need to know about: Avoiding HTTP server conflicts between AS/400 and Domino Serving documents from the QSYS.LIB file system. Handling case-sensitive URLs Setting up CGI-BIN programs Creating SSL key ring files For more information about the Domino Web server, see Chapter 2 of the Extending the Domino System book or the Domino administrator help database (HELPADMN.NSF). Avoiding conflicts between the AS/400 HTTP server and Domino The AS/400 operating system (OS/400) includes several TCP/IP application servers, including an HTTP server that is known as the Internet Connection Secure Server (ICS). This HTTP server processes HTML documents, CGI scripts, and Java scripts for home pages. Domino for AS/400 also provides an HTTP server capability, which enables Notes databases to be seen as HTML documents on the Web. You can have both HTTP servers installed and running. However, the Domino HTTP server and the Internet Connection Secure Server are both set up to use TCP/IP port 80. Because both HTTP servers use the same port, the server that is started second will have a problem accessing the port. To eliminate this problem, do one of the following: End the TCP/IP HTTP server by entering the following AS/400 command: endtcpsvr *http Then use the AS/400 WRKHTTPCFG command to change the TCP/IP server so that it uses a port other than port 80. Change the Domino HTTP server so that it uses a port number other than port 80. You change the HTTP server port number in the server document of the Public Address Book for the Domino server. For more information, see the Internet Connection Server and Internet Connection Secure Server for AS/400 Webmaster s Guide (GC ). Chapter 2: Extending Domino for AS/400 49

56 Serving documents from the QSYS.LIB file system Domino for AS/400 can serve HTML documents from the integrated file system, including the QSYS.LIB file system. When serving HTML files and CGI-BINs that are not Notes databases, be aware of the following: You must add the appropriate MAP and PASS directives to the domcfg.nsf database (or to the HTTPD.CNF configuration file in the Domino data directory). The data in the HTTPD.CNF file is ASCII. To edit the file, use the EDTF command on AS/400 or copy the file to an ASCII system. Make sure the QNOTES user profile has the authority to read HTTPD.CNF after making changes. Use the AS/400 Work with Object Links (WRKLNK) command to change the authority: Display the contents of the data directory for the server. For example: wrklnk '/notes/data' Enter a 9 (Work with authority) next to the HTTPD.CNF file. Verify that either QNOTES or *PUBLIC has at least read (*R) data authority. If needed, you can use option 1 or 2 to correct the authority for the file. If you serve files from the QSYS.LIB file system, the suffix is.mbr or.mbr. You must add an AddType directive to the HTTPD.CNF file for the.mbr and.mbr suffix to set the appropriate type. For example, add the following line to the HTTPD.CNF file to allow data in the QSYS.LIB file system to be served as an HTML document: AddType.MBR text/html 8bit 1.0 # QSYS file system Data served from the QSYS.LIB file system is mapped from the file ebcdic code page to ASCII. In addition to authenticating access to Domino databases, Domino for AS/400 can also authenticate users for access to files in the integrated file system, including QSYS.LIB. You can use the PasswdFile subdirective to indicate how the authentication should be done. The PasswdFile subdirective can contain either %%SYSTEM%% or the name of a validation list object. %%SYSTEM%% is used to indicate all valid AS/400 users. The validation list object is the AS/400 substitute for a password file. You can build a validation list object that contains Internet users; that is, names that have an associated password but cannot sign on to the AS/400. You can build the validation list object using AS/400 APIs or using the ICS/400 administration panels. Here are examples of using the PasswdFile subdirective. 50 Installing and Managing Domino for AS/400

57 To specify that you want to use AS/400 user profiles to validate user names and passwords: PasswdFile %%SYSTEM%% To specify that you want validation list object VLDL in library QUSRSYS to be used for a protection mechanism: PasswdFile QUSRSYS/VLDL For more information, see the Internet Connection Server and Internet Connection Secure Server for AS/400 Webmaster s Guide (GC ). Handling case-sensitive URLs URLs that refer to HTML documents are case-sensitive. For example, is not the same as: To avoid errors, make sure you use the correct uppercase and lowercase characters for the URL. If the browser cannot find the file, you see an error such as: Not found - file doesn t exist or is read protected Setting up CGI-BIN programs There are two ways you can define the location in which the server should look for a CGI-BIN program: Change the Server document in the Public Address Book to specify the desired directory (location). Use the Mapping form in the Domino Configuration database (DOMCFG.NSF) to map the CGI-BIN URL to the desired directory (location) and specify EXECUTE access. You can also use ILE RPG and ILE COBOL programs as CGI-BIN programs. For information about running these types of CGI programs on AS/400, see the ICS, ICSS Web Programming Guide (GC ). Examples: Defining the location of a CGI-BIN program The ILE C CGI-BIN program named MYLIB/CGIEXMP is referenced from an HTML document with the following tag: <form method=post action = "/cgi-bin/cgiexmp"> This example assumes the default CGI-BIN path is /cgi-bin. To have the server pick up the desired CGI-BIN program, use one of the following procedures. Chapter 2: Extending Domino for AS/400 51

58 Change the server document in the Public Address Book: 1. Open the server document for the Web server in the Public Address Book. 2. In the HTTP Server section, enter in the CGI directory field: /qsys.lib/mylib.lib/*pgm 3. Save the document and restart the Web server. Change the Domino Configuration database: 1. Open the Domino Configuration database (DOMCFG.NSF) and choose Create - Mapping URL -> Directory. 2. In the URL path field, enter: cgi-bin 3. In the directory field, enter: /qsys.lib/mylib.lib/*pgm 4. Click Execute. 5. If you are creating a mapping for a virtual server, specify its IP address in the IP address field. 6. Save the document and restart the Web server. Creating SSL key ring files The Certificate Authority application (CERTCA.NSF) lets you establish a Certification Authority (CA) within your organization. As an internal CA, you are responsible for handling certificate requests from Domino server administrators within your organization and adding client certificates to the Public Address Book. Setting up an internal CA simplifies the process of creating and managing certificates when your users do not need to communicate with external servers or when external users do not need to access your servers. In addition, setting up an internal CA lets you avoid unnecessary fees that external CAs charge to create and recertify certificates. The Certificate Authority application lets you create the CA certificate and key ring file, sign server certificates, and add client certificates to the Public Address Book. Before you can use the Certificate Authority application, you must create the database using the Certificate Authority template (CERTCA.NTF) and enforce database and server security. To use the Server Certificate Administration application for your Domino server on AS/400, you need to map a network drive to your AS400 data directory and specify that drive when creating your key ring and certificate 52 Installing and Managing Domino for AS/400

59 files. To map a network drive, you must have either of the following on the workstation: AS/400 Client Access support For more information about Client Access, see one of the following: The Client Access documentation; for example, Client Access for Windows 95/NT-Setup (SC ) The Welcome Center CD that is provided with your AS/400 The AS/400 Technical Studio Web page at AS/400 NetServer support For more information about NetServer, see the book Getting Your AS/400 Working for You (SC ), which is included with each AS/400. If the workstation has the Windows 95 or Windows NT operating system, you can use the Network Neighborhood to map the network drive. See Windows online help for instructions. It is more secure to run the Certificate Authority application from a workstation and keep the certificate authority CA key ring on the workstation. That is, the Certificate Authority database (CERTCA.NSF) resides on the AS/400 Domino server (for web availability) but the CA key ring file resides on the workstation hard disk. See the Lotus Domino 4.6 Release Notes and Getting Started with the Domino Server documentation for detailed descriptions of how to set up SSL certificates. You can also use the following methods to manage your key ring and certificate files: Create the key ring files and certificates using Domino on another platform and then use FTP to copy them in BIN mode to your Domino data directory on AS/400. Make sure the QNOTES user profile has read (*R) authority to the files after you copy them to the data directory. The Notes 4.6 client must include Notes Designer. Use the Internet Connection Secure Server (included in the AS/400 TCP/IP support) to create your key ring files and certificates. For more information, see Chapter 8 in the Internet Connection Server and Internet Connection Secure Server for AS/400 Webmaster s Guide. Chapter 2: Extending Domino for AS/400 53

60 About the SMTP/MIME MTA A Message Transfer Agent (MTA) is a program that runs under the control of a Domino server to exchange messages (mail) with mail applications that use different protocols than Lotus Notes does. Simple Mail Transfer Protocol (SMTP)/Multipurpose Internet Mail Extension (MIME) is a standard based on TCP/IP. SMTP/MIME is often used to connect unlike systems. The SMTP MTA provides for scalable, bidirectional message transfer with SMTP networks. Through the implementation of standards, such as MIME, the MTA ensures state-of-the-art interoperability with other SMTP/MIME implementations. The Lotus Domino SMTP/MIME MTA is an integrated component of the Domino 4.6 server that provides advanced messaging features and extensions to the 4.6 server. With the SMTP/MIME MTA, a Domino 4.6 server transfers SMTP/MIME messages between SMTP networks (both Internet and intranets) and Domino. In addition, other mailing applications such as OfficeVision/400 or cc:mail can also use OS/400 functions (for example, OS/400 SMTP support) to convert from and to SMTP, thus allowing exchange of mail with a Domino server through the MTA. Setting up the SMTP/MIME MTA for Domino on AS/400 Although the SMTP/MTA on the AS/400 Domino server works the same way as the STMP/MIME MTA on other Domino servers, there are some differences with installation and configuration on AS/400. The unique AS/400 installation and configuration steps for the SMTP/MIME MTA are: 1. Verify that the required products are installed on the AS/ Select the SMTP/MIME MTA option when configuring the Domino server. 3. Verify that the AS/400 SMTP server is started. 4. Verify that the AnyMail function is started on the AS/400. For additional information about configuring and using the SMTP/MIME MTA on a Domino server in general, see Extending the Domino System or the Notes administrator help database (HELPADMN.NSF). Also see the following Web sites for related information: The AS/400 Technical Studio ( The Lotus home page ( under the Notes MTAs link from the Products link. 54 Installing and Managing Domino for AS/400

61 Verifying that the required products are installed for SMTP MTA The SMTP MTA for the AS/400 requires the following software: Domino for AS/400 The SMTP/MIME MTA is part of the *BASE software for the Domino server. TCP/IP Connectivity Utilities for AS/400 (5769TC1) To verify what software is installed on your AS/400: 1. From an AS/400 command line, enter: dspsfwrsc 2. Verify that products with the following resource IDs appear in the list: 5769LNT 5769TC1 If these products are not in the list, they are not installed. For more information about installing these products, see Chapter 1. Selecting the SMTP/MIME option when setting up the Domino server If you select the SMTP/MIME MTA option when you set up the AS/400 Domino server, the SMTP/MIME MTA is automatically configured. Because there are two methods for setting up the Domino server, the procedure for setting up the SMTP/MIME MTA configuration option depends on the method you use to set up the Domino server on AS/400: If you use the CFGDOMSVR command, specify the value *SMTPMTA for the Internet mail packages parameter. If you use the Operations Navigator, select the appropriate option in step 3 of the setup procedure. If you use the Quick and Easy setup procedure, select the Internet Mail Packages option. If you use the Advanced setup procedure, select the SMTPMTA option. Note If you have already configured the AS/400 Domino server without adding the SMTP/MIME MTA, and would now like to add the SMTP/MIME MTA, you must reconfigure the server. Chapter 2: Extending Domino for AS/400 55

62 Domino documents affected by the SMTP/MIME MTA option The AS/400 implementation of the Domino SMTP/MIME MTA simplifies the setup process by automatically creating and configuring the required Domino documents. The following SMTP/MIME MTA documents are automatically created when you set up a Domino server on AS/400 with the SMTP/MIME MTA option: Global Domain document. The Global Domain Name and Internet domain suffix are set based on the AS/400 TCP/IP configuration values. Foreign Domain document. Connection document. In addition, the Server document is also updated with the following information: In the Basics section: Routing tasks: Mail Routing, SMTP Mail Routing In the Internet Message Transfer Agent (SMTP MTA) section: Global domain name: MTAGLOBAL Fully qualified Internet host name. This is set based on the AS/400 TCP/IP domain name. For more information about using the CFGDOMSVR command or reconfiguring (changing) the server, see Chapter 1. For more information about using Operations Navigator, see Appendix A. Verifying that AS/400 SMTP server is started The SMTP/MIME MTA on the AS/400 uses the SMTP/MIME server and the AnyMail function of the AS/400. The AS/400 SMTP server must be started before the SMTP/MIME MTA can function. 1. From an AS/400 command line, use the NETSTAT command to display the Work with TCP/IP Network Status panel: netstat *cnn 2. On the Work with TCP/IP Connection Status panel, look for an entry in the Local Port column with a value of SMTP (or 25). If the SMTP local port shows a state of Listen, the SMTP server is operational. If the SMTP server is not operational, enter the following AS/400 command to start it: strtcpsvr server(*smtp) 56 Installing and Managing Domino for AS/400

63 If the NETSTAT command response indicates that TCP/IP is not started: Enter the AS/400 command: strtcp Allow a few minutes for TCP/IP to start. Try the NETSTAT command again. Verifying that the AnyMail function is started on AS/400 The SMTP/MIME MTA on AS/400 uses the AS/400 SMTP/MIME server and the AnyMail function. After you set up the Domino server, you must reset the AnyMail function one time by stopping it and then restarting it. 1. From an AS/400 command line, enter the following command to stop the AnyMail function: endmsf 2. Enter the following AS/400 command to restart the AnyMail function: strmsf 3. Enter the following AS/400 command to display a list of jobs: wrkusrjob qmsf 4. Verify that there is at least one job listed. After you verify that AnyMail is operational, start the SMTP/MIME MTA and verify that it is operational. For more information, see Overview of Managing the Domino SMTP/MIME MTA in Chapter 3. Each time you use the SMTP/MIME MTA, both the AnyMail function and the SMTP server must be operational. If the AnyMail function is not operational, enter the following AS/400 command to start it: strmsf If the SMTP server is not operational, enter the following AS/400 command to start it: strtcpsvr server(*smtp) Chapter 2: Extending Domino for AS/400 57

64 Considerations for the Domino SMTP MTA on AS/400 Be aware of the following differences for the SMTP/MIME MTA on AS/400. AnyMail framework The AS/400 implementation of the SMTP/MIME MTA differs from other platforms in that it takes advantage of the AS/400 AnyMail framework. AnyMail (QMSF jobs) links the SMTP MTA to: The AS/400 SMTP/MIME support (and to other TCP/IP servers and the Internet) POP3 users local to the Domino server OV/400 users local to the Domino server or elsewhere in a SNADS network FS/400 (Fax Server) if it is installed on that AS/400 Messages that originate from users of any of these functions are first processed in AnyMail and routed through the SMTP MTA and to Domino users with a function that works as part of the AnyMail framework. Messages that originate from Domino users that are sent to users of any of these functions are passed to the AnyMail framework by the AS/400 implementation of the SMTP MTA. Functions of the AnyMail framework route the message to the appropriate AS/400 function. For more information on AS/400 SMTP/MIME support and the AnyMail framework, see the book AS/400 Electronic Mail Capabilities (SG ). AS/400 SMTP server The AS/400 implementation of the SMTP/MIME MTA differs from other platforms in that it takes advantage of the AS/400 SMTP server. Because of this, configuration of some aspects of the SMTP/MIME MTA on the AS/400 is performed differently than on other platforms. For example, on non-as/400 platforms that support the SMTP/MIME MTA, configuration of some transport level functions is performed by modifying the transport configuration portion of the Internet Message Transfer Agent (SMTP MTA) section in the Domino Server document. For the AS/400, the transport configuration portion of the Internet Message Transfer Agent section of the Domino Server document is ignored. Instead, configuration of the functions associated with these values can still be performed, but must be done through the AS/400 SMTP configuration interfaces as follows: 58 Installing and Managing Domino for AS/400

65 Host name mapping To change this parameter on the AS/400: 1. From an AS/400 command line, enter the following command: cfgtcp 2. Type a 12 (Change TCP/IP domain information) in the Opt column and press ENTER. 3. In the Host name search priority field, type the desired value. For help, position the cursor on the field and press the F1 key. Retry limit and retry interval To change this parameter on the AS/400: 1. From an AS/400 command line, enter the following command: cfgtcpsmtp 2. Type a 3 (Change SMTP attributes) in the Opt column and press ENTER. 3. In the Number of retries field, type the desired value. For help, position the cursor on the field and press the F1 key. 4. In the Time interval field, type the desired value. For help, position the cursor on the field and press the F1 key. Message sizes The AS/400 SMTP/MIME MTA breaks up messages that are above 126Kb. Unfortunately, some mail clients do not follow the SMTP/MIME recommendations for allowing the reassembly of split messages. You have two options available to avoid problems with these types of clients: Use the CHGPOPA command as follows: chgpopa msgsplit(2048) Use the CRTDTAARA command to create the data area, QTMSNOSPLT, of type *CHAR in the QUSRSYS library. The content of the data area is not important; the existence of the data area is. When you create the data area, the CHGPOPA MSGSPLIT parameter setting is ignored. SMTP outgoing messages are no longer split, regardless of their destination. AS/400 SMTP/MIME support will continue to reassemble any split incoming messages. Partitioning The SMTP/MIME MTA can be installed on more than one Domino server on a single AS/400, but can only be active on one of those Domino servers at a time. Chapter 2: Extending Domino for AS/400 59

66 Clustering The SMTP/MIME MTA can be run on clustered Domino servers, but you will not get the advantage of a cluster. Control section of the Server document The value for the MTA work path parameter must be an AS/400 integrated file system path. The QNOTES user profile must have access to this directory. For more information about the QNOTES user profile, see Chapter 5. SMTP Server Connection document The following fields are ignored by the AS/400 SMTP/MIME MTA: Connect via Destination domain Relay host About partitioned servers The partitioned server is an advanced services feature that allows multiple Domino servers to run on a single computer. You must have a Lotus Domino Advanced Services license to run a partitioned server. Partitioning a single computer into separate servers provides: Full Domino security for users of partitioned servers Reduced number of computers to own and administer in order to support independent groups of users Easy migration from partitioned servers to individual servers AS/400 requirements for partitioned servers To use partitioned servers on AS/400, you must: 1. Install the Advanced Services product option on AS/ Set up all Domino servers on AS/400 as partitioned servers. For example, if you use the AS/400 CFGDOMSVR command to set up a Domino server as a partitioned server, you must specify either *ALL or *PARTITION in the Advanced services field: Advanced services *partition If you previously configured a Domino server on AS/400 as a single server (not partitioned) and want to add a second server, you must reconfigure the first server as a partitioned server. 60 Installing and Managing Domino for AS/400

67 For more information about installing the Domino software and setting up the Domino server, see Chapter 1. For an example of reconfiguring a Domino server, see About changing a Domino server in Chapter 1. Configuring partitioned servers for the TCP/IP network There are two ways to configure partitioned servers for TCP/IP network access: Use one unique IP address for each partitioned server. Using separate IP addresses, you can have up to 16 partitioned servers on an AS/400. Have partitioned servers share an IP address and use one unique port number for each partitioned server that shares an address. Up to four partitioned servers can share an IP address on an AS/400. The simplest approach is to assign a unique IP address to each partitioned server. You can use the CFGTCP command to display a Configure TCP/IP menu that contains the options you need to set up TCP/IP on AS/400. Just enter this command on any AS/400 command line: cfgtcp For each partitioned server, you need to do the following: 1. Obtain an IP address and host name. 2. Update either the Domain Name Service (DNS) or the host table of each server and client with the IP address and host name of the server. You can use option 10 on the Configure TCP/IP menu to add IP addresses and their associated host names to the AS/400 TCP/IP configuration. 3. Add a TCP/IP interface that associates the IP address of the server with an AS/400 line description. Use option 1 on the Configure TCP/IP menu to add a TCP/IP interface. A line description identifies an AS/400 communications port. You can use the same line description that you used for the first server or you can create additional line descriptions for groups of servers. 4. Edit the NOTES.INI file and the Server document in the Public Address Book for each server and add the TCP/IP information. For more information about setting up partitioned servers, see Chapter 10 in the Extending the Domino System book or the Domino administrator help database (HELPADMN.NSF). For more information about changing the NOTES.INI file, see Editing the NOTES.INI file on AS/400 or Using Domino administrative functions in Chapter 3. Chapter 2: Extending Domino for AS/400 61

68 Chapter 3 Managing the Domino Server This chapter describes how to manage a Domino server running on AS/400. You can do most of the tasks from a Lotus Notes client on a workstation. You can do other tasks using AS/400 commands on AS/400 or the AS/400 Operations Navigator on a Notes workstation. Ways of managing a Domino server on AS/400 Typically, you manage a Domino server from a Notes client. The Notes client interface provides the full set of Domino administration functions. Because the Domino server on AS/400 does not have a local Notes client, you use a remote Notes client on a workstation to manage the Domino server. AS/400 also supports the Domino Web Administration tool. This tool allows you to perform a subset of the Domino administration tasks from a Web browser. For more information about Domino administration and the Web Administration tool, see Getting Started with the Domino Server or the Notes administrator help database (HELPADMN.NSF). To help you manage the Domino server, Domino for AS/400 allows you to use two alternative methods to perform common administration tasks: AS/400 commands. These commands allow you to interact directly with the AS/400 operating system (OS/400). Operations Navigator on a Notes workstation. Operations Navigator is part of the workstation support provided by AS/400 Client Access. You must use AS/400 commands or Operations Navigator to do a few Domino server tasks, such as starting the server or deleting the server. If you are familiar with AS/400, the commands provide a direct and convenient way of managing both AS/400 and a Domino server running on AS/400. You can run the commands from any display or workstation that is communicating with the OS/400 operating system. No additional setup is required. If you are more comfortable with the graphical user interface of Windows 95 or NT, you may prefer to use Operations Navigator. For some tasks, using Operations Navigator is easier than using commands or the Notes administrator functions. For example, the graphical interface of the 63

69 Operations Navigator allows you to quickly see the status of a Domino server or to add both a Notes user and an AS/400 user at the same time. However, the Operations Navigator does require AS/400 Client Access and additional setup on the workstation. Whether you use AS/400 commands or Operations Navigator to manage a Domino server, you must have an AS/400 user profile that has the necessary authority to perform each administrative operation. AS/400 authority requirements for Domino administrators Users who perform Domino administrative functions need authority to perform those functions. To help you plan the authority for your Domino administrators, think of the administrative tasks in two different categories: Domino-only administrative tasks These tasks occur within the Domino server when it is running. They do not require interaction with the AS/400 server environment outside of Domino. A Domino-only administrator does not need any special authorities on your AS/400. In fact, a Domino-only administrator does not even need an AS/400 user profile. Following are several examples of Domino-only administrative tasks: Creating a new Domino database From an OS/400 security perspective, a task such as creating a new Domino database runs under the QNOTES user profile. When the QNOTES user profile has proper authority to the Domino database directory, a Domino administrator (running as QNOTES) has the necessary authority to create a new object in the directory. Defining access to the database By default, Domino for AS/400 sets the authority for a new database correctly (from an OS/400 security perspective), so that the server can access Domino databases and public users cannot. The Domino administrator uses Domino functions to control access to the Domino databases when they are accessed through Domino. Creating Domino-only users Some users access only your Domino server. They do not need to access other AS/400 functions or objects. These users do not need an AS/400 user profile. Your Domino administrator can register these users through Domino. 64 Installing and Managing Domino for AS/400

70 Mixed administrative tasks These tasks require interaction with the AS/400 server environment. Domino administrators who use AS/400 commands or Operations Navigator to perform these tasks need an AS/400 user profile. Following are descriptions of these tasks and of the AS/400 authority these administrators need: Starting and stopping the Domino server From an AS/400 perspective, the administrator starts or stops both the server and the subsystem where the server job runs. The administrator can use either AS/400 commands or Operations Navigator. Both interfaces require *JOBCTL special authority to start and stop Domino servers. To give a user *JOBCTL special authority, change the special authority field in the user s profile. You can use either the Change User Profile (CHGUSRPRF) command or Operations Navigator to change a user s profile. Working with the Domino console The administrator can access the Domino console through either an AS/400 command (WRKDOMCSL) or Operations Navigator. The administrator can issue Domino server commands from this Domino console. To work with the Domino console, the administrator needs *USE authority to the QNNINCSS program and the WRKDOMCSL command in the QNOTES library. To grant this authority, type the following commands from an AS/400 command line: grtobjaut obj(qnotes/qnnincss) objtype(*pgm) user(admin-profile-name) aut(*use) replace(*yes) grtobjaut obj(qnotes/wrkdomcsl) objtype(*cmd) user(admin-profile-name) aut(*use) replace(*yes) By default, any AS/400 user can display the Domino console. Administrators need authority to the QNNINCSS program to be able to enter Domino server commands from the Domino console. Deleting the Domino server Deleting a Domino server deletes the data directory used by the server. The data directory may also contain user data. The administrator can use either an AS/400 command (CFGDOMSVR) or Operations Navigator to delete a Domino server. Both interfaces require *ALLOBJ, *IOSYSCFG, *JOBCTL, and *SECADM special authorities. To give a user these special authorities, change the special authority field in the user s profile. You can use either the Change User Profile (CHGUSRPRF) command or Operations Navigator to change a user s profile. Chapter 3: Managing the Domino Server 65

71 Deleting the Domino software The administrator can use an AS/400 command (DLTLICPGM) to delete the software. The command requires *ALLOBJ special authority. To give a user *ALLOBJ authority, change the special authority field in the user s profile. You can use either the Change User Profile (CHGUSRPRF) command or Operations Navigator to change a user s profile. Changing the NOTES.INI file The administrator can use either an AS/400 command (EDTF) or Operations Navigator to change the NOTES.INI file on AS/400. Both interfaces require either *ALLOBJ special authority or specific authority to change the file. To give a user *ALLOBJ special authority, change the special authority field in the user s profile. You can use either the Change User Profile (CHGUSRPRF) command or Operations Navigator to change a user s profile. To give a user specific authority to change the NOTES.INI file, use the Work with Object Links (WRKLNK) command to find the file path and then use option 9 to work with the authorities for the file (press F23 to display option 9). Overview of using AS/400 commands to manage a Domino server You can do all of the tasks needed to manage Domino servers on your AS/400 by using AS/400 commands in combination with the administrator functions available from a Notes client. Using the AS/400 commands, you can, either directly or indirectly: Start a Domino server Stop a Domino server Use the Domino console to display Domino server messages and issue Domino server commands Display server activities Determine if a server is active Edit the NOTES.INI file that controls the operation of a Domino server Delete a Domino server from AS/400 Delete Domino software from AS/ Installing and Managing Domino for AS/400

72 Starting a Domino server on AS/400 Use the Start Domino Server (STRDOMSVR) command to start a Domino server on AS/400. Make sure you have *JOBCTL special authority. 1. On any AS/400 command line, type: strdomsvr 2. Press the F4 key to have the system prompt you for the server name. 3. Type the server name in the field provided. If you are not sure of the name, press the F4 key to display a list of Domino servers on your AS/ Press ENTER. While the system is starting the Domino server, you see a message that indicates the server is starting. If the message appears for more than 1 or 2 minutes, the server may be waiting for you to enter a password. To determine if the server is waiting for a password, use the WRKDOMCSL command to start a server console session for the server. You can enter the password in this console session. For more information about a server console on AS/400, see Using the Domino console on AS/400. Also see Determining if the Domino server is active. Stopping a Domino server on AS/400 To stop a Domino server that you previously started on your AS/400, use either of the following: The Domino server Quit or Exit command The AS/400 End Domino Server (ENDDOMSVR) command The normal form of ENDDOMSVR command is the equivalent of using the Quit or Exit command. If the Quit or Exit command or the normal form of the ENDDOMSVR command fails to shut down the Domino server, you can use the ENDDOMSVR command again in a form that forces the server to stop immediately. However, forcing the server to stop immediately could cause data to be lost. You can enter the Quit or Exit server command from the Domino console on AS/400 or from the remote console on the administrator workstation. For more information, see Using the Domino console on AS/400. Chapter 3: Managing the Domino Server 67

73 You can enter the ENDDOMSVR command from any AS/400 command line. You must have *JOBCTL special authority to use the command. 1. Type: enddomsvr 2. Press the F4 key to have the system prompt you for details. 3. Type the server name in the field provided. If you are not sure of the server name, press the F4 key to display a list of Domino servers on your AS/ Specify one of the following for the option: *CNTRLD This option is the equivalent of using the Quit or Exit server command. *IMMED Use this option only if the Domino server fails to shut down after you try the *CNTRLD option or the Quit or Exit server command. This option forces the AS/400 to immediately end the AS/400 subsystem in which the Domino server is running, which stops all processing by the server. 5. Press ENTER. Using the Domino console on AS/400 Use the Work with Domino Console (WRKDOMCSL) command to open a console session with a Domino server. While this session is active, you can issue Domino server commands to the server and see the server s response. Make sure you have *ALLOBJ special authority or the specific authorities to run this command. 1. On any AS/400 command line, type: wrkdomcsl 2. Press the F4 key to have the system prompt you for the server name. 3. Type the server name in the field provided. If you are not sure of the server name, press the F4 key to display a list of Domino servers on your AS/ Press ENTER. 68 Installing and Managing Domino for AS/400

74 The console panel shows server events that occurred since the last time the Domino server was started. The events and responses to commands that are entered by a user are presented as one or more messages. User commands are indicated by a > symbol. Here is an example of one page of console information: 07/01/97 09:25:10 AM SchedMgr: Validating Schedule Database 07/01/97 09:25:26 AM Database Server started > show stat 07/01/97 09:25:54 AM SchedMgr: Done validating Schedule Database 07/01/97 09:25:54 AM SchedMgr: Calculating hourly statistics 07/01/97 09:25:54 AM SchedMgr: Done calculating hourly statistics Calendar.Total.All.Appts.Reservations = 0 Calendar.Total.All.Users.Resources = 0 Calendar.Total.Appts = 0 Calendar.Total.Reservations = 0 Calendar.Total.Resources = 0 Calendar.Total.Users = 0 MAIL.Dead = 0 Mail.Domain = Acme The console information is initially positioned to show the most recent events. You can use the PAGE UP key to display earlier events or the PAGE DOWN key to display more recent events. The F5 (Refresh) key updates the information with any additional events that occurred since you started the console session or last pressed the F5 key. To issue a Domino server command to the Domino server, type the command in the underlined entry area that follows the ===> symbol and press ENTER. For details on Domino server commands, see Getting Started with the Domino Server or the administrator help database (HELPADMN.NSF). The entry area on the console display accepts only server commands, not AS/400 commands. If you want to enter an AS/400 command while using the Domino console, press the F21 key to pop up an AS/400 command line. Press the F3 (Exit) key to end the console session. Ending the console session does not end the Domino server. Chapter 3: Managing the Domino Server 69

75 Only one user job can interact with a Domino server at a time. However, other users can use the DSPDOMCSL command to display server activities while one user is interacting with the server. Displaying Domino server activities on AS/400 Use the Display Domino Console (DSPDOMCSL) command to open a read-only console session. This session shows the messages that are generated by server activities. 1. On any AS/400 command line, type: dspdomcsl 2. Press the F4 key to have the system prompt you for the server name. 3. Type the server name in the field provided. If you are not sure of the server name, press the F4 key to display a list of Domino servers on your AS/ Press ENTER. The console information is initially positioned to show the most recent events. You can use the PAGE UP key to display earlier events or the PAGE DOWN key to display more recent events. The F5 (Refresh) key updates the information with any additional events that occurred since you started the console session or last pressed the F5 key. Press the F3 (Exit) key to end the console session. Determining if the Domino server is active You can easily determine if a Domino server is active by looking at the status of the server in Operations Navigator on your administrator workstation. There is no direct way of obtaining Domino status information from the AS/400. However, here are some ways of using AS/400 commands to determine if a Domino server is active. Use the DSPDOMCSL or WRKDOMCSL command to display the console for the Domino server. Then, starting with the last message, page backward and look for the latest messages that indicate server events are either starting or being shut down. If the most recent messages indicate that server events are starting, the server is active. If the most recent messages indicate that server events are being shut down, the server is not active. 70 Installing and Managing Domino for AS/400

76 Use the WRKDOMCSL command to display the server console. Enter the server command: show tasks If the server is active, it returns a list of active tasks. Use the Work with Active Jobs (WRKACTJOB) command. On any AS/400 command line, enter: wrkactjob On the resulting display, look for a subsystem name that begins with DOMINO ; for example, DOMINO01. Jobs listed under this subsystem name have a user name of QNOTES. If you do not see a DOMINOxx subsystem name, there are no active Domino servers on your AS/400. Editing the NOTES.INI file on AS/400 After you set up your Domino server on AS/400, you may need to add or change settings in the NOTES.INI file. The AS/400 Edit Files (EDTF) command provides a simple editor for changing a stream file such as the NOTES.INI file. You must have the AS/400 authority to change the NOTES.INI file. Caution Changing the NOTES.INI file is recommended only for experienced administrators. Changes to the NOTES.INI file can introduce errors into the file and impair the operation of a Domino server. 1. On any AS/400 command line, type: edtf 2. Press the F4 key. Tip The EDTF command is supplied in the QGPTOOLS library. If a message indicates that the command was not found, try typing qgptools/edtf. For OS/400 V4R2, the QGPTOOLS library is provided by PTF SF Type the path that identifies the location of the file in the AS/400 integrated file system. For example, if the NOTES.INI file is in the /NOTES/DATA directory, type: /notes/data/notes.ini The path for the Notes data directory is specified when the Domino server is set up. 4. Press ENTER. Chapter 3: Managing the Domino Server 71

77 5. While in the editing session, you can use the i line command to insert a line and the d line command to delete a line. 6. Use the F3 key to end the session and save the changes. Use the F12 key to end the session without saving the changes. Deleting a Domino server from AS/400 Use the Configure Domino Server (CFGDOMSVR) command to delete a Domino server from your AS/400 system. You must have the AS/400 special authorities to use this command. Caution Deleting a Domino server also deletes the data directory for the server. The data directory contains server files such as the Public Address Book and may contain user data. 1. On any AS/400 command line, type: cfgdomsvr 2. Press the F4 key. 3. On the resulting display, provide these details: Server name Type the name of the server you want to delete. Option Use the *REMOVE option. 4. Press ENTER. Deleting Domino software from AS/400 Use the Delete Licensed Program (DLTLICPGM) command to delete Domino software from your AS/400 system. You must have *ALLOBJ special authority to use this command. 1. On any AS/400 command line, type: dltlicpgm 2. Press the F4 key. 3. On the resulting display, provide these details: Product Type the following: 5769LNT Optional part to be deleted To delete the Domino server software (*BASE), use the default value *ALL. You cannot delete the *BASE option without also deleting all other Domino options. However, if you do not delete the *BASE option, you can specify an option number to delete a specific option. 4. Use the default values provided for the remaining fields. To see a description of the values for a specific field, press the F1 key while the cursor is on the field. 72 Installing and Managing Domino for AS/400

78 Overview of using Operations Navigator to manage a Domino server Operations Navigator enables you to use your Notes administrator workstation to manage both your AS/400 system and the Domino servers on your AS/400. Through the Domino for AS/400 support in Operations Navigator, you can: Determine the status of all Domino servers on AS/400 Use a simple drop-down menu to perform administrative tasks on a Domino server, such as starting and stopping the server, determining the properties of a server, and changing the NOTES.INI file for the server Operations Navigator works through the AS/400 Client Access support. Therefore, you must install Client Access on your AS/400 and the administrator workstation. For more information, see About adding Operations Navigator to your administrator workstation in Chapter 2 or About AS/400 Operations Navigator for Domino in Appendix A. Determining the status of a Domino server 1. Open the IBM AS/400 Client Access folder. 2. Click the Operations Navigator icon. 3. The AS/400 Operations Navigator window appears. Select the AS/400 that has the Domino server. 4. Click the + button to expand the directory. 5. Select Network and click the + button to expand the directory. 6. Select Servers and click the + button to expand the directory. 7. Right-click Domino and choose Explore. 8. A list of Domino servers appears. The Status column indicates the current condition of the server. Here are the possible status values and what they mean: Status Stopped Start submitted Starting Started Started and active Meaning All server tasks are stopped. The server is not active. The request to start the server tasks was submitted. The primary server tasks are beginning. The server is running. The server is running and can be accessed from a workstation. Chapter 3: Managing the Domino Server 73

79 Using Domino administrative functions 1. Open the IBM AS/400 Client Access folder. 2. Click the Operations Navigator icon. 3. The AS/400 Operations Navigator window appears. Select the AS/400 that has the Domino server. 4. Click the + button to expand the directory. 5. Select Network and click the + button to expand the directory. 6. Select Servers and click the + button to expand the directory. 7. Right-click Domino and choose Explore. 8. A list of Domino servers appears. Right-click the Domino server you want to manage. 9. A drop-down menu shows the administrative functions. Choose a function: 74 Installing and Managing Domino for AS/400

80 Start Choose Start to start the server. A message indicates the start operation was submitted for processing. It may take 2 to 5 minutes to start the Domino server. Use the Refresh button to see updated status. Note If the status does not change to Started and Active, the server may be waiting for you to enter a password. To determine if the server is waiting for a password, use the WRKDOMCSL command on your AS/400 to start a server console session for the server. You can enter the password in this console session. For more information, see Using the Domino console on AS/400 in this chapter. Stop Choose Stop to shut down the server. Stop Immediately Choose Stop Immediately to force the server to stop. The AS/400 immediately stops the subsystem in which the Domino server tasks are running. As a result, all processing stops on the server tasks. Use this function only if the Stop function fails to shut down the server. Forcing the server to stop immediately could cause data to be lost. Server Administration Choose Server Administration to display the Lotus Notes server administration panel. For more information about using the server administration panel, see Getting Started with the Domino Server. Delete Choose Delete to delete the Domino server from your AS/400. Caution Deleting a Domino server also deletes the data directory for the server. The data directory contains server files such as the Public Address Book and may contain user data. Chapter 3: Managing the Domino Server 75

81 Properties Choose Properties to display information about the server. Three tabs show different aspects of the server properties: Basics This dialog shows information such as the server s name and title. If the server is not active, some of the information is displayed as not available. Network Configuration This dialog shows network information for the server. The values on this page are set in the Public Address Book. You can only view this dialog when the server is active. The server s Public Address Book must be available to view this dialog. Initialization File This dialog shows a copy of the NOTES.INI file that runs when you start this Domino server. The system creates this initialization file automatically when you set up the server. Click the Edit button to change the NOTES.INI file. If you do not see the Edit button, you cannot change the file. Caution Changing the NOTES.INI file is recommended only for experienced administrators. Changes to the NOTES.INI file can introduce errors into the file and impair the operation of a Domino server. Make sure you want to change the file before continuing. About automatic Domino server restarts An exception (unhandled error) in the Domino server or add-in programs that run under the server usually leaves the server in an unpredictable condition. Therefore, if an exception occurs, Domino for AS/400 automatically cleans up the server and restarts it. The clean-up processing ends all server and add-in jobs. You can add two AS/400 environment variables to control this automatic recovery and the number of attempts to restart the server. The FaultRecovery environment variable specifies whether automatic recovery is on or off. When you set up a Domino server on AS/400, automatic recovery is on. If you want to turn off automatic recovery, set the FaultRecovery value to 0. For example, you may want to turn off automatic recovery to debug add-in jobs. 76 Installing and Managing Domino for AS/400

82 The AS400_DOMSVR_RESTART environment variable specifies the number of restart attempts after an exception occurs. Initially, Domino for AS/400 tries up to 10 times to restart the server after an exception. You can use AS400_DOMSVR_RESTART to change the value to a larger or smaller number. Use the Add Environment Variable (ADDENVVAR) or Work with Environment Variable (WRKENVVAR) command to add these environment variables and set their values. These environment variables affect only the Domino server that you start from the same job in which you define the environment variables. For example, to turn off automatic recovery for the Domino server named SERVER1: 1. Sign onto your AS/ Use the ADDENVVAR command to add the FaultRecovery environment variable and set its value to 0: addenvvar envvar('faultrecovery') value('0') 3. Start the server: strdomsvr server1 About copying files to the data directory Domino for AS/400 requires that the QNOTES user profile have authority to access the files in the Domino data directory. In addition, to prevent unauthorized access to Domino databases, the files should be owned by the QNOTES user profile and the public should be excluded from accessing the files. Domino databases created by the server are created with QNOTES as the owner and with the public excluded from access. If you put files into the data directory through means other than using the Domino server, you should: Change the owner of the files to QNOTES. Use the AS/400 Change Owner (CHGOWN) command to change the owner. Change the public authority (*PUBLIC) for the files to *EXCLUDE. Use the AS/400 Work with Object Links (WRKLNK) command to find the file path and then use option 9 to work with the authorities for the file (press F23 to display option 9). Chapter 3: Managing the Domino Server 77

83 Overview of managing the Domino SMTP/MIME MTA To properly manage the SMTP/MIME MTA for Domino on AS/400, you should be able to perform the following tasks: 1. Start the SMTP/MIME MTA. 2. Verify that the SMTP/MIME MTA is operational. 3. Stop the SMTP/MIME MTA. For more information, see About the SMTP/MIME MTA in Chapter 2. Starting the SMTP/MIME MTA There are several ways of starting the SMTP/MIME MTA on the AS/400: Manually from the AS/400 Domino console Manually from a remote Notes console Automatically as an add-in server task Manually from the AS/400 Domino console 1. From an AS/400 command line, enter the command to start a Domino console session: wrkdomcsl servername where servername is the name of the Domino server on AS/ On the Domino console, enter the server command: load smtpmta 3. Press F5 (Refresh) to see the response from the command. Repeat this procedure every time you start the Domino server, or if you end the MTA. Manually from a remote Notes console 1. From the workspace of your Notes administrative workstation, choose File - Tools - Server Administration from the pull-down menus. 2. Click the Console icon. 3. Enter the name of the AS/400 Domino server. 4. On the remote console, type the server command: load smtpmta 5. Click Send. Repeat this procedure every time you start the Domino server, or if you end the MTA. 78 Installing and Managing Domino for AS/400

84 Automatically as an add-in server task You can edit the NOTES.INI file on the AS/400 and add SMTPMTA in the ServerTasks= line. There are several methods for doing this. The recommended method is to use the Set Config command from a Domino or Notes console. 1. From either the Notes or Domino console, enter the command: Show Config ServerTasks. 2. Record the response from the command. (Press F5 to see the response if you are using the Domino console on AS/400.) For example, you should see a response similar to: SERVERTASKS=HTTP,Replica,Router,Update,Stats,AMgr,Adminp, Sched,CalConn,Event,Report,QNNINADD. 3. From the console, enter the Set Config ServerTasks command, but add the value SMTPMTA to the end of the list. For example, using the example from the previous step, the command would be: Set Config ServerTasks=HTTP,Replica,Router,Update,Stats,AMgr,Adminp,Sched, CalConn,Event,Report,QNNINADD,SMTPMTA. Once the change is successfully completed, the MTA tasks will start automatically whenever the AS/400 Domino server is stared. Verifying that the SMTP/MIME MTA is operational When the AS/400 SMTP/MIME MTA is operational, the following tasks should be active: The Delivery Report Task (DRT or DRTASK) This task deletes all messages that have been successfully sent or received. For messages that have experienced some kind of permanent failure, the DRT generates a Non-Delivery Report or Undeliverable Message Notification back to the sender. The DRT also notifies the administrator of any dead mail. The Inbound Message Conversion Task (IMSGCNV) This task converts messages received by the Inbound Session Handlers to a Domino object store format. It also converts the destination user address to a Domino object store format and checks that this address is deliverable. If the message is not convertible, or the address is not deliverable, the task indicates the message has failed delivery. This allows a Non-Delivery Report to be generated. If the message is not destined for Domino, the task puts a message into the work queue for the Outbound Transport. Chapter 3: Managing the Domino Server 79

85 The Add-In Controller Task (SMTPMTA) This Domino task is loaded on the Domino server. It acts as the control point for all other MTA tasks. The Outbound Message Conversion Task (OMSGCNV) This task converts Domino messages into an SMTP/MIME format ready for transmission. The Outbound Session Controller Task (OSESCTL) This task controls the transport of the converted messages to their respective SMTP destinations. The Outbound Session Handler(s) (OSESHLRn) These tasks are child processes of the OSESCTL task. These handlers perform the actual tasks of connecting to the destination or next hop in the SMTP system, delivering message(s) and posting back any errors. Note The OSESHLRn tasks only appear when mail is being sent. The Inbound Session Controller Task (ISESCTL) The task controls the receiving of messages from other SMTP systems. It listens on SMTP port 25 and accepts the initial incoming connection. It then notifies an Inbound Session Handler to take the connection so that it can listen for a new connection. The Inbound Session Handler(s) (ISESHLRn) These tasks accept incoming connections from the ISESCTL. They perform the SMTP protocol handshaking with the sending system and write the incoming data to the work queue. Note The ISESHLRn tasks only appear when mail is being received. There are several ways to determine if the AS/400 SMTP/MIME MTA tasks are active: From the AS/400 system. From the AS/400 Domino console. From a remote Notes console. From the AS/400 system 1. From an AS/400 command line, enter: wrkactjob 2. Look for the Domino subsystem under which your server is running. For example, DOMINO01. All AS/400 Domino servers run under a subsystem whose name begins with DOMINO and ends with a two-digit number. 80 Installing and Managing Domino for AS/400

86 3. Verify that the tasks listed above appear. Note The OSESHLRn and the ISESHLRn tasks only appear when mail is either being sent or received. From the AS/400 Domino console 1. From an AS/400 command line, enter: wrkdomcsl servername where servername is the name of the Domino server on AS/ On the Domino console, enter the server command: show tasks 3. Press F5 to see the response to the command. 4. Verify that the tasks listed above appear. Note The OSESHLRn and the ISESHLRn tasks only appear when mail is either being sent or received. From a remote Notes console 1. From workspace of a Lotus Notes administrative workstation, choose File - Tools - Server Administration. 2. Click the Console icon. 3. Enter the name of the AS/400 Domino server. 4. Type the command: show tasks 5. Click Send. 6. Verify that the tasks listed above appear. Note The OSESHLRn and the ISESHLRn tasks only appear when mail is either being sent or received. Stopping the SMTP/MIME MTA There are two ways of stopping the SMTP/MIME MTA on the AS/400: From the AS/400 Domino console. From a remote Notes console. From the AS/400 Domino console 1. From an AS/400 command line, enter: wrkdomcsl servername where servername is the name of the Domino server on AS/400. Chapter 3: Managing the Domino Server 81

87 2. On the Domino console, enter one of the following server commands: Tell SMTPMTA quit Tell SMTPMTA exit Tell SMTPMTA stop This command does not end the SMTPMTA add-in controller task. 3. Press F5 to see the response from the command. From a remote Notes console 1. From the workspace of a Lotus Notes administrative workstation, choose File - Tools - Server Administration. 2. Click the Console icon. 3. Enter the name of the AS/400 Domino server. 4. Enter one of the following server commands: Tell SMTPMTA quit Tell SMTPMTA exit Tell SMTPMTA stop This command does not end the SMTPMTA add-in controller task. 5. Click Send. 6. End the Domino server. When you end the Domino server, the MTA jobs also end in a controlled manner. 82 Installing and Managing Domino for AS/400

88 Chapter 4 Managing Domino Users When you add a Domino user, you may want that user to be an AS/400 user also. This chapter describes techniques and tools you can use to coordinate information on Domino and AS/400 users. About Domino for AS/400 users A Domino server on AS/400 can have three types of users: Domino-only users. These users connect to the Domino server from a Notes client or a browser. They do not use any AS/400 functions except the Domino for AS/400 server. These users do not need an AS/400 user profile. Domino and AS/400 users. These users connect to the server from a Notes client or a browser. They also access your AS/400 in others ways, such as with 5250 workstation emulation or Client Access. These users need both an AS/400 user profile and a Domino registration. Domino users who need DB2/400 access. These users might never appear to run an AS/400 application. However, they might use a Notes application that accesses DB2/400 data. Whether they need an AS/400 user profile depends on how you design your Notes application. Setting up Domino for AS/400 users When you set up a new Domino user on a server, the server application creates the following: A Person document in the server Public Address Book. An ID file for the user. The ID file contains the certificate that the Notes client uses to authenticate with the server. The user s workstation must have a copy of this ID file for the user to connect to the server successfully. 83

89 Two options are available for setting up Domino for AS/400 users: From a Notes client workstation connected to the Domino server, you can use the administration function that is part of Domino to set up a new user. This method does not create an AS/400 user profile for the Domino user. However, you can use the directory synchronization function to copy the user entries from the Domino Public Address book to the AS/400 system distribution directory. From an administrator workstation connected to the AS/400, you can use Operations Navigator to create an AS/400 user profile and register the user for Domino at the same time. You can also use this method to register an existing AS/400 user as a Domino user. An administrator workstation needs both a Notes client connection to the AS/400 and an AS/400 Client Access for Windows 95/NT connection to the AS/400. To create an AS/400 user profile, your Domino administrator s AS/400 user profile must have *SECADM special authority. To give a user *SECADM special authority, change the special authority field in the user s profile. You can use either the Change User Profile (CHGUSRPRF) command or Operations Navigator to change a user s profile. For details on directory synchronization, see About directory synchronization later in this chapter. Using Operations Navigator to add users Note In order to add or view users for a particular server, your current Notes user ID must be cross-certified on that server. Use the following steps to authorize an existing AS/400 user to use a Domino server. 1. In AS/400 Operations Navigator, click the + button next to Users and Groups to expand this section. 2. Click All Users to display a list of all users. 84 Installing and Managing Domino for AS/400

90 3. You can either add an existing AS/400 user as a Domino user or you can create a new AS/400 and Domino user at the same time. To add an existing AS/400 user as a Domino user, double-click the user you want to work with. This will bring up the user s properties. (You can also use the right mouse button and select properties.) Proceed to the next step. To create a new AS/400 and Domino user at the same time, right-click All Users and then select New User. (If the new user will be very similar to an existing user, it may be easier to right-click on the existing user and select New Based On.) This will bring up the User Properties or New User dialog which allows you to define AS/400 group, personal, security, and job information. When you are ready to register add the new user as a Domino server user, proceed to the next step. 4. Click the Networks button. 5. The Networks dialog appears. Select the Domino Registration tab. The dialog automatically searches each of the servers for the name of the user you selected based on the existing personal information. The registrations display as they are found, one per line. In the list, the server name appears on the left and the user s registration name appears on the right. If you want to see registrations for the current user on a particular server immediately, double-click the server name. Searching starts on that server. If you are not currently signed onto the server, you will be prompted for your password. 6. Select the server that you want to register the user on. Chapter 4: Managing Domino Users 85

91 7. You may be asked for a password. 8. Click Add. 9. Enter the information as required on the four pages. The Other tab allows you to specify where to save the user s ID file. Click OK to complete the registration. Status messages display as the process continues, which can take up to three minutes. A confirmation message appears to let you know that the user s id file has been created. Remember, you need to download the id file to the user s workstation. You may also copy the user id file to a diskette for the user. Tip For help on filling in the required fields, click the Help button. For additional information, see Planning the Domino System. 10. You can register the user on another server or select Cancel to return to the Networks dialog. 86 Installing and Managing Domino for AS/400

92 11. On the Networks dialog, select OK. The main user dialog displays. If you added an existing AS/400 user to the Domino server, the user properties dialog displays. Click OK. If you are creating a new AS/400 and Domino user, the new user dialog displays. Click Add. Viewing a user 1. In the Domino Registration tab, select the server where you want to view a user registration. 2. Click View to view the user properties read-only. About directory synchronization The Domino server and AS/400 each use a directory that contains information about people. These directories contain information such as name, department, phone numbers, address, company, and electronic mail address. In addition to containing information about users of your system or server, these directories often contain information about users on other systems or servers. The information about users on other systems or servers makes it easy to send them mail. AS/400 keeps this user information in the system distribution directory. Domino servers keep the user information in a Public Address Book, along with other information. Domino for AS/400 directory synchronization provides the capability to automatically synchronize the user information in a Domino Public Address Book with the user information in the AS/400 system distribution directory. By taking advantage of directory synchronization, you can avoid manually updating the user information in two places. You can think of directory synchronization as a form of replication that updates a Domino address book from the AS/400 directory, the AS/400 directory from a Domino address book, or both, based on your specifications. Directory synchronization is also similar to shadowing an AS/400 system distribution directory. Understand that directory synchronization only updates the directory information; it does not automatically authorize users to either the Domino server or AS/400. Chapter 4: Managing Domino Users 87

93 To determine whether directory synchronization is important for you, consider how you use or plan to use each directory. Here are some things to think about: Many AS/400 system functions use the AS/400 system distribution directory. You may have more entries in the directory than you realize. For example, Client Access and AS/400 OfficeVision users are always included in the system distribution directory. Use the Work Directory Entry (WRKDIRE) command to look at the list of entries in the system distribution directory. If there are many entries, you will probably want to use directory synchronization so that both directories are kept up to date. Your AS/400 system distribution directory may already include entries for people in other locations with whom you exchange electronic mail. By synchronizing directories, you make it easy for your Domino users to also send mail to those people. The Public Address Book on your Domino server may contain a large amount of information. Perhaps it was replicated from another Domino server. Directory synchronization can make this information available to AS/400 users. AS/400 directory synchronization is a powerful function that can help simplify the management of user directory information. However, as with any powerful tool, make sure you take time to understand the capabilities and to plan carefully so that the integrity of your directories is maintained. Be sure to consider how you are already using other similar functions. For example, you already may be using one or more of the following capabilities: Shadowing AS/400 system distribution directories between AS/400s Shadowing the AS/400 system distribution directory to an Domino server on an Integrated PC Server Replicating the Domino Public Address Book between Domino servers For more information about managing the AS/400 system distribution directory, see to the AS/400 book SNA Distribution Services (SC ). You set up directory synchronization through the Directory Sync Configuration database (NNDIRSYC.NSF) on the Domino server. Messages related to directory synchronization are written to the Directory Synchronization Log database (NNDILOG.NSF). If you have more than one Domino server on your AS/400 (partitioned servers), each server has its own NNDIRSYC.NSF and NNDILOG.NSF. 88 Installing and Managing Domino for AS/400

94 To use directory synchronization, you must install product option 1 (AS/400 Integration) and product option 6 (HiTest C API) of the Domino for AS/400 software. For details on installing the directory synchronization options, see Installing the Domino software in Chapter 1. Directory synchronization concepts To use directory synchronization, you need to understand several terms and concepts. Public Address Book Each Domino server uses a specific Public Address Book. A Public Address Book is the control and administration center for a group of Domino servers (a domain). This address book contains documents that provide information needed by the Domino servers. For example, the Public Address Book contains a Person document for each user of the Domino server. Each Person Document has a group of fields that have specific information about the user, such as last name, first name, middle initial, telephone number, postal mailing address, and address. AS/400 system distribution directory The AS/400 system distribution directory is like a Public Address Book for the AS/400. It contains user entries that are similar to the Person documents in a Domino Public Address Book. For example, an AS/400 directory entry contains fields for last name, first name, middle initial, telephone number, postal mailing address, and information for routing . Field mappings Because fields in the Domino Public Address Book contain the same type of user information as fields in the AS/400 system distribution directory, you can define direct relationships (mappings) between specific fields in the Domino address book and the AS/400 directory. Each field mapping is a link between a specific field in the Domino address book and a specific field in the AS/400 directory. During directory synchronization, the field mappings determine which information from the source directory or address book should go into which field in the target address book or directory. The directory synchronization function provides default field mappings that are already set up for you. These default mappings include the most commonly used fields, such as name, address, telephone, and company. You can remove mappings, specify additional mappings, or change the default mappings. You can also specify more than one mapping to a particular target field. If the first mapping does not produce a value for the target field, directory Chapter 4: Managing Domino Users 89

95 synchronization continues processing the mappings in the order listed until one of the mappings produces a value. You can also create a mapping that inserts a specified character string (rather than the value of a field) in a target field. For example, you might create a mapping to insert the character string xxx in the department name field of the Domino Public Address Book entry if the department name field in the system distribution directory is empty. Key mappings You must designate at least one field mapping as a key mapping. When you specify that a particular field mapping is a key mapping, the mapping target field is used by directory synchronization as a key field to distinguish one target directory entry from another. In the default set of field mappings, last name and first name are used as key mappings. If you have more than one person in your system distribution directory or Public Address Book with the same first name and last names, use additional key mappings to distinguish between them. For example, you could add a key mapping for department name. Make sure you have enough key mappings to clearly distinguish all entries. You can specify up to 10 key mappings with unique target fields. Fields that are used as the target of key mappings should always be filled in when a directory entry is created. If any key mapping field in an entry is empty, that entry is ignored during directory synchronization. Remember that a directory entry may be created directly by you or it may be created by directory synchronization as a result of an addition to the other directory. To help make sure that a target field for a key mapping is not left empty, you can provide multiple field mappings for the same target field, as described earlier. When you provide multiple mappings to the same key field, you must designate all of the mappings to that field as key mappings. You can create as many key mappings as you like using the same target field, but there can only be 10 unique fields that are the target of a key mapping. Configuration You set up directory synchronization by creating a configuration document in the Directory Sync Configuration database. In this configuration document, you define which fields are synchronized in the Domino Public Address Book and AS/400 system distribution directory. The configuration contains the following information: Field mappings The default field mappings are your starter set. You can add other mappings to the default set or delete mappings from this set. Key mappings Each configuration must have at least one field mapping designated as a key mapping. 90 Installing and Managing Domino for AS/400

96 Synchronization type The synchronization can be either one way (unidirectional) or two way (bidirectional). With unidirectional synchronization, you specify whether the AS/400 directory is used to update the Domino address book or the Domino address book is used to update the AS/400 directory. With bidirectional synchronization, both the AS/400 directory and the Domino address book are used to update each other. Use bidirectional synchronization if you want both the Domino address book and the AS/400 directory to remain synchronized whenever a change occurs in either of them. Synchronization status A configuration document can be Enabled, Suspended, or Disabled. Enabled While a configuration document is enabled, directory synchronization occurs as defined in the configuration. Only one configuration document can be enabled on your AS/400 at a time, even if your AS/400 has multiple partitioned servers. If you have multiple partitioned servers, you can use directory synchronization to keep one of the Public Address Books synchronized with the AS/400 system distribution directory and then use Domino replication to synchronize the Public Address Books between the servers. Suspended While a configuration document is suspended, directory synchronization does not occur for this configuration. Use the Suspended status when you want to make changes to either the AS/400 system distribution directory or the Domino address book that should not be reflected in the other directory. Do not use the Suspended status when you want to enable a different configuration. A Suspended configuration retains internal links between the AS/400 system distribution directory and the Domino address book. These links improve the startup performance if you later change the status to Enabled but can cause problems if you enable a different configuration. Disabled While a configuration document is disabled, directory synchronization does not occur for this configuration. No internal links are maintained between the entries in the AS/400 system distribution directory and the Domino Public Address Book. Use the Disabled status if you plan to enable a different configuration or if you want to edit the key mappings. Populate When you first set up a configuration for directory synchronization, the AS/400 system distribution directory and Domino address book probably contain different entries. Usually, you want them to have the same entries when you start directory synchronization. Therefore, you want to fill (populate) the AS/400 directory with entries from the Chapter 4: Managing Domino Users 91

97 Domino address book or populate the Domino address book with entries from the AS/400 directory. For bidirectional synchronization, you want to do both. If you do not select Populate, additions and changes to one directory are still reflected in the other directory as long as the configuration is enabled. However, directory entries that you do not change are never synchronized. If you temporarily suspend or disable a configuration, you may also want to use Populate when you change the configuration status to Enabled. As a result, changes that were made while the configuration was suspended or disabled are reflected in the other directory. If you choose to populate directories for bidirectional synchronization, you must choose either the AS/400 directory or the Domino address book as the master directory. The directory synchronization function first uses the entries in the master directory to populate the secondary directory and then uses the entries in the secondary directory to populate the master directory. You can also select a particular day and time when you want the populate operation to occur. Synchronize all users or selected users You can choose to synchronize all user entries or specific user entries that meet selection criteria. For example, you may want to synchronize only users who have specific names or users who are in a specific department. Preparing for directory synchronization 1. Make sure you have installed the Domino software that enables directory synchronization. For more information, see Installing the Domino software in Chapter Make sure the workstation that you use to set up directory synchronization: Has the required operating system and level of the Notes client Is communicating with the Domino server on AS/400 You can use the administrator workstation that you set up for the Domino server if it has the required operating system and Notes client. For more information, see About Lotus Domino for AS/400 system requirements and About installing Domino on AS/400 in Chapter Become familiar with the contents of the AS/400 system distribution directory and the Domino Public Address book. 92 Installing and Managing Domino for AS/400

98 Decide which fields in each directory are important to you and how you plan to use them. In which directory will you normally add new entries? Does either directory already contain many entries? Decide whether you want to use bidirectional or unidirectional synchronization. In most cases you will want to use bidirectional synchronization so that changes in either directory will be reflected in the other one. To view the contents of the AS/400 system distribution directory, use the Work with Directory Entries (WRKDIRE) command. To view a Domino Public Address Book, open your Notes desktop and choose File - Database - Open. Specify the name of your Domino server, select the Public Address Book for the domain, and click Open. 4. Become familiar with the default field and key mappings provided by the directory synchronization function. Open the directory synchronization database on the Notes desktop: Choose File - Database - Open. Select or specify the Domino server. Select Directory Sync Configuration (NNDIRSYC.NSF). Click Open. When you open the database, you see several options. The following options are the most useful in planning for directory synchronization: Default Field Mappings - Select this option to view the set of default field mappings provided for you. If you change the default mappings, the new defaults are used for any configuration documents you create in the future. Caution Do not delete all of the default field mappings. If you delete all mappings, you cannot create new directory synchronization configurations. Directory Fields - Select this option to view the fields that are available in either the AS/400 system distribution directory or the Domino Public Address Book. Decide whether the default mappings meet your needs or whether you need to make changes when you create your own directory synchronization configuration document. 5. Create a test version of your Domino address book (optional). Because there is only one copy of the AS/400 system distribution directory, you may want to create a small test version of your Domino address book to limit changes to the system distribution directory while testing your configuration. The Domino address book that you use for directory synchronization must be in the Notes data directory on the Chapter 4: Managing Domino Users 93

99 Domino server and must have the same format as the Public Address Book. 6. Back up your AS/400 system distribution directory and Domino Public Address Book. Here is an example of using the AS/400 SAVOBJ command to back up the system distribution directory to a tape device called TAP01: savobj obj(qaok*) lib(qusrsys) dev(tap01) objtype(*file) Here is an example of using the AS/400 SAV command to back up the Domino Public Address Book to a tape device called TAP01: sav dev('/qsys.lib/tap01.devd') obj('/notes/data/names.nsf') 7. Create and enable a directory synchronization configuration document for your test configuration. Carefully verify that your configuration is working as intended. 8. When you are ready to use directory synchronization in a production environment, edit the test configuration and change its status to Disabled. Then create a similar configuration for synchronizing the AS/400 system distribution directory and the production version of your Domino Public Address Book. Directory synchronization tips Do not replicate the Directory Sync Configuration database. Directory synchronization is a stand-alone application. Synchronization continues even when you shut down the Domino server. Disable a directory synchronization configuration before changing key mappings in the configuration. That is, first edit the configuration, change its status to Disabled, and save it. Then edit the configuration again, change the key fields, and save it. In some cases, you may want to stop or start the AS/400 synchronization jobs. When you stop the synchronization jobs, all directory changes are saved and will be synchronized when you restart the jobs. This is useful if you want to temporarily stop synchronization during a period of heavy system workload but still want changes reflected in the other directory at a later time. Also, if a Domino server error occurs, the directory synchronization jobs may not restart automatically even if the configuration is still enabled. 94 Installing and Managing Domino for AS/400

100 You can stop the directory synchronization jobs (QNNDIxxx) running in the QSYSWRK subsystem by issuing the following AS/400 command: call qnotesint/qnndiend You can restart the jobs by issuing the following command: call qnotesint/qnndistj Stopping or starting the directory synchronization jobs requires a user profile that has *JOBCTL special authority. Do not use the Set Secure command to password-protect the server console. If you do, the directory synchronization jobs will fail. If the server console is password-protected, use the Set Secure command to remove password protection and then restart the directory synchronization jobs. The Domino address book that you use in directory synchronization must be in the Notes data directory on the Domino server and must have the same format as the Public Address Book. Before enabling directory synchronization, make sure you back up the AS/400 system distribution directory and the Domino Public Address Book. Once you are using directory synchronization, you should always back up the AS/400 system distribution directory and the Domino Public Address Book at the same time. Before backing them up, stop synchronization by stopping the AS/400 synchronization jobs. Remember: directory synchronization does not stop when you stop the Domino server. The AS/400 system distribution directory is in the QUSRSYS library. When you back up all user libraries, the QUSRSYS library is backed up. When you use the option on the SAVE menu to back up all user data (option 23), the system backs up both the system distribution directory (in the QUSRSYS library) and the Domino Public Address Book (in a user directory in the integrated file system). If you ever change the AS/400 user ID delimiter, AS/400 host name, AS/400 domain name, or select Domino SMTP MTA configuration fields, you must edit and save the enabled directory synchronization configuration document. If you want the changes to take effect immediately for all AS/400 directory and Domino address book entries, choose Yes to populate directories when editing the configuration document. Directory synchronization only supports address books that have names of eight characters or less with an extension of three characters; for example, NAMES.NSF. Chapter 4: Managing Domino Users 95

101 Creating a directory synchronization configuration 1. Open the directory synchronization configuration database on the Notes desktop: Choose File - Database - Open. Select or specify the Domino server. Select Directory Sync Configuration (NNDIRSYC.NSF). Click Open. 2. Click Configurations and then Click New Configuration. 3. As needed, specify the file name of the Domino address book to be synchronized. For example, if you created a test address book named TESTSYNC.NSF, specify that name. 4. Choose a synchronization type and a synchronization status. Choose a status of Enabled if you want synchronization to occur. When finished, click Next. 5. Choose Yes for the Populate Directories option if any of the following is true: You chose AS/400-to-Domino synchronization and you want the Domino address book to contain all the selected entries that are in the AS/400 directory. You chose Domino-to-AS/400 synchronization and you want the AS/400 directory to contain all the selected entries (Person documents) that are in the Domino address book. You chose bidirectional synchronization and you want both the AS/400 directory and the Domino address book to contain the same entries. If you choose to populate directories, you must provide additional information: For bidirectional synchronization, select either the AS/400 system distribution directory or the Domino address book as the master directory. The master directory is used first to populate the other directory. Choose when the populate operation should be done; either immediately or at a specific day and time. 6. Click Next. If you chose AS/400-to-Domino synchronization or bidirectional synchronization, you see a panel for configuring the AS/400-to-Domino synchronization. If you chose Domino-to-AS/400 synchronization, you see a panel for configuring the Domino-to-AS/400 synchronization. 96 Installing and Managing Domino for AS/400

102 7. If you want to change the field or key mappings, click Edit field mappings. A panel shows the default field and key mappings. You can add, remove, or change field and key mappings. 8. Choose whether you want to synchronize all users or define criteria for synchronizing specific users. Then click Next. If you selected the option to synchronize specific users, you see a panel for defining the criteria. 9. If you chose bidirectional synchronization, you see a panel for configuring the Domino-to-AS/400 synchronization. You can choose to edit the Domino-to-AS/400 field mappings and define selection criteria as you did for the AS/400-to-Domino configuration. When finished, click Next. 10. Specify whether mail addressing information should be automatically synchronized. If you choose to maintain mail information, you may have to provide additional information: For bidirectional synchronization, select either the AS/400 system distribution directory or the Domino Public Address Book as the master mail directory. When an AS/400 system distribution directory entry and a Domino Public Address Book entry are synchronized for the first time, the information in the master mail directory replaces the mail information in the other directory. When changes are made to either of the directory entries at a later time, the changed information replaces the mail information in the synchronized directory entry, regardless of which directory is the master mail directory. For bidirectional synchronization or AS/400-to-Domino unidirectional synchronization with the populate option, specify how existing AS/400 SMTP addresses should be handled. If you choose to map existing AS/400 SMTP addresses during the populate operation, an existing SMTP address in an AS/400 directory entry is inserted after any existing values in the ShortName field of the corresponding entry in the Domino Public Address Book. Once the populate operation is completed, existing SMTP addresses are not mapped in subsequent populate operations. If you want to map existing AS/400 SMTP addresses during a bidirectional populate operation, it is best to select the AS/400 system distribution directory as the master directory. If you do not specify Chapter 4: Managing Domino Users 97

103 the AS/400 directory, directory synchronization displays a warning and allows you to change the master directory to the AS/400 directory. For bidirectional synchronization or Domino-to-AS/400 unidirectional synchronization, specify how unknown SMTP addresses in a Domino entry should be handled. You must indicate whether you want to maintain or reset the existing AS/400 SMTP information in an AS/400 directory entry if directory synchronization cannot determine the SMTP address of the synchronized entry in the Domino Public Address Book. If you choose to maintain the existing AS/400 SMTP information, none of the AS/400 directory entry mail information is changed. If you choose to reset the existing AS/400 SMTP information when the SMTP address of the Domino address book entry is unknown, the following changes are made to the synchronized AS/400 directory entry: (a) mail service level (MSFSRVLVL) and preferred address (PREFADR) are reset to the system default; (b) SMTP user ID (SMTPUSRID) and SMTP domain (SMTPDMN) are set to blanks. When you are finished, Click Next. 11. Specify any advanced options as needed. Then click Next. 12. When you see the completion panel, click Save and Close. Details: Creating a directory synchronization configuration Editing field mappings When you click the Edit field mappings button, the directory synchronization function shows you which fields are mapped between directories. You can change existing mappings, remove existing mappings, or insert new mappings. Directory synchronization processes the mappings in the order they are listed. Therefore, if you choose to add a mapping, you must specify whether it should be inserted before or after an existing mapping. When you edit or add a mapping, directory synchronization shows you entry areas for specifying the field to be mapped from and the field to be mapped to. To select the field to be mapped from, click the Add AS/400 Fields button or the Add Domino Fields button to display the available fields. Then select a field. To select the field to be mapped to, click the Find button. 98 Installing and Managing Domino for AS/400

104 When you edit or add a field mapping, you can also indicate the following: Whether the field mapping should be used as a key mapping. Remember that key mappings are processed in the order they are listed. Whether an AS/400 to Domino field mapping should add to or replace the current value in the Domino field. Domino address book fields typically allow more than one value. If you choose Add, the value from the AS/400 field is inserted before any existing values in the Domino field. The one exception is the FullName field; the value is inserted after any existing values. If you choose Replace, the value from the AS/400 field replaces all of the values in the Domino field. If a field allows only one value, the existing value is replaced regardless of whether you chose Add or Replace. Note To remove a field mapping, you must change the access control list for the Directory Sync database to allow deletions. Adding a field mapping For example, use the following procedure to add a mapping from an AS/400 field to a Domino field: 1. Select an existing field mapping at the point where you want to insert the new mapping. 2. Click Insert New Mapping Before or Insert New Mapping After. 3. Click Add AS/400 Fields to display the available AS/400 fields. 4. Select an AS/400 field. This field is the source for the mapping. Click Add > and then click OK. 5. Click Find to display the Domino fields. 6. Select a Domino field. This field is the target for the mapping. Click OK. 7. Indicate whether the field mapping should be used as a key mapping. Also indicate whether this mapping should add to or replace the value in the Domino address book. 8. Click Save and then click Close. 9. When you are finished editing field mappings, click Return. Tip You can specify more than one mapping to a particular target field. If there is more than one mapping to a field, directory synchronization processes the mappings in the order listed and uses the first mapping that produces a value. Chapter 4: Managing Domino Users 99

105 Adding a key mapping The default field mappings have two key mappings: the last name field and first name field. Use the following procedure to add sufficient key mappings to clearly distinguish between directory entries: 1. Double-click the field mapping that you want to designate as a key mapping. 2. Click Edit Mapping. 3. Indicate that the field mapping should be used as a key mapping. 4. Click Save and then click Close. Defining criteria for synchronizing users Instead of synchronizing all user entries in the AS/400 directory or Domino address book, you can define criteria for specific user entries or groups of user entries. 1. Choose Define criteria for synchronizing users. 2. Click Next. 3. Click Find and select a field. Then click OK. 4. Select a comparison condition. 5. Type the comparison value. 6. As needed to add more conditions, click AND or OR and repeat the previous three steps. 7. When you are done adding selection criteria, click Next. For example, the following criteria select all user entries in the system distribution directory that belong to department D123 or D456 in the Acme company: Selection Field Comparison Condition Comparison Value DEPT Equal d123 OR DEPT Equal d456 AND CMPNY Equal acme The comparisons are done in the order that you specify them. The comparison values are not case-sensitive. 100 Installing and Managing Domino for AS/400

106 Enabling directory synchronization Directory synchronization occurs only if the directory synchronization configuration is enabled. 1. Open the directory synchronization configuration database on the Notes desktop: Choose File - Database - Open. Select or specify the Domino server. Select Directory Sync Configuration (NNDIRSYC.NSF). Click Open. 2. Click Configurations. 3. Select the configuration document that you want to enable and click Edit Configuration. 4. Change the status of the configuration to Enabled. 5. Click Save and Close. Disabling or suspending directory synchronization Directory synchronization ends if you disable or suspend the directory synchronization configuration. 1. Open the directory synchronization configuration database on the Notes desktop: Choose File - Database - Open. Select or specify the Domino server. Select Directory Sync Configuration (NNDIRSYC.NSF). Click Open. 2. Click Configurations. 3. Select the configuration document for the configuration that you want to end and click Edit Configuration. 4. Change the status of the configuration to Disabled or Suspended. 5. Click Save and Close. Directory synchronization may take up to 5 minutes to end. Chapter 4: Managing Domino Users 101

107 What happens when a directory synchronization configuration is enabled When you specify a status of Enabled in a directory synchronization configuration document and then save the configuration document, the following occurs: For AS/400-to-Domino unidirectional synchronization When any entry that satisfies the selection criteria is changed in the AS/400 system distribution directory, the equivalent entry is immediately changed in the Domino address book. The key mapping fields in the configuration document define the equivalent entry in the Domino address book. For example: If an entry is added to the AS/400 system distribution directory, an equivalent entry is added to the Domino address book. If an entry is deleted from the AS/400 system distribution directory, the equivalent entry is deleted from the Domino address book. If the information is changed in an entry in the AS/400 system distribution directory, the equivalent entry is changed in the Domino address book. If you choose Yes for the Populate Directories option, entries from the AS/400 system distribution directory that satisfy the selection criteria are copied to the Domino address book as new or changed Person documents. This populate operation occurs at the specified day and time. For Domino-to-AS/400 unidirectional synchronization When any entry that satisfies the selection criteria is changed in the Domino address book, the equivalent entry is immediately changed in the AS/400 system distribution directory. The key mapping fields in the configuration document define the equivalent entry in the AS/400 system distribution directory. For example: If an entry is added to the Domino address book, an equivalent entry is added to the AS/400 system distribution directory. If an entry is deleted from the Domino address book, the equivalent entry is deleted from the AS/400 system distribution directory. If the information is changed in an entry in the Domino address book, the equivalent entry is changed in the AS/400 system distribution directory. 102 Installing and Managing Domino for AS/400

108 If you choose Yes for the Populate Directories option, entries from the Domino address book that satisfy the selection criteria are copied to the AS/400 system distribution directory as new or changed entries. This populate operation occurs at the specified day and time. For bidirectional synchronization When any entry that satisfies the selection criteria is changed in either directory (AS/400 system distribution directory or Domino address book), the equivalent entry is immediately changed in the other directory. The key mapping fields in the configuration document define the equivalent entries in the AS/400 system distribution directory and Domino address book. For example: If an entry is added to either directory, an equivalent entry is added to the other directory. If an entry is deleted from either directory, the equivalent entry is deleted from the other directory. If the information is changed in an entry in either directory, the equivalent entry is changed in the other directory. If you choose Yes for the Populate Directories option, entries from the master directory that satisfy the selection criteria are copied to the secondary directory as new or changed entries. Then, entries from the secondary directory that satisfy the selection criteria are copied to the master directory as new or changed entries. These populate operations occur at the specified day and time. Chapter 4: Managing Domino Users 103

109 Chapter 5 Managing Backup and Recovery This chapter describes how you implement backup and recovery for a Domino server running on AS/400. You use AS/400 commands to do the backup and recovery tasks. About backing up a Domino for AS/400 server A Domino server often contains important business information that may not exist elsewhere in your organization. For example, users may rely on for important communications that are not documented anywhere else. Similarly, an online customer service application might contain records that do not exist in printed form. To protect the data from disasters (such as a site loss or hardware loss) and from human error, such as accidentally deleting a critical database, develop a good strategy for regularly backing up the information on your Domino server. Make a plan to back up the following: Objects that change infrequently, such as programs for the Domino product. Backing Up the Domino Programs and Product Files describes options for backing up the relatively static (unchanging) parts of your Domino server. Objects that change regularly, such as Domino databases. Backing up all Domino databases describes the options for backing up the dynamic (changing) parts of your Domino server. Domino for AS/400 takes advantage of the AS/400 single-level store architecture. Domino databases and programs are spread across all the AS/400 disk units, along with other AS/400 objects. The OS/400 operating system automatically manages the allocation of disk space so that you do not have to. To back up information on AS/400, you back up logically (by library or directory), not physically (by disk unit). To plan a backup strategy, you need to understand the logical location of your Domino for AS/400 databases and programs. For more information, see Libraries and Directories for the Domino for AS/400 Product. 105

110 Note For more information about planning a backup strategy for your AS/400 system, using the Save menu, and using SAVxxx and RSTxxx commands, see the AS/400 Backup and Recovery book (SC ). This book comes with your OS/400 software. It is also available in the AS/400 softcopy library and on the Web. Libraries and directories for the Domino for AS/400 product AS/400 libraries contain programs for the Domino for AS/400 server product, programs that are available for your Domino developers to copy to their workstations, and customization information such as subsystem descriptions. The following table lists the Domino libraries: Item AS/400 Library Path for Library Domino for AS/400 product QNOTES /qsys.lib/qnotes.lib Directory synchronization QNOTESINT /qsys.lib/qnotesint.lib C APIs QNOTESAPI /qsys.lib/qnotesapi.lib C++ APIs QNOTESCPP /qsys.lib/qnotescpp.lib HiTest APIs QNOTESHTST /qsys.lib/qnoteshtst.lib LotusScript Extensions QNOTESLSKT /qsys.lib/qnoteslskt.lib Customization information (such as subsystem descriptions and job descriptions) QUSRNOTES /qsys.lib/qusrnotes.lib Directories in the AS/400 integrated file system contain product information, customization files, and databases. The following table lists the Domino directories: Item Product information Customization information Directory for databases on the server Path /QIBM/ProdData/Lotus/Notes /QIBM/UserData/Lotus/Notes Specified when you set up the server (usually /NOTES/DATA) Backing up Domino programs and product files After you install the Domino for AS/400 product, including its optional features, you should save a copy of the product offline. You should also save a copy of the product periodically, for example when you update to a new release or apply fixes. Following are two options for backing up the libraries and directories that contain the relatively static information for your Domino for AS/400 server. Note If your AS/400 is already running other applications, you probably already use one of these options. 106 Installing and Managing Domino for AS/400

111 To back up your entire AS/400 system, including your Domino programs, product files, and databases, use option 21 (Entire system) from the Save menu. You access the Save menu by typing GO SAVE from a command line of an AS/400 session. To back up only product libraries and directories that contain information for AS/400 licensed programs, including Domino for AS/400, use option 22 (System data only) from the Save menu. (Option 22 saves the QNOTESxx libraries and the /QIBM/ProdData/Lotus/Notes directory.) Backing up all Domino databases Develop a plan to back up all Domino databases, including users mail databases and system databases, such as the Public Address Book. When you configure a Domino server, you specify the directory for that server, such as /NOTES/DATA. By default, all the databases for the server are in that path. Your Domino administrators might have the authority to place a Domino database in another path (by using an integrated file system command). Typically, end-users cannot create Domino databases in any location except the default path for the server. If you are responsible for backing up a Domino for AS/400 server, you should develop a backup strategy that matches your policy for where information is stored. Choose one of the following: Limiting the location of Domino databases Use a combination of policies and security to keep all Domino databases within the default directory (path) for the Domino server. With this approach, you need to back up only the data directory and the directory that contains customization information (/QIBM/UserData/Lotus/Notes). Following is an example of the steps to back up the data directory for your Domino for AS/400 server and the directory with customization information. Substitute the name of your tape device for TAP01 and the name of your Domino server data directory for /NOTES/DATA. 1. Sign on to your AS/400 using a user profile that has *JOBCTL and *SAVSYS special authorities. 2. To ensure that you get a complete copy of your server, you must stop the server before you start the save operation. Use the following command: enddomsvr server(servername) where servername is the actual name of your Domino server. Chapter 5: Managing Backup and Recovery 107

112 3. If you are using directory synchronization, stop the directory synchronization jobs. Use the following command: call qnotesint/qnndiend 4. To back up the directories, use the following command. Substitute your directory name for /NOTES/DATA. sav dev('/qsys.lib/tap01.devd') obj(('/notes/data/*') ('/QIBM/UserData/Lotus/Notes/*')) Note If you already use option 21 or option 23 from the Save menu regularly, you do not need to back up your Domino server separately. 5. If you are using directory synchronization, back up the AS/400 system distribution directory files (so they are at the same level on your backup tapes as the Domino Public Address Book). Use the following command: savobj obj(qaok*) lib(qusrsys) objtype(*file) dev(tap01) 6. If you are using directory synchronization, restart the directory synchronization job after your backup procedure is complete. Use the following command: call qnotesint/qnndistj Backing up everything With this approach, you assume that Domino databases might exist anywhere in the integrated file system (in either the root directory or the /QOpenSys directory). Therefore, you need to back up the entire root directory and /QOpenSys directory. Use any of the following methods: Back up your entire system (option 21 from the Save menu). Back up all user data (option 23 from the Save menu). Use the SAV (Save Object) command to back up everything except the QSYS.LIB file system, the QDLS file system, and directories that contain static program product information. Substitute your tape device name for TAP01. sav dev('/qsys.lib/tap01.devd') obj(('/*') ('qsys.lib' *omit)('/qdls.lib' omit) ('/QIBM/ProdData' *omit) ('QOpenSys/QIBM/ProdData' *omit)) updhist(*yes) Note When you use option 21 or 23 from the Save menu, the system automatically stops all activity (goes to a restricted state). When you use commands (instead of the Save menu) to back up your server information, you must stop the server before you back up. This ensures that the databases are in a known state for the backup operation. You can use the End Domino Server (ENDDOMSVR) command to stop the 108 Installing and Managing Domino for AS/400

113 server. If you use directory synchronization, you should also stop the directory synchronization job before you back up using commands. See the instructions in the previous topic. Backing up mail databases This topic describes specifically how to back up mail from your Domino for AS/400 server. If you already have a strategy for backing up all the user information from your Domino server, you probably do not need a separate procedure for backing up only mail. However, you might discover that your backup interval for your entire server is not frequent enough for because mail is so volatile. Your Domino server stores mail in multiple databases: The MAIL.BOX database on each server contains mail for the server to route to individual user mailboxes or to another server. Each Lotus Notes user has an individual mail database. The name of the mail database is typically the user s ID with the NSF extension. (The Domino administrator has the option to use different names for mail databases.) For example, the mail database for user GNELSON is GNELSON.NSF. Typically, all the individual mail databases are in a dedicated subdirectory, such as /NOTES/DATA/MAIL. To back up mail, do the following: 1. Sign on to your AS/400 using a user profile that has *JOBCTL and *SAVSYS special authorities. 2. From a command line, use the following command to stop the Domino server: enddomsvr server(servername) where servername is the actual name of your Domino server. To back up a database, the AS/400 must be able to lock the database so that no changes occur during the backup operation. To successfully back up Notes mail, you will need to stop the Domino for AS/400 server that contains the mail databases. 3. Mount the appropriate backup tape in the tape device. 4. Use the Save Object (SAV) command to back up the mail databases. Following is an example. Substitute your server directory name for /NOTES/DATA. Substitute your tape device name for TAP01. sav dev('/qsys.lib/tap01.devd') obj('/notes/data/mail/*.nsf') Chapter 5: Managing Backup and Recovery 109

114 Examples: Backing up mail from your Domino server Following are examples of using the Save Object (SAV) command to back up mail from your Domino server. Substitute your server directory name for /NOTES/DATA. Substitute your tape device name for TAP01. To back up a specific database, such as the MAIL.BOX database, use the following command: sav dev('/qsys.lib/tap01.devd') obj('/notes/data/mail/mail.box') To back up all the files of a specific type in the MAIL subdirectory, use the following command: sav dev('/qsys.lib/tap01.devd') obj('/notes/data/mail/*.nsf') To back up a specific user s mail database, such as GNELSON s mail database, use the following command: sav dev('/qsys.lib/tap01.devd') obj('/notes/data/mail/gnelson.nsf') Notes about the examples 1. To back up a database, the AS/400 must be able to lock the database so that no changes occur during the backup operation. To successfully back up Notes mail, do one of the following before you use the SAV command: Stop the Domino for AS/400 server that contains the mail databases. (Use the ENDDOMSVR (End Domino Server) command to stop the server.) Stop activity on the databases file by using drop all and dbcache flush. However, with this method, any attempted mail delivery during the backup operation results in the mail being returned to the user with a message that the server is busy/in use. 2. To reduce the downtime of your server during backups, use clustered servers. AS/400 can support clustered servers on the same system. Backing up specific databases You might want to back up a specific Domino database to tape for several reasons. For example: To create a backup copy before you make programming changes or test a new agent. To create an archive copy at the end of an accounting period. 110 Installing and Managing Domino for AS/400

115 To back up a specific database or group of databases from your Domino for AS/400 server, do the following: 1. Sign on to your AS/400 using a user profile that has *JOBCTL and *SAVSYS special authorities. 2. Ensure that no one is using the database. You want a copy at a known point when no changes are occurring to the database. 3. Mount a tape for the backup operation. 4. Use the SAV (Save Object) command for the database. For example, to back up a database called CUSTINF.NSF in the /NOTES/DATA directory, use the following command. Substitute your tape device name for TAP01: sav dev('/qsys.lib/tap01.devd') obj('/notes/data/custinf.nsf') Examples: Backing up a specific Domino database Following are examples for using the Save Object (SAV) command to back up specific Domino databases to tape. Substitute your server directory name for /NOTES/DATA. Substitute your tape device name for TAP01. To back up all the Domino databases in the DEPT57 subdirectory (folder), use the following command: sav dev('/qsys.lib/tap01.devd') obj('/notes/data/dept57/*.nsf') To back up the HRINFO database from the HRDPT directory, use the following command: sav dev('/qsys.lib/tap01.devd') obj('/notes/data/hrdpt/hrinfo.nsf') To back up all the HR files (not in a specific subdirectory), use the following command: sav dev('/qsys.lib/tap01.devd') obj('/notes/data/hr*.nsf') Notes about the examples 1. To back up a database, the AS/400 must be able to lock the database so that no changes occur during the backup operation. Either make sure that no one has the database open or stop the server for the backup operation. 2. To reduce the downtime of your server during backups, use clustered servers. AS/400 can support clustered servers on the same system. Chapter 5: Managing Backup and Recovery 111

116 Backing up changed objects from your Domino for AS/400 server AS/400 provides the capability to back up only objects that have changed either since a specific date and time or since the last backup operation. This type of backup capability is sometimes called an incremental backup. You might find a combination of complete backup and incremental backup particularly useful if your Domino server has many databases that do not change very often. Strategies for incremental backup Following are the two most common strategies for incremental backups: Backing up changes since last full backup. With this strategy, you back up everything that has changed since you last backed up all the databases from your Domino server. For example, assume that you back up your entire server on Saturday night. On Sunday night, you would back up everything that has changed since Saturday night. On Monday night, you would back up everything that has changed since Saturday night. On Tuesday night, you would back up everything that has changed since Saturday night. And so on. The advantage to this strategy is that it makes recovery simple. When you need to recover, you need to use only your tapes from your full backup and your tapes from your most recent incremental backup. The disadvantage to this strategy is that your backups grow larger (both in media usage and duration) each day until your next complete backup. Backing up changes since the last incremental backup. With this strategy, you back up only objects that have changed since the most recent backup. For example, assume that you back up your entire server on Saturday night. On Sunday night, you would back up everything that has changed since Saturday night. On Monday night, you back up everything that has changed since Sunday night. On Tuesday night, you back up everything that has changed since Monday night. And so on. The advantage to this strategy is that the size of your incremental backup is smaller (both in media usage and duration). The disadvantage is that recovery is more complex. When you need to recover, you need to use your tapes from your full backup and your tapes from each incremental backup. 112 Installing and Managing Domino for AS/400

117 Examples: Backing up changed objects from your Domino for AS/400 server Following are examples for backing up changed objects from your Domino server. Substitute your server directory name for /NOTES/DATA. Substitute your tape device name for TAP01. Backing up all changes (since previous full backup) To perform a nightly incremental backup of all changes that have occurred since that last full backup, do the following: 1. On Saturday evening, perform a complete backup (for example, by using option 23 from the Save menu). Make sure that you specify UPDHST(*YES) on the SAV command so that the system updates the object information with the time and day of the most recent backup. 2. On Sunday evening, use the following command: sav dev('/qsys.lib/tap01.devd') obj('/notes/data/*.*') chgperiod(*lastsave) updhst(*yes) 3. On Monday evening, use the following command: sav dev('/qsys.lib/tap01.devd') obj('/notes/data/*.*') chgperiod(*lastsave) updhst(*yes) Continue using the same command every night until your next full backup. Backing up one day s changes To perform a nightly incremental backup of what has changed since the previous incremental backup, you need to adjust the CHGPERIOD parameter each night. Following is an example: 1. On Saturday evening at 8 PM, perform a complete backup (for example, by using option 23 from the Save menu). Make sure that you specify UPDHST(*YES) on the SAV command so that the system updates the object information with the time and day of the most recent backup. 2. On Sunday evening, November 9 at 10 PM, use the following command: sav dev('/qsys.lib/tap01.devd') obj('/notes/data/*.*') chgperiod('11/08/97' ) updhst(*yes) 3. On Monday evening, November 10 at 9 PM, use the following command: sav dev('/qsys.lib/tap01.devd') obj('/notes/data/*.*') chgperiod('11/09/97' ) updhst(*yes) Chapter 5: Managing Backup and Recovery 113

118 4. On Tuesday evening, November 11 at 8 PM, use the following command: sav dev('/qsys.lib/tap01.devd') obj('/notes/data/*.*') chgperiod('11/10/97' ) updhst(*yes) 5. Each evening, run the SAV command. Alter the Change Period parameter to the time and date of the previous backup. Notes about the examples 1. To back up a database, the AS/400 must be able to lock the database so that no changes occur during the backup operation. To successfully back up Domino databases, you must either ensure that no one is using the databases or stop the Domino for AS/400 server that contains the databases. (Use the ENDDOMSVR (End Domino Server) command to stop the server.) 2. To reduce the downtime of your server during backups, use clustered servers. AS/400 can support clustered servers on the same system. Recovery of Domino for AS/400 Domino for AS/400 programs and product files reside in libraries in the QSYS.LIB file system on your AS/400. Domino databases reside in the integrated file system in a directory path that you specify when you configure your server. Your backup strategy for Domino for AS/400 should include backing up both the libraries (infrequently) and the database directories (frequently). You might need to recover Domino for a variety of reasons, for example: Damage to your server, such as fire or flooding Hardware problems, such as a disk failure Note AS/400 provides disk protection options (mirrored protection and device parity protection) both to increase availability and to ensure that disk failures do not cause loss of data. You can find out more about disk protection in the AS/400 Backup and Recovery book (SC ). User or operator error, such as deleting a database or running a month-end procedure twice 114 Installing and Managing Domino for AS/400

119 Sometimes, you must recover your entire server. Other times, you must recover a specific directory. The topics discussed below provide general information about recovery steps for Domino for AS/400. Recovering an entire Domino server Recovering Domino mail Recovering Domino databases Restoring changed objects to a Domino server For complete procedures and considerations, see the AS/400 Backup and Recovery book and the Domino documentation. Recovering an entire Domino for AS/400 server If you are faced with a system disaster, such as a site loss or the failure of an unprotected disk unit, you must recover (restore) your entire AS/400 system from a backup. Because AS/400 is a highly integrated system, you must recover objects in the correct sequence to rebuild the proper links between objects. The AS/400 Backup and Recovery book (SC ) provides complete instructions for performing a full system recovery. If you are faced with a problem that requires recovering only your Domino for AS/400 server, not your entire AS/400 system, you can use the Restore Object (RST) command to recover your Domino directories from tape. Following is an example of the steps: 1. Sign on your AS/400 using a user profile that has *SAVSYS and *JOBCTL special authority. 2. To make sure that no one is using the server that you plan to recover, stop the server. Use the End Domino Server (ENDDOMSVR) command. 3. If you use directory synchronization, stop the directory synchronization function. Use the following command: call qnotesint/qnndiend 4. Mount the tape that has the most recent backup copy of the directories for the server. 5. Use the appropriate restore (RST) command for your Domino directory. For example, if your Domino directory is /NOTES/DATA and your tape device is TAP01, use the following command: rst dev('qsys.lib/tap01.devd') obj('/notes/data/*') 6. If you use directory synchronization, you should also recover the AS/400 system distribution directory. Chapter 5: Managing Backup and Recovery 115

120 This process restores the physical contents of the data directory for your server to your AS/400 disk storage. Consult Domino documentation for any special recovery activities that you might need to perform after you have restored the directories. Recovering Domino Public Address Books If you use directory synchronization between your Domino Public Address Book and your AS/400 system distribution directory, special considerations apply during recovery. If possible, you should recover both the Domino Public Address Book and the AS/400 system distribution directory from backup tapes that were created at the same time. If you cannot recover them both from a matching backup, you need to use the populate capability of directory synchronization to ensure that they match. To recover the AS/400 system distribution directory, do the following: 1. To stop the directory synchronization function, use the following command: call qnotesint/qnndiend 2. Use the following restore command: rstobj obj(qaok*) savlib(qusrsys) objtype(*file) dev(tap01) 3. When your recovery is complete, use the following command to restart directory synchronization: call qnotesint/qnndistj For more information on directory synchronization, see About directory synchronization in Chapter 4. Recovering Domino mail If you need to recover one or more mail databases from your backup tapes, use the Restore Object (RST) command. Following is an example of the steps: 1. Sign on with a user profile that has *SAVSYS and *JOBCTL special authority. 2. Stop the server that contains the mail databases that you want to recover; for example, use the End Domino Server (ENDDOMSVR) command. 3. Mount the tape that has the most recent backup of the mail databases. 4. Use the appropriate Restore Object (RST) command for the mail databases that you want to recover. For example, to recover all the databases to the MAIL subdirectory from device TAP01, use the following command. rst dev('/qsys.lib/tap01.devd') obj('/notes/data/mail/*') 116 Installing and Managing Domino for AS/400

121 Examples: Recovering Domino mail The name of a user s mail database is usually the user s ID (short name) with the.nsf extension. (The Domino administrator has the option to use different names for mail database files.) To recover a specific user s mail database, such as the mail database for user GNELSON, use the RST command and specify the database name: rst dev('/qsys.lib/tap01.devd') obj('/notes/data/mail/gnelson.nsf') You can specify more than one file on the RST command. To recover mail databases for GNELSON, LSMITH, and JPETERS, use the following command: rst dev('/qsys.lib/tap01.devd') obj(('/notes/data/mail/gnelson.nsf') ('/notes/data/mail/lsmith.nsf') ('/notes/data/mail/jpeters.nsf')) Notes about the examples 1. You cannot restore over a database that is in use. All users must close the database before you can restore a backup copy. 2. All of the examples assume that the directory for your Domino server is /NOTES/DATA. 3. Substitute the name of your AS/400 tape device for TAP01. Recovering Domino databases You might need to recover a specific Domino database or a group of databases. Use the Restore Object (RST) command. Following is an example of the steps for recovering all the files to the HRDPT subdirectory: 1. Sign onto your AS/400 using a user profile that has *SAVSYS and *JOBCTL special authority. 2. Stop the server that contains the databases that you want to recover. Use the End Domino Server (ENDDOMSVR) command. (You can restore a database when the server is running. However, you need to make sure that no one is using the database. Stopping the server is the best way to ensure that no one is using the database.) 3. Mount the tape that has the most recent backup of the databases. 4. Use the appropriate Restore Object (RST) command for the mail files that you want to recover. For example, to recover all the files to the HRDPT subdirectory from device TAP01, use the following command: rst dev('/qsys.lib/tap01.devd') obj('/notes/data/hrdpt/*.nsf') Chapter 5: Managing Backup and Recovery 117

122 Examples: Recovering Domino databases In the examples, substitute your server directory for /NOTES/DATA. Substitute your tape device name for TAP01. To recover a specific database named HRINFO to the HRDPT subdirectory (folder), use the following: rst dev('/qsys.lib/tap01.devd') obj('/notes/data/hrdpt/hrinfo.nsf') To recover all the Domino databases to the CUSTSVC subdirectory, use the following: rst dev('/qsys.lib/tap01.devd') obj('/notes/data/custsvc/*.nsf') To recover all the Domino databases whose name begins with INV to the main directory for your server, use the following: rst dev('/qsys.lib/tap01.devd') obj('/notes/data/inv*.nsf') Note You cannot restore over a database that is in use. All users must close the database before you can restore a backup copy. The best way to ensure that databases are not in use is to stop the server. Recovering changed objects to a Domino for AS/400 server To reduce the length of your backup window, your backup strategy might include backing up only changed objects from your Domino server during the business week. When you need to use these backup tapes to recover, you must decide on your recovery sequence and determine the location of the most recent copy of each database. Examples: Recovering changed objects to a Domino server Following are examples of different recovery scenarios and an overview of the recovery steps for each. Substitute your server directory for /NOTES/DATA. Substitute your tape device name for TAP01. Recovering all changed Domino objects from a cumulative backup Assume that your strategy for backing up changed objects is cumulative (each night you back up everything that changed since the last complete backup). To recover your entire Domino data directory, do the following: 1. Sign onto your AS/400 using a user profile that has *JOBCTL and *SAVSYS special authorities. 2. To ensure that no one is using the databases, stop the Domino server; for example, use the End Domino Server (ENDDOMSVR) command. 3. Locate the tapes from your most recent complete backup. Mount the correct tape in the tape unit. 118 Installing and Managing Domino for AS/400

123 4. To recover the entire Domino data directory, use the Restore Object (RST) command. For example, rst dev('/qsys.lib/tap01.devd') obj('/notes/data/*') Substitute your Domino data directory for /NOTES/DATA and your tape device name for TAP Locate and mount your most recent backup tapes (from backing up changed objects). 6. To recover all the changed objects on the tape (everything that has changed since your full backup), use the following command: rst dev('/qsys.lib/tap01.devd') obj('/notes/data/*') Substitute your Domino data directory for /NOTES/DATA and your tape device name for TAP01. Recovering all changed Domino objects from a nightly backup Assume that your strategy for backing up changed objects is nightly (each night you back up only objects that have changed since the previous night). To recover your entire Domino directory, do the following: 1. Sign onto your AS/400 using a user profile that has *JOBCTL and *SAVSYS special authorities. 2. To ensure that no one is using the databases, stop the Domino server; for example, use the End Domino Server (ENDDOMSVR) command. 3. Locate the tapes from your most recent complete backup. Mount the correct tape in the tape unit. 4. To recover the entire Domino database directory, use the Restore Object (RST) command. For example, rst dev('/qsys.lib/tap01.devd') obj('/notes/data/*') Substitute your Domino data directory for /NOTES/DATA and your tape device name for TAP Locate and mount your first backup tapes (from backing up changed objects). For example, if you back up everything on Saturday night, locate your backup tapes from Sunday night. 6. To recover all the changed objects on the tape (everything that has changed since the previous night), use the following command: rst dev('/qsys.lib/tap01.devd') obj('/notes/data/*') Substitute your Domino data directory for /NOTES/DATA and your tape device name for TAP Repeat steps 5 and 6 for each nightly backup tape until your directory is current. For example, if you are recovering on Thursday, you need to use the tapes for Monday, Tuesday, and Wednesday nights. Chapter 5: Managing Backup and Recovery 119

124 Recovering a specific Domino database from an incremental backup To recover a specific database named HRINFO to the HRDPT subdirectory (folder), do the following: 1. Sign onto your AS/400 using a user profile that has *JOBCTL and *SAVSYS special authorities. 2. To ensure that no one is using the databases, stop the Domino server; for example, use the End Domino Server (ENDDOMSVR) command. 3. Locate the most recent tape that has the database. Do one of the following: Consult the log that the system creates during the save operation. Use the Display Tape (DSPTAP) command to display the contents of the tape. 4. Mount the tape in the tape unit. 5. To recover the database, use the following command: rst dev('/qsys.lib/tap01.devd') obj('/notes/data/hrdpt/hrinfo.nsf') Substitute your tape device name for TAP01. Recovering changed objects to a specific Domino subdirectory To recover all the Domino databases to the CUSTSVC subdirectory, use the same approach that you use to recover the entire server. Do the following: 1. Sign onto your AS/400 using a user profile that has *JOBCTL and *SAVSYS special authorities. 2. To ensure that no one is using the databases, stop the Domino server; for example, use the End Domino Server (ENDDOMSVR) command. 3. Locate the tapes from your most recent complete backup. Mount the correct tape in the tape unit. 4. To recover the entire directory from the tapes from your last full backup, use the RST (Restore Object) command. For example, to recovery objects in the CUSTSVC subdirectory from the TAP01 device, use the following command: rst dev('/qsys.lib/tap01.devd') obj('/notes/data/custsvc/*') 5. If your incremental backup tapes are cumulative, mount your most recent incremental backup tape. Use the same restore command (step 4) to recover the changes. Otherwise, if your backup tapes are nightly, repeat this step for each incremental backup tape. Start with the oldest tape and work forward, using the RST command from step Installing and Managing Domino for AS/400

125 About user-defined file systems and availability Normally, all disk units attached to an AS/400 server are treated as a single logical disk unit. The operating system places data across the disk units to optimize performance and disk utilization. However, an AS/400 administrator has the option to create logical groupings of disk units, called auxiliary storage pools or ASPs. Auxiliary storage pools provide several possible benefits, for example: ASPs provide the option for different strategies for backup and disk protection. For example, you might have large history databases that do not change very often. By segregating them in a separate ASP, you can easily set up a less-frequent backup schedule. You might also choose not to use RAID5 disk units for this ASP if availability of the information is not time-critical. ASPs provide the option to isolate database journals from the databases both for protection from data loss and for performance. If you want to place your Domino data directory in a user ASP, you need to create a user-defined file system (UDFS) to map the integrated file system directory to the correct ASP. You can read more about ASPs and creating user-defined file systems in the Backup and Recovery book (SC ). Or, consult the Domino information in the AS/400 Technical Studio at Chapter 5: Managing Backup and Recovery 121

126 Chapter 6 Planning Security for Database Integration A strength of Domino for AS/400 is the ability to integrate data between DB2 /400 and Domino databases in both directions. To take advantage of this integration capability, you need to understand and manage the way authorizations work between the two databases. About the QNOTES user profile Every AS/400 job runs under an AS/400 user profile. The user profile defines operational characteristics for the job. The user profile is also the source for privileges (special authorities) that the job needs for system functions and for the authority that the job needs to perform operations on AS/400 objects. The Domino for AS/400 product includes an AS/400 user profile called QNOTES. The QNOTES user profile provides the mechanism for Domino access control to work with the underlying AS/400 security. To function correctly, all Domino applications must run under the QNOTES user profile. For more information, see About AS/400 support for Domino access control. Processes that automatically run under the QNOTES user profile The following Domino processes run under the QNOTES user profile: The Domino server Programs that the Domino server starts as a result of ServerTasks or ServerTasksAt settings in the NOTES.INI file Programs that start as a result of Program documents in the Public Address Book Hook drivers and extension managers that run in the Domino server Agents that run in the Domino server Programs that start when you enter the Load command at the Domino server console 123

127 Ensuring that your Domino application runs under the QNOTES user profile If your Domino application is not designed to run in a process that automatically runs under the QNOTES user profile, use one of the following techniques to ensure that your application runs under the QNOTES user profile: Inside your application, swap to the QNOTES user profile by using the following AS/400 system APIs: QSYGETPH - get profile handle QWTSEPT - set profile Use the AS/400 Submit Job (SBMJOB) command to run the job in the background (in batch) under the QNOTES user profile. The SBMJOB command has a parameter to specify the user profile that the job should run under. Following is an example for using the SBMJOB command to run the CUSTSVC program in the CUSTPGM library: sbmjob cmd(call pgm(custpgm/custsvc)) user(qnotes) To submit a job that runs under QNOTES, the user must have *USE authority to the QNOTES user profile. In general, you should avoid giving users authority to the QNOTES user profile because the QNOTES user profile has the authority to change or delete any object on your Domino server. See also About authority when AS/400 programs access Domino databases in this chapter. Examples: Swapping to the QNOTES user profile Following is a coding example for using the AS/400 APIs to swap to the QNOTES user profile: /* header files to include */ #include <qsygetph.cleinc> QSYGETPH */ #include <qwtsetp.cleinc> */ /* Header file for the /* Header file for the QWTSETP #include <qusec.h> /* Error code structure */ #include <qsnapi.h> /* Error code structure */ /* declarations */ Qus_EC_t err_code; char cur_user[11] = "*CURRENT "; 124 Installing and Managing Domino for AS/400

128 char qnotes_user[11] = "QNOTES "; char qnotes_password[11] = "*NOPWD "; char char user_prof_handle[13]; qnotes_prof_handle[13]; /* get the handle to the QNOTES profile */ QSYGETPH(qnotes_user, qnotes_password, qnotes_prof_handle, &err_code); if (err_code.bytes_available) { /* Error retrieving handle to QNOTES user profile. */ return -1; } /* get the handle to the profile we are currently running under */ QSYGETPH(cur_user, NULL, user_prof_handle, &err_code); if(err_code.bytes_available) { /* Error retrieving handle to current user profile. */ return -1; } /* switch to QNOTES user profile */ QWTSETP(qnotes_prof_handle,&err_code); if(err_code.bytes_available) { /* Error switching to QNOTES user profile. */ return -1; } Chapter 6: Planning Security for Database Integration 125

129 /*******************************/ /* do notes APIs or functions */ /*******************************/ /* switch back to current user */ QWTSETP(user_prof_handle,&err_code); if(err_code.bytes_available) { /* Error switching to current user profile. */ return -1; } About AS/400 support for Domino access control Domino security and the underlying AS/400 security work together to achieve two objectives: The portability of Domino applications: access control for Domino for AS/400 must work just like it does on other Domino server platforms. The security and integrity of other applications that might share the same AS/400: Domino for AS/400 must follow the security rules that apply to every other AS/400 application. To understand how Domino security and AS/400 work together to achieve these objectives, you need some basic information about how Domino security works and about how AS/400 stores Domino databases. Domino provides the capability to define an access control list for every Domino database. Access control lists provide authorities that are similar to AS/400 object authorities. For example, in Domino, editor authority lets a user change any document in a database. However, an editor cannot delete a database or give other users authority to the database. Similarly, in DB2/400, *CHANGE authority lets a user add, change, or delete records in a database file. However, *CHANGE authority does not allow a user to delete the file or authorize others to use the file. 126 Installing and Managing Domino for AS/400

130 When you configure a Domino for AS/400 server, you specify the directory for server databases. For example, you might specify /NOTES/DATA. Domino for AS/400 databases (files with an.nsf extension) always reside in the AS/400 integrated file system. Domino for AS/400 creates the Domino database directory with public authority set to *EXCLUDE. Whenever a Domino user creates a new database, the public authority for the new database is *EXCLUDE. This prevents AS/400 users from accessing Domino databases outside of Domino. (Of course, a user with *ALLOBJ special authority can access or delete any database.) Domino for AS/400 provides a user profile called QNOTES, which owns the Domino database directory and all the objects in the directory. The QNOTES user profile has *ALL authority to the objects. Domino server jobs run using the QNOTES user profile. Note By default, the QNOTES user profile owns the Domino directory. You can change the owner, but you must ensure that the QNOTES user profile has *ALL authority to the directory and the objects in it or your server will not function properly. Now you can put the pieces together and see what happens when a Notes user tries to access a Domino database: 1. OS/400 checks to see whether the user has authority to the object in the integrated file system (such as /NOTES/DATA/MYDB.SNF). To OS/400, the user appears to be the QNOTES user profile, which owns all of the objects in the /NOTES/DATA/ path. Therefore, OS/400 allows access. 2. Control passes to Domino for AS/400. Domino knows the Notes user who has established a connection with the server and provided authentication. The Domino server checks that user s authority on the access control list for the database. If the user has the correct authority, Domino for AS/400 allows the user s request to proceed. Chapter 6: Planning Security for Database Integration 127

131 About authority when Domino applications access DB2/400 An important feature of Domino for AS/400 is the integration between Domino and DB2/400 databases. Three methods are available for Domino applications to access (and potentially update) DB2/400 databases: LotusScript applications use LS:DO (LotusScript data object) as an interface to DB2/400 data. Agents written using the Domino formula language can instructions to interact with a relational database, including DB2/400. The NotesPump product (which is an add-on Domino product that you can order separately) provides easy-to-use methods for synchronizing information in Domino databases with information in DB2/400 databases. All three methods for accessing DB2/400 from Domino establish a connection from Domino to AS/400. The connection specifies both the user profile whose authority the system uses to access DB2/400 database files and a password for that user profile. Details: Authority when Domino applications use LS:DO to access DB2/400 A Domino application can use either LS:DO (LotusScript data object) functions to provide access to DB2/400 databases. With both methods, the application establishes a connection with the DB2/400 database. The connection specifies an AS/400 user profile and password. Before allowing the connection, OS/400 checks for the following: A valid user profile and password combination. The user s authority to the DB2/400 database file. Following are security considerations for protecting your DB2/400 databases when you provide access from Domino applications. 1. For real-time applications (applications connected to a client), decide which AS/400 user profile the Domino applications will use to access DB2/400 data. You might decide based either on the Domino application or on the DB2/400 database. Following are the options: Use the user profile of the user who is running the Domino application. With this method, you need an AS/400 user profile for every Domino user who needs to run an application that accesses DB2/400 data. Connecting a Domino application to DB2/400 with a matching AS/400 user profile describes how your Domino application can provide the AS/400 user profile and password. 128 Installing and Managing Domino for AS/400

132 Set up special AS/400 user profiles whose only function is to provide Domino access to AS/400 data. This eliminates the need for each Domino user to have an AS/400 user profile. Connecting a Domino application to DB2/400 with a special AS/400 user profile discusses considerations for this method. Use a combination of these methods. Create special user profiles to provide the equivalent of public (or anonymous) access to Domino users. This technique might be appropriate for database files that every user can view. Rely on the Domino user s AS/400 user profile either for higher levels of access or for confidential files. 2. For scheduled applications (such as agents), you also need to provide an AS/400 user profile when you connect to DB2/400. Scheduled applications run on the server without a connected client. Therefore, the application cannot request a user ID and password from a Domino user. Review Connecting a Domino application to DB2/400 with a special AS/400 user profile for alternatives. Consider using adopted authority to provide tighter control over the actions a Domino program can perform on DB2/400 data. Connecting a Domino application to DB2/400 with a matching AS/400 user profile When a Domino application accesses a DB2/400 database, the Domino application needs to establish a connection with DB2/400. The connection requires a valid AS/400 user profile and password. When you want your Domino application to connect by using the Domino user s AS/400 profile, do one of the following: Prompt the user: Your application can prompt the Domino user for an AS/400 user profile name and password during the first connection within a session. Be sure that your application protects this information carefully. You should avoid storing the passwords for individual AS/400 user profiles on your server. Store the user ID and password: You can provide a form and database for your Domino users who need AS/400 database access. The form would prompt the user for the AS/400 user profile name and password. The application would encrypt the information and store it in a secure database on the client. Therefore, only the user or an application running on that user s behalf would be able to decrypt the password. When you use this method, your users do not need to enter their AS/400 user profile and password every time they make a connection from Domino to DB2/400. They will, however, need to use the form to update their database record when they change their AS/400 password. Chapter 6: Planning Security for Database Integration 129

133 Connecting a Domino application to DB2/400 with a special AS/400 user profile When a Domino application accesses a DB2/400 database, the Domino application needs to establish a connection with DB2/400. The connection requires a valid AS/400 user profile and password. You might want to create special user profiles for the purpose of providing connections between Domino applications and DB2/400 databases. Do the following for your special user profiles: 1. Decide how many special user profiles to create. Possible options are: A single AS/400 user profile to provide anonymous (or public) access to non-confidential databases. Multiple special-purpose profiles to provide access to DB2/400 data. You might think of these user profiles as similar to group profiles. Their role is to simplify the management of authority. Keep in mind that with this method, AS/400 does not know anything about the real Domino user. The Domino application sets the user profile name. You are relying on the Domino administrator to control who can use the application. 2. Decide whether to use passwords for the connection. Possible options are: Your connection can specify a user profile name and *NOPWD. The QNOTES user profile must have *USE authority to the user profile. With this method, any Domino application can use this AS/400 user profile to attempt to access data. Your application can store the user profile name and a password. You can protect this information so that only trusted programmers can view and update it. However, you must update the application whenever the AS/400 password changes. With this method, only Domino users who have authority to the program that contains the user profile and password can attempt to access DB2/400 data with it. The QNOTES profile does not need *USE authority to the user profile. 3. Set up the user profile to protect it from unintended use: Set the initial program to *NONE. Set the initial menu to *SIGNOFF. 130 Installing and Managing Domino for AS/400

134 Examples: Using adopted authority for Domino access to DB2/400 data On your AS/400, you might use adopted authority to manage how users update information. For example, the typical user might have *USE authority to the open order file (which allows viewing but not creating, changing, or deleting). However, you want to make sure that only certain users can create or change orders. And you want to make sure that a new order passes edit checks before it goes into the open order file. You accomplish this kind of control on AS/400 with adopted authority. A user profile with *CHANGE authority to the open order file owns the program that provides the create and change function. Certain users have *USE authority to run the program. To use a similar technique when you want to manage the ability to update DB2/400 data from Domino applications, do the following: 1. If necessary, design and create AS/400 programs that perform the desired tasks (such as changing a specific record in a database). You can probably adapt programs that you already have. 2. Set up the programs to adopt the authority of a user profile that has appropriate authority to the database file. Do the following: To transfer ownership of the program to the appropriate user profile, use the Change Object Owner (CHGOBJOWN) command. To specify that the program should adopt authority, use the Change Program (CHGPGM) command. Specify *OWNER for the User Profile (USRPRF) parameter. 3. Define the programs as a stored procedures for the DB2/400 database files that you want to update. 4. Design and create your Domino programs to use the stored procedures to update the DB2/400 database files. 5. When your Domino programs connect to DB2/400, specify a user profile name that has *USE authority to the stored-procedure programs. About authority when AS/400 programs access Domino databases The database integration between Domino and AS/400 works in both directions. Your Domino applications can retrieve (and potentially update) DB2/400 databases. Similarly, AS/400 applications can retrieve (and potentially update) information in Domino databases. Following are the basics steps to gain access to a Domino database from an AS/400 program: 1. To access a Domino database, an AS/400 program uses Domino application programming interfaces (APIs). These Domino APIs are available for C, C++, and Java programming languages. Chapter 6: Planning Security for Database Integration 131

135 2. Domino processes the database request as a server program (not a client/server program). Therefore, the Domino user for the database request is the user who is associated with the server. 3. A Domino server can have more than one NOTES.INI file. The NOTES.INI file specifies the user for server jobs for that INI file. 4. Your AS/400 program can use an API to point to the INI file that is appropriate for the Domino databases that the program wants to access. If your AS/400 program does not explicitly specify an INI file, Domino uses the default user for the server. 5. The Domino user must have the necessary authority to the Domino database. 6. To gain access to the Domino server and the NOTES.INI file, the AS/400 program that contains the APIs must run under the QNOTES user profile. This program cannot use adopted authority because adopted authority does not work with the integrated file system. (Domino databases reside in the integrated file system on AS/400.) For your Domino server to function properly, the QNOTES user profile must have *ALL authority to all of the Domino objects. Therefore, you should avoid giving users authority to the QNOTES user profile, either directly or indirectly. Instead, use specific programs for specific functions and use profile swapping. The topic that follows provides an example of this technique. Examples: Setting up authority for accessing Domino databases from AS/400 programs Following is an example for providing access to Domino data from an AS/400 program while protecting the QNOTES user profile: 1. Create an AS/400 program that contains the API instructions to access specific Domino databases. For the example, the program is a C++ program called ACCESSDOM. Following are the security characteristics of the ACCESSDOM program: Public authority is *EXCLUDE. The QNOTES user profile owns the program. The program does not adopt authority. No users have private authority to the program. 132 Installing and Managing Domino for AS/400

136 2. Create a program that provides the AS/400 user interface. The program might display information from both AS/400 databases and a Domino database. For the example, the program is an RPG program called USERDB1. Following are the security characteristics of the USERDB1 program: Public authority is *EXCLUDE. The QNOTES user profile owns the program. The program adopts the authority of the QNOTES user profile. Authorized users have private authority to the program. 3. Provide access to the Domino database through the following steps: An authorized user runs the USERDB1 program. Program USERDB1 uses an AS/400 API to swap to the QNOTES user profile. (The user does not have direct authority to swap to the QNOTES user profile. However, the USERDB1 program adopts the authority of the QNOTES profile and, therefore, has sufficient authority to swap to the QNOTES user profile.) Program USERDB1 calls the ACCESSDOM program and passes parameters about the database request. The ACCESSDOM program runs the Domino APIs to retrieve the Domino data and return it to the USERDB1 program. The USERDB1 program swaps back to the user profile of the requesting user. It displays the Domino data for the user. Following is a summary of the security features of this example: Public authority to the ACCESSDOM program is *EXCLUDE. No user (except a user with *ALLOBJ special authority) can run this program directly. Therefore, AS/400 users cannot gain access to Domino databases outside the control of the USERDB1 program. Public authority to the USERDB1 program is also *EXCLUDE. Only specific AS/400 users have the authority to run the program. The ACCESSDOM program can specify a NOTES.INI file. The NOTES.INI file can point to a Domino user who has the desired database authorities. This example does not require that any AS/400 users have *USE authority to the QNOTES user profile. For more information and a coding example, see Examples: Swapping to the QNOTES user profile. Chapter 6: Planning Security for Database Integration 133

137 About security recommendations for Domino for AS/400 Following are recommendations to protect both your Domino server and your other AS/400 applications and data when you run Domino for AS/400 on your system: The QNOTES user profile owns all of the objects in the Domino data directory. It has the capability to change or delete any Domino database. The settings for the QNOTES user profile are designed to protect your Domino data. For example, the QNOTES user profile does not have a password. Its initial menu is *SIGNOFF. You should not change the QNOTES user profile. Public authority to the QNOTES user profile is *EXCLUDE. This prevents users from submitting jobs that run under the QNOTES user profile. You should not change the public authority to the QNOTES user profile. Grant private authority to the QNOTES user profile with extreme caution. Note To ensure that users cannot submit jobs under the QNOTES user profile, the security level (QSECURITY system value) for your system must be 40 or higher. Otherwise, a job description that runs under the QNOTES user profile represents a security exposure. The QNOTES user profile owns the Domino database directory and the objects in it. To ensure that Domino applications run properly, you should not change the ownership to these objects. Public authority to the Domino database directory and the objects in it is *EXCLUDE. To ensure that Domino security works correctly, you should not change the public authority to the directory or the objects. Note The Domino data directory is the directory that you specify when you configure the Domino server, such as /NOTES/DATA. 134 Installing and Managing Domino for AS/400

138 Chapter 7 Setting Up the Application Development Environment To use the application development tools provided with Domino for AS/400, you need to do some setup so that you can access the AS/400 support (such as the header files) for those tools. You also need to know about AS/400 differences in using the tools. See Where to find information about Domino application development at the end of this chapter for a list of books and online databases that contain additional information. General considerations for using C, C++, HiTest C, and Java APIs There are several requirements and restrictions that apply to all programs that use the Notes C, C++, HiTest C, or Java APIs. Run all programs under the QNOTES user profile. Be aware of OS/400 restrictions for thread safety. Define a Path environment variable to identify Domino directories. Use a symbolic link to start server add-ins automatically. Avoid putting Domino APIs in exception and cancel handlers. Avoid using global new() and delete() operators. As needed, change your programs to use the AS/ bit API handles. Make sure you properly convert between EBCDIC and LMBCS (ASCII). Running under the QNOTES user profile All programs must run under jobs that use the QNOTES user profile. The following processes run under the QNOTES profile when they are started: The Domino server Programs that are started by the Domino server as a result of ServerTasks or ServerTasksAt settings in the NOTES.INI file Programs that are started as a result of Program documents in the Public Address Book 135

139 Hook drivers and extension manager applications that run in the Domino server Programs that are started as a result of entering the Load command on the Domino server console If your application is not designed to run in the above processes (such as an interactive application), you must take some action to make sure you run under the QNOTES profile. Use one of the following ways to make your application run under the QNOTES profile: Inside your application, swap to the QNOTES profile by using the following system APIs: QSYGETPH - get profile handle QWTSETP - set profile Use the Submit Job command (SBMJOB) to submit the job to run under QNOTES. For more details and examples, see About the QNOTES user profile in Chapter 6. Restrictions for thread safety The following programs run in processes (jobs) that can have multiple threads: Programs that are started as a result of Program documents in the Public Address Book and any programs they call Programs that are started as a result of entering the Load command on the Domino server console and any programs they call The following programs run in secondary threads: Hook drivers and extension manager applications that run in the Domino server C programs called by the LotusScript Declare statement in agents as well as any programs called from those C programs The AS/400 operating system (OS/400) has restrictions on jobs capable of running multiple threads and on the use of secondary threads. For details, see the AS/400 books System API Programming (SC ) and System API Reference (SC ). 136 Installing and Managing Domino for AS/400

140 Setting the Path environment variable To run Notes C API programs on AS/400, you must set up a Path environment variable that identifies: The Domino executable directory The path for this directory is /QIBM/UserData/Lotus/Notes. The resource directory The path for this directory is /QIBM/ProdData/Lotus/Notes. The data directory for the Domino server You specify the path for the data directory when you set up the Domino server. Following is an example of the statement necessary to set the Path environment variable where the server data directory is /NOTES/DATA. addenvvar envvar(path) value('/qibm/proddata/lotus/notes:/qibm/userdata/lotus/notes:/ NOTES/DATA') If your application will run on a partitioned server, you must set the value of the NOTESPARTITION environment variable to the path number of the partitioned server that your application will run on. You can find the path number of the partitioned server by looking in the file named.sgf.notespartition in the Notes data directory. Starting server add-ins To start server add-ins automatically or on the server console, create a symbolic link for the add-in in the /QIBM/UserData/Lotus/Notes directory. For example, for a program named MyAddin that is in the library MyLibrary, specify the following Add Link (ADDLNK) command to create a symbolic link: ADDLNK OBJ('/QSYS.LIB/MYLIBRARY.LIB/MYADDIN.PGM') NEWLNK('/QIBM/UserData/Lotus/Notes/MYADDIN.PGM') lnktype(*symbolic) Once created, the symbolic link will persist even if the program is deleted and created again. For more information about symbolic links, see the AS/400 Integrated File System Introduction (SC ). Chapter 7: Setting Up the Application Development Environment 137

141 Restriction on APIs in exception or cancel handlers Do not put Domino APIs in exception or cancel handlers. The Domino APIs use locks to synchronize access to resources with the server. The result of putting Domino APIs in exception or cancel handlers could range from deadlocking the Domino server to requiring an ipl (restart) of your AS/400. If a Domino API is invoked in your exception or cancel handler, a deadlock could occur. If a Domino API in your application is holding a lock when an exception or cancel occurs and the handler issues another Domino API, a deadlock occurs. The effect of the deadlock depends on whether it occurs in an exception handler or a cancel handler: If the deadlock occurs in an exception handler, you need to end that job and end and restart the Domino server and any Domino applications that are running on the server. If the deadlock occurs in a cancel handler, you need to end that job abnormally. As a result of ending the job abnormally, you must IPL the AS/400. Restriction on using global operators Do not use global new() or delete() operators in any add-in, library, or LSX. If you need to override those operators, confine them to class scope. Using global new() or delete() operators may result in some parts of the Domino server not working correctly. This restriction is related to an AS/400 restriction that there can be only one global new() and delete() operator per activation group. Using API handles API handles are 32 bits on AS/400. If your code depends on handles being 16 bits, change your code to accommodate the 32-bit handles. About ASCII-to-EBCDIC conversion Notes runs internally in LMBCS (Lotus Multi-Byte Character Set), and the character string representation for the Notes C API parameters is assumed to be LMBCS. When you write C programs using EBCDIC character strings, you must use the Notes OSTranslate API to convert between the EBCDIC strings used by the program and the LMBCS parameters passed to and from the C APIs. You may see Notes sample programs where this is not done. Those sample programs are technically incorrect, although functional in most cases. The sample programs usually work because ASCII code page 850 (PC ASCII) is a proper subset of LMBCS; therefore, characters in that character set do not 138 Installing and Managing Domino for AS/400

142 need to be translated to and from LMBCS because they are already in LMBCS. Because most of today s Notes applications use code page 850, or its 7-bit ASCII subset, the use of OSTranslate is not needed under those circumstances. The C++ APIs require EBCDIC strings for input and output, rather than the LMBCS strings used for C APIs. Where to find the header files on AS/400 When you install the application development software, the files are loaded into specific AS/400 libraries. The following table shows the AS/400 library in which the tools support is installed and the path for accessing that library through the AS/400 integrated file system. Item Library Path C APIs QNOTESAPI /qsys.lib/qnotesapi.lib C++ APIs QNOTESCPP /qsys.lib/qnotescpp.lib HiTest APIs QNOTESHTST /qsys.lib/qnoteshtst.lib LotusScript Extensions QNOTESLSKT /qsys.lib/qnoteslskt.lib About enabling the C++ compiler to access the header files You can compile your C, C++, HiTest, or LSX programs by using the VisualAge C++ for AS/400 cross-compiler on a PC workstation that is communicating with your AS/400. However, you must enable the compiler to access the header files. Unfortunately, the naming convention of the QSYS library system does not allow direct access to the header files through the compiler. The standard way for a C program to access header files is to use the #include statement. For example, for a C++ header file: #include <lncppapi.h> The compiler will not find the header file because the AS/400 name of the file (for our C++ example) is: /qsys.lib/qnotescpp.lib/h.file/lncppapi.mbr Therefore, you must make a name transformation to successfully compile your programs. There are four ways to achieve this name transformation: Copy the header files to the workstation where you plan to compile the programs. For example, you can use the TCP/IP file transfer support (FTP) to copy the files. Chapter 7: Setting Up the Application Development Environment 139

143 Detach a zip file containing the header files and unzip on the workstation where you plan to compile the programs. The zip files are attached to the APIDEV.NSF Notes database in the OS400 directory on the Lotus Domino CD. Copy the header files from the QSYS library (QSYS.LIB) to the AS/400 integrated file system. Then you can access the header files from a workstation by setting up a shared drive or directory between the workstation and the integrated file system. Create a symbolic link from the integrated file system to the actual location of the header files in QSYS.LIB and then access the files through a shared drive or directory. For more information about setting up a shared drive or directory, see the following: The documentation for the Client Access version you are using. The chapter on Connecting AS/400 to a TCP/IP Environment Using NetServer in the Getting Your AS/400 Working for You book (SC ). The Windows 95 or Windows NT help information about mapping a network drive. For more information about the integrated file system and symbolic links, see the AS/400 Integrated File System Introduction (SC ). Examples: Accessing the header files Here are examples of four ways of enabling the C++ compiler on a workstation to access the header files. These examples use the C++ directory (QNOTESCPP) and file (LNCPPAPI.H) names. Substitute the appropriate directory and file names for header files other than C++. Use FTP to copy the header files to a local drive This method involves copying the header files from the AS/400 to the workstation where you will compile the programs. The disadvantage of this method is that every workstation that you use to compile the programs must have its own copy of the header files. On an OS/2 workstation, you can use the following TCP/IP commands and FTP subcommands to get the header files to the workstation: cd (workstation directory to hold the header files) ftp(your AS/400 system name or IP address) (your AS/400 user ID) (your AS/400 password) ascii 140 Installing and Managing Domino for AS/400

144 cd qnotescpp nmap h.$1 $1.h prompt n mget h.* nmap hpp.$1 $1.hpp mget hpp.* quit On a Windows workstation, there is no FTP subcommand equivalent to NMAP. Therefore, you must enter the GET subcommand separately for each header file. For example: cd (workstation directory to hold the header files) ftp (your AS/400 system name or IP address) (your AS/400 user ID) (your AS/400 password) ascii cd qnotescpp get h.lncppapi lncppapi.h.. (one GET for each H file) quit.. Detach a zip file from a Notes database and unzip the header files This method makes copying the header files easier and the same for both OS/2 and Windows. You must do this on every workstation that you use to compile C source code for AS/400. The Lotus Domino CD includes a Notes database that contains the header files for the C. C++, and HiTest APIs. The header files are in zip files that are attached to the database. If you detach the zip file from the Notes database and then unzip the file, the header files are copied to your local directory. Chapter 7: Setting Up the Application Development Environment 141

145 The zip files are attached to the APIDEV.NSF Notes database under the OS400 directory on the CD. There are two ways to access the database from your client workstation: If your workstation has a CD-ROM drive, you can put the CD in the drive and access it through the drive letter. For example, if the CD-ROM drive of your workstation is letter D:, the Notes database is D:\OS400\APIDEV.NSF. You can also access the Notes database by putting the CD in the AS/400 CD-ROM drive. Use the Work with Object Links (WRKLNK) command to determine the contents of the CD. Look for the file APIDEV.NSF in the OS400 subdirectory of the QOPT directory. If you have a Client Access shared drive, you can access the file from the Notes client on the workstation. For example, if the shared drive is E:, you can access the Notes database at E:\QOPT\OS400\APIDEV.NSF. If you do not have Client Access, you can copy the database from the CD-ROM drive to the Notes data directory. Then clients can access the database through the Domino server. Once the APDEV.NSF database is opened, detach the zip file (for example, CPPHDR.ZIP for C and C++). When the detach operation is completed, unzip the file using common workstation tools (such as WinZip or PKUNZIP). The header files are then located on the workstation local directory. Specify that local directory in the /I compiler option when compiling your code. Copy the files to the AS/400 integrated file system and access a shared drive This method eliminates the need to copy the header files to each workstation that you use for compiling code. Using this method, you handle the name transformation problem by copying the files into the AS/400 integrated file system and renaming the files to the appropriate name. You do the operation once on your AS/400. Then each workstation uses a shared drive or shared directory to access the header files. The tool for doing the copy operation is the AS/400 Copy to Stream File (CPYTOSTMF) command. You must enter this command for each member of the H files in the library containing the header files. Following is an example for the C++ header files: cpytostmf frommbr('/qsys.lib/qnotescpp.lib/h.file/lncppapi.mbr') tostmf('/lotus/notes/include/cpp/lncppapi.h') This command copies the LNCPPAPI member of the H file in the QNOTESCPP library to the include directory /Lotus/Notes/Include/CPP. Enter this command for every member of the H and HPP file. 142 Installing and Managing Domino for AS/400

146 Once you have copied all header files to the include directory, you can specify /Lotus/Notes/Include/CPP each time you invoke the compiler on the workstation. You must set up the workstation so that it can access /Lotus/Notes/Include/CPP as a shared directory or through a shared drive. For example, you can use Client Access in combination with the Windows Network Neighborhood to set up a mapped network drive. Or you can use the AS/400 NetServer support to set up a shared directory that you access through Windows. Use AS/400 integrated file system symbolic links and access through a shared drive This method eliminates the need to copy the header files to each workstation that you use for compiling your code. Using this method, you handle the name transformation problem by creating a symbolic link from the integrated file system to the actual header files. You do the operation once on your AS/400. Then each workstation uses a shared drive or shared directory to access the header files through the symbolic link in the integrated file system. The tool for creating the symbolic link is the AS/400 Add Link (ADDLNK) command. You must enter this command for each member of the H files in the library containing the header files. Following is an example for the C++ header files: addlnk obj('/qsys.lib/q4notescpp.lib/h.file/lncppapi.mbr') newlnk('/lotus/notes/includes/cpp/lncppapi.h') lnktype(*symbolic) This command adds a symbolic link from /Lotus/Notes/Includes/ CPP/lncppapi.h to the LNCPPAPI member of the H file in the QNOTESCPP library. Whenever you reference /Lotus/Notes/Includes/CPP/lncppapi.h, you are actually referencing the LNCPPAPI member of the H file in library QNOTESCPP. Enter this command for every member of the H and HPP file. Once you have set up the symbolic link, you can specify /Lotus/Notes/ Includes/CPP when you invoke the compiler on the workstation. You must set up the workstation so that it can access the file containing the symbolic link through a shared directory or a shared drive. Chapter 7: Setting Up the Application Development Environment 143

147 Considerations for C APIs Be aware of the following considerations as you use the C APIs. Compiler requirements Ensuring compilation in ASCII Accessing the header files Compiling on AS/400 Compiling from a client workstation Compiler requirements for C You can compile the C APIs using either the AS/400 C compiler on AS/400 or the VisualAge C++ compiler on a client workstation. There are no special requirements for compiling on AS/400. For compiling on a client, you need an OS/2 or Windows 95/NT client with the following software: IBM VisualAge C++ for AS/400 IBM Client Access for the operating system you are using on the workstation. For example: Client Access for OS/2 Client Access for Windows 95/NT TCP/IP In addition to the normal setup for Client Access, you need to do an additional operation to enable automatic conversion between EBCDIC and ASCII. From the Network Drives tab of Client Access Properties, add the extensions.h and.mbr. Ensuring ASCII compilation for C APIs Notes C APIs expect and return LMBCS (ASCII) strings, literals, and so on. By default, VisualAge C++ compiles in EBCDIC code page 37. To get ASCII compilation, you need to use the following compiler flag: /AScp850 Because the C++ APIs require EBCDIC and not ASCII, avoid mixing the two. Accessing the C header files When you install the C API support on AS/400, the C header files are installed in the library QNOTESAPI. Within this library, the header files are members of the OS/400 file H.FILE (QNOTESAPI/H). If you compile on AS/400, the AS/400 compiler can access the header files as they are installed. No additional setup is required. 144 Installing and Managing Domino for AS/400

148 If you use the VisualAge C++ compiler on a workstation, you must set up the header files so that the compiler can access them. Following are examples of using each of four methods to make the C header files accessible to the compiler. Use FTP to copy the header files to a local drive On an OS/2 workstation, use the following instructions to copy the files: cd (workstation directory to hold the header files) ftp (your AS/400 system name or IP address) (your AS/400 user ID) (your AS/400 password) ascii cd qnotesapi nmap h.$1 $1.h prompt n mget h.* quit On a Windows 95/NT workstation, use the following instructions to copy the files: cd (workstation directory to hold the header files) ftp (your AS/400 system name or IP address) (your AS/400 user ID) (your AS/400 password) ascii cd qnotesapi get h.addin addin.h.. (one GET for each H file) quit.. Detach a zip file from a Notes database and unzip the header files Chapter 7: Setting Up the Application Development Environment 145

149 Open the APDEV.NSF database and detach the file CPPHDR.ZIP. When the detach operation is completed, unzip the file. The header files are then located on the workstation local directory. Specify that local directory in the /I compiler option when compiling your code. Copy the files to the AS/400 integrated file system and access through a shared drive The following example command copies the ADDIN member from /QSYS.LIB/QNOTESAPI.LIB/H.FILE/ADDIN.MBR to /Lotus/Notes/Include/C/addin.h (you can put these files wherever you want): cpytostmf frommbr('/qsys.lib/qnotesapi.lib/h.file/addin.mbr') tostmf('/lotus/notes/include/c/addin.h') Enter this command for every member of the H.FILE in the QNOTESAPI library. When you invoke the compiler, use the /I option to specify the directory /Lotus/Notes/Include/C on the shared drive. Use AS/400 integrated file system symbolic links and access through a shared drive The following example command adds a symbolic link from /Lotus/Notes/Include/C/addin.h to the ADDIN member of H.FILE in the QNOTESAPI library (that is, to /QSYS.LIB/QNOTESAPI.LIB/H.FILE/LNCPPAPI.MBR): addlnk obj('/qsys.lib/qnotesapi.lib/h.file/addin.mbr') newlnk('/lotus/notes/include/c/addin.h') lnktype(*symbolic) Enter this command for every member of the H.FILE in the QNOTESAPI library. When you invoke the compiler, use the /I option to specify the directory /Lotus/Notes/Include/C on the shared drive. For more information about installing the C header files, see About installing the Domino software on AS/400 in Chapter 1. For more information about setting up the header files, see the four methods that are described in About enabling the C++ compiler to access the header files in this chapter. Compiling the C program on AS/400 The ILE C/400 Programmer s Guide (SC ) describes how to compile a C program using the AS/400 compiler. In addition to the procedures described in that book, you need to put the QNOTESAPI library in your library list. For example: addlible qnotesapi 146 Installing and Managing Domino for AS/400

150 If you need more information, see Where to find information about Domino application development at the end of this chapter. Compiling and linking the C program from a client The VisualAge C++ compiler cross-compiles C source on a client workstation into intermediary.qwobj files. After compilation, those files are transferred to the AS/400 and translated into *MODULE files. On the AS/400, use the CRTPGM and CRTSRVPGM commands to link these modules and any other dependencies. To successfully use the VisualAge C++ compiler to compile a C source program that uses the Notes C APIs, you must do the following: 1. Install the compiler and other prerequisite programs. 2. Enable the compiler to access the Notes C header files. 3. Invoke the compiler on the workstation. The VisualAge C++ compiler comes with a Workframe tool to assist in developing C programs. You can also invoke the compiler from a DOS or OS/2 command line. The following description is based on invoking the compiler from the command line. The mapping from the command line syntax to the Workframe environment is straightforward. To invoke the compiler from the command line, use the iccas command. Use the following options to compile a source file that uses Notes C APIs: /DOS400 (define for specifying the OS/400 platform) /AScp850 (suggested define for compiling in ASCII) /ICdirectory (specifies the location of the header files) Following is an example of compiling a single module. In this example, we compile the file FOO.C into the library CTEST on the AS/400 whose system name is AS4ONE. We have already copied the C header files into the directory C:\Lotus\Notes\Include\C. Here is the compile statement: iccas /DOS400 /IC:\Lotus\Notes\Include\C /ASlCTEST /ASnAS4ONE /AScp850 FOO.C This statement creates a module file called FOO.MODULE in the library CTEST on the AS/400 called AS4ONE. 4. Invoke the CRTPGM or CRTSRVPGM command on AS/400 You can now link the module you created into a program (CRTPGM command) or a service program (CRTSRVPGM command) on the AS/400 on which you created the module. When you use either the CRTPGM or the CRTSRVPGM command, you must bind in the Chapter 7: Setting Up the Application Development Environment 147

151 LIBNOTES service program found in the QNOTES library. Here is a link statement that uses CRTPGM to make a program from the above compilation: crtpgm pgm(ctest/foo) module(ctest/foo) bndsrvpgm(qnotes/libnotes) The CRTPGM command creates FOO.PGM in the library CTEST.LIB. Depending on what type of Notes application is being written, you may need to link in either or both of the NOTES0 and NOTESAI0 modules. These two modules are in the QNOTESAPI library. To link in either or both of these modules, add the module or modules to the module list of CRTPGM or CRTSRVPGM command. For example: crtpgm pgm(ctest/foo) module(ctest/foo qnotesapi/notes0) bndsrvpgm(qnotes/libnotes) If the application is to run under the Domino server, you must manually create a symbolic link from the Domino server UserData directory to the location of the executable: addlnk obj('/qsys.lib/ctest.lib/foo.pgm') newlnk('/qibm/userdata/lotus/notes/foo.pgm') lnktype(*symbolic) You can invoke the program by using the AS/400 CALL command: call ctest/foo Considerations for C++ APIs Be aware of the following considerations as you use the C++ APIs. Compiler requirements Accessing the header files Compiling the program Differences and restrictions Compiler requirements for C++ The only compiler that is available for compiling C++ source code is VisualAge C++ for OS/400. To use this compiler, you must use an OS/2 or Windows 95/NT client with the following software: IBM VisualAge C++ for AS/ Installing and Managing Domino for AS/400

152 IBM Client Access for the operating system you are using on the workstation. For example: Client Access for OS/2 Client Access for Windows 95/NT TCP/IP Accessing the C++ header files The header files that are required for compiling your C++ source are located in the library QNOTESCPP on AS/400. The header files are members of two OS/400 files, QNOTESCPP/H and QNOTESCPP/HPP. You must set up the header files so that the compiler can access them. For more information, see the methods that are described in About enabling the C++ Compiler to access the header files in this chapter. Compiling and linking the C++ program VisualAge C++ for AS/400 is a cross-compiler that enables you to compile C++ source on a workstation (PC running OS/2 or Windows) and link the programs and service programs on AS/400. To successfully compile a C++ source program that uses the Notes C++ APIs, you must do the following: 1. Install the compiler and other prerequisite programs. 2. Enable the compiler to access the Notes C header files. 3. Enable the compiler to access the Notes C++ header files. 4. Invoke the compiler on the workstation. The VisualAge C++ compiler comes with a Workframe tool to assist in developing C++ programs. You can also invoke the compiler from a DOS or OS/2 command line. The following description is based on invoking the compiler from the command line. The mapping from the command line syntax to the Workframe environment is straightforward. To invoke the compiler from the command line, use the iccas command: Use the following options to compile a C++ source file that uses Notes C++ APIs: /DOS400 /ICPPdirectory /ICdirectory where CPPdirectory is the directory where the Notes C++ APIs are located and Cdirectory is the directory where the Notes C APIs are located. Chapter 7: Setting Up the Application Development Environment 149

153 Following are two examples of compiler invocations. For both examples, the target AS/400 system is AS4ONE and the target AS/400 library is CPPTEST. The C++ source file is named notestst.cpp. In the first example, the header files are on a shared drive (E:) in the directories /Lotus/Notes/Include/C and /Lotus/Notes/Include/CPP of the AS/400 integrated file system. For this example, the compiler invocation is: iccas /C /DOS400 /IE:/Lotus/Notes/Include/C /IE:/Lotus/Notes/Include/CPP /ASlCPPTEST /ASnAS4ONE notestst.cpp The /C option tells the compiler to create only a *MODULE. In the second example, the header files are on the workstation local disk drive (C:) in the directories /Lotus/Notes/Include/C and /Lotus/Notes/Include/CPP. For this example, the compiler invocation is: iccas /C /DOS400 /I/Lotus/Notes/Include/C /I/Lotus/Notes/Include/CPP /ASlCPPTEST /ASnAS4ONE notestst.cpp 5. Invoke the CRTPGM or CRTSRVPGM command on AS/400. The result of a successful compile by VisualAge C++, with the /C option, is an AS/400 *MODULE object that is created in the target library. If the above examples are successful, the AS/400 library CPPTEST on the system AS4ONE contains a *MODULE object named NOTESTST. You can use this module as input for creating either a program (CRTPGM) or a service program (CRTSRVPGM). Both the CRTPGM and CRTSRVPGM commands must bind in the NOTESCPP service program. This service program is found in the AS/400 library QNOTESCPP. As an example, suppose the above C++ source file NOTESTST.CPP is a small hello world type program that has a main entry point and uses a Notes C++ API. In the previous step, the NOTESTST.CPP file compiled successfully and now the NOTESTST module is in the CPPTEST library on AS4ONE. To create the program object that is required, enter the following AS/400 command: crtpgm pgm(cpptest/notestst) module(cpptest/notestst) bndsrvpgm(qnotescpp/notescpp) When the processing of this command is completed, the library CPPTEST contains the object NOTESTST that is ready for invocation. 150 Installing and Managing Domino for AS/400

154 The following command invokes the NOTESTST program that was created above (assuming no input parameters): call cpptest/notestst Differences and restrictions for C++ The following restrictions apply to using C++ APIs in programs that run on AS/400. Character set The Notes C++ API interface expects string input to be in the OS/400 character set. This means that EBCDIC strings must be used on the API interfaces. APIs not supported The LNMailMessage class is not supported. This class sends user mail from a server. Considerations for HiTest APIs Be aware of the following considerations as you use the HiTest C APIs. Compiler requirements Accessing the header files Compiling the program on AS/400 Compiling the program on a client workstation Differences and restrictions Compiler requirements for HiTest C You can compile the HiTest C APIs using either the AS/400 C compiler on AS/400 or the VisualAge C++ compiler on a client workstation. There are no special requirements for compiling on AS/400. For compiling on a client, use an OS/2 or Windows 95/NT client with the following software: IBM VisualAge C++ for AS/400 IBM Client Access for the operating system you are using on the workstation. For example: Client Access for OS/2 Client Access for Windows 95/NT TCP/IP Chapter 7: Setting Up the Application Development Environment 151

155 Accessing the HiTest C header files The header files for the HiTest C APIs are located in the library QNOTESHTST. These header files are members of the file QNOTESHTST/H. If you are using the AS/400 C compiler, nothing needs to be done to access the header files. If you are using the VisualAge C++ compiler, you must make the header files accessible to the compiler. For more information, see the methods that are described in About enabling the C++ compiler to access the header files in this chapter. Compiling HiTest C programs on AS/400 The ILE C/400 Programmer s Guide (SC ) describes how to compile a C program using the AS/400 compiler. In addition to the procedures described in that book, you must put the QNOTESHTST library in your library list and define the symbol HTOS_OS400 for your compilation. Here is an example: addlible qnoteshtst crtcmod module(testpgm) define(os400 unix htos_os400) Here are examples of creating a HiTest program and a service program: crtpgm pgm(testpgm) module(testmod) bndsrvpgm(qnoteshtst/libht451) crtsrvpgm srvpgm(testsrvpgm) module(testmod) bndsrvpgm(qnoteshtst/libht451) Here is an example of creating a HiTest program that will run as a Notes add-in: crtpgm pgm(testpgm) module(testmod qnoteshtst/htaddin qnotesapi/notes0 qnotesapi/notesai0) bndsrvpgm(qnoteshtst/libht451) For more information, see Where to find information about Domino application development at the end of this chapter. Compiling and linking HiTest C programs from a client To compile using the VisualAge C++ compiler, use the same procedures that you use for C programs. In addition, you need to specify the following options in the compile statement: /DHTOS_OS400 /IHiTestdirectory For more information, see Compiling and linking the C program from a client in this chapter. 152 Installing and Managing Domino for AS/400

156 Differences and restrictions for HiTest C At the HiTest C API interface, all string data is in LMBCS (ASCII), for both input and output. You can use the #pragma convert preprocessor statement in your source code to specify the code page in which literals should be generated. The #pragma convert(850) statement causes all following literals to be generated in ASCII. You can use #pragma convert(0) to change back to EBCDIC literals. The HiTest API HTTranslate() enables you to translate data between native (EBCDIC) and LMBCS. Considerations for Java Be aware of the following considerations as you develop applications that use Java APIs or run Java agents: AS/400 software required to run Java programs or agents Setup required to run Java programs Restrictions and requirements for running Java agents AS/400 software requirements for Java To run Java programs or Java agents on AS/400, you must install this AS/400 software: OS/400 - Qshell Interpreter option, 5769SS1 option 30 AS/400 Developer Kit for Java, 5769JV1 Setup required to run Java programs Before running the Java program: Set the CLASSPATH environment variable to include: The file /QIBM/UserData/Lotus/Notes/Notes.jar The directory that contains the class files for the Java program Add QNOTES to the library list: addlible qnotes When you run the Java program, submit it under the QNOTES user profile. For example, to run the Java program MyProg, enter this AS/400 command: sbmjob cmd(java class(mypgm)) user(qnotes) cpyenvvar(*yes) For more information, see About the QNOTES user profile in Chapter 6. Chapter 7: Setting Up the Application Development Environment 153

157 Restrictions and requirements for running Java agents Java programs cannot run Java agents or any agents that run Java agents. C++ programs cannot run Java agents or any agents that run Java agents. Programs that use the C or HiTest C APIs must link with the NOTES0J module instead of the NOTES0 module. Server add-in programs should link with both NOTES0J and NOTEAI0. The NOTES0J module enables the Java Virtual Machine (JVM) before passing control to the NotesMain() or AddinMain() function. Linking with NOTES0J causes multiple threads to be created in the program. Most of the program runs in a secondary thread. Because the JVM requires multiple threads, programs that link with NOTES0J must run in a job that is capable of multiple threads. The JVM on the AS/400 uses file descriptors 0, 1 and 2 for the stdin(), stdout(), and stderr() functions. Stand-alone programs that load and run programs linked with NOTES0J using OSLoadProgram will have their file handles inherited. Therefore, those programs must do either of the following: Use file descriptors 0, 1 and 2 for stdin(), stdout(), and stderr(). Mark those file descriptors as not inheritable by calling the fcntl() API with the FD_CLOEXEC command on file descriptors 0, 1 and 2. Considerations for LotusScript Be aware of the following considerations as you develop LotusScript applications. Accessing LotusScript Differences and restrictions Accessing the LotusScript support Starting with Lotus Notes Release 4.0, LotusScript is included with each Lotus Notes client and server (Domino). Differences and restrictions for LotusScript Various LotusScript functions are not supported or work differently because of the AS/400 integrated storage management and operating system (OS/400) support. 154 Installing and Managing Domino for AS/400

158 Language construct differences ActivateApp Not supported. Generates a run-time error. ChDir A run-time error is generated if LotusScript cannot interpret the argument to ChDir; for example, if a drive letter is specified in the argument. ChDrive Generates a run-time error unless the drive argument is an empty string (""), signifying the default drive. CreateObject Not supported. Generates a run-time error. CurDir, CurDir$ Generates a run-time error unless the drive argument is the empty string (""), signifying the default drive. CurDrive, CurDrive$ Returns the empty string (""), because there are no drives on AS/400. Date, Date$ Changing the date on AS/400 through LotusScript is not supported. Generates a run-time error. Declare The Pascal calling convention for external function calls is not supported. All external function calls must use the CDECL calling convention. In addition, you must use the _System linkage keyword when passing arguments other than pointers. Dir, Dir$ Ignores the optional attributemask argument. These functions behave as if all files have the attribute Normal. Returns all files for *.*, not just those containing.. Returns those files ending with a period for *., not every file without an extension. FileLen, Len, LenB, LenBP, LOF Strings containing line terminators are smaller than on DOS/Windows platforms. The line terminator is one character (line feed), not two. Therefore, the return value of these functions will be smaller for strings on AS/400 than on Windows. Chapter 7: Setting Up the Application Development Environment 155

159 GetFileAttr Generates a run-time error if a drive letter is included in the argument. Does not return the following attributes: ATTR_HIDDEN, ATTR_ARCHIVE, ATTR_VOLUME, ATTR_SYSTEM. GetObject Not supported. Generates a run-time error. Input #, Input, Input$, InputB, InputB$, Line Input, Print, Write # Compiled scripts using these constructs may be platform-specific, because file data is stored in a platform-specific manner. AS/400 character set, byte order, line terminator, and numeric precision specifics may affect the portability of scripts using these functions. IsObject, IsUnknown See Other differences below. Open, Lock, Unlock Explicit or implicit file locking is not supported. This implies the following: LotusScript for AS/400 allows the user to do operations (such as copy or open) on a file that is already opened for reading. Thus, the Name statement works differently on AS/400. The Open statement can specify only Shared as its lock status. Lock Read, Lock Write, and Lock Read Write will cause a run-time error. The Lock and Unlock statements will cause a run-time error. SendKeys Not supported. Generates a run-time error. SetFileAttr Ignores the attributes ATTR_HIDDEN, ATTR_ARCHIVE, and ATTR_VOLUME. Shell Window styles are ignored. Time, Time$ Changing the time on AS/400 through LotusScript is not supported. Generates a run-time error. 156 Installing and Managing Domino for AS/400

160 File system differences There are no drive letters on AS/400. If you use a path name containing a drive letter, LotusScript may return an error. AS/400 uses the slash (/) character as the directory separator, while DOS/Windows use backslash (\) character. LotusScript supports use of both the slash and backslash, with the following restrictions: A script compiled on any platform other than AS/400 or UNIX that uses a backslash in a path name string literal will not work on the AS/400. LotusScript cannot use file names (in contrast to path names) that contain the backslash character, because this character is always a path separator on other platforms. Other differences Function aliasing with ordinal numbers (using the Alias classes in the Declare statement) is not possible on AS/400. Where wild cards are permitted in file path strings, LotusScript supports the use of UNIX regular expressions in addition to the * and? characters. However, using regular expressions in file path strings makes the script platform-dependent. OLE is not supported on LotusScript Release 3.1 for AS/400. This difference affects the CreateObject, GetObject, IsObject, and IsUnknown functions. The CreateObject and IsObject functions will raise run-time errors when executed on AS/400 platforms. The IsObject function can determine if a variable refers to a native or product object, but not an OLE object, because OLE objects do not exist on the AS/400 platform. The IsUnknown function always returns FALSE on AS/400, because there is no way for a Variant expression to receive the V_UNKNOWN value. When passing pointer arguments to C functions, be aware that the pointer size on AS/400 is 16 bytes, not 4 bytes. Chapter 7: Setting Up the Application Development Environment 157

161 Considerations for LotusScript Extensions The LotusScript Extensions (LSX) Toolkit V2.0 for AS/400 is designed to run on a Win32 environment, such as Windows 95 or Windows NT. The LSX Toolkit relies on the availability of the Visual Age C++ for AS/400 cross-compiler on Win32. The LSX Toolkit for AS/400 uses the same Win32 development tools as the LSX toolkits for other platforms. Therefore, you should be familiar with LSX toolkit documentation database, which is located in the \LSX\LSXNSF directory. The topics that follow are an AS/400-specific supplement to that documentation. Requirements for LSX Preparing for LSX development Creating an LSX Running the LSX Differences for LSX Installation Agreement Installation and use of the LSX Toolkit is governed by the agreement called Software Development Kit Agreement. You can find this agreement in the text file LSX\LSXLICNS.TXT. Read the agreement before installing or using the LSX Toolkit. Requirements for LSX To use the LSX Toolkit V2.0 for AS/400, you need the following hardware and software: An Intel-based PC running Win32 This is the only platform on which the LSX Toolkit V2.0 for AS/400 has been tested. IBM VisualAge C++ for AS/400 cross-compiler The LSX Toolkit V2.0 for AS/400 is designed to run on any Win32 environment with the VisualAge C++ for AS/400 cross-compiler. Microsoft Visual C++ compiler for Win32 This compiler provides the required nmake and the environment to compile and create the LSXs on Win32 A connection (such as a LAN) between the Win32 workstation and the AS/400 The connection must communicate with AS/400 using TCP/IP. Client Access Optimized Windows Client for OS/ Installing and Managing Domino for AS/400

162 The developer uses this software to connect to AS/400 to create the AS/400 modules, objects, and service programs. Preparing for LSX development When you install Domino for AS/400 software, the LSX software is installed in the directory /QIBM/PRODDATA/LOTUS/LSX. Do the following on your workstation: 1. Make sure the AS/400 directory is accessible from your Win32 workstation through a mapped network drive. 2. Copy the entire LSX directory to the root directory of a local drive on your Win32 workstation. Following is an example of the command: copy n:/qibm/proddata/lotus/lsx c:\lsx where n: represents the drive letter of the mapped network drive. 3. In the LSX directory on the local drive, modify the LSXSETUP.BAT file with the following information: Environment variables for OS/400. Following are the parameters that you need to set: AS/400_HOST=XXXXX! Name of AS/400 where LSX will reside AS/400_DISK=N:! Name of AS/400 mapped drive AS/400_COMMLIB=qlsxcomm! Name of library for LSX common objects Environment variables for VisualAge C++ (MSDEV) Location of the LSX sources 4. Register the LSX wizard (\LSX\BIN\W32\LSXWIZRD.DLL) by using \LSX\BIN\W32\LSXREGN.EXE. Creating an LSX The LSX documentation database describes how to use the LSX Wizard to create an LSX. For Domino for AS/400, the wizard creates the required sources for both Win32 and AS/400. The help files in the \LSX\LSXNSF directory provide more information. The steps for creating an LSX for AS/400 are similar to the steps for creating an LSX for the Win32 environment. During development, you may find it helpful to create the LSX for the Win32 environment first. Chapter 7: Setting Up the Application Development Environment 159

163 Following are sample steps for creating an LSX for AS/400: 1. Use the LSX wizard to create a new LSX called; for example, APPX1. The wizard creates the directory (\LSX\SRC\APPX1) and the sources. Note When you eventually create your AS/400 LSX, the system names the service program by appending your LSX name to lib. Therefore, limit your LSX name to 7 characters. 2. Create a DOS prompt window from IBM VisualAge C++ for AS/400 program files. 3. To set environment variables for using VisualAge, do the following: Change to the LSX directory: c:\> c:\> cd \LSX c:\lsx> Run LSXSETUP for AS/400 and MSDEV (assuming you have Microsoft Visual C++ V5.0): c:\lsx> lsxsetup os400 msdev LSXSETUP does the following: Sets the required environment variables Changes the prompt Changes the directory to SRC Sets the path for nmake and the compiler 4. To create LSX common libraries and objects, run DO_IT: c:\lsx\src> do_it For AS/400, when you run DO_IT, the system runs MAKEFILE.OS400, which does the following: Connects to the AS/400 Creates the AS/400_COMMLIB specified in LSXSETUP.BAT Compiles the LSX common sources Creates the common bnddir on the AS/400 Disconnects from the AS/400 When you run DO_IT in the Win32 environment, the system runs MAKEFILE.MAK, which creates several sample LSXs. These sample LSXs are not completely tested for AS/ Installing and Managing Domino for AS/400

164 5. Change to the new LSX directory and run do_it: c:\lsx\src> cd appx1 c:\lsx\src\appx1> do_it For AS/400, DO_IT does the following: Connects to the AS/400 Creates the LSX library on the AS/400; for example, APPXLIB (/qsys.lib/appxlib.lib) Compiles the newly generated codes Links the new modules with QLSXCOMM library Creates the new LSX service program with lib appended to the front of the LSX name. For the example, the service program has the name /QSYS.LIB/APPX1.LIB/LIBAPPX1.SRVPGM. Disconnects from the AS/400 Example LSX As an example to help you, Domino for AS/400 includes an LSX called SIMPLE. It is fully ported and tested for AS/400. A LotusScript (LSS) file is also provided in the \LSX\TESTS directory to exercise the SIMPLE LSX. Running the LSX Currently, the only way to run an LSX on a server-only environment such as AS/400 is to create an agent on a Lotus Notes client. Because of this restriction, when you create an LSX for AS/400, you also must create a client version. Do the following: 1. Create an agent that will run on the server, such as a scheduled agent. The agent should contain a USELSX statement in the options: option public uselsx "*appx1" Note Do not provide the complete path of the LSX in the agent because the client and the server have different LSX locations. 2. On the Win32 environment, register the LSX ( appx1 ) for Notes using \LSX\BIN\W32\LSXREGN. 3. On AS/400, register the LSX ( appx1 ) for Notes by updating the user s LOTUS.INI file. The LOTUS.INI file is in the user s Notes data directory. Following is the statement for the example LSX: appx1=/qsys.lib/appx1.lib/libappx1.srvpgm Chapter 7: Setting Up the Application Development Environment 161

165 Make sure that you have an extra empty line at the end of LOTUS.INI file. Also, notice that the directory specification uses the / (UNIX style) rather than the \ (DOS style). Note If the user does not have a LOTUS.INI file in the \NOTES\DATA directory, copy the sample from the C:\LSX directory. For LSX release notes, see the README.TXT file. Differences for LSX Do not write a global new() or delete() operator in your LSX. If you need to override these operators, confine them to class scope. Failure to do so will result in some parts of the Domino server not working correctly. This restriction is related to an AS/400 restriction that there can be only one global new() and delete() operator per activation group. You can specify C functions, but not C++ functions, in the ProcRegister API. The functions must use the system linkage that is available in the AS/400 C compiler. About integrating Notes and DB2/400 data You can use one of three methods to access the DB2/400 relational database from Domino applications: LotusScript applications use the LotusScript data object (LS:DO ) as an interface to DB2/400 data. Through LS:DO, the Domino application sends a request to the DB2/400 database. On other server platforms, LS:DO uses an ODBC interface to relational databases. On AS/400, the LS:DO code passes the request directly to DB2/400 without using ODBC. Therefore, the LotusScript program looks the same as it does on other platforms, but the underlying processing on AS/400 is more direct. Domino formula applications can functions to access a relational database, including DB2/400. NotesPump provides easy-to-use methods for synchronizing information in Domino databases with information in DB2/400 databases. Both the LS:DO and functions are included as part of the Lotus Notes base support. NotesPump is a separate product. See the NotesPump documentation for details on how to use NotesPump. 162 Installing and Managing Domino for AS/400

166 As you use LS:DO functions, be aware of the following differences and restrictions. Security requirements General requirements and differences LS:DO differences Where to find error messages For more information on security requirements, see About authority when Domino applications access DB2/400 in Chapter 6. General requirements and differences for LS:DO functions When you use LS:DO functions to access AS/400 data, be aware of the following: For LS:DO, you must specify the following UseLSX statement in the Event (Options) within LotusScript: uselsx "*lsxodbc" This requirement is similar to other platforms. functions, the first parameter must be ODBC. For AS/400, the LS:DO functions require that you specify a user ID and password. However, there is no interactive prompting for the user ID and password and no support for automatic registration. Therefore, you must specify the user ID and password in your script. The LS:DO functions use the SQL Call Level Interface (CLI) instead of ODBC. However, the user interface is the same. The CLI does not have an ODBC.INI file. You must register the data source on AS/400 by using the Work with Relational Database Entries (WRKRDBDIRE) command to add the data source to the AS/400 relational database directory. The SQL CLI is described in the AS/400 book DB2 for OS/400 SQL Call Level Interface (SC ). Differences for LS:DO When you use LS:DO to access DB2/400, be aware of the following differences. ODBCConnection class ListTables method This method returns a list of all the tables in all the libraries. Therefore, the result set can be so large that it cannot be returned. Chapter 7: Setting Up the Application Development Environment 163

167 ListFields method Do not specify the optional datasource parameter. For OS/400, a connection must already be established before calling ListFields. ListDataSource method If you specify the datasource parameter, you must also specify a user ID and password to establish a connection. Otherwise, the current connection is used. ListProcedures method If you specify the datasource parameter, you must also specify a user ID and password. If the data source is not specified, the connection that is currently established is used. ODBCQuery class If the tables from the datasource contain a large number of columns (greater than 100), avoid using * in the SQL statement to list all columns. Instead, specify the actual column names that you want to retrieve. For example, the following SQL statement might result in a memory error if the table contains more than 100 columns: Myquery.SQL = "select * from lib.table" Instead, use a SQL statement such as the following: Myquery.SQL = "select col1, col2, col3 from mylib.mytable" ODBCResult class Do not use quotation marks around the table name or the column name. For example, the following command will not work: Result1.DeleteRow("mylib.""mytable""") When setting DateTime values using the SetValue method, you must enclose the values in quotation marks as strings. The values must be in the following format: Value Format Example Date yyyy-mm-dd Time hh:mm:ss 12:15:30 Time Stamp yyyy-mm-dd-hh.mm.ss.mmmmmm If the query statement specified on the SQL property of the ODBCQuery class contains a column with REAL (single-precision floating-point) data type, the UpdateRow method might not work. The error #546 is returned: LS:DO- The result contains no data. 164 Installing and Managing Domino for AS/400

168 If the query statement contains multiple columns of the same name from different tables and the column names are qualified with the alias table names, the UpdateRow method does not work. To avoid this problem, qualify the column names with the full library.table names. Here are examples. This SQL statement does not work: Select t1.cusnum, t2.cusnum, t2.balance from mylib.mytable1 t1, mylib.mytable2 t2 where t1.cusnum=t2.cusnum This SQL statement works: Select mylib.mytable1.cusnum, mylib.mytable2.cusnum, mylib.mytable2.balance from mylib.mytable1, mylib.mytable2 where mylib.mytable1.cusnum=mylib.mytable2.cusnum Use the Close method to close a result set and free the associated resource before executing another SQL statement; for example: Result.Close(DB_CLOSE) The FieldInfo method returns an array of elements. The following elements are not supported on AS/400: DB_INFO_UNSIGNED DB_INFO_MONEY DB_INFO_READONLY (always returns 1) DB_INFO_AUTOINCREMENT DB_INFO_CASESENSITIVE DB_INFO_SEARCHABLE DB_INFO_SETTABLE (always returns -1) The DB_INFO_LENGTH element (same as the ResultSet.FieldSize method) is applicable for specific data types: SQL data type DB_INFO_LENGTH indicates integer, small integer, float number of bytes char, varchar, longvarchar number of characters numeric, decimal (not applicable) The DB_INFO_PRECISION and DB_INFO_SCALE elements are applicable only for numeric or decimal data types. Chapter 7: Setting Up the Application Development Environment 165

169 Remote connection differences When you retrieve data from a remote system for the first time, the Execute method may fail and issue the following error message: SQL package QSQCLIPKGN in QGPL not found If the Execute method fails with this message, create the following LS:DO script and add it to the beginning of your existing LS:DO script: Sub Initialize Dim con As New ODBCConnection con.autocommit=false If (con.connectto("datasource","userid","password")) Then End If Call con.disconnect End Sub After you successfully run your script, delete the script you added. The added script only needs to run once to create the SQL package on the remote system. Where to find error messages Some SQL messages are logged in the AS/400 job logs, such as the Agent Manager job log or the HTTP server job log. For the LS:DO function, you can use the GetError, GetErrorMessage, and GetExtendedErrorMessage methods to log any error messages to the server console or to a file. You can log additional information about SQL calls to the server console by doing the following: 1. From the console, enter: SET CONFIG lsxodbc_gdf_level =2 (or specify a level of 0 to turn off the logging) 2. End the job that processes the LS:DO requests. For example, from the console, enter: tell AMgr quit 3. Restart the job. For example, from the console, enter: load AMgr 166 Installing and Managing Domino for AS/400

170 Where to find information about Domino application development Lotus information Lotus Notes Designer for Domino 4.6 Programmer s Guide Part 1 describes scripts and formulas using LotusScript, including LS:DO. Part 2 describes Online databases Lotus Notes C API Lotus Notes C++ API Lotus Notes Designer for Domino 4.6 Java Programmer s Guide Lotus LSX Toolkit LotusScript Data Object (LS:DO) This information may be available from the Lotus User Assistance Web site at IBM AS/400 information DB2 for OS/400 SQL Call Level Interface (SC ) Describes the DB2/400 SQL call level interface (CLI). ILE C/400 Programmer s Guide (SC ) Describes how to use the AS/400 C compiler to create C programs. Integrated File System Introduction (SC ) Describes the structure and use of the AS/400 integrated file system, including rules for specifying path names. System API Programming (SC ) Describes the use of APIs on AS/400. System API Reference (SC ) Provides details about each API that can run on AS/400. This information is available from the AS/400 Online Library Web site at Other IBM information Lotus Notes Release 4.5: A Developer s Handbook (SG ) Describes the use of LotusScript, LSX, LS:DO, functions. Chapter 7: Setting Up the Application Development Environment 167

171 Appendix A Using Operations Navigator to Install Domino This chapter describes how to install and set up Domino servers on AS/400 using Operations Navigator. It also describes what you need to do to set up an administrator workstation for the server. About AS/400 Operations Navigator for Domino AS/400 Operations Navigator is a powerful graphical interface for Windows 95/NT clients that allows you to manage and administer your AS/400 systems using your Windows 95/NT skills. Using AS/400 Operations Navigator, you can work with database administration, file systems, Internet, network administration, users, user groups, and more. There is no need to start an emulation session and use OS/400 commands. You can access the AS/400 Operations Navigator from the Client Access folder, by double-clicking the AS/400 Operations Navigator icon. AS/400 Operations Navigator for Domino is a separately installed sub-component for Operations Navigator that allows you to: Create and set up Domino servers Add and register Domino servers and users Access the NOTES.INI file Start and stop Domino servers Access the Domino Administration panel 169

172 Overview of using Operations Navigator to set up a Domino server Using Operations Navigator to install Domino for AS/400 involves the following tasks: 1. Ensure you have completed the following tasks: Make sure you have the AS/400 authorities that are required to install and setup the Domino server Verify the required hardware and software Make sure TCP/IP is set up and active on AS/400 For more information, see Overview of preparing AS/400 for Domino in Chapter 1. Install Domino software on AS/ Set up the administrator workstation. 2. Install AS/400 Operations Navigator for Domino. 3. Use Operations Navigator to set up the first or an additional Domino server. About setting up the administrator workstation You may be wondering, why do I need to set up an administrator workstation? Typically, a computer used for a Domino server is both a server and a Notes client workstation. The AS/400 is a pure server in that it does not provide a client workstation. Therefore, to use the capabilities of a workstation to administer the Domino server, you must connect a workstation to the AS/400 and set up the Notes client on the workstation. The workstation that you use to administer a Domino server must have access to the Certifier ID file and administrator ID file that are created when you set up the server. When you set up a First Domino Server on the AS/400, the Certifier ID and administrator ID files are stored on the AS/400. Operations Navigator copies these files automatically to your workstation at the end of server setup. 170 Installing and Managing Domino for AS/400

173 To use the Operations Navigator to set up the Domino server, you must set up the administrator workstation first. This workstation must contain the following software: Microsoft Windows 95 or Microsoft Windows NT Version 4.0 operating system AS/400 Client Access, 5763-XD1 V3R1M3 Cumulative Service Pack Notes 4.5 with full administrator functions or Notes 4.6 with Notes Designer To communicate with AS/400 through Client Access, you must have the following software installed on your AS/400: OS/400 Host servers, 5769SS1 option 12 Client Access for Windows 95/NT, 5769XD1 AS/400 Client Access Family for Windows, 5769XW1 Tasks involved in setting up the administrator workstation To use the capabilities of a Lotus Notes workstation to administer the Domino server, you must set up the workstation with the Certifier ID and administrator ID that authorize the workstation user to be the administrator. These IDs are created when you set up the Domino domain. The following procedure assumes that the Notes client is not installed on the workstation. If Notes is already installed, skip the tasks that are already done. Preparing your workstation before you install Lotus Notes 1. Determine the hardware and operating system requirements for the release of Notes 4 you plan to install on the workstation. Refer to the installation documentation for that release of Notes. For example: For Notes 4.5, see the Lotus Notes Install Guide for Workstations. For Notes 4.6, see the Lotus Notes Install Guide. 2. Install and set up the operating system on the workstation, if you have not already done so. 3. Physically attach the workstation to the network so it can communicate with the AS/ Install and set up TCP/IP on the workstation. Tip For the following steps you may want to refer to the AS/400 book Client Access for Windows 95/NT - Setup (SC ). This book contains a helpful chapter on configuring Microsoft TCP/IP for Windows 95 or Appendix A: Using Operations Navigator to Install Domino 171

174 Windows NT, installing Client Access, and connecting to your AS/400. You can access this book from the AS/400 Online Library Web site at You may also locate this information at: or and click the Connect to your LAN section. 5. Verify the TCP/IP connection to the AS/400. In Windows 95 or Windows NT, click the start button, and then click Run. In the Open text box enter the following: ping hostname where hostname is the TCP/IP host name of the AS/400. You determined this host name when you verified the TCP/IP setup for AS/400. Click OK. If the PING is successful, the workstation is communicating with the AS/400. If the PING is not successful, review the steps you followed to set up TCP/IP on the workstation and AS/400. If the server name is not the same as the hostname, then you can also PING the server name. In Windows 95 or Windows NT, click the start button, and then click Run. In the Open text box enter the following: ping servername If the PING is successful, the workstation is communicating with the AS/400. If the PING is not successful, review the steps you followed to set up TCP/IP on the workstation and AS/ Install Client Access and enroll CA/400 Users on AS/400. You can locate more information on Client Access at: and click the Connect to your LAN section. 7. Connect your Windows 95/NT workstation to your AS/400 using Client Access. 172 Installing and Managing Domino for AS/400

175 Installing and setting up Notes 4.6 Designer on your workstation Note Skip this procedure if you already have the Notes client installed. 1. Set up the Notes client with no connection to a Domino server. Later you will create a connection document to connect to your AS/400 server. In the Notes Workstation Setup dialog, choose: No connection to a Domino server. No mail server. Click OK. 2. In the unconnected workstation setup dialog, enter your full user name exactly as your administrator registered you. Select Notes Designer for Domino License. Select User ID supplied in a file. Choose the administrator id file you stored in: \notes\idfiles\servername 3. Setup begins. 4. Select a time zone. Select Observe Daylight Savings Time April-October if appropriate. 5. Notes setup is complete. Choose OK. Lotus Notes 4.6 Install Guide (or previous version install information) lists platform-specific instructions on installing and setting up Notes workstations for Lotus Notes Mail, Lotus Notes Desktop, and Lotus Notes Designer for Domino. The Install Guide is also available online as a database named WKSINST.NSF. Previous versions of Notes (4.x) can be used to do the install. However, some AS/400 administration functions require Notes 4.6. For more information, see AS/400 Technical Studio at: For details on installing Notes 4.5, see the Lotus Notes Install Guide for Workstations. 6. Start Lotus Notes 4.6. Appendix A: Using Operations Navigator to Install Domino 173

176 Installing AS/400 Operations Navigator for Domino Note If your workstation already has a Notes data directory that contains a Certifier ID (CERT.ID) or administrator ID (USER.ID) file, take precautions to avoid replacing those files. Create a separate directory for the ID files that will be copied automatically from the AS/400. You will specify this directory in the administration settings during the Domino server setup. For example, create this new directory: \notes\idfiles\servername where servername is the name of the Domino server you just set up on AS/ Double-click the IBM AS/400 Client Access shortcut on your desktop. 2. Double-click the Accessories Icon. 3. Double-click the Selective Setup Icon. The selective setup window appears. 4. Click Next. 5. The Selective Setup Options dialog appears. Choose the Use managing system radio button. 6. Click Next. The message Checking for components available on managing system appears. Note If not already signed on to your AS/400, you should sign on now. Ensure you have a user profile on the AS/400 that has the authorities you need to set up the Domino server. 7. The Component Selection panel appears. Select the components you want. (As a minimum component selection, choose AS/400 Operations Navigator.) 8. Click the Change button. The Select Sub-Components dialog box appears. Note If you already have Operations Navigator installed, you still need to click the change button to add the sub-component Lotus Domino. 9. Select Operations Navigator Base Support (if not already installed) and Lotus Domino. 10. Click Continue. 11. Click Next. Click Next again on the Start Copying files screen. The preparing to install small dialog box appears at the bottom right-hand corner. 174 Installing and Managing Domino for AS/400

177 12. Install Completed panel appears. Click Next. 13. The Readme - Notepad file appears. 14. The Setup Complete dialog appears. Choose the radio button: Yes, I want to restart my computer now. Note If you are installing Operation Navigator for the first time, reboot your workstation. You do not have to restart your workstation to use Lotus Domino support. 15. Click Finish. About the Domino server setup program Before you set up your Domino server using Operations Navigator, familiarize yourself with the following Domino terms: Domino server ID Each Domino server has a unique name that is maintained in its own ID file. Domino creates the server ID automatically during the server Setup program. Notes user ID Each Notes user has a unique name that is maintained in its own ID file. Domino creates the user ID when you register new users. Certifier ID Each grouping of Domino servers, known as a domain, has an organization certifier ID that is stored in a file named CERT.ID. This certifier automatically certifies the first server s ID and the administrator s ID. When you register new users or servers, you use the certifier ID to give access to the domain. You also use the organization certifier ID when you create organizational unit certifiers for a hierarchical name scheme. Domino creates the organization certifier ID automatically during the first server setup program using the organization name you specify and an optional country code. You can only add a country code if your country s clearinghouse for X.500 names has approved your organization name. Doing this minimizes the chance that another organization has the same organization name as yours. A multinational organization requires only one certifier ID, even if a country code is specified; it s not necessary to have separate certifier IDs for each country in which Domino is deployed. Domain A domain is a group of Domino servers that share the same Public Address Book. Appendix A: Using Operations Navigator to Install Domino 175

178 Public Address Book Each domain has a Public Address Book. The Public Address Book is the control and administration center for Domino servers in the domain. It contains a Server document for each server and a Person document for each user. In addition, you can create Group documents to establish relationships among servers and users for mailing and security purposes, and create Connection documents to schedule replication and mail routing among servers. For more information, see Planning the Domino System and Getting Started with Domino. Choosing first or additional server If this is the first server you are setting up in your organization, or if you are creating a new domain, see Setting up first Domino server using Operations Navigator. If this is a new server that has already been defined in an existing organization, see Overview of using Operation Navigator to install additional Domino server later in this chapter. If you want to use advanced functions like partitioned servers or clustering, see Create an additional Domino server using advanced setup. Ensuring full message logging The AS/400 domino server setup programs requests run under the QSYSWRK subsystem using prestarted jobs that are submitted using the QUSER user profile. AS/400 errors related to the setup function are written to QUSER job logs. These job logs are put in spooled output files on AS/400. The job name for these spooled files is QZRCSRVS, which is the job name associated with the prestarted jobs. To be able to see the fully detailed messages resulting from the server setup program, change the job description to increase the logging level. You can use the Change Job Description (CHGJOBD) command to change the job description QZBSJOBD to have the following values for the maximum logging level: Message logging: Level Severity Text *seclvl Use the command WRKSPLF QUSER on any OS/400 command line to see a list of QUSER job logs. 176 Installing and Managing Domino for AS/400

179 Overview of using Operations Navigator to set up the first Domino server Setting up first Domino server involves the following tasks: 1. Create a separate directory for the ID files. 2. Set up your first Domino Server. 3. Complete the server setup. Start the Domino server Switch to the administrator id Create a Lotus Notes connection to your Domino server 4. Verify your connection to your Domino Server. Creating a separate directory for the ID files 1. If your workstation already has a Notes data directory that contains a Certifier ID (CERT.ID) or administrator ID (USER.ID) file, take precautions to avoid replacing those files. Create a separate directory for the ID files that get copied from the AS/400. For example, create this new directory: \notes\idfiles\servername where servername is the name of the Domino server you just set up on AS/400. During Domino server setup, you will be asked to specify where the ID files should be copied. You should specify this directory. Setting up your first Domino server 1. Double-click the IBM AS/400 Client Access shortcut on your desktop. 2. Double-click the Operations Navigator icon. 3. The AS/400 Operations Navigator window appears. Select the AS/400 on which you want to set up Domino. Note When a scanning for new Client Access components dialog appears, click Scan Now. 4. Click the + button to expand the directory. 5. Select Network and click the + button to expand the directory. 6. Select Servers and click the + button to expand the directory. Appendix A: Using Operations Navigator to Install Domino 177

180 7. Right-click Domino and choose New Domino Server. 8. Operations Navigator opens the Domino Server Setup database (SETUP400.NSF). The setup process has four steps. Complete the information in each step and then click the right arrow to go to the next step. For more information about the choices you make, see the Quick Help on the right side of the screen. 178 Installing and Managing Domino for AS/400

181 Completing Step 1: Create a New Domino Server 1. Select First Domino Server. 2. Enter the AS/400 system that the Domino Server is being created on. (It may already appear.) 3. Click the right arrow in the upper right-hand corner of the screen. This will take you to step 2. Completing Step 2: Choose a setup method for the first server 1. Click Quick and Easy Setup. 2. Click the right arrow in the upper right-hand corner of the screen. This will take you to step 3. Appendix A: Using Operations Navigator to Install Domino 179

182 For details on Advanced setup, see Advanced Setup, later in this chapter. Advanced setup offers experienced users the most control and customization of the server setup parameters. Completing Step 3: Server audience for the first server You can return to a previous panel to change its settings by clicking the left arrow at the top right of the panel. The numbers at the top left of the panel indicate which of the four Setup panels you are in. 1. Select who can access the Domino server. If you want Web browsers such as Microsoft Internet Explorer and Netscape Navigator to access data on the server, select Web Browsers. If you want Internet mail clients using Post Office Protocol 3 (POP3), Internet Message Access Protocol (IMAP), and Simple Mail Transfer Protocol (SMTP) to access mail on the server, select Internet Mail Packages. If you want Internet news readers using Network News Transfer Protocol (NNTP) to access news groups and discussions on the server, select News Readers. 2. Click the right arrow. 180 Installing and Managing Domino for AS/400

183 Completing Step 4: Administration settings for the first server Defaults are automatically set for all fields. You can use the defaults or change them. For Help on what terms mean, click the blue labels and hold down the mouse button to read the Help. 1. In the Organization Identity section, enter the name of your organization; for example, the name of your company or a group or location within your company. 2. In the New Server Identity section, enter a Server Name. This is the name of the new server. Users and other servers access the server using this name. We suggest you choose a server name that is the same as your AS/400 TCP/IP host name. To determine the host name of your AS/400, user option 12 on the Configure TCP/IP menu. To display this menu, enter the following AS/400 command: cfgtcp 3. In the Administrator s Identity section, do all of the following: Enter a First Name, Middle Initial (M.I.), and Last Name for the server Administrator. Enter a password for the Administrator s ID. Lotus recommends using a password of at least 13 characters. Appendix A: Using Operations Navigator to Install Domino 181

184 4. In the data files location section, do all of the following: In the Server s Directory field, specify the path to the AS/400 integrated file system directory where you want Domino data files to reside. For example: /notes/data If the specified directory does not exist, it is automatically created. In the Copy ID files to field, specify the workstation directory where you want to store the Domino server ID files. The ID files are copied from your AS/400 to your Windows client. 5. Click the Finish button to create your first Domino server. Note Clicking the finish button sends the Configure Domino Server (CFGDOMSVR) command to your AS/400. After the CFGDOMSVR command completes, the cert.id file, server.id, and user.id files are copied to your workstation. It will take 10 to 15 minutes for the entire process (CFGDOMSVR and copy id files) to complete. You see the message: Begin sending the request to server name. This requires 5-15 minutes of computation. Would you like to continue? Click YES. Once this process is complete, you can start the Domino server. Note The time zone is set based on the client time zone. The password default length is set based on the password typed in. Tip To monitor progress of the setup process, use the command WRKSPLF QUSER on any OS/400 command line to see a list of QUSER job logs. Locate the job log that corresponds to the time you began the setup process. Use option 5 to display the job log. About what happens during first server setup What happens when you run first server setup? Before you set up the first Domino server, decide about the names you will use for the domain, Domino named network, and server. For more information, see Planning the Domino System and Getting Started with Domino. Note A Domino server cluster member may or may not be the first server in a domain. For all Domino servers, only choose first server setup when you are setting up Domino for the first time in your company or when you are creating a new domain. 182 Installing and Managing Domino for AS/400

185 The first server setup does the following: Creates a new domain for the Domino servers. Enables the appropriate network and serial ports. Creates the Public Address Book for the domain. The Install program uses the PUBNAMES.NTF template to create the Public Address Book in the same directory you choose for Domino data files and gives it the default name NAMES.NSF. Creates a Certifier ID for your organization. The Install program saves the Certifier ID in the same directory you choose for Domino data files and gives it the default name CERT.ID. Creates a Certifier document in the Public Address Book. This document describes the Certifier ID. Creates a server ID for the new server. The Install program saves the server ID in the same directory you choose for Domino data files and gives it the default name SERVER.ID. Certifies the server ID with the organization certifier ID. Creates a Server document in the Public Address Book. This document describes the first server based on information that you specify during setup. Creates a Person document in the Public Address Book for the Domino administrator specified during setup. Creates a user ID and a password for the Domino administrator and attaches it as a file named USER.ID to the administrator s Person document in the Public Address Book. Certifies the administrator s user ID with the organization certifier ID. Adds the administrator s name and the server s name as managers in the access control list of the Public Address Book. Adds the server name to the LocalDomainServers group in the Public Address Book. Creates the log file for the server in the same directory you choose for Domino data files and gives it the default name LOG.NSF. Creates a mail directory in the Domino data directory and a mail file in that directory for the Domino administrator. Appendix A: Using Operations Navigator to Install Domino 183

186 Completing server setup After you finish setting up the server, the Domino Server Setup database displays a Congratulations panel with the server name, domain name, server ID file name, certifier ID file name, administrator ID file name, and administrator ID password. Notes prompts you to write down the server ID password, certifier ID password, and administrator s ID password. Ensure you keep these passwords secure. Tip To close the database and go to the Notes client workspace, click Exit to Workspace. After you write down your passwords you will need to: Start the Domino server Switch to the administrator id Create a connection to your server Starting the Domino server 1. Open the IBM AS/400 Client Access folder. 2. Double-click the Operations Navigator icon. 3. The AS/400 Operations Navigator window appears. Select the AS/400 you want to work with. 4. Click the + button to expand the directory. 5. Select Network and click the + button to expand the directory. 6. Select Servers and click the + button to expand the directory. 7. Right-click Domino and choose Explore. (You can expect a delay.) 8. A list of Domino servers appears. In the server name field, right-click the Domino server you wish to start and select start from the drop-down menu. Note This process takes about 2 to 5 minutes. Click the refresh button to see updated status information. Start submitted appears in the status field. When the status field indicates started and active, you can then create a connection document to connect to your server. Note If you specified a password when you registered the additional server, you will need to go to an AS/400 command prompt and issue the command: WRKDOMCSL server name Enter the password The server will not become fully active until the password is entered. 184 Installing and Managing Domino for AS/400

187 Switching to the administrator ID 1. From AS/400 Operations Navigator, right-click the Domino server you want to work with. Choose server administration. 2. Choose File - Tools - Switch ID. 3. Select the administrator id (user.id) created previously during the setup process. (This id file is in the directory you specified in the Administration Settings panel of the Domino server setup.) 4. Choose OK. Creating a Notes client connection to your AS/400 Domino server If you don t already have a connection follow the steps listed below. 1. Go to the Lotus Notes status bar. (The status bar appears above the Windows 95 or Windows NT task bar, unless you ve moved the task bar.) 2. Click the word Island, and choose Office (Network) from the pop-up menu. 3. Click the word Office on the status bar. 4. A pop-up menu appears. Choose Edit Current. 5. In the location document, go to the basics section. 6. In the Location type field, Local Area Network automatically displays. If this is not the correct location type go to step 7. If Local Area Network is correct, go to step Click the button near Location type. 8. A keyword dialog box appears. Choose the appropriate location type and click OK. 9. In the Servers section, enter your server name. 10. In the Ports section, select what Port to use. 11. In the Mail section, enter the path and the file name of the mail file being used at this location. The administrator mail database is usually created by using the first initial and last name of the administrator. For example: John Doe = mail\jdoe.nsf 12. Scroll down to the advanced section of the location document. Click the twistie next to the word Advanced to expand that section. 13. In the advanced section, change the time zone to your local time zone. 14. In the User Id to switch to field, click the flashlight and choose the user.id you just created. (This id file is in the directory you specified in the Administration Settings panel of the Domino server setup.) Appendix A: Using Operations Navigator to Install Domino 185

188 15. Press the Save and Close button. Getting Help connecting to a server Note For more information on location documents and connecting to a server, go to Lotus Notes Help. 1. Choose Help - Help Topics. 2. Begin typing: server connections 3. The Quick Search dialog appears and server connections displays in the search text field. 4. Click OK. The help topic displays information on creating a server connection document. See also Getting Started with the Domino Server. For information on registering new users, see Chapter 4, Managing Domino Users. Verifying your connection to your Domino Server 1. From the Lotus Notes workspace, choose File - Tools - Server Administration. 2. Enter the name of the Domino server in the choose a server to administer field. 3. Click the console button. 4. In the server console command field enter: show tasks 5. Click send. 6. In the server output field, you should see a listing of server tasks. Your first Domino server setup is complete. For information on registering new users, see Chapter 4, Managing Domino Users. Completing your Administrator Workstation Setup If you had to install Notes onto the administrator workstation in order to set up your first Domino server, you will need to complete the following tasks. From the workspace of your Notes administrator workstation: 1. Remove unnecessary databases from the Notes administrator workstation workspace. (When you created your Notes administrator workstation as standalone or unconnected, several databases were added that are no longer required.) 186 Installing and Managing Domino for AS/400

189 2. To remove these databases, right click on the database and select Remove from Workspace. 3. Add the Domain Public Address Book to the Notes administrator workstation workspace: Choose File - Database - Open Select or specify the Domino server that you just set up Select the address book for the domain that you just created Click Add icon 4. Add the administrator s mail file to the Notes administrator workstation workspace Overview of using Operations Navigator to set up an additional Domino server Use this procedure if you want to add another Domino server to an existing Domino domain. When you add a Domino server to a Domino domain, the additional server uses the same Public Address Book as other servers in the Domain. For example, set up the Domino server as an additional server if: You already have a Domino server on another system and you want the Domino server on AS/400 to use the same Public Address Book. You already have a Domino server on an Integrated PC Server in your AS/400 and you want the Domino server on AS/400 to use the same Public Address Book. You already have a Domino server set up on your AS/400 and you want to add a second server that uses the same Public Address Book. Note If you set up more than one Domino server on the same AS/400, you must install the Lotus Advanced Services feature and set up all Domino servers on the AS/400 as partitioned servers. Setting up an additional Domino server involves these tasks: 1. Prepare the AS/400 environment for the Domino server. If you previously set up your first Domino server on the same AS/400, you already set up the AS/400 environment. For more information, see Overview of preparing AS/400 for Domino in Chapter Use an existing server in the Domino domain to register the additional server. 3. Verify the TCP/IP connection from the registration server and its administrator workstation to the AS/400. Appendix A: Using Operations Navigator to Install Domino 187

190 4. Copy the server ID file for the additional server to the AS/400, if you saved the server ID in a file when you registered the server. 5. Set up the additional Domino Server Using Operations Navigator. Registering the additional Domino server 1. Select an existing server in the Domino domain and use that server (the registration server) to register the additional server. For information about registering the additional server, see Getting Started with the Domino Server or the Administrator Help database (HELPADMN.NSF). The server registration process creates a Server document in the Public Address Book of the registration server and creates a server ID. Unless you specify differently, the server ID is encrypted and attached to the Server document in the Public Address Book. You have the option of storing the server ID in a file on the registration server. If you store the server ID in the Public Address Book, you must provide a password. Keep a record of the password in a secure place. When you use Operations Navigator to configure the additional server, you must provide the password. Domino copies the Public Address Book, including the server ID, to the new server during the setup processing. You must also specify the password every time you start the additional server. Therefore, after you issue the start request, you must start the Domino server console (using the AS/400 WRKDOMCSL command) and enter the password. If you store the server ID as a file on the registration server, you must manually copy the file from the registration server to the AS/400 where you plan to configure the additional server. You must copy the server ID file before you run the CFGDOMSVR command. 2. Record the full hierarchical name of the registration server and the additional server that you registered. Registration server: Additional server: For example, here is a full hierarchical name: Server2/Chicago/Acme Also record the TCP/IP host name of the registration server. This host name is usually the same as the server name. Registration server TCP/IP host name: 188 Installing and Managing Domino for AS/400

191 Verifying the TCP/IP connection to AS/400 When you set up the additional Domino server on AS/400, Domino copies the Public Address Book from the registration server to the new server. Therefore, the AS/400 must have an active TCP/IP connection to the registration server. Similarly, the administrator workstation for the domain must be able to communicate with the AS/400. Verifying the TCP/IP connection between the registration server and AS/ Make sure the registration server is started. 2. From any AS/400 command line, enter this command: ping registration-server-host-name where registration-server-host-name is the TCP/IP host name of the registration server. You recorded this host name as part of the procedure to register the additional server. The host name of the registration server may be different from the TCP/IP host name of the system on which the registration server is running. If the registration server responds to the PING, the TCP/IP connection between the registration server and AS/400 is operational. If the PING is not successful, verify the TCP/IP configuration on the AS/400 and the system containing the registration server. Also verify that the AS/400 and the other system are properly connected to the network and that the network is operational. Note If the registration server for the domain is running on an Integrated PC Server in the same AS/400 as the additional server, you may need to do additional configuration. For more information on using a Domino for AS/400 server in the same domain as a Domino server on an Integrated PC Server, see Appendix B. Verifying the TCP/IP connection between the workstation and AS/400 To manage the additional server from your current administrator workstation, you must be able to communicate with the AS/400 through TCP/IP. If you are using a network protocol other than TCP/IP to administer your current servers, you must set up TCP/IP on the workstation. 1. Install and set up TCP/IP on the workstation. For instructions, see the documentation for the TCP/IP product. Tip If you are using Microsoft Windows 95 or Windows NT, you may want to refer to the AS/400 book Client Access for Windows 95/NT - Setup (SC ). This book contains a helpful chapter on configuring Microsoft TCP/IP for Windows 95 or Windows NT. You can access this Appendix A: Using Operations Navigator to Install Domino 189

192 book from the AS/400 Online Library Website at 2. Verify the TCP/IP connection to the AS/400. Open a DOS prompt window on the workstation and enter the following: ping hostname where hostname is the TCP/IP host name of the AS/400. If the PING is successful, the workstation is communicating with the AS/400 If the PING is not successful, review the steps you followed to set up TCP/IP on the workstation and AS/400. Copying the ID file for the additional server to AS/400 If you stored the server ID in a file (instead of the Public Address Book) on the registration server, you must copy the file to the AS/400 where you plan to set up the additional server. Skip this step if you stored the server ID in the Public Address Book. 1. When you copy the server ID file, you must identify the system that contains the file and the location of the file on the system: Record the TCP/IP host name or Internet address for the system that contains the registration server. If the registration server is on an AS/400, use the CFGTCP command on that AS/400 to display the Configure TCP/IP menu. Then use option 12 to determine the TCP/IP host name or Internet address: Host name of system containing registration server: Internet address of system containing registration server: Record the location of the server ID file. Directory path and file name of new server ID: 2. Copy the server ID file from the system containing the registration server to the AS/400 on which you plan to set up the additional server. Use any method that you typically use to copy files between systems. For example, you can use: The TCP/IP File Transfer Protocol (FTP). The Windows Network Neighborhood in combination with either AS/400 Client Access or AS/400 NetServer support to map a network drive between systems. To use either method, you must have TCP/IP communications set up and active between the workstation and AS/ Installing and Managing Domino for AS/400

193 For more information see, Examples: Copying the server ID file to the AS/400 in the additional server setup section of Chapter Change the AS/400 authorities to secure the server ID file but still allow the Domino server to access the file: Change the public authority (*PUBLIC) for the file to *EXCLUDE. Use the Work with Object Links (WRKLNK) command to find the file path and then use option 9 to work with the authorities for the file (press F23 to display option 9). Change the owner of the file to QNOTES. Use the Change Owner (CHGOWN) command to change the owner. Setting up an additional Domino server using Operations Navigator 1. Double-click the IBM AS/400 Client Access shortcut on your desktop. 2. Double-click the Operations Navigator icon. 3. The AS/400 Operations Navigator window appears. 4. Select the AS/400 you want to work with. (This is the AS/400 you will be installing Domino on.) Note If a scanning for new Client Access components dialog appears, click Scan Now. 5. Click the + button to expand the directory. 6. Select Network and click the + button to expand the directory. 7. Select Servers and click the + button to expand the directory. Note It may take a few minutes for the new server panel to appear. Note You may be prompted to choose a file to be used. If prompted, you will need to choose the administrator id file. Ensure you select the administrator id for the current domain. If you are not prompted to switch your id file, follow the steps listed below. Choose File - Tools - Switch ID. Select the User ID file to switch to. Click OK. Appendix A: Using Operations Navigator to Install Domino 191

194 8. Right-click Domino and choose New Domino Server. 9. New Domino Server window appears. About additional Domino server setup Set up the Domino Server from the Domino Server Setup database (SETUP400.NSF). This is a four-step process. Complete the information in each step and then click the right arrow to go to the next step. For more information about the choices you make, see the Quick Help on the right side of the panel. Completing Step 1: Create an additional Domino server Note Select this option if you want to create a new server in an existing Domino organization. (Domino domain.) You will only need to supply a few key pieces of information. 1. Select Additional Domino Server. 2. Enter the AS/400 system that the Domino Server is being created on. (It may already appear.) 3. Click the > next button in the upper right-hand corner of the panel. Completing Step 2: Select a Setup method Choose Quick and Easy or Advanced Setup. Quick and Easy Setup requires the least manual input. Predefined default settings (gathered during the installation process or from you machine) streamline the setup process. You can customize these default settings at any time. 192 Installing and Managing Domino for AS/400

195 Choose Advanced Setup if you want to use advanced functions like partitioned servers or clustering. 1. Click Quick and Easy Setup. 2. Click the right arrow button in the upper right-hand corner of the panel. For details on Advanced setup, see Advanced Setup, later in this chapter. Advanced setup offers experienced users the most control and customization of the server setup parameters. For additional details on Advanced setup, including partitioned servers and server clusters, see Chapter 2 Extending Domino for AS/400. Completing Step 3: Server audience 1. Determine which of the functions below (if any) you want to use. 2. Check Web Browsers, Internet Mail Packages, and/or News Readers. The Web Browsers feature enables your Domino Server to be accessible by Web Browsers. The Internet Mail Packages feature enables your Domino Server to host mailboxes for Internet mail packages and to send and receive mail from the internet. The News Readers feature enables your Domino Server to send and receive messages form Internet Newsgroups, and to be accessible by Internet News readers. 3. Click the right arrow button in the upper right-hand corner of the panel. This will take you to step four. For additional details on Web Browsers, see Chapter 2, Extending Domino for AS/400. Completing Step 4: Administration settings You must enter the name and location of a server from which the new Domino server can obtain the domain address book. For Help on what terms mean, click the blue labels and hold down the mouse button to read the Help. 1. Under the New Server Identity section, enter name of the server in the Server Name field. The server Identity must be the full hierarchical name. For example, Server2/Chicago/Acme. 2. In the Server ID field, choose whether to get the Server ID from the Domain Address Book, or from a file. (This depends on your registration option.) If you choose Server ID supplied in a file, a Browse button appears. Click the browse button to locate where you stored the server ID. Appendix A: Using Operations Navigator to Install Domino 193

196 3. In the Server ID password field, enter a password (if you chose one when registering). 4. In the Domain Address Book location section, specify the name of an existing Domino server that has the Public Address Book to be used for this server. The Address Book is copied from the specified Domino server to this additional server. 5. In the server s directory field specify the path to the AS/400 integrated file system directory where you want Domino data files to reside. For example: /notes/data If the specified directory does not exist, it is automatically created. 6. In the Copy ID files to field, specify the workstation directory where you want the server ID file to be copied. This process copies the server ID file from your AS/400 to your Windows client. The server ID file will be automatically copied from the AS/400 to this directory at the end of the setup process. For example: \notes\idfiles\server-name 7. Click the Finish button when you are done to create your additional Domino server. You see the message: Begin sending the request to server name. This requires 5-15 minutes of computation. Would you like to continue? Click YES. Once this process is complete, you can start the Domino server. Completing server setup After the setup process completes, the Domino Server Setup database displays a Congratulations panel with the server name, domain name, and server ID file name. Tip To close the database and go to the Notes client workspace, click Exit to Workspace. Server setup includes the following tasks: Start the Domino server Switch to the administrator ID Create a connection to your server For information on switching to the administrator ID, see Switching to the administrator ID earlier in this chapter. 194 Installing and Managing Domino for AS/400

197 For information on creating a connection to your server, see Creating a Notes client connection to your AS/400 Domino server earlier in this chapter. Starting the Domino server 1. Open the IBM AS/400 Client Access folder. 2. Double-click the Operations Navigator icon. 3. The AS/400 Operations Navigator window appears. Select the AS/400 you want to work with. 4. Click the + button to expand the directory. 5. Select Network and click the + button to expand the directory. 6. Select Servers and click the + button to expand the directory. 7. Right-click Domino and choose Explore. (You can expect a delay.) 8. A list of Domino servers appears. In the server name field, right-click the Domino server you wish to start and select start from the drop-down menu. Note This process takes about 2 to 5 minutes. Click the refresh button to see updated status information. Start submitted appears in the status field. When the status field indicates started and active, you can then create a connection document to connect to your server. Note If you specified a password when you registered the additional server, you will need to go to an AS/400 command prompt and issue the command: WRKDOMCSL servername Enter the password The server will not become fully active until the password is entered. For information on verifying your connection to your Domino server, see Verifying your connection to your Domino Server earlier in this chapter. For information on registering new users, see Chapter 4, Managing Domino Users. Appendix A: Using Operations Navigator to Install Domino 195

198 About additional Domino server advanced setup Set up the Domino Server from the Domino Server Setup database (SETUP400.NSF). This is a four-step process. Complete the information in each step and then click the right arrow to go to the next step. For more information about the choices you make, see the Quick Help on the right side of the panel. Completing Step 1: Create an additional Domino server using advanced setup 1. Select Additional Domino Server. 2. Enter the AS/400 system that the Domino Server is being created on. (It may already appear.) 3. Click the right arrow button. Completing Step 2: Select a setup method Advanced setup offers experienced users the most control and customization of the server setup parameters. Choose Advanced Setup if you want to use advanced functions like partitioned servers or clustering. 1. Choose Advanced Setup. 2. Click the right arrow button. 196 Installing and Managing Domino for AS/400

199 Completing Step 3: Server audience In addition to Notes Users who else will be the audience for this server? Select the options you need from this screen. Standard Services Default values include: Administration Process Agent Manager Calendar Connector Event Manager Indexer Mail Router Replicator Reporter Schedule Manager Statistics Advanced Services Choose Partition, Billing, or Cluster. For more information on partitioned servers and server clusters, see Chapter 9 in the Extending the Domino System book or the Domino administrator help database (HELPADMN.NSF). 1. Web Browsers This feature enables your Domino Server to be accessible by Web browsers. Check HPPT to enable. Appendix A: Using Operations Navigator to Install Domino 197

200 2. Internet Mail Packages This feature enables your Domino Server to host mailboxes for Internet mail packages and to send and receive mail from the Internet. Check any or all of the following: IMAP LDAP POP3 or SMTP MTA 3. News Readers This feature enables your Domino Server to send and receive messages from Internet Newsgroups, and to be accessible by Internet News readers. 4. News Readers This feature enables your Domino Server to send and receive messages from Internet Newsgroups, and to be accessible by Internet News readers. Check NNTP to enable. Completing Step 4: Administration settings You must enter the name and location of a server from which the new Domino server can obtain the domain address book. For Help on what terms mean, click the blue labels and hold down the mouse button to read the Help. 1. Under the New Server Identity section, enter name of the server in the Server Name field. The server Identity must be the full hierarchical name. For example, Server2/Chicago/Acme. 2. In the Server ID field, choose whether to get the Server ID from the Domain Address Book, or from a file. 198 Installing and Managing Domino for AS/400