Skip to content

Building IBM i Applications

Chapter 3-3
Building IBM i Applications


Introduction

The HCL C API Toolkit for Notes/Domino lets you also build IBM i applications. However, development of IBM i applications specifically requires the HCL C API Toolkit for Notes/Domino for IBM i. This chapter describes the details specific to building HCL C API applications for Domino in the IBM i environment. It covers the following topics:

    Getting Started
   Toolkit installation, compiler requirements<br>


Toolkit Files
Accessing the IBM i toolkit header files

Compiling and Linking
Compiling and linking on the IBM i

Running the C API program
Running C API programs on the IBM i

General Considerations for Using C API
Considerations using the C API on the IBM i

Building C applications Using CL Programs
Building C applications using CL programs on the IBM i

Building C applications Using WebSphere Development Studio for IBM i CODE
Building C applications using WebSphere development studio CODE on the IBM i

Getting Started

If you did not install the HCL C API for Notes/Domino software for IBM i when you installed the Domino for IBM i software, you will need to go back and install it for now as it is not part of the HCL C API toolkit at this time.



Compiler Requirements for C

Compiling C application programs requires using the native IBM i C compiler -- ILE C compiler.

The process for creating IBM i ILE C programs or service programs includes two steps:

  1. Run the CRTCMOD (Create C Module) command to compile C source code into modules.
  2. Run the CRTPGM(Create Programs) or CRTSRVPGM(Create Service Programs) to bind modules into an ILE program or service program.


The required software to compile C programs are:

  • The ILE C Compiler, available as Product 5770WDS(on V7R2) Option 51.
  • The QSYSINC, available through the "Install Licensed Program" Option 13.


In addition, the CODE (CoOperative Development Environment) component of the WebSphere Development Studio Client for IBM i provides tools to develop, compile and link the C programs. For further information on obtaining the WebSphere Development Studio Client for IBM i go to:
http://www.ibm.com/software/ad/wdt400


Toolkit Files

When you install the C API support software on IBM i, the C header files are installed in the library QNOTESAPI. Within this library, the header files are members of the IBM i file H.FILE (QNOTESAPI/H). The installation also creates symbolic links /qibm/proddata/lotus/notesapi/include/.h to the header file members.

The source code of a C application can be stored as a "Root" file system file in IFS (Integrated File System), or as a member of a physical file. It is recommended to keep the source in an IFS file.

If you compile the C application programs with the source code in the Integrated File System, the compiler will access the headers through the symbolic links. You only need to specify the symlnk directory /qibm/proddata/lotus/notesapi/include with the compiler Include Directory parameter (INCDIR).

If you compile the C application programs with the source code as a member of a physical file, the ILE C compiler can access the headers as they are installed in the QNOTESAPI library. You only need to add the QNOTESAPI to your library list.


Compiling and Linking

The IBM i ILE C/C++ Programmer's Guide (SC09-2712) describes how to compile a C program using the ILE C compiler. In using the procedures described in that book, you need to follow either the IFS or physical file instructions below to compile the C application and then do the linking.

Compiling the C application with the source as an IFS file

Compile the application using CRTCMOD command. You need to specify the path name of the source file in SRCSTMF compiler parameter. Also, specify the Include Directory in the parameter INCDIR and define names of OS400 and UNIX in DEFINE parameter. For example:
CRTCMOD MODULE(ctest/foo)
SRCSTMF('ctest/foo/foo.c')
DEFINE(OS400 UNIX) SYSIFCOPT(IFSIO)
INCDIR('/qibm/proddata/lotus/notesapi/include')

This command creates a module called FOO.MODULE in the library CTEST on the IBM i.

Compiling the C application with the source as a member of physical file

  1. Put the QNOTESAPI library in your library list. For example, enter this IBM i command:
    ADDLIBLE QNOTESAPI
  2. Specify a define name of OS400 when you compile the C module on IBM i (CRTCMOD command). For example:

   crtcmod module(ctest/foo) define(os400)

This command creates a module called FOO.MODULE in the library CTEST on the IBM i.


Linking the C application

After compiling the C module with the source in either an IFS file or a physical file , link the module into a program (CRTPGM command) or a service program (CRTSRVPGM command) on the IBM i on which you compiled the module. When you use either the CRTPGM or the CRTSRVPGM command, bind in the LIBNOTES service program found in the QNOTES library. Here is a link statement that uses CRTPGM to make a program from the above compilation:
CRTPGM PGM(CTEST/FOO)  MODULE (CTEST/FOO)  BNDSRVPGM (QNOTES/LIBNOTES)

The CRTPGM command creates FOO.PGM in the library CTEST.LIB.

Note: It is very important to make sure that the program is bound to the LIBNOTES service program in library QNOTES. Some applications have been found to incorrectly specify a library of *LIBL when binding to the LIBNOTES service program. This can result in incorrect operation in a multi-versioned Domino environment. Applications must specify library QNOTES when binding to the LIBNOTES service program in order to function correctly in a multi-versioned environment.

Depending on what type of Domino application is being written, you may need to link in either or both of the NOTES0 and NOTESAI0 modules. These two modules are in the QNOTESAPI library. To link in either or both of these modules, add the module or modules to the module list of the CRTPGM or CRTSRVPGM command. For example:
CRTPGM PGM (CTEST/FOO) MODULE(CTEST/FOO QNOTESAPI/NOTES0)
BNDSRVPGM (QNOTES/LIBNOTES)
or
CRTPGM PGM(CTEST/FOO) MODULE(CTEST/FOO QNOTESAPI/NOTESAI0)
ENTMOD(QNOTESAPI/NOTES0) BNDSRVPGM(QNOTES/LIBNOTES)

Linking in either or both NOTES0 or NOTESAI0 modules depends on the main entry pointer you used in your program. For more details, see Chapter 4 of Program Structure.

If using main() as the main entry point in your program, you may need to link with proper module in library QADRT for ASCII I/O. More details can be found at:
http://www.ibm.com/partnerworld/wps/servlet/ContentHandler/pw_com_asciirt_tips

    If the application is to run under the Domino server, you must manually create a symbolic link from the Domino server UserData directory to the location of the executable:
    ADDLNK OBJ ('/QSYS.LIB/CTEST.LIB/FOO.PGM')
    NEWLNK('/Qibm/UserData/Lotus/Notes/foo.pgm')  LNKTYPE (*SYMBOLIC)

    For More Information


      TBD

    Using the C API toolkit makefiles (CL programs) to build C applications

    The HCL C API toolkit provides samples to illustrate how to use the C++ APIs. We have ported some of the samples from the HCL C API toolkit to IBM i. For each of the IBM i samples, the toolkit provides 2 makefiles. One is used to build the sample with the source in IFS; one is used for the sample source as a member of a physical file. Each makefile is an IBM i Command Line Program (CLP) and is kept as a physical file member.

    This is probably the easiest way to build a sample. To build a sample, the users only need to compile the makefile (CLP source) and call the CL program. The section "Building C applications Using CL Programs" contains more detail information.

    Using the WebSphere Development Studio for iSeries CODE to build C applications

    CODE is a suite of tools for creating source and DDS files, and managing your project. The CODE consists of CODE Designer, CODE Editor and CODE Program Generator. With CODE Program Generator you can specify compiler and link options, and submit requests to compile, bind or build on the host or local workstation. As an alternative, we can use the CODE Program Generator feature to compile, link and build C applications. The section "Building C applications Using WebSphere Development Studio for iSeries CODE" contains more detailed information.


    Running the C API Program

    Run the C API program by using the IBM i CALL command. For example,

    CALL CTEST/FOO

    runs the program FOO in the CTEST library.

    However, to make sure that the program can access the needed resources, you must:

    • Set a PATH environment variable that identifies the IBM i path for the resources that are needed by the program.
    • Run the program under the QNOTES user profile so that the program has the authorities to access the resources.


    Setting the PATH environment variable

    The PATH environment variable identifies:

    • The Domino user executable directory
      The path for this directory is /QIBM/UserData/Lotus/Notes.
    • The Domino executable directory
      The path for this directory is /QIBM/ProdData/Lotus/Notes.
    • The data directory for the Domino server
      You specify the path for the data directory when you set up the Domino server.


    With releases 6.0.3, 6.5.0 and later, Domino for IBM i supports multiple releases of Domino on the same LPAR (Logical Operating System partition), In order to support multiple releases each Domino release has its own product executable (ProdData) directory. For example, the ProdData directory for Domino 6.5.5 is /QIBM/ProdData/LOTUS/DOMINO655, the ProdData directory for Domino 9.0.1 is /QIBM/ProdData/LOTUS/DOMINO901. With multi-version capable releases, the /QIBM/ProdData/LOTUS/NOTES directory still exists, but is now a symbolic link to the primary release of Domino installed on the system.
    Applications using /QIBM/ProdData/LOTUS/NOTES in their PATH will continue to work, but only when one release of Domino is installed. If the system has multiple releases of Domino installed, the environment for these applications must have the correct Domino product executable directory in their PATH based on the Domino server against which they are running. When setting the PATH environment variable, applications that use /QIBM/ProdData/LOTUS/NOTES will fail when the application tries to reference a Domino database that is on any Domino server that is not configured to use the primary release. Applications that reference /QIBM/ProdData/LOTUS/NOTES should be corrected so that the correct information is set in the PATH environment variable regardless of the Domino server's configured release.
    Instead of hard coding the /QIBM/ProdData/LOTUS/NOTES directory when setting the PATH environment variable in applications, it is recommended that you set the Domino server environment from within a C/C++ application using this method:

    • Use the QnninSetDominoEnv API to set the Domino server environment in your application. The QnninSetDominoEnv API is passed a parameter that has the Domino server's name. The API detects the Domino server's configured release and automatically sets the PATH environment variable correctly for that Domino server's configuration, regardless of the release for which the server is configured to use.
      See Setting the Domino server environment when using Notes APIs for more details about these using these techniques.

    There are also two other methods to be aware of:

    • Use the Run Domino Command (RUNDOMCMD) CL command to launch your stand-alone application against a particular Domino server. You can submit this command to run in batch and it runs with the correct Domino server environment, under the correct user profile of QNOTES, etc. The Domino server does not need to be running for this command to work. The RUNDOMCMD command detects the Domino server's configured release and automatically sets the PATH environment variable correctly for that server's configuration regardless of the release that the Domino server is configured to use.
    • Use the Set Domino Environment (SETDOMENV) CL command to set the Domino server environment before you run the application. The SETDOMENV command detects the Domino servers configured release and automatically sets the PATH environment variable correctly. This command should not be used in an interactive job since it sets the job user profile to QNOTES.

    If you set the Domino server environment from a CL program or interactively before you run an application, you would most likely use a CL command. It is important that you do not hard code the /QIBM/ProdData/LOTUS/NOTES directory and assume that it is correct for all Domino servers. You must now consider this directory as something that can be different for each Domino server, just like the data directory for each Domino server is different.


    Running under the QNOTES user profile

    All programs must run under jobs that use the QNOTES user profile. The following processes run under the QNOTES profile when they are started:

    • The Domino server
    • Programs that are started by the Domino server as a result of ServerTasks or ServerTasksAt settings in the NOTES.INI file
    • Programs that are started as a result of Program documents in the Domino Directory
    • Hook drivers and extension manager applications that run in the Domino server
    • Programs that are started as a result of entering the Load command on the Domino server console


    If your application is not designed to run in the above processes (such as an interactive application), you must take some action to make sure you run under the QNOTES profile. Use one of the following ways to make your application run under the QNOTES profile:

    Method 1: Inside your application, swap to the QNOTES profile by using the following system APIs:

    • QSYGETPH - get profile handle
    • QWTSETP - set profile

    Following is a coding example for using the IBM i APIs to swap to the QNOTES user profile:

    / header files to include /
    #include <qsygetph.cleinc>   / Header file for the QSYGETPH /
    #include <qwtsetp.cleinc>    / Header file for the QWTSETP /
    #include <qusec.h>       / Error code structure /
    #include <qsnapi.h>      / Error code structure /

    / declarations /
    Qus_EC_t err_code;
    char      cur_user[11] = "CURRENT  ";
    char      qnotes_user[11] = "QNOTES    ";
    char      qnotes_password[11] = "    NOPWD    ";
    char      user_prof_handle[13];
    char      qnotes_prof_handle[13];

     / get the handle to the QNOTES profile /
     QSYGETPH(qnotes_user, qnotes_password, qnotes_prof_handle,  &err_code);
     if (err_code.Bytes_Available)
     {
         / Error retrieving handle to QNOTES user profile. /
         return -1;
     }
     / get the handle to the profile we are currently running under /
     QSYGETPH(cur_user, NULL, user_prof_handle, &err_code);
     if(err_code.Bytes_Available)
     {
         / Error retrieving handle to current user profile. /
         return -1;
     }
     / switch to QNOTES user profile /
     QWTSETP(qnotes_prof_handle,&err_code);
     if(err_code.Bytes_Available)
     {
         / Error switching to QNOTES user profile. /
         return -1;
     }

     /****/
       /      do C APIs or functions */
     /    ****/

     /     switch back to current user /
     QWTSETP(user_prof_handle,&err_code);
     if(err_code.Bytes_Available)
     {
         /     Error switching to current user profile. /
         return -1;
     }  


    Method 2: Use the Submit Job command (SBMJOB) to submit the job to run under QNOTES.
    The SBMJOB command has a parameter to specify the user profile that the job should run under. Following is an example for using the SBMJOB command to run the FOO program in the CTEST library:
    sbmjob cmd(call pgm(ctest/foo)) user(qnotes) cpyenvvar(    yes)

    In addition to specifying the QNOTES user profile, this command copies the environment variable to the submitted job.

    To submit a job that runs under QNOTES, the user must have USE authority to the QNOTES user profile. In general, you should avoid giving users authority to the QNOTES user profile because the QNOTES user profile has the authority to change or delete any object on your Domino server.

    Method 3: Use the rundomcmd utility.
    This utility is provided as an IBM i Command Language (CL) command called RUNDOMCMD. The RUNDOMCMD runs a given program against a server using the QNOTES user profile.

    RUNDOMCMD is available with the Domino version for IBM i product.

    The format of command is: ( text in between <> is a variable that the user must supply )
    RUNDOMCMD SERVER(<server name>) CMD(CALL PGM(<library>/<program name>) PARM(<optional parameters>)) BATCH(    no)

    For example, the following will run the C API program acls in library notesapi on the server called DOM400:
    rundomcmd server(DOM400) cmd(call pgm(notesapi/acls) parm(acllog.nsf)) batch(no)

    Starting server add-ins

    Server add-ins can be automatically started when the server starts or manually started on the server console.

    First, you need to create a symbolic link for the add-in in the /QIBM/UserData/Lotus/Notes directory. For example, for a program named MyAddin that is in the library MyLibrary specify the following Add Link (ADDLNK) command to create a symbolic link:

    ADDLNK OBJ('/QSYS.LIB/MYLIBRARY.LIB/MYADDIN.PGM')
    NEWLNK('/QIBM/UserData/Lotus/Notes/MYADDIN.PGM') LNKTYPE(    SYMBOLIC)

    Once created, the symbolic link will persist even if the program is deleted and created again.

    Addin can now be started by:

    1) add the name of the add-in to the Server Task list in the notes.ini file. When the server restarts, the add-in task will start to run.
    or
    2) on the server console, type: load myaddin. The add-in task will start to run.


    General Considerations for Using C API

    There are several requirements and restrictions for using HCL C API for IBM i:

    Restriction on APIs in exception or cancel handlers

    Do not put Domino APIs in exception or cancel handlers. The Domino APIs use locks to synchronize access to resources with the server. The result of putting Domino APIs in exception or cancel handlers could range from deadlocking the Domino server to requiring an ipl (restart) of your IBM i.

    If a Domino API is invoked in your exception or cancel handler, a deadlock could occur. If a Domino API in your application is holding a lock when an exception or cancel occurs and the handler issues another Domino API, a deadlock occurs. The effect of the deadlock depends on whether it occurs in an exception handler or a cancel handler:

    • If the deadlock occurs in an exception handler, you need to end that job and end and restart the Domino server and any Domino applications that are running on the server.
    • If the deadlock occurs in a cancel handler, you need to end that job abnormally. The ENDJOBABN command must be used to end a job abnormally.



    Using API handles

    API handles are 32 bits on IBM i. If your code depends on handles being 16 bits, change your code to accommodate the 32-bit handles.

    About ASCII-to-EBCDIC conversion

    Domino runs internally in LMBCS (Lotus Multi-Byte Character Set), and the character string representation for the C API parameters is assumed to be LMBCS. When you write C programs using EBCDIC character strings, you must use the OSTranslate API to convert between the EBCDIC strings used by the program and the LMBCS parameters passed to and from the C APIs.

    You may see the samples in the C API toolkits for IBM i, where "#pragma convert(850)" is specified and no OSTranslate is done. These C API programs usually work because the code page 850 (PC ASCII) is a subset of LMBCS. Therefore, C API programs that use code page 850, or its 7-bit ASCII subset, do not need to call OSTranslate.

    It is recommended that you specify the "#pragma convert(850)" in each source file of your application. This will free you from having to do the error-prone EBCDIC/LMBCS conversion.

    ASCII C/C++ Run Time for ASCII-EBCDIC conversion

    The "ASCII C/C++ Run Time for IBM i" provides a facility that assists in converting between ASCII and EBCDIC in applications that run on IBM i platforms. The "ASCII C/C++ Run Time" allows for ASCII applications to send EBCDIC output to the IBM i and receive EBCDIC input from the IBM i. It also enables ASCII applications to interface with many system API's, such as printf() and scanf(). You need to use such an interface layer in cases where user-written code is compiled into ASCII, such as when using the HCL C API for Notes/Domino. By using "ASCII C/C++ Run Time for IBM i", you can significantly reduce the number of changes required when porting Domino applications to the IBM i.

    "ASCII C/C++ Run Time for IBM i" includes support for only the most commonly used APIs. For APIs that are not supported, you can use some of the inconv() routines that are built into "ASCII C/C++ Run Time for IBM i".

    The "ASCII C/C++ Run Time for IBM i" is available for download at
    http://www.ibm.com/partnerworld/wps/servlet/ContentHandler/pw_com_asciirt_tips

    The installation of the ASCII C/C++ Run Time creates the library QADRT, which contains QADRTTS.SRVPGM, QADRTNTA.SRVPGM, QADRTMAIN.MODULE, H.FILE etc. The installation also creates the following directory in IFS, which contains symlnks to the headers in the file QADRT/H: /qibm/proddata/qadrt/include

    No change to the source code is required to use the ASCII C/C++ Run Time. The only modifications necessary are to the build process. The preprocessor must pick up the ASCII C/C++ Run Time include file before the standard include files, and the program must bind with either of the two service programs: QADRTTS for teraspace enabled program and QADRTNTS for non-teraspace program. Here is the modified build process.

    • When compiling C applications (CRTCMOD), ensure that the ASCII C/C++ Run Time includes are first in the search path:
    1. If the source code is an IFS file, specify INCDIR(/qibm/proddata/qadrt/include, ......)
    2. If the C source code is a member of a physical file, place the library QADRT at the top of the library list: ADDLIBLE QADRT.
    • When link C modules (CRTPGM or CRTSRVPGM), bind in the QADRTTS or QADRTNTA service program in QADST library:
    BNDSRVPGM(QADRT/QADRTTS) or BNDSRVPGM(QADRT/QADRTNTS)
    Where QADRTTS supports teraspace enabled programs and QADRTNTS supports non-teraspace programs.

      Additional considerations

      The following must also be considered when writing C API programs:
      • Be aware of the IBM i operating system (OS/400) restrictions for thread safety.
      • Avoid using global new() and delete() operators.

      Restrictions for thread safety
      The following programs run in processes (jobs) that can have multiple threads:
      • Programs that are started as a result of Program documents in the Domino Directory and any programs they call.
      • Programs that are started as a result of entering the Load command on the Domino server console and any programs they call.

      The following programs run in secondary threads:
      • Hook drivers and extension manager applications that run in the Domino server.
      • C API programs that are called by the LotusScript Declare statements in agents and any programs that are called from those C programs.
      • Programs that are specified in the LotusScript Shell statement in agents and any programs that are called by those programs.

      The IBM i has restrictions on jobs capable of running multiple threads and on the use of secondary threads. For details, see the IBM i books, System API Programming (SC41-5800) and System API Reference (SC41-5801).

      Restrictions on using global operators
      For service programs that are written in C++, do not use global new or delete operators in any add-in. If you need to override those operators, confine them to class scope. Using global new or delete operators may result in some parts of the Domino server not working correctly. This restriction is related to an IBM i restriction that there can be only one global new and delete operator per activation group.


      Building C applications Using CL Programs

      We will use the C API toolkit sample "acls" to describe how to use the toolkit makefile (CL program) to build a C application. Here, the ASCII C/C++ Run Time has been installed and the C program will be built with teraspace enabled.
      • Build the C API sample application "acls" with the source code as an IFS file /qntcsdk/samples/admin/acls/acls.c.

      1. Create source physical file QNTCSDK/ACLS:
      CRTLIB QNTCSDK
      CRTSRCPF FILE(QNTCSDK/ACLS)

      2. Create the makefile (CL program) mk_acls_i as a member of physical file QNTCSDK/ACLS:
      STRSEU SRCFILE(QNTCSDK/ACLS) SRCMBR(MK_ACLS_I) TYPE(CLP)
      Type in the following CL program and save it:

      PGM
      MONMSG MSGID(CPF2103)

      CRTCMOD MODULE(QNTCSDK/ACLS) +
      SRCSTMF('/QNTCSDK/SAMPLES/ADMIN/ACLS/ACLS.C') +
      SYSIFCOPT(*IFSIO) +
      DBGVIEW(*ALL) +
      DEFINE(OS400 UNIX) +
      TGTCCSID(37) +
      TERASPACE(*YES) +
      STGMDL(*INHERIT) +
      INCDIR('/QIBM/PRODDATA/QADRT/INCLUDE' '/QIBM/PRODDATA/LOTUS/NOTESAPI/INCLUDE')

      CRTPGM PGM(QNTCSDK/ACLS) +
      MODULE(*PGM) +
      ENTMOD(QADRT/QADRTMAIN2) +
      BNDSRVPGM(QNOTES/LIBNOTES QADRT/QADRTNTS) +
      OPTION(*DUPVAR *DUPPROC) +
      DETAIL(*BASIC)
      ENDPGM

      3. Compile the CL program:

      1) WRKMBRPDM FILE(QNTCSDK/ACLS) select the CLP "MK_ACLS_I" and apply option 14=Compile.
      or
      2) CRTCLPGM PGM(QNTCSDK/MK_ACLS_I) SRCFILE(QNTCSDK/ACLS)

      4. Compile and link the C API sample "acls":
      CALL QNTCSDK/MK_ACLS_I
      As a result, the command creates a C program acls (*PGM) in the library QNTCSDK.

      • Build the C API sample application "acls" with the source code as a member of physical file qntcsdk/acls(*FILE)

      1. Create the makefile (CL program) mk_acls_p as a member of physical file QNTCSDK/ACLS:
      STRSEU SRCFILE(QNTCSDK/ACLS) SRCMBR(MK_ACLS_P) TYPE(CLP)
      Type in the following CL program and save it:

      PGM
      MONMSG MSGID(CPF2103)

      ADDLIBLE QNOTESAPI
      ADDLIBLE QNTCSDK
      CHGSYSLIBL QADRT

      CRTCMOD MODULE(QNTCSDK/ACLS) +
      SRCFILE(QNTCSDK/ACLS) +
      SYSIFCOPT(*IFSIO) +
      DBGVIEW(*ALL) +
      DEFINE(OS400 UNIX) +
      TERASPACE(*YES) +
      STGMDL(*INHERIT)

      CRTPGM PGM(QNTCSDK/ACLS) +
      MODULE(*PGM) +
      ENTMOD(QADRT/QADRTMAIN2) +
      BNDSRVPGM(QNOTES/LIBNOTES QADRT/QADRTNTS) +
      OPTION(*DUPVAR *DUPPROC) +
      DETAIL(*BASIC)

      ENDPGM

      2. Compile the CL program:
      1) WRKMBRPDM FILE(QNTCSDK/ACLS) select the CLP "MK_ACLS_P" and apply option 14=Compile.
      or
      2) CRTCLPGM PGM(QNTCSDK/MK_ACLS_P) SRCFILE(QNTCSDK/ACLS)

      3. Compile and link the CAPI sample "acls":
      CALL QNTCSDK/MK_ACLS_P
      As a result, the command creates a C program acls (*PGM) in the library QNTCSDK>


      Building C applications Using WebSphere Development Studio for iSeries CODE

      We will build a C program for the C API toolkit sample "acls" with the source code as an IFS file /qntcsdk/samples/admin/acls/acls.c.

      Start the CODE Program Generator. This is typically in the Start Menu under Programs > IBM WebSphere Development Studio Client for iSeries > IBM CODE.
      • Compile the C API sample "acls" .

      1. From the Server pull-down menu, choose the server that contains the source code to be compiled.

      2. In the Label menu, choose CRTCMOD. After your selection, you should see "CRTCMOD" in the Command field, and "ILE C Compile" in the Associated Profile field. Also, the field name "Source" is displayed.

      3. In the Source field, type in the full path name of the source file acls.c: "/qntcsdk/samples/admin/acls/acls.c".

      4. Click on the Options... button. A window named "Create C Module Compiler Options" should pop up. Now we specify the compiler options:

      a. Under the Module tab, enter "acls" in the Module field. In the Library field, enter "qntcsdk". Select the Source stream file checkbox. You should see these options appear in the generated command at the bottom of the window.

      b. Under the Generation tab, select "*INHERIT" for Storage model and "*YES" for the Teraspace storages addresses. Leave everything else as the default.

      c. Under the Debug tab, select "*ALL" for Debugger View.

      d. Under the Other tab:
      • select "*IFSIO" for the Integrated File Systems options.
      • For Target CCSID, type in "37".
      • For the Include Directory, type in "/qibm/proddata/qadrt/include" and click Add. Then type in "/qibm/proddata/lotus/notesapi/include" and click Add again.
      • For Define preprocessor macros", add "OS400" and "UNIX".

      5. Check to see that the resulting command at the bottom of the window is:

      CRTCMOD MODULE(qntcsdk/acls) SRCSTMF('&I') TEXT(*SRCMBRTXT) OPTION(*EVENTF) STGMDL(*INHERIT) TERASPACE(*YES) DBGVIEW(*ALL) SYSIFCOPT(*IFSIO) TGTCCSID(37) INCDIR('/qibm/proddata/qadrt/include' '/qibm/proddata/lotus/notesapi/include') DEFINE(OS400 UNIX)

      Click OK. The pop-up window should go away.

      6. Click Submit. You should get a message saying the command CRTCMOD has completed successfully. If you check on the IBM i, you will see the module ACLS created in library QNTCSDK.
      • Link the module QNTCSDK/ACLS into a program.

      1. From the Server pull-down menu, choose the server that contains the module to be linked in to a program.

      2. In the Label menu, choose CRTPGM. After your selection, you should see "CRTPGM" in the Command field, and "ILE Bind" in the Associated Profile field. Also, the field name "Program" is displayed.

      3. In the Program field, type in the program name in "library-name/program-name" format: "qntcsdk/acls".

      4. Click on the Options... button. A window named "Create Program Options" should pop up. Now we specify the bind options:

      a. Under the Create Program tab, select "*PGM" for Module List". In the Entry Module field, enter "qadrtmain2". In the Entry Library field, enter "qadrt". Leave everything else as the default.

      b. Under the Bind Service Programs tab: for Bind service programs, add "qnotes/libnotes" and "qadrt/qadrtts".

      c. Under the Other tab:
      • Select "*DUPPROC" for the Duplicate procedure names
      • Select "*DUPVAR" for the Duplicate variable names
      • Select "*BASIC" for the Listing detail field

      5. Check to see that the resulting command at the bottom of the window is:

      CRTPGM PGM(&L/&F) MODULE(*PGM) ENTMOD(qadrt/qadrtmain2) BNDSRVPGM(qnotes/libnotes qadrt/qadrtts) OPTION(*DUPPROC *DUPVAR) DETAIL(*BASIC)

      Click OK. The pop-up window should go away.

      6. Click Submit. You should get a message saying the command CRTPGM has completed successfully. If you check on the IBM i, you will see the *PGM ACLS created in library QNTCSDK. ---