--- Information about Concord Script Language ----------------------[ 1/8 ]--


  Lines marked with "|" represent changes since previous version.

  Introduction :

          Concord Script Language is very powerful way of writing own
          additions to the software itself. Syntax is something between
          Basic and Pascal without type and range checking which makes it
          closer to C language, because all responsibility is left for the
          author. Script files are interpreted on the run and they need
          not to be compiled before use.

|         Script language will be enhanced later, providing more syntax
|         checking and more flexibility than the current way provides.

  Some features :

          - single type variables (string, number, date)
          - mathematical formulas
          - arithmetical operations
          - string handling commands
          - IF-THEN-ELSE construction
          - sub-routines: functions and procedures
          - various units
          - run external programs
          - run Concord menutypes
          - redirectable output
          - scripts can be edited with any ASCII editor

  Reserved words :

          - commands :

            GOTO     GOSUB    RETURN   QUIT     CALL     EXIT
            VAR      SET      WRITE    OUTPUT   EXEC     MENUTYPE
            IF       ELSE     END      PARAM    INPUT    ALLPARAM

          - variable types :

            ARRAY    STRING   NUMBER   DATE     TIME     DATETIME

          - string handling :

            STRLEN   STRCPY   STRDEL   STRPOS   STRINS   RANDOM

          - macros :

            @ANSWER@ + all valid Concord macro codes (@XXX@)
  
  --- Information about Concord Script Language ----------------------[ 2/8 ]--


  General :

          - Default script file extension is .Q-A, scripts are searched
            from Concord system path.

          - No limitations concerning number of variables, subroutines and
            units

          - Max line length is 255 (in expanded format, which means after
            macro codes have been converted)

          - Remark and comment lines start with semicolon character, ie.
            ";anything possible here"

          - Variables are identified with percent signs, ie.
            "%THIS_IS_VARIABLE%"

          - Variables must be assigned to some type before use, ie.
            "VAR %variable% = NUMBER"

          - All variables are global which means that they can be
            referenced anywhere in script even if assigned in subroutine.

          - Subroutine labels are defined like in DOS batch files, ie.
            ":THIS_IS_LABEL"

          - Subroutine parameters must be assigned to some type in
            beginning of each subroutine, ie.
            "PARAM %parameter% = NUMBER" or
            "ALLPARAM %parameter% = STRING"

          - Parenthesis must be used in comparisons, ie.
            "IF (variable1 = variable2)" or "IF ((a = b) OR (a = c))"

          - All commands must be on separate lines and cannot be divided
            into several lines.
  
  --- Information about Concord Script Language ----------------------[ 3/8 ]--


  Command usage :

          GOTO <label> [<parameters>]
          GOSUB <label> [<parameters>]
          RETURN
          PARAM %variable% = type
          ALLPARAM %variable% = STRING 255

                  GOTO and GOSUB jumps into subroutine <label> with given
                  parameters. In GOTO, it is not possible to return back
                  to original position in script without another GOTO
                  command. In GOSUB, RETURN continues execution from
                  original position. PARAM defines subroutine parameters
                  and their types. This must be done in beginning of
                  subroutine. In STRING types, max length must also be
                  specified. ALLPARAM assigns all the remaining subroutine
                  parameters to the string variable (parameter list is not
                  emptied).

                  Example :

                      GOTO main

                    :greet
                      ALLPARAM %paramlist% = STRING 255
                      PARAM %firstname% = STRING 15
                      PARAM %lastname%  = STRING 15
                      PARAM %seclvl%    = NUMBER
                      write "Debug: parameter list = %paramlist%^M;"
                      write "^C14,0;Hello, %firstname%! Let me guess, your "
                      write "security level is... %seclvl%, isn't it?^M;^M;"
                      RETURN

                    :demo
                      write "^C13,0;No parameters for this sub-routine.^M;^M;"
                      RETURN

                    :main
                      GOSUB greet @name@ @seclvl@
                      GOSUB demo
                      quit

          QUIT

                  QUIT ends script and returns to Concord.
  
  --- Information about Concord Script Language ----------------------[ 4/8 ]--


          CALL <scriptfile>
          EXIT

                  CALL jumps into another script file. EXIT returns back
                  to caller script.

          VAR %variable% = type
          SET %variable% = <newvalue>
          SET @macro@ = <newvalue>

                  VAR assigns variable to type. This must be done before
                  variable is used. In STRING types, max length must also
                  be specified. Arithemetical operations and string
                  handling commands are allowed with SET command.

                  Arithmetical operations :

                    [ (SHL)    ] (SHR)    | (OR)     & (AND)    ^ (XOR)
                    $ (MOD)    * (MUL)    / (DIV)    + (ADD)    - (DEC)

                    Parenthesis are allowed and will normally affect to
                    calculation order, ie. 2+3*5=17 but (2+3)*5=25

                  Special commands :

                    RANDOM <max>

                    returns random value from 0 to max-1, ie. RANDOM 100
                    ==> 0..99

                  String handling commands :

                    STRLEN <str>

                    returns length of string <str>, ie. STRLEN pasi = 4

                    STRCPY <pos> <len> <str>

                    copies <len> chars from position <pos> in string
                    <str>, ie. STRCPY 6 5 talliniemi = niemi

                    STRDEL <pos> <len> <str>

                    deletes <len> chars from position <pos> in string
                    <str>, ie. STRDEL 6 5 talliniemi = talli

                    STRPOS <searchstr> # <str>

                    returns position of first occurrence of string
                    <searchstr> in string <str>, ie. STRPOS niemi #
                    talliniemi = 6
  
  --- Information about Concord Script Language ----------------------[ 5/8 ]--


                    STRINS <pos> <ins> # <str>

                    inserts string <ins> to position <pos> in string
                    <str>, ie. STRINS 3 s # pai = pasi

|                   STRUPP <str>
|
|                   converts string <str> to uppercase, ie. STRUPP
|                   talliniemi = TALLINIEMI
|
|                   STRLOW <str>
|
|                   converts string <str> to lowercase, ie. STRLOW
|                   TALLINIEMI = talliniemi
|
|                   STRCAP <str>
|
|                   converts first char of each word in string <str> to
|                   uppercase and the rest to lowercase, ie. STRCAP
|                   TALLINIEMI = Talliniemi

                  Example 1 :

                    VAR %test% = STRING 35
                    write "^C15;Please enter your name: ^C14,1;^L35;^C15;^M;"
                    SET %test% = @ANSWER@
                    write "^C14;You entered: %test%^M;"
                    quit

                  Example 2 :

                    SET @HOTKEYS@ = OFF
                    SET @SECLVL@  = 32000
                    quit

                  Example 3:

                    VAR %totalmsgs% = NUMBER
                    SET %totalmsgs% = (@PUBLICMSGS@+@PRIVATEMSGS@)
                    write "^C15,0;You have written %totalmsgs% messages.^M;"
                    quit

                  Example 4:

                    VAR %str% = STRING 10
                    VAR %len% = NUMBER
                    SET %str% = STRCPY 6 10 Pasi Talliniemi
                    SET %len% = STRLEN %str%
                    write "^C14,0;%str% (length %len%)^M;"
                    quit
  
  --- Information about Concord Script Language ----------------------[ 6/8 ]--


          WRITE <string>
          OUTPUT [>][<filename>]
          OUTPUT [<device>]

                  WRITE outputs given string. By default, this happens to
                  console. It can be changed with OUTPUT command which
                  redirects output to given destination (generally into
                  ASCII text file). When writing to console, normal screen
                  macros can be used, eg. ^M; sends linefeed and ^E1;
                  clears screen. Optional ">" char before filename
                  overwrites existing file instead of appending.

                  Example :

                    WRITE "^C14,0;This comes to screen.^M;"
                    OUTPUT SCRIPT.LOG
                    WRITE "@CURRDATE@ @CURRTIME@  @NAME@ was here.^M;"
                    OUTPUT
                    WRITE "^C14,0;Now returning to board...^M;"
                    quit

          EXEC <cmdline>

                  EXEC shells to operating system and runs given command
                  line. All normal MENU_EXEC parameters can be used, eg.
                  *B is current bps rate and *T is user's time left.

                  Example :

                    EXEC c:\doors\xoremote.exe *P *G *D1- *D2- *E-
                    quit

          MENUTYPE <num> <params>

                  MENUTYPE runs given menutype with given parameters. All
                  menutypes are valid.

                  Example :

                    MENUTYPE 5 WELCOME.ANS
                    MENUTYPE 5 /NEW NEWS.ANS
                    quit
  
  --- Information about Concord Script Language ----------------------[ 7/8 ]--


          IF
          ELSE
          END

                  IF-ELSE-END allows creating conditional loops where
                  IF-loop is executed only if IF-statement is TRUE and
                  ELSE-loop if IF-statement is FALSE. These can be one
                  within another. ELSE branch is optional.

                  Example 1 :

                    IF (@SECLVL@ = 32000)
                      write "^C14,0;You must be sysop!^M;"
                    ELSE
                      write "^C15,0;Your security level is @seclvl@^M;"
                    END
                    quit

                  Example 2 :

                    IF (@TAGFILES_COUNT@ > 0)
                      write "^C12,0;You have flagged files to download.^M;"
                    END
                    quit

                  Example 3 :

                    write "Sysops only: do you want to continue? "
                    write "(~1Y/~2n) ^W;^M;"
                    IF ((@ANSWER@ = 1) AND (@SECLVL@ = 32000))
                      write "Haha, nothing really important here...^M;"
                    ELSE
                      IF (@ANSWER@ <> 1)
                        write "Wise choice...^M;"
                      END
                    END
                    quit

          INPUT <filename>

                  Opens file <filename> for input. File can be read with
                  macros @INPUT_NEXT@ and @INPUT_PREV@. Current file
                  position is reported (and can be modified) in macro
                  @INPUT_POS@. Input file size is reported in macro
                  @INPUT_SIZE@ (-1=file not open).

  
  --- Information about Concord Script Language ----------------------[ 8/8 ]--


  Examples :

|         See *.SCR for example scripts.

  Notes :

  - Calculating : Works only with %VARIABLES% (not @CONSTANTS@). Always
    remember to use () chars around formula...

| - If one comparison variable is number and the other is string,
|   a string comparison will be performed.

  - String / Date / Time comparing : Always use double quotes (") around
    variables. For example,

    VAR %STR1% = STRING 5
    VAR %STR2% = STRING 5
    SET %STR1% = STRCPY 1 5 @BIRTHDAY@
    SET %STR2% = STRCPY 1 5 @CURRDATE@
    IF ("%STR1%"="%STR2%")
      WRITE "HAPPY BIRTHDAY!^M;"
    END

  <end of document>