Updated: 11 December 1998

DEC Text Processing Utility Reference Manual

Format

SET (FACILITY_NAME, string)

Parameters

FACILITY_NAME

A keyword that indicates that the SET built-in procedure is being used to set the first item (the facility name) in a message generated by DECTPU.

string

The string that you specify as the facility name for messages. The maximum length of this name is 10 characters.

Description

The SET (FACILITY_NAME) procedure sets the facility name for messages. The facility name appears in messages if you have used the SET (MESSAGE_FLAGS) built-in procedure either to explicitly include the facility name in messages or to include the facility name only if enabled by the default message flags for your OpenVMS process.

Signaled Errors

• TPU$_FACTOOLONG	WARNING	Name specified is longer than maximum allowed.
  TPU$_MINVALUE	WARNING	Argument specified is less than the minimum allowed.
  TPU$_ARGMISMATCH	ERROR	The second parameter must be a string.
  TPU$_INVPARAM	ERROR	One or more of the specified parameters have the wrong type.

Example

The following example causes "new_editor" to be used as the facility name in messages:

SET (FACILITY_NAME, "new_editor") 
      

Format

SET (FIRST_INPUT_ACTION,

• NONE
• program_source

)

Parameters

FIRST_INPUT_ACTION

A keyword that specifies that DECTPU is to implement the application's first input action routine.

NONE

A keyword that disables the current action routine.

program_source

Specifies the program or learn sequence that DECTPU executes when it gets the first key or button event.

Description

The SET (FIRST_INPUT_ACTION) procedure specifies the program or learn sequence that DECwindows DECTPU executes when it gets the first key or button event. DECwindows EVE uses FIRST_INPUT_ACTION to set an action routine that removes the copyright notice from the title bar when you first press a key or mouse button.

This built-in is valid only until DECTPU gets the first key or mouse event. After that first event, DECTPU signals TPU$_BUILTININV, "Built-in is invalid at this time."

Signaled Errors

Example

The following example causes the procedure REMOVE_COPYRIGHT to be executed when you press the first key or mouse button in the DECwindows application. That procedure typically sets the "title" resource of the application's shell widget to be the name of the application, removing the original copyright notice in the title bar.

SET (FIRST_INPUT_ACTION, "remove_copyright") 
 
      

Format

SET (FORWARD, buffer)

Parameters

FORWARD

A keyword that specifies the direction of the buffer. FORWARD means to go toward the end of the buffer. The default direction for a buffer is forward.

buffer

The buffer whose direction you want to set.

Description

The SET (FORWARD) procedure sets the specified buffer's direction to forward. The editor uses this feature to keep track of direction for searching or movement.

Signaled Errors

Example

The following example causes the direction of the buffer to be toward the end of the buffer:

SET (FORWARD, my_buffer) 
 
      

Format

[[ integer := ]] SET (GLOBAL_SELECT, SCREEN,

• PRIMARY
• SECONDARY
• selection_name

),

• GLOBAL_SELECT_GRAB
• GLOBAL_SELECT_UNGRAB

Parameters

GLOBAL_SELECT

A keyword that indicates that the SET built-in procedure is being used to request a global selection property.

SCREEN

A keyword used to preserve compatibility with future versions of DECTPU.

PRIMARY

A keyword that directs DECTPU to request ownership of the primary global selection.

SECONDARY

A keyword that directs DECTPU to request ownership of the secondary global selection.

selection_name

A string that names the global selection whose ownership DECTPU is to request.

GLOBAL_SELECT_GRAB

A keyword that tells DECTPU to grab the selection. This is the default.

GLOBAL_SELECT_UNGRAB

A keyword that tells DECTPU to relinquish the grab of the selection.

Return Value

Description

The SET (GLOBAL_SELECT) procedure requests ownership of the specified global selection property. SET (GLOBAL_SELECT) returns the integer 1 if the request for ownership of a global selection was granted; otherwise 0.

DECTPU is notified immediately if its request is granted. Therefore, DECTPU does not automatically execute the global selection grab routine when it encounters SET (GLOBAL_SELECT). DECTPU executes the routine only when it automatically grabs the primary selection after it receives input focus.

Applications can voluntarily relinquish global selections through the optional GLOBAL_SELECT_UNGRAB parameter.

For more information about the concept of global selection, see the OSF/Motif Style Guide.

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 (GLOBAL_SELECT) built-in only if you are using DECwindows DECTPU.
  TPU$_TOOFEW	ERROR	Too few arguments passed to the SET (GLOBAL_SELECT) built-in.
  TPU$_TOOMANY	ERROR	Too many arguments passed to the SET (GLOBAL_SELECT) built-in.

Examples

The following example requests ownership of the primary global selection:

SET (GLOBAL_SELECT, SCREEN, PRIMARY); 
 
      

The following example shows the use of the GLOBAL_SELECT_UNGRAB parameter. In this statement, global selection is relinquished.

SET (GLOBAL_SELECT, SCREEN, PRIMARY, GLOBAL_SELECT_UNGRAB); 
                                          
      

Format

SET (GLOBAL_SELECT_GRAB, SCREEN
[[,

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

]])

Parameters

GLOBAL_SELECT_GRAB

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

SCREEN

A keyword used to preserve compatibility with future versions of DECTPU.

buffer

The buffer that contains the grab routine.

learn_sequence

The learn sequence that specifies the grab routine.

program

The program that specifies the grab routine.

range

The range that contains the grab routine.

string

The string that contains the grab routine.

NONE

A keyword that directs DECTPU to delete the current global selection grab routine. This is the default if you do not specify the optional third parameter.

Description

The SET (GLOBAL_SELECT_GRAB) procedure specifies the program or learn sequence that DECTPU should execute whenever it automatically grabs ownership of the primary selection. For more information about DECTPU global selection support, see the Guide to the DEC Text Processing Utility.

If the optional parameter is not specified, NONE is the default. When NONE is specified or used by default, DECTPU deletes the current global selection grab routine. When no global selection grab routine is defined, your application is not informed when DECTPU grabs the primary global selection.

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 (GLOBAL_SELECT_GRAB) cannot return a value.
  TPU$_REQUIRESDECW	ERROR	You can use the SET (GLOBAL_SELECT_GRAB) built-in only if you are using DECwindows DECTPU.
  TPU$_TOOFEW	ERROR	Too few arguments passed to the SET (GLOBAL_SELECT_GRAB) built-in.
  TPU$_TOOMANY	ERROR	Too many arguments passed to the SET (GLOBAL_SELECT_GRAB) built-in.

Example

The following example designates the procedure user_grab_global as a global selection read routine:

SET (GLOBAL_SELECT_GRAB, SCREEN, "user_grab_global");      
 
      

Format

SET (GLOBAL_SELECT_READ,

• buffer1
• SCREEN

[[,

• buffer2
• learn_sequence
• program
• range
• string
• NONE

]])

Parameters

GLOBAL_SELECT_READ

A keyword that indicates that the SET built-in procedure is being used to set the global select read routine.

buffer1

The buffer with which the global selection read routine is to be associated.

SCREEN

A keyword that indicates that the specified routine is to be the application's default global selection read routine.

buffer2

The buffer that contains the global selection read routine.

learn_sequence

The learn sequence that specifies the global selection read routine.

program

The program that specifies the global selection read routine.

range

The range that contains the global selection read routine.

string

The string that contains the global selection read routine.

NONE

A keyword that indicates that the global selection read routine should be deleted. If you do not specify the optional third parameter, NONE is the default.

Description

The SET (GLOBAL_SELECT_READ) procedure specifies the program or learn sequence that DECTPU should execute whenever it receives a selection request event on a global selection it owns. To specify a buffer-specific global selection read routine, use the buffer1 parameter. To specify a global selection read routine for the entire application, use the SCREEN keyword.

When DECTPU receives a request for information about a global selection it owns, it checks to see if the current buffer has a global selection read routine. If so, it executes that routine. If not, it checks to see if there is an application-wide global selection read routine. If so, it executes that routine. If not, it tries to respond to the request itself.

If the optional parameter is not specified, NONE is the default. When NONE is specified or used by default, DECTPU deletes the current global selection read routine.

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 (GLOBAL_SELECT_READ) cannot return a value.
  TPU$_REQUIRESDECW	ERROR	You can use the SET (GLOBAL_SELECT_READ) built-in only if you are using DECwindows DECTPU.
  TPU$_TOOFEW	ERROR	Too few arguments passed to the SET (GLOBAL_SELECT_READ) built-in.
  TPU$_TOOMANY	ERROR	Too many arguments passed to the SET (GLOBAL_SELECT_READ) built-in.

Example

The following example designates the procedure user_read_global as a global selection read routine:

SET (GLOBAL_SELECT_READ, SCREEN, "user_read_global");      
      

Format

SET (GLOBAL_SELECT_TIME, SCREEN,

• integer
• string

)

Parameters

GLOBAL_SELECT_TIME

A keyword that indicates that the SET built-in procedure is directing DECTPU to set the expiration time for a global selection information request.

SCREEN

A keyword used to maintain compatibility with future versions of DECTPU.

integer

The number of seconds that DECTPU should wait.

string

A string that indicates how long DECTPU should wait. The format of the string is "dd hh:mm:ss.cc" where dd is the number of days (0-24), hh is the number of hours (0-23), mm is the number of minutes (0-59), ss is the number of seconds (0-59), and cc is the number of hundredths of seconds (0-99).

Description

The SET (GLOBAL_SELECT_TIME) procedure specifies how long DECTPU should wait before it assumes that a request for information about a global selection will not be satisfied. The default waiting time is set by DECwindows. The maximum waiting time you can set is 24 days, 20 hours.

Signaled Errors

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

Example

The following example sets the waiting time for a global selection response to 3 seconds:

SET (GLOBAL_SELECT_TIME, SCREEN, 3); 
      

Format

SET (GLOBAL_SELECT_UNGRAB, SCREEN
[[,

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

]])

Parameters

GLOBAL_SELECT_UNGRAB

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

SCREEN

A keyword used to preserve compatibility with future versions of DECTPU.

buffer

The buffer that contains the global selection ungrab routine.

learn_sequence

The learn sequence that specifies the global selection ungrab routine.

program

The program that specifies the global selection ungrab routine.

range

The range that contains the global selection ungrab routine.

string

The string that contains the global selection ungrab routine.

NONE

A keyword that directs DECTPU to delete the current global selection ungrab routine. This is the default if you do not specify the optional third parameter.

Description

The SET (GLOBAL_SELECT_UNGRAB) procedure specifies the program or learn sequence that DECTPU should execute whenever it loses ownership of a selection. For more information about DECTPU global selection support, see the Guide to the DEC Text Processing Utility.

If the optional parameter is not specified, NONE is the default. When NONE is specified or used by default, DECTPU deletes the current global selection ungrab routine. When no global selection ungrab routine is defined, your application is not informed when DECTPU loses ownership of the primary global selection.

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 (GLOBAL_SELECT_UNGRAB) cannot return a value.
  TPU$_REQUIRESDECW	ERROR	You can use the SET (GLOBAL_SELECT_UNGRAB) built-in only if you are using DECwindows DECTPU.
  TPU$_TOOFEW	ERROR	Too few arguments passed to the SET (GLOBAL_SELECT_UNGRAB) built-in.
  TPU$_TOOMANY	ERROR	Too many arguments passed to the SET (GLOBAL_SELECT_UNGRAB) built-in.

Example

The following example designates the procedure user_ungrab_global as a global selection ungrab routine:

SET (GLOBAL_SELECT_UNGRAB, SCREEN, "user_ungrab_global");      
 
      

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

6020PRO_027.HTML