This SPD describes DECnet SNA Application Programming Interface for OpenVMS, which is available for the OpenVMS VAX and OpenVMS AXP plat- forms. All information applies to both platforms unless otherwise in- dicated. DESCRIPTION The DECnet SNA Application Programming Interface for OpenVMS (API) is a layered software product that allows user-written applications run- ning on suitably configured OpenVMS systems running DECnet or VMS/SNA software to exchange information with cooperating applications on an IBM host. The API software exists in the OpenVMS system as a share- able image. Access between the cooperating Digital and IBM applica- tions is via one of the following products: o DECnet SNA Gateway for Synchronous Transport o DECnet SNA Gateway for Channel Transport o DEC SNA Domain Gateway for Channel Transport o VMS/SNA - an OpenVMS VAX layered product that supports users on the system where VMS/SNA is running Features The DECnet SNA Application Programming Interface for OpenVMS (API) is a collection of subroutines designed to provide an easy-to-use inter- face for the OpenVMS application programmer who has a specific need to interface to an IBM application subsystem. It supports many dif- ferent types of sessions between OpenVMS applications and applica- tions running in an IBM host. DIGITAL August 1993 AE-EV67F-TE API implements all of the path control layer, and portions of the trans- mission and data flow control layers of SNA. The interface supports a number of different applications, each of which uses the SNA func- tion management, data flow control, and transmission control layers in a different way. API is not limited to supporting a particular ap- plication, such as 3270 terminals or RJE workstations; the supported April 1996 AE-EV67G-TE session types are Logical Unit Types 0, 1, 2, and 3, using the FM and TS profile types 3 and 4, as described in the product documentation. API provides extensive parameter checking, state machine management, and other high level services, relieving the OpenVMS application pro- grammer of tedious protocol details such as state machine process- ing or "standard" SNA message format checking. The interface appears to the OpenVMS application as a set of subroutines that it calls to re- quest the following operations: o Establish an SNA session with an application running on an IBM host o Respond to a session request initiated by an IBM application o Re-establish a session if the connection is broken o Disconnect from a session o Receive messages from an IBM host on the normal or expedited flow o Send messages to an IBM host on the normal or expedited flow o Provide positive or negative responses to messages transmitted from an IBM host Asynchronous Event Notification API provides a mechanism for an OpenVMS user application to receive control when an asynchronous "network event" occurs such as the dis- connection of a DECnet logical link, an SNA circuit failure, or the receipt of an Unbind Type 2 from IBM. The OpenVMS application is called at a notification entry point defined by the application at connec- tion time; an indication of the event that occurred is reported. SNA Functions API provides OpenVMS applications with access to the SNA functions per- formed by either an SNA gateway or VMS/SNA software. These include SNA path control functions, data link control functions, and upper- level functions such as checking access information. API provides as- sistance with some functions such as brackets and chaining. In addi- tion, API supports negotiable binds and handles exception responses 2 for the user application. For complete details about which SNA func- tions are pro- vided by this product, refer to the product documen- tation. The application must provide the remaining SNA functions it requires. For example, the application must be designed to: o Process all FMD layer protocols o Take into account all data flow control and session control request /response units o Keep track of any "states" relevant to the application o Translate between ASCII and EBCDIC and vice versa o Parse the bind request o Respond to request units Basic and Extended Modes The DECnet SNA Application Programming Interface for OpenVMS (Version 2.3) can be used in either basic or extended mode (it cannot be used in both modes simultaneously). In basic mode, OpenVMS applications writ- ten for the Version 1.x product are compatible with the new version, provided that they ran successfully with the earlier version. Extended mode subroutines are layered on the basic mode subroutines, providing OpenVMS programmers with an easier-to-use interface to the SNA environment. Some additional services the extended mode provides for the OpenVMS programmer include chaining, state machine checking, building request and response headers, and implementing the transmis- sion control and data flow control of SNA sessions for the user. For additional details of the two modes of operation, refer to the prod- uct documentation. User Interface 3 Users of API should be experienced OpenVMS application programmers. They can use any of the OpenVMS programming languages which conform to the OpenVMS Calling Standard to create application programs which interact with application programs on an IBM system. The user docu- mentation provides example programs written in the following languages: o MACRO-32 o C o COBOL o FORTRAN o PASCAL o PL/I Users of this product should be familiar with SNA and have some knowl- edge of the type of logical unit that will be used. Source Code Sources of message files are available only for translation to lan- guages other than English. Source Code will not be distributed for gen- eral purposes. INSTALLATION Only experienced customers should attempt installation of this prod- uct. Digital recommends that all other customers purchase Digital's Installation Services. These services provide for installation of the software product by an experienced Digital Software Specialist. Customer Responsibilities Before Digital installation of the software the customer must: o Have previously installed all requisite hardware including termi- nals and SNA gateway products. 4 o Obtain, install, and demonstrate as operational any modems and other equipment and facilities necessary to interface to Digital's com- munications equipment. o Have generated, to Digital's satisfaction, any necessary IBM host software that will be communicating with the SNA gateway or VMS/SNA and the Application Programming Interface product. o Make available for a reasonable period of time, as mutually agreed by Digital and the customer, all hardware, communications facil- ities, and terminals that are to be used during installation. Delays caused by any failure to meet these responsibilities will be charged at the prevailing rate for time and materials. Successful use of this product requires that: o The customer must be prepared to work with both Digital and IBM sys- tems personnel to coordinate the pre-installation activities. o The customer should be capable of modifying IBM component gener- ation parameters to support either the SNA gateway or VMS/SNA and the Application Programming Interface software. WARRANTY LIMITATIONS IBM Supported Configurations This software has been tested and is warranted against IBM System/370 and IBM System/390 (includes 9xxx, 30xx, and 43xx series) class pro- cessor systems configured with the following IBM software. While this software may function correctly with other IBM software and equipment, and with software other than that supported by IBM, Digital cannot of- fer its standard warranty for this software unless it has been tested with such equipment and software configurations. The API software interoperates with the following IBM software: 5 Software___________________________________________________________ Product_______Version____Release___________________________________ CICS/DOS/VS 1 7.0 CICS/MVS 2 1.2 CICS/ESA 3 1.1 2.0 3.0 ACF/VTAM______4__________1.0_______________________________________ Since the introduction of this software, other configurations may have been tested. Please contact your local Digital office for up-to-date information regarding listed configurations. PREREQUISITE SUPPORT A Network Profile and a DECnet Customer Support Plan (where appropri- ate) must be prepared jointly by Digital and the customer covering all OpenVMS nodes that wish to install the Application Interface prod- uct. In order for this product to be Digital supported, the customer must have a Digital supported SNA gateway or VMS/SNA configuration. To have a Digital supported SNA gateway configuration or VMS/SNA con- figuration, purchase of the Transport Orientation/Installation Ser- vice (QSF0X-SZ) is REQUIRED in conjunction with the customer's first purchase of an SNA gateway. HARDWARE REQUIREMENTS For AXP Systems: o AXP processor as specified in the System Support Addendum (SSA 26.86.05- x). 6 o Any properly configured SNA gateway as specified in the System Sup- port Addendum (SSA 26.86.05-x). For VAX Systems: o VAX, MicroVAX, VAXstation, or VAXserver configuration as specified in the System Support Addendum (SSA 26.86.05-x). o Any properly configured SNA gateway as specified in the System Sup- port Addendum (SSA 26.86.05-x). An alternative is to run VMS/SNA software on the same VAX system as the 3270 TE product. SOFTWARE REQUIREMENTS For AXP Systems: o OpenVMS AXP Operating System (SPD 41.87.xx) o DECnet for OpenVMS (SPD 42.25.xx) o DECnet SNA Gateway for Channel Transport (SPD 29.76.xx) or o DECnet SNA Gateway for Synchronous Transport (SPD 25.C6.xx) or o DEC SNA Domain Gateway for Channel Transport (SPD 38.69.xx) For VAX Systems in a DECnet SNA Gateway Environment: o OpenVMS VAX Operating System (SPD 25.01.xx) o DECnet-VAX (SPD 48.48.xx) o DECnet SNA Gateway for Channel Transport (SPD 29.76.xx) or DECnet SNA Gateway for Synchronous Transport (SPD 25.C6.xx) or DEC SNA Domain Gateway for Channel Transport (SPD 38.69.xx) For VAX Systems in a VMS/SNA Environment: o OpenVMS VAX Operating System (SPD 25.01.xx) o VMS/SNA Software (SPD 27.01.xx) 7 ORDERING INFORMATION DECnet SNA Application Programming Interface for OpenVMS, Version 2.3 For OpenVMS AXP systems: Software Licenses: QL-10VA*-** Software Documentation: QA-455AA-GZ Software Product Services: QT-10VA*-** Media and documentation for this product are available on the Digi- tal CD-ROM Software Library for OpenVMS AXP. Documentation in hard- copy format can be ordered separately. For OpenVMS VAX systems: Software Licenses: QL-455A*-** Software Media: QA-455A*-** Software Documentation: QA-455AA-GZ Software Product Services: QT-455A*-** * Denotes variant fields. For additional information on available li- censes, services and media refer to the appropriate price book. SOFTWARE LICENSING This software is furnished under the licensing provisions of Digital's Terms and Conditions. For more information about Digital's licensing terms and policies, contact your local Digital office. LICENSE MANAGEMENT FACILITY SUPPORT This layered product supports the OpenVMS License Management Facil- ity. License units for this product are allocated on a CPU-capacity basis. 8 For more information on the License Management Facility, refer to the OpenVMS VAX Operating System Software Product Description (SPD 25.01.xx), the OpenVMS AXP Operating System Software Product Description (SPD 41.87.xx), or the License Management Facility manual of the OpenVMS Operating Sys- tem documentation set. For more information about Digital's licensing terms and policies, con- tact your local Digital office. SOFTWARE PRODUCT SERVICES A variety of service options are available. For more information on these or other services, please contact your local Digital office. SOFTWARE WARRANTY Warranty for this software product is provided by Digital with the pur- chase of a license for the product. [TM] The Digital Logo, DEC, Digital, AXP, DECnet, OpenVMS, VAX, VMS and VT are trademarks of Digital Equipment Corporation. [R] IBM is a registered trademark of International Business Ma- chines Corporation. 8 9