Document revision date: 30 March 2001

## DEC Text Processing Utility Reference Manual

Previous | Contents | Index

## SET (FIRST_INPUT_ACTION)

### 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

TPU$_BUILTININV | ERROR | This indicates that the first key or button event has already occurred.
TPU$_REQUIRESDECW | ERROR | This built-in is valid on DECwindows only.
TPU$_TOOFEW | ERROR | This SET built-in requires two parameters.
TPU$_TOOMANY | ERROR | You specified more than two parameters.
TPU$_INVPARAM | ERROR | The second parameter is not of type string.

### 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")

## SET (FORWARD)

### 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

TPU$_TOOFEW | ERROR | SET (FORWARD) requires 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$_BADKEY | ERROR | You specified an invalid keyword.

### Example

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

    SET (FORWARD, my_buffer)

## SET (GLOBAL_SELECT)

### 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

Returns 1 if the global selection ownership request was granted; otherwise, returns 0.

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

#1
    SET (GLOBAL_SELECT, SCREEN, PRIMARY);

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

#2
    SET (GLOBAL_SELECT, SCREEN, PRIMARY, GLOBAL_SELECT_UNGRAB);

## SET (GLOBAL_SELECT_GRAB)

### 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");

## SET (GLOBAL_SELECT_READ)

### 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");

## SET (GLOBAL_SELECT_TIME)

### 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);

## SET (GLOBAL_SELECT_UNGRAB)

### 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");

## SET (HEIGHT)

### 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);

## SET (ICON_NAME)

### 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");

Previous | Next | Contents | Index

| privacy and legal statement |
6020PRO_027.HTML