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.

 

Send MIME Mail parameters

Filename (Input)

Offset

Type

Field

What it is

00 BINARY(4) File name length
The number of bytes in the filename (no NULL assumed at end).
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.

 

Attachment stream file (Input)

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
The number of attachments (0 for none).
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.

 

Base directory name (Input)

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
The number of bytes in the base directory name (no NULL assumed at end).
04 CHAR(*) Base directory name The character string of the Integrated File System directory name. It can be either absolute or relative path.

 

Originator address (SMTP) (Input)

Offset

Type

Field

What it is

00 BINARY(4) Address length
The length of originator address string (no NULL assumed at end).
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.

 

Subject (Input)

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
The length of the subject string (no NULL assumed at end).
04 CHAR(*) The subject string The character string representing the subject of e-mail message. It should be in CCSID 500.

 

Recipient addresses (SMTP) (Input)

Offset

Type

Field

What it is

00 BINARY(2) Number of recipients
The number of recipient address structure (the must be at least one).
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
  • '*TO ' Normal
  • '*CC ' Carbon Copy
  • '*BCC' Blind Carbon Copy
*+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.

 

Error code (I/O)

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.

 

Allow headers (Input)

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
If *YES specified for this parameter the API would not add an empty line after standard headers, thus allowing you to specify additional MIME headers.

 

 

 

Send MIME Mail authorities

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.

Directory Authority
The user of the API must have:
  • *X authority to all the directories in the CommuniGate base directory path (default is /var/CommuniGate)
  • *WX authority to the directory Submitted.
  •  

    Send MIME Mail error messages

    CPFA09C
    Not authorized to object.
    CPFA0A9
    The object was not found.
    CPFA0CE
    The path name parameter that was specified resulted in an error.
    CPF24B4
    Severe error while addressing parameter list.
    CPF3C1D
    Length specified in parameter &1 not valid.
    CPF3C3C
    Value for parameter &1 not valid.
    CPFA825
    Out of memory.
    CPF3C88
    The number of variable length records &1 is not valid.
    CPF3CF1
    Error code parameter not valid.
    CPF9897
    Severe error.

     

     

    Send MIME Mail example

    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
    * 

     

    CGSENDMAIL (Send MIME Mail) Command Description

    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:

    1. The user must have:
  • *X authority to all the directories in the CommuniGate base directory path (default is /var/CommuniGate)
  • *WX authority to the directory Submitted.
  • 2. The maximum number of attachment file names that can be specified in command is 300.
    3. The maximum number of recipient addresses that can be specified in command is 300.

    Required Parameters

    STMF
    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. A maximum length of file name is 5000 characters.
    ATTSTMF
    The character string of the Integrated File System file name, 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. A maximum length of file name is 5000 characters.
    BASEDIR
    The character string of the Integrated File System directory name. It can be either absolute or relative path. Base directory is the directory containing queued messages, account files, settings, and other server data. The default is /var/CommuniGate. The maximum length is 5000.
    FRMADDR
    The character string of an SMTP originator address. For example, smith@myhost.mytown.com. All SMTP addresses should be in CCSID 500. The maximum length is 256.
    SUBJECT
    The character string representing the subject of e-mail message. It should be in CCSID 500. The maximum length is 512.
    TOADDR
    Distribution type:
  • '*TO ' Normal
  • '*CC ' Carbon Copy
  • '*BCC' Blind Carbon Copy
  • Destination address:
    The actual SMTP address of recipient. All SMTP addresses should be in CCSID 500. The maximum length is 256.
    ALWHDR
    Allow user specified headers in the ASCII note pointed by STMF parameter. The default value is *NO.
  • '*NO ' No MIME headers are assumed
  • '*YES' MIME headers preceeding the message body must be processed
  • 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

    CPFA09C
    Not authorized to object.
    CPFA0A9
    The object was not found.
    CPFA0CE
    The path name parameter that was specified resulted in an error.
    CPF24B4
    Severe error while addressing parameter list.
    CPF3C1D
    Length specified in parameter &1 not valid.
    CPF3C3C
    Value for parameter &1 not valid.
    CPFA825
    Out of memory.
    CPF3C88
    The number of variable length records &1 is not valid.
    CPF3CF1
    Error code parameter not valid.
    CPF9897
    Severe error.

     

    CGSENDMAIL (Send MIME Mail) syntax diagram

    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:

    1. A maximum of 300 repetitions.