Document revision date: 19 July 1999

The program that COMPILE optionally returns is the compiled form of valid DECTPU procedures, statements, or both. You can assign the compiled version of DECTPU code to a variable name. DECTPU statements, as well as procedure definitions, can be stored by DECTPU in the program returned by COMPILE. Later in your editing session, you can execute the DECTPU code that you compiled by using the program as a parameter for the EXECUTE built-in procedure. You can also use the program as a parameter for the DEFINE_KEY built-in procedure to define a key to execute the program. Then you can execute the program by pressing that key.

COMPILE returns a program variable only if the compilation generates executable statements. COMPILE does not return a program variable if you compile any of the following:

• Null strings or buffers
• Procedure definitions that do not have any executable statements following them
• Programs with syntax errors

DECTPU cannot compile a string or line of text in a buffer or range longer than 256 characters. If DECTPU encounters a longer string or line, DECTPU truncates characters after the 256th character and attempts to compile the truncated string.

If necessary, use the SET (INFORMATIONAL, ON) built-in procedure before compiling a procedure interactively to see the compiler messages.

To check the results of a compilation to determine whether execution is possible, use the following statement in a program:

x := COMPILE (my_range); !if the program is nonzero, continue IF x <> 0 THEN . . . ENDIF;

If x = 0, no program is generated because of compilation errors or because there are no executable statements. The statement IF x <> 0 THEN allows your program to continue as long as a program is generated.

You can also use an ON_ERROR statement to check the result of a compilation. This statement tells you whether the compilation completed successfully; it does not tell you whether execution is possible.

Signaled Errors

Examples

The following example associates the MOVE_VERTICAL (1) function with the variable dwn. You can use the variable dwn with the EXECUTE built-in procedure to move the editing point down one line.

dwn := COMPILE ("MOVE_VERTICAL (1)") 
 
      

The following example compiles the contents of the main buffer:

user_program := COMPILE (main_buffer) 
      

If the buffer contains executable statements, DECTPU returns a program that stores these executable commands. If the buffer contains procedure definitions, DECTPU compiles the procedures and lists them in the procedure definition table so that you can call them in one of the following ways:

• Enter the name of the procedure after the appropriate prompt from the interface you are using.
• Call the procedure from within other procedures.

Format

CONVERT ({DECW_ROOT_WINDOW|SCREEN|window}, {CHARACTERS,|COORDINATES,}

from_x_integer, from_y_integer,

{DECW_ROOT_WINDOW|SCREEN|window}, {CHARACTERS,|COORDINATES,}

to_x_integer, to_y_integer )

Parameters

DECW_ROOT_WINDOW

Specifies the coordinate system to be that used by the root window of the screen on which DECTPU is running.

SCREEN

Specifies the coordinate system to be that used by the DECwindows window associated with DECTPU's top-level widget.

window

Specifies the coordinate system to be that used by the DECTPU window.

CHARACTERS

Specifies a system that measures screen distances in rows and columns, as a character-cell terminal does. In a character-cell-based system, the cell in the top row and the leftmost column has the coordinates (1,1).

COORDINATES

Specifies a DECwindows coordinate system in which coordinate units correspond to pixels. The pixel in the upper left corner has the coordinates (0, 0).

from_x_integer
from_y_integer

Integer values that represent a point in the original coordinate system and units.

to_x_integer
to_y_integer

Variables of type integer that represent a point in the specified coordinate system and units. The previous contents of the parameters are deleted when DECTPU places the resulting values in them. You must specify DECTPU variables for the parameters to_x_integer and to_y_integer. Passing a constant integer, string, or keyword value causes an error. (This requirement does not apply to the parameters from_x_integer and from_y_integer.)

Description

The CONVERT procedure, given the coordinates of a point in one coordinate system, returns the corresponding coordinates for the point in the coordinate system you specify. The converted coordinates are returned using the to_x_integer and to_y_integer parameters. Coordinate systems are distinguished both by units employed and where each places its origin.

Signaled Errors

Example

The following example converts a point's location from the current window's coordinate system (with the origin in the upper left-hand corner of the window) to the DECTPU screen's coordinate system (with the origin in the upper left-hand corner of the DECTPU screen).

PROCEDURE user_convert 
 
LOCAL source_x, 
      source_y, 
      dest_x, 
      dest_y; 
 
source_x := 1; 
source_y := 1; 
dest_x := 0; 
dest_y := 0; 
 
 
 
CONVERT (CURRENT_WINDOW, COORDINATES, source_x, source_y, 
         SCREEN, COORDINATES, dest_x, dest_y); 
 
 
 
ENDPROCEDURE;                      
      

If the current window is not the top window, CONVERT changes the value of the y coordinate to reflect the difference in the DECTPU screen's coordinate system. For more information about the difference between a DECTPU window and the DECTPU screen, see the program development chapter in the Guide to the DEC Text Processing Utility.

Format

[[range2 := ]] COPY_TEXT ({buffer|range1|string})

Parameters

buffer

The buffer containing the text that you want to copy.

range1

The range containing the text that you want to copy.

string

A string representing the text that you want to copy.

Return Value

Description

The COPY_TEXT procedure makes a copy of the text you specify and places it in the current buffer. If the current buffer is in insert mode, the text you specify is inserted before the current position in the current buffer. If the current buffer is in overstrike mode, the text you specify replaces text starting at the current position and continuing for the length of the string, range, or buffer.

Note You cannot add a buffer or a range to itself. If you try to add a buffer to itself, DECTPU issues an error message. If you try to insert a range into itself, part of the range is copied before DECTPU signals an error. If you try to overstrike a range into itself, DECTPU may or may not signal an error.

Using COPY_TEXT may cause DECTPU to insert padding spaces or blank lines in the buffer. COPY_TEXT causes the screen manager to place the editing point at the cursor position if the current buffer is mapped to a visible window. For more information on the distinction between the cursor position and the editing point, see Appendix C.

If the cursor is not located on a character (that is, if the cursor is before the beginning of a line, beyond the end of a line, in the middle of a tab, or below the end of the buffer), DECTPU inserts padding spaces or blank lines into the buffer to fill the space between the cursor position and the nearest text.

Signaled Errors

Examples

The following example causes the string "Perseus is near Andromeda" to be placed just before the current position in the current buffer when the buffer is set to insert mode:

COPY_TEXT ("Perseus is near Andromeda") 
 
      

The following example implements a simple INSERT HERE function. It assumes that there is a paste buffer and that this buffer contains the most recently deleted text. The procedure copies the text from that buffer into the current buffer.

PROCEDURE user_simple_insert 
   IF BEGINNING_OF (paste_buffer) = END_OF (paste_buffer) 
   THEN 
      MESSAGE ("Nothing to INSERT"); 
   ELSE 
       COPY_TEXT (paste_buffer); 
   ENDIF; 
ENDPROCEDURE; 
      

Format

array :=

CREATE_ARRAY [[ (integer1 [[ , integer2]]) ]]

Parameters

integer1

The number of integer-indexed elements to be created when the array is created. DECTPU processes elements specified by this parameter more quickly than elements created dynamically. You can add integer-indexed elements dynamically, but they are not processed as quickly as predeclared integer-indexed elements.

integer2

The first predeclared integer index of the array. The predeclared integer indexes of the array extend from this integer through to integer2 + integer1 --1. This parameter defaults to 1.

Return Value

Description

The CREATE_ARRAY procedure creates an array. In DECTPU, an array is a one-dimensional collection of data values that you can consider or manipulate as a unit.

To create an array variable called bat, use the CREATE_ARRAY built-in as follows:

bat := CREATE_ARRAY;

DECTPU arrays can have a static portion, a dynamic portion, or both. A static array or portion of an array contains predeclared integer-indexed elements. These elements are allocated contiguous memory locations to support quick processing. To create an array with a static portion, specify the number of contiguous integer-indexed elements when you create the array. You also have the option of specifying a beginning index number other than 1. For example, the following statement creates an array with 100 predeclared integer-indexed elements starting at 15:

bat := CREATE_ARRAY (100, 15);

All static elements of a newly created array are initialized to the data type unspecified.

A dynamic portion of an array contains elements indexed with expressions evaluating to any DECTPU data type except unspecified, learn, pattern, or program. Dynamic array elements are dynamically created and deleted as needed. To create a dynamic array element, assign a value to an element of an existing array. For example, the following statement creates a dynamic element in the array bat indexed by the string "bar" and assigns the integer value 10 to the element:

bat{"bar"} := 10;

To create an array with both static and dynamic elements, first create the static portion of the array. Then use assignment statements to create as many dynamic elements as you wish. For example, the following code fragment creates an array stored in the variable small_array. The array has 15 static elements and one dynamic element. The first static element is given the value 10. The dynamic element is indexed by the string "fred" and contains the value 100.

small_array := CREATE_ARRAY (15); small_array{1} := 10; small_array{"fred"} := 100;

To delete a dynamic array element, assign to it the constant TPU$K_UNSPECIFIED, which is of type unspecified.

One array can contain elements indexed with several data types. For example, you can create an array containing elements indexed with integers, buffers, windows, markers, and strings. An array element can be of any data type. All array elements of a newly created array are of type unspecified.

If the same array has been assigned to more than one variable, DECTPU does not create multiple copies of the array. Instead, each variable points to the array that has been assigned to it. DECTPU arrays are reference counted, meaning that each array has a counter keeping track of how many variables point to it. DECTPU arrays are autodelete data types, meaning that when no variables point to an array, the array is deleted automatically. You can also delete an array explicitly by using the DELETE built-in. For example, the following statement deletes the array bat:

DELETE (bat);

If you delete an array that still has variables pointing to it, the variables receive the data type unspecified after the deletion.

If you modify an array pointed to by more than one variable, modifications made using one variable show up when another variable references the modified element. To duplicate an array, you must write a procedure to create a new array and copy the old array's elements to the new array.

To refer to an array element, use the array variable name followed by an index expression enclosed in braces or parentheses. For example, if bar were a variable of type marker, the following statement would assign the integer value 10 to the element indexed by bar:

bat{bar} := 10;

You can perform the same operations on array elements that you can on other DECTPU variables, with one exception: you cannot make partial pattern assignments to array elements.

See the Guide to the DEC Text Processing Utility for additional information about arrays.

Signaled Errors

Examples

The following example creates an array that has ten predeclared integer-indexed elements that can be processed quickly by DECTPU. It can also be indexed by any other DECTPU data type except pattern, program, learn, and unspecified.

array2 := CREATE_ARRAY( 10 ); 
      

The following example creates an array that can be indexed by the integers --5 through 5. It can also be indexed by any other DECTPU data type other than patterns and learn sequences.

array3 := CREATE_ARRAY( 11, -5 ); 
      

Format

[[buffer2 := ]] CREATE_BUFFER (string1 [[,string2 [[,buffer1]] [[,string3]] ]])

Parameters

string1

A string representing the name of the buffer that you want to create.

string2

A string representing the file specification of an input file that is read into the buffer.

buffer1

The buffer that you want to use as a template for the buffer to be created. The information copied from the template buffer includes the following:

• End-of-buffer text
• Direction (FORWARD/REVERSE)
• Text entry mode (INSERT/OVERSTRIKE)
• Margins (right and left)
• Margin action routines
• Maximum number of lines
• Write-on-exit status (NO_WRITE)
• Modifiable status
• Tab stops
• Key map list

DECTPU does not copy the following attributes of the template buffer to the new buffer:

• Buffer contents
• Marks or ranges
• Input file name
• Mapping to windows
• Cursor position
• Editing point
• Associated subprocesses
• Buffer name
• Permanent status, if that is an attribute of the template buffer
• System status, if that is an attribute of the template buffer

string3

The name of the journal file to be used with the buffer. DECTPU does not copy the journal file name from the template buffer. Instead, CREATE_BUFFER uses string3 as the new journal file name. If you do not specify string3, DECTPU names the journal file by using its journal file naming algorithm. For more information on the naming algorithm, see the Guide to the DEC Text Processing Utility.

EVE turns on buffer-change journaling by default for each new buffer. However, the CREATE_BUFFER built-in procedure does not automatically turn on journaling. If you are layering directly on DECTPU, your application must use SET (JOURNALING) to turn journaling on.

Caution Journal files contain a record of all information being edited. Therefore, when editing files containing secure or confidential data, be sure to keep the journal files secure as well.

Return Value

Description

The CREATE_BUFFER procedure defines a new work space for editing text. You can create an empty buffer or you can associate an input file name with the buffer. CREATE_BUFFER optionally returns a buffer.

Although you do not have to assign the buffer that you create to a variable, you need to make a variable assignment if you want to refer to the buffer for future use. The buffer variable on the left-hand side of an assignment statement is the item that you must use when you specify a buffer as a parameter for other DECTPU built-in procedures. For example, to move to a buffer for editing, enter the buffer variable after the POSITION built-in procedure:

my_buffer_variable := CREATE_BUFFER ("my_buffer_name", "my_file_name"); POSITION (my_buffer_variable);

The buffer name that you specify as the first parameter for the CREATE_BUFFER built-in procedure (for example, "my_buffer_name") is used by DECTPU to identify the buffer on the status line. To change the status line, use the SET (STATUS_LINE) built-in procedure.

If you want to skip an optional parameter and specify a subsequent optional parameter, you must use a comma as a placeholder for the skipped parameter.

You can create multiple buffers. Buffers can be empty or they can contain text. The current buffer is the buffer in which any DECTPU commands that you execute take effect (unless you specify another buffer). Only one buffer can be the current buffer. See the CURRENT_BUFFER built-in procedure for more information.

A buffer is visible when it is associated with a window that is mapped to the screen. A buffer can be associated with multiple windows, in which case any edits that you make to the buffer are reflected in all of the windows in which the buffer is visible. To get a list of all the buffers in your editing context, use the SHOW (BUFFERS) built-in procedure.

When you use the following keywords with the SET built-in procedure, you can establish attributes for buffers. The text describes the default for the attributes:

• SET (EOB_TEXT, buffer, string)---The default end-of-buffer text is [EOB].
• SET (ERASE_UNMODIFIABLE, buffer, {ON|OFF} )---By default, unmodifiable records can be deleted from buffers by built-ins such as ERASE_LINE.
• SET (FORWARD, buffer)---The default direction is forward.
• SET (INSERT, buffer)---The default mode of text entry is insert.
• SET (JOURNALING, buffer, {ON|OFF} )---By default, buffer-change journaling is turned off.
• SET (LEFT_MARGIN, buffer, integer)---The default left margin is 1 (that is, the left margin is set in column 1).
• SET (LEFT_MARGIN_ACTION, buffer, program_source)---By default, buffers do not have left margin action routines.
• SET (MARGINS, buffer, integer1, integer2)---The default left margin is 1 and the default right margin is 80.
• SET (MAX_LINES, buffer, integer)---The default maximum number of lines is 0 (in other words, this feature is turned off).
• SET (MODIFIABLE, buffer, {ON|OFF} )---By default, a buffer can be modified. Using the OFF keyword makes a buffer unmodifiable.
• SET (MODIFIED, buffer, {ON|OFF} )---Turns on or turns off the bit indicating that the specified buffer has been modified.
• SET (NO_WRITE, buffer [[,keyword]])---By default, when you exit from DECTPU, the buffer is written if it has been modified.
• SET (OUTPUT_FILE, buffer, string)---The default output file is the input file specification with the highest existing version number for that file plus 1.
• SET (OVERSTRIKE, buffer)---The default mode of text entry is insert.
• SET (PERMANENT, buffer)---By default, the buffer can be deleted.
• SET (RECORD_ATTRIBUTE, marker, range, buffer)
• SET (REVERSE, buffer)---The default direction is forward.
• SET (RIGHT_MARGIN, buffer, integer)---The default right margin is 80.
• SET (RIGHT_MARGIN_ACTION, buffer, program_source)---By default, buffers do not have right margin action routines.
• SET (SYSTEM, buffer)---By default, the buffer is a user buffer.
• SET (TAB_STOPS, buffer, {string|integer} )---The default tab stops are set every eight character positions.

---

Previous

Next

Contents

Index

	privacy and legal statement
6020PRO_003.HTML