Writing a service component

This section describes the relationship between services, components, entry points, and return codes.


Functions and components

Each service consists of a set of related functions. For example, the name service contains function for:

  • Looking up a queue name and returning the name of the queue manager where the queue is defined
  • Inserting a queue name into the service's directory
  • Delete a queue name from the service's directory

It also contains initialization and termination functions.

An installable service is provided by one or more service components. Each component can perform some or all of the functions that are defined for that service. For example, in IBM MQ for AIX , the supplied authorization service component, the OAM, performs all the available functions. See Authorization service interface for more information. The component is also responsible for managing any underlying resources or software (for example, an LDAP directory) that it needs to implement the service. Configuration files provide a standard way of loading the component and determining the addresses of the functional routines that it provides.

Figure 1 shows how services and components are related:

  • A service is defined to a queue manager by stanzas in a configuration file.
  • Each service is supported by supplied code in the queue manager. Users cannot change this code and therefore cannot create their own services.
  • Each service is implemented by one or more components; these can be supplied with the product or user-written. Multiple components for a service can be invoked, each supporting different facilities within the service.
  • Entry points connect the service components to the supporting code in the queue manager.
Figure 1. Understanding services, components, and entry points


Entry-points

Each service component is represented by a list of the entry-point addresses of the routines that support a particular installable service. The installable service defines the function to be performed by each routine.

The ordering of the service components when they are configured defines the order in which entry-points are called in an attempt to satisfy a request for the service.

In the supplied header file cmqzc.h, the supplied entry points to each service have an MQZID_ prefix.

If the services are present, the services are loaded in a predefined order. The following list shows the services, and the order in which they are initialized.

  1. NameService
  2. AuthorizationService
  3. UserIdentifierService

The AuthorizationService is the only service that is configured by default. Configure the NameService and UserIdentifierService manually if you want to use them.

Services, and service components have a one-to-one or one-to-many mapping. Multiple service components can be defined for each service. On UNIX and Linux systems, the ServiceComponent stanza's Service value must match the Service stanza's Name value in the qm.ini file. On Windows, the ServiceComponent 's Service registry key value must match the Name registry key value, and is defined as: HKEY_LOCAL_MACHINE\SOFTWARE\IBM\WebSphere MQ\Installation\MQ_INSTALLATION_NAME\Configuration\QueueManager\qmname\ where qmname is the name of the queue manager.

For UNIX and Linux systems, service components are started in the order they are defined in the qm.ini file. On Windows, because the Windows registry is used, IBM MQ issues a RegEnumKey call which returns the values in alphabetic order. Therefore, on Windows the services are called in alphabetic order, as they are defined in the registry.

The ordering of the ServiceComponent definitions is significant. This ordering dictates the order in which components are run for a given service. For example, the AuthorizationService on Windows is configured with the default OAM component named MQSeries.WindowsNT.auth.service. Additional components can be defined for this service in order to override the default OAM. Unless MQCACF_SERVICE_COMPONENT is specified, the first component encountered in alphabetic order is used to process the request, and the name for that component is used.


Return codes

Service components provide return codes to the queue manager to report on various conditions. They report the success or failure of the operation, and indicate whether the queue manager is to proceed to the next service component. A separate Continuation parameter carries this indication.


Component data

A single service component might require data to be shared between its various functions. Installable services provide an optional data area to be passed on each invocation of a service component. This data area is for the exclusive use of the service component. It is shared by all the invocations of a particular function, even if they are made from different address spaces or processes. It is guaranteed to be addressable from the service component whenever it is called. You must declare the size of this area in the ServiceComponent stanza.