10/11/95 Dynamic Screen Utility (dscreen) Tips SPECIAL NOTICES Information in this document is correct to the best of our knowledge at the time of this writing. Please send feedback by fax to "AIXServ Information" at (512) 823-4009. Please use this information with care. IBM will not be responsible for damages of any kind resulting from its use. The use of this information is the sole responsibility of the customer and depends on the customer's ability to eval- uate and integrate this information into the customer's operational environment. ABOUT THIS DOCUMENT This document describes the use of the Dynamic Screen | Utility (the dscreen command) in AIX versions 3.2.4 ,3.2.5 | and 4.1. It applies to all asynchronous adapters (native, 8-port, 16-port, 64-port, and 128-port). It describes the utility and its options and includes the sections on dynamic screen assignment and the dsinfo information file. | Note: The dscreen utility when used in an AIX 4.1 environ- | ment will only support the 128-port adapter. An error | message "dscreen: not supported on this terminal connection" | will display if not used on a terminal attached to a | 128-port RAN. DESCRIPTION OF THE UTILITY The dynamic screen utility, or "dscreen" command, is a utility that allows a single physical terminal to be con- nected to several virtual terminal sessions (screens) at one time. It is mainly intended for use with terminals that have two or more pages of screen memory (for example, the IBM 3151 display with the Cartridge for Expansion (IBM part number 64f9314)). With such terminals, switching between virtual screens also switches between physical terminal screen pages, allowing each virtual screen's image to be saved and restored. On terminals without multiple pages of screen memory, "dscreen" can still be used to switch among virtual screen sessions, although the appearance of the screen will not be maintained. NOTE: For full support of "dscreen", the terminal must be able to switch internal screen pages on command and must remember the cursor position for each page. While "dscreen" will work on both smart and dumb terminals, screen images are not saved during screen changes on dumb terminals. Dynamic Screen Utility (dscreen) Tips 1 10/11/95 SYNTAX The syntax for the dscreen command is: Syntax: "dscreen [-i infofile] [-t termtype ]" | OPTIONS: "-i infofile" Configuration information is read from the first of the fol- lowing locations that is specified: o file specified with optional "-i infofile" parameter o file specified with DSINFO environment variable o /usr/lbin/tty/dsinfo file In this document, "dsinfo" will refer to any of the above and "/usr/lbin/tty/dsinfo" will specifically refer to that file. The default dsinfo file terminal type assumes a single page of screen memory; therefore, if a terminal supports addi- tional pages of screen memory, the dsinfo file must be cus- tomized to use the appropriate sequence for page memory control. Consult the appropriate terminal reference guide for the specific control sequence. If a different set of keys needs to be used (for example, if the default keys conflict with a software application), you can modify the /usr/lbin/tty/dsinfo file or specify an alternate file with "-i infofile" or DSINFO. "-t termtype" The "termtype" field is used to select which entry in dsinfo is used to describe the terminal. The optional "-t termtype" parameter will override the TERM environment vari- able, Terminal type entries in the dsinfo file will resemble the following IBM 3151 values: Dynamic Screen Utility (dscreen) Tips 2 10/11/95 ---------------------------------------------------------------------- # The Cartridge for Expansion (pn: 64F9314) needed for this entry ibm3151|3151|IBM 3151, dsks=\E!a\r|Shift-F1|, # Selects first screen dsks=\E!b\r|Shift-F2|, # Selects second screen dsks=\E!c\r|Shift-F3|, # Selects third screen dsks=\E!d\r|Shift-F4|, # Selects fourth screen dskc=\E!e\r|Shift-F5|, # Creates a new screen dske=\E!f\r|Shift-F6|\E pA\EH\EJ, # Go to screen 1 and end dskl=\E!g\r|Shift-F7|, # Lists function keys (help) dskp=\E!h\r|Shift-F8|, # Go to previous screen dskq=\E!i\r|Shift-F9|\E pA\EH\EJ, # Go to screen 1 and quit dsp=\E pA|\EH\EJ, # Terminal sequence for screen 1 dsp=\E pB|\EH\EJ, # Terminal sequence for screen 2 dsp=\E pC|\EH\EJ, # Terminal sequence for screen 3 dsp=\E pD|\EH\EJ, # Terminal sequence for screen 4 dst=10, # Allow 1 second timeout buffer ---------------------------------------------------------------------- Figure 1. dsinfo Example -- IBM 3151 USING DSCREEN When "dscreen" is run, it starts a virtual screen. Some of the keys on the terminal keyboard will not be passed through to the virtual screen; instead, "dscreen" will intercept these keys and perform certain actions when they are pressed. The actions include: "select" - select a specified screen "block" - block all input and output "new" - start a new screen "end" - end dscreen (exit code 0) "quit" - quit dscreen (exit code 1) "previous" - switch to a previous screen "list" - list the dscreen keys and what they do. Which keys perform the above functions is dependent upon the terminal and the terminal description in the dsinfo file. NOTES: 1. Do not switch screens when the current screen is being written to; an escape sequence may be truncated and leave the terminal in an unknown state. 2. Some terminal displays may save the cursor position for individual screens but may not save other states such as insert mode, inverse video, etc. If this is the case, users should avoid these modes while switching screens. Dynamic Screen Utility (dscreen) Tips 3 10/11/95 "Select" When a new virtual screen is created, it is assigned a "select" key. Pressing the select key causes the following actions: o A switch from the physical terminal to the video page associated with the particular virtual screen. o Input and output is directed appropriately between the physical terminal and the virtual screen. Once all of the select keys defined in the dsinfo file have virtual screens assigned to them, no more screens may be created. Individual screen sessions end when the original shell process exits. This frees the associated select key for use with another virtual screen. The "dscreen" utility is ended when there are no more active screens. "Block" "Block" keys are used to stop output in a fashion similar to when using IXON flow control. The purpose of these keys is to allow for transparently setting up terminal sessions on two computers using a terminal that has two serial ports. "New" When the "new" screen key is pressed, dscreen creates a new logical screen and assigns it to one of the "select" keys. Each new screen requires: o a "select" key as defined in the "dsinfo" file o a dscreen pseudo terminal device o memory enough for the various structures used in screen tracking o a process from which to run the shell If any of these are not available, the new screen operation will fail and print a message indicating the reason for the failure. "End" and "Quit" When the "end" key is pressed, dscreen will do the fol- lowing: o send a SIGHUP signal to all the screen sessions o clean up o exit with a status of zero (0) When the "quit" key is pressed, dscreen will perform the same actions but will exit with status of 1. Dynamic Screen Utility (dscreen) Tips 4 10/11/95 "Previous" When the "previous" key is pressed, dscreen will switch the terminal to the screen that was last displayed. "List" When the "list" key is pressed, dscreen will display a list of keys and their actions on the terminal display. Only those keys recognized by dscreen will be shown. When a new screen is created using dscreen, the message "Press for help" (where is the name of the "list" key) is displayed on the terminal. Note that the message is only displayed if there is a "list" key defined. DYNAMIC SCREEN ASSIGNMENT The terminal description entry in the dsinfo file will have the same number of screen selection keys as the terminal has physical screen pages. If more screen selection keys are defined than the number of physical screen pages, dscreen will dynamically assign physical screen pages to virtual screens. When a virtual screen is selected that does not have an associated page of screen memory, dscreen assigns the least recently used physical screen to the virtual screen. Depending on the specifications maintained in the dsinfo description file, an indication that the physical screen is connected to a different virtual screen may be noticeable. For example, the screen may be cleared. DSINFO DSCREEN INFORMATION FILE Description "dsinfo" is a database of terminal descriptions used by the dscreen multiple screen utility. The file contains the fol- lowing information: o dscreen keys and the functions they perform o the number of screen memory pages for the terminal o the code sequences sent or received to use the above features Entry Format for dsinfo Entries in the "dsinfo" file consist of comma-separated fields. The first field is a list of alternate names for the terminal. Each name is separated by a pipe "|" char- acter. The remaining fields are string types and value strings (in the format "string_type=value_string") describing the capabilities of the terminal to the dscreen utility. Within these strings, the following escape codes are recognized: Dynamic Screen Utility (dscreen) Tips 5 10/11/95 \E,\e escape character \n,\l newline (or linefeed) character \r carriage return \t tab character \b backspace character \f formfeed character \s space character \nnn character with octal value nnn ^x control-x for any appropriate x value Any other character preceded by a backslash will yield the character itself. String Types and Associated Value Strings The "string" types used in the dsinfo file are as follows: DSKX A string type that starts with "dsk" describes a key. The type must be four letters long, and the fourth letter indicates what action is taken when the key is received. The key types are: TYPE ACTION ___________________________________________ dsks Switch Screens dskb Block Input and Output dske End dscreen dskq Quit dscreen (exit status=1) dskc Create New Screen dskp Switch to Previous Screen dskl List Keys and Actions Any other key type (e.g., a string type dskx where "x" isn't s, b, e, q, c, p, or l) will cause no internal dscreen action, but will show up in the key listing and will be recognized and acted upon. A "type" of "dskn" ("n" for No Operation) should be used when no internal dscreen action is desired. The value string for each key (to the right of the "=") is divided into three substrings, which are separated by pipe "|" characters. NOTE: Use "\|" to include the "|" character in one of the substrings. o The first substring is the sequence of charac- ters that the terminal sends to dscreen when the key is pressed. o The second substring is a label for the key that is printed when a list of keys is dis- played. o The third substring is a sequence of charac- ters that dscreen sends to the terminal when this key is pressed before performing the action this key requests. Dynamic Screen Utility (dscreen) Tips 6 10/11/95 DSP A string type of "dsp" describes a physical screen in the terminal. One dsp string should be present for each physical screen in the terminal. The value string for each physical screen has two substrings, which are separated by a pipe "|" character. For example: dsp=\E pA|\EH\EJ, # Sequence for screen 1 of a # 3151 Terminal o The first substring is the sequence of charac- ters to send to the terminal to display and output to the physical page on the terminal. o The second substring is sent to the terminal when the page is used for something new. This second substring is often set to the "clear screen" sequence. It is sent under the fol- lowing two conditions: 1. When a new virtual terminal session is being created. 2. When there are more virtual terminals than there are physical screens. If a virtual terminal is selected which requires dscreen to reuse one of the physical screens, it will send this sequence to the screen to indicate that the screen con- tents do not match the output of the virtual terminal connected. NOTE: Running with more virtual terminals than physical screens can be confusing and is not recommended; it can be avoided by defining no more screen selection keys ("dsks=") than physical screens ("dsp=") in the dsinfo entry. DST A string with a type of "dst" adjusts dscreen's input timeout. The value of the string is a decimal number. The timeout value is in tenths of seconds and has a maximum value of 255 (default=1 [ or .1 seconds]). When dscreen recognizes a prefix of an input key sequence but does not have all the characters of the sequence, it will wait for more characters to be sent until it is recognizable. If the timeout occurs before more characters are received, the characters are sent on to the virtual screen and dscreen will not consider these characters as part of an input key sequence. It may be necessary to raise this value if one or more of the "keys" dscreen is to trigger on is actually a number of keystrokes (i.e. assigning Dynamic Screen Utility (dscreen) Tips 7 10/11/95 1, 2, 3, etc. for screen selection, N for new screen and so on). Example 1 The following example dsinfo entry is for a Wyse 60 with three screen sessions: wy60|wyse60|wyse model 60, dsks=^A`\r|Shift-F1|, dsks=^Aa\r|Shift-F2|, dsks=^Ab\r|Shift-F3|, dskc=\200|Ctrl-F1|, dske=\201|Ctrl-F2|\Ew0\E+, dskl=\202|Ctrl-F3|, dsp=\Ew0|\E+, dsp=\Ew1|\E+, dsp=\Ew2|\E+, In the above example: o through are used for selecting screens one through three. o creates a new screen o sends " w 0 +" to the screen (switching to window 0 and clearing the screen) and then ends dscreen o will list the keys and their functions Each time a physical screen is used for a new screen, the sequence " +" will be sent to the terminal, which will clear the screen. Example 2 The following example is for a Wyse 60 with three screen sessions, but one of the screens is on a second computer communicating through the second serial port on the ter- minal: Dynamic Screen Utility (dscreen) Tips 8 10/11/95 wy60-1|wyse60-1|wyse model 60 - first serial port dsks=^A`^M|Shift-F1|, dsks=^Aa^M|Shift-F2|, dskb=^Ab^M|Shift-F3|\Ed#^Ab\r^T\Ee9, dskc=\200|Ctrl-F1|, dske=\201|Ctrl-F2|\Ed#\201^T\Ew0\E+, dskl=\202|Ctrl-F3|, dsp=\Ew0|\E+,dsp=\Ew1|\E+, wy60-2|wyse60-2|wyse model 60 - second serial port dsks=^A`^M|Shift-F1|\Ed#^A`\r^T\Ee8, dsks=^Aa^M|Shift-F2|\Ed#^Aa\r^T\Ee8, dsks=^Ab^M|Shift-F3|, dskc=\200|Ctrl-F1|, dske=\201|Ctrl-F2|\Ed#\201^T\Ew0\E+, dskl=\202|Ctrl-F3|, dsp=\Ew2|\E+, dscreen must be run on both computers, with terminal type "wy60-1" on the first computer and terminal type "wy60-2" on the second computer (using the -t option for dscreen). In the wy60-1 entry, the first two key entries are unchanged from the original wy60 entry. The third key, however, has type "dskb", which means block both input and output. When this key is pressed the sequence: d # b e 9 is sent to the terminal; after this, output is blocked and dscreen continues scanning input for key sequences but dis- cards all other input. The sequence " d #" puts the terminal in "Transparent Print Mode", which echoes all characters up to a out through the other serial port. The characters " b " are sent out the other serial port, informing the dscreen process on the other com- puter that it should activate the window associated with the key. The "" exits the Transparent Print Mode. The " e 9" tells the terminal to switch to the other "AUX" serial port for data communications. At this point, the other computer takes over and sends an " w 2" to switch to the third physical screen and then resumes normal communication. The "wy60-2" entry follows the same general pattern for keys and : o switch to transparent print mode o send function key string to other computer o switch transparent print off o switch to the other serial port Dynamic Screen Utility (dscreen) Tips 9 10/11/95 The end key works the same for both computers; it sends the end key sequence to the other computer through the transparent print mechanism, switches the terminal to window 0, clears the screen, then exits. Dynamic Screen Utility (dscreen) Tips 10 10/11/95 READER'S COMMENTS Please fax this form to (512) 823-4009, attention "AIXServ Informa- tion". You may also e-mail comments to: elizabet@austin.ibm.com. These comments should include the same customer information requested below. Use this form to tell us what you think about this document. If you have found errors in it, or if you want to express your opinion about it (such as organization, subject matter, appearance) or make sug- gestions for improvement, this is the form to use. If you need technical assistance, contact your local branch office, point of sale, or 1-800-CALL-AIX (for information about support offer- ings). These services may be billable. Faxes on a variety of sub- jects may be ordered free of charge from 1-800-IBM-4FAX. Outside the U.S. call 415-855-4329 using a fax machine phone. When you send comments to IBM, you grant IBM a nonexclusive right to use or distribute your comments in any way it believes appropriate without incurring any obligation to you. NOTE: If you have a problem report or item number, supplying that number may help us determine why a procedure did or did not work in your specific situation. Problem Report or Item #: Branch Office or Customer #: Be sure to print your name and fax number below if you would like a reply: ______________________________________________________________________ END OF DOCUMENT (dscreen.zap, 4FAX# 1399) Dynamic Screen Utility (dscreen) Tips 11