MPL Documentation

The Mystic BBS Programming Language Documentation

Copyright (C) 1998-2015 By James Coyle.  All Rights Reserved

All mentioned programs are copyrighted by their respective authors

-----------------------------------------------------------------------

Introduction to Mystic Programming Language (MPL)

-----------------------------------------------------------------------

The Mystic Programming Language (refered to as MPL from here on out) is

not complete.  In the state that it's in now, its still more powerful

than most BBS script languages, but its still not to the point where

it is as powerful as it should be.

The documentation for the MPL is also not complete.  This documentation

as well as the Mystic BBS documentation will be worked on as time

permits and may not be completed for quite some time.  There are some

example programs included with the distribution (found in the scripts

directory) which may help assist you in getting the hang of the MPL

structure and commands.

If you have written any useful MPL programs, please send them via e-mail

to [email protected] so they can be included for download on the

various Mystic BBS support sites.

-----------------------------------------------------------------------

General Notes About Using The MPL

-----------------------------------------------------------------------

The syntax of the Mystic BBS Programming Language follows closely to

that of the Turbo Pascal series of programming compilers.  At one time,

the language was almost 100% Turbo Pascal compatible (except for the

BBS functions) but it has been slightly changed to make it a little

more friendly to the programmer.

Two versions of the programming compiler are available in the scripts

directory.  The first one, MIDE.EXE, is a fully functional IDE for

creating and compiling MPE programs.  This program looks similar to the

Turbo Pascal IDE, including syntax highlighting of all command keywords!

The second version of the compiler is MPLC.EXE.  This is a command line

compiler supplied so you are not forced to use MIDE.EXE to write

programs.  If you do not find the MIDE interface to be satisfactory, then

you can use your favorite text editor and MPLC.EXE to create programs!

The following are some quick notes about the syntax of the language as

well as some notes about things that aren't working as they probably

should be:

1.  All text after a number sign (#) is considered a comment.  It will    be ignored until the next line of code.  For example:

   WriteLn ('Hello There')  # This is a comment and will be ignored.

2.  Operation types:

   The MPL does not follow the order of operations when doing

   mathmatical equations (ie PEMDAS - parenthesis, exponents,

   multiplication, division, addition, subtraction).  So math    functions are done in the order that they appear in the expression.    This doesn't mean its not POSSIBLE to do PEMDAS-ordered expressions,    it will just take a little more effort on the programmer's behalf.    The following operation codes are supported for mathmatical    equations:

       -   Subtract

       +   Addition

       *   Multiplication

       /   Division

       %   Modulus Operator

2a. Bitwise math:

   MPL fully supports bitwise math and operators!  The following are    implemented:

   AND - Bitwise AND

   OR  - Bitwise OR

   XOR - Bitwise exclusive OR

   SHL - Bitwise shift left

   SHR - Bitwise shift right

   Example:

   Const

   UserDeleted = $04;  // established bit for userdeleted from records.pas

                       // note: this value has changed check records.pas!

   Begin

   GetThisUser

   If UserFlags AND UserDeleted <> 0 Then

    WriteLn('User is deleted');

   End;

3.  Defining variables:  All variables are global to all of the program,

   including procedures.  The syntax for declaring a variable follows:

   Var <VarName> : <VarType>

   Examples:

   var dummy : byte

   var str   : string

   var

     dummy : byte,

     str   : string

   The following variable types are supported:

   Type            Format         Range

   --------------- -------------- -----------------------------------

   Boolean         FALSE/TRUE     0..1

   Char            Text           1 character

   String          Text           Sequence of 1..255 characters

   Byte            Numerical      0..255

   Integer         Numerical      -32767..32767

   Word            Numerical      0..65535

   LongInt         Numerical      -2147483648..214748364

   Real            Numerical      9.99

   All variables exept ARRAYs can be initialized when when defined.

   Var TotalBases : LongInt = GetMBaseTotal(False)

   Var Int        : Integer = 33

   Var Str        : String = 'This is a string'

   ARRAY multi-dimensional variables are supported.  The syntax for

   declaring an array variable is:

   Var <VarName> :  ARRAY[<Low>..<High>] of <VarType>

   Var <VarName> :  ARRAY[<L>..<H>, <L>..<H>] of <VarType>

   Var <VarName> :  ARRAY[<L>..<H>, <L>..<H>, <L>..<H>] of <VarType>

   Examples:

   Var Dummy : Array[1..10] of Byte

   Var Str   : Array[5..10] of String

   Var Int   : Array[1..10,1..10,1..10] of Integer

   HEXIDECIMAL values are supported.  They can be used in numeric

   variable assignment numerical evaluation, and in numeric constant

   variables.  A hex value must begin with a $ character.  

   Some examples:

   Const

      MyHexValue = $1F;

   Value := $10;

   If Value = $10 Then WriteLn('Value is 16 <in decimal>');

3b. Record structures: 

Groups data in to records.  This command

   allows you to create a datatype of multiple different variable

   types.

   Defining the record:

   Type

     testrec = record

     x : byte;

     y : byte;

     d : array[1..10,1..5] of string[9]

   end

   Declaring the record:

       Var struct : testrec

   Using the record:

       struct.x:=1

       struct.y:=10

       struct.d[1,1]:='abc123'

   

3c. CODE BLOCKS:  When using multiple lines (more than one line) within a

   IF/ELSE/WHILE/CASE blocks, the lines need to be grouped into

   blocks between BEGIN and END statments.  If there is only one line

   following the IF/ELSE/WHILE/CASE blocks, then no blocking statements

   are needed.

   Examples:

 

   If X = 1 Then

   Begin

      WriteLn('X = '+Int2Str(X))

      X:=X+1

      WriteLn('X = '+Int2Str(X))

   End

   The same is true for the ELSE block.

   If X = 1 Then

   Begin

      WriteLn('X = '+Int2Str(X))

      X:=X+1

      WriteLn('X = '+Int2Str(X))

   End

   Else

   Begin

      WriteLn('X = '+Int2Str(X))

      X:=X-1

      WriteLn('X = '+Int2Str(X))

   End

4.  FOR LOOPS (FOR/FEND):  The syntax for a for loop is as follows:

   For <variable> := <start number> <TO> or <DOWNTO> <end number> Do.  

   For A := 1 to 10 Do

        WriteLn (A)

   For A := 10 DownTo 1 Do

   Begin

        WriteLn (A)

        WriteLn (A)

   End

5.  REPEAT/UNTIL:  The syntax for a repeat until loop is as follows:

   Repeat

        <Code here>

   Until <Boolean Expression>

   IE:

   Repeat

        WriteLn ('Blah blah')

   Until A > 0 or A = 5

6.  WHILE:  The syntax for a while loop is as follows:

   While <Boolean Expression> Do

         <Code Here>

   IE:

   While A > 0 and A = 5 Do

       WriteLn ('Blah')

   OR:

   While A > 0 and A = 5 Do

   Begin

       WriteLn ('Blah')

       WriteLn ('More Blah')

   End

7. PROCEDURES: The syntax for defining a procedure is as follows:

  Procedure <Proc Name> (<varname vartype>, <varname vartype>)

    <Code here>

  IE:

  Procedure Hello_World

    WriteLn ('Hello World')

  OR:

  Procedure SomeProc (Str String, A Byte)

    WriteLn ('Str = ' + Str)

    WriteLn ('A   = ' + A)

  End

  OR:

  Procedure SomeProc (Str String)

  Var

    Str2 : String,

    Str3 : String

  Begin             <--- The keyword "BEGIN" is ignored by the compiler           

    WriteLn (Str)        just to maintain a "Pascal-like" feel.

  End

8. IF THEN/ELSE/END:  The syntax of an if/else/end statement:

  If <boolean statement> Then

     <True code here>

  Else If <boolean statement> Then     (optional)

     <True code here>

  Else                            (optional)

     <False code here>

  If Not fEof(fptr) Then

       WriteLn ('We''re not at the end of the file.')

  The above example is the same as the following example, except we've

  added an else statement:

  If fEof(fptr) = False Then

       WriteLn ('We''re not at the end of the file.')

  Else

       WriteLn ('This is the end of the file.')

  If A = 1 Then

       WriteLn ('A is 1')

  Else If A = 2 Then

       WriteLn ('A is 2')

  Else If A = 5 Then

       WriteLn ('A is 5')

  Else

       WriteLn ('A is not 1, 2, or 5...')

8a. CASE statements

   This has actually been expanded on

   from the Pascal standard but still follows the same syntax.  It has been

   expanded to allow CASE of more variable types, such as strings.  See

   the included MPLTEST.MPS for examples.

   Var I : Integer = 10

   Case I Of

      1 : WriteLn('I = 1')

      2 : Begin

            I:=I+1

            WriteLn('I = 3')

          End

      2,3,4,5,6,7,8,9: WriteLn('Not 1, 2, or 10')

   End

   Var S : String = 'ABCDEFG'

   Case S[3] Of

      'A': WriteLn('S[3] = '+S[3])

      'B','C','D': WriteLn('S[3] = '+S[3])

   Else

      WriteLn('This is the default choice')

   End

9.  The USES command must be declared before ANY other variables

   or your program may not function properly.  See documentation for

   the USES command for further information.

10. FUNCTIONS: The syntax for defining a function is as follows:

   Function <Function Name> (<varname vartype>) : <result type>

   IE:

   Function AddTen (Num Byte) : Byte

   Begin

     AddTen := Num + 10

   End

11. CONST VARIABLES: The syntax for a constant variable is as follows:

   String constants:

   Const

     SomeStr = 'Hello World!'

   Numerical constants:

   Const

     SomeNum = 69

   Constant variables, like regular variables, can be separated with a

   comma:

   Const

     SomeNum = 69,

     SomeStr = 'Hello World!'

   At the moment, constant variables cannot be used in certain places

   within the MPE engine.  If you are assigning a value to a variable,

   constant values will not be recongnized.

-----------------------------------------------------------------------

General Functions and Procedures

-----------------------------------------------------------------------

Function ABS (Num: LongInt) : LongInt

   This function takes a signed integer and returns the absolute value.

   Example:

   Var Int : LongInt = -1234

   WriteLn('The absolute value of '+Int2str(Int) +' is '+Abs(Int)+'.')

Function ALLOWARROW (Boolean)

   

   Used to turn on arrow key processing in the READKEY function.  It is

   also used outside of MPL so use with caution.

   Example:

   AllowArrow := True

   ReadKey

Variable ALLOWMCI (boolean)

   This function toggles on/off MCI code parsing.  This is used outside of

   MPL so adjust this with caution.

Procedure APPENDTEXT (FileName, Text: String).  

   This procedure will append a single line of text onto a text file.  If

   the file does not exist, it will be created.  Example:

Function BITCHECK (B : Byte; I : Integer) : Boolean

   This function accepts a bit position and checks it against an integer,

   returning true or false if the bit is on.  So for example in the

   Records, the third bit in UserFlags is UserDeleted:

   GetThisUser

   If BitCheck(3, UserFlags) Then WriteLn('User is marked deleted');

Procedure  BITSET (B : Byte; I : Integer)

   This procedure accepts a bit position and an integer and sets the

   bit ON/OFF based on a boolean:

   GetThisUser

   BitSet(3, UserFlags, True);  // user is marked as deleted

Procedure BITTOGGLE (B : Byte; I : Integer)

   This procedure accepts a bit position and an integer and toggles the

   bit.

   GetThisUser

   BitToggle(3, UserFlags);  // undeletes if they are deleted or deletes if

                             // they are not deleted.

Variables CFGCHATSTART CFGCHATEND.  

   These return the byte of the chat hour start and end variables from the

   System Configuration

Procedure CLRSCR

    This function will clear the screen.

    Example:

    CLRSCR

    Writeln ('The screen was just cleared.')

    The above function will clear the screen and write the text "The

    screen was just cleared." to the screen.

Function DATE2DOS (Str : String) : LongInt

    This function takes a MM/DD/YY format date and converts it to

    DOS packed datetime format.

    Var DStr : String = '01/01/14'

    Var PDt  : LongInt

    PDt := Date2Dos(DStr)

Function DATE2JULIAN (Str : String) : LongInt

    This function takes a MM/DD/YY format date and converts it to a

    Julian date format.

Function DATEG2J (Str : String) : LongInt

    This function takes a gregorian date format (MMDDYY) and converts

    it to a Julian format

Function DATEJ2G (LI : LongInt) : String

    This function takes a julian date format and converts it to a

    gregorian format (MMDDYY).

Function DATEJULIAN : LongInt

    This function returns the Julian value of the current date.

Function DATESTRJULIAN (JD : LongInt) : String

    This function returns the MM/DD/YY string value of the julian date.

Function DATEVALID (Str : String) : Boolean

    This function takes a MM/DD/YY date and returns true or false

    depending on if the date is valid (ie, month is 01-12, etc).

Function DAYOFTHEWEEK

    Returns a number between 0-6 depending on the day of the week:

    0 = Sun, 1 = Mon, 2 = Tue, 3 = Wed, 4 = Thu, 5 = Fri, 6 = Sat

Function DAYSAGO (JD : LongInt) : Integer

    This function takes the Julian date value and returns the number

    of days between the current date and the passed date.

Function DAYOFWEEK : Integer

    This function will return a number between 0-6 depending on the

    day of the week:

    0 = Sun, 1 = Mon, 2 = Tue, 3 = Wed, 4 = Thu, 5 = Fri, 6 = Sat

Procedure DELAY (MS: Word)

    This procedure will delay for a specified number of milliseconds.

    Example:

    DELAY (1000)

    The above example will delay the program for one second.

Function DOSERROR : Byte

    This function returns the current DosError and is used with the

    FindFirst and FindNext functions.  The possible values which may

    be returned by DosError are as follows:

    Value  Meaning

    -----  ---------------------

      0    No error

      2    File not found

      3    Path not found

      5    Access denied

      6    Invalid handle

      8    Not enough memory

     10    Invalid environment

     11    Invalid format

     18    No more files

    -----  ---------------------

    Example:

    FindFirst ('*.*', AnyFile)

    While DosError = 0 Do Begin

         WriteLn ('File Name: ', DirName)

         FindNext

    End

    FindClose                

    The above example will list all files in the current directory.

    The DosError function is used to return when there are no more

    files to be listed.  For more information on this see the reference

    for the FindFirst and FindNext functions.

Procedure FINDCLOSE

    This function is used along with the FindFirst and FindNext

    functions.  It is called only after all "Find" procedures have

    completed.  See the "FindFirst" and "FindNext" command references

    for more information.

Procedure FINDFIRST (Mask : String, Attributes)

    This function is used to search a drive for files using a supplied

    file mask and attribute list.  The results of the search are held

    in the DIR variables as listed below.

    Mask : The mask variable must contain at least a file mask

           (ie "*.*") but can also contain a drive and directory name

           as well (ie "C:\MYSTIC\TEXT\*.*").

    Attributes : The file attributes are used to specify what type of

                 files to return in the DIR variables.  The following

                 is a list of supported file attributes:

                 Dec Description Returns

                 --- ----------- -----------------

                 001 ReadOnly    files marked as "read only".

                 002 Hidden      files marked as "hidden".

                 004 SysFile     files marked as "system files".

                 008 VolumeID    files marked as "volume ID".

                 016 Directory   files marked as "directory".

                 032 Archive     files marked as "archive".

                 066 AnyFile     any and all files.

                 These attributes can be combined when passed to

                 FindFirst.  For example: 1 + 2 will return

                 any files which have been marked as "readonly" OR

                 "hidden".  Example: 16 (DIRECTORY) will only return names

                 of directories.

    DIR Variables : The DIR variables are what contain the information

                    returned by the FindFirst command.  If your program

                    is going to use these variables, it must be declared

                    with the USES statement at the beginning of your

                    program source code.  The following DIR variables

                    are supported:

                    DirName : Holds the file name.

                    DirSize : Holds the file size.

                    DirAttr : Holds the file attributes

                    DirTime : Holds the file date and time in packed

                              date format.  The DateSTR and TimeSTR

                              functions will need to be used in order

                              to display these.

    Example:

    USES DIR

    WriteLn ('The following files are in the C:\ directory:')

    WriteLn ('')

    FindFirst ('C:\*.*', 66)

    While DosError = 0 Do

    Begin

         WriteLn ('File Name: ', DirName)

         WriteLn ('     Size: ', DirSize)

         WriteLn ('     Date: ', DateSTR(DirTime), 0)

         WriteLn ('     Time: ', TimeSTR(DirTime), 1)

         Write   ('Press a key to search for more.~PN')

         FindNext

    End

    FindClose

    WriteLn ('No more files have been found.')

    The above example will list all files which fit the file mask of

    "C:\*.*" and fit the attributes of either ReadOnly or Archive.

    The DOSERROR function is used to determine when there are no more

    files found (See the DOSERROR reference).  If a file has been

    found, it will then be printed to the screen using the DIR

    variables.  The FindNext functon is used to find the next file

    that matches the name and attributes specified in the earlier call

    to FindFirst.  FindClose is used when all "Find" functions have been

    completed.

Procedure FINDNEXT

    This procedure is used to find the next file which matches the file

    mask and attibutes specified in the last call to FindFirst.

    Example:

    Uses DIR

    FindFirst ('*.*', 32)

    While DosError = 0 Do

    Begin

         WriteLn ('File Name: ', DirName)

         FindNext

    End

    FindClose

    The above example uses the FindFirst/FindNext functions to do a

    listing of all files in the current directory.  The DosError

    function is used to determine when no more files have been found.

Procedure GOTOXY (X: Byte, Y: Byte)

    This procedure will move the cursor to a specified X and Y

    position on the screen.  This only works for users who have ANSI

    graphics.

    Example:

    CLRSCR

    GotoXY (1, 10)

    WriteLn ('Hello')

    The above example will clear the screen then goto the first column

    of the tenth line and output the text "Hello" to the screen.

Procedure HALT

    This procedure will exit the program and return the user back to

    the BBS immediately.

    Example:

    If Graphics = 0 Do

    Begin

         WriteLn ('Sorry, you do not have ANSI graphics.')

         Halt

    End

    The above example will check to see if the user has ANSI graphics

    and if not, display "Sorry, you do not have ANSI" and exit the

    program immediately by using the HALT command.

Function INITIALS (String) : String

    This function takes a user name and attempts to return one or two

    character initials.

    S := Initials('Jack Phlash'); // should return "JP"

Function INPUT (Field: Byte, Max: Byte, Mode: Byte, Default: String) : String

    This function gives input to the user, and returns the result of

    the input as a string variable.

    The Field parameter is the size of the input field (in characters)

    that the user will be able to see.  If the field size is smaller

    than the maximum number of characters allowed in the input, the

    input line will scroll when the user reaches the end.  This field

    is usually set to the same as the Max parameter.

    The Max parameter is the maximum number of characters that

    Input will allow to be entered.  Note that the Field parameter, in

    most cases, should be set to the same value as this.

    The Mode parameter is the type of input that will be accepted, and

    can be any one of the following input types:

         1 : Standard input.  All characters allowed.

         2 : Upper case input.  Allows all characters, but will convert

             any lower case letters into upper case.

         3 : Proper input.  Allows all characters, but will convert

             the first letter in each word to an upper case letter.

         4 : Phone input.  Allows only numbers and will pre-format them

             using the USA-style phone numbers.  IE: XXX-XXX-XXXX.

             Note that the length of this input should always be 12,

             as that is the length of the USA phone number format.

         5 : Date input.  Allows only numbers and will pre-format them

             using the date format (ie XX/XX/XX) that is currently

             selected by the user.  NOTE: The date input will always

             return the date in the MM/DD/YY format, regardless of what

             format the user has selected.  For example, if the user

             has selected the DD/MM/YY format, Input will expect the

             user to enter the date in that format, but will then

             convert it to MM/DD/YY when it returns the date back to

             the MPE program.

         6 : Password input.  Allows all characters, but will convert

             any lower case letters into upper case.  The character

             that is typed is NOT echoed to the screen.  Instead, it

             is replaced by the * character so that what they have

             entered will not be shown on the screen.

          7: Lowercase Allows characters but will be lowercase.

    8: User Defined Input (from system config)

          9: Standard Input with no CR

         10: Number Input numbers only and +-

    NOTE: If any of the above input values are increased by 10, Input

    will create an input field using the foreground/background color

    that has been defined for that language.  For example, input type

    11 will function the same as input type 1, but will fill an input

    field to the maximum field length.

    The Default parameter can be used to force a default text into

    the input field.  If you do not wish to have any default text in

    the buffer, supply a blank string parameter (ie '').

    EXAMPLE:

    Var Str : String

    Write ('Enter something: ')

    Str := Input (30, 30, 1, '')

    The above example will print the text "Enter something: " to the

    screen and the allow input of up to 30 characters in length, using

    input type 1 (allows all characters).  No default text has been

    supplied so the input field will be empty by default.

    Var Str : String

    Write ('Enter something: ')

    Str := Input (30, 30, 11, 'Default')

    The above example will function just like the first example, except

    it will create an input field background and stuff the text of

    "Default" into the input field.

Function INPUTNY (Text: String) : Boolean

    This function prompts the user with a Yes/No question, defaulting

    to No. TRUE will be returned if the user answered Yes, or FALSE if

    the user answered No.  The passed Text variable is the text that is

    displayed to the user asking the question.

    Example:

    If Not InputNY('Do you want to run this program? ') Then

         Halt

    The above example will prompt the user with the Yes/No question

    passed as <Text>.  This question will default to No.  If the user

    answers No, the program will halt from being executed.

Function INPUTYN (Text: String) : Boolean

    This function prompts the user with a Yes/No question, defaulting

    to Yes.  TRUE will be returned if the user answered Yes, or FALSE

    if the user answered No.  The passed Text variable is the text

    that is displayed to the user asking the question.

    Example:

    If Not InputYN('Do you want to run this program? ') Then

         Halt

    The above example will prompt the user with a Yes/No question,

    asking "Do you want to run this program?".  If the user responds

    No, the program will not run, using the Halt command.

Function ISARROW : Boolean

    This function is used along with the READKEY function.  After

    READKEY is called, this function can be checked to process various

    extended keys, such as arrow keys.  When ISARROW is true, READKEY

    will return the following:

    ASCII #     Char     Key Pressed

    -------     ----     -----------

    71          G        Home

    72          H        Up Arrow

    73          I        Page Up

    75          K        Left Arrow

    77          M        Right Arrow

    79          O        End

    80          P        Down Arrow

    81          Q        Page Down

    83          S        Delete

    The character returned by READKEY can be checked by either the

    ASCII # or the actual character.  Below is an example:

    Example:

    Var Ch : Char

    Ch := ReadKey                 # Input one key

    If IsArrow Then               # Is key returned an arrow key?

      If Ch = 'H' Then

        WriteLn ('Up arrow')

      Else If Ch = Chr(80) Then

        WriteLn ('Down arrow')

    Else                          # No arrow key.  A normal character

      WriteLn ('You entered character: ', Ch)

    The above example reads a key with READKEY and then uses the

    ISARROW function to process the Up Arrow and Down Arrow keys.

Function ISUSER (String) : Boolean

    This function takes a string value which can contain either a user

    realname, handle, or user perm index number.  If the user exists,

    it will return a TRUE result or FALSE if the user does not exist.

Function KEYPRESSED : Boolean

    This function returns TRUE if a key has been pressed either

    remotely or locally.  Keep in mind two things about this

    function:

         (1) It doesn't check for inactivity timeout.  If you are

             using this function to wait for a key to be pressed then

             you may want to use the TIMER function and check for

             inactivity.

         (2) This function only returns whether a key was PRESSED.

             It does not actually read the key out of the buffer.

             See the READKEY function for reading keys from the

             buffer.

    Example:

    Repeat

    Until KeyPressed

    WriteLn ('You pressed a key!')

    The above example will wait for a key to be pressed and then

    write to the screen "You pressed a key!".

  Function MCI2STR (String) : String

    This function will take the value of the supplied 2-character MCI

    code (without pipe) and returns the string value of that code.

    Ex:

    Var BBSName : String

    

    BBSName:=MCI2Str('BN')

    WriteLn('The name of this BBS is "'+BBSName+'"')

  Function MCILENGTH (String) : Integer

    This function works just like LENGTH except it tries to ignore MCI

    codes.  It doesn't check for actual validity of MCI codes.

    Var B : Byte;

    B := MCILength('|15Hello|UH');

    WriteLn ('Length should be 5: ' + Int2Str(B));

  Function MOREPROMPT : Char

    This function displays the system more prompt and returns a Char

    value of either Y N or C depending on what the user selected.

    Var C : Char

    C:=MorePrompt

Procedure MOVEX (Pos : Byte)

        This procedure is used to move the cursor to the passed X coordinate

        on the screen.  It only works if the user has ANSI graphics enabled.

        Example:

        MoveX (20)

        WriteLn ('This text starts on the 20th space')

Procedure MOVEY (Pos : Byte)

        This procedure is used to move the cursor to the passed Y coordinate

        on the screen.  It only works if the user has ANSI graphics enabled.

        Example:

        MoveY (10)

        WriteLn ('This is on the 10th line of the screen')

Function PARAMCOUNT : Byte

    This function is used to determine the number of command line

    options which have been passed to the MPE program.  For more

    information, see the PARAMSTR function.

    Example:

    If ParamCount < 2 Then Begin

         WriteLn ('Invalid command line.')

         Halt

    End

    The above example will check to see if less than 2 command line

    options have been passed to the MPE program.  If there are less

    than two, the program will terminal with a "invalid command line"

    message.

Function PARAMSTR (Number : Byte) : String

    This function returns the command line option specified by the

    NUMBER parameter.  A command line is the optional data which

    is passed on the "Data" field of a menu command.  For example,

    when defining a menu command which executes an MPE program in

    the menu editor, the text after the program name becomes command

    line options.

    Menu Command: GX

    Data        : BULLETIN p1 p2 p3 p4

    If the above was defined in the menu editor, the following would

    be true:

    ParamCount  would return 4

    ParanStr(0) would return "BULLETIN"

    ParamStr(1) would return "p1"

    ParamStr(2) would return "p2"

    ParamStr(3) would return "p3"

    ParamStr(4) would return "p4"

    Note that ParamStr(0) will ALWAYS return the file name of the

    MPE program being executed.  Even when there are no other

    parameters defined.

Procedure PAUSE

    Envokes the Mystic pause prompt as defined in the current

    language file.

Function PAUSEPOS : Byte

 

    This function gives access to Mystic's internal line

    counter used for screen pauses.

Function RANDOM (Max: Word) : Word

    This function will return a random number within the range

    specified.

    Example:

    Var A : Byte

    A := Random(255)

    WriteLn (A)

    The above example will generate a random number within the range

    of 0 to 255 in the variable A and then print it to the screen.

Function READKEY : Char

    This function will read a key from the buffer and return it as

    a char variable.  If there are no keys in the buffer, readkey will

    wait for a key to be pressed.

    Example:

    Var Ch : Char

    Repeat Until KeyPressed

    Ch := ReadKey

    WriteLn ('You entered: ', Ch)

    The above example will wait for a key to be pressed by using the

    KEYPRESSED function.  Afterwards, the key will be read into the

    CH variable using readkey, and then print it to the screen.

Procedure SETPROMPTINFO (N : Integer; S : String)

   This allows you to set Mystic's internal "changing" PromptInfo MCI

   codes (the |&X codes).  For example:

   SetPromptInfo(1, 'Hello!');

   WriteLn ('This MCI code would like to say: |&1');

   As a side note, there is NOT a GetPromptInfo because you can simply use

   MCI2STR:

   WriteLn('This MCI code would like to say: ' + Mci2Str('&1'));

Procedure STUFFKEY (S : String)

    This function will stuff a string of text into the keyboard

    buffer.  This can be used to force your program into thinking

    the user had actually typed <S>.

    Example:

    Var Ch : Char

    StuffKey ('A')

    Ch := ReadKey

    WriteLn ('You entered: ', Ch)

    The above example will stuff the character "A" into the input

    buffer, where it will be read into Ch using the ReadKey function.

    It is possible to stuff entire strings of text into the buffer

    too.

    Example:

    Var Str : String

    StuffKey 'Hello World'

    Str := Input (20, 20, 1, '')

    The above example will stuff "Hello World" into the input buffer.

    This will cause the input function to think the user has actually

    typed in "Hello World".  In this case, the above is the same as

    supplying "Hello World" in the <DEFAULT> field of the Input

    function.

Function TIMER : LongInt

    This function will return the current number of seconds which have

    passed since midnight.  This function can be used to time how long

    a user is doing something.

    Example:

    Var StartTime : LongInt

    Var EndTime   : LongInt

    Var Total     : LongInt

    Var Str       : String

    StartTime := Timer

    Write ('Enter something: ')

    Str := Input (40, 11, 'Nothing')

    EndTime := Timer

    Total := EndTime - StartTime

    WriteLn ('You took ', Total, ' seconds to type something!')

    The above example will prompt the user to type something and time

    how long in seconds they took.  WriteLn will then display the

    number of seconds the user took to the screen.

Function TIMERMIN : LongInt

    This function works just like TIMER except returns minues

    instead of seconds.

Function WHEREX : Byte

    This function returns the current X coordinate of the cursor.

    Example:

    Var X : Byte

    Var Y : Byte

    X := WhereX

    Y := WhereY

    WriteLn ('      World')

    GotoXY  (X, Y)

    WriteLn ('Hello')

    The above example will save the current X and Y cursor positions

    and then write the text "World" to the screen.  After which, it

    will return to the saved X and Y position and write the text

    "Hello" to the screen.  The end result will be the text of

    "Hello World" written to the screen.  Note: GotoXY can only be

    used if the user has ANSI graphics mode.

Function WHEREY : Byte

    This function returns the current Y coordinate of the cursor.

    For more information on this function, please see the definition

    of the WHEREX function.

Procedure WRITE (Text)

    This procedure is used to write text to the screen without

    going to the next line (ie, without sending a carriage return).

    All text to be printed to the screen should be enclosed inside of

    ' characters.  If you wish to print the value of a variable to

    the screen, just include the variable name without the '

    characters.  If you wish to combine multiple text and variables,

    they must be separated by commas.

    Examples:

    Write ('Hello ')

    Write ('World')

    This example will write the text "Hello World" to the screen.

    Write ('Hello World')

    This example does the exact same thing as the function above, but

    makes a little more sense.

    Var Str : String

    Str := 'Hello World'

    Write (Str)

    This example will write the value held in the variable Str to the

    screen.  The resulting output will be "Hello World"

    Var Str : String

    Str := 'Hello '

    Write (Str, 'World')

    This example will write the value of the variable Str to the

    screen, followed by the text "World".  The resulting output will

    be "Hello World".  An unlimited number of variables and text can

    be outputted with the Write statement, but they must all be

    separated by a comma, as shown above.

    If a ' character needs to be printed to the screen, it can be done

    by doubling the ' character.  For example:

    Write ('This is how it''s done.')

    The resulting screen output will be "This is how it's done", with

    only one ' character.

    All MCI display codes can be used within the Write statement.  If

    you wish to change the display colors, use the MCI color system to

    do so.  For example:

    Write ('~14Hello World')

    This example will write the text Hello World in yellow to the

    screen.  All MCI display codes are available to the write

    statement.

Procedure WRITELN (Text)

    This procedure outputs text to the screen.  It functioning is

    identical to the WRITE statement except that it goes to the next

    line after the text is printed (ie, it sends a carriage return).

    For example:

    WriteLn ('Hello')

    WriteLn ('World')

    The above example will write the text "Hello" on one line, and

    then the text of "World" on the next line.

Procedure WRITEPIPE (Text)

    This function works just like WRITE but only parses pipe color

    codes instead of all MCI codes.

Procedure WRITEPIPELN (Text)

    This procedure works just like WRITEPIPE but with a CRLF at the end.

Procedure WRITERAW (Text)

    This procedure works just like WRITE except it does not parse

    any pipe color codes OR MCI codes.

Procedure WRITERAWLN (Text)

    This procedure is the same as WRITERAW, but with a CRLF at the end.

Procedure WRITEXY (X,Y,Z: Byte; Str : String)

    This procedure writes a string of text at the defined X/Y location with a

    specific text color attribute 'Z'.  This of course requires the user has

    ANSI to function properly.  This function will NOT parse MCI pipe codes.

    Example:

    WriteXY (1, 10, 8, 'Prints at X:1 Y:10 with dark grey text');

Procedure WRITEXYPIPE (X,Y,Z: Byte; Len: Integer; Str : String)

    This procedure writes a string of text at the defined X/Y location with a

    specific text color attribute 'Z'.  This of course requires the user has

    ANSI to function properly.  This function will NOT parse MCI pipe codes.

    Example:

    WriteXYPipe (1, 10, 8, 50, 'This pads to 50 chars at location 1,10');

-----------------------------------------------------------------------

String Handling Functions and Procedures

-----------------------------------------------------------------------

Function ADDSLASH(S: String) : String

   takes a directory and appends the appropriate ending backslash or

   forward slash depending on operating system.  If the slash is already

   there, it does nothing.

Function CHR (B: Byte) : Char

    This function will take a numerical byte value and return it's

    ASCII character.  The byte value must be between 0 and 255 as

    there are only 255 characters in the ASCII character set.

    Example:

    WriteLn ('Hello', Chr(32), 'World')

    This will output the text "Hello World" to the screen.  The ASCII

    number for the space character is 32 and by passing a 32 to CHR,

    a space is returned.

Function COPY (S: String, Index: Byte, Count: Byte) : String;

    This function will copy a defined part of a string and return

    the copied portion as a string.

    Example:

    Var Str : String

    Str := 'Hello World'

    WriteLn (Copy(Str, 1, 5))

    This will output "Hello" to the screen.  The copy function takes

    the given Str and copies Count number of character from the Index.

    So the above copies 5 characters starting at the 1st character in

    Str and WriteLn outputs it to the screen.

Procedure DELETE (S: String, Index: Byte, Count: Byte)

    This procedure will delete a defined portion of a string

    variable.

    Example:

    Var Str : String

    Str := 'Hello World'

    Delete (Str, 6, 6);

    WriteLn (Str)

    This example will delete 6 characters from the string Str starting

    at the 6th character.  The resulting output from WriteLn will be

    "Hello"

Function FillChar (V: Variable; S: LongInt; C Char ): String

    Fills variable V with Char C for S size.

    type

      myuserrecord = record

      username  : string[30];

      somevalue : array[1..5] of byte;

    end;

    var

      u : myuserrecord;

    begin

      fillchar(u, sizeof(u), #0);

    end.

Procedure INSERT (Source: String, Target: String, Index: Byte)

    This procedure will insert text into a string at a specified

    location.

    Example:

    Var Str : String

    Str := 'Mystic v1.00'

    Insert ('BBS ', Str, 8)

    WriteLn (Str)

    The above example will insert the text "BBS" into the Str variable

    starting at the 8th character in the string.  The result WriteLn

    output would be "Mystic BBS v1.00"

Function INT2STR (L: LongInt) : String

    This function converts a numerical type variable to a string

    type variable.

    Example:

    Var A : Byte

    Var S : String

    A := 255

    S := Int2Str(A)

    WriteLn (S)

    The above example sets the numerical variable to the value of

    255, which is then converted to a string variable using Int2Str.

    The resulting value of S will be '255' as WriteLn will output to

    the screen.

Function LENGTH (S: String) : Byte

    This function returns the length in characters of the passed

    string variable.

    Example:

    WriteLn (Length('Hello World'))

    The above example would output "11" to the screen, which is the

    number of characters in the text passed to Length.

Function LOWER (S: String) : String

    This function converts a passed string variable to all lower

    case letters.

    Example:

    WriteLn (Lower('HELLO'))

    The above statement would output the text "hello" to the screen.

    The original text of HELLO is converted to all lower case letters

    and than displayed by WriteLn.

Function ONEKEY (Keys : String; Echo : Boolean) : Char

    This function accepts a string of uppercase letters, and wait for

    input from the user.  If the keystroke is among the characters in

    Keys, it will return that character.  If the keystroke is not among

    the Keys string, it will do nothing.  If Echo is set to TRUE, it

    will also echo the Key to the screen.

    Var Ch   : Char

    Var Keys : String = 'ABCDQ'

    Ch := OneKey(Keys,True)

    WriteLn('You selected '+Ch+'.')

Function ONEKEYRANGE (String, Int, Int ) : Char

    This function works similar to OneKey, except that it will also allow

    for a number input within a certain range.  The number value is

    stored in a variable called RangeValue and the function returns a #0

    if a number was entered.  For example:

    Var

      Ch : Char;

    Begin

      Write ('Enter letters A-G or a number between 1-50: ');

      Ch := OneKeyRange('ABCDEFG', 1, 50);

      If Ch = #0 Then

        WriteLn ('You entered a number: ' + Int2Str(RangeValue))

      Else

        WriteLn ('You entered character: ' + Ch);

    End.

Function ORD (C: Char) : Byte

    This function returns the ASCII code of the passed Char variable.

    This function works the exact opposite of the CHR function.

    Example:

    WriteLn (Ord(' '))

    The above example would output the text "32" to the screen because

    32 is the ASCII character code for space.

Function PADCT (S: String, N: Byte, C: Char) : String

    This function pads a string to the center with the specified

    character.

    Example:

    Var Str : String

    Str := PadCT('Hello World', 80, ' ')

    WriteLn (Str)

    The above example would display the text "Hello World" centered on

    the screen.  The PadCT function returns the text "Hello World"

    centered in 80 spaces with the character of " " used to fill the

    blank spaces.

Function PADLT (S: String, N: Byte, C: Char) : String

    This function returns a text string padded with spaces to the

    left side.

    Example:

    Var Str : String

    Str := PadLT('Hello World', 79, ' ')

    The above example would return a string which is 79 characters in

    length with the text "Hello World" as the leftmost part of the

    string.  The passed character is the character that is used to

    fill the blank spaces.

Function PADRT (S: String, N: Byte, C: Char) : String

    This function returns a text string padded with spaces to the

    right side.

    Example:

    Var Str : String

    Str := PadRT('Hello World', 79, ' ')

    The above example would return a string which is 79 characters in

    length with the text "Hello World" being the rightmost part of the

    string.  The empty spaces are filled with the passed charcter (in

    this case ' ').

Function POS (Sub: String, S: String) : Byte

    This function returns the starting position of a substring in a

    string.

    Example:

    Var A : Byte

    A := POS('World', 'Hello World')

    WriteLn (A)

    The above example would output "7" to the screen becase POS

    returns the position of the text "World" in the string

    "Hello World".  If POS does not find a match, a zero will be

    returned.  IE: A := POS('Blah', 'Hello World') would return a zero

    because the text "Blah" was not found in the string "Hello World".

Function REPLACE(Str1, Str2, Str3 : String) : String

    This function replaces all occurances of a supplied text and

    returns a string.  Ex:

    Var Str : String = 'Hello Hello Hello';

    Str := Replace(Str, 'Hello', 'World');  // Str is now World World World

Function STRCOMMA(LI : LongInt) : String

    This function  accepts a longint and returns it as a string, with

    commas added where applicable:

    Ex:

    WriteLn (strComma(1000000));  // will print 1,000,000

Function STR2INT (S: String) : LongInt

    This function converts a passed string variable to a numerical

    variable.  The passed string variable must contain a valid number.

    Example:

    Var A : Byte

    Var S : String

    S := '100'

    A := Str2Int(S)

    WriteLn (S)

    WriteLn (A)

    The above example will output "100" twice the screen.  The

    variable S is assigned to '100' and the function Str2Int converts

    the string into a numerical value which is assigned to variable

    A.

Function STRIPB (S1, S2 : String) : String

    This function strips both sides of the string if a specific character.

    Var S : String = '     Hello     ';

    S := StripB(S, ' ');

Function STRIPL (S1, S2 : String) : String

    This function strips the left side of a string of any specified

    leading characters.

    Var S : String = '    Hello';

    S := StripL(S, ' ');

Function STRIPR (S1, S2 : String) : String

    This function strips the right side of a string of any specifcied

    trailing character:

    Var S : String = 'Hello     ';

    S := StripR(S, ' ');

Function STRIPLOW (String) : String

    This function strips all chracters from a string that are less than

    ascii code #32.

    Var S : String = #12#12#12#12 + 'Hello';

    S := StripLow(S);

Function STRIPMCI (S : String) : String

    This function will strip the passed string variable of all MCI

    codes and return the "cleaned" version.

    Example

    Var S : String

    S := '|10|H|02ello |10W|02orld|07'

    WriteLn ('Normal   : ', S)

    WriteLn ('Stripped : ', StripMCI(S))

    The above example assigns a string with MCI codes in it to the S

    variable.  It then writes the original string and the stripped

    string to the screen, so the difference is shown.

Function STRIPPIPE (String) : String

    This function takes a string and strips only pipe color codes

    from it.

    S := StripPipe('|15Hello there, |UH');  //returns "Hello There, |UH"

Function STRMCI (String) : String

    This function takes an entire string and attempts to translate any

    MCI codes found in it, returning the entire result.

    S := StrMci('Hello |UH');

Function STRREP (Ch: Char, Num: Byte) : String

    This function returns a string filled with character <CH> to the

    length of <NUM>.

    Example:

    WriteLn (strRep('-', 60 ))

    The above example will use strRep to create a string 60 characters

    long of the character '-', then write it to the screen.  So the

    outputted text would look like:

    "------------------------------------------------------------"

Function STRWRAP(Str, Str2 : String; Len: Integer) : Byte

    This function takes two strings and wraps them after the word closest

    to the maximum supplied length.  It optionally returns the actual

    position where it wrapped.

    Var Str   : String = 'This will wrap';

    Var Str2  : String = '';

    Var Where : Byte;

    Where := strWrap(Str, Str2, 10);

    WriteLn ('It wrapped at ' + Int2Str(Where));

    WriteLn ('First string: ' + Str);

    WriteLn ('Second string: ' + Str2);

Function UPPER (S: String) : String

    This function coverts the passed string variable to all upper

    case letters.

    Example:

    WriteLn (Upper('hello'))

    The above example would output the text "HELLO" to the screen.

    The UPPER function converts the passed text of "hello" to all

    upper cased letters, which is then printed to the screen by

    WriteLn.

Function WORDCOUNT (S,C: String) : Integer

    Function WordCount returns the number of words in a string using

    the final parameter to define the character that determines what

    separates words.  Ex:

    Str := 'Hello this is a test';

    WriteLn ('Str has ' + Int2Str(WordCount(Str, ' ')) + ' words in it.');

Function WORDGET(I : Integer, S, C : String) : String

    returns the actual word at a specific word count.

    S is the inputted string value.

    I is the numerical value of the position where the word can be found.

    C is the string value used as the word separater.

    Ex:

    Str := 'Hello this is a test';

    WriteLn('The second word was: ' + WordGet(2, Str, ' '));

Function WordPos (I : Integer; S, C : String ) : Integer

    Function WordPos returns the character position in the string where

    specific word is located.

    S = Inputted string value

    I = Index value of the the desired word within S

    C = String value of the word separater.

    Ex:

    Str := 'Hello this is a test';

    WriteLn ('Second word is at: ' + Int2Str(WordPos(2, Str, ' ')));

    See Also : WordCount, WordGet

-----------------------------------------------------------------------

File Accessing Functions and Procedures

-----------------------------------------------------------------------

Function FEOF (Handle) : Boolean

    This function will return true if the file position of an opened

    file is at the End Of the File (EOF).  The passed Handle value is

    the file number of the already opened file.

    Example:

    Var Str : String

    Var Fpt : File

    FOpen (1, Text, Reset, 'BLAH.TXT')

    While Not Eof(1)

         FReadLn (1, Str)

         WriteLn (Str)

    End

    FClose (1)

    The above example will open a text file under the filename of

    BLAH.TXT.  The WHILE loop is used to repeat the code until the

    EOF (end of file) is reached.  The FCLOSE statement will close

    the file after it is done being accessed.

    The result of the above example will be (in pseudocode):

    1. Open text file.

    2. If not at the end of file, run this code:

        3. Read line from text file into string variable

        4. Print line read from text file to the screen.

        5. Goto 2.

    6. Close the text file.

    So the above example will basically write the entire text file to

    the screen.

Procedure FCLOSE (File)

    This procedure closes an already opened file.  The passed Handle

    value is the file number of the opened file.  All files which

    are opened MUST be closed after they are not being accessed any

    more.

    For example:

    Var Fptr : File

    fAssign  (Fptr, 'BLAH.TXT', 66)

    fReWrite (Fptr)

    <Code to access file goes here>

    fClose (Fptr)

    The above example opens a file using the FOPEN procedure.  When

    the file has been opened successfully, it can be accessed in

    various ways using the file I/O functions.  Afterwards, it MUST

    be closed using the FCLOSE procedure as shown above.

Function FILECOPY (Source: String, Dest: String) : Boolean

    This function will copy a file from the specified source location

    to the specified destination location.  The function will return

    as TRUE if the file was copied successfully, or FALSE if an error

    occured.  Note:  The file which is being copied should not already

    be opened for File I/O by the program.

    Example:

    Write ('Copying C:\HELLO.TXT -> D:\HELLO.TXT: ')

    If fileCopy ('C:\HELLO.TXT', 'D:\HELLO.TXT')

         WriteLn ('OK')

    Else

         WriteLn ('ERROR')

    End

    The above example will attempt to copy the file "C:\HELLO.TXT" to

    the destination of "D:\HELLO.TXT".  If the file is copied without

    any problems an "OK" will be printed to the screen.  If an error

    occured while copying, "ERROR" will be printed to the screen.

Procedure FILEERASE (FileName: String)

    This procedure is used to erase an existing file from the disk.

    The FileName variable is a string variable which contains the

    file name which is to be erased.  The result of the FILEERASE

    procedure can be checked by checking the DOSERROR function.

    DOSERROR will return a 0 if successful or a 2 if an error occured.

    Example:

    FileErase ('C:\HELLO.TXT')

    The above example will erase the file "C:\HELLO.TXT" if it exists.

Function FILEEXIST (FileName: String) : Boolean

    The above function will check to see if a file exists, and return

    TRUE if it does.  The passed FileName string if the path and file

    name of the file to check.  This file should not already be opened

    with the FOPEN procedure.

    Example:

    If FileExist('BLAH.TXT') Then

         WriteLn ('BLAH.TXT exists.')

    Else

         WriteLn ('BLAH.TXT does NOT exist.')

    The above example will check to see if the file "BLAH.TXT" exists

    and if it does, will output "BLAH.TXT exists" to the screen.  If

    BLAH.TXT does NOT exist, the output will be "BLAH.TXT does NOT

    exist".

Function FPOS (File) : LongInt

    This function returns the current file position of an opened

    file.  The passed Handle is the file handle number used when the

    file was opened.  The FilePos function only works for files that

    are opened as Binary, since Text files are read line by line.

    Example:

    Var Fptr : File

    fAssign (Fptr, 'TEST.DAT', 66)

    fReset(Fptr)

    If IORESULT = 0 Then Begin

       If fPos(Fptr) = FSize(Fptr)

          WriteLn ('END OF FILE.')

       End

       fClose (fPtr)

    End

    The above example opens the file "TEST.DAT" for binary and then

    writes to the screen if the file position is at the end of the

    file.  The above statement "fPos(Fptr) = fSize(Fptr)" is the same

    as "fEof(Fptr)" since it's stating "if the file position is equal to

    the total file size, then we're at the end of the file."

Function FSIZE (File) : LongInt

    This function returns the total file size of an opened file.  The

    passed Handle is the file handle number used when the file was

    opened.  This function only works with files that have been opened

    as Binary since Text files are read line by line.

    Example:

    Var Fptr : File

    fAssign (Fptr, 'TEST.DAT', 66)

    fReset(Fptr)

    If IoResult = 0 Then

        WriteLn ('This file is ', fSize(Fptr), ' bytes in size.')

    fClose (Fptr)

    The above example opens the file "TEST.DAT", writes the size of

    the file to the screen, and then closes the file.

Procedure FASSIGN (Fptr : File, Mask : String, Attr : Int)

    This procedure opens a text or binary file for file operations.

    Fptr  : The passed file pointer is the file reference, of type FILE

    Mask  : The path and filename of the file to open, in string format.

    Attr  : File attributes to open.  See FINDFIRST for more info.

    EXAMPLE:

    Var Fptr : File  

    fAssign (Fptr, 'BLAH.TXT', 66)

    fReWrite (Fptr)

    fWriteLn (Fptr, 'Hello World!')

    fClose (Fptr)

    The above example creates a text file under the name 'BLAH.TXT'.

    If BLAH.TXT already exists, it will be erased and replaced by a

    new BLAH.TXT file.  The FWriteLn writes the text "Hello World" to

    the file, and then FClose closes the file.

Procedure FRESET (File)

    This procedure moves the file pointer to the beginning of an already

    opened file.  This is useful for moving the file pointer to specific

    spots in the file, without having to close and reopen the file.  The

    file must have previously been opened by FASSIGN.

    Use IORESULT to determine if the freset command was successful.

    Var fPtr : File

    fAssign(Fptr,CfgDataPath+'somefile.dat',66)

    fReset(Fptr)

    If IORESULT = 0 Then Begin

       WriteLn('somefile.dat is opened for use!')

       WriteLn('closing somefile.dat!')

       fClose(Fptr)

    End Else

       WriteLn('Unable to open somefile.dat')

     

Procedure FREWRITE(File)

    This procedure will this will erase an existing file and recreate it,

    leaving the file position at the beginning of the file.  If the

    file does not already exist, MPL will create the file.  The file must

    have previously been opened by FASSIGN.

Procedure FSEEK (Fptr: File, Position: LongInt)

    This procedure seeks to a file position in a binary file.  It

    will only work on binary files, not text file.

    Fptr : The passed file pointer value of type FILE

    Position : This is the position where FSEEK will seek to.

    EXAMPLE:

    Var Str : String

    Var Fptr: File

    Str := 'Hello World!'

    fAssign   (Fptr, 'BLAH.DAT',66)

    fSeek     (Fptr, FileSize(1))

    fWriteRec (Fptr, Str, 12)

    fClose    (Fptr)

    The above example opens an already existing file under the name

    'BLAH.DAT'.  Using FSEEK, it will seek to the end of the file,

    so that "Hello World" can be added as the last record.

Procedure FREAD (File, Str, Int)

    This procedure is used to read binary data from a file.

    Type FileInfo = record

       Index : Integer

       Name  : String [50]

       Data  : Integer

    End

    Var fptr : File

    Var info : FileInfo

    Var Recno: Integer = 3

    fAssign(Fptr,'FILE.DAT',66) // Open the file

    fReset(Fptr) // Reset to the beginning of the file

   If IoResult = 0 Then Begin  // If successful...

      fSeek(Fptr,(Recno-1)*SizeOf(Info)) // Go to 3rd record in the file

      If Not fEof(Fptr) Then // If the 3rd record is there...

         fRead(Fptr,Info,SizeOf(Info)) // Read the record

         // Optionally, use FreadRec(Fptr,Info) when reading record types.

    End

    fClose(Fptr) // close the file

Procedure FREADLN(File,Str)

    This procedure will read string data from a text file.

    Var fptr : File

    Var Str  : String

    fAssign(Fptr,'somefile.txt',66)

    fReset(Fptr)

    If IoResult = 0 Then Begin

       While Not fEof(Fptr) Do Begin

          FReadLn(Fptr,Str)

          WriteLn(Str)

       End

       fClose(Fptr)

    End

Procedure FWRITE (File, Str, Int)

    This procedure is used to write binary data to a file.

    Type FileInfo = record

       Index : Integer

       Name  : String [50]

       Data  : Integer

    End

    Var fptr : File

    Var info : FileInfo

    info.Index:=1

    info.Data:=33

    info.Name:='newname'

    fAssign(Fptr,'FILE.DAT',66)

    fReWrite(Fptr)

    fWrite(Fptr,Info,SizeOf(Info))

    fClose(Fptr)

Procedure FWRITELN(File,Str)

    This procedure is used to save string data to a text file.

    Var Fptr : File

    Var Str  : String = 'I am a string value!'

    fAssign(Fptr,'flatfile.txt',66)

    fReset(Fptr)

    If IoRESULT = 0 Then Begin

       // File already exists.

       // Seek to the end of the file.  aka append to the file

       fSeek(Fptr,FSize(Fptr))

    End Else Begin

       // File is not yet created.  Create it now.

       fReWrite(Fptr)

    End

    fWriteLn(Fptr,Str)

    fClose(Fptr)

Function SIZEOF (Type) : LongInt

    This function will take any named data type as input, and return

    the size of the data.

    Type TypeOfData = Record

      N : Integer

      L : Real

      V : LongInt

      Q : String [32]

    End

    Var I : Integer

    Var S : String [50]

    Var R : Real

    Var T : TypeofData

    WriteLn('Size Of I = '+Int2Str(SizeOf(I)))

    WriteLn('Size Of S = '+Int2Str(SizeOf(S)))

    WriteLn('Size Of R = '+Int2Str(SizeOf(R)))

    WriteLn('Size Of T = '+Int2Str(SizeOf(T)))

-----------------------------------------------------------------------

BBS Related Functions and Procedures

-----------------------------------------------------------------------

Function ACS (S: String) : Boolean

    This function processes an ACS string and returns true if the user

    has passed.

    Example:

    If ACS('s10g1') Then

         WriteLn ('You have access to this.')

    Else

         WriteLn ('Sorry, you do not have access.')

    The above example checks to see if the user passes the ACS string

    of "s10g1" and prints the result to the screen.

Function DATESTR (DT: LongInt, dType: Byte) : Integer

    This function will take a packed datetime number and convert it to

    a date string.  The dType parameter is used to set the format of the

    date which is returned.  Valid types are:

         UserDateType  = Returns date in the users date format

         1 = Returns date in format: MM/DD/YY

         2 = Returns date in format: DD/MM/YY

         3 = Returns date in format: YY/DD/MM

    Example:

    GetThisUser

    WriteLn ('Welcome.  You last called on ', DateStr(UserLast))

    The above example loads the currently logged in user's information

    into the USER variables using GETTHISUSER, then displays the last

    time the user has called to the screen using the DATESTR procedure.

Function DATETIME : LongInt

    This function returns the current Date and Time in the packed

    format.  DATESTR and TIMESTR can be used to convert this value

    into strings.

    Example:

    WriteLn ('Current Date: ', DateStr(DateTime), 0)

    WriteLn ('Current Time: ', TimeStr(DateTime), 1)

    The above example outputs the current date and time to the screen

    using the DATESTR and TIMESTR functions.  The DateTime function

    which is passed to DATESTR and TIMESTR, contains the current date

    and time in the packed format.

Function DIREXIST (S : String) : Boolean

    This function returns TRUE or FALSE if a directory exists.

    If DirExist('C:/MYSTIC/TEMP46') Then

       WriteLn('Dir C:/MYSTIC/TEMP46 exists!')

    Else

       WriteLn('Dir C:/MYSTIC/TEMP46 does not exist!')

Procedure DISPFILE (FN: String)

    This procedure displays a text or ANSI file to the screen.  If a

    path not included in the passed filename, Mystic will look for

    the file in the language text file directory.  If no file

    extension is provided in the passed file name, Mystic will display

    the correct file according to the user's graphics settings

    (ie .ANS for ANSI, .ASC for non-ansi).

    Example:

    DispFile ('WELCOME')

    The above example will display the text file "WELCOME" from the

    language text file directory.  Since there is no file extension

    provided, Mystic will display "WELCOME.ANS" or "WELCOME.ASC"

    depending on what the user's terminal settings are.

Procedure FILLCHAR (R : Record; S : Integer; V : Value )

    Fillchar fills the memory starting at X with Count bytes or

    characters with value equal to Value.

    type

    myuserrecord = record

      username  : string[30];

      somevalue : array[1..5] of byte;

    end;

    var

      u : myuserrecord;

    begin

      fillchar(u, sizeof(u), #0);

    end.

Procedure GETCFG

    This procedure will load the current configuration data into the

        CFG variables.  The "USES CFG" command must be used at the start

        of your program for GETCFG to work.  The following variables will

        be loaded:

    CFGSYSPATH     : System Path

    CFGDATAPATH    : Data Path

    CFGMSGSPATH    : Message Base Path

    CFGPROTPATH    : Protocol Path

    CFGQWKPATH     : Local QWK Path

    CFGMPEPATH     : Script (MPE) Path

    CFGATTPATH     : File Attach Path

    CFGLOGSPATH    : System Logs Path

    CFGTEXTPATH    : Text Files Path (for the current language)

    CFGTEMPPATH    : Temp path for the current node

    CFGMENUPATH    : Menu Files Path (for the current language)

    CFGTIMEOUT     :

    CFGSEEINVIS    : Gives the "See Invisible" ACS value

    CFGTNNODES     : Number of max telnet nodes to allow

    CFGNETDESC[1..30]     : Give the network descriptions.

    Example:

        Uses CFG

        GetCFG

    WriteLn ('Mystic BBS is installed in ', CfgSysPath)

    The above example will load the configuration into the CFG

    variables, and then print the directory where Mystic BBS is

    installed in to the screen.

Function GETATTRXY (X, Y : Byte) : Byte

    This function returns the attribute of the character at position

    XY on the user's screen:

    Var Attr : Byte;

    Attr := GetAttrXY(1, 1);

    WriteLn ('The attribure of the character at 1,1 is: ' + strI2S(Attr));

Function GETCHARXY (X, Y : Byte) : Char

    This function returns the character located on the user's

    screen at the XY location.

    Var Ch : Char;

    Ch := GetCharXY(1, 1);

    WriteLn('The user has the following character at 1,1: ' + Ch);

    This kind of stuff could allow you to create MPL-based custom screen

    effects like TheDraw used to have, except for on-the-fly with whatever

    is on the user's screen.

Function GETMBASE (N : Word) : Boolean

    This procedure will read message base data into the MBASE variables.

    The supplied N is the record number to read.  The function will

    return TRUE if the record was read successfully, or FALSE if the

        record was not read.  The "USES MBASE" command must be called at

        the start of your program for the MBASE functions to work

        correctly.

    The following MBASE variables will be set when a record is read:

    Variable Name   Type     Description

    -------------------------------------------------------------------

    MBASENAME      String    Name

   MBASEACS       String    ACS level

   MBASERACS      String    Read ACS level

   MBASEPACS      String    Post ACS level

   MBASESACS      String    SysOp ACS level

   MBASEINDEX     Integer   Index number (*NEVER* change this)

    Example:

    Var A Word

    A := 1

    While GetMBase Do

    Begin

         WriteLn ('Base name: ', MBaseName)

         A := A + 1

    End

    The above example will list all available message base systems on

    the BBS.

Function GETMBASESTATS (Base : LongInt; B1, B2 : Boolean; Tot, New, Yours : LongInt) : Boolean

     This can be used as a function or a procedure (returning true if

     successful).  It takes 6 parameters.

     #1: Message base number

     #2: Exclude messages FROM the current user in stats

     #3: Exclude messages TO the current user that have already been read

     #4: Total messages (this is a VAR parameter)

     #5: New messages (this is a VAR parameter)

     #6: New messages to you (this is a VAR parameter)

     Example:

     uses mbase;

     var

       count, total, new, yours : longint;

     begin

     count := 1;  //start @1 to skip email base

     while getmbase(count) do begin

       getmbstats(count, true, true, total, new, yours);

       writeln('base       : ' + mbasename);

       writeln('total msgs : ' + int2str(total));

       writeln('new msgs   : ' + int2str(new));

       writeln('your msgs  : ' + int2str(yours));

       writeln('');

       count := count + 1

     end;

Function GETMBASETOTAL (Compress : Boolean) : LongInt

    This function returns the total message bases on the system.  If

    Compressed is true, then it will return the total number of message

    bases the user has access to (slower to calculate).  If it is false,

    it returns the raw total number of bases on the system.

Function GETPROMPT (N : Word) : String

    This function will return a prompt from the current user's language

    file.  The passed N varliable is the prompt number to return.

    Example:

    WriteLn(GetPrompt(1))

    The above example writes prompt #1 from the user's currently

    selected language file to the screen.

Procedure GETSCREENINFO (I, X, Y, Attr : Integer)

    This allows you to read Mystic's internal ScreenInfo codes,

    used in Templates - so your MPLs can easily have templates

    just like Mystic!  These are the |!X codes.

Var

  X, Y, Attr : Byte;

Begin

  GetScreenInfo(1, X, Y, Attr);

  WriteLn('The value of the !1 MCI code was:');

  WriteLn('   X: ' + Int2Str(X));

  WriteLn('   Y: ' + Int2Str(Y));

  WriteLn('Attr: ' + Int2Str(Attr));

End;

Function GETUSER (N: Integer) : Boolean

    This procedure will read user data into the USER variables.  The

    supplied N is the record number to read.  The function returns

    true if the record was read, or false if a record was not read.

    The following USER variables will be set when a record is read:

    Variable Name   Type     Description

    -------------------------------------------------------------------

    USERDELETED     Boolean  Is the user marked as deleted?

    USERNAME        String   User's real name.

    USERALIAS       String   User's BBS alias.

    USERPASSWORD    String   User's password.

    USERADDRESS     String   User's street address.

    USERCITY        String   User's City/State.

    USERBIRTHDAY    String   User's birth date.

    USERSEX         Char     User's gender (M = Male, F = FeMale).

    USERSEC         Byte     User's security level (0-255).

    USERFIRSTON     LongInt  User's date/time of first call to the BBS.

                             This is stored in the packed date format

                             so in order to display the date & time,

                             the functions of DATESTR and TIMESTR need

                             to be used.

    USERLASTON      LongInt  User's date/time of the last call to the

                             BBS.  This is also stored in a packed date

                             format, so the same rules for USERFIRST

                             apply to this.

    -------------------------------------------------------------------

    Example:

    Var A Integer

    A := 1

    While GetUser(A) Do

    Begin

         WriteLn ('User Alias: ', UserAlias)

         A := A + 1

    End

    The above example will list all user accounts on the BBS system.

Procedure GETTHISUSER;

    This procedure loads the user information for the currently

    logged in user into the USER variables.  See the GETUSER function

    for a reference of the USER variables.

    Example:

    GetThisUser

    WriteLn ('Welcome to this BBS, ', UserAlias)

    WriteLn ('You have called ', UserCalls, ' times!')

    The above example will load the currently logged in user

    information into the user variables, then display a line of

    text welcoming them to the BBS.

Function GRAPHICS : Byte

    This function returns the user's current graphics mode in

    numerical format:

         0 = ASCII graphics mode

         1 = ANSI graphics mode

    Example:

    If Graphics = 1 Then

         WriteLn ('ANSI graphics')

    Else

         WriteLn ('ASCII graphics')

    The above example will print the user's current graphics mode

    to the screen.  If the user has ANSI (graphics mode 1), "ANSI

    graphics" will be printed.  If the user does not have ANSI

    (graphics mode 0), "ASCII graphics" will be printed to the screen.

Procedure HANGUP

    This procedure will stop the program immediately, hangup up on the

    user, and return Mystic BBS to the waiting for caller screen.

    Example:

    If InputYN ('Do you want to hangup now? ') Then

         HangUp

    The above example will prompt the user with a Yes/No question

    asking "Do you want to hangup now?" and if the user responds

    "Yes", they will be logged off the BBS using the HangUp command.

Function JustFile (S : String) : String

    This function takes a string arguement and returns only the

    filename:

    WriteLn ('This MPX filename is: ' + JustFile(ProgName));

Function JustFileName (S : String) : String

    This function  takes a string arguement and returns only the base

    filename (ie, not the extension so it basically just removes a file

    extension).  This does not remove a path, JustFile does that.

    WriteLn ('This MPX filename is: ' + JustFileName(ProgName));

Function JustPath (S : String) : String

    This function takes a string arguement and returns only the

    path (including the trailing backslash).

    Ex:

    WriteLn ('This MPX is located in ' + JustPath(ProgName));

Function LOCAL : Boolean

    This function returns TRUE if the user is logged into the BBS

    system locally.  It will return FALSE if the user is connected

    via a remote location.

    Example:

    If Local Then

      WriteLn ('Local caller detected.')

    Else

      WriteLn ('Remote caller detected.')

Function MSGEDITOR(0,Int,Int,Int,Bool,Str,Str) : Bool

Procedure MSGEDITSET(Int,Str)

Procedure MSGEDITGET(Int,Str)

     Added 3 new MPL functions: MsgEditor, MsgEditSet, MsgEditGet.  These

     allow access to the internal Mystic msg editor (line and/or full)

     from within MPL.  It even allows you to define wrap position and

     template to completely make it look like its not the Mystic editor!

     As a little hint the MsgEditSet and MsgEditGet stuff could be used to

     post process message text on posts.  Like say for example you wanted

     to write a MPL that allows users to add Tag lines, you could do that

     by replacing the "Saving message..." prompt and using those two in

     order to modify the text before it is saved by Mystic!

     Rather than trying to explain it all, here is an example of all 3:

Var

  Lines    : Integer = 0;

  WrapPos  : Integer = 79;

  MaxLines : Integer = 200;

  Forced   : Boolean = False;

  Template : String  = 'ansiedit';

  Subject  : String  = 'My subject';

  Count    : Integer;

Begin

  MsgEditSet (1, 'this is line 1');

  MsgEditSet (2, 'this is line 2!');

  Lines := 2;

  SetPromptInfo(1, 'MsgTo');  // if template uses &1 for "To:" display

  If MsgEditor(0, Lines, WrapPos, MaxLines, Forced, Template, Subject) Then Begin

    WriteLn('User selected to save.');

    WriteLn('There are ' + Int2Str(Lines) + ' of text in buffer:');

    For Count := 1 to Lines Do

      WriteLn(MsgEditGet(Count));

    Pause;

  End Else Begin

    WriteLn('User aborted the edit.');

    Pause;

  End

End

Procedure MENUCMD (CM: String, Data: String)

    This procedure will allow menu commands to be ran from within a

    program.  <CM> is the menu command, and <DATA> is the menu command

    data.

    Example:

    MenuCmd ('NW', '')

    The above example will run the menu command "NW" with the optional

    data field set to nothing.  This example will display the Who's

    Online list.  See MYSTIC.DOC for a list of all available menu

    commands.

Function NODENUM : Byte

    This function returns the current node number which the program

    is being ran on.

    Example:

    WriteLn ('Welcome to node number ', NodeNum)

    The above example will print the text "welcome to node number x"

    to the screen, where the x will be the current node number which

    the program is being ran on.

Variable PROGNAME : String

    Returns the path and filename of the current MPL program

Variable PROGPARAMS : String

    Returns any of th eparameters passed to the MPL program as a

    single string

Procedure PUTMBASE

    This procedure will save the currently loaded MBASE variables into

    a message base record.  See the GETMBASE function for a list of

    valid MBASE variables.

    Example:

    If GetMBase(1) Then Begin

         MBaseName := 'Message Base #1'

         PutMBase(1)

    End

    The above example will read the data for message base #1, set the

    name to "Message Base #1" and write the data back to the data file.

Procedure PUTTHISUSER

    This procedure will save the USER variables into the currently

    logged in user's record.  See the GETUSER function for a list of

    the USER variables which are saved by the PutThisUser function.

    Example:

    GetThisUser

    WriteLn ('Welcome ', UserAlias, '.  Your account is being deleted.')

    UserDeleted := True

    PutThisUser

    HangUp

    The above example will load the USER variables with the currently

    logged in user's information, then mark them as deleted with the

    UserDeleted variable.  Their account is then saved with the

    PutThisUser procedure and then they are hangup on using the HangUp

    command.

Procedure PUTUSER (N: Integer)

    This procedure will save the USER variables into the user file.

    The passed N parameter is the record number to save under.  See

    the GETUSER function for a list of the USER variables which are

    saved by the PutUser procedure.

    Example:

    If GetUser(1) Then

    Begin

         UserDeleted := True

         PutUser(1)

    End

    The above example will attempt to load the data from user record

    1 into the USER variables.  If the data is loaded without any

    errors, it will mark the user as deleted using the USERDELETED

    variable, and then save the record back to the user file.

Function READENV (S : String) : String

    This function returns the value of the given environment variable

    of the operating system.

Function REAL2STR(Real,Int):String

    This takes a string and decimal place value.

    Ex:

    Var

      R : Real;

    Begin

      R := 1234.1234;

      WriteLn (Real2Str(R, 2));  // Will print 1234.12

   End

Procedure SYSOPLOG (S: String)

    This procedure will add a line into the sysop log file found in

    the logs directory.

    Example:

    SysopLog ('User ran this program.')

    The above example will write the text "User ran this program" in

    the system log file, using the same format as Mystic uses in the

    log files (ie, the date and time will automatically be added).

Function TIMESTR (DT: LongInt, Mode: Byte)

    This function converts a packed datetime number into a time

    string.  The passed mode variable defines the format of the time

    string returned.  Valid options are:

         0 = 24 hour format: HH:MM:SS

         1 = 12 hour format: HH:MMa or HH:MMp

    Example:

    WriteLn ('The current time is: ', TimeStr(DateTime, 1))

    The above example outputs the current time to the screen using the

    TIMESTR and DATETIME functions.

Procedure UPUSER (Sec: Byte)

    This procedure will upgrade the currently logged in user's

    security level using the validation system.  The passed value

    is the security level to upgrade to and must be between the

    range of 0 to 255.

    Example:

    WriteLn ('Upgrading your access to level 20')

    UpUser (20)

    The above example will do a validation upgrade to the security

    level of 20.

-----------------------------------------

Other Supported Functions and procedures:

-----------------------------------------

Commands WITHOUT the ** DONE after them have not yet been documented above.

Hopefully all the commands are listed below, but it's possible that I could

have forgot a couple...  These docs will be up-to-date as time goes on! :)

ABS        ** DONE

ACS        ** DONE

ADDSLASH   ** DONE

ALLOWARROW ** DONE

CHR        ** DONE

CLRSCR     ** DONE

CONST

COPY       ** DONE

DATESTR    ** DONE

DATETIME   ** DONE

DELAY      ** DONE

DELETE     ** DONE

DISPFILE   ** DONE

DOSERROR   ** DONE

FEOF          ** DONE

FCLOSE        ** DONE

FCOPY         ** DONE

FILEERASE     ** DONE

FILEEXIST     ** DONE

FOPEN         ** DONE

FPOS          ** DONE

FSIZE         ** DONE

FINDCLOSE     ** DONE

FINDFIRST     ** DONE

FINDNEXT      ** DONE

FREAD

FREADLN

FREADREC

FSEEK         ** DONE

FUNCTION

FWRITE

FWRITELN

FWRITEREC

GETCFG        ** DONE

GETFBASE

GETMBASE      ** DONE

GETPROMPT     ** DONE

GETUSER       ** DONE

GETTHISUSER   ** DONE

GOTOXY        ** DONE

GRAPHICS      ** DONE

HALT          ** DONE

HANGUP        ** DONE

INPUT         ** DONE

INPUTNY       ** DONE

INPUTYN       ** DONE

INSERT        ** DONE

INT2STR       ** DONE

ISARROW       ** DONE

ISNOFILE      ** DONE

KEYPRESSED    ** DONE

LENGTH        ** DONE

LOCAL         ** DONE

LOWER         ** DONE

MENUCMD       ** DONE

MOVEX         ** DONE

MOVEY         ** DONE

NODENUM       ** DONE

ONEKEY

ONEKEYRANGE   ** DONE

ORD           ** DONE

PADCT         ** DONE

PADLT         ** DONE

PADRT         ** DONE

PARAMCOUNT    ** DONE

PARAMSTR      ** DONE

POS           ** DONE

PUTFBASE

PUTMBASE      ** DONE

PUTTHISUSER   ** DONE

PUTUSER       ** DONE

RANDOM        ** DONE

READKEY       ** DONE

SETPROMPT

SETUSERTIME

STATUSMODE

STATUSUPDATE

STR2INT       ** DONE

STRIPMCI      ** DONE

STRREP        ** DONE

STUFFKEY      ** DONE

SYSOPLOG      ** DONE

TIMER         ** DONE

TIMESTR       ** DONE

UPPER         ** DONE

UPUSER        ** DONE

USES

WHEREX        ** DONE

WHEREY        ** DONE

WORDCOUNT     ** DONE

WORDGET       ** DONE

WORPOS        ** DONE

WRITE         ** DONE

WRITELN       ** DONE