Whatson ======= version 1.0 ©1999 Frey Mansikkaniemi ------------------------ 1. Legal Stuff 2. Requirements 3. Description 4. Installation 5. Usage 6. GUI Reference 7. ARexx Interface 8. Bugs 9. Future 1. Legal Stuff ============== Whatson is released as freeware as long as it's not used commercially. That is, it's free for personal use but if it is used in any commercial activity or business you have to contact the author to discuss the licence. Whatson may be distributed freely over the Internet and on Aminet CD collections. For inclusion in other distributions (on CD or any other media not freely available to everyone) permission from the author is required. Oh and you are of course using this program completely at your own risk. If it blows up your computer I won't be liable. 2. Requirements =============== To run this program you need at least version 3.0 of AmigaOS and MUI version 3.8 or better. In order for this program to be of any use to you, you will also need access to the Internet, a program to download HTML files and a program to convert HTML files to text. For this purpose I can recommend GrabURL by Serge Emond and httx by Gabriele Favrin. Both are available on Aminet. 3. Description ============== The purpose of Whatson is to have a program which can tell you what's on TV at any given time. This is done by first downloading the files containing the TV listings from the Internet, converting them to ASCII-files and finally loading them into Whatson. Whatson then tries to interpret the files and compiles a list of programs for each channel. It then goes through the lists and finds out which programs are on at the moment. The result is displayed in a listview, which automatically updates itself, when new programs come on. 4. Installation =============== No special installation is required. Just copy it wherever you want it. 5. Usage ======== -The listing files The listing files provided to Whatson must be in ASCII format. In the listing file the programs should be listed below each other. Every program entry should begin with the start time of the program optionally followed by the end time and after that the name of the program and finally a program description. Example: --- 10.30 First program This is the first program 11.00 Second Program This is the second program 11.30-12.00 Third Program This is the third program --- It doesn't have to look exactly like the example. Different variations are allowed. Most listings of European channels I have tried work fine. Different Time Formats ---------------------- Both 12 hour and 24 hour time formats are supported. The Date of the Listing ----------------------- The date for which the listing is meant is determined by the date stamp of the file. This could be implemented in a better way, but this works fine for me and I didn't have time to work on a different solution. So if the listing is for Wednesday May 5th 1999, the date stamp (the creation date of the file) must be the same. Listings for More than One Day ------------------------------ If you want to use listings for multiple days all the listings have to be in the same file below each other in the right order. The date stamp of the file must be the date of the first day of the listing. -Adding a new channel The first thing you have to do, after downloading and converting the listing files is to add the channel to Whatson's list of channel profiles. This is done in the Channel Editor. Bring it up by selecting Edit Channels in the Settings menu. Now press New below the listview. The string gadgets will be activated and you will be able to enter data about the new channel. Enter the channel name and enter the file name of the text file which holds the listing for this channel. Next enter the time zone of the place where you got the listing from (Note: this is not necessarily the same time zone as the one where the TV station is). The format of the time zone is hh.mm where hh is hours and mm is minutes to add to GMT. The remaining cycle gadgets are optional and should be left like they are in most cases. You might need to adjust the settings later but leave them like they are for now. Now press the Save button and Whatson should begin to work on your new channel. After a moment it should appear in the listview and the program which is currently showing on that channel should show up in the listview of the Whatson window. Repeat this process for all of your channels and finally save your channel profiles with the Save item in the Project menu. 6. GUI Reference ================ -Menus *Project NEW Clear the current project. Deletes all the channels and resets everything. OPEN... Open a project file containing channel profiles. UPDATE Use this after you have updated the listing files to scan through them again and load the new contents. SAVE Save the current project. Saves the channel profiles. The listings are not saved, they are reloaded from the original files every time a project is opened. SAVE AS... Same as SAVE except it opens a file requester. ABOUT... Information about Whatson. Current version number and ARexx port. ABOUT MUI... Self explanatory. ICONIFY Iconifies the program. Closes all windows and puts an icon on the Workbench which can be used to uniconify the program. QUIT PROGRAM Quits the program *Settings EDIT CHANNELS... Open the channel editor. MUI PREFS... MUI settings for this program. -Windows *Whatson Window -Now tab Displays all the programs currently on TV. -Next tab Displays the programs for every channel that will come on next. *Channel Editor -Channel listview Displays all the channel profiles -Save button Add the entries in the string gadgets and cycle gadgets to the list of channel profiles as a new channel. -New button Clears and activates the string gadgets and cycle gadgets. Use when you want to start entering data for a new channel profile. -Delete Deletes the active entry in the channel listview -Name string gadget The name of the channel -File gadget The file name of the listing file belonging to this channel. Press the popup gadget to pop up a file requester. -Time zone The time zone of the place where you got the listing file from. Expressed in hh.mm where hh is hours and mm is minutes to add to GMT in order to get the local time of the listing file. - End of program name The method used to separate the program name from the description. Currently the options are : (colon) . (period) and linefeed ( a new line character ). Normally you should use the dafault Auto option, which automatically finds out the correct option for this file. If something looks wrong, like the program name doesn't end where it should when parsed by Whatson, you can try to change this setting to fix the problem. - Time format Determines if 24 hour or 12 hour time format is used in the file. Auto automatically chooses the right alternative. Change this only if it seems impossible for Whatson to get it right. - Hour-minute separation The character used to separate hours from minutes in the listing files. The options are : (colon) and . (period). Use Auto to make Whatson find the right character automatically. Only use something else than Auto if Whatson can't get it right by itself (ie it doesn't find any programs in the file). 7. ARexx Interface ================== The name of Whatson's ARexx port is WHATSON.x , where x is a number beginning from 1, depending on how many copies of Whatson you are running simultaneously. The name of the ARexx port for each copy of the program can be found in the About window. All commands set the return code in ARexx to 0 if they succeed. A return code of 5 is used if the command itself was successful, but it failed to complete some secondary task like updating a listview after adding an entry. 15 is used if the command failed completely. 30 is used if Whatson didn't understand the ARexx command. The following commands are supported: QUIT FORCE/S Quit the program. FORCE switch will prohibit the program from popping up any requesters. HIDE Iconifies the program SHOW Uniconifies the program NEW Same as menu option New UPDATE Same as menu option Update OPEN FILE/A Same as menu option Open. FILE is the project file containing channel profiles. SAVE Same as menu option Save SAVEAS FILE/A Same as menu option Save As, except the file name must be provided, this won't pop up a requester. GETNOW STEM/K Sets an array of ARexx stem variables to the list of programs currently on TV. STEM sets the name of the stem variable, default is NOW. The following variables are set: NOW.i.CHANNEL channel name NOW.i.TITLE program name NOW.i.STARTTIME start time of program in the format hh.mm NOW.i.DATE start date in the format dd.mm.yyyy NOW.i.ENDTIME end time of program if available, default is 0 NOW.i.DESCRIPTION program description and finally NOW.COUNT the number of the last entry in the list In the definition above i runs from 0 to NOW.COUNT GETNEXT STEM/K Same as above, except this gets a list of programs coming up next. The default stem variable name is NEXT. GETCHANNEL NAME,NUMBER/N/K,STEM/K Sets an array of ARexx stem variables to a list of all of the programs of a certain channel. STEM sets the name of the stem variable, the default is PROGRAM NAME specifies the name of the channel to list. NUMBER specifies the ordinal number of the channel to list. Either NAME or NUMBER must be specified. The variables set are the same as for GETNOW and GETNEXT ADDCHANNEL FILE/A,NAME/A,TIMEZONE/A Adds a channel to the list of channel profiles. FILE is the file name for the listing file NAME is the channel name TIMEZONE is the number of hours and minutes to add to GMT to get the local timezone of the listing file. The format is hh.mm. DELETECHANNEL NAME,NUMBER/N/K Deletes a channel from the list of channel profiles. NAME is the name of the channel to delete. NUMBER is the ordinal number of the channel to delete Either NAME or NUMBER must be specified. LISTCHANNELS STEM/K Sets an array of ARexx stem variables to a list of all the channels in the list of channel profiles. STEM sets the name of the stem variable, the default is CHANNEL The following variables are set: CHANNEL.i.NAME channel name CHANNEL.i.FILE file containing the listing for this channel CHANNEL.i.TIMEZONE timezone of the channel listing file in the format hh.mm where hh is hours and mm is minutes to add to GMT to get the local time of the listing file and finally CHANNEL.COUNT the number of the last channel in the list. In the above definition i runs from 0 to CHANNEL.COUNT 8. Bugs ======= As in every other program there are probably lots of undiscovered bugs in Whatson. Bug reports can be sent to freym@icon.fi -Known Bugs *The channel listview is supposed to be sortable by dragging and dropping the entries, but for reasons I can't understand this doesn't work. *The ARexx command ADDCHANNEL sets the returncode to 0 even if it fails. 9. Future ========= The future of this program is largely dependent on the feedback I get from other users, so please let me know what you think about Whatson and what you would like to see in the future. Currently I have plans to add a favorite program feature, which would alert you when one of your favorite programs comes on. It's also possible that I would add support for channel logos. But please let me know about your thoughts of this program: * freym@icon.fi *