Lotus Domino 6.0.2 for z/OS - File/domcnsl.pdfDomino console commands can be ... the command from any UNIX command line ... used by Domino and Lotus Notes administrators. The z/OS

z/OS Console Support for Lotus Domino

Lotus Domino 6.0.2 for z/OS

software

Disclaimer

THIS DOCUMENTATION IS PROVIDED FOR REFERENCE PURPOSES ONLY. WHILE EFFORTS WERE MADE TO VERIFY THE COMPLETENESS AND ACCURACY OF THE INFORMATION CONTAINED IN THIS DOCUMENTATION, THIS DOCUMENTATION IS PROVIDED "AS IS" WITHOUT ANY WARRANTY WHATSOEVER AND TO THE MAXIMUM EXTENT PERMITTED, LOTUS AND IBM DISCLAIM ALL IMPLIED WARRANTIES, INCLUDING WITHOUT LIMITATION THE IMPLIED WARRANTIES OF MERCHANTABILITY, NONINFRINGEMENT AND FITNESS FOR A PARTICULAR PURPOSE, WITH RESPECT TO THE SAME. LOTUS AND IBM SHALL NOT BE RESPONSIBLE FOR ANY DAMAGES, INCLUDING WITHOUT LIMITATION, DIRECT, INDIRECT, CONSEQUENTIAL OR INCIDENTAL DAMAGES, ARISING OUT OF THE USE OF, OR OTHERWISE RELATED TO, THIS DOCUMENTATION OR ANY OTHER DOCUMENTATION. NOTWITHSTANDING ANYTHING TO THE CONTRARY, NOTHING CONTAINED IN THIS DOCUMENTATION OR ANY OTHER DOCUMENTATION IS INTENDED TO, NOR SHALL HAVE THE EFFECT OF, CREATING ANY WARRANTIES OR REPRESENTATIONS FROM LOTUS AND IBM (OR THEIR SUPPLIERS OR LICENSORS), OR ALTERING THE TERMS AND CONDITIONS OF THE APPLICABLE LICENSE AGREEMENT GOVERNING THE USE OF THIS SOFTWARE.

Copyright

Under the copyright laws, neither the documentation nor the software may be 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 IBM Corporation, except in the manner described in the documentation or the applicable licensing agreement governing the use of the software.

Licensed Materials - Property of IBM

© Copyright IBM Corporation 1985, 2003

Lotus SoftwareIBM Software GroupOne Rogers StreetCambridge, MA 02142

All rights reserved. Printed in the United States.

US Government Users Restricted Rights - Use, duplication or disclosure restricted by GS ADP Schedule Contract with IBM Corp.

Revision History: Original material produced for IBM Lotus Notes and IBM Lotus Domino Release 6.0.

List of Trademarks

IBM, the IBM logo, AIX, AS/400, iSeries, OS/2, OS/2 Warp, S/390, Tivoli, WebSphere, z/OS, and zSeries, Lotus, cc:Mail, Domino, Freelance, Freelance Graphics, Lotus Notes, LotusScript, Notes, 1-2-3, Organizer, Quickplace, Sametime, SmartIcons and SmartSuite are trademarks or registered trademarks of IBM Corporation in the United States, other countries, or both.

Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.

Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both.

MMX and Pentium are trademarks of Intel Corporation in the United States, other countries, or both.

UNIX is a registered trademark of The Open Group in the United States and other countries.

Other company, product and service names may be trademarks or service marks of others.

z/OS Console Support for Lotus Domino 6.0.2 Contents

Chapter 1 - Overview 1............................................................................................Welcome 1....................................................................................................................................

Introduction 1..........................................................................................................................Summary of Changes 1..........................................................................................................

How the Console Support Works 2...............................................................................................Console Support 2..................................................................................................................

Chapter 2 - Preparing the z/OS system 3..............................................................Prerequisites 3..............................................................................................................................

Before you begin 3.................................................................................................................Migration 3....................................................................................................................................

Migrating from an Earlier Version of the Domino Console 3..................................................Domino Console Support for Multiple Versions 4.........................................................................

Supporting multiple Domino versions 4..................................................................................NLS Considerations 4...................................................................................................................

NLS 4......................................................................................................................................

Chapter 3 - Installing the z/OS Console Support for Domino 5...........................Install instructions 5......................................................................................................................

Installation 5...........................................................................................................................

Chapter 4 - Using Console Support 17....................................................................From a z/OS Operator’s Console 17...............................................................................................

Recycling the notes.log file while the server is active 17..........................................................Enabling and Disabling the Monitor 17.....................................................................................Filtering Messages Sent to the Console 18..............................................................................Passwords 19...........................................................................................................................Sending Commands to Domino Servers 20.............................................................................Starting Domino Servers 21.....................................................................................................Stopping Domino Servers 22....................................................................................................

From Unix Systems Services 23.....................................................................................................Using domoe to Send Commands to the Server from USS 23................................................

Chapter 5 - Problem determination 25.....................................................................What to look for 25..........................................................................................................................

Indications of problems 25........................................................................................................Messages 29...................................................................................................................................

Domino z/OS Console Messages and Codes 29.....................................................................

Chapter 6 - Reader comments 39.............................................................................Reader comments 39......................................................................................................................

z/OS Console Support for Domino

May 2003

About the z/OS Console Support for Domino Guide

This database contains information about installation, operation, and problem determination for the z/OS Console Support for Domino.

z/OS Console Support for Lotus Domino 6.0.2 Chapter 1 - Overview

Chapter 1 - Overview

Welcome


IntroductionThis document is intended for use with Domino 6 for z/OS and higher. If you want to manage Domino servers from the z/OS operator's console and send commands from UNIX Systems Services, this document is intended for you.

Use this document to install the z/OS Console Support for Domino, formerly known as DOMCON. The console support provides:

The ability to manage Domino partitioned servers from the same z/OS console or from a single UNIX System lServices telnet or rlogin sessionThe capability to do an orderly shutdown of the Domino server from the z/OS Operator's consolelRACF protected dataset to store Domino passwords (server.id) and the ability to automatically feed them into the lserver's input stream at startupAutomated startups with secure server.id files lThe ability to start and terminate the messages sent to the console independently of starting and stopping your lDomino serverThe ability to establish filters to limit what information is sent to the z/OS console for DominolAn interface to automation systems that can start, stop, or send commands to the server in response to error lsituationsSynchronized zSeries resource utilization - signal the Domino server to start replications at the completion of the lbatch processing (may be variable on end-of-month/week)The ability to support servers operating in different locales in the same LPARlThe ability to handle Domino 6 and R5 servers concurrently on the same LPAR.lA non-intrusive tool for your Domino servers. The z/OS console support for Domino does not require changes to lthe basic server configuration. You can still start and run the server from a telnet or rlogin session if desired.Use of Domino 6 new Fault Recovery option may be used with z/OS Console Support for Domino.l


Summary of ChangesFunctional Changes

New function for z/OS Console Support for Domino 6 includes the ability to handle servers that have different code versions. Several Domino 6 versions can be accomodated as well as one R5 version. Function is provided by new executables, revised setup script, and updated JCL procedures.

Changes to this Manual

This manual has been changed globally for the new release of Domino 6 for z/OS. This section summarizes the sections that have had major changes. Note that this table does not include those sections that have had minor editorial or typographical corrections.

Chapter, "Section" DescriptionChapter 1, "Introduction" New function.Chapter 2, "Prerequisites" New prerequisites based on release of Domino 6 for z/OS. Chapter 2, "Domino console support for multiple domino versions"

New section.

Chapter 3, "Install Instructions" Section completely rewritten for new install procedure.Chapter 5, "What to Look For" New domcon log file output example.

1

z/OS Console Support for Lotus Domino 6.0.2 Chapter 1 - Overview

How the Console Support Works


Console SupportWithout the z/OS Console Support for Domino, the Domino server is started by accessing UNIX Systems Services from either a telnet or rlogin session. From the UNIX System Services session the server may be started by either invoking the server command or shell script rc.notes.

The server command provides a Domino console where you can enter Domino console commands and see the output. This Domino console is a dedicated session on z/OS. The z/OS programmer or Domino administrator has the responsibility of securing this physical session to protect the Domino server. If the session loses connection to z/OS, then the Domino server continues to run in the background without a console.

The rc.notes shell script runs in the background with no dedicated session. Domino console commands can be issued and the output displayed using another shell script named concom.

With the z/OS Console Support for Domino, you can start and stop the Domino server in the background from the z/OS system console without using a UNIX System Services session. Domino console commands may also be issued and the Domino console output displayed from the z/OS system console. Filtering may also be defined to filter what Domino console output is displayed on the z/OS system console. In the case of multiple partitioned Domino servers, commands can be sent and output received from any of the partitioned Domino servers.

The following z/OS system console procedures are provided:

DOMINS - used to start a Domino server and the monitor process which routes messages to the operator's lconsole.DOMINK - used to shut down a Domino server and clean up any resources left over after a server has stopped. lThis procedure will also clean up any resources left over from an abnormal shutdown of your server.DOMINM - used to stop and restart output from the Domino console on the z/OS system console. lDOMINC - used to send a command from the console to a Domino for z/OS server.l

A UNIX System Services command, domoe, may also be used to issue Domino console commands and display the output from the command from any UNIX command line interface (telnet, rlogin, OMVS, or ISHELL session). In the case of multiple partitioned Domino servers, domoe may be used to issue Domino console commands to any of the partitioned Domino servers.

The z/OS system console procedures are designed to be used by the z/OS System Administrator and Operations staff. The domoe UNIX system Services command was designed to be used by Domino and Lotus Notes administrators.

The z/OS Console Support for Domino uses the following z/OS user IDs:

Domino console ID which has root security access.lDomino server IDs which own the Notes data directory and are used to start the server. lDomino and Lotus Notes administrator IDs used to telnet or rlogin on to UNIX System Services and invoke ldomoe.

2

z/OS Console Support for Lotus Domino 6.0.2 Chapter 2 - Preparing the z/OS system

Chapter 2 - Preparing the z/OS system

Prerequisites


Before you beginPlease make sure the following prerequisites are met before starting.

Domino 6 for z/OS, completely installed and working in the appropriate locale.lThere should be a z/OS systems programmer and Domino administrator available to help with the install.lThe MOUNT FILESYSTEM parameter for the product HFS in the BPXPRM SYS1.PARMLIB member must be set lto SETUID or let it default. Do not change it to NOSETUID. For more information, see z/OS MVS Initialization and Tuning Reference, SA22-7592.RACF - Domino Console support requires z/OS UNIX security; BPX.DAEMON facility class to be set up in the lRACF database. If you are new to setting up the BPX.DAEMON facility class, see z/OS UNIX System Services Planning, GA22-7800. It shows how to implement z/OS UNIX security. High-Level- Qualifier.SCEERUN2 needs to be added to RACF PROGRAM General Resource Class.l

Why z/OS Console Support for Domino requires z/OS UNIX Level Security

The ability to switch between user IDs is a protected function controlled by your System Authorization Facility (SAF) server. In the UNIX Services environment, this function is managed by the Facility class member BPX.DAEMON. The Domino console was implemented to support multiple Domino partitions. Similar to INETD daemon (provides telnet/rlogin sessions), Domino console eliminates the need to copy or replicate a version of itself for an additional Domino partition. The Domino console must be enabled by the security server or else this ability to switch to the correct Domino's server SAF ID will fail and the Domino console will not work correctly.

Migration


Migrating from an Earlier Version of the Domino ConsoleMigrating from 5.0.3 and Subsequent 5.0.x Releases

If you are migrating from Domino Release 5.0.3 or a subsequent 5.0.x release to Domino 6 for z/OS, you should follow the steps in the installation section. Migration information is included in Chapter 3, "Installation." Before starting, we suggest that you retain a copy of the domino_global_env file for reference during the install. If you have customized other parts, you should retain a copy of those also so that you can reconcile the customizations with the Domino 6 for z/OS version. In particular, all of the DOMIN* JCL procedures are updated for Domino 6 for z/OS, so you will need to migrate any customizations to the new version.

Note: If you are running R5.x and Domino 6 for z/OS, you must use this current level of z/OS Console Support for Domino.

3

z/OS Console Support for Lotus Domino 6.0.2 Chapter 2 - Preparing the z/OS system

Domino Console Support for Multiple Versions


Supporting multiple Domino versionsBeginning in Domino 6 for z/OS, you can have multiple Domino server versions installed and operating concurrently. Several Domino 6 for z/OS versions can be installed in addition to one Domino R5 version. Any or all of the servers associated with these Domino versions can be controlled using the z/OS Console Support for Domino. Versions are differentiated by the installed directory location (also known as the program directory).

Configuration is controlled by the domino_global_env file, which is extended to handle multiple versions. Version-sensitive environment variables that were previously common to all servers are redefined on a per-server basis as special "version" variables. When a function to that server is invoked, a new front end program causes the content of the "version" variables for that server to replace the value of the corresponding common variables, then drives the appropriate version of code. A unique server alias name is required for each server regardless of version.

The domcon.setup script is updated to support multiple code versions. The domino_global_env configuration file utilizes the "version" variables, with fewer common variables. A script option is added for specifying the target program library, allowing the script to operate on the configuration data for a program library other than its own. A second new option allows server variables to be appended to the existing domino_global_env data instead of creating an entirely new file. Using the latter, you can use an existing domino_global_env file containing R5 server data as a base and just append the Domino 6 for z/OS server definitions reflecting its configuration data.

NLS Considerations


NLSUse the information in the "NLS Considerations" sections of the Domino 6 for z/OS Install Guide for this release and the corresponding Release Notes to set up the Domino server for your locale. Before running the Setup Script in Chapter 3, set the language environment variable to "C" (LANG=C).

Different servers may use different locale settings. When servers are started using z/OS Console Support for Domino, each server's locale is controlled by the value of the corresponding SRVnn_VARN_LANG environment variable in the domino_global_env file. To customize the locale settings for your servers, edit the domino_global_env file. For each server in your configuration, find the sample line that contains SRVnn_VARN_LANG (SRVnn identifies the server). Uncomment the sample line by removing # from the start of the line. Change the value to the right of the equal sign (=) to reflect your locale. This causes the console support to set the LANG environment variable to the value you specify before it starts the server. For example, if you want the server to operate in the German locale, change #SRV01_VARN_LANG=LLLLL.PPPPPPPP to SRV01_VARN_LANG=De_DE.IBM-273. A complete table of supported locales is in the "NLS Considerations" section of the current Domino 6 for z/OS Install Guide. Note that before 5.0.6, all R5 servers in an LPAR were required to operate with the same locale setting.

Code translations between the server and the zSeries console assume that the z/OS system is using the IBM-1047 code page.

If you customized your zSeries so that the UNIX session for your Domino console ID does not start in the C locale, then you need to convert the Domino console .profile and domino_global_env files to the same locale. Use the iconv command to do the conversion. See the the following example and, if necessary, see: "Customizing For Your National Code Page" in the UNIX System Services Planning for more information.

Example of using iconv command to convert domino_global_env from 1047 to Japanese 939 code page:

iconv -f IBM-1047 -t IBM-939 domino_global_env > domino_global_env.939

The domoe command should operate in the same locale setting as the Domino for z/OS Server. No character translations are performed for commands and messages passed between the domoe user and the Domino Server. If you have multiple Domino servers running in different locales and want to administer all the servers from a common UNIX user ID through the domoe command, then you should issue the "export LANG=Xx_XX.IBM-nnn" command whenever you issue the domoe command for a server running in a different locale than currently set.

4

z/OS Console Support for Lotus Domino 6.0.2 Chapter 3 - Installing the z/OS Console Support for Domino

Chapter 3 - Installing the z/OS Console Support for Domino

Install instructions


Installation

Installation Summary

The following summarizes the steps to make the console support operational. For a new installation, you must perform all of these steps. When upgrading (replacing a code version ), adding a code version (program library), or changing server configurations, review all of the following steps.

Note: Shut down any active servers controlled by the z/OS Console Support for Domino or OS/390 Console Support for Domino before executing these procedures.

Uploading DOMIN* JCL procedures and install1.Setting Up the DOMCNSL ID2.Adding DOMIN* procedures to the Started Class/Started Procedure Table 3.Verifying High-Level- Qualifier.SCEERUN2 is in the RACF PROGRAM General Resource Class4.Authorizing Notes Administrator IDs to enter domoe commands5.Authorizing server ID(s) to BPX.JOBNAME6.Running the console support setup script7.Adjusting the DOMCNSL .profile for your location8.Adjusting the domino_global_env file9.Finishing set up for user IDs that will run the domoe program10.

Step 1: Uploading DOMIN* JCL procedures and install

The JCL procedures provide the mechanism to invoke the Domino Console function from the z/OS system console. These procedures are located on the product CD and must be uploaded and placed where they can be used with the start command from the system console. The procedures include the following:

DOMINC - Issues commands to the Domino serversDOMINK - Stops the Domino serversDOMINM - Enables and disables the monitorDOMINS - Starts the Domino servers

Migration Note: If you are migrating from an earlier version, be sure to install the JCL procedures from the Domino 6 for z/OS product CD. All of the above procedures have changed for Domino 6 for z/OS.

1. You can either create a new partitioned data set (PDS) or use the existing PDS (DOMINO.JCL.CNTL) that was made during the Domino server install. This dataset is used to store the DOMINC, DOMINK, DOMINM and DOMINS members. If you decided to create a new PDS, log on to Domino 6 for z/OS TSO and use ISPF (option 3.2) to specify the following data set attributes:

Space units BLOCKS Primary quantity 10 Secondary quantity 1 Directory blocks 5 Record format FB Record length 80 Block size 3120

You can specify any permitted PDS name. DOMINO.JCL.CNTL is used in the following instructions.

5


2. Transfer the sample files from the CD-ROM on your workstation to the pre-allocated PDS using the FTP service on your workstation. These files must be transferred to the z/OS system in binary mode.

FTP Example:

a. On the workstation, start an FTP session to the z/OS UNIX Services FTP server. b. Enter bin to have the file transferred in binary. c. Enter cd 'DOMINO.JCL.CNTL' to change to the target location of the PDS. d. Using the LCD command, change to the appropriate drive where the CD is located. e. Enter put DOMINC.600 DOMINC to transfer this file. f. Enter put DOMINK.600 DOMINK to transfer this file. g. Enter put DOMINM.600 DOMINM to transfer this file. h. Enter put DOMINS.600 DOMINS to transfer this file.

Note: The above "put" command examples are for the Domino 6 release as specified by the ".600" filename suffix. If you are using this example for some other release, you must verify the JCL file names on your CD and enter the correct filename suffix (for example, put DOMINC.600 DOMINC for Domino 6).

3. After the file transfer, check that the PDS contains these files and that they are readable:

DOMINO.JCL.CNTL(DOMINC) DOMINO.JCL.CNTL(DOMINK) DOMINO.JCL.CNTL(DOMINM) DOMINO.JCL.CNTL(DOMINS)

4. Copy DOMINC, DOMINK, DOMINM, and DOMINS to your SYS1.PROCLIB. Use the instructions in the JCL for customization.

Step 2: Setting Up the DOMCNSL ID

The DOMCNSL id requires daemon authority so that the console support programs running in it's address spaces can utilize setuid to switch between server IDs. All programs loaded into an address space that requires daemon authority must be defined to program control. If a program that is not a controlled program is loaded, the address space is marked dirty and cannot perform daemon activities, such as setuid(). See z/OS V1R2.0 UNIX System Services Planning, GA22-7800 which further explains the concept of a dirty environment and how to find modules that are not defined to program control.

The following steps presume that z/OS UNIX Level security is already implemented and that the BPX.DAEMON class is already defined. If this is the first time you will be using BPX.DAEMON, refer to z/OS UNIX System Services Planning, GA22-7800. This publication describes how to implement z/OS UNIX Level security. The DOMSAF sample JCL has some of the required RACF commands for setting up the BPX.DAEMON facility class, including commands for defining system data sets to program control.

You can set up the DOMCNSL ID by either doing steps 1-4 below or by using the DOMSAF JCL sample and following the instructions in the JCL. We recommend reading the substeps even if you use the JCL sample. The DOMSAF sample was placed in a PDS during the Domino server install. If the sample is not available, FTP it from the Domino CD-ROM. The user ID that will be used to enter these commands must have the Special attribute set.

1. Create a user ID for the console support. This user ID must be defined as a superuser ID and have a valid home location in its OMVS segment. This user ID must also be defined with its default group as the same group ID used when the Domino servers were set up.

ADDUSER DOMCNSL DFLTGRP(NOTES) PASSWORD(password) OMVS(UID(0) PROGRAM('/bin/sh') HOME('/u/domcnsl')) LISTUSER DOMCNSL OMVS

Note: DOMCNSL is the default user ID. If you change this ID, please make sure you also change the other started procedures in this chapter. Throughout the install instructions, the z/OS console support ID is DOMCNSL.

6


2. Grant the z/OS console support user ID read access to the BPX.DAEMON facility class. Update BPX.DAEMON - read permission must be granted to the DOMCNSL user ID. If this access is not allowed, RACF does not allow the started task to switch to the Domino user ID.

PERMIT BPX.DAEMON CLASS(FACILITY) ID(DOMCNSL) ACCESS(READ) SETROPTS RACLIST(FACILITY) REFRESH

3. The user ID that will be used for running the install script for the console support must be UID 0 and have read access to BPX.FILEATTR.PROGCTL and BPX.FILEATTR.APF before running the domcon.setup install script. This is required so the install script can set the extended attributes for the console support to be APF authorized and program controlled. The ID may be an install id, the DOMCNSL id or another UID 0. Use the name of the appropriate ID in place of the install_id designator in the commands below.

RDEFINE FACILITY BPX.FILEATTR.PROGCTL UACC(NONE) SETROPTS RACLIST(FACILITY) REFRESH PERMIT BPX.FILEATTR.PROGCTL CLASS(FACILITY) ACCESS(READ) ID(install_id)SETROPTS RACLIST(FACILITY) REFRESH

RDEFINE FACILITY BPX.FILEATTR.APF UACC(NONE) SETROPTS RACLIST(FACILITY) REFRESH PERMIT BPX.FILEATTR.APF CLASS(FACILITY) ACCESS(READ) ID(install_id) SETROPTS RACLIST(FACILITY) REFRESH

Step 3: Adding DOMIN* Procedures to Started Class/Started Procedure Table

For installations using the Started class:

Add DOMIN*.* to the started class as follows:

RDEFINE STARTED DOMIN*.* STDATA(USER(DOMCNSL) GROUP(NOTES)) SETROPTS RACLIST(STARTED) REFRESHRLIST STARTED DOMIN*.* STDATA

For installations that use the Started procedure table (ICHRIN03): 1. Add the following entries to the Started procedure table. Remember to IPL before starting these new procedures:

DOMINCDOMINKDOMINMDOMINS

2. Verify you are using the correct user ID and Group ID for these started tasks.

In our example you would have the following:

DC CL24'DOMINC DOMCNSL NOTES'DC CL24'DOMINK DOMCNSL NOTES'DC CL24'DOMINM DOMCNSL NOTES'DC CL24'DOMINS DOMCNSL NOTES'

taskname

(8)

taskuserid

(8)

taskgroup

(8)

7


Step 4: Verifying High-Level Qualifier.SCEERUN2 is in the RACF PROGRAM General Resource Class

Verify the high-level qualifier.SCEERUN2 is in the RACF Program General Resource Class by entering the following RACF Command:

RLIST PROGRAM * ALL

Verify the high-level qualifer.SCEERUN2 is listed under the DATA SET NAME

Example:

DATA SET NA,ME VOLSER PADS CHECKING- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - CEE.SCEERUN2 * * * * * * NO

If SCEERUN2 is not in the PROGRAM General Resource Class, enter the following RACF Commands, as shown in the example below:

Example:

RALTER PROGRAM * ADDMEM('CEE.SCEERUN2'/'******'/NOPADCHK) UACC(READ)SETROPTS WHEN(PROGRAM) REFRESHRLIST PROGRAM * ALL

Step 5: Authorizing Notes Administrator IDs to enter domoe commands

The domoe command provides the capability to access the server console from your own ID within UNIX System Services. See "Sending Commands to the Server from Unix System Services" for more information on domoe. Before starting this section, you should know the ID for each server, know the UNIX IDs that will be issuing domoe commands and decide what server(s) each ID will be allowed to access. Typically, each Domino administrator requires a user ID that has been set up to run the domoe command

To allow a UNIX user to issue domoe commands to a server, the following three conditions must be met:

1. BPX.SERVER is set up with Update access for the user ID that will be entering commands.2. A SURROGAT class entry must be set up for the server user ID.3. The user ID using domoe commands must be given access to the SURROGAT class for the server.

To set up the BPX.SERVER and the SURROGAT class for user IDs using the domoe command, do one of the following:

Update and use the DOMSAF JCL.ll

Execute the REXX EXEC sample provided in /usr/lpp/lotus/bin/tools/domoe_setup. If you use it, make sure llthat the user ID from which you are executing the command has the RACF special attribute set.

You can run this from the TSO environment by using ishell or OMVS. Note that this REXX EXEC does not run from telnet or rlogin. To run the EXEC for the first time, run all three steps (as described in the EXEC), one at a time. Follow the instructions on the screen.

Or use the following instructions:ll

Security Note: When setting up the SURROGAT class, you must not run these commands on a UID of 0. By running these commands on a UID of 0, you will be authorizing any UID 0 userid to log on to the system with the id you are permitting to the SURROGAT class without specifying a password. This means that if your FTP server runs with UID 0, then anyone can log on with FTP without specifying a password with these ids. This is also the case for telnet and rlogin. Furthermore, you do not want to permit any userid to these profiles that has a UID of 0.

1. Define the BPX.SERVER facility class and SURROGAT class.

RDEFINE FACILITY BPX.SERVER UACC(NONE)SETROPS RACLIST(FACILITY) REFRESHSETROPTS CLASSACT(SURROGAT)

8


2. For each server, define the BPX.SRV SURROGAT class for the server user IDs defined to your system. The RDEFINE command will create an entry in the SURROGAT class for the sever ID. Replace server_id with the actual ID used by your Domino server. Repeat this step for each Domino server ID.

RDEFINE SURROGAT BPX.SRV.server_id UACC(NONE)

3. Allow the Notes Administrators user IDs access to the domoe command by permitting them to the BPX.SERVER facility and BPX.SRV SURROGAT classes.

For each Notes Administrator domoe user, permit their user ID to the BPX.SERVER Facility Class. You will lneed to PERMIT each user ID that you want to be allowed to use domoe.

PERMIT BPX.SERVER CLASS(FACILITY) ACCESS(UPDATE) ID(userid) SETROPTS RACLIST(FACILITY) REFRESHRLIST FACILITY BPX.SERVER AUTHUSER

For each server to which a Notes Administrator sends commands through domoe, you need to PERMIT that luser to the server's BPX.SRV.server_id SURROGAT class member. You will need to PERMIT once for each server a user may access.

PERMIT BPX.SRV.server_id CLASS(SURROGAT) ID(userid) ACCESS(READ)

Example:

An installation has 3 servers (whose IDs are SERVERA, SERVERB and SERVERC) and 2 UNIX IDs (ADMIN1 and ADMIN2) that can access them with domoe commands. ADMIN1 is allowed to access SERVERA and SERVERB. ADMIN2 is allowed to access SERVERB and SERVERC. The following commands provide the necessary authorizations.

RDEFINE FACILITY BPX.SERVER UACC(NONE)SETROPS RACLIST(FACILITY) REFRESHSETROPTS CLASSACT(SURROGAT)

RDEFINE SURROGAT BPX.SRV.SERVERA UACC(NONE) RDEFINE SURROGAT BPX.SRV.SERVERB UACC(NONE) RDEFINE SURROGAT BPX.SRV.SERVERC UACC(NONE)

PERMIT BPX.SERVER CLASS(FACILITY) ACCESS(UPDATE) ID(ADMIN1) PERMIT BPX.SERVER CLASS(FACILITY) ACCESS(UPDATE) ID(ADMIN2) SETROPTS RACLIST(FACILITY) REFRESHRLIST FACILITY BPX.SERVER AUTHUSER

PERMIT BPX.SRV.SERVERA CLASS(SURROGAT) ID(ADMIN1) ACCESS(READ)PERMIT BPX.SRV.SERVERB CLASS(SURROGAT) ID(ADMIN1) ACCESS(READ)PERMIT BPX.SRV.SERVERB CLASS(SURROGAT) ID(ADMIN2) ACCESS(READ)PERMIT BPX.SRV.SERVERC CLASS(SURROGAT) ID(ADMIN2) ACCESS(READ)

Step 6: Authorizing server ID(s) for BPX.JOBNAME

A server that is started with the z/OS Console Support for Domino uses the _BPX_JOBNAME environment variable to assign a unique job name for itself and each task associated with the server. To authorize this, the server ID must be permitted to the BPX.JOBNAME FACILITY class. Remember to replace the "server_id" in the following with the actual ID used by your Domino server. You must repeat this step for each Domino server user ID.

RDEFINE FACILITY BPX.JOBNAME UACC(NONE)SETROPTS RACLIST(FACILITY) REFRESHPERMIT BPX.JOBNAME CLASS(FACILITY) ACCESS(READ) ID(server_id)SETROPTS RACLIST(FACILITY) REFRESHRLIST FACILITY BPX.JOBNAME ALL

9


Example:

An installation has three servers whose IDs are SERVERA, SERVERB and SERVERC. All three servers will be driven by the z/OS console support and require authority for _BPX_JOBNAME. The following commands provide the necessary authorizations.

RDEFINE FACILITY BPX.JOBNAME UACC(NONE)SETROPTS RACLIST(FACILITY) REFRESHPERMIT BPX.JOBNAME CLASS(FACILITY) ACCESS(READ) ID(SERVERA)PERMIT BPX.JOBNAME CLASS(FACILITY) ACCESS(READ) ID(SERVERB)PERMIT BPX.JOBNAME CLASS(FACILITY) ACCESS(READ) ID(SERVERC)SETROPTS RACLIST(FACILITY) REFRESHRLIST FACILITY BPX.JOBNAME ALL

Step 7: Running the console support Setup Script

The setup script performs the necessary operations on the domcnsl id's home directory and all of the notesdata directories to make the domino console function operational. The script creates a "noteslog" subdirectory for each notesdata directory and creates a "logs" subdirectory under the home directory for the Domino console ID. It also sets up the Domino console ID home directory with a .profile (if one does not exist). The Setup Script examines your Domino server configuration in the program directory to find the notesdata directory(s) and owner IDs. Using the configuration data, it builds a domino_global_env file with default settings that reflect the configuration and places it in the home directory for the Domino console ID. If there is already a file by this name, a new file is created called domino_global_env.new. Appropriate extended file attributes are also set for the Domino console executables.

For Domino 6 for z/OS, the script is updated to provide support for multiple code versions. Function is added to set up a bin subdirectory under the home directory for the Domino console ID. This directory is used to access a new executable that provides multiversion support. A new script option is added to allow server variables to be appended to the existing domino_global_env data and a second new option allows for targeting a program directory other than /usr/lpp/lotus .

The setup script provides output on standard out to chronicle the operations it performs. You should tee or redirect this output to a file for future reference as indicated below.

To run the setup script, do the following:

Ensure that you are running on a superuser id (UID=0). The script must be run from a UID=0.lEnsure the user ID from which you are running the install script has read access to BPX.FILEATTR.PROGCTL land BPX.FILEATTR.APF facility classes.Identify the program directory name for the code version to be set up. Versions are differentiated by their linstalled directory location (also known as the program directory). The program directory name always ends with 'lotus' and contains the .install.dat file when Domino install program has completed successfully.Decide which script options you need to use based on your installationl

You have a new Domino 6 for z/OS installation or are replacing an existing installation with Domino 6 for lz/OS. Identify the program directory. If not /usr/lpp/lotus, use the domcon.setup -p option to specify the target program directory. You have installed Domino 6 for z/OS in addition to an existing installation. You will continue to run one lor more servers from the existing installation. The domino_global_env file includes your current server definitions. Identify the program directory for the new install. If the program directory is not /usr/lpp/lotus, use the domcon.setup -p option to specify the target program directory. Use the -a option to append server definitions for this configuration to the existing data. If -a is omitted, a full set of variables is created in domino_global_env.new and you will have to manually combine the new server variables with your existing domino_global_env.

Invoke the script by issuing the command. (Use the -a and -p options only if needed, as described in the lprevious bullets):

program_directory/bin/tools/domcon.setup -a -p target_dir parm1 2>&1 | tee setup.out

-a (optional) causes the server variable data derived from the config data in the specified program directory to be appended to existing domino_global_env data. Output is in domino_global_env.new. -p target_dir (optional) identifies the program directory whose config data will be used to do the setup. If omitted, the target directory defaults to /usr/lpp/lotus.parm1 (required) is the home directory for your Domino Console ID.

In addition to appearing on the terminal, the file setup.out will contain the script output.

10


Review the output from the setup script. Verify that all Domino servers were identified by their user ID and lthe name of their notesdata directory. Check that each server's user ID is in the same group as the Domino Console ID. Information regarding these servers will be included in the domino_global_env file, enabling them to be controlled by Domino console. Identify servers that you will not want controlled by Domino Console as well as any additional servers that should be added to the list.If a domino_global_env file is present in the home directory of your Domino Console ID before running the lsetup script, a file is created called domino_global_env.new. An existing domino_global_env file will not be replaced. You can use either the new or the existing file, but you will need to reconcile the content of the new file with the content of the existing file to ensure it includes all pertinent information. If you will be using the new file, rename it to domino_global_env.

Example 1:

A location performs a new install of Domino 6 in /usr/lpp/lotus. The home directory for the console id is /u/domcnsl. Use the following command to run the setup script.

/usr/lpp/lotus/bin/tools/domcon.setup /u/domcnsl 2>&1 | tee setup.out

Example 2:

A location installs Domino 6 in /usr/lpp/domino6/lotus. Domino R5 is already installed in /usr/lpp/lotus and the OS/390 Console Support for Domino has been setup to manage the server(s) associated with R5. A domino_global_env file already exists in the home directory for the console id, which is /u/domcnsl. Use the following command to run the setup script.

/usr/lpp/domino6/lotus/bin/tools/domcon.setup -a -p /usr/lpp/domino6/lotus /u/domcnsl 2>&1 | tee setup.out

Step 8: Adjusting the DOMCNSL .profile for your location.

Running the setup script creates a default .profile for the DOMCNSL id. If a .profile already exists, it is not replaced. Rather, a sample .profile is copied to the home directory of the Domino Console ID for reference and named domcon.profile. The sample .profile contains the minimum functionality needed for the Domino console to operate.

If you use the default .profile created by the setup script, you can add customizations needed at your location. If you are using another .profile, some adjustments may be needed as indicated below. If you are migrating from an earlier version, use a saved copy of this file from the earlier version for reference.

In all cases, review the following steps to be sure the .profile retains the necessary characteristics.

Change directory (cd) to the home directory of your Domino Console ID.lEdit your .profile and do the following.l

Add a line containing l

. domino_global_env Make sure this line has a preceding dot and space, as shown. Also add export at the end of the .profile. This causes all environment variables to be echoed and thus lappear in the .sto file when a DOMIN* proc is invoked. Review your existing .profile for any functions that may be detrimental to automated operations, such as a lprompt for user input during profile execution. You need to remove these or Domino Console will not operate properly.Ensure that the current directory (.) and the Domino Console ID home directory are contained in your path. l

To find out, issue echo $PATH. Be sure you are logged on to the Domino Console ID or the results may not be accurate. See the commentary in the .profile (or domcon.profile) for suggestions on how to change your .profile to add these to your path.

File the .profile to save the above changes.l

Step 9: Adjusting the domino_global_env file.

Running the setup script also creates a domino_global_env file in the home directory of your Domino Console ID. The domino_global_env file establishes the basic Domino Console control parameters for its operations with all Domino 6 for z/OS Servers that it can control. These parameters take the form of environment variables that act in conjunction with the parameters specified on individual operations. The domino_global_env file is created with default values based on the configuration data provided. While this is normally sufficient to provide basic operation, you should review the resulting file and provide any adjustments needed for your location.

11


Some environment variables affect all servers, while others affect only a specific server. The domino_global_env file created by the setup script is organized so that there is one section that contains all common variables and an additional section for each server. Each server section contains the variables for a particular server. For instance if you have an installation with 3 servers, the global env file will have a common section and 3 server sections.

Each server is identified by an alias name. In addition to specifying which server a command is to act on, the alias name is used to identify jobs in the system that are related to the server and as a prefix on console messages that come from that server. All server specific environment variables begin with the server's alias name. The alias must be 5 characters or less, with the first character being alphabetic (A-Z) and the rest alpha (A-Z) or numeric (0-9). Alphabetics must be upper case. The alias is not the same as the user ID, although it could be if the user ID falls within the above guidelines.

The domino_global_env file is created with defaulted server alias names. These have the form "SRVnn", where nn begins at 00 and is incremented for each server during initial domino_global_env generation. When the -a (append) option of the setup script is used, the script uses alias names for appended data where nn is beyond those already in use in the original file.

Each server then has a unique alias. These appear as the first characters of any environment variable name that is specific for the server. Variables for any given server are grouped together. You can use these alias names as created or you can change them to something more meaningful for your location. The alias for each server must be unique and the name must follow the above guidelines. If you are migrating from a pre 5.0.3 version, you may have to choose a different alias and update your server specific variables to reflect the new alias.

The setup script uses the install configuration data to identify the servers. If your install input included all server definitions, they should all be represented in the domino_global_env file that is created. If not, the sample server section can easily be duplicated and altered to work for any missing server. For any given server alias, the variables containing the server's user ID and notesdata directory name provide the linkage to the associated real server.

While the domino_global_env file reflects your configuration as indicated in the configuration data, it contains default values and probably needs to be adjusted to reflect your location. When adjusting the domino_global_env file and customizing it for your location, verify that all servers are represented and proceed to adjust any default values as needed.

To verify the appropriate servers are represented, do the following:

Edit the domino_global_env file in the home directory of the Domino Console ID.lCheck that there is a server section for each server that you want the Domino Console to be able to control. lSearch for the notesdata directory name or user ID name for each server. The associated variables containing the user ID and notesdata directory name provide the association with an installed server. Check for multiple server sections for any given server by searching for the notesdata directory name and/or user lID name. If you used the append option on the setup script and an existing server is included in the both the old and new configurations, the server will be represented twice in the resulting domino_global_env.new file - once in the original data and again in the appended server data. One section per server is recommended. Choose the newer section and update it to include any applicable variables from the older section. Then comment out the older section by inserting a "#" character at the start of each line or delete them from the file.If there are servers included that you DO NOT want accessed by Domino Console, you can comment out the lines lfor these server(s) by inserting a "#" character at the start of each line in this section or you can delete the lines for this server entirely.Note the alias name assigned (SRVxx). As created, this is the name you would use for the SRVID parameter (to ldesignate the target server) when any of the DOMIN* procedures (e.g. S DOMINC,SRVID=SRV01,CMD='SHOW SERVER') are invoked. Also, server output to the console is prefixed by the alias and jobs in the system are also prefixed with the alias (that is, output from d a,l). You can use the alias name as created or you can change it to something more meaningful for your location, lstaying within the guidelines provided above. You do this by changing all occurrences of the alias within a given server section to the name you prefer. For example, to change an alias from SRV03 to MAIL3 in a server section starting on line 100 and ending on line 120, you can use the vi editor and a command of "100,120s/SRV03/MAIL3/g" . If the section for a server is missing, make a copy of the sample server section at the bottom of the file, luncomment the appropriate lines and change the alias name of the variables to an alias as described in the previous step. You should also set the value of the Notes data directory name and the server's user ID in the appropriate variables at this time. The position of this section in the file does not matter.When you are satisfied that the servers you want available for control by the Domino Console are represented, lsave the file.

12


Next, follow these steps to review the settings for the environment variables that are common to all servers. Be sure to retain the quoting (if any) for any variable setting that you change.

Edit the domino_global_env file in the home directory of the Domino Console ID.lFind the common section, which is at the top in the newly created file. Review the settings for the following lvariables.The LotusDir, PATH, LIBPATH and CLASSPATH variables are common variables that are version dependent. For lDomino 6 for z/OS, these variables are no longer used. Rather they are handled with version variables (See SRVnn_VERS_ xxxx below). However, the domino_global_env file may contain data that was created for Release 5. When that is the case, they should be set as describe here for compatability.

PATH, LIBPATH and CLASSPATH - These should reflect the same values that you are using with the server ID when you start the server. These were verified during the server installation. The only change is the addition of $LotusDir/bin to the PATH. LotusDir - This variable is set to the Domino program directory by the setup script and should not be changed.

unset _BPX_SHAREAS - The unset for this variable is provided by the setup script and should not be changed. llThe setuid() function is used by the Domino Console to change its address space identity to that of the server. In order for the setuid() function to work, shared address space operation must be disabled by unsetting _BPX_SHAREAS . dsrvid - This variable contains the alias name of the default server. The server specified here becomes the target llserver when a DOMIN* proc is started and no SRVID parameter is specified. You need to decide which (if any) server you want to be the default and assign its alias name to this variable. If you do not want to designate a default, set the value to null. domcon_pws - This specifies the name of a server password data set. When enabled, this provides a password to lla server on startup. See Step 1 in this chapter for a detailed description of the data set organization, content and use. The data set name is required if you have any AAAAA_saf variable set to 1 for any server (where AAAAA is the server's alias name). domcon_pbits - Domino Console runs each server in the background with redirected input and output to files. lThese files are located in the noteslog subdirectory of the notesdata directory for each server. The default permissions for these files allows only access by the owner ID for the server (700). If you want to allow other users to access these, specify a two digit number that represents the "group" and "other" permission settings. For example, the value 60 allows read/write access to any user in the same group as the server ID but no access to "other" users (outside of the user and group). domcon_srv_startup - This variable defines the string that Domino Console looks for to consider the server llstartup complete. If not specified, it defaults to the value "Database Server started". On a normal start (DOMINS,TYPE=N), the Monitor is disabled either at the detection of this string in the server output or when the time specified in SRVnn_start_srv_sleep expires, whichever occurs first.domcon_debug - This variable should be commented out (# at start of line) or set to 0 for normal operation. llWhen set to 1 or 2, it provides additional program operation information in the .sto files located in the logs subdirectory of the domino console ID. domconsl_debug - This variable should be commented out (# at start of line) or set to 0 for normal operation. llWhen set to 2, it provides additional monitor program operation information in the domconsl.log files located in the noteslog subdirectory of the notesdata directory for the server. Note these files can become quite large.

Note: The debug setting should be set to zero once the installation of Domino Console support has been verified.

When you are satisfied that the settings are correct for your location, save the file.l

Finally, follow these steps to review the settings for the environment variables that are specific to each server. Check all of these variables for appropriate settings in each section's server specific value. Be sure to retain the quoting (if any) for any variable settings that you change.

Edit the domino_global_env file in the home directory of the Domino Console ID.lExamine all of the server specific values (below) in each server section one section at a time. Check that the lvalues set in each section are appropriate for the server and your operation.

13


SRVnn_VERS_xxxx - For Domino 6 for z/OS, version sensitive environment variables that were previously common llto all servers are redefined on a per server basis using 'version' variables. When a function is invoked to a particular server, the content of the version variable(s) for that server replaces the value of the corresponding common variable(s). The requested function is then processed. Because one of the variables must always designate the program directory location, the appropriate code version for that server is always directed to handle the processing. Names for the version variables take the form SRVnn_VERS_xxxx='value', where SRVnn is the server alias, xxxx is the name of the common variable to be replaced and 'value' is the new value assigned to the variable xxxx. For functions processed for SRVnn, the effect is the same as if xxxx had be set to 'value'. For instance, the variable SRVnn_VERS_testvar='test value' causes the variable named testvar to be set to 'test value' before processing functions directed to SRVnn

Variables that are sensitive to version include the program directory location in LotusDir as well as PATH, LIBPATH and CLASSPATH.

SRVnn_VERS_LotusDir - This variable is set to the Domino program directory for this version by the setup script and should not be changed.SRVnn_VERS_PATH - A default value is provided. However you should ensure that it reflects the PATH you are using with the server ID when you start the server from a telnet session. These were verified during the server installation. SRVnn_VERS_LIBPATH and SRVnn_VERS_CLASSPATH - These variable are not provided. The server startup processing ensures appropriate values are set in order to start the server.

SRVnn_NOTESDATAD - This variable specifies the name of the notesdata directory associated with this server. llSRVnn_safid - This variable specifies the SAF ID or user ID used for this server. This is the owner user ID of the llserver's notesdata directory.SRVnn_saf - Set this to 1 if this server requires a password on startup. This indicates that a server password is to llbe retrieved from the password PDS and given to the server when it is started. The domcon_pws variable in the common section must specify the name of the PDS. See Step 1 in this chapter for a detailed description of the dataset organization, content and use.SRVnn_start_srv_sleep - On a normal server start, specifies how long (seconds) the monitor is to look for the llserver started message before shutting down. The monitor becomes inactive when either the server started message is found or this time expires. SRVnn_kill_srv_sleep - On a server stop (except type=Q), specifies how long (seconds) to look for the server llshutdown complete message before proceeding with any further shutdown processing or cleanup. Processing proceeds when either the server shutdown message is found or this time expires. SRVnn_kill_prc_sleep - During resource cleanup, specifies how long (in seconds) to wait after issuing SIGTERM to llprocesses that are still associated with the Domino for z/OS Server. When this time expires, SIGKILLS are then issued to any remaining processes. If not specified, this variable defaults to 5 seconds.SRVnn_VARy_thisvar_1='some value here'. You can specify any number of server unique environment variables llthat need to be set for an individual server. When starting a server, the environment is scanned for variables beginning with servers alias and "_VAR". A variable whose name is the remainder of the name following the second underscore (thisvar_1 in this example) is affected as indicated by the letter "y" (in VARy) as follows.

N - New. This is a new variable to be created and will contain the value specified. If the variable already llexists, its value is replaced. For example, SRV01_VARN_STUFF='srv1 stuff' causes an environment variable called STUFF to be created with the content "srv1 stuff". The variable is visible only to SRV01.F - Front. The indicated value is appended to the front of the value of the environment variable indicated. llThe environment variable must already exist. For example, SRV01_VARF_PREPEND='pre' causes an existing variable called PREPEND to have the value "pre" added to the beginning of its content. If its original value was "abcde", its updated value would be "preabcde". The change in value is visible only to SRV01.B - Back. The indicated value is appended to the end of the value of the environment variable indicated. The llvariable must already exist. For example, SRV01_VARB_APPEND='end' causes an existing variable called APPEND to have the value "end" added to the end of its current content. If its original content was "abcde", its updated content would be "abcdeend". The change in value is visible only to SRV01.

SRVnn_VARN__CEE_DMPTARG='dump directory name' - Use this variable if you want CEEDUMPs for this server llto go into a server specific directory. If so, activate this variable by removing the # at the start of the line and change "dump directory name" to the desired directory location. Otherwise, the default location for CEE_DUMPs is the current working directory for the function. This is normally the notesdata directory for the server ID, but could be the home directory for the Console user ID (/u/domcnsl) depending on when the failure occurs.SRVnn_VARN_LANG='LLLLL.PPPPPPPP'. Use this variable to indicate the locale that the server will operate in. llThis value will be used to set the LANG environment variable before the server is started and also to determine the server's code page for any text conversion for server commands and messages. Activate the variable by removing the # at the start of the line and change LLLLL.PPPPPPPP to a valid locale setting. For example, enter De_DE.IBM-273 for the German locale. See the Domino 6 for z/OS Installation Guide for locale values. Be sure to observe the additional NLS Considerations described earlier.

14


SRVnn_domconsl_debug - This variable provides the capability to use the domconsl_debug function on a specific llserver without affecting other servers. Settings for this variable are the same as domconsl_debug, and only apply to the server indicated by SRVnn. If set, the SRVnn_domconsl_debug value takes precedence for this server over any value used in domconsl_debug. If SRVnn_domconsl_debug is not set, the value of the domconsl_debug variable applies. SRVnn_dcontroller - This variable, when set to 1, invokes the server with the Domino Console controller support. llThis support enables the server to be controlled from the z/OS Native Console as well as the new Domino 6 Domino Console support. If set, the server is started with the '-jc -c' options, enabling many GUI Domino Consoles to also be attached to the server. This setting also provides the ability to "recycle" the notes.log file without shutting down the server. See the "Using the Server from the z/Os Operater's Console" section.

Output from the domino controller (not the server) is placed in noteslog/dcontroller.log off the data directory.When you are satisfied that the settings are correct for this server, repeat the above instructions for each server linstance in the domino_global_env file.When you are satisfied that all of the settings are correct for your location, save the file.l

This completes the changes to the domino_global_env file.

Step 10: Finishing set up user IDs that will run the domoe program

Domino administrators will require a user ID that has been set up to run the domoe program, which is used to issue Domino console commands and display the output on a UNIX system services telnet or rlogin session.

Unlike the Domino Console functions that are invoked from the zSeries console, the domoe program runs on a normal (not UID 0) UNIX services user ID. At least one Domino administrator user ID should be set up to access each server. This provides you with the capability to access the server console from this user ID and use appropriate Domino console commands to manage the server(s).

domoe is built around the SAF surrogate authorization. This protects the server's input and log files by not having to authorize these files directly to the user who uses domoe. Access to these files is only given at a thread level for the duration of the command being entered in domoe. This allows these commands to be audited and protects the server's files since no authorization exists to them outside of domoe. You will need to perform the following for each user ID that will be using domoe.

Authorize the user ID for system functions via RACF as described in Step 4 above.lProvide access to the domoe executable. The setup script provides a link from the /bin directory to the domoe lexecutable when possible. Otherwise, you can update the PATH environment variable for the user ID to access /usr/lpp/lotus/bin where the domoe executable resides or use the absolute directory location to invoke the program. Moving the executable is not suggested as this resets extended file attributes that are needed for program execution. Provide read access for the ID to the domino_global_env file in the Domino Console home directory (usually l/u/domcnsl). During execution, domoe reads the domino_global_env file and uses some of the parameter values. Any ID that uses domoe will need read permission to this file. The setup script allows the group read access for the domino_global_env file that it creates. You may need to chmod the file/directory to allow the access.Set appropriate environment variables for domoe execution. Each user ID of domoe must set the following lenvironment variables, typically in the .profile they run with:

domoe_env - (required) Set to the Domino Console ID's home directory.ldomoe_srvid - (required) Set to the alias name of the server to be accessed.ldomoe_debug - (optional) When set to 1 or 2, provides additional information on standard out regarding linternal program operation. When omitted or set to 0, provides only normal program output on standard out.domoe_time - (optional) Indicates the time (seconds) to wait for server output. After this time, control lreturns to the command line for the next command. If omitted, defaults to 2 seconds.

The environment variables could be contained in a simple script such as the following:

export domoe_env='/u/domcnsl'export domoe_srvid='SRV01' export domoe_debug=0 export domoe_time=3

15


Once all of the above has been completed, you can access the server console and issue commands to it from the ID(s) you have enabled. To try this, first be sure that the server has been started. Then log on to one of the IDs you have just enabled and issue a command such as "domoe sh server". The show server command output for the designated server should appear on the terminal.

Note: Using domoe requires the user ID to be permitted to BPX.SERVER, which requires all executables loaded in an address space to be designated as program controlled. This can result in DOMOE ERROR 402 with reason code xxxx02af when all executables are not program controlled. If you experience this error, see Resolving Domino Console Program Control Problems in Section 01 (What to Look for) of Chapter 5 - Problem Determination.

16

z/OS Console Support for Lotus Domino 6.0.2 Chapter 4 - Using Console Support

Chapter 4 - Using Console Support

From a z/OS Operator's Console


Recycling the notes.log file while the server is activeWith the additon to the SRVnn_dcontroller domino_global_env, the z/OS Native console support is now compatible with the Domino 6 Domino Controller/Console feature. With this support, it is also possible to "recycle" the notes.log file of a running server without shutting down the server. In the past, the notes.log file contained all the server output from the entire life of the server and sub-processes. The noteslog/notes.log file could become very large, causing some filesystem management issues with filling up large amounts of DASD space.

When using the SRVnn_dcontroller setting for a specific server, from either the MVS operator's console, or the UNIX system services interface, a user can enter "recycle noteslog" and upon the next line to the console, the noteslog/notes.log file will be backed up and a new noteslog/notes.log file created. The old notes.log file is renamed using the current naming convention: notes.logyyyyMMdd.hh:mm:ss.

This support makes it easy for a customer to create a PROC to do the recycle command at a specified interval, or use cron from a shell to schedule the task. This recycle command can also be sent anytime through either one of the two methods:

1) Using DOMINC proc2) Using domoe

This recycle support is only available when using the SRVnn_dcontroller setting. It is important to note that using the SRVnn_dcontroller setting does not inhibit any current function of z/OS Native Console support.


Enabling and Disabling the MonitorTo enable or disable the console monitor for a Domino for z/OS server, start the DOMINM procedure which has the following syntax.

S DOMINM,SRVID=server_alias_name,TYPE=x

DOMINM: Name of the JCL procedure.

SRVID=server_alias_name: Identifies the target server for this operation. Replace server_alias_name with the actual alias defined for the desired server. If the SRVID parameter is omitted, the target server is designated by the "dsrvid" environment variable as specified in the domino_global_env file.

TYPE=x: Defines whether the monitor is enabled or disabled. Replace x with one of the following: E- Enable - Causes the monitor process to be enabled (started), allowing the server output to be forwarded to the z/OS console. D - Disable - Causes the monitor process to be stopped. No further server output is forwarded to

the z/OS console.

Operating Notes:

This function activates or deactivates the monitor independently of the Domino server. Server operation is not laffected. The server must be running in order to enable or disable the monitor.l

17


Examples:

The following will enable monitoring for the default Domino server.

S DOMINM The following disables monitoring for the server whose alias is SRV02:

S DOMINM,SRVID=SRV02,TYPE=D


Filtering Messages Sent to the ConsoleThe z/OS console support for Domino allows you to filter output from the Domino server before it reaches the z/OS Operator's console. The filtering examines each server output line for filter string(s) that you specify. When a string is found to be present in a server output line, the line is discarded and is not forwarded to the z/OS console.

To activate filtering, create a file called server.filters (for example, SRV01.filters) located in the noteslog subdirectory of the server's notesdata directory. The text strings that you want to use as filters are put into this file. Each line is considered a different filter string. Up to fifty filters of less than 100 characters are allowed.

Filtering is disabled if either limit is exceeded. Note that filters are case sensitive.

The z/OS console support for Domino filter function does not support National Language double byte characters and other unique national language characters.

There is a sample filter file: /usr/lpp/lotus/bin/tools/domcon.filters. Listed below are the contents.

Opened sessionClosed sessionreplicationClusterDatabases accessed:Maps ExtractorAdministration Requests

Any messages from the Domino server that contain the above text strings will not to be displayed on the operator’s console. Any occurrence of the text string in the line causes the line to be filtered. The filtering process does not search for the filter at the beginning of the line, but anywhere in the line. Therefore, filters should be as restrictive as possible.

As the console support runs, it captures statistics about how many lines are matching each filter. These are written into a file in the noteslog subdirectory of the server's notesdata directory at 10 minute intervals. The statistics file names are of the form server.filters.stats.timestamp.. For example, SRV01.filters.stats.20000309.11:08:36 is a stats file for the server whose alias is SRV01.

Example file from the results of filtering: 19990729.15:00:01,Hits, 0, 0, 0, 3, 0, 1, 0, 6219990729.15:00:01,New order, 4, 6, 1, 2, 3, 5, 719990729.15:10:01,Hits, 35, 21, 4, 11, 51, 0, 5, 2119990729.15:10:01,New order, 5, 1, 2, 4, 7, 3, 6

The above example is an illustration of statistics associated with the Example domcon.filters above. At each interval, two lines are produced. Each line starts with a time stamp. The line "Hits" denotes how many times in the previous interval a line returned from the Domino server matched that filter. The order of the hits matches the order of filter file. For example, at 15:00:01 there were 3 hits on the "Cluster" filter and 1 hit on the "Maps Extractor" filter. The remainder of the filters received no hits which, for our case, was all right since the server is only just starting. The last value on the "Hits" line indicates the number of server output lines where there was no filter match (62).

18


The console support orders the filter list, based on the statistics for the previous interval. This way the most commonly used filters in the previous intervals are searched first. This allows the console support to switch the filters based on actual usage as the server’s usage characteristics change during the day and night hours. The second line "New order" reflects the new search order for the just starting interval. In our above example at 15:00:01 the filter search order becomes:

Order Filter3 Opened session4 Closed session5 replication1 Cluster6 Databases accessed:2 Maps Extractor7 Administration Requests

This file should be used to evaluate your filter's performance. A filter that is not being found is a good candidate for update or removal. You should keep the number of filters as small as possible. The more filters you establish, the more checks that must be performed for each line returned from Domino. By limiting the number of filters, you reduce the overhead associated with trying to find a filter.

With the ability to stop and start the console monitor process independently of the Domino server, you can dynamically reset your filters and activate them without recycling your Domino servers. First update your filter file, then use DOMINM to disable the monitor and again to enable it. When reenabled, the updated filter file is processed and activated.


PasswordsThe password file is a PDS that contains the passwords to be used by Domino for z/OS servers at startup. This is an optional file and does not need to be defined unless you have server(s) that require a password and you want the password fed to the server automatically when it is started. The file should be SAF protected.

For each server that requires a password, a member must be created in the password PDS where the member name matches the SAF userid used to start the Domino for z/OS server. The member should contain a line that includes the Domino for z/OS server’s (non-SAF) password.

Remember that the password is case sensitive, so be sure to store the password in the correct case. Also, blanks can be part of the password. Therefore, after the end of the password you must specify the end-of-line marker which are the characters <end>. The line will be parsed looking for these characters and all preceding data will be considered the password.

To have the password utilized at server startup, indicate in the corresponding server section(s) of the domino_global_env file that passwords are in effect by setting the aaaaa_saf environmental variable to 1 for the partitioned Domino for z/OS server(s) that require a password ("aaaaa" is the alias name for the server). If any of the servers has the aaaaa_safenvironment variable set to 1, you must also indicate the name of the password PDS in the domcon_pws environment variable. The domcon_pwssetting can be omitted if no aaaaa_saf variables are set to 1.

Caution:

Passwords may be supplied by other methods, such as DOMINC or domoe. These methods cause a password to appear in the SYSLOG and other logs. To maintain the password's security, use the RACF-protected PDS.

19



Sending Commands to Domino ServersTo send a command to the Domino 6 for z/OS server, start the DOMINC proc which has the following syntax.

S DOMINC,SRVID=server_alias_name,CMD=command_text

DOMINC: Name of the JCL procedure.

SRVID=server_alias_name: Identifies the target server for this operation. Replace server_alias_name with the actual alias defined for the desired server. If the SRVID parameter is omitted, the target server is designated by the "dsrvid" environment variable as specified in the domino_global_env file.

CMD=command_text: Replace command_text with the Domino server command to be passed to the server you specify. This command may include blanks and it is case sensitive. If you require lower case in the command, see the SDSF considerations section below.

Operating Notes:

The CMD= parameter value must appear in single quotes if it includes spaces or special characters.lIf special characters (such as, ") are part of the command text, precede them with an escape character (such as, l\). For example, S DOMINC,CMD='broadcast \"msgtext\" \"userid\"' The monitor must be enabled in order for command output to appear on the console or in the system log. l If the monitor is not enabled, l

A message is provided to indicate that server command output will not appear on the console.lThe command is still submitted to the server for processing.lThe server command submitted is still audited in the system log.l

The server must be running in order to submit a command. lThe DOMINC proc basically provides input data to the server's console. Normal usage is for command input as ldescribed above. It can also be used to provide other input data when expected by the server, such as a reply to a server prompt. To provide the data to the server, use the DOMINC proc and place the data in the CMD= parameter value. The SRVID parameter function is unchanged.

Examples:

The following will send the "show server" command to the default Domino 6 for z/OS server:

S DOMINC,CMD='show server'

The following command will send the "replicate" command to the Domino 6 for z/OS server whose alias is SRV03.

S DOMINC,SRVID='SRV03', CMD='replicate oemvs2/washsyscnt'

SDSF Considerations:

Since SDSF under ISPF changes all characters into upper case before sending a command, this restricts what commands can be sent from SDSF.

Server commands that contain database names cannot be submitted if the database name has lowercase characters because UNIX file names are case sensitive.

SDSF Work around:

1. Use the domoe command.

2. Create a file in the /notesdata directory with the lowercase command you want to execute from the DOMINC procedure. From SDSF, enter the following command:

/S DOMINC,CMD='\<file name'

Replace file name with the name of the file you created in /notesdata.

20



Starting Domino ServersNote: Starting the Domino server can now be done in two modes: with or without the Domino Console support. This support enables the server to be "controlled" from a controller program, which allows for many GUI Domino Consoles. The Domino Controller/Console support was added in Release 6.0. With this new support (enabled with SRVxx_dcontroller=1 in the domino_global_env file), the Domino Controller can remain active after the server is shut down. This enables a GUI Console to connect to and start the server remotely. This feature is now integrated into the z/OS Native Console support. Starting the Domino server does not change from an external view, but when the SRVxx_dcontroller=1 setting is active, the Domino Controller owns the server , which provides more flexibility in accessing the Domino console. See the Domino 6 Release notes for more information on the new Domino Console support and its ramifications.

To start the server, start the DOMINS proc from the z/OS console or SDSF, which has the following syntax:

S DOMINS,SRVID=server_name,TYPE=x

DOMINS: Name of the JCL procedure.

SRVID=server_name: Defines which partitioned Domino server to start. Replace server_name with the server alias defined in the domino_global_env file. If a server name is not specified, the default server specified by the "dsrvid" environment variable in domino_global_env is started.

TYPE=x: Defines the type of start. This is not a required parameter. Replace x with either:

N - Normal start (default). Starts the Domino server and a monitor process which sends messages to the z/OS console. Once the server is started, the monitor terminates. If needed, the monitor can be restarted (enabled) using the DOMINM proc. K - Keeps the monitor active. Starts the Domino server and a monitor process. The monitor remains active until the server is stopped. Monitor can be stopped (disabled) without affecting the server using the DOMINM proc.

Note: DOMINS parameters may be entered in any order.

Operating Notes:

All variations of DOMINS cause the monitor processing to be started. The TYPE parameter determines how llong monitoring will continue - indefinitely (TYPE='K') or just until the server has started (TYPE='N'). The monitor is the console support function that causes the Domino server output to be forwarded to the lz/OS console and to appear in the system log.The value in the xxxx_start_srv_sleep enviroment variable in the domino_global_env file determines the ltimeout period (in seconds) that the start processing waits for the server to start before terminating the monitor process (TYPE='N' only). "xxxx" is the server's alias name.Server start processing looks for the server output string "Database Server started" to indicate that the server lis started. Optionally, the domcon_srv_startup environment variable in the domino_global_env file can be used to specify an alternate string. If the server started string is not found before the timeout period expires, an error is sent to the console and lthe monitor terminates. The server should be verified since the expected string was not returned. The server must have a clean environment when started in order to operate successfully. Attempting to start la server that has resources (processes, shared memory, semaphores) associated with it is flagged with an error message and the server is not started. To restart a failed server, use DOMINK,TYPE=Q to cleanup resources that may still be allocated. Then repeat the server start.

Examples:

Starts the default server. The monitor will become inactive after the server has started:

S DOMINS

Both of these commands will do a normal start of the Domino server - MAILS.

S DOMINS,SRVID='MAILS',TYPE='N'S DOMINS,TYPE='N',SRVID='MAILS'

Starts the default server. The monitor will stay active until the server is stopped or disabled with DOMINM:

S DOMINS,TYPE='K'

21



Stopping Domino ServersNote: The DOMINK and DOMINC proc can both stop the Domino server and its processes. There are differences between the two, however, especially when the SRVxx_dcontroller=1 setting is active. When you use the Domino Console support within the z/OS Native Console support, the DOMINK proc also quits the Domino Controller that owns the server. If you use the DOMINC proc only to issue a "quit" to the server, the Domino Controller remains active. This enables a GUI Domino Console to be able to connect to the controller and restart the server. To quit the controller and server from the DOMINC proc, you must issue "controller quit". The DOMINK proc always shuts down the controller and server, and can shut down the controller at any time, even if the server is not currently active.

To stop the server, start the DOMINK procedure which has the following syntax:

S DOMINK,SRVID=server_alias_name,TYPE=x

DOMINK: Name of the JCL procedure.

SRVID=server_alias_name: Identifies the target server for this operation. Replace server_alias_name with the actual alias defined for the desired server. If the SRVID parameter is omitted, the target server is designated by the 'dsrvid' environment variable as specified in the domino_global_env file.

TYPE=x: Replace x with one of the following.N - Normal shutdown (default). This sends the "drop all" and "quit" commands to the server, waits for the server to shut down (or time out), and then any leftover resources are cleaned up. S - Soft. Sends the "drop all" and "quit" commands to the server and then waits for the server to shut down (or time out). Resources are not cleaned up. Use TYPE='Q' if subsequent resource cleanup is required.Q - Quick shutdown. The console support bypasses the delay for detecting that the server stopped and proceeds immediately to perform server resource cleanup. This does not give the server an opportunity to stop using its normal shutdown processing, so do not use this to perform a normal server stop. Use this option when a server needs to be cleaned up before being restarted.

Operating Notes:

All forms of DOMINK cause the monitor processing to be stopped. lServer resource cleanup consists of purging any remaining server processes with sigterm/sigkill and removing lipcs memory and semaphore resources belonging to the server using ipcrm. This affects only resources that belong to the servers saf ID.The value in the xxxx_kill_srv_sleep enviroment variable in the domino_global_env file determines the timeout lperiod (in seconds) that the stop processing waits for the server to stop before proceeding. "xxxx" is the server's alias name.Server stop processing looks for the server output string "Server shutdown complete" to indicate that the server is lstopped. Optionally, the domcon_srv_shutdown environment variable in the domino_global_env file can be used to specify an alternate string.

Examples: The following command will stop the default server using the TYPE='N' (normal) shutdown processing:

S DOMINK

The following command will shut down the Domino server with the alias MAILS and clean up its resources without waiting for the server to stop.

S DOMINK,SRVID='MAILS', TYPE='Q'

22


From Unix Systems Services


Using domoe to Send Commands to the Server from USSOverview

The domoe command works with the UNIX System Services of z/OS to provide a way to send commands to the Domino server and receive output directly back to your UNIX user ID telnet or rlogin session. Typically each Domino administrator requires a user ID that has been set up to run the domoe command. The domoe code is installed when you install the Domino console support. Security for this function is controlled by RACF and was set up during the Domino server installation steps.

See the installation instructions on how to set up the user ID used to run domoe. The following is an example of the environment variables set for the user ID used to run domoe. You may also need to change the LANG variable if the servers are operating in different locales.

export domoe_env='/u/domcnsl'export domoe_srvid='SRV01' export domoe_debug=0 export domoe_time=3

To run the domoe command to issue a Domino console "show server" and display the output, enter the following from the UNIX system services command prompt:

domoe show server

Note: When SRVxx_dcontroller=1 is set (Domino Console support is active for the server), the "quit" command terminates only the server and its processes and does not shut down the Domino Controller. If you use only "quit", the only way to restart the server is to use a GUI Domino Console, connect to the Domino Controller, and have it restart the server. To provide a way to quit the server and controller, there is a new command: "controller quit".

Example: domoe controller quit

This command shuts down the controller and server, and is equivalent to issuing DOMINK from the operator's console.

23

z/OS Console Support for Lotus Domino 6.0.2 Chapter 5 - Problem determination

Chapter 5 - Problem determination

What to look for


Indications of problems

Messages on the z/OS ConsoleDomino Console provides error and status messages on the z/OS console. For any invocation of a DOMIN* proc, at least one message should appear. Errors are indicated with the DOM99609E message, which contains an error code that further delineates the problem. The error message with these codes should provide enough information to solve most problems. Refer to Messages and Codes in the following section for detailed descriptions of the console messages and error codes. Messages from domoedomoe is run from a normal UNIX services ID. Requested server output and messages from this function appear exclusively on the standard out for the terminal. They are not recorded in any other log files and do not appear on the z/OS console. The only exception is that the server command entered is audited and appears in the DOM99607I message on the console and in the system log. Errors encountered using domoe are listed with Messages and Codes in the following section.

Starting a Domino Server without the Domino ConsoleTo help isolate a problem, start the Domino server without the z/OS Console Support for Domino. This quickly eliminates the Domino Console as the problem source.

If a Server code version is reinstalled When a server code version is reinstalled, new Domino Console executables are created that are not designated as program controlled. Unless some action is taken to mark these as program controlled, the Domino Console function will encounter errors and will not work when functions are sent to the servers associated with the reinstalled code version..

After initially installing the code or after reinstalling the code where the server configuration has changed, the setup script should be run (or rerun) to do all of the setup work so that the function will operate. This includes marking the executables as program controlled. Alternatively, when the configuration is unchanged, you can mark the executables as program controlled by issuing the following extattr commands in lieu of rerunning the setup script. Substitute the actual program library name for the target code version (i.e. /usr/lpp/lotus) for the designation program_library in the commands below.

extattr +ap program_library/notes/latest/os390/domcon llextattr +ap program_library/notes/latest/os390/domconfellextattr +p program_library/notes/latest/os390/domconsl llextattr +p program_library/notes/latest/os390/domoell

The UNIX services ID you are using must be permitted to BPX.FILEATTR.PROGCTL and BPX.FILEATTR.APF.

DOMIN* STDOUT and STDERR FilesThese log files may provide additonal information when an error is encountered. The files are defined by the STDOUT and STDERR DD cards in the DOMIN* procedures. The default location for these files is: /u/domcnsl/logs. If these log files are not at this location, check the DD definition in the DOMIN* procedure to determine the log file location and names.

The contents of the .err files are produced by system type failures. Typically, this file is empty. The contents of the .sto files are normally only standard messages. You can edit the files and page through them to get more information on what happened. The domcon_debug variable in the domino_global_env file controls the verbosity of the information in this file (0 is low, 2 is very verbose).

25


No Messages After Starting a DOMIN* Proc

Normally, Domino Console should provide at least one message to the z/OS Console whenever a DOMIN* proc is invoked. Proper setup of the Domino Console ID, its profile, the domino_global_env file as well as proper SAF authority are required.

After issuing the start for the proc to be run, check the IEF695I message in the system log to see which ID the job was assigned to. It should be assigned to the Domino Console ID. For example after issuing a S DOMINM, you should see the following:IEF695I START DOMINM WITH JOBNAME DOMINM IS ASSIGNED TO USER DOMCNSL, GROUP NOTES

If the correct ID and Group are not assigned, please review the Installation step to "Add DOMIN* Procs to Started Procedure Table/Started Class" in Chapter 3.

If you are just installing the product, log on to the Domino Console ID. Check the present working directory after logon. It should be the home directory for the Domino Console ID (normally /u/domcnsl). To verify, issue the pwd command and check the output. Check that the .profile runs and that it invokes the domino_global_env file. This is required to establish the environment for Domino Console operation. You can check the latter by issuing the export command with no parameters, which lists all environment variables and their current values. Ensure that the variables set by the domino_global_env are present.

Locate the log files for the proc just run. These are the files produced by the STDOUT and STDERR DD statements in the JCL proc. The default directory location is the log's subdirectory of the Domino Console ID's home directory (normally /u/domcnsl/logs). The files have the extensions .sto and .err respectively. These should be the two files with the latest timestamp.

Check the .err file for any system errors and pursue accordingly. Note that using special characters without a preceding escape character (\) in the DOMINC CMD= parameter string can cause errors. The UNIX shell may attempt to interpret these and perform shell functions such as I/O redirection or string substitution. For example invoking DOMINC with a CMD="< JUNK" causes the UNIX shell to try to redirect input for the Domino Console executable, resulting in an error such as FSUM7343 cannot open "JUNK" for input: EDC5129I No such file or directory. Here is the proper way to invoke DOMINC with a preceding escape character in the CMD=parameter string: DOMINC,CMD="\<JUNK".

Check the .sto file to see how far the operation proceeded. Edit the file and page down. The following is an example of a .sto file. It indicates the profiles executed, the domino_global_env file was invoked and executed, the environment variables set as displayed by the export command at the end of the .profile and finally the beginning of the actual Domino Console module execution. Look for setup problems in the area where your log file differs. For instance, if the .profile is not executed, the ID definition or home directory may not be correct. If the domino_global_env file is not invoked, check the .profile for invocation and check that the domino_global_env file exists. Both the .profile and domino_global_env files must reside in the home directory for the Domino Console ID.

/etc/profile executed /etc/profile_localsystem executed*************************************************** Domino Console .profile has been entered ** ************************************************* Calling domino_global_env to define setup

************************************************************** ** The common values have been set in domino_global_env ** **************************************************************

***************************************************************** Environment variables for server >SRV00< have been set ** ***************************************************************

************************************************************* ** The following values are set at the end of .profile ** ** Issuing export command... ** *************************************************************

26


EDITOR="ed"HOME="/u/domcnsl" LANG="C" LIBPATH="/lib:/usr/lib:/usr/lpp/Printsrv/lib:." LOGNAME="DOMCNSL"MAIL="/usr/mail/DOMCNSL" MANPATH="/usr/man/%L:/usr/doc" NLSPATH="/usr/lib/nls/msg/%L/%N:/usr/lpp/Printsrv/%L/%N"PATH="/usr/lpp/Printsrv/bin:/bin:.:/usr/local/bin:/u/domcnsl" PRINTER="plpsc.p2f23,c,std" PS1="\$LOGNAME:\$PWD: >" SHELL="/bin/sh" SRV00_NOTESDATAD="/notesdata" SRV00_VERS_LotusDir="/usr/lpp/lotus" SRV00_VERS_PATH="/usr/lpp/lotus/bin:/usr/lpp/lotus/bin/tools:/usr/lpp/Printsrv/bin:/bin:.:/usr/local/bin:/u/domcnsl"SRV00_kill_srv_sleep="120"SRV00_saf="0"SRV00_safid="domsrv1" SRV00_start_srv_sleep="300"TZ="EST5EDT"...domcon_pbits="00" domcon_pws="DOMCON.SRVIDS"dsrvid="SRV00" ****************************************************** Domino Console Support * * Front End program - 01/25/2002 * Executable DOMCONFE started at 10:04:52 on May 20, 2002***************************************************** Server alias name is SRV00 Looking for version vars to process for server SRV00... Processing --> SRV00_VERS_PATH=/usr/lpp/lotus/bin:/usr/lpp/lotus/bin/tools:/usr/lpp/Printsrv/bin:/bin:.:/usr/local/bin:/u/domcnsl Setting variable PATH=/usr/lpp/lotus/bin:/usr/lpp/lotus/bin/tools:/usr/lpp/Printsrv/bin:/bin:.:/usr/local/bin:/u/domcnsl Processing --> SRV00_VERS_LotusDir=/usr/lpp/lotus Setting variable LotusDir=/usr/lpp/lotus

10:04:52 Invoking main program /usr/lpp/lotus/bin/domcon ***************************************************** * Domino Console Support * * Main program - 01/25/2002 * Executable DOMCON started at 10:04:52 on May 20, 2002 ***************************************************** ...

27


Resolving Domino Console Program Control ProblemsAll programs loaded into an address space that requires daemon authority (as Domino Console does) must be defined to program control. If a program that is not a controlled program is loaded, the address space is marked dirty and cannot perform daemon activities, such as setuid().

When invoked using a DOMIN* proc with the start command, initial processing is performed using the Domino Console user ID. Once the targeted server has been identified, a setuid is executed to switch to that Domino server's user ID. As noted, the system services used to perform the switch requires that all of the modules (executable programs and DLLs) loaded into the address space come from datasets or HFS files that are program controlled. When this is not the case, the DOM99609E message appears with error 032 - setuid failed. Included in the message are the RC and RSN code xxxx02AF. Related operating system messages (such as BPXP014I and BPXP015I) can also appear. These contain further information to assist in locating the problem. An example of the preceding is shown in the SYSLOG excerpt that follows.

S DOMINS $HASP100 DOMINS ON STCINRDR IEF695I START DOMINS WITH JOBNAME DOMINS IS ASSIGNED TO USER DOMCNSL$HASP373 DOMINS STARTED IEF403I DOMINS - STARTED - TIME=14.06.13 $HASP100 BPXAS ON STCINRDR $HASP373 BPXAS STARTED IEF403I BPXAS - STARTED - TIME=14.06.14 BPXP015I HFS PROGRAM /usr/lpp/lotus/bin/domcon IS NOT MARKED PROGRAM CONTROLLED. BPXP014I ENVIRONMENT MUST BE CONTROLLED FOR DAEMON (BPX.DAEMON) PROCESSING. BPXP015I HFS PROGRAM /usr/lpp/lotus/bin/domcon IS NOT MARKED PROGRAM CONTROLLED. BPXP014I ENVIRONMENT MUST BE CONTROLLED FOR DAEMON (BPX.DAEMON) PROCESSING. +SRV10 DOM99609E Error 032 SETUID to 95194 failed. RC=157, RSN=0b8802afIEF404I DOMINS - ENDED - TIME=14.06.14 $HASP395 DOMINS ENDED

Use information from any available system messages and the following list to identify and resolve the source of the program controlled problem. In addition to the information presented in this section, see z/OS V1R2.0 UNIX System Services Planning, GA22-7800 which further explains the concept of a dirty environment and how to find modules that are not defined to program control.

Check the program controlled flag in the extended file attributes for the Domino Console executables. These are lnormally set by the Domino Console setup script, Enter

ls -E program_library/notes/latest/os390/domcon and ls -E program_library/notes/latest/os390/domconfe

The extended file attributes appear to the right of the permissions and should be aps for both. Also, enter ls -E program_library/notes/latest/os390/domconsl and ls -E program_library/notes/latest/os390/domoe

The extended file attributes for these should be -ps. If the extended attributes for any of the above are incorrect, use the extattr command to set the correct attribute(s). See the section earlier in this chapter, titled "If the Server Code Version is Reinstalled...," for more information. Be sure to substitute the actual program library name of the target code version (i.e. /usr/lpp/lotus) for the designation program_library in the above commands.Ensure that the domino_global_env file contains an "unset _BPX_SHAREAS". In order for the setuid() function to lwork, shared address space operation must be disabled by unsetting _BPX_SHAREAS.Check that the MOUNT FILESYSTEM parameter for the product HFS in the BPXPRM SYS1.PARMLIB member is lnot set to NOSETUID. The NOSETUID option causes the setuid to fail.Check that the system datasets are defined as program controlled. These include SYS1.LINKLIB, SYS1.CSSLIB, lCEE.SCEERUN, CEE.SCEERUN2,CBC.SCLBDLL,CBC.SCBCCMP and TCPIP.SEZALINK. The DOMSAF JCL provides the commands to define these to program control as part of defining BPX.DAEMON. For additional information, refer to the Defining Modules to Program Control section of the z/OS V1R2.0 UNIX System Services Planning, GA22-7800.

28


Program control problems can also be encountered when using the domoe program. Here, the message displayed on standard out for the invoking terminal is domoe error 402 - error switching to server ID. In this case the failing function is pthread_security_np() and the message includes the RC (errno) and RSN (erno2). The RSN will again indicate xxxx02AF. Additional information may be obtained from system messages BPXP014I and BPXP015I that appear in the SYSLOG time that the domoe command fails. The following example illustrates the standard out messages and corresponding SYSLOG messages.

Standard out....

DOMOE ERROR 402 Error switching thread to Server RACF ID >domsrv1 DOMOE ERROR 402 pthread_security_np failed, errno=139, errno2=0be802af

In the SYSLOG...

BPXP015I HFS PROGRAM /bin/domoe IS NOT MARKED PROGRAM CONTROLLEDBPXP014I ENVIRONMENT MUST BE CONTROLLED FOR SERVER (BPX.SERVER) PROCESSING.

Use information from all available messages and review the bulleted list above to identify the problem. When verifying the extended file attribute, note that the domoe executable is program_library/notes/latest/domoe and the correct attributes are -ps. Also, the unset _BPX_SHAREAS in the domino_global_env file has no effect for domoe execution. The unset has to be performed on the ID issuing the domoe command.

In addition to the information presented in this section, see z/OS UNIX System Services Planning, GA22-7800. which further explains the concept of a dirty environment and how to find modules that are not defined to Program Control.

Messages


Domino z/OS Console Messages and Codes

z/OS Console MessagesThe following Domino Console messages appear on the z/OS system console(s) and in the system log. All messages are prefixed by the server alias name identifying the server to which the message pertains. All of these messages have a message ID of DOM996xx.

DOM99601I Domino Server command being entered from the z/OS Console A command is being submitted to the Domino server via the DOMINC proc.

DOM99602I <Command String to server>This message follows DOM99601I and contains the command string that is sent to the server. This echos the value of the cmd= parameter entered on the DOMINC proc.

DOM99603I Domino z/OS Console Monitor started Console monitor execution has begun. Domino Server messages will be forwarded to the z/OS operator's console.

DOM99604I SIGTERM issued to stop Domino Monitor The Console Monitor process has been signaled to stop. Forwarding of the Domino Server messages to the z/OS operator's console stops.

DOM99605I Monitor Shutdown - Found Server StartedThe Monitor has found the server has started and the Monitor has consequently shut down. The Domino Console Monitor was started with the DOMINS type parameter set to "n" (normal) and has found the "Database server started" line in the Domino Server output, Under these conditions, the Monitor shuts down and thus stops forwarding server output to the z/OS console.

DOM99606I Domino shutdown now completeProcessing to stop the Domino Server has completed.

DOM99607I Domino Server command being issued by: %1A command for the server has been entered by a DOMOE user whose logon ID is %1.

29


DOM99608I Entering console command %1A start or stop command %1 was submitted to the system to control the starting or stopping of

Websphere.DOM99609E Error %1 %2

This message presents all Domino Console detected errors. %1 is the Domino Console error code. %2 is a text string containing a brief desciption of the error. More detailed error code descriptions and suggested actions appears in the error codes section.

DOM99611I Issuing SIGTERM to process --> %1Domino Console has found processes that need to be cleaned up. A SIGTERM (soft kill) has been issued to remove the process whose PID appears in %1.

DOM99614I Issuing SIGKILL to process --> %1Domino Console has found processes that need to be cleaned up and were not removed with SIGTERM. A SIGKILL (hard kill) has been issued to remove the process whose PID appears in %1. This may cause ABEND messages to appear on the z/OS console.

DOM99617I Clean up in process for Domino shared memoryDomino Console has found Domino shared memroy resources remaining allocated after the server has stopped. Cleanup is in process to remove these resources with ipcrm -m.

DOM99619I Clean up in process for Domino semaphoresDomino Console has found Domino semaphores remaining allocated after the server has stopped. Cleanup is in process to remove these resources with ipcrm -s.

Error CodesDomino Console presents the following error codes and text as the error code and descriptive text part of a DOM99609E message. Some of the codes in this section show two lines. Only the first line appears in the context of the DOM99609E message. However, both lines will appear in the corresponding log file.

Some messages contain the ERRNO returned from the function calls and corresponding text as provided by the strerror function. The z/OS C/C++ Run-Time Library Reference (SA22-7821) can provide greater detail on the function call and error condition detected. A listing of the ERRNO's (Return Codes) by value and by name can be found in

z/OS UNIX System Services Messages and Codes (SA22-7807).

003 'LotusDir' environment variable not foundThe LotusDir environmental variable could not be found. Validate that the setting for LotusDir is being set in domino_global_env by checking the log for the DOMIN* proc you invoked. This value should be set in the global section of the domino_global_env file.

004 'PATH' environment variable not foundThe PATH environmental variable could not be found. Check that the PATH setting for this server is set to a non null value in the domino_global_env file.

005 Minimum number of parameters not specifiedThe members in PROCLIB pass parameters to Domino Console. The order and number of parameters passed are dependent on the function (start, kill, monitor or command) being started. The PROCLIB member you started is passing the incorrect number of parameters. Validate any changes that you made to this member.

006 First parameter is invalidThe first parameter passed by the PROCLIB member is invalid. The valid values are s, k, m or c. Validate any changes made to this member. You can refer to the original members for a sample of the correct parameters.

007 Domino Console started from a non-superuser UIDThe SAF userid associated in the "started" task is not a superuser (UID of 0). A getuid returned a non-0 value. Domino Console requires that it be started as a superuser in order to change the userid of the address space. With SDSF, check the system log, and validate what userid was associated with this start of the PROCLIB member. If the correct userid is associated with the start of this member, validate that this userid has a valid OMVS SAF segment and that its UID is 0. Otherwise, change the started class in your SAF server to associate the correct userid with the member at start time.

008 Domino Console started from a non-superuser UIDThe SAF userid associated in the "started" task is not a superuser (UID of 0). A getuid returned a non-0 value. Domino Console requires that it be started as a superuser in order to change the userid of the address space. With SDSF, check the system log, and validate what userid was associated with this start of the PROCLIB member. If the correct userid is associated with the start of this member, validate that this userid has a valid OMVS SAF segment and that its UID is 0. Otherwise, change the started class in the SAF server to associate the correct userid with the member at start time.

30


009 Value passed for FORCE is not validThe parameter passed for FORCE is not valid. The valid values are N, Y, n, or y. The default value is N. If you are specifying one of these values, validate with a debug setting of 1 or 2 that the parameters are being passed in the correct order from your PROCLIB member. Refer to the original members for a sample of the correct parameters.

010 Value passed for TYPE is not valid for start The parameter passed for TYPE not valid. The valid values are N, K, n or k. The default value is n. If you are specifying one of these values, validate with a debug setting of 1 or 2 that the parameters are being passed in the correct order from your PROCLIB member. Refer to the original members for a sample of the correct parameters.

011 Value passed for TYPE is not valid for killThe parameter passed for TYPE is not valid. The valid values are N, Q, n or q. The default value is N. If you are specifying one of these values, validate with a debug setting of 1 or 2 that the parameters are being passed in the correct order from your PROCLIB member. Refer to the original members for a sample of the correct parameters.

012 Unable to get CPU limit with getrlimit012> errno -> %1 set to -->%2

Using the getrlimit function, the CPU limit was not obtained. The error number from the getrlimit call is %1 with its associated text of %2.

013 CPU limit for Domino less than 2147483647Domino is being limited to less than 2147483647 CPU seconds. A value of 2147483647 is considered no limit and is recommended. Check the MAXCPUTIME parameter for the recommended value by entering the following from the z/OS Console: D OMVS,O This displays the active BPXPRM parameters on which you are currently running.

014 Unable to get filesize limit with getrlimit014 errno -> %1 set to -->%2

Using the getrlimit function, the filesize limit was not obtained. The error number from the getrlimit call is %1 with its associated text of %2.

015 Unable to get no. of file descr. limit with getrlimit015 errno -> %1 set to -->%2

Using the getrlimit function, the number of file descriptors limit was not obtained. The error number from the getrlimit call is %1 with its associated text of %2.

016 Address Space limit for Domino less than 2147483647Domino has been limited to a Address Space Region Size of less that 2147483647 bytes. A size of 2147483647 bytes is recommended. Check the MAXASSIZE parameter by entering the following from the z/OS Console: D OMVS,O This displays the active BPXPRM parameters on which you are currently running.

017 Unable to get address space limits with getrlimit017 errno -> %1 set to -->%2

Using the getrlimit function, the Address Space Region Size limit was not obtained. The error number from the getrlimit call is %1 with its associated text of %2.

018 Value passed for TYPE is not valid for monitorThe parameter passed for TYPE on the DOMINM proc is not valid. The valid values are D, E, d or e. The default value is e. If you are specifying one of these values, validate with a debug setting of 1 or 2 that the parameters are being passed in the correct order from your PROCLIB member. Refer to the original members for a sample of the correct parameters.

020 'LOTUSDIR' env. var. value is not validAfter processing any version variables for this server, the value for the LOTUSDIR environmental variable indicates a program library different from that specified by the LotusDir environment variable. If the LOTUSDIR variable is set, its value must be the same.

030 'dsrvid' environment variable not foundThe dsrvid environmental variable could not be found. Validate that the domino_global_env file is in the home path (RACF) for the Domino Console userid. This value should be set in the global section of the domino_global_env file. Validate that the domino_global_env file is being executed by the .profile in the home path by checking the log for the DOMIN* proc you invoked.

031 No UNIX Services SAF Segment UID found for id ->%1031 errno -> %2 set to -->%3

Using the getpwnam function, a UID was not found for the userid %1. The error number from the getpwnam call is %2 with its associated text of %3. Ensure that the userid %1 is defined in the SAF (RACF) data base.

31


032 SETUID to %1 failed. RC=%2, RSN=%3The setuid function failed trying to set the address space to UID %1. The return code (errno) from the setuid call is %2 and the associated reason code (errno2) is %3. Use the return and reason codes to help identify the problem. Generally, this has to do with SAF BPX.DAEMON definitions and permissions and with defining modules to Program Control. For RSN of xxxx02AF, more information is available in the Resolving Domino Console Program Control Problems in the Troubleshooting section.

034 Notes input log file ->%1 does not existThe notes.input file specified by %1 does not exist. The start, kill and command processing require that this file exists.

035 Write access denied to input log file ->%1The notes.input file specified by %1 does not have the correct permission bit to allow write access. Validate that the correct userid is being used and that this file is owned by the Domino/390 partition SAF userid.

036 Could not create input log file ->%1036 errno -> %2 set to -->%3

The notes.input file specified by %1 could not be created. The error number from the create call is %2 with its associated text of %3 .

037 Could not open input log file ->%1037 errno -> %2 set to -->%3

The notes.input file specified by %1 could not be opened. The error number from the open call is %2 with its associated text of %3.

038 Server id returned a 0 UID The Domino server returned a UID of 0. The UID of the Domino server must be a non-zero UID. If a 0 UID is allowed, DOMINK will terminate all processes that are owned by 0 (root) and its children. This will terminate all processes in UNIX Services.

040 'domcon_pbits' environment variable not foundThe environmental variable which controls the permission bit settings for the notes.input and notes.log files could not be found. "domcon_pbits" is specified in global section of the domino_global_env file.

041 'domcon_pbits' env. var. value is not validThe value for the environmental variable which controls the permission bit settings for the notes.input and notes.log files was found to be invalid. Valid values are between 00 and 77 decimal. "domcon_pbits" is specified in global section of the domino_global_env file.

045 Server Alias Name specified is greater than 5 charactersThe server name specified on the srvid parameter of a DOMIN* proc or the value of the dsrvid environment variable in the domino_global_env file is longer than 5 characters.

046 LOGNAME env. var. could not be setThe setenv function call failed while attempting to set the LOGNAME environmental variable to match the server's user id.

048 'execv' system call failed048 errno -> %1 set to -->%2

An error occurred when the execv system call was invoked. The resulting error number is %1 with accompanying text of %2

049 Server alias name %1 contains invalid charactersThe server name (%1) specified in the SRVID parameter of a DOMIN* proc or the value of the dsrvid environment variable in the domino_global_env file contains characters that are not allowed. The first character must be A-Z and the remaining characters must be A-Z or 0-9.

050 '%1 _safid' environment variable not foundThe environment variable that contains the SAF ID for this server was not found. This variable should be unique to the partitioned server whose alias is %1. Validate the setting in this servers section of the domino_global_env file and ensure that it is being exported by viewing the log file for the DOMIN* proc you invoked.

051 %1 is not the owner of %2 The SAF user ID (%1) for this server is not the owner of the notesdata directory indicated by %2. The ID may not be the correct owner id for the notesdata directory indicated or the notesdata directory name may be incorrect. Check the output from the setup script to find the correct notesdata directory names and the corresponding owner ID for each. Update the domino_global_env file so that the server id specified in xxxx_safid is the owner of the notesdata directory specified by xxxx_NOTESDATAD (xxxx is the server's alias name).

060 '%1 _NOTESDATAD' environment variable not foundThe environment variable that defines the name of this server's notesdata directory was not found. This variable should be unique to your partitioned server whose alias is %1. Validate the setting in the domino_global_env file and that it is being exported by viewing the log file for the DOMINM* proc you invoked.

32


061 Couldn't set PATH environment variable to ->%1061 errno -> %2 set to -->%3

The setenv command failed. Domino Console Support attempted to update the PATH environmental variable to include the notesdata path and the LotusDir path. The attempted update to the PATH was %1. The error number from the setenv call is %2 with its associated text of %3.

063 open failed on working file ->%1063> errno -> %2 set to -->%3

The working file specified by %1 could not be opened. The error number from the fopen call is %2 with its associated text of %3.

064 %1_390WAS Procname > 8 characters\n",The JCL proc name to start/stop the OS/390 Webserver is to long. The proc name is obtained from the environment variable %1_390WAS set in the domino_global_env file. %1 is the alias name of the server.

070 Failed on opendir function to ->%1 070 errno -> %2 set to -->%3

An error occurred on an opendir function to the directory in %1. The resulting error number is %2 with accompanying text of %3.

071 Failied on stats function to ->%1 071 errno -> %2 set to -->%3

An error occurred on an stats function to the module in %1. The resulting error number is %2 with accompanying text of %3.

090 '%1 _kill_srv_sleep' env. variable not foundThe time for the server to sleep after issuing the "quit" environmental variable was not found. This variable should be unique to your partitioned server. Validate the setting in the domino_global_env file and that it is being exported by viewing the log file for the DOMIN* proc you invoked.

091 '%1 _kill_prc_sleep' env. variable not foundThe time for the server to sleep after issuing "SIGTERM" environmental variable was not found. This variable should be unique to your partitioned server. Validate the setting in the domino_global_env file and that it is being exported by viewing the log file for the DOMINM* proc you invoked.

092 Could not locate the server's log fileThe server’s log file could not be found. The file name is always notes.log.

093> Could not read from the server's log fileThere is no read access to the server's log file notes.log.

094 Could not open server's log file094> errno -> %1 set to -->%2

The server’s log file could not be opened. The file name is always notes.log. The fopen call failed with return code of %1 with its associated text of %2.

121 Could not rename current output log file to ->%1121 errno -> %2 set to -->%3

An existing notes.log file was found and Domino Console Support attempted to rename it with a date/time stamp to %1. The rename call failed with return code of %2 with its associated text of %3.

122 Could not creat/open output log file 122 errno -> %2 set to -->%3

The create call to the notes.log file failed. The file name is always notes.log. The create failed with a return code of %2 with its associated text of %3.

126 Could not find %1 _saf env.varThe Domino 6 for z/OS password environmental variable was not found. This variable should be unique to your partitioned server whose alias is %1. Validate the setting in the domino_global_env file and verify that it is being exported by viewing the log file for the DOMINM* proc you invoked.

127 Invalid value for %1 _saf of -->%2The value specified for %1_saf is not valid. The only valid values are 0 or 1.

128 Could not find domcon_pws env.varThe Domino password file variable was not found. This variable should be in the global section of the domino_global_env file. It is required if password input is activated for any server. Validate the setting in the domino_global_env file and verify that it is being exported by viewing the log file for the DOMINM* proc you invoked.

129 open error on %1 password file129 errno -> %2 set to -->%3

The Domino password file specified by %1 could not be opened. The error number from the fopen call is %2 with its associated text of %3.

33


130 error reading data from %1 password file130 errno -> %2 set to -->%3

The fgets call on the Domino password file specified by %1 failed. The error number from the fgets call is %2 with its associated text of %3.

131 No End Of Line token '<end>' found The line read from the Domino password file does not contain a valid end marker. The end of the password should be marked with a "<end>". Edit the password PDS member, and correct the end of file token.

138 Couldn't find %1_start_srv_sleep env. var.The getenv function call resulted in the "%1_start_srv_sleep" environmental variable not being found. This variable should be unique to your partitioned server whose alias is %1. Validate the setting in the domino_global_env file and verify that it is being exported by viewing the log file for the DOMINM* proc you invoked.

150 Could not close input file ->%1150 errno -> %2 set to -->%3

Error closing the notes.input file. The processing of the command to the input file has already occurred. The error number from the close call is %2 with its associated text of %3.

151 Failed on iconv_open from IBM-1047 to %1.151 errno -> %2 set to -->%3

Error occurred on iconv_open to convert the server command to the %1 code page. The error number from the iconv_open call is %2 with its associated text of %3. The server command is from the "cmd=" parameter of the DOMINC proc. This error can be caused by an incorrect locale value in the SRVnn_VARN_LANG environment variable. Correct the locale value for this server in the domino_global_env file. See the Domino 6 for z/OS Installation Guide for nls locale values.

152 Failed on iconv from IBM-1047 to %1.152 errno -> %2 set to -->%3

Error occurred converting the server command to the %1 code page. The error number from the iconv call is %2 with its associated text of %3. The server command comes from the "cmd=" parameter of the DOMINC proc.

160 Domino Console Monitor already enabled.An attempt to enable the Domino Console Monitor was processed while the monitor was already enabled. The monitor stays enabled and continues operation.

161 Domino Console Monitor already disabled.An attempt to disable the Domino Console Monitor was processed while the monitor was already disabled. The monitor remains disabled.

162 Error changing to notesdata directory %1162 errno -> %2 set to -->%3

System call to change directory to notes data directory %1 returned an error. The error number from the chdir call is %2 with its associated text of %3.

163 Can't enable Monitor - server %1 not running.An attempt to enable the Domino Console Monitor was processed when its server (%1) was not running. The monitor remains disabled. You must start the server before disabling or enabling the monitor.

164 Can't send command - server %1 not running.An attempt to send a command to the Domino Server was processed when the server (%1) was not running. The command is discarded. You must start the server before you can send it a command.

165 Monitor is disabled - no command output will appear.A command was sent to a Domino Server while the Domino Console Monitor for this server was disabled. While the monitor is disabled, no server output is forwarded to the z/OS console, including any output related to the command. The command is still sent to the server and processed appropriately. Use the DOMINM proc to enable the monitor in order to view server command output.

180 Starting server system error ->%1180 errno -> %2 set to -->%3

An error occurred while trying to start the Domino server with a system call. The command being executed on the system call is %1. The error number from the system call is %2 with its associated text of %3.

181 Error starting Domino Console Monitor ->%1181 errno -> %2 set to -->%3

An error occurred while trying to start the Domino Console Monitor process with a system call. The command being executed on the system call is %1. The error number from the system call is %2 with its associated text of %3. If you used the DOMINS proc, the Domino server was started and is running in the background. If you used the DOMINM proc, the server operation continues unaffected. In either case, you can use the DOMINM proc to again try to enable the monitor.

34


182 Failure resetting the notes.input file's perm. bits182 errno -> %2 set to -->%3

Subsequent to finding that the input file’s permission bits were not set correctly, an attempt to reset the bits failed. The error number from the system call is %2 with its associated text of %3.

183 Failure resetting the notes.log file's perm. bits 183 errno -> %2 set to -->%3

Subsequent to finding that the notes.log file’s permission bits were not set correctly, an attempt to reset the bits failed. The error number from the system call is %2 with its associated text of %3.

184 The Unique Envir. Flag Variable is invalid ->%2The flag in a server unique environment variable is invalid. Check the server unique environment variables for this server in the domino_global_env file . The flag is the character following the "_VAR" in the variable name. Valid flags are N, B and F.

185 New Unique Var not found after SETENVThe getenv function call resulted in the new server unique environmental variable not being found.

186 SETENV error modifying an existing Unique env var.The setenv function call failed while attempting to modify an existing server unique environmental variable.

210 Could not find the end of the server's log fileWhile preparing to read from the server’s notes.log file, the end of file could not be found.

211 >Server shutdown complete< was not found/timeoutThe time specified in the kill_srv_sleep variable passed without the "Server shutdown complete" message being found. Domino Console will now continue shutdown processing appropriate for the DOMINK, TYPE= parameter value specified.

212 Error issuing cmd ps -ef to find monitor task212 errno -> %1 set to -->%2

Error received while issuing the ps -ef command to find the monitor task. The error number from the ps -ef command is %1 with its associated text of %2.

213 Error issuing cmd kill for monitor task213 errno -> %1 set to -->%2

Error received while issuing the kill command for the monitor task. The error number from the kill command is %1 with its associated text of %2.

240 Write failure to notes.input ->%1240 errno -> %1 set to -->%2

The write function failed in writing to the notes.input file of %1. The error number for the write call is %2 with its associated text of %3.

270 ID %1 has process %2 associated with itThe SAF(RACF) userid of %1 currently has existing OMVS processes of %2 associated with it. All existing OMVS processes with %1 must be terminated before the Domino server will start. This may indicate that the server is already running or that the environment needs to be cleaned up. Issue DOMINK with an appropriate TYPE parameter to remove any remaining processes owned by the Domino userid.

271 Couldn't send soft kill(SIGTERM) to process %1271 errno -> %2 set to -->%3

The call kill with option SIGTERM to the process %1 failed. The error code from the kill call is %2 with its associated text of %3.

272 Couldn't send hard kill(SIGKILL) to process %1272 errno -> %2 set to -->%3

The call kill with option SIGKILL to process %1 failed. The error code from the kill is %2 with its associated text of %3.

273 IPCS memory resources associated with %1The SAF(RACF) userid with your server (%1) currently has IPCS memory resources associated with it. All existing IPCS memory resources must be released before the Domino server will start. This may indicate that the server is already running or that the environment needs to be cleaned up. Issue DOMINK with an appropriate TYPE parameter to remove any remaining IPCS memory resources owned by the Domino userid.

274 ipcrm -m error on id ->%1274 errno -> %2 set to -->%3

The system call with the command %1 to release the IPCS memory resource failed. The error code for the system call is %2 with its associated text of %3.

35


275 IPCS semaphore resources associated with %1The SAF userid of the Domino server (%1) currently has IPCS semaphore resources associated with it. All existing IPCS semaphore resources must be released before the Domino server will start. This may indicate that the server is already running or that the environment needs to be cleaned up. Issue DOMINK with an appropriate TYPE parameter to remove any remaining IPCS semaphore owned by the Domino 6 for z/OS userid.

276 ipcrm -s error on id ->%1276> errno -> %2 set to -->%3

The system call with the command %1 to release the IPCS semaphore resource failed. The error code for the system call is %2 with its associated text of %3.

300 Could not execute command to load processes ->%1300 errno -> %2 set to -->%3

The system call with command %1 to gather the current processes used, failed. The error code for the system call is %2 with its associated text of %3.

301 Error reading ->%1 file for process informationA fgets call on the ipcs work file %1 failed.

330 Could not execute command to load ipcs info ->%1330 errno -> %2 set to -->%3

The system call with command %1 to gather the current IPCS memory/semaphores used, failed. The error code for the system call is %2 with its associated text of %3.

331 Error reading ->%1 file for ipcs information A fgets call on the ipcs work file %1 failed.

The following messages are issued from the Monitor (DOMCONSL) module.

501 Invalid number of parms. passed to MonitorThe invalid number of parameters was passed to the Monitor. The valid number of parameters is 4.

502 Invalid first parm passed to MonitorThe first parameter passed to the Monitor was invalid. Valid parms include i, c, s, r, o.

504 Error getting %1_start_srv_sleep env. variable The getenv function failed to find the "start_srv_sleep" environmental variable. The environment variable could not be found that specifies how long the monitor is to look for the server started message before shutting down. This variable should be unique to your partitioned server whose alias is %1. Validate the setting in the domino_global_env file and verify that it is being exported by viewing the log file for the DOMIN* proc you invoked.

505 Error getting %1 env. variable, ndataThe environment variable that defines the name of this server's notesdata directory was not found. This variable should be unique to your partitioned server whose alias is %1. Validate the setting in the domino_global_env file and verify that it is being exported by viewing the log file for the DOMINM* proc you invoked.

506 Too many filters. Filtering NOT enabledMore than 50 filters were defined in your filter list and the limit is 50. Monitor operation continues, but filtering is not enabled. To enable filtering, reduce the number of filters in your filter file, then recycle the monitor by disabling then re-enabling it using the DOMINM proc.

507 Error creating filter stats file ->%2507 errno -> %1 set to -->%2

The filter stats file could not be created in the noteslog subdirectory. Monitor operation continues with the designated filtering, however, no filtering stats are provided. The create function invoked failed with the error code %2. Its associated text is %3.

508 Server started message not found. Timing out!The time specified in the start_srv_sleep variable passed without the "Database server started" message being found in the server output. The Domino Console monitor process terminates. You need to validate the status of the domino server. A longer wait time may be needed to allow the server sufficient time to start.

509 Filter file data in error. Filtering NOT enabled.The z/OS Console Monitor for Domino found that the filter file contains incorrect filter definitions. Monitor operation continues, but filtering is not enabled. More information on filter errors is recorded in the domconsl.log file in the noteslog subdirectory. To enable filtering, correct the definition(s) in error, then recycle the Monitor by disabling then re-enabling it using the DOMINM proc.

36


510 Filter too long. Filtering NOT enabled.A filter line was encountered that was over 100 characters in length. The filter length limit is 100 characters. Monitor operation continues, but filtering is not enabled. More information on the filter in error is recorded in the domconsl.log file in the noteslog subdirectory. To enable filtering, correct the filter, then recycle the Monitor by disabling then re-enabling it using the DOMINM proc.

512 Failed on iconv_open from %1 to IBM-1047.512 errno -> %2 set to -->%3

Error occurred on iconv_open to convert the server output line from the %1 code page to IBM-1047. The error number from the iconv_open call is %2 with its associated text of %3. This error can be caused by an incorrect locale value in the SRVnn_VARN_LANG environment variable. Correct the locale value for this server in the domino_global_env file. See the Domino 6 for z/OS Installation Guide for nls locale values.

513 Failed on iconv from %1 to IBM-1047.513 errno -> %2 set to -->%3

Error occurred converting the Domino server output line from the %1 code page to IBM-1047 for display on the z/OS console. The error number from the iconv call is %2 with its associated text of %3.

999> Unknown error code %1 return An error code of %1 was passed to the error message section of Domino Console. Currently, this error code is unknown and does not have a defined error message.

Error Codes from DOMOE These codes appear as text for DOMOE error messages. The message starts with the text "DOMOE ERROR" followed by the one of the codes and accompanying text described below. The messages are written to standard out (usually the terminal screen) of the terminal invoking DOMOE. These messages do not appear as text to a DOM99609E message, do not appear on the z/OS console and do not have a DOM prefix.

400 domoe_env env. var. could not be foundThe domoe_env environmental variable was not found. This variable indicates the directory location of the domino_global_env file, which contains definitions for the servers. This variable must be set correctly for DOMOE to execute.

401 domoe_srvid env. var. could not be foundThe domoe_srvid environmental variable was not found. This variable contains the target server's alias name. No server alias is currently specified and DOMOE does not know what server the command should be sent to. This variable must be set for DOMOE to execute.

402 Error switching thread to Server RACF ID >%1402 pthread_security_np failed, errno=%2, errno2=%3

An error occurred during an attempt to switch thread identity to the Domino server’s userid. The call to pthread_security_np failed for the indicated reason and the identity was not changed. Use the return code (errno) and reason code (errno2) to help identify the problem. Generally, this has to do with SAF SURROGAT and BPX.SERVER definitions and permissions and with defining modules to Program Control. For RSN (errno2) of xxxx02AF, more information is available in Resolving Domino Console Program Control Problems in the Troubleshooting section.

403 domino_global_env file could not be foundThe domino_global_env file could not be found at the directory location specified in the domoe_env variable. This file must exist at the indicated location for DOMOE to execute.

404 Could not read the domino_global_env fileYou do not have read authority to the domino_global_env file. The ID you are running under does not have read permission on the file.

405 Could not open the domino_global_env file 405 errno -> %1 set to -->%2

The domino_global_env file could not be opened. The error number from the fopen call is %1 with its associated text of %2.

406 Server %1 variable(s) not defined in domino_global_envWhile scanning the domino_global_env file, the end of the file was reached before all of the required information was retrieved for the server whose alias is %1. One or both of the variables %1_safid or %1_NOTESDATAD could not be found. Both of these are required for DOMOE operation with the server. Either the server alias name specified in the domoe_srvid environment variable is incorrect or the server definition is not correct in the domino_global_env file. You can change the domoe_srvid environment variable to specify a different server or update the domino_global_env file to correct the definition.

37


411 LOGNAME env. var. could not be foundThe current user’s LOGNAME environment variable could not be found.

412 pthread_create failure412 errno -> %1 set to -->%2

DOMOE attempt to create a thread and the call failed. The error number from the pthread_create is %1 with its associated text of %2.

413 pthread_join failure413 errno -> %1 set to -->%2

The main process of DOMOE attempted to issue a pthread_join to wait for the processing of the created thread and this call failed. The error number from the pthread_join is %1 with its associated text of %2.

414 Invalid setting for domoe_debug - default of 0 assumedThe value of the domoe_debug environment variable was not 0, 1 or 2. The default value of 0 is assumed and processing continues for the command entered. Set the domoe_debug variable to a value of 0, 1 or 2 in order to get the desired level of debug output.

415 Invalid setting for domoe_time - default of 2 sec assumedThe value of the domoe_time environment variable contains a non-numeric value. The default value of 2 seconds is assumed and processing continues for the command entered. Set the domoe_time variable to a numeric value in order to define a wait time for server output that is other than the default time.

416 No response received - server may not be runningNo output from the server was found after forwarding the command input to the specified server and waiting the designated time for output, DOMOE processing for this command is terminated. The lack of output from the server could be caused by the fact that the server is not running or is not using the redirected input and output files notes.input and notes.log respectively. Be sure the server is running and using the redirected input and output files. It's also possible that the server was unable to provide the command output in the time allowed. You can use a larger value for domoe_time for this situation.

474 Notes input log file ->%1 does not existThe Notes input file specified by %1 does not exist. Be sure that the server has been started and is using the redirected input file.

475 Write access denied to input log file ->%1The Notes input file specified by %1 does not have the correct permission bit to allow write access. Check the permissions for the file and directory.

476 Could not open input log file ->%1476 errno -> %2 set to -->%3

The notes.input file specified by %1 could not be opened. The error number from the open call is %2 with its associated text of %3.

477 Could not close input file ->%1477 errno -> %2 set to -->%3

Error closing the Notes input file. The processing of the command to the input file has already occurred. The error number from the close call is %2 with its associated text of %3.

478 Write failure to notes.input file.478 errno -> %1 set to -->%2

The write call failed in writing to the Notes input file of %1. The error number for the write call is %2 with its associated text of %3.

482 Could not locate the server's log fileThe server’s log file could not be found. The file name is always notes.log.

483 Could not read from the server's log fileThere is no read access to the server’s log file notes.log.

484 Could not open server's log file484> errno -> %1 set to -->%2

The server’s log file could not be opened. The file name is always notes.log The fopen call failed with return code of %1 with its associated text of %2.

485 Could not find the end of the server's log fileWhile preparing to read from the server’s notes.log file, the end of file could not be found.

499 Unknown error code %1 return An error code of %1 was passed to the error message section of DOMOE. This error code is unknown and does not have a defined error message.

38

z/OS Console Support for Lotus Domino 6.0.2 Chapter 6 - Reader comments

Chapter 6 - Reader comments

Reader comments


Reader commentsReader Comment Form

Domino 6.0.2 or z/OSz/OS Console Support for Domino

We appreciate your feedback. Please tell us how we can improve this document:

How to Notify Us:

By e-mail: [email protected]

On the Web: http://www.s390.ibm.com/os390/webqs.html

By FAX: (International Access Code)-1-845-432-9405

By Mail: IBM CorporationDept. 55JA, Mail Station P3842455 South RoadPoughkeepsie, NY 12601-5400

In your mailings, please include the name of this publication and the page or section number.

When you send comments to IBM, you grant IBM a nonexclusive right to use or distribute your comments in any way it believes appropriate without incurring any obligation to you.

May we contact you? ___ YES ___ NO

Name:

Company or organization:

Address:

Phone Number:

e-mail address:

39

Documents

Lotus Domino 6.0.2 for z/OS - File/domcnsl.pdfDomino console commands can be ... the command from any UNIX command line ... used by Domino and Lotus Notes administrators. The z/OS