SENDTO is similar to SEND, except that it includes the
destination address parameter. You can use the destination address
on the SENDTO macro to send datagrams on a UDP socket that is connected
or not connected.
Use the
FLAGS parameter to:
- Send out-of-band data, such as interrupts, aborts, and data marked
as urgent.
- Suppress the local routing tables. This implies that the caller
takes control of routing, which requires writing network software.
For datagram sockets, the SENDTO macro sends the entire
datagram if the datagram fits into the buffer.
For stream sockets, data is processed as streams of information
with no boundaries separating the data. For example, if a program
is required to send 1000 bytes, each SENDTO macro call can send any
number of bytes, up to the entire 1000 bytes, with the number of bytes
sent returned in RETCODE. Therefore, programs using stream sockets
should place SENDTO in a loop that repeats the macro until all data
has been sent.
The following requirements apply to this call:
Authorization: |
Supervisor state or problem state, any PSW key. |
Dispatchable unit mode: |
Task. |
Cross memory mode: |
PASN = HASN. |
Amode: |
31-bit or 24-bit.
|
ASC mode: |
Primary address space control (ASC) mode. |
Interrupt status: |
Enabled for interrupts. |
Locks: |
Unlocked. |
Control parameters: |
All parameters must be addressable by the caller
and in the primary address space. |
>>-EZASMI--TYPE=SENDTO--,S--=--+-number---+--------------------->
+-address--+
+-*indaddr-+
'-(reg)----'
>--,NBYTE--=--+-number---+--,BUF--=--+-address--+--------------->
+-address--+ +-*indaddr-+
+-*indaddr-+ '-(reg)----'
'-(reg)----'
>--,ALET--=--+-address--+--,NAME--=--+-address--+--------------->
+-*indaddr-+ +-*indaddr-+
'-(reg)----' '-(reg)----'
>--,ERRNO--=--+-address--+--,RETCODE--=--+-address--+----------->
+-*indaddr-+ +-*indaddr-+
'-(reg)----' '-(reg)----'
>--+--------------------------------+--------------------------->
'-,FLAGS--=--+-'MSG_OOB'-------+-'
+-'MSG_DONTROUTE'-+
+-address---------+
+-*indaddr--------+
'-(reg)-----------'
>--+---------------------------+--+-------------------------+--->
+-,ECB--=--+-address--+-----+ '-,ERROR--=--+-address--+-'
| +-*indaddr-+ | +-*indaddr-+
| '-(reg)----' | '-(reg)----'
'-,REQAREA--=--+-address--+-'
+-*indaddr-+
'-(reg)----'
>--+------------------------+----------------------------------><
'-,TASK--=--+-address--+-'
+-*indaddr-+
'-(reg)----'
- Keyword
- Description
- S
- Output parameter. A value or the
address of a halfword binary number specifying the socket descriptor
of the socket sending the data.
- NBYTE
- Input parameter. A value or the
address of a fullword binary number specifying the number of bytes
to transmit.
- BUF
- Input parameter. The address of the
data being transmitted. The length of BUF must
be at least as long as the value of NBYTE.
- ALET
- Optional input parameter. A fullword
binary field containing the ALET of BUF. The default is 0 (primary address space).
If
a nonzero ALET is specified, the ALET must
represent a valid entry in the dispatchable unit access list (DU-AL)
for the task issuing this call. Note that ALETs can be
specified only for synchronous socket calls (for example, ECB/REQAREA
cannot be specified). An exception to this is an ALET representing a SCOPE=COMMON data space.
- NAME
-
Input parameter. The address of the IPv4 or IPv6
target. Include the SYS1.MACLIB(BPXYSOCK) macro to get the assembler
mappings for the socket address structure. The socket address structure
mappings begin at the SOCKADDR label. The AF_INET socket address structure
fields start at the SOCK_SIN label. The AF_INET6 socket address structure
fields start at the SOCK_SIN6 label.
The IPv4 socket address
structure must specify the following fields:
- Field
- Description
- FAMILY
- A halfword binary field containing the IPv4 addressing family.
The value for the IPv4 socket descriptor (S parameter) is a decimal
2, indicating AF_INET.
- PORT
- A halfword binary field containing the port number bound to the
socket.
- IP-ADDRESS
- A fullword binary field containing the 32-bit IPv4 Internet Protocol address of the socket.
- RESERVED
- Specifies an 8-byte reserved field. This field is required, but
is not used.
The IPv6 socket structure must specify the following
fields:
- Field
- Description
- NAMELEN
- A 1-byte binary field specifying the length of this IPv6 socket
address structure. Any value specified by the use of this field is
ignored when processed as input and the field is set to 0 when processed
as output.
- FAMILY
- A 1-byte binary field specifying the IPv6 addressing family. The
value for IPv6 socket descriptor (S parameter) is a decimal 19, indicating
AF_INET6.
- PORT
- A halfword binary field containing the port number bound to the
socket.
- FLOW-INFO
- A fullword binary field specifying the traffic class and flow
label. This field must be set to 0.
- IPv6-ADDRESS
- A 16-byte binary field that is set to the 128-bit IPv6 Internet Protocol address, in network byte order, of the client
host machine. If 0 is specified, the application accepts connections
from any network address.
- SCOPE-ID
- A fullword binary field which identifies a set of interfaces as
appropriate for the scope of the address carried in the IPv6-ADDRESS field. A value of 0 indicates the SCOPE-ID field does not identify the set of interfaces
to be used, and can be specified for any address types and scopes.
For a link scope IPv6-ADDRESS, SCOPE-ID can specify a link index which identifies
a set of interfaces. For all other address scopes, SCOPE-ID must be set to 0.
- ERRNO
- Output parameter. A fullword binary
field. If RETCODE is negative, ERRNO contains a valid error number. Otherwise, ignore ERRNO.
See Socket call error return codes for information
about ERRNO return codes.
- RETCODE
- Output parameter. A fullword binary
field that returns one of the following values:
- Value
- Description
- 0 or >0
- A successful call. The value is set to the number of bytes transmitted.
- -1
- Check ERRNO for an error code.
- FLAGS
- Input parameter. FLAGS can be a literal value or a fullword binary field:
Literal Value |
Binary Value |
Description |
---|
'MSG_OOB' |
X'00000001' |
Send out-of-band data. (Stream sockets
only.) |
'MSG_DONTROUTE' |
X'00000004' |
Do not route. Routing is handled
by the calling program. |
- ECB or REQAREA
- Input parameter. This parameter is required if you are
using APITYPE=3. It points to a 104-byte field containing:
- For ECB
- A 4-byte ECB posted by TCP/IP when the
macro completes.
- For REQAREA
- A 4-byte user token (set by you) that is presented to your exit
when the response to this function request is complete.
- For ECB/REQAREA
- The last 100 bytes is a storage field used by the interface to
save the state information.
Note: This storage must not be modified until the
macro function has completed and the ECB has
been posted, or the asynchronous exit has been driven.
- ERROR
- Input parameter. The location in your program to receive
control when the application programming interface (API) processing
module cannot be loaded.
- TASK
- Input parameter. The location of the task storage area in your
program.