Manual for DB Scope

Version 3.2

Note: This manual assumes that you have a working knowledge of the Palm OSŪ, including launching applications, using menus, etc. Please see the documentation that came with your handheld for help with these types of questions.

Installation

For installation and one-time setup instructions, please see the ReadMe file that comes with the DB Scope application. 

List of Layouts Screen

This screen lists the layouts that you have thus far created.

For each layout, you are shown the name of the layout, along with its database selection criteria. If you entered a specific database name, that name is displayed. Otherwise, the creator and/or type you specified (if any) are displayed.

Scroll bars are available if there are more layouts than will fit on the screen.

Tapping on the "New" button will let you create a new layout. You are prompted for a name for the new layout. Tap on the "Done" button to create the database.

 

 

 

Tapping on the name of a layout will execute the currently selected function. Whenever you arrive at the List of Layouts screen, the default function is "Use". You select a different function using the popup trigger at the bottom of the screen. The following functions can be executed for an existing layout:

  1. Use – View the contents of a database using the selected layout at the Database View Screen
  2. Edit – Modify the definition of the selected layout at the Edit Layout Screen
  3. Rename – Rename the selected layout
  4. Copy – Copy the selected layout to a new one
  5. Delete – Delete the selected layout

For the Rename and Copy functions, you are prompted to enter a name for the layout. For the Delete function, you are asked to confirm that you want to delete the layout.

The trial version of DB Scope will let you create only 1 layout, with a maximum of 7 fields.

To register DB Scope, select "Register…" from the Options menu. This will display the Register dialog.

Enter the entire registration code, including leading zeros (if any). The registration code will work only for the HotSync User Name you specified when you purchased DB Scope. This must exactly match the actual HotSync User Name associated with your handheld, which is displayed near the top of the screen.

Selecting "Databases..." from the View menu will display the Database List Screen, where you can view information about existing databases and create or delete databases.

Selecting "Files..." from the View menu will display the File List Screen, where you can view information about existing files on your expansion card (if one is inserted and your handheld supports VFS).

Edit Layout Screen

The title of the screen is the name of the current layout, and it lists the fields that you have thus far defined.

For each field, you are shown:

See the Edit Field Screen for more information.

Scroll bars are available if there are more fields than will fit on the screen.

Tapping on the "New" button will let you create a new field at the Edit Field Screen. New fields are always added at the end of the list.

Tapping on the name of a field will execute the currently selected function. Whenever you arrive at the Edit Layout screen, the default function is "Edit". You select a different function using the popup trigger at the bottom of the screen. The following functions can be executed for an existing field:

  1. Edit – Modify the definition of the selected field at the Edit Field Screen
  2. Move Up – Move the selected field up 1 in the list of fields
  3. Move Down – Move the selected field down 1 in the list of fields
  4. Delete – Delete the selected field

For the Delete function, you are asked to confirm that you want to delete the field.

Tapping on the "DB" button will display the Database Options dialog.

Tapping on the "Done" button will return you to the List of Layouts Screen.

Database Options Dialog

This dialog box lets you specify what data can be viewed using the current layout. The various data types are listed in the Edit popup list, which includes:

Data Type Data Edited By This Type
Data Database's records
AppInfo Database's Application Information Block
Prefs - Saved Application's Saved Preferences
Prefs - Unsaved Application's Unsaved Preferences

If the layout is intended to be used with a specific database (whose name is always the same), enter that name in the "Database" field. If the layout will be used for multiple databases, enter the database type and/or creator for those databases. For layouts to be used for Preference data, simply enter the creator ID of the application. Or you can leave the creator ID field blank, and preferences will be displayed for all applications.

Note: In Palm OSŪ 5, having the Saved Preference database open for Read/Write causes a crash. Therefore, if you are running Palm OSŪ 5, Saved Preferences can be viewed but not modified.

Tapping on the "Done" button will return you to the Edit Layout Screen.

Edit Field Screen

This screen lets you specify the definition of a field.

For each field, you can specify:

The following field types are supported:

Field Type Abbreviation on Edit Layout screen
8-bit integer (unsigned) UInt8
8-bit integer (signed) SInt8
16-bit integer (unsigned) UInt16
16-bit integer (signed) SInt16
32-bit integer (unsigned) UInt32
32-bit integer (signed) SInt32
Float Float
Double Double
Character Char
String String
Date Date-S or Date-L (short or long format)
Time Time
Date/Time Date/Time
Date/Time (in seconds since 1/1/1904) DateSec

For character fields, you can specify the number of characters in the field (default is 1). For date fields, you can specify whether to display the date in short or long format. For float or double fields, you can specify the number of fractional digits to be displayed.

The number of occurrences lets you create an array. If you have 5 consecutive fields of the same type, this lets you define all of them at once, instead of having to do each one separately. If you create such an array called, for example, "Data", they will be listed as "Data 1", "Data 2", etc.

If you specify that a field should be displayed in hex, the abbreviation will have "-H" appended to it.

Tapping on the "Done" button will save your changes and return you to the Edit Layout Screen. Tapping on the "Cancel" button will return you without saving your changes.

Database View Screen

The title of this screen is "Select Database" if no database has yet been selected. Otherwise, it is the name of the database being displayed. If the database is a ROM-based database, the word "ROM" is displayed in the top right corner.

When viewing database records, for each record in the database, the following information is displayed:

In addition, one other value is displayed. This is controlled by the popup trigger near the top, and can be one of the following:

Each attribute that is "on" is represented by a letter, as shown in the following table:

Attribute Represented By
Delete X
Dirty D
Busy B
Secret S

If you select "Category" in the popup list, and the database has defined categories, the name of the category is shown. If categories have not been defined, "Not Available" is displayed.

WARNING: DB Scope might crash if ALL of the following are true:

When viewing a database's application information block, the Category, Unique ID, Attributes, and Category name cannot be displayed because they are not applicable. The "[A]" indicator at the right edge reminds you that you are looking at the database's application information block and not its data records.

 

 

 

 

 

 

When viewing preference data, the title bar will say either "Saved Preferences" or "Unsaved Preferences", and the following information is displayed:

In addiition, one other value is displayed. This is controlled by the popup trigger near the top, and can be one of the following:

In the bottom right corner of the screen, the number of records in the current view is displayed.

Tapping on any item in this list will take you to the Record View Screen for the selected data.

Scroll bars are available if there are more records than will fit on the screen.

Tapping on the "DB" button will take you to the Select Database Dialog, which will let you select the database to be displayed.

Tapping on the "UID" button will take you to the Find Dialog, where you can find a record in the current database by its unique ID.

Tapping on the "New" button will create a new record at the end of the database. All fields are filled with zeros, except for string fields which are set to a null string.

Tapping on the "Status" button will display the Database Status Screen for the current database.

When using an application information block layout, the UID button is not available. In addition, the New is button is available only if the database does not already have an appinfo block.

When using a preference layout, the DB, UID, and New buttons are not available.

Tapping on the "Done" button will return you to the List of Layouts Screen.

Select Database Dialog

At this screen, a list of databases is displayed. You can enter a 4-character creator ID in the field in the bottom right corner, and only databases with a matching creator ID will be displayed.

If you entered a creator and/or type on the Database Options Dialog, only databases with matching values will be displayed. Otherwise, all databases are displayed.

Scroll bars are available if there are more databases than will fit on the screen.

If you select a database, you will be returned to the Database View Screen, and the selected database will be displayed. DB Scope will remember the database you selected, and automatically select it for you the next time you use current the layout.

Tapping on the New button takes you to the Create Database Screen, and lets you specify information for a new database. If a creator and/or type was specified for the current layout, those values will be filled in for you.

Tapping on the "Cancel" button will return you to the Database View Screen.

Find Dialog

At this screen, you are prompted for a unique ID.

The unique ID must be entered in hex. If you enter a valid unique ID and tap on the "Done" button, you are taken back to the Database View Screen, and if a record with the specified unique ID exists, the list is scrolled to that record.

Tapping on the "Cancel" button will return you to the Database View Screen.

Record View Screen

If this is a data layout, the title of this screen is "Record nnnnn" where nnnnn is the 0-based record number of the record being displayed. If this is an application information block layout, the title is "AppInfo".

For each field defined in the current layout, the following information is displayed:

If the field is a repeating field, an index number is appended to the name of the field.

The value of the field in the current record is displayed in an appropriate format. Numbers are right justified, and all other values are left justified.

If the field is to be displayed in hex, the hex on/off box is turned on. You can tap on this box to toggle between hex and the field’s default format. DB Scope will remember if you switch hex on and off, and will display the field in that format from now on. Tapping on the hex on/off box of an array field changes the format of all fields in the array.

If there are not enough bytes in the record for all of the defined fields, "(end of record)" is displayed for those extra fields. This also happens if a record ends before a terminating null character is found for a String field.

If there are more bytes in the record than have been defined in the layout, an extra field called "(undefined)" is added to the list of fields. The value of this field is always displayed in hex, since there is no known format. If you use a layout in which no fields have been defined, the whole record’s contents will appear in the undefined field.

If a field of type String is null, the value "(null string)" is displayed. If the contents of a field of type Date are invalid, "(invalid date)" is displayed. If the contents of a field of type Time are 0xFFFF, "(no time)" is displayed.

In the bottom right corner of the screen, the number of bytes in the current record is displayed.

Scroll bars are available if there are more fields than will fit on the screen.

Tapping on a field’s value or overflow indicator will take you to the Field Detail Screen for the selected field.

Tapping on the up and down arrows at the bottom of the screen will take you to the prior and next record in the database.

Tapping on the "Done" button will take you back to the Database View Screen.

Field Detail Screen

The title of this screen is the name of the field.

Each row on the screen displays 10 characters of the current field, displayed in either ASCII or hex. This is controlled by the push buttons at the bottom of the screen.

In the bottom right corner of the screen, the number of bytes in the current field is displayed.

Scroll bars are available if there are more bytes than will fit on the screen.

Tapping on the "Edit" button lets you edit the value of this field at the Edit Value Screen.

Tapping on the "Done" button returns you to the Record View Screen.

Edit Value Screen

This screen lets you edit the value of a field. There are different screens you might see, depending on the type of the field whose value is being edited, as shown below.

Numeric Fields Date/Time Fields String Fields Character Fields

Numeric fields: If the Char/Hex selector on the prior screen was set to hex, DB Scope will display "(hex)" and interpret your input as hexadecimal digits. For float and double fields, you can enter numbers such as 123.45.

Date/Time Fields: The "Date" fields are displayed for fields of type Date, and the "Time" fields are displayed for fields of type Time. Both are displayed for fields of types "Date/Time" and "Date/Time in Seconds".

Character Fields: Values are entered a byte at a time. You can enter values in decimal, hex, or as character by tapping on the selector in the bottom right corner, or by tapping on the words "Decimal", "Hex", or "Char". Tapping on the "Save" button saves the current byte. Tapping the up/down scrollers saves the current byte and moves you through the array of characters.

Database List Screen

This screen lists all of the databases that exist on your handheld. For each one, the creator and type are displayed. You can enter a 4-character creator ID in the field in the bottom right corner, and only databases with a matching creator ID will be displayed.

Tapping on a database takes you to the Edit Database Screen, which displays information about that database. Tapping on the New button takes you to the Create Database Screen, and lets you specify information for a new database. Scroll bars are provided to scroll through the list.

Tapping on the Done button takes you back to the List of Layouts Screen.

Edit Database Screen

This screen displays information for an existing database. You can change the name, creator, type, version, and modification number by entering new values. You can also change the database's attributes by checking and unchecking the checkboxes. Naturally, you need to be very careful changing these attributes. Tapping on the Delete button allows you to delete the database, after a confirmation.

Tapping on the "Status" button will display the Database Status Screen for the current database.

Tapping on the Move button will let you move or copy this file to an expansion card at the Move or Copy Screen.

If the database is in ROM, the word "ROM" is displayed in the top right corner. In this case, you will not be able to change the database's information or attributes. You also cannot delete a ROM-based database.

Tapping on the Done button takes you back to the Database List Screen.

 

 

 

Create Database Screen

This screen lets you create a new database. You must specify valid values for the database name, creator, and type. You can also select the attributes you want for the new database by tapping on the checkboxes.

Tapping Done will create the database and take you back to the previous screen. Tapping Cancel will return you to that screen without creating the new database.

 

 

Move or Copy Screen

This screen lets you move a database in main memory to an expansion card, or an expansion card file into main memory. Your version of the Palm OSŪ must support VFS and you must have an expansion card inserted.

If you check the "Make a copy" box, a copy is made. Otherwise, the original is deleted.

When moving to the expansion card, if you check the Launchable box, databases are placed into /PALM/Launcher. If the box is not checked, databases are placed into /PALM/Programs. By default, the Launchable box is checked only for applications (i.e., databases whose type is "appl").

Applications are created with a .prc extension. All other databases are created a .pdb extension.

Tapping Move will move or copy the database and return you to the prior screen. Tapping Cancel will return you to the prior screen with no move or copy taking place.

Database Status Screen

This screen displays information about a database. This includes the database name, number of records, size, and the creation, modification, and backup dates and times.

Tapping the Done button will return you to the previous screen.

 

 

File List Screen

This screen lists the files in the current directory of the expansion card. For each file, the name is displayed along with the creator and type. For directories, "Dir" is displayed.

Tapping on a file will display the Edit File Screen for that file. Tapping on a directory will display the contents of that directory.

You can move up the directory hierarchy by tapping the Up button. The popup list in the top right corner displays the path to the current directory. That is, /PALM/Launcher will be displayed as 3 levels : "/", "PALM", and "Launcher". Selecting one of these levels will move you up to that directory. 

Selecting "Delete Directory" from the menu will delete the current directory (after a confirmation).

Tapping the New button lets you create a new file or directory in the current directory.

Tapping the Done button will return you to the List of Layouts Screen.

Edit File Screen

This screen displays the name and attributes of the current file. You can modify the name of the file and the attributes. Tapping the Done button will save your changes and return you to the File List Screen.

Tapping the Delete button will delete the current file (after a confirmation). Tapping the Move button will let you move or copy this file to main memory at the Move or Copy Screen.

 

About Screen

This screen displays the current version number, followed by a letter in parentheses. If the letter is "R", you have entered the correct registration code for DB Scope. Otherwise, it is the letter "U" for Unregistered.

Tapping the Done button will return you to the prior screen.