Application Tools

In this section:

An application program may be as simple as a TABLE FILE ... END request or as elaborate as a series of replaceable variables (known as amper variables) controlled by dynamic inputs, GOTO statements, and/or looping logic (known collectively as Dialogue Manager). While Dialogue Manager is fully detailed in the Stored Procedure Reference manual, a limited set of these commands and tools are also noted here due to their integral use in APP management.


Top of page

x
EX Procedure and Amper Variables

In this section:

The EX procedure executes another procedure, as found on the application path. The procedure extension (on non-PDS platforms) is not required, and is assumed to be .fex. The full syntax is:

EX[EX] [appname/]procedure[.fex] [parameter=value[,parameter=value][,...]

Parameters may be names (such as LASTNAME) or numeric (such as 1), and may be mixed within the list. A specific APP name can be referenced and does not require the APP to be on the application path prior to execution. Numerics can also be assumed positionally, as in this example:

EX mytest DETAIL=ALL,QUARTERLY,PERSON=JAMES MADISON,5=MANAGER

and the procedure would contain amper variables (parameters) for &DETAIL, &2, and &PERSON, and would use the context of:

TABLE FILE ...
WHERE PERSON IS '&PERSON' AND PERIOD EQ '&2' 
...
END

There are two types of amper variables, single and double. Single amper variables are only active within the procedure they are created in. Double amper variables are good for the life of the session. Additionally, there are predefined, single amper variables, such as &LINES (records returned from a request), &FOCUSER (current user ID), &FOCFOCEXEC (name of the current executing procedure), &FOCCODEPAGE (the server NLS code page), and many others. See the Stored Procedure Reference manual for a detailed listing of other pre-defined amper variables.



x
EX EDAMAIL

Emails can be sent from a procedure with the content of a specific file included in the email body or as an attachment. This is useful for sending email alerts for events ranging from special error conditions to simple report completion. EDAMAIL requires a configured (and working) email SMTP Server node for the server workspace.

There are two forms of syntax for EDAMAIL:

The extended form is assumed if the first parameter contains an equal sign (=) indicating a name-value pair is being passed.

Most forms of email addresses are acceptable, including support@ibi.com, support1 <support@ibi.com>, and "support1" <support@ibi.com>. A semi-colon is used as the address separator for parameters that allow multiple email addresses. A comma is also allowed as a separator, if the overall address string is enclosed in single quotation marks.

The actual use and display of the email headers created by EDAMAIL are a function of the SMTP Server in use (and any intervening SMTP hops), plus the user email client (such as Outlook, Gmail, Hotmail, and so on). They are not directly controlled by the sender email headers. Therefore, an email may not always exhibit the expected behavior in all email client environments. For example, older email clients may not recognize newer header types, and may ignore Reply To. Any functional issues should first be investigated by an experienced SMTP/Email administrator to determine if they are client-related.



x
Syntax: How to Use EX EDAMAIL in the Positional Parameter Form

The syntax is:

EX EDAMAIL to, from, subject, [flag], filetype, data

where:

to

Is the email recipient. Multiple addresses are allowed, using a semi-colon as the address separator. A comma is also allowed as a separator, if the overall address string is enclosed in single quotation marks (‘).

from

Is the email sender.

subject

Is the email subject string. If the subject string contains a comma, the string must be enclosed in quotation marks.

flag

If set to a or A, the file is sent as an attachment. Otherwise, it is included as the body of the email. All other values are ignored. The value is also ignored if the filetype parameter is blank.

filetype

Defines the data file type for an email message body that uses a file. Any application file type is valid, including MASTER, FOCEXEC, HTML, TEXT, and so on. Leave the parameter empty to use the inline email message body feature.

data

Is the inline data stream for the email message body or the [app/]filename file containing the email message body. The inline data stream feature requires an empty filetype parameter. The EDAMAIL feature can also spread an inline email message body on to multiple lines using the -LINES {n|*} feature.

If an inline data stream message body is spread across multiple lines in the procedure, the resulting email is a single line of output. Multi-line message bodies are respected when the message body from a file option is used.



Example: Mailing an HTML File as Message Body
TABLE FILE file1
PRINT A B C
ON TABLE HOLD AS MYFILE FORMAT HTML
END
EX EDAMAIL  user1@corp1.com, user2@corp1.com, File1 Report,,HTML, MYFILE


Example: Mailing an HTML File as a Message Attachment
TABLE FILE file1
PRINT A B C
ON TABLE HOLD AS MYFILE FORMAT HTML
END
EX EDAMAIL  user1@corp1.com, user2@corp1.com, File1 Report,a,HTML, MYFILE


Example: Mailing a Multi-line Inline Message
...
EX -LINES * EDAMAIL user1@corp1.com, user2@corp1.com, &SUBJECT,,, 
    Run result for &TESTNAME is:
&RESULT
EDAMAIL*


x
Syntax: How to Use EX EDAMAIL in the Extended Form

The EDAMAIL extended form using name-value pairs is activated by the detection of an equal sign (=) in the first parameter. Parameter names are not case sensitive and may be in any order, but the message parameter (if used) must be last.

The syntax is:

EX EDAMAIL to=addresslist, [toaddr=addresslist,] [from=address,]
 [fromaddr=address,] [replyto=address,] [importance=low|normal|high,]
 [subject=string,] [flags=value,] [filetype=extension,]
 [filename=file,] [message=body message]

where:

to=addresslist

Is the email recipient displayed by the user email client (and used in an email client Reply To All, if a toaddr header is not supplied). Multiple addresses are allowed, using a semi-colon as the address separator. A comma is also allowed as a separator, if the overall address string is enclosed in single quotation marks.

If the to parameter is used in conjunction with toaddr, the value of to may be an arbitrary string, such as "Group Managers", which most email clients will display as a pseudo title in the To field, and will not display the actual addresses used in the toaddr parameter. A forced blank can be supped for the To field by using to="".

toaddr=addresslist

Is the email recipient. If not supplied, SMTP servers will use the to header. Email clients will use the toaddr value in an email client Reply To All. Multiple addresses are allowed, using a semi-colon as the address separator. A comma is also allowed as a separator, if the overall address string is enclosed in single quotation marks.

from=address

Is the email sender displayed by the email client (and used in an email client Reply, unless overridden by a fromaddr or Reply To header). If the from parameter is used in conjunction with fromaddr, the from value may be an arbitrary string, such as The Boss, which most email clients will display as a pseudo title in the From field, and will not display the actual address used in the fromaddr parameter.

fromaddr=address

Is the email sender. If not supplied, most email clients will use the From header when doing a reply.

replyto=address

Is the email sender. If not supplied, most email clients will use the fromaddr or from parameter value.

importance=low|normal|high

Is the email importance level for email clients that support importance flags. Valid values are high, normal, and low.

subject=string

Is the email subject string. If the subject string contains a comma, the string must be enclosed in quotation marks.

flags=value

If set to a or A, the file is sent as an attachment. Otherwise, it is included as the body of the email.

filetype=extension

Defines the data file type for an email message body that uses a file as the body. Any application file type is valid, including MASTER, FOCEXEC, HTML, TEXT, and so on. Leave the parameter out to use the inline email message body feature.

filename=file

Defines the data file for an email message body that uses a file as the body. Leave the parameter out to use the inline email message body feature.

message=body message

Is the inline data stream containing the email message body. If used, it must be the last parameter in the EDAMAIL command. To use the inline data stream feature, the filetype and filename parameters cannot be supplied. The data stream may also be spread onto multiple lines if EDAMAIL is used with the EX -LINES {n|*} feature.

If an inline data stream message body is spread across multiple lines in the procedure, the resulting email is a single line of output. Multi-line message bodies are respected when the message body from a file option is used.



Example: Mailing an HTML File as a Message Body Using Multiple Addresses and Extended Form
TABLE FILE file1
PRINT A B C
ON TABLE HOLD AS MYFILE FORMAT HTML
END
EX EDAMAIL to=Managers,toaddr=user1@corp1.com;user2@corp1.com,
from=support1@corp1.com,subject=File1 Report, filetype=HTML, 
filename=MYFILE

iWay Software