cgiaction files

cgiaction files
	Chapter 4. Various BillMax files

Name

cgiaction files — Input for the cgiaction table

DESCRIPTION

This describes the input files for the cgiaction table, the HTML template files and their relationship to each other. The cgiaction table is used by ua.cgi to decide what processing to do when a CSR submits a web form from the staff interface. The cgiaction table and templates work together to:

Display a web page.
Accept data from a web form.
Execute BillMax programs on behalf of the CSR.

A cgiaction file is made up of a series entries. A cgiaction file must be formatted in the following manner:

Comments may be inserted using a "#" as the first non-whitespace character on a line.
Each entry begins with catID,qualifier at the beginning of a line. No whitespace is allowed before catID,qualifier.
Non-comment, non-blank lines following catID,qualifier entry that are associated with the entry must begin with a whitespace.
Each entry ends when another entry begins or when the end of the cgiaction file is reached.
Blank lines are permissible.

The cgiaction files are located in /usr/local/billmax/cfg/cgiaction. The extension for the cgiaction files is ".cat". The cgiaction table is populated with data from cgiaction files using the mkca program.

Each execution of ua.cgi MUST include the CGI variable FORM. The FORM variable specifies which catID entries in the cgiaction table to use. ua.cgi will process an HTML template file to display a web page in a web browser if one of the following conditions is met:

ua.cgi is executing without the CGI variable action.
ua.cgi is executing with the CGI variable action, but there are no directives in a cgiaction file instructing ua.cgi to execute a new process.
ua.cgi is executing with the CGI variable action, there are directives in a cgiaction file instructing ua.cgi to execute a new process, but due to conditional processing, the new process is not executed.

Otherwise, ua.cgi will do input form processing.

ua.cgi replaces the following tags while processing a template:

##Ifilename# - ua.cgi reads the contents of filename and include them as the page is sent to the browser. The contents of filename may not include a ##I directive.
##Ftagname# (##F tag) - ua.cgi use directives from the cgiaction table to determine the substitution for ##Ftagname#. The cgiaction entry to use is identified by catID,qualifier. The value of the FORM variable is used for a catID and tagname is used for qualifier.
@TEST( 'arg1', 'arg2', 'True Response', 'False Response') - A basic IF..THEN..ELSE construct. A string comparison is done between arg1 and arg2. If they are equal, True Response is used, otherwise False Response is used. Quoting the parameters is optional, but recommended. All four arguments are required. but NULL arguments are allowed. "\" may be used to escape single quotes, commas and parentheses within an argument.

	Important
	##F tags are substituted before the @TEST directives are evaluated. Care must be taken that the substitution for a ##F tag does not create an invalid @TEST.

Within the cgiaction file, there is not a clear distinction between a template and a CGI form. In general, there is a one-to-one correspondence between a template and a form. However, there may be more than one form in a template, and there may be catID entries that have no corresponding template. ua.cgi may use the CGI variable FORM to determine the template to process, but there is no requirement that the template include a CGI form or include the CGI variable FORM. For ease of management, it is recommended that each cgiaction file contain information for a single template and/or form. Currently there is one cgiaction file for each template in /usr/local/billmax/uatemplates.

When processing a template for display, ua.cgi uses the value of FORM for catID. ua.cgi then processes the template /usr/local/billmax/uatemplates/catID.tmp. When ua.cgi encounters a ##Ftagname# construct, it uses FORM value,tagname for catID,qualifier to determine the substitution for the ##F tag.

When processing a CGI form for input, ua.cgi uses the value of FORM for catID. ua.cgi then uses catID to select the cgiaction entries that instruct what to do when a form is submitted. The variables names from the form are mapped to the qualifiers associated with the catID as well as the ##Dvariable name# constructs (##D tag). Whereas every ##F tag in a template must have a cgiaction entry, not every form variable need have a cgiaction entry. If the form variable is simply an intermediate value for processing, the value of the variable may be access by a ##D tag in the cgiaction file.

As previously mentioned, qualifier may map to a ##F tag, a form variable, or both. In addition, qualifier may also be one of the three required cgiaction keywords:

authlevel The numeric values specified are interpreted as a bitmask. This is compared to the Permissions from the Authorized BillMax User and any intersection will suffice.
1. The auth keyword specifies what Permissions are needed to process and display the catID template.
2. The b1..b31 keywords define the Permissions needed to execute ua.cgi with a specific FORM action combination.
buttons - Maps the CGI form variable action to a button number. Every value for action must be included in this cgiaction entry and be mapped to a distinct button number. There may be at most 31 different values for action for a given catID.
directaction - Given a button number derived from action, what processes should be executed, it any. If no direct action is specified for a button, then ua.cgi will display the template as indicated by catID as specified by the value of FORM.

Each cgiaction entry that maps to an ##F tag or form variable or both may have one or more of the following lines:

defval

Used when displaying a template. Indicates what the default value should be for a ##F tag if the CGI variable action was not supplied.

type

Used when displaying a template and, in some cases, when validating the value of a form variable on input. Valid values for type are:

MULTIROW
DATE
FLOAT
LIT
BITMASK
MBITMASK
MULTIPLE
MONEY
EDATE
EHDATE
ETIME
EHTIME
CURRENCY
LOCALE

template

Used when type is MULTIROW. The template is a printf format with "%s" used as variable placeholders for multiple columns of output data. At most 20 "%s"s may be specified.

multitype

May be used when template is specified. Any of the type keywords (except MULTIROW) may be used. Expressed as a comma delimited list. Must have an entry for each "%s" specified in the template. A NULL entry for a "%s" is valid.

constraints

Used when a form is submitted. Using regular expressions or macros from the regexmacros list, the value of the form variable is checked to see that it satisfies the specified constraint.

A cgiaction file uses a meta-language of its own, some of which has already been presented. There are many different keywords and some symbolism. Understanding these are a key to understanding a cgiaction file. These will be listed here and their use will also be demonstrated in the examples that follow.

cgiaction meta-language

\

The line continuation character. It must be followed by a newline character.

&&

Used to cause the serial execution of processes. The previous process must succeed for the subsequent process to be executed.

@TEST( 'arg1', 'arg2', 'True Response', 'False Response')

A basic IF..THEN..ELSE construct. A string comparison is done between arg1 and arg2. If they are equal, True Response is used, otherwise False Response is used. Quoting the parameters is optional, but recommended. All four arguments are required. but NULL arguments are allowed. "\" may be used to escape single quotes, commas and parentheses within an argument.

	Important
	##D tags are substituted before the @TEST directives are evaluated. Care must be taken that the substitution for a ##F tag does not create an invalid @TEST.

REDIRECT::web server location

ua.cgi redirects processing to web server location. This may be another CGI, an HTML page, etc.

EXEC(program)

Executes program. Output from program is passed directly to browser. Causes ua.cgi to exit upon completion of program.

EXTERN(program)

Executes program. Output from program is NOT passed directly to the browser. In general, output from EXTERN is interpreted by ua.cgi. If used with a button, must output a "Location" server directive or be followed by another process by using &&. May be used for a replacing a ##F tag on display.

VOID

Used to direct ua.cgi to default to using the just submitted form variables to display a template. Currently used within the directaction section as an argument to @TESTs. When the value of action is "SEARCH" and the CGI variable scol is not also supplied, the @TEST results in VOID rather than executing a new process.

SQL::sqlstatement

Executes sqlstatement against the database.

ESC

Used when interpreting a form variable for substituting a ##D tag. Interpret the form variables as simple text.

##D(ESC)number#

ESCU

Used when interpreting a form variable for substituting a ##D tag. Will cause URL escaping on the value. Used in conjunction with the REDIRECT tag to make sure the URL used by the REDIRECT is appropriately formatted.

##D(ESCU)number#

ESCQ

Used when interpreting a form variable for substituting a ##D tag. Given a string of characters, will insert "\" before a double-quote character or a "\" character.

If form variable var1 is asd\df"qwe, then the substitution for ##D(ESCQ)var1# will be asd\\df\"qwe.

MULTIROW

Used on output. Multiple rows of data will be output. Use with type or multitype.

DATE

Used on output. Display the data as a date. Use with type or multitype.

FLOAT

Used on output and input. Display the data as a floating point value. On input, validate that a valid floating point value was submitted. Use with type, multitype, or a ##D tag.

LIT

Used on output. Display the data as is with no escaping. This is useful if the original data contains HTML. Use with type, multitype, or a ##D tag.

BITMASK

Used on output and input. Data is displayed as a series of checkboxes. Input datum are AND'd together to create a bitmask.

MBITMASK

Used on output and input. Data is displayed as a multi-select field. Input datum are AND'd together to create a bitmask. Use with type, multitype, or a ##D tag.

MULTIPLE

Used on input. Multiple values for one form variable are not treated as a bitmask but are made into a comma delimited string. Use with type, multitype, or a ##D tag.

MONEY

Used on output and input. Display the data as money without currency symbolization. Used when displaying money in an input field. When the input field is submitted, validate that the data submitted is money. Use with type, multitype, or a ##D tag.

EDATE, EHDATE

Used on output and input. Display the data as a date, but separating the year, month and day parts into separate form variables named formvar_year, formvar_month and formvar_day. EHDATE uses hidden variables on display. On input, validate each form variable exists and that the combination results in a valid date.

ETIME, EHTIME

Used on output and input. Display the data as a time, but separating the hours, minutes and seconds parts into separate form variables formvar_hour, formvar_minute and formvar_second. EHTIME uses hidden variables on display. On input, validate each form variable exists and that the combination results in a valid time. Use with type, multitype, or a ##D tag.

CURRENCY

Used on output. Display the data as currency. Use with type, multitype.

REMOTE_ID

The auth.number of the Authorized BillMax User submitting the CGI. Access using a ##D tag such as ##DREMOTE_ID#.

REMOTE_USER

The auth.user of the Authorized BillMax User submitting the CGI. Access using a ##D tag such as ##DREMOTE_USER#.

BILLMAXDIR

The directory in which BillMax is installed. Always /usr/local/billmax. Access using a ##D tag such as ##DBILLMAXDIR#.

CURRENTDATE

The current date as reported by BillMax. May not be the current date if BillMax is in test mode. Access using a ##D tag such as ##DCURRENTDATE#.

CURRENTTIME

The current time as reported by BillMax. May not be the current time if BillMax is in test mode. Access using a ##D tag such as ##DCURRENTTIME#.

LOCALE

Used on input. Validate the submitted value is a locale supported by the underlying operating system. Access using a ##D tag such as ##DLOCALE#. Use with type or a ##D tag.

ROWID

The id of the last row inserted. Access using a ##D tag such as ##DROWID#.

CRYPT, INDIRECT

Obsolete.

cgiaction and HTML template examples

The following examples are partial listings of a generic cgiaction file and the corresponding syntax for an HTML template file. In these examples, the catID and the FORM variable will be "form1" and the template file is "form1.tmp"

Example 4.2. Basic template/cgiaction example

	template file contents:
	<HTML>
	<HEAD>
	##Icalendar.js#
	<SCRIPT language="JavaScript">
	function VerifyData(btn) { (1)
		document.forms[0].action.value=btn.value;
		document.forms[0].submit();
	}
	</SCRIPT>
	</HEAD>
	<BODY>
	<FORM name="Form" action="/cgi-bin/ua.cgi" method=POST> (2)
		<input type=hidden name="FORM"		value="form1"> (3)
		<input type=hidden name="action"		value=""> (4)
		<input name="number"		value="##Fnumber#"> (5)
		<input type=button value="SEARCH" onClick="VerifyData(this);"> (1) (6)
		<input type=button value="SAVE" onClick="VerifyData(this);"> (7)
		<input type=button value="EXAMPLE" onClick="VerifyData(this);">
	</FORM>
	</BODY>
	</HTML>
			

	cgiaction file contents:
	form1,authlevel
		auth:1  (8)
		b1:1 (6)  
		b2:2 (7)
		b3:1
	form1,buttons
		b1:SEARCH (6)
		b2:SAVE (7)
		b3:EXAMPLE 
	form1,directaction
		b1:VOID (6)
		b2:EXEC(##DBILLMAXDIR#/cgi-bin/enter_account.cgi)  (7)
	form1,number (9)
		defval:
		b1:##Dnumber#
		b3:Irrational Number

(1)	A common technique used in BillMax templates. A JavaScript function VerifyData sets the `action` to value of the button clicked. Code may be added to do data validation.
(2)	Defines a CGI form that will be processed by ua.cgi. Required if you want to submit a CGI form that is processed by ua.cgi.
(3)	The CGI form must have the form variable named `FORM`. In this case, `FORM` is set to "form1". This directs ua.cgi to used the cgiaction entries with catID "form1".
(4)	The CGI form most likely will have the form variable named `action`. A common technique is for this to be blank when the Web page loads, and then set it using code.
(5)	`number` is a common variable in a BillMax CGI form. This is usually a database identifier for the data being displayed on a web page. Also an example of a ##F tag.
(6)	The HTML button "SEARCH" is mapped to button `b1`. Variable `action` with a value of "SEARCH" may be submitted by a Authorized BillMax User that has BASIC READ Permission. The `VOID` causes the template to be displayed using the form variables passed. In this example, the `b1` entry for form1,number will be used. Note that specifying "b1:VOID" is the same as not specifying an entry for `b1`, as is the case for `b3`.
(7)	The HTML button "SAVE" is mapped to `b2`. Variable `action` with a value of "SAVE" may be submitted by a Authorized BillMax User that has BASIC Write Permission. The `EXEC` will cause ua.cgi to execute a enter_account.cgi.The output from enter_account.cgi will be passed directly to the web server without any further processing by ua.cgi.
(8)	The Permissions needed to view the form. The Authorized BillMax User must have permission BASIC READ to view the form.
(9)	If no `action` variable is supplied, then the valueless `defval` keyword causes an empty string substitution for the value of ##Fnumber#. If the value of `action` is "SEARCH", then the value of the form variable `number` is substituted for ##Fnumber# when the template is processed. If the value of `action` is "EXAMPLE", then string "Irrational Number" is substituted for ##Fnumber# when the template is processed.

Example 4.3. Tying a database field to a BillMax List

Assume a BillMax list called "holidays". Each account will have one holiday specified in which they will get an email greeting. It is desired that the date of the holiday be stored in the account record. This example shows how to capture the date of the holiday. In does not show how to use the date in sending the email greeting.

In this example, an account record consists of the fields number and misc11. There are three entries in the "holidays" list:

value	description
0000-00-00	No Holiday Specified
2003-12-25	Christmas
2003-11-27	Thanksgiving

The following template and cgiaction entries will have the desired effect.

	template file contents:
	<HTML>
	<HEAD>
	##Icalendar.js#
	<SCRIPT language="JavaScript">
	function VerifyData(btn) {
		document.forms[0].action.value=btn.value;
		document.forms[0].submit();
	}
	</SCRIPT>
	</HEAD>
	<BODY>
	<FORM name="Form" action="/cgi-bin/ua.cgi" method=POST> 
		<input type=hidden name="FORM"		value="form1"> 
		<input type=hidden name="action"		value=""> 
		<input name="number"		value="##Fnumber#"> 
		<select name="holidays"> (1)
	##Fholidays#
		<select>
		<input type=button value="SEARCH" onClick="VerifyData(this);"> 
		<input type=button value="SAVE" onClick="VerifyData(this);"> 
	</FORM>
	</BODY>
	</HTML>
			

	cgiaction file contents:
	form1,authlevel
		auth:1 
		b1:1 
		b2:2 
	form1,buttons
		b1:SEARCH
		b2:SAVE
	form1,directaction
		b2:SQL::UPDATE account SET misc11=##Dholidays# WHERE \
			number=##D(ESC)number&&\ (2)
			REDIRECT::/cgi-bin/ua.cgi?FORM=account&number=##D(ESCU)number#  (3)
	form1,number 
		defval:
		b1:##Dnumber# 
	form1,holidays 
		type:MULTIROW (4)
		template:\t<option value="%s" %s>%s-%s</option>\n (5)
		multitype:,,,DATE (6)
		constraints:^[[:nulldate:]]$ (7)
		defval:SQL::SELECT value,IF(lists.value='0000-00-00','SELECTED',''),\ (8)
			descr,value FROM lists WHERE list='holidays' \
			ORDER BY sortorder
		b1:SQL::SELECT lists.value,\ (9)
			IF(lists.value=account.misc11,'SELECTED',''),\ 		
			lists.descr,list.value FROM lists,account WHERE list='holidays' AND \
			account.number='##D(ESC)number#' ORDER BY lists.sortorder,lists.descr

(1)	An HTML options list. Substitutions for ##Fholidays# will populate the list.
(2)	Example of using `SQL`. When the `action` value is "SAVE", the SQL will be executed updating the misc11 field of the account record identified by value for `number`. If the SQL command is successful, the "&&" causes the execution of the `REDIRECT`.
(3)	An example of a `REDIRECT`. In this case, ua.cgi will be executed again in a template display mode.
(4)	Example of using `MULTIROW` for `type`
(5)	Because `type` is `MULTIROW`, `template` must be specified. There are 4 "%s"s in the template line indicating that there should be four data elements per row returned by `defval` and `b1`.
(6)	A multitype line is included to format the display of the date. The first 3 columns for each row have no special formatting. The fourth column will format the value of the list according the BillMax globalconf.dateformat specification.
(7)	When a selection is chosen and the form submitted, the value of `holidays` will be checked against the regular expression macro [[:nulldate:]] to make sure the data submitted is valid.
(8)	The `defval` entry creates the HTML for the options list and displays all available holidays list entries. Note that the NULLDATE is selected in the HTML by default. Also note that 4 columns of data are return per row of data.
(9)	The `b1` does the same as `defval` but will select in HTML the list value that was stored in the database.


	BillMax Billing Solutions 877.245.5629 sales@billmax.com


ccsoft.conf		dbschema