|
|
|
Receives a message through a previously opened port.
Syntax
REC I32 CA
AIFPORTRECEIVE ( overall_status, port_id, message_buffer,
I32 I32 I32
message_length, envelope_code, message_id,
I32A @64A RECA
itemnum_array, item_array, itemstatus_array );
Parameters
- overall_status
- record by reference (required)
Returns the overall status of the call. A zero indicates a successful
call. A negative value indicates an error in the overall call, not
specific to any particular item. A positive value indicates the last
element in itemstatus_array, signaling an error condition. Refer to
appendix A for meanings of status values.
Record type: status_type (Refer to appendix B.)
- port_id
- 32-bit signed integer by reference (required)
Passes a port ID, returned from a successful call to
AIFPORTOPEN. This parameter specifies from which port to
receive the message. If you specify a port_id of zero,
the next message received from any port previously opened by the calling
process is returned, and the port_id of the port from
which the message was taken is returned in this parameter.
- message_buffer
- character array (required)
Returns the message. The buffer passed must be large enough to hold the
message, or the message is truncated.
Array type: message_buffer_type (Refer to appendix B.)
- message_length
- 32-bit signed integer by reference (required)
Passes the length, in bytes, of message_buffer. (If the
message returned is longer than this length, the message is truncated.)
Returns the actual length of the message returned in
message_buffer if the actual length is shorter than the
value passed.
- envelope_code
- 32-bit signed integer by reference (optional)
Returns an integer code associated with the envelope portion of the
message. The use of this value is application dependent (for example, it
can be used to identify the type of message being received without
accessing the actual message buffer).
Default: nil
- message_id
- 32-bit signed integer by reference (optional)
Returns the message ID assigned to this message when it was sent by
AIFPORTSEND.
Default: nil
- itemnum_array
- 32-bit signed integer array by reference (optional)
This is an array of integers, terminated by an element containing the
value zero, used to define the corresponding option given in the
item_array parameter. If this optional parameter is
specified, the item_array parameter and the
itemstatus_array parameter must both be supplied.
Default: nil
- item_array
- 64-bit address array by reference (optional)
An array with the same number of elements as the
itemnum_array parameter, each of which is a
globalanyptr that points to the appropriate type needed by each
particular item number. The value used for each option is taken from, or
returned to, the location pointed to by the globalanyptr in
this array. When this parameter is supplied, the
itemnum_array parameter and the
itemstatus_array parameter must both be supplied.
Array type: globalanyptr
Default: nil
- itemstatus_array
- record array by reference (optional)
If problems are detected with specific items, an error status is placed
in the corresponding element of this array for each item with an error.
The overall status parameter indicates whether any individual items
contained errors, and the element of the last detected error. This array
must contain as many elements as are contained in the
itemnum_array and item_array parameters.
A nonzero value indicates an error, but a valid option does not set the
value to zero, so this array should be initialized to all zeros before
making the call.
Array type: status_type (Refer to appendix B.)
Default: nil
Operation Notes
Several options are included with AIFPORTRECEIVE to allow increased
control over the delivery of each message. Some of the most significant
options are the ability to wait for the message to be delivered and the
ability to time out if the message is not received within a given number of
seconds.
For asynchronous ports it is very important for the user to properly manage
the receipt of messages on the port. When a port has its interrupt handler
enabled, it is possible for multiple messages to arrive, causing nested
interrupts. Inside a handler, the user should receive a single message, even
though muliple messages could exist on the port. Clearing a message does not
prevent the handler from being invoked.
There is an exception, however: when AIFPORTINT was used to disable
port interrupt handling, newly arriving messages do not cause the handler to
be invoked. Interrupt handling is delayed, and a pending count is incremented.
After AIFPORTINT is used inside the handler, the first receive should
pick up the message that caused the handler to be called. The user can then
issue another receive with item 11007 to get a message with a pending count.
When there are messages with a pending count, the receive succeeds and the
message is returned. The receive can be called repeatedly with item 11007
until an error is returned indicating that there are no more messages with
pending interrupts. Each AIFPORTRECEIVE with item 11007 will
decrement the pending count. When the pending count is 0, delayed calls of the
interrupt handler do not occur.
AIFPORTRECEIVE Item Descriptions
The following table provides detailed descriptions of item numbers and
corresponding items associated with AIFPORTRECEIVE.
Table 3-24 AIFPORTRECEIVE Item Descriptions
| Item Number |
Item Name (Data Type) Release First Available Description |
| 11001 |
Priority mask (I32); Release 3.0
Passes a priority bit mask that determines which messages are received. A
message can be sent at any of 32 possible priorities. If this option is
specified, only messages that come in with the indicated priorities are
received. This parameter is a bit mask with each bit position, from left
to right, indicating the corresponding priority, 0 to 31, that should be
received. For example, if the third bit is on with all other bits off,
only messages that have a priority of 2 are received. Remember that the
leftmost bit is bit zero, and the bits are numbered left to right. |
| 11002 |
Time out seconds (I32); Release 3.0
Passes a value that sets a time out value in seconds. If the message is
not received within the number of seconds specified,
AIFPORTRECEIVE fails, and a status indicating that the timeout
has expired is returned.
Following are valid values and their meanings:
| -1 | Don't wait. Specifying a timeout of -1 signals this
receive to be a nowait receive. |
| 0 | Wait indefinitely to receive the message. |
| >0 | Wait the specified number of seconds for a
receiver to get the message, then return an error status. |
Default: 0 (wait indefinitely) |
| 11003 |
Message return (B); Release 3.0
Passes a value that allows the retrieval of pieces of information from the
envelope without getting the message portion of the package.
Following are the possible values and their meanings :
| TRUE | Return the message to the specified message
buffer. If the message is longer than the length of the buffer, it
is truncated. There is no indication returned that the message has
been truncated. |
| FALSE | Do not return the message. When this option is
used, the next AIFPORTRECEIVE call to the same port (with
this option set to true) returns the message. Other parameters in
the AIFPORTRECEIVE call (for example,
envelope_code, message_id,
message_length, and port_id) are
returned with information that may be useful at a later time. Both
envelope_code and message_length, in
particular, can be used to determine the application-defined type of
message, and if the available buffer space is enough before the
message is received and truncated because the buffer is not big
enough. |
Default: TRUE |
| 11004 |
Sender PID (I32); Release 3.0
Returns the sender's process ID (PID). |
| 11005 |
Sender PIN (I32); Release 3.0
Returns the sender's process identification number (PIN). The PIN is a
16-bit value, but is returned as an 32-bit integer. |
| 11006 |
Actual priority (I32); Release 3.0
Returns the priority of the message. Unless messages are being received
only from a specific priority (See item 11001 priority mask), there is no
way to tell the priority of the message just received unless this option
is used. |
| 11007 |
Message with pending interrupt (B); Release 4.0
Passes a Boolean that when set to TRUE, indicates a request to receive a
message that has a pending interrupt.
Messages with pending interrupts are caused by calls to the
AIFPORTINT routine, which disables interrupt handling on a
specified port. Messages that arrive on a port after disabling interrupt
handling cause a pending interrupt count to be incremented for each
message that has arrived provided the receiver is not waiting on the port.
When the AIFPORTINT routine is called to enable interrupts, the
user handler is called once for each pending interrupt.
When this option is used on an AIFPORTRECEIVE with a value of
TRUE and there is a pending interrupt count greater than 0, the message is
received and the pending interrupt count is decremented by one. When there
are no messages with pending interrupts, an error is returned. (Refer to
appendix A.) A port ID of zero cannot be used with this option.
Default: FALSE |
|
