IPCCREATE

Creates a call socket for the calling process.

Syntax

IPCCREATE (socketkind[,protocol][,flags][,opt],calldesc[,result])

Parameters

socketkind (input)

32-bit integer, by value. Indicates the type of socket to be created. The only type that a user process may create is: 3 = call socket. It is used for sending and receiving connection requests.

protocol (input)

32-bit integer, by value. Indicates the protocol module which the calling process wishes to access. If the value is zero or if this parameter is not specified, the TCP module is chosen by default. The protocols currently available to user processes are:

0 = Default protocol. The current default is TCP. The recommended value for programs using IPCNAME and IPCLOOKUP is 0 rather than 4 for TCP.
2 = X.25 protocol
4 = TCP (Transmission Control Protocol)

flags (input)

32 bits, by reference. A bit representation of various options. The following option is defined:

flags [0] (input). TCP only. Makes the newly created socket a "protected" socket. A protected socket is one which only a privileged user may create or use.

opt (input)

Record or byte array, by reference. A list of options, with associated information. Refer to "Common Parameters" for more information on the structure of this parameter. The following options are available:

maximum connection requests queued (option code=6, length=2, 2-byte integer) (input). Used to specify the maximum number of unreceived connections that can be queued to a call socket. The default value is 7.
address option (option code=128, length=n; n-byte array), (input). Allows users to specify the socket's protocol relative address rather than having NetIPC allocate an address. The format of this address is defined by the protocol, for TCP and X.25 protocol access, the address is a 2-byte array. For X.25, you must either specify a protocol relative address, or identify the socket as catch-all. (See the opt protocol flags "catch-all socket flag" (bit 2) description).
Address values in the range 30767 to 32767 decimal (% 74057 to % 77777) can be used without special capabilities. In privileged programs, values in the range 1 to 30766 decimal (%1 to % 74056) can be used. See the paragraph "User-specified Protocol Addressing" at the beginning of this chapter for more information.
network name (code=140, length=8, packed array of characters) (input). The X.25 network name is the network interface (NI) name defined when the network is configured with NMMGR. This option is required for X.25 protocol access. This field is left-justified.
protocol flags (code 144, length=4, 4-byte buffer).
- catch-all socket flag (bit 2) (input). X.25 protocol access only. This flag identifies the socket as a catch-all socket. Network administrator (NA) capability is required to set this flag. User capability is required to run a program that creates a catch-all socket. The address option (protocol relative address) does not apply to a catch-all socket.

calldesc (output)

32-bit integer, by reference. Call socket descriptor. The socket descriptor which identifies the created socket.

result (output)

32-bit integer, by reference. The returned error code; zero if no error.

Description

The IPCCREATE intrinsic creates a call socket, returning a call socket descriptor. A call socket descriptor is an identifying number which may be used in other NetIPC intrinsic calls. A process may own a maximum of 64 (call and VC) sockets. If a socket has been given away (via the IPCGIVE intrinsic), it is included in this total until another process takes it (via IPCGET).

Only the socketkind and calldesc parameters are required.

Condition codes returned by this intrinsic are:

CCE — Succeeded.
CCL — Failed.
CCG — Not returned by this intrinsic.

IPCCREATE runs in waited mode. It does not return until the request is completed.

Protocol-Specific Considerations

The following Table 3-5 “IPCCREATE Protocol Specific Parameters” outlines parameters that are specific to the particular protocol you are accessing.

Table 3-5 IPCCREATE Protocol Specific Parameters

Parameters		TCP	X.25
flags
	0	Protected socket	n/a
opt
	140	n/a	NI name required
	144	none defined	Bit 2: catch-all socket flag

X.25 Considerations

For direct access to X.25, the protocol parameter must be 2 (X.25). The opt parameter network name must include the X.25 network NI name.

The opt parameter address option (code 128) is used to contain the protocol relative address of the source socket.

X.25 compares the protocol relative address contained in an incoming call (in the CUD field) to the protocol relative addresses assigned to all X.25 call sockets at the source sockets' destination. If the protocol relative address of the source socket matches the incoming call's address (CUD) the call is routed to that socket.

If no match is found, the incoming call is routed to the catch-all socket if one has been defined. If the CUD address does not match any of the call sockets and no catch-all socket has been defined, the incoming call is cleared. the cause field of the clear packet is set to 0 and the diagnostic is 64.

The catch-all socket can be defined by setting the opt protocol flags catch-all socket flag (bit 2). Only one catch-all socket can be defined per directly-connected network.

The catch-all socket and address option (protocol relative address) only apply to switched virtual circuits (SVCs).

Common errors returned by IPCCREATE in result are:

SOCKERR   0  Successful completion.
SOCKERR   4  Transport has not been initialized.
SOCKERR   9  Protocol is not active.
SOCKERR  55  Exceeded protocol module's limit.
SOCKERR 106  Address currently in use by another
             socket.
SOCKERR 107  Transport is going down.
SOCKERR 153  Socket is already in use.

A complete table of SOCKERRs is included in Appendix C “Error Messages”

TCP

for TCP access, only the socketkind and calldesc parameters are required.

Cross-System Considerations for TCP

The following are HP 3000 to HP 1000, HP 3000 to HP 9000, and HP 3000 to PC programming considerations for this intrinsic:

TCP protocol address — Although the ranges of protocol addresses for each computer system are different, the recommended range for cross-system user applications is from 30767 to 32767 decimal (%74057 to %77777).

IPCCREATE

Technical documentation

» Table of Contents

» Glossary

» Index