news

info

people

software

stuff

Using My External Commands

Description

In general all of my externals have been written so that they can do more than one thing (or will do in the future). Because of this, the first parameter to any of my externals will be the name of the particular command to do.

In addition to the commands to do their specific job, all of my externals support some default commands which allow you to interrogate the external about itself. These commands are documented in the note "Standard Commands".

Also, all of my externals handle errors in a consistent way. This is documented in the note "Error Reporting".

Standard Commands

These are currently: !version,!short,!author,!date,!commands,!type,!name.

In addition, externals that create external windows support the !properties and !messages commands.

VERSION NUMBERS

I regularly update my externals, to fix bugs, and to extend their functionality.

If you encounter a problem, it is worth checking that you are using the most up to date version of the command in question.

The version command will always return a string giving a copyright notice, version number and compilation time.

If its an XCMD, do

    MyXCMD "!version"

  put the result

If its an XFCN, do

    put MyXFCN("version")

FINDING OUT WHAT COMMANDS ARE AVAILABLE Each one of my externals can return a list of the commands that it understands.

This list can be obtained by

  MyXCMD "!commands"

  put the result

or by

  put MyXFCN("!commands")

The list doesn't contain any detailed information about the syntax of each command, but it may be enough to jog your memory if you are trying to remember a command name, and it will give you a clue if you are already familiar with the syntax of the external's other commands.

For externals that create external windows, the !properties and !messages commands will also be implemented. These commands return a list of the properties possessed by the external windows, and the messages that they can be sent.

Error Reporting

I have arrived at a standard way of dealing with errors, and all of my externals have now been updated to use this method.

There are two globals, called XStatus and XError, which are always set by a call to one of my XCMDs.

XStatus will be set to "ok", if all is well. If not, it will contain one of a number of standard error messages, which are short and fairly unhelpful - things like "resource not found", or "wrong parameters".

In this case, XError will contain a longer string describing in more detail the specific problem, for example "Couldn't find the resource called Tester".

Both of these globals are worth checking if something seems to be going wrong. Also, look at the result returned by the external. In my older externals, this result would generally be "Error: some error message" if an error had occurred.

In addition, if the global variable XErrorHandler is not empty, then its contents are taken as the name of an error handling routine to call. The routine is called with the parameters <name> (the name of the external), and <type> (whether the external is an XCMD or an XFCN.

The Sam's Library stack installs a default error handler which traps external's errors and displays them in an external window.

NB: There are performance issues associated with always having to reset the XStatus and XError globals, even if no error has occurred. If anyone has a problem with performance, I may consider producing "fast" versions of the relevant XCMDs, with identical behaviour, but with error reporting removed. Mail me if this would be valuable.