Introduction

 

About This Guide and FML

This chapter describes the contents of the guide, how the Field Manipulation Language (FML) fits into the BEA MessageQ system, and how you might get the most out of the guide. We assume that you are familiar with the BEA MessageQ system.

What Is FML?

FML is a set of C language functions for defining and manipulating storage structures called fielded buffers that contain attribute-value pairs in fields. The attribute is the field's identifier, and the associated value represents the field's data content.

Fielded buffers provide an excellent structure for communicating parameterized data between cooperating processes, by providing named access to a set of related fields. Programs that need to communicate with other processes can use the FML software to provide access to fields without concerning themselves with the structures that contain them.

The original FML allowed for 16-bit field identifiers, field lengths, field occurrences, and record lengths. A newer FML32 interface allows for larger identifiers (32-bit), field lengths, field occurrences, and record lengths. The interfaces are nearly identical; the only difference is that a suffix of "32" is added to the name of type definitions, header files, functions, and commands.

Note: BEA MessageQ only supports FML32. Do not use the 16-bit FML functions in developing MessageQ applications.

How Does FML32 Fit into the BEA MessageQ System?

Within the BEA MessageQ system, FML32 functions are used to manipulate fielded buffers. In MessageQ applications, messages may be sent as message buffers (predefined, static data structures) or as FML32 buffers. Using FML32, applications construct messages containing both the message content and the information needed by the receiver program to understand what is in the message.

Who Is This Document For?

This guide gives detailed information about the features of FML32 and how the different FML32 functions are used.

This guide is intended for programmers who need to learn how to use FML32 functions in programming BEA MessageQ applications. This guide also provides information for users of applications that make use of FML32 with regard to setting up the environment correctly.

Prerequisites

To make full use of this guide, you should be familiar with the following:

• The UNIX System environment-We assume, for example, that you do not need a definition of a shell command or an environment variable, and that you understand what is meant by a UNIX System file or running a process in the background.

• The C programming language-The functions and macros that make up FML are intended to be incorporated in C language programs, so we assume you have previously spent some time developing C programs.

• The BEA MessageQ system-We assume, even if you have not yet worked on a BEA MessageQ application, that you at least have an understanding of what the BEA MessageQ system is intended to do, and that you have read about the application development environment in the BEA MessageQ Programmer's Guide.

What Does This Document Include?

• Concepts and Definitions-Several definitions are provided to explain ideas and terms that are used in the guide.

• An Overview of FML32-Chapter 2 offers an overview of the software. If you have not used FML functions before, you may find it helpful to read through the overview to get a general idea of how things work.

• Setup and Customization-Chapter 3 gives you the information you need to set up the environment variables, directory structure, and files that are required by the BEA MessageQ system in general, and FML32 in particular. This chapter also shows you how to customize your installed FML32 software.

• Defining and Using FML32 Fielded Buffers-Chapter 4 outlines the use of the FML32 software, and how to set up your C language programs to use the software.

• FML32 Field Manipulation Functions-Chapter 5 deals with how to use the FML32 functions to manipulate data.

Code Fragments-There are illustrations throughout Chapters 4 and 5 that show you examples of the functions as they might be used in a C program. Chapter 6 has provides additional examples.

What Other FML32 Documentation Is There?

In addition to this guide, documentation on FML32 function calls can be found in the reference page for each FML32 function and the following related reference pages in the BEA MessageQ Reference Manual:

Table 1-1 Section 5 reference pages

Reference Page	Description
field_tables(5)	describes the structure of FML field tables
mkfldhdr32	describes the command used to create header files from field tables

Concepts and Definitions

Field Identifier

A field identifier (fldid) is a tag for an individual data item in an FML record or fielded buffer. The field identifier consists of the name of the field (a number) and the type of the data in the field.

Fielded Buffer

A fielded buffer is a data structure in which each data item is accompanied by an identifying tag (a field identifier) that includes the type of the data and a field number.

Field Types

Fields in FML and fielded buffers are typed. They can be any of the standard C language types: short, long--> float, double, and char. Two other types are also supported: string (a series of characters ending with a null character) and carray (character arrays).