| REQUESTSTRING | AmigaDOS |
| Purpose: | Allows AmigaDOS and ARexx scripts to use a string requester. |
| Format: | REQUESTFILE [TITLE <title>] [BODY <body>] [POSITIVE <text>] [NEGATIVE <text>] [DEFSTRING <default string>] [MAXLEN <maximum length>] [NOTEMPTY] [INVISIBLE] [TO <variable name>] [PUBSCREEN <public screen name>] [CHARSET <charset>] |
| Template: | TITLE/A, BODY/A, POSITIVE/K, NEGATIVE/K, DEFSTRING/K, MAXLEN/K/N, NOTEMPTY/S, INVISIBLE/S, TO/K, PUBSCREEN/K, CHARSET/K |
| Path: | C:REQUESTSTRING |
The TITLE argument specifies the title of the requester.
The BODY argument specifies the text for the body of the requester.
The POSITIVE option specifies the text to appear in the positive (left) choice in the file requester. The default is 'Ok'.
The NEGATIVE option specifies the text to appear in the negative (right) choice in the file requester. the default is 'Cancel'.
The DEFSTRING option specifies the default string to be displayed in the requester.
The MAXLEN option specifies the maximum length for the string, and prevents more than the specified number of characters from being entered. If the DEFSTRING option specifies a value longer than MAXLEN the displayed default value will be truncated, but the full value will be passed.
The NOTEMPTY option specifies that a string must be entered. No error message is displayed, but the requester will not close until a value is entered.
The INVISIBLE option specifies that the neither the default or entered value is to be displayed, so all characters are substituted with asterisks (*).
The TO argument specifies the file where to store the result string. If not specified, the string is written to the current default output file handle.
The PUBSCREEN argument allows the requester to open its window on a public screen.
The CHARSET argument allows to specify the charset of the strings given in the BODY, POSITIVE, NEGATIVE and DEFSTRING arguments. (The TITLE argument is always displayed in the charset of the screen font).
REQUESTSTRING will return with RETURN_FAIL (20) on any failure, with RETURN_WARN (5) if the user clicked the cancel gadget (the result string is the provided default string in this case), and with RETURN_OK(0) otherwise. The result string (or the default string if the user did cancel the requester) will be enclosed in quotation marks, then terminated with a linefeed, and written to the file specified with the TO argument or the current default output file handle.
Example 1:
3.OS4:> REQUESTSTRING "Identify Yourself" "Please enter your name"
displays the following requester:
"Amiga User"
On the other hand, if Cancel was clicked, the following would be displayed on the console:
""
Example 2:
3.OS4:> REQUESTSTRING "Welcome" "Password" INVISIBLE TO=ENV:pwd
displays the following requester:
3.OS4:> GETENV pwd
"mysecret"
On the other hand, if Cancel was clicked, ENV:pwd would contain "".
See also: ASK, REQUESTCHOICE, REQUESTFILE.
Disclaimer: Amiga Auckland have prepared the above information for the use of its members based on our experiences and as such is subject to revision at any time. Amiga Auckland cannot guarantee any of the information and cannot be held accountable for any issues that may result from using it.