OS/2 Shareware BBS: 2 BBS

home *** CD-ROM | disk | FTP | other *** search

/ OS/2 Shareware BBS: 2 BBS / 02-BBS.zip / flink11.zip / FrexxLink.doc < prev next >

Wrap

Text File | 1995-09-14 | 78KB | 2,355 lines

FrexxLink Documentation by Björn Stenberg for Version 1.1 COPYRIGHT FrexxLink is Copyright (C) 1995 Björn Stenberg Permission to use, copy, and distribute this software and its documentation is hereby granted without fee, provided that the above copyright notice appear in all copies and that the copyright notice and this permission notice appear in supporting documentation. NO WARRANTY BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. CONTACT INFORMATION If you wish to contact me, I can be reached at the following addresses: FidoNet: 2:201/328 (BBS phone: +46-8-6121258 V34,CM) AmigaNet: 39:164/102 Email: Bjorn.Stenberg@sth.frontec.se Paper mail: Björn Stenberg Birger Jarlsgatan 93 B 113 56 Stockholm Sweden GENERAL DESCRIPTION FrexxLink is not actually a BBS system in the usual sense. A more accurate description is to call it an FPL interpreter with a lot of built-in functions useful for BBS system operators. A FrexxLink BBS system consists of a number of FPL scripts, interpreted by FrexxLink. Whatever you want your system to do you must write down in FPL files. I have designed FrexxLink not as the most easy-to-use or -setup system available, but instead with ultimate flexibility as my primary goal. Therefore, the functions available are pretty low-level and a lot of work is required of the sysop/FPL programmer in order to get a fully functional BBS system. The benefit of this is, of course, that you can make yourself a truly unique BBS. It's all up to you. There are many function calls being mentioned in this text. For a full documentation of all functions, see the end of this file. EXE/DLL FILE DESCRIPTIONS FrexxLink.exe The main exe file, containing all of the BBS specific code except for the Squish stuff. BjornEd.exe A simple full-screen message editor. Fwrap.exe A word-wrap program for wrapping messages into neat quotable text buffers. Max2Flink.exe A multi-purpose conversion utility, able to convert the Maximus/2 2.x USER.BBS file, the FILES.BBS files and to create sample message and file area arrays from Max's FILEAREA.CTL and MSGAREA.CTL files. FPL.DLL Frexx Programming Language. The FPL interpreter by Daniel Stenberg. DDE4SBS.DLL The shared Standard C library for IBMs C/Set compiler. Used by FrexxLink, BjornEd and Fwrap to keep their exe size down. MSGAPI32.DLL The Squish message base API by Scott Dudley. Routines for handling most of the message area stuff. P.DLL A protocol stack by Jyrki Salmi for Z- ,X- and Ymodem etc. P.exe Frontend for P.DLL. I like this better than using P.DLL directly from within the FrexxLink executable. It allows you to use something completely different, should you want to. THE TALE OF CREATION The first script controlled BBS I used was a system called WOP, created by Magnus Nilsbo. It was a pretty "normal" system, but it had more advanced screen codes than many other systems. It also allowed conditional execution based on arbitrary variables, which was way more than anything else I'd seen BBS software do (this was around 1988-89, I think). I used it passionately for some years but when I changed to OS/2 in the beginning of the 90's, I really didn't want to run a DOS system for my BBS. So I did like everyone else, I ran the only thing available: Maximus/2. Now don't get me wrong, Max is not a bad system. But it's a real bore when you're used to WOP like I was. In the meantime, my brother Daniel was starting to develop this text editor for the Amiga, called FrexxEd, with some friends. They wanted something more powerful than ARexx to control the editor, something like the GNU Emacs LISP system, only more modern. It quickly became obvious that C was the best language to use, simply because no other language is better known throughout the computer world. So Daniel started programming a script interpreter based on the C syntax and semantics, calling it the 'Frexx Programming Language', or FPL. In the beginning there were quite a lot of differences between FPL and C, but over the years FPL has adapted more and more of the 'real' C language. Today I'd say it is pretty close to the real thing. In the end of 1993, I was getting increasingly irritated by the feeling of having my arms tied behind my back by Maximus. The idea of creating my own system, using Daniel's FPL interpreter, started to form in my mind. I philosiphied a lot about it and Daniel and I talked quite a bit about how the system 'ought' to be. Finally, in the spring of 1994, I sat down and started to hack out the basics of the system. I ported FPL (done in a few minutes, that piece of code is one heck of a portable thing!) and set it up, I created the user file system and a lot of the basic function calls like getstring(), printf() and the support system for different character sets (which was something WOP had and I really really missed in Maximus), the file description field system and some other things. Then I started to look into the Squish API (because I didn't want to have to make my own tosser, scanner etc) and that was when I ran into this huge brick wall. I somehow never managed to get the 16-bit MSGAPI working properly with the rest of my 32-bit code. I worked for weeks, but eventually I ran out of ideas and found that I COULD NOT make it work. So the summer of 1994 became a summer of much sun and little code for me. I simply gave up, having tried everything I could think of and having asked everyone I could imagine having a clue. I put the whole thing on ice. Some months later (I don't know exactly when) Scott (the author of Squish) released a 32-bit version of the MSGAPI.DLL. I was quite put off by my previous poor experience with the thing, though, so I didn't try it out until around christmas time 1994. It was with extreme delight I found my test code was actually working with the new DLL. That was when FrexxLink really started to take form. I sat, nights at an end, programming. I had spent months that autumn, thinking how I would want the system to be "if just that **** API code would work for me". Now that it did work, I had merely to convert all my ideas and strategies into code and FPL scripts. I started with making a carbon-copy of the Maximus system I had running, so I'd know I had all the basic functionality and to make sure I didn't forget anything vital. That was completed in the middle of February '95 and after some extra tuning and (a lot of) FPL script hacking I finally converted my Maximus USER.BBS to FrexxLink user files on March 10, 1995. From that date on, I'm quite proud to say, FrexxLink has been running around the clock on my two-node system. FILES and DIRECTORIES FrexxLink never changes it's current directory. Therefore, all references to files and directories can always depend on the current directory being where FrexxLink was originally started. Here are descriptions of some notable files and directories used by FrexxLink: Users/ (directory) This is where all the user files are stored. Each file in this directory contains the information for one user. Users/xxxxx xxxxx (files) The user files are (as all FrexxLink files) simple text files, editable with any normal text editor. The file has the name of the user whose data is stored within the file. (i.e. user "Max Headroom" is stored in the file "Users/Max Headroom") Each line in a user file contains a variable, with the name of the variable as the first word and the value as the rest of the line, in the following format: "Password thisisme,reallyreally" Meaning that the string 'thisisme,reallyreally' is stored in a variable called 'Password'. The variable name cannot contain spaces or tabs, since those are used as delimiters. MsgMap/ (directory) This directory stores the message maps of all users. Each file in this directory contains the message maps of one user. The file has the same name as the user whose data it contains. MsgMap/Xxxxx Xxxxxx (files) This file contains a number of lines, one line for each message area the user has read messages in. The line consists of the area tag, a colon, and a list of the unique message id numbers of the messages in that area that have been read. Example: ---- FREXXLINK:2983,2999-3100,3123 *LOCALCHAT:202-302,305,308,312 ---- This file is loaded the first time a gotomarea() call is issued. It is created (and updated) each time the user leaves FrexxLink. It can also be updated at an earlier time by the calling the savemsgmap() function. The asterix (*) first on the line means that the user is a member of the area. .Files (file) This is the file description list for a file area. Actually, this name is not defined anywhere in FrexxLink, it's just the one I chose for the BBS I'm sending with the package as an example. You may call it anything you like. The description file contains one line for each file in the area, as this example shows: --- Filename for the masses.txt,UL:John Doe,DL:23,TX:Neat text thingy! FrexxLink.Zip,UL:Björn Stenberg,DA:19980923,TX:FrexxLink, VR version. --- Every line is divided into several 'fields'. A field consists of a two-character identifier, a colon, a string and a trailing comma. Ex: 'UL:Björn Stenberg,'. A field can therefore never contain a comma sign. The maximum line length is defined by your system memory. A few field identifiers are hard-coded into FrexxLink: 'TX:' is the file description displayed in file lists. This field must exist on all files in the file list or an error will occur. It may be empty, but it must exist. 'DA:' is an optional field specifying the file date in the format 'YYYYMMDD' (ex: '19950502' for 2 May 1995). If this field exists, it will override the file's creation date stamp as the date showed in the file lists. Also, if this field exists, newscan() will not have to examine the disk file for it's file date, thus speeding up the search for new files substantially. There are some exceptions to the file field rules, however: * To save some space, the filename field has no identifier and no colon. Instead it must always be the FIRST field on a line. * The 'TX:' field CAN contain comma signs, to allow file descriptions containing pretty much anything. To enable this, the TX field must always be the LAST field on every line. This means that everything put after the 'TX:' is considered part of the file description. Empty lines and lines beginning with a whitespace character are displayed as they are, with no parsing or interpretation whatsoever. In addition to those hard-coded fields above, I use some fields in my enclosed example BBS. These are just my choices and nothing enforced by FrexxLink. You may do however you like with these: 'DL:' is the number of times the file has been downloaded. 'UL:' is the name of the user who uploaded the file. FplErr.log (file) This file is created in the current directory whenever FrexxLink encounters a FPL script error. It is a simple log file, containing one error per line. If the file already exists when an error occurs, FrexxLink simply appends the new error line to the existing file. Lines with an asterix (*) between the time and the log message means the the error occured when running in "safe" mode. Several other files and directories are used by the enclosed example BBS system. However those are not required or at all known of by FrexxLink but are used by the FPL code. Examples are the Signatures/ directory, containing up to five signatures per user, or the OneLiners/ directory, containing one-line logon notes between users. CHARACTER SETS (This section is mainly aimed at non-english speaking countries like Sweden which has several major charsets for their national characters.) FrexxLink has internal support for four separate character sets. They are ISO 8859-1, IBM CodePage 437, IBM CodePage 850 and SIS-11 (7-bit ASCII with Swedish national chars where {[]}\| is). FrexxLink assumes all local data (FPL scripts, file descriptions etc.) are stored in CodePage 850. The reason for this is that CP850 contains all characters found in ISO 8859-1, only in scrambled order. Therefore CP850 is able to contain without distortion all ISO 8859-1 chars. And since ISO is the world-wide standard, that is not an altogether bad thing. This means that you must enter all text in FPL scripts and file descriptions as CP850 if you want your users to be able to read it properly after charset conversion. To cope with the problem of users with different charsets, you can set up FrexxLink to convert the user input and output. Also, you can alter FrexxLink's CP850 assumptions a bit, for example when you wish to display a message or a text file with another character set. Both these conversion settings are done with the charset() function call. FrexxLink also supplies a translate() function, allowing translation of strings from one charset to another. USER SYSTEM FrexxLink keeps data of one user in memory at a time. To load the user into memory, you use the loaduser() function. After that, you can access the user data with the functions getuservar() and setuservar(). To save any altered information or new user variables into the user file, use the saveuser() function. The first time a new user logs on, there is no file to load with his data in. In that case, clear the internal buffers using the inituser() function before starting to add variables. FILE AREA SYSTEM FrexxLink remembers only one file area at a time. You tell FrexxLink where the current areas file list is and what it's called, plus you tell it in what directory the actual files can be found. For this, you use the gotofarea() function call. After you've defined where the current area is, you can list all or a subset of the files using the filelist() function, you can search for files by date, using newfiles(), you can alter and read file fields, using setffield() and getffield(), you can remove a file from the file list, using fkill(), move a file to another list, using fmove() and so on. When you want to change file area, you simply issue another gotofarea() call. The upload/download system in the examle system depends on the protocol handler creating a log file in DSZ format. A dszfield() function is supplied by FrexxLink to facilitate the interpretation of such log files. All files listed, either using filelist() or newfiles() get a file tag, a number from 1 to 99. For each file listed, the tag is increased one step. At 99, the number starts at 1 again and continues upwards. The idea with this system is that the last 99 files listed by the user can always be accessed by a number rather than having to enter the full filename. You obtain what file a specific tag represents to by using the getftag() function. If you wish to reset the tag counter to 1 (I like to do that at the start of a new list, for example), use the clrftags() function. MESSAGE SYSTEM Currently, only the Squish message format is supported. JAM is suggested and will probably be implemented sometime soon. The message system concept is just like with the file areas. FrexxLink knows of one message area, set with gotomarea(). The difference is that with the message area, you tell FrexxLink the Squish base name for the area and the tagname for it. Note now that ALL areas in a FrexxLink system must have a tagname, including local and netmail areas. The reason for this is that the tagname is used in the MsgMap files to identify the area. Without a tag, FrexxLink would be unable to remember what messages has been read in what areas. The getmarea() function obtains information about the area, such as the number of messages etc. Message areas always start with message #1. The getmsg() function obtains part of a message, such as the subject, body text, creation date etc. Using this function with printf() and printmsg() (which displays a message body, wrapped and with coloured quotes) will allow you to read messages. The messages in Squish areas are stored in the order of tossing. However, using MSGID/REPLY linking, there is the possibility of linking message threads together to achieve threaded reading. The nextmsg() function is used to locate messages in thread order. FrexxLink keeps a message map of each area, consisting of one flag for every message in the area. This map is used to find out exactly which messages the user has read and which are still unread. The function markmsg() is used to modify this map and savemsgmap() can be used to store all the message maps to disk. If you do not use the savemsgmap() function, or if any message map is modified after your last savemsgmap() call, FrexxLink will save the message map file when exiting. In order to know the filename of the MsgMap file to read and write, you must supply the username (or whatever filename you wish to use) in the setuid() function before entering any message areas. A concept of area membership is supported by FrexxLink. The function msgmember() is used both to set and check area membership. Creating messages is one major thing about BBSing. The FrexxLink way of doing this is to first clear the internal message buffer using createmsg(). After that, you add parts of the message using putmsg() and putmsgflag() until you are satisfied, at which point you call sendmsg() to write the message to the Squish area. If you at any point wish to abort the message or start again, simply call the createmsg() function again and the buffer will be cleared. delmsg() removes a written message from the area. Currently, there are no functions for modifying an existing message. I intend to implement that soon, though. One of the message parts you may wish to put into the messages you send is the "control" part, containing kludges like MSGID and such. The only control information created by FrexxLink is a PID kludge, looking like "\1PID: FrexxLink X.X", where X.X is the current version. All other kludges you wish your system to send, you must put into the message yourself using 'putmsg("control",kludges)'. One of the more useful kludges is the MSGID kludge. It requires a uniqe number from the originating system. Therefore, a msgid() function is supplied by FrexxLink. EXCEPTION HANDLING There are some special occations that do not follow the normal flow of execution in the FPL files. These are handled using "callback functions" which basically are small FPL programs stored in FrexxLink for usage when required. Currently, two such exceptions exist. They are the more prompt at the end of the screen and something called the timeleft function, which is called every minute to let you check the user's time status and warn him, kick him out or whatever you wish to do. For the user time, a function called setusertime() makes life a little easier. FUNCTION REFERENCE ============================================================================== FPL Functions ============================================================================== FPL contains a number of internal functions that FrexxLink has no doing with, such as the strcmp(), the substr(), strstr() and so on. These functions are fully described in the FPLUser.doc document. ============================================================================== System Variables ============================================================================== NAME errno -- standard error variable TYPE int DESCRIPTION Holds the current error code. The possible error codes are: 0 No error. All is fine. -1 The user provided no input to a getstring() or getint() prompt, but hit enter right away. -2 A file related function failed to locate a requested file. ------------------------------------------------------------------------------ NAME sys_local -- is this a local logon? TYPE int DESCRIPTION Contains 1 if the current process is local only, or 0 if the serial communication is active. ------------------------------------------------------------------------------ NAME sys_comhandle -- what com handle is in use? TYPE int DESCRIPTION Holds the currently used com port handle. ------------------------------------------------------------------------------ NAME sys_timeleft -- how much time is there left? TYPE int DESCRIPTION Holds the number of seconds until the user time is up. SEE ALSO setusertime() ------------------------------------------------------------------------------ NAME sys_version -- the version number of FrexxLink TYPE string DESCRIPTION Holds the version number of the FrexxLink being run. The string is in format "version.revision", ex "1.0". ------------------------------------------------------------------------------ NAME fpl_version -- the version number of FPL.DLL TYPE string DESCRIPTION Holds the version number of the FPL.DLL being used. The string is in format "version.revision", ex "13.2". ------------------------------------------------------------------------------ NAME sys_safemode -- are we running in "safe" mode? TYPE int DESCRIPTION Contains 1 if running in "safe" mode, or 0 if running in normal mode. SEE ALSO runsafe() ============================================================================== Programming Functions ============================================================================== NAME getstring -- Retreive a string from user SYNTAX string getstring( [ string Prompt ], [ int Display ] ); DESCRIPTION Retrieves a string from the user, allowing primitive command line editing using BACKSPACE. PARAMETERS If Prompt is supplied, it will be displayed before the user can enter any input. If Display is supplied, it controls what will be echoed back from the user's keypresses. A value of 0 will inhibit any echoing. A value of -1 will echo the actual input characters and any other value will be used as the echo eharacter. If the Display parameter is omitted, -1 is assumed. You cannot supply Display without also supplying Prompt. If you wish to alter the display mode without displaying a prompt, use "" for the Prompt parameter. RETURNS The string entered by the user. If the user entered nothing, errno will be set to -1. SEE ALSO getint(), getchar(), getkey() ------------------------------------------------------------------------------ NAME getint -- Retreive an integer from user SYNTAX int getint( [ string Prompt ], [ int Display ] ); DESCRIPTION Retrieves an integer from the user, allowing primitive command line editing using BACKSPACE. PARAMETERS If Prompt is supplied, it will be printed before the user can enter anything. If Display is supplied, it controls what will be echoed back from the user's keypresses. A value of 0 will inhibit any echoing. A value of -1 will echo the actual input characters and any other value will be used as the echo eharacter. If the Display parameter is omitted, -1 is assumed. RETURNS The integer entered by the user. If the user entered nothing, errno will be set to -1. SEE ALSO getstring(), getchar(), getkey() ------------------------------------------------------------------------------ NAME getchar -- Retreive a character from user SYNTAX int getchar( [ string Prompt ], [ int Display ] ); DESCRIPTION Retrieves a character from the user. PARAMETERS If Prompt is supplied, it will be printed before the user can enter anything. If Display is supplied, it controls what will be echoed back from the user's keypresses. A value of 0 will inhibit any echoing. A value of -1 will echo the actual input characters and any other value will be used as the echo eharacter. If the Display parameter is omitted, -1 is assumed. RETURNS The value of the character pressed by the user. SEE ALSO getstring(), getint(), getkey() ------------------------------------------------------------------------------ NAME getkey -- Retreive a character from the input queue SYNTAX int getkey( void ); DESCRIPTION Retrieves a character from the input queue without waiting for input. RETURNS The first character in the input queue, or -1 if the input queue is empty. SEE ALSO getstring(), getint(), getchar() ------------------------------------------------------------------------------ NAME loadstring -- load a text file into a string SYNTAX string loadstring( string File ); PARAMETERS File must be a fully qualified filename, reachable and readable by the current process. SAFE MODE In "safe" mode, any path specified in the filename is ignored. The file is loaded from the directory specified by runsafe(). RETURNS The created string. If the file could not be found, the string is set to "" and errno is set to -2. SEE ALSO savestring() ------------------------------------------------------------------------------ NAME savestring -- save a string as a text file SYNTAX void savestring( string String, string File [, int Mode] ); PARAMETERS String is the string to be written File must be a fully qualified filename, reachable and writable by the current process. Mode is the "write mode", which is: 0 for normal, nonfiltered writing, which is the default 1 for "message filter mode", which does two things: a) Replaces all LF chars with SPACE (0x20) b) Truncates the message at the first occurence of "SEEN-BY: " SAFE MODE In "safe" mode, any path specified in the filename is ignored. The file is saved to the directory specified by runsafe(). NOTES If String is 0 bytes long, the File is removed. SEE ALSO loadstring(), fappend(), fprepend() ------------------------------------------------------------------------------ NAME loadarray -- load a text file into an array of strings, one string per line SYNTAX int loadarray( string File, string& Array[] ); PARAMETERS File must be a fully qualified filename, reachable and readable by the current process. Array must be a reference to a string array. The size of the array does not matter, since FrexxLink will expand the array enough to hold the file. SAFE MODE In "safe" mode, any path specified in the filename is ignored. The file is loaded from the directory specified by runsafe(). RETURNS The size (number of elements) of the expanded string array, or -1 if the file was not found. SEE ALSO loadstring() ------------------------------------------------------------------------------ NAME savearray -- save am array of strings as a text file SYNTAX void savearray( string& Array[], string File, [ int Elements ] ); PARAMETERS Array is a reference to an array of strings to be saved File must be a fully qualified filename, reachable and writable by the current process. Elements is an optional number of elements to write. If this parameter is omitted, all elements in the array are written. SAFE MODE In "safe" mode, any path specified in the filename is ignored. The file is saved to the directory specified by runsafe(). SEE ALSO loadarray(), savestring(), loadstring(), fappend(), fprepend() ------------------------------------------------------------------------------ NAME toupper -- Convert a character to uppercase SYNTAX int toupper( int Char ); DESCRIPTION Converts a character to uppercase. If Char is not a letter, no change will be made. Unlike the standard C equivalence, this function also converts 8-bit local characters properly. RETURNS The value of the converted character. ------------------------------------------------------------------------------ NAME runfile -- Executes an FPL file. SYNTAX void runfile( string Filename ); DESCRIPTION Executes an FPL file. RETURNS Nothing SEE ALSO runsafe() ------------------------------------------------------------------------------ NAME runsafe -- Executes an FPL file in "safe" mode. SYNTAX void runsafe( string Filename, string UserPath ); DESCRIPTION Executes an FPL file with all potentially "dangerous" functions disabled in the FPL interpreter. Calling the disabled functions is still possible, but the functions will not do anything. Disabled functions are: fappend, fprepend, ffindfirst, ffindnext, fmove, fkill, fdelete, frename, getffield, setffield, gotofarea, newfiles, filelist, typefile, dszfield, inituser, loaduser, saveuser, setuservar, setsysvar, setuid, runfile, runsafe, setfunc, gotomarea, getmarea, delmsg, getmsg, printmsg, nextmsg, savemsgmap, msgmember, markmsg, createmsg, sendmsg, putmsgflag, getmsgflag, setmareasize, putmsg, setusertime, settimeout, charset, system, bye In addition to these disabled functions, some functions are functionally limited when called in "safe" mode. UserPath is where all calls to load/savestring and load/savearray will read/write their files. It should be a fully qualified path WITHOUT trailing backslash. RETURNS Nothing SEE ALSO runfile(), sys_safemode ------------------------------------------------------------------------------ NAME printf -- formatted output SYNTAX void printf( string Format, [ ... ] ); DESCRIPTION printf() produces formatted output. It behaves pretty much exactly like the C printf() function, except that floating point numbers aren't supported. (This description is not complete, but just explains the basic aspects of printf().) To take it short, printf() checks the Format string for percent signs (%). Everywhere there's a % char, printf will output something special. What, and how to output it depends on the characters immediately following the %: %d print an integer in base 10 %s print a string %x print an integer in base 16 (hexadecimal) %% print a percent sign Also, there are some flags and parameters that can be used to define how to format the field: %5s print the string to at least 5 characters length. If the string is shorter, the output will be padded with space to the left of the string. (right justified) %-5s same as above, but put the padding spaces to the right of the string. (left justified) %5d print an integer to at least 5 characters length, left justified %05d print an integer to at least 5 characters length, right justified but padded with zeros instead of spaces. Example: printf( "%d %s were printed at %02d:%02d\n",5,"dots",10,3) will output the string '5 dots were printed at 10:03\n'. RETURNS 1 if a MorePrompt() was answered negatively, i.e the user wants the output to stop. 0 in all other cases. SEE ALSO lprintf(), sprintf() ------------------------------------------------------------------------------ NAME lprintf -- local formatted output SYNTAX void printf( string Format, [ ... ] ); DESCRIPTION lprintf() produces formatted output on the local console only. It works just like printf() in all other aspects. RETURNS Nothing SEE ALSO printf(), sprintf() ------------------------------------------------------------------------------ NAME sprintf -- formatted string SYNTAX string sprintf( string Format, [ ... ] ); DESCRIPTION sprintf() is exactly like printf(), except that it returns the resulting string to FPL instead of displaying it on the user screen. RETURNS The created string SEE ALSO printf(), lprintf() ------------------------------------------------------------------------------ NAME setfunc -- set system function SYNTAX void setfunc( string FuncId, string Code ); DESCRIPTION Defines the action of the predefined system functions PARAMETERS FuncId is one of the following functions: "moreprompt" When the screen is filled with scrolling text, a "More? (Y/n)" prompt is generally appreciated by the average user. This function defines what that prompt should do. "timeleft" is called once every minute. Use it to keep track of the user's time, warn him when it's running short and to kick him out when time is up etc. Code is a complete FPL statement to execute as the function. It is recommended to use a function call here, rather than a complicated routine. IMPORTANT: All functions called from within these system FPL functions must be 'export' declared! RETURNS Nothing SEE ALSO sys_timeleft, screenlen() ------------------------------------------------------------------------------ NAME clear -- clear line counter SYNTAX void clear( [ int ClearScreen ] ); DESCRIPTION In order to know when to execute the more prompt, a line counter is maintained internally by FrexxLink. This function clears that counter, so that it will take a screenfull of lines to trigger the more prompt again. PARAMETERS If ClearScreen is 1, the screen clear escape code will be sent. RETURNS Nothing SEE ALSO screenlen(), setfunc() ------------------------------------------------------------------------------ NAME colour -- obtain the escape sequence to change text color SYNTAX string colour( string Colour ); DESCRIPTION Returns the ANSI standard escape sequence needed to change the text colour. PARAMETERS Colour A string describing which colour is desired. The string must be one of the following (case insensitive): black, red, green, brown, blue, magenta, cyan, gray, dgray, lred, lgreen, yellow, lblue, lmagenta, lcyan, white. The 'l' in 'lblue' etc means light and the 'd' in 'dgray' means dark. RETURNS The escape sequence SEE ALSO gotoxy() ------------------------------------------------------------------------------ NAME gotoxy -- position cursor on the screen SYNTAX void gotoxy( int Xpos, int Ypos ); DESCRIPTION Sends the ANSI standard escape sequence to position the cursor on screen. PARAMETERS Xpos the column on which the cursor is desired. The leftmost column on the screen is number 0. Ypos the line on which the cursor is desired. The topmost line on the screen is number 0. RETURNS Nothing SEE ALSO colour() ------------------------------------------------------------------------------ NAME system -- execute external command SYNTAX int system( string CmdLine ); DESCRIPTION Executes an external command such as an editor, protocol handler etc. PARAMETERS CmdLine is the command line to be executed. RETURNS The returncode of the executed command ------------------------------------------------------------------------------ NAME translate -- translate string from one charset to another SYNTAX string translate( string Str, int FromSet, int ToSet ); PARAMETERS Str is the string to be translated FromSet is the charset to convert from ToSet is the charset to convert to 1 = CodePage 850 2 = CodePage 437 3 = ISO 8859-1 4 = Swedish ASCII RETURNS The translated string SEE ALSO charset() ------------------------------------------------------------------------------ NAME fappend -- append string to a file SYNTAX void fappend( string File, string Str ); DESCRIPTION Appends a string to a file. It does not add a newline to the string, so if you want one you must include it in the string. PARAMETERS File the path+name of the file to modify Str the string to append to the file RETURNS Nothing SEE ALSO savestring(), fprepend() ------------------------------------------------------------------------------ NAME fprepend -- prepend string to a file SYNTAX void fprepend( string File, string Str ); DESCRIPTION Prepends a string to a file. I.e it works just like fappend() only it puts the line at the top of the file instead of at the bottom. PARAMETERS File the path+name of the file to modify Str the string to append to the file RETURNS Nothing SEE ALSO savestring(), fappend() ------------------------------------------------------------------------------ NAME fexists -- check if a file exists SYNTAX int fexists( string File ); PARAMETERS File the filename to look for. RETURNS 1 if the file exists. 0 if it doesn't. ------------------------------------------------------------------------------ NAME ffindfirst -- find the first directory entry matching a pattern SYNTAX string ffindfirst( string Pattern, [ string Attribs ] ); PARAMETERS Pattern is the file pattern to look for. Ex: "C:\\FrexxLink\\*.exe". Attribs is a string describing what kind of files you wish to find. Each character in the string represents one flag: 'h' include hidden files in the search 's' include system files in the search 'd' include directory entries in the search 'H' search for hidden files only 'S' search for system files only 'D' search for directory entries only 'A' search for archive files only 'R' search for read-only files only RETURNS The name of the found file, or "" if no matching file was found. SEE ALSO ffindnext() ------------------------------------------------------------------------------ NAME ffindnext -- find the next directory entry matching a pattern SYNTAX string ffindnext(); PARAMETERS None RETURNS The name of the found file, or "" if no more matching files could be found. SEE ALSO ffindfirst() ------------------------------------------------------------------------------ NAME fdelete -- delete a file from disk SYNTAX void fdelete( string Filename ); PARAMETERS Filename the name of the file to be deleted RETURNS Nothing SEE ALSO fkill(), frename(), fmove() ------------------------------------------------------------------------------ NAME frename -- rename a file to a new name SYNTAX void frename( string Oldname, string Newname ); PARAMETERS Oldname the name of the file to be renamed Newname the new name of the file RETURNS Nothing NOTES Supplying a path with the new filename will move the file to a new directory. This will only occur if the assigned directory is on the same disk/partition as the old file. SEE ALSO fmove() ------------------------------------------------------------------------------ NAME getenv -- get environment variable SYNTAX string getenv( string Variable ); DESCRIPTION Obtains an environment variable from the parent shell. (The 'SET' variables in an OS/2 CMD session.) PARAMETERS Variable is the name of the variable to get RETURNS The value of the variable if it exists, or "" if it doesn't. SEE ALSO getuservar() ------------------------------------------------------------------------------ NAME tokstr -- tokenize string SYNTAX string tokstr( string Source, int PartNo [, string Delimiters ] ); DESCRIPTION Copies part of the source string, based on the delimiters and PartNo. PARAMETERS Source the source string from which to copy the substrings PartNo the ordinal number of the part to copy. The first part is number 1. Delimiters a string containing the delimiter chars used in Source to separate the parts. The default is ";". RETURNS The copied string, or "" (null length string) if no part was found. ------------------------------------------------------------------------------ NAME sort -- sort an array of strings SYNTAX void sort( string& Array[] ); DESCRIPTION Sorts the array in ASCII order. PARAMETERS Array a reference to the array of strings to sort. RETURNS Nothing ------------------------------------------------------------------------------ NAME parsecmnd -- parse a command line in KOM-style fashion SYNTAX string parsecmnd( string Line, string& Commands[] ); DESCRIPTION Parses a command line, looking to match the line to a single command, as given in the Commands array. The string matching is done character by character, until either the command ends or a space is encountered. Given the commands "search new files" and "search next file", the string "s n f" will match both commands while the string "s nex f" only will match the second. PARAMETERS Line The command line to be parsed. Commands A reference to an array of accepted commands. RETURNS A string containing the index numbers of the matching commands separated by commas, or "" if no string matched. EXAMPLE 1 (short) string commands[2] = { "go home","go back" }; string index; /* this is how you call parsecmnd(): */ index = parsecmnd("go",&commands); /* index will now contain the string "0,1,", since both "go back" and "go home" are matched by the string "go". */ index = parsecmnd("g b",&commands); /* index will now contain the string "1,", since only "go back" is matched by the string "g b". Note how the word 'go' is prematurely terminated using a space character. Had there been a command in the array starting with, say, 'get' the 'g b' string would have been ambigous since 'g ' could have meant either 'go' or 'get'. */ EXAMPLE 2 (long) /* declare variables */ string commands[5] = { "go home","go back","loot","lurk","sleep" }; string input,index; /* ask user for string */ input = getstring("Enter command: "); /* parse string and match it to the commands */ index = parsecmnd(input,&commands); /* did user enter any known command? */ if(!strlen(index)) printf("\nUnknown command '%s'.\n",input); else { /* did we match more than one command? */ /* (check for a second value in index string) */ if (atoi(tokstr(index,2,','))){ int i; string s; printf("\nAmbigous input '%s' matches the following:\n",input); for(i=1;;i++){ s=tokstr(index,i,','); /* if s=="" then we're out of indexes */ if(!strlen(s)) break; printf("%s\n",commands[atoi(s)]); } } else { switch(command[atoi(index)]){ case "go home": printf("Go home!\n"); break; case "go back": printf("Go back!\n"); break; default: printf("Not implemented! :-)\n"); break; } } } ------------------------------------------------------------------------------ NAME bye -- quit frexxlink SYNTAX void bye( void ); DESCRIPTION Quits FrexxLink immediately. Using the keyword 'exit' only stops the current FPL file, which does not always exit FrexxLink. The timeout function, for example, runs as a separate FPL session and issuing an 'exit' in there only exits the timeout function, and does not exit FrexxLink. Use bye() instead to achieve a complete exit. RETURNS It doesn't return. FrexxLink exits. ------------------------------------------------------------------------------ NAME random -- get a random value SYNTAX int random( void ); DESCRIPTION Creates a properly randomized value between 0 and 999. This function is seeded when FrexxLink is started, using the system's millisecond counter as seed. The proper spread of values can be checked with the supplied FPL test program 'RandomTest.FPL'. RETURNS The random value ------------------------------------------------------------------------------ NAME sleep -- suspend execution for a certain amount of time SYNTAX void sleep( int Milliseconds ); DESCRIPTION Suspends the system for the specified number of milliseconds. If this function is called in "safe" mode, the maximum allowed sleep time is 10 seconds (10000 milliseconds). RETURNS Nothing ============================================================================== User Functions ============================================================================== NAME inituser -- create a new user SYNTAX void inituser( void ); DESCRIPTION This function clears all internal structures of any previous user and sets up the basis for a new user. RETURNS Nothing SEE ALSO loaduser(), saveuser() ------------------------------------------------------------------------------ NAME loaduser -- load a user file from disk SYNTAX int loaduser( string Username ); DESCRIPTION Loads a user file from the "Users" directory. PARAMETERS Username is the username (and filename) of the user to load. It is not case sensitive. RETURNS 0 if the user was found, or -1 if it wasn't. SEE ALSO inituser(), saveuser() ------------------------------------------------------------------------------ NAME saveuser -- save a user file to disk SYNTAX int saveuser( String Username ); DESCRIPTION Saves a user to disk in the "Users" directory. PARAMETERS Username is the name of the user to save. It is not case sensitive. RETURNS 0 if the user was saved correctly, or -1 if the file could not be created. SEE ALSO inituser(), loaduser() ------------------------------------------------------------------------------ NAME setuid -- set user identification string SYNTAX void setuid( string Username ); PARAMETERS Username is the name of the user, or whatever string is desired to use for identifying which file in the MsgMap/ directory thath should be used as data file for which messages has been read. RETURNS Nothing SEE ALSO getuid(), markmsg() ------------------------------------------------------------------------------ NAME getuid -- get user identification string SYNTAX string getuid( void ); RETURNS The string sent with setuid(), or "" if no calls to setuid() has been made. SEE ALSO setuid() ------------------------------------------------------------------------------ NAME getuservar -- get user variable SYNTAX string getuservar( string VarName ); PARAMETERS VarName is the name of the user variable. It is not case sensitive. RETURNS The string SEE ALSO setuservar(), getenv(), getuid() ------------------------------------------------------------------------------ NAME setuservar -- set user variable SYNTAX void setuservar( string VarName, string Value ); PARAMETERS VarName is the name of the user variable. It is not case sensitive. Value is what the user variable is assigned. Case is preserved. RETURNS Nothing SEE ALSO getuservar(), setuid() ------------------------------------------------------------------------------ NAME charset -- set charset conversion SYNTAX void charset( int UserSet, int DataSet ); DESCRIPTION Internally, FrexxLink handles all text as CodePage 850. In order to supply proper charset conversion for things like messages and such, it is necessary set the charset used. PARAMETER UserSet specifies the user's charset. DataSet specifies the charset used in the current message area. RETURNS Nothing SEE ALSO translate() ------------------------------------------------------------------------------ NAME screenlen -- get/set user screen length SYNTAX int screenlen( [ int Lines ] ); PARAMETERS Lines is the number of lines on the user's screen. By supplying this parameter, the previous value will be overwritten. However, altering the screen length is not allowed in "safe" mode. RETURNS The number of lines per screen. SEE ALSO setfunc(), clear() ------------------------------------------------------------------------------ NAME setusertime -- set the amount of user time left SYNTAX void setusertime( int Seconds ); DESCRIPTION This functions sets the amount of time for the current user. Every time the minute count "clicks" down, the system FPL function "timeleft" is called. PARAMETERS Seconds is the number of seconds until the user time is up. RETURNS Nothing SEE ALSO setfunc(), sys_timeleft ============================================================================== Message Area Functions ============================================================================== NAME gotomarea -- set current message area SYNTAX int gotomarea( string Tag, string Path ); DESCRIPTION Sets the internal "cursor" to the specified area. All subsequent message functions are applied to this area. PARAMETERS Tag is the area tag, used in the MsgMap file for marking read messages. Path is the path+base filename to the squish data files for this area. RETURNS -1 if the call failed. 0 otherwise. ------------------------------------------------------------------------------ NAME getmarea -- get information about current message area SYNTAX int getmarea( string Id ); PARAMETERS Id is the information identifier: "total" the total number of messages in the area. "unread" the number of unread messages in the area. "highest" the number of the highest message in the area. RETURNS SEE above. ------------------------------------------------------------------------------ NAME getmsg -- get a subpart of a message SYNTAX string getmsg( int MsgNo, string PartId [, int ReplyNo] ); PARAMETERS MsgNo specifies which message to read from. PartId specifies which part of the message to fetch: "body" - the message body, truncated below the first occurence of " * Origin: ". "from" - the 'From' field "to" - the 'To' field "subject" - the 'Subject' field "origaddr" - the originating 4D address (Zone:Net/Node.Point) "destaddr" - the destination 4D address (Zone:Net/Node.Point) "date" - the creation date of the message (YY-MM-DD HH:MM) "replyto" - the message number this message is a reply to, or 0 if this message isn't a reply "control" - the ^A kludges of the message. Each SOH (0x01) is replaced with a newline character. "replies" - the message number(s) of the replies to this message. This is where the ReplyNo parameter comes in. It specifies which reply to check for, starting with #1. There can be a maximum of 10 replies to every message. This function RETurns "0" if there is no reply with the specified number. Replies are always stored 1->10, so once you find a 0 it's no use checking the rest of the replies. RETURNS See above ------------------------------------------------------------------------------ NAME printmsg -- display message body with quote colouring and word wrapping SYNTAX void printmsg( string Body, string QuoteCol, string TextCol ); DESCRIPTION FidoNet messages can be somewhat messy to handle, so here's a function that does all that neat formatting and colouring stuff for you. It replaces all LF (0x0a) characters whith SPACE (0x20) and then outputs each paragraph (i.e. lines separated with CR (0x0d)) neatly wrapped. All paragraphs having a '>' character in the first 10 characters are considered quoted and are thus prefixed with the QuoteCol string. All "normal" text paragraphs immediately following a quote are prefixed with the TextCol string. PARAMETERS Body - The body of a message QuoteCol - The escape sequence (or whatever) for the quoted lines colour TextCol - The escape sequence for normal lines RETURNS Nothing ------------------------------------------------------------------------------ NAME nextmsg -- Find next unread message in thread SYNTAX int nextmsg( int Message ); DESCRIPTION Finds the next unread message. PARAMETERS If Message is a valid message number, nextmsg() will scan Message's thread for an unread reply. If Message is -1, nextmsg() will scan for the first unread message in the area. RETURNS Next unread message number. If the thread is exhausted, nextmsg() RETurns -1. If the area is exhausted, nextmsg() returns 0. ------------------------------------------------------------------------------ NAME markmsg -- check read mark for message SYNTAX int msgmsg( int MsgNo [, int Set ] ); PARAMETERS MsgNo is the number of the message to check Set is an optional flag which changes the value of the mark: 0 marks the message as unread 1 marks the message as read -1 does not modify the mark (default) RETURNS 0 if the message is marked as unread, otherwise 1. ------------------------------------------------------------------------------ NAME savemsgmap -- store map of read messages SYNTAX void savemsgmap( void ); DESCRIPTION Stores a map of read messages in the "MsgMap" directory, in a filename as set by the setuid() function. RETURNS Nothing ------------------------------------------------------------------------------ NAME createmsg -- clear all internal message structures SYNTAX void createmsg( void ); DESCRIPTION Clears all stuff internally used for sending messages. Use this before putmsg()ing stuff. RETURNS Nothing ------------------------------------------------------------------------------ NAME putmsg -- assign message part value SYNTAX void putmsg( string PartId, string Value ); DESCRIPTION Adds part of a message to the internal message buffer. PARAMETERS PartId is the part which is to be assigned: "body" - the message body "from" - the 'From' field "to" - the 'To' field "subject" - the 'Subject' field "origaddr" - the originating 4D address (Zone:Net/Node.Point) "destaddr" - the destination 4D address (Zone:Net/Node.Point) "control" - the ^A kludges of the message, with SOH (0x01) characters positioned correctly. FrexxLink does not alter this field in any way before sending it, so it's all up to you! Value is the value to set. RETURNS Nothing ------------------------------------------------------------------------------ NAME putmsgflag -- set message flags SYNTAX void putmsgflag( string FlagId, int Value ); PARAMETERS FlagId is the flag identifier: "private", "crash", "read", "sent", "file", "forward", "orphan", "kill", "local", "hold", "freq", "rreq", "receipt", "ureq", "scanned", "uid", Value is 0 if the flag is to be cleared, or 1 if the flag should be set. RETURNS Nothing ------------------------------------------------------------------------------ NAME getmsgflag -- get message flags SYNTAX int getmsgflag( int MsgNo, string FlagId ); DESCRIPTION Checks if a message contains a specific flag. PARAMETERS MsgNo is the number of the message to be examined FlagId is the flag identifier: "private", "crash", "read", "sent", "file", "forward", "orphan", "kill", "local", "hold", "freq", "rreq", "receipt", "ureq", "scanned", "uid", RETURNS 1 if the flag is set. 0 otherwise. ------------------------------------------------------------------------------ NAME sendmsg -- write message to message base SYNTAX void sendmsg( void ); RETURNS Nothing ------------------------------------------------------------------------------ NAME msgid -- create new MSGID SYNTAX int msgid( void ); DESCRIPTION This function creates a new message ID of the type you are required to put into your FidoNet messages. The FTS-09 document specifies that no two messages from a system may contain the same MSGID for at least three years. I have solved this by counting the time passed since the last 5-year shift, in 1/10th of seconds. That means that my counter reset last time 1995-01-01 00:00 and is increasing constantly at a speed of 864000 clicks per day. Even with this speed, the counter will not wrap for about 13 years, so I think we're on the safe side. RETURNS The message id. ------------------------------------------------------------------------------ NAME msgmember -- check area membership SYNTAX int msgmember( [ int Flag ] ); DESCRIPTION FrexxLink supports the concept or area membership. This function controls whether the current user (as specified with setuid()) is a member of the current area (as specified with gotomarea()) or not. PARAMETERS Flag is an optional parameter, changing the state of membership: 0 clears the member flag 1 sets the member flag -1 does not modify the member flag (default) RETURNS The state of membership for the area. ------------------------------------------------------------------------------ NAME delmsg -- delete a message SYNTAX void delmsg( int MsgNo ); DESCRIPTION Deletes a message from the message base. PARAMETERS MsgNo is the number of the message to delete. RETURNS Nothing ------------------------------------------------------------------------------ NAME setmareasize -- define maiximum size of a message area SYNTAX void setmareasize( int MaxSize ); DESCRIPTION Sets the maximum size of the current message area. The tosser will start throwing away old messages when this number is reached. You only need to call this function when you wish to modify the maximum size of the area. PARAMETERS MaxSize is the maximum number of messages in the area. RETURNS Nothing ============================================================================== File Area Functions ============================================================================== NAME gotofarea -- set current file area SYNTAX void gotofarea( string ListPath, string FilePath ); DESCRIPTION Defines the current file area. All subsequent file area functions will use this setting PARAMETERS ListPath is the path and filename to the list file for this area. FilePath is the path to where the actual files of this area are stored. RETURNS Nothing ------------------------------------------------------------------------------ NAME filelist -- list files in current file area SYNTAX int filelist( [ string Type ], [ string Field ], [ string Key ] ); DESCRIPTION Lists files in the current directory, all or a selected few. If searching is enabled, this function will output two newlines before the first file match is printed. PARAMETERS If no parameters are supplied, this function will list all files as they are listed in the list file, including comments and separator lines. Type controls what kind of searching is to be done. Possible parameters are "string" and "date". If Type is set to "date", the Field and Key parameters are not required. Field if "string" is chosen as search type, this field is used to define which string field is to be searched for matching text. Setting this PARAMeter to "TX" will actually search both the "TX" field and the filename. This parameter is case sensitive. Key is the string to search for in the field specified by Field. It is not case sensitive. RETURNS 1 if the user has pressed Ctrl-C. 0 otherwise. ------------------------------------------------------------------------------ NAME newfiles -- search for files newer than a specific date SYNTAX int newfiles( int Date ); DESCRIPTION Scans current file area looking for files not older than Date. If there exists a field 'DA' on a file description line, newscan() uses the date specified in that field. Otherwise, newscan() examines the file on the disk and obtains the creation date. PARAMETERS Date the time in integer format, i.e. seconds from 1970. RETURNS 1 if the user has pressed Ctrl-C. 0 otherwise. ------------------------------------------------------------------------------ NAME typefile -- display a text file onscreen SYNTAX int typefile( string Filename ); PARAMETERS Filename the path+filename of the file to display. RETURNS -1 if the file was not found. 0 if all is fine. ------------------------------------------------------------------------------ NAME fileinfo -- get specifics about a disk file SYNTAX int fileinfo( string Filename, string Field ); PARAMETERS Filename the path+filename of the file to examine. Field a string describing what information is requested: "size" the size of the file in bytes. "time" the creation time of the file, as an integer. RETURNS The result examination, or -1 if the file was not found. ------------------------------------------------------------------------------ NAME dszfield -- parse a dszlog type file SYNTAX string dszfield( string DszLog, int Line, string Field ); DESCRIPTION Many transfer protocols produce a result log in the format defined by the DSZ software. This is a convenience function to decipher such a log file. PARAMETERS DszLog the path+filename of the DSZ-style log file Line the line number to examine. Each file transfered in a batch gets a line of its own, so this parameter simply says which file in order you wish to examine. Field the information field requested: "protocol" a one character string describing the protocol used in transfer. An upper case character means upload, lower case download. 'z' and 'Z' are used for Zmodem. 'x' and 'X' are used for Xmodem. 'e' and 'E' are used to signal that the transfer was unsuccessful (a fatal error occured). "fsize" the size of the transfered file in bytes "dte" the dte (computer to modem) speed "cps" the achieved transfer speed i bytes per second "errors" the number of non-fatal errors during the transfer "stops" the number of transfer stops occured "psize" the packet size used (for Xmodem and other packet oriented protocols. Zmodem does not use packets). "file" the (path and) name of the file transferred "serial" the serial number of the remote protocol handler RETURNS The requested field. NOTES Use the protocol field to check the number of lines. If the protocol is "" (zero length string) that means there are no more files in the log. ------------------------------------------------------------------------------ NAME splitpath -- split a path+file string into path and filename SYNTAX string splitpath( string FullName, string Field ); DESCRIPTION Copies either the path or the filename out of a full path+filename string. The algorithm used is to locate the last '\' character in the string and consider the filename to begin at the next character. Everything before that is the path. PARAMETERS FullName the path to be split. ex: "C:\FrexxLink\Top.FPL" Field the part requested: "path" the path, WITHOUT trailing backslash "file" the filename RETURNS The requested field. ------------------------------------------------------------------------------ NAME clrftags -- clear file tags SYNTAX void clrftags( void ); DESCRIPTION Clears the internal file tags and resets the tag counter to 1. PARAMETERS None RETURNS Nothing ------------------------------------------------------------------------------ NAME getftag -- get a file tag SYNTAX string getftag( int TagNo ); DESCRIPTION The tag list FrexxLink keeps consists of 99 path+file strings, containing the last 99 files listed using filelist() and newfiles(). getftag() copies one of those tag strings. PARAMETERS TagNo the number of the tag you wish to get. RETURNS The tag string, if TagNo is the number of a tag that actually exists. Otherwise, an empty string ("") is returned. SEE ALSO clrftags() ------------------------------------------------------------------------------ NAME getffield -- get file description field SYNTAX string getffield( string Filename, string Field ); DESCRIPTION Every file description line consists of several file fields. getffield() RETurns the value of a field for a specific file. The description file used is the one specified with gotofarea(). PARAMETERS Filename the name of the file whose description contains the field Field the two-character field name to look for, case sensitive RETURNS The contents of the file field, or "" if no such field exists for the specified file. SEE ALSO gotofarea(), setffield() ------------------------------------------------------------------------------ NAME setffield -- set file description field SYNTAX void setffield( string Filename, string Field, string Contents ); DESCRIPTION Sets the contents of a file description field. If no such field exists for the specified file, it will be created. PARAMETERS Filename the name of the file whose field should be set Field the two-character field name to set, case sensitive Contents the new contents of the description field RETURNS Nothing SEE ALSO gotofarea(), getffield() ------------------------------------------------------------------------------ NAME fkill -- remove a file description line SYNTAX void fkill( string Filename ); DESCRIPTION Removes the description line for Filename from the description file. The first line encountered describing the specified filename is simply removed from the list file. If the list file contains several entries for the same filename, only the first one is removed. PARAMETERS Filename the name of the file whose description line should be removed RETURNS Nothing ------------------------------------------------------------------------------ NAME fmove -- move a file description line SYNTAX void fmove( string Filename, string NewList ); DESCRIPTION Moves the description line for Filename from the current description file to the top of another file. PARAMETERS Filename the name of the file whose description line should be moved NewList the path+filename of the description file to where the line should be moved RETURNS Nothing ------------------------------------------------------------------------------ NAME setdatestr -- set file date display strings SYNTAX void setdatestr( string& Days[3], string& Months[12] ); DESCRIPTION In the file list, the file date can be displayed in varying ways. The default is the following: If the file date is "today", the string "Today" is displayed instead of the file date. The same goes for yesterday. For all dates other than today, yesterday and the day before yesterday, but in the same year as today, the format "DD Month" is used. For all other dates (other years) the format YY-MM-DD is used. setdatestr() defines the strings displayed when the YY-MM-DD format is NOT used. That is, it defines the relative day names and the month names. PARAMETERS Days A reference to an array of three (3) strings with a maximum length of eight characters each. The first string should contain the string to be displayed for dates being the current day. Default: "Today" The second string should contain the string to be displayed for dates being one day prior to the current day. Default: "Yestrday" The third string is for dates being TWO days prior to the current day. Default: "" (no string). Months A reference to an array of twelve (12) strings with a maximum length of five characters each. The strings should be the month names. Default: Jan,Febr,March, April,May,June,July,Aug,Sept,Oct,Nov,Dec If you wish to inhibit the use of one or more of these strings, use an empty string ("") in place of a month or day name. Supplying only empty day names inhibits the use of relative days and supplying only empty month names inhibits the current-year display variant. RETURNS Nothing EXAMPLE /* Set all three day strings */ string Days[3] = {"Todei","Jestrday","DayBfore"}; /* Use strings for all months, except july, august and september, */ /* where the YY-MM-DD format will be displayed. */ string Months[12] = { "Yan","Fbrrr","March","April","May","June", "","","","Oct","Nov","Dec" }; setdatestr(&Days,&Months); ============================================================================== Time Functions ============================================================================== NAME nowtime -- find out current system time SYNTAX int nowtime( void ); DESCRIPTION notime() returns the current system time in the number of seconds since 1970. PARAMETERS None RETURNS The time. ------------------------------------------------------------------------------ NAME timepart -- get part of a time (better description wanted!) SYNTAX int timepart( int Time, string Field ); DESCRIPTION This function allows you to extract a single part from a time, such as the year, the month number or the minute. PARAMETERS Time the time to use, in seconds from 1970. Field the time part to return: "year" the year, 1970- "month" the month, 1-12 "day" the day of the month, 1-31 "wday" the day of the week, 0-6 (0=Monday) "hour" the hour, 0-23 "minute" the minute, 0-59 "second" the second, 0-59 RETURNS The time part requested. ------------------------------------------------------------------------------ NAME time2str -- convert an integer to a time string SYNTAX string time2str( int Time ); DESCRIPTION Converts an integer representing the number of seconds from 1970 into a string in the format "YYYY-MM-DD,HH:MM:SS" PARAMETERS Time the time to convert RETURNS The time, as a string. ------------------------------------------------------------------------------ NAME str2time -- convert a time string into an integer SYNTAX int str2time( string Time ); DESCRIPTION Converts a string in the format "YYYY-MM-DD,HH:MM:SS" into an integer representing the number of seconds since 1970. Actually, the time format is "YYYY.MM.DD.HH.MM.SS" where the '.' chars can be any character at all. PARAMETERS Time the time string to convert RETURNS The time, as an integer.