COSmanager/User Guide/Appendices

From Documentation

Contents 1 Appendix A — the COSmanager User Interface 1.1 The Functional Toolset 1.2 Methtool 1.3 Prompt 1.4 Menu 1.5 Button Bar 1.6 Scroll/Keep 1.7 Keep 1.8 Choose/Order 1.9 Order 1.10 Search 2 Appendix B—Terminal Support 2.1 How to Check a Terminfo Definition 2.1.1 To check a terminal definition 2.2 Checking Your Terminal Definition 2.2.1 Checking the alternate character set 2.2.2 Checking character attributes 2.2.3 Checking Tab-stops and margin settings 2.2.4 Checking function keys 2.3 How To Configure Function Keys 2.4 Terminfo Technical Details 2.4.1 Alternate character set 2.4.2 Character attributes 2.4.3 Terminals With Fewer Than Eight Function Keys 2.4.3.1 VT100-compatible terminals 2.4.3.2 VT200-Compatible Terminals 2.4.3.3 Generic Function Key Definitions 2.4.3.4 Keypad Keys 2.5 Troubleshooting 2.5.1 Data loss 2.5.2 Slow scrolling 2.5.3 Intermittent function keys 2.5.4 ‘Magic cookie glitch” 2.5.5 Incorrect vendor-supplied Terminfo definitions 3 Appendix C — COSmanager GUI Server for Windows 3.1 Installing the COSmanager GUI Server for Windows 3.1.1 Uninstalling 3.2 Configuring the COSmanager GUI Server for Windows 3.2.1 To Configure the Standard Settings 3.2.2 To Configure the Advanced Settings 3.3 Running the COSmanager GUI Server for Windows 3.3.1 To run COSmanager 3.3.2 To exit COSmanager 3.4 Technical Notes 3.4.1 Running the COSmanager GUI Server 3.4.2 Remote Connection 3.4.3 Debugging 3.4.4 Variables 3.5 Remote Command 3.5.1 Directory Structure and Key Files 3.6 Troubleshooting 3.6.1 Connection failure 3.6.2 COSmanager host not defined! 3.6.3 Couldn't find server directory 3.6.4 Couldn't initialize winsock 3.6.5 Couldn't set COSmanager GUI Server directory 3.6.6 Create socket failure 3.6.7 Error reading socket 3.6.8 Failed to open file: <file> 3.6.9 Failed to open <home directory>\COSmanager.ini 3.6.10 Failed to read form: <form> 3.6.11 Fatal Error in wish 3.6.12 GUIserver Error 3.6.13 [incr Tcl] Init Error 3.6.14 libfs Init Error 3.6.15 Local IP Address not defined! 3.6.16 rexec: <message> 3.6.17 Socket error: <message> 3.6.18 Tcl Init Error 3.6.19 Tk Init Error 3.6.20 Unknown host <host> 3.6.21 Unknown service tcp

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 MS Windows 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:

Button	Function
Help	Display help for the current option.
Exit	Exit from methtool.
Search	Display the first occurrence of the specified character string.
Select	Select highlights a row. DeSelect removes the highlight.
Go to	Move the viewing window to the top of the specified page. (CUI)
Options	Change configurable settings or print selected items.
Menu	Display methods in a pop-up window.

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:

Button	Function
Help	Display the extended help facility (GUI).
Exit	Exit without saving any changes.
Choose/Select	Choose from a pop-up window or select from a set of alternatives.
Insert/Overtype	Toggle between insert mode (the default) and overtype mode.
Del Char	Delete the character at the current cursor position.
Clr Fld	Clear the current data field.
Accept	Accept the selection and proceed.

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:

Button	Function
Help	Display help for the current option.
Manual	Display the manual page for this command, if available.
Exit	Exit from the current operation without proceeding.
Index	Invoke Mtree to search through the hierarchy of menus available to thecurrent user.
Top	Go directly to the current user’s top level menu.
Shell	Break out from this menu to the UNIX shell.
Accept	Select the highlighted menu item.

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:

Button	Function
Help	Display help for scroll.
Exit	Exit from the current display without proceeding.
Search	Display the first occurrence of the specified character string.
Print	Print all or selected pages on the default printer.
Go to	Move the viewing window to the top of the specified page. (CUI)

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:

Button	Function
Help	Display the extended help facility (GUI).
Exit	Exit from the current operation without proceeding.
Follow	Track new data as it is added to the end of the display (GUI).

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:

Button	Function
Help	Display the extended help facility.
Exit	Exit without choosing any rows.
Search	Display the first occurrence of the specified character string.
Select/DeSelect	Where multiple rows can be selected, Select highlights a row and DeSelect removes the highlight. (CUI)
Go to	Move the viewing window to the top of the specified page. (CUI)
Accept	Accept the selection(s) and proceed

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).

Mouse Action	Function
B1	select the row under the pointer. Double-click to accept it.
B1-drag	select several rows
Shift-B1	select all the rows between the pointer and the nearest previously selected row.
B2 or Ctrl-B1	add row to the previously selected rows, or deselect the row if it was already selected.
B2-drag	across unselected rows: adds them to the selection. across selected rows: deselects them.
Ctrl-Shift-B2	toggle every row

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:

Button	Function
Help	Display the extended help facility.
Exit	Exit from the current operation without saving changes.
Search	Display the first occurrence of the specified character string.
PickUp/PutDown	PickUp highlights a row to be moved elsewhere in the list. PutDown places the row in its new location. Pressing PutDown over the old location cancels a selection.
Go to	Moves the viewing window to the top of the specified page.
Accept	Accept the selection(s) and save the rows in the new order

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:

Button	Function
Help	Display the extended help facility (GUI)
Exit	Exit the search window and return to the original location in the scroll box.
Search/Next/Restart	Search for the next occurrence of the entered string or pattern. Restart resumes searching from the top of the data.
Clr Fld	Clear the text in the search field.
Accept	Exit the search window, and return to the scroll box at the position of the found row.

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.

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

• 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.

• If necessary, run ticonfig to rebuild the Terminfo function key definitions for the current terminal.
• 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.

• 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.
• 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.

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:

$ echo $TERM vt220

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
• 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 characters, 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 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
• home and end
• insert and delete
• clear line.

If any of these keys are not recognized, read the next section on configuring function keys.

How To Configure Function Keys

Typically, the only change required to the terminal definition is make it recognize thefunction 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:

$ cat -v
^[OP
^[OQ
^[OR
^[OS
^D
$

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:

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:

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.

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

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.

This information is used to create the new Terminfo definition. You can abort this process at any stage by typing q.

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.

	Caution!
	You may affect other users if your TERMINFO environment variable is not set or is set to a public directory.

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.

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.

Once the definition is compiled you can check the definition using ticheck.

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.

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

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

Character attributes

The bold, reverse, blink, and underline character attributes are specified through the following Terminfo variables:

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

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 for more information.

The following is a fragment from a VT100 Terminfo definition that implements such a function key scheme.

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,

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.

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.

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,

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.

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.

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,

Keypad Keys

The Functional Toolset can use several of the keys available on the keypads of modern terminals, as shown in the following table.

	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.

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†

The smkx/rmkx will only be required if a terminal has separate keypad and application modes, such as DEC terminals

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.

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)
• 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

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 variants.

Installing the COSmanager GUI Server for Windows

This topic explains how to install and uninstall the COSmanager GUI Server for Windows.

	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 COSmanager GUI Server for Windows.

	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 onto your hard disk.

The system requirements of COSmanger GUI Sever are extremely low. If your machine starts up, it will run the server.

The installation procedure is as follows:

1. Start Windows.
2. Select Settings > Control Panel from the Start button.
3. Download the PCgui Software for Windows from http://downloads.fs.com.au. Please be aware that this requires a support contract to be in place with Functional Software.
4. Browse on your PC to the folder you downloaded the software to.
5. Double-click on the file to start the installation.
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.

Uninstalling

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:
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:

• 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.

Configuring the COSmanager GUI Server for Windows

To start the COSmanager GUI Server, double-click on the COSmanager icon.

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.
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 Host

The 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

• Press the Advanced button.

The Port number is determined automatically.

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.

• Enter or set the following fields:

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:

`grep COSmanager /etc/passwd | cut -d: -f6`/bin/cos

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.

Press Accept to save the new settings.

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.

To run COSmanager

1. To start the COSmanager GUI Server, double-click on the COSmanager icon.
2. Press the Connect button.
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.

	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.

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:
   • Windows NT/95 HKEY_LOCAL_MACHINE\SOFTWARE\Functional Software\COSmanager GUI Server\3.2.2
4. Initialize Winsock.
5. Determine default values and set environment variables.
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.

	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

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.

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.

The syntax for the rexec command is:

rexec <host> <user> <password> <command>

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:

/bin/ksh -c “DISPLAY=<ipaddress> GUI_HOST=<ipaddress> GUI_PORT=<GUI_PORT> GUI_OS=<GUI_OS> ~COSmanager/bin/cos $Arguments”

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:

DISPLAY=<host> GUI_HOST=<host> GUI_PORT=<GUI_PORT> GUI_OS=<GUI_OS> $Command $Arguments

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:

% set <variable name>

Most of the variables used in the COSmanager GUI Server are stored in arrays.

You can display the elements of an array by typing:

% array names <array>

Common variables include:

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

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 runremote 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:

remote <host> <user> <password> <command>

Directory Structure and Key Files

The COSmanager home directory ($GUI_HOME) contains:

COSmanager.ini

the initialization file for the COSmanager GUI Server

errors.txt

an alphabetical list of error messages (see also Troubleshooting)

install.txt

installation notes

readme.txt

overview notes

COSmanager/bin contains:

cos.exe

the COSmanager GUI Server executable

.dll

• various DLLs

COSmanager/icons contains:

.xbm, *.xpm

• icon files used in COSmanager Software
• .ico: COSmanager and ReadMe icons used by Windows

COSmanager/lib contains:

tcl7.6

the current TCL library

tk4.2

the current Tk library

COSmanager/server contains various TCL files:

defaults

application defaults for fonts, colours, etc.

startup.tcl

initial startup TCL script

tclIndex

TCL index for TCL files

winmain.tcl

WinMain TCL class

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

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.

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.

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.