 |
» |
|
|
|
Receives a message through a previously opened port. Syntax | |
REC I32 CA I32
AIFPORTRECEIVE (overall_status, port_id, message_buffer, message_length,
I32 I32 I32A @64A
envelope_code, message_id, itemnum_array, item_array,
RECA
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 |
|
