Updated: 11 December 1998

DEC Text Processing Utility Reference Manual

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

"visible"

"visible_bottom"

Digital recommends that you use GET_INFO (window, "bottom", visible_text) to retrieve this information.

"visible_length"

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

"visible_top"

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

"width"

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.

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.

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.

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

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

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.

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:

! 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; 
      

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

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":

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.

PROCEDURE user_is_character (c) 
 
   LOCAL  symbol_characters; 
 
   symbol_characters := 
"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890"; 
 
   RETURN INDEX( symbol_characters, c ) > 0; 
 
ENDPROCEDURE; 
      

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

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:

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.

! 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; 
      

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

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

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

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.

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.

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; 
      

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.

Digital 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 Digital keyboards, the Alt key is labeled Compose Character.

ALT_MODIFIED modifies only function keys and keypad keys.

Digital 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.

Digital 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.

Digital 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

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:

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

---

Previous

Next

Contents

Index

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

6020PRO_016.HTML