Node:Application definition file syntax, Next:Key bindings, Previous:Modes of deployment, Up:Top

Application definition file syntax

This tries to describe the syntax that must be used to write the application definition file. Parser for the file is done in yacc and greedy souls¹ willing to know everything might want to have a look at file kortparser.y and kortelements.lex to find out what really happens.

The file is line-oriented e.g. one thingie is one line in the file, line ends when \n is found. Reason for this is TCL as TCL really seems to be a line-oriented programming language where one line of code is one statement or something alike and as TCL may be included in the same file, we must be able to pass the endlines

In file, rows beginning with # are comments and silently ignored.

Beginning from kort version 0.0.3 the application definition file needs to be in UTF-8 encoding. If you're using english language only and expressing your things in US7ASCII only then you don't need to care about this but for the rest of us this is important: trying to use ISO8859-1 or any other "codepage" won't do any more and if you have had an application written for kort that has international characters in it then you need to convert the file to UTF-8 unicode before you can use it. I have not tried using UTF-8 in table or column or field names and I'm almost sure that it will not work so please keep them in US7ASCII. For label contents and TCL scripts UTF-8 is very ok and should work. And remember to set UTF-8 locale before using kort :)

The file always begins with record definition (or comment). More record definitions (or comments) may follow but at least one is required (not a comment). Record definition begins with word RECORD that must be typed in UPPER CASE, followed by record name, that is Case SeNsitive when referenced. Record name is followed be word DBTABLE or word NOTSAVED. Word DBTABLE must be followed by database table name where this record will be saved. Database table name may be followed by word JOINS meaning that this record is a subrecord of some other record. Name of the master record must follow. Examples might be like these:

RECORD not_a_saved_record NOTSAVED
RECORD kew1_stuff DBTABLE kew1_table
RECORD subkew1_stuff DBTABLE subkewl_table JOINS kew1_stuff

Record definition continues with function key command definitions for the defined record. List is newline separated. Entries in the list are generally of form

FUNCTION_KEY x command label

where x is number of function key, command is the thing to do and label is a "quoted" string to display in bottom line of the terminal for guidance to user. Possible commands are the following:

SAVERECORD causes the record to be saved when user hits Fx. Label may be followed by optional word BUTASKFIRST that presents user with a yes-no -question first.
SAVERECORDANDEXIT is like SAVERECORD but causes kort to exit after save.
DELETERECORD causes the current record and all subrecords and recursively subsubrecords etc. to be deleted from the database. May be given the BUTASKFIRST option.
RETRIEVERECORD causes the current record to be re-loaded from database.
SAVERECORDASNEW causes the current record to be given a new surrogate and inserted to database as new record. This command may be given BUTASKFIRST option.
SAVERECORDASNEWANDEXIT is like SAVERECORDASNEW but it causes kort to exit after save is complete.
SELECTANOTHERRECORD selects a current record the record that has the same value in database table column that user has typed to current field. Current field is the field where cursor is blinking² and value of this field is compared to values in the database in the table where current record is saved in the column where current field is saved. the record that has value that begins with text that user has typed is selected. If several records match, user is presented with a list of values from the current column and is forced to choose one value from the list. The record with the selected value is loaded to kort for viewing and/or editing.
EXITRECORD causes kort to exit. No questions asked.
MOVETO RECORD is a command with different syntax. Command MOVETO RECORD is followed by a valid record name. When command is selected by user, the current record is left and the named record is selected as the current record and displayed to user. Here is an example
```
FUNCTION_KEY 5 MOVETE RECORD FooRecord "FooData"
```
that causes F5 to be given label "FooData" and when hit, transfers focus to record FooRecord that must be defined in the same application definition file.

These pre-defined commands may be followed by function key definitions that invoke TCL code. Example of such a definition is here:

SCRIPT_BEGIN FUNCTION_KEY 6 "Calc"
 set answer [ expr $a_number + $another_number ]
SCRIPT_END

Where between lines SCRIPT_BEGIN and SCRIPT_END is the code. SCRIPT_BEGIN is always followed by event when the code is run. In this example the event is user hitting F6. F6 is here given label "Calc". The actual code given to TCL interpreter is one line

 set answer [ expr $a_number + $another_number ]

that makes sense if there are fields in the current record with names answer, a_number and another_number as before program is given to interpreter, each field in the current record is defined as a variable in TCL interpreter with value being the current value from the field. After TCL commands are done the same variable names are searched from the interpreter and if found, values assigned back to current record. Possible events for TCL code to get executed when code relates to a record are the following:

FUNCTION_KEY x "Label" causes function key x to be labeled "Label" and associated TCL code to be done when Fx is hit by user.
ONENTER causes TCL code to be given to interpreter when user navigates to record that has ONENTER TCL code. "Navigates" here means that user first views some record and then moves to this record with command MOVETO RECORD. Also the record having ONENTER TCL code gets this code executed at applications startup if the record is a starting record in the file. Starting record is the first record in the application definition file and it is shown to user first.
ONLEAVE code gets interpreted when user navigates out from record.
AFTERRETRIEVE code gets interpreted after record content has been fetched from database but before it is displayed to user.
BEFORERETRIEVE code gets interpreted before record content has been fetched from database.
ATMESSAGE code gets done in case that associated record is being viewed and a UDP message is received via network. Content of the message is given to TCL interpreter as value of variable KN_NEW_MESSAGE.
BEFORESAVE code gets done after user has hit command key telling kort to save record contents (via SAVERECORD or SAVERECORDASNEW) but before saving actually is done (update-command issued to the DB).
AFTERSAVE is like BEFORESAVE but after the update-command to DB.
AT_INIT code gets done exactly once, namely at application startup. Code is run before any other code snippet and before the first record is fetched or displayed.

ONENTER and ONLEAVE codes may also relate to a field instead of record and they then get fired upon leaving and entering a record field.

RECFIELD 5 2 20 just_a_field STRING "Yes, sir: "
SCRIPT_BEGIN ONENTER
 set a_counter [ expr $counter + 1 ]
 set COUNTER_DISPLAYED $a_counter
SCRIPT_END

Previous example shows TCL code that is done before user navigates to a field named "just_a_field". Code is done after user has issued a command that changes input focus to another field and that another field happens to be "just_a_field" and before control is returned to user. Is the previous field happened to have ONLEAVE code, this ONLEAVE -code is interpreted before next fields ONENTER -code.

That said, the next thing that must follow record definition consisting of line beginning RECORD and possible TCL code snippets is record field and label definitions. There is two main types if fields, namely LABEL and RECFIELD. Label is a static text that user can do nothing with except to stare at it. Format for defining a label is

LABEL row column "some text here"

that place some text here so that letter s is located at row row and at column column. Using labels is not necessary from syntaxes point of view. Syntax demands that at least one record field is defined for each record. A record field definition has several forms, the most basic being

RECFIELD row column length name type "label"

where row and column and length are integer numbers. Name is an un-quoted string, type is one of STRING, DECIMAL, INTEGER, DATETIME. When type DATETIME is used, length must be omitted as dates have a format that dictates the length. Entities row and column dictate the place of first letter l of "label", in the screen. Field content is expected to be typed immediately after "label", e.g. right of "label". Length tells the maximum length the content may have. Field with STRING type may contain anything. Field with INTEGER type may contain a plus or minus sign and 1-n numbers. Field with DECIMAL type is like INTEGER except that it may have a decimal point between the numbers. DATETIME type always has format, default format is dd.mm.yyyy hh:mi:ss where each dmyhmis must be a number. A different format may be specified, like in this example:

RECFIELD 10 2 today DATETIME "To-Day is: " "dd.mm.yyyy"

The date format is interpreted as follows:

dd double letter d is replaced in output (or input, for that matter) with day of month.
mm is month number.
yyyy is year waiting for y10k to happen.
yy is year recovering from happenings of y2k. Use of this is strongly not recommended, at least for fields that are not for display-only.
hh is hour in 24-hour format. 12-hour format is not supported by kort.
mi is minute-part of time.
ss is second-part of time.

Any other characters in format string are interpreted as static content of the date-format that user must fill in when entering or modifying a date-value. All values are presented with two numbers (exept yyyy) and leading zeros must be used when entering dates. Any of the date format elements may appear only once in date format.

For plain regular STRING fields a more rigorous format may also be summoned. This may be done by attaching a regular expression for a field and field content must then satisfy this expression. Regexp is evaluated when user tries to get out of the field (just like with date-typed fields too) and if kort is not happy with the format, a loud \a is heard and input focus not moved to other field. Here is an example:

RECFIELD 5 2 20 zuib STRING "Zuib: " REGEXP "foo|foo18"

where values of zuib may be either "foo" or "foo18" and nothing else. See man regexec for regular expressions. Also note that usage of UTF-8 sequnces in regular expressions is ok with kort ; those sequences are turned into strings of wchar_t and the tre regexp mathcing library is used to match those and it seems to work ok at least with scandinavian letter that I've tried it.

Other way than regular expressions for specifying possible content for a field is to give kort a table.column that has same datatype as record field in question. This is done by appending a string ALLOWED_VALUES DBTABLE table TABLEFIELD column where table is a table and column is column in said table. Example of such a arrangement might look like this:

RECFIELD 6 2 20 z STRING "Z: " ALLOWED_VALUES DBTABLE t TABLEFIELD c

that causes field z to need to have values from table/column t.c. This affects only new values e.g. if user inputs one day a value that is on that day found from t.c and then t.c changes and another day user comes back it does not affect z but only if user does not try to modify z. If user types to z something not found from t.c then a list of values from t.c is presented and user is forced to select one. Empty value is always allowed regardless precence of null valus in t.c.

Footnotes

In reality, no such thing exists
Supposing your $TERM is allright