An entry sent to a data queue can cause a program using a display
file to be interrupted and allow the program to handle the unique
request. The program's normal function can be in operation when the
interrupt occurs.
There are two typical applications:
** When a data queue entry arrives, the operator should be
interrupted and an entire new display shown. When the
operator completes the interrupt task, the original screen is
re-displayed. This will be called the 'Interrupt'
application.
** Information appears at the bottom of the display that should
be refreshed whenever a data queue entry is sent. The
information is displayed only. The operator works with the
format at the top of the display. This will be called the
'Refresh' application.
This tool provides the two sample applications for demonstration
purposes.
The coding for both applications is approximately the same. If you
are interested in the 'Refresh' application, you should read the
explanation of the 'Interrupt' application first.
Both functions require the display file to be created with the DTAQ
parameter.
The first two sections describe the source. See the later section
'Trying the example'.
Comparison with sending a break message
---------------------------------------
A break message can be sent to a user to interrupt his current work
and let him read a message. This is independent of the application
of the application being performed at the Workstation.
Break messages are simpler to implement because the application does
not have to be modified. It is possible to have a break handling
interrupt program that is sensitive to certain message IDs and
actually invoke a program and not just the DSPMSG display.
Break messages have a few disadvantages:
** It is possible for the user job to say it does not want to be
interrupted in which case a break message can be sent, but
will not be seen by the user unless he takes an overt action
(See the CHGJOB BRKMSG parameter).
** The user is truly interrupted and must normally take an
additional action to process the new information.
** Using a specific break handling program to invoke an
application function for a specific message ID can be complex
in that it then prevents other break messages from occurring.
** Using a break message does not provide as smooth a flow as
refreshing part of the display.
Interrupt application
---------------------
To understand this section you will need to refer to the source:
DDS source is TAADTQCD in QATTDDS in TAATOOL
CL source is TAADTQCC in QATTCL in TAATOOL
Assume the operator is working with a normal display. When the data
queue entry arrives, the operator should be interrupted and handle
the interrupt.
A single display file will be used in the example. There is an
'interruptible' format that the user normally sees. If an entry is
sent to a data queue, an 'interrupt' format is displayed.
Note that the interruptible format (FMT1) uses the INVITE keyword
which specifies that the data queue will be used to receive
information. Even though FMT1 is only written (SNDF), the FRCDTA
keyword is not needed because the INVITE keyword causes the format to
be displayed.
FMT2 is the interrupt format and will be written with a SNDRCVF and
therefore does not need to consider the use of INVITE or FRCDTA.
It is a good practice when dealing with data queues to delete and
create the queue as part of the application. This ensures that any
existing entries would be cleared and that the size of the data queue
is at its minimum when the application starts.
Note that every interruptible format must do a SNDF and then a call
to wait for an entry to appear on the data queue. If a workstation
response is received, the data must still be read from the
workstation with a RCVF. If you have many formats that are
interruptible, the same approach must be used for each. Any formats
that are handling an interrupt should normally not be made
interruptible.
It is possible for both a data queue entry and a WS response to be
received on the data queue almost simultaneously. If this occurs, WS
support prevents writing to the display until the WS data has been
received. The program tries to write the interrupt format and
monitors for the error. If the error has occurred, the WS data is
read (RCVF) and a switch is set. The program then loops back to
write the interrupt format. After processing the interrupt, the
switch is checked to determine if WS data has already been read and
if so, the program loops back to process it.
If multiple data queue entries are sent before the first has
completed processing, the additional entries will be queued up. Note
that the code checks to see if another data queue entry has appeared
before branching back to normal processing. The &WAIT value is set
to zero before checking the data queue to provide an immediate
answer. If the &ENTLEN value is greater than zero, another data
queue entry exists and the program processes it. If no data queue
entry exists, the program returns to normal processing. This second
check of the data queue avoids the operator seeing a very brief
display of FMT1.
In this example, any keystrokes entered by the operator on FMT1 would
be lost if an interrupt occurs. It is possible to save the
keystrokes and the cursor position by having the interrupt display in
a second display file and specifying RSTDSP(*YES) on the file with
the interruptible formats.
It would be possible to write a window on top of the 'interruptible'
display rather than replace the entire screen. Use the DDS window
keywords.
If the application to be interrupted has many screens it will require
many code changes to allow for an interrupt. An alternative is to
consider the use of a break handling program. If the function to
interrupt with is simple and will not last long, this could be a
preferred method.
Refresh application
-------------------
To understand this section you will need to refer to the source:
DDS source is TAADTQCD2 in QATTDDS in TAATOOL
CL source is TAADTQCC2 in QATTCL in TAATOOL
The operator works with a normal format at the top of the display.
When the data queue entry arrives, information on the bottom of the
display is refreshed.
A single display file will be used in the example. The data queue
entry itself is used to refresh the bottom part of the display. This
format is only written (it is never read). Another alternative is to
use the data queue entry to act as a key field or indication that
some new information exists to be placed on the refresh format.
Both formats are coded as OVERLAY so that the entire screen is never
erased. The PUTRETAIN keyword is used to prevent erasing any
keystrokes the operator may have made without pressing the Enter key
when a data queue entry arrives. The FRCDTA keyword is not needed on
FMT2 because FMT1 will always be written with the INVITE keyword
which causes all formats to be sent to the display.
Indicator 32 controls the use of the PUTRETAIN keyword. If WS data
has been read, PUTRETAIN is off which causes the input field to be
blanked out. If a data queue entry exists, the operator may have
already entered keystrokes into the input field. To retain these
keystrokes, the PUTRETAIN keyword is optioned on and the format is
sent again.
If multiple data queue entries exist, they will cause successive
writes of the 'refresh' format. If a data queue entry and a WS entry
both appear on the data queue, the exception condition caused is
monitored for (see the discussion in the previous example), the data
is received and the refresh format sent again.
Trying the example
------------------
The sample code will may be executed as a demonstration.
Both programs delete and create the data queue DTQ1 using the default
for the library parameter. If you do not have a current library,
QGPL will be used and it must be on your library list for successful
execution.
The 'interrupt' application can be tried by:
CALL TAADTQCC
The 'interrupt' screen is displayed. Data entered into the NAME
field will appear as an informational message when the command
completes.
To try the function of an entry being sent to the data queue, you can
use a group job, a system request job or another workstation. Use
the TAA tool SNDDTAQ.
SNDDTAQ DTAQ(DTQ1) ENTLEN(80) ENTRY('xxxxxx')
When you return to the job that did the call to TAADTQCC, you should
see the interrupt screen with the ENTRY data that was sent. You can
try various options including sending multiple data queue entries
before returning to the job which did the call.
The 'refresh' application can be tried by:
CALL TAADTQCC2
The normal display appears. Data entered into the NAME field will
appear as an informational message when the command completes.
To try the function of an entry being sent to the data queue, use the
same approach described previously.
You should see the information you specified appear in the bottom
part of the display.
To simulate both a data queue entry and a workstation entry arriving
at the same time is difficult to test without changing the code. The
best solution is to modify the programs with the DLYJOB command. A
comment line appears in each of the CL programs where this should be
placed (Scan the source for DLYJOB). Remove the comment symbols and
re-create the tool. Call the program(s). When the display appears,
use SNDDTAQ as described previously from a different job. Then
return to the main job, enter data and press Enter. Both the data
queue entry and the WS entry will be in the data queue.
Restrictions
------------
None.
Prerequisites
-------------
The following TAA Tools must be on your system:
SNDESCMSG Send escape message
Implementation
--------------
None, the tool is ready to use.
Objects used by the tool
------------------------
Object Type Attribute Src member Src file
------ ---- --------- ---------- ----------
TAADTQCD *FILE DSPF TAADTQCD QATTDDS
TAADTQCD2 *FILE DSPF TAADTQCD2 QATTDDS
TAADTQCC *PGM CLP TAADTQCC QATTCL
TAADTQCC2 *PGM CLP TAADTQCC2 QATTCL
|
