Web Form API
Pass 2.00
*** The User's code must define the following functions: ***
Function: createForm
Calling Sequence: void createForm (int newForm);
Purpose: Create the form that is sent back over the Internet. When newForm =
NOT_NEW_FORM, the form fields are filled in before being sent over.
Arguments: newForm: A flag (NEW_FORM, NOT_NEW_FORM) telling if this form has
ever been displayed previously.
Function: evaluateForm
Calling Sequence: void evaluateForm (void);
Purpose: evaluateForm is called when a query or other data request has been
submitted. It causes an SQL statement to be executed, and causes the results
to be shown.
** The Common Code API consists of the following functions: ***
Function: main
Calling Sequence: int main (int argc, char **argv);
Purpose: This is the first function that is called from CGI. It calls
createForm () and evaluateForm (), which you must supply.
Function: informixEnv
Calling Sequence: int informixEnv (void);
Purpose: Initialise the environment for Informix. This is called from within
main () which is defined by the API.
Returns: Success / Failure
Function: htmlErrorMsg
Calling Sequence: void htmlErrorMsg (void);
Purpose: Prints message if fatal error occurred.
Function: paragraph
Calling Sequence: void paragraph (void);
Purpose: Issue the HTML to ensure a new line in the Web document.
Function: boldPrint
Calling Sequence: void boldPrint (char *msg);
Purpose: Print the passed message in bold print.
Arguments: msg: A pointer to the string that is to be printed in bold.
Function: htmlTitle
Calling Sequence: void htmlTitle (char *brTitle, char *backFile, char *iconFile,
char *pgTitle1, char *pgTitle2);
Purpose: Issue the HTML for the browser and page titles. Each page title prints
on a separate line.
Arguments: brTitle: Browser title. Appears at top of browser.
backFile: Graphics file containing the background. For future, look
into method to specify solid color only.
iconFile: An optional icon to be placed at the upper left.
pgTitle1: Page title. Appears centered at top of document.
pgTitle2: Page subtitle. Appears centered below page title. If not
needed, pass NULL for this argument.
Function: sectionTitle
Calling Sequence: void sectionTitle (char *title);
Purpose: Issue the HTML for the section title.
Arguments: title: Section title. Appears in a larger font than the rest of the
document.
Function: formBegin
Calling Sequence: void formBegin (void);
Purpose: Issue HTML to start a web form.
Function: formEnd
Calling Sequence: void formEnd (void);
Purpose: Issue HTML to end a web form.
Function: fillHidden
Calling Sequence: void fillHidden (char *name, char *textFill);
Purpose: Create a "hidden" GUI element. This can save information between CGI
invocations, such as record list information or application state info.
Arguments: name: Name of this hidden element. No spaces allowed.
textFill: The value of this hidden element.
Function: fillText
Calling Sequence: void fillText (int newForm, char *name, int size, int maxSize,
char *textFill);
Purpose: Create a text GUI element. If this is not the 1st time this form has
been displayed, fill in the element before displaying.
Arguments: newForm: A flag (NEW_FORM, NOT_NEW_FORM) telling if this form has
ever been displayed previously.
name: Name of this text element. No spaces allowed.
size: The size of the text element to be displayed, in characters.
maxSize: The largest number of characters the user is allowed to type.
If 0, there is no maximum.
textFill: The initial value of the text element. Only applies if
"newForm" is "NEW_FORM".
Function: fillPassword
Calling Sequence: void fillPassword (char *name, int size, int maxSize);
Purpose: Create a password GUI element. This element starts out blank, and
prints *'s no matter what the user types.
Arguments: name: Name of this text element. No spaces allowed.
size: The size of the text element to be displayed, in characters.
maxSize: The largest number of characters the user is allowed to type.
If 0, there is no maximum.
Function: fillTextArea
Calling Sequence: void fillTextArea (int newForm, char *name, int rows,
int cols, char *textFill);
Purpose: Create a text area GUI element. If this is not the 1st time this form
has been displayed, fill in the element before displaying.
Arguments: newForm: A flag (NEW_FORM, NOT_NEW_FORM) telling if this form has
ever been displayed previously.
name: Name of this text area element. No spaces allowed.
rows: The number of rows displaying in the text area element.
cols: The number of columns displaying in the text area element.
textFill: The initial value of the text element. Only applies if
"newForm" is "NEW_FORM".
Function: fillSelectBegin
Calling Sequence: void fillSelectBegin (char *name, int size);
Purpose: Create a select (list box) element. Note that the creation of a list
box involves 3 sets of calls: 1 fillSelectBegin, 0 or more fillSelectAdd, and
1 fillSelectEnd.
Arguments: name: Name of this list box element. No spaces allowed.
size: The number of items that the list box displays at once.
Function: fillSelectAdd
Calling Sequence: void fillSelectAdd (int newForm, char *textFill,
int selected);
Purpose: Add a selection to a list box, only if this is not a new form.
Arguments: newForm: A flag (NEW_FORM, NOT_NEW_FORM) telling if this form has
ever been displayed previously.
textFill: A value to be contained in the list box.
selected: Should this item be displayed as selected?
Function: fillSelectEnd
Calling Sequence: void fillSelectEnd (void);
Purpose: Finish creation of a select (list box) element.
Function: fillPopupBegin
Calling Sequence: void fillPopupBegin (char *name);
Purpose: Create a pop up menu element. Note that the creation of a pop up menu
involves 3 sets of calls: 1 fillPopupBegin, 0 or more fillPopupAdd, and
1 fillPopupEnd.
Arguments: name: Name of this pop up menu element. No spaces allowed.
Function: fillPopupAdd
Calling Sequence: void fillPopupAdd (int newForm, char *textFill);
Purpose: Add a selection to a pop up menu, only if this is not a new form.
Arguments: newForm: A flag (NEW_FORM, NOT_NEW_FORM) telling if this form has
ever been displayed previously.
textFill: A value to be contained in the pop up menu.
Function: fillPopupEnd
Calling Sequence: void fillPopupEnd (void);
Purpose: Finish creation of a pop up menu element.
Function: fillCheckbox
Calling Sequence: void fillCheckbox (int checked, char *name, char *title);
Purpose: Create a checkbox element.
Arguments: checked: Is this element pre-checked? (TRUE/FALSE)
name: Name of this checkbox element. No spaces allowed.
title: String identifying this checkbox on the document.
Function: fillRadiobutton
Calling Sequence: void fillRadiobutton (char *boxName, char *buttonLabel,
int def);
Purpose: Create a radio box button of a radio box element.
Arguments: boxName: Name of this radio box element. No spaces allowed.
buttonLabel: String identifying the individual radio button.
def: Is this radio button the default of the box?
Function: fillReset
Calling Sequence: void fillReset (char *name);
Purpose: Create a reset button element.
Arguments: name: Name of this reset button element. No spaces allowed. If
supplied as NULL, the name defaults to "Reset".
Function: fillButton
Calling Sequence: void fillButton (char *name);
Purpose: Create a generalized button element.
Arguments: name: Name of this button element. No spaces allowed. If supplied as
NULL, the name defaults to "SubmitQuery".
Function: fillQueryButton
Calling Sequence: void fillQueryButton (void);
Purpose: Create a Query button element.
Function: fillHelp
Calling Sequence: void fillHelp (char *name);
Purpose: Create an online "Help" link with the text "Help!!".
Arguments: name: Name of HTML file that contains the help for this form.
Function: traverseButtons
Calling Sequence: void traverseButtons (void);
Purpose: Create buttons used for traversing record lists.
Function: remainCount
Calling Sequence: void remainCount (char *table, int newForm);
Purpose: Display which record in the current list is being displayed.
Arguments: table: The name of the table that this call is about.
newForm: Is this call for a new or old (response) form?
Function: getCount
Calling Sequence: void getCount (char *table);
Purpose: Fetch the record information (which one, how many) from the submitted
form.
Arguments: table: The name of the table that this call is about.
Function: border
Calling Sequence: void border (void);
Purpose: Start definition of a bordered area.
Function: endBorder
Calling Sequence: void endBorder (void);
Purpose: End definition of a bordered area.
Function: traverseOn
Calling Sequence: int traverseOn (void);
Purpose: Detects if one of the traverse buttons was pressed.
Returns: Which traversal button was pressed, if any.
Function: traverseList
Calling Sequence: int traverseList (int buttonNum, char *table, ...);
Purpose: Traverse the active list of records (the result of a query).
Arguments: buttonNum: Integer identifying pressed traversal button.
table: What table list are we traversing?
...: List of additional arguments passed onto "fetch". They are:
field list:
fieldPtr: Pointer to area receiving field value. NULL indicates
end of the field list.
fieldName: Name of the field. Does not appear after NULL.
orderBy: Comma-separated list of fields to perform ordering by.
Example: traverseList (1, "aspec", aspecPara, "aspec_para", aspecShall,
"aspec_shall", NULL, "aspec_para, aspec_shall");
Returns: Failure / Success of called "fetch" (see entry for "fetch")
Function: initSqlTable
Calling Sequence: void initSqlTable (char *table);
Purpose: Initialize the view assocviated with the specified table.
Arguments: table: name of an Informix table or view.
Function: queryTable
Calling Sequence: void queryTable (char *table, char *linkTable, char *fields,
...);
Purpose: Query an Informix table, putting results in a temp view.
Arguments: table: name of an Informix table or view.
linkTable: Table that is linked to.
fields: Fields to include in the temp view.
...: List of additional field arguments. They are:
field list:
fieldName: Name of the field. NULL indicates end of the field
list.
fieldType: Type of the field. LINK indicates how 2 tables are
linked. Uses fieldVal literally. SQLxxx indicates the field
type in the database. Does not appear after NULL.
fieldVal: Value of the field to look for. This is of type char*
if fieldType is LINK, otherwise, the type is t_cgi_entry*.
The wild cards "*" and ":" are recognized. Does not appear
after NULL.
Example: queryTable ("aspec_build", "aspec", "aspec_seq, imple_build",
"aspec_seq", LINK, "aspec.aspec_seq", "imple_build", SQLCHAR, impleBuildOne,
NULL);
Function: fetch
Calling Sequence: void fetch (char *table, int whichRecord, ...);
Purpose: fetch gets the specified record from the current list.
Arguments: table: name of an Informix table or view.
whichRecord: Which record to get. Record numbering is 1-based.
...: List of additional arguments. They are:
field list:
fieldPtr: Pointer to area receiving field value. NULL indicates
end of the field list.
fieldName: Name of the field. Does not appear after NULL.
orderBy: Comma-separated list of fields to perform ordering by.
Example: fetch ("aspec", 17, aspecPara, "aspec_para", aspecShall,
"aspec_shall", NULL, "aspec_para, aspec_shall");
Returns: Success / Failure
Function: queryFloat
Calling Sequence: t_cgi_entry *queryFloat (float flNum);
Purpose: Translate a float into CGI entry format.
Arguments: flNum: the number to translate.
Returns: Pointer to CGI entry containing the Float.
Function: queryDouble
Calling Sequence: t_cgi_entry *queryDouble (double dblNum);
Purpose: Translate a double into CGI entry format.
Arguments: dblNum: the number to translate.
Returns: Pointer to CGI entry containing the Double.
Function: queryShort
Calling Sequence: t_cgi_entry *queryShort (short shNum);
Purpose: Translate a short into CGI entry format.
Arguments: shNum: the number to translate.
Returns: Pointer to CGI entry containing the Short.
Function: queryInt
Calling Sequence: t_cgi_entry *queryInt (int intNum);
Purpose: Translate a integer into CGI entry format.
Arguments: intNum: the number to translate.
Returns: Pointer to CGI entry containing the Int.
Function: clearList
Calling Sequence: void clearList (void);
Purpose: Reset the database list to empty, reset the counters.
Function: wordWrap
Calling Sequence: void wordWrap (char *str, int maxLength);
Purpose: Break a string into displayable "lines", according to max line length
passed.
Arguments: str: The string to break up.
maxLength: Longest possible length of a line.
Function: unWordWrap
Calling Sequence: void unWordWrap (char *str);
Purpose: Merge the logical lines of a field into one long string.
Arguments: str: The string to merge. All lines are separated by the newline
character.
Function: hashName
Calling Sequence: char *hashName (char *table, char *user);
Purpose: Create a unique name for a "temporary view" that incorporates the
original table name and the UNIX user name.
Arguments: table: The name of the table.
user: The UNIX user name.
Returns: The created hash name. These names start with "tv" and have 1-8
hexadecimal digits (0-9, a-f) appended. This is the name of the "temporary
view".
Explanation: A "temporary view" is one that is meaningless outside of the
context of these Web forms. When a query needs to be made to the database,
a view is created that incorporates the query. This is done because a Web
form session will almost always cause more than one invocation of the form
(each invocation is caused by pressing one of the buttons on the form);
"temporary view"s cause the result of a query to be available to all such
invocations. A "temporary view"s life ends when the same user performs
another query on the same table, thus re-creating the "temporary view"...
Function: spaceFill
Calling Sequence: void spaceFill (char *string, int howLong);
Purpose: Fill a "C" string with spaces to make it 100% compatible with a
database CHAR field.
Arguments: string: The "C" string to be filled.
howLong: The size of the database CHAR field (i.e., CHAR (howlong) ).
Function: add
Calling Sequence: int add (char *table, ...);
Purpose: Add a record to a table.
Arguments: table: name of an Informix table or view.
...: List of additional field arguments. They are:
field list:
fieldName: Name of the field. NULL indicates end of the field
list.
fieldType: Type of the field. SQLxxx indicates the field
type in the database. Does not appear after NULL.
fieldVal: Value of the field to look for. This is of type
t_cgi_entry*. Does not appear after NULL.
Example: add ("aspec_build", "aspec_seq", SQLINT, aspecSeq",
"imple_build", SQLCHAR, impleBuildOne, NULL);
Returns: Success / Failure
Function: removeRec
Calling Sequence: int removeRec (char *table, ...);
Purpose: Remove one or more records from a table.
Arguments: table: name of an Informix table or view.
...: List of additional field arguments. They are:
field list:
fieldName: Name of the field. NULL indicates end of the field
list.
fieldType: Type of the field. LINK indicates how 2 tables are
linked. Uses fieldVal literally. SQLxxx indicates the field
type in the database. Does not appear after NULL.
fieldVal: Value of the field to look for. This is of type char*
if fieldType is LINK, otherwise, the type is t_cgi_entry*.
The wild cards "*" and ":" are recognized. Does not appear
after NULL.
Example: removeRec ("aspec_build", "aspec_seq", LINK, "aspec.aspec_seq",
"imple_build", SQLCHAR, impleBuildOne, NULL);
Returns: Success / Failure
Function: updateRec
Calling Sequence: int updateRec (char *table, int recNum, ...);
Purpose: Update a record in a table.
Arguments: table: name of an Informix table or view.
recNum: Which record in the current list to update.
...: List of additional field arguments. They are:
field list:
fieldName: Name of the field. NULL indicates end of the field
list.
fieldVal: Value of the updated field. This is of type
t_cgi_entry*. Does not appear after NULL.
Example: updateRec ("aspec_build", "imple_build", impleBuildOne, NULL);
Returns: Success / Failure