DDS for display files
Use this file- or record-level keyword to invite the device for a later
read. To send an invite to a specific device, your program sends an
output operation to the device with the INVITE keyword in effect. If
the record format used has output-capable fields, the data is sent to the
device before the device is invited.
This keyword has no parameters.
INVITE must be used if the display file can have multiple acquired devices
and your program does read from invited devices operations. This is
because a read from invited devices to a multiple device display file only
returns a record from one of the devices that was invited. If you want
all the acquired devices to be able to return data, an output operation with
INVITE in effect must be sent to each device before the read from invited
devices. Even if there is only one device acquired on the multiple
device file, the device must be invited via INVITE before a read from invited
devices.
INVITE also gives you the ability to create a subset of acquired devices
that are eligible to respond on a read from invited devices. For
example, if ten devices are currently acquired to the file but only three
devices were invited, the next read from invited devices operation returns a
record from one of the three invited devices. This is true even if the
other devices have data available.
INVITE provides some performance improvement. Normally a read
request is issued to a device when your program sends an input
operation. However, INVITE allows you to request the read when you
issue the output operation. After the output operation is complete,
your program can do other processing while the device is issuing data and the
OS/400 program is processing the received data. This may be a
significant improvement if the device is remote.
For specific instructions on when an invite operation is necessary and how
to specify a read from invited devices operation in your program, see the
appropriate high-level language manual.
INVITE cannot be specified at both the file and record level and cannot be
specified with the subfile keyword (SFL).
Option indicators are valid for this keyword.
Special considerations when using the INVITE keyword:
The following are special considerations when using the INVITE
keyword:
- An input operation sent to a specific device does not require an
invite. Input operations with a specified record format name or device
are directed to one device. If that device has an invite outstanding at
the time of the input operation, the invite is deleted after the input
operation is completed.
- Once an invite has been sent to a device, the only valid operations (in
addition to a read from invited devices) are the following:
- An input operation to a specific device.
- An output operation with data that tries to cancel the invite. If
the cancel is successful, the data is written. If INVITE was in effect
on the output operation, the device is invited again. If the cancel is
not successful (because the data has already been received by the system), the
output operation fails. Your program must perform an input operation to
process the data. The input operation erases the invite for that
device.
- On a read from invited devices operation to a display file, only data from
devices with an outstanding invite are considered. The input operation
waits for data from any of the invited devices. (See the WAITRCD
parameter on the Create Display File (CRTDSPF) and Change Display File
(CHGDSPF) commands.) If none of the invited devices responds before the
wait time ends, a notify message is sent and no data is returned. All
invited devices remain invited.
- If more than one device acquired to the display file has an invite
outstanding, a read from invited devices operation returns the next available
record from one of the invited devices. If records are received from
more than one device before this input operation, the other records are kept
for subsequent input operations.
- When a read from invited devices operation to a display file returns a
record to your program from an invited device, the invite for that device is
deleted. Other devices that have an invite outstanding remain
invited. The device that sent the record your program read must be
invited again if you want to receive data from this device on a later read
from invited devices operation.
- If no device was invited or if a device was invited but the job was
canceled with the controlled option, a read from invited devices operation to
a display file results in a notify message and no data is returned to your
program. All invited devices remain invited.
- If you want to invite a device but have no data to send it, issue an
output operation using a record format containing no output-capable fields
with INVITE in effect.
- After the first record is received from an invited display device, the
device should not be re-invited until all the record formats on the display
with input-capable fields are read by your program. Your program can
read those other record formats if you specify the record format name and the
device name on the read operation.
- If your display file has the delayed write option (DFRWRT(*YES) parameter
on the (Create Display File (CRTDSPF) and Change Display File (CHGDSPF)
commands), an output operation with the INVITE keyword in effect causes the
delayed output to appear on the display before the device is invited.
Example:
The following example shows how to specify the INVITE keyword.
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
00010A 01 INVITE
00020A R RCD1
00030A FLD1 10 2 2
00030A FLD2 5 2 24
A
INVITE is in effect only when option indicator 01 is set on.
[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]
(C) Copyright IBM Corporation 1992, 2005. All Rights Reserved.