Charlotte CMS WWW browser, V2.1.0 Perry Ruiter Province of British Columbia http://www.gov.bc.ca/ Welcome to Charlotte Version 2, the World Wide Web client for VM ================================================================ Charlotte V2 is a major new version of the Charlotte web client for VM/CMS. It provides text-mode full screen access to the World Wide Web from 3270-type screens, including support for Gopher and FTP (File Transfer) protocols and network news (NNTP) support. ------------------------------------------------------------------------ Version 2 Highlights ==================== For those familiar with the previous version, 1.2, here is a summary of some of the highlights of this new version. (Some of these enhancements have also been made available as fixes on 1.2, usually in a more restricted form). -- New more powerful HTML parser and formatter (written in C/370) -- Based on HTML 3.2 specification -- Supports tables as defined for HTML 3.2, including nesting -- Supports normal text formatting (indents, lists) inside tables -- Adjusts table cell widths to make best use of screen width -- Provides links to individual frames if document uses FRAMES -- Provides links for client-side image map AREA tags -- SOCKS firewall server support -- Supports http, gopher, ftp, news access via SOCKS4 protocol -- Multiple firewall server support -- Automatic selection based on IP address, protocol or host name -- Network news reading support -- Tracks last article read in newsgroups being followed -- If no newsgroup specified, lists current groups being followed -- Supports leading/trailing wild card for newsgroup name list -- Provides links to referenced articles -- Can link to URLs and other references appearing in ordinary text -- Just press Enter (or Receive key) with cursor on reference -- Supports all standard URLs, e.g. http://www.ibm.com -- Supports most news article references and e-mail addresses -- Can deduce omitted scheme, for example www.name implies http -- Recognizes when a link returns to a previous document -- Restores "Return" key path to previous state (with a message) -- Often makes it easier to navigate through hierarchical documents -- Supports XEDIT for filling in text area input fields -- Makes it easier to enter multi-line text -- Can be used to include existing file input in text area -- Terminal codepage support ("brackets look like brackets") -- Queries terminal device to select appropriate translate table -- Uses APL/Text box characters and bullets if supported -- APL/Text mode square brackets are supported in input data -- Options and optional configuration files -- Supports command line options to select configuration files -- Used for example to select PF key layout -- Options remain in effect for future sessions unless cancelled -- PF key tailorability -- Can easily select CMS, CUA or PROFS conventions, 12 or 24 keys -- Can also override individual key definitions -- Tracing of TCP/IP activity for debugging purposes: -- Traces SOCKET call time, parameters, return time, results -- Writes to files WW2HTTP TRACE, WW2FTP TRACE etc. -- TRACE option turns on all traces for current session -- Attempt to display binary file now gives helpful error message -- Request is cancelled as soon as binary file is detected -- User is told that file can be downloaded using the Receive key -- Leading "http://" can be omitted when entering http URLs -- WebMap display ("see where you have been") ------------------------------------------------------------------------ Installation and getting started ================================ Charlotte V2 should run on any version of VM that will run CMS Pipelines (PRPQ 5785-RAC, or shipped with CMS), VM TCP/IP (5735-FAL) Version 2 or later and REXX Sockets Version 2 (shipped with CMS since CMS 13). Charlotte V2 includes REXX routines which have been compiled with the IBM Compiler for SAA REXX/370 (5695-013) release 3. These routines normally require the IBM Library for SAA REXX/370 (5695-014) release 2 or above. However, if this is not available, the compiled routines can be run in interpreted mode using the Alternate Library components (prefixed "EAG") included in the package, in which case the code will run about three times slower. The Alternate Library components are activated by renaming EAGALPRC MODULE to EAGRTPRC MODULE (which is normally the name of the real library) and renaming EAGALUME TXTAMENG to EAGUME TXTAMENG. If you already have a copy of the Alternate Library, check the date of your EAGRTALT MODULE against the one supplied with Charlotte and use the later one, as older copies of that module cause problems with Pipelines. (If you have problems with the Alternate Library or need to recompile code locally, an optional source materials package is also available). Charlotte V2 runs best with the latest "Field Test" level of Pipelines (currently 1.0110) but at present Charlotte also tests dynamically whether recent Pipeline functions are supported, and if not it uses older techniques. These may not work so well, but should allow Charlotte to run with some limitations using Pipeline levels down to 1.0106 (or the VM/ESA equivalent level 2.0101). For example, if the user attempts to display a binary file at a level of Pipelines which does not support FANOUTWO, then Charlotte will receive the whole file before detecting that it is not displayable instead of cancelling it immediately. Note that this support for down-level Pipelines has proved very difficult to maintain and is unlikely to be continued into any future release of Charlotte. If you don't have REXX Sockets (RXSOCKET MODULE), you can get the latest level by sending a note to listserv@cunyvm.cuny.edu containing the single line "get rxsocket vmarc (f=uue". You should receive two mail files in response. The first is a listing of what the LISTSERV thought you said and the second, if all goes well, is RXSOCKET VMARC. You will need to extract the UUEncoded file and then UUDecode it before you VMARC UNPACK it. To avoid any conflict with an existing copy of Charlotte V1, all installation files for Charlotte V2 start with "WW2" instead of "WWW". The file WW2 PACKAGE contains a list of all the files you should have received with brief descriptions of their functions. When you have successfully installed Charlotte V2 you may wish to make it available under the name "WWW", in which case you can merely rename the primary invocation exec (and its help file), or create a front-end WWW EXEC which just invokes WW2, as described in the comments in WW2 EXEC. Charlotte should run as shipped. It expects to be able to use Pipelines support (which has been shipped with all recent releases of CMS), REXX sockets (which is shipped with CMS 13 or above), and either the run-time library or alternate library for compiled REXX. The TCP/IP interface requires a visible copy of the file TCPIP DATA, but no other TCP/IP components normally need to be visible (unless Telnet support is used). If this software is not available on a normally accessed system disk, you will need to modify the invocation exec WW2 EXEC to make the software available before invoking WW2MAIN and to restore the original environment on exit. See the source of WW2 EXEC for further instructions. Once you have Charlotte working, you will want to update the WW2 CONFIG file to set your home page URL and the Print and MailTo options among others. After you have installed Charlotte, instructions on how to use it are available in the built-in help file displayed by invoking Charlotte with the parameter HELP or ?, or by pressing the Help PF key (usually PF1) within Charlotte. Charlotte includes interfaces to use external commands for various protocols that it does not support directly, including Telnet/TN3270, PhoneBook and MailTo. In the case of PhoneBook, a Gopher type 2 request, Charlotte will look for a PH EXEC (shipped with the Rice Gopher) and use that, otherwise it will issue an error message saying the PhoneBook support is not enabled. For MailTo and Telnet, Charlotte has parameters in the WW2 CONFIG file to determine what external routine will be called to handle the request. Charlotte also has parameters to allow external commands to be used for Gopher and News support, but it normally uses its own built-in support. ------------------------------------------------------------------------ Technical Notes =============== 1. Using TCP3270 (Host Explorer). If your terminal emulator is TCP3270 from McGill Systems (now called Host Explorer from Hummingbird Communications) there are a couple of things you need to know in order to have all characters displayed properly. First, select a session that supports extended attributes. Sessions that do not support extended attributes also do not support write structured field and hence the query information needed by Charlotte is not available. Second, even with an extended attribute session, in all likelihood you will end up with the wrong terminal code page being selected by Charlotte. Regardless of which translation table is in use, TCP3270 always returns a constant Character Sets descriptor in its write structured field query response. The default code page after installation often is US-English C370 CECP V2, but the query reply indicates US-English CECP is loaded. So ... you need to change your terminal translate table to match the query reply. You do this by selecting the global options and then selecting the appropriate translate table. To have correct values returned in the Query Character Sets inbound structured field you need to upgrade to Host Explorer V4.01. This will address most of the problems. However, even at that level Host Explorer returns the same character set descriptor for the US English CECP, US-English C370 CECP and US-English C370 CECP V2 translate tables. This will be corrected in the upcoming V6.0 release. See also the section on problem solving in the on-line help for further information about problems with characters being displayed incorrectly. 2. Authorization checks on proxy firewall (such as ANS Interlock). If your proxy firewall is configured to require a userid and password, you may find that you cannot use it to access a target site which itself requires a userid and password. This occurs when the proxy firewall uses the HTTP/1.0 401 status code with the WWW-authenticate header to request authentication, which is the same method normally used by target sites. (This can be verified by running with the TRACE option and looking at the file WW2HTTP TRACE). The only solution is to reconfigure or modify the proxy firewall server to use the 407 status code and a Proxy-authenticate header, which is an HTTP/1.1 extension supported by Charlotte V2, leaving the WWW-authenticate header free for use by the target site. The firewall server may for example be modified to check the start of the "User-agent" request header for the string "Charlotte/2." and use "Proxy-authenticate" in this case. The supplier of your proxy firewall software should be able to help you with this. ------------------------------------------------------------------------ Discussions and Support ======================= You can join the discussion of things relating to the World Wide Web on VM by sending a note containing the single line: SUBSCRIBE WWW-VM Your Name to listserv@maelstrom.stjohns.edu. Within a few minutes you should receive a reply saying you were added to the list and giving you instructions on how to send mail to the other subscribers. If you have a network news server available, you may also be able to read this mailing list as a newsgroup, using the URL news:bit.listserv.www-vm. Unfortunately we are not able to offer formal support at this time. We would, however, like to hear of any problems, questions, suggestions or bug fixes. When reporting a problem, please provide us with a URL, or if the page is behind a firewall, the source for the page so we can attempt to reproduce the problem locally. You can contact us at: Charlotte.Support@gems4.gov.bc.ca Users within IBM can discuss Charlotte on WWWVM FORUM on the IBMVM disk (also available as newsgroup ibm.ibmvm.wwwvm) and should follow the instructions in the forum header for reporting problems or requesting further information. ------------------------------------------------------------------------ PS. In case you are wondering, Charlotte was named after the spider, Charlotte A. Cavatica, in the story "Charlotte's Web" by E. B. White. The name was suggested by Simeon Ventura.