Document revision date: 30 March 2001

Examples

The following example creates a pattern that matches the next five characters starting at the editing point. The characters themselves are arbitrary; it is the number of characters that is important for a pattern created with ARB.

pat1 := ARB (5) 
 
      

The following example replaces a prefix of any three characters followed by an underscore (xxx_) in the current buffer with the string "user_". It does not change the current position.

PROCEDURE user_replace_prefix 
   LOCAL  cur_mode, 
          here, 
          pat1, 
         found_range; 
 
   pat1 := (LINE_BEGIN | NOTANY ("ABCDEFGHIJKLMNOPQRSTUVWXYZ_$")) 
           + ((ARB (3) + "_") @ found_range); 
   here := MARK (NONE); 
   cur_mode := GET_INFO (current_buffer, "mode"); 
 
   POSITION (BEGINNING_OF (CURRENT_BUFFER)); 
   LOOP 
      found_range := 0; 
      SEARCH_QUIETLY (pat1, FORWARD); 
      EXITIF found_range = 0; 
      ERASE (found_range); 
      POSITION (END_OF (found_range)); 
      COPY_TEXT ("user_"); 
  ENDLOOP; 
  POSITION (here); 
  SET (cur_mode, current_buffer); 
ENDPROCEDURE; 
      

Format

{integer2|string2}:= ASCII ({integer1|keyword|string1})

Parameters

integer1

The decimal value of a character in the DEC Multinational Character Set.

keyword

Must be a key name. If the key name is the name of a key that produces a printing character, ASCII returns that character; otherwise it returns the character whose ASCII value is 0.

string1

The character whose ASCII value you want. If the string has a length greater than 1, the ASCII built-in returns the ASCII value of the first character in the string.

Return Value

The ASCII value of the string you specify (if you specify a string parameter).

Description

The ASCII procedure returns the ASCII value of a character or the character that has the specified ASCII value. The result of ASCII depends upon its argument. If the argument is an integer, ASCII returns a string of length 1 that represents the character of the DEC Multinational Character Set corresponding to the integer you specify. If the argument is a string, ASCII takes the first character of the string and returns the integer corresponding to the ASCII value of that character.

If the argument to ASCII is a keyword, that keyword must be a key name. The KEY_NAME built-in produces key names. In addition, there are several predefined keywords that are key names. See the Guide to the DEC Text Processing Utility for a list of these keywords.

If the keyword is a key name and the key produces a printing character, ASCII returns that character; otherwise, it returns the character whose ASCII value is 0.

Signaled Errors

Examples

The following example assigns a string of length 1 to the variable my_character. This string contains the form-feed character because that character has the ASCII value 12.

my_character := ASCII(12) 
 
      

The following example assigns the integer value 97 to the variable ascii_value. The a is specified in quotation marks because it is a parameter of type string.

ascii_value := ASCII ("a"); 
 
 
      

The following example prompts you to press a key. When you do so, the procedure reads the key. If the key is associated with a printing character, ASCII tells you what character is produced. If the key is not associated with a printable character, ASCII informs you of this.

PROCEDURE user_test_key 
   LOCAL key_struck, 
         key_value; 
 
   MESSAGE ("Press a key"); 
   key_struck := READ_KEY; 
   key_value := ASCII (key_struck); 
 
   IF key_value = ASCII (0) 
   THEN 
      MESSAGE ("That is not a typing key"); 
   ELSE 
      MESSAGE (FAO ("That key produces the letter "!AS".", key_value)); 
   ENDIF; 
ENDPROCEDURE; 
      

Format

ATTACH [[ ({integer|string}) ]]

Parameters

integer

An integer that DECTPU interprets as the process identification (PID) of the process to which terminal control is to be switched. You must use decimal numbers to specify the PID to DECTPU.

string

A string that DECTPU interprets as the name of the process to which terminal control is to be switched.

Description

The ATTACH procedure enables you to switch control from your current process to another OpenVMS process that you previously created.

To use ATTACH you must have previously created a subprocess. If the process you specify is not part of the current job or does not exist, an error message is displayed. For information on creating subprocesses, see the description of SPAWN.

ATTACH suspends the current DECTPU process and switches context to the process you use as a parameter. If you do not specify a parameter for ATTACH, DECTPU switches control to the parent or owner process. A subsequent use of the DCL ATTACH command (or a logout from any process except the parent process) resumes the execution of the suspended DECTPU process.

In all cases, DECTPU first deassigns the terminal. If a DECTPU process is resumed following a SPAWN or ATTACH command, DECTPU reassigns the terminal and refreshes the screen.

If the current buffer is mapped to a visible window, the ATTACH built-in causes the screen manager to synchronize the editing point (which is a buffer location) with the cursor position (which is a window location). This may result in the insertion of padding spaces or lines into the buffer if the cursor position is before the beginning of a line, in the middle of a tab, beyond the end of a line, or after the last line in the file.

ATTACH is not a valid built-in in DECwindows DECTPU. However, if you are running non DECwindows DECTPU in a DECwindows terminal emulator, ATTACH works as described.

Signaled Errors

Examples

The following example causes DECTPU to attach to the OpenVMS subprocess with the PID 97899:

ATTACH (97899) 
 
      

The following example switches the terminal's control to the OpenVMS process JONES_2:

ATTACH ("JONES_2") 
      

Format

marker := BEGINNING_OF ({buffer|range})

Parameters

buffer

The buffer whose beginning you want to mark.

range

The range whose beginning you want to mark.

Return Value

Description

The BEGINNING_OF procedure returns a marker that points to the first position of a buffer or a range. If you use the marker returned by BEGINNING_OF as a parameter for the POSITION built-in procedure, the editing point moves to the marker.

Signaled Errors

Examples

The following example uses two built-in procedures to move your current character position to the beginning of my_range. If my_range is in a visible buffer in which the cursor is located, the cursor position is also moved to the beginning of my_range.

POSITION (BEGINNING_OF (my_range)) 
 

 
 
      

The following example creates a new buffer, associates the buffer with the main window, and maps the main window to the screen. It positions to the top of the buffer, prompts you for the name of a file to include, and reads the file into the buffer.

PROCEDURE user_include_file 
! Create scratch buffer 
   b1 := CREATE_BUFFER ("Scratch Buffer"); 
 
! Map scratch buffer to main window 
   MAP (main_window, b1); 
 
! Read in file name given 
   READ_FILE (READ_LINE ("File to Include:" )); 
 
! Go to top of file 
   POSITION (BEGINNING_OF (b1)); 
ENDPROCEDURE; 
      

Format

BREAK

Parameters

None.

Description

The BREAK procedure activates the debugger if DECTPU was invoked with the /DEBUG qualifier. If there is no debugger, BREAK causes the following message to be displayed in the message window:

Breakpoint at line xxx

It has no other effect. Although BREAK behaves much like a built-in, it is actually a DECTPU language element.

BREAK is evaluated for correct syntax at compile time. In contrast, DECTPU procedures are usually evaluated for a correct parameter count and parameter types at execution time.

Signaled Errors

Example

The following example contains a break statement. If the statement is executed, DECTPU's debugger is activated, enabling you to debug that section of the code.

PROCEDURE user_not_quite_working 
     . 
     . 
     . 
   BREAK; 
     . 
     . 
     . 
ENDPROCEDURE; 
      

Format

string2 := CALL_USER (integer, string1)

Parameters

integer

The integer that is passed to the user-written program.

string1

The string that is passed to the user-written program.

Return Value

Description

The CALL_USER procedure calls a program written in another language from within DECTPU. The CALL_USER parameters are passed to the external routine exactly as you enter them; DECTPU does not process the parameters in any way. The integer is passed by reference, and string1 is passed by descriptor. String2 is the value returned by the external program.

In addition to returning the value string2 to CALL_USER, the external program returns a status code that tells whether the program executed successfully. You can trap this status code in an ON_ERROR statement. An even-numbered status code (low bit in R0 clear) causes the ON_ERROR statement to be executed. The ERROR lexical element returns the status value from the program in the form of a keyword.

The CALL_USER parameters are input parameters for the external program you are calling. DECTPU does not process the parameters in any way but passes them to the external procedure exactly as you enter them. You must supply both parameters even if the routine you are calling does not require that information be passed to it. Enter the following null parameters to indicate that you are not passing any actual values:

CALL_USER (0,"")

For information on the DECTPU callable interface, see the OpenVMS Utility Routines Manual.

Signaled Errors

Examples

The following example calls a program that you wrote. Before invoking DECTPU, you created a logical name, TPU$CALLUSER, that points to the file containing the program you want called by CALL_USER. DECTPU passes the first parameter (6) by reference, and the second parameter ("ABC") by descriptor. If, for example, you use an integer and a string as input values, the program processes the integer 6 and the string "ABC". If the program is designed to return a result, the result is returned in the variable ret_value.

ret_value := CALL_USER (6, "ABC") 
 
      

The following example shows the steps required to use the CALL_USER built-in procedure. The routine that is called to do floating-point arithmetic is written in BASIC.

Step-by-Step Example of Using CALL_USER 
   
  


  
Write a program in BASIC that does floating-point arithmetic on the 
values passed to it: 
 
 



  

    

      

      
 
  
 
  
! Filename:FLOATARITH.BAS 
 
1       sub TPU$CALLUSER ( some_integer% , input_string$ , return_string$ ) 
 
10      ! don't check some_integer% because this function only does 
        ! floating-point arithmetic 
 
20      ! parse the input string 
        ! find and extract the operation 
        comma_location = pos ( input_string$, ",", 1% ) 
        if comma_location = 0 then go to all_done 
        end if 
 
        operation$ = seg$( input_string$, 1%, comma_location - 1% ) 
 
        ! find and extract the 1st operand 
        operand1_location = pos ( input_string$, ",", comma_location +1 ) 
        if operand1_location = 0 then go to all_done 
        end if 
 
        operand1$ = seg$( input_string$, comma_location + 1% ,  & 
                          operand1_location -1 ) 
 
        ! find and extract the 2nd operand 
        operand2_location = pos ( input_string$, ",", operand1_location +1 ) 
        if operand2_location = 0 then 
                operand2_location = len( input_string$) + 1 
        end if 
 
        operand2$ = seg$( input_string$, operand1_location + 1% ,  & 
                          operand2_location -1 ) 
 
        select operation$ ! do the operation 
        case "+" 
                result$ = sum$(  operand1$ , operand2$ )  ! 
 
        case "-" 
                result$ =  dif$(  operand1$, operand2$ )  ! 
 
        case "*" 
                result$ =  num1$( Val( operand1$ ) * Val( operand2$ ) ) 
 
        case "/" 
                result$ =  num1$( Val( operand1$ ) / Val( operand2$ ) ) 
 
        case else 
                result$ =  "unknown operation." 
        end select 
 
        return_string$ = result$ 
 
999     all_done: end sub 




  
Compile the program with the following statement:



  

    

      

      
$ BASIC/LIST floatarith




  
Create an options file to be used by the linker when you link the 
  BASIC program.



  

    

      

      
!+ 
!   File: FLOATARITH.OPT 
! 
!   Options file to link floatarith BASIC program with DECTPU 
! 
!- 
floatarith.obj 
! 
!   For OpenVMS VAX, use the following link option: 
! 
UNIVERSAL=TPU$CALLUSER 
! 
!   For OpenVMS Alpha, use the following link option: 
! 
SYMBOL_VECTOR=(TPU$CALLUSER=PROCEDURE) 
! 




  
Link the program (using the options file) to create a shareable 
  image.



  

    

      

      
$ LINK floatarith/SHARE/OPT/MAP/FULL




  
Define the logical name TPU$CALLUSER to point to the executable 
  image of the BASIC program.



  

    

      

      
$ DEFINE TPU$CALLUSER device:[directory]floatarith.EXE




  
Invoke DECTPU.
  
Write and compile the following DECTPU procedure:



  

    

      

      
PROCEDURE my_call_user 
 
! test the built-in procedure call_user 
 
   LOCAL output, 
         input; 
 
   input := READ_LINE ("Call user >");  ! Provide a parameter for routine 
   output := CALL_USER ( 0, input);     ! Value this routine returns 
   MESSAGE (output); 
ENDPROCEDURE; 




  
When you call the procedure my_call_user, you are prompted 
  for parameters to pass to the BASIC routine. The order of the 
  parameters is operator, number, number. For example, if you enter +, 
  3.33, 4.44 after the prompt, the result 7.77 is displayed in the 
  message area.


      

Format

{returned_buffer|returned_range|returned_string} := CHANGE_CASE ({buffer|range|string}, {INVERT|LOWER|UPPER} [[, IN_PLACE|, NOT_IN_PLACE]])

Parameters

buffer

The buffer in which you want DECTPU to change the case. You cannot use the NOT_IN_PLACE keyword if you specify a buffer for the first parameter.

range

The range in which you want DECTPU to change the case. You cannot use the NOT_IN_PLACE keyword if you specify a range for the first parameter.

string

The string in which you want DECTPU to change the case. If you specify IN_PLACE for the third parameter, CHANGE_CASE makes the specified change to the string specified in the first parameter. If string is a constant, IN_PLACE has no effect.

INVERT

A keyword that directs DECTPU to change uppercase letters to lowercase and lowercase letters to uppercase.

LOWER

A keyword that directs DECTPU to change letters to all lowercase.

UPPER

A keyword that directs DECTPU to change letters to all uppercase.

IN_PLACE

A keyword that directs DECTPU to make the indicated change in the buffer, range, or string specified. This is the default.

NOT_IN_PLACE

A keyword that directs DECTPU to leave the specified string unchanged and return a string that is the result of the specified change in case. You cannot use NOT_IN_PLACE if the first parameter is specified as a range or buffer. To use NOT_IN_PLACE, you must specify a return value for CHANGE_CASE.

Return Values

returned_buffer

A variable of type buffer that points to the buffer containing the modified text, if you specify a buffer for the first parameter. The variable returned_buffer points to the same buffer pointed to by the buffer variable specified as the first parameter.

returned_range

A range that contains the modified text, if you specify a range for the first parameter. The returned range spans the same text as the range specified as a parameter, but they are two separate ranges. If you subsequently change or delete one of the ranges, this has no effect on the other range.

returned_string

A string that contains the modified text, if you specify a string for the first parameter. CHANGE_CASE can return a string even if you specify IN_PLACE.

Description

The CHANGE_CASE procedure changes the case of all alphabetic characters in a buffer, range, or string, according to the keyword that you specify. Optionally, CHANGE_CASE returns a string, range, or buffer containing the changed text.

Signaled Errors

Examples

The following example makes all the characters in the current buffer uppercase. If you enter this statement on the command line of your interface, you see the effects immediately. If you use this statement within a procedure, you see the effect of the statement at the next screen update.

CHANGE_CASE (CURRENT_BUFFER, UPPER) 
 
      

The following example puts the current text object in uppercase:

PROCEDURE user_upcase_item 
   ON_ERROR 
   ! In case no string is found during search 
      MESSAGE ("No current item."); 
      RETURN; 
   ENDON_ERROR; 
 
   delimiters   := " " + ASCII(9); 
   current_item := ANCHOR & SCAN (delimiters); 
   item_range   := SEARCH (current_item, FORWARD, NO_EXACT); 
   CHANGE_CASE (item_range, UPPER); 
ENDPROCEDURE; 
 
      

The following example inverts the case of all characters in the string pointed to by the_string and returns the modified string in the variable returned_value. It does not change the_string in any way.

returned_value := CHANGE_CASE (the_string, INVERT, NOT_IN_PLACE); 
      

---

Previous

Next

Contents

Index

	privacy and legal statement
6020PRO_002.HTML