OpenNTF.org - Setting up C++ API as Server T
My Links (Not logged in)
Code Bin Search
 
Hosted by Prominic.NET
Rate This Code
5 - brilliant stuff
4 - very nice
3 - average
2 - needs work
1 - bad
   OpenNTF Code Bin
About This Code
Brief Description:
Setting up C++ API as Server Tasks 
Rating:
Not Rated Yet 
Contributor:
Andrew Jones 
Category:
C/Cpp 
Type:
API Functions 
Last Modified:
03 Jul 2003 
OpenNTF Disclaimer

All of the program code and information presented in the OpenNTF.org Code Bin are provided "as-is", and should be used at your own risk. OpenNTF.org make no express or implied warranty about anything in the Code Bin, and OpenNTF.org will not be responsible or liable for any damage caused by the use or misuse of anything from this site. OpenNTF.org makes no guarantees about anything. Please thoroughly test all of the knowledge and code you find here before you attempt to use them in your production environment.

Code / Description
Usage / Example
Author: Daniel Sheppard - Notes/Domino C++ API Team
Date: Thursday, 7/15/99 6:10 PM PDT (Modified: Thursday, 7/15/99 7:06 PM PDT)
Subject: Add In Tasks and Message Queues - For Jack Yeh, Roar Fredriksen, and anyone else interested.
Category: C++ API



All,

I have finished overhauling the AddInJob sample to include using the LNMessageQueue class to accept user commands from the Domino server command console. The source listing for the new ADDINJOB.CPP file is at the bottom of this message for anyone wishing to use it. Just cut and paste it to replace the entire contents of your existing ADDINJOB.CPP file in the samples\addinjob folder of your current C++ API toolkit.

NOTE: I have tested it on Windows NT with a local Domino 5.0 server running on my machine and find it to work fine. However, it has not been thoroughly tested on any of the other supported platforms and our QE department has not blessed it either. So, just be warned ok... Well, now that this little disclaimer is over with... If you are currently having any problems with server add in Tasks or using message queues, this little sample should help you get over your troubles. Try it out and be sure to let everyone here know if it helps you out. Unfortunately, the updated sample will not officially appear until the next release of the toolkit, which is many months away... There is talk going on currently about setting up a "SandBox" web site where samples will appear on a regular basis so stay tuned for that...

Here is the updated description of the sample from the readme.txt file:

addinjob - Notes C++ API program that demonstrates how to use the LNServerAddin and LNMessageQueue classes. Its creates a server add-in task that periodically updates a database and gets and processes messages from the Lotus Domino server command console. It creates a status line and sets its status, and performs certain operations at specific time intervals. The 20 second time interval task looks for any new messages in the message queue and reports the receipt of each message as it is read off the queue. All output is logged in the server's log.nsf file and also shows up on the console screen.

One last note:

For more detailed information on creating and using server add-in tasks and message queues, be sure to read the related articles on these subjects in both the Lotus C++ API and Lotus C API User Guides that come with each respective tool kit.

And now, here is the listing for the new ADDINJOB.CPP file.

Cheers,
Daniel Shepppard
The Notes/Domino C++ API Team.

//===========================================================================
//
// Module: ADDINJOB.CPP
//
// Description:
//
// This program demonstrates how to use the LNServerAddin class
// to create a server add-in task to periodically update a
// database. It creates a status line and sets its status.
// Then it performs certain operations at specific time intervals.
// It outputs the status line text and the add-in task name to
// the server log.nsf file. In addition to all this, the program
// creates a message queue using the LNMessageQueue class and
// uses the message queue to receive commands from the server
// console every 20 seconds which are echoed back to the console
// using the LNServerAddin::AppendLogMessage method.
//
// SYNTAX: (at the Lotus server console) > load addinjob
//
//===========================================================================
//
// Copyright (c) 1997-1999 Lotus Development Corporation. All rights reserved.
// This software is subject to the Lotus Software Agreement, Restricted
// Rights for U.S. government users, and applicable export regulations.
//
//===========================================================================
#include <iostream.h>

// Notes C++ API headers.

#include "lncppapi.h"

// Forward declarations:

void OurAddInJob( LNDatabase &db, LNNotesSession &session );

//---------------------------------------------------------------------------
//
// MAIN
//
//---------------------------------------------------------------------------
int main(int argc, char *argv[])
{
int ProgramStatus = 0;
LNNotesSession session;
LNServerAddin addin;

// Throw all errors encountered during execution.

LNSetThrowAllErrors(TRUE);

try
{
LNDatabase db;
LNString buffer;
LNString taskname;
LNMessageQueue mqueue;

// Initialize the C++ API.

session.Init(argc, argv);

// First get our output database file.

session.GetDatabase("addinjob.nsf", &db);

// Create a server add-in task with default status line.

session.GetServerAddin("ADDINJOB","CPP ADDIN SAMPLE", &addin);

// Append the addin task Name to the log file.

taskname = addin.GetDefaultStatusLineTaskName();
buffer = "DefaultStatusLineTaskName = ";
buffer.Append(taskname);
addin.AppendLogMessage(buffer);

// Append the status line text to the log file.

buffer = "DefaultStatusLineText = ";
buffer.Append(addin.GetDefaultStatusLineText());
addin.AppendLogMessage(buffer);

// Create a message queue for this addin task.

buffer = TASK_QUEUE_PREFIX;
buffer.Append(taskname);
session.CreateMessageQueue( buffer, &mqueue);

// Begin the addin task main processing loop. The call to
// addin.Idle() serves two functions. First it relinquishes
// processor control to Domino allowing other tasks to run.
// Secondly, addin.Idle() will return TRUE, when it has received
// a quit command from Domino meaning a user has typed
// "tell myaddin quit" at the server console.
// NOTE: the member function: ShouldAddinTerminate() could be
// used to find this out as well without having to relinquish
// processor control.

while (!addin.Idle())
{
// Do the operations that we do each day.

if (addin.IsNewDay())
{
addin.SetDefaultStatusLineText("Doing daily job");

// Append the status line text to the log file.

addin.AppendLogMessage("CPP Add In Sample: Daily job complete.");
addin.SetDefaultStatusLineText("Idle");
}

// Do the operations that we do every other minute.

else if (addin.HaveMinutesElapsed(2))

{
addin.SetDefaultStatusLineText("Doing two-minute job");

// Do our database update job in this add-in task.

OurAddInJob(db,session);

// Append the status line text to the log file.

addin.AppendLogMessage("CPP Add In Sample: Two-minute job complete.");
addin.SetDefaultStatusLineText("Idle");
}

// Do the operations that we do every 20 seconds. (check message queue)

else if (addin.HaveSecondsElapsed(20))
{
LNString message;
LNINT nRetLen;
const LNINT nMaxMsgLen = MQ_MAX_MSGSIZE;
char buffer[nMaxMsgLen+1];

addin.SetDefaultStatusLineText("Doing 20-second job");

// Process messages if any are in the message queue.

while (mqueue.GetMessageCount() > 0)
{
// GetNextMessage automatically de-queues the message
// and decrements the current message count.

mqueue.GetNextMessage( nMaxMsgLen, buffer, &nRetLen);

// Do stuff with the messages...

message = "CPP Add In Sample: Received console command: ";
message.Append( LNString((const char *)buffer, nRetLen) );

addin.AppendLogMessage(message);
}

// Append the status line text to the log file.

addin.AppendLogMessage("CPP Add In Sample: 20-second job complete.");
addin.SetDefaultStatusLineText("Idle");
}

} // End while (!addin.Idle())

// Close the database.

db.Close();

} // END Try

catch (LNSTATUS lnerror)
{
char ErrorBuf[LNERROR_MESSAGE_LENGTH];
LNString errormessage;

LNGetErrorMessage(lnerror, ErrorBuf, LNERROR_MESSAGE_LENGTH);

errormessage = "AddInJob Sample: Exception thrown! Error: ";
errormessage.Append(ErrorBuf);
addin.AppendLogMessage(errormessage);

ProgramStatus = 1;
}

catch (const char *pErrorMessage)
{
LNString errormessage;

errormessage = "AddInJob Sample: Exception thrown! Error: ";
errormessage.Append(pErrorMessage);
addin.AppendLogMessage(errormessage);

ProgramStatus = 2;
}

catch (...)
{
LNString errormessage;

errormessage = "AddInJob Sample: Exception thrown! Error unknown!: ";
addin.AppendLogMessage(errormessage);

ProgramStatus = 3;
}

// Terminate the API

session.Term();

return(ProgramStatus);

} // END main()


//---------------------------------------------------------------------------
//
// Name:
// OurAddInJob
//
// Description:
// Local function called by the main add-in task loop.
//
// Inputs:
// db - LNDatabase for the database to be updated
// session - LNNotesSession for this Notes session
//
// Outputs:
// If successful, the database is updated.
//
//---------------------------------------------------------------------------
void OurAddInJob ( LNDatabase &db, LNNotesSession &session )
{
LNDocument Doc;
LNText AddInTextFld;
LNDatetime Dt;
LNDatetimes TimeFld;

try
{
// Open the database, create a new doc, and set its form.

db.Open();
db.CreateDocument(&Doc);
Doc.SetForm("AddInForm");

// Set the AddIn_Text field value.

AddInTextFld.SetValue("This is a note written by the add-in task.");

// Create AddIn_Text text field item in the new document.

Doc.CreateItem("AddIn_Text", AddInTextFld, LNITEMFLAGS_SUMMARY);

// Get a snapshot of the current date/time and use it to
// create a new datetime field in the new document.

Dt = session.GetCurrentDatetime();
TimeFld.SetValue(Dt);
Doc.CreateItem("AddIn_Time", TimeFld, LNITEMFLAGS_SUMMARY);

// Save and close the new document and close the database.

Doc.Save();
Doc.Close();
db.Close();

} // END try

catch (LNSTATUS lnerror)
{
char ErrorBuf[LNERROR_MESSAGE_LENGTH];

LNGetErrorMessage(lnerror, ErrorBuf, LNERROR_MESSAGE_LENGTH);

// Close everything that may be open at this point and then re-throw.
Doc.Close();
db.Close();

throw lnerror;
}

} // END OurAddInJob()

// END AddInJob.cpp



--------------------------------------------------------------------------------

[Previous Main Topic]
Add In Tasks and Message Queues - For Jack Yeh, Roar Fredriksen, and anyone else interested. (Daniel Sheppard - Notes/Domino C++ API Team) * You are here *

[Next Main Topic]

--------------------------------------------------------------------------------
by Topic (Expanded) , (Collapsed) | by Category | by Author | by Date | Home Page
--------------------------------------------------------------------------------

 Comments
Posted by Ove Størholt on 01/22/2005 04:53:24 PMI get a compile error trying this sample...
...related to the mq (messageque) stuff.
Any ideas?
Ove
Posted by asmi p on 12/15/2007 01:33:40 AMextending client functionality
Hello Sir,
As you have extended server functionality. I have a question about can we extend functionality of email client of notes8. For that does lotus notes provide any free templates. And also If it is allowed to do how can we do that ?
Thank You
 Add your comment!