Document revision date: 30 March 2001

## DEC Text Processing Utility Reference Manual

Previous | Contents | Index

The following example returns the comment associated with a particular key:

#2
    PROCEDURE user_get_key_info
       LOCAL key_to_interpret,
             key_info;

       MESSAGE ("Press the key you want information on: ");

       key_to_interpret := READ_KEY;
       key_info := LOOKUP_KEY (key_to_interpret, COMMENT);

       IF key_info <> ""
       THEN
           MESSAGE ("Comment: " + key_info);
       ELSE
           MESSAGE ("No comment is associated with that key.");
       ENDIF;
    ENDPROCEDURE;

> The following example implements multiple shift keys:

#3
    PROCEDURE shift_key_handler (key_map_list_name);

       LOCAL bound_program;

       bound_program := LOOKUP_KEY (READ_KEY, PROGRAM, "key_map_list_name");

       IF bound_program <> 0
       THEN
          EXECUTE (bound_program);
       ELSE
          MESSAGE ("Attempt to execute undefined key");
       ENDIF;
    ENDPROCEDURE;

    red_keys := CREATE_KEY_MAP ("red_keys");

    red_key_map_list := CREATE_KEY_MAP_LIST ("red_key_map_list",
                        red_keys);
    DEFINE_KEY ("shift_key_handler (red_key_map_list)", PF3,
               "RED shift key");

## LOWER_WIDGET

### Format

> LOWER_WIDGET (widget)

### Parameter

> #### widget

> The widget you want DECTPU to lower. The specified widget must be a subclass of WindowObjClass.

### Description

> The LOWER_WIDGET procedure places the widget at the bottom of a viewing stack. This prevents the widget window associated with the widget from obscuring any sibling windows. LOWER_WIDGET calls the XLIB routine XLowerWindow.

#### Signaled Errors

TPU$_INVPARAM | ERROR | The parameter to LOWER_WIDGET has the wrong data type.
TPU$_NORETURNVALUE | ERROR | This built-in does not return a result.
TPU$_NOTSUBCLASS | WARNING | The parameter to LOWER_WIDGET is not a widget that has an associated widget window.
TPU$_TOOFEW | ERROR | You specified too few parameters.
TPU$_TOOMANY | ERROR | You specified too many parameters.

## MANAGE_WIDGET

### Format

> MANAGE_WIDGET (widget [[, widget... ]])

### Parameter

> #### widget

> The widget to be managed.

### Description

> The MANAGE_WIDGET procedure makes the specified widget or widgets visible, provided that their parent widget is also visible.

> MANAGE_WIDGET allows the specified widget's parent to allocate space for the widget by laying out all its children for display. The parent ignores unmanaged children so that they do not take up space on the screen. If the parent widget is realized, and the specified widget's mappedWhenManaged resource is true (the default), then the widget becomes visible on the screen.

> If you have multiple children of a single widget that you want to manage, include them in a single call to MANAGE_WIDGET. Managing several widgets at once is more efficient than managing one widget at a time.

> All widgets passed in the same MANAGE_WIDGET operation must have the same parent.

#### Signaled Errors

TPU$_INVPARAM | ERROR | You specified a parameter of the wrong type.
TPU$_TOOFEW | ERROR | Too few arguments passed to the MANAGE_WIDGET built-in.
TPU$_NORETURNVALUE | ERROR | MANAGE_WIDGET cannot return a value.
TPU$_REQUIRESDECW | ERROR | You can use the MANAGE_WIDGET built-in only if you are using DECwindows DECTPU.
TPU$_WIDMISMATCH | ERROR | You have specified a widget whose class is not supported.

### Example

> For a sample procedure using the MANAGE_WIDGET built-in procedure, see Example A-1.

## MAP

### Format

> MAP ({window, buffer |widget})

### Parameters

> #### window

> The window you want to map to the screen.

> #### buffer

> The buffer you want to associate with the window.

> #### widget

> The widget you want to make visible.

### Description

> The MAP procedure associates a buffer with a window and causes the window or widget to become visible on the screen. Before using MAP, you must already have created the widget, buffer, and window that you specify as parameters. See CREATE_WIDGET, CREATE_BUFFER, and CREATE_WINDOW.

> The window and buffer that you use as parameters become the current window and the current buffer, respectively. The map operation synchronizes the cursor position with the editing point in the buffer. If the window is not already mapped to the buffer when you use MAP, DECTPU puts the cursor back in the last position the cursor occupied the last time the window was the current window.

> MAP may cause other windows that are mapped to the screen to be partially or completely occluded. If MAP causes the new window to segment another window into two pieces, only the upper part of the segmented window remains visible and continues to be updated. The lower part of the segmented window is erased on the next screen update. If you remove the window that is segmenting another window, DECTPU repaints the screen so that the window that was segmented regains its original size and position on the screen.

> In DECwindows, MAP also maps the DECTPU main widget if it has not already been mapped.

> If you execute MAP within a procedure, the screen is not updated to reflect such operations as window repainting, line erasure, or new mapping until the procedure has finished executing and control has returned to the screen manager. If you want the screen to reflect the changes before the entire program is executed, you can force the immediate update of a window by including the following statement in the procedure before any statements containing the MAP built-in:

>     UPDATE(WINDOW);

#### Signaled Errors

TPU$_TOOFEW | ERROR | MAP requires at least two parameters.
TPU$_TOOMANY | ERROR | You specified more than two parameters.
TPU$_INVPARAM | ERROR | One or more of the specified parameters have the wrong type.
TPU$_MAXMAPPEDBUF | WARNING | The buffer is already mapped to the maximum number of windows allowed by DECTPU.

### Examples

> The following example associates the main buffer with the main window and maps the main window to the screen. You must have established the main buffer and the main window with CREATE_BUFFER and CREATE_WINDOW before you can use them as parameters for MAP.

#1
    MAP (main_window, main_buffer)

> The following example creates a message buffer and a message window. It then associates the message buffer with the message window and maps the message window to the screen.

#2
    PROCEDURE user_message_window

       message_buffer := CREATE_BUFFER ("message");
       SET (EOB_TEXT, message_buffer, "");
       SET (NO_WRITE, message_buffer);
       SET (SYSTEM, message_buffer);

       message_window := CREATE_WINDOW (23, 2, OFF);
       SET (VIDEO, message_window, NONE);
       MAP (message_window, message_buffer);
    ENDPROCEDURE;

## MARK

### Format

> marker := MARK ( {BLINK |BOLD |FREE_CURSOR |REVERSE |UNDERLINE |NONE}) [[, {buffer |window} [[, integer1 [[, integer2 ]] ]] ]]

### Parameters

> #### BLINK

> A keyword that directs DECTPU to display the marker in blinking rendition.

> #### BOLD

> A keyword that directs DECTPU to display the marker in bold rendition.

> #### FREE_CURSOR

> A keyword that directs DECTPU to create a free marker (that is, a marker not bound to a character). A free marker has no video attribute.

> #### REVERSE

> A keyword that directs DECTPU to display the marker in reverse video.

> #### UNDERLINE

> A keyword that directs DECTPU to underline the marker.

> #### NONE

> A keyword that directs DECTPU to apply no video attributes to the marker.

> #### buffer

> The buffer in which the marker is to be located. By default, DECTPU locates markers in the current buffer.

> #### window

> The window that is mapped to the buffer in which the marker is to be located. You can specify a window variable only if the window is mapped to a buffer. By default, DECTPU locates markers in the current buffer.

> #### integer1

> An integer for the screen column where the marker is to be located. You can specify an integer from 1 to 32767. However, if you specify an integer smaller than the record's left margin or larger than the end of the record, DECTPU inserts padding spaces between the marker and the nearest text. The default is to locate the marker at the buffer offset that corresponds to the current screen column.

> #### integer2

> An integer for the record in the buffer where the marker is to be located. You can specify any integer greater than 1 but less than the maximum number of lines in the buffer, if it has been set with the SET (MAX_LINES) built-in procedure. The default is to locate the marker in the current record.

### Return Value

A marker for the location in a buffer that you specify.

### Description

> The MARK procedure returns a marker for a specified location in a buffer. You must specify how the marker is to be displayed on the screen (no special video, reverse video, bolded, blinking, or underlined). You can use MARK to establish placeholders or "bookmarks."

> A marker can be either bound or free. For more information on how these markers differ, see the Guide to the DEC Text Processing Utility.

> To create a bound marker, use the MARK built-in procedure with any of its parameters except FREE_CURSOR. This operation creates a bound marker even if the editing point is beyond the end of a line, before the beginning of a line, in the middle of a tab, or beyond the end of a buffer. To create a bound cursor in a location where there is no character, DECTPU fills the space between the marker and the nearest character with padding space characters.

> A bound marker is tied to the character at which it is created. If the character tied to the marker moves, the marker moves also. If the character tied to the marker is deleted, the marker moves to the nearest character position. The nearest character position is determined in the following ways:

> - If there is a character position on the same line and to the right, the marker moves to this position, even if the position is at the end of the line.
> - If the line on which the marker is located is deleted, the marker moves to the first position on the following line.

> You can move one column past the last character in a line and place a marker there. However, the video attribute for the marker is not visible unless a subsequent operation puts a character under the marker.

> If you use a marker at the end of a line as part of a range, the end of line is included in the range even though the marker is not positioned on a character.

> A marker is free if the following conditions are true:

> - You used the FREE_CURSOR keyword to create the marker.
> - There was no character in the position where you created the marker.

> DECTPU keeps track of the location of a free marker by measuring the distance between the marker and the character nearest to the marker. If you move the character from which DECTPU measures distance to a free marker, the marker moves too. DECTPU preserves a uniform distance between the character and the marker. If you collapse white space that contains one or more free markers (for example, if you delete a tab or use the APPEND_LINE built-in procedure), DECTPU preserves the markers and binds them to the nearest character.

> Unless you specify the parameter FREE_CURSOR, using the MARK built-in may result in the insertion of padding spaces or lines into the buffer if the new marker is one of the following:

> - Before the beginning of a line
> - In the middle of a tab

> - Beyond the end of a line
> - After the last line in the buffer

#### Signaled Errors

TPU$_TOOFEW | ERROR | MARK requires one parameter.
TPU$_TOOMANY | ERROR | MARK accepts only one parameter.
TPU$_NEEDTOASSIGN | ERROR | The MARK built-in must be on the right-hand side of an assignment statement.
TPU$_NOCURRENTBUF | WARNING | You must be positioned in a buffer to set a marker.
TPU$_INVPARAM | ERROR | One or more of the specified parameters have the wrong type.
TPU$_BADKEY | ERROR | The keyword must be NONE, BOLD, BLINK, REVERSE, UNDERLINE, or FREE_CURSOR.
TPU$_UNKKEYWORD | ERROR | You specified an unknown keyword.
TPU$_INSVIRMEM | FATAL | There is not enough memory to create the marker.

### Examples

> The following example places a marker at the editing point. There are no video attributes applied to the marker.

#1
    user_mark := MARK (NONE)

> The following example marks a temporary position at the current character position, and then goes to the paste buffer and creates a range of the contents of the paste buffer. DECTPU then goes to temp_pos and copies the text from the paste buffer at the temporary position.

#2
    PROCEDURE user_paste

       temp_pos := MARK (NONE);

       POSITION (END_OF (paste_buffer));
       MOVE_HORIZONTAL (-2);

       paste_text := CREATE_RANGE (BEGINNING_OF (paste_buffer),
                     MARK (NONE), NONE);
       POSITION (temp_pos);
       COPY_TEXT (paste_text);
    ENDPROCEDURE;

## MATCH

### Format

> pattern := MATCH ( {buffer |range |string})

### Parameters

> #### buffer

> An expression that evaluates to a buffer. MATCH forms a string from the contents of the buffer and stops matching when it finds the resulting string.

> #### range

> An expression that evaluates to a range. MATCH forms a string from the contents of the range and stops matching when it finds the resulting string.

> #### string

> An expression that evaluates to a string. MATCH stops matching when it finds this string.

### Return Value

A variable of type pattern that matches text from the editing point up to and including the characters specified in the parameter.

### Description

> The MATCH procedure returns a pattern that matches from the editing point up to and including the sequence of characters specified in the parameter. The matched string does not contain line terminators.

#### Signaled Errors

TPU$_NEEDTOASSIGN | ERROR | MATCH must appear on the right-hand side of an assignment statement.
TPU$_TOOFEW | ERROR | MATCH requires at least one argument.
TPU$_TOOMANY | ERROR | MATCH requires no more than one argument.
TPU$_ARGMISMATCH | ERROR | Argument to MATCH has the wrong type.
TPU$_CONTROLC | ERROR | You pressed Ctrl/C during the execution of MATCH.

### Examples

> The following example stores in pat1 a pattern that matches a string of characters starting with the editing point up to and including the characters "abc":

#1
    pat1 := MATCH ("abc")

> The following example finds text within double parentheses. It moves the editing point to the beginning of the parenthesized text, if it is found.

#2
    PROCEDURE user_double_parens

       paren_text    := "((" + MATCH ('))');
       found_range   := SEARCH_QUIETLY (paren_text, FORWARD, NO_EXACT);

       IF found_range = 0   ! No match
       THEN
           MESSAGE  ("No match found.");
       ELSE
           POSITION (found_range);
       ENDIF;
    ENDPROCEDURE;

## MESSAGE

### Formats

> MESSAGE ( {buffer |range} [[, integer1 ]])

> MESSAGE ( {integer2 |keyword |string |buffer} [[, integer3
> [[, FAO-parameter [[, FAO-parameters... ]] ]] ]])

### Parameters

> #### buffer

> The buffer that contains the text that you want to include in the message buffer.

> #### range

> The range that contains the text that you want to include in the message buffer.

> #### integer1

> An integer that indicates the severity of the message placed in the message buffer. If you do not specify this parameter, no severity code is associated with the message. The allowable integer values and their meanings are as follows:

> Integer | Meaning
> --- | ---
> 0 | Warning
> 1 | Success
> 2 | Error
> 3 | Informational

> #### integer2

> The integer that represents the message code associated with the text to be fetched.

> #### keyword

> The DECTPU keyword that represents the message code associated with the text to be fetched. DECTPU provides keywords for all of the message codes used by DECTPU and EVE.

> #### string

> Either a quoted string or a variable that represents the text you want to include in the message buffer.

> #### integer3

> A bit-encoded integer that specifies what fields of the message text associated with the message code from the first parameter are to be fetched. If the message flags are not specified or the value is 0, then the message flags set by the SET (MESSAGE_FLAGS) built-in procedure are used.

> Table 2-7 shows the message flags.

> Table 2-7 Message Flag Values for MESSAGE
> Bit | Constant | Meaning
> --- | --- | ---
> 0 | TPU$K_MESSAGE_TEXT | Include text of message.
> 1 | TPU$K_MESSAGE_ID | Include message identifier.
> 2 | TPU$K_MESSAGE_SEVERITY | Include severity level indicator.
> 3 | TPU$K_MESSAGE_FACILITY | Include facility name.

> #### FAO-parameter

> One or more expressions that evaluate to an integer or string. The MESSAGE_TEXT built-in procedure uses these integers and strings as arguments to the $FAO system service, substituting the values into the text associated with the message code to form the resultant string.

> The FAO directives are listed in the description of $FAO in the OpenVMS System Services Reference Manual.

### Description

> The MESSAGE procedure, depending on the format you choose, either puts the characters that you specify into the message buffer or else fetches text associated with a message code, formats the text using FAO directives, and puts it in the message buffer.

> If you use the first format, MESSAGE inserts the characters in the string, range, or buffer that you specify into the message buffer, if one exists. (By default, DECTPU looks for a buffer variable that is named MESSAGE_BUFFER.) If there is no message buffer, DECTPU displays the message at the current location on the device pointed to by SYS$OUTPUT (usually your terminal).

> If you use the first format, MESSAGE provides the user who is writing an editing interface with a method for displaying messages in a way that is consistent with the DECTPU language.

> If you use the second format, MESSAGE fetches the text associated with a message code, uses FAO directives to format the text, and displays the formatted message in the message buffer. (If there is no message buffer, DECTPU displays the message on SYS$OUTPUT (usually your terminal).)

> If you use the second format, MESSAGE writes a formatted string in the message buffer. The difference between MESSAGE and MESSAGE_TEXT is that MESSAGE_TEXT returns the resulting string while MESSAGE places the resulting string in the message buffer. The string is specified by the message code passed as the first parameter and constructed according to the rules of the $FAO system service. The control string associated with the message code directs the formatting process, and the optional arguments are values to be substituted into the control string.

> MESSAGE accepts up to 127 parameters. This built-in can return strings of 65535 characters maximum.

> If you have associated a message buffer with a message window, and if the message window is mapped to the screen, the range you specify appears immediately in the message window on the screen.

> If you have not associated a message buffer with a message window, messages are written to the buffer but do not appear on the screen.

> MESSAGE capitalizes the first character of the string placed in the message buffer. The MESSAGE_TEXT built-in procedure, on the other hand, does not capitalize the first character of the returned string.

> You can include the following FAO directives as part of the message text:

> !AS | Inserts a string as is
> !OL | Converts an integer to octal notation
> !XL | Converts an integer to hexadecimal notation
> !ZL | Converts an integer to decimal notation
> !UL | Converts an integer to decimal notation without adjusting for negative numbers
> !SL | Converts an integer to decimal notation with negative numbers converted
> !/ | Inserts a new line character (carriage return/line feed)
> !_ | Inserts a tab
> !} | Inserts a form feed
> !! | Inserts an exclamation point
> !%S | Inserts an s if the most recently converted number is not 1
> !%T | Inserts the current time if you enter 0 as the parameter (you cannot pass a specific time because DECTPU does not use quadwords)
> !%D | Inserts the current date and time if you enter 0 as the parameter (you cannot pass a specific date because DECTPU does not use quadwords)

#### Signaled Errors

TPU$_TOOFEW | ERROR | MESSAGE requires at least one argument.
TPU$_TOOMANY | ERROR | MESSAGE cannot accept as many arguments as you specified.
TPU$_ARGMISMATCH | ERROR | You specified an argument of the wrong type.
TPU$_INVFAOPARAM | WARNING | Argument was not a string or integer.
TPU$_INVPARAM | ERROR | You specified an argument of the wrong type.
TPU$_FLAGTRUNC | INFORMATIONAL | Message flag truncated to 4 bits.
TPU$_SYSERROR | ERROR | Error fetching the message text.
TPU$_ILLSEVERITY | WARNING | Illegal severity specified; DECTPU used the severity "error."
TPU$_MSGNOTFND | WARNING | Message not found. DECTPU returned default message.

### Examples

> The following example writes the text "Hello" in the message area:

#1
    MESSAGE ("Hello")

> Previous | Next | Contents | Index

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