| |
Home |
![[Table of Contents]](/dwicons/b_toc.gif)
|
Sybase dbQueue User's Guide |
![[-]](/dwicons/i_colpse.gif)
| Chapter 4: Building dbQueue Applications |
This chapter contains the following topics:
You can set up your dbQueue system either using Sybase Central (Chapter 3) or by using administration scripts. This chapter discusses using the administration scripts for system setup, as well as using standard SQL APIs or the dbQueue-supplied objects APIs to build applications that take advantage of the dbQueue distributed messaging system. dbQueue objects APIs include libraries that offer both administrative and queuing functions. Use the administrative functions to build Visual Basic scripts or incorporate administrative operations into your applications. Use the queuing functions to incorporate enqueue and dequeue operations into your applications.
You can use standard SQL APIs with the dbQueue system. dbQueue provides a set of queuing functions that allows you to integrate dbQueue enqueuing and dequeuing operations seamlessly into client applications written in SQL, CT-Lib, ODBC, or JDBC. The SQL API libraries do not support administrative functions.
dbQueue also provides a C++ objects library that includes a complete set of object class operations for implementing the dbQueue system. You can use the objects library to administer the system and queue messages. The Sybase Central administration tool is built with the dbQueue objects library.
dbQueue objects are ActiveX-compliant components. You can build applications that use ActiveX components as objects in such development environments as Visual Basic, Visual C++, Power++, and PowerBuilder. Because ActiveX components are built on top of the dbQueue objects, they possess all the dbQueue objects functionality, including administration and queuing methods.
Figure 4-1 illustrates the relationship between dbQueue API libraries, user applications, Sybase Central, and dbQueue system entities.
Figure 4-1: dbQueue API relationship diagram
If you are not using Sybase Central to define your system, use the administrative functions of the dbQueue objects library or the ActiveX components to create scripts or embed code into your application.
Use scripts when a Windows NT machine or Sybase Central is not available. Scripts are the only way you can perform administrative tasks on a UNIX-only system. Scripts can run independently without an operator present. On a Windows NT system, scripts are Visual Basic or PowerBuilder scripts developed using ActiveX components. On a UNIX system, scripts are compiled C++ programs developed using the C++ objects library.
For example, you could use a script running as a daemon process every night to reconfigure a transfer definition to accommodate changes in input data.
You can incorporate administrative operations into your application to configure the system "on the fly." For example, you could use the dbQueue objects library or the ActiveX components to develop an application that creates queues to be used as a smart cache and then frees the queues when they terminate.
The following code fragment shows how to use the dbQueue objects library in a C++ program to create a domain. You can use the code in a standalone administration program or embed it within an application. See the Sybase dbQueue Reference Guide for details on using the dbQueue objects library in your C++ applications.
// Declare some general variables.
DbqEnv* env; // Environment instance
DbqDomain* dom; // Domain connection
DbqAppDb* appdb; // Application database
DBQ_STATUS status; // Return status from API calls
// Get the environment. This call automatically
//initializes the library.
status = DbqEnv::NewEnv(&env);
if (status != DBQ_SUCCEED)
{
printf("Library initialization failure. Code: %d\n", status);
exit(1);
}
// Instantiate and fill out information for the //domain.
status = env->NewDomain(&dom);
if (status != DBQ_SUCCEED)
ErrorHandler(env);
dom->SetDomainName("MonaLisa");
dom->SetDataSource(CAT_SERVER);
dom->SetLogin(CAT_LOGIN);
dom->SetPassword(CAT_PASSWORD);// Install the catalog.
status = dom->Install();
if (status != DBQ_SUCCEED)
ErrorHandler(dom);
// Open the catalog, now that it's installed.
status = dom->Open();
if (status != DBQ_SUCCEED)
ErrorHandler(dom);
// Close the catalog again.
status = dom->Close();
if (status != DBQ_SUCCEED)
ErrorHandler(dom);
// Free instances.
dom->Delete();
env->Delete();
If you want functionality that is not in Sybase Central, you can build your own custom administration tool using the dbQueue objects library or ActiveX components.
You can combine methods to perform administrative tasks in your system. For example, you may set up the system using Sybase Central. Once the system is running and stable, you might want to create administration scripts that run as automatic daemon processes nightly to reconfigure some of the components to accommodate input data. Applications might also, for example, create and remove queues for the application's internal use.
Sybase Central and the ActiveX components are built on top of the dbQueue objects library. Therefore, they have access to all the dbQueue objects library's functionality.
Note: Implementing a dbQueue system is similar to most software development projects in that it usually requires a certain amount of iteration. The setup and administrative portion of the process is closely tied to the application building part of the process. You may find that you will be administering the system and building applications simultaneously as you develop the system.
You can build your applications using any of the standard SQL APIs or dbQueue-supplied objects APIs (except that SQL APIs do not support any administrative operations). You can use more than one API in the same application if the APIs are compatible. For example, you can use both dbQueue objects and ODBC in a C++ application that accesses SQL Server.
Note: If you are using the dbQueue objects library with CT-Lib in the same application, you need to open separate connections to the database. dbQueue objects and ODBC can use the same connection.
Each API has its own advantages. Your choice depends on the type of system you are implementing.
Standard SQL APIs supported by dbQueue include:
dbQueue-supplied APIs include:
The only design accommodation dbQueue requires is that you incorporate the enqueue and dequeue operations into your applications. Because dbQueue queues are built into the same databases that applications normally access for SQL operations, you can combine queuing operations with SQL database operations. For example, a dbQueue application can enqueue a message and insert a row into a database table in the same application database in a single transaction.
Note: Queues currently lock when client applications enqueue or dequeue. For example, if client A is dequeuing a message, other clients must wait until client A commits before their dequeue operations can proceed. Other clients can still enqueue during this time. To improve performance, it is therefore recommended that you place enqueue and dequeue operations at the end of the transaction.
To apply the dbQueue design model, first define the types of messages that pass between applications and the structure of the queues that contain these messages. Then organize your data into structures that fit your defined message types. Finally, call the enqueue and dequeue functions to deliver or retrieve the data messages against the queues.
With the standard SQL APIs, you can write your applications to access dbQueue queues in languages such as C and Java. dbQueue provides a set of enqueue and dequeue stored procedures that you can call within a CT-Lib, ODBC, JDBC, or SQL application.
You cannot perform dbQueue system administration using the SQL APIs. If you are developing applications with SQL APIs, you must set up the system before you start the applications. Use Sybase Central or Visual Basic scripts to set up the system.
CT-Lib applications use the dbQueue stored procedures enq_Q and deq_Q (where Q is the name of the queue) to access queues that are implemented in SQL Server. If you are familiar with CT-Lib programming, you can easily integrate the enqueue and dequeue calls into your applications. You must define and implement queues, message types, and other dbQueue entities before you call enq_Q and deq_Q.
The advantages of using CT-Lib include high performance and a high degree of program control. Because CT-Lib procedures execute at a level close to the SQL Server engine, they offer the highest performance of any API into SQL Server. Because CT-Lib is tightly coupled with SQL Server, it also offers more program control than high-level APIs. For example, you can dequeue in batches and filter out irrelevant messages by conditional testing at the SQL level.
Figure 4-2: Application development using CT-Lib API
As in CT-Lib applications, use enq_Q and deq_Q to access the queues in SQL Server and any ODBC-compliant datasource. You must define and implement queues, message types, and other dbQueue entities before you call the stored procedures.
The advantages of ODBC include the same advantages as CT-Lib. ODBC calls are executed at a layer that offer performance and a high degree of program control. Because the ODBC calls are translated into native dataserver calls, they add a small layer of indirection and decrease performance slightly compared to CT-Lib. However, dbQueue applications written using the ODBC API can access any ODBC-compliant datasource. Using ODBC calls, you can access dbQueue queues in SQL Server and SQL Anywhere. Future releases of dbQueue will support additional ODBC-compliant datasources.
Figure 4-3: Application development using ODBC API
The JDBC API is similar to the ODBC API, and offers performance, program control, and flexibility for the developers of Java applications for ODBC-compliant data sources. JDBC offers the same features as ODBC except it is adapted to work with Java applications. You use the same enq_Q and deq_Q stored procedures to access the queues. However, by programming in Java, you can leverage the advantages of dbQueue to create Web-based applications that are portable and platform-independent.
Figure 4-4: Application development using JDBC API
Your SQL application can call enq_Q and deq_Q to access the queues in SQL Server and SQL Anywhere. You can also call the stored procedures from an Embedded SQL/C or Embedded SQL/Cobol application, or from any compatible SQL language application.
Figure 4-5: Application development using SQL
The dbQueue objects library is a C++ library that contains all the necessary operations to create, deploy, monitor, and use the dbQueue system. It contains classes for system administration and application classes for enqueuing and dequeuing messages. Objects classes possess both public methods and static functions. The dbQueue objects library is the core of the dbQueue system interface. It is the underlying layer for the dbQueue ActiveX components and for any future dbQueue objects components.
Figure 4-6 illustrates the basic relationship of the dbQueue objects library, C++ applications, and the dbQueue system entities.
Figure 4-6: Application development using dbQueue objects in C++
For more information on how to use the dbQueue objects library (including code samples), see the Sybase dbQueue Reference Guide.
The dbQueue objects library has a set of administrative classes, application classes (for enqueuing and dequeuing), an error class, and a list class. Each class possesses action methods and list methods. Action methods can create, alter, and destroy objects. List methods return lists of objects.
The administrative classes are used for creating, implementing, and monitoring the system entities.
See the Sybase dbQueue Reference Guide for more information.
The application classes are used by applications to enqueue and dequeue messages.
See Sybase dbQueue Reference Guide for usage information.
The error class is used to signal errors. See the Sybase dbQueue Reference Guide for information about using the error class.
The list class is used to retrieve dbQueue entities. See Sybase dbQueue Reference Guide for information about using the list class.
dbQueue ActiveX components possess all the functionality of the dbQueue objects and provide easy integration with ActiveX applications. ActiveX objects are especially useful when you are developing applications using application development environment tools such as PowerBuilder, Visual Basic, Visual C++, and Power++.
dbQueue provides a wrapper around the dbQueue objects to make them available as ActiveX components to the development tool. You incorporate dbQueue objects into your application by using your tool's ActiveX integration mechanism.
In development tools such as Power++, the dbQueue ActiveX components appear as a set of nonvisual components in the reference card. By choosing from a list in the reference card, you can use drag-and-drop techniques to automatically generate C++ code directly into your application.
In Visual Basic, the dbQueue ActiveX library is fully accessible and conforms to Visual Basic syntax. Use the dbQueue ActiveX components as you would any other ActiveX component.
Normally, system administration is performed using Sybase Central. However, you can also integrate dbQueue administrative operations into your Visual Basic application or create standalone Visual Basic administration scripts. For example, a Visual Basic script can implement hundreds of dbQueue queues together as a batch. To do the same thing using Sybase Central interactively would be time-consuming and prone to errors.
Figure 4-7 illustrates the Visual Basic development environment. It shows how Visual Basic can access the dbQueue ActiveX components to build applications that can perform administration and queuing operations.
Figure 4-7: Application development using Visual Basic and dbQueue ActiveX
You can use Visual C++ to generate C++ applications that perform both administration and queuing operations. Because the dbQueue objects library is a C++ library, you have the option of using the dbQueue ActiveX components or directly accessing the dbQueue objects.
Figure 4-8 shows that Visual C++ can access the dbQueue objects library and the ActiveX components to generate a C++ application.
Figure 4-8: Application development using Visual C++
You can use Powersoft Power++ to generate C++ applications that can perform administration and queuing functions. Because the dbQueue objects library is a C++ library, you can either use ActiveX components or directly access the dbQueue objects.
Because Power++ has the ability to automatically generate C++ code for ActiveX objects, you can create a complete dbQueue-compliant application using drag-and-drop features.
Similiar to Visual Basic, you can use PowerBuilder to develop 4GL applications with dbQueue queuing capabilities.
Note: Future releases of dbQueue are expected to support Java components.
The dbQueue security model distinguishes between administration and messaging. dbQueue does not implement its own security model directly, but uses the security mechanism of the underlying databases that contain the queues. Administration and messaging functions are protected using database logins and groups.
The dbq_sa login is the standard account for dbQueue administration. dbq_sa has full privileges for sending and receiving messages and must be defined in every database that contains queues or catalogs. dbq_sa has administrative privileges within the database, which permits it to create objects and grant privileges on them to other users. dbQueue does not permit other accounts to install catalogs or administer databases.
The dbq_user group is for messaging application accounts. You can add a database user to the dbq_user group to grant send and receive privileges. dbQueue automatically grants the following privileges to members of the dbq_user group, which are then acquired by all group members:
dbQueue does not grant any additional privileges to members of dbq_user.
Before you can use a database with dbQueue, you must set up the dbq_sa login and the dbq_user group accounts. dbQueue assumes they already exist.
Add logins and groups to SQL Server using Sybase Central or calling stored procedures. The following example shows how to create the dbq_sa login for an entire server. Once executed, these commands apply to all databases managed by the server.
/* Create dbq_sa login with SA privileges. */
use master
go
sp_addlogin dbq_sa, dbq_sa
go
/* Grant sa_role and sso_role to dbq_sa */
sp_role "grant", sa_role, dbq_sa
go
sp_role "grant", sso_role, dbq_sa
go
The following example shows commands to create dbq_sa user and dbq_sa group for a single database appdb1. Run these commands once for each database.
use appdb1
go
sp_adduser dbq_sa
go
sp_addgroup dbq_user
go
More examples are in the sample SQL scripts in the dbQueue release directory.
Add logins and groups to SQL Anywhere using Sybase Central or grant commands. You must define dbq_sa as a group as well as a login, which allows accounts other than dbq_sa to view stored procedures and tables created by dbq_sa.
/* Create user DBQ_SA. The password of course may be different. */
grant connect to dbq_sa identified by dbq_sa;
/* Grant administrator and operator roles to dbq_sa. */
grant dba to dbq_sa;
grant resource to dbq_sa;
/* Make DBQ_SA a group. */
grant group to dbq_sa;
/* Create DBQ_USER and make it a group. */
grant connect to dbq_user;
grant group to dbq_user;
/* Make group DBQ_USER a member of DBQ_SA group */
grant membership in group dbq_sa to dbq_user;
Once you run this script, you can add any user as a member of the dbq_user group. More examples are in the sample SQL scripts in the dbQueue release directory.
Users must be dbq_sa or a member of the dbq_user group to send and receive messages. For example, bob wants to access queues in database appdb1. The sa for database appdb1 adds bob to the SQL Server with privileges on queues:
use appdb1
go
sp_adduser bob, bob, dbq_user
go
For SQL Anywhere, the command is:
grant membership in group dbq_user to bob;
Once privileges are granted, bob can enqueue and dequeue messages. The account can also be used to open a domain catalog and access message type information. However, if bob attempts to perform any other administrative function, such as adding an application database or a queue, dbQueue will reject the operation and issue an error.
You can customize the security of a queue by adding priviledges directly to the stored procedures used for queuing. For example, you might want to avoid using dbq_user and grant execute privilege to users on the following stored procedures:
rst_<Q> , enq_<Q>, and deq_<Q>
where <Q> is the name of the queue. For example, the following SQL commands permit bob to enqueue, dequeue, and truncate on queue Q1.
grant execute on rst_Q1 to bob
grant execute on enq_Q1 to bob
grant execute on deq_Q1 to bob
Be aware that if the queue is reinstalled, specialized privileges to users will disappear. You should store the list of privileges in a script so it can be run later.
WARNING! Users should not customize grants on the catalog stored procedures or the non-public stored procedures on queues. These procedures are not intended for general use, and may change between dbQueue versions without warning. Also, adding grants incorrectly may result in system failures. Instead, use dbq_sa for all administrative access to the catalog and other stored procedures.
If you have a simple system, integration may mean starting just one QTM and two dbQueue applications. If you have a large and complex system, integration may mean starting the full suite of multiple applications, queues, and QTMs. In such a large system, you may decide to break the system into smaller subsystems, and then integrate the fully tested subsystems.
Regardless of the size of the system or subsystem, the basic integration procedure includes:
The QTM is an Open Server process that moves messages between queues by dequeuing from source queues and enqueuing into target queues. The QTM obtains information about its transfer definitions, its source and target queues, and associated message types from the catalog metadata.
Note: Not all queues need to have a QTM. If the enqueuing application and the dequeuing application are operating on the same application database, a target queue is all that is required and a QTM is not necessary.
Start the QTM at the site where the source queue resides.
> setenv SYBASE /remote/cardhu3/users/dbq/sybase/solaris/10_0_conn
> setenv DSLISTEN QTMwhere QTM references an entry in a sql.ini file or interfaces file.
> qtm -CDBQSERV -Udbq_sa -Pdbq_saYou can also create a config file containing the parameters. For example, a config file entry may appear as follows:
Source DBQSERV
Username dbq_sa
Password dbq_sa
Note: Alternatively, you can use Sybase Central to start and stop the QTM. See Chapter 3, "Using Sybase Central," for more information.
After the QTMs are started and running properly, start the dbQueue applications that will perform queuing operations.
You can use Sybase Central to monitor the status of the queues.
dbQueue provides a trace file for collecting system and error messages.
System log messages are written to a log file specified by the DBQ_TRACE_PATH environment variable. For example, to specify a log file name dbqplog in the C drive:
set DBQ_TRACE_PATH=C:\dbQ\Errors\dbqplog
If you do not set this variable, the default file name is %DBQ%\log\dbq.log on Windows NT and $DBQ/log/dbq.log on UNIX. System messages are appended to the log file continuously.
You can use the dbQueue Log Viewer from Sybase Central to view the log file. See Chapter 3, "Using Sybase Central," for more information.
Note: The information in the log file is useful when you contact Sybase Technical Support. If you are experiencing a repeatable error, make sure that DBQ_TRACE_PATH is set to a valid path and file name before you contact Sybase Technical Support.
dbQueue includes several sample programs that you can use to learn about the dbQueue system. The samples are specific to each platform. See the Installation Guide for your platform and the README file for information.
|
|