DEC Text Processing Utility Reference Manual

Updated: 11 December 1998

DEC Text Processing Utility Reference Manual

Contents

Index

Using CURRENT_LINE may cause DECTPU to insert padding spaces or blank lines in the buffer. CURRENT_LINE causes the screen manager to place the editing point at the cursor position if the current buffer is mapped to a visible window. For more information on the distinction between the cursor position and the editing point, see Appendix C.

If the cursor is not located on a character (that is, if the cursor is before the beginning of a line, beyond the end of a line, in the middle of a tab, or below the end of the buffer), DECTPU inserts padding spaces or blank lines into the buffer to fill the space between the cursor position and the nearest text.

Signaled Errors

TPU$_TOOMANY	ERROR	CURRENT_LINE takes no parameters.
TPU$_NEEDTOASSIGN	ERROR	The CURRENT_LINE built-in must be on the right-hand side of an assignment statement.
TPU$_NOCURRENTBUF	WARNING	You are not positioned in a buffer.
TPU$_NOEOBSTR	WARNING	You are positioned at or beyond the EOB (end-of-buffer) mark.

Examples

The following example stores in the variable my_cur_lin the string that represents the current line. The current line is the line in the current buffer that contains the editing point.

#1
my_cur_lin := CURRENT_LINE

The following example returns true if the current line has the format of a DSR command (starts with a period followed by an alphabetic character, a semicolon, or an exclamation point). If not, the procedure returns false. The procedure assumes that the cursor was at the beginning of the line and moves it back to the beginning of the line when done.

#2
PROCEDURE user_runoff_line IF LENGTH (CURRENT_LINE) < 2 THEN user_runoff_line := 0; ELSE IF CURRENT_CHARACTER <> "." THEN user_runoff_line := 0; ELSE MOVE_HORIZONTAL (1); IF INDEX ("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ!;", CURRENT_CHARACTER) = 0 THEN user_runoff_line := 0; ELSE user_runoff_line := 1; ENDIF; MOVE_HORIZONTAL (-1); ENDIF; ENDIF; ENDPROCEDURE;

PROCEDURE user_runoff_line 
 
IF LENGTH (CURRENT_LINE) < 2 
THEN 
   user_runoff_line := 0; 
ELSE 
   IF CURRENT_CHARACTER <> "." 
   THEN 
      user_runoff_line := 0; 
   ELSE 
      MOVE_HORIZONTAL (1); 
      IF INDEX 
         ("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ!;", 
         CURRENT_CHARACTER) = 0 
      THEN 
         user_runoff_line := 0; 
      ELSE 
         user_runoff_line := 1; 
      ENDIF; 
      MOVE_HORIZONTAL (-1); 
   ENDIF; 
ENDIF; 
ENDPROCEDURE;

CURRENT_OFFSET

Format

integer := CURRENT_OFFSET

Parameters

None.

Return Value

An integer that is the offset of the editing point within the current line.

Description

The CURRENT_OFFSET procedure returns an integer for the offset of the editing point within the current line. The current offset is the number of positions a character is located from the first character position in the current line (offset 0). In DECTPU, the leftmost character position is offset 0, and this offset is increased by 1 for each character position (including the tab character) to the right. DECTPU numbers columns starting with the leftmost position on the screen where a character could be placed, regardless of where the margin is. This leftmost position is numbered 1.

Note
The current offset value is not the same as the position of the cursor on the screen. See the CURRENT_COLUMN built-in procedure if you want to determine where the cursor is. For example, if you have a line with a left margin of 10 and if the cursor is on the first character in that line, then CURRENT_OFFSET returns 0 while CURRENT_COLUMN returns 10.

Using CURRENT_OFFSET may cause DECTPU to insert padding spaces or blank lines in the buffer. CURRENT_OFFSET causes the screen manager to place the editing point at the cursor position if the current buffer is mapped to a visible window. For more information on the distinction between the cursor position and the editing point, see Appendix C.
If the cursor is not located on a character (that is, if the cursor is before the beginning of a line, beyond the end of a line, in the middle of a tab, or below the end of the buffer), DECTPU inserts padding spaces or blank lines into the buffer to fill the space between the cursor position and the nearest text.
If you are using an interface with free cursor motion, when you move beyond the end of a line CURRENT_OFFSET makes the current cursor position the new end-of-line.
If the current offset equals the length of the current line, you are positioned at the end of the line.

Signaled Errors

TPU$_TOOMANY	ERROR	CURRENT_OFFSET takes no parameters.
TPU$_NEEDTOASSIGN	ERROR	The CURRENT_OFFSET built-in must be on the right-hand side of an assignment statement.
TPU$_NOCURRENTBUF	WARNING	You are not positioned in a buffer.

Examples

The following example stores the integer that is the offset position of the current character in the variable my_cur_off:

#1
my_cur_off := CURRENT_OFFSET

The following example uses the CURRENT_OFFSET built-in procedure to determine whether the editing position is at the beginning of a line. If the position is at the beginning, the procedure appends the current line to the previous line; otherwise, it deletes the previous character. Compare this procedure with the procedure used as an example for the APPEND_LINE built-in procedure.

#2
PROCEDURE user_delete IF CURRENT_OFFSET = 0 THEN APPEND_LINE; ELSE ERASE_CHARACTER (-1); ENDIF; ENDPROCEDURE;

CURRENT_ROW

Format

integer := CURRENT_ROW

Parameters

None.

Return Value

An integer that represents the screen line on which the cursor is located.

Description

The CURRENT_ROW procedure returns an integer that is the screen line on which the cursor is located. The screen lines are numbered from 1 at the top of the screen to the maximum number of lines available on the terminal. You can get the value of the current row by using the GET_INFO (SCREEN, "current_row") built-in procedure.
When used in a procedure, CURRENT_ROW does not necessarily return the position where the cursor has been placed by other statements in the procedure. The value returned by CURRENT_ROW may not be the current value because DECTPU generally does not update the screen until all statements in a procedure are executed. If you want the cursor position to reflect the actual editing location, put an UPDATE statement in your procedure immediately before any statements containing CURRENT_ROW, as follows:
UPDATE (CURRENT_WINDOW);

Signaled Errors

TPU$_NEEDTOASSIGN	ERROR	The CURRENT_ROW built-in must be on the right-hand side of an assignment statement.
TPU$_TOOMANY	ERROR	CURRENT_ROW takes no parameters.

Examples

The following example causes the cursor to move up the screen:

#1
PROCEDURE user_go_up IF CURRENT_ROW = GET_INFO (CURRENT_WINDOW, "visible_top") THEN SCROLL (CURRENT_WINDOW, -1); ELSE CURSOR_VERTICAL (-1); ENDIF; ENDPROCEDURE;

The following example causes the cursor to move down the screen. Because CURSOR_VERTICAL crosses window boundaries, you must use the SCROLL built-in procedure to keep the cursor motion within a single window if you are using free cursor motion. See CURSOR_HORIZONTAL and CURSOR_VERTICAL for more information.
If the movement of the cursor would take it outside the window, the preceding procedures scroll text into the window to keep the cursor visible. You can bind these procedures to a key so that the cursor motion can be accomplished with a single keystroke.

#2
PROCEDURE user_go_down IF CURRENT_ROW = GET_INFO (CURRENT_WINDOW, "visible_bottom") THEN SCROLL (CURRENT_WINDOW, 1); ELSE CURSOR_VERTICAL (1); ENDIF; ENDPROCEDURE;

CURRENT_WINDOW

Format

window := CURRENT_WINDOW

Parameters

None.

Return Value

The window in which the cursor is visible.

Description

The CURRENT_WINDOW procedure returns the window in which the cursor is visible. The current window is the window on which you have most recently performed one of the following operations:

Selection by using the POSITION built-in
Mapping to the screen by using the MAP built-in
Adjustment by using the ADJUST_WINDOW built-in

The current window contains the cursor at the screen coordinates current_row and current_column. The current buffer is not necessarily associated with the current window.

Signaled Errors

TPU$_TOOMANY	ERROR	CURRENT_WINDOW takes no parameters.
TPU$_NEEDTOASSIGN	ERROR	The CURRENT_WINDOW built-in must be on the right-hand side of an assignment statement.
TPU$_WINDNOTMAPPED	WARNING	No windows are mapped to the screen.

Examples

The following example stores the window that holds the cursor in the variable my_cur_win:

#1
my_cur_win := CURRENT_WINDOW

The following example determines the length of the current window and then uses that value as a parameter for the SCROLL built-in procedure.

#2
PROCEDURE user_next_screen LOCAL how_much_scroll; how_much_scroll := GET_INFO (CURRENT_WINDOW, "visible_length"); SCROLL (CURRENT_WINDOW, how_much_scroll); ENDPROCEDURE;

CURSOR_HORIZONTAL

Format

[[ integer2 :=]] CURSOR_HORIZONTAL (integer1)

Parameter

integer1
The signed plus or minus integer value that specifies the number of screen columns to move the cursor position. A positive value directs DECTPU to move the cursor to the right; a negative value directs DECTPU to move the cursor to the left. The value 0 causes DECTPU to synchronize the active editing point with the cursor position.

Return Value

An integer that represents the number of columns the cursor moved. If DECTPU cannot move the cursor as many columns as specified by integer1, DECTPU moves the cursor as many columns as possible. The return value may be negative. This notation is reserved for future versions of DECTPU. A negative return value does not denote that the cursor moved to the left. Rather, the integer shows the number of spaces that the cursor moved right or left. If the cursor did not move, integer2 has the value 0. If the CURSOR_HORIZONTAL built-in produces an error, the value of integer2 is indeterminate.

Description

The CURSOR_HORIZONTAL procedure moves the cursor position across the screen and optionally returns the cursor movement status. You can use CURSOR_HORIZONTAL to provide free cursor movement in a horizontal direction. Free cursor movement means that the cursor is not tied to text, but can move across all available columns in a screen line.
If you move before the beginning of a line, after the end of a line, in the middle of a tab, or beyond the end-of-file mark, other built-ins may cause padding lines or spaces to be added to the buffer.
If you use the CURSOR_HORIZONTAL built-in within a procedure, screen updating occurs in the following manner:

When you execute a built-in that modifies the buffer or the editing point before you issue the call to CURSOR_HORIZONTAL, the screen is updated before CURSOR_HORIZONTAL is executed. This action ensures that the horizontal movement of the cursor starts at the correct character position. Otherwise, the screen manager does not update the screen until the procedure has finished executing and control is returned to the screen manager.
CURSOR_HORIZONTAL does not move the cursor beyond the left or right edge of the window in which it is located. You cannot move the cursor outside the bounds of a window.
CURSOR_HORIZONTAL has no effect if you use any input device other than a video terminal supported by DECTPU.

Signaled Errors

TPU$_TOOFEW	ERROR	CURSOR_HORIZONTAL requires one parameter.
TPU$_TOOMANY	ERROR	CURSOR_HORIZONTAL accepts only one parameter.
TPU$_INVPARAM	ERROR	One or more of the specified parameters have the wrong type.

Examples

The following example moves the cursor position one screen column to the right:

#1
int_x := CURSOR_HORIZONTAL (1)

The following example provides for free cursor motion to the left. You can bind these procedures to keys (for example, the arrow keys) so that the movement can be accomplished with a single keystroke.

#2
PROCEDURE user_free_cursor_left move_left := CURSOR_HORIZONTAL (-1); ENDPROCEDURE;

CURSOR_VERTICAL

Format

[[integer2 :=]] CURSOR_VERTICAL (integer1)

Parameter

integer1
The signed integer value that specifies how many screen lines to move the cursor position. A positive value for integer1 moves the cursor position down. A negative integer moves the cursor position up.

Return Value

An integer that represents the number of rows that the cursor moved up or down. If DECTPU could not move the cursor as many rows as specified by integer1, DECTPU moves the cursor as many rows as possible.

If CROSS_WINDOW_BOUNDS is set to ON, CURSOR_VERTICAL may position the cursor to another window. In this case, CURSOR_VERTICAL returns the negative of the number of rows the cursor moved. A negative return value does not denote that the cursor moved upward.

If the cursor did not move, integer2 has the value 0. If the CURSOR_VERTICAL built-in procedure produced an error, the value of integer2 is indeterminate.

Description

The CURSOR_VERTICAL procedure moves the cursor position up or down the screen and optionally returns the cursor movement status. You can use CURSOR_VERTICAL to provide free cursor movement in a vertical direction. Free cursor movement means that the cursor is not tied to text, but that it can move up and down to all lines on the screen that can be edited, whether or not there is text at that column in the new line.
The cursor does not move beyond the top or the bottom edges of the screen. However, CURSOR_VERTICAL can cross window boundaries, depending upon the current setting of the CROSS_WINDOW_BOUNDS flag. See SET (CROSS_WINDOW_BOUNDS) for information on how to set this flag. (Use the POSITION built-in to move the cursor to a different window on the screen.)
When CROSS_WINDOW_BOUNDS is set to ON, CURSOR_VERTICAL can move the cursor position to a new window. The new window in which the cursor is positioned becomes the current window. The column position of the cursor remains unchanged unless vertical movement would position the cursor outside the bounds of a window narrower than the previous window. In this instance, the cursor moves to the left until it is positioned within the right boundary of the narrower window.
When CROSS_WINDOW_BOUNDS is set to OFF, CURSOR_VERTICAL does not move the cursor outside the current window. If the SET (SCROLLING) built-in has been used to set scrolling margins, CURSOR_VERTICAL also attempts to keep the cursor within the scroll margins.
CURSOR_VERTICAL positions the cursor only in screen areas in which editing can occur. For example, CURSOR_VERTICAL does not position the cursor on the status line of a window, in the prompt area, or in an area of the screen that is not part of a window. The blank portion of a segmented window is not considered part of a window for this purpose.
If you use CURSOR_VERTICAL within a procedure, screen updating occurs in the following manner:

When you execute a built-in that modifies the buffer or the current character position before you issue the call to CURSOR_VERTICAL, the screen is updated before CURSOR_VERTICAL is executed. This action ensures that the vertical movement of the cursor starts at the correct character position. Otherwise, the screen manager does not update the screen until the procedure has finished executing and control is returned to the screen manager.
CURSOR_VERTICAL has no effect if you use an input device other than a video terminal supported by DECTPU.

Signaled Errors

TPU$_TOOFEW	ERROR	CURSOR_VERTICAL requires at least one parameter.
TPU$_TOOMANY	ERROR	CURSOR_VERTICAL accepts at most one parameter.
TPU$_INVPARAM	ERROR	You did not specify an integer as the parameter.

Examples

The following example moves the cursor position five lines toward the bottom of the screen:

#1
int_y := CURSOR_VERTICAL (5)

The following example provides for free cursor motion up and down the screen. These procedures can be bound to keys (for example, the arrow keys) so that you can make the movement with a single keystroke.

#2
PROCEDURE user_free_cursor_down IF GET_INFO (CURRENT_WINDOW, "CURRENT_ROW") = GET_INFO (CURRENT_WINDOW, "VISIBLE_BOTTOM") THEN SCROLL (CURRENT_WINDOW, 1); ELSE right_x := CURSOR_VERTICAL (1); ENDIF; ENDPROCEDURE;

PROCEDURE user_free_cursor_down 
 
   IF GET_INFO (CURRENT_WINDOW, "CURRENT_ROW") = 
               GET_INFO (CURRENT_WINDOW, "VISIBLE_BOTTOM") 
   THEN 
       SCROLL (CURRENT_WINDOW, 1); 
   ELSE 
       right_x := CURSOR_VERTICAL (1); 
   ENDIF; 
ENDPROCEDURE;

These examples work regardless of the setting of CROSS_WINDOW_BOUNDS because the SCROLL built-in procedure keeps the cursor motion within a single window.

DEBUG_LINE

Format

integer := DEBUG_LINE

Parameters

None.

Return Value

An integer that represents the line number of the current breakpoint.

Description

The DEBUG_LINE procedure returns the line number of the current breakpoint. Use DEBUG_LINE when writing your own DECTPU debugger.
Digital recommends that you use the debugger provided in SYS$SHARE:TPU$DEBUG.TPU.

Signaled Error

TPU$_NEEDTOASSIGN

ERROR

The DEBUG_LINE built-in must appear on the right-hand side of an assignment statement.

Example

In the following example, the code fragment first uses GET_INFO to request the line number of the breakpoint in the current procedure. If the line number is 0, meaning that the breakpoint is not in a procedure, the code uses DEBUG_LINE to determine the breakpoint's line number relative to the buffer.


the_line := GET_INFO (DEBUG, "line_number"); IF the_line = 0 THEN the_line := DEBUG_LINE; ENDIF;

DEFINE_KEY

Format

DEFINE_KEY (

buffer
learn
program
range
string1
, key-name
[[ ,string2 [[ ,string3]] ]])

Parameters

buffer
A buffer that contains the DECTPU statements to be associated with a key.
learn
A learn sequence that specifies the executable code associated with a key.
program
A program that contains the executable code to be associated with a key.
range
A range that contains the DECTPU statements to be associated with a key.
string1
A string that specifies the DECTPU statements to be associated with a key.
key-name
A DECTPU key name for a key or a combination of keys. See the Guide to the DEC Text Processing Utility for a list of the DECTPU key names for the LK0201 and LK0401 series of keyboards. You can also use the SHOW (KEYWORDS) built-in procedure to display all the DECTPU keywords.
See the Description section of this built-in procedure for information on keys that you cannot define.
To define a key for which there is no DECTPU key name, use the KEY_NAME built-in procedure to create your own key name for the key. For example, KEY_NAME ("A", SHIFT_KEY) creates a key name for the combination of PF1, the default shift key for DECTPU, and the keyboard character A. For more information, see the description of the KEY_NAME built-in procedure.
string2
An optional string associated with a key that you define. The string is treated as a comment that you can retrieve with the LOOKUP_KEY built-in procedure. You might want to use the comment if you are creating a help procedure for keys that you have defined.
string3
A key map or a key map list in which the key is to be defined. If a key map list is specified, the key is defined in the first key map in the key map list. If neither a key map nor a key map list is specified, the key is defined in the first key map in the key map list bound to the current buffer. See the descriptions of the CREATE_KEY_MAP, CREATE_KEY_MAP_LIST, and SET (KEY_MAP_LIST) built-in procedures for more information on key maps and key map lists.

Description

The DEFINE_KEY procedure associates executable DECTPU code with a key or a combination of keys. DEFINE_KEY compiles the first parameter if it is a string, buffer, or range.
If you use DEFINE_KEY to change the definition of a key that was previously defined, DECTPU does not save the previous definition.
You can define all the keys on the LK201 and LK401 keyboards and keypads with the following exceptions:

The Compose Character key and Alt function key
The Shift keys
The Escape key
The keys F1 through F5

There are some keys that you can define but that Digital strongly recommends you avoid defining. DECTPU does not signal an error when you use them as keyword parameters. However, on character-cell terminals the definitions you assign to these key combinations are not executed unless you set your terminal in special ways at the DCL level. Digital recommends that you do not use the following special terminal settings. The settings may cause unpredictable results if you do not understand all the implications of changing the default settings:

Ctrl/C, Ctrl/O, Ctrl/X, and F6---To execute programs that you bind to these keys, you must first enter the DCL SET TERMINAL/PASTHRU command.
Ctrl/T, Ctrl/Y---To execute programs that you bind to these keys, you must first enter the DCL SET TERMINAL/PASTHRU command, the DCL SET NOCONTROL command, or both.
Ctrl/S, Ctrl/Q---To execute programs that you bind to these keys, you must first enter the DCL SET TERMINAL/NOTTSYNC command.

The PF1 key is the default shift key for the editor. You cannot define PF1 unless you use either the SET (SHIFT_KEY, keyword) built-in procedure or the EVE SET GOLD KEY command to define a different key as the shift key for the editor.

Previous Next Contents Index

Copyright © Compaq Computer Corporation 1998. All rights reserved.
Legal

6020PRO_006.HTML

DEC Text Processing Utility Reference Manual

Signaled Errors

Examples

CURRENT_OFFSET

Format

integer := CURRENT_OFFSET

Parameters

Return Value

Description

Signaled Errors

Examples

CURRENT_ROW

Format

integer := CURRENT_ROW

Parameters

Return Value

Description

Signaled Errors

Examples

CURRENT_WINDOW

Format

window := CURRENT_WINDOW

Parameters

Return Value

Description

Signaled Errors

Examples

CURSOR_HORIZONTAL

Format

[[ integer2 :=]] CURSOR_HORIZONTAL (integer1)

Parameter

integer1

Return Value

Description

Signaled Errors

Examples

CURSOR_VERTICAL

Format

[[integer2 :=]] CURSOR_VERTICAL (integer1)

Parameter

integer1

Return Value

Description

Signaled Errors

Examples

DEBUG_LINE

Format

integer := DEBUG_LINE

Parameters

Return Value

Description

Signaled Error

Example

DEFINE_KEY

Format

DEFINE_KEY ( buffer learn program range string1, key-name [[ ,string2 [[ ,string3]] ]])

Parameters

buffer

learn

program

range

string1

key-name

string2

string3

Description

DEFINE_KEY (

buffer
learn
program
range
string1
, key-name
[[ ,string2 [[ ,string3]] ]])