Series 300 and 800 Only

NAME

ipcconnect() − requests a connection to another process

SYNOPSIS

#include <sys/ns_ipc.h>

void ipcconnect (calldesc,destdesc,flags,opt,vcdesc,result);
ns_int_t calldesc,destdesc,*flags,*vcdesc,*result;
short int opt[];

DESCRIPTION

The ipcconnect call is used to initiate a virtual circuit on which data may be sent and received.  Compared to the telephone system, ipcconnect is similar to dialing a telephone but not waiting for an answer.  Pursuing this analogy, the destdesc parameter is similar to a telephone number and the calldesc parameter references a call socket or "telephone."  When ipcconnect is called from your process, it uses its "telephone" (call socket descriptor) and "telephone number" (destination descriptor) to "dial," or initiate a connection with, another process.  Socket descriptors can be obtained with an ipccreate call.  Destination descriptors can be obtained with ipclookup.  or ipcdest. 
 
ipcconnect could be said to "not wait for an answer" when it is called because it reports only whether a virtual circuit has been initiated, not whether it was successfully established.  If the connection is successfully initiated, ipcconnect will return a VC socket descriptor in its vcdesc parameter.  This VC socket descriptor refers to a VC socket that is the endpoint of the virtual circuit at the local node.  The VC socket descriptor identifies the connection in much the same way that switch buttons are used to identify conversations on a multi-extension telephone. 
 
Actively establishing a virtual circuit with NetIPC calls is a two-step process. First, ipcconnect is called to request a connection; second, ipcrecv is called to find out if a connection initiated with ipcconnect was successfully established.  Compared to the telephone system, this process is similar to dialing a telephone and then checking to see if someone answered.  Using this two-step process, processes can initiate several connections simultaneously without waiting for each one to complete. 
 
ipcconnect’s opt parameter enables you to specify the maximum number of bytes you expect to send and receive on the connection.  The default for both sending and receiving is 100 bytes. 
 
When a process calls ipcconnect, TCP checksumming for the connection that will be established is automatically enabled.  TCP checksum is performed in addition to data link checksum. 
 
This routine can be linked into a program by giving the -lnsipc option to cc(1) or ld(1). 

PARAMETERS

calldesc (input parameter) Call socket descriptor.  Refers to a call socket owned by the calling process.  If NS_NULL_DESC or -1 is specified in this parameter, ipcconnect will create a call socket and delete it after completing successfully. 

destdesc (input parameter) Destination descriptor.  Refers to a structure that indicates the location of the destination call socket (this is the call socket to which the connection request will be sent).  A destination descriptor can be obtained by calling ipclookup or ipcdest. 

flags (input parameter) This parameter is reserved for future use.  All bits must be clear (not set).  Refer to the NetIPC programmer’s manual for your system for a complete description of this parameter. 

opt (input parameter)  See below.  Refer to the NetIPC programmer’s manual for your system for a complete description of this parameter. 

vcdesc (output parameter) VC socket descriptor.  Refers to a VC socket that is the endpoint of the virtual circuit connection at this node.  May be used in subsequent NetIPC calls to reference the connection. 

result (output parameter) The error code returned; zero or NSR_NO_ERROR if no error.  See "Diagnostics" below for more information. 

OPTION PARAMETER

NSO_MAX_SEND_SIZE
( optioncode = 3) ( datalength = 2) A two-byte integer that specifies the maximum number of bytes you expect to send with a single ipcsend call on this connection.  Range:  1 to 32,000 bytes.  Default:  100 bytes.  If not specified, ipcsend will return an error if a call attempts to send greater than 100 bytes. 

NSO_MAX_RECV_SIZE
( optioncode = 4) ( datalength = 2) A two-byte integer that specifies the maximum number of bytes you expect to receive with a single ipcrecv call on this connection.  Range:  1 to 32,000 bytes.  Default:  100 bytes.  If not specified, ipcrecv will return an error if a call attempts to receive greater than 100 bytes. 

RETURNS

None.  Errors are returned in the result parameter. 

AUTHOR

HP

SEE ALSO

ipclookup(2), ipcrecv(2), ipcsend(2), ipcdest(2). 

DIAGNOSTICS

[NSR_NO_ERROR] The call was successful. 

[NSR_xxxx] Refer to the errors listed in the NetIPC programmer’s manual for your system. 

Hewlett-Packard Company  —  May 11, 2021