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 TIBCO WebFOCUS® Developing Reporting Applications manual, a limited set of these commands and tools are also noted here due to their integral use in APP management.

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[EC] [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 (local) and double (global). 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.

EX EDAMAIL

How to:

EDAMAIL is an internal procedure that allows you to send emails 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 original form uses positional parameters, and is limited to the original specification.
  • The extended form uses non-positional, name-value pair parameters. The extended form supports additional SMTP email client features such as Reply To and Importance.

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

The basic form of email address (that is, foo@foo.com or <foo@foo.com>) may be used in either the original or the extended form of EDAMAIL. Extended forms of email addressing (such as My Support <support@foo.com>, "My Support" <support@foo.com>, "My Support <support@foo.com>", and "Support, Me <support@foo.com>") are only supported in the extended form of EDAMAIL.

Multiple addresses may be use for parameters that support multiple addresses (for example, to) when properly formed and delimited.

For multiple addresses and basic EDAMAIL, the separator must be a semi-colon (;), and the overall string may be, optionally, enclosed in double quotation marks, but remember that basic EDAMAIL only supports simple addresses.

For multiple addresses and extended EDAMAIL, the separator is normally a semi-colon (with exceptions where a comma may be used), plus the overall string must be enclosed in single quotation marks if any of the addresses contains a comma (for example, Support, Me <support@foo.com>). A comma may be used as separator if the email addresses are all simple addresses (that is, foo@foo.com or <foo@foo.com>), plus the overall string must be enclosed in single or double 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.

The EDAPRINT log records all EDAMAIL executions. It shows the user ID that executed the EDAMAIL command and sender and addressee information. For example: 

02/01/2019 16:58:41.395 I EDAMAIL u=PTH\srvadmin,from=user2@ibi.com(),to=(user1@ibi.com)

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

The syntax is: 

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

where:

to

Is the email recipient. Multiple addresses are allowed, using a semi-colon as the address separator.

cc

Is the carbon copy recipient. Multiple addresses are allowed, using a semi-colon as the address separator.

bcc

Is the blind carbon copy recipient. Multiple addresses are allowed, using a semi-colon as the address separator.

from

Is the email sender.

subject

Is the email subject string. If the subject string contains a comma, the string must be enclosed in single or double 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*

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|%[app/]addresslist.fex}, ]
[cc=cadrlist1,] 	 
[ccaddr=cadrlist2,] 	 
[bccaddr=bcadrlist,] [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.

toaddr=%[app/]addresslist.fex

Is a FOCEXEC that generates an email recipient list at run time. Email clients will use the toaddr value in an email client Reply To All. The actual FOCEXEC may go against any data source for the addresses, but must PRINT a single column and use ON TABLE PCHOLD FORMAT COMT FORMATTED syntax to format the data (as one email address enclosed in double quotation marks per row).

The actual FOCEXEC extension must be .fex in the specification. This feature also only works in a running server context. It is not supported in any other mode.

cc=cadrlist1

Is the carbon copy recipient displayed by the user email client (and used in an email client Reply To All, if a ccaddr 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 cc parameter is used in conjunction with ccaddr, the value of cc may be an arbitrary string, such as Group Managers, which most email clients will display as a pseudo title in the Cc field, without displaying the actual addresses used in the ccaddr parameter. A forced blank can be supped for the Cc field by using to="".

ccaddr=cadrlist2

Is the carbon copy recipient. If not supplied, SMTP servers will use the cc header. Email clients will use the ccaddr 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 (').

bccaddr=bcadrlist

Is the blind carbon copy recipient. Email clients will use the bccaddr 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 single or double 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