Updated: 11 December 1998

Guide to the DEC Text Processing Utility

Buffer-change journaling creates a separate journal file for each text buffer. The application can use the enhanced SET (JOURNALING) built-in to direct DECTPU to establish and maintain a separate journal file for any buffer or buffers created during the session. The application programmer or user can also use the SET (JOURNALING) built-in to turn journaling off or on for a given buffer during a session.

In the buffer's journal file, DECTPU keeps track of the following record attributes (and any changes made to them):

• Left margin setting
• Modifiability or unmodifiability
• Display value

The journal file also tracks the following:

• Characters inserted in and deleted from a record (including the location where the change took place)
• Records inserted in and deleted from a buffer (including the location where the change took place)

To determine whether buffer-change journaling is turned on, use the following statement:

status := GET_INFO (buffer_name, "journaling");

For more information on record attributes and display values, see the descriptions of the SET (RECORD_ATTRIBUTE) and SET (DISPLAY_VALUE) built-in procedures in the DEC Text Processing Utility Reference Manual.

Buffer-change journaling does not keep a record of all keystrokes performed while editing a given buffer.

2.4.3 Buffer-Change Journal File-Naming Algorithm

By default, DECTPU creates the buffer-change journal file name by using the following algorithm:

1. Converts all characters in the buffer name that are not alphanumeric, a dollar sign, underscore, or hyphen to underscores
2. Truncates the resulting file name to 39 characters
3. Adds the file type .TPU$JOURNAL

For example, a buffer named TEST.BAR has a default journal file name of TEST_BAR.TPU$JOURNAL.

DECTPU puts all journal files in the directory defined by the logical name TPU$JOURNAL. By default, this logical is defined as SYS$SCRATCH. You can reassign this logical name. For example, if you want journal files written to the current default directory, define TPU$JOURNAL as [].

2.5 Avoiding Errors Related to Virtual Address Space

DECTPU manipulates data in a process's virtual memory space. If the space required by the DECTPU images, data structures, and files in memory exceeds the virtual address space, DECTPU tries to write part of the data to the work file, thus freeing up space for other parts of the data that it needs immediately.

If the work file is full, DECTPU attempts to return either a TPU$_GETMEM or TPU$_NOCACHE error message. Although you may be able to free up some space by deleting unused buffers, Digital recommends that you terminate the DECTPU session if you encounter either of these errors. You can then start a new session with fewer or smaller buffers. Alternatively, you may want to put the work file on a disk that contains more free space. Use one of the following methods to do this:

• Redefine TPU$WORK to point to the disk with more free space.
• Invoke DECTPU with the /WORK=filename qualifier.

DECTPU may be unable to signal an error when it frees up memory by writing to the work file. In this case, DECTPU aborts with a fatal internal error.

You may be able to avoid writing to the work file by increasing the virtual address space available to a process. The virtual address space is controlled by the following two factors:

• The SYSGEN parameter VIRTUALPAGECNT
• The page file quota of the account you are using

The VIRTUALPAGECNT parameter controls the number of virtual pages that can be mapped for a process. For more information on VIRTUALPAGECNT, see the description of this parameter in the OpenVMS documentation on the System Generation Utility (SYSGEN).

The page file quota controls the number of pages in the system paging file that can be allocated to your process. For more information on the page file quota, see the description of the /PGFLQUOTA qualifier in the OpenVMS documentation on the Authorize Utility (AUTHORIZE).

You may need to modify both the VIRTUALPAGECNT parameter and the page file quota to enlarge the virtual address space.

DECTPU keeps strings in a different virtual pool than it does other memory. Once DECTPU starts writing to the work file, the size of the string memory pool is fixed. DECTPU cannot write strings to the work file, so if it needs to allocate more space in the string memory pool, it will fail with a fatal internal error. If you encounter this problem, you can expand the string memory pool during startup by preallocating several large strings. The following example shows how to do this:

PROCEDURE preallocate_strings LOCAL str_len, string1, string2; str_len := 65535; string1 := 'a' * str_len; string2 := string1; ENDPROCEDURE;

2.6 Using OpenVMS EDIT/TPU Command Qualifiers

The DCL command EDIT/TPU has qualifiers for setting attributes of DECTPU or an application layered on DECTPU. The qualifiers fall into the following two categories:

• Qualifiers handled by DECTPU
  Qualifiers in this category have their defaults set by DECTPU.
• Qualifiers handled by the application layered on DECTPU
  Some qualifiers in this category have their defaults set entirely by DECTPU; some have their defaults set entirely by the layered application, and some have their defaults set partly by each.

The following sections present the qualifiers in alphabetical order, giving a detailed description of each. The examples in the following sections show the qualifiers directly after the EDIT/TPU command and before the input file specification. You can place the qualifiers anywhere on the command line after EDIT/TPU. These sections show the defaults that are set if you use EVE. They also explain how EVE handles each qualifier that can be processed by a layered application. Applications not based on EVE may handle qualifiers differently.

2.6.1 /CHARACTER_SET

• /CHARACTER_SET=DEC_MCS (default)
• /CHARACTER_SET
  • =ISO_LATIN1
  • =GENERAL

The /CHARACTER_SET qualifier determines the character set you want DECTPU to use to display 8-bit characters. The choice of character set affects how DECTPU performs the following operations on characters:

• Converting to lowercase
• Converting to uppercase
• Inverting case
• Removing diacritical marks
• Converting to uppercase and removing diacritical marks

The choice of character set also affects how your text appears when printed. For the text displayed in DECTPU to look the same when printed, you must choose the same character set for both DECTPU and the printer.

There are two ways to specify the character set you want to use:

• Define the TPU$CHARACTER_SET logical name to specify the character set.
  This lets you use that character set for all editing sessions---including when you invoke DECTPU within MAIL or other utilities. You can put the definition in your LOGIN.COM file. For example, the following commands define TPU$CHARACTER_SET as ISO_LATIN1 and then use that character set to invoke DECTPU:

  $ DEFINE TPU$CHARACTER_SET ISO_LATIN1 $ EDIT/TPU

• Use /CHARACTER_SET= and specify the character set on the command line.
  This overrides any definition of the TPU$CHARACTER_SET logical name. By default, DECTPU uses the DEC_MCS character set. For example, the following command specifies the GENERAL character set to invoke DECTPU. DECTPU uses the current character set to display 8-bit characters and does not use the default DEC Supplemental Graphics character set.

  $ EDIT/TPU/CHARACTER_SET=general

If the character set you specify either with /CHARACTER_SET or by defining TPU$CHARACTER_SET is invalid, the editing session is aborted, returning you to the DCL level.

Table 2-3 shows the values you can specify with the /CHARACTER_SET qualifier or the TPU$CHARACTER_SET logical name.

Table 2-3 Character Set Values You Can Set with /CHARACTER_SET

Value	Description
DEC_MCS	This is the default setting that uses the DEC Supplemental Graphics character set containing supplemental and multinational characters, such as letters with accents and umlauts.
ISO_LATIN1	This character set contains supplemental and multinational characters that contain LATIN1 characters, such as the non-breaking space, multiplication and division signs, and the trademark sign.
GENERAL	DECTPU does not specify a character set for 8-bit characters. 8-bit characters are displayed the same as they were before you started DECTPU.

2.6.2 /COMMAND

• /COMMAND[[=filespec]]
• /NOCOMMAND
• /COMMAND=TPU$COMMAND.TPU (default)

The /COMMAND qualifier determines whether DECTPU compiles and executes a command file (a file of DECTPU procedures and statements) at startup time. Command files extend or modify a DECTPU-based application or create a new application. The default file type for DECTPU command files is .TPU. You cannot use wildcards in the file specification.

By default, DECTPU tries to read a command file called TPU$COMMAND.TPU in your default directory. You can use a full file specification after the /COMMAND qualifier or define the logical name TPU$COMMAND to point to a command file other than the default.

To determine whether you specified /COMMAND on the DCL command line, use the following call in the application:

x := GET_INFO (COMMAND_LINE, "command");

The preceding call returns 1 if /COMMAND was specified, 0 otherwise. To fetch the name of the command file specified on the command line, use the following call:

x := GET_INFO (COMMAND_LINE, "command_file");

For more information on GET_INFO, see the DEC Text Processing Utility Reference Manual.

The following command causes DECTPU to read a command file named SYS$LOGIN:MY_TPU$COMMAND.TPU and uses LETTER.RNO as the input file for an editing session:

$ EDIT/TPU/COMMAND=sys$login:my_tpu$command.tpu letter.rno

To prevent DECTPU from processing a command file, use the /NOCOMMAND qualifier. If you usually invoke DECTPU without a command file, define a symbol similar to the following:

$ EVE == "EDIT/TPU/NOCOMMAND"

Using /NOCOMMAND when you do not want to use a command file decreases startup time by eliminating the search for a command file.

If you specify a command file that does not exist, DECTPU terminates the editing session and returns you to the DCL command level.

For more information on writing and using command files, see Chapter 5.

2.6.3 /CREATE

• /CREATE (default)
• /NOCREATE

The /CREATE qualifier controls whether a DECTPU-based application creates a new file when the specified input file is not found. If you do not specify /CREATE or /NOCREATE on the command line, DECTPU sets the default to /CREATE but does not specify a default name for the file to be created.

The application layered on DECTPU is responsible for handling this qualifier.

To determine if you specified /CREATE on the DCL command line, include the following call in the application:

x := GET_INFO (COMMAND_LINE, "create");

The preceding call returns 1 if /CREATE was specified, 0 otherwise.

For more information on GET_INFO, see the DEC Text Processing Utility Reference Manual.

By default, EVE creates a new file if the specified input file does not exist. If you use /NOCREATE and specify an input file that does not exist, EVE aborts the editing session and returns you to the DCL command level. For example, if your default device and directory are DISK$:[USER] and you specify a nonexistent file, NEWFILE.DAT, your command and EVE's response would be as follows:

$ EDIT/TPU/NOCREATE newfile.dat Input file does not exist: DISK$:[USER]NEWFILE.DAT;

2.6.4 /DEBUG

• /DEBUG[[=debug_source_filename]]
• /NODEBUG (default)

The /DEBUG qualifier determines whether DECTPU loads, compiles, and executes a file implementing a DECTPU debugger. If /DEBUG is specified, DECTPU reads, compiles, and executes the contents of a debugger file before executing the procedure TPU$INIT_PROCEDURE and before executing the command file.

For more information on the DECTPU initialization sequence, see Chapter 5.

By default, DECTPU does not load a debugger. If you specify that a debugger is to be loaded but do not supply a file specification, DECTPU loads the file SYS$SHARE:TPU$DEBUG.TPU.

For more information on how to use the default DECTPU debugger, see Chapter 5.

To use a debugger file other than the default, use the /DEBUG qualifier and specify the device, directory, and file name of the debugger to be used. If you specify only the file name, DECTPU searches SYS$SHARE for the file. You can define the logical name TPU$DEBUG to specify a file that contains a debugger program. Once you define this logical name, using /DEBUG without specifying a file calls the file specified by TPU$DEBUG.

2.6.5 /DISPLAY

• /DISPLAY
  • = CHARACTER_CELL (default)
  • = DECWINDOWS
• /NODISPLAY

To choose the DECwindows or the non-DECwindows version of DECTPU, use the /DISPLAY qualifier on the DCL command line when you invoke DECTPU.

The /DISPLAY qualifier is optional. By default, DECTPU uses /DISPLAY=CHARACTER_CELL, regardless of whether you are running DECTPU on a workstation or a terminal.

If you specify /DISPLAY=CHARACTER_CELL, DECTPU uses its character-cell screen manager, which implements the non-DECwindows version of DECTPU by running in a DECterm terminal emulator or on a physical terminal.

If you specify /DISPLAY=DECWINDOWS, and if the DECwindows environment is available, DECTPU uses the DECwindows screen manager, which creates a DECwindows window in which to run DECTPU.

If you specify /DISPLAY=DECWINDOWS and the DECwindows environment is not available, DECTPU uses its character-cell screen manager to implement the non-DECwindows version of DECTPU.

For more information about the difference between a DECwindows window and a DECTPU window, see Chapter 5.

The /NODISPLAY qualifier causes DECTPU to run without using the screen display and the keyboard functions of a terminal. Use /NODISPLAY in the following cases:

• When running DECTPU procedures in a batch job
• When using DECTPU on an unsupported terminal

When you use /NODISPLAY, all operations continue as usual, except that no output occurs. (The only exception is that information usually put into the message buffer will appear on SYS$OUTPUT if no message buffer is available.)

The following command causes DECTPU to edit the file MY_BATCH_FILE.RNO without using terminal functions such as screen display:

$ EDIT/TPU/NODISPLAY my_batch_file.rno

2.6.6 /INITIALIZATION

• /INITIALIZATION[[=filespec]] (default)
• /NOINITIALIZATION

The /INITIALIZATION qualifier determines whether the DECTPU-based application being run executes a file of initialization commands. The application layered on DECTPU is responsible for processing this qualifier.

To determine whether you specified /INITIALIZATION on the DCL command line, use the following call in the application:

x := GET_INFO (COMMAND_LINE, "initialization");

The preceding call returns 1 if /INITIALIZATION was specified, 0 otherwise. To fetch the name of the initialization file specified on the command line, use the following call:

x := GET_INFO (COMMAND_LINE, "initialization_file");

For more information on GET_INFO, see the DEC Text Processing Utility Reference Manual.

If you do not specify any form of /INITIALIZATION on the DCL command line, DECTPU specifies /INITIALIZATION but does not supply a default file specification. The default file specification for /INITIALIZATION is set by the application. Digital recommends that a user-written application define the default file specification of an initialization file by using the following format:

facility$init.facility

For example, the default initialization file for the EVE editor is EVE$INIT.EVE.

In EVE, if you do not specify a device or directory, EVE first checks the current directory. If the specified (or default) initialization file is not there, EVE checks SYS$LOGIN. If EVE finds the specified (or default) initialization file, EVE executes the commands in the file.

For more information on using initialization files with EVE, see Chapter 5 and the Extensible Versatile Editor Reference Manual.

2.6.7 /INTERFACE

• /INTERFACE
  • = CHARACTER_CELL
  • = DECWINDOWS
• /INTERFACE= CHARACTER_CELL (default)

The /INTERFACE qualifier determines the interface or screen display you want (same as /DISPLAY). The default is CHARACTER_CELL.

For example, to invoke EVE with the DECwindows interface, use the following command:

$ EDIT/TPU /INTERFACE=DECWINDOWS

Then, if DECwindows is available, DECTPU displays the editing session in a separate window on your workstation screen and enables DECwindows features; for example, the EVE screen layout includes a menu bar and scroll bars. If DECwindows is not available, DECTPU works as if on a character-cell terminal.

2.6.8 /JOURNAL

• /JOURNAL[[=input_file.TJL]] (default for EVE)
• /NOJOURNAL (default for DECTPU)

The /JOURNAL qualifier determines whether DECTPU keeps a journal file of an editing session so you can recover the session if it is unexpectedly interrupted. DECTPU offers two forms of journaling:

• Keystroke---In a single journal file, keeps track of each keystroke you make, regardless of which buffer is in use when you press the key.
• Buffer-change---In a separate journal file, keeps track of changes made to buffers for each buffer created during the session.

The application layered on DECTPU is responsible for processing this qualifier.

To determine whether you specified /JOURNAL on the DCL command line, use the following call in the application:

x := GET_INFO (COMMAND_LINE, "journal");

The preceding call returns 1 if /JOURNAL was specified, 0 otherwise.

To determine whether buffer-change journaling is turned on for a buffer, use a statement similar to the following:

status := GET_INFO (buffer_name, "journaling");

To determine the name of the keystroke journal file specified on the command line, use the following call:

x := GET_INFO (COMMAND_LINE, "journal_file");

For more information on GET_INFO, see the DEC Text Processing Utility Reference Manual.

In EVE, if you do not specify any form of /JOURNAL or specify /JOURNAL but not a journal file, buffer-change journaling is turned on. The buffer-change journal file's default file type is .TPU$JOURNAL.

If you specify /JOURNAL=filename, then EVE also turns on keystroke journaling. The keystroke journal file's default file type is .TJL.

To prevent EVE from creating either a keystroke or buffer-change journal file for an editing session, use the /NOJOURNAL qualifier. For example, the following command causes EVE to turn off buffer-change journaling when you edit the input file MEMO.TXT:

$ EDIT/TPU/NOJOURNAL memo.txt

If you are developing an application layered on DECTPU, you can use the built-in JOURNAL_OPEN to direct DECTPU to create a keystroke journal file for an editing session. Using JOURNAL_OPEN causes DECTPU to provide a 500-byte buffer in which to journal keystrokes. By default, DECTPU writes the contents of the buffer to the journal file when the buffer is full.

You can use the built-in procedure SET (JOURNALING) to turn on buffer-change journaling, even if you have used /NOJOURNAL to turn it off initially. You can also use SET (JOURNALING) to adjust the journaling frequency.

For more information on JOURNAL_OPEN and SET (JOURNALING), see the DEC Text Processing Utility Reference Manual. For more information on buffer-change journaling, see Section 2.4.

Once a keystroke journal file is created, use the /RECOVER qualifier to direct DECTPU to process the commands in the keystroke journal file. For example, the following command causes DECTPU to recover a previous editing session on an input file named MEMO.TXT. Because the journal file has a name different from the input file name, both /JOURNAL and /RECOVER are used. The name of the keystroke journal file is MEMO.TJL:

$ EDIT/TPU/RECOVER/JOURNAL=memo.tjl memo.txt

In buffer-change journaling, to recover the changes made to a specified buffer, use the RECOVER_BUFFER built-in procedure.

For more information on RECOVER_BUFFER, see the DEC Text Processing Utility Reference Manual. For more information on how to recover from an interrupted EVE editing session, see the Extensible Versatile Editor Reference Manual.

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

6018PRO_002.HTML