SNAX/APN Application Programming Manual Abstract This manual describes how to use the SNAX/APN CRT and ITI application programming interfaces to communicate with 3270-type devices in an attached SNA subarea network. Also included is information about the SNAX Application Logical Unit (SNALU) interface, the EXtended Logon Facility (XLF), and the Enhanced Logon Facility (ELF). This manual is for programmers who develop applications that communicate with dependent LUs Product Version SNAX/APN G06.
Document History Part Number Product Version Published 098292 SNAX/APN D21 April 1994 105777 SNAX/APN D30.00 January 1995 112214 SNAX/APN D30.02 July 1995 420111-001 SNAX/APN G06.03 December 1998 Ordering Information For manual ordering information: domestic U.S. customers, call 1-800-243-6886; international customers, contact your local sales representative. Document Disclaimer Information contained in a manual is subject to change without notice.
SNAX/APN Application Programming Manual Glossary Index Figures Tables What’s New in This Manual vii Manual Information vii New and Changed Information vii About This Manual ix Organization of This Manual x Your Comments Invited x Notation Conventions xi 1.
2. The CRT Interface (continued) Contents 2.
4. The SNALU Interface Contents 4.
A. Migrating Applications From SNAX/XF and SNAX/CDF to SNAX/APN Contents A. Migrating Applications From SNAX/XF and SNAX/CDF to SNAX/APN How SNAX/APN Differs From SNAX/XF and SNAX/CDF A-1 A-1 WRITEREAD Request Differences Incoming BIU Differences A-2 Procedure Call Differences A-2 How SNAX/APN Differs From SNAX/XF A-3 Support of the Character-Coded LOGON A-3 How SNAX/APN Differs From SNAX/CDF A-4 Support of INITOTHER and TERMOTHER Requests A-4 B.
Figures Contents Figures Figure 1-1. Role of SNAX/APN in Communication Between Applications and Devices 1-2 Figure 1-2. SNA Layers Handled by the High-Level APIs Figure 1-3. Tandem PLU Acquire Figure 1-4. Tandem PLU Accept Figure 2-1. Typical Subsystem Use of the CRT Interface 2-2 Figure 2-2. Headers and Trailer of the 3270 Data Stream 2-2 Figure 2-3. Format of the Inbound Data Stream Figure 2-4. Enabling CDI by a READ Procedure Call in Normal CDI Mode 2-5 Figure 2-5.
Tables Contents Tables Table 1-1. Device Types and Subtypes Returned by the FILE_GETINFOBYNAME_ Procedure Call 1-5 Table 2-1. Differences Between Normal, Special, and Enhanced CDI Modes Table 3-1. Simulated BREAK Keys in 3270-Type Terminals Table 4-1. SNAX Header Table 4-2. Positive Response to BIND Request Table 4-3. Negative Response to BIND Request (page 1 of 2) Table 4-4. BCI and ECI Bit Settings Table 4-5. Format of an UNBIND Request Table 4-6.
What’s New in This Manual Manual Information SNAX/APN Application Programming Manual Abstract This manual describes how to use the SNAX/APN CRT and ITI application programming interfaces to communicate with 3270-type devices in an attached SNA subarea network. Also included is information about the SNAX Application Logical Unit (SNALU) interface, the EXtended Logon Facility (XLF), and the Enhanced Logon Facility (ELF).
What’s New in This Manual New and Changed Information ELF information has been added to Section 1, Introduction to SNAX/APN High-Level APIs, under the heading Configuration Requirements for CRT and ITI on page 1-5. Under the same heading, XLF information was revised to add clarity and more configuration detail. ELF information has also been added to Appendix C, Logic Flows and Internal Formats When Using SNALU, PLU Accept Mode: Session Initiation using ELF on page C-7.
About This Manual About SNAX/APN SNAX Advanced Peer Networking (SNAX/APN) is a Tandem product that implements part of the IBM Systems Network Architecture (SNA). SNA defines various node types, and SNAX/APN implements the Node Type 2.1 (NT2.1) architecture; SNAX/APN enables a Tandem NonStop system to function as a type 2.1 node. SNAX/APN has two main functions: • • Advanced Peer-to-Peer Networking (APPN) that allows a variety of systems to communicate as peers and to support LU-LU sessions using LU6.
Organization of This Manual About This Manual The Extended Logon Facility (XLF) Using XLF enables the following communications: • • Dependent LU terminals and workstations in IBM networks can request LU-LU sessions with (logon to) Tandem applications. Tandem applications that emulate dependent LU devices can request LU-LU sessions with (logon to) applications in IBM networks. XLF requires Tandem supplied software to be installed and running in the IBM host.
Notation Conventions About This Manual Also provided on the Reader Comment Card is an Internet mail address. When you send an Internet mail message to us, we immediately acknowledge receipt of your message. A detailed response to your message is sent as soon as possible. Be sure to include your name, company name, address, and phone number in your message. If your comments are specific to a particular manual, also include the part number and title of the manual.
General Syntax Notation About This Manual | Vertical Line. A vertical line separates alternatives in a horizontal list that is enclosed in brackets or braces. For example: INSPECT { OFF | ON | SAVEABEND } … Ellipsis. An ellipsis immediately following a pair of brackets or braces indicates that you can repeat the enclosed sequence of syntax items any number of times. For example: M address-1 [ , new-value ]... [ - ] {0|1|2|3|4|5|6|7|8|9}...
Notation for Messages About This Manual !i,o. In procedure calls, the !i,o notation follows an input/output parameter (one that both passes data to the called procedure and returns data to the calling program). For example: error := COMPRESSEDIT ( filenum ) ; !i,o !i:i. In procedure calls, the !i:i notation follows an input string parameter that has a corresponding parameter specifying the length of the string in bytes.
Change Bar Notation About This Manual either vertically, with aligned braces on each side of the list, or horizontally, enclosed in a pair of braces and separated by vertical lines. For example: LBU { X | Y } POWER FAIL process-name State changed from old-objstate to objstate { Operator Request. } { Unknown. } | Vertical Line. A vertical line separates alternatives in a horizontal list that is enclosed in brackets or braces. For example: Transfer status: { OK | Failed } % Percent Sign.
1 Introduction to SNAX/APN High-Level APIs This section provides an introduction to the SNAX/APN high-level application program interfaces, CRT and ITI. For the low-level, SNALU interface, see Section 4, The SNALU Interface.
Support of Kanji Devices Introduction to SNAX/APN High-Level APIs Figure 1-1 shows the role of SNAX/APN in communication between applications and devices. Figure 1-1. Role of SNAX/APN in Communication Between Applications and Devices Tandem NonStop System CRT Application CRT API SNAX/APN ITI API SNA Subarea Network Device ITI Application CDT 101.CDD The PRT (printer) protocol, used with SNAX/XF, is not supported by SNAX/APN. Printer support is available only through the CRT protocol.
Support of Kanji Devices Introduction to SNAX/APN High-Level APIs Map Types (Names) Single Double SETMODE 144 Returns (Hex) IBMKANJI KATAKANA IBM Kanji 1402 KATAKANA-JEFKANJI KATAKANA FUJITSU JEF Kanji 1405 EBCDIC-JEFKANJI EBCDIC FUJITSU JEF Kanji 0905 SNAX/APN Application Programming Manual—420111-001 1 -3
SNA Layers Supported by the Protocols Introduction to SNAX/APN High-Level APIs SNA Layers Supported by the Protocols SNA functions are organized into layers. The functions that are automatically handled by the high-level APIs are shaded in Figure 1-2. When you use the CRT protocol, your application process must perform the presentation services functions (except when used with the Tandem Pathway/TS product, in which case Pathway/TS performs them).
Configuration Requirements for CRT and ITI Introduction to SNAX/APN High-Level APIs for both the CRT and ITI protocols. The default is subtype 21: a screen size of 24 lines with 80 characters in each line (24 by 80). Table 1-1.
Introduction to SNAX/APN High-Level APIs • • Tandem PLU Acquire whether XLF (Extended Logon Facility) or ELF (Enhanced Logon Facility) is used whether the Tandem application is acting as a primary LU (PLU) or a secondary LU (SLU). Tandem PLU Acquire Tandem PLU acquire does not require XLF or ELF configuration, and neither feature participates in session establishment.
Tandem PLU Accept Introduction to SNAX/APN High-Level APIs positive response from the device, the application can communicate directly with the device by issuing other procedure calls. Figure 1-3. Tandem PLU Acquire Tandem System SNA Host VTAM Tandem Application SNA Communication Controller OPEN NCP SNA Cluster Controller Remote LU Object BIND Request SNAX/APN IBM LU 3270 Terminal CDT 103.
Introduction to SNAX/APN High-Level APIs • • • • • • Tandem PLU Accept An APPL must be defined as subordinate to the service manager for the SNAX Creator-2 application A local LU6.2 LU must be defined for the TLOGMGR and a remote PU and a remote LU6.
Tandem PLU Accept Introduction to SNAX/APN High-Level APIs a positive response from the device, the application can communicate directly with the device by issuing other procedure calls. When ELF is used with SNAX/APN End Node, the TLOGMGR and ILOGMGR do not exist. The device’s owning VTAM sends a Locate CDINIT to the network. The ELF component of SNAX/APN End Node determines that it owns the target LU and ELF uses a template LU to create a remote LU representing the requesting device.
Introduction to SNAX/APN High-Level APIs LU-LU Sessions Between Applications and Devices LU-LU Sessions Between Applications and Devices When the configuration is done, an LU-LU session can be established between the application process and a device. The high-level SNAX/APN protocols allow a Tandem application to communicate with devices on the IBM network as though they were ordinary files residing on a Tandem system.
2 The CRT Interface This section describes the CRT interface, which supports block-mode communication with display terminals and printers. Although the CRT interface is primarily used in support of the Tandem Pathway transaction processing environment, it can be used by any application process residing on a Tandem system.
Sending and Receiving 3270 Data Streams The CRT Interface Figure 2-1. Typical Subsystem Use of the CRT Interface Tandem NonStop System User Application SNA Subarea Network CRT SNAX/APN Device User Application CDT 201.CDD Sending and Receiving 3270 Data Streams The CRT protocol enables the transmission of 3270 (or SCS) data streams between an application process and a device (either a terminal or a printer). Data streams consist of data as well as processing and formatting information.
Outbound Data Stream The CRT Interface Outbound Data Stream An outbound data stream is sent from an application process on a Tandem system to a device on an IBM system. For outbound data, the application process explicitly controls the screen format by including standard 3270 screen orders within the outgoing block of text. An application process uses a WRITE procedure call to send an outbound data stream to a device.
The Change Direction Indicator The CRT Interface 2. The second read operation is initiated by a READ procedure call; for example: CALL READ (filenum, buffer, countbuffer); This call reads the incoming data block into the second parameter, buffer. The third parameter, countbuffer, specifies the size of the incoming data block; this value is obtained by the WRITEREAD procedure call in Step 1.
Normal CDI Mode The CRT Interface You can also set CDI modes when you configure the LU with SCF or SPI. See the SCF Reference Manual for SNAX/APN or the SNAX/APN Management Programming Manual respectively for information on these configuration methods. Normal CDI Mode Normal CDI mode is the default.
Enhanced CDI Mode The CRT Interface Enhanced CDI Mode Enhanced CDI mode functions in the same way as normal CDI mode except for one additional feature. When an application issues a WRITE procedure call, it can cause the enabling of the CDI with a 3270 write command if the keyboard restore bit of the WCC byte is enabled.
Special CDI Mode The CRT Interface Figure 2-5 shows the enhanced CDI mode. Figure 2-5. Enabling CDI by a WRITE Procedure Call in Enhanced CDI Mode File-System Procedure Call Keyboard Restore Indicator WRITE WRITE READ ----- 0 1 NA CDI Status OFF ON ON ON Data Stream Outbound Outbound Null Request Unit (Outbound) Inbound CDT 205.
Summary of the Three CDI Modes The CRT Interface Table 2-1. Differences Between Normal, Special, and Enhanced CDI Modes Normal CDI Mode Enhanced CDI Mode Special CDI Mode SETMODE (163,0) (163,1) (163,2) CALL READ If part of a two-step read: Get the data from SNAX/APN. Same as normal CDI mode A READ is allowed only as part of a two-step read. Same as normal CDI mode, with one addition: Same as normal CDI mode If not part of a two-step read: From SEND state: Send (Null RU, CDI).
Functions Available With the CRT Protocol The CRT Interface Functions Available With the CRT Protocol This subsection describes the functions available when using the CRT protocol to communicate with 3270-type devices (terminals and printers).
Setting BREAK Key Ownership (SETMODE Function 11) The CRT Interface This SETMODE procedure call is relevant only to applications sending data to and receiving data from a terminal device. Setting BREAK Key Ownership (SETMODE Function 11) The file system enables a terminal user to signal a running application by pressing the break key if the application performs its own break handling.
Setting and Fetching BREAK Parameters (SETPARAM Function 3) The CRT Interface BREAK function and BREAK handling are described in greater detail in the Guardian Programmer’s Guide.
Setting Terminal Access Mode and File Access Type (SETMODE Function 12) The CRT Interface Setting Terminal Access Mode and File Access Type (SETMODE Function 12) When a BREAK owner receives a break-on-device message, it places the terminal in BREAK mode by using SETMODE function 12.
Obtaining SNA Sense Codes (SETMODE Function 53) The CRT Interface Obtaining SNA Sense Codes (SETMODE Function 53) In an SNA environment, error status from a device is passed to an application process in the form of a 4-byte sense code. In a Tandem SNAX/APN environment, an application process that uses the CRT interface receives a file-system error instead.
Setting CDI Options (SETMODE Function 144) The CRT Interface last-params allows you to view the most recent option setting. Because the option can also be set using SCF or SPI, the returned value indicates the setting before this call takes effect. Setting CDI Options (SETMODE Function 144) For protocol CRT, ITI, CREATOR and SNALU, SNAX/APN accepts the SETMODE 144 procedure call and returns information about the mapping for the current APPL object.
Waiting for LU to Start (CONTROL Operation 11) The CRT Interface sending and receiving 3270 data streams. Thus, you must reissue the SETMODE procedure call if the file is closed and then reopened. If an application closes and then later reopens, the CDI option reverts to the value configured through SCF or SPI, or (if no option is configured) the normal CDI mode.
The CRT Interface Waiting for LU to Start (CONTROL Operation 11) SNAX/APN Application Programming Manual—420111-001 2- 16
3 The ITI Interface The interactive terminal interface (ITI) is implemented through the ITI protocol.This section describes the ITI protocol, which supports conversational mode (line-at-a-time) communication with SNA 3270-type display terminals.
Sending and Receiving Data The ITI Interface Sending and Receiving Data The ITI protocol enables data to be transmitted one line at a time between an application process and a terminal. The sending party sends pure text (without control information) to the receiving party, and SNAX/APN provides screen control. Each WRITE procedure call issued by the application process is formatted by ITI before output is presented to the display.
Operational Characteristics The ITI Interface Operational Characteristics The following operational characteristics apply when using ITI: • • • Backspace and line delete are local terminal functions. Control-Y (end of file) is simulated by the PA2 key. After pressing PA2, the string EOF! is displayed on the screen. Depending on the model of the device and the character set used, certain displayable characters in ASCII code are not converted to their equivalent displayable characters in EBCDIC code.
Functions Available With the ITI Protocol The ITI Interface Functions Available With the ITI Protocol The following table lists the set of functions you can use when using the ITI protocol to communicate with 3270-type terminals, along with the procedure calls that perform these functions: Function Procedure Call Setting transfer mode SETMODE function 8 BREAK key-related functions: Setting BREAK key ownership SETMODE function 11 Setting and fetching BREAK parameters SETPARAM function 3 Setting ter
Setting BREAK Key Ownership (SETMODE Function 11) The ITI Interface Setting BREAK Key Ownership (SETMODE Function 11) The file system lets a terminal user signal a running application by pressing the BREAK key if the application performs its own BREAK handling. (If the application does not performs its own BREAK handling, pressing the BREAK key while the application is running returns you to the command interpreter where you started the application.
Setting and Fetching BREAK Parameters (SETPARAM Function 3) The ITI Interface Setting and Fetching BREAK Parameters (SETPARAM Function 3) Like SETMODE function 11, you can use SETPARAM function 3 to set parameters for BREAK handling. In addition, you can also use SETPARAM function 3 to fetch the current settings of the BREAK parameters, and to set the value of a 32-bit BREAK-tag.
Setting Terminal Access Mode and File Access Type (SETMODE Function 12) The ITI Interface Setting Terminal Access Mode and File Access Type (SETMODE Function 12) When a user presses the BREAK key at the terminal, a Break-on-device message is sent to the owner of BREAK (the process that is enabled for the BREAK key). Typically, when the BREAK owner receives the message, it places the terminal in BREAK mode by using SETMODE function 12.
Enabling Line Feed (SETMODE Function 6) The ITI Interface Enabling Line Feed (SETMODE Function 6) When you use the WRITE procedure call to send output to the terminal, you can specify whether you want to associate a carriage return/line feed (CR/LF) with each write operation using function 6 of the SETMODE procedure. If you specify no line feed, no CR/LF is issued.
Setting Auto Line Feed (SETMODE Function 7) The ITI Interface Setting Auto Line Feed (SETMODE Function 7) The carriage return is used as a line-termination character when you press the return key at the terminal to enter your input. Upon receipt of the carriage return, the system sends the terminal a line feed character if auto line feed is on.
The ITI Interface Waiting for LU to Start (CONTROL Operation 11) Waiting for LU to Start (CONTROL Operation 11) CONTROL operation 11 ensures that the LU is started. After you issue a CONTROL operation 11, the operation is not completed until the LU is started.
4 The SNALU Interface This section discusses the use of the SNAX Application Logical Unit (SNALU) interface in a SNAX/APN environment.
SNALU Message Format The SNALU Interface Figure 4-1. SNA Layers Implemented by the SNALU Interface SNA Layers 6 Presentation Services (PS) User Application 5 Data Flow Control (DFC) 4 Transmission Control (TC) 3 Path Control (PC) 2 Data Link Control (DLC) 1 Physical Control SNALU Interface Controller CDT 401.CDD To successfully implement an application using the SNALU interface, the programmer must understand the conventions and rules associated with SNA LU-LU sessions. Note.
SNAX Header The SNALU Interface Figure 4-2. Exchange of Control and Data Information With the SNALU Interface Application SNAX Header RU SNALU SNAX/APN Line Handler SNA Basic Link Unit (BLU) Controller Link CDT 402.CDD SNAX Header The application is responsible for setting the various SNAX header bits in outgoing BIUs and for interpreting them in incoming BIUs. The first nine bytes of the application I/O buffer must always contain the SNAX header. Table 4-1 describes the format of this header.
SNAX Header The SNALU Interface TC Indicators The application and the SNAX/APN line handler share the SNA transmission control functions. Bytes 0 and 1 of the SNAX header are used for passing certain TC indicators back and forth between the two processes. Figure 4-3 shows the format of the TC indicators field. Figure 4-3. TC Indicators in a SNAX Header Byte 0 Bits: Byte 1 (Reserved) QRI EFI LUNS (Reserved) 0-5 6 7 8 9 - 15 CDT 403.
Sending and Receiving BIUs: WRITEREAD Procedure The SNALU Interface For PLU processes on a Tandem system, this control bit is set to 1 in all incoming CINIT and CTERM requests.
Sending and Receiving BIUs: WRITEREAD Procedure The SNALU Interface filenum is the number of an open file that identifies the file where the WRITEREAD is to occur. buffer is the name of the application input/output buffer. write-count is a variable or literal specifying the number of bytes to be transmitted from the buffer. read-count is a variable or literal specifying the number of bytes to be accepted into the buffer.
Two-Step Read Operations (QRI Usage) The SNALU Interface The following WRITEREAD call initiates a read operation that accepts up to 250 bytes into the application I/O buffer named APPLBUF: WRITEREAD (filenum, APPLBUF, 0, 250) The WRITEREAD call completes when SNAX/APN accepts or rejects the read operation. The corresponding AWAITIO call completes when an inbound BIU has been received and placed in the buffer. 3.
Other File-System Procedures The SNALU Interface • readcount must equal 12 Note. This is the only case in which write-count can equal 6. When the read operation completes, the byte count is returned in the word area following the SNAX header, as shown in Figure 4-4: Figure 4-4. Byte Count Returned SNAX Header 9 Bytes Byte Count 1 2 Bytes CDT 404.CDD For this type of read completion, the QRI control bit is also set in the SNAX header of the incoming byte count record.
SNALU Application as PLU or SLU The SNALU Interface • The CANCEL Procedure A call to the CANCEL procedure cancels a read and/or write operation. It applies to any outstanding operation (write, read, or write and read) associated with the oldest uncompleted WRITEREAD call. Note. The CANCEL procedure has meaning only when performing nowait I/O. • The CANCELREQ Procedure A call to the CANCELREQ procedure cancels the specified read and/or write operation.
Session Phases The SNALU Interface With SNAX/APN, an application on a Tandem system can act as either a primary logical unit (PLU) or a secondary logical unit (SLU): • • When acting as a PLU, the application can establish and control LU-LU sessions with any application or any SNA device connected to an SNA terminal node controller (physical unit [PU] type 1) or an SNA cluster controller (PU type-2).
Initiating LU-LU Sessions The SNALU Interface The PLU can send an unsolicited BIND request to the SLU, or the SLU can solicit a BIND request by an SNA INIT-SELF request or a character-coded logon request (the PLU still, however, formats and sends the BIND request). This is described in detail under Initiating LU-LU Sessions on page 4-11. 2. Data Exchange Once an LU-LU session is established, the application on the Tandem system communicates with the remote LU by way of WRITEREAD procedure calls.
The SNALU Interface SNALU Application Initiates Session with Remote SLU filename identifies a remote LU by the fully qualified name assigned to it through SCF configuration. filenum supplies a variable which returns a file number that uniquely identifies this opening. flags specifies certain file-system characteristics. A single file name can be used to access several remote LUs, provided it has one session at a time.
SNALU Application Initiates Session with Remote SLU The SNALU Interface Whichever method is used to specify the SLU name in the BIND request, the SLU name must match the name configured on the VTAM system of the LU accepting the BIND request for the BIND to succeed. Response Formats A SNALU application accepts responses from the SLU in the read portion of a WRITEREAD call. Table 4-2 shows how a positive response to a BIND request appears in the application’s buffer. Table 4-2.
Remote SLU Initiates Session With SNALU Application The SNALU Interface Table 4-3. Negative Response to BIND Request (page 2 of 2) Byte Description 9-12 sense data 13 request code (X’31’ for BIND) For negative responses, the SNALU application should at least examine the sense data (bytes 9 through 12 of the incoming record) to determine why the SLU responded negatively.
SNALU Application Initiates Session With Remote PLU The SNALU Interface SLU Acquire mode. For information about the character-coded logon request, see Character-Coded Logon Requests on page 4-16. The sequence of events for SLU Acquire are as follows: 1. The application opens the SNALU LU. 2. The application formats an INIT-SELF request or character-coded logon request and sends it to the SLALU LU that was just opened. 3.
SNALU Application Initiates Session With Remote PLU The SNALU Interface Figure 4-5. Formats for INIT-SELF Requests Format Type Format 0 Format 1 Parameters for Each Function Supplies the name of an entry in a logon mode table on the host. The specified entry is used to select a BIND image. The BIND image is then passed by the host SSCP to the PLU in a CINIT request.
Remote PLU Initiates Session With SNALU Application The SNALU Interface Remote PLU Initiates Session With SNALU Application When the SNALU application is the SLU, it may open the SNALU LU, issue a WRITEREAD, and wait for an unsolicited BIND request from the PLU. This is called SLU Accept mode. For illustrations of situations in which SLU Accept is used, see Appendix C, Logic Flows and Internal Formats When Using SNALU.
Normal/Expedited Flows The SNALU Interface Normal/Expedited Flows Within a SNAX/APN environment, an application can use normal or expedited-flow RUs with the remote LU and normal-flow RUs with the SNAX/APN logon manager (TLOGMGR): • LU-LU normal flow Because sequence numbers are required for LU-LU sessions, both LUs involved in the session attach sequence numbers to all outgoing normal-flow LU-LU requests and responses.
Flow Control The SNALU Interface Flow Control A set of SNA requests is used to control the flow of RUs within an LU-LU session. The requests are discussed in sections describing data traffic protocols and DFC request/response in the IBM Systems Network Architecture: Format and Protocol Reference: Architectural Logic manual. Chaining Chaining provides a means of sending (and receiving) a sequence of requests as a single logical entity.
Brackets The SNALU Interface • • If immediate request mode is used, the sender of an RU must specify that it desires a definite response (ERI=0, DR1I and/or DR2I = 1). If delayed request mode is used, the sender of an RU can request: • • • No response A definite response An exception response The use of these modes is enforced by the data flow control (DFC) portion of the user’s application.
Pacing The SNALU Interface The IBM Systems Network Architecture: Format and Protocol Reference: Architectural Logic manual more fully describes these send and receive modes. Pacing Session-level pacing allows an LU to control the rate at which it receives requests on a normal flow. Such pacing is typically used when the sending LU is capable of transmitting requests faster than the receiving LU can process them. Note. It is recommended that SNALU applications implement pacing.
SNALU Application Terminates Session With Remote SLU The SNALU Interface Figure 4-6.
SNALU Application Terminates Session With Remote SLU The SNALU Interface Table 4-6.
SLU Initiates Termination of Session The SNALU Interface SLU Initiates Termination of Session An SLU can initiate session termination by sending an UNBIND request, a TERM-SELF request, or character-coded logoff request. A TERM-SELF request or character-coded logoff request sent by a Tandem application will be intercepted by SNALU, and a TERM-SELF request or character-coded logoff request sent by a remote LU will be intercepted by VTAM.
A Migrating Applications From SNAX/XF and SNAX/CDF to SNAX/APN This appendix covers what you need to know when migrating a SNAX/XF or SNAX/CDF application to SNAX/APN. For more information on SNAX/XF and SNAX/CDF, refer to the SNAX/XF Application Programming Manual and the SNAX/CDF Application Programming Manual, respectively.
Migrating Applications From SNAX/XF and SNAX/CDF to SNAX/APN Incoming BIU Differences Incoming BIU Differences The only incoming BIUs that an application receives with the LUNS bit set to 1 are the following: • • • • • INIT-SELF response TERM-SELF response CINIT request NSPE request NOTIFY request In SNAX/APN, a Tandem application never receives a CTERM or CLEANUP request or a USS message as it does in SNAX/CDF or SNAX/XF.
Migrating Applications From SNAX/XF and SNAX/CDF to SNAX/APN How SNAX/APN Differs From SNAX/XF How SNAX/APN Differs From SNAX/XF The following is a list of features that are supported in SNAX/XF but not in SNAX/APN. If you plan to use any or all of these features with applications migrating from SNAX/XF to SNAX/APN, or if SNAX/XF applications will be using SNAX/APN, your applications must be modified. • • • • • • The PRT protocol The ERMODE and the programmatic invocation of exception response mode X.
Migrating Applications From SNAX/XF and SNAX/CDF to SNAX/APN How SNAX/APN Differs From SNAX/CDF How SNAX/APN Differs From SNAX/CDF The following is a list of features that are supported in SNAX/CDF but not in SNAX/APN. If you plan to use any or all of these features with applications migrating from SNAX/CDF to SNAX/APN, or if SNAX/CDF applications will be running across SNAX/APN, your applications must be modified.
B Handling Errors in SNAX/APN Applications Programmers writing SNAX/APN applications must interpret two categories of error codes: • • File-system error codes, generated by the file system within the Tandem distributed processor in which the application process is executing. RU sense codes, most often generated by the remote LU with which the application is communicating, but sometimes by SNA elements that exist within the network path between the local LU and the remote LU.
File-System Error Codes Handling Errors in SNAX/APN Applications appropriate recovery operations. Table B-1 lists the error codes returned by the FILE_GETINFO_ procedure call. Note. Nowait WRITEREAD calls initiate write and read operations; the operations do not complete at the application level until execution of a corresponding AWAITIO call. Therefore, when a nowait WRITEREAD call completes with CCE, it means that the file system successfully delivered the request to SNAX/APN.
File-System Error Codes Handling Errors in SNAX/APN Applications Table B-1. File-System Error Codes (page 2 of 4) Error Number Type Meaning Possible Cause/Solution 60 (%74) ITI PRT CRT SNALU Wrong volume ID or LU not available The volume mounted is not the one on which this file resides (volume changed); the device powered off then on (old request); or an LU has not been defined or started, or has been opened and aborted.
File-System Error Codes Handling Errors in SNAX/APN Applications Table B-1. File-System Error Codes (page 3 of 4) Error Number Type Meaning Possible Cause/Solution 123 (%173) ITI PRT CRT SNALU Subdevice busy The subdevice has returned sense code x'082D' or x'0814,' or status sense DB (device busy). The printer might have a full buffer and be unable to accept any more data. Retry the operation. A second possibility is that an open request was received while a close request was being processed.
File-System Error Codes Handling Errors in SNAX/APN Applications Table B-1. File-System Error Codes (page 4 of 4) Error Number Type Meaning Possible Cause/Solution 181 (%265) ITI PRT CRT SNALU SNA device error A status/sense code of %H0801, %H0807, %H080A, %H081C, %H082A, %H082F, %H0831, or %H084A was received from an SNA device. See IBM SNA Network Product Formats for detailed information.
File-System Error Codes Handling Errors in SNAX/APN Applications Table B-2 outlines the responses when a LINE and/or PU either stops operations completely (hard down) or is interrupted. In the table, the following apply: • • • A WRITE request is a WRITEREAD request with read-count = 0 and a READ request is a WRITEREAD request with write-count = 0. A WRITEREAD request is handled the same as a WRITE request followed by a READ request.
Handling Errors in SNAX/APN Applications SNALU Outbound RU Error Codes SNALU Outbound RU Error Codes File-system error 182 indicates that SNAX/APN was unable to transmit an outbound RU passed to it by a user’s PLU or SLU process. A PLU or SLU process always uses WRITEREAD calls to send outgoing data and to receive incoming data.
Handling Errors in SNAX/APN Applications SNA Environment Errors Table B-3. Data Integrity Errors Hex Value Description 0C01 TERMINAL NOT USABLE OR POWERED OFF. 0C07 SESSION RECOVERY IN PROGRESS. Contact with the logical unit has been lost and a request was issued after session recovery has been initiated. 0C09 DEVICE OFFLINE. The device has been (or is in the process of being) deactivated by the operator. 0C0B REQUEST CANCELED. The session has been terminated.
Handling Errors in SNAX/APN Applications RU Sense Codes RU Sense Codes As an RU travels through the network to its intended destination, there are many points at which an error could occur and a negative response be generated. The user’s PLU or SLU process accepts incoming responses by means of read requests (WRITEREAD with a nonzero read-count).
Handling Errors in SNAX/APN Applications SNALU Path Errors SNALU Path Errors This category indicates that the request could not be delivered to the intended receiver, due to a path outage or an invalid sequence of activation requests. Table B-7 lists SNALU path error codes. The RU sense codes are described in detail in the IBM Systems Network Architecture: Network Product Formats manual. Table B-7. SNALU Path Errors Hex Value Description 8001 INTERMEDIATE NODE FAILURE.
C Logic Flows and Internal Formats When Using SNALU SNALU allows four modes of operation, which are described as follows: • PLU Acquire, which occurs when an application on a local system functions as a PLU and initiates a session with an SLU on a remote node by sending a BIND to that SLU • PLU Accept, which occurs when an application on a local system functions as a PLU and accepts a session initiation request (CINIT) as the read portion of a WRITEREAD procedure call from an SLU on a remote node • SL
Logic Flows and Internal Formats When Using SNALU PLU Acquire Mode: Session Initiation PLU Acquire Mode: Session Initiation In the following figures, SNAX/APN has been configured according to Table C-1 for PLU Acquire mode. If you need more information about configuring SNAX/APN, please refer to the SNAX/APN Configuration and Control Manual. Table C-1.
Logic Flows and Internal Formats When Using SNALU PLU Acquire Mode: Session Initiation In Figure C-2, Application #2 sends BINDs to the two SLUs specified in Table C-1. Because the PLU names in the BINDs do not match any local SNA name that is currently being used, the BINDs are accepted and passed on to the adjacent nodes. The BIND at (c) is rejected because plu1 is a local SNA name that is currently being used.
Logic Flows and Internal Formats When Using SNALU PLU Acquire Mode: Session Initiation In Figure C-3, the first BIND is successful, but the second BIND, at (b), fails because there is no SNA name on the LU statement (see Table C-1) and there is no SLU name in the BIND. Figure C-3.
Logic Flows and Internal Formats When Using SNALU PLU Accept Mode: Session Initiation PLU Accept Mode: Session Initiation In the following figures, SNAX/APN has been configured according to Table C-2 for PLU Accept mode. If you need more information about configuring SNAX/APN, please refer to the SNAX/APN Configuration and Control Manual. Table C-2.
Logic Flows and Internal Formats When Using SNALU PLU Accept Mode: Session Initiation using XLF Figure C-4.
Logic Flows and Internal Formats When Using SNALU PLU Accept Mode: Session Initiation using ELF PLU Accept Mode: Session Initiation using ELF Figure C-5 gives the logic flows using the Enhanced Logon Facility (ELF). The first two BINDs are successful. The logon at (c), however, fails because plu1 is still in session with LU1. The second failure shown at (c) occurs because plu9 was not defined as a local SNA name during configuration (See Table C-2).
Logic Flows and Internal Formats When Using SNALU PLU Accept Mode: Session Initiation using ELF Figure C-5.
Logic Flows and Internal Formats When Using SNALU SLU Acquire Mode: Session Initiation SLU Acquire Mode: Session Initiation In the following figures, SNAX/APN has been configured according to Table C-3 for SLU Acquire mode. If you need more information about configuring SNAX/APN, please refer to the SNAX/APN Configuration and Control Manual. Table C-3.
Logic Flows and Internal Formats When Using SNALU SLU Accept Mode: Session Initiation In Figure C-7, a second application also succeeds in establishing a BIND with a remote PLU. Figure C-7. SLU Acquire Mode of Operation: Second Application SNAX/APN (TLOGMGR) Application #2 Adjacent Node OPEN #LU1 INITSELF ( ) or LOGON ( ) PSR (pludef1,TANLU1) CDT C07.CDD In Figure C-8, the INITSELF is rejected because no SNA name was defined during configuration (see Table C-3). Figure C-8.
Logic Flows and Internal Formats When Using SNALU SLU Accept Mode: Session Initiation In Figure C-3, the first three BINDs from the remote PLU are successful. However, the fourth BIND, from plu3, fails because tanlu3 is already in session with plu2. Figure C-9.
Logic Flows and Internal Formats When Using SNALU SLU Accept Mode: Session Initiation SNAX/APN Application Programming Manual—420111-001 C -12
Glossary This glossary defines terms used in this manual. Several definitions are taken from the IBM Dictionary of Computing and the IBM Network Program Products: General Information. Please refer to these IBM manuals for IBM terms not included in this glossary. acquire. The means by which a Tandem application initiates and establishes a session with a logical unit in another domain. ADD command. A Subsystem Control Facility (SCF) command that defines an object to a subsystem.
BBI Glossary BBI. See begin bracket indicator. (BBI). begin bracket indicator. (BBI). A value in the request header that denotes the start of a bracket. BETB. See between brackets (BETB) state. between brackets (BETB) state. A state of an LU-LU session where a new bracket can be opened. bid. An attempt to gain control over a line in order to transmit data. Usually associated with contention style of sharing a single line among several terminals.
character-coded logon Glossary character-coded logon. A logon request encoded and transmitted as a character string; The format indicator in the request header (RH) for the request is set to zero. Synonymous with unformatted request. Contrast with field-formatted request. character set. A defined collection of character representations valid for a particular program, printer, or language. Characters may be stored in ASCII or EBCDIC, and may be displayed on screen or printed in a variety of languages.
domain Glossary domain. In SNA, a system services control point and the physical units, logical units, links, and associated resources that the system services control point has the ability to control by means of activation requests and deactivation requests. double-byte character. A character represented in two bytes. See also double-byte character set. double-byte character set. A character set, such as Tandem Kanji, that uses two bytes of data to represent a single character.
file-system procedure Glossary file-system procedure. A programmatic way of communicating with the file system. FMD. See function management data. function key. (1) A key on the user’s terminal keyboard (usually labeled with its function) that performs a specific function, as opposed to one that enters a character or a number. (2) A key that can be assigned a value in order to perform a special function. function management data.
Katakana character set Glossary Katakana character set. A character set of symbols used in one of the two common Japanese phonetic alphabets, which is used primarily to write foreign words phonetically. It is not supported in SNAX/APN. LEN end node. See low-entry networking (LEN) end node. logical unit (LU). An entity representing a logical port that provides access to the services of an SNA network, typically for communications between end users such as terminals, printers, or application programs.
node Glossary node. In SNA, an endpoint of a link or junction common to two or more links in a network. There are peripheral and subarea nodes. Nodes include host processors, communication controllers, cluster controllers, and workstations. Nodes can vary in routing and other functional capabilities. node type (NT). A classification of SNA network nodes on the basis of the physical unit (PU) type associated with the node. For instance, a node containing a PU of type 4 is called a Node Type 4.
peer Glossary the services of the NonStop TS/MP product. See also NonStop Transaction Services/MP (NonStop TS/MP) and Pathway. peer. An entity that communicates as an equal with another entity at the same protocol level. physical unit (PU). An entity in an SNA network that is responsible for the physical configuration of a node. It is often identified with the node itself; for example, a host is a PU Type 5. process. A unique execution of a program (that is, a running program) in the Guardian environment.
SNALU Glossary SNALU. SNAX Application Logical Unit. A SNAX/APN application protocol that provides the functions of the lower two SNA layers (data link control and path control) and some functions of the transmission control layer. SNAX/APN Logon Manager (TLOGMGR). The module within SNAX/APN that handles logon from a remote 3270 device. Works in cooperation with the Tandem Logon Manager for IBM Systems (ILOGMGR). SNAX/Creator-2 subsystem. A subsystem used with SNAX/XF or SNAX/APN.
template LU Glossary template LU. An LU that is added using SCF like standard LUs but is never opened by applications. A template LU is added for each and every CRT or ITI application that will be logged onto by devices in the IBM network when the SNAX/APN enhanced logon facility (ELF) is used. When ELF receives a logon request for a CRT or ITI application, it uses the information in that application’s template LU to build and dynamically add an LU for the requested session. terminal.
Index Numbers 3270 data streams 2-2 3270 data streams, inbound 2-3 3270 data streams, outbound 2-3 A Acquire 1-6 AID (attention identifier) character 2-3 APIs (application program interfaces) 1-1 See also CRT protocol, ITI protocol Application I/O buffer 4-5 Application program interfaces See APIs (application program interfaces) ASCII-to-EBCDIC translation 3-3 Attention identifier character See AID (attention identifier) character ATTN key CRT interface 2-10 ITI protocol 3-5 Auto line feed 3-9 AWAITIO pro
C Index BREAK tag CRT interface 2-11 ITI protocol 3-6 Break-on-device system message CRT interface 2-11 ITI protocol 3-6 C CANCEL procedure 4-9 CANCELREQ procedure 4-9 Caret (^) 3-3 Carriage return 3-8, 3-9 CCE B-1 CCG B-1 CCL B-1 CDI (change direction indicator) 2-4, 4-20 normal CDI mode 2-5, 2-6 setting 2-14 special CDI mode 2-7 Cent sign (¢) 3-3 Chaining 4-19 Change direction indicator See CDI (change direction indicator) Channel-attached terminal CRT interface 2-10 ITI protocol 3-5 Character-coded LO
F Index End of file 3-3 Enhanced CDI mode 2-6 Enhanced logon facility See ELF (enhanced logon facility) EOF! 3-3 Equal signs 3-2 Error codes file-system procedure calls B-1 error codes CRT protocol B-1 data integrity in the SNALU protocol B-7 ITI protocol B-1 PRT protocol B-1 SNA environment B-8 SNA logic B-8 SNALU outbound RUs B-7 SNALU path B-10 SNALU protocol B-1 Error handling B-1 Exclamation point (!) 3-3 Expedited-flow RUs 4-18 Extended logon facility See XLF (extended logon facility) File-system p
I Index I Inbound data streams 2-3 Initiating LU-LU sessions 4-10 INITOTHER request A-4 INIT-SELF request WRITEREAD request requirements A-1 response A-2 INIT-SELF request 4-10, 4-14 format 0 4-15 format 1 4-15 format 2 4-15 sending 4-15 Interactive terminal interface See ITI protocol ITI See ITI protocol ITI protocol error codes B-1 functions 3-4/3-10 how to use 3-1 introduction 1-1 unit of transmission 3-2 L Layers, SNA 1-4 Line delete key 3-3 line failure B-6 Line feed 3-9 automatic 3-9 enabling 3-8,
M Index M Migrating applications from SNAX/XF to SNAX/APN A-3 N Negative response formats and SNALU interface 4-13 Normal access, file access type CRT interface 2-12 ITI protocol 3-7 Normal CDI mode 2-5 Normal mode, terminal access mode CRT interface 2-10, 2-12 ITI protocol 3-5, 3-7 Normal-flow request chains 4-20 responses 4-20 NOT character 3-3 NOTIFY request A-2 response A-1 NSPE request A-2 response A-1 Null request units 2-5 O Obtaining SNA sense codes CRT interface 2-13 ITI protocol 3-7 OPEN proce
Q Index Procedure calls See also individual procedure calls error codes B-1 Processing a BIND image 4-17 PRT protocol 1-2 error codes B-1 PU failure B-6 PU type 1 and the SNALU interface 4-10 PU type 2 and the SNALU interface 4-10 Response formats SNALU interface 4-13 terminating LU-LU sessions 4-22 responses to a line or PU failure B-6 RH (request/response header) 2-4, 4-2, 4-5 Rules for LU-LU sessions 4-2 RUs (request/response units) expedited flow 4-18 sense codes B-9 Q S QRI (Queue Request Indicat
S Index Sessions See also LU-LU sessions initiated by a device 1-6, 1-7 initiated by an application 1-6 SETMODE procedure calls CRT interface 2-9 ITI protocol 3-4 SETPARAM procedure calls CRT interface 2-9 ITI protocol 3-4 Setting BREAK key owners CRT interface 2-10 Setting BREAK key ownership ITI protocol 3-5 Setting BREAK parameters CRT interface 2-11 ITI protocol 3-6 Setting CDI options 2-14 Setting echo mode 3-9 Setting file access type CRT interface 2-12 ITI protocol 3-7 Setting line feed mode 3-8, 3
T Index SNALU (SNAX application logical unit) (continued) communicating between LUs 4-17 DEVICEINFO procedure 4-9 EFI (Expedited Flow Indicator) 4-4 FILEINFO procedure 4-9 initiating LU-LU sessions 4-11 LUNS indicator 4-4 negative response formats 4-13 OPEN procedure 4-9 opening an LU 4-11 pacing 4-21 positive response formats 4-13 PU type 1 4-10 PU type 2 4-10 QRI (Queue Request Indicator) 4-4 request/response header 4-5 request/response mode 4-19 send/receive modes 4-20 sequence numbers 4-5 status codes
U Index TERMOTHER request A-4 TERM-SELF request 4-24, A-1 response A-2 TLOGMGR (SNAX/APN logon manager CLOSE procedure and 4-9 TLOGMGR (SNAX/APN logon manager) Expedited-flow RUs and 4-18 LUNS and 4-4 Trailers 1-4, 2-2 Transfer mode, set CRT interface 2-9 Transfer mode, setting ITI protocol 3-4 Translation, ASCII-to-EBCDIC 3-3 Transmission control indicators See TC (transmission control) indicators Two-step reads 2-3, 4-7 U UNBIND request 4-21, 4-22, 4-24 format 4-22 used in terminating sessions 4-21, 4-
Special Characters Index SNAX/APN Application Programming Manual—420111-001 Index -10
