Building the Program

Supported Compilers

The current release of the Essbase API supports the following compilers:

Supported Platforms

The current release of the Essbase API supports the following platforms:

Naming Conventions

The Essbase API uses its own naming conventions for functions, constants, and data types. To ensure compatibility with future releases of the API, use these constants and data type declarations in your program.

Function Names

An Essbase API function name describes the action the function performs. A name is made of a prefix that represents the interface, followed by one or more words or fragments that describes the action and its object. The parts of the name are not separated by spaces but are capitalized for easier interpretation. Names follow this format:

An Essbase API data structure name begins with a prefix that represents the interface, includes a word or fragment that describes the structure, and ends with a suffix indicating either typedef definition or macro. Underscore characters separate the parts of the name. Names follow this format:

An Essbase C API constant name begins with the prefix ESS that represents the C interface, includes a word that describes the constant, and has no suffix. Underscore characters separate the parts of the name. Names follow this format:

Including API Files in Your Program

To use the Essbase API in your program, you must include the file that contains API definitions. This section describes the files you need for the C or Visual Basic API.

Note: See API Libraries for information on the Essbase files you need to distribute with your completed applications.

API Files for C Programs

To use the Essbase API in a C program, you must include the API header definitions file (ESSAPI.H) in the appropriate source modules. Always include this file after any C run-time library header files. If you are programming in the Windows environment, place ESSAPI.H after the Windows include file WINDOWS.H.

C Compiler Options

If you are using an encapsulated C development environment, such as Microsoft Visual C++, you should check the compiler and linker options carefully to ensure that the Essbase API will work correctly. In particular, you must ensure that structure fields are byte-aligned, and that the correct libraries are used (using the large memory model on Intel X86 platforms). In addition, don't forget to include the appropriate Essbase API library in your link process.

API Files for Visual Basic Program

To use the Essbase API in a Visual Basic program, you must include the ESB32.BAS file for 32-bit programs. This file contains the constant definitions and declarations for all Essbase functions. You can use the file as shipped, or customize it to meet the needs of your application.

To use ESB32.BAS,

1. Open a project.
2. Choose File | Add File , and specify ESSBASE\API\INCLUDE\ESB32.BAS

Building an Application Program on UNIX

• HP-UX Information
• AIX Information
• Solaris Information

The Essbase API is supported on the HP-UX, AIX, and Solaris platforms. This section provides the following information needed to compile an application program using the Essbase API on UNIX:

• Default memory allocation routines
• Supplied files
• Sample make files for compiling

Memory Allocation

The Essbase API for UNIX uses the standard C library memory allocation functions, malloc(), realloc(), and free(), as the default memory functions. You use the default memory functions if you pass NULLs in the AllocFunc, ReallocFunc, and FreeFuncfields of the ESS_INIT_T initialization structure. See Using Memory in C Programs for more information.

UNIX Support

EssAutoLogin() is not supported in the UNIX versions of the Essbase API.

Be sure to follow UNIX file-naming conventions when using UNIX versions of the Essbase API.

HP-UX Information

This section provides information specific to HP-UX.

HP-UX Supplied Files

For a listing of files supplied with Essbase API for HP-UX, see API Libraries.

All .sl files should be located in a directory specified in the LPATH search path. For example, the LPATH variable can be set to: .:/lib:/usr/lib:$ARBORPATH/lib

Alternatively, you can use the -L flag to tell the linker where to locate the shared library:
$(CC) file1.o file2.o -L /essbase/lib -lessapi \ $(LIBS) -o

All libess*.sl files are linked with the +s flag which allows you to use the SHLIB_PATH search path to locate the shared library when the linked program is run. For further information about LPATH and SHLIB_PATH, please check HP-UX programming documentation.

Linking Programs on HP-UX

With the Hyperion Essbase 6.0 release, you must use aCC to link your program to maintain compatibility with the third party libraries used with Essbase. If you are using Hyperion Essbase 5.0.2 as the server version, you should continue to use the ld compiler for linking.

HP-UX Make File Sample

With HP-UX, you can run Essbase using dynamic or static libraries. This section provides sample make files for both.

Dynamic Libraries

The LPATH environment variable must be properly set before you execute a make file. For information on setting the LPATH variable, see the Hyperion Essbase Installation Guide.

The following sample shows a make file for HP-UX if you are using dynamic libraries. This example compiles and links the first sample program.

# Include File Paths
INCS='-I/home/hyperion/essbase/api/include -I/usr/include'

# Compiler Flags
CFLAGS='-g -Ae -D_REENTRANT'

# Library files
LIBS='-lpthread -lndbm -ldld -lm
      -L/home/hyperion/essbase/api/lib
      -lessapi -lglobalc -lesssm -lesssd' 

# Compile and link commands
cc ${INCS} ${CFLAGS} -c cs1.c 
aCC -Wl,+s cs1.o ${LIBS} -ocs1 $@

The libessapi.sl library automatically includes libessnet.sl, libessotl.sl, libessshr.sl, and libessutl.sl, so you need to specify only libessapi.sl (or -lessapi) when linking. However, all .sl files must be available at run time.

Static Libraries

The following sample shows a make file for HP-UX if you are using static libraries. This example compiles and links the first sample program.

# Include File Paths
INCS='-I/home/hyperion/essbase/api/include -I/usr/include'

# Compiler Flags
CFLAGS='-g -Ae -D_REENTRANT'

# Library files
LIBS='-lpthread -lndbm -lrt -lm
     -L/home/hyperion/essbase/api/lib
     -l:libessapi.a -l:libessnet.a -l:libesssd.a
     -l:libessshr.a -l:libessutl.a -l:libessotl.a
     -l:libglobalc.a'

# Compile and link commands
cc ${INCS} ${CFLAGS} -c cs1.c 
aCC -Wl,+s cs1.o ${LIBS} -ocs1 $@

The .a libraries are static. You need to specify all of them when linking. However, they don't need to be available at run time.

Note: Use the -Wl and -aarchive parameters only if your dynamic and static libraries are stored in the same directory.

AIX Information

This section provides AIX-specific information.

AIX Supplied Files

For a listing of files supplied with Essbase API for AIX, see API Libraries.

Solaris Information

This section provides Solaris-specific information.

Solaris Supplied Files

For a listing of files supplied with Essbase API for Solaris, see API Libraries.

Note: The dynamic libraries for the Solaris API are delivered with names of the form *.so.1. When compiling, Solaris looks for filenames of the form *.so. You can rename the *.so.1 files to *.so, or establish symbolic links with names of the form *.so and link them to the *.so.1 library files.

Compiling and Linking Solaris API Programs

You can link Solaris API programs using dynamic or shared libraries.

• The .so libraries are dynamic. You must specify all of them when linking, and they must be available at run time.
• The .a libraries are static. You need to specify all of them when linking. However, they don't need to be available at run time.

1. Update the LD_LIBRARY_PATH setting to include the Essbase directory you are using for your API (for example, /home/hyperion/essbase). In the C shell environment, you might add the following:

   setenv LD_LIBRARY_PATH "/usr/openwin/lib:/usr/lib:$ARBORPATH"
   

2. Before you link your API program, verify the existence and location of the library files by using the ldd ESSSVR command. To get a list of Essbase API library files and their locations, enter

   ldd ESSSVR
   

The following sample shows a command line to compile and link a Solaris API program:

cc sample.c -D_REENTRANT -o sample -lm -ldl -lsocket -lnsl -lpthread \
-L/home/hyperion/essbase/api/lib \
-lessapi -lessnet -lessotl -lessshr -lesssql -lessutl 

By default, the linking program uses shared libraries. If you want to link static libraries, use the -B static flag on the cc command. For example:

cc -B static sample.c -D_REENTRANT -o sample -lm -ldl -lsocket -lnsl -lpthread \
-L/home/hyperion/essbase/api/lib \
-lessapi -lessnet -lessotl -lessshr -lessutl

Although shared libraries are used by default, the cc command also accepts -B dynamic as a parameter to specify dynamic libraries.