当ブログに掲載しているサンプルは、すべて利用者の自己責任とします。
ただし、明らかな不具合がある場合、ご連絡いただければ、訂正記事を出します。
また、こちらのサンプルは、別のサイト等への公開、転載は一切禁止しています。
どうしてもと言う場合は、筆者にあらかじめご連絡ください。
記事そのもののリンクについてはご自由に行っていただいてよいです。
xxのようなサンプルを作って欲しいとかxxxの作り方を教えて欲しいというお問い合わせには応じていません。
このようなお問い合わせは、株式会社エフまでご一報ください。

2020年2月21日金曜日

Examined results of ImportItem method

Today, this article is about function not described in help.
I already written by Japanese, but there I recieved request for translate, so I will translate it into English.

I will write about how to use ImportItem method of the NotesUIDocument class, in this time.

This method was added from Domino 8.5, actually used by mail databases.
For that reason, you may already know how to use it.
In that case please read reconfirm it.

1. Using in mail databases

You know where is ImportItem method used in mail databases don't you?
It is the signature part of the mail.
But it is not Electronic signature, it is the self-introduction part written at the bottom.
Add Signature action

Maybe you have used this action about once.
Usually, you would create a default signature in your mail preference and insert into mail body automatically.
The signature can write rich text, and it can be changed in color and size, and you can be pasted an image.

Default signature

When you execute the [Sign] action in memo form, it is inserted value of the signature from calendar profile at the bottom the mail.
Exactly it is the movement of importing a signature item(ImportItem) into the current document(NotesUIDocument).


In addition, if you check source code, it is written in the  function 'InsertSignature' of the class 'UIMemoDocument' of the script libraries 'CoreEmailClasses'.

By the way, this code is set as a string.

Code is described as a character string

I couldn't easily find the code, so I used the teamstudio configurator for find the code.
This code as a string is executed by 'Execute' function of LotusScript.
I don't know how to do this, so I learned.


2.Syntax

Let's check syntax by use Code Assistant.
Syntax of ImportItem

According to this, it doesn't have return value.
The arguments are the NotesDocument object and ItemName (strings).
I guess by above, the NotesDocument object may be expressed the source Notes documents, and the ItemName may be expressed by item name (Subject or Body).

What you should check is
(1) Is it all good if it is NotesDocument? It is a profile document in the signature of mail, but is a normal notes document good?
(2) Is it all good if it is NotesItem? Is it just rich text item or plain text, number, date-time is OK?


3.How to use

Let's check how to use it.
This method is import item from another Notes document.
So, what field is imported to?
The syntax of the method doesn't describe where to import it.
I think current field, but that it is performed action menu it is incomprehensible.

Let's check about NotesUIDocument class again.
They have GotoField method.
As you know, it is moved cursor to the specified field name.
Now you have the current field!
After that, you would execute ImportItem method of NotesUIDocument class.

I created sample code based on above.


4.Sample code

The sample code is as below.
Sub subImportItemTest( strGotoFieldName As String, strFromFieldName As String )
    On Error Goto ErrProc
    
    Dim uiws        As New NotesUIWorkspace
    Dim uidoc       As     NotesUIDocument
    Dim cENv        As     cEnvironment
    Dim docs        As     NotesDocumentCollection
    Dim doc         As     NotesDocument
    
    'PickList to get the source Notes document
    Set cEnv = New cEnvironment()
    Set docs = uiws.PickListCollection( PICKLIST_CUSTOM, False, cEnv.DBSERVER, cEnv.DBPATH, cENv.VIEWNAME, "Select document", "Please select the document information you want to get." ) 
    Set doc  = docs.GetFirstDocument
    
    'Executing ImportItem of NotesUIDocument
    Set uidoc = uiws.CurrentDocument
    Call uidoc.GotoField( strGotoFieldName )
    Call uidoc.ImportItem( doc, strFromFieldName )
    
    Exit Sub
    
ErrProc:
    Msgbox _
    "Error Line: " & Cstr(Erl) & Chr$(10) & _
    "Error Number: " & Cstr(Err) & Chr$(10) & _
    "Error Content: " & Error, _
    0 + 16, "Test for ImportItem method"
    
    Exit Sub
End Sub


This samle code is called and used by Call function.
Call subImportItemTest( "Field name to set", "Field name of the source document" )

This is it selects a document from another Notes databases and imports the items in the Notes document into specified field of current document.

The following figure shows an execution example.
Success stories

It was imported from Body field in another Notes document.
In addition, items of "text", "number", "date/time" and "rich text" in source document was worked normally.
Also, it works regular Notes document not only profile document.

But…

There are conditions the import destination field name.
If conditions are not met, it will occur error.

Failure example

It occurs error by ImportItem method of the NotesUIDocument class.
So, what are the requirements?

The answer is that it is a "Rich text" field.
Actually, I was trying to execute that without knowing this condition at first.
Because of that, I was troubled without success.
But I considered that NotesUIDocument class has FieldSetText or FieldAppendText method.

The good things about this is that you can set rich text item from another document.
It is a suitable for setting a signature of mail.


I wanted to that they had made error messages to be easier.
For example, "It was not specified rich text".


Now that you learn how to use it, why not use it into your existing Notes application?





That’s all. Thank you for reading.




Notes/Dominoで困ったことがあれば、弊社にお問い合わせください。
HCL Masterの私が承ります!
お問い合わせはこちらから→Lotus Notes/Domino カスタマイズとセキュリティ強化 - 株式会社エフ

2020年2月20日木曜日

ImportItemについて

皆さん、こんにちは。
今日もヘルプに載っていない機能についての話です。
今日で4つ目の紹介になります。

今回はNotesUIDocumentクラスのImportItemというメソッドになります。
このメソッドはDomino 8.5から追加されたもので、実はメールDBで利用されていたりします。
ですので、すでに利用方法についてご存じの方もいるかもしれません。
そういった方は復習のつもりで読んでみてください。


1.既存の利用箇所

このImportItemメソッドはメールのどこで使われているのでしょうか?
設計をくまなく探せば出てくるのでわかるかと思いますが、それでは何のために記事にしたんだ!ということになりますので、答えを書きます。
メールの署名の部分です。
署名といっても電子署名ではなく、メールの最下部に書く自己紹介の部分のことです。
署名の追加アクション

このアクション、一度は使ったことがあるのではないでしょうか?
通常は、メールのプリファレンスでデフォルトの署名を作成しておき、それを自動で挿入するようにしておくと思います。
この署名にはリッチテキストでの設定が可能になっており、色やサイズを変えたり、画像を貼り付けることも可能になっています。
デフォルトの署名
[署名]アクションを実行すると、カレンダープロフィール文書の署名欄の値をメールの最下部に挿入してくれるようになっています。
まさに、現在の文書(NotesUIDocument)に署名というリッチテキストアイテムをインポートしている(ImportItem)という動きです。

なお、実際のソースコードを確認すると、「CoreEmailClasses_ja-JP」というスクリプトライブラリの「UIMemoDocument」というクラスの「InsertSignature」という関数の中に記述されています。

少し話がそれますが、このコード、文字列として設定されています。
文字列としてコードが記述されている
そのため、コードの部分を一生懸命追いかけてもなかなか見つかりません(私は探すのに、ツールを使いました)。
この文字列となっているコードはLotusScriptのExecute関数で実行しているのです。
こういうやり方は知らなかったので勉強になりました。


2.構文

さて、利用されている個所も分かったので、構文を見ていきましょう。
いつものようにコードアシスタント(Ctrl+Space)を利用して確認します。
コードアシスタントによる構文の確認
これによると、戻り値はなさそうです。
また、引数はNotesDocumentオブジェクトとItemName(文字列)となっています。
既存の利用箇所で紹介したところから推察すると、
NotesDocumentオブジェクトはインポート元のNotes文書を表しているのでしょう。
ItemNameはアイテム名(SubjectとかBodyとか)を表しているのでしょう。

気になるのは、NotesDocumentであればなんでもよいのか?(メールの署名ではプロフィール文書が取得元ですが、通常の文書でも大丈夫なのか?)
ItemNameで指定するアイテムは何でもよいのか?(リッチテキストだけなのか、普通のテキストや数値、日付/時刻でもよいのか?)
というところでしょうか。

3.使用方法

さて、使用方法について確認してみましょう。
メールの署名でも確認したとおり、別の文書からアイテムをインポートしてくるという動きです。
では、どこにインポートするのでしょうか?
具体的に言えば、現在の文書のどのフィールドにインポートするのか?です。
メソッドの構文を見ても、どこにインポートするのかがわかりません。
また、アクションで実行されることを考えると、現在のフィールドというのも腑に落ちません。

ここでNotesUIDocumentクラスについてもう一度調べなおしてみましょう。
GotoFieldというメソッドがあります。
ご存じのように、指定したフィールド名にカーソルを移動するというものです。
これで、現在のフィールドが確保できました!
後は、NotesUIDocumentクラスのImportItemメソッドを実行すればよいでしょう。

上記を踏まえて、サンプルを作ってみましょう。

4.サンプル

サンプルコードはこちらです。

Sub subImportItemTest( strGotoFieldName As String, strFromFieldName As String )
    On Error GoTo ErrProc
    
    Dim uiws        As New NotesUIWorkspace
    Dim uidoc       As     NotesUIDocument
    Dim cENv        As     cEnvironment
    Dim docs        As     NotesDocumentCollection
    Dim doc         As     NotesDocument
    
    'インポート元のNotes文書を取得するためのPickList
    Set cEnv = New cEnvironment()
    Set docs = uiws.PickListCollection( PICKLIST_CUSTOM, False, cEnv.DBSERVER, cEnv.DBPATH, cENv.VIEWNAME, "文書の選択", "取得したい文書情報を選択してください。" ) 
    Set doc  = docs.GetFirstDocument
    
    'NotesUIDocumentのImportItemの実行
    Set uidoc = uiws.CurrentDocument
    Call uidoc.GotoField( strGotoFieldName )
    Call uidoc.ImportItem( doc, strFromFieldName )
    
    Exit Sub
    
ErrProc:
    MsgBox _
    "エラー行数:" & CStr(Erl) & Chr$(10) & _
    "エラー番号:" & CStr(Err) & Chr$(10) & _
    "エラー内容:" & Error, _
    0 + 16, "ImportItemのテスト"
    
    Exit Sub
End Sub



こちらは以下のようにCallで呼び出して使います。
Call subImportItemTest( "セットしたいフィールド名", "インポート元の文書のフィールド名" )

これは、別で指定しておいたNotes DBから文書を選択して、その文書内のアイテムを現在の文書のフィールドにインポートするものです。

実行例が以下の図です。
成功例
別文書のBodyフィールドの値をインポートしてくれました。
なお、インポート元の文書のアイテムは「テキスト」「数値」「日付/時刻」「リッチテキスト」のいずれも正常に動作しました。
また、サンプルでわかるように、プロフィール文書ではなく、通常のNotes文書でも動作します。

しかし・・・
インポート先の文書で指定するフィールド名ですが、条件があります。
その条件を満たしていないと以下のようなエラーになります。
失敗した場合
はい。NotesUIDocumentクラスのImportItemメソッドでエラーになります。
では必要条件は何でしょうか?

答えは「リッチテキスト」フィールドであることです。
実は、最初にこの条件がわからずに、テキストフィールドにインポートしようとしていました。
そのため、何をやってもエラーになってしまい、「どうやって使うんだ?使えないメソッドだなぁ。不親切だなぁ。」など、数々の暴言を(PCに向かって)吐いていましたw

ですが、ちょっと考えればわかりそうなものですよね。
テキストフィールドにセットするのであれば、NotesUIDocumentクラスのFieldSetTextやFieldAppendTextなど他にいくらでも手段があるのです。
わざわざ追加する機能ではないのです。

このメソッドのいいところは、別文書のリッチテキストをセットできるところです。
まさにメールの署名のような定型文をセットするのに向いているのでしょう。



願わくば、エラーメッセージをもう少しわかりやすくしてほしかったですね。
リッチテキスト以外が指定されていますとか、優しくしてほしいですw


これで使い方はわかっていただけたと思いますので、既存のNotes アプリケーションに組み込んではいかがでしょうか?





それでは今日はこの辺で・・・






Notes/Dominoで困ったことがあれば、弊社にお問い合わせください。
HCL Masterの私が承ります!
お問い合わせはこちらから→Lotus Notes/Domino カスタマイズとセキュリティ強化 - 株式会社エフ

2020年2月13日木曜日

InitiallyModifiedについて

皆さん、こんにちは。

今日もヘルプに載っていない機能についての話です。
ですが、あまりにも簡単で、なおかつ、ヒント自体はヘルプに出ているので 、日本語のみの投稿とします。

今回は、NotesDocumentクラスのInitiallyModifiedプロパティです。

まずはいつものようにコードアシスタントを確認してみます。
コードアシスタントに表示される
このようにNotesDocumentクラスのプロパティとして候補に表示されるのがわかります。
さて、ではヘルプを確認してみましょう。
NotesDocumentクラスのプロパティ一覧

見事なまでにないのがわかりますね・・・

しかし、今回はここであきらめずに検索してみました。
ヘルプの検索結果
おや?検索結果が出てきましたね。
JavaScriptクラスのメンバーとして検索されました。
これによると、
『読み取り専用。文書が最初に変更された日付/時刻。』とのことです。

ここで勘の鋭い方はNotesDocumentクラスのLastModifiedプロパティを思い出すのではないでしょうか?
はい、InitiallyModifiedはこのプロパティと対になっているものです。

では、具体的にどういったものかについて説明します。
InitiallyModifiedは文書のプロパティのうち、「更新日(初回)」を取得するものです。
対して、 LastModifiedは文書のプロパティのうち、「更新日(現在のファイル)」を取得するものです。
どのプロパティを取得する?

本当にそうなのかを確認するために、以下のようなサンプルを作成してみました。
Sub Click(Source As Button)
    On Error Goto ErrProc
    
    Dim session As New NotesSession
    Dim db      As     NotesDatabase
    Dim docs    As     NotesDocumentCollection
    Dim doc     As     NotesDocument
    
    Set db   = session.CurrentDatabase
    Set docs = db.UnprocessedDocuments
    Set doc  = docs.GetFirstDocument
    
    Msgbox _
    "InitiallyModified: " & Cstr(doc.InitiallyModified) & Chr$(10) & _
    "LastModified     : " & Cstr(doc.LastModified), _
    0 + 64, "InitiallyModified"
    
    Exit Sub
    
ErrProc:
    Msgbox _
    "エラー行数:" & Cstr(Erl) & Chr$(10) & _
    "エラー番号:" & Cstr(Err) & Chr$(10) & _
    "エラー内容:" & Error, 0 + 16, "InitiallyModifiedとLastModified"
    
    Exit Sub
End Sub


これはビューアクションです。
ビューで選択した最初の文書のプロパティを取得して画面に表示するものです。

結果はこちら。
実行結果

どうでしょう?説明の通りになっていますね。
実はこのInitiallyModifiedは「@Modified」関数で代用できるそうです。なので、使わなくても何とかなるでしょう。ただ、ソースコードに統一性を持たせたいのであれば、こちらを使ったほうがいいかもしれません。

詳しくは、
[Notes/Domino] 設計の更新日時を取得する方法
を読むと良いでしょう。


ちなみに、このプロパティはDomino 8.5から実装されたものになります。
どうりでJavaScriptのヘルプに載っているんですね…




それでは今日はこの辺で…






Notes/Dominoで困ったことがあれば、弊社にお問い合わせください。
HCL Masterの私が承ります!
お問い合わせはこちらから→Lotus Notes/Domino カスタマイズとセキュリティ強化 - 株式会社エフ

2020年2月10日月曜日

CancelSendOnMissingKeyについて

皆さん、こんにちは。

ここのところ、英語で記事を書きました。
こちらは、HCL Grand Masterの加藤さまからの課題ということで書いてみました。
ただ書くだけなら、過去の記事を英訳するだけでも良かったのですが、それではHCL Masterとしては(私自身を含めて)、誰も納得しないでしょう。
ですので、新しいことを調べた結果について書き上げました。

あえて日本語にしなかったのには理由があります。
実は、HCLへの苦情のつもりで書きました。私のブログは基本的にヘルプに書いてあることを元にしてあります。
ヘルプを読んでもわからない、わかりにくいだろうというところを補足するつもりで書いてきたのです。サンプルなんかもそうです。
ヘルプの補足なのです。

なので、日本語で書いても、HCLには届かないだろうということで英語で書いたのです。

それでも、私のブログの読者の大半は日本の技術者さまであろうということなので、日本語でも情報提供をしないといけないかな?と思い、前回の記事(Research results about CancelSendOnMissingKey)を日本語化したものをここに書きます。
英語が堪能な方にとっては、同じことの繰り返しになりますので、この記事はスルーしていただいてかまいません。

では、始めましょう・・・


コードアシスタントには出てくるけど、ヘルプの記述がないものがいくつかあります。今日はその中の一つであるNotesSessionクラスのCancelSendOnMissingKeyプロパティについて調べた結果を書いていきます。

1.構文

コードアシスタントを使うことでメソッドやプロパティの構文が表示されます。
コードアシスタントによる構文の確認
これによると、このプロパティの構文は次のようになりそうです。
データ型Boolean
取得する場合flag = notesDocument.CancelSendOnMissingKey
設定する場合notesDocument.CancelSendOnMissingKey = flag
有効な値True or False


2.デフォルト値

これはプロパティなので、デフォルト値があるはずです。
データ型は構文のところで説明したとおり、Boolean型ですから、デフォルト値はTrue もしくはFalseのどちらかになります。
また、NotesDocumentクラスのプロパティなので、Notes文書についても考慮する必要があります。
新規文書の場合と既存文書の場合です。
*厳密に言えば、既存文書の場合、色々なパターンが存在しますが、ここでは単にすでに作成してある文書とだけにしておきます。
それぞれのデフォルト値はどうなっているのかについて調べてみましょう。
次のようなコードを作成しました。
Sub Click( Source As Button )
  On Error GoTo ErrProc
  
  Dim session    As New NotesSession
  Dim dbCurrent  As     NotesDatabase
  Dim vwMailSend As     NotesView
  Dim docNew     As     NotesDocument
  Dim docExist   As     NotesDocument
  
  Set dbCurrent  = session.CurrentDatabase
  Set vwMailSend = dbCurrent.GetView( "your view name" )
  
  Set docNew = dbCurrent.CreateDocument
  MsgBox docNew.CancelSendOnMissingKey, 0 + 64, "Default value for new document"
  
  Set docExist = vwMailSend.GetFirstDocument()
  MsgBox docExist.CancelSendOnMissingKey, 0 + 64, "Default value for existing document"
  
  Exit Sub
  
ErrProc:
  MsgBox _
  "Error Line:    " & CStr(Erl) & Chr$(10) & _
  "Error Number : " & CStr(Err) & Chr$(10) & _
  "Error Content: " & Error, _
  0 + 16, "Mail send test"
  
  Exit Sub
End Sub


これを実行した結果は次の通りです。
新規文書の場合
既存文書の場合
どうやら、デフォルト値は常にFalseのようです。

3.サンプル

では、この値をTrueに変更したら何が起きるのでしょうか?
プロパティの名前から、メール送信に関するものではないかと推測しています。
そこで、以下のようなサンプルを作ってみました。
Sub subMailSendTest
  On Error GoTo ErrProc
  
  Dim session    As New NotesSession
  Dim dbCurrent  As     NotesDatabase
  Dim vwMailSend As     NotesView
  Dim docNew     As     NotesDocument
  
  Set dbCurrent  = session.CurrentDatabase
  Set vwMailSend = dbCurrent.GetView( "vwMailSend" )
  
  Set docNew = dbCurrent.CreateDocument
  
  Call docNew.ReplaceItemValue( "Form", "Memo" )
  Call docNew.ReplaceItemValue( "Subject", "Created by LotusScript " + CStr(Now) )
  Call docNew.ReplaceItemValue( "SendTo", "Masahiko Miyo/EFFECT-FORCE )
  
  docNew.CancelSendOnMissingKey = True
  
  Call docNew.Send( False )
  
  Exit Sub
  
ErrProc:
  MsgBox _
  "Error Line:    " & CStr(Erl) & Chr$(10) & _
  "Error Number : " & CStr(Err) & Chr$(10) & _
  "Error Content: " & Error, _
  0 + 16, "Mail send test"
  
  Exit Sub
End Sub


実行してみたら、こんなエラーが出ました。
エラーが発生…
どうやら、メールを送信できないようにするようです。

ちなみに、この後、プロパティをTrueにしてからNotes文書を保存するというサンプルを作成・実行してみましたが、正常に保存できました。


4.使い方

上のサンプルで見たように、Trueにしておくと、メール送信が失敗します。
これを利用して、画面の入力チェックやビジネスロジックのチェックに使うと良いのではないでしょうか?
ただ、エラー番号が4000という一般的なエラー番号になっているので、その他のエラーとの切り分けがしづらいところです。
できれば、他のエラー番号を割り当ててほしいですね。


5.まとめ

サンプルではメール送信時のエラー判定用として使えそうだという話をしましたが、プロパティの名前からすると、正しい使い方とは言えなさそうです。
どなたか、この機能について知っていたら、是非教えてください。


それでは今日はこの辺で…









Notes/Dominoで困ったことがあれば、弊社にお問い合わせください。
HCL Masterの私が承ります!
お問い合わせはこちらから→Lotus Notes/Domino カスタマイズとセキュリティ強化 - 株式会社エフ

Research results about CancelSendOnMissingKey

When I write LotusScript in Domino Designer, there are some methods and properties that appear in Code Assistant but don't have help document.
I will write about research results one of them, that the CancelSendOnMissingKey property of the NotesSession class, in this time.

** In addition, this property is a function added in Version 10.


1.Syntax

As shown below to display to the syntax for methods and property by use Code Assistant.
code assistant
According to this, the property syntax is below.   
Data typeBoolean
To getflag = notesDocument.CancelSendOnMissingKey
To setnotesDocument.CancelSendOnMissingKey = flag
Legal ValuesTrue or False


2.Default value

Since this is a property, it has default value.
As described in the syntax, this property data type is boolean that the default value is true or false.
Also, this is a property of NotesDocument class, then that must be also considered by about Notes document.
It is the case of new and exist one.
Let's examine about default value both new and exist one.
I created the sample code below.

Sub Click( Source As Button )
  On Error GoTo ErrProc
  
  Dim session    As New NotesSession
  Dim dbCurrent  As     NotesDatabase
  Dim vwMailSend As     NotesView
  Dim docNew     As     NotesDocument
  Dim docExist   As     NotesDocument
  
  Set dbCurrent  = session.CurrentDatabase
  Set vwMailSend = dbCurrent.GetView( "your view name" )
  
  Set docNew = dbCurrent.CreateDocument
  MsgBox docNew.CancelSendOnMissingKey, 0 + 64, "Default value for new document"
  
  Set docExist = vwMailSend.GetFirstDocument()
  MsgBox docExist.CancelSendOnMissingKey, 0 + 64, "Default value for existing document"
  
  Exit Sub
  
ErrProc:
  MsgBox _
  "Error Line:    " & CStr(Erl) & Chr$(10) & _
  "Error Number : " & CStr(Err) & Chr$(10) & _
  "Error Content: " & Error, _
  0 + 16, "Mail send test"
  
  Exit Sub
End Sub


The result of doing is below.
result of new document
result of exist document
Apparently, the default values always may be False.

3.Sample code

What will happen if it will be changed this value to True?
I guess from the property name that it is related to sending email.
So, I created sample code below.
Sub subMailSendTest
  On Error GoTo ErrProc
  
  Dim session    As New NotesSession
  Dim dbCurrent  As     NotesDatabase
  Dim vwMailSend As     NotesView
  Dim docNew     As     NotesDocument
  
  Set dbCurrent  = session.CurrentDatabase
  Set vwMailSend = dbCurrent.GetView( "vwMailSend" )
  
  Set docNew = dbCurrent.CreateDocument
  
  Call docNew.ReplaceItemValue( "Form", "Memo" )
  Call docNew.ReplaceItemValue( "Subject", "Created by LotusScript " + CStr(Now) )
  Call docNew.ReplaceItemValue( "SendTo", "Masahiko Miyo/EFFECT-FORCE )
  
  docNew.CancelSendOnMissingKey = True
  
  Call docNew.Send( False )
  
  Exit Sub
  
ErrProc:
  MsgBox _
  "Error Line:    " & CStr(Erl) & Chr$(10) & _
  "Error Number : " & CStr(Err) & Chr$(10) & _
  "Error Content: " & Error, _
  0 + 16, "Mail send test"
  
  Exit Sub
End Sub


When I ran it, it is displayed the following error.
Error occured

Apparently, that prevents me from sending mail.

incidentally, after that I created the other sample code.
The code is change to property to True and save the Notes document.
When I ran it, it was saved successfully.


4.How to use this property

As checked above, if set True to property to fail sending an email.
It is better idea to use this property for input check on screen or business logic check.
But Error number is 4000 of general error number, it is not easier to distinguish it from other errors.
I want to that is should to assign another error number.


5.Conclusion

In the sample code I mentioned that it could be used for error distinguish it when sending email.
But maybe it is not correct how to use.
Please teach me if anyone knows about this function.






That’s all. Thank you for reading.




Notes/Dominoで困ったことがあれば、弊社にお問い合わせください。
HCL Masterの私が承ります!
お問い合わせはこちらから→Lotus Notes/Domino カスタマイズとセキュリティ強化 - 株式会社エフ

2020年2月6日木曜日

About "Profiling agents and Web services"

** This blog is my first English text. I'm sorry if there is a mistake in the translation.

I was reading Help on Domino Designer and found unfamiliar features.
That is "Profiling agents and Web services". It seems like a feature introduced in version 7.0, but I never knew it.
As a result of reading the document, I became interested in this feature, so I will write about the results of various investigations.

1.Overview

The profiling agents feature reports on the following when an agent is written in LotusScript.
* The method of the Domino object used
* How many times was called
* Performance (execution time)

The following figure is an actual screenshot of profile results.

profile results

In this way, it is described separately for each object class and method.
The table is sorted in descending order of execution time, making it easier to understand where bottlenecks are in your programs.

you would be better to read help document this URL.
* but this site owner is IBM, you won't know when it will disappear.
Profiling agents and Web services

if you want to Japanese information, you would be better to read this site.
Lotus Domino 7エージェントプロファイル機能のご紹介



2.How to check profiling agents by agent’s property.

I will describe how to actually settings and check.

At first, the case of the agent.
(1) Open the agent written by LotusScript in Domino Designer.
(2) Open the agent properties.
(3) Check "Profile this agent" in Options.
Agent property
(4) Save the agent.
(5) Next, execute agent.
  * There is no problem with manual or scheduled execute.
  * The Notes application can be on the Domino server or on the Notes client.
(6) Right-click the agent in the agent view.
(7) Click '"View Profile Results" menu.

It is displayed the agent profiling results with this.
Profile results is saved as profile document in the Notes application. For that reason, only last exection results is saved. if you want to keep a record every time, save screen shots or copy and paste to Word documents.


3.How to check profiling agents by LotusScript.

The profile results can also be confirmed using LotusScript.
According to the help documentation, it is written to use GetPerformanceDocument of NotesAgent class.
Specifically:
using NotesAgent.GetPerformanceDocument, get profile document.
and, using NotesUIWorkspace.EditDocument, it displays on the screen.



4.About Extension feature

Actually, this feature enhanced in version 8.5.
It has been added method GetProfilerResults StartProfiler and StopProfiler into NotesSession class.
It can be profiling LotusScript code other than agents using these functions. you wrote the code directly script library or form, but isn't it working so slowly and not working as expected? It will be effective when used in such cases.
This profile document is saved as normal document in the Notes applications, not as a profile document.
For that reason, you can confirm the difference for every execute.


5.Sample code

I created sample code.
please refer to this code and execution results below.
There are 2 samples.
One is how to check agent's profile documents, the other one is about enhanced feature in version 8.5.

Sub Click(Source As Button)
  On Error Goto ErrProc
  
  Dim session As New NotesSession
  Dim db      As     NotesDatabase
  Dim agent   As     NotesAgent
  Dim doc     As     NotesDocument
  Dim uiws    As New NotesUIWorkspace
  
  Set db    = session.CurrentDatabase
  Set agent = db.GetAgent( "agtAgentAnalysisTest" )
  Call agent.Run()
  
  'Acquisition of profile result document and screen display
  Set doc = agent.GetPerformanceDocument()
  Call uiws.EditDocument( False, doc )
  
  Exit Sub
  
ErrProc:
  Msgbox _
  "Error Line: "     & Cstr(Erl) & Chr$(10) & _
  "Error Number: "   & Cstr(Err) & Chr$(10) & _
  "Error Contents: " & Error, _
  0 + 16, "Agent Profile Test"
  
  Exit Sub
End Sub


Sub Click(Source As Button)
  On Error Goto ErrProc
  
  Dim session    As New NotesSession
  Dim dbProfile  As     NotesDatabase
  Dim docProfile As     NotesDocument
  Dim db         As     NotesDatabase
  Dim doc        As     NotesDocument
  
  Set dbProfile  = session.GetDatabase( "ServerName", "Notes Application Path", False )
  Set docProfile = dbProfile.CreateDocument()
  Call session.GetProfilerResults( docProfile, "Program Profile Result" )
  Call session.StartProfiler()
  
  '--- Code to be profiled---
  Set db      = session.CurrentDatabase
  Set doc     = db.CreateDocument
  
  Call doc.ReplaceItemValue( "Form", "fmMainTopic" )
  Call doc.ReplaceItemValue( "Subject", " Document created by agent " + Cstr(Now) )
  Call doc.Save( True, True, True )
  '--- Code to be profiled---
  
  Call session.StopProfiler()
  Call docProfile.Save( True, True, True )
  
  Exit Sub
  
ErrProc:
  Msgbox _
  "Error Line: "     & Cstr(Erl) & Chr$(10) & _
  "Error Number: "   & Cstr(Err) & Chr$(10) & _
  "Error Contents: " & Error, _
  0 + 16, "Program Profile Test"
  
  Exit Sub
End Sub




6.Conclusion

Very few people around me knew about this feature.
Why?
I think it is because of the help documents and Domino Designer features.
Because the LotusScript mentioned above is not linked between Domino Desiger and help documents.
NotesSession.GetProfilerResults NotesSession. StartProfiler and NotesSession.StopProfiler appear in contents assistant, but they don't have a help document.

NotesSession class code assistant

NotesSession class help documentation
Conversely, NotesAgent.GetPerformanceDocument has a help documents, but don't appear in assistant contents.

GetPerformaceDocument method help documentation

NotesAgent class content assistant

This makes it difficult to use them correctly.
I hope that HCL will fix the documentation and modify Domino Designer.




That's all. thank you for reading.









Notes/Dominoで困ったことがあれば、弊社にお問い合わせください。
HCL Masterの私が承ります!
お問い合わせはこちらから→Lotus Notes/Domino カスタマイズとセキュリティ強化 - 株式会社エフ