sci(1SP)

NAME
sci - Template controlled full screen input of data

SYNOPSIS

sci [-l, -s -h -d -r -H ]
    -p <char> -t </path/filename> -o </path/filename> -S <Screen key> -F <Field key> -D <delim> -f <Field Char> -B <pickBox Delim> -P <Prev Key> -N <Next Key>

DESCRIPTION
sci uses a template file to control the operator's input of data into a flat tab separated ASCII data file. The default tab delimiter may be changed.

OPTIONS

-l or --loop
loop mode; accepts more than one screen of data. For the operator, a 'Cntrl-c' is the only way out of loop mode.

-s or --sequential
serial number mode. sci will supply a unique serial number for each screen full of data it writes to the data file.

-d or --datestamp
timestamp mode. sci will supply a time stamp field in ASCII for number of seconds past epoch (JAN 1, 1970 0:00:00 UTC).

-t <path/filename> or --template <path/filename>
This identifies the file to use as an input template for data entry.

-o <path/filename> or --output <path/filename>
This identifies the file to use as an output file.

-p <char> or --pad-char <char>
This defines the character to use on the screen to indicate a character field. The char may be ' 'in which case the edit fields will not be visibly indicated. The <char> may be a hex value 0xNNNNNNNN or a single character.

-f <Field Char> or --field-char <Field Char>
This defines the character to use in a template to indicate a data entry field instead of a period. The <Field Char> may be a hex value 0xNNNNNNNN or a single character.

-S <Screen key> or --screen-key <Screen key>
This defines the key to use for screen acceptance. Default is a carriage return. The <Screen key> may be a hex value 0xNNNNNNN or a single character.

-F <Field key> or --field-key <Field key>
This defines the key to use to signal the program that the operator has accepted a field. Default is a tab. The <Field key> may be a hex value 0xNNNNNNN or a single character.

-D <delim> or --delimiter-char <delim>
This allows the user to specify the delimiter used in the output file to separate fields inside of a record. The default is 0x09 (tab). The <delim> may be a single character or a two digit hex value 0xNN.

-h or --hilite
High Light mode; Acceptance fields have terminal defined standout mode.

-r or --reverse
Reverse <Screen Key> and <Field Key> functions.

-H or --no-help
Turns off the pop up help system. The pop up help system can explain why sci seems stuck in a field when the <Screen Key> or <Field Key> keys are pressed or why nothing seems to be occurring when a write is requested.

-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 0xNN 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 0xNN or a single character.

EXAMPLES

sci
Entered by itself sci will search for the default template file 'template.sci' in the current directory. If it doesn't find one sci will abort operation. If a template is found the screen will be cleared, and the data input portion of the template file will be displayed. a '.' in the active portion of a sci template file will serve to designate a data input field. An example template file follows:

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: ......

# The end of the screen display information is given by this line

# 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 --

SCIPARMS

sci -l
This command will place SCI in the loop mode. In the loop mode accepting a screen full of data by pressing the <Screen Key> (default 'Enter') key will cause sci to save the entered data in the output file, clear the data fields of previously entered data on the screen and allow sci to accept more data. The only way out of this data entry mode is through the 'Cntrl-c' keys.

sci -t foo.bar
This command line will cause sci to use the file 'foo.bar' as a template for data entry.

sci -o foo.bar
This command line will cause sci to use the file 'foo.bar' as an output file. Data is appended to the end of the file.

sci -s
This command line places sci in the serial number mode, the output file will have an extra field in it, a sequential serial number will be added into each line of data.

sci -d
This command line places sci in the time stamp mode, the output file will have an extra field in it; an ASCII timestamp: number of seconds past the epoch (JAN 1 1970 0:00:00 UTC) will be added into each line of data.

EDITING COMMANDS
To erase the last entered keystroke in a field the operator uses the backspace or 'Cntrl-h' keys. To skip to the next data entry field the operator presses the <Field Key> (normally a 'Tab' key unless changed). When in the last data entry field on a screen the <Field Key> will recycle to the first data entry field. To erase the entire entry field (including default information) the operator presses the 'Cntrl-u' keys. If the terminal has left and right arrow keys which are recognized by curses, then the cursor may be moved back into the text to insert or delete characters. If the terminal has home and end keys recognized by curses then pressing the home key will result in the cursor being moved to the start of the field, pushing the end key will result in the cursor being moved to the end of the entered data in the field.

To abort data entry the operator presses the 'Cntrl-c' keys. This will cause whatever information is in the data entry fields to be discarded without saving. The program traps SIGINT so that 'Cntrl-c' will exit from the program, but will not abort a shell script or other wrapper program. To accept the screen full of data the operator presses the <Screen Key> (normally 'Enter'). This will cause the entered data to be appended to the output file as a <delim> (normally 0x09 'Tab') separated line of ASCII data terminated by a '0x0a' newline character. If the -r option is given then the functions of the <Screen Key> key and the <Field Key> will be reversed.
 If the program is in the serial number mode, (sci -s) a unique sequential serial number is placed in an extra field before the newline character. If the program is in the timestamp mode (sci -d) a timestamp consisting of the number of seconds since the epoch (JAN 1 1970 0:00:00 UTC) will be added to the record. If the program in in the loop mode (sci -l) the data fields are cleared, default information is entered into the fields, the cursor is placed in the first field, and the program is ready for more data input. If the program is not in the loop mode pressing the <Screen Key> will cause the data to be saved and sci will exit. In formatted input mode, if not enough numbers to the right of the decimal place are entered, the field will be padded after the decimal point with ASCII zeros ('0') to make up for the missing characters when the record is written to the output file. Sci is a multi-user program. In the event that sci becomes a zombied process, or the operating system crashes, (during a data write) it is possible that lock files may remain in the target directory. These files are named <template_name><hostname><processid> and have to be erased before sci can perform any ensuing writes.