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 >
Text File  |  1999-12-13  |  24KB  |  491 lines
  1.  
  2.  
  3.     The Script Language
  4.     by Scott Adams (12/98)
  5.  
  6.        Telegard is one of the most modern versatile bbs softwares out there
  7.     to date and part of the reason is its scripting language.  This
  8.     article will give a overview and discussion of the language.
  9.  
  10.        * What is the scripting language?
  11.  
  12.          The scripting language is nothing more than a series of commands
  13.     that telegard can understand and perform some actions.  Many sysops
  14.     are scared to use it because they think its programming.  In a sense
  15.     it is but you do not need to be a programmer to use it at all.  All
  16.     you need is a basic understanding of the commands and how to use them.
  17.     Hopefully by the end of this article you'll have some understanding
  18.     of the language.  A telegard script ends with the extension of .scr
  19.     like logon.scr.
  20.  
  21.        * Where is the language?
  22.  
  23.          There is no particular software program that runs the scripts.
  24.     Instead Telegard itself will load and run the scripts.  But you should
  25.     place all Telegard scripts in your \text directory which is off your
  26.     main Telegard directory.
  27.  
  28.        * Who should run the scripts?  When should I? Why should I?
  29.  
  30.          Any sysop who wishes to save space and organization.  Menus take
  31.     up time on working on them and editing them.  Instead a script file
  32.     can do the same operations as a menu so it will save you time to
  33.     edit just one item rather than a series of menu commands.  If you
  34.     know you need to perform long or complicated tasks like viewing a
  35.     file or saving some user data then use a script.  While a menu could
  36.     do the same thing a script saves space and time.
  37.  
  38.        * How do I write scripts?
  39.  
  40.          If you are interested in doing scripts then read the article
  41.     further as I will give some pointers, tips and even some examples.
  42.  
  43.        * The documentation on scripts.
  44.  
  45.          The core documentation of the scripting language is in one reference
  46.     file located in your \docs directory called script.ref.  You should
  47.     consult and read it before you can fully understand the language.
  48.     Do not worry if it confuses you at first hopefully in time it will
  49.     become easy for you to use.
  50.  
  51.        * Telegard default scripts
  52.  
  53.          Telegard comes pre-packaged with several scripts already in your
  54.     \text directory.
  55.  
  56.          1) Autoval.scr - autovalidates users if a password is given.
  57.          2) bdaychek.scr- Does a birthday check at logon
  58.          3) callback.scr- Sample callback script using the TCR CBV
  59.          4) callinfo.scr- callinfo door format script
  60.          5) dorinfo1.scr- dorinfo1 door format script
  61.          6) dorinfon.scr- dorinfo  door format script
  62.          7) doorsys.scr - door.sys door format script
  63.          8) doorfile.scr- doorfile.sr door dropfile format script
  64.          9) hangup.scr  - hangup script for logoff operations
  65.         10) hitenter.scr- full screen logon help script
  66.         11) logoff.scr  - logoff operations script
  67.         12) logon.scr   - logon script that controls logon process
  68.         13) newupass.scr- new user script
  69.         14) olddoors.scr- old door.sys format for old doors
  70.         15) sfdoors.scr - sfdoors dropfile script
  71.         16) single.scr  - single node doors on multi-node systems
  72.         19) tcr110.scr  - TCR cbv sample script
  73.         20) updateu.scr - updates user account if missing data exists
  74.  
  75.  
  76.          That's twenty scripts that you can look over and experiment with.
  77.     Scripts 4-8 and 14-15 are scripts that are used for door dropfiles.
  78.     If you have problems with a dropfile reporting the wrong data then
  79.     you should try to use one of these scripts.  At the very least you
  80.     should edit the logon.scr since it is used everytime a user logs
  81.     on and you should personalize it to your system.
  82.  
  83.        * Script.ref overview
  84.   :
  85.          So by now you've looked at the script.ref and your lost.  Well
  86.     hopefully I can help with some explanations of the commands in that file.
  87.                 
  88.          1.  :label all this command tells the script that a "block" begins
  89.     here.  In cases where you might need to return to a spot previously
  90.     in a script you would use this command.  You can "jump" to this spot
  91.     as well and perform loops and other things.  An example is
  92.               :Start
  93.                ...
  94.               :Loop1
  95.              "label" can be any text you want of one word but the : is
  96.     required along with the word.
  97.  
  98.          2.   ACS this command performs a ACS check to see if hte user
  99.     is qualified for a action in the script.  If not the command is skipped.
  100.     You must use the ACS acs script_cmd in that order.  ACS is the keyword
  101.     to tell the interpreter a ACS check is being done.  The word "acs"
  102.     is the actual ACS string and script_cmd is any script command or action.
  103.     An example is ACS GF Putnl "you are a female!" would check to see if
  104.     the user is female if so then displays that line to the user.
  105.  
  106.          3.  Call is a way to jump to the labels or subsections of your
  107.     script.  The keyword CALL is required along with the name of the
  108.     pre-existing label name (see A).
  109.  
  110.          4.  CLS - simply clears the screen display.
  111.                                         
  112.          5.  COMMANDLINE  "text"- this updates teh command line with the
  113.     "text" you give.  A good use of this is to debug your scripts it
  114.     will show the script commnad line on top of the TG screen when
  115.     it runs the screen.  You can also use this to update the parameters
  116.     of a script if you need to.
  117.                       
  118.          6.  COMMENT "text" - this allows you to update and change the
  119.     comme6t field in the user account (see user editor). The keyword
  120.     COMMENT is required and the text to change it to.
  121.  
  122.          7.  Decrement variable (value) - this changes the values of
  123.     some variable in the script used to store data.  The value must
  124.     be of Integer type -32767..32767 in that range.  If no value is
  125.     given with the keyword then a value of 1 is given.
  126.  
  127.          8.  ENDSCRIPT - this will end the script entirely.
  128.  
  129.          9.  FILECLOSE this closes a open text file you previously opened.
  130.  
  131.         10.  FILECREATE filename - opens a new textfile in a destructive
  132.     manner, meaning it will overwrite the file if it exists.  An example
  133.     might be FILECREATE demo.txt to hold some data the user might type in.
  134.  
  135.         11.  FILEDISPLAY filename - displays a file.  This includes the
  136.     telegard file formats of color codes and ascii.
  137.  
  138.         12.  FILEERASE filename - erases the file given by filename.
  139.  
  140.         13.  FILEEXIST filename script_cmd - this will test if the file
  141.     exists, if it does it will then execute script_cmd otherwise it skips
  142.     the script_cmd.  This is sueful to check to see if a flag file might
  143.     exist.  An example is FILEEXIST scott.flg putnl "you have the flag".
  144.     This will also work FILEEXIST scott.flg FILEDISPLAY scott.flg.
  145.  
  146.         14.  FILEOPEN filename - opens the textfile and allows you to then
  147.     append data to it.
  148.  
  149.         15.  FILEPUT "text" this will add the "text" you define (say a value
  150.     given by the user) to the file you should previously open.  An example
  151.     would be FILEPUT "Scott did a bad thing on the bbs".
  152.  
  153.         16. FLUSH - flush keyboard/inbound buffer.  This will basically
  154.     clear out keystrokes the buffer might have.  Sometimes a user might
  155.     enter too many keys and foul up the system.  If you use this command
  156.     then you can clear it up and prevent such actions.
  157.  
  158.         17. HANGUP - this will simply hang up on the user.  This command
  159.     might be useful if the user refuses to do some action you want.
  160.  
  161.         18. IF/ENDIF - this is what we can a conditional statement.  It
  162.     checks for values you define then will do various actions you define.
  163.  
  164.             IF           "text" "text"             If
  165.             IFNOT        "text" "text"             If not
  166.                <statement>                          :
  167.                <statements...>                      :
  168.             ELSE                                   Else
  169.                <statement>                          :
  170.                <statements...>                      :
  171.             ENDIF                                  Endif
  172.  
  173.             "text" is the value to check.  (statements) are the command to
  174.     perform if the value matches.  This part looks confusing but IF and
  175.     IFNOT should be used by themselves.  IF will check to see if "text"
  176.     equals "text" and IFNOT checks to see if "text" does not match "text".
  177.     The ELSE will perform if the action fails for either option (IF/IFNOT).
  178.     Here is an example:
  179.  
  180.         IF "~U0" "00/00/00"
  181.            MENU OP9
  182.         ELSE
  183.            PUTNL "Good user has a birthdate set"
  184.         ENDIF
  185.     
  186.         This will check to see if the user via the MCI code ~U0 has a
  187.     birthdate set in the records.  If the value of ~U0 is 00/00/00 then
  188.     the script will run the commadn to have the user enter his birthday
  189.     via the MENU OP9 option.  Otherwise the script will tell him that
  190.     he has a birthday defined since the ELSE was there.  The ELSE line
  191.     does not have to be there but can be included as an alternative
  192.     to the checked value.  An example of IFNOT would be
  193.  
  194.          IFNOT "~TR" "0"
  195.            PUTNL "you have ~TR illegal logons!"
  196.          ENDIF
  197.  
  198.          This will check the users illegal logon field (via ~TR mci code)
  199.     If the value is greater than 0 then it will display the number of
  200.     bad logons otherwise the next line will be ENDIF.  Notice in both
  201.     cases ENDIF finished the block and is required in both cases.  Anything
  202.     between the IF/IFNOT and ENDIF lines are performed if the result matchs.
  203.  
  204.  
  205.         19. INCREMENT: works the opposite of DECREMENT.
  206.  
  207.         20.  JE "text1" "text2" label - this will tell the scrip to jump
  208.     to an existing label if the values equal.  An example might be
  209.              JE "~TR" "0" No_bad_logons
  210.              This would jump to no_bad_logons if the user had no illegal
  211.     logons in his user account.
  212.  
  213.         21.  JNE "test1" "test2" label this does the same as JE but if the
  214.     values are NOT equal to each other.
  215.  
  216.         22.  JUMP label - this will simply jump to the label no matter what.
  217.  
  218.         23.  KEYPRESSED script_cmd this is useful if you are waiting for
  219.     a user to press a key on the keyboard.  An example would be
  220.               PUTNL "Hit any key to continue"
  221.               KEYPRESSED JUMP continue_label
  222.  
  223.         24.   MCI variable - this will process the MCI code result on the
  224.     given string by variable.
  225.  
  226.         25.   MENU command "Text" - this will do any menu command that
  227.     is defined in \docs\menus.ref.  An example would be
  228.               MENU -Fuserinfo
  229.               This command would display using the -F menu command to
  230.     display the file userinfo.msg
  231.  
  232.         26.   NL - this sends a carriage return/line feed.
  233.  
  234.         27.   NOYES variable "text" - this is used for questions
  235.      the default in this case is NO (because it starts with NOyes).
  236.      An example would be:
  237.                 NOYES READY "Are you ready? [No]"
  238.               If the user hits enter or N then the value READY is given
  239.      no or false (if boolean).  Otherwise the variable READY is TRUE or YES.
  240.  
  241.         28.   PAGEUSER - this pages the user through a series of bells.
  242.  
  243.         29.   PUT "test" - this will send "text" to the display to show
  244.     the user something he should see.
  245.  
  246.         30.   PUTNL "text" works like PUT but this will add a CR/LF after.
  247.  
  248.         31.   RANDOM variable max_value - this will generate a random
  249.      number.  The variable must be a integer in the range of 0 to max_value.
  250.      An example would be RANDOM RANDVAL 100 would generate a number between
  251.      0 and 100 inclusive.
  252.  
  253.         32.  RETURN this will return th escript position to the last
  254.      saved position that was called by the CALL statement.  For every CALL
  255.      you must have one RETURN.
  256.  
  257.         33.  SCRIPT (name_of_script) is used to execute or run another script
  258.      within a script.
  259.  
  260.         34.   TRANSLATE    variable "text" "c1" "c2" Translate characters
  261.      Think of this as a text replace/change command.  The variable must be
  262.      of STRING type.  The "text" the variable to translate, "c1" character
  263.      to translate, and "c2" characters to replace with.  An example might
  264.      be to change a variable of a user inputed value to a new value.  Say
  265.      a variable HOLIDAY holds "Halloween" and you want to change it to
  266.      "X-mas" it would be TRANSLATE HOLIDAY "HALLOWEEN" "HALLOWEEN" "X-mas"
  267.      (2 halloweens because you want to change the entire word).  Another
  268.      example would be to change all asteriks from a variable and replace
  269.      them with spaces - TRANSLATE DATA "***DATA***" "*" " ".
  270.                                                                 
  271.         35.  VALIDATE level this will upgrade a user to an existing
  272.      validation level.  The level ID should match that in your validation
  273.      level configuration.
  274.  
  275.         36.  VARIABLE variable type <"text"> this is the heart of the script
  276.      data manipulation.  This statement will declare a variable and give
  277.      it a optional value possibly.  Delcaring a variable is a way to
  278.      store data for the script to work with.  When you delcare something
  279.      it is defined or stored.  The variable types are STRING which is a
  280.      series of characters together that fit a string like "hello" which
  281.      can not exceed 70 characters max in length.  Another type is INTEGER
  282.      which is a number that ranges from -32767 to +32767.  A CHAR type
  283.      is a single character like from a..z, A..Z, 0..9 or the other characters
  284.      like !,^.  The BOOLEAN type either is YES or NO.  Some examples are:
  285.                 VARIABLE Data 4
  286.                 VARIABLE Date STRING "10/12/98"  (Date is given 10/12/98)
  287.                 VARIABLE AGE  INTEGER 27
  288.                 VARIABLE SEX  CHAR
  289.                 VARIABLE TOGGLE BOOLEAN
  290.  
  291.         37.  YESNO variable "text" works like NOYES but the default answer
  292.      is YES if enter is hit by default.
  293.  
  294.         38.  var_name "text" this sets or defines a variable to the "text"
  295.      contents or value.  You MUST use the VARIABLE to define the variable
  296.      type first before you can use this statement.  An example using 36
  297.      above would be:
  298.                 SEX "M"   or TOGGLE "Yes"
  299.  
  300.         39.  GET statement I saved this for last since its fairly big.
  301.      In a nutshell this is how you GET data from a user from the keyboard.
  302.              GET variable "text" (options) - is the line to use
  303.                  if type string "text" length upper_YES/NO >"mask">
  304.      If the variable is of type string you use the above.  The "text"
  305.      is the prompt you want shown if any (can be "" for blank), length
  306.      is the max length of the string to input, and the upper_YES/NO is
  307.      just a yes/no answer to use case sensitivity.  This means if YES
  308.      the stored data will be in all caps if NO then it will be in the
  309.      case the user types in (lower/upper).  Finally "mask" is a way to
  310.      force the data to be typed in a certain way.  The make can be of
  311.      any combination of the following: ? - any character, @ - alpha
  312.      characters, # - number. other - forced add (or any value you give
  313.      will be forced in.  An example of the mask would be "###-###-####"
  314.      for a phone number  or "@#@-###" canadian postal.
  315.                  if type INTEGER "text" its just a number to give
  316.                  If Type CHAR "text" (valid_chars) - where valid chars
  317.      are the valid range of values that can be entered.  Other special
  318.      keys can be used here like ^M for ENTER, ^_ for the space bar,
  319.      ^[ for ESCape key, and ^^ for the Caret.
  320.                 Now for some examples
  321.                 GET FILENAME "Enter the filename " 12 NO
  322.                 GET Name "Enter your name " 30 YES
  323.                 GET Time "Enter the time " 5 "##:##"
  324.                 GET Age "Your age is ?"
  325.                 GET Gender "Your sex is " "MF"
  326.               The first sample will store the filename entered but does
  327.      not worry about the case of the input.  The second gets the user name
  328.      and places it all in capital letters of length 30.  The third will
  329.      ask for the time to be entered using the defined method of input.
  330.      The next will ask for AGE of the person.  Finally the last will ask
  331.      for the gender of the person and only accept M or F.
  332.  
  333.         You should read the bottom of script.ref since it explains the
  334.      other points of scripts in a easy to understand manner and does not
  335.      need to be repeated here.
  336.  
  337.        * The new Script language
  338.  
  339.          Yes you've heard right there will be a new script language that
  340.      will be even more powerful.  This new version will be able to compile
  341.      and run scripts (sorta like a EXE program does).  Do no panic though
  342.      any scripts you do now will be able to be used in the new version.
  343.      There will be a script translator to the new format.  So still play
  344.      with the old scripts until it is out.  Matter of fact by the time
  345.      this article is published it might be out.
  346.  
  347.        *  Script tips and common mistakes
  348.  
  349.           1) Don't include the .scr extension when using the scripts from
  350.      a menu/language file.  This is a common mistake.
  351.           2) All scripts should be placed in \text.
  352.           3) Use the strict guidelines and methods above to define your
  353.      script lines or it may not work.
  354.           4) For more tips and comments on scripts consult \docs\faq.doc
  355.      section 9 for common questions on scripts.
  356.           5) Use scripts in your language files to cut down on string
  357.      editing and to use full screen displays.
  358.  
  359.        *  Sample Scripts
  360.  
  361.           I have collected some 30 or so scripts over the few years the
  362.      script language has been out.  But since I don't have the express
  363.      permission from the authors I will not show them here.  However
  364.      I will show a list of some of the good ones.  Many if not all of
  365.      them can be found on the official Telegard web and ftp sites.
  366.      Here is a list of good (but not all that are out there) scripts
  367.      to look over as good examples.
  368.  
  369.     Script file    Author        File to download    Description
  370.  
  371.     Bullet.scr     David Stumpf      unknown      Bulletins replacement
  372.     Imail.scr      Beer Software     Imaid16.zip  Internet Email script
  373.     Light.scr      Jeff Irvine       unknown      Light bar script
  374.     Locate.scr     David Stumpf      unknown      Ansi relocate script
  375.     MH-TGFTL.SCR   Max Headroom      unknown      File tagging script
  376.     Netapp.scr     Jeff Weese        TGnet101.zip Network applications
  377.     Rndpause.scr   David Stumpf      unknown      Random Pauses
  378.     Tfiles.scr     Thomas Moore      Tfiles02.zip Tfiles replacement
  379.     Vsysop.scr     Unknown           Vsysv1_0.zip Visiting Sysop script
  380.     YNC.scr        David Stumpf      unknown      Prompt script
  381.  
  382.           I will show you a few I use here to give an idea of what you can
  383.     do within Telegard.
  384.  
  385.         1) FD.scr
  386.            I use this script:
  387.                 ---FD.SCR---
  388.                 MENU -;@1@;~SM
  389.                 MENU FD
  390.                 ------------
  391.            To allow users to download certain special files without having
  392.     to hunt them down.  I have about 10 or so special files on one
  393.     menu like my master file list and such.  The menu command would then
  394.     Execute (-E) the script using: "FD master.zip" as the command line.
  395.     Notice the @1@ above.  The Master.zip replaces that @1@ as a parameter.
  396.  
  397.         2) Newuser.scr
  398.            This script MUST be named this and is a special way of having
  399.     Telegard do special new user options.  This script will automatically
  400.     run (doesn't need to be executed) after the new user saves his
  401.     new user application letter and before logons.cr is run.  Mine looks
  402.     like this:
  403.            MENU MT0;new.msg;Welcome to the BBS!;Longshot
  404.  
  405.            Which simply posts a email message to that new user.  The letter
  406.     is in my \text\new.msg file and the subjet line is Welcome to the
  407.     BBS and longshot is who it is from.  This way by the time they
  408.     get to the logon.scr area prompting for new email it will display the
  409.     email to them.
  410.  
  411.         3) Vote.scr
  412.            This script handles some Voting booth operations
  413.            ----vote.scr----
  414.            ;Script for new voting Questions
  415.            VARIABLE VOTEBOOL BOOLEAN
  416.  
  417.            PUTNL "~SM|10There are some unanswered voting questions."
  418.            NL
  419.            NOYES VOTEBOOL "|13Enter the voting booth now? |12[N/y] "
  420.            IF "$VOTEBOOL$" "YES"
  421.               MENU OV
  422.            ENDIF
  423.            -----
  424.            I placed this file in my language file on line 0369 like
  425.      0369 $vote - this replaces the previous line that was in there.
  426.      This shows how you can use scripts within the language file.  This
  427.      script will run if there are unanswered voting questions and if so
  428.      it will then prompt the user to enter the booth or not.  If the
  429.      user does say yes it will run the voting booth (OV menu command).
  430.  
  431.         4) Jgroup.scr
  432.            I don't use this one but if you want to replace teh language
  433.      line or menu command from the default join group to this you
  434.      can do so:
  435.            --------------
  436.            VARIABLE GROUP CHAR
  437.            NL
  438.            PUTNL "`07<1> Current main group: `0F~CG `09<`0E~CC`09>"
  439.            PUTNL "`07<2> Current file group: `0F~CK `09<`0E~CH`09>"
  440.            GET GROUP "`09Change which group? [12Q]: `0B" "12Q^M"
  441.            IF "$GROUP$" "1"
  442.                MENU OR
  443.            ENDIF
  444.            IF "$GROUP$" "2"
  445.                MENU OQ
  446.            ENDIF
  447.            -----------
  448.  
  449.         5) Trule.scr
  450.            This one I made for the bbs online game tournaments I have.
  451.      I make users read the online tournament rules before they continue
  452.      into the actual tournament door.
  453.              ---------------
  454.              VARIABLE VB BOOLEAN
  455.  
  456.              PUTNL "~SC"
  457.              PUTNL
  458.              PUTNL "|10Before you enter the Tournament Game for this month."
  459.              PUTNL "|14 You are required to read the online Tournament rules."
  460.              NL
  461.              PUTNL "~SP"
  462.              NOYES VB "|13Read the Tournament Rules now? |12[N/y] "
  463.              IF "$VOTEBOOL$" "YES"
  464.                 FILEDISPLAY trule.msg
  465.                 MENU -S"User ~UH Read the tournament rules on ~SD at ~ST!"
  466.              ENDIF
  467.              -------------------
  468.  
  469.         In conclusion you can see the power of scripts will only benefit
  470.     and improve your system.  They are easy to understand and design.
  471.     You do not need to be a veteran programmer just one who can understand
  472.     the basics.  There are plenty of sample scripts out there to help
  473.     give you ideas and sample ways of doing things.  Just experiment
  474.     with scripts the worst you can do is get Telegard to say "error" you
  475.     will not crash Telegard or your computer.  If you are really worried
  476.     then as always backup your data before you start.  But you will
  477.     once you use scripts never go back to the complex menus.
  478.  
  479.    ------------------------------------------------------------------
  480.    To contact me for feedback on the article or questions/comments:
  481.        BBS: 904-733-1721 Fringe BBS-EWOG II (guest account avaliable)
  482.      Email: longshot@darktech.org                 ICQ #: 24436933
  483.    website: http://users.cybermax.net/~longshot
  484.    Netmail: FidoNet 1:112/91   Fido TG Echo: Tg_support
  485.      I welcome any comments or questions ohe articles.  If enough
  486.    feedback is given I can do article follow-ups.  I suggest you also
  487.    send feedback to the the other article authors of this newsletter
  488.    for without feedback the desire to continue is difficult.
  489.    ------------------------------------------------------------------
  490.                                         
  491.