DEC Text Processing Utility Reference Manual

Updated: 11 December 1998

Order Number: AA--PWCCB--TE

November 1996

This manual describes the elements of the DEC Text Processing Utility (DECTPU). It is intended as a reference manual for experienced programmers.

Revision/Update Information: This manual supersedes the DEC Text Processing Utility Reference Manual, Version 3.1 for OpenVMS Version 6.0.

Software Version: DEC Text Processing Utility Version 3.1 for OpenVMS Alpha Version 7.1 and OpenVMS VAX Version 7.1

Digital Equipment Corporation Maynard, Massachusetts

November 1996

Digital Equipment Corporation makes no representations that the use of its products in the manner described in this publication will not infringe on existing or future patent rights, nor do the descriptions contained in this publication imply the granting of licenses to make, use, or sell equipment or software in accordance with the description.

Possession, use, or copying of the software described in this publication is authorized only pursuant to a valid written license from Digital or an authorized sublicensor.

Digital conducts its business in a manner that conserves the environment and protects the safety and health of its employees, customers, and the community.

The following are trademarks of Digital Equipment Corporation: DEC, DECpaint, DECwindows, Digital, GIGI, OpenVMS, ULTRIX, ULTRIX Mail Connection, VAX, VAXcluster, VAX RMS, VAXstation, VMS, VMS/ULTRIX Connection, VT, and the DIGITAL logo.

The following are third-party trademarks:

Motif is a registered trademark of Open Software Foundation, Inc.

PostScript is a registered trademark of Adobe Systems Incorporated.

All other trademarks and registered trademarks are the property of their respective holders.

ZK6020

The OpenVMS documentation set is available on CD-ROM.

This document was prepared using VAX DOCUMENT, Version V3.2m.

Contents Index

Preface

Intended Audience

This manual is a reference for experienced programmers who want to program in the DEC Text Processing Utility (DECTPU). Some features of DECTPU, for example, the callable interface and the built-in procedure FILE_PARSE, are intended for system programmers who have a good understanding of OpenVMS system concepts.

Document Structure

This manual is organized as follows:

Chapter 1 lists DECTPU built-in features according to their function.
Chapter 2 contains complete descriptions of the DECTPU built-in functions.
Appendix A contains sample procedures written in DECwindows DECTPU.
Appendix B contains DECTPU messages.
Appendix C discusses cursor behavior in DECTPU applications.

Reader's Comments

Digital welcomes your comments on this manual.

Print or edit the online form SYS$HELP:OPENVMSDOC_COMMENTS.TXT and send us your comments by:

Internet openvmsdoc@zko.mts.dec.com

Fax 603 881-0120, Attention: OSSG Documentation, ZKO3-4/U08

Mail OSSG Documentation Group, ZKO3-4/U08
110 Spit Brook Rd.
Nashua, NH 03062-2698

How To Order Additional Documentation

Use the following table to order additional documentation or information. If you need help deciding which documentation best meets your needs, call 800-DIGITAL (800-344-4825).

Conventions

The name of the OpenVMS AXP operating system has been changed to the OpenVMS Alpha operating system. Any references to OpenVMS AXP or AXP are synonymous with OpenVMS Alpha or Alpha.

In this manual, every use of DECwindows and DECwindows Motif refers to DECwindows Motif for OpenVMS software.

The following conventions are also used in this manual:

Ctrl/ x Ctrl/ x indicates that you hold down the Ctrl key while you press another key or mouse button (indicated here by x).

PF n PF n indicates that you press the key labeled PF n on the numeric keypad, where n is 1, 2, 3, or 4.

x A lowercase italic x indicates the generic use of a letter. For example, xxx indicates any combination of three alphabetic characters.

n A lowercase italic n indicates the generic use of a number. For example, 19 nn indicates a 4-digit number in which the last 2 digits are unknown.

PF1 x The key sequence PF1 x indicates that you press and release PF1, and then you press and release another key or mouse button (indicated here by x).

[Return] A key name enclosed in a box indicates that you press that key.

{ } In format descriptions, braces indicate required elements. You must choose one of the elements.

[ ] In format descriptions, brackets indicate optional elements. You can choose none, one, or all of the options. (Brackets are not optional, however, in the syntax of a directory name in a OpenVMS file specification.)

( ) In format descriptions, parentheses delimit the parameter or argument list.

" " Quotation marks enclose system messages that are specified in text.

... In format descriptions, horizontal ellipsis points indicate one of the following:

An item that is repeated
An omission, such as additional optional arguments
Additional parameters, values, or other information that you can enter

.
.
. Vertical ellipsis points indicate the omission of information from an example or command format. The information is omitted because it is not important to the topic being discussed.

italic type Italic type emphasizes important information, indicates variables, and indicates complete titles of manuals.

text style This text style represents the introduction of a new term or the name of an argument, an attribute, or a reason.
This style is also used to show user input in Bookreader versions of the manual.

mouse The term mouse refers to any pointing device, such as a mouse, a puck, or a stylus.

MB1, MB2, MB3 MB1 indicates the left mouse button. MB2 indicates the middle mouse button. MB3 indicates the right mouse button. (Users can redefine the mouse buttons.)

nn nnn.nnn nn A space character separates digits in numerals with 5 or more digits. For example, 10 000 equals ten thousand.

n.nn A period in numerals signals the decimal point indicator. For example, 1.75 equals one and three-fourths.

UPPERCASE Words in uppercase indicate a command, the name of a file, the name of a file protection code, or an abbreviation for a system privilege.

lowercase In format descriptions, words in lowercase indicate parameters or arguments to be specified by the user.

Chapter 1
DECTPU Built-In Procedures Grouped According to Function

This chapter groups each of the DECTPU built-in procedures in a table according to the functions that they perform so you can see at a glance which built-in is related to what task.

When you want to perform editing tasks, use the following table to help you identify which built-in procedures are related to a particular task.

Chapter 2 lists the built-in procedures alphabetically and describes them in detail.

Some entries in this manual describe language elements or keywords that are not built-in procedures. These elements and keywords are included because they are used in the same way built-ins are used.

Table 1-1 lists all the DECTPU built-in procedures, grouped by the functions they perform (screen layout, moving the cursor, matching patterns, and so on).

Table 1-1 List of DECTPU Built-In Procedures by Function
Screen Layout

ADJUST_WINDOW SET (PAD) SET (VIDEO)

CREATE_WINDOW SET (PROMPT_AREA) SET (WIDTH)

MAP SET (SCREEN_UPDATE) SHIFT

REFRESH SET (SCROLLING) UNMAP

SET (DISPLAY_VALUE) SET (STATUS_LINE) UPDATE

SET (HEIGHT) SET (TEXT)

Moving the Cursor

CURSOR_HORIZONTAL SET (COLUMN_MOVE_VERTICAL) SET (DETACHED_ACTION)

CURSOR_VERTICAL SET (CROSS_WINDOW_BOUNDS) SET (MOVE_VERTICAL_CONTEXT)

SCROLL

Moving the Editing Position

MOVE_HORIZONTAL MOVE_VERTICAL POSITION

Manipulating Text

APPEND_LINE ERASE_LINE SEARCH_QUIETLY

BEGINNING_OF FILE_PARSE SELECT

CHANGE_CASE FILE_SEARCH SELECT_RANGE

COPY_TEXT FILL SET (ERASE_UNMODIFIABLE)

CREATE_BUFFER MARK SET (MODIFIABLE)

CREATE_RANGE MESSSAGE_TEXT SET (MODIFIED)

EDIT MODIFY_RANGE SPLIT_LINE

END_OF MOVE_TEXT TRANSLATE

ERASE READ_FILE WRITE_FILE

ERASE_CHARACTER SEARCH

Matching Patterns

ANCHOR MATCH SCANL

ANY NOTANY SPAN

ARB PAGE_BREAK SPANL

LINE_BEGIN REMAIN UNANCHOR

LINE_END SCAN

Status of the Editing Context

CURRENT_BUFFER SET (DEBUG) SET (NO_WRITE)

CURRENT_CHARACTER SET (DEFAULT_DIRECTORY) SET (OUTPUT_FILE)

CURRENT_COLUMN SET (FACILITY_NAME) SET (OVERSTRIKE)

CURRENT_DIRECTION SET (FORWARD) SET (PAD_OVERSTRUCK_TABS)

CURRENT_LINE SET (INFORMATIONAL) SET (PERMANENT)

CURRENT_OFFSET SET (INSERT) SET (RECORD_ATTRIBUTE)

CURRENT_ROW SET (JOURNALING) SET (RECORD_MODE)

CURRENT_WINDOW SET (KEYSTROKE_RECOVERY) SET (REVERSE)

DEBUG_LINE SET (LEFT_MARGIN) SET (RIGHT_MARGIN)

ERROR SET (LEFT_MARGIN_ACTION) SET (RIGHT_MARGIN_ACTION)

ERROR_LINE SET (LINE_NUMBER) SET (SPECIAL_ERROR_SYMBOL)

ERROR_TEXT SET (MARGINS) SET (SUCCESS)

GET_INFO SET (MAX_LINES) SET (SYSTEM)

LOCATE_MOUSE SET (MESSAGE_ACTION_LEVEL) SET (TAB_STOPS)

RECOVER_BUFFER SET (MESSAGE_ACTION_TYPE) SET (TIMER)

SET (AUTO_REPEAT) SET (MESSAGE_FLAGS) SET (TRACEBACK)

SET (BELL) SET (MOUSE) SHOW

Defining Keys

ADD_KEY_MAP LAST KEY SET (PRE_KEY_PROCEDURE)

CREATE_KEY_MAP LOOKUP_KEY SET (SELF_INSERT)

CREATE_KEY_MAP_LIST REMOVE_KEY_MAP SET (SHIFT_KEY)

DEFINE_KEY SET (KEY_MAP_LIST) SET (UNDEFINED_KEY)

KEY_NAME SET (POST_KEY_PROCEDURE) UNDEFINE_KEY

Multiple Processing

ATTACH SEND SPAWN

CREATE_PROCESS SEND_EOF

Executing Programs

ABORT COMPILE RETURN

BREAK EXECUTE SAVE

Specific to DECwindows

CREATE_WIDGET SET (DRM_HIERARCHY) SET (MENU_POSITION)

DEFINE_WIDGET_CLASS SET (ENABLE_RESIZE) SET (RESIZE_ACTION)

GET_CLIPBOARD SET (FIRST_INPUT_ACTION) SET (SCREEN_LIMITS)

GET_DEFAULT SET (GLOBAL_SELECT) SET (SCROLL_BAR)

GET_GLOBAL_SELECT SET (GLOBAL_SELECT_GRAB) SET (SCROLL_BAR_AUTO_THUMB)

LOWER_WIDGET SET (GLOBAL_SELECT_READ) SET (UID)

MANAGE_WIDGET SET (GLOBAL_SELECT_TIME) SET (WIDGET)

RAISE_WIDGET SET (GLOBAL_SELECT_UNGRAB) SET (WIDGET_CALLBACK)

READ_CLIPBOARD SET (ICON_NAME) SET (WIDGET_CALL_DATA)

READ_GLOBAL_SELECT SET (ICON_PIXMAP) SET (WIDGET_CONTEXT_HELP)

REALIZE_WIDGET SET (INPUT_FOCUS) SET (WIDGET_RESOURCE_TYPES)

SEND_CLIENT_MESSAGE SET (INPUT_FOCUS_GRAB) UNMANAGE_WIDGET

SET (ACTIVE_AREA) SET (INPUT_FOCUS_UNGRAB) WRITE_CLIPBOARD

SET (CLIENT_MESSAGE) SET (MAPPED_WHEN_MANAGED) WRITE_GLOBAL_SELECT

SET (DEFAULT_FILE)

Miscellaneous

ASCII INDEX QUIT

CALL_USER INT READ_CHAR

CONVERT JOURNAL_CLOSE READ_KEY

CREATE_ARRAY JOURNAL_OPEN READ_LINE

DELETE LEARN_ABORT SET (EOB_TEXT)

EXIT LEARN_BEGIN SLEEP

EXPAND_NAME LEARN_END STR

FAO LENGTH SUBSTR

HELP_TEXT MESSAGE

**Table 1-1 List of DECTPU Built-In Procedures by Function**
	Screen Layout
ADJUST_WINDOW	SET (PAD)	SET (VIDEO)
CREATE_WINDOW	SET (PROMPT_AREA)	SET (WIDTH)
MAP	SET (SCREEN_UPDATE)	SHIFT
REFRESH	SET (SCROLLING)	UNMAP
SET (DISPLAY_VALUE)	SET (STATUS_LINE)	UPDATE
SET (HEIGHT)	SET (TEXT)
	Moving the Cursor
CURSOR_HORIZONTAL	SET (COLUMN_MOVE_VERTICAL)	SET (DETACHED_ACTION)
CURSOR_VERTICAL	SET (CROSS_WINDOW_BOUNDS)	SET (MOVE_VERTICAL_CONTEXT)
SCROLL
	Moving the Editing Position
MOVE_HORIZONTAL	MOVE_VERTICAL	POSITION
	Manipulating Text
APPEND_LINE	ERASE_LINE	SEARCH_QUIETLY
BEGINNING_OF	FILE_PARSE	SELECT
CHANGE_CASE	FILE_SEARCH	SELECT_RANGE
COPY_TEXT	FILL	SET (ERASE_UNMODIFIABLE)
CREATE_BUFFER	MARK	SET (MODIFIABLE)
CREATE_RANGE	MESSSAGE_TEXT	SET (MODIFIED)
EDIT	MODIFY_RANGE	SPLIT_LINE
END_OF	MOVE_TEXT	TRANSLATE
ERASE	READ_FILE	WRITE_FILE
ERASE_CHARACTER	SEARCH
	Matching Patterns
ANCHOR	MATCH	SCANL
ANY	NOTANY	SPAN
ARB	PAGE_BREAK	SPANL
LINE_BEGIN	REMAIN	UNANCHOR
LINE_END	SCAN
	Status of the Editing Context
CURRENT_BUFFER	SET (DEBUG)	SET (NO_WRITE)
CURRENT_CHARACTER	SET (DEFAULT_DIRECTORY)	SET (OUTPUT_FILE)
CURRENT_COLUMN	SET (FACILITY_NAME)	SET (OVERSTRIKE)
CURRENT_DIRECTION	SET (FORWARD)	SET (PAD_OVERSTRUCK_TABS)
CURRENT_LINE	SET (INFORMATIONAL)	SET (PERMANENT)
CURRENT_OFFSET	SET (INSERT)	SET (RECORD_ATTRIBUTE)
CURRENT_ROW	SET (JOURNALING)	SET (RECORD_MODE)
CURRENT_WINDOW	SET (KEYSTROKE_RECOVERY)	SET (REVERSE)
DEBUG_LINE	SET (LEFT_MARGIN)	SET (RIGHT_MARGIN)
ERROR	SET (LEFT_MARGIN_ACTION)	SET (RIGHT_MARGIN_ACTION)
ERROR_LINE	SET (LINE_NUMBER)	SET (SPECIAL_ERROR_SYMBOL)
ERROR_TEXT	SET (MARGINS)	SET (SUCCESS)
GET_INFO	SET (MAX_LINES)	SET (SYSTEM)
LOCATE_MOUSE	SET (MESSAGE_ACTION_LEVEL)	SET (TAB_STOPS)
RECOVER_BUFFER	SET (MESSAGE_ACTION_TYPE)	SET (TIMER)
SET (AUTO_REPEAT)	SET (MESSAGE_FLAGS)	SET (TRACEBACK)
SET (BELL)	SET (MOUSE)	SHOW
	Defining Keys
ADD_KEY_MAP	LAST KEY	SET (PRE_KEY_PROCEDURE)
CREATE_KEY_MAP	LOOKUP_KEY	SET (SELF_INSERT)
CREATE_KEY_MAP_LIST	REMOVE_KEY_MAP	SET (SHIFT_KEY)
DEFINE_KEY	SET (KEY_MAP_LIST)	SET (UNDEFINED_KEY)
KEY_NAME	SET (POST_KEY_PROCEDURE)	UNDEFINE_KEY
	Multiple Processing
ATTACH	SEND	SPAWN
CREATE_PROCESS	SEND_EOF
	Executing Programs
ABORT	COMPILE	RETURN
BREAK	EXECUTE	SAVE
	Specific to DECwindows
CREATE_WIDGET	SET (DRM_HIERARCHY)	SET (MENU_POSITION)
DEFINE_WIDGET_CLASS	SET (ENABLE_RESIZE)	SET (RESIZE_ACTION)
GET_CLIPBOARD	SET (FIRST_INPUT_ACTION)	SET (SCREEN_LIMITS)
GET_DEFAULT	SET (GLOBAL_SELECT)	SET (SCROLL_BAR)
GET_GLOBAL_SELECT	SET (GLOBAL_SELECT_GRAB)	SET (SCROLL_BAR_AUTO_THUMB)
LOWER_WIDGET	SET (GLOBAL_SELECT_READ)	SET (UID)
MANAGE_WIDGET	SET (GLOBAL_SELECT_TIME)	SET (WIDGET)
RAISE_WIDGET	SET (GLOBAL_SELECT_UNGRAB)	SET (WIDGET_CALLBACK)
READ_CLIPBOARD	SET (ICON_NAME)	SET (WIDGET_CALL_DATA)
READ_GLOBAL_SELECT	SET (ICON_PIXMAP)	SET (WIDGET_CONTEXT_HELP)
REALIZE_WIDGET	SET (INPUT_FOCUS)	SET (WIDGET_RESOURCE_TYPES)
SEND_CLIENT_MESSAGE	SET (INPUT_FOCUS_GRAB)	UNMANAGE_WIDGET
SET (ACTIVE_AREA)	SET (INPUT_FOCUS_UNGRAB)	WRITE_CLIPBOARD
SET (CLIENT_MESSAGE)	SET (MAPPED_WHEN_MANAGED)	WRITE_GLOBAL_SELECT
SET (DEFAULT_FILE)
	Miscellaneous
ASCII	INDEX	QUIT
CALL_USER	INT	READ_CHAR
CONVERT	JOURNAL_CLOSE	READ_KEY
CREATE_ARRAY	JOURNAL_OPEN	READ_LINE
DELETE	LEARN_ABORT	SET (EOB_TEXT)
EXIT	LEARN_BEGIN	SLEEP
EXPAND_NAME	LEARN_END	STR
FAO	LENGTH	SUBSTR
HELP_TEXT	MESSAGE

Contents

Index

Legal

 
6020PRO.HTML

Internet	openvmsdoc@zko.mts.dec.com
Fax	603 881-0120, Attention: OSSG Documentation, ZKO3-4/U08
Mail	OSSG Documentation Group, ZKO3-4/U08 110 Spit Brook Rd. Nashua, NH 03062-2698

Ctrl/ x	Ctrl/ x indicates that you hold down the Ctrl key while you press another key or mouse button (indicated here by x).
PF n	PF n indicates that you press the key labeled PF n on the numeric keypad, where n is 1, 2, 3, or 4.
x	A lowercase italic x indicates the generic use of a letter. For example, xxx indicates any combination of three alphabetic characters.
n	A lowercase italic n indicates the generic use of a number. For example, 19 nn indicates a 4-digit number in which the last 2 digits are unknown.
PF1 x	The key sequence PF1 x indicates that you press and release PF1, and then you press and release another key or mouse button (indicated here by x).
`[Return]`	A key name enclosed in a box indicates that you press that key.
{ }	In format descriptions, braces indicate required elements. You must choose one of the elements.
[ ]	In format descriptions, brackets indicate optional elements. You can choose none, one, or all of the options. (Brackets are not optional, however, in the syntax of a directory name in a OpenVMS file specification.)
( )	In format descriptions, parentheses delimit the parameter or argument list.
" "	Quotation marks enclose system messages that are specified in text.
...	In format descriptions, horizontal ellipsis points indicate one of the following: An item that is repeated An omission, such as additional optional arguments Additional parameters, values, or other information that you can enter
. . .	Vertical ellipsis points indicate the omission of information from an example or command format. The information is omitted because it is not important to the topic being discussed.
italic type	Italic type emphasizes important information, indicates variables, and indicates complete titles of manuals.
text style	This text style represents the introduction of a new term or the name of an argument, an attribute, or a reason. This style is also used to show user input in Bookreader versions of the manual.
mouse	The term mouse refers to any pointing device, such as a mouse, a puck, or a stylus.
MB1, MB2, MB3	MB1 indicates the left mouse button. MB2 indicates the middle mouse button. MB3 indicates the right mouse button. (Users can redefine the mouse buttons.)
nn nnn.nnn nn	A space character separates digits in numerals with 5 or more digits. For example, 10 000 equals ten thousand.
n.nn	A period in numerals signals the decimal point indicator. For example, 1.75 equals one and three-fourths.
UPPERCASE	Words in uppercase indicate a command, the name of a file, the name of a file protection code, or an abbreviation for a system privilege.
lowercase	In format descriptions, words in lowercase indicate parameters or arguments to be specified by the user.