DEC Text Processing Utility Reference Manual

Updated: 11 December 1998

DEC Text Processing Utility Reference Manual

Contents

Index

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.

#2

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;

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

ASCII

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 character with the specified ASCII value (if you specify an integer or keyword parameter).

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

TPU$_NEEDTOASSIGN	ERROR	ASCII must be on the right-hand side of an assignment statement.
TPU$_TOOFEW	ERROR	ASCII requires one argument.
TPU$_TOOMANY	ERROR	ASCII accepts only one argument.
TPU$_ARGMISMATCH	ERROR	The parameter you passed to ASCII is of the wrong type.
TPU$_NULLSTRING	WARNING	You passed a string of length 0 to ASCII.

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.

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

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

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

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;

ATTACH

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

TPU$_NOPARENT	WARNING	There is no parent process to which you can attach. Your current process is the top-level process.
TPU$_TOOMANY	ERROR	Too many arguments passed to the ATTACH built-in.
TPU$_SYSERROR	ERROR	Error requesting information about the process being attached to.
TPU$_ARGMISMATCH	ERROR	Wrong type of data sent to the ATTACH built-in. Only process name strings and process IDs are allowed.
TPU$_CREATEFAIL	WARNING	Unable to attach to the process.
TPU$_REQUIRESTERM	ERROR	Feature requires a terminal.

Examples

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

#1
ATTACH (97899)

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

#2
ATTACH ("JONES_2")

BEGINNING_OF

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

A marker that points to the first character position of the specified buffer or range.

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

TPU$_NEEDTOASSIGN	ERROR	BEGINNING_OF must appear on the right-hand side of an assignment statement.
TPU$_TOOFEW	ERROR	BEGINNING_OF requires one argument.
TPU$_TOOMANY	ERROR	BEGINNING_OF accepts only one argument.
TPU$_ARGMISMATCH	ERROR	You passed something other than a range or a buffer to BEGINNING_OF.

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.

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

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

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;

BREAK

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

BREAK is a language element and has no completion codes.

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;

CALL_USER

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

The value returned by the called program.

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

TPU$_REQUIRESVMS	ERROR	Feature not available on this operating system.
TPU$_BADUSERDESC	ERROR	User-written routine incorrectly filled in the return descriptor.
TPU$_NOCALLUSER	ERROR	Could not find a routine to invoke.
TPU$_TOOFEW	ERROR	Too few arguments passed to CALL_USER.
TPU$_TOOMANY	ERROR	Too many arguments passed to CALL_USER.
TPU$_NEEDTOASSIGN	ERROR	The call to CALL_USER must be on the right-hand side of the assignment statement.
TPU$_INVPARAM	ERROR	Wrong type of data sent to CALL_USER.
TPU$_ARGMISMATCH	ERROR	Parameter is of the wrong data type.
TPU$_CALLUSERFAIL	WARNING	CALL_USER routine failed with status %X'status'. The value returned by ERROR after this type of error will be the status value reported by this message.

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.

#1
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 
UNIVERSAL=TPU$CALLUSER 




  
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.

CHANGE_CASE

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

TPU$_TOOFEW	ERROR	CHANGE_CASE requires two parameters.
TPU$_TOOMANY	ERROR	CHANGE_CASE accepts only two parameters.
TPU$_ARGMISMATCH	ERROR	One of the parameters to CHANGE_CASE is of the wrong data type.
TPU$_INVPARAM	ERROR	One of the parameters to CHANGE_CASE is of the wrong data type.
TPU$_BADKEY	WARNING	You gave the wrong keyword to CHANGE_CASE.
TPU$_NOTMODIFIABLE	WARNING	You cannot change the case of text in an unmodifiable buffer.
TPU$_CONTROLC	ERROR	You pressed Ctrl/C during the execution of CHANGE_CASE.

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.

#1
CHANGE_CASE (CURRENT_BUFFER, UPPER)

The following example puts the current text object in uppercase:

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

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.

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

COMPILE

Format

program :=
COMPILE (

buffer
range
string
)

Parameters

buffer
A buffer that contains only valid DECTPU declarations and statements.
range
A range that contains only valid DECTPU declarations and statements.
string
A string that contains only valid DECTPU declarations and statements.

Return Value

The program created by compiling the declarations and statements in the string, range, or buffer. If the program fails to compile, an integer zero is returned.

Description

The COMPILE procedure converts DECTPU procedures and statements into an internal, compiled format. Valid items for compilation can be represented by a string, a range, or a buffer. COMPILE optionally returns a program.

Previous Next Contents Index

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

6020PRO_002.HTML

DEC Text Processing Utility Reference Manual

ASCII

Format

integer2 string2:= ASCII ( integer1 keyword string1)

Parameters

integer1

keyword

string1

Return Value

Description

Signaled Errors

Examples

ATTACH

Format

ATTACH [[ ( integer string) ]]

Parameters

integer

string

Description

Signaled Errors

Examples

BEGINNING_OF

Format

marker := BEGINNING_OF ( buffer range)

Parameters

buffer

range

Return Value

Description

Signaled Errors

Examples

BREAK

Format

BREAK

Parameters

Description

Signaled Errors

Example

CALL_USER

Format

string2 := CALL_USER (integer, string1)

Parameters

integer

string1

Return Value

Description

Signaled Errors

Examples

CHANGE_CASE

Format

returned_buffer returned_range returned_string:= CHANGE_CASE ( buffer range string, INVERT LOWER UPPER , IN_PLACE, NOT_IN_PLACE)

Parameters

buffer

range

string

INVERT

LOWER

UPPER

IN_PLACE

NOT_IN_PLACE

Return Values

returned_buffer

returned_range

returned_string

Description

Signaled Errors

Examples

COMPILE

Format

program := COMPILE ( buffer range string)

Parameters

buffer

range

string

Return Value

Description

integer2
string2
:= ASCII (

integer1
keyword
string1
)

ATTACH [[ (

integer
string
) ]]

marker := BEGINNING_OF (

buffer
range
)

returned_buffer
returned_range
returned_string
:= CHANGE_CASE (

buffer
range
string
,

INVERT
LOWER
UPPER

, IN_PLACE
, NOT_IN_PLACE
)

program :=
COMPILE (

buffer
range
string
)