PiTcl commands: DLP connection handling

Creates a new dlp connection object of the given name. The device to connect to is optional. If it is missing, the system will fall back to the value in the environment variable PILOTPORT. If that fails too, it will use /dev/pilot.

Return value is the name of the new object.

The available options and subcommands are described below.

Registers a new converter with the given name. Returns the empty string. The possible options are described later.

Reconfigures the converter name. Returns a list of possible options if called without options (Should return all values of these too, but this is not yet implemented). Equivalent to the subcommand cget if called with a single option, and without value.

Returns the current setting of the specified option, for the converter name.

The recognized options are

Deletes the specified converter. The internal datastructure on the other hand will stay as long as there are references to it.

No arguments. Returns a list containing the names of all registered converters.

Associates database name, creator and type with a converter to use. The first 3 arguments are glob-style patterns. Returns an empty string.

Removes the association defined by the database name, creator and type pattern from the map. Returns an empty string.

Searches the map for a converter to the given database name, creator and type, which are no patterns! (The patterns are in the map).

The search algorithm is explained below. It returns the name of the found converter, or an empty string if no entry was eligible.

Returns a list containing the whole map. Its elements are lists by themselves, with 4 elements each. These are database name, creator, type and associated converter, in this order.

Waits for the pilot to talk to us. Tell the user to press HotSync before doing this. Multiple calls have no effect, the system knows when the line is activated. Returns an empty string. All commands talking to the pilot do this implicitly!

Destroys the dlp object, closes the connection to the pilot. Causes the pilot to reset if session resetSystem was called before doing this.

Returns the number of memory cards installed on the pilot. Usually 1.

Returns information about memory card i. The returned list is suitable for array set.

card         0
version      1
created      893254347
romsize      1245180
ramsize      2097152
ramfree      1890358
name         PalmCard
manufacturer {Palm Computing}
	    

Returns a list containing the information from get i for all installed cards.

{
    card 0 version 1 created 893254347
    romsize 1245180 ramsize 2097152
    ramfree 1890358 name PalmCard
    manufacturer {Palm Computing}
}
	    

Returns the global system information block of the pilot, formatted as a list suitable for array set. Date information in this list is in the format returned by clock seconds.

romVersion 50343936
locale     65536
name       {}
	    

Returns the global user information of the pilot, formatted as a list suitable for array set. Date information in this list is in the format returned by clock seconds.

userId             0
viewerId           0
lastSyncPC         0
successfulSyncDate 916005120
lastSyncDate       916611309
username           {}
password           {}
	    

Returns the global system time of the pilot, in the same format as is used by clock seconds.

916611504
	    

Returns the global netsync information of the pilot, formatted as a list suitable for array set. Date information in this list is in the format returned by clock seconds.

lanSync     1
hostName    bluepeak
hostAddress {}
hostSubnet  {}
	    

Writing complement of the reading accessor above. Expects the information as a list suitable for array set, containing the same keywords as returned by the corresponding get. The order of the keywords is not important.

Writing complement of the reading accessor above. Expects the information in the same format as returned by the corresponding get.

Writing complement of the reading accessor above. Expects the information as a list suitable for array set, containing the same keywords as returned by the corresponding get. The order of the keywords is not important.

Start a conduit session. Can be called multiple times during a session, to detect any cancel issued from the pilot. Returns an empty string.

Writes the text to the session log handled by the pilot. Explicit newlines are required to step to the next line! Returns an empty string.

Stops the interaction, closes the channel to the pilot. Causes the pilot to reset if resetSystem was called during the session. state allows the transmission of the reason for closing down. The recognized values are:

• normal
• outofmem
• cancel
• other

The default value is normal. Returns an empty string.

Tells the pilot to reset after the interaction is done, detected by closing the channel. Returns an empty string. The actual reset is done after session end or delete.

Sends a keep-alive packet down the socket, to prevent the pilot from closing the connection from its side. The default timeout of the pilot is 30 seconds.

Closes all currently open databases. The associated accessor objects are destroyed too.

Returns a list containing the names of all databases stored on the pilot, independent of type (record, resource) and location (rom, ram, which card).

LauncherDB NetworkDB {Date Book} MemoDB
{IrDA Library} {PPP NetIF} DatebookDB
ShortCuts CitiesDB System {Saved Preferences}
{Net Prefs} {To Do List} Mail Buttons
Preferences {PADHTAL Library} Owner
{Net Library} {SLIP NetIF} AMX ExpenseDB
VendorsDB {MIDI Sounds} {Address Book}
Modem {Graffiti ShortCuts} {Extension Registry}
UIAppShell Security HotSync ReversiBoard MailDB
Calculator ToDoDB {Unsaved Preferences}
{Loopback NetIF} AddressDB {MS-CHAP Support}
General GrafAid Expense Reversi Network Launcher
{Memo Pad} Digitizer Formats
	    

Returns a list containing information about the specified database. The list is suitable for array set.

name       {Memo Pad}
card       0
createDate 893252776
modifyDate 893252776
backupDate -1
modnum     0
version    1
type       appl
creator    memo
flags      {readOnly resource}
miscflags  {}
	    

Deletes the specified database from the memory of the pilot.

Opens the specified database and creates an accessor object with the name dbObj. Returns that name. The recognized options are:

• -packer

  Accepts only the names of registered converters as value. Defaults to {}. The specified converter is used to convert between tcl lists and the binary information coming from or going to the pilot. The default value causes the system to transfer binary data without any conversion.

• -mode

  Accepts a list of flags describing the way the database is opened. Defaults to {}. Recognized list elements are:

  read

  open for reading

  write

  open for writing

  exclusive

  open for exclusive access (no application on the pilot may have the database open).

  secret

  make the secret records accessible.

Creates a new database and opens it in read/write mode. Database creator- and type-code are strings, they are truncated to four characters. Returns the name of the newly created database object, dbObj. The recognized options are:

• -packer

• -card

  The number of the memory card the newly created database is installed into. Defaults to 0.

• -version

  The version number of the newly created database. Defaults to 0.

• -flags

  A list of flags describing some aspects of the newly created database. Defaults to {}. Recognized values are:

  backup

  Database is tagged for generic backup

  resource

  Database is a resource file (= application)

  appinfoDirty

  AppInfo data has been modified

  reset

  Reset the pilot after installation

  newer

  A newer version may be installed over open DB

  Two other values are defined, but here not allowed as they describe non-writable state information of the database on the pilot.

  open

  The database is currently open

  readOnly

  The database resides in ROM.

Closes the database, destroys the object.

Retrieves the description of the database. The result is a list suitable for array set.

Retrieves the number of records in the database.

Retrieves the application information block of the database. The result depends on the chosen converter, but usually is a list suitable for array set.

See Conversions commands for the description of the formats returned by the converters for the standard databases.

Retrieves the sort information block of the database. The result depends on the chosen converter, but usually is a list suitable for array set.

See Conversions commands for the description of the formats returned by the converters for the standard databases.

Retrieves a list containing the ids of all records in the database. Using the -sorted option causes them to be sorted by increasing index numbers.

Retrieves the specified record of the database. The result is a 4-element list containing the id of the record, its category (a number), its attributes (as a list of attribute flags) and the (possibly converted) record contents, in this order. The format of the record contents depends on the chosen converter, but usually is a list suitable for array set.

See Conversions commands for the description of the formats returned by the converters for the standard databases.

Using the -byId option causes the system to interpret the following number as a record id, else as a record index (in the range 0 .. get recnum).

Allowed only for non-resource databases.

Generated attributes are:

The same as above, but the record is implicitly specified as the next record after the last which is marked as modified. If a category is specified it is the next modified record with the given category. See resetIndex too.

Allowed only for non-resource databases.

The same as above, but the record is implicitly specified as the next record with the given category. See resetIndex too.

Allowed only for non-resource databases.

Retrieves the resource record with the specified index from the database. The result is a 2-element list containing the resource type and the (possibly converted) resource contents, in this order. The format of the resource contents depends on the chosen converter, but usually is a list suitable for array set.

Allowed only for resource databases, i.e. applications.

The resource type is a character string, like the database creator/type information.

Write the application information block of the database. data has to be in the same format as returned by get appinfo, for the same setting of the converter option.

Write the sort information block of the database. data has to be in the same format as returned by get sortinfo, for the same setting of the converter option.

Write a record into the database. data has to be in the same format as returned by the various get record-commands, for the same setting of the converter option.

attr is a list containing database attributes, as explained before.

Write a resource into the database. data has to be in the same format as returned by get resource, for the same setting of the converter option.

Changes the cateegory of all entries with category from to category to. Returns an empty string.

Categories are identified by integer numbers in the range 0 .. 15 (There are no more than 16 categories).

Deletes the category 'id' (but not the entries using it ?). Returns an empty string.

Delete all records marked for deletion. Returns an empty string.

Resets the flags governing the sync process (dirty, archive) for all records in database.

Resets the internal pointer for the next... commands to the start of the database.

Deletes one or all records, if one based upon id

Deletes one or all resources, if one based upon id and type.

Iterator, wrapper around the resetIndex and next... commands to simplify access to the database. Cannot be nested for a single database!

Not yet implemented.

Returns the value associated to the specified option.

Recognized options are:

• -pack

  Accepts only the names of registered converters as value. Defaults to {}. The specified converter is used to convert between tcl lists and the binary information coming from or going to the pilot. The default value causes the system to transfer binary data without any conversion.

Returns a list of options if called without arguments. Returns the value associated to the option if called with a single option and no value. Sets the values of given options to the specified information.