Using the Application Program Interface


Chapter 2. Using the API Sample Application

The API package that you receive includes a sample application that demonstrates the API function calls in context. Install the sample application and review the source code to understand how you can use the function calls. Select one of two sample application packages: the interactive, single-threaded application package (dapi*), or the multi-threaded application package (callmt*).


Building the Sample Application

When you build the sample application, the procedure to follow depends on the platform on which you run.

Windows NT and Windows 98 Platforms

Note:For Windows NT applications that are built with the Version 2 API, replace the current adsm32.dll with the adsm32.dll and adsmv3.dll. For new applications, build with, and use the adsmv3.dll.

We recommend that you use dynamic loading. See dynaload.c and implementation in the sample code. For Windows NT and Windows 98 platforms, the files listed in Table 4 comprise the source files that you need to build the sample application. This sample application is included in the API package.

Table 4. Files Needed to Build the Windows NT and 98 API Sample Application

File Names
Description
api.txt
Readme file
dapismp
API sample program

blkhook.def
blkhook.c
blkhook.mak



Definition file for blocking hook single-threaded DLL
Sample source code for blocking function
Makefile


tsmapi.dll
adsmv3.dll
adsm32.dll
blkhook.dll


API DLLs

dsmrc.h
dsmapitd.h
dsmapips.h
dsmapifp.h
dsmapidl.h



Return codes header file
Common type definitions header file
Operating system-specific type definitions header file
Function prototype header file
Dynamically loaded function prototype header file


dapidata.h
dapint64.h
dapitype.h
dapiutil.h


Source code header files

dsmapi.lib



Implicit library


dapibkup.c
dapiinit.c
dapint64.c
dapipref.c
dapiproc.c
dapiproc.h


dapipw.c
dapiqry.c
dapirc.c
dapismp.c
dapiutil.c
dynaload.c

Source code files for dapismp.exe

dapismp.mak



Visual C++ makefile for API sample program


callmt1.c
callmt2.c
makemt.mak



Multi-threaded sample files
Multi-threaded sample files
Makefiles to build multi-threaded samples for your platform.

In addition, the API\OBJ directory contains the API sample program object files, the API\SAMPRUN directory contains the sample program, and the dapismp sample program contains the execution directory.

The source code (blkhook.c) and makefile (blkhook.mak) for a blocking function are included along with the sample API program, dapismp, for applications using non-threaded graphical user interfaces (GUI) that must switch out from their message loops when blocked. The DLLs (tsmapi.dll, adsm32.dll, blkhook.dll, and adsmv3.dll) are all 32-bit DLLs.

Use the Microsoft Visual C++ Level 6.0 compiler and the makefile, dapismp.mak, to compile the API sample application, dapismp. It might be necessary to adjust the makefiles (specifically, the library or the Include directories) to fit your environment. To run the sample application, enter dapismp from the api\samprun directory.

OS/2 Platform

Note:Applications that are built with the Version 2 DLL will not run with the adsmv3.dll because of memory model incompatibility. Build your OS/2 applications again using adsmv3.dll and adsmv3.lib files.

The files listed in Table 5 comprise the source files and other files that you need to build the sample application included with the API package.

Table 5. Files Available for Building the OS/2 API Sample Application

File Names
Description
readme.api
Readme file
dapismp.mak
Makefile for dapismp.exe

dapibkup.c
dapidata.h
dapiinit.c
dapint64.c
dapint64.h
dapipref.c
dapiproc.c
dapiproc.h


dapipw.c
dapiqry.c
dapirc.c
dapismp.c
dapitype.h
dapiutil.c
dapiutil.h

Source code files for dapismp.exe

dsmrc.h
dsmapitd.h
dsmapips.h
dsmapifp.h



Return codes header file
Common type definitions header file
Operating system-specific type definitions header file
Function prototype header file


adsmv3.dll
tsmapi.dll


API DLL

adsmv3.lib
tsmapi


Implicit library

callmt1.c
callmt2.c
makemt.mak



Multi-threaded sample files
Multi-threaded sample files
Makefiles to build the multi-threaded samples for your platform

It might be necessary to adjust the dapismp.mak file to fit your environment (specifically, the library or the Include directories). The DLL (adsmv3.dll) is a 32-bit DLL, and the makefile assumes that you are using VisualAge C++ 3.0 or a higher level.

UNIX Platform

The files listed in Table 6 comprise the source files and other files that you need to build the sample application that is included with the API package.

Table 6. Files Available for Building the UNIX API Sample Application

File Names
Description
readme.api
Readme file

dsmrc.h
dsmapitd.h
dsmapips.h
dsmapifp.h



Return codes header file
Common type definitions header file
Operating system-specific type definitions header file
Function prototype header file


dapibkup.c
dapidata.h
dapiinit.c
dapint64.h
dapint64.c
dapipref.c
dapiproc.c
dapiproc.h


dapipw.c
dapiqry.c
dapirc.c
dapismp.c
dapitype.h
dapiutil.h
dapiutil.c

Modules for the command line-driven sample application
makeapi.xxx
Makefile to build dapismp for your platform. The xxx indicates the platform.

caller1.c
caller2.c


Simple example modules

callmt1.c
callmt2.c


Multi-threaded sample files

For specific install and build instructions, see the README.API for your platform and follow these steps:

  1. After you build the sample, set up your environment variables, especially DSMI_DIR, and your options files. See Understanding Configuration Files and Options Files and Tivoli Storage Manager Installing the Clients for more information.

  2. Log on as root the first time for password registration.

  3. Run dapismp to start the sample application.

NetWare Platform

The files listed in Table 7 comprise the source files and other files that you need to build the sample application that is included with the API package.

Table 7. Files Available for Building the Novell NetWare API Sample Application

File Names
Description
readme.api
Readme file

dsmapifp.h
dsmapitd.h
dsmapips.h
dsmrc.h



Function prototype header file
Common type definitions header file
Operating system-specific type definitions header file
Return codes header file

dsmapi.nlm
API loadable module

dapibkup.c
dapidata.h
dapiinit.c
dapipref.c
dapiproc.c
dapiproc.h
dapipw.c
dapiqry.c
dapirc.c


dapismp.c
dapismp.lnk
dapismp.wat
dapismp.nlm
dapitype.h
dapinwut.c
dapiutil.c
dapiutil.h

Source code files for a sample application that demonstrates the use of the major API functions

callmt1.c
callmt2.c
callmt1.wat
callmt2.wat



Multi-threaded sample files


Makefiles to build multi-threaded samples for your platform

Follow these steps to compile the sample application and test the installation:

  1. When your makefile and WATCOM compiler are ready, enter:
       wmake /f dapismp.wat
    

    Compiler messages display until the compile completes.

  2. Copy dapismp.nlm to the NetWare server.
    Note:You must have the following files on your NetWare server before you run the sample application, dapismp.nlm:
    dsm.smp
    dscameng.txt
    dsmapi.nlm
    acpwsrvs.nlm
    acpwtcps.nlm
    acpwsaas.nlm
    dapismp.nlm

  3. Copy dsm.smp to dsm.opt.

  4. Edit dsm.opt and enter values for the commmethod and nodename options.

  5. Enter values for the options that relate to the specific communication method you are using.

  6. At the NetWare console enter:
       search add sys:\adsm\api
    

  7. To start the sample application and run dapismp, enter:
       load dapismp
    

AS/400 Platform

The files listed in Table 8 comprise the source files and other files that you need to build the sample application that is included with the API package.

Table 8. Files Available for Building the AS/400 API Sample Application

File Names
Description
CRTAPISMP
Source for a CL program to create the sample application

dsmrc.h
dsmapitd.h
dsmapips.h
dsmapifp.h



Return codes header file
Common type definitions header file
Operating system-specific type definitions header file
Function prototype header file


dapibkup.c
dapidata.h
dapiinit.c
dapint64.h
dapint64.c
dapipref.c
dapiproc.c
dapiproc.h


dapipw.c
dapiqry.c
dapirc.c
dapismp.c
dapitype.h
dapiutil.h
dapiutil.c

Source code files for a sample application that demonstrates the use of the primary API functions

The .c files are members of the file, QANSAPI/QCSRC, and the .h files are members of the file, QANSAPI/H. The CL source is contained in the file, QANSAPI/QCLSRC.

Follow these steps to compile the sample application and test the installation:

  1. To compile the CL program, QANSAPI/QCLSRC(CRTAPISMP), enter:
       CRTCLPGM PGM(QANSAPI/CRTAPISMP) SRCFILE(QANSAPI/QCLSRC)
    

  2. To compile the source code for the sample application, enter the CRTCMOD command for each member in QANSAPI/QCSRC. For example:
       CRTCMOD MODULE(QANSAPI/DAPISMP) SRCFILE(QANSAPI/QCSRC) OUTPUT(*PRINT)
    

  3. Start CRTAPISMP to create the sample application and bind it to the API service program.
       CALL CRTAPISMP ( target_library QANSAPI )
    

  4. Ensure that target_library is in your library list.

  5. Copy QANSAPI/QAANSDOC(APIOPTSMP) to library/QOPTADSM(APIOPT), where library is in your library list.

  6. Edit library/QOPTADSM(APIOPT) and enter values for the commmethod and nodename options. Enter values for the options that relate to the specific communication method you are using.

  7. To run dapismp, enter:
       call dapismp
    

Running the Sample Application

After you enter dapismp to start the sample application, follow the instructions that display on your screen. When you run the application, perform the following:


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]