Source Code 1992 March

home *** CD-ROM | disk | FTP | other *** search

/ Source Code 1992 March / Source_Code_CD-ROM_Walnut_Creek_March_1992.iso / usenet / compsrcs / mac / 9 / MacLayers.doc < prev next >

Wrap

Text File | 1990-06-05 | 30.2 KB | 673 lines

MacLayers Document Version 1.00 March 17, 1990 MacLayers provides multi-window capability for a Macintosh connected to a host UNIX(TM) system with sockets support. Each window may be associated with a shell, login to a different host, or an individual command. Complete facilities are available for controlling the window and the associated host processes attached thereto. What You Need To Run MacLayers 1) A Unix host which supports the sockets protocol. 2) A Macintosh with more than 128k of RAM and connected to the host. 3) The MacLayers Macintosh Application provided with this package. 4) The Unix host server command 'layers' provided with this package. 5) If you want to resize windows which are logged into a second BSD machine or resize windows on a BSD machine running in non-layers mode then you need the 'layersize' command provided with this package. 6) If you want to specify window titles on your own (such as to indicate your current directory or other such information) you need the Unix 'layertitle' command provided with this package. MacLayers Operation The MacLayers Application on the Macintosh starts up as a garden variety host-to-terminal vt-100 emulator. (As such you can run it with any host, not just a BSD machine.) Baud rate and other configurations are set by selections in the Control menu. MultiFinder is fully supported so you can use other applications while MacLayers is executing and downloading. The initial or any document window may be saved via the "Save As" File menu option. When this happens the file is designated as a MacLayers application document and contains not only logged text from the host communications in that window but also the current Control menu settings. Once the initial 'layers' command is executed on the host (use no options or parameters) MacLayers and the host start operating in MacLayers protocol mode. Automatically the document file window is closed and reopened as layer number 1 running with a new shell. The shell is either /bin/sh or the shell indicated by your $SHELL environment variable. The term 'layer' refers to a process group running on the Unix host and the associated MacLayers window to which the group is attached. The Macintosh Layer menu list shows the status of currently opened layers and read-only text files (described later). Selecting the menu item brings the associated window up front. Layer number 1 is always associated with your startup document. Its shell identifies itself to the host as your login shell so that broadcast messages and commands like 'talk' and 'write' will be properly redirected to that window. (The current mesg(1) state remains unchanged.) You can start a new shell layer via the New menu item from the Layers menu. You can also start a new layer window by issuing the 'layers' command in a shell layer window. If you use no operands then the new layer window will be a shell. However, instead of a shell you can specify any command you wish by simply adding it as a parameter. Examples: layers vi testfile.c layers telnet earth If you are specifying a shell then you can also elect to have it be a login shell by adding a -l option. This allows broadcast/write/talk capabilities for that window. By default only the document layer (number 1) always starts out as a login shell. The host is always kept informed of your current window size and programs using curses(3) like 'vi' and 'more' will properly adapt. However, most utilities only size the window once when they start up so changing the window size is verboten after they are running. MacLayers normally disallows window resizing when it recognizes that you are running such a program. This can be overridden by holding down the shift key when resizing the window. A 'vi' symbol appears in the lower right window 'growbox' area when MacLayers detects you are running a cursor moving type of program. Zooming also is disallowed at this time unless both the zoomed and non-zoomed state have exactly the same character line width and height. See the section "Logging Into Another Host" below for information on proper window sizing when your window is being used to do a login command into another host. Note: You may have to hit return once after some programs terminate to get MacLayers to recognize you are out of 'vi' mode. The "enter" key is typically used to send a break (SIGINT) to all processes associated with that layer window. The method can be configured in the Control menu Terminal item. You may terminate the window's processes with the Layers menu "SIGTERM/SIGHUP Layer" item. The layer may also be killed by closing its window (SIGHUP). When a layer process group terminates on the host its window is automatically closed. MacLayers exits layers mode when the last (or only) layer window is closed. You may also use the Layers menu "Shutdown" to terminate layers mode. You cannot quit the MacLayers application while in layers mode but must Shutdown the multi-window mode first. You can abort host layers by using the Control menu "Abort Host Layers" item which is always available. This may be necessary if your Macintosh loses contact with the host and you restart the MacLayers application at which time the application would not be in layers mode but the host would. If the MacLayers application aborts due to a non-recoverable problem it will inform the host to terminate layers mode before returning to the Finder. More About Window Sizing Each MacLayers window has two complete window size environments, a zoomed state size and a non-zoomed state size. Each state may have its own associated font size and screen location. When you change the window size by dragging the grow corner (bottom right) you convert the window into its zoomed state. Clicking the zoom box in the title bar switches between the two states. Simply moving a window doesn't change its state. Both the font and size for the two states can be set by the Control menu "Default Window Settings" and "Current Window Settings" items. The default item settings are used when any new windows are created. Logging Into A Secondary Host If you log onto another system from within a layer window then that system will not know of your current window's size. MacLayers provides you with a way to inform that system of this information if the system is a BSD or System V Unix. For remote BSD systems you can execute the 'layersize' command provided with this package. (The command must be copied or built on the remote system and be accessible by your shell there.) When at the shell command prompt select the Control menu item "Inform BSD of Window Size" and a string will be sent invoking the 'layersize' command. This informs the remote kernel of the current process window size. If your BSD .login or .profile uses the 'tset' command to set the terminal type then you must add the -I option to keep 'tset' from forcing each login window to be treated as always having 24 lines (the vt-100 default.) System V allows window (actually screen) sizes to be specified with the environment variables "COLUMNS" and "LINES". You can automatically set these shell variables when at a shell command prompt by selecting the Control menu "Inform System V of Window Size" item. It is up to you to inform the indirect login host of any window size changes by using the menu items. Your terminal type on such hosts should be specified as vt100 if you wish to execute screen oriented commands such as 'vi' or 'more'. Other Capabilities Cursor Positioning In 'vi' Mode When in 'vi' mode MacLayers provides a useful cursor moving feature. Double-clicking in the window causes a series of vi commands to be issued which cause the insertion cursor to move to that location. You must not be in vi insert mode or the commands will simply be taken to be text that you have typed. (You can do that just for fun to see what MacLayers sends on a double-click.) Read-only Text Files MacLayers can open up text files as read-only windows by using the "Open Text" File menu. Such windows can have their contents copied to the clipboard but may never be altered in any way. Text window titles show the circle-r (registered trademark) to let you know they are read-only and a "no-write" symbol appears at the bottom right portion of the window (the "grow" area.) Window Aliasing At times you may wish to view two portions of a communication window's contents at one time. The File menu "Open Window Alias" will create a new read-only window for any communications window and this can be scrolled to any independent position desired just like a text-only window. Since in-coming text from the computer always forces a window to the bottom for proper capturing, the window aliasing feature can be used to open a surrogate window that is immune to this action. XMODEM Downloading MacLayers has a download facility for accepting downloaded XMODEM MacTerminal ('macput' command) and macbinary ('macbput' command) files. Straight vanilla XMODEM is not supported. A copy of the public domain macbinary downloading program 'macbput' is provided with this package. Only one window can be doing a XMODEM download at any one time. Downloading does not effect any other MacLayers operations so you can freely use any other windows or applications (with MultiFinder) while a download is in progress. Remember though that the topmost window receives the highest priority data transfer from the host so for the fastest downloading keep the XMODEM layer window the active window. The File menu "Download Site" can be used to preselect the location where downloads are to occur. By default files are placed where the startup document resides. This setting is forgotten each time the MacLayers application terminates. If you have an error-free line then setting the "Fast" mode in the Control menu "File Transfer" selection will speed up download by about 28%. Downloading Examples The macbput utility provided with this package can be run on the host Unix system and is used to ship files to a Macintosh running MacLayers. (Some Unix systems already have a utility called macput which is used in exactly the same way. But macbput properly updates Macintosh file dates concerning the time of original creation and last use.) To download a standard Unix text file, for example one created by a editor such as vi or emacs, enter the following command: macbput -u filename The transfer will start automatically and will create a Macintosh file of type TEXT on the Macintosh which can be opened by applications such as MacWrite and Word. Other types of Macintosh files and applications may also be downloaded. On the host Unix system they may take on one of many forms. If you have a single file which ends in the name "hqx" then it must first be converted into three files with names ending in .info, .data and .rsrc with a utility such as xbin (not provided.) xbin filename.sit.hqx If you have the .info, .data and .rsrc files then you are ready to download with the macbput (or macput) command. Specify only the front part of the file name, the part before the .info, .data and .rsrc. macbput filename.sit The transfer will start automatically and upon completion a copy of the file will be available on the Macintosh. Sometimes the host version of the file will not be in three pieces but instead exist as a single binary (non-text) file. These are called macbinary files and almost always end in the suffix ".bin". Macbinary files may be converted to the three file info, data and rsrc format with utilities such as "mcvert" (not provided) and then downloaded with macbput as above. It is also possible to directly download a macbinary file if you have a so-called XMODEM download utility. (One such utility is called "xmodem".) To accomplish this, issue the download command on the host: xmodem -sb filename.bin and then select the File menu "Download File" item. The download should start at that time. But if it doesn't you may have to invert the Control menu "File Transfer ..." CRC/Checksum selection and try again. Note that downloading via XMODEM utilities will not auto-start the process on the Macintosh. You must use the "Download File" menu item to start the Macintosh side of the operation. Paste Speed Unix is known for the ease with which its tty device drivers can be overrun by input. (This causes data to be lost.) MacLayers provides time delay options which can be set for pasting text into a window. (Data pasted into a window is sent on to the host.) The options are in the Control menu "File Transfer" selections. Preferences Menu Item The Control menu Preferences item provides user selectable options for highlighted text format and cursor display among other things. Window or Selection Printing The entire window or the current selection may be printed by activating the File menu "Print" entry. If you have an early Macintosh model with only 64K of ROM then printing will refuse to work due to Apple's lack of support for that machine in the MPW programming environment. Vertical Window Scrolling With Keyboard Keys You can scroll the active window up or down via the key sequences given below. The second sequence for each option is an alternate provided only for keyboards not having arrow keys: COMMAND+UPARROW scroll back one page or COMMAND+"'" COMMAND+DOWNARROW scroll forward one page or COMMAND+'/' COMMAND+OPTION+UPARROW scroll back one line or COMMAND+OPTION+"'" COMMAND+OPTION+DOWNARROW scroll forward one line or COMMAND+OPTION+'/' COMMAND+SHIFT+UPARROW scroll to the top of the file or COMMAND+SHIFT+"'" COMMAND+SHIFT+DOWNARROW scroll to the bottom of the file or COMMAND+SHIFT+'/' Horizontal Window Movement With Keyboard Keys MacLayers does not directly support horizontal scrolling of window contents. However, the entire window can be easily moved right or left with keyboard sequences. Requesting a movement right or left will bring the opposite edge of the window into view on the screen. If the opposite edge is already in view then the window is moved still further in the indicated direction. This capability when used with the vertical scrolling key sequences allows small screen Macintosh users to comfortably manipulate windows that are wider than the screen. Here are the key sequences provided. The second sequence for each option is an alternate provided only for keyboards not having arrow keys: COMMAND+LEFTARROW or COMMAND+'<' move window left COMMAND+RIGHTARROW or COMMAND+'<' move window right Tandem Scrolling Holding the shift key down while selecting a vertical line or page scroll with the mouse will automatically cause the same scroll to be attempted on the next lower MacLayers window (if any.) This is handy when eyeballing two long similar sections of text for differences. Special Keyboard Sequences For emacs users MacLayers allows a metakey sequence to cause bit 7 (the high bit in a character) to be set. Combining both the command and option keys with any other key sequence will cause bit 7 to be forced on. Thus, keyboards having a built-in control key can generate all 256 possible 8-bit characters. Macintoshes with old non-ADB keyboards will ignore this treatment for the "'" or "/" characters since they are required for the window scrolling movements indicated earlier. For users requiring the generation of ASCII NUL (a zero byte, sometimes called the IDLE character) an alternative to CONTROL-@ (also CONTROL-2) is to issue CONTROL-space (also OPTION-space.) This follows vt-100 terminal convention. Find Capabilities The Find menu items allow searching windows for specific contents or going to the current selection. Iconed Window Capability A unique feature of MacLayers is the ability to shrink a window to an icon. While iconed the window will still actively display its contents and scroll just like a standard sized window. To iconize a window simply double-click its title bar or select the Iconize menu item from the Layers menu. While iconed the window may be moved around just like a Finder Icon and the miniaturized window retains its own independent location. A window is deiconized when you double click it, type input to it as the top window, select it with a Layers menu item, or select the Deiconize Layers menu item. Just for fun MacLayers allows you to scroll a iconed window with the vertical scroll keys (defined earlier) without causing it to deiconize. For users running under MultiFinder standard windows can be auto-iconed temporarily while MacLayers is not the front most application. A check box in the Preferences menu dialog box enables this action. If checked then holding the shift key down while switching to another application will temporarily inhibit the auto-iconing. Icons to Default Positions This menu selection from the Control menu item resets the positions of all iconed windows such that when iconed they appear along the top, right, left or bottom of the screen. There is also an option for the bottom where only the titles show. This allows the user to treat the titles of iconed windows as though they are buttons at the bottom of the screen. By double clicking the button (which is really the title of the iconed window) the window returns to its full size. The menu item simply resets the position for all icon windows to the designated choice selected in the Preferences dialog. They may then be moved again by you to other areas of the screen. Shrink Window To Title At times the desktop becomes too cluttered so MacLayers provides yet another feature to ease the busy desktop problem. Any MacLayers window can be shrunk to just its title bar by shift-double-clicking the title bar or selecting the Titleize item from the Layers menu item. In effect the window is still there but only the title bar remains visible. The window remains titled even if output is being sent to it. Moving the title bar has the same effect as moving the window. The window may be detitleized by double-clicking the title bar or selecting the Detitleize item from the Layers menu. Hide Window Capability You may also completely hide any MacLayers window at any time by selecting the Hide item from the Layers menu. The window will stay hidden until output is sent to it from the host or you reactivate it from the Layers menu. Cycling Through Windows All active MacLayers windows may be displayed one after the other in numerical order by selecting the Layers menu Cycle item. Hidden windows do not appear in the cycle list. Specifying a Layer Window Title The 'layertitle' command provided with this package allows a single argument (which may be a string) to specify a title to be displayed for the controlling window of the process. The source for this command should compile and execute on any Unix system and so can be used even for windows which are logged into remote hosts. An example use of this feature is to create your own "cd" directory change shell command and have it always display the current directory name in the title bar. Expert users can examine the 'layertitle' source code to discover the control sequence needed to send the ANSI Private Message string which actually causes the new title to be recognized. Knowing this sequence standard shell echo facilities can be used in place of the 'layersize' command. Sending an Interrupt to a Window Process The Send Interrupt To Layer item of the Layers menu causes a internal packet to be sent to the host indicating that a SIGINT signal be sent to the UNIX process group attached to the window. This is only available in layers mode. At times the UNIX tty mode settings for a process may become garbled and if the Enter key is sending DEL or CONTROL-C this may not be enough to interrupt the process. Selecting this menu item bypasses the tty driver and so ensures that an interrupt signal is received. Reset Terminal Occasionally you may have bad data transmitted to the Macintosh which can cause the vt-100 emulation to enter a special graphics mode or setup a vt-100 screen scrolling area smaller than your full window size. If this occurs the Control menu item "Reset Terminal" will reinstate normal operation. This in no way affects layers mode operation. Sending Break in Layers Mode A hardware 'break' can be placed on the host serial line with the Control menu Send Hardware Break item. However, when in layers mode this is only allowed if the line is idle to guarantee that no internal control packets become garbled or lost. A beep occurs when the line is busy. Aborting Current Activity Paste and XMODEM operations may be aborted by entering COMMAND-period (cmd-.). Use of the Macintosh RAM Cache For the last few years versions of the Macintosh operating system have provided a RAM cache feature configurable in the control panel to speed up data transfers to floppy and hard disks. There are two types of environments where this option is especially useful with MacLayers. The first situation is for users running off of floppy disks. In this case running with at least the minimal RAM cache size of 32K will inhibit the constant whirring of your diskettes and improve screen text display speed. Users using high-speed communication connections (9600 and above) make up the second group that may need to run with the RAM cache turned on. This is necessary to avoid data loss when receiving large amounts of uninterrupted data. An example of this would be the listing of a large source file directly to your window. Once the RAM cache is filled it purges itself by writing the cached data to an output file. The Macintosh serial driver can lose high speed data coming in if diskette or hard disk accesses are being done at the same time. (This is called data overrun.) Users with this potential situation need to guarantee that the size of their ram cache is at least as big as the largest amount of data they want to capture. (This does not concern XMODEM transfers. They do not require RAM cache although cache of at least minimum size can speed these up as well.) Disk Full Processing MacLayers will put up a warning box and delete all data in the scroll file up to the current output position if the disk where the file resides becomes completely filled. Minimal Memory Environment For users with extremely tight memory requirements MacLayers can be forced to run in a memory partition approximately 95k bytes smaller than normal. When run in this manner MacLayers will beep at startup and issue a warning that only a single window is allowed. No more than one window can be open at a time and no read-only text windows are available in this mode. Also, the maximum size of data handled by cut and paste operations is more restrictive. Enhanced Terminal Capabilities MacLayers supports standard vt-100 terminal protocol as described in BSD Termcap(5) and System V Terminfo(4). But there are also two extra capabilities which can speed up screen updating particularly with screen editors. UNIX users who specify vt100 terminal type only for the sake of running MacLayers can include these extra capabilities by using the replacement terminal descriptions below. These not only include the extra MacLayers terminal capabilities but also remove timing waits required by real vt-100's thus providing even further speed improvements. For BSD Termcap the following description can be used: # MacLayers vt-100 Termcap d0|vt100|vt100-am|MacLayers dec vt100:\ :cr=^M:do=^J:nl=^J:bl=^G:co#80:li#44:cl=\E[;H\E[2J:\ :le=^H:bs:am:cm=\E[%i%d;%dH:nd=\E[C:up=\E[A:\ :ce=\E[K:cd=\E[J:so=\E[7m:se=\E[m:us=\E[4m:ue=\E[m:\ :md=\E[1m:mr=\E[7m:mb=\E[5m:me=\E[m:is=\E[1;24r\E[24;1H:\ :rf=/usr/lib/tabset/vt100:\ :rs=\E>\E[?3l\E[?4l\E[?5l\E[?7h\E[?8h:ks=\E[?1h\E=:ke=\E[?1l\E>:\ :ku=\EOA:kd=\EOB:kr=\EOC:kl=\EOD:kb=^H:\ :ho=\E[H:k1=\EOP:k2=\EOQ:k3=\EOR:k4=\EOS:ta=^I:pt:sr=\EM:vt#3:xn:\ :sc=\E7:rc=\E8:cs=\E[%i%d;%dr:\ :dc=\ED:ic=\EI: The System V Terminfo specialized definition is: # Special System V Terminfo definition for MacLayers vt100 vt100|vt100-am|dec vt100 without tabs and with MacLayers extras, am, mir, msgr, xenl, xon, cols#80, lines#24, vt#3, acsc=``aaffggjjkkllmmnnooppqqrrssttuuvvwwxxyyzz{{||}}~~, bel=^G, blink=\E[5m, bold=\E[1m, clear=\E[H\E[J, cr=\r, csr=\E[%i%p1%d;%p2%dr, cub=\E[%p1%dD, cub1=\b, cud=\E[%p1%dB, cud1=\n, cuf=\E[%p1%dC, cuf1=\E[C, cup=\E[%i%p1%d;%p2%dH, cuu=\E[%p1%dA, cuu1=\E[A, dch1=\ED, ed=\E[J, el=\E[K, el1=\E[1K, enacs=\E(B\E)0, home=\E[H, ich1=\EI, ind=\n, ka1=\EOq, ka3=\EOs, kb2=\EOr, kbs=\b, kc1=\EOp, kc3=\EOn, kcub1=\EOD, kcud1=\EOB, kcuf1=\EOC, kcuu1=\EOA, kent=\EOM, kf0=\EOy, kf1=\EOP, kf10=\EOx, kf2=\EOQ, kf3=\EOR, kf4=\EOS, kf5=\EOt, kf6=\EOu, kf7=\EOv, kf8=\EOl, kf9=\EOw, rc=\E8, rev=\E[7m, ri=\EM, rmacs=^O, rmkx=\E[?1l\E>, rmso=\E[m, rmul=\E[m, rs2=\E>\E[?3l\E[?4l\E[?5l\E[?7h\E[?8h, sc=\E7, sgr=\E[0%?%p1%p6%|%t;1%;%?%p2%t;4%;%?%p1%p3%|%t;7%;%?%p4%t;5%;m%?%p9%t^N%e^O%;, sgr0=\E[m^O, smacs=^N, smkx=\E[?1h\E=, smso=\E[1;7m, smul=\E[4m, tbc=\E[3g, Hints *) MacLayers must internally handle your window display differently whenever the cursor is being positioned above the bottom line such as occurs during the execution of a screen editor on the host. The "vi" symbol is displayed in the grow box during this time to indicate this special mode. During so-called "vi" mode you are not allowed to change the window size. Holding the shift key down will override this restriction and allow you to resize the window. But remember that if you are running a utility then the utility may not be able to dynamically adjust to a new window size. If it can then you must do whatever is required of the utility to inform it of the change. At times MacLayers may think the window is still in "vi" mode even after an editor or cursor controlling utility has finished. One instance of this is immediately after a "clear screen" command. MacLayers does not know to go out of "vi" mode until a new line is added to the very bottom of the screen causing the screen to scroll up a line. If the window has stayed in "vi" mode and you want to resize it simply hold the shift key down or type empty lines to the shell until the window begins to scroll again. (The "vi" will then disappear from the grow box.) *) When running in layers mode the host/MacLayers interface always uses vt-100 protocol regardless of your TERM terminal type setting. Thus if you only set your TERM variable to vt100 to run MacLayers and you always run in layers mode then you need not bother actually setting vt100 as your Unix terminal type. *) As mentioned at the start of this document MacLayers can be used as a normal vt-100 terminal emulator when connected to any host computer. On BSD and System V systems you can also use the variable sized window feature in non-layers mode by following the same instructions given for logging into a remote host as described in the "Logging Into A Secondary Host" section above. (This also holds true for a layers host before the layers command is entered.) On systems other than BSD and System V changing the current window size may garble output unless there is a means for you to notify your connection of the new window size. Problems/Caveats *) The current version does not do data validation with packet retry for MacLayers/host internal communication. Thus poor line conditions may cause a host internal message to be missed. This is usually not catastrophic but means something won't work correctly. For instance a window might not auto-close when a host process death occurs or output might be sent to the wrong window. *) The shell TERM variable must have the same value in your layer shells as it does when you initially start layers up. *) If you set the BSD shell TERMCAP variable then that variable must be set in your .login file. It may not be changed to something different in .cshrc. *) The host/MacLayers system attempts to give highest data communication priority to the topmost MacLayers window at all times by throttling down output to other windows. However due to internal UNIX kernel I/O buffering the attempts may not always succeed. *) The "Download Site" folder is always kept open which means if you want to trash the folder you must first choose a new download site or quit MacLayers. *) MacLayers has U.S. keyboard dependencies. *) The layers command will not properly work when being issued from a remote login into the same machine which is already running the initial layers startup command. *) If a layers window text file is read as a file of type TEXT by another application and that file has highlighted characters (as sent by the host) embedded within it then those characters will appear as garbage in that application. (Specifically such characters have the high bit [bit 7] on.) Bugs *) Occasionally during or after a cursor moving utility has executed if the window is scrolled backwards then when it is eventually scrolled forward to the bottom (last) line of the file the bottom line will be missing from the display. If you can reproduce this problem then please send a complete description of how to do so to uunet!rascal.ics.utexas.edu!layers-reply Acknowledgement The author owes a big thanks to Werner Uhrig and his band of testers at the University of Texas for the many bug reports and suggestions delivered during the intensive beta testing phase of this product. MacLayers is a substantially improved application as a result. Dave Trissel Austin UNIX(TM) is a registered trademark of American Telephone and Telegraph. Macintosh is a trademark of McIntosh Laboratories and is licensed to Apple Computer. **** end of document ****