
If you inspect the standard set of Linux tools you will discover that there
is one tool which is conspicuous in its absence. While grep, sort, sed, and
awk do an admirable job of searching, sorting and formatting the output of
existing data files there is no standardized low level tool for inputing
data from a user via a terminal input. In the past each programmer was
forced to write their own data entry program. Not only is this a time
consuming task, it requires considerable skill on the part of the
programmer.

'sci' ('sci' is an abbreviation for SCreen Input, and is pronounced SKY) is
designed to address that deficiency. 'sci' is a template based full screen
input and field editing utility program. 'sci' is designed to be used as
part of a shell script application program - although it may be easily
embedded in compiled C programs by using the 'system' command.

'sci' allows an application programmer to easily create a template using an
ASCII text editor such as 'vi'; which directs 'sci' as to how the the human
- machine interface is to appear to the computer user. An example of a sci
template will quickly illustrate the ease of use, ease of creation, and
power of a 'sci' enabled application.




			Student Billing Program
			 Press Cntrl C to Exit

	Last Name: ...................
	First Name: ...................
	Home Phone: ............
	Work Phone: ............
	Home Street Address: .........................
	Apt Number: .................
	City: .....................
	State: ..
	Zip Code: ..........
	Email: ...................................
	Monthly fee: ......
# Any line with a lb-sign at the start is a comment or 
# control line. Lines after the first comment
# line starting with 'lb-sign,colon' are   
# instructions to SCI as to the type of entry field. 
#
#
#:7dHouston 
#:8dTx 
#:9d770 
#:9n 
#:11f###.##
#:0Cc
#
#
# The first command  7dHouston  tells SCI to place the 
# Default value Houston in the seventh (City) field.
# The user may wipe out this default or tab  
# past it to accept it. The next two commands do 
# the same thing. The zip code field allows the user
# to complete the zip code without having to 
# input the 770 common to most Houston zip codes. 
# Defaults are not necessary 
# but are allowed in any field. 
# The next instructs SCI to only accept 
# numeric values in this field. 
# Normally SCI defaults to alpha-numeric 
# input on all fields. This allows some error 
# checking on what goes into 
# critical data fields in the resulting database. 
# More than one data entry field may be placed 
# on a single line. 
#
# A #:1N command allows only numbers to be entered.
#
# The difference between #:1n and #:1N is that the former
# allows '+' '-' or '.' plus numbers while the latter allows
# numbers only to be entered.
#
# A #:1A command would allow the entry of alpha characters only
#
# A #:1a command would allow the entry of alpha or punctuation,
# in the first data entry field. The c and a flags may be used
# with the same field. However if the n and a flags are both used
# in a field no data may be entered into the field since the 
# alpha and numeric fields are mutually exclusive.
#
# The command #:11f###.## is a formatted input. When using
# formatted input data entry is calculator style: from right
# to left. The formatted input requires that the total number of
# periods in the field is the same as the number of formatting
# characters to the right of the f in the command. The numbers
# 0..9 '+' and '-' are the only characters accepted during a 
# formatted input. The decimal point is fixed by the format.
# Default values are ignored in a formatted input field.
#
# The command #:0Cc turns on color in the input fields. The
# colors are c - cyan, r - red, y - yellow, m - magenta,
# b - blue, g - green, w - white. The field number 0 selects 
# all of the input fields. Individual fields may be given  
# different colors by issuing multiple color commands. For 
# example to set the first field to red and the third field 
# to green the following commands could be given: 
# #:1Cr and #:3Cg.
#
# A #:0bg command would change the background colors for
# the data entry screen. No number other than 0 is allowed for
# this instruction. The color options are the same as for the
# character color options. Pick contrasting colors for 
# visibility.
#
# An input field may be placed in one of two mandatory 
# states by use of the #:1m or #:1M commands. The 'm' 
# version requires at least one character in the field
# before the tab key will exit the field. The 'M' version
# requires that the field be filled in completely before
# the tab key will exit the field. The use of the #:0M 
# command would require each of the fields to be completely
# filled in before the tab key could exit the fields.
#
# A #:1c command would force sci to capitalize every thing in the
# first data entry field. The command #:0c would capitalize all 
# of the data entry fields.
#
# A #:1y command would force the first field to become
# Yes/No field. Yes/No fields are exactly one character
# in length - if a Yes/No field is more than one
# character long it will be reduced to one character in length.
# Yes/No fields may have the capitalization flag ( #:1c ) 
# and mandatory flags ( #:1m or #:1M ) set. Yes/No fields will
# accept only 'y', 'Y', 'n', 'N' characters. A #:0y command
# would make all the fields one character in length.
# 
# It is permitted to have more than one data entry field on
# a line in a sci template.
#
# Starting with revision 0.4.0 the -f flag may be used to 
# change the character used to indicate a data entry field
# in a template.
#
# Starting with revision 0.4.2 a #:0x<path><parms> command
# will allow the command specified by the path to fill in a 
# field as though the user had typed in the data. This would
# be useful if there was a bar code reader program etc. An
# example line would be: 
#
# #:3x/usr/bin/bcode -a
#
# In that example the imaginary program 'bcode' would be 
# passed the '-a' parameter and would pass back the data
# produced on its standard output. The data passed back will
# truncated to the length of the input field or will be 
# ended by the called program exiting or the end of the first
# line of data it outputs. If the program does not exist an
# error message will be given.
#
# Starting with revision 0.4.3 two new commands have been
# added: #:0s<path><parms> and #:0S<path><parms>.
# These commands will pipe the data in a field to an 
# executable file. The 'S' version of the command will also
# send the data to the output file while the 's' version will
# only send the data to the executable - leaving the field in
# output data file blank. An example usage would be:
#
# #:3S/bin/cat >> extraout
#
# This command would append the data from the 3rd field to the
# end of the 'extraout' file as well as sending it to the 
# normal sci output file.
# Starting with revision 0.4.7 pick Boxes have been added to the
# templates command structure. An example of a pick box is:
#
# #:7pHouston,Dallas,Los Angeles,Berkeley,Alameda,Biloxi
#
# This command would allow the operator to enter one of the 
# listed commands by simply selecting it. When the cursor is
# over a pick box data item and the <screenKey> (default is
# the 'Enter' key) is pressed the data is written to the 
# field. Pressing the <fieldKey> (default is 'Tab') will exit
# the pick box.
#
# Starting with revision 0.5.1, a simple, m1-like preprocessor
# has been added.  Think of it somewhat like the C language
# pre-processor, except that directives are introduced by
# a `@' in column 1 instead of a `#'.
#
# The following directives are implemented:
#   @include file
#     Process the text appearing in `file' as if it were copied
#     directly into this file.
#
#   @ifdef var
#     Text after this statement (up until the next @else or
#     @endif) is processed only if `var' exists.
#
#   @ifndef var
#     Text after this statement (up until the next @else or
#     @endif) is processed only if `var' does not exist.
#
#   @else
#     Only valid between an @ifdef/@ifndef and @endif pair,
#     works like `else' in shell lingo.
#
#   @endif
#     Ends an @ifdef or @ifndef block.  This works like `fi'
#     in shell lingo.
#
#   @def var [value ...]
#     Sets the value of `var' to the `value' parameters,
#     concatenated.
#
#   @undef var
#     Removes `var' from the namespace.
#
#   @center [text ...]
#     Calculates and pads text so that it will be centered
#     regardless of the terminal width.
#
# Variable substitution can occur anywhere within the file, and
# is invoked by placing a `@' followed by the variable name.
# For example, @HOME will expand to the value of the HOME
# variable.  A pseudo-variable `@' exists, which may be
# referenced as `@@' in the source, which evaluates to a single
# `@' symbol in the output.
#
# The syntax @{HOME} is also valid, and is useful when you
# need to run the right side of the variable name up against
# some other text.
#
# At startup, sci inherits all of the calling shell's exported
# variables (environment variables).  This means you may
# reference any shell variables from the sci script.  Setting
# a variable, however, does not affect the value of the
# calling shell's variable.
#
# Any programs that are started by sci will see the new values
# of the variables.
#
# Also starting with Revision 0.5.1 #!/usr/bin/sh/sci -t may 
# be used on the first line of a template to turn it into an 
# executable script. The install location of sci has been 
# changed from /usr/local/bin to /usr/bin.  
# As of version 0.5.2 command line parameters may be overridden
# with the SCIPARMS environment variable. It is possible to 
# pass the variable using the @def SCIPARMS macro on a 
# template. EXAMPLE
#
# @def SCIPARMS -h -l -d -t -o output.file
#




-- End of Example Template --

As you can see a 'sci' input template is both easy to create and to
understand. Once the template is created 'sci' uses it to interact with the
user in a full screen input session. The periods in the template display
portion show the size of the interactive data fields which will be accepted.

'sci' may also be instructed to generate a non edit-able sequential number
unique to each screen - which may be used as a serial number etc.

'sci' uses the curses package to allow operation on just about any terminal
or display device supported by Linux. 'sci' is designed to greatly increase
the ease with which applications may be written while reducing the skill
level required by the application writer. The individual application writer
is no longer required to be able to handle the cryptic curses programming
required to achieve the degree of functionality in screen input and editing
which sci supplies.

'sci' accepts the following command line options:

-l or --loop puts 'sci' into the loop mode; 'sci' accepts new input screens
after a <Screen Key> (the default is the 'Enter' key). This allows multiple
screens of data to be placed in the output file. The only exit from 'sci' in
the loop mode is 'Cntrl-C'. Default is single screen entry.

-s or --sequential puts 'sci' into the serial number mode: each screen of
data will have a trailing serial number tacked onto it in the output data
file.

-t <file_name> or --template <file_name> gives 'sci' the name of a template
file to use for generating the screen. The default looks for the file
'template.sci'.

-o <file_name> or --output <file_name> gives 'sci' the name of an output
file to use for storing data. The default name is 'scidata.out'

-h or --hilite causes 'sci' to high-light the data fields, so that they
stand out from back ground areas of the screen.

-d or --datestamp causes 'sci' to enter the timestamp (date) mode. Each
screen of data will have a timestamp field in ASCII added to it in the
output data file. The timestamp will indicate the number of seconds past the
epoch (Jan 1, 1970 0:00:00 UTC)

-r or --reverse reverses the functions of the <Field Key>  and <Screen Key>;
<Field Key> accepts a screen of data, <Screen Key> goes from one field to
the next. This is useful in the case of numeric data entry from a key pad.

-H or --no-help turns off the popup help system. The popup help can explain
why the program is not accepting keystrokes in a field, or why the tab and
return keys are not working properly.

-p <char> --pad-char allows the default padding character in data fields to
be changed from a period to anything the programmer desires. The -p option
will accept either a literal character such as '*' or a hexadecimal value
0x2a for example in the <char> field.

-S <Screen Key> or --screen-key allows the programmer to set the key used to
accept a screen to any value desired. As in the -p switch either a hex value
or a literal character may be used as the <Screen Key> parameter. The
default <Sreen Key> is the 'Enter' key.

-F <Field Key>  or --field-key <Field Key> allows the programmer to set the
key used to accept a field to any value desired. As in the -p switch either
a hex value or a literal character may be used as the <Field Key> parameter.
The default <Field Key> is the 'Tab' key.

-D <delim> or --delimiter <delim> allows the programmer to change the
delimiter in the output file which separates records. The default delimiter
is a 0x09 ('Tab') character. As in the -p switch either a hex value or a
literal character may be used as the <delim> parameter.

-f <Field char> or --field-char <Field char> allows the character used in
the template to indicate a data entry field to be changed from a period to
any value the desired. The -f option will accept either a literal character
such as '*' or a hexadecimal value 0x2a for example in the <Field char>
field.

-B or --pickBox-delimiter <pickBox delim> Changes the default separator
character for pickBox lists from ',' to the user's preference. A character
may be given or a hex value 0xnn for the separator is acceptable.

-P <Prev key> or --prevkey <Prev key> This defines the key to use for back
tabbing. Default is a KEY_UP. The <Prev key> may be a hex value 0xNNNNNNN or
a single character.


-N <Next key> or --nextkey <Next key> This defines the alternate key to use
for tabbing. Default is a KEY_DOWN. The <Next key> may be a hex value
0xNNNNNNN or a single character.

Each command line option may be used in conjunction with any other command
line option, or by itself.

While editing a screen, the <Field Key> (default is a 'Tab' key) causes
'sci' to jump to the next field to edit. Pressing the <Field Key> (default
is an 'Enter' key) when in the last field causes 'sci' to jump back to the
first field on the screen. When there is data in a field using the <Field
Key> in that field causes the cursor to go to the next empty place in the
field.

The 'Backspace' key or 'Cntrl-h' keys will cause 'sci' to erase the last
character typed in the current field.

The left arrow key - if supported by the terminal - will reposition the
cursor into an already entered field. The right arrow key will move the
cursor toward the end of the field. Inside of edited data the backspace and
delete keys work as expected: backspace deletes the character to the left of
the cursor, delete removes the character at the cursor. The field operate in
insert mode rather than over type mode when the cursor is inside of already
entered data. (Thanks to Sotiris Vassilopoulos for these improvements).


The 'Cntrl-u' keys will cause the entire current active field to be erased
(including any default values in the field).

The 'Cntrl-c' keys will cause 'sci' to abort data entry without saving the
current data fields to the output file. 'sci' traps the SIGINT command,
pressing 'Cntrl-c' will not cause a script which wraps around 'sci' to also
abort.

Pressing the <Screen Key>  will cause 'sci' to record a new screen full of
data in the output file. In the loop mode 'sci' will accept another screen
of data
- in default single screen mode 'sci' will exit.


When a field has been designated as a numeric only field 'sci' will accept
only the following keys: the numbers 0 through 9, a '-' key, a '+' key, and
a decimal point.

'sci' input fields are designed to be 'bullet proof'; that is keystrokes are
accepted only within a data field. No amount of effort on the part of the
operator will allow keystroke entry outside of a data field; i.e. the
background part of a 'sci' template is a protected area of the screen which
the operator may not change from within sci.

The fields in a 'sci' output file are separated from each other by <delim>
(default is 0x09 'Tab') characters, a screen full of data is separated from
the next screen by a '0x0a' ('newline') character.

'sci' is designed to be easily portable to any Unix style operating system
which supports 'curses'.

Because of its nature, 'sci' cannot be written as a redirect-able 'filter' type
program which accepts input from 'stdin' and writes output to 'stdout'; the
use of the 'curses' package prevents IO redirection of this type from being
meaningful.

This program is released under the GPL, and represents payment of part of the
debt I owe to the developers of Linux for producing such a superior
operating system.  


Included with the 'sci' source code is a simple integrated development system
written in shell script which greatly speeds up the development process.
This shell script is called 'c'. As I was raised on 'Wordstar' in the CP/M
era I use 'jstar' as my editor in this script, if you prefer 'vi' or
'emacs' etc. as your editor please feel free to edit the shell script.
I recommend that you try the 'c' shell script, I think that after a little
use you will really like the way it increases your productivity.

As of version 0.1.3 or later, sci is multiuser - file locking is handled
properly to allow multiple users to update an output file.

'sci' uses the 'usleep()' function during record locking to sleep for a
random time (between 1000 and 2000 microseconds) during record locking
attempts. This keeps the program from hammering the file system with record
lock attempts, and hogging the processor. If your operating system does not
support the usleep() function, the configure script will disable this
option.

Also included in the package is an elementary application called 'app' which
demonstrates the use of 'sci' in a shell script. The application produces a
zip code sorted mail list using data input by 'sci' and formatting by 'awk'.
As of version 3.3 the sample application has been expanded to demonstrate
how to use sci to edit fields in place in a multi-user fashion. Several new
scripts have been added to the distribution to facilitate this use of sci.

To create the 'sci' program type

./configure 

make

To install the program and the man page, become root and type

make install

  
Depending upon your operating system it may be necessary to change the line 
#include <curses.h> in the source program and the variable CURSES in the
makefile. Some operating systems use the different syntax for these
definitions.

Sadly under Red Hat 6.0 use of toupper() in a program compiled with
optimization on will result in a warning being issued from the compiler. My
apologies for this behavior. If anyone knows a way around this please
contact:

Bob Canup

rcanup@hal-pc.org
