HP SNA 3270 Data Stream Programming Interface for_OpenVMS_________________________________________ Release Notes October 2003 This manual describes installation notes for this release, new features not discussed in the current documentation, corrections included in this release, documentation errata, operational notes, and known problems and restrictions with this release. Revision/Update Information: This is a new manual. Operating Systems: HP OpenVMS Alpha Version 7.3-1 HP OpenVMS VAX Version 7.3 Software Version: HP SNA 3270 Data Stream Programming Interface for OpenVMS, Version 1.7 Hewlett-Packard Company Palo Alto, California ________________________________________________________________ © Copyright 2003 Hewlett-Packard Development Company, L.P. The information contained herein is subject to change without notice. The only warranties for HP products and services are set forth in the express warranty statements accompanying such products and services. Nothing herein should be construed as constituting an additional warranty. HP shall not be liable for technical or editorial errors or omissions contained herein. Proprietary computer software. Valid license from HP required for possession, use, or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license. _________________________________________________________________ Contents Preface................................................... v 1 Installation 1.1 Installation Notes............................ 1-1 2 New Features 2.1 Added Support for the Local Transport on the OpenVMS Alpha Platform........................ 2-1 3 Problems Fixed in This Release 3.1 Problems Fixed in Version 1.7 Release......... 3-1 3.1.1 Passing LOW(1) or 0 as SNA Server Gateway Name from a PL/1 Program.................. 3-1 3.1.2 Increased Maximum Length for Access Name Parameter................................. 3-1 3.2 Problems Fixed in V1.6 ECO-02 Release......... 3-1 3.2.1 Access Violation After Attempt To Reconnect Issued.......................... 3-1 3.2.2 Isolated Pacing Response Not Being Processed Causing Hang.................... 3-2 3.2.3 Connecting with the TCP Transport Fails... 3-2 3.2.4 SNA 3270 Data Stream Programming Interface Returns INVTRMPAR Error................... 3-2 iii 4 Documentation Errata and Addenda 4.1 Current Product Documentation................. 4-1 4.2 Problem Resolution and Isolation with the SNALOG_MASK Facility.......................... 4-1 4.2.1 Controlling the SNALOG_MASK Facility with OpenVMS Logical Names..................... 4-2 4.2.2 Breakdown of SNALOG_MASK Bits by Product................................... 4-4 4.2.3 Breakdown of the Bits in the Four-Bit Group..................................... 4-4 4.2.4 Setting SNALOG_MASK Bits.................. 4-5 4.2.5 Controlling Output: SNALOG_SIZE and the Directory /VERSION_LIMIT Qualifier........ 4-6 5 Operational Notes 5.1 COBOL Programming Example..................... 5-1 6 Known Problems and Restrictions iv _________________________________________________________________ Preface Intended Audience These Release Notes are intended for all SNA 3270 Data Stream Programming Interface users. Read these Release Notes before you install, upgrade, or use HP SNA 3270 Data Stream Programming Interface for OpenVMS, Version 1.7. ________________________ Note ________________________ You should read this document carefully before using the HP SNA 3270 Data Stream Programming Interface for OpenVMS, Version 1.7 software. There is no other new documentation for this release. ______________________________________________________ Structure of These Release Notes These Release Notes consist of the following chapters: o Chapter 1 describes installation information about this release. o Chapter 2 describes features that are not described in the current documentation set for the SNA 3270 Data Stream Programming Interface product. o Chapter 3 describes problems corrected in this release. o Chapter 4 contains documentation errata and addenda. o Chapter 5 contains operational notes for the SNA 3270 Data Stream Programming Interface product. o Chapter 6 contains known problems and restrictions for this release. v Reader's Comments HP welcomes your comments on this manual or any of the SNA 3270 Data Stream Programming Interface documents. Please send comments to either of the following addresses: Internet openvmsdoc@hp.com Mail Hewlett-Packard Company OSSG Documentation Group, ZKO3-4/U08 110 Spit Brook Rd. Nashua, NH 03062-2698 How To Order Additional Documentation For information about how to order additional documentation, visit the following World Wide Web address: http://www.hp.com/go/openvms/doc/ vi 1 _________________________________________________________________ Installation 1.1 Installation Notes V1.7 HP SNA 3270 Data Stream Programming Interface for OpenVMS, Version 1.7 requires either HP OpenVMS Alpha Version 7.3-1 or HP OpenVMS VAX Version 7.3. Install this kit using the VMSINSTAL command procedure by logging into the SYSTEM account and entering the following command at the DCL prompt: $ @SYS$UPDATE:VMSINSTAL SNA3270017 ddcu: [OPTIONS N] For more information about the installation process, see Digital SNA 3270 Data Stream Programming Interface for OpenVMS Installation. See Chapter 4 of these Release Notes for more information about this product's current documentation set. Installation 1-1 2 _________________________________________________________________ New Features This chapter describes features included in the SNA 3270 Data Stream Programming Interface product since the last documentation set was produced (Version 1.5). 2.1 Added Support for the Local Transport on the OpenVMS Alpha Platform V1.7 Added support for the Local transport when using the SNA Server for OpenVMS Alpha gateway. This enables local users to connect to the gateway without using a network connection. This is similar to the support found in the SNA Server for OpenVMS VAX (formerly VMS/SNA). To use the Local transport, use the following SET HOST command: $ SET HOST/SNA 0 New Features 2-1 3 _________________________________________________________________ Problems Fixed in This Release This chapter discusses problems fixed in the following releases: o Version 1.7 release o Version 1.6 ECO releases 3.1 Problems Fixed in Version 1.7 Release 3.1.1 Passing LOW(1) or 0 as SNA Server Gateway Name from a PL/1 Program When passing LOW(1) or 0 as the SNA Server gateway name parameter from a PL/1 program, the name was not recognized and an error "Gateway unknown or unreachable" was returned. This problem has been corrected and these values will be accepted as the SNA Server gateway name. 3.1.2 Increased Maximum Length for Access Name Parameter Increased the maximum length of the Access Name and Circuit parameters from 8 to 16 characters. Previously, the following error was returned for names exceeding 8 characters: %SNA-E-INVACCPAR, parameter ACCNAME is invalid -SNA-E-LENTOOLON, transmit byte count exceeds buffer length 3.2 Problems Fixed in V1.6 ECO-02 Release 3.2.1 Access Violation After Attempt To Reconnect Issued An ACCVIO error occurred when the application tried to perform a reconnect. For example, an application might attempt this when the remote IBM system became unavailable. This problem was seen while using the SNA Server (formerly VMS/SNA) as a gateway. It was caused by the session block Problems Fixed in This Release 3-1 Problems Fixed in This Release 3.2 Problems Fixed in V1.6 ECO-02 Release no longer being available or the receive buffer having been deallocated. 3.2.2 Isolated Pacing Response Not Being Processed Causing Hang When an Isolated Pacing Response (IPR) was received, and there were no receives outstanding, the pacing state was not set properly. This led to a hang in the application after the pacing window was exhausted. An additional fix was also needed to properly handle Expedited IPR's. The following error was displayed: %SNATERM-F-UNKRSPREC, unexpected response received 3.2.3 Connecting with the TCP Transport Fails As the SNA 3270 Data Stream Programming Interface establishes a connection, it tries a sequence of transports (default order is Local, DECnet and TCP). Previously, if one transport failed, the subsequent transports also failed. This problem has been corrected. 3.2.4 SNA 3270 Data Stream Programming Interface Returns INVTRMPAR Error When the SET HOST/SNA command was executed from a TELNET terminal, the SNA 3270 Data Stream Programming Interface returned the following error: %SNA$-E-ACCROUFAI, error from Gateway access routine -SNA-E-INVTRMPAR, invalid authterm parameter -SNA-E-LENTOOLON, transmit byte count exceeds buffer length SNA 3270 Data Stream Programming Interface was exceeding the maximum length of a terminal ID (32 bytes for GAP V2.1). This problem only occurred while using a TELNET terminal (that is, a terminal created via TELNET from another system) to access a PU Type 2 gateway or SNA Server through GAS. This problem has been corrected. 3-2 Problems Fixed in This Release 4 _________________________________________________________________ Documentation Errata and Addenda 4.1 Current Product Documentation V1.7 The current documentation set for the SNA 3270 Data Stream Programming Interface is shown in the following list: o HP SNA 3270 Data Stream Programming Interface for OpenVMS Software Product Description, Version 1.7 (SPD number: SPD 26.87.xx) o Digital SNA 3270 Data Stream Programming Interface for OpenVMS Installation, Version 1.5 (Order number: AA- EV64E-TE) o Digital SNA 3270 Data Stream Programming Interface for OpenVMS Programming, Version 1.5 (Order number: AA- ET84E-TE) o Digital SNA 3270 Data Stream Programming Interface for OpenVMS Problem Solving, Version 1.5 (Order number: AA-NF58C-TE) 4.2 Problem Resolution and Isolation with the SNALOG_MASK Facility V1.5 The SNA 3270 Data Stream Programming Interface has a means to trace internal events. It is called the SNALOG_ MASK facility. Note that the SNALOG_MASK facility, which runs only under OpenVMS, is very similar in function to the portable SNALOG facility, which runs under multiple operating systems. The SNALOG facility is used by some newer members of the OpenVMS SNA product set, for example, the HP SNA 3270 Application Services product. Documentation Errata and Addenda 4-1 Documentation Errata and Addenda 4.2 Problem Resolution and Isolation with the SNALOG_MASK Facility The SNALOG_MASK facility provides ASCII tracing output specific to internal routines and parameters, data stream communications, state changes, and data flow control. The output is used by engineering and support personnel in conjunction with the source code to help diagnose software problems. Therefore, there is no information about the interpretation of the output in this document. 4.2.1 Controlling the SNALOG_MASK Facility with OpenVMS Logical Names The following logical names control the operation of the SNALOG_MASK facility: SNALOG_FILE The filename for the ASCII tracing output. If not specified, the default is to place the output in the file SNALOG.DAT located in the current default directory. SNALOG_SIZE The maximum file size specified in decimal blocks (512 bytes per block). The range in values allowed is 100 to 2**22 - 1 blocks. When the approximate maximum file size is reached, the trace file is closed and a new file is opened. SNALOG_SIZE is typically used when the amount of disk space consumed by the trace file may be a problem. 4-2 Documentation Errata and Addenda Documentation Errata and Addenda 4.2 Problem Resolution and Isolation with the SNALOG_MASK Facility SNALOG_MASK The hexadecimal bitmask used to control tracing. When SNALOG_MASK is not defined or its value is "0", tracing is disabled. SNALOG_MASK is a 32-bit mask specified as a hexadecimal string (bit order 31 to 0, left to right), starting with a "0x". The general format of the SNALOG_ MASK is 0xnnnnnnnn where n is a four-bit hexadecimal value (nibble) specifying the tracing options for a specific layer. The first nibble of SNALOG_MASK specifies general tracing options for the output. If bit 31 is clear (that is, 0x7FFFFFFF) messages in the trace file are timestamped. If bit 31 is set (that is, 0xFFFFFFFF) messages in the trace file are not timestamped, instead a line of asterisk characters ( * ) are output. This facilitates the easy comparing of trace files using the DIFFERENCE utility. If bit 30 is set in the first nibble of the SNALOG_MASK (that is, 0xFFFFFFFF) the tracing subsystem logs informational messages to SYS$OUTPUT when the trace file is opened and closed. If bit 30 is clear (that is, 0xBFFFFFFF) these messages won't appear. For the actions of the other nibbles in SNALOG_MASK, see Section 4.2.2. SNALOG_BUFLEN The number of bytes of the output buffer to write (truncate to) on output. Specify the value as a decimal number. The default (-1) means the number of bytes is unlimited. The default is used if the logical name is undefined or if defined as a value less than or equal to 0. (This logical is little-used; Its value is not documented in the log file.) Documentation Errata and Addenda 4-3 Documentation Errata and Addenda 4.2 Problem Resolution and Isolation with the SNALOG_MASK Facility 4.2.2 Breakdown of SNALOG_MASK Bits by Product In addition to the timestamping and open/close message output bits described in Section 4.2.1, the bits of the SNALOG_MASK logical name are broken down into groups of four bits, with each group corresponding to a particular layer of the HP SNA Gateway product architecture. The bits are assigned as follows: 0-3 Gateway Access Interface Layer (GAI) 4-7 Extended Applications Interface Layer (EAI) 8-11 HP SNA Application Programming Interface for HP OpenVMS (API) 8-11 Network Job Entry Layer (NJE) 12-15 Access Routine GAI Interface (NEW AI) 12-15 Professional Office System Layer (PROFS) 12-15 HP SNA Remote 3270 Application Services for HP OpenVMS (R3270) 16-19 HP SNA 3270 Data Stream Programming Interface for HP OpenVMS (DSPI) 16-19 HP SNA Remote 3270 Print Services for HP OpenVMS (AS3270) 20-23 HP SNA Remote Job Entry for HP OpenVMS (RJE) 20-23 HP SNA Printer Emulator for HP OpenVMS (PRE) 20-23 HP SNA 3270 Terminal Emulator for HP OpenVMS (TE) 20-23 HP SNA Data Transfer Facility for HP OpenVMS (DTF) 20-23 SNA Distribution Services (SNADS) 24-27 General Communications Interface Layer (GCI) 4.2.3 Breakdown of the Bits in the Four-Bit Group Each group of four bits is further broken down. Each bit in the group serves a particular function: bit 0 Traces calls to routines and returns from routines bit 1 Traces buffers that are passing through the software layer bit 2 The meaning is specific to that particular software layer 4-4 Documentation Errata and Addenda Documentation Errata and Addenda 4.2 Problem Resolution and Isolation with the SNALOG_MASK Facility bit 3 The meaning is specific to that particular software layer Most OpenVMS SNA access routines include the Gateway Access Interface Layer (GAI), the Extended Applications Interface Layer (EAI), the Access Routine GAI Interface (NEW AI), and the General Communications Interface Layer (GCI). Therefore, the setting of bits 0 - 7, 12 - 15, and 24-27 produces comprehensive trace output for these products. 4.2.4 Setting SNALOG_MASK Bits Set the SNALOG_MASK bits using the DEFINE command. For example, use the following command to turn on tracing that is enabled by bits 8, 7, 5, 2, and 0: $ DEFINE SNALOG_MASK 0x000001A5 The SNALOG_MASK logical name must be defined in a logical name table that is accessible from the process that is running the image that you wish to trace. (For example, if you want to look at the trace output of the image SNADTF$FAL.EXE-an image in the HP SNA Data Transfer Facility product-the logical name must be defined as a process logical name in the process that is running that image. Alternatively, it can be a logical name in the group table for that process or a systemwide logical name.) Note that if you define SNALOG_MASK as a systemwide logical name all OpenVMS SNA access routines that incorporate SNALOG_ MASK tracing support will start to log output to their respective trace files. When submitting a problem report to HP, you should include an SNALOG.DAT file that was generated with SNALOG_MASK defined as follows: $ DEFINE SNALOG_MASK 0x7F0F000F If this produces a log file that is inordinately large, you can use a setting defined as follows: $ DEFINE SNALOG_MASK 0x7F0F0002 Documentation Errata and Addenda 4-5 Documentation Errata and Addenda 4.2 Problem Resolution and Isolation with the SNALOG_MASK Facility You should only define the SNALOG_MASK logical name when you are diagnosing a problem. When the logical name is defined, there is a significant performance impact on the executing image. Tracing is disabled by deassigning the SNALOG_MASK logical name with the command: $ DEASSIGN SNALOG_MASK Alternatively, you can define SNALOG_MASK using a value of 0 with the command: $ DEFINE SNALOG_MASK 0 4.2.5 Controlling Output: SNALOG_SIZE and the Directory /VERSION_LIMIT Qualifier As mentioned above, the SNALOG_SIZE logical name can be used to enforce an approximate block limit on the size of the trace files created. When the current trace file exceeds the defined size, the SNALOG_MASK facility closes the current trace file file and a opens a new trace file (with the version number incremented by 1). You can control the number of sequential file versions retained by specifying the /VERSION_LIMIT parameter when you create the target OpenVMS directory using the CREATE/DIRECTORY command. For example, to limit the number of trace file versions retained in the [.TRACEFILE] directory to 10, use the following command: $ CREATE/DIRECTORY/VERSION_LIMIT = 10 [.TRACEFILE] See OpenVMS online help for further information. The total amount of trace information retained is determined by a combination of the SNALOG_SIZE logical and the value of the /VERSION_LIMIT qualifier used to create the directory. Note that the information in the deleted files might or might not be required to adequately diagnose a problem. 4-6 Documentation Errata and Addenda 5 _________________________________________________________________ Operational Notes This chapter highlights various operational characteristics of the SNA 3270 Data Stream Programming Interface product that merit special attention. 5.1 COBOL Programming Example V1.6 The COBOL programming example in the Digital SNA 3270 Data Stream Programming Interface for OpenVMS Programming illustrates the use of COB$CALL to return the address of a function. The example program will link on OpenVMS VAX but not on OpenVMS Alpha. The COB$.... functions are internal calls to the compiler and are not supported for application programming. This is enforced by the OpenVMS Alpha linker. In order to build this example on OpenVMS Alpha, replace COB$CALL with a supported system service or runtime library call. Operational Notes 5-1 6 _________________________________________________________________ Known Problems and Restrictions There are no known problems or restrictions with HP SNA 3270 Data Stream Programming Interface for OpenVMS, Version 1.7. Known Problems and Restrictions 6-1