KEYIN()

KEYIN(), KEYINC(), KEYINR()

Top  Previous  Next

 

The KEYIN(), KEYINC() and KEYINR() functions read a single keystroke from the keyboard.

 

 

Format

 

KEYIN({timeout})

KEYINC({timeout})

KEYINR({timeout})

 

 

The KEYIN() function pauses program execution until a key is pressed. The character associated with that key is returned as the value of the function. The character is not echoed to the display.

 

The KEYINC() function is identical except that the case of alphabetic characters is inverted if case inversion has been enabled.

 

The KEYINR() function reads a single character with no internal processing. In particular, null characters are not removed and char(10) and char(13) are passed through without any special handling.

 

The KEYINR() function is redundant from release 2.1-8 as QM now honours the setting of the telnet binary mode parameter. The function will be retained as a synonym for KEYIN() for the foreseeable future.

 

KEYIN(), KEYINC() and KEYINR() do not take data from the DATA statement queue.

 

The optional timeout parameter specifies a period in seconds after which the function will return if no input is received. In this case the returned value is a null string and the STATUS() function will return ER$TIMEOUT. The timeout value may be fractional to specify timeouts of less than one second. Values less than 10mS or greater than 24 hours may not behave correctly.

 

A null string is also returned when taking input from a pipe if the piped data stream is exhausted. In this case the STATUS() function will return ER$EOF. The value returned by the STATUS() function is not significant unless KEYIN() has returned a null string.

 

 

Character Values

 

On Windows console sessions, special keys such as the function keys, ALT sequences and special keys (Home, Delete, cursor moves, etc) are represented by characters with values in the range 128 to 227, effectively rendering the characters normally in these positions unusable with these functions. See KEYINV() for an alternative way to read a single keystroke. Click here for a table of key code values.

 

 

See also:

IN, KEYCODE(), KEYINV() KEYREADY()