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

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

Reference Type: Supported, Category: XGF Function Library, Integration Agreement: 3173

Description

This extrinsic function provides a way to perform READs using escape processing. READs, when escape processing is turned on, are terminated by: <UP-ARROW> ("↑"), <DOWN-ARROW> ("↓"), <PREV> ("←"), <NEXT> ("→"), <TAB>, and other special keystrokes.

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

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 Parameters

returns:

Returns the string READ from the user.

XGRT:

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

NOTE: For a list of possible values, please refer to the list below or the table in routine XGKB.

DTOUT:

If defined, signifies that the READ timed out.

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

 


VA (Internet) / VA(Intranet) / OI / PD / Site Map / Terms of Use / VA Privacy Policy / Accessibility

Reviewed/Updated: August 26, 2011

If you have questions, need more information, or are having accessibility problems with this website, please contact us by E-Mail: Webmasters, Phone: 510-768-6800, or FAX: 510-768-6850.