|
Send MIME Mail (CGSENDMAIL) API reference |
The Send MIME Mail (CGSENDMAIL) API provides a front end for applications to use CommuniGate Pro server to send e-mail to the Internet. When sending e-mail, applications create an Integrated File System (IFS) ASCII file with an SMTP or MIME formatted piece of e-mail. The formatted e-mail is then Internet ready. The application next calls the CGSENDMAIL API. The application gives it both the name of the file and also the addresses that CommuniGate Pro server must use to forward the e-mail.
Note: The command only submits e-mail for processing. It does not ensure that e-mail is delivered to destination.
|
Offset |
Type |
Field |
What it is |
| 00 | BINARY(4) | File name length |
|
| 04 | CHAR(*) | File name | The character string of the Integrated File System filename of the ASCII note. It can be either absolute or relative path. After the API finishes processing the file, it will be unlinked. If this is the last link, the file will be deleted. |
If NULL pointer is specified for this parameter no attachments are to be processed.
|
Offset |
Type |
Field |
What it is |
| 00 | BINARY(2) | Attachments number |
|
| 02 | Array of BINARY(2) | File name offsets | Each element specifies offset from the beginning of this structure to a name of file containing an attachment. The number of elements is specified by 'Number of attachments'. |
| The following structure is repeated 'Number of attachments' times. | |||
| * | BINARY(2) | Reserved | |
| *+02 | BINARY(4) | File name length | The number of bytes in the file name (no NULL assumed at end). |
| *+06 | CHAR(*) | File name | The character string of the Integrated File System filename, which is to be sent as an attachment. It can be either absolute or relative path. After the API finishes processing the file, it will be unlinked. If this is the last link, the file will be deleted. |
is the directory containing queued messages, account files, settings, and other server data. The default name is /var/CommuniGate. The default is taken if name length is 0 or NULL pointer is specified for this parameter.
|
Offset |
Type |
Field |
What it is |
| 00 | BINARY(4) | Directory name length |
|
| 04 | CHAR(*) | Base directory name | The character string of the Integrated File System directory name. It can be either absolute or relative path. |
|
Offset |
Type |
Field |
What it is |
| 00 | BINARY(4) | Address length |
|
| 04 | CHAR(*) | Base directory name | The character string of an SMTP originator address. For example, smith@myhost.mytown.com. All SMTP addresses should be in CCSID 500. |
The subject is assumed empty if the length is 0 or NULL pointer is specified for this parameter.
|
Offset |
Type |
Field |
What it is |
| 00 | BINARY(4) | The subject string length |
|
| 04 | CHAR(*) | The subject string | The character string representing the subject of e-mail message. It should be in CCSID 500. |
|
Offset |
Type |
Field |
What it is |
| 00 | BINARY(2) | Number of recipients |
|
| 02 | Array of BINARY(2) | Address offsets | Each element specifies offset from the beginning of this structure to a recipient address. The number of elements is specified by 'Number of recipients'. |
| The following structure is repeated 'Number of recipients' times. | |||
| * | BINARY(2) | Reserved | |
| *+02 | CHAR(4) | Distribution type | Type of recipient
|
| *+06 | BINARY(4) | Address length | The length in bytes of the SMTP address. The maximum length is 256 bytes. This maximum length is determined by Internet standards. |
| *+10 | CHAR(*) | Address | The actual SMTP address (no NULLS included). All SMTP addresses should be in CCSID 500. |
The structure that returns error information. If this parameter is omitted or specified as NULL pointer the errors occurred are reported to the caller as exceptions.
|
Offset |
Type |
Field |
What it is |
| 00 | BINARY(4) | Bytes provided | The number of bytes provided for
feedback including this field. The bytes provided must be 0, 8, or more
than 16. If more than 32 783 bytes (32KB for exception data plus 16 bytes
for other fields) are specified, it is not an error, but only 32 767 bytes
(32KB) can be returned in the exception data.
0 - If an error occurs, an exception is returned to the application to indicate that the requested function failed. 8 - If an error occurs, the 'Bytes available' is filled in. No exception is returned. >=16 - If an error occurs, the space is filled in with the exception information. No exception is returned. |
| 04 | BINARY(4) | Bytes available | The number of bytes available to return to caller of this API. If this is 0, no error was detected and none of the fields that follow this field in the structure are changed. |
| 08 | CHAR(7) | Exception ID | The identifier for the message for the error condition. |
| 15 | CHAR(1) | Reserved | A 1-byte reserved field. |
| 16 | CHAR(*) | Exception data | A variable-length character field that contains the insert data associated with the exception ID. |
If this parameter is omitted or specified as NULL pointer the value *NO is assumed.
|
Offset |
Type |
Field |
What it is |
| 00 | CHAR(4) | Allow headers |
|
The MIME IFS file must exist for the duration of the CGSENDMAIL API pass. The API will remove (unlink) the link. If this is the last link, the file will be deleted.
ÊH/TITLE Call CGSENDMAIL * * Name of stream file with the body of e-mail. * Although FNAME is limited by 256 bytes it can actually be very * long. Some AS/400 file systems allow 16Mb for path name. * Unfortunately, in RPG/400 data structure subfield can not be * longer than 256 bytes. Sure, this limitation can be overcome by * dividing the name into several parts. * Probably ILE RPG does not impose such a limit. ISTMF DS I B 1 4 FLEN I 5 256 FNAME * Attachment files data structure. * Here we reserved place for 2 attachments maximum. * The API itself does not impose any limit on the number of * attachments. IASTMF DS I B 1 2 NUMATT I B 3 4 OFFT11 I B 5 6 OFFT12 * Attachment file name 1. I 7 8 RSRV11 I B 9 12 ANLEN1 I 13 268 AFILN1 * Attachment file name 2. I 269 270 RSRV12 I B 271 274 ANLEN2 I 275 530 AFILN2 * CommunigatePro server BaseDirectory. * Although DNAME is limited by 256 bytes it can actually be very * long. Some AS/400 file systems allow 16Mb for path name. * Unfortunately, in RPG/400 data structure subfield can not be * longer than 256 bytes. Sure, this limitation can be overcome by * dividing the name into several parts. * Probably ILE RPG does not impose such a limit. IBDIR DS I B 1 4 DLEN I 5 256 DNAME * Originator address. * The maximum length of address is 256 bytes. IFRMADR DS I B 1 4 FADLEN I 5 256 FADDR * The subject. * The subject field can be as long as 16Mb. ISBJ DS I B 1 4 SBJLEN I 5 256 SUBJEC * Destination addresses data structure. * Here we reserved place for 5 destination addresses maximum. * The API itself does not impose any limit on the number of * destination addresses. Each address may not be longer than 256. ITOADDR DS I B 1 2 NUMADR I B 3 4 OFFT1 I B 5 6 OFFT2 I B 7 8 OFFT3 I B 9 10 OFFT4 I B 11 12 OFFT5 * Destination address 1. I 13 14 RSRV1 I 15 18 DSTTP1 I B 19 22 ADLEN1 I 23 278 TOADR1 * Destination address 2. I 279 280 RSRV2 I 281 284 DSTTP2 I B 285 288 ADLEN2 I 289 544 TOADR2 * Destination address 3. I 545 546 RSRV3 I 547 550 DSTTP3 I B 551 554 ADLEN3 I 555 810 TOADR3 * Destination address 4. I 811 812 RSRV4 I 813 816 DSTTP4 I B 817 820 ADLEN4 I 821 1076 TOADR4 * Destination address 5. I 1077 1078 RSRV5 I 1079 1082 DSTTP5 I B 1083 1086 ADLEN5 I 1087 1342 TOADR5 * Error code. * If ECODE would be as long as 512 bytes and PROVID = 512 * then (in case of error) API will return MSGID and message data. * In this example we limit ourself to MSGID only. IECDS DS I 1 16 ECODE I B 1 4 PROVID I B 5 8 AVAIL I 9 15 MSGID * CGSENDMAIL API * Name CGSENDMAIL is too long for RPG. * It's even longer when qualified by library name. * If CGSERVER library (or however it is called) is in library * list, then qualifying is not necessary. * Let's define a constant. I 'CGSERVER/CGSENDMAIL' C SNDM * * As file name, subject and SMTP addresses can be quite long * let's define constants. * Name of my file containing e-mail. I '/home/myhome/- C MYFILE I 'tmp/myfile' I 23 C MYFLEN * Name of my file containing attachment. I '/home/myhome/- C ATTF1 I 'tmp/myattfile' I 26 C AN1LEN * My address. I 'myname@myhost.com' C MYADDR I 17 C MYALEN * The subject. I 'This is subject of-' C MYSUBJ I 'my e-mail' I 27 C MYSBJL * Dst. address 1. I 'hisname@hishost.com' C ADDR1 I 19 C AD1LEN * Dst. address 2. I 'hername@herhost.com' C ADDR2 I 19 C AD2LEN ***************************************************************** * Stream file name. C MOVELMYFILE FNAME File name. C Z-ADDMYFLEN FLEN Len. of name. * Attachment files. **** Z-ADD0 NUMATT --- no attachment. C Z-ADD1 NUMATT One attachment. * OFFT11 must contain offset from the beginning of ASTMF * to the field RSRV11. C Z-ADD6 OFFT11 Offset to att1. C Z-ADDAN1LEN ANLEN1 Len. att1. C MOVELATTF1 AFILN1 Att. file name. * Use default base directory. C Z-ADD0 DLEN Len. = 0. * Originator address. C MOVELMYADDR FADDR From address. C Z-ADDMYALEN FADLEN Addr. len. * Subject. C MOVELMYSUBJ SUBJEC Subject. C Z-ADDMYSBJL SBJLEN Length. * Destination addrersses. C Z-ADD2 NUMADR Two addrs. * OFFT1 must contain offset from the beginning of TOADDR * to the field RSRV1. C Z-ADD12 OFFT1 Offset to adr1. * OFFT2 must contain offset from the beginning of TOADDR * to the field RSRV2. C Z-ADD278 OFFT2 Offset to adr2. C MOVEL'*TO ' DSTTP1 Dst.type. adr1. C MOVEL'*CC ' DSTTP2 Dst.type. adr2. C Z-ADDAD1LEN ADLEN1 Len. addr1. C MOVELADDR1 TOADR1 C Z-ADDAD1LEN ADLEN2 Len. addr2. C MOVELADDR2 TOADR2 * Initialize error code parameter. C Z-ADD16 PROVID Bytes provided. * Call CGSENDMAIL. C CALL SNDM C PARM STMF C PARM ASTMF C PARM BDIR C PARM FRMADR C PARM SBJ C PARM TOADDR C PARM ECODE * C AVAIL IFNE 0 * Call to program ended in error * Send message 'Error xxxxxxx occured on CALL...' * MSGID field contains CPFnnnn, resulted from this call. C END C SETON LR *
CGSENDMAL Command syntax diagram
Purpose
The Send MIME Mail (CGSENDMAIL) command is used to send e-mail to Internet via CommuniGate Pro server.
Note: The command only submits e-mail for processing. It does not ensure that e-mail is delivered to destination.
Restrictions:
Required Parameters
Examples for CGSENDMAIL
Example 1:
CGSENDMAIL STMF('/home/myhome/temp/myfile') FRMADDR('smith@myhost.mytown.com') TOADDR((*TO 'John@hishost.histown.com') (*CC 'brown@hishost.histown.com')
This command takes message body from IFS stream file '/home/myhome/temp/myfile' and sends an e-mail to SMTP address 'John@hishost.histown.com' and a copy to 'brown@histhost.histown.com'.
Example 2:
CGSENDMAIL STMF('/home/myhome/temp/myfile') BASEDIR('/variable/CGate') FRMADDR('smith@myhost.mytown.com') SUBJECT('This is subject of e-mail') TOADDR((*TO 'John@hishost.histown.com') (*CC 'brown@hishost.histown.com')
This example differs from the previous one in that it uses '/variable/CGate' base directory instead of default and specifies the subject of e-mail.
Example 3:
CGSENDMAIL STMF('/home/myhome/temp/myfile') ATTSTMF('/home/myhome/temp/myatt1' '/home/myhome/temp/myatt2') FRMADDR('smith@myhost.mytown.com') TOADDR((*TO 'John@hishost.histown.com') (*CC 'brown@hishost.histown.com')
This command takes message body from IFS stream file '/home/myhome/temp/myfile', attaches files '/home/myhome/temp/myatt1' and '/home/myhome/temp/myatt2' and sends an e-mail to SMTP address 'John@hishost.histown.com' and a copy to 'brown@histhost.histown.com'.
Error messages for CGSENDMAIL
*ESCAPE Messages
|
Job: B,I Pgm: B,I REXX: B,I Exec |
|
Threadsafe: No |
>>-CGSENDMAIL---STMF(--'file-name'--)----------------------------->
>-----+----------------------------------------------+------------>
| .--------------------------. |
| V (1) | |
'-ATTSTMF(----+-------'file-name'--------+--)--'
>-----+--------------------------------+-------------------------->
| |
'-BASEDIR(--'directory-name'--)--'
>-----FRMADDR(--'originator-address')----------------------------->
>-----+------------------------------+---------------------------->
| |
'-SUBJECT(--'subject-text'--)--'
.-------------------------------------.
V (1) |
>-----TOADDR(----+-*TO--+--'destination-address'-------+--)------->
+-*CC--+
'-*BCC-'
>-----+-----------------------------+-----------------------------<>
'-ALWHDR(----+-*NO--+----)----'
'-*YES-'
Note: