X25Decode(3X25) — Subroutines
Digital
NAME
X25Decode − Decodes an item from an Encoded Parameter List
LIBRARY
X.25 Library (libx25.a)
SYNOPSIS
#include <netx25/x25.h>
int X25Decode(
unsigned char ∗ epl ,
int eplLength ,
short itemCode ,
void ∗ itemValue ,
int ∗ itemSize );
PARAMETERS
eplPoints to the Encoded Parameter List containing the item to be decoded.
eplLengthSpecifies the size of the Encoded Parameter List epl.
itemCodeSpecifies the item code of the item to be decoded, as defined in the x25.h include file.
itemValuePoints to a buffer in which to store the decoded item. This parameter is not necessary when decoding boolean items. For integers, specify a pointer to an integer. For strings, specify a pointer to an array of characters. For lists, specify a pointer to an array of shorts.
itemSizePoints to the size of the decoded item. On entry to this routine, this parameter specifies the size of the buffer pointed to by the itemValue parameter. On return, this value is set to the actual size of the list or string decoded. This parameter should only be specified when decoding lists or strings.
DESCRIPTION
The X25Decode routine decodes a single item from an Encoded Parameter List (EPL). To decode all the items contained in an EPL, proceed as follows:
•Obtain the list of item codes contained in the EPL by calling the X25GetItemList routine.
•For each item code returned, decode the corresponding item by calling the X25Decode routine.
X.25 for Digital UNIX returns EPLs in a number of instances. Note that not all items can be returned in all cases. For details on which items are returned in a particular situation, refer to the appropriate manpage. The four instances in which EPLs are returned are described below:
Call ClearingClear facilities such as charging information are returned via the X25ReadClear routine.
Incoming Facilities
Incoming call facilities are returned prior to taking the call via the X25Listen and X25ReadCallDetails routines.
Outgoing Facilities
The outgoing call facilities are available after successfully connecting to the remote DTE. They can be determined via the X25ReadAccept routine.
Port StatusThe X25GetPortStatus routine returns data transfer values for the port such as incoming- and outgoing-packet sizes.
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 is specified, there is no associated value.
| Item Code | Description |
| X25I_AUTOMODE | Indicates that the port is set to automatic Q and M bit processing. |
| 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_REVERSECHARGE | A request that the DTE receiving the call is to be charged for the call. |
Integer
The item code and a short integer value are returned.
| Item Code | Description |
| X25I_INTMSGSIZE | Defines the maximum interrupt message size. |
| 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_REDIRECTREASON | Indicates that the call has been redirected by the PSDN or the originally called DTE. The value of the redirection reason is as follows: Call redirection due to originally called DTE busy. Call distribution within a hunt group. Call redirection due to originally called DTE out of order. Call redirection due to prior request from originally-called DTE for systematic call redirection. Call deflection by the originally called DTE. Call deflection by gateway as a result of call redirection due to originally called DTE busy. Call deflection by gateway as a result of call redirection due to originally called DTE out of order. Call deflection by gateway as a result of call redirection due to prior request from originally called DTE for systematic call redirection. |
| 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. |
X25IV_REDIRECT_BUSY
X25IV_REDIRECT_HUNT
X25IV_REDIRECT_DOWN
X25IV_REDIRECT_SYST
X25IV_REDIRECT_CALLED
X25IV_REDIRECT_GWYBUSY
X25IV_REDIRECT_GWYDOWN
X25IV_REDIRECT_GWYSYST
String
The item code, the string length (in bytes) and the string are returned.
| Item Code | Description |
| X25I_CALLEDDTE | The DTE address of the system called. This is the originally called address when a call is redirected. Represented as a string of ASCII numeric 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 contains an NSAP address formatted 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_CALLINGDTE | The X.25 DTE address of the remote host which made this call. 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_CHARGEMON | A string of octets sent by the PSDN, when the call is cleared, to indicate the monetary cost of the call. The exact format is PSDN specific. |
| X25I_CHARGESEG | A string of octets sent by the PSDN, when the call is cleared, to indicate the volume of data (measured in segments), sent during the call. The exact format is PSDN specific. |
| X25I_CHARGETIME | A string of octets sent by the PSDN, when the call is cleared, to indicate the duration of the call. The exact format is PSDN specific. |
| 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_LOCALDTE | The DTE address of the DTE on the local system on which the call was received. Represented as a string of ASCII numeric digits. |
| 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_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. |
List
The item code, the count of short integers in the list, and the list of short integers are returned.
| Item Code | Description |
| X25I_ETEDELAY | A list 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. |
EXAMPLES
The following example illustrates the decoding of a boolean item:
reverseCharge = X25Decode(epl, eplLength,
X25I_REVERSECHARGE);
The following example illustrates the decoding of an integer item:
error = X25Decode(epl, eplLength,
X25I_PKTSIZEIN, &incomingSize);
The following example illustrates the decoding of a string item:
error = X25Decode(epl, eplLength,
X25I_CALLINGDTE, caller, &callerSize);
The following example illustrates the decoding of a list item:
error = X25Decode(epl, eplLength,
X25I_ETEDELAY, eteDelay, &eteDelaySize);
RETURN VALUES
Upon successful completion, the X25Decode routine returns a value of 1. A return value of zero indicates that the item was not found in the specified EPL. If the call fails a (negative) error code is returned.
ERRORS
If the X25Decode routine fails, one of the following error codes is returned:
[X25RC_BADEPL]
The specified EPL is not a correctly formatted EPL. Either the epl parameter does not contain a valid EPL, or the eplLength parameter does not match the EPL.
[X25RC_USRBUFSIZE]
The specified buffer is too small to contain the requested data. The itemValue parameter is not big enough to contain the requested list or string. As much of the list or string as will fit is returned in itemValue; the actual size of the list or string is returned in itemSize.
RELATED INFORMATION
Functions: X25Encode(3X25), X25GetItemList(3X25), X25GetPortStatus(3X25), X25Listen(3X25), X25ReadAccept(3X25).
DECnet/OSI − Network Control Language Reference,
X.25 for Digital UNIX − Programmer’s Reference Manual.