Fileshare Helpfile

This is a little know-how intended for people with no PIL experience and/or little computer knowledge as well. If you can still not understand my explanations, this is possibly because I'm not a native english speaker... :-) - mail me!

What do you want to know?

How to...

...install the whole thing
...start it
...make a filelist
...create a filelist from a PLS or M3U playlist (winamp mainly)
...NEW:change the messages to channels and users and their colors, change the list file header

...create a filelist from a DOS directory listing (obsolete)
...make a filelist of files from several drives / directories without a common root (obsolete)

...the control panel
...commands for the sender
...commands for the remote user
...the "Settings"
...the files the script creates
...known problems

Installation

Install the program itself in the "Aliases" section:
• make a new subdirectory (subfolder) in your PIRCH98 directory (may be c:\programs\pirch98 or something similar). The name of the directory must be FILESHARE

If you have windows then this is done with the windows explorer:
Start the explorer program (Start => Programs => Windows Explorer) (not the Internet Explorer!), find the PIRCH98 directory (usually this is something like c:\programs\pirch98 or c:\pirch98 - open subfolders by klick on the "+" sign next to the folder name in the folder list), mark the PIRCH98 folder in the directory tree on the left, then select file - then new - then folder from the menu and type in the name FILESHARE
The script will place all the files it needs into this directory at run-time.
• extract or copy all the files you downloaded there (especially custom.txt)
• klick on "Aliases" in the Icons bar (or select Tools - Aliases from the menu)
• Alias window pops up
• move the mouse arrow over the aliases list on the left-hand side of the window, klick the right-hand mouse button
• quick menu pops up
• select "add PIL script" from the popup menu
• file selector window pops up
• select FileShare.pil
• repeat this with FileShare1.pil (both modules are required)
• close the alias window with the "save" icon in the upper left


now, install the event triggers in the "Events" section: see screenshot

• klick on "Events" in the Icons bar
• Events window pops up
• select event level "000-unknown" in the upper left (check (select) it - adress mask then is *!*@*)
• copy the following lines into the editing area (you'll have to press ctrl-v if you want to paste it):

ON TEXT:@*:#:/runscript [FILESHARE] AT $nick # *1
ON TEXT:!*:#:/runscript [FILESHARE] FILEREQUEST $nick # *1
ON TEXT:!*:*:/runscript [FILESHARE] FILEREQUEST $nick MSGWINDOW *1
ON DCCSENDFAIL:*.*:/runscript [FILESHARE] DCCSENDFAIL $nick $rate $percent $sent $filename
ON DCCSENT:*.*:/runscript [FILESHARE] DCCSENDCOMPLETE $nick $rate $filesize $filename
ON NICK:#:/runscript [FILESHARE] NICKCHANGE # $nick $newnick
Caution! Case sensitive!
• check (=select) the "Enabled" box in the icon bar
• close the Events window by clicking on the "Save" icon in the upper left


The installation is now complete.

How to start the program

Type in: /runscript [fileshare] reset

/runscript [fileshare] compile
This is only needed when an initialisation breaks somehow. Compile first, then reset once more.

Creating a filelist:

This is now very easy as I have managed to make the whole process automatic. Just klick on the Createlistfiles button. You get prompted for directories and file masks.
Examples for inputs:
c:\*.jpg /s   (all .jpg files in the c: root directory and all its subdirectories)
d:\mp3\*.mp3  (all .mp3 files in d:\mp3 - without subdirectories)
c:\programs\pirch98\fileshare\marc2_filelist.txt  (include the own filelist)
You can use as many lines as you want and combine any drives and directories. Should be quite easy.
You can use the Other List... button if you already have a playlist or DOS dir file.

Note: PIL is a script language and normally doesn't let handle binary files like mpeg audio, though I managed to read the music data of these files. But unfortunately this is a bit slow, so be patient when you make the list the first time. (only files that have changed are being evaluated)
Some files do not have a valid frame header at the beginning (data can only be extracted by a binary-reading program). They will be considered to have 128 kBits/sec.

Please also see the known problems section on this topic!

Creating a filelist out of a playlist file:

This another option you can choose. The process is more time consuming than the one above but it lets you select individual files more effectively.
If you are sharing MP3 files, your player should be capable of creating list files of the M3U or the PLS format (Winamp is). If not, the list file should be type text and contain 1 file name per line,
...if the variable file root is empty (see settings): specifying the whole directory path including the drive, e.g.:
d:\mp3\file1.mp3
d:\mp3\somesubdir\file2.mp3
...
...if you have a basefiledir, it should contain the paths from the basefiledir up and the filename. (am I getting complicated? :-)
In my example, if basefiledir=d:\mp3\ - then the entries are:
file1.mp3
somesubdir\file2.mp3
...

With Winamp you can do it easily: open the playlist editor, then drag/drop the whole folder which contains your MP3s into the editor, sort the list (best is filename and folder), then save the list (M3U and PLS both work). Screenshots

• Before you klick the "create list files" button on the fileshare panel you must set the basefiledir variable. See settings (most times this will be the directory name which you made your dir listing of). If the dir list does not work for any reason, please send the list to me, may be it has some other format that is currently not recognized by the script.

You also have to set the listfile variable. See how to do it (Settings)
• type in the PIRCH input line: /runscript [fileshare] reset (if it doesn't work, type /compile [fileshare] first).
• A window labelled "Fileshare Monitor" should appear. (if not, check if the script is installed properly in the aliases section)
• Klick the button Create list files... , then Other List. A file selector window pops up.

NOTE: Your nick should now be the one you intend to use when the script is active.
• Select the "mother" filelist you have made in the above step.
• See a line counter count upwards. When finished there appears something like this in the "Actions" field:

30.03.99 02:00:07  new list files generated
list files generation complete, number of files: 351,1477 MegaBytes total
paths list: D:\Programme\pirch98\fileshare\paths.txt
send list: D:\Programme\pirch98\fileshare\SCHNECK_FILELIST.txt
plain list: D:\Programme\pirch98\fileshare\filelist.txt
As you can see, there were three text files generated. These can beviewed with any text editor. More about the files

The control panel ("Fileshare Monitor")

see screenshot

Main functions can be switched directly by activating the checkbox and then pressing the Apply button.
Script ON

Turns the whole script processing (@find, send, advertise, any messages) On and Off.
Send
Switches the file sending. When send is off, also playing to channels is off. (@find still works)
@Find
Switches replies on @find requests.
Random Player
Turns the player on and off.
Advertise
Turns advertising in channels on and off.


The new GUI has several sections that can be switched with the buttons on top.
Log

Shows you a log of the actions. A full log is also available as a file: fileshare.log Info on generated files
Sends/Queue
Shows current sends and queue. Including some controls.
Send now! button
Selected file will be added to the send list and sent immediately. You are prompted for a nick to send to.
Refresh button
If Status is not updated frequently enough, do it this way.
Send now! button
Select an entry in the queue section of the status field first. This file will be sent immediately, no matter how long the queue is (see Settings) and how many sends you currently have.
Delete Entry! button
Select an entry in the queue section of the status field first. This file will be removed from the queue.
/msg User button
Use this if you want to send a private message to a user in your send- or queuelist. Select a user first.
/msg All button
Use this if you want to send the same message to all the users you are sending to and those in your queue.
View/Play/Send
Opens the player and manual send control. With Send to.. button you can send the selected file to the nick entered in the box next to it.
Open! button
Select a file and play/view/whatever it with the system default viewer.
Create list files
Switches to the list file maker. Enter the paths and press Go! - press Other list... if you want to use a playlist or have a DOS dir file. see creating lists
Settings... button
Displays the initial Settings/Options to edit.
www (Help)
Loads the FileShare homepage into your browser.
 

Settings / Options:

see screenshot

NOTE: not all the settings you change have effect immediately after you press "Save" (e.g. the filenames)! These are meant to be initial values after a reset!
 

• Click on the Settings... button in the control window.
• Settings/Options field appears. Now you can change the initial constant values:


auto start on event

If checked, the program will start whenever a @nick or !nick event occurs. This way, it automaticly pops up whenever you're in a dedicated channel.
max. sends
Maximum of simultaneous allowed send sessions. Depends on your bandwidth how many sends you can handle at once.
sends per user
Maximum allowed simultaneous sends to a single user. All additional requests will be added to the queue.
queue length
Maximum entries in the queue. All additional requests will recieve a "sorry" message and will not be added.
queue per user
Maximum entries in the queue a single user is allowed to have.
low cps limit
Is the low cps limit (characters per second = bytes per second), below which a send may be removed from the send list. This protection only comes to account if (size of file [bytes] / duration of send [sec]) < lowcps.
NOTE: The transmission will not break if this condition comes true, only the send list will be cleaned up!
Unfortunately, there is no way of getting the real cps at any time of transmission in PIRCH yet.
max. @find replies
If more files are found, the user is informed to download your list.
file root
Note: it is only necessary to set the file root if you generate your list file from playlists. Else leave this field empty.
This is the base directory (folder) of all the files you want to make public. This is the common root of the entries in your primary file list (the "file list" textfile you derive your working lists from - this is discussed here). If they don't have a common root, leave this empty.
e.g. if all the files can be found in d:\mp3\ and its subdirectories,
d:\mp3\file1.mp3
d:\mp3\subdir\file2.mp3
...the file list entries will be
file1.mp3
subdir\file2.mp3
...and so on. The file root then is d:\mp3\
If your files are located on different harddisks, leave this empty
queue commands
If you want to queue commands (messages etc.), set this to 1, else to 0.
Command queue is useful when you have heavy traffic and come in danger of being disconnected because of "excess flood". Commands in the queue are executed one by one at fixed intervals (see comminterval).
commands interval
Interval in seconds the command execution is called. On every call a single command of the queue is processed.
advertising interval
Interval in seconds you want the advertise/signature/status line to be displayed in channels.
accept priv.message requests
If on then requests from private message windows are accepted, else they are ignored.
send mIRC notice on priv.message request
If on then a message is sent to those who make a file request in a private message window. The message tells them how to turn this off in mIRC.
list file name
This is the name of the "files list" which the script will send to a user on request. Typically it contains your nick and is type textfile (.TXT)
This file will be created automatically as described here.
NOTE: the name filelist.txt must not be used because this name is already used internally.
my alternative nicks
If you happen to use alternative nicks frequently, type them in here. This will only have effect on the listfile.
If you do not have alternate nicks then leave this empty.
debug mode
Displays function more detailed in the status window. (for my own - debugging - purpose, nice to view)


player radiobuttons

choose whether you want to play to channels or play audible on your own machine or both.
Channels button
see screenshot
Press it to open the channel options. There you enter the channels you send to and set the advertise (A), send (S), find reply (F) and play (P) options for each channel separate. PS stands for play short. This is an alternative player message, commonly shorter. P overrules the PS option.
Press the Save button to apply the changes on exit.
Custom button
Opens the message editor. More about this if you >klick here<

Customizeable messages and listfile header

All messages to channels and users (including colors) and the list file header can now be changed more easily by usage of defined tags and by defining own tags. It's as easy as typing the text itself.

Press the Custom Button on the Settings screen. A small editor will appear to edit your messages. Information is normally shown there. If you accidently deleted it, here it is again.

Back to Top!
 
 

Commands for the hosting user:

/runscript [fileshare] reset
Start the program and reset to default values.
This is done automatically if the script is started by any event and hasn't been initialized before.

/runscript [fileshare] compile
This is only needed when an initialisation breaks somehow. Compile first, then reset once more.

/runscript [fileshare] version
Types out the version identifier line to the status window.

/runscript [fileshare] end
Ends the program execution.
 

Commands for the remote user:

(replace "Yournick" by your actual nick)

@Yournick
- Sends the list file to the remote user.

!Yournick filename
- Request a download. If the number of simultaneous sends has reached its specified max, then the request will be added to the queue. If the queue is full, then the request is rejected.

!Yournick tsend filename
- Request a TDCC download. Faster but only for PIRCH users.

@Yournick-que
- Shows the downloader the position of each of his requests in the queue.

@Yournick-remove filename
- Removes the user's requests from the queue (if no filename is given, all the files are removed).

@find mask or @locator mask (equivalent)
- The function searches the filenames in filelist.txt for a given mask.
Mask can contain wildcards (?,*) and text in any order. Wildcards will be added if none given, spaces and underlines replaced by "?". Example: @find *cranberries*dreams*  (search for "dreams" from the cranberries - @find cranberries*dreams is the same)
IMPORTANT NOTE: I set the maximum of returned lines to 10 so far. Thus, to prevent flood, you should ALWAYS use the command queue when find is on (see Settings section in this document)!!

@Yournick-help
- Sends a brief commands overview to the user.

@Yournick-ver
- Shows the user the version number of FileShare you are running.

Files the script creates:

All these files can be found in the pirchdir \fileshare\ folder.

fileshare.ini

Settings/Options as they are loaded whenever you make a reset. This file can be edited from the control window.
paths.txt paths1.txt paths2.txt ...
Are used to find the path of each single file. They also contain the player information. (not of interest to the user) Do not edit!
filelist.txt
Is a list that contains file names only. It is also used internally only. Do not edit!
schneck_filelist.txt
(or whatever you have specified as the listfile name - see Settings section in this document)
Is the file being sent to other users on request. It contains full get commands (!yournick filename) and additional the size of each file in Bytes.
que.txt
Used internally for the queue. Not of interest to the user. Do not edit!
sends.txt
Used internally for the list of current sends. Same as above. Do not edit!
commands.txt
This file holds the command queue (if you use it). Do not edit!
stats.txt
Contains a set of settings and statistics.
- How many bytes and files were sent, how many broken sends.
- How many file requests in which channels
- How many full downloads of which files
- How many full downloads by which user
NOTE: this file is also used internally, so do not edit it!
custom.txt
User and channel messages. Edit if you like to.
temp.bat, temp.txt, temp1.txt... temppaths.txt
Temporary files.
listdirs.txt
Contains list directory information.

Known Problems, Bugs, Troubles I had

Here is a list of problems I encountered (to be continued...)
If anybody out there knows more than I know, feel free to mail me a little hint (not the sort: "UBastard,LearnSomethingAboutProgrammingBeforeUPublishRubbishLikeThis!" ;-)
Also I would be happy about some feedback, if you have other trouble than the described or don't have these at all!

• List generation runs very slow when I have lots of new files or moved them into new folders.

Yes, it is, because PIL's file handling is slow (part a disk caching problem I suppose). Despite this, a lot of string manipulation is involved here.
 
 
• I entered a path but the list is empty!

Check if your path contains spaces. If yes, change the path to DOS 8+3 format. This means: leave out the spaces, cut to 6 characters and add ~1 to the directory name (this will work in most cases - only if two names would be equal they are named ~1 ~2 ~3).
Example: dir name is c:\own files\ - you enter c:\ownfil~1\

It is also possible that you use another language Windows distribution which I didn't have a DOS Dir sample of. (there even were troubles with an english version) - If you think this is the case, please send me a mail and attach the temp2.txt file from your fileshare directory.
 
 

• I get multiple "I/O error 5" messages while the file data extraction runs.

Check if any of your files are write-protected. This especially is the case if you copied the files from a Compact Disc. Remove the write protection if you want to use the random player with these files. The script does never write to the files but Pirch requires them to be write-enabled.
 
 
• There comes an access violation error when I have closed the control window and want to re-open it by /runscript [fileshare] reset!
• Control panel does not open when I type /runscript [fileshare] reset

Yes. :)
try this: /compile [fileshare]   - then reset
 
 
• Script generates Access violations and sometimes PIRCH simply stops

This problem can be severe with Windows NT because it is very restrictive. But it simply cannot be solved because it is more a PIRCH bug. Most of these errors have no effect, though.

 
• There come various access violations that may PIRCH even stop accepting any input (while script continues to work normally)

I encountered this with windows NT. I am not sure if it even is the script's fault because I had these errors when I was not in a file exchange channel and was not sending, too. May be it's simply PIRCH that is not optimized very well with NT (by the way, NT generates far too much of these errors - everything works very well and it kills a program that seemed not to do any harm to the system)

 
• On reset, loading of the list is soooo slow or simply does hang up.

Right. Can be slow. Depends on your system circumstances. I found, if you join a channel before/while loading the list PIRCH can hang up.
I had less trouble with load stop when I first started the script and after that joined the mp3 channel
 
 
• Sometimes entries are added to the send list, but no DCC starts.

Seen this, watched it, don't really know where this comes from. AFAIK, it depends on the reciever, seems to be some incompatibility of the DCC send protocol. That's why I added a "delete" feature ;) - hit delete, the send list is cleaned up, but running DCC still continues. If you intend to let your server run stand-alone, set the lowcps limit quite high, let's say, 1500. This way, lost DCC is cleaned up after a reasonable time.
 
 
• Some mIRC people seem to have this "feature" that their client automatically sends a private message if they type !nick.

I, too, don't like to get requests in private message windows, but that "bug" forced me to make another event, that triggers a send when the request came that way.
I checked mIRC and found, this function can be turned off:
klick  File => Options - choose  Sounds => Requests
- there you uncheck the "send !nick file as private message" option
- then press OK

So, I added a new option: notice on priv.message request and accept priv.message requests
If you set proceed=0 then the requests will simply be ignored.
If you set notice=1 then the user will recieve a message like this:
Your mIRC "request in private message" option seems to be on. Some people don't like getting file requests in private windows.
Please turn that off (by choosing: File -> Options - doubleclick Sounds -> Requests -> uncheck "send !nick file as private message" -> hit OK) - then repeat your request in the channel window. Thank you :)

If you intend to change it, don't forget the smilie! ;-)


 
• The script is harddisk intensive, why didn't I make the send and queue lists using arrays:

Seems to be a bug of PIRCH98, at least on WinNT machines. Arrays of string didn't want to work, produced exception errors whenever the script wanted to read (!) their entries.
• Timers are killed when I part a channel!
• Some messages or sends seem to be "lost"

This is funny, but not a problem anymore. Timers will be re-animated as soon as the script is triggered once more by any !nick or @nick event (this happens frequently in mp3 channels).
If you are out of the channels and want to finish the command queue, wait a few seconds (two times command interval) and then simply klick a button on the console or type in /runscript [fileshare]
• Interference with other scripts you run

If you have other scripts installed, look at the event triggers: there must not be two events with the same trigger text. That's the sequence ON TEXT:<trigger text>:<#channel>: (example: with catninja there is a problem concerning the ON TEXT:@*: event)
If ever possible, change the events of the other script to make fileshare work. It is now a "standard" to use !nick filename for file requests and @nick-command for other functions (I don't know why people didn't take the same character for both, may be the mIRC programmers invented the !nick filename command). Because of this standardization it would not make sense to change the triggers of fileshare (to, say, @nick filename).
Again, I remind you to tell me your experience.

PolarGeek (the maker of PIRCH) recently said, he is working on a new release right now, so I'm looking forward to that, let's see what comes.

The main window (log view)

 

Settings/Options: main window

 

Channel options

 

What your events window should look like:
Back
 

drag/drop the folder into the playlist editor (move over folder symbol, hold mouse button down and move)
Back
 

sort the list

save it

Back