Table of Contents
[ Up To iMail ]
iMail Command APIs
This section covers commands that are not accessible from the iMail menu, but rather from a command line. Ideally suited for programming, the commands may be embedded within any high level language such as RPG IV or CL.
Note that the commands mirror the menu options available from the menu group entitled Send Mail Commands.
General note: As of iDocs release 6.90, iMail supports blank, comma or semi-colon as address separators in the TO, CC and BC addresses fields for all API's listed below.
Examples below: ken@informdecisions.com, anh@informdecisions.com ken@informdecisions.com,anh@informdecisions.com ken@informdecisions.com anh@informdecisions.com
ECVTDBF
This command will copy a data base file to the IFS. It was added to iMail version 6.85 on 1/22/16.
Convert Database File (ECVTDBF)
Type choices, press Enter.
File name . . . . . . . . . . . Name
Library . . . . . . . . . . . *LIBL Name, *LIBL
Member name . . . . . . . . . . *FIRST Character value
Conversion Type . . . . . . . . *TXT *TXT, *SAVF, *DIF, *XLS, *CSV
IFS Directory . . . . . . . . .
Bottom
F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display
F24=More keys
The following describes the command qualifiers and their expected values:
- File Name – Enter the file name in this command qualifier
- Library – Enter the iSeries library where the file can be found.
- Member Name – Enter the member name if know, or *FIRST for the first member found in this file.
- Conversion Type – Select *TXT, *SAVF, *DIF, *XLS, *CSV.
- IFS Directory - Enter the target directory on the IFS in single quotes, i.e. 'home/mydirectory'. This diectory/path must exist, or ECVTDBF will be aborted. This text is case sensitive.
Note: If selecting the *XLS format, the column text is determined by the iMail Configuration default value for XLS Col from column text (Y/C/B). The *SAVF format will only function if selecting an appropriate save file.
ECVTSPLF
This command is used primarily for converting a spool file to a specific format and subsequently saving the resulting format to a file within the IFS directory structure.
iMail Convert Spooled File (ECVTSPLF)
Type choices, press Enter.
Spool file name . . . . . . . . Name
Job name . . . . . . . . . . . . * Name, *
User . . . . . . . . . . . . . Name
Number . . . . . . . . . . . . 000000-999999
Spool file number . . . . . . . *LAST 1-9999, *LAST
Converted spool types . . . . . *PDF Character value, *FCFC...
IFS Directory . . . . . . . . . '/imail'
IFS Filename . . . . . . . . . . *SYSTEM
The screen shot above looks nearly identical to the command ESNDSPLF in that the same technique is used to select the last spool file within a job stream. Likewise, another spool file may be selected if explicitly identified.
The remaining two parameters, TYPE and DIR define the spool conversion type and the location of where the file should be placed. Additionally, when converting a spooled file to *PDF the orientation of the spooled file will conform to the orientation value stored in the data area, DSORIENT. This value may contain *PORTRAIT, *LANDSCAPE, or *SYSDFT. If the value contains *SYSDFT, then the resulting orientation will be derived from the orientation of the source spooled file.
ESNDDTAQ
This command will send data to keyed data queue. It's included in the IFDCLIENT module. See https://manual.informdecisions.com/doku.php?id=pub:ifdcinstructions
ESNDDBF
The command ESNDDBF allows a specific member from a database file to be attached to an email and subsequently converted to the desired format and sent as an email attachment.
Below is how the command appears when prompted:
Send Database File (ESNDDBF)
Type choices, press Enter.
File name . . . . . . . . . . . FILE DBFILE Name
Library . . . . . . . . . . . QGPL Name, *LIBL
Member name . . . . . . . . . . MBR DBMBR Character value
Attachment Type . . . . . . . . TYPE *TXT *TXT, *SAVF, *DIF, *XLS, *CSV
From: eMail address . . . . . . FROMADDR
To: eMail address . . . . . . . TOADDR
+ for more values
CC: eMail address . . . . . . . CCADDR
+ for more values
BCC: eMail address . . . . . . . BCCADDR
+ for more values
Subject . . . . . . . . . . . . SUBJECT
Message text . . . . . . . . . . MSG
...
Zip Attachment . . . . . . . . . ZIP *NO
Within the command above in the prompt for type any one of the following formats may be entered from the table below.
| Type | Format | Description |
|---|---|---|
| *CSV | Comma Separated Value | Record and field based text file delimited with commas |
| *DIF | Data Interchange Format | Record and field based text file delimited with tabs |
| *SAVF | System i Save File | Requires that the source file already be a save file |
| *TXT | Text | Fixed format text file with no field delimitation |
| *XLS | Excel format | Fully compatible Excel format * |
* Prior to using *XLS to send a database in Excel format, the command IMAILIFS needs to first be issued to install the Java dependencies used to create the Excel file form the DB2 database. The syntax for the using the command is:
IMAILIFS LIB([YourSourceLibrary])
NOTE: Outlook 365 doesn't allow an override of the From Address and if entered on the API it will result in a send failure.
Thresholds and Limitations:
- Limited to emailing a single database file. (For multiples use command ESNDDBFS)
- Limited to 80 characters for the sender and recipient addresses
- Limited to 300 direct recipients in the To address*
- Limited to 300 direct recipients in the Cc address in addition to those in the To address*
- Limited to 300 blind copy recipients in the Bc address*
- Limited to 80 characters for the subject
- Limited to 2048 characters for the message
- Limited to converting the database file to the following types if the attribute is a
source physical file. CSV, DIF, TXT, XLS, XLSX
- Limited to retaining the initial format if the database file to the following types if the attribute is a
source save file.
- CSV - The maximum length of a database record is 32766 characters
- DIF - The maximum length of a database record is 32766 characters
- XLS - Maximum columns 255, Maximum column width 256
- TXT - Maximum columns 255, Maximum column width 256
Note: Your mail server can also limit the file size sent. Check with your Mail Server Administrator.
Release specific notes:
iMail 6.90 and above supports blank, comma or semi-colon as address separators in TO, CC and BC addresses.
iMail 6.98 includes data area DSCSVLEFT used to control the method used to convert a database to CSV.
DSCSVLEFT = 'Y': Uses the original approach of utilizing SQL to read the data: it will limit the number of
fields in database to 256 columns.
DSCSVLEFT = 'N': Uses the CPYTOIMPF command to convert a database to CSV and will not limit the columns in
the data file, but it can negatively impact the format of numeric fields for some customers who will be better
served with the original SQL approach.
ESNDDBFS
Identical to the command ESNDDBF but allows multiple database files to be attached to an email and subsequently converted to the desired format and sent as an email attachment. (iMail 6.87, 11/15/2016)
Below is how the command appears when prompted:
Send Multiple Database Files (ESNDDBFS)
Type choices, press Enter.
Select database files:
File name . . . . . . . . . . Name
LIBRARY . . . . . . . . . . *LIBL Name, *LIBL
Member name . . . . . . . . . *FIRST Character value
Attachment Type . . . . . . . *XLS *TXT, *SAVF, *DIF, *CSV, *XLS
+ for more values
From: eMail address . . . . . .
To: eMail address . . . . . . .
+ for more values
CC: eMail address . . . . . . .
+ for more values
More...
F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display
F24=More keys
With a + in the Select database files field:
Specify More Values for Parameter DBFILES
Type choices, press Enter.
Select database files:
File name . . . . . . . . . . Name
LIBRARY . . . . . . . . . . *LIBL Name, *LIBL
Member name . . . . . . . . . *FIRST Character value
Attachment Type . . . . . . . *XLS *TXT, *SAVF, *DIF, *CSV, *XLS
File name . . . . . . . . . . Name
LIBRARY . . . . . . . . . . *LIBL Name, *LIBL
Member name . . . . . . . . . *FIRST Character value
Attachment Type . . . . . . . *XLS *TXT, *SAVF, *DIF, *CSV, *XLS
File name . . . . . . . . . . Name
LIBRARY . . . . . . . . . . *LIBL Name, *LIBL
Member name . . . . . . . . . *FIRST Character value
Attachment Type . . . . . . . *XLS *TXT, *SAVF, *DIF, *CSV, *XLS
More...
F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display
F24=More keys
ESNDFILURL / ERCVFILURL
iDocs provides a utility to send a file from the IBM i to other system (ESNDFILURL) and receive files from other system to the IBM i (ERCVFILURL) via secured HTTP methods. With these commands, iDocs can facilitate the exchange of data with other systems via web services and a trust store. Since the integration is highly customized for each application, and because it depends on the receiving system to issue a certificate which is able to document in general. please contact your customer service representative and IFD will assist in the necessary configuration. The sample interface screen is shown below. Sample steps and useful commands to create certificates for mutual authentication to a server and a cacerts file (a trust store which contains server and client-signed certificates) are described here. This is for example only and will not work for every interface.
Below is an example for ESNDFILURL:
Send IFS File to URL (HTTPS) (ESNDFILURL)
Type choices, press Enter.
HTTPS URL . . . . . . . . . . . > informdecisions.com
IFS Sending File . . . . . . . . > file
Keystore File . . . . . . . . . '$USERDATA/JAVA400/EXT/.KEYSTORE'
Keystore Password . . . . . . . 'inform'
More...
Type choices, press Enter.
TrustStore File . . . . . . . . '$JAVA_HOME/LIB/SECURITY/CACERTS'
Truststore Password . . . . . . 'changeit'
Private Key Entry Alias . . . . 'agave'
Server Log File . . . . . . . . ESNDFILURL.LOG
Bottom
Below is an example for ERCVFILURL:
Receive File from URL (HTTPS) (ERCVFILURL)
Type choices, press Enter.
HTTPS URL . . . . . . . . . . . '/idocs/receive'
LISTEN PORT . . . . . . . . . . 443 Character value
IFS Output Directory . . . . . . '/home/receive'
Prefix name of receiving file . 'receive.'
Keystore File . . . . . . . . . '$USERDATA/JAVA400/EXT/.KEYSTORE'
Keystore Password . . . . . . . 'inform'
TrustStore File . . . . . . . . '$JAVA_HOME/LIB/SECURITY/CACERTS'
Truststore Password . . . . . . 'changeit'
ESNDMAIL
This command can be used to send an email message, and optionally to attach one or more pre-existing files contained in the IFS directory structure. ESNDMAIL will used either RPG or Java – depending on the iMail configuration setting.
Prompting the command will display the following command parameters:
Send iMail with Attachments (ESNDMAIL)
Type choices, press Enter.
To: eMail address . . . . . . . > TOADDR
+ for more values
Subject . . . . . . . . . . . . > SUBJECT
Message text . . . . . . . . . . > MSG
From: eMail address . . . . . . FROMADDR
More...
F3=Exit F4=Prompt F5=Refresh F10=Additional parameters F12=Cancel
F13=How to use this display F24=More keys
Page Down for Additional Parameters.
Send iMail with Attachments (ESNDMAIL)
Type choices, press Enter.
Additional Parameters
Attachment file . . . . . . . . > 'ATTACH1'
+ for more values > 'ATTACH2'
Bottom
F3=Exit F4=Prompt F5=Refresh F10=Additional parameters F12=Cancel
F13=How to use this display F24=More keys
Below are the parameter descriptions:
- TOADDR - Enter the recipients email address in this parameter.
- SUBJECT – Enter the email subject in this parameter.
- MSG – Enter the message body in this parameter value. The message text can contain a macro substitution variable that will be used to insert an email message. This message will be derived from a text file identified with a '&' located on the IFS iMail directory. i.e. MSG(’This text file verbiage will be inserted &MESSAGE.txt into the body’). In this example MESSAGE is a formatted text file on the imail directory of the IFS.
- CCADDR - Enter the copied recipients email address in this parameter.
- BCCADDR - Enter the blind copied recipients email address in this parameter. Note that blind copy recipients addresses are not visible to the recipients specified in the parameter TOADDR
- FROMADDR - Enter the from email address.
- ATTACH - Enter one or more IFS directory files.
Below is an example of this command with multiple IFS attachments:
ESNDMAIL TOADDR(davis@informdecisions.com) SUBJECT('Sending 3 Word Documents')
MSG('Message text') ATTACH('/home/dyokana/wordDoc1.doc' '/home/dyokana
/wordDoc2.doc' '/home/dyokana/wordDoc3.doc')
ESNDMAILJ
Added to version 6.90 on 3/21/18, this command is similar to ESNDMAIL, but will always use Javamail to send. It can be used to send an HTML email with the email message extracted from an HTML file in IFS, and optionally to attach one or more pre-existing files contained in the IFS directory structure. This command also uses an enhanced ifdjava.jar to read mail message from a file.
The example below used ECVTSPLF to convert a spool file to HTML into file /home/anguyen/samplehtm.htm, and ESNDMAILJ to email that file. Example command shown below:
ESNDMAILJ TOADDR(ANH@INFORMDECISIONS.COM) SUBJECT(ESNDMAILJ) MSG('/home/anguyen/samplehtm.htm')
You can create other HTML files, put them on to the IFS and use the command ESNDMAILJ specifying the path of HTML file into mail message.
ESNDMSG
This command simply sends an email message without attachments.
iMail Send Message (ESNDMSG)
Type choices, press Enter.
From: eMail address . . . . . . FROMADDR
To: eMail address . . . . . . . TOADDR
+ for more values
CC: eMail address . . . . . . . CCADDR
+ for more values
BCC: eMail address . . . . . . . BCCADDR
+ for more values
Subject . . . . . . . . . . . . SUBJECT
Message text . . . . . . . . . . MSG
The parameter values above conform to the requirements of the previously described APIS.
ESNDSPLF
This command will send a spool file as an email attachment. The spool file attachment may be specified one of two ways.
The most straightforward way to address the spool file to be attached is to assume that the last spool file created with the job stream should be sent. In fact, this is the command default.
The second way to specify the spool file attachment would be to identify the unique spool file name, user name, job, and spool file number. Consequently, with this level of specification the exact spool file can be located and attached regardless of whether or not the spool file had been created in the same job stream. However, these values need to be known prior to calling the command. Though it can be done, an end user would certainly not be expected to provide this information. This second technique would be much better suited to a CL, or RPG program. Note: The iDocs release V6.89 (10/05/17) and above will automatically detect the spool file type: SCS, PCL, AFPDS (new) and convert it to PDF. The OS release requires V7R1 and above for this feature to work.
When the command is prompted the following qualifiers appear as shown in the figure below:
iMail Send Spool File (ESNDSPLF)
Type choices, press Enter.
Printer file name . . . . . . . FILE > X
Job name . . . . . . . . . . . . JOB *
User . . . . . . . . . . . . .
Number . . . . . . . . . . . .
Spooled file number . . . . . . SPLNBR *LAST
To: eMail address . . . . . . .
+ for more values
Subject . . . . . . . . . . . . SUBJECT
More. . .
Message text . . . . . . . . . . MSG
CC: eMail address . . . . . . . CCADDR
+ for more values
BCC: eMail address . . . . . . . BCCADDR
+ for more values
More. . .
From: eMail address . . . . . . FROMADDR
Attachment file . . . . . . . . ATTACH
+ for more values
Attachment type . . . . . . . . TYPE *PDF *FCFC. *HTML, *PCL, *PDF
Retain attachment in IFS . . . .
Overwrite attachment in IFS . . N Y, N
Retain .msg file in /tmp . . . . N Y, N
More. . .
Name of output file . . . . . .
Additional Parameters
Zip Attachment . . . . . . . . . *NO *NO, *YES, Y, N
Read Receipt . . . . . . . . . . *NO *NO, *YES, Y, N
Delivery Receipt . . . . . . . . *NO *NO, *YES, Y, N
Bottom
The following describes the command qualifiers and their expected values:
- FILE – Enter the spool file name in this command qualifier
- JOB – Here either the asterisk default needs to be accepted in order to capture the last spool file created within the job stream or the actual job name, user and job number needs to be explicitly defined.
- SPLNBR – When capturing the last spool file in a job stream, accept the default value of *LAST, otherwise replace the default value with the specific spool file number associated with the job defined above.
- TOADDR – The recipient’s address must appear in this parameter.
- SUBJECT - Though not required, the subject may be placed here.
- MSG – Here enter the body of the message text. A carriage return <CR> tag can be used anywhere in the text to break the text to the following line. The message text can contain a macro substitution variable that will be used to insert an email message. This message will be derived from a text file identified with a '&' located on the IFS iMail directory. i.e. MSG('This text file verbiage will be inserted &MESSAGE.txt into the body'). In this example MESSAGE is a formatted text file on the imail directory of the IFS.
- CCADDR – Any copied addresses must appear in this parameter.
- BCCADDR - Any blind copy addresses must appear here. Note that blind copy recipients addresses are not visible to the recipients specified in the parameter TOADDR
- FROMADDR – This parameter requires the senders email address. If ommitted, then the default from address from the iMail configuration will be used.
- ATTACH – This qualifier specifies a PC file from the IFS directory to be attached.
- TYPE – Enter the type of attachment here as either or F4 Prompt displays a list for you to choose from:
- *FCFC
- *HTML
- *PCL
- *PDF
- *PRTCTL
- *RTF
- *TXT
- *XLS
- *XLSX
- *TIF
- OUTPUTNAME - (Added 6.90 12/15/17) The parameter overrides the iMail attachment name. If this parameter is blank, then the default name is used. User can use the following values:
- *SPLFNAME, *SPLNAME, *SPLNAM for spool file name
- *SPLFNUM4, *SPLNUM4, *SPLFNBR4, *SPLNBR4, *SPLF#4, *SPL#4 for spool file number with 4 characters length.
- *SPLFNUM, *SPLNUM, *SPLFNBR, *SPLNBR, *SPLF#, *SPL# for spool file number with 7 characters length.
- *JOBNAME, *JOBNAM for spool job name
- *JOBUSER, *JOBUSR for job user name
- *JOBNUMBER, *JOBNBR, *JOBNUM, *JOB# for job number (6 characters)
- *FORMTYPE, *FRMTYP, *FORMTYP for form type
- *USERDATA, *USRDTA, *USERDAT for user data
- *DATE for sending date in format YYMMDD
- *TIME for sending time in format hhmmss
- ZIP - The parameter controls whether or not the attachment is compressed and attached as a ZIP file. If the values is set to *YES, then the single spooled file is compressed and attached.
- RCPREAD - This option deteremines if a read email receipt is sent back to the email senders' address.
- RCPDLVR - This option deteremines if a deliveried email receipt is sent back to the email senders' however the ability to do so is based on the email client and settings of the recipients' email client.
ESNDSPLFS
This command is a nearly identical to ESNDSPLF except that it may be used to send multiple spooled file email attachements instead of one. This command however has not be extended to enable the multiple attachments to be compressed into a zipped file.
Below is the first portion of the command illustrating the optional multiple spooled files.
iMail Send Spool Files (ESNDSPLFS)
Type choices, press Enter.
Send Spooled Files: CMDSPL
Spooled file name . . . . . .
Job name . . . . . . . . . . . *
User . . . . . . . . . . . .
Number . . . . . . . . . . .
Spooled file number . . . . . *LAST
+ for more values
To iMail address . . . . . . . . TOADDR
+ for more values
Subject . . . . . . . . . . . . SUBJECT
As is the convention for specifying a list, entering a plus sign in the prompt for more values enables more spooled files to be entered.