 COMMAND_NAME                          X                       NeoSoft, Inc.

                         COMMAND_NAME - PACKAGE_TYPE

  Short description of what the command does

Synopsis:

*  command_name argument argument argument

Description

A longer description of what the command does goes here

----------------------------------------------------------------------------
 ABORT_PAGE                           1                       NeoSoft, Inc.

                          ABORT_PAGE - Neowebscript

  Aborts execution immediately

Synopsis:

*  abort_page

Description

Aborts NeoWebScript execution immediately. Does not emit any of the rest of
the webpage to the requester. Remaining code in the script being executed
will still be executed, so abort_page is typically immediately followed by
return.

----------------------------------------------------------------------------
 ACCESS_DATA_FILE                     2                       NeoSoft, Inc.

                       ACCESS_DATA_FILE - Neowebscript

  Opens the specified datafile for reading and writing, creating if not there

Synopsis:

*  access_data_file datafile

Description

access_data_file opens the specified datafile for reading and writing,
creating it if its not there. Datafile name can consist of upper and
lowercase letters and numbers only. No slashes, no periods, etc. The file
can then be operated on in the normal manner by gets, puts, seek, tell,
flush, close, etc.

----------------------------------------------------------------------------
 APPEND                               3                       NeoSoft, Inc.

                              APPEND - Safe TCL

   Append to variable

Synopsis:

* append varName ? value value value ... ?

Description

Append all of the value arguments to the current value of variable varName.
If varName doesnt exist, it is given a value equal to the concatenation of
all the value arguments. This command provides an efficient way to build up
long variables incrementally. For example, "append a $b" is much more
efficient than "set a $a$b" if $a is long.

Keywords:

 append, variable

----------------------------------------------------------------------------
 ARRAY                                4                       NeoSoft, Inc.

                              ARRAY - Safe TCL

  Manipulate array variables

Synopsis:

* arrrayoption arrayName ?arg arg ...?

Description

This command performs one of several operations on the variable given by
arrayName. Unless otherwise specified for individual commands below,
arrayName must be the name of an existing array variable. The option
argument determines what action is carried out by the command. The legal
options (which may be abbreviated) are:

array anymore arrayName searchId
Returns 1 if there are any more elements left to be processed in an array
search, 0 if all elements have already been returned. SearchId indicates
which search on arrayName to check, and must have been the return value from
a previous invocation of array startsearch. This option is particularly
useful if an array has an element with an empty name, since the return value
from array nextelement wont indicate whether the search has been completed.

array donesearch arrayName searchId
This command terminates an array search and destroys all the state
associated with that search. SearchId indicates which search on arrayName to
destroy, and must have been the return value from a previous invocation of
array startsearch. Returns an empty string.

array exists arrayName
Returns 1 if arrayName is an array variable, 0 if there is no variable by
that name or if it is a scalar variable.

array get arrayName ?pattern?
Returns a list containing pairs of elements. The first element in each pair
is the name of an element in arrayName and the second element of each pair
is the value of the array element. The order of the pairs is undefined. If
pattern is not specified, then all of the elements of the array are included
in the result. If pattern is specified, then only those elements whose names
match pattern (using the glob-style matching rules of string match) are
included. If arrayName isnt the name of an array variable, or if the array
contains no elements, then an empty list is returned.

array names arrayName ?pattern?
Returns a list containing the names of all of the elements in the array that
match pattern (using the glob-style matching rules of string match). If
pattern is omitted then the command returns all of the element names in the
array. If there are no (matching) elements in the array, or if arrayName
isnt the name of an array variable, then an empty string is returned.

array nextelement arrayName searchId
Returns the name of the next element in arrayName, or an empty string if all
elements of arrayName have already been returned in this search. The
searchId argument identifies the search, and must have been the return value
of an array startsearch command. Warning: if elements are added to or
deleted from the array, then all searches are automatically terminated just
as if array donesearch had been invoked; this will cause array nextelement
operations to fail for those searches.

array set arrayName list
Sets the values of one or more elements in arrayName. list must have a form
like that returned by array get, consisting of an even number of elements.
Each odd-numbered element in list is treated as an element name within
arrayName, and the following element in list is used as a new value for that
array element.

array size arrayName
Returns a decimal string giving the number of elements in the array. If
arrayName isnt the name of an array then 0 is returned.

array startsearch arrayName
This command initializes an element-by-element search through the array
given by arrayName, such that invocations of the array nextelement command
will return the names of the individual elements in the array. When the
search has been completed, the array donesearch command should be invoked.
The return value is a search identifier that must be used in array
nextelement and array donesearch commands; it allows multiple searches to be
underway simultaneously for the same array.

See Also:

bgerror

Keywords:

array, element names, search

----------------------------------------------------------------------------
 BACKLINK                             5                       NeoSoft, Inc.

                           BACKLINK - Neowebscript

  Emit a hyperlink pointing to the referer URL

Synopsis:

*  backlink [linktext] [nolinktext]

Description

Emit a hyperlink pointing to the referer URL, with linktext emitted as HTML
text within the hyperlink. Emits nolinktext if there was no referer.

See Also:

bgerror

Keywords:

array, element names, search

----------------------------------------------------------------------------
 BREAK                                6                       NeoSoft, Inc.

                              BREAK - Safe TCL

  Abort looping command

Synopsis:

* break

Description

This command is typically invoked inside the body of a looping command such
as for or foreach or while. It returns a TCL_BREAK code, which causes a
break exception to occur. The exception causes the current script to be
aborted out to the innermost containing loop command, which then aborts its
execution and returns normally. Break exceptions are also handled in a few
other situations, such as the catch command, Tk event bindings, and the
outermost scripts of procedure bodies.

See Also:

bgerror

Keywords:

abort, break, loop

----------------------------------------------------------------------------
 BSEARCH                              7                       NeoSoft, Inc.

                           BSEARCH - Extended TCL

  Searches an sorted  file for a match

Synopsis:

*  bsearch fileId key ?retvar? ?compare_proc?

Description

Search an opened file fileId containing lines of text sorted into ascending
order for a match. Key contains the string to match. If retvar is specified,
then the line from the file is returned in retvar, and the command returns 1
if key was found, and 0 if it wasnt. If retvar is not specified or is a
null name, then the command returns the line that was found, or an empty
string if key wasnt found.

By default, the key is matched against the first white-space separated field
in each line. The field is treated as an ASCII string. If compare_proc is
specified, then it defines the name of a Tcl procedure to evaluate against
each line read from the sorted file during the execution of the bsearch
command. Compare_proc takes two arguments, the key and a line extracted from
the file. The compare routine should return a number less than zero if the
key is less than the line, zero if the key matches the line, or greater than
zero if the key is greater than the line. The file must be sorted in
ascending order according to the same criteria compare_proc uses to compare
the key with the line, or erroneous results will occur.

See Also:

bgerror

Keywords:

abort, break, loop

----------------------------------------------------------------------------
 CASE                                 8                       NeoSoft, Inc.

                               CASE - Safe TCL

  Evaluate one of several scripts, depending on a given value

Synopsis:

*  case string ?in? patList body  ? patList body
 ...?
*  case string ?in? {patList body  ? patList
body ...?}

Description

Note: the case command is obsolete and is supported only for backward
compatibility. At some point in the future it may be removed entirely. You
should use the switch command instead.

The case command matches string against each of the patList arguments in
order. Each patList argument is a list of one or more patterns. If any of
these patterns matches string then case evaluates the following body
argument by passing it recursively to the Tcl interpreter and returns the
result of that evaluation. Each patList argument consists of a single
pattern or list of patterns. Each pattern may contain any of the wild-cards
described under string match. If a patList argument is default, the
corresponding body will be evaluated if no patList matches string. If no
patList argument matches string and no default is given, then the case
command returns an empty string.

Two syntaxes are provided for the patList and body arguments. The first uses
a separate argument for each of the patterns and commands; this form is
convenient if substitutions are desired on some of the patterns or commands.
The second form places all of the patterns and commands together into a
single argument; the argument must have proper list structure, with the
elements of the list being the patterns and commands. The second form makes
it easy to construct multi-line case commands, since the braces around the
whole list make it unnecessary to include a backslash at the end of each
line. Since the patList arguments are in braces in the second form, no
command or variable substitutions are performed on them; this makes the
behavior of the second form different than the first form in some cases.

See Also:

bgerror

Keywords:

case, match, regular expression

----------------------------------------------------------------------------
 CATCH                                9                       NeoSoft, Inc.

                              CATCH - Safe TCL

  Evaluate script and trap exceptional returns

Synopsis:

* catch script ?varName?

Description

The catch command may be used to prevent errors from aborting command
interpretation. Catch calls the Tcl interpreter recursively to execute
script, and always returns a TCL_OK code, regardless of any errors that
might occur while executing script. The return value from catch is a decimal
string giving the code returned by the Tcl interpreter after executing
script. This will be 0 (TCL_OK) if there were no errors in script; otherwise
it will have a non-zero value corresponding to one of the exceptional return
codes (see tcl.h for the definitions of code values). If the varName
argument is given, then it gives the name of a variable; catch will set the
variable to the string returned from script (either a result or an error
message).

Note that catch catches all exceptions, including those generated by break
and continue as well as errors.

See Also:

bgerror

Keywords:

catch, error

----------------------------------------------------------------------------
 CCOLLATE                            10                       NeoSoft, Inc.

                           CCOLLATE - Extended TCL

  Compares two strings

Synopsis:

*  ccollate ?-local? string1 string2

Description

This command compares two strings. If returns -1 if string1 is less than
string2, 0 if they are equal amd 1 if string1 is greater than string2.

If -local is specified, the strings are compared according to the collation
environment of the cur- rent locale.

See Also:

bgerror

Keywords:

catch, error

----------------------------------------------------------------------------
 CEQUAL                              11                       NeoSoft, Inc.

                            CEQUAL - Extended TCL

  Compares two strings for equality

Synopsis:

*  cequal string1 string2

Description

This command compares two strings for equality. It returns 1 if string1 and
string2 are the identical and 0 if they are not. This command is a short-cut
for string compare and avoids the problems with string expressions being
treated unintentionally as numbers.

See Also:

bgerror

Keywords:

catch, error

----------------------------------------------------------------------------
 CINDEX                              12                       NeoSoft, Inc.

                            CINDEX - Extended TCL

  Returns character indexed by expression indexExpr

Synopsis:

*  cindex string indexExpr

Description

Returns the character indexed by the expression indexExpr (zero based) from
string.

If the expression indexExpr starts with the string end, then end is replaced
with the index of the last character in the string. If the expression starts
with len, then len is replaced with the length of the string.

See Also:

bgerror

Keywords:

catch, error

----------------------------------------------------------------------------
 CLENGTH                             13                       NeoSoft, Inc.

                           CLENGTH - Extended TCL

  Returns length of string (number of characters)

Synopsis:

*  clength string

Description

Returns the length of string in characters. This command is a shortcut for:

string length string

See Also:

bgerror

Keywords:

catch, error

----------------------------------------------------------------------------
 CLOCK                               14                       NeoSoft, Inc.

                              CLOCK - Safe TCL

  Obtain and manipulate time

Synopsis:

* clock option?arg arg...?

Description

This command performs one of several operations that may obtain or
manipulate strings or values that represent some notion of time. The option
argument determines what action is carried out by the command. The legal
options (which may be abbreviated) are:

clock clicks
Return a high-resolution time value as a systemdependent integer value. The
unit of the value is system-dependent but should be the highest resolution
clock available on the system such as a CPU cycle counter. This value should
only be used for the relative measurement of elapsed time.

clock format clockValue ?-format string? ?-gmt boolean? Converts an integer
time value, typically returned by clock seconds, clock scan, or the atime,
mtime, or ctime options of the file command, to humanreadable form. If the
-format argument is present the next argument is a string that describes how
the date and time are to be formatted. Field descriptors consist of a %
followed by a field descriptor character. All other characters are copied
into the result. Valid field descriptors are:

%%
     Insert a %.

%a
     Abbreviated weekday name. (Mon, Tue, etc.)

%A
     Full weekday name. (Monday, Tuesday, etc.)

%b
     Abbreviated month name. (Jan, Feb, etc.)

%B
     Full month name.

%d
     Day of month (01 - 31).

%D
     Date as %m/%d/%y.

%e
     Day of month (1 - 31), no leading zeros.

%h
     Abbreviated month name.

%H
     Hour (00 - 23).

%I
     Hour (00 - 12).

%j
     Day number of year (001 - 366).

%m
     Month number (01 - 12).

%M
     Minute (00 - 59).

%n
     Insert a newline.

%p
     AM or PM.

%r
     Time as %I:%M:%S %p.

%R
     Time as %H:%M.

%S
     Seconds (00 - 59).

%t
     Insert a tab.

%T
     Time as %H:%M:%S.

%U
     Week number of year (01 - 52), Sunday is the first day of the week.

%w
     Weekday number (Sunday = 0).

%W
     Week number of year (01 - 52), Monday is the first day of the week.

%x
     Local specific date format.

%X
     Local specific time format.

%y
     Year within century (00 - 99).

%Y
     Year as ccyy (e.g. 1990)

%Z
     Time zone name.

If the -format argument is not specified, the format string "%a %b %d
%H:%M:%S %Z %Y" is used. If the -gmt argument is present the next argument
must be a boolean which if true specifies that the time will be formated as
Greenwich Mean Time. If false then the local timezone will be used as
defined by the operating environment.

clock scan dateString ?-base clockVal? ?-gmt boolean? Convert dateString to
an integer clock value (see clock seconds). This command can parse and
convert virtually any standard date and/or time string, which can include
standard time zone mnemonics. If only a time is specified, the current date
is assumed. If the string does not contain a time zone mnemonic, the local
time zone is assumed, unless the -gmt argument is true, in which case the
clock value is calculated assuming that the specified time is relative to
Greenwich Mean Time.

If the -base flag is specified, the next argument should contain an integer
clock value. Only the date in this value is used, not the time. This is
useful for determining the time on a specific day or doing other
date-relative conversions.

The dateString consists of zero or more specifications of the following
form:

time A time of day, which is of the form: hh?:mm?:ss?? ?meridian? ?zone? or
hhmm ?meridian? ?zone?. If no meridian is specified, hh is interpreted on a
24-hour clock.

date
     A specific month and day with optional year. The acceptable formats are
     mm/dd?/yy?, monthname dd ?, yy?, dd monthname ?yy? and day, dd
     monthname yy. The default year is the current year. If the year is less
     then 100, then 1900 is added to it.

relative time
A specification relative to the current time. The format is number unit
acceptable units are year, fortnight, month, week, day, hour, minute (or
min), and second (or sec). The unit can be specified as a singular or
plural, as in 3 weeks. These modifiers may also be specified: tomorrow,
yesterday, today, now, last, this, next, ago.

The actual date is calculated according to the following steps. First, any
absolute date and/or time is processed and converted. Using that time as the
base, day-of-week specifications are added. Next, relative specifications
are used. If a date or day is specified, and no absolute or relative time is
given, midnight is used. Finally, a correction is applied so that the
correct hour of the day is produced after allowing for daylight savings time
differences.

clock seconds
Return the current date and time as a systemdependent integer value. The
unit of the value is seconds, allowing it to be used for relative time
calculations. The value is usually defined as total elapsed time from an
"epoch". You shouldnt assume the value of the epoch.

See Also:

bgerror

Keywords:

clock, date, time

----------------------------------------------------------------------------
 CLOSE                               15                       NeoSoft, Inc.

                              CLOSE - Safe TCL

  Close an open channel

Synopsis:

* close channelID

Description

Closes the channel given by channelId. ChannelId must be a channel
identifier such as the return value from a previous open or socket command.
All buffered output is flushed to the channels output device, any buffered
input is discarded, the underlying file or device is closed, and channelId
becomes unavailable for use.

If the channel is blocking, the command does not return until all output is
flushed. If the channel is nonblocking and there is unflushed output, the
channel remains open and the command returns immediately; output will be
flushed in the background and the channel will be closed when all the
flushing is complete.

If channelId is a blocking channel for a command pipeline then close waits
for the child processes to complete.

If the channel is shared between interpreters, then close makes channelId
unavailable in the invoking interpreter but has no other effect until all of
the sharing interpreters have closed the channel. When the last interpreter
in which the channel is registered invokes close, the cleanup actions
described above occur. See the interp command for a description of channel
sharing.

Channels are automatically closed when an interpreter is destroyed and when
the process exits. Channels are switched to blocking mode, to ensure that
all output is correctly flushed before the process exits.

The command returns an empty string, and may generate an error if an error
occurs while flushing output.

See Also:

bgerror

Keywords:

blocking, channel, close, nonblocking

----------------------------------------------------------------------------
 CMDTRACE                            16                       NeoSoft, Inc.

                           CMDTRACE - Neowebscript



Synopsis:

*  cmdtrace args

Description

The Extended Tcl command cmdtrace will work if supervisor mode is enabled
for the directory.

See Also:

bgerror

Keywords:

blocking, channel, close, nonblocking

----------------------------------------------------------------------------
 CONCAT                              17                       NeoSoft, Inc.

                              CONCAT - Safe TCL

  Join lists together

Synopsis:

* concat arg arg ...?

Description

This command treats each argument as a list and concatenates them into a
single list. It also eliminates leading and trailing spaces in the args and
adds a single separator space between args. It permits any number of
arguments. For example, the command
concat a b {c d e} {f {g h}} will return
a b c d e f {g h}
as its result.

If no args are supplied, the result is an empty string.

See Also:

bgerror

Keywords:

concatenate, join, lists

----------------------------------------------------------------------------
 CONTINUE                            18                       NeoSoft, Inc.

                             CONTINUE - Safe TCL

  Skip to the next iteration of a loop

Synopsis:

* continue

Description

This command is typically invoked inside the body of a looping command such
as for or foreach or while. It returns a TCL_CONTINUE code, which causes a
continue exception to occur. The exception causes the current script to be
aborted out to the the innermost containing loop command, which then
continues with the next iteration of the loop. Catch exceptions are also
handled in a few other situations, such as the catch command and the
outermost scripts of procedure bodies.

See Also:

bgerror

Keywords:

continue, iteration, loop

----------------------------------------------------------------------------
 CRANGE                              19                       NeoSoft, Inc.

                            CRANGE - Extended TCL

  Returns a range of characters from string

Synopsis:

*  crange string firstExpr lastExpr

Description

Returns a range of characters from string starting at the character indexed
by the expression first- Expr (zero-based) until the character indexed by
the expression lastExpr.

If the expression firstExpr or lastExpr starts with the string end, then end
is replaced with the index of the last character in the string. If the
expression starts with len, then len is replaced with the length of the
string.

See Also:

bgerror

Keywords:

continue, iteration, loop

----------------------------------------------------------------------------
 CSUBSTR                             20                       NeoSoft, Inc.

                           CSUBSTR - Extended TCL

  Returns a range of characters from string for lengthExpr characters

Synopsis:

*  crange string firstExpr lengthExpr

Description

Returns a range of characters from string starting at the character indexed
by the expression first- Expr (zero-based) for lengthExpr characters.

If the expression firstExpr or lengthExpr starts with the string end, then
end is replaced with the index of the last character in the string. If the
expression starts with len, then len is replaced with the length of the
string.

See Also:

bgerror

Keywords:

continue, iteration, loop

----------------------------------------------------------------------------
 CTOKEN                              21                       NeoSoft, Inc.

                            CTOKEN - Extended TCL

  Parse a token out of a character string

Synopsis:

*  ctoken strvar separators

Description

Parse a token out of a character string. The string to parse is contained in
the variable named strvar. The string separators contains all of the valid
separator characters for tokens in the string. All leading separators are
skipped and the first token is returned. The variable strvar will be
modified to contain the remainder of the string following the token.

See Also:

bgerror

Keywords:

continue, iteration, loop

----------------------------------------------------------------------------
 CTYPE                               22                       NeoSoft, Inc.

                            CTYPE - Extended TCL

  Determines if all characters in string are of the specified class

Synopsis:

*  ctype ?-failindex var? class string

Description

ctype determines whether all characters in string are of the specified
class. It returns 1 if they are all of class, and 0 if they are not, or if
the string is empty. This command also provides another method (besides
format and scan) of con- verting between an ASCII character and its numeric
value. The following ctype commands are available:

ctype ?-failindex var? alnum string Tests that all characters are alphabetic
or numeric characters as defined by the character set.

ctype ?-failindex var? alpha string Tests that all characters are alphabetic
char- acters as defined by the character set.

ctype ?-failindex var? ascii string Tests that all characters are an ASCII
charac- ter (a non-negative number less than 0200).

ctype char number Converts the numeric value, string, to an ASCII character.
Number must be in the range 0 through 255.

ctype ?-failindex var? cntrl string Tests that all characters are "control
char- acters" as defined by the character set.

ctype ?-failindex var? digit string Tests that all characters are valid
decimal digits, i.e. 0 through 9.

ctype ?-failindex var? graph string Tests that all characters within are any
char- acter for which ctype print is true, except for space characters.

ctype ?-failindex var? lower string Tests that all characters are lowercase
let- ters as defined by the character set.

ctype ord character Convert a character into its decimal numeric value. The
first character of the string is converted.

ctype ?-failindex var? space string Tests that all characters are either a
space, horizontal-tab, carriage return, newline, ver- tical-tab, or
form-feed.

ctype ?-failindex var? print string Tests that all characters are a space or
any character for which ctype alnum or ctype punct is true or other
"printing character" as defined by the character set.

ctype ?-failindex var? punct string Tests that all characters are made up of
any of the characters other than the ones for which alnum, cntrl, or space
is true.

ctype ?-failindex var? upper string Tests that all characters are uppercase
let- ters as defined by the character set.

ctype ?-failindex var? xdigit string Tests that all characters are valid
hexadeci- mal digits, that is 0 through 9, a through f or A through F.

If -failindex is specified, then the index into string of the first
character that did not match the class is returned in var.

See Also:

bgerror

Keywords:

continue, iteration, loop

----------------------------------------------------------------------------
 DBDELKEY                            23                       NeoSoft, Inc.

                           DBDELKEY - Neowebscript

  Delete in database entry corresponding to key

Synopsis:

*  dbdelkey database key

Description

Delete in database database the entry corresponding to key. If the entry
isnt there or the datbase doesnt exist, returns 0, otherwise 1 (or an
error).

See Also:

bgerror

Keywords:

continue, iteration, loop

----------------------------------------------------------------------------
 DBEXISTS                            24                       NeoSoft, Inc.

                           DBEXISTS - Neowebscript

  Determines if database exists

Synopsis:

*  dbexists database

Description

Returns 1 if database exists, 0 otherwise.

See Also:

bgerror

Keywords:

continue, iteration, loop

----------------------------------------------------------------------------
 DBFETCH                             25                       NeoSoft, Inc.

                           DBFETCH - Neowebscript

  Fetch from database into the array specified

Synopsis:

*  dbfetch database key arrayName -singleVar

Description

Fetch from database database into the array specified by arrayName the
key-value pairs for the specified key, previously stored by dbstore (This
was formerly called props_to_array.)

If -singleVar is specified, then arrayName will be treated as the name of a
variable to store the results of the lookup. This should be used with
dbstore, when -singleVar is used.

See Also:

bgerror

Keywords:

continue, iteration, loop

----------------------------------------------------------------------------
 DBFILES                             26                       NeoSoft, Inc.

                           DBFILES - Neowebscript

  Returns a list of databases

Synopsis:

*  dbfiles

Description

Returns a list of the databases in the webpage owners database directory.

See Also:

bgerror

Keywords:

continue, iteration, loop

----------------------------------------------------------------------------
 DBKEYS                              27                       NeoSoft, Inc.

                            DBKEYS - Neowebscript

  Return a list of all of the keys in the specified database matching pattern

Synopsis:

*  dbkeys database pattern

Description

Return a list of all of the keys in the database database matching pattern.
Pattern is in the style of a Unix wildcard. In other words, if you were
looking for a key starting with horace, the pattern would be horace*. To
match horace anywhere in the string, *horace*.

See Also:

bgerror

Keywords:

continue, iteration, loop

----------------------------------------------------------------------------
 DBSTORE                             28                       NeoSoft, Inc.

                           DBSTORE - Neowebscript

  Store the contents of the specified array into a database

Synopsis:

*  dbstore database key arrayName ?-singleVar?

Description

Store the contents of the array specified by arrayName into the database
database, indexed by key, as key-value pairs. (This was formerly called
array_to_props.)

If -singleVar is specified, then arrayName will be treated as a single
value, and that value will be stored under the key given.

See Also:

bgerror

Keywords:

continue, iteration, loop

----------------------------------------------------------------------------
 DELETE_DATA_FILE                    29                       NeoSoft, Inc.

                       DELETE_DATA_FILE - Neowebscript

  Deletes a datafile

Synopsis:

*  delete_data_file datafile

Description

delete_data_file deletes a datafile. It is not an error to delete a datafile
that is not there.

See Also:

bgerror

Keywords:

continue, iteration, loop

----------------------------------------------------------------------------
 DIRECTORY_LISTING                   30                       NeoSoft, Inc.

                      DIRECTORY_LISTING - Neowebscript

  Displays disk usage for the current directory

Synopsis:

*  directory_listing

Description

Displays disk usage for the current directory. Also shows K-bytes used from
the current directory on down.

See Also:

bgerror

Keywords:

continue, iteration, loop

----------------------------------------------------------------------------
 DUMP_ENVIRONMENT                    31                       NeoSoft, Inc.

                       DUMP_ENVIRONMENT - Neowebscript

  Write all of servers environment vars and values

Synopsis:

*  dump_environment

Description

Write all of the servers environment vars and values into webpage.

See Also:

bgerror

Keywords:

continue, iteration, loop

----------------------------------------------------------------------------
 EMIT_STANDARD_
 MAGELLAN_SEARCH_LINK                32                       NeoSoft, Inc.

                               EMIT_STANDARD_
                     MAGELLAN_SEARCH_LINK - NeoWebScript

  Emits a Magellan link.

Synopsis:

* emit_standard_magellan_search_link

Description

Emit a Magellan link with at-link searching.

See Also:

bgerror

Keywords:

continue, iteration, loop

----------------------------------------------------------------------------
 EMIT_STANDARD_
 YAHOO_LINK                          33                       NeoSoft, Inc.

                               EMIT_STANDARD_
                          YAHOO_LINK - NeoWebScript

  Emits a standard Yahoo link.

Synopsis:

* emit_standard_yahoo_link

Description

Emit a link back to Yahoo in the manner that they ask.

See Also:

bgerror

Keywords:

continue, iteration, loop

----------------------------------------------------------------------------
 EOF                                 34                       NeoSoft, Inc.

                               EOF - Safe TCL

  Check for end of file condition on channel

Synopsis:

* eof channelID

Description

Returns 1 if an end of file condition occurred during the most recent input
operation on channelId (such as gets), 0 otherwise.

See Also:

bgerror

Keywords:

channel, end of file

----------------------------------------------------------------------------
 ERROR                               35                       NeoSoft, Inc.

                              ERROR - Safe TCL

  Generate an error

Synopsis:

* error message ?info? ?code?

Description

Returns a TCL_ERROR code, which causes command interpretation to be unwound.
Message is a string that is returned to the application to indicate what
went wrong.

If the info argument is provided and is non-empty, it is used to initialize
the global variable errorInfo. errorInfo is used to accumulate a stack trace
of what was in progress when an error occurred; as nested commands unwind,
the Tcl interpreter adds information to errorInfo. If the info argument is
present, it is used to initialize errorInfo and the first increment of
unwind information will not be added by the Tcl interpreter. In other words,
the command containing the error command will not appear in errorInfo; in
its place will be info. This feature is most useful in conjunction with the
catch command: if a caught error cannot be handled successfully, info can be
used to return a stack trace reflecting the original point of occurrence of
the error:
catch {...} errMsg
set savedInfo $errorInfo
...
error $errMsg $savedInfo

If the code argument is present, then its value is stored in the errorCode
global variable. This variable is intended to hold a machine-readable
description of the error in cases where such information is available; see
the tclvars manual page for information on the proper format for the
variable. If the code argument is not present, then errorCode is
automatically reset to "NONE" by the Tcl interpreter as part of processing
the error generated by the command.

See Also:

bgerror

Keywords:

error, errorCode, errorInfo

----------------------------------------------------------------------------
 ESTIMATE_HITS_PER_HOUR              36                       NeoSoft, Inc.

                    ESTIMATE_HITS_PER_HOUR - Neowebscript

  Return an estimate of the number of hits to be served on the next hour

Synopsis:

*  estimate_hits_per_hour

Description

Return a numeric estimate of the number of hits that will be served in the
next hour. Works by seeking back approximately 1000 hits into the log file
and sees how long ago it was, to extrapolate hits-per-hour. If there are
fewer than 1000 hits in the access log file, it will return 0.

See Also:

bgerror

Keywords:

error, errorCode, errorInfo

----------------------------------------------------------------------------
 EVAL                                37                       NeoSoft, Inc.

                               EVAL - Safe TCL

  Evaluate a Tcl script

Synopsis:

* eval arg ?arg ...?

Description

Eval takes one or more arguments, which together comprise a Tcl script
containing one or more commands. Eval concatenates all its arguments in the
same fashion as the concat command, passes the concatenated string to the
Tcl interpreter recursively, and returns the result of that evaluation (or
any error generated by it).

See Also:

bgerror

Keywords:

concatenate, evaluate, script

----------------------------------------------------------------------------
 EXPR                                38                       NeoSoft, Inc.

                               EXPR - Safe TCL

  Evaluate an expression

Synopsis:

* expr arg ?arg arg ...?

Description

Concatenates args (adding separator spaces between them), evaluates the
result as a Tcl expression, and returns the value. The operators permitted
in Tcl expressions are a subset of the operators permitted in C expressions,
and they have the same meaning and precedence as the corresponding C
operators. Expressions almost always yield numeric results (integer or
floating-point values). For example, the expression
expr 8.2 + 6
evaluates to 14.2. Tcl expressions differ from C expressions in the way that
operands are specified. Also, Tcl expressions support non-numeric operands
and string comparisons.

OPERANDS

A Tcl expression consists of a combination of operands, operators, and
parentheses. White space may be used between the operands and operators and
parentheses; it is ignored by the expression processor. Where possible,
operands are interpreted as integer values. Integer values may be specified
in decimal (the normal case), in octal (if the first character of the
operand is 0), or in hexadecimal (if the first two characters of the operand
are 0x). If an operand does not have one of the integer formats given above,
then it is treated as a floatingpoint number if that is possible.
Floating-point numbers may be specified in any of the ways accepted by an
ANSIcompliant C compiler (except that the "f", "F", "l", and "L" suffixes
will not be permitted in most installations). For example, all of the
following are valid floating-point numbers: 2.1, 3., 6e4, 7.91e+16. If no
numeric interpretation is possible, then an operand is left as a string (and
only a limited set of operators may be applied to it).

Operands may be specified in any of the following ways:

[1]
     As an numeric value, either integer or floatingpoint.

[2]
     As a Tcl variable, using standard $ notation. The variables value will
     be used as the operand.

[3]
     As a string enclosed in double-quotes. The expression parser will
     perform backslash, variable, and command substitutions on the
     information between the quotes, and use the resulting value as the
     operand

[4]
     As a string enclosed in braces. The characters between the open brace
     and matching close brace will be used as the operand without any
     substitutions.

[5]
     As a Tcl command enclosed in brackets. The command will be executed and
     its result will be used as the operand.

[6]
     As a mathematical function whose arguments have any of the above forms
     for operands, such as "sin($x)". See below for a list of defined
     functions.

Where substitutions occur above (e.g. inside quoted strings), they are
performed by the expression processor. However, an additional layer of
substitution may already have been performed by the command parser before
the expression processor was called. As discussed below, it is usually best
to enclose expressions in braces to prevent the command parser from
performing substitutions on the contents.

For some examples of simple expressions, suppose the variable a has the
value 3 and the variable b has the value 6. Then the command on the left
side of each of the lines below will produce the value on the right side of
the line:

expr 3.1 + $a
     6.1

expr 2 + "$a.$b"
     5.6 expr 4*[llength "6 2"] 8 expr {{word one} < "word $a"}0

OPERATORS

The valid operators are listed below, grouped in decreasing order of
precedence:

-
     + ~ ! Unary minus, unary plus, bit-wise NOT, logical NOT. None of these
     operands may be applied to string operands, and bit-wise NOT may be
     applied only to integers.

* / % Multiply, divide, remainder. None of these operands may be applied to
string operands, and remainder may be applied only to integers. The
remainder will always have the same sign as the divisor and an absolute
value smaller than the divisor.

+ - Add and subtract. Valid for any numeric operands.

<< >> Left and right shift. Valid for integer operands only. A right shift
always propogates the sign bit.

< > <= >= Boolean less, greater, less than or equal, and greater than or
equal. Each operator produces 1 if the condition is true, 0 otherwise. These
operators may be applied to strings as well as numeric operands, in which
case string comparison is used.

== != Boolean equal and not equal. Each operator produces a zero/one result.
Valid for all operand types.

&
     Bit-wise AND. Valid for integer operands only.

^
     Bit-wise exclusive OR. Valid for integer operands only.

|
     Bit-wise OR. Valid for integer operands only.

&&
     Logical AND. Produces a 1 result if both operands are non-zero, 0
     otherwise. Valid for numeric operands only (integers or
     floating-point).

||
     Logical OR. Produces a 0 result if both operands are zero, 1 otherwise.
     Valid for numeric operands only (integers or floating-point).

x?y:z
     If-then-else, as in C. If x evaluates to non-zero, then the result is
     the value of y. Otherwise the result is the value of z. The x operand
     must have a numeric value.

See the C manual for more details on the results produced by each operator.
All of the binary operators group leftto-right within the same precedence
level. For example, the command
expr 4*2 < 7
returns 0.

The &&, ||, and ?: operators have "lazy evaluation", just as in C, which
means that operands are not evaluated if they are not needed to determine
the outcome. For example, in the command
expr {$v ? [a] : [b]}
only one of [a] or [b] will actually be evaluated, depending on the value of
$v. Note, however, that this is only true if the entire expression is
enclosed in braces; otherwise the Tcl parser will evaluate both [a] and [b]
before invoking the expr command.

MATH FUNCTIONS

Tcl supports the following mathematical functions in expressions:

acos cos hypot sinh asin cosh log sqrt atan exp log10 tan atan2 floor pow
tanh ceil fmod sin

Each of these functions invokes the math library function of the same name;
see the manual entries for the library functions for details on what they
do. Tcl also implements the following functions for conversion between
integers and floating-point numbers:

abs(arg)
Returns the absolute value of arg. Arg may be either integer or
floating-point, and the result is returned in the same form.

double(arg)
If arg is a floating value, returns arg, otherwise converts arg to floating
and returns the converted value.

int(arg)
If arg is an integer value, returns arg, otherwise converts arg to integer
by truncation and returns the converted value.

round(arg)
If arg is an integer value, returns arg, otherwise converts arg to integer
by rounding and returns the converted value.

In addition to these predefined functions, applications may define
additional functions using Tcl_CreateMathFunc().

TYPES, OVERFLOW, AND PRECISION

All internal computations involving integers are done with the C type long,
and all internal computations involving floating-point are done with the C
type double. When converting a string to floating-point, exponent overflow
is detected and results in a Tcl error. For conversion to integer from
string, detection of overflow depends on the behavior of some routines in
the local C library, so it should be regarded as unreliable. In any case,
integer overflow and underflow are generally not detected reliably for
intermediate results. Floating-point overflow and underflow are detected to
the degree supported by the hardware, which is generally pretty reliable.

Conversion among internal representations for integer, floating-point, and
string operands is done automatically as needed. For arithmetic
computations, integers are used until some floating-point number is
introduced, after which floating-point is used. For example, expr 5 / 4
returns 1, while
expr 5 / 4.0
expr 5 / ( [string length "abcd"] + 0.0 ) both return 1.25. Floating-point
values are always returned with a "." or an "e" so that they will not look
like integer values. For example, expr 20.0/5.0
returns "4.0", not "4". The global variable tcl_precision determines the the
number of significant digits that are retained when floating values are
converted to strings (except that trailing zeroes are omitted). If
tcl_precision is unset then 6 digits of precision are used. To retain all of
the significant bits of an IEEE floating-point number set tcl_precision to
17; if a value is converted to string with 17 digits of precision and then
converted back to binary for some later calculation, the resulting binary
value is guaranteed to be identical to the original one.

STRING OPERATIONS

String values may be used as operands of the comparison operators, although
the expression evaluator tries to do comparisons as integer or
floating-point when it can. If one of the operands of a comparison is a
string and the other has a numeric value, the numeric operand is converted
back to a string using the C sprintf format specifier %d for integers and %g
for floating-point values. For example, the commands
expr {"0x03" > "2"}
expr {"0y" < "0x12"}
both return 1. The first comparison is done using integer comparison, and
the second is done using string comparison after the second operand is
converted to the string "18". Because of Tcls tendency to treat values as
numbers whenever possible, it isnt generally a good idea to use operators
like == when you really want string comparison and the values of the
operands could be arbi

trary;
     its better in these cases to use the string compare command instead.

See Also:

bgerror

Keywords:

arithmetic, boolean, compare, expression

----------------------------------------------------------------------------
 FCONFIGURE                          39                       NeoSoft, Inc.

                            FCONFIGURE - Safe TCL

  Set and get options on a channel

Synopsis:

* fconfigure channelId

* fconfigure channelId name

* fconfigure channelId name value ?name value ...?

Description

The fconfigure command sets and retrieves options for channels. ChannelId
identifies the channel for which to set or query an option. If no name or
value arguments are supplied, the command returns a list containing
alternating option names and values for the channel. If name is supplied but
no value then the command returns the current value of the given option. If
one or more pairs of name and value are supplied, the command sets each of
the named options to the corresponding value; in this case the return value
is an empty string.

The options described below are supported for all channels. In addition,
each channel type may add options that only it supports.

-blocking boolean
     The -blocking option determines whether I/O operations on the channel
     can cause the process to block indefinitely. The value of the option
     must be a proper boolean value. Channels are normally in blocking mode;
     if a channel is placed into nonblocking mode it will affect the
     operation of the gets, read, puts, flush, and close commands; see the
     documentation for those commands for details. Setting stdin, stdout, or
     stderr into nonblocking mode is disallowed because it could interfere
     with the operation of the parent process. For nonblocking mode to work
     correctly, the application must be using the Tcl event loop (e.g. by
     calling Tcl_DoOneEvent or invoking the vwait command).

-buffering newValue
     If newValue is full then the I/O system will buffer output until its
     internal buffer is full or until the flush command is invoked. If
     newValue is line, then the I/O system will automatically flush output
     for the channel whenever a newline character is output. If newValue is
     none, the I/O system will flush automatically after every output
     operation. The default is for -buffering to be set to full except for
     channels that connect to terminal-like devices; for these channels the
     initial setting is line.

-buffersize newSize
     Newvalue must be an integer; its value is used to set the size of
     buffers, in bytes, subsequently allocated for this channel to store
     input or output. Newvalue must be between ten and one million, allowing
     buffers of ten to one million bytes in size.

-translation mode
     In Tcl scripts the end of a line is always represented using a single
     newline character (\n). However, in actual files and devices the end of
     a line may be represented differently on different platforms, or even
     for different devices on the same platform. For example, under UNIX
     newlines are used in files, whereas carriage-return-linefeed sequences
     are normally used in network connections. The Tcl I/O system
     automatically translates between the newlines used internally and
     whatever end-ofline characters are appropriate for the underlying files
     and devices. The -translation option selects the end-of-line
     character(s) to use on the file or device for a particular channel.
     Note that if you want no translations at all applied to input and
     output on a specific channel, you should set it to lf mode - see below.
     The following values are currently supported:

cr
     The end of a line in the underlying file or device is represented by a
     single carriage return character. During input commands such as read
     Tcl translates carriage returns to newline characters, and during
     output commands such as puts Tcl translates newline characters to
     carriage returns. This mode is typically used on Macintosh platforms.

crlf The end of a line in the underlying file or device is represented by a
carriage return character followed by a linefeed character. During input
commands such as read Tcl

translates
     carriage-return-linefeed sequences to newlines, and during output
     commands such as puts Tcl translates newline characters to
     carriage-return-linefeed sequences. This mode is typically used on
     Windows platforms and for network connections.

lf
     The end of a line in the underlying file or device is represented by a
     single newline (linefeed) character. In this mode no translations occur
     during either intput or output. This mode is typically used on UNIX
     platforms.

binary This is a synonym for lf mode.

platform

nel according to the platform on which the application is executing; for
sockets on all platforms Tcl chooses crlf, for all Unix flavors, it chooses
lf, for the Macintosh platform it chooses cr and for the various flavors of
Windows it chooses crlf.

auto In this mode Tcl sets the translation mode based on the first valid
end-of-line sequence it sees during input on the channel. If output is
generated for the channel before an end-of-line sequence has appeared on
input, then Tcl uses platform mode for the channel. The default setting for
-translation is auto.

See Also:

close, flush, gets, puts, read

Keywords:

blocking, buffering, carriage return, end of line, flushing, linemode,
newline, nonblocking, platform, translation

----------------------------------------------------------------------------
 FILEMV                              40                       NeoSoft, Inc.

                            FILEMV - Neowebscript

  Renames the file type

Synopsis:

*  filemv type oldname newname

Description

Renames the file type type from oldname to newname. Valid types are db and
data.

See Also:

close, flush, gets, puts, read

Keywords:

blocking, buffering, carriage return, end of line, flushing, linemode,
newline, nonblocking, platform, translation

----------------------------------------------------------------------------
 FILERM                              41                       NeoSoft, Inc.

                            FILERM - Neowebscript

  Removes the data or db file of type

Synopsis:

*  filerm type name

Description

Removes the data or db file of the given type. Valid types are db and data.

See Also:

close, flush, gets, puts, read

Keywords:

blocking, buffering, carriage return, end of line, flushing, linemode,
newline, nonblocking, platform, translation

----------------------------------------------------------------------------
 FLOCK                               42                       NeoSoft, Inc.

                            FLOCK - Extended TCL

  Places a lock on all or part of fole specified by fileId

Synopsis:

*  flock options fileId ?start? ?length? ?origin?

Description

This command places a lock on all or part of the file specified by fileId.
The lock is either advi- sory or mandatory, depending on the mode bits of
the file. The lock is placed beginning at relative byte offset start for
length bytes. If start or length is omitted or empty, zero is assumed. If
length is zero, then the lock always extents to end of file, even if the
file grows. If origin is "start", then the offset is relative to the begin-
ning of the file. If it is "current", it is rela- tive to the current access
position in the file. If it is "end", then it is relative to the end-of-
file (a negative is before the EOF, positive is after). If origin is
omitted, start is assumed.

The following options are recognized:

-read - Place a read lock on the file. Multiple processes may be accessing
the file with read- locks.

-write - Place a write lock on the file. Only one process may be accessing a
file if there is a write lock.

-nowait - If specified, then the process will not block if the lock can not
be obtained. With this option, the command returns 1 if the lock is obtained
and 0 if it is not.

See your systems fcntl system call documentation for full details of the
behavior of file locking. If locking is being done on ranges of a file, it
is best to use unbuffered file access (see the fcntl command).

See Also:

close, flush, gets, puts, read

Keywords:

blocking, buffering, carriage return, end of line, flushing, linemode,
newline, nonblocking, platform, translation

----------------------------------------------------------------------------
 FLUSH                               43                       NeoSoft, Inc.

                              FLUSH - Safe TCL

  Flush buffered output for a channel

Synopsis:

* flush channelId

Description

Flushes any output that has been buffered for channelId. ChannelId must be a
channel identifier such as returned by a previous open or socket command,
and it must have been opened for writing. If the channel is in blocking mode
the command does not return until all the buffered output has been flushed
to the channel. If the channel is in nonblocking mode, the command may
return before all buffered output has been flushed; the remainder will be
flushed in the background as fast as the underlying file or device is able
to absorb it.

See Also:

open, socket

Keywords:

blocking, buffer, channel, flush, nonblocking, output

----------------------------------------------------------------------------
 FOR                                 44                       NeoSoft, Inc.

                               FOR - Safe TCL

  For loop

Synopsis:

* for start test next body

Description

For is a looping command, similar in structure to the C for statement. The
start, next, and body arguments must be Tcl command strings, and test is an
expression string. The for command first invokes the Tcl interpreter to
execute start. Then it repeatedly evaluates test as an expression; if the
result is non-zero it invokes the Tcl interpreter on body, then invokes the
Tcl interpreter on next, then repeats the loop. The command terminates when
test evaluates to 0. If a continue command is invoked within body then any
remaining commands in the current execution of body are skipped; processing
continues by invoking the Tcl interpreter on next, then evaluating test, and
so on. If a break command is invoked within body or next, then the for
command will return immediately. The operation of break and continue are
similar to the corresponding statements in C. For returns an empty string.

See Also:

open, socket

Keywords:

for, iteration, looping

----------------------------------------------------------------------------
 FOREACH                             45                       NeoSoft, Inc.

                             FOREACH - Safe TCL

  Iterate over all elements in one or more lists

Synopsis:

* foreach varname list body
* foreach varlist1 list1 varlist2 list2...? body

Description

The foreach command implements a loop where the loop variable(s) take on
values from one or more lists. In the simplest case there is one loop
variable, varname, and one list, list, that is a list of values to assign to
varname. The body argument is a Tcl script. For each element of list (in
order from first to last), foreach assigns the contents of the element to
varname as if the lindex command had been used to extract the element, then
calls the Tcl interpreter to execute body.

In the general case there can be more than one value list (e.g., list1 and
list2), and each value list can be associated with a list of loop variables
(e.g., varlist1 and varlist2). During each iteration of the loop the
variables of each varlist are assigned consecutive values from the
corresponding list. Values in each list are used in order from first to
last, and each value is used exactly once. The total number of loop
iterations is large enough to use up all the values from all the value
lists. If a value list does not contain enough elements for each of its loop
variables in each iteration, empty values are used for the missing elements.

The break and continue statements may be invoked inside body, with the same
effect as in the for command. Foreach returns an empty string.

EXAMPLES

The following loop uses i and j as loop variables to iterate over pairs of
elements of a single list.

set x {}
foreach {i j} {a b c d e f} { lappend x $j $i
}
# The value of x is "b a d c f e" # There are 3 iterations of the loop.

The next loop uses i and j to iterate over two lists in parallel.

set x {}
foreach i {a b c} j {d e f g} { lappend x $i $j
}
# The value of x is "a d b e c f {} g" # There are 4 iterations of the loop.

The two forms are combined in the following example.

set x {}
foreach i {a b c} {j k} {d e f g} { lappend x $i $j $k
}
# The value of x is "a d e b f g c {} {}" # There are 3 iterations of the
loop.

See Also:

open, socket

Keywords:

foreach, iteration, list, looping

----------------------------------------------------------------------------
 FORMAT                              46                       NeoSoft, Inc.

                              FORMAT - Safe TCL

  Format a string in the style of sprintf

Synopsis:

* format formatString ?arg arg ...?

Description

This command generates a formatted string in the same way as the ANSI C
sprintf procedure (it uses sprintf in its implementation). FormatString
indicates how to format the result, using % conversion specifiers as in
sprintf, and the additional arguments, if any, provide values to be
substituted into the result. The return value from format is the formatted
string.

DETAILS ON FORMATTING

The command operates by scanning formatString from left to right. Each
character from the format string is appended to the result string unless it
is a percent sign. If the character is a % then it is not copied to the
result string. Instead, the characters following the % character are treated
as a conversion specifier. The conversion specifier controls the conversion
of the next successive arg to a particular format and the result is appended
to the result string in place of the conversion specifier. If there are
multiple conversion specifiers in the format string, then each one controls
the conversion of one additional arg. The format command must be given
enough args to meet the needs of all of the conversion specifiers in
formatString.

Each conversion specifier may contain up to six different parts: an XPG3
position specifier, a set of flags, a minimum field width, a precision, a
length modifier, and a conversion character. Any of these fields may be
omitted except for the conversion character. The fields that are present
must appear in the order given above. The paragraphs below discuss each of
these fields in turn.

If the % is followed by a decimal number and a $, as in "%2$d", then the
value to convert is not taken from the next sequential argument. Instead, it
is taken from the argument indicated by the number, where 1 corresponds to
the first arg. If the conversion specifier requires multiple arguments
because of * characters in the specifier then successive arguments are used,
starting with the argument given by the number. This follows the XPG3
conventions for positional specifiers. If there are any positional
specifiers in formatString then all of the specifiers must be positional.

The second portion of a conversion specifier may contain any of the
following flag characters, in any order:

-
     Specifies that the converted argument should be left-justified in its
     field (numbers are normally right-justified with leading spaces if
     needed).

+
     Specifies that a number should always be printed with a sign, even if
     positive.

space
     Specifies that a space should be added to the beginning of the number
     if the first character isnt a sign.

0
     Specifies that the number should be padded on the left with zeroes
     instead of spaces.

#
     Requests an alternate output form. For o and O conversions it
     guarantees that the first digit is always 0. For x or X conversions, 0x
     or 0X (respectively) will be added to the beginning of the result
     unless it is zero. For all floatingpoint conversions (e, E, f, g, and
     G) it guarantees that the result always has a decimal point. For g and
     G conversions it specifies that trailing zeroes should not be removed.

The third portion of a conversion specifier is a number giving a minimum
field width for this conversion. It is typically used to make columns line
up in tabular printouts. If the converted argument contains fewer characters
than the minimum field width then it will be padded so that it is as wide as
the minimum field width. Padding normally occurs by adding extra spaces on
the left of the converted argument, but the 0 and - flags may be used to
specify padding with zeroes on the left or with spaces on the right,
respectively. If the minimum field width is specified as * rather than a
number, then the next argument to the format command determines the minimum
field width; it must be a numeric string.

The fourth portion of a conversion specifier is a precision, which consists
of a period followed by a number. The number is used in different ways for
different conversions. For e, E, and f conversions it specifies the number
of digits to appear to the right of the decimal point. For g and G
conversions it specifies the total number of digits to appear, including
those on both sides of the decimal point (however, trailing zeroes after the
decimal point will still be omitted unless the # flag has been specified).
For integer conversions, it specifies a minimum number of digits to print
(leading zeroes will be added if necessary). For s conversions it specifies
the maximum number of characters to be printed; if the string is longer than
this then the trailing characters will be dropped. If the precision is
specified with * rather than a number then the next argument to the format
command determines the precision; it must be a numeric string.

The fifth part of a conversion specifier is a length modifier, which must be
h or l. If it is h it specifies that the numeric value should be truncated
to a 16-bit value before converting. This option is rarely useful. The l
modifier is ignored.

The last thing in a conversion specifier is an alphabetic character that
determines what kind of conversion to perform. The following conversion
characters are currently supported:

d
     Convert integer to signed decimal string.

u
     Convert integer to unsigned decimal string.

i
     Convert integer to signed decimal string; the integer may either be in
     decimal, in octal (with a leading 0) or in hexadecimal (with a leading
     0x).

o
     Convert integer to unsigned octal string.

x or X
     Convert integer to unsigned hexadecimal string, using digits
     "0123456789abcdef" for x and "0123456789ABCDEF" for X).

c
     Convert integer to the 8-bit character it represents.

s
     No conversion; just insert string.

f
     Convert floating-point number to signed decimal string of the form
     xx.yyy, where the number of ys is determined by the precision
     (default: 6). If the precision is 0 then no decimal point is output.

e or e
     Convert floating-point number to scientific notation in the form
     x.yyye+-zz, where the number of ys is determined by the precision
     (default: 6). If the precision is 0 then no decimal point is output. If
     the E form is used then E is printed instead of e.

g or G
     If the exponent is less than -4 or greater than or equal to the
     precision, then convert floating-point number as for %e or %E.
     Otherwise convert as for %f. Trailing zeroes and a trailing decimal
     point are omitted.

%
     No conversion: just insert %.

For the numerical conversions the argument being converted must be an
integer or floating-point string; format converts the argument to binary and
then converts it back to a string according to the conversion specifier.

DIFFERENCES FROM ANSI SPRINTF

The behavior of the format command is the same as the ANSI C sprintf
procedure except for the following differences:

[1]
%p and %n specifiers are not currently supported.

[2]
     For %c conversions the argument must be a decimal string, which will
     then be converted to the corresponding character value.

[3]
     The l modifier is ignored; integer values are always converted as if
     there were no modifier present and real values are always converted as
     if the l modifier were present (i.e. type double is used for the
     internal representation). If the h modifier is specified then integer
     values are truncated to short before conversion.

See Also:

open, socket

Keywords:

conversion specifier, format, sprintf, string, substitution

----------------------------------------------------------------------------
 FSTAT                               47                       NeoSoft, Inc.

                            FSTAT - Extended TCL

  Obtains status info about an open file

Synopsis:

*  fstat fileId ?item?| ?stat arrayvar?

Description

Obtain status information about an open file.

The following keys are used to identify data items:

   * atime - The time of last access.

   * ctime - The time of last file status change

   * dev - The device containing a directory for the file. This value
     uniquely identifies the file sys- tem that contains the file.

   * gid - The group ID of the files group.

   * ino - The inode number. This field uniquely identifies the file in a
     given file system.

   * mode - The mode of the file (see the mknod system call).

   * mtime - Time when the data in the file was last modified.

   * nlink - The number of links to the file.

   * size - The file size in bytes.

   * tty - If the file is associated with a terminal, then 1 otherwise 0.

   * type - The type of the file in symbolic form, which is one of the
     following values: file, direc- tory, characterSpecial, blockSpecial,
     fifo, link, or socket.

   * uid - The user ID of the files owner.

If one of these keys is specified as item, then that data item is returned.

If stat arrayvar is specified, then the information is returned in the array
arrrayvar. Each of the above keys indexes an element of the array contain-
ing the data.

If only fileId is specified, the command returns the data as a keyed list.

The following values may be returned only if explicitly asked for, it will
not be returned with the array or keyed list forms:

   * remotehost - If fileId is a TCP/IP socket connection, then a list is
     returned with the first element being the remote host IP address. If
     the remote host name can be found, it is returned as the second element
     of the list. The remote host IP port number is returned as the this
     element.

   * localhost - If fileId is a TCP/IP socket connec- tion, then a list is
     returned with the first ele- ment being the local host IP address. If
     the local host name can be found, it is returned as the sec- ond
     element of the list. The local host IP port number is returned as the
     this element.

See Also:

open, socket

Keywords:

conversion specifier, format, sprintf, string, substitution

----------------------------------------------------------------------------
 FUNLOCK                             48                       NeoSoft, Inc.

                           FUNLOCK - Extended TCL

  Remove a locked from a file that was placed with flock

Synopsis:

*  flock fileId ?start? ?length? ?origin?

Description

Remove a locked from a file that was previously placed with the flock
command. The arguments are the same as for the flock command, see that
command for more details.

See Also:

open, socket

Keywords:

conversion specifier, format, sprintf, string, substitution

----------------------------------------------------------------------------
 GET_AVG_NC                          49                       NeoSoft, Inc.

                          GET_AVG_NC - NeoWebScript

  Returns an average daily count.

Synopsis:

* get_avg_nc counter_name [browser]

Description

Returns the average daily counts assigned to the counter. The average is
calculated by dividing the real counts by the number of days since the
counter was registered. (NOTE: initial counts are not used to calculate the
average.) By default the total value for all browsers is returned. Caller
may request a specific browser (all, mozilla, mosaic, lynx, mie, other).

See Also:

open, socket

Keywords:

conversion specifier, format, sprintf, string, substitution

----------------------------------------------------------------------------
 GET_INIT_NC                         50                       NeoSoft, Inc.

                         GET_INIT_NC - NeoWebScript

  Returns the initial counter value.

Synopsis:

* get_init_nc counter_name [browser]

Description

Returns the initial counts assigned to the counter when it was registered.
By default the total value for all browsers is returned. Caller may request
a specific browser (all, mozilla, mosaic, lynx, mie, other).

See Also:

open, socket

Keywords:

conversion specifier, format, sprintf, string, substitution

----------------------------------------------------------------------------
 GET_NC                              51                       NeoSoft, Inc.

                            GET_NC - NeoWebScript

  Returns the current counter value.

Synopsis:

* get_nc counter_name [browser] [val_type]

Description

Returns the current counter value. By default the overall lifetime count is
returned. Caller may request a specific browser (all, mozilla, mosaic, lynx,
mie, other). Caller may request lifetime of todays count only using
val_type.

See Also:

open, socket

Keywords:

conversion specifier, format, sprintf, string, substitution

----------------------------------------------------------------------------
 GET_REAL_NC                         52                       NeoSoft, Inc.

                         GET_REAL_NC - NeoWebScript

  Returns an actual daily count.

Synopsis:

* get_real_nc counter_name [browser]

Description

Returns the actual counts assigned to the counter (i.e. count-init_count).
By default the total value for all browsers is returned. Caller may request
a specific browser (all, mozilla, mosaic, lynx, mie, other).

See Also:

open, socket

Keywords:

conversion specifier, format, sprintf, string, substitution

----------------------------------------------------------------------------
 GETS                                53                       NeoSoft, Inc.

                               GETS - Safe TCL

  Read a line from a channel

Synopsis:

* gets channelID ? varName?

Description

This command reads the next line from channelId, returns everything in the
line up to (but not including) the endof-line character(s), and discards the
end-of-line character(s). If varName is omitted the line is returned as the
result of the command. If varName is specified then the line is placed in
the variable by that name and the return value is a count of the number of
characters returned.

If end of file occurs while scanning for an end of line, the command returns
whatever input is available up to the end of file. If channelId is in
nonblocking mode and there is not a full line of input available, the
command returns an empty string and does not consume any input. If varName
is specified and an empty string is returned in varName because of
end-of-file or because of insufficient data in nonblocking mode, then the
return count is -1. Note that if varName is not specified then the
end-of-file and no-full-line-available cases can produce the same results as
if there were an input line consisting only of the end-of-line character(s).
The eof and fblocked commands can be used to distinguish these three cases.

See Also:

eof, fblocked

Keywords:

blocking, channel, end of file, end of line, line, nonblocking, read

----------------------------------------------------------------------------
 GLOBAL                              54                       NeoSoft, Inc.

                              GLOBAL - Safe TCL

  Access global variables

Synopsis:

* global varname ?varname ...?

Description

This command is ignored unless a Tcl procedure is being interpreted. If so
then it declares the given varnames to be global variables rather than
local ones. For the duration of the current procedure (and only while
executing in the current procedure), any reference to any of the varnames
will refer to the global variable by the same name.

See Also:

eof, fblocked

Keywords:

global, procedure, variable

----------------------------------------------------------------------------
 GM_TIMESTR_822                      55                       NeoSoft, Inc.

                        GM_TIMESTR_822 - NeoWebScript

  Returns standard unix time.

Synopsis:

* gm_timestr_822 time

Description

Returns an RFC822 string representing of time which is in standard Unix
time, ie. seconds from the start of the epoch, ie. Jan 1, 1970. Currently
used only to generate the Expires header for server-cached images.

See Also:

eof, fblocked

Keywords:

global, procedure, variable

----------------------------------------------------------------------------
 HISTORY                             56                       NeoSoft, Inc.

                             HISTORY - Safe TCL

  Manipulate the history list

Synopsis:

* history ?option? ?arg arg ...?

Description

The history command performs one of several operations related to
recently-executed commands recorded in a history list. Each of these
recorded commands is referred to as an "event". When specifying an event to
the history command, the following forms may be used:

[1]
     A number: if positive, it refers to the event with that number (all
     events are numbered starting at 1). If the number is negative, it
     selects an event relative to the current event (-1 refers to the
     previous event, -2 to the one before that, and so on).

[2]
     A string: selects the most recent event that matches the string. An
     event is considered to match the string either if the string is the
     same as the first characters of the event, or if the string matches the
     event in the sense of the string match command.

The history command can take any of the following forms:

history
Same as history info, described below.

history add command ?exec?
Adds the command argument to the history list as a new event. If exec is
specified (or abbreviated) then the command is also executed and its result
is returned. If exec isnt specified then an empty string is returned as
result.

history change newValue ?event?
Replaces the value recorded for an event with newValue. Event specifies the
event to replace, and defaults to the current event (not event -1). This
command is intended for use in commands that implement new forms of history
substitution and wish to replace the current event (which invokes the
substitution) with the command created through substitution. The return
value is an empty string.

history event ?event?
Returns the value of the event given by event. Event defaults to -1. This
command causes history revision to occur: see below for details.

history info ?count?
Returns a formatted string (intended for humans to read) giving the event
number and contents for each of the events in the history list except the
current event. If count is specified then only the most recent count events
are returned.

history keep count
This command may be used to change the size of the history list to count
events. Initially, 20 events are retained in the history list. This command
returns an empty string.

history nextid
Returns the number of the next event to be recorded in the history list. It
is useful for things like printing the event number in command-line prompts.

history redo ?event?
Re-executes the command indicated by event and return its result. Event
defaults to -1. This command results in history revision: see below for
details.

history substitute old new ?event?
Retrieves the command given by event (-1 by default), replace any
occurrences of old by new in the command (only simple character equality is
supported; no wild cards), execute the resulting command, and return the
result of that execution. This command results in history revision: see
below for details.

history words selector ?event?
Retrieves from the command given by event (-1 by default) the words given by
selector, and return those words in a string separated by spaces. The
selector argument has three forms. If it is a single number then it selects
the word given by that number (0 for the command name, 1 for its first
argument, and so on). If it consists of two numbers separated by a dash,
then it selects all the arguments between those two. Otherwise selector is
treated as a pattern; all words matching that pattern (in the sense of
string match) are returned. In the numeric forms $ may be used to select the
last word of a command. For example, suppose the most recent command in the
history list is format {%s is %d years old} Alice [expr $ageInMonths/12]

Below are some history commands and the results they would produce:

Command
     Result

history words $ [expr $ageInMonths/12] history words 1-2{%s is %d years old}
Alice history words *a*o*{%s is %d years old} [expr $ageInMonths/12]

History words results in history revision: see below for details.

HISTORY REVISION

The history options event, redo, substitute, and words result in "history
revision". When one of these options is invoked then the current event is
modified to eliminate the history command and replace it with the result of
the history command. For example, suppose that the most recent command in
the history list is set a [expr $b+2]
and suppose that the next command invoked is one of the ones on the left
side of the table below. The command actually recorded in the history event
will be the corresponding one on the right side of the table.

Command_Typed Command_Recorded

history redo
     set a [expr $b+2]

history s a b
     set b [expr $b+2] set c [history w 2]set c [expr $b+2]

History revision is needed because event specifiers like -1 are only valid
at a particular time: once more events have been added to the history list a
different event specifier would be needed. History revision occurs even when
history is invoked indirectly from the current event (e.g. a user types a
command that invokes a Tcl procedure that invokes history): the top-level
command whose execution eventually resulted in a history command is
replaced. If you wish to invoke commands like history words without history
revision, you can use history event to save the current history event and
then use history change to restore it later.

See Also:

eof, fblocked

Keywords:

event, history, record, revision

----------------------------------------------------------------------------
 HTML                                57                       NeoSoft, Inc.

                             HTML - Neowebscript

  Write string into the webpage

Synopsis:

*  html string [tag]

Description

write string into the webpage being sent to the user. If tag is specified,
it is emitted in its on-state in front, and its off state behind of, the
string.

See Also:

eof, fblocked

Keywords:

event, history, record, revision

----------------------------------------------------------------------------
 ID                                  58                       NeoSoft, Inc.

                              ID - Extended TCL

  Provides a means of getting, setting, and converting user, group, and
process ids

Synopsis:

*  id options

Description

This command provides a means of getting, setting and converting user, group
and process ids. The id command has the following options:

id user ?name?

id userid ?uid? Set the real and effective user ID to name or uid, if the
name (or uid) is valid and permis- sions allow it. If the name (or uid) is
not specified, the current name (or uid) is returned.

id convert userid uid

id convert user name Convert a user ID number to a user name, or vice versa.

id group ?name?

id groupid ?gid? Set the real and effective group ID to name or gid, if the
name (or gid) is valid and permis- sions allow it. If the group name (or
gid) is not specified, the current group name (or gid) is returned.

id groups

id groupids Return the current group access list of the process. The option
groups returns group names and groupids returns id numbers.

id convert groupid gid

id convert group name Convert a group ID number to a group name, or vice
versa.

id effective user

id effective userid Return the effective user name, or effective user ID
number, respectively.

id effective group

id effective groupid Return the effective group name, or effective group ID
number, respectively. id effective groupids Return all of the groupids the
user is a mem- ber of.

id host Return the hostname of the system the program is running on.

id process Return the process ID of the current process.

id process parent Return the process ID of the parent of the current
process.

id process group Return the process group ID of the current process.

id process group set Set the process group ID of the current pro- cess to
its process ID.

id host Returns the standard host name of the machine the process is
executing on.

See Also:

eof, fblocked

Keywords:

event, history, record, revision

----------------------------------------------------------------------------
 IF                                  59                       NeoSoft, Inc.

                                IF - Safe TCL

  Execute scripts conditionally

Synopsis:

* if expr1 ?then? body1 elseif
expr2 ?then? body2 elseif ... ?else?
?bodyN?

Description

The if command evaluates expr1 as an expression (in the same way that expr
evaluates its argument). The value of the expression must be a boolean (a
numeric value, where 0 is false and anything is true, or a string value such
as true or yes for true and false or no for false); if it is true then body1
is executed by passing it to the Tcl interpreter. Otherwise expr2 is
evaluated as an expression and if it is true then body2 is executed, and so
on. If none of the expressions evaluates to true then bodyN is executed. The
then and else arguments are optional "noise words" to make the command
easier to read. There may be any number of elseif clauses, including zero.
BodyN may also be omitted as long as else is omitted too. The return value
from the command is the result of the body script that was executed, or an
empty string if none of the expressions was non-zero and there was no bodyN.

See Also:

eof, fblocked

Keywords:

boolean, conditional, else, false, if, true

----------------------------------------------------------------------------
 IMAGE_CREATE                        60                       NeoSoft, Inc.

                         IMAGE_CREATE - NeoWebScript

  Returns a file handle which writes to the cache for the given name

Synopsis:

*   image_create  name ?expire-seconds?

Description

NOTE: Image generation is experimental in the current release of
NeoWebScript.

Returns a file handle which writes to the cache for the given name. Name
must be a file name relative to the current directory. The user should close
the file when finished with it using the \"close\" command. The old image,
if any, is already destroyed when this call returns.

Expire-seconds defines the number of seconds the image may be delivered from
the server cache before it becomes invalid.

For further info, see the Gd command set

See Also:

eof, fblocked

Keywords:

boolean, conditional, else, false, if, true

----------------------------------------------------------------------------
 IMAGE_EXPIRE                        61                       NeoSoft, Inc.

                         IMAGE_EXPIRE - NeoWebScript

  Allows server caching of current image

Synopsis:

*  image_expire seconds

Description

NOTE: Image generation is experimental in the current release of
NeoWebScript.

Turns on server-side caching for the current image being generated, and sets
an expiration time on the cache to seconds. (0 is a valid value for seconds,
and will cause it to always be expired.) Cached files are served out obeying
the \"If-modified-since\" header, allowing for client-side caching as well.

For further info, see the Gd command set

See Also:

eof, fblocked

Keywords:

boolean, conditional, else, false, if, true

----------------------------------------------------------------------------
 IMAGE_OPEN                          62                       NeoSoft, Inc.

                          IMAGE_OPEN - NeoWebScript

  Returns a file handle for image name

Synopsis:

*   image_open  name

Description

NOTE: Image generation is experimental in the current release of
NeoWebScript.

Return a file handle for image name. Name refers to a file in the current
directory, including the extension (usually .gd). Makes it possible to
access previously generated images. If name is empty, then a handle to the
previsouly cached image for the current URI is returned. The user should
close the file when finished with it using the \"close\" command. The
implementation takes special care not to destroy the old copy of the current
image until the current image has been generated.

For further info, see the Gd command set

See Also:

eof, fblocked

Keywords:

boolean, conditional, else, false, if, true

----------------------------------------------------------------------------
 IMPORT_KEYVALUE_PAIRS               63                       NeoSoft, Inc.

                    IMPORT_KEYVALUE_PAIRS - NeoWebScript

  Loads key-value pairs from a string into an array.

Synopsis:

* import_keyvalue_pairs arrayName string

Description

load the key-value pairs from string into array arrayName, as -element
string.

Example: import_keyvalue_pairs foo "-action paint -customer fred"

Will set element action of array foo to paint and element customer to fred.

The normal usage would be to get optional key-value pairs as arguments to a
proc, as in:

proc sell_item {customer item args} {
import_keyvalue_pairs options $args
.
.
}

This will pull an arbitrary number of optional key-value pairs, read into
the args list when the proc began execution (because of the special meaning
Tcl attaches to this keyword in argument lists), and store the key-value
pairs into the options array.

See Also:

eof, fblocked

Keywords:

boolean, conditional, else, false, if, true

----------------------------------------------------------------------------
 INCLUDE_FILE                        64                       NeoSoft, Inc.

                         INCLUDE_FILE - NeoWebScript

  Copies the contents of a local file onto the page.

Synopsis:

* include_file fileName

Description

Copy the contents of the specified file into the webpage being generated.
File must be in the same directory or somewhere beneath the current
directory. If the filename matches the MIME type for a server side include,
the server side include is still performed. If it also contains embedded
NeoWebScript, the NeoWebScript is executed. If the owner of the current page
and the page being included are the same, the code is executed within the
same safe interpreter thats handling the current page. If the file is owned
by someone else, it gets its own interpreter for its neoscript.

See Also:

eof, fblocked

Keywords:

boolean, conditional, else, false, if, true

----------------------------------------------------------------------------
 INCLUDE_VIRTUAL                     65                       NeoSoft, Inc.

                       INCLUDE_VIRTUAL - NeoWebScript

  Copies contents of virtual files.

Synopsis:

* include_virtual virtualPath

Description

Copy the contents of the file named by the specified virtual path (rooted
from the htdocs directory) into the webpage currently being generated.

Matching MIME types and processing embedded requests proceeds as for
include_file above.

See Also:

eof, fblocked

Keywords:

boolean, conditional, else, false, if, true

----------------------------------------------------------------------------
 INCR                                66                       NeoSoft, Inc.

                               INCR - Safe TCL

  Increment the value of the variable

Synopsis:

* incr varName ?increment?

Description

Increments the value stored in the variable whose name is varName. The value
of the variable must be an integer. If increment is supplied then its value
(which must be an

integer) is added to the value of variable varName;
     otherwise 1 is added to varName. The new value is stored as a decimal
     string in variable varName and also returned as result.

See Also:

eof, fblocked

Keywords:

add, increment, variable, value

----------------------------------------------------------------------------
 INCR_NC                             67                       NeoSoft, Inc.

                           INCR_NC - NeoWebScript

  Increments a neo-web counter.

Synopsis:

* incr_nc counter_name [show] [browser] [val_type]

Description

Increment the indicated named counter. This increments the overall lifetime
total, the browsers lifetime total and the daily browser total. Any value
other than "show" in the show argument causes no value to be returned. If
"show" is specified, the indicated value is returned by the incr_nc call.
The default return value is the overall lifetime total. The caller may
request only a specific browser (all, mozilla, mosaic, lynx, mie, other) in
the browser argument. The caller may request only todays count value by
specifying the val_type argument (lifetime, today).

On the first incr_nc call of a new day, a new daily-count record is created
automatically.

See Also:

eof, fblocked

Keywords:

add, increment, variable, value

----------------------------------------------------------------------------
 INCR_PAGE_COUNTER                   68                       NeoSoft, Inc.

                      INCR_PAGE_COUNTER - Neowebscript

  Increment a counter for this webpage and return count

Synopsis:

*  incr_page_counter

Description

Increment a counter for this webpage and return the new count.
(Automatically creates and zeros the counter if it doesnt already exist.)

See Also:

eof, fblocked

Keywords:

add, increment, variable, value

----------------------------------------------------------------------------
 INFO                                69                       NeoSoft, Inc.

                               INFO - Safe TCL

  Return information about the state of the Tcl interpreter

Synopsis:

* info option ?arg arg ...?

Description

This command provides information about various internals of the Tcl
interpreter. The legal options (which may be abbreviated) are:

info args procname
Returns a list containing the names of the arguments to procedure procname,
in order. Procname must be the name of a Tcl command procedure.

info body procname
Returns the body of procedure procname. Procname must be the name of a Tcl
command procedure.

info cmdcount
Returns a count of the total number of commands that have been invoked in
this interpreter.

info commands ?pattern?
If pattern isnt specified, returns a list of names of all the Tcl commands,
including both the builtin commands written in C and the command procedures
defined using the proc command. If pattern is specified, only those names
matching pattern are returned. Matching is determined using the same rules
as for string match.

info complete command
Returns 1 if command is a complete Tcl command in the sense of having no
unclosed quotes, braces, brackets or array element names, If the command
doesnt appear to be complete then 0 is returned. This command is typically
used in line-oriented input environments to allow users to type in commands
that span multiple lines; if the command isnt complete, the script can
delay evaluating it until additional lines have been typed to complete the
command.

info default procname arg varname
Procname must be the name of a Tcl command procedure and arg must be the
name of an argument to that procedure. If arg doesnt have a default value
then the command returns 0. Otherwise it returns 1 and places the default
value of arg into variable varname.

info exists varName
Returns 1 if the variable named varName exists in the current context
(either as a global or local variable), returns 0 otherwise.

info globals ?pattern?
If pattern isnt specified, returns a list of all the names of
currently-defined global variables. If pattern is specified, only those
names matching pattern are returned. Matching is determined using the same
rules as for string match.

info hostname
Returns the name of the computer on which this invocation is being executed.

info level ?number?
If number is not specified, this command returns a number giving the stack
level of the invoking procedure, or 0 if the command is invoked at toplevel.
If number is specified, then the result is a list consisting of the name and
arguments for the procedure call at level number on the stack. If number is
positive then it selects a particular stack level (1 refers to the top-most
active procedure, 2 to the procedure it called, and so on); otherwise it
gives a level relative to the current level (0 refers to the current
procedure, -1 to its caller, and so on). See the uplevel command for more
information on what stack levels mean.

info library
Returns the name of the library directory in which standard Tcl scripts are
stored. This is actually the value of the tcl_library variable and may be
changed by setting tcl_library. See the tclvars manual entry for more
information.

info loaded
?interp?
Returns a list describing all of the packages that have been loaded into
interp with the load command. Each list element is a sub-list with two
elements consisting of the name of the file from which the package was
loaded and the name of the package. For statically-loaded packages the file
name will be an empty string. Interp defaults to the current interpreter.

info locals ?pattern?
If pattern isnt specified, returns a list of all the names of
currently-defined local variables, including arguments to the current
procedure, if any. Variables defined with the global and upvar commands will
not be returned. If pattern is specified, only those names matching pattern
are returned. Matching is determined using the same rules as for string
match.

info
nameofexecutable
Returns the full path name of the binary file from which the application was
invoked. If Tcl was unable to identify the file, then an empty string is
returned.

info
patchlevel
Returns the value of the global variable tcl_patchLevel; see the tclvars
manual entry for more information.

info procs ?pattern?
If pattern isnt specified, returns a list of all the names of Tcl command
procedures. If pattern is specified, only those names matching pattern are
returned. Matching is determined using the same rules as for string match.

info script
If a Tcl script file is currently being evaluated (i.e. there is a call to
Tcl_EvalFile active or there is an active invocation of the source command),
then this command returns the name of the innermost file being processed.
Otherwise the command returns an empty string.

info
sharedlibextension
Returns the extension used on this platform for the names of files
containing shared libraries (for example, .so under Solaris). If shared
libraries arent supported on this platform then an empty string is
returned.

info
tclversion
Returns the value of the global variable tcl_version; see the tclvars manual
entry for more information.

info vars ?pattern?
If pattern isnt specified, returns a list of all the names of
currently-visible variables, including both locals and currently-visible
globals. If pattern is specified, only those names matching pattern are
returned. Matching is determined using the same rules as for string match.

See Also:

eof, fblocked

Keywords:

command, information, interpreter, level, procedure, variable

----------------------------------------------------------------------------
 INFOX                               70                       NeoSoft, Inc.

                            INFOX - Extended TCL

  Return info about Extended Tcl or the current application

Synopsis:

*  infox option

Description

Return information about Extended Tcl, or the cur- rent application. The
following infox command options are available:

version Return the version number of Extended Tcl. The version number for
Extended Tcl is gener- ated by combining the base version of the standard
Tcl code with a letter indicating the version of Extended Tcl being used.
This is the documentation for version 7.4a.

patchlevel Return the patchlevel for Extended Tcl.

have_fchown Return 1 if the fchown system call is avail- able. This supports
the -fileid option on the chown and chgrp commands.

have_fchmod Return 1 if the fchmod system call is avail- able. This supports
the -fileid option on the chmod command.

have_flock Return 1 if the flock command defined, 0 if it is not available.

have_fsync Return 1 if the fsync system call is available and the sync
command will sync individual files. 0 if it is not available and the sync
command will always sync all file buffers.

have_ftruncate Return 1 if the ftruncate or chsize system call is available.
If it is, the ftruncate command -fileid option maybe used.

have_msgcats Return 1 if XPG message catalogs are avail- able, 0 if they are
not. The catgets is designed to continue to function without mes- sage
catalogs, always returning the default string.

have_posix_signals Return 1 if Posix signals are available (block and
unblock options available for the signal command). 0 is returned if Posix
signals are not available. have_truncate Return 1 if the truncate system
call is avail- able. If it is, the ftruncate command may truncate by file
path.

have_waitpid Return 1 if the waitpid system call is avail- able and the wait
command has full functional- ity. 0 if the wait command has limited func-
tionality.

appname Return the symbolic application name of the current application
linked with the Extended Tcl library. The C variable tclAppName must be set
by the application to return an appli- cation specific value for this
variable.

applongname Return a natural language name for the current application. The
C variable tclLongAppName must be set by the application to return an
application specific value for this variable.

appversion Return the version number for the current application. The C
variable tclAppVersion must be set by the application to return an
application-specific value for this variable.

apppatchlevel Return the patchlevel for the current applica- tion. The C
variable tclAppPatchlevel must be set by the application to return an
applica- tion-specific value for this variable.

See Also:

eof, fblocked

Keywords:

command, information, interpreter, level, procedure, variable

----------------------------------------------------------------------------
 INTERP                              71                       NeoSoft, Inc.

                              INTERP - Safe TCL

  Create and manipulate Tcl interpreters

Synopsis:

* interp option ?arg arg ...?

Description

This command makes it possible to create one or more new Tcl interpreters
that co-exist with the creating interpreter in the same application. The
creating interpreter is called the master and the new interpreter is called
a slave. A master can create any number of slaves, and each slave can itself
create additional slaves for which it is master, resulting in a hierarchy of
interpreters.

Each interpreter is independent from the others: it has its own name space
for commands, procedures, and global variables. A master interpreter may
create connections between its slaves and itself using a mechanism called an
alias. An alias is a command in a slave interpreter which, when invoked,
causes a command to be invoked in its master interpreter or in another slave
interpreter. The only other connections between interpreters are through
environment variables (the env variable), which are normally shared among
all interpreters in the application. Note that the name space for files
(such as the names returned by the open command) is no longer shared between
interpreters. Explicit commands are provided to share files and to transfer
references to open files from one interpreter to another.

The interp command also provides support for safe interpreters. A safe
interpreter is a slave whose functions have been greatly restricted, so that
it is safe to execute untrusted scripts without fear of them damaging other
interpreters or the applications environment. For example, all IO channel
creation commands and subprocess creation commands are removed from safe
interpreters. See SAFE INTERPRETERS below for more information on what
features are present in a safe interpreter. The alias mechanism can be used
for protected communication (analogous to a kernel call) between a slave
interpreter and its master.

A qualified interpreter name is a proper Tcl lists containing a subset of
its ancestors in the interpreter hierarchy, terminated by the string naming
the interpreter in its immediate master. Interpreter names are relative to
the interpreter in which they are used. For example, if a is a slave of the
current interpreter and it has a slave a1, which in turn has a slave a11,
the qualified name of a11 in a is the list {a1 a11}.

The interp command, described below, accepts qualified interpreter names as
arguments; the interpreter in which the command is being evaluated can
always be referred to as {} (the empty list or string). Note that it is
impossible to refer to a master (ancestor) interpreter by name in a slave
interpreter except through aliases. Also, there is no global name by which
one can refer to the first interpreter created in an application. Both
restrictions are motivated by safety concerns.

The interp command is used to create, delete, and manipulate slave
interpreters. It can have any of several forms, depending on the option
argument:

interp alias srcPath srcCmd
Returns a Tcl list whose elements are the targetCmd and args associated with
the alias named srcCmd (all of these are the values specified when the alias
was created; it is possible that the actual source command in the slave is
different from srcCmd if it was renamed).

interp alias srcPath srcCmd {}
Deletes the alias for srcCmd in the slave interpreter identified by srcPath.
srcCmd refers to the name under which the alias was created; if the source
command has been renamed, the renamed command will be deleted.

interp alias srcPath srcCmd targetPath targetCmd ?arg arg ...?
This command creates an alias between one slave and another (see the alias
slave command below for creating aliases between a slave and its master). In
this command, either of the slave interpreters may be anywhere in the
hierarchy of interpreters under the interpreter invoking the command.
SrcPath and srcCmd identify the source of the alias. SrcPath is a Tcl list
whose elements select a particular interpreter. For example, "a b"
identifies an interpreter b, which is a slave of interpreter a, which is a
slave of the invoking interpreter. An empty list specifies the interpreter
invoking the command. srcCmd gives the name of a new command, which will be
created in the source interpreter. TargetPath and targetCmd specify a target
interpreter and command, and the arg arguments, if any, specify additional
arguments to targetCmd which are prepended to any arguments specified in the
invocation of srcCmd. TargetCmd may be undefined at the time of this call,
or it may already exist; it is not created by this command. The alias
arranges for the given target command to be invoked in the target
interpreter whenever the given source command is invoked in the source
interpreter. See ALIAS INVOCATION below for more details.

interp aliases ?path?
This command returns a Tcl list of the names of all the source commands for
aliases defined in the interpreter identified by path.

interp create ?-safe? ?--? ?path?
Creates a slave interpreter identified by path and a new command, called a
slave command. The name of the slave command is the last component of path.
The new slave interpreter and the slave command are created in the
interpreter identified by the path obtained by removing the last component
from path. For example, if path is "a b c" then a new slave interpreter and
slave command named "c" are created in the interpreter identified by the
path "a b". The slave command may be used to manipulate the new interpreter
as described below. If path is omitted, Tcl creates a unique name of the
form interpx, where x is an integer, and uses it for the interpreter and the
slave command. If the -safe switch is specified (or if the master
interpreter is a safe interpreter), the new slave interpreter will be
created as a safe interpreter with limited functionality; otherwise the
slave will include the full set of Tcl built-in commands and variables. The
-- switch can be used to mark the end of switches; it may be needed if path
is an unusual value such as -safe. The result of the command is the name of
the new interpreter. The name of a slave interpreter must be unique among
all the slaves for its master; an error occurs if a slave interpreter by the
given name already exists in this master.

interp delete ?path ...?
Deletes zero or more interpreters given by the optional path arguments, and
for each interpreter, it also deletes its slaves. The command also deletes
the slave command for each interpreter deleted. For each path argument, if
no interpreter by that name exists, the command raises an error.

interp eval path arg ?arg ...?
This command concatenates all of the arg arguments in the same fashion as
the concat command, then evaluates the resulting string as a Tcl script in
the slave interpreter identified by path. The result of this evaluation
(including error information such as the errorInfo and errorCode variables,
if an error occurs) is returned to the invoking interpreter.

interp exists path

Returns
     1 if a slave interpreter by the specified path exists in this master, 0
     otherwise. If path is omitted, the invoking interpreter is used.

interp issafe ?path?
Returns 1 if the interpreter identified by the specified path is safe, 0
otherwise.

interp share srcPath channelId destPath Causes the IO channel identified by
channelId to become shared between the interpreter identified by srcPath and
the interpreter identified by destPath. Both interpreters have the same
permissions on the IO channel. Both interpreters must close it to close the
underlying IO channel; IO channels accessible in an interpreter are
automatically closed when an interpreter is destroyed.

interp slaves ?path?
Returns a Tcl list of the names of all the slave interpreters associated
with the interpreter identified by path. If path is omitted, the invoking
interpreter is used.

interp target path alias
Returns a Tcl list describing the target interpreter for an alias. The alias
is specified with an interpreter path and source command name, just as in
interp alias above. The name of the target interpreter is returned as an
interpreter path, relative to the invoking interpreter. If the target
interpreter for the alias is the invoking interpreter then an empty list is
returned. If the target interpreter for the alias is not the invoking
interpreter or one of its descendants then an error is generated. The target
command does not have to be defined at the time of this invocation.

interp transfer srcPath channelId destPath Causes the IO channel identified
by channelId to become available in the interpreter identified by destPath
and unavailable in the interpreter identified by srcPath.

SLAVE COMMAND

For each slave interpreter created with the interp command, a new Tcl
command is created in the master interpreter with the same name as the new
interpreter. This command may be used to invoke various operations on the
interpreter. It has the following general form: slave command ?arg arg ...?
Slave is the name of the interpreter, and command and the args determine the
exact behavior of the command. The valid forms of this command are:

slave aliases
Returns a Tcl list whose elements are the names of all the aliases in slave.
The names returned are the srcCmd values used when the aliases were created
(which may not be the same as the current names of the commands, if they
have been renamed).

slave alias srcCmd
Returns a Tcl list whose elements are the targetCmd and args associated with
the alias named srcCmd (all of these are the values specified when the alias
was created; it is possible that the actual source command in the slave is
different from srcCmd if it was renamed).

slave alias srcCmd {}
Deletes the alias for srcCmd in the slave interpreter. srcCmd refers to the
name under which the alias was created; if the source command has been
renamed, the renamed command will be deleted.

slave alias srcCmd targetCmd ?arg ..?
Creates an alias such that whenever srcCmd is invoked in slave, targetCmd is
invoked in the master. The arg arguments will be passed to targetCmd as
additional arguments, prepended before any arguments passed in the
invocation of srcCmd. See ALIAS INVOCATION below for details.

slave eval arg ?arg ..?
This command concatenates all of the arg arguments in the same fashion as
the concat command, then evaluates the resulting string as a Tcl script in
slave. The result of this evaluation (including error information such as
the errorInfo and errorCode variables, if an error occurs) is returned to
the invoking interpreter.

slave issafe
Returns 1 if the slave interpreter is safe, 0 otherwise.

ALIAS INVOCATION

The alias mechanism has been carefully designed so that it can be used
safely when an untrusted script is executing in a safe slave and the target
of the alias is a trusted master. The most important thing in guaranteeing
safety is to ensure that information passed from the slave to the master is
never evaluated or substituted in the master; if this were to occur, it
would enable an evil script in the slave to invoke arbitrary functions in
the master, which would compromise security.

When the source for an alias is invoked in the slave interpreter, the usual
Tcl substitutions are performed when parsing that command. These
substitutions are carried out in the source interpreter just as they would
be for any other command invoked in that interpreter. The command procedure
for the source command takes its arguments and merges them with the
targetCmd and args for the alias to create a new array of arguments. If the
words of srcCmd were "srcCmd arg1 arg2 ... argN", the new set of words will
be "targetCmd arg arg ... arg arg1 arg2 ... argN", where targetCmd and args
are the values supplied when the alias was created. TargetCmd is then used
to locate a command procedure in the target interpreter, and that command
procedure is invoked with the new set of arguments. An error occurs if there
is no command named targetCmd in the target interpreter. No additional
substitutions are performed on the words: the target command procedure is
invoked directly, without going through the normal Tcl evaluation mechanism.
Substitutions are thus performed on each word exactly once: targetCmd and
args were substituted when parsing the command that created the alias, and
arg1 - argN are substituted when the aliass source command is parsed in the
source interpreter.

When writing the targetCmds for aliases in safe interpreters, it is very
important that the arguments to that command never be evaluated or
substituted, since this would provide an escape mechanism whereby the slave
interpreter could execute arbitrary code in the master. This in turn would
compromise the security of the system.

SAFE INTERPRETERS

A safe interpreter is one with restricted functionality, so that is safe to
execute an arbitrary script from your worst enemy without fear of that
script damaging the enclosing application or the rest of your computing
environment. In order to make an interpreter safe, certain commands and
variables are removed from the interpreter. For example, commands to create
files on disk are removed, and the exec command is removed, since it could
be used to cause damage through subprocesses. Limited access to these
facilities can be provided, by creating aliases to the master interpreter
which check their arguments carefully and provide restricted access to a
safe subset of facilities. For example, file creation might be allowed in a
particular subdirectory and subprocess invocation might be allowed for a
carefully selected and fixed set of programs.

A safe interpreter is created by specifying the -safe switch to the interp
create command. Furthermore, any slave created by a safe interpreter will
also be safe.

A safe interpreter is created with exactly the following set of built-in
commands:

append array break case catch clock close concat continue eof error eval

expr
     fblocked flush for foreach format gets global history if incr info
     interp join lappend lindex

list
     llength lrange lreplace pid proc puts read regexp regsub rename return
     scan set seek split string switch tell trace

All commands not on this list are removed from the interpreter by the interp
create command. Of course, the missing commands can be recreated later as
Tcl procedures or aliases.

In addition, the env variable is not present in a safe interpreter, so it
cannot share environment variables with other interpreters. The env variable
poses a security risk, because users can store sensitive information in an
environment variable. For example, the PGP manual recommends storing the PGP
private key protection password in the environment variable PGPPASS. Making
this variable available to untrusted code executing in a safe interpreter
would incur a security risk.

If extensions are loaded into a safe interpreter, they may also restrict
their own functionality to eliminate unsafe commands. The management of
extensions for safety will be explained in the manual entries for the
package and load Tcl commands.

See Also:

load, package, Tcl_CreateSlave

Keywords:

alias, master interpreter, safe interpreter, slave interpreter

----------------------------------------------------------------------------
 JOIN                                72                       NeoSoft, Inc.

                               JOIN - Safe TCL

  Create a string by joining together list elements

Synopsis:

* join list ?joinString?

Description

The list argument must be a valid Tcl list. This command returns the string
formed by joining all of the elements of list together with joinString
separating each adjacent pair of elements. The joinString argument defaults
to a space character.

See Also:

load, package, Tcl_CreateSlave

Keywords:

element, join, list, separator

----------------------------------------------------------------------------
 KEYLDEL                             73                       NeoSoft, Inc.

                           KEYLDEL - Extended TCL

  Delete field specified by key from the keyed list in listvar

Synopsis:

*  keyldel listvar key

Description

Delete the field specified by key from the keyed list in the variable
listvar. This removes both the key and the value from the keyed list.

See Also:

load, package, Tcl_CreateSlave

Keywords:

element, join, list, separator

----------------------------------------------------------------------------
 KEYLGET                             74                       NeoSoft, Inc.

                           KEYLGET - Extended TCL

  Return value associated with key from the keyed list in listvar

Synopsis:

*  keylget listvar ?key? ?retvar | {}?

Description

Return the value associated with key from the keyed list in the variable
listvar. If retvar is not specified, then the value will be returned as the
result of the command. In this case, if key is not found in the list, an
error will result.

If retvar is specified and key is in the list, then the value is returned in
the variable retvar and the command returns 1 if the key was present within
the list. If key isnt in the list, the command will return 0, and retvar
will be left unchanged. If {} is specified for retvar, the value is not
returned, allowing the Tcl programmer to determine if a key is present in a
keyed list without setting a variable as a side-effect.

If key is omitted, then a list of all the keys in the keyed list is
returned.

See Also:

load, package, Tcl_CreateSlave

Keywords:

element, join, list, separator

----------------------------------------------------------------------------
 KEYLKEYS                            75                       NeoSoft, Inc.

                           KEYLKEYS - Extended TCL

  Return the list of the keys in the keyed list in listvar

Synopsis:

*  keylkeys listvar ?key?

Description

Return the a list of the keyes in the keyed list in the variable listvar. If
keys is specified, then it is the name of a key field whos subfield keys
are to be retrieve.

See Also:

load, package, Tcl_CreateSlave

Keywords:

element, join, list, separator

----------------------------------------------------------------------------
 KEYLSET                             76                       NeoSoft, Inc.

                           KEYLSET - Extended TCL

  Set the value associated with key in the keyed list contained in the
variable listvar

Synopsis:

*  keylset listvar key value ?key2 value2...?

Description

Set the value associated with key, in the keyed list contained in the
variable listvar, to value. If listvar does not exists, it is created. If
key is not currently in the list, it will be added. If it already exists,
value replaces the existing value. Multiple keywords and values may be
speci- fied, if desired.

See Also:

load, package, Tcl_CreateSlave

Keywords:

element, join, list, separator

----------------------------------------------------------------------------
 LAPPEND                             77                       NeoSoft, Inc.

                             LAPPEND - Safe TCL

  Append list elements onto a variable

Synopsis:

* lappend varName ?value value value ...?

Description

This command treats the variable given by varName as a list and appends each
of the value arguments to that list as a separate element, with spaces
between elements. If varName doesnt exist, it is created as a list with
elements given by the value arguments. Lappend is similar to append except
that the values are appended as list elements rather than raw text. This
command provides a relatively efficient way to build up large lists. For
example, "lappend a $b" is much more efficient than "set a [concat $a [list
$b]]" when $a is long.

See Also:

load, package, Tcl_CreateSlave

Keywords:

append, element, list, variable

----------------------------------------------------------------------------
 LASSIGN                             78                       NeoSoft, Inc.

                           LASSIGN - Extended TCL

  Assign successive elements of a list to specified variables

Synopsis:

*  lassign list var ?var...?

Description

Assign successive elements of a list to specified variables. If there are
more variable names than fields, the remaining variables are set to the
empty string. If there are more elements than variables, a list of the
unassigned elements is returned.

For example,

lassign {dave 100 200 {Dave Foo}} name uid gid longName

Assigns name to "dave", uid to "100", gid to "200", and longName to "Dave
Foo".

See Also:

load, package, Tcl_CreateSlave

Keywords:

append, element, list, variable

----------------------------------------------------------------------------
 LEMPTY                              79                       NeoSoft, Inc.

                           LEMPTY  - Extended TCL

  Determines whether a list is empty or not.

Synopsis:


* lempty list

Description

Determine if the specified list is empty. If empty, 1 is returned,
otherwise, 0 is returned. This command is an alternative to comparing a list
to an empty string.

See Also:

load, package, Tcl_CreateSlave

Keywords:

append, element, list, variable

----------------------------------------------------------------------------
 LINDEX                              80                       NeoSoft, Inc.

                              LINDEX - Safe TCL

  Retrieve an element from a list

Synopsis:

* lindex list index

Description

This command treats list as a Tcl list and returns the indexth element from
it (0 refers to the first element of the list). In extracting the element,
lindex observes the same rules concerning braces and quotes and backslashes
as the Tcl command interpreter; however, variable substitution and command
substitution do not occur. If index is negative or greater than or equal to
the number of elements in value, then an empty string is returned. If index
has the value end, it refers to the last element in the list.

See Also:

load, package, Tcl_CreateSlave

Keywords:

element, index, list

----------------------------------------------------------------------------
 LINSERT                             81                       NeoSoft, Inc.

                             LINSERT - Safe TCL

  Insert elements into a list

Synopsis:

* linsert list index element by inserting all of the
element arguments just before the indexth element of
list. Each element argument will become a separate element of
the new list. If index is less than or equal to zero, then the new
elements are inserted at the beginning of the list. If index has the
value end, or if it is greater than or equal to the number of
elements in the list, then the new elements are appended to the list.

Description

This command produces a new list from list by inserting all of the element
arguments just before the indexth element of list. Each element argument
will become a separate element of the new list. If index is less than or
equal to zero, then the new elements are inserted at the beginning of the
list. If index has the value end, or if it is greater than or equal to the
number of elements in the list, then the new elements are appended to the
list.

See Also:

load, package, Tcl_CreateSlave

Keywords:

element, insert, list

----------------------------------------------------------------------------
 LIST                                82                       NeoSoft, Inc.

                               LIST - Safe TCL

  Create a list

Synopsis:

* list ?arg arg ...?

Description

This command returns a list comprised of all the args, or an empty string if
no args are specified. Braces and backslashes get added as necessary, so
that the index command may be used on the result to re-extract the original
arguments, and also so that eval may be used to execute the resulting list,
with arg1 comprising the commands name and the other args comprising its
arguments. List produces slightly different results than concat: concat
removes one level of grouping before forming the list, while list works
directly from the original arguments. For example, the command
list a b {c d e} {f {g h}}
will return
a b {c d e} {f {g h}}
while concat with the same arguments will return a b c d e f {g h}

See Also:

load, package, Tcl_CreateSlave

Keywords:

element, list

----------------------------------------------------------------------------
 LIST_DATA_FILES                     83                       NeoSoft, Inc.

                       LIST_DATA_FILES - Neowebscript

  Lists datafiles

Synopsis:

*  list_data_files

Description

Returns a list of all of the users datafiles.

See Also:

load, package, Tcl_CreateSlave

Keywords:

element, list

----------------------------------------------------------------------------
 LLENGTH                             84                       NeoSoft, Inc.

                             LLENGTH - Safe TCL

  Count the number of elements in a list

Synopsis:

* llength list

Description

Treats list as a list and returns a decimal string giving the number of
elements in it.

See Also:

load, package, Tcl_CreateSlave

Keywords:

element, list, length

----------------------------------------------------------------------------
 LMATCH                              85                       NeoSoft, Inc.

                           LMATCH  - Extended TCL

  Searches a list for matching patterns.

Synopsis:


* lmatch ?mode? list pattern

Description

Search the elements of list, returning a list of all elements matching
pattern. If none match, an empty list is returned.

The mode argument indicates how the elements of the list are to be matched
against pattern and it must have one of the following values:

-exact The list element must contain exactly the same string as pattern.

-glob Pattern is a glob-style pattern which is matched against each list
element using the same rules as the string match command.

-regexp Pattern is treated as a regular expression and matched against each
list element using the same rules as the regexp command.

If mode is omitted then it defaults to -glob.

See Also:

load, package, Tcl_CreateSlave

Keywords:

element, list, length

----------------------------------------------------------------------------
 LOAD_COOKIES                        86                       NeoSoft, Inc.

                         LOAD_COOKIES - Neowebscript

  Loads the cookie into global array

Synopsis:

*  load_cookies [cookieArrayName]

Description

Load the HTTP persistent data cookies into the global array cookies or the
array named by cookieArrayName.

See Also:

load, package, Tcl_CreateSlave

Keywords:

element, list, length

----------------------------------------------------------------------------
 LOAD_FILE                           87                       NeoSoft, Inc.

                          LOAD_FILE - NeoWebScript

  Loads and evaluates code.

Synopsis:

* load_file fileName

Description

Load and evaluate the NeoWebScript code contained in fileName. This is to
support libraries of procs and shared code.

See Also:

load, package, Tcl_CreateSlave

Keywords:

element, list, length

----------------------------------------------------------------------------
 LOAD_MIME_RESPONSE                  88                       NeoSoft, Inc.

                      LOAD_MIME_RESPONSE - Neowebscript

  In multipart/form-data response, master interpreter creates a temporary
directory to receive MIME data

Synopsis:

*  load_mime_response [responseVarName] [uploadedDataVar]

Description

In the event of a multipart/form-data response, the master interpreter
creates a temporary directory to receive and decode the MIME data. The
posted-to file must use load_mime_response to access the MIME data.
responseVarName defaults to "response", and uploadedDataVar defaults to
"filesUploaded". responseVarName is as in load_response.

uploadedDataVar is the name of an array, indexed by field name, in which to
place information about the files uploaded. The information stored in the
array is a list as follows:

   * the temporary name of the file on disk
   * the name of the requested file (in the browser) (OS dependent, and may
     or may not be the full pathname).
   * content-length
   * content-type

The return value of load_mime_response is a list of field names (or else an
empty string) which may be used as arguments to open_mime_file.

Note that an additional program, webunpack must be compiled to support file
uploads. Webunpack is derived munpack, (C) Copyright 1993,1994 by Carnegie
Mellon University, All Rights Reserved, ftp.andrew.cmu.edu:pub/mpack/

See Also:

load, package, Tcl_CreateSlave

Keywords:

element, list, length

----------------------------------------------------------------------------
 LOAD_RESPONSE                       89                       NeoSoft, Inc.

                        LOAD_RESPONSE - Neowebscript

  Load the CGI response into the global array

Synopsis:

*  load_response [responseArrayName] [multiList]

Description

Load the CGI response into the global array response or the array named by
responseArrayName

If the same name is repeated in the post or query, response(__name) is set,
and response(name) is converted to a list. Use [info exists
response(__name)] to check if the array member is a straight value or a
list.

If multiple response is expected (as in <select multiple>), use multiList to
force the array members of the response array to always be a list.

See Also:

load, package, Tcl_CreateSlave

Keywords:

element, list, length

----------------------------------------------------------------------------
 LOAD_VIRTUAL                        90                       NeoSoft, Inc.

                         LOAD_VIRTUAL - NeoWebScript

  Loads and evaluates virtual code.

Synopsis:

* load_virtual virtualPath

Description

Load and evaluate the NeoWebScript code specified by the virtual path
virtualPath. This also supports libraries of procs and shared code.

See Also:

load, package, Tcl_CreateSlave

Keywords:

element, list, length

----------------------------------------------------------------------------
 LOG_MESSAGE                         91                       NeoSoft, Inc.

                         LOG_MESSAGE - NeoWebScript

  Logs a message to a database.

Synopsis:

* log_message loggingDatabase message

Description

The Neoscript programmer can log messages to a number of self-defined
logging databases. When log_message is executed, the message is logged along
with the server time (in integer-seconds format) and the remote hostname (or
IP number, if hostname either was unavailable due to DNS problems or if
Apache was compiled with MINIMAL_DNS selected) fetching the page.

If you need something fancier you can always roll your own with
access_data_file.

See Also:

load, package, Tcl_CreateSlave

Keywords:

element, list, length

----------------------------------------------------------------------------
 LOOP                                92                       NeoSoft, Inc.

                            LOOP  - Extended TCL

  A superior looping procedure.

Synopsis:


* loop var first limit ?increment? body

Description

Loop is a looping command, similar in behavior to the Tcl for statement,
except that the loop state- ment achieves substantially higher performance
and is easier to code when the beginning and ending values of a loop are
known, and the loop variable is to be incremented by a known, fixed amount
every time through the loop.

The var argument is the name of a Tcl variable that will contain the loop
index. The loop index is set to the value specified by first. The Tcl
interpreter is invoked upon body zero or more times, where var is
incremented by increment every time through the loop, or by one if increment
is not specified. Increment can be negative in which case the loop will
count downwards.

When var reaches limit, the loop terminates without a subsequent execution
of body. For instance, if the original loop parameters would cause loop to
terminate, say first was one, limit was zero and increment was not specified
or was non-negative, body is not executed at all and loop returns.

The first, limit and increment are integer expres- sions. They are only
evaulated once at the begin- ning of the loop.

If a continue command is invoked within body then any remaining commands in
the current execution of body are skipped, as in the for command. If a break
command is invoked within body then the loop command will return
immediately. Loop returns an empty string.

See Also:

load, package, Tcl_CreateSlave

Keywords:

element, list, length

----------------------------------------------------------------------------
 LRANGE                              93                       NeoSoft, Inc.

                              LRANGE - Safe TCL

  Return one or more adjacent elements from a list

Synopsis:

* lrange list first last

Description

List must be a valid Tcl list. This command will return a new list
consisting of elements first through last, inclusive. First or last may be
end (or any abbreviation of it) to refer to the last element of the list. If
first is less than zero, it is treated as if it were zero. If last is
greater than or equal to the number of elements in the list, then it is
treated as if it were end. If first is greater than last then an empty
string is returned. Note: "lrange list first first" does not always produce
the same result as "lindex list first" (although it often does for simple
fields that arent enclosed in braces); it does, however, produce exactly
the same results as "list [lindex list first]"

See Also:

load, package, Tcl_CreateSlave

Keywords:

element, list, range, sublist

----------------------------------------------------------------------------
 LREPLACE                            94                       NeoSoft, Inc.

                             LREPLACE - Safe TCL

  Replace elements in a list with new elements

Synopsis:

* lreplace list first last ?element element ...?

Description

Lreplace returns a new list formed by replacing one or more elements of list
with the element arguments. First gives the index in list of the first
element to be replaced (0 refers to the first element). If first is less
than zero then it refers to the first element of list; the element indicated
by first must exist in the list. Last gives the index in list of the last
element to be replaced. If last is less than first then no elements are
deleted; the new elements are simply inserted before first. First or last
may be end (or any abbreviation of it) to refer to the last element of the
list. The element arguments specify zero or more new arguments to be added
to the list in place of those that were deleted. Each element argument will
become a separate element of the list. If no element arguments are
specified, then the elements between first and last are simply deleted.

See Also:

load, package, Tcl_CreateSlave

Keywords:

element, list, replace

----------------------------------------------------------------------------
 LSEARCH                             95                       NeoSoft, Inc.

                             LSEARCH - Safe TCL

  See if a list contains a particular element

Synopsis:

* lsearch ?mode? list pattern

Description

This command searches the elements of list to see if one of them matches
pattern. If so, the command returns the index of the first matching element.
If not, the command returns -1. The mode argument indicates how the elements
of the list are to be matched against pattern and it must have one of the
following values:

-exact
     The list element must contain exactly the same string as pattern.

-glob
     Pattern is a glob-style pattern which is matched against each list
     element using the same rules as the string match command.

-regexp
     Pattern is treated as a regular expression and matched against each
     list element using the same rules as the regexp command.

If mode is omitted then it defaults to -glob.

See Also:

load, package, Tcl_CreateSlave

Keywords:

list, match, pattern, regular expression, search, string

----------------------------------------------------------------------------
 LSORT                               96                       NeoSoft, Inc.

                              LSORT - Safe TCL

  Sort the elements of a list

Synopsis:

* lsort ?switches? list

Description

This command sorts the elements of list, returning a new list in sorted
order. By default ASCII sorting is used with the result returned in
increasing order. However, any of the following switches may be specified
before list to control the sorting process (unique abbreviations are
accepted):

-ascii
     Use string comparison with ASCII collation order. This is the default.

-integer
     Convert list elements to integers and use integer comparison.

-real
     Convert list elements to floatingpoint values and use floating
     comparison.

-command command
     Use command as a comparison command. To compare two elements, evaluate
     a Tcl script consisting of command with the two elements appended as
     additional arguments. The script should return an integer less than,
     equal to, or greater than zero if the first element is to be considered
     less than, equal to, or greater than the second, respectively.

-increasing
     Sort the list in increasing order ("smallest" items first). This is the
     default.

-decreasing
     Sort the list in decreasing order ("largest" items first).

See Also:

load, package, Tcl_CreateSlave

Keywords:

element, list, order, sort

----------------------------------------------------------------------------
 LVARCAT                             97                       NeoSoft, Inc.

                           LVARCAT  - Extended TCL

  Treats each string argument as a list
and concatenates them into a single list.

Synopsis:


* lvarcat var string ?string...?

Description

This command treats each string argument as a list and concatenates them to
the end of the contents of var, forming a single list. The list is stored
back into var and also returned as the result. If var does not exist, it is
created.

See Also:

load, package, Tcl_CreateSlave

Keywords:

element, list, order, sort

----------------------------------------------------------------------------
 LVARPOP                             98                       NeoSoft, Inc.

                           LVARPOP  - Extended TCL

  Deletes an expression from a list.

Synopsis:


* lvarpop var ?indexExpr? ?string?

Description

The lvarpop command pops (deletes) the element indexed by the expression
indexExpr from the list contained in the variable var. If index is omit-
ted, then 0 is assumed. If string, is specified, then the deleted element is
replaced by string. The replaced or deleted element is returned. Thus
"lvarpop argv 0" returns the first element of argv, setting argv to contain
the remainder of the string.

If the expression indexExpr starts with the string end, then end is replaced
with the index of the last element in the list. If the expression starts
with len, then len is replaced with the length of the list.

See Also:

load, package, Tcl_CreateSlave

Keywords:

element, list, order, sort

----------------------------------------------------------------------------
 LVARPUSH                            99                       NeoSoft, Inc.

                          LVARPUSH  - Extended TCL

  Inserts a string into a list.

Synopsis:


* lvarpush var string ?indexExpr?

Description

The lvarpush command pushes (inserts) string as an element in the list
contained in the variable var. The element is inserted before position
indexExpr in the list. If index is omitted, then 0 is assumed. If var does
not exists, it is created.

If the expression indexExpr starts with the string end, then end is replaced
with the index of the last element in the list. If the expression starts
with len, then len is replaced with the length of the list. Note the a value
of end means insert the string before the last element.

See Also:

load, package, Tcl_CreateSlave

Keywords:

element, list, order, sort

----------------------------------------------------------------------------
 MAKE_NC_REGISTRY                    100                      NeoSoft, Inc.

                       MAKE_NC_REGISTRY - NeoWebScript

  Increments a neo-web counter.

Synopsis:

* make_nc_registry [max_counters] [comments]

Description

Executed one time only, to create the page owners Named Counter Registry
file (NCRegistry). Defaults to 20 counters in the registry. Maximum of 200
counters allowed.

See Also:

load, package, Tcl_CreateSlave

Keywords:

element, list, order, sort

----------------------------------------------------------------------------
 MAX                                101                       NeoSoft, Inc.

                             MAX  - Extended TCL

  Returns the higher value argument.

Synopsis:


* max num1 ?..numN?
* expr max(num1,num2)

Description

Returns the argument that has the highest numeric value. Each argument may
be any integer or floating point value.

This functionality is also available as a math function max in the Tcl expr
command.

See Also:

load, package, Tcl_CreateSlave

Keywords:

element, list, order, sort

----------------------------------------------------------------------------
 MD5                                102                       NeoSoft, Inc.

                             MD5 - NeoWebScript

  Returns an md5 digest of string.

Synopsis:

* md5 string

Description

Returns an md5 digest of string.

See Also:

load, package, Tcl_CreateSlave

Keywords:

element, list, order, sort

----------------------------------------------------------------------------
 MIN                                103                       NeoSoft, Inc.

                             MIN  - Extended TCL

  Returns the lesser of two values.

Synopsis:


* min num1 ?..numN?

* expr min(num1, num2)

Description

Returns the argument that has the lowest numeric value. Each argument may be
any integer or float- ing point value.

This functionality is also available as a math function min in the Tcl expr
command.

See Also:

load, package, Tcl_CreateSlave

Keywords:

element, list, order, sort

----------------------------------------------------------------------------
 NEO_CLOCK_TO_RFC850_GMT             104                      NeoSoft, Inc.

                   NEO_CLOCK_TO_RFC850_GMT - NeoWebScript

  Returns the RFC-850 time in GMT.

Synopsis:

* neo_clock_to_rfc850_gmt clock

Description

Returns the passed integer-since-1970 time formatted according to RFC-850,
with the additional proviso that it be specified in GMT timezone only.
(Because thats the way Netscape wanted it.)

For example, neo_clock_to_rfc850_gmt 84236782 should produce "Fri, 01-Sep-72
18:06:22 GMT".

See Also:

load, package, Tcl_CreateSlave

Keywords:

element, list, order, sort

----------------------------------------------------------------------------
 NEO_MAKE_COOKIE                     105                      NeoSoft, Inc.

                       NEO_MAKE_COOKIE - Neowebscript

  Return HTML to create a cookie

Synopsis:

*  neo_make_cookie cookieName cookieValue [-days expireInDays]
[-hours expireInHours] [-minutes expireInMinures] [-path
urlPathCookieAppliesTo] [-domainCookieAppliesTo] [-secure 1|0]

Description

Return HTML to create a cookie which, if emitted to a browser that is
cookie-capable, will cause the cookie to be included subject to defined
restrictions.

Example: neo_make_cookie email karl@neosoft.com -days 30 -path /myApp

Create a cookie named email containing karl@neosoft.com that will be
included in all HTTP requests from the browser were responding to, for a
period of 30 days, when the requests are underneath/myApp on this server,
and the browser is cookie-enabled.

For more information, see Persistent Client State HTTP Cookies at Netscape,
and also Which Browsers Support Cookies at Digital.

This only works with Netscape if its emitted before any other HTML. It uses
<meta http-equiv> to set the cookie, and wont work with browsers that dont
support this.

See Also:

load, package, Tcl_CreateSlave

Keywords:

element, list, order, sort

----------------------------------------------------------------------------
 NEOTRACK                            106                      NeoSoft, Inc.

                           NEOTRACK - NeoWebScript

  Records a visitors path through a site.

Synopsis:

*  neotrack [timeout] [filename]

Description

neotrack records information that may be used to determine a visitors path
through a site. NeoTrack uses IP number to distinguish between users.
timeout is an optional specification of the number of minutes that the
visitor can remain on the current page before we will assume that he has
left the site. Default is 30 minutes. A dash, "-", may be used in this
position if you wish to supply a filename argument but still wish to use the
default timeout. filename - is an optional specification of the name of the
file in which the visitors path information is to be recorded. Default is
NeoTrack (.db is implied and should not be specified). The neotrack command
returns 1 if the page is served to a new visitor. Otherwise, 0 is returned.

See Also:

load, package, Tcl_CreateSlave

Keywords:

element, list, order, sort

----------------------------------------------------------------------------
 NEOTRACK_REPORT                     107                      NeoSoft, Inc.

                       NEOTRACK_REPORT - NeoWebScript

  Reports a visitors path through a site.

Synopsis:

*  neotrack_report key[filename]

Description

neotrack_report produces a report table that details a visitors path. For
each page in the path, this command reports 1) the Refering address (if
available), the current pages URI, 3) the time the current page was entered,
4) the time that the visitor spent on the page (not available for the last
page in a path) and 5) the timeout assigned to the current page. You may
write your orw proc to produce this or a similar report. This built in proc
is provided only for convenience. You must suply the key required to access
the visitor that you want reported. The key is formed as time_IP where time
is the time (in seconds) that the visitor entered your site and IP is the
visitors IP number. The filename argument is an optional identification of
the tracking data file from which the report is to be produced.

See Also:

load, package, Tcl_CreateSlave

Keywords:

element, list, order, sort

----------------------------------------------------------------------------
 OPEN_OUTBOUND_MAIL                  108                      NeoSoft, Inc.

                      OPEN_OUTBOUND_MAIL - NeoWebScript

  Opens an email message.

Synopsis:

* open_outbound_mail subject [to]

Description

This opens an email message and returns the filehandle for use with puts,
etc, for the contents of the message body. The message always comes from the
user name of the owner of the webpage file thats being interpreted, and the
name of the server that did the serving. If to is not specified, the
recipient is also set to be the user name of the owner of the webpage file.

See Also:

load, package, Tcl_CreateSlave

Keywords:

element, list, order, sort

----------------------------------------------------------------------------
 OPEN_POST_NEWS                      109                      NeoSoft, Inc.

                        OPEN_POST_NEWS - NeoWebScript

  Starts a news posting.

Synopsis:

* open_post_news -subject subject -newsgroups
grouplist -distribution distribution

Description

This starts a news posting and returns the filehandle for use with puts,
etc, for the contents of the message body. The message always comes "from"
the user name of the owner of the webpage file thats being interpreted, and
the name of the server that did the serving.

When done writing the body of the news article, write a single line to the
filehandle consisting only of a single period, then close the file.

Note that for this to work you must have a news server within your domain
named or aliased as news. For example, within neosoft.com, open_post_news
will try to contact the news server at news.neosoft.com.

This is an experimental capability that obviously needs work.

See Also:

load, package, Tcl_CreateSlave

Keywords:

element, list, order, sort

----------------------------------------------------------------------------
 PACKAGE                             110                      NeoSoft, Inc.

                             PACKAGE - Safe TCL

  Facilites for pachage loading and version control

Synopsis:

* package forget package

* package ifneeded package version
?script? package names

* package provide package ?version?

* package require ?-exact? package
?version? package unknown ?command?

* package vcompare version1 version2

* package versions package

* package vsatisfies version1 version2

Description

This command keeps a simple database of the packages available for use by
the current interpreter and how to load them into the interpreter. It
supports multiple versions of each package and arranges for the correct
version of a package to be loaded based on what is needed by the
application. This command also detects and reports version clashes.
Typically, only the package require and package provide commands are invoked
in normal Tcl scripts; the other commands are used primarily by system
scripts that maintain the package database.

The behavior of the package command is determined by its first argument. The
following forms are permitted:

package forget package
Removes all information about package from this interpreter, including
information provided by both package ifneeded and package provide.

package ifneeded package version ?script? This command typically appears
only in system configuration scripts to set up the package database. It
indicates that a particular version of a particular package is available if
needed, and that the package can be added to the interpreter by executing
script. The script is saved in a database for

use by subsequent package require commands;
     typically, script sets up auto-loading for the commands in the package
     (or calls load and/or source directly), then invokes package provide to
     indicate that the package is present. There may be information in the
     database for several different versions of a single package. If the
     database already contains information for package and version, the new
     script replaces the existing one. If the script argument is omitted,
     the current script for version version of package package is returned,
     or an empty string if no package ifneeded command has been invoked for
     this package and version.

package names
Returns a list of the names of all packages in the interpreter for which a
version has been provided (via package provide) or for which a package
ifneeded script is available. The order of elements in the list is
arbitrary.

package provide package ?version?
This command is invoked to indicate that version version of package package
is now present in the interpreter. It is typically invoked once as part of
an ifneeded script, and again by the package itself when it is finally
loaded. An error occurs if a different version of package has been provided
by a previous package provide command. If the version argument is omitted,
then the command returns the version number that is currently provided, or
an empty string if no package provide command has been invoked for package
in this interpreter.

package require ?-exact? package ?version? This command is typically invoked
by Tcl code that wishes to use a particular version of a particular package.
The arguments indicate which package is wanted, and the command ensures that
a suitable version of the package is loaded into the interpreter. If the
command succeeds, it returns the version number that is loaded; otherwise it
generates an error. If both the -exact switch and the version argument are
specified then only the given version is acceptable. If -exact is omitted
but version is specified, then versions later than version are also
acceptable as long as they have the same major version number as version. If
both -exact and version are omitted then any version whatsoever is
acceptable. If a version of package has already been provided (by invoking
the package provide command), then its version number must satisfy the
criteria given by -exact and version and the command returns immediately.
Otherwise, the command searches the database of information provided by
previous package ifneeded commands to see if an acceptable version of the
package is available. If so, the script for the highest acceptable version
number is invoked; it must do whatever is necessary to load the package,
including calling package provide for the package. If the package ifneeded
database does not contain an acceptable version of the package and a package
unknown command has been specified for the interpreter then that command is
invoked; when it completes, Tcl checks again to see if the package is now
provided or if there is a package ifneeded script for it. If all of these
steps fail to provide an acceptable version of the package, then the command
returns an error.

package unknown ?command?
This command supplies a "last resort" command to invoke during package
require if no suitable version of a package can be found in the package
ifneeded database. If the command argument is supplied, it contains the
first part of a command; when the command is invoked during a package
require command, Tcl appends two additional arguments giving the desired
package name and version. For example, if command is foo bar and later the
command package require test 2.4 is invoked, then Tcl will execute the
command foo bar test 2.4 to load the package. If no version number is
supplied to the package require command, then the version argument for the
invoked command will be an empty string. If the package unknown command is
invoked without a command argument, then the current package unknown script
is returned, or an empty string if there is none. If command is specified as
an empty string, then the current package unknown script is removed, if
there is one.

package vcompare version1 version2
Compares the two version numbers given by version1 and version2. Returns -1
if version1 is an earlier version than version2, 0 if they are equal, and 1
if version1 is later than version2.

package versions package
Returns a list of all the version numbers of package for which information
has been provided by package ifneeded commands.

package vsatisfies version1 version2
Returns 1 if scripts written for version2 will work unchanged with version1
(i.e. version1 is equal to or greater than version2 and they both have the
same major version number), 0 otherwise.

VERSION NUMBERS

Version numbers consist of one or more decimal numbers separated by dots,
such as 2 or 1.162 or 3.1.13.1. The first number is called the major version
number. Larger numbers correspond to later versions of a package, with
leftmost numbers having greater significance. For example, version 2.1 is
later than 1.3 and version 3.4.6 is later than 3.3.5. Missing fields are
equivalent to zeroes: version 1.3 is the same as version 1.3.0 and 1.3.0.0,
so it is earlier than 1.3.1 or 1.3.0.2. A later version number is assumed to
be upwards compatible with an earlier version number as long as both
versions have the same major version number. For example, Tcl scripts
written for version 2.3 of a package should work unchanged under versions
2.3.2, 2.4, and 2.5.1. Changes in the major version number signify
incompatible changes: if code is written to use version 2.1 of a package, it
is not guaranteed to work unmodified with either version 1.7.3 or version
3.1.

PACKAGE INDICES

The recommended way to use packages in Tcl is to invoke package require and
package provide commands in scripts, and use the procedure pkg_mkIndex to
create package index files. Once youve done this, packages will be loaded
automatically in response to package require commands. See the documentation
for pkg_mkIndex for details.

See Also:

load, package, Tcl_CreateSlave

Keywords:

package, version

----------------------------------------------------------------------------
 PARRAY                              111                      NeoSoft, Inc.

                            PARRAY - Neowebscript

  Dump global array keys and values into page

Synopsis:

*  parray arrayName

Description

Dump the specified global arrays keys and values into webpage.

See Also:

load, package, Tcl_CreateSlave

Keywords:

package, version

----------------------------------------------------------------------------
 PID                                112                       NeoSoft, Inc.

                               PID - Safe TCL

  Retrieve process id(s)

Synopsis:

* pid fileId?

Description

If the fileId argument is given then it should normally refer to a process
pipeline created with the open command. In this case the pid command will
return a list whose elements are the process identifiers of all the
processes in the pipeline, in order. The list will be empty if fileId refers
to an open file that isnt a process pipeline. If no fileId argument is
given then pid returns the process identifier of the current process. All
process identifiers are returned as decimal strings.

See Also:

load, package, Tcl_CreateSlave

Keywords:

file, pipeline, process identifier

----------------------------------------------------------------------------
 PROC                               113                       NeoSoft, Inc.

                               PROC - Safe TCL

  Create a Tcl procedure

Synopsis:

* proc name args body

Description

The proc command creates a new Tcl procedure named name, replacing any
existing command or procedure there may have been by that name. Whenever the
new command is invoked, the contents of body will be executed by the Tcl
interpreter. Args specifies the formal arguments to the procedure. It
consists of a list, possibly empty, each of whose elements specifies one
argument. Each argument specifier is also a list with either one or two
fields. If there is only a single field in the specifier then it is the name
of the argument; if there are two fields, then the first is the argument
name and the second is its default value.

When name is invoked a local variable will be created for each of the formal
arguments to the procedure; its value will be the value of corresponding
argument in the invoking command or the arguments default value. Arguments
with default values need not be specified in a procedure invocation.
However, there must be enough actual arguments for all the formal arguments
that dont have defaults, and there must not be any extra actual arguments.
There is one special case to permit procedures with variable numbers of
arguments. If the last formal argument has the name args, then a call to the
procedure may contain more actual arguments than the procedure has formals.
In this case, all of the actual arguments starting at the one that would be
assigned to args are combined into a list (as if the list command had been
used); this combined value is assigned to the local variable args.

When body is being executed, variable names normally refer to local
variables, which are created automatically when referenced and deleted when
the procedure returns. One local variable is automatically created for each
of the procedures arguments. Global variables can only be accessed by
invoking the global command or the upvar command.

The proc command returns an empty string. When a procedure is invoked, the
procedures return value is the value specified in a return command. If the
procedure doesnt execute an explicit return, then its return value is the
value of the last command executed in the procedures body. If an error
occurs while executing the procedure body, then the procedure-as-a-whole
will return that same error.

See Also:

load, package, Tcl_CreateSlave

Keywords:

argument, procedure

----------------------------------------------------------------------------
 PROFILE                             114                      NeoSoft, Inc.

                           PROFILE  - Extended TCL

  Collects information on the performance of a Tcl script.

Synopsis:


* profile ?-commands? On

* profile off arrayVar

Description

This command is used to collect a performance pro- file of a Tcl script. It
collects data at the Tcl procedure level. The number of calls to a proce-
dure, and the amount of real and CPU time is col- lected. Time is also
collected for the global con- text. The procedure data is collected by
bucketing it based on the procedure call stack, this allows determination of
how much time is spent in a par- ticular procedure in each of its calling
contexts.

The on option enables profile data collection. If the -commands option is
specifed, data on all com- mands within a procedure is collected as well a
procedures. Multiple occurrences of a command within a procedure are not
distinguished, but this data may still be useful for analysis.

The off option turns off profiling and moves the data collected to the array
arrayVar. The array is address by a list containing the procedure call
stack. Element zero is the top of the stack, the procedure that the data is
for. The data in each entry is a list consisting of the procedure call count
and the real time and CPU time in millisec- onds spent in the procedure (and
all procedures it called). The list is in the form {count real cpu}. A Tcl
procedure profrep is supplied for reducing the data and producing a report

See Also:

load, package, Tcl_CreateSlave

Keywords:

argument, procedure

----------------------------------------------------------------------------
 PUTS                               115                       NeoSoft, Inc.

                               PUTS - Safe TCL

  Write a channel

Synopsis:

* puts ?-nonewline? ?channelId? string

Description

Writes the characters given by string to the channel given by channelId.
ChannelId must be a channel identifier such as returned from a previous
invocation of open or socket. It must have been opened for output. If no
channelId is specified then it defaults to stdout. Puts normally outputs a
newline character after string, but this feature may be suppressed by
specifying the -nonewline switch.

Newline characters in the output are translated by puts to platform-specific
end-of-line sequences according to the current value of the -translation
option for the channel (for example, on PCs newlines are normally replaced
with carriage-return-linefeed sequences; on Macintoshes newlines are
normally replaced with carriage-returns). See the fconfigure manual entry
for a discussion of end-ofline translations.

Tcl buffers output internally, so characters written with puts may not
appear immediately on the output file or device; Tcl will normally delay
output until the buffer is full or the channel is closed. You can force
output to appear immediately with the flush command.

When the output buffer fills up, the puts command will normally block until
all the buffered data has been accepted for output by the operating system.
If channelId is in nonblocking mode then the puts command will not block
even if the operating system cannot accept the data. Instead, Tcl continues
to buffer the data and writes it in the background as fast as the underlying
file or device can accept it. The application must use the Tcl event loop
for nonblocking output to work; otherwise Tcl never finds out that the file
or device is ready for more output data. It is possible for an arbitrarily
large amount of data to be buffered for a channel in nonblocking mode, which
could consume a large amount of memory. To avoid wasting memory, nonblocking
I/O should normally be used in an event-driven fashion with the fileevent
command (dont invoke puts unless you have recently been notified via a file
event that the channel is ready for more output data).

See Also:

fileevent

Keywords:

channel, newline, output, write

----------------------------------------------------------------------------
 REPLICATE                           116                      NeoSoft, Inc.

                          REPLICATE  - Extended TCL

  Creates a random integer.

Synopsis:


random limit | seed ?seedval?

Description

Generate a pseudorandom integer number greater than or equal to zero and
less than limit. If seed is specified, then the command resets the random
num- ber generator to a starting point derived from the seedval. This allows
one to reproduce pseudorandom number sequences for testing purposes. If
seedval is omitted, then the seed is set to a value based on current system
state and the current time, pro- viding a reasonably interesting and
ever-changing seed.

See Also:

fileevent

Keywords:

channel, newline, output, write

----------------------------------------------------------------------------
 RANDOM_PICK_HTML                    117                      NeoSoft, Inc.

                       RANDOM_PICK_HTML - Neowebscript

  Randomly picks one of the elements in a list

Synopsis:

*  random_pick_html list

Description

Randomly picks one of the elements in a list and emits that into the webpage
being generated.

See Also:

fileevent

Keywords:

channel, newline, output, write

----------------------------------------------------------------------------
 READ                               118                       NeoSoft, Inc.

                               READ - Safe TCL

  Read from a channel

Synopsis:

* read ?-nonewline? channelId

* read channelId numbytes

Description

In the first form, the read command reads all of the data from channelId up
to the end of the file. If the -nonewline switch is specified then the last
character of the file is discarded if it is a newline. In the second form,
the extra argument specifies how many bytes to read. Exactly that many bytes
will be read and returned, unless there are fewer than numBytes left in the
file; in this case all the remaining bytes are returned.

If channelId is in nonblocking mode, the command may not read as many bytes
as requested: once all available input has been read, the command will
return the data that is available rather than blocking for more input. The
-nonewline switch is ignored if the command returns before reaching the end
of the file.

Read translates end-of-line sequences in the input into newline characters
according to the -translation option for the channel. See the manual entry
for fconfigure for details on the -translation option.

See Also:

eof, fblocked, fconfigure

Keywords:

blocking, channel, end of line, end of file, nonblocking, read, translation

----------------------------------------------------------------------------
 REGEXP                              119                      NeoSoft, Inc.

                              REGEXP - Safe TCL

  Match a regular expression against a string

Synopsis:

* regexp ?switches? exp string ?matchVar? ?subMatchVar
subMatchVar ...?

Description

Determines whether the regular expression exp matches part or all of string
and returns 1 if it does, 0 if it doesnt.

If additional arguments are specified after string then they are treated as
the names of variables in which to return information about which part(s) of
string matched exp. MatchVar will be set to the range of string that matched
all of exp. The first subMatchVar will contain the characters in string that
matched the leftmost parenthesized subexpression within exp, the next
subMatchVar will contain the characters that matched the next parenthesized
subexpression to the right in exp, and so on.

If the initial arguments to regexp start with - then they are treated as
switches. The following switches are currently supported:

-nocase
     Causes upper-case characters in string to be treated as lower case
     during the matching process.

-indices
     Changes what is stored in the subMatchVars. Instead of storing the
     matching characters from string, each variable will contain a list of
     two decimal strings giving the indices in string of the first and last
     characters in the matching range of characters.

-
     Marks the end of switches. The argument following this one will be
     treated as exp even if it starts with a -.

If there are more subMatchVars than parenthesized subexpressions within
exp, or if a particular subexpression in exp doesnt match the string (e.g.
because it was in a portion of the expression that wasnt matched), then the
corresponding subMatchVar will be set to "-1 -1" if -indices has been
specified or to an empty string otherwise.

REGULAR EXPRESSIONS

Regular expressions are implemented using Henry Spencers package (thanks,
Henry!), and much of the description of regular expressions below is copied
verbatim from his manual entry.

A regular expression is zero or more branches, separated by "|". It matches
anything that matches one of the branches.

A branch is zero or more pieces, concatenated. It matches a match for the
first, followed by a match for the second, etc.

A piece is an atom possibly followed by "*", "+", or "?". An atom followed
by "*" matches a sequence of 0 or more matches of the atom. An atom followed
by "+" matches a sequence of 1 or more matches of the atom. An atom followed
by "?" matches a match of the atom, or the null string.

An atom is a regular expression in parentheses (matching a match for the
regular expression), a range (see below), "." (matching any single
character), "^" (matching the null string at the beginning of the input
string), "$" (matching the null string at the end of the input string), a
"\" followed by a single character (matching that character), or a single
character with no other significance (matching that character).

A range is a sequence of characters enclosed in "[]". It normally matches
any single character from the sequence. If the sequence begins with "^", it
matches any single character not from the rest of the sequence. If two
characters in the sequence are separated by "-", this is shorthand for the
full list of ASCII characters between them (e.g. "[0-9]" matches any decimal
digit). To include a literal "]" in the sequence, make it the first
character (following a possible "^"). To include a literal "-", make it the
first or last character.

CHOOSING AMONG ALTERNATIVE MATCHES

In general there may be more than one way to match a regular expression to
an input string. For example, consider the command
regexp (a*)b* aabaaabb x y
Considering only the rules given so far, x and y could end up with the
values aabb and aa, aaab and aaa, ab and a, or any of several other
combinations. To resolve this potential ambiguity regexp chooses among
alternatives using the rule "first then longest". In other words, it
considers the possible matches in order working from left to right across
the input string and the pattern, and it attempts to match longer pieces of
the input string before shorter ones. More specifically, the following rules
apply in decreasing order of priority:

[1]
     If a regular expression could match two different parts of an input
     string then it will match the one that begins earliest.

[2]
     If a regular expression contains | operators then the leftmost matching
     sub-expression is chosen.

[3]
     In *, +, and ? constructs, longer matches are chosen in preference to
     shorter ones.

[4]
     In sequences of expression components the components are considered
     from left to right.

In the example from above, (a*)b* matches aab: the (a*) portion of the
pattern is matched first and it consumes the leading aa; then the b* portion
of the pattern consumes the next b. Or, consider the following example:
regexp (ab|a)(b*)c abc x y z After this command x will be abc, y will be ab,
and z will be an empty string. Rule 4 specifies that (ab|a) gets first shot
at the input string and Rule 2 specifies that the ab sub-expression is
checked before the a subexpression. Thus the b has already been claimed
before the (b*) component is checked and (b*) must match an empty string.

See Also:

eof, fblocked, fconfigure

Keywords:

match, regular expression, string

----------------------------------------------------------------------------
 REGISTER_NC                         120                      NeoSoft, Inc.

                         REGISTER_NC - NeoWebScript

  Increments a neo-web counter.

Synopsis:

* register_nc counter_name [init_counts] [comments]

Description

Executed one time only for each Named Counter. This creates the counter and
places it in the page owners NCRegistry file. Name should be unique.
Initial counts are distributed over the 5 browser classes as Mozilla 85%,
Mosaic 5%, Lynx 2%, MIE 1% and Other 7%. Default initial counts is 0.

See Also:

eof, fblocked, fconfigure

Keywords:

match, regular expression, string

----------------------------------------------------------------------------
 REGSUB                              121                      NeoSoft, Inc.

                              REGSUB - Safe TCL

  Perform substitutions based on regular expression pattern matching

Synopsis:

* regsub ?switches? exp string subSpec varName

Description

This command matches the regular expression exp against string, and it
copies string to the variable whose name is given by varName. If there is a
match, then while copying string to varName the portion of string that
matched exp is replaced with subSpec. If subSpec contains a "&" or "\0",
then it is replaced in the substitution with the portion of string that
matched exp. If subSpec contains a "\n", where n is a digit between 1 and 9,
then it is replaced in the substitution with the portion of string that
matched the n-th parenthesized subexpression of exp. Additional backslashes
may be used in subSpec to prevent special interpretation of "&" or "\0" or
"\n" or backslash. The use of backslashes in subSpec tends to interact badly
with the Tcl parsers use of backslashes, so its generally safest to
enclose subSpec in braces if it includes backslashes.

If the initial arguments to regexp start with - then they are treated as
switches. The following switches are currently supported:

-all
     All ranges in string that match exp are found and substitution is
     performed for each of these ranges. Without this switch only the first
     matching range is found and substituted. If -all is specified, then "&"
     and "\n" sequences are handled for each substitution using the
     information from the corresponding match.

-nocase
     Upper-case characters in string will be converted to lower-case before
     matching against exp; however, substitutions specified by subSpec use
     the original unconverted form of string.

-
     Marks the end of switches. The argument following this one will be
     treated as exp even if it starts with a -.

The command returns a count of the number of matching ranges that were found
and replaced. See the manual entry for regexp for details on the
interpretation of regular expressions.

See Also:

eof, fblocked, fconfigure

Keywords:

match, pattern, regular expression, substitute

----------------------------------------------------------------------------
 REMOTE_HOSTNAME                     122                      NeoSoft, Inc.

                       REMOTE_HOSTNAME - NeoWebScript

  Returns the hostname of the remote host.

Synopsis:

* remote_hostname [ip-address]

Description

This returns the hostname of the remote host if it can be determined. If the
webserver is running with normal DNS, we return the hostname already looked
up and stored in the environment. If its running with minimal DNS, we
perform a DNS lookup on the IP number to try to get the hostname. If we
succeed, we return the hostname, otherwise we return the IP number.

If ip-address is provided, then it attempts to resolve the given IP.
Warning: resolution failures can take a long time and make a page callup
slow.

See Also:

eof, fblocked, fconfigure

Keywords:

match, pattern, regular expression, substitute

----------------------------------------------------------------------------
 RENAME                              123                      NeoSoft, Inc.

                              RENAME - Safe TCL

  Rename or delete a command

Synopsis:

* rename oldName newName

Description

Rename the command that used to be called oldName so that it is now called
newName. If newName is an empty string then oldName is deleted. The rename
command returns an empty string as result.

See Also:

eof, fblocked, fconfigure

Keywords:

command, delete, rename

----------------------------------------------------------------------------
 REPLICATE                           124                      NeoSoft, Inc.

                          REPLICATE  - Extended TCL

  Replicates a string.

Synopsis:


replicate string countExpr

Description

Returns string, replicated the number of times indicated by the expression
countExpr.

See Also:

eof, fblocked, fconfigure

Keywords:

command, delete, rename

----------------------------------------------------------------------------
 RETURN                              125                      NeoSoft, Inc.

                              RETURN - Safe TCL

  Return from a procedure

Synopsis:

* return ?-code code? ?-errorinfo info?
?-errorcode code? ?string?

Description

Return immediately from the current procedure (or toplevel command or source
command), with string as the return value. If string is not specified then
an empty string will be returned as result.

EXCEPTIONAL RETURNS

In the usual case where the -code option isnt specified the procedure will
return normally (its completion code will be TCL_OK). However, the -code
option may be used to generate an exceptional return from the procedure.
Code may have any of the following values:

ok
Normal return: same as if the option is omitted.

error
Error return: same as if the error command were used to terminate the
procedure, except for handling of errorInfo and errorCode variables (see
below).

return
The current procedure will return with a completion code of TCL_RETURN, so
that the procedure that invoked it will return also.

break
The current procedure will return with a completion code of TCL_BREAK, which
will terminate the innermost nested loop in the code that invoked the
current procedure.

continue
The current procedure will return with a completion code of TCL_CONTINUE,
which will terminate the current iteration of the innermost nested loop in
the code that invoked the current procedure.

value
Value must be an integer; it will be returned as the completion code for the
current procedure.

The -code option is rarely used. It is provided so that procedures that
implement new control structures can reflect exceptional conditions back to
their callers.

Two additional options, -errorinfo and -errorcode, may be used to provide
additional information during error returns. These options are ignored
unless code is error.

The -errorinfo option specifies an initial stack trace for the errorInfo
variable; if it is not specified then the stack trace left in errorInfo will
include the call to the procedure and higher levels on the stack but it will
not include any information about the context of the error within the
procedure. Typically the info value is supplied from the value left in
errorInfo after a catch command trapped an error within the procedure.

If the -errorcode option is specified then code provides a value for the
errorCode variable. If the option is not specified then errorCode will
default to NONE.

See Also:

eof, fblocked, fconfigure

Keywords:

break, continue, error, procedure, return

----------------------------------------------------------------------------
 SAVE_MIME_FILE                      126                      NeoSoft, Inc.

                        SAVE_MIME_FILE - Neowebscript

  Copy the mime file uploaded as a field to a datafile

Synopsis:

*  save_mime_file fieldname datafilename

Description

Copy the mime file uploaded as field fieldname to the datafile datafilename.
Once saved, the user can do with it as they will. Our general experience is
that, to make good use of mime uploads, Supervisor mode should be enabled so
that the web page can access a broader range of destinations.

See Also:

eof, fblocked, fconfigure

Keywords:

break, continue, error, procedure, return

----------------------------------------------------------------------------
 SCAN                               127                       NeoSoft, Inc.

                               SCAN - Safe TCL

  Parse string using conversion specifiers in the style of sscanf

Synopsis:

* scan string format varName ?varName ...?

Description

Scan operates by scanning string and formatString together. If the next
character in formatString is a blank or tab then it matches any number of
white space characters in string (including zero). Otherwise, if it isnt a
% character then it must match the next character of string. When a % is
encountered in formatString, it indicates the start of a conversion
specifier. A conversion specifier contains three fields after the %: a *,
which indicates that the converted value is to be discarded instead of
assigned to a variable; a number indicating a maximum field width; and a
conversion character. All of these fields are optional except for the
conversion character.

When scan finds a conversion specifier in formatString, it first skips any
white-space characters in string. Then it converts the next input characters
according to the conversion specifier and stores the result in the variable
given by the next argument to scan. The following conversion characters are
supported:

d
     The input field must be a decimal integer. It is read in and the value
     is stored in the variable as a decimal string.

o
     The input field must be an octal integer. It is read in and the value
     is stored in the variable as a decimal string.

x
     The input field must be a hexadecimal integer. It is read in and the
     value is stored in the variable as a decimal string.

c
     A single character is read in and its binary value is stored in the
     variable as a decimal string. Initial white space is not skipped in
     this case, so the input field may be a whitespace character. This
     conversion is different from the ANSI standard in that the input field
     always consists of a single character and no field width may be
     specified.

s
     The input field consists of all the characters up to the next
     white-space character; the characters are copied to the variable.

e or f or g
The input field must be a floating-point number consisting of an optional
sign, a string of decimal digits possibly containing a decimal point, and an
optional exponent consisting of an e or E followed by an optional sign and a
string of decimal digits. It is read in and stored in the variable as a
floating-point string.

[chars] The input field consists of any number of characters in chars. The
matching string is stored in the variable. If the first character between
the brackets is a ] then it is treated as part of chars rather than the
closing bracket for the set.

[^chars] The input field consists of any number of characters not in chars.
The matching string is stored in the variable. If the character immediately
following the ^ is a ] then it is treated as part of the set rather than the
closing bracket for the set.

The number of characters read from the input for a conversion is the largest
number that makes sense for that particular conversion (e.g. as many decimal
digits as possible for %d, as many octal digits as possible for %o, and so
on). The input field for a given conversion terminates either when a
white-space character is encountered or when the maximum field width has
been reached, whichever comes first. If a * is present in the conversion
specifier then no variable is assigned and the next scan argument is not
consumed.

DIFFERENCES FROM ANSI SSCANF

The behavior of the scan command is the same as the behavior of the ANSI C
sscanf procedure except for the following differences:

[1] %p and %n conversion specifiers are not currently
     supported.

[2]
     For %c conversions a single character value is converted to a decimal
     string, which is then assigned to the corresponding varName; no field
     width may be specified for this conversion.

[3]
     The l, h, and L modifiers are ignored; integer values are always
     converted as if there were no modifier present and real values are
     always converted as if the l modifier were present (i.e. type double is
     used for the internal representation).

See Also:

eof, fblocked, fconfigure

Keywords:

conversion specifier, parse, scan

----------------------------------------------------------------------------
 SCANCONTEXT                         128                      NeoSoft, Inc.

                         SCANCONTEXT - Extended TCL

  Manages file scan contexts.

Synopsis:


scancontext ?option?

Description

This command manages file scan contexts. A scan context is a collection of
regular expressions and commands to execute when that regular expression
matches a line of the file. A context may also have a single default match,
to be applied against lines that do not match any of the regular expres-
sions. Multiple scan contexts may be defined and they may be reused on
multiple files. A scan con- text is identified by a context handle. The
scan- context command takes the following forms:

scancontext create Create a new scan context. The scanmatch command is used
to define patterns in the context. A con- texthandle is returned, which the
Tcl programmer uses to refer to the newly created scan context in calls to
the Tcl file scanning commands.

scancontext delete contexthandle Delete the scan context identified by
contex- thandle, and free all of the match statements and compiled regular
expressions associated with the specified context.

scancontext copyfile contexthandle ?filehandle? Set or return the file
handle that unmatched lines are copied to. (See scanfile). If filehandle is
omitted, the copy file handle is returned. If no copy file is associated
with the context, {} is returned. If a file handle is specified, it becomes
the copy file for this context. If file- handle is {}, then it removes any
copy file speci- fication for the context.

See Also:

eof, fblocked, fconfigure

Keywords:

conversion specifier, parse, scan

----------------------------------------------------------------------------
 SCANFILE                            129                      NeoSoft, Inc.

                           SCANFILE - Extended TCL

  Scan the file specified by fileId, starting from the current file position.

Synopsis:


scanfile ?-copyfile copyfieId? Contexthandle fileId

Description

Scan the file specified by fileId, starting from the current file position.
Check all patterns in the scan context specified by contexthandle against
it, executing the match commands corresponding to patterns matched.

If the optional -copyfile argument is specified, the next argument is a file
ID to which all lines not matched by any pattern (excluding the default
pattern) are to be written. If the copy file is specified with this flag,
instead of using the scancontext copyfile command, the file is disasso-
ciated from the scan context at the end of the scan.

See Also:

eof, fblocked, fconfigure

Keywords:

conversion specifier, parse, scan

----------------------------------------------------------------------------
 SCANMATCH                           130                      NeoSoft, Inc.

                          SCANMATCH - Extended TCL

  Specify Tcl commands to be evaluated
        when regexp is matched by a scanfile command.

Synopsis:


scanmatch ?-nocase? contexthandle ?regexp? commands

Description

Specify Tcl commands, to be evaluated when regexp is matched by a scanfile
command. The match is added to the scan context specified by contex-
thandle. Any number of match statements may be specified for a give context.
Regexp is a regular expression (see the regexp command). If -nocase is
specified as the first argument, the pattern is matched regardless of
alphabetic case.

If regexp is not specified, then a default match is specified for the scan
context. The default match will be executed when a line of the file does not
match any of the regular expressions in the current scancontext.

The array matchInfo is available to the Tcl code that is executed when an
expression matches (or defaults). It contans information about the file
being scanned and where within it the expression was matched.

matchInfo is local to the top level of the match command unless declared
global at that level by the Tcl global command. If it is to be used as a
global, it must be declared global before scanfile is called (since scanfile
sets the matchInfo before the match code is executed, a subsequent global
will override the local variable). The following array entries are
available:

matchInfo(line) Contains the text of the line of the file that was matched.

matchInfo(offset) The byte offset into the file of the first character of
the line that was matched.

matchInfo(linenum) The line number of the line that was matched. This is
relative to the first line scanned, which is usually, but not necessarily,
the first line of the file. The first line is line number one.

matchInfo(context) The context handle of the context that this scan is
associated with.

matchInfo(handle) The file id (handle) of the file currently being scanned.

matchInfo(copyHandle) The file id (handle) of the file specified by the
-copyfile option. The element does not exist if -copyfile was not specified.

matchInfo(submatch0) Will contain the characters matching the first
parenthesized subexpression. The second will be contained in submatch1, etc.

matchInfo(subindex0) Will contain the a list of the starting and ending
indices of the string matching the first parenthesized subexpression. The
second will be contained in subindex1, etc.

All scanmatch patterns that match a line will be processed in the order in
which their specifications were added to the scan context. The remainder of
the scanmatch pattern- command pairs may be skipped for a file line if a
continue is executed by the Tcl code of a preceding, matched pat- tern.

If a return is executed in the body of the match command, the scanfile
command currently in progress returns, with the value passed to return as
its return value.

See Also:

eof, fblocked, fconfigure

Keywords:

conversion specifier, parse, scan

----------------------------------------------------------------------------
 SEEK                               131                       NeoSoft, Inc.

                               SEEK - Safe TCL

  Change the access position for an open channel

Synopsis:

* seek channelId offset ?origin?

Description

Changes the current access position for channelId. ChannelId must be a
channel identifier such as returned from a previous invocation of open or
socket. The offset and origin arguments specify the position at which the
next read or write will occur for channelId. Offset must be an integer
(which may be negative) and origin must be one of the following:

start
     The new access position will be offset bytes from the start of the
     underlying file or device.

current The new access position will be offset bytes from the current access
position; a negative offset moves the access position backwards in the
underlying file or device.

end
     The new access position will be offset bytes from the end of the file
     or device. A negative offset places the access position before the end
     of file, and a positive offset places the access position after the end
     of file.

The origin argument defaults to start.

The command flushes all buffered output for the channel before the command
returns, even if the channel is in nonblocking mode. It also discards any
buffered and unread input. This command returns an empty string. An error
occurs if this command is applied to channels whose underlying file or
device does not support seeking.

See Also:

eof, fblocked, fconfigure

Keywords:

access position, file, seek

----------------------------------------------------------------------------
 SELECT                              132                      NeoSoft, Inc.

                           SELECT  - Extended TCL

   This command allows an Extended Tcl program to wait
              on  zero or more files being
ready for for reading,
              writing, have an exceptional
condition pending,  or
              for  a  timeout  period
to  expire.

Synopsis:

 select readfileIds ?writefileIds? ?exceptfileIds? ?time-
              out?

Description

This command allows an Extended Tcl program to wait on zero or more files
being ready for for reading, writing, have an exceptional condition pending,
or for a timeout period to expire. readFileIds, writeFileIds, exceptFileIds
are each lists of fileIds, as returned from open, to query. An empty list
({}) may be specified if a category is not used.

The files specified by the readFileIds list are checked to see if data is
available for reading. The writeFileIds are checked if the specified files
are clear for writing. The exceptFileIds are checked to see if an
exceptional condition has occured (typically, an error). The write and
exception checking is most useful on devices, how- ever, the read checking
is very useful when commu- nicating with multiple processes through pipes.
Select considers data pending in the stdio input buffer for read files as
being ready for reading, the files do. not have to be unbuffered.

Timeout is a floating point timeout value, in sec- onds. If an empty list is
supplied (or the parame- ter is omitted), then no timeout is set. If the
value is zero, then the select command functions as a poll of the files,
returning immediately even if none are ready.

If the timeout period expires with none of the files becomming ready, then
the command returns an empty list. Otherwise the command returns a list of
three elements, each of those elements is a list of the fileIds that are
ready in the read, write and exception classes. If none are ready in a
class, then that element will be the null list. For example:

select {file3 file4 file5} {file6 file7} {} 10.5

could return

{file3 file4} {file6} {}

or perhaps

file3 {} {}

See Also:

eof, fblocked, fconfigure

Keywords:

access position, file, seek

----------------------------------------------------------------------------
 SET                                133                       NeoSoft, Inc.

                               SET - Safe TCL

  Read and write variables

Synopsis:

* set varName ?value?

Description

Returns the value of variable varName. If value is specified, then set the
value of varName to value, creating a new variable if one doesnt already
exist, and return its value. If varName contains an open parenthesis and
ends with a close parenthesis, then it refers to an array element: the
characters before the first open parenthesis are the name of the array, and
the characters between the parentheses are the index within the array.
Otherwise varName refers to a scalar variable. If no procedure is active,
then varName refers to a global variable. If a procedure is active, then
varName refers to a parameter or local variable of the procedure unless the
global command has been invoked to declare varName to be global.

See Also:

eof, fblocked, fconfigure

Keywords:

read, write, variable

----------------------------------------------------------------------------
 SET_HEADER                          134                      NeoSoft, Inc.

                          SET_HEADER - NeoWebScript

  Sets output headers for image processing routines.

Synopsis:

* set_header header-name header-value

Description

Used by the image processing routines to set output headers. Note that use
of set_header is only effective while generating images, since otherwise the
headers have already been transmitted by the time the users Tcl code
executes. This should change and be more globally available in a future
release.

See Also:

eof, fblocked, fconfigure

Keywords:

read, write, variable

----------------------------------------------------------------------------
 SPLIT                               135                      NeoSoft, Inc.

                              SPLIT - Safe TCL

  Split a string into a proper Tcl list

Synopsis:

* split string ?splitChars?

Description

Returns a list created by splitting string at each character that is in the
splitChars argument. Each element of the result list will consist of the
characters from string that lie between instances of the characters in
splitChars. Empty list elements will be generated if string contains
adjacent characters in splitChars, or if the first or last character of
string is in splitChars. If splitChars is an empty string then each
character of string becomes a separate element of the result list.
SplitChars defaults to the standard white-space characters. For example,
split "comp.unix.misc" .
returns "comp unix misc" and
split "Hello world" {}
returns "H e l l o { } w o r l d".

See Also:

eof, fblocked, fconfigure

Keywords:

list, split, string

----------------------------------------------------------------------------
 STRING                              136                      NeoSoft, Inc.

                              STRING - Safe TCL

  Manipulate strings

Synopsis:

* string option arg  ?arg ...?

Description

Performs one of several string operations, depending on option. The legal
options (which may be abbreviated) are:

string compare string1 string2
Perform a character-by-character comparison of strings string1 and string2
in the same way as the C strcmp procedure. Return -1, 0, or 1, depending on
whether string1 is lexicographically less than, equal to, or greater than
string2.

string first string1 string2
Search string2 for a sequence of characters that exactly match the
characters in string1. If found, return the index of the first character in
the first such match within string2. If not found, return -1.

string index string charIndex
Returns the charIndexth character of the string argument. A charIndex of 0
corresponds to the first character of the string. If charIndex is less than
0 or greater than or equal to the length of the string then an empty string
is returned.

string last string1 string2
Search string2 for a sequence of characters that exactly match the
characters in string1. If found, return the index of the first character in
the last such match within string2. If there is no match, then return -1.

string length string
Returns a decimal string giving the number of characters in string.

string match pattern string
See if pattern matches string; return 1 if it does, 0 if it doesnt.
Matching is done in a fashion similar to that used by the C-shell. For the
two strings to match, their contents must be identical except that the
following special sequences may appear in pattern:

*
     Matches any sequence of characters in string, including a null string.

?
     Matches any single character in string.

[chars]
     Matches any character in the set given by chars. If a sequence of the
     form x-y appears in chars, then any character between x and y,
     inclusive, will match.

\x
     Matches the single character x. This provides a way of avoiding the
     special interpretation of the characters *?[]\ in pattern.

string range string first last
Returns a range of consecutive characters from string, starting with the
character whose index is first and ending with the character whose index is
last. An index of 0 refers to the first character of the string. Last may be
end (or any abbreviation of it) to refer to the last character of the
string. If first is less than zero then it is treated as if it were zero,
and if last is greater than or equal to the length of the string then it is
treated as if it were end. If first is greater than last then an empty
string is returned.

string tolower string
Returns a value equal to string except that all upper case letters have been
converted to lower case.

string toupper string
Returns a value equal to string except that all lower case letters have been
converted to upper case.

string trim string ?chars?
Returns a value equal to string except that any leading or trailing
characters from the set given by chars are removed. If chars is not
specified then white space is removed (spaces, tabs, newlines, and carriage
returns).

string trimleft string ?chars?
Returns a value equal to string except that any leading characters from the
set given by chars are removed. If chars is not specified then white space
is removed (spaces, tabs, newlines, and carriage returns).

string trimright string ?chars?
Returns a value equal to string except that any trailing characters from the
set given by chars are removed. If chars is not specified then white space
is removed (spaces, tabs, newlines, and carriage returns).

string wordend string index
Returns the index of the character just after the last one in the word
containing character index of string. A word is considered to be any
contiguous range of alphanumeric or underscore characters, or any single
character other than these.

string wordstart string

index
     | Returns the index of the first character in the word containing
     character index of string. A word is considered to be any contiguous
     range of alphanumeric or underscore characters, or any single character
     other than these.

See Also:

eof, fblocked, fconfigure

Keywords:

case conversion, compare, index, match, pattern, string, word

----------------------------------------------------------------------------
 SWITCH                              137                      NeoSoft, Inc.

                              SWITCH - Safe TCL

  Evaluate one of several scripts, depending on a given value

Synopsis:

* switch ?options? string pattern body ?pattern body ...?
* switch ?options? string {pattern body ?pattern body...?}


Description

The switch command matches its string argument against each of the pattern
arguments in order. As soon as it finds a pattern that matches string it
evaluates the following body argument by passing it recursively to the Tcl
interpreter and returns the result of that evaluation. If the last pattern
argument is default then it matches anything. If no pattern argument matches
string and no default is given, then the switch command returns an empty
string.

If the initial arguments to switch start with - then they are treated as
options. The following options are currently supported:

-exact
     Use exact matching when comparing string to a pattern. This is the
     default.

-glob
     When matching string to the patterns, use globstyle matching (i.e. the
     same as implemented by the string match command).

-regexp
     When matching string to the patterns, use regular expression matching
     (i.e. the same as implemented by the regexp command).

--
     Marks the end of options. The argument following this one will be
     treated as string even if it starts with a -.

Two syntaxes are provided for the pattern and body arguments. The first uses
a separate argument for each of the patterns and commands; this form is
convenient if substitutions are desired on some of the patterns or commands.
The second form places all of the patterns and commands together into a
single argument; the argument must have proper list structure, with the
elements of the list being the patterns and commands. The second form makes
it easy to construct multi-line switch commands, since the braces around the
whole list make it unnecessary to include a backslash at the end of each
line. Since the pattern arguments are in braces in the second form, no
command or variable substitutions are performed on them; this makes the
behavior of the second form different than the first form in some cases.

If a body is specified as "-" it means that the body for the next pattern
should also be used as the body for this pattern (if the next pattern also
has a body of "-" then the body after that is used, and so on). This feature
makes it possible to share a single body among several patterns.

Below are some examples of switch commands: switch abc a - b {format 1} abc
{format 2} default {format 3} will return 2,
switch -regexp aaab {
^a.*b$
b {format 1}
a* {format 2}
default {format 3}
}
will return 1, and
switch xyz {
a

b
{format 1}
a*
{format 2}
default
{format 3}
}
will return 3.

See Also:

eof, fblocked, fconfigure

Keywords:

switch, match, regular expression

----------------------------------------------------------------------------
 TELL                               138                       NeoSoft, Inc.

                               TELL - Safe TCL

  Return current access position for an open channel

Synopsis:

* tell channelId

Description

Returns a decimal string giving the current access position in channelId.
The value returned is -1 for channels that do not support seeking.

See Also:

eof, fblocked, fconfigure

Keywords:

access position, channel, seeking

----------------------------------------------------------------------------
 TRACE                               139                      NeoSoft, Inc.

                              TRACE - Safe TCL

  Monitor variable accesses

Synopsis:

* trace option ?arg arg ... ?

Description

This command causes Tcl commands to be executed whenever certain operations
are invoked. At present, only variable tracing is implemented. The legal
options (which may be abbreviated) are:

trace variable name ops command
Arrange for command to be executed whenever variable name is accessed in one
of the ways given by ops. Name may refer to a normal variable, an element of
an array, or to an array as a whole (i.e. name may be just the name of an
array, with no parenthesized index). If name refers to a whole array, then
command is invoked whenever any element of the array is manipulated.

Ops indicates which operations are of interest, and consists of one or more
of the following letters:

r
     Invoke command whenever the variable is read.

w
     Invoke command whenever the variable is written.

u
     Invoke command whenever the variable is unset. Variables can be unset
     explicitly with the unset command, or implicitly when procedures return
     (all of their local variables are unset). Variables are also unset when
     interpreters are deleted, but traces will not be invoked because there
     is no interpreter in which to execute them.

When the trace triggers, three arguments are appended to command so that the
actual command is as follows:
command name1 name2 op
Name1 and name2 give the name(s) for the variable being accessed: if the
variable is a scalar then name1 gives the variables name and name2 is an
empty string; if the variable is an array element then name1 gives the name
of the array and name2 gives the index into the array; if an entire array is
being deleted and the trace was registered on the overall array, rather than
a single element, then name1 gives the array name and name2 is an empty
string. Name1 and name2 are not necessarily the same as the name used in the
trace variable command: the upvar command allows a procedure to reference a
variable under a different name. Op indicates what operation is being
performed on the variable, and is one of r, w, or u as defined above.

Command executes in the same context as the code that invoked the traced
operation: if the variable was accessed as part of a Tcl procedure, then
command will have access to the same local variables as code in the
procedure. This context may be different than the context in which the trace
was created. If command invokes a procedure (which it normally does) then
the procedure will have to use upvar or uplevel if it wishes to access the
traced variable. Note also that name1 may not necessarily be the same as the
name used to set the trace on the variable; differences can occur if the
access is made through a variable defined with the upvar command.

For read and write traces, command can modify the variable to affect the
result of the traced operation. If command modifies the value of a variable
during a read or write trace, then the new value will be returned as the
result of the traced operation. The return value from command is ignored
except that if it returns an error of any sort then the traced operation
also returns an error with the same error message returned by the trace
command (this mechanism can be used to implement read-only variables, for
example). For write traces, command is invoked after the variables value
has been changed; it can write a new value into the variable to override the
original value specified in the write operation. To implement read-only
variables, command will have to restore the old value of the variable.

While command is executing during a read or write trace, traces on the
variable are temporarily disabled. This means that reads and writes invoked
by command will occur directly, without invoking command (or any other
traces) again. However, if command unsets the variable then unset traces
will be invoked.

When an unset trace is invoked, the variable has already been deleted: it
will appear to be undefined with no traces. If an unset occurs because of a
procedure return, then the trace will be invoked in the variable context of
the procedure being returned to: the stack frame of the returning procedure
will no longer exist. Traces are not disabled during unset traces, so if an
unset trace command creates a new trace and accesses the variable, the trace
will be invoked. Any errors in unset traces are ignored.

If there are multiple traces on a variable they are invoked in order of
creation, most-recent first. If one trace returns an error, then no further
traces are invoked for the variable. If an array element has a trace set,
and there is also a trace set on the array as a whole, the trace on the
overall array is invoked before the one on the element.

Once created, the trace remains in effect either until the trace is removed
with the trace vdelete command described below, until the variable is unset,
or until the interpreter is deleted. Unsetting an element of array will
remove any traces on that element, but will not remove traces on the overall
array.

This command returns an empty string.

trace vdelete name ops command
If there is a trace set on variable name with the operations and command
given by ops and command, then the trace is removed, so that command will
never again be invoked. Returns an empty string.

trace vinfo name
Returns a list containing one element for each trace currently set on
variable name. Each element of the list is itself a list containing two
elements, which are the ops and command associated with the trace. If name
doesnt exist or doesnt have any traces set, then the result of the command
will be an empty string.

See Also:

eof, fblocked, fconfigure

Keywords:

read, variable, write, trace, unset

----------------------------------------------------------------------------
 TRANSLIT                            140                      NeoSoft, Inc.

                           TRANSLIT - Extended TCL

  Translates characters in a string.

Synopsis:

*  translit inrange outrange string

Description

Translate characters in string, changing characters occuring in inrange to
the corresponding character in outrange. Inrange and outrange may be list of
characters or a range in the form "A-M". For exam- ple: translit a-z A-Z
foobar

See Also:

eof, fblocked, fconfigure

Keywords:

read, variable, write, trace, unset

----------------------------------------------------------------------------
 UNSET                               141                      NeoSoft, Inc.

                              UNSET - Safe TCL

  Delete variables

Synopsis:

* unset name ?name name ... ?

Description

This command removes one or more variables. Each name is a variable name,
specified in any of the ways acceptable to the set command. If a name refers
to an element of an array then that element is removed without affecting the
rest of the array. If a name consists of an array name with no parenthesized
index, then the entire array is deleted. The unset command returns an empty
string as result. An error occurs if any of the variables doesnt exist, and
any variables after the non-existent one are not deleted.

See Also:

eof, fblocked, fconfigure

Keywords:

remove, variable

----------------------------------------------------------------------------
 UPDATE                              142                      NeoSoft, Inc.

                              UPDATE - Safe TCL

  Process pending events and idle callbacks

Synopsis:

* update ?idletasks?

Description

This command is used to bring the application "up to date" by entering the
event loop repeated until all pending events (including idle callbacks) have
been processed.

If the idletasks keyword is specified as an argument to the command, then no
new events or errors are processed; only idle callbacks are invoked. This
causes operations that are normally deferred, such as display updates and
window layout calculations, to be performed immediately.

The update idletasks command is useful in scripts where changes have been
made to the applications state and you want those changes to appear on the
display immediately, rather than waiting for the script to complete. Most
display updates are performed as idle callbacks, so update idletasks will
cause them to run. However, there are some kinds of updates that only happen
in response to events, such as those triggered by window size changes; these
updates will not occur in update idletasks.

The update command with no options is useful in scripts where you are
performing a long-running computation but you still want the application to
respond to events such as user interactions; if you occasionally call update
then user input will be processed during the next call to update.

See Also:

eof, fblocked, fconfigure

Keywords:

event, flush, handler, idle, update

----------------------------------------------------------------------------
 UPLEVEL                             143                      NeoSoft, Inc.

                             UPLEVEL - Safe TCL

  Execute a script in a different stack frame

Synopsis:

* uplevel ? Level? arg ?arg ... ?

Description

All of the arg arguments are concatenated as if they had been passed to
concat; the result is then evaluated in the variable context indicated by
level. Uplevel returns the result of that evaluation.

If level is an integer then it gives a distance (up the procedure calling
stack) to move before executing the command. If level consists of # followed
by a number then the number gives an absolute level number. If level is
omitted then it defaults to 1. Level cannot be defaulted if the first
command argument starts with a digit or #.

For example, suppose that procedure a was invoked from top-level, and that
it called b, and that b called c. Suppose that c invokes the uplevel
command. If level is 1 or #2 or omitted, then the command will be executed
in the variable context of b. If level is 2 or #1 then the command will be
executed in the variable context of a. If level is 3 or #0 then the command
will be executed at toplevel (only global variables will be visible).

The uplevel command causes the invoking procedure to disappear from the
procedure calling stack while the command is being executed. In the above
example, suppose c invokes the command
uplevel 1 {set x 43; d}
where d is another Tcl procedure. The set command will modify the variable x
in bs context, and d will execute at level 3, as if called from b. If it in
turn executes the command
uplevel {set x 42}
then the set command will modify the same variable x in bs context: the
procedure c does not appear to be on the call stack when d is executing. The
command "info level" may be used to obtain the level of the current
procedure.

Uplevel makes it possible to implement new control constructs as Tcl
procedures (for example, uplevel could be used to implement the while
construct as a Tcl procedure).

See Also:

eof, fblocked, fconfigure

Keywords:

context, stack frame, variables

----------------------------------------------------------------------------
 UPVAR                               144                      NeoSoft, Inc.

                              UPVAR - Safe TCL

  Create link to variable in a different stack frame

Synopsis:

* upvar ? Level? otherVar myVar ?otherVar myVar ...?

Description

This command arranges for one or more local variables in the current
procedure to refer to variables in an enclosing procedure call or to global
variables. Level may have any of the forms permitted for the uplevel
command, and may be omitted if the first letter of the first otherVar isnt
# or a digit (it defaults to 1). For each otherVar argument, upvar makes the
variable by that name in the procedure frame given by level (or at global
level, if level is #0) accessible in the current procedure by the name given
in the corresponding myVar argument. The variable named by otherVar need not
exist at the time of the call; it will be created the first time myVar is
referenced, just like an ordinary variable. There must not exist a variable
by the name myVar at the time upvar is invoked. MyVar is always treated as
the name of a variable, not an array element. Even if the name looks like an
array element, such as a(b), a regular variable is created. OtherVar may
refer to a scalar variable, an array, or an array element. Upvar returns an
empty string.

The upvar command simplifies the implementation of callby-name procedure
calling and also makes it easier to build new control constructs as Tcl
procedures. For example, consider the following procedure:
proc add2 name {
upvar $name x
set x [expr $x+2]
}
Add2 is invoked with an argument giving the name of a variable, and it adds
two to the value of that variable. Although add2 could have been implemented
using uplevel instead of upvar, upvar makes it simpler for add2 to access
the variable in the callers procedure frame.

If an upvar variable is unset (e.g. x in add2 above), the unset operation
affects the variable it is linked to, not the upvar variable. There is no
way to unset an upvar variable except by exiting the procedure in which it
is defined. However, it is possible to retarget an upvar variable by
executing another upvar command.

BUGS

If otherVar refers to an element of an array, then variable traces set for
the entire array will not be invoked when myVar is accessed (but traces on
the particular element will still be invoked). In particular, if the array
is env, then changes made to myVar will not be passed to subprocesses
correctly.

See Also:

eof, fblocked, fconfigure

Keywords:

context, frame, global, level, procedure, variable

----------------------------------------------------------------------------
 VWAIT                               145                      NeoSoft, Inc.

                              VWAIT - Safe TCL

  Process events until a variable is written

Synopsis:

* vwait ?varName?

Description

This command enters the Tcl event loop to process events, blocking the
application if no events are ready. It continues processing events until
some event handler sets the value of variable varName. Once varName has been
set, the vwait command will return as soon as the event handler that
modified varName completes.

In some cases the vwait command may not return immediately after varName is
set. This can happen if the event handler that sets varName does not
complete immediately. For example, if an event handler sets varName and then
itself calls vwait to wait for a different variable, then it may not return
for a long time. During this time the toplevel vwait is blocked waiting for
the event handler to complete, so it cannot return either.

See Also:

eof, fblocked, fconfigure

Keywords:

event, variable, wait

----------------------------------------------------------------------------
 WHILE                               146                      NeoSoft, Inc.

                              WHILE - Safe TCL

  Execute script repeatedly as long as a condition is met

Synopsis:

* while test body

Description

The while command evaluates test as an expression (in the same way that expr
evaluates its argument). The value of the expression must a proper boolean
value; if it is a true value then body is executed by passing it to the Tcl
interpreter. Once body has been executed then test is evaluated again, and
the process repeats until eventually test evaluates to a false boolean
value. Continue commands may be executed inside body to terminate the
current iteration of the loop, and break commands may be executed inside
body to cause immediate termination of the while command. The while command
always returns an empty string.

See Also:

eof, fblocked, fconfigure

Keywords:

boolean value, loop, test, while

----------------------------------------------------------------------------
 WRAP                               147                       NeoSoft, Inc.

                             WRAP - Neowebscript

  Add hard wrapping to a string of text

Synopsis:

*  wrap string maxlength ?-html?

Description

Returns a modified string of consecutive characters. Hard wrapping is
inserted at whitespace at or before maxlength number of characters. This
command is very useful in conjunction with mail (refer to
open_outbound_mail), Usenet postings (refer to open_post_news) and other
environments that do not always perform automatic soft wrapping of text.

wrap normally performs hard wrapping by inserting newline characters. But
using the -html switch, newlines can be replaced with <BR> tags to reproduce
the effect of hard wrapping of text in an HTML document without relying on
the <PRE></PRE> elements.

See Also:

eof, fblocked, fconfigure

Keywords:

boolean value, loop, test, while

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