



    ________________________________________________________________________
                                              Chapter 13: Functions   219
    ________________________________________________________________________


    CHAPTER THIRTEEN:  FUNCTIONS


    INTRODUCTION

    This chapter describes all of the functions available in HyperPAD. Each
    HyperPAD function returns a single value to your script.


    CALLING A FUNCTION

    To make a function call within a script, use the following syntax:

    put min(10,12) into msg;

    put the min of 10,12 into msg;

    If the function doesn't have any arguments, then use the following
    syntax:

    put screenWidth() into msg;

    put the screenWidth into msg;

    You cannot mix the two syntax together. For example, the following are
    wrong:

    put the min(10,12) into msg;

    put min of 10,12 into msg;


    FUNCTION SEND MESSAGES

    All functions in HyperPAD are send as messages. For example, the
    function call min(4,5) sends a min message with two parameters: 4 and 5.
    This allows you to redefine any of the built-in function available in
    HyperPAD by replacing the function with your own.

    For example, the following redefines the built-in function min():

    function min;
    begin
      return 6;
    end;

    Redefining built-in functions prevents your scripts lower in the
    hierarchy from accessing the real function. If the above redefinition of
    the min() function occurred in a pad script, then all of the background,
    pages, button, and fields, of that pad which use the min() function
    would not work.



    ________________________________________________________________________
                                              Chapter 13: Functions   220
    ________________________________________________________________________


    In the next example, suppose you wanted HyperPAD to look for files in a
    certain directory on your hard disk that isn't specified in the DOS
    path. In this case, the findFile() function, which normally searches the
    DOS path for files, will not find files in your special directory. You
    could redefine the findFile() function and place it into the pad script
    of your Home pad so that all pads that use findFile() will work
    properly.

    function findFile(fileName);
    begin
      return fileExists("C:\DOCUMENTS\OLD\" & fileName);
    end;


    FUNCTION LISTING BY TOPIC


    COMPUTER FUNCTIONS

    The following is a complete list of computer functions in HyperPAD:

    coprocessor         freeMem             mouseLoc
    cup                 graphicsCard        mouseX
    cursorLoc           mouseButton         mouseY
    cursorX             mouseClick          screenHeight
    cursorY             mouseExists         screenWidth


    CONVERSION FUNCTIONS

    The following are the conversion functions in HyperPAD:

    charToNum           numToChar


    DATE AND TIME FUNCTIONS

    The following are the date and time functions in HyperPAD:

    date                longTime            time
    longDate            seconds



    ________________________________________________________________________
                                              Chapter 13: Functions   221
    ________________________________________________________________________


    DOS FUNCTIONS

    The following are the DOS functions in HyperPAD:

    append              dosVersion          files
    commandLine         drive               fileSize
    create              drives              findFile
    directory           environment         fullName
    dirs                fileExists          longFiles
    diskSpace           fileOpen            open


    FINANCIAL FUNCTIONS

    The following are the HyperPAD financial functions:

    annuity             stdev               compound
    variance


    KEYBOARD FUNCTIONS

    The following are the keyboard functions in HyperPAD:

    altKey              key                 shiftKey
    ctrlKey



    ________________________________________________________________________
                                              Chapter 13: Functions   222
    ________________________________________________________________________


    MATHEMATICAL FUNCTIONS

    The following are the mathematical functions in HyperPAD:

    abs                 exp2                round
    acos                fact                sin
    asin                ln                  sqrt
    atan                ln1                 sum
    average             max                 tan
    cos                 min                 trunc
    exp                 product
    exp1                random


    PAD INFORMATION FUNCTIONS

    The following functions return information about pads: 

    currentBackground   freeSize            target
    currentObject       isSound             version
    currentPad          number of
    currentPage         padSize


    TEXT HANDLING FUNCTIONS

    The following are the text handling functions in HyperPAD:

    clean               offset              substitute
    leftString          proper              upper
    lenght              repeatChar
    lower               rightString



    ________________________________________________________________________
                                              Chapter 13: Functions   223
    ________________________________________________________________________


    MISCELLANEOUS FUNCTIONS

    The following are the miscellaneous functions in HyperPAD:

    choose              paramCount          popup
    param               params              result

    -----------------------------------
    ABS

    Syntax:
    abs(<number>)

    Purpose: The abs() function returns the absolute value of a number;
    which is always a positive number, even if the <number> is negative.

    Examples:

    The following example puts 9 into page field 1.

    put the abs of 9 into page field 1;

    The next example puts 33 into the message box.

    put abs (-33) into the message box;

    -----------------------------------
    ACOS

    Syntax:
    acos(<number>)

    Purpose: The acos() function returns the arc cosine of a number. The arc
    cosine (inverse cosine) is the angle whose cosine is <number>. The angle
    is given in degrees.

    Examples:

    The following example puts 60 into page field 1.

    put the acos of 0.5 into page field 1;

    See Also: asin(), atan()



    ________________________________________________________________________
                                              Chapter 13: Functions   224
    ________________________________________________________________________


    -----------------------------------
    ALTKEY

    Syntax:
    altKey()

    Purpose: The altKey() function returns the status of the ALT key. It
    returns either down or up.

    Examples:

    put the altKey into the message box;

    See Also: shiftKey(), ctrlKey()

    -----------------------------------
    ANNUITY

    Syntax:
    annuity(<rate>,<periods>);

    Purpose: This function computes the present or future value of an
    annuity. <Rate> represents the interest rate per period. <Periods> is
    the number of periods.

    HyperPAD uses the following formula:

    (1-(1+rate)^-periods)/rate

    Examples:

    To compute the monthly payment of a loan of $10,000.00 at 11% for 10
    years:

    put 10000 into total;    --amount borrowed
    put 11/100/12 into interest;  -- interest per month
    put 10*12 into numPayments;   -- 10 years*12 mo/yr
    put total/annuity(interest,numPayments) into payment;

    HyperPAD puts the number 137.75 into the container payment.

    As another example, to determine the present value in 2 years of an
    investment of $1000.00 that earns 18% interest, use the following
    statement:

    put 1000*annuity(18/100,2) into future_value;

    HyperPAD puts 1565.64 into the container future_value.

    See Also: compound()



    ________________________________________________________________________
                                              Chapter 13: Functions   225
    ________________________________________________________________________


    -----------------------------------
    APPEND

    Syntax:
    append(<filename>)

    Purpose: The append() function accesses and opens an existing file
    moving the DOS file write position to the end of the file so that data
    can be added using the write command.

    The value returned by append() is a number that is used to refer to that
    file. You must supply this number in order to use the write and close
    commands.

    If you attempt to append a file that doesn't exist, no file is opened
    and the result() function will return "no such file". If the append
    function is successful, the result() function will return empty. When
    you give the file's name (in the script) you must follow DOS file naming
    conventions. If no pathname is specified, HyperPAD searches the current
    directory.

    The file is closed when the user exits HyperPAD, issues a run command,
    or explicitly closes the file with the close command.

    Examples:

    The following example appends a line to your AUTOEXEC.BAT file:

    put the append of "C:\AUTOEXEC.BAT" into fh;
    if the result is empty then   --append successful?
    begin
      write return & "rem this is appended" to fh;
      close fh;
    end;

    See Also: write, close, open(), read

    -----------------------------------
    ASIN

    Syntax:
    asin(<number>)

    Purpose: This function returns the arc sine of a number. The arc sine
    (inverse sine) is the angle whose sine is <number>.

    Examples:

    put the asin of .789 into page field 1;

    See Also: acos(), atan()



    ________________________________________________________________________
                                              Chapter 13: Functions   226
    ________________________________________________________________________


    -----------------------------------
    ATAN

    Syntax:
    atan(<number>)

    Purpose: This function returns the arc tangent of a number. The arc
    tangent (inverse tangent) is the angle whose tangent is <number>.

    Examples:

    put the atan of 1 into page field 2;

    See Also: acos(), asin()

    -----------------------------------
    AVERAGE

    Syntax:
    average(<number>,<number>[,<number>...])

    Purpose: The average() function averages a group of numbers.
    The numbers can be constants or containers with numeric values. You can
    supply any number of parameters (at least two are required) to this
    function.

    The formula used is:

    (num1+num2+num3+...+numN)/N

    Examples:

    get the average of (field 1, 10, field4);

    put the average of 10,67,10.67,page field 2 into msg;

    See Also: stdev()

    -----------------------------------
    CHARTONUM

    Syntax:
    charToNum(<string>)

    Purpose: This function returns the ASCII value of the specified
    character. If a string is given, charToNum() only returns the value of
    the first character.

    Examples:

    put the charToNum of "a" into "list";



    ________________________________________________________________________
                                              Chapter 13: Functions   227
    ________________________________________________________________________


    put the charToNum of "L" into field 3;

    See Also: numToChar()

    -----------------------------------
    CHOOSE

    Syntax:
    choose(<index>,<argument>[,<argument>...]

    Purpose: The choose() function chooses the Nth parameter
    from the parameter list. The arguments may be any combination of values,
    strings, or containers. If the index is larger than the number of
    arguments, choose() returns empty.

    A good use for this function is in performing an "array" lookup. The
    statement:

    put choose(2,10,12,14);

    puts the value 12 into the message box, because 12 was the second
    parameter (after the 2).

    Examples:

    put choose(3,"A",word 1 of page field 1,"C");

    put choose(i,page field 1,page field 2,page field 2) into
    page field 2;

    -----------------------------------
    CLEAN

    Syntax:
    clean(<string>)

    Purpose: The clean() function strips a text string of unreadable
    characters, returning a text string that does not contain control codes
    or any other non-printable characters.

    Examples:

    put the clean of it into the message box;

    put clean(page field 1) into page field 1;

    You can use clean() to strip unreadable characters from text read into
    HyperPAD from a file:

    read 3 lines from fh;
    put clean(it) into field 1;



    ________________________________________________________________________
                                              Chapter 13: Functions   228
    ________________________________________________________________________


    -----------------------------------
    COMMANDLINE

    Syntax:
    commandLine()

    Purpose: The commandline() function returns the exact command line that
    was used to run HyperPAD from the DOS prompt. The command line can be up
    to 128 characters. No special DOS characters (like |, >, <) are returned
    because they are transparent to applications.

    Because HyperPAD ignores any command line parameters it doesn't
    recognize, authors can implement their own command line switches.

    Examples:

    If the user started HyperPAD with the following command:

    HPAD PHONE /43 /nomsg /geewiz

    The commandline() returns "PHONE /43 /nomsg /geewiz".

    This example tests for a user-defined command line option:

    if "/geewiz" is in the commandLine then
    begin
      visual effect peel;
      go to page "stuff";
    end;

    -----------------------------------
    COMPOUND

    Syntax:
    compound(<rate>,<periods>)

    Purpose: This function computes the future value of an account that
    earns compound interest. <Rate> is the interest rate for the period,
    <periods> is the number of periods.

    The formula for the above syntax is:

    (1+rate)^periods



    ________________________________________________________________________
                                              Chapter 13: Functions   229
    ________________________________________________________________________


    Examples:

    To determine the future value in 2 years of an investment of $1000.00
    that earns 18%, use the following statement:

    put 1000*compound(18/100,2) into future_value;

    This puts 1392.4 into the message box.

    See Also: annuity()

    -----------------------------------
    COPROCESSOR

    Syntax:
    coprocessor()

    Purpose: This function returns true if there is a math processor (80x87)
    installed.

    -----------------------------------
    COS

    Syntax:
    cos(<angle>)

    Purpose: This function returns the cosine of an angle, which must be
    specified in degrees.

    Examples:

    put the cos of 45 into page field 12;

    See Also: sin(), tan()

    -----------------------------------
    CPU

    Syntax:
    cpu()

    Purpose: The cpu() function returns the microprocessor in use, either
    8086, 80186, 80286, or 80386. HyperPAD doesn't differentiate between the
    8088 and 8086 microprocessors, it returns 8086 for 8088 machines.

    Examples:

    put the cpu into cpuType;

    put cpu() into the message box;



    ________________________________________________________________________
                                              Chapter 13: Functions   230
    ________________________________________________________________________


    -----------------------------------
    CREATE

    Syntax:
    create(<filename>)

    Purpose: The create() function creates a new file with the specified
    filename that can be used with the write command. The returned value is
    a number that is used to refer to the file with the write and close
    commands.

    If a file with that name already exists, its length is truncated to
    zero, so the new data replaces any previous data. If create() is
    successful, the result() function returns empty; if there is an error,
    the result() function will return "open error".

    A file created with create() can be written to using the write command.
    HyperPAD creates the file in the current directory if no path is
    specified in <filename>.

    All files are closed when the user exits HyperPAD, issues a run command,
    or explicitly closes the file with the close command.

    Examples:

    put the create of "C:\HPAD\DATA.DAT" into myFile;

    The following example uses create() to create a new file of page scripts
    from the current pad:

    put the create of "SCRIPTS.TXT" into fh;
    if the result is not empty then exit;
    for i = 1 to the number of pages do
      write (the script of page i) & return to fh;
    close fh;

    See Also: append(), open(), write, read

    -----------------------------------
    CTRLKEY

    Syntax:
    ctrlKey()

    Purpose: This function returns the status of the CTRL key. If the CTRL
    key is pressed, it returns down, and if the CTRL key is not pressed it
    returns up.

    Examples:

    put the ctrlKey into msg;



    ________________________________________________________________________
                                              Chapter 13: Functions   231
    ________________________________________________________________________


    -----------------------------------
    CURRENTBACKGROUND

    Syntax:
    currentBackground()

    Purpose: The currentBackground() function returns the number of the
    background used by the current page.

    Examples:

    put the currentBackground into the message box;

    See Also: currentPage(), currentObject(), currentPad()

    -----------------------------------
    CURRENTOBJECT

    Syntax:
    currentObject()

    Purpose: This function returns the name of the object that currently has
    the focus in the following format:

    (page | background) (button | field) id <number>

    Some examples of text returned by currentObject() are:

    page button id 4

    page field id 9

    background field id 1

    background button id 89

    Examples:

    if word 4 of the currentObject is 4 then
      go to page 5;

    Abbreviations: curObj()

    See Also: target, me



    ________________________________________________________________________
                                              Chapter 13: Functions   232
    ________________________________________________________________________


    -----------------------------------
    CURRENTPAD

    Syntax:
    currentPad()

    Purpose: The currentPad() function returns the full DOS filename of the
    current pad including the drive letter and directory.

    For example, if the current pad is HOME.PAD, then currentPad() might
    return:

    C:\HPAD2\HOME.PAD

    Examples:

    put the currentPad into the message box;

    This function is especially useful in determining the directory of the
    pad you are currently using. The following example extracts the
    directory from the name of the current pad and loads another pad from
    that same directory:

    get currentPad();             -- it = current pad
    get substitute(it,"\",",");   -- "\" changed to ","
    delete the last item of it;   -- get rid of filename
    get substitute(it,",""\");    -- "," changed to "\"
    go to pad it & "\PHONE.PAD"   -- append new name

    Abbreviations: curPad()

    See Also: currentPage(), currentBackground(), currentObject()

    -----------------------------------
    CURRENTPAGE

    Syntax:
    currentPage()

    Purpose: This function returns the number of the current page. This is
    not the page's ID number; it is the number that corresponds to the
    page's position in the pad.

    Examples:

    put currentPage() into msg;

    go to page (currentPage() + 2);



    ________________________________________________________________________
                                              Chapter 13: Functions   233
    ________________________________________________________________________


    The following example shows you how to alter the Next command on the Go
    menu so that on the last page of the pad, the command will do nothing.

    handler doMenu(d);
    begin
      if d is "Next" then
        if the currentPage = the number of pages then
        put "Last page.";
      pass;
    end;

    Abbreviations: curPage()

    See Also: currentObject(), currentBackground(), currentPad()

    -----------------------------------
    CURSORLOC

    Syntax:
    cursorLoc()

    Purpose: This function returns the current X,Y coordinates of the
    cursor. The returned text string describes the character cell where the
    hardware text cursor (the blinking cursor) is located; for example,
    "10,12" specifies character position 10 horizontally and character
    position 12 vertically.

    Examples:

    put the cursorLoc into the message box;

    put the cursorLoc into page field 5;

    See Also: cursorX, cursorY, cursor



    ________________________________________________________________________
                                              Chapter 13: Functions   234
    ________________________________________________________________________


    -----------------------------------
    CURSORX

    Syntax:
    cursorX()

    Purpose: This function returns the X coordinate of the cursor. The
    X coordinate of the hardware text cursor (the blinking cursor) is its
    current horizontal position or column location. For example, 10
    specifies the tenth horizontal character cell.

    Examples:

    if cursorX() > 40 then put "right side of page";

    put the cursorX into the message box;

    See Also: cursorY(), cursorLoc(), cursor

    -----------------------------------
    CURSORY

    Syntax:
    cursorY()

    Purpose: This function returns the Y coordinate of the cursor. The
    Y coordinate of the hardware text cursor (the blinking cursor) is its
    current vertical position or character location. For example, 12
    represents the twelfth vertical character cell.

    Examples:

    if cursorY() > 12 then
    put "bottom half of page" into page field 4;

    put the cursorY into the message box;

    See Also: cursorLoc(), cursorX(), cursor

    -----------------------------------
    DATE

    Syntax:
    date()

    Purpose: This function returns the short form of the current date. The
    date is a text string showing Month/Day/Year (MM/DD/YY), for example:

    12/25/90



    ________________________________________________________________________
                                              Chapter 13: Functions   235
    ________________________________________________________________________


    Examples:

    if char 1 to 5 of the date is "12/25" then
      answer "It's Christmas!" with "Yippee";

    See Also: longDate()

    -----------------------------------
    DIRECTORY

    Syntax:
    directory([<driveletter>])

    Purpose: The directory() function returns the working directory on any
    drive. The returned value includes a drive letter and the complete
    pathname.

    get the directory; -- get the current directory

    get the directory of "F"; -- get dir on drive F

    The drive letter parameter is optional. If one is not specified,
    directory() will return the current directory. A value of empty means
    that the specified drive was invalid.

    Examples:

    put the directory into page field "Current Directory";

    The following example searches the current directory on all drives for a
    file called JUNK.TXT:

    put the drives into driveList;
    for i = 1 to the number of items of driveList do
      begin
        get the directory of item i of driveList;
        if the last char of it is not "\" then
          put "\" after it;
        if fileExists(it & "JUNK.TXT") then
          answer "Found it in directory" && it with "Ok";
      end;

    Abbreviations: dir()

    See Also: currentDirectory()



    ________________________________________________________________________
                                              Chapter 13: Functions   236
    ________________________________________________________________________


    -----------------------------------
    DIRS

    Syntax:
    dirs([<pathname>])

    Purpose: The dirs() function returns a list of all the sub-directories
    within a specified directory. If you don't specify the optional
    pathname, HyperPAD returns a list of sub-directories from the current
    directory.

    get the dirs;    -- subdirs of current directory

    get dirs("C:\"); -- subdirs of root on C:

    This function will return a list of sub-directories resembling the
    following format:

    [..          ]
    [123         ]
    [WORD        ]
    [SAMPLES     ]
    The ".." means that there is a parent directory.

    Examples:

    put the dirs into page field "Directory List";

    put dirs("C:\LOTUS") into page field "Dirs";

    if ".." is not in dirs() then
      answer "You are currently in a root directory";

    See Also: drives(), files(), longFiles()

    -----------------------------------
    DISKSPACE

    Syntax:
    diskSpace([<driveletter>])

    Purpose: The diskSpace() function returns the amount of free space on
    the specified drive in bytes. If the optional drive letter is not
    specified, then the free space from the current drive is returned.

    Examples:

    put the diskSpace of "E" into page field 4;

    put the diskSpace into background field 1;



    ________________________________________________________________________
                                              Chapter 13: Functions   237
    ________________________________________________________________________


    -----------------------------------
    DOSVERSION

    Syntax:
    dosVersion()

    Purpose: This function returns the DOS version. Both the major version
    number and the minor version number are returned, like the following:

    3.0
    3.3
    4.0

    Examples:

    put the dosVersion in the message box;

    -----------------------------------
    DRIVE

    Syntax:
    drive()

    Purpose: This function returns the current drive.

    Examples:

    if the drive is "C" then put "this is a hard disk"
      in page field 3;

    See Also: drives()



    ________________________________________________________________________
                                              Chapter 13: Functions   238
    ________________________________________________________________________


    -----------------------------------
    DRIVES

    Syntax:
    drives()

    Purpose: The drives() function returns a list of valid disk drives in an
    item delimited list, like the following:

    A:,B:,C:

    Examples:

    The following example puts the drives into a field, putting each drive
    letter on a different line:

    put substitute(the drives,",",return) into pg fld 1;

    The following statements let the user select a drive letter from a list:

    get popup(drives(),35,10);
    if it is not 0 then
      answer "You chose drive" && item it of drives();

    -----------------------------------
    ENVIRONMENT

    Syntax:
    environment(<environstring>)

    Purpose: This function returns the DOS environment setting for the
    passed DOS environment variable. The environment() function searches the
    list of environment variables for an entry corresponding to the passed
    argument.

    The environment() function is useful for finding the location of the
    command processor (the COMSPEC variable). It may also be useful to
    retrieve user-defined environment variables that may control a pad.

    Examples:

    put the environment of "path" into the msg;



    ________________________________________________________________________
                                              Chapter 13: Functions   239
    ________________________________________________________________________


    The following example uses environment() to locate COMMAND.COM.
    Normally, there is an environment string called COMSPEC that has its
    directory:

    get environment("COMSPEC");  --try the environment
    if it is empty then
      get findFile("COMMAND.COM");  --try the path
    if it is empty then
      get "C:\COMMAND.COM");  --last resort - drive C
    if not fileExists(it) then
      answer "Unable to locate the command processor.";

    -----------------------------------
    EXP

    Syntax:
    exp(<number>)

    Purpose: This function returns the value of e raised to the power of the
    argument. E equals 2.7182818, the base of the natural logarithm.

    Examples:

    The following statement puts 54.59815 into the message box:

    put the exp of 4 into msg;

    See Also: exp1(),exp2()

    -----------------------------------
    EXP1

    Syntax:
    exp1(<number>)

    Purpose: This function returns the value of one less than e raised to
    the power of the argument. E equals 2.7182818, the base of the natural
    logarithm.

    Examples:

    The following statement puts 8102.083928 into the message box:

    put the exp1 of 9 into msg;

    See Also: exp(), exp2()



    ________________________________________________________________________
                                              Chapter 13: Functions   240
    ________________________________________________________________________


    -----------------------------------
    EXP2

    Syntax:
    exp2(<number>)

    Purpose: This function returns the value of 2 raised to the power of the
    argument. To calculate the power of other numbers, use the power (^)
    operator.

    Examples:

    put exp2(6*2) into the message box;   -- 64

    put the exp2 of 4 into x;             -- 16

    See Also: exp(), exp1()

    -----------------------------------
    FACT

    Syntax:
    fact(<number>)

    Purpose: This function returns the factorial of the specified number.
    The factorial of a number is equal to:

    number*(number - 1) * (number *...* (number - n)
    where n = number - 1.

    Examples:

    put the fact of 6 into it;    -- 720

    put the fact of 10 into msg;  -- 3628800

    -----------------------------------
    FILEEXISTS

    Syntax:
    fileExists(<filename>)

    Purpose: The fileExists() function allows you to determine if the file
    you specified exists. This function returns true or false. You can
    specify any valid DOS filename, including a path.

    Examples:

    put the fileExists of "MY.PAD" into IT;



    ________________________________________________________________________
                                              Chapter 13: Functions   241
    ________________________________________________________________________


    if fileExists("C:\123\123.COM") then
      run "C:\123\123.COM" with programDirectory;

    -----------------------------------
    FILEOPEN

    Syntax:
    fileOpen(<title>,<prompt>,<file extension>)

    Purpose: This function allows the user to select a file from the File
    Open dialog box. This is the same dialog box that HyperPAD uses when you
    select Open from the File menu.

    Parameter:       Description:
    -------------------------------------------------------------
    <title>          Title of the dialog box

    <prompt>         Text above the filename field in the dialog box.

    <file extension> Extension of the files that HyperPAD displays in the
                     list box, like "WK1" or "DOC". This parameter can also
                     include a path specification, like "C:\123\*.WK1".

    The fileOpen() function returns empty if the user selected Cancel,
    otherwise it returns a complete DOS path specification (with drive
    letter) for the file that the user selects.

    For example:

    C:\123\SHEETS\HOUSE.WK1

    Examples:

    put fileOpen("Open File","File Name:","C:\*.COM");

    put the fleOpen of
      "My Open File Box",
      "Type in the file name:",
      "..\*.WK1,..\*.DOC,..\*.TXT";



    ________________________________________________________________________
                                              Chapter 13: Functions   242
    ________________________________________________________________________


    -----------------------------------
    FILES

    Syntax:
    files([<filemask>])

    Purpose: The files() function returns a list of all the filenames
    separated by carriage returns that match a search mask.

    If no search mask is specified, files() returns all of the files in the
    current directory (*.*). The files are returned in the following manner:

    HOME.PAD
    PHONE.PAD
    ZAP.PAD

    The files are sorted according to the value of the fileSortMethod
    property, which is 1 by default (sort ascending by filename).

    Examples:

    put the files into page field 4;
    put files ("*.EXT") into page field 4;

    See Also: longFiles(), fileSortMethod

    -----------------------------------
    FILESIZE

    Syntax:
    fileSize(<filename>)

    Purpose: This function returns the size in bytes of the specified file.
    If the file does not exist, fileSize() returns 0.

    Examples:

    put fileSize("README.DOC") into the message box;

    if the fileSize of "DATA.DAT" < 30000 then
      doMenu "Import...";



    ________________________________________________________________________
                                              Chapter 13: Functions   243
    ________________________________________________________________________


    -----------------------------------
    FINDFILE

    Syntax:
    findFile(<fileName>)

    Purpose: This function searches for a file using HyperPAD's built-in
    search technique. HyperPAD looks in the following places in the
    following order:

    1.  Search the current directory.

    2.  Search the directory pointed to by the HPADNET environment variable
    (if there is one).

    3.  Search the directory where HPAD.EXE exists.

    4.  Search the directory where HyperPAD was started.

    5.  Search all directories specified in the DOS path.

    6.  Search the B: drive if the Program disk is in A and A is a low
    density disk (360K).

    If the file is located, you are returned the full DOS path name. If the
    file cannot be located, findFile() returns empty.

    Examples:

    if findFile("DATA.DAT") is not empty then
      answer "Can't find the data file";

    get the findFile of "readme.doc";

    See Also: fileExists(), fullName()

    -----------------------------------
    FREEMEM

    Syntax:
    freeMem()

    Purpose: The freeMem() function returns the number of bytes of free
    memory. The number is not the total memory in the computer; nor is it
    the total amount of memory for your pad. It returns the free memory at
    the time you call the function.

    Examples:

    put the freeMem into the message box;

    See Also: padSize(), freeSize()



    ________________________________________________________________________
                                              Chapter 13: Functions   244
    ________________________________________________________________________


    -----------------------------------
    FREESIZE

    Syntax:
    freeSize()

    Purpose: The freeSize() function returns the number of bytes of free
    space in the current pad. This number is constantly changing as you use
    your pad.

    Note: The free space in read-only pads (pads whose
    cantModify property is set to true) will never change.

    Examples:

    if the freeSize >` 4000 then doMenu "Compress";

    See Also: freeMem(), padSize()

    -----------------------------------
    FULLNAME

    Syntax:
    fullName(<pathname>)

    Purpose: The fullName() function takes a partial file specification and
    returns a full DOS path name for the file. The following table shows
    samples of what this function returns, depending on the parameter
    supplied to the fullName() function:

    Current Directory:   Parameter:         Returns:
    -------------------------------------------------------------
    C:\HPAD2             ..                 C:\

    C:\HPAD\PADS         ..\ACCOUNTS\..\..  C:\

    C:\HPAD2             C:..               C:\HPAD2

    C:\HPAD2\PADS        C:\                C:\

    C:\HPAD2             C:                 C:\HPAD2

    C:\HPAD2             ..\..\DOS          C:\DOS



    ________________________________________________________________________
                                              Chapter 13: Functions   245
    ________________________________________________________________________


    Examples:

    put the fullName of "D:..\DOS" into msg;

    ask "What directory";
    put fullName(it) into msg;

    This function can be used to validate DOS filenames:

    ask "Pad to load";  -- get a pad name
    get fullName(it);   -- make sure it's a full name
    if fileExists(it) then
      go to pad it;          -- go to the pad

    -----------------------------------
    GRAPHICSCARD

    Syntax:
    graphicsCard()

    Purpose: The graphicsCard() function returns the video card in use. The
    following are possible returned values:

    Monochrome
    CGA
    Extended CGA
    Extended CGA-PLASMA
    Hercules Monochrome
    EGA
    Extended EGA
    MCGA
    VGA
    Extended VGA
    Leading EDGE Internal Graphics Adapter
    Unknown

    Examples:

    put graphicsCard into the msg;

    if the graphicsCard is not "monochrome" then
      LoadGX2 "PICTURE.GX2";

    if the graphicsCard() is "vga" then
      go to pad "phone50";



    ________________________________________________________________________
                                              Chapter 13: Functions   246
    ________________________________________________________________________


    -----------------------------------
    ISSOUND

    Syntax:
    isSound()

    Purpose: This function returns true if music is playing or a sound
    command is active. Otherwise, the function returns false.

    Examples:

    put isSound() into the msg;

    if not isSound() then play "ABC";

    To wait until some music is finished playing:

    play "ABCDEFG";
    repeat until not isSound();

    See Also: play, sound, noSound

    -----------------------------------
    KEY

    Syntax:
    key(<keyNumber>)

    Purpose: This function translates a key (the type passed with the
    keyPress message) to text.

    Keys are normally encoded into numbers in the following manner:

    scan code * 256 + ascii code

    For example, the scan code of the ENTER key is 28, the ASCII code is 13,
    so the key code is 256*28 + 13 = 7181. The key() function translates the
    number 7181 to the string "ENTER".

    In addition to normal letters, digits, and punctuation, key() returns
    strings like "ENTER", "F1", "ALT+T" for special keys and key
    combinations. The possible values returned by key() are listed in
    Appendix  2, "Key Values".



    ________________________________________________________________________
                                              Chapter 13: Functions   247
    ________________________________________________________________________


    Examples:

    put the key of k into It;

    handler keyPress(k);
    begin
      if the key of k is "escape" then quit
      else pass;
    end;

    See Also: keyPress

    -----------------------------------
    LEFTSTRING

    Syntax:
    leftString(<string>,<numchars>)

    Purpose: The leftString() function returns the specified number of
    characters in a string beginning from the left.

    For example, leftString("Hello World",7) returns "Hello W".

    Note:  This function requires exactly two arguments.

    Examples:

    put the leftString of "This is a string", 6 into msg;

    See Also: rightString()



    ________________________________________________________________________
                                              Chapter 13: Functions   248
    ________________________________________________________________________


    -----------------------------------
    LENGTH

    Syntax:
    length(<expression>)

    Purpose: The length() function returns the number of characters in a
    string. The string can be a literal string or a container.

    The following two statements are equivalent:

    the number of characters of page field 1;

    length(page field 1);
    Examples:

    if the length(page field 1) > 10 the beep;

    put length(userName) into userNameLength;

    Abbreviations: len()

    See Also: number of

    -----------------------------------
    LN

    Syntax:
    ln(<number>)

    Purpose: This function returns the natural logarithm of the number. The
    natural logarithms are based on the constant e, 2.7182818. The argument
    must be positive.

    Examples:

    put the ln of 6 into it;       -- 1.791759

    put the ln of 89076 into msg;  -- 11.397245

    See Also: ln1()



    ________________________________________________________________________
                                              Chapter 13: Functions   249
    ________________________________________________________________________


    -----------------------------------
    LN1

    Syntax:
    ln1(<number>)

    Purpose: This function returns the natural logarithm of the sum of one
    plus the number. The natural logarithms are based on the constant e,
    2.7182818. The argument must be positive.

    Examples:

    put ln1(7) into msg;

    See Also: ln()

    -----------------------------------
    LONGDATE

    Syntax:
    longDate()

    Purpose: This function returns the long form of the current date. The
    long date is a text string showing day of the week, month, day, and
    year; for example:

    "Monday, December 25, 1989"

    Examples:

    put longDate() into the msg;

    put "Today's date is" && the longDate into page field 8;

    get the longDate;
    convert it to abbreviated date;
    put in into msg;

    See Also: date(), time(), longTime()



    ________________________________________________________________________
                                              Chapter 13: Functions   250
    ________________________________________________________________________


    -----------------------------------
    LONGFILES

    Syntax:
    longFiles([<filespec>])

    Purpose: The longFiles() function lists the filenames, extensions, size,
    and modification date and time for all files matching the specified
    filespec. If <filespec> isn't given, HyperPAD assumes "*.*" in the
    current directory and lists all those files. Below is a sample list:

    FILENAME.EXT   12345678  12-21-89  12:40p
    FILENAME.EXT   34577310  01-30-90  11:20a

    Examples:

    put longFiles("*.EXE") into page field 4;

    -----------------------------------
    LONGTIME

    Syntax:
    longTime()

    Purpose: The longTime() function returns the current time in the long
    format. The long time is a text string showing hours/minutes/seconds AM
    or PM (HH:MM:SSxx). For example:

    12:30:56 PM

    Examples:

    put the longTime into background field time;

    The following handler in a pad script updates the time displayed in the
    message box constantly:

    handler idle;
    begin
      put the longTime;
    end;

    See Also: time(), seconds()



    ________________________________________________________________________
                                              Chapter 13: Functions   251
    ________________________________________________________________________


    -----------------------------------
    LOWER

    Syntax:
    lower(<string>)

    Purpose: The lower() function returns the specified string in lowercase
    letters. Characters that are not letters are left unchanged. For
    example, lower("HyperPAD 123") returns "hyperpad 123".

    Examples:

    put lower(page field 1) into page field 1;

    ask "What is your name";
    put lower(it) into page field "Name";

    See Also: upper()

    -----------------------------------
    MAX

    Syntax:
    max(<num>,<num>[,<num>...])

    Purpose: The max() function returns the largest number in a series of
    numbers. The numbers can be constants or containers. Any number of
    arguments can be specified as long as there are at least two.

    Examples:

    The following example puts 77 into the message box.

    put the max of 23,43,77 into the message box;

    See Also: min()



    ________________________________________________________________________
                                              Chapter 13: Functions   252
    ________________________________________________________________________


    -----------------------------------
    MIN

    Syntax:
    min(<num>,<num>[,<num>...])

    Purpose: The min() function returns the smallest number in a series of
    numbers. The numbers can be constants or containers. Any number of
    arguments can be specified as long as there are at least two.

    Examples:

    The following example puts 34 into page field 3.

    put min(34,67,89) into page field 3;

    See Also: max()

    -----------------------------------
    MOUSEBUTTON

    Syntax:
    mouseButton()

    Purpose: The mouseButton() function returns the current status of the
    mouse buttons. The response from this function is a text string
    describing the status:

    0     No buttons are pressed.
    1     The left button is pressed.
    2     The right button is pressed.
    3     Both left and right buttons are pressed.
    4     The middle button is pressed (three-button mouse).

    Examples:

    if mouseButton() = 1 then
      put "Button pressed" into the message box;

    The next example waits for all mouse buttons to be released.

    repeat until mouseButton() is zero;

    See Also: mouseClick(), mouseExists(), mouseLoc()



    ________________________________________________________________________
                                              Chapter 13: Functions   253
    ________________________________________________________________________


    -----------------------------------
    MOUSECLICK

    Syntax:
    mouseClick()

    Purpose: The mouseClick() function returns true if the mouse button has
    been pressed since the last idle message was sent; otherwise it returns
    false.

    Examples:

    if mouseClick() then beep;

    for i = 1 to 10 do go to next page;
    if the mouseClick then
      answer "You pressed the mouse during the show.";

    See Also: mouseButton(), mouseExists(), mouseLoc()

    -----------------------------------
    MOUSEEXISTS

    Syntax:
    mouseExists()

    Purpose: This function returns true if the mouse is installed and the
    mouse software is loaded and working, and false if the mouse is not
    installed.

    Examples:

    put mouseExists() into the message box;

    get the mouseExists;

    This example installs a keyPress handler that allows keys to pass
    through only if there isn't a mouse present:

    handler keyPress(k);
    begin
      if not the mouseExists then pass;
    end;

    See Also: mouseClick(), mouseButton(), mouseLoc()



    ________________________________________________________________________
                                              Chapter 13: Functions   254
    ________________________________________________________________________


    -----------------------------------
    MOUSELOC

    Syntax:
    mouseLoc()

    Purpose: The mouseLoc() function returns the current X,Y coordinates of
    the mouse. For example:

    10,12

    Examples:

    put mouseLoc() into background field "Mouse Location";

    if the mouseLoc is "1,1" then beep;

    See Also: mouseX(), mouseY()

    -----------------------------------
    MOUSEX

    Syntax:
    mouseX()

    Purpose: The mouseX() function returns the current X coordinate of the
    mouse. The X coordinate of the mouse is its current horizontal position
    or column location.

    Examples:

    put the mouseX into the message box;

    See Also: mouseLoc(), mouseY()

    -----------------------------------
    MOUSEY

    Syntax:
    mouseY()

    Purpose: The mouseY() function returns the current Y coordinate of the
    mouse. The Y coordinate of the mouse is its current vertical position or
    row location.

    Examples:

    put the mouseY into the message box;

    See Also: mouseLoc, mouseX



    ________________________________________________________________________
                                              Chapter 13: Functions   255
    ________________________________________________________________________


    -----------------------------------
    NUMBER OF

    Syntax:
    number(chars | words | items | lines) of <container>
    number(backgrounds | pages)
    number([page | background] buttons)
    number([page | background] fields)

    Purpose: The number() function returns whether the number of objects, or
    returns the number of characters, words, items, or lines within a
    container.

    Examples:

    The different forms of number() are shown here:

    put the number of pages into msg;

    put the number of backgrounds into msg;

    put the number of pages of background 2 into msg;

    put the number of page buttons into msg;

    put the number of fields into msg;

    put the number of flds of pg 1 of bkgnd 4 into msg;

    put the number of characters of msg into msg;

    put the number of words of item 6 of page field 1;

    put the number of lines of page field "File List";

    To show all of the pages:

    for i = 1 to the number of pages do
      go to the next page;



    ________________________________________________________________________
                                              Chapter 13: Functions   256
    ________________________________________________________________________


    To print all the button scripts in a pad:

    set the printer to on;
    for i = 1 to the number of backgrounds do
      begin
        go to page 1 of background i;
        for j = 1 to the number of background buttons do
          print the script of background button j;
      end;
    for i = 1 to the number of pages do
      begin
        go to page i;
        for j = 1 to the number of page buttons do
          print the script of page button j;
      end;
    set the printer to off;

    Abbreviations: chars, flds, pgs, cds

    See Also: length()

    -----------------------------------
    NUMTOCHAR

    Syntax:
    numToChar(<number>)

    Purpose: The numToChar() function returns the ASCII character associated
    with the specified number (an integer from 0 to 255).

    Examples:

    The following example puts the letter "A" into the message box:

    put the numToChar of "65" into page field 3;
    To get a random capital letter:

    put numToChar(random(26) + 64) into msg;



    ________________________________________________________________________
                                              Chapter 13: Functions   257
    ________________________________________________________________________


    -----------------------------------
    OFFSET

    Syntax:
    offSet(<findstring>,<targetstring>)

    Purpose: The offset() function returns the character number where the
    first string appears in the second. If the first string doesn't occur
    within the second, offset() returns 0.

    Examples:

    The following example puts 5 into the message box:

    put offSet("blue", "the blue ocean");

    The next example puts 2 into the message box:

    put offSet("e", "hello there mate") into msg;

    The next example replaces all occurrences of one string with another:

    function
    replaceIt(targetString,searchString,repString);
    begin
      if repString is in searchString then exit;
      put length(searchString) into l;
      while searchString is in targetString do
       begin
        get offSet(SearchString);
        put repString into char it to it+l of targetString;
        end;
      return targetString;
    end;

    To use this function:

    put replaceIt(page field 1,"lawyer","attorney") into page field 1;



    ________________________________________________________________________
                                              Chapter 13: Functions   258
    ________________________________________________________________________


    -----------------------------------
    OPEN

    Syntax:
    open(<filename>)

    Purpose: The open() function opens a file for reading and places the
    file pointer at the beginning of that file. The function returns a file
    number that you will need to refer to that file. A file opened with the
    open() function, can only be read, it cannot be modified.

    If HyperPAD can't locate the specified file, the result() function will
    return "no such file". If open() is successful, the result() function
    will return empty.

    Once you have opened a file, you can read from it using the read
    command. When you are done with the file, be sure to close it using the
    close command.

    Examples:

    put open("DATA.DAT") into the msg;

    To open a file and read its entire contents into a field:

    put open("DOCUMENT.TXT") into fh;
    if the result is empty then
      begin
        read from fh until end;
        put it into field "Document";
        close fh;
      end
    else
      answer "Error opening file";

    See Also: close(), read



    ________________________________________________________________________
                                              Chapter 13: Functions   259
    ________________________________________________________________________


    -----------------------------------
    PADSIZE

    Syntax:
    padSize()

    Purpose: This function returns the size of the pad in bytes.

    Examples:

    put the padSize into the message box;

    The following function uses padSize() to determine if there is room to
    expand the pad by a certain number of bytes.

    function roomForExpansion(numBytes);
    begin
      return the padSize > the diskSpace + numBytes;
    end;

    -----------------------------------
    PARAM

    Syntax:
    param(<paramnumber>)

    Purpose: The param() function returns the value of the nth parameter of
    the parameter list passed to the currently executing handler or
    function.

    If there are not any parameters or <paramnumber> is too large, then
    empty is returned.

    Examples:

    Use param to put all of the passed parameters into a separate line of a
    field:

    handler makeList;
    begin
      for i = 1 to the paramCount do
      put param(i) into line i of page field 1;
    end;



    ________________________________________________________________________
                                              Chapter 13: Functions   260
    ________________________________________________________________________


    The next example uses param() to define a max() function:

    function max;
    begin
      put param(1) into m;
      for i = 2 to the paramCount do
        if param(i) > m then put param(i) into m;
      return m;
    end;

    See Also: paramCount(), params()

    -----------------------------------
    PARAMCOUNT

    Syntax:
    paramCount()

    Purpose: The paramCount() function returns the total number of
    parameters passed to the currently executing handler, regardless of the
    number of place holders declared by the handler or function. This
    function is the only way to determine the actual number of arguments
    passed to a handler or function.

    Examples:

    get the paramCount;

    The next example uses paramCount() to determine the number of
    parameters, then checks to see if any of the parameters can be found in
    background field 1:

    function findMany;
    begin
      for i = 1 to the paramCount do
        begin
          find param(i) in field 1; --find parameter
          if the result is "found" then
            begin
              return true; --found one!
              exit;
            end;
        end;
      return false; --can't find any
    end;

    See Also: param(), params()



    ________________________________________________________________________
                                              Chapter 13: Functions   261
    ________________________________________________________________________


    -----------------------------------
    PARAMS

    Syntax:
    params()

    Purpose: The params() function returns a list of the parameters passed
    to the currently executing handler or function. The values of the
    arguments (not the expressions themselves) are returned in a list,
    separated by commas. The expressions are evaluated before the parameter
    list is returned. For example, if the following call is made to a
    handler called stuff:

    stuff(10,"hello",45,56);

    then the params() function will return the text

    10,hello45,56

    Examples:

    put params() into the message box;

    handler putThem;
    begin
      put the params;
    end;

    See Also: param(), paramCount()



    ________________________________________________________________________
                                              Chapter 13: Functions   262
    ________________________________________________________________________


    -----------------------------------
    POPUP

    Syntax:
    popup(<upper left x>,<upper left y>,<choices>)

    Purpose: The popup() function displays and controls a popup menu. A
    popup menu is a window with a list of choices from which you can choose,
    similar to HyperPAD pull down menus (like the File menu). Here is a
    sample of a popup:

 Ŀ
                                                                        
  **** The Printed Documentation has a picture or screen shot here **** 
                                                                        
 
    

    You specify the location of the popup menu by its upper left X,Y
    coordinates. The choices that appear within the popup menu are specified
    in the <choices> parameter. The <choices> text has the following format:

    "choice1,choice2,choice3"

    Each choice is separated be either a semi-colon, comma, or a carriage
    return. The following characters have special meaning within a choice:


    - (hyphen)

    A hyphen defines a horizontal separator bar. You can also create
    separator bars by specifying an empty choice.



    ________________________________________________________________________
                                              Chapter 13: Functions   263
    ________________________________________________________________________


    @@

    When the @ character is the first character of a choice, the choice is
    dimmed.


    !

    The ! character as the first character of a choice, checks the choice.


    &

    The & character means that the next character in the choice is an
    accelerator key.

    The following are sample choice strings:

    "Eggs,Bacon,Cheese,Butter"
    "&Eggs,&Bacon,C&heese,!Butter"
    "&Monday,!@Tuesday,-,&Wednesday"

    If you have many choices in your popup, you can put the choices into a
    field and use the statement:

    put the popup of 10,10,field 1 into userChoice;

    Using a popup is similar to using a HyperPAD pull down menu. The
    following keys control a popup:

    Key:              Action:
    -------------------------------------------------------
    UP                Highlight the previous choice.
    DOWN              Highlight the next choice.
    ENTER or SPACE    Select the highlighted choice
    HOME              Highlight the first choice.
    END               Highlight the last choice.
    LETTER            Select the choice with that accelerator key.

    The popup() function returns the number of the selected choice. If you
    press ESC, popup() will return 0.

    HyperPAD adjusts the popup's position if the coordinates you specify
    cause the popup menu to be drawn off the edge of the screen. Thus, if
    you wanted to create a popup in the lower right hand corner, you could
    use the following statement:

    get popup(100,100,"Choice1,Choice2,Choice3);

    In this case, HyperPAD would adjust the upper left corner to 70,21.



    ________________________________________________________________________
                                              Chapter 13: Functions   264
    ________________________________________________________________________


    The popup() function will return an error if the number of choices
    exceeds the height of the display, if the length of any of the choices
    is greater the 80, or if all of the choices are disabled.

    Example:

    get popup(10,10,"Eggs,Ham,Cheese,Bread");

    To display a popup with three choices:

    put popup 4,3,"New...,Open...,Save a Copy..." into r;

    To display a popup with the same three choices, except this time, the
    first choice has an accelerator key (w) and the second choice has a
    check mark:

    put popup 10,10,"Ne&w...;!Open...;Save a Copy..." into r;

    The following handlers implement an Edit menu similar to HyperPAD's Edit
    menu. The two handlers should be in a button script.

    handler mouseDown;
    begin
      -- assemble some choices
      put "@&Undo,-,Cu&t,&Copy,&Paste,&Delete" cList;
      -- let the user pick one
      put popup(7,2,cList) into choice;
      if it is 0 then exit;
      -- convert choice to usable string
      get item it of cList;
      get substitute(it,"&",empty);
      get substitute(it,"@",empty);
      -- execute it
      domenu it;
    end;

    handler select;
    begin
      -- simulate the user pressing the mouse on this choice
      mouseDown;
    end;



    ________________________________________________________________________
                                              Chapter 13: Functions   265
    ________________________________________________________________________


    The following example allows the user to pick a drive from a list:

    get popup(3,3,drives());
    if it is 0 then exit;
    answer "You picked" item it of drives();

    See Also: setPopupColor, setDefaultPopupColors

    -----------------------------------
    PRODUCT

    Syntax:
    product(<num>,<num>[,<num>...])

    Purpose: The product() function multiplies each of the numbers given as
    arguments. This function accepts two or more arguments.

    Examples:

    put the product of 3,56,98,54 into total;

    put the product of 4,6,32,78,99 into page field 3;

    See Also: sum()

    -----------------------------------
    PROPER

    Syntax:
    proper(<string>)

    Purpose: The proper() function returns the proper form of the passed
    parameter by changing the first character of each word to uppercase and
    all other characters to lowercase. The function also capitalizes any
    character that follows a non-alphabetic character.

    For example:            Returns:
    ------------------------------------------------------
    proper("hello there")   Hello There

    proper("hELLO THeRE")   Hello There

    Examples:

    put proper("this is a string") into the message box;

    ask "What is your name";
    put proper(it) into field "Name";

    See Also: upper(), lower()



    ________________________________________________________________________
                                              Chapter 13: Functions   266
    ________________________________________________________________________


    -----------------------------------
    RANDOM

    Syntax:
    random(<upperbound>)

    Purpose: The random() function returns a random integer greater than or
    equal to 1 and less than or equal to the number specified. The function
    may return the same number more than once before all the numbers within
    the specified range have been returned.

    Examples:

    put random(3) into the message box;

    put item random(3) of "Jim,John,Lisa" into pg fld 1;

    The next example shows each page in a pad in a random order. The problem
    here is that random can return the same value twice before all the
    values have been returned at least once. To remedy this, the handler
    creates an item delimited list of page numbers. For example, if there
    are 10 pages, list looks like:

    1,2,3,4,5,6,7,8,9,10

    The algorithm retrieves a random number between 1 and the number of
    items in this list and retrieves this item number from the list. Then,
    this page is shown and that item is deleted from the list. This process
    continues until the list is empty.

    handler showAll;
    begin
      --create an item list of page numbers:
      put empty into list;
      for i = 1 to the number of pages do
        put i into item i of list;
      --show each item, delete the item after showing it
      while list is not empty do
        begin
          put random(number of items of list) into r;
          go to page (item r of list);
          delete item r of list;
        end;
    end;



    ________________________________________________________________________
                                              Chapter 13: Functions   267
    ________________________________________________________________________


    -----------------------------------
    REPEATCHAR

    Syntax:
    repeatChar(<number of times>,<character to repeat>)

    Purpose: This function returns a string made up of a single character of
    a specified length. For example,

    repeatChar(10,"A")
    returns

    AAAAAAAAAA

    Examples:

    put repeatChar(10,char 1 of page field 1) into msg;

    print repeatChar(30-length(s),space);

    Abbreviations: repChar()

    -----------------------------------
    RESULT

    Syntax:
    result()

    Purpose: This function returns the result of many operations in
    HyperPAD, including run, open(), create(), append(), find, go, and
    query.

    The following modify the return value of result():

    1.  The run command. After running a program with the run command, the
    result() returns the value of the return code of the program. (This is
    the same return code that you test for using the DOS errorlevel
    command).

    2.  The read command. After reading data from a file using the read
    command, the result() returns "eof" if the end of file has been reached;
    otherwise the result() returns empty.

    3.  The write command. The result() returns empty.

    4.  The go command. If you attempt to go to an invalid page, the
    result() returns "no such page".

    5.  The open function. If there is an error opening a file, result()
    returns "no such file".



    ________________________________________________________________________
                                              Chapter 13: Functions   268
    ________________________________________________________________________


    6.  The append function. If there is an error opening a file, result()
    returns "no such file".

    7.  The create function. If there is an error creating the file,
    result() returns "open error".

    8.  The find command. The result() returns either "found" or "not found"
    depending on the outcome of the search.

    9.  The query command. The result() returns either "found" or "not
    found" depending on the result of the query.

    Examples:

    put the result into status;

    The following resume handler checks the result() function to see if the
    program exited with an error.

    handler resume;
    begin
      if the result is not zero then
        answer "The program exited with an error code";
    end;

    -----------------------------------
    RIGHTSTRING

    Syntax:
    rightString(<string>,<numchars>)

    Purpose: This function returns the specified number of characters from
    the string beginning from the right. For example,
    rightString("Hello World",3);
    returns "rld".

    Examples:

    put rightString("This is a string",6) into the msg;

    See Also: leftString



    ________________________________________________________________________
                                              Chapter 13: Functions   269
    ________________________________________________________________________


    -----------------------------------
    ROUND

    Syntax:
    round(<number>)

    Purpose: This function rounds the specified number to the nearest
    integer. The operation is performed by adding .5 to the number and
    truncating the decimal part. If the number is negative, the negative
    sign is removed, rounding is performed and then the negative sign is put
    back.

    Examples:

    The following puts 6 into it:

    put the round of 5.77 into it;

    The following example puts 187654 into page field 2:

    put the round of 187654.222 into page field 2;

    See Also: trunc()

    -----------------------------------
    SCREENHEIGHT

    Syntax:
    screenHeight()

    Purpose: This function returns the height of the screen in character
    cells or rows. Normally, the screen is 25 rows high.

    You can change the screen height of new pads using the command line
    options "/43" and "/50".

    Examples:

    put the screenHeight into msg;

    The following positions a button beyond the 25th line, but checks first:

    if the screenHeight > 25 then
    begin
      --user has an extended text mode
      set the position of button "home" to 70,40;
    end;

    See Also: screenWidth()



    ________________________________________________________________________
                                              Chapter 13: Functions   270
    ________________________________________________________________________


    -----------------------------------
    SCREENWIDTH

    Syntax:
    screenWidth()

    Purpose: This function returns the width of the screen, which is
    normally 80 columns wide.

    Examples:

    put the screenHeight into msg;

    See Also: screenHeight()

    -----------------------------------
    SECONDS

    Syntax:
    seconds()

    Purpose: This function returns the number of seconds between January 1,
    1583 and the current date. The function works by retrieving your
    computer's date and time and converting it to seconds (be sure your
    computer's date and time are correct).

    Examples:

    put the seconds into msg;

    The following example uses seconds() to time an operation.

    put the seconds into savedSeconds;
    for i = 1 to the number of pages do
      go to page i;
    answer "That operation took" && seconds() - savedSeconds() && "seconds";

    Using seconds(), you can set up an alarm, as demonstrated
    with the following handlers. First, this button script sets up the alarm
    time.

    handler select;
    begin
      global stopSeconds;
      ask "Alarm at what time?" with the time;
      if it is empty then exit;
      convert it to seconds;
      put it into stopSeconds;
    end;



    ________________________________________________________________________
                                              Chapter 13: Functions   271
    ________________________________________________________________________


    The following script should be placed in the pad script of your Home
    pad. It watches for the alarm.

    handler idle;
    begin
      global stopSeconds;
      -- check to see if an alarm is set...
      if stopseconds > 0 then
        begin
          -- has time elapsed?
          if the seconds >= stopSeconds then
            begin
              answer "The alarm has gone off!" with "Ok";
              put 0 into stopSeconds;
            end;
        end;
      pass; -- pass on to the next object
    end;

    Abbreviations: secs()

    See Also: time(), longTime()

    -----------------------------------
    SHIFTKEY

    Syntax:
    shiftKey()

    Purpose: This function determines the status of the SHIFT key. It
    returns either up or down.

    Examples:

    put shiftKey() into shiftStatus;

    put the shiftKey into the message box;



    ________________________________________________________________________
                                              Chapter 13: Functions   272
    ________________________________________________________________________


    -----------------------------------
    SIN

    Syntax:
    sin(<angle>)

    Purpose: This function returns the sine of an angle.

    Examples:

    put sin(30) into the message box;  -- 0.5

    put the sin of 45 into page field 1;  -- 0.707107

    See Also: cos(), tan()

    -----------------------------------
    SQRT

    Syntax:
    sqrt(<number>)

    Purpose: This function returns the square root of <number>. A error
    occurs if <number> is negative.

    Examples:

    put the sqrt of 5 into it;

    put the sqrt of 90 into it;

    -----------------------------------
    STDEV

    Syntax:
    stdev(<num>,<num>[,<num>...])

    Purpose: This function calculates the standard deviation of two or more
    numbers. The formula used to compute the standard deviation is:

    sqrt(((num1-average)^2 + (num2-average)^2 +...+ (numN-
    average)^2)/N)

    Examples:

    put the stdev of 6600, 7954, 4399, 7895 into msg;

    put stdev(5000,15000,30000,40000,50000); -- puts 18234.583



    ________________________________________________________________________
                                              Chapter 13: Functions   273
    ________________________________________________________________________


    -----------------------------------
    SUBSTITUTE

    Syntax:
    substitute(<targetstring>,<pattern>,<replacement>

    Purpose: The substitute() function replaces all of the occurrences of
    one string with another and returns the new string. For example, if you
    wanted to replace all occurrences of "o" with "X":

    substitute("Hello World","o","X")

    would return "hellX WXrld".

    Examples:

    put substitute("Biff and Chet and Sid","and","and not");

    -----------------------------------
    SUM

    Syntax:
    sum(<num>,<num>[,<num>...])

    Purpose: This function returns the sum off all the passed parameters

    Examples:

    put sum(1,45,6,92) into message box;

    put the sum of apples,oranges into fruit;

    See Also: product(), max(), min()

    -----------------------------------
    TAN

    Syntax:
    tan(<number>)

    Purpose: This function returns the tangent of an angle.

    Examples:

    put tan(30) into the message box;  -- 30

    put the tan of 45 into page field 5;  -- 1

    See Also: cos(), sin()



    ________________________________________________________________________
                                              Chapter 13: Functions   274
    ________________________________________________________________________


    -----------------------------------
    TARGET

    Syntax:
    target()

    Purpose: The target() function returns a string identifying the initial
    receiver of a message. The target can also be used as an object within
    the script. The target is returned in the following manner:

    page button id 2
    bkgnd button id 2
    page field id 1
    bkgnd field id 1
    page id 2
    bkgnd id 3
    pad "C:\HPAD2\HOME.PAD"

    Examples:

    put the target into the message box;

    if word 2 of the target is "button then
      send "select" to the target;

    See Also: currentObject()

    -----------------------------------
    TIME

    Syntax:
    time()

    Purpose: This function returns time in the format:

    HH:MM PP
    where HH = hour, MM = minute, and PP = AM or PM

    Examples:

    get the time;          --put the time into IT
    convert it to seconds; --convert current time to seconds
    add 30 to it;          --add 30 seconds
    convert it to time;    --convert it back
    put it;                --display it in the message box

    See Also: longTime(), seconds()



    ________________________________________________________________________
                                              Chapter 13: Functions   275
    ________________________________________________________________________


    -----------------------------------
    TRIM

    Syntax:
    trim(<string>)

    Purpose: The trim() function removes the trailing and leading spaces
    from a container. For example,

    trim("   hello   ")

    returns "hello".

    Examples:

    put the trim of page field 1 into page field 5;

    -----------------------------------
    TRUNC

    Syntax:
    trunc(<number>)

    Purpose: This function returns the integer portion of a number. The
    function does not round the number, it simply ignores all digits
    following the decimal point. For example,

    trunc(56.78)

    returns 56.

    Examples:

    put the trunc of 7.489 into IT;

    put the trunc of "P" into the message box;

    See Also: round()



    ________________________________________________________________________
                                              Chapter 13: Functions   276
    ________________________________________________________________________


    -----------------------------------
    UPPER

    Syntax:
    upper(<string>)

    Purpose: This function returns the string in all uppercase leaving
    characters that aren't letters unchanged. For example,

    upper("Hello World 123")

    returns "HELLO WORLD 123".

    Examples:

    put upper("this is a string") into the msg;

    See Also: lower()

    -----------------------------------
    VARIANCE

    Syntax:
    variance(<rate>,<previous>)

    Purpose: This function returns the variance of two or more numbers.

    Examples:

    put the variance of 6600, 7954, 4399, 7895;

    See Also: compound(), annuity()

    -----------------------------------
    VERSION

    Syntax:
    version()

    Purpose: The version() returns the version number of
    HyperPAD.

    Examples:

    put the version in the message box;
