----------------------------------------------------------------------------
README:  UCO Forms

CURRENT REV: VERSION

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

This is a forms design/deployment toolset based in Sybase and Tcl.
To use it, you need

	Sybase SQL Server v 4.9.1 or later
	OpenClient library for your host
	Tcl, Tk, TclX, and sybtcl, linked against the OpenClient lib
	... and some free time :-)
	The latest version of fosql assumes tk4.1 and tcl7.5.

This tool is not as simple as wisql!  The installation process is
trickier, and I am assuming that you are a Sybase dba, dbo, or
similar well-qualified Sybase tinkerer.  You will have to understand
such Sybase concepts as triggers, keying, joins, bcp dataload, etc.  

If you do not understand these things, STOP right here.  This is *not* a 
friendly toy for the unwary.  It is a tool for confident Sybase developers.

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

WHAT IT DOES;  SOME LIMITATIONS

The purpose of this toolkit is to give you a relatively Q/D way to
design forms for users to use for data entry/update/browse.  The nice
part about this toolset is that you can see the form, exercise the form
and edit the form all at the same time.  In other words, developer mode
works simultaneously with user mode.  One basic core procedure-set 
does all the forms painting for any form.  You can add your own
custom code to this core, see below.

In order to make this toolkit robust, I have had to establish some 
rules for the backend data.

1) all tables in a forms application must have primary keys properly
   set.
2) if you want to use the provided "generic" insert/update/delete/display
   code, your tables must be well normalized so that auto-joining really
   works.  more on this later.
3) only basic datatypes are supported.  No user-defined or bit-oriented
   datatypes (blobs, bitfields, etc) are supported.  If you use user-defined
   datatypes then you'll have to hack in site-specific support for them.

If your backend data (the stuff you want to use forms on) doesn't conform
to these rules, then you're on your own.

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

HOW IT WORKS:

The basic concept is that a set of tables (definitions provided) define
the look of a form.  To paint the form, a general-purpose application
runs against the defining tables, snarfs up the information on how
to paint the form and what to do when the user pushes button X, and
goes ahead and does it.  You can write your own custom code to be
executed on user actions such as button press... or if your app is
real simple, as most of them are, you can use the "generic" routines
provided (Insert, Update, Delete).

The forms painter can paint several types of widget on to the form.
Each widget is represented by one record in the table 'forms'.
I'm using widget rather loosely here, as some of these entities can
consist of 2 actual X widgets.

	EN -- entry widget, consists of a text label (tells the user what
		they're entering) and a box to put the entered data in or
		to display existing data.  One label, one entry.  You
		control their fonts, sizes, relative positions etc.

	DA -- just like an entry widget but the user cannot change it.
		One label, one entry configured -state disabled
		same editability

	TX -- just like an entry, except for big varchars:  puts a text
		widget rather than an entry.  One label, one text.
		same editability

	LA -- just a label

	ME -- just a message

	BT -- a button

	RB -- a radiobutton

	CB -- a checkbutton

	PS -- PseudoSQL, a button that executes SQL code some of which is
	      composed of references to values displayed in the form;  the
	      output is directed to a particular widget or widgets in the
	      form.

	LB -- a listbox widget for displaying multiple values as a list

	GN -- not really a widget, a General Form description record.

You position these toys on the form using relative x and y placing,
editing their characteristics with popup dialog boxes, and Commiting
your changes to the underlying table 'forms'.  When you are all done,
you have a working form that a user can use.  If you are smart, you
make a deployment version that does not permit the developer-mode
actions.  The 'mode' global var will take care of this for you.

The characteristics you can edit for each widget are defined in the
table fwidgets.  take a look at that table for some insights.

All this fancy editing and whatnot is done with various modified mouse
clicks.  Users' Guide is in a separate doc.

Extra value-added features:

Help: This is a wisql-family product, so of course balloon help is 
	implemented.  Control-Click for balloon help.

Data Dictionary support:  table def AND FORM included
	This permits data entry person to look up the meaning of a field
	in a data dictionary maintained by YOU the developer.  As in
	"Endd:  Termination date:  the date the employee's severance 
	action was completed and filed."  See the dictionary table and
	notes for more info.  See the global vars in 'form'.
	Control-Double-Click for data dictionary help

Code Lookup support:  for those repetitive code values that key entry
	personnel are always having to look up in little paper pamphlets,
	the forms app supports looking those up via Sybase tables and
	entering the desired code value with a double-click.  This is
	for the situation where your personnel, for example, are divided
	into categories by a 2-character code.  The codes and the categories
	they represent can be displayed to the data entry person, who
	can choose the right one easily.
	Double click on entry widget for code lookup help.  I'm leaving it
	to you to decide how you want to indicate visually that this
	feature is in fact hiding beind a certain entry widget.  different
	font?  asterisks?  it's your decision.

Field Linking:  the forms editor permits you to link sets of widgets.
 	for example, if you link a set of entry and text widgets, you
	will get a default binding on forms load that permits traversal
	of those widgets *in the order you linked them* by means of
	Return and Tab.  If you link a list of listboxes you can make
	them the recipients of multiple return records from a SQL operation.
	see the popList procedure for the nitty-gritty details.
	
----------------------------------------------------------------------------

INSTALLATION STEPS:

Before you start you will have to 

	pick a database where you have full object create privs, 

	make sure select into/bulkcopy is enabled there, 

	READ the forms.sql script!

	edit the forms.sql script appropriately

	run (use isql) the forms.sql script

	use bcp to load in the file fwidgets.FLAT -- script provided, but
		you must edit it as indicated

	and then you can play.

edit the tcl source file 'form' to load the tlib from the right place
and to find the tcl executable in the right place.  Edit it some more
to fix the global variables the way you want them.  they are all
commented.  Make sure to set "base" appropriately.

Now try to run form as whichever user has the right privs to modify those
tables you just built.  Run form by typing 

	form -x SYBASE_LOGIN_NAME

You should get a wisql-style sign-on widget.  Sign on.

You should then get a drab little widget with some text and a couple
of buttons -- Forms, New, and Quit.  You want New.

New should pop up a dialog box with some fields for you to fill out.

Start filling out fields.  Use ctrl-click for help.

Commit your level 0 form.  Quit.

Restart the tool.  You can now see your application name from the
level 0 you just created in the Forms menu.  Right?

Choose it.

You can now start putting widgets into your form.  If you got this far,
the software should all be working, but let's check:

in the blank area of your new form, Shift-Control-Mouse2.

You should get a "Define New Widget" popup, inviting you to pick
a type and name and all like that.  Make it a type EN and hit
Return in the type entry box.  Use control-click for help.

The new widget popup should get larger and show you all the characteristics
you can set for a widget of that type.  Now you know that you installed 
things right.  Now it's time to read the manual.  Please, please, read it.

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

Rollup release 1.0.5 had a lot more in it than just the tlibDoc feature.

It introduced several new features and internal rules:

	All SQL (in fassists and PS) is now pseudoSQL and can include
	references to widget names

	The echo field can be used in a form GN record to store the fid
	of a button to execute at startup of that form

	DA's can be set with default values:  if so, they are NOT cleared
	when a form is cleared.  They are also not cleared if they are
	echoes of a widget on a parent form.

	It is now possible to do auxiliary joins on one form (not merely
	1-to-1 Pkey joins).  You can do a 1-M where the 1, obviously, is
	in the aux table:  as on a PO where there is exactly one vendor
	per PO, but the alias is not the Pkey of the header (PO header),
	only of the vendor.  The entry widget has to be associated, at
	this release, with the master form.  It then must be ECHOED to
	a DA widget for the aux table.  This restriction will probably
	be overcome later, but for now the echo mechanism is the only
	way to link the two *independent of underlying nomenclature*
	(in other words, you can join on fields of unlike name but
	identical meaning).  Everything else comes naturally.

	PSQL processing has been improved a lot; pseudoSQL is now 
	insensitive to spaces.

	General Find is now implemented, wherein all text fields are 
	compared using "like value%" so that the user can enter partial
	initial values and get a Find list of matching records.  This
	limits the use of assistLists to the places they were designed
	for, and is more intuitive.

	the tlibDoc feature itself shows up as a new button in Expert Mode
	only, labeled Docu.  the help message pretty much says it all:  it
	will generate a "spec sheet" for the code.  It's a little hokey but
	works all right.

