nu/TPU README files' contents: READ_ME nu/TPU files and directories Use of environment variables Additional X command line switches X keyboard files Using non-windowed nu/TPU in X Window environments Using VAX/VMS developed programs User defaults file Screen attributes Compiling nu/TPU source code License lock management Keyboard drivers nu/TPU installation verifier nu/TPU support policies v4 differences from v3 Known problems READ_ME.SI Differences from tpusec.ini Menu builder facility TPU source files si keypad, EVE, EDT, and others READ_ME.X nu/TPU windowing built-ins Motif widget class and nu/TPU Xnu_tpu file -------------------------------------------------------------------------- Getting Help a/Soft Development, Inc. One Executive Park Drive Bedford, NH 03110 603.666.6699 603.666.6460 Fax If you have problems installing nu/TPU, technical support can be reached at (603)666-6699. Calling while you are working at the computer will provide the fastest possible service. When you call, please have ready your nu/TPU serial number and the type of computer you are working on. IMPORTANT: After installation, review the read me files for machine-specific information, known bugs, VMS differences, and other important information. -------------------------------------------------------------------------- nu/TPU files and directories After the installation process is complete, the following directories and files will be installed on your system. [THE DIRECTORY YOU SPECIFIED DURING INSTALLATION] tpu Script to run character cell version xtpu Script to run Motif version READ_ME Installation and last minute notes READ_ME.X Xwindows specific notes READ_ME.SI SI (Simple Interface) specific notes [nu_tpu] nu_tpu.def User defaults file nu_tpu.win Motif version menu bar structure Xnu_tpu Motif version resource file [OS_specific] tpu_v41 Main executable file license.lok Serial management file makeseri Program to fix/create license file makehelp Program to create help indexes motif_v41 [Optional] Motif program keys Program to output key values [dev] Various keyboard files [common] si.ini Simple interface tpusec.ini VMS 5.0 style interface sihelp.hlb Help file For si.ini sihelp.idx Help index For si.ini tpuhelp.hlb Help file tpuhelp.idx Help index evehelp.hlb Help file For tpusec.ini evehelp.idx Help index For tpusec.ini evekey.hlb Help file For tpusec.ini evekey.idx Help index For tpusec.ini [source] si interface TPU source files -------------------------------------------------------------------------- Use of environment variables nu/TPU uses environment variables to define the hardware and the location of files to be used by nu/TPU. Normally these variables are set in your login or tpu script files. Refer to your UNIX documentation if you are unfamiliar with use of environment variables. Variable Use Values HOME Optional The location of the user home directory. KEYBOARD Optional The type of keyboard to be used. Must match one of the files in the /usr/local/nu_tpu/dev directory. TERM Required Used by the termcap/terminfo libraries to manage the video display. TPU_DEFAULTS_FILE Optional Name of file containing session information. If a full file name is not provided, the file is assumed to exist in the /usr/local/ or TPU_HOME directory. The default name is nu_tpu.def. TPU_HOME Optional The name of the directory containing the nu_tpu directory. This variable is REQUIRED if the directory is not /usr/local/. -------------------------------------------------------------------------- Using VAX/VMS developed programs Source code used with TPU on Digital VAX/VMS systems can be compiled with nu/TPU. User defaults file An example of a defaults file is in the appendix of the nu/TPU manual. A defaults file is not required, however a warning message will always appear if one cannot be found at run time. Normally the only thing defined in the defaults file is the type of keyboard you are using. Defaults file entries are superseded by command line switches. Screen attributes nu/TPU supports the following screen attributes: NORMAL, BOLD, BLINK, REVERSE, and UNDERLINE; and colors: BLACK, BLUE, GREEN, RED, MAGENTA, CYAN, YELLOW, and WHITE. Not all computers or monitors support all of the above attributes. Compiling nu/TPU source code nu/TPU can compile code from either a command file or a buffer using the EXTEND TPU command. Command file code is compiled before the user interface is started. The EXTEND TPU command should also be reviewed. Compiling code instead of using initialization files will improve startup time. License lock management nu/TPU can be installed on a network file server. Each time nu/TPU runs, the license file is verified. If a lock is available (the default number of locks for MS-DOS is 1), then a new session is started. The lock is returned when the program is finished. If the lock file becomes damaged, run the makeseri program with the -reset option. Keyboard drivers Keyboard files define the relationships between the character sequences or key codes sent from the keyboard and the edit functions for the nu/TPU interface. nu/TPU works on various platforms and operating systems. The outcome of all that versatility is that there is a wide variety of keyboards nu/TPU has to work with. The keyboard files that have been predefined are located in the nu_tpu/dev directory. The filenames will match the terminal type, with X Windows keyboard drivers ending with a '.x' extension. For more specific information on the keyboard file syntax, operation, and customization, see keyboard files under the nu/TPU Files section in the reference manual. -------------------------------------------------------------------------- nu/TPU Installation Verifier COMMON PROBLEMS & ERRORS Using the verifier. The following text is set up in a progressive format. After entering the requested command, if your results match the text shown, proceed directly to the next verification phase. If your results do not match, the common problems and corrections are shown. Problems resulting from installation and normal use are presented together. Assumptions: Super-user 'su' privileges are needed to fix most problems. Correction examples are shown in bourne shell syntax '/bin/sh'. The installation directory is assumed to be /usr/local/. In examples, '???' is not literal, but should be replaced by your data. The section file used is si.ini, off the distribution media. VERIFICATION PHASE 1 Problems preventing nu/TPU from starting. SHELL PROMPT $ tpu -env ABORT_2_CONTROL_C:1: BACKUPS:1: CREATE:1: COMMAND_FILE:common/tpuini.tpu: DEBUG_FILE:common/debug.tpu: DISPLAY:1: ESCAPE_IS_SHIFT:0: FILE_STYLE:UNIX: HANDLE_ESCAPE:1: INITIALIZATION_FILE:: JOURNAL_FILE:: KEYBOARD:vt200: WIDTH:80: LENGTH:24: LANGUAGE:USA_ENGLISH: MESSAGE_FILE:: MODIFY:0: OUTPUT_FILE:: READ_ONLY:0: RECOVER:0: SECTION_FILE:/usr/local/nu_tpu/common/si.ini: START_RECORD:1: START_CHARACTER:1: STACK_SIZE:1000: SWITCH_STYLE:-: TERM_TYPE:ANSI: TPU_DEFAULTS_FILE:nu_tpu.def: WRITE:1: INTERFACE:: # Serial Number:0000000000000000 Version 4.1 Proceed to Phase 2 of verification if the above text was displayed; an exact match of the text is not required. If you did not get the proper display, check the common errors below and rerun Phase 1. tpu not found An executable file named tpu could not be located in your current path. The installation process created a shell script named tpu in the installation directory. Select one of the following three recommendations. 1) Add the installation directory to your search path. PATH=/usr/local:$path; export PATH 2) Move the tpu script to a directory that is in your path. mv /usr/local/tpu /bin/tpu 3) Specify the entire path every time you use nu/TPU. /usr/local/tpu Unknown terminal '???' The TERM environment variable is set to a value the UNIX terminfo/termcap does not understand. Common unknown settings are 'unknown', 'network', and 'dialup'. Your system administrator can suggest the proper setting for your terminal. The manual pages on 'terminfo' will show how to determine the complete set of terminal choices. '???/nu_tpu' is not a properly installed nu/TPU location. You receive this message if nu/TPU is not in the directory /usr/local/ and the environment variable TPU_HOME is not properly defined. The '???' is the directory containing the nu_tpu directory. It is recommended to add the following line to your tpu shell script. TPU_HOME=???; export TPU_HOME Unable to read license file: '???/license.lok' The license file must be read/write enabled. If mounted on a network, file-system must also be read/write enabled. If the license file does not exist, proceed with the following license.lok damaged instructions. License file: license.lok damaged The license.lok is located in the same directory as the 'tpu_v41' program. If you are unsure of the location, it is specified in the 'tpu' shell script. cd /usr/local/nu_tpu/??? ./makeseri -reset If this problem persists, the license.lok was corrupted by an outside utility. Use the makeseri utility with your serial number as the argument. ./makeseri ????-????-?????-??? Missing Section file '???' The requested section file does not exist. The default section filename is /usr/local/nu_tpu/common/si.ini. It is possible to request a different section file on the command line or in your nu/TPU defaults file. When specifying a section name, if an absolute or relative path name is not provided, the section file is assumed to exist in the directory /usr/local/nu_tpu/common. Undefined keyboard: '???' The keyboard file '???' does not exist in the /usr/local/nu_tpu/dev directory. The default keyboard file is vt200. The keyboard file can be specified in the nu/TPU defaults file or through the environment variable KEYBOARD. The environment variable takes precedence. SYSTEM MESSAGE: Missing system library file. Contact Customer service. VERIFIER PHASE 2 Problems preventing the si interface from starting SHELL PROMPT $ tpu Invoking the nu/TPU editor creates a screen with the bottom two lines of the window being used for displaying messages and command/prompt input. The remainder of the screen is used by the edit window and a status line indicating the current buffer name is 'main'. If your screen display does not match the description above, either the section file off the distribution tape is not being used or environment variable TERM is set to something that does not update your screen properly. Section files from version 3.0 may be used with the character cell version 4.1 of nu/TPU. Internal nu/TPU error, on signal 11 The file requested is either not a section file, a section file from non-supported version, or a damaged section file. If the section file is user-defined, it must be rebuilt. If the section file is from the distribution media, nu/TPU must be reinstalled. SHELL PROMPT $ xtpu Sorry: need to use si.ini When running the X version of nu/TPU, the section file must be the si.ini section file or an extended version of it. VERIFIER PHASE 3 Problems defining keyboard From within a nu/TPU session, press the Control-K key. A keymap similar to the display on page 94 of the nu/TPU reference manual will be displayed. The keymap should match your keyboard layout and not the text from the reference manual. If the keymap shown does not match your keyboard, either you are using the default keyboard 'vt200' or have selected an invalid keyboard for your terminal. The keyboard file is specified by the following methods. Keyboard files are located in the directory /usr/local/nu_tpu/dev 1) Setting the KEYBOARD environment variable. KEYBOARD=???; export KEYBOARD 2) If not set by method 1, then by adding a KEYBOARD entry in your nu/TPU defaults file. ~/nu_tpu.def or /usr/local/nu_tpu/nu_tpu.def. See the appendix in the reference manual for the syntax defaults files. 3) If not set by method 2, vt200 is assumed. If a different key mapping is preferred nu/TPU contains many predefined key mappings. The default key-map positions keys to approximate the Digital EDT editor. Refer to the SET KEYPAD commands in your reference manual to select other key mappings. It is also possible for you to create a user-defined key mapping. VERIFIER PHASE 4 Problems using specific keys When the help keypad is displayed, pressing a key will display a short description of the function assigned to that key. The description of a highlighted function is displayed by pressing the GOLD key then the key of interest. If all the keys show the proper help description, go to Phase 5. If a whole group of keys do not work, refer to your machine- specific installation instructions. If using a windowed environment, refer to the X Window customization instructions. If pressing a key causes the nu/TPU session to be terminated: The Control-Z (and sometimes F10) is predefined to be exit. The Control-Z is also assumed to be tied to the STTY SWITCH or SUSP key. The following commands sets Control-Z to its assumed behavior. stty switch ^Z or stty susp ^Z nu/TPU provides an escape hatch for special cases. Hitting the interrupt key twice aborts the current nu/TPU session. No attempt is made to save any work. Normally the interrupt key is assigned to Control-C, but sometimes the backspace key is used. The following command sets Control-C to its assumed behavior. stty intr ^C Some or all video attributes do not work. Check that your system supports attributes like BLINK, UNDERLINE, and BOLD. Almost all systems support REVERSE, and some substitute REVERSE when others are requested. To change the video attributes used for the FIND and SEARCH operations, set the si$x_found_highlighting and si$x_select_highlighting variables to the desired attribute value. License lock delays are time consuming. Under no circumstances will data be lost while completing a license verification, but delays can be up to 5 minutes under some circumstances. User message about license limit exceeded. Either nu/TPU is at its session limit or one or more nu/TPU sessions were halted prematurely by improper terminal settings, system crashes, program aborts, or other similar failures. Premature system terminations do not return license locks to the available pool. License locks lost to terminated sessions can be recovered by running the makeseri program. This program is located in the same directory as the nu/TPU executable. Note: running makeseri will cause license lock delays for currently active users. The following commands will reset all the license locks. # cd /usr/local/nu_tpu/??? Where ??? is the OS directory # makeseri -reset -------------------------------------------------------------------------- nu/TPU Support Policies a/Soft Development's nu/TPU support policy includes user hot-line support and upgrades to new versions of nu/TPU. To be eligible for these services, we must receive your completed nu/TPU registration card. For the first year after receiving nu/TPU, you can take advantage of our free hot-line support to help you resolve any processing problems. For questions on more complex nu/TPU interface extensions, we may request a diskette copy of your code in order to provide you with the most thorough and accurate support possible. If a new release of nu/TPU is made available within 90 days of your purchase, you will receive the new release free of charge. You must have registered your original version of nu/TPU with a/Soft to receive the free update. Our technical support staff can be reached at: MAIL : User Services a/Soft Development, Inc. One Executive Park Drive Bedford, NH 03110 VOICE : (603)666-6699 FAX : (603)666-6460 -------------------------------------------------------------------------- Changes in nu/TPU from v3 to v4 - New simple interface (SI) with sources. - Improved windows integration. - Screen updating and larger file performance improvements. - New UNDO built in function, allows unlimited undo. - New CHOICE builtin in function. - Improved process control. - Buffer names are no longer forced to uppercase. - The evebox section file (VMS 5.4 and later EVE) is no longer supported. This section file is superceded by the new SI section file. - The only section file that can be used with the Motif version of nu/TPU is si.ini - VI support is no longer separate, but integrated in the SI interface. - BOX range type added. - BACKUPS qualifier added to nu_tpu.def. Allows user to control number of backup copies to be retained. Range 0-99 copies. - Keys program to aid in the customization of keyboard drivers. - Window resize for character cell is added. Motif interface changes - Motif supported at the TPU built-in level - Clipboard input allowed - Interactive menu builder - Definable status line with buttons - Vertical and horizontal scroll bars for each window -------------------------------------------------------------------------- Simple Interface (SI) usage Version 4 begins the release the of the a/Soft (S)imple (I)nterface. Complete sources are included in the nu_tpu/source directory. You are free to make modifications and distribute those modifications to your friends and family royalty free. We would love to hear about, see, use, and/or distribute any modifications you make to the SI sources. The intent of the SI interface is to provide a smaller, faster, and less VMS dependent interface for nu/TPU customers. Instructions for extending SI are contained within the source. We hope the smaller size and modular keypad design will make the SI interface easier to enhanced than the EVE for VMS. SI interface does not support modifying the menu bar from the command line. -------------------------------------------------------------------------- nu/TPU v4.1 vs. DECTPU VMS 5.5 Differences between VMS DECTPU and nu/TPU Version 4.1: - Only the source files are compatible not the compiled section files. - File naming conventions are different. - nu/TPU does not support the following DECTPU builtin functions: get_info( buffer_variable, "journal_file/name" ) get_info( COMMAND_LINE, "character" ) get_info( COMMAND_LINE, "work_file" ) get_info( DEBUG, "procedure" ) get_info( SCREEN, "decwindows" ) get_info( window_variable, "key_map_list" ) set( KEYSTOKE_RECOVERY ) RECOVER_BUFFER - DECTPU does not support the following nu/TPU builtin functions: get_info( ENVIRONMENT, "" ) get_info( SCREEN, "term" ) get_info( SCREEN, "windows" ) get_info( SYSTEM, "box_range" ) get_info( widget_variable, "get_child", integer ) get_info( window_variable, "text_widget" ) set( INPUT_FOCUS, widget, integer ) CHOICE HELP_KEYPAD UNDO - DECTPU does not support the following nu/TPU concepts Status line button bar Buffer name case-sensitivity Video color display - ATTACH nu/TPU does not provide VMS functionality. - CALL_USER nu/TPU does not provide VMS functionality. - CONVERT return values differ, see documentation. - DELETE The definition of the current_buffer after deleting the current_buffer differ between DECTPU and nu/TPU. - DELETE( integer-value ) DECTPU sets variable referenced in argument one to UNSPECIFIED, nu/TPU the variable reference is unchanged. - FAO nu/TPU expresses numeric overflows as ****, DECTPU expresses them as the largest possible number to fit in the field. - FAO nu/TPU the width specifier is only valid for the fao immediately following specification. - GET_INFO( window, "current_row" ) & GET_INFO( window, "current_column" ) VMS/TPU only updates these values during the refresh process. nu/TPU updates these values for every buffer and/or window change. nu/TPU returns zero if the window is not visible. - LOCATE_MOUSE return values differ, see documentation. - SET( POST_KEY_PROCEDURE ) - SET( PRE_KEY_PROCEDURE ) Invalid third argument, turns off function only in DECTPU. Zero as third argument, turns off function in both. - SLEEP DECTPU allows fractional seconds, nu/TPU does not. - STR nu/TPU range value is -2,147,483,648 to +2,147,483,647. - STR(F16) & STR(DO) Under DECTPU both return "DO" Under nu/TPU both return "F16" - STR(BS_KEY) & STR(CTRL_H_KEY) Under DECTPU both return "BS_KEY" Under nu/TPU both return "CTRL_H_KEY" - DEFINE_WIDGET_CLASS No support for third parameter in nu/TPU. - Arrays and array elements can not be used as output arguments with nu/TPU. - Constants must be define before being used under nu/TPU, this restriction does not apply to DECTPU. - All statements must end with a semicolon in nu/TPU. DECTPU requires semicolons only to separate statements. - Undefined procedures cause DECTPU to step to the next statement after error handling, nu/TPU will continue with the current statement. - Error from bad argument counts to user procedures generated at run-time under DECTPU, and at compile time under nu/TPU. - Unmapping then remapping must cause a text scroll in nu/TPU. - The /nomodify command line switch does not prohibit modifing text retrived with READ_FILE later in the session under nu/TPU. - Buffers with the NO_WRITE flag set cannot be written with WRITE_FILE in nu/TPU. DECTPU only uses the NO_WRITE flag to determine writing of file at exit time. - No UIL support for builtins in nu/TPU: CREATE_WIDET SET( DRM_HIERARCHY ) SET( ICON_PIXMAP ) SET( ICONIFY_PIXMAP ) - Different time units: DECTPU uses seconds, UNIX uses milliseconds get_info( SCREEN, "time", GLOBAL_SELECT ) - DECTPU has a more extensive default global selection behavior: If no global selection routine is registered in DECTPU, it "knows" about property names "FILE_NAME", "FONT", and "LINE_NUMBER" and returns this information to asking application. nu/TPU doesn't do this to save on server memory. To get this functionality in nu/TPU, register your own global selection behavior. - HELP_MODIFIED mouse button event not supported in nu/TPU. - MARKERS and RANGES in different buffers can only be compared with the boolean operators = and <>, relative boolean operators >, >=, <, and <= return unpredictable results in nu/TPU. - SI does not provide the WPS paginate feature at the command line. - nu/TPU renames the following DECTPU keywords. EVE$_CANTCREADCL --> EVE$CANTCREASHELL EVE$_CREATESHELL --> EVE$CREATESHELL EVE$_SHELLPROMPT --> EVE$SHELLPROMPT EVE$_NODCLCMD --> EVE$NOSHELLCMD - nu/TPU adds the following keywords BACKGROUND BLACK BLUE BOL_TEXT BOX_RANGE CYAN ENVIRONMENT ESCAPE F21 - F40 FOREGROUND GREEN MAGENTA RED SIGNAL TPU$_REQUIRESWINDOWS WHITE YELLOW -------------------------------------------------------------------------- Known bugs (FCS) release November 1, 1993 GENERAL problems Replace doesn't apply the case of the original text to the new substitution text. Journal file conflicts occur when seperate 2 sessions are running in the same directory at the same time. Compile errors can cause the editor to issue memory exhausted messages and die. Possible conditions are, missing then on if, missing endif, or unmatching parenthesis. TERMINAL update problems VT100 reverse scroll puts all updates on first line of window. Silicon Graphics iris-ansi: Finding a second occurance of a string on a line matching the width of screen will cause improper screen updating. CTRL-W clears. TPUSEC.INI specific or all interface problems Select, bottom (when bottom is not shown on current screen) --> highlights "[End of File]" Show buffers: status line reports buffer name incorrectly Show system buffer: status line reports buffer name incorrectly. SELECT, then goto bottom, CUT. Does not fill window with text. SI.INI specific problems SET FIND AUTO REVERSE: Should search in forward and reverse directions, but when positioned on a previous match, searches that should change direction don't. No message is displayed and cursor does not move. MOTIF specific problems Initial geo = 220x40 (larger geometry than the screen) nu/TPU will start correctly, but when you create a new buffer, the windows doesn't stay the correct size. Setting borderWidth = bad window sizes. Scrollbar: if try to turn on, and it doesn't fit, need to return 0. MENU_POSITION set( MENU_POSITION ) doesn't move menu so that last item selected is under the cursor. get_info( MENU_POSITION ) not implemented. Global Selections need to convert a WRITE_GLOBAL_SELECT array default global selection behavior not implemented passing an integer as a global selection not implemented. MOUSE Stuff: click vs mouse down event: need to time-out. XmList callback data struct should return an array (selected positions). Resize window, split, message and prompt buffers disappear. EVE command two, one leaves empty space at the bottom of the nu/TPU window. Split 8 causes 8 redraws of the nu/TPU window. One redraws 8 times, leaves lots-O space at the bottom of the nu/TPU window and a message occurred in built-in Delete in the message window. EVE command two, the second window does not have a scroll bar. Follow by EVE command one, the scroll bar is removed from the original window. All Help information via the menu options positions the help text at the bottom of the help_buffer instead of the top part of the entry. When text is inserted from the Motif global selection via mouse button 2, only part of the data is initially visible. After any other key is struck. When editing position is not visible (over right edge) and resize, cursor moves to bottom left corner of window. Replace, button press on Search when the cursor is past EOB will insert lines up to the cursor position. Addition button presses on Search will insert one line to the end of the edit buffer. After two windows, alternating [Find] and [Do] keypresses will shrink the edit windows leaving blank space at the bottom of the nu/TPU window. SET BOX SELECTION - Box selection is not active for the first select operation after the command is issued. SET BOX PAD, BOX CUT OVER/INSERT, BOX PASTE OVER/INSERT have no affect on cutting or pasting box text. Cutting a box, text to the right always fills to the left. Inserting box text acts as a linear range paste. SET(FOREGROUND) and SET(BACKGROUND) do not update status line color nor menu popups.