ftp.wwiv.com

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

/ ftp.wwiv.com / ftp.wwiv.com.zip / ftp.wwiv.com / pub / MISC / TGARTS.ZIP / SCRIPT.DOC < prev next >

Wrap

Text File | 1999-12-14 | 23.8 KB | 491 lines

The Script Language by Scott Adams (12/98) Telegard is one of the most modern versatile bbs softwares out there to date and part of the reason is its scripting language. This article will give a overview and discussion of the language. * What is the scripting language? The scripting language is nothing more than a series of commands that telegard can understand and perform some actions. Many sysops are scared to use it because they think its programming. In a sense it is but you do not need to be a programmer to use it at all. All you need is a basic understanding of the commands and how to use them. Hopefully by the end of this article you'll have some understanding of the language. A telegard script ends with the extension of .scr like logon.scr. * Where is the language? There is no particular software program that runs the scripts. Instead Telegard itself will load and run the scripts. But you should place all Telegard scripts in your \text directory which is off your main Telegard directory. * Who should run the scripts? When should I? Why should I? Any sysop who wishes to save space and organization. Menus take up time on working on them and editing them. Instead a script file can do the same operations as a menu so it will save you time to edit just one item rather than a series of menu commands. If you know you need to perform long or complicated tasks like viewing a file or saving some user data then use a script. While a menu could do the same thing a script saves space and time. * How do I write scripts? If you are interested in doing scripts then read the article further as I will give some pointers, tips and even some examples. * The documentation on scripts. The core documentation of the scripting language is in one reference file located in your \docs directory called script.ref. You should consult and read it before you can fully understand the language. Do not worry if it confuses you at first hopefully in time it will become easy for you to use. * Telegard default scripts Telegard comes pre-packaged with several scripts already in your \text directory. 1) Autoval.scr - autovalidates users if a password is given. 2) bdaychek.scr- Does a birthday check at logon 3) callback.scr- Sample callback script using the TCR CBV 4) callinfo.scr- callinfo door format script 5) dorinfo1.scr- dorinfo1 door format script 6) dorinfon.scr- dorinfo door format script 7) doorsys.scr - door.sys door format script 8) doorfile.scr- doorfile.sr door dropfile format script 9) hangup.scr - hangup script for logoff operations 10) hitenter.scr- full screen logon help script 11) logoff.scr - logoff operations script 12) logon.scr - logon script that controls logon process 13) newupass.scr- new user script 14) olddoors.scr- old door.sys format for old doors 15) sfdoors.scr - sfdoors dropfile script 16) single.scr - single node doors on multi-node systems 19) tcr110.scr - TCR cbv sample script 20) updateu.scr - updates user account if missing data exists That's twenty scripts that you can look over and experiment with. Scripts 4-8 and 14-15 are scripts that are used for door dropfiles. If you have problems with a dropfile reporting the wrong data then you should try to use one of these scripts. At the very least you should edit the logon.scr since it is used everytime a user logs on and you should personalize it to your system. * Script.ref overview : So by now you've looked at the script.ref and your lost. Well hopefully I can help with some explanations of the commands in that file. 1. :label all this command tells the script that a "block" begins here. In cases where you might need to return to a spot previously in a script you would use this command. You can "jump" to this spot as well and perform loops and other things. An example is :Start ... :Loop1 "label" can be any text you want of one word but the : is required along with the word. 2. ACS this command performs a ACS check to see if hte user is qualified for a action in the script. If not the command is skipped. You must use the ACS acs script_cmd in that order. ACS is the keyword to tell the interpreter a ACS check is being done. The word "acs" is the actual ACS string and script_cmd is any script command or action. An example is ACS GF Putnl "you are a female!" would check to see if the user is female if so then displays that line to the user. 3. Call is a way to jump to the labels or subsections of your script. The keyword CALL is required along with the name of the pre-existing label name (see A). 4. CLS - simply clears the screen display. 5. COMMANDLINE "text"- this updates teh command line with the "text" you give. A good use of this is to debug your scripts it will show the script commnad line on top of the TG screen when it runs the screen. You can also use this to update the parameters of a script if you need to. 6. COMMENT "text" - this allows you to update and change the comme6t field in the user account (see user editor). The keyword COMMENT is required and the text to change it to. 7. Decrement variable (value) - this changes the values of some variable in the script used to store data. The value must be of Integer type -32767..32767 in that range. If no value is given with the keyword then a value of 1 is given. 8. ENDSCRIPT - this will end the script entirely. 9. FILECLOSE this closes a open text file you previously opened. 10. FILECREATE filename - opens a new textfile in a destructive manner, meaning it will overwrite the file if it exists. An example might be FILECREATE demo.txt to hold some data the user might type in. 11. FILEDISPLAY filename - displays a file. This includes the telegard file formats of color codes and ascii. 12. FILEERASE filename - erases the file given by filename. 13. FILEEXIST filename script_cmd - this will test if the file exists, if it does it will then execute script_cmd otherwise it skips the script_cmd. This is sueful to check to see if a flag file might exist. An example is FILEEXIST scott.flg putnl "you have the flag". This will also work FILEEXIST scott.flg FILEDISPLAY scott.flg. 14. FILEOPEN filename - opens the textfile and allows you to then append data to it. 15. FILEPUT "text" this will add the "text" you define (say a value given by the user) to the file you should previously open. An example would be FILEPUT "Scott did a bad thing on the bbs". 16. FLUSH - flush keyboard/inbound buffer. This will basically clear out keystrokes the buffer might have. Sometimes a user might enter too many keys and foul up the system. If you use this command then you can clear it up and prevent such actions. 17. HANGUP - this will simply hang up on the user. This command might be useful if the user refuses to do some action you want. 18. IF/ENDIF - this is what we can a conditional statement. It checks for values you define then will do various actions you define. IF "text" "text" If IFNOT "text" "text" If not <statement> : <statements...> : ELSE Else <statement> : <statements...> : ENDIF Endif "text" is the value to check. (statements) are the command to perform if the value matches. This part looks confusing but IF and IFNOT should be used by themselves. IF will check to see if "text" equals "text" and IFNOT checks to see if "text" does not match "text". The ELSE will perform if the action fails for either option (IF/IFNOT). Here is an example: IF "~U0" "00/00/00" MENU OP9 ELSE PUTNL "Good user has a birthdate set" ENDIF This will check to see if the user via the MCI code ~U0 has a birthdate set in the records. If the value of ~U0 is 00/00/00 then the script will run the commadn to have the user enter his birthday via the MENU OP9 option. Otherwise the script will tell him that he has a birthday defined since the ELSE was there. The ELSE line does not have to be there but can be included as an alternative to the checked value. An example of IFNOT would be IFNOT "~TR" "0" PUTNL "you have ~TR illegal logons!" ENDIF This will check the users illegal logon field (via ~TR mci code) If the value is greater than 0 then it will display the number of bad logons otherwise the next line will be ENDIF. Notice in both cases ENDIF finished the block and is required in both cases. Anything between the IF/IFNOT and ENDIF lines are performed if the result matchs. 19. INCREMENT: works the opposite of DECREMENT. 20. JE "text1" "text2" label - this will tell the scrip to jump to an existing label if the values equal. An example might be JE "~TR" "0" No_bad_logons This would jump to no_bad_logons if the user had no illegal logons in his user account. 21. JNE "test1" "test2" label this does the same as JE but if the values are NOT equal to each other. 22. JUMP label - this will simply jump to the label no matter what. 23. KEYPRESSED script_cmd this is useful if you are waiting for a user to press a key on the keyboard. An example would be PUTNL "Hit any key to continue" KEYPRESSED JUMP continue_label 24. MCI variable - this will process the MCI code result on the given string by variable. 25. MENU command "Text" - this will do any menu command that is defined in \docs\menus.ref. An example would be MENU -Fuserinfo This command would display using the -F menu command to display the file userinfo.msg 26. NL - this sends a carriage return/line feed. 27. NOYES variable "text" - this is used for questions the default in this case is NO (because it starts with NOyes). An example would be: NOYES READY "Are you ready? [No]" If the user hits enter or N then the value READY is given no or false (if boolean). Otherwise the variable READY is TRUE or YES. 28. PAGEUSER - this pages the user through a series of bells. 29. PUT "test" - this will send "text" to the display to show the user something he should see. 30. PUTNL "text" works like PUT but this will add a CR/LF after. 31. RANDOM variable max_value - this will generate a random number. The variable must be a integer in the range of 0 to max_value. An example would be RANDOM RANDVAL 100 would generate a number between 0 and 100 inclusive. 32. RETURN this will return th escript position to the last saved position that was called by the CALL statement. For every CALL you must have one RETURN. 33. SCRIPT (name_of_script) is used to execute or run another script within a script. 34. TRANSLATE variable "text" "c1" "c2" Translate characters Think of this as a text replace/change command. The variable must be of STRING type. The "text" the variable to translate, "c1" character to translate, and "c2" characters to replace with. An example might be to change a variable of a user inputed value to a new value. Say a variable HOLIDAY holds "Halloween" and you want to change it to "X-mas" it would be TRANSLATE HOLIDAY "HALLOWEEN" "HALLOWEEN" "X-mas" (2 halloweens because you want to change the entire word). Another example would be to change all asteriks from a variable and replace them with spaces - TRANSLATE DATA "***DATA***" "*" " ". 35. VALIDATE level this will upgrade a user to an existing validation level. The level ID should match that in your validation level configuration. 36. VARIABLE variable type <"text"> this is the heart of the script data manipulation. This statement will declare a variable and give it a optional value possibly. Delcaring a variable is a way to store data for the script to work with. When you delcare something it is defined or stored. The variable types are STRING which is a series of characters together that fit a string like "hello" which can not exceed 70 characters max in length. Another type is INTEGER which is a number that ranges from -32767 to +32767. A CHAR type is a single character like from a..z, A..Z, 0..9 or the other characters like !,^. The BOOLEAN type either is YES or NO. Some examples are: VARIABLE Data 4 VARIABLE Date STRING "10/12/98" (Date is given 10/12/98) VARIABLE AGE INTEGER 27 VARIABLE SEX CHAR VARIABLE TOGGLE BOOLEAN 37. YESNO variable "text" works like NOYES but the default answer is YES if enter is hit by default. 38. var_name "text" this sets or defines a variable to the "text" contents or value. You MUST use the VARIABLE to define the variable type first before you can use this statement. An example using 36 above would be: SEX "M" or TOGGLE "Yes" 39. GET statement I saved this for last since its fairly big. In a nutshell this is how you GET data from a user from the keyboard. GET variable "text" (options) - is the line to use if type string "text" length upper_YES/NO >"mask"> If the variable is of type string you use the above. The "text" is the prompt you want shown if any (can be "" for blank), length is the max length of the string to input, and the upper_YES/NO is just a yes/no answer to use case sensitivity. This means if YES the stored data will be in all caps if NO then it will be in the case the user types in (lower/upper). Finally "mask" is a way to force the data to be typed in a certain way. The make can be of any combination of the following: ? - any character, @ - alpha characters, # - number. other - forced add (or any value you give will be forced in. An example of the mask would be "###-###-####" for a phone number or "@#@-###" canadian postal. if type INTEGER "text" its just a number to give If Type CHAR "text" (valid_chars) - where valid chars are the valid range of values that can be entered. Other special keys can be used here like ^M for ENTER, ^_ for the space bar, ^[ for ESCape key, and ^^ for the Caret. Now for some examples GET FILENAME "Enter the filename " 12 NO GET Name "Enter your name " 30 YES GET Time "Enter the time " 5 "##:##" GET Age "Your age is ?" GET Gender "Your sex is " "MF" The first sample will store the filename entered but does not worry about the case of the input. The second gets the user name and places it all in capital letters of length 30. The third will ask for the time to be entered using the defined method of input. The next will ask for AGE of the person. Finally the last will ask for the gender of the person and only accept M or F. You should read the bottom of script.ref since it explains the other points of scripts in a easy to understand manner and does not need to be repeated here. * The new Script language Yes you've heard right there will be a new script language that will be even more powerful. This new version will be able to compile and run scripts (sorta like a EXE program does). Do no panic though any scripts you do now will be able to be used in the new version. There will be a script translator to the new format. So still play with the old scripts until it is out. Matter of fact by the time this article is published it might be out. * Script tips and common mistakes 1) Don't include the .scr extension when using the scripts from a menu/language file. This is a common mistake. 2) All scripts should be placed in \text. 3) Use the strict guidelines and methods above to define your script lines or it may not work. 4) For more tips and comments on scripts consult \docs\faq.doc section 9 for common questions on scripts. 5) Use scripts in your language files to cut down on string editing and to use full screen displays. * Sample Scripts I have collected some 30 or so scripts over the few years the script language has been out. But since I don't have the express permission from the authors I will not show them here. However I will show a list of some of the good ones. Many if not all of them can be found on the official Telegard web and ftp sites. Here is a list of good (but not all that are out there) scripts to look over as good examples. Script file Author File to download Description Bullet.scr David Stumpf unknown Bulletins replacement Imail.scr Beer Software Imaid16.zip Internet Email script Light.scr Jeff Irvine unknown Light bar script Locate.scr David Stumpf unknown Ansi relocate script MH-TGFTL.SCR Max Headroom unknown File tagging script Netapp.scr Jeff Weese TGnet101.zip Network applications Rndpause.scr David Stumpf unknown Random Pauses Tfiles.scr Thomas Moore Tfiles02.zip Tfiles replacement Vsysop.scr Unknown Vsysv1_0.zip Visiting Sysop script YNC.scr David Stumpf unknown Prompt script I will show you a few I use here to give an idea of what you can do within Telegard. 1) FD.scr I use this script: ---FD.SCR--- MENU -;@1@;~SM MENU FD ------------ To allow users to download certain special files without having to hunt them down. I have about 10 or so special files on one menu like my master file list and such. The menu command would then Execute (-E) the script using: "FD master.zip" as the command line. Notice the @1@ above. The Master.zip replaces that @1@ as a parameter. 2) Newuser.scr This script MUST be named this and is a special way of having Telegard do special new user options. This script will automatically run (doesn't need to be executed) after the new user saves his new user application letter and before logons.cr is run. Mine looks like this: MENU MT0;new.msg;Welcome to the BBS!;Longshot Which simply posts a email message to that new user. The letter is in my \text\new.msg file and the subjet line is Welcome to the BBS and longshot is who it is from. This way by the time they get to the logon.scr area prompting for new email it will display the email to them. 3) Vote.scr This script handles some Voting booth operations ----vote.scr---- ;Script for new voting Questions VARIABLE VOTEBOOL BOOLEAN PUTNL "~SM|10There are some unanswered voting questions." NL NOYES VOTEBOOL "|13Enter the voting booth now? |12[N/y] " IF "$VOTEBOOL$" "YES" MENU OV ENDIF ----- I placed this file in my language file on line 0369 like 0369 $vote - this replaces the previous line that was in there. This shows how you can use scripts within the language file. This script will run if there are unanswered voting questions and if so it will then prompt the user to enter the booth or not. If the user does say yes it will run the voting booth (OV menu command). 4) Jgroup.scr I don't use this one but if you want to replace teh language line or menu command from the default join group to this you can do so: -------------- VARIABLE GROUP CHAR NL PUTNL "`07<1> Current main group: `0F~CG `09<`0E~CC`09>" PUTNL "`07<2> Current file group: `0F~CK `09<`0E~CH`09>" GET GROUP "`09Change which group? [12Q]: `0B" "12Q^M" IF "$GROUP$" "1" MENU OR ENDIF IF "$GROUP$" "2" MENU OQ ENDIF ----------- 5) Trule.scr This one I made for the bbs online game tournaments I have. I make users read the online tournament rules before they continue into the actual tournament door. --------------- VARIABLE VB BOOLEAN PUTNL "~SC" PUTNL PUTNL "|10Before you enter the Tournament Game for this month." PUTNL "|14 You are required to read the online Tournament rules." NL PUTNL "~SP" NOYES VB "|13Read the Tournament Rules now? |12[N/y] " IF "$VOTEBOOL$" "YES" FILEDISPLAY trule.msg MENU -S"User ~UH Read the tournament rules on ~SD at ~ST!" ENDIF ------------------- In conclusion you can see the power of scripts will only benefit and improve your system. They are easy to understand and design. You do not need to be a veteran programmer just one who can understand the basics. There are plenty of sample scripts out there to help give you ideas and sample ways of doing things. Just experiment with scripts the worst you can do is get Telegard to say "error" you will not crash Telegard or your computer. If you are really worried then as always backup your data before you start. But you will once you use scripts never go back to the complex menus. ------------------------------------------------------------------ To contact me for feedback on the article or questions/comments: BBS: 904-733-1721 Fringe BBS-EWOG II (guest account avaliable) Email: longshot@darktech.org ICQ #: 24436933 website: http://users.cybermax.net/~longshot Netmail: FidoNet 1:112/91 Fido TG Echo: Tg_support I welcome any comments or questions ohe articles. If enough feedback is given I can do article follow-ups. I suggest you also send feedback to the the other article authors of this newsletter for without feedback the desire to continue is difficult. ------------------------------------------------------------------