 |
OpenVMS System Services Reference Manual
$ICC_CONNECTW
Establishes a link between two ICC associations.
The $ICC_CONNECTW service completes synchronously; that is, it returns
to the caller after the server has either accepted or rejected the
connection request.
For asynchronous completion, use the $ICC_CONNECT service; $ICC_CONNECT
returns to the caller as soon as the connection request has been sent
to the server, without waiting for a response from the server.
On Alpha, this service accepts 64-bit addresses.
Format
SYS$ICC_CONNECTW ios_icc, [astadr], [astprm], assoc_handle,
conn_handle, remote_assoc, [remote_node], [user_context], [conn_buf],
[conn_buf_len], [return_buf], [return_buf_len], [retlen_addr], [flags]
C Prototype:
int sys$icc_connectw (struct _ios_icc *ios_icc, void
(*astadr)(__unknown_params), __int64 astprm, unsigned int assoc_handle,
unsigned int *conn_handle, void *remote_assoc, void *remote_node,
unsigned int user_context, char *conn_buf, unsigned int conn_buf_len,
char *return_buf, unsigned int return_buf_len, unsigned int
*retlen_addr, unsigned int flags);
$ICC_DISCONNECT
Terminates the specified connection.
On Alpha systems, this service accepts 64-bit addresses.
Format
SYS$ICC_DISCONNECT conn_handle ,iosb ,[astadr] ,[astprm] ,[disc_buf]
,[disc_buf_len]
C Prototype:
int sys$icc_disconnect (unsigned int conn_handle, struct _iosb, *iosb,
void (*astadr)(__unknown_params), __int64 astprm, char * disc_buf,
unsigned int disc_buf_len);
Arguments
conn_handle
| OpenVMS usage: |
connection_id |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
The ID of the connection to be disconnected.
iosb
| OpenVMS usage: |
io_status_block |
| type: |
quadword (unsigned) |
| access: |
write only |
| mechanism: |
by 32-bit or 64-bit reference (Alpha) |
| mechanism: |
by 32-bit reference (VAX) |
I/O status block:
Completion status values:
SS$_NORMAL, SS$_EXQUOTA, SS$_LINKDISCON, $ICC_REJECT
astadr
| OpenVMS usage: |
ast_procedure |
| type: |
procedure_entry_mask |
| access: |
call without stack unwinding |
| mechanism: |
by 32-bit or 64-bit linkage reference (Alpha) |
| mechanism: |
by 32-bit reference (VAX) |
The AST routine to be executed when the operation completes.
astprm
| OpenVMS usage: |
user_arg |
| type: |
quadword (unsigned) (Alpha), longword (unsigned)
(VAX) |
| access: |
read only |
| mechanism: |
by 64-bit value (Alpha) |
| mechanism: |
by 32-bit value (VAX) |
The parameter to be passed to the AST routine.
disc_buf
| OpenVMS usage: |
byte_stream |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by 32-bit or 64-bit reference (Alpha) |
| mechanism: |
by 32-bit reference (VAX) |
A buffer of up to 1000 bytes of disconnect data to be sent to the
partner in the connection when notifying it that disconnection is being
initiated. Delivery of this data is not guaranteed.
disc_buf_len
| OpenVMS usage: |
buffer_length |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
The number of bytes in disc_buf to be sent.
Description
This service must be called in the mode in which the association was
opened.
This service terminates the specified connection. After this service is
called, no further communication is possible over this connection. All
outstanding data transmission and reception functions are terminated
with an error before completion is signaled by calling the AST (if
supplied).
A connection may be disconnected by either party. Proper programming
procedure for network communications strongly recommends that the party
that last received a message initiate the disconnection. If the party
that last sent a message initiates the disconnection, there is no
guarantee that the message was delivered.
Similarly, although this interface provides the ability to send
disconnect data, only noncritical information should be transmitted
with the disconnect data mechanism, because there is no guarantee that
the data will have been received or acted upon by the other party to
the connection.
Required Access or Privileges
None.
Required Quota
BYTLM (disc_buf)
Related Services
$ICC_ACCEPT, $ICC_CLOSE_ASSOC, $ICC_CONNECT, $ICC_CONNECTW,
$ICC_DISCONNECTW, $ICC_OPEN_ASSOC, $ICC_RECEIVE, $ICC_RECEIVEW,
$ICC_REJECT, $ICC_REPLY, $ICC_REPLYW, $ICC_TRANSCEIVE,
$ICC_TRANSCEIVEW, $ICC_TRANSMIT, $ICC_TRANSMITW
Condition Values Returned
|
SS$_NORMAL
|
Normal successful completion.
|
|
SS$_ACCVIO
|
Access violation on parameter.
|
|
SS$_BADPARAM
|
Bad parameter value specified.
|
|
SS$_INSFMEM
|
Not enough nonpaged pool.
|
|
SS$_IVBUFLEN
|
The length of the disconnect data buffer is more than 1000 bytes.
|
|
SS$_IVCHAN
|
Unknown connection specified or invalid connection handle.
|
|
SS$_IVMODE
|
Attempted to disconnect a connection from a more privileged access mode
than the requested connection.
|
|
SS$_LINKDISCON
|
The remote association closed the connection before it was accepted or
rejected.
|
|
SS$_TOO_MANY_ARGS
|
Too many arguments specified.
|
$ICC_DISCONNECTW
Terminates a link between two ICC associations.
The $ICC_DISCONNECTW service completes synchronously; that is, it
returns to the caller after the connection has completely finished the
disconnection request.
For asynchronous completion, use the $ICC_DISCONNECT service;
$ICC_DISCONNECT returns to the caller as soon as the disconnection
request has been sent to the transport layer, without waiting for
notification that the disconnection has completed.
On Alpha, this service accepts 64-bit addresses.
Format
SYS$ICC_DISCONNECTW conn_handle ,iosb ,[astadr] ,[astprm] ,[disc_buf]
,[disc_buf_len]
C Prototype:
int sys$icc_disconnectw (unsigned int conn_handle, struct _iosb, *iosb,
void (*astadr)(__unknown_params), __int64 astprm, char * disc_buf,
unsigned int disc_buf_len);
$ICC_OPEN_ASSOC
Declares an application association with ICC.
On Alpha systems, this service accepts 64-bit addresses.
Format
SYS$ICC_OPEN_ASSOC assoc_handle ,[assoc_name] ,[logical_name]
,[logical_table] ,[conn_event_rtn] ,[disc_event_rtn] ,[recv_rtn]
,[maxflowbufcnt] ,[prot]
C Prototype:
int sys$icc_open_assoc (unsigned int *assoc_handle, void *assoc_name,
void *logical_name, void *logical_table, void
(*conn_event_rtn)(__unknown_params), void
(*disc_event_rtn)(__unknown_params), void
(*recv_rtn)(__unknown_params), unsigned int maxflowbufcnt, unsigned int
prot);
Arguments
assoc_handle
| OpenVMS usage: |
association_id |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by 32-bit or 64-bit reference (Alpha) |
| mechanism: |
by 32-bit reference (VAX) |
The 32-bit or 64-bit address (on Alpha systems) or the 32-bit address
(on VAX systems) of a longword into which $ICC_OPEN_ASSOC writes the
handle assigned to the opened association.
assoc_name
| OpenVMS usage: |
char_string |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by 32-bit or 64-bit descriptor (Alpha) |
| mechanism: |
by 32-bit descriptor (VAX) |
An ASCII character string of up to 31 characters in length specifying
the name of the application opening the association. Null (0 length),
and empty or blank association names are not allowed. If this argument
is omitted (that is, a zero is passed in by value), it signifies that
the user wants to open the default association. This argument is case
sensitive.
logical_name
| OpenVMS usage: |
logical name |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by 32-bit or 64-bit descriptor (Alpha) |
| mechanism: |
by 32-bit descriptor (VAX) |
A logical name in a clusterwide logical name table used to maintain the
simple association registry. The logical name represents the name of
the service provided by the application. Logical names are case
sensitive.
logical_table
| OpenVMS usage: |
logical name table |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by 32-bit or 64-bit descriptor (Alpha) |
| mechanism: |
by 32-bit descriptor (VAX) |
The table containing the logical name logical_name.
Logical name tables are converted to uppercase. Unless your application
requires an application-specific logical name table, this argument
should be either the default ICC Registry search list (ICC$REGISTRY),
or the default registry table (ICC$REGISTRY_TABLE).
conn_event_rtn
| OpenVMS usage: |
user_routine |
| type: |
procedure_entry_mask |
| access: |
call without stack unwinding |
| mechanism: |
by 32-bit or 64-bit linkage reference (Alpha) |
| mechanism: |
by 32-bit reference (VAX) |
The address of the AST routine to be called for incoming connect
events. This routine will be called in the mode of the caller. (No
mechanism is provided for the routine to be called at a different mode).
You must have a conn_event_rtn to operate as a server.
disc_event_rtn
| OpenVMS usage: |
user_routine |
| type: |
procedure_entry_mask |
| access: |
call without stack unwinding |
| mechanism: |
by 32-bit or 64-bit linkage reference (Alpha) |
| mechanism: |
by 32-bit reference (VAX) |
The address of the AST routine to be called for incoming disconnect
events. This routine will be called in the mode of the caller. (No
mechanism is provided for the routine to be called at a different
mode). The arguments, conn_event_rtn, and
disc_event_rtn, may reference the same routine.
recv_rtn
| OpenVMS usage: |
user_routine |
| type: |
procedure_entry_mask |
| access: |
call without stack unwinding |
| mechanism: |
by 32-bit or 64-bit linkage reference (Alpha) |
| mechanism: |
by 32-bit reference (VAX) |
The address of the AST routine to be called for incoming new data
events.
If the user provides this routine, it indicates that the user will
supply a buffer of the size required (specified in an argument to the
recv_rtn at each call) each time one is requested. If
the user supplies this routine, receive calls should only be issued
after receive events arrive and sufficient buffer space has been
allocated to handle the incoming data.
This routine will be called in the mode of the caller. (No mechanism is
provided for the routine to be called at a different mode).
maxflowbufcnt
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
The maximum number of pending inbound messages (per connection) that
ICC will allow the user before initiating flow control. A message is
pending if it is being held within ICC but no receive call(s) are
outstanding from the user.
Default = 5 (Pass 0 to get the default)
prot
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
This argument is ignored for non-server applications.
The default protection scheme for this association is as follows:
0 - access for everyone (default)
1 - stops WORLD access
2 - stops both WORLD and GROUP access
Advanced access control is provided by ICC Security objects. Refer to
the OpenVMS System Manager's Manual for information on ICC system management and security.
Description
This service declares an application association with ICC. Servers must
make this call to declare or register their name and to indicate their
readiness to receive incoming connections. Although a client is
permitted to call this routine, it is unnecessary for simple
applications. A client application that wishes to be notified of
disconnection events or Receive Data events must call the
$ICC_OPEN_ASSOC service.
A client can open a connection without specifying an open association;
this automatically creates a default association name of
ICC$PID_nnnnnnnn (where nnnnnnnn is a character representation of the
Process ID).
NETMBX privilege is required to open any association.
The association name space is a controlled resource. Refer to the
OpenVMS System Manager's Manual for information on managing this resource.
An attempt to open an association with a name not authorized as
described in the OpenVMS System Manager's Manual will fail with the error SS$_NOPRIV
returned to the caller. In addition to making entries in the system's
local association name space, a call to $ICC_OPEN_ASSOC may also make
an entry in a simple clusterwide registry of active associations.
An association may only be accessed from the mode in which it was
opened. Inner modes are prevented from using the default association.
An application can open any number of associations subject to available
process BYTLM quota. Currently, there is a systemwide limit of 512 open
associations. There is no limit imposed clusterwide.
Description of User-Supplied Routines (ASTs)
When opening an association, the user may optionally supply a
connect/disconnect AST and/or a Data Event AST. These routines will be
used for all connections established over the specified association. In
addition, for any of the asynchronous services (those provided with
both an immediate return and a "W" form), a completion AST may be
supplied by the user. This section describes these ASTs.
1. Connect and Disconnect AST
The user chooses the name of this routine and supplies the procedure
name as an argument to the Open Association service. Seven arguments
will be passed to the user.
The first argument notifies the user whether this is an incoming new
connection or a disconnection of an existing connection. The second
identifies the connection. The third and fourth provide access to
incoming connect or disconnect data (if any) sent by the cooperating
application. The fifth argument provides the number of bytes available
for any optional Accept or Reject data (in the case of a connect
request) or the disconnect reason supplied by the cooperating
application (if any).
For connect events, the sixth and seventh arguments are the EPID and
username of the process requesting the connect, respectively.
The user has the choice of using and declaring a common routine or
separate routines as specified when calling $OPEN_ASSOCIATION.
Format
ConnDiscRtn event_type ,conn_handle ,data_len ,data_bfr ,P5 ,P6 ,P7
|
C Prototype:
void ConDiscRtn (unsigned int event_type, unsigned int conn_handle,
unsigned int data_len, char *data_bfr,
unsigned int P5, unsigned int P6, char *P7);
|
Arguments
event_type
Type: longword (unsigned)
Access: read only
Mechanism: by value
|
This field will contain a code describing the type of event. The
possible event codes are defined in ICCDEF:
ICC$C_EV_CONNECT - Connection event
ICC$C_EV_DISCONNECT - Disconnection event
|
conn_handle
Type: longword (unsigned)
Access: read only
Mechanism: by value
|
The handle of the connection associated with the event.
data_len
Type: longword (unsigned)
Access: read only
Mechanism: by value
|
The length (in bytes) of the incoming data. This value specifies the
length of the buffer data_bfr, and will be between 0
and 1000, with zero indicating no data.
data_bfr
Type: character-coded text string
Access: read only
Mechanism: by 32-bit or 64-bit value (Alpha)
by 32-bit value (VAX)
|
The 32-bit address of the P1-space buffer containing the data, or zero
if no data is available. The length of this buffer is specified by the
argument data_len.
Upon return from the AST, the address of the data is no longer valid.
An application wishing to reference the Connection or Disconnection
data after Return must copy the data from the supplied buffer to
storage owned by the application.
P5
Type: longword (unsigned)
Access: read only
Mechanism: by value
|
The usage of this argument is dependent on the specified event type
code (event_type).
For connect events (event_type=ICC$C_EV_CONNECT), this
argument contains the length (in bytes) of the buffer available for a
reply.
For disconnect events
(event_type=ICC$C_EV_DISCONNECT), this argument
contains the user-defined disconnect reason/status from the remote
partner.
P6
Type: longword (unsigned) (VAX), quadword (Alpha)
Access: read only
Mechanism: by value
|
The usage of this argument is dependent on the specified event type
code (event_type).
For connect events (event_type=ICC$C_EV_CONNECT), this
argument contains the EPID of the process requesting the connection,
passed by value.
For disconnect events
(event_type=ICC$C_EV_DISCONNECT), this argument
contains the user-defined user_context supplied when
the connection was opened. For a client, the
user_context is that supplied to the $ICC_CONNECT
call. For a server, it is the value supplied to $ICC_ACCEPT.
P7
Type: character-coded text string
Access: read only
Mechanism: by reference
|
For connect events: Username, passed by reference (to P1 space buffer)
as a 12-character, space-filled string.
The application must copy this information to local storage before
exiting from the connect routine.
For disconnect events, this argument is zero (0).
2. Data Event Routine
This routine, if supplied by the user when opening the association,
allows the user to be notified of any pending data events over any
connections subsequently opened over that association.
If the user has supplied this routine, the Receive service must only be
called in response to incoming data events signaled by this routine,
and must be called with a buffer large enough to handle the message
size specified.
Use of this routine obligates the user to allocate buffers up to the
size requested by the cooperating application. The only recovery
provided at this time if a sufficiently large buffer cannot be
allocated is to disconnect the connection. Failure to issue a receive
call or disconnect may stall all further communication on this
connection.
Format
DataEventRtn message_size ,conn_handle ,user_context
|
C Prototype:
void DataEventRtn (unsigned int message_size, unsigned int conn_handle,
unsigned int user_context);
|
Arguments
message_size
Type: longword (unsigned)
Access: read only
Mechanism: by value
|
This field will contain the number of bytes in the pending data event.
conn_handle
Type: longword (unsigned)
Access: read only
Mechanism: by value
|
The handle of the connection associated with the event. This value
should be used as the conn_handle argument to
$ICC_RECEIVE.
user_context
Type: longword (unsigned) (VAX), quadword (Alpha)
Access: read only
Mechanism: by value
|
The user-defined user_context supplied when the
connection was opened. For a client, the user context is that supplied
to the $ICC_CONNECT call. For a server, it is the value supplied to
$ICC_ACCEPT.
3. Completion ASTs
Completion ASTs may be supplied to the $ICC_CONNECT[W],
$ICC_DISCONNECT[W], $ICC_TRANSMIT[W], $ICC_RECEIVE[W],
$ICC_TRANSCEIVE[W], and $ICC_REPLY[W] services. In all cases, they are
called at the completion of the requested operation, with the single
argument, the AST parameter supplied when the original service was
called, passed by value.
Completion ASTs are not called if the service returns an error prior to
initiating the operation. $ICC_CONNECT and $ICC_ACCEPT accept the flag
ICC$V_SYNCH_MODE which indicates that the routines $ICC_TRANSMIT[W],
$ICC_RECEIVE[W], and $ICC_REPLY[W] are permitted to return the status
SS$_SYNCH, which will indicate that completion has already occurred and
the AST will not be called.
Required Access or Privileges
Refer to the OpenVMS System Manager's Manual for more information.
Required Quota
BYTCNT, BYTLM
Related Services
$ICC_ACCEPT, $ICC_CLOSE_ASSOC, $ICC_CONNECT, $ICC_CONNECTW,
$ICC_DISCONNECT, $ICC_DISCONNECTW, $ICC_RECEIVE, $ICC_RECEIVEW,
$ICC_REJECT, $ICC_REPLY, $ICC_REPLYW, $ICC_TRANSCEIVE,
$ICC_TRANSCEIVEW, $ICC_TRANSMIT, $ICC_TRANSMITW
Condition Values Returned
|
SS$_NORMAL
|
Normal completion.
|
|
SS$_ACCVIO
|
Access violation on parameter.
|
|
SS$_BADPARAM
|
Bad parameter value specified.
|
|
SS$_DUPLNAM
|
Specified association name is already registered (already exists), or
default association is already open.
|
|
SS$_EXQUOTA
|
One or more process quotas has been exceeded (probably BYTCNT/BYTLM).
|
|
SS$_INSFARG
|
Too few arguments supplied.
|
|
SS$_INSFMEM
|
Not enough system resources or process virtual memory available.
|
|
SS$_IVMODE
|
Attempt to open default association from other than user mode.
|
|
SS$_NOLINKS
|
Too many associations open for this process.
|
|
SS$_NONETMBX
|
Request requires NETMBX privilege.
|
|
SS$_NOPRIV
|
No privilege for association name access or logical name table access
if using the Registry.
|
|
SS$_SSFAIL
|
Transport association name table is full, systemwide.
|
|
SS$_TOO_MANY_ARGS
|
Too many arguments were specified.
Any failures from the system services: $ENQ, $DEQ, $CRELNM,
$TRNLNM.
|
|
