Updated: 11 December 1998

DEC Text Processing Utility Reference Manual

Format

SET (HEIGHT, SCREEN, length)

Parameters

HEIGHT

A keyword that indicates that the SET built-in procedure is setting the height of the DECTPU main window.

SCREEN

A keyword that indicates that the screen is being resized.

length

The length (in lines) that you want the screen to have. The value must be an integer between 1 and 255.

Description

The SET (HEIGHT) procedure sets the height of the DECTPU screen without modifying the height or location of any DECTPU window. SET (HEIGHT) does not alter any DECTPU windows. However, the default EVE behavior when the screen is made smaller is to unmap windows from the screen, starting with the bottom-most window and working upward until there is room on the screen for the remaining windows. If the screen is subsequently made larger, the unmapped windows are not remapped by default.

Signaled Errors

• TPU$_TOOMANY	ERROR	You specified more than three parameters.
  TPU$_TOOFEW	ERROR	SET (HEIGHT) requires three parameters.
  TPU$_INVPARAM	ERROR	One or more of the specified parameters have the wrong type.
  TPU$_BADKEY	WARNING	The second parameter must be SCREEN.
  TPU$_BADLENGTHCHANGE	WARNING	The terminal's characteristics will not allow the height of the screen to change.
  TPU$_BADVALUE	ERROR	The terminal cannot be set to the requested height.

Example

The following example causes the screen to have a height of 20 lines:

SET (HEIGHT, SCREEN, 20); 
 
      

Format

SET (ICON_NAME, string)

Parameters

ICON_NAME

A keyword that instructs DECTPU to set the text of an icon.

string

The text you want to appear in the icon.

Description

The SET (ICON_NAME) procedure designates the string used as the layered application's name in the DECwindows icon box.

Signaled Errors

• TPU$_INVPARAM	ERROR	One of the parameters was specified with data of the wrong type.
  TPU$_NORETURNVALUE	ERROR	SET (ICON_NAME) cannot return a value.
  TPU$_REQUIRESDECW	ERROR	You can use the SET (ICON_NAME) built-in only if you are using DECwindows DECTPU.
  TPU$_TOOFEW	ERROR	Too few arguments passed to the SET (ICON_NAME) built-in.
  TPU$_TOOMANY	ERROR	Too many arguments passed to the SET (ICON_NAME) built-in.

Example

The following example sets the text naming the layered application to be the string WordMonger:

SET (ICON_NAME, "WordMonger"); 
 
      

Format

SET (ICON_PIXMAP,integer,icon_pixmap [[,widget]])

or

SET (ICON_PIXMAP,bitmap_file_name [[,widget]])

Parameters

ICON_PIXMAP

A keyword that indicates that the SET built-in procedure is being used to determine the pixmap that the application uses to create its icon in the DECwindows icon box.

integer

The hierarchy identifier returned by the SET (UID) built-in procedure. This identifier is passed to the Motif Resource Manager, which uses the identifier to find the hierarchy's resource name in the resource database.

icon_pixmap

A case-sensitive string that is the name assigned to the icon in the User Interface Language (UIL) file defining the icon pixmap. The icon must be declared EXPORTED in the UIL file.

Applications must have three icons in their UIL file, as supported by the Motif window manager:

• A small icon that is 32 pixels by 32 pixels
• A medium icon that is 50 pixels by 50 pixels
• A large icon that is 75 pixels by 75 pixels

The icon name that you pass to this built-in must match the root name of the three icon names in the UIL file.

The UIL names start with the root name and end with the dimension _nXn. For example, EVE's root name is EVE_ICON. The three icon names in EVE's Motif UIL file are therefore EVE_ICON_32X32, EVE_ICON_50X50, and EVE_ICON_75X75.

When you use the SET (ICON_PIXMAP) built-in procedure, or change the window manager icon size and restart the Motif Window Manager, DECTPU automatically selects the application's largest icon currently allowed by the Motif Window Manager. Thus, the icon pixmap can correctly fill the image area decoration of the icon. This means that a Motif application cannot specify which icon to display; DECTPU decides for it.

widget

The widget whose icon pixmap is to be set. By default, DECTPU sets the icon pixmap of its top-level widget.

bitmap_file_name

The file specification of a bitmap file. SET (ICON_PIXMAP) requires these files to be in the format created by the Xlib routine WRITE BITMAP FILE. To create a file with the correct format, you can use the OpenVMS program SYS$SYSTEM:DECW$PAINT.EXE (the DECpaint application) or the program DECW$EXAMPLES:BITMAP.EXE. If you use the paint application, use the Customize Picture Size option to set the picture size to nonstandard. Use the Zoom option to manipulate this small image. Choose the X11 format when you save the file.

On DECwindows, set the height and width to 75 pixels for large icons, to 50 pixels for medium icons, and to 32 pixels for small icons.

Description

The SET (ICON_PIXMAP) procedure determines the pixmap the application uses to create its icon in the DECwindows icon box. To specify an icon pixmap defined in a UIL file, use the first format variant shown in the format section. To specify an icon created in a bitmap file, use the second format variant shown in the format section.

Signaled Errors

• TPU$_FAILURE_STATUS	ERROR	The Digital Resource Manager returned an error status.
  TPU$_INVPARAM	ERROR	One of the parameters was specified with data of the wrong type.
  TPU$_REQUIRESDECW	ERROR	Requires the DECTPU DECwindows screen updater.
  TPU$_TOOFEW	ERROR	You specified too few parameters.
  TPU$_TOOMANY	ERROR	You specified too many parameters.
  TPU$_BADHIERARCHY	ERROR	You specified an invalid hierarchy identifier.

Example

The following example causes the icon pixmap stored in the file ICON_FLAMINGO.X11 to be displayed in the application's icon:

SET (ICON_PIXMAP, "DISK1:[SMITH]ICON_FLAMINGO.X11") 
 
      

Format

SET (INFORMATIONAL,

• ON
• OFF
• 1
• 0

)

Parameters

INFORMATIONAL

Informational messages that DECTPU writes.

ON, 1

Causes the informational messages to be displayed.

OFF, 0

Suppresses the display of informational messages.

Description

The SET (INFORMATIONAL) procedure sets whether or not you see informational messages. If you specify a section file when invoking DECTPU (either by default or by using the /NOSECTION qualifier), DECTPU may not display informational messages. You can cause informational messages to be written by using SET (INFORMATIONAL, ON).

If you use the /NOSECTION qualifier when invoking DECTPU, informational messages are written by default.

When you are developing DECTPU programs, the informational messages help you find errors in your program, so it is a good idea to use the SET (INFORMATIONAL) built-in procedure to cause the messages to be displayed.

See Appendix B for a list of the DECTPU informational messages.

Signaled Errors

Example

The following example causes the display of informational messages to be turned off:

SET (INFORMATIONAL, OFF) 
      

Format

SET (INPUT_FOCUS

• , SCREEN
• , widget

)

Parameters

INPUT_FOCUS

A keyword that directs DECTPU to request the input focus.

SCREEN

An optional keyword that indicates that the top-level widget associated with DECTPU's screen is to receive the input focus. This keyword is the default.

widget

The widget that is to receive the input focus. If you specify a widget for this parameter, the DECTPU key bindings are not available to process keyboard input into the specified widget.

You can set or get the input-focus state of a widget only if that widget is a shell widget, that is, if it has a resource named XtNinput.

Description

The SET (INPUT_FOCUS) procedure requests ownership of the input focus. Ownership of the input focus determines which application or widget processes user input from the keyboard. It does not guarantee that DECTPU or the widget gets the input focus. If DECTPU or the widget receives the input focus, it gets a focus-in event. When DECTPU gets this event, it calls the input focus grab routine. For more information about the role of events in DECwindows applications, see the VMS DECwindows Guide to Application Programming.

When the top-level widget for DECTPU's screen has the input focus, DECTPU processes keystrokes normally. That is, undefined printable keys insert characters in the current buffer, and defined keys execute the code bound to them.

If a child widget in the widget hierarchy has the input focus, keystrokes are processed by that widget. For example, when a text widget in an EVE dialog box has the input focus, keystrokes are processed by the text widget, not by DECTPU. No DECTPU key bindings are in effect.

Signaled Errors

• TPU$_BADKEY	WARNING	You specified an invalid keyword as a parameter.
  TPU$_INVPARAM	ERROR	One of the parameters was specified with data of the wrong type.
  TPU$_REQUIRESDECW	ERROR	You can use the SET (INPUT_FOCUS) built-in only if you are using DECwindows DECTPU.
  TPU$_TOOFEW	ERROR	Too few arguments passed to the SET (INPUT_FOCUS) built-in.
  TPU$_TOOMANY	ERROR	Too many arguments passed to the SET (INPUT_FOCUS) built-in.

Example

The following example is a modified version of the EVE procedure EVE$$WIDGET_REPLACE_EACH_OK. The original version is in SYS$EXAMPLES:EVE$MENUS.TPU. For more information about using the files in SYS$EXAMPLES as examples, see Appendix A.

PROCEDURE eve$$widget_replace_each_ok 
 
SET (INPUT_FOCUS);      ! This statement grabs input focus 
                        ! so Ctrl/C events will be detected. 
 
eve$$replace_loop (0, eve$x_yes); 
 
ENDPROCEDURE; 
      

Procedure EVE$$WIDGET_REPLACE_EACH_OK responds when you press the OK button in the REPLACE dialog box that asks if an occurrence of the old string should be replaced with the new string.

Format

SET (INPUT_FOCUS_GRAB , SCREEN [[,

• buffer
• learn_sequence
• program
• range
• string
• NONE

]] )

Parameters

INPUT_FOCUS_GRAB

A keyword that indicates that the SET built-in procedure is being used to set the input focus grab routine.

SCREEN

A keyword used for compatibility with future versions of DECTPU.

buffer

The buffer that specifies the actions that DECTPU should take whenever it processes a focus-in event.

learn_sequence

The learn sequence that specifies the actions that DECTPU should take whenever it processes a focus-in event.

program

The program that specifies the actions that DECTPU should take whenever it processes a focus-in event.

range

The range that specifies the actions that DECTPU should take whenever it processes a focus-in event.

string

The string that specifies the actions that DECTPU should take whenever it processes a focus-in event.

NONE

A keyword that directs DECTPU to delete the input focus grab routine. If you specify this keyword or do not specify the parameter at all, the application is not notified when input focus is received.

Description

The SET (INPUT_FOCUS_GRAB) procedure specifies the program or learn sequence that DECTPU should execute whenever it processes a focus-in event. For more information about DECTPU input focus support, see the Guide to the DEC Text Processing Utility.

Signaled Errors

• TPU$_BADKEY	WARNING	You specified an invalid keyword as a parameter.
  TPU$_INVPARAM	ERROR	One of the parameters was specified with data of the wrong type.
  TPU$_NORETURNVALUE	ERROR	SET (INPUT_FOCUS_GRAB) cannot return a value.
  TPU$_REQUIRESDECW	ERROR	You can use the SET (INPUT_FOCUS_GRAB) built-in only if you are using DECwindows DECTPU.
  TPU$_TOOFEW	ERROR	Too few arguments passed to the SET (INPUT_FOCUS_GRAB) built-in.
  TPU$_TOOMANY	ERROR	Too many arguments passed to the SET (INPUT_FOCUS_GRAB) built-in.

Example

The following example designates the procedure user_grab_focus as an input focus grab routine:

SET (INPUT_FOCUS_GRAB, SCREEN, "user_grab_focus");      
      

Format

SET (INPUT_FOCUS_UNGRAB, SCREEN [[,

• buffer
• learn_sequence
• program
• range
• string
• NONE

]] )

Parameters

INPUT_FOCUS_UNGRAB

A keyword that indicates that the SET built-in procedure is being used to set the input focus ungrab routine.

SCREEN

A keyword used for compatibility with future versions of DECTPU.

buffer

The buffer that specifies the actions that DECTPU should take whenever it processes a focus-out event.

learn_sequence

The learn sequence that specifies the actions that DECTPU should take whenever it processes a focus-out event.

program

The program that specifies the actions that DECTPU should take whenever it processes a focus-out event.

range

The range that specifies the actions that DECTPU should take whenever it processes a focus-out event.

string

The string that specifies the actions that DECTPU should take whenever it processes a focus-out event.

NONE

A keyword that directs DECTPU to delete the input focus ungrab routine. If you specify this keyword or do not specify the parameter at all, the application is not notified when input focus is lost.

Description

The SET (INPUT_FOCUS_UNGRAB) procedure specifies the program or learn sequence that DECTPU should execute whenever it processes a focus-out event. For more information about DECTPU input focus support, see the Guide to the DEC Text Processing Utility.

Signaled Errors

• TPU$_BADKEY	WARNING	You specified an invalid keyword as a parameter.
  TPU$_INVPARAM	ERROR	One of the parameters was specified with data of the wrong type.
  TPU$_NORETURNVALUE	ERROR	SET (INPUT_FOCUS_UNGRAB) cannot return a value.
  TPU$_REQUIRESDECW	ERROR	You can use the SET (INPUT_FOCUS_UNGRAB) built-in only if you are using DECwindows DECTPU.
  TPU$_TOOFEW	ERROR	Too few arguments passed to the SET (INPUT_FOCUS_UNGRAB) built-in.
  TPU$_TOOMANY	ERROR	Too many arguments passed to the SET (INPUT_FOCUS_UNGRAB) built-in.

Example

The following example designates the procedure user_ungrab_focus as an input focus ungrab routine:

SET (INPUT_FOCUS_UNGRAB, SCREEN, "user_ungrab_focus");      
 
      

Format

SET (INSERT, buffer)

Parameters

INSERT

A keyword that specifies the mode of entering text. INSERT means that characters are added to the buffer immediately before the editing point. See also the description of the SET (OVERSTRIKE) built-in procedure. The default mode for text entry is insert.

buffer

The buffer whose mode of text entry you want to set.

Description

The SET (INSERT) procedure sets the specified buffer to insert mode.

Signaled Errors

Example

The following example causes the characters that you add to the buffer to be added immediately before the editing point:

SET (INSERT, my_buffer) 
      

Format

SET (JOURNALING, buffer

• ON
• OFF
• 1
• 0

, integer [[,file_name_string ]])

or

SET (JOURNALING, integer)

Parameters

JOURNALING

A keyword that indicates that the SET built-in procedure is being used to enable or disable buffer-change journaling or set the frequency of journaling.

buffer

The buffer for which you want to enable or disable buffer-change journaling.

ON, 1

A keyword that turns on buffer-change journaling.

OFF, 0

A keyword that turns off buffer-change journaling.

integer

The integer that you specify that determines how frequently records are written to the journal file. The value of this integer must be between 1 and 10.

file_name_string

The string that names the file you want to use as the buffer's journal file. If the file does not exist, DECTPU automatically creates it. You cannot specify this parameter if you have specified the OFF keyword. If you do not specify any file name when you turn journaling on, DECTPU creates a journal file for you and names the file by using the default naming algorithm.

You can set a default journaling directory.

Description

The SET (JOURNALING) procedure turns buffer-change journaling on or off, sets the journaling frequency, and specifies a journal file name. You can turn on journaling only if the buffer is safe for journaling. For a buffer to be safe for journaling, it must either be empty, have never been modified, or be unmodified since the last time it was written to a file. (Whether the buffer has been modified is not the same as whether the buffer is marked as modified. The modified flag can be set or cleared by the application or by you.)

Once a buffer that is being journaled is written to a file, the journal file is closed and deleted and a new journal file is started that references the newly created file. Similarly, reading a file into an empty buffer does not copy the file into the journal---it simply inserts a reference to the file in the journal. This behavior must be taken into account when you perform operations that use temporary files. For example, writing a buffer to a temporary file (which is modified by an external program), then erasing the buffer and rereading a (modified) temporary file will point the journal file at the temporary file. If you then delete the temporary file, the buffer will be unrecoverable.

You can supply a journal file name only if journaling is turned on. If a journal file name is supplied, DECTPU creates a journal file that uses the name you specified. If this parameter is omitted, DECTPU creates a journal file name based on the buffer's name.

If journaling is turned off for the specified buffer, DECTPU closes the journal file but does not delete it.

DECTPU signals a warning or error if any of the following conditions apply:

• Journaling is turned on and one or more of the following is also true:
  • The specified buffer is not safe for journaling.
  • The specified buffer is already being journaled.
  • An RMS error was returned when DECTPU tried to create the journal file.
• Journaling is turned off and a journal file name is specified in the built-in call.

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.

The integer parameter specifies the journaling frequency. DECTPU provides a 500-byte buffer for journaling keystrokes. If journaling is enabled, a write to the journal file occurs when the buffer is full. With this built-in procedure, you can determine the frequency with which records are written to the journal file; the lower the integer you specify, the more often journal records are written to disk.

A value of 1 causes a record to be written for approximately every 10 keys pressed. A value of 10 causes a record to be written for approximately every 125 keys. If you are entering only text (rather than procedures that are bound to keys), the number of keystrokes included in a record is greater. For a value of 1, a record is written for approximately every 30 to 35 keystrokes; for a value of 10, a record is written for approximately every 400 keystrokes.

Signaled Errors

• TPU$_MINVALUE	WARNING	Argument is less than minimum allowed.
  TPU$_MAXVALUE	WARNING	Argument is greater than maximum allowed.
  TPU$_TOOMANY	ERROR	You specified too many parameters.
  TPU$_TOOFEW	ERROR	You specified too few parameters.
  TPU$_INVPARAM	ERROR	You specified a parameter with the wrong data type.
  TPU$_BADKEY	ERROR	You specified an invalid keyword.
  TPU$_JRNLOPEN	ERROR	A journal file for this buffer is already open.

Examples

The following example turns on buffer-change journaling for the current buffer and directs DECTPU to use the file JOURNAL.JNL in the directory [JONES] as the journal file:

SET (JOURNALING, CURRENT_BUFFER, ON, "disk1:[jones]journal.jnl"); 
 
      

---

Previous

Next

Contents

Index

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

6020PRO_028.HTML