SMTPMailService Example
This example program will perform the following steps:
1. It performs a series of calls necessary to load the SMTPMailService
2. It specifies the SMTP server and the user and password necessary to logon to that server using the SET service command (you need to modify the source code to provide details appropriate for your environment)
3. It specifies the TO and FROM address and SUBJECT line for the example e-mail it will send using the SET service command (you need to modify the source code to provide details appropriate for your environment)
4. It sends the example e-mail using the SEND service command – in this simple example, the body text lines comes from compile-time array data coded in the RPG program, but it could equally well have come from a database or have been received in various formats through another LANSA Integrator service call
5. It unloads the service and closes the connection to the JSM server.
Refer to the comments and code in the example for more information.
There are three steps required to make this application work:
1. Create the structure XML
The call to the SEND command of the SMTPMailService passes a multiple occurrence data structure containing the body text lines that will be sent in the e-mail. For this to work, the LANSA Integrator service needs to know the characteristics of this structure. This is accomplished by supplying an XML file that describes the structure.
For this example, the required XML is supplied below. To install this XML you need to perform the following steps:
a. Locate the structure folder in the JSM instance folder for your JSM server
b. Create a file called SMTPMailBody.xml
c. Edit the file with a text editor and paste into it the xml supplied below
Note that the field names used in the structure XML do not need to match the variable names used in the RPG program. It is their order, types and length that are important – not their names.
<?xml version="1.0" encoding="UTF-8"?>
<rdml:structure xmlns:rdml="http://www.lansa.com/2000/XML/Function">
<rdml:field name="BODYTXT" type="A" length="80" />
</rdml:structure>
2. Register the structure XML with the JSM Server
The example program refers to the structure XML supplied above with the symbolic name SMTP.MailBodyList by specifying that name in the SERVICE_STRUCTURE keyword of the SEND command.
The JSM Server needs to be given a link between the symbolic name and the actual name and location of the structure XML file created in step 1. To do this you need to perform the following steps:
a. Locate the system folder in the JSM instance folder for your JSM server
b. Edit the file structure.properties with a text editor and paste into it the entry supplied below (make sure the new entry is on a line by itself)
c. Save your changes
d. Restart or refresh the JSM Server instance (refer to Java Service Manager Refresh).
structure.SMTP.MailBodyList=structure/SMTPMailBody.xml
3. Create and run the ILE RPG example program
Copy and paste the source provided below into a source file member. Then modify the constant values for server, user id and password and to and from addresses as directed above and in the source code.
To create the program, you need to use the CRTRPGMOD and CRTPGM commands. Make sure that you use the parameter values specified in the source member.
*************************************************
* SMTP: example in RPG ILE of using the LANSA Integrator
* SMTPMailService
*
* Note: This is an example program containing only
* rudimentary exception handling
*
* To create this program you must execute the following commands,
* supplying the indicated parameter values and any others that are
* necessary in your installation:
*
* CRTRPGMOD MODULE(<modlib>/SMTP)
* SRCFILE(<srclib>/<srcfil>)
*
* CRTPGM PGM(<pgmlib>/SMTP)
* MODULE(<modlib>/SMTP)
* BNDSRVPGM(<jsmpgmlib>/DCXS882X)
* ACTGRP(*CALLER)
*************************************************
* You MUST replace the value of these constants
* before compiling and running this example
* - for smtp_server, specify the network name or address of
* your SMTP mail server (this might not be an IBM i or
* IBM i server). However, it must be addressable from the
* system where the LANSA Integrator JSM server is running
* - for smtp_user, specify the user name used to login to the
* SMTP server
* - for smtp_password, specify the password for the smtp_user
* specified that is used to login to the SMTP server
* NB: user and password might be case sensitive, depending on
* the SMTP server you are using
d smtp_server c '<your server>'
d smtp_user c '<user id>'
d smtp_password c '<password>'
* - for smtp_to, specify the e-mail address you want to send
* the e-mail to (for example, your own e-mail address)
* - for smtp_from, specify the e-mail address you want the
* e-mail to originate from. Because many SMTP mail servers
* prohibit mail relay, this may need to be an address from the
* e-mail domain that is normally managed by the mail server.
* You can specify your own address - it does not matter if the
* FROM address is the same as the TO address.
d smtp_to c '<to address>'
d smtp_from c '<from address>'
d smtp_subject c 'E-mail generated +
d by SMTPMailService +
d example program'
* Declare variables for the JSM calls
d jsmsrv s 50a inz(*blanks)
d jsmsts s 20a inz(*blanks)
d jsmmsg s 255a inz(*blanks)
d jsmcmd s 255a inz(*blanks)
d bytelength s 10i 0 inz(*zero)
* Declare structure to send body text to the SMTPMailService
* - in this simple example, the data comes from the compile-time
* array data, but it could equally well have come from a database
* or received through another LANSA Integrator service call
* NB: This MUST match the structure xml provided to the JSM Server!
d smtpbody ds occurs(smtpocur)
d based(smtplistptr)
d bodytext 80a
d smtpocur c const(6)
d smtpsize c const(%size(smtpbody))
* Declare the compile-time array that provides the body text
* for this simple example
d smtpdata s 80a dim(smtpocur) perrcd(1) ctdata
* Completion messages
d CompMsg01 c 'JSMOPEN call completed.'
d CompMsg02 c ' SERVICE_LOAD call completed.'
d CompMsg10 c ' SET call completed.'
d CompMsg20 c ' SEND call completed.'
d CompMsg98 c ' SERVICE_UNLOAD call completed.'
d CompMsg99 c 'JSMCLOSE call completed.'
* Procedure prototypes
d CheckResult pr
d crjsts const like(jsmsts)
d crjmsg const like(jsmmsg)
d SendMessage pr
d smText 512a VALUE
d smType 10a VALUE
* Prototypes for the JSM calls
/COPY QRPGLESRC,JSM_PROC.H
* Open a connection to the default JSM server
* - because the server parameter is blank, details of the default
* JSM server are obtained from the data area JSMCLTDTA on IBM i
* or from the file jsmcltdta.txt on other supported platforms)
c callp p_jsmopen(jsmsrv:jsmsts:jsmmsg)
c callp CheckResult(jsmsts:jsmmsg)
c callp SendMessage(CompMsg01:'*COMP')
* Load the SMTPMailService
* - this example explicitly turns tracing on, overriding the
* settings in the manager.properties file
c eval jsmcmd = 'SERVICE_LOAD'
c + ' SERVICE(SMTPMAILSERVICE) TRACE(*YES)'
c callp p_jsmcmd(jsmcmd:jsmsts:jsmmsg)
c callp CheckResult(jsmsts:jsmmsg)
c callp SendMessage(CompMsg02:'*COMP')
* Set the SERVER, USER and PASSWORD necessary to connect to
* your SMTP mail server
* - you MUST alter the constant definitions at the beginning of
* this program to specify values appropriate for your mail server
* - this assumes the mail server listens on port 25.
* If your mail server uses a different port then you will need
* to specify the PORT keyword too
c eval jsmcmd = 'SET'
c + ' SERVER(' + %trim(smtp_server) + ')'
c + ' USER(' + %trim(smtp_user) + ')'
c + ' PASSWORD(' + %trim(smtp_password) + ')'
c callp p_jsmcmd(jsmcmd:jsmsts:jsmmsg)
c callp CheckResult(jsmsts:jsmmsg)
c callp SendMessage(CompMsg10:'*COMP')
* Set TO and FROM addresses and SUBJECT
* - you MUST alter the constant definitions at the beginning of
* this program to specify values appropriate for your mail server
* - these can also be specified directly on the SEND command
* - you can specify a list of TO addresses, you can also specify
* single or lists of CC and BCC addresses. To specify multiple
* addresses you must make separate calls to SET for each of TO
* CC and BCC, supplying the appropriate list of addresses for each
c eval jsmcmd = 'SET'
c + ' TO(' + %trim(smtp_to) + ')'
c + ' FROM(' + %trim(smtp_from) + ')'
c + ' SUBJECT(' + %trim(smtp_subject) + ')'
c callp p_jsmcmd(jsmcmd:jsmsts:jsmmsg)
c callp CheckResult(jsmsts:jsmmsg)
c callp SendMessage(CompMsg10:'*COMP')
* You may wish to specify file attachments to be sent with the e-mail.
* You can use the ADD service command to add the attachments. This
* example does not send attachments.
* Populate the list of e-mail body text lines to be sent
* - in this simple example, the data comes from the compile-time
* array data, but it could equally well have come from a database
* or received through another LANSA Integrator service call
c eval smtplistptr = %addr(smtpdata)
* Send the e-mail
* - this passes the multiple occurrence data structure
* (smtpbody) containing the body text lines
* - the structure is described to the SMTPMailService by the
* structure XML identified by the SERVICE_STRUCTURE keyword - there
* must be a matching entry in the structure.properties file and a
* corresponding structure XML file, usually in JSMInstance\Structure
* folder
* NOTE: this call uses the JSMCMDX api in order to be able to send
* variable data (in this case the body text structure/list)
c eval jsmcmd = 'SEND'
c + ' SERVICE_STRUCTURE(SMTP.MailBodyList)'
c + ' COUNT(' + %char(smtpocur) + ')'
c + ' OCCURS(' + %char(smtpocur) + ')'
c + ' SIZE(' + %char(smtpsize) + ')'
c eval bytelength = smtpocur * smtpsize
c callp p_jsmcmdx(jsmcmd:smtpbody:bytelength:
c jsmsts:jsmmsg)
c callp CheckResult(jsmsts:jsmmsg)
c callp SendMessage(CompMsg20:'*COMP')
* Unload the SMTPMailService
c eval jsmcmd = 'SERVICE_UNLOAD'
c callp p_jsmcmd(jsmcmd:jsmsts:jsmmsg)
c callp CheckResult(jsmsts:jsmmsg)
c callp SendMessage(CompMsg98:'*COMP')
* Close the connection to the JSM server and finish
c callp p_jsmclose(jsmsts:jsmmsg)
c callp CheckResult(jsmsts:jsmmsg)
c callp SendMessage(CompMsg99:'*COMP')
c eval *inlr = *on
c return
*************************************************
* Procedure to check the result of a Java Service Manager call
*************************************************
p CheckResult b
d CheckResult pi
d crjsts const like(jsmsts)
d crjmsg const like(jsmmsg)
d crText s 512a
d crMsg1 c const('JSM Status : ')
d crMsg2 c const('JSM Message: ')
d crMsg3 c const('JSM Service error has +
d occurred')
c if crjsts <> 'OK'
c eval crText = crMsg1 + crjsts
c callp SendMessage(crText:'*DIAG')
c eval crText = crMsg2 + crjmsg
c callp SendMessage(crText:'*DIAG')
c callp SendMessage(crMsg3:'*ESCAPE')
c endif
p CheckResult e
*************************************************
* Procedure to send a program message
*************************************************
p SendMessage b
d SendMessage pi
d smText 512a VALUE
d smMsgT 10a VALUE
d smMsgI s 7a inz('CPF9897')
d smMsgF s 20a inz('QCPFMSG *LIBL ')
d smDtaL s 10i 0 inz(%size(smText))
d smStkE s 10a inz('*')
d smStkC s 10i 0 inz(1)
d smMsgK s 4a
d smErrC s 10i 0 inz(0)
c if smMsgT = '*ESCAPE'
c eval smMsgI = 'CPF9898'
c endif
c call 'QMHSNDPM'
c parm smMsgI
c parm smMsgF
c parm smText
c parm smDtaL
c parm smMsgT
c parm smStkE
c parm smStkC
c parm smMsgK
c parm smErrC
p e
**CTDATA smtpdata
This e-mail was generated by the LANSA Integrator RPG ILE example
program for the SMTPMailService.
Refer to the LANSA Integrator Guide for more information about using the
SMTPMailService and other LANSA Integrator services.
====================
http://www.lansa.com