Palm OS Programmer's API Reference/30-2

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

---

この章のページ 1 へ

この章の索引

• （ページ 1）
• データ マネージャ データ構造体
  • DmOpenRef
  • DmResID
  • DmResType
  • SortRecordInfoType
• データ マネージャ定数
  • カテゴリ定数
  • レコード属性定数
  • データベース属性定数
  • エラー コード
  • オープン モード定数
  • Miscellaneous Constants
• データ マネージャ関数
  • DmArchiveRecord
  • DmAttachRecord
  • DmAttachResource
  • DmCloseDatabase
  • DmCreateDatabase
  • DmCreateDatabaseFromImage
  • DmDatabaseInfo
  • DmDatabaseProtect
  • DmDatabaseSize
  • DmDeleteCategory
  • DmDeleteDatabase
  • DmDeleteRecord
  • DmDetachRecord
  • DmDetachResource
  • DmFindDatabase
  • DmFindRecordByID
  • DmFindResource
  • DmFindResourceType
  • DmFindSortPosition
  • DmFindSortPositionV10
  • DmGetAppInfoID
  • DmGetDatabase
  • DmGetDatabaseLockState
  • DmGetLastErr
  • DmGetNextDatabaseByTypeCreator
  • DmGetRecord
  • DmGetResource
  • DmGetResourceIndex
  • DmGet1Resource
  • DmInsertionSort
  • DmMoveCategory
  • DmMoveRecord
• （ページ 2）
  • DmNewHandle
  • DmNewRecord
  • DmNewResource
  • DmNextOpenDatabase
  • DmNextOpenResDatabase
  • DmNumDatabases
  • DmNumRecords
  • DmNumRecordsInCategory
  • DmNumResources
  • DmOpenDatabase
  • DmOpenDatabaseByTypeCreator
  • DmOpenDatabaseInfo
  • DmOpenDBNoOverlay
  • DmPositionInCategory
  • DmQueryNextInCategory
  • DmQueryRecord
  • DmQuickSort
  • DmRecordInfo
  • DmReleaseRecord
  • DmReleaseResource
  • DmRemoveRecord
  • DmRemoveResource
  • DmRemoveSecretRecords
  • DmResizeRecord
  • DmResizeResource
  • DmResourceInfo
  • DmSearchRecord
  • DmSearchResource
  • DmSeekRecordInCategory
  • DmSet
  • DmSetDatabaseInfo
  • DmSetRecordInfo
  • DmSetResourceInfo
  • DmStrCopy
  • DmSync
  • DmSyncDatabase
  • DmWrite
  • DmWriteCheck
• アプリケーション定義関数
  • DmComparF

---

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

DmNewHandle 関数 ^TOP^

目的

渡されたデータベース アクセス ポインタのデータベース ヘッダと同じデータ ヒープまたはカードに対して、新しいチャンクの割り当てを試みます。データ ヒープに十分な空き容量が無い場合は、他のヒープで試みます。

宣言されている場所

DataMgr.h

Prototype

MemHandle DmNewHandle (
	DmOpenRef dbP,
	UInt32 size
)

パラメータ

• → dbP
  • オープンされたデータベースへの DmOpenRef
• → size
  • 新しいハンドルのサイズ

返り値

新しいチャンクのチャンク ID を返します。エラーが起きた場合は 0 を返し、DmGetLastErr() が失敗理由を示すエラー コードを返します。

コメント

与えられたサイズの新しいハンドルを割り当てます。新しいハンドルが、与えられたデータベースと同じメモリ カードにあることを保証します。このことは、データベースに新しいハンドルをレコードとして追加でき、かつ、その LocalID をデータベース ヘッダの appInfoID または sortInfoID フィールドに保存できるということを保証します。

新しいハンドルをできる限り早くデータベースに追加すべきです。ハンドルをデータベースに追加できず、アプリケーションがクラッシュした場合、新しいハンドルに使用されたメモリはソフト リセットされるまで使用できません。

互換性

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

DmNewRecord 関数 ^TOP^

目的

データベース中の新しいレコードへのハンドルを返し、レコードを Busy 状態にします。

宣言されている場所

DataMgr.h

Prototype

MemHandle DmNewRecord (
	DmOpenRef dbP,
	UInt16 *atP,
	UInt32 size
)

パラメータ

• → dbP
  • オープンされたデータベースへの DmOpenRef
• ←→ atP
  • 新しいレコードが位置する場所を示すインデックスへのポインタ。データベースの最後にレコードを追加する場合は、dmMaxRecordIndex を指定します。
• → size
  • 新しいレコードのサイズ

返り値

レコード データへのハンドル。エラーが起きた場合、この関数は 0 を返し、DmGetLastErr() が失敗理由を示すエラー コードを返します。データベースが Read-only モードでオープンされている場合、または、データベースがリソース データベースの場合、いくつかのエラーは致命的なエラー メッセージを表示するかもしれません。

コメント

与えられたサイズの新しいレコードを割り当て、そのレコード データへのハンドルを返します。パラメータ atP はインデックス変数を指します。新しいレコードはインデックス *atP に挿入され、その後に位置するすべてのレコードはシフト ダウンされます。*atP がデータベースの現在のレコード数よりも大きい場合、新しいレコードはデータベースの最後に追加され、そのインデックスが *atP で返されます。新しいレコードに対して busy と dirty の両方のビットがセットされ、固有 ID が自動的に作成されます。

レコードの閲覧または編集の完了後は、できるだけ早く DmReleaseRecord() を呼び出すべきです。

互換性

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

参照

DmAttachRecord(), DmRemoveRecord(), DmDeleteRecord()

DmNewResource 関数 ^TOP^

目的

リソース データベースに対して、新しいリソースの割り当てと追加を行います。

宣言されている場所

DataMgr.h

Prototype

MemHandle DmNewResource (
	DmOpenRef dbP,
	DmResType resType,
	DmResID resID,
	UInt32 size
)

パラメータ

• → dbP
  • オープンされたデータベースへの DmOpenRef
• → resType
  • 新しいリソースの型
• → resID
  • 新しいリソースの ID
• → size
  • 新しいリソースに指定するサイズ

返り値

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

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

コメント

新しいリソースにメモリ チャンクを割り当て、与えられたリソース データベースに追加します。新しいリソースは与えられた型と ID を持ちます。成功した場合、アプリケーションは、リソースの初期化が終了後、できるだけ早く DmReleaseResource() を呼び出すべきです。

参照

DmAttachResource(), DmRemoveResource()

DmNextDatabase 関数 ^TOP^

目的

現在のタスクのために、次のオープンされたデータベースへの DmOpenRef を返します。

宣言されている場所

DataMgr.h

Prototype

DmOpenRef DmNextOpenDatabase (
	DmOpenRef currentP
)

パラメータ

• → currentP
  • 現在のデータベース アクセス ポインタまたは NULL

返り値

次のオープンされたデータベースへの DmOpenRef。次のデータベースが無い場合は、NULL を返します。

コメント

すべてのオープンされたデータベースの DmOpenRef を取得するには、このルーチンを相次いで呼び出します。最初の DmOpenRef を取得する場合には、currentP に NULL を渡します。通常、アプリケーションがこの関数を呼び出すことはありませんが、システム情報を取得する場合には有用です。

参照

DmOpenDatabaseInfo(), DmDatabaseInfo()

DmNextOpenResDatabase 関数 ^TOP^

目的

連続した探索を行う場合に、次のオープンされたリソース データベースへのアクセス ポインタを返します。

宣言されている場所

DataMgr.h

Prototype

DmOpenRef DmNextOpenResDatabase (
	DmOpenRef dbP
)

パラメータ

• → dbP
  • データベースへのポインタ。または、先頭から探索を開始する場合には 0。

返り値

次のオープンされたリソース データベースへのポインタ

コメント

次のオープンされたリソース データベースへのポインタを返します。連続した探索で最初のポインタを取得するには、dbP に NULL を渡します。これにより取得されるデータベースは、DmGet1Resouce() の呼び出しで得られるものです。

関連するオーバレイを持つかもしれないリソース データベースにアクセスするためにこの関数を使用する場合、その返り値をどのように使用するのかに気をつけてください。この関数で返される DmOpenRef はオーバレイ データベースへのポインタであり、ベース データベースではありません。次にこのポインタを DmFindResource() に渡すと、オーバレイ リソースへのハンドルが返されます。ベースのみのリソースを探索している場合、それは見つかりません。代わりに、リソースを取得するのに DmGetResource() または DmGet1Resource() を使用してください。これらの関数は両方ともオーバレイ データベースとそれらが関連しているベース データベースの両方を探索します。

DmNumDatabases 関数 ^TOP^

目的

メモリ カードにいくつのデータベースが存在しているか調べます。

宣言されている場所

DataMgr.h

Prototype

UInt16 DmNumDatabases (
	UInt16 cardNo
)

パラメータ

• → cardNo
  • チェックするカードの番号

返り値

見つかったデータベースの数

コメント

このルーチンはカード上のすべてのデータベースのディレクトリを取得する助けになります。ルーチン DmGetDatabase() は、0 から -1 までのインデックスを受け付け、インデックスからデータベース ID を返します。

互換性

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

参照

DmGetDatabase()

DmNumRecords 関数 ^TOP^

データベース中のレコード数を返します。

宣言されている場所

DataMgr.h

Prototype

UInt16 DmNumRecords (
	DmOpenRef dbP
)

パラメータ

• → dbP
  • オープンされたデータベースへの DmOpenRef

返り値

データベース中のレコード数

コメント

deleted ビットがセットされているレコード（つまり、ユーザが削除マークを付けたため、次回の同期時に削除されるレコード）はレコード数に含まれます。これらのレコードを除外したい場合は、DmNumRecordsInCategory() を使用して、カテゴリとして dmAllCategories を渡してください。

参照

DmNumRecordsInCategory(), DmRecordInfo(), DmSetRecordInfo()

DmNumRecordsInCategory 関数 ^TOP^

目的

データベース中の指定されたカテゴリのレコード数を返します。

宣言されている場所

DataMgr.h

Prototype

UInt16 DmNumRecordsInCategory (
	DmOpenRef dbP,
	UInt16 category
)

パラメータ

• → dbP
  • オープンされたデータベースへの DmOpenRef
• → category
  • カテゴリ インデックス

返り値

カテゴリのレコード数

コメント

この関数はデータベース中のすべてのレコードを評価しなくてはならないため、大きなデータベースに対して呼び出した場合は特に、返りが遅くなることがあります。

deleted ビットがセットされたレコードは数に入りませし、ユーザがプライベート レコードに hide または mask を指定している場合はプライベート レコードも数に入りません。

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

DmOpenRef myDB; 
UInt16 record, attr, category, total; 
 
DmRecordInfo(myDB, record, &attr, NULL, NULL); 
category = attr & dmRecAttrCategoryMask; 
total = DmNumRecordsInCategory(myDB, category); 

互換性

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

参照

DmNumRecords(), DmQueryNextInCategory(), DmPositionInCategory(), DmSeekRecordInCategory(), DmMoveCategory()

DmNumResources 関数 ^TOP^

与えられたリソース データベース中のリソース数を返します。

宣言されている場所

DataMgr.h

Prototype

UInt16 DmNumResources (
	DmOpenRef dbP
)

パラメータ

• → dbP
  • オープンされたデータベースへの DmOpenRef

返り値

与えられたデータベース中のリソースの総数。

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

コメント

DmNumResources は、DmOpenRef パラメータで指定されたデータベース中のみのリソース数をカウントします。データベースが関連するオーバレイを持つリソース データベースである場合、この関数はベース データベース中のリソース数を返すだけで、オーバレイ中のリソース数は返しません。

DmOpenDatabase 関数 ^TOP^

目的

データベースをオープンし、そのデータベースへの参照を返します。データベースがリソース データベースの場合、現在のロケールでのそのデータベースのオーバレイもまた、オープンします。

宣言されている場所

DataMgr.h

Prototype

DmOpenRef DmOpenDatabase (
	UInt16 cardNo,
	LocalID dbID,
	UInt16 mode
)

パラメータ

• → cardNo
  • データベースが存在しているカード番号
• → dbID
  • データベースのデータベース ID
• → mode
  • データベースをオープンするモード（オープン モード定数 を参照してください）

返り値

オープンされたデータベースへの DmOpenRef を返します。データベース パラメータが NULL または無効な ID である場合、致命的なエラー メッセージが表示されるかもしれません。他のすべてのエラーでは、この関数は 0 を返し、DmGetLastErr() が失敗理由を示すエラー コードを返します。

コメント

読み込みまたは書き込みを行うデータベースをオープンするためにこの関数を呼び出します。

このルーチンはデータベースの個々のレコードへのアクセスに用いられる DmOpenRef を返します。失敗した場合、0 が返され、エラーが起きた理由は DmGetLastErr() を呼び出すことで調べられます。

リソース データベースを Read-only モードでオープンするためにこのルーチンを使用した場合、現在のロケールでそのデータベースに関連しているオーバレイがあれば、そのオーバレイもまたオープンします。（関数 OmGetCurrentLocale が現在のロケールを返します。）オーバレイは、一般に、アプリケーション、共有ライブラリ、それにパネルをローカライズするのに用いられるリソース データベースです。オーバレイはベース データベースと同じ作者を持ち、'ovly' の型（記号的には omOverlayDBType と名付けられています）を持ち、さらにベース データベースのリソースと同じ ID と型のリソースを保持しています。DmGetResouce() または DmGet1Resource() を使ってデータベースからリソースを取り出そうとした場合、オーバレイが最初に探索されます。オーバレイが与えられた ID のリソースを保持していれば、それが返されます。保持していなければ、ベース データベースのリソースが返されます。

この関数で返される DmOpenRef はベース データベースへのポインタであり、オーバレイ データベースへのポインタではありません。ですから、このポインタをオーバレイを回避する関数 DmFindResource() などに渡す場合には気を付けてください。

ユーザ インターフェイス リソースを持たない「剥ぎ取られた（訳者注: stripped）」ベース データベースが作成される可能性があります。DmOpenDatabase は剥ぎ取られたデータベースに関連するオーバレイが存在する場合にのみ、そのデータベースをオープンします。オーバレイが存在しないか、オーバレイが利ソート データベースと一致しない場合、DmOpenDatabase は NULL を返し、DmGetLastErr() がエラー コード omErrBaseRequiresOverlay を返します。

リソース データベースを書き込み可能モードでオープンする場合、関連のオーバレイはオープンされません。リソース データベースに変更を加える場合、オーバレイにも存在するリソースのどれかに影響を与える変更を加えると、そのオーバレイ データベースは無効になります。このことは、その後にリソース データベースを Read-only モードでオープンしても、Palm OS はそのオーバレイは無効であると見なしてオーバレイがオープンされないことを意味します。

---

TIP: リソース データベースがオーバレイされるのを防ぎたい場合、データベースに ID 0 （sysResIDExtPrefs）の 'xprt' リソース（記号的には sysResTExtPrefs と名付けられています） を含め、その disableOverlays フラグをセットしてください。このリソースは UIResource.r で定義されています。

---

互換性

3.5 New Feature Set を満たす場合にのみ、オーバレイ サポートが利用可能です。

4.0 New Feature Set を満たす場合に DmOpenDatabase が剥ぎ取られたリソース データベースをオープンしようと試みて、そのオーバレイを見つけられないと、システム ロケールがデフォルト ロケールと異なる場合、DmOpenDatabase はデフォルト ロケールと一致するオーバレイを探します。

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

参照

DmCloseDatabase(), DmCreateDatabase(), DmFindDatabase(), DmOpenDatabaseByTypeCreator(), DmDeleteDatabase(), DmOpenDBNoOverlay()

DmOpenDatabaseByTypeCreator 関数 ^TOP^

目的

与えられた型と作者から、最新バージョンのデータベースをオープンします。データベースがリソース データベースの場合、現在のロケールに対応するオーバレイもオープンします。

宣言されている場所

DataMgr.h

Prototype

DmOpenRef DmOpenDatabaseByTypeCreator(
	UInt32 type,
	UInt32 creator,
	UInt16 mode
)

パラメータ

• → type
  • データベースの型
• → creator
  • データベースの作者
• → mode
  • データベースをオープンするモード（オープン モード定数 を参照してください）

返り値

オープンされたデータベースへの DmOpenRef。データベースが見つからなかった場合、この関数は 0 を返し、DmGetLastErr() が失敗理由を示すエラー コードを返します。

コメント

Read-only モードでリソース データベースをオープンするのにこの関数を使用すると、現在のロケールに対応するこのデータベース関連のオーバレイもオープンします。オーバレイとリソース データベースに関する詳細情報は、DmOpenDatabase() を参照してください。

互換性

3.5 New Feature Set を満たす場合にのみ、オーバレイ サポートが利用可能です。それより前のものでは、この関数はリソース データベースをオープンする際に関連のオーバレイを探しません。

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

参照

DmCreateDatabase(), DmOpenDatabase(), DmOpenDatabaseInfo(), DmCloseDatabase(), DmOpenDBNoOverlay()

DmOpenDatabaseInfo 関数 ^TOP^

目的

オープンされたデータベースについての情報を調べます。

宣言されている場所

DataMgr.h

Prototype

Err DmOpenDatabaseInfo (
	DmOpenRef dbP,
	LocalID *dbIDP,
	UInt16 *openCountP,
	UInt16 *modeP,
	UInt16 *cardNoP,
	Boolean *resDBP
)

パラメータ

• → dbP
  • オープンされたデータベースへの DmOpenRef
• ← dbIDP
  • データベースの ID。この情報について調べたくない場合は、このパラメータに NULL を渡してください。
• ← openCountP
  • このデータベースをオープンしたアプリケーションの数。この情報について調べたくない場合は、このパラメータに NULL を渡してください。
• ← modeP
  • データベースをオープンする際のモード（オープン モード定数 を参照してください）。この情報について調べたくない場合は、このパラメータに NULL を渡してください。
• ← cardNoP
  • このデータベースが存在しているカードの番号。この情報について調べたくない場合は、このパラメータに NULL を渡してください。
• ← resDBP
  • true が返された場合、データベースはリソース データベースです。リソース データベースでなければ false が返されます。この情報について調べたくない場合は、このパラメータに NULL を渡してください。

返り値

エラーが無い場合、errNone を返します。

参照

DmDatabaseInfo()

DmOpenDBNoOverlay 関数 ^TOP^

目的

データベースをオープンし、そのデータベースへの参照を返します。

宣言されている場所

DataMgr.h

Prototype

DmOpenRef DmOpenDBNoOverlay (
	UInt16 cardNo,
	LocalID dbID,
	UInt16 mode
)

パラメータ

• → cardNo
  • データベースが存在しているカード番号
• → dbID
  • データベースのデータベース ID
• → mode
  • データベースをオープンする際のモード（オープン モード定数 を参照してください）

返り値

オープンされたデータベースへの DmOpenRef。データベース パラメータが NULL の場合、致命的なエラー メッセージを表示するかもしれません。他のすべてのエラーでは、この関数は 0 を返し、DmGetLastErr() が失敗理由を示すエラー コードを返します。

コメント

読み込みまたは書き込みのためにデータベースをオープンするのにこの関数を呼び出します。オープンする際、そのデータベースに関連するかもしれないオーバレイ データベースを無視します。

このルーチンは、データベースの個々のレコードにアクセスするために使用される DmOpenRef を返します。失敗した場合、0 が返され、エラーが起きた理由を DmGetLastErr() を呼び出すことで調べることができます。

互換性

3.5 New Feature Set を満たす場合にのみ、実装されます。

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

参照

DmCloseDatabase(), DmCreateDatabase(), DmFindDatabase(), DmOpenDatabaseByTypeCreator(), DmDeleteDatabase(), DmOpenDatabase()

DmPositionInCategory 関数 ^TOP^

目的

指定したカテゴリでのレコードの位置を返します。

宣言されている場所

DataMgr.h

Prototype

UInt16 DmPositionInCategory (
	DmOpenRef dbP,
	UInt16 index,
	UInt16 category
)

パラメータ

• → dbP
  • オープンされたデータベースへの DmOpenRef
• → index
  • レコードのインデックス
• → category
  • 探索を行うカテゴリのインデックス

返り値

（0 ベースの）位置を返します。指定したインデックスが範囲外の場合、この関数は 0 を返し、DmGetLastErr() が失敗理由を示すエラー コードを返します。このことは、0 の返り値は呼び出し成功かもしれないし、失敗かもしれないということを意味するということに注意してください。この関数が 0 を返し、DmGetLastErr が errNone を返した場合、返り値はカテゴリの最初のレコードを示していることになります。

コメント

この関数は現在のレコードをすべて評価しなくてはならないため、大きなデータベースに対して呼び出した場合特に、返りが遅くなる可能性があります。deleted ビットがセットされたレコードは無視し、ユーザがプライベート レコードを隠したり、マスクをかけている場合は、プライベート レコードも無視します。

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

レコードが収められているカテゴリを調べるには、DmRecordInfo() を使用してください。

互換性

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

参照

DmQueryNextInCategory(), DmSeekRecordInCategory(), DmMoveCategory()

DmQueryNextInCategory 関数 ^TOP^

目的

指定した読み込み専用（busy ビットがセットされていない）でオープンされているカテゴリ中の次のレコードへのハンドルを返します。

宣言されている場所

DataMgr.h

Prototype

MemHandle DmQueryNextInCategory (
	DmOpenRef dbP,
	UInt16 *indexP,
	UInt16 category
)

パラメータ

• → dbP
  • オープンされたデータベースへの DmOpenRef
• ←→ indexP
  • 既存のレコード（たいてい DmPositionInCategory() で調べます）のインデックス。「次の」レコードが見つかった場合、このインデックスはそのレコードを示すように更新されます。
• → category
  • 問い合わせるカテゴリのインデックス、または、すべてのカテゴリ中の次のレコードを見つける場合には dmAllCategories

返り値

既知のレコードのインデックスの後に続くインデックスを持つレコードへのハンドルを返します。レコードが見つからなかった場合、この関数は NULL を返し、DmGetLastErr() が失敗理由を示すエラー コードを返します。

コメント

この関数は、指定したカテゴリ中のレコードを見つけるために、データベースの探索を *indexP のレコードから開始します。*indexP のレコードが指定したカテゴリに属する場合、そのレコードへのハンドルが返されます。レコードが属さない場合、この関数はカテゴリに属するレコードが見つかるまで探索を続けます。

deleted ビットがセットされたレコードはスキップされ、ユーザがプライベート レコードを隠したり、マスクをかけている場合は、プライベート レコードもスキップされます。

カテゴリ中のインデックスが既知のレコードの次のレコードを見つけるには、この関数を呼び出す前にこのインデックス値を +1 しておきます。以下に例を挙げます。

DmOpenRef myDB; 
UInt16 record, attr, category, pos; 
MemHandle newRecH; 
 
DmRecordInfo(myDB, record, &attr, NULL, NULL); 
category = attr & dmRecAttrCategoryMask; 
pos = DmPositionInCategory(myDB, record,  
  category); 
pos++; 
newRecH = DmQueryNextInCategory(myDB, &pos, category); 

互換性

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

参照

DmNumRecordsInCategory(), DmPositionInCategory(), DmSeekRecordInCategory()

DmQueryRecord 関数 ^TOP^

目的

読み込み専用（busy ビットがセットされていない）レコードへのハンドルを返します。

宣言されている場所

DataMgr.h

Prototype

MemHandle DmQueryRecord (
	DmOpenRef dbP,
	UInt16 index
)

パラメータ

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

返り値

レコード ハンドルを返します。エラーが起きた場合、この関数は NULL を返し、DmGetLastErr() が失敗理由を示すエラー コードを返します。

指定したインデックスが範囲外の場合、いくつかのエラーは致命的なエラー メッセージを表示します。

コメント

与えられたレコードへのハンドルを返します。レコードが見えている（訳者注: インデックスがわかっている？）場合にのみ、このルーチンを使用します。このルーチンは成功すると、もしレコードが Busy 状態であっても、そのレコードへのハンドルを返します。

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

互換性

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

DmQuickSort 関数 ^TOP^

目的

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

宣言されている場所

DataMgr.h

Prototype

Err DmQuickSort (
	DmOpenRef dbP,
	DmComparF *compar,
	Int16 other
)

パラメータ

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

返り値

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

• dmErrReadOnly
• dmErrNotRecordDB

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

コメント

削除されたレコードはどのような順序であっても最後にきます。他のすべてのレコードは、渡された比較関数によってソートされます。

DmQuickSort の実行後でも、等価なデータベース レコードの順序は一貫しません。それゆえ、DmQuickSort に等価な 2 つのレコードを渡した場合、2 つのレコードのソート順序は予測できません。同じデータを持つレコードが予測不可能な順序に並び替えられるのを防ぐには、レコードの固有 ID を比較関数に渡してください（SortRecordInfoType 構造体を使用します）。

DmQuickSort は、制御されない再帰を制限するために、それ自身のスタックを持っています。スタックがいっぱいになると、DmQuickSort は代わりとして「挿入-ソート（訳者注: insertion-sort）」を行います。レコード数が少ない場合も、少ないレコードにクイック ソートを行う際の無視できないオーバヘッドを避けるため、「挿入-ソート」を行います。最後に、レコードがほぼソートされているように見える場合、移動させる必要のあるレコードのみを移動させるために「挿入-ソート」が実行されます。

互換性

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

参照

DmFindSortPositionV10(), DmInsertionSort()

DmRecordInfo 関数 ^TOP^

目的

データベース ヘッダに保存されたレコード情報を調べます。

宣言されている場所

DataMgr.h

Prototype

Err DmRecordInfo (
	DmOpenRef dbP,
	UInt16 index,
	UInt16 *attrP,
	UInt32 *uniqueIDP,
	LocalID *chunkIDP
)

パラメータ

• → dbP
  • オープンされたデータベースへの DmOpenRef
• → index
  • レコードのインデックス
• ← attrP
  • レコードの属性。レコード属性定数 を参照してください。この値について調べたくない場合は、このパラメータに NULL を渡してください。
• ← uniqueIDP
  • レコードの固有 ID。この値について調べたくない場合は、このパラメータに NULL を渡してください。
• ← chunkIDP
  • レコードのローカル ID。この値について調べたくない場合は、このパラメータに NULL を渡してください。

返り値

エラーが無い場合、errNone を返します。指定したレコードが見つからなかった場合、dmErrIndexOutOfRange を返します。いくつかのエラーは、エラー コードを返す代わりに、致命的なエラー メッセージを表示するかもしれません。

互換性

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

参照

DmNumRecords(), {[goto DmSetRecordInfo,DmSetRecordInfo()}}, DmQueryNextInCategory()

DmReleaseRecord 関数 ^TOP^

目的

与えられたレコードの busy ビットをクリアし、Dirty が true であれば dirty ビットをセットします。

宣言されている場所

DataMgr.h

Prototype

Err DmReleaseRecord (
	DmOpenRef dbP,
	UInt16 index,
	Boolean dirty
)

パラメータ

• → dbP
  • オープンされたデータベースへの DmOpenRef
• → index
  • ロックを解除するレコード
• → dirty
  • ture であれば dirty ビットをセットします。

返り値

エラーが無い場合、errNone を返します。指定したインデックスが範囲外の場合、dmErrIndexOutOfRange を返します。いくつかのエラーは、エラー コードを返す代わりに、致命的なエラー メッセージを表示するかもしれません。

コメント

DmGetRecord() で呼び出した、または、DmNewRecord() で作成したレコードへの変更または読み込みが終了したときに、このルーチンを呼び出します。

互換性

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

参照

DmGetRecord()

DmReleaseRecord 関数 ^TOP^

目的

DmGetResource() で取得したリソースを解放します。

宣言されている場所

DataMgr.h

Prototype

Err DmReleaseResource (
	MemHandle resourceH
)

パラメータ

• → resourceH
  • リソースへのハンドル

返り値

エラーが無い場合、errNone を返します。

コメント

アプリケーションにとって必要のなくなったリソースに印を付けます。

参照

DmGet1Resource(), DmGetResource()

DmRemoveRecord 関数 ^TOP^

目的

データベースからレコードを削除し、そのデータ チャンクを処分します。

宣言されている場所

DataMgr.h

Prototype

Err DmRemoveRecord (
	DmOpenRef dbP,
	UInt16 index
)

パラメータ

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

返り値

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

• dmErrReadOnly
• dmErrIndexOutOfRange
• dmErrNotRecordDB
• memErrChunkLocked
• memErrInvalidParam

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

コメント

レコードのデータ チャンクを処分し、データベース ヘッダからレコードのエントリを削除します。DmRemoveRecord は新たに作成され削除されたばかりのレコード、または、決して同期されることのないレコードに対してのみ使用されます。

互換性

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

参照

DmDetachRecord(), DmDeleteRecord(), DmArchiveRecord(), DmNewRecord()

DmRemoveResource 関数 ^TOP^

目的

リソース データベースからリソースを削除します。

宣言されている場所

DataMgr.h

Prototype

Err DmRemoveResource (
	DmOpenRef dbP,
	UInt16 index
)

パラメータ

• → dbP
  • オープンされたデータベースへの DmOpenRef
• → index
  • 削除するリソースのインデックス

返り値

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

• dmErrCorruptDatabase
• dmErrIndexOutOfRange
• dmErrReadOnly
• memErrChunkLocked
• memErrInvalidParam
• memErrNotEnoughSpace

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

コメント

このルーチンは、与えられたりソースを保持しているメモリ マネージャ チャンクを処分し、データベース ヘッダからリソースのエントリを削除します。

参照

DmDetachResource(), DmRemoveResource(), {[goto DmAttachResource,DmAttachResource()|Palm OS Programmer's API Reference/30-1}}

DmRemoveSecretRecords 関数 ^TOP^

目的

すべてのシークレット レコードを削除します。

宣言されている場所

DataMgr.h

Prototype

Err DmRemoveSecretRecords (
	DmOpenRef dbP
)

パラメータ

• → dbP
  • オープンされたデータベースへの DmOpenRef

返り値

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

• dmErrReadOnly
• dmErrNotRecordDB

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

互換性

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

参照

DmRemoveRecord(), DmRecordInfo(), DmSetRecordInfo()

DmResizeRecord 関数 ^TOP^

目的

インデックスで示されたレコードをリサイズします。

宣言されている場所

DataMgr.h

Prototype

MemHandle DmResizeRecord (
	DmOpenRef dbP,
	UInt16 index,
	UInt32 newSize
)

パラメータ

• → dbP
  • オープンされたデータベースへの DmOpenRef
• → index
  • 処理を行うレコード
• → newSize
  • レコードの新しいサイズ

返り値

リサイズされたレコードへのハンドル。レコードをリサイズするのに十分な空き容量がない場合、NULL を返し、DmGetLastErr() が失敗理由を示すエラー コードを返します。

コメント

このルーチンは、現在のヒープに十分な空き容量が無い場合、レコードを同じメモリ カードにある他のヒープに再割り当てします。これが起きるとハンドルは変更されるので、リサイズされたレコードにアクセスする際は返されたハンドルを使うようにしてください。

互換性

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

DmResizeResource 関数 ^TOP^

目的

リソースをリサイズして、新しいハンドルを返します。

宣言されている場所

DataMgr.h

Prototype

MemHandle DmResizeResource (
	MemHandle resourceH,
	UInt32 newSize
)

パラメータ

• → resourceH
  • リソースへのハンドル
• → newSize
  • リソースの新しいサイズ

返り値

新しいサイズのリソースへのハンドルを返します。リソースをリサイズするのに十分な空き容量が無い場合、NULL を返し、DmGetLastErr() が失敗理由を示すエラー コードを返します。いくつかのエラーは、エラー コードを返す代わりに致命的なエラー メッセージを表示するかもしれません。

コメント

リソースをリサイズして、新しいハンドルを返します。リソースのサイズを大きくする場合、このルーチンはリソースを現在のメモリ カード上の他のヒープに再割り当てする可能性があります。

現在のデータ ヒープに十分な空き容量が無いために異なるデータ ヒープに再割り当てされた場合、リソースのハンドルは変更されるかもしれません。

DmResourceInfo ^TOP^

目的

与えられたリソースの情報を調べます。

宣言されている場所

DataMgr.h

Prototype

Err DmResourceInfo (
	DmOpenRef dbP,
	UInt16 index,
	DmResType *resTypeP,
	DmResID *resIDP,
	LocalID *chunkLocalIDP
)

パラメータ

• → dbP
  • オープンされたデータベースへの DmOpenRef
• → index
  • 情報を取得するリソースのインデックス
• ← resTypeP
  • リソースの型。この情報について調べたくない場合は NULL を渡してください。
• ← resIDP
  • リソース ID。この情報について調べたくない場合は NULL を渡してください。
• ← chunkLocalIDP
  • リソース データのメモリ マネージャ ローカル ID。この情報について調べたくない場合は NULL を渡してください。

返り値

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

コメント

dbP がベース リソース データベースへのハンドルの場合、データベースのみからリソースについての情報が返されます。この関数は関連するすべてのオーバレイを無視します。

参照

DmGetResource(), DmGet1Resource(), DmSetResourceInfo(), DmFindResource(), DmFindResourceType()

DmSearchRecord 関数 ^TOP^

目的

オープンされたすべてのデータベースで、渡されたハンドルを持つレコードを探します。

宣言されている場所

DataMgr.h

Prototype

UInt16 DmSearchRecord (
	MemHandle recH,
	DmOpenRef *dbPP
)

パラメータ

• → recH
  • レコード ハンドル
• ← dbPP
  • レコード recH を保持しているデータベース

返り値

レコードのインデックスとデータベース アクセス ポインタを返します。見つからなかった場合、-1 を返し、*dbPP は 0 になります。

参照

DmGetRecord(), DmFindRecordByID(), DmRecordInfo()

DmSearchResource 関数 ^TOP^

目的

オープンされたすべてのリソース データベースで、型と ID から、または、ポインタが non-NULL の場合はポインタからリソースを探します。

宣言されている場所

DataMgr.h

Prototype

UInt16 DmSearchResource (
	DmResType resType,
	DmResID resID,
	MemHandle resH,
	DmOpenRef *dbPP
)

パラメータ

• → resType
  • 探すリソースの型
• → resID
  • 探すリソースの ID
• → resH
  • ロックされたりソースへのポインタ、または、NULL
• ← dbPP
  • 指定したりソースを保持しているリソース データベース

返り値

リソースのインデックスを返します。dbPP には DmOpenRef が収められています。

コメント

このルーチンは、オープンされたすべてのリソース データベースで、型と IDから、または、ポインタからリソースを探すために使用されます。resH が NULL の場合、型と ID からリソースを探します。resH が NULL ではない場合、resType と resID は無視され、リソース ハンドルのインデックスが返されます。返ってきたとき、*dbPP はリソースが見つかったリソース データベースのアクセス ポインタを保持しています。一旦リソースのインデックスがわかれば、DmGetResourceIndex() を呼び出すことで、リソースをロックしてアクセスすることができます。

オープンされたデータベースのいずれかがオーバレイされている場合に、型と ID （訳者注: 原文では ID ではなく creator と書かれていましたが、誤りだと思われます）で探索を行うと、リソースのローカライズされたバージョンを見つけて、返します。この場合、dbPP で返される値は、オーバレイ データベースへのポインタであり、ベース リソース データベースへのポインタではありません。

参照

DmGetResource(), DmFindResourceType(), DmResourceInfo(), DmFindResource()

DmSeekRecordInCategory 関数 ^TOP^

目的

渡されたレコード インデックスからのオフセットに最も近く、渡されたカテゴリと一致するカテゴリを持つレコードのインデックスを返します。（offset パラメータは何レコード分前方または後方ということを示します。）

宣言されている場所

DataMgr.h

Prototype

Err DmSeekRecordInCategory (
	DmOpenRef dbP,
	UInt16 *indexP,
	UInt16 offset,
	Int16 direction,
	UInt16 category
)

パラメータ

• → dbP
  • オープンされたデータベースへの DmOpenRef
• ←→ index
  • 探索を開始するインデックス。返る際は、渡されたインデックスから offset 分ずれた位置にあるレコードのインデックスを保持しています。
• → offset
  • 渡されたレコード インデックスからのオフセット。この値は正の数でなくてはなりません。後方に探索する場合は direction パラメータに dmSeekBackward を渡してください。
• → direction
  • dmSeekForward または dmSeekBackward のどちらかでなくてはなりません。
• → category
  • カテゴリ インデックス

返り値

エラーが無い場合、errNone を返します。エラーが起きた場合、dmErrIndexOutOfRange または dmErrSeekFailed を返します。

コメント

DmSeekRecordInCategory は指定されたカテゴリ中のレコードを探します。探索は index に位置するレコードから開始します。指定されたカテゴリ中にレコードを見つけると、offset パラメータを -1 し、一致するレコードが見つかり、かつ、offset が 0 になるまで探索を続けます。

このため、特定のカテゴリに属する最も近い一致レコードを見つけるために DmSeekRecordInCategory を使用する場合、開始レコードがそのカテゴリに属しているか、属していないかで異なる offset パラメータを渡さなくてはなりません。index に位置するレコードがカテゴリに属する場合、そのカテゴリに属する次のレコードを見つけるためには 1 の offset を渡さなくてはなりません。なぜなら、value 値が変わる前に比較が行われるからです。index に位置するレコードがカテゴリに属さない場合、そのカテゴリに属する次のレコードを見つけるためには 0 の offset を渡さなくてはなりません。この場合、1 の offset だと最初の一致レコードはスキップされてしまいます。

deleted ビットがセットされたレコードは無視され、ユーザがプライベート レコードを隠したり、マスクをかけている場合は、プライベート レコードも無視されます。

参照

DmNumRecordsInCategory(), DmQueryNextInCategory(), DmPositionInCategory(), DmMoveCategory()

DmSet 関数 ^TOP^

目的

レコードのある範囲に特定の値を書き込みます。また、この関数はレコードのポインタの妥当性をチェックし、レコードへの書き込みがそのレコードの領域を超えないことを確実にします。

宣言されている場所

DataMgr.h

Prototype

Err DmSet (
	void *recordP,
	UInt32 offset,
	UInt32 bytes,
	UInt8 value
)

パラメータ

• → recordP
  • ロックされたデータ レコードへのポインタ（チャンク ポインタ）
• → offset
  • 書き込みを開始するレコードのオフセット
• → bytes
  • 書き込むバイト数
• → value
  • 書き込むバイトの値

返り値

エラーがない場合は、errNone を返します。レコード ポインタが無効である場合、または、この関数がレコードを上書きする場合（訳者注: 指定したレコードの領域を超えた書き込みが行われる場合という意味？）、致命的なエラー メッセージが表示されるかもしれません。

コメント

データ マネージャ レコードの書き込みに使用しなくてはなりません。データ ストレージ領域は Write-protect されています。

参照

DmWrite()

DmSetDatabaseInfo 関数 ^TOP^

目的

データベースの情報をセットします。

宣言されている場所

DataMgr.h

Prototype

Err DmSetDatabaseInfo (
	UInt16 cardNo,
	LocalID dbID,
	const 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
  • データベースの新しい名前へのポインタ、または NULL。データベースの名前は、null 終端子を含む、32 バイトまでの ASCII です（dmDBNameLength で指定されています）。データベースの名前には 7 ビット ASCII 文字（0x20 から 0x7E まで）を使用しなくてはなりません。
• → attributesP
  • 新しい属性変数へのポインタ、または NULL。取り得る値のリストは 「データベース属性定数」 を参照してください。
• → versionP
  • 新しいバージョンへのポインタ、または NULL。
• → crDateP
  • 新しい作成日付変数へのポインタ、または NULL。値には 1904年1月1日 からの秒数を指定してください。
• → modDateP
  • 新しい変更日付変数へのポインタ、または NULL。値には 1904年1月1日 からの秒数を指定してください。
• → bckUpDateP
  • 新しいバックアップ日付変数へのポインタ、または NULL。値には 1904年1月1日 からの秒数を指定してください。
• → modNumP
  • 新しい変更数（訳者注: 回数？）変数へのポインタ、または NULL。
• → appInfoIDP
  • 新しい appInfoID 変数へのポインタ、または NULL。
• → sortInfoIDP
  • 新しい sortIDP 変数へのポインタ、または NULL。
• → typeP
  • 新しい type 変数へのポインタ、または NULL。
• → creatorP
  • 新しい creator 変数へのポインタ、または NULL。

返り値

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

• dmErrInvalidDatabaseName
• dmErrAlreadyExists
• dmErrInvalidParam

コメント

appInfoID または sortInfoID を変更するためにこの関数を呼び出すと、古いチャンク ID （があれば）は、孤立したチャンク（注1）というマークを付けられ、新しいチャンク ID が付加されます。そのため、すでに他のデータベースに取り付けた appInfoID または sortInfoID のチャンクを置き換えるべきではありません。

カード番号とデータベース ID を除くデータベースのいずれか、または、すべての情報をセットするためにこのルーチンを呼び出します。このルーチンはすべての non-NULL パラメータを新しい値としてセットします。

参照

DmDatabaseInfo(), DmOpenDatabaseInfo(), DmFindDatabase(), {[goto DmGetNextDatabaseByTypeCreator,DmGetNextDatabaseByTypeCreator()|Palm OS Programmer's API Reference/30-1}}, {[goto TimDateTimeToSeconds,TimDateTimeToSeconds()|Palm OS Programmer's API Reference/57}}

DmSetRecordInfo 関数 ^TOP^

目的

データベース ヘッダに保存されているレコード情報をセットします。

宣言されている場所

DataMgr.h

Prototype

Err DmSetRecordInfo (
	DmOpenRef dbP,
	UInt16 index,
	UInt16 *attrP,
	UInt32 *uniqueIDP
)

パラメータ

• → dbP
  • オープンされたデータベースへの DmOpenRef
• → index
  • レコードのインデックス
• → attrP
  • 新しい属性変数へのポインタ、または NULL。とりえる値のリストは 「レコード属性定数」 を参照してください。
• → uniqueIDP
  • 新しい固有 ID 変数へのポインタ、または NULL

返り値

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

• dmErrReadOnly
• dmErrNotRecordDB
• dmErrIndexOutOfRange

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

コメント

レコードの情報をセットします。このルーチンは dmRecAttrBusy ビットをセットするのに使用することはできません。代わりに、DmGetRecord() がそのビットをセットし、DmReleaseRecord() がクリアします。

通常、レコードの固有 ID は、レコードが DmNewRecord() によって作成されたときに、データ マネージャによって自動的に作成されます。ですから、アプリケーションがその固有 ID を変更することは、通常では、ありません。

互換性

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

参照

DmNumRecords(), DmRecordInfo()

DmSetResource 関数 ^TOP^

目的

データベース ヘッダに保存されたレコード情報をセットします。

宣言されている場所

DataMgr.h

Prototype

Err DmSetRecordInfo (
	DmOpenRef dbP,
	UInt16 index,
	UInt16 *attrP,
	UInt32 *uniqueIDP
)

パラメータ

• → dbP
  • オープンされたデータベースへの DmOpenRef
• → index
  • レコードのインデックス
• → attrP
  • 新しい属性変数へのポインタ、または NULL。取り得る値のリストは、「レコード属性定数」を参照してください。
• → uniqueID
  • 新しい固有 ID 変数へのポインタ、または NULL

返り値

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

• dmErrReadOnly
• dmErrNotRecordDB
• dmErrIndexOutOfRange

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

コメント

レコードの情報をセットします。このルーチンは dmRecAttrBusy ビットをセットするのには使用できません。代わりに、DmGetRecord() でそのビットをセットし、DmReleaseRecord() でクリアします。

通常、レコードの固有 ID は、DmNewRecord() がレコードを作成する際に、自動的に作成されます。そのため、アプリケーションが固有 ID を変更することは、通常は、ありません。

互換性

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

参照

DmNumRecords(), DmRecordInfo()

DmSetResourceInfo 関数 ^TOP^

目的

与えられたリソースの情報をセットします。

宣言されている場所

DataMgr.h

Prototype

Err DmSetResourceInfo (
	DmOpenRef dbP,
	UInt16 index,
	DmResType *resTypeP,
	DmResID *resIDP
)

パラメータ

• → dbP
  • オープンされたデータベースへの DmOpenRef
• → index
  • 情報をセットするリソースのインデックス
• → resTypeP
  • 新しい resType （リソースの型）へのポインタ、または NULL
• → resIDP
  • 新しいリソース ID へのポインタ、または NULL

返り値

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

• dmErrIndexOutOfRange
• dmErrReadOnly

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

コメント

この関数は、指定したりソースのすべての、または一部の情報をセットするために使用します。いずれかの、または、すべての新しい情報ポインタを NULL にすることができます。NULL でない場合、リソースの型と ID は *resTypeP と *resIDP に変更されます。

関数 ^TOP^

目的

文字列を、書き込みのためにオープンされたデータベース中のレコードにコピーします。

宣言されている場所

DataMgr.h

Prototype

Err DmStrCopy (
	void *recordP,
	UInt32 offset,
	const Char *srcP
)

パラメータ

• ←→ recordP
  • データ レコードへのポインタ（チャンク ポインタ）
• → offset
  • 書き込みを開始するレコードでのオフセット
• → srcP
  • null で終了している文字列へのポインタ

返り値

エラーが無い場合、errNone を返します。レコード ポインタが無効の場合、または、関数がレコードを上書きする場合（訳者注: レコードの領域を超えて書き込む場合？）、致命的なエラー メッセージが表示されるかもしれません。

コメント

このルーチンは、データ マネージャ レコードに書き込みをするためのルーチンの 1 つです。データ ストレージ領域は Write-protect されているため、そこに直接書き込むことはできません。このルーチンは、チャンク ポインタの妥当性をチェックし、レコードへの書き込みがそのチャンクの領域を超えないことを保証します。DmStrCopy は与えられた文字列のサイズを調べるのに便利な手段であり、DmStrCopy を呼び出した後には、単に、DmWrite() を呼び出せば済みます。

参照

DmSet()

DmSync 関数 ^TOP^

目的

オープンされたすべてのデータベースの自動バックアップ ファイルを更新します。この関数は非難されます。開発者は、この関数の代わりに、DmSyncDatabase() を使用するべきです。

宣言されている場所

DataMgr.h

Prototype

void DmSync(
	void
)

パラメータ

ありません。

返り値

ありません。

互換性

この関数は、Palm OS Cobalt ではサポートされておらず、Palm OS Garnet では非難されます。開発者は、この関数の代わりに、DmSyncDatabase() を使用するべきです。

DmSyncDatabase 関数 ^TOP^

目的

与えられたオープンされたデータベースの自動バックアップ ファイルを更新します。

宣言されている場所

DataMgr.h

Prototype

Err DmSyncDatabase (
	DmOpenRef dbRef
)

パラメータ

• → dbRef
  • オープンされたデータベースへの DmOpenRef

返り値

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

• dmErrInvalidParam
  • dbRef はオープンされたデータベースへの参照としては無効です。
• dmErrReadOnly
  • dbRef が参照しているデータベースは Read-only モードでオープンされています。データベースは書き込みできるようにオープンされていなくてはなりません。
• dmErrOperationAborted
  • Palm OS デバイスが自動データベース バックアップ機能をサポートしてきません。

コメント

データベースはオープンされたままです。

この関数は、オープンされたデータベースのバックアップをとるのに使用されます。

Palm OS Cobalt バージョン 6.1 を走らせている多くのデバイスは、RAM ストレージ ヒープの中身を何種類かの不揮発性 NAND フラッシュにバックアップします。RAM ストレージ ヒープが何らかの理由で壊れたり、失われた場合、そのストレージ ヒープはバックアップにより修復することができます。バックアップは、いくつかに制限されたイベントによって引き起こされます: データベースがクローズされた、データベースが作成された、DmSetDatabaseInfo() が呼び出された、または、デバイスがスリープ状態に入った（オープンされたデータベースがある場合にのみ）。開発者は、DmSyncDatabase() を呼び出すことで明示的にデータベースのバックアップを引き起こすことができます。

この機能についての詳細情報は、ファイルとデータベース を参照してください。

互換性

与えられたデバイスがこの機能を持っているかどうか調べるには、sysFtrNumDmAutoBackup 特性の存在をチェックしてください。

DmWrite 関数 ^TOP^

目的

指定されたバイト数を書き込みのためにオープンされたデータベース中のレコードにコピーします。

宣言されている場所

DataMgr.h

Prototype

Err DmWrite (
	void *recordP,
	UInt32 offset,
	const void *srcP,
	UInt32 bytes
)

パラメータ

• ←→ dbP
  • ロックされたデータ レコードへのポインタ（チャンク ポインタ）
• → offset
  • レコードでの書き込みを開始するオフセット
• → srcP
  • レコードにコピーするデータへのポインタ
• → bytes
  • 書き込むバイト数

返り値

エラーが無い場合、errNone を返します。レコード ポインタが無効の場合、または、関数がレコードを上書きする場合（訳者注: レコードの領域を超えて書き込む場合？）、致命的なエラー メッセージを表示するかもしれません。

コメント

このルーチンは、データ マネージャ レコードに書き込みをするためのルーチンの 1 つです。データ ストレージ領域は Write-protect されているため、そこに直接書き込むことはできません。このルーチンは、チャンク ポインタの妥当性をチェックし、レコードへの書き込みがそのチャンクの領域を超えないことを保証します。

参照

DmStrCopy(), DmSet()

DmWriteCheck 関数 ^TOP^

目的

書き込みが実際に行われる前に、データ ストレージ チャンクへの書込み操作のパラメータをチェックします。

宣言されている場所

DataMgr.h

Prototype

Err DmWriteCheck (
	void *recordP,
	UInt32 offset,
	UInt32 bytes
)

パラメータ

• → recordP
  • recordH へのロックされたポインタ
• → offset
  • レコードへの書き込みを開始するオフセット
• → bytes
  • 書き込むバイト数

返り値

エラーが無い場合、errNone を返します。エラーが起きた場合、dmErrNotValidRecord または dmErrWriteOutOfBounds を返します。

アプリケーション定義関数 ^TOP^

DmComparF 関数 ^TOP^

目的

データベース中の 2 つのレコードを比較します。

宣言されている場所

DataMgr.h

Prototype

typedef Int16 DmComparF (
	void *rec1,
	void *rec2,
	Int16 other,
	SortRecordInfoPtr rec1SortInfo,
	SortRecordInfoPtr rec2SortInfo,
	MemHandle appInfoH
)

パラメータ

• → rec1
  • 比較する 2 つのレコードへのポインタ
• → other
  • 比較関数に渡すすべての値。このパラメータは、しばしば、ソート方法（昇順または降順）を指示するのに使用されます。
• → rec1SortInfo
  • 2 つのレコードの固有のソート情報を指定する SortRecordInfoType 構造体へのポインタ
• → appInfoH
  • データベースのアプリケーション情報ブロックへのハンドル

返り値

• rec1 = rec の場合、0
• rec1 < rec の場合、< 0
• rec1 > rec の場合、> 0

コメント

この関数は、データベース中のレコードをソートするのに使用されます。この関数は、特に、DmFindSortPosition(), DmInsertionSort() それに DmQuickSort() によって呼び出されます。

互換性

DmComparF のプロトタイプは Palm OS バージョン 2.0 で変更されました。それ以前では、プロトタイプは最初の 3 つのパラメータのみを定義していました。

規則では、バージョン 1.0 のアプリケーションがバージョン 2.0 のデバイスで実行された場合、引数が 3 つから 6 つに変更されたことは問題を引き起こしません。なぜなら、システムは引数が存在しているスタックから引数を引いてくるだけだからです（訳者: ？）。

しかしながら、2.0 以降のデバイスで走らせる場合に、Palm OS 用の Metrowerks CodeWarrior 以外のツールでビルドされた最適化されたアプリケーションのいくつかは、引数の変更の結果として、問題を引き起こすかもしれないということに注意してください。

---

. 「孤立したチャンク」（原文: "orphaned chunk"）は、ストレージ ヒープに割り当てられていますが、参照されることはありません。孤立したチャンクがデータベースにレコード、appInfo ブロック、またはそれに類するものとしてセットされておらず、かつ、アプリケーションがそのトラックを -- おそらく、グローバル変数として -- 保持していばい場合、そのチャンクは失われる可能性があります。アプリケーションが、チャンクが停止するか、クラッシュする前、または、デバイスがリセットされる前に、そのチャンクを解放しておかないと、そのチャンクのストレージは永遠に使用不可能になります: ユーザはデータベースを削除するだけなので、ユーザはそのチャンクを削除することができません。

ソフトリセットがかかると、OS はストレージ ヒープを走査して、孤立したチャンクを見つけるとそれを解放します。しかしながら、たいていのユーザは、リセットをかけるのは稀なので、この機能に頼るべきではありません。

この章のページ 1 へ

---

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