
********
wcCODE
*************************************************************************

This file contains information that became available after the manual was
printed.  Please review it carefully.

*************************************************************************

If you installed the sample wcCODE applications, they have been placed
in a directory named CODESAMP (by default) located under your Wildcat!
home directory.  Each program is commented and may require modification
before operation.

New features
------------

- C++ style // comments are now supported

- Added BOOLEAN (8 bit signed) and WORD (16 bit unsigned) data types

- The ACTIVECONF field in the user record is now available.  Assigning a
  value to User.ActiveConf is equivalent to calling Join.

- The BYVAL keyword can be used in front of a function argument in its
  declaration to force call-by-value semantics.
    For example, this is now legal:
    sub test(byval s as string)
      print s
    end sub
    dim a as string*10
    a = "test"
    test(a)
  Previously you had to call it with test((a)) which was ugly.

- WCC386.EXE is a protected mode version of the compiler that has a much
  larger capacity.

- A new command line parameter to WCC or WCC386 so you can find runtime
  errors from the command line.  For example,
    wcc test /f1234
  will find the source location that corresponds to location 1234.


New functions
-------------

ADDMARKFILE(fn as string, area as word) as boolean
 - This function adds the file "fn" to the user's mark list.  The file must
exist in the file database.  If there is more than one file by the name
"fn" in the file database, the area must be specified, otherwise it is
optional.  This function returns True if the file was successfully added to
tha mark list.

ADDMARKFILEDIRECT(fn as string) as boolean
 - This function adds the file "fn" to the user's mark list.  The file does
not have to exist in the file database but a full path should be specified
to the file.  This function returns True if the file was successfully added
to the mark list.

DATESTRINGTODATE(mask as string, s as string, d as date)
 - This statement converts a date in string format into a Date variable
based on a mask.  For example, DateStringToDate("mm/dd/yy", "09/15/70", d)
will cause d to contain the date value for September 15, 1970.

DELETEFILE(fn as string, area as integer, disktoo as boolean) as boolean
 - This function removes the file named "fn" in area "area" from the file
database.  The "disktoo" parameter indicates whether or not the file will
be removed from disk as well as from the database.  This function returns
True if the file was successfully removed.

DELETEUSER(userid as long) as boolean
 - This function deletes a user from the user database by user id number.
This function returns True if the user is successfully deleted.

DISPLAYMENU(fn as string)
 - This statement displays a menu display file from the menu display file
directory.  For example, DisplayMenu("MSG") might display MSG5.BBS based on
the user's security level and current display mode.

DMYTODATE(day as integer, month as integer, year as integer, d as date)
 - This statement converts a date in day/month/year format to a Wildcat
Date type variable.

EDITFILE(fn as string, maxlines as integer, title as string) as boolean
 - This function brings up the Wildcat full-screen editor to edit the file
"fn".  If "maxlines" is specified, the number of lines in the file is
limited to "maxlines".  If it is omitted the number of lines is limited to
150.  The "title" is displayed at the top of the screen during editing the
file.  This function returns True if the user selects [S]ave at the edit
message prompt.

EDITMESSAGE(msg as messageheader, fn as string, maxlines as integer) as
boolean
 - This function is similar to EDITFILE, except that it takes a message
header in addition to the file name and maximum number of lines.  The
message header should already be filled in with valid information when this
function is called.  This function returns True if the user selects [S]ave
at the edit message prompt.

EVENTRUNNING as boolean
 - This function returns true if the wcCODE program is running from an event.

FASTLOGONCHAR as string
 - This function returns the fast logon character, if any, used at logon.

FLAGCLEAR(flag as integer/long, value as integer/long)
 - This function clears the flag specified by "value" in the "flag"
variable.

FLAGISSET(flag as integer/long, value as integer/long)
 - This function tests the "flag" variable for the flag specified by
"value".  It returns True if the flag is set, or False if it is not set.

FLAGSET(flag as integer/long, value as integer/long)
 - This function sets the flag specified by "value" in the "flag" variable.

FORMATNUMBER(n as long/real, mask as string) as string
 - This function formats a number according to a mask specification.

The FormatNumber function offers advanced numeric formatting especially
applicable to financial reports.

The mask parameter is a string that can contain any combination of normal
characters as well as a sequence of the special characters # * @ $ - + , .
This sequence is called a numeric field, and FormatNumber replaces it with
a formatted version of the number.  The number is returned right-justified
within the field, decimals are returned rounded if they exceed the number
of decimals specified by the format, and if the number is too large to be
returned in the field, all digit positions are filled with asterisks.

The special characters represent:

# A digit position.  If the numeric field contains no * or @ characters,
unused digits are returned as blanks.  If the numeric field contains no
sign positions (+ or - characters) and the number is negative, a floating
minus is returned in front of the number.  Examples:

      FormatNumber(34.567, "####") returns "  35"
      FormatNumber(-12.3, "####.##") returns " -12.30"
      FormatNumber(1000.0, "##.##") returns "**.**"

* A digit position.  Unused positions are returned as asterisks instead of
blanks.  The * character needs to occur only once in the numeric field to
activate this effect.  The sign of the number is not returned unless the
field also contains a sign character (- or +).  Examples:

      FormatNumber(4.567, "*##.##") returns "**4.57"
      FormatNumber(123, "****") returns "*123"

@ A digit position.  Unused positions are returned as zeros instead of
blanks.  The @ character needs to occur only once in the numeric field to
activate this effect.  The sign of the number is not returned unless the
field also contains a sign character (- or +).  Examples:

      FormatNumber(9, "@##") returns "009"
      FormatNumber(12.3, "@@@.@@") returns "012.30"

$ A digit position.  A floating dollar sign is returned in front of the
number.  The $ character needs to occur only once in the numeric field to
activate this effect.  Examples:

      FormatNumber(123.45, "$####.##") returns " $123.45"
      FormatNumber(12.34, "*$####.##") returns "***$12.34"

- A sign position.  If the number is negative, a minus sign is returned in
that position.  If it is positive, a blank is returned.  Examples:

      FormatNumber(-1.2, "-###.##") returns "-  1.20"
      FormatNumber(1.2, "-###.##") returns "   1.20"

+ A sign position.  If the number is positive, a plus is returned in that
position.  If it is negative, a minus is returned.  Examples:

      FormatNumber(1.2, "+###.##") returns "+  1.20"
      FormatNumber(-12.34, "*$####.##+") returns "***$12.34-"

, A decimal comma or a separator comma.
. A decimal period or a separator period.  The last period or comma in the
numeric field is considered the decimal delimiter.  Examples:

      FormatNumber(123456.78, "##,###,###.##") returns "   123,456.78"
      FormatNumber(-12345.6, "$#.###.###,##") returns "  -$12.345,60"

Note: The most frequently asked question about FormatNumber concerns cases
like this:

      print FormatNumber(1000.0, "###,###,###")

What many users expect is "      1,000".  What they get is "  1,000,000".
This is not a bug.  When using real numbers, FormatNumber treats the last
period or comma in the mask as marking the decimal point, allowing
FormatNumber to be used in countries that use commas in places where
Americans use periods.  To get the expected result, you would need to add a
final decimal point to the mask ("###,###,###.") and then remove it from
the string returned by FormatNumber.  This does not happen when using
FormatNumber to format integers.

GETFIRSTFILE(f as filerecord, key as integer) as boolean
 - This function gets the first file in the database based on the key
number specified in "key".  The key numbers are as follows:
 1 = Sorted by file area, then name
 2 = Sorted by file name, then area
 3 = Sorted by file area, then date
 4 = Sorted by file uploader name/id
If the key is omitted, the default key is 2.  This function returns True if
the file record was successfully obtained.
 
GETFIRSTMESSAGE(msg as messageheader) as boolean
 - This function gets the first message in the current conference.  The
return value is True if the message header was successfully obtained.

GETFIRSTUNREAD(conf as integer) as integer
 - This function reads the user's first-unread message number for the
conference specified by "conf".

GETFIRSTUSER(u as userrecord, key as integer) as boolean
 - This function gets the first user in the database based on the key
number specified in "key".  The key numbers are as follows:
 1 = Sorted by user name (last name first)
 2 = Sorted by security level, then name
 3 = Sorted by expiration date, then name
 4 = Sorted by alias
 5 = Sorted by user id
 6 = Sorted by real name (first name then last name)
If the key is omitted, the default key is 1.  This function returns True if
the user record was successfully obtained.

GETHIGHMESSAGE as integer
 - This function returns the highest message number in the current
conference.

GETLASTFILE(f as filerecord, key as integer) as boolean
 - This function gets the last file in the database based on the key number
specified in "key" (see GETFIRSTFILE for key numbers).  This function
returns True if the file record was successfully obtained.

GETLASTMESSAGE(msg as messageheader) as boolean
 - This function gets the last message in the current conference.  The
return value is True if the message header was successfully obtained.

GETLASTREAD(conf as integer) as integer
 - This function reads the user's last-read message number for the
conference specified by "conf".

GETLASTUSER(u as userrecord, key as integer) as boolean
 - This function gets the last user in the database based on the key number
specified in "key" (see GETFIRSTUSER for key numbers).  This function
returns True if the user record was successfully obtained.

GETLOWMESSAGE as integer
 - This function returns the lowest message number in the current
conference.

GETMARKEDFILES as integer
 - This function returns the number of marked files in the user's mark
list.

GETMARKEDFILEAREA(i as integer) as integer
 - This function returns the file area for the "i"th marked file in the
mark list.  If i is out of range this function returns 0.

GETMARKEDFILENAME(i as integer) as string
 - This function returns the file name for the "i"th marked file in the
mark list.  If i is out of range this function returns an empty string.

GETPREVFILE(f as filerecord, key as integer) as boolean
 - This function gets the file record before the specified file record in
the order specified by "key" (see GETFIRSTFILE for key numbers).  This
function returns True if the file record was successfully obtained.

GETPREVMESSAGE(msg as messageheader) as boolean
 - This function gets the message before the specified message in the
current conference.  This function returns True if the message header was
successfully obtained.

GETPREVUSER(u as userrecord, key as integer) as boolean
 - This function gets the user record before the specified user record in
the order specified by "key" (see GETFIRSTUSER for key numbers).  This
function returns True if the user record was successfully obtained.

GETUSERCONFFLAGS(conf as integer) as integer
 - This function returns the user's conference flags for conference "conf".

GOTOMENU(menuname as string) as boolean
 - This function sets the next menu to be the menu specified by "menuname".
 Menuname must be the same as the "Menu description" as specified in
Makemenu (case is not significant when searching for the menu name).  Note
that the menu will not be immediately displayed, but will be displayed the
next time the user enters the menu system (usually when the wcCODE program
ends).  Also note that the menu security is NOT checked against the user's
security level when using this function.  This function returns True if the
menu was successfully found.

HMSTOTIME(hour as integer, min as integer, sec as integer, t as time)
 - This statement converts a time in hour:minute:second format to a Wildcat
Time type variable.

INCDATE(d as date, days as integer, months as integer, years as integer)
 - This statement advances a Date type variable "d" by the amount of time
specified in the "days", "months", and "years" parameters.

INCDATETIME(dt as datetime, days as integer, seconds as integer)
 - This statement advances as DateTime type variable "dt" by the amount of
time specified in the "days" and "seconds" parameters.


LOCKCONFERENCE(conf as integer) as boolean
 - This function opens and locks the specified conference.  During the time
the conference is locked, the message database is open and wcPACK cannot
pack the conference.  This can be used to speed up repeated access to a message
database.  See also UNLOCKCONFERENCE.

LOCKFILE(filenum as integer, start as long, length as long) as boolean
 - This function locks the file specified by "filenum" starting at position
"start" and covering "length" records.  Files locked using this function
MUST be unlocked using UNLOCKFILE with the same start and length
parameters otherwise unpredictable results may occur.  To protect the
integrity of the Wildcat system, this function should not be used to
lock any Wildcat files.  This function returns True if the attempt to
lock the file was successful.

MARKMESSAGEREAD(n as integer) as boolean
 - This function marks the message numbered "n" in the current conference
as read.  This function returns True if the message was successfully marked
as read.

MID()
 - The MID() function can now be used on the left hand side of an
assignment statement to modify part of a string.

NODEBELL(onoff as boolean) as boolean
NODEDOSNEXT(onoff as boolean) as boolean
NODEKEYBOARD(onoff as boolean) as boolean
NODELOCALNEXT(onoff as boolean) as boolean
NODEMAINTMODE(onoff as boolean) as boolean
NODEPAGE(onoff as boolean) as boolean
NODEPRINTER(onoff as boolean) as boolean
NODESCREENWRITE(onoff as boolean) as boolean
NODESYSOPNEXT(onoff as boolean) as boolean
 - Each of these functions takes an optional on/off parameter to set the
corresponding option in the nodeinfo record, and they return the
previous value of the flag.  Without an argument they will just return
the current value of the flag.

PARAMCOUNT as integer
 - This function returns the number of parameters passed on the command
line to this wcCODE program.

PARAMSTR(n as integer) as integer
 - This function returns the "n"th command line parameter passed on the
command line to this wcCODE program.

READBACKCLOSE
 - This statement closes the file that is currently opened for backward
reading.

READBACKNEXT as string
 - This function returns the next line in the text file that is currently
opened for backward reading.  The "next" line is actually the line that
precedes the last line read.

READBACKOPEN(fn as string) as boolean
 - This function opens the text file "fn" for backward reading.  The return
value is True if the file is opened successfully.

READBACKTOF as boolean
 - This function returns True if the file pointer in the file that is
currently open for backward reading has reached the beginning of the file.

RECEIVEFILE(fn as string, protocol as integer) as boolean
 - This function receives a file into "fn" using the file transfer protocol
specified in "protocol".  If protocol is not specified then the user is
prompted for a protocol.  The protocol is one of Xmodem, XmodemCrc, Ymodem,
YmodemG, Xmodem1K, Xmodem1KG, Kermit, Zmodem, Ascii, or Ext1 through Ext10.
 This function returns True if the file transfer is successful.

REMOVEMARKFILE(n as integer)
 - This statement removes the "n"th marked file from the mark list.

SETIDLETIMEOUT(min as integer)
 - This statement sets the Wildcat idle timeout to "min" minutes.  This
setting remains in effect until the user logs off.

SETLASTREAD(conf as integer, lastread as integer)
 - This statement sets the user's last-read number in conference "conf" to
"lastread".

SETLOGONNAME(name as string, logonparams as string)
 - This statement is for use in PRELOG.WCC, it has no effect when used
elsewhere.  It allows you to set the logon name used when Wildcat is about
to ask the user for their name.  If this function has been called then
Wildcat will not ask the "What is your first name?" question, but will
automatically answer it with the name passed to this statement.  Note that
you can also include a password in the name parameter, just as you can when
logging in normally.  The "logonparams" parameter is used as the command
line to LOGON.WCC, if present.

SETUSERCONFFLAGS(conf as integer, flags as integer)
 - This statement sets the user's per-conference flags to "flags" for
conference "conf".  The user's current flags should be read with
GETUSERCONFFLAGS before using this function in order to retain the values
of flags that you don't intend to change.

SIZEOF(x)
 - This function returns the size of either a type or a variable.
When used with a type it works exactly the same way as LEN(), but with
a variable it will return the size, in bytes, of the variable.

STATUSCLEAR(color as byte)
 - This statement clears the status area, if any, to the color specified in
"color".  If the color parameter is omitted the default color is black text
on a white background.

STATUSCLEARLINE(line as integer, color as byte)
 - This statement clears the line specified by "line" to the color
specified in "color".  If the color parameter is omitted the default color
is black text on a white background.

STATUSCLOSE
 - This statement removes the status area, if any.

STATUSOPEN(lines as integer)
 - This statment opens a status area of "lines" lines near the bottom of
the Wildcat screen, above the user status window.  The other STATUSxxx
functions can be used to display information in this status window.

STATUSSCROLL(lines as integer, color as byte)
 - This statement scrolls the status area by "lines" lines, up if lines is
positive, and down if lines is negative.  The new lines are cleared to the
color specified in "color".  If the color parameter is omitted the default
color is black text on a white background.

STATUSWRITE(s as string, x as integer, y as integer, color as byte)
 - This statement writes information to the status area.  If the position
(x and y) is not specified, the text is written to the last line of the
status area after scrolling the existing information up by one line.  This
makes it easy to write information to the status area without worrying
about scrolling or position.  If the color is not specified in "color", the
existing screen color is used.

TICKER as long
 - This function returns the number of 18.2 Hz timer ticks since midnight.

TIMESTRINGTOTIME(mask as string, s as string, t as time)
 - This statement converts a time in string format into a Time variable
based on a mask.  For example, TimeStringToTime("hh:mm:ss", "09:32:00", t)
will cause t to contain the time value for 9:32am.

UNLOCKCONFERENCE
 - This statement unlocks the conference that has been locked with
LOCKCONFERENCE.

UNLOCKFILE(filenum as integer, start as long, length as long) as boolean
 - This function unlocks the file specified by "filenum" starting at
position "start" and covering "length" bytes.  Files unlocked using this
function MUST have been locked using LOCKFILE with the same start and
length parameters otherwise unpredictable results may occur.  This
function returns True if the attempt to unlock the file was successful.

VALIDDATE(day as integer, month as integer, year as integer) as boolean
 - This function returns True if the date specified by the day, month, and
year parameters is a valid date.

WCMSGHDRFILEABORT(fn as string)
 - This statement is for use in FIDOENTR.WCC or INETENTR.WCC.  It erases
the file specified by fn (no path is allowed, the file is always erased
from the node work directory).

WCMSGHDRFILEREAD(msg as messageheader, fn as string)
 - This function is for use in FIDOENTR.WCC or INETENTR.WCC.  It reads the
message header in the file "fn" in the node work directory into the msg
variable.

WCMSGHDRFILEWRITE(msg as messageheader, fn as string) as boolean
 - This function is for use in FIDOENTR.WCC or INETENTR.WCC.  It writes the
message header "msg" to the file "fn" in the node work directory.  When the
wcCODE program returns to Wildcat, Wildcat will read the message header
back from the file.

Changed functions
-----------------

ADDMESSAGE
 - Now takes two optional parameters, an attachment file name and
conference in which to place the message.  Also will fill in the message
number in the message header upon return.

CHAIN
 - Now takes an optional parameter specifying the parameters to pass to the
next wcCODE program.

DOWNLOAD
 - Now takes two optional parameters, a file name and area.  If these
parameters are not present then the user is prompted for a file.

FILEINFO
 - Now takes two optional parameters, a file name and area.  If these
parameters are not present then the user is prompted for a file.

GETNEXTFILE
 - Now takes an optional key number.  For file database key numbers, see
GETFIRSTFILE.

GETNEXTUSER
 - Now takes an optional key number.  For user database key numbers, see
GETFIRSTUSER.

GOODBYE
 - Now takes an optional parameter indicating whether you would like
Wildcat to ask the user whether they would really like to log off or not.

INPUTMASK
 - Now takes two additional optional parameters, a default response and a
flag indicating to Wildcat to echo back stars (*) to the user instead of
what they typed (this is useful for entering passwords).

INPUTYESNO
 - Now takes an optional parameter indicating the default response.

JOIN
 - The parameter to JOIN is now optional, if omitted it will allow the user
to select a conference from the list.

LISTFILES
 - Now takes an optional parameter indicating the file area.

LISTFILESDATA
 - Now takes an optional parameter indicating the file area.

MID
 - The last parameter is now optional, if omitted MID will return the
remainder of the string starting at the start position.

QUESTIONNAIRE
 - Now can take a questionnaire file name as a parameter so you can run
QUESDATE with QUESTIONNAIRE "QUESDATE".

READTEXTFILE
 - Now takes two optional parameters, the file name and area.

RUN
 - Now takes an optional parameter specifying the parameters to pass to the
next wcCODE program.

SEARCHFILES
 - Now takes an optional parameter indicating the file area.

SENDFILE
 - Now takes an optional parameter indicating the file transfer protocol to
use (see RECEIVEFILE for a list of valid transfer protocol identifiers).

VIEWFILE
 - Now takes two optional parameters, the file name and area.


Fixes
-----

- Fixed problem with UPDATEUSER

- Fixed problem with FINDFIRST

- Fixed problem with GETNEXTMESSAGE

- Opening a file for APPEND now recognizes a Ctrl-Z at the end of the file

- Changing the user language with User.Language = "LANGUAGE" now works

- Fixed problem with any RIP command that takes a string parameter

- Fixed problem with CURRENTDATE when used on a user date field

- Fixed problem with updating user last-new-files date

- GETUSER and GETFILEINFO now work with a blank name to get the first record

- Alias names are now checked for duplicates when set with user.alias="..."


