Home Page The Club Computers News Links Glossary EYAWTK
Before Amiga Background ICS OCS ECS AGA ??? PPC
U-Boot SLB Linux Amiga OS Dual Boot Motherboards Peripherals Other
Initialisation Installation OS4 Updates About OS4 File Systems Networking Printing Other
Introduction File System Workbench Preferences Commands Error Msgs Miscellaneous

AmigaOS 4.0 - About OS4 - Commands

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
REQUESTSTRING is used to request string data from a user during the execution of an AmigaDOS or ARexx script, which can subsequently be used by the script. REQUESTSTRING requires a minimum of two arguments; the title and body arguments.

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:

If "Amiga User" was entered and Ok was clicked, the following would be displayed on the console:

    "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:

If "mysecret" was entered as the password, it would only show as asterisks in the requester, and when Ok was clicked, nothing would be displayed on the console because the TO argument was specified, but ENV:pwd would contain the value:

    3.OS4:> GETENV pwd
    "mysecret"

On the other hand, if Cancel was clicked, ENV:pwd would contain "".

See also: ASK, REQUESTCHOICE, REQUESTFILE.


Return to Commands Selection

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.


Copyright 2006 Amiga Auckland Inc. All rights reserved.
Revised: February 9, 2006.