APIGlue.NET Shell Reference

APIGlue shell runs script files containing APIGlue scripting language. This guide is a reference manual about APIGlue scripting language. The guide is divided into the following main chapters:

GENERAL DESCRIPTION

Shell Startup

Shell startup contains the following steps:

Get Shell Folder

Check that environment variable APIGLUE_PATH exists and contains a pathname to an existing folder.

Check Shell Version

Give warning if the running shell assembly differs from the assembly found in APIGLUE_PATH folder.

Check License File

Check that shell license file exists and is valid. Shell searches a license file using the following methods:

Command Line Options

Shell supports the following command line options which are processed during startup.

Option Description
/CONSOLE Start shell by showing console window.
/C Same as /CONSOLE.
/SCRIPT pathname Load startup script file from given pathname. 1
/S pathname Same as /SCRIPT.
/LICENSE name Require a valid license with name. 2
/L name Same as /LICENSE.
/DEBUG modes Start shell debugging using modes. 3
/D modes Same as /DEBUG.

1 Relative script file pathname is searched using shell search paths.

2 License name is searched from Name attribute of <License> tag in license file.

3 See DEBUG command for more information about debug modes.

SHELL VARIABLES

Shell contains system and user defined variables and can use Windows environment variables.

System variables contain shell runtime information and they can be used to set options and defaults for some runtime commands. A system variable name ends with a dollar sign ($).

A user defined variable name must start with a letter or an underscore (_) character. The name can contain letters, numbers and underscore characters.

Windows environment variables can be used in expressions by prefixing the environment variable name with dollar sign ($). The commands SETENV and GETENV can be used to manage Windows environment variables.

Shell variable scope is global by default. Global variables can be seen and used from all functions. Function arguments are local variables and they cannot be seen outside the function. If local and global variable has the same name then the local variable is used.

Shell variable can contain string, numeric or Boolean value. Variable's type is dynamic and it is based on the last stored value.

System variables can be divided into following categories:

Common System Variables

The following lists common system variables:

Variable Description
APISession$ True when a shell extension is started.
APISystem$ Name of active shell extension.
Call$ Name of active function at shell runtime.
CadSystem$ Name of active Cad extension.
Client$ Path name of Link-It Client installation folder (Windows environment variable APIGLUE_CLIENT).
Computer$ Computer name (Windows environment variable COMPUTERNAME).
Culture$ Name of active Windows culture of shell process.
Date$ Today's date in short date format.
Debug$ True when shell's debug mode is on.
Dialect$ Active shell dialect number.
EmptyValue$ Expression for empty value in user menus (default is ~).
Encoding$ Text encoding of active shell process (default is "Default").
Error$ Last shell error code (default is 0).
ErrorMsg$ Last shell error message.
False$ String expression of Windows False value (culture dependent).
IgnoreCase$ If True then ignore character case when comparing strings.
InstallDir$ Path name of Link-It Server parent folder.
LicenseDays$ Number of days left of active shell license.
LicenseName$ Name of active shell license.
LicensePath$ Path name of shell license file.
MaxDecimals$ Maximum number of decimals in shell double number.
MsgBox$ Default and result value of MSGBOX INPUT and MSGBOX QUERY commands.
OpenDir$ Folder pathname of script file which started shell.
Path$ Shell search paths which are used to search script files.
Q$ Single quote character (').
Qq$ Double quote character (").
Return$ Returned result value of RETURN command.
ScreenHeight$ Screen height in pixels.
ScreenWidth$ Screen width in pixels.
Server$ Pathname of Link-It Server folder (Windows environment variable APIGLUE_PATH).
Shared$ Pathname of Link-It Shared folder (Windows environment variable APIGLUE_SHARED).
Shell$ Path name of shell executable.
ShellActive$ Pathname of shell executable or main dll.
ShellComment$ Shell version comment.
ShellDir$ Path name of folder of shell executable or main dll.
ShellId$ Unique identifier for a shell process (identifier format is computername_processid)
ShellOSBits$ Shell process bits (32 or 64).
ShellProduct$ Shell product name.
ShellRelease$ Shell release.
ShellVersion$ Shell version.
Site$ Path to Link-It Site folder, see Shell Search Paths.
SqlNewline$ A string which replaces new line in SQL query results (default is space).
StartDir$ Path to folder where shell started.
StartScript$ Pathname of script file which started shell.
TempDir$ Windows temporary folder path.
Time$ Time updated by last TIME command execution.
TimeGap$ Elapsed time in seconds since last TIME command execution.
Title$ Default title text for user forms and message boxes.
True$ String expression of Windows True value (culture dependent).
WinDecimalSep$ Windows decimal separator character.
WorkDir$ Path name of current working folder which can be changed with WORKDIR command.

Active User Control Variables

The following system variables are updated before calling a user control function:

Variable Description
CtrlColumn$ Column number of table item of active user control.
CtrlFunction$ Function name of active user control.
CtrlMenu$ Menu table name of active user control.
CtrlName$ Name of active user control.
CtrlNumber$ Unique identifier number of active user control.
CtrlOption$ Menu table index of last selected menu item.
CtrlProperties$ Property table name of active user control.
CtrlColumn$ Row index of table item of active user control.
CtrlTable$ Table name of table item of active user control.
CtrlType$ Type name of active user control.
CtrlValue$ Value of active user control.
CtrlVariable$ Variable name of active user control.

Active User Form Variables

The following variables are related to active user form:

Variable Description
FontSize$ Default font size in Twips of a user form (default is 96 Twips).
FormAction$ Name of action to exit a user form.
FormCenterX$ Active form center X position in pixels.
FormCenterY$ Active form center Y position in pixels.
FormExit$ Form command button name pressed when user exits a user form.
FormHeight$ Active user form height in pixels.
FormLoad$ True if form is loading.
FormLeft$ Active user form position in pixels.
FormModal$ True if user form is a modal window.
FormSheet$ Active sheet label text.
FormSheetId$ Active sheet number.
FormStatus$ False if user cancelled a user form.
FormTop$ Active user form top position in pixels.
FormWidth$ Active user form width in pixels.

SELECT Command Variables

The following variables are related to SELECT command.

Variable Description
SelectColor$ Default and result color of SELECT COLOR command.
SelectDate$ Default and result date of SELECT DATE command.
SelectDir$ Default and result folder path of SELECT command.
SelectFile$ Default and result file name of SELECT command.
SelectName$ Name of result file of SELECT command.
SelectPath$ Default and result file path of SELECT command.
SelectSuffix$ Suffix name of result file of SELECT command.
SelectTable$ Table name for multiselection of files with SELECT command.

Legacy System Variables

The following lists system variables which are maintained for legacy reasons and will be removed in future shell versions:

Variable Description
CslInit$ File name of initialization script file (Windows environment variable APIGLUE_CSLINIT).
InputComment$ INPUT command ignores lines starting with given string.
InputSeparator$ INPUT command splits lines to tokens with given string.
ShellIsNet$ True if shell is based on .NET Framework.
ShellNet$ File name of .NET shell executable.

Shell Search Paths

Shell searches script files with relative pathname using a list of search paths which are stored to Path$ variable.

The following shows initial search path folders which are set during startup:

1 Link-It Site folder path is first searched from environment variable APIGLUE_SITE and then read from Windows registry path "HKEY_CURRENT_USER\Software\VB and VBA Program Settings\APIGlue\UserData\LinkIt_Site".

2 CSLPATH environment variable can contain multiple search path folders separated with semicolon ;.

Error Handling

Shell error handling shows an error message window when it notices an error situation.

When shell loads a script file shell checks only one or two first words, that is, shell checks that a command line starts with a valid command name or that a definition statement is correct.

At runtime shell parses rest of command line arguments and shows error message if parser finds syntactical defects or incorrect command usage.

Shell traps internal runtime errors and shows error information in message window.

Loading Of Script Files

Shell reads script file lines and parses them at load time.

SHELL DEFINITIONS

Shell definitions are used to define executable program structure and data.

Shell definitions for APIGlue shell contain the following statements:

FUNCTION

Start function definition.

FUNCTION name [arg ...]
  function body
END FUNCTION

FUNCTION statement starts a function name definition which ends with END FUNCTION statement. A function definition must reside inside one script file.

FUNCTION and END FUNCTION statements allow the execution of codes written inside the function block, i.e. function body.

Function definition can contain optional arguments which are local variables to function and their value cannot be seen outside the function.

Use CALL command to run a function at runtime. When calling a function the number of parameters must be less or equal than the number of function arguments.

Note!A function definition overwrites an existing function with the same name.
Note!A function definition cannot contain other function or table definitions.

INCLUDE

Include script file.

INCLUDE name

INCLUDE statement includes a script file of given name which can be an absolute or a relative path name. Multiple script files can be included by using Windows Search wildcards in name.

The following lists search rules to include a script file or files:

INCLUDE statement uses shell search paths to locate a script file. Use LIBRARY statement to add a folder path into shell search paths. Shell search paths are stored in global variable Path$. The following lists default search paths:

  1. Link-It Server folder.
  2. scripts subfolder in Link-It Server folder.
  3. Link-It Shared folder.
  4. Link-It Site folder.

LIBRARY

Add search path.

LIBRARY pathname

LIBRARY statement adds given pathname to shell search paths.

The pathname can be relative to current parsed script file. The pathname can contain %env% expression which expands the value of environment variable env.

TABLE

Start data table definition.

TABLE name [columns] [+]
  table body
END TABLE

TABLE statement starts a data table name definition which ends with END TABLE statement. A table definition must reside inside one script file.

A table definition can contain number of data columns, which define how many data items are read into a table row. If columns option is missing then the number of columns is the number of data items in the first data row.

A table definition overwrites an existing table with the same name. Use number zero (0) for columns to keep number of columns same with an existing table. Use optional + sign to append or overwrite data rows in an existing table.

A data table can be empty or can contain data rows. A single data row contains data items which are separated with space and Tab characters. If a data item contains a space or Tab character then it must be enclosed with either single or double quotes.

Data items are interpreted into four data types:

The string values of the first column are used as indexes for data rows. Existing data row items are overwritten if the index of the data row is the same as an input data row.

Use the following syntax to refer different parts of data table:

A data row can also be refered with its position number in the table. A negative position number is counted from the end of the table.

Use the following syntax in expressions to test different parts of data table:

TRACE

Trace loading of script files.

TRACE option [value]

TRACE statement traces loading of script files by writing information of parsed script lines to a log file.

The following lists tracing options:

Trace mode letters control which items are written to log file:

SHELL COMMANDS

Shell commands are executed during shell run.

Shell commands can be divided into following categories:

Shell Data Handling Commands

Shell Debugging Commands

Shell Flow Control Commands

Shell Form Related Commands

Shell Operating System Commands

Shell Miscellaneous Commands

CALL Command

Call predefined function.

CALL function_name [value ...]

Call a predefined function function_name. Optionally use argument values.

CLS command

Clear Debug window's console page.

CLS

COPY Command

Copy a file or a directory to another location.

COPY source_path target_path

Copying Files

If source_path contains wildcard characters or destination target_path ends with a path separator (\), it is assumed that destination is an existing folder in which to copy matching files. Otherwise, destination is assumed to be the name of a file to create. In either case, the following things can happen when an individual file is copied:

  1. If destination does not exist, source gets copied. This is the usual case.
  2. If destination is an existing file, an attempt is made to copy source over the existing file.
  3. If destination is a directory, an error occurs.
  4. An error also occurs if a source using wildcard characters doesn't match any files.

Copying Directories

If source source_path contains wildcard characters or destination target_path ends with a path separator (\), it is assumed that destination is an existing folder in which to copy matching folders and subfolders. Otherwise, destination is assumed to be the name of a folder to create. In either case, the following things can happen when an individual folder is copied:

  1. If destination does not exist, the source folder and all its contents gets copied. This is the usual case.
  2. If destination is an existing file, an error occurs.
  3. If destination is a directory, an attempt is made to copy the folder and all its contents. If a file contained in source already exists in destination, it will attempt to copy the file over the existing file.
  4. An error also occurs if a source using wildcard characters doesn't match any folders.
Note!The command stops on the first error it encounters. No attempt is made to roll back any changes made before the error occurs.
Note!The command allows copying files and folders between volumes only if supported by the operating system.

CULTURE Command

Set or query current culture.

CULTURE [culture_name]

Set current culture to give culture_name and update the following system variables:

If empty culture name then update only variables.

DATEADD Command

Add an interval to a date variable.

DATEADD variable interval units

DATEADD command parses variable value to datetime value and The numeric interval can be positive or negative. The resulting datetime is stored back as string value to variable.

The following lists available datetime units:

DATEDIFF Command

Get number of time intervals between two dates.

DATEDIFF variable date1 date2 units

DATEDIFF command parses two values date1 and date2 to datetime values and calculates the number of units between the values. The resulting intervals are stored back as integer value to variable.

The following lists available datetime units:

DEBUG Command

Control shell debugging.

DEBUG [option [value]]

DEBUG command controls shell debugging with the following options:

Debug modes are:

DEBUG command without options opens a Debug window.

DEL Command

Delete a variable, a table, a file or a directory.

DEL variable
DEL table[row]
DEL table[??match]
DEL table[???regexp]
DEL table[row][col]
DEL table[][col]
DEL table[]
DEL pathname

A table is recognised from square brackets ([]) characters.

A directory is recognised from ending backslash (\) character in pathname.

A file is recognized from either dot (.) or backslash (\) character in pathname.

DEL command supports in pathname the use of multiple-character (*) and single-character (?) wildcards to specify multiple files.

If the deleted item is not a table, a file or a directory then it is assumed to be a variable.

Note!Local function variables can not be deleted.

DELREG Command

Delete a variable, a table or a sub key from Windows register.

DELREG {variable|table[]} [subkey]

DELREG command deletes a variable, a table or a sub key from Windows register. Use SETREG command to store and GETREG command to restore items from the registry.

A subkey is recognized from subkey with its ending back slash (\).

The subkey can be used to specify a relative key path from

HKEY_CURRENT_USER\Software\VB and VBA Program Settings\APIGlue\UserData

DIALECT Command

Set or reset command interpreter dialect.

DIALECT [number]

DIALECT command sets command dialect to given number and updates Dialect$ variable. If number is omitted then dialect is set to the latest dialect.

DIR Command

List files or directories to table.

DIR [option] table [pathname]

DIR command writes information of files or directories to table.

DIR command options are:

If no pathname is given, then DIR command uses the current directory. pathname can contain wild characters to match listed files. pathname can contain directory path, file name, file name match, path name or matching path name.

ECHO Command

Show message in Debug window console page.

ECHO [text]

ECHO command prints text to console page of Debug window. With no arguments the command prints an empty line.

ERROR Command

Show error text in a message box window and end shell run.

ERROR text [title]

EVALUATE Command

Evaluate expression in a variable or in a table item.

EVALUATE variable
EVALUATE table[row]
EVALUATE table[][column]
EVALUATE table[row][col]

EVALUATE command evaluates expression in a variable or in a table item and stores evaluated value back to the variable or table item.

EXIT Command

Quit shell session or an application.

EXIT [application]

EXITCALL Command

Exit current called function and return to calling function.

EXITCALL

EXITCALL command returns to calling function and updates Return$ variable to an empty string. See RETURN command to return with a value.

EXITFORM Command

Exit a user form.

EXITFORM [action]

EXITFORM command exits the current user form with given action which is stored to FormAction$ variable.

EXITFORM command action is one of the following:

EXITFORM command can be used in user form's function which is called when user form is exiting. This function can test FormAction$ variable and set FormStatus$ variable which controls whether form exits or not.

EXITLOOP Command

Exit a loop.

EXITLOOP [variable]

EXITLOOP command exits loop whose variable name is variable. If no variable is provided then EXITLOOP exits the current loop.

FORMAT Command

Format a variable value using a format string.

FORMAT variable format [expression | variable2 | table_values]

FORMAT command formats the value of a variable using instructions contained in a format string expression and stores the result back to the variable. Optionally variable value is read from expression or from value of variable2. The command supports also composite formatting with multiple table_values from a table column or a table row.

FORMAT command uses current culture which can be managed with CULTURE command.

If FORMAT command fails to format a value then the original value is returned.

Value Types

FORMAT command accepts boolean, numerical and string values. Boolean values True and False are converted to numbers 1 and 0. The following list shows special data conversions for string values:

If special data conversion for a string value fails then the original string is used.

Format Strings for Single Values

FORMAT command has the following special format strings for a single value:

Other format strings for a single value use System.String.Format function which supports a wide variaty of standard and custom format strings:

Composite Formatting with Multiple Values

The composite formatting feature of FORMAT command takes a list of values and a composite format string as input and outputs result to variable. The list of values is read from a table row or a table column. A composite format string consists of fixed text intermixed with indexed placeholders, called format items, that correspond to the values in the list. The formatting operation yields a result string that consists of the original fixed text intermixed with the string representation of the values in the list.

FORMAT command uses the .NET composite formatting feature.

GETENV Command

Get Windows environment variables.

GETENV table[]
GETENV [target:]name [variable]

GETENV command gets Windows environment variables to a result table. Optionally GETENV command stores the value of Windows enviroment variable name to a shell variable.

The optional target can be used to specify the location of the environment variable:

If shell variable is missing then environment variable name is used for the shell variable name. If environment variable name does not exist then an empty string is stored to the variable.

Use SETENV command to set value of an environment variable.

GETREG Command

Restore Windows register items.

GETREG {variable|table[]} [item]

GETREG command restores given variable or table fromWindows register to a shell variable or table. The shell variable or table is created if neccessary. The command returns an empty string if the register items does not exist.

The optional register item can contain a register name or a register key. If the item ends with and ending backslash (\) then the item is recognized as a key. If a key starts with a backslash (\) then it is recognized as a key with an absolute path in Windows registry.

If the optional register item does not end with a backslash then it is recognized as a register name under the default user register area, which is UserData key in the application register area:

HKEY_CURRENT_USER\Software\VB and VBA Program Settings\APIGlue\Shell (EXE)\UserData\"

The register item name may contain a sub key path.

By default, the variable or table name is used for register item name.

Use SETREG command to store and DELREG command to delete items from registry.

See SETREG for more information about how the table items are stored to Windows registry.

GETTBL Command

Get target table from source table values.

GETTBL target_table source_table [alternate_name]

GETTBL command searches specially named indexes from source table and use the found rows to make rows to target table.

Target table is created from rows whose index matches to regular expression "^table_[0-9]+_[0-9]+$", where table is target table name and numbers refer to row and column numbers. Optionally, you can specify alternate target table name with the option alternate_name.

INFO Command

Get information from shell session.

INFO type table [option]

INFO command gets information from shell session and stores the information to a result table.

INFO command has the following shell session information types:

IF Command

Conditionally executes a group of statements.

IF expression
[statements]
[ELSEIF elseifexpression
[elseifstatements]]
[ELSE
[elsestatements]]
ENDIF

When an IF...ENDIF block is encountered, expression is tested. If expression is True, the statements following IF command are executed. If expression is False, each ELSEIF command (if there are any) is evaluated in order. When a True elseifexpression is found, the statements immediately following the associated ELSEIF are executed. If no elseifexpression evaluates to True, or if there are no ELSEIF commands, the statements following ELSE are executed. After executing the statements following IF, ELSEIF or ELSE, execution continues with the statement following ENDIF.

The ELSEIF and ELSE clauses are both optional. You can have as many ELSEIF clauses as you want in an IF...ENDIF block, but no ELSEIF clause can appear after an ELSE clause. IF...ENDIF blocks can be nested within each other.

INPUT Command

Input text file to a table.

INPUT pathname table [options]

INPUT command reads a text from pathname into a result table by writting text line tokens to table columns. Table rows are indexed using a sequential numbers starting from 1.

The result table is created if neccessary. If the result table exists then the rows are added to the table.

A text line is tokenized using separator characters from a system variable InputSeparator$, which has a default value of space and tab characters.

By default multiple separator characters between tokens are considered as one separator. Also leading and trailing separator characters in the text line are ignored.

A text line is ignored if it contains no tokens or if its first token starts with a comment string from a system varible InputComment$, which has a default value "!".

The optional table options can be used to specify how file is read.

Below is listed options that can be used in options table:

INSERT Command

Insert row data before given table row.

INSERT table[row] source

INSERT command is used to insert row data from source before given target row of existing table. If target row is missing or its value is an empty string then data is inserted starting at 1st row of target table. If a row to be added already exists in the target table then row's data is updated.

The source of inserted row data can be a table, a table row or table row values.

INSERT table[row] table2[]

Insert table table2 rows.

INSERT table[row] table2[row2]

Insert table table2 row row2.

INSERT table[row] row2 [value ...]

Insert a new row with index row2 and optional values.

LOG Command

Log text to a file.

LOG pathname text [table]

LOG command appends text to the end of the file pathname. If the file does not exist then it is created. By default, the text is written to the file by using encoding value from variable Encoding$.

The optional setup table can contain the following option:

LOOP Command

Loop statments until a condition is met.

LOOP variable condition
  statements
ENDLOOP

LOOP command executes statements between LOOP and ENDLOOP statements until a condition is met.

LOOP command supports two types of conditions:

LOOP variable expression
  statements
ENDLOOP

Loop variable is incremented on each loop starting from 1. The Boolean expression is evaluated before each loop and the loop continues while the expression evaluates to True.

LOOP variable table[]
  statements
ENDLOOP

Loop variable is assigned to table's row indexes before each loop starting from row 1. Loop exits after all indexes have been gone through.

One loop block can contain other loop blocks. A loop block must reside inside a function definition.

Loop variable is visible only inside loop's function. Use different variable names on loop blocks which reside inside each other.

Use EXITLOOP command to exit a loop immediately and to continue execution after ENDLOOP.

MKDIR Command

Create any intermediate directories in given path.

MKDIR pathname

MKDIR creates any intermediate directories in the pathname The command gives no error message if a directory already exists.

MOVE Command

Move files or directorys to another location.

MOVE source target

Moving Files

The source is a file pathname which can contain Windows wild characters to match multiple files. If source contains wildcards or destination ends with a path separator (\), it is assumed that destination specifies an existing folder in which to move the matching files. Otherwise, destination is assumed to be the name of a destination file to create. In either case, the following things can happen when an individual file is moved:

  1. If destination does not exist, the file gets moved. This is the usual case.
  2. If destination is an existing file, an error occurs.
  3. If destination is a directory, an error occurs.
  4. An error also occurs if a wildcard character that is used in source doesn't match any files.
Note! This command allows moving files between volumes only if it supported by the operating system.

Moving Directories

The source is a directory pathname which can contain Windows wild characters to match multiple files. If source contains wildcards or destination ends with a path separator (\), it is assumed that destination specifies an existing folder in which to move the matching files. Otherwise, destination is assumed to be the name of a destination folder to create. In either case, the following things can happen when an individual folder is moved:

  1. If destination does not exist, the folder gets moved. This is the usual case.
  2. If destination is an existing file, an error occurs.
  3. If destination is a directory, an error occurs.
  4. An error also occurs if a wildcard character, that is used in source, doesn't match any folders.
Note!The command stops on the first error it encounters. No attempt is made to roll back any changes made before the error occurs.
Note!The command allows moving files and folders between volumes only if supported by the operating system.

MSGBOX Command

Show message in message box window.

MSGBOX [style] message [title]

MSGBOX shows a message box window using optional style and title. The message box window styles are:

INFO, ERROR and WARNING style message box window contains a message and OK button.

QUERY style message box window contains a message and OK and Cancel buttons. User's button selection is stored as a boolean value into MsgBox$ system variable. OK button stores True value and Cancel button False value.

INPUT style message box window contains a message, a textbox and OK and Cancel buttons. User's input text is stored as a string into MsgBox$ system variable. If user cancels the window then variable's value is set to an empty string. The default text value of INPUT style message box window can be set to MsgBox$ variable.

PASSWORD style message box is like the INPUT style message box its textbox text is hidden with '*' characters.

PROGRESS Command

Show progress window.

PROGRESS setup[]

PROGRESS command shows a progress window which visually indicates the progress of a lengthy operation.

READ Command

Read tokens from file to variables or tables.

READ pathname [table [format]]

READ command parses tokens from file and stores them to variables or tables. The optional table can be used to store all tokens to one table.

By default, the tokens are parsed based on the file type, which is recognized from file's suffix. The known suffixes are:

The optional formatting table format can be used to define the parsing method thus ignoring the parsing method based on file name suffix. Each row in the format table defines the parsing method of one data table column:

REFRESH Command

Refresh form.

REFRESH [option]

REFRESH command refreshes a user form by updating form data, rereading property tables and resizing form controls. REFRESH command should only be called from functions of form controls.

REFRESH options are:

A function call can contain multiple REFRESH commands which all are executed before returning control to user.

RELOAD Command

Reload function and table definitions at run-time.

RELOAD pathname [prefix]

RELOAD command replaces current function and table definitions with new ones found from the given pathname, which is a script file. The optional prefix string can be used to rename the found function and table names by adding the prefix to the name.

If a function or a table does not exist, RELOAD command creates a new one.

Note!RELOAD command cannot replace main program or functions, which are open in current call stack.

RESTART Command

Restart shell.

RESTART [pathname]

RESTART command restarts the current shell session. The optional pathname can be used to reload a script file, which can replace the main program.

RETURN Command

Return to calling function and update Return$ variable.

RETURN [expression]

RETURN command returns to calling function and updates Return$ variable with expression value. If expression is omitted then Return$ variable is set to an empty string.

SELECT Command

SELECT command selects file system objects, a color, a date or a font using Windows common dialogs.

Select File System Objects

SELECT DIR
SELECT FILE [filter]
SELECT SAVE [filter]

Use the following SELECT command sub commands to select file system objects:

A file is selected by using a filter, which contains one or more file type filters separated by a pipe character (|). The "All files" filter is added automatically at the end of the list. A file type filter has two parts (strings) separated by a pipe character. The first part is a type description shown in the dialog window. The second part is a match string, which is used to select file names shown in the dialog window. For example, you can use the following filter string to select either a parameter file (.par suffix) or text file (.txt suffix):

 "Parameter file (*.par)|*.par|Text file (*.txt)|*.txt"

The following variables can be used to control the command behaviour:

The command updates the following variables:

Select Color

SELECT COLOR

SELECT COLOR command shows "Select Color" dialog, which can be used to select a color. The following variables can be used to control the command behaviour:

The command updates the following variable:

Select Date

SELECT DATE

SELECT DATE command shows "Select Date" dialog with a month view control, which can be used to select a date. The following variables can be used to control the command behaviour:

The command updates the following variable:

Select Font

SELECT FONT [table]

SELECT FONT command shows "Select Font" dialog which can be used to select a font and its characteristics and save results to a font table. Default font table name is SelectFont$. The following variables can be used to control the command behaviour:

The command updates the following variable:

Font Table Properties

The following table show font table properties:

Property Description
BOLD boolean If True then show bold text.
ITALIC boolean If True then show italic text.
NAME name Windows font name.
SIZE esize Font size in em.
STRIKEOUT boolean If True then show strikeout text.
UNDERLINE boolean If True then show underlined text.

SENDKEY Command

Send "keys" to an application.

SENDKEY text [match]

SENDKEY command sends text containing key strokes to an application window whose title starts with match. If match is omitted then the keys are sent to desktop's active window.

Note!SENDKEY command sends keys to the first window whose title starts with the same string as in match.

SET Command

Set variable, table item, table row, table column or table values.

SET target source [option]

SET command sets data from source to target.

Set Variable Value

SET variable value

Set value to variable, which can be a variable or a table item.

Concatenate Table Column to Variable

SET variable table[[column]] [separator]

Concatenate table column values using a separator string separator and set resulting string to variable, which can be variable or a table item. The default value of column number column is 2. The default value of separator string separator is " " (a space character).

Set Table Row Values

SET table[row][[col]] value [...]

The above syntax sets table row values using the following rules:

Set Table Column Values

SET table[][column] value

The above syntax initializes all table column values to value.

Copy Table to Another Table

SET table1[] table2[] [match]

Copy table table2 contents to table table1 and overwrite existing values. The optional index match can be used to copy only rows whose index matches to regular expression match.

If table1 exists then only columns which exist both in table1 and table2 are copied.

Copy Table Row to Another Table

SET table1[[row1]] table2[row2]

Copy row row2 of table table2 to table table1. Optionally set target row row1.

Copy Table Column to Another Table

SET table1[][[col1]] table2[][col2] [match]

Copy column col2 of table table2 to table table1. Optionally set target column col1. The optional index match can be used to copy only column items whose row index matches to regular expression match.

SETENV Command

Set environment variable value.

SETENV [target:]name value

SETENV command sets Windows environment variable name value to value which is always a string. The name of environment variable cannot include equal sign (=). Optional target can be used to specify the location of the environment variable:

SETENV command deletes an existing system or user environment variable if the value is the same as in system variable EmptyValue$ which has the value ~ (tilde) by default.

Note!Updating Windows system environment variable with SYSTEM target requires that shell is run with administrative priviledges.

Use GETENV command to get value of an environment variable.

SETREG Command

Store variable or table to Windows registry.

SETREG {variable|table[]} [subkey|regname]

SETREG stores a variable or a table to Windows register. Use GETREG to restore and DELREG to delete the stored items.

By default, variable and table items are stored using their name as a register name. The optional regname can be used to store items under a different name.

Table items are named using formula "name_row_col", where name is either the table name or the given register name, row and col are table item's row and column numbers.

String values are stored as "String" type, integer values as "Number" type and boolean values as "Binary" type. Floating number values are stored as "String" type and by using !@#$% prefix.

The optional register key subkey can be used to store items under a different subkey under the default key. The subkey path may contain multiple levels. The subkey path is recognized from its ending slash (\). Absolute register key path starts with two backslashes (\\).

By default, the keys are stored under "UserData" key in the application

  "\HKEY_CURRENT_USER\Software\VB and VBA Program Settings\APIGlue\UserData\"

SETTBL Command

Convert source table to target table values.

SETTBL target source [name]

SETTBL command stores each source table item to target table. Items are indexed using expression "name_row_col", where row and col are item's row and column numbers in source table. If name is omitted then source is used.

SLEEP Command

Pause execution for a given number of seconds.

SLEEP [number]

SLEEP command pauses shell execution for number of seconds. The maximum pausing time is 600 seconds (10 minutes) and the default is one second.

SORT Command

Sort table rows.

SORT table [key ...]

SORT command sorts table rows using sort keys. A sort key is a string which has three parts:

If sort key is missing then the table is sorted using textual ascending sort to first column.

For example, the sort key "ND2" sorts the table using numeric descending sort to column 2.

SPLIT Command

Split string into table items using separator characters.

SPLIT string table [separators|FILE]

SPLIT command splits given string expression using separators characters and stores the tokens into table. By default, the separators are a space and a tab characters.

If separators string starts with ??? then the rest of the string is used as a reqular expression to split the given string expression. System variable IgnoreCase$ controls operations letter case sensitive.

The FILE option can be used to split a pathname into three file system parts: folder, basename and suffix.

If the table does not exist then it is created and indexed using row's order number.If the table exists then the tokens are stored to table using the same order as found from the string.

SQL Command

Run SQL query.

SQL CONNECT text
SQL SELECT text table[]
SQL COLUMN_NAMES text table[]
SQL DISCONNECT

SQL command has the following sub commands:

STRLEN Command

Get value length or maximum length of table items.

STRLEN variable value
STRLEN variable table_name>[]
STRLEN variable table_name>[row]
STRLEN variable table_name>[][column]
STRLEN variable table_name>[row][column]

STRTBL Command

Convert text to table items.

STRTBL text table

STRTBL command splits text into tokens and stores them into table items (2nd column).

The result table should exist and should contain the following four columns:

SUBST Command

Substitute a substring to a new one in a string variable.

SUBST variable [from_text [to_text [ALL]]]

SUBST command substitutes substring from_text to string to_text in variable. Use option ALL to substitute all occurence of substring from.

If from and thus to is omitted then SUBST command trims the contents of variable by removing leading and trailing spaces and tabs and by substituting sequential spaces and tabs to one space character.

SUBSTR Command

Get substring from a string variable.

SUBSTR variable length [start [variable2]]

SUBSTR command returns the substring of the string variable starting at the position start and using the length length. The result is stored to variable2, which is a string variable.

If the optional variable2 is omitted then the result is stored to variable. If the optional start position start is omitted then the start position is at the beginning of the string. If length is negative then length is calculated by subtracting length from the total string length. If start is negative then start position is calculated from the end of the string.

SYSTEM Command

Execute operating system command.

SYSTEM [option ...] [command [arguments]]

SYSTEM command start a new process to run a command with arguments. If command is omitted then run "CMD.EXE".

SYSTEM< command accepts the folloing options:

TBLSTR Command

Convert table row or table column items into a string variable.

TBLSTR table variable [separator]
TBLSTR table[][column] variable [separator]
TBLSTR table[row] variable [separator]

TBLSTR command stores column or row values of table to variable. If row or column is omitted then the values of table's 2nd column are written sequentially to variable using space character as a separator. The optional separator can be used to specify the separator and it can be an empty string.

If writing table's 2nd column values then the table can contain the following optional columns to specify how table item value is written to the text variable:

If a non-empty separator is given then the start position and length values are ignored. If the start position is omitted then the value is added at the end of the string. If the length is omitted then the value's length is used.

TIME Command

Get time and elapsed time since last queried.

TIME [table]

TIME command updates time information to table and to shell variables Date$, Time$ and TimeGap$ (in seconds).

If Debug window is present then TIME command shows time and elepsed time in Console page.

TITLE Command

Set form window title.

TITLE text

TRANSLATE Command

Set language translation table.

TRANSLATE table

WEB Command

Run HTTP Web request.

WEB URL [option_table]

WEB command runs a HTTP Web request to Web server's URL.

The optional option_table can contain the following options:

Option Description
METHOD Method type: GET (default) or POST. POST method is used automatically if post-data or post-file arguments are found.
POSTFILE Post-file, e.g. "file1=C:\tmp\file.txt&file2=C:\tmp\file2.jpg"
POSTDATA Post-data, e.g. "id=1234&arg1=true&arg2=DESC"
OUTPUT Pathname of response file.
HEADER Header, e.g. "Content-Type: multipart/form-data".
KEEPCOOKIES If True (default) then keep cookies.
KEEPALIVE If True (default) then keep process alive.
TIMEOUT Timeout in seconds. Default is 30.
SILENT If True then process silently.
URL URL, e.g. "http://propeli/portalapi/portalapi/user/GetInfo?id=MST&infosetid=full"
HTTPUSER User id.
HTTPPASSWORD Password.
HTTPPASSWD Indentical with HTTPPASSWORD.
DATAWRITE If False then do not write reponse to file. Default is True.
DATATABLE Data table name. Default name is "XML".

If option_table is missing then URL is opened into default internet browser.

WORKDIR Command

Query or change working directory.

WORKDIR [pathname]

WORKDIR command updates shell's current working directory path to variable WorkDir$. The optional pathname changes shell's working directory to the given path. The command accepts both absolute and relative pathnames.

WRITE Command

Write variables or tables to a file.

WRITE pathname text [options]
WRITE pathname table[] [options_table]

WRITE command appends the text or the table contents to pathname. The file is created if neccessary.

By default, he file name suffix determines how information is written to the file. Below are listed the recognized suffixes:

USER FORM DEFINITIONS

User form contains the following layout definitions:

User form contains the following user control definitions:

FORM Definition

Define a user form.

FORM [title] [table[]]
statements
ENDFORM

FORM statement starts a new user form definition block. ENDFORM statement ends the definition block and shows the form. Optional title defines title text of form's window. Form controls are defined between FORM and ENDFORM statements. Shell supports only one user form at a time.

A user form contains three areas: header, stretch and center areas. The height of header and footer areas are fixed and based on the heights of their controls. Stretch area height streches when form is streched.

Form
Header area
Stretch area
Footer area

Stretch area is defined using SHEET statements and the area ends with ENDSHEET or ENDFORM statement. Header area contains controls defined before the first SHEET statement. Footer area contains controls defined after ENDSHEET statement.

Form properties are read from optional table and are described in section Form Statement Properties.

SHEET Definition

Define a tab control with tab pages.

SHEET [text [table]]
statements
[SHEET [text [table]]]
statements
ENDSHEET

SHEET statement starts a new sheet definition in user form and the following SHEET, ENDSHEET or ENDFORM statement ends an active sheet definition. A user form can contain only one sheet definition block but multiple sheet definitions. User form shows user controls of sheet definition block in the middle area of the form.

If sheet block definition contains two or more sheets then user form shows a tab control whose tab pages are populated with control statements of individual sheet definitions. SHEET statement's label text is used as tab label text for sheet's tab page. If label text is omitted then sheet's order number is shown.

If sheet block definition contains only one sheet definition then user form shows control statements without tab control.

Sheet properties are read from optional table and are described in section SHEET Statement Properties.

FRAME Definition

Define a frame box.

FRAME [title] [table[]]
statements
ENDFRAME

FRAME statement starts a new frame box definition and ENDFRAME statement ends the definition. The optional title can be used to specify frame's title. Frame contains the user controls which are defined between FRAME and ENDFRAME statements. If title is omitted then the table name table must end with square brackets []. A frame cannot contain an other frame.

FRAME user control has a frame box control which is in a picture box container.

frame

FRAME user control properties are read from the optional property table and are described in section FRAME Statement Properties.

ROW Definition

Start a row definition in a user form.

ROW [width ...]

ROW starts a row defintion in a user form. A row can hold multiple controls in the same row.

Row's height is the height of its heighest control.

The optional width values define the widths of row controls. If no width values are found then all row controls have the same width which is row's total width divided by the number of controls. The same effect can be achieved using zero (0) as the width value.

A width value can be proportional or fixed. A proportional value is a number or a number followed by a percent sign %. A fixed value is a number followed by "px" suffix. Proportional width values are calculated by extracting fixed widths from row's total width and then dividing the remaining width into proportinal widths.

BUTTON Definition

Define a user control with a command button.

BUTTON function [text [property_table]]

BUTTON user control contains a command button. The function is called when the button is pressed. If no label text is provided then function name is used as label text.

BUTTON user control has a button control which is in a picture box container.

button

BUTTON user control has an optional property MENU which shows a popup menu when user presses the button. Button's function is called with the following three arguments when user selects a menu item from the popup menu:

Button properties are read from the optional property_table and are described in section BUTTON Statement Properties.

COMBO Definition

Define a user control with a label and a combo box.

COMBO variable combo_table [text [property_table]]

COMBO user control shows a label text and has a combo box to select the value of variable from a dropdown value list populated from combo_table.

COMBO user control has label text and combobox controls which are in a picture box container.

label text combobox

The user control has an optional MENU property which shows a menu button to select the value from a popup menu.

label text combobox menu

COMBO user control properties are read from the property_table and are described in section COMBO Statement Properties.

COMBO2 Definition

Define a user control with a label, a combo box, a showbox and a menu button.

COMBO2 variable combo_table text property_table

COMBO2 user control shows a label text and has a combo box to select the value of variable from a dropdown value list populated from combo_table. The control has also a menu button to select the value from a menu and a showbox to show value's menu name.

COMBO2 user control has label text, combobox, showbox and menu button controls which are in a picture box container.

label text combobox showbox menu

COMBO2 user control properties are read from the property_table and are described in section COMBO2 Statement Properties.

CONTROL Definition

Define a general user control.

CONTROL name [property_table]

CONTROL statement defines a user control whose type is defined with CONTROL property in property_table. CONTROL statement supports the following user controls types:

If CONTROL property is omitted and MENU property exists then control's type is MENU. Otherwise control's default type is QUERY.

CONTROL statement properties are read from the property_table and are described in section CONTROL Statement Properties.

LABEL Definition

Define a user control with a label text.

LABEL [text [property_table]]

LABEL statement shows a label text in the current user form. If no label text is provided then an empty row is shown.

LABEL user control has a label text control which is in a picture box container.

label text

LABEL user control properties are read from the optional property_table and are described in section LABEL Statement Properties.

MATRIX Definition

Define a matrix user control.

MATRIX data_table [property_table]

MATRIX statement defines a matrix user control in a user form. Matrix user control shows the contents of data_table in a datagridview control which is in a picture box container.

header1 header2 header3
index 1 1 item 1 2 item 1 3
index 2 1 item 2 2 item 2 3

MATRIX user control properties are read from the optional property_table and are described in section MATRIX Statement Properties.

MENU Definition

Define a user control with a label, a textbox and a menu button.

MENU variable menu_table [text [property_table]]

MENU user control shows a label text and has a textbox to input the value of variable. The control has a menu button to select a menu item from a popup menu populated from menu_table.

MENU user control has label text, textbox and menu button controls which are in a picture box container.

label text textbox menu

MENU user control properties are read from the optional property_table and are described in section MENU Statement Properties.

MENU2 Definition

Define a user control with a label text, a textbox, a showbox and a menu button.

MENU2 variable menu_table [text [property_table]]

MENU2 user control shows a label text and has a textbox to input the value of variable. The control has a menu button to select a menu item from popup menu populated from menu_table and a a showbox to show value's menu name.

MENU2 user control has label text, textbox, showbox and menu button controls which are in a picture box container.

label text textbox showbox menu

MENU2 user control properties are read from the optional property_table and are described in section MENU2 Statement Properties.

PICTURE Definition

Define a user control with a picture box.

PICTURE image [property_table]

PICTURE user control shows an image in a picture box control which is in a picture box container.

image

PICTURE user control properties are read from the optional property_table and are described in section PICTURE Statement Properties.

QUERY Definition

Defines a user control with label and textbox or checkbox.

QUERY variable [text [property_table]]

QUERY defines a user control row in a user form.

QUERY control appeares in a different way if the variable contains a boolean value or it contains text or number.

Text or numeric value is queried by using a label text and a textbox.

label text textbox

Boolean value is queried by using a label text and a checkbox.

label text

QUERY user control properties are read from the optional property_table and are described in section QUERY Statement Properties.

SHOW Definition

Defines a user control with a label and a showbox or a locked checkbox.

SHOW variable [text [property_table]]

SHOW control appears in a different way if the variable contains a Boolean value or it contains text or number value. Text or numeric value is shown by using a label text and a showbox.

label text showbox

Boolean value is shown by using a label text and a locked checkbox.

label text

SHOW user control properties are same than QUERY user control properties.

SHOW user control properties are read from the optional property_table and are described in section QUERY Statement Properties.

SHELL EXPRESSIONS

An expression is a sequence of operators and operands that specifies a computation of a value. Expression tokenizer splits an expression to tokens and expression evaluator calculates the value of an expression.

EXPRESSION TOKENS

Expression tokenizer splits an expression to tokens and returns a list of tokens which include string, number or Boolean values, reserved names and operators.

Expression tokenizer extracts the value of variables and table items. It also handles testing of named tokens.

Expression tokenizer uses the following methods:

Character content

Shell searches special characters from an expression to extract literal string or number value, grouping or operator.

The following lists special characters:

Characters Description
" ' Quoted string "..." or '...'
0...9 . , Number [0-9]*[.,]?[0-9]*
( ) Grouping parantheses (...)
+ - / * ^ Arithmetic operators + - / * ^
& String concatenation operator
= > < Comparison operators = > < == >= => =< <= ><
? Testing operators ?? ???
[ Empty table test []?
$ Expand environment variable $name 1

1 If environment variable name does not exist then an empty string is used. Environment variable name can contain the following characters: 0-9 A-Z a-z _ $ # @

Reserved keywords

The following keywords are reserved, which means that you cannot use them as names for variables, tables or functions:

Token Description
AND Logical AND operator
NOT Logical NOT operator
OR Logical OR operator
LIKE Comparison LIKE operator
SAME Comparison SAME operator
FALSE Boolean FALSE value
TRUE Boolean TRUE value

Function related values

The following lists function name related tokens:

Token Description
name()? Function existence testing.

Variable related values

The following lists variable name related tokens:

Token Description
name?VALUE Test if variable has a non default value. 1
name?NUMBER Test if variable value can be converted to a number.
name?=NUMBER Test if variable value is a number.
name?INTEGER Test if variable value can be converted to an integer number.
name?=INTEGER Test if variable value is an integer number.
name?REAL Test if variable value can be converted to a real number.
name?=REAL Test if variable value is a real number.
name?BOOLEAN Test if variable value can be converted to a Boolean value.
name?=BOOLEAN Test if variable value is a Boolean value.
name?STRING Test if variable value can be converted to a string value.
name?=STRING Test if variable value is a string value.
name? Test if variable exists.
name Variable name value.

Table related values

Expression tokenizer recognizes a table or table item reference from an opening square bracket [ after a table name.

The following shows table name tokens:

Token Description
name[] Number of rows in a table name.
name[]? Test existence of table name.
name[][] Number of columns in a table name.

Table name item is refered with row index and optional column number:

  name[index]
  name[index][number]

The following shows table item tokens:

Token Description
item?VALUE Test if table item has a non default value. 1
item?NUMBER Test if table item value can be converted to a number.
item?=NUMBER Test if table item value is a number.
item?INTEGER Test if table item value can be converted to an integer number.
item?=INTEGER Test if table item value is an integer number.
item?REAL Test if table item value can be converted to a real number.
item?=REAL Test if table item value is a real number.
item?BOOLEAN Test if table item value can be converted to a Boolean value.
item?=BOOLEAN Test if table item value is a Boolean value.
item?STRING Test if table item value can be converted to a string value.
item?=STRING Test if table item value is a string value.
item? Test if table item exists.
item Table item value.

1 Default table item values are: Empty string for string items, zero (0) for numeric items and False for Boolean items.

EXPRESSION EVALUATOR

Expression evaluator evaluates a list of values and operators and returns the value of an expression.

The expression evaluator supports the following operations in decreasing order of precedence:

Category Operators
Values String, number or Boolean value.
Grouping ( )
Arithmetics ^ * / + -
Concatenation &
Pathname existence pathname?
Comparison ??? ?? LIKE SAME = == > < >= <= ><
Logical AND OR NOT

Values

The following lists value types:

Type Examples
String
Number 123 45.6 7,89
Boolean value True False

Grouping

Grouping of expressions is done with enclosing parentheses ( ).

Parentheses can force some parts of an expression to be evaluated before others. This can override order of operations. Expression evaluator calculates expression value by starting from innermost parentheses and ending to outermost ones.

Arithmetics

Shell supports the following arithmetical operations in the shown order:

Operation Expression Example
Negation -number -123
Exponentation number^number 3^2 => 9
Multiplication number*number 3*2 => 6
Division number/number 3/2 => 1.5
Adding number+number 3+2 => 5
Substration number-number 3-2 => 1

Concatenation

Concatenation operator & joins to values into a single string. Shell converts a value to a string before joining it.

Pathname Existence

Pathname existence is tested using a question mark ? operator after a pathname. A pathname can point to a file or a directory. A directory is recognized when a pathname ends to a backslash \. A pathname can be absolute or relative to the current working folder of shell session (see WORKDIR command).

Comparison Operators

Comparison operators compare two values to determine whether they are equal, and if not, how they differ.

Operation Description
text ??? regexp Compare text against regular expression regexp. 1
text ?? match Compare text against wildchar expression match. 1
text LIKE match Compare text against wildchar expression match. 1
path1 SAME path2 Compare if two paths have same file content.
value = match Compare if two values are the same using case sensitivity. 1
number1 == number2 Compare if two numbers are the same.
number1 >= number2 Compare if a number is equal or greater an other number.
number1 <= number2 Compare if a number is equal or less than an other number.
number1 > number2 Compare if a number is greater than an other number.
number1 < number2 Compare if a number is less than an other number.
value1 <> value2 Compare if two values differ.

1 Case sensitivity of comparison is controlled by Boolean variable IgnoreCase$.

Logical Operators

Logical operators perform computation with Boolean values and return a Boolean value.

Operation Description
NOT value True if value is false.
value1 AND value2 True if both values are true.
value1 OR value2 True if at least one value is true.

USER FORM PROPERTIES

This section explains properties of a user form and its user controls. The section is divided into the following categories:

User Form Layout

Properties Of User Controls

Properties Of Windows Controls

Common Property Value Specifications

FORM Statement Properties

FORM statement properties are divided into the following categories:

Form Window Properties

The following list shows user form's window properties:

Property Description
COLOR color Form background color. 1
FONT table Font property table name. 2
HEIGHT wsize Height of form window. 3
LEFT wsize Left position of form window. 3
MAXBUTTON bool If False then do not show maximize button.
MINBUTTON bool If False then do not show minimize button.
TITLE text Title of form window.
TOP wsize Top position of form window. 3
TOPMOST bool If True keep form window topmost.
WIDTH wsize Width of form window. 3

1 Color properties are inherited to form's controls. See color specification.

2 Font properties are inherited to form's controls. See font specification.

3 Form window size and position can be specified using pixel values or percentages of screen size. A pixel value contains a number followed by "px" suffix, e.g. 600px. A percentage value contains a number between 1 and 100 followed by %" suffix. A negative location value specifies location at screen's opposite side.

The sample below shows a user form with the following properties:

table P_Form
"Top"     -1px
"Left"    -1px
"Height"  50%
"Width"   400px
"TopMost" true
"Title"   "My window"
end table
form P_Form[]
endform

Form Miscellaneous Properties

The following list shows miscellaneous form properties:

Property Description
FOOTERCOLOR color Footer area color. 1
FUNCTION func Name of form's exit function. 2
HEADERCOLOR color Header area color. 1
HELPPATH path HTML help file path. 3
HELPTOPIC text HTML help file context ID.
MENU table Popup menu table name. 4
TABACTIVECOLOR color Color of active tab. 1
TABCOLOR color Color of tabs. 1
TABSTART digit Number of tab sheet shown at startup.
TABSTYLE digit Tab control style. 5
TABTEXTCOLOR color Color of tab text. 1

1 See color specification.

2 Form's exit function is called when the user hits a form command button. System variable FormAction$ contains the name of the selected command button. If exit function sets system variable FormStatus$ value to False then form window is not closed.

3 Value of HTML help file path can contain Windows environment variables or shell variables enclosed with percent (%) signs.

4 Form's popup menu is active at form's command button area and at areas not containing user controls.

5 Tab control style with value SingleRow or 0 (zero) keeps all tabs in one row. Tab control style with value MultiRow or 1 (one) shows multiple tab rows if tabs cannot fit in one row.

The sample below shows a user form with the following properties:

table P_Form
"Menu" "M_Form_Menu"
"Function" "F_Form_Exit"
"TabStart" 2
"TabStyle" "MultiRow"
"Width" 300px
end table
table M_Form_Menu
"Debug" call F_Form_Menu
"Sheet?" call F_Form_Menu
end table
function F_Form_Menu
if (CtrlOption$ = "Debug")
debug
else
msgbox (CtrlName$ & " (" & CtrlNumber$ & ")")
endif
end function
function F_Form_Exit
msgbox query "OK to exit?"
set FormStatus$ (MsgBox$)
end function
form "" P_Form
sheet "First Long Sheet Name"
label "Sheet number 1"
sheet "Second Long Sheet Name"
label "Sheet number 2"
sheet "Third Long Sheet Name"
label "Sheet number 3"
endform

The sample below shows how to assing a help topic to form's Help command button:

table P_Form
"HelpButton" P_HelpButton
"HelpPath"   "%Client$%\Link-It6.chm"
"HelpTopic"  "/4_Settings/Settings_UI.htm"
end table
table P_HelpButton
"ButtonLabel" "My Help"
end table
form "" P_Form
endform

Form Color Defaults

The following properties specify default colors for form controls:

Property Description
COLOREDIT color Default background color when editing text field. 1
COLORERROR color Default background color for text field containing errors. 1
COLORLOCKED color Default background color for locked text field. 1
COLORWARN color Default background color for text field containing warning. 1

1 See color specification.

Form User Control Defaults

The following properties specify default values for user controls:

Property Description
BUTTONWIDTH percent Default proportional width for command buttons.
CHECKALIGN align Default alignment for check boxes. 1
EDITMENU table Default table name for text edit popup menu.
IMAGEDIR path Default folder path of images. 2
IMAGESIZE digits Default image size in pixels. 2
LABELALIGN align Default alignment for label texts. 1
LABELWIDTH percent Default proportional width for labels.
SHOWWIDTH percent Default proportional width for show fields.
TABLE table Default table name for non-table control items.
TYPECHECK bool Default value for control's type check.

1 See aligment_specification_frm_prop aligment specification.

1 See image_specification_frm_prop image specification.

Form Command Buttons

Form's command buttons are located at the bottom area of a user form. A user form can contain four (4) command buttons whose properties are specified using a separate property table. The following list contains user form properties which specify property table names for command buttons:

Property Description
OKAYBUTTON name Property table name of 1st button from left (OK). 1
APPLYBUTTON name Property table name of 2nd button from left (Apply). 1
CANCELBUTTON name Property table name of 3rd button from left (Cancel). 1
HELPBUTTON name Property table name of 4th button from left (Help). 1

The following lists properties for a user form command button:

Property Description
COLOR color Button color. 1
ENABLED boolean If False then button is disabled.
FONT table Table name containing font properties. 2
LABEL text Button label text.
IMAGE image Button image name. 3
TOOLTIP text Tool tip text.
VISIBLE boolean If False then button is invisible.

1 See color specification.

2 See font specification.

3 See image specification.

The following lists renamed legacy properties:

Legacy property New property
BUTTONCOLOR COLOR
BUTTONFONT FONT
BUTTONIMAGE IMAGE
BUTTONPICTURE IMAGE
BUTTONLABEL LABEL

SHEET Statement Properties

The following list shows SHEET statement properties:

Property Description
COLOR color Sheet background color. 1
FUNCTION func Name of sheet function. 2
CTRLFUNC func Name of common function for sheet's controls. 3
ENABLED bool If True (*) then sheet is enabled.
LABEL name Sheet name shown in tab.
LOCKED bool If True (*) then sheet is locked.
TABLE table Default table name for non-table control items.
VISIBLE bool If True (*) then sheet is visible.

1 Color properties are inherited to sheet's controls. See color specification.

2 Sheet function is called when user enters a sheet

3 Common control function is called every time a user leaves sheet's control but after calling optional control's function. Use system variables starting with Ctrl to get information about control which called the function.

FRAME Statement Properties

FRAME user control has a frame control which is in a picture box container.

frame

FRAME statement propertys are divided into the following categories:

BUTTON Statement Properties

BUTTON user control has a button control which is in a picture box container.

button

BUTTON statement propertys are divided into the following categories:

COMBO Statement Properties

COMBO user control has label text and combobox controls in a picture box container.

label text combobox

The user control has also an optional menu button control.

label text combobox menu

COMBO statement propertys are divided into the following categories:

COMBO2 Statement Properties

COMBO2 user control has label text, combobox,

label text combobox showbox menu

COMBO2 statement propertys are divided into the following categories:

CONTROL Statement Properties

CONTROL statement defines type of a user control using the following rules:

CONTROL statement properties are the same than properties of its control type:

LABEL Statement Properties

LABEL user control has a label text control which is in a picture box container.

label text

LABEL statement properties are divided into the following categories:

MATRIX Statement Properties

MATRIX user control shows the contents of a data table in a matrix control which is in a picture box container.

header1 header2 header3
index 1 1 item 1 2 item 1 3
index 2 1 item 2 2 item 2 3

MATRIX statement propertys are divided into the following categories:

MENU Statement Properties

MENU user control has label text, textbox and menu button controls in a picture box container.

label text textbox menu

MENU statement propertys are divided into the following categories:

MENU2 Statement Properties

MENU2 user control has label text, textbox, showbox and menu button controls in a picture box container.

label text textbox showbox menu

MENU2 statement propertys are divided into the following categories:

PICTURE Statement Properties

PICTURE user control has a picture box control which is in a picture box container.

PICTURE statement propertys are divided into the following categories:

QUERY Statement Properties

QUERY user control can query text or Boolean value.

Query Text Value

When quering a text value a QUERY user control has label text and textbox controls in a picture box container.

label text textbox

QUERY statement propertys for a text value are divided into the following categories:

Query Boolean Value

When quering a Boolean value a QUERY user control has label text and checkbox controls in a picture box container.

label text

QUERY statement propertys for a Boolean value are divided into the following categories:

RICHTEXT Statement Properties

RICHTEXT user control has a richtext control which is in a picture box container.

RICHTEXT statement propertys are divided into the following categories:

SHOW Statement Properties

Common Properties For User Controls

A user control contains one or more Windows controls which are collected into a container. The container is a picture box and has its own properties which are common to all user controls. The following list contains common properties for user controls.

Property Description
COLOR color Background color. 1
ENABLED bool If False then the user control is disabled.
FONT table Name of table containing a font specification. 2
IMAGEDIR path Folder path for images. 3
IMAGESIZE digits Image size in pixels. 3
LOCKED bool If False then the user control is locked.
TOOLTIP text Tooltip text to show when cursor is on top of the user control.
VISIBLE bool If False then the user control is invisible.

1 See color specification.

2 See font specification.

3 See image specification.

Button Control Properties

The following list shows button control properties.

Property Description
ALIGN align Button alignment. 1
BUTTONHEIGHT height Button height in pixels.
COLOR color Button color. 2
FONT table Name of table containing font specification. 3
FORECOLOR color Button forecolor. 2
FUNCTION name Function name to call when user presses the button.
IMAGE image Name of button's image. 4
LABEL text Button's label text. 5
MENU table Popup menu table to show when user presses the button. 6
STYLE style Button style. 6
TOOLTIP text Tooltip text to show when cursor is on top of the control.
WIDTH width Button's width. 7

1 See alignment specification.

2 See color specification.

3 See font specification.

4 See image specification.

5 If button has an image then label text is not shown.

6 Button's function is called with three arguments related to the selected menu item:

7 If button's width is zero 0 then button is autosized.

The following lists renamed legacy properties:

Legacy property New property
BUTTONALIGN ALIGN
BUTTONCOLOR COLOR
BUTTONFONT FONT
BUTTONLABEL LABEL
BUTTONIMAGE IMAGE
BUTTONPICTURE IMAGE
BUTTONWIDTH WIDTH

Menu Button Control Properties

The following lists menu button control properties used by MENU and MENU2 statements.

Property Description
BUTTONALIGN align Button alignment. 1
BUTTONCOLOR color Button color. 2
BUTTONENABLED bool If False then button is disabled.
BUTTONFONT table Button font table name. 3
BUTTONLABEL name Button name.
BUTTONIMAGE image Button's image. 4
BUTTONWIDTH width Button's proportional width. 5
TOOLTIP text Tooltip text to show when cursor is on top of the control.

1 See alignment specification.

2 See color specification.

3 See font specification.

4 See image specification.

5 If button's proprotional width is zero then the button is autosized.

Checkbox Control Properties

The following list shows checkbox control properties.

Property Description
CHECKALIGN align Checkbox alignment.1
CHECKCOLOR color Checkbox color.2
TOOLTIP text Tooltip text shown when cursor is on top of control.

1 See alignment specification.

2 See color specification.

Combo Control Properties

The following list shows combo control properties:

Property Description
COMBOCOLUMN number Number of table colum to populate list values from.
COMBOMODE text Autocomplete mode of value list. 1
COMBOSORTED bool If True then sort value list.
COMBOTABLE table A table to populate list values. Default column is 1.
EDITMENU table Edit menu table name.
FORMAT format Value formatting.2
IMEMODE bool If True then IME mode is on.3
MAXLEN length Maximum number of input characters.
TEXTFONT table Text font table name.4
TEXTWIDTH width Text box width.
TOOLTIP text Tooltip text.
TYPECHECK bool If True then check value.5

1 Combo list autocomplete modes are SUGGESTAPPEND (default), SUGGEST, APPEND and NONE.

2 See value formatting specification.

3 See IME mode specification.

4 See font specification.

5 See value check specification.

Label Control Properties

The following list shows label control properties.

Property Description
LABEL text Label text.
LABELALIGN align Label text alignment. 1
LABELFONT table Label text font property table. 2
LABELWIDTH width Label text propertional width. 3
TOOLTIP text Tooltip text.

1 See alignment specification.

2 See font specification.

3 If label width is zero then label is autosized.

Picture Control Properties

The following list shows picture control properties:

Property Description
ALIGN align Picture box alignment. 1
IMAGE image Picture's image name. 2
PICTUREHEIGHT height Picture box height.
PICTUREWIDTH width Picture box width. 3
TOOLTIP text Tooltip text to show when cursor is on top of the control.

1 See alignment specification.

2 See image specification.

3 Picture's width is calculated using to following rules:

width height Picture's width
= 0 = 0 Sheet's width
> 0 = 0 width
= 0 > 0 height * ( width / height )
> 0 > 0 width

The following lists renamed legacy properties:

Legacy property New property
PICTUREALIGN ALIGN
PATH IMAGE
PICTUREPATH IMAGE

Richtext Control Properties

The following list shows richtext control properties.

Property Description
TEXTPATH path Text file path.
TOOLTIP text Tooltip text.

Showbox Control Properties

The following list shows showbox control properties:

Property Description
SHOWFONT name Font table name.1
SHOWWIDTH width Show box width.
SHOWCOLOR color Background color.2
TOOLTIP text Tooltip text.

1 See font specification.

2 See color specification.

Textbox Control Properties

The following list shows textbox control properties:

Property Description
FORMAT format Value formatting.1
EDITMENU table Edit menu table name.
IMEMODE bool If True then IME mode is on.2
MAXLEN length Maximum number of input characters.
PASSWORDCHAR char Show all characters using the given character.
TEXTCOLOR color Textbox background color.3
TEXTFONT table Text font table name.4
TEXTWIDTH width Text box width.
TOOLTIP text Tooltip text.
TYPECHECK bool If True then check entered value type.5

1 See value formatting specification.

2 See IME mode specification.

3 See color specification.

4 See font specification.

5 See check value specification.

Frame Control Properties

The following list shows frame control properties:

Property Description
BORDERCOLOR color Border color.1
BORDERSTYLE style Border style.2
COLOR color Background color.1
FONT table Text font table name.3
LABEL text Frame panel label text.
STYLE style Frame style.4

1 See color specification.

2 Border style has the following values:

3 See font specification.

4 Frame style has the following values:

Matrix Control Properties

MATRIX statement's matrix control is a datagridview control whose properties are divided into the following categories:

Matrix Grid Properties

The following list shows grid properties or MATRIX statement:

Property Description
COLOR color Grid background color.1
COLUMNS count Number of columns in grid.
EDITMENU table Table name of text edit menu.
FONT table Table name of grid text font definition.2
IMAGEDIR path Folder path of grid images.
IMAGESIZE path Image size in pixels.
IMAGEZOOM bool If true then fit image into owner control.
IMEMODE bool If true then IME mode is on.3
MAXROWS count Max number of rows in grid.
MENU table Table name of grid context menu.
MENUENABLED bool If true then grid menus as enabled.
MENULOCKED bool If true then show menu when entering a locked cell.
ROWADD bool If true then rows can be added.
ROWDELETE bool If true then rows can be deleted.
ROWS count Number of visible rows.
SELECT option Row selection mode.4
SELECTTABLE table Table name for selected rows.4
SORTABLE bool If true then grid columns are sortable.
STRETCH bool If true then grid streches.5
TOOLTIP text Grid tooltip.
TYPECHECK bool> If true then grid column values are checked.

1 See color specification.

2 See font specification.

3 See IME mode specification.

4 Grid selection mode enables selection of grid rows. The selected rows are stored to SelectTable$ table by default. Use SELECTTABLE option to specify another result table. Selection modes are:

5 Grid streching increases heights of grids on the same user form sheet with an equal amount of heights to fill the lower empty area of the sheet. Grid stretching occures only in form stretch area (see Form definition) but not in form header or footer area.

Matrix Row Properties

Matrix row properties are defined using a data table whose index values are same than matrix table indexes. Property's value is read from column number.

Property Description
ROWCOLOR table:number Define colors of matrix rows.
ROWLOCKED table:number Define locking of matrix rows.
ROWVISIBLE table:number Define visibility of matrix rows.

Matrix Column Properties

Matrix column property name starts with COLUMNn: prefix which specifies column's number n. The following list shows matrix column number n properties:

Property Description
COLUMNn:ALIGN align Value alignment.1
COLUMNn:COLOR color Column background color.2
COLUMNn:DEFAULT value Default value for column cells.
COLUMNn:HEADERMENU table Column header popup menu table name.
COLUMNn:EDITMENU table Text edit popup menu table name.
COLUMNn:FUNCTION func Name of column function.
COLUMNn:INDEXMENU prefix Prefix of index menu table names.
COLUMNn:LABEL text Column label text.
COLUMNn:LOCKED bool If True then column is locked.
COLUMNn:MENU table Column popup menu table name (unless cell menu).
COLUMNn:MENULOCKED bool Show menu on a locked cell.
COLUMNn:SORTABLE bool If True then column is sortable.
COLUMNn:SORTTYPE type Column sort type.3
COLUMNn:TYPE type Column type (TEXT, CHECK, IMAGE).
COLUMNn:TYPECHECK bool Check entered value type.
COLUMNn:VISIBLE bool If False then column is hidden.
COLUMNn:WIDTH width Column width.

1 Alignment values are LEFT, CENTER and RIGHT.

2 See color specification.

3 Column's SORTTYPE property specifies how column values are sorted when user clicks column's header:

4 Column's TYPE property specifies the type type of cells in a column:

Matrix Cell Properties

Matrix cell properties are defined using a data table whose index values are same than matrix table indexes. Property's value is read from given column.

Name of matrix cell property starts with COLUMNnumber: prefix which specifies the number of cell's matrix column. The following list shows matrix cell properties for column n:

Property Description
COLUMNn:CELLCOLOR table:col Get cell's backgroup color from column col of data table.1
COLUMNn:CELLMENU table:col Get cell's popup menu name from column col of data table.

1 See color specification.

Common Specifications

This section contains the following common property value specifications:

Alignment Specification

A user control contains a panel box and one or many Windows controls which lie in a row on top of the panel box. Each Windows control has its own rectangle area whose height is user control's height and width is either a fixed pixel value or a proportional part of user control's width. The alignment of a Windows control happends in its own rectangle area.

The following list shows control alignment values:

Alignment Description
LEFT Align control at left.
CENTER Align control to center.
RIGHT Align control to bottom.
TOP Align control at top.
MIDDLE Align control at middle.
BOTTOM Align control at bottom.

If a user control contains a label text then it is the leftmost control in a user control. Use the following values to change label text location in a user control:

Alignment Description
LEFTMOST Label text is the leftmost control.
RIGHTMOST Label text is the rightmost control.

Use semicolon (;) to separater alignment values.

Legacy: Label text location can also be switched to user control's rightmost control by starting the alignment value with a minus sign (-).

Color Specification

Color can be specified in the following ways:

Font Specification

Font is specified with a property table that contains properties of font characteristics.

Font specification table can contain the following properties:

Property Description
BOLD boolean If True then show bold text.
COLOR color Font color. 1
ITALIC boolean If True then show italic text.
NAME name Windows font name. 2
SIZE esize Font size in em.
STRIKEOUT boolean If True then show strikeout text.
UNDERLINE boolean If True then show underlined text.

1 See color specification.

2 Use Windows typeface font names like Arial, Impact, Tahome, Courier New or Times Roman New. See list of Windows typefaces.

Folder Specification

Shell uses the following rules to search for a folder path:

Image Specification

The image of a user control has the following properties:

Image Name

Shell uses the following rules to define an image from IMAGE property value:

Image Folder

By default, a relative image file path of a user control is searched from script file's folder. This can be changed by specifying image folder path to IMAGEDIR property of user control or user form.

Relative paths of popup menu images use always folder of IMAGEDIR property value.

Image size

Control's image is scaled to fit inside the control by default.

Image's size can be defined with IMAGESIZE property by using the following format:

xsize[;ysize]

If only xsize is defined then images's width and height are xsize pixels. Otherwise images's width is xsize pixels and image's height is ysize pixels.

IME Mode Specification

When IME mode is on then the text field editing happens under Input Method Editor (IME).

An Input Method Editor (IME) allows users to enter and edit Chinese, Japanese, and Korean characters. The IME is an essential component for writing Chinese, Japanese, and Korean scripts. These writing systems have more characters than can be encoded for a regular keyboard. The IMEs for these languages use sequences of base characters that describe an individual character or group of characters to allow you to enter a larger set of characters. Base characters can be component letters from Hangul syllables, phonetic components for Japanese Kanji characters, or various

For more information about IME mode see Installing and Using Input Method Editors.

Popup Menu Specification

Shell builds a popup menu from a menu table. Each table row represents one menu item. A popup menu can have the following menu item types:

Popup Menu Data Item

The data item is defined using the following data:

Column Value Description
1 caption Data item caption shown in popup menu.
2 value Text value inserted into releated text field.
3 Empty
4 image Optional data item image. See image specification.

When user selects a data item from a popup menu its value is inserted into a related text field of a user control.

Popup Menu Title Item

The title item is specified using the following data:
Column Value Description
1 ---text--- Title text shown in menu.
2 Empty
3 Empty
4 image Optional data item image. See image specification.

Popup menu title item shows title text in popup menu. The menu item is disabled, text is italic and menu item background is grey.

Popup Menu Separator Item

The separator item is specified using the following data:
Column Value Description
1 ---id Optional identifier id is not shown.
2 Empty
3 Empty
4 Empty

Popup menu separator item shows a separator line in a popup menu. If a menu table has multiple separator lines then identifiers must differ.

Popup Menu Submenu Item

The submenu item is defined using the following data:

Column Value Description
1 caption Submenu caption shown in popup menu.
2 TABLE A word without quotes.
3 name Menu table name.
4 image Optional data item image. See image specification.

When a submenu item is selected it opens a submenu which is build using attached menu table.

Popup Menu Function Item

The function item is defined using the following data:

Column Value Description
1 caption Function caption shown in popup menu.
2 CALL A word without quotes.
3 name Function name to call.
4 image Optional data item image. See image specification.

When a function item is selected the shell updates some system variables and function arguments and then calls the attached function.

For more informaton about updated variables see Active user control variables.

Shell populates the following function arguments if they exist:

.