14
Thu, Nov
2 New Articles

Notes C API with RPG IV

APIs
Typography
  • Smaller Small Medium Big Bigger
  • Default Helvetica Segoe Georgia Times

Lotus Domino is a very powerful groupware application server with several ways of implementing your software solution. There are so many choices for programming in Domino/Notes that it can be hard to choose which application strategy to follow. Notes wants to be your graphical interface to everything and is equipped to make that as easy as possible. For instance, Lotus has made it very easy to use DB2 UDB for AS/400 as a data store for Notes. Domino Enterprise Connection Services (DECS), which is part of the base Domino package, uses ODBC to store and retrieve individual records from external databases corresponding to forms in a Notes document. However, DECS does not push data into Notes from the back-end database.

Fortunately, Domino provides a number of solutions for this DECS limitation. One of them is the Notes API, which allows you to write programs that extract data from an external database and store this data in a Domino database.

This article is an introductory user’s guide to Notes C API programming using RPG IV. It covers the technical details of using the C API. Even though the API is written in C, you don’t have to understand the C language to use it, nor do you need to have a C compiler.

History and Background

Earlier in Notes’ life, there were several APIs to choose from. The lowest level, and the most functionally rich, was the Notes C API. At a higher level, being easier to use but with a bit less functionality, was the Notes HiTest API. Higher still was the Notes C++ API.

Then the happy decision to port Domino to the AS/400 was made. Shortly after that, some very helpful developers at Rochester wanted to give AS/400 programmers a head start with Lotus Notes API programming. So they decided to create a free, unsupported, downloadable library called RNHLIB containing function prototypes, help functions, and HTML documentation on how to use the Notes HiTest APIs.

However, as of Release 5 of Domino, the HiTest APIs are no longer officially supported by Lotus. You can still use the HiTest APIs, but they will not be enhanced any further. So, while the RNHLIB library functions do work, they are built over a function set that will not continue to grow and will possibly cease to work at some point in the future.


According to Lotus, the C API is, and will continue to be, the standard API for Lotus Notes programming. Thus, it would make sense to build any API-level access using the Notes C API, rather than the HiTest API.

However, the kind folks at Rochester have not built prototypes for the Notes C API, so programmers must. I chose to build the C API prototypes and help functions within the framework of the existing RNHLIB copybooks.

Before You Dig In

You can use the Notes C API to perform almost any function available within Notes. The subset of APIs I have prototyped will allow you to open and close a database; open, create, modify, and delete a Notes document; and create, retrieve, modify, and delete items (fields) within a Notes document. There are many more functions to prototype, and it is my sincere hope that the readers of Midrange Computing will continue to build upon this API set and share their prototypes with the rest of the AS/400 programming world.

To support Lotus Notes C API programming I had to declare a lot of prototype fields and constants. These are in member NTCNOTES. I also made use of several help functions written by the RNHLIB team (as well as writing some new ones myself), including setenv(), which sets environment variables necessary to the API, and SwitchTo/ FromQNOTES(), which switches your job to the QNOTES user profile and back. I also used addlibs() and rmvlibs() to manipulate the library list. These help functions are in member NTCTOOLS. Before I go any further, I should point out that my work built on that already done by the kind folks at Rochester and would have taken much longer otherwise. Kudos to IBM for making this API prototype set available.

As a general rule, the C API functions return a status variable of type NSFSTATUS, which I have prototyped for you. A return value of 0 (zero) means that the call was successful. Any return value other than 0 indicates a specific error. Lotus supplies a C function (OSLoadString()) that returns the text version of this error, but I have not yet encapsulated this function, as it requires a C macro to be run as a preparatory step. (Perhaps one of you would be willing to submit this prototype to the magazine?)

Data Types and Other Items

Notes has several data types. Some map well to relational databases. Text is like an alphanumeric field, except that it is not fixed in length by definition. A number is always stored in Notes as a double-precision floating-point value. (By the way, this means that Notes numbers are limited to 17 significant digits, as this is the upper limit of precision for double-precision floating-point values.) DateTime is an AS/400 time stamp. There are other list types that do not map well to relational database fields, but I haven’t covered them in this article. For instance, Notes has a text list data type that is similar to an element list in a command definition. This does not map well to a single field in a relational table since it represents multiple values.

Get Initialized!

Writing Notes C API programs is similar to writing HiTest API programs. In the setup and initialization process, for example, you have to make sure the library list is configured correctly; then you have to set up the path variables and switch to the QNOTES user profile. The HiTest help functions handle these tasks for you.

The next required step for using C API in an RPG IV program is initialization. Figure 1 contains an RPG snippet for this step.

To accomplish this initialization you have to perform a “fakeout” of the C API. Argc and argv represent the entry parameters to a standard C program’s main() function. A standard C program receives two arguments, or parameters. The first, argc (argument count), is a count of the parameters. The second, argv (argument vector), is a pointer to an array of pointers to the actual parameters. To accomplish this “double indirection,” I use the


%addr function to get the address of the variable “arg” and store that in arg@. I then use the %addr function again to get the address of arg@, store it in argv, and pass that to the function. You will see this “pointer to a pointer” technique used a lot in the Notes C API.

The Notes C API expects most strings to be converted to the Lotus Multi-byte Character Set (LMBCS). Taking my inspiration from the CvtTo/FromDomStr() functions provided in the HiTest API set, I wrote functions CvtToNSFString() and CvtFromNSFString(), which use the C API function OSTranslate(). These functions enable RPG IV to converse with the C API and are in member NTCTOOLS.

Parts Is Parts

Having successfully initialized the Notes C API, you can now open a database. To do this, pass the file path to the function, as illustrated by the RPG code in Figure 1. The NSFOpenDb() function receives the path to the database in a null-terminated string, and returns a handle to the database. This is really just a number, but it means something to Notes.

As shown in Figure 2, to create a new Notes document, you specify that the database should create one by using a valid database handle. The Notes API creates a Notes document in that database, returning a handle to the database.

Also as illustrated in Figure 2, to specify the default form for the Notes document, you add a text item to the note called Form using NSFItemSetText(). You pass the NOTEHANDLE to the Notes document so that the API knows where to insert the new item. You would use this API to add or update any text (character) item to a Notes document. Figure 2 also demonstrates the very similar code to add a Number item using NSFItemSetNumber(). Again, the same API is used to add a new item or update an existing item.

As shown in Figure 3 (page 71), creating TIMEDATE items requires a bit more work. Sometimes when the API reference says it wants an ASCII string as input, it really means it! So you have to convert the Date/Time string to ASCII first. For this task, I use the API QDCXLATE. Then I call the function ConvertTextToTIMEDATE() to get a Notes TIMEDATE value. Finally, I call NSFItemSetTime() to create the data item. Again, a lot of this functionality should be encapsulated into a higher-level function. Note once again (in Figure 3) the “double indirection” pointer to a pointer to a variable.

A Notes document’s Universal Identifier (UNID) is like the relative record number of a database record, except that it will never change, even if you send the note to another database. You can view the UNID of a Notes document by right-clicking in a document, selecting Document Properties, and then selecting the rightmost tabbed pane (the one with the propeller hat on it). The UNID is in the first two lines shown there. However, it is represented differently there than it is in the API. What you see in that pane is the hexadecimal representation of the UNID. However, that representation is in a different order than what you find in the UNID used by the API. Why Lotus represents the UNID in different ways is a mystery to me! One common function is to open a document by specifying the UNID for that document. However, you can’t directly retrieve the UNID of a note. The UNID is in the first 16 bytes of the Note Originator ID, or OID. So you must retrieve the OID using the NSFNoteGetInfo() API, and extract the UNID from it, as illustrated in Figure 4.

You’ve created a new Notes document and added data items to it. All you have to do now is close the document, right? No! If you close the document at this point, you’ll lose all that you have created. To save the new document to disk, you must call the NSFNoteUpdate() function, and then close it with the NSFNoteClose() function, as shown in Figure 5.

Go Get It


So you know how to create a Notes document and add items to it. Now I’ll show you how to retrieve them. Figure 6 illustrates how to retrieve a text item using NSFItemGetText(). Note that the CvtFromNSFStr() function was used and that the input and return variables are the same. It’s neat that this works.

Figure 6 also illustrates how to retrieve a Number item using NSFItemGetNumber(). There is more work involved in retrieving a TIMEDATE value. Once again, this is a multistep process. You retrieve the TIMEDATE value using NSFItemGetTime(), convert it to text using ConvertTIMEDATEToText(), and then convert the text from ASCII with QDCXLATE (see Figure 7). Further encapsulation would be good here, too.

Make It Go Away

Deleting a Notes document is different from creating a note. You delete a Notes document by its NOTEID, not by the NOTEHANDLE returned from NSFNoteCreate(). As shown in Figure 8, you use NSFNoteGetInfo(), the same function used to get the UNID.

Having done that, just call NSFNoteDelete(), also as shown in Figure 8. All that’s left to do now is close the database and detach from Notes (see Figure 8).

First, you close the database, and then the terminate function, NotesTerm(), is called. Since this function returns no value and takes no parameters, I just used a CALLP to invoke it.

It is good manners to undo any changes made to an environment, so switch back from the QNOTES profile and remove the library list changes before exiting. Again, the RNHLIB help functions are your friends. However, my experience has been that the OS/400 API to switch back to the original user profile doesn’t always work properly. I was often required to sign off my interactive session and sign back on to get my authorities back.

Building Blocks

In addition to the prototype and helper function source members that are available in a downloadable Save file at www.midrangecomputing.com/mc, I've included the RPGLE source for a sample program you can compile and run to test your new-found Notes C API savvy. Creating the program is a two-step process. First, you create the module:

CRTRPGMOD MODULE(LIBNAME/NTCAPITEST)

SRCFILE(LIBNAME/SRCFILE)

SRCMBR(NTCAPITEST)

Then you create the program. I found that the OPTION(*DUPPROC) parameter was necessary because there was a conflict between the Java function GetVersion() and the Notes function GetVersion(). I never could figure out how or why the CRTPGM command was finding the Java function, but this solved the problem. I also created a binding directory named NTCBNDDIR that contained the non-Lotus modules needed to support Notes C API programming, namely NTCTOOLS and NTCLIBL:

CRTPGM PGM(LIBNAME/NTCAPITEST)

MODULE(LIBNAME/NTCAPITEST)

BNDSRVPGM(QNOTES/LIBNOTES)

BNDDIR(NTCBNDDIR)

ACTGRP(*CALLER)

OPTION(*DUPPROC)

It’s Your Turn

The Notes C API is very flexible and very deep. There are many useful functions I have not prototyped. For instance, NSFSearch() can be used to retrieve a list of Notes


documents matching selection criteria. Further encapsulation of some of the functions I have presented would be valuable from a clarity or usability standpoint. Nonetheless, I hope this will speed you on your way to using your Domino server in ever more productive and interesting ways.

D arg s 10A inz('NTCAPITEST')
D arg@ s * inz(%addr(arg))
D argv s * inz(%addr(arg@))
D argc s like(NSFDWORD) inz(1)
D Path s 256A
D Database s like(NSFDBHANDLE)

C eval Status = NotesInitExtended( argc : argv )
C eval Status = NSFDbOpen(
C CvtToNSFStr(Path) :
C Database)

C eval Status = NSFNoteCreate(
C Database :
C NoteHandle)

C eval ItemName = 'TextItem'
C eval Status = NSFItemSetText(
C NoteHandle :
C CvtToNSFStr(ItemName) :
C CvtToNSFStr(ItemValue) :
C %len(%trim(ItemValue)))

C eval ItemName = 'NumberItem'
C eval Status = NSFItemSetNumber(
C NoteHandle :
C CvtToNSFStr(ItemName) :
C Double)

D TotLen S 5p 0 inz(20)
D OutLen S 5p 0
D XltTbl DS
D Table 10 inz('QASCII ')
D TableLib 10 inz('*LIBL ')
D TimeText s 20a inz('10/22/1962 08:30:00')
D TimeText@ s * inz(%addr(TimeText))
D TimeText@@ s * inz(%addr(TimeText@))
D TimeValue s like(NSFTIMEDATE)
D TimeValue@ s * inz(%addr(TimeValue))
D TimeTextLen s like(NSFWORD) inz(20)

* Add an item of type TIMEDATE
C call 'QDCXLATE'
C parm TotLen
C parm TimeText
C parm Table
C parm TableLib

C eval Status = ConvertTextToTIMEDATE(
C *NULL :
C *NULL :
C TimeText@@ :
C TimeTextLen :
C TimeValue@)

C eval ItemName = 'TestTimeItem'
C eval Status = NSFItemSetTime(
C NewNoteHandle :
C CvtToNSFStr(ItemName) :
C TimeValue)

Figure 3: Here the RPG program creates a date item in a Notes document.


Figure 1: This RPG program snippet performs Notes API initialization and opens the database.

Figure 2: Here the RPG program creates a Notes document, assigns a form name as a text item, and then adds a number item.

D NoteHandle s like(NSFNOTEHANDLE)
D UNID s like(NSFUNID)

C eval Status = NSFNoteGetInfo(
C NoteHandle :
C NSF_NOTE_OID :
C %addr(NoteOID))
C eval UNID = %subst(NoteOID:1:16)

C eval Status = NSFNoteOpenByUnid(
C Database :
C UNID :
C 0 :
C NoteHandle)

C eval Status = NSFNoteUpdate(NoteHandle : 1)
C eval Status = NSFNoteClose(NoteHandle)

D RtvString s 80a
D RtvString@ s * inz(%addr(RtvString))
D RtvDouble s 8f
D RtvDouble@ s * inz(%addr(RtvDouble))

C eval ItemName = 'TextItem'
C eval Status = NSFItemGetText(
C NewNoteHandle :
C CvtToNSFStr(ItemName) :
C RtvString@ :
C %len(%trim(RtvString)))
C eval RtvString = CvtFromNSFStr(RtvString)

C eval ItemName = 'NumberItem'
C eval Status = NSFItemGetNumber(
C NewNoteHandle :
C CvtToNSFStr(ItemName) :
C RtvDouble@)

D RtvTimeValue s like(NSFTIMEDATE)
D RtvTimeValue@ s * inz(%addr(RtvTimeValue))
D RtvOkay s 1a
D RtvTimeText s 80a
D RtvTimeText@ s * inz(%addr(RtvTimeText))
D RtvBufferLength...
D s like(NSFWORD) inz(80)
D RtvTextLen s like(NSFWORD)
D RtvTextLen@ s * inz(%addr(RtvTextLen))

* Retrieve the value of the TIMEDATE item "TestTimeItem"
C eval ItemName = 'TestTimeItem'
C eval RtvOkay = NSFItemGetTime(
C NewNoteHandle :
C CvtToNSFStr(ItemName) :
C RtvTimeValue@)
C eval Status = ConvertTIMEDATEToText(
C *NULL :
C *NULL :
C RtvTimeValue:
C RtvTimeText@ :
C RtvBufferLength :
C RtvTextLen@)
C eval TotLen = RtvTextLen
C eval Table = 'QEBCDIC '
C call 'QDCXLATE'

Figure 4: Here the RPG program retrieves a Notes document’s UNID and opens a document by its Universal ID.

Figure 5: To store an updated Notes document to disk, you update it and then close it.

Figure 6: Here the RPG program retrieves a text item and a number item.

Figure 7: Here the RPG program retrieves a Date item.


D NoteID s like(NSFNOTEID)

C eval Status = NSFNoteGetInfo(
C RtvNoteHand :
C NSF_NOTE_ID :
C %addr(NoteID))

C eval Status = NSFNoteDelete(
C Database :
C NoteID :
C 0)

C eval Status = NSFDbClose(Database)
C callp NotesTerm

Figure 8: Delete a Notes document, close the database, and terminate your API session.


BLOG COMMENTS POWERED BY DISQUS

LATEST COMMENTS

Support MC Press Online

$

Book Reviews

Resource Center

  • SB Profound WC 5536 Have you been wondering about Node.js? Our free Node.js Webinar Series takes you from total beginner to creating a fully-functional IBM i Node.js business application. You can find Part 1 here. In Part 2 of our free Node.js Webinar Series, Brian May teaches you the different tooling options available for writing code, debugging, and using Git for version control. Brian will briefly discuss the different tools available, and demonstrate his preferred setup for Node development on IBM i or any platform. Attend this webinar to learn:

  • SB Profound WP 5539More than ever, there is a demand for IT to deliver innovation. Your IBM i has been an essential part of your business operations for years. However, your organization may struggle to maintain the current system and implement new projects. The thousands of customers we've worked with and surveyed state that expectations regarding the digital footprint and vision of the company are not aligned with the current IT environment.

  • SB HelpSystems ROBOT Generic IBM announced the E1080 servers using the latest Power10 processor in September 2021. The most powerful processor from IBM to date, Power10 is designed to handle the demands of doing business in today’s high-tech atmosphere, including running cloud applications, supporting big data, and managing AI workloads. But what does Power10 mean for your data center? In this recorded webinar, IBMers Dan Sundt and Dylan Boday join IBM Power Champion Tom Huntington for a discussion on why Power10 technology is the right strategic investment if you run IBM i, AIX, or Linux. In this action-packed hour, Tom will share trends from the IBM i and AIX user communities while Dan and Dylan dive into the tech specs for key hardware, including:

  • Magic MarkTRY the one package that solves all your document design and printing challenges on all your platforms. Produce bar code labels, electronic forms, ad hoc reports, and RFID tags – without programming! MarkMagic is the only document design and print solution that combines report writing, WYSIWYG label and forms design, and conditional printing in one integrated product. Make sure your data survives when catastrophe hits. Request your trial now!  Request Now.

  • SB HelpSystems ROBOT GenericForms of ransomware has been around for over 30 years, and with more and more organizations suffering attacks each year, it continues to endure. What has made ransomware such a durable threat and what is the best way to combat it? In order to prevent ransomware, organizations must first understand how it works.

  • SB HelpSystems ROBOT GenericIT security is a top priority for businesses around the world, but most IBM i pros don’t know where to begin—and most cybersecurity experts don’t know IBM i. In this session, Robin Tatam explores the business impact of lax IBM i security, the top vulnerabilities putting IBM i at risk, and the steps you can take to protect your organization. If you’re looking to avoid unexpected downtime or corrupted data, you don’t want to miss this session.

  • SB HelpSystems ROBOT GenericCan you trust all of your users all of the time? A typical end user receives 16 malicious emails each month, but only 17 percent of these phishing campaigns are reported to IT. Once an attack is underway, most organizations won’t discover the breach until six months later. A staggering amount of damage can occur in that time. Despite these risks, 93 percent of organizations are leaving their IBM i systems vulnerable to cybercrime. In this on-demand webinar, IBM i security experts Robin Tatam and Sandi Moore will reveal:

  • FORTRA Disaster protection is vital to every business. Yet, it often consists of patched together procedures that are prone to error. From automatic backups to data encryption to media management, Robot automates the routine (yet often complex) tasks of iSeries backup and recovery, saving you time and money and making the process safer and more reliable. Automate your backups with the Robot Backup and Recovery Solution. Key features include:

  • FORTRAManaging messages on your IBM i can be more than a full-time job if you have to do it manually. Messages need a response and resources must be monitored—often over multiple systems and across platforms. How can you be sure you won’t miss important system events? Automate your message center with the Robot Message Management Solution. Key features include:

  • FORTRAThe thought of printing, distributing, and storing iSeries reports manually may reduce you to tears. Paper and labor costs associated with report generation can spiral out of control. Mountains of paper threaten to swamp your files. Robot automates report bursting, distribution, bundling, and archiving, and offers secure, selective online report viewing. Manage your reports with the Robot Report Management Solution. Key features include:

  • FORTRAFor over 30 years, Robot has been a leader in systems management for IBM i. With batch job creation and scheduling at its core, the Robot Job Scheduling Solution reduces the opportunity for human error and helps you maintain service levels, automating even the biggest, most complex runbooks. Manage your job schedule with the Robot Job Scheduling Solution. Key features include:

  • LANSA Business users want new applications now. Market and regulatory pressures require faster application updates and delivery into production. Your IBM i developers may be approaching retirement, and you see no sure way to fill their positions with experienced developers. In addition, you may be caught between maintaining your existing applications and the uncertainty of moving to something new.

  • LANSAWhen it comes to creating your business applications, there are hundreds of coding platforms and programming languages to choose from. These options range from very complex traditional programming languages to Low-Code platforms where sometimes no traditional coding experience is needed. Download our whitepaper, The Power of Writing Code in a Low-Code Solution, and:

  • LANSASupply Chain is becoming increasingly complex and unpredictable. From raw materials for manufacturing to food supply chains, the journey from source to production to delivery to consumers is marred with inefficiencies, manual processes, shortages, recalls, counterfeits, and scandals. In this webinar, we discuss how:

  • The MC Resource Centers bring you the widest selection of white papers, trial software, and on-demand webcasts for you to choose from. >> Review the list of White Papers, Trial Software or On-Demand Webcast at the MC Press Resource Center. >> Add the items to yru Cart and complet he checkout process and submit

  • Profound Logic Have you been wondering about Node.js? Our free Node.js Webinar Series takes you from total beginner to creating a fully-functional IBM i Node.js business application.

  • SB Profound WC 5536Join us for this hour-long webcast that will explore:

  • Fortra IT managers hoping to find new IBM i talent are discovering that the pool of experienced RPG programmers and operators or administrators with intimate knowledge of the operating system and the applications that run on it is small. This begs the question: How will you manage the platform that supports such a big part of your business? This guide offers strategies and software suggestions to help you plan IT staffing and resources and smooth the transition after your AS/400 talent retires. Read on to learn: