|
|
|
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).
|
