HP 3000 Manuals HP 3000 Manuals
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 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.
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).