THE - The Hessling Editor
Query, Extract
and Status

The following lists the valid variables that can be queried and also shows what values are returned. For both QUERY and STATUS, the values are concatenated together and displayed as a single line. For EXTRACT the REXX variables that are set are defined. The capitalised portion of the variable is the minimum abbreviation recognised.

The bracketed text at the end of the description indicates from which commands a valid response will be supplied.

ALT

The number of alterations to the current file since the last SAVE or automatic save via SET AUTOSAVE.

(QES)

alt.0	-	2
alt.1	-	Number of alterations since last SAVE or autosave
alt.2	-	Number of alterations since last SAVE

ARBchar

The status of SET ARBCHAR and the ARBCHAR characters.

(QEMS)

arbchar.0	-	3
arbchar.1	-	ON|OFF
arbchar.2	-	multiple match character
arbchar.3	-	single match character

AUtosave

The status of SET AUTOSAVE and/or the frequency setting.

(QEMS)

autosave.0	-	1
autosave.1	-	OFF|n

BACKup

Indicates if a .bak file is kept after editing.

(QEMS)

backup.0	-	1
backup.1	-	ON|OFF|TEMP|KEEP

BEEP

Indicates if the bell is sounded on display of error messages. Set by SET BEEP

(QEMS)

beep.0	-	1
beep.1	-	ON|OFF

BLOCK

Returns information about the marked block, if any.

(E)

block.0	-	6 if a marked block exists, or 1 for NONE
block.1	-	type of marked block (LINE|BOX|NONE|WORD|COLUMN)
block.2	-	line number of start of block
block.3	-	column number of start of block
block.4	-	line number of end of block
block.5	-	column number of end of block
block.6	-	file name containing marked block

CASE

The settings related to the CASE of characters entered, searched for, changed and sorted. Set by SET CASE

(QEMS)

case.0	-	4
case.1	-	MIXED|UPPER|LOWER
case.2	-	RESPECT|IGNORE
case.3	-	RESPECT|IGNORE
case.4	-	RESPECT|IGNORE

CLEARScreen

Indicates if the screen is cleared on exit from THE. Set by SET CLEARSCREEN.

(QEMS)

clearscreen.0	-	1
clearscreen.1	-	ON|OFF

CLOCK

Indicates if the time is displayed on the status line. Set by SET CLOCK.

(QEMS)

clock.0	-	1
clock.1	-	ON|OFF

CMDArrows

Returns the settings for arrow key behaviour on command line. Set by SET CMDARROWS.

(QEMS)

cmdarrows.0	-	1
cmdarrows.1	-	RETRIEVE|TAB

CMDline

The settings for the command line. Set by SET CMDLINE.

(QEMS)

If CMDLINE OFF

cmdline.0	-	1
cmdline.1	-	OFF

If CMDLINE ON, BOTTOM or TOP

cmdline.0	-	3
cmdline.1	-	ON|TOP|BOTTOM
cmdline.2 *	-	line number within window of command line
cmdline.3 *	-	contents of command line

* these values are only returned with

COMPAT

The settings for the compatibility mode. Set by SET COMPAT.

(QEMS)

compat.0	-	1
compat.1	-	THE|XEDIT|KEDIT

CURline

The value and position of the current line within the current file. Set by SET CURLINE.

(QEMS)

With EXTRACT command:

curline.0	-	3
curline.1	-	curline setting
curline.2	-	line number within window of current line
curline.3	-	contents of current line

With QUERY, MODIFY and STATUS commands:

curline.0	-	1
curline.1	-	curline setting

CURSor

The position of the cursor within the displayed screen and file at the time the EXTRACT /CURSOR/ is issued and the position of the cursor at the time the macro was issued. If the cursor is not in the filearea, then line and column values will be set to -1.

(QE)

cursor.0	-	8
cursor.1	-	line number of cursor in screen (current)
cursor.2	-	column number of cursor in screen (current)
cursor.3	-	line number of cursor in file (current)
cursor.4	-	column number of cursor in file (current)
cursor.5	-	line number of cursor in screen (original)
cursor.6	-	column number of cursor in screen (original)
cursor.7	-	line number of cursor in file (original)
cursor.8	-	column number of cursor in file (original)

CURSORSTay

The setting for the behaviour of the cursor after a file scroll. Set by SET CURSORSTAY.

(QEMS)

cursorstay.0	-	1
cursorstay.1	-	ON|OFF

DIRFILEID

The value of the path and filename of the focus line in a DIR.DIR file.

(E)

dirfileid.0	-	2
dirfileid.1	-	full path of directory
dirfileid.2	-	file name at focus line

DISPlay

Indicates the range of selection levels current. Set by SET DISPLAY.

(QEMS)

display.0	-	2
display.1	-	display low value
display.2	-	display high value

EOF

Indicates if the current line is on the Bottom-of-File line.

(QES)

eof.0	-	1
eof.1	-	ON|OFF

EOLout

Returns the value of the end-of-line character(s).

(QEMS)

eolout.0	-	1
eolout.1	-	LF|CRLF|CR|NONE

ETMODE

Indicates if extended display mode is set. Set by SET ETMODE.

(QEMS)

etmode.0	-	1
etmode.1	-	ON|OFF

FNAME

The file name of the current file.

(E)

fname.0	-	1
fname.1	-	File name.

FPATH

The path name of the current file. This includes a trailing directory separator.

(E)

fpath.0	-	1
fpath.1	-	File path.

FTYPE

The extension of the current file. The characters following the trailing . character.

(E)

ftype.0	-	1
ftype.1	-	File extension.

GETENV variable

The value of the supplied environment variable or ***invalid*** if the variable does not exist.

(E)

getenv.0	-	1
getenv.1	-	value of variable

HEX

Indicates if hexadecimal values in commands are interpreted as hexadecimal values or not.

Set by SET HEX.

(QEMS)

hex.0	-	1
hex.1	-	ON|OFF

HEXDISPlay

Indicates if the current character is displayed on the status line. Set by SET HEXDISPLAY.

(QEMS)

hexdisplay.0	-	1
hexdisplay.1	-	ON|OFF

HEXShow

Returns details of HEXSHOW placement. Set by SET HEXSHOW.

(QEMS)

hexshow.0	-	2
hexshow.1	-	ON|OFF
hexshow.2	-	line displaying first hexshow line

IDline

Indicates if the idline is displayed for a file. Set by SET IDLINE.

(QEMS)

idline.0	-	1
idline.1	-	ON|OFF

IMPMACro

Indicates if implied macro processing is on or off. Set by SET IMPMACRO.

(QEMS)

impmacro.0	-	1
impmacro.1	-	ON|OFF

IMPOS

Indicates if implied operating system command processing is on or off. Set by SET IMPOS or SET IMPCMSCP.

(QEMS)

impos.0	-	1
impos.1	-	ON|OFF

INSERTmode

Indicates if currently in insert mode or overstrike mode. Set by SET INSERTMODE.

(QEMS)

insertmode.1	-	1
insertmode.1	-	ON|OFF

LASTmsg

Return the text of the last error message generated.

(E)

lastmsg.0	-	1
lastmsg.1	-	text of last message.

LASTRC

Return code from last command issued from command line.

(QES)

lastrc.0	-	1
lastrc.1	-	Last return code.

LENgth

Length of the current line.

(QES)

length.0	-	1
length.1	-	Length of current line.

LIne

Line number of current line in current file.

(QES)

line.0	-	1
line.1	-	Line number

LINENd

Indicates if multiple commands allowed on command line and the delimiter. Set by SET LINEND.

(QEMS)

linend.0	-	2
linend.1	-	ON|OFF
linend.2	-	delimiter

LScreen

Displays the size of the current screen and window. Also shows the upper left corner of the window.

(QE)

lscreen.0	-	6
lscreen.1	-	height of current window
lscreen.2	-	width of current window
lscreen.3	-	screen line of upper left corner of window
lscreen.4	-	screen column of upper left corner of window
lscreen.5	-	height of screen
lscreen.6	-	width of screen

MACROExt

The current setting for a macro's file extension. Set by SET MACROEXT.

(QEMS)

macroext.0	-	1
macroext.1	-	Default file extension

MACROPath

The path that THE looks for by default for macro files. Set by SET MACROPATH.

(QEMS)

macropath.0	-	1
macropath.1	-	Path for macro files.

MARgins

The settings for left and right margins and paragraph indent. Set by SET MARGINS.

(QEMS)

margins.0	-	3
margins.1	-	left column
margins.2	-	right column
margins.3	-	indent value (column or offset from left margin)

MONITOR

Indicates if the combination of monitor and the curses package supports colour. If the curses package supports colour, then monitor.3 is set to COLOR and monitor.2 can be COLOR or MONO depending on whether the monitor supports colour. If monitor.3 is MONO then monitor.2 will also be set to MONO.

(QES)

monitor.0	-	2
monitor.1	-	COLOR|MONO
monitor.2	-	COLOR|MONO

MSGLine

Returns details of where the message line is displayed. Set by SET MSGLINE.

(QEMS)

msgline.0	-	2
msgline.1	-	ON
msgline.2	-	line position of
msgline.3	-	number of message lines available
msgline.4	-	OVERLAY

MSGMode

Indicates if messages are suppressed. Set by SET MSGMODE.

(QEMS)

msgmode.0	-	1
msgmode.1	-	ON|OFF

NBFile

Returns with the number of files currently in the ring.

(QES)

nbfile.0	-	1
nbfile.1	-	Number of files in ring

NEWLines

Indicates if NEWLINES variable is set to LEFT or ALIGNED. Set by SET NEWLINES.

(QEMS)

newlines.0	-	1
newlines.1	-	ALIGNED|LEFT

NONDisp

Returns the character that is displayed for extended characters that are not displayed. Set by SET NONDISP.

(QEMS)

nondisp.0	-	1
nondisp.1	-	char

NUMber

Indicates if line numbers are displayed in the prefix area. Set by SET NUMBER.

(QEMS)

number.0	-	1
number.1	-	ON|OFF

PENDing [BLOCK] [OLDNAME] name|*

Returns information about pending prefix commands.

(E)

pending.0	-	4
pending.1	-	line number in file
pending.2	-	newname - actual name entered in prefix area
pending.3	-	oldname - original name of macro after synonym resolution
pending.4	-	BLOCK or null

Point [*]

Returns the name and line number of the focus line, or names and line numbers of all lines in a file if * is specified.

(QE)

With no arguments:

point.0	-	0 or 1 (0 if focus line not named)
point.1	-	line number and name of line (if line is named)

With [ * ] argument:

(E)

point.0	-	number of named lines in the file
point.1	-	line number and name for first named line
point.n	-	line number and name for nth named line

POSition

Indicates if LINE/COL is displayed on idline . Set by SET POSITION.

(QMS)

position.0	-	1
position.1	-	ON|OFF

The current/focus line/column is also returned via EXTRACT.

(E)

position.0	-	3
position.1	-	ON|OFF
position.2	-	current or focus line
position.3	-	current or focus column

PREfix [Synonym [*]]

Indicates if prefix is displayed for the view and if displayed where is is displayed. See SET PREFIX.

(QEMS)

prefix.0	-	1 or 2 (1 if prefix.1 is OFF, 2 otherwise)
prefix.1	-	ON|OFF|NULLS
prefix.2	-	LEFT|RIGHT (if prefix.1 is ON or NULLS)

With [ Synonym ] option, the name of the macrofile (oldname) is returned that is associated with the synonym. If name is not a synonym then name is returned.

(E)

prefix.0	-	1
prefix.1	-	oldname

With [ Synonym [ * ]] option, all prefix synonyms are returned.

(E)

prefix.0	-	number of prefix synonyms
prefix.1	-	newname oldname
prefix.n	-	newname oldname

PRINTER

Returns the value of the printer port or spooler. Set by SET PRINTER.

(QEMS)

printer.0	-	1
printer.1	-	port or spooler name

REPROFile

Indicates if the profile is to be re-executed for each subsequent file to be edited. Set by SET REPROFILE.

(QEMS)

reprofile.0	-	1
reprofile.1	-	ON|OFF

RESERved [*]

Return with list of the screen rows that have been reserved. Set by SET RESERVED.

(QES)

reserved.0	-	0 if no reserved lines; 1 otherwise
reserved.1	-	list of screen row numbers reserved

With [ * ] option, the line number, followed by the colour specification and reserved line contents are returned; one variable for each reserved line.

(E)

reserved.0	-	the number of reserved lines
reserved.1	-	first reserved line
reserved.2	-	second reserved line
reserved.n	-	nth reserved line

REXXOUTput

Indicates if REXX output is captured to a file or not and the line number limit of lines to be displayed. Set by SET REXXOUTPUT.

(QEMS)

rexxoutput.0	-	2
rexxoutput.1	-	FILE|DISPLAY
rexxoutput.2	-	line number limit

RING

Returns details of each file being edited.

(QE)

ring.0	-	number of files in the
ring.1	-	IDLINE of first file in the ring
ring.2	-	IDLINE of second file in the ring
ring.n	-	IDLINE of nth file in the ring

SCALe

Returns details of scale line. Set by SET SCALE.

(QEMS)

scale.0	-	2
scale.1	-	ON|OFF
scale.2	-	line displaying scale line

SCOPE

Returns information about whether shadow lines will be affected by commands or not. Set by SET SCOPE.

(QEMS)

scope.0	-	1
scope.1	-	ALL|DISPLAY

SCReen

Returns the number and orientation of THE screens. Set by SET SCREEN.

(QEMS)

screen.0	-	2
screen.1	-	Number of screens displayed
screen.2	-	HORIZONTAL|VERTICAL

SELect

Returns the selection level of the focus line and the maximum selection level for the file. Set by SET SELECT and ALL commands.

(QES)

select.0	-	2
select.1	-	selection level of focus line
select.2	-	maximum selection level for file

SHADow

Returns the status of the display of shadow lines. Set by SET SHADOW.

(QEMS)

shadow.0	-	1
shadow.1	-	ON|OFF

SHOWkey key

Returns the commands and parameters assigned to the key passed as an argument. This keyvalue is returned as READV.3 from a call to READV KEY.

(E)

showkey.0	-	the number of commands assigned
showkey.1	-	first command/parameter assigned
showkey.n	-	last command/parameter assigned

SIze

Returns the number of lines in the current file.

(QES)

size.0	-	1
size.1	-	Lines in current file.

STATUSLine

Indicates if the status line is displayed and if so, where. Set by SET STATUSLINE.

(QEMS)

statusline.0	-	1
statusline.1	-	TOP|BOTTOM|OFF

STAY

Indicates if the focus line stays where it is after a successful THE command or an unsuccessful LOCATE command. Set by SET STAY.

(QEMS)

stay.0	-	1
stay.1	-	ON|OFF

TABKey

Returns settings about behaviour of TAB key. tabkey.1 indicates behaviour while not in insert mode tabkey.2 indicates behaviour while in insert mode Set by SET TABKEY.

(QEMS)

tabkey.0	-	2
tabkey.1	-	TAB|CHARACTER
tabkey.2	-	TAB|CHARACTER

TABLine

Returns details of if and where the tab line is displayed. Set by SET TABLINE.

(QEMS)

tabline.0	-	2
tabline.1	-	ON|OFF
tabline.2	-	line displaying tab line

TABS

Returns settings about tab columns. Set by SET TABS.

(QEMS)

tabs.0	-	2
tabs.1	-	tab columns

TABSIn

Indicates if TABSIN processing is on or off and the size of the tabs setting. Set by SET TABSIN.

(QEMS)

tabsin.0	-	2
tabsin.1	-	ON|OFF
tabsin.2	-	size of tabs

TABSOut

Indicates if TABSOUT processing is on or off and the size of the tabs setting. Set by SET TABSOUT.

(QEMS)

tabsout.0	-	2
tabsout.1	-	ON|OFF
tabsout.2	-	size of tabs

TERMinal

Identifies the terminal type currently being used.

(QES)

terminal.0	-	1
terminal.1	-	DOS|OS2|X11|$TERM value under Unix

TOF

Indicates if the current line is on the Top-of-File line.

(QES)

tof.0	-	1
tof.1	-	ON|OFF

TYPEAhead

Indicates if THE will wait until all keyboard input has been processed before updating the screen display. Set by SET TYPEAHEAD.

(QEMS)

typeahead.0	-	1
typeahead.1	-	ON|OFF

Verify

Returns verify column settings. Set by SET VERIFY.

(QEMS)

verify.0	-	1
verify.1	-	Column pair of verify start and end columns.

VERShift

Returns vertical shift value.

(QES)

vershift.0	-	1
vershift.1	-	VERSHIFT value

VERSION

Returns information about name of application (THE) and version information.

(QES)

version.0	-	4
version.1	-	THE
version.2	-	version string e.g. 1.5
version.3	-	platform version (DOS,OS2,UNIX,X11)
version.4	-	version status information e.g. beta

Width

Returns maximum line width setting. Set by -w command line switch on starting THE.

(QES)

width.0	-	1
width.1	-	Maximum line width value.

WORDWrap

Indicates if WORDWARP is on or off. Set by SET WORDWRAP.

(QEMS)

wordwrap.0	-	1
wordwrap.1	-	ON|OFF

XTERMinal

Returns the current value of the X11 terminal program. Only applicable in X version. Set by SET XTERMINAL.

(QEMS)

xterminal.0	-	1
xterminal.1	-	X11 terminal program

Zone

Returns zone column settings. Set by SET ZONE.

(QEMS)

zone.0	-	2
zone.1	-	Zone start column
zone.2	-	Zone end column

The above REXX variables set by the EXTRACT command may also be obtained by a REXX macro as an implied EXTRACT. Each variable above that may be set by an explicit EXTRACT command may also be used as an external function to REXX to obtain the same information. E.g. The REXX commands:

'EXTRACT /SIZE/CURLINE/'
Say size.1 curline.1

may be substituted with:

Say size.1() curline.1()

THE also provides other information to the REXX interpreter via boolean functions. These functions return either 1 or 0 depending on the information queried.

after()

Returns 1 if the cursor is currently after the last non-blank character on the line, or if the line is blank.

blank()

Returns 1 if the line the cursor field is completely blank.

batch()

Returns 1 if THE is being run in batch mode. i.e. THE was started with the -b switch.

block()

Returns 1 if the marked block is within the current view.

before()

Returns 1 if the cursor is currently before the first non-blank character on the line, or if the line is blank.

bottomedge()

Returns 1 if the cursor is on the bottom edge of the filearea or prefix area.

command()

Returns 1 if the command line is on. This is different to the definition in KEDIT; "Returns 1 if the cursor is on the command line." To get the equivalent KEDIT functionality use incommand();

current()

Returns 1 if the cursor is on the current line.

dir()

Returns 1 if the current file is the special DIR.DIR file.

end()

Returns 1 if the cursor is on the last non-blank character on the line.

eof()

Returns 1 if the cursor is on the Bottom-of-File line and the cursor is not on the command line.

first()

Returns 1 if the cursor is in column 1 of the current window.

focuseof()

Returns 1 if the focus line is the Bottom-of-File line whether the cursor is on it or not.

focustof()

Returns 1 if the focus line is the Top-of-File line whether the cursor is on it or not.

inblock()

Returns 1 if the cursor is in the marked block.

incommand()

Returns 1 if the cursor is on the command line.

initial()

Returns 1 if the function is called from the profile.

inprefix()

Returns 1 if the cursor is located in the prefix area.

leftedge()

Returns 1 if the cursor is on the left edge of the filearea.

modifiable()

Returns 1 if the cursor is located in an area that can be changed. i.e. not on Top-of-File line or Bottom-of-File line nor on a shadow line.

rightedge()

Returns 1 if the cursor is on the right edge of the filearea.

spacechar()

Returns 1 if the cursor is on a space character.

tof()

Returns 1 if the cursor is on the Top-of-File line and the cursor is not on the command line.

topedge()

Returns 1 if the cursor is on the top edge of the filearea.

verone()

Returns 1 if the column 1 of the file is being displayed in column 1.

 

The following functions provide features to simplify THE macros written in REXX.

valid_target(target[,anything])

The first argument is the target to be validated. If a second, optional argument is supplied, the target to be validated can consist of a target followed by any optional characters. This can be useful if the arguments to a macro consist of a target followed by another argument. If a valid target is supplied, the remainder of the string passed to valid_target() is returned following the first line affected and the number of lines to the target.

Returns ERROR if the supplied target is invalid. Returns NOTFOUND if the supplied target is valid, but not found.

If a valid target, returns the first line affected by the target followed by the number of lines to the target, and optionally the remainder of the argument. e.g.

If the focus line is 12 and valid_target() is called as

result = valid_target(":7")      ===> result = "12 -5"

if the focus line is 12 and valid_target is called as

result = valid_target(":7 /fred/",junk), ===> result = "12 -5 /Fred/"

run_os(command[,stdin_stem[,stdout_stem[,stderr_stem]]])

This function allows the macro writer to call an operating system command and have the standard streams; stdin , stdout and stderr redirected to or from REXX arrays.

The first argument is the operating system command to execute. The command can include any command line switches appropriate to the command.

All other arguments comprise a stem name (including a trailing . ) which refers to the REXX arrays where stdin , stdout and stderr are to be redirected.

As with all REXX arrays, the value of the 0th element (stem.0) contains the number of elements in the array.

The only restriction with the names of the stem variables is that the stem name for the stdin stem cannot be the same as the stem for stdout or stderr .

The stem name for stdout and stderr can be the same; the contents of the resulting output stems will consist of stdout and stderr in the order that the command generates this output.

Return values:

0 - successful

1005 - invalid argument or syntax

1012 - problems with system redirection of streams

1094 - out of memory

1099 - error interfacing to REXX interpreter

all other numbers, return code from operating system command

e.g. to spell check the words "The Hessling Editr" with ispell

in.0 = 3
in.1 = "The"
in.2 = "Hessling"
in.3 = "Editr"
rc = run_Os("ispell -a","in.","out.")

sets:

out.0 --> 3

out.1 --> "*"

out.2 --> "#"

out.3 --> "& edits edit editor"