 |
» |
|
|
|
Sends a message to another process through a previously opened port. Syntax | |
REC I32 CA I32
AIFPORTSEND (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 the port that is to receive the message.
- message_buffer
character array (required) Passes the actual message to send through the specified port.
- message_length
32-bit signed integer by value (required) Passes the length, in bytes, of the message buffer to send through the
specified port. - envelope_code
32-bit signed integer by value (optional) Passes 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 sent, so the receiving process can
identify the message type without accessing the actual message buffer. If
this parameter is not supplied, envelope_code is defaulted to zero. Default: 0
- message_id
32-bit signed integer by reference (optional) A code returned by AIFPORTSEND to identify this particular message. 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 optional items allow AIFPORTSEND increased control over
the delivery of each message. Some of the most significant
options are the ability to wait for the message to be received,
and the ability to time out if the message is not received within
a given number of seconds. It is possible to send a message to a port that was not explicitly
opened by the caller. The AIFPORTSEND must use item 11101 with
a nowait value of -1. A nowait send queues the message to the
port and returns immediately to the caller and does not wait for a receive
to be issued against the port. AIFPORTSEND Item Descriptions | |
The following table provides detailed descriptions of item numbers and
corresponding items associated with AIFPORTSEND. Table 3-25 AIFPORTSEND Item Descriptions | Item Number | Item Name (Data Type) Release First Available Description
|
|---|
| 11101 | Time out seconds (I32); Release 3.0 Passes a value that sets a timeout in seconds. If the message is not
received within the number of seconds specified,
AIFPORTSEND 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 send
to be a nowait send. Control is returned to the
caller as soon as the message has been placed in the specified
port. - 0
Wait indefinitely for a receiver to get the message.
- >0
Wait the specified number of seconds for a receiver to
get the message, then destroy the message (no process will
receive it) and return an error status.
Default: 0 (wait indefinitely) | | 11102 | Priority (I32); Release 3.0 Passes the priority to use in sending this message. The possible values
range from 0 to 31, with 0 being the highest priority. If
priorities are used, the messages are no longer guaranteed
to be received in the same order in which they were sent. Default: 0 | | 11103 | Connectionless send (B); Release 4.0 Passes a boolean that indicates that a message may be sent to a port that has
not been previously opened for send access. This item does not allow item
11101 to be specified with a value >= 0. This means that a connectionless
send may only be done as a "no wait" send. If item 11101 is specified with
an illegal value, an error is returned. Default: FALSE |
|
