Ask User Prompt

AskUser

The AskUser procedure prompts the end user for a reply to a message. The message is displayed in a window/dialog box.

The dialog box contains the programmer-provided message text in a windowed display file record format. Up to 4 lines of text may be specified. Use the \n symbol to indicate a new line in the message text. A reply is returned as a one-position character value.

reply =  AskUser(
  szMsg           120A  Const Varying 
  szOptions        10A  Const Varying Options(*NOPASS : *OMIT) 
  szDftReply        1A  Const         Options(*NOPASS : *OMIT) 
  szPromptMsg      10A  Const Varying Options(*NOPASS : *OMIT) 
  szTitleText      35A  Const Varying Options(*NOPASS)
)

Parameters

szMsg: [ input VChar(120) const ] Up to 120 characters of message text may be displayed. Specify the message text as one continuous stream of text. If you would like line breaks, embed a backslash followed by a lower case 'n' , for example: \n

szOptions [ optional ] DFT('YN'): [ input VChar(10) const ] Specify a list of valid responses the user may specify. Each response is one character in length and up to 10 responses may be specified. The responses are displayed to the right of the reply field separated with a forward slash. For example, to limit the reply to the number 1, 2 and 3, specify '123'. In the prompt, these replies will be displayed for the user as '1/2/3'.

szDftReply [ optional ] DFT(first option): [ input Char(1) const ] Specify the default reply if the user should not specify a reply (i.e., an empty or blank reply is processed). If no default reply is specified, then the character specified in position 1 of the szOptions parameter is used as the default reply. The following special values may be specified as the default reply.

szPromptMsg [ optional ] DFT('Reply'): [ input VChar(10) const ] Up to 10 characters of message text may be specified. This text is displayed to the left of the reply field. If the prompt message text is not 10 positions in length, it is padded on the right with periods and blanks. For example 'Exit' will result in 'Exit . . .' being displayed.

szTitleText [ optional ] DFT('Message Box'): [ input VChar(35) const ] Up to 35 characters of text may be specified. This text is displayed in the top bar of the pop up window that is displayed.

Return Value

If the function succeeds, the return value is the reply that the end user typed into the reply field. If the function fails or the end-user presses F3 or F12, then a blank is returned.

Example

      /INCLUDE QCPYSRC,ASKUSER

D YES S 1A Inz('Y')

     C                   if        AskUser('Are you sure?') = YES

     C*** do something because the user said Yes!

     C                   endif

In this example, a dialog box (popup up window) is displayed with the message "Are you sure?". The default reply is YN so the end use may respond with Y or N. If they respond with Y, then condition in this example is true and processing continues.

Special Value	Meaning
#	Allow blanks. A blank is both the initial value and the default reply. If a blank is entered for the reply, it is accepted and returned to the caller.
*	Any value may be entered, the reply is not limited to the list of replies specified on the szOptions parameter.