Document revision date: 19 July 1999
[Compaq] [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]
[OpenVMS documentation]

DEC Text Processing Utility Reference Manual


Previous Contents Index


GET_DEFAULT


Format

{string3|integer} := GET_DEFAULT (string1, string2 )


Parameters

string1

The name of the resource whose value you want GET_DEFAULT to fetch. Resource names are case sensitive.

string2

The class of the resource. Resource class names are case sensitive.

Return Value


The string equivalent of the resource value or 0 if the specified resource is not defined. If necessary, the application must convert the string to the data type appropriate to the resource.

Description

The GET_DEFAULT procedure returns the value of an X resource from the X resources database. GET_DEFAULT is useful for initializing a layered application that uses an X defaults file. You can use GET_DEFAULT only in the DECwindows environment.

If you use the SET (DEFAULT_FILE) built-in to merge a new X resource database into the display's database, this affects the values returned by GET_DEFAULT.

Signaled Errors

TPU$_INVPARAM ERROR One of the parameters was specified with data of the wrong type.
TPU$_TOOFEW ERROR Too few arguments passed to GET_DEFAULT.
TPU$_TOOMANY ERROR Too many arguments passed to GET_DEFAULT.
TPU$_NEEDTOASSIGN ERROR GET_DEFAULT must return a value.
TPU$_REQUIRESDECW ERROR You can use GET_DEFAULT only if you are using DECwindows DECTPU.

Example

The following example shows the portion of a module_init procedure directing DECTPU to fetch the value of a resource from the X resources database. For more information on module_init procedures, see the Extensible Versatile Editor Reference Manual.

If you want to create an extension of EVE that enables use of an X defaults file to choose a keypad setting, you can use a GET_DEFAULT statement in a module_init procedure.


PROCEDURE application_module_init 
 
LOCAL 
    keypad_name; 
 
    : 
    : 
    : 
 
keypad_name := GET_DEFAULT ("user.keypad", "User.Keypad"); 
 
EDIT (keypad_name, UPPER); ! Convert the returned string to uppercase. 
 
IF keypad_name <> '0' 
THEN 
 
   CASE keypad_name 
 
      "EDT"      :  eve_set_keypad_edt (); 
      "NOEDT"    :  eve_set_keypad_noedt (); 
      "WPS"      :  eve_set_keypad_wps (); 
      "NOWPS"    :  eve_set_keypad_nowps (); 
      "NUMERIC"  :  eve_set_keypad_numeric (); 
      "VT100"    :  eve_set_keypad_vt100 (); 
      [INRANGE, OUTRANGE]  :  eve_set_keypad_numeric; ! If you have 
                                                      ! used invalid value, 
                                                      ! set the keypad to 
                                                      ! NUMERIC setting. 
 
   ENDCASE; 
 
ENDIF; 
 
    : 
    : 
    : 
 
ENDPROCEDURE; 
      

To provide a value for the GET_DEFAULT statement to fetch, an X defaults file would contain an entry similar to the following:


User.Keypad : EDT 
      


GET_GLOBAL_SELECT


Format

{array|integer|string|unspecified}:= GET_GLOBAL_SELECT ({PRIMARY|SECONDARY|selection_name} , selection_property_name)


Parameters

PRIMARY

A keyword indicating that the layered application is requesting information about a property of the primary global selection.

SECONDARY

A keyword indicating that the layered application is requesting information about a property of the secondary global selection.

selection_name

A string identifying the global selection whose property is the subject of the layered application's information request. Specify the selection name as a string if the layered application needs information about a selection other than the primary or secondary global selection.

selection_property_name

A string specifying the property whose value the layered application is requesting.

Return Values


array

An array that passes information about a global selection whose contents describe information that is not of a data type supported by DECTPU.

DECTPU does not use or alter the information in the array; the application layered on DECTPU is responsible for determining how the information is used, if at all. Because the array is used to receive information from other DECwindows applications, all applications that exchange information whose data type is not supported by DECTPU must adopt a convention on how the information is to be used.

The element array {0} contains a string that names the data type of the information being passed. For example, if the information being passed is a span, the element contains the string "SPAN". The element array {1} contains either the integer 8, indicating that the information is passed as a series of bytes, or the integer 32, indicating that the information is passed as a series of longwords. If array {1} contains the value 8, the element array {2} contains a string and there are no array elements after array {2}. The string does not name anything, but rather is a series of bytes of information. As mentioned, the meaning and use of the information is agreed upon by convention among the DECwindows applications. To interpret this string, the application can use the SUBSTR built-in procedure to obtain substrings one at a time, and the ASCII built-in procedure to convert the data to integer format if necessary. For more information about using these DECTPU elements, see the description of the SUBSTR and ASCII built-in procedures.

If array {1} contains the value 32, the element array {2} and any subsequent elements contain integers. The number of integers in the array is determined by the application that responded to the request for information about the global selection. The interpretation of the data is a convention that must be agreed upon by the cooperating application. To determine how many longwords are being passed, an application can determine the length of the array and subtract 2 to allow for elements array {0} and array {1}.)

integer

The value of the specified global selection property. The return value is of type integer if the value of the specified global selection property is of type integer.

string

The value of the specified global selection property. The return value is of type string if the value of the specified global selection property is of type string.

unspecified

A data type that indicates that the information requested by the layered application was not available.

Description

The GET_GLOBAL_SELECT procedure supplies information about a global selection. If an owner for the global selection exists, and if the owner provides the information requested in a format that DECTPU can recognize, GET_GLOBAL_SELECT returns the information.

Signaled Errors

TPU$_ARGMISMATCH ERROR Wrong type of data sent to GLOBAL_SELECT.
TPU$_NEEDTOASSIGN ERROR GLOBAL_SELECT must return a value.
TPU$_INVPARAM ERROR One of the parameters was specified with data of the wrong type.
TPU$_REQUIRESDECW ERROR You can use GLOBAL_SELECT only if you are using DECwindows DECTPU.
TPU$_TOOFEW ERROR Too few arguments passed to GLOBAL_SELECT.
TPU$_TOOMANY ERROR Too many arguments passed to GLOBAL_SELECT.
TPU$_GBLSELOWNER WARNING DECTPU owns the global selection.
TPU$_BADKEY WARNING You specified an invalid keyword as a parameter.
TPU$_INVGBLSELDATA WARNING The global selection owner provided data that DECTPU cannot process.
TPU$_NOGBLSELDATA WARNING The global selection owner indicated that it cannot provide the information requested.
TPU$_NOGBLSELOWNER WARNING You requested information about an unowned global selection.
TPU$_TIMEOUT WARNING The global selection owner did not respond before the timeout period expired.

Example

The following example fetches the text in the primary global selection and assigns it to the variable string_to_paste:

string_to_paste := GET_GLOBAL_SELECT (PRIMARY, "STRING"); 
      

For another example of how to use the GET_GLOBAL_SELECT built-in procedure, see Example A-3.


GET_INFO


Description

The GET_INFO procedure returns information about the current status of the editor.

For information on how to get a screen display of the status of your editor, see the description of the SHOW built-in procedure.

This description provides general information on the GET_INFO built-in procedures. Included are descriptions of individual GET_INFO built-ins. The individual GET_INFO built-ins are grouped according to the value of their first parameter. For a list of the groups of GET_INFO built-ins, see Table 2-3.

All GET_INFO built-in procedures have the following two characteristics in common:

Each GET_INFO built-in procedure in this section shows the possible return values for a given combination of the first and second parameters. For example, the GET_INFO (any_variable) built-in shows that when you use any variable as the first parameter and the string "type" as the second parameter, GET_INFO returns a keyword for the data type of the variable.

Depending upon the kind of information requested, GET_INFO returns any one of the following:

DECTPU maintains internal lists of the following items:

You can step through an internally maintained list by using "first", "next", "previous", or "last" as the second parameter to GET_INFO. The order in which DECTPU maintains these lists is private and may change in a future version. Do not write code that depends on a list being maintained in a particular order. When you write code to search a list, remember that DECTPU keeps only one pointer for each list. If you create nested loops that attempt to search the same list, the results are unpredictable.

For example, suppose that a program intended to search two key map lists for common key maps sets up a loop within a loop. The outer loop might contain the following statement:


GET_INFO (KEY_MAP, "previous", name_of_second_key_map) 

The inner loop might contain the following statement:


GET_INFO (KEY_MAP, "next", name_of_first_key_map) 

In DECTPU, the behavior of such a nested loop is unpredictable.

Unless documented otherwise, the order of the internal list is not defined.

The syntax of GET_INFO depends on the kind of information you are trying to get. For more information on specific GET_INFO built-in procedures, see the descriptions in this section. GET_INFO built-ins whose first parameter is a keyword are grouped separately from GET_INFO built-ins whose first parameter is a variable.

Table 2-3 GET_INFO Built-In Procedures by First Parameter
Variable Keyword Any Keyword or Key Name
GET_INFO (any_variable) GET_INFO (ARRAY) GET_INFO (any_keyname)
GET_INFO (array_variable) GET_INFO (BUFFER) GET_INFO (any_keyword)
GET_INFO (buffer_variable) GET_INFO (COMMAND_LINE)  
GET_INFO (integer_variable) GET_INFO (DEBUG)  
GET_INFO (marker_variable) GET_INFO (DEFINED_KEY)  
GET_INFO (process_variable) GET_INFO (KEY_MAP)  
GET_INFO (range_variable) GET_INFO (KEY_MAP_LIST)  
GET_INFO (string_variable) GET_INFO (mouse_event_keyword)  
GET_INFO (widget_variable) GET_INFO (PROCEDURES)  
GET_INFO (window_variable) GET_INFO (PROCESS)  
  GET_INFO (SCREEN)  
  GET_INFO (SYSTEM)  
  GET_INFO (WIDGET)  
  GET_INFO (WINDOW)  

Signaled Errors

TPU$_BADREQUEST WARNING Request represented by second argument is not understood for data type of first argument.
TPU$_BADKEY WARNING Bad keyword value or unrecognized data type is passed as the first argument.
TPU$_NOCURRENTBUF WARNING Current buffer is not defined.
TPU$_NOKEYMAP WARNING Key map is not defined.
TPU$_NOKEYMAPLIST WARNING Key map list is not defined.
TPU$_INVPARAM ERROR One or more of the specified parameters have the wrong data type.
TPU$_NEEDTOASSIGN ERROR The GET_INFO built-in can be used only on the right-hand side of an assignment statement.
TPU$_NOBREAKPOINT WARNING This string constant is valid only after a breakpoint.
TPU$_NONAMES WARNING There are no names matching the one requested.
TPU$_TOOFEW ERROR Too few arguments passed to the GET_INFO built-in.
TPU$_TOOMANY ERROR Too many arguments passed to the GET_INFO built-in.
TPU$_UNKKEYWORD ERROR An unknown keyword was used as an argument.

Examples

The following example stores the pointer to the current buffer in the variable my_buffer:
#1

my_buffer := GET_INFO (BUFFERS, "current"); 
 
      

The following example stores the integer 1 or 0 in the variable is_buf_mod. A value of 1 means the current buffer has been modified. A value of 0 means the current buffer has not been modified.

#2

is_buf_mod := GET_INFO (CURRENT_BUFFER, "modified"); 
 
      

The following example uses GET_INFO to find the top of the current window. It then removes the top five lines and replaces them with an example window.

#3

PROCEDURE user_getinfo 
 
   top_of_window := GET_INFO (CURRENT_WINDOW, "top", visible_window); 
 
       ! Remove the top five lines from the main window 
   ADJUST_WINDOW (CURRENT_WINDOW, +5, 0); 
 
       ! Replace removed lines with an example window 
   example_window := CREATE_WINDOW (top_of_window, 5, ON); 
   example_buffer := CREATE_BUFFER ("EXAMPLE", 
                                    "sys$login:template.txt"); 
   MAP (example_window, example_buffer); 
ENDPROCEDURE; 
 

The following example shows whether the key map list associated with the current buffer inserts undefined printable characters:

#4

PROCEDURE show_self_insert 
      
   LOCAL key_map_list_name; 
 
   key_map_list_name := GET_INFO (CURRENT_BUFFER, "key_map_list"); 
 
   IF GET_INFO (key_map_list_name, "self_insert") 
   THEN 
      MESSAGE ("Undefined printable characters will be inserted"); 
   ELSE 
      MESSAGE ("Undefined printable characters will cause an error"); 
   ENDIF; 
ENDPROCEDURE; 
      


GET_INFO (any_keyname)


Format

{integer|keyword} := GET_INFO (any_keyname, {"key_modifiers"|"key_type"| "unmodified"})


Parameters

"key_modifiers"

Returns a bit-encoded integer that indicates what key modifier or modifiers were used to create the DECTPU key name specified by the parameter any_keyname. For more information about the meaning and possible values of key modifiers, see the description of the KEY_NAME built-in procedure.

DECTPU defines four constants to be used when referring to or testing the numerical value of key modifiers. The correspondence between key modifiers, defined constants, and bit-encoded integers is as follows:
Key Modifier Constant Bit-Encoded Integer
SHIFT_MODIFIED TPU$K_SHIFT_MODIFIED 1
CTRL_MODIFIED TPU$K_CTRL_MODIFIED 2
HELP_MODIFIED TPU$K_HELP_MODIFIED 4
ALT_MODIFIED TPU$K_ALT_MODIFIED 8

You may have used the SHIFT_KEY keyword to create a DECTPU key name. SHIFT_KEY is not a modifier; it is a prefix. The Shift key is also called the GOLD key by the EVE editor. To use the Shift key, press and release it before you press any other key.

In DECwindows, to use modifying keys (such as Ctrl), press and hold the modifying key while you press the modified key.

If you use more than one key modifier with the KEY_NAME built-in procedure, the value of the returned integer is the sum of the integer representations of the key modifiers. For example, if you create a key name by using the modifiers HELP_MODIFIED and ALT_MODIFIED, the GET_INFO (any_keyname, "key_modifiers") built-in returns the integer 12.

"key_type"

Returns a keyword that describes the type of key named by any_keyname. The keywords that can be returned are PRINTING, KEYPAD, FUNCTION, CONTROL, SHIFT_PRINTING, SHIFT_KEYPAD, SHIFT_FUNCTION, and SHIFT_CONTROL. Returns 0 if parameter1 is not a valid key name. There are cases in which GET_INFO (any_keyname, "name") returns the PRINTING keyword but the key described by the key name is not associated with a printable character. For example, if you use the KEY_NAME built-in to define a key name as the combination of the character A and the ALT modifier, and if you then use GET_INFO (any_keyname, "name") to find out how DECTPU classifies the key, the GET_INFO built-in returns the PRINTING keyword. However, if you use the ASCII built-in to obtain the string representation of the key, the ASCII built-in returns a null string because ALT/A is not printable.

"unmodified"

Returns a keyword that describes the key name specified by any_keyname without any modifiers. For example, if you create a key name for the F20 key with the ALT_MODIFIED modifier, the GET_INFO (any_keyname, "unmodified") built-in returns the F20 keyword.

Return Values


integer

Returns requested information about the integer you specify.

keyword

Returns requested information about the keyword you specify.


Description

The GET_INFO (any_keyname) procedure returns a keyword that describes the type of key named by any_keyname.

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


Example

In the following example, the first statement creates a DECTPU key name for the key sequence produced by pressing the Ctrl key, the Shift key, and the 4 key on the keypad all at once. The new key name is assigned to the variable new_key. The second statement fetches the integer equivalent of this combination of key modifiers. The third statement displays the integer 3 in the message buffer. The IF clause of the fourth statement shows how to test whether a key name was created using a modifier. (This statement does not detect whether a key name was created using the SHIFT_KEY keyword.) The THEN clause shows how to fetch the key modifier keyword or keywords used to create a key name. The final statement displays the string KEY_NAME (KP4, SHIFT_MODIFIED, CTRL_MODIFIED) in the message buffer.

new_key := KEY_NAME (KP4, SHIFT_MODIFIED, CTRL_MODIFIED); 
modifier_value := GET_INFO (new_key, "key_modifiers"); 
MESSAGE (STR (modifier_value)); 
IF GET_INFO (new_key, "key_modifiers") 
THEN 
    the_name := GET_INFO (new_key, "name") 
    MESSAGE (STR (the_name)); 
ENDIF; 
 
      


Previous Next Contents Index

  [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]  
  privacy and legal statement  
6020PRO_010.HTML