Digital

NAME

X25OpenPVC − Associates an existing X.25 port with a Permanent Virtual Circuit (PVC) and returns the current state of the PVC. 

LIBRARY

X.25 Library (libx25.a)

SYNOPSIS

#include <netx25/x25.h>
int X25OpenPVC(

int pd ,
int dataMode ,
unsigned char ∗ epl ,
int eplLength ,
char ∗ PVCName );

PARAMETERS

pdIdentifies an existing open port with which to associate the Permanent Virtual Circuit with. 

dataModeSpecifies the data-transfer mode in which the port is to operate.  A value of 1 sets the port to Manual Mode.  A value of 0 sets the port to Automatic Mode. 

eplPoints to an Encoded Parameter List containing the parameters that define the operation of the PVC.  Presently, there are no valid epl items for an X25OpenPVC operation and this argument must be specified as NULL. 

eplLengthSpecifies the length of the Encoded Parameter List, epl.  This must be set to 0. 

PVCNamePointer to a null-terminated string containing the name of the Permanent Virtual Circuit with which the port should become associated. 
 

DESCRIPTION

The X25OpenPVC routine associates a Permanent Virtual Circuit with an existing X.25 port that has been previously created with the X25OpenPort routine.  If successful, this routine also returns the Permanent Virtual Circuit state.  Currently there are no valid epl items for PVCs, therefore the epl and eplLength arguments must be NULL.  Encoded Parameter Lists are further described in the X25Encode(3X25) manpage.  The PVCName parameter is a string identifying an existing X.25 PVC management entity. 

The dataMode parameter controls the data transfer mode of the connection.  To operate in Manual Mode, where the user controls the More data bit, Qualified data bit and packetization, the dataMode parameter must be set to a non-zero value.  To operate in Automatic Mode, where all packet fragmentation and re-assembly are handled by the system, the dataMode parameter must be set to zero. 

The X25OpenPVC routine blocks, (unless the port has been set to non-blocking by a call to X25SetIOMode), until the PVC is connected or an error is encountered.  On successful completion, the port state is returned and will be one of the following values:

X25S_RUNNING
The PVC is in an X.25 state suitable for data transfer, however it is advisable that if upon opening, a PVC is found in this state, a reset is initiated via X25SendReset.  This is necessary since any data transferred by the remote end while there was no port associated with the PVC, will have been discarded.  A reset is therefore advisable in order to initiate re-synchronization between the two ends. 

X25S_SYNCThe local system is waiting for a reset confirmation to be returned from the remote end.  No immediate action is required but data transfer can not continue until a reset confirm has been received. 

X25S_UNSYNC
the remote end has instigated a reset, which has not been confirmed by the local application.  A call to X25SendReset must be performed to take the link to a state where data transfer can continue. 

RETURN VALUES

Upon successful completion, the X25OpenPVC routine returns the current port state.  Otherwise, a (negative) error code is returned. 
 

ERRORS

 
If the X25OpenPVC routine fails, one of the following error codes is returned:

[X25RC_BADPD]
Invalid port descriptor specified.

[X25RC_BADPARAM]
Non NULL epl specified.

[X25RC_INPROGRESS]
The specified port is operating in non-blocking mode, and the X25OpenPVC operation is still in progress. 

[X25RC_INVALSTATE]
The port is not in a valid state to perform the requested operation. There is a connection already established on this port.

[X25RC_PVCBUSY]
The PVC requested in PVCName, is already associated with an existing X25 port and therefore can not be assigned to this port. 

[X25RC_SECURITY]
The call has been blocked by X.25 security.  For details on X.25 security, refer to X.25 for Digital UNIX − Security Guide. 

[X25RC_SERVICEDOWN]
The X.25 service is not available because an entity is not in the correct state.  Either the X25 Access entity is disabled, or the X25 Protocol entity does not exist.

[X25RC_PVC]
The PVC entity specified in PVCName, does not exist. 

RELATED INFORMATION

Functions: X25OpenPort(3X25),

X.25 for Digital UNIX − Programmer’s Reference Manual,
X.25 for Digital UNIX − Security Guide.