Palm Programmer's Laboratory

トップ 差分 一覧 ソース 検索 ヘルプ RSS ログイン

Palm OS Programmer's API Reference/30-1

←　29 章に戻る?　↑トップへ　31 章に進む　→?

この章のページ 2 へ

この章の索引

30 データとリソース マネージャ （ページ 1）

この章では、ヘッダ ファイル DataMgr.h で定義される、データ マネージャとリソース マネージャ API について説明します。以下のことを説明します。

データとリソース マネージャについて、さらに詳しく知りたければ、Palm OS Programmer's Companion, vol. I の 「ファイルとデータベース」|Palm OS Programmer's Companion を参照してください。

データ マネージャ データ構造体 ^TOP^

DmOpenRef Typedef ^TOP^

目的

DmOpenRef 型はオープンされたデータベースへのポインタを定義します。データベース ポインタは DmOpenDatabase() によって作成され、返されます。そのポインタは、オープンされたデータベースへのアクセスを要求するいくつかの関数で使用されます。

Prototype

typedef void *DmOpenRef;

DmResID Typedef ^TOP^

目的

DmResID 型はリソース識別子を定義します。作成時にそれぞれのリソース ID を代入します。10000 以上のリソース ID はシステムで使用するために予約されていることに注意してください。

Prototype

typedef UInt32 DmResID;

DmResType Typedef ^TOP^

目的

DmResType 型はリソースの型を定義します。リソース型は、ビットマップ リソースである "'Tbmp'" などの 4 文字のコードです。

Prototype

typedef UInt32 DmResType;

SortRecordInfoType 構造体 ^TOP^

目的

SortRecordInfoType 構造体はレコードのソートに使用できる情報を指定します。データベースをソートする関数（DmInsertionSort() と DmQuickSort()）はこの構造体を比較コールバック関数（ DmComparF() のような）に渡します。比較コールバック関数で、この構造体の情報を 2 つのレコードを比較するのに役立てることができます。この構造体を作成するために、与えられたレコードからこれらの値を返す DmRecordInfo() を呼び出すことができます。

Prototype

typedef struct {
	UInt8 attributes;
	UInt8 uniqueID[3];
} SortRecordInfoType;

typedef SortRecordInfoType *SortRecordInfoPtr;

フィールド

データ マネージャ定数 ^TOP^

カテゴリ定数 ^TOP^

以下の定数はカテゴリについての情報を指定するのに使用されます。
定数 値 説明
dmAllCategories 0xFF すべてのカテゴリを表すために使用されるマスク
dmCategoryLength 16 カテゴリ名の長さ。現在のところ、null 終端子を含めて 16 バイト
dmRecAttrCategoryMask 0x0F レコードの属性フィールドからカテゴリ情報を調べるために使用されるマスク
dmRecNumCategories 16 許可されているカテゴリ数。現在のところ、「未分類」カテゴリを含め 16
dmUnfiledCategory 0 未分類カテゴリを示すのに使用されるマスク

レコード属性定数 ^TOP^

以下の定数はデータベース レコードの属性を指定するために使用されます。
定数 値 説明
dmMaxRecordIndex 0xFFFF 許可されるレコード インデックスの最大値を示す
dmAllRecAttrs 0xF0 すべてのレコード属性を指定するのに使用されるマスク
dmRecAttrBusy 0x20 Busy 状態（アプリケーションがこのレコードにアクセスするためにロックしている）。このビットがセットされているレコードに DmGetRecord() を呼び出すと失敗します。そうでなければ、この関数がこのビットをセットします。レコードを解放し、このビットをクリアするためには、DmReleaseRecord() を呼び出します。dmRecAttrBusy の状態を変えるために DmSetRecordInfo()
dmRecAttrDelete 0x80 Deleted
dmRecAttrDirty 0x40 Dirty （最後の sync の後に変更されている）
dmRecAttrSecret 0x10 プライベート
dmSysOnlyRecAttrs 0x20 レコード属性を指定するのに使用されるマスク。システムのみが変更可能。（言い換えると、busy 属性）

データベース属性定数

以下の定数がデータベースの属性を定義するのに使用されます。
定数 説明
dmAllHdrAttrs ヘッダ属性を指定するのに使用されるマスク
dmHdrAttrAppInfoDirty アプリケーション情報ブロックが Dirty （最後の sync の後に変更された）
dmHdrAttrBundle （無線）通信（訳者注: beam とは?）時にデータベースはアプリケーションにバンドルされます。つまり、ユーザがランチャーからアプリケーションを（無線）通信で送る場合に、ランチャーはこのデータベースをリソース データベースやオーバレイ データベースと一緒に（無線）通信で送ります。
この属性は Palm OS 4.0 以降で適用されます。Palm OS 4.0 以降では、オーバレイデータベースは自動的にアプリケーション データベースと一緒に（無線）通信で送られるということに注意してください。オーバレイ データベースではこのビットをセットする必要はありません。
dmHdrAttrCopyPrevention データベースが IR （赤外線） （無線）通信などでコピーされるのを防ぎます。
dmHdrAttrHidden このデータベースは見えなくなります。例えば、この属性は、いくつかのアプリケーションをランチャーのメイン ビューで見えなくするために、セットされます。レコード データベースのこの属性をセットすることで、ランチャーは、レコード数を表示する際に、そのデータベースのレコードを無視するようになります。この属性は Palm OS バージョン 3.2 以降で適用されます。
dmHdrAttrLaunchableData このデータベースはデータ データベースですが、ランチャーから「開始（launch）」させることができます。例えば、この属性は Web Clipping Application Viewer アプリケーションから開始させられる Palm Query Applications (PQAs) にセットされます。
dmHdrAttrOpen データベースはオープンされています。
dmHdrAttrOKToInstallNewer 現在のデータベースがオープンされている場合、バックアップ Conduit はこのデータベースのより新しいバージョンを別の名前でインストールすることができます。このメカニズムは、例えば、Graffiti と Graffiti 2 ショートカット データベースを更新するのに使用されます。
dmHdrAttrReadOnly このデータベースは Read-only データベースです。
dmHdrAttrRecyclable このデータベースはリサイクル可能です。リサイクル可能なデータベースは、クローズされたりシステム リセットがかかると、消去されます。この属性は Palm OS 4.0 以降で適用されます。
dmHdrAttrResetAfterInstall デバイスはこのデータベースがインストールされた後にリセットされなくてはなりません。つまり、HotSync アプリケーションは、このデータベースをインストールした後、強制的にリセットを行います。
dmHdrAttrStream このデータベースはファイル ストリームです。
dmSysOnlyHdrAttrs システムのみが（オープンされたリソース データベースを）変更できるという属性を指定するマスクです。

エラー コード

以下の定数は、データ マネージャとリソース マネージャ 関数により返されるエラー コードを定義します。いくつかの関数は、エラー コードの代わりに、NULL また 0 などの失敗値（failure value）を返します。多くの場合、この値を受け取るとき DmGetLastErr() を呼び出して、より詳細なエラー コードを取得することができます。

また、Palm OS リリース 3.5 より前のリリースでは、あるエラー コンディションが true だと多くのデータ マネージャ関数は ErrFatalDisplayIf() マクロを使用して致命的なエラー メッセージを表示することに注意してください。通常、Palm OS ROM の一部はエラー チェック付きの状態で出荷されるため、致命的なエラー メッセージを受け取ることになるのです。エラー チェックが付いていない ROM の場合、関数はここで挙げるエラー コードのうちの 1 つを返します。（Palm 社はエラー チェックが付いていない ROM をリリースしたことはありませんし、そのようなことをする計画もないということに注意してください。）

定数 説明
dmErrAlreadyExitst 同名のデータベースがすでに RAM に存在しています。
dmErrAlreadyOpenForWrites データベースはすでに書き込みアクセスできる状態でオープンされています。
dmErrCantFind 指定したリソースが見つかりません。
dmErrCantOpen データベースをオープンできません。
dmErrCorruptDatabase データベースは破壊されています。
dmErrDatabaseOpen データベースはオープンされていますが、関数を実行することができません。
dmErrDatabaseNotProtected DmDatabaseProtect は指定されたデータベースをプロテクトするのに失敗しました。
dmErrDatabaseProtected データベースはプロテクトされています。
dmErrIndexOutOfRange 指定されたインデックスは範囲外です。
dmErrInvalidDatabaseName 指定した名前はデータベースの名前としては無効です。
dmErrInvalidPara 関数が無効なパラメータを受け取りました。
dmErrMemError メモリ エラーが生じました。
dmErrNotOpenDatabase 関数がオープンされているデータベースを探しましたが、オープンされたデータベースはありません。
dmErrNotRecordDB リソース データベースにレコード関数を実行しようとしました。
dmErrNotBalidRecord レコード ハンドルが無効です。
dmErrOpenedByAnotherTask 他のタスクがすでにオープンしたデータベースをオープンしようとしました。
dmErrReadOnly Read-only モードのデータベースに書き込みまたは変更しようとしました。
dmErrRecordArchived 関数はレコードがアーカイブされないことを要求していますが、そのレコードはアーカイブされています。
dmErrRecordBusy 関数はレコードが Busy 状態でないことを要求していますが、そのレコードは Busy 状態です。
dmErrRecordDeleted レコードはすでに削除されています。
dmErrRecordInWrondCard レコードとデータベースが異なるメモリ カードに存在しているのに、レコードをデータベースに追加しようとしました。
dmErrResourceNotFound リソースが見つかりません。
dmErrROMBased ROM ベースのデータベースを削除または変更しようとしました。
dmErrSeekFailed カテゴリの次のレコードを探す操作が失敗しました。
dmErrUniqueIDNotFound 指定された ID のレコードが見つかりません。
dmErrWriteOutOfBounds 書込み操作がレコードの境界を越えてしまいました。
memErrCardNotPresent 指定されたカードが見つかりません。
memErrChunkLocked 関連するメモリ チャンクはロックされています。
memErrInvalidParam, memErrNotEnoughSpace メモリ エラーが生じました。
memErrInvalidStoreHeader, memErrRAMOnlyCard 指定されたカードは RAM を持っていません。
omErrBaseRequiresOverlay 分割されたリソース データベースをオープンしようとしましたが、関連するオーバレイが見つかりませんでした。
omErrUnknownLocale 知らないロケール（訳者注: Locale）を使用しているオーバレイでリソース データベースをオープンしようとしました。

オープン モード定数 ^TOP^

以下の定数がデータベースをオープンするときのモードを定義しています。これらの定数の 1 つまたはいくつかを DmOpenDatabase(), DmOpenDatabaseByTypeCreator() または DmOpenDBNoOverlay() へのパラメータとして渡します。

定数 説明
dmModeReadWrite Read-write アクセス
dmModeReadOnly Read-only アクセス
dmModeWrite Write-only アクセス
dmModeLeaveOpen アプリケーションを終了した後もデータベースをオープンにしておく
dmModeExclusive このデータベースを他の人にオープンさせない
dmModeShowSecret プライベート の レコードを表示する

その他の定数 ^TOP^

以下の追加定数がデータ マネージャとの接続に使用されます。

定数 値 説明
dmDBNameLength 32 null 終端子を含むデータベース名の最大長。データベースには 7 ビット ASCII 文字（0x20 から 0x7E）しか使えません。

データ マネージャ関数 ^TOP^

DmArchiveRecord 関数 ^TOP^

目的

レコード チャンクに手をつけずに次の sync のために削除ビットをセットすることで、レコードにアーカイブされるようマークをします。

宣言されている場所

DataMgr.h

Prototype

Err DmArchiveRecord (
	DmOpenRef dbP,
	UInt16 index
)

パラメータ

  • → dbP
    • オープンされたデータベースへの DmOpenRef
  • → index
    • アーカイブするレコードを指定します。

返り値

エラーが無ければ errNone を返します。エラーがある場合は以下のエラーの 1 つを返します。

これらのエラーのいくつかは、エラー コードを返す代わりに、致命的なエラー メッセージを表示するかもしれません。

コメント

レコードをアーカイブするとき、削除ビットはセットされていますが、チャンクは解放されておらず、ローカル ID は存在しています。これにより、次にユーザがデスクトップ システムと同期を取るとき、デスクトップは Palm デバイスからレコード エントリとデータを永久に削除する前にレコード データを PC に保存することができます。

DmArchiveRecord の呼び出しがレコードの操作が終了し、再びそれを参照することがないということを意味するという仮定に基づき、この関数はチャンクのロック カウントを 0 にセットします。

互換性

Palm OS Cobalt Feature Set を満たす場合に PIM アプリケーション データベースにかかわるこの関数を呼び出すと、PACE は呼び出しを阻止して、対応するスキーマ データベースに対して適切な行動をとります。詳細は、「PIM アプリケーション データベースへのアクセス」? を参照してください。

参照

DmRemoveRecord(), DmDetachRecord(), DmNewRecord(), DmDeleteRecord()

DmAttachRecord 関数 ^TOP^

目的

存在するチャンク ID ハンドルをレコードとしてデータベースに追加します。

宣言されている場所

DataMgr.h

Prototype

Err DmAttachRecord (
	DmOpenRef dbP,
	UInt16 *atP,
	MemHandle newH,
	MemHandle *oldHP
)

パラメータ

  • → dbP
    • オープンされたデータベースへの DmOpenRef
  • ←→ atP
    • 新しいレコードを作成すべき場所を示すインデックスへのポインタ。レコードをデータベースの最後に追加するために dmMaxRecordIndex 値を指定します。
  • → newH
    • 新しいレコードのハンドル
  • ←→ oldHP
    • エントリのときに non-NULL であれば、*atP が示すレコードが置き換えられるであろうということを意味します。リターンのときであれば、置き換えられたレコードへのハンドルになります。

返り値

エラーが無ければ errNone を返します。エラーが生じた場合は以下のうちの 1 つを返します。

いくつかのエラーは、エラー コードを返す代わりに、致命的なエラー メッセージを表示するかもしれません。

コメント

存在するチャンクのハンドルが与えられると、このルーチンはそのチャンクをデータベースの新しいレコードにし、Dirty ビットをセットします。パラメータ atP はインデックス変数を指します。
oldHP が NULL の場合、新しいレコードはインデックス *atP に挿入され、その後のインデックスはすべてシフト ダウンされます。*atP がデータベースの現在のレコード数よりも大きい場合、新しいレコードは最後に挿入され、そのインデックスは *atP で返されます。oldHP が NULL でない場合、新しいレコードはインデックス *atP に存在するレコードと置き換えられ、古いレコードのハンドルは *oldHP で返されます。返されたハンドルで、アプリケーションは古いレコードを解放したり、他のデータベースに追加することができます。

この関数は、データベース間でカット＆ペーストを行うのに有用です。

互換性

Palm OS Cobalt Feature Set を満たす場合に PIM アプリケーション データベースにかかわるこの関数を呼び出すと、PACE は呼び出しを阻止して、対応するスキーマ データベースに対して適切な行動をとります。詳細は、「PIM アプリケーション データベースへのアクセス」? を参照してください。

参照

DmDetachRecord(), DmNewRecord(), DmNewHandle(), DmFindSortPosition()

DmAttachResource 関数 ^TOP^

目的

存在するチャンク ID を新しいリソースとしてリソース データベースに追加します。

宣言されている場所

DataMgr.h

Prototype

Err DmAttachResource (
	DmOpenRef dbP,
	MemHandle newH,
	DmResType resType,
	DmResID resID
)

パラメータ

  • → dbP
    • オープンされたデータベースへの DmOpenRef
  • → newH
    • 新しいリソースのデータのハンドル
  • → resType
    • 新しいリソースの型
  • → resID
    • 新しいリソースの ID

返り値

エラーが無ければ errNone を返します。エラーが生じた場合は以下の 1 つを返します。

いくつかのエラーは、エラー コードを返す代わりに、致命的なエラー メッセージを表示するかもしれません。データベースがリソース データベースでない場合は、すべてのエラーが致命的なエラー メッセージを表示するかもしれません。

コメント

リソース データが収められている存在するチャンクのハンドルを与えられると、このルーチンはそのチャンクをリソース データベースの新しいレコードにします。新しいリソースは与えられた型と ID を持ちます。

参照

DmDetachRecord(), DmRemoveRecord(), DmNewHandle(), DmNewResource()

DmCloseDatabase 関数 ^TOP^

目的

データベースをクローズします。

宣言されている場所

DataMgr.h

Prototype

Err DmCloseDatabase (
	DmOpenRef dbP
)

パラメータ

  • → dbP
    • データベースにアクセスするためのポインタ

返り値

エラーが無ければ errNone を返します。エラーが生じた場合は dmErrInvalidParam を返します。いくつかのエラーは、エラー コードを返す代わりに、致命的なエラー メッセージを表示するかもしれません。

コメント

このルーチンはロックされていたレコードのロックを解除しません。レコードとリソースはロックされたままにしておくべきではありません。レコード/リソースがロックされたままだと、それらの参照を使用できません。なぜなら、HotSync の間やデータベースがユーザによって削除されるとき、レコードは隠れていられるからです。データベースが削除されるのを防ぐために、クローズする前に DmDatabaseProtect() を使うことができます。

渡されたデータベースと関連のあるオーバレイがある場合、DmCloseDatabase はオーバレイもクローズします。

データベースにリサイクル可能ビット（dmHdrAttrRecyclable）がセットされている場合、DmCloseDatabase はデータベースを削除するために DmDeleteDatabase() を呼び出します。

互換性

Palm OS 2.0 以降では、DmCloseDatabase はデータベースの更新日付を更新します。

  • Palm OS 2.0 では、データベースが Write アクセスでオープンされていた場合に DmCloseDatabase は更新日付を更新します。
  • Palm OS 3.0 以降では、データベースが Write アクセスでオープンされていて、変更があった場合にのみ更新日付が更新されます。更新を引き起こす変更とは、レコードの追加、削除、アーカイブ、レコードの範囲またはサイズの変更、DmReleaseRecord() によるレコードの Dirty ビットのセット、カテゴリの範囲の変更または削除、DmSetDatabaseInfo() によるデータベース ヘッダ フィールドの更新です。

Palm OS 1.0 では、更新日付は更新されませんでした。

OS バージョンに関係なく同じ基準で更新日付が更新されることを確実にする必要がある場合、DmSetDatabaseInfo() を使うことで明示的に更新日付をセットできます。

Palm OS Cobalt Feature Set を満たす場合に PIM アプリケーション データベースにかかわるこの関数を呼び出すと、PACE は呼び出しを阻止して、対応するスキーマ データベースに対して適切な行動をとります。詳細は、「PIM アプリケーション データベースへのアクセス」? を参照してください。

参照

DmOpenDatabase(), DmDeleteDatabase(), DmOpenDatabaseByTypeCreator()

DmCreateDatabase 関数 ^TOP^

目的

指定したカードに、与えられた名前、作成者、型で新しいデータベースを作成します。

宣言されている場所

DataMgr.h

Prototype

Err DmCreateDatabase (
	UInt16 cardNo,
	const Char *nameP,
	UInt32 creator,
	UInt32 type,
	Boolean resDB
)

パラメータ

  • → cardNo
    • データベースを作成するカード番号
  • → nameP
    • 新しいデータベースの名前。null 終端子を込みにして、ASCII で 32 バイト長までです（dmDBNameLength で指定されます）。データベースの名前には 7 ビット ASCII 文字（0x20 から 0x7E まで）のみが使用できます。
  • → creator
    • データベースの作成者
  • → type
    • データベースの型
  • → res
    • true の場合、リソース データベースを作成します。

返り値

エラーが無ければ errNone を返します。エラーが起きた場合は以下のうちの 1 つを返します。

マスター データベース リストが見つからない場合は、致命的なエラー メッセージを表示するかもしれません。

コメント

指定されたカードに新しいデータベースを作成するためにこのルーチンを呼び出します。同名のデータベースがすでに RAM に存在している場合、このルーチンは dmErrAlreadyExists エラー コードを返します。一旦データベースが作成されると、DmFindDatabase() を呼び出すことでそのデータベース ID を検索することができます。データベース ID を使うことでデータベースをオープンすることができます。レコード用のデータベースの代わりに、リソース データベースを作成する場合は、resDB Bool 値を true にセットします。

データベースの作成後に、DmSetDatabaseInfo() を呼び出してバージョン番号をセットすることが推奨されています。データベースのバージョンが明示的にセットされない場合、デフォルトの 0 になります。

参照

DmCreateDatabaseFromImage(), DmCreateDatabase(), DmDeleteDatabase()

DmCreateDatabaseFromImage 関数 ^TOP^

目的

データベースのイメージを収めている 1 つのリソースからデータベース自体を作成します。

宣言されている場所

DataMgr.h

Prototype

Err DmCreateDatabaseFromImage (
	MemPtr bufferP
)

パラメータ

  • → bufferP
    • データベース イメージを収めているロックされたリソースへのポインタ

返り値

エラーが無ければ errNone を返します。

コメント

イメージは、prc または pdb ファイルのデスクトップ ファイル表現と同じです。

この関数は、ハード リセット後に ROM にあるアプリケーションのために、デフォルト データベースをインストールするように意図されています。デフォルト データベースをインストールする必要のある RAM ベースのアプリケーションは、ストレージ ヒープ スペースを保存するために、pdb ファイルを個々にインストールすべきです。

参照

DmCreateDatabase(), DmOpenDatabase()

DmDatabaseInfo ^TOP^

目的

データベースに関する情報を検索します。

宣言されている場所

DataMgr.h

Prototype

Err DmDatabaseInfo (
	UInt16 cardNo,
	LocalID dbID,
	Char *nameP,
	UInt16 *attributesP,
	UInt16 *versionP,
	UInt32 *crDateP,
	UInt32 *modDateP,
	UInt32 *bckUpDateP,
	UInt32 *modNumP,
	LocalID *appInfoIDP,
	LocalID *sortInfoIDP,
	UInt32 *typeP,
	UInt32 *creatorP
)

パラメータ

  • → cardNo
    • データベースが存在しているカードの番号
  • → dbID
    • データベースのデータベース ID
  • ← nameP
    • データベースの名前。このパラメータに対して、32 バイトの文字配列へのポインタを渡してください。名前について気にしない場合は、NULL を渡してください。
  • ← attributesP
    • データベースの属性フラグ。「データベース属性定数」で挙げられている定数を使って、このパラメータで返される値について問い合わせることができます。
  • ← versionP
    • アプリケーション特有のバージョン番号。デフォルトのバージョン番号は 0 です。バージョン番号について検索したくない場合は、このパラメータに NULL を渡します。
  • ← crDateP
    • データベースが作成された日付。1904 年 1 月 1 日からの秒数で表現されます。作成日付について検索したくない場合は、このパラメータに NULL を渡します。
  • ← modDateP
    • データベースが最後に変更された日付。1904 年 1 月 1 日からの秒数で表現されます。変更日付について検索したくない場合は、このパラメータに NULL を渡します。
  • ← bckUpDateP
    • データベースがバックアップされた日付。1904 年 1 月 1 日からの秒数で表現されます。バックアップ日付について検索したくない場合は、このパラメータに NULL を渡します。
  • ← modNumP
    • 変更番号。データベースのレコードが追加、変更、または削除されるたびに +1 されます。変更番号について検索したくない場合は、このパラメータに NULL を渡します。
  • ← appInfoIDP
    • アプリケーション情報ブロックのローカル ID、または NULL。アプリケーション情報ブロックは、データベースがデータベースについてのアプリケーション特有の情報を格納するかもしれない任意の（オプションである）フィールドです。これについて検索したくない場合は、このパラメータに NULL を渡します。
  • ← sortInfoIDP
    • データベースのソート テーブルのローカル ID。これは、データベース ヘッダにある任意の（オプションである）フィールドです。これについて検索したくない場合は、このパラメータに NULL を渡します。
  • ← typeP
    • データベースが作成されるときに指定されたデータベースの型。これについて検索したくない場合は、このパラメータに NULL を渡します。
  • ← creatorP
    • データベースが作成されるときに指定されたデータベースの作成者。これについて検索したくない場合は、このパラメータに NULL を渡します。

返り値

エラーが無ければ errNone を返します。エラーが起きた場合は dmErrInvalidParam を返します。

互換性

変更日付の更新は、アプリケーションが実行されている OS のバージョンによって異なります。

  • Palm OS 1.0 では、更新日付は更新されません。
  • Palm OS 2.0 では、更新日付はWrite アクセスでオープンされたデータベースがクローズされるたびに更新されます。
  • Palm OS 3.0 以降では、更新日付は Write アクセスでオープンされたデータベースに変更が加えられた場合にのみ更新されます（更新はデータベースがクローズされたときに行われます）。更新を引き起こす変更とは、レコードの追加、削除、アーカイブ、レコードの範囲またはサイズの変更、DmReleaseRecord() によるレコードの Dirty ビットのセット、カテゴリの範囲の変更または削除、DmSetDatabaseInfo() によるデータベース ヘッダ フィールドの更新です。

OS バージョンに関係なく同じ基準で更新日付が更新されることを確実にする必要がある場合、DmSetDatabaseInfo() を使うことで明示的に更新日付をセットできます。

参照

DmSetDatabaseInfo(), DmDatabaseSize(), DmOpenDatabaseInfo(), DmFindDatabase(), DmGetNextDatabaseByTypeCreator(), TimSecondsToDateTime()

DmDatabaseProtect 関数 ^TOP^

目的

データベースのプロテクト カウントを +1 または -1 します。

宣言されている場所

DataMgr.h

Prototype

Err DmDatabaseProtect (
	UInt16 cardNo,
	LocalID dbID,
	Boolean protect
)

パラメータ

  • → cardNo
    • プロテクト/プロテクト解除するデータベースのカード番号
  • → dbID
    • プロテクト/プロテクト解除するデータベースのローカルID
  • → protect
    • true の場合、protect カウントは +1 されます。false の場合、protect カウントは -1 されます。

返り値

エラーが無い場合は、errNone を返します。エラーが起きた場合は、以下の 1 つを返します。

コメント

このルーチンはデータベースが削除されるのを防ぐために使用することができます（protect パラメータに true を渡すことによって）。protect が true の場合、プロテクト カウントは +1 され、protect が false の場合は -1 されます。アプリケーションを終了する前に、true をセットした回数と false をセットした回数のバランスをとっておかなくてはなりません。

この関数は、データベースの特定のレコードまたはリソースをロックし、かつ、そのデータベースをオープンしたくない場合に、使用します。プロテクト情報はダイナミック ヒープに保存され、システム リセット時にはすべてのデータベースのプロテクトが解除されます。

現在のロケールに関連するオーバレイを保持するリソース データベースの場合、そのオーバレイもこの関数によりプロテクトまたはプロテクト解除されます。

互換性

2.0 New Feature Set を満たし場合に実装されます。オーバレイ サポートは、3.5 New Feature Set を満たす場合にのみ使用可能です。

DmDatabaseSize 関数 ^TOP^

目的

データベースのサイズ情報を調べます。

宣言されている場所

DataMgr.h

Prototype

Err DmDatabaseSize (
	UInt16 cardNo,
	LocalID dbID,
	UInt32 *numRecordsP,
	UInt32 *totalBytesP,
	UInt32 *dataBytesP
)

パラメータ

  • → cardNo
    • データベースが存在するカード番号
  • → dbID
  • データベースのデータベース ID
  • ← numRecordsP
    • データベースに存在するレコードの総数。この値について調べたくない場合は、このパラメータに NULL を渡してください。
  • ← totalBytesP
    • オーバヘッドを含むデータベースの総バイト数。この値について調べたくない場合は、このパラメータに NULL を渡してください。
  • ← dataBytesP
    • レコードのデータ保存に使用されているデータベースの総バイト数。この値について調べたくない場合は、このパラメータに NULL を渡してください。

返り値

エラーが無い場合は、errNone を返します。エラーが起きた場合は、dmErrMemError を返します。
互換性

Palm OS Cobalt Feature Set を満たす場合に PIM アプリケーション データベースにかかわるこの関数を呼び出すと、PACE は呼び出しを阻止して、対応するスキーマ データベースに対して適切な行動をとります。詳細は、「PIM アプリケーション データベースへのアクセス」? を参照してください。

参照

DmDatabaseInfo(), DmOpenDatabaseInfo(), DmFindDatabase(), DmGetNextDatabaseByTypeCreator()

DmDeleteCategory 関数 ^TOP^

目的

カテゴリのすべてのレコードを削除します。カテゴリ名は変化しません。

宣言されている場所

DataMgr.h

Prototype

Err DmDeleteCategory (
	DmOpenRef dbR,
	UInt16 categoryNum
)

パラメータ

  • → dbP
    • データベース アクセス ポインタ
  • → categoryNum
    • 削除するレコードのカテゴリ。dmAllCategorie などのカテゴリ マスクは有効ではありません。

返り値

エラーが無い場合は、errNone を返します。エラーが起きた場合は、以下の 1 つを返します。

いくつかのエラーは、エラー コードを返す代わりに、致命的なエラー メッセージを表示するかもしれません。

コメント

この関数はカテゴリのすべてのレコードを削除します。しかし、カテゴリ自体は削除しません（この関数はレコード データとヘッダ情報を削除しますが、削除ビットをセットするわけではないことに注意してください）。レコードの各レコードに対して、DmDeleteCategory はデータベース ヘッダに deleted ビットをセットし、レコードのデータ チャンクを処分します。データベース ヘッダのレコード エントリは残りますが、レコード エントリの localChunkID には NULL がセットされます。

カテゴリがレコードを持っていない場合、この関数は何もせず、処理が成功したことを意味する errNone を返します。categoryNum パラメータは存在する単一のカテゴリでなくてはなりません。複数のカテゴリを示すカテゴリ マスクを渡すと、この関数はその値が単一のカテゴリを示すと解釈し、カテゴリ中に削除するレコードはないと判断して errNone を返します。

与えられたレコードからカテゴリ インデックスを取得するのに DmRecordInfo() を使用することができます。使用例:

DmOpenRef myDB; 
UInt16 record, attr, category, total; 

DmRecordInfo(myDB, record, &attr, NULL, NULL); 
category = attr & dmRecAttrCategoryMask; 
err = DmDeleteCategory(myDB, category);

互換性

2.0 New Feature Set を満たす場合に実装されます。

Palm OS Cobalt Feature Set を満たす場合に PIM アプリケーション データベースにかかわるこの関数を呼び出すと、sysErrNotAllowed が返されます。詳細は、「PIM アプリケーション データベースへのアクセス」? を参照してください。

DmDeleteDatabase 関数 ^TOP^

目的

データベースとすべてのレコードを削除します。

宣言されている場所

DataMgr.h

Prototype

Err DmDeleteDatabase (
	UInt16 cardNo,
	LocalID dbID
)

パラメータ

  • → cardNo
    • データベースが存在しているカード番号
  • → dbID
    • データベース ID

返り値

エラーが無い場合は、errNone を返します。エラーが起きた場合は以下の 1 つを返します。

コメント

データベースを削除するためにこの関数を呼び出します。この関数はデータベース、アプリケーション情報ブロック、ソート情報ブロック、それにこのデータベースに関連するすべての他のオーバヘッド情報を削除します。データベースを削除した後、この関数は待機していた sysNotifyDBDeletedEvent 通知をキューに追加し、その通知はイベント ループの先頭にブロードキャストされます。

データベースが関連するオーバレイを持っている場合、この関数はそのオーバレイを削除しません。このオーバレイは別個に DmDeleteDatabase を呼び出すことで削除できます。

このルーチンはパラメータとしてデータベース ID を受け付けます。データベース ID を決定するために、データベース インデックスを使って DmFindDatabase() または DmGetDatabase() を呼び出します。

互換性

4.0 New Feature Set を満たす場合にのみ、sysNotifyDBDeletedEvent はブロードキャストされます。

参照

DmDeleteRecord(), DmRemoveRecord(), DmRemoveResource(), DmCreateDatabase(), DmGetNextDatabaseByTypeCreator(), DmFindDatabase()

DmDeleteRecord 関数 ^TOP^

目的

データベースからレコードのチャンクを削除します。しかし、ヘッダのレコード エントリは残しておき、次の sync のために deleted ビットをセットします。

宣言されている場所

DataMgr.h

Prototype

Err DmDeleteRecord (
	DmOpenRef dbP,
	UInt16 index
)

パラメータ

  • → dbP
    • オープンされたデータベースへの DmOpenRef
  • → index
    • 削除するレコード

返り値

エラーが無い場合は、errNone を返します。エラーが起きた場合は以下の 1 つを返します。

いくつかのエラーは、エラー コードを返す代わりに、致命的なエラー メッセージを表示するかもしれません。

コメント

レコードのデータベース ヘッダに deleted ビットをセットし、レコードのデータ チャンクを処分します。データベースからレコード エントリを削除することはしませず、単にレコード エントリの localChunkID に NULL をセットします。

互換性

Palm OS Cobalt Feature Set を満たす場合に PIM アプリケーション データベースにかかわるこの関数を呼び出すと、PACE は呼び出しを阻止して、対応するスキーマ データベースに対して適切な行動をとります。詳細は、「PIM アプリケーション データベースへのアクセス」? を参照してください。

参照

DmDetachRecord(), DmRemoveRecord(), DmArchiveRecord(), DmNewRecord()

DmDetachRecord 関数 ^TOP^

目的

データベースからレコードを取り外し、孤立したレコードにします。しかし、レコードのチャンクは削除しません。

宣言されている場所

DataMgr.h

Prototype

Err DmDetachRecord (
	DmOpenRef dbP,
	UInt16 index,
	MemHandle *oldHP
)

パラメータ

  • → dbP
    • オープンされたデータベースへの DmOpenRef
  • → index
    • 取り外すレコードのインデックス
  • ←→ oldHP
    • 取り外されたレコードのハンドルを返すためのポインタ

返り値

エラーが無い場合は、errNone を返します。エラーが起きた場合は以下の 1 つを返します。

いくつかのエラーは、エラー コードを返す代わりに、致命的なエラー メッセージを表示するかもしれません。

コメント

この関数は、データベース ヘッダからレコードのエントリを削除することにより、レコードをデータベースから取り外します。レコードのデータ チャンクのハンドルを *oldHP に収めて返します。DmDeleteRecord() とは異なり、このルーチンはデータベース ヘッダからレコード エントリを削除しますが、レコードの実体は削除しません。

互換性

Palm OS Cobalt Feature Set を満たす場合に PIM アプリケーション データベースにかかわるこの関数を呼び出すと、PACE は呼び出しを阻止して、対応するスキーマ データベースに対して適切な行動をとります。詳細は、「PIM アプリケーション データベースへのアクセス」? を参照してください。

参照

DmAttachRecord(), DmRemoveRecord(), DmArchiveRecord(), DmDeleteRecord()

DmDetachResource 関数

目的

データベースからリソースを取り外し、リソースのデータのハンドルを返します。

宣言されている場所

DataMgr.h

Prototype

Err DmDetachResource (
	DmOpenRef dbP,
	UInt16 index,
	MemHandle *oldHP
)

パラメータ

  • → dbP
    • オープンされたデータベースへの DmOpenRef
  • → index
    • 取り外すリソースのインデックス
  • ←→ oldHP
    • 取り外されたリソース（訳者注: record となっていたが resource と思われる）のハンドルを返すためのポインタ

返り値

エラーが無い場合は、errNone を返します。エラーが起きた場合は以下の 1 つを返します。

いくつかのエラーは、エラー コードを返す代わりに、致命的なエラー メッセージを表示するかもしれません。データベースがリソース データベースでない場合は、すべてのエラーは致命的なエラー メッセージを表示します。

コメント

このルーチンは、データベース ヘッダからリソースのエントリを削除することにより、リソースをデータベースから取り外します。リソースのデータ チャンクのハンドルを *oldHP に収めて返します。

参照

DmAttachResource(), DmRemoveResource()

DmFindDatabase 関数 ^TOP^

目的

カード番号と名前からデータベースのデータベース ID を返します。

宣言されている場所

DataMgr.h

Prototype

LocalID DmFindDatabase (
	UInt16 cardNo,
	const Char *nameP
)

パラメータ

  • → cardNo
    • 検索するカードの番号
  • → nameP
    • 探すデータベースの名前

返り値

データベース ID を返します。データベースが見つからない場合、この関数は 0 を返します。DmGetLastErr() が失敗した理由を示すエラー コードを返します。

互換性

Palm OS Cobalt Feature Set を満たす場合に PIM アプリケーション データベースにかかわるこの関数を呼び出すと、PACE は呼び出しを阻止して、対応するスキーマ データベースに対して適切な行動をとります。詳細は、「PIM アプリケーション データベースへのアクセス」? を参照してください。

参照

DmGetNextDatabaseByTypeCreator(), DmDatabaseInfo(), DmOpenDatabase()

DmFindRecordByID 関数 ^TOP^

目的

与えられた固有の ID を持つレコードのインデックスを返します。

宣言されている場所

DataMgr.h

Prototype

Err DmFindRecordByID (
	DmOpenRef dbP,
	UInt32 uniqueID,
	UInt16 *indexP
)

パラメータ

  • → dbP
    • データベース アクセス ポインタ
  • → uniqueID
    • 探す対象となる固有 ID
  • ← indexP
    • 返り値となるインデックス

返り値

見つかった場合は、0 を返します。見つからなかった場合は、dmErrUniqueIDNotFound を返します。固有 ID が無効な場合は、致命的なエラー メッセージを表示するかもしれません。

互換性

Palm OS Cobalt Feature Set を満たす場合に PIM アプリケーション データベースにかかわるこの関数を呼び出すと、PACE は呼び出しを阻止して、対応するスキーマ データベースに対して適切な行動をとります。詳細は、「PIM アプリケーション データベースへのアクセス」? を参照してください。

参照

DmQueryRecord(), DmGetRecord(), DmRecordInfo()

DmFindResource 関数 ^TOP^

目的

型と ID 、または、ポインタ（NULL でない場合）で指定されたリソース データベースを探します。

宣言されている場所

DataMgr.h

Prototype

UInt16 DmFindResource (
	DmOpenRef dbP,
	DmResType resType,
	DmResID resID,
	MemHandle resH
)

パラメータ

  • → dbP
    • オープンされたリソース データベースへのポインタ
  • → resType
    • 探すリソースの型
  • → resID
    • 探すリソースの ID
  • → resH
    • ロックされたリソースへのポインタ、または、NULL

返り値

リソース データベース中のリソースのインデックスを返します。見つからなかった場合は、dmInvalidRecIndex を返します。

データベースがリソース データベースではない場合は、致命的なエラー メッセージを表示するかもしれません。

コメント

この関数は、型と ID 、または、ポインタから、個々のリソース データベース中のリソースを探します。ただ 1 つの、最上位ではないデータベースを探す場合に、特に有用です。

重要: この関数は、指定されたデータベース中のリソースを探すことしかしません。ベース リソース データベースへのポインタを渡した場合、そのデータベースのオーバレイで探すことはしません。ベース データベースとそのオーバレイの両方に対してリソースを探す場合は、この関数の代わりに DmGet1Resource() を使用してください。

resH が NULL の場合、型と ID でリソースを探します。

resH が NULL ではない場合、resType と resID は無視され、与えられたロックされたリソースのインデックスを返します。

一旦リソースのインデックスが見つかると、DmGetResourceIndex() を呼び出すことでリソースをロックし、アクセスすることができます。

参照

DmGetResource(), DmSearchResource(), DmResourceInfo(), DmGetResourceIndex(), DmFindResourceType()

DmFindResourceType 関数 ^TOP^

目的

型と型インデックスで与えられたデータベースからリソースを探します。

宣言されている場所

DataMgr.h

Prototype

UInt16 DmFindResourceType (
	DmOpenRef dbP,
	DmResType resType,
	UInt16 typeIndex
)

パラメータ

  • → dbP
    • オープンされたリソース データベースへアクセスするためのポインタ
  • → resType
    • 探すリソースの型
  • → typeIndex
    • 与えられたリソースの型のインデックス

返り値

リソース データベース中のリソースのインデックスを返します。
見つからない場合は、0xFFFF を返します。

データベースがリソース データベースではない場合、致命的なエラー メッセージを表示するかもしれません。

コメント

データベース中に対して、与えられた型のすべてのリソースを探し出すためにこのルーチンを使用します。typeIndex は 0 から始まり、エラーが返されるまで +1 されます。与えられた型のリソースの総数とそれらのリソース個々のインデックスが決定されます。一旦リソースのインデックスが決定されると、DmGetResourceIndex() を呼び出すことでロックし、アクセスすることができます。

重要: この関数は指定されたデータベースのリソースを探すだけです。ベース リソース データベースへのポインタを渡した場合、そのデータベースのオーバレイで探すことはしません。ベース データベースとそのオーバレイの両方に対してリソースを探す場合は、この関数の代わりに DmGet1Resource() を使用してください。

参照

DmGetResource(), DmSearchResource(), DmResourceInfo(), DmGetResourceIndex(), DmFindResource()

DmFindSortPosition 関数 ^TOP^

目的

与えられたレコードがソートされたレコードのリストのどこに位置しているかについて返します。レコードが DmAttachRecord() でどこに挿入されるかを調べるときに有用です。バイナリ サーチを行います。

宣言されている場所

DataMgr.h

Prototype

UInt16 DmFindSortPosition (
	DmOpenRef dbP,
	void *newRecord,
	SortRecordInfoPtr newRecordInfo,
	DmComparF *compar,
	Int16 other
)

パラメータ

  • → dbP
    • データベース アクセス ポインタ
  • → newRecord
    • 新しいレコードへのポインタ
  • → newRecordIndfo
    • 新しいレコードに関するソート情報。SortRecordInfoType を参照してください。
  • → compar
    • 比較関数へのポインタ。DmComparF を参照してください。
  • → other
    • アプリケーションが比較関数に渡すすべての値。このパラメータは、しばしば、ソート方法（昇順または降順）を指示するのに使用されます。

返り値

レコードが挿入される場所を返します。

挿入される場所は、返されたレコードとその前のレコードの間になります。返り値はレコード数よりも大きくなるかもしれないということに注意してください。

コメント

newRecord がデータベースの他のレコードと同じキーを持つ場合、DmFindSortPosition は newRecord はそのレコードの後に挿入されるだろうと仮定します。同じキーを持つレコードが複数ある場合、newRecord はそれらのレコードすべての後に挿入されます。そのため、データベース中に存在していることがあらかじめわかっているレコードに対して DmFindSortPosition を使用する場合は、結果から 1 引かなくてはなりません。（値が 0 にならないことを必ず確認してください。）

データベースに削除されたレコードがある場合、DmFindSortPosiotion はそれらのレコードがデータベースの最後にあるものとして処理します。DmFindSortPosition は常に削除されたレコードは他のすべてのレコード以上であると仮定します。

互換性

2.0 New Feature Set を満たす場合に実装されます。

Palm OS Cobalt Feature Set を満たす場合に PIM アプリケーション データベースにかかわるこの関数を呼び出すと、PACE は呼び出しを阻止して、対応するスキーマ データベースに対して適切な行動をとります。詳細は、「PIM アプリケーション データベースへのアクセス」? を参照してください。

参照

DmFindSortPositionV10()

DmFindSortPositionV10 関数 ^TOP^

目的

与えられたレコードがソートされたレコードのリストのどこに位置しているかについて返します。レコードが DmAttachRecord() でどこに挿入されるかを調べるときに有用です。バイナリ サーチを行います。

宣言されている場所

DataMgr.h

Prototype

UInt16 DmFindSortPositionV10 (
	DmOpenRef dbP,
	void *newRecord,
	DmComparF *compar,
	Int16 other
)

パラメータ

  • → dbP
    • データベース アクセス ポインタ
  • → newRecord
    • 新しいレコードへのポインタ
  • → compar
    • 比較関数へのポインタ。DmComparF を参照してください。
  • → other
    • アプリケーションが比較関数に渡すすべての値。このパラメータは、しばしば、ソート方法（昇順または降順）を指示するのに使用されます。

返り値

レコードが挿入される場所を返します。

挿入される場所は、返されたレコードとその前のレコードの間になります。返り値はレコード数よりも大きくなるかもしれないということに注意してください。

コメント

データベースに削除されたレコードがある場合、DmFindSortPosiotionV10 はそれらのレコードがデータベースの最後にあるものとして処理します。DmFindSortPositionV10 は常に削除されたレコードは他のすべてのレコード以上であると仮定します。

互換性

この関数は DmFindSortPosition をバージョン 1.0 に対応させたものです。

参照

DmFindSortPosition(), DmQuickSort(), DmInsertionSort()

DmGetAppInfoID 関数 ^TOP^

目的

アプリケーション情報ブロックのローカル ID を返します。

宣言されている場所

DataMgr.h

Prototype

LocalID DmGetAppInfoID (
	DmOpenRef dbP
)

パラメータ

  • → dbP
    • データベース アクセス ポインタ

返り値

アプリケーション情報ブロックのローカル ID を返します。アプリケーション情報ブロックは、データベースがデータベースに関するアプリケーション特有の情報を保存するかもしれないオプションのフィールドです。データベースがアプリケーション情報ブロックを持たない場合、DmGetAppInfoID は 0 を返します。

参照

DmDatabaseInfo(), DmOpenDatabase()

DmGetDatabase 関数 ^TOP^

インデックスとカード番号からデータベースのデータベース ヘッダを返します。

宣言されている場所

DataMgr.h

Prototype

LocalID DmGetDatabase (
	UInt16 cardNo,
	UInt16 index
)

パラメータ

  • → cardNo
    • データベースのカード番号
  • → index
    • データベースのインデックス

返り値

データベース ID を返します。無効なパラメータが渡された場合は、0 を返します。

コメント

インデックスからデータベースのデータベース ID を調べるのにこのルーチンを使用します。インデックスの範囲は、0 から DmNumDatabase()-1 です。

このルーチンは、カードに存在しているすべてのデータベースのディレクトリを取得する場合に有用です。返されるデータベースは ROM または RAM のどちらかに存在するかもしれません。データベースが返される順序は固定されていません。したがって、あなたは特定の順序のデータベースのリストを受け取るのを当てにするべきではありません。

参照

DmOpenDatabase(), DmNumDatabases(), DmDatabaseInfo(), DmDatabaseSize()

DmGetDatabaseLockState 関数 ^TOP^

目的

データベース中のロックされ Busy 状態のレコード数に関する情報を返します。

宣言されている場所

DataMgr.h

Prototype

void DmGetDatabaseLockState (
	DmOpenRef dbR,
	UInt8 *highest,
	UInt32 *count,
	UInt32 *busy
)

パラメータ

  • → dbR
    • データベース アクセス ポインタ
  • ← highest
    • データベース中のすべてのレコードのロック カウントで最も高いカウント。データベースが 2 つのレコードを持ち、1 つが 2 のロック1カウントを持ち、もう 1 つが 1 のロック カウントを持つ場合、最も高いロック カウントは 2 になります。この値について調べたくない場合は、このパラメータに NULL を渡してください。
  • ← count
    • highest パラメータで返されるロック カウントを持つレコード数。この値について調べたくない場合は、このパラメータに NULL を渡してください。
  • ← busy
    • Busy ビットがセットされているレコード数。この値について調べたくない場合は、このパラメータに NULL を渡してください。

返り値

返り値はありません。すべての情報を渡されたパラメータに収めて返します。

コメント

この関数はデバッグするために用いられます。この関数を使って、いくつのレコードが Busy 状態にあるか、どれだけロックが起きているのか知ることができます。

互換性

3.2 New Feature Set を満たす場合に実装されます。

DmGetLastErr 関数 ^TOP^

目的

最後のデータ マネージャの呼び出しからのエラー コードを返します。

宣言されている場所

DataMgr.h

Prototype

Err DmGetLastErr (
	void
)

パラメータ

ありません。

返り値

最後の成功しなかったデータ マネージャが呼び出しからのエラー コード。

コメント

データ マネージャの呼び出しが失敗した理由を調べるためにこのルーチンを使用します。特に、DmGetRecord() のように失敗したときに 0 を返す関数の場合、失敗した理由を調べる唯一の方法は DmGetLastErr() を呼び出すことです。

DmGetLastErr がいつでも最後のデータ マネージャの呼び出しのエラー ステータスを反映するわけではないということに注意してください。むしろ、この関数はエラー コードを返さないデータ マネージャのエラー ステータスを反映します。それらのデータ マネージャのいくつかは、呼び出しが成功したときのエラー コードが 0 ではありません。

例えば、DmOpenDatabaseByTypeCreator() の呼び出しが、データベースへの参照として NULL を返してきた（つまり、呼び出しが失敗した）場合、DmGetLastErr|Palm OS Programmer's API Reference/30-2 の返り値は意味のあるものになります。一方、DmGetLastErr が、以前のデータ マネージャの呼び出しのエラーを返す場合もあります。

現在のところ、以下のデータ マネージャ関数が、DmGetLastErr の返り値に影響を与えます。

DmGetNextDatabaseByTypeCreator 関数 ^TOP^

目的

与えられた型と/または、作者から、データベース ヘッダ ID とカード番号を返します。このルーチンはすべてのメモリ カードに対して探索を行います。

宣言されている場所

DataMgr.h

Prototype

Err DmGetNextDatabaseByTypeCreator(
	Boolean newSearch,
	DmSearchStatePtr stateInfoP,
	UInt32 type,
	UInt32 creator,
	Boolean onlyLatestVers,
	UInt16 *cardNoP,
	LocalID *dbIDP
)

パラメータ

  • → newSearch
    • 新しい探索を始める場合は true にします。
  • ←→ stateInfoP
    • newSearch が false の場合、このパラメータには前回の探索で使用したデータと同じものを指定しなくてはなりません。
  • → type
    • 探索するデータベースの型。ワイルドカードにするには 0 を渡します。
  • → creator
    • 探索するデータベースの作者。ワイルドカードにするには 0 を渡します。
  • → onlyLatestVers
    • true の場合、与えられた型と作者から最新バージョンのデータベースのみを返します。
  • ← cardNoP
    • 見つかったデータベースのカード番号を返します。
  • ← dbIDP
    • 見つかったデータベースのローカル ID を返します。

返り値

エラーが無い場合は、errNone を返します。何も見つからなかった場合は dmErrCantFind を返します。

コメント

特定の型/作者のすべてのデータベースを見つけるために、この関数を相次いで呼び出す必要があるかもしれません。

探索を開始するには、newSearch に true を渡します。DmSearchStateType 構造体を割り当て、それを stateInfoP パラメータとして渡します。DmGetNextDatabaseByTypeCreator は内部情報を stateInfoP に保存して、探索が続けられる場合にそれを使用します。

前回の探索で残された分の探索を続ける場合、newSearch に false を渡し、前回この関数を呼び出す際に使用した stateInfoP と同じものを渡します。

より幅広い指定で探索を行うために、type または creator パラメータに対しワイルドカードとして 0 を渡すことができます。type パラメータが 0 の場合、与えられた作者のすべてのデータベースを返すために、このルーチンを相次いで呼び出すことができます。creator パラメータが 0 の場合、与えられた型のすべてのデータベースを返すために、このルーチンを相次いで呼び出すことができます。また、型と作者を指定せず、すべての利用可能なデータベースを返すために、これらのパラメータの両方に 0 を渡すこともできます。

データベースはメモリ空間中を自由に散らばっているため、特定の順番で返されるわけではありません -- 指定された型/作者の評価基準に合うどんなデータベースからでも返されます。そのため、onlyLatestVers パラメータ値が false の場合、この関数が返すデータベースは、指定した型/作者に一致する最新バージョンのデータベースではないかもしれません。指定した評価基準に一致する最新バージョンのデータベースのみを取得するには、onlyLatestVers パラメータ値に true をセットします。

どのデータベースが最新バージョンか決定する際、バージョン番号が同じなら RAM データベースのほうが ROM データベースよりも新しいと見なされます。このため、指定したバージョンのデータベースを使用するどんな ROM ベースのアプリケーションであっても置き換えることができます。また、バージョン番号が同じなら、カード 1 の RAM データベースのほうがカード 0 の RAM データベースよりも新しいと見なされます。

'''"WARNING!"''' DmGetNextDatabaseByTypeCreator を存在しているデータベースに対して繰り返し呼び出している間に、データベースの作成または削除を行ってはいけません。これを行うと、一致するデータベースがスキップされたり、一度返されたデータベースが再度返される可能性があります。

互換性

Palm OS version 3.1 以降では、onlyLatestVers が true の場合、型/作者に一致する 1 つのデータベースを返します。Palm OS version 3.0 以前では、onlyLatestVers が true であっても、複数の一致するデータベースを返す可能性があります。

この関数の振る舞いが異なるのは、型と作者の両方を指定し、かつ、onlyLatestVers が true の場合のみであるということに注意してください。

例えば、あるアプリケーションが同じ型、作者、それにバージョン番号を持つ 3 つのデータベースを保持していて、それらのデータベースを以下のように処理するコードを書いたと仮定します。

DmSearchStateType state; 
Boolean latestVer; 
UInt16 card; 
LocalID currentDB = 0; 

theErr = DmGetNextDatabaseByTypeCreator(true,
  &state, myType, myCreator, latestVer, &card,
  &currentDB);
while (!theErr && currentDB) {
  /* do something with currentDB */
  /* now get the next DB */
  theErr = DmGetNextDatabaseByTypeCreator(
    false, &state, myType, myCreator,
    latestVer, &card, &currentDB);
}

latestVer が false の場合、このコードはすべての Palm OS で同じように機能し、指定した型と作者に一致する 3 つすべてのデータベースを返します。latestVer が true の場合、このコードは Palm OS version 3.0 以前では 3 つすべてのデータベースを返しますが、version 3.1 以降では 1 つのデータベースしか返しません。（どのデータベースが返されるかはわかりません。）

評価基準に一致するデータベースが複数あると予想される場合、コードがすべての Palm OS バージョンで同じように振舞うように、DmGetNextDatabaseByTypeCreator を以下に示す方法の 1 つを使って呼び出すようにしてください。

  • type と creator の両方を指定する場合は、onlyLatestVers に false をセットする。
  • type または creator のどちらか（または両方）に 0 をセットする。

Palm OS Cobalt Feature Set を満たす場合に PIM アプリケーション データベースにかかわるこの関数を呼び出すと、PACE は呼び出しを阻止して、対応するスキーマ データベースに対して適切な行動をとります。詳細は、「PIM アプリケーション データベースへのアクセス」? を参照してください。

参照

DmGetDatabase(), DmFindDatabase(), DmDatabaseInfo(), DmOpenDatabaseByTypeCreator(), DmDatabaseSize()

DmGetRecord 関数 ^TOP^

目的

インデックスからレコードへのハンドルを返し、レコードを Busy 状態にします。

宣言されている場所

DataMgr.h

Prototype

MemHandle DmGetRecord (
	DmOpenRef dbP,
	UInt16 index
)

パラメータ

  • → dbP
    • オープンされたデータベースへの DmOpenRef
  • → index
    • 探索するレコードのインデックス

返り値

レコード データへのハンドルを返します。レコードが解放される前に、同じレコードに対してもう 1 つの DmGetRecord 呼び出しが試みられた場合、NULL が返され、DmGetLastErr() は失敗理由を示すエラー コードを返します。

コメント

与えられたレコードへのハンドルを返し、そのレコードに対して busy をセットします。

レコードが ROM ベース（pointer accessed 訳者??）の場合、このルーチンはそのレコードに対する偽の（訳者注: fake）ハンドルを作成し、このハンドルを DmAccessType 構造体に保存します。

この関数呼び出しでレコードを閲覧または編集した直後に、DmReleaseRecord() を呼び出すべきです。

互換性

Palm OS Cobalt Feature Set を満たす場合に PIM アプリケーション データベースにかかわるこの関数を呼び出すと、PACE は呼び出しを阻止して、対応するスキーマ データベースに対して適切な行動をとります。詳細は、「PIM アプリケーション データベースへのアクセス」? を参照してください。

参照

DmSearchRecord(), DmFindRecordByID(), DmRecordInfo(), DmReleaseRecord(), DmQueryRecord()

DmGetResource 関数 ^TOP^

目的

すべてのオープンされたリソース データベースを探索し、与えられたリソースの型と ID からリソースへのハンドルを返します。

宣言されている場所

DataMgr.h

Prototype

MemHandle DmGetResource (
	DmResType type,
	DmResID resID
)

パラメータ

  • → type
    • リソースの型
  • → resID
    • リソース ID

返り値

リソース データへのハンドル。指定されたリソースが見つからない場合、この関数は NULL を返し、DmGetLastErr() が失敗理由を示すエラー コードを返します。

コメント

すべてのオープンされたリソース データベースのうち最も最近にオープンされたものから、与えられた型と ID のリソースを探します。見つかった場合は、そのリソース ハンドルを返します。リソース データへのアクセスが終了するとすぐに、アプリケーションは DmReleaseResource() を呼び出すべきです。この関数ではリソース ハンドルはロックされません。

オープンされたオーバレイが指定された型と ID に一致するリソースを持つ場合、この関数は常にオーバレイに存在するリソースを返します。オーバレイにリソースが無い場合、この関数はベース データベースからリソースを返します。

参照

DmGet1Resource(), DmReleaseResource(), ResLoadConstant()

DmGetResourceIndex 関数 ^TOP^

目的

インデックスからリソースへのハンドルを返します。

宣言されている場所

DataMgr.h

Prototype

MemHandle DmGetResourceIndex (
	DmOpenRef dbP,
	UInt16 index
)

パラメータ

  • → dbP
    • オープンされたデータベースへのアクセス ポインタ
  • → index
    • ハンドルを取得したいリソースのインデックス

返り値

リソースへのハンドル。指定されたインデックスが範囲外の場合、この関数は NULL を返し、DmGetLastErr() が失敗理由を示すエラー コードを返します。

データベースがリソース データベースではない場合、致命的なエラー メッセージを表示するかもしれません。

重要: この関数は指定されたデータベースのみに対してリソースの探索を行います。ベース リソース データベースを渡した場合、そのオーバレイは探索されません。したがって、潜在的に局所化されたリソースにアクセスする場合にこの機能を使用するとき注意すべきです。リソースが局所化されている場合、オーバレイ データベースへのポインタを取得するために DmSearchResouce() を使用することができます。しかしながら、DmGetResouce() または DmGet1Resouce() を使用するほうが便利です。

参照

DmFindResource(), DmFindResourceType(), DmSearchResource()

DmGet1Resouce 関数 ^TOP^

目的

最も最近にオープンされたリソース データベースを探索し、与えられたリソースの型と ID からリソースへのハンドルを返します。

宣言されている場所

DataMgr.h

Prototype

MemHandle DmGet1Resource (
	DmResType type,
	DmResID resID
)

パラメータ

  • → type
    • リソースの型
  • → resID
    • リソース ID

返り値

リソース データへのハンドル。失敗した場合、この関数は NULL を返し、DmGetLastErr() は失敗理由を示すエラー コードを返します。

コメント

最も最近にオープンされたリソース データベースを探索し、与えられたリソースの型と ID からリソースへのハンドルを返します。データベースが関連するオーバレイを持つ場合、そのオーバレイが最初に探索され、オーバレイがリソースを持っていなかった場合にベース データベースが探索されます。リソースが見つかると、そのリソース ハンドルが返されます。アプリケーションは、リソース データへのアクセスが終了するとすぐに、DmReleaseResource() を呼び出すべきです。この関数によってリソース ハンドルはロックされません。

参照

DmGetResource(), DmReleaseResource(), ResLoadConstant()

DmInsertionSort 関数 ^TOP^

目的

データベース中のレコードをソートします。

宣言されている場所

DataMgr.h

Prototype

Err DmInsertionSort (
	DmOpenRef dbR,
	DmComparF *compar,
	Int16 other
)

パラメータ

  • → dbR
    • データベースにアクセスするためのポインタ
  • → compar
    • 比較関数。DmComparF() を参照してください。
  • → other
    • アプリケーションが比較関数に渡すすべての値。このパラメータは、しばしば、ソート方法（昇順または降順）を指示するのに使用されます。

返り値

エラーが無い場合は、errNone を返します。エラーが起きた場合は、以下の 1 つを返します。

いくつかのエラーは、エラー コードを返す代わりに致命的なエラー メッセージを表示するかもしれません。

コメント

削除されたレコードは、どのような順序でも最後にきます。他のすべてのレコードは、渡された比較関数によって、ソートされます。すでにソートされたレコードの範囲外のレコードのみが移動させられます。移動させるレコードは、ソートされたレコードの後に移動させされます。多くのレコードがソートされる場合は、クイック ソートを使用してみてください。

以下の挿入-ソート アルゴリズムが使用されます: 2 番目のレコードから開始し、各レコードを 1 つ前のレコードと比較します。最終レコードよりも大きくないレコードは、すでにソートされたレコードの適切な位置に挿入されます。バイナリ ソートを行います。移動されるレコードは、他のレコードの後に挿入されます。

Palm OS Cobalt Feature Set を満たす場合に PIM アプリケーション データベースにかかわるこの関数を呼び出すと、PACE は呼び出しを阻止して、対応するスキーマ データベースに対して適切な行動をとります。詳細は、「PIM アプリケーション データベースへのアクセス」? を参照してください。

参照

DmQuickSort()

DmMoveCategory 関数 ^TOP^

カテゴリ中のすべてのレコードを他のカテゴリに移動させます。

宣言されている場所

DataMgr.h

Prototype

Err DmMoveCategory (
	DmOpenRef dbP,
	UInt16 toCategory,
	UInt16 fromCategory,
	Boolean dirty
)

パラメータ

  • → dbP
    • オープンされたデータベースへの DmOpenRef
  • → toCategory
    • レコードを追加すべきカテゴリ
  • → fromCategory
    • レコードが削除されるカテゴリ
  • → dirty
    • true の場合、Dirty ビットをセットします。

返り値

成功した場合は、0 を返します。データベースが Read-only モードの場合は、dmErrReadOnly を返します。いくつかのエラーは、エラー コードを返す代わりに、致命的なエラー メッセージを表示するかもしれません。

コメント

dirty が true の場合、移動させられたレコードには Dirty ビットがセットされます。

toCategory と fromCategory パラメータには、カテゴリ インデックス値が入ります。あるレコードが存在しているカテゴリは DmRecordInfo() を呼び出すことで調べることができ、その値をこの関数に使用することができます。例えば、以下のコードでは、レコード rec1 と rec2 が同じカテゴリに入ることが保証されます。

DmOpenRef myDB; 
UInt16 rec1, rec2; 
UInt16 rec1Attr, rec2Attr; 
UInt16 category1, category2; 

DmRecordInfo (myDB, rec1, &rec1Attr, NULL,  
  NULL); 
category1 = rec1Attr & dmRecAttrCategoryMask; 
DmRecordInfo(myDB, rec2, &rec2Attr, NULL,  
  NULL); 
category2 = rec2Attr & dmRecAttrCategoryMask; 
if (category1 != category2)  
  DmMoveCategory(myDB, category1, category2,  
    true);

互換性

Palm OS Cobalt Feature Set を満たす場合に PIM アプリケーション データベースにかかわるこの関数を呼び出すと、sysErrNotAllowed が返されます。詳細は、「PIM アプリケーション データベースへのアクセス」? を参照してください。

DmMoveRecord 関数 ^TOP^

目的

与えられたインデックスのレコードを他のインデックスに移動させます。

宣言されている場所

DataMgr.h

Prototype

Err DmMoveRecord (
	DmOpenRef dbP,
	UInt16 from,
	UInt16 to
)

パラメータ

  • → dbP
    • オープンされたデータベースへの DmOpenRef
  • → from
    • 移動させるレコードのインデックス
  • → to
    • レコードの移動先

返り値

エラーが無い場合は、errNone を返します。エラーが起きた場合は、以下の 1 つを返します。

いくつかのエラーは、エラー コードを返す代わりに、致命的なエラー メッセージを表示するかもしれません。

コメント

to インデックスにレコードを挿入して、他のレコードを下げます。to で指定された場所が、挿入場所と見なされます。この値は、データベースの最後のレコードのインデックスよりも大きくなるかもしれません。to が from よりも大きい場合、レコードの新しいインデックスは、移動が完了すると、to-1 になります。

互換性

Palm OS Cobalt Feature Set を満たす場合に PIM アプリケーション データベースにかかわるこの関数を呼び出すと、PACE は呼び出しを阻止して、対応するスキーマ データベースに対して適切な行動をとります。詳細は、「PIM アプリケーション データベースへのアクセス」? を参照してください。

この章のページ 2 へ

←　29 章に戻る?　↑トップへ　31 章に進む　→?

Copyright (C) 2002-2006 PalmwareInfo
Powered by FreeStyleWiki3.6.2 with Perl5.032001

Index


メニュー

各種掲示板

検索

キーワード

Wiki

最新

2023/12/1

2021/4/5

2020/7/7

2020/5/15

2020/1/13

2019/4/1

2018/4/18

2018/4/17

Visitor:
[Today:]
[Yesterday:]