z/OS Console Support for Lotus Domino Lotus software Lotus Domino 6 for z/OS

Lotus Domino 6 for z/OS
Lotus software
Lotus Domino 6 for z/OS
z/OS Console Support for Lotus Domino
z/OS Console Support for Lotus Domino
Printed in USA
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.
©Copyright 1985 - 2002 Lotus Development Corporation
©Copyright IBM Corporation
Lotus Software, IBM Software Group
One Rogers Street
Cambridge, MA 02142
All Rights Reserved. Printed in the United States.
Revision History:
Original material produced for Lotus Notes and Lotus Domino Release 6.
List of Trademarks
IBM, the IBM logo, S/390, zSeries, z/OS, zFS, and WebSphere are trademarks or registered trademarks
of International Business Machines Corporation.
Lotus, Domino, Lotus Notes, and Notes are trademarks or registered trademarks of Lotus Development
Corporation and/or IBM Corporation in the United States, other countries, or both.
Tivoli/Courier is a trademark of Tivoli Systems Inc. and/or IBM Corporation in the United States, other
countries, or both.
z/OS Console Support for Lotus Domino
Contents
Chapter 1 - Overview ............................................................................................
1
Introduction ................................................................................................................................
Introduction ..........................................................................................................................
Summary of Changes ..........................................................................................................
How the Console Support Works ...............................................................................................
How the Console Support Works ........................................................................................
1
1
2
2
2
Chapter 2 - Preparing the z/OS System ..............................................................
5
Prerequisites ..............................................................................................................................
Prerequisites ........................................................................................................................
Migration ....................................................................................................................................
Migrating from an Earlier Version of the Domino Console ..................................................
Domino Console Support for Multiple Versions .........................................................................
Domino Console Support for Multiple Domino Versions .....................................................
NLS Considerations ...................................................................................................................
NLS Considerations.............................................................................................................
5
5
5
5
6
6
6
6
Chapter 3 - Installing the z/OS Console Support for Domino ...........................
9
Install Instructions ......................................................................................................................
Installation ...........................................................................................................................
9
9
Chapter 4 - Using the Console Support from a z/OS Operator’s Console ......
23
From a z/OS Operator’s Console ...............................................................................................
Enabling and Disabling the Monitor .....................................................................................
Filtering Messages Sent to the Console ..............................................................................
Passwords ...........................................................................................................................
Sending Commands to Domino Servers .............................................................................
Starting Domino Servers .....................................................................................................
Stopping Domino Servers....................................................................................................
From UNIX Systems Services ...................................................................................................
Using domoe to Send Commands to the Server from USS ................................................
23
23
24
25
26
27
28
30
30
Chapter 5 - Problem Determination ....................................................................
31
What to Look For .......................................................................................................................
What to Look For .................................................................................................................
Messages ...................................................................................................................................
Messages ............................................................................................................................
31
31
36
36
Chapter 6 - Reader Comments ............................................................................
49
iii
z/OS Console Support for Lotus Domino
October 2002
About the z/OS Console Support for Lotus Domino
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
Chapter 1 - Overview
Chapter 1 - Overview
Introduction
z/OS Console Support for Domino
Introduction
This 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:
l
The ability to manage Domino partitioned servers from the same z/OS console or from a single UNIX
System Services telnet or rlogin session
l
The capability to do an orderly shutdown of the Domino server from the z/OS Operator's console
l
RACF protected dataset to store Domino passwords (server.id) and the ability to automatically feed
them into the server's input stream at startup
l
Automated startups with secure server.id files
l
The ability to start and terminate the messages sent to the console independently of starting and
stopping your Domino server
l
The ability to establish filters to limit what information is sent to the z/OS console for Domino
l
An interface to automation systems that can start, stop, or send commands to the server in response
to error situations
l
Synchronized zSeries resource utilization - signal the Domino server to start replications at the
completion of the batch processing (may be variable on end-of-month/week)
l
The ability to support servers operating in different locales in the same LPAR
l
The ability to handle Domino 6 and R5 servers concurrently on the same LPAR.
l
A non-intrusive tool for your Domino servers. The z/OS console support for Domino does not require
changes to the basic server configuration. You can still start and run the server from a telnet or rlogin
session if desired.
l
Use of Domino 6 new Fault Recovery option may be used with z/OS Console Support for Domino.
1
z/OS Console Support for Lotus Domino
Chapter 1 - Overview
z/OS Console Support for Domino
Summary of Changes
Functional 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"
Description
Chapter 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.
How the Console Support Works
z/OS Console Support for Domino
How the Console Support Works
Without 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.
2
z/OS Console Support for Lotus Domino
Chapter 1 - Overview
The following z/OS system console procedures are provided:
l
DOMINS - used to start a Domino server and the monitor process which routes messages to the
operator's console.
l
DOMINK - used to shut down a Domino server and clean up any resources left over after a server has
stopped. This procedure will also clean up any resources left over from an abnormal shutdown of your
server.
l
DOMINM - used to stop and restart output from the Domino console on the z/OS system console.
l
DOMINC - used to send a command from the console to a Domino for z/OS server.
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:
l
Domino console ID which has root security access.
l
Domino server IDs which own the Notes data directory and are used to start the server.
l
Domino and Lotus Notes administrator IDs used to telnet or rlogin on to UNIX System Services and
invoke domoe.
Note that z/OS Console Support for Domino is incompatible with the Domino console support (server -jc)
3
z/OS Console Support for Lotus Domino
Chapter 2 - Preparing the z/OS System
Chapter 2 - Preparing the z/OS System
Prerequisites
z/OS Console Support for Domino
Prerequisites
Please make sure the following prerequisites are met before starting.
l
Domino 6 for z/OS, completely installed and working in the appropriate locale.
l
There should be a z/OS systems programmer and Domino administrator available to help with the
install.
l
The MOUNT FILESYSTEM parameter for the product HFS in the BPXPRM SYS1.PARMLIB member
must be set to SETUID or let it default. Do not change it to NOSETUID. For more information, see
z/OS MVS Initialization and Tuning Reference, SA22-7592.
l
RACF - Domino Console support requires z/OS UNIX security; BPX.DAEMON facility class to be set
up in the RACF 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.
l
High-Level- Qualifier.SCEERUN2 needs to be added to RACF PROGRAM General Resource Class.
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
z/OS Console Support for Domino
Migrating from an Earlier Version of the Domino Console
Migrating 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.
5
z/OS Console Support for Lotus Domino
Chapter 2 - Preparing the z/OS System
Domino Console Support for Multiple Versions
z/OS Console Support for Domino
Domino Console Support for Multiple Domino Versions
Beginning 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
z/OS Console Support for Domino
NLS Considerations
Use 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.
6
z/OS Console Support for Lotus Domino
Chapter 2 - Preparing the z/OS System
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.
7
z/OS Console Support for Lotus Domino
Chapter 3 - Installing the z/OS Console Support for Domino
Chapter 3 - Installing the z/OS Console Support for
Domino
Install Instructions
z/OS Console Support for Domino
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.
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
Uploading DOMIN* JCL procedures and install
Setting Up the DOMCNSL ID
Adding DOMIN* procedures to the Started Class/Started Procedure Table
Verifying High-Level- Qualifier.SCEERUN2 is in the RACF PROGRAM General Resource Class
Authorizing Notes Administrator IDs to enter domoe commands
Authorizing server ID(s) to BPX.JOBNAME
Running the console support setup script
Adjusting the DOMCNSL .profile for your location
Adjusting the domino_global_env file
Finishing set up for user IDs that will run the domoe program
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
DOMINK
DOMINM
DOMINS
-
Issues commands to the Domino servers
Stops the Domino servers
Enables and disables the monitor
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
9
z/OS Console Support for Lotus Domino
Chapter 3 - Installing the z/OS Console Support for Domino
Record length 80
Block size 3120
You can specify any permitted PDS name. DOMINO.JCL.CNTL is used in the following instructions.
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.
10
z/OS Console Support for Lotus Domino
Chapter 3 - Installing the z/OS Console Support for Domino
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.
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) REFRESH
RLIST 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:
DOMINC
DOMINK
DOMINM
DOMINS
11
z/OS Console Support for Lotus Domino
Chapter 3 - Installing the z/OS Console Support for Domino
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
DC CL24'DOMINK
DC CL24'DOMINM
DC CL24'DOMINS
DOMCNSL
DOMCNSL
DOMCNSL
DOMCNSL
NOTES'
NOTES'
NOTES'
NOTES'
task
name
(8)
task
userid
(8)
task
group
(8)
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) REFRESH
RLIST 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.
12
z/OS Console Support for Lotus Domino
Chapter 3 - Installing the z/OS Console Support for Domino
To set up the BPX.SERVER and the SURROGAT class for user IDs using the domoe command, do one
of the following:
l
Update and use the DOMSAF JCL.
l
Execute the REXX EXEC sample provided in /usr/lpp/lotus/bin/tools/domoe_setup. If you use it,
make sure that 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.
l
Or use the following instructions:
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) REFRESH
SETROPTS CLASSACT(SURROGAT)
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.
l
For each Notes Administrator domoe user, permit their user ID to the BPX.SERVER Facility
Class. You will need 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) REFRESH
RLIST FACILITY BPX.SERVER AUTHUSER
l
For each server to which a Notes Administrator sends commands through domoe, you need
to PERMIT that user 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) REFRESH
SETROPTS CLASSACT(SURROGAT)
13
z/OS Console Support for Lotus Domino
Chapter 3 - Installing the z/OS Console Support for Domino
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) REFRESH
RLIST 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) REFRESH
PERMIT BPX.JOBNAME CLASS(FACILITY) ACCESS(READ) ID(server_id)
SETROPTS RACLIST(FACILITY) REFRESH
RLIST FACILITY BPX.JOBNAME ALL
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) REFRESH
PERMIT 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) REFRESH
RLIST 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.
14
z/OS Console Support for Lotus Domino
Chapter 3 - Installing the z/OS Console Support for Domino
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:
l
Ensure that you are running on a superuser id (UID=0). The script must be run from a UID=0.
l
Ensure the user ID from which you are running the install script has read access to
BPX.FILEATTR.PROGCTL and BPX.FILEATTR.APF facility classes.
l
Identify the program directory name for the code version to be set up. Versions are differentiated by
their installed 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.
l
Decide which script options you need to use based on your installation
l
l
You have a new Domino 6 for z/OS installation or are replacing an existing installation with
Domino 6 for z/OS. Identify the program directory. If not /usr/lpp/lotus, use the domcon.setup -p
option to specify the target program directory.
l
You have installed Domino 6 for z/OS in addition to an existing installation. You will continue to
run one or 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 previous 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.
l
Review the output from the setup script. Verify that all Domino servers were identified by their user ID
and the 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.
15
z/OS Console Support for Lotus Domino
l
Chapter 3 - Installing the z/OS Console Support for Domino
If a domino_global_env file is present in the home directory of your Domino Console ID before running
the setup 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.
l
Change directory (cd) to the home directory of your Domino Console ID.
l
Edit your .profile and do the following.
l
Add a line containing
domino_global_env
Make sure this line has a preceding dot and space, as shown.
l
l
Also add export at the end of the .profile. This causes all environment variables to be echoed
and thus appear in the .sto file when a DOMIN* proc is invoked.
l
Review your existing .profile for any functions that may be detrimental to automated operations,
such as a prompt for user input during profile execution. You need to remove these or Domino
Console will not operate properly.
l
Ensure that the current directory (.) and the Domino Console ID home directory are contained in
your path. 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.
16
z/OS Console Support for Lotus Domino
Chapter 3 - Installing the z/OS Console Support for Domino
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.
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:
l
Edit the domino_global_env file in the home directory of the Domino Console ID.
l
Check that there is a server section for each server that you want the Domino Console to be able to
control. Search 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.
17
z/OS Console Support for Lotus Domino
Chapter 3 - Installing the z/OS Console Support for Domino
l
Check for multiple server sections for any given server by searching for the notesdata directory name
and/or user ID 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.
l
If there are servers included that you DO NOT want accessed by Domino Console, you can comment
out the lines for 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.
l
Note the alias name assigned (SRVxx). As created, this is the name you would use for the SRVID
parameter (to designate 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).
l
You can use the alias name as created or you can change it to something more meaningful for your
location, staying 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" .
l
If the section for a server is missing, make a copy of the sample server section at the bottom of the
file, uncomment 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.
l
When you are satisfied that the servers you want available for control by the Domino Console are
represented, save the file.
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.
l
Edit the domino_global_env file in the home directory of the Domino Console ID.
l
Find the common section, which is at the top in the newly created file. Review the settings for the
following variables.
l
The LotusDir, PATH, LIBPATH and CLASSPATH variables are common variables that are version
dependent. For Domino 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.
l
l
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.
l
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. The 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 .
18
z/OS Console Support for Lotus Domino
Chapter 3 - Installing the z/OS Console Support for Domino
l
dsrvid - This variable contains the alias name of the default server. The server specified here
becomes the target server 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.
l
domcon_pws - This specifies the name of a server password data set. When enabled, this provides a
password to a 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).
l
domcon_pbits - Domino Console runs each server in the background with redirected input and
output to files. These 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).
l
domcon_srv_startup - This variable defines the string that Domino Console looks for to consider the
server startup 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.
l
domcon_debug - This variable should be commented out (# at start of line) or set to 0 for normal
operation. When 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.
l
domconsl_debug - This variable should be commented out (# at start of line) or set to 0 for normal
operation. When 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.
l
When you are satisfied that the settings are correct for your location, save the file.
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.
l
Edit the domino_global_env file in the home directory of the Domino Console ID.
l
Examine all of the server specific values (below) in each server section one section at a time. Check
that the values set in each section are appropriate for the server and your operation.
l
SRVnn_VERS_xxxx - For Domino 6 for z/OS, version sensitive environment variables that were
previously common to 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
19
z/OS Console Support for Lotus Domino
Chapter 3 - Installing the z/OS Console Support for Domino
Variables that are sensitive to version include the program directory location in LotusDir as well as
PATH, LIBPATH and CLASSPATH.
l
SRVnn_VERS_LotusDir - This variable is set to the Domino program directory for this version by
the setup script and should not be changed.
l
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.
l
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.
l
SRVnn_NOTESDATAD - This variable specifies the name of the notesdata directory associated with
this server.
l
SRVnn_safid - This variable specifies the SAF ID or user ID used for this server. This is the owner
user ID of the server's notesdata directory.
l
SRVnn_saf - Set this to 1 if this server requires a password on startup. This indicates that a server
password is to be 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.
l
SRVnn_start_srv_sleep - On a normal server start, specifies how long (seconds) the monitor is to
look for the server started message before shutting down. The monitor becomes inactive when either
the server started message is found or this time expires.
l
SRVnn_kill_srv_sleep - On a server stop (except type=Q), specifies how long (seconds) to look for
the server shutdown 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.
l
SRVnn_kill_prc_sleep - During resource cleanup, specifies how long (in seconds) to wait after
issuing SIGTERM to processes 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.
l
SRVnn_VARy_thisvar_1='some value here'. You can specify any number of server unique
environment variables that 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.
l
N - New. This is a new variable to be created and will contain the value specified. If the variable
already exists, 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.
l
F - Front. The indicated value is appended to the front of the value of the environment variable
indicated. The 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.
l
B - Back. The indicated value is appended to the end of the value of the environment variable
indicated. The variable 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.
20
z/OS Console Support for Lotus Domino
Chapter 3 - Installing the z/OS Console Support for Domino
l
SRVnn_VARN__CEE_DMPTARG='dump directory name' - Use this variable if you want
CEEDUMPs for this server to 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.
l
SRVnn_VARN_LANG='LLLLL.PPPPPPPP'. Use this variable to indicate the locale that the server
will operate in. This 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.
l
SRVnn_domconsl_debug - This variable provides the capability to use the domconsl_debug function
on a specific server 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.
l
When you are satisfied that the settings are correct for this server, repeat the above instructions for
each server instance in the domino_global_env file.
l
When you are satisfied that all of the settings are correct for your location, save the file.
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.
l
Authorize the user ID for system functions via RACF as described in Step 4 above.
l
Provide access to the domoe executable. The setup script provides a link from the /bin directory to the
domoe executable 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.
21
z/OS Console Support for Lotus Domino
Chapter 3 - Installing the z/OS Console Support for Domino
l
Provide read access for the ID to the domino_global_env file in the Domino Console home directory
(usually /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.
l
Set appropriate environment variables for domoe execution. Each user ID of domoe must set the
following environment variables, typically in the .profile they run with:
l
domoe_env - (required) Set to the Domino Console ID's home directory.
l
domoe_srvid - (required) Set to the alias name of the server to be accessed.
l
domoe_debug - (optional) When set to 1 or 2, provides additional information on standard out
regarding internal program operation. When omitted or set to 0, provides only normal program
output on standard out.
l
domoe_time - (optional) Indicates the time (seconds) to wait for server output. After this time,
control returns 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
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.
22
z/OS Console Support for Lotus Domino
Chapter 4 - Using the Console Support from a z/OS Operator's Cons
Chapter 4 - Using the Console Support from a z/OS
Operator's Console
From a z/OS Operator's Console
z/OS Console Support for Domino
Enabling and Disabling the Monitor
To 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 affected.
l
l
The server must be running in order to enable or disable the monitor.
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
23
z/OS Console Support for Lotus Domino
Chapter 4 - Using the Console Support from a z/OS Operator's Cons
z/OS Console Support for Domino
Filtering Messages Sent to the Console
The 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 session
Closed session
replication
Cluster
Databases accessed:
Maps Extractor
Administration 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, 62
19990729.15:00:01,New order, 4, 6, 1, 2, 3, 5, 7
19990729.15:10:01,Hits, 35, 21, 4, 11, 51, 0, 5, 21
19990729.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).
24
z/OS Console Support for Lotus Domino
Chapter 4 - Using the Console Support from a z/OS Operator's Cons
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 Filter
3 Opened session
4 Closed session
5 replication
1 Cluster
6 Databases accessed:
2 Maps Extractor
7 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.
z/OS Console Support for Domino
Passwords
The 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.
25
z/OS Console Support for Lotus Domino
Chapter 4 - Using the Console Support from a z/OS Operator's Cons
z/OS Console Support for Domino
Sending Commands to Domino Servers
Use the following to send a command to the Domino server from a z/OS operator’s console.
Sending a Command to the Domino Server
To 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.
l
l
If special characters (such as, ") are part of the command text, precede them with an escape
character (such as, \).
For example, S DOMINC,CMD='broadcast \"msgtext\" \"userid\"'
l
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.
l
The command is still submitted to the server for processing.
l
The server command submitted is still audited in the system log.
l
The server must be running in order to submit a command.
l
The DOMINC proc basically provides input data to the server's console. Normal usage is for
command input as described 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'
26
z/OS Console Support for Lotus Domino
Chapter 4 - Using the Console Support from a z/OS Operator's Cons
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.
z/OS Console Support for Domino
Starting Domino Servers
Use the following command from a z/OS operator's console and SDSF to start the Domino server.
Starting the Domino Server
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 long monitoring will continue - indefinitely (TYPE='K') or just until the server has
started (TYPE='N').
l
l
The monitor is the console support function that causes the Domino server output to be forwarded to
the z/OS console and to appear in the system log.
l
The value in the xxxx_start_srv_sleep enviroment variable in the domino_global_env file determines
the timeout 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.
27
z/OS Console Support for Lotus Domino
Chapter 4 - Using the Console Support from a z/OS Operator's Cons
l
Server start processing looks for the server output string "Database Server started" to indicate that the
server is started. Optionally, the domcon_srv_startup environment variable in the domino_global_env
file can be used to specify an alternate string.
l
If the server started string is not found before the timeout period expires, an error is sent to the
console and the monitor terminates. The server should be verified since the expected string was not
returned.
l
The server must have a clean environment when started in order to operate successfully. Attempting
to start a 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'
z/OS Console Support for Domino
Stopping Domino Servers
Use the following command from a z/OS operator’s console or SDSF to stop the Domino server.
Stopping the Domino Server
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:
28
z/OS Console Support for Lotus Domino
Chapter 4 - Using the Console Support from a z/OS Operator's Cons
l
All forms of DOMINK cause the monitor processing to be stopped.
l
Server resource cleanup consists of purging any remaining server processes with sigterm/sigkill and
removing ipcs memory and semaphore resources belonging to the server using ipcrm. This affects
only resources that belong to the servers saf ID.
l
The value in the xxxx_kill_srv_sleep enviroment variable in the domino_global_env file determines the
timeout period (in seconds) that the stop processing waits for the server to stop before proceeding. "
xxxx" is the server's alias name.
l
Server stop processing looks for the server output string "Server shutdown complete" to indicate that
the server is stopped. 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'
29
z/OS Console Support for Lotus Domino
Chapter 4 - Using the Console Support from a z/OS Operator's Cons
From UNIX Systems Services
z/OS Console Support for Domino
Using domoe to Send Commands to the Server from USS
Overview
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
30
z/OS Console Support for Lotus Domino
Chapter 5 - Problem Determination
Chapter 5 - Problem Determination
What to Look For
z/OS Console Support for Domino
What to Look For
Messages on the z/OS Console
Domino 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 domoe
domoe 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 Console
To 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.
l
l
l
l
extattr +ap program_library/notes/latest/os390/domcon
extattr +ap program_library/notes/latest/os390/domconfe
extattr +p program_library/notes/latest/os390/domconsl
extattr +p program_library/notes/latest/os390/domoe
The UNIX services ID you are using must be permitted to BPX.FILEATTR.PROGCTL and
BPX.FILEATTR.APF.
31
z/OS Console Support for Lotus Domino
Chapter 5 - Problem Determination
DOMIN* STDOUT and STDERR Files
These 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).
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.
32
z/OS Console Support for Lotus Domino
Chapter 5 - Problem Determination
/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...
**
*************************************************************
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
/b
in:/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"
33
z/OS Console Support for Lotus Domino
Chapter 5 - Problem Determination
*****************************************************
*
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/Print
srv/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
*****************************************************
.
.
.
Resolving Domino Console Program Control Problems
All 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
34
z/OS Console Support for Lotus Domino
Chapter 5 - Problem Determination
CONTROLLED.
BPXP014I ENVIRONMENT MUST BE CONTROLLED FOR DAEMON (BPX.DAEMON)
PROCESSING.
+SRV10 DOM99609E Error 032 SETUID to 95194 failed. RC=157, RSN=0b8802af
IEF404I 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.
l
Check the program controlled flag in the extended file attributes for the Domino Console executables.
These are normally 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.
l
Ensure that the domino_global_env file contains an "unset _BPX_SHAREAS". In order for the setuid()
function to work, shared address space operation must be disabled by unsetting _BPX_SHAREAS.
l
Check that the MOUNT FILESYSTEM parameter for the product HFS in the BPXPRM
SYS1.PARMLIB member is not set to NOSETUID. The NOSETUID option causes the setuid to fail.
l
Check that the system datasets are defined as program controlled. These include SYS1.LINKLIB,
SYS1.CSSLIB, CEE.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.
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
35
z/OS Console Support for Lotus Domino
Chapter 5 - Problem Determination
In the SYSLOG...
BPXP015I HFS PROGRAM /bin/domoe IS NOT MARKED PROGRAM CONTROLLED
BPXP014I 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
z/OS Console Support for Domino
Messages
Domino z/OS Console Messages and Codes
z/OS Console Messages
The 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
DOM99602I
DOM99603I
DOM99604I
DOM99605I
DOM99606I
Domino Server command being entered from the z/OS Console
A command is being submitted to the Domino server via the DOMINC proc.
<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.
Domino z/OS Console Monitor started
Console monitor execution has begun. Domino Server messages will be forwarded to
the z/OS operator's console.
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.
Monitor Shutdown - Found Server Started
The 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.
Domino shutdown now complete
Processing to stop the Domino Server has completed.
36
z/OS Console Support for Lotus Domino
DOM99607I
DOM99608I
DOM99609E
DOM99611I
DOM99614I
DOM99617I
DOM99619I
Chapter 5 - Problem Determination
Domino Server command being issued by: %1
A command for the server has been entered by a DOMOE user whose logon ID is %1.
Entering console command %1
A start or stop command %1 was submitted to the system to control the starting or
stopping of Websphere.
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.
Issuing SIGTERM to process --> %1
Domino 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.
Issuing SIGKILL to process --> %1
Domino 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.
Clean up in process for Domino shared memory
Domino 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.
Clean up in process for Domino semaphores
Domino Console has found Domino semaphores remaining allocated after the server
has stopped. Cleanup is in process to remove these resources with ipcrm -s.
Error Codes
Domino 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 found
The 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 found
The 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 specified
The 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 invalid
The 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.
37
z/OS Console Support for Lotus Domino
Chapter 5 - Problem Determination
007 Domino Console started from a non-superuser UID
The 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 UID
The 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.
009 Value passed for FORCE is not valid
The 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 kill
The 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 getrlimit
012> 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 2147483647
Domino 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 getrlimit
014 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 getrlimit
015 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 2147483647
Domino 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.
38
z/OS Console Support for Lotus Domino
Chapter 5 - Problem Determination
017 Unable to get address space limits with getrlimit
017 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 monitor
The 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 valid
After 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 found
The 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 ->%1
031 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.
032 SETUID to %1 failed. RC=%2, RSN=%3
The 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 exist
The 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 ->%1
The 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 ->%1
036 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 ->%1
037 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.
39
z/OS Console Support for Lotus Domino
Chapter 5 - Problem Determination
040 'domcon_pbits' environment variable not found
The 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 valid
The 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 characters
The 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 set
The setenv function call failed while attempting to set the LOGNAME environmental variable
to match the server's user id.
048 'execv' system call failed
048 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 characters
The 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 found
The 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 found
The 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.
061 Couldn't set PATH environment variable to ->%1
061 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 ->%1
063> 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.
40
z/OS Console Support for Lotus Domino
Chapter 5 - Problem Determination
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 found
The 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 found
The 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 file
The server’s log file could not be found. The file name is always notes.log.
093> Could not read from the server's log file
There is no read access to the server's log file notes.log.
094 Could not open server's log file
094> 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 ->%1
121 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.var
The 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 -->%2
The value specified for %1_saf is not valid. The only valid values are 0 or 1.
128 Could not find domcon_pws env.var
The 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.
41
z/OS Console Support for Lotus Domino
Chapter 5 - Problem Determination
129 open error on %1 password file
129 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.
130 error reading data from %1 password file
130 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 ->%1
150 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 %1
162 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.
42
z/OS Console Support for Lotus Domino
Chapter 5 - Problem Determination
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 ->%1
180 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 ->%1
181 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.
182 Failure resetting the notes.input file's perm. bits
182 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 ->%2
The 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 SETENV
The 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 file
While 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/timeout
The 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 task
212 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 task
213 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.
43
z/OS Console Support for Lotus Domino
Chapter 5 - Problem Determination
240 Write failure to notes.input ->%1
240 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 it
The 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 %1
271 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 %1
272 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 %1
The 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 ->%1
274 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.
275 IPCS semaphore resources associated with %1
The 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 ->%1
276> 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 ->%1
300 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 information
A fgets call on the ipcs work file %1 failed.
330 Could not execute command to load ipcs info ->%1
330 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.
44
z/OS Console Support for Lotus Domino
Chapter 5 - Problem Determination
The following messages are issued from the Monitor (DOMCONSL) module.
501 Invalid number of parms. passed to Monitor
The invalid number of parameters was passed to the Monitor. The valid number of
parameters is 4.
502 Invalid first parm passed to Monitor
The 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, ndata
The 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 enabled
More 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 ->%2
507 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.
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.
45
z/OS Console Support for Lotus Domino
Chapter 5 - Problem Determination
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 found
The 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 found
The 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 >%1
402 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 found
The 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 file
You 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_env
While 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.
46
z/OS Console Support for Lotus Domino
Chapter 5 - Problem Determination
411 LOGNAME env. var. could not be found
The current user’s LOGNAME environment variable could not be found.
412 pthread_create failure
412 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 failure
413 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 assumed
The 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 assumed
The 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 running
No 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 exist
The 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 ->%1
The 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 ->%1
476 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 ->%1
477 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 file
The server’s log file could not be found. The file name is always notes.log.
483 Could not read from the server's log file
There is no read access to the server’s log file notes.log.
47
z/OS Console Support for Lotus Domino
Chapter 5 - Problem Determination
484 Could not open server's log file
484> 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 file
While 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.
48
z/OS Console Support for Lotus Domino
Chapter 6 - Reader Comments
Chapter 6 - Reader Comments
Reader Comments
z/OS Console Support for Domino
Reader Comments
Reader Comment Form
Domino 6 or z/OS
z/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 Corporation
Dept. 55JA, Mail Station P384
2455 South Road
Poughkeepsie, NY 12601-5400
USA
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:
49