dsmInit

オンライン編集

dsmInit 関数呼び出しは、API セッションを開始し、クライアントを IBM® Storage Protect ストレージに接続します。アプリケーション・クライアントは、一度に 1 つのみ活動セッションをオープンできます。別のパラメーターを使用して別のセッションを開くには、まず dsmTerminate 呼び出しを使用して現行セッションを終了します。

ノード間の照会、リストア、リトリーブを許可するには、-fromnode および -fromowner ストリング・オプションを使用します。詳しくは、複数のノードおよび所有者にまたがるオブジェクトへのアクセスを参照してください。

構文

dsInt16_t  dsmInit  (dsUint32_t        *dsmHandle,
   dsmApiVersion *dsmApiVersionP,
   char          *clientNodeNameP,
   char          *clientOwnerNameP,
   char          *clientPasswordP,
   char          *applicationType,
   char          *configfile,
   char          *options);

パラメーター

dsUint32_t *dsmHandle (O)

この初期化セッションを識別し、それを後続の IBM Storage Protect 呼び出しに関連付けるハンドル。

dsmApiVersion *dsmApiVersionP (I)

アプリケーション・クライアントがこのセッションに使用している API のバージョンを識別するデータ構造を指すポインター。この構造体には、 dsmapitd.h ファイルに設定されている 3 つの定数 (DSM_API_VERSION、DSM_API_RELEASE、および DSM_API_LEVEL) の値が含まれています。アプリケーション・クライアントの API バージョンと、ユーザーのワークステーションにインストールされている API ライブラリーのバージョンとの間に互換性があることを確認するために、 dsmQueryApiVersion に対する以前の呼び出しを実行する必要があります。

char *clientNodeNameP (I)

このパラメーターは、 IBM Storage Protect セッションのノードを指すポインターです。すべてのセッションには、それぞれ、ノード名が関連付けられていなければなりません。ファイル dsmapitd.h 内の定数 DSM_MAX_NODE_LENGTH によって、ノード名に許可される最大サイズが設定されます。

ノード名では、大文字小文字が区別されません。

このパラメーターが両方とも NULL に設定されており、しかも passwordaccess が prompt に設定されている場合、API は、まず渡されたオプション・ストリングからノード名を取得しようとします。ノード名がオプション・ストリングにない場合は、API は構成ファイルまたはオプション・ファイルからノード名を取得しようとします。これらのノード名検索の試行が失敗すると、UNIX または Linux® API はシステム・ホスト名を使用し、他のオペレーティング・システム上の API は DSM_RC_REJECT_ID_UNKNOWN コードを返します。

このパラメーターが NULL で、 dsm.opt ファイル (Windows API の場合) または dsm.sys ファイル (UNIX または Linux API の場合) の passwordaccess オプションが generateに設定されている場合、 API は、 nodename オプション値またはシステム・ホスト名を使用します。

char *clientOwnerNameP (I)

このパラメーターは、 IBM Storage Protect セッションの所有者を指すポインターです。セッションを開始するオペレーティング・システムが複数ユーザー・オペレーティング・システムの場合、NULL の所有者名 (root ユーザー) には、オブジェクトの所有者に関係なく、アプリケーションに所属するオブジェクトをバックアップ、アーカイブ、リストアまたはリトリーブする権限があります。

所有者名では、大文字小文字が区別されます。

このパラメーターが NULL で、 dsm.sys ファイルの passwordaccess オプションが generateに設定されている場合、API はログイン・ユーザー ID を使用します。

注: マルチユーザー・オペレーティング・システムでは、所有者名が、アプリケーションを実行しているセッションのアクティブ・ユーザー ID と一致している必要はありません。

char *clientPasswordP (I)

このパラメーターは、 IBM Storage Protect セッションが実行されるノードのパスワードを指すポインターです。 dsmapitd.h ファイル内の定数 DSM_MAX_VERIFIER_LENGTH によって、このパスワードに許可される最大サイズが設定されます。

このパスワードでは大文字小文字が区別されません。

passwordaccess が generate に設定されている場合、パスワード・ファイルを最初に開始するときを除いて、このパラメーターの値は無視されます。

char *applicationType (I)

このパラメーターは、セッションを実行しているアプリケーションを識別します。アプリケーション・クライアントが値を定義します。

API アプリケーション・クライアントがサーバーとのセッションを開始するたびに、クライアントのアプリケーション・タイプ (またはプラットフォーム) がサーバー上で更新されます。アプリケーション・タイプ値は、サーバーの platform (プラットフォーム) フィールドに入力されるので、オペレーティング・システムの省略語を組み込むことをお勧めします。ストリングの最大長は DSM_MAX_PLATFORM_LENGTH です。

アプリケーション・タイプの現行値を確認するには、 dsmQuerySessInfoを呼び出します。

char *configfile (I)

このパラメーターは、API 構成ファイルの完全修飾名を含む文字ストリングを指します。 API 構成ファイルに指定したオプションによって、クライアント・オプション・ファイルの指定が指定変更されます。オプション・ファイルは、 IBM Storage Protect (クライアントまたは API) のインストール時に定義されます。

char *options (I)

次のユーザー・オプションを含むことができる文字ストリングを指します。

圧縮販売方法
Servername (UNIX または Linux のみ)
TCP/IP サーバー・アドレス
フロム・ノード
フロモwner
EnableClientEncryptKey
パスワード・アクセス

アプリケーション・クライアントは、オプション・リストを使用して、構成ファイルによって設定されたこれらのオプションの値を指定変更できます。

オプションの形式は、次のようになります。

オプション・リストに指定される各オプションはダッシュ (-) で始まりその後に直接オプション・キーワードが続きます。
このキーワードの後に、直接等号 (=) が続き、その後にオプション・パラメーターが続きます。
オプション・パラメーターにブランク・スペースがある場合は、このパラメーターを単一引用符または二重引用符で囲む必要があります。
複数のオプションを指定する場合は、それらのオプションの間にブランクを入れます。

options が NULL の場合、すべてのオプションの値はユーザー・オプション・ファイルまたは API 構成ファイルから取られます。

戻りコード

戻りコード番号を括弧 ( ) 内に示してあります。

表 1. dsmInit の戻りコード
戻りコード	説明
DSM_RC_ABORT_SYSTEM_ERROR (1)	サーバーはシステム・エラーを検出し、クライアントに通知した。
DSM_RC_REJECT_VERIFIER_EXPIRED (52)	パスワードが期限切れになっており、更新の必要がある。
DSM_RC_REJECT_ID_UNKNOWN (53)	ノード名が見つからなかった。
DSM_RC_AUTH_FAILURE (137)	認証できなかった。
DSM_RC_NO_STARTING_DELIMITER (148)	パターンに開始区切り文字がない。
DSM_RC_NEEDED_DIR_DELIMITER (149)	一致ディレクトリーのメタ・ストリングの直前と直後にディレクトリー区切り文字 (...) が必要ですが、ディレクトリー区切り文字が見つかりませんでした。
DSM_RC_NO_PASS_FILE (168)	パスワード・ファイルは使用できません。
DSM_RC_UNMATCHED_QUOTE (177)	オプション・ストリングにアンマッチの引用符がある。
DSM_RC_NLS_CANT_OPEN_TXT (0610)	メッセージ・テキスト・ファイルをオープンできない。
DSM_RC_INVALID_OPT (400)	オプション・ストリング内の項目が無効。
DSM_RC_INVALID_DS_HANDLE (2014)	DSM ハンドルが無効。
DSM_RC_NO_OWNER_REQD (2032)	passwordaccess が generate の場合、所有者パラメーターは NULL でなければならない。
DSM_RC_NO_NODE_REQD (2033)	passwordaccess が generate の場合、ノード・パラメーターは NULL でなければならない。
DSM_RC_WRONG_VERSION (2064)	アプリケーション・クライアントの API バージョンが、 IBM Storage Protect バージョンより高い値になっています。
DSM_RC_PASSWD_TOOLONG (2103)	指定されたパスワードが長すぎる。
DSM_RC_NO_OPT_FILE (2220)	構成ファイルが見つけられなかった。
DSM_RC_INVALID_KEYWORD (2221)	オプション・ストリングに指定されたキーワードが無効。
DSM_RC_PATTERN_TOO_COMPLEX (2222)	包含/除外パターンが複雑すぎて、 IBM Storage Protect が解釈できません。
DSM_RC_NO_CLOSING_BRACKET (2223)	パターン内に右大括弧がありません。
DSM_RC_INVALID_SERVER (2225)	複数ユーザー環境で、システム構成ファイル内にサーバーが見つからなかった。
DSM_RC_NO_HOST_ADDR (2226)	ホストに接続するための情報が不十分。
DSM_RC_MACHINE_SAME (2227)	オプション・ファイル内に定義するノード名は、システム・ホスト名と同じであってはならない。
DSM_RC_NO_API_CONFIGFILE (2228)	構成ファイルをオープンできない。
DSM_RC_NO_INCLEXCL_FILE (2229)	包含/除外ファイルが見つからなかった。
DSM_RC_NO_SYS_OR_INCLEXCL (2230)	dsm.sys ファイルまたは包含/除外ファイルが見つからなかった。