3. Ultra Messaging® Programming Quick Start

The C programs below contain the minimum code and supporting material. Their purpose is to verify that the user's build and run-time environments are set up correctly. They also give a basic introduction to the Ultra Messaging® API.

We also have equivalent Java and C# programs available in source form. See MinSrc.java and MinRcv.java or MinSrc.cs and MinRcv.cs We also have an example of how application callbacks are coded in C++ programs. See minrcv.cpp (Most browsers let you right-click on the link and use the save link target function, or some variation.)

Note that these programs do not allow the user to override any of the default configuration values. As a result, operation is fixed according to the normal LBM defaults; for example TCP is the transport protocol, topic resolution is performed using multicast, etc. See the Ultra Messaging Configuration Guide.

The Ultra Messaging Examples page provides a much richer set of source files that use a wide variety of features. However, those programs double as performance testing tools, so they tend to be more complex than just demonstrating the features. We recommend to first build and run these minimal examples.

This source code example is provided by Informatica for educational and evaluation purposes only.

Error handling in these programs is primitive. A production program would want to have better error handling, but for the purposes of a minimal example, it would just be a distraction. Also, a production program would want to support a configuration file to override default values on options.

When building on Windows, the following notes are applicable.

1. Make sure the preprocessor variable "WIN32" is defined. From Visual Studio 6, navigate: "Project"->"Settings...", "C/C++", "Category:General", "Preprocessor definitions:".

2. Add C:\Program Files\29West\<VERS>\Win2k-i386\include\lbm as an additional include directory (where "<VERS>" is the appropriate version identifier). From Visual Studio 6, navigate: "Project"->"Settings...", "C/C++", "Category:Preprocessor", "Additional include directories:"

3. Add lbm.lib and wsock32.lib as Object/library modules. From Visual Studio 6, navigate: "Project"->"Settings...", "Link", "Category:General", "Object/library modules:"

4. Add C:\Program Files\29West\VERS\Win2k-i386\lib as an additional library path (where VERS is the appropriate version identifier). From Visual Studio 6, navigate: "Project"->"Settings...", "Link", "Category:Input", "Additional library path:"

5. The install procedure should already have added the LBM bin directory to the Windows PATH. This is necessary so that lbm.dll can be found when a program is run. To modify the Windows PATH from Windows XP, navigate: "right-click My Computer"->"properties", "Advanced", "Environment variables", "System variables:Path", "Edit"

When building on Unix, the following notes are applicable.

1. Sample build command:

   cc -I$HOME/lbm/<VERS>/<PLATFORM>/include
      -L$HOME/lbm/<VERS>/<PLATFORM>/lib -llbm -lm -o min_src min_src.c
   

   (This should be all one line.)
   
   

2. The appropriate library search path should be updated to include the Ultra Messaging lib/ directory. For example, on Linux:

   LD_LIBRARY_PATH="$HOME/lbm/<VERS>/<PLATFORM>/lib:$LD_LIBRARY_PATH"
   export LD_LIBRARY_PATH
   

   (For other flavors of Unix, see http://bhami.com/rosetta.html.) Alternatively, the shared library can be copied from the LBM lib/ directory to a directory which is already in the library search path.
   
   

/*file: minsrc.c - minimal source (sender) program.
 *
 * Copyright (c) 2005-2014 Informatica Corporation. All Rights Reserved.
 * Permission is granted to licensees to use
 * or alter this software for any purpose, including commercial applications,
 * according to the terms laid out in the Software License Agreement.
 */

#include <stdio.h>

#if defined(_MSC_VER)
/* Windows-only includes */
#include <winsock2.h>
#define SLEEP(s) Sleep((s)*1000)
#else
/* Unix-only includes */
#include <stdlib.h>
#include <unistd.h>
#define SLEEP(s) sleep(s)
#endif

#include <lbm/lbm.h>

main()
{
    lbm_context_t *ctx;    /* pointer to context object */
    lbm_topic_t *topic;    /* pointer to topic object */
    lbm_src_t *src;        /* pointer to source (sender) object */
    int err;               /* return status of lbm functions (true=error) */

#if defined(_MSC_VER)
    /* windows-specific code */
    WSADATA wsadata;
    int wsStat = WSAStartup(MAKEWORD(2,2), &wsadata);
    if (wsStat != 0)
    {
        printf("line %d: wsStat=%d\n",__LINE__,wsStat);
        exit(1);
    }
#endif

    err = lbm_context_create(&ctx, NULL, NULL, NULL);   
    if (err)
    {
        printf("line %d: %s\n", __LINE__, lbm_errmsg());
        exit(1);
    }

    err = lbm_src_topic_alloc(&topic, ctx, "Greeting", NULL);   
    if (err)
    {
        printf("line %d: %s\n", __LINE__, lbm_errmsg());
        exit(1);
    }

    err = lbm_src_create(&src, ctx, topic, NULL, NULL, NULL);   
    if (err)
    {
        printf("line %d: %s\n", __LINE__, lbm_errmsg());
        exit(1);
    }

    SLEEP(3);   

    err = lbm_src_send(src, "Hello!", 6, LBM_MSG_FLUSH | LBM_SRC_BLOCK);   
    if (err)
    {
        printf("line %d: %s\n", __LINE__, lbm_errmsg());
        exit(1);
    }

    /* Finished all sending to this topic, delete the source object. */
    SLEEP(2);   
    lbm_src_delete(src);

    /* Do not need to delete the topic object - LBM keeps track of topic
     * objects and deletes them as-needed.  */

    /* Finished with all LBM functions, delete the context object. */
    lbm_context_delete(ctx);

#if defined(_MSC_VER)
    WSACleanup();
#endif
}  /* main */

/*file: minrcv.c - minimal receiver program.
 *
 * Copyright (c) 2005-2014 Informatica Corporation. All Rights Reserved.
 * Permission is granted to licensees to use
 * or alter this software for any purpose, including commercial applications,
 * according to the terms laid out in the Software License Agreement.
 */

#include <stdio.h>

#if defined(_MSC_VER)
/* Windows-only includes */
#include <winsock2.h>
#define SLEEP(s) Sleep((s)*1000)
#else
/* Unix-only includes */
#include <stdlib.h>
#include <unistd.h>
#define SLEEP(s) sleep(s)
#endif

#include <lbm/lbm.h>

/*
 * A global variable is used to communicate from the receiver callback to
 * the main application thread.
 */
int msgs_rcvd = 0;

int app_rcv_callback(lbm_rcv_t *rcv, lbm_msg_t *msg, void *clientd)   
{
    /* There are several different events that can cause the receiver callback
     * to be called.  Decode the event that caused this.  */
    switch (msg->type)
    {
    case LBM_MSG_DATA:    /* a received message */
        printf("Received %d bytes on topic %s: '%.*s'\n",   
               msg->len, msg->topic_name, msg->len, msg->data);

        /* Tell main thread that we've received our message. */
        ++ msgs_rcvd;
        break;

    case LBM_MSG_BOS:
    printf("[%s][%s], Beginning of Transport Session\n", msg->topic_name, msg->source);
    break;

    case LBM_MSG_EOS:
    printf("[%s][%s], End of Transport Session\n", msg->topic_name, msg->source);
    break;
    
    default:    /* unexpected receiver event */
        printf("Received lbm_msg_t type %x [%s][%s]\n", msg->type, msg->topic_name, msg->source);
        break;
    }  /* switch msg->type */

    return 0;
}  /* app_rcv_callback */


main()
{
    lbm_context_t *ctx;    /* pointer to context object */
    lbm_topic_t *topic;    /* pointer to topic object */
    lbm_rcv_t *rcv;        /* pointer to receiver object */
    int err;               /* return status of lbm functions (true=error) */

#if defined(_MSC_VER)
    /* windows-specific code */
    WSADATA wsadata;
    int wsStat = WSAStartup(MAKEWORD(2,2), &wsadata);
    if (wsStat != 0)
    {
        printf("line %d: wsStat=%d\n",__LINE__,wsStat);
        exit(1);
    }
#endif

    err = lbm_context_create(&ctx, NULL, NULL, NULL);   
    if (err)
    {
        printf("line %d: %s\n", __LINE__, lbm_errmsg());
        exit(1);
    }

    err = lbm_rcv_topic_lookup(&topic, ctx, "Greeting", NULL);   
    if (err)
    {
        printf("line %d: %s\n", __LINE__, lbm_errmsg());
        exit(1);
    }

    err = lbm_rcv_create(&rcv, ctx, topic, app_rcv_callback, NULL, NULL);   
    if (err)
    {
        printf("line %d: %s\n", __LINE__, lbm_errmsg());
        exit(1);
    }

    while (msgs_rcvd == 0)
        SLEEP(1);

    /* Finished all receiving from this topic, delete the receiver object. */
    lbm_rcv_delete(rcv);

    /* Do not need to delete the topic object - LBM keeps track of topic
     * objects and deletes them as-needed.  */

    /* Finished with all LBM functions, delete the context object. */
    lbm_context_delete(ctx);

#if defined(_MSC_VER)
    WSACleanup();
#endif
}  /* main */