Document revision date: 30 March 2001

The following DECTPU procedures are samples of how to use DECTPU to perform certain tasks. These procedures show one way of using DECTPU; there may be other, more efficient ways to perform the same task. Make changes to these procedures to accommodate your style of editing.

For these procedures to compile and execute correctly, you must make sure that there are no conflicts between these sample procedures and your interface. This appendix contains the following types of procedures:

1. Line-mode editor
2. Translation of control characters
3. Restoring terminal width before exiting from DECTPU
4. DCL command procedure to run DECTPU from a subprocess

Example A-1 shows a portion of an editing interface that uses line mode rather than screen displays for editing tasks. You can use this mode of editing for batch jobs or for running DECTPU on terminals that do not support screen-oriented editing.

Example A-1 Line-Mode Editing

! Portion of a line mode editor for DECTPU ! input_file := GET_INFO (COMMAND_LINE, "file_name"); ! Set up main main_buffer := CREATE_BUFFER ("MAIN", input_file); ! buffer from input POSITION (BEGINNING_OF (main_buffer)); ! file ! LOOP ! Continuously loop until QUIT cmd := READ_LINE ("*"); IF cmd = "" THEN cmd_char := "N"; ELSE cmd_char := SUBSTR (cmd, 1, 1); CHANGE_CASE (cmd_char, UPPER); ENDIF; CASE cmd_char FROM "I" TO "T" ! Only accepting I,L,N,Q,T !Top of buffer command ["T"]: POSITION (BEGINNING_OF (CURRENT_BUFFER)); MESSAGE (CURRENT_LINE); !Next line command ["N"]: MOVE_HORIZONTAL (-CURRENT_OFFSET); MOVE_VERTICAL (1); MESSAGE (CURRENT_LINE); !Insert text command ["I"]: SPLIT_LINE; COPY_TEXT (SUBSTR (cmd, 2, 999)); MESSAGE (CURRENT_LINE); !List from here to end of file command ["L"]: m1 := MARK (NONE); LOOP MESSAGE (CURRENT_LINE); MOVE_VERTICAL (1); EXITIF MARK (NONE) = END_OF (CURRENT_BUFFER); ENDLOOP; POSITION (m1); !QUIT ["Q"]: QUIT; [INRANGE,OUTRANGE]: MESSAGE ("Unrecognized command - enter I,L,N,Q or T"); ENDCASE; ENDLOOP;

A.2 Translation of Control Characters

Example A-2 shows how to display control characters in a meaningful way. This is accomplished by translating the buffer to a different visual format and mapping this new form to a window. On the VT400, VT300, and VT200 series of terminals, control characters are shown as reverse question marks; on the VT100 series of terminals, they are shown as rectangles.

Example A-2 Procedure to Display Control Characters

! This procedure performs the substitution of meaningful characters ! for the escape or control characters. ! PROCEDURE translate_controls (char_range) LOCAL replace_text; ! ! If the translation array is not yet set up, then do it now. The elements ! that we do not initialize will contain the value TPUK_UNSPECIFIED. They are ! characters that TPU will display meaningfully. ! IF translate_array = TPU$K_UNSPECIFIED THEN translate_array := CREATE_ARRAY (32, 0); translate_array {1} := '<SOH>'; translate_array {2} := '<STX>'; translate_array {3} := '<ETX>'; translate_array {4} := '<EOT>'; translate_array {5} := '<ENQ>'; translate_array {6} := '<ACK>'; translate_array {7} := '<BEL>'; translate_array {8} := '<BS>'; translate_array {14} := '<SO>'; translate_array {15} := '<SI>'; translate_array {16} := '<DLE>'; translate_array {17} := '<DC1>'; translate_array {18} := '<DC2>'; translate_array {19} := '<DC3>'; translate_array {20} := '<DC4>'; translate_array {21} := '<NAK>'; translate_array {22} := '<SYN>'; translate_array {23} := '<ETB>'; translate_array {24} := '<CAN>'; translate_array {25} := '<EM>'; translate_array {26} := '<SUB>'; translate_array {27} := '<ESC>'; translate_array {28} := '<FS>'; translate_array {29} := '<GS>'; translate_array {30} := '<RS>'; translate_array {31} := '<US>'; ENDIF; ! ! The range *must* be a single character long ! IF LENGTH (char_range) <> 1 THEN RETURN 0; ENDIF; ! ! Find the character ! replace_text := translate_array {ASCII (STR (char_range))}; ! ! If we got back a value of TPU$K_UNSPECIFIED, TPU will display the character ! meaningfully ! IF replace_text = TPU$K_UNSPECIFIED THEN RETURN 0; ENDIF; ! ! Erase the range and insert the new text ! ERASE (char_range); COPY_TEXT (replace_text); RETURN 1; ENDPROCEDURE; ! ! This procedure controls the outer loop search for the special ! control characters that we want to view. ! PROCEDURE view_controls (source_buffer) CONSTANT Ctrl_char_str := ASCII (0) + ASCII (1) + ASCII (2) + ASCII (3) + ASCII (4) + ASCII (5) + ASCII (6) + ASCII (7) + ASCII (8) + ASCII (9) + ASCII (10) + ASCII (11) + ASCII (12) + ASCII (13) + ASCII (14) + ASCII (15) + ASCII (16) + ASCII (17) + ASCII (18) + ASCII (19) + ASCII (20) + ASCII (21) + ASCII (22) + ASCII (23) + ASCII (24) + ASCII (25) + ASCII (26) + ASCII (27) + ASCII (28) + ASCII (29) + ASCII (30) + ASCII (31); LOCAL Ctrl_char_pattern, Ctrl_char_range; ! Create the translation buffer and window, if necessary ! IF translate_buffer = TPU$K_UNSPECIFIED THEN translate_buffer := CREATE_BUFFER ("translation"); SET (NO_WRITE, translate_buffer); ENDIF; IF translate_window = TPU$K_UNSPECIFIED THEN translate_window := CREATE_WINDOW (1, 10, ON); ENDIF; ! ! Make a copy of the buffer we are translating ! ERASE (translate_buffer); POSITION (translate_buffer); COPY_TEXT (source_buffer); ! ! Search for any control characters and translate them. If a control character ! is not found, SEARCH_QUIETLY will return a 0. ! Ctrl_char_pattern := ANY (Ctrl_char_str); POSITION (BEGINNING_OF (translate_buffer)); LOOP Ctrl_char_range := SEARCH_QUIETLY (Ctrl_char_pattern, FORWARD); EXITIF Ctrl_char_range = 0; POSITION (Ctrl_char_range); ! ! If we did not translate the character, move past it ! IF NOT translate_controls (Ctrl_char_range) THEN MOVE_HORIZONTAL (1); ENDIF; ENDLOOP; ! ! Now display what we have done ! POSITION (BEGINNING_OF (translate_buffer)); MAP (translate_window, translate_buffer); ENDPROCEDURE;

A.3 Restoring Terminal Width Before Exiting from DECTPU

Example A-3 Procedure to Restore Screen to Original Width

PROCEDURE user_restore_screen LOCAL original_screen_width, temp_w; original_screen_width := GET_INFO (SCREEN, "original_width"); IF original_screen_width <> GET_INFO (SCREEN, "width") THEN temp_w := get_info(windows,"first"); LOOP EXITIF temp_w = 0; SET (WIDTH, temp_w, original_screen_width); temp_w := GET_INFO (WINDOWS, "next"); ENDLOOP; REFRESH; ENDIF; ENDPROCEDURE; ! Define the key combination Ctrl/E to do an exit which ! restores the screen to its original width, repaints ! the screen, and then exits. DEFINE_KEY ("user_restore_screen;EXIT", Ctrl_E_KEY);

A.4 Running DECTPU from an OpenVMS Subprocess

Example A-4 Procedure to Run DECTPU from a Subprocess

! !DCL command procedure to run DECTPU from subprocess ! !Put $ e = "@keptedit" !in your login.com. This spawns the editor the first time !and attaches to it after that. I have defined a key to be !"attach" so it always goes back to the parent. $ tt = f$getdvi("sys$command","devnam") - "_" - "_" - ":" $ edit_name = "Edit_" + tt $ priv_list = f$setprv("NOWORLD, NOGROUP") $ pid = 0 $10$: $ proc = f$getjpi(f$pid(pid), "PRCNAM") $ if proc .eqs. edit_name then goto attach $ if pid .ne. 0 then goto 10$ $spawn: $ priv_list = f$setprv(priv_list) $ write sys$error "[Spawning a new Kept Editor]" $ define/nolog sys$input sys$command: $ t1 = f$edit(p1 + " " + p2 + " " + p3 + " " + p4 + " " + p5 + " " + p6 + " " + p7 + " " + p8,"COLLAPSE") $ spawn/process="''edit_name'" /nolog edit/tpu 't1' $ write sys$error "[Attached to DCL in directory ''f$env("DEFAULT")']" $ exit $attach: $ priv_list = f$setprv(priv_list) $ write sys$error "[Attaching to Kept Editor]" $ define/nolog sys$input sys$command: $ attach "''edit_name'" $ write sys$error "[Attached to DCL in directory ''f$env("DEFAULT")']" $ exit

This appendix lists the terminals that support screen-oriented editing and describes how differences among these terminals affect the way DECTPU performs. This appendix also describes how you can run DECTPU on terminals that do not support screen-oriented editing. Finally, this appendix tells you how DECTPU manages wrapping and how you can modify that.

B.1 Using Screen-Oriented Editing on Supported Terminals

DECTPU supports screen-oriented editing only on terminals that respond to ANSI control functions and that operate in ANSI mode.

DECTPU screen-oriented editing is designed to optimize the features available with the Compaq VT400, VT300, and VT200 families of terminals and the Compaq VT100 family of terminals. DECTPU does not support screen-oriented editing on Compaq VT52-compatible terminals. Optimum DECTPU performance is achieved on the VT300-series, VT200-series, and VT100-series terminals. Some of the high-performance characteristics of DECTPU may not be apparent on the terminals listed in Table B-1 for the reasons stated.

Table B-1 Terminal Behavior That Affects DECTPU's Performance

Terminal	Characteristic
VT102	Slow autorepeat rate
VT240	Slow autorepeat rate Slower scrolling region setup time than the VT220.
GIGI	One form of scrolling region (DECTPU repaints screen, rather than use this scrolling mechanism) Variable autorepeat rate (cursor keys pick up speed when used repeatedly)

By default, your DECTPU session runs with the screen management file TPU$CCTSHR.EXE. To check your terminal setting, enter the following command at the command prompt:

$ SHOW TERMINAL

B.1.1 Terminal Settings on OpenVMS Systems That Affect DECTPU

The following settings may affect the behavior of DECTPU, depending on the terminal that you use.

132-Column Mode

Only terminals that set the DEC_CRT mode bit and the advanced video mode bit can alter their physical width from 80 columns to 132 and back. All other terminals keep the physical width that is set when you enter the editor.

For the DECTPU screen manager to behave predictably on GIGI terminals, you should report the terminal width as 84 to OpenVMS systems. Use the DCL command SET TERMINAL/DEVICE=VT100 to set the proper terminal width.

Autorepeat ON/OFF and Auxiliary Keypad Enabling

To take advantage of the SET (AUTO_REPEAT) built-in procedure or to enable the auxiliary keypad for applications mode, the terminal must be set to DEC_CRT3, DEC_CRT2, DEC_CRT, or VT100. Use the DCL command SET TERMINAL/DEVICE=characteristic to set the terminal.

Control Sequence Introducer

DECTPU can use one 8-bit control sequence introducer (CSI) to introduce a terminal control sequence. (Usually you use the 2-character combination of the ESCAPE key and the left bracket ([).) To take advantage of this feature, set your terminal to DEC_CRT2 mode. The Compaq VT300-series and VT220 and VT240 terminals currently support this feature.

Cursor Positioning

If your terminal sets the DEC_CRT mode bit, DECTPU assumes that when control sequences that position the cursor to row 1 or column 1 are sent to the terminal, the 1 can be omitted. If your terminal does not behave correctly when it receives these control sequences, you must turn off the DEC_CRT mode bit. Some foreign terminals may not be fully compatible with DECTPU and may exhibit this behavior.

Edit Mode

Terminals that are operating in edit mode allow the editor to take advantage of special edit-mode control sequences during deletion and insertion of text for optimization purposes. Some current Compaq terminals that support edit mode include the VT102, the VT220, the VT240, the VT241, and VT300-series terminals.

8-Bit Characters

ANSI terminals operating in 8-bit mode have the ability to use the supplemental characters and control sequences in the DEC Multinational Character Set. The Compaq VT300-series and the VT220 and VT240 terminals currently support 8-bit character mode. If you have the 8-bit mode bit set, DECTPU designates the DEC Multinational Character Set into G2 and invokes it into GR. For more information on how your terminal interacts with the DEC Multinational Character Set, refer to the programming manual for your specific terminal.

Scrolling

DECTPU uses scrolling regions only for terminals that have the DEC_CRT mode bit set. On other terminals, DECTPU repaints the window when a scroll would have been used (for example, when a line is deleted or inserted).

Video Attributes

When you set the video attributes of windows, markers, or ranges, only those attributes supported by your terminal type give predictable results. Most ANSI CRTs support reverse video. However, only terminals that support DEC_CRT mode with the advanced video option (AVO) have the full range of video attributes (reverse, bold, blink, underline) that DECTPU supports.

B.1.2 SET TERMINAL Command

When you use the SET TERMINAL command to specify characteristics for your terminal, make sure to set only those characteristics that are supported by your terminal. If you set characteristics that the terminal does not support, the screen-oriented functions of DECTPU may behave unpredictably. For example, if you run DECTPU on a VT100 terminal and you set the DEC_CRT2 characteristic that VT100s do not support, DECTPU tries to use 8-bit CSI controls. This could cause ";7m" to appear on the screen where the reverse video attribute should be set.

Most users do not knowingly set characteristics that are not supported by their terminals. However, if you temporarily move to a different type of terminal, your LOGIN.COM file may have characteristics set for your usual terminal that do not apply to the current terminal. This problem may also occur if, before running DECTPU, you run a program that modifies your terminal characteristics without your knowledge.

If you see unexpected video attributes or extraneous characters on the screen, exit from DECTPU and check your terminal characteristics with the DCL command SHOW TERMINAL.

To recover your files, use the same terminal characteristics you used to create your file; otherwise, a journal file inconsistency may occur, depending on how your interface is written.

B.2 Using Line-Mode Editing on Unsupported Terminals

If you want to run DECTPU from an unsupported terminal, you must inform DECTPU that you do not want to use screen capabilities. To invoke DECTPU on an unsupported terminal, use the /NODISPLAY qualifier after the EDIT/TPU command. See Chapter 2 for more information on this qualifier. While in no-display mode, DECTPU uses the RTL generic LIB$PUT_OUTPUT routine to display prompts and messages at the current location in SYS$OUTPUT. By using a combination of the READ_LINE and MESSAGE built-in procedures, you can devise your own line-mode editing functions or perform editing tasks from a batch job. See the sample line-mode editor in Appendix A.

B.3 Using Terminal Wrap

Terminal wrap characteristics perform differently on each operating system.

If you have enabled an automatic wrap setting on your terminal, DECTPU disables this setting in order to manage the screen more efficiently. When you exit from DECTPU, DECTPU restores all terminal characteristics. If the SET TERM/NOWRAP command is active, DECTPU leaves the hardware wrap off. However, if the SET TERM/WRAP command is active, DECTPU assumes that you want hardware wrap on, so it turns it on when you exit from DECTPU.

You can prevent DECTPU from turning on hardware wrap by specifying SET TERM/NOWRAP before invoking DECTPU. You can enter the command interactively, or you can write a DCL command procedure that makes this setting part of your DECTPU environment. Example B-1 shows a DCL command procedure that is used to control this terminal setting before and after a DECTPU session.

Example B-1 DCL Command Procedure for SET TERM/NOWRAP

$ SET TERM/NOWRAP $ ASSIGN/USER SYS$COMMAND SYS$INPUT $ EDIT/TPU/SECTION = EDTSECINI $ SET TERM/WRAP

	privacy and legal statement
6018PRO_014.HTML