trunk/c_tin0/c_tin0.tex

%$Header: /home/dashley/cvsrep/e3ft_gpl01/e3ft_gpl01/dtaipubs/esrgubka/c_tin0/c_tin0.tex,v 1.6 2003/11/03 02:14:24 dtashley Exp $

\chapter[\ctinzeroshorttitle{}]{\ctinzerolongtitle{}}

\label{ctin0}

\index{Hobbs, Jeffrey}
\beginchapterquote{``I may seem more arrogant, but I think that's just because
                     you didn't realize how arrogant I was before.''}
                   {Jeffrey Hobbs \cite{bibref:i:jeffreyhobbs}, Tcl Ambassador, Ajuba Solutions}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%Section Tag: INT
\section{Overview Of The Iju Tool Set}
\index{IjuTools}\index{Iju!tool set}
The \emph{Iju}\footnote{The name \emph{Iju} is an acronym for
``\emph{I}t's \emph{J}ust \emph{U}s'', and has its origins in
a dilbertesque conversation between disgruntled engineers 
in a large company years ago where it
was stated that we felt \emph{it's just us} who understood
the nature of certain product problems.} tool set (or \emph{IjuTools} for short) 
is a collection of utilities and research tools which are
useful for small microcontroller work.  At this time, the current version of 
IjuTools is v1.05.

As of v1.05, IjuTools consists of [only] the following components.

\begin{itemize}
\item \emph{IjuScripter}, a statically linked\footnote{By \emph{statically linked}
      I mean that a monolithic executable which is complete and requires no
      DLLs is provided.} version of Tclsh, with extensions.

\item \emph{IjuConsole}, a statically linked version of Wish, with extensions.

\item A set of DOS command-line utilities.  In many cases, these utilities
      perform functions similar to the Tcl/Tk extensions incorporated into
          IjuScripter/IjuConsole.
\item Supplemental example scripts, technical papers, books, and URLs.\footnote{As
      of v1.03, just a few, but I hope the list will grow.}
\end{itemize}

IjuTools is built around Tcl/Tk 8.3.1.\index{Tcl}\index{Tk}
Tcl is a scripting language from 
Scriptics\index{Scriptics} (now Interwoven).\index{Interwoven}
At the present time,
all components of the tool set are implemented
as Tcl extensions, so that they can be executed interactively or as part of
a script.  The scripted nature of the tool set gives users the ability to
use the tool set components together in arbitrary ways.

Although IjuTools is slanted towards microcontroller software development,
it is a good general automation solution (in the same sense that
Tcl and Tk are), and it can be used for other endeavors.  (In fact,
the generation of this book is automated using IjuConsole.)

At the present time, \emph{The Iju Tool Set} (including this
book) is maintained
at the site \texttt{http://ijutools.sourceforge.net} as an
open-source product.  All source code may be freely downloaded.
In the future, in order to recoup some of the cost of producing
the tool set, some of the convenient distributions (packaged installations,
printed materials, and media) may be sold
for a small fee.  However, all of the source code will remain
public and free.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%Design Goals Of IjuTools
%Section tag: DGI
\section{IjuTools Design Goals}
The design goals of IjuTools are enumerated below.  
Each goal is discussed in more detail later.

\begin{itemize}

\item \textbf{Stability, Repeatability, And Lack Of Intermittent Behavior:}  
      because the tool set will be used to produce ROM images, it must be very reliable.

\item \textbf{Extensibility:}
      it must be straightforward to extend the capabilities of the tool set.

\item \textbf{Cross-Platform Capability:}
      the tool set should have a migration path to platforms other than Microsoft
      Windows.

\item \textbf{Utility:}
      the tool set should be genuinely useful.

\end{itemize}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Stability, Repeatability, And Lack Of Intermittent Behavior}

\emph{Microsoft Windows}\index{Windows}\index{Microsoft Windows}\index{Microsoft!Windows}
is surely the most despised computing
platform in the world.  The complaints include
lack of stability, incomplete uninstallation of
applications, and unintended interactions between
applications.   Web servers,\index{web server}\index{HTTP server} 
file servers,\index{file server} and mail\index{mail server}
servers are often hosted under Unix\index{Unix} or Linux\index{Linux}
rather than a Microsoft product because
the MTBF for Windows is typically hundreds of hours, whereas the the MTBF
for Unix or Linux is typically hundreds of days.  However, most microcontroller 
software development is done on Windows platforms.

Defects in Windows are unlikely to result
in the corruption of a ROM image or in incorrect data (human error is 
a more likely cause).  However, to minimize the possibility of human error and
unforeseen interactions between applications, IjuTools possesses the following design 
characteristics.

\begin{itemize}

\item \textbf{DLLs and the Windows registry are not used.}  
      Each component of \emph{The Iju Tool Set} is a monolithic
      executable image (an .EXE file).  This makes it impossible 
      to mismatch an application
      with the DLLs it requires.  Additionally, the Windows registry,
      which may cause differences in behavior from machine to machine,
      is not used.  Although the IjuTools installation installs executable
      files in specific directories, any of these executable files may be copied
      or moved to other locations or to other machines (without an installation process),
      because the executable files are standalone and have no DLL or registry
      dependencies.

\item \textbf{Executable files are internally versioned.}  
      IjuTools version numbers are never re-used, and each executable component
      of the tool set ``knows'' its version number.  IjuScripter and IjuConsole
      contain embedded commands to allow a script to determine the version number of 
      the executable.  Thus, it is possible to author scripts that will only run
      with a specific version of IjuScripter or IjuConsole.

\end{itemize}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Extensibility}

The two core components of IjuTools (IjuScripter and IjuConsole) are extensible in the
sense that additional commands can be added to the language understood by the tools.
Because of the way in which Tcl treats strings (they can be of arbitrary length), the output
of a built-in command can be easily retained in RAM (for further processing by other
commands) or placed in a file (as output).
Thus, if parsing or file transformation is involved, it is easy to make the claim that
IjuTools is ``arbitrarily extensible'' because commands can be added arbitrarily to IjuScripter
and IjuConsole..

For microcontroller work, this type of extensibility is probably adequate.

However, no framework has yet been developed to encompass the integration of 
GUI applications or additional executables into IjuTools.  I welcome suggestions
in this area.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Cross-Platform Capability}

Windows is presently the dominant platform for microcontroller software
development.  However, it is easy to envision scenarios in which Linux or Unix become
popular platforms for certain types of development.

Tcl/Tk inherently runs on Windows, Linux, Unix, and Solaris platforms.
(I'm sure that designing one set of source code that fits all of these
platforms has caused Scriptics substantial technical anguish, but they
were successful in this.)  To ensure that IjuScripter and IjuConsole are
portable to these other platforms if necessary, the following steps
are planned.

\begin{itemize}

\item All changes to the Tcl/Tk 8.3.1 core (the changes will be bug fixes
      only) will be logged so that they can be
      reproduced if IjuTools is ported to another platform using 
      the original Scriptics 8.3.1 code as the starting
      point.\footnote{As the Tcl 8.3.1 core is maintained, 
      to clean up the Windows source code and enhance clarity, it is natural
      to eliminate blocks of code that are preprocessed out and do not
      enter the compile stream for a Windows build.  This type of maintenance
      will make it impossible to compile the code for any other platform,
      and hence the original Scriptics code would be necessary as a starting
      point.}

\item Extensions will follow coding standards to minimize platform dependencies
      and enhance portability
      (sizes of ordinal data sizes, use of floating-point arithmetic, etc.).

\item Extensions will not make use of the Win32 API or standard library
      calls---instead, they will interact only with the Tcl/Tk core.

\end{itemize}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Utility}

In the assembly of IjuTools and supporting materials, I hope and believe 
I've met the goal of providing something genuinely useful for microcontroller
software developers. I've listed below the characteristics of the tool set
which I feel most enhance its usefulness.

\begin{itemize}
\item \textbf{The tools can be used interactively as well as from a script.} 
      Because Tcl commands can be used 
      both interactively and from
      a script, IjuScripter and IjuConsole are useful for interactive
      tasks (file conversions, impromptu calculations).  For example,
      with no calculator handy, \texttt{expr sqrt(5)} can be used
      interactively in IjuScripter or IjuConsole to obtain $\sqrt{5}$.
\item \textbf{The tools are suitable for orchestrating microcontroller
      software builds.}  Microcontroller software builds tend to be
      awkward, complex, and to involve many steps---utilities such as
      \texttt{MAKE} fall short in their ability to support
      such builds.  The Tcl scripting language
      is rich enough to allow the automation of these kinds of software builds.
\item \textbf{The tools can be used as a general automation utility.}
      The static executables provided can be used
      to automate common office tasks; such as 
      removing all files last modified prior to a certain date,
      or searching your boss' computer for information
      about your colleagues' salaries while your boss is away at lunch.
\item \textbf{The full source code for the tools is available.}  The full 
      source code for the tools is available at 
          \texttt{http://ijutools.sourceforge.net}.  
          The source code can be useful in several ways.
      \begin{itemize}
      \item The source code contains all project files for the GUI version
            of Microsoft Visual C++.  It can be used as a quick way to get
            a Tcl/Tk GUI build for Windows up and going.\footnote{Two notes on this
            \ldots{} First, the base source code is available from Scriptics
            for free, but as of this writing, Scriptics does not support
            a GUI build (instead, they provide a MAKE file).  The port to
            the GUI interface is not wholly straightforward and requires
            some effort.  Second, 
            Tcl/Tk version 8.3.1 is old and getting older (but the new 
            features added in subsequent versions don't make them any more
            useful for microcontroller work).}
      \item The source code can be used as the basis for another product.
      \item The source code for Tcl extensions can be harvested for other
            purposes.  For example, functions to calculate the CRC32
            are included to support the
            Tcl/Tk extensions.  This code could be harvested for other
            uses.
      \end{itemize}
\item \textbf{The IjuTools distribution contains useful materials not available
      anywhere else.}  The technical papers and supplemental materials included
      are genuinely useful for microcontroller software work.
\end{itemize}

Overall, I hope I've met the aim of assembling and distributing something which is
genuinely \emph{useful}.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%Section Tag:  EPL
\section{IjuTools Expansion And Development Plans}

Future development of the Iju tool set will focus [only] in the following directions.

\begin{itemize}
\item \textbf{Removal of any existing Tcl/Tk 8.3.1 bugs.}  This is the very 
      highest priority, as any such bugs threaten the usability or 
      logical integrity of the tool.
\item \textbf{Development and co-development of new extensions useful in
      microcontroller work.}  Any suggestions that I receive for
      extensions will be placed on my Web page, and I will attack them as
      time and expertise permit.  I also welcome co-development opportunities,
      where other parties develop the extensions and I act in a review and
      integration capacity.
\item \textbf{Acquisition of additional software useful in microcontroller work.}
      I welcome contributions in this area, as well.
\item \textbf{Acquisition of additional books, technical papers, books, web links, and
      other materials.}  I welcome contributions in all of these areas.  (Please keep in
      mind that in order for me to distribute any contributed material with the Iju
      tool set, I must have a letter of permission from the copyright holder.)
\end{itemize}

One direction that it won't be possible to go with the Iju tool set is enhancement of
the Tcl/Tk 8.3.1 core.  The Tcl/Tk core is its own complexity, and I'd like to confine
any efforts there to correction of existing defects and neatening of the set
of source files.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Common Parameter Formats}
%Section tag: CCL0
\label{ctin0:sccl0}

\emph{The Iju Tool Set} consists of the following components:

\begin{itemize}
\item The core of \emph{Tclsh} and \emph{Wish} (the \emph{Tcl}
      language with \emph{Tk} graphic extensions).

\item Extensions to the language, added for utility in microcontroller
      work or for research purposes.

\item A set of DOS command-line utilities.
\end{itemize}

Each of these components makes heavy use of strings.  Since Tcl/Tk is 
string-based (really, this is the \emph{only} Tcl data type), it is natural
to think of each Tcl/Tk command as accepting string arguments.  Many of the
DOS command-line utilities accept arguments on the command-line which are
in exactly the same form as required by a Tcl/Tk extension, and hence
it is also useful to think of the DOS command-line utilities as 
accepting string arguments.  For this reason, all string parameter types
are documented together in this section.

When using Tcl/Tk extensions, the author of the Tcl/Tk script
has complete control over how strings are passed to the extension.
However, when using the DOS command-line utilities,
the DOS/Windows command-line
interpreter breaks the command-line into parameters based on the 
occurence of whitespace (spaces and tabs) on the command line.  These
parameters are passed to the utility itself as an array of strings.
It is possible to cause the command-line interpreter to pass parameters
containing whitespace by quoting the parameter.  All of the IjuTools
command-line utilites will work correctly with whitespace embedded in
parameters if it is appropriate for the context (for example, whitespace
may be appropriate in a path name but not appropriate within an integer).

In this section, each different type of parameter is given a symbolic
tag (\texttt{urn}, for example).  This symbolic tag is used in the description
of Tcl extensions and DOS utilities to denote parameters.  In some cases,
additional descriptive information is concatenated to the symbolic 
tag (\texttt{divisor\_urn} or \texttt{urn\_divisor}, for example) to
indicate the role the parameter fills.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{\texttt{winfname} Parameter Format}
%Section Tag: WNF0
\label{ctin0:sccl0:swnf0}

\index{winfname@\texttt{winfname}}
\texttt{winfname} is used to indicate a file whose name is used only through
the Windows operating system (i.e. to open a file, read from a file, etc.).  File
names are ultimately arbitrated by the underlying operating system, which
in the case of any of \emph{The Iju Tool Set} components will always be a variant
of Microsoft Windows.
A parameter of type \texttt{winfname} may be any file name which Windows
will accept.

Note in parameters of type \texttt{winfname} that backslashes (`$\backslash$')
must normally be used in paths rather than forward slashes 
(`/').\footnote{Note that this is different than the path conventions in Tcl
scripts.  The reason for this is that Tcl seeks to be operating system
independent, so that the path separator is standardized to be the 
forward slash.}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{\texttt{tclfname} Parameter Format}
%Section Tag: TCF0
\label{ctin0:sccl0:stcf0}

\index{tclfname@\texttt{tclfname}}
\texttt{tclfname} is used to indicate a file name as specified within a Tcl
script.  This is normally the same as a Windows file name, except that
the forward slash rather than the backslash is used as the path separator.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{\texttt{winfpath} Parameter Format}
%Section Tag: WFP0
\label{ctin0:sccl0:swfp0}

\index{winfpath@\texttt{winfpath}}
\texttt{winfpath} is used to indicate a directory path in a format
acceptable to Microsoft Windows.  This means that the path 
separator is the backslash rather than the forward slash.  In nearly all
cases the the path name may be specified with or without a trailing backslash.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{\texttt{tclfpath} Parameter Format}
%Section Tag: TCF1
\label{ctin0:sccl0:stcf1}

\index{tclfpath@\texttt{tclfpath}}
\texttt{tclfpath} is used to indicate a directory path in a format
acceptable inside a Tcl script.  This means that the path 
separator is the forward slash rather than the backslash.
In nearly all cases the path name may be specified with or without
a trailing forward slash.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{\texttt{uint} Parameter Format}
%Section Tag: UIN0
\label{ctin0:sccl0:suin0}

\index{uint@\texttt{uint}}
\texttt{uint} is used to indicate an arbitrarily large unsigned integer 
(\emph{unsigned} means non-negative).  The following formats are accepted:

\begin{itemize}
\item \emph{A string of digits.}  Examples: ``0'', ``342'', ``4912947'', etc.
      Note in this format that the only acceptable representation of 
      zero is ``0'' (``00'' will not be accepted).
\item \emph{A string of digits with commas.}  Examples: ``0'',
      ``342'', ``4,921''.  Note that if \emph{any} commas occur
      in the string of digits, \emph{every} comma must be
      properly placed.  For example, ``49,241,34'' will not be accepted
      as an integer.  In this format, the only acceptable representation
      of zero is ``0''.
\item \emph{An integer expressed as a number in scientific notation.}
      ``3.14e2'' will be accepted as the integer ``314''.  Numbers in
      scientific notation that do not evaluate to integers, such
      as ``3.12e1'', will not be accepted.
\end{itemize}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{\texttt{sint} Parameter Format}
%Section Tag: SIN0
\label{ctin0:sccl0:ssin0}

\index{sint@\texttt{sint}}
\texttt{sint} is used to indicate a signed integer 
of arbitrary magnitude.  (By \emph{signed} we mean
that the integer may be negative, zero, or positive.)

Any format described for the \emph{uint} parameter format
in Section \ref{ctin0:sccl0:suin0} (immediately above)
will be accepted, with the relaxation that a minus sign
(`-') may be included in front of the integer.  As described
above, the integer zero may have only one `0' digit.
Additionally, the parsing strategies have been relaxed to
allow zero to be negated, i.e. ``-0'' is allowed (but 
``-00'' is not).  \footnote{This parsing relaxation was made to allow for the
possibility that some software may output negative numbers
close to zero in forms such as ``-0.000e+000''.  The
permissiveness in the parsing was deliberate.}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{The \texttt{uint8}, \texttt{uint16},
            \texttt{uint24}, 
            \texttt{uint32}, \texttt{uint64}, And
            \texttt{uint128} Parameter Formats}
%Section Tag: UIG0
\label{ctin0:sccl0:suig0}

\index{uint8@\texttt{uint8}}
\index{uint16@\texttt{uint16}}
\index{uint24@\texttt{uint24}}
\index{uint32@\texttt{uint32}}
\index{uint64@\texttt{uint64}}
\index{uint128@\texttt{uint128}}
The \texttt{uint8}, \texttt{uint16},
\texttt{uint32}, \texttt{uint64}, and
\texttt{uint128} are unsigned integers with the 
number of bits implied by the name.  Such integers
may assume values from 0 through $2^{N} - 1$,
where $N$ is the number of bits.

For example, a \texttt{uint8} may assume values from
0 through 255.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{The \texttt{sint8}, \texttt{sint16},
            \texttt{sint24}, 
            \texttt{sint32}, \texttt{sint64}, And
            \texttt{sint128} Parameter Formats}
%Section Tag: SIG0
\label{ctin0:sccl0:ssig0}

\index{sint8@\texttt{sint8}}
\index{sint16@\texttt{sint16}}
\index{sint24@\texttt{sint24}}
\index{sint32@\texttt{sint32}}
\index{sint64@\texttt{sint64}}
\index{sint128@\texttt{sint128}}
The \texttt{sint8}, \texttt{sint16},
\texttt{sint32}, \texttt{sint64}, and
\texttt{sint128} are signed integers with the 
number of bits implied by the name.  Such integers
may assume values from $-2^{N-1}$ through $2^{N-1} - 1$,
where $N$ is the number of bits.

For example, a \texttt{sint8} may assume values from
-128 through 127.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{The \texttt{rint8}, \texttt{rint16}, \texttt{rint24},
            \texttt{rint32}, \texttt{rint64}, And
            \texttt{rint128} Parameter Formats}
%Section Tag: RIG0
\label{ctin0:sccl0:srig0}

\index{rint8@\texttt{rint8}}
\index{rint16@\texttt{rint16}}
\index{rint24@\texttt{rint24}}
\index{rint32@\texttt{rint32}}
\index{rint64@\texttt{rint64}}
\index{rint128@\texttt{rint128}}
The \texttt{rint8}, \texttt{rint16},
\texttt{rint32}, \texttt{rint64}, and
\texttt{rint128} are unsigned (i.e. non-negative)
integers which do not exceed the maximum positive
value that a signed integer of the same size could
attain.  Such integers may assume values from 0
through $2^{N-1} - 1$,
where $N$ is the number of bits.

For example, a \texttt{rint8} may assume values from
0 through 127.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{The \texttt{urn} Parameter Formats}
%Section Tag: URN0
\label{ctin0:sccl0:surn0}

\index{urn@\texttt{urn}}
The \texttt{urn} parameter type is a non-negative rational number with
non-negative integer components of arbitrary magnitude.  
There are two ways to specify such a rational
number.

\begin{enumerate}
\item \emph{Integer components, separated by a forward slash.}
      ``1/3'', ``0/49'', and ``36/1e31'' are acceptable.  A denominator
      of zero is not allowed.
\item \emph{A number in scientific notation.}  The general accepted
      form is

      \texttt{[digs|digs.|.digs|digs.digs][e|E[[+|-]digs]]},

      where \texttt{digs} represents a series of digits and the 
      vertical bar (`\texttt{|}') separates a string of parameters,
      only one of which is allowed to appear.  Numbers of this
      type are always rational and will be converted to a rational
      number for calculation.  A unary `+' before the mantissa is allowed.
\end{enumerate}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{The \texttt{srn} Parameter Formats}
%Section Tag: SRN0
\label{ctin0:sccl0:ssrn0}

\index{srn@\texttt{srn}}
The \texttt{srn} parameter type is a signed arbitrary rational number
(by \emph{signed} we mean that it may be negative, zero, or positive).
This format is identical to the format
described in Section \ref{ctin0:sccl0:surn0}, immediately above,
with the relaxation that a unary `-' is allowed to indicate a 
negative number.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{A High-Speed Tour Of Tcl And Tk}

\subsection{Invoking Tclsh, Wish, IjuScripter, And IjuConsole}

\subsection{General Features Of Tcl}

\subsection{Statements}

\subsection{Procedures}

\subsection{The \emph{expr} Command}

\subsection{Conditional Control Constructs}

\subsection{Looping Constructs}

\subsection{File And Console I/O}

\subsection{Obtaining Command-Line Arguments}

\subsection{A Sample Program}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Additional Resources For Learning Tcl And Tk}

This chapter has provided a brief tutorial of Tcl and Tk---enough
information to begin writing basic scripts which use the microcontroller
extensions in IjuTools.  However, to use Tcl and Tk in a competent
fashion, additional materials and additional study are required.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Acknowledgements}

What I've called \emph{The Iju Tool Set} would not have been possible in
its present form without the outstanding technical work by the engineers
at Scriptics, Ajuba Solutions, and Interwoven; plus contributors and
newsgroup posters from all over the world.  I had discussed with colleagues
the possibility of an interpreted language to integrate tools, but I never
could have done such a masterful job as Scriptics has done; and I was fortunate
to discover Tcl/Tk.

For proposing Tcl and Tk as a solution to my particular integration
problem, I'm grateful to Les Hatton \cite{bibref:i:leshatton}.  

For generous
technical support from Scriptics/Ajuba/Interwoven, I'm grateful to 
Jeff Hobbs \cite{bibref:i:jeffreyhobbs}, Dan Kuchler \cite{bibref:i:dankuchler}, 
and John Ousterhout \cite{bibref:i:johnousterhout}.
I'm also grateful to all of the newsgroup posters who 
answered questions and offered suggestions, including
but not limited to Jan Nijtmans and Dave Graveaux.

For providing a solution (the \emph{mktclapp} program) which allows
the construction of a standalone Wish executable without the
requirement for external library script files, I'm grateful to
D. Richard Hipp \cite{bibref:i:drichardhipp}.

For testing installation packages and executables for the 
Win32 platform and offering
prompt and detailed feedback about problems, I'm grateful to
Mirza Kolokovic \cite{bibref:i:mirzakolakovic}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\noindent\begin{figure}[!b]
\noindent\rule[-0.25in]{\textwidth}{1pt}
\begin{tiny}
\begin{verbatim}
$RCSfile: c_tin0.tex,v $
$Source: /home/dashley/cvsrep/e3ft_gpl01/e3ft_gpl01/dtaipubs/esrgubka/c_tin0/c_tin0.tex,v $
$Revision: 1.6 $
$Author: dtashley $
$Date: 2003/11/03 02:14:24 $
\end{verbatim}
\end{tiny}
\noindent\rule[0.25in]{\textwidth}{1pt}
\end{figure}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% $Log: c_tin0.tex,v $
% Revision 1.6  2003/11/03 02:14:24  dtashley
% All duplicate labels as flagged by LaTeX removed.  Additional files added
% to Microsoft Visual Studio edit context.
%
% Revision 1.5  2001/08/18 18:37:56  dtashley
% Preparation for v1.05 release.
%
% Revision 1.4  2001/08/16 19:53:27  dtashley
% Beginning to prepare for v1.05 release.
%
% Revision 1.3  2001/07/30 02:54:17  dtashley
% INTFAC extension and command-line utility finished.
%
% Revision 1.2  2001/07/01 20:42:51  dtashley
% Move out of binary mode for use with CVS.
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% $History: c_tin0.tex $
% 
% *****************  Version 4  *****************
% User: Dashley1     Date: 1/01/01    Time: 8:13p
% Updated in $/uC Software Multi-Volume Book (A)/Chapter, TIN0, Tool Introduction
% Edits.
% 
% *****************  Version 3  *****************
% User: Dashley1     Date: 12/31/00   Time: 7:42p
% Updated in $/uC Software Multi-Volume Book (A)/Chapter, TIN0, Tool Introduction
% 
% *****************  Version 2  *****************
% User: Dashley1     Date: 12/22/00   Time: 12:56a
% Updated in $/uC Software Multi-Volume Book (A)/Chapter, TIN0, Tool Introduction
% Tcl automated method of build refined.
% 
% *****************  Version 1  *****************
% User: David Ashley Date: 11/29/00   Time: 5:45p
% Created in $/uC Software Multi-Volume Book (A)/Chapter, TIN0, Tool Introduction
% Initial check-in.
%
%End of file C_TIN0.TEX