Kernel 8.0 APIs Banner
Office of Information and Technology (OIT) Banner
[skip navigation]

$$READ^XGF(): Read Using Escape Processing

Reference Type: Supported, Category: XGF Function Library, ICR#: 3173

Description

The $$READ^XGF extrinsic function provides a way to perform READs using escape processing. READs, when escape processing is turned on, are terminated by:

$$READ^XGF is a low-level reader compared to the VA FileMan reader. In some respects it is as simple as using the M READ command. This READ function incorporates escape processing, which puts the burden on the operating system to READ the arrow, function, and all other keys.

A call to INITKB^XGF or PREP^XGF must be made at some point prior to calling $$READ^XGF.

If the number of characters you request with the first parameter is not entered, the READ does not terminate until some terminating character is pressed (or the timeout period is reached).

If you do not pass the timeout parameter, DTIME is used for the timeout period. If the READ times out, caret (^) is returned and DTOUT is left defined.

The list of mnemonics for keys that can terminate READs is:

XGF Function Library—Mnemonics for Keys that Terminate READs

Key Type Mnemonic
Control ^A, ^B, ^C, ^D, ^E, ^F, ^G, ^H, ^J, ^K, ^L, ^N, ^O, ^P, ^Q, ^R, ^S, ^T, ^U, ^V, ^W, ^X, ^Y, ^Z, ^\, ^], ^6, ^_
Cursor UP, DOWN, RIGHT, LEFT, PREV, NEXT
Editing FIND, INSERT, REMOVE, SELECT
Function F6 to F14, HELP, DO, F17 to F20
Keyboard TAB, CR
Keypad KP0 to KP9, KP-, KP+, KP., KPENTER
PF PF1, PF2, PF3, PF4

Format

  $$READ^XGF([no_of_char][,timeout])

Input Parameters

no_of_char:

(optional) Maximum number of characters to READ.
timeout:

(optional) Maximum duration of READ, in seconds.

Output Variables

XGRT:

Set to the mnemonic of the key that terminated the READ.

NOTE: For a list of possible values, see the list in the table above or the table in routine XGKB.
DTOUT:

If defined, signifies that the READ timed out.

Output

returns:

Returns the string READ from the user.

Examples

Example 1

To READ a name (with a maximum length of 30) from input and display that name on the screen, do the following:

 D INITKB^XGF("*")
 W "Name: " S NM=$$READ^XGF(30)
 D SAY^XGF(10,20,"Hello " NM)

Example 2

To accept only <Up-Arrow> ("↑") or <Down-Arrow> ("↓") keys to exit a routine, do the following:

 ;Only accept UP or DOWN arrow keys
 F  S %=$$READ^XGF(1) Q:XGRT="UP"!(XGRT="DOWN")

NOTE: When you set up the XGF keyboard environment using INITKB^XGF rather than PREP^XGF, the keypad is not automatically set to application mode. For READs to be terminated by the keypad keys (<KP0> to <KP9>, <KPENTER>, <KP+>, <KP->, and <KP>), the keypad must be in application mode. You can put the keypad in application mode by using an M WRITE statement (W IOKPAM to set application mode, IOKPNM to set numeric mode). Take care to preserve the value of $X when using a direct M WRITE, so that relative positioning in XGF cursor/text output calls is not thrown off:

  >S X=$X W IOKPAM S $X=X