COSmanager/User Guide/Appendices

From Documentation

Revision as of 02:35, 26 April 2006

Appendix A — the COSmanager User Interface

The user interface to all COSmanager applications is provided through a series of reusable software tools known collectively as The Functional Toolset. Both graphical (GUI) and character (CUI) mode interfaces are provided.

The GUI mode features a Motif-style ‘look and feel’. It can be used from an X terminal, or a PC running Windows 3.11, Windows 95 or Windows NT, without the need for X emulation software.

The CUI mode is intended for users who access COSmanager from a character terminal or via terminal emulation from a PC. It features a full-screen interface with support for function keys and pop-up windows.

Keyboard traversal in the GUI interface is consistent with the CUI version. This allows users to swap between X displays, Windows PCs, and character terminals, with minimal retraining and without loss of productivity.

This appendix introduces the major components of The Functional Toolset, including examples of both GUI and character mode screens.

The Functional Toolset

The key components of the user interface are:

Methtool

provides a console through which you can perform actions or methods on selected items.

Prompt

‘fill in the form’ data entry.

Scroll/Keep

browse through and print the output from a program.

Menu

hierarchical menu management system.

Choose/Order

choose a data item from a list.

Search

search for a character string or pattern.

Each of these tools presents a similar user interface in both graphical (GUI) and character (CUI) modes, though some extra facilities are available in the GUI version.

The standard features in the character user interface (CUI) are:

• A title bar showing the customer name and the tool or menu name
• A row of eight function key labels on the bottom line of the screen, with F1 being Help, F3 Exit, and F8 Accept. Other function keys are tool-specific
• A message area on the second bottom line, for showing error or informative messages.

Some features of the GUI are:

• Motif-style ‘look and feel’
• compatibility with the function key buttons in the CUI
• a toolbar providing shortcuts to common actions.

Detailed reference information is contained in the manual pages for the interface tools. See the COSmanager Reference Guide.

Methtool

methtool allows you to select actions or methods from a menu bar to perform on data base tables or items selected from a list.

Function keys available within methtool are:

GUI Notes

The menu bar contains the COSmanager pulldown, Help button, and any pulldowns specific to this methtool. The COSmanager pulldown contains Search and Print, and a number of configurable Options:

Multiple prompt

whether you can perform table maintenance operations such as Remove and Change on multiple rows at once.

Confirm actions

if selected, asks for confirmation before performing certain table maintenance operations such as Remove.

Tool tips

whether to show tool tips when the pointer is positioned over buttons on the toolbar.

Toolbar

whether to display shortcut buttons under the menu bar.

Methods which are temporarily unavailable are ‘grayed out’, for example if they require one or more items to be selected, and none have been.

The status line shows messages relating to the selected option or the last action that was performed.

Prompt

prompt is COSmanager’s data entry tool. It enables COSmanager database tables to be created and maintained via screen-based forms.

prompt allows a user to fill in the fields in a form. Each field consists of (from left to right):

• a ‘prompt’ to indicate what the field is
• a data area, in which text is entered or changed
• an optional information area, giving more details about the current value in the data area

There are several ways to enter data:

• by typing from the keyboard, or by cut-and-paste using the mouse
• by stepping through a short list of alternatives via the Select button
• by choosing from a list of options via the Choose tool

Initially, the cursor is placed at the start of the first editable field. The Help button displays help text, if available, for the active field.

If incorrect data is entered into a field, or if a mandatory field is left blank, prompt will display an error message and prevent you from advancing to the next field. You may return to a previous field, but you cannot move past the wrong field until the error is corrected.

Hidden fields are used to enter sensitive data such as a password without it being displayed on the screen. Text can not be inserted into a hidden field. If it is necessary to edit the data, clear the field and re-enter the text in full. If the Choose button is available, the required data can be selected from a pop-up window.

If the Select button is available, the user can toggle through a small number of alternatives by pressing the left or right arrow keys or the first letter of the desired option When all the required fields have been entered, press Accept to save the changes. The available function keys within prompt are:

GUI Notes

• Input fields appear recessed. Display-only fields have the same appearance as the background of the form.
• Clicking button 1 in an input field makes it the active field. prompt still performs any validations on the intervening fields, so mandatory fields cannot be bypassed.
• You can copy text between fields using your window manager’s cut and paste buttons.
• The Choose control lets you choose from a pop-up list of values.
• The Select control steps through the set of available values.
• Groups of related fields may be framed by a border.

Menu

menu implements a hierarchical menu structure based on a user’s access capabilities. The user selects an option via the keyboard or mouse.

Function keys available within menu are:

GUI Notes

• Posted menus stay on the screen until you press Exit. Cascading submenus appear to the right of the selected option, and are transient—that is, they disappear once an action is selected.
• A symbol indicates that the option will display a submenu. An ellipsis ( … ) indicates that the submenu will be a posted menu.
• Pressing button 2 over a cascading menu converts it to a posted menu. Alternatively, invoking a normally cascaded menu with button 2 will invoke it as a posted menu under the cursor.
• Pressing button 3 displays help text for the highlighted option, if available. Clicking on the box dismisses the help window.

Button bar

The COSmanager button bar is the main menu through which you launch and configure COSmanager applications. The button bar has a button for each installed application that you have access to, and a Config button through which you can configure COSmanager applications and the COSmanager framework.

The left-most button is the COSmanager pulldown, which has these options:

Manual

browse the manual pages for COSmanager commands

Remote

run COSmanager on a remote host

Shell

launch a shell with the COSmanager environment set up (not available from the COSmanager GUI Server for Windows)

About

display COSmanager version and customer name

Minimize

iconify the COSmanager button bar

Tooltips

enable/disable tooltips on the COSmanager button bar

Exit

exit the button bar

Exit All

exit all COSmanager windows launched from this button bar (except xterms and windows in another process group).

To move the button bar, middle-click and drag to the new location. Note To use the Product configuration menu you must have the Admin, Config, or Manager role in at least one application.

Scroll/Keep

scroll provides up, down, left, and right scrolling through any output text. You can search for text or patterns, and print selected pages. scroll has several advantages over standard UNIX pagers:

• lines longer than 80 characters are not wrapped
• header lines and column headings are highlighted and retained as you scroll through the data
• selected pages may be sent to the printer

A > symbol under the title bar indicates that more data is held to the right of the current window. A < symbol indicates more data to the left. The scroll viewing ‘window’ is moved by:

• using the Page Up and Page Down keys to scroll up or down
• using the arrow keys to move left and right
• using the Search and Go to buttons.

The available function keys within scroll are:

GUI Notes

The GUI scroll does not have the concept of a standard page size or page number. Instead, the vertical scroll bar shows the current position.

Keep

keep is a real-time version of scroll. keep tracks the output from a running command, displaying new data as it is generated.

The available function keys within keep are:

GUI Notes

The GUI keep retains approximately the last ten windows of output. If the current end of data is not visible, keep keeps the view over the rows that are currently displayed. To resume tracking the end of data, press Follow.

Choose/Order

choose is typically used to select one or more rows of data for further action, or in a prompt form to select from a list of valid values for a field.

The current item is indicated by a > symbol, and is selected by pressing the Return key or Accept. You can move through the list in the same way as for scroll:

• using the Up or Down Arrow keys or the space bar
• pressing the first letter of the item you want to choose
• using Search to search for rows containing a text string or pattern.

In some cases, a multiple line choose facility is available. This enables more than one row to be selected using choose. If the multiple choose facility is available, the Select/DeSelect button will be enabled.

The available function keys within choose are:

GUI Notes

Some choose screens allow multiple rows to be selected. The following mouse actions are available in the multiple choose facility: For references to mouse actions, B1 is the primary button (usually the left button).

On UNIX B2 is usually the middle button. On Windows B2 is usually the right button.

Order

order is a version of choose that lets you reorder a items in a list. You move the cursor to a row and press PickUp. The selected row is highlighted and the label of the PickUp button changes to PutDown. Next, move the cursor to the new location (using the scroll keys or Search if necessary). Press PutDown to put the row down.

If the selected row is being moved down the list, it will be put down below the current pointer position. If it is being moved up the list, it will be put down above the current pointer position.

Press Accept to save the items in their new order. Press Exit to exit without saving changes to the order of the rows.

The available function keys within order are:

GUI Notes

If both the old and new locations are visible in the same window you can click and drag the row to its new location. To cancel a selection, press PutDown or click again on the selected row.

Search

The search tool allows you to find occurrences of a character string or pattern in a scroll box (e.g. a scroll, choose or order window). Enter the string or pattern to be searched for. If a matching row is found it is indicated by the > cursor. To repeat the search, press Search twice. Searching starts from the first row of data in the current window. If the search string is not found before the end of the data, the search wraps around to the start. ‘Pattern not found’ indicates that the search string was not found anywhere in the data.

GUI Notes

GUI search includes two options that affect how the search is performed.

• If Ignore case is selected, the string that was entered will match either upper-case or lower-case numbers.
• If Regular expression is selected, the search string can be an arbitrary regular expression (see (ed(1)). If it is not selected, search does a simple string comparison with no pattern matching.

If the search string is found, the row is highlighted and the label on the Search button changes to Next, as shown in Figure 51. To search for the next occurrence, press Next. If Search reaches the end of the data without finding the string, the label Next changes to Restart. Pressing Restart resumes the search from the start of the data.

Once you have found the line you were searching for, press Accept to remove the search window. To cancel the search and return to the original location in the scroll box, press Cancel.

The available function keys within the GUI version of search are:

Appendix B—Terminal Support

COSmanager uses the UNIX Terminfo facility to support different character terminal types. Terminfo is a database of the features and capabilities of various terminals and printers that may be used with UNIX systems. These features are not always implemented consistently or correctly in the standard Terminfo definitions. COSmanager includes tools to check and correct Terminfo definitions for character terminals and PC terminal emulators. We recommend that you check all the Terminfo definitions for any terminals that you will use to access COSmanager. This appendix shows you how to: • use ticheck to test alternate characters, video attributes, function keys, cursor movement keys, and tab stops and margins • use ticonfig to rebuild a Terminfo definition • troubleshoot common problems. 130 Appendix B—Terminal Support How to Check a Terminfo Definition To check a Terminfo definition, use the ticheck command. Pay particular attention to the function keys (F1 through F8), and the Page Down and Page Up keys. It is common for these keys to need configuring, especially for terminal emulators and terminals with programmable function keys. If the function keys are not recognized by ticheck, use the ticonfig command to rebuild your Terminfo definition to recognize the sequences sent by your terminal. To check a terminal definition 1. Use ticheck to check the Terminfo definition for your current terminal. ticheck verifies that all the graphics characters and video attributes used by COSmanager display correctly, and that function keys, cursor-movement keys and editing keys are recognized. Note if there is already a definition for this terminal in your current directory, you should first save a copy of it. 2. If necessary, run ticonfig to rebuild the Terminfo function key definitions for the current terminal. 3. If you have run ticonfig, then run the tic command to compile your new definition for the current terminal. Caution you may affect other users if your TERMINFO environment variable is not set or is set to a public directory. 4. Repeat step 1 to confirm that you have correctly configured the function key definitions for your current terminal. If need be, repeat steps 2 and 3 and rerun ticheck until they work correctly. 5. Repeat the above for each different terminal type on which you wish to run COSmanager. The following sections contain detailed descriptions of how to check and configure your terminal definition. Appendix B—Terminal Support 131 Checking Your Terminal Definition Enter ticheck at the UNIX command line to check the definition for your current terminal. You should see a screen that looks similar to this: Figure 52 — ticheck: Checking your terminal definition If the screen doesn’t look like this, or if it is garbled, then your terminal type may be incorrectly specified. Echo the TERM environment variable to see whether it is set correctly for your terminal. For example, on a VT220-compatible terminal you should see something like the following: If the TERM variable appears to be correct, it is possible that the Terminfo definition is wrong. If this is the case then you will need help from someone knowledgeable in the Terminfo facility. If all is well, the top line of the ticheck screen tells you the terminal’s name and description. The rest of the screen is divided into four regions: • the alternate character set region $ echo $TERM vt220 132 Appendix B—Terminal Support • the character attribute region • the tab stop and margin check region • the function key checking region. The following sections describe how each of these may be interpreted. Checking the alternate character set The alternate character set (ACS) comprises line drawing and other special characters (such as arrows and blocks). The ACS region of the ticheck screen is used to check the terminal’s support for ACS characters. The left of this region shows the arrow and block characters. If your terminal supports special characters they will be drawn here. The characters in brackets are the Terminfo symbols used to identify the graphics characters. In the middle of this region are the line-drawing characters. If the terminal is configured properly, a box with a cross in the middle is drawn. If your terminal does not support line-drawing characters, the box will be made up of – and | characters, with + characters in the corners. On the right of this region are the Terminfo characters used to represent each of the line drawing characters. Checking character attributes Character attributes are used to enhance the visual effect of COSmanager screens. The character attribute region of the ticheck screen is used to check the terminal’s support for the four primary attributes used by COSmanager: • bold (B) • reverse (R) • underline (U) • blinking. The character attribute region shows all combinations of character attributes except blinking as a table with two rows and four columns. Each table entry has three charcosmos. Appendix B—Terminal Support 133 acters, each representing an on/off switch for an attribute. The first character is “U” for underline, the second is “R” for reverse video and the third is “B” for bold. As an example, the second column in the second row is U-B, indicating that both underline and bold are turned on but not reverse video. Not all terminals can support all these attributes, and some cannot support all combinations. For example, some PC-based terminal emulators are unable to support the ‘underline’ attribute due to limitations of PC video interfaces. Often colors can be used to differentiate between attributes. See Terminfo Technical Details on page 139 for more information on configuring Terminfo definitions. Checking Tab-stops and margin settings Tab stops are used by COSmanager to align text on the screen. If the tab stops are not correctly set, then COSmanager screens will not appear correct. The lower line in the tab-stop region is a ruler with a tick at every tenth character. If tab-stops are set correctly, the line above the ruler should have a number above each ruler tick. An “L” is drawn at the left end of the ruler and an “R” at the right end. Above the “R” there should be drawn two more. If this is not correctly displayed, then the “auto-margin” features of the Terminfo are incorrect. The “L” and “R” characters are all drawn in bold. If other characters in the tab-stop region are bold, then there is a problem with the Terminfo setup. Checking function keys COSmanager uses a terminal’s keypad and function keys to speed access to various facilities. You use the function key region of the ticheck screen to check whether the Terminfo definition recognizes your terminal’s key definitions. To test your keys, push each of the following and note the response from ticheck: • function keys 1-8 • page up and page down 134 Appendix B—Terminal Support • home and end • insert and delete • clear line. If any of these keys are not recognized, read the next section on configuring function keys. Appendix B—Terminal Support 135 How To Configure Function Keys Typically, the only change required to the terminal definition is make it recognize the function key sequences sent by your terminal. This is done by logging in to the COSmanager account and running the ticonfig command. ticonfig reads the current Terminfo definition, prompts you to press each function key and keypad key in turn, and then writes a new Terminfo definition modified to recognize the key sequences. Note When configuring Terminfo support for COSmanager use the COSmanager user account. Before running ticonfig you should make sure that your terminal is sending the default terminal sequences for your terminal type. One way to check this is to use the cat -v command to display each function key in turn. For example, if you run cat -v and press F1 through F4, then ^D (ctrl-d) to exit cat, you will see something like the following: If you are not sure, then it may be possible to reset or reprogram the terminal’s function key sequences. You will need to refer to the terminal manufacturer’s manual for more information. When you run ticonfig, you should see a screen similar to the following: $ cat -v ^[OP ^[OQ ^[OR ^[OS ^D $ Terminfo generator Hit "q" at any time to quit You are modifying the terminfo description for terminal type "xterm". If this is not the case, please enter its name: 136 Appendix B—Terminal Support ticonfig uses the current value of the TERM variable for the name of the terminal type you are creating. If you do not like this choice, then enter another name. In the following examples we will use the name myterm. ticonfig uses this name, with an extension of .ti, to create a Terminfo definition file in the current directory – e.g. myterm.ti. If this file already exists, ticonfig issues a warning and allows you to give another name for this definition. If the file does not exist, ticonfig prompts for the name of an existing Terminfo definition. This is used to provide the basic Terminfo functions. ticonfig displays the current terminal description and allows you to change it. Once you have done this you can go on to press each function key in response to the prompt from ticonfig. After you have hit the key, ticonfig will show the key sequence sent by your terminal. Note You must wait for ticonfig to prompt for each key before pressing it. File myterm.ti doesn't exist. It should be created by copying another terminal's definition. Enter the terminal type to use (default xterm): The terminal description is currently: xterm terminal emulator Do you want to change this description? (y/n) y Enter the new description Appendix B—Terminal Support 137 This information is used to create the new Terminfo definition. You can abort this process at any stage by typing q. Caution You may affect other users if your TERMINFO environment variable is not set or is set to a public directory. In response to the following questions, hit RETURN if you don't have that key, or to take the default value. If you make a mistake, please quit (q) and start again. Please hit the F1 key: \E[11~ Please hit the F2 key: \E[12~ Please hit the F3 key: \E[13~ Please hit the F4 key: \E[14~ Please hit the F5 key: \E[15~ Please hit the F6 key: \E[17~ Please hit the F7 key: \E[18~ Please hit the F8 key: \E[19~ Please hit the F9 key: \E[20~ Please hit the F10 key: \E[21~ Do you have standard function key labels (i.e. F1, F2 etc.)? Yes Please hit the UP ARROW key: \E[A Please hit the DOWN ARROW key: \E[B Please hit the LEFT ARROW key: \E[D Please hit the RIGHT ARROW key: \E[C Please hit the NEXT PAGE/SCROLL DOWN key: \E[6~ Please hit the PREVIOUS PAGE/SCROLL UP key: \E[5~ Please hit the HOME key: \E[^@ Please hit the BACKSPACE key: \b Please hit the BACK/REVERSE TAB key: <none> Please hit the INSERT key: \E[2~ Please hit the DELETE CHARACTER key: ^? Please hit the CLEAR TO END OF LINE key: <none> Please hit the END key: \E[^@ Please hit the ENTER key: <none> Terminfo generation complete. 138 Appendix B—Terminal Support The Terminfo definition file has now been created. Before you can use this new definition it must be compiled. ticonfig will ask if you wish to compile the definition. We suggest that you let ticonfig do this. Once the definition is compiled you can check the definition using ticheck. Do you want to compile the terminfo entry now? (y/n) y You can test the terminal using "ticheck". Make sure you set your TERM variable to "myterm" first. Appendix B—Terminal Support 139 Terminfo Technical Details All COSmanager screen handling is performed through a set of user interface tools called The Functional Toolset. This chapter will help you to write Terminfo definitions for use with COSmanager applications. It presumes that you are reasonably familiar with the UNIX Terminfo and Curses facilities. Although each tool in The Functional Toolset is a separate program, all the tools present a consistent ‘look and feel’. All interface tools use the UNIX Curses facility to perform screen management on character terminals and terminal emulators, resulting in optimized screen updates. Curses uses the UNIX Terminfo database to look up the capabilities of the user’s terminal. The following Terminfo facilities are used by The Functional Toolset: • alternate character sets • character attributes • function key definitions • keypad support. If you are about to modify an existing Terminfo definition, you should read How to Check a Terminfo Definition on page 130. This describes how to use the ticheck command to verify that an existing terminal definition correctly handles the above facilities. If you are writing a new definition, or if your existing definition does not work, you should first refer to a good Curses or Terminfo reference to set up the basic definition. In particular, you will need to ensure that the cursor motion sequences are correctly specified. Once this is done, you can proceed to add support for the additional facilities used by The Functional Toolset. Alternate character set The alternate character set is supported via several Terminfo variables, shown in the following table. Note that enacs is not needed on all terminals, though it usually is on DEC VT compatible terminals. 140 Appendix B—Terminal Support Note also that many definitions, particularly for the VT series, fail to include the rmacs character in the sgr0 definition. If the terminal is left in alternate character set mode when you exit from a COSmanager application, this may be the problem Character attributes The bold, reverse, blink, and underline character attributes are specified through the following Terminfo variables: Capname Description acsc Graphic charset pairs smacs Start alternate character set mode rmacs End alternate character set mode enacs Enable alternate character set sgr Set graphics rendition. Attribute #9 is the alternate character set attribute. sgr0 Turn off all attributes Capname Description smso Start standout mode rmso End standout mode smul Start underline mode rmul End underline mode bold Start bold mode blink Start blinking mode rev Start reverse video mode sgr Set graphics rendition (set video attributes) sgr0 Turn off all attributes Appendix B—Terminal Support 141 Terminals With Fewer Than Eight Function Keys The Functional Toolset presumes the availability of eight function keys numbered from 1 to 8. This is not the case for many older terminals, in particular DEC (Digital Equipment Corporation) terminals and compatibles. These notes are provided to help you configure Terminfo definitions to support COSmanager on terminals with few or no function keys. VT100-compatible terminals The VT100 only supports 4 function keys, labelled PF1 to PF4. Typically, VT100 or compatible terminals provide additional keys (which may be programmable). If available, these should be used. If you have a genuine VT100, it is possible to simulate additional keys by using PF1 followed by the keys 1 through 8. For example, f1 would be PF1 1, f2 would be PF1 2, and so on through to f8 (which would be PF1 8). There is a potential problem with this scheme. On some UNIX versions you must press the numeric key within one second, or the curses(3) library will interprets the PF1 separately and return an invalid character to the program. You can overcome this by setting the NOTIMEOUT variable. Refer to Intermittent function keys on page 146 for more information. The following is a fragment from a VT100 Terminfo definition that implements such a function key scheme. The lf1 through to lf8 definitions specify the labels for each function key. These are used by the confirm program when showing function key templates. If these are omitted from the Terminfo definition they will default to f1 through f8. kf1=\EOP1, lf1=PF1 1, kf2=\EOP1, lf2=PF1 2, kf3=\EOP3, lf3=PF1 3, kf4=\EOP4, lf4=PF1 4, kf5=\EOP5, lf5=PF1 5, kf6=\EOP6, lf6=PF1 6, kf7=\EOP7, lf7=PF1 7, kf8=\EOP8, lf8=PF1 8, 142 Appendix B—Terminal Support VT200-Compatible Terminals The VT200 function key scheme is less than ideal for COSmanager. PF1 to PF4 still exist (perhaps to maintain upward compatibility with the VT100 series), but the VT200 series also have keys F1 to F20. Unfortunately, F1 to F5 are reserved and not programmable (for example, F3 is the setup key for the terminal) and so can’t be used for COSmanager. One scheme that may be used to overcome this is to use PF1 through PF4 for f1 through f4, and then use the four function keys above the PF keys (f17 through f20) for f5 through f8. The following is a fragment from a VT200 Terminfo definition that implements such a function key scheme. Generic Function Key Definitions It is possible to construct a Terminfo definition that uses a generic key sequence to specify function keys. The COSmanager framework includes such a definition for an ANSI 3.64-compatible terminal (FSansi.ti). This Terminfo definition should be used as an example if you need to support a terminal that does not have function keys. kf1=\EOP, lf1=PF1, kf2=\EOQ, lf2=PF2, kf3=\EOR, lf3=PF2, kf4=\EOS, lf4=PF2, kf5=\E[31~, lf5=f17, kf6=\E[32~, lf6=f18, kf7=\E[33~, lf7=f19, kf8=\E[34~, lf8=f20, Appendix B—Terminal Support 143 The f1 through f8 keys are represented by ESC 1 through ESC 8, and the page forward/page backward keys are represented by ctrl-f and ctrl-b respectively. Keypad Keys The Functional Toolset can use several of the keys available on the keypads of modern terminals, as shown in the following table. FSansi|simplistic ansi with 8 Fkeys, am, xon, cols#80, lines#24, bel=^G, blink=\E[5m, bold=\E[1m, clear=\E[H\E[J, cr=\r, cub1=\b, cud1=\n, cuf1=\E[C, cup=\E[%i%p1%d;%p2%dH, cuu1=\E[A, dch1=\E[P, dl1=\E[M, ed=\E[J, el=\E[K, home=\E[H, ht=\t, hts=\EH, ich1=\E[@, il1=\E[L, ind=\n, kbs=\b, kcub1=\E[D, kcud1=\E[B, kcuf1=\E[C, kcuu1=\E[A, khome=\E[H, rev=\E[7m, rmso=\E[m, rmul=\E[m, sgr=\E[%?%p1%t7;%;%?%p2%t4;%;%?%p3%t7;%;%?%p4%t5;%;%?%p6%t 1;%;m, sgr0=\E[0m, smso=\E[7m, smul=\E[4m, kf1=\E1, kf2=\E2, kf3=\E3, kf4=\E4, kf5=\E5, kf6=\E6, kf7=\E7, kf8=\E8, knp=^f, kpp=^b, 144 Appendix B—Terminal Support Note not all the keypad definitions are required—some only give more convenient access to facilities provided by existing function keys. Those are marked with † are optional. The smkx/rmkx will only be required if a terminal has separate keypad and application modes, such as DEC terminals Capname Description smkx put the terminal in keypad transmit mode rmkx exit from keypad transmit mode kcub1 cursor left (left arrow) kcud1 cursor down (down arrow) kcuf1 cursor forward (right arrow) kcuu1 cursor up (up arrow) kbs backspace key† khome home key† knp next page (page down) kpp previous page (page up) kent enter key† kcbt back tab key† kcan cancel key† khlp help key† kich1 insert character† kdch1 delete character† kel clear (to end of) line† krfr refresh key† Appendix B—Terminal Support 145 Troubleshooting Data loss Sometime you may notice menu headings overwriting previous ones, menu options or prompt fields not aligning, or menu hierarchy diagrams appearing to lose characters. If this happens randomly, your terminal flow control may not be set up correctly. However, if it happens consistently, it may be that the terminal is not handling TAB characters correctly. This is often the case when using DEC terminals. To test this out, try disabling tabs using the following UNIX command: stty -tabs Slow scrolling Sometimes, especially when scrolling left or right in scroll, you may notice that the time to redraw the screen is longer than would be expected, given the line speed between your terminal and the host computer. If this occurs, it may be because your terminal is relatively slow at processing parameterized commands. A typical example is the ‘delete character’ sequences. The dch variable specifies the escape sequence to delete multiple characters. The dch1 variable deletes a single character. On some terminals such as the Liberty ‘Freedom 1’, it is much quicker for the terminal to process a series of dch1 sequences than the equivalent single dch sequence with many parameters. To test this, comment out the parameterized variable, after making sure the equivalent single variable is defined correctly. Then go into COSmanager and display a table, then shift right and left several times. These considerations may also apply to the equivalent ‘insert character’ sequences, ich and ich1. 146 Appendix B—Terminal Support Intermittent function keys If your function keys only work intermittently, and your terminal is connected to the computer through a network, it is possible that the network could introduce delays. This is particularly noticeable if you are connecting through more than one network through a gateway. The problem may be that the network is breaking the function key sequence into multiple packets, and Curses tries to recognize the individual parts as function key sequences. For example, you are connected from a PC on a Novell network, through a gateway into a UNIX host. You press F1. The code sent would be: \E[OP Note this does not occur on all versions of UNIX When the start of a function key sequence is recognized, Curses sets a one second timer and tries to read the next character (the timer is reset after each character is read). When the characters read match a key sequence, Curses informs The Functional Toolset the name of the function key that was pressed. If the timer expires before a complete key sequence is matched, Curses assumes that an invalid key sequence was pressed. In our example, if the network splits the key sequence across two packets, and there is a delay between the packets, then Curses will see two sequences, neither of which matches a known function key. Caution If NOTIMEOUT is set and the user presses the ESC key, COSmanager will wait indefinitely until another character is pressed. To overcome this you can set the NOTIMEOUT environment variable to ‘true’. This tells The Functional Toolset not to time out after one second if it gets an incomplete key sequence. This forces Curses to wait for more characters until it either can match a sequence or fails to match any. You can set NOTIMEOUT in a number of locations: • in the system-wide profile (/etc/profile or /etc/login) Appendix B—Terminal Support 147 • in the affected user’s individual profile (.profile or .login) • in the COSmanager global parameters (see page 89) ‘Magic cookie glitch” COSmanager applications will not run optimally on terminals with the “magic cookie glitch.” These terminals leave extra blank characters on the screen before and after video attribute changes such as reverse video or underlining). Examples of these types of screens are Wyse 50 and older Televideo. Incorrect vendor-supplied Terminfo definitions COSmanager requires at least eight function keys to run correctly, and uses many extended Terminfo facilities. We have found that some Terminfo definitions distributed with UNIX systems to be inadequate. Therefore, several common Terminfo entries have been supplied. These can be found in the $FShome/lib/terminfo directory. By default, the environment setup command for the COSmanager account ($FShome/.profile) refers to these Terminfo entries.

Appendix C—COSmanager GUI Server for Windows 149

Appendix C — COSmanager GUI Server for Windows

The COSmanager GUI Server for Windows provides a Graphical User Interface to COSmanager Software running on a remote host from a PC or workstation running Microsoft Windows NT, Windows 95, or Windows 3.11. 150 Appendix C—COSmanager GUI Server for Windows Installing the COSmanager GUI Server for Windows This topic explains how to install and uninstall the COSmanager GUI Server for Windows. There is one procedure for Windows 95 and Windows NT 4.0, and another procedure for Windows 3.11 and Windows NT 3.51. Caution If a version of the COSmanager GUI Server is currently installed, it must be uninstalled before installing or re-installing another version. Once the COSmanager GUI Server software has been installed you can run it. For instructions on how to run the COSmanager GUI Server, see Running the COSMOS GUI Server for Windows on page 158. System Requirements The COSmanager GUI Server for Windows requires the following: Note Before you can use the COSmanager GUI Server you must run the setup program on disk 1. You can not just copy the files from the floppy disk onto your hard disk. Hardware 5Mb of hard disk space 8Mb Memory required 16Mb Memory recommended Software Windows NT 3.51, Windows NT 4.00, Windows 95 or Windows 3.11 win32s version 1.30 required on Windows 3.11 TCP/IP Appendix C—COSmanager GUI Server for Windows 151 Installing on Windows 95 or Windows NT 4.0 Before installing the COSmanager GUI Server check System Requirements on page 150 to ensure your system has the required resources. The installation procedure is as follows: 1. Start Windows. 2. Select Settings > Control Panel from the Start button. 3. Open the “Add/Remove Programs” icon. On the Install/Uninstall tab, press Install. 4. Place the ‘COSmanager GUI Server for Windows 95/NT’ disk 1 in the floppy drive. These instructions assume that the floppy drive is drive A. Press Next to continue. 5. The command should be A:\SETUP.EXE Press Finish to run the Setup program. 6. The welcome screen is displayed. If at any time you wish to exit from the installation, press the Cancel button. Press Next to continue. 7. Enter your user name and company name. This information is used for display purposes. Press Next to continue. 8. Choose the destination directory. To change the default directory, press the Browse button and select a new directory. Press Next to continue. 9. Setup asks where you want the menu entries to be placed in the Program Menu hierarchy. Press Next to continue. 10. Setup displays the details you have entered so far. To change any of the details press Back, otherwise press Next to continue. Setup unpacks the necessary files and places them in the destination directory. You may be prompted to insert other disks as necessary. When Setup has completed, press Finish to exit the installation procedure. 152 Appendix C—COSmanager GUI Server for Windows Uninstalling on Windows 95 or Windows NT 4.0 1. Start Windows. 2. Select Settings > Control Panel from the Start button. The control panel program group should now be displayed. 3. Select the “Add/Remove Programs” icon and if necessary click on the Install/Uninstall tab to display this dialog: Figure 53 — Add/Remove Programs Properties 4. Select the “COSmanager GUI Server” entry from the “Add/Remove” list and press the Add/Remove button. 5. Press Yes to confirm that you want to remove the COSmanager GUI Server from your system. Uninstall removes: Appendix C—COSmanager GUI Server for Windows 153 • all files in and under the COSmanager GUI Server home directory • entries in the Windows Registry • menu entries in the program menu hierarchy When Uninstall has completed, press OK to exit the uninstall procedure. Installing on Windows 3.11 or Windows NT 3.51 Before installing the COSmanager GUI Server check the System Requirements to ensure your system has the required resources. The installation procedure is as follows: 1. Start Windows. 2. Place COSmanager GUI Server for Windows 3.11 diskette 1 in the floppy drive. These instructions assume that the floppy drive is drive A. 3. Make the Program Manager the active window. 4. Select File > Run to open the File Run dialog box. 5. Enter the command to run the COSmanager GUI Server setup program. If the disk is in floppy drive A, type: a:setup If the disk is in floppy drive B, type: b:setup Press the OK button (or press Enter). 6. The welcome screen is displayed. If at any time you wish to exit from the installation, press the Cancel button. Press Next to continue. 7. Enter your user name and company name. This information is used for display purposes. Press Next to continue. 8. Choose the destination directory. To change the default directory, press the Browse button and select a new directory. Press Next to continue. 9. Setup asks in which Program Manager group to add the icons for the COSmanager GUI Server. Press Next to continue. 154 Appendix C—COSmanager GUI Server for Windows Setup unpacks the necessary files and places them in the destination directory. Setup may prompt you to insert other disks as necessary. 10. Installation Complete. Instructions for running the COSmanager GUI Server will be displayed at this point. Press OK to exit the installation procedure. Uninstalling on Windows 3.11 or Windows NT 3.51 1. Start Windows. 2. Open the COSmanager program group and double-click the UnInstall icon. 3. Press OK to confirm that you want to remove the COSmanager GUI Server from your system. Uninstall removes: • all files in and under the COSmanager GUI Server home directory • the COSmanager program group and items. When Uninstall has completed, press OK to exit the uninstall procedure. Appendix C—COSmanager GUI Server for Windows 155 Configuring the COSmanager GUI Server for Windows To start the COSmanager GUI Server, double-click on the COSmanager icon. Figure 54 — GUI Server (Windows 95/NT) main window From this window you can: • exit from the COSmanager GUI Server • configure the standard or advanced settings • establish a connection to run COSmanager on the remote host To Configure the Standard Settings 1. Press the Settings button. Figure 55 — Standard settings dialog 156 Appendix C—COSmanager GUI Server for Windows 2. Enter or set the following fields: Local Computer The name of the local Windows PC on which the COSmanager application will be displayed. IP Address The IP address of the local Windows PC. COSmanager HostThe name of the remote UNIX host on which the COSmanager application will run. Connect on startup Select this check box to display the Connection Details dialog when the COSmanager icon is launched. The default settings for user name and COSmanager host will be used. Change COSmanager host Select this check box to show the COSmanager Host field in the Connection Details dialog. This means that the user can change the host name and try to connect to a different host from the default. If the check box is not selected, the user can only connect to the default host. Press Accept to save the new settings. To Configure the Advanced Settings 1. Press the Advanced button. The Port number is determined automatically (see step 7 on page 161 for details). The Default command is the command used to start COSmanager on the remote host. It can’t be edited, but you can override it by entering a Custom command. 2. Enter or set the following fields: Appendix C—COSmanager GUI Server for Windows 157 Figure 56 — Advanced settings dialog Custom Command Enter a command here to override the Default command. Example: if ksh and the ~COSmanager construct are not available on your UNIX hosts, you will need to use a different shell and obtain the COSmanager home directory by another means, such as: Appended Arguments Optional arguments passed to the cos command on the remote host. Default User The default user name in the Connection Details dialog box. If this is not set the Windows login name will be used. Debug log Select this check box to open a Tk console. You can use this to show debugging information (see Debugging on page 163). Press Accept to save the new settings. `grep COSmanager /etc/passwd | cut -d: -f6`/bin/cos 158 Appendix C—COSmanager GUI Server for Windows Running the COSmanager GUI Server for Windows Note If you are running the COSmanager GUI Server for the first time, before you can establish a connection you need to specify the COSmanager Host in the Standard Settings dialog. See Configuring the COSMOS GUI Server for Windows on page 155. To run COSmanager 1. To start the COSmanager GUI Server, double-click on the COSmanager icon. 2. Press the Connect button. Figure 57 — Connection details 3. Fill in your user name and password on the remote host and press Accept. This will start COSmanager on the remote machine talking to the locally running COSmanager GUI Server, and display the COSmanager button bar on your Windows desktop. Figure 58 — COSmanager button bar Appendix C—COSmanager GUI Server for Windows 159 Note The Shell escape option is not available from the COSmanager GUI Server for Windows. To exit COSmanager 1. To exit the COSmanager button bar on the remote host, click on the COSmanager button and select Exit. This will leave the COSmanager GUI Server running on the local PC. To exit the COSmanager button bar on the remote host and exit the COSmanager GUI Server on the local PC, click on the COSmanager button and select Exit All. Alternatively, you can press Exit on the GUI Server main window. Figure 59 — Exiting the COSmanager GUI Server Exit COSmanager on remote host Exit COSmanager on remote host and COSmanager GUI Server on local host 160 Appendix C—COSmanager GUI Server for Windows Technical Notes This topic contains technical details as to the operation of the COSmanager GUI Server for Windows. The basic function of the COSmanager GUI Server is to load the cos.exe process, establish a socket connection, and start COSmanager running on the remote host. Running the COSmanager GUI Server The COSmanager GUI Server is invoked by running the cos.exe executable. When you run COSmanager through the COSmanager GUI Server for Windows the following steps are performed: 1. Establish the location of the COSmanager GUI Server software. • If the GUI_HOME variable is set, COSmanager looks in the directory it points to. If it contains bin/cos.exe, GUI_HOME is left unchanged. • If GUI_HOME is not set, COSmanager looks in the current working directory. If it contains bin/cos.exe, GUI_HOME is set to the current directory. If GUI_HOME can’t be determined, COSmanager will exit. 2. Set environment variables: TCL_LIBRARY=$GUI_HOME\lib\tcl7.6 TK_LIBRARY=$GUI_HOME\lib\tk4.2 ICON_DIR=$GUI_HOME\icons Change directory to $GUI_HOME\server. 3. Look up Company Name in the Windows Registry under the following key: 4. Initialize Winsock. Windows NT/95 HKEY_LOCAL_MACHINE\SOFTWARE\Functional Software\ COSmanager GUI Server\3.2.2 Windows 3.11 HKEY_CLASSES_ROOT\SOFTWARE\Functional Software\ COSmanager GUI Server\3.2.2 Appendix C—COSmanager GUI Server for Windows 161 5. Determine default values and set environment variables. Note On connection, the remote command is called with $Arguments. Example: if the command is: cos sentinel -v 1.0 $Arguments=sentinel -v 1.0 6. Perform the standard wish (Tk windowing shell) initialization. 7. Source the startup.tcl script, which is responsible for: • initializing defaults. This includes reading COSmanager.ini. • initializing the server, including establishing a socket connection. The GUI_PORT variable contains the port number used for the socket connection. If GUI_PORT is not set, the value in COSmanager.ini is used. If GUI_PORT is not set in COSmanager.ini, the port number is automatically generated. • displaying the main window or Connection Details form. Remote Connection Remote connection involves running a command on the remote host to start the remote COSmanager software talking to the local COSmanager GUI Server. A command has been linked into FSwish to achieve this. The command rexec passes the remote command to be run to the rexecd (rexec daemon) on the remote host. Variable Description Obtained From Hostname Local host gethostname (system call) IP Address IP Address gethostbyname (system call) Username Current user’s name GetUserName (system call) Company Company name Registry lookup—see step 3 Arguments Optional arguments to cos.exe Any arguments following the cos command. 162 Appendix C—COSmanager GUI Server for Windows The syntax for the rexec command is: rexec does not wait for the remote command to complete and does not know of the success or failure of this command. When the remote command is run and after validating the user, rexec changes to the user’s home directory and establishes the user and group permissions. The command is then passed to the normal login shell of the user. Note There is also a remote command that has been linked into FSwish which does wait for the results of the command. For more details see the section on debugging. The command that is run remotely is responsible for starting the COSmanager software on the remote host and getting it to connect to the Windows socket. This is achieved by the setting of three environment variables: GUI_HOST, GUI_PORT, and DISPLAY. The default command that is run is as follows: The default command can be overridden by setting the Custom command in the Advanced Settings prompt form. If this command has been set, rexec is called with the following: The GUI_OS variable is set to the OS of the host running the COSmanager GUI Server for Windows: rexec <host> <user> <password> <command> /bin/ksh -c “DISPLAY=<ipaddress> GUI_HOST=<ipaddress> GUI_PORT=<GUI_PORT> GUI_OS=<GUI_OS> ~COSmanager/bin/cos $Arguments” DISPLAY=<host> GUI_HOST=<host> GUI_PORT=<GUI_PORT> GUI_OS=<GUI_OS> $Command $Arguments On … Windows NT 3.51 and 4.0 GUI_OS=Windows_NT Windows 95 GUI_OS=Windows_95 Windows 3.11 GUI_OS=Windows_3.11 Appendix C—COSmanager GUI Server for Windows 163 Debugging To enable debugging, turn on the Debug check box in the Advanced Settings dialog. This will display the Tk Console. The Tk Console displays debug messages and also allows you to interact with the COSmanager GUI Server, for example to display the contents of environment variables. Figure 60 — Tk Console Variables The contents of variables can be displayed by doing a set: Most of the variables used in the COSmanager GUI Server are stored in arrays. % set <variable name> 164 Appendix C—COSmanager GUI Server for Windows You can display the elements of an array by typing: Common variables include: An env array contains an element for each of the environment variables currently set. Remote Command The COSmanager GUI Server for Windows uses the rexec command to run remote commands. However rexec does not wait for the remote command to terminate, so there is no way of knowing if it was successful or of seeing any error messages. FSwish also has another command remote which does wait for the output of the remote command. This can be used for debugging purposes. Note As remote waits for the remote command to terminate, the GUI Server will ‘freeze’ until the remote command terminates. The syntax of the remote command is the same as for rexec: % array names <array> ini(Company) company name ini(Command) override command ini(GUI_PORT) setting of GUI_PORT in advanced settings ini(LocalHost) the name of the local (Windows) host ini(RemoteHost) the name of the remote COSmanager host ini(IPAddress) the IP Address of the local (Windows) host remote <host> <user> <password> <command> Appendix C—COSmanager GUI Server for Windows 165 Directory Structure and Key Files Figure 61 — COSmanager GUI Server for Windows directory structure The COSmanager home directory ($GUI_HOME) contains: COSmanager/bin contains: COSmanager/icons contains: COSmanager. ini the initialization file for the COSmanager GUI Server errors.txt an alphabetical list of error messages (see also Troubleshooting on page 167) install.txt installation notes readme.txt overview notes cos.exe the COSmanager GUI Server executable

• .dll various DLLs
• .xbm, *.xpm icon files used in COSmanager Software
• .ico COSmanager and ReadMe icons used by Windows

166 Appendix C—COSmanager GUI Server for Windows COSmanager/lib contains: COSmanager/server contains various TCL files: tcl7.6 the current TCL library tk4.2 the current Tk library defaults application defaults for fonts, colours, etc. startup.tcl initial startup TCL script tclIndex TCL index for TCL files winmain.tcl WinMain TCL class Appendix C—COSmanager GUI Server for Windows 167 Troubleshooting Connection failure Reason: Although a socket was created, the rexec command was unable to connect to that socket. Solution: No solution. COSmanager host not defined! Reason: The remote COSmanager host to connect to has not been defined. Solution: Enter the name of the remote host in the COSmanager host field in the standard settings. Couldn't find server directory Reason: This error results from a failed attempt by cos.exe to change to the server directory. Solution: Ensure that the server directory exists and is accessible and that the COSmanager GUI Server home directory is valid. Couldn't initialize winsock Reason: Before a socket connection can be made, the Windows socket API needs initializing. This error will occur if the initialization fails. Solution: Check that the TCP/IP protocol is installed and configured correctly. Couldn't set COSmanager GUI Server directory Reason: On startup the COSmanager GUI Server looks up the Windows registry to determine its home directory. If this fails it will attempt to use the current working directory. This error message will be displayed if both these attempts to set the COSmanager GUI Server home directory fail. Solutions: 1. Ensure that the current working directory is correct. 2. Set the GUI_HOME variable (in the autoexec.bat file) to point to the COSmanager GUI Server home directory, and restart Windows 168 Appendix C—COSmanager GUI Server for Windows Create socket failure Reason: A failed attempt was made to create a socket for the rexec command. Solution: Check that the TCP/IP protocol is installed and configured correctly. Error reading socket Reason: The rexec command was unable to read from the socket. Solution: No solution. Failed to open file: <file> Reason: The specified file was unable to be opened for writing. Solution: Check that the file exists and is readable. The is most likely located in the server directory. Failed to open <home directory>\COSmanager.ini Reason: The COSmanager.ini file could not be found or read. Solution: Check that the file exists and is accessible. If the file does not exist create an empty file of that name in the COSmanager GUI Server home directory. Failed to read form: <form> Reason: The specified form could not be opened. Solution: Check that the form exists and is readable. The file should be located in the server directory. Appendix C—COSmanager GUI Server for Windows 169 Fatal Error in wish Reason: Any number of run time errors will cause this message to be displayed. Solution: Possible corruption of COSmanager GUI Server software or clash with other running software. Check for existence of other dll's of the same name as those found in the COSmanager GUI Server bin directory. Try re-installing the COSmanager GUI Server software. GUIserver Error Reason: The cos.exe failed to source the startup.tcl file in the server directory. Solution: Check that the startup.tcl file exists and is accessible in the server directory. [incr Tcl] Init Error Reason: The COSmanager GUI Server failed to initialize itcl. Solution: Fatal error, software has been corrupted. Re-install COSmanager GUI Server. libfs Init Error Reason: The COSmanager GUI Server failed to initialize libfs. Solution: Fatal error, software has been corrupted. Re-install COSmanager GUI Server. Local IP Address not defined! Reason: The COSmanager GUI Server was unable to determine the IP Address for the local computer. Solution: Check that TCP/IP is correctly set up. Check that the IP Address is set for the local computer. rexec: <message> Reason: A call to rexec has returned a message. Message returned depends on rexecd on remote host. Solution: Check documentation on remote host for more information. 170 Appendix C—COSmanager GUI Server for Windows Socket error: <message> Reason: The COSmanager GUI Server was unable to create the socket used for communications with remote COSmanager product. Solution: Check that the TCP/IP protocol is installed and configured correctly. Tcl Init Error Reason: The COSmanager GUI Server failed to initialize tcl. Solution: Check that the tcl76.dll exists and is accessible in the COSmanager GUI Server bin directory. Tk Init Error Reason: The COSmanager GUI Server failed to initialize tk. Solution: Check that the tk42.dll exists and is accessible in the COSmanager GUI Server bin directory. Unknown host <host> Reason: The host <host> is not known to the local computer. Solution: Check the network configuration and ensure that the host is on the network and accessible. Unknown service tcp Reason: Failed attempt to retrieve service information for “exec” service and “TCP” protocol. Solution: Check that exec service is available. Check that the TCP/IP protocol is installed and configured correctly.