Tivoli Service Desk 6.0 Developer's Toolkit Script プログラミングの手引き

第 9 章: Tivoli Service Desk (TSD) Script メール・インターフェース

目次に戻る


概要

電子メール (E メール) は、最も急速に成長しているソフトウェア・アプリケーション分野の 1 つです。インターネットおよび組織内イントラネットは両方とも、可視通信エージェントとして電子メールに依存しています。

電子メールによって、次の各種の通信を使用することができます。

蓄積交換機構

電子メール・ネットワークによって提供される利点の 1 つは、蓄積 交換機構です。

蓄積交換機構によって、あるユーザーが 2 番目のユーザーにメッセージを送信することができ、2番目のユーザーが電子メール・ネットワークにログオンしていない場合にも、これが可能となります。

サーバーが最初のユーザーによって送信されたメッセージを保管して、2 番目のユーザーが自身のメールボックスをチェックした時にそれを 2 番目のユーザーに転送します。これによって、2 人のユーザー間で 非同期通信 が可能となります。非同期通信とは、通信操作が時間とは関係なく続行されることを意味します。

通信 API

ほとんどの電子メール・ベンダーは、独自の API (アプリケーション・プログラミング・インターフェース) をそれらの様式で発行していて、これによって、他のベンダーのアプリケーションがそれらのメッセージ交換インフラストラクチャーにインターフェースすることができます。API とは、オペレーティング・システムで低レベル・サービスを要求し実行するために、アプリケーションが使用する 1 組のルーチンです。

API を使用することによって、ソフトウェア・ベンダーは専門化された操作をサポートすることができます。ただし、これは、メッセージ交換機能利点を利用するために、これらの API を使用するアプリケーションは所有権を主張できるシステム内で実行する必要がある、ことを意味します。

注: インターネット・メール・プロトコル (SMTP/POP) は API ではありません。

VIM プロトコル

ベンダー特有のメッセージ交換 API とは異なり、VIM (ベンダー独立メッセージ交換) プロトコルは、ベンダー特有の形式とは無関係のものです。 VIM プロトコルを使用することによって、開発者は任意のプラットフォームで実行するアプリケーションを作成し、そのアプリケーションに組み込まれたメッセージ交換機能をサポートすることができます。

VIM インターフェース・プロトコルは VIM 国際協会によって設計されたもので、これには次のメンバーが加入しています。

MAPI

TSD Script 言語をサポートするもう 1 つの一般的な電子メール・プロトコルは、MAPI (メール・アプリケーション・プログラム・インターフェース) で、Microsoft 製品です。 MAPI は VIM と類似した機能性を公開していて、これによって VIM で行なわれるのと同じメール通信を使用することができます。

TSD Script メール・インターフェースは、VIM と MAPI の両方と通信します。

注: 次のステートメントは MAPI ではサポートされて いません

SMTP

シンプル・メール転送プロトコル (SMTP) は、次のようにして電子メールを伝送する機構をサポートします。

POP3

POP - バージョン 3 (POP3) は、ワークステーションがサーバー・ホスト上のメール・ドロップに動的にアクセスするのを許可します。通常、これは、POP3 サーバー用にサーバーが保有している電子メールをワークステーションで検索できる、ことを意味します。

注: 次のステートメントは SMTP および POP3 ではサポートされていません。

プロトコルによる TSD Script メールの使用法

TSD Script メール・インターフェースは、メール可能なアプリケーションの開発手段をプログラマーに提供します。現在、インターフェースは次の 3 つのプロトコルをサポートしています。

TSD Script メール・インターフェースによって、アプリケーションのビルドに融通性が与えられ、それは下記に要約されています。

TSD Script メール・インターフェースの使用法

TSD Script メール・インターフェースを使用して、次を行なうための TSD Script プログラムを作成することができます。

TSD Script メール・インターフェースの用語

この項では、TSD Script メール・インターフェースの実装を説明するために使用される一部の用語を紹介します。

住所録

住所録 とは、ユーザー情報、アドレス、メーリング・リストなどを保管する場所です。一般に、メール・アドミニストレーターが住所録を管理します。

住所録は、次の 2 つのタイプ、共通私用 があります。

TSD Script メール・インターフェースは、VIM プロトコルの場合にかぎり、共通住所録の読み取り機能をサポートしています。

エンティティー

エンティティー とは、電子メール・メッセージを送信または受信する担当者またはプログラムのことです。

添付ファイル

添付ファイル とは、メッセージに添付できるファイルのことです。添付ファイルは任意の形式にすることができます。 そのファイルを正しく解釈するのは、送信側と受信側の責任となります。

受信箱

受信箱 は、POP3 プロトコルのもとでのメッセージの読み取りおよび作成をサポートする特別なファイルです。これは、 POP3 サーバーから検索されたメッセージを保管し、読み取りまたは非読み取りとマーク付けるメッセージの機構を提供します。

MsgCntnr は SMTP/POP3 の受信箱へのパラメーター・ポインターとしてサービスします。

メール・アドミニストレーター

メール・アドミニストレーター は、メール・サーバーの監督の責任を負う担当者です。この担当者は、ユーザー・アカウントの管理、およびネットワークに保管されるメッセージのボリュームの管理の責任を負うこともあります。

メールボックス

メールボックス は、個々のエンティティーに割り当てられる物理的な場所です。 メールボックスは、メッセージが送達された時にそれを保管します。メールボックスはメッセージ・コンテナーとも呼ばれることもあります。

メッセージ

メッセージ は、メッセージ・システム上を移送し、メッセージ・コンテナーに保管できる任意のオブジェクトです。

メッセージ・クライアント

メッセージ・クライアント は、エンド・ユーザーが次のことを実行できるインターフェースです。

メッセージ・コンテナー

メッセージ・コンテナー は、受信したメッセージの記憶場所です。 これはメールボックスと同義語です。

メッセージ・ヘッダー

メッセージ・ヘッダー は、次に関しての情報が入っているヘッダーです。

メッセージ・アイテム

メッセージ・アイテム は、アイテムのリストです。メッセージ・アイテムは、次の 2 つのタイプのアイテムとすることができます。

メッセージ・タイプ

メッセージ・タイプ は、メッセージの目次の形式および意味を定義します。

注の部分

注の部分 は、メッセージの実際のコンポーネントであり、幾つかのタイプは VIM プロトコルによってサポートされます。

TSD Script メール・インターフェースが現在サポートしているのはテキストの注の部分だけです。

サーバー

サーバー は、次のタスクを処理するメッセージ・システムの部分です。

また、サーバーは "バックエンド" とも呼ばれます。

ユーザー・アドレス

ユーザー・アドレス は、メッセージの宛先のメールボックスの場所です。各メッセージ・システムには、それぞれ固有のアドレス形式があります。

メッセージ・アドレス指定は、メッセージ・アプリケーションの開発で最も複雑な問題の 1 つです。 TSD Script メール・インターフェースは、すべての VIM、MAPI、および SMTP/POP 対応のメッセージ・システムとインターフェースするために開発されました。ただし、メッセージ・アプリケーションまたは機能強化の開発時には、使用している基礎メッセージ・システムの要件を考慮する必要がある、ことに注意してください。

ユーザー ID

ユーザー ID は、そのエンティティーに割り当てられた固有の識別子です。これによって、エンティティーはメール・サーバーにログオンすることができます。

TSD Script メール・レコード構造


次の項は、TSD Script mail.kb ファイルから取り出しました。詳細については、 この章の終わりにある "Mail.kb ファイル" の項を参照してください。

ヘッダー・ファイル

次のタイプが TSD Script メール・インターフェース用に定義されます。ユーザーのメール・システムの実装によっては、一部のタイプが任意指定である場合があります。 インターネット・メール・プロトコルでサポートされるタイプは EntityName および Address だけです。 SMTP/POP では、Address が指定されていなければなりません。 EntityName は任意指定です。

MAILContainer is INTEGER; 
MAILSession is INTEGER; 
MAILRef is REAL; 
MAILName is RECORD; 
  EntityType        : INTEGER; 
  NameType          : INTEGER; 
  AddressBookName   : STRING; 
  EntityName        : STRING; 
  AddressType     : INTEGER; 
  Address         : STRING; 
  CharSet:            : STRING; 
              END; 

上記の例で使用されるタイプの説明は、次にリストされます。

メッセージ・アイテムの指定

次のレコードは、メッセージ・アイテムの定義に使用されます。

MAILItem is RECORD
  Class         : INTEGER; 
  Type                      : STRING; 
  Name            : STRING; 
  BufferType    : INTEGER; 
  BufferData    : STRING; 
              END; 

上記の例で使用されるタイプの説明は、次にリストされます。

メッセージの送信側と受信側の間で専用のアグリーメントがない場合には、他の文字セットより優先して ISO-8859-* シリーズのメンバーを使用することをお奨めします。

メッセージ・ヘッダー

このレコードには、送信されるメッセージのヘッダー情報が入っています。

MAPI では、Subject タイプだけが機能していて、これは、その他のタイプはサポートされていないことを表します。

インターネット・メール・プロトコルがサポートするタイプは SubjectInReplyTo だけです。

Status: 
MAILSendHeader is RECORD 
  Subject                       : STRING; 
  Priority                      : INTEGER; 
  DeliveryReport      : BOOLEAN; 
  NonDeliveryReport   : BOOLEAN; 
  NonDeliveryContents : BOOLEAN; 
  Encrypt             : BOOLEAN;
  Sign                          : BOOLEAN; 
  ExpirationDate      : DATE
  ConversationID                       : LIST of STRING;
  Sensitivity                   : INTEGER; 
  InReplyTo                            : STRING;
  RespondBy                     : DATE; 
  KeyWord             : LIST of STRING; 
  ReturnReceipt                        : BOOLEAN; 
  Save                : BOOLEAN; 
  CharSet:            : STRING;
              END; 

上記の例で使用されるタイプの説明は、次にリストされます。

注: デフォルト設定は NORMAL です。

メッセージの送信側と受信側の間で専用のアグリーメントがない場合には、他の文字セットより優先して ISO-8859-* シリーズのメンバーを使用することをお奨めします。

メッセージ属性

このレコードは、メッセージの送信中のメッセージ・ヘッダー属性を設定します。複数の値のヘッダー属性はリストとして宣言されます。
MAPI では、次のタイプだけがサポートされています。

インターネット・メール・プロトコルは次のタイプをサポートします。

次の例は、メッセージ・ヘッダー属性を示します。

MAILReadHeader is RECORD 
  Type                      : STRING; 
  FromName                  : STRING; 
  FromAddress               : STRING; 
  Subject                       : STRING; 
  MessageDate               : DATE; 
  Priority                      : INTEGER; 
  Sign                          : BOOLEAN; 
  NestingDepth                         : INTEGER; 
  UniqueMsgID                   : STRING; 
  Sensitivity                   : INTEGER; 
  InReplyTo                            : STRING; 
  RespondBy                     : DATE; 
  ReturnReceipt                        : BOOLEAN; 
  ConversationID                       : LIST of STRING; 
  KeyWords                             : LIST of STRING;
  AddressType     : INTEGER; 
  FromCharSet               : STRING;
  SubjectCharSet            : STRING;
              END; 

上記の例のタイプの説明は、次にリストされます。

メッセージの送信側と受信側の間で専用のアグリーメントがない場合には、他の文字セットより優先して ISO-8859-* シリーズのメンバーを使用することをお奨めします。

メッセージの要約

このレコードは、メッセージ・コンテナーでメッセージをスキャン中にメッセージ属性の要約を入手します。

MAPI では、MsgReference タイプだけがサポートされています。

インターネット・メール・プロトコルでは、Priority を除いて、すべてのタイプがサポートされています。

次の例には、要約メッセージ属性が示されています。

MAILMsgSummary is RECORD 
  MsgReference              : MAILRef; 
  Type                      : STRING; 
  UnreadMail                : BOOLEAN; 
  FromName                  : STRING; 
  FromAddress               : STRING; 
  Priority                      : INTEGER; 
  Subject                       : STRING; 
  MessageDate               : DATE; 
  FromCharSet               : STRING;
  SubjectCharSet            : STRING;
              END; 

上記の例で使用されるタイプの説明は、次にリストされます。

メッセージの送信側と受信側の間で専用のアグリーメントがない場合には、他の文字セットより優先して ISO-8859-* シリーズのメンバーを使用することをお奨めします。

レコードのフィルター掛け

このレコードを使用して、メッセージ・スキャン処理中に検索されるメッセージのタイプにフィルターを掛けます。

MAPI および SMTP/POP では、フィルター掛けはサポートされません。

次の例には、フィルター属性が示されています。

MAILFilter is RECORD 
  MessageType                   : STRING; 
  UniqueMsgID                   : STRING; 
  Sent                          : BOOLEAN; 
  Keyword                       : STRING; 
  From                          : STRING; 
  Subject                       : STRING; 
  Date                          : DATE; 
  Priority                      : INTEGER; 
  Sign                          : BOOLEAN; 
  ConversationID                : STRING; 
  Sensitivity                   : INTEGER; 
  RespondBy                     : DATE; 
              END; 

上記の例で使用されるタイプの説明は、次にリストされます。

また、追加のユーザー定義値も受け入れられます。

MAILInfoRec

MAILQueryDefaults 関数で MAILInfoRec レコード構造を使用して、デフォルトのメール・システム値を受信します。
次の例には、MailInfoRec 構造の機能が示されています。

MAILInfoRec is RECORD
  Product:                        STRING;
  SpecVersion:                    INTEGER;
  MaxSubjectLen:                  INTEGER;
  MaxTextLen:                     INTEGER;
  PathNameReq:                    BOOLEAN;
  UserNameReq:                    BOOLEAN;
  PasswdReq:                      BOOLEAN;
  DefPathName:                    STRING;
  DefUserName:                    STRING;
  DefCharSet:                     STRING;
              END;

上記の例で使用されるタイプの説明は、次にリストされます。

住所録

TSD Script によって、住所録のメッセージ受信側の名前をリストすることができます。 (住所録は MAPI または SMTP/POP はサポートされません。) また、TSD Script はネスト された住所録をサポートしていません。

次のレコードは、住所録で項目を検索するために使用されます。

MAILABEntry is RECORD 
  Name            : STRING; 
  AddressType     : INTEGER; 
  Address         : STRING; 
  Comments        : STRING; 
  EntryType       : INTEGER; 
              END; 

注: エンド・ユーザーが住所録を変更することはできません。

上記の例で使用されるタイプの説明は、次にリストされます。

TSD Script メール・インターフェースの実装

この項では、TSD Script の小さいサンプル・プログラムの実装プロセスを介して説明します。このプログラムは、その ID が "BILL" のユーザーから、そのユーザー ID が "JOHN." のユーザーにメール・メッセージを送信します。

TSD Script プログラムへの TSD Script メール・インターフェースの追加

TSD Script プログラムは、TSD Script メール・モジュールを知識ベースの使用セクションに追加することによって、TSD Script メール・インターフェースを使用することができます。
TSD Script メール・モジュールは mail.kb ファイルで検出され、Developer's Toolkit のインストール時にディレクトリーに自動的にインストールされています。この mail.kb ファイルには、レコード構造の定義、定数、および TSD Script メール機能で使用される戻りコードが入っています。

次のコーディング断片には、TSD Script メール・インターフェースをプログラムに追加するための最初のステップが図示されています。

Knowledgebase SENDMAIL; 
USES
    mail; 
PUBLIC 
PROCEDURE SendMailMessage; 
PRIVATE 
ROUTINES 
PROCEDURE SendMailMessage IS 
ACTIONS 
    (*Body of procedure *) 
              END; 

TSD Script メール・インターフェースの初期化

TSD Script メール機能のどれかを呼び出す前に、アプリケーションは、まず初めに MAILInitialize ステートメントを呼び出さなければなりません。この機能は、TSD Script メール・インターフェースで使用されるリソースおよびデータ構造を初期化します。

MAILInitialize ステートメントは、そのパラメーターとして、使用する予定の次のプロトコルを指定しなければなりません。

TSD Script メール・インターフェースを初期化した後、その中のメール・セッションを任意の数だけオープンすることができます。

MAILInitialize(OMI_VIM_INTERFACE)

注: MailInitialize を正常に呼び出した後、 MailTerminate は常に、プログラムの終了の前に呼び出す必要があります。

セッションのオープン

TSD Script メール・インターフェースを初期化した後、MAILOpenSession ステートメントによってセッションをオープンすることができます。 MAILOpenSessionでは、次が必要となります。

次のサンプル・コーディングの場合:

注: OS/2 では、OMISEL_CP850 を使用します。Windows では、OMISEL_CP1252 を使用します。

また、ユーザーは $Unknown を渡し、システムがデフォルトの文字セットを使用することもできます。

注: Microsoft Windows 95/98 ユーザー: 「TSD Script 言語解説書」の MailOpenSession ステートメントの注の項を参照してください。

失敗の状態の場合には、MailGetLastErrorType ステートメントを使用してください。

PROCEDURE SendMailMessage 
VARIABLES 
    sessID:       MailSession; 
    rc:Integer; 
ACTIONS 
    rc := MAILInitialize(OMI_VIM_INTERFACE); 
     IF (rc <> KML_SUCCESS) THEN 
        WinMessageBox($desktop, 'error', $MBOK,
                      'Error in MAILInit. 
                       Error code is ' & rc <); 
        Exit; 
              END; 
     rc := MAILOpenSession('M:\APPS\CCMAIL\CCDATA',
                          'BILL','K2K2', OMISEL_CP850,
                           sessID,OMI_VIM_INTERFACE);
     IF (rc <> KML_SUCCESS) THEN 
        WinMessageBox($desktop, 'error', $MBOK,
                      'Error in MAILInit. 
                       Error code is ' & rc <); 
        MailTerminate(OMI_VIM_INTERFACE);
        Exit; 
              END; 
        (* Send the message *) 
     rc := MAILCloseSession(sessID); 
     IF (rc <> KML_SUCCESS) THEN 
        WinMessageBox($desktop, 'error', $MBOK,
                      'Error in MAILInit. 
                       Error code is ' & rc <); 
        MailTerminate(OMI_VIM_INTERFACE); 
        Exit; 
              END; 
     rc := MAILTerminate(OMI_VIM_INTERFACE); 
              END; 

この時点で、有効なセッションがオープンされます。ただし、メッセージを送信する前に、次のいくつかのタスクを実行しなければなりません。

  1. メッセージ・ヘッダー・レコードを初期化します。
  2. 受信側のリストを初期化します。
  3. 受信側のリストを指定します。
  4. メッセージ・アイテムのリストを指定します。

メッセージ・ヘッダーの初期化

次の例では、MAILSendHeader レコード構造の SubjectPriority のフィールドだけが初期化されます。他のすべてのフィールドは $Unknown のままです。

msgHeader:MAILSendHeader; 
msgHeader.Subject := 'Floor Plan'; 
msgHeader.Priority := OMI_HIGH_PRIORITY; 

受信側のリストの初期化

メッセージを John の名前の受信側に送信したいものとします。宛先リストは、 アドレス "JOHN." の 1 つの要素だけで構成されています。

この例に示されている通り、toListMAILName レコードのリストです。

    toList:       LIST of MAILName; 
toRecipient:MAILName;

受信側の指定

受信側を指定する方法は 2 つあり、アドレスと名前です。

MailName レコードは EntityType と呼ばれるタイプであり、受信側のタイプを示しています。受信側が単一のユーザーまたはプログラムである場合には、EntityType に値 OMISEL_ENTITY を割り当てる必要があります。 メッセージの受信側がグループ (メーリング・リストなど) である場合には、EntityType に値 OMISEL_GROUP を割り当てる必要があります。

名前による受信側の指定

受信側を名前で指定する場合には、MAILName レコードに次のタイプを初期化しなければなりません。

NameType タイプの入力は、メッセージ交換アプリケーションの名前を基本にしています。例:

アドレスによる受信側の指定

受信側をアドレスで指定する場合には、MAILName レコードの AddressTypeAddress のフィールドを初期化しなければなりません。

AddressType フィールドはそのアドレスのタイプを示します。たとえば、 OMISEL_CCMAIL、OMISEL_NOTES、OMISEL_MHS などです。AddressType の 完全なリストは、この章の後方のタイプの説明に示されています。

Address タイプには、AddressType タイプで規定された形式のアドレス文字列が入っています。正しいドレス形式については、ユーザーの VIM 電子メール・ツールのベンダーからの文書を参照してください。

SMTP/POP では、受信側はアドレスで指定されていなければなりません。name フィールドは任意指定です。

注:
MAILReadMessage がメッセージを読み取ると、メッセージの検索中に MAILName レコードの NameAddress の両方の仕様タイプを完了します。

ステートメント msgCntnr は、SMTP/POP3 サポートで使用される時の受信箱を指示します。このコーディング断片に示されている通り、受信側を名前で指定し、デフォルトの住所録を使用します。

toRecipient.EntityType := OMISEL_ENTITY; 
toRecipient.AddressBookName := ''; 
toRecipient.EntityName := 'JOHN'; 
ListInsert(toList, toRecipient, $After); 

注: ステートメント toListccList は同じ方法で宣言することができます。

メッセージ・アイテムのリストの指定

次のタスクでは、メッセージ・アイテム・リストをビルドします。次のアイテムを指定しなければなりません。

このサンプル・プログラムには、次の通りメッセージ・アイテム・リストが入っています。

(* Build the message items list *) 
    (* First item is a note part *) 
Item.Class      := OMISEL_NOTE_PART; 
    Item.Type       := OMI_TEXT; 
    Item.Name       := 'Title for the 
                       note part'; 
    Item.BufferType := OMI_ACTUAL_DATA; 
    Item.BufferData := 'Hi John. I have' & 
                       'enclosed the floor' &
                       'plan layout in the' & 
                       'file attachment. ';
    Name.Address    := 'JOHN/ACME CORPORATION'
    ListInsert(Items, Item, $After);
   (* Second item is a file attachment *)
Item.Class      := OMISEL_ATTACH;
    Item.Name       := 'image.pcx';
    Item.BufferType := OMI_FILE_DATA;
    Item.BufferData := 'D:\TMP\PAPANIM.PCX';
    ListInsert(Items, Item, $After);

注: Name.Address の SMTP/POP の例は次の通りです。

Name.Address := 'john@acme.com'

SendMailMessage プロシージャーの作成

SendMailMessage プロシージャーは次のように作成することができます。

PROCEDURE SendMailMessage IS 
VARIABLES 
    header:       MAILSendHeader; 
    Items:        LIST of MAILItem; 
    Item:         MAILItem; 
    name:         MAILName; 
    toList:       LIST of MAILName; 
  rc              :INTEGER; 
    sessID:       MailSession; 
ACTIONS 
    rc := MAILInitialize(OMI_VIM_INTERFACE); 
    IF (rc < 1) THEN 
        WinMessageBox($desktop, 'error', $MBOK,
                      'Error in MAILInit. 
                       Error code is ' & rc <); 
        Exit; 
              END; 
    rc := MAILOpenSession('M:\APPS\CCMAIL\CCDATA', 
                          'BILL','K2K2', 
                     OMISEL_CP850, sessID,
OMI_VIM_INTERFACE); 
    IF (rc < 1) THEN 
        WinMessageBox($desktop, 'error', $MBOK,
                      'Error in MAILInit. 
                       Error code is ' & rc <); 
        MailTerminate(OMI_VIM_INTERFACE); 
        Exit; 
                  END; 
    (* Send the message *) 
    (* Set the header record *) 
    header.subject := 'Floor Plan'; 
    header.Priority := OMI_HIGH_PRIORITY; 
    (* Build the message items list *) 
    (* First item is a note part *) 
    Item.Class      := OMISEL_NOTE_PART; 
    Item.Type       := OMI_TEXT; 
    Item.Name       := 'Title for
                      the note part'; 
    Item.BufferType := OMI_ACTUAL_DATA; 
    Item.BufferData := 'Hi John. I have enclosed'& 
                       'the floor plan layout in'& 
                       'the file attachment. '; 
    ListInsert(Items, Item, $After); 
    (* Second item is a file attachment *) 
    Item.Class      := OMISEL_ATTACH; 
    Item.Name       := 'image.pcx'; 
    Item.BufferType := OMI_FILE_DATA; 
    Item.BufferData := 'D:\TMP\PAPANIM.PCX'; 
    ListInsert(Items, Item, $After); 
    (* Specify the recipient *) 
    name.EntityType := OMISEL_ENTITY; 
    name.AddressBookName := ''; 
    name.EntityName := 'JOHN' 
    ListInsert(toList, name, $After); 
    rc := MailSendMessage(SESSID, OMI_MAIL, header,
                          toList, $UNKNOWN,$UNKNOWN,
                           Items);
    IF (rc < 1) THEN 
        WinMessageBox($desktop, 'error', $MBOK,
                      'Error in MAILInit. 
                       Error code is ' & rc <); 
        ELSE ('Mail sent successfully'); 
              END; 
    rc := MAILCloseSession(sessID); 
    IF (rc < 1) THEN 
        WinMessageBox($desktop, 'error', $MBOK,
                      'Error in MAILInit. 
                       Error code is ' & r <); 
        MailTerminate(OMI_VIM_INTERFACE); 
        Exit; 
              END; 
    rc := MAILTerminate(OMI_VIM_INTERFACE); 
              END; 

メッセージ・コンテナーのメッセージの読み取り

TSD Script メール・インターフェースは、メッセージ・コンテナーのメッセージを読み取ることができます。メッセージの読み取りには、次の 2 つのステップがあります。

注: SMTP/POP3 では、フィルターはサポートされていません。

次の例は、メールを受信するプログラムを示しています。

KNOWLEDGEBASE mailrecv;
 
USES mail; 

ROUTINES 

PROCEDURE ReadMail; 

PRIVATE
ROUTINES 

PROCEDURE ReadMail IS
VARIABLES
  sess :MAILSession;
  msgContainer :MAILContainer;
  toList :LIST OF MAILName;

  outfile         :FILE;
  numMessages     :INTEGER;
  msgSummary      :LIST OF MAILMsgSummary;
  summRec         :MAILMsgSummary;
  msgRef          :MAILRef;
  msgHeader       :MAILReadHeader;
  msgItems        :LIST of MAILItem;
  ccList, bccList :LIST of MAILName;
  nestedMsg       :BOOLEAN;
  reply           :string;
  rc              :INTEGER;
ACTIONS
   rc:=MAILInitialize(OMI_SMTP_POP_INTERFACE);
              IF rc < 1 THEN
    EXIT;
              END;
   rc:=MAILOpenSession('mozart.softart.com',
                      'Mr Totstuser@domain name',
                       'pass',$UNKNOWN,
                       sess,OMI_SMTP_POP_INTERFACE);
              IF rc < 1 THEN
             WinMessageBox($Desktop,'Error',$MBIconError,
                'Open session failed: '&rc);
 MAILTerminate(OMI_SMTP_POP_INTERFACE);
    EXIT;
              END;
 rc:=MAILOpenMessageContainer (sess,
                              'c:\mail\inbox.idx',
                               msgContainer);
              IF rc < 1 THEN
             WinMessageBox($Desktop,'Error',$MBIconError,
                 'Open container failed: '&rc);
 MAILCloseSession(sess);
 MAILTerminate(OMI_SMTP_POP_INTERFACE);
    EXIT;
              END;
 rc:= MAILScanMessages(msgContainer, OMI_UNREADONLY,
                      $Unknown, TRUE, numMessages,
                       msgSummary);
              IF rc < 1 THEN
     WinMessageBox($Desktop,'Error',$MBOK,
                   'Scan failed: '&rc);
 MAILCloseMessageContainer(msgContainer);
 MAILCloseSession(sess);
 MAILTerminate(OMI_SMTP_POP_INTERFACE);
    EXIT; 
              END;
 REPEAT
    IF numMessages > 0 THEN
         rc:=FOpen(outfile, 'mailtest.log', $CREATE);
              IF rc < 1 THEN 
             WinMessageBox($Desktop,'Error',$MBIconError,
                          'File Open failed: '&rc);
                EXITLoop;
ELSE
             FWriteLn(outfile, 'Number Read: ' & 
                      numMessages);
            FOR msgSummary DO
                 summRec := msgSummary[$Current];
                 FWriteLn(outfile, 'Message Type: ' &
                          summRec.Type);
                 FWriteLn(outfile, 'Unread Mail: ' &
                          summRec.UnreadMail);
                 FWriteLn(outfile, 'FromName: ' &
                          summRec.FromName);
                 FWriteLn(outfile, 'FromAddress ' &
                          summRec.FromAddress);
                 FWriteLn(outfile, 'Priority: ' &
                          summRec.Priority);
                 FWriteLn(outfile, 'Subject: ' &
                          summRec.Subject);
                 msgRef := summRec.MSGReference;
                rc := MAILReadMessage(msgContainer,msgRef,
                                      0,msgHeader,
                                     msgItems,toList,
                                     ccList,bccList,
                                      nestedMsg);
              IF rc < 1 THEN
                WinMessageBox($Desktop,'Error',
                              $MBIconError,
                              'ReadMessage failed: '&rc);
          FClose(outfile); 
                EXITLoop; 
               ELSE
                    MAILReleaseMessageReference
                        (msgContainer, msgSummary
                         [$Current].msgReference);
              FOR tolist DO
                 FWriteLn(outfile,'To Name: ' &
                          toList[$current].EntityName);
                 FWriteLn(outfile,'To Address: ' &
                          toList[$current].address);
              END;
              FWriteLn(outfile, ' ***Message Items**** ');
                 FOR msgItems DO
            FWriteLn(outfile,msgItems
                     [$current].Type);
            FWriteLn(outfile,msgItems
                     [$current].Name);
            FWriteLn(outfile,msgItems
                     [$current].BufferData);
              END;
            FWriteLn(outfile, 
                    '*********************************
                     ******************* ');
            END; (*End of Else*)
          END; (*End of For LOOP*)
          FClose(outfile); 
       END;(*End of Else*)
    END;(*End of IF*)
 UNTIL TRUE;
 MAILCloseMessageContainer(msgContainer);
 MAILCloseSession(sess);
 MAILTerminate(OMI_SMTP_POP_INTERFACE);
 WinMessageBox($Desktop,'Program Complete',$MBOK,
              'Execution is complete. 
               Check for output.');
              END;

TSD Script メール・セッションのクローズ

TSD Script の複数のメール・セッションを同時にオープンさせることができます。

TSD Script Mail メール・セッションをクローズするには、MAILCloseSession ステートメントを呼び出してください。これは、TSD Script メール・セッションと関連付けられたシステム・リソースを解放します。

TSD Script メール・インターフェースの終了

TSD Script メール・インターフェースを終了可能にするには、まず初めに、すべてのオープン TSD Script メール・セッションをクローズしなければなりません。その後で、MAILTerminate ステートメントを呼び出さなければなりません。

TSD Script メール戻りコード

この項では、TSD Script メール・インターフェース・ステートメントから出されることがあるエラー・コードをリストします。エラーは、VIM または MAPI 層、あるいは TSD Script 層のいずれかで、メッセージ処理中の幾つかの時点で起こる可能性があります。次の表は、これらの層のそれぞれで起こりうるエラー・コードを説明しています。

注: すべての TSD Script メール・インターフェースの呼び出しでは、その機能が正常に実行された場合に値 1 が戻されます。そうでない場合には、負の値が戻されます。

VIM 層で生成されるエラー・コード

下記のリストでは、VIM 層で生成されることがあるエラー・コードについて説明されています。

エラー コメント
OMISTS_FAILURE -1 一般の障害
OMISTS_FATAL -2 致命的エラーが起こりました。その問題が訂正されるまで、
それ以上システムを使用することはできません。
OMISTS_ALL_PARAMS_REQUIRED -3 MAILOpenSession は、パス、名前、およびパスワードが
基礎となるメッセージ・システムで必要である時に、このメッセージを戻します。
OMISTS_ATTACHMENT_NOT_FOUND -4 (MAILSendMessage で)
指定された添付ファイルが見つかりません。
OMISTS_BAD_PARAM -5 必須パラメーターが不明であるか、パラメーターが範囲外であるか、
あるいはパラメーターが無効です。
OMISTS_BUF_TOO_SMALL -6 TSD Script メール・インターフェースは、バッファーを使用して
メッセージ・システムから値を検索します。この戻りコードは、使用されたバッファーが小さすぎて
戻された値が適合しないことを表します。
OMISTS_CONV_NOT_SUPPORTED -7 指定された変換は、この実装ではサポートされていません。
OMISTS_INSUFFICIENT_MEMORY -8 使用可能メモリーが不足しているために、
内部操作に失敗しました。
OMISTS_INVALID_CONFIGURATION -9 無効な基本構成が検出されました。
OMISTS_INVALID_OBJECT
-10 オブジェクト・ハンドル (MAILSessionMAILContainerMAILRef) が不明または無効です。
たとえば、メール・メッセージが必要な機能に対して、非メール・メッセージに対するハンドルが
渡されていない可能性があります。
OMISTS_INVALID_PASSWORD -11 MAILOpenSession に不良パスワードが渡されました。
OMISTS_INVALID_SELECTOR -12 このコンテキストでは認識されないセレクター (OMISEL_*) が、
ステートメントに渡されました。
OMISTS_INVALID_SIGNATURE -13 不良シグニチャーが MAILVerifySignature
渡されたか、あるいはメッセージの和解が得られました。
OMISTS_NAME_EXISTS -14 この戻りコードは VIM では使用されません。
OMISTS_NAME_NOT_FOUND -15 MAILSendMessage は受信側の名前を即時に妥当性検査しましたが、その名前は指定された住所録で検出されていません。 (住所録が指定されなかった場合には、
デフォルトの住所録が使用されます。)
OMISTS_NOT_SUPPORTED -16 呼び出された機能は、この実装ではサポートされていません。
OMISTS_NO_COMMON_CERTIFICATES -17 MAILVerifyMessage シグニチャーは、受信側と送信側の間で共通な認証がないことを報告しています。
OMISTS_NO_DEFAULT -18 MAILGetEntityName は、いくつかのアクティブ・セッションの中から選択することができません。一部
の実装では、エラー・コードを戻すのではなく、最大時間アクティブであった
セッションの名前が戻されることがあります。
OMISTS_NO_MATCH -19 一致するものが検索されていません。
OMISTS_NO_SIGNATURE -20 MAILVerifyMessage シグニチャーは、
指定されたメッセージにシグニチャーがないことを報告しています。
OMISTS_NO_SUCH_ATTRIBUTE -21 呼び出された属性は使用されません。
OMISTS_OPEN_FAILURE -22 ファイルのオープンまたは作成中に、プラットフォーム従属エラーが起こりました。
OMISTS_PASS_REQUIRED -23 MAILOpenSession は、この実装でセッションを
オープンするにはパスワードが必要であることを報告しています。
OMISTS_READ_FAILURE -24 ファイルのオープンまたは作成中に、プラットフォーム従属エラーが起こりました。
OMISTS_UNSUP_TYPE -25 MAILSendMessage または MAILSendDerived Message は VIM_MAIL 以外のメッセージ・タイプで渡されましたが、
これはこの実装ではサポートされていません。あるいは、MAILReadMessage がこの
タイプのアイテムの読み取りをサポートしていません。
OMISTS_UNSUP_VERSION -26 TSD Script メール・インターフェースと
基礎となる VIM インターフェースのミスマッチ。
OMISTS_WRITE_FAILURE -27 ファイルの書き込み中に、プラットフォーム従属エラーが起こりました。

MAPI 層によって生成されるエラー・コード

下記のリストでは、MAPI 層で生成されることがあるエラー・コードについて説明されています。

エラー コメント
MAPI_USER_ABORT -201 ユーザーが処理を取り消しました。この機能は完了していません。
MAPI_E_FAILURE

-202 指定されない 1 つまたは複数のエラーが起こりました。この機能は
完了していません。
MAPI_E_LOGIN_ FAILURE

-203 ユーザーは正常にログオンされませんでした。セッション識別子は
戻されません。
MAPI_E_DISK_FULL
-204 ディスクが満杯です。
MAPI_E_INSUFFICIENT
_MEMORY

-205 メモリーが不十分で、先に進めません。この機能は
完了していません。
MAPI_E_TOO_MANY_SESSIONS

-208 一度にオープンするセッションが多過ぎます。
MAPI_E_ TOO_MANY_FILES -209 添付ファイルが多過ぎます。
MAPI_E_ TOO_MANY_RECIPIENTS -210 指定されたメッセージ受信側が多過ぎます。
MAPI_E_ATTACHMENT_NOT
_FOUND
-211 メッセージに添付する必要がある
1 つまたは複数のファイルを検出できません。
MAPI_E_ ATTACHMENT_OPEN_FAILURE -212 メッセージに添付する必要がある
1 つまたは複数のファイルをオープンできません。
MAPI_E_ ATTACHMENT_WRITE_FAILURE -213 添付を一時ファイルに書き込みできません。
ディレクトリー権限を検査してください。
MAPI_E_UNKNOWN_RECIPIENT -214 受信側が宛先リストで検索されません。
MAPI_E_BAD_RECIPTYPE -215 受信側タイプが指定されていないか、あるいは無効です。
MAPI_E_INVALID_MESSAGE -217 メッセージ参照番号が無効です。
MAPI_E_TEXT_TOO_LARGE -218 メッセージ・テキストが長すぎます。
MAPI_E_INVALID_SESSION -219 セッション識別子が無効です。
MAPI_E_TYPE_NOT
_SUPPORTED
-220 1 つまたは複数のタイプがこの実装でサポートされていません。
MAPI_E_AMBIGUOUS
_RECIPIENT
-221 1 つまたは複数の受信側があいまいです。
MAPI_E_INVALID_RECIPS -225 1 つまたは複数の受信側が無効です。
MAPI_E_NOT_SUPPORTED -226 この機能が基礎の実装でサポートされていません。


SMTP で生成されるエラー・コード

下記のテーブルには、SMTP で生成されることがあるエラー・コードがリストされています。

エラー コメント
OMI_ERR_SMTP_OPENSESSION
_FAILURE
-3000 MAILOpenSession(..) 中のすべてのデータの初期化に失敗しました。
OMI_ERR_SMTP_MAIL
_FAILURE
-3001 SMTP サーバーへの mail コマンドの送信に失敗しました。
OMI_ERR_SMTP_CLOSE
_FAILURE
-3002 SMTP サーバーへの close コマンドの送信に失敗しました。
OMI_ERR_SMTP_VERIFY
_FAILURE
-3003 SMTP サーバーは宛先リストのユーザーを検査することができません。
OMI_ERR_ATTACH_FILE
_ERROR
-3004 添付として指定されたファイルが存在しないか、あるいは
ファイル名が間違った形式になっています。
OMI_ERR_SMTP_OPEN_SERVER
_FAILURE
-3005 SMTP サーバーとの添付のオープンに失敗しました。
OMI_ERR_POP_OPEN_FAILURE -3006 POP サーバーとの添付のオープンに失敗しました。
OMI_ERR_INVALID_PASSWORD -3007 パスワードの検査に失敗しました。
OMI_ERR_POP_STAT_FAILURE -3008 POP サーバーへの stat コマンドの送信に失敗しました。
OMI_ERR_POP_RETR_FAILURE -3009 POP サーバーへの retr コマンドの送信に失敗しました。
OMI_ERR_POP_DELE_FAILURE -3010 POP サーバーへの delete コマンドの送信に失敗しました。
OMI_ERR_POP_QUIT_FAILURE -3011 POP サーバーへの quit コマンドの送信に失敗しました。
OMI_ERR_SOCKET_FAILURE -3012 ソケット呼び出しで失敗しました。
OMI_ERR_PARSE_MESSAGE
_FAILURE
-3013 解析メッセージの呼び出しで失敗しました。
OMI_ERR_INVALID_FILE -3014 ファイル・サイズが 0 です。
OMI_ERR_SERVICE_NOT
_AVAILABLE
-3421 シャットダウンする必要があることをサービスが知っている場合には、これは、どれかの SMTP コマンドに対する応答である場合があります。
OMI_ERR_MAILBOX_BUSY -3450 メールボックスが使用中です。
OMI_ERR_LOCAL_ERROR_IN
_PROCESSING
-3451 処理中のローカル・エラーのために、要求されたアクションが打ち切られました。
OMI_ERR_INSUFFCIENT
_SYSTEM_STORAGE
-3452 システム記憶域が十分でないために、要求されたアクションが打ち切られました。
OMI_ERR_SYNTAX_ERROR -3500 構文エラーで、コマンドが認識されていません。
OMI_ERR_SYNTAX_ERROR_IN
_PARAMETER
-3501 パラメーターまたは引き数の構文エラー。
OMI_ERR_COMMAND_NOT
_IMPLEMENTED
-3502 コマンドが実装されていません。
OMI_ERR_SEQUENCE_ERROR -3503 コマンド順序が不良。
OMI_ERR_PARAMETER_NOT
_IMPLEMENTED
-3504 コマンド・パラメーターが実装されていません。
OMI_ERR_MAILBOX
_UNAVAILABLE
-3550 要求されたアクションが取られない; メールボックスが使用不可。
OMI_ERR_USER_NOT_LOCAL -3551 ユーザーがローカルでない; <パスの転送> をやり直してください。
OMI_ERR_EXCEEDED
_STORAGE_ALLOCATION
-3552 要求されたメール・アクションの中断: 記憶割り振りを超えました。
OMI_ERR_MAILBOX_NAME
_NOT_ALLOWED
-3553 メールボックス名が不許可
OMI_ERR_TRANSACTION
_FAILED
-3554 トランザクションの失敗
OMI_ERR_SOCKET_ERROR -3099 ソケット通信エラー

TSD Script で生成されるエラー・コード

下記のリストでは、TSD Script で生成されることがあるエラー・コードについて説明されています。

エラー コメント
OMI_ERR_INVALID_BUFFER
_TYPE
-2000 メール・アイテム・レコードに無効なバッファー・タイプが
指定されました。
OMI_ERR_INVALID_BUFFER
_DATA
-2001 無効なバッファー・データ
OMI_ERR_NO_MEMORY -2002 システム・メモリー・リソースが使い尽くされました。
OMI_ERR_INVALID_FILENAME -2003 無効なファイル名
OMI_ERR_NO_TOLIST -2004 "To" リストが指定されていません。
OMI_ERR_BAD_PARAM -2005 無効なパラメーターが指定されました。
OMI_ERR_NO_NESTED
_MESSAGE
-2006 要求されたレベルでネストされたメッセージが検出されていません。
OMI_ERR_TOO_MANY_FILE
_NAMES
-2007 指定されたファイル名が多過ぎます。
OMI_ERR_UNSUPPORTED
_PROTOCOL
-2008 プロトコル引き数の値が無効であるか、
あるいはこのプロトコルがサポートされていません。
OMI_ERR_UNSUPPORTED
_FEATURE
-2009 この機能はこの実装では使用できません。
OMI_ERR_NOT_IMPLEMENTED -2010 この機能が実装されていません。
OMI_ERR_UNKNOWN_ITEM
_CLASS
-2011 アイテムのクラスが不明です。
OMI_ERR_INVALID_NOTE_PART -2012 メッセージの注の部分が無効です。
OMI_ERR_MAPI_FAILURE -2013 MAPI インターフェースのプログラミングでエラーが検出されました。
OMI_ERR_NOT_INITIALISED -2014 メール・インターフェースが初期化されていません。 MailInitialize は、TSD Script メール・インターフェースを使用する前に呼び出さなければなりません。
OMI_ERR_COULD_NOT_LOAD
_DLL
-2015 TSD Script メールが MAPI または VIM DLL のいずれかをロードできません。
KML_ERR_UNKNOWN_ITEM
_CLASS
-5000 不明なアイテムのクラスが指定されました。
KML_ERR_UNKNOWN_ITEM
_TYPE
-5001 不明なアイテム・タイプが指定されました。
KML_ERR_UNKNOWN_BUFFER_TYPE -5002 不明なバッファー・タイプが指定されました。
KML_ERR_UNKNOWN_BUFFER_DATA -5003 不明なバッファー・データが指定されました。

TSD Script メールの定数

有効な TSD Script メールの定数は次の通りです。

定数
OMISEL_ADDRESS 1
OMISEL_ATTACH 6
OMISEL_BCC 9
OMISEL_CC 10
OMISEL_CCMAIL 11
OMISEL_CLASS 13
OMISEL_CP1252 16
OMISEL_CP437 17
OMISEL_CP850 18
OMISEL_ENTITY 26
OMISEL_FORWARD 33
OMISEL_GROUP 38
OMISEL_LMBCS 44
OMISEL_MHS 49
OMISEL_NOT_SUPPORTED 61
OMISEL_NOTE_PART 62
OMISEL_NOTES 63
OMISEL_REPLY 77
OMISEL_TO 97
OMISEL_UNICODE 99
OMISEL_UNKNOWN_RECIP_TYPE 101
OMISEL_UNWRAPPED_TEXT 105
OMISEL_X400 107
OMISEL_X500 108
OMI_MAIL 'VIM_MAIL'
OMI_RTF 'VIM_RTF'
OMI_DLR 'VIM_DLR'
OMI_NDLR 'VIM_NDLR'
OMI_PRIVATE 'VIM_PRIVATE'
OMI_PUBLIC 'VIM_PUBLIC'
OMI_RTRC 'VIM_RTRC'
OMI_TEXT 'VIM_TEXT'
OMI_UNWRAPPED_TEXT 'VIM_UNWRAPPED
_TEXT'
OMI_LOW_PRIORITY 0
OMI_NORMAL_PRIORITY 1
OMI_HIGH_PRIORITY 2
OMI_HISTORY 1
OMI_INHERIT_CONTENTS 2
OMI_ALL_RECIPIENTS 4
OMI_UNREADONLY 2
OMI_NORMAL_SENS 0
OMI_PRIVATE_SENS 1
OMI_PERSONAL_SENS 2
OMI_CO_CONFID_SENS 3
OMI_APP_DEF_SENS 16384
OMI_FILE_DATA 1
OMI_ACTUAL_DATA 2
OMI_REVERSE_SCAN 1
OMI_UNREAD_ONLY 2
OMI_SMTP_POP_INTERFACE 3

Mail.kb ファイル

TSD Script メール・ファイル

完全な mail.kb ファイルは、Developer's Toolkit がインストールされたディレクトリーで調べることができます。


Tivoli Service Desk 6.0 Developer's Toolkit Script プログラミングの手引き

目次に戻る

著作権