Tivoli Service Desk 6.0 Developer's Toolkit Tools and Utilities Guide
The TSD Script Parser translates ASCII text files that contain Developer's Toolkit source code into a binary format used to build application files. The TSD Script Parser translates .kb files to .kbc files.
The TSD Script Parser is available in both a command prompt version (kp.exe) and a windowed version (kpw.exe).
Note: These are the same in UNIX except for the .exe extension.
When the TSD Script Parser searches for a source file that has no explicitly specified directory, it checks directories in the following order:
You can open the TSD Script Parser using either one of the following methods:
kpw [option] [.kb file ...]
The TSD Script Parser dialog box is used to specify the file .kb to parse and to set parse options.
Note: Using the switches at the command prompt is the same as typing commands in the text boxes.
- File Name specifies the .kb file to parse.
- Browse accesses a dialog box used to locate and select a source file instead of typing the file name in File Name.
- Parse Options:
~ Parse parses only the specified .kb file.
~ Update parses all .kb files referenced in an application. If a .kbc file already exists that is not older than the current
source code, the TSD Script Parser does not reparse the file.
~ Build translates the specified .kb file referenced in any USES section in a parsed .kb file. If you select this option and
the .kb file contains the application's entry point, you rebuild the entire application.
- Connect String enables you to set the DBMS connection string.
- Error Message Filename specifies the file where error messages generated by the TSD Script Parser should be sent. If no error messages are generated, the specified file is removed automatically.
- Assert Symbol is used for conditional translation. You specify an identifier that is added to the TSD Script Parser's internal database so that source text enclosed in the #IF ... #ENDIF construct is translated.
- Deny Symbol is used for conditional translation. You specify an identifier that is removed from the TSD Script Parser's internal database so that source text enclosed in the #IF ... #ENDIF construct is ignored by the TSD Script Parser.
- Additional Search Dirs specifies a path whose directories are added to the list of directories that are searched when the TSD Script Parser locates the source text path. The path may consist of any number of fully qualified directory names separated by semicolons.
- Cross-Reference specifies a database in which three tables are created. These tables contain information on the definition and use of global constants, types, variables, routines, SQL tables, text files, icon files, and bitmap files.
- Listing Filename specifies the file where a list generated from the source text is sent. If no file name is specified, the list is sent to standard output.
- Code Page (Windows only) specifies whether the ANSI default or OEM code page is used when writing strings to the .kbc output file.
Before parsing only one file, make sure the changes you made to the file do not affect other .kb files.
Use the Build option to parse your entire application when you have made changes to more than one .kb file. This will assure that all the changed .kb files will be parsed.
Note: It is recommended that you choose the Build option if you do not know what affect a changed .kb file has on other .kb files.
The command line version of the TSD Script Parser accepts the following arguments:
-a, -b, -c, -d, -e, -f, -u, -l, -m, -o, -p, -q, -s, -x, -ide, -help
Note: You can automatically set the TSD Script Parser to use parse commands by editing the TDT KML Parser section in the softart.ini file.
A parameter can follow the argument character (with no space) or precede it with an equal symbol (=) or colon (:). For instance, the following examples achieve the same effect:
-uf:\sai\ea
-u=f:\sai\ea
-u:f:\sai\ea
Valid arguments for the TSD Script Parser are shown in the following table.
Argument | Value | Comment |
-a<identifier> | Assert | Installs the identifier in the TSD Script Parser's internal database so source text enclosed in the #IF ... #ENDIF construct is translated. More information on assert symbols can be found in the documentation specific to your application. |
-b | Build | Initiates the TSD Script Parser to translate any specified .kb files at the command prompt. Also parses .kb files referenced in any USES section. If you specify the -b option when you parse the .kb file containing an application's entry point, the TSD Script Parser rebuilds the application. |
-c <drive> <path> | n/a | Switches to the specified drive and directory. |
-d <identifier> | Deny | Removes the identifier from the TSD Script Parser's internal database so source text enclosed in the #IF ... #ENDIF construct is ignored. |
-e <file> | Error | Sends error messages generated by the TSD Script Parser to the specified file. If no error messages are generated, the specified file is removed automatically. |
-f <path> <module> .KB | Shorthand Notation | Equates to typing the line: kp-u=<path> <module> |
-l -l <file> -l+ |
List | Generates a list of source text. If you specify the -l option, the list is sent to standard output. If you specify a file name (-l<file>), the list is sent to the file. If you specify the -l+ option, the list is sent to a file whose name consists of the .kb file name with a .lst extension. (The .kb file name may be altered to the filenaming conventions of the operating system). Error messages generated by the TSD Script Parser are written to the list file unless another error file is specified using the -E option. |
-m | Make | Initiates the TSD Script Parser to parse the .kb file referenced in an application. If a .kbc file exists that is not older than the current source code, the TSD Script Parser does not reparse the file. |
-o <directory> -o=<directory> -o:<directory> |
n/a | Specifies the output directory where all generated kbc files are written. By default, the Parser generates .kbc files to the directory where the .kb file is. |
-p=oem -p=ansi -poem -pansi (Windows only) |
n/a | Specifies the OEM or ANSI code page to use when writing strings to the .kbc output file. If not specified at the command prompt, the Parser uses the value read from the softart.ini file. Otherwise, the ANSI code page is used (EPSDIC in UNIX.) |
-q | Quiet | Suppresses display of copyright banners and progress messages, which are otherwise sent to standard output. |
-s <string> | n/a | Sets the DBMS connection string to <string>. |
-u <path> | Use | Adds directories in the path to the list of searched directories when the TSD Script Parser locates source text for a .kb file. The path may consist of many qualified directory names separated by semicolons. (In UNIX, directory names are separated by colons.) |
-x <database> | Cross-Reference | Creates three tables in the specified database that contains information on the definition and usage of global constants, types, variables, routines, SQL tables, text files, icon files, and bitmap files. |
-ide | IDE | Alters the format of error messages generated by the TSD Script Parser so the Tivoli Service Desk (TSD) Developer's Toolkit IDE can find the appropriate source text where the errors were. |
-help/? | Help | Displays a usage summary in standard output. |
If the Developer's Toolkit source code to be parsed contains any IMPORT declarations, you must be connected and logged on to the appropriate database manager, and the necessary database(s) must be bound. Otherwise, error messages are generated.
Using the IMPORT declaration to import data from a database results in the creation of a temporary file. This file, kmlimprt.out, is automatically removed on import completion.
If the TSD Script Parser terminates unexpectedly, deletion of this file may not be completed. You can manually delete this file as long as the TSD Script Parser is not running.
The -S option enables you to specify the database at parse time and eliminates the need to hard code the database source name.
The -S option also enables you to specify the user ID and password at parse time when running the TSD Script Parser from the command prompt. Any values specified in the sai_sql.cfg file are ignored.
The preferred method for using the -S option is to specify all values except the user ID and password in the sai_sql.cfg file. Then, at parse time, pass in these values. For example:
-S"UID=UserId; PWD=Password"
where UserId is the user ID and Password is the user's unique password.
The Developer's Toolkit language is designed to allow .kb files to use each other. When .kb files use each other, each .kb file defines a record type that is accessed by the other. This results in circular usage. In other words, .kb file A cannot use .kb file B's PUBLIC section if B already uses A's PUBLIC section. Circular usage is supported by Developer's Toolkit, but it is not supported by the TSD Script Parser.
To avoid circular usage, move all affected record declarations into a separate .kb file that is used by both of the original .kb files. The two original .kb files can then continue to reference each other's variables and routines.
The following table summarizes the error conditions reported by the TSD Script Parser. (These errors are common to the graphical windows parser, as well as command line.)
Caution: Missing semicolons can cause many errors. If you have an error you do not understand, make sure that semicolons are present.
Error | Explanation |
$CURRENT is not a valid index for an array. | An attempt was made to index an array expression with the special index $CURRENT. This index is only valid for list expressions. |
$EVENT is not defined in the scope of <function>. | The function is not an event handler, and it is not nested in the scope of an event handler, so the symbols associated with event handling are not defined. |
$EVENTPARM is not defined in the scope of <function>. | The function is not an event handler, and it is not nested in the scope of an event handler, so the symbols associated with event handling are not defined. |
$HANDLE is not defined in the scope of <function>. | The function is not an event handler, and it is not nested in the scope of an event handler, so the symbols associated with event handling are not defined. |
$NullHandler may not have an initialization argument when used as an argument to <creation routine>. | Passing an initialization argument to $NullHandler when used with the given creation routine serves no purpose. |
#ELSE encountered without a matching #IF. | The TSD Script Parser read the preprocessor directive without encountering a matching #IF directive. |
#ENDIF encountered without a matching #IF. | One of these preprocessor directives was read without having seen a matching #IF directive. |
<name> is not a defined type. | The given name was encountered in a context where a type specification was expected. |
<name> is not a field of the given record type. | An expression that refers to a field by name gives a name that does not belong to any field in that record. |
<name> is not a function or procedure. | A call expression refers to an object that is not a routine. |
A comma (,) is missing. | The TSD Script Parser did not encounter a comma it expected. |
A file write error occurred. | A file write operation failed after a successful open operation. Usually indicates an internal software error. |
A parameter passing protocol (either VALue or REFerence) must be specified. | A formal parameter declaration must be prefixed with a VAL or REF keyword to specify which protocol is used when the routine is called. |
All selectors in a WHEN statement must have the same type. | A selector (or selectors) in a WHEN clause with multiple selectors has a different type than other selectors in the WHEN clause. |
An event handling function is required. | Only event-handling functions can be passed to creation routines for windows, dialog boxes, and other event generating objects. |
An unexpected delimiter was encountered. | The last specification in a formal parameter list has an unnecessary trailing comma. |
Argument #<n> (<name>) to function <routine> is invalid. | The type of argument does not match the type of corresponding formal parameter. |
Constant expression required. | A constant expression is required in the current context. |
Constant <name> is never referenced in the scope of <name>. | The constant is declared but not used. |
Did not find #ENDIF to match directive on line <n>. | The TSD Script Parser reached the end of the source file without finding an #ENDIF directive matching the #IF or #ELSE on the given line. |
Event handler type of <name> does not match forward declaration. | A FORWARD or PUBLIC declaration for the event handler specified a different event type than what is specified in the declaration. (WINDOW is the default event type to be handled.) |
Event handler <name> may not be declared with a return type. | A routine declared as an event handler may not have a return type specified. Event handlers always return an integer. If no value is returned, 1 is the default value. |
Event handling function <name> does not handle the type of events generated for the object created by <creation routine>. | Window event handlers cannot handle events for Process objects, and vice versa. |
Event handling function <name> may not have more than one formal parameter. | The given event handler was declared with more than one formal parameter. |
Event handling functions can only appear at the outermost scope. | An event handler cannot be nested inside another routine. |
Expression does not refer to an accessible location. | An assignment (or other expression that affects the value of an object) requires an accessible and mutable object to operate. |
Expression cannot be passed by reference. | An expression that does not evaluate to an accessible, mutable object cannot be passed as a REF parameter. |
Forward declaration for <variable_name> does not match forward declaration of <Routine_name> | The PUBLIC ROUTINES section does not match the PRIVATE ROUTINES section. Make sure the arguments in each section match and are of the same data type. |
Forward function <function> has no effective implementation. | The function was declared publicly or by a FORWARD declaration, however, it has no effective declaration. |
fread() in flex scanner failed | The source .kb file became unreadable after it was opened. Usually caused by a disk or network failure. |
Function <name> is missing a return type declaration. | A routine declared as a function must have a return type. |
Function <name> is never referenced in the scope of <name>. | The routine is declared but not used. |
Function <name> cannot be called in a procedural context. | The named function returns a value that cannot be ignored. |
INTERNAL ERROR detected at line <n> in <file>. | An error condition exists in the TSD Script Parser. Note the file name and line number and contact Tivoli Systems Customer Support. |
Invalid $EXPORT annotation. Valid annotations are: LITTLE_ENDIAN, INTEL, BIG_ENDIAN, ASCII, EBCDIC, CUSTOM_CONVERT(...) and CTYPE(...) | An annotation not in the list of valid annotations appeared in the $EXPORT clause of a record declaration. |
Invalid coercion from type <type-1> to type <type-2>. | It is invalid to coerce between the types in the current context. |
Invalid control expression in FOR loop. | The FOR statement may only iterate over integer ranges and the contents of a list. |
Invalid declaration. | Invalid syntax was found in a location where the TSD Script Parser expected to find a declaration. |
Invalid expression. | A syntax error was found in a context where the TSD Script Parser expected to find an expression. |
Invalid expression type. | A different type was expected. |
Invalid field annotation. | An annotation that may not be applied to a field was found. The LITTLE_ENDIAN, INTEL, BIG_ENDIAN, CUSTOM_CONVERT(...), and FILL(...) annotations are invalid in this context. |
Invalid identifier: <string>. | An identifier specified on the command prompt (as a .kb file name or as part of an -a or -d option) does not fit the lexical specifications for a Developer's Toolkit identifier. |
Invalid operand to <op> operator. | The operator requires an operand of a different type. |
Invalid option: <???>. | The TSD Script Parser encountered an unknown command prompt switch. |
Invalid pseudofield annotation. | An annotation that cannot be applied to a pseudofield was found. Only the FILL(...) and VALUE(...) annotations are legal in this context. |
Invalid redeclaration of symbol <symbol>. | The symbol has more than one definition in the same scope. |
Invalid statement. | A syntax error was found where a statement was expected. Make sure that required semicolons are present. |
Invalid type specification. | A syntax error was found where a type specification was expected. |
Invalid WHEN statement expression type. | The WHEN statement can only select INTEGER or STRING types. |
KB file <kb-1> references type <typename>
which is defined in .kb file <kb-2>, but does not list <kb-2>among the .kb files which it uses. |
A type is referenced for with no corresponding definition. This usually occurs when a record defined in one .kb file contains a field of a type defined in a second .kb file, while a third .kb file uses the first .kb file instead of the second, attempts to access the field. |
.KB file name <name-1> does not match the name (<name-2>) by which it is known externally. | The name in the KNOWLEDGEBASE declaration at the beginning of the .kb file does not match the name by which it was accessed from the command line or by a USES declaration in another .kb file. |
Parameter count for function <function> does not match FORWARD declaration. | A FORWARD or public declaration of a function specified a different number of parameters than is specified by the effective declaration. |
Parameter declaration for <parameter> does not match the FORWARD declaration of <function>. | A FORWARD or public declaration of a function specified the parameter differently (a different type or different parameter-passing protocol) than the effective declaration. |
Parameter name <name-1> does not match <name-2> from FORWARD declaration of function <function>. | A FORWARD or public declaration of a function specified the same formal parameter under a different name than the effective declaration. |
Parameter <name> of function <function> is never referenced. | The parameter is declared but not used. |
Procedural function <name> has no $RESULT. | The $RESULT pseudo-variable may not be referenced inside a routine declared as a procedure. |
Procedure <name> cannot be declared with a return type. | A routine declared as a procedure cannot have a return type. |
Selector <value> cannot appear multiple times in a WHEN statement. | Each selector can appear only once in a WHEN statement. |
Specified size (-<n>) may not be negative. | An array or list was declared with a negative initial size. |
Symbol <symbol> is defined in both <.kb file-1> and <.kb file-2>. | The given symbol is publicly defined in both .kb files. This is a warning as the second definition shadows the first. |
Symbol <symbol> is undefined. | The symbol was used in an expression or declaration without being defined. |
Symbol <symbol or variable name> is undefined. | A variable is used in the ACTIONS section that was not declared in the VARIABLES section locally, globally, or in the USES chain. |
The argument to an event handler must be passed by reference. | The formal parameter to an event handler was not specified with the REF keyword. |
The declaration of <symbol> is missing a colon (:) delimiter. | A colon delimiter is missing from the declaration. |
The declaration of <symbol> is missing the IS keyword. | The IS keyword is missing from the declaration. |
The predefined symbol <symbol> cannot be redefined. | The symbol is predefined in the Developer's Toolkit language and cannot be given a new definition by application code. |
Too many types defined (more than 65000). | There is an internal error condition in the TSD Script Parser. |
Type <name> is never referenced in the scope of <name>. | The type is declared but not used. |
Type <type> is not a RECORD type. | A record type is required in the current context. |
Type <type> cannot be indexed. | An attempt was made to index an expression that was not an array, list, or string type. |
Type of initialization argument #<n> is invalid. | The type of initialization argument does not match the type of corresponding parameter, field, or element. |
Type returned by <function> does not match forward declaration. | A FORWARD or public declaration of a function specified a different return type than is specified by the effective declaration. |
Unable to allocate a <n> byte block at line <m> in <file>. | The TSD Script Parser ran out of memory while parsing the source code which may cause the operating system to lock up. Unless the value given for n is extremely large (which may indicate an internal error), this message is rare unless you are running the debugging heap manager. The only way to run out of memory is to run out of swap space. |
Unable to coerce value <v> to type <type>. | The TSD Script Parser is unable to coerce the constant value to the specified type. |
Unable to IMPORT <view>, error code = <n>. | An IMPORT declaration failed. The database may not be bound or the machine may not be connected and logged to the appropriate database manager. |
Unable to locate file <file>. | The named file was not found by the TSD Script Parser. Directories include the current one, where Developer's Toolkit i420.dll is located, and the directories specified in the SAIPATH, dpath environment variable, or by the -u command prompt argument. |
Unable to make <path> the current directory. | The directory specified with the -c command prompt switch is inaccessible. |
Unable to open file <file>. | The file open operation failed. Likely caused by appropriate rights. |
Unexpected selector type. | The type of selector in a WHEN clause does not match the type of the controlling expression. |
Unrecognized character <char> encountered. | An unrecognized character was found. |
Unrecognized preprocessor directive. | A line beginning with a '#' character was found and the directive was something other than #ASSERT, #DENY, #IF, #IFNOT, #ELSE or #ENDIF. |
Unterminated comment beginning on line <n>. | The end of the source file was reached without finding a ';*)'; character sequence to match the ';(*'; sequence on the given line. |
Unterminated string. | The end of a line was reached without finding the quote character to close a string literal. |
Untrapped syntax error at or near column 0 of line 12. | The keyword ROUTINES is missing, the keyword KNOWLEDGEBASE at the top of the file is spelled incorrectly, or one of the ACTIONS, WHILE, or IF sections is missing an END statement. |
Variable <name> is never referenced in the scope of <name>. | The variable is declared but not used. |
Wrong number of arguments to <type> initializer. | The initializer for the type requires a different (probably smaller) number of arguments. |
Wrong number of arguments to function <name>. | The named routine requires a different number of arguments than the number provided in the call expression. |
Wrong number of arguments to function <procedure_name>. Expected <number>. Received <number>. | When the procedure, function, or event is called in the ACTIONS section of the .kb file, it does not match the formal definition. |
Unable to find a file with the name <filename-1>. Using <filename-2> instead. | If you specify a .kb file name in the USES section of a .kb
file, it should have the same case as the file containing the .kb file. If it does not,
the TSD Script Parser attempts to find it, displaying this message if it succeeds. Note: This will not be supported in future releases. |
Expected non-obsolete syntax for WinSetMousePointer. Replace with WinSetWaitPointer. | The WinSetMousePointer statement in version 4.2 and earlier versions has been modified to support multiple windows in TSD Developer's Toolkit 5.0. To remain compatible with the old syntax, the TSD Script Parser translates it to a new function (WinSetWaitPointer) that performs the old behavior. |
Invalid (or obsolete) linkage specification for EXTERNAL routine <routine>. | The $BC16 and $BC32 linkage specs are no longer supported in TSD Developer's Toolkit 5.0 (which is now a 32-bit program and no longer able to load 16-bit Windows DLLs). Use $C instead and be sure you are linking to a 32-bit DLL. |
.KB file name <name> conflicts with a built-in function or other internal symbol. | Versions prior to 4.2 allowed you to give a .kb file the same name as an internal symbol. For example, STRING, WinCreate, when, etc.) resulting in confusion and potential internal errors. The TSD 5.0 Developer's Toolkit TSD Script Parser now recognizes this and reports it. Give your .kb file a unique name. |
Tivoli Service Desk 6.0 Developer's Toolkit Tools and Utilities Guide