Examples: Using a data queue

These examples explain three methods to process data queue files.

Note: Read the Code license and disclaimer information for important legal information.

Example 1: Waiting up to 2 hours to receive data from data queue

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.

The data queue is created with the following command:

CRTDTAQ DTAQ(QGPL/DTAQ1) MAXLEN(80)

In this example, all data queue entries are 80 bytes long.

In program A, the following statements relate to the data queue:

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)
.
.
.

In program B, the following statements relate to the data queue:

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)
 .

Example 2: Waiting for input from a display file and an ICF file

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.

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 *ICFF and display file entries start with *DSPF.

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.

Position (and Data Type)	Description
1 through 10 (character)	The type of file that placed the entry on the data queue. This field will have one of two values: `ICFF` for ICF file `DSPF` for display file 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.
11 through 12 (binary)	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.
13 through 22 (character)	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.
23 through 32 (character)	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.
33 through 42 (character)	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.
43 through 80 (character)	Reserved.

The following example shows coding logic that the application program previously described might use:

  .
  .
  .
  .
  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      */

                                   /*  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

Example 3: Waiting for input from a display file and a data queue

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.

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.

The structure of the display file entry is described in the previous example.

The structure of the entry placed on the queue by Job A is defined by the application programmer.

The following example shows coding logic that the application program in Job B might use:

  .
  .
  .
  .
  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