# Building the Program

Supported Compilers
Supported Platforms
API Libraries
Naming Conventions
Including API Files in Your Program
Building a Program on UNIX

## Supported Compilers

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

Windows XP | Microsoft Visual Basic 6.0 Microsoft Visual C++ 6.0
Windows 2000 | Microsoft Visual Basic 6.0 Microsoft Visual C++ 6.0
HP-UX | Hewlett Packard C compiler for HP-UX Version 10.01 or later
AIX | IBM C compiler for AIX Version 3.1.2 or later
Solaris | Solaris C/C++ compiler Version 3.0.1 or later

Note: The Essbase API does not support VB.NET

## Supported Platforms

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

Windows | Windows XP, Windows 2000 sp 3
HP-UX | Version 11.0 / 11i
AIX | Version 5L (V5.1/5.2)
Solaris | Version 8/9 (Sun OS 5.8/5.9)

## 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:

Format and Parts of Name | Example
InterfaceVerbObject | Interface
Programming interface | EssCreateGroup
Ess = C API | EssUpdate = C API
Esb = Visual Basic API | EsbUpdate = Visual Basic API
EssOtl = C Outline API | EssOtlOpenOutline = C Outline API
EsbOtl = Visual Basic Outline API | EsbOtlOpenOutline = Visual Basic Outline API
EssG = C Grid API | EssGSetGridOption = C Grid API
Verb Action to perform, such as "Report" | EssReportFile (no verb) sends the report
Object Object of action, such as "Group" | EssUpdate (no Object) acts on the current object

Data Structure Names

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:

Format and Parts of Name | Example
Interface_Name_Type | Interface
Programming interface, either ESS or ESB | EssCreateGroup
Verb Data type, such as STR (string) | ESB_BOOL_T = Visual Basic typdef for Boolean
Type Type of structure, either T (typedef definition) or M (macro) | ESS_STR_T = C language typedef for String

C API Constant Names

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:

Format and Parts of | Example
Structure Data type or structure field, such as "Boolean" | ESS_Structure_Value
Value Type of value the constant stores | ESS_STS_NOERROR could store a value for the ESS_STS_T data type

## 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. Make sure to include the appropriate Essbase API library in your link process.

The following pragma statements will ensure byte alignment and should be placed in the INCLUDE section of the program:

    #ifdef WINNT
    #pragma pack (1)
    #endif
    #include
    #include
    #pragma pack ()
    #endif

### 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 `FreeFunc`fields 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
          -l:libessapiu -l:libessglobu -l:libesssm -l:libesssdu'

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

The `libessapiu.sl` library automatically includes `libessnetu.sl`, `libessotlu.sl`, `libessshru.sl`, and `libessutlu.sl`, so you need to specify only `libessapiu.sl` (or `-lessapiu`) 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.

#### Sample AIX Build Process

This example build a shared lib named libessldapS.a on AIX.

The export file, `aixldap.exp`, contains the symbols which will be exported in the lib; while the import file, `essldap.imp`, contains symbols which are in other libs which are not on the link line.

    cc_r -c -DAIX -DAD_UNIX -DAD_CURRENCY_ON -DAD_ESM_SEM_OBJECT -DAD_42B -DAD_TMG_O
    RION -DAD_ESM_ORION -g -DUNISCAPE -DAIX43 -DAD_CALF -DECLIPSE_ATTRIBUTE -DAD_STR
    UCT_ALIGN4 -DEACC -DLL_APP_STARTUP   -I. -I/usr/include
    -I/home/yzhou/globalc/include -I../lum/include/aix
    -L/home/yzhou/globalc/lib /lib/crt0_r.o
    -lpthreads -lm -lc_r -lbsd -lglobalcS -o
    essldap.o essldap.c
    ld -bM:SRE -T512 -H512 -bnoentry -lm -lc_r -lpthreads -o libessldapS.a
    essldap.o -bE:aixldap.exp -bI:essldap.imp

The linker option flags are defined as follows:

- -T512 : starting address of text section is 512. The default is 0. This is just for the loading performance and is not needed to produce a shared lib.
- -H512: aligns the text, data and loader sections of the output file so that each section begins on a file offset that is a multiple of 512. Again this is not needed to produce a shared lib.
- -bM:SRE: This is the flag used to produce a shared lib.

### 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.

For Solaris, your makefile should include all of these libraries, in this order:

1. esstest.out
2. posix4
3. socket
4. nsl
5. pthread
6. globalc
7. essapiu
8. essotlu
9. essglobu
10. essnetu
11. essshru
12. essutlu
13. esssdu
14. esssecu

#### 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. Static libraries are not available for all libraries. For a listing of files supplied with Essbase API for Solaris, see API Libraries.

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 -I$ARBORPATH/api/include -L$ARBORPATH/api/lib -D_REENTRANT \
    -o esstest.out -lm -ldl -lposix4 -lsocket -lnsl -lpthread -lglobalc \
    -lessapiu -lessotlu -lessglobu  -lessnetu -lessshru -lessutlu -lesssdu -lesssecu

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 -I$ARBORPATH/api/include -L$ARBORPATH/api/lib -D_REENTRANT \
    -o esstest.out -lm -ldl -lposix4 -lsocket -lnsl -lpthread -lglobalc \
    -lessapiu -lessotlu -lessglobu -lessnetu -lessshru -lessutlu -lesssdu -lesssecu

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

©2004 Hyperion Solutions Corporation. All Rights Reserved. http://www.hyperion.com