Document revision date: 30 March 2001

## DEC Text Processing Utility Reference Manual

Previous | Contents | Index

The following example shows a portion of a command file that defines the keys for an editing interface that emulates EDT:

#2
    ! Procedure to define keys to emulate EDT

    PROCEDURE user_define_edtkey

    ! Bind the EDT Fndnxt function to PF3

      DEFINE_KEY ("edt$search_next", PF3);

    !  Bind the EDT Find function to SHIFT PF3

      DEFINE_KEY ("edt$search", KEY_NAME (PF3, SHIFT_KEY));
    ENDPROCEDURE;

## LAST_KEY

### Format

> keyword := LAST_KEY

### Parameters

> None.

### Return Value

A marker that returns a keyword for the last key that was entered, read, or executed.

### Description

> The LAST_KEY procedure returns a DECTPU keyword for the last key that was entered, read, or executed. When DECTPU is replaying a learn sequence or executing the program bound to a key, LAST_KEY returns the last key replayed or processed so far---not the last key that was pressed to invoke the learn sequence or program.

> When you invoke DECTPU with the /NODISPLAY qualifier, the value 0 is returned for LAST_KEY, except in the following case: If you precede the LAST_KEY statement with a READ_LINE statement, LAST_KEY can return a key name that represents the last key read by READ_LINE, Ctrl/Z, or the Return key. See the description of READ_LINE for more information on the values that LAST_KEY can return when you use LAST_KEY while running DECTPU in /NO_DISPLAY mode.

#### Signaled Error

TPU$_TOOMANY | ERROR | Too many arguments passed to the LAST_KEY built-in.

### Example

> The following example prompts you for input for key definitions:

    PROCEDURE user_define_key

       def := READ_LINE ("Definition: ");
       key := READ_LINE ("Press key to define.",1);
       IF LENGTH (key) > 0
       THEN
           key := KEY_NAME (key)
       ELSE
             key := LAST_KEY;
       ENDIF;
       DEFINE_KEY (def, key);
    ENDPROCEDURE;

## LEARN_ABORT

### Format

> [[integer := ]] LEARN_ABORT

### Parameters

> None.

### Return Value

An integer that indicates whether a learn sequence was actually replaying at the time the LEARN_ABORT statement was executed. The value 1 is returned if a learn sequence was being replayed; otherwise it returns 0. The value 1 is returned each time LEARN_ABORT executes until DECTPU gets back to its main key-reading loop.

### Description

> The LEARN_ABORT procedure causes a learn sequence being replayed to be terminated whether or not the learn sequence has completed. Only the currently executing learn sequence is aborted.

> Whenever you write a procedure that can be bound to a key, the procedure should invoke the LEARN_ABORT built-in procedure in case of error. Using LEARN_ABORT prevents a learn sequence from finishing if the learn sequence calls the user-written procedure and the procedure is not executed successfully.

#### Signaled Error

TPU$_TOOMANY | ERROR | The LEARN_ABORT built-in takes no parameters.

### Example

> If an error occurs, the following error handler aborts any executing learn sequence:

    ON_ERROR
       MESSAGE ("Aborting command because of error.");
       LEARN_ABORT;
       ABORT;
    ENDON_ERROR

## LEARN_BEGIN and LEARN_END

### Format

> LEARN_BEGIN ({EXACT|NO_EXACT})

> .

> .

> .

> learn := LEARN_END

### Parameters

> #### EXACT

> Causes DECTPU to reuse the input, or learn sequence, that you entered for each READ_LINE, READ_KEY, or READ_CHAR built-in procedure.

> #### NO_EXACT

> Causes DECTPU to prompt for new input each time a READ_LINE, READ_KEY, or READ_CHAR built-in procedure is replayed within a learn sequence.

### Return Value

A variable of type learn that stores the keystrokes you specify.

### Description

> The LEARN_BEGIN and LEARN_END procedures saves all keystrokes typed between LEARN_BEGIN and LEARN_END. LEARN_BEGIN starts saving all keystrokes that you type. LEARN_END stops the "learn mode" of DECTPU and returns a learn sequence that consists of all the keystrokes that you entered.

> You can use the variable name that you assign to a learn sequence as the parameter for the EXECUTE built-in procedure to replay a learn sequence. You can also use the variable name with the DEFINE_KEY built-in procedure to bind the sequence to a key so that the learn sequence is executed when you press that key.

> Learn sequences are different from other DECTPU programs because they are created with keystrokes rather than with DECTPU statements. You create the learn sequence as you are entering text and executing DECTPU commands. Because learn sequences make it easy to collect and execute a sequence of DECTPU commands, they are convenient for creating temporary "programs." You can replay these learn sequences during the editing session in which you create them.

> Learn sequences are not flexible enough to use for writing general programs. Learn sequences are best suited for saving a series of editing actions that you perform many times during a single editing session.

> You can save learn sequences from session to session so that you can replay them in an editing session other than the one in which you created them. To save a learn sequence, bind it to a key. Before ending your editing session, use the SAVE built-in procedure to do an incremental save to the section file you are using. Using the SAVE built-in procedure causes the new definitions from the current session to be added to the section file with which you invoked DECTPU. For more information, see the SAVE built-in procedure.

> Learn sequences cannot be transferred from one version of DECTPU to another.

> Note You should not use built-in procedures that can return WARNING or ERROR messages as a part of a learn sequence because learn sequences do not stop on error conditions. Because the learn sequence continues executing after an error or warning condition, the editing actions that are executed after an error or a warning may not take effect at the character position you desire. If, for example, a SEARCH built-in procedure that you use as a part of a learn sequence fails to find the string you specify and issues a warning, the learn sequence does not stop executing. This can cause the rest of the learn sequence to take inappropriate editing actions.

> Prekey and postkey procedures interact with learn sequences in the following order:

> 1. When you press the key or key sequence to which the learn sequence is bound, DECTPU executes the prekey procedure of that key if a prekey procedure has been set.
> 2. For each key in the learn sequence, DECTPU executes procedures or programs in the following order:
>    1. DECTPU executes the prekey procedure of that key if a prekey procedure has been set.
>    2. DECTPU executes the code bound to the key itself.
>    3. DECTPU executes the postkey procedure of that key if a postkey procedure has been set.
> 3. When all keys in the learn sequence have been processed, DECTPU executes the postkey procedure, if one has been set, for the key to which the entire learn sequence was bound.

> Note If, during the recording of a learn sequence, a margin action route is executed (for example EVE's word wrap), the margin action routine is not executed when the learn sequence is replayed.

#### Signaled Errors

TPU$_NOTLEARNING | WARNING | LEARN_BEGIN was not used since the last call to LEARN_END.
TPU$_ONELEARN | WARNING | A learn sequence is already in progress.
TPU$_TOOFEW | ERROR | LEARN_BEGIN requires one argument.
TPU$_TOOMANY | ERROR | LEARN_BEGIN accepts only one argument.
TPU$_INVPARAM | ERROR | The specified parameter has the wrong type.

### Example

> The following example shows how to combine LEARN_BEGIN and LEARN_END so that all of the keystrokes that you enter between them are saved. The (EXACT) keyword specifies that if you use READ_LINE, READ_CHAR, or READ_KEY within the learn sequence, any input that you enter for these built-in procedures is repeated exactly when you replay the learn sequence.

    LEARN_BEGIN (EXACT)
                 .
                 .
                 .
    This represents a typical editing session,
    in which you perform commands that are
    bound to keys.
                 .
                 .
                 .
    do_again := LEARN_END

## LENGTH

### Format

> integer := LENGTH ( {buffer |range |string})

### Parameters

> #### buffer

> The buffer whose length you want to determine. If you specify a buffer, line terminators are not counted as character positions.

> #### range

> The range whose length you want to determine. If you specify a range, line terminators are not counted as character positions.

> #### string

> The string whose length you want to determine.

### Return Value

An integer that indicates the number of character positions in a buffer, range, or string you specify.

### Description

> The LENGTH procedure returns an integer that is the number of character positions in a buffer, range, or string.

#### Signaled Errors

TPU$_NEEDTOASSIGN | ERROR | LENGTH must be on the right-hand side of an assignment statement.
TPU$_TOOFEW | ERROR | LENGTH requires one argument.
TPU$_TOOMANY | ERROR | LENGTH accepts only one argument.
TPU$_ARGMISMATCH | ERROR | The argument to LENGTH must be a string or a range.
TPU$_CONTROLC | ERROR | You pressed Ctrl/C while LENGTH was executing.

### Examples

> The following example stores the number of characters in the string "Don Quixote" in the variable str_len. In this example, the integer value is 11:

#1
    str_len := LENGTH ("Don Quixote")

> The following example puts a marker without any video attributes at the current position. The marker is assigned to a variable that begins with user_mark_ and ends with the string you pass as a parameter. The procedure writes a message to the message area verifying the mark name that comes from the input parameter.

#2
    ! Parameters:
    !
    !   mark_parameter is user-supplied string,
    !   which is used as a mark name

    PROCEDURE user_mark_ (mark_parameter)

    ! Local copy of mark_parameter

       LOCAL mark_name;

       ON_ERROR
           MESSAGE (FAO ("Cannot use !AS as a mark name", mark_name));
           RETURN;
       ENDON_ERROR;

    ! 132 - length ("user_mark_")

       IF LENGTH (mark_parameter) > 122
       THEN
           mark_name := SUBSTR (mark_name, 1, 122);
       ELSE
           mark_name := mark_parameter;
       ENDIF;

       EXECUTE ("user_mark_" + mark_name + " := MARK (NONE)");
       MESSAGE (FAO ("Current position marked as !AS", mark_name));
    ENDPROCEDURE;

## LINE_BEGIN

### Format

> LINE_BEGIN

### Parameters

> None.

### Description

> The LINE_BEGIN procedure matches the beginning of a line when used as part of a complex pattern or as an argument to SEARCH. Although LINE_BEGIN behaves much like a built-in, it is actually a keyword.

> LINE_BEGIN lets you search for complex strings by creating patterns that match certain conditions. For example, if you want to find all occurrences of the exclamation point (!) when it is the first character in the line, use LINE_BEGIN to create the following pattern:

> `pat1 := LINE_BEGIN + "!";`

> For more information on patterns, see the Guide to the DEC Text Processing Utility.

#### Signaled Errors

LINE_BEGIN is a keyword and has no completion codes.

### Examples

> The following example stores the beginning-of-line condition in the variable pat1:

#1
    pat1 := LINE_BEGIN

> The following example removes all lines that start with Compaq Standard Runoff (DSR) commands from a file by searching for a pattern that has a period (.) at the beginning of a line and then removing the lines that match this condition:

#2
    PROCEDURE user_remove_dsrlines

       LOCAL s1,
             pat1;

       pat1 := LINE_BEGIN + ".";

       LOOP
          s1 := SEARCH_QUIETLY (pat1, FORWARD);
          EXITIF s1 = 0;
          POSITION (s1);
          ERASE_LINE;
       ENDLOOP;
    ENDPROCEDURE;

## LINE_END

### Format

> LINE_END

### Parameters

> None.

### Description

> The LINE_END procedure matches the end of a line when used as part of a complex pattern or as an argument to SEARCH. Although LINE_END behaves much like a built-in, it is actually a keyword.

> The end-of-line condition is one character position to the right of the last character on a line.

> For more information on patterns, see the Guide to the DEC Text Processing Utility.

#### Signaled Errors

LINE_END is a keyword and has no completion codes.

### Examples

> The following example stores the LINE_END keyword in the variable pat1. You can use Pat1 as an argument to the SEARCH built-in or as part of a complex pattern.

#1
    pat1 := LINE_END

> In the following example, if you are not already at the end of the current line, the preceding procedure moves the editing point to the end of the line:

#2
    PROCEDURE user_end_of_line

       LOCAL eol_range;

       eol_range := SEARCH_QUIETLY (LINE_END, FORWARD);

       IF eol_range <> 0
       THEN
          POSITION (eol_range);
       ENDIF;
    ENDPROCEDURE;

## LOCATE_MOUSE

### Format

> [[ integer := ]] LOCATE_MOUSE (window, x_integer, y_integer)

### Parameters

> #### window

> Returns the window in which the pointer is located. You can pass any data type except a constant in this parameter. If the pointer is not found, an unspecified data type is returned.

> #### x_integer

> Returns the column position of the pointer. You can pass any data type except a constant in this parameter. If the pointer is not found, an unspecified data type is returned. This parameter returns 0 if the pointer is in a vertical scroll bar.

> #### y_integer

> Returns the row position of the pointer. You can pass any data type except a constant in this parameter. If the pointer is not found, an unspecified data type is returned. This parameter returns 0 if the pointer is in the status line for a window.

### Return Value

An integer that indicates whether the pointer was found in a window. The value is 1 if DECTPU finds a window position; otherwise it is 0.

### Description

> The LOCATE_MOUSE procedure locates the window position of the pointer at the time LOCATE_MOUSE is invoked. LOCATE_MOUSE returns the window name and the window position of the pointer and optionally returns a status that indicates whether the pointer was found in a window. When you press a mouse button, DECTPU determines the location of the mouse pointer and makes that information available while the code bound to the mouse button is being processed. Mouse pointer location information is not available at any other time.

> In DECwindows DECTPU, you can use the LOCATE_MOUSE built-in procedure anytime after the first keyboard or mouse-button event. The built-in returns the location occupied by the pointer cursor at the time of the most recent keyboard or mouse button event.

> If there is no mouse information available (because no mouse button has been pressed or if the mouse has been disabled using SET (MOUSE)), LOCATE_MOUSE signals the status TPU$_MOUSEINV.

#### Signaled Errors

TPU$_MOUSEINV | WARNING | The mouse position is not currently valid.
TPU$_TOOFEW | ERROR | LOCATE_MOUSE requires three parameters.
TPU$_TOOMANY | ERROR | LOCATE_MOUSE accepts at most three parameters.
TPU$_BADDELETE | ERROR | You specified a constant as one or more of the parameters.

### Examples

> The following example statement returns an integer in the variable status that indicates whether the pointer cursor was found in a window; returns the window in the parameter new_window where the mouse was found; returns an integer in the parameter x_value that specifies the pointer cursor's location in the horizontal dimension; and returns an integer in the parameter y_value that specifies the pointer cursor's location in the vertical dimension.

#1
    status := LOCATE_MOUSE (new_window, x_value, y_value);

> In the following example, binding the user_move_to_mouse procedure to a mouse button moves the cursor to the mouse location. The user_move_to_mouse procedure is essentially equivalent to POSITION (MOUSE).

#2
    PROCEDURE user_move_to_mouse

       LOCAL my_window,
             x_1,
             y1;

       IF (LOCATE_MOUSE (my_window, x_1, Y1) <> 0)
       THEN
          IF (CURRENT_WINDOW <> my_window)
          THEN
             POSITION (my_window);
             UPDATE (my_window);
          ENDIF;
          CURSOR_VERTICAL (y1 - (CURRENT_ROW - GET_INFO
                          (my_window,"visible_top") + 1));
          CURSOR_HORIZONTAL (CURRENT_COLUMN - x_1);
       ENDIF;
    ENDPROCEDURE;

> CURRENT_ROW and CURRENT_COLUMN return screen-relative location information, while LOCATE_MOUSE returns window-relative location information.

## LOOKUP_KEY

### Format

> {integer |learn_sequence |program |string3} := LOOKUP_KEY

> (key-name, {COMMENT |KEY_MAP |PROGRAM} [[{, string1 |, string2}]])

### Parameters

> #### 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 LK201, LK401, and VT100-series keyboards.

> #### COMMENT

> A keyword that specifies that the LOOKUP_KEY built-in procedure is to return the comment supplied when the key was defined. If no comment was supplied, the LOOKUP_KEY built-in returns the integer zero.

> #### KEY_MAP

> A keyword that specifies that the LOOKUP_KEY built-in procedure is to return the key map in which the key's definition is stored. If you specify a key that is not defined in any key map, LOOKUP_KEY returns a null string.

> #### PROGRAM

> A keyword that specifies that the LOOKUP_KEY built-in procedure is to return the program or learn sequence bound to the key specified. If the key is not defined, the LOOKUP_KEY built-in returns the integer 0.

> #### string1

> The name of the key map from which the LOOKUP_KEY built-in procedure is to get the key definition. Use this optional parameter if the key is defined in more than one key map. If you do not specify a key map or a key map list for the third parameter, the first definition found for the specified key in the key map list bound to the current buffer is returned.

> #### string2

> The name of the key map list from which the LOOKUP_KEY built-in procedure is to get the key definition. Use this optional parameter if the key is defined in more than one key map list. If you do not specify a key map or a key map list for the third parameter, the first definition found for the specified key in the key map list bound to the current buffer is returned.

### Return Values

> #### integer

> The integer 0. This value is returned if the key specified as a parameter has no definition.

> #### learn_sequence

> The learn sequence bound to the key specified as a parameter.

> #### program

> The program bound to the key specified as a parameter.

> #### string3

> If you specified COMMENT as the second parameter, string3 is the comment bound to the key specified as the first parameter. If you specified KEY_MAP as the second parameter, string3 is the string naming the key map in which the key definition was found.

### Description

> The LOOKUP_KEY procedure returns the executable code or the comment that is associated with the key that you specify. The code can be returned as a program or as a learn sequence. The comment is returned as a string. LOOKUP_KEY can return a program, a learn sequence, a string, or the integer 0 (0 means that the key has no definition).

> LOOKUP_KEY is useful when you are defining keys temporarily during an editing session and you want to check the existing definitions of a key.

#### Signaled Errors

TPU$_NOTDEFINABLE | WARNING | Argument is not a valid reference to a key.
TPU$_NOKEYMAP | WARNING | Argument is not a defined key map.
TPU$_NOKEYMAPLIST | WARNING | Argument is not a defined key map list.
TPU$_KEYMAPNTFND | WARNING | The specified key map is not found.
TPU$_EMPTYKMLIST | WARNING | The specified key map list contains no key maps.
TPU$_TOOFEW | ERROR | Too few arguments passed to the LOOKUP_KEY built-in.
TPU$_TOOMANY | ERROR | Too many arguments passed to the LOOKUP_KEY built-in.
TPU$_NEEDTOASSIGN | ERROR | LOOKUP_KEY must be on the right-hand side of an assignment statement.
TPU$_INVPARAM | ERROR | Wrong type of data sent to the LOOKUP_KEY built-in.
TPU$_BADKEY | ERROR | An unknown keyword was used as an argument. Only PROGRAM, COMMENT, and KEY_MAP are valid keywords.

### Examples

> The following example returns the executable code that is associated with key1. The second keyword, PROGRAM, indicates that the result is returned to a variable of type program or learn.

#1
    programx := LOOKUP_KEY (key1, PROGRAM)

> Previous | Next | Contents | Index

> | privacy and legal statement |
> 6020PRO_017.HTML