Validate Data Field Exit Program

 Exit Point Name:  QIBM_QZMFMSF_VLD_TYP
 Exit Point Format Name:  VDFF0100

To configure the mail server framework, the user or programmer defines the format of information that it will use. The four basic type groups that the mail server framework supports are address types, message types, envelope types, and attachment types. The definition of a type consists of its name and its value. The mail server framework assumes that the definition of the type of the information defines the format of the information.

The mail server framework also provides a Validate Data Field exit program where a system can register programs to provide additional checking. These programs are called when mail messages are created or changed (using the Create Mail Message (QzmfCrtMailMsg) or Change Mail Message (QzmfChgMailMsg) API) and the message contains a type that has a validate data field exit program configured. The exit programs can be registered to be called for specific types of information only, or whenever any information for a particular type group is changed. Only list entries that have a matching type are passed to the user exit programs. The Validate Data Field exit program is called whenever any information matching the selection material is added to the message. When the program is complete, it returns its status in the return code parameter. If the return code from the exit program was zero, then the data is assumed to be valid and accepted. If the return code was not zero, then the data is assumed to be not valid and is rejected.

Authorities and Locks

None.

Required Parameter Group

Mail message identifier

INPUT; CHAR(32)

The variable containing the mail message identifier that the Validate Data Field exit program is passing information for. The mail message identifier is composed of characters A through Z and 0 through 9 only.

Message descriptor attributes

INPUT; ARRAY OF CHAR(*)

This array contains the message descriptor attributes for the data that is to be validated. The following table defines a message descriptor attributes array entry.

Offset		Type	Field
Dec	Hex
0	0	(PTR(SPP))	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 set to zero)

Number of message descriptor attributes

OUTPUT; BINARY(4)

Tells the snap-in program how many message descriptor entries are in the array being passed.

Format name

INPUT; CHAR(8)

The variable containing the format name of the parameter list in which information is being passed. This field must be set to VDFF0100.

Return code

OUTPUT; BINARY(4)

0	Data was valid.
1	Data was not valid.
2	Severe error encountered

Message Descriptors

A message descriptor consists of:

• A Validate Data Field Exit common header section
  
  
• A list data section that contains the data to be validated. The following table shows valid format names for message descriptors that are passed to the validate data field exit program.
  
  

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

Validate Data Field Exit Common Header

The following table shows the common header section that is always included at the beginning of a message descriptor. It can be used with all of the formats that can be passed using this exit. There may be one or more entries after the common header section.

Message Descriptor Formats for Validate Data Field Exit

One of the following message descriptor formats is used to describe the data that follows the common header.

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.

Note: The reason code and diagnostic code fields are assumed to contain values that are documented in CCITT Data Communication Networks Message Handling Systems 1988 Recommendation for X.400-X.420 for fields Non-delivery-reason-code and Non-delivery-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 entry 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.

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.

Exit program number. A number assigned to the exit program when it is registered using the registration facility. This is the number in effect at the time the exit program was called.

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

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 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 the common header.

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.

Number of entries available for this message descriptor. The total number of entries available for this message descriptor indicates the number of entries that would be returned if the length of the message descriptor is greater than or equal to the number of bytes available for this message descriptor.

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 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.

Note: The reason code and diagnostic code fields are assumed to contain values that are documented in CCITT Data Communication Networks Message Handling Systems 1988 Recommendation for X.400-X.420 for fields Non-delivery-reason-code and Non-delivery-diagnostic-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.

Recipient status flag. A flag which when set to 1 indicates that this entry has been replaced by either one or multiple entries. Entries with this flag set to 1 are referred to as parents. Entries with this flag set zero are referred to as children.

Reply requested flag. Whether this original recipient should reply to the message. The possible values are:

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 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.

Return code from the exit program. The return code returned by the user exit program.

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:

Unique identifier. A unique identifier that differentiates each item within a particular list. Identifiers are generated for each list item when the Create Mail Message (QzmfCrtMailMsg) API has successfully completed. These unique identifiers are temporary and may change as the mail service processes a message. List entries are placed in message descriptors such that unique identifiers are in ascending order.

Unique identifier of referenced entry. The unique identifier of another ORCL0100, ORGL0100, ENVL0100, RTAL0100, ROAL0100, RPYL0100, or ATTL0100 entry that this entry refers to. This field can be used to create entry cross-references as new entries are added.

Exit Program Introduced: V3R1