INITIALIZE

Use the INITIALIZE command to preallocate a socket set.

A socket set is a number of preallocated sockets available to a single REXX application. You can define multiple socket sets for one session, but only one socket set can be active at a time. The INITIALIZE command must be issued before any socket services are requested.

Guideline: When multiple socket sets are initialized, the last socket set that is initialized becomes the active socket set. Before closing a socket belonging to a specific socket set, you must ensure that the socket set that owns the socket is the active set. Otherwise, the CLOSE command fails.

Format


                                              .-,--40------.   
>>-SOCKET--(--+-"INITIALIZE"-+--,--subtaskid--+------------+---->
              '-"INITIALISE"-'                '-,--maxdesc-'   

>--+------------+--)-------------------------------------------><
   '-,--service-'

Parameters

subtaskid

The name of the socket set. This parameter can be 1-8 characters in length; it cannot contain blanks.

maxdesc

The number of sockets descriptors that can be opened in this socket set. By default, this parameter is set to 40.

service

The name of the TCP/IP service. This is the job name of an active TCP/IP stack. The name of the TCP/IP service must match the name of an active stack.

Result: If service is not specified on the INITIALIZE command, it defaults to the TCPIPJOBNAME that is specified in the Resolver input used for this application. If TCPIPJOBNAME is not specified either, it defaults to TCPIP.

Restrictions:

In a CINET environment, if the service name does not match the name of an active TCP/IP stack, the INITIALIZE command fails with the 1004 EIBMIUCVERR return code.
In an INET environment, any service name is accepted. However, the service name is changed to *INET if the service name does not match the name INET that is the TYPE operand specified on the FILESYSTYPE statement, which is defined in the BPXPARMxx PARMLIB member. The *INET service name indicates to the caller that a UNIX INET environment exists.

Returned value

The command returns a string that contains the return code, the name of the socket set, the number of socket descriptors that can be opened, and the name of the TCP/IP services, for example, 0 MYTASK 40 TCPSVT. The return code can be 0, a REXX socket API error number, or the REXX TCP/IP error number that is set by the socket command. The return code 0 indicates that the requested socket command was completed successfully.

For information about the format of the NAME string, see How structures are represented. See Socket call error return codes for additional information about the numeric error codes that are returned by this command.

The following REXX TCP/IP error numbers can be returned:

9 EBADF
22 EINVAL
38 ENOTSOCK
45 EOPNOTSUPP
1004 EIBMIUCVERR

The following REXX socket API error numbers can be returned:

2001 EINVALIDRXSOCKETCALL
2003 ESUBTASKINVALID
2004 ESUBTASKALREADYACTIVE2012 EINVALIDNAME

Tip: If the 2003 ESUBTASKINVALID error code is returned, issue the TERMINATE command and then reissue the INITIALIZE command. If the command continues to fail, verify that the value of service parameter is applicable for the system.

LE C/C++ equivalent

This command has no LE C/C++ equivalent.

Code example

The example code described in GETADDRINFO can be used to experiment with the INITIALIZE command in a CINET environment.