PORTALX - THE AMIGA AUTOMATED "FRONT-END" FOR THE PORTAL ONLINE SYSTEM [sm] NOTE: A description of changes from V1.10 to V1.30 is in the file "Changes.Txt". SYSTEM REQUIREMENTS: - Any Amiga running Operating System 2.04 or greater. - A minimum of two floppy drives required. A hard disk preferred. - A valid current account on The Portal Online System [sm] - A modem and telephone line with which to dial the Portal Online System LEGAL STUFF: PortalX, the executable program, and this documentation file are all Copyright 1992, Steve Tibbett, All Rights Reserved. You may redistribute this archive file anywhere you please however you MUST retain ALL the original unmodified pieces within it. If you redistribute the original archive as you downloaded it from Portal, do NOT add anything to it and do NOT remove anything from it. Please respect these distribution requirements. Do not attempt to modify the PortalX program in any way. Source code is not available. The archive file from which you extrated this documentation should have contained the following: Changes.Txt - ASCII text, listing PortalX changes since V1.00 Friends - A friends list with Harv Laser and Steve Tibbett in it. PortalX - the executable program itself PortalX.info - icon for the program (Thanks to Mike Crossmire for the Icon!) PortalX.Docs - the file you are reading now PortalX.Docs.info - icon for this text file Problems.Txt - help with some common problems Problems.Txt.info - icon for this text file Pages.Txt - ancillary index file used by PortalX Sprintnet.script - login script for PortalX for SprintNet callers Tymnet.script - login script for PortalX for Tymnet callers Direct.script - login script for Portal direct callers xprzmodem.library - Amiga system library to be copied into your SYS:Libs directory, required to use PortalX --------------------------------------------------------------------------- PortalX V1.30 Documentation by Steve Tibbett and Harv Laser INTRODUCTION The Portal Online System ("Portal") is an excellent service for Amiga users. It offers more files than any other Amiga service, and at very low rates. However, the user interface on Portal is less than ideal - the simple task of entering a message can become complicated on Portal. While reading messages is easy, setting Portal up to read messages is not easy. PortalX makes these operations much easier, and gives you a familiar interface to use when reading and writing messages. PortalX uses your favorite text editor to create messages, and complies with as much of the Amiga Style Guide as it can. Once you have PortalX set up and working for you, the only reason to manually log onto Portal with your usual terminal program will be to search for and download older files, and to participate in the live, nightly chats, or to use Portal's Internet Services facilities. PortalX does not deal with live chatting or Portal's Internet Services, and further, PortalX is a completely free-standing executable program - it does not run "inside" of or "alongside" your current terminal program. PortalX requires Kickstart 2.04 or later. PORTALX IS SHAREWARE I'm putting this right at the start of the documentation because I feel this is important. I spent a lot of time working on the original PortalX, and now realize how much more time I could spend working on it. I would like to add quite a few things to PortalX and I can't afford to keep working on it without making any money back from it. I wanted to keep PortalX as freeware, which the first version was released as, but when I released the first version, it was with the intention of being "done" with it, of not working on it anymore, but response has been so good on Portal that I've spent some time working on this new version, especially on the problems that plagued early users, such as the difficulty of setting up Portal. If better time accounting appeals to you, or perhaps a database of messages (rather than just the current session's worth), or an easy way into and out of chat mode - you get the picture - then consider registering PortalX. If nobody registers, it's not going to get these features. If people register, it will. Registering PortalX will give you access to the closed PortalX area on Portal. I will be posting new versions there more frequently than the public releases - but the public version if PortalX will have all it's features enabled. It just might not be as current as the registered version. To register PortalX, send a cheque for $30, payable to Steve Tibbett, to: PortalX Registration 2710 Saratoga Pl. #1108 Gloucester, ON K1T 1Z2 Canada Be sure to mention your Portal ID when registering! (Otherwise I won't be able to let you into the PortalX area). How much work goes into future versions of PortalX will depend entirely on how many users register. A program worth using is a program worth registering, and I hope you appreciate the opportunity to see how the full, uncrippled program performs without having to send in your money first. Thank you. HOW PORTAL WORKS Before you can really understand what PortalX is doing, and how to make it do what you want without getting it confused, you have to understand how Portal arranges messages and files. You don't need to know this stuff unless you start writing messages or uploading files, but it is a good idea to understand this information. CONFERENCE -> COLLECTION -> ARTICLE 1 -> ARTICLE 2 -> ARTICLE 3 COLLECTION -> ARTICLE 1 -> ARTICLE 2.. and etc. A conference is a list of collections. Collections hold articles. This is a simplistic view of how Portal works, since they can set these things up however they want, but for the AmigaZone on Portal, this is how things are set up. For example: FILES -> NEW_FILES -> NewFileOne.LZH -> NewFileTwo.LZH ETC_FILES -> AnotherFile.LZH -> YouGuessedIt.LZH This is how the file area is set up on Portal. So when PortalX speaks of wanting the name of a "Collection", it wants what you would normally call a message or file area. When getting a file catalog of a lot of areas at once, you tell PortalX that the page number you have given it is a Conference, and it knows that that page contains Collections, not Articles. I mentioned Page Numbers there. Everything on Portal has a page number or "go" number, and this is normally right at the top of your terminal screen if you use Portal in its "screen" mode or at each page break if you use Portal in its "line" mode. To get to any page number on Portal, from any prompt, you can type "Go 123.45" where 123.45 is the page number you want to go to. Page numbers for an article will change when the article is moved, but otherwise they are constant. Every collection, every message, every file on Portal has its own unique "go" number. The page numbers themselves say something about the content of that page. A page number ending in ".1" is a root menu, ".3" is a conference, ".3.nnn" is a collection, and ".3.nnn.nnn" is an article. In the AmigaZone, "4842.3" is the file library, "4842.3.32" is the new files area, and a file in the new files area might be called "4842.3.32.104". The message area in the AmigaZone is a little different, in that each message area is a conference, and then each message topic is a collection with articles within that. Whereas "4842.3" is all the AmigaZone file areas, "16046.3" is one message conferece - the programming message section. Within this area, ie, "16046.3.111" you might find a collection of messages on a particular topic, and then the messages in that topic will be "16046.3.111.1" and on up. THE PAGE LIST PortalX has a list of page numbers, kept in a text file called "Pages.Txt", that you can view and edit from within PortalX. When you want to enter a message, or upload a file (for example), you have to pick the page number you want the article to be posted to, otherwise PortalX has no idea where to put it! You do this by selecting the "< pick" gadget and then choosing an appropriate page from the page list. It is important that you choose an appropriate page: If PortalX wants a Conference, and you select a Collection, (or make any other similar mistake), PortalX will likely tell you of your mistake, but if PortalX misses it, then when it tries to send your article (or however it tries to access that page) it will get lost. (Getting lost is covered later) INSTALLATION OF PORTALX ONTO YOUR AMIGA There are a number of simple steps involved in installing PortalX. First is the physical installation - copying PortalX into it's home directory. Make a directory for PortalX, or format a floppy disk for it if you are running off floppies, and place PortalX either in the directory you have made, or on this floppy disk. This will be PortalX's home, and you should always change to this directory before starting PortalX if you are using the CLI. Example: you make a directory on your hard drive partition DH1: called "Portal". To change to this directory from a CLI/Shell prompt you would type "cd dh1:portal" and hit . From Workbench, this happens automatically. (Installation from Workbench is even easier. Create a new drawer for PortalX, and drop it's icon into this drawer). Copy the Pages.Txt as well, to wherever you put PortalX. PortalX uses the XPR external protocol method of doing file transfers, which means you will need to have an "xprzmodem.library" installed in your libs: directory. Copy xprzmodem.library to sys:libs from a CLI/Shell or use your favoriate "dirutil" program to copy it. PortalX will create subdirectories in it's home directory as needed. Mail, MailSend, and Subs are the three directories for storing incoming mail, outgoing mail and requests, and subscriptions, in that order. You don't need to worry about these directories, in general, unless something goes wrong. The items in the Mail Send directory are documented later. CONFIGURATION Once you have installed PortalX, run it. You will see a screen with a single window full of buttons. Click on the Configure button. Here you will see buttons for summoning various other windows, and some string gadgets. "Login Script:" is where you will put the name of the login script that PortalX will use to log into Portal. Typically this will be "Login.script" but if you have multiple ways of getting to Portal, you may need to switch scripts. Login scripts are discussed later. "Download Path:" is where binary files that you download will be placed. This defaults to "RAM:" but most people have a place where they put new downloads, and that is what you should put here. "Log File:" is where you choose a name for the PortalX log file. You can also choose to leave this empty. If this is a valid filename, then PortalX will write the text from the Report window into this file, so that you will have a permanent summary of what you have done in PortalX. "Pop to front when done?" tells PortalX whether or not to pop it's screen to the front of all other screens every time it finishes an online session. "Skip Message of the Day?" tells PortalX to ignore the daily login message. PortalX will normally open a window with the contents of the message of the day, and you can close this window any time during the session. Picking this box will cause PortalX to never open this window. In "Set Editor..." you are asked for the name of a text editor. This must be the COMPLETE PATH to your text editor - not just it's name. Even if the editor is in C:, you must say "C:Editor" or PortalX will not find it. PortalX will use this editor whenever it wants you to write text. The Commodore "C:Ed" editor is not good for this, since it runs on the Workbench screen. You will want to put the name of an editor here that runs on it's own screen, or one that runs on a named public screen. The name of the file to be edited is appended to this string, and then that string is passed to AmigaDOS to be executed. When AmigaDOS returns, the file is looked at, and if it is unchanged, then the edited file is not used. Some text editors "detach" themselves from the shell window when run, meaning that the prompt comes back at the shell before you have even begun editing. You must tell your editor not to do this, to work with PortalX. For example, in TurboText, there is a WAIT option to ask it to wait until the editing is done before returning, and there is a -STICKY option in CygnusEd to do the same thing. The EMACS editor that comes with Workbench is a good editor to use here, if you don't have any other text editor. If your text editor supports opening its window on a public screen, and you can set this on the command line, then do this here. For example, with TurboText, you would say "TURBOTEXT:TTX WAIT SCREEN PORTALX". PortalX's public screen is called "PORTALX", all upper case. In "Set Signature..." you supply the names of files containing "Signatures" that you want to use, when writing either Mail messages, or normal public messages. A signature is your usual signoff at the end of a message. You can use no signature if you like, or you can use the same filename for both signatures. The signature is added to the file before your text editor is called, so you will see the signature while writing the message. Clicking on the "< Edit" gadget next to the signature names will load your text editor (assuming you have configured it already) for editing the Signatures. In "Set Serial..." you tell PortalX where to find your modem. The built-in serial port is called "serial.device" unit 0, but if you have any other serial port or internal modem, you will have to change this. The name of the device, and the unit number, should be included in the documentation for your device. The baud rate when logging in will be set to the number you choose here - all communications with your modem will happen at this rate. You also tell PortalX how to hang up. PortalX needs to hang up the phone (your modem) at the end of each session, and there are many ways to do this. The two most common, depending on your modem settings, are to either just drop the DTR line, or to send the modem a "+++", then an "ATH" with a one second delay surrounding the "+++". PortalX will use one of these methods depending on what you tell it here. "Set Screen Mode..." is only available if you are running Workbench 2.1 or later. Picking this option will bring up a screen mode requester, where you can choose a new screen type to run PortalX on. If you do not have Workbench 2.1, you can use the "i" and "n" characters to tell PortalX, when started from the CLI, which screen mode to use: Interlace and Non-Interlace respectively. If you save the configuration after running it this way, then that will be your screen mode for future sessions. If you "Save" your configuration, it will be the same the next time you load PortalX. "Use" will make the changes for this session only - quitting PortalX will cause it to use the last saved settings the next time you run it. The PortalX config file is called "S:PortalX.Config". When you save your configuration, some other things are saved as well, that are not set in the Config window. These are: The path for saved messages, and the size of the message and mail read window, and the settings in the Session Options window. The "Check In" button is discussed later on. The "PortalX Support" button is a button you can push to get PortalX help (assuming you've already gotten PortalX working). This button automatically directs a message from you into the PortalX message area in the AmigaZone on Portal. THE LOGIN SCRIPT PortalX has to log into Portal for you. To do this it uses a script file, whose name you can set in the Configuration section in the program. Login Script Commands: @ Set maximum wait time in Seconds < Wait for the text after the < > Send the text after the > (Using ^ for ctrl) # Wait this number of fiftieths of a second * Same as > but shows "Sending Password" in the status window. The login script is parsed right from the start, and cannot include comments or other text. If the maximum wait time is exceeded, then PortalX will abort the login. Sample PortalX login scripts are included with PortalX for some of the various ways of getting to Portal. "Tymnet.script" works for tymnet nodes, and "Sprintnet.script" works for Sprintnet. You will have to change the phone number after the ATDT to your local Tymnet or Sprintnet phone number, and of course change the Username and Password to your own. If you have a PCPursuit account and wish to use it for your Portal hours, change the entry which reads "c portal^m" to "c portal,PCP-ID,PCP-PASSWORD^m" using your own PCPursuit account's information. If you don't have nor use a PCPursuit account, then just leave that line alone. If you have trouble logging in, then one of many things may be happening. The most common is that takes a very long time to log in, or the Login script complains of a timeout. This is because sometimes Portal takes a long time before it will ask you for your name, and sometimes it will take a long time between asking for the password and actually letting you online. There is nothing you can do here other than be patient. Another common problem is that Portal refuses to acknowledge your password the first time you enter it. Your only recourse in this case is to call back. This will normally happen more often for folks who use Sprintnet or Tymnet V.32 9600 nodes than for those who use 1200 or 2400 baud nodes. PORTAL SETUP: CONFIGURATION *Note: With PortalX 1.10 and later, the Portal configuration discussed in this section can be performed automatically by PortalX. If you select the "Configure Portal?" box in the Session Options window, then the next time you call Portal, PortalX will make all of these settings for you. It is a good idea to do this the first time you call Portal with PortalX! I am leaving this section in the manual just in case the automatic configuration doesn't work for some reason. PortalX has to talk to Portal like no other program does. It parses the ANSI sequences that Portal sends, and keeps its own internal map of what the screen looks like, and instead of dealing with information as it is sent from Portal, it waits for the end of each "Page" and then looks at it's internal image of the page and gets information from there. This method has advantages and disadvantages. One big advantage is that for pages that are small changes from the previous page, very little information needs to be sent for an entire new page. But the big disadvantage is that one byte of line noise can corrupt an entire page. In practice, it's not so bad, especially if you use an error-free connection such as MNP or V.42. However, another disadvantage is that the information that PortalX expects has to be sent, and has to be exactly where it is expected to be. If you haven't changed your Portal configuration much from the defaults, then this shouldn't be a problem for you. However, if you have changed the default separator, the command prompt, or how the menus are laid out, then it may cause problems. The best way to proceed is to try PortalX with your configuration as it is, and if that fails, then set things back to the defaults. You will need to have the help_type set to none, otherwise every page will have multiple lines of useless help information on it and PortalX will fail. You must also make sure Portal is set to use Zmodem for file transfers. If you are starting with the default settings, then getting PortalX to work would involve setting these things: set form/screen/header/help_type=none set transfer/general/protocol=zmodem set transfer/general/end_line=lf set transfer/general/batch_files=no To make these changes, log into Portal with your usual term program, and then type those lines, exactly as you see them, at the main menu command: prompt. If you have made changes that you think will make PortalX incompatible with your setup, then go to the various pages you have changed and type Default. This will reset the settings to the defaults - and then you can make sure they are set properly by using the commands above. Make sure you leave each Portal Settings menu with an "ok" command in order to save the changes. PORTAL SETUP: SUBSCRIPTIONS ** THIS IS WHAT IT'S ALL ABOUT SO READ THIS PART CAREFULLY! ** PortalX's main function is the daily collection of "Subscriptions", and the interface it gives you for reading them and responding to them. But first, you need to know what Subscriptions are. On most bulletin boards and online systems, when you want to read messages from a specific area, you have to go there and read them. This would be like having to go to a different store to pick up every magazine you wanted. On Portal, you can subscribe to the areas you are interested in, and then these are delivered to your subscriptions box as they are created. When you read Subs, you are reading all the NEW messages that have been entered in any area that you have subscribed to SINCE you subscribed to that area. You only need to subscribe to any area on Portal ONCE. If you try to subscribe to an area that you are already subscribed to, Portal will tell you. If you subscribe to an area to which you are NOT already subscribed, Portal will simply reply with an "OK" meaning, okay, this area is now added to your subs. Think of subs as your own private "clipping service" which keeps track of all new notices and files posted to your favorite areas. It's your job to first tell Portal WHAT those favorite areas are. Subscribing to an area on Portal is easy - you just go there and type "Subscribe". "Go there" means you can wander around Portal manually using its menu system, or you can use shortcut "go" numbers if you know where you want to go. KEEP IN MIND THAT PORTAL GATHERS YOUR SUBSCRIPTIONS IN THE SAME ORDER THAT YOU SUBSCRIBED TO EACH AREA! So before you start collecting Subs with PortalX, you will have to log onto Portal, go to all the collections you are interested in, and Subscribe to them. Alternatively, if you want to subscribe to ALL the message areas or ALL the file areas, then go to the conference that holds them, and type Subscribe there. This will subscribe you to every collection in that conference. Then if you don't want some specific collections, you can unsubscribe to those. Subscribe and unsubscribe can be abbreviated "sub" and "unsub". They are toggles. You either turn a Portal area on or off for your subscriptions. When you first joined Portal, all areas are, by default, turned off, except for the Portal News area. The file area in the AmigaZone is a special case. New files show up in collection #0, and after a week are moved into the other collections. To avoid having every file show up both as new and when it is moved, you should subscribe to only collection #0, the new files collection. So to set up subscriptions to read all new messages in the AmigaZone, and all new files, you would do this (Don't type in the text from the asterisk on, it's just comments): Go 4842.3.32 * Go to the New Files page Subscribe * Subscribe to it Go Amiga;0;2 * Go to the AmigaZone Messages Subscribe * Subscribe to them Also, I recommend that you subscribe to the PortalX message area, at least initially. If you do not, then the "PortalX Support" button in the Config window will post any questions you ask, but since you aren't subscribed to that area, you won't see the answers! To subscribe to this area: Go PortalX;0 * Go to the PortalX public area Subscribe * Subscribe to it SESSION OPTIONS The Session Options button brings up the Session Options window. Here you can change what PortalX is going to do next time it connects with Portal. "Retrieve Mail" asks PortalX to download all your mail messages so you can read them offline. "Kill Mail" asks PortalX to kill the mail after it has read it, so that it is not there the next time you log in. "Get Subs" asks it to pick up all your subscriptions, with one exception: UUEncoded files will not be gotten, rather just the first page will be. (You can ask PortalX to download the entire uuencoded contents while reading subs). The options you select in this window are saved when you save the configuration from the Configuration window. "Do Requests" asks PortalX to go through the Send directory and do everything you have asked it to do. This incldues posting mail messages, public messages, downloading files, uploading files, and getting file catalogs. "Configure Portal" asks PortalX to change the Portal settings to those that PortalX requires. You should do this the first time you use PortalX to call Portal, and if PortalX for some reason stops working for you (it gets lost when trying to log in), you can try "Configure Portal" again. CALLING PORTAL The Big Button. When you select Call Portal, PortalX will start processing the login script, and when it is done, take over and do what you have asked it to do in the Session Options window. You can abort the online session by clicking the close gadget in the Online Status window. The Report window can be closed only when the session is complete. Portal's Message-Of-The-Day will be displayed inside of PortalX in its own window which will pop up every time you log in. You can close this window as soon as it appears, or disable it with a button in the Config window. Please consider reading the MOTD window.. it contains useful and important information about what's going on, on Portal today. It is important to keep in mind that PortalX never appends to existing data. If you have previously downloaded 20 mail messages, and you ask PortalX to go get mail, it will delete your existing 20 mail messages from your disk drive. Same for Subs. PortalX has the capabilities to let you save to another file any mail or subs articles while you are reading them. When your PortalX session is complete, if PortalX picked up mail or subs, then the "Read Subs" or "Read Mail" buttons may have a hilight around them. This means that there is material here that you have not yet read. Once you have read all the subs, and all the mail, these buttons will no longer be hilited. Also, if you write mail, write a message, upload a file, or ask PortalX to do anything else online, PortalX will hilite the "Call Portal" button so you know there is something for it to do online. If you want your PortalX sessions to happen unattended, for example during the early morning, then put a "c" on the command line: "PortalX c" will cause PortalX to act as if you had pressed the Call button as soon as you ran the program. However, be warned that there is no guarantee that every PortalX session will go smoothly. You may come home to find that PortalX has been online the whole time, thanks to some miscommunication between PortalX and Portal. In general, however, this is an excellent method of having your subscriptions picked up during the early morning, ready for you the next time you check in with your computer. The AmigaDOS WAIT command is an excellent and simple way to accomplish this. If you type into a shell window: Wait Until 6:00 PortalX c The WAIT command will wait until 6AM, and then let PortalX proceed, calling Portal. READING MAIL Pick "Read Mail" to start reading mail. You will be shown each mail message, in a window with a few buttons at the bottom, the Read Window. The Read Window has a few keyboard shortcuts that you should know about: The up and down arrows will move you through the current article, and the left and right arrow keys will move you through all the articles you have downloaded. Shift-up and Shift-down will page through the article. When you click Reply, you will be asked who the article is to, with the default being the person who sent you the letter. If you select Include Original, then the original message text will be prefaced by '>' and included with your signature in the text file that you will be editing as the message to send. The read window position is saved into the config file. To have the read window come up in a specific position, after you have gotten it to look the way you want it, go into the Config window and pick Save. There are some menus available while reading mail messages. On the message menu are options for saving the message to a file, or appending the message to an existing file (creating it if it does not already exist). The Print option will send the text to the printer, and the Copy to Clipboard option will copy the entire text to the clipboard from which you could paste it into a text editor, etc. The Keep button in the Read window will take the text you are reading and append it to the file you last appended data to using the "Append to File..." menu option. READING SUBSCRIPTIONS This works the same as reading Mail messages, except that you can also choose a menu option to have PortalX download the body of the article you are looking at next time you log in. While this may not be of use for normal messages, it is a handy way of downloading files that appear in the AmigaZone New Files directory while you are reading subs, or binary files that appear in any other Portal SIG to which you are subscribed. While reading subscriptions, there are three extra menu options: Next Topic, Next Conference, and Goto Article. Next Topic and Next Conference will skip articles in either the current topic or the current conference. Goto Article will ask you for an article number, and will then take you there. If the last two lines of an article indicate that the article is a binary article which cannot be read, only transferred, then PortalX has sent the describe command to get the description that you see (if indeed you see a description). To download the body of the article, use the Download menu option. PortalX will download the file for you the next time you use it go log in to Portal. THE FRIENDS LIST The file "Friends" in the same directory as PortalX is read into memory when PortalX is loaded. This file is a list of names, Portal ID's, and comments, for people you exchange mail with. When you write a mail message or reply to one, you can click on "< Pick" next to the string gadget for the name, and pick the user's name from the list. You edit this list in PortalX by selecting "Edit Friends List" from the main window. To add a new friend, click on the New button and then type in the name, ID, and any comments you have. The name is actually added to the list when you hit return in the comments field, so make sure you do this. WRITING MAIL To compose a mail message, pick Write Mail message. You will be asked who the message is to, what it is about, and then dropped into your text editor. The message will be sent next time you log in with the 'Do Requests' button selected. You can send mail to more than one person by separating their names with commas in the To: field, such as "SteveX,Harv,Elvis" to send mail to Steve Tibbett, Harv Laser, and Elvis Presley. Unfortunately, PortalX doesn't deal with bad usernames - if the username is incorrect, PortalX will tell you that the name is bad and ask you if you want to edit the request file that has the bad name in it, or just delete the message. Make sure you know the current, correct, and complete address for anyone to whom you wish to send email. WRITING A MESSAGE Writing a public message is more involved than writing a mail message, because of the many different types of messages involved. Specifically, you can post into a local Portal area, or you can be posting to a Usenet newsgroup. You could also be trying to post to a Usenet newsgroup where posts are not allowed. Usenet postings are called "articles." The person who posts an article to Usenet is called the "poster." You are asked for a page number to post the article into, and for a subject. The page number must be that of a collection - not of an article you want to reply to. Since 'Do Requests' happens before 'Get Subs', if you post a message to a local Portal message area, you will see it as a new subs article in the same session, unless you are posting to a Usenet group, in which case the article will show up sometime in the near future. As usual, if you ask PortalX to do something that Portal will refuse to do, PortalX will get lost. UPLOADING A FILE Uploading a file to Portal is much like entering a message, except that the body of the message is binary, and there is a description. PortalX wants a filename for the file to upload, and also wants a disk filename that contains the description of the file. If you don't have a file description already written for the file, you can use the "Create Description" to create a temporary file and write a description into it. The actual subject line of the posted file will be the filename, converted to upper case, with " - " appended to it, and then the summary field you supply here appended to that. So if you are uploading "fred.txt", and your summary is "A new text file.", then the actual subject line on Portal would be "FRED.TXT - A new text file." Please do NOT upload new files to the Amiga Zone without also including a good description of the file. Other Portal SIGs may have different rules about descriptions for their files. When in doubt, send email to the SIG moderator and ask. PortalX wants a page number to upload a file into. This page has to be one that contains a list of files - a collection - otherwise PortalX will get lost. (File collections have 3 numbers, for example, the AmigaZone new files area is "4842.3.32"). GET CATALOG This function will pick up a file catalog from Portal. PortalX will look for the page number it should fetch the catalog from, and where it should put it. PortalX will figure out if you are asking for a catalog of a single area, or of an entire tree, by the page number. Feeding it "12117.3" would ask PortalX to go and build a catalog of all 700+ fish disks, which PortalX would happily do over the next few hours. So don't ask for a Fish catalog unless you really mean to. More explanation of this function is in order, since it can really do more than it claims to. What this function does is go into a collection and read the titles of all the articles there. It can also go through an entire list of collections. Because of Portal's setup, messages look just like files - so you could give this function a page number that contained, for example, the "Rumours" AmigaZone message area, and PortalX would get a ilst of all the messages in that message area. Asking this function to pick up a catalog of "4842.3" would give you a file similar to what Harv creates every week and posts as the AllFiles list in the Amiga Zone New Uploads library. Thus you can now make your own AllFiles list anytime you wish! DOWNLOADING A FILE To download a file, you need to know the location of the file. You can either specify it as a complete page number, or you can give the page number of the area the file is in, and then the file number you want to get with a semicolon between them as in "4842.3.32;3" to get file #3 in 4842.3.32. This method is less reliable than having a full page number since when files are moved, all the files after them in the list get a new number. A file's page number is never changed. If you ask PortalX to get a catalog, see a file you want in the catalog, and the file is not in the new files area, then you can be fairly certain that if you ask PortalX to download it, it will still be in the same place. If you want a month, it might not be. GETTING LOST If PortalX encounters a situation it cannot deal with, it will typically sit waiting for some result from Portal, that Portal has no intention of ever sending. In this case, PortalX will wait up to five minutes, and will then abort the session. However, if PortalX and Portal get into a situation where PortalX is sending data and Portal is responding in some way that makes PortalX think things are proceeding properly, they may get into a mode where they could be online forever. There are some checks in PortalX for this situation - such as repeated sending of the same page. These situations are usually caused by line noise, so if an error-free connection is possible, then try and use it. If you typically get noisy connections, you are advised against using PortalX at all unless/until you get the line noise problem straightened out, with your modem, your modem cable, and/or your telephone company. WARNING PortalX's job is processing your mail and messages. If PortalX doesn't do it's job properly, then it is possible that you could lose mail messages, subscriptions, your mail may not be posted properly, you get the picture. PortalX could decide to stay online much longer than it should have, for no good reason. While this doesn't normally happen in real life, it could. I cannot be held responsible for anything this program does - use it at your own risk. CHECKING IN I had fun writing PortalX, and have a lot of things I'd like to do to it. I'd like to know how many people are using the program - and the only way I can know this is if people tell me. Rather than having everybody write me a mail message just saying "I used PortalX", I put in the "Check In" button. Press this button once, and then the next time you call Portal, PortalX will send me a short message telling me that you are using Portal, and what version. Please press this button, I would appreciate it. Thanks. SUMMARY That about covers it. PortalX will let you keep up with what's going on in the message areas on Portal, download new files, post public messages, and generally get a lot more out of your Portal account. I look forward to seeing you use it! TECHNICAL: THE SEND DIRECTORY The "Send" directory in PortalX's home directory contains files that tell PortalX what to do next time it is online. There is nothing special about these files - you can create them yourself if you like. This entire directory is searched for every online session with the "Do Requests" box checked. Every .Data file is processed. Some of the event types require extra information, such as the actual message to post, and this is stored in the "MailSend-%d.Txt" file - so if you manipulate the .Data files, you should manipulate the .Txt files as well. The types of files, and what they are expected to contain: Upload Upload [Page to upload to] [Filename] [Subject line] [Description filename] GetCatalog GetCatatalog [Filename to hold catalog] [Page number] GetAllFiles GetAllFiles [Filename to hold catalog] [Page number] * Post Mail Mail [Who the message is To] [Message Subject] * Public Message Message [Page Number] [Subject] Download Download [Page Number] [Destination Directory] * Public Reply [Page Number] [Subject] Items marked with a '*' are items that require an associated .Txt file, containing the message text to be sent. WHERE TO GET MORE HELP WITH PORTALX A new Amiga Zone message base named "PortalX questions and answers" has been created in the Amiga Zone. You should ONLY post questions or offer assistance to other users in this new message base. Be sure to subscribe to it! Please do not burden the email boxes of the Amiga Zone moderators with PortalX questions. Ask your questions in public so that everyone can see them and have an equal opportunity to learn from the replies. Please do *NOT* phone Portal Communications to ask for help with PortalX. They are not Amiga users and will just refer you to the Amiga Zone for help. PortalX is *NOT* sold by, nor distributed by, nor supported by Portal Communications at this time. ----- Amiga is a registered trademark of Commodore-Amiga Inc. and/or Commodore Business Machines and/or Commodore International Ltd. "The Portal Online System" is a registered service mark of Portal Communications Inc. -----