# vceBuildPromptList

Builds a list of message numbers from a text string.

#### Prototype

DWORD vceBuildPromptList ( VCEPROMPTHD prompthandle, unsigned method, char *text, unsigned list[], unsigned maxcount, unsigned *actualcount)

Argument | Description
prompthandle | Handle of the prompt table obtained through vceLoadPromptRules.
method | Table-specific method used for deciphering the specified text string.
text | Pointer to the string of text to translate.
list | Array to receive message numbers to use with vcePlayList.
maxcount | Maximum number of message numbers that can be put in list.
actualcount | Pointer to the returned number of messages. This number can be passed to vcePlayList.

#### Return values

Return value | Description
SUCCESS |
CTAERR_BAD_SIZE | maxcount is too small to contain the output list.
CTAERR_INVALID_HANDLE | prompthandle is not a valid handle to an open prompt rules table.
CTAERR_SVR_COMM | Server communication error.
VCEERR_BAD_PROMPT_COMMAND | Invalid method is entered (a value other than 0, 1, 2, 3, or 4) or an error exists in the rules table to which prompthandle refers.
VCEERR_PROMPT_BUILD_FAIL | Error exists in the prompt rules table to which prompthandle refers.

#### Details

vceBuildPromptList builds a list of message numbers based on the specified prompt rule table entry point and variable text. vceBuildPromptList only creates a message list. The application must open the corresponding voice file separately.

list is built by translating the text string into specific messages in the associated VOX file. The array must be large enough to contain the maximum number of message numbers in the list. For example, $1.25 is translated into six different messages (one, dollar, and, twenty, five, cents) using the American rules.

The standard rules provided in american.tbl are translated using the following methods:

Method | Description
--- | ---
0 | Based on the characters in the string, vceBuildPromptList decides if it is for date, time, number, monetary, day-of-week, or month utterances.
1 | Any number up to 999 trillion with or without commas. Can also handle numbers with decimal fractions.
2 | Date in mm/dd, mm/dd/yy, or mm/dd/yyyy formats.
3 | Time in hh:mm or hh:mm:ss formats. Hours must be in 24 hour time, for example, from 0 to 23.
4 | Monetary amounts with or without commas every three digits.

#### See also

vceUnloadPromptRules

#### Example

/* Demonstrates playing a text string */
char *text = "$1,234,567";
extern CTAHD CtaHd;
extern CTAQUEUEHD CtaQueueHd;
void mytestprompt ()
{
VCEHD vh;
VCEPROMPTHD prompthandle;
unsigned msglist[50];
unsigned count;
/* Open the associated voice file */
vceOpenFile (CtaHd, "american.vox", VCE_FILETYPE_VOX,
VCE_PLAY_ONLY, 0, &vh);
/* Load the American rules */
vceLoadPromptRules (CtaHd, "american.tbl", &prompthandle );
/* Translate the string into a list of messages in american.vox */
vceBuildPromptList (prompthandle, 0, text, msglist,
sizeof msglist/sizeof msglist[0], &count);
/* Play the messages */
vcePlayList (vh, msglist, count, NULL);
do
{
ctaWaitEvent( CtaQueueHd, &event, CTA_WAIT_FOREVER);
} while (event.id != VCEEVN_PLAY_DONE); /* Ignore other events */
/* Close the rules table */
vceUnloadPromptRules (prompthandle);
/* Close the associated voice file */
vceClose (vh);
}