X25Encode(3X25) — Subroutines
Digital
NAME
X25Encode − Encodes items into an Encoded Parameter List
LIBRARY
X.25 Library (libx25.a)
SYNOPSIS
#include <netx25/x25.h>
int X25Encode(
unsigned char ∗ epl ,
int eplLength ,
... ,
X25I_NULL );
PARAMETERS
eplPoints to the buffer in which the parameter list item(s) will be encoded.
eplLengthSpecifies the maximum size of the Encoded Parameter List returned.
X25I_NULL
Indicates the end of the items to be encoded. X25I_NULL must be specified as the last parameter.
DESCRIPTION
The X25Encode routine encodes a set of X.25 call parameters into the array epl, which is of size eplLength. The call parameters are specified as items in a variable length parameter list.
The call parameters encoded by X25Encode are used to override the call parameters in the X25 Access Template entity when an outgoing call request is made, or an incoming call is accepted.
There are four different types of items that can be contained in an EPL, namely boolean, integer, string, and list items. The item codes that belong to each of these types are described in the following sections.
Boolean
Only the item code below is specified, there is no associated value.
| Item Code | Description |
| X25I_CHARGEINFO | Request that the PSDN return information about the cost, duration, and volume of data sent in the call when the call is cleared. |
| X25I_EXPEDITE | Indicates that X.25 interrupt messages can be used during the data transfer phase of the call. Not valid on 1980 networks. |
| X25I_FASTSELECT | A request for a Fast Select call. |
| X25I_FASTSELECTRESTR | A request for a Fast Select call with Restricted Response. |
| X25I_NOEXPEDITE | Indicates that X.25 interrupt messages cannot be used. Not valid on 1980 networks. |
| X25I_NSAPMAP | Indicates that the address supplied with the X25I_CALLEDEXTISO item is to be transformed into an X.25 DTE address and optionally a called address extension by the use of the X25 Access Reachable Address entities. For more information refer to the DECnet/OSI − Network Control Language Reference. |
| X25I_REVERSECHARGE | A request that the DTE receiving the call is to be charged for the call. |
Integer
The item code followed by one short integer value are specified.
| Item Code | Description |
| X25I_MINTHRUCLSIN | |
| X25I_MINTHRUCLSOUT | The minimum input and output throughput class for the call. Not valid on 1980 networks. |
| X25I_PKTSIZEIN | |
| X25I_PKTSIZEOUT | The desired packet size for the call. |
| X25I_THRUCLSIN | |
| X25I_THRUCLSOUT | The desired input and output throughput class for the call. |
| X25I_TRANSITDELAY | Indicates to the called DTE the transit delay calculated by the user. The transit delay is expressed in milliseconds and is a binary integer. A value of 65535 (0xffff) indicates that the value is not known, or exceeds 65534 milliseconds. |
| X25I_WINSIZEIN | |
| X25I_WINSIZEOUT | The desired window size for the call. |
String
The item code, the string length (in bytes) and the address of the string are specified. Zero-length strings will be ignored.
| Item Code | Description |
| X25I_CALLEDDTE | The X.25 DTE address of the host to which this connection is being made. Represented as a string of ASCII digits. |
| X25I_CALLEDEXTISO | The Network Service Access Point (NSAP) address of the system being called. Used in conjunction with the X25I_NSAPMAP item code to perform NSAP to DTE address translation. This string must contain a correctly-formatted NSAP address according to ISO 8348, preceded by an octet (byte) that contains the count of semi-octets in the NSAP. The whole string can have a maximum length of 21 octets (bytes). Not valid on 1980 networks. |
| X25I_CALLEDEXTNONISO | The Called Address Extension of the system being called. This code is used for address extensions that are not formatted according to ISO 8348. The format is as defined in X25I_CALLEDEXTISO. Not valid on 1980 networks. |
| X25I_CALLEDSUBADDR | The X.25 sub-address of the object on the remote DTE to which the call is destined. Represented as a string of ASCII digits. |
| X25I_CALLINGEXTISO | The Network Service Access Point (NSAP) address of the calling system. This must be a correctly-formatted NSAP address according to ISO 8348. The format is as defined in X25I_CALLEDEXTISO. Not valid on 1980 networks. |
| X25I_CALLINGEXTNONISO | The Calling Address Extension of the calling system. This code is used for address extensions that are not formatted according to ISO 8348. The format is as defined in X25I_CALLEDEXTISO. Not valid on 1980 networks. |
| X25I_CALLINGSUBADDR | The X.25 local sub-address of the current client making the outgoing call. This is often used for addressing objects within a specific DTE. Represented as a string of ASCII digits. |
| X25I_CUG | The name of the Closed User Group (CUG) or Bilateral Closed User Group (BCUG) to be used when making the call. This name must correspond to the name of an X25 Protocol Group entity. For more information on CUGs and BCUGs, refer to the DECnet/OSI − Network Control Language Reference. |
| X25I_DTECLASS | The name of the X25 Access DTE Class entity to be used on an outgoing call. |
| X25I_NETUSERID | The name of the network user. The format of this string is specific to a local authority. |
| X25I_NONX25FACILITIES | A string of non-X.25, non-CCITT facilities that have significance to the local PSDN, or the remote PSDN in the case of an internetwork call. The first octet of these facilities must be the local/remote facility category indicator − 0 for local, 255 (0xff) for remote. |
| X25I_PRIORITY | A string of maximum length 6 octets used to indicate to the PSDN the priority that is desired for this call, to gain a connection, and keep a connection. Not valid on 1980 networks. |
| X25I_PROTECTION | A string of octets that define the protection desired for this call. Not valid on 1980 networks. |
| X25I_TEMPLATE | The name of the X25 Access Template entity to be used for the call accept when the X25AcceptCall routine is called. The call parameters in this template are combined with the encoded call parameters to form the set of call parameters specified in the call accept packet. |
| X25I_USERDATA | A string of octets to be passed in the call request, or call accept packet. The length of the string can be up to 128 octets in the case of a fast select call and up to 16 octets otherwise. Zero-length strings will be ignored. |
List
The item code, the total size of the list (in bytes), and the address of the list of short integers are specified.
| Item Code | Description |
| X25I_ETEDELAY | An array of one, two, or three short integers. The first integer is the Cumulative End-to-End Transit Delay, which indicates the estimated value of transit delay from one end of the network connection to the other. The second integer is the Desired End-to-End Transit Delay, which indicates the target value requested for the network connection. The third integer is the Maximum End-to-End Transit Delay, which indicates the largest acceptable value. Each transit delay value is expressed in milliseconds and is a binary integer. A value of 65535 (0xffff) indicates that the value is not known, or exceeds 65534 milliseconds. Not valid on 1980 networks. |
| X25I_RPOASEQUENCE | A list of Recognized Private Operating Agency (RPOA) Data Network Identification Codes (DNICs) that indicate the network to which the call is addressed. |
RESTRICTIONS
Some of the parameters described above can only validly be set via an X25MakeCall routine prior to an outgoing call request.
The following values are not valid for an incoming call accept, that is an X25AcceptCall routine:
| X25I_CALLEDDTE | X25I_FASTSELECT |
| X25I_CALLEDSUBADDR | X25I_FASTSELECTRESTR |
| X25I_MINTHRUCLSIN | |
| X25I_CALLINGEXTISO | X25I_MINTHRUCLSOUT |
| X25I_CALLINGEXTNONISO | X25I_NSAPMAP |
| X25I_CALLINGSUBADR | X25I_REVERSECHARGE |
| X25I_CUG | X25I_RPOASEQUENCE |
| X25I_DTECLASS | X25I_TRANSITDELAY |
The X25I_TEMPLATE parameter, that is the name of the template to be used in the outgoing call request, must be specified as a parameter value when the X25MakeCall routine is called.
For information on the validity of each item code, refer to the appropriate manpage.
EXAMPLES
The following example illustrates a call using each type of parameter.
short rpoaList[2] = {0x4401, 0x5052};
int rpoaLength = sizeof(rpoaList) / sizeof(rpoaList[0]);
error = X25Encode(epl, eplLength,
X25I_REVERSECHARGE,
X25I_PKTSIZEIN, 256,
X25I_CALLEDDTE, strlen("1234567"), "1234567",
X25I_RPOASEQUENCE, rpoaLength, rpoaList,
X25I_NULL);
RETURN VALUES
Upon successful completion, the X25Encode routine returns the length of the EPL. Otherwise, a (negative) error code is returned.
ERRORS
If the X25Encode routine fails, one of the following error codes is returned:
[X25RC_BADEPL]
The specified EPL is not a correctly formatted EPL. The epl parameter does not contain a valid EPL. The most likely reason is that the EPL was not initialized before attempting to encode items into it.
[X25RC_BADPARAM]
One of the items specified does not have a recognized X.25 item code. The permissible item codes are defined in the x25.h include file.
[X25RC_EPLSIZE]
The specified EPL is too small to contain the requested items. As many of the items as will fit are returned in epl.
RELATED INFORMATION
Functions: X25AcceptCall(3X25), X25ClearCall(3X25), X25Decode(3X25), X25GetItemList(3X25), X25MakeCall(3X25).
DECnet/OSI − Network Control Language Reference,
X.25 for Digital UNIX − Programmer’s Reference Manual.