Document revision date: 30 March 2001

## DEC Text Processing Utility Reference Manual

Previous | Contents | Index

Compaq recommends that you use GET_INFO (window, "length", visible_window) to retrieve this information.

#### "visible_top"

Returns an integer that is the screen line number of the visible top of the window. Use the ADJUST_WINDOW built-in procedure, create other windows, or map a window on top of the current window to change this value.

Compaq recommends that you use GET_INFO (window, "top", visible_window) to retrieve this information.

#### "width"

Returns an integer that is the number of columns or the number of visible columns in the specified window or the specified window's text area. The number of columns returned depends on the keyword you specify as the third parameter. If you do not specify a keyword, the default is TEXT. Valid keywords are shown in Table 2-6.

Use the SET built-in procedure to establish or change this parameter.

### Return Values

> #### buffer

> Returns requested information about the buffer you specify.

> #### integer

> Returns requested information about the array you specify.

> #### keyword

> Returns requested information about the keyword you specify.

> #### string

> Returns requested information about the string you specify.

> #### widget

> Returns requested information about the widget you specify.

> #### window

> Returns requested information about the window you specify.

### Description

> The GET_INFO (window_variable) procedure returns information about a specified window.

> For general information about using all forms of GET_INFO built-in procedures, see the description of GET_INFO.

### Examples

> The following example returns the last line of the window bottom_window. The value returned is the line that contains the status line or scroll bar, whichever comes last, if the window has a status line or scroll bar.

#1
    last_line := GET_INFO (bottom_window, "bottom", WINDOW);

> The following example returns the number of the rightmost column in the current window. The column whose number is returned can be occupied by a vertical scroll bar if one is present. Also, the returned value changes if you widen the window, but not if you move the window without widening it.

#2
    last_column := GET_INFO (CURRENT_WINDOW, "right", WINDOW);

> The following example returns the number of the first row in the current window. The row number returned is relative to the top of the DECTPU screen. Thus, if the current window is not the top window on the DECTPU screen, the row number returned is not 1.

#3
    first_row := GET_INFO (CURRENT_WINDOW, "top", WINDOW);

## HELP_TEXT

### Format

> HELP_TEXT (library-file, topic, {ON |OFF |1 |0} ,buffer)

### Parameters

> #### library-file

> A string that is the file specification of the help library. The string can be a logical name.

> #### topic

> A string that is the initial library topic. If this string is empty, the top level of help is displayed.

> #### ON, 1

> A keyword or integer that specifies that the VMS Help utility should prompt you for input.

> #### OFF, 0

> A keyword or integer that specifies that prompting should be turned off.

> #### buffer

> The buffer to which the help information is written.

### Description

> The HELP_TEXT procedure provides help information on the topic you specify. You must specify the help library to be used for help information, the initial library topic, the prompting mode for the Help utility, and the buffer to which DECTPU will write the help information. You can enter a complete file specification for the help library as the first parameter. However, if you enter only a file name, the Help utility provides a default device (SYS$HELP) and default file type (.HLB).

> If you do not specify an initial topic as the second parameter, you must enter a null string as a placeholder. The Help utility then displays the top level of help available in the specified library.

> When the prompting mode is ON for the HELP_TEXT built-in procedure, the following prompt appears if the help text contains more than one window of information:

>     Press RETURN to continue ...

> Before DECTPU invokes the Help utility, it erases the buffer specified as the help buffer. (In EVE, the buffer to which the help information is written is represented by the variable help_buffer.) If the help buffer is associated with a window that is mapped to the screen, the window is updated each time DECTPU prompts you for input. If you set the prompting mode to OFF, the window is not updated.

> If help_buffer is not associated with a window that is mapped to the screen, the information from the Help utility is not visible.

#### Signaled Errors

TPU$_BADKEY | ERROR | Only ON and OFF are allowed.
TPU$_INVPARAM | ERROR | One or more of the specified parameters have the wrong type.
TPU$_NOTMODIFIABLE | WARNING | The output buffer is currently unmodifiable.
TPU$_OPENIN | ERROR | Error opening help library.
TPU$_SYSERROR | ERROR | Error activating the help library.
TPU$_TOOFEW | ERROR | The HELP_TEXT built-in requires four parameters.
TPU$_TOOMANY | ERROR | You specified more than four parameters.

### Examples

> The following example causes the top level of help information from the SYS$HELP:TPUHELP.HLB library to be written to the help buffer. The Help utility prompting mode is not turned on.

#1
    HELP_TEXT ("tpuhelp", "", OFF ,help_buffer)

> This procedure displays information about getting out of help mode on the status line, prompts you for input, and maps help_buffer to the screen:

#2
    ! Interactive HELP

    PROCEDURE user_help

       SET (STATUS_LINE, info_window, UNDERLINE,
           "Press Ctrl/Z to leave prompts then Ctrl/F to resume editing");

       MAP (info_window, help_buffer);
       HELP_TEXT ("USERHELP", READ_LINE ("Topic: "), ON, help_buffer);
    ENDPROCEDURE;

## INDEX

### Format

> integer := INDEX (string, substring)

### Parameters

> #### string

> The string within which you want to find a character or a substring.

> #### substring

> A character or a substring whose leftmost character location you want to find within string1.

### Return Value

An integer that shows the character position within a string of the substring you specify.

### Description

> The INDEX procedure locates a character or a substring within a string and returns its location within the string. INDEX finds the leftmost occurrence of substring within string. It returns an integer that indicates the character position in string at which substring was found. If string is not found, DECTPU returns a 0. The character positions within string start at the left with 1.

#### Signaled Errors

TPU$_NEEDTOASSIGN | ERROR | INDEX must be on the right-hand side of an assignment statement.
TPU$_TOOFEW | ERROR | INDEX requires two arguments.
TPU$_TOOMANY | ERROR | INDEX accepts only two arguments.
TPU$_INVPARAM | ERROR | The arguments to INDEX must be strings.

### Examples

> The following example stores an integer value of 6 in the variable loc because the substring "67" is found starting at character position 6 within the string "1234567":

#1
    loc := INDEX ("1234567","67")

> The following example uses the INDEX built-in procedure to return true if a given item is an alphanumeric character; otherwise, it returns false. (The list of characters in this example does not include characters that are not in the ASCII range of the DEC Multinational Character Set. However, you can write a procedure that uses such characters because DECTPU supports the DEC Multinational Character Set.) The parameter that is passed to this procedure is assumed to be a single character.

#2
    PROCEDURE user_is_character (c)

       LOCAL  symbol_characters;

       symbol_characters :=
    "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890";

       RETURN INDEX( symbol_characters, c ) > 0;

    ENDPROCEDURE;

## INT

### Format

> integer3 := INT ({integer1 |keyword |string [[, integer2 ]] })

### Parameters

> #### integer1

> Any integer value. INT accepts a parameter of type integer so you need not check the type of the parameter you supply.

> #### keyword

> A keyword whose internal value you want.

> #### string

> A string that consists of numeric characters.

> #### integer2

> An integer that specifies the radix (base) of the string being converted. The default radix is 10. The other allowable values are 8 and 16.

### Return Value

The integer equivalent of the parameter you specify.

### Description

> The INT procedure converts a keyword or a string that consists of numeric characters into an integer. You can use INT to store an integer value for a keyword or a string of numeric characters in a variable. You can then use the variable name in operations that require integer data types.

> INT signals a warning and returns 0 if the string is not a number.

#### Signaled Errors

TPU$_NEEDTOASSIGN | ERROR | INT returns a value that must be used.
TPU$_TOOFEW | ERROR | INT requires one parameter.
TPU$_TOOMANY | ERROR | INT accepts only one parameter.
TPU$_ARGMISMATCH | ERROR | The parameter to INT was not a keyword or string.
TPU$_INVNUMSTR | WARNING | The string you passed to INT was not a number.
TPU$_NULLSTRING | WARNING | You passed a string of length 0 to INT.
TPU$_BADVALUE | ERROR | You specified a value other than 8, 10, or 16 for the radix parameter.

### Examples

> The following example converts the string "12345" into an integer value and stores it in the variable user_int:

#1
    user_int := INT ("12345")

> The following example is used by commands that prompt for integers. The procedure returns true if prompting worked or was not needed; otherwise it returns false. The number that is returned is returned in the output parameter.

#2
    ! Parameters:
    !
    !   new_number          New integer value - output
    !   prompt_string       Text of prompt - input
    !   no_value_message    Message printed if you press the
    !                       RETURN key to get out of the command - input

    PROCEDURE user_prompt_number (new_number, prompt_string,
                                  no_value_message)
       LOCAL read_line_string;

       ON_ERROR
           IF ERROR = TPU$_NULLSTRING
           THEN
              MESSAGE (no_value_message);
           ELSE
              IF ERROR = TPU$_INVNUMSTR
              THEN
                 MESSAGE (FAO ("Don't understand !AS",
                              read_line_string));
              ELSE
                 MESSAGE (ERROR_TEXT);
              ENDIF;
           ENDIF;
           user_prompt_number := 0;
       ENDON_ERROR;

       user_prompt_number := 1;
       read_line_string := READ_LINE (prompt_string);

       EDIT (read_line_string, TRIM);
       TRANSLATE (read_line_string, "1", "l");

       new_number := INT (read_line_string);
    ENDPROCEDURE;

## JOURNAL_CLOSE

### Format

> JOURNAL_CLOSE

### Parameters

> None.

### Description

> The JOURNAL_CLOSE procedure closes an open keystroke journal file (if one exists for your session) and saves the journal file. JOURNAL_CLOSE applies only to keystroke journaling. Once you specify JOURNAL_CLOSE, DECTPU does not keep a keystroke journal of your work until you specify JOURNAL_OPEN. Calling the JOURNAL_OPEN built-in procedure causes DECTPU to open a new keystroke journal file for your session.

> To turn off buffer-change journaling, see the description of the SET (JOURNALING) built-in procedure.

> Caution Journal files contain a record of all information being edited. Therefore, when editing files that contain secure or confidential data, be sure to keep the journal files secure as well.

#### Signaled Error

TPU$_TOOMANY | ERROR | JOURNAL_CLOSE accepts no arguments.

## JOURNAL_OPEN

### Format

> [[string := ]] JOURNAL_OPEN (file-name)

### Parameter

> #### file-name

> A string that is the name of the keystroke journal file created for your editing session.

### Return Value

The file specification of the file journaled.

### Description

> The JOURNAL_OPEN procedure opens a keystroke journal file and starts making a copy of your editing session by recording every keystroke you make. If you invoked DECTPU with the /RECOVER qualifier, then DECTPU recovers the previous aborted session before recording new keystrokes. JOURNAL_OPEN optionally returns a string that contains the file specification of the file journaled. JOURNAL_OPEN applies only to keystroke journaling.

> DECTPU saves the keystrokes of your editing session by storing them in a buffer. DECTPU writes the contents of this buffer to the file that you specify as a journal file. If DECTPU terminates unexpectedly, you can recover your editing session by using this journal file. To do this, invoke DECTPU with the /RECOVER qualifier. See the Guide to the DEC Text Processing Utility for information on recovering files.

> To turn on buffer-change journaling, see the description of the SET (JOURNALING) built-in procedure.

> By default, DECTPU writes keystrokes to the journal file whenever the journal buffer contains 500 bytes of data. DECTPU also tries to write keystrokes to the journal file when it aborts.

> When you recover a DECTPU session, your terminal characteristics should be the same as they were when the journal file was created. If they are not the same, DECTPU informs you what characteristics are different and asks whether you want to continue recovering. If you answer yes, DECTPU tries to recover; however, the different terminal settings may cause differences between the recovered session and the original session.

> There are no keystrokes in batch mode. You can use JOURNAL_OPEN nodisplay mode with the /NODISPLAY qualifier; however, when you do this, nothing is journaled.

> Caution Journal files contain a record of all information being edited. Therefore, when editing files that contain secure or confidential data, be sure to keep the journal files secure as well.

#### Signaled Errors

TPU$_BADJOUFILE | ERROR | JOURNAL_OPEN could not open the journal file.
TPU$_TOOFEW | ERROR | JOURNAL_OPEN requires one argument.
TPU$_TOOMANY | ERROR | JOURNAL_OPEN accepts only one argument.
TPU$_INVPARAM | ERROR | The parameter to JOURNAL_OPEN must be a string.
TPU$_ASYNCACTIVE | WARNING | You cannot journal with asynchronous handlers declared.
TPU$_JNLOPEN | ERROR | A journal file is already open.

### Examples

> The following example causes DECTPU to open a file named TEST.FIL as the journal file for your editing session. DECTPU uses your current default device and directory to complete the file specification.

#1
    JOURNAL_OPEN ("test.fil")

> The following example starts journaling. It can be called from the TPU$INIT_PROCEDURE after a file is read into the current buffer.

#2
    PROCEDURE user_start_journal

       LOCAL default_journal_name,  ! Default journal name
             aux_journal_name;      ! Auxiliary journal name derived
                                    ! from file name
       IF (GET_INFO (COMMAND_LINE, "journal") = 1)
       AND
          (GET_INFO (COMMAND_LINE, "read_only") <> 1)
       THEN
          aux_journal_name := GET_INFO (CURRENT_BUFFER, "file_name");

          IF aux_journal_name = ""
          THEN
             aux_journal_name := GET_INFO (CURRENT_BUFFER, "output_file");
          ENDIF;

          IF (aux_journal_name = "") or (aux_journal_name = 0)
          THEN
             default_journal_name := "user.TJL";
          ELSE
             default_journal_name := ".TJL";
          ENDIF;

          journal_file := GET_INFO (COMMAND_LINE, "journal_file");
          journal_file := FILE_PARSE (journal_file, default_journal_name,
                                     aux_journal_name);
          JOURNAL_OPEN (journal_file);
       ENDIF;
    ENDPROCEDURE;

## KEY_NAME

### Format

> keyword2 := KEY_NAME ({integer |key_name |string}
> [[, {SHIFT_KEY |SHIFT_MODIFIED |ALT_MODIFIED |CTRL_MODIFIED |HELP_MODIFIED} [[, ...]] ]], [[, FUNCTION |, KEYPAD]])

### Parameters

> #### integer

> An integer that is either the integer representation of a keyword for a key, or is a value between 0 and 255 that DECTPU interprets as the value of a character in the DEC Multinational Character Set.

> #### key_name

> A keyword that is the DECTPU name for a key.

> #### string

> A string that is the value of a key from the main keyboard.

> #### SHIFT_KEY

> A keyword that specifies that the key name created includes one or more shift keys. The SHIFT_KEY keyword specifies the DECTPU shift key, not the key on the keyboard marked Shift. The shift key is also referred to as the GOLD key in EVE. (See the description of the SET (SHIFT_KEY) built-in procedure in the VAX Text Processing Utility Manual.)

> #### SHIFT_MODIFIED

> A keyword that specifies that the key name created by the built-in includes the key marked Shift on the keyboard that toggles between uppercase and lowercase, not the key known as the GOLD key.

> Compaq recommends that you avoid using this keyword in the non-DECwindows version of DECTPU. In non-DECwindows DECTPU, when you use this keyword to create a key name, the keyboard cannot generate a corresponding key.

> #### ALT_MODIFIED

> A keyword that specifies that the key name created by the built-in includes the Alt key. On most Compaq keyboards, the Alt key is labeled Compose Character.

> ALT_MODIFIED modifies only function keys and keypad keys.

> Compaq recommends that you avoid using this keyword in the non-DECwindows version of DECTPU. In non-DECwindows DECTPU, when you use this keyword to create a key name, the keyboard cannot generate a corresponding key.

> #### CTRL_MODIFIED

> A keyword that specifies that the key name created by the built-in includes the Ctrl key.

> CTRL_MODIFIED modifies only function keys and keypad keys.

> Compaq recommends that you avoid using this keyword in the non-DECwindows version of DECTPU. In non-DECwindows DECTPU, when you use this keyword to create a key name, the keyboard cannot generate a corresponding key.

> #### HELP_MODIFIED

> A keyword that specifies that the key name created by the built-in includes the Help key.

> HELP_MODIFIED modifies only function keys and keypad keys.

> Compaq recommends that you avoid using this keyword in the non-DECwindows version of DECTPU. In non-DECwindows DECTPU, when you use this keyword to create a key name, the keyboard cannot generate a corresponding key.

> #### FUNCTION

> A parameter that specifies that the resulting key name is to be that of a function key.

> #### KEYPAD

> A parameter that specifies that the resulting key name is to be that of a keypad key.

### Return Value

A DECTPU keyword to be used as the name of a key.

### Description

> The KEY_NAME procedure returns a DECTPU keyword for a key or a combination of keys, or creates a keyword used as a key name by DECTPU. With KEY_NAME, you can create key names that are modified by more than one key. For example, you can create a name for a key sequence that consists of the GOLD key, the Ctrl key, and an alphanumeric or keypad key.

> The GET_INFO (key_name, "key_modifiers") built-in procedure returns a bit-encoded integer whose value represents the key modifier or combination of key modifiers used to create a given key name. For more information about interpreting the integer returned, see the description of GET_INFO (key_name, "key_modifiers").

> The GET_INFO (keyword, "name") built-in procedure has been extended to return a string that includes all the key modifier keywords used to create a key name. For more information about fetching the string equivalent of a key name, see the description of GET_INFO (keyword, "name").

> If you specify only one DECTPU key name as an argument to KEY_NAME, KEY_NAME is sensitive to the case of the argument. For example, the following expressions do not evaluate to the same value:

>     KEY_NAME ("Z");
>     KEY_NAME ("z");

> When you use the optional parameter SHIFT_KEY with KEY_NAME, however, KEY_NAME is case insensitive and the following statements return the same keyword:

>     KEY_NAME ("Z", SHIFT_KEY);
>     KEY_NAME ("z", SHIFT_KEY);

#### Signaled Errors

TPU$_INCKWDCOM | WARNING | Inconsistent keyword combination.
TPU$_MUSTBEONE | WARNING | String must be one character long.
TPU$_NOTDEFINABLE | WARNING | Second argument is not a valid reference to a key.
TPU$_NEEDTOASSIGN | ERROR | KEY_NAME call must be on the right-hand side of an assignment statement.
TPU$_ARGMISMATCH | ERROR | Wrong type of data sent to the KEY_NAME built-in.
TPU$_BADKEY | ERROR | KEY_NAME accepts SHIFT_KEY, FUNCTION, or KEYPAD as a keyword argument.
TPU$_TOOFEW | ERROR | Too few arguments passed to the KEY_NAME built-in.
TPU$_TOOMANY | ERROR | Too many arguments passed to the KEY_NAME built-in.

### Examples

> The following example creates a name for the key sequence GOLD/Ctrl/KP4 and binds the EVE FILL command to the resulting key sequence:

#1
    new_key := KEY_NAME (KP4, Ctrl_MODIFIED, SHIFT_KEY);
    DEFINE_KEY ("eve_fill", new_key);

> Previous | Next | Contents | Index

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