HP SNA Application 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 Application Programming Interface for OpenVMS, Version 2.6 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 By This Release 3.1 Problems Fixed in Version 2.6 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 Incorrect Handling of IPRs Results in Sense Code 2001 and 200A.................. 3-1 3.2 Problems Fixed in V2.5 ECO-02 Release......... 3-1 3.2.1 Access Violation After Attempt To Reconnect Issued.......................... 3-1 3.2.2 Connecting with the TCP Transport Fails... 3-2 3.2.3 SNA Application Programming Interface Returns INVTRMPAR Error................... 3-2 3.2.4 Isolated Pacing Response Not Being Processed Causing Hang.................... 3-2 3.2.5 AST Routine Would Not Fire from SNALU0$REQUEST_DISCONNECT................. 3-2 3.2.6 SNA LU0 Applications Failed When Calling LIB$SFREE1_DD............................. 3-3 3.2.7 SNA LU0 Applications Hung During a Disconnect................................ 3-3 iii 3.2.8 SNA LU0 Applications Hung During a Connect................................... 3-3 4 Documentation Errata and Addenda 4.1 Current Product Documentation................. 4-1 4.2 Sense Argument in SNALU0$TRANSMIT_RESPONSE.... 4-1 4.3 Problem Resolution and Isolation with the SNALOG_MASK Facility.......................... 4-2 4.3.1 Controlling the SNALOG_MASK Facility with OpenVMS Logical Names..................... 4-2 4.3.2 Breakdown of SNALOG_MASK Bits by Product................................... 4-4 4.3.3 Breakdown of the Bits in the Four-Bit Group..................................... 4-4 4.3.4 Setting SNALOG_MASK Bits.................. 4-5 4.3.5 Controlling Output: SNALOG_SIZE and the Directory /VERSION_LIMIT Qualifier........ 4-6 5 Operational Notes 5.1 Invalid RU Size Errors for LU Types Other Than Zero.......................................... 5-1 5.2 COBOL Programming Example on Alpha Systems.... 5-1 5.3 Additional Information for PASCAL Users....... 5-2 5.4 Additional Information for FORTRAN Users...... 5-2 6 Known Problems and Restrictions iv _________________________________________________________________ Preface Intended Audience These Release Notes are intended for all SNA Application Programming Interface users. Read these Release Notes before you install, upgrade, or use HP SNA Application Programming Interface for HP OpenVMS, Version 2.6. ________________________ Note ________________________ You should read this document carefully before using the HP SNA Application Programming Interface for HP OpenVMS, Version 2.6 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 Application 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 Application 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 Application 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 V2.6 HP SNA Application Programming Interface for HP OpenVMS, Version 2.6 requires either HP OpenVMS Alpha Version 7.3-1 or HP OpenVMS VAX Version 7.3. Load your PAKs ahead of time before the installation. 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 SNALU0026 ddcu: [OPTIONS N] For more information about the installation process, see Digital SNA Application Programming Interface for OpenVMS Installation. See Chapter 4 of these Release Notes for more information about this product's current documentation set. When you install HP SNA Application Programming Interface for HP OpenVMS, Version 2.6 on a system which already has SNA Application Programming Interface Version 2.5, you do not need to remove SNA Application Programming Interface Version 2.5 first. The installed image SNASHR.EXE is no longer provided with the installation kit. Any existing copy of SNASHR.EXE on your system will not be removed. The PASCAL environment files, SNALIBDEF.PEN and SNALU0DEF.PEN, are no longer supplied with the installation kit. These files must be created on your own system to avoid system and compiler dependencies (see Section 5.3). Installation 1-1 2 _________________________________________________________________ New Features This chapter describes features included in the SNA Application Programming Interface product since the last documentation set was produced (Version 2.4). 2.1 Added Support for the Local Transport on the OpenVMS Alpha Platform V2.6 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 By This Release This chapter discusses problems fixed in the following releases: o Version 2.6 release o Version 2.5 ECO releases 3.1 Problems Fixed in Version 2.6 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. 3.1.2 Incorrect Handling of IPRs Results in Sense Code 2001 and 200A Expedited Isolated Pacing Responses (IPRs) were handled incorrectly and as a result RUs were rearranged out of order in the internal queue. A valid RU was then rejected with sense 2001 and/or with sense 200A. This problem happened only when the IPRs from the IBM application are in the expedited flow and not when they are in the normal flow. 3.2 Problems Fixed in V2.5 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 no longer being available or the receive buffer having been deallocated. Problems Fixed By This Release 3-1 Problems Fixed By This Release 3.2 Problems Fixed in V2.5 ECO-02 Release 3.2.2 Connecting with the TCP Transport Fails As the SNA Application Programming Interface software 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.3 SNA Application Programming Interface Returns INVTRMPAR Error When the interface was invoked from a TELNET terminal, the SNA Application Programming Interface software 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 The software 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.4 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.5 AST Routine Would Not Fire from SNALU0$REQUEST_DISCONNECT When an UNBIND was received, followed by data received on the SSCP-LU channel, and an SNALU0$REQUEST_DISCONNECT was called asynchronously, the AST routine did not fire due to the internal close routine never completing. This was observed when using the SNA Server gateway. This problem has been corrected. 3-2 Problems Fixed By This Release Problems Fixed By This Release 3.2 Problems Fixed in V2.5 ECO-02 Release 3.2.6 SNA LU0 Applications Failed When Calling LIB$SFREE1_DD SNA LU0 applications failed when calling LIB$SFREE1_DD with an error similar to the following: %SNA-F-LIBFREFAI, LIB$FREE_VM failed -STR-F-ERRFREDYN, error freeing dynamic string when returned to LIB$FREE_VM when a request RU is received that is turned into an EXR RU. 3.2.7 SNA LU0 Applications Hung During a Disconnect SNA LU0 applications would hang during a disconnect because the UNBIND response was never received/processed. This problem was only seen with the SNA Server. This has been corrected in this release. 3.2.8 SNA LU0 Applications Hung During a Connect SNA LU0 applications would hang during a connect when using the SNA Server. The following error messages would be seen in the SNALOG MASK trace: GAI state change for Connect ID = 0xxxxxxx [ Bind Received -> Unknown ] Asynchronous routine completing: GAI_RECEIVE exiting with status %SNA-E-GAPPROVIO, GAP protocol violation Problems Fixed By This Release 3-3 4 _________________________________________________________________ Documentation Errata and Addenda 4.1 Current Product Documentation V2.6 The current documentation set for the SNA Application Programming Interface product is shown in the following list: o HP SNA Application Programming Interface for OpenVMS Software Product Description, Version 2.6 (SPD number: SPD 26.86.xx) o Digital SNA Application Programming Interface for OpenVMS Installation, Version 2.4 (Order number: AA- EW86E-TE) o Digital SNA Application Programming Interface for OpenVMS Programming, Version 2.4 (Order number: AA- P591G-TE) o Digital SNA Application Programming Interface for OpenVMS Problem Solving, Version 2.4 (Order number: AA-NG05C-TE) 4.2 Sense Argument in SNALU0$TRANSMIT_RESPONSE V2.6 The description of the sense argument in Section 5.7 of the Digital SNA Application Programming Interface for OpenVMS Programming manual is incomplete. It should include a sentence stating that the sense data should be in OpenVMS format. The sentence (and a second sentence amplifying the point) were incorrectly included in the description of the event-flag argument immediately following the sense argument. Documentation Errata and Addenda 4-1 Documentation Errata and Addenda 4.3 Problem Resolution and Isolation with the SNALOG_MASK Facility 4.3 Problem Resolution and Isolation with the SNALOG_MASK Facility V2.4 The SNA Application 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. 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.3.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.3 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.3.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.3 Problem Resolution and Isolation with the SNALOG_MASK Facility 4.3.2 Breakdown of SNALOG_MASK Bits by Product In addition to the timestamping and open/close message output bits described in Section 4.3.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.3.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.3 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.3.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 0x7F000FFF If this produces a log file that is inordinately large, you can use a setting defined as follows: $ DEFINE SNALOG_MASK 0x7F000222 Documentation Errata and Addenda 4-5 Documentation Errata and Addenda 4.3 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.3.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 Application Programming Interface product that merit special attention. 5.1 Invalid RU Size Errors for LU Types Other Than Zero V2.5 If the primary request unit (RU) size (byte 11) in a BIND arrives without an RU size, the software rejects the BIND with an INVOUTSIZ error. If the secondary RU size (byte 10) in a BIND arrives without an RU size, the software rejects the BIND with an INVINBSIZ error. If the secondary RU size (byte 10) or the primary RU size (byte 11) in a BIND arrives without an RU size less than 256, the software rejects the BIND with an INVRUSIZE error. 5.2 COBOL Programming Example on Alpha Systems V2.4 The COBOL programming example in the Digital SNA Application Programming Interface for OpenVMS Programming illustrates the use of COB$CALL to get the address of a function. The example program will link on OpenVMS VAX but not on the OpenVMS Alpha. The COB$CALL is not supported on OpenVMS Alpha. In order to build the COBOL example on OpenVMS Alpha, modify the example to get the correct address of a function. Operational Notes 5-1 Operational Notes 5.3 Additional Information for PASCAL Users 5.3 Additional Information for PASCAL Users V2.4 For PASCAL users, the API symbol and structure definitions used by the application program are provided in source code files (SNALU0DEF.PAS and SNALIBDEF.PAS) and an environment files (SNALU0DEF.PEN and SNALIBDEF.PEN). The kit no longer includes the environment files. Instead, you must generate the environment files using the PASCAL compiler on your OpenVMS system. To generate the environment files, enter the following commands: $ pascal/noobject/environment=snalibdef.pen - _$ sys$library:snalibdef.pas_for_pen $ pascal/noobject/environment=snalu0def.pen - _$ sys$library:snalu0def.pas_for_pen 5.4 Additional Information for FORTRAN Users V2.4 The FORTRAN definition files, SYS$LIBRARY:SNALU0DEF.FOR and SYS$LIBRARY:SNALIBDEF.FOR, were built for FORTRAN compilers supporting structure definitions. If you plan to use a FORTRAN compiler which does not have this support, you can edit the definition files to remove the structure definitions. Structures are delimited by the keywords STRUCTURE and END STRUCTURE. You should comment out or delete all lines between the STRUCTURE and END STRUCTURE keywords except for PARAMETER statements. 5-2 Operational Notes 6 _________________________________________________________________ Known Problems and Restrictions There are no known problems or restrictions with HP SNA Application Programming Interface for HP OpenVMS, Version 2.6. Known Problems and Restrictions 6-1