Create Mail Message (QzmfCrtMailMsg) API

The Create Mail Message (QzmfCrtMailMsg) API creates a single electronic mail message.

The input to this API is a parameter list which includes an array of message descriptor attributes. Message descriptor attributes define the basic characteristics of the message descriptor such as the format name associated with it, a pointer to it, and its length. Each message descriptor has a common header, which defines such things as the number of entries in the message descriptor and where the first entry is located. Following the common header is a list of individual entries, which contain information that define the message. The format name defines the format of the individual entries in the message descriptor data. The following message descriptor formats are used.

Original recipient entry. An entry that contains the addresses of the original recipients of the message.

Originator entry. An entry that contains the addresses of the originators of the message.

Envelope entry. An entry that defines the format that is used to pass envelopes. An envelope is a string of data representing information about the message, aside from the attachments and its recipients. This may include the text of the message.

Recipient entry. An entry that contains information about the recipient of the message. This includes the address of the recipient. Recipient addresses are reported on when the message cannot be delivered to the recipient.

Reply-to address entry. An entry that contains the address to be replied to.

Report-on address entry. An entry that defines the address to be reported on.

Report-to address entry. An entry that defines an address to be reported to in case errors are encountered delivering messages to a recipient.

Attachment reference entry. A reference to an attachment that is associated with the message. Attachments may include the text of the message.

Authorities and Locks

None.

Required Parameter Group

Mail message identifier

OUTPUT; CHAR(32)

The variable containing a unique message identifier associated with this message. The mail message identifier is composed of characters A through Z and 0 through 9 only. On completion of this API, if a reserved mail message identifier field is not set to blanks, this variable contains the reserved mail message identifier. Otherwise, this field contains the identifier associated with the message created by the API. If an error occurs during processing, the identifier is set to zeros and a notification of the error is made in the error code parameter. See Reserve Mail Message Identifier (QzmfRsvMailMsgId) API for information on reserving mail message identifiers.

Reserved mail message identifier

INPUT; CHAR(32)

The variable containing the reserved mail message identifier associated with this message. If the reserved mail message identifier field is set to blanks, then a unique mail message identifier associated with this message is returned in the mail message identifier field after the API has completed running and has created a message. If the reserved mail message identifier field is not set to blanks, then it is assumed that the field contains a reserved mail message identifier. The reserved mail message identifier is returned in the mail message identifier variable when the API has completed successfully. If the value of the reserved mail message identifier field is not a reserved mail message identifier, then error message CPFAF8B is generated. See Reserve Mail Message Identifier (QzmfRsvMailMsgId) API for information on reserving mail message identifiers.

Creation message type

INPUT; CHAR(4)

The message type that the originator intended to create. This is used to indicate the message type associated with the mail server framework message.

Message descriptor attributes

INPUT; CHAR(*)

An array containing message descriptor attributes entries (see Example of a Message Descriptor for the Create Mail Message (QzmfCrtMailMsg) or Change Mail Message (QzmfChgMailMsg) API). A message descriptor attributes entry is required for each of the following message descriptors:

• Originator entry
  
  
• Envelope entry
  
  
• Recipient entry

The following table shows the data that must be provided for each message descriptor attributes entry. The other message descriptors are optional.

Offset		Type	Field
Dec	Hex
0	0	POINTER	Message descriptor pointer
16	10	BINARY(4)	Length of the message descriptor
20	14	CHAR(8)	Message descriptor format name
28	1C	BINARY(4)	Reserved (must be zero)

Number of message descriptor attributes

INPUT; BINARY(4)

The number of entries in the array of message descriptor attributes. A minimum of three message descriptor attributes entries is required (originator entry, envelope entry, and recipient entry).

Format name

INPUT; CHAR(8)

The variable containing the format name of the parameter list passed to the API. This field must be set to CRTM0100.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error Code Parameter.

Message Descriptors

A message descriptor consists of:

• A create message common header section
  
  
• The actual message descriptor format. The following table shows valid message descriptor formats.
  
  

  Format name	Description
  ORCL0100	Original recipient entry
  ORGL0100	Originator entry
  ENVL0100	Envelope entry
  RCPL0100	Recipient entry
  ROAL0100	Report-on address entry
  RPYL0100	Reply-to address entry
  RTAL0100	Report-to address entry
  ATTL0100	Attachment reference entry

Create Message Common Header

The following table shows the common header section that is always included at the beginning of a message descriptor.

The common header is used for all of the different formats that can be supplied on the API. A specific format name can only be supplied in one of the message descriptor common headers when this API is called. There may be zero or more list items after the common header section.

Message Descriptor Formats for Create Mail Message

If there is data after the common header, one of the following message descriptor formats must be used. There may be multiple instances of the formats following the common header, depending on the size of the message descriptor.

ORCL0100 Format (Original Recipient Entry)

ORGL0100 Format (Originator Entry)

ENVL0100 Format (Envelope Entry)

RCPL0100 Format (Recipient Entry)

ROAL0100 Format (Report-on Address Entry)

RPYL0100 Format (Reply-to Address Entry)

RTAL0100 Format (Report-to Address Entry)

ATTL0100 Format (Attachment Reference Entry)

Field Descriptions

Address type. The type of address that is contained in the entry.

Attachment reference. A reference to an attachment that is associated with the message.

Attachment reference type. The type of attachment that is contained in the entry.

Diagnostic code. A code that indicates the cause of a problem which caused the delivery of a message to this address to fail. The diagnostic code is assumed to contain the X.400 nondelivery diagnostic code.

Displacement of the attachment reference from the beginning of this ATTL0100 entry. The displacement from the beginning of this entry to the attachment reference in this entry.

Displacement of the envelope from the beginning of this ENVL0100 entry. The displacement from the beginning of this entry to the envelope in this entry.

Displacement of the origin address from the beginning of this ORGL0100 entry. The displacement from the beginning of this entry to the origin address in this entry.

Displacement of the original recipient address from the beginning of this ORCL0100 entry. The displacement from the beginning of this entry to the original recipient address in this entry.

Displacement of the recipient address from the beginning of this RCPL0100 entry. The displacement from the beginning of this entry to the recipient address in this entry.

Displacement of the reply-to address from the beginning of this RPYL0100 entry. The displacement from the beginning of this entry to the reply-to address in this entry.

Displacement of the report-to address from the beginning of this RTAL0100 entry. The displacement from the beginning of this entry to the report-to address in this entry.

Displacement of the report-on address from the beginning of this ROAL0100 entry. The displacement from the beginning of this entry to the report-on address in this entry.

Displacement of the snap-in provided information (SPIN) of this RCHL0100. The displacement from the beginning of this entry to the snap-in provided information (SPIN). (There are fields for RCPL0100 and RCHL0100 entries.)

Distribution type. The type of distribution associated with each recipient entry. The possible values are:

Envelope. A string of data representing information about the message, aside from the attachments and its recipients.

Envelope type. The type of envelope that is contained in the entry.

Length of address. The length of address that is contained in the entry. The maximum length of an address is 1024 bytes.

Length of attachment reference. The length in bytes of the attachment reference that is contained in the entry.

Length of envelope. The length of envelope that is contained in the entry.

Length of origin address. The length of the origin address for this entry. The maximum length of an origin address is 1024 bytes.

Length of the original recipient address. The length of the original recipient address for this entry. The maximum length of an original recipient address is 1024 bytes.

Length of receiver message descriptor. The length in bytes of the message descriptor that is being pointed to by the pointer to the message descriptor. The maximum length of a message descriptor is 16 million bytes.

Length of recipient address. The length in bytes of the recipient address. The maximum length of a recipient address is 1024 bytes.

Length of reply-to address. The length in bytes of the reply-to address. The maximum length of a reply-to address is 1024 bytes.

Length of snap-in provided information (SPIN). The length in bytes of the snap-in provided information (SPIN). The maximum length of the SPIN is 256 bytes.

Length of this entry. The length in bytes of this entry. This is used to get to the next entry.

Length of this message descriptor. The length in bytes of this message descriptor. The maximum length of a message descriptor is 16 million bytes.

Message descriptor data. One or more parameter list formats that follow the common header. Message descriptors are made up of a common header and a list of entries. The format of each entry in the list is defined by the format name associated with the message descriptor, which is located in the common header. The number of entries in the list is also defined in he common header.

Message descriptor format name. The content and format of the information provided for each message parameter. The possible values are:

Message descriptor pointer. A space pointer that points to a message descriptor. A message descriptor is used to pass information which describes the message.

Message type. The type of message that is associated with the entry.

Number of bytes available for this message descriptor. The number of bytes available in the space where the mail server framework puts the information being retrieved.

Offset of the first entry in the message descriptor. The offset from the beginning of this message descriptor to the first entry in the list of entries.

Origin address. A string that represents the address associated with the originator of the message. The contents and format of the string are not defined by the mail server framework. It is assumed that the address type associated with the origin address defines the contents of the origin address field.

Origin address coded character set identifier (CCSID). The CCSID provided for the origin address. Valid values for the CCSID are 1 through 65533 and 65535.

Original recipient address. A string that represents the address associated with the original recipient of the message. The contents and format of the string are not defined by the mail server framework. It is assumed that the address type associated with the original recipient address defines the contents of the original recipient address field.

Original recipient address coded character set identifier (CCSID). The CCSID provided for the original recipient address. Valid values for the CCSID are 1 through and including 65533, and 65535.

Reason code. A code that identifies reasons associated with the message delivery to this address. In the case of a nondelivery entry, this field would contain the reason the delivery of this message to this recipient failed. The reason code is assumed to contain the X.400 nondelivery reason code.

Recipient address. A string that represents the address associated with a recipient of the message. The contents and format of the string are not defined by the mail server framework. It is assumed that the address type associated with the recipient address defines the contents of the recipient address field.

Recipient address coded character set identifier (CCSID). The CCSID provided for the recipient address. Valid values for the CCSID are 1 through 65533 and 65535.

Reply requested flag. A flag that indicates whether this original recipient should reply to the message. The possible values are as follows:

Reply-to address. A string that represents the address to be replied to. The contents and format of the string are not defined by the mail server framework. It is assumed that the address type associated with the reply-to address defines the contents of the reply-to address field.

Reply-to address coded character set identifier (CCSID). The CCSID provided for the reply-to address. Valid values for the CCSID are 1 through and including 65533, and 65535.

Report-on address. A string which represents the address to be reported on. The contents and format of the string are not defined by the mail server framework. It is assumed that the address type associated with the report-on address defines the contents of the report-on address field.

Report-on address coded character set identifier (CCSID). The CCSID provided for the report-on address. Valid values for the CCSID are 1 through 65533 and 65535.

Report-to address. A string which represents the address to be reported to. The contents and format of the string are not defined by the mail server framework. It is assumed that the address type associated with the report-to address defines the contents of the report-to address field.

Report-to address coded character set identifier (CCSID). The CCSID provided for the report-to address. Valid values for the CCSID are 1 through 65533 and 65535.

Reserved. All reserved fields must be set to zero.

Snap-in provided information (SPIN). An area where snap-ins can store information that other snap-ins may use. SPIN provides a place where information relating to a specific recipient can be stored and used by snap-ins in the same or different exit points. This is completely user-defined and user-interpreted data.

Status. The status associated with each recipient entry. The possible values are:

Error Messages