MODIFY command: SMTP

The MODIFY SMTP command provides an interactive interface to the SMTP server that allows you to perform the following functions:

Query the operating statistics of the SMTP server
Query the SMTP mail delivery queues
Perform privileged system administration tasks such as shutting down the SMTP server and enabling or disabling various tracing and debugging options

Format


>>-+-MODIFY-+--smtpprocname --,SMSG,--+-DEbug-------------------+-><
   '-F------'                         +-EXpire,ipaddr-----------+   
                                      +-HElp--------------------+   
                                      +-NODebug-----------------+   
                                      +-NOTrace-----------------+   
                                      +-NUMQueue----------------+   
                                      |        .-,MAX=100-----. |   
                                      +-QUeues-+--------------+-+   
                                      |        +-,MAX=*-------+ |   
                                      |        '-,MAX=--lines-' |   
                                      +-SHutdown----------------+   
                                      +-STARTEXIT---------------+   
                                      +-STats-------------------+   
                                      +-STOPEXIT----------------+   
                                      '-TRace-------------------'

Parameters

Tip: The minimum abbreviation for each parameter is shown in uppercase letters.

DEbug: Enables connection debugging and tracing, which sends information to the SMTP DEBUG data set. Specifying this parameter has the same effect as adding the DEBUG statement to the SMTP configuration data set (SMTPCONF).
EXpire,ipaddr: Causes the domain name resolution for mail queued for delivery to this IP address to expire. SMTP again attempts to resolve the IP addresses for this mail if the retry time interval has not expired.
HElp: Provides a list of valid SMTP SMSG commands.
NODebug: Disables connection debugging and tracing.
NOTrace: Disables resolver tracing.
NUMQueue: Provides the number of mail messages currently queued in SMTP.
QUeues: Provides a list of mail queued on the various SMTP mail processing queues.
SHutdown: Causes the SMTP server to shut down.
STARTEXIT: Causes SMTP to enable a user exit program by issuing the initialization call to the user exit program if one exists. For more information about user exit programs, see the z/OS Communications Server: IP Configuration Guide.
STats: Provides operating statistics about SMTP server events that have occurred since the SMTP server was started.
STOPEXIT: Causes SMTP to disable a currently running user exit program by issuing the termination call to the user exit program if one exists. For more information about user exit programs, see the z/OS Communications Server: IP Configuration Guide.
TRace: Enables resolver tracing. The output of the resolver trace is sent to the SMTP console. The result is the same as adding TRACE RESOLVER to the TCPIP.DATA data set.
MAX: Limits the number of lines that are displayed to the MVS™ operator console for the QUeues report. Valid values are in the range 1 – 65 533. An asterisk (*) causes all output lines up to line 65 533 to be displayed. The default value is 100.

Examples

MODIFY SMTP,SMSG,DEBUG
EZA5597I SMSG DEBUG Output - Session Debugging Enabled 
  
MODIFY SMTP,EXPIRE,123.123.123.123 
EZA5598I SMSG EXPIRE Output - 123.123.123.123 - Mail queued for re-resolution

MODIFY SMTP,SMSG,HELP
EZA5593I SMSG HELP Output 376                                         
Valid SMSG Commands:                                                  
QUeues,max=xxxx  - for mail queue lengths                             
NUMQueue - for total number of mail messages currently queued         
STats    - for operating statistics                                   
HElp     - to get this message                                        
TRace    - to enable resolver tracing                                 
NOTrace  - to disable resolver tracing                                
DEbug    - to enable session debugging                                
NODebug  - to disable session debugging                               
EXpire,a.b.c.d - to expire the domain name resolution for mail queued 
                 for delivery to this IP address                      
SHutdown - to terminate the SMTP server                               
STARTEXIT- start/restart the user exit                                
STOPEXIT - stop the user exit                                                                   
  
       
MODIFY SMTP,NODEBUG
EZA5599I SMSG NODEBUG Output - Session Debugging Disabled 

MODIFY SMTP,NOTRACE
EZA5654I SMSG NOTRACE Output -  Resolver Tracing Disabled

MODIFY SMTP,SMSG,NUMQUEUE
EZA5596I SMSG NUMQUEUE Output -  Current Number of Mail Queued is 50

MODIFY SMTP,SMSG,QUEUE
EZA5594I SMSG QUEUE Output            
----- Mail Queues -----                      
Spool Queue        : 0      
R: xxx.xxx.xxx.xxx : 1 HostName.DomainName                     
Undeliverable Queue: 0                       
--- Resolver Queues ---                      
Process Queue:       0
Send Queue:          0
Wait Queue:          0
Retry Queue:         0
Completed Queue:     0
Error Queue:         0

Spool Queue

Contains mail that is destined for recipients on the local MVS system, or for recipients on an NJE system attached to the local MVS system. This queue is generally empty, because SMTP can deliver this mail quickly by spooling it to the local recipient or to the NJE address space for delivery to an NJE network recipient.

Active

Indicates that if SMTP is currently transmitting to a TCP network destination, all the mail queued for that destination is shown to be active. Use the following format:

A: xxx.xxx.xxx.xxx : 1 HostName.DomainName

xxx.xxx.xxx.xxx - The IP address
1 - The number of pieces of mail
HostName.DomainName - The symbolic name

Queued

All mail that arrives over a batch SMTP connection, and mail from TCP connections that is to be forwarded to another TCP network destination through source routing, is placed on the queued list. As soon as SMTP receives resources from the TCP/IP address space, mail that is queued is considered to be active. The format is:

Q: xxx.xxx.xxx.xxx : 1 HostName.DomainName

xxx.xxx.xxx.xxx - The IP address
1 - The number of pieces of mail
HostName.DomainName - The symbolic name

Retry Queue

Mail is placed in this queue after SMTP attempts to transmit mail to each of the TCP network hosts but is unable to either open a connection or to complete delivery over the connection. After the number of minutes specified by the RETRYINT value, mail is promoted from the retry queue to the QUEUED state. For more information about the RETRYINT variable, see the z/OS Communications Server: IP Configuration Reference.

The format is:

R: xxx.xxx.xxx.xxx : 1 HostName.DomainName

xxx.xxx.xxx.xxx - The IP address
1 - The number of pieces of mail
HostName.DomainName - The symbolic name

Undeliverable Queue

Mail is placed in this queue if SMTP cannot deliver mail to a local MVS recipient or to a recipient on the NJE network attached to the local MVS system because spool space on the local MVS system is full.

After spool space has been increased and SMTP has been restarted, delivery attempts are resumed.

Resolver Queues

SMTP uses the following queues for processing queries to the name server. If the SMTP server is configured to use the site tables rather than the name server, these queues are not used. If the queue is empty, the word Empty appears to the right of the queue. If the queue contains queries, the queries appear on separate lines below the queue. However, because of the speed of the SMTP server, the output might indicate that the queue is active without containing any entries. In this case, the word Empty does not appear.

Process Queue: Contains queries waiting to be sent to the SMTP resolver. After the query has been processed, it is moved to the resolver send queue. This queue is typically empty.
Send Queue: Contains queries waiting to be processed by the SMTP resolver. SMTP staggers the number of queries sent by the resolver to prevent overloading the network and the name server.
Wait Queue: Contains queries for which the SMTP resolver is waiting for responses. Queries remain in this queue for the period of time it takes to receive a reply from the name server. If a reply is not received, the queries are removed from this queue after the resolver timeout has occurred, and are placed in the resolver retry queue. If the query is successful, the query is placed in the resolver completed queue.
Tip: The SMTP resolver timeout is specified by the RESOLVERTIMEOUT statement in the TCPIP.DATA data set.
Retry Queue: Contains queries that have previously failed, either because the name server did not reply, or the name server returned a temporary error that forced the SMTP resolver to retry the query. A temporary error occurs if, for example, the name server truncates a packet, or if the name server detects a processing error. The RESOLVERRETRYINT statement specifies the number of minutes SMTP waits before trying the query again. The RETRYAGE statement specifies the number of days SMTP continues to resolve the query before returning the mail to the sender.
Completed Queue: Contains queries that have been resolved and are waiting to be recorded into the mail. After the IP addresses are recorded, SMTP attempts to deliver the mail.
Error Queue: Contains queries that the name server has returned without answers. The corresponding mail message is returned to the sender with an unknown recipient error.

MODIFY SMTP,SHUTDOWN
EZA5655I SMSG SHUTDOWN Output - Stopping SMTP

MODIFY SMTP,STARTEXIT
EZA5656I SMSG STARTEXIT Output - Exit started

MODIFY SMTP,SMSG,STATS

EZA5595I SMSG STATS Output 618                            
Last Up Time:  Sat, 29 Jul 06 17:07:10 EST                
Statistics  : 07/29                                       
From TCP    :     0                                       
From Spool  :   500                                       
BSMTP Logs  :     0                                       
Error Mail  :     0                                       
To Local    :     0                                       
To RSCS     :     0                                       
To TCP      :   500                                       
Passive Opns:     0                                       
Active Opens:   400                                       
--------------------------------                          
Highest num queued: 50                                     
High reached at: Date: Sat, 29 Jul 06 17:07:09 EST

Last Up Time

The date and time that SMTP was last started.

Statistics

Statistics about mail handled by SMTP over the past four days including the following information:

From TCP: Number of pieces of mail that arrived over TCP connections
From Spool: Number of pieces of mail that arrived from spool (local or NJE senders)
BSMTP Logs: Number of pieces of mail generated in response to requests to VERBose batch SMTP connections
Error Mail: Number of pieces of mail generated to return error mail to the sender
To Local: Number of pieces of mail delivered to local recipients
To RSCS: Number of pieces of mail delivered to recipients on the RSCS network
To TCP: Number of pieces of mail delivered to recipients on the TCP/IP network
Passive Opns: Number of TCP connections through which mail was received
Active Opens: Number of TCP connections through which mail was delivered
Highest num queued: Highest number of messages queued in SMTP and the time and date this occurred
High reached at: Date and time that the Highest num queued value was reached

MODIFY SMTP,STOPEXIT
EZA5657I SMSG STOPEXIT Output - Exit Stopped

MODIFY SMTP,TRACE     
EZA5658I SMSG TRACE Output - Resolver Tracing Enabled