| Application development environments evolve as new technologies are introduced. Both Domino and i5/OS are no exceptions to this. In fact, changes in one environment can influence changes in another.
The purpose of this article is to describe how some changes to i5/OS require new considerations when developing applications that use the Domino application programming interfaces; in particular, the C and C++ API interfaces. The i5/OS technology changes that this article contains information about are multiversioning and the use of teraspace storage. In addition to explaining these technologies, this article explains how they affect Domino on i5/OS applications and provides specific best practices for dealing with them.
More specifically, this article covers the following five recommended best practices for the development of C and C++ Domino applications on i5/OS in light of the multiversioning and teraspace storage changes:
- Bind to the LIBNOTES service program in QNOTES
- Link with the most current notes0 and notesai0 modules
- Teraspace-enable your applications
- Create or change service programs to use the inherit storage model and the caller activation group
- Create or change programs to use the teraspace storage model
Before going into the details on each of these items, let’s discuss the reasons you will want to implement these items when deploying C or C++ Domino applications on i5/OS.
Binding to the LIBNOTES service program in QNOTES is required so you do not have functional problems with your applications. This due to the multi-versioning support that was added to Domino on i5/OS. Multi-versioning was provided starting in Domino 6.5.0 and 6.0.3 on i5/OS and provides customers with a lot more flexibility when upgrading their Domino servers.
The reason you want to teraspace-enable your C and C++ Domino applications is to prepare them for future versions of Domino that will use teraspace storage internally. Teraspace support on the i5/OS allows for larger contiguous memory allocations and the use of 8-byte (64 bit) pointers. When using Single Level Store data, 16-byte (128 bit) pointers are required. The smaller 8-byte pointers can result in improved performance because of faster loads, stores, and pointer arithmetic. The performance improvements will result in lower CPU utilizations. Future versions of Domino expect to provide significantly lower CPU utilizations by using both teraspace storage and 8-byte pointers internally. Without teraspace-enablement, your applications will not be able to de-reference pointers to data returned by the Domino APIs. This does not require that your applications themselves actually use the teraspace storage model (that is optional), but data being returned by Domino APIs will be in teraspace, so you will need teraspace-enablement to de-reference this data.
Creating or changing service programs to use the inherit storage model and the caller activation group allows your programs to have the most flexibility for taking advantage of teraspace.
Creating or changing programs to use the teraspace storage model can improve the performance characteristics of the application. In addition, it is expected to be a requirement for any new Domino C and C++ API delivered in the future.
Let's now discuss these five best practices in more detail.
Bind to the LIBNOTES service program in library QNOTES When creating C or C++ programs that use the Notes/Domino C or C++ SDK on i5/OS, you must bind explicitly to the LIBNOTES service program in library QNOTES.
The LIBNOTES service program incorporates the functions and interfaces which support the Domino C and C++ API on i5/OS. This service program has always resided in library QNOTES on i5/OS. However, since the advent of multiversioning in Domino versions 6.0.3 and 6.5, it is now possible to have more than one version of the LIBNOTES service program on an i5/OS partition. Multiversioning allows more than one version or release of Domino to be installed and run within the same i5/OS partition. With multiversioning, each installed version of Domino has an associated library named QDOMINOxxx, where xxx corresponds to the version number. An example is QDOMINO653 for Lotus Domino version 6.5.3. Each QDOMINOxxx library also has a unique copy of the LIBNOTES service program which specifically supports the associated version of Domino.
Since the introduction of multiversioning, it has been documented that the version of the LIBNOTES service program in the library QNOTES should be the one bound to. This is because the version in QNOTES actually has the "smarts" to call the proper QDOMINOxxx version of LIBNOTES based upon the release level of the server being used. Failure to follow this approach may cause the wrong version of LIBNOTES to be used for the release of server in use, potentially resulting in undesired results.
When using the i5/OS commands for creating C and C++ programs and service programs, the BNDSRVPGM keyword has a default value of *LIBL which means that the version of LIBNOTES used will be the one found first in the library list, which may not be the LIBNOTES service program in library QNOTES. Because of this, do not use the default value of *LIBL on the BNDSRVPGM keyword.
Best Practice #1: Program (*PGM) and service program (*SRVPGM) objects that bind to the LIBNOTES service program must bind explicitly to the LIBNOTES service program in the QNOTES library. In other words, specify QNOTES/LIBNOTES on the BNDSRVPGM keyword, as shown in the following example:
CRTSRVPGM SRVPGM(MYLIB/MYSRVPGM) BNDSRVPGM(QNOTES/LIBNOTES)
In addition, the version of LIBNOTES in QNOTES will also likely have some new "smarts" added in a future major release for changes related to Domino use of teraspace storage and 8-byte pointers. The following sections explain more on these topics and the implications for existing i5/OS Domino C and C++ API applications.
Link with the most current notes0 and notesai0 modules
You can structure a Domino program as a subroutine named NotesMain. You can also structure a Domino program as a subroutine named AddInMain, which makes the program a Domino Server add-in task. Domino C API programs structured as a NotesMain or AddInMain subroutine need to link with certain modules.
Best Practice #2: NotesMain C API programs must link with the module notes0. AddInMain C API programs must link with both modules notes0 and notesai0.
For Domino on i5/OS, these modules reside in the library QNOTESAPI. The QNOTESAPI library gets installed either by loading option 1 of the Domino for i5/OS product or by downloading the Domino C API Toolkit from the product website.
If your Domino C API program links with notes0 or notesai0, make sure that it is updated to link with the most current version of these modules. Before building your application, install the most current version of the QNOTESAPI library to the system you are building your application on. Of specific importance, if you want to be able to teraspace-enable your application using the CHGPGM or CHGSRVPGM options noted in the next section, your application needs to be built with the Domino 6.5.1 or later version of notes0 and notesai0. You can use either the DSPPGM or the DSPSRVPGM commands to determine the level of the notes0 and notesai0 modules linked with your program.
Teraspace-enable your applications
You can choose from two types of storage on i5/OS servers when you create your ILE programs: teraspace and single-level store. Because single-level storage is constrained to 16MB of contiguous storage, teraspace storage was made available on i5/OS. Teraspace is a large temporary space that is local to a job. It allows for larger contiguous memory allocations and for the use of 8-byte pointers (instead of the 16-byte pointers required for Single Level Store data). The traditional 16-byte pointers can still be used to access teraspace storage; however, in order to access teraspace storage a program must be teraspace enabled. A non-teraspace enabled program will receive an MCH0607, MCH3601 or MCH3602 exception if it attempts to touch teraspace storage. The ILE C and C++ ILE compilers provide a command option to request the generation of teraspace enabled code. Details on these compiler options is explained later in this article.
NOTE: There is a difference between teraspace enabling an application and using teraspace storage in an application. By teraspace enabling an application, it gains the ability to access data passed to it whether the data is teraspace or single level storage. However, an application can go a step further and actually change so any storage it creates is teraspace rather than single level storage. While it is not required to use teraspace storage for current applications, it is expected to be a requirement for any new Domino C and C++ API delivered in the future. In addition, there are performance benefits to applications when they change to use teraspace storage.
Currently, the Domino server makes use of teraspace storage in certain areas where it needs more than 16MB of contiguous storage. The Lotus Domino code on the i5/OS is also fully teraspace-enabled. In other words, you can pass a teraspace address on a Domino API function call and the Domino server can access the data at the passed address.
IMPORTANT: While it has been recommended since release 5 of Domino that customers enable their Domino applications for teraspace, the next major release of Domino may require that your application is enabled for teraspace. Service program extensions to Domino should also be enabled for teraspace.
Best Practice #3: All programs and service programs that use the Domino C or C++ API should be enabled for teraspace.
When creating modules, programs or service programs, follow the guidelines below to ensure that your Domino applications are enabled for teraspace and are able to run in this environment.
- Teraspace-enablement does not require any source code changes, a recompile is all that is needed, in most cases.
- To determine if an existing application that interfaces with a Domino server is teraspace-enabled, issue the DSPPGM and DSPSRVPGM commands against any programs and service programs for that application. If you see *ALL for the 'Teraspace storage enabled modules' field, then that program or service program is teraspace-enabled.
- If instead of *ALL you see *SOME or *NONE, then the modules that make up the program or service program need to be teraspace-enabled.
There are two possible methods that can be used to teraspace-enable your application.
Method 1: Teraspace-enable your applications One potentially easy way to teraspace-enable your program or service program is via the CHGPGM or CHGSRVPGM commands. To teraspace-enable a program or service program using these commands, the application must have creation data supplied with it. Creation data is information stored internally within the program or service program from when the object was first created. Application providers sometimes strip out this creation data in order to reduce the size of the application objects.
If you have purchased a C or C++ Domino application from an ISV or business partner, ask them if they have teraspace-enabled the application. If they have not, request a version of the application code that is teraspace-enabled. You should never make modifications to Domino C or C++ applications that you have not written yourself, as you may not have the understanding of what the underlying application code does.
If you are working with a C or C++ Domino application that you have written, you can determine if the creation data is present for your application. The easiest way to determine if the creation data is present is to issue the CHGPGM or CHGSRVPGM commands against the programs and service programs, specifying the TERASPACE(*YES) option. If the commands work, then the program and service programs are enabled to use teraspace addresses.
Method 2: Teraspace-enable your applications If the CHGPGM or CHGSRVPGM approach detailed above does not work, then consider the following recommendations:
- Modules created using the CRTCMOD or CRTCPPMOD commands are enabled for teraspace by specifying the TERASPACE(*YES) keyword option. In addition, use STGMDL(*INHERIT) which provides the most flexibility when using these modules in programs and service programs later.
- Programs created using the CRTPGM command are enabled for teraspace if the modules are also enabled for teraspace. Specify TERASPACE(*YES) and STGMDL(*SNGLVL) on the CRTBNDC command if you are creating a module and program in one step. However, if you follow the recommendation of best practice #5 below, you would specify STGMDL(*TERASPACE) instead of STGMDL(*SNGLVL).
In a future version, Domino internally will use 8 byte pointers and the teraspace storage model (for better performance), but the QNOTES/LIBNOTES service program will provide appropriate data conversion so that customer application programs can continue to use 16 byte pointers and SLS storage, provided your program is teraspace-enabled so that it can de-reference the teraspace data returned by Domino. As an additional optional step, there will be some performance advantages if customer programs also convert to use the teraspace storage model, but this is not required.
For more information on enabling your application for teraspace, see Chapter 4 of the iSeries ILE Concepts (SC41-5606) book which is available at the following Web address:
http://publib.boulder.ibm.com/iseries/v5r2/ic2924/books/c4156066.pdf
Another good reference is the Domino for i5/OS C and C++ toolkits which can be downloaded from developerWorks:Lotus at the following Web address:
http://www.ibm.com/developerworks/lotus
Create service programs using the inherit storage model and the caller activation group
When working with bound service programs, you can cause the service programs to be created in such a way that they can use either single-level store or teraspace, depending on the type of storage in use in the activation group into which the service program is activated.
Best Practice #4: When you create a bound service program using the CRTSRVPGM command, specify ACTGRP(*CALLER) and STGMDL(*INHERIT) for a neutral storage model.
This will create a service program that will be compatible with current and future releases of Domino. This causes the service program to be created so it can use either single-level store or teraspace. The storage space used will depend on the type of storage in use in the activation group that invokes the service program. The use of the *INHERIT attribute provides the greatest flexibility, but then you must also specify *CALLER on the ACTGRP parameter. In this case, remember that your service program could get activated with either single-level store or teraspace, and you must take care that your code can effectively handle both situations
Create or change programs to use teraspace storage
In a future version, Domino internally will use 8 byte pointers and the teraspace storage model (for better performance), but the QNOTES/LIBNOTES service program will provide appropriate data conversion so that customer application programs can continue to use 16 byte pointers and SLS storage, provided your program is teraspace-enabled so that it can de-reference the teraspace data returned by Domino. As an additional optional step, there will be some performance advantages if customer programs also convert to use the teraspace storage model. In addition, while it is not required to use teraspace storage for current applications, it is expected to be a requirement for any new Domino C and C++ API delivered in the future. Therefore, it is strongly recommended to consider making this change at the same time that you are teraspace-enabling your application.
Best Practice #5: Create or change programs to use the teraspace storage model
Specify *TERASPACE on the STGMDL parameter of the CRTPGM command. You can also specify *TERASPACE on the STGMDL parameter of the CRTBNDC and CRTBNDCPP commands, which create in one step a bound program that contains only one module.
Summary of practices for preparing Domino applications for teraspace
Below is a summarization of the different compilation options for preparing your C and C++ API Domino applications for teraspace:
- Ensure that your modules are enabled for teraspace by specifying *YES on the TERASPACE parameter when you create your modules.
- Specify *TERASPACE or *INHERIT on the Storage model (STGMDL) parameter of the create module command for your ILE programming language.
- Specify *TERASPACE on the STGMDL parameter of the CRTPGM command. This choice must be compatible with the storage model of the modules that you bind with the program. You can also specify *TERASPACE on the STGMDL parameter of the CRTBNDC and CRTBNDCPP commands, which create in one step a bound program that contains only one module.
For more information on enabling your application for teraspace, see Chapter 4 of the iSeries ILE Concepts (SC41-5606) book which is available at the following Web address:
http://publib.boulder.ibm.com/iseries/v5r2/ic2924/books/c4156066.pdf
Another good reference is the Domino for i5/OS C and C++ toolkits which can be downloaded from developerWorks:Lotus at the following Web address:
http://www.ibm.com/developerworks/lotus |
