Tech Note 09: Palm OS データベースへのアクセス

May 4, 2005

Copyright 2005 NS BASIC Corporation / translated by mizuno-ami.

目次:

    はじめに
    オブジェクト
    索引・クイックリファレンス
    オブジェクトとコレクション
    関数
    メソッド
    プロパティ


はじめに

PalmDBオートメーションコントロール(PalmDB.dll)は、Palmオーガナイザー、Treoシリーズやその他多くのPalmデバイスによって作られる「PalmOS データベースファイル」へのフルアクセスを可能にするCOMコンポーネントです。それら拡張子が「.pdb」のファイルは、HotSyncによって、パソコン上にバックアップされるバイナリーイメージを含むデータベースです。

PalmDBは、数年前、Maxime Labelleによって作られました。それは、積極的にメンテナンスされおり、適切に動作し、ソースコードがフリーで公開されていますが、もし、何らかの改良・改善点を望むのなら、こちらまで連絡を下さい

オリジナルのソース、ドキュメント類は、こちらからダウンロードできます:
http://www.freewarepalm.com/utilities/palmdbautomationserver.shtml

インストールと使用方法

PalmDBオートメーションコントロール(PalmDB.dll)を使うには、NS Basicプログラムが動作しているコンピュータに、それらがコピーされている事が必要です。 これは単独のActiceXコントロールなので、NS Basic/Desktopのプログラムの中には組み込まれておらず、利用するパソコンのOSに個別に登録をしなければなりません。 ただし、NS Basic/Desktopのインストーラには含まれているので、開発者の方は、開発用のパソコンで使用する場合は、特に作業をする必要はありません。

NS Basicプログラムで、このコントロールを使うには、次のような宣言をします。

AddObject "PalmDB.Database", "PalmDB"

(当然ですが)このコントロールがプログラム中使われる前に、この宣言をしておく必要があります。 上記の宣言文では「PalmDB」の名前を使いましたが、これはどのような名前を付けても大丈夫です(本書では「PalmDB」で記述します)
1つのインスタンスは1つのデータベースしか開く事が出来ません。そのため、複数のデータベースを取り扱う場合は、適宜、AddObjectにってコントロールを追加してください。

NS Basic/Desktopには、PalmDatabaseと呼ばれるサンプルプログラムが付加されていますが、これはNS Basic/Palmに同梱されるKeyedDBDemoによって作られるkeydbtext.pdbとデータを共有しています。

もし、これらのコントロールを使う場合、NS Basic/Desktop Ver.1.2かそれ以降のバージョンが必要になります。

オブジェクト

PalmDBコントロールは、以下のオブジェクトとコレクションを持っています:

オブジェクト 説明
Database Databaseオブジェクトは、最高位にあるオブジェクトで、これを使って直接クライアントアプリケーションからPDBファイルを作ることが出来ます。
PalmDBを使ってこのオブジェクトを参照してください。
ApplicationInfo 各々のPalmOSデータベースは、ユーザー定義のアプリケーション情報を持つことが出来ます。それは、通常上、データベースのカテゴリーを含んでいます。
PalmDB.ApplicationInfo で、このオブジェクトを参照してください。
Records Recordsコレクションは、データベースのレコードに対し、ランダムアクセスもしくは、シーケンシャルアクセスを提供します。また、レコードの追加や削除もサポートしています。
Use PalmDB.Recordで、このコレクションを参照してください。
Record このオブジェクトは、各レコードを表します。個々のレコードを管理するためのメソッドや関数が提供されています。
PalmDB.Records(レコード番号)で、個々のレコードを参照します。
レコード番号は 0番から始まり、最終レコードはPalmDB.Records.Count - 1で表現されます。

 

索引・クイックリファレンス:

オブジェクトとコレクション
        ApplicationInfo (object) ApplicationInfo
        Database (object) Database
        Record (object) Record
        Records (collection) Records
関数
        Count (function) object.Count
        GetDateField (function) object.GetDateField(Offset)
        GetStringField (funtion) object.GetStringField([Offset = 0])
        GetValueField (function) object.GetValueField(Offset, Length)
        Item (function) object[.Item](Index)
メソッド
        Add (method) object.Add(Index)
        CategoryInitialize (method) object.CategoryInitialize
        Load (method) object.Load(Filename)
        PutDateField (method) object.PutDateField(Value, Offset)
        PutStringField (method) object.PutStringField(Value, [Offset])
        PutValueField (method) object.PutValueField(Value, Offset, Length)
        Remove (method) object.Remove(Index)
        Save (method) object.Save(Filename)
プロパティ
        ApplicationInfo (property) object.ApplicationInfo
        Attributes (property) object.Attributes [= Value]
        Category (property - Record object) object.Category [= Value]
        Category (property - ApplicationInfo object) object.Category(Index) [= Value]
        CreationDate (property) object.CreationDate
        Creator (property) object.Creator [= Value]
        ModificationDate object.ModificationDate
        Name (property) object.Name [= Value]
        Records (property) object.Records
        Size (property) object.Size [= Value]
        Type (property) object.Type [= Value]

オブジェクトコレクション

 

ApplicationInfo (オブジェクト)


ApplicationInfoオブジェクトは、ユーザ定義のアプリケーション情報を含んでいます。
ここには、データベースカテゴリが含まれています。

書式

ApplicationInfo

メソッド

プロパティ

備考

アプリケーション情報のエリアに任意のデータを置く機能は実装されていません。 そのため、Recordオブジェクトのように多くのメソッドや関数を持っていません。

このオブジェクトは、直接作ることが出来ませんので、代わりにDatabaseオブジェクトのApplicationInfoプロパティを使います。


 

Database (オブジェクト)


Databaseオブジェクトは、最高位にあるオブジェクトで、直接、クライアントアプリケーションから作ることが出来ます。それは、.pdbファイルの事です。

書式

Database

メソッド

プロパティ

備考

インストールと使用方法」で説明したように、AddObject命令を使ってデータベースオブジェクトを作ってください。

 
 
 

Record (オブジェクト)


Recordオブジェクトは、データベース中の各レコードを表します。個々のフィールドデータを管理するために、多用なメソッドと関数を持っています。

書式

Record

メソッド

プロパティ

備考

直接、このオブジェクトを作ることは出来ません。Records コレクションのメソッドと関数を使用してください。

 
 
 

Records (コレクション)


Recordsコレクションは、データベースのレコードに対し、ランダムアクセスとシーケンシャルアクセスの両方を提供します。また、レコードの追加や削除もサポートされています。

書式

Records

メソッド

備考

Recordsオブジェクトは、データベース内の各レコードを列挙する事を考え、NS Basic/Desktopの For Each 構造をサポートしています。

このオブジェクトは、直接作ることが出来ません。代わりに、DatabaseオブジェクトのRecords プロパティを使ってください。

 
 
 

関数

Count (関数)

対象:Records

書式

object.Count
項目 意味
object 対象リスト内のオブジェクトを表す式

備考

 

 

GetDateField (関数)

対象:Record

Syntax

object.GetDateField(Offset)
GetDateField関数は、次の項目を含みます:
項目 意味
object 対象リスト内のオブジェクトを表す式
Offset レコードデータの先頭からのオフセット値。先頭は 0から始まります。

備考

この関数は、PalmOSが扱う4バイトの整数で表される標準の日付型データに対して機能します。これらは、NS Basic/Palmが扱う8バイト実数の日付型、(Year-1900)*10000 + month*100+ day、とは異なります。

 

 

GetStringField (関数)

対象:Record

書式

object.GetStringField([Offset = 0])
GetStringField 関数は、次の項目を含みます:
項目 意味
object 対象リスト内のオブジェクトを表す式
Offset レコードデータの先頭からのオフセット値。先頭は 0から始まります。

備考

この関数は、オフセット値で指定された位置から、レコードデータの最後までの文字列を取得できます。これは記録されているバイナリデータを取り出すのに役立ちます。 文字列データとして取り出す場合は、次のようなコードでデータを整えてください:

s = PalmDB.Record(0).GetStringField(37)
s = Left(s, Instr(s, chr(0)) - 1)

 

 

GetValueField (関数)

対象:Record

書式

object.GetValueField(Offset, Length)
GetValueField 関数は、次の項目を含みます:
項目 意味
object 対象リスト内のオブジェクトを表す式
Offset レコードデータの先頭からのオフセット値。先頭は 0から始まります。
Length 取り出したい数値データの長さ。
バイト(Byte)=1、整数(Integer)=2、長整数(Long)=4

備考

 

 

Item (関数)

対象:Record

書式

object[.Item](Index)
Item 関数は、次の項目を含みます:
項目 意味
object 対象リスト内のオブジェクトを表す式
Index 有効なレコード番号を表すインデックス。範囲は 0 - Count

備考

 

 

 

メソッド

 

Add (メソッド)

対象:Records

書式

object.Add(Index)
Add メソッドは、次の項目を含みます:
項目 意味
object 対象リスト内のオブジェクトを表す式
Index 新しいレコード番号を表す 0から始まるインデックス番号。レコードは、Indexで示された位置に挿入され、IndexとCountが等しい時は、最終位置への追加になります。

備考

 

 

 

CategoryInitialize (メソッド)

対象:ApplicationInfo

書式

object.CategoryInitialize 
CategoryInitialize メソッドは、次の項目を含みます:
項目 意味
object 対象リスト内のオブジェクトを表す式

備考

CategoryInitializeメソッドはUnfiledBusiness、およびPersonalの初期のカテゴリを作成します。

 

Load (メソッド)

対象:Database

書式

object.Load(Filename)
Load メソッドは、次の項目を含みます:
項目 意味
object 対象リスト内のオブジェクトを表す式
Filename 読み込みたい.pdbファイルのフルパス

備考

 

 

PutDateField (メソッド)

対象:Record

書式

object.PutDateField(Value, Offset)
PutDateField メソッドは、次の項目を含みます:
項目 意味
object 対象リスト内のオブジェクトを表す式
Value 保存したい日付を表す数値データ
Offset レコードデータの先頭からのオフセット値。先頭は 0から始まります

備考

このメソッドは、PalmOSが扱う4バイトの整数で表される標準の日付型データ(特定の期日からの経過秒)を取り扱います。これらは、NS Basic/Palmが扱う8バイト実数の日付型、(Year-1900)*10000 + month*100+ day、とは異なります。

 

 

PutStringField (メソッド)

対象:Record

書式

object.PutStringField(Value, [Offset])
PutStringField メソッドは、次の項目を含みます:
項目 意味
object 対象リスト内のオブジェクトを表す式
Value 保存したい文字列データ
Offset レコードデータの先頭からのオフセット値。先頭は 0から始まりす

備考

 

 

PutValueField (メソッド)

対象:Record

書式

object.PutValueField(Value, Offset, Length)
PutValueField メソッドは、次の項目を含みます:
Item Meaning
object 対象リスト内のオブジェクトを表す式
Value 保存したい数値データ。Lengthによって適切なデータ長を指定してください。
Offset レコードデータの先頭からのオフセット値。先頭は 0から始まります
Length 数値データの長さ。バイト(Byte)=1、整数(Integer)=2、長整数(Long)=4

Remarks

 

 

Remove (メソッド)

対象:Records

書式

object.Remove(Index)
Remove メソッドは、次の項目を含みます:
項目 意味
object 対象リスト内のオブジェクトを表す式
Index 削除したいレコードを表すインデックス番号。指定できる範囲は、0 - (Count - 1)(最終レコード)

Remarks

 

 

Save (メソッド)

対象:Database

書式

object.Save(Filename)
Save メソッドは、次の項目を含みます:
項目 意味
object 対象リスト内のオブジェクトを表す式
Filename 保存したい.pdbファイルのフルパス

備考

 

 

 

 

 


プロパティ

 

ApplicationInfo (プロパティ)

対象:Database

書式

object.ApplicationInfo 
ApplicationInfo プロパティは、次の項目を含みます:
項目 意味
object 対象リスト内のオブジェクトを表す式

備考

 

 

 

Attributes (プロパティ)

対象:Database, Record

書式

object.Attributes [= Value]
Attributes プロパティは、次の項目を含みます:
項目 意味
object 対象リスト内のオブジェクトを表す式
Value 設定する属性を表す数値データ。以下のDatabase AttributesRecord Attributes を使ってマスクを指定できます。

Database Attributes

名前 意味
dmHdrAttrResDB  
dmHdrAttrReadOnly  
dmHdrAttrAppInfoDirty  
dmHdrAttrBackup  
dmHdrAttrOKToInstallNewer  
dmHdrAttrResetAfterInstall  
dmHdrAttrCopyPrevention  
dmHdrAttrStream  
dmHdrAttrHidden  
dmHdrAttrLaunchableData  
dmHdrAttrOpen  
dmAllHdrAttrs  

Record Attributes

名前 意味
dmRecAttrSecret  
dmRecAttrBusy  
dmRecAttrDirty  
dmRecAttrDelete  
dmAllRecAttrs  

Category Attributes

名前 意味
dmRecAttrCategoryMask  

備考

 

 

 

Category (プロパティ - Record オブジェクト)

対象:Record

書式

object.Category [= Value]
Category プロパティは、次の項目を含みます:
項目 意味
object 対象リスト内のオブジェクトを表す式
Value 0 - 15 の範囲の数値

備考

 

 

Category (プロパティ - ApplicationInfo オブジェクト)

対象:ApplicationInfo

書式

object.Category(Index) [= Value]
Category プロパティは、次の項目を含みます:
項目 意味
object 対象リスト内のオブジェクトを表す式
Index 0 - 15 の範囲の数値
Value 指定されたカテゴリに保存される文字列

Remarks

 

 

CreationDate (プロパティ)

対象:Database

書式

object.CreationDate
CreationDate プロパティは、次の項目を含みます:
項目 意味
object 対象リスト内のオブジェクトを表す式

備考

 

 

Creator (プロパティ)

対象:Database

書式

object.Creator [= Value]
Creator プロパティは、次の項目を含みます:
項目 意味
object 対象リスト内のオブジェクトを表す式
Value データベースファイルが持つ4文字のクリエータID。 有効なクリエータIDは、大文字のみ、もしくは大文字・小文字が混在した文字列で、全て小文字のものはPalmによって予約されています。

備考

 

 

ModificationDate (プロパティ)

対象:Database

書式

object.ModificationDate
ModificationDate プロパティは、次の項目を含みます:
項目 意味
object 対象リスト内のオブジェクトを表す式

備考

 

 

Name (プロパティ)

対象:Database

書式

object.Name [= Value]
Name プロパティは、次の項目を含みます:
項目 意味
object 対象リスト内のオブジェクトを表す式
Value データベース名を表す文字列

備考

 

 

Records (プロパティ)

対象:Database

書式

object.Records
Records プロパティは、次の項目を含みます:
項目 意味
object 対象リスト内のオブジェクトを表す式

備考

 

 

Size (プロパティ)

対象:ApplicationInfo, Record

書式

object.Size [= Value]
The Size プロパティは、次の項目を含みます:
項目 意味
object 対象リスト内のオブジェクトを表す式
Value オブジェクトの新しいサイズ。 オリジナルのオブジェクトの内容は可能な限り保持されます。もし、新しいサイズが従来のサイズよりも大きい場合、そのオブジェクトは切り詰められます。

Remarks

 

 

Type (プロパティ)

対象:Database

書式

object.Type [= Value]
Type プロパティは、次の項目を含みます:
項目 意味
object 対象リスト内のオブジェクトを表す式
Value データベースのタイプを表す4文字の文字列。 有効なタイプは、小文字のみ、もしくは大文字・小文字が混在した文字列で、全て大文字のものはPalmによって予約されています。

備考

このコントロールは、データベースファイルを扱う事を前提としています。従って、タイプにはデータベースを表す「data」を使うのが適切です。