289 lines
14 KiB
HTML
289 lines
14 KiB
HTML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE html
|
|
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<html lang="en-us" xml:lang="en-us">
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
|
<meta name="security" content="public" />
|
|
<meta name="Robots" content="index,follow" />
|
|
<meta http-equiv="PICS-Label" content='(PICS-1.1 "http://www.icra.org/ratingsv02.html" l gen true r (cz 1 lz 1 nz 1 oz 1 vz 1) "http://www.rsac.org/ratingsv01.html" l gen true r (n 0 s 0 v 0 l 0) "http://www.classify.org/safesurf/" l gen true r (SS~~000 1))' />
|
|
<meta name="DC.Type" content="reference" />
|
|
<meta name="DC.Title" content="Examples: Using a data queue" />
|
|
<meta name="abstract" content="These examples explain three methods to process data queue files." />
|
|
<meta name="description" content="These examples explain three methods to process data queue files." />
|
|
<meta name="DC.Relation" scheme="URI" content="apiexmp.htm" />
|
|
<meta name="copyright" content="(C) Copyright IBM Corporation 1998, 2006" />
|
|
<meta name="DC.Rights.Owner" content="(C) Copyright IBM Corporation 1998, 2006" />
|
|
<meta name="DC.Format" content="XHTML" />
|
|
<meta name="DC.Identifier" content="apiexusque" />
|
|
<meta name="DC.Language" content="en-us" />
|
|
<!-- All rights reserved. Licensed Materials Property of IBM -->
|
|
<!-- US Government Users Restricted Rights -->
|
|
<!-- Use, duplication or disclosure restricted by -->
|
|
<!-- GSA ADP Schedule Contract with IBM Corp. -->
|
|
<link rel="stylesheet" type="text/css" href="./ibmdita.css" />
|
|
<link rel="stylesheet" type="text/css" href="./ic.css" />
|
|
<title>Examples: Using a data queue</title>
|
|
</head>
|
|
<body id="apiexusque"><a name="apiexusque"><!-- --></a>
|
|
<!-- Java sync-link --><script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
|
|
<h1 class="topictitle1">Examples: Using a data queue</h1>
|
|
<div><p>These examples explain three methods to process data queue files.</p>
|
|
<div class="section"><div class="note"><span class="notetitle">Note:</span> Read the <a href="codedisclaimer.htm">Code license and disclaimer information</a> for important
|
|
legal information.</div>
|
|
</div>
|
|
<div class="section" id="apiexusque__HDRWAIT"><a name="apiexusque__HDRWAIT"><!-- --></a><h4 class="sectiontitle">Example 1: Waiting up to 2 hours to receive data
|
|
from data queue</h4><p>In the following example, program B specifies to
|
|
wait up to 2 hours (7200 seconds) to receive an entry from the data queue.
|
|
Program A sends an entry to data queue DTAQ1 in library QGPL. If program A
|
|
sends an entry within 2 hours, program B receives the entries from this data
|
|
queue. Processing begins immediately. If 2 hours elapse without program A
|
|
sending an entry, program B processes the time-out condition because the field
|
|
length returned is 0. Program B continues receiving entries until this time-out
|
|
condition occurs. The programs are written in CL; however, either program
|
|
could be written in any high-level language.</p>
|
|
<p>The data queue is created
|
|
with the following command:</p>
|
|
<pre>CRTDTAQ DTAQ(QGPL/DTAQ1) MAXLEN(80)</pre>
|
|
<p>In
|
|
this example, all data queue entries are 80 bytes long.</p>
|
|
<p>In program A,
|
|
the following statements relate to the data queue:</p>
|
|
<pre>PGM
|
|
DCL &FLDLEN *DEC LEN(5 0) VALUE(80)
|
|
DCL &FIELD *CHAR LEN(80)
|
|
.
|
|
.(determine data to be sent to the queue)
|
|
.
|
|
CALL QSNDDTAQ PARM(DTAQ1 QGPL &FLDLEN &FIELD)
|
|
.
|
|
.
|
|
.</pre>
|
|
<p>In program B, the following statements relate to the data queue:</p>
|
|
<pre>PGM
|
|
DCL &FLDLEN *DEC LEN(5 0) VALUE(80)
|
|
DCL &FIELD *CHAR LEN(80)
|
|
DCL &WAIT *DEC LEN(5 0) VALUE(7200) /* 2 hours */
|
|
.
|
|
.
|
|
.
|
|
LOOP: CALL QRCVDTAQ PARM(DTAQ1
|
|
QGPL &FLDLEN &FIELD &WAIT)
|
|
IF (&FLDLEN *NE 0) DO /* Entry received */
|
|
.
|
|
. (process data from data queue)
|
|
.
|
|
GOTO LOOP /* Get next entry from data queue */
|
|
ENDDO
|
|
.
|
|
. (no entries received for
|
|
2 hours; process time-out condition)
|
|
.</pre>
|
|
</div>
|
|
<div class="section" id="apiexusque__HDRDSPFICF"><a name="apiexusque__HDRDSPFICF"><!-- --></a><h4 class="sectiontitle">Example 2: Waiting for input from a display
|
|
file and an ICF file</h4><p>The following example is different from the
|
|
usual use of data queues because there is only one job. The data queue serves
|
|
as a communications object within the job rather than between two jobs.</p>
|
|
<br /><img src="RBAFX653.gif" alt="Waiting for input from a display
file and an ICF file" /><br /><p>In this example, a program is waiting
|
|
for input from a display file and an ICF file. Instead of alternately waiting
|
|
for one and then the other, a data queue is used to allow the program to wait
|
|
on one object (the data queue). The program calls QRCVDTAQ and waits for an
|
|
entry to be placed on the data queue that was specified on the display file
|
|
and the ICF file. Both files specify the same data queue. Two types of entries
|
|
are put on the queue by display data management and ICF data management support
|
|
when the data is available from either file. ICF file entries start with <tt class="sysout">*ICFF</tt> and
|
|
display file entries start with <tt class="sysout">*DSPF</tt>.</p>
|
|
<p>The
|
|
display file or ICF file entry that is put on the data queue is 80 characters
|
|
in length and contains the field attributes described in the following table.
|
|
Therefore, the data queue that is specified using the CRTDSPF, CHGDSPF, OVRDSPF,
|
|
CRTICFF, CHGICFF, and OVRICFF commands must have a length of at least 80 characters.</p>
|
|
|
|
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all"><thead align="left"><tr><th valign="top" id="d0e61">Position (and Data Type)</th>
|
|
<th valign="top" id="d0e63">Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody><tr><td valign="top" headers="d0e61 ">1 through 10 (character)</td>
|
|
<td valign="top" headers="d0e63 ">The type of file that placed the entry on the data queue. This field
|
|
will have one of two values: <p><tt class="sysout">*ICFF</tt> for ICF
|
|
file</p>
|
|
<p><tt class="sysout">*DSPF</tt> for display file</p>
|
|
<p>If the
|
|
job receiving the data from the data queue has only one display file or one
|
|
ICF file open, then this is the only field needed to determine what type of
|
|
entry has been received from the data queue.</p>
|
|
</td>
|
|
</tr>
|
|
<tr><td valign="top" headers="d0e61 ">11 through 12 (binary)</td>
|
|
<td valign="top" headers="d0e63 ">The unique identifier for the file. The value of the identifier is
|
|
the same as the value in the open feedback area for the file. This field should
|
|
be used by the program receiving the entry from the data queue only if there
|
|
is more than one file with the same name placing entries on the data queue.</td>
|
|
</tr>
|
|
<tr><td valign="top" headers="d0e61 ">13 through 22 (character)</td>
|
|
<td valign="top" headers="d0e63 ">The name of the display file or ICF file. This is the name of the file
|
|
actually opened, after all overrides have been processed, and is the same
|
|
as the file name found in the open feedback area for the file. This field
|
|
should be used by the program receiving the entry from the data queue only
|
|
if there is more than one display file or ICF file that is placing entries
|
|
on the data queue.</td>
|
|
</tr>
|
|
<tr><td valign="top" headers="d0e61 ">23 through 32 (character)</td>
|
|
<td valign="top" headers="d0e63 ">The library where the file is located. This is the name of the library,
|
|
after all overrides have been processed, and is the same as the library name
|
|
found in the open feedback area for the file. This field should be used by
|
|
the program receiving the entry from the data queue only if there is more
|
|
than one display file or ICF file that is placing entries on the data queue.</td>
|
|
</tr>
|
|
<tr><td valign="top" headers="d0e61 ">33 through 42 (character)</td>
|
|
<td valign="top" headers="d0e63 ">The program device name, after all overrides have been processed. This
|
|
name is the same as that found in the program device definition list of the
|
|
open feedback area. For file type *DSPF, this is the name of the display device
|
|
where the command or Enter key was pressed. For file type *ICFF, this is the
|
|
name of the program device where data is available. This field should be used
|
|
by the program receiving the entry from the data queue only if the file that
|
|
placed the entry on the data queue has more than one device or session invited
|
|
prior to receiving the data queue entry.</td>
|
|
</tr>
|
|
<tr><td valign="top" headers="d0e61 ">43 through 80 (character)</td>
|
|
<td valign="top" headers="d0e63 ">Reserved.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<p>The following example shows coding logic that the application program
|
|
previously described might use:</p>
|
|
<pre> .
|
|
.
|
|
.
|
|
.
|
|
OPEN DSPFILE ...
|
|
/* Open the Display file. DTAQ parameter specified on*/
|
|
/* CRTDSPF, CHGDSPF, or OVRDSPF for the file. */
|
|
|
|
OPEN ICFFILE ...
|
|
/* Open the ICF file. DTAQ parameter specified on */
|
|
/* CRTICFF, CHGICFF, or OVRICFF for the file. */
|
|
|
|
.
|
|
.
|
|
DO
|
|
WRITE DSPFILE
|
|
/* Write with Invite for the Display file */
|
|
WRITE ICFFILE
|
|
/* Write with Invite for the ICF file */
|
|
|
|
CALL QRCVDTAQ
|
|
/* Receive an entry from the data queue specified */
|
|
/* on the DTAQ parameters for the files. Entries */
|
|
/* are placed on the data queue when the data is */
|
|
/* available from any invited device or session */
|
|
/* on either file. */
|
|
/* After the entry is received, determine which file */
|
|
/* has data available, read the data, process it, */
|
|
/* invite the file again and return to process the */
|
|
/* next entry on the data queue. */
|
|
IF 'ENTRY TYPE' FIELD = '*DSPF ' THEN
|
|
/* Entry is from display */
|
|
DO /* file. Since this entry*/
|
|
/* does not contain the */
|
|
/* data received, the data*/
|
|
/* must be read from the */
|
|
/* file before it can be */
|
|
READ DATA FROM DISPLAY FILE /* processed. */
|
|
PROCESS INPUT DATA FROM DISPLAY FILE
|
|
WRITE TO DISPLAY FILE /* Write with Invite */
|
|
END
|
|
ELSE /* Entry is from ICF */</pre>
|
|
<pre> /* file. Since this entry*/
|
|
/* does not contain the */
|
|
/* data received, the data*/
|
|
/* must be read from the */
|
|
/* file before it can be */
|
|
/* processed. */
|
|
READ DATA FROM ICF FILE
|
|
PROCESS INPUT DATA FROM ICF FILE
|
|
WRITE TO ICF FILE /* Write with Invite */
|
|
LOOP BACK TO RECEIVE ENTRY FROM DATA QUEUE
|
|
.
|
|
.
|
|
.
|
|
END</pre>
|
|
</div>
|
|
<div class="section" id="apiexusque__HDRDSPFDQ"><a name="apiexusque__HDRDSPFDQ"><!-- --></a><h4 class="sectiontitle">Example 3: Waiting for input from a display
|
|
file and a data queue</h4><p>In the following example, the program in Job
|
|
B is waiting for input from a display file that it is using and for input
|
|
to arrive on the data queue from Job A. Instead of alternately waiting for
|
|
the display file and then the data queue, the program waits for one object,
|
|
the data queue.</p>
|
|
<br /><img src="RBAFX654.gif" alt="Waiting
for input from a display file and a data queue" /><br /><p>The program
|
|
calls QRCVDTAQ and waits for an entry to be placed on the data queue that
|
|
was specified on the display file. Job A is also placing entries on the same
|
|
data queue. There are two types of entries put on this queue, the display
|
|
file entry and the user-defined entry. The display file entry is placed on
|
|
the data queue by display data management when data is available from the
|
|
display file. The user-defined entry is placing on the data queue by Job A.</p>
|
|
<p>The
|
|
structure of the display file entry is described in the previous example.</p>
|
|
<p>The
|
|
structure of the entry placed on the queue by Job A is defined by the application
|
|
programmer.</p>
|
|
<p>The following example shows coding logic that the application
|
|
program in Job B might use:</p>
|
|
<pre> .
|
|
.
|
|
.
|
|
.
|
|
OPEN DSPFILE ...
|
|
/* Open the Display file. DTAQ parameter specified on*/
|
|
/* CRTDSPF, CHGDSPF, or OVRDSPF for the file. */
|
|
|
|
|
|
.
|
|
.
|
|
DO
|
|
WRITE DSPFILE /* Write with Invite for the Display file */
|
|
|
|
CALL QRCVDTAQ
|
|
/* Receive an entry from the data queue specified */
|
|
/* on the DTAQ parameter for the file. Entries */
|
|
/* are placed on the data queue either by Job A or */
|
|
/* by display data management when data is */
|
|
/* available from any invited device on the display */
|
|
/* file. */
|
|
/* After the entry is received, determine what type */
|
|
/* of entry it is, process it, and return to receive */
|
|
/* the next entry on the data queue. */
|
|
IF 'ENTRY TYPE' FIELD = '*DSPF ' THEN
|
|
/* Entry is from display */
|
|
DO /* file. Since this entry*/
|
|
/* does not contain the */
|
|
/* data received, the data*/
|
|
/* must be read from the */
|
|
/* file before it can be */
|
|
READ DATA FROM DISPLAY FILE /* processed. */
|
|
PROCESS INPUT DATA FROM DISPLAY FILE
|
|
WRITE TO DISPLAY FILE
|
|
/* Write with Invite */
|
|
END
|
|
ELSE /* Entry is from Job A. */
|
|
/* This entry contains */
|
|
/* the data from Job A, */
|
|
/* so no read is required*/
|
|
/* before processing the */
|
|
/* data. */
|
|
PROCESS DATA QUEUE ENTRY FROM JOB A
|
|
LOOP BACK TO RECEIVE ENTRY FROM DATA QUEUE
|
|
.
|
|
.
|
|
.
|
|
END</pre>
|
|
</div>
|
|
</div>
|
|
<div>
|
|
<div class="familylinks">
|
|
<div class="parentlink"><strong>Parent topic:</strong> <a href="apiexmp.htm" title="Contains example programs that use APIs and exit programs.">Examples: APIs</a></div>
|
|
</div>
|
|
</div>
|
|
</body>
|
|
</html> |