MiscPack Plugin v2.2 for FileMaker Pro

Windows版ファイルメーカー Proのためのプラグイン「MiscPack v2」の説明。

■Introduction

MiscPack v2はFileMaker Pro 7以降の新しいプラグインインターフェイスに対応させたMiscPack v1.xの後継バージョンです。従来のExternal( ) 関数を使った呼び出しに代わって直接関数名を計算式に記述することができ、引数も複数個与えることができるようになりました。バージョンアップにあたりFileMaker Pro 9で同等な機能がすでに組み込まれているような関数を削除し、代わりにいくつかの新しい関数を追加しました。どうしても旧バージョンの関数が必要な場合はMiscPack v1.5を使用してください。MiscPack v1.5でもFileMaker Pro 7以降で使用することができます。MiscPack v2と同時にインストールして使用することも可能です。ライセンスコードは両者で共通ですので、既にライセンスコードを購入されているユーザーはMiscPack v2もすぐに使用することができます。

■Installation

"MiscPack2.fmx" ファイルをファイルメーカーの実行ファイル（FileMaker Pro.exe or FileMaker Pro Advanced.exe）と同じ階層にある「Extensions」フォルダの中にコピーまたは移動してください。通常は「C:\Program Files\FileMaker\FileMaker Pro 9\Extensions」のようなパスにあります。OSがWindows Vistaの場合、管理者権限が必要になることがあります。
To install the plugin, locate the MiscPack2.fmx file into the Extensions folder below the FileMaker executable file. You might also need Administrator privilege on Windows Vista.

■使用方法

計算フィールドやスクリプトステップの計算式で外部関数を呼び出します。関数によってはスクリプト内でしか使用できないものもあるので注意してください。関数の引数にはオプションになっているものがありますが、FileMaker Pro 7ではすべての引数を指定しないと式を保存できないようです。

■ライセンスコードの入力

FileMaker Proの環境設定ダイアログボックスを表示します。「プラグイン」タブに移動し、「MiscPack v2」の行を選択します。ダイアログボックス内の「設定...」ボタンが使用できるようになるのでそれをクリックします。「MiscPack v2」ダイアログボックスが表示されるのでライセンスコードを入力します。（入力欄が表示されない場合すでにライセンスされているので入力の必要はありません。）なお、後述のKMisc_Register関数を使いスクリプト内からライセンスコードを入力することもできます。

■関数レファレンス

KMisc_BitAnd(Integer1; Integer2): 引数の二つの整数のビットAND演算の結果を返します。
e.g.: KMisc_BitAnd(255; 2) -> 2
KMisc_BitAndInv(Integer1; Integer2): 第２引数のビットを反転させたものと第１引数のビットAND演算の結果を返します。第１引数の値から特定のビットをクリアするのに使用します。
e.g.: KMisc_BitAndInv(254; 3) -> 252
KMisc_BitOr(Integer1; Integer2): 引数の二つの整数のビットOR演算の結果を返します。
e.g.: KMisc_BitOr(3; 2) -> 3
KMisc_BitXOr(Integer1; Integer2): 引数の二つの整数の排他的OR演算の結果を返します。
e.g.: KMisc_BitXOr(254; 3) -> 253
KMisc_CreateFolder(NewFolderPath): 引数で指定されるパスに新しいフォルダ（＝ディレクトリ）を作成します。正常に作成された場合数字の0を返します。フォルダを作成するにはユーザーがそのパスに対してフォルダの作成権限を持っていなければならない注意してください。この関数は計算フィールドの定義式では使用することができません。
e.g.: KMisc_CreateFolder("C:\Test") -> 0 if successful.
KMisc_CreateGUID: GUIDを返します。（例："D6EB3A17-778F-415A-B13D-3857B1E423CF"）実行のたびに異なる値を返します。GUIDは常に一意であることが保証されている文字列で、レコードをユニークに識別するのに使用できます。（旧バージョンと異なり戻り値に括弧 { } を含みません。）
KMisc_CreateGUID returns a new GUID every time the function is invoked.
KMisc_DecToHex(Integer): 整数から16進数表記の文字列を求めます。64ビット整数まで扱えます。
e.g.: KMisc_DecToHex(16) -> "10"
KMisc_Gamma(Number {; AlternativeText}}): Γ関数（Gamma function: ガンマ関数）の値を計算します。引数が自然数の場合 Γ(n) = (n - 1)! となって階乗に一致しますが、計算誤差のため結果は完全に整数にはなりません。引数が整数値しかとらない場合は、FileMaker ProのFactorial 関数を使用してください。結果が無限大ないしは計算不能な場合、第２引数の値が返されます。第２引数を省略した場合"∞"が返されます。
KMisc_GCD(Integer1; Integer2): 引数の二つの整数のGCD (Greatest Common Divisor: 最大公約数) を返します。
KMisc_GCD returns the GCD of the two integers.
e.g.: KMisc_GCD(12; 8) -> 4
kMisc_GetFileAttributes( FilePath ): 引数で指定されるファイルまたはフォルダの属性を返します。Windows APIのGetFileAttributesと同じです。指定パスにファイルまたはフォルダが存在しない場合、-1 が返されます
e.g.: KMisc_CreateFolder("C:\Windows") -> 16
KMisc_GetRegistryValue( HKeyNumber ; Path; ValueName): レジストリの値を返します。第１引数が 0, 1, 2 のときそれぞれ HKEY_CLASSES_ROOT, HKEY_CURRENT_USER, HKEY_LOCAL_MACHINE を意味します。第２引数にレジストリパス、第３引数には値の名前を指定します。値のタイプは文字列、DWORDまたはQWORDでなくてはなりません
Active Directoryを導入している場合、第２引数を空文字にして第３引数を "CustomString"にした場合、MiscPackのグループポリシー管理用テンプレートで入力されたカスタム文字列が返されます。この機能を用いればユーザーが使用するコンピューターまたはユーザーアカウントが属するOU（組織単位）に応じて異なる処理をさせることが可能になります。詳細は「Using MiscPack ADM Template」を参照してください。
KMisc_GetRegistryValue returns the registry value specified by the arguments. The values 0, 1 and 2 of the first argument correspond to HKEY_CLASSES_ROOT, HKEY_CURRENT_USER and HKEY_LOCAL_MACHINE respectively.
e.g.: KMisc_GetRegistryValue(1; "SOFTWARE\FileMaker\FileMaker Pro\9.0A"; "Printer") -> some text if it exists KMisc_GetRegistryValue(2; ""; "CustomString") -> the custom string entered in the machine part of the GPO using the MiscPack ADM template. (Effective only in an Active Directory envrionment.)
KMisc_HexToDec(Hexadecimal): KMisc_DecToHexの逆で、16進数表記の文字列（例："C3AF"）から10進数の整数を求めます。
KMisc_Int32ToVersion(Integer): KMisc_VersionToInt32の逆の働きをします。
KMsc-NumToVersionEx works as the inverse of KMisc_VersionToInt32.
KMisc_Int64ToVersion(Integer): KMisc_VersionToInt64の逆の働きをします。
KMsc-NumToVersionEx works as the inverse of KMisc_VersionToInt64.
KMisc_LogGamma(Number {; AlternativeText}}): 対数Γ関数（logarithmic Gamma function: 対数ガンマ関数）の値を計算します。結果が無限大ないしは計算不能な場合、第２引数の値が返されます。第２引数を省略した場合"∞"が返されます。
KMisc_MD5( Text ; UseANSI ): テキストのMD5(Message Digest 5)ハッシュを求めます。テキスト原文と共に保存しておくことでテキストに改ざんが加えられていないかをチェックしたり、パスワードをハッシュとして保存しておくことでパスワードの機密性を向上することができます。（同じパスワードに対して同じハッシュが生成されないようにするために、ユーザーID等を後ろに付加するなどしてからハッシュを生成するとよいでしょう。）MD5ハッシュは本来16バイトですが、この関数はそれを16進数の文字列として表すため常に32文字を返します。旧バージョンではマルチバイト文字列（Shift JISテキスト）からハッシュを作成していましたが、MiscPack v2からデフォルトではUnicodeテキストからハッシュを作成するようになりました。そのため同じ引数を与えても旧バージョンとは結果が異なります。第２引数に「1」を与えるとUnicodeをマルチバイト文字列に変換してからハッシュを作成するため旧バージョンとの互換性を保つことができます。
（第２引数を省略するとクラッシュするバグがありました。バージョン2.1では修正されています。）
KMisc_MD5 calculates and returns the MD5 (Message Digest 5) hash out of the passed text. The hash can be used to check whether the text has been modified inadvertently. Or you can increase password security by saving the hash calculated from the password (plus, say, some unique ID to produce different results for the same text) instead of the original plain-text password. This version 2 of MiscPack utilizes unicode text to produce a hash in contrast to the previous versions which used multi-byte text for hashing. In order to retain compatibility with the previous versions, pass 1 as the second argument of the KMisc_MD5 function. This will cause the function to convert unicode text to multi-byte text before hashing it.
KMisc_MoveFile(OldPath; NewPath): ファイルを移動またはリネームします。第１引数に既存ファイルのフルパスを、第２引数に移動先のパスを指定します。成功した場合0を返します。
KMisc_Register( LicenseCode ): 引数にMiscPackのライセンスコードを渡すことにより未登録版の制限を解除します。通常はファイルメーカー Proの環境設定でライセンスコードを登録しますが、この方式はMiscPackを使用するデータベースを不特定多数のユーザーに配布する場合に有用です。（たとえば、データベースを開くときに自動実行されるスクリプト（ファイルの環境設定で指定します）で、「フィールド設定」コマンドを使って適当なグローバルフィールドにKMisc_Register("xxxxx")の結果を代入するようにします。）
You can pass your license code as the argument of KMisc_Register function to get rid of the limitaion of the unregistered plugin. This is useful when you want to distribute your database to an indefinite number of users. The license code is the same as that of the previous versions of MiscPack.
KMisc_RemoveLeadingZeros( Text ): テキスト中の先行する半角の0を除いたテキストを返します。
e.g.： KMisc_RemoveLeadingZeros("0008406-003") -> "8406-003"
KMisc_RemoveLeadingZeros removes leading zeros from the passed string. It does not remove zeros after the first non-zero letter.
KMisc_SHA1( Text ): テキストのSHA-1 (Secure Hash Algorithm 1) ハッシュを求めます。用途はKMisc_MD5関数のMD5ハッシュの場合と同じです。生成されるハッシュは160ビットであるため、16進数の文字列としては40文字の結果が返されます。常にUnicode文字列からハッシュを生成します。
KMisc_SHA1 calculates a hash from the passed text with the use of the SHA-1 hash algorithm.
KMisc_Version: MiscPackのバージョンを返します。
KMisc_Version returns the version of the plugin itself.
KMisc_VersionToInt32(VersionString): バージョンをあらわす文字列、たとえば"1.0.3"のような文字列を倍長整数に変換します。ピリオドの間の各数値は255以下でなければなりません。値が256以上になる場合はKMisc_VersionToInt64関数を使用してください。この関数を使えば、"1.03.4" と"1.2.4.2" ではどちらのバージョンが新しいかといった比較ができるようになります。文字列中のピリオドまたはコンマの数は3個以内でなければなりません。
†KMsc-VersionToNumが行うバージョン文字列と数値との間の変換は「192.168.0.1」といったIPアドレスの文字表記をを倍長整数に変換する方法とよく似ています。しかしながらIPアドレスの場合は0で始まるオクテットは8進数として解釈されるのに対し、KMisc_VersionToInt32では常に10進数として解釈される点が異なります。
KMisc_VersionToInt32 converts a version string such as "1.2.12.1" to a 32-bit integer. Each of the numbers between the periods (or commas) must be less than 256. Unlike the IP address conversion, the numbers are always treated as decimal integers even when preceded by a 0. (Note that an octet in an IP address representation that begins with 0 is interpreted as an octal number.)
KMisc_VersionToInt64(VersionString): バージョンをあらわす文字列、たとえば"1.2.1200.1"のような文字列を64ビット整数に変換します。ピリオドの間の各数値は65535以下でなければなりません。この関数を使えば、"1.03.2400.1"と"1.2.104.2" ではどちらのバージョンが新しいかといった比較ができるようになります。文字列中のピリオドまたはコンマの数は3個以内でなければなりません。
KMisc_VersionToInt64 converts a version string such as "1.2.1200.1" to a 64-bit integer. Each of the numbers between the periods (or commas) must be less than 65536. This function enables you to compare two version strings such as "1.03.2400.1" and "1.2.104.2" and to tell which one is newer or older. The number of periods or commas in the version string must not exceed three.
KMisc_StringCbLength( Text ): 引数の文字列が実際に占めるバイト数を返します。
FileMaker Proが持つLength()組み込み関数や、フィールドの最大文字数の入力制限にはどれも「文字数」が使われます。一方、SQL Serverのユニコードタイプのフィールド、たとえばnvarchar(50)における50は、文字数ではなく「バイト数÷2」を意味します。そのため、FileMakerをSQL Serverのフロントエンドとして使用している場合、テキストフィールドに4バイトのユニコード文字が含まれていると、FileMakerの最大文字数制限はパスしても、実際にSQL Serverに保存される際に文字数制限でエラーになることがあります。文字列が占めるバイト数を正確に知りたい時にこの関数を使用します。一般に、KMisc_StringCbLength( Text ) <> 2*Length( Text )の場合、Textに4バイトのユニコード文字が１つ以上含まれていることを意味します。
KMisc_StringCbLength returns the actual byte-size occupied by the (unicode) text.
FileMaker always handles the lengh of a string as the number of characters. But since one unicode character may occupy 2 or 4 bytes, the acutal length in bytes can differ for strings of the same 'length'. In contrast, the column sizes used in SQL Server (such as nvarchar(10)) represent 'the length in bytes divided by 2' instead of the 'number' of characters. This function might be useful to resolve this discrepancy.

戻る →旧バージョンの説明
 VectorでMiscPackを購入...(Buy MiscPack at Vector's site)