Using Data Queues in Modern Applications

Presented by

Carsten FlensburgRPG & Beyond Web Conference 2009

RPG & Beyond 2009: Using Data Queues in Modern Applications

Introduction: Data Queues provide a speedy, versatile, and functional program-to program communication method and also provide a perfect coupling and transaction layer in modern application design models, aiming at separating the data processing and business logic from the presentation layer, and thus achieving independence between the back-end and the front-end of the application.

Objectives of this presentation:• Discuss data queue objects and attributes as well as the Data Queue

APIs and their use• Learn how to design and develop applications using data queues• Present a number of data queue CL commands missing from the i5/OS

native collection• Point you to more data queue information, articles and programming

examples

Getting Started: What’s a data queue

Data queue object and primary attributes:

The data queue object is one of two queue type objects available on the IBM System i and recognized by the symbolic object type *DTAQ. The Create Data Queue (CRTDTAQ) command exposes the data queue attributes, some of which are explained below:

The primary queue attribute is type, being either: *STD – Standard local data queue *DDM – Remote data queue

Depending on the sequence type assigned to the data queue entries added to the data queue will be received in one of three possible sequences:

*FIFO – First In First Out *LIFO – Last In First Out *KEYED – Entry binary key value

Getting Started: How to define a local data queue

Data queue attributes - operational:

The operational attributes of a local data queue allow you to configure a data queue to optimize it’s capacity and performance to fit the requirements of your application. - Let’s have a brief look at the attributes available as well as their supported values:

Maximum entry length – 1-64512 bytes Key length – 1-256 bytes Include sender ID – *NO, *YES Force to auxiliary storage – *NO, *YES Maximum number of entries – *MAX16MB, *MAX2GB Initial number of entries – Positive number Automatic reclaim – *NO, *YES

Getting Started: How to define a remote data queue

Data queue attributes - connectivity:

The data queue connectivity attributes enables you to achieve system-to-system communication by means of defining a remote data queue. For this type of data queue only the attributes required to establish the connection between the two systems are specified.

You can use either SNA/APPC or RDB based on either SNA or TCPIP to configure the communications layer. The RDB/TCPIP option is by far the simplest of the available options and the recommended approach.

Remote data queue & library – Name, *LIBL and *CURLIB Remote location – Name, *RDB Relational database – RDB Entry name APPC device description – Name, *LOC Local location (APPC) – Positive number Mode (APPC)) – Name, *NETATR Remote network id (APPC) – Name, *LOC, *NETATR, *NONE

Getting Started: How to define a remote data queue using RDB

Using the RDB option to identify the remote location is the easiest way to configure DDM data queues in today's TCP/IP networks. The following steps are involved in performing this type of remote data queue configuration:

1. On the system on which you want to configure the DDM data queue, use the Work with Relational Database Directory Entry (WRKRDBDIRE) command to find the RDB Entry name of the remote system.

2. On the CRTDTAQ command, specify *RDB for the Remote location name and the RDB Entry name of the server found in step 1 for the RDB attribute.

3. To enable the user profile that puts or gets data queue entries on or from the preceding DDM data queue to successfully connect to the remote system, the user profile and password need to be identical on the two systems or alternatively you must add a server authentication entry.

4. If you now add a data queue entry to the newly created DDM data queue on the local system, the result is a data queue entry showing in the corresponding data queue on the remote system.

Data Queue Programming: The Data Queue APIs and Commands

Native Data Queue CL commands:

Create Data Queue (CRTDTAQ) Delete Data Queue (DLTDTAQ) Work with Data Queues (WRKDTAQ)

Start Journal Object (STRJRNOBJ) End Journal Object (ENDJRNOBJ)

i5/OS Data Queue APIs:

Clear Data Queue (QCLRDTAQ) Receive Data Queue (QRCVDTAQ) Retrieve Data Queue Description (QMHQRDQD) Retrieve Data Queue Message (QMHRDQM) Send to a Data Queue (QSNDDTAQ) Change Data Queue (QMHQCDQ) – 6.1

Data Queue Programming: The Send Data Queue API

The Send Data Queue (QSNDDTAQ) API

Required Parameter Group:

1 Data queue name Input Char(10) 2 Library name Input Char(10) 3 Length of data Input Packed(5,0) 4 Data Input Char(*)

Optional Parameter Group 1:

5 Length of key data Input Packed(3,0) 6 Key data Input Char(*)

Optional Parameter Group 2:

7 Asynchronous request Input Char(10)

Optional Parameter Group 3:

8 Data is from a journal entry Input Char(10)

Data Queue Programming: The Receive Data Queue API

The Receive Data Queue (QRCVDTAQ) API

Required Parameter Group:

1 Data queue name Input Char(10) 2 Library name Input Char(10) 3 Length of data Output Packed(5,0) 4 Data Output Char(*) 5 Wait time Input Packed(5,0)

Optional Parameter Group 1:

6 Key order Input Char(2) 7 Length of key data Input Packed(3,0) 8 Key data I/O Char(*) 9 Length of sender information Input Packed(3,0) 10 Sender information Output Char(*)

Optional Parameter Group 2:

11 Remove message Input Char(10) 12 Size of data receiver Input Packed(5,0) 13 Error code I/O Char(*)

Data Queue Programming: The Retrieve Data Queue Message API

The Retrieve Data Queue Message (QMHRDQM) API

Required Parameter Group:

1 Receiver variable Output Char(*) 2 Length of receiver variable Input Binary(4) 3 Format name Input Char(8) 4 Qualified data queue name Input Char(20) 5 Message selection information Input Char(*) 6 Length of message selection info Input Binary(4) 7 Message selection info format name Input Char(8) 8 Error code I/O Char(*)

Data Queue Programming: Data Queue API Prototypes

The QRCVDTAQ API prototype:

**-- Receive data queue entry: D RcvDtaQe Pr ExtPgm( 'QRCVDTAQ' ) D DtqNam 10a Const D DtqLib 10a Const

D DtaLen 5p 0 D Data 32767a Options( *VarSize )

D Wait 5p 0 Const D KeyOrder 2a Const Options( *NoPass ) D KeyLen 3p 0 Const Options( *NoPass ) D Key 256a Const Options( *VarSize: *NoPass ) D SndInfoLen 3p 0 Const Options( *NoPass) D SndInfo 44a Options( *VarSize: *Nopass ) D RmvMsg 10a Const Options( *Nopass ) D DtaRcvLen 5p 0 Const Options( *Nopass ) D Error 32767a Options( *VarSize: *Nopass )

Data Queue Programming: Data Queue API Prototypes

The QSNDDTAQ API prototype:

**-- Send data queue entry: D SndDtaQe Pr ExtPgm( 'QSNDDTAQ' ) D DtqNam 10a Const D DtqLib 10a Const D DtaLen 5p 0 Const D Data 32767a Const Options( *VarSize ) D KeyLen 3p 0 Const Options( *NoPass ) D Key 256a Const Options( *VarSize: *NoPass ) D AscRqs 10a Const Options( *NoPass ) D JrnDta 10a Const Options( *NoPass )

The QCLRDTAQ API prototype:

**-- Clear data queue: D ClrDtaQ Pr ExtPgm( 'QCLRDTAQ' ) D DtqNam 10a Const D DtqLib 10a Const D KeyOrder 2a Const Options( *NoPass ) D KeyLen 3p 0 Const Options( *NoPass ) D Key 256a Const Options( *VarSize: *NoPass ) D Error 32767a Options( *VarSize: *Nopass )

Data Queue Programming: Data Queue API Prototypes

The QMHQRDQD API prototype:

**-- Retrieve data queue description: D RtvDtqDsc Pr ExtPgm( 'QMHQRDQD' ) D RcvVar 32767a Options( *VarSize ) D RcvVarLen 10i 0 Const D FmtNam 10a Const D DtaQ_q 20a Const

The QMHRDQM API prototype:

**-- Retrieve data queue message: D RtvDtqMsg Pr ExtPgm( 'QMHRDQM' ) D RcvVar 32767a Options( *VarSize ) D RcvVarLen 10i 0 Const D FmtNam 10a Const D DtaQ_q 20a Const D MsgSel 10a Const D MsgSelLen 10i 0 Const D MsgSelFmt 8a Const D Error 32767a Options( *NoPass: *VarSize)

Data Queue Programming: Data Queue API Prototypes

The QMHQCDQ API prototype:

**-- Change data queue: D ChgDtaQ Pr ExtPgm( 'QMHQCDQ' ) D DtaQue_q 20a Const D RqsChg 32767a Const D Error 32767a Options( *VarSize )

The QMHQCDQ API change request data structure:

**-- API change request: D RqsChg Ds Qualified D NbrVarRcd 10i 0 Inz( %Elem( RqsChg.VarLenRcd )) D VarLenRcd LikeDs( VarLenRcd ) Dim( 2 ) ** D VarLenRcd Ds Qualified D ChgKey 10i 0 D ValLen 10i 0 D NewVal 1a

Data Queue Programming: Data Queue API Parameter Structures

QRCVDTAQ API – Sender information:

**-- Sender information: Qualified D SndInf Ds D BytRtn 7p 0 D BytAvl 7p 0 D JobNam 10a D UsrPrf 10a D JobNbr 6a D CurUsr 10a

Note the data type packed 7,0 specified for the Bytes returned and Bytes available subfields.

Data Queue Programming: Data Queue API Parameter Structures

QMHQRDQD API - Local data queue information:

**-- QMHQRDQD RDQD0100 format: D RDQD0100 Ds Qualified D BytRtn 10i 0 D BytAvl 10i 0 D MsgLen 10i 0 D KeyLen 10i 0 D Seq 1a D IncSndId 1a D FrcInd 1a D TxtDsc 50a D Type 1a D AutRcl 1a D 1a D NbrCurMsg 10i 0 D NbrMsgAlc 10i 0 D DtaQ_Nam 10a D DtaQ_Lib 10a D MaxMsgAlw 10i 0 D InlNbrMsg 10i 0 D DtaQ_Size 10i 0

Data Queue Programming: Data Queue API Parameter Structures

QMHRQRDQD API - Remote data queue information:

**-- RDQD0200 format:

D RDQD0200 Ds Qualified

D BytRtn 10i 0

D BytAvl 10i 0

D AppcDevD 10a

D Mode 8a

D RmtLocNam 8a

D LclLocNam 8a

D RmtNetId 8a

D RmtDtaQ_Nam 10a

D RmtDtaQ_Lib 10a

D DtaQ_Name 10a

D DtaQ_Lib 10a

D RdbNam 18a

Data Queue Programming: Data Queue API Parameter Structures

QMHRDQM API – Message selection formats:

**-- RDQS0100 selection format: D RDQS0100 Ds Qualified D SelTyp 1a D 3a D MsgBytRtv 10i 0

**-- RDQS0200 selection format: D RDQS0200 Ds Qualified D SelTyp 1aD KeySchOrd 2a D 1a D MsgBytRtv 10i 0 D KeyBytRtv 10i 0 D KeyLen 10i 0 D KeyVal 256a

Making the Case: Data queue employment

Data queues used as a communication layer:

Data queues provide a powerful method to establish an asynchronous communication layer between two programs. The example utility presented later demonstrating the techniques involved, uses local data queues. The information about data queue setup, the programming of the transaction dialogue as well as the data queue API calls apply however irrespective of where the physical data queues are located.

In the perspective of the communicating programs, the data exchange is merely a question of addressing the interface provided by the Send and Receive Data Queue APIs, respectively.

Data queues also offer a solution to different types of design and architecture objectives. For example, it could be a need to process a workload from a web application located on a separate server accessible from the Internet, while the production data and business logic are on a back-end server behind the company firewall.

Or the situation could involve a CPU-intensive application that should have its system workload moved from expensive interactive CPU cycles to less expensive batch cycles. The latter issue is potentially not only a question of cost, but also of sufficient system CPU capacity and thereby application scalability.

Making the Case: Data queue employment

Data queue applicability:

To elaborate a bit further on my opening statement, let me go into a little more detail and explain some of the application design objectives that can be achieved with data queues.

In general a variety of programming challenges are well served by the queue functionality provided by data queues but in an application design context the following properties are in focus:

1. Speed – program activation already completed

2. Scalability – more jobs waiting on same data queue

3. Threading – different requests handled in parallel

4. Distribution – dispatch request to different servers

Making the Case: Application Design

Design process and considerations:

To build a robust and flexible data queue communication layer, the following data protocol and application design objectives are worth considering in the early phase of your development project:

Message Format

Message Extensibility

Message Size Limit

Error and Event Communication

Language Support

Exception Tolerance

Debug Facility and Application Monitoring

Making the Case: Application Design

Message format: What kind of formatting should be applied to the message?

For internal applications, mapped data structures might suffice, but if the data exchange involves external partners or programming languages with poor data structure facilities, XML is definitely worth considering.

Regardless of the format that you choose, divide the message into at least two sections:

1. A message header section containing the control data of the message, such as protocol ID, request ID and type, reply key, message format/version, list control information, offset to and length of message data, error and event codes, and other similar information, if applicable.

2. A message data section containing the actual request or response data.

Making the Case: Application Design

Message Extensibility: How should we handle changes in or additions to the message format?

For XML-formatted messages, this concern is well covered; otherwise, including message format or message version/release/modification level information in the message header provides the ticket to safely modify or extend a message in the future. Here’s an example of how a message header could be designed in order to open up for support of future requirements:

Data protocol 6 CharTransaction ID 16 CharRequest ID 6 CharMessage format 8 CharMessage language 3 CharMessage offset value 30 CharNumber of entries requested 4,0 Zoned

Making the Case: Application Design

Message Size Limit: Some message types are by nature limitless in size. For example, when embedded lists or textual descriptions are involved, it might be impossible or useless to define the maximum message length to cover the longest imaginable message length. Instead, you have to include a mechanism that allows a message to be split into more segments.

One way of providing such a mechanism is adding a correlation-ID and an end-of-message flag to the message header information. The correlation-ID contains the sequence number of the message segment, and the end-of-message flag is used to signal when the current message segment is the last in the chain.

For some purposes, such as displaying lists, a better approach is to have the client request the additional segments one by one as new pages are required. There's no need to build and return a full list if only the first page is ever displayed. In such a setup, a number-of-list-entries field and a list-offset field is added to the message header. The list-offset field contains a value that uniquely identifies a list entry, such as a customer number or product ID. In some cases, this could also be a composite value to ensure uniqueness.

Making the Case: Application Design

Error and Event Communication: How should error and informational messages be communicated within the data protocol, to ensure a correct and helpful dialogue with the application user?

Defining unique error codes and event codes and related messages helps the receiving part of the application correctly identify and properly communicate an error or event. Message files can be of great help in creating and administering error messages and event messages.

Language Support: Do you need to support more than one language within the data protocol?

If so, you must include information in the message header to define the language that applies to the message dialogue, so that all language-sensitive information can be presented in the correct language.

Making the Case: Application Design

Exception Tolerance: Foreseeable, logical errors, such as a customer record not found, should be handled by the error and event communication facility that I just described. However, it is very important to include in your application design an exception trap mechanism that catches — and communicates back — unforeseen errors.

These errors could be any kind of exception that occurs during program execution and that unhandled would lead to an inquiry message being sent to the QSYSOPR message queue and bring the job to a screeching halt. Over time, unhandled errors could lead to all the server jobs hanging in a message wait, and before that suffering performance as the number of message waiting jobs grows.

Registering ILE condition handlers, adding RPG/IV *PSSR subroutines, and coding ditto monitor groups and (e)rror opcode extenders are all vital instruments in establishing the defensive programming style (also) required for this type of application.

Making the Case: Application Design

Debug Facility and Application Monitoring: How do you provide for daily monitoring of the application and investigation of problems and errors?

One way is to include log files to record the transaction dialogue as well as the application errors and events. If necessary because of performance or storage considerations, a switch could control the transaction logging and activate it only if debugging the transaction flow or message dialogue is necessary.

Building a Sample Data Queue Application: The Display TCP/IP Servers (DSPTCPSVR) command.

The DSPTCPSVR command displays a list of all or a subset of the TCP/IP servers available on your system. Using the display option in the list panel, you can further display all the selected server's start attributes from the QATOCSTART file.

Making it Work: The Data Protocol

Data Protocol Design: The following are the requirements for my data protocol design as far as request and response types are concerned:

1. Request a list of TCP/IP servers, optionally subset by server type.

2. Return a list of TCP/IP servers, including server file key information.

3. Request TCP/IP server information for a specific server.

4. Return TCP/IP server information for a specific server.

Making it Work: The Data Protocol

Here's what the QATOCSTART file layout looks like:

File . . . . . : QATOCSTART Record format . . . : QTOCSTRTLibrary . . . : QUSRSYS Record length . . . : 240

Field name Field type Buffer Length Key Column heading SERVERTYPE Char 1 1 SVR TYP SERVER Char 2 30 1 U Server AUTOSTART Char 32 4 Auto Start LIBRARY Char 36 10 Library of Program PROGRAM Char 46 10 Program to Call EXTSTRCMD Char 56 64 External Start CMD EXTENDCMD Char 120 64 External End CMD

Making it Work: The Data Protocol

Data protocol: TCPSVR

Request ID: SVRLST - Inbound

Request header:Data protocol 6 CharTransaction ID 16 CharRequest ID 6 CharMessage format 8 CharMessage language 3 CharMessage offset value 30 Char Number of entries requested 4,0 Zoned Valid range 1-24

Request data: Server type 1 Char

Making it Work: The Data Protocol

Data protocol: TCPSVR

Request ID: SVRLST - Outbound

Response header:Data protocol 6 CharTransaction ID 16 CharRequest ID 6 CharEvent code 4,0 ZonedError code 4,0 ZonedEvent message offset 4,0 ZonedError message offset 4,0 ZonedResponse data offset 4,0 ZonedMessage offset value 30 CharNumber of entries returned 4,0 ZonedEntry length 4,0 Zoned

Response data: Server type 1 CharServer key name 30 Char Server name 30 CharAuto start 4 Char

Making it Work: The Data Protocol

Data protocol: TCPSVR

Request ID: SVRATR - Inbound

Request header:Data protocol 6 CharTransaction ID 16 CharRequest ID 6 CharMessage format 8 CharMessage language 3 Char

Request data: Server key name 30 Char

Making it Work: The Data Protocol

Data protocol: TCPSVR

Request ID: SVRATR - Outbound

Response header:Data protocol 6 CharTransaction ID 16 CharRequest ID 6 CharEvent code 4,0 ZonedError code 4,0 ZonedEvent message offset 4,0 ZonedError message offset 4,0 ZonedResponse data offset 4,0 Zoned

Response data: Server type 1 CharServer name 30 CharAuto start 4 CharProgram name 10 CharProgram library 10 CharStart command 64 CharEnd command 64 Char

Making it Work: Logging the Transactions

Error and event log file example:

File . . . . . : CBX1691F Record format . . . : CBX1691R

Library . . . : QGPL Record length . . . : 595

Field name Field type Buffer Length Column

LGTSTP Timestamp 1 26 Log timestamp

LGTYPE Char 27 6 Log type (LOGERR, LOGEVT)

LGTRID Char 33 16 Transaction ID

LGPGMN Char 49 12 Program/module name

LGFUNC Char 61 12 Function (*PSSR, Monitor)

LGDGCD Zoned 73 4 0 Diagnostic code

LGDGMS Char 77 7 Diagnostic message ID

LGDGDT Char 84 512 Diagnostic data

Making it Work: Logging the Transactions

Transaction log file example:

File . . . . . : CBX1692F Record format . . . : CBX1692R

Library . . . : QGPL Record length . . . : 4157

Field name Field type Buffer Length Column

LGTSTP Timestamp 1 26 Log timestamp

LGTYPE Char 27 6 Log type (LOGTRN)

LGTRID Char 33 16 Transaction ID

LGDTPC Char 49 6 Data protocol

LGRQID Char 55 6 Request ID

LGRQTP Char 61 1 Request type (I/O)

LGDATA Char 62 4096 Log data

Making it Work: Separating the Data Flows

Why separate data flows:

Inbound traffic is typically handled first-in-first-out, whereas outbound traffic is keyed to ensure that the server reply is received by the correct request sender. To support this requirement efficiently, the inbound data queue should therefore be created with sequence *FIFO, and the outbound data queue should be created with sequence *KEYED.

Separating data flow means that you avoid the risk of data queue object lock conflicts between the sending and receiving processes.

Loss of client or server side processing is easier to detect if the inbound and outbound transactions are not mixed. This setup also makes it easier to monitor the inbound workload to ensure that sufficient server jobs are available to process the incoming requests.

Making it Work: Application Data Queues

Here are the commands to create the two data queues needed to establish the program-to-program communication in the preceding setup:

CRTDTAQ DTAQ(CBX169I) MAXLEN(8192) FORCE(*NO) SEQ(*FIFO) SENDERID(*NO) SIZE(*MAX2GB 16) AUTORCL(*YES) TEXT('Sample data queue application inbound queue')

CRTDTAQ DTAQ(CBX169O) MAXLEN(8192) FORCE(*NO) SEQ(*KEYED) KEYLEN(16) SENDERID(*NO) SIZE(*MAX2GB 16) AUTORCL(*YES) TEXT('Sample data queue application outbound queue')

Making it Work: The Application Components

The Data Queue Sample Application includes the following sources:

CBX169 -- RPGLE -- Data Queue Sample App - Service functions CBX169B -- SRVSRC -- Data Queue Sample App - Binder source

CBX1691 -- RPGLE -- Run Data Queue Server - TCPSVR Protocol CBX16911 -- RPGLE -- Run Data Queue Server - SVRLST Request CBX16912 -- RPGLE -- Run Data Queue Server - SVRATR Request CBX1691H -- PNLGRP -- Run Data Queue Server - Help CBX1691X -- CMD -- Run Data Queue Server

CBX1692 -- RPGLE -- Display TCP/IP Servers - CPP CBX1692E -- RPGLE -- Display TCP/IP Servers - UIM General Exit Pgm CBX1692H -- PNLGRP -- Display TCP/IP Servers - Help CBX1692L -- RPGLE -- Display TCP/IP Servers - UIM List Exit Program CBX1692P -- PNLGRP -- Display TCP/IP Servers - Panel Group CBX1692X -- CMD -- Display TCP/IP Servers

CBX1691F -- PF -- Error/event log file CBX1692F -- PF -- Transaction log file CBX169M -- CLP -- Data Queue Sample App – Build Application

Making it Work: Performing a Test Run

After successful creation of all objects, follow these steps to perform a test run:

1. Using the Change Current Library (CHGCURLIB) command, change your job's current library to the one containing the application.

2. Using the Run Data Queue Server (RUNDTAQSVR) command, start the server process: RUNDTAQSVR LOGTRN(*YES). To avoid locking up your interactive session, submit the command to batch. Check that the submitted job has gone active before proceeding.

3. To generate some work for the server job, run the DSPTCPSVR command. The DSPTCPSVR command requests the list of TCP/IP servers, one page at a time, from the server job through the inbound data queue CBX169I and receives its reply from the outbound data queue CBX169O. Every time you page down, the next block of TCP/IP servers is requested. The list request is sent from the CBX1692L UIM List Exit Program. The list request is processed by the CBX1691 and CBX16911 data queue server programs.

Making it Work: Performing a Test Run

Test run steps – continued:

4. The server job logs all transactions to the transaction log file CBX1692F. Using the Display Physical File (DSPPFM) command, you can monitor the request/response dialogue in the transaction log file CBX1692F: DSPPFM FILE(CBX1692F) FROMRCD(*END).

5. From the DSPTCPSVR panel, you can select option 5=Display server start information. Doing so generates one request/response per selected TCP/IP server. This can of course also be monitored in the transaction log file. The server information request is sent from the CBX1692E UIM General Exit Program. The server information request is processed by the CBX1691 and CBX16912 data queue server programs.

6. To complete the test run, end the server job submitted in step 2. If you ran the data queue server job interactively, use the SysRqs (System Request) key in that job and specify option 2, which runs the End Request (ENDRQS) command.

Data Queue Programming: New CL Commands

New data queue CL commands:

Display Data Queue Description (DSPDTAQD) - (1)Clear Data Queue (CLRDTAQ) - (1)Send Data Queue Entry (SNDDTAQE) - (1)Copy Data Queue Description (CPYDTAQD) - (2)Display Data Queue Entries (DSPDTAQE) - (3)Work with Data Queues (WRKDTAQ2) - (4)

The data queue commands were all published as part of the Programming Tips Newsletter’s APIs by Example article series.

Links to the articles explaining the commands in detail as well as links to the zip files containing all the source code are found on slide 44.

(1) - APIs by Example: Data Queue APIs and CL Commands, part 1(2) - APIs by Example: Data Queue APIs and CL Commands, Part 2(3) - APIs by Example: Data Queue APIs and CL Commands, Part 3(4) - APIs by Example: Data Queue APIs and CL Commands, Part 4

Data Queue Programming:Work with Data Queues (WRKDTAQ2) Command

Work with Data Queues WYNDHAMW 28-08-09 21:04:20 Type options, press Enter. 1=Send entry 3=Copy 4=Delete 5=Display description 8=Display entries 13=Change description 14=Clear Opt Data queue Library Type Text QPMJ12T017 QMPGDATA *STD QQFEQ04906 QQFTEMP *STD QSNMPSAQ QUSRSYS *STD QSRVCTL QSERVICE *STD QSRVMON QSERVICE *STD QSYSDTAQ QSYS *STD Exit point: QIBM_QWT_JOBNOTIFY -format: NT QS9HDW QSRVAGT *STD QS9PALTIME QSRVAGT *STD QYIVPUBDTQ QUSRSYS *STD Central PublishingAgent Data Queue QYPSJDTAQ QMGTC2 *STD QYPSJSVR data queue QYPSJDTAQ QUSRSYS *STD QYPSJSVR data queue More... Parameters or command ===> F3=Exit F4=Prompt F5=Refresh F6=Create data queue F9=Retrieve F11=Display full text F12=Cancel F17=Top F18=Bottom

Data Queue Programming: System-to-Program Communication

Besides the efficient and flexible program-to-program communication support that data queues provide, they are also useful for enabling system-to-program communication. I've collected information and programming examples at the end of this article, documenting the following operating system usage of data queues:

Display File (DSPF): Specifying a data queue for the CRTDSPF, CHGDSPF, or OVRDSPF commands' DTAQ parameter lets your interactive application be event driven (i.e., wait for user input and data queue input at the same time), as well as lets it time out the display file if no action occurs within a user-defined time limit. For further documentation and a programming example, please follow the link provided at the end of this presentation.

Intersystem Communications Function File (ICFF): Specifying a data queue for the CRTICFF, CHGICFF, or OVRICFF commands' DTAQ parameter lets your communication application be event driven (i.e., wait for local program input and remote system input to the communications file at the same time), as well as lets it time out the communication if no action occurs within a user-defined time limit. A link to documentation is at the end of this presentation.

Data Queue Programming: System-to-Program Communication

System-to-Program Communication – continued:

Spooled file support 1: Specifying a data queue for the CRTOUTQ or CHGOUTQ commands' DTAQ parameter generates a predefined data queue entry to the specified data queue every time a spooled file enters the ready (RDY) status on that output queue. Links to documentation and a programming example are at the end of this presentation.

Spooled file support 2: Adding the QIBM_NOTIFY_CRTSPLF environment variable at either system or job level generates a predefined data queue entry to the data queue specified in the environment variable, whenever a spooled file is created on the system or in the job for which the environment variable was added. Links to documentation and a programming example are at the end of this presentation.

Job event notification: Registering a data queue for the QIBM_QWT_JOBNOTIFY exit point and specifying a combination of event types and subsystems generates a predefined data queue entry whenever a specified job event (e.g., job placed on job queue, job starts, job ends) takes place in the specified subsystem. The programming example at the link provided at the end of this presentation reveals the details of setting up a job monitor using this exit point, and a link to the exit point documentation is also provided.

More Information on System iNetwork

Previously published APIs by Example articles:

APIs by Example: Data Queue APIs and CL Commands, part 1:

http://systeminetwork.com/article/apis-example-data-queue-apis-and-cl-commands

http://www.pentontech.com/IBMContent/Documents/article/53542_143_DataQueue1.zip

APIs by Example: Data Queue APIs and CL Commands, Part 2:

http://systeminetwork.com/article/apis-example-data-queue-apis-and-cl-commands-part-2

http://www.pentontech.com/IBMContent/Documents/article/53685_149_DataQueue2.zip

APIs by Example: Data Queue APIs and CL Commands, Part 3:

http://systeminetwork.com/article/apis-example-data-queue-apis-and-cl-commands-part-3

http://www.pentontech.com/IBMContent/Documents/article/53850_156_DataQueue3.zip

APIs by Example: Data Queue APIs and CL Commands, Part 4:

http://systeminetwork.com/article/apis-example-data-queue-apis-and-cl-commands-part-4

http://www.pentontech.com/IBMContent/Documents/article/54001_161_DataQueue4.zip

APIs by Example: Data Queue APIs and CL Commands, Part 5:

http://systeminetwork.com/article/apis-example-data-queue-apis-and-cl-commands-part-5

http://www.pentontech.com/IBMContent/Documents/article/54098_170_DataQueue5.zip

NOTE: The Data Queue CL commands presented here are available for download from the above articles. For your convenience the link to the zip file containing the object sources is

also included immediately below the article link.

More Information on System iNetwork

Data queue articles and utility examples:

Using Data Queue APIs: http://systeminetwork.com/article/using-data-queue-apisUsing Data Queues in RPG/IV: http://systeminetwork.com/article/using-data-queue-apis-rpg-ivData Queues: A PC-to-iSeries Quick Link:http://systeminetwork.com/article/data-queues-pc-iseries-quick-linkAutomatic Notification When Spool Files Are Created: http://systeminetwork.com/article/club-tech-iseries-systems-management-newsletter-20Automatic Spool Rerouting:http://systeminetwork.com/article/automatic-spool-reroutingAPIs by Example: Realtime Job Monitor: http://systeminetwork.com/article/apis-example-realtime-job-monitorAn Introduction to Asynchronous Messages:http://systeminetwork.com/article/introduction-asynchronous-messages

User queue articles:

APIs by Example: Creating a User Queue:http://www.systeminetwork.com/article.cfm?id=17972APIs by Example: User Queues, Part 2:http://www.systeminetwork.com/article.cfm?id=18097

More Information from IBM

IBM Data Queue API Documentation:

Data Queue APIs:http://publib.boulder.ibm.com/infocenter/iseries/v5r4/topic/apis/obj2.htm

Using Data Queues:http://publib.boulder.ibm.com/infocenter/iseries/v5r4/topic/apis/obj2a.htm

Clear Data Queue (QCLRDTAQ) API:http://publib.boulder.ibm.com/infocenter/iseries/v5r4/topic/apis/qclrdtaq.htm

Receive Data Queue (QRCVDTAQ) API:http://publib.boulder.ibm.com/infocenter/iseries/v5r4/topic/apis/qrcvdtaq.htm

Retrieve Data Queue Description (QMHQRDQD) API:http://publib.boulder.ibm.com/infocenter/iseries/v5r4/topic/apis/qmhqrdqd.htm

Retrieve Data Queue Message (QMHRDQM) API:http://publib.boulder.ibm.com/infocenter/iseries/v5r4/topic/apis/qmhrdqm.htm

Send Data Queue (QSNDDTAQ) API:http://publib.boulder.ibm.com/infocenter/iseries/v5r4/topic/apis/qsnddtaq.htm

More Information from IBM

IBM Technical Documents:

Configuring DDM Data Queue Support over TCP/IP:https://www-912.ibm.com/s_dir/slkbase.NSF/1ac66549a21402188625680b0002037e/e95c5072635554dd86256e980068aada?OpenDocumentAssigning a Default User Profile for IBM DRDA over TCP/IP:https://www-912.ibm.com/s_dir/slkbase.NSF/643d2723f2907f0b8625661300765a2a/9e61c67ade70359986256afd007cc9f1?OpenDocumentIBM AnyNet Configuration (SNA over TCP/IP) 1:https://www-912.ibm.com/s_dir/slkbase.nsf/1ac66549a21402188625680b0002037e/c5057870085200f8862565c2007cdc47?OpenDocumentIBM AnyNet Configuration (SNA over TCP/IP) 2:https://www-912.ibm.com/s_dir/slkbase.nsf/1ac66549a21402188625680b0002037e/c0e073485d35f074862569da0063626f?OpenDocumentSource System Security in a TCP/IP Network — Server Authentication - V5R4:http://publib.boulder.ibm.com/infocenter/iseries/v5r4/topic/ddm/rbae5sourcesecurity.htm

Configuring EE (Enterprise Extender) between Two IBM System i Systems:http://www-912.ibm.com/s_dir/slkbase.nsf/1ac66549a21402188625680b0002037e/

ed75fbb6841d9f718625710a004963a3?OpenDocument

Cross-Platform Data Queue Support

System iNetwork:

Exploring the Client Access Data Queue APIs:

http://systeminetwork.com/article/exploring-client-access-data-queue-apis

Programming with ODBC and Data Queues:

http://systeminetwork.com/article/programming-odbc-and-data-queues

AS/400 Toolbox: Using Dataqueue, Record, and RecordFormat Classes:

http://systeminetwork.com/article/as400-toolbox-using-dataqueue-record-and-recordformat-classes

Data Queues: A PC-to-iSeries Quick Link:

http://systeminetwork.com/article/data-queues-pc-iseries-quick-link

Use .NET to Develop iSeries Data Queue Applications:

http://systeminetwork.com/article/use-net-develop-iseries-data-queue-applications

Queue Up to Work with Data Queues in .NET Programs:

http://systeminetwork.com/node/26092

Work with the Data Queues API in .NET Applications:

http://systeminetwork.com/article/work-data-queues-api-net-applications

Accessing SQL Server Databases with Java (using data queues):

http://systeminetwork.com/article/accessing-sql-server-databases-java

Cross-Platform Data Queue Support

IBM:

Using the Client Access for Microsoft Windows 95 and Windows NT OCX Control and OLE Automation Objects with Visual Basic:

http://www-912.ibm.com/s_dir/slkbase.NSF/515a7ef1f8deef8c8625680b00020380/def5574d27de318e862565c2007cbc3c?OpenDocument

CWBDQ: Q&A for the Optimized Data Queue API:http://www-912.ibm.com/s_dir/slkbase.NSF/515a7ef1f8deef8c8625680b00020380/2202a0b08aebc41a862565c2007cb060?OpenDocument

IBM Toolbox for Java:http://www-03.ibm.com/servers/eserver/iseries/toolbox/overview.html

Data Queue Host Server Does Not Support DDM Data Queues:http://www-912.ibm.com/s_dir/slkbase.NSF/f5ed8d76fdf9afb88625680b00020384/8bc86c06f162066b86256d91006a6cac?OpenDocument

Websphere MQ (licensed product):http://www-01.ibm.com/software/integration/wmq/

RPG & Beyond 2009: Using Data Queues in Modern Applications – THE END

Presentation completed!

Questions concerning this presentation, data queues in general or data queue code snippets can be directed to me at:flensburg@novasol.dk

Thank you!