AS/400 Advanced Series IBM

AnyMail/400 Mail Server

Framework Support
Version 4

SC41-5411-00
AS/400 Advanced Series IBM
AnyMail/400 Mail Server
Framework Support
Version 4

SC41-5411-00
 Take Note!

Before using this information and the product it supports, be sure to read the general information under “Notices” on page v.

First Edition (August 1997)

This edition applies to the licensed program IBM Operating System/400 (Program 5769-SS1), Version 4 Release 1 Modification 0, and to all
subsequent releases and modifications until otherwise indicated in new editions.

Make sure that you are using the proper edition for the level of the product.

Order publications through your IBM representative or the IBM branch serving your locality. If you live in the United States, Puerto Rico, or
Guam, you can order publications through the IBM Software Manufacturing Solutions at 800+879-2755. Publications are not stocked at the
address given below.

IBM welcomes your comments. A form for readers’ comments may be provided at the back of this publication. You can also mail your
comments to the following address:

IBM Corporation
Attention Department 542
IDCLERK
3605 Highway 52 N
Rochester, MN 55901-7829 USA

or you can fax your comments to:

United States and Canada: 800+937-3430

Other countries: (+1)+507+253-5192

If you have access to Internet, you can send your comments electronically to [email protected]; IBMMAIL, to
IBMMAIL(USIB56RZ).

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

 Copyright International Business Machines Corporation 1997. All rights reserved.

Note to U.S. Government Users — Documentation related to restricted rights — Use, duplication or disclosure is subject to restrictions set forth
in GSA ADP Schedule Contract with IBM Corp.
Contents
Notices . . . . . . . . . . . . . . . . . . . . . . . . . . v Chapter 5. Mail Server Framework Message
Programming Interface Information . . . . . . . . . . . . v Concepts . . . . . . . . . . . . . . . . . . . . . . . 5-1
Trademarks and Service Marks . . . . . . . . . . . . . v MSF Message Lists . . . . . . . . . . . . . . . . . . . 5-2
Originator List . . . . . . . . . . . . . . . . . . . . 5-2
About AnyMail/400 Mail Server Framework Support Original Recipient List . . . . . . . . . . . . . . . . 5-2
(SC41-5411) . . . . . . . . . . . . . . . . . . . . . . vii Recipient List . . . . . . . . . . . . . . . . . . . . 5-2
Who Should Use This Book . . . . . . . . . . . . . . . vii Envelope List . . . . . . . . . . . . . . . . . . . . 5-3
Benefits of Using the Mail Server Framework Support . . vii Attachment Reference List . . . . . . . . . . . . . 5-3
Prerequisite and Related Information . . . . . . . . . . . vii Other Lists . . . . . . . . . . . . . . . . . . . . . . 5-3
Information Available on the World Wide Web . . . . . . vii Report-On List . . . . . . . . . . . . . . . . . . 5-3
Report-To List . . . . . . . . . . . . . . . . . . 5-3
Chapter 1. AnyMail/400 Mail Server Framework - Message Identifier . . . . . . . . . . . . . . . . . . 5-3
Introduction . . . . . . . . . . . . . . . . . . . . . 1-1 MSF Data Types . . . . . . . . . . . . . . . . . . . . 5-4
Rules for MSF Data Type Definitions . . . . . . . . 5-4
Chapter 2. Operations Considerations . . . . . . . 2-1 How the MSF Data Types Are Used to Call Exit Point
Starting and Stopping the Mail Server Framework . . . 2-1 Programs . . . . . . . . . . . . . . . . . . . . . . . 5-4
The Start Mail Server Framework (STRMSF) How the MSF Message Changes . . . . . . . . . . . 5-4
Command . . . . . . . . . . . . . . . . . . . . . 2-1 How the MSF Message Flows Through the Framework 5-5
The End Mail Server Framework (ENDMSF)
Command . . . . . . . . . . . . . . . . . . . . . 2-1 Appendix A. Mail Server Framework APIs . . . . . A-1
MSF QSYSWRK Jobs . . . . . . . . . . . . . . . . . 2-2 MSF Configuration APIs . . . . . . . . . . . . . . . . A-1
Managing MSF Jobs . . . . . . . . . . . . . . . . . . 2-2 Add Mail Server Framework Configuration
Description Considerations . . . . . . . . . . . . . . . 2-3 (QzmfAddMailCfg) API . . . . . . . . . . . . . . . A-1
Descriptions Reset During OS/400 Installation . . . 2-3 List Mail Server Framework Configuration
Changing Subsystem and Job Descriptions . . . . 2-3 (QzmfLstMailCfg) API . . . . . . . . . . . . . . . A-1
Error Recovery and Error Messages . . . . . . . . . . 2-3 Remove Mail Server Framework Configuration
QMSF Job Error Recovery . . . . . . . . . . . . . 2-3 (QzmfRmvMailCfg) API . . . . . . . . . . . . . . A-1
STRMSF and ENDMSF Command Error Recovery 2-4 MSF Message APIs . . . . . . . . . . . . . . . . . . A-1
Create Mail Message (QzmfCrtMailMsg) API . . . . A-1
Chapter 3. Configuration Considerations . . . . . . 3-1 Change Mail Message (QzmfChgMailMsg) API . . . A-2
Exit Point Program Registration . . . . . . . . . . . . 3-1 Retrieve Mail Message (QzmfRtvMailMsg) API . . . A-2
MSF Configuration APIs . . . . . . . . . . . . . . . . 3-2 Other Optional APIs . . . . . . . . . . . . . . . . . A-2
Query Mail Message Identifier
Chapter 4. Mail Server Framework Structure . . . . 4-1 (QzmfQryMailMsgId) API . . . . . . . . . . . . A-2
Exit Points . . . . . . . . . . . . . . . . . . . . . . . 4-1 Reserve Mail Message Identifier
Exit Point Programs . . . . . . . . . . . . . . . . . . 4-1 (QzmfRsvMailMsgId) API . . . . . . . . . . . . A-2
Snap-Ins . . . . . . . . . . . . . . . . . . . . . . . . 4-1 Complete Creation Sequence
Exit Points Provided on the Mail Server Framework . . 4-2 (QzmfCrtCmpMailMsg) API . . . . . . . . . . . A-2
MSF Exit Point Groups . . . . . . . . . . . . . . . . . 4-3 Remove Reserved Mail Message Identifier
Exit Point Programs in the Addressing Group . . . . . 4-4 (QzmfRmvRsvMailMsgId) API . . . . . . . . . A-2
List Expansion Exit Point . . . . . . . . . . . . . . 4-4 Exit Points . . . . . . . . . . . . . . . . . . . . . . . A-2
Address Resolution Exit Point . . . . . . . . . . . . 4-4 Snap-In Call Exit Point Program . . . . . . . . . . A-2
Exit Point Programs in the Pre-Delivery Processing Track Mail Message Changes Exit Point Program . A-2
Group . . . . . . . . . . . . . . . . . . . . . . . . . 4-6 Validate Data Field Exit Point Program . . . . . . . A-2
Envelope Processing Exit Point . . . . . . . . . . . 4-6
Attachment Conversion Exit Point . . . . . . . . . . 4-6 Appendix B. MSF Journal Logging and Journal
Security and Authority Exit Point . . . . . . . . . . 4-7 Formats . . . . . . . . . . . . . . . . . . . . . . . . B-1
Exit Point Programs in the Delivery Group . . . . . . . 4-8 QZMF Journal . . . . . . . . . . . . . . . . . . . . . B-1
Local Delivery Exit Point . . . . . . . . . . . . . . 4-8 Displaying the QZMF Journal . . . . . . . . . . . . . B-1
Message Forwarding Exit Point . . . . . . . . . . . 4-8 Displaying the Journal Entries . . . . . . . . . . . . B-2
Exit Point Programs in the Management Group . . . . 4-9 Entry Type LG . . . . . . . . . . . . . . . . . . B-3
Non-Delivery Exit Point . . . . . . . . . . . . . . . 4-9 Entry Type ER . . . . . . . . . . . . . . . . . . B-3
Attachment Management Exit Point . . . . . . . . . 4-9 Entry Type SY . . . . . . . . . . . . . . . . . . B-3
Accounting Exit Point . . . . . . . . . . . . . . . . 4-9 Entry Type CF . . . . . . . . . . . . . . . . . . B-4
Format for MSF Message Logging (LG) . . . . . . . . B-5
Format for MSF Message Errors (ER) . . . . . . . . . B-7

 Copyright IBM Corp. 1997 iii

Format for MSF System Level Events Table (SY) . . . B-8 Local Delivery . . . . . . . . . . . . . . . . . . . . D-3
Format for MSF Configuration Changes (CF) . . . . . B-9 Message Forwarding . . . . . . . . . . . . . . . . D-3
Non-Delivery . . . . . . . . . . . . . . . . . . . . . D-3
Appendix C. Preregistered Exit Point Programs . . C-1 Attachment Management . . . . . . . . . . . . . . D-4
Exit Program QZMFSNPA . . . . . . . . . . . . . . . C-1 Accounting . . . . . . . . . . . . . . . . . . . . . . D-4

Appendix D. How Mail Server Framework Works Bibliography . . . . . . . . . . . . . . . . . . . . . . H-1

with SNADS, Object Distribution, and OfficeVision D-1
List Expansion . . . . . . . . . . . . . . . . . . . . D-3 Index . . . . . . . . . . . . . . . . . . . . . . . . . . X-1
Address Resolution . . . . . . . . . . . . . . . . . D-3

Figures
1-1. MSF Support when Sending Electronic Mail . 1-3 5-2. MSF Message Lists . . . . . . . . . . . . . 5-2
1-2. MSF Support when Receiving Electronic Mail 1-4 5-3. MSF Data Types Used to Determine Which
2-1. QMSF Jobs in QSYSWRK Subsystem . . . 2-2 Exit Point Program to Call . . . . . . . . . . 5-5
2-2. Work with Subsystems Display . . . . . . . 2-3 5-4. Exit Point Programs Can Change Information
2-3. Work with Subsystem Jobs Display . . . . . 2-3 in an MSF Message . . . . . . . . . . . . . 5-5
3-1. Work with Registration Information - First 5-5. How an MSF Message Flows Through the
Display . . . . . . . . . . . . . . . . . . . . 3-1 Framework . . . . . . . . . . . . . . . . . . 5-6
3-2. Work with Registration Information - Second B-1. Display Journal - First Display . . . . . . . . B-1
Display . . . . . . . . . . . . . . . . . . . . 3-1 B-2. Display Journal - Second Display . . . . . . B-1
3-3. Work with Registration Information Display . 3-1 B-3. Display Journal - Third Display . . . . . . . B-2
3-4. Work with Exit Programs Display . . . . . . 3-2 B-4. Display Journal Entries Display . . . . . . . B-2
3-5. Display Exit Program Display . . . . . . . . 3-2 B-5. Display Journal Entry - Type LG . . . . . . . B-3
3-6. Example of an Exit Program in the Mail Server B-6. Display Journal Entry - Type ER . . . . . . . B-3
Framework . . . . . . . . . . . . . . . . . . 3-2 B-7. Display Journal Entry - Type SY . . . . . . . B-3
4-1. MSF Exit Point and Exit Point Program B-8. Display Journal Entry - Type CF . . . . . . . B-4
Overview . . . . . . . . . . . . . . . . . . . 4-2 B-9. Fields of the Journal Entries - Example . . . B-6
4-2. Using Multiple MSF Exit Point Programs . . 4-2 B-10. Function Identifier A - Example . . . . . . B-11
4-3. MSF Exit Point Groups . . . . . . . . . . . 4-3 B-11. Function Identifier B - Example . . . . . . B-11
4-4. Exit Point Programs in the Addressing Group 4-4 B-12. Function Identifier D - Example . . . . . . B-11
4-5. Exit Point Programs in the Pre-Delivery B-13. Function Identifier F - Example . . . . . . B-11
Processing Group . . . . . . . . . . . . . . 4-6 C-1. Exit Point Programs Shipped with MSF . . . C-1
4-6. Exit Point Programs in the Delivery Group . 4-8 C-2. Address Resolution Exit Point Programs . . C-1
4-7. Exit Point Program in the Management Group 4-9 C-3. Example of Preferred Address Resolution . . C-2
5-1. MSF Message Concept Overview . . . . . . 5-1 D-1. SNADS Overview . . . . . . . . . . . . . . D-2

Tables
4-1. MSF Exit Points . . . . . . . . . . . . . . . 4-1 B-3. Type SY Journal Entries for the MSF System
B-1. Type LG Journal Entries for MSF Messages B-5 Level Events Table Changes . . . . . . . . B-8
B-2. Type ER Journal Entries for MSF Message B-4. Type CF Journal Entries for MSF
Errors . . . . . . . . . . . . . . . . . . . . . B-7 Configuration Changes . . . . . . . . . . . . B-9

iv AnyMail/400 Mail Server Framework Support V4

Notices
References in this publication to IBM products, programs, or services do not imply that IBM intends to make these available in
all countries in which IBM operates. Any reference to an IBM product, program, or service is not intended to state or imply that
only that IBM product, program, or service may be used. Subject to IBM's valid intellectual property or other legally protectable
rights, any functionally equivalent product, program, or service may be used instead of the IBM product, program, or service.
The evaluation and verification of operation in conjunction with other products, except those expressly designated by IBM, are
the responsibility of the user.

IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this docu-
ment does not give you any license to these patents. You can send license inquiries, in writing, to the IBM Director of
Licensing, IBM Corporation, 500 Columbus Avenue, Thornwood, NY 10594, U.S.A.

Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information
between independently created programs and other programs (including this one) and (ii) the mutual use of the information
which has been exchanged, should contact the software interoperability coordinator. Such information may be available,
subject to appropriate terms and conditions, including in some cases, payment of a fee.

Address your questions to:

IBM Corporation
Software Interoperability Coordinator
3605 Highway 52 N
Rochester, MN 55901-7829 USA

This publication could contain technical inaccuracies or typographical errors.

This publication may refer to products that are announced but not currently available in your country. This publication may also
refer to products that have not been announced in your country. IBM makes no commitment to make available any unan-
nounced products referred to herein. The final decision to announce any product is based on IBM's business and technical
judgment.

This publication contains examples of data and reports used in daily business operations. To illustrate them as completely as
possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious
and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental.

This publication contains small programs that are furnished by IBM as simple examples to provide an illustration. These exam-
ples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability,
or function of these programs. All programs contained herein are provided to you "AS IS". THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE EXPRESSLY DISCLAIMED.

Programming Interface Information

This book is intended to help the system operator and system administrator use the mail server framework on the IBM AS/400
system. It also provides concepts for the business partner or system programmer. This book documents General-Use Pro-
gramming Interface and Associated Guidance Information provided by the Operating System/400 licensed program.

General-Use Programming Interfaces allow the customer to write programs that obtain the services of the mail server frame-
work.

Trademarks and Service Marks

The following terms are trademarks of the IBM Corporation in the United States or other countries or both:

Application System/400 Operating System/400

AS/400 OS/400
IBM 400
OfficeVision

 Copyright IBM Corp. 1997 v

Microsoft, Windows, and the Windows 95 logo are trademarks or registered trademarks of Microsoft Corporation.

PC Direct is a trademark of Ziff Communications Company and is used by IBM Corporation under license.

UNIX is a registered trademark in the United States and other countries licensed exclusively through X/Open Company Limited.

C-bus is a trademark of Corollary, Inc.

Java and HotJava are trademarks of Sun Microsystems, Inc.

Other company, product, and service names, which may be denoted by a double asterisk (**), may be trademarks or service
marks of others.

vi AnyMail/400 Mail Server Framework Support V4

About AnyMail/400 Mail Server Framework Support (SC41-5411)
This book contains information about the mail server frame- Chapter 1, AnyMail/400 Mail Server Framework - Intro-
work (MSF) on the AS/400 system. The book is organized duction
as follows: Chapter 2, Operations Considerations
Chapter 3, Configuration Considerations
Ÿ Introduction to the mail server framework (Chapter 1,
Appendix B, MSF Journal Logging and Journal Formats
“AnyMail/400 Mail Server Framework - Introduction”).
Appendix C, Preregistered Exit Point Programs
Ÿ Usage considerations for the mail server framework Appendix D, How Mail Server Framework Works with
(Chapter 2, “Operations Considerations”). The control SNADS, Object Distribution, and OfficeVision
language (CL) commands used to start and end the
This book also supplies the business partner or system pro-
framework operation are in this chapter. There is also
grammer with conceptual information about the mail server
information about error messages and error recovery.
framework. Use the following parts of this book to better
Ÿ Configuration considerations for the mail server frame- understand how the mail server framework is used:
work (Chapter 3, “Configuration Considerations”). This
Chapter 1, AnyMail/400 Mail Server Framework - Intro-
chapter explains how to find the registered exit points
duction
and how to register exit programs with an exit point.
Chapter 3, Configuration Considerations
Ÿ Description of the mail server framework structure Chapter 4, Mail Server Framework Structure
(Chapter 4, “Mail Server Framework Structure”). This Chapter 5, Mail Server Framework Message Concepts
includes definitions of exit points and exit point pro- Appendix A, Mail Server Framework APIs
grams.
Ÿ Conceptual information about the mail server framework
messages (Chapter 5, “Mail Server Framework Message Benefits of Using the Mail Server
Concepts”), including MSF message lists and MSF data Framework Support
types.
Ÿ Overview of mail server framework APIs (Appendix A, The mail server framework provides the basis for
“Mail Server Framework APIs”). OfficeVision mail, SNA distribution services (SNADS), and
any future mail offering on the AS/400 system. The QMSF
Ÿ Information about the QZMF journal, journal formats, and mail server framework jobs, running in the QSYSWRK sub-
journal logging (Appendix B, “MSF Journal Logging and system, support the mail server framework.
Journal Formats”).
Ÿ Description of the preregistered exit point programs that Users of the mail server framework can tailor their mail appli-
are shipped with MSF (Appendix C, “Preregistered Exit cations to meet their specific needs. The user applications
Point Programs”). are enabled and managed by the mail server framework.

Ÿ Description of how SNA distribution services (SNADS)

uses the mail server framework to route and distribute
Prerequisite and Related Information
messages (Appendix D, “How Mail Server Framework
Works with SNADS, Object Distribution, and For information about other AS/400 publications (except
OfficeVision”). Advanced 36), see either of the following:
The term operator refers to the system operator as the Ÿ The Publications Reference book, SC41-5003, in the
person responsible for operating the console, responding to AS/400 Softcopy Library.
messages, and diagnosing any system malfunctions Ÿ The AS/400 Information Directory, a unique, multimedia
(problem analysis). interface to a searchable database that contains
descriptions of titles available from IBM or from selected
For a list of publications related to this book, see the “Bibli- other publishers. The AS/400 Information Directory is
ography.” shipped with the OS/400 operating system at no charge.

Who Should Use This Book Information Available on the World Wide
Web
This book supplies the system operator and system adminis-
trator with the information needed to use the mail server More AS/400 information is available on the World Wide
framework on the AS/400 system. The operator's role is to Web. You can access this information from the AS/400
maintain and support mail on the AS/400 system. The oper- home page, which is at the following uniform resource locator
ator may find the following parts of this book most useful (URL) address:
when using the framework:

 Copyright IBM Corp. 1997 vii

http://www.as4ðð.ibm.com Select the Information Desk, and you will be able to access a
variety of AS/400 information topics from that page.

viii AnyMail/400 Mail Server Framework Support V4

Chapter 1. AnyMail/400 Mail Server Framework - Introduction
The AnyMail/400 mail server framework is an open structure system supported message store. The client and the AS/400
for electronic mail distribution that is provided with the application would then read the information from the
OS/400 operating system. AnyMail/400 functions are a set message store.
of mail-related functions that provide open and flexible inter-
faces to support mail on the AS/400. The mail server frame- The MSF message might be created by an application and,
work (MSF) is the distribution framework. The primary as a result of using specific exit point programs, the informa-
function of the mail server framework is to allow the distribu- tion might be sent to other applications on the same system,
tion of electronic mail messages (for example, voice, video, as well as applications on other systems. Also, messages
or text). could be arriving from other systems. This is not shown in
Figure 1-1 on page 1-3 or Figure 1-2 on page 1-4. As a
On the AS/400 system, the mail server framework performs result of using specific exit point programs, that information
the following functions: could be both delivered to the application on that system and
forwarded to another system.
Ÿ Creates and queues MSF messages
Ÿ Distributes MSF message information by calling config- The exit points allow you to install software to affect MSF
ured exit programs message flow through the mail server framework. For each
of the mail server framework exit points provided, functions
An exit point is a specific point in a system function or
of the exit programs follow:
program where control is passed to one or more specified
programs. An exit point passes control to an exit program. List expansion
The exit program can be written by the user or it can be a Allows for expansion of the distribution lists for
program that is already on the system. An application the MSF message. It expands any distribution
program interface (API) is a functional interface supplied by list found in a recipient list. Note that distribution
the operating system that allows an application program lists may contain other distribution lists that can
written in a high-level language to use specific data or func- be expanded further.
tions of the operating system.
Address resolution
Allows for address mapping for each destination
The mail server framework allows programs to be configured
address and adds the correct information to the
and accessed through an API. A snap-in is a registered exit
MSF message recipient information so appro-
point program that is called from a mail server framework exit
priate exit programs can be called at later exit
point. The user-written exit programs provide the mail
points.
message processing required for each MSF message that is
created. Envelope processing
Allows the message envelope to be changed to
The mail server framework (MSF) message contains informa- a format that the mail delivery system accepts.
tion that defines the electronic mail message. The mail
Attachment conversion
server framework does not process the contents of a mail
Allows for changes or additions to MSF message
message. Instead, it determines which exit program is
attachments.
allowed to work with the MSF message and it tracks the flow
of the MSF message through the framework. When an MSF Security and authority
message is sent, the MSF data type is stored and used Allows for verification of user authority to dis-
asynchronously. The framework also provides support for tribute the MSF message information to
electronic mail messages that arrive from other systems. addresses in its recipient list, before the MSF
message is delivered using the local or remote
Figure 1-1 on page 1-3 illustrates client mail enabled appli- delivery exit programs.
cations using the AS/400 system as a server and an AS/400
Local delivery
application, such as OfficeVision. These applications are
Allows for delivery of the MSF message to local
creating MSF messages and the exit point programs config-
recipients.
ured in the framework use the information in the messages
to send the information to applications on other systems. Message forwarding
Allows forwarding of the MSF message informa-
Figure 1-2 on page 1-4 illustrates electronic mail information tion to remote recipients.
arriving from applications on other systems. The support for
the information arriving from specific protocols uses the MSF Non-delivery
by creating MSF messages. The framework then uses exit Allows for reporting of the non-delivery of an
point programs to deliver the message information to a MSF message.

 Copyright IBM Corp. 1997 1-1

Attachment management Accounting
Allows for management of attachments refer- Allows for an audit trail of activity required in the
enced by an MSF message as part of the electronic mail environment.
message distribution.
See Chapter 4, “Mail Server Framework Structure” for more
information about each of the exit points.

1-2 AnyMail/400 Mail Server Framework Support V4

 Client
Client application
uses API to send
message

Client Mail Support

AS/400 application QzmfCrtMailMsg
uses API to send
message Create Mail Message

AS/400 Mail Support

QzmfCrtMailMsg
Create Mail Message

Mail Server Framework

List Expansion
Directory Data

Address Resolution
Directory
Services
Envelope Processing

Attachment Conversion
Transform

Security and Authority

<READ>
Local Delivery

Message Forwarding <WRITE>

Non-Delivery
Message Store
Attachment Management

Accounting

Other
SNADS VM/MVS X.400 SMTP Specific
Bridge Protocols

Exit Point
Exit Point Program RV3W152-7

Figure 1-1. MSF Support when Sending Electronic Mail

Chapter 1. AnyMail/400 Mail Server Framework - Introduction 1-3

 Client
Client application
uses API to read
message

Server Client Mail Support

AS/400 application
uses API to read
message

AS/400 Mail Support

QzmfCrtMailMsg

Create Mail Message

Mail Server Framework

List Expansion
Directory Data

Address Resolution
Directory
Services
Envelope Processing

Attachment Conversion
Transform

Security and Authority

<READ>
Local Delivery

Message Forwarding <WRITE>

Non-Delivery
Message Store
Attachment Management

Accounting

Other
SNADS VM/MVS X.400 SMTP Specific
Bridge Protocols

Exit Point
Exit Point Program RV3W170-3

Figure 1-2. MSF Support when Receiving Electronic Mail

1-4 AnyMail/400 Mail Server Framework Support V4

Chapter 2. Operations Considerations
If you use applications such as OfficeVision/400 or object The valid value range is 1 through 99. If mail traffic is
distribution, make sure that both the SNADS subsystem and high, use a larger value. Performance may be affected
the mail server framework are active. by the amount of mail traffic occurring.
The default for this parameter is 3.

Starting and Stopping the Mail Server Example 1: Starting One Mail Server Framework Job
Framework STRMSF NBRMSFJOB(1)

There are two control language (CL) commands that control This example starts one QMSF job (in the QSYSWRK sub-
the processing of MSF messages: system) in a normal manner, processing any MSF messages
Ÿ Start Mail Server Framework (STRMSF) at the point at which processing was interrupted.
Ÿ End Mail Server Framework (ENDMSF)
Example 2: Restarting Mail Server Framework Jobs
The primary purposes of the STRMSF and ENDMSF com- STRMSF MSGOPT(\RESET)
mands are to start and end the framework, and to reset the
framework when errors occur. This example restarts the MSF jobs, using the default of 3.
The MSF messages, partially handled by previous MSF jobs,
are processed again as if they were just created.
The Start Mail Server Framework
(STRMSF) Command
The End Mail Server Framework (ENDMSF)
The Start Mail Server Framework (STRMSF) command starts Command
the mail server framework jobs in the system work sub-
system (QSYSWRK). For more information about The End Mail Server Framework (ENDMSF) command ends
QSYSWRK, see the Work Management book. There are two the mail server framework jobs in the system work sub-
parameters you can specify on the STRMSF command. system (QSYSWRK). This command stops all MSF
message distribution; however, MSF messages can continue
to be created even when the QMSF jobs are intentionally
MSGOPT (Message Option) ended or have failed. These messages will be processed
This parameter specifies how the mail server framework when the QMSF jobs are restarted by the STRMSF
processes existing MSF messages. command.
*RESUME is the default option, which allows all existing
MSF messages to continue processing from the point There are two parameters you can specify on the ENDMSF
the mail server framework was previously ended. command.

*RESET allows all existing MSF messages to be pro-

cessed as if they were just created. Users may receive OPTION (Option)
duplicate messages when this parameter is used. This parameter specifies whether the mail server frame-
work jobs in QSYSWRK end immediately or in a con-
Note trolled manner.
*CLEAR deletes all existing MSF messages. Use *CNTRLD allows all MSF jobs to end in a controlled
the *CLEAR option only when a software error is manner. This option allows each framework job a
reported with the mail server framework or its asso- chance to process the MSF messages completely before
ciated exit point programs that requires all MSF the job ends. *CNTRLD is the default.
messages to be deleted. Use the option only when
you want to remove all mail message traffic from the *IMMED allows all MSF jobs to end immediately. The
system because of errors. The possibility may exist MSF messages being processed when the jobs end are
that a message was already delivered before an reprocessed when the mail server framework is
error occurred. If this option is used, all messages restarted.
are deleted and cannot be recovered. DELAY (Delay)
This parameter can be used to specify the maximum
NBRMSFJOB (Number of Mail Server Framework Jobs) amount of delay time, in seconds, before the MSF jobs
This parameter specifies the number of mail server are ended.
framework jobs to start in the QSYSWRK subsystem. This parameter is ignored if OPTION(*IMMED) is speci-
Several MSF messages can be processed concurrently. fied.
Valid values range from 1 through 999999 seconds.

 Copyright IBM Corp. 1997 2-1

 The default option for this parameter is 30 seconds, Application Job
which means that a maximum delay time of 30 seconds
AS/400 Mail Support
is allowed before the MSF jobs are ended.

Example 1: Ending the Mail Server Framework in a Con- Create Mail Message
trolled Manner
ENDMSF OPTION(\CNTRLD) DELAY(6ð)

This example ends the MSF jobs in the QSYSWRK sub-

system in a controlled manner. The MSF jobs have 60 MSF
Message
MSF STRMSF
Message
seconds to complete processing any MSF messages cur- MSF
Message

rently being handled. Submits

QMSF
Jobs
Example 2: Ending the Mail Server Framework Imme-
diately
ENDMSF OPTION(\IMMED) QSYSWRK Subsystem

This example ends the MSF jobs in the QSYSWRK sub-

system immediately. The MSF jobs do not complete pro-
QMSF Job
cessing of any MSF messages currently being handled.

QMSF Job
MSF QSYSWRK Jobs
The STRMSF command starts a specified number of jobs in QMSF Job
the QSYSWRK subsystem named QMSF.

These jobs perform the distribution function of the mail server

framework. Note MSF messages can be created in other
RV3W172-2
jobs.
Figure 2-1. QMSF Jobs in QSYSWRK Subsystem

Managing MSF Jobs

There is an autostart entry, QZMFECOX, that is shipped as
part of the QSYSWRK subsystem. Whenever the
QSYSWRK subsystem is started, one QMSF job is started
by the autostart job entry.

If you want to change the number of jobs that are started in

the QSYSWRK subsystem, change the STRMSF command
that is in the request data of the QSYS/QZMFEJBD job
description. Use the Change Job Description (CHGJOBD)
command to make the change.

If you do not want any MSF jobs started when the

QSYSWRK subsystem starts, remove the autostart job entry,
QZMFECOX, from the QSYSWRK subsystem description.
Use the Remove Autostart Job Entry (RMVAJE) command.

For more information about QSYSWRK and work manage-

ment, refer to the Work Management book.

To work with the QMSF jobs, first locate the QSYSWRK sub-
system where they are running. Use the Work with Sub-
system display. Type WRKSBS on the command line and
press the Enter key. Then type 8 in the Opt field next to
QSYSWRK.

2-2 AnyMail/400 Mail Server Framework Support V4

à ð Description Considerations
Work with Subsystems
System: RCHASEEL
Type options, press Enter. Following are tips to consider when you are working with
4=End subsystem 5=Display subsystem description
8=Work with subsystem jobs subsystem descriptions and job descriptions.
Total -----------Subsystem Pools------------
Opt Subsystem Storage (K) 1 2 3 4 5 6 7 8 9 1ð
___
___
BATS
QBATCH
ð
ð
2
2 Descriptions Reset During OS/400
___
___
QCMN
QCTL
ð
ð
2
2 Installation
___ QINTER ð 2 4
___ QSNADS ð 2
___ QSPL ð 2 3 When the OS/400 licensed program is installed, all sub-
_8_ QSYSWRK ð 2
___ QXFPCS ð 2 system descriptions and job descriptions get replaced.
Bottom
Therefore, if either QSYSWRK subsystem description or
Parameters or command QZMFEJBD job description is changed before an installation
===>
F3=Exit F5=Refresh F11=Display system data F12=Cancel of OS/400, the changes will be lost after the installation is
F14=Work with system status
completed. If changes to the descriptions need to be saved,
á ñ the job description and subsystem description objects should
be saved before the installation. These objects can then be
Figure 2-2. Work with Subsystems Display restored after the installation completes. Use the Save
Object (SAVOBJ) and Restore Object (RSTOBJ) commands.
QSYSWRK contains several jobs relating to the OS/400
operating system. You can expect to see at least one QMSF
job running in the QSYSWRK subsystem when it is started. Changing Subsystem and Job
Descriptions
The reason for having more than one QMSF job is
throughput performance. If you have only a very few mail If you change the subsystem description and job description,
users on your system, consider reducing the number of the subsystem may not start or any jobs associated with
QMSF jobs. However, if the mail processing appears to be MSF may fail to run.
very slow, consider starting more QMSF jobs.
No log entries are made to indicate there is an error.
Figure 2-3 shows QSYSWRK with QMSF and other jobs that
typically run there. In this particular example, there are three
QMSF jobs running. Error Recovery and Error Messages
The MSF jobs are named QMSF. To work with a QMSF job,
use option 5. QMSF Job Error Recovery
If MSF messages are not processed: Situations may
occur in which you find that messages are not being pro-
à Work with Subsystem Jobs
ð
RCHASEEL cessed. Error messages or job log messages may indicate
ð1/16/95 15:53:21
Subsystem . . . . . . . . . . : QSYSWRK that the mail server framework stopped the processing of
Type options, press Enter. some messages and is beginning to process new messages
2=Change 3=Hold 4=End 5=Work with 6=Release 7=Display message
8=Work with spooled files 13=Disconnect from the message queue.

Opt Job User Type -----Status----- Function To recover from this situation, check the job logs for the exit
___ QDIRSHDCTL QDOC BATCH ACTIVE \ -DIRSHD
5__ QMSF QMSF BATCH ACTIVE point and the exit program running when MSF stopped pro-
___
___
QMSF
QMSF
QMSF
QMSF
BATCH
BATCH
ACTIVE
ACTIVE
cessing the messages. Use the information to determine
___ QTCPIP QSYS BATCH ACTIVE where and why MSF stopped processing the messages.
___ QTFTPð1ð45 QTCP BATCH ACTIVE CMD-RGZPFM
___ QTFTPð1231 QTCP BATCH ACTIVE CMD-MOVOBJ
___
___
QTFTPð1956
QTFTP1ð2ð9
QTCP
QTCP
BATCH
BATCH
ACTIVE
ACTIVE
CMD-MOVOBJ
CMD-MOVOBJ
If the mail server framework ends: If the MSF job in
___ QTFTP27ðð1 QTCP BATCH ACTIVE CMD-RGZPFM QSYSWRK ends, first try restarting MSF. If that does not
More...
Parameters or command resolve the problem, check for messages in QSYSOPR and
===>
F3=Exit F4=Prompt F5=Refresh F9=Retrieve F11=Display schedule data in the job logs for the QMSF jobs that are running that
F12=Cancel caused MSF to end. The mail server framework is finding
á ñ something it cannot process, so it ends the framework.

A case where this could occur is if someone deleted the exit

Figure 2-3. Work with Subsystem Jobs Display
point program, but did not remove it (unregister the program)
from the exit point. You can use the Work with Registration
Information (WRKREGINF) display to check for this situation.

Chapter 2. Operations Considerations 2-3

If these messages appear in the job log: STRMSF and ENDMSF Command Error
Ÿ CPFAF95 - Job ended Recovery
– Exit programs encountered severe errors causing
When the STRMSF and ENDMSF commands are started:
the job to end.
Sometimes you may get a message indicating that MSF is
– The mail server framework encountered abnormal
already active. If this error occurs, you must end the mail
conditions.
server framework (using the ENDMSF command) before the
– Exit programs encountered situations that stopped
MSF will start again.
the processing of MSF messages and ended the
MSF job. What if the job log contains error message CPFAFA4:
Ÿ CPFAF98 - Message postponed There are two ways to recover from the CPFAFA4 error
message.
One of the exit programs determined that an MSF
message should be postponed until the next STRMSF. Ÿ Use the Remove Mail Server Framework Configuration
(QzmfRmvMailCfg) API.
To recover from these messages, use the Display Job Log
Ÿ Use the Work with Registration display to remove an exit
(DSPJOBLOG) command to determine what the problem is.
program. See Chapter 3, “Configuration Considerations”
Display the message and use the recovery information to
for more information about using this display.
correct the problem. Then restart MSF.
Journal entries in the QZMF journal will help you determine
See the Alerts Support book for a list of the IBM-supplied
when these errors occurred. See Appendix B, “MSF Journal
alertable messages shipped with OS/400.
Logging and Journal Formats” for more information about
journal types and their descriptions.

2-4 AnyMail/400 Mail Server Framework Support V4

Chapter 3. Configuration Considerations
This chapter explains how you can find the registered exit
points and how to register exit programs with an exit point. à Work with Registration Information
ð
Type options, press Enter.
5=Display exit point 8=Work with exit programs

Exit Point Program Registration Exit

Exit
Point
Opt Point Format Registered Text
___ QIBM_QZMFMSF_VLD_TYP MSFFð1ðð \YES MSF Validate Type
An exit point program is registered with one of the following
ten MSF exit points:
QIBM_QZMFMSF_LST_EXP
QIBM_QZMFMSF_ADR_RSL
QIBM_QZMFMSF_ENL_PSS
QIBM-QZMFMSF_ATT_CNV Bottom
QIBM_QZMFMSF_SEC_AUT Command
===>
QIBM_QZMFMSF_LCL_DEL F3=Exit F4=Prompt F9=Retrieve F12=Cancel
QIBM_QZMFMSF_MSF_FWD
QIBM_QZMFMSF_NON_DEL á ñ
QIBM_QZMFMSF_ATT_MGT
Figure 3-2. Work with Registration Information - Second Display
QIBM_QZMFMSF_ACT
The first ten exit points you see here are those described in
To view the exit points, use the WRKREGINF command.
Chapter 4, “Mail Server Framework Structure.”
You probably have a number of exit points registered on your
system, but you can work with only MSF exit points by typing There are two other exit points
WRKREGINF FORMAT(MSFFð1ðð) on the command line. (QIBM_QZMFMSF_TRK_CHG and
QIBM_QZMFMSF_VLD_TYP). These exit points can be
Exit points are shown in alphabetical order as follows:
called by MSF to start a program to track changes made to
an MSF message and to validate information associated with
an MSF message. For more information about how an MSF
à Work with Registration Information
ð message changes, refer to “How the MSF Message
Type options, press Enter. Changes” on page 5-4. This information is useful when
5=Display exit point 8=Work with exit programs testing exit point programs.
Exit
Exit Point
Opt Point Format Registered Text To display information about the specific exit point, use
__
__
QIBM_QZMFMSF_ACT
QIBM_QZMFMSF_ADR_RSL
MSFFð1ðð
MSFFð1ðð
\YES
\YES
MSF Accounting Exit
MSF Address Resolution
option 5. To view and work with programs registered with a
__ QIBM_QZMFMSF_ATT_CNV MSFFð1ðð \YES MSF Attachment Conversion specific exit point, use option 8. The address resolution exit
__ QIBM_QZMFMSF_ATT_MGT MSFFð1ðð \YES MSF Attachment Management
__ QIBM_QZMFMSF_ENL_PSS MSFFð1ðð \YES MSF Envelope Processing point is displayed by typing 8 next to exit point
__ QIBM_QZMFMSF_LCL_DEL MSFFð1ðð \YES MSF Local Delivery
__ QIBM_QZMFMSF_LST_EXP MSFFð1ðð \YES MSF List Expansion QIBM_QZMFMSF_ADR_RSL in the Opt field.
__ QIBM_QZMFMSF_MSG_FWD MSFFð1ðð \YES MSF Message Forwarding
__ QIBM_QZMFMSF_NON_DEL MSFFð1ðð \YES MSF Non Delivery
__ QIBM_QZMFMSF_SEC_AUT MSFFð1ðð \YES MSF Security and Authority
__ QIBM_QZMFMSF_TRK_CHG MSFFð1ðð \YES MSF Track Mail Message Change

Command
More... à Work with Registration Information
ð
===>________________________________________________________________
F3=Exit F4=Prompt F9=Retrieve F12=Cancel Type options, press Enter.
5=Display exit point 8=Work with exit programs
á ñ Exit
Exit Point
Opt Point Format Registered Text
Figure 3-1. Work with Registration Information - First Display ___ QIBM_QZMFMSF_ACT MSFFð1ðð \YES MSF Accounting Exit
_8_ QIBM_QZMFMSF_ADR_RSL MSFFð1ðð \YES MSF Address Resolution
___ QIBM_QZMFMSF_ATT_CNV MSFFð1ðð \YES MSF Attachment Conversion
___ QIBM_QZMFMSF_ATT_MGT MSFFð1ðð \YES MSF Attachment Management
___ QIBM_QZMFMSF_ENL_PSS MSFFð1ðð \YES MSF Envelope Processing
___ QIBM_QZMFMSF_LCL_DEL MSFFð1ðð \YES MSF Local Delivery
___ QIBM_QZMFMSF_LST_EXP MSFFð1ðð \YES MSF List Expansion
___ QIBM_QZMFMSF_MSG_FWD MSFFð1ðð \YES MSF Message Forwarding
___ QIBM_QZMFMSF_NON_DEL MSFFð1ðð \YES MSF Non Delivery
___ QIBM_QZMFMSF_SEC_AUT MSFFð1ðð \YES MSF Security and Authority
___ QIBM_QZMFMSF_TRK_CHG MSFFð1ðð \YES MSF Track Mail Message Change
More...
Command
===>
F3=Exit F4=Prompt F9=Retrieve F12=Cancel

á ñ
Figure 3-3. Work with Registration Information Display

 Copyright IBM Corp. 1997 3-1

You can add, remove, display, or replace exit programs Figure 3-6 shows how the output on the display maps to the
using the Work with Exit Programs display. Figure 3-4 mail server framework.
shows that SNA distribution services (SNADS) has a single
exit program preregistered with this exit point. The other exit
program is provided by the framework. Exit Program
Exit Point
QSYS/QZDSNPAD
Attention QIBM_QZMFMSF_ADR_RSL
SPCL010001A101A201A301C0
Do not add exit program numbers that have exit program
numbers in multiples of 100 (for example, 100 or 200).
Multiples of 100 are reserved for IBM use. Do not move
RV3W168-4
IBM-supplied exit programs to different positions, change
the sequence of the exit programs, or change exit point Figure 3-6. Example of an Exit Program in the Mail Server Frame-
program data. work

.1/ The exit point name, which is the address reso-

(For more information about how SNADS uses MSF, see lution exit point.
Appendix D, “How Mail Server Framework Works with .2/ The name of the exit program, which is a
SNADS, Object Distribution, and OfficeVision.”) program associated with the support of the
SNADS function. See Appendix D, “How Mail
Server Framework Works with SNADS, Object
à Work with Exit Programs
ð Distribution, and OfficeVision.”
Exit point: QIBM_QZMFMSF_ADR_RSL Format: MSFFð1ðð .3/ The exit program data used by the mail server
Type options, press Enter. framework to select the exit program
1=Add 4=Remove 5=Display 1ð=Replace
(QSYS/QZDSNPAD). This data consists of a
Exit
Program Exit
format name (SPCL0100), followed by MSF
Opt Number Program Library address types. These address types are used
___ _________ð_
___ 1ððð QZDSNPAD QSYS by the framework to determine if the exit
___ 2ððð QZMFSNPA QSYS
program (QSYS/QZDSNPAD) should be called.
Whenever an MSF message having addresses
of these types in its recipient list is distributed by
Bottom the framework, this exit program is called and
Command
===> passed information about the MSF message.
F3=Exit F4=Prompt F5=Refresh F9=Retrieve F12=Cancel

á ñ
MSF Configuration APIs
Figure 3-4. Work with Exit Programs Display
The mail server framework requires that MSF data types be
To display details about a specific exit point program, type 5 configured. These configured types are stored in internal
in the Opt field next to the exit program you want to display. files. There are APIs available to list, add, and remove the
The Display Exit Program display is shown. four data types from the framework. Appendix A, “Mail
Server Framework APIs” on page A-1 contains a description
of these APIs.
à Display Exit Program
ð
System: RCHAS218
When an MSF message is created, the message information
Exit point . . . . . . . . . . . . . . . : QIBM_QZMFMSF_ADR_RSL .1/ is assigned data types. The mail server framework validates
Exit point format . . . . . . . . . . . . : MSFFð1ðð
the data types by looking in the internal table. If the data
Exit program number . . . . . . . . . . . : 1
Exit program . . . . . . . . . . . . . . : QZDSNPAD .2/ type is not configured, the MSF cannot process the
Library . . . . . . . . . . . . . . . . : QSYS
Text description . . . . . . . . . . . . : SNADS Address Resolution message. Messages are logged in the job log of the
Exit program data CCSID . . . . . . . . . : 37
program that attempted to use a data type that was not con-
Exit program data length . . . . . . . . : 24 figured.
Exit program data . . . . . . . . . . . . :
SPCLð1ððð1A1ð1A2ð1A3ð1Cð .3/
The same is true if an exit point program tries to change a
message. If the data type is not configured, MSF cannot
change the message. Messages are logged in the job log of
Bottom
Press Enter to continue. the QMSF job in which the exit point program was called.
F3=Exit F1ð=Display data F12=Cancel
In either case, the owner of the failing program needs to look
á ñ for the error in the exit point program. These instances are
not indications of problems with the mail server framework.
Figure 3-5. Display Exit Program Display

3-2 AnyMail/400 Mail Server Framework Support V4

It is important to note that when the program is changed, or then restart the mail server framework for the changes to
any configuration changes are made using the MSF config- take effect.
uration APIs, you must end the mail server framework and
See “MSF Data Types” on page 5-4 for more information
about the four data types used by the mail server framework.

Chapter 3. Configuration Considerations 3-3

3-4 AnyMail/400 Mail Server Framework Support V4
Chapter 4. Mail Server Framework Structure
The mail server framework provides the structure to support There are two other exit points,
functions that do the work of electronic mail distribution. This QIBM_QZMFMSF_TRK_CHG and
chapter shows how an MSF message is processed by the QIBM_QZMFMSF_VLD_TYP.
framework.
“Exit Point Program Registration” on page 3-1 explains how
to work with registration information about the exit points
listed in Table 4-1.
Exit Points
See the System API Reference book for more information
An exit point is a specific point in a system function or
about exit points and exit point programs.
program where control may be passed to one or more speci-
fied exit programs.

An exit point can call one program, a fixed number of pro- Exit Point Programs
grams, or all programs associated with an exit point. An exit
point contains an exit point name and exit point format name. An exit point program is a program to which control is
passed from an exit point. Each exit point program is associ-
Table 4-1. MSF Exit Points ated with an exit point and exit point format.

MSF Exit Point Description MSF Exit Point Name

List expansion QIBM_QZMFMSF_LST_EXP Snap-Ins
Address resolution QIBM_QZMFMSF_ADR_RSL
An MSF snap-in is an exit point program that is called from
Envelope processing QIBM_QZMFMSF_ENL_PSS the mail server framework exit points (see Table 4-1). The
Attachment conversion QIBM_QZMFMSF_ATT_CNV mail server framework recognizes snap-ins as exit point pro-
grams.
Security and authority QIBM_QZMFMSF_SEC_AUT
Local delivery QIBM_QZMFMSF_LCL_DEL The MSF message passes by the exit point if an exit point
Message forwarding QIBM_QZMFMSF_MSG_FWD program is not configured for the exit point. The exit point
program is called by the address types or message types in
Non-delivery QIBM_QZMFMSF_NON_DEL
the message. More information about APIs can be found in
Attachment management QIBM_QZMFMSF_ATT_MGT Appendix A, “Mail Server Framework APIs.” For an example
Accounting QIBM_QZMFMSF_ACT of how SNADS uses the mail server framework, see
Appendix D, “How Mail Server Framework Works with
SNADS, Object Distribution, and OfficeVision.”

 Copyright IBM Corp. 1997 4-1

 Figure 4-1 shows the exit points provided on the mail server
Exit Points Provided on the Mail Server framework. The MSF exit points provide a place for an exit
Framework program to be snapped in. A program that is snapped in at
an exit point provides the function. These functions are not
The MSF message enters at the top of the framework and part of the mail server framework. The framework only pro-
continues to flow through the framework until it reaches the vides the capability to call programs to correct, distribute, or
bottom. log the MSF message information. The mail server frame-
work uses the results of each of the exit point programs to
determine which exit program to call next.
List Expansion List Expansion

Address Resolution Address Resolution

List Expansion List Expansion

Envelope Processing Envelope Processing

Address Resolution Address Resolution

Attachment Conversion Attachment Conversion

Envelope Processing Envelope Processing

Security and Authority Security and Authority

RV3W158-0
Local Delivery Local Delivery
Figure 4-2. Using Multiple MSF Exit Point Programs
Message Forwarding Message Forwarding
Multiple exit point programs can be configured for each mail
server framework exit point. Figure 4-2 shows multiple exit
Non-Delivery Non-Delivery
point programs attached to an exit point.

Attachment Management Attachment Management

Accounting Accounting

Exit Point
Exit Point Program
RV3W151-2

Figure 4-1. MSF Exit Point and Exit Point Program Overview

4-2 AnyMail/400 Mail Server Framework Support V4

MSF Exit Point Groups
It is easiest to think about the exit point programs in terms of
groups of exit point programs that the exit points call. The
exit points are described in groups that perform related pro-
cessing functions.

Addressing
List Expansion List Expansion

Address Resolution Address Resolution

Pre-delivery Envelope Processing Envelope Processing

Processing

Attachment Conversion Attachment Conversion

Security and Authority Security and Authority

Delivery Local Delivery Local Delivery

Message Forwarding Message Forwarding

Management Non-Delivery Non-Delivery

Attachment Management Attachment Management

Accounting Accounting

Exit Point
Exit Point Program
RV3W153-3

Figure 4-3. MSF Exit Point Groups

Ÿ Addressing group Ÿ Delivery group

The exit point programs in this exit point group resolve The delivery group exit point programs provide local
the addresses of the originator, recipient, report-to, and delivery or forwarding of an MSF message.
report-on lists.
Ÿ Management group
These exit point programs establish that every recipient
This is the clean-up area. The management group exit
has a MSF data type and that the recipient list is com-
point programs determine what to do with the MSF
plete and correct. The mail server framework continues
message if it cannot be delivered or forwarded. It
to call these exit point programs until the recipient list
manages storage used by the MSF message attach-
information is complete.
ments when the attachments are no longer needed. It
Ÿ Pre-delivery processing group can also log how and when the framework was used,
track the processing of the MSF message, or provide
The pre-delivery processing group determines if the MSF
accounting for the MSF message flowing through the
data type needs to be changed for delivery to take
framework.
place, including envelopes and attachment references.

Chapter 4. Mail Server Framework Structure 4-3

Exit Point Programs in the Addressing
Group

Addressing
List Expansion List Expansion

Address Resolution Address Resolution

Pre-delivery Envelope Processing Envelope Processing

Processing

Attachment Conversion Attachment Conversion

Security and Authority Security and Authority

Delivery Local Delivery Local Delivery

Message Forwarding Message Forwarding

Management Non-Delivery Non-Delivery

Attachment Management Attachment Management

Accounting Accounting

RV3W154-1

Figure 4-4. Exit Point Programs in the Addressing Group

List Expansion Exit Point Address Resolution Exit Point

The list expansion exit point calls programs that determine if One of the main purposes of any program called by this exit
a message recipient address name is the name of a distribu- point is to assign a message type and message status to
tion list. The name of the distribution list can expand into every MSF message recipient. Recipient message types are
either a list of recipients or more names of distribution lists. used to select programs configured in the remaining exit
This exit point calls registered programs based on the points. It allows the user to configure an exit program that
address type of recipients that do not have a message type provides various routing functions. Sometimes the message
already assigned to them. A nondeliverable message type is originator does not provide all of the necessary distribution
assigned to those that do not have a message type already information. For example, the exit point program could take
assigned. Every message recipient has an address and a a partial recipient list, locate it in the directory, and then
type associated with the address. The list expansion exit change the recipient information to include the complete
point program is configured by address type. When an MSF information required by later exit point programs.
message is being processed that contains recipients with that
address type, then the program is called. After all address resolution exit point programs are called,
the mail server framework checks to see if a recipient list
For example, a single recipient list address could represent entry was replaced or added by a recipient without a
the name of a distribution list containing the names of the message type. If this occurred, processing continues at the
members of a department. A list expansion exit point list expansion exit point, allowing the new information to be
program function could expand the single recipient list processed.
address into the addresses of the department members.
If any entries are added to the list either during list expansion
To see how exit point programs are configured to be called, or address resolution, the processing of the list expansion
see Chapter 3, “Configuration Considerations.” exit point program and the address resolution exit point
program is recursive. Only the new entries are processed

4-4 AnyMail/400 Mail Server Framework Support V4

because the other entries have already been processed.
See Figure 4-4.

Chapter 4. Mail Server Framework Structure 4-5

Exit Point Programs in the Pre-Delivery
Processing Group

Addressing
List Expansion List Expansion

Address Resolution Address Resolution

Pre-delivery Envelope Processing Envelope Processing

Processing

Attachment Conversion Attachment Conversion

Security and Authority Security and Authority

Delivery Local Delivery Local Delivery

Message Forwarding Message Forwarding

Management Non-Delivery Non-Delivery

Attachment Management Attachment Management

Accounting Accounting

RV3W155-2

Figure 4-5. Exit Point Programs in the Pre-Delivery Processing Group

Note An envelope processing exit point program can add a new

envelope type to the MSF message. If this occurs, the mail
If a recipient list entry does not have a message data
server framework does not call any of the exit point programs
type at the start of the pre-processing delivery group, the
from previous exit points. An exit program might want to add
recipient list entry is given a nondeliverable status and
another envelope if there is an exit point program later in the
message type.
mail server framework processing that is designed to use
that particular type of envelope.

Envelope Processing Exit Point

Attachment Conversion Exit Point
Any envelope processing program called by this exit point
allows for message envelope alterations and conversions. The programs called by this exit point resolve potential con-
An envelope is information associated with an MSF flicts between the previously resolved message type, and the
message and the recipient, such as subject, date and time, format, structure, or content of the attachments associated
priority, notes, and special instructions. with the MSF message. For example, a conflict could be
that the attachments are not in the correct format, not stored
This exit point program uses information about a recipient in the correct file system, or need to be changed so that the
message type and envelope contents. It can provide exit point programs that follow can use the information. This
message envelope updates, in addition to converting an exit point allows an attachment conversion exit point program
envelope format into another envelope associated with a to make the required changes to the message attachment
recipient message type. content. For example, an OfficeVision document could be
converted to simple ASCII text within this exit point program.

4-6 AnyMail/400 Mail Server Framework Support V4

Security and Authority Exit Point distribution status for each refused recipient (for example, a
remote recipient) could be changed to nondeliverable or
The security and authority exit point is available for users to security violation state by the program.
write exit programs to do specific security and authority
checking required by a system or mail server. An MSF The exit program can access all information about the
message could be changed by the user-written exit program message (not the message itself) provided by the mail server
so all or some of its recipients would not receive the framework.
message information. To stop such a message, the recipient

Chapter 4. Mail Server Framework Structure 4-7

Exit Point Programs in the Delivery Group

Addressing
List Expansion List Expansion

Address Resolution Address Resolution

Pre-delivery Envelope Processing Envelope Processing

Processing

Attachment Conversion Attachment Conversion

Security and Authority Security and Authority

Delivery Local Delivery Local Delivery

Message Forwarding Message Forwarding

Management Non-Delivery Non-Delivery

Attachment Management Attachment Management

Accounting Accounting

RV3W156-1

Figure 4-6. Exit Point Programs in the Delivery Group

Local Delivery Exit Point the message recipient. The framework only decides which
exit point programs to call and pass the message information
The programs called by the local delivery exit point provide to. It uses the message types of recipient list entries that
local delivery of the MSF message. have a remote status to make these decisions.

As with other MSF exit points, it is possible to configure exit As with other MSF exit points, it is possible to configure exit
point programs to call or pass recipients that have certain point programs that only call or pass recipients that have
message types in a message recipient list. The message specific MSF data types assigned to them. The message
status of the recipient must be a local message status and status of the recipient must be remote and the exit point
the exit point program must be configured to handle recipi- program must be written to handle recipients with that recip-
ents with that recipient message type. ient message type.

Various exit point programs might be written to support

Message Forwarding Exit Point protocol-specific message forwarding. For example, the
SNADS message forwarding program forwards an MSF data
The programs called by the message forwarding exit point
type to remote SNADS recipients by creating a SNADS distri-
allow an MSF message to be forwarded to remote recipients
bution and placing the distribution on a SNADS distribution
(for example, a mail user not defined on the same AS/400
queue. A SNADS sender will then do the actual sending of
system).
the distribution. See the SNA Distribution Services book for
The mail server framework does not forward the message to more information about SNADS distribution.

4-8 AnyMail/400 Mail Server Framework Support V4

Exit Point Programs in the Management
Group

Addressing
List Expansion List Expansion

Address Resolution Address Resolution

Pre-delivery Envelope Processing Envelope Processing

Processing

Attachment Conversion Attachment Conversion

Security and Authority Security and Authority

Delivery Local Delivery Local Delivery

Message Forwarding Message Forwarding

Management Non-Delivery Non-Delivery

Attachment Management Attachment Management

Accounting Accounting

RV3W157-1

Figure 4-7. Exit Point Program in the Management Group

Non-Delivery Exit Point Ÿ A recipient does not have a message type and was
marked nondeliverable by the mail server framework.
The programs called by the non-delivery exit point report that
the MSF message was not delivered to its destination or
recipient. The exit point program allows for the following Attachment Management Exit Point
solutions:
The programs called by the attachment management exit
Ÿ Logging the distribution that cannot be delivered point manage the attachments to an MSF message. This
Ÿ Routing the nondeliverable messages to a storage area exit point is used only if there is an attachment reference list
where they are kept, corrected, and resent associated with the MSF message.

Ÿ Creating a new message to report the non-delivery MSF messages only refer to attachments to a message; they
do not own or manage the storage of the attachments to the
Several things can prevent a message from being delivered. message.
Examples include the following:
Ÿ An address resolution exit point program may have a
Accounting Exit Point
partial address of a recipient. The exit point program
cannot construct a complete address, and the MSF The programs called by the accounting exit point support the
message is labeled nondeliverable. system or network accounting functions required in the elec-
Ÿ The local delivery exit point program or the message for- tronic mail environment. The accounting is done after all
warding exit point program may be configured incor- other activity has taken place in the other exit point pro-
rectly. grams. The user can write an exit program that records the
activity that takes place in the mail server framework.
Ÿ Recipients may have been marked nondeliverable
through address resolution processing. This is the last point at which message information is avail-
able. The mail server framework deletes the internal struc-

Chapter 4. Mail Server Framework Structure 4-9

tures associated with the message as soon as the point program must be written and called to save, deliver, or
appropriate exit point programs have used the information. forward any message information.
The MSF message is destroyed after this exit point. An exit

4-10 AnyMail/400 Mail Server Framework Support V4

Chapter 5. Mail Server Framework Message Concepts
MSF messages are created when the Create Mail Message
(QzmfCrtMailMsg) API is used. The framework passes infor-
mation about the MSF message across the API. The MSF
Recipient List
message is put on a queue. MSF messages exist until all of Envelope List Attachment
Reference List
the appropriate exit point programs have processed them.

The MSF message contains typed information about the

message. The mail server framework contains interfaces to
exit points that deal with the MSF message.
Originator List Original
The MSF message lists and data types allow the framework Recipient List
to work with the MSF message information. The MSF
message can be used or changed only by an exit point
program when the framework calls it and passes the MSF
message information to the program.

MSF
Message

MSF
Message

Mail Server Framework

List Expansion List Expansion

Address Resolution Address Resolution

RV3W160-2

Figure 5-1. MSF Message Concept Overview

 Copyright IBM Corp. 1997 5-1

MSF Message Lists Originator List

Address Type The MSF message must have an originator list with at least
Address Type
Address Type
one originator entry. Each originator entry is made up of an
originator address and an originator address type. If more
Address than one originating entry is specified when the message is
Originator
List created, the mail server framework assumes that all of the
entries represent the same originator.

Original Recipient List

Address Type
Address Type
Address Type

Address An MSF message can contain a list of all the recipients that
Original were originally specified when the message was sent. This
Recipient List
optional list can be used by applications that, for example,
want to reply to all recipients of a message. This list is dif-
ferent from the recipient list in that, as a message moves
through the network, recipients that are delivered on interme-
diate systems are removed from the recipient list. However,
Envelope
Envelope
the original recipient list remains intact.
Envelope

Recipient List
Envelope List

Address Type
Address Type
An MSF message must have one or more recipient entries.
Address Type When an MSF message is created, the recipient address and
recipient address type are required fields for each recipient
Address
Recipient List entry.

While the message type in the recipient list entry is not a

required field for creating a message, it must be assigned to
Attachment a recipient by one of the addressing exit point programs.
Reference Type
Attachment The MSF data type assigned must be in the table of accept-
Reference Type
Attachment able MSF data types for the system.
Reference Type

The key parts of a recipient list entry are:

Attachment Reference Attachment
Reference Ÿ Address types
List
RV3W161-3
Ÿ Message types
Ÿ Status field
Figure 5-2. MSF Message Lists

5-2 AnyMail/400 Mail Server Framework Support V4

Envelope List acceptable reference types for the system. For example, a
reference type can be a database file member or a folder
document.

Other Lists
An MSF message must have one or more envelope entries.
The message envelope is the information about a particular There are other lists that can be passed to the Create Mail
message for a particular protocol type, except for the generic Message API.
envelope type.
Report-On List: The mail server framework requires that
A generic envelope type is defined for any exit point program each report-on list entry contain a non-delivery address and
to use. Using the generic envelope type allows an exit point a corresponding address type. The address type must be
program that is processing messages for one protocol type to configured as a valid address type in the mail server frame-
hand over the message to another exit point program that work by using the configuration APIs described in “MSF Con-
processes messages for another protocol type. figuration APIs” on page A-1.

The mail server framework requires that each envelope entry Report-To List: The report-to list contains a list of users
contain envelope information and an identifying envelope that are sent an error report when an error occurs with a
type. The envelope type must be in the table of acceptable message. The mail server framework requires that each
protocol types for the system. report-to address entry contain a report-to address and a cor-
responding address type. An MSF message can have zero,
one, or multiple report-to address entries. The address type
Attachment Reference List must be configured as a valid address type in the mail server
framework by using the configuration APIs described in “MSF
Configuration APIs” on page A-1.

An MSF message can refer to any number of attachments. Message Identifier

Each attachment referenced is an entry in the attachment
reference list. The MSF messages without attachments have The message identifier (ID) is a 32-character unique ID gen-
no attachment reference list. erated by the mail server framework when the message is
created. This ID is used by the exit point programs when
The mail server framework requires that each attachment ref- they are called to retrieve or change information in the MSF
erence list contain attachment reference data and a refer- message. The message identifier cannot be reused. The ID
ence type. The reference type must be in the table of is kept with the message and passed to all of the exit point
programs.

Chapter 5. Mail Server Framework Message Concepts 5-3

 The data type value is a unique 4-character representation.
MSF Data Types The following type values have special meaning to the mail
server framework.
Ÿ 0xxx to 9xxx are reserved for use by IBM.
MSF
Message
Important
It is not recommended to define a data type using
The MSF data type is used by the mail server framework to this range. IBM may, at a later time, add additional
define the contents of the data and how the data should be predefined data types within this range. If a data
processed by the exit point programs. The MSF does not type definition is found in this range and it is not
process the contents of the message. The framework supplied by IBM, problems could occur for MSF mail
passes the MSF message to the exit point programs for pro- applications.
cessing.
Ÿ 9998 is reserved for use as the nondelivery message
MSF data types are used in the exit program data when con- data type.
figuring exit point programs. Figure 3-6 on page 3-2 shows
Ÿ 9999 is not a data type. It is reserved for use in speci-
an example of exit program data .3/.
fying that an exit point program is configured to process
The MSF data type determines which exit point program all address or message data types.
processes the message and how the MSF message is pro-
The type name is the name of the data type being config-
cessed. Figure 5-3 on page 5-5 shows the framework using
ured. The type text is a description of the data type defi-
MSF data types to determine which exit point program to
nition. Figure B-12 on page B-11 is an example of a CF
call.
journal entry, showing the type group, data type value, and
There are four data types that are defined by the mail server type name.
framework.
Ÿ Address type
How the MSF Data Types Are Used to Call
The address type is an identifier that indicates the type Exit Point Programs
of data that is contained in the address string. The
address type determines what exit point program to call Exit point programs are called by the mail server framework
for the list expansion and address resolution exit points. based on the following:
Ÿ Message type Ÿ MSF data types specified in the exit program data of the
The message type is used in the remaining exit points to registered exit point program.
identify which exit point program to call. Ÿ MSF data types present in the MSF message recipient
Ÿ Envelope type list entries.

The envelope type is an identifier that indicates the type An exit point program is called and passed information about
of data that is contained in the envelope. the MSF message so that the program can perform its func-
Ÿ Attachment reference type tions.

The attachment reference type is an identifier that indi-

cates the type of data that is contained in the attachment
reference.
How the MSF Message Changes
Exit point programs that are called by the mail server frame-
Rules for MSF Data Type Definitions work can change the information in an MSF message so
other exit point programs can see different or additional
Every MSF data type definition is associated with a type message information. An exit point program can use the
group, consisting of a data type value, type name, and type Change Mail Message (QzmfChgMailMsg) API to make
text. There are IBM-supplied data types predefined in the changes to the MSF message. These changes have no
MSF configuration that are shipped with the OS/400 licensed effect until the program returns control to the framework, indi-
program. See AnyMail/400 Mail Server Framework Devel- cating that it has finished processing the MSF message suc-
oper Guide for more information about the IBM-supplied data cessfully. See Figure 5-4 on page 5-5.
types.
There are some restrictions regarding which exit point pro-
grams may change an MSF message at certain exit points.

5-4 AnyMail/400 Mail Server Framework Support V4

 MSF
Message

MSF data type configured

as exit program data

01A4
01A3

01A4
01A2
01A3
01A1
01A1

Address
Address

Recipient List

Data type assigned

when MSF message
is created RV3W162-3

Figure 5-3. MSF Data Types Used to Determine Which Exit Point Program to Call

Exit Point Program page 2-2 for more information about the QSYSWRK sub-
called for data system.
type 01A1

The mail server framework decides which exit point programs

to call at each exit point. The exit point programs can act on
01A4 or change message information that might be used by other
01A3 01A1 exit point programs. This does not mean that each message
01A1 QzmfChgMailMsg
uses every registered exit point program; the message data
Address
Address Change Mail Message types of the recipient determine which exit point programs
are called.
Recipient List
It also does not mean that every exit point program called
Recipient Address uses the MSF message information. The exit point program
Changed
RV3W171-2
determines that it has no function to perform for that
message and simply returns it to the framework.
Figure 5-4. Exit Point Programs Can Change Information in an
MSF Message In Figure 5-5 on page 5-6, the address resolution exit point
program is the first program called .1/ based on the MSF
address types in the message recipient list. This exit point
How the MSF Message Flows Through the program decides which MSF message types and recipient
Framework status are assigned to recipients in the message recipient
list. It changes the recipient list entries. In this example,
A user mail application on the system uses the mail server some message recipients are assigned local status and
framework Create Mail Message API to create MSF mes- some are assigned remote status.
sages. The mail server framework inspects the MSF mes-
sages to ensure that the information is acceptable. A local delivery exit point program .2/ is called by the frame-
work and passed information in the MSF message. The
Once MSF messages are created, they are put on a queue. information includes the recipient list entries that have the
When the mail server framework has been started by the message type (and local status) that the exit point program is
Start Mail Server Framework (STRMSF) command, the MSF configured to handle.
message is processed by the framework. Processing of the
MSF message is handled by the QMSF job (located in the When the program returns, a message forwarding exit point
QSYSWRK subsystem). See “Managing MSF Jobs” on program .3/ is called and passed information in the MSF

Chapter 5. Mail Server Framework Message Concepts 5-5

message. The information includes the recipient list entries
that have the message type (and forward status) that the exit MSF
Message
point program was configured to handle. When the message MSF
MSF
Message
Message
forwarding program returns, the framework determines if
other exit point programs at the remaining exit points should
be called based on the message types in the message recip-
ient list. In this example, there are no additional exit point
programs to be called so the MSF message is removed.
List Expansion
Figure 5-5 shows three exit point programs cooperating in
delivering MSF message information to local recipients and Address Resolution Address Resolution
forwarding that information to remote recipients in its recip-
ient list. There could be more exit point programs configured Envelope Processing
but not part of the example message flow because the MSF
data types did not result in a call to these exit point pro- Attachment Conversion
grams.
Security and Authority

Local Delivery Local Delivery

Message Forwarding Message Forwarding

Non-Delivery

Attachment Management

Accounting

RV3W169-0

Figure 5-5. How an MSF Message Flows Through the Framework

5-6 AnyMail/400 Mail Server Framework Support V4

Appendix A. Mail Server Framework APIs
This appendix describes the mail server framework APIs. Add Mail Server Framework Configuration
For more information about the required parameter groups, (QzmfAddMailCfg) API
message descriptors, message descriptor formats, and error
messages, see the System API Reference book. The Add Mail Server Framework Configuration
(QzmfAddMailCfg) API configures the MSF data types used
The following APIs are made up of program calls: by the mail server framework to process messages. The fol-
MSF configuration APIs lowing data types are valid:
Add Mail Server Framework Configuration Ÿ Address
(QzmfAddMailCfg) Ÿ Message
List Mail Server Framework Configuration Ÿ Envelope
(QzmfLstMailCfg) Ÿ Attachment reference
Remove Mail Server Framework Configuration
(QzmfRmvMailCfg) This API also configures the address type and message type
Message APIs that can be specified as exit program data in the user-written
Create Mail Message (QzmfCrtMailMsg) exit program.
Change Mail Message (QzmfChgMailMsg)
Retrieve Mail Message (QzmfRtvMailMsg) The MSF data type is used to process the MSF message
Complete Creation Sequence through the framework. Only one data type can be added at
(QzmfCrtCmpMailMsg) a time. See “MSF Data Types” on page 5-4 for more infor-
Query Mail Message Identifier (QzmfQryMailMsgId) mation about the four data types.
Reserve Mail Message Identifier
(QzmfRsvMailMsgId)
Remove Reserved Mail Message Identifier
List Mail Server Framework Configuration
(QzmfRmvRsvMailMsgId) (QzmfLstMailCfg) API
The mail server framework also provides three exit points The List Mail Server Framework Configuration
where the following exit programs are used: (QzmfLstMailCfg) API creates a list of data types and places
the list in a specified user space.
Snap-In Call Exit Point Program
Track Mail Message Changes Exit Point Program
Validate Data Field Exit Point Program Remove Mail Server Framework
Configuration (QzmfRmvMailCfg) API

MSF Configuration APIs The Remove Mail Server Framework Configuration

(QzmfRmvMailCfg) API removes MSF data types that the
The MSF configuration APIs are used to process type config- mail server framework uses to process MSF messages. The
urations within the mail server framework configuration. The MSF data type is removed from the configuration when this
following processes can be performed: API is used. Only one data type can be removed at a time.
See “MSF Data Types” on page 5-4 for more information
Ÿ Adding to the configuration about the four data types.
Ÿ Removing from the configuration
Ÿ Listing the contents of the configuration

These APIs are used to add or remove new mail application MSF Message APIs
support in the framework or to list the current configuration. The MSF message APIs are used to create an MSF
message and ensure delivery of the message. These APIs
Exit point programs can also access the trace information
are used by user-written exit programs.
that contains an account of all the exit point programs used
in the framework and those that changed the message by
using the Retrieve Mail Message (QzmfRtvMailMsg) API. Create Mail Message (QzmfCrtMailMsg)
The framework does not record the exact changes made to API
the message. The Track Mail Message Changes Exit
Program is called whenever an exit point program changes The Create Mail Message (QzmfCrtMailMsg) API creates an
the message and a program is registered for the exit point. MSF message. When an MSF message is created, the fol-
lowing lists can be specified:
Ÿ Originator (required)
Ÿ Recipient (required)
Ÿ Envelope (required)

 Copyright IBM Corp. 1997 A-1

 Ÿ Attachment reference Reserve Mail Message Identifier
Ÿ Report-on (QzmfRsvMailMsgId) API: The Reserve Mail Message
Ÿ Report-to Identifier (QzmfRsvMailMsgId) API is used to reserve an
Ÿ Original recipient list identifier for an electronic mail message.
Ÿ Reply-to list
Complete Creation Sequence
The format of the data is defined by assigning a type to the
(QzmfCrtCmpMailMsg) API: The Complete Creation
information. The MSF data types need to be configured
Sequence (QzmfCrtCmpMailMsg) API removes a previously
before they can be supported. There are four MSF data
created, reserved mail message identifier from the MSF list
types.
of reserved identifiers and acknowledges that the MSF
Ÿ Address type message was created.
Ÿ Message type
Ÿ Envelope type Remove Reserved Mail Message Identifier
Ÿ Attachment reference type (QzmfRmvRsvMailMsgId) API: The Remove Reserved
Mail Message Identifier (QzmfRmvRsvMailMsgId) API
See Chapter 5, “Mail Server Framework Message Concepts” removes a reserved identifier for an electronic mail message
for more information about MSF lists and MSF data types. that you have not yet created. If the message was created,
you must use the Complete Creation Sequence API to
Change Mail Message (QzmfChgMailMsg) release the reserved message. After the Remove Reserved
Mail Message Identifier API completes successfully, you
API cannot use the message identifier you reserved earlier when
The Change Mail Message (QzmfChgMailMsg) API changes the message was created.
information about an MSF message that was previously
created using the Create Mail Message API. Each time it is
called, the Change Mail Message API can change one or Exit Points
more list items for each of the message parameter list
formats. For example, one call can result in changes to the The mail server framework provides three exit points where
envelope list, the recipient list, and the attachment reference the following exit programs are used.
list. An exit program can be written to change an MSF
message. If the requested changes are acceptable, the Snap-In Call Exit Point Program
existing list items are replaced with the new items that are
specified. The list items do not retain their same unique list The Snap-In Call Exit Point Programs process the electronic
identifiers after the changes are complete. mail within the framework.

Figure 5-4 on page 5-5 shows an example of how the MSF

message changes when this API is used. Track Mail Message Changes Exit Point
Note: The Change Mail Message API is only valid within Program
the processing of a Snap-In Call Exit Point Program.
In some cases, the user may want to track the changes
made to a message. The Track Mail Message Changes Exit
Retrieve Mail Message (QzmfRtvMailMsg) Program can be used. Whenever a message is changed by
API an exit point program, an exit program registered for this exit
point is called and the following information is passed:
The Retrieve Mail Message (QzmfRtvMailMsg) API retrieves Ÿ The message identifier
information about an MSF message and returns it in the Ÿ The exit point name being processed when the change
receiver variable provided by the caller. was made
Note: The Retrieve Mail Message API is only valid within Ÿ The exit point program name responsible for the change
the processing of a Snap-In Call Exit Point Program or the
Track Mail Message Changes Exit Point Program.
Validate Data Field Exit Point Program
Other Optional APIs The Validate Data Field Exit Point Program allows exit pro-
grams to validate the data for a message based on the MSF
Query Mail Message Identifier (QzmfQryMailMsgId) data type selected. As part of the mail server framework
API: The Query Mail Message Identifier configuration, MSF data types must be defined to the
(QzmfQryMailMsgId) API is used to query the status of a system.
mail message identifier within the mail server framework.

A-2 AnyMail/400 Mail Server Framework Support V4

Appendix B. MSF Journal Logging and Journal Formats
This appendix provides information about the journal support uration of MSF types or exit programs takes place; this entry
used by the mail server framework. is type CF.

QZMF Journal Displaying the QZMF Journal

The mail server framework uses OS/400 journal support to You can view the MSF journal entries by using the Display
track MSF configuration changes and MSF message pro- Journal (DSPJRN) command. Type DSPJRN on the command
cessing performed on the local system by the mail server line and press F4. You are prompted for the information you
framework. want to see. You can enter specific parameters and options
or take the default values for each of the prompted parame-
A journal (QZMF) is shipped with security officer authority in ters.
the QUSRSYS library. The journal name used for the mail
server framework must be QZMF. QZMF uses a journal
code of S. Code S is a distributed mail service for SNA dis-
tribution services (SNADS), network alerts, or the mail server
à Display Journal (DSPJRN)
ð
framework. For the QZMF journal, this code always means Type choices, press Enter.
the mail server framework. Journal . . . . . . . . . . . . QZMF Name, \INTSYSJRN
Library . . . . . . . . . . . \LIBL Name, \LIBL, \CURLIB
Journaled physical file:
There are four types of MSF journal entries: File . . . . . . . . . . . . . \ALLFILE Name, \ALLFILE, \ALL
Library . . . . . . . . . . Name, \LIBL, \CURLIB
Member . . . . . . . . . . . . Name, \FIRST, \ALL
LG MSF message log information for the mail server + for more values
framework. A normal function, such as creating or Range of journal receivers:
Starting journal receiver . . \CURRENT Name, \CURRENT, \CURCHAIN
completing an MSF message, was successfully per- Library . . . . . . . . . . Name, \LIBL, \CURLIB
Ending journal receiver . . . Name, \CURRENT
formed. Library . . . . . . . . . . Name, \LIBL, \CURLIB
Starting sequence number . . . . \FIRST Number, \FIRST
ER MSF message error information for specific MSF Starting date and time:
Starting date . . . . . . . . ð1/16/95 Date
messages in the mail server framework. The MSF Starting time . . . . . . . . ð8:ðð:ðð Time
More...
message could not be completed because of a F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display
F24=More keys
framework or exit point program error.
SY MSF system information for the mail server frame- á ñ
work.
Figure B-1. Display Journal - First Display
CF Configuration information for the mail server frame-
work.

An output file for each type of entry is provided that shows à Display Journal (DSPJRN)
ð
the data for each entry. This file enables you to copy the Type choices, press Enter.
information to an output file using the Display Journal Ending sequence number . . . . . \LAST Number, \LAST
(DSPJRN) command. Specify *TYPE1 for the outfile format Ending date and time:
Ending date . . . . . . . . . ð1/16/95 Date
(OUTFILFMT) parameter. Ending time . . . . . . . . . Time
Number of journal entries . . . \ALL Number, \ALL
Journal codes:
You are responsible for changing the QZMF journal receiver Journal code value . . . . . . S \ALL, \CTL, A, C, F, J, L...
Journal code selection . . . . \ALLSLT, \IGNFILSLT
with the Change Journal (CHGJRN) command. You can do + for more values
Journal entry types . . . . . . \ALL Character value, \ALL, \RCD
this when the receiver is full, or at any convenient time. + for more values
Job name . . . . . . . . . . . . \ALL Name, \ALL
User . . . . . . . . . . . . . Name
When an MSF message is created or processed by the mail Number . . . . . . . . . . . . ðððððð-999999
Program . . . . . . . . . . . . \ALL Name, \ALL
server framework successfully, a journal entry, type LG, is User profile . . . . . . . . . . \ALL Name, \ALL
made on the system. If an error occurs when processing an More...
F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display
MSF message, an error entry, type ER, is made in the QZMF F24=More keys

journal. SY entries record significant events that may affect

MSF functions, for example when the STRMSF or ENDMSF
á ñ
commands are used. An entry is made whenever a config-
Figure B-2. Display Journal - Second Display

 Copyright IBM Corp. 1997 B-1

 – Ending time: The time is specified in 24-hour format
à Display Journal (DSPJRN)
ð and can be specified with or without a time sepa-
Type choices, press Enter.
rator (for example, 08:00:00).
Commit cycle identifier . . . . \ALL Number, \ALL Ÿ Journal codes: For the mail server framework entries,
Dependent entries . . . . . . . \ALL \ALL, \NONE
Output format . . . . . . . . . \CHAR \CHAR, \HEX this code will always be S. No other codes are used by
Output . . . . . . . . . . . . . \ \, \PRINT, \OUTFILE MSF.
Ÿ Journal entry types: For the mail server framework,
the following entries are used:
LG: MSF message log information entries
ER: MSF message error information entries
SY: MSF message system information entries
Bottom
CF: MSF configuration information entries
F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display
F24=More keys You can specify any combination of codes. For
example, you can specify that you only want to see the
á ñ LG and ER entries. The default displays all entries.
Figure B-3. Display Journal - Third Display Ÿ Job name: Specify QMSF or the user job name (for
example, QPADEV0007) to show the jobs running for
The following specifies the parameters and the options avail- the mail server framework.
able for MSF entries.
Ÿ Range of journal receivers: Specifies the starting Displaying the Journal Entries
(first) and ending (last) journal receivers that contain the
journal entries being converted for output. From the Display Journal display, press the Enter key to see
Ÿ Starting sequence number: Specifies the first journal the Display Journal Entries display. The information con-
entry to be considered for conversion for output. You tained on this display depends on the parameters and values
can specify *FIRST to display the entire journal receiver you specified (including default values taken). The entries
range or you can specify a specific sequence number to are always displayed in chronological order. The following is
be converted. an example of the display:

Ÿ Starting date and time: Specifies the date and time of

the first journal entry.
à Display Journal Entries
ð
– Starting date: The format for the date is defined by
Journal . . . . . . : QZMF Library . . . . . . : QUSRSYS
the job attributes DATFMT and, if separators are
Type options, press Enter.
used, DATSEP (for example, 01/16/95). 5=Display entire entry

– Starting time: The time is specified in 24-hour

Opt Sequence Code Type Object Library Job Time
format and can be specified with or without a time 1 J PR DSPð1 19:15:28
3 J RR QZMF QUSRSYS 19:42:51
separator (for example, 08:00:00). 4 J IN 22:21:ð6
5 J IN 11:43:28
These fields are very useful because they segment the 6 S SY QPADEVððð7 12:43:31
7 S SY QPADEVððð7 13:ð1:42
QMSF journal entries into specific windows of interest. 8 S SY QPADEVððð8 14:1ð:22
9 S SY QPADEVððð8 14:1ð:31
For example, if you want to display all entries that 1ð S SY QPADEVððð8 14:1ð:33
occurred on 05/24/95, starting at 11:00 a.m., specify the 11
12
S
S
SY
SY
QPADEVððð8
QPADEVððð8
14:13:27
14:13:34
starting date of 05/24/95 and the starting time of 13 S SY QPADEVððð8 14:13:35 +

11:00:00, and then press the Enter key. F3=Exit F12=Cancel

Ÿ Ending sequence number: Specifies the last journal á ñ

entry to be considered for conversion. You can specify
*LAST to display the final journal receiver being con- Figure B-4. Display Journal Entries Display
verted or you can specify a specific sequence number to
be converted. This sample display was shown with default values specified
for all of the parameters. As a result, there are different
Ÿ Ending date and time: Specifies the date and time of
codes, different entry types, and different jobs listed.
the last journal entry.
– Ending date: The format for the date is defined by If the data in the record does not fit on one display, use the
the job attributes DATFMT and, if separators are page keys to advance to subsequent displays or to return to
used, DATSEP (for example, 05/30/95). a previous display in the series. A plus sign (+) in the lower
right corner of the display indicates that there are more dis-
plays in the series.

B-2 AnyMail/400 Mail Server Framework Support V4

Note: If there are no entries in the journal receiver that Entry Type ER: This display is shown when you type a 5
match the values on the entered parameters, this message (Display entire entry) on the Display Journal Entries display
appears on the display: next to an entry that has function type ER (error). “Format
(No log entries). for MSF Message Errors (ER)” on page B-7 provides
detailed information about the contents of this display.
This condition can occur when the log entries are sent to the
journal receiver during a time when the system clock is set to
an incorrect date or time. You would be unable to find à ð
Display Journal Entry
entries for a specified range when you use a range search to
search the affected journal receiver. Use the Change Object . . . . . . . : Library . . . . . . :
Member . . . . . . . : Sequence . . . . . . : 3395
Journal (CHGJRN) command to create a new journal Code . . . . . . . . : S - Distributed mail services
Type . . . . . . . . : ER - Mail error information
receiver. Creating a new journal receiver (once the system
Entry specific data
clock has been set to the correct time) ensures that the Column \...+....1....+....2....+....3....+....4....+....5
ðððð1 'QMSF QMSF ðð6ðððQZMFBIGE2ID 1ðððð3394ð51'
current journal receiver entries have the correct time. This ððð51 '613ð5ð9ðððððððð15 CAPITST DEBPGM '
command has no effect on old journal receivers.

From the Display Journal Entries display, you can type a 5

(Display entire entry) in the Opt field to see the detail for
each entry. The information available in the detail is different Bottom
Press Enter to continue.
for each entry type, so the detail has a unique display based
F3=Exit F6=Display only entry specific data
on the entry type. The following are examples of detail dis- F1ð=Display only entry details F12=Cancel F24=More keys
plays for different function and entry types.
á ñ
Entry Type LG: This display is shown when you type a 5
(Display entire entry) on the Display Journal Entries display Figure B-6. Display Journal Entry - Type ER
next to an entry that has function type LG (logging). “Format
for MSF Message Logging (LG)” on page B-5 provides Entry Type SY: This display is shown when you type a 5
detailed information about the contents of this display. (Display entire entry) on the Display Journal Entries display
next to an entry that has function type SY (system). “Format
for MSF System Level Events Table (SY)” on page B-8 pro-
vides detailed information about the contents of this display.
à Display Journal Entry
ð
Object . . . . . . . : Library . . . . . . :
Member . . . . . . . : Sequence . . . . . . : 338ð
Code .
Type .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
:
:
S - Distributed mail services
LG - Mail logging table information
à Display Journal Entry
ð
Entry specific data Object . . . . . . . : Library . . . . . . :
Column \...+....1....+....2....+....3....+....4....+....5 Member . . . . . . . : Sequence . . . . . . : 3715
ðððð1 'QMSF QMSF ðð6ðððQZMFBIGE2ID 1ðððð3394ð51' Code . . . . . . . . : S - Distributed mail services
ððð51 '5215842ððððððððð9 ' Type . . . . . . . . : SY - Mail system information

Entry specific data

Column \...+....1....+....2....+....3....+....4....+....5
ðððð1 'QPADEVððð7BANER ðð6163QZMFEEND5 '

Bottom
Press Enter to continue.

F3=Exit F6=Display only entry specific data

F1ð=Display only entry details F12=Cancel F24=More keys
Bottom
Press Enter to continue.
á ñ F3=Exit F6=Display only entry specific data
F1ð=Display only entry details F12=Cancel F24=More keys
Figure B-5. Display Journal Entry - Type LG
á ñ
Figure B-7. Display Journal Entry - Type SY

Appendix B. MSF Journal Logging and Journal Formats B-3

Entry Type CF: This display is shown when you type a 5
(Display entire entry) on the Display Journal Entries display à Display Journal Entry
ð
next to an entry that has the entry type CF (configuration). Object . . . . . . . : Library . . . . . . :
“Format for MSF Configuration Changes (CF)” on page B-9 Member . . . . . . . : Sequence . . . . . . : 369ð
Code . . . . . . . . : S - Distributed mail services
provides detailed information about the contents of this Type . . . . . . . . : CF - Mail configuration information
display. Entry specific data
Column \...+....1....+....2....+....3....+....4....+....5
ðððð1 'QPADEVððð7BANER ðð6163QZMFDLTC4 ð1ð1TTð1T'
ððð51 'TNAME'

Bottom
Press Enter to continue.

F3=Exit F6=Display only entry specific data

F1ð=Display only entry details F12=Cancel F24=More keys

á ñ
Figure B-8. Display Journal Entry - Type CF

B-4 AnyMail/400 Mail Server Framework Support V4

Format for MSF Message Logging (LG)
The entry is made when a MSF message is created, reset,
or completed. The entry is mapped by the database file
record, QAZMFLG, that represents the MSF message log
information entered. This record is defined by the physical
file QAZMFLG, which is shipped in QSYS library. The
LG-type journal entry contains the following information:

Table B-1. Type LG Journal Entries for MSF Messages

Field Format Description
Entry length Zoned(5,0) Total length of the journal entry, including the entry length field.
Sequence number Zoned(10,0) Applied to each journal entry. Initially set to 1 for each new or restored journal. Reset when
a new receiver is attached.
Journal code Char(1) Always S for MSF entries.
Entry type Char(2) Always LG for MSF message entries.
Date stamp Char(6) The system date that the entry was made.
Time stamp Zoned(6,0) The system time that the entry was made.
(Reserved area) Char(95)
Job name Char(10) The name of the job that caused the entry to occur.
User name Char(10) The user profile name associated with the job.
Job number Zoned(6,0) The job number.
Program name Char(8) The name of the MSF program that made the journal entry.
Function identifier Char(1) Function that was being performed when the entry was made. The possible values are:
1 MSF message created log entry
2 MSF message ended normally
3 MSF message reset by STRMSF command (STRMSF MSGOPT(\RESET))
4 MSF message removed by STRMSF command (STRMSF MSGOPT(\CLEAR))
5 MSF message acted on by address switcher
MSF message ID Char(32) The MSF message ID logged.
Length of entry data Zoned(5,0) The length of the logged data.
Logged data Char(256) The data logged by MSF when the function identifier is:
2 Data is three Zoned(5,0) numbers. The first number is the number of entries in the
recipient list when the message was created. The second number is the number of
entries in the recipient list when processing was completed for the message. The
third number is the number of recipients that had a non-deliverable status when
processing was completed for the message.
5 Data is two Zoned(5,0) numbers. The first number is the number of recipients that
had their address switched by program QZMFSNPA. The second number is the
total number of recipients that were in the recipient list of the MSF message pro-
cessed by QZMFSNPA.

Appendix B. MSF Journal Logging and Journal Formats B-5

Figure B-9 is an example LG journal entry you might see Job Name, MSF
when you use option 5 on the Display Journal Entries display User Name, Program Function Message
Job Number Name Identifier ID
to display the entire entry. The values of any QZMF journal
entry field can be mapped to the entry data displayed.

RV3W175-1

Logged Data

Figure B-9. Fields of the Journal Entries - Example

B-6 AnyMail/400 Mail Server Framework Support V4

Format for MSF Message Errors (ER)
The entry for MSF message errors is mapped by the data-
base file record, QAZMFER, that represents the error infor-
mation entered. This record is defined by the physical file
QAZMFER, which shipped in QSYS. The ER type journal
entry contains the following information:

Table B-2. Type ER Journal Entries for MSF Message Errors

Field Format Description
Entry length Zoned(5,0) Total length of the journal entry, including the entry length field.
Sequence number Zoned(10,0) Applied to each journal entry. Initially set to 1 for each new or restored journal. Reset when
a new receiver is attached.
Journal code Char(1) Always S for MSF entries.
Entry type Char(2) Always ER for MSF message error entries.
Date stamp Char(6) The system date that the entry was made.
Time stamp Zoned(6,0) The system time that the entry was made.
(Reserved area) Char(95)
Job name Char(10) The name of the job that caused the entry to occur.
User name Char(10) The user profile name associated with the job.
Job number Zoned(6,0) The job number.
Program name Char(8) The name of the MSF program that made the journal entry.
Error ID Char(1) The MSF error ID. The possible values are:
2 MSF message ended by an exit program
3 QMSF job ended by an exit program
4 An exit program returned data that was not valid
5 An exit program failed
MSF message ID Char(32) The MSF message ID logged.
Data length Char(5) The length of the logged data.
Logged data Char(256) The data logged by MSF when the error ID is:
2 Exit program name char(10) and library char(10)
3 Exit program name char(10) and library char(10)
4 Exit program name char(10) and library char(10)
5 Exit program name char(10) and library char(10)

Figure B-9 on page B-6 shows an example of how the fields

defined for QZMF journal entries are mapped to the dis-
played data.

Appendix B. MSF Journal Logging and Journal Formats B-7

 entries to be made in the MSF journal. The SY-type journal
Format for MSF System Level Events entry contains the following information:
Table (SY)
The entry for system level events table change is shown by
the database file record, QAZMFSY, which represents MSF
system name table entries. This record is defined by the
physical file QAZMFSY, which is shipped in the QSYS
library. Various mail server framework functions cause

Table B-3. Type SY Journal Entries for the MSF System Level Events Table Changes
Field Format Description
Entry length Zoned(5,0) Total length of the journal entry, including the entry length field.
Sequence number Zoned(10,0) Applied to each journal entry. Initially set to 1 for each new or restored journal. Reset when
a new receiver is attached.
Journal code Char(1) Always S for MSF entries.
Entry type Char(2) Always SY for MSF system level events entries.
Date stamp Char(6) The system date that the entry was made.
Time stamp Zoned(6,0) The system time that the entry was made.
(Reserved area) Char(95)
Job name Char(10) The name of the job that caused the entry to occur.
User name Char(10) The user-profile name associated with the job.
Job number Zoned(6,0) The job number.
Program name Char(8) The name of the MSF program that made the journal entry.
Function identifier Char(1) Function that was being performed when the entry was made. The possible values are:
1 STRMSF command started (QMSF jobs)
2 Internal tables initialized (part of STRMSF command function)
3 Internal queues initialized (part of STRMSF command function)
4 Space pool index created and initialized
5 ENDMSF command started (ended QMSF jobs)
6 Damaged or destroyed internal space found
7 Message destroyed by using DATAAREA QZMFKQ value
8 Abnormal IPL destroyed in internal MSF space index
9 MSF clean up functions (part of Reclaim Storage (RCLSTG) command) started
A MSF space clean up function started
B MSF clean up functions completed
C MSF reclaim storage function ended
Data length Zoned(5,0) The length of the logged data.
Logged data Char(256) The data logged by MSF when the function identifier is:
6 32 character MSF message ID
7 32 character MSF message ID followed by total number of internal entries
destroyed

Figure B-9 on page B-6 shows an example of how the fields

defined for QZMF journal entries are mapped to the dis-
played data.

B-8 AnyMail/400 Mail Server Framework Support V4

Format for MSF Configuration Changes
(CF)
The entry for MSF configuration change is mapped by the
database file record, ZMFXCFFT, which represents the
change made. This record is defined by physical file
QAZMFCF, which is shipped in the QSYS library. The
CF-type journal entry contains the following information:

Table B-4. Type CF Journal Entries for MSF Configuration Changes

Field Format Description
Entry length Zoned(5,0) Total length of the journal entry, including the entry length field.
Sequence number Zoned(10,0) Applied to each journal entry. Initially set to 1 for each new or restored journal. Reset when
a new receiver is attached.
Journal code Char(1) Always S for MSF entries.
Entry type Char(2) Always CF for MSF configuration change entries.
Date stamp Char(6) The system date that the entry was made.
Time stamp Zoned(6,0) The system time that the entry was made.
(Reserved area) Char(95)
Job name Char(10) The name of the job that caused the entry to occur.
User name Char(10) The user profile name associated with the job.
Job number Zoned(6,0) The job number.
Program name Char(8) The name of the MSF program that made the journal entry.
Function identifier Char(1) Function that was being performed when the entry was made. The possible values are:
1 MSF data type configured added to configuration database by QZMFCOPN
program. MSF type tables initialized with shipped type definitions.
2 Reserved.
3 Added configuration to the configuration database. New MSF data type defined by
using the QzmfAddMailCfg API.
4 Configuration removed from the configuration database. MSF data type removed
by using the QzmfRmvMailCfg API.
5 Exit program removed from MSF exit point.
6 Exit program added to MSF exit point, except QIBM_QZMFMSF_VLD_TYP and
QIBM_QZMFMSF_TRK_CHG.
7 Exit program added to QIBM_QZMFMSF_VLD_TYP or
QIBM_QZMFMSF_TRK_CHG.
A Install program started.
B Install program ended.
C Type not deleted during install.
D Type not added during install.
E Exit point program not deleted during install.
F Exit point program not added during install.
Data length Zoned(5,0) The length of the logged data.
Logged data Char(256) The data logged by MSF when the function identifier is:
1 The record for the MSF data type that was added.
3 The record for the MSF data type that was added.
4 The record for the MSF data type that was removed.
5 The information about the MSF exit point program that was removed during install.
6 The information about the MSF exit point program that was added during install.
7 The information about the MSF exit point program that was added during install.
C The record for the MSF data type that the install program failed to delete.
D The record for the MSF data type that the install program failed to add.
E The information about the MSF exit point program that the install program failed to
delete.
F The information about the MSF exit point program that the install program failed to
add.

Appendix B. MSF Journal Logging and Journal Formats B-9

Figure B-9 on page B-6 shows an example of how the fields
defined for QZMF journal entries are mapped to the dis-
played data.

B-10 AnyMail/400 Mail Server Framework Support V4

Figure B-10 shows an example of how the A function identi- Data
fier field is mapped to the displayed data. Function Type Type
Identifier Group Value

Function
Identifier

RV3W178-1

Type
Name

RV3W176-1 Figure B-12. Function Identifier D - Example

Figure B-10. Function Identifier A - Example
Figure B-13 shows an example of how an F function identi-
Figure B-11 shows an example of how an B function identi- fier field is mapped to the displayed data. The E and F func-
fier field is mapped to the displayed data. tion identifier entries look identical.

Function Function Exit

Identifier Identifier Point

RV3W179-1

Exit Exit Exit Exit

RV3W177-1 Point Program Point Point
Format Number Program Program
Figure B-11. Function Identifier B - Example
Library

Figure B-12 shows an example of how an D function identi- Figure B-13. Function Identifier F - Example
fier field is mapped to the displayed data. The C and D func-
tion identifier entries look identical.

Appendix B. MSF Journal Logging and Journal Formats B-11

B-12 AnyMail/400 Mail Server Framework Support V4
Appendix C. Preregistered Exit Point Programs
The exit point programs shipped with MSF are preregistered
when you install your AS/400 system. These preregistered à Work with Exit Programs
ð
programs are shown in Figure C-1. Exit point: QIBM_QZMFMSF_ADR_RSL Format: MSFFð1ðð

Type options, press Enter.

Exit 1=Add 4=Remove 5=Display 1ð=Replace
Exit Program
Program Exit
Number Program Exit
Opt Number Program Library
___ _________ð_
Mail Server Framework ___ 1ððð QZDSNPAD QSYS
___ 2ððð QZMFSNPA QSYS

List Expansion QSYS/QZDSNPLE 1000

Bottom
QSYS/QZMFSNPA 2000 Command
===>
Address Resolution QSYS/QZDSNPAD 1000 F3=Exit F4=Prompt F5=Refresh F9=Retrieve F12=Cancel

á ñ
Local Delivery QSYS/QZDSNPLD 1000
Figure C-2. Address Resolution Exit Point Programs

Message Forwarding QSYS/QZDSNPMF 1000

Exit Program QZMFSNPA

QSYS/QZDSNPND 1000
For those recipients of a MSF message who do not have a
Non-Delivery
MSF data type assigned by previous address resolution exit
point programs, a preregistered default exit point program is
called. This preregistered address resolution exit point
Attachment Management QSYS/QZDSNPAM 1000
program, QZMFSNPA, changes the recipient list addresses
to their preferred addresses and address types, as specified
in the system distribution directory. The exit point program
Accounting QSYS/QZDSNPAC 1000
uses the directory search API (QOKSCHD) to determine the
preferred addresses and address types of the message
RV3W174-4 recipients. An example is shown in Figure C-3 on page C-2.
Figure C-1. Exit Point Programs Shipped with MSF
Note
On the Work with Registration Information display, type 8 in For any exit point program, including QZMFSNPA, to use
the Opt Field next to the address resolution exit point, the directory search API (QOKSCHD), the directory must
QIBM_QZMFMSF_ADR_RSL. The Work with Exit Programs allow searches. The Change System Directory Attributes
display containing information about the address resolution (CHGSYSDIRA) command can be used to specify that
exit point is shown, as in Figure C-2. The two programs, directory searches are allowed by changing the ALWSCH
QZDSNPAD and QZMFSNPA, are the address resolution parameter to *YES. If directory searches are not
handler and the switcher programs. allowed, QZMFSNPA issues error message CPFAF90,
which indicates the QMSF job will end.

See the SNA Distribution Services book for more information

about preferred addresses.

 Copyright IBM Corp. 1997 C-1

 QSYS/QZMFSNPA Called
for any Data Type Address

Address Resolution Exit Point

Address Data Type
01A1 and Address1
01A1 9999
01A5 Directory Search Directory
Preferred Address Data
Address1 Data Type 01A5
Address2
Address Change Mail Message
and Address2

Recipient List

Recipient Address and

Address Data Type Changed RV3W173-3

Figure C-3. Example of Preferred Address Resolution

C-2 AnyMail/400 Mail Server Framework Support V4

Appendix D. How Mail Server Framework Works with SNADS, Object
Distribution, and OfficeVision
This appendix describes how SNA distribution services has been organized differently. Applications that use
(SNADS), as shipped by IBM, uses the mail server frame- SNADS, such as OfficeVision and Object Distribution, are not
work (MSF) to route and distribute messages asynchro- affected by this change to SNADS. Figure D-1 on page D-2
nously. The function of SNADS has not changed because of shows the current organization of SNADS.
the introduction of the MSF. The SNADS routing function

 Copyright IBM Corp. 1997 D-1

AS/400 Mail Server OfficeVision/400 Object Distribution
and API Applications
Applications

SNDNETxxx/
SNDDST/RCVDST
RCVNETxxx

Object
Distribution List Office Distribute OfficeVision
Distribution
Expansion Function Receive
Receive

SNADS Distribute SNADS Receive

Function Function

API

Create Mail Message

Function

SNADS List
List Expansion List Expansion
Expansion Function

System
Address Resolution SNADS Routing Distribution
Address Resolution Directory
Function

SNADS
Local Delivery Local Delivery Local Delivery
Function

SNADS Message
Message Forwarding Message Forwarding Forwarding
Function

Non-Delivery SNADS Reporting

Non-Delivery Function

Attachment Management SNADS FSO

File Server
Attachment Management Management Object
Function

SNADS
Accounting SNADS Logging Journal
Accounting
Function

SNADS Queuing
Function

SNADS Distribution Queues

SNADS SNADS SNADS SNADS

SNADS Inbound Outbound Outbound Outbound
Gateway Gateway Gateway Gateway
Function
X.400 VM/MVS SMTP

RV3W159-4

Figure D-1. SNADS Overview

D-2 AnyMail/400 Mail Server Framework Support V4

The routing function of SNADS occurs within the exit point preference is stored for the recipient. If the preference is
programs that are configured for the mail server framework either the ATDGNDEN or the ATRGEDGE address type,
exit points. Only seven of the ten available exit points are then this exit program continues to route the recipient. If the
used by SNADS. preference is any other address type, this exit program does
not route the recipient, and lets another address resolution
Ÿ List expansion
exit program process it.
Ÿ Address resolution
Ÿ Local delivery
After determining the correct route for a recipient, the
Ÿ Message forwarding
SNADS address resolution exit program assigns a message
Ÿ Non-delivery
type and status (local or remote) for that recipient. The
Ÿ Attachment management
SNADS message types include:
Ÿ Accounting
Type Description
MTDIA OfficeVision/400 type
List Expansion MTOBJDST Object Distribution type
MTDLS Document Library Services type
The SNADS exit program for list expansion expands a distri-
MTDSNX Distributed System Node Executive type
bution list into a recipient list containing SNADS recipients.
This exit program accepts the following address type:
Type Description
Local Delivery
ATDDLIST Distribution list
The SNADS exit program for local delivery routes a message
to the local Object Distribution or OV/400 applications for all
Address Resolution local recipients. This exit program accepts the following
message types:
In the exit point program for address resolution, SNADS
Type Description
accesses the system distribution directory, the SNADS
MTDIA OfficeVision/400 type
routing table, the SNADS distribution queues table, and the
MTOBJDST Object Distribution type
SNADS secondary system name table to determine the
MTDLS Document Library Services type
correct route of a message recipient. This exit program
MTDSNX Distributed System Node Executive type
accepts the following address types:
Type Description
ATDGNDEN Address/User ID
Message Forwarding
ATRGEDGE System name/Address/User ID (fully qualified
The SNADS exit program for message forwarding routes a
recipient name)
message to the appropriate SNADS distribution queue for all
ATRGNREN Group name/System name
remote recipients. This exit program accepts the following
ATDDLIST Distribution list
message types:
Information that is stored in the system distribution directory Type Description
(for example, preferred address and mail service level) can MTDIA OfficeVision/400 type
be used in determining the message type of a recipient. Pre- MTOBJDST Object Distribution type
ferred address is generally used to determine the address MTDLS Document Library Services type
type of a remote recipient (for example, TCP/IP or X.400). MTDSNX Distributed System Node Executive type
Mail service level is used to decide how the message will be
stored for a local recipient. If the address is stored in the
system distribution directory, the directory search API
Non-Delivery
(QOKSCHD) can be used to query information needed by The SNADS exit program for non-delivery creates a status
the user. message for those recipients who had routing or delivery
errors. This exit program then uses the Create Mail
If a recipient is local, the SNADS address resolution exit
Message API to put the new status message into the mail
program checks the system directory to see what the mail
server framework to be routed. This exit program accepts
service level is for that recipient. If the mail service level is
the following message types:
user index, this exit program continues to process the recip-
ient. If the mail service level is system message store or Type Description
other mail service, this exit program does not route the recip- MTDIA OfficeVision/400 type
ient, and lets another address resolution exit program MTOBJDST Object Distribution type
process it. MTDLS Document Library Services type
MTDSNX Distributed System Node Executive type
If a recipient is remote, the SNADS address resolution exit
program checks the system directory to see what address

Appendix D. How Mail Server Framework Works with SNADS, Object Distribution, and OfficeVision D-3
Attachment Management Accounting
The SNADS exit program for attachment management The SNADS exit program for accounting makes entries in the
manages the SNADS file server object attached to the QSNADS journal for any messages that are processed. The
message, if there is one. File server objects include files, function types or entry types that can be journaled by this
spool files, or network jobs sent by object distribution, or doc- exit program include the following:
uments or notes sent by OV/400. This exit program accepts
*RTR/*NRM
the following message types:
*RTR/*ERR
Type Description
MTDIA OfficeVision/400 type The Display Distribution Log (DSPDSTLOG) command can
MTOBJDST Object Distribution type be used to view the SNADS journal entries. See the SNA
MTDLS Document Library Services type Distribution Services book for more information on SNADS
MTDSNX Distributed System Node Executive type journaling.

D-4 AnyMail/400 Mail Server Framework Support V4

Bibliography
The IBM publications listed here provide additional informa- Ÿ Publications Reference, SC41-5003
tion about topics described or referred to in this book. These identifies and describes the printed and online informa-
books are listed with their full title, order number, and version tion in the AS/400 library, and also lists other publica-
and release number. tions about the AS/400 system. Includes
cross-reference information between the current library
Ÿ AnyMail/400 Mail Server Framework Developer Guide,
and the previous version library.
GG24-4449
provides the programmer technical details to understand Ÿ SNA Distribution Services, SC41-5410
how the AnyMail/400 mail server framework (MSF) provides the system operator or system administrator
works. It provides information about how to write pro- with information about configuring a network for Systems
grams that either create MSF messages or how to act Network Architecture distribution services (SNADS) and
on MSF messages as MSF exit point programs. the Virtual Machine/Multiple Virtual Storage (VM/MVS)
bridge. In addition, object distribution functions and doc-
This book is written to assist AS/400 programmers who
ument library and system distribution directory services
use MSF to write mail messaging applications. Its scope
are discussed.
includes a description of MSF, designing MSF applica-
tions, configuring MSF, MSF operations, and MSF Ÿ System API Reference, SC41-5801
problem determination. provides information for those customers or systems
houses that wish to:
Ÿ CL Reference, SC41-5722
provides the application programmer with a description – Write their own communications protocol on the
of the AS/400 control language (CL) and its commands. AS/400 system to connect to systems in ways not
Each command description includes a syntax diagram, currently possible with IBM communications support,
parameters, default values, keywords, and an example. or
– Connect programmable work stations (PWSs)
Ÿ Communications Configuration, SC41-5401
through a specialized Virtual Terminal Manager
contains general configuration information including
interface.
detailed descriptions of network server, network inter-
face, line, controller, device, mode, class-of-service, and Ÿ TCP/IP Configuration and Reference, SC41-5420
NetBIOS descriptions, and configuration lists and con- provides information for configuring and using AS/400
nection lists. TCP/IP support. The applications included are Network
Status (NETSTAT), Packet InterNet Groper (PING),
Ÿ Alerts Support, SC41-5413
TELNET, File Transfer Protocol (FTP), Simple Mail
provides the system operator, programmer, or system
Transfer Protocol (SMTP), line printer requester (LPR),
administrator with information for configuring and using
and line printer daemon (LPD). The TCP and UDP
AS/400 Alerts support. It discusses how to allow end-
Pascal application program interface (API) is also dis-
user applications to create alerts, control the creating
cussed.
and sending of alert messages for problem manage-
ment, and perform central site problem analysis for the Ÿ Work Management, SC41-5306
AS/400 systems in the network. provides information about creating and using subsys-
tems.

 Copyright IBM Corp. 1997 H-1

H-2 AnyMail/400 Mail Server Framework Support V4
Index
data type (continued)
Special Characters rules 5-4
*TYPE1 B-1 description considerations 2-3
displaying
journal B-1
A
accounting exit point 4-9
Add Mail Server Framework Configuration E
(QzmfAddMailCfg) API A-1 End Mail Server Framework (ENDMSF) command 2-1
adding types 3-2 ending MSF jobs 2-2
address resolution exit point 4-4 ENDMSF (End Mail Server Framework) command 2-1
AnyMail/400 1-1 envelope
API (application program interface) definition 4-6
definition 1-1 generic 5-3
mail server framework A-1 list 5-3
attachment conversion exit point 4-6 envelope processing exit point 4-6
attachment management exit point 4-9 ER journal entry B-1
attachment reference error messages 2-3
list 5-3 error recovery 2-3
example
A function identifier B-11
B B function identifier B-11
benefits vii
D function identifier B-11
bibliography H-1
exit point program 3-1
F function identifier B-11
C journal entry fields B-6
registered exit point program 3-1
CF journal entry B-1
Change Mail Message (QzmfChgMailMsg) API A-2 registering a program 3-1
code S B-1 exit point
command, CL See also System API Reference
End Mail Server Framework (ENDMSF) 2-1 accounting 4-9
ENDMSF (End Mail Server Framework) 2-1 address resolution 4-4
Start Mail Server Framework (STRMSF) 2-1 attachment conversion 4-6
STRMSF (Start Mail Server Framework) 2-1 attachment management 4-9
Complete Creation Sequence (QzmfCrtCmpMailMsg) definition 1-1, 4-1
API A-2 envelope processing 4-6
configuration example 4-1
considerations 3-1 list expansion 4-4
configuration APIs A-1 local delivery 4-8
considerations message forwarding 4-8
configuration 3-2 non-delivery 4-9
description 2-3 security and authority 4-7
operations 2-1 exit point program
Create Mail Message (QzmfCrtMailMsg) API A-1 addressing group 4-3
definition 4-1
delivery group 4-3
D management group 4-3
data type multiple 4-2
address 5-4 overview 4-2
attachment reference 5-4 pre-delivery processing group 4-3
definition 5-4 preregistered C-1
envelope 5-4 QZMFSNPA C-1
message 5-4 registered 3-1

 Copyright IBM Corp. 1997 X-1

exit point program (continued) local delivery exit point 4-8
snap-in call A-2
snap-in definition 1-1
track mail message changes A-2 M
validate data field A-2 mail server framework (MSF)
exit program adding types 3-2
definition 1-1 API A-1
benefits vii
configuration considerations 3-2
F definition 1-1
formatting ending 2-1
QZMF journal B-1 introduction 1-1
framework types managing jobs 2-2
adding 3-2 starting 2-1
using 2-1
mail server framework API A-1
G message
generic envelope type 5-3 no log entries B-3
message APIs A-1
message forwarding exit point 4-8
J message identifier 5-3
jobs, MSF
message lists 5-2
managing 2-2
MSF (mail server framework)
journal
adding types 3-2
displaying B-1
API A-1
entries
benefits vii
displaying QZMF B-1
configuration considerations 3-2
type CF B-4, B-9
definition 1-1
type ER B-3, B-7
ending 2-1
type LG B-3, B-5
introduction 1-1
type SY B-3, B-8
managing jobs 2-2
QZMF
starting 2-1
configuration changes (CF) B-9
using 2-1
displaying B-1
MSF API A-1
error entry (ER) B-7
formatting B-1
logging (LG) B-5 N
support B-1 non-delivery exit point 4-9
system level events table (SY) B-8
receiver
full B-1 O
new B-9 object distribution D-1
OfficeVision D-1
operations considerations 2-1
L original recipient
LG journal entry B-1 list 5-2
list originator
attachment reference 5-3 list 5-2
envelope 5-3 outfile format (OUTFILFMT) parameter B-1
original recipient 5-2 OUTFILFMT (outfile format) parameter B-1
originator 5-2
recipient 5-2
report-on 5-3 P
report-to 5-3 preregistered exit point program C-1
list expansion exit point 4-4 program
List Mail Server Framework Configuration registered 3-1
(QzmfLstMailCfg) API A-1

X-2 AnyMail/400 Mail Server Framework Support V4

programming example
See AnyMail/400 Mail Server Framework Developer Guide S
publications, list of H-1 S code B-1
security and authority exit point 4-7
SNADS
Q graphic overview D-1
QSYSWRK routing function D-3
jobs 2-2 using 7 exit points D-3
subsystem 2-2 using mail server framework D-1
Query Mail Message Identifier (QzmfQryMailMsgId) snap-in
API A-2 definition 1-1, 4-1
QZMF journal B-1 example 4-1
QzmfAddMailCfg (Add Mail Server Framework Configura- Snap-In Call Exit Point Program A-2
tion) API A-1 Start Mail Server Framework (STRMSF) command 2-1
QzmfChgMailMsg (Change Mail Message) API A-2 starting MSF jobs 2-2
QzmfCrtCmpMailMsg (Complete Creation Sequence) STRMSF (Start Mail Server Framework) command 2-1
API A-2 SY journal entry B-1
QzmfCrtMailMsg (Create Mail Message) API A-1
QzmfLstMailCfg (List Mail Server Framework Configura-
tion) API A-1 T
QzmfQryMailMsgId (Query Mail Message Identifier) Track Mail Message Changes Exit Point Program A-2
API A-2 trouble shooting 2-3
QzmfRmvMailCfg (Remove Mail Server Framework Con- type
figuration) API A-1 journal entries
QzmfRmvRsvMailMsgId (Remove Reserved Mail Message CF B-9
Identifier) API A-2 ER B-7
QzmfRsvMailMsgId (Reserve Mail Message Identifier) LG B-5
API A-2 SY B-8
QzmfRtvMailMsg (Retrieve Mail Message) API A-2 MSF data 3-2, 5-4
QZMFSNPA exit point program C-1
V
R Validate Data Field Exit Point Program A-2
recipient
list 5-2
registering exit point programs 3-1
related printed information H-1
Remove Mail Server Framework Configuration
(QzmfRmvMailCfg) API A-1
Remove Reserved Mail Message Identifier
(QzmfRmvRsvMailMsgId) API A-2
report-on
list 5-3
report-to
list 5-3
Reserve Mail Message Identifier (QzmfRsvMailMsgId)
API A-2
Retrieve Mail Message (QzmfRtvMailMsg) API A-2
routing function
See SNA Distribution Services
routing table
See SNA Distribution Services
rules
data type definitions 5-4

Index X-3
Reader Comments—We'd Like to Hear from You!
AS/400 Advanced Series
AnyMail/400 Mail Server
Framework Support
Version 4
Publication No. SC41-5411-00

Overall, how would you rate this manual?

Very
Very Dissatis-
Satisfied Dissatis-
Satisfied fied
fied
Overall satisfaction

How satisfied are you that the information in this manual is:

Accurate
Complete
Easy to find
Easy to understand
Well organized
Applicable to your tasks
THANK YOU!

Please tell us how we can improve this manual:

May we contact you to discuss your responses? __ Yes __ No

Phone: (____) ___________ Fax: (____) ___________ Internet: ___________
To return this form:
Ÿ Mail it
Ÿ Fax it
United States and Canada: 800+937-3430
Other countries: (+1)+507+253-5192
Ÿ Hand it to your IBM representative.
Note that IBM may use or distribute the responses to this form without obligation.

Name Address

Company or Organization

Phone No.
 Cut or Fold
Reader Comments—We'd Like to Hear from You!

IBM
Along Line
SC41-5411-00


Fold and Tape Please do not staple Fold and Tape

NO POSTAGE
NECESSARY
IF MAILED IN THE
UNITED STATES

BUSINESS REPLY MAIL

FIRST-CLASS MAIL PERMIT NO. 40 ARMONK, NEW YORK

POSTAGE WILL BE PAID BY ADDRESSEE

ATTN DEPT 542 IDCLERK

IBM CORPORATION
3605 HWY 52 N
ROCHESTER MN 55901-9986

Fold and Tape Please do not staple Fold and Tape

Cut or Fold
SC41-5411-00 Along Line
IBM 

Printed in the United States of America

on recycled paper containing 10%
recovered post-consumer fiber.

SC41-5411-ðð
Spine information:

AnyMail/400 Mail Server

IBM AS/400 Advanced Series Framework Support Version 4