PROMPT

From CometWiki

PROMPT

Syntax:
The PROMPT statement has several variations:
PROMPT %PromptName% length prompt-string [default value]
PROMPT %PromptName% length prompt-string [ENTER program,dir,"message"]
PROMPT %PromptName% ENTER program,dir,"message"
PROMPT CAPTION caption-string

Placement:
The PROMPT statements need to be defined before their use as a replacement string. It is recommended that they be located at the top of the report spec.

Discussion:
The PROMPT statement is used to prompt the operator at runtime for a value to be used to replace text in a Reporter command. For example, the operator can be prompted for a printer name, a range of dates, or the text for a TITLE statement. One PROMPT statement is used for each value to be replaced. It is best to group all PROMPT statements for the report together. At runtime the Reporter collects the PROMPT statements and creates a dialog to prompt the operator for each of the replacement strings in the group. When a default value is specifed in the PROMPT the dialog is populated with that value.

The ENTER option expands the possibilities for prompting the operator for replacement strings. ENTER programs can popup date pickers, customer lists, etc. To assist you with two of the most popular uses of this statement Signature Systems has provided the source for a date picker (datepick.ibs) and printer picker (ptrpick.ibs) in the XTL folder so these programs may be customized to your needs. You will find the source in the XTL folder.

ENTERed programs are passed their messages in # buffer. Likewise, the ENTERed program passes its message back to the parent program in # buffer.

Examples:
PROMPT CAPTION Invoices for Specified Date Range
PROMPT %startdate% 8 From date: [ENTER datepick,,"YY/MM/DD,Enter from date"]
PROMPT %enddate% 8 To date: [ENTER datepick,,"YY/MM/DD,Enter to date"]
PROMPT %printer% 3 Printer name: [ENTER ptrpick]
PRINTER %printer%
TITLE Invoice from %startdate% thru %enddate%
INPUT invoice.header
REPORT
SELECTING inv.date ge %startdate% and inv.date le %enddate%
PRINT ivh.no;cust.no;inv.total

When the report runs, the Reporter pops up this dialog:

Notice the caption string at the top of the dialog. This came from the statement

PROMPT CAPTION Invoices for Specified Date Range

Each of the prompts in this example is associated with an ENTER program invoked when the control for the prompt gets the focus. When the operator clicks on the "From Date:" field, the Reporter ENTERs the datepick subprogram:

The caption on the date picker comes from the PROMPT statement:

PROMPT %startdate% 8 From date: [ENTER datepick,,"YY/MM/DD,Enter from date"]

The other parameter passed to datepick is the format specifying that the date will be returned in (YY/MM/DD) format.

When the printer prompt gets the focus, the ptrpick program is ENTERed:

After the operator clicks "OK" on the main dialog, the responses are written to the #CPROMPT file on TMP. This file is keyed by PARTITION$ + PROMPT name. Such as:

P00%product%
P00%company.name%
P00%5%

As the report spec is interpreted, string fields are parsed for a %..% pair. If found, the #CPROMPT file will be read to see if there is a replacement defined for the %..% prompt name. If not found, the string will be used as is, thus allowing for data to actually contain % signs.

The silent ENTER option provides a way to run a program without operator interface to provide the string substitution:

PROMPT %PromptName% ENTER program,dir,"message"

In this case a field for this substitution will not be included in the dynamically created dialog. The program will be ENTERed and its value saved for substitution later in the report. This can be useful for getting operator or other context-sensitive information that your application knows without having to ask the operator. Unlike ENTERed programs called from the dialog, silent ENTERed programs do not have a length specified for the return value. The value is returned in # buffer. If trailing blanks are an important part of the value, the value must be enclosed in quotes. In that case, the length of the replacement string will be the length of the value within the quotes. If not enclosed in quotes, the value will be stripped of trailing blanks and the resultant length of the string will be used for the replacement field length.