SOCKET

The SOCKET macro creates an endpoint for communication and returns a socket descriptor representing the endpoint. Different types of sockets provide different communication services.

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.

Note: See "Addressability mode (Amode) considerations" under CALL instruction API environmental restrictions and programming requirements.

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=SOCKET--,AF--=--+-'INET'---+-------------------->
                                +-'INET6'--+   
                                +-address--+   
                                +-*indaddr-+   
                                '-(reg)----'   

>--,SOCTYPE--=--+-'STREAM'---+--,ERRNO--=--+-address--+--------->
                +-'DATAGRAM'-+             +-*indaddr-+   
                +-'RAW'------+             '-(reg)----'   
                +-address----+                            
                +-*indaddr---+                            
                '-(reg)------'                            

>--,RETCODE--=--+-address--+--+----------------------+---------->
                +-*indaddr-+  '-,NS--=--+-number---+-'   
                '-(reg)----'            +-address--+     
                                        +-*indaddr-+     
                                        '-(reg)----'     

>--+-------------------------+--+---------------------------+--->
   '-,PROTO--=--+-address--+-'  +-,ECB--=--+-address--+-----+   
                +-*indaddr-+    |          +-*indaddr-+     |   
                '-(reg)----'    |          '-(reg)----'     |   
                                '-,REQAREA--=--+-address--+-'   
                                               +-*indaddr-+     
                                               '-(reg)----'     

>--+-------------------------+--+------------------------+-----><
   '-,ERROR--=--+-address--+-'  '-,TASK--=--+-address--+-'   
                +-*indaddr-+                +-*indaddr-+     
                '-(reg)----'                '-(reg)----'

Keyword

Description

AF

Input parameter. Specify one of the following values:

Value: Description
'INET' or a decimal 2: Indicates the socket being created will use the IPv4 Internet protocol.
'INET6' or decimal 19: Indicates the socket being created will use the IPv6 Internet protocol.

Note: AF can also indicate a fullword binary number specifying the address family.

SOCTYPE

Input parameter. A fullword binary field set to the type of socket required. The types are:

Value: Description
1 or 'STREAM': Stream sockets provide sequenced, two-way byte streams that are reliable and connection-oriented. They support a mechanism for out-of-band data. This is the normal type for TCP⁄IP.
2 or 'DATAGRAM': Datagram sockets provide datagrams, which are connectionless messages of a fixed maximum length whose reliability is not guaranteed. Datagrams can be corrupted, received out of order, lost, or delivered multiple times. This type is supported only in the AF_INET domain.
3 or 'RAW': Raw sockets provide the interface to internal protocols (such as IP and ICMP).
Note: For SOCK_RAW sockets, the application must by APF-authorized.

ERRNO

Output parameter. A fullword binary field. If RETCODE is negative, this field contains an error number. 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
> or = 0: Contains the new socket descriptor.
-1: Check ERRNO for an error code.

NS

Optional input. A value or the address of a halfword binary number specifying the socket number for the new socket. If a socket number is not specified, the interface assigns one.

PROTO

Input parameter. A fullword binary number specifying the protocol supported. PROTO only applies to new sockets and should be set to 0 for TCP/IP. PROTO for IPv6 raw sockets cannot be set to the following values:

Protocol name: Numeric value
IPROTO_HOPOPTS: 0
IPPROTO_TCP: 6
IPPROTO_UDP: 17
IPPROTO_IPV6: 41
IPPROTO_ROUTING: 43
IPPROTO_FRAGMENT: 44
IPPROTO_ESP: 50
IPPROTO_AH: 51
IPPROTO_NONE: 59
IPPROTO_DSTOPTS: 60

PROTO numbers are found in the hlq.etc.proto data set.

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.