The GET statement receives unprompted input from an attached line.
Format
GET var [,length] [SETTING count-var] FROM line [UNTIL term-expr] [RETURNING term-var] [WAITING seconds] [THEN | ELSE statements] |
Parameter(s)
var |
Assigns the received input to variable var. |
length |
An expression evaluating to the number of characters to wait for from the attached line. The default is 1 character, unless the UNTIL clause is used, in which case there is no limit if one is not explicitly specified. |
SETTING count-var |
Assigns the variable count-var to the number of characters taken from the attached line. |
FROM line |
line evaluates to the attached line to receive input from. |
UNTIL term-expr |
An expression evaluating to a string of characters, any of which are taken as a terminating character for the accepted input. Characters often used for the UNTIL clause are carriage return (CHAR(13)) and linefeed (CHAR(11)). The terminating character does not appear in the returned text var. |
RETURNING term-var |
Assigns to the variable term-var the character, if any, which forced the end of input. If the input terminated due to the maximum number of characters being reached, due to a timeout condition, or due to a segment mark (CHAR(255)) having been read, then the variable term-var contains the null string. |
WAITING seconds |
seconds evaluates to the number of seconds to wait before timing out. |
THEN statements |
See THEN and ELSE Clauses for information on the THEN clause. |
ELSE statements |
See THEN and ELSE Clauses for information on the ELSE clause. |
Description
The GET statement accepts input from an attached line. No prompt is printed, and all control characters including carriage return and linefeed are accepted as input characters. If the line is not attached, the ELSE clause is executed; if the line is not attached and there is no ELSE clause, a run-time error is printed and the user enters the mvBASIC Debugger.
The characters taken from the attached line are echoed to the line. To suppress character echo, use the ECHO OFF statement. Control characters (CHAR(1) to CHAR(31)) are never echoed to the attached line.
The behavior of the GET statement varies according to what termination conditions are specified and whether the THEN or ELSE clauses are specified.
Input from the attached line may normally be terminated in four ways:
When the number of expected characters is read. If the number of characters is not explicitly specified and an UNTIL clause is not used, only one character is accepted. Note that the only time the GET statement does not have a maximum to the number of characters it accepts is when the UNTIL clause is used without a length having been explicitly specified.
When any one of the characters specified by the UNTIL clause is encountered in the input. When one of these characters is read from the attached line, the GET statement terminates and the variable var is assigned all characters up to the terminating character. If the RETURNING clause is used, the variable term-var is assigned to the terminating character.
Upon reading the segment mark character, CHAR(255).
If a number of seconds has been specified with the WAITING clause, and none of the conditions listed above has been met before the number of seconds has elapsed.
The GET statement cannot be used to read CHAR(255) from a remote device, since this character is generally taken as the end of data. To read this character, the GETX statement should be used, which translates data into its ASCII hexadecimal format before assigning it to a variable. GETX statement for more information.
For the GET statement, the THEN and ELSE clauses have different meanings and produce different results, depending on what conditions are specified for terminating input. The following rules apply only if the THEN or ELSE clause is specified.
If the UNTIL clause is used without a WAITING clause or an expected length, the GET statement behaves normally. The program waits indefinitely until a termination character is read, and the THEN clause is executed. The ELSE clause is never executed in this case!
If the WAITING clause is used, the GET statement behaves normally, and the ELSE clause is executed only if the number of seconds for timeout has elapsed. If the input is terminated for any other reason, the THEN clause is executed. In either case, whatever data was read from the attached line is placed in var.
If the WAITING clause is not used and there is a finite number of characters to expect in the input, then only the type-ahead buffer is examined for input. If the type-ahead buffer contains the expected number of characters, the THEN clause is executed; otherwise, the ELSE clause is executed. In either case, whatever data was read from the attached line is placed in var. Note that if the type-ahead feature has been turned off, the ELSE clause is always executed.
In a special case, the ELSE clause is executed if the line has not been attached before executing the GET statement.
In short, unless the WAITING clause is used, specifying the THEN and ELSE clauses causes the GET statement to behave like an INPUTIF...FROM statement. The exception to this is the UNTIL clause without a maximum length specified, in which case the GET statement behaves normally and the ELSE portion of the statement is never used.
Example
To assign the variable RESP to the first 5 characters from line 7, the code would read:
GET RESP,5 FROM 7 |
In this application the GET statement is used for a two-way communication program. Before the communication begins, the type-ahead buffer for the remote process is cleared with the PROTOCOL command, and the remote user is prompted to type a character within 60 seconds. If the remote user does not respond, the program exits.
If the remote user responds, a loop begins using the GET statement to capture input from the type-ahead buffer of the local process as well as the remote process. If a character is in the type-ahead buffer, the program proceeds to print it on the other screen. If the type-ahead buffer is empty, no action is taken.
PRINT "ENTER PROCESS NUMBER" : INPUT LINE THIS.LINE = SYSTEM(18) SEND "2-WAY COMMUNICATION PROGRAM" TO LINE ELSE ... SEND "PRESS ANY KEY TO CONTINUE." TO LINE ELSE ... PRINT "WAITING FOR RESPONSE FROM REMOTE LINE ..." EXECUTE "PROTOCOL " : LINE : " (C)" GOSUB CLEARSCREENS GET CHAR2 FROM LINE WAITING 60 ELSE PRINT "NO RESPONSE FROM PROCESS " : LINE SLEEP 2 GOSUB EXIT END LOOP GET CHAR1 FROM THIS.LINE THEN . . . END GET CHAR2 FROM LINE THEN . . . END UNTIL ... DO REPEAT |
See Also