API tools faq
paste
p4ste

WAOL.doc

p4ste
Jul 15th, 2022
181
0
Never
Add comment
Not a member of Pastebin yet? Sign Up, it unlocks many cool features!
text 246.93 KB | None | 0 0
raw download clone embed print report
  1. Date: Monday, May 03, 1999
  2.  
  3. Subject: Rough Draft of WAOL Client Code Outline & Misc. Info.
  4.  
  5. CONFIDENTIAL - FOR IN HOUSE USE ONLY
  6.  
  7. This document is NOT to be distributed and is intended for use ONLY by AOL employees.
  8.  
  9. Some items within this document are educated guesses. Please do not hold me responsible for the content of this document.
  10.  
  11. Technology at AOL moves rapidly, as a result information in this document can quickly become out-of-date. This document is only meant as a starting point to learn about AOL technology and is not meant to be all-inclusive nor fully up-to-date at any given time.
  12.  
  13. INTRODUCTION 5
  14. Packet 5
  15. Token 5
  16. Object 6
  17. Atom 7
  18. Atom Streams (FDO 91 Interpreted Scripting Language) 7
  19. FORMS 8
  20. CLIENT OVERVIEW 10
  21. How client handles a simple form from the Host to the Client 15
  22. CLIENT CORE - WAOL.EXE 17
  23. WAOL command line parameters 17
  24. GPF Phone Home Reports 18
  25. Com Interface 18
  26. SUPERSUB.DLL 19
  27. Loader 19
  28. ATOM handling (dispatching) 19
  29. IDB – main.idx 21
  30. The Database Design 21
  31. TOOLS - OVERVIEW/IMPLEMENTATION 23
  32. TOOLINIT 23
  33. TOOLEND 23
  34. TOOLREGISTER 23
  35. TOOL UNREGISTER 24
  36. REGISTERATOMPROTOCOL 24
  37. REGISTERATOM 24
  38. TOOLHANDLERS 24
  39. SMART TOOL FUNCTIONS 25
  40. TOOLSENDMSG 25
  41. ADVANCED TOPIC ON TOOLS 25
  42. ACTION 26
  43. AOLCONV 27
  44. AOL DEVICE DRIVER 28
  45. BLOCK DIAGRAM 28
  46. TCP/IP 28
  47. NDIS 30
  48. AOLMAC.VXD 30
  49. Initialization 31
  50. Transferring Data from the Internet to a PC 31
  51. Transferring Data from PC to the Internet 31
  52. AOLSOCK.AOL 31
  53. Initialization 32
  54. Sending and Receiving Data 32
  55. AOLDICE AND AOLCOMM.DLL 33
  56. Access Numbers 33
  57. Phone Home Report 35
  58. Abstract vs. Verbose Reports 36
  59. AOLLIST 37
  60. AOLMODEM 38
  61. AOLRICH 39
  62. AOLSPELL 41
  63. ASYNC 42
  64. BUFFER 43
  65. CSL 44
  66. CHAT 45
  67. CHARTMAN 46
  68. CODEMAN 47
  69. Intercepting Atoms & Tokens 47
  70. Posion Tree 48
  71. DATAMAN 49
  72. FILER 50
  73. MANAGER AND ITS RELATED DLLS 51
  74. Global Ids 52
  75. Display Object 53
  76. MANAGER’s Object Tree 54
  77. Clusters 55
  78. Image Formats supported by the Client 57
  79. Data Extraction from on EDIT field 59
  80. MASTER 60
  81. MIPMAN 61
  82. MMI 62
  83. MORG 63
  84. P3 65
  85. SECURITY 68
  86. Secure Login (Handshake) 68
  87. Form Level Encryption 69
  88. Field Level Encryption 70
  89. SHORT 71
  90. XFER 72
  91. Timing Tests for File Upload 72
  92. WWW 73
  93. OVERVIEW 73
  94. RESPONSIBILITIES OF THE BROWSER CUSTOM CONTROL/DLL: 73
  95. RESPONSIBILITIES OF THE AOL APPLICATION: 74
  96. Interfacing to AOLSOCK 79
  97. BROWSER 79
  98. APPENDIX: ADVANCED TOPIC ON DOD 80
  99. APPENDIX: UDO 86
  100. APPENDIX: TOD 87
  101. HOW TO IMPLEMENT TOD 88
  102. Step 1: Update the Code 89
  103. Step 2: Upload the file 90
  104. Step 3: Design the Forms 90
  105. Step 4: Create an Invalidation Stream 91
  106. Explicit TOD 92
  107. Phoenix TOD 92
  108. How host servers know tool versions 93
  109. How host servers know that a new tool has been downloaded 93
  110. APPENDIX: JOHNSON GRACE - ART, ART PLUS & ART DOC 95
  111. APPENDIX: MAPI 99
  112. APPENDIX: FORM & CONTENT TOOLS 101
  113. FORM_EDIT 101
  114. LIB_EDIT 102
  115. COPYUSER 102
  116. CONFIGURE 102
  117. BUMP USER 102
  118. WATCH 102
  119. RAINMAN. 103
  120. APPENDIX: INFORMATION 107
  121. Utilities 107
  122. Updating Forms 107
  123. Updating the MAIN.IDX for Builds 110
  124. Test Systems 110
  125. APPENDIX: GLOSSARY 111
  126. NEWCOMER’S CHECKLIST 115
  127.  
  128.  
  129.  
  130. Introduction
  131.  
  132. The Windows client application is a client/server application with WAOL.EXE and its associated tools acting as the client and the host computers acting as the server. The client part is based on a small set of core functions system and a large set of supporting functions. The core functions, available through APIs, manage communications with Windows and the server and provide an inter-tool messaging system. The supporting functions are grouped on the basis of common functionality into tools. Tools are merely specialized custom DLLs developed by the in-house Windows Development team. WAOL tools can be identified by their extension, they have the extension AOL rather than DLL. Developers can add to the existing client functionality by modifying existing tools or creating new tools.
  133.  
  134. In much the same way that a simple Windows app. is message driven, the WAOL client is also message driven. At AOL these messages are called FDO 91 Atoms, or sometimes just Atoms. Like standard Windows messages theses atoms have several parameters associated with them. A collection of these atoms is often referred to as an atom stream. The client and its associated tools use these atom streams to perform most actions. As an alternative description one might call the WAOL client a large interpreter where the host send commands in the form of atom streams and tokens.
  135.  
  136. Throughout this document Packets, Tokens, Objects, Atoms, Atom Streams, Forms are frequently discussed. So a quick discussion of these terms is warranted.
  137. Packet
  138.  
  139. Packet is the unit of communication between the host and the client. All data that comes to/from the host servers are in the form of a P3 packet. A packets has three major parts which are Header, Token and Data.
  140.  
  141.  
  142.  
  143.  
  144.  
  145. P3 Packet P3 Packet P3 Packet
  146.  
  147.  
  148.  
  149.  
  150.  
  151.  
  152. P3 Packet TCP/IP, X.25, AOLNet
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159. …...
  160. Token
  161. Each packet always contains a token which is a 2-byte value. A Token indicates the nature of the packet and is used by the host to determine which process to send the packet to. The tokens are also used by the client to send packet information directly to the following tools: ASYNC, CHAT, CODEMAN, WAOLSOCK and XFER. If the client sends a packet to the host, the client must set the token to the appropriate value. If the host sends a packet to the client the host will usually set the packet token to some form of the “AT” token (i.e. AT, aT, At, at). The data contained in these packets are usually in atom form (although some packets contain non-atom forms of raw data, such as data associated with a file during a file transfer).
  162.  
  163. A complete list of host bound tokens can be generated on the Stratus host using: edit_token, followed by list_token. At present it appears there is no easy to use mechanism that will allow generation of a client bound tokens list.
  164.  
  165. CHAT tool intercepts the following tokens:
  166.  
  167. AA : Normal chat message
  168. AB : Chat message with name
  169. AC : Chat message with count
  170. AD : Auditorium count msg.
  171. CA : User entry
  172. CB : User exit
  173.  
  174. The ASYNC tool (ASYNC.AOL) intercepts the following tokens:
  175.  
  176. D3 : Causes a message to Codeman which sends a D6 token
  177. OT : Display Alert Message
  178. XS : Force Off and Hang up
  179. hO : Luanch a PC Game
  180. DSTAR (D*) : Disconnect
  181. STARSTART (**) : P3 Release - Not used any longer
  182.  
  183. The XFER tool (XFER.AOL) intercepts the following tokens:
  184.  
  185. tj : The packet contains info about file we're getting ready to download
  186.  
  187. The following tokens are intercepted by XFER, but it does not do much with them. The cleint is slowly migrating to using th AT token exclusively. The following tokens were used by the client at one time.
  188.  
  189. ta : file flags, count, size, and filename to be D/Led
  190. tf : receive D/L file; host requests immediate xG ack (?????)
  191. F8 : receive D/L file; host requests immediate xG ack
  192. FF, F7 : receive D/L file; no immediate ack required
  193. F9 : receive D/L file; this is the last packet of the file
  194.  
  195. fX, tN, tt, td, th, ti, tc, tx : Upload Token
  196.  
  197. If and when data, such as image data, is required for the form the client will send one of the following tokens to the host ‘f2’, ‘ff’, ‘fh’. These tokens are specifically reserved for DOD requests.
  198. Object
  199. Within WAOL an Object is any MDI child window, button, listbox, combobox, text field, static text, toolbar, tab control and image view. Each of these objects is fully described by a DISPLAY_OBJECT structure in AOLMAN.AOL. The definition for this structure is static and non-changing. It is one large structure containing every possible variable definition for any type of WAOL object. For any given object this structure is only partially used with the rest of variables being set to NULL. Refer to Manager chapter for detailed information.
  200. Atom
  201. Atoms can be sent by the host to the client and vice versa. All atoms have a Class and a Protocol associated with them. Class, in this case, refers to a type of atom. More specifically Class refers to the source from which the atom originated from and Protocol refers to the destination for the atom. An atom type is more fully defined by referring to an atoms Class and Protocol type. The Class and Protocol of an atom are used, by the client’s “Dispatcher” to determine which AOL tool’s ToolAtomHandlers to call.
  202.  
  203. Atoms are basically host or client based instructions to perform various actions. All atoms are uniquely numbered within their protocol. All client tools with tool atom handlers can accept atoms and act on them. An atom stream is nothing more than a series of atoms. It should be noted that atom stream are sent back and forth to enable interaction between the client and the host. (Atom streams are typically assembled in AOLBUF.AOL.)
  204.  
  205. The Key atom sets are broken out by logical function groups:
  206. • UNI (aolact.aol): This set is responsible for governing the flow of streams .
  207. • IF (aolact.aol): This set of atoms allows the programmer to test conditions.
  208. • VAR (aolact.aol): These atoms are used to move data into, out of, and among the client registers.
  209. • ACT (aolact.aol): This is for the control and implementation of action streams in a form. There are three ways to perform actions in a form:
  210.  Using ACT_REPLACE_SELECT_ACTION to associate an action with the pressing of the button.
  211.  Using ACT_SET_CRITERION to establish an action when predefined conditions are met.
  212.  Using ACT_DO_ACTION to implement a subroutine like action in a form. This method allows for greater reusability and flexibility of action streams.
  213. • MAN (aolman.aol): It defines the creation of objects and the layout of those objects within a form. It also used to select of parts of forms for modification and data extraction.
  214. • MAT (aolman.aol): This set of atoms works together with MAN atoms to set the attributes for the objects created by MAN atoms.
  215. • BUF (aolbuf.aol): Handles the client buffer system. These buffers are used to hold data that can then be sent to the host or stored in the database (main.idx).
  216. • DE (aoldata.aol): Work directly with the client buffers to extract data from objects and place them in buffers for storage or to be sent to the host.
  217. • IDB (aolidb.aol): These atoms are used to store or retrieve data from the database (main.idx).
  218. • FM (aolfiler.aol): This atom set allows the user to do limited direct I/O with the users harddrive. This is often a very difficult process as the method of defining a disk operation requires the setting of many individual FM registers. These atoms also allow the programmer to do a broadcast of a file type message to all tools that might also be interested in particular file operation.
  219. • CM (aolcode.aol): The CM atoms are responsible for the management of client tools. These atoms allow the definition of a TOD or tool replacement and allow for the verification of tools and tool versions.
  220. • ASYNC (aolasync.aol): It contains many useful atoms for popping messages, signon and signoff .....
  221. • SM (aolshort.aol): This is a collection of atoms that are step saving atoms (shorthand atoms).
  222. • DICE (aoldice.aol): These atoms take care of the connectivity setup.
  223.  
  224. Atom Streams (FDO 91 Interpreted Scripting Language)
  225. We have emphasized that the client is Atom driven. A sequence of atoms which will perform a meaningful task is called atom stream. Atom stream is the basis of all objects and actions displayed and performed on the client. The Menubar, Toolbar, and all forms displayed by the client are created through the use of atom streams. These atom streams are extracted from the local database (main.idx) or are sent to the client from the host. After the client releases host can send down atom streams to enhance or correct existing client functionality remotely. Sometimes Atom is referred as FDO 91 as this scripting language is designed in 1991. FDO 91 is designed for both Windows and Macintosh platforms.
  226.  
  227. Atom streams are typically assembled in text from using a wordprocessor or form_edit. The resulting text file is then compiled into a binary file using a host based tool called form_edit. These compilations consist of nothing more than replacing the text based form of the atom with its numeric form. (All the atoms are defined in Atoms.h. in the client code. There is also a similar file on the host.) The resulting binary is loaded into a host process. The user can then accesses this via the AOL client. Typically the atom stream could represent a new form or set of forms used by the client.
  228.  
  229. When a user goes to access this new form, perhaps by clicking on a button in another form, the client will send a token to the host (such as the f1 token). The retriever process, on the host, will receive the request and retrieve the requested data from the host’s retriever.file. The host will send the binary atom stream, associated with this request data, or form, to the client.
  230.  
  231. Of course atoms and associated client bound data are wrapped inside of the P3 packet. The MODEM tool will receive the P3 packet data from the comm port. It sends the data directly, via a pointer to a P3 function, to the P3 tool. In the case of the MAN_UPDATE_DISPLAY atom, P3 will send the packet info to the Atomizer in Supersub.dll. The Atomizer will strip the packet and broadcast this atom and any associated data (using a mechanism discussed elsewhere in this document) to the MANAGER tool, specifically the ToolAtomHandler. The ToolAtomHandler uses a large CASE statement to determine which actions to take. In the case of MAN_UPDATE_DISPLAY it will execute a function called: UpdateDisplay. UpdateDisplay will actually create a MDI Window form on the users screen.
  232.  
  233. FORMS
  234. Forms are nothing more than MDI Windows on the Client screen. Typical forms contain a wide variety of gadgets including list boxes, buttons, text fields, images, etc. The description for a form is manifested in an atom stream or is stored in the main.idx database (main.idx database can be found in the client dir. AOL\IDB). If a form does not exist in the main.idx database then it must be sent by the host. The client requests this form by sending a token to the host. There are many different tokens that can be sent that will result in the transmission of form data to the client. The host contains a lookup table that it uses to determine if form data is being requested. The retriever process, on the host, will receive the request and it retrieves the requested data from the host’s retriever.file. The host will send the binary atom stream, associated with this request for data, or form, to the client. The host will send the form to the client using atom streams.
  235.  
  236. The client and associated tools can also send atoms amongst themselves. Typically the client sends itself atoms when a WAOL tool requests a form that is local to the client. Instead of asking for the form from the host it pulls the atom stream, associated with the form, from the local database, Main.idx. This is much quicker and reduces the amount of host intervention. Typically forms such as the sign-on screen, welcome screen form, main menu, address book, and exit form are stored in the main.idx.
  237.  
  238. There are three basic types of forms. These forms are usually created in-house by AOL production staff. A number of tools are available to create these forms. Most of these tools are host (Stratus or Unix) based tools and require some training to use.
  239.  
  240. 1. Library forms (created by the Stratus lib_edit tool and handled by the Stratus Library process. These forms are very rudimentary and only work for collections and articles.)
  241.  
  242. 2. Retriever forms (created by the Stratus form_edit tool and handled by the Stratus retriever process)
  243.  
  244. 3. Canned forms (created/modified by a Stratus text editor and turned into executables using the Stratus compile_canned_forms process. These forms are handled by the process named in the <process_name>.canned file. Most processes use canned forms in some way, shape, or form. soft_box, for example, displays the form that lists files in a software library, while soft_text displays the description text that relates to a particular software library file.)
  245.  
  246. Forms can also be generated by creating a custom atom stream. However, this requires expertise at a fairly high level, and requires some knowledge of the WAOL client system architecture. Typically custom forms based on custom atom streams are developed in-house by the Platform Development group.
  247.  
  248. Forms required for offline use and very prevalent forms are stored in the main.idx database in atom stream format. However, a large number of forms contain variable information and are typically not stored in the database.
  249.  
  250. Most forms are generated by AOL Producers. They typically use a tool known as Form Edit (form_edit). This tool is a text based tool located on the Stratus system. When a Producer uses form edit to create a Window with buttons, listboxes, check boxes, text , and images. Form Edit then compiles the data they enter into an atom stream. They then install the form onto the host production computers for use on the service.
  251.  
  252.  
  253. Client Overview
  254.  
  255. The client application contains the following tools and DLLs:
  256.  
  257. Core Client
  258.  
  259. AOL.EXE : Does a window execution of WAOL.EXE
  260.  
  261. WAOL.EXE : The Main Application for AOL. It manages the client MDI frame and performs startup, shutdown and initilization procedures. It also handles crash message and stores the necessary GPF phone home data on file PH.PH.
  262.  
  263. SUPERSUB.DLL : Handles IDB atoms. Contains tool loader, message dispatcher, message queues, memory management, Performs TOD per Codeman tool’s instructions. Handles incoming Atoms/Atom Streams and then dispatches each of them to tools. Loaded by WAOL.EXE
  264.  
  265. NLS.DLL : International DLL - Handles International strings and provide language specific APIs.
  266.  
  267. BUTLER.OBJ :General Purpose Statically linked Library (Used by many tools.)
  268.  
  269. KERNEL.OBJ :Atom Handling & Context Handling Statically Linked Library (Used by many tools and DLLs)
  270.  
  271. Tools
  272.  
  273. AOLACT.AOL : Handles ACTION, IF, and VAR atoms. This tool provides the ability to define and manage actions.
  274.  
  275. AOLAPI.AOL : Obsolete, do not use. (Third party AOL API).
  276.  
  277. AOLASYNC.AOL: Handles ASYNC atoms. Sets up Init Packet Structure, handles sign-on atoms, miscellaneous APIs.
  278.  
  279. AOLBUF.AOL : Handles BUF atoms. Packet Builder tool that assembles Atom Commands into outbound P3 packets
  280.  
  281. AOLCHART.AOL: Charting tool for Stock, and weather charts, etc.
  282. CHARTLAN.DLL: Charting DLL used in conjunction with AOLCHART.AOL
  283.  
  284. AOLCHAT.AOL : Handles CHAT atoms, Chat Room tool
  285.  
  286. AOLCODE.AOL : Handles CM atoms. Manages tools, handles TODs, Tracks TODs, handles Poison tree
  287.  
  288. AOLCONV.AOL : Converts the old PFC and Address book to the latest format. This tool should only be loaded once.
  289.  
  290. AOLCSL.AOL : Comm. Connection Language Interpreter. Interprets CSL scripts for Network & Modem connection
  291.  
  292. AOLDATA.AOL : Handles DE atoms. Data extractor, extracts & manipulates data from fields in windows
  293.  
  294. AOLDICE.AOL : Handles DICE atoms. DICE stands for Device Independent Connectivity Engine. This is an abstract layer for locality and connectivity setups
  295. AOLCOMM.DLL: Communication APIs
  296.  
  297. AOLEXAPI.AOL: DIL - Download, install and loader.
  298.  
  299. AOLFILER.AOL : Handles FM atoms. File handling & management file based I/O tool, Read/Save File Common Dialogs
  300.  
  301. AOLGAL.AOL : Handles GALLERY atoms. Image Gallery tool used to create thumbnails and to display thumbnail images
  302.  
  303. AOLLIST.AOL : Handles list in list boxes
  304.  
  305. AOLMAN.AOL : Handles MAN, MAT and DOD atoms. Handles MDI Window creation and display of Windows, buttons, listboxes, etc. Contains DISPLAY_OBJECT tree and initiates execution of action streams
  306. MANUTILS.DLL: Utility routines used by Manager tool and its related other DLLs
  307. OBJWRAP.DLL : Display object related routines used by Manager tool and its related DLLs
  308. OBJNDRCT.DLL: None display object related routines used by Manager tool and OBJDRCT.DLL
  309. OBJDRCT.DLL : Display object related routines used by Manager tool
  310. DRAGMAN.DLL: Drag and Drop related APIs
  311. IMGLIB.DLL : Accusoft Image library for displaying bitmaps
  312. JGAOL.DLL : Johnson Grace Drag & Drop & ART Stuff /Loaded by Manager
  313. JGAWAOLS.DLL: Johnson Grace Audio Decoder
  314. JGDWAOL.DLL : Johnson-Grace Interface
  315. JGEWAOL.DLL : Johnson-Grace Encoder
  316. JGFRAOL.DLL : Johnson-Grace Foreign Image Decoder (GIF, JPG, BMP)
  317. JGMDAOL.DLL : Johnson-Grace Midi Decoder
  318. JGPLAOL.DLL : Johnson-Grace main ART play for decoding ART 4.0 and below
  319. JGSDAOL.DLL : Johnson-Grace Speech Decoder
  320. JGSHAOL.DLL : Johnson-Grace Slide Show Decoder
  321.  
  322. AOLMIP.AOL : Handles MIP atoms. Mail Interface tool used to handle mail and transfer of large amounts of text to views
  323.  
  324. AOLMMI.AOL : Multimedia Interface tool (uses MCICommands to implement WAV, AVI, MIDI)
  325.  
  326. AOLMODEM.AOL : Direct interface to Modem (Like a Modem Device Driver)
  327.  
  328. AOLMORG.AOL : Handles MORG atoms. Multimedia Organizer for PFC, Favorite Places and Address Book.
  329.  
  330. AOLP3.AOL : P3 Packet Handling : Transfers P3 data packets between the AOL Client & Server
  331.  
  332. AOLRICH.AOL : Handles RICH atoms. Handles creation of Rich views for Hyperlinks and rich text (bold, italics, underline, color)
  333. PGCNTL32.DLL : Datapac's Rich text engine DLL, used by AOLRICH
  334.  
  335. AOLSEC.AOL : Security tool. Handles screen name encryption and login hand shakes with the host
  336.  
  337. AOLSHORT.AOL: Handles SM (shorthand) atoms (super atom concept, atom represents common combo of atoms used for function such as extracting and sending form field data to the host)
  338.  
  339. AOLSOCK.AOL : Primary interface between browser & P3
  340.  
  341. AOLSPELL.AOL: Spell checker. Handles SPELL atoms and interface with dictionary and spell checking DLLs
  342. PDDLLWIN32.DLL: Personal spell checking dictionary
  343. PRDLLWIN32.DLL: Mail spell checking DLL
  344.  
  345. AOLTCPIP.AOL : Interface to TCP/IP networks via Winsock, bypassing modems (bypass the MODEM tool)
  346.  
  347. AOLVID.AOL : Handles VID atoms. Video capture tool
  348.  
  349. AOLWWW.AOL : Client Interface, WWW View, to Browser engine allowing the use of FDO91 forms, Interface with IWENG.DLL
  350. IWENG.DLL : Internet Works Engine Browser
  351.  
  352. AOLXFER.AOL : Handles XFER atoms. Process the file transfers between the client and server (not used by browser)
  353. DZIP.DLL : PKZIP used in mail for multiple file attachments
  354. DUNZIP.DLL : PKUNZIP used in mail download.
  355.  
  356. IMFBMP.AOL : BMP image filter (Converts BMP to DIB)
  357. IMFGIF.AOL : GIF image filter (Converts GIF to DIB)
  358. IMFJPG.AOL : JPG image filter (Converts JPG to DIB)
  359.  
  360. AOLPHX.EXE : Bounces WAOL (Auto Logoff & Logon).
  361.  
  362. Other Files:
  363. MAIN.IDX : Contains forms, DOD artworks, usernames and password.
  364. DIAG.DAT : Encrypted File contains diagnostic Data about WAOL
  365. (Created by pressing Ctrl-Alt-D)
  366. SPOOL.LST : List of Files to Download and then immediately erase (Such as Weather Maps) (AOLXFER.AOL)
  367. CSL Files : Comm. Connection Language scripts particular to the Network Type (AOLNet.csl, Global.csl, etc.)
  368. GLOBAL.ORG : Stores connectvity settings and access numbers. It is a file in MORG format.
  369.  
  370.  
  371. WAOL.EXE starts up and loads SUPERSUB.DLL which then loads all the tools under Tool directory except the delayed tools. The loading procedure has been optimized by loading minimum number of tools at the startup in order to gain the maximum speed. The list of delayed tools is stored in database (main.idx). The delayed tools are loaded on demand (when there is a function call to these tools). Some of the tools have their own associated DLLs which will be loaded when the tool is loaded. For example MANUTILS.DLL, OBJDRCT.DLL, OBJWRAP.DLL and OBJNDRCT.DLL are loaded together with AOLMAN.AOL. See the list above for DLL associations.
  372.  
  373. There are three ways for the client to communicate with other tools. The first one is the atom messages which gets sent out from the ATOMIZAR and DISPATCHER (in Supersub.dll) to its associated tools. The atoms are usually handled by ToolAtomHandler. The second way is for each tool to talk to another tool through its specialized messages which perform some of the same functions as an atom. These messages are used to communicate directly with various tools and thus by passing the host and the intermediate atom stream controls and tools within the client. These internally derived messages are usually handled by ToolMsgHandlers. The last method is for each module to broadcast specific notify messages to all other tools. Each tool will listen and process the notify messages it cares about in ToolNotifyHandler. Notify message is very expensive when there are many tools.
  374.  
  375. The following chart shows how the client communicates with its tools and DLLs by parsing and handling atom streams.
  376.  
  377.  
  378.  
  379. As the chart shows, the atom streams are encapsulated in a P3 packet and transmitted down the communications line. (The communications line is typically a phone line or an ethernet line. See the chapter on P3 for further details on P3.) The P3 packet arrives at the modem, is captured by the client, validated and stripped of its header, and the token and associated data contained in the packets is broadcast, via a dispatcher, to tools that handle tokens. (The dispatcher is the set of functions responsible for handling the broadcasting of tokens, atoms, and messages to various client tools, see: Supersub.dll for further details.) If the token is an AT token, which usually constitutes most of the traffic when the client is trying to render forms, it is usually sent to the atomizer (which is also part of supersub.dll) for parsing, then broadcasts the atom and associated data, via dispatcher, to all tools that have registered themselves to accept atoms. The atom stream data is broadcasted one atom at a time. Each WAOL tool, that can handle atoms, contains a special WAOL function called a “ToolAtomHandler.” The appropriate WAOL ToolAtomHandler captures the atom message and performs the necessary action as described by the atom.
  380. How client handles a simple form from the Host to the Client
  381.  
  382. A simple form that the host could send to the client would be described by the following atom stream.
  383.  
  384. 0 atom$uni_start_stream
  385. 1 atom$man_start_object <ind_group> ""
  386. 2 atom$man_start_object <trigger> "DISCOVER AOL FORM"
  387. 3 atom$act_replace_select_action
  388. 4 atom$uni_start_stream_wait_on <0>
  389. 5 atom$sm_send_f1 <0-40-5242>
  390. 6 atom$man_end_object
  391. 7 atom$man_update_display
  392. 8 atom$uni_wait_off
  393. 9 atom$uni_end_stream
  394.  
  395. This atom stream will create a simple MDI Window with a button titled: "DISCOVER AOL FORM." Pressing this button will cause the f1 token along with a form ID, in this case the Discover AOL form, to be sent to the host. The host would respond by sending the Discover AOL form atom stream to the client and causing the Discover AOL form to be displayed.
  396.  
  397. In the above example two objects will be created. The first being a MDI Window or form and the second being a Button. This button will have an action assigned to it. This action will be: SM_SEND_f1.
  398. The send SM_SEND_f1 action and the global ID 0-40-5242 will be sent to the host computer. When this button is clicked a ToolSendMsg command will braodcast the SM_SEND_f1 atom to the tool AOLSHORT.AOL. The routine ToolAtomHandler in AOLSHORT.AOL will intercept this message and send the f1 token and global form id to the host. The specific set of actions, once the atom enters the tool SHORT’s ToolAtomHandler are as follows:
  399.  
  400. 1. ToolAtomHandler traps SM_SEND_f1
  401. 2. SM_SEND_f1 calls RequestObject
  402. 3. RequestObject checks to see if form is already created, if so it brings it to focus using “Magic.”
  403. 4. If the form is not currently available the main.idx database is asked if it contains the form. If so the form is retrieved from the main.idx and invoked.
  404. 5. If the form is not available on the client then the function SendImmediateLong is called. It in turn calls the BufferClose function (see AOLBUF.AOL). BufferClose sends the f1 token and data to P3 which in turn sends it to the MODEM tool which sends it down the phone line to the host.
  405. 6. The host then responds by sending the atom stream for the associated f1 token and form ID (GID) back to the client for display on the client monitor.
  406.  
  407. This stream can be contained in one P3 packet that consists of a block of data and the AT token. If the host system were to send this packet to a user it would typically be transmitted down the communication line. In the case of a phone line, the P3 packet arrives at a user’s modem, is captured by the client via the MODEM tool. When this packet arrives the MODEM tool retrieves the data from the comm. port connected to the modem and sends it directly to the P3 tool. The P3 tool validates the packet and strips it off its header, and the token and associated data contained in the packets is broadcast, via a dispatcher, to all AOL tools that have register themselves to except tokens. The dispatcher broadcasts the data using a Dispatcher function called ToolSendMsg. The ToolSendMsg function will send the token and associated data to each tool by actually calling each tool’s ToolTokenHandler function and passing the data via the functions arguments. Each ToolTokenHandler will inspect the token using a large case statement. If a match is found that tool acts on the data and returns a TRUE, else it passes the data and returns a false. If a false is returned the ToolSendMsg function then proceeds to call the next ToolTokenHandler in its list.
  408.  
  409. In the case of the above example the ATOMIZAR would intercept this packet because only it uses the AT token. The ATOMIZAR would take the packet, and its associated atom stream and data, and process it. It would parse the data into single atom elements, in this case four atoms or lines. Each atom would then be broadcast, in order, to all tools registered to accept atoms. Each atom would be broadcast using the ToolSendMsg function and would work in much the same manner as described above except that it would now call only the ToolAtomHandlers for tools that have register themselves to accept atoms.
  410.  
  411. In the above example the very first atom would be intercepted by SUPERSUB.DLL. The Universe module of the ATOM tool would receive the atom UNI_START_STREAM and initiate the opening of the stream.
  412.  
  413. The second atom MAN_START_OBJECT would be intercepted by AOLMAN.AOL’s ToolAtomHandler. It would allocate memory for a large structure called DISPLAY_OBJECT. The DISPLAY_OBJECT is the base object used to describe and contain each and every object created in WAOL. In this case object refers to an MDI Window, Button, Listbox, Text Field, Checkbox and Picture field. This structure contains a wide variety of variables to cover all possible objects. It includes things like the object’s Windows’ handle, the type of object, any short cut keys, handle to its font, its location on the screen, and much more. This structure is the same size for all objects. Of course many of these variables do not apply to all objects so some overhead is acquired as a result. The MAN_START_OBJECT atom also will cause many of these variables in this object to be initialized with default variables. The type of default values are indictated by the parameter associated with MAN_START_OBJECT, in this case <ind_group> represents a simple MDI Window.
  414.  
  415. Atom “atom$man_update_display” in the above example will actually take the object that was created by the MAN_START_OBJECT and display it on the users monitor. In this case a MDI Window and a button will appear on the user’s screen.
  416.  
  417. Atom “atom$act_replace_select_action” is the start of an action stream which is associated with the button. When the button is pressed the next two atoms followed will be executed. This atom is handled by AOLACT.AOL which will simply store the action stream and associate it with the button object.
  418.  
  419. The very last atom, UNI_END_STREAM will end the stream. At this point all processing of this Window, by the WAOL client, will cease until the Window is manipulated by the user or destroyed.
  420.  
  421. See the Chapter MANAGER for additional detail on the creation of FORMS.
  422.  
  423. Client Core - WAOL.EXE
  424.  
  425. WAOL.EXE contains the main procedures and main message looping for managing the client MDI frame. It performs startup and shutdown procedures and some initialization tasks, including loading SUPERSUB.DLL, setting timer system and loading the crash recovery functions. All the handles to the MDI Frame and the MDI Child Windows are stored in a global structure that is created in WAOL.EXE
  426.  
  427. When WAOL.EXE launches it does the following:
  428.  
  429. • WAOL.EXE loads and launches
  430. • Supersub.dll is loaded into memory
  431. • WAOL checks to make sure App is not already running, if yes then exit.
  432. • Supersub sets up Application memory management
  433. • Database indexes, such as main.ind, are created if missing
  434. • MDI Client Frame is created
  435. • All Tools are loaded via Loader, in Supersub.dll, and being initialized via ToolInit and MSG_NOTIFY_APP_STARTUP
  436. • Addresses for all Tool's ToolHandler functions are stored in Loader's table
  437. • Poison Tree is setup - When tool Codeman loads
  438. • Root of the object gets created
  439. • The Main.idx database is accessed for one large start-up action stream (GLOBALID_APP_INIT)
  440. • Main Menu bar is retrieved from Main.idx and placed on the root and displayed
  441. • Toolbar is retrieved from Main.idx, placed on the root and displayed
  442. • Sign-on Screen is retrieved from Main.idx placed on the off-line cluster and displayed
  443.  
  444. Whenever a main menu item on main Window menu bar is clicked Windows sends a WM_COMMAND message to AOLMDIFrameProc (see WAOL\WAOLPROC.C). AOLMDIFrameProc intercepts the WM_COMMAND message and passes it on to the HANDLE_WM_COMMAND macro which uses ToolSendMsg to send the WM_COMMAND message to the ToolWMHandler in AOLMAN.AOL. The ToolWMHandler traps the WM_COMMAND message and calls the MenuHandleCommand function (see Manager\Manager.c & Menu.c) which then triggers the action stream associated with the menu item object.
  445. WAOL command line parameters
  446. Username: -n
  447. Password: -p
  448. Keyword: -s
  449. URL: -u
  450. CSL: -c
  451. LaucherName: -a
  452. CertificateNumber: -r
  453. DB Stored Commands: -X
  454. In the Main.idx, GID 20-255-39 stores all commands for –X. Example would be: hide, restore, minimize, maximize, start, setup. NOTE: syntax for start: aol/xstart:<exe filename>
  455. Change text of menu item if it is the signoff menu: -o
  456. URL Filename: -lfileName
  457. NOTE: Aol.exe will put “http”//” in front of URL if it is not there. URL filename has to be full path.
  458.  
  459. GPF Phone Home Reports
  460. In order to support one of the major client improvements ---Phone Home report. The client WAOL.EXE captures system’s message at GPF events and writes out diagnostic information out to the disk (ph.ph). Next time the client launches DICE tool will pick up the saved information and send them together with other information to the host. For 32 bit clients we call “SetUnhandledExceptionFilter(ExceptionFilter)” to supersede the top level exception handler that Win32 places at the top of each thread and process. For 16 bit client we use “InterruptRegister(NULL, ExceptionHandler)”. Both callback functions are located in waol\crash.c or aolnetc\crash.c. Please refer to DICE tool for Phone home specifications.
  461. Com Interface
  462. The latest version of windows client is also a component server with AOLnet Connect COM Interface architecture. This architecture is built around the standard Microsoft Component Architecture, and will provide for the needs of the present AOL Enterprise Thin Client product while not limiting the possibilities for future expansion. As shown in the diagram below, there is one main AOLnet Connect COM interface group, from which all other AOLnet Connect COM interfaces will be queried. This main interface is called IAOLClient. There will be four starting Client Interfaces queried from IAOLClient for the general public, and one company private (internal only) interface. These interfaces are IAOLClientSystem, IAOLClientLocalityDB, IAOLClientDeviceDB, and IAOLClientPhoneDB. For detailed information about each interface refer to COM Architecture.doc.
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469.  
  470.  
  471.  
  472.  
  473.  
  474. SuperSub.DLL
  475.  
  476. The Supersub.dll (Super Subroutine) contains a number of important fundamental blocks of code that effectively run WAOL. The supersub API logical components are described as follows:
  477.  
  478. • Loader, which loads all AOL tools (see Loader.c).
  479. • Memory and heap manager, which provides a front-end to Windows memory management and optimizes performance and memory usage.
  480. • Atomizar, which handles the atom stream
  481. • Dispatcher, which controls communication between the tools, the client software and the host.
  482. • Handles the access to main.idx database.
  483. • Maintenance, which provides diagnostic functions.
  484. • Utilities, which provides file handling and miscellaneous functions.
  485. • Communications, which provides a common communications interface between tools.
  486.  
  487. Loader
  488.  
  489. In the process Loader will load each tool using the LoadLibrary Windows API and then run the ToolInit function of each tool. It finds each module’s associated ToolInit function by using the Windows API GetProcAddress function as similar to as what follows:
  490.  
  491. Note: Simplified Example Code fragment to demonstrate start tool process.
  492.  
  493. // Load AOL Tool
  494. hTool = LoadLibrary("AOLCHAT.AOL");
  495.  
  496. / / Retrieve the address of the ToolInit function.
  497. (FARPROC) lpfnInit = GetProcAddress(hTool, "ToolInit");
  498.  
  499. //Execute the ToolInit function
  500. nResult = (*lpfnInit)(lpGlobalEnv->hWndMDIClient,
  501. lpGlobalEnv->hWndMDIFrame,
  502. lpGlobalEnv->hWndToolbar, lpGlobalEnv->hWndStatus,
  503. lpGlobalEnv->hInst, lpGlobalEnv, lpTool,
  504. fRestart);
  505.  
  506. Specifically the way loader accomplishes this is through the use of a WAOL function called StartTool. StartTool uses a WAOL function called LoadToolModule which uses LoadLibrary to load the AOL tool into memory. Then StartTool uses a WAOL function called InitTool which uses GetProcAddress and then executes the *lpfnInit(...) function (ToolInit).
  507.  
  508. There is a table stored in main.idx for a list of delayed loading tools. Loader checks if a tool is in the table before loading the tool. If a tool is in the table it will not be loaded until it is called by other modules. This optimizes the speed of the application startup.
  509. ATOM handling (dispatching)
  510.  
  511. The Atomizer receives packet data from the P3 tool. The packet data is received through the
  512. ToolTokenHandler. The tool token handler then sends the data to the ProcessAtomStream function that eventually broadcasts the stripped packet data to the appropriate AOL tools. Detail as the following:
  513.  
  514. Data Comes into the Computer through the Modem
  515. ||
  516. \/
  517. ModemTimerHandler //aolmodem.c, Timer Based Callback retrieves raw P3 data from Modem
  518. || // This is the callback function set up by a SetTimer function for 125ms
  519. \/
  520. ReadEventHandler //aolmodem.c retrieves raw P3 data from Modem comm port
  521. ||
  522. \/
  523. DataFromCommTool //aolcomm.c, This does not use a normal AOL ToolHandler to transfer
  524. || //This uses the actual P3DataHandler address.
  525. \/
  526. P3DataHandler //P3.c
  527. ||
  528. \/
  529. HandlePacket //P3.C
  530. ||
  531. \/
  532. Place Packet in Queue //P3.C, QueueInputPacket
  533. ||
  534. \/
  535. DispatchPacket //P3.C
  536. ||
  537. \/
  538. ToolSendMsg(CLASS_TOKEN, //P3.C, Note: ToolSendMsg Def. in Disp.C
  539. PROTO_NOTIFY,
  540. MAKEWORD(lpPacket->data[0], lpPacket->data[1]), //The atom, (first two bytes of P3 packet)
  541. &nResult,
  542. 2, //Number of arguments
  543. (LONG)(LPSTR)&lpPacket->data[2], // The P3 packet data
  544. MAKELONG(Flipitw(lpPacket->wLength) - 4, 0)); // The length of the data
  545. ||
  546. \/
  547. ToolTokenHandler //Atomizer.C (It can go to other Tool’s such as: XFER, ASYNC, CHAT, CODEMAN.)
  548. ||
  549. \/
  550. ProcessAtomStream //Atomizer.C
  551. ||
  552. \/
  553. DoAtomStream //Atomizer.C
  554. ||
  555. \/
  556. ProcessAtom //Atomizer.C
  557. ||
  558. \/
  559. GiveAtomToProtocol //Atomizer.C
  560. ||
  561. \/
  562. ExecAtom //Atomizer.C
  563. ||
  564. \/
  565. ToolSendMsg(CLASS_ATOMS,lpAtm->wStreamProtocol, wAtom, lpnResult, //Send atom & Data to tools
  566. 6,lpAtm,lpData,MAKELONG(wLen,wAtom), dwSid,
  567. (LONG)(DWORD)lpAtm->lpObject,lpAtm->lValue);
  568. ||
  569. \/
  570. The Atom and data now go to the appropriate AOL tool.
  571. IDB – main.idx
  572.  
  573. Supersub.dll also contains the Database Manager which provides support for the storage and retrieval of data records in the online service client application's main database MAIN.IDX. Various record types and attributes are supported. A unique global ID identifies each record in the database. The Database Manager performs space reclamation tasks in order to keep the database size to a minimum.
  574.  
  575. The MAIN.IDX database is used by the client to store a variety of local client data records. The database
  576. contains the following:
  577.  
  578. • Forms (all offline forms and some online forms, typically frequently used, non-changing forms)
  579. • Action atom streams
  580. • Icons
  581. • PICs
  582. • DOD Artwork
  583. • Screen names and passwords
  584. • User's current locality
  585. • Last Access number used
  586. • Preferences
  587. The Database Design
  588.  
  589. The Main.idx database design includes a permanent index file, main.ind. This index file will contain a set of indices that will be read at WAOL launch time. The index will be read into a B-Tree structure, in ram. The B-Tree structure will be used to help reduce database search times when the client is trying to access records.
  590. B-Trees
  591.  
  592. Disks allow random access to all records stored, but the time required for such an access is great compared to internal memory speeds. There is a high overhead in time to initiate an access - i.e. a transfer of records from the disk to internal memory. Efficient organization of tables on disk thus requires minimizing the number of times such an access is initiated and transferring large numbers of records on each access.
  593.  
  594. Since accesses are costly compared to probes, it is preferable to make many probes for each disk access. Thus to adapt search trees to disks we use m-way branches instead of two-way (binary) branches. Typically, m will be several hundred; the best choice for m depends on the precise physical characteristics of the storage device (access and transfer time), the sizes of the elements in the table, and the amount of internal memory available to store elements. As with binary trees, it is quite time consuming to keep the tree perfectly balanced while inserting and deleting: We only insist that all paths from the root to a leaf node are equal length and that each node except the root has at least [m/2] sub trees. Such a tree is called a balanced multiway tree or B-tree.
  595. Improving Launch Speed with Permanent Index File
  596.  
  597. The old database design always created the index to the database each time WAOL was launched. It did this by reading the entire main.idx database at launch and storing this index in memory. This would take significant amounts of time in cases where the main.idx was large (i.e. 20 MB) primarily due to disk drive read time. When WAOL terminated the index would be lost. The new permanent index will significantly reduce launch time because no index needs to be created at launch. Instead it is always saved to a file whenever WAOL terminates and read back in when WAOL launches. Since the index file is relatively small (less than 50K) the amount of time to read it in is very small and thus the application can launch quicker.
  598. Improving Record Access with Better Indexing
  599.  
  600. As the main.idx gets very large (i.e. greater than 20Mb, and more than a few thousand records) accessing records in the database will take longer and longer. It takes longer because sequentially walking through a linear index, like the old index, will take longer. As the linear index gets longer the search will take longer on average. Although it will be barely noticeable on fast machines, it will be noticeable on older machines. On a 386 16Mhz machine a simple index search on 40,000 indices took 400 milliseconds whereas the same search on a 486 66Mhz and 90Mhz Pentium takes 33 and 17 milliseconds respectively. Also with main.idx databases exceeding 10,000 records and heading for 100,000 records RAM space for the index will soon become an issue. (Each index entry contains a four-byte GID and a four byte file offset plus a 4 byte pointer to the next index in the linked list and 4 byte pointer to the previous index location, for a total of 16 bytes.) With 16 bytes per index and 100,000 records this would require 1.6Mb of the users RAM. Using this much RAM could cause many kinds of complications that users would not be happy with. There are currently 20 keys per page.
  601.  
  602. One solution is to store this linear index on the disk. However, then the search times go up by enormous amounts due to disk speed limitations. One way around the disk speed limitations is to implement the index on the disk in a Balance Multiway Tree format, or B-Tree. This will significantly reduce the amount of time required to search the index on the disk because significantly fewer accesses are required. Instead of sequentially searching, it will jump, at most three to four times, to the GID entry and its respective file offset in the main.idx. It should be noted that B-Trees were originally designed to deal with searches on disk drives and magnetic media and as such are a better alternative than binary trees when doing searches on drives.
  603.  
  604. When WAOL launches it will always check the main.idx database for the format type. If it is the old type it will automatically do a conversion to the new type. If the index file is missing WAOL will create a new one.
  605.  
  606. WAOL will not launch properly if the Main.idx is missing.
  607. Deletion of Records
  608.  
  609. Records will be deleted from the database using Least Recently Used (LRU) algorithm, by access date.
  610. If one of two records with the same access date is to be deleted the smaller of the two will be deleted.
  611.  
  612.  
  613. TOOLS - Overview/Implementation
  614.  
  615. AOL tools are DLLs with the extension DLL replaced with AOL. These tools contain the supporting functions used by the America Online Windows client program (WAOL).
  616.  
  617. Each new AOL tool must have some basic code incorporated into it to work with WAOL. At a minimum each new tool must have a ToolInit and a ToolEnd function. In addition to the ToolInit and ToolEnd functions, optional tool handler functions are often provided. These tool handlers are the communications interface between the tool and the main application and other tools.
  618. ToolInit
  619.  
  620. int API ToolInit( HWND hMDIClient, HWND hMDIFrame, HWND hWndToolbar,
  621. HWND hWndStatus, HINSTANCE hInstance,
  622. LPGLOBALENV lpGlobal, LPTOOLINFO lpTool, BOOL fRestart)
  623.  
  624. The ToolInit function uses ToolRegister (see below) to register the appropriate tool handlers required by the given tool. Each AOL tool will have a function by the name of ToolInit (and a matching ToolEnd).
  625.  
  626. The ToolInit function also gives the tool the handles to various windows that may be needed by the tool. The tool stores these handle values in variables private to the tool.
  627. ToolEnd
  628.  
  629. BOOL API ToolEnd(BOOL fRestart)
  630.  
  631. The ToolEnd function unregisters the appropriate Tool Handlers required by the given tool.
  632. ToolRegister
  633.  
  634. BOOL API ToolRegister(WORD wClass, WORD wProtocol, TOOLPROC lpProc, LPSTR lpProcName, BOOL fPos);
  635.  
  636. To receive messages a tool must register with the Dispatcher component of the client core. ToolRegister is usually called from within the tool’s ToolInit function.
  637.  
  638. ToolRegister registers the appropriate tool handlers required by the given tool. The available tool handler’s types include:
  639.  
  640. ToolActionHandler
  641. ToolAtomHandler
  642. ToolFileHandler
  643. ToolMsgHandler
  644. ToolNotifyHandler
  645. ToolObjNotifyHandler
  646.  
  647. Typically the tool handlers function address is passed to ToolRegister using the TOOLPROC lpProc argument. ToolRegister then uses a private function called AddObj(wClass, wProtocol, lpProc, lpProcName, fPos) to register the tool handler’s address (lpProc) with a special structure in Supersub.dll (see \\supersub\Disp.c). This special structure is LPCLASS lpList[kDEFINED_CLASSES]. This structure is a complex linked list that stores every address of every registered tool handler. The tool handler addresses are stored within this linked list structure using class and protocol as indicators to the appropriate tool handlers. ToolSendMsg and ToolPostMsg will later access this structure, using a class and protocol type, to determine which tool handler functions to execute.
  648.  
  649. Each tool ‘s tool handler will have an associated class and protocol.
  650.  
  651. Tool Unregister
  652.  
  653. BOOL API ToolUnRegister(WORD wClass, WORD wProtocol, TOOLPROC lpProc);
  654.  
  655. Used to unregister a tool that was registered with Toolregister. Usually performed in a tool’s ToolEnd function.
  656. RegisterAtomProtocol
  657.  
  658. BOOL RegisterAtomProtocol(WORD wProto, LPATOMLISTENTRY lpList,
  659. LPFNDEFAULT lpfnDefault)
  660.  
  661. Register AtomProtocol allows tools to register a list of atoms, using RegisterAtom, with a list of atom handler functions respectively. This is a fairly new development that is used in tools such as AOLRICH, MORG, WWW, MMI, AOLLIST. The Kernel.c must be linked with the tool in order to use this function.
  662. The function uses RegisterAtom to register the individual atoms and its associated function with the dispatcher.
  663. RegisterAtom
  664.  
  665. BOOL RegisterAtom(WORD wProto, WORD wAtom, ATOMTYPE atomType,
  666. FARPROC lpfnHandler)
  667.  
  668. Allows developers to have a function called directly by the dispatcher when a given atom of a certain type and Protocol arrives.
  669. ToolHandlers
  670.  
  671. The tool handlers typically take a given atom, message, or token and use it to determine which function or functions within the tool to execute. It typically uses a large CASE statement to switch the atom, message or token and make a decision to perform the appropriate action. Some AOL tools have more than one tool handler (i.e. some tools have a ToolAtomHandler, ToolMsgHandler , and ToolNotifyHandler).
  672.  
  673. Generally speaking ToolAtomHandlers handle atoms that are sent from the host. ToolMsgHandlers handle messages sent from other tools. ToolNotificationHandlers handle notification messages.
  674.  
  675. ToolAtomHandler receives and handles atoms from the host to the client. Some tools, such as Aolman.aol, have more than one ToolAtomHandler.
  676.  
  677. /* CLASS_ATOMS, PROTO_XXXX */
  678. LONG API ToolAtomHandler (WORD wAtom, LPINT lpnResult, int nArg, LPLONG lplValue);
  679. LONG API ToolAtomHandler2 (WORD wAtom, LPINT lpnResult, int nArg, LPLONG lplValue);
  680. LONG API ToolAtomHandler3 (WORD wAtom, LPINT lpnResult, int nArg, LPLONG lplValue);
  681.  
  682. ToolNotifyHandler handles system wide App. messages such as:
  683.  
  684. MSG_NOTIFY_APP_STARTUP
  685. MSG_NOTIFY_SHUTDOWN
  686. MSG_NOTIFY_OFFLINE
  687.  
  688. /* CLASS_MSG, PROTO_NOTIFY */
  689. LONG API ToolNotifyHandler(WORD wAtom, LPINT lpnResult, int nArg, LPLONG lplValue);
  690.  
  691. Smart Tool Functions
  692.  
  693. BOOL API ToolGetEnv(void);
  694.  
  695. BOOL API ToolSetEnv(DWORD dwVersion, DWORD dwKey, WORD wLen, DWORD dwData);
  696.  
  697. ToolGetEnv enables a tool to perform tasks to save its programmer-defined context before the tool is bounced. ToolSetEnv enables a tool to perform tasks to restore its programmer-defined context after the tool is bounced.
  698.  
  699. ToolSendMsg
  700.  
  701. LONG VAPI ToolSendMsg(WORD wClass, WORD wProtocol, WORD wAtom, LPINT lpnResult, int nArgs, ...);
  702.  
  703. The ToolSendMsg will send the message (wAtom) to ALL tool’s ToolHandlers that have registered class and protocols that match the wClass and wProtocol arguments. It is one of the most important communication functions in WAOL. It should be noted that ToolSendMsg will execute each and every preregistered toolhandlers under the appropriate wClass and wProtocol arguments.
  704.  
  705. Rather than using ToolSendMessages to execute tool function within other tools, tool macros are used. Since macros are easier to understand all Tool to Tool messages are sent using macros found in the WAOL.H. These macros have easy to understand names and parameters. Each macro implements its function using a ToolSendMessage with the appropriate class and protocol filled in.
  706. Advanced Topic on Tools
  707.  
  708. Tools can be updated using Tool On Demand (TOD). The TOD code lives in AOLXFER.AOL and in AOLCODE.AOL where the CODEMAN tool is primarily responsible for managing code updates and XFER tool carries out downloads of new code modules (tools). See Appendix for how to create a TOD.
  709.  
  710. ACTION
  711.  
  712. Action protocols are managed by the Action Tool (AOLACT.AOL) and consists of the following three atom
  713. command sets:
  714.  
  715. • Action
  716. • If
  717. • Variable
  718.  
  719. The Action command set allows actions to be associated with objects on forms. For example, you can set up an action to occur as the result of a member selecting an object, such as an icon, on a form.
  720.  
  721. Most forms have actionable items such as buttons and list boxes. These items typically have an “action atom stream” associated with them. When the actionable item is pressed it will invoke the appropriate action stream. These action streams are usually stored in a buffer referenced by the actionable objects data structure.
  722.  
  723. The If command set allows conditional operations to be defined in FDO91 atom streams. Many of the atom
  724. commands act on the registers set up using atoms from Variable command set.
  725.  
  726. The Variable command set allows data variable to be associated with objects on forms.
  727.  
  728.  
  729. AOLCONV
  730.  
  731. This is a new tool in AOL 4.0 where we upgrade previous version of PFC (Personal Filing Cabinet) to the new format including new folder names and locations for mail and newsgroups, new art icon for some type if items and some XFER related upgrades. This tool also merges the old address book file “address.lst” into PFC under the new subfolder name “Address Book”. The upgrades route through each screen name and process the upgrade. Address book gets copied (duplicated) to the PFC for each screen name.
  732.  
  733. This tool is loaded only once for each installation of AOL that is the first time launching the client after the installation.
  734.  
  735.  
  736. AOL Device Driver
  737.  
  738. The new AOL Device Driver is solely a Windows 95 device driver and is broken up into two major parts:
  739.  
  740. AOLMAC.VXD : Windows Virtual Device Driver
  741. AOLSOCK.AOL : AOL tool
  742.  
  743. These parts fit into the WAOL design in the following manner:
  744. Block Diagram
  745.  
  746. ATOM<=====> ||
  747. ||
  748. XFER<======> ||
  749. ||
  750. ASYNC <====> ||
  751. ||
  752. AOLSOCK<==>|| |------------|
  753. BROWSER /\ P3 <=>AOLMODEM<=> | Modem |<>=Phone Line (X.25)==...
  754. /\ || | ------------|
  755. || ||
  756. \/ ||
  757. MS WINSOCK ||
  758. /\ ||
  759. || ||
  760. \/ ||
  761. MS TCP/IP Stack ||
  762. /\ ||
  763. || ||
  764. \/ ||
  765. MS NDIS ||
  766. /\ ||
  767. || ||
  768. \/ \/
  769. < =========>AOLMAC.VXD
  770.  
  771.  
  772. These components from MS WINSOCK to P3 will be discussed below:
  773. TCP/IP
  774.  
  775. TCP/IP is the native protocol of the Internet and many Unix systems. Microsoft Windows 95 includes a new 32-bit protected mode VxD that implements a complete version of this protocol.
  776.  
  777. While there is no universal agreement about how to describe TCP/IP with a layered model (such as the International Standards Organization ISO architectural model), it is generally viewed as being composed of four layers. It is seen in the way data is handled as it passes down the protocol stack from the Application layer to the underlying physical network. Each layer in the stack adds control information to ensure proper delivery. This control information is called a header because it is placed in front of the data to be transmitted. Each layer treats all of the information it receives from the layer above as data and places its own header in front of that information. Generally we refer to transmitted data as packets. The packet format is described below.
  778.  
  779. Typical TCP/IP Layered Protocol Stack using a LAN
  780.  
  781. 4. Application Layer (Browser /WinSock)
  782. 3. Transport Layer (TCP Layer)
  783. 2. Internet Layer (IP Layer)
  784. ---------------------------------------- NDIS Interface
  785. 1. Network Access Layer (Routines for accessing physical networks, VxD)
  786.  
  787. In the case of AOL using a modem layer two is expanded. The AOLMAC then redirects communications to the AOLSOCK tool, which then communicates with P3, which then communicates with AOLMODEM which communicates directly with modem hardware (physical network). For further details see AOLMAC section below.
  788.  
  789. Typical TCP/IP Layered Protocol Stack using a Modem
  790.  
  791. 6. Application Layer (Browser/Winsock)
  792. 5. Transport Layer (TCP)
  793. 4. Internet Layer (IP)
  794. ---------------------------------------- NDIS Interface
  795. 3. AOLMAC.VxD (VxD to access IP layer)
  796. ---------------------------------------- AOLSOCK.AOL Interface (VxD to AOL interface)
  797. 2. P3 (P3 Layer)
  798. 1. AOLMODEM (Access physical layer, modem hardware and phone line)
  799.  
  800. The TCP Segment Format (TCP Header)
  801.  
  802. 0 4 8 12 16 20 24 28 31
  803. ---------------------------------------------------------------------------------------
  804. 1 | Source Port | Destination Port |
  805. ---------------------------------------------------------------------------------------
  806. 2 | Sequence Number |
  807. ---------------------------------------------------------------------------------------
  808. 3 | Acknowledgment Number |
  809. ---------------------------------------------------------------------------------------
  810. 4 | Offset | Res. | Flags | Windows |
  811. ---------------------------------------------------------------------------------------
  812. 5 | Checksum | Urgent Pointer |
  813. ---------------------------------------------------------------------------------------
  814. 6 | Options | Padding |
  815. ---------------------------------------------------------------------------------------
  816. | Data Begins Here ... |
  817.  
  818.  
  819. The IP Datagram Format (IP Header)
  820.  
  821. 0 4 8 12 16 20 24 28 31
  822. ---------------------------------------------------------------------------------------
  823. 1 | Ver | IHL | Type of Service | Total Length |
  824. ---------------------------------------------------------------------------------------
  825. 2 | Identification | Flags | Fragmentation Offset |
  826. ---------------------------------------------------------------------------------------
  827. 3 | Time to Live | Protocol | Header Checksum |
  828. ---------------------------------------------------------------------------------------
  829. 4 | Source Address |
  830. ---------------------------------------------------------------------------------------
  831. 5 | Destination Address |
  832. ---------------------------------------------------------------------------------------
  833. 6 | Options | Padding |
  834. ---------------------------------------------------------------------------------------
  835. | Data Begins here ... |
  836.  
  837.  
  838. With the advent of Windows 95 the TCP/IP stack is total encapsulated from our application. In fact it is still encapsulated from our AOL Device Driver. We communicate with the TCP/IP stack through NDIS and NDIS deals with the stack. Likewise our browser communicates with WinSock and Winsock communicates with the stack.
  839. NDIS
  840.  
  841. The Network Driver Interface Specifications (NDIS) was created by Microsoft to provide a standard API that Media Access Control (MAC) drivers, such as the AOLMAC.Vxd, can offer to network transport layers. NDIS allows many transports and MAC drivers to cooperate. NDIS interfaces with the MS TCP/IP stack. The AOLMAC.VxD interfaces with NDIS. NDIS sits below the Internet Protocol layer in the layers shown under the TCP/IP section of this document. NDIS has a set of API functions that are used by the AOLMAC.VXD to communicate with the TCP/IP stack.
  842. AOLMAC.VXD
  843.  
  844. The AOLMAC.VXD (AOL Media Access Control driver sometimes referred to as a MAC driver) is an event driven virtual device driver that is involved in all transactions between the Windows 95 NDIS and the AOLSOCK.AOL tool. It primarily transfers packets between Win 95 NDIS and the AOLSOCK.AOL tool. (As a device driver in ring 0, AOLMAC can access any memory location in the system.) One part of AOLMAC emulates an Ethernet device driver; this part of AOLMAC and NDIS call each other to exchange data. The other part of AOLMAC defines an interface used by AOLSOCK to transfer data and status information. NDIS, AOLMAC, and AOLSOCK are all event driven (they do not use polling). Even though the AOLMAC emulates an Ethernet device driver, we do not communicate with any Ethernet hardware (however Windows may think we do).
  845.  
  846. Usually all MAC drivers are at the bottom of the layered stack (as shown under the TCP/IP section of this document) and directly control hardware. Typically MAC drivers provide low level access to the network adapters. MAC drivers are loaded at initialization time and they stay in system memory. It is important to note that in the case of our AOLMAC there is no physical network adapter. Instead we are using the AOLMAC in a rather nonstandard way to communicate with. It then in turn communicates with the modem hardware.
  847.  
  848. To further clarify let me elaborate: Instead of the AOLMAC talking to hardware, the AOLMAC redirects packets to the AOLSOCK tool, which then transmits packet data to the P3 tool, which then transmits data to the AOLMODEM which communicates directly with the modem (physical network).
  849.  
  850. In essence its primary goal is to act as a middleman and transfer the appropriate data to/from WAOL and the TCP/IP stack. It receives events from the Windows 95 NDIS and responds to them accordingly.
  851.  
  852. Since the AOLMAC emulates an Ethernet device driver it receives data from NDIS in the form of an Ethernet Frame Header (sometimes referred to as a MAC header). The Ethernet Frame Header consists of the following:
  853.  
  854. • 8 byte preamble. The Preamble is always contains 10101010 in the first 7 bytes, with 10101011 in the last (8th) byte.
  855. • 6 byte Destination Address. The Destination address contains the address of the workstation that will receive this frame and is set to an arbitrary value.
  856. • 6 byte Source Address. The Source address identifies the workstation sending the frame. This number is set to a safe value. However, it is conceivable that a machine exists with this number. If so it may not work with that machine. The odds of this happening are low. Around 1 in 2 to the power of 64 (1 in 1.85 X 10 to the 19).
  857. • 2 byte Type address. The Type field contains 2 bytes of information that identify the type of higher level protocol the issued (or wants to receive) this frame.
  858. • 4 byte CRC. The CRC is the Cyclic Redundancy Checksum.
  859.  
  860. When NDIS sends this Frame containing data to the AOLMAC, the AOLMAC strips this header off before passing it to the AOLSOCK.
  861.  
  862. For additional information on Ethernet Device Drivers see: Introduction to Networking, by QUE. For more information on NDIS see Networking Device Drivers by Dhawanm published by Van Nostrand Reinhold.
  863. Initialization
  864.  
  865. The AOLMAC is initially loaded by AOLSOCK tool. When the AOLMAC device driver loads, it registers with NDIS. In particular it gives NDIS the address of the call back function that NDIS uses to send messages to AOLMAC.
  866. Transferring Data from the Internet to a PC
  867.  
  868. During runtime, AOLMAC is responsible for transferring IP data between NDIS (and effectively the TCP/IP stack) and the AOLSOCK tool.
  869.  
  870. Data destined for the PC arrive at the AOL host’s IP tunnel from the Internet. The IP tunnel sends packets to WAOL using the P3 protocol. WAOL routes packets to AOLSOCK. AOLSOCK calls AOLMAC with the packet. AOLMAC "indicates a receive" to NDIS. NDIS makes the data available to all protocols bound to the AOLMAC driver. In this case, there is only a single bound protocol, TCP/IP. The TCP stack passes data to an application through Winsock.
  871. Transferring Data from PC to the Internet
  872.  
  873. A PC application calls Winsock with data to transfer. Winsock passes data to the TCP stack. The TCP stack builds one or more IP packets and uses routing tables to determine which packets should be sent via
  874. the AOLMAC "adapter". The TCP stack calls NDIS and NDIS calls the "send" function in AOLMAC. That function stores the packet in an internal buffer and posts a message to WAOL. WAOL passes the
  875. message to AOLSOCK and AOLSOCK calls AOLMAC to transfer the packet. AOLSOCK then calls P3 to transfer the IP packet to the AOL Host IP tunnel. The IP tunnel (in Vienna) puts the packet on the Internet.
  876. AOLSOCK.AOL
  877.  
  878. The AOLSOCK for WAOL under Windows 3.1 is vastly different than the AOLSOCK in Windows 95. Under Windows 3.1 the AOLSOCK contains the entire TCP/IP stack and the interface to the client. Under Windows 95 the AOLSOCK is responsible for the interface between the AOLMAC virtual device driver and the WAOL P3 tool. It asks the IP tunnel for an IP address during sign-on, it performs the compression and decompression of the TCP header and fragments packets that exceed P3 limits.
  879.  
  880. The name AOLSOCK is now considered a misnomer. At one time it used to contain the AOL Socket and a full TCP/IP stack. With the emergence of Windows 95 containing its own Windows Socket and TCP/IP stack the AOLSOCK tool has been relegated into the role of middleman between the AOLMAC and WAOL.
  881. Initialization
  882.  
  883. The AOLSOCK is loaded by WAOL during WAOL initialization. During initialization a ToolTokenHandler is registered with WAOL. The AOLSOCK is responsible for loading the AOLMAC device driver, setting and registering the IP address and mask associated with this process. At this early stage, AOLMAC helps AOLSOCK determine the system configuration, it is not making any calls to NDIS. If AOLMAC cannot be found or if the TCP stack isn't present, AOLSOCK displays a message box with an error.
  884.  
  885. During sign on, AOLSOCK requests an IP address from the tunnel. When AOLSOCK receives it, it makes entries in the Win95 registry that specifies AOLMAC as a device driver and binds it to the TCP/IP protocol. Then AOLSOCK asks the plug and play configuration manager to "reenumerate" all devices in the system. This causes NDIS to recognize AOLMAC as an active network driver.
  886.  
  887. When it loads the device driver (using the CreateFile Win32 API) it receives a handle to the AOLMAC device driver which it uses for communication with the driver.
  888.  
  889. When the user signs off, AOLSOCK removes the registry entries and reenumerates again. This causes NDIS to remove the AOLMAC driver.
  890. Sending and Receiving Data
  891.  
  892. Data is sent to the AOLMAC using the Windows API DeviceIOControl. It passes data to the AOLMAC using the handle received during loading of the device driver and by passing the address of the data buffer.
  893.  
  894. AOLSOCK receives data from the AOLMAC device driver. It compresses the TCP/IP header associated with the data and then passes the data to the WAOL P3 tool.
  895.  
  896. The AOLSOCK will receive data from the P3 tool via its ToolTokenHandler. If it receives data from the host via the P3 tool then it decompresses the header and sends it to the AOLMAC device driver using the Win32 API function DeviceIOControl.
  897.  
  898.  
  899. AOLDICE and AOLCOMM.DLL
  900.  
  901. Aolcomm.dll is a connectivity utility DLL with a set of related APIs. DICE, Modem and Tcpip tools are all linked to this DLL.
  902.  
  903. AOLDICE.AOL is the abstract layer on top of all devices (modem and TCPIP). It takes care of connection setup routines by handling DICE atoms and talks to TCPIP and Modem devices for the actual connect commands. DICE stands for Device Independent Connectivity Engine.
  904.  
  905. Since DICE tool is the abstract layer on top of all devices it has its own dispatcher for Atoms, messages, notify messages and APIs. Each device can call Dice_Register to set the call back functions associated with specific prototypes. At the application startup each device calls RegisterCommTool (in AOLCOMM.DLL) to announce its existence. DICE (actually AOLCOMM.DLL) stores a table where each device type maps the tool handlers. When DICE performs auto-detection it loops through all the registered device tools by calling EnumNextTool. Each tool then performs its associated detection. For example, the Modem tool will search for each Com port to see if there is any modems attached. The error messages will be reported back to DICE tool and being populated in DICE.
  906.  
  907. DICE is the connectivity interface with users and the core client. It stores connectivity setups and access numbers in a MORG format file “Global.org”. Global.org file contains four subfolders:
  908.  
  909. • Devices, it stores the list of all devices that was found through auto detection.
  910. • Locality, it stores all the localities that user has selected
  911. • Access, this folder stores all the access numbers sent by the host and categorized by country, area code and numbers.
  912. • Access View, this is the access numbers for all the local area code.
  913.  
  914. This file get created and rendered at the application startup. For each sign on session host will check and make sure that this copy of AOL has up to date access number information. Storing access numbers improves locality setup and reduces the cost of 800# dial in.
  915. Access Numbers
  916. One of the major responsibilities for DICE is to interact with the host to update the client Access number database. The idea is that the user will dial in once to the 800 number local access number service to get the first set of local numbers. After user signed on through one of the obtained local access number he/she will receive updates to the access number database little by little in every subsequent session they have. The update happens in the background. The following is the process for PDOD access numbers:
  917. Step1: Client requests a list of area code / time-stamps from Host (token ‘AN’ and function ‘ClientRequestList’)
  918. This is what starts the update of the database. The client is responsible for kicking this off and can happen at any time, but right now it happens one minute after the client gets online. In this step, the client will compile a list of area codes to send to the host to get the time-stamps of each. The first area code will be the area code the user has indicated as being local. This list of area codes will be sent all in one field (relative ID 2) separated by semi-colon. The country code is also contained in that field preceding the area code separated by a ‘/’. The bookmark area code is sent in a separate field (relative ID 3). The bookmark is a country code followed by an area code separated by a ‘ /’.
  919. Step 2: Host sends a list of area code / time-stamps
  920. In response to the client’s ‘Aa’ token, the host will do a lookup on each of the area codes it received for the local / localities list. It will then send a list of area codes with their accompanying time-stamp. In addition to this list, the host will also look at the bookmark area code sent by the client, find the next area code and compile a list of area codes to send with time-stamps. The number of area codes to send following the bookmark area codes is calculated based on the baud width. Faster connection will receive more numbers for each session. The host send these area code / time-stamp pairs in a string format and through DICE atom “atom$dice_access_current_update”.
  921. Step 3: Client requests given area code update (token ‘AN’ ClientRequestArea)
  922. The client is responsible for knowing if it should request an update for a given area code. When the client decides that it needs an update for an area code because it either does not have the area code or the area code is out of date, the client will send token ‘AN’ to request the given area code. The request is of the following format:
  923.  
  924. Relative ID 2 --- country code;
  925. Relative ID 3 --- Area code;
  926. Relative ID 4 --- Time stamp of last update;
  927. Relative ID 5 --- fEntire state (0 for delta, others for entire state)
  928. Relative ID 7 --- 0 for normal send down, 1 for direct request
  929.  
  930. The host is responsible for sending the delta numbers in the given area code between the last update on the client and the last update on the host. If the client does not have the given area code in its database it will put 0 as the time-stamp of the last update.
  931. Step 4: Host updates numbers in database
  932. The host will send an update for an area code through a dice atom. This update is in response to the client requesting the area code update. (Note: In order to keep the client from locking receiving numbers the host will be pacing the data sent down. The client does not prevent a user from signing off even if they are in the middle of getting an area code. This is why the host sets the time-stamp attribute on the area code after all the numbers have been brought down.) This update will either create an area code for the given number, or will update the existing one.
  933.  
  934. The following is an example if session access number retrieve and update:
  935. Example: Client is a US client located in Vienna, VA which also wants an area code for Dallas, TX
  936.  
  937. Step1: Client requests a list of area codes by sending the following data:
  938.  
  939. Relative ID 1: ClientRequestList
  940. Relative ID 2: 01/703;01/214
  941. Relative ID 3: 0/0
  942.  
  943. Step 2: Host sends a list of area codes and time stamps. 703 updated 45678 and 214 updated 123456. And the next number after the bookmark (this should be a valid area code) followed by a determined number of area codes.
  944.  
  945. Atom$uni_start_stream
  946. Atom$dice_access_current_update “01/703/45678”
  947. Atom$dice_access_current_update “01/214/123456”
  948. Atom$dice_access_current_update “01/001/342533”
  949. Atom$dice_access_current_update “01/002/252232”
  950. Atom$uni_end_stream
  951.  
  952. Step 3: Client requests given area code update by sending the following data for each area code.
  953.  
  954. Relative ID 1: ClientRequestArea
  955. Relative ID 2: 01
  956. Relative ID 3: 703
  957. Relative ID 4: 0
  958. Relative ID 5: 0
  959. Relative ID 1: ClientRequestArea
  960. Relative ID 2: 01
  961. Relative ID 3: 214
  962. Relative ID 4: 0
  963. Relative ID 5: 0
  964. ……
  965.  
  966. Step 4: Host updates the numbers
  967.  
  968. Atom$uni_start_stream
  969. Atom$dice_access_update_country “01”
  970. Atom$dice_update_area “703”
  971. Atom$dice_access_update_number “506-0152”
  972. Atom$dice_set_obj_attrib <phone_number>
  973. Atom$dice_set_obj_info “506-0152”
  974. Atom$dice_set_obj_attrib <phone_city>
  975. Atom$dice_set_obj_info “vienna”
  976. Atom$dice_set_obj_attrib <phone_state>
  977. Atom$dice_set_obj_info “va”
  978. Atom$dice_set_obj_attrib <phone_country>
  979. Atom$dice_set_obj_info “01”
  980. Atom$dice_set_obj_attrib <phone_area>
  981. Atom$dice_set_obj_info “703”
  982. Atom$dice_end_context
  983. ……
  984. atom$dice_set_obj_attrib <time_stamp>
  985. atom$dice_end_context
  986. atom$dice_access_set_bookmark “01/002”
  987. atom$dice_end_context
  988. atom$uni_end_stream
  989.  
  990. Phone Home Report
  991.  
  992. DICE also handles another major client feature --- Phone Home report. They are seven kinds of template for storing phone home data:
  993.  
  994. • Common template, which stores all the data that applies to all abnormal events
  995. • Online template, stores data related to abnormal disconnect
  996. • Attempt template, some information for attempt to connect to AOL
  997. • GPF template, stores information related to GPF event
  998. • Hardware template, stores information for auto-detection
  999. • Install template, records data related to the installation
  1000. • Diagnostic template, stores informational data
  1001.  
  1002. All the templates are stored in main.idx. Each tool can call PhoneHomeData to write the required data to each template. PhoneHomeEvent will cause DICE to put all the information into a packet and add the packet to a packet list (also stored in main.idx). For each phone home event only one template plus the common template gets packed as one package.
  1003.  
  1004. GPF template is stored differently. Most of the GPF related information is stored in the memory in MANUTILS.DLL and SUPERSUB.DLL. As discussed in WAOL.EXE, when a GPF occurred the client has the capability to track and write some diagnostic information to an external file “ph.ph” (which is in .INI file format located at the AOL running directory). Each time user starts the client that was previously GPFed, DICE reads PH.PH file and collects GPF information, stores them in GPF template and build a packet for it. Upon Sign On, Client will send an ET token to the host if and only of there is data to report. ET token signifies number of disconnects events to report and complete size of data waiting to be sent. If the host accepts the data it will send down atom DICE_PHONEHOME_REQUEST to let the client send all waiting phone home data to Host. Client keeps accumulated Phone Home data until the client successfully sends the data to host or host tells the client to purge all the accumulated data.
  1005. Abstract vs. Verbose Reports
  1006. During 4.0 development, client is set to record and report (if possible) all of the information on abnormal disconnect including GPF. This is called Verbose Phone Home Report. Once the client goes GM, client will only record and report a subset of those data. This flag is stored in main.idx.
  1007.  
  1008. NOTE: Refer to Phone Home Document for more information.
  1009.  
  1010. AOLLIST
  1011.  
  1012. The AOLLIST.AOL handles the List Manager protocol (LM atoms) and provides a generic way to transport lists of items, such as e-mail messages, between the host and client. List Manager operates independently or interfaces with other tools and protocols depending upon what platform is used and what type of list function is being performed. On platforms that are form driven (such as WAOL), the List Manager provides an interface between the Database Manager tool and the Display Manager tool.
  1013.  
  1014.  
  1015. AOLMODEM
  1016.  
  1017. The AOLMODEM tool acts as the primary interface between the WAOL program and the modem. It receives the packet data from the comm. port associated with the modem and passes it on to the P3 tool.
  1018.  
  1019. When the tool notify handler for this tool is received (via the message MSG_NOTIFY_APP_STARTUP usually during application startup) a timer based callback function is set up to periodically check the comm port for data at 125ms intervals.
  1020.  
  1021. The ModemTimerHandler is called by the system timer periodically. It checks the comm port associated with the modem for new data. If new data is available then it calls a number of subroutines that eventually call a special P3 function P3DataHandler.
  1022.  
  1023. AOLMODEM and TCPIP talk through the AOLCOMM module to the P3 module. The AOLCOMM module acts as the interface between AOLMODEM and TCPIP and P3.
  1024.  
  1025. The following is what happened when an user try to sign on AOL through a modem:
  1026.  
  1027. Dice_Connect (Dice tool)  OpenComPort (Modem tool)  Send Init String (AT&F in CSL)  Dial #  CSL: Banner (connect)  Look for ‘Login’ (BBIN, Aolnet)  Send Pop Login  Send password  CSL: Success (P3 state online)  checking password (sending init packet, getting message “connected” and sending ‘Dd’ token)  Aolsock tool receives ‘ya’ or ‘yc’ token for DAHA and notifies the client of IP.
  1028.  
  1029. There are a few external files that client uses for modem detection, command strings, speed, call waiting and others. These files are located in subfolder “Modem” of AOL root and they are:
  1030.  
  1031. • modemid.dat, this is the list of all modems and the appropriate AT commands that are required to uniquely identify the modem.
  1032. • modems.dat, this is the list of all modems and the appropriate Setup strings.
  1033. • speed.dat, this defines the proper port speed based on the response from ATI0 command.
  1034. • callwait.dat, this defines the commands and the responses for call waiting.
  1035. • atmodem.dat, the AT command.
  1036. • dial9.dat, dial9 command.
  1037. • dtmf.dat, command for dial tone pause.
  1038. • phoneli.dat, command for open phone line.
  1039.  
  1040. At the beginning of launching the client, modem tool builds the match tree by load information from these files. The files controls how the client is supposed to talk to each specific modem which has made it easier to modify the client by changing these external files. The client will use the generic command strings when there is a modem that client does not know.
  1041.  
  1042.  
  1043. AOLPPP
  1044. Quick description of various open-standards communications protocols…
  1045.  
  1046. • IP (internet Protocol): connection-less, non-reliable; used to deliver datagrams from one machine to another. IP mostly provides basic addressing functionality.
  1047. • UDP (User Dategram Protocol): sits on top of IP; connection-less, non-reliable. Lightweight, low onverhead. Good for applications like RealAudio.
  1048. • TCP (Transport Control Protocol): sits on top of IP. Provides reliable, in-order packet delivery – effectively allows apps to assume they have a direct, consistant data link with a remote machine. Used by most internet apps, such as FTP, browsers, etc.
  1049. • PPP (Point to Point Protocol): datalink protocol, designed to transport diverse range of the network protocols over a single communications link. Mostly commonly used to move IP over a serial connection (e.g. MSDUN modem connection to an ISP).
  1050. • P3: procides reliable, in-order packet delivery. P3 was originally created to optimized slow-speed connections over packet-switched networks (e.g. Sprint X.25).
  1051.  
  1052. Non-PPP data flow
  1053.  
  1054. • Client’s basic connection to the host complex : TTY (raw byte) connection to the network Point of Presence (POP).
  1055. • POP converts raw byte stream into a TCP/IP connection to a TFEP in the AOL host complex. (Non-AOLnet POP’s use X.25 to a FEP instead.)
  1056. • Data flow diagram for service traffic might look like this ...
  1057.  
  1058.  
  1059.  
  1060.  
  1061. AOLRICH
  1062.  
  1063. AOLRICH.AOL is the rich edit hyperlink tool. This is considered a managed by tool. It is called a managed by tool because it is largely instructed to do certain operations by other tools, in the case of AOLRICH, it is managed by AOLMAN.AOL by setting the object with RICH_MANAGE atom. The AOL Rich tool uses the Paige Engine DLL which contains a set of Window displaying and text editing functions that supersede the standard EDIT Window. It effectively creates a new class of Window with a rich set of edit controls and functions such as highlighting, bold, Italics, etc. The Rich edit features are implemented using the Paige Engine rich edit DLL. Once the rich edit Window or view is created, much of the code associated with the features that come with it are transparent to the developer. This DLL is explicitly loaded by AOLRICH.AOL tool when it is loaded by Supersub’s tool loader. The remaining functionality associated with hyperlinks were custom developed by AOL developers.
  1064.  
  1065. The AOLRICH edit tool sets up and registers three different Tool Handlers,
  1066.  
  1067. ToolNotifyHandler is registered as CLASS_MSG, PROTO_NOTIFY,
  1068. ToolObjNotifyHandler is registered as CLASS_OBJECT_NOTIFY, PROTO_NOTIFY,
  1069. ToolFileHandler is registered as CLASS_FILE, PROTO_FILE
  1070. (The ToolObjNotifyHandler is the handler that receives most of the messages from AOLMAN.AOL.)
  1071.  
  1072. The AtomManage function does only one thing. It sets up the associated Object’s TID to TID_AOLRICH. This ID is later used by the ToolObjNotifyHandler to determine if it should merely pass any messages it receives or do something with it. If a message comes in with a parameter pointing to an object with this TID then AOLRICH’s ToolObjNotifyHandler traps this message and does something with it.
  1073.  
  1074. These functions are registered with the dispatcher using the RegisterAtomProtocol function. Unlike ToolRegister this function registers specific atoms to specific functions with the dispatcher. This way when the specific atom comes through it will invoke the associated function directly rather than going through a tool handler with a large number of case statements.
  1075.  
  1076. If a process wishes to use a rich edit window it must place the RICH_MANAGE atom immediately after the MAN_START_OBJECT in the beginning of its stream. This will effectively wake up the AOLRICH ToolObjNotifyHandler and cause it to trap the messages that will handle the text-related operations associated with the Window. When MANAGER tool process atom MAN_UPDATE_DISPLAY it will call
  1077. CallExternalObjectManager with OBJ_MSG_CREATE message to tell RICH tool to create the window itself. CallExternalObjectManager merely sets up an information structure and then uses:
  1078.  
  1079. ToolSendMsg(CLASS_OBJECT_NOTIFY, PROTO_NOTIFY, wNotifyCmd,
  1080. (LPINT) &nResult, 1, (DWORD)(lpObjInfo));
  1081.  
  1082. Most of these messages are hard-coded in the AOLMAN.AOL code in the appropriate places. A few atoms do come in that are processed by other functions that eventually call CallExternlObjectManager. These messages are trapped by the appropriate manage by tool, in this case AOLRICH and processed.
  1083.  
  1084. During the Compose mail session the hyperlinks are stored in a linked list structure stored locally in the AOLRICH tool. The structure contains the Hyperlinked word or phrase, the hyperlink (usually an URL or a keyword) and the Hyperlinked word or phrase starting offset and ending offset within the body of the text. The offsets are used to uniquely associate the hyperlinks. Any time text is added to the field (by subclassing WM_CHAR messages) a local dirty flag is set within a local data structure. Any time AOLRICH needs to access the linked list structure it checks the dirty flag and if set it recalculates all the starting and ending offsets of all the hyperlinks in the list. Note: You cannot have two hyperlinks with the same name.
  1085.  
  1086. If a user double clicks on a highlighted word or phrase, during Read Mail, the AOLRICH tool subclasses on WM_LBUTTONDBLCLK it then uses Paige engine features to determine the offset of the character that the cursor is over. If the word or phrase that the cursor is over is a hyperlink it then calls the AOLRICH tool calls a dialog box function that display the hyperlink content (i.e. URL or keyword) and allows the user to edit it.
  1087.  
  1088. The AOLRICH tool contains a FormatOutput function that will extract and reformat the text to contain the hyperlink information.
  1089.  
  1090. The host will send the MIP atoms and associated data using MIP_DATA & MIP_DATA_URLs. The MIP tool will intercept these atoms and extract the string data (text). It will send this data to the AOLRICH tool in string form. When this data is received by a Hyperlink enabled client and the AOLRICH tool, it is reformatted back into a rich edit compatible hyperlinked letter by the AOLRICH function called ParseInput. Since data comes in packet limited chunks, an entire letter cannot always be sent in one packet. The incoming data is dynamically searched for tildas. If a tilda is not found within the packet the data is sent directly to the mail view window. If a tilda is found the data is buffered until the tilda triumvirate is found. At that point AOLRICH knows the entire hyperlink and its associated URL or keyword is found. The hyperlink word or phrase is displayed in the body of the e-mail and the linked list, as discussed above, is built.
  1091.  
  1092. If a user single clicks on a highlighted word or phrase, during Read Mail, the AOLRICH tool subclasses on WM_LBUTTONDOWN. It then uses Paige engine features to determine the offset of the character that the cursor is over. If the word or phrase that the cursor is over is a hyperlink it then calls MuiJumpUrl (AOLMORG.AOL) to jump to the URL or keyword.
  1093.  
  1094. Modifications were made to the MIP tool to handle the new MIP_DATA_URL atom and to parse the host bound mail strings into MIP_DATA and MIP_DATA_URL accordingly.
  1095.  
  1096. The following fully describes the HTML that is either generated or recognized by the AOLRICH. HTML is simply being used because it represents a standard markup language for interaction between the host and client. HTML is stripped and processed on input. On output to the host, HTML is packaged in a MIP_DATA_MARKER packet (272). Hyperlinks are packaged in a MIP_DATA_URL (270), and text as MIP_TEXT. This makes it possible for the host to strip or handle tagged data in custom ways for older clients or internet mail. Currently HTML should be stripped to older clients and Internet mail. The tags selected are those deemed necessary to transport the attributed we found necessary a user would like to experience in a mail session. Some tags like the body tag exist for IP’s who will also use the AOLRICH tool to modify window background color.
  1097.  
  1098. Starting from AOL4.0, RICH tool also supports embedded images and audio, which is largely used in email. Images are identified and stored in binary blocks with MIP_DATA_BINARY.
  1099.  
  1100. AOLSPELL
  1101.  
  1102. This tool interfaces with the client and links to a third party software for spell checking. It handles SPELL atoms, displays and handles the preference dialog and the error message dialog.
  1103.  
  1104. In order to accomplish the spell checking in email. We created atom “mip_spell_check_send_now” to set the form object in SPELL tool and then calls MANAGER tool which in turn route to RICH tool to pass the proper text block for spell checking by calling “Spell_CheckSent”.
  1105.  
  1106. ASYNC
  1107.  
  1108. The FDO91 Async Tool (AOLASYNC.AOL) provides a variety of miscellaneous features that do not belong in any other tools. These features let you set up your online service application to:
  1109.  
  1110. • Display an alert box.
  1111. • Display the Network News form.
  1112. • Send a message to let the client tools know the member is offline or online.
  1113. • Play a sound if the member has a sound card.
  1114. • Builds the Init Packet
  1115.  
  1116. The init Packet gets sent to the host when the user first signs on. The host uses this packet for a large variety of reasons. The Init Packet Structure is defined as:
  1117.  
  1118. typedef struct INITPACKET
  1119. {
  1120. BYTE bPlatform; // WAOL Platform (i.e 03 for WAOL , 0C for MAC)
  1121. BYTE bVersionNum;
  1122. BYTE bSubVersionNum;
  1123. BYTE bUnused; // Unused
  1124. BYTE bMachineMem;
  1125. BYTE bAppMem;
  1126. WORD wPCType; // Unused
  1127. BYTE bReleaseMonth;
  1128. BYTE bReleaseDay;
  1129. WORD wCustomerClass; // set to zero for now
  1130. LONG lUDOTimeStamp; // Unused
  1131. WORD wDosVersion;
  1132. WORD wSessionFlags; // Unused (Mac only)
  1133. BYTE bVideoType;
  1134. BYTE bProcessorType;
  1135. LONG lMediaType;
  1136. LONG lWindowsVersion;
  1137. BYTE bWinMemoryMode; // 0 = standard, 1 = enhanced
  1138. WORD wHorzRes;
  1139. WORD wVertRes;
  1140. WORD wNumColors;
  1141. BYTE bFiller; //align for Stratus
  1142. WORD wRegion; //International support
  1143. WORD wLanguage[4]; //language types
  1144. BYTE bConnectSpeed; // Connection Speed established
  1145. }INITPACKETSTRUCT;
  1146.  
  1147.  
  1148. BUFFER
  1149.  
  1150. The AOLBUF.AOL tool assembles FDO91 atom commands into P3 packets. The Buffer Tool centralizes the management of all host-bound data. The BufferEnd function actually sends the packet to P3.AOL
  1151.  
  1152. • Forming atom streams.
  1153. • Breaking atoms into large atom segments when data length exceeds 255 bytes
  1154. • Breaking data correctly on packet boundaries so an individual atom does not span multiple packets
  1155. • Accepting raw data as well as atom data
  1156. • Buffering packets when the P3 tool is busy
  1157. • Acting as the throttle control between the P3 tool and all other tools
  1158.  
  1159. The Buffer tool can process up to sixteen concurrent buffers. Buffers are associated with stream IDs and use the stream ID for reference once created. Most buffer usage comes directly from local tools on the client computer. Every atom call has an equivalent tool message call. The message calls made by tools to manipulate the buffers allow more arguments and flexibility than their counterparts, which are atom commands.
  1160.  
  1161. All data is sent to the host using the BUFFER tool function: BufferClose().
  1162.  
  1163. CSL
  1164.  
  1165. The Communications Scripting Language Tool (AOLCSL.AOL) connects the online client software to the remote host system. This procedure includes control over what command strings are sent to the modem, what result codes are expected from the modem in response, and, once a connection is made to the modem, how to connect to the online service via the appropriate data-switch networks (i.e. Sprintnet, AOLNet). The CSL module does not handle any P3-protocol communications.
  1166.  
  1167. The CSL language is a primitive language that is used during the dial-in process when WAOL is launched. WAOL contains a CSL script for various types of networks. The CSL script directs WAOL on how to dial-in/connect to the host. The appropriate network can be selected in the Network Setup form (Welcome/Setup/Edit/Network Location). Each CSL script contains a Title and an ID that is unique to the network WAOL is trying to use. For example:
  1168.  
  1169. The SprintNet title and ID are:
  1170.  
  1171. Title "SprintNet"
  1172. ID 1
  1173.  
  1174. The AOL In-House ATG testing system title and ID are:
  1175.  
  1176. Title "AOLNet (aratg)"
  1177. ID 602
  1178.  
  1179.  
  1180. CHAT
  1181.  
  1182. The Chat Tool (AOLCHAT.AOL) provides support for real-time conferencing in People Connection rooms, forum conference halls, and auditoriums through atom and token handlers. The Chat tool internally handles all the older tokens used for providing chat functionality.
  1183.  
  1184.  
  1185. CHARTMAN
  1186.  
  1187. Chartman contains the functionality necessary to create complicated charts in windows. Chartman is used to create charts such as the ones used by Historical Quotes. Chartman uses a third party DLL made by SoftwareFX.
  1188.  
  1189. Chartman tool handles the interface with the client through atom stream to get the requirement for the chart and then calls the third party DLL to draw the chart.
  1190.  
  1191.  
  1192. CODEMAN
  1193.  
  1194. The Code Manager (AOLCODE.AOL) Tool provides an atom-based interface for tool management. It
  1195. augments the capabilities of the loader module to implement the following features:
  1196.  
  1197. • The ability to replace a tool or any other online service module at any time by downloading a new version of the tool. (Not fully implemented as of 9/18/95.)
  1198. • A facility for marking specific atoms or entire protocols invalid so that their use in a stream initiates a forced tool download to obtain a new handler (ToolAtomHandler function) for that atom.
  1199. • Support for transient tools, which are tools that are started and stopped explicitly through atoms. This feature is intended primarily for games.
  1200.  
  1201. CODEMAN is responsible for ensuring that tools are up to date by handling code-on-demand and other code updates. It also serves as the atom and message interface for Loader, allowing tools to be loaded and
  1202. killed by request.
  1203.  
  1204. CODEMAN contains and uses a linked list object called the “Poison Tree.” This object or tree is filled with all atoms and protocols that are marked as invalid for that particular copy of the client code. (The poison tree is also stored in main.idx.) This tree is used primarily to determine when and if the host should send a new tool, to the a, using TOD. As atoms come into a client they are checked against the Poison Tree. If a match in the tree is found, the client code will automatically put further actions on hold. It will then ask for the host to do a TOD on the tool associated with the invalid atom. Once the TOD is complete the matching invalid atom, in the poison tree, is removed.
  1205.  
  1206. When the WAOL disk is first sent to a user, it contains a limited set of AOL tools. This is primarily due to space limitations on the 3.5” floppy disk. Therefore the Poison tree has several invalid entries in it. As soon as the user tries to access part of the service associated with a nonexistent tool, they will be sent an atom that will be in the Poison tree.
  1207.  
  1208. If AOL develops a new tool and wishes to distribute it to all users then a UDO is used to first download a new Poison tree. This new Poison tree will contain new atoms associated with the new tool. When the user goes to an area associated with the new tool they will then get the new tool as a TOD.
  1209. Intercepting Atoms & Tokens
  1210.  
  1211. As each and every atom and protocol comes into the client it get scanned by a set of ToolIntercept functions before being sent to other tool handlers. If an invalid atom, protocol or token is found then a TOD will be invoked according to the contents of the Poison Tree, if not then the atom and tokens as passed through untouched. If something is found then a TOD will commence if all additional criterions are met.
  1212.  
  1213. When the host marks a protocol or atom invalid, Codeman registers (via INSTALL_FIRST) for that protocol and has Dispatch route atoms in that protocol here for a first peek. If an invalid atom or protocol is found, we cause a TOD to be initiated.
  1214.  
  1215. LONG CALLBACK ToolInterceptAtoms(WORD wAtom, LPINT lpnResult, int nArg, LPLONG lplValue)
  1216.  
  1217. This routine performs a similar function for tokens. Note that the token is still just passed through and will be executed by the old tool, but a download of the new tool will be initiated.
  1218.  
  1219. LONG CALLBACK ToolInterceptTokens(WORD wAtom, LPINT lpnResult, int nArg, LPLONG lplValue)
  1220. Posion Tree
  1221.  
  1222. The Poision Tree gets scanned for pending downloads based on invalidated Atoms, or Protocols consists of a linked list of the structure.
  1223.  
  1224. For more information on Codeman & TODs see the chapter on TODs.
  1225.  
  1226.  
  1227. DATAMAN
  1228.  
  1229. The Data Manager Tool (AOLDATA.AOL) provides the ability to extract data from fields in forms for local processing or to be sent to the host. Various data types and extraction options are supported. There is also support for limited input field validation. Most of the real data extraction gets accomplished by calling Manager tool to get to the handler of each specific control to get the data. This tool handles the DE atoms.
  1230.  
  1231. FILER
  1232.  
  1233. The File Manager protocol is managed by the File Manger Tool (AOLFILER.AOL) which handles the management of the client computer's files. The File Manager Tool provides a number of features that can be tapped through inter-tool messaging, as well as at the atom level.
  1234.  
  1235. • Support for the commands on the standard File menu and extendibility for future non-text views.
  1236. • File type registration and notification for tools
  1237. • Atom- and message-based interface to the Windows Common Dialog Library's Open, Print, and Save As
  1238. • Dialog boxes.
  1239. • Low-level session log and chat log support, including basic word wrap.
  1240. • Windows drag and drop functionality
  1241. • The ability to read and modify any .INI file.
  1242. • Basic file operations such as creation, deletion, and renaming of files.
  1243.  
  1244. Since the online service application supports multiple, concurrent streams of data, it is possible that the File
  1245. Manager Tool's features may be needed simultaneously for two or more operations. For that reason, the File Manager Tool has been designed to maintain multiple contexts (the circumstance in which in which an event occurs). A context is the current state of the File Manager Tool and consists mainly of approximately twenty context registers, each of which contains a single value or string representing data to be passed to an
  1246. operation, the result of an operation, or some other piece of information.
  1247.  
  1248. In order to support multiple file attachments in mail FILER tool keeps a structure of attachment information and handles the file attachment atom “fm_edit_attachment_command”. All the file attachments are stored in MORG format under subfolder “attachments”. The content of each item is a structure in FILER. After user finished selecting all the attachments FILER build the list of the file names and put them in one of the controls in the Compose Mail forms. MIP tool retrieves the list of file names from this control and asks Filer tool to compress the list of files and create a single Zipped file. This file name is then saved and later sent together with the mail content.
  1249.  
  1250.  
  1251. MANAGER and its Related DLLs
  1252.  
  1253. Manager tool and its related DLLs contain virtually all the functionality required to display MDI Windows (forms) and objects on the user’s computer screen. Manager is responsible for setting up the form’s object tree. Typically the object tree is a description of the various objects associated with the form, such as buttons, listboxes, text, etc. Manager is responsible for accepting atoms, creating MDI Windows, displaying MDI windows, filling the MDI Window, and corresponding object tree, with buttons, listboxes, images, etc. Without AOLMAN.AOL the user would not see WAOL on their monitor. Generally speaking these windows are thought of as objects. Therefore the Display Manager controls all aspects of creating, displaying and manipulating objects. Multiple hierarchies of display objects are maintained. Display Manager consists of the following three atom command sets:
  1254.  
  1255. • Display Manager (MAN atoms)
  1256. • Attribute (MAT atoms)
  1257. • Image Manager (IMAGE atoms)
  1258. • DOD (DOD atoms)
  1259.  
  1260. At the present time Windows messages, such as WM_COMMAND, are handled by the ToolWMHandler .
  1261.  
  1262. Typically the MAN_START_OBJECT atom is used to draw, not only the form, but individual objects themselves. Each new object will require a MAN_START_OBJECT with its own unique object_type parameters setting. Manager supports 20 types of objects:
  1263.  
  1264. “ind_group” is a new MDI Window.
  1265. “dms_list” is a new list box.
  1266. “trigger” is a new actionable object (i.e. a button, icon, menu item, etc.)
  1267. “ornament” is a new static or decorative object (e.g. a picture, static text, etc.)
  1268.  
  1269. BUTTON Designates a small rectangular child window that represents a button the user can turn on or off by clicking. Button controls can be used alone or in groups, and can either be labeled or appear without text. Button controls typically change appearance when the user clicks them.
  1270.  
  1271. COMBOBOX Designates a control consisting of a list box and a selection field similar to an edit control. The list box may be displayed at all times or may be dropped down when the user selects a pop-up list box next to the selection field.
  1272.  
  1273. Depending on the style of the combo box, the user can or cannot edit the contents of the selection field. If the list box is visible, typing characters into the selection box will cause the first list box entry that matches the characters typed to be highlighted. Conversely, selecting an item in the list box displays the selected text in the selection field.
  1274.  
  1275. EDIT Designates a rectangular child window in which the user can type text from the keyboard. The user selects the control, and gives it the input focus by clicking it or moving to it by pressing the TAB key. The user can type text when the control displays a flashing caret. The mouse can be used to move the cursor and select characters to be replaced, or to position the cursor for inserting characters. The BACKSPACE key can be used to delete characters.
  1276.  
  1277. LISTBOX Designates a list of character strings. This control is used whenever an application must present a list of names, such as filenames, from which the user can choose. The user can select a string by pointing to it and clicking. When a string is selected, it is highlighted and a notification message is passed to the parent window. A vertical or horizontal scroll bar can be used with a list box control to scroll lists that are too long for the control window. The list box automatically hides or shows the scroll bar as needed.
  1278.  
  1279. MDICLIENT Designates an MDI client window. The MDI client window receives messages that control the MDI application's child windows. The recommended style bits are WS_CLIPCHILDREN and WS_CHILD. To create a scrollable MDI client window that allows the user to scroll MDI child windows into view, an application can also use the WS_HSCROLL and WS_VSCROLL styles.
  1280.  
  1281. SCROLLBAR Designates a rectangle that contains a scroll box (also called a "thumb") and has direction arrows at both ends. The scroll bar sends a notification message to its parent window whenever the user clicks the control. The parent window is responsible for updating the position, if necessary. Scroll bar controls have the same appearance and function as scroll bars used in ordinary windows. Unlike scroll bars, however, scroll bar controls can be positioned anywhere in a window and used whenever needed to provide scrolling input for a window.
  1282.  
  1283. The scroll bar class also includes size box controls (Maximize and Minimize buttons). These controls are small rectangles that the user can click to change the size of the window.
  1284.  
  1285. STATIC Designates a simple text field, box, or rectangle that can be used to label, box, or separate other controls. Static controls take no input and provide no output.
  1286.  
  1287. When the MAN_START_OBJECT with an object type of “dms_list” arrives the CreateWindow function is executed with the lpszClassName variable set to LISTBOX. When the MAN_START_OBJECT with an object type of “ornament” arrives the CreateWindow function is executed with the lpszClassName variable set to STATIC.
  1288.  
  1289. TAB CONTROL This.
  1290.  
  1291. PAGE CONTROL This.
  1292.  
  1293. TAB PAGE This.
  1294.  
  1295. Important Structs in Manager:
  1296.  
  1297. All objects use the same basic structure to represent themselves. The appropriate fields are set to null.
  1298.  
  1299. DISPLAYSTRUCT
  1300. MENUSTRUCT
  1301.  
  1302. Global Ids
  1303.  
  1304. All forms on the service have a global ID (GID). All DOD art on the service has a global art ID. Art can be loaded onto a client form using the art ID. The art can also be loaded into a form using a relative ID (RID). When the art department creates DOD art they assign a global art ID to it. New art can be requested from the artshop using keyword IWANT or ARTSHOP. You can also find a list of available art in the ARTSHOP area. (As of 9/26/95 the Art Dept. is located in 8615, 4th floor, room 459, see Jeff Wright). Additionally some art Ids can be found using form_edit. There does not seem to be one centralized area to find art and art IDs.
  1305.  
  1306. All art loaded using a relative ID can be reloaded without rebuilding the entire form. Otherwise the art is reference in some kind of linked list associated with the form. ????
  1307.  
  1308. Global ID (GID) is the four byte (two words) ID of a form, atom stream or piece of art that is used by WAOL when referencing objects. Typically each form has a GID. The GID is displayed in two or three parts with a dash between each part.. The two part format is always separated into two words (where each word is two bytes), a hi word (W1)and a lo word (W2). The left most number is the hi word and the number to the right of the dash is the lo word. The conversion formula to a numerical form without a dash would be as follows:
  1309.  
  1310. W = (W1 X 65536) + W2.
  1311.  
  1312. For example:
  1313. GID = 32-30
  1314. W=(32 X 65536)+30=2097182
  1315.  
  1316. For three part GIDs, such as 1-0-2240, the left most number is the highest byte (B1) of the four byte GID. The next number is the low byte (B2) of the hi word. The last number is the lo word (W2).
  1317.  
  1318. GID = 1-0-2240
  1319.  
  1320. B1=1
  1321. B2=0
  1322. W2=2240
  1323.  
  1324. W=(B1X256 + B2)X65536 + W2
  1325. W=(1X256+0)X65536 + 2240 =
  1326.  
  1327. You can also use the WAOL TOOL GID.EXE to find the GID value for a two or three part GID. (See: X:\WAOLTOOL\BIN)
  1328.  
  1329. Please Note: You can envoke a form by typing in the form GID in the WAOL keyword box.
  1330. You can check for existence within the client by using the *\Invoke Database Record on the Atomic Debugger for WAOL. If the form comes up then it is a client form. If it does not come up then it is a host form. You will need to find the form GID first. You can find it by using SNOOP on the Atomic Debugger.
  1331. Display Object
  1332.  
  1333. For any given object this structure contains many superfluous variables that are simply set to NULL (I believe). Needless to say this structure is large and can cause a substantial amount of waste when used for objects such as simple buttons. The Windows team has stopped adding variables to this structure and has started adding variables to a new type of structure called BLOBS.
  1334.  
  1335. Each object that is created in WAOL (MDI Window, Button, Listbox, etc.) is fully described and contained within a structure of the type DISPLAY_OBJECT. Display object contains a wide variety of variables that are used to fully describe each and every type of object that can be create on WAOL. Each time a new object needs to be created the atom MAN_START_OBJECT is sent causing memory to be allocated for a variable of the type DISPLAY_OBJECT. This structure is then filled with data representing the type or class of object to be rendered. Then when the MAN_UPDATE_DISPLAY atom arrives the actual object is rendered on the users monitor.
  1336.  
  1337. A form is represented as a tree of objects. Any group can have from zero to infinity children. In order to allow for an unlimited number of children, a parent node points only to its first child. Each child points to the next and previous sibling in the chain. Every child points to its parent also. Routines are provided to instantiate objects, attach them to the tree at any point, and detach them from the tree.
  1338.  
  1339.  
  1340.  
  1341.  
  1342.  
  1343.  
  1344.  
  1345.  
  1346.  
  1347.  
  1348.  
  1349.  
  1350.  
  1351.  
  1352.  
  1353.  
  1354.  
  1355.  
  1356.  
  1357.  
  1358.  
  1359.  
  1360. Important Terms/Structs/Macros etc.
  1361.  
  1362. CID : Comm ID
  1363. FID : Font ID
  1364. GID : Global ID (Also known as a Form ID)
  1365. LID : Logical Database ID
  1366. RID : Relative ID
  1367. SID : Stream ID
  1368. TID : Tool ID
  1369. VID : Variable ID
  1370. WID : Widget ID
  1371. XID : Index ID
  1372. MANAGER’s Object Tree
  1373.  
  1374. A form is represented as a tree of objects. Any group can have from zero to infinity children. In order to allow for an unlimited number of children, a parent node points only to its first child. Each child points
  1375. to the next and previous sibling in the chain. Every child points to its parent also. Routines are provided to instantiate objects, attach them to the tree at any point, and detach them from the tree.
  1376.  
  1377. • All objects are tied to one global root node (GLOBALID_ROOT =1)
  1378. • The root node is created in AOLMAN.AOL.
  1379. • The menu bar is attached to the root. (GLOBALID_MENUBAR=2)
  1380. • The tool bar is attached to the root. (GLOBALID_TOOLBAR=3)
  1381. • Producers can chose to attach any object/form to the root.
  1382. • A node called the "On-line Cluster" and a node called the "Off-line Cluster" are attached to the root.
  1383. • A “Cluster” is a logical collection of objects.
  1384. • Objects viewed only off-line are placed on the "Off-line cluster." (GLOBALID_OFFLINE=52) - Terminated when on-line
  1385. • Objects viewed only on-line are placed on the "On-line cluster." (GLOBALID_ONLINE=53) - Terminated when off-line
  1386. • Objects that need to have the capability to be viewed both On and Off-line need to be on the root.
  1387. • All Objects are placed into the Object Tree as they are prepared for rendering on the client.
  1388. • All Objects are removed from the Object Tree when the objects are removed from the client frame window and destroyed
  1389. • Over time, the Object Tree can become quite large as the user opens more and more forms. (a limit of 24 forms has been imposed on the client)
  1390. • All forms are connected to the tree at the same level off of the cluster
  1391. • All objects in forms or groups are stored at the next level
  1392. • All objects in groups are at the next level and so on and so forth
  1393. • Object art, labels, and text are typically stored in "blobs"
  1394. • Blob is a linked list by object, all new extensions are stored in Blobs
  1395. • Blob.h & Manflags.h contain blob keys, see TestObjFlag
  1396. • If a form is closed (destroyed) by the member then the form object, and all of its objects, is removed from the tree.
  1397. • Some forms can be marked as hidden when closed.
  1398. Clusters
  1399.  
  1400. All objects such as forms, buttons, listboxes, static text, etc. are part of an object tree. Multiple Object trees can make up a cluster. There can be sub clusters. Eventually all clusters are part of the Online cluster or the offline cluster. At the very base of the cluster is the Root. The root is the anchor, so to speak, of the whole object tree. It is always there. It is an object with a global ID (GID) of one (1) with hardly any attributes set. Its purpose is to have something that can always be referenced to no matter what. Upon startup, Manager, without consulting the database, creates root, menu bar, tool bar offline and online cluster. These objects are created by the code dynamically.
  1401.  
  1402. GLOBALID_ROOT = 1
  1403. GLOBALID_MENUBAR = 2
  1404. GLOBALID_TOOLBAR = 3
  1405. GLOBALID_STATUS = 4
  1406. GLOBALID_OFFLINE = 52
  1407. GLOBALID_ONLINE = 53
  1408. GLOBALID_POISON_TREE = 85
  1409.  
  1410. Root
  1411. Main Menu, Toolbar
  1412. On-line Cluster : All forms that should only be viewed on-line should be stored on the online cluster.
  1413. Off-line Cluster : All forms that should only be viewed off-line should be stored on the online cluster.
  1414. Orphanage Cluster
  1415.  
  1416. MANAGER’s Object Tree Diagram
  1417.  
  1418.  
  1419.  
  1420.  
  1421.  
  1422.  
  1423.  
  1424.  
  1425.  
  1426.  
  1427.  
  1428.  
  1429. Image Formats supported by the Client
  1430.  
  1431. • BMP, JPEG, GIF, ART (ART is a Johnson Grace compressed format ideal for on-line use)
  1432. • WAOL uses Image Filters to convert all to Windows DIB (Device Independent Bitmap) format
  1433. • IMFBMP.AOL, IMFJPG.AOL, IMFGIF.AOL, IMFART.AOL
  1434. Filters (converts) to DIB
  1435. • WAOL uses Johnson-Grace’s JGDWAOLS.DLL and Accusofts’ IMGLIB.DLL to help display images
  1436. • MANAGER contains the image processing & display code
  1437. • All Images are stored in the database as ICH format.
  1438. • ICH Header + Image Header + Image
  1439. • ICH contains the transparency color (RGB Value or Index)
  1440. • ICH definition can be found in ART.H & ICON.H
  1441. • Use WART.EXE or VWART.EXE utility to convert to/from ICH
  1442. • DOD Mask & Unmasked small images (art) are processed by the DBART.C module.
  1443. • DBART uses BitBlt, StretchBlt, etc to display images
  1444. • Large unmasked, usually unstored images are processed by IMGVIEW.C (non ICH images)
  1445. • IMGVIEW.C uses the custom Accusoft LIB to display images
  1446. • IMGATOM.C used by IMGVIEW & vice versa
  1447. IMGATOM.C processes images (scale, rotate, etc.)
  1448.  
  1449. Existing Windows versus New Windows
  1450.  
  1451. Magic is a term used to describe how you can check for the existence of a window before creating it, and if the window is found, make it the top-most form. This prevents creation of multiple instances of the same window. If the window already exists on-screen, the atom stream that was supposed to create the windows is terminated. Magic is used largely on forms that do not have variable data. Producers can chose to use the magic option with a given form when they create it.
  1452.  
  1453. Manager & Existing DOD art
  1454.  
  1455. When manager needs to draw art using a global ID it does the following:
  1456.  
  1457. 1. Sends Message to IDB asking if art exists in local database?
  1458. 2. If NO then manager sends message to ATOMIZER to put current stream on hold.
  1459. 3. ATOM asks IDB to get the DOD art from the host.
  1460. 4. IDB sends messages to BUFFER (typically either Token & Data or Atoms)
  1461. 5. BUFFER assembles packet and sends it to the host.
  1462. 6. The host will then send the required DOD art to the client.
  1463.  
  1464. See Appendix for advanced topic about DOD.
  1465.  
  1466. During the ToolInit for Manager tool many important items are set up. Among them is the registration for all the different major class types used by WAOL and the subclass of all the supporting object procedures.
  1467.  
  1468. DisplayWindowProc is an IMPORTANT procedure that is subclassed (see CreateIndependent) to receive all MDI windows messages before the defualt MDI procedure receives them. This is a key procedure and is the work horse for processing Windows messages.
  1469.  
  1470. // hWndCtl is the handle of the control, such as a button, passed to IndependentCommand
  1471.  
  1472. void IndependentCommand(HWND hWnd, int nID, HWND hWndCtl, WORD wCodeNotify)
  1473. {
  1474. .
  1475. .
  1476. wClass = GetObjectWindowClass(hWndCtl);
  1477. nCode = (int)wCodeNotify;
  1478. .
  1479. .
  1480. switch (wClass)
  1481. {
  1482. .
  1483. .
  1484. case kCLASS_ICON: //If the user pressed an Icon button on an MDI Window then
  1485. case kCLASS_BUTTON: //If the user pressed a button on an MDI Window then
  1486. switch (nCode)
  1487. {
  1488. case BN_CLICKED:
  1489. case BN_DOUBLECLICKED:
  1490. wAction = ACTION_SELECTION;
  1491. break;
  1492. }
  1493. break;
  1494. .
  1495. .
  1496. ObjectActionState(lpObj, hWndCtl, wAction, wClass, MAKELONG(nID,wCodeNotify));
  1497. }
  1498.  
  1499. // Called by IndependentCommand - See above.
  1500.  
  1501. void ObjectActionState(OBJPTR lpObj, HWND hWndCtl, WORD wAction, WORD wClass, LONG lCode)
  1502. {
  1503. .
  1504. .
  1505. .
  1506. if (wAction == ACTION_SELECTION)
  1507. {
  1508. SetActionTitle(lpObj);
  1509. AddPendingRequest(GetResponseID(lpObj), lpObj);
  1510. ToolPostMsg(CLASS_ACTION,PROTO_NOTIFY, wAction,
  1511. 5, MAKELONG(hWndCtl,0),lCode,(LONG)(DWORD)lpObj,
  1512. MAKELONG((WORD)lpObj->bInherit,0),
  1513. GetResponseID(lpObj));
  1514. }
  1515. .
  1516. .
  1517. }
  1518.  
  1519. Viewer
  1520.  
  1521. Manager also handles the Image Viewer that comes with WAOL is a custom viewer written using Accusoft image functions. The image viewer also has several simple image processing features that allow users to rotate and flip images, adjust brightness, contrast, convert colors, create negatives, and more. These features were implemented using the Accusoft Imaging library.
  1522. Data Extraction from on EDIT field
  1523.  
  1524. Data can be extracted from EDIT fields by setting the appropriate object type and then using the appropriate action stream. (The action stream is attached to the object. An action stream is a stream of atoms that are stored in a buffer pointed to by pAction in the DISPLAYOBJECT.) For data extraction to the host developers can use any number of Shorthand atoms, found in SHORT.AOL. For local client extraction developers will need to create their own custom atom streams.
  1525.  
  1526.  
  1527. Master
  1528.  
  1529. Master is the AOL tool used for internal debugging purposes. It allows developers to:
  1530.  
  1531. • Invoke Database records from WAOL’s main.idx
  1532. • Delete Database records from WAOL’s main.idx
  1533. • Update Database records from WAOL’s main.idx
  1534. • Display Art
  1535. • Trace atom streams
  1536. • Set Version Number
  1537. • Set Proxy Configuration
  1538. • Clear Poison Tree
  1539. • Invoke WAOL Snoop, allowing you to see Art Ids, GIDs, Handles, etc.
  1540. • Crash the application through three different ways
  1541. • Disable and enable the security hand shake
  1542. • Disable and enable outgoing packets
  1543. • Erase account info
  1544. • Delete artwork in top form
  1545. • Show groups in top form
  1546. • Bring up the connectivity file Global.org
  1547. • Set proxy configuration
  1548. • Set affinity group
  1549. • Set network address
  1550. • Waolsock debug
  1551. • Reload CSLs
  1552.  
  1553. NOTE: This tool is supposed to be used in house only. It should not be distributed to non-AOL employee. It should be given out on a limited basis even within the house.
  1554.  
  1555. MIPMAN
  1556.  
  1557. The Message Interchange Protocol (MIP) is managed by the MIP tool (MIPMAN.AOL) and provides a generic way to transports messages, which are in the form of raw data, between the host and the client. It is also used for Auto AOL. MIP services require the services of the List Manager (AOLLIST.AOL).
  1558.  
  1559. The following services are available using both the MIP and List Manager protocols:
  1560.  
  1561. • E-mail
  1562. • Stock Quote Retrieval
  1563. • News Story Retrieval
  1564.  
  1565. The most important construct of MIP is a message. Messages are comprised of several header fields, followed by 0 or more data blocks. The header fields describe the global context of the message, including but not limited to: its source (author), its destination (recipients), when it was created, and its summary (subject). Data blocks are streams of raw data that are typed; the data block's type determines its meaning. The host may choose to send or not send certain types of data to a client based on that client's ability to interpret the data.
  1566.  
  1567. MIP tool talks a lot to MORG tool because the messages are stored in Personal Filing Cabinet which is handled by MORG. MIP tool owns the following folders in PFC:
  1568.  
  1569. • Incoming/Saving Mail
  1570. • Mail waiting to be sent
  1571. • Mail you have sent
  1572. • Incoming/saved postings
  1573. • Postings waiting to be sent
  1574. • Postings you’ve sent
  1575.  
  1576. Each folder has its own attributes and is handled by its own folder handler. When an item in those folder get clicked an event will be sent to from MORG to this folder handler in MIP and then being routed to the corresponding routing for reading and editing.
  1577.  
  1578. MIP tool also interacts a lot with Rich tool since the message content is handled by Rich control. Starting from AOL 4.0 we supports image in email. The display is handled by Rich together with other Art tools and the binary data itself is retrieved in MIP tool from host and stored in MORG.
  1579.  
  1580. Starting from AOL 4.0. The client supports multiple file attachments in email. When the compose mail form is closed by clicking “send” or “send later” button. MIP tool retrieves the list of file names that user has entered and ask Filer tool to compress the list of files and create a single Zipped file. This file name is then saved or sent together with the mail content.
  1581.  
  1582. MMI
  1583.  
  1584. The MMI.AOL tool is the multimedia interface tool. It can handle MIDI, WAV, and AVI video files. To play these files the MMI tool uses mciSendCommand messages that are part of the mmsystem accessories that one can get for Windows. The mciSendString function sends a command string to a Media Control Interface (MCI) device. The device that the command is sent to is specified in the command string.
  1585. AVI Video requires that the Video for Windows device drivers & DLLs are preloaded on the users machine. This is rarely the case for Windows 3.1 users and comes standard with Windows 95 users. WAV sound requires that a compatible sound driver and DLLs, such as the Creative Labs Sound drivers are preloaded on the users machine.
  1586.  
  1587. Sound Player
  1588.  
  1589. The sound player feature was custom developed in-house. It is part of the aolmmi.aol tool. This tool is invoked whenever a WAV file is opened during a file transfer or using the File/Open menu command on WAOL.
  1590.  
  1591. AVI Video Player
  1592.  
  1593. The AVI Video Player feature was custom developed in-house. It is part of the MMI.AOL
  1594.  
  1595. MMI does not have a ToolAtomHandler that it formally registers with the dispatcher. Instead this tool links to the KERNEL library, which has a ToolAtomHandler under the covers.
  1596.  
  1597.  
  1598. MORG
  1599.  
  1600. MORG is the Multimedia Organizer for Personal Filing Cabinet (PFC), Address Book and Favorite Places. The database format is a proprietary AOL format. MORG does not have a ToolAtomHandler that it formally registers with the dispatcher. Instead this tool links to the KERNEL library, which has a ToolAtomHandler under the covers.
  1601.  
  1602. Each folder can have a specific attribute together with call back function. Whenever there is an event happened to the folder (add, delete, double click …) the call back function gets called and the owner of the folder can perform the appropriate action at the notification There is a very good set of APIs in MORG that provides users with all kinds of functionality to the database.
  1603.  
  1604. MORG tool is also used to store connectivity information and the file name is Global.org. Most of the MORG format files are always mapped to the disk after each operation. But Global.org is an exception that is saved at a timer of two seconds unless the caller forces the database to be saved.
  1605.  
  1606. Database
  1607.  
  1608. All Favorite Places items (the items marked with a small heart) and PFC items are stored in a separate database file, per username, in the AOL\ORGANIZE directory. Unfortunately having PFC/Fav. Places databases manifested as one large file causes some difficulties. This file, lets call it the Organize file, can grow to be quite large. Each additional new record causes the file to grow larger. Some users' have reported Organize files larger than 100Mbytes. The difficulty arises when the user wishes to delete records from the file and reclaim the disk space. Marking the record as deleted is easy. Reclaiming the disk space can be laborious. Lets take a simple case of reclaiming the space occupied by one 1000 byte record that is located somewhere in the middle of the Organize file. If the user has room on his/her hardrive, the space is reclaimed by writing the entire contents of the 100MB file to another file. As the program reads each record it checks for the records marked as deleted. When the program encounters items marked for deletion it does not write them to the new file. Hence the resulting file is shorter by the length of the records marked as deleted. In the case of a 1000 byte record you have now reduced the file by 1000 bytes to 99.999MB. Then the program deletes the old file and renames the new, shorter file. The difficulty here is that, even if the code ran instantaneously, it would still take time to read and write from and to the harddrive. In the case of a 100Mb file it will take many minutes. This is the case even if you wish to reclaim the space associated with just one record containing one byte.
  1609.  
  1610. If the user does not have free space larger than the current size of the Organize file on his/her harddrive then the space recovery code sequentially searches the database file for deleted items. Each time it finds a deleted item it skips to the next undeleted item and writes that record on top of the deleted item. Then it proceeds to the next record and copies (or moves) it to the end of the previously written (or moved) record and so on and so forth. Thus the migration of undeleted items moves closer to the beginning of the file and the space associated with the deleted items migrates to the end of the file. After the entire file is searched all the items marked for deletion are at the bottom of the file in one continuous group. Then the end of the file is truncated. (In the 32 bit world a SetEndOfFile() API can be used. In the 16 bit and 32bit world writing 0 bytes to desired EOF is used.)
  1611.  
  1612. A simplified example illustrated graphically where any [1-9] is valid data, x is deleted data:
  1613.  
  1614. The uncompressed database..
  1615.  
  1616. 11111111112222222222xxxxxxxxxxx333333333344444444444xxxxxxxxxxx5555555555
  1617.  
  1618. After first deleted record is found..
  1619.  
  1620. 111111111122222222223333333333xxxxxxxxxxxxxx44444444444xxxxxxxxxxx5555555555
  1621.  
  1622. After second deleted record is found..
  1623.  
  1624. 11111111112222222222333333333344444444444xxxxxxxxxxxxxxxxxxxxxxxxx5555555555
  1625.  
  1626. After third deleted record is found..
  1627.  
  1628. 111111111122222222223333333333444444444445555555555xxxxxxxxxxxxxxxxxxxxxxxxx
  1629.  
  1630. Then null data is written to the end of the file to tell the system to adjust the end-of-file and the resulting
  1631. file looks like..
  1632.  
  1633. 111111111122222222223333333333444444444445555555555
  1634.  
  1635. The important thing to note is that there is only one pass.. empty blocks are merged into each other to cut the number of moves as they occur, thus optimizing the seek-for-deleted-space algorithm.
  1636.  
  1637. Batch Mode versus Dynamic
  1638.  
  1639. If we were to automatically reclaim the disk space each time the user deletes a record from the PFC or Fav. Places they would be forced into a significant wait if the Organize file is large. We would not want users to have to sit and wait each and everytime they clicked an item as deleted. This would be aggravating to many users. Forcing the reclamation task on users during sign-off would not be friendly either. Although it would consolidate the deletion of multiple records to one reclamation event it would still cause our app. to sit there, for possibly many minutes, before terminating, thus aggravating users that did not expect this.
  1640. Therefore we allow users to initiate the process voluntarily. We could also pop up a message box at sign-off suggesting when and how to do it and giving the user the option to do it now.
  1641.  
  1642. Long-term we need to improve this. One way is to redesign the Organize file. Rather than use one large file for the PFC/Fav. Places database we could use one file per record and have a master index to the files. (Much like the way CompuServe does their "Filing Cabinet.") However, with larger disk drives this can cause lots of wasted space due to disk granularity problems. Larger disk drives, such as one gigabyte drives have cluster sizes that are anywhere between 1K and 16K. Thus if you want to create and store a one byte file, it could take up to 16K of disk space. Since many articles and items stored in the PFC and Fav. Places are only a few hundred bytes, saving many of these, as separate files would result in large amounts of wasted space. The otherway to solve this problem is to make the Space recovery code run in the background when the client is idle. This will be fairly straightforward in the New Windows 95 true multitasking environment.
  1643. In this environment this process could be run as a separate low priority thread and would process the database incrementally. MORG contains the Space Recovery Code for the PFC/Fav. Places organize database.
  1644.  
  1645. The PFC/Fav. Places database consists of the data file and an Index file. The Index file is a permanent index that gets updates each time the user does a delete or addition to the Fav. Places or PFC. This index contains the ID, offset within the data file. When the application starts it reads in this Index file. It then creates the list of titles for the PFC & Fav. Places folders by jumping to the data file and reading the titles. The process of reading these titles can be time consuming if the number of records is large.
  1646.  
  1647.  
  1648. P3
  1649.  
  1650. AOLP3.AOL validates packets, checks and/or creates the CRC, checks and/or creates length, checks or create and Sync, TXseq, RXseq, and type. It wraps hostbound data it receives from the client with these parameters. It strips inbound packets of these, and the packet header, and sends it to the dispatcher that generally will send out the token and associated data to the tools that have registered themselves to handle the token data. Outbound packets are limited to 119 data bytes. Inbound packets can be larger.
  1651.  
  1652. The P3 Tool is a communications protocol used to ensure error-free transmission between the host and the
  1653. client computer. The data is formed into packets with an 8-byte header and a terminating carriage return. The minimum length of a packet is the header plus carriage return, the nominal length is 128 bytes, and the current maximum length is 1024 bytes.
  1654.  
  1655. The P3 protocol was designed with the following constraints:
  1656. (1) The protocol must detect any errors in transmission, and make sure that all messages are delivered without error in correct order.
  1657. (2) The number of packets sent should be kept to a minimum.
  1658. (3) The maximum size of a packet, including all headers and trailers must be less than or equal to 128 characters, because of its intended use over packet networks.
  1659.  
  1660. There are two classes of packets - numbered and unnumbered. Data packets are numbered; all other packets are not. The data packets are numbered consecutively and must be delivered in order.
  1661.  
  1662. A packet is considered invalid if it is received out of order, with an incorrect length, or bad cyclic redundancy check (CRC). If a data packet is detected as invalid by the P3 tool, a retransmission of all data packets, beginning with the number of the bad packets is requested. This ensures that the sequence of the packets is maintained.
  1663.  
  1664. P3 Packet Structure
  1665.  
  1666. typedef struct packet //Header = 12 bytes followed by data
  1667. {
  1668. BYTE sync;
  1669. WORD wCRC;
  1670. WORD wLength;
  1671. BYTE TXseq;
  1672. BYTE RXseq;
  1673. BYTE type;
  1674. BYTE data[1017]; // 1 byte slop for length overrun check...
  1675. } PACKET, FAR *LPPACKET;
  1676.  
  1677. The error detection field within the header consists of a 16-bit CRC (Cyclic Redundancy Check) which has been split into 4 bytes as follows: If the CRC was (using space to separate the bytes) x’WX YZ’, it becomes x’W1 8X Y1 8Z’. This ensures that none of the CRC codes will ever be a x’0D’. The CRC used is a standard CRC (CRC-16) for data communications developed by IBM and widely used. It will catch all errors 16 bits long or less, and 99.955% of those over 16 bits long.
  1678.  
  1679. The sequence number and response number fields with the header should be in the range of 16-127 (x’10’ – x’7F’). This will avoid unwanted values and allow for long periods between repeats. Certain control messages are un-numbered, i.e. their sequence numbers are the same as the last message sent. When they are received, they will not be ignored or discarded, regardless of their sequence number of the last correct message received.
  1680.  
  1681. Each sender has a certain number of messages it can buffer for retransmission. The range of sequence numbers currently in the buffer, plus those available for outgoingt message make up the ‘window’. The window is typically a small subset of the whole range of possible sequence numbers.
  1682.  
  1683. The message is terminated by a carriage return (x’0D’). This enables the packet network pads to collect an entire message before forwarding it along the network.
  1684.  
  1685. Message types:
  1686.  
  1687. (1) INIT (x’23’) – An INIT forces an initialization of communications. The micro is the only one allowed to send an INIT, and therefore the host can only receive an INIT. The host will clear its buffers, and set the current response and sequence numbers to the values passed by the INIT. The macro will continue sending INIT’s periodically until it receives a valid acknowledgement. The host will not send anything until it has received an INIT.
  1688.  
  1689. (2) ACK (x’24’) – An ACK is simply a null, un-numbered message. It contains the response number of the last correctly received message. An ACK is normally sent only if the sender (of the ACK) has no traffic to send, and the receiver’s window is filling up past a certain point. It is also sent in response to a valid INIT and a valid HEARTBEAT (to be described later).
  1690.  
  1691. (3) SS (x’21’) – An SS requests the other end of the connection to send an SSR. If an SS is sent, and no response is received with a given time period (10-20 seconds), it will be re-transmitted. While waiting on an SSR, the sender (of the SS) will not respond to NAK’s or open its window.
  1692.  
  1693. (4) SSR (x’22’) – An SSR is a response to an SS. It is only sent when an SS is received. Receiving an SSR will cause the receiver to retransmit any messages that the SSR indicats the sender (of the SSR) has not received. Before an SSR is sent, the NAK queue is cleared.
  1694.  
  1695. (5) NAK (x’25’) – a NAK is sent when a bad message is received (bad message being defined as a bad CRC or an out of sequence message), with certain exceptions. A NAK tells the receiver to re-transmit starting with a certain message. A NAK has a sequence number, but it is not discarded if it is out of sequence. If it is out of sequence, it is processes, and put on a stack of out of sequence NAKs. If a NAK is received that is a re-transmit of a NAK that was received correctly, but out of sequence, it is ignored. If a NAK is received while waiting for an SSR, it is ignored.
  1696.  
  1697. If a message is received incorrectly and the window is closed, it is queued to go out when the window opens. IF a NAK is already queued, it (the new NAK) is ignored instead. The NAK queue is cleared if an SS is received, to keep from asking for two re-transmission of the same messages.
  1698.  
  1699. (6) DATA (x’20’) – In normal transmission, messages are being passed in both directions. Each message sent carries the number of the last message correctly received, which is an implicit acknowledgement of all messages up to and including that one. When a message is received correctly, it is passed up to the application level. Then the response number of the message is examined. If it acknowledges any messages currently in the buffer, they are dropped from the buffer. If the receiver of the message has received a certain number of messages without acknowledging, it will send an ACK to keep the sender’s window from closing. (A window is closed when the buffer of sent messages is full, preventing any more transmissions.)
  1700.  
  1701. If a single message gets mangled, the receiver will get a bad checksum, and send a NAK (assuming its window is open) requesting re-transmission of all messages starting at the mangled one. It will then ignore out of sequence messages until it gets the mangled message correctly. If its window is closed, and there is no NAK queued, it will queue the NAK for transmission when the window opens. If there is a NAK queued already, it will ignore the new one.
  1702.  
  1703. The same NAK logic would apply to messages received out of sequence, assuming that a NAK had not already been sent.
  1704.  
  1705. In all cases, where a numbered message is sent, the window is checked. If it is closed, an SS is sent to try to re-open the wondow. When an SS has been sent, and no SSR has been received, all NAKs are accepted, but they are ignored, instead of being processed.
  1706.  
  1707. When a SSR is received, any messages that were not received are queued for transmission. When there is a message to send, and the window is open, it is sent and put into buffer. If the window is closed, the message is queued for transmission. This is separate from NAK queue.
  1708.  
  1709. (7) HEARTBEAT (x’26’) – If either side of the connection, has an un-acknowledged message for more than some period of time (10-20 seconds), and has not received any communication from the other side, it will transmit a heartbeat. A heartbeat is an un-numbered message, and the only response to a heartbeat is to send an ACK.
  1710.  
  1711. Token, Protocol, Class and Atom Data and Size
  1712.  
  1713. The token is always the first two bytes of the packet data. In any atomized packet, it's followed by a stream ID and then the atoms. Atoms can be encoded a number of different ways ("styles"), so where the protocol, atom #, and length are stored depends on the style being used. The most often used style ("full") is simply:
  1714.  
  1715. <protocol> <atom> <length>
  1716.  
  1717. Initialization
  1718.  
  1719. Once the user is connected to the host a message is sent to CSL that in turn sends a MSG_P3_START message to the P3 ToolMsgHandler. The P3 tool handler calls a function P3Start that uses the subroutine: SetCommDataCallback(... (LPFN)P3DataHandler) to set up the P3DataHandler callback function address to be used by the comm port subroutines each time new data comes in.
  1720.  
  1721. Runtime
  1722.  
  1723. Each time new data comes in from the comm port (via AOLMODEM.AOL) the P3DataHandler is called. The comm port data (a P3 packet) is passed to it through its argument list. It handles the P3 packet using a
  1724. function called: HandlePacket which parses the packet and places it in a Queue called: QueueInputPacket. At the end of the P3DataHandler a DispatchPacket subroutine is executed. It sends a message using
  1725. ToolSendMsg to broadcast the P3 data primarily to the ATOMIZER in SUPERSUB.dll.
  1726.  
  1727. Downloads come down to the client in 1k packets where uploads come up to the host in 119 byte packets.
  1728.  
  1729.  
  1730.  
  1731. SECURITY
  1732.  
  1733. This tool is responsible for the security handshake after the connection is established. This handshake authenticates the host as AOL, and negotiates a session key to be used during the current session. It has the capability to wrap/unwrap any packet sequence. Wrapper provides both an integrity check and encryption. Most of the code in this tool is also used in the security server and in an application to manage the SafeKeyper device for private keys. The server contains additional security code that is highly compatible with the security tool in the client to allow use of existing and new code across platforms and applications.
  1734.  
  1735. AOL 4.0 has the following security implementations:
  1736. Secure Login (Handshake)
  1737. Old Technique
  1738.  
  1739. INIT Packet
  1740.  
  1741.  
  1742. ACK
  1743.  
  1744.  
  1745. DD packet
  1746. (contains plain text SN/PW)
  1747.  
  1748.  
  1749. Secure Technique
  1750.  
  1751. INIT Packet
  1752.  
  1753.  
  1754. ACK
  1755.  
  1756.  
  1757. DD packet
  1758. (contains plain text SN/PW)
  1759.  
  1760.  
  1761.  
  1762.  
  1763. New Login Process:
  1764. • Init packet sent from client to host
  1765. • Client receives ACK from host. If client is secure (currently a database setting), sends a “Wh” token with the first of several sections of data
  1766. • Host acknowledges with “Wk” token
  1767. • These tokens, passed back and forth establishes client as secure, and sets the maximum level of encryption avaliable to that particular client
  1768. • Once this section is successfully completed, the encrypted version of the “Dd” token, “Wd” is sent to the host
  1769. • The client is now connected to the host and has been marked as secure
  1770.  
  1771. Form Level Encryption
  1772.  
  1773. Forms are completely encrypted as the form is sent from the host. Retriever sends the whole form via security server which encrypts the entire form.
  1774.  
  1775.  
  1776.  
  1777.  
  1778. Field Level Encryption
  1779.  
  1780. The form comes down as normal, with certain fields marked for secure extraction, and or data is delivered to the form as an encrypted MAN_APPEND_SECURE_DATA.
  1781.  
  1782.  
  1783.  
  1784.  
  1785.  
  1786.  
  1787.  
  1788.  
  1789.  
  1790.  
  1791.  
  1792.  
  1793.  
  1794.  
  1795.  
  1796.  
  1797.  
  1798.  
  1799.  
  1800.  
  1801.  
  1802.  
  1803. SHORT
  1804.  
  1805. AOLSHORT.AOL contains a number of shorthand atoms used to reduce the atom stream overhead associated with repetitive atom streams (like K1 token).
  1806.  
  1807. XFER
  1808.  
  1809. The File Transfer Tool (AOLXFER.AOL) provides for error free transfer of files between the online service client application and the AOL host. Both uploading and downloading of files are supported. In addition to single file transfers, batch downloads can also be performed. Downloads can be interrupted and resumed at a later time.
  1810.  
  1811. The File Decompression Tool (Pakman.c) in XFER.AOL provides the online service with the ability to
  1812. decompress files that are compressed with the ZIP format. Often, files on the online service available for
  1813. downloading are compressed to shorten the length of the download time. This tool lets members decompress files manually or request that files be decompressed when they sign off. It also lets members choose if they want the compressed files automatically deleted after they are decompressed. There are no atoms associated with this tool.
  1814. Timing Tests for File Upload
  1815.  
  1816. The WAOL 3.0 client is not throttled. Therefore its upload limit will be the limit of the host. In this case it will be the Terminal Handler (TIH) that limits to approximately 57Kbps.
  1817.  
  1818.  
  1819. WWW
  1820.  
  1821. The AOL for Windows Browser Integration Approach
  1822. Overview
  1823.  
  1824. In order for a web browser to be integrated into America Online for Windows, it must be factored into a standard Windows custom control that resides in a DLL. This control should consist of the scrolling document portion of the browser and should not include any buttons, status bars or gauges, menus, or dialog boxes displayed outside of the main document view. This approach was taken in order to leverage the best features of both the browser and AOL; it allows us to display the rich content of the World Wide Web within the familiar, user-friendly surroundings of the AOL user interface. It also gives form designers a great deal of latitude to create compelling “hybrid” windows that blend web and AOL content in interesting ways.
  1825.  
  1826. Using the Windows custom control standard has many advantages: It removes the need to exchange source code, is language and memory model independent, and is above all a simple and well-known interface. Conceptually, integrating a browser into AOL is straightforward, although converting an application-centric browser into a DLL can be a considerable undertaking depending on the current state of the code.
  1827.  
  1828. Responsibilities of the Browser Custom Control/DLL:
  1829.  
  1830. • Paint and manage scrolling for the document window. This includes all content displayed within that view, including HTML forms and background bitmaps. The browser control must not display anything outside of that view (such as buttons, status windows, dialog boxes, menus, etc.) -- those will be provided by AOL. In a similar vein, AOL will never draw in the browser view window.
  1831. • Support multiple, independent instances of browser controls open simultaneously. This is vital to AOL’s web browser implementation, where forms throughout the service now seamlessly mix AOL and WWW content.
  1832. • Support the Johnson-Grace ART content type for image compression by making appropriate calls to the J-G decompression DLL.
  1833. • Display the appropriate cursor bitmap when the cursor is over a hyperlink or image map in the document view.
  1834. • Perform all HTTP, FTP, etc. conversations as normal. In the case of the 16-bit control, this will involve linking to AOL’s custom “AOLSock” DLL instead of to WinSock, though all API calls will be exactly the same. Few if any changes to the communications layer of a browser are required to interface with AOL.
  1835. • Perform all HTML parsing as normal.
  1836. • Provide a suite of custom window messages that AOL can use to control the browser view. These messages include the following: Load and display a specific URL, cancel transmission, reload, print, copy to clipboard, etc.
  1837. • Provide an interface to allow AOL to designate proxy server information, cache preferences, and other relevant settings.
  1838. • Notify AOL (via notification window messages) of various events relating to the browser as they occur: errors loading documents, status of the current load, requests to jump to URLs (by selecting hyperlinks), the need to display a dialog box (for searching, authentication, and security), occurrences of unhandled content types, etc.
  1839. Responsibilities of the AOL application:
  1840.  
  1841. • Create and destroy browser views of appropriate size and position as necessary.
  1842. • Control all form layout external to the browser view.
  1843. • Display all necessary errors, status messages, and dialog boxes in response to events from the browser view.
  1844. • Maintain the history list that enables back and forward navigation for each browser view.
  1845. • Manage the external viewer list and launch viewers in response to events received from the browser view.
  1846. • Provide WinSock-complaint dial-up TCP/IP.
  1847.  
  1848. When WAOL launches, its loader will load all the WAOL tools. Among them is the WWW.AOL tool. WWW is a managed-by-tool that receives managed-by messages and WWW atoms. It also registers itself to receive a number of WWW atoms. When the WWW.AOL tool loads it will initialize itself and register the WWW Control Process function (WWWControlProc) which will handle all the browser event control messages (IWENG_EVT).
  1849.  
  1850.  
  1851. The IWENG browser DLL uses several channels of communication to perform various actions.
  1852.  
  1853. Managed-by-Tool Messages
  1854.  
  1855. For direct control of features such as browser window creation, resizing, saving, and printing WAOL sends commands via Managed-by-tool messages (via Manager atoms) to the WWW ToolObjNotifyHandler. These messages call functions that, in most cases, eventually call the IWENG_REQ messages (IWENG REQuest messages) that are sent to the IWENG DLL using the Windows API SendMessage function.
  1856.  
  1857. WWW is a managed-by-tool that is sent messages from Manager.AOL if the WWW_MANAGE atom was previously sent in the object stream. The WWW has a ToolObjNotifyHandler that handles OBJ_MSG messages usually sent by Manager.AOL. WWW also defines a set of WWW atoms that it uses for direct browser control.
  1858.  
  1859. Managed by Messages
  1860.  
  1861. OBJ_MSG_CREATE sent in Response to MAN_UPDATE_DISPLAY atom will call a WWW function called CreateBrowser if the WWW_MANAGE atom was previously sent within the stream. This function uses the Windows API CreateWindow to create a child window that uses the WWWControlProc, to handle IWENG_EVT messages, subclassed by IWENG. The CreateBrowser function will also initialize the IWENG.DLL, set anchor colors, loaded anchor colors, background color, set layout configurations including margines, set the proxy configuration and context.
  1862.  
  1863. The OBJ_MSG_DESTROY is sent in response to a WM_DESTROY and is used for debug purposes.
  1864.  
  1865. The OBJ_MSG_GET_SIZE is sent by the routines that need to create or update the window. In the process of updating the window it requests the size of the window. This message will update a structure used by the browser to report its window size.
  1866.  
  1867. WWW Atoms
  1868.  
  1869. For direct control of features such as loading URLS, going back to previous URLS, reload URLs, purge cache, stop, get current title, go back, go forward, refresh preferences, etc., WAOL uses a set of WWW atoms. These atoms call Atom Handler functions, that have been individually registered by the WWW tool. The Atom handler functions use IWENG_REQ messages that are sent to the IWENG DLL using the Windows API SendMessage function.
  1870.  
  1871. A number of new atoms have been create to control the browers. These atoms include:
  1872.  
  1873. WWW_LOAD_URL WWW_GO_BACK
  1874. WWW_GO_FORWARD WWW_RELOAD
  1875. WWW_STOP WWW_GET_CURRENT_URL
  1876. WWW_GET_CURRENT_LINK WWW_GET_PARTS_COMPLETE
  1877. WWW_CAN_GO_BACK WWW_CAN_GO_FORWARD
  1878. WWW_GET_CURRENT_TITLE WWW_BROWSE
  1879. WWW_MANAGE WWW_REFRESH_PREFS
  1880. WWW_PURGE_CACHE WWW_GET_STATUS_MSG
  1881. WWW_BOOL_SUPPRESS_ERRORS
  1882.  
  1883. These new atoms will call their respective Atom handler functions that use a wide variety of IWENG_REQ messages to ask the browser to perform various functions.
  1884.  
  1885. For example:
  1886.  
  1887. The WWW_LOAD_URL will send an URL to the IWENG DLL instructing it that a specified URL be loaded. WWW will use the "IENG_REQ_Load" message to send the URL to the IWENG DLL It will also Set the graphics optimization and the layout of the web page(s).
  1888.  
  1889. WWW_STOP sends the IWENG_REQ_Cancel to the IWENG.DLL. IWENG_REQ_Cancel cancels the current load process in the IWENG.DLL
  1890.  
  1891. Developers should take note that the WWW tool does not have a “ToolAtomHandler” like many other tools, such as Manage, Atom, Xfer, etc. Instead it registers individual atom handling function for each atom (see WWW.C). And instead of using ToolRegister to register these atom handling functions, it uses the RegisterAtomProtocol with the Protocol set to PROTO_WWW.
  1892. Receiving messages from the IWENG DLL
  1893.  
  1894. Unlike most forms the WWW Window is not a MDI Window. Instead it is a WS_CHILD window that is created with the CreateWindow function using its own uniquely registered Windows type. It also has it’s own Window Procedure called:
  1895. LRESULT CALLBACK __export WWWControlProc(HWND hWnd, UINT message, WPARAM wParam, LPARAM lParam).
  1896. When the IWENG DLL (API) needs to send messages to WAOL it sends IWENG_EVT messages (IWENG EVenT messages) to the WWWControlProc procedure. The WWWControlProc is the WWW Window procedure that is defined in the WWW.AOL tool and subclassed by the IWENG to handle the IWENG_EVT messages and a select set of Windows messages.
  1897.  
  1898. The IWENG.DLL will send IWENG_EVT (IWENG Event messages) to the WWWControlProc procedure allowing WAOL to show status, jump to URLs, display text describing hot spots, and Offer/Give.
  1899.  
  1900. The Offer/Give mechanism is used everytime a document is to be downloaded. This mechanism allows WAOL to intercept certain content types.
  1901.  
  1902. After a hyperlink has been activated the InternetWorks DLL (IWENG) establishes a connection to the document server. Once this connection has been established the document header is downloaded.
  1903.  
  1904. Some of the information in the header is then stored in an IwEngOffStruct and then the DLL sends an IWENG_EVTOffer event message which is intercepted by the WWWControlProc window handler function.
  1905.  
  1906. At this point the WWWControlProc can inspect the IwEngOffStruct and decide if the DLL should handle the document content. If WAOL does not have the built -in capability to handle the data then it will ask the user if they still want the offer given WAOL does not have a helper application for it. If the Offer is excepted the IWENG DLL will then download the document content and either display it or, if the "offer" was accepted, store it to the specified file. (This includes files like AVI, WAV and MIDI files.) If the "offer" was accepted then at this point the DLL will send the IWENG_EVT_Give event message.
  1907.  
  1908. Receiving and Displaying Content from Remote Servers
  1909.  
  1910. IWENG.DLL communicates with remote servers through the Winsock. The Winsock interfaces with the AOLSOCK.AOL tool in Win3.1. In Windows95 the IWENG.DLL communicates with remote server through MS WinSock, the MS TCP/IP, NDIS, and the AOLMAC.VXD, and then to the AOLSOCK.AOL tool. See the chapter on AOLSOCK for further details. IWENG does all this work without getting WAOL directly involved with the retrieval of remote server content.
  1911.  
  1912. Internet Works Engine IWENG
  1913.  
  1914.  
  1915. IWENG API Overview
  1916.  
  1917. The InternetWorks Browser Applications Program Interface (API) is delivered as a DLL which provides the user with World Wide Web (WWW), Gopher and File Transfer Protocol (FTP) access to the Internet. It does not provide access to either Net News or Mail.
  1918.  
  1919. The API is broken down into three parts. The first is a small set of functions which the are used for initialization, cleanup etc. . The second part is a set of Events which the DLL creates. Finally, the third part is the Message Set which makes up the bulk of the API.
  1920.  
  1921. IWENG Browser DLL Block Diagram
  1922.  
  1923.  
  1924.  
  1925. Interfacing
  1926.  
  1927. The primary interface to IWENG is through its API. Its API consists of a set of predefined structures, API functions, REQuest messages and Event messages. (Please se AOL North API Document for further details.)
  1928.  
  1929. The API functions are used to create and initiate the IWENG.DLL. WAOL, via WWW.AOL, uses IWENG_REQ_xxxxxx messages to request an action. The browser sends IWENG_EVT_xxxx messages to WWW’s subclassed window procedure.
  1930.  
  1931. The following briefly describes the above block diagram:
  1932.  
  1933. API : API Function & Messaging interface to WWW & WAOL
  1934. Loader : Coordinates actions among IWENG modules
  1935. NetLoad : Establishes Server/Network connections, handles network interactions
  1936. WWW : (Not WWW.AOL) Creates Protocol classes an interfaces with Winsock
  1937. WinSock : Windows Socket for interfacing with TCP/IP stack
  1938. Parser : Parses data into appropriate type, in the case of HTTP it parses data into HTML commands
  1939. Content : Creates structure that holds web page data & associated parameters
  1940. Cache : Holds previously retrieved data (i.e. web pages)
  1941. Layout : Sets up the layout of the web page (i.e. margins, background color, etc.)
  1942. Window : Actually paints the web page in the WAOL/WWW.AOL provided window
  1943. Global : Contains IWENG global variables (i.e. HTTP Proxy, Port, Graphics settings, etc.)
  1944.  
  1945. Communication
  1946.  
  1947. One of the parameters required during initialization and setup of the API is the Window Handle <Popup with explanation that Window Handle = HWND>. This Window Handle is used to pass messages to and from the API. This window is also used by the API to render information obtained from the WWW, FTP or Gopher services.
  1948.  
  1949. The IWENG.DLL is runtime lodaed when the WWW.AOL tool is loaded by the WAOL loader. The IWENG.DLL is not loaded using LoadLibrary.
  1950.  
  1951. For further details on the IWENG.DLL see the IWENG API & Messaging Document published by AOL North.
  1952.  
  1953. 1. What is a WildMask?
  1954.  
  1955. It's used in conjunction with a proxy server setting. A WildMask is a range of IP addresses to which no proxy should be used. Normally, if a proxy server is specified, all connections are directed to the server
  1956. first. However, if a connection to a specific range of servers is intended, the proxy server is ignored. An example is: 208.118.*.*
  1957.  
  1958. 2. How does a trusted server differ from a normal or standard server?
  1959.  
  1960. I'm not sure how this ties in with the browser, but in network admin a trusted server is a well-known server from which connections to other machines are trusted. What exactly did you have in mind here?
  1961.  
  1962. 3. What is a POP3?
  1963.  
  1964. Post Office Protocol. As opposed to SMTP (Send Mail Transport Protocol), which allows an app to send mail, POP sets up a mail source on a server to which a mail client can send and receive email.
  1965.  
  1966. 4. What is the difference between a Proxy & a Port?
  1967.  
  1968. Proxy is the name of a server through which all connections should be made, and a port is the socket port # on the proxy server on which connections are accepted.
  1969.  
  1970. Interfacing to AOLSOCK
  1971.  
  1972. When using the browser it uses AOLSOCK.AOL to interface with WAOL instead of Winsock. AOL North complies the IWENG.DLL with the interface set to WINSOCK. When building a new WAOL disk you will need to use a hex editor to open up the IWENG.DLL, search for the string WINSOCK and change it to AOLSOCK. Then save IWENG.DLL and build a disk using this newly modified form
  1973. Browser
  1974. SSL - Required UI change. When the browser enters a secure page a dialog box will come up with a message indicating a secured area.
  1975. Reload - A Reload option is included that checks the data of previously loaded images. If an image date has changed the new image will be loaded, else the old image that was saved will be loaded.
  1976. Pdata.bin
  1977. This file caches all user-id/password hits the user encounters at FTP sites, authenticate HTML sites, etc. This way, the next time the user hits those sites, they don't have to type their user-id/password pairs again.
  1978.  
  1979. Client Internationalization
  1980.  
  1981. The client code internationalization is accomplished through the following steps:
  1982.  
  1983. (1) All the strings and dialogs are centralized under “Res” subfolder of each tool. In the latest of version of the client they are merged into one folder and will be built independently.
  1984.  
  1985. (2) NLS dll for the foundation of internationalization. This dll supports the string conversions from host to client and from client to host, digression on host-client interface, string APIs (nlsStrChr, nlsStrrChr, nlsStrStr, nlsStrncpy …), data formatting APIs, Checkchar API for enforcing filters on type-in text, APIs for getting system languages.
  1986.  
  1987. (3) A set of internationalization atoms is used to localize data sent from the host system to international clients. These atoms localize text, data/time formats, and data types according to time zone and language preferences specified within the member preferences of AOL. Host data is also localized according to data and time settings within the client computer OS. Refer to Appendix B of FDO91 Manual for details of these atoms.
  1988.  
  1989. As we know the Client is atom driven, large part of internationalization involves converting the atom streams. When SUPERSUB.DLL dispatches each atom to the corresponding tools one of the parameter is for the language data type. Atom “uni_start_typed_data <data_type>” is used to set this data type which applies for the text arguments of all subsequent atoms where value 0 is the default (ASCII), 260 is for Latin1, and 4096-6143 is for Unicode. When the subsequent atoms come in each tool will call Htext2Ctext (in NLS.dll) to convert the string arguments based on the data type. Atom “uni_end_typed_data” will set the data type back to ASCII.
  1990.  
  1991. Starting from AOL 4.0 the client becomes globalized software which means that further design and coding should cover “internationalization” by the accomplishing the following:
  1992.  
  1993. • All strings should be placed in resource files
  1994. • Avoid assumptions about sentence structure: “You have selected abc.dat” should go in string file as “You have selected %s” instead of “You have selected” with idea of concatenating a filename argument.
  1995. • Dates/Times are language sensitive. Use NLS dll APIs.
  1996. • Avoid run-time library string functions because they do not work for MBCS (Multiple Bytes Character Set). NOTE: Windows APIs (e.g. lstrlen), NLS APIs (e.g. nlsStrStr), memcpy and _fmemcpy are OK.
  1997. • DOS calls with string arguments must be wrapped as the following: OemToAnsi(arg), DosCall(arg), AnsiToOem(arg).
  1998. • Do not assume 1 char = 1 byte. Use AnsiNext, AnsiPrev to walk a string. Do not break strings at arbitrary length.
  1999.  
  2000. The process of creating globalized software has two facets – “internationalization” and “localization”. AOL client localization includes translating all the strings, local forms and dialog boxes. This is done by a separate team.
  2001.  
  2002.  
  2003. Appendix: Advanced Topic On DOD
  2004.  
  2005. Data and Artwork, for buttons and form backgrounds, can be updated using Data On Demand (DOD). The DOD code lives in MANAGER.AOL and in IDB.AOL. Please refer to the respective modules for additional information. It should be noted that, at this time a major redesign of the DOD section is underway to add progressive rendering capability to the DOD feature.
  2006.  
  2007. The Progressive Rendering DOD (PDOD) feature will update artwork on forms, and download the data to the member’s local hard drive in a progressive mode. The new form is initially displayed in skeleton form and is fully usable, but not highly readable, before all the art is downloaded to the form. The skeleton form will initially have default buttons and artwork with hint titles. The sizing of the various objects within the form will be accomplished with the use of new size hinting atoms. The DOD artwork will be downloaded and rendered to the form in a progressive manner. The data downloads for each displayed form will be prioritized with the top-most form (foreground window) having the highest priority. If a form loses focus (due to a different form gaining focus), its art data will be sent in slower pace. Even if it's the only form that has pending requests, art delivery will not become faster. The reason is that the user may be actively interacting with a different form (e.g. chat) and by slowing down art delivery, the user gets a better interaction response. The artwork associated for each form will be stored to the local database. If the form is closed before the download is done, the artwork for objects that completed the download will be saved to the main.idx database, the art associated with an object that is in progress will finish downloading to the local database, and any art that has not begun a download will not be sent. If at a later time the user clicks on a object that requires this form they will see the form partially filled with the previously saved DOD art. The remaining art will then be sent to the form from the host.
  2008.  
  2009. Once the foreground form artwork is completely downloaded and rendered the client/host will go back to the previous forms(s) (background forms) and continue to download the necessary art and render the background forms at a faster rate.
  2010.  
  2011. Progressive DOD will involve two phases - A more detailed look at the process.
  2012.  
  2013. 1. Form phase.
  2014. 2. DOD Art reception and progressive rendering phase.
  2015.  
  2016. New Forms - Form Phase
  2017.  
  2018. During the first phase, the form atom stream will be transmitted. This will happen quickly because most forms can be sent in relatively few packets, more specifically most forms can be sent in five to 20 packets of data. The size hinting atoms (the hinting atoms will contain X & Y gadget size information will be embedded in the beginning of the form’s atom stream for all forms and the title hinting atom stream willbe embedded within the stream for new forms. Included in this list will be a sepcial tag. This tag will be used to request the DOD data. The forms will then be rendered using the X & Y hinting atoms, default images, bitmaps and hinting titles. For example: suppose a form with several buttons is requested. The form will be rendered in skeletal form with the bitmaps on the buttons replaced with default bitmaps (under Yellow & Black under construction strips covering only a small portion of the object) and size to the values stored in the X & Y hinting atoms with the hinting title placed in the button titles.
  2019.  
  2020. Old Forms - Form Phase
  2021.  
  2022. If the form is an old form, and it is not present on the client, then a request will be made, by the client, for special DOD hinting atoms after all the form atoms are received, but before the form is rendered. However in this case, since the form and art will be of the old style, only the X & Y hinting atoms will be sent. No hint title will be sent. These hinting atoms will contain size information used to draw skeleton buttons and other controls on the form. Once the hinting atoms are received the form will be rendered using default images and bitmaps. In this case of no hinting titles, default titles will be used. These titles will be “Click Here” and “Picture Here.” These titles are generated and placed by the client. These hinting atoms along with the DOD data will be stored in the main.idx database for future use. At this point the form is fully functional.
  2023.  
  2024. What the Host Does if it is an Old Form.
  2025.  
  2026. When a separate request for hints come in to the host from the client, due to an older form, a host process will retrieve the hints from a hinting table in the Host hinting table cache. If it is not present in the host cache, because not one even member has requested it yet, then the host process will retrieve the DOD art file, open it and extract the hint. It will then place the hint in the cache. Once the hint is in the cache table it does not need to be extracted again for the next DOD hint request. The time required to extract this hint will not be noticeable to the user. This cache table will grow quickly. At each system bounce (usually on Tuesday mornings) the DOD hint cache table will be lost and will begin rebuilding at start-up.
  2027.  
  2028. Rendering Phase
  2029.  
  2030. Once the skeleton form is rendered the second phase begins. The client will then request the DOD art using the tag described above. The host will begin sending the data intensive DOD art. The DOD art, except Windows bitmaps, will be progressively rendered into the form as it comes in. However, Windows bitmaps will not be progressively rendered. Windows bitmaps are generally used on buttons and are usually quite small therefore the Windows bitmap will be popped on the button as soon as all the data is available. During this period all the controls will still be fully usable. Additionally the various controls and the locations for art will contain the minimal text info. while the art is being received and rendered.
  2031.  
  2032. All new forms and associated DOD art will automatically be created using the new formats that includes embedded hinting atoms. Form_edit is being modified to support the new hints. The X & Y hint atom insertions will be automatic and transparent to the producer. However, producers will have to manually enter the hinting titles for each new object.
  2033.  
  2034. It should be noted that all DOD art is always stored to the local main.idx database on the client. All DODs are sent uncompressed. It should also be noted that images, like those associated with a news article, are attached to a form using Rainman. These images are not DODed and ofcourse do not get stored in the main.idx database. Instead they are compressed/decompressed using the Johnson Grace format.
  2035.  
  2036. No Progressive Rendering
  2037.  
  2038. Title bar icons in the upper left hand corner of the forms is not progressively render. In other words they still use the old style DOD, they wait and download and then render. Sounds will not be progressively DODed either, sounds and title bar icons will still display a progress gauge in a modal format.
  2039.  
  2040. Free DOD Downloads
  2041.  
  2042. Free bulk downloads use one Object ID, the progress gauge, to download multiple DODs. Unfortunately new forms with PDOD hints will suppress the progress gauge while downloading art. This would give the impression, to the user, that the system has hung. The code implements a work around to this particular case. The code watches for multiple DODs to the same Object. The code records the pointer address of the object associated with the first DOD and if a second DOD occurs, within the same stream, it checks the associated object, if it is the same as the first then it knows it is a free DOD download. In this case the very first DOD will be progressive, if a Progessive DOD form with hints is used. The second and subsequent DODs, to the same object, will then force the progress gauge to display for subsequent PDODs or DODs to the same object. In this mode no DOD hints will be requested.
  2043.  
  2044. The following describes the proposed new background DOD protocols between the host server and the client software:
  2045.  
  2046. The following needs updating!!!
  2047.  
  2048. New Atom Definitions for Progessive Rendering of DOD (Not Complete):
  2049.  
  2050. atom$mat_art_hint_width <x>
  2051. This atoms is sent by the host to tell the client the width of the art. If this atom is not present, art DOD must complete before the form can be displayed.
  2052.  
  2053. atom$mat_art_hint_height <x>
  2054. This atoms is sent by the host to tell the client the height of the art. If this atom is not present, art DOD must complete before the form can be displayed.
  2055.  
  2056. atom$mat_art_hint_title “string”
  2057. This atoms is sent by the host to tell the client the title of the art. This atom can be modified by atom$uni_start_typed_data and atom$uni_next_atom_typed to include typed data.
  2058.  
  2059. atom$dod_start
  2060. This atom starts a DOD transaction. It can be used both ways. When it is used by the client, it indicates a request for DOD. When it is used by the host, it indicates a reply to a previous DOD request.
  2061.  
  2062. atom$dod_type <type>
  2063. This atom is used by the host to indicate the type of the DOD sent.
  2064.  
  2065. atom$dod_gid <gid>
  2066. This atom indicates the requested dod global id. It is sent from the client.
  2067.  
  2068. atom$dod_form_id <gid>
  2069. This atom indicates from which form the DOD is requested. It will be sent from the client.
  2070.  
  2071. atom$dod_end
  2072. This atom indicates end of the current DOD transaction. It will be used by both the host and the client.
  2073.  
  2074. atom$dod_gain_focus
  2075. The client will use this atom to inform the host that a form specified by atom$dod_form_id atom is gaining the current focus.
  2076.  
  2077. atom$dod_lose_focus
  2078. The client will use this atom to inform the host that a form specified by atom$dod_form_id atom is losing the current focus.
  2079.  
  2080. atom$dod_ form_closed
  2081. The client will use this atom to inform the host that a form specified by atom$dod_form_id atom is closed by the user.
  2082.  
  2083. atom$dod_data <data>
  2084. This atom is sent by the host to include all the DOD data. Multiple atom$dod_data atoms can be sent for a large DOD object.
  2085.  
  2086. atom$dod_not_available
  2087. This atom is sent by the host to indicate a requested DOD is not available on the host or any reason.
  2088.  
  2089. atom$dod_end_data
  2090. - sent when all data has been delivered for a piece of art.
  2091.  
  2092. atom$dod_no_hints
  2093. - used in two ways. Client uses it to indicate that a request does not need hints. Host will not send hints when this atom is received. Host also uses this atom to indicate to client that requested art has not hints. This happens only when the art itself does not exist.
  2094.  
  2095. atom$dod_hints
  2096. - host uses it to send (width,height) hints to client. Its value has four bytes - first 2 corresponds to width, last 2 corresponds to height.
  2097.  
  2098. atom$dod_end_form
  2099. - client sends it to indicate that the form has been traversed completely and the host can start sending art data.
  2100.  
  2101.  
  2102. Progressive DOD Tokens
  2103.  
  2104. Some new tokens will be defined for host bound requests. We have a new token for the new styled art DOD, and a new token for art DOD control.
  2105.  
  2106. • Token for new styled art DOD: fh
  2107. • Token for art DOD control: ff
  2108.  
  2109. Progressive DOD Example:
  2110.  
  2111. From the host, when an art work is referenced, the following will be sent with the object:
  2112.  
  2113. atom$uni_start_stream
  2114. atom$man_start_object <ind_group>
  2115. atom$mat_object_id <32-1234>
  2116. ...
  2117. atom$man_start_object <trigger> “”
  2118. atom$mat_relative_tag <1>
  2119. atom$mat_art_id <1-0-1234>
  2120. atom$mat_art_hint_width <x>
  2121. atom$mat_art_hint_height <y>
  2122. atom$mat_art_hint_title “title”
  2123. ...
  2124.  
  2125. When the client gets the art, it will trigger a DOD if the art work is not in the database. The following stream is sent to request the DOD.
  2126.  
  2127. atom$uni_start_stream
  2128. atom$dod_start
  2129. atom$dod_form_id <32-1234>
  2130. atom$uni_transaction_id <1>
  2131. atom$dod_gid <1-0-1234>
  2132. atom$unitransaction_id <2>
  2133. atom$dod_gid <1-0-1235>
  2134. atom$uni_transaction_id <3>
  2135. atom$dod_gid <1-0-1236>
  2136. atom$dod_end
  2137. atom$uni_end_stream
  2138.  
  2139. The host will send the following stream to the client.
  2140.  
  2141. atom$uni_start_stream
  2142. atom$dod_start
  2143. atom$uni_transaction_id <1>
  2144. atom$dod_type <dod_art>
  2145. atom$dod_data “...”
  2146. atom$dod_data “...”
  2147. ...
  2148. atom$dod_end
  2149. atom$uni_end_stream
  2150.  
  2151. atom$uni_start_stream
  2152. atom$dod_start
  2153. atom$uni_transaction_id <2>
  2154. atom$dod_type <dod_art>
  2155. atom$dod_data “...”
  2156. atom$dod_data “...”
  2157. ...
  2158. atom$dod_end
  2159. atom$uni_end_stream
  2160.  
  2161. atom$uni_start_stream
  2162. atom$dod_start
  2163. atom$uni_transaction_id <3>
  2164. atom$dod_type <dod_art>
  2165. atom$dod_data “...”
  2166. atom$dod_data “...”
  2167. ...
  2168. atom$dod_end
  2169. atom$uni_end_stream
  2170.  
  2171. When the user changes the current focus from the current form to a different form, the client will send the following stream to the host.
  2172.  
  2173. atom$uni_start_stream
  2174. atom$dod_start
  2175. atom$dod_form_id <32-1234>
  2176. atom$dod_lose_focus
  2177. atom$dod_end
  2178. atom$uni_end_stream
  2179.  
  2180. When the user changes the current focus back to an earlier opened form, the client will send the following stream to the host.
  2181.  
  2182. atom$uni_start_stream
  2183. atom$dod_start
  2184. atom$dod_form_id <32-1234>
  2185. atom$dod_gain_focus
  2186. atom$dod_end
  2187. atom$uni_end_stream
  2188.  
  2189. When the user closes the current form, the client will send the following stream to the host.
  2190.  
  2191. atom$uni_start_stream
  2192. atom$dod_start
  2193. atom$dod_form_id <32-1234>
  2194. atom$dod_ form_closed
  2195. atom$dod_end
  2196. atom$uni_end_stream
  2197.  
  2198.  
  2199. When the host can not satisfy a DOD request for any reason, the following stream will be sent.
  2200.  
  2201. atom$uni_start_stream
  2202. atom$dod_start
  2203. atom$uni_transaction_id <1>
  2204. atom$dod_not_available
  2205. atom$dod_end
  2206. atom$uni_end_stream
  2207.  
  2208. Host Process for new PDOD : DOD_MAN_RETRIEVER
  2209.  
  2210.  
  2211. Masking
  2212.  
  2213. In order to make parts of an image transparent the client uses a masking color to determine which parts will be transparent. Masking involves setting a special bitmap color in the header of the DOD art. This mask can be any value and is usually set by the art department. The DOD art will have the mask color embedded in it everywhere the art should be transparent. When the client receives this DOD art it looks for the mask color and then builds a separate mask bitmap, on the fly, from the original DOD art. The client then uses StretchDIBits and the appropriate ROP code to paint the DOD art with all locations defined by the separate mask bitmap as transparent and all other pixels will be the actual color.
  2214.  
  2215. Appendix: UDO
  2216.  
  2217. UDO (Update Disk Operation) can be used to update forms and artwork data on the client. Specifically it can be used to update the contents of the main.idx. A UDO, if it occurs, always occurs automatically right after sign-on. More specifically, immediately after the host Porch process, the Update Disk process is performed, and it will do a UDO if necessary.
  2218.  
  2219. The UDO is actually an atom stream similar to atom streams created with form_edit. An atom stream is created and then compiled into a binary using the AddGen4UDO compiler. This compiler also downloads the binary to the host. The developer then updates the PCDB (PC Database) with UDO specific information, such as: Start Date, End Date, Version number, etc. The Update Disk process will then send the UDO atom stream to each client that meets the criteria as set forth in the PCDB.
  2220.  
  2221. UDOs can be used for things like changing existing forms and artwork on the user’s harddrive. It can be used to send new forms to the user. It can also be used to delete existing forms on the user’s drive. UDOs always send data in uncompressed form.
  2222.  
  2223. Update Disk always checks the time stamp in the main.idx of the user.
  2224.  
  2225. More information can also be found in the: Host Online Processes book Release 1.1 Jan. 1994-June 1995, Document Number: AOL-C-DEV-001
  2226.  
  2227.  
  2228. Appendix: TOD
  2229.  
  2230. TOD (Tool On Demand) can be used to send new AOL tools to users. A TOD is invoked, by the client software, when ever an atom, a protocol or token is received that is marked as invalid in a structure known as the Poison tree.
  2231.  
  2232. As atoms come into a client they are checked against a structure known as the Poison Tree. If a match in the tree is found, the client code will automatically put further actions on hold and ask the user if he wishes to do the TOD now. If yes, then the client code will then ask for the host to do a TOD on the tool associated with the invalid atom. A TOD is always sent in compressed form and is uncompressed with UNZIP. All new tools will be stored with the AOL extension. All files downloaded with the TOD mechanism will be placed in a TOD subdirectory underneath the WAOL directory. Each TOD will be accompanied by a TOD Command Script File. Prior to commencing with the download process the hard disk drive space on the users machine will be checked to see if it can handle the space required by the new files associated with the TOD. (The atom stream written for the TOD will have to contain the amount of space required plus some margin, for the TOD, and compare that against the space available on the users drive. If the user’s drive contains insufficient space then the process cleanly aborts. ) Once the TOD download is complete the matching invalid atom, protocol, or token, in the poison tree, is removed. WAOL will then ask the user if he wishes to exit WAOL and update the tools. If yes then WAOL will start a special executable called PHOENIX.EXE. Once it starts Phoenix, WAOL will terminate. If the user selects NO then WAOL will start Phoenix when the user exits WAOL at that later time.
  2233.  
  2234. Before terminating WAOL will check the state of a TOD flag, that should be set if a TOD process occurred. If it is set then WAOL will launch Phoenix. Phoenix will start and, using a timer, periodically check for the existence of WAOL.EXE using the GetModuleHandle API. Once Phoenix detects that WAOL has terminated it will use a PHX command script file to check to see if either WAOL.EXE or SUPERSUB.DLL need updating as a result of the previous TOD download. If a new PHX file exsits then it will be executed. Typically the PHX file will direct the simple Phoenix parser to back-up the old WAOL.EXE and SUPERSUB.DLL files into a backup directoryu and then copy the new WAOL.EXE & SUPERSUB.DLL from the TOD directory into the AOL working directory. Phoenix will then restart WAOL.EXE and wait for a conformation message from WAOL.EXE. If Phoenix receives the confirmation message from WAOL then it will terminate. If Phoenix does not receive the conformation message from WAOL then it will restore the old WAOL.EXE and SUPERSUB.DLL.
  2235.  
  2236. Terminating and restarting WAOL will force WAOL to unload all of its tools, from memory, in a manner that is highly reliable. At this point WAOL.EXE will runtime load SUPERSUB.DLL implicitly. Supersub’s loader module will then check the TOD directory for the TOD Command file script(s) (*.TOD) that come with each TOD.Supersub will then open the TOD Command file scripts and parse through its commands to determine how to take the new TOD components and load them into the appropriate WAOL directories.
  2237.  
  2238. The TOD Command file will contain a script or directions for deleting old TOD files, renaming new TOD files, moving new TOD files and/or copying TOD files to the appropriate directories. This script will contain simple statements such as: DELETE, COPY, RENAME and MOVE followed by various parameters.
  2239.  
  2240. The TOD Command File is parsed by the “Parser” found in Supersub. The Parser will read the TOD Command file one line at a time and perform the various actions. Generally the script will inform the Parser how to move TOD components into the respective WAOL directories and which files to delete in the process. Once this deletion/renaming process is complete then loader will commence loading all of the tools in the normal fashion and WAOL will continue launching. Typically this TOD script will also dictate how to backup the old tools, should the new tools fail.
  2241.  
  2242. If the TOD process fails, the TOD parser will use the Recovery.TOD file to restore all the old tools. The TOD process is an all or nothing event. Should even one tool fail to load, all old tools will be restored.
  2243.  
  2244. To Avoid Looping Conditions
  2245.  
  2246. WAOL.EXE, in addition to Phoenix, will always check for a new WAOL.EXE and a new SUPERSUB.DLL in the TOD directory at start-up. If either of these two files still exist when WAOL starts then WAOL will start Phoenix and terminate. Phoenix will then perform the necessary actions as described above and then restart WAOL. In order to eliminate the possibility of any looping conditions WAOL will keep a TOD Phoenix Counter in the registry (Windows 95) or an INI file (Windows 3.1). This Phoenix Counter will always be reset during a TOD download or a complete reinstall. Each time WAOL starts Phoenix WAOL will increment this counter. If this counter equals two or more then WAOL will not restart Phoenix under any condition. (Only give WAOL two tries to load the new WAOL.EXE and the SUPERSUB.DLL. If it did not do it successfully after the second try just give up and wait for the next TOD or complete install, at which time this counter will be reset.)
  2247.  
  2248. Backward Compatibility
  2249.  
  2250. This design will require that new WAOL.EXEs & SUPERSUB.DLLs are 100% backward compatible.
  2251.  
  2252. Diagnostics
  2253.  
  2254. Each step of the TOD process should be download to the Diag.dat buffer for downloading and debugging purposes via the Ctrl-Shift-D keyboard combination.
  2255.  
  2256. Checking the User’s Available Disk Space
  2257.  
  2258. A new atom and it respective functionality has been created to check the users disk space to determine if the user has sufficient disk space for the TOD. The atom stream sent by the host will send a stream to the client during the TOD process to query the user’s drive for available space. If the space is insufficient then the TOD process will abort.
  2259.  
  2260. Why not Let Phoenix Delete & Move All AOL Modules?
  2261.  
  2262. Many tools can be updated while WAOL is running. These tools are the so called “Smart Tools.” These are tools that, if missing, will not cause the underlying functionality of WAOL to fail. If the ability to update all tools is placed in Phoenix then WAOL would lose the ability to update the tools listed below dynamically while WAOL is running. When doing a TOD is much more preferable to update dynamically when possible to minimize disruption among users.
  2263.  
  2264. All components of a TOD download file are wrapped up in a file that has been zipped using PKZIP. The extension of these files is BUT.
  2265.  
  2266. For more information on Codeman & TODs see the chapter on CODEMAN.
  2267. How to implement TOD
  2268.  
  2269. This guild is intended to describe the process necessary to set up online code updates for the windows version of AOL. Any of the code modules that make up AOL can be replaced automatically while the member is online. The Codeman tool is primarily responsible for managing code updates, although the normal file transfer tool is used to carry out downloads of new code modules.
  2270.  
  2271. Code updates are initiated on demand, making them similiar to the data-on-demand (DOD) scheme used for updating database records. The advantage of this approach is that a module only needs to be updated if the member uses the feature in question. Since some TODs are not forced on everyone at sign-off, we can offer more of them and target them directly at the members who use the features we are updating, without alienating members who are not interested. It should be noted, however, that code updates are required; we sometimes give members an opportunity to refuse code updates, but doing so will make the feature unusable until the update is accepted. In order for code updates to remain viable as the fastest, most economical form of software distribution, we must be able to ensure that all users of a particular feature are always using the most recent version of the software.
  2272.  
  2273. Most recent code modules have been written to require a full application restart when they are replaced. A restart is necessary because the context of the module – its global variables and links to its dynamically allocated data – is lost when the original module is terminated. A mechanism does exist to allow an outgoing tool to relay its context to its replacement, but because it was created fairly late in the project, few tools have been restructured to take advantage of it. Tools that use this mechanism, such as Chat tool, are called smart tools and can be replaced at any time without requiring a restart. The purpose of replacing a tool is known as bouncing the tool. You can find out whether a tool is smart by checking its type as specified in the Master tool section called Manage Tool’s.
  2274.  
  2275. Step 1: Update the Code
  2276. Obviously, the first step in this process is to update the code module and prepare it for online distribution. Take special care to ensure that the interaction between the module and other modules is preserved; it might be necessary to include other modules in the code update if they have changed since the last release. The bottom line here is to treat code updates as if you were preparing a new disk release; there is little difference in the eyes of the user.
  2277.  
  2278. Each code module has an independent version number stored in its .RC file. The version number must be increased each time a code update for the module is created. It should also be increased whenever a new disk is released. Make a note of the new version number; it is one of several pieces of information you’ll need to have handy during this process.
  2279.  
  2280. Once the module has been successfully compiled and tested, you must create the necessary script file that accompanies the tool. The script must have the following syntax:
  2281.  
  2282. Each section of the script can have comments about each command by starting the line with a semicolon. The install section should contain, at the very least, the command necessary to copy the old tool to the TODBKUP directory, delete the old tool file, and then copy the new tool from TOD directory to the TOOL directory.
  2283.  
  2284. [install]
  2285. ; This section contains the install portion of the script
  2286. copy tool\aolchat.aol todbkup\aolchat.aol
  2287. delete tool\aolchat.aol
  2288. copy tod\aolchat.aol tool\aolchat.aol
  2289. ;
  2290. The restore section should contain the commands necessary to remove the new tool and replace it with the tool stored in TODBKUP directory.
  2291.  
  2292. [restore]
  2293. ; This section contains the restore portion of the script
  2294. delete tool\aolchat.aol
  2295. copy todbkup\aolchat.aol tool\aolchat.aol
  2296. ;
  2297.  
  2298. Lastly there should be a cleanup section that should delete all of the unwanted files from the customers computer.
  2299.  
  2300. [cleanup]
  2301. ; This section contains the cleanup portion of the script
  2302. delete tod\aolchat.aol
  2303. delete tod\aolchat.tod
  2304. ; the next line deletes the compressed tool file that contains both the script and the tool file
  2305. delete tod\aolchat.aol
  2306. ; end of script file
  2307.  
  2308. After creating the TOD script file you must compress both the tool (aolchat.aol) and the script file into a single file using PKZIP. All code updates must be compressed. In case of the Chat tool, you should use the following command:
  2309. pkzip aolchat aolchat.aol
  2310. pkzip aolchat aolchat.tod
  2311.  
  2312. It is also necessary for safety reasons, to include a place holder file that should be built by creating a small text file that contains a few characters in it. You should then name the file AOLTAG.TAG and add it as the last file to the zip archive:
  2313. pkzip aolchat aoltag.tag
  2314.  
  2315. Finally, rename the .ZIP file to *.UTF.
  2316.  
  2317. Step 2: Upload the file
  2318.  
  2319. Sign on to the test system (we’ll assume you are using test sytem arclient) and upload the .UTF file to the TOD software library. It is very important to note that the subject line of the upload file. The subject line will be used later in the TOD process to key off of when requesting the file from the host. It is also important to note the file size as this is used later as well.
  2320.  
  2321. Step 3: Design the Forms
  2322.  
  2323. Two forms must be designed using the stratus FDO 91 tool for each module offered as an update. The request form is intended to concisely provide all of the information required to explain the update members and put them at ease. It also provides all of the information required to explain the update members and put them at ease. It also provides the member with an opportunity to refuse the update before it occurs. At a minimum, the following information should be provided:
  2324. • The purpose of the module and the reason for the update
  2325. • The actual name and location of the module
  2326. • Whether or not a full application restart will be triggered after the download.
  2327.  
  2328. You are free to give th request form any appearance you want, as long as you include two predefined objects: an acceptable trigger, which must be assigned the Raw Action of atom$cm_accept_update; and a refusal trigger, which must be assigned the Raw Action of atom$cm_reject_update. These triggers may be icons or buttons and may be given any title desired. You must also complete the actions for the buttons. You may also specify any other additional actions (i.e. requesting a form explaining that the customer cannot use the new features unless they accept the update, when the cancel update button is pushed).
  2329.  
  2330. The second form that you can create, but is not required, is the splash form. This form will be displayed while the tool update is being download to the customer. This form can contain any information that is needed. However, the use of many pieces of custom artwork on this form is not recommended. Artwork would be PDOD’ed as normal, but would slow down the TOD process.
  2331.  
  2332. When saving and installing the request and splash forms for a module being updated, be sure to note the global IDs assigned to each.
  2333.  
  2334. Step 4: Create an Invalidation Stream
  2335.  
  2336. In order to trigger a code update, you must invalidate an atom in a specific protocol, an entire protocol, or a token. In fact, you can link several of the above to a particular code update so that, when one of them is encountered, a tool update will be initiated. Choosing the right event to invalidate can be an art; to cause an update to happen at a desired time, sometimes it makes sense to invalidate an atom in a protocol managed by a tool other than the one you are updating. For example, replacing the main application or support library would seem like an impossible task because neither handles any atoms or tokens. As it turns out, the best way to update those modules is to invalidate teh atom$async_online_atom, which is the first clear indication teh PC receives that it is online. Using this technique, the code update will be initiated prior to diaplaying the Welcome screen.
  2337.  
  2338. Tool updates are one area where having a central atomizer pays off. When an individual atom or protocol is encountered, the Atomizer places the stream that contains it on hold and notifies Codeman. Codeman determintes what tool ot tools will be needed to validate the atom and indicates downloads of those tools. If no tool downloaded requires an application restart, Codeman orders the Atomizer to resume execution of the stream on hold. In this scenario, the state of the application has been perfectly preserved during the asynchronous tool update, and the user is able to continue right where he left off. Note that, while token can be used to trigger a code update, there is no mechnism to handle putting token on hold.
  2339.  
  2340. Events are marked invalid by a UDO sent to users at sign-on. You must prepare on atom stream to describe the module or modules being replaced and associate it/them with one or more events. For example, the following stream might be used to trigger a Chat tool update when any chat atom is received:
  2341.  
  2342. atom$cm_start_block ; begin the dependency block
  2343. atom$cm_mark_proto_invalid 11
  2344. atom$cm_set_request_record 32-1234 ; designate record of the Request form
  2345. atom$cm_version 03000002x ; specify version of the new tool
  2346. atom$cm_tod_name “upfront_chat_test” ; this is the subject line of the UTF file uploaded to the service
  2347. (this is not the file name)
  2348. atom$cm_disk_space_needed ; this count should indicate the total space needed for both the
  2349. UTF file and any compressed file within (*1.5)
  2350. atom$cm_byte_count ; this is the size of the UTF file and is used to indicate download
  2351. time
  2352. atom$cm_set_splash_record 32-5678 ; Designate record of the splash form
  2353. atom$cm_notify_token Tu ; this is the token used to notify the DRUL that a particular tool
  2354. has been upated
  2355. atom$cm_check_tool 7 ; Create an entry for this tool ID
  2356. atom$am_end_block ; End the dependency block
  2357. atom$uni_end_stream ; End the stream
  2358.  
  2359. You can force an application restart for a smart tool by including an atom$cm_set_to_restart atom before the atom$cm_check_tool atom. This atom was created as an emergency fall-back in case a tool was improperly configured as a smart tool and would cause a crash of replaced without a restart.
  2360.  
  2361. Once you’ve written your invalidation stream, create a UDO out of it by using the following command:
  2362. add_gen4_udo TSTSYS>pcdb.file steam_filename ‘Descriptive comment’ TSTSYS
  2363. TSTSYS refers to the appropriate test system path or abbreviation.
  2364.  
  2365. Next, use the edit_pcdb command to optionally limit the range of WAOL versions that should receive this update. It’is a good idea to test code updates using a version number that no one else is using in order to avoid inconveniencing other people on the test system.
  2366.  
  2367. Finally, make the UDO active by issuing this command:
  2368. updater pcdb_update TSTSYS
  2369.  
  2370. The next time you sign on, you should receive your TOD request form when you cause one of your invalidated events to occur.
  2371.  
  2372. Explicit TOD
  2373.  
  2374. One of the more flexible features of new TOD process is Explicit TOD. This is a TOD that is triggered using a button on a form as opposed to an invalidation created by a UDO. The steps for creating an Explicit TOD are indentical as listed above, until step 4 is reached. The first thing must be done is to change the stream in Step 4 to support the Explicit TOD method.
  2375.  
  2376. ....
  2377. atom$cm_notify_token Tu
  2378. atom$cm_trigger_tod
  2379. atom$cm_check_tool 7
  2380. ....
  2381.  
  2382. Once the stream has been modified, you are now able to attach the stream to a button on a form. Once the form is on the proper test system or production, the button will cause teh TOD to begin. No additional setup is required when using Explicit TOD. There is no need to create or implement a UDO using ADD_GEN4_UDO and UPDATER.
  2383.  
  2384. Phoenix TOD
  2385.  
  2386. The Phoenix TOD process is provided to enable the replacement of Load Time components, such as WAOL.EXE and SUPERSUB.DLL. These components can only be replaced during a full restart of the Windows Client Application. In order for this to be accomplished, you must provide a Phoenix script file. This file is a very simple script file which should only contain the commands necessary to delete teh old file and copy the new one into place. No restoration information is necessary, due to the fact that Phoenix now automatically backs up any deleted or moved files. The following is a script that would be needed to put a new version of WAOL.EXE into place:
  2387.  
  2388. d waol.exe
  2389. c tod\waol.exe waol.exe
  2390.  
  2391. The above lines are all that are necessary in the PHOENIX.PHX script file. If you wish to have files deleted and cleaned-up at the end of the TOD process you must include a TOD script such as WAOL.TOD that would contain the following:
  2392.  
  2393. [install]
  2394. ;
  2395. [restore]
  2396. ;
  2397. [cleanup]
  2398. delete tod\waol.exe
  2399. delete tod\waol.tod
  2400. delete tod\phoenix.phx
  2401. delete tod\waol.utf
  2402. delete tod\aoltag.tag
  2403. ;end of script file
  2404.  
  2405. How host servers know tool versions
  2406.  
  2407. All tool versions which ahve a host component (i.e., chat, mail, etc) are sent to the host subsequent to INIT packet. The packets containing the tool versions are received by DRUL. The client must send this information in an agreed-upon format.
  2408.  
  2409. Later, when a host server receives a request from the client and the request requires utilization of some client tool functionality, the server requests that user’s tool version from DRUL.
  2410.  
  2411. The following diagram and subsequent text describes this scenario:
  2412.  
  2413.  
  2414.  
  2415.  
  2416. 1
  2417.  
  2418. 3 4
  2419. 2
  2420.  
  2421.  
  2422. 1. The client sends tool version information up to DRUL upon sign on.
  2423. 2. The user performs an action that requires use of a host server and that server has a client component. For example, the ‘bb’ token is sent to the Roomer process and Roomer interacts with chat tool.
  2424. 3. At this point, Roomer does not know what tool version is being used so Roomer sends a message to DRUL requesting the tool version of chat for that user.
  2425. 4. DRUL sends Roomer the chat tool version. Now Roomer knows how to properly interact with the chat tool.
  2426.  
  2427. How host servers know that a new tool has been downloaded
  2428.  
  2429. When a new tool version is downloaded to the client and the session remains active (i.e., no forced sign off occurs), the client sends this information back up to DRUL. DRUL then sends this information to any server who has registered to receive it. Once the host server receives the new tool version from DRUL, the server lets the client know.
  2430. Note that a tool download may force a sign off and restart of client. In this case, the host would get the tool information via the scenario described previously.
  2431.  
  2432.  
  2433. Appendix: Johnson Grace - ART, ART Plus & ART DOC
  2434.  
  2435. Johnson and Grace compression including Darkstar, slide show,and Art Plus.
  2436.  
  2437. "ART" is a new core compression technology developed by Johnson-Grace. ART technology can be implemented in a range of applications which employ image, video, and sound data. Online ART, developed to work within the transmission constraints of ordinary telephone lines, is an implementation of ART compression technology custom-designed for online services.
  2438.  
  2439. With industry leading compression technology, display speed, color management, and image presentation features, Online ART enables online services and content publishers to integrate high-quality images into electronic shopping services, sports, news, games, and other content in a dramatically more compelling way than is possible with alternative systems. ART Press, a Windows implementation of the Online ART technology developed for both professional and non-professional content publishers, is an essential authoring tool for creating, viewing, and managing ART images. A Macintosh version of ART Press will be available later this year.
  2440.  
  2441. A compressed ART image requires on average only half the file size needed by JPEG to produce the same quality decompressed image. Smaller compressed image files translate directly into time savings for subscribers since less data needs to be downloaded to view an image. Shorter image transmission times, in concert with ART's other features, nearly eliminate the perception -- for users with 14.4 and 9.6 kbps modems -- of having to wait for images to transmit and decode. For 2,400 bps modem subscribers, ART reduces wait times below the threshold needed for image-intensive applications such as online shopping and news.
  2442.  
  2443. In addition to producing 50% smaller files than JPEG, ART decodes images five times faster. With fewer than one-fourth the number of decoding operations required by JPEG, the Windows version of the ART Viewer decompresses a 1 MB image in 1.5 seconds on a 486 PC. (JG's DOS-based ART Decoder can decompress a 1 MB image in one-half second.) The ART Encoder is more than twice as fast as a JPEG encoder -- and more than 100 times faster than fractal-based compression -- compressing a 1 MB image in 1.5 seconds on a high-end PC.
  2444.  
  2445. To minimize image downloading delays, ART has been designed to compress and store images in layers. As an ART image is transmitted, the first layer displays almost immediately as a full-size preview (Splash) image. The preview then becomes sharper as each additional layer is received and decompressed. The sharpness of the displayed image is improved seamlessly without breaking the visual continuity of the image or transmitting any redundant information.
  2446.  
  2447. Comprising less than one-third of a compressed file, the Splash version of the original begins appearing on the user's screen in roughly one second, giving the user a swift response to commands which invoke an image download. Within 2-3 seconds, the Splash is fully downloaded and displayed, providing the user with enough of a preview to understand the image's general content. Depending on the compressed file size, the second layer produces a good quality or Standard image by adding detail within another 3-5 seconds. The third layer generates a Sharp image, sharpening the image within an additional 2-3 seconds.
  2448.  
  2449. A Splash image is stored at the beginning of an ART file with subsequent layers following one after another. The ART format's layering takes advantage of the human eye's ability to make sense out of a Splash version of the original image. The image comes into clearer focus as image detail is supplied in second and third layers, although the number of layers can be user-determined in the encoding process. Since image content can be determined from the Splash image within 2-3 seconds, the client application can provide users the choice of viewing the image fully or instantly canceling the download.
  2450.  
  2451.  
  2452. ART images are also streamable -- the Online ART image viewer decompresses an image data stream as data is received, rather than waiting for a file to completely download before beginning the decoding process. This allows online members to view the panelling-in of each image layer. Panels are decoded from independent blocks of data; typically, the first panel of an ART file can be displayed after only 1KB of data is received. A Splash image will thus begin to appear on the screen within approximately 1 second of a transmission being initiated.
  2453.  
  2454. The ART viewer decodes directly to 24-, 16-, 8-, or 4-bit color, offering the online user a choice of several color palettes and dithering methods. Because ART's proprietary colormapping and dithering algorithms are integrated with the decoding process, they cause almost no additional delay in the display of an image.
  2455.  
  2456. The ART encoder provides an option for embedding a compressed optimal color palette into ART files. The ART encoder can compute the optimal palette for the decoded image and embed it in the compressed image at the cost of less than 500 bytes for a 256-color palette.
  2457.  
  2458. The ART viewer automatically recognizes and uses the embedded optimal palette in mapping the decoded image, giving best fit colors on-the-fly. Since all displayed images must use the foreground image's optimal palette, the optimal palette option is best employed when only one image will be displayed at a time or when the color quality of the active or foreground image is more important than the color quality of background images.
  2459.  
  2460. When no palette option is selected, the ART encoder will default to the standard palette option in which all images share a fixed palette. With a standard palette, no repaletting is required as new images are displayed or as the focus shifts from one image to another. A standard palette is desirable in applications in which many images will be displayed simultaneously.
  2461.  
  2462. A key technical innovation of the ART technology is its content-sensitive fuzzy logic engine which enables the ART algorithm to classify the elements of a picture and determine the best image compression techniques to apply to each image element. This allows the ART algorithm to achieve the best possible compression of any type of image, whether it is graphical, photographic, typographic, or a combination of the three.
  2463.  
  2464. JG's ongoing R&D employs neural network and genetic algorithm technology for refining the fuzzy logic engine's rules for identifying additional image elements -- for example, the high color saturation and line art found in cartoon drawings -- and for specifying content-sensitive encoder settings which optimize the compression of these elements. JG is constantly improving the ART Encoder's ability to optimally and automatically compress any kind of image content.
  2465.  
  2466. Johnson-Grace's "ART" still image compression is a proprietary technology (patents pending). After discussions with many companies in need of "better-than-JPEG" compression, Johnson-Grace developed ART believing that only a new proprietary technology could overcome the problems endemic to JPEG, such as:
  2467.  
  2468. • Reliance on the compute-intensive DCT algorithm which causes inordinate encoding and decoding delays.
  2469. • Lack of content sensitivity to adjust and adapt to different image types (e.g., high detail, graphical, photographic), so that any image can be compressed within a consistent quality range.
  2470. • Ambiguous ownership-by-committee status which slows innovation and decisionmaking, leading to a marginally adequate standard in the long run.
  2471. • Failure to support the design flexibility and customization needed by specific industries (e.g., online services) to tailor compression technology to application requirements.
  2472. • Inability to gain the support of most OEMs, online services, content publishers, game and multimedia developers, and end users.
  2473.  
  2474. ART's versatility, speed, and compression performance give it a decided advantage over JPEG. One of the most innovative features of ART compression is the Viewer's ability to handle Encoder upgrades without invalidating the ART format. This is important since ART's encoding structure is designed to be continually improved as new coding techniques are discovered.
  2475.  
  2476. Johnson-Grace projects that ART will become the de facto online industry standard image compression and viewing system by the Summer of 1995.
  2477.  
  2478. Speed to screen is a major objective of the ART technology. The following ART features dramatically reduce the time required to view images online.
  2479.  
  2480. a) HIGH COMPRESSION RATIOS. ART compressed images can be downloaded in half the time of comparable JPEG images as ART's average compression ratios are twice as high as JPEG's.
  2481.  
  2482. b) LAYERED IMAGE FORMAT. The Splash layer of an ART file can be displayed in only 2-3 seconds (with a 9600 bps modem) with sharpening layers taking just 3-5 seconds each to download and decode.
  2483.  
  2484. c) BUILT-IN THUMBNAILS. An ART Thumbnail can be exploded into a full-size, high-quality image in just seconds by adding high detail layers since the Thumbnail comprises core image information.
  2485.  
  2486. d) STREAMABLE DECODING. Images can be displayed almost instantaneously since compressed image data is decoded in 16-row pixel strips as it is received online.
  2487.  
  2488. e) ON-THE-FLY COLOR MANAGEMENT. Color reduction and dithering can be performed with only a small increase in processing time as these algorithms are tightly interwoven into the decoder to economize on processing steps.
  2489.  
  2490. f) ULTRA-FAST DECODING. The ART Viewer can decode compressed images five times faster than JPEG because ART requires just one-quarter the number of decoding operations as JPEG .
  2491.  
  2492. The addition of Darkstar (one motionless picture with a streamed audio
  2493. file) is relatively simple, requiring the addition of a 3 dll download. The
  2494. user downloads these to their Windows directory (not available yet on mac),
  2495. restarts, and is good to go.
  2496.  
  2497. Johnson Grace ART Format
  2498.  
  2499. SLIDE SHOW and DARKSTAR
  2500. The Slide Show program has a number allows users to sit through this (slide show) while online. A lot of members may want to create their own shows and mail the file to family and friends. It could also be great for doing voice mail however members will have to buy the tools to create them.
  2501.  
  2502. Demo Example:
  2503.  
  2504. Martin Luther King demo -- was 16 minutes long including multiple images and full sound. Compressed this file came in at about 800 k. Very impressive at that size. Some of the features this displayed were. (most of these were witnessed while some were mentioned by Johnson and Grace)
  2505. a) sound, multiple images, text were displayed
  2506. b) photos already used earlier in the demo were cached in memory
  2507. so they didn’t require the standard time to come down.
  2508. c) photos were layered and placed around the screen in different
  2509. places.
  2510. d) audio streamed seamlessly and the voice compression was
  2511. better than RealAudio.
  2512. e) simulated at 14.4 speeds and was relatively quick streaming.
  2513. f) track was synchronized to audio and the timing was in direct
  2514. relation to download speed...NOT to CPU clock speed.
  2515. g) photos can be overlapped (floating graphical images)
  2516. h) text is a separate image and has the equivalent of a transparent
  2517. background
  2518. i) only need to add 3 dll's to system in order to run. (darkstar)
  2519. Slide Show requires player.
  2520. j) almost ready for mac...
  2521. k) will run fine on a 4 meg machine
  2522. l) hotspots/hyperlinks possible
  2523. m) DARKSTAR - rainman looking file with the addition of a
  2524. "speaker" to indicate sound on form.
  2525. n) can take speaker and drag and drop it to another picture to add
  2526. sound (like a favorite places kind of drop)
  2527. o) Darkstar does not need a new player to play sound. Slide Show
  2528. DOES need a new player.
  2529. p) automatically recognizes palette on WAOL/MAC
  2530. q) sound compression 8 bit/22 hz is 40:1
  2531.  
  2532. ART DOC....
  2533.  
  2534. Artdoc has many features that resemble the MSN front end with photos coming down in pieces. Some of the features:
  2535.  
  2536. a) rich text editor - FULLY cross platform with the ability to manipulate
  2537. fonts, size, color, alignment, spacing, columns, style.
  2538. b) choreography - p[ick and choose what order items come down in...such as
  2539. graphic #1 first, #2 second, sound third, graphic #3 fourth, and so on...
  2540. c) resizing window reflows the text downward.
  2541. d) currently working on supporting bitmaps/color/tiled backgrounds
  2542. e) hyperlinks to text and graphics
  2543. f) can lock items down so that it is READ ONLY and can't be changed
  2544. g) player has the ability to read or edit items.
  2545. i) zoom mode
  2546. j) NO scrolling features within scrollable document as of yet. ie..placing a
  2547. scrollable list box within the ArtPlus doc.
  2548. k) supports borders, separators, frames, captions, box style, changeable
  2549. widths, bevels, margins, and colors
  2550. l) **coming soon -- embedded fonts and temporary fonts.
  2551. m) once a Darkstar image/sound is dropped in ArtPlus, the sound file becomes
  2552. separate from the image and becomes its own entity with ArtPlus
  2553. n) playing sound during download or waiting until whole doc downloads.
  2554.  
  2555. Appendix: Form & Content Tools
  2556.  
  2557. There are many Form & Content Tools. These include:
  2558. Form_edit
  2559.  
  2560. Most forms are generated by AOL Producers. They typically use a tool known as Form Edit (form_edit). This tool is a text based tool located on the Stratus system. This tool is similar to the Resource Workshop found in Borland’s C++ package. When a Producer uses form edit the create a Window with buttons, listboxes, check boxes, text , and images. Form Edit then compiles the data they enter into an atom stream. They then install the form onto the host production computers for use on the service.
  2561.  
  2562. Basic Steps to Use Form Edit (Highly simplified, not very thorough):
  2563.  
  2564. 1. Get a Stratus Account
  2565. 2. Install Procomm for Windows on a Windows machine.
  2566. 3. Start Procomm with the necessary Stratus Script (instaled by OpsHelp)
  2567. 4. Log onto Stratus using your account number and password.
  2568. i.e. Login Kloewenthal
  2569.  
  2570. 5. Set terminal Emulation Mode
  2571. set_terminal_parameters - terminal_type v103_ascii
  2572. 6. Start Form Edit
  2573. form_edit -qlink_dir <your test system>
  2574. form_edit -qlink_dir arrmgs
  2575.  
  2576. 7. You will need the following keys:
  2577.  
  2578. NUMLOCK - Toggles main menu on form_edit
  2579. ‘/’ on the keypad is used for Cancel operations
  2580. ‘*’ on the keypad is used for Refresh operations
  2581.  
  2582. 8. Start with basic Window (defaults)
  2583. 9. To add objects (items)
  2584. NUMLOCK/Add to Tree
  2585. Then choose desired item, such as a button
  2586.  
  2587. 10. To edit the attributes associated with the item press the F5 (Edit Tree) key to choose the object.
  2588. Move the the desired object with the arrow keys.
  2589.  
  2590. 11. To edit the desired object press F5 (Edit Object).
  2591. Tab over to the attribute and use one of the following:
  2592. -Hit the Space Bar to toggle option On/Off (+= Off, A small triangle = On)
  2593. - Arrow keys to change
  2594. 12. Use F7 (Adv. Attrb.) to edit Advance Attributes
  2595. 13. Go back to Edit Tree menu and use F8 (Adv. Edit) Advanced Edit to delete items from the tree.
  2596. 14. To Save form goto the main menu, then Manage/Save Form.
  2597. 15. To Install Form goto main menu, then Manage/Install
  2598. 16. To preview form:
  2599. -Start WAOL
  2600. -Hit F2 (Send Form)
  2601. - Choose System: qr
  2602. - Enter your username
  2603. - Choose Client: WAOL 2
  2604. - Hit Enter and you should see your form pop up on your WAOL client Window.
  2605.  
  2606. 17. You can also add pictures to various controls within the window using form_edit. You will need to either know the picture name or the global ID. You can find the global id for art in the WAOL client by using the WAOL Snoop function in the Atomic Debugger. Once you have the global ID you can hit the F12 key in form edit and enter the picture name or global ID.
  2607.  
  2608. 18a. To view the atom stream in form edit:
  2609. -F3 Show FDOs
  2610. -F4 WAOL 2
  2611. 18b. To close view of atom stream:
  2612. - F6 Finish
  2613. - ‘/’ to cancel
  2614. Lib_Edit
  2615.  
  2616. The earliest and most primative forms can be created using the Lib Edit (lib_edit) tool. It is considered obsolete and is only used in unusual cases. It is one of the oldest existing tools.
  2617.  
  2618. CopyUser
  2619.  
  2620. CopyUser is a Stratus tool that will copy a users account information from one host system to another. This includes billing information, password, & other host stored preferences. This is typically used to transfer account info. from one test system to another.
  2621.  
  2622. At the Stratus prompt:
  2623.  
  2624. copy_user
  2625. user: kloewenth
  2626. -to: arclient
  2627.  
  2628. You can also try using the Ctrl-F9 key to get a form to fill out.
  2629. Configure
  2630.  
  2631. Configure is a Stratus tool that is used to determine what processes are on a test system.
  2632. Example: Configure arclient
  2633. Bump User
  2634.  
  2635. Sometimes users are forced off of AOL, but the host still believes that you are logged in. You must then tell the host to log you off. To do this you must either call AOLs help line or as an AOL employee use the Stratus process called: bump_user. To do this, from the Stratus ready prompt, type bump_user and press enter. You will then be prompted for a screen name. Type that in and press Enter again.
  2636. WATCH
  2637.  
  2638. At a Stratus prompt type “Watch” to view the number of users online on various clients.
  2639. Rainman.
  2640.  
  2641. Rainman (Remote Automated Information Manager) is a suite of online tools and host system processes that together let information providers create, update and delete information stored on the online service. Information providers modify their Rainman areas online using Rainman scripts, which are simple text files that contain instructions. When an IP sends a script to the Rainman system, Rainman reads the script and automatically performs the actions the script tells it to do, without the assistance of human operators.
  2642.  
  2643. Rainman and the Rainman command language are designed to give Ips the maximum control possible over there areas online. Once online service staff set up an information provider’s area, the information provider can change it at will with minimal assistance from the online service.
  2644.  
  2645. You create a script, or a text file of instructions, on your local computer system. Once you create the script, you send it to Rainman, which reads the script and performs the commands as instructed. The following is a brief introduction to Rainman. For more detailed information, consult Bringing Information Online Using Rainman.
  2646.  
  2647. CONCEPTS AND TERMS.
  2648.  
  2649. Groups.
  2650.  
  2651. A group is an area where Rainman stores the information that you send. There may be only one information provider per group, but there may be more than one group per information provider. Who can use Rainman and whether objects are date/time/ID stamped are configured in the group. Groups are set up and maintained by America Online staff. The content of the group, however, is controlled by the information provider.
  2652.  
  2653. Objects.
  2654.  
  2655. An object is any item that you can include in a Rainman group. Each object must be given an ID, a three to eight character designation which must be unique within the group. This ID may contain letters, numbers, dollar signs ($), and underscores (_). The types of objects are:
  2656. • Articles. A block of text for members to read online.
  2657. • Collections. An online folder that contains other objects.
  2658. • Tokens and Arguments. A command that makes Rainman Plus perform an action.
  2659. • Conference Rooms. Areas where members can conduct real-time conversations.
  2660. • Auditoriums. An area where up to 500 members can come to hear a speaker.
  2661. • Message Boards. An area where members write notes that other members can read and answer.
  2662. • Software Libraries. Areas where members can upload and download files.
  2663. • Search Databases. UNIX-based online searchable databases.
  2664. • Form. A form in American Online's retriever database.
  2665. • Old Form. An America Online library record.
  2666. • Old Search Database. Stratus-based online search database.
  2667.  
  2668. Links and positioning.
  2669.  
  2670. A link establishes a connection between an object and an existing collection. You may either define an ID for a link (a number from 1 to 256) or Rainman will automtically assign one for you. You may also specify the time at which to insert or remove the link. An object may have more than one link. However, there must be at least one link or else members will be unable to see it.
  2671.  
  2672. In addition to establishing a link to a collection, you may also define the position of that object within the collection. This position can be either absolute, defining the object's exact location within the collection, or it can be relative to another object within the collection.
  2673.  
  2674. Delimiter.
  2675.  
  2676. A typical Rainman command looks like this: \CREATE. The backslash (\) is a delimiter that tells Rainman that the next word is a command. You may change the delimiter if the use of a backslash conflicts with the nature of the information you are uploading. You can change the delimiter to any combination of up to three characters. The change of your delimiter will be in effect for that script only.
  2677.  
  2678. WRITING A SCRIPT.
  2679.  
  2680. The following are sample scripts which demonstrate basic processes that can be performed with Rainman. Items contained within angle brackets <> indicate information that you need to provide.
  2681.  
  2682. Creating a Collection.
  2683.  
  2684. \CREATE COLLECTION <id>
  2685. \HEADLINE <text>
  2686. \INSERT LINK <id>
  2687. \POSITION IN COLLECTION <id>
  2688.  
  2689. This script creates a collection, assigns it a headline, and places it within an existing collection. The ID in the first command must be unique within the group. The text in the \HEADLINE command will appear in the title bar of the collection's window. Remember, you do not have to assign an ID for a link. If you do not, Rainman will. The collection in which you place this collection must already exist.
  2690.  
  2691. Creating an Article.
  2692.  
  2693. \CREATE ARTICLE <id>
  2694. \HEADLINE <text>
  2695. \FIELD <#> TEXT
  2696. <text>
  2697. \INSERT LINK <id>
  2698. \POSITION IN COLLECTION <id>
  2699.  
  2700. This script creates an article, assigns it a headline and text, and places it within an existing collection. The ID in the first command must be unique within the group. The text in the \HEADLINE command will appear in the title bar of the article's window. The number <#> in the \FIELD command indicates to which field the following text is displayed. TEXT is a parameter of the \FIELD command. Also, remember to hit the return key after the TEXT parameter and before the text. The collection in which you place this collection must already exist.
  2701.  
  2702. Creating a Graphic Article.
  2703.  
  2704. \CREATE ARTICLE <id>
  2705. \HEADLINE <text>
  2706. \FORM 113
  2707. \FIELD 3 TEXT
  2708. <text>
  2709. \FIELD 1 TEXT
  2710. <text>
  2711. \FIELD 11 TEXT
  2712. <text>
  2713. \BINARY 5 <full path name of graphic>
  2714.  
  2715. This script goes a step further than the previous one. We defined which form we wanted to use with the \FORM command. You can find the form definitions in the "Forms Catalog." The various \FIELD # TEXT commands specify which text goes to which field. The \BINARY command is actually a flag for the RM.EXE tool which will need to be run on this script. Consult "How To Create a Graphics Script with RM.EXE" for more information on this process. Scripts for graphic articles will need to be submitted via e-mail.
  2716.  
  2717. SUBMITTING A SCRIPT.
  2718.  
  2719. Interactive Rainman.
  2720.  
  2721. In order to use Interactive Rainman, you must first sign on to America Online. Go to key word RM BETA and double click on your collection in the list box. Click on the Interactive Rainman icon in the upper right corner of this window. Type your script into the Rainman Command Interface field and then click execute. Once Rainman has processed your script you will receive feedback that details what was created and any errors or warnings that were generated.
  2722.  
  2723. E-Mail
  2724.  
  2725. You do not have to go to the Rainman beta test area in order to submit a script. You may do it via e-mail. In order to do this, compose a new mail message and address it to RainmanSys. You may either type the script in the body or attach a file containing the script to the message. Send the message. Rainman processes the script upon receipt and replies in a mail message that details what was created and any errors or warnings that were generated.
  2726.  
  2727. Creating a RAINMAN form set (collection):
  2728.  
  2729. 1.First you need to create a top most form, goto keyword RAINMAN then choose FormsCatalog,
  2730. 2. Pick a form with a list box from the forms catalog (i.e. 20001, 20002, 20003, etc.)
  2731. 3. Goto keyword 40-411
  2732. 4. Enter a Rainman script
  2733.  
  2734. Example Script:
  2735.  
  2736. \group 20.in_house
  2737. \create page kenfirst
  2738. \headline This is a test.
  2739. \form 20003
  2740. \field 1
  2741. Welcome to the my first form. This is a test.
  2742.  
  2743. 5. Now Press EXECUTE
  2744. 6. Record the Internal ID number returned by the execution of the script (i.e. 0-1-58933)
  2745. 7. You can check this number out using WAOL keyword: EOI
  2746. 8. Goto a Stratus terminal and encode this number, from the ready prompt:
  2747.  
  2748. encode 1-58933
  2749. Notice: Leave the "0-" off of the Internal ID
  2750. Also see: decode
  2751.  
  2752. 9. Record the results of the encode operation. Be sure to record all the numbers with the word "byte" infront of them.
  2753.  
  2754. Data: @^Xu
  2755.  
  2756. byte 64
  2757. byte 94
  2758. byte 88
  2759. byte 117
  2760.  
  2761. 10. Goto Stratus prompt and type in lib_edit and then hit enter twice.
  2762. 11. When the lib_edit screen comes in fill in: background and then hit enter.
  2763. 12. In the lib_edit screen fill in the Queue with "background" without the quotes.
  2764. 13. In the data field enter: t1(byte 64)(byte 94)(byte 88)(byte 117)
  2765. be sure to enter no space between the "t1" ans the '('.
  2766. 14. Goto Update Abbreviation and change it to 'Y'
  2767. 15. Record the number that returns, in this case 17-20999
  2768. (This is a: lib edit background directory number)
  2769. 16. Test the form out using WAOL keyword: 17-20999
  2770. 17. You can add additional forms to the first forms list box using the Visual Publisher (Visual Rainman).
  2771. You can upload the Visual Rainman using WAOL keyword:
  2772. RAINMAN
  2773. SW Utility
  2774. Grinder & Visual Publisher
  2775. 18. Goto the NewsRoom Catalog
  2776. -Double click on desired form.
  2777. - Open up an Image with WAOL
  2778. -Press the CTRL key while dragging the mouse cursor ontop of form picture field. Drop the image on
  2779. the picture field. Then add any text,.
  2780. 19. Goto Visual Publisher/Send Article to Rainman Sys...
  2781. 20. Enter your group: 20.in_house
  2782. 21. Make up an ID: Ken3_ID
  2783. 22. Add a Headline
  2784. 23. Add your Collection name (top most form created with the Rainman Script/Encode/lib_edit (i.e. kenfirst)
  2785. 24. Go back to your keyword, in this case: 17-20999 and you should see your top most form. In its list box you should find the item representing the form created with Visual Publisher.
  2786. 25. You can now go back to Visual Publisher and add additional forms to the top most form list box.
  2787.  
  2788.  
  2789. Appendix: Information
  2790. Utilities
  2791.  
  2792. There are a large number of small utility programs that are useful. These programs should be loaded on your C drive in a directory called BIN. These small utilities are usually located on the server’s X drive in a file called: BIN.ZIP. You may have to do a search to find it. It includes utilites such as DO.EXE and SHOWLOCK.EXE. You will need DO.EXE to download all the source code files to your local harddrive. DO cannot handle complex commnad line fucntions unless they are encapsulated in a BAT file.
  2793.  
  2794. You can find a large number of misc. WAOL utility tools in the M:\Projects\utils\BIN directory on the WAOL server. These tools include:
  2795.  
  2796. GID.EXE : Displays GID conversions (i.e. GID 32-199)
  2797. MANAGEDB.EXE : Displays WAOL 2,5 Main.idx records
  2798. (i.e. MANAGEDB -I 32-199 Main.idx)
  2799. (i.e. MANAGEDB -I * main.idx)
  2800. At DOS prompt Type MANAGEDB - ? for help
  2801.  
  2802. MANAGEBT.EXE : Displays WAOL 3.0 Main.idx records (i.e. MANAGEBT -I 32-199 Main.idx)
  2803.  
  2804. WART.EXE : Converts BMP files to ICH files. (ICH Image files for DOD Art)
  2805. Example: WART IMG1.ICH -s IMG1.BMP
  2806.  
  2807. DIAG.EXE : Displays WAOL DIAG.DAT diagnostic files (they are XOR with 55 hex so
  2808. users cannot read them.)
  2809.  
  2810. You can generate a Diag.Dat file by simultaneously pressing: Ctrl-Shift-D. This will create the latest Diag.Dat file.
  2811.  
  2812. There is also a main.idx Windows utility tool called DBView which is located on M:\projects\utils. This tool helps to view all records, set attributes, import and export records, compact the database, etc.
  2813.  
  2814. You can merge the ICH file into WAOL.EXE using the Art Administration function on the Atomic Debugger Menu.
  2815.  
  2816. Ctrl-R : Displays internal WAOL version number, used at About Box
  2817. Ctrl-F9 : Used to terminate requests to host, ideal for terminating wait for host delays. only available with the Master tool
  2818. Ctrl-K : Keyword, brings up the Keyword Form
  2819. Esc : Stops incoming text
  2820. Updating Forms
  2821.  
  2822. Forms and art that appear on the client can come from two different sources: the client's local database, main.idx, or the host. When a form, whether new or not, arrives from the host the atom stream for the form is not saved on the client disk unless the form has a special force DOD atom in it causing the form to be DOD to the local client database. (Once the form is on the client disk, it cannot be updated without a special UDO operation. UDO operations are costly and are not run often.) However, the DOD art work for forms is automatically saved to the local client disk database. If a form is on the client disk database then that form is invoked and used rather than using a host based form. Many forms are prepackaged on the client disk during disk ship time. These forms make up the forms required to allow the user to sign on (i.e. Sign-On form, the Connection form, toolbar, the exit dialog, etc.). Then there are commonly used forms that come prepackaged to reduce the host load and improve performance of the client. The Welcome screen and the Main Menu (channel screen) are both placed on the client. Since these forms are used by every user (the main menu screen can be turned off by the user but, most elect to keep it on) and if the associated form packets were sent each time a user signed on it would increase the packet traffic from the host considerably.
  2823.  
  2824. Updating forms on the client database GM disk, main.idx.
  2825.  
  2826. 1. Create a form using form_edit.
  2827. 2. Submit the form to a test system.
  2828. 3. Start a debug version of WAOL on the test system. (A debug version of WAOL is a version of WAOL that has the MASTER.AOL tool in its \tool directory. This tool is only available to developers.)
  2829. 4. Goto the '*' menu item on the far left hand corner of the main menu on WAOL.
  2830. 5. Choose "Update Database Record." This will bring up a dialog box with a field labeled: "Global ID."
  2831. 6. In the Global ID field enter the global ID of the host based form that you inserted into the main.idx database of the client that you are currently running (i.e. 32-4645).
  2832.  
  2833. At this point the atom stream for the form you choose is in the main.idx database. You should also see an increase in size of the main.idx as a result of adding the form. For example: Suppose one wanted to put the RoadTrip form and art in the main.idx. You might start by bringing up the form on your client thus, causing the DOD mechanism to deposit all the art into the main IDX while simultaneously displaying the art. Then you would need the form GID. You could get this using the MASTER tools' "snoop" option that is located in the '*' menu. In the case of RoadTrip the GID is: 40-19864. Once you have the GID you can go to Update Database Record and type it in. If successful the MASTER tool will respond accordingly. So now the database contains the atom stream for the form and the DOD art for the form. The art for this form will increase the main.idx database size by 88383 bytes (on 2/11/96) and the form will increase the database size by 602 bytes. Of course the art is almost always larger in size than the form because the art typically represents bitmaps while the form is a series of atoms.
  2834.  
  2835. Now you will need to transfer it to the database that gets shipped with the client.
  2836.  
  2837. The main.idx that gets shipped with the client is a virgin database that does not contain any unique specific user names. When you signed on with the client to get the form you had to sign on as someone and this someone gets inserted into the main.idx. We do not want that information going out to users. Likewise a virgin copy of the main.idx contains records directing users to the first time regitration areas if they are a new user. Once a main.idx is used on a client the registration related records are no longer accessable by the user. Therefore, all records (forms and art) must be acquired using one main.idx database and then transferred to the virgin, shipping main.idx database. Developers use a command line driven program called MANAGEBT.EXE to facilitate this transfer.
  2838.  
  2839. 1. To transfer the record from the user database to a temporary file using managebt.exe
  2840.  
  2841. managebt -g 32-XXXX c:\aol30\idb\main.idx foo.bin
  2842. Where 32-XXXX is the record/form number, ‘-g’ stands for GET.
  2843.  
  2844. 2. To transfer the record from the temporary file to the virgin GM main.idx database using managebt.exe
  2845.  
  2846. managebt -p 32-XXXX j:\build30\16\Source\idb\main.idx foo.bin
  2847. Where 32-XXXX is the record/form number, ‘-p’ stands for PUT.
  2848.  
  2849. At this point the record is transferred to the virgin GM database.
  2850.  
  2851. Updating the main.idx database on all client’s in the field.
  2852.  
  2853. 1. Create a form/atom stream using form_edit.
  2854. 2. Submit the form/atom stream to production.
  2855. 3. Now write a UDO atom stream
  2856.  
  2857. If the form exists in user's databases and we need to update it, first we must delete it. The UDO should contain the following atom:
  2858.  
  2859. atom$idb_delete_obj <GID> where GID is the form number.
  2860.  
  2861. example:
  2862.  
  2863. atom$idb_delete_obj <32-345>
  2864.  
  2865. To add the form record you must first invoke the form, then set context and then save it to the database therefore, the UDO should contain the following atoms:
  2866.  
  2867. atom$idb_start_obj <A>
  2868. atom$idb_append_data <data>
  2869. atom$idb_append_data <data>
  2870. atom$idb_append_data <data>
  2871. atom$idb_append_data <data>
  2872. atom$idb_append_data <data>
  2873. atom$idb_append_data <data>
  2874. …
  2875. atom$idb_append_data <data>
  2876. atom$idb_end_context ;Saves form to local main.idx database
  2877.  
  2878. In the case of the above UDO all the atom$idb_append_data atoms are generated by the ADDGEN4UDO process by specifying
  2879.  
  2880. ccc$retriever <Platform> <Language> <Form GID> <SID>
  2881.  
  2882. Platform = 5 for Windows
  2883. Language = 0 or 255?
  2884. Form GID is the form number in retriever
  2885. SID usually 0
  2886.  
  2887. in place of the atom$idb_append_data atoms. ADDGEN4UDO creates the append_data on the fly at the time a developer submits the stream to the host. Therefore, the stream that a developer submits to the host looks like:
  2888.  
  2889. atom$idb_start_obj <record_type>
  2890. ccc$retriever <Platform> <Language> <Form GID> <SID>
  2891. atom$idb_end_context ;Saves form to local main.idx database
  2892.  
  2893. Note: The record_type for atom$idb_start_obj can be one of the following: A, B, T, P.
  2894.  
  2895. A= Atom
  2896. B=Binary
  2897. T=Text
  2898. P=Picture
  2899.  
  2900.  
  2901. Extracting Art from the Main.idx database.
  2902.  
  2903. You can extract art from the main.idx using managebt.
  2904.  
  2905. 1. Extract the art using the Art ID as described above.
  2906. 2. Check out the art format using the AOL custom utility called WART.EXE.
  2907. WART foo.bin -i
  2908. 3. Convert the art from the ICH format
  2909. WART foo.bin -xc artimage.gif
  2910.  
  2911. WART will convert the ICH format found in foo.bin to a GIF format and store it in artimage.gif.
  2912. Updating the MAIN.IDX for Builds
  2913.  
  2914. To add a new piece of art, form or atom stream to the MAIN.IDX that gets shipped with the floppy disk you need to perform a series of steps (also see the section on FORMS):
  2915.  
  2916. Streams or Forms:
  2917.  
  2918. 1. Create new stream using form_edit.
  2919. 2. Save the form or stream to the host.
  2920. 3. Use WAOL & Master.AOL to get the new stream and save it locally to your main.idx. (This main.idx still contains your username & password so you cannot ship this one.)
  2921. 4. Use Managebt.exe to move a copy of he new stream to the clean main.idx that is in the BUILD30 directory on a build machine. Use the -z option to make it permenent.
  2922. Managebt -z main.idx
  2923.  
  2924. New Art
  2925.  
  2926. New art is typically created by the art department and then submitted for approval before being place on the host. A special department will then push the new art onto the system and in the process give the art a new and unique ART ID. Once the art is on the system the last two steps of the above for steps can be used to get the art and palce it in the clean main.idx.
  2927. Test Systems
  2928.  
  2929. Before new software can be placed on the Production Host system (the system that the average AOL user accesses when they log onto AOL) it must be tested on a test system and thoroughly tested. These test systems are usually an independent piece of hardware that has many of the same processes on it that production systems have. At the present time, there is no centralized test system organization. Each test system usually has a separate owner and has a different purpose, as a result most test systems vary significantly in what they can and cannot do. Most test systems are rather poor at fully emulating the AOL production system. Both new client software (i.e. WAOL 3.0, MAC 3.0) must be tested on a test system before it can be placed on the production system. Any new host process must be tested on a test system before it can be placed on the production system.
  2930.  
  2931. To access a given test system from the WAOL client you must select the appropriate CCL file from the Network listbox in the Network Setup form (Sign On/Setup/Network & Modem Setup/Network Setup/Network). For example: The TCP/IP CCL listing (using ethernet in-house) for arclient is named: TCP/IP Client, with a corrosponding filename of TCPCLNT.CCL.
  2932.  
  2933. Appendix: Glossary
  2934.  
  2935. Alpha Test First test release of a new piece of software. Because such software almost always has serious bugs, alpha tests are conducted by limited groups of experienced users. At AOL, alpha tests are conducted entirely in-house.
  2936.  
  2937. AOLNet: AOL Network purchased from ANS
  2938.  
  2939. ARC AOL Resource Center. An organization within the AOL services company that supports producers both internal to AOL and at information provider sites. Provides training, telephone support, and online area (KW:ARC).
  2940.  
  2941. ART [AOL/Johnson-Grace]. The graphics format created by the Johnson-Grace Company and used by AOL in the client software.
  2942.  
  2943. Atom A single command in the FDO91 language.
  2944.  
  2945. Bandwidth The capacity of a communications link. A high-bandwidth communications link is one that can send a great deal of information quickly. For example, the connection between AOL's office computers and the AOL service is high bandwidth (relative to the needs of application), while a 2400 baud modem and phone line is low bandwidth connection. Application are often described in terms of the bandwidth they require to operate effectively: "Surfing the web requires more bandwidth than you can get out of a 14.4 modem".
  2946.  
  2947. BERP Back End Routing Processor. Part of the host complex. Each BERP manages traffic between Front End Processors (FEPs) for approximately 20,000 simultaneous users and all application servers. BERPs route messages to appropriate servers, track the status of the host complex and the FEPs.
  2948.  
  2949. Beta Test The round of testing a new software release which follows the alpha test. There are generally many rounds of testing included in a beta test. During each round, a new version of the software is distributed to a selected group of users to test. At AOL, client software beta tests start with the internal staff and a few selected users and grow to include thousands of users during the late rounds of testing. The Beta user list is maintained by member services. In agreeing to participate in a beta test, users gain access to leading edge technology with the agreement that they will report any problems they encounter. By the end of a beta test, all major bugs should have been discovered and repaired.
  2950.  
  2951. Bounce (System and/or process) Bringing the AOL Host system down and then back up. The process of taking all or part of the service down and bring it back up. Can be used in reference to particular part of the system: "We're going to bounce message boards." Can also be used in relation to the entire system: "There will be a system bounce Thursday at 4am." Bounces can be used to reset a process that is running improperly or for an emergency installation of a new version of a piece of software. In either of these cases, the bounce takes only a few minutes. System bounces are planned in advance and are used for major software installations, network reconfiguration, and other tasks which may involve keeping the entire service down for several hours.
  2952.  
  2953. Bounce In To install a new version of a piece of software while the rest of the service continues to run.
  2954.  
  2955. Bump To disconnect member’s session for his or her misbehavior.
  2956.  
  2957. Canned Forms Forms for which the design is complete but data is to be filled in by a process at the time the user displays the form itself. For instance, the Top News forms are stored complete in appearance but without a list of articles. At the time a user asks to display the top news, the news program displays the form and then fills in a list of articles.
  2958.  
  2959. CCL Communications control language. CCL is a scripting language that allows AOL developers to "tweak" the connection sequence to communications network without having to rebuild the client code. CCL comes into play when you are making your host connection during logon. CCL tells the logon code the logon sequence. The logon code is the same for all networks; The CCL contains the differences.
  2960.  
  2961. Certificate The number and password used by the member during the registration process in order to register an account. Certificates are used for security, marketing, and control purpose. Key for the certificate file.
  2962.  
  2963. Channel An online area that contains like content (for example, Sports and Today's News). The major Channels are accessible using buttons on the main menu.
  2964.  
  2965. DOD Data On Demand. The process by which artwork not present on the client is downloaded from the host at the time it is needed.
  2966.  
  2967. DRUL Distributed Replicated User List. A UNIX-based application that maintains the list of members currently logged on to AOL. DRUL is used by other applications, such as IM and Locate Member Online, when an application needs to know if a particular user is logged on.
  2968.  
  2969. FDO91 Form Definition Operator - 1991 Version. The version of the FDO language used in the Windows client, the Magic Cap client, and the Macintosh client.
  2970.  
  2971. FEP Front End Processor
  2972.  
  2973. Form A window that is a part of AOL. Data for most forms reside on the host and are sent to the client at the time the user enters a given area. For instance, the appearance of the MTV area is stored on the host and sent to the client at the time the user goes to KW:MTV.
  2974.  
  2975. FormEdit A program used by AOL producers to create forms.
  2976.  
  2977. HTML Hypertext Markup Language
  2978.  
  2979. IM Instant Message. A feature of the AOL software which allows a member to send a message to any other member who is logged on at the same time. The program that performs the IM function is called Whisper, since it is a 'quieter' version of chat.
  2980.  
  2981. Internationalization Modifying a part of AOL's client or host software to enable it to handle non-English text.
  2982.  
  2983. IP Information Provider. An organization which creates content for the America Online service. IPs build and maintain their areas and receive a commission based on the number of hours spent in their area by AOL.
  2984.  
  2985. IP Tunnel Server which routes (IP) packets between AOL users and the internet.
  2986.  
  2987. ISDN Integrated Services Digital Network (128Kbps)
  2988.  
  2989. JG Johnson Grace - Decompression and Compression Tools
  2990.  
  2991. Localization The process of creating forms, text, and design elements appropriate for a particular language, country, or culture. Client software and all necessary forms must be localized before AOL can be launched in a particular country. Localization of a given part of the software cannot be performed until that software has been internationalized.
  2992.  
  2993. Message Board Server and software that allows users to post, read, and respond to online messages.
  2994.  
  2995. MIME Multipurpose Internet Mail Extensions
  2996.  
  2997. MIS The people and supporting software that run and care for
  2998. billing AOL customers
  2999. ordering software and merchandise
  3000. providing customer support systems
  3001. tracking, monitoring and reporting on membership and system usage and activities.
  3002.  
  3003. Online CRIS Online Customer Relations Information System. An online area which allows customer service representatives to access and modify members account information when the users calls in to ask a technical question or request a change in Billing information.
  3004.  
  3005. Ops Short for "Operations". The department in AOL Technologies responsible for configuring hardware and software, monitoring and maintaining the online services.
  3006.  
  3007. P3 The proprietary protocol used to ensure the integrity of data transmitted between the client and the host computers.
  3008.  
  3009. Packets A data communication term that refers to a chunk of data passed through the communications path as a single entity.
  3010.  
  3011. Pageman Page Manager. An online publishing tool that allows for graphics, text, and other multimedia on the same page (form).
  3012.  
  3013. POD Stands for "peas in a pod". An organizational unit in the AOL host system. One pod is designed to support the communications, download, and internet access needs of approximately 20,000 simultaneous users.
  3014.  
  3015. PPP Point-to-Point Protocol
  3016.  
  3017. Producer A member of the AOL Services staff who works with IPs to create content areas for the AOL service.
  3018.  
  3019. PDOD Progressive DOD. An enhancement to the DOD system that allows forms to be displayed to the user while data is being transferred. This allows users to keep working while art is downloaded.
  3020.  
  3021. Rainman Remote Automated Information Manger. A program which allows producers and information providers to create online content by writing simple scripts and sending them to the system by email.
  3022.  
  3023. RMG Remote Managed Gateways (RMG) provide a way to offer real-time services that conform to online service graphical user interface even though the data resides on different computer platforms. This means that members can query a database uploaded to the host online system by an information provider, but cannot communicate directly with that information provider.
  3024.  
  3025. A remote managed gateway consists of a series of customized screens or forms) developed for the gateway information provider. The forms look and act the same as the forms used on the online service. While the actual data resides on the gateway information provider’s computer, the forms reside on the host online system once they are developed.
  3026.  
  3027. When a member accesses an area on the online service, the gateway information provider issues requests for the forms to be displayed, accepts member input as required, and fills the forms with data as required, all through the gateway. The member cannot tell the difference between a service residing on the host computer and one residing on a remote computer accessed through the gateway.
  3028.  
  3029. Server A program running in the host complex that implements some feature or underlying capability of the AOL services. One or more processes that implement one feature of the online service, for example, logging on and Sending Instant Messages.
  3030.  
  3031. SLIP Serical Line Internet Protocol
  3032.  
  3033. SSL Secure Sockets Layer protocol that uses RSA encryption
  3034.  
  3035. Stratus The board of mini-computer on which the entities AOL host system was created. Until 1994, all of AOL run exclusively on Stratus systems. Stratus machines are fault-tolerant. That is, they have redundant hardware designed to stay running 24 hours a day, 365 days a year.
  3036.  
  3037. TIH Terminal Interrupt Handler. The host program which receives information from the client and sends it to the appropriate place in the host system and visa-versa. Each TIH can handle up to 63 simultaneous sessions.
  3038.  
  3039. TOD Tool On Demand. Technology which allows AOL to send the member a new version of a part of the AOL software at the time they enter an area which requires that software.
  3040.  
  3041. UDO Update Disk Operation. At time of sign on, updates the client database to account for changes in forms, artwork, etc.
  3042.  
  3043. Vantive Bug Tracking Database Tool. The database system used by the customer service organization to track member calls as well as all known problems and their symptoms and solutions. As of October 2, 1995, Vantive is used to track bugs in the AOL Client and host software. It contains the QA database of client, host, and forms bugs and enhancements. Bugs are usually entered as discovered by AOL QA personnel. However other employees of AOL can also enter bugs. Bugs are usually reported by Ranking and Severity. Valid Ranking values are: $ , 1, 2, 3, where $ is the highest ranked bug and 3 is the lowest ranked bug. Valid Severity values are: E, 1, 2, 3, where E (Emergency) is the highest severity bug and 3 is the lowest severity. Generally Ranking takes precedence over severity. All bugs are given a Vantive ID for tracking purposes. The Vantive database includes a bug Summary, Steps to Reproduce, and research information field. Vantive also allows the automatic generation of bug reports.
  3044.  
  3045. Newcomer’s Checklist
  3046.  
  3047. Welcome to America Online. As a new developer or tech in the group you will want to spend some time setting up your office environment. The following list, although by no means complete, will help you get started.
  3048.  
  3049. • Go to KW: HR and finish your First 90 days Checklist
  3050. • Map your drives as the following:
  3051. M: \\aold05mf\data
  3052. N: \\aold05mf\Apps
  3053. S: \\aold05mf\data
  3054. • Install the following software on your computer:
  3055. (a) VC++ 5.0 (ask Mark Predergast for CDs)
  3056. (b) SourceSafe 5.0 from network
  3057. (c) DBView form network
  3058. (d) Procomm plus from network
  3059. (e) Vantive from network
  3060. Vantive is a bug tracking and reporting software that we have been using since Oct. 1995. It contains the QA database of client, host and forms bugs and enhancements. Bugs are usually entered as discovered by AOL QA personnel. However other employees of AOL can also enter bugs. Bugs are usually categorized by Ranking and Severity. Valid ranking values are $, 1, 2, 3, where $ is the highest ranked bug. Valid severity values are E, 1, 2, 3, where E (Emergency) is the highest severity bug. Generally ranking takes precedence over severity. All bugs are given a Vantive ID for tracking purpose. The Vantive database includes a bug Summary, Steps to Reproduce, and research information field. Vantive also allows the automatic generation of bug reports.
  3061. (f) Utilities from network
  3062. There are a number of small utility programs that are useful. We suggest you load these programs on you C drive in a directory called BIN. It includes utilities such as GID.exe and Managetit.EXE. You will need GID.exe to convert global IDs between heximal to GID format.
  3063.  
  3064. • Enter your name into the Phone Directory by going to KW: phone
  3065. • Acquire a Stratus account by going to KW: opssec
  3066. • Order basic AOL manuals (FDO91, Building an Online Service, Windows Client Manual) by sending email to DocOrder.
  3067. • Take Producer Training Class by going to KW: ARC
  3068. • If you are not familiar with the AOL service you may wish to spend some time reviewing the entire client. Go through every menu item and ever toolbar item at least once within the first week or two.
  3069. • Spend time reviewing the client source code. Please be sure to note the coding style when reading the code.
  3070. • Study the client documentation.
  3071. • Check out the client web site at http://www.office.aol.com/windows client.
  3072. • Get a specific version of the client at KW: clients
  3073. • Check out KW:Guidelines, TheGuild
  3074.  
  3075.  
  3076.  
  3077.  
Add Comment
Please, Sign In to add comment
Public Pastes
We use cookies for various purposes including analytics. By continuing to use Pastebin, you agree to our use of cookies as described in the Cookies Policy.  OK, I Understand
Not a member of Pastebin yet?
Sign Up, it unlocks many cool features!