Third Edition (April 1996)

This edition of applies to AIX Version 3.2.5, AIX Version 4.1, and to all subsequent releases of these products until otherwise indicated in new releases or technical newsletters.

THIS MANUAL IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions; therefore, this statement may not apply to you.

It is not warranted that the contents of this publication or the accompanying source code examples, whether individually or as one or more groups, will meet your requirements or that the publication or the accompanying source code examples are error-free.

This publication could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication.

It is possible that this publication may contain references to, or information about, products (machines and programs), programming, or services that are not announced in your country. Such references or information must not be construed to mean that such products, programming, or services will be offered in your country. Any reference to a licensed program in this publication is not intended to state or imply that you can use only that licensed program. You can use any functionally equivalent program instead.

The information provided regarding publications by other vendors does not constitute an expressed or implied recommendation or endorsement of any particular product, service, company or technology, but is intended simply as an information guide that will give a better understanding of the options available to you. The fact that a publication or company does not appear in this book does not imply that it is inferior to those listed. The providers of this book take no responsibility whatsoever with regard to the selection, performance, or use of the publications listed herein.

NO WARRANTIES OF ANY KIND ARE MADE WITH RESPECT TO THE CONTENTS, COMPLETENESS, OR ACCURACY OF THE PUBLICATIONS LISTED HEREIN. ALL WARRANTIES, EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE SPECIFICALLY DISCLAIMED. This disclaimer does not apply to the United Kingdom or elsewhere if inconsistent with local law.

A reader's comment form is provided at the back of this publication. If the form has been removed, address comments to Publications Department, Internal Zip 9561, 11400 Burnet Road, Austin, Texas 78758-3493. To send comments electronically, use this commercial internet address: . Any information that you supply may be used without incurring any obligation to you.

© Copyright International Business Machines Corporation 1994, 1996. All rights reserved.

Notice to U.S. Government Users -- Documentation Related to Restricted Rights -- Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract.

Trademarks and Acknowledgements

The following trademarks and acknowledgements apply to this book:

AIX is a registered trademark of International Business Machines Corporation.

AIX is a registered trademark of International Business Machines Corporation.

AS/400 is a registered trademark of International Business Machines Corporation.

CICS is a trademark of International Business Machines Corporation.

Hayes is a trademark of Hayes Microcomputer Products, Inc.

IBM is a registered trademark of International Business Machines Corporation.

Micro Channel is a registered trademark of International Business Machines Corporation.

Portmaster is a registered trademark of International Business Machines Corporation.

PS/2 is a registered trademark of International Business Machines Corporation.

RS/6000 is a trademark of International Business Machines Corporation.

System/370 is a trademark of International Business Machines Corporation.

System/390 is a registered trademark of International Business Machines Corporation.

SNA 3270 is a trademark of International Business Machines Corporation.

UNIX is a registered trademark in the United States and other countries, licensed exclusively through X/Open Company Limited.

VTAM is a registered trademark of International Business Machines Corporation.

About This Book

The provides information on using, managing, and programming the AIX/Link X.25 Version 1 application for AIX Versions 3.2.5 and 4.

The information in this book can also be found in the Hypertext Information Base Library Version 1 for AIX. This online documentation is designed for use with the InfoExplorer hypertext retrieval system.

Who Should Use This Book

This book is intended primarily for system administrators and application developers for X.25, but it also contains some end-user information.

Highlighting

The following highlighting conventions are used in this book:

ISO 9000

ISO 9000 registered quality systems were used in the development and manufacturing of this product.

Related Publications

The following books contain information about or related to AIXLink/X.25 1.1:

Ordering Publications

You can order publications from your sales representative or from your point of sale.

To order additional copies of this book, use order number SC23-2520.

Use for information on related publications and how to obtain them. The is available:

http://www.ibm.com/

Chapter 1. X.25 Network Communications Overview

X.25 can be a cost-effective means of networking systems in a wide geographical area, compared to traditional dial-up (circuit switched) connections, or remote-bridged local area networks (LANs) connected by leased lines. It provides worldwide interconnection for international corporations.

X.25 provides the ability to transmit data between remote machines. It is a set of recommendations from the International Telegraph and Telephone Consultative Committee (CCITT). These recommendations define a standard network access protocol for attaching different types of computer equipment to a packet-switched data network (PSDN) . A PSDN is an interconnecting set of switching nodes that enables subscribers to exchange data using a standard protocol and packet-switching technology. This protocol is particularly useful for communication between different types of computer systems and for accessing public databases.

Both public and private PSDNs can be based on the X.25 protocol. Public networks are usually provided nationally by the Post, Telegraph, and Telecommunications (PTT) authority. Private networks are operated by individual corporations. Many of the corporations using X.25 networks have a requirement for communication between themselves and other companies, such as dealers and agents. An example of such an X.25 network use is an airline reservation system.

Although some corporations have created private networks, most companies subscribe to a public PSDN. Such a network carries messages divided into packets over circuits that are shared by many network users. A single physical line into an office can handle many concurrent connections. A consists of a sequence of data and control elements in a format that is always transmitted as a whole. The network packet size is commonly 128 bytes, but can vary from 16 to 4096 bytes. In X.25, a byte is called an .

You can use X.25 communications to provide a network service for higher-level protocols , such as System Network Architecture (SNA) and Transmission Control Protocol/Internet Protocol (TCP/IP) . Or you can use an X.25 network directly, either by using the command , or by using an application programming interface (API) to write your own applications.

X.25 Equipment Terminology

The terms DTE, DCE, and DSE are used with both the X.25 protocol and modems, with slightly different meanings. The CCITT has defined these terms as follows for X.25 protocol:

X.25 is not an end-to-end protocol. defines a standard protocol for information exchange in packet mode between a DTE and a DCE (that is, between an individual user's equipment and the network provider's equipment).

The network is composed of DCEs and DSEs that route the packets of data through the network to the intended destination. The path that a user's data takes might vary with every packet. In most cases the DTE is connected to a DCE in some form of network. In a few cases, two systems might be attached more directly, without an intermediate network. When this is the case, one system has to act as a DCE at the Data Link layer. This usage is not common because it restricts the flexibility of the protocol and degrades performance.

Operation and maintenance of DCEs and DSEs are the responsibilities of the network provider. If a link between two DSEs goes down, the provider must reroute traffic. X.25 does not define the route through the network or the protocols employed within it.

The X.25 Network shows the elements of a packet-switched data network.

X.25 Levels

Several models have been used to specify how networks work. One of the most common of these conceptual models is the International Standards Organization's Open System Interconnect (OSI) Reference Model , also referred to as the OSI 7-layer model . The OSI model numbers the seven layers, or levels, beginning at the lowest (physical) level, as follows:

Levels 1-3 are network-specific, and differ depending on the physical network used. Levels 4-7 are network-independent, higher-level functions. The X.25 protocol has three levels . These levels correspond to Levels 1, 2, and 3 of the OSI model as follows:

The X.25 protocol can be quite complicated to set up. If protocol information is required, refer to a communications textbook. Each layer relies on the lower layers to be functional for it to work. If a problem is encountered when setting up an X.25 connection, each layer should be checked to see if it is active.

Physical Level

The physical level activates, maintains, and deactivates the physical circuit between a DTE and a DCE. The physical level is implemented as a STREAMS driver and performs the following functions:

This implementation supports three physical interfaces: V.24, V.35, and X.21bis. CCITT recommendations V.24 and V.35 are found in 1988 volume VIII.I. The CCITT X.21bis is found in volume VIII.

Link Level or Frame Level

The packet layer produces X.25 packets to establish calls and transfer data. All these packets are then passed to the frame layer for transmission to the local DCE. The frame layer uses a link-access procedure to ensure that data and control information are accurately exchanged over the physical circuit between the DTE and DCE. It provides recovery procedures and is based on a subset of the high-level data-link control (HDLC) protocol called LAP-B . It is synchronous and full-duplex. Once a link is started, either station can transfer information without waiting for permission from the other.

In HDLC all commands, responses, and data are transmitted in frames. Each frame has a header containing address and control information, and a trailer containing a frame-check sequence. Normally, none of this is seen when using X.25.

The three types of frames are:

Packet Level

The packet-level protocol specifies how X.25 controls calls and data transfers between systems. There are many networks running X.25, and a number of these are interconnected. Each system connected to the network has an address to identify it, and this address is used when a connection from the local system to the remote is being requested.

When a system is installed with X.25 and a network subscription obtained, various pieces of configuration information are supplied by the network provider. This information is used to configure the X.25 software. One or more X.25 lines can be connected and for each line, an X.25 port will be configured.

The data transfer capacity of the X.25 line may be shared between a number of different sessions. The maximum number of subscriptions is based on the network subscription and the capabilities of the DTE hardware and software. Each session is called a . A virtual circuit is a data circuit between the local and remote systems, but a circuit that may have its route switched within the network. The element of the network subscription that limits the number of simultaneous virtual circuits in use is the number of subscribed to. Each virtual circuit takes up a logical channel for the period the circuit is active.

Logical Channels

Logical channels are the communications paths between a DTE and its data circuit-terminating equipment (DCE). For 15 simultaneous connections across a network, the network supplier must provide 15 logical channels. Valid logical channel numbers range from 1 to 4095 (logical channel number 0 is usually reserved for diagnostics). The network provider assigns the specific logical channel numbers, and each number must match between the DTE and its DCE. For example, a DTE configured to use logical channels 51-58 could not communicate with its DCE using logical channels 3002-3009. However, when a DTE communicates with another DTE across a packet-switched data network (PSDN), the DTE logical channel numbers do not have to match. The logical channel is not end-to-end in the network; it must only match between each DTE/DCE pair, as shown in the Logical Channels and Virtual Circuits .

Virtual Circuits

When a user application begins a session with another DTE on the network, a virtual circuit is established from one DTE to the other, through the DCEs on the network. For an outgoing call, the system that originates the call automatically selects a free channel. When an incoming call is received, the system's local DCE selects the channel. Each application running between two hosts requires use of a virtual circuit. There are two kinds of virtual circuits, permanent (PVC) and switched (SVC), of which SVCs are the more commonly used. Normally when using an SVC, it is not necessary to know the logical channel number in use; the X.25 software ensures that the data from a given session goes over the appropriate virtual circuit. It is necessary to know the logical channel number a given session is on when using PVCs or when tracing the traffic on the X.25 line.

Some applications multiplex their own connections over one virtual circuit. For example, in AIX, once a virtual circuit is established between two machines for TCP/IP , all TCP/IP traffic between those machines flows on that circuit.

It is important that the virtual circuit ranges used for configuration agree with those defined by the network provider.

Permanent Virtual Circuits

Configure permanent virtual circuits (PVCs) to agree with the network provider's subscription. The subscription is permanently configured so that the PVC occupying a particular local communications network (LCN) connects to a remote machine on a specified LCN on the remote machine. This allows call setup time to be saved, but dedicates the channel to that one remote system. This makes PVCs less flexible and less likely to be used.

Switched Virtual Circuits

A switched virtual circuit (SVC) is a virtual circuit that exists only for the duration of the call, acting like a connection over a telephone network. There are three types of logical channels for SVCs:

These channel types are significant only during call initiation. Once a virtual circuit has been established, it is always for two-way communication. Typically, only two-way SVCs are used. However, if more than one type is used, the CCITT states that the logical channel numbers must be assigned within the following hierarchy, from the lowest logical channel numbers to the highest:

If a system has only two-way SVCs, then it is possible that at any given time they could all be in use by incoming calls. If the ability to make an outgoing call must to be guaranteed, then an outgoing-only SVC would perform that function.

Network User Address

Each system on an X.25 network has an address to identify it. This address is supplied by the network provider. To ensure that the address is unique across different network providers and between different countries, the X.121 specification defines an international numbering scheme that ensures a unique DTE address. This address is called the network user address (NUA) . For communication between systems, it is the remote system's NUA that must be known.

Most public networks use the X.121 addressing standard (defined in CCITT Volume VIII.3) to create NUAs. Under the X.121 addressing standard, an NUA consists of the following parts:

Data Network Identification Code

A data network identification code (DNIC) consists of 4 digits that include:

Because of the limitation of 1 digit to define only 10 PDNs within one single country, the United States obtained CCITT permission to use 1 digit for the DCC and 2 digits to specify a PDN.

National Terminal Number

Following the DNIC are 10 digits assigned by the PDN. No rule determines how the national terminal numbers (NTNs) are made up. Most PDNs reserve the last 2 digits as an optional subaddress for the X.25 subscriber. It is the NTN, when communication is made within a given network, that is often given as the system's NUA. The optional subaddress is not processed by the PDN, but is available to identify a finer granularity of address on the remote system. The DNIC is usually used when the remote system is on a different network from the calling system.

The following shows the structure of the network user address (NUA), leaving two digits for the subaddress.

      1234                      56789012                    34       

The X.121 addressing standard also defines a 1-digit optional prefix for international calls. If a call is beyond PDN boundaries, the user or application establishing the call can add a 0 or a 1 at the beginning of the NUA. If a call is within PDN boundaries, no prefix is necessary. The maximum length of an NUA is 15 digits.

X.25 Usage

Once all three layers are active, the DTE can set up calls and transfer data to other DTEs. To do this, the X.25 protocol uses different types of packets to make or accept the call, transfer data, and end calls. The X.25 communications software performs most of the tasks involved in creating the packets. You do not need to know the contents of each packet, you need only supply the information necessary to create it.

The way calls work on SVCs is different from the way calls work on PVCs. SVCs are more commonly used, and they initiate the DTE to DTE connection with a call-request packet.

The DTE to DTE connection shown in the illustrates how a call is set up, used, and cleared. The call uses a virtual circuit for the duration of the call. This circuit can be reused once the call is over.

Data sent during the call is divided up into units. The size of these units is the . Packet size applies to the size of each data packet, not all packets. The default packet size is 128 bytes. When one unit of data needs to be sent that is greater than the packet size, a number of packets are sent. This sequence of packets is marked to indicate that it makes up one unit of data through use of a flag called the or bit. The packet size can be varied from 128 either through configuration or at call setup time. Allowing more data in each packet can have performance gains as there is a degree of overhead for every packet sent. The packet size is one of the call's characteristics that can be changed at call setup. Requests to make changes at this time are controlled by .

Usually the calling DTE is responsible for inserting all the facility requests it needs. Sometimes though, the network inserts the facility requests into the call packet to indicate to the remote DTE certain characteristics of the local DTE, one of which can be packet size. The contents of a packet, when it reaches the called DTE, may be different from the packet that left the calling DTE. Packet contents may change because some information differs for each DTE (for example, logical channel numbers) or only applies to one of the DTEs. The name given to a packet also varies to indicate if it is received or sent.

Packets are grouped into the following categories, according to type:

Call Setup

The call-setup packets contain different types of information:

Call-Time Facilities

A is a service provided by the X.25 network. Some facilities are offered as options by the network provider. Negotiating packet size, for example, is a standard facility on most networks, while reverse-charging acceptance is optional. Some optional facilities, such as reverse-charging acceptance, are valid for all virtual calls. Other facilities, such as reverse charging, must be specifically requested for the duration of a call. Certain facilities can be allowed or disallowed for a given X.25 port. If not disallowed, the requested facilities can be used during call setup.

The X.25 facilities and their coding are defined in the , Sections 6 and 7. The facilities you can use are defined in your X.25 subscription.

To use a valid facility during a virtual call, a facility request and the facility's corresponding parameters must be inserted in the call packet. The X.25 program on the data terminal equipment (DTE) can insert a facility request in the call request (calling DTE) or in the call accepted (called DTE) packet. Coding of the facilities is the responsibility of the X.25 application and not of the application programming interface (API), device driver, or X.25 microcode.

The network DCE can also notify the DTE of the use and parameters of a facility. The DCE inserts a facility indication, either in the incoming-call packet or in the call-connected packet. The Facilities and Call Packets illustrates the call-packet names.

The following table lists the main facilities that may be requested by the DTE or the DCE for the duration of a call.

The Throughput Class Selection facility allows you to change your default throughput class (measuring the transmission speed within the network) to a lower value. This action does not affect the DTE-to-DCE speed, only the speed at which a packet traverses the switching nodes in the network.

Coding and Decoding Facilities

The Call Packet Structure shows the structure of a call packet. Call requests, incoming calls, call-accepted packets, and call-connected packets all have the same structure.

Facility requests or facility indications are inserted between the address block and the call user data (CUD) and are prefixed by an octet containing the total length of the facilities. For information on coding and decoding facilities, see .

Facilities Requested by the DTE

Your application is responsible for coding a facility you want to use and inserting it in the call-request or call-accepted packet. The command , Transmission Control Protocol/Internet Protocol (TCP/IP) , and System Network Architecture (SNA) Services allow the user optionally to define a facility request to be inserted in the call packet.

X.25 Network Subscription

The network provider must supply some information about a connection before a user can connect to the network. The network provider assigns the DTE address (NUA), the logical channel numbers, and the types of virtual circuits. Additional attributes must also match between the DTE and the network's DCE .

The network supplier provides the X.25 attachment attributes that must be used to configure the DTE for a particular network subscription. Suppliers create subscriptions based on their network conventions, DCE hardware, and customers' requirements, such as performance, number of concurrent connections, and security needs. The network attachment speed and the DCE hardware determine the adapter and interface choice, so customers should check with the network provider before making these hardware choices.

To configure an AIX DTE, the network provider should be told that the X.25 device driver requires the following attachment characteristics:

The X.25 licensed program supports CCITT up to 1988.

Chapter 2. X.25 Licensed Program Functionality

This chapter discusses the functionality of the X.25 Licensed Program interface. The X.25 Licensed Program provides the following functionality:

Each of these functional areas is covered in more detail in the relevant chapters.

Configuration Structure

With multiport adapters , more than one X.25 port can be associated with a given adapter. When the Licensed Program is configured, X.25 ports are set up to use the available ports on a given communications adapter. Supported under AIX are the X.25 Interface Adapter and the ARTIC Portmaster Adapter, with its V.24, V.35 or X.21 interfaces. These adapters produce device instances of the form and , respectively. When configuring the Licensed Program, the X.25 support can be added to any of the available adapters. If an adapter is to be used by the X.25 Licensed Program, then its device driver has to be associated with the adapter. Once a device driver is configured onto a given adapter, then as many ports as the adapter supports can be configured. The main device used is the X.25 port as shown in the following .

The device driver is associated with the adapter, and there can only be one available per adapter. The X.25 ports are associated with the individual communication ports supported by the adapter, which can vary from one up to eight. It is the individual X.25 ports that must be configured with their NUA, packet information, and so forth. For example, when the traffic on an X.25 line is traced, the port name, is passed to .

When each device is added to the systems configuration, be it a device driver or an X.25 port, it is given an instance number based on what is next available. This means the device driver's instance number might not match the adapter it is configured on. The relationship between what ports are configured on a given device driver or adapter can be viewed through or by entering the command.

Once an X.25 port is available, it can be used by a number of possible applications:

Triple-X PAD

A PAD allows remotely attached ASCII terminals to access applications running in X.25 based hosts. Refer to for more details.

The PAD support can be enabled or disabled for the system, refer to . If enabled, one instance of X.29 supports all the configured X.25 ports, servicing all remote terminals using the PAD. Where the system is being used as a terminal PAD, each terminal has its own X.3/X.28 session.

COMIO

Each X.25 port can have COMIO emulation enabled. This emulation produces a programming interface compatible with that in the base AIX Version 3 X.25 support. Applications such as can use the emulation without recompiling. To allow for this emulation, a device entry is created with the same device name that would have been generated by the base AIX Version 3 X.25 support - . Refer to for details on using this emulation.

Not all applications supplied with Version 3 are supported. and do not apply to the Licensed Program's emulation ports. can be used to trace the activity of the X.25 line.

The following shows how driver instances relate.

See "Appendix H. Using AIXLink/X.25 over the IBM 2-Port Multiprotocol Adapter" for information on differences when using 2-Port Multiprotocol Adapters.

STREAMS

The X.25 Licensed Program works under the environment. Refer to the section on STREAMS in the for more details on how this works under AIX.

When an X.25 port is configured, the various modules of supporting code are loaded into the environment as shown in the following figure. Then the driver and modules are pushed to create the protocol stack.

Once the system is configured for use, the STREAMS setup happens automatically. Applications of NPI and the instances of the X.3/X.28-based PAD require that an instance of the module be pushed onto the stream. This is taken care of by the application.

For more information on STREAMS concepts and programming, refer to the published by Prentice Hall and by Stephen A. Rago, published by Addison-Wesley, Reading, Massachusetts.

See "Appendix H. Using AIXLink/X.25 over the IBM 2-Port Multiprotocol Adapter" for information on how the x.25 modules are loaded into STRAMS when using 2-Port Multiprotocol Adpaters.

Chapter 3. X.25 Migration

This chapter describes the differences between X.25 Support on AIX Versions 3 and 4.

Chapter 4. X.25 Installation and Configuration

The following information explains what you need to install the X.25 program and how to configure your system for X.25 communications.

Before you install the X.25 program, ensure that your system meets the minimum software and hardware requirements.

Minimum Requirements

Software

You need the following software:

or

Hardware

You need the following hardware:

The interrupt level of this adapter is set using switches on the adapter. The interrupt level should be set to match the other adapters installed. Refer to the system unit's documentation for more details.

The PowerPC model must have PCI slots in order to use this adapter.

Planning Your X.25 Installation

The best method for data transfer over a wide area network depends on a number of factors. Among the common factors are the amount of data traffic, the frequency that data is sent, response time required, and so forth. Along with these, the tariff available for the network providers can play an important part in protocol choice.

Once X.25 is decided upon, the specifics of the network subscription must be planned along with the network provider. Switched virtual circuits can be used by different applications, possibly to different remote destinations, at different times. Permanent virtual circuits are dedicated to a given remote destination. Depending on the type of X.25 traffic that is generated, the number and speed of X.25 lines must be decided, along with the number of virtual circuits, and so forth.

With the characteristics of the X.25 interfaces defined, X.25 adapters (X.25 Co-Processor/2 or the ARTIC Portmaster Adapter) to support these interfaces must be added to the system. Choice of adapter and line interface depends on the characteristics of the network subscription.

If you are using an AIX Version 3 system, the base AIX Version 3 X.25 may already be in use. With the base system active, it should be decided which adapters should be used to support the old X.25 system and which should be used to support the licensed program.

If your X.25 applications use the Data Link Provider Interface (DLPI), and you are migrating to AIXLink/X.25 Version 1.1.4 from a prior version of the product, you may need to make changes to your DLPI applications.

The changes are necessary to allow your applications to make use of all adapters supported by the AIXLink/X.25 product. If your DLPI applications are not configured to use the IBM 2-Port Multiprotocol PCI adapter, then the changes are not strictly required. See Chapter 6, , for more information.

Installation Procedure

The X.25 licensed program is delivered as an install-image. To install the X.25 program:

Hardware Installation

The adapters should be installed as described in the system unit's documentation.

Method error (/usr/lib/methods/define):
     0514-022 The specified connection is not valid. 

/usr/lpp/sx25/inst_root/sx25.rte.config

Please order the appropriate cable for your interface equipment.

Configuration Commands

The X.25 Licensed Program can be configured directly from the command line if this is desired, though for most users the SMIT interface is preferable. A set of general system and specific X.25 commands allow the X.25 system to be configured.

Managing Device Driver

Instances of the adapter device driver are added and deleted through the system commands and . The port and adapter numbers used in the following examples would have to be replaced by those needed on a particular system.

mkdev -c driver -s artic -t star -w0 -p 'apm1'

This assumes a Portmaster adapter, but could equally be a coprocessor For more details, see the command.

rmdev -l twd1

Moves the driver to the defined state. Using the option also removes the configured data from the database. For more details, see the command.

lsdev -C -t star lsx25

For more details, see the or commands.

Managing X.25 Ports

To manage the X.25 ports, the X.25 commands listed should be used.

The following is only an example.

NPI STREAMS Programming

The NPI interface works in the STREAMS environment. The following provides an overview of how to program to the STREAMS interface.

Initially the module is not available for use by an application, and the application itself must push it onto a stream.

For an application to work with NPI in the STREAMS environment, the NPI module must be available to STREAMS applications. Once the AIX software is installed on a system, the NPI module is made available. Then applications that link to the STREAMS library are able to access the NPI module. The way that an application "pushes" NPI is shown in the following sample of pseudo code:

dev=open("/dev/x25pkt", O_RDWR);        assumes good return value
ioctl(dev, I_PUSH, "npi");              uses the streams library
                                        push ioctl

Once pushed, the application would then bind to NPI. See the primitive for more details. The application uses the functions and to communicate with NPI. Detailed under the STREAMS documentation, examples of their use with NPI are given under some of the primitives. An example of programming to NPI can be seen in the licensed program's sample programs.

Handling Calls

The primitives are used to generate outgoing calls and accept incoming calls. If incoming calls are expected, the application must specify their characteristics to identify them. The X.25 call user data field is used to identify incoming calls to NPI, and how the listen is specified is described under the primitive. The primitives are used to terminate the calls.

N_BIND_REQ Primitive

Purpose

Requests that NPI binds a user stream to the X.25 protocol layers for the calling application. For X.25 SVCs, this gives the details of what incoming calls should be routed to the application. For X.25 PVCs, it gives details of what logical channel number to use.

Structure

This primitive consists of one message block with the following structure:

Description

The primitive requests that a network address be associated with a stream. It gives the maximum number of connect indications that can be outstanding for the particular application. It also indicates if the stream is a listening stream or a non-listening stream. A listening stream only receives connect indications (), and a non-listening stream either sends connect responses () or connect requests (). Bind requests for listening streams should use the field to specify the details of incoming calls that should be listened for.

If it is desired that a stream bound as a non-listening stream issue both and primitives, it is necessary to do two binds. One bind allows primitives to be sent; then an primitive followed by an primitive that binds the stream for sending the primitive is issued.

A sample of NPI code is included with the X.25 product.

Parameters

The following table defines specific address formats to be used used at bind time. Note that this primitive is also used for attaching PVCs.

The address must be a null-terminated string, and the null character is not counted as part of the length field of the message.

At a given time, not all 4096 LCNs are available. The range must be that which is configured for this X.25 port.

The line number can be obtained several ways. The command lists the logical port number for each port, which is the line number. Another way is to use the command as follows:

lsattr -E -l portname -a port_num

The value to use for the line number is the field. A third option is to use the subroutine. An example of this code can be found in the sample code directory for NPI.

In cases where the flag is used, the following rules apply:

The field gives a pattern to match to the call user data (CUD) of incoming X.25 packets. It must be a null-terminated ASCII string where only digits (0-9), hex digits (A-F), "?" and "*" are allowed. Note that the length of this string, including the null character, cannot exceed 34 bytes. Following are some examples of how the matching for the works.

Acknowledgments

The NS provider generates one of the following acknowledgments upon receipt of the primitive:

Error Codes

The applicable non-fatal errors are as follows:

Implementation Specifics

The primitive is part of X.25 licensed program.

N_BIND_ACK Primitive

Purpose

Acknowledges that the NPI application has been bound to a network address.

Structure

This primitive consists of one message block with the following structure:

Description

The primitive indicates to the application that the specified network user entity has been bound to the requested network address. The primitive also indicates the number of outstanding connect indications that can be queued.

Parameters

Implementation Specifics

The primitive is part of X.25 Licensed Program.

N_UNBIND_REQ Primitive

Purpose

Requests that the NPI application be unbound from the network address.

Syntax

This primitive consists of one message block with the following structure:

Description

The primitive requests that the NPI unbinds the application that was previously bound to the network address.

Parameters

Acknowledgments

NPI can generate the following acknowledgments upon receipt of the primitive:

Error Codes

The applicable non-fatal errors are as follows:

Implementation Specifics

This primitive is part of X.25 Licensed Program.

N_OK_ACK Primitive

Purpose

Indicates the network provider received the previous user-originated primitive.

Syntax

This primitive consists of one message block with the following structure:

Description

The primitive indicates to the application that the network provider received the previously submitted primitive. The does not indicate any network protocol action taken due to the issuance of the last primitive. The primitive can only be initiated as an acknowledgment for user-originated primitives that have no other means of confirmation. These primitives include the , , , and primitives.

Parameters

Implementation Specifics

The primitive is part of X.25 Licensed Program.

N_ERROR_ACK Primitive

Purpose

Provides notification of an error.

Structure

This primitive consists of one message block with the following structure:

Description

The primitive informs the application that a non-fatal error occurred in the previously issued primitive. This primitive can only be initiated as an acknowledgment for those primitives that require one. The primitive does not perform any action on the primitive that caused the error.

Parameters

Error Codes

The following error codes can be returned:

Implementation Specifics

The primitive is part of X.25 Licensed Program.

N_INFO_REQ Primitive

Purpose

Requests network information from the network service (NS) provider.

Structure

This primitive consists of one message block with the following structure:

Description

The primitive requests the NS provider to return the values of all supported protocol parameters and the current state of the NS provider. The primitive does not affect the state of the network. The information returned is detailed under the primitive.

Parameters

Acknowledgments

The NS provider generates one of the following acknowledgments upon receipt of the primitive:

Implementation Specifics

The primitive is part of X.25 Licensed Program.

N_INFO_ACK Primitive

Purpose

Acknowledges a request for network information.

Structure

This primitive consists of one message block with the following structure and values. Where a value is not supported, is returned:

{
   N_INFO_ACK;
   default_transmit_size;
   interrupt_packet_size;
   call_data_size;
   call_data_size;
   40 (X.25 extended address size);
   QOS_UNKNOWN;
   QOS_UNKNOWN;
   QOS_UNKNOWN;
   QOS_UNKNOWN;
   QOS_UNKNOWN;
   QOS_UNKNOWN;
   QOS_UNKNOWN;
   nidu size;
   N_CONS;
   QOS_UNKNOWN;
   QOS_UNKNOWN;
   QOS_UNKNOWN;
   QOS_UNKNOWN;
   QOS_UNKNOWN;
   QOS_UNKNOWN;
} N_info_ack_t;

Description

The primitive acknowledges a request for network information. The primitive indicates to the network services (NS) user any relevant protocol-dependent parameters. The primitive serves as a response to the primitive. The data transmission sizes are based on those of the underlying X.25 network.

Parameters

Implementation Specifics

This primitive is part of X.25 Licensed Program.

N_CONN_REQ Primitive

Purpose

Requests a network connection.

Structure

This primitive consists of one message block with the following structure:

and are not supported and should be set to 0 (zero).

Description

The primitive requests that the network service (NS) provider make a network connection to a specified destination. This will generate an X.25 call request to the remote X.25 host.

The format of the message is one message block followed by one or more blocks for the NS user data transfer. Specifying user data is optional. The NS user can send any integral number of octets of data within the range supported by the NS provider. (For more information, see the primitive.)

The following table defines the specific address format to be used for SVCs. The address must be a null-terminated string, and the null character is not counted as part of the length field of message.

User data is expected to be an even-length, null-terminated ASCII string. Facilities should be included in the M_DATA, and are expected to be coded as they would appear in a call packet. The sample code gives an example of facilities and CUD.  

For PVCs, the N_CONN primitives are not used. The connection is established through the N_BIND_REQ.

The line number can be obtained several ways. The command lists the logical port number for each port, which is the line number. Another way is to use the command as follows:

lsattr -E -l portname -a port_num

The value to use for the line number is the port_num field. A third option is to use the subroutine. An example of this code can be found in the sample code directory for NPI.

Parameters

Acknowledgments

The following acknowledgments are valid for the primitive:

The primitive indicates non-fatal errors.

Error Codes

The applicable non-fatal errors are defined as follows:

Implementation Specifics

The primitive is part of X.25 Licensed Program.

N_CONN_IND Primitive

Purpose

Indicates a network request connection has been made.

Structure

This primitive consists of one message block with the following structure:

and are 0 (zero) since they are not supported.

Description

The primitive indicates to an application that it has received an incoming call or connection.

The format of this message is one message block normally followed by one or more blocks for NS user data. The calling application could have sent any integral number of octets of data within the range supported by the NS provider. The NS user data exists only if the corresponding primitive specified user data. The data in the and primitives is identical.

Parameters

Implementation Specifics

The primitive is part of X.25 Licensed Program.

N_CONN_RES Primitive

Purpose

Allows the destination NPI application to accept an incoming connection request.

Structure

This primitive consists of one message block with the following structure:

should be 0 (zero) since QOS parameters are not supported.

Description

The format of this message is one message block followed by one or more blocks. The blocks contain user data which is optional. Any integral number of octets, up to the limit imposed by the underlying network, can be passed. Note that an odd-length CUD string is not allowed.

Parameters

The NS user determines the stream's value by issuing an primitive with the flag set. The primitive returns the token value.

Acknowledgments

The NS provider generates one of the following acknowledgments upon receipt of the primitive:

Error Codes

The applicable non-fatal errors are defined as follows:

Implementation Specifics

The primitive is part of X.25 Licensed Program.

N_CONN_CON Primitive

Purpose

Confirms a network connection.

Structure

This primitive consists of one message block with the following structure:

and are 0 (zero) since they are not supported.

Description

The primitive informs an NPI application that issued a that the remote application accepted the connection.

The format of this primitive is one message block followed by one or more blocks that contain NS user data. In the remote application's response it can send an integral number of octets of user data - within the range supported by the network. User data will be a part of the confirmation only if used in the remote's primitive. The data in the and primitives are always identical.

Parameters

Implementation Specifics

The primitive is part of X.25 Licensed Program.

N_DATA_REQ Primitive

Purpose

Sends data to the remote application

Structure

The structure of the message block, if present, is as follows:

Description

The primitive indicates that the message contains data. This primitive is user-originated and allows transfers of data between applications.

The NS user must send any integral number of octets of data greater than 0. If the size of the NSDU exceeds the network interface data unit (NIDU), the NSDU may be broken up into multiple NIDUs. When an NSDU is segmented into multiple NIDUs, the primitive sets the flag on each NIDU except the last one. The flag can only be set on the last NIDU. This is the standard method of working for the X.25 network.

The format of the message is one or more blocks. Using a message block is optional but is used for for two reasons:

Parameters

Acknowledgments

This primitive does not require any acknowledgments. However, the primitive may generate a fatal error. The STREAMS message type notifies the application of an error. As a result of the error, all system calls on that stream will fail.

Error Codes

Implementation Specifics

The primitive is part of X.25 Licensed Program.

N_DATA_IND Primitive

Purpose

Indicates that the current message contains application data.

Structure

The structure of the message block, if present, is as follows:

Otherwise, the message consists of one or more message blocks.

Description

The primitive indicates to the NS user that this message contains NS user data. This primitive originates from the network provider and is a response to the primitive. The network service data unit (NSDU) can be segmented into more than one network interface data units (NIDUs). The associates NIDUs with the NSDU. The flag can be set only on the last NIDU.

The format of the message is one or more message blocks. The value of the NS user data field is always the same as that supplied in the corresponding primitive at the peer service access point. message blocks are optional.

Parameters

Implementation Specifics

The primitive is part of X.25 Licensed Program.

N_DATACK_REQ Primitive

Purpose

Acknowledges the receipt of data which had the flag set.

Structure

This primitive consists of one message block with the following structure:

Description

The primitive acknowledges receipt of an primitive which had the receipt confirmation parameter set. The NPI application should send a on receipt of such data.

Parameters

Acknowledgments

This primitive does not require any acknowledgments. However, the primitive may generate a fatal error. The STREAMS message type notifies the NS user of an error. As a result of the error, all system calls on that stream will fail.

Error Codes

Implementation Specifics

The primitive is part of X.25 Licensed Program.

N_DATACK_IND Primitive

Purpose

Indicates the remote NPI application has acknowledged data sent to it with the receipt acknowledge flag set.

Structure

This primitive consists of one message block with the following structure:

Description

The primitive indicates to the local NPI application that the remote has acknowledged the data that had previously been sent with the receipt confirmation set. The primitive is a received based on the remote application submitting a primitive.

Parameters

Implementation Specifics

The primitive is part of X.25 Licensed Program.

N_RESET_REQ Primitive

Purpose

Requests that the network connection be reset.

Syntax

This primitive consists of one message block with the following structure:

Description

The primitive requests that the network service (NS) provider reset the network connection. The NS user initiates this primitive.

Parameters

Acknowledgments

Error Codes

The following non-fatal error codes are valid:

Implementation Specifics

The primitive is part of X.25 Licensed Program.

N_RESET_IND Primitive

Purpose

Indicates the connection has been reset.

Syntax

This primitive consists of one message block with the following structure:

Description

The primitive indicates to the network service user that the network connection has been reset. The network provider originates this primitive.

Parameters

Once a reset indication is received, a should be sent in response. After the , no other primitives should be sent until a subsequent reset indication is received. Other primitives issued will receive a reset in response.

Implementation Specifics

The primitive is part of X.25 Licensed Program.

N_RESET_RES Primitive

Purpose

Acknowledges receipt of a reset indication.

Syntax

This primitive consists of one message block with the following structure:

Description

The primitive indicates that the NPI application has accepted a reset request. This primitive must be issued before use of the connection can be restored after a reset has been indicated.

Parameters

Acknowledgments

Error Codes

The following non-fatal error codes are valid:

Implementation Specifics

The primitive is part of X.25 Licensed Program.

N_RESET_CON Primitive

Purpose

Provides confirmation from the network that it received the primitive.

Syntax

This primitive consists of one message block with the following structure:

Description

The primitive informs the NPI application that the reset previously issued with the primitive has completed. The NS provider can issue the primitive to the application before receiving an primitive from the remote.

Parameters

Implementation Specifics

The primitive is part of X.25 Licensed Program.

N_DISCON_REQ Primitive

Purpose

Requests that an existing connection be disconnected.

Structure

This primitive consists of one message block with the following structure:

(Optionally followed by clear user data.)

Description

The primitive requests that the network service (NS) provider either disconnect an existing connection or deny a request for a network connection. This primitive is user-originated.

The format of the message is one message block, followed by one or more message blocks that indicate user data. Any integral number of octets of data, up to the network's clear user data limit, can be sent provided the length is even.

Parameters

Acknowledgments

The NS provider should generate one of the following acknowledgments upon receipt of this primitive:

Error Codes

The applicable non-fatal errors are as follows:

Implementation Specifics

The primitive is part of X.25 Licensed Program.

N_DISCON_IND Primitive

Purpose

Indicates a disconnected or denied connection.

Structure

This primitive consists of one message block with the following structure:

Description

The primitive indicates to the NPI application that either an existing connection has been disconnected or a request for connection has been denied. The network provider generates this primitive.

The format of the message is one message block, followed by one or more blocks. The value of the user data parameter is identical that sent in the corresponding primitive if one was used. There would be no user data if the disconnection was not initiated by the remote application.

Parameters

When the value of this parameter is nonzero and matches the sequence number assigned to an unacknowledged primitive, the value of the parameter indicates that the NS provider is canceling the unacknowledged primitive.

Implementation Specifics

The primitive is part of X.25 Licensed Program.

Chapter 6. Data Link Provider Interface Programming Reference

This chapter discusses the Data Link Provider Interface (DLPI) which provides access to the LAP-B frame layer, including the primitives necessary to run DLPI.

The Data Link Provider Interface (DLPI) enables a data link service user to access and use the frame or LAP-B layer of the protocol stack. To access the frame layer directly on a port, the port's configuration must be set to allow it. With the frame layer access active, regular X.25 applications cannot use the port.

The interface provides point-to-point data communications and is designed for two systems connected back to back over a communications link. This is provided through a connection-oriented subset of the full DLPI specification. Other implementations of DLPI exist, and shipped with the operating system's portable STREAMS environment is a connectionless-oriented subset. The X.25 Licensed Program only supports the connection-oriented subset of the specification that is shipped with the product.

For X.25 ports that use the device driver, the frame layer resides in the AIX kernel. In this case it is not necessary (or appropriate) to encode the DLPI primitives. They are issued directly to the frame layer.

Thus, a different device driver open is required, depending on the location of the frame layer. Once the open is done, DLPI interactions are identical, regardless of frame location. See the sample programs (referenced below) for the subroutine called . This subroutine provides a single open interface that isolates these base device driver differences form DLPI applications.

For additional information on the device driver, see .

The Data Link Layer

The data link layer (layer 2 in the OSI Reference Model ) is responsible for the transmission and error-free delivery of information over a physical communications medium. This layer is also referred to as the frame or LAP-B layers .

The model of the data link layer is presented here to describe concepts that are used throughout the specification of DLPI. It is described in terms of an interface architecture, as well as addressing concepts needed to identify different components of that architecture.

Model of the Service Interface

Each layer of the OSI Reference Model has two standards:

DLPI is an implementation of the first type of standard. It specifies an interface to the services of the data link layer. The following depicts an overview of DLPI.

The data link interface is the boundary between the network and data link layers of the OSI Reference Model. The network layer entity, which is usually the X.25 layer , is the user of the services of the data link interface. This user is DLPI's user application and is sometimes referred to as the Data Link Service (DLS) user . The DLPI layer which provides the programming interface is referred to as the DLS provider. This interface consists of a set of primitives that provide access to the data link layer services.

The service primitives that make up kernel-level interfaces are defined as STREAMS messages that are transferred between the user and provider of the service. DLPI is targeted for STREAMS protocol modules that either use or provide data link services. In addition, user programs that wish to access a STREAMS-based data link provider directly may do so using the and subroutines.

The use of DLPI is demonstrated in a set of sample programs located in the directory for AIX version 3; and for AIX version 4 users.

DLPI Primitives

Before DLPI primitives can be used by the application, the user must establish a stream to DLPI. It does this by binding to the frame layer that has been made available in the streams environment though the X.25 Licensed Program's installation. Once bound to a stream, the application can send primitives to DLPI and connect and transfer data. When an application wishes to terminate it disconnects the link and unbinds from its stream. The primitives are split into two groups :

Local Management Service Primitives

The following primitives support the information reporting, attach, and bind services of DLPI. Once a stream has been opened by a DLS user, these primitives initialize the stream and prepare it for use.

Connection-Mode Service Primitives

This section describes the service primitives that support the connection-mode service of the data link layer. These primitives support:

Connection Establishment Primitives

The following DLPI primitives establish data link connections:

The calling application initiates the connection by issuing a primitive. The primitive informs the calling application that the connection has been established.

Once the connection is established, data is exchanged using the STREAMS and subroutines.

The data transfer service provides for the exchange of user data in either direction or in both directions simultaneously between the applications. Data is transmitted in local groups called DLSDUs. The DLS provider preserves both the sequence and boundaries of DLSDUs as they are transmitted.

Normal data transfer is neither acknowledged nor confirmed. It is up to the DLS users, if they so choose, to implement a confirmation protocol. Refer to the DLPI sample programs for an example of coding data frames.

Connection Release Primitives

The following DLPI primitives provide data link connection release service:

The connection release service allows DLS users or the DLS provider to initiate the connection release. Any data in that has not been delivered to the DLS user when the connection release is requested can be discarded. Normally, one DLS user requests disconnection and the DLS provider issues an indication of the ensuing release to the other DLS user.

Reset Primitives

The following DLPI primitives provide reset service:

The reset service may be used by the DLS user to resynchronize the use of a data link connection, or by the DLS provider to report detected loss of data unrecoverable within the data link service.

If the data link connection is congested, running the reset service unblocks the flow of DLSDUs. DLSDUs may be discarded by the DLS provider. The DLS user or users that did not invoke the reset are notified that a reset has occurred. A reset may require a recovery procedure to be performed by the DLS users.

DL_BIND_ACK Primitive for X.25

Purpose

Reports the successful bind of a data link service access point (DLSAP) to a stream.

Structure

This primitive consists a message block with the following structure:

Description

The primitive reports the successful bind of an application to a stream and returns the bound DLSAP address to the DLS user. This primitive is generated in response to a primitive.

Parameters

Implementation Specifics

The primitive is part of X.25 Licensed Program.

DL_BIND_REQ Primitive for X.25

Purpose

The application requests a stream to be bound for the application to the frame layer, thus producing a data link service access point (DLSAP) to the stream.

Structure

This primitive consists of a message block with the following structure:

Description

The primitive requests the DLS provider to bind a DLSAP to a stream. The DLS user must identify the address of the DLSAP to be bound as well as indicate whether it will accept incoming connect requests on the stream. The request directs the DLS provider to activate the stream associated with the DLSAP.

A stream is active when the DLS provider can transmit and receive protocol data units destined to or originating from the stream. The physical point of attachment (PPA) associated with each stream must be initialized when the primitive has been processed. The PPA is initialized when the primitive is received. If the PPA cannot be initialized, the primitive fails.

A stream can be bound as a connection management stream, which receives all connect requests that arrive through a given PPA. In this case, the parameter is ignored.

Parameters

where byte 1 is the most significant byte of the ulong, and byte 4 is the least significant.

States

Acknowledgments

Error Codes

Implementation Specifics

The primitive is part of X.25 Licensed Program.

DL_CONNECT_CON Primitive for X.25

Purpose

Informs the local data link service (DLS) user that the requested data link connection has been established.

Structure

This primitive consists of one message block with the following structure:

Description

The primitive informs the local DLS user that the requested data link connection has been established. The primitive contains the data link service access point (DLSAP) address of the responding DLS user as well as the quality of service (QOS) parameters selected by the responding DLS user.

Parameters

Addressing and quality of service parameters are not supported; therefore, each of the following parameters will be set to 0.

States

Implementation Specifics

The primitive is part of X.25 Licensed Program.

DL_CONNECT_REQ Primitive for X.25

Purpose

Requests data link connection between the data link service (DLS) provider and a remote DLS user.

Structure

This primitive consists of a message block with the following structure:

Description

The primitive requests that a DLS provider establish a data link connection with a remote DLS user.

Parameters

Addressing and quality of service parameters are not supported; therefore, each of the following parameters will be set to 0.

States

Acknowledgments

The primitive has no immediate response. However, if the connect request is accepted by the called DLS user, the primitive is sent to the calling DLS user, resulting in the state.

If the connect request is rejected by the called DLS user, the called DLS user cannot be reached, or the DLS provider or called DLS user do not agree on the specified quality of service, a is sent to the calling DLS user, resulting in the state.

If the request is erroneous, the primitive is returned and the resulting state is unchanged.

DL_DISCONNECT_IND Primitive for X.25

Purpose

Informs the data link service (DLS) user that the data link connection on the current stream has been disconnected.

Structure

This primitive consists of one message block with the following structure:

Description

The primitive informs the DLS user of one of the following conditions:

The primitive indicates the origin and the cause of the disconnect.

Parameters

States

Implementation Specifics

This primitive is part of X.25 Licensed Program.

DL_DISCONNECT_REQ Primitive for X.25

Purpose

Requests that an active data link be disconnected.

Structure

This primitive consists of one message block with the following structure:

Description

The primitive requests the data link service (DLS) provider to disconnect an active data link connection or one that was in the process of activation. The primitive can be sent in response to a previously issued or primitive. If an incoming primitive is being refused, the correlation number associated with that connect indication must be supplied. The message indicates the reason for the disconnect.

Parameters

States

Acknowledgments

Error Codes

Implementation Specifics

This primitive is part of X.25 Licensed Program.

DL_ERROR_ACK Primitive for X.25

Purpose

Informs the data link service (DLS) user that a request or response was invalid.

Structure

This primitive consists of one message block with the following structure:

Description

The primitive informs the DLS user that the previously issued request or response was invalid. The primitive identifies the primitive in error, specifies a data link provider interface (DLPI) error code, and if appropriate, indicates an operating system error code.

Parameters

States

Implementation Specifics

This primitive is part of X.25 Licensed Program.

DL_INFO_ACK Primitive for X.25

Purpose

Returns information about the Data Link Provider Interface (DLPI) stream in response to the primitive.

Structure

This primitive consists of one message block with the following structure:

Description

The primitive returns information about the DLPI stream to the data link service (DLS). The primitive is a response to the primitive.

Parameters

Once this service mode has been bound to the stream, this parameter returns that specific service mode.

If QOS has not yet been negotiated, default values are returned. These values correspond to those that are applied by the DLS provider on a connect request. For any parameter the DLS provider does not support or cannot determine, the corresponding entry will be set to . If the DLS provider does not support any QOS parameters, this length field is set to 0.

For any parameter the DLS provider does not support or cannot determine, the corresponding entry is set to . If the DLS provider does not support any QOS parameters, this length field is set to 0.

States

Implementation Specifics

This primitive is part of X.25 Licensed Program.

DL_OK_ACK Primitive for X.25

Purpose

Acknowledges that a previously issued primitive was received.

Structure

This primitive consists of one message block with the following structure:

Description

The primitive acknowledges to the DLS user that a previously issued primitive was received. It is only initiated for the primitives listed in the "States" section.

Parameters

States

For more information, see Appendix B.

Implementation Specifics

This primitive is part of X.25 Licensed Program.

DL_RESET_CON Primitive for X.25

Purpose

Informs the reset-initiating data link service (DLS) user that the reset has completed.

Structure

This primitive consists of one message block with the following structure:

Description

The primitive informs the DLS user initiating the reset that the reset has completed.

Parameters

States

Implementation Specifics

This primitive is part of X.25 Licensed Program.

DL_RESET_IND Primitive for X.25

Purpose

Indicates a data link service (DLS) connection has been reset.

Structure

This primitive consists of one message block with the following structure:

Description

The primitive informs the DLS user that either the remote DLS user is resynchronizing the data link connection, or the DLS provider is reporting loss of data from which it cannot recover. The primitive indicates the reason for the reset.

Parameters

States

Acknowledgments

The DLS user should issue a primitive to continue the resynchronization procedure.

Implementation Specifics

This primitive is part of X.25 Licensed Program.

DL_RESET_REQ Primitive for X.25

Purpose

Requests that the data link service (DLS) provider begin resynchronizing a data link connection.

Structure

This primitive consists of one message block with the following structure:

Description

The primitive requests that the DLS provider begin resynchronizing a data link connection.

Data in transit when the primitive is initiated may not be delivered.

Parameters

States

Acknowledgments

Error Codes

Implementation Specifics

This primitive is part of X.25 Licensed Program.

DL_RESET_RES Primitive for X.25

Purpose

Directs the data link service (DLS) provider to complete resynchronizing of the data link connection.

Structure

This primitive consists of one message block with the following structure:

Description

The primitive directs the DLS provider to complete resynchronizing of the data link connection.

Parameters

States

Acknowledgments

Error Codes

Implementation Specifics

This primitive is part of X.25 Licensed Program.

DL_UNBIND_REQ Primitive for X.25

Purpose

Requests the data link service (DLS) provider to unbind a data link service access point (DLSAP).

Structure

This primitive consists of one message block with the following structure:

Description

The primitive requests that the DLS provider unbind the DLSAP that had been bound by a previous primitive. If one or more DLSAPs were bound to the stream with a primitive and have not been unbound with a primitive, the primitive unbinds all the subsequent DLSAPs for that stream along with the DLSAP bound with the previous primitive.

At the successful completion of the request, the DLS user can issue a new primitive for a potentially new DLSAP.

Parameters

States

Acknowledgments

Error Codes

Implementation Specifics

The primitive is part of X.25 Licensed Program.

Chapter 7. X.25 and SNA Networks

You can use an X.25 connection to connect a host machine to a (SNA) network and access a System/370 host.

This information is intended for system administrators responsible for:

SNA administrators should be familiar with an AIX node and operating procedures for the AIX operating system. Also, they should know the network to which the system is being connected and the general concepts of SNA. In addition, individuals assuming administrative responsibilities should know how to use the System Management Interface Tool (SMIT) . Some of the tasks related to system administration are:

The SNA Server/6000 product provides menu dialogs, commands, and procedures for system administration purposes.

The following sections contain detailed information about using an X.25 connection to connect a host machine to a System Network Architecture (SNA) network and access an S/390 host.

Accessing an SNA Network with X.25

The X.25 protocol allows you to access a (SNA) network. You can make the connection by using the SNA Server/6000 licensed program product. The connection illustrated in the Scenario for an SNA Connection Using X.25 also uses the 3270 Host Connection Program 2.1 and 1.3.3 for AIX (HCON) Version 1.3 terminal emulation program .

QLLC with Reference to X.25 Support

Qualified Logical Link Control (QLLC) is only for SNA support. It permits the use of additional link control information that SNA needs, but which X.25 does not. QLLC architecture specifies the mapping between Synchronous Data Link Control (SDLC) frames and X.25 packets.

When SNA is used over X.25, it uses the qualifier-bit (Q-bit) in the X.25 packet header to indicate special link control information. This information is relevant for SNA control between the two systems communicating with each other, but it is of no concern to X.25 link control. These qualified packets help SNA to determine who is calling whom between the two communicating systems and indicate such items as maximum message size.

QLLC must be used in the following situations:

Some systems can control the segmenting and unsegmenting of messages themselves, rather than leaving it to the X.25 protocol . These systems use additional control on top of X.25 to perform this. The in/6000; does not support this additional control of Logical Link Control (LLC) headers, embedded in X.25 packets, to segment messages. The system leaves it to the X.25 protocol to handle segmenting.

The X.25 ports that are to be used for SNA must have COMIO emulation configured on them. This produces ports such as which are used by QLLC. For example, the X.25 port, cannot be used directly by SNA or QLLC.

Introduction to SNA Server/6000

SNA Server/6000 implements two SNA components that control the operation of the local node in the network. These components are as follows:

SNA Configuration Profiles

SNA Server/6000 keeps all network information in structured files called profiles. It stores the profiles as database files that are controlled by system data management routines.

The profiles needed to use the 3270 host connection program with X.25 are:

Session profiles define and register LU addresses, primary and secondary LU0 logical units and corresponding link station profile names, system services control point (SSCP ID), network name and remote LU name for LU1, LU2, and LU3 profiles, and for LU6.2 profiles: local and partner LU profiles, side information profiles for CPIC applications, mode profiles, transaction program name profiles, session and conversation security profiles, session time-out profiles, class of service profiles, and partner LU 6.2 location profiles.

For additional information on SNA configuration and profiles, see , Order Number SC31-7002, and , Order Number SC31-7014.

SNA Configuration Commands

A set of configuration commands is provided with SNA Server/6000 to assist with and accomplish network configuration and setup. An extensive list of these commands can be found in , Order Number SC31-7100, and , Order Number SC31-7014. A few of the more commonly used commands are:

mksnaobj -t ProfileType [-w link_type|-u lu_type] \
 
[-T template_profname] [suboptions... ] ProfileName

chsnaobj -t ProfileType [-w link_type|-u lu_type] \
 
[suboptions... ] ProfileName

rmsnaobj -A | -t ProfileType [-w link_type|-u lu_type] \ 
 
ProfileName [ProfileName ...]

qrysnaobj [-C] [-S | -L] -t ProfileType [-w link_type| \
 
-u lu_type] ProfileName

sna {-start(-s) [sna | session(s) | link_station(1) | \ 
 
anynet] -stop | -display | -trace(-t) | -setlogs} \
 
[Options]
 
sna -start(-s) session(s) [ [Flag Value] ...]
 
sna -start(-s) session(s) [ [Flag Value] ...]
 
[-local_lu_name(-ln) Name | -local_lu_alias(-la) Alias]
 
{-partner_lu_name(-pn) Name | -partner_lu_alias(-pa) \ 
 
Alias} -mode(-m) Name [-session_type(-st) conwinner(cw) \ 
 
| conloser(cl)]
 
sna -start(-s) link_station(l) -profile(-p) Value

verifysna {[-R] | [-U] } [-B backup_ascii_file]
 
                         [-S backup_security_file]

SNA Server/6000 Profile Types and Profile Parameters

The following table lists some of the common profile types, their corresponding profile parameters, and a brief description.

SNA Server/6000 Components

SNA Server/6000 is comprised of:

The System Resource Controller, in turn, provides all services to transfer data over the network. To provide these services, the SRC requests information from the profile and data management components to define the characteristics of connections and link stations on the network. Refer to for more information on the SRC.

SNA Device Drivers

The following AIX device drivers are part of SNA Server/6000:

These device drivers must be present for SNA Server/6000 to function properly. They should appear in a listing of the directory as , , and , respectively.

3270 Host Connection Program 2.1 and 1.3.3 for AIX

The AIX 3270 Host Connection Program 2.1 and 1.3.3 for AIX (HCON) is a software package that allows communication with one or more IBM System/370 computer systems.

HCON Overview

To communicate with a System/370 host, HCON establishes a session with the host system. HCON can be used to establish multiple sessions with IBM System/370 computers. Each session emulates either a 3278/79 display or a 3286/87 printer. A session emulating a display is known as a , while a session emulating a printer is known as a . HCON provides file transfer capabilities within display sessions. It also includes an application programming interface (API), which can be used to write programs that communicate with a System/370 host.

At the beginning of a display session, the emulator acts as if you had just turned on the 3278/79 terminal. After you log in to the System/370 host, you can run commands and programs. You can also use the command to upload and download files to and from the host as well as change the format of the data in files as you transfer them. For example, you can translate the file from ASCII to EBCDIC or add or remove carriage-return characters.

During a printer session, you can print files from the host on a local printer as if it were attached directly to the host or save files in printable form to print or edit later.

A user with root authority must register you as an HCON user before you can use HCON commands. After you have been registered, you must create at least one session profile before you can run HCON.

The or the commands may be used to add a new HCON user.

Each user of HCON can have a maximum of 26 sessions, allowing one or more simultaneous invocations of HCON to communicate with one or more hosts using different session characteristics and communication protocols, but because of SNA constraints you are limited to one host per physical link station. The parameters defining the characteristics of each session are established by a .

Session profiles can be created with or commands.

The following list is a classification of HCON commands:

This command provides a menu that allows the creation of a binary color definition table, a binary keyboard definition table, explicit file transfer, logon/logoff facilities and access to the command used to create or modify automatic logon profiles.

See for more information about HCON commands.

Setup and Use of 3270 Host Connection Program 2.1 and 1.3.3 for AIX

Once you have set up all the related profiles, use the following procedure to start the connection:

Defining HCON Users

Use the following procedure to add an HCON user.

smit mkhconu

Defining HCON SNA Sessions

Use the following procedure to define an HCON SNA session.

smit mkhcons_st

  HCON user name                               edgar
  SESSION name                                 a
  Session USE                                 [X.25 CONNECTION]
* SNA Profile                                 [XPROF02]
  COUNTRY                                      United States
* KEYBOARD table                              [/usr/lib/hcon/e78>
* COLOR table                                 [/usr/lib/hcon/e78>
* File used by SAVES key                      [/u/edgar/e789_sav>
* File used by REPLS key                      [/u/edgar/e789_rep>
  Host TYPE                                    CMS
  Host LOGIN ID                               [ ]
  Autolog NODE ID                             [ ]
  Autolog TRACE                                no
  Autolog TIMEOUT (seconds)                   [ ]

Starting a HCON Session

To start a session, enter the following command:

e789 SessionName

SNA Problems

See for information on problem determination procedures.

HCON Problems

The file transfer times out on a System/370 host with the emulator screen displaying message 0789-114.

One of the reasons this can occur is that the value of the field of the macro has not been set correctly for HCON. If it has been set correctly, check that the logmode table has been refreshed since changing the value of the field.

Chapter 8. Packet Assembler/Disassembler (PAD)

X.25 defines the relationship between a Date Terminal Equipment (DTE) node and a network's DCE . The CCITT also defines the attachment of asynchronous start-stop devices to the PSDN in recommendations X.3, X.28 and X.29. The asynchronous device is typically a low-cost terminal such as an IBM 3151 or 3152. These terminals lack the intelligence of a full-function node on the network and rely on a device called a packet assembler/disassembler (PAD). A PAD is a protocol converter interfacing asynchronous terminals with an X.25 network or an X.25 network with applications written for asynchronous terminals .

Low-cost asynchronous terminals are connected by the public-switched telephone network to a local public outgoing PAD, often simply referred to as a PAD. The PAD takes the ASCII data stream coming from the terminal, buffers it, converts it into a properly formatted X.25 packet, then sends it over the X.25 PSDN addressed to the desired DTE. Data from the terminal that has been divided into packets and shipped by a PAD to the DTE node must be received by some incoming PAD software (also referred to as an X.29 interface). This incoming PAD unpacks the data and passes it to the application (typically, the TTY driver) for processing as if it were coming from directly attached asynchronous terminals. The other way, data coming from the application is first put into packets by the X.29 PAD then transferred over the network. When the PAD receives a packet addressed to the terminal, it reverses the process. This presents the data in a form that the terminal can accept.

The computer industry has expanded the definition of a packet assembler/disassembler (PAD) to include protocol conversion between X.25 and various teleprocessing protocols, for example, SDLC PADs, BSC-3270 PADs, and so on.

Basic PAD functions include:

Optional functions include:

X.3, X.28 and X.29 Standards

PAD Setup

To use the PAD software on the system, configure it through SMIT. See for more details. Once the PAD software is enabled on the system, it can be used as a terminal PAD for supporting local terminal users, or as a host PAD to work with remote terminal PADs. Both modes of operation can be run at the same time.

For use as a terminal PAD, each terminal or terminal emulator that requires a PAD session executes the command. The command connects the terminal to an application that provides the standard X.28 interface. See for more details on the use of terminal PAD sessions.

When the system is to be used as a host PAD, no user interaction takes place on the system itself. Once the system is configured to enable the PAD, users can connect from terminals connected to remote terminal PADs. The system running the host PAD allows login and application execution similar to any other type of remote ASCII terminal.

PADs support ASCII terminals using 7-bit character set defined in International Alphabet 5 (IA5). PAD supports 8-bit data. The characteristics of the terminal must agree with its configuration data on the system unit it is attached to if using on an ASCII terminal. This is also true for any attached TTY.

PAD for AIXLink/X.25 1.1.2 Running on AIX Version 4

There are three basic PAD features that are controlled by four new PAD configuration files located in the directory:

The daemon must be running for these features to work. You can start the daemon with flags for use with these features.

The four PAD configuration files are:

Automatic Login

The automatic login feature is implemented by defining the attribute in the file with a value of an existing user name. When a call is received from a matching address, the call is automatically logged in as that user, instead of being presented with the normal system authentication method. For example:

31*:
   login_user = user1

automatically logs in any calls from an address beginning with as .

Automatic TTY and PAD Parameter Selection

The and files are used to define sets of parameters by name. These are then pointed to by the and attributes, respectively, in the and/or files. This allows the selection of any combination of host TTY and remote PAD parameters based on calling address, login user, or both. For example, if the following stanza exists in the file:

tty1:
   echo  = off
   vmin  = 1
   vtime = 1

and the following stanza exists in the file:

user1:
   in_tty = tty1

any call that logs in as has its TTY parameters set according to the values defined in the stanza in the file.

Since the and attributes can appear in either the or files, it is necessary to decide which should take priority if both are defined. By default, the attribute has priority. For example, if both the matching address and user entries define or , the value is taken from the file. However, this default prioritization can be changed by explicitly setting the priority of the attribute as follows:

attribute = value;priority

where is a decimal number, with lower numbers being more favored and being the most favored priority. For example, assume the file has the following stanza:

user1:
   in_tty = tty1

and the file has the following stanza:

addr1:
   in_tty = tty2

If a call is received from and logs in as , the TTY would be set according to the definition in the file. If, however, the address stanza looks like:

addr1:
   in_tty = tty2;0

all calls received from get the settings, regardless of which user they log in as.

Restriction of Outgoing Calls

The and attributes can be defined in the file to control which addresses specific users can place PAD calls to. The attribute values can consist of patterns so that a complex set of addresses can be specified. In order for a call to succeed, the called address must match the attribute for the calling user, and it must not match the attribute.

For example, if the following stanza exists in the user file:

user1:
   out_allow = 31*
   out_deny  = 31[3-5]*

is allowed to call any address starting with , except for those starting with , , or .

The file is shipped with the default stanza having the attribute set to   (the asterisk character), which permits all users without explicit entries in the file to place calls to any address.

Configuration File Format (AIXLink/X.25 Version 1 and later)

Each PAD configuration file contains a set of stanzas of the following form:

key1:
   attribute1 = value1
   attribute2 = value2
   attribute3 = value3
   ...
key2:
   ...

Each new key begins after a blank line. The field and some attribute values may contain pattern-matching characters that are defined as follows:

The following is an example of attribute values:

12*   Matches any value beginning with "12".

12?   Matches any value beginning with "12" followed by any
   single character. 

[1-3]*   Matches any value beginning with "1", "2", or "3".

12*|23*   Matches any value beginning with either "12" or "23".

The configuration file is searched sequentially, and the first key value that matches the search key is used. To avoid redundant attribute definitions, it is possible to use the special attribute to specify another stanza that supplies attribute values not explicitly defined in the matching stanza. If the attribute definition is still not found after searching any specified stanzas, the stanza with the special key is checked. For example:

default:
   attribute1 = value1
   attribute2 = value2
   attribute3 = value3
key1:
   attribute1 = value1
key2:
   default    = key1
   attribute2 = value2
key3:
   default    = key2
   attribute3 = value3

In this case, the value for 's comes from , since it is not defined in 's stanza; and is 's default stanza. Since an arbitrary number of default links can be followed, 's value also comes from , as the default links are followed from to and to . Finally, the value for 's comes from the default stanza, since neither nor 's default stanza, , defines a value for it.

Call packets can be received without a calling address specified. In these cases, the NULL key value can be used in the file to match a nonexistent calling address.

x29d Usage Changes

The default x29d mode can run as an outgoing PAD call validation daemon and an X.29 listener daemon (a single process with dual functionality).

If started using the flag, the x29d runs as an outgoing PAD call. If started in the default mode using no flags, x29d runs as an incoming X.29 call server daemon.

You can start x29d as follows:

x29d [-a] [-p user] | [-n]

Chapter 9. X.25 Simple Network Management Protocol

With the AIX Licensed Program, is support for a Simple Network Management Protocol (SNMP) proxy agent . This support allows statistical data related to the X.25 interfaces to be gathered and transferred to an SNMP agent for analysis. The items of data gathered form a subset of the Management Information Base for X.25 specified in RFCs 1381 and 1382 . RFC 1381 covers the frame layer and 1382 the packet layer.

For more details on the individual MIB objects, refer to the appropriate RFCs.

Data collection from X.25 for SNMP is enabled and disabled by the config methods:

Installation Notes for SNMP Multiplexer X.25 Peer Daemon (x25smuxd)

It is assumed that the is running and all the necessary software needed to ensure that the is properly functioning is installed and working. The X.25 proxy agent and the MIB defs file resides in directory. Before invoking by the config methods at the port configuration time, use the following installation procedure:

-- object definitions compiled from RFC1381-MIB { iso 3 6 1 2 1 }

"x25smuxd"     1.3.6.1.2.1.10.16     "x25smuxd_password"

smux     1.3.6.1.2.1.10.16     x25smuxd_password     #x25smuxd

refresh -s snmpd

Frame Layer Objects

The following objects from RFC1381 are supported in read-only mode:

Packet Layer Objects

The following objects from RFC1382 are supported in read-only mode:

Chapter 10. Common Input/Output Emulation

Prior to AIX Version 4, there was base X.25 support that provided a number of programming interfaces, higher layer protocols and applications. This support was provided through devices such as . With the X.25 support provided by the separate Licensed Programs, this former interface is emulated through common input/output (COMIO) emulation. Each X.25 port that requires COMIO emulation should have it selected through SMIT configuration.

All the documentation in this chapter refers to use of the COMIO emulator, its programming interfaces or applications. Ensure that a suitable COMIO emulation port is available for use.

X.25 Application Programming Interface Overview

The X.25 application programming interface (API) can be used to write applications tailored to specific needs.

This overview provides the following information about programming X.25 communications:

X.25 Application Programming Interface (API)

X.25 communications can be used to provide a network service for higher-level protocols, such as SNA, or directly with commands or the API. The X.25 commands can be used as soon as you have set up X.25 communications. The application programming interface (API) can be used to write applications tailored to specific needs. The following sections discuss portions of the X.25 API:

Before you can use the COMIO emulation X.25 API, the X.25 Licensed Program must be installed and , and emulation ports added as required. You also need access to a C compiler.

The X.25 API includes a library of C subroutines that use the services of the X.25 adapter and adapter code. Application programs call these subroutines to access X.25 functions. The subroutines use a number of structures to pass information between the X.25 functions and the application programs. Further information can be found in:

The X.25 API provides the following types of identifiers for use in programs:

In addition to the subroutine library and the header files for the structures, there are example programs that demonstrate the use of the subroutines. Further information can be found in .

Background information for using the subroutines is included in .

Using the X.25 Structures and Flags

For many of the subroutines, parameters are placed in a structure, and the subroutine is passed a pointer to this structure. Definitions of these structures are supplied as a header file,. Include the following line in programs:

#include <x25sdefs.h>

in lists all the structures included in the file.

Each of the fields in a structure has an associated flag. This flag tells the API whether the associated field has been used. If the corresponding flag has not been set, the field is ignored by the API. To use the flag, which is a constant, it with the in the structure. This sets the appropriate bit in the field.

Before invoking a subroutine, the appropriate field must be set to 0 or to a particular flag constant. For example, to set the field to 0 before invoking the subroutine, use the following:

cb_call.flags = 0

To indicate that the field is being used, before invoking the subroutine, use the following:

cb_call.flags = X25FLG_LINK_NAME

Some flags, for instance, , do not correspond to structure elements.

/dev/x25sn Special File

The special file is provided through the COMIO emulation migration.

The emulator supports the special file as a character-multiplex special file. The special file must be opened for both reading and writing (). There are no particular considerations for closing the special file. The special file name used in an call differs depending on how the device is to be opened. Types of special file names are:

X.25 Error Codes

The X.25 subroutines set the and flags to indicate error conditions.

If an error condition results from an X.25 API subroutine call, it is indicated in one of the following ways:

In a production program, check for each condition that is likely to occur, giving the end user a message telling what action to take. The code for the subroutine shows how to do this. All the other subroutines can be handled in a similar way.

lists the error codes that may be returned by X.25 subroutines.

Using Processes in X.25 Applications

To improve performance, applications should be divided into multiple processes. For instance, you can start a separate process for sending or receiving data. Or, you can have one process to listen for calls and one process to make calls.

Child processes should not be created while a call is being established or after an incoming call has been received. However, you can start a process:

After an incoming call is successfully received, an open file is created in the current process that is used by the API library functions for subsequent communication on this connection. The file is closed when the call is cleared. Creating child processes after the call is received may leave the file open indefinitely, leading to an error due to reaching the limit on open files ().

A connection identifier can be used by the process that made or received the call, or by the process' children. It cannot be used by other processes.

A child process can use a virtual circuit established by its parent, but a parent process cannot use a virtual circuit established by its child.

X.25 Example Programs

To help you learn how to use the X.25 subroutines there are two pairs of example programs. One pair demonstrates the use of a switched virtual circuit, and the other the use of a permanent virtual circuit. The example programs are: