Messaging and Directory Server software used around the world in the Government, Military, Aviation and Commercial sectors.

Documentation

Isode R14.3v0 P7/P3 TCL API documentation

August 2008

Copyright © 2008 Isode Limited, London, U.K

X.400 Tcl API - Example Applications

• Application Features
• Submission via the Message Store (P7)
• Retrieval from the Message Store (P7)
• Submission directly to the MTA (P3)
  • Connection to the MTA
• Retrieval directly from the MTA (P3)
  • Connection to the MTA
• Running the Applications
  • Unix
  • Windows
• Correlation of messages, delivery reports and IPNs

Application Features

These examples show how to do the following using the Tcl API

• submit X.400 messages,
• submit delivery reports
• submit IPNs
• retrieve X.400 messages
• retrieve delivery reports
• retrieve IPNs
  

Note that the examples used in this text will work with the values configured by the quickconfig program.

However you must configure 3 variables. So If your quickconfig configuration was running on "hay.isode.net" using a country code of "GB" you should set the following:

• hostname - "hay"
• domainname - "isode.net"
• country - "GB"

Configuring the Applications

You can set the default values in the session object in the same way as the C API. For example:

      
$c priority 94
$m original_encoded_information_types ia5-text

In the script, the variables which be usefully configured are between the lines

# Start configuration
[...]
# End

Some of the values set are optional, but appear in the example to show you how they are set.

You must configure whether you are using P3 or P7

set connection_type "p7"

Submission via the Message Store (P7)

• x400_ms_send_message.tcl - Sends a simple text message to the Message Store, to one or more addresses
• x400_ms_send_read_receipt.tcl - Sends a IPN (read receipt) to an address
• x400_ms_send_non_read_receipt.tcl - Sends a IPN (non read receipt) to an address

Make sure that the users that are referred to in originator and recipient variables exist and the MTA knows how to route a message to them. To check the O/R address use the command line utility (or test user in EMMA)

# ckadr -x "<O/R address>" 

By default quickconfig will setup suitable users for you.

You may wish to configure recipient2 to be an undeliverable message, you can cause Non-delivery reports to be generated. NB if the recipient is non-delivered by the MTA associated with the store the submission will fail, so you should arrange for the recipient to be non-delivered by an MTA to which the message is relayed to generate the non-delivery report).

Retrieval from the Message Store (P7)

• x400_ms_rcv_message.tcl [all] - Receives one (or all) messages that are waiting for a user in the Message Store, and shows the content on the screen. It can deal with simple text messages, delivery reports and IPNs.

Submission directly to the MTA (P3)

Connection to the MTA

This is configured in a similar way to P7 submission, except for the connection_type variable:

set connection_type "p3"

The Presentation Address of the P3 Channel in the MTA, includes the Internet address of the machine where is running. Check in EMMA the value used by your Message Store. To set the value change the following line (with the correct IP address or hostname of your store):

set pa "\"593\"/Internet=192.168.1.22"

The Credentials of the user are configured as a Message Store User (even though messages are being submitted and retrieved directly from the P3 channel). The credentials comprise an O/RName (DN and O/R address) and a password. Check in EMMA the value used by your Message Store User.

The following entries are used to configure credentials. To make the originator the same as the bound user, set the O/R address as follows:

set user_oraddr $originator

The password of the user that is binding to the P3 channel to send or receive messages must be entered on the command line. You can check the user's password by editing its properties in EMMA.

set user_password "l1password"

Retrieval directly from the MTA (P3)

Connection to the MTA

This is configured in the same as for P3 Submission, except for the connection_type variable:

set connection_type "p3"

The Presentation Address of the P3 Channel in the MTA, includes the Internet address of the machine where is running. Check in EMMA the value used by your Message Store. To set the value change the following line (with the correct IP address or hostname of your store):

set pa "\"593\"/Internet=192.168.1.22"

The Credentials of the user are configured as a Message Store User (even though messages are being submitted and retrieved directly from the P3 channel). The credentials comprise an O/RName (DN and O/R address) and a password. Check in EMMA the value used by your Message Store User.

The following entries are used to configure credentials. To make the originator the same as the bound user, set the O/R address as follows:

set user_oraddr $originator

The password of the user that is binding to the P3 channel to send or receive messages must be entered on the command line. You can check the user's password by editing its properties in EMMA.

set user_password "l1password"

Running the Applications

Unix

To run the applications you simply run the script from the command line. No arguments are required.

Submitting a message:

  
# ./x400_ms_send_message.tcl
Message Sent:   message_identifier = [/PRMD=TestPRMD/ADMD=TestADMD/C=GB/;dhcp-164.i.1013701-080228.141118]
                message_submission_time=080228141118Z
                ipm_identifier=99999999.9999*/CN=P7User1/OU=Sales/O=dhcp-164/PRMD=TestPRMD/ADMD=TestADMD/C=GB/<cn=Him, c=gb>

Retrieving a message

# ./x400_ms_rcv_message.tcl

Waiting for 60 seconds or for a message to arrive
done
******************* Read a message *********************
Message sequence number = 52
***Envelope attributes***
message_identifier = [/PRMD=TestPRMD/ADMD=TestADMD/C=GB/;dhcp-164.i.1018201-080228.141422]
content_type = 22
content_identifier = My-Test
original_encoded_information_types = ia5-text
priority = 1
message_submission_time = 080228141422Z
message_delivery_time = 080228141422Z
originator_return_address = /CN=P7User1/OU=Sales/O=dhcp-164/PRMD=TestPRMD/ADMD=TestADMD/C=GB/
or_address = /CN=P7User1/OU=Sales/O=dhcp-164/PRMD=TestPRMD/ADMD=TestADMD/C=GB/
start of DL expansion
Command failed: Missing attribute in message
***Recipients***
***recip_primary number 1***
or_address = /CN=P7User2/OU=Sales/O=dhcp-164/PRMD=TestPRMD/ADMD=TestADMD/C=GB/
country_name = GB
admd_name = TestADMD
prmd_name = TestPRMD
organization_name = dhcp-164
organizational_unit_name_1 = Sales
common_name = P7User2
reply_requested = 0
***header_originator number 1***
or_address = /CN=P7User1/OU=Sales/O=dhcp-164/PRMD=TestPRMD/ADMD=TestADMD/C=GB/
country_name = GB
admd_name = TestADMD
prmd_name = TestPRMD
organization_name = dhcp-164
organizational_unit_name_1 = Sales
common_name = P7User1
***recip_envelope number 1***
or_address = /CN=P7User2/OU=Sales/O=dhcp-164/PRMD=TestPRMD/ADMD=TestADMD/C=GB/
country_name = GB
admd_name = TestADMD
prmd_name = TestPRMD
organization_name = dhcp-164
organizational_unit_name_1 = Sales
common_name = P7User2
responsibility = 1
IPN attribute '0'
***Content attributes***
ipm_identifier = 99999999.9999*/CN=P7User1/OU=Sales/O=dhcp-164/PRMD=TestPRMD/ADMD=TestADMD/C=GB/<cn=Him,c=gb>
subject = Test of sending from Tcl
replied_to_identifier = 1064840642.7877*/I=AN/S=Other/O=Isode/PRMD=Isode/ADMD= /C=GB/<cn=Him,c=gb>
obsoleted_ipms = 10.0001*/I=AN/S=Other/O=Isode/PRMD=Isode/ADMD= /C=GB/<c=gb> 10.0002*/I=AN/S=Other/O=Isode/PRMD=Isode/ADMD= /C=GB/<c=gb>
related_ipms = 10.0003*/I=AN/S=Other/O=Isode/PRMD=Isode/ADMD= /C=GB/<c=gb> 10.0004*/I=AN/S=Other/O=Isode/PRMD=Isode/ADMD= /C=GB/<c=gb>
expiry_time = 080929140419+1100
reply_time = 080929140419+1100
importance = 2
sensitivity = 1
num_attachments = 1
ia5text = Body of the message sent from the Tcl script

Windows

To run the applications you run tclsh to source the script from the command line. No arguments are required.

Submitting a message:

# tclsh -s x400_ms_send_message.tcl
Message Sent:   message_identifier = [/PRMD=TestPRMD/ADMD=TestADMD/C=GB/;dhcp-164.i.1013701-080228.141118]
                message_submission_time=080228141118Z
                ipm_identifier=99999999.9999*/CN=P7User1/OU=Sales/O=dhcp-164/PRMD=TestPRMD/ADMD=TestADMD/C=GB/<cn=Him, c=gb>

Retrieving a message

# tclsh -s x400_ms_receive_message.tcl 

Waiting for 60 seconds or for a message to arrive
done
******************* Read a message *********************
Message sequence number = 52
***Envelope attributes***
message_identifier = [/PRMD=TestPRMD/ADMD=TestADMD/C=GB/;dhcp-164.i.1018201-080228.141422]
content_type = 22
content_identifier = My-Test
original_encoded_information_types = ia5-text
priority = 1
message_submission_time = 080228141422Z
message_delivery_time = 080228141422Z
originator_return_address = /CN=P7User1/OU=Sales/O=dhcp-164/PRMD=TestPRMD/ADMD=TestADMD/C=GB/
or_address = /CN=P7User1/OU=Sales/O=dhcp-164/PRMD=TestPRMD/ADMD=TestADMD/C=GB/
start of DL expansion
Command failed: Missing attribute in message
***Recipients***
***recip_primary number 1***
or_address = /CN=P7User2/OU=Sales/O=dhcp-164/PRMD=TestPRMD/ADMD=TestADMD/C=GB/
country_name = GB
admd_name = TestADMD
prmd_name = TestPRMD
organization_name = dhcp-164
organizational_unit_name_1 = Sales
common_name = P7User2
reply_requested = 0
***header_originator number 1***
or_address = /CN=P7User1/OU=Sales/O=dhcp-164/PRMD=TestPRMD/ADMD=TestADMD/C=GB/
country_name = GB
admd_name = TestADMD
prmd_name = TestPRMD
organization_name = dhcp-164
organizational_unit_name_1 = Sales
common_name = P7User1
***recip_envelope number 1***
or_address = /CN=P7User2/OU=Sales/O=dhcp-164/PRMD=TestPRMD/ADMD=TestADMD/C=GB/
country_name = GB
admd_name = TestADMD
prmd_name = TestPRMD
organization_name = dhcp-164
organizational_unit_name_1 = Sales
common_name = P7User2
responsibility = 1
IPN attribute '0'
***Content attributes***
ipm_identifier = 99999999.9999*/CN=P7User1/OU=Sales/O=dhcp-164/PRMD=TestPRMD/ADMD=TestADMD/C=GB/<cn=Him,c=gb>
subject = Test of sending from Tcl
replied_to_identifier = 1064840642.7877*/I=AN/S=Other/O=Isode/PRMD=Isode/ADMD= /C=GB/<cn=Him,c=gb>
obsoleted_ipms = 10.0001*/I=AN/S=Other/O=Isode/PRMD=Isode/ADMD= /C=GB/<c=gb> 10.0002*/I=AN/S=Other/O=Isode/PRMD=Isode/ADMD= /C=GB/<c=gb>
related_ipms = 10.0003*/I=AN/S=Other/O=Isode/PRMD=Isode/ADMD= /C=GB/<c=gb> 10.0004*/I=AN/S=Other/O=Isode/PRMD=Isode/ADMD= /C=GB/<c=gb>
expiry_time = 080929140419+1100
reply_time = 080929140419+1100
importance = 2
sensitivity = 1
num_attachments = 1
ia5text = Body of the message sent from the Tcl script

Correlation of messages, delivery reports and IPNs

When a message is submitted via the Message Store API the MTA assigns it a message identifier. This value is then returned by the API in the message_identifier attribute of the message object.

When a report is generated by the destination MTA, the value of the original message identifier is set in the subject_identifier of the delivery report, allowing you to correlate the original message with the report.

When the recipient's X.400 user agent reads the message, an IPN should be created, with the message_identifier field set to the message_identifier of the original message.

Please note that the Tcl API example x400_ms_rcv_message.tcl does not generate an IPN when it reads a message.

When a message is transferred-in via the MT API, the message identifier is set by the API user.

When a report is generated by the MT API user, the value of the original message identifier has to be set in the subject_identifier of the delivery report, allowing the recipient to correlate the original message with the report.