User`s guide

ManualsBrandsProtogate ManualsComputer equipmentFreeway 3600

Protogate, Inc.

12225 World Trade Drive, Suite R

San Diego, CA 92128

BSC Programmer’s Guide

DC 900-1340I

December 2002

Summary of content (270 pages)

PAGE 1
BSC Programmer’s Guide DC 900-1340I Protogate, Inc.
PAGE 2
Protogate, Inc. 12225 World Trade Drive, Suite R San Diego, CA 92128 (858) 451-0865 BSC Programmer’s Guide © 2002 Protogate, Inc. All rights reserved Printed in the United States of America This document can change without notice. Protogate, Inc. accepts no liability for any errors this document might contain. Freeway is a trademark of Protogate, Inc. All other trademarks and trade names are the properties of their respective holders.
PAGE 3
Contents List of Figures 11 List of Tables 13 Preface 17 1 25 Introduction 1.1 Product Overview . . . . . . . . . . . . . . . . . . . 1.1.1 Freeway Server . . . . . . . . . . . . . . . . . . 1.1.2 Embedded ICP . . . . . . . . . . . . . . . . . . 1.2 Freeway Client-Server Environment . . . . . . . . . 1.2.1 Establishing Freeway Server Internet Addresses 1.3 Embedded ICP Environment . . . . . . . . . . . . . 1.4 Client Operations . . . . . . . . . . . . . . . . . . . 1.4.
PAGE 4
BSC Programmer’s Guide 2.1.4 Messages and Transmission Blocks. . 2.1.5 BSC 3270 Product Features. . . . . . 2.2 BSC 3270 Access Modes . . . . . . . . . . 2.3 BSC 2780/3780 Protocol Implementation 2.3.1 BSC 2780 Protocol . . . . . . . . . . 2.3.2 BSC 3780 Protocol . . . . . . . . . . 2.3.3 Transmission Codes. . . . . . . . . . 2.3.4 Messages and Transmission Blocks. . 2.3.5 BSC 2780/3780 Product Features. . . 2.4 BSC 2780/3780 Access Modes . . . . . . . 3 . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 5
Contents 3.4.2.2 Request Configuration Report . . . . . . . . . . 3.4.2.3 Request Statistics Report. . . . . . . . . . . . . . 3.4.2.4 Request Status Report . . . . . . . . . . . . . . . 3.4.2.5 Request Translation Table Report . . . . . . . . . 3.4.2.6 Request Software Version ID . . . . . . . . . . . 3.4.2.7 Request BSC 3270 Poll List . . . . . . . . . . . . 3.4.2.8 Request Virtual 3270 Device Status . . . . . . . . 3.4.3 Data Transfer using Raw dlWrite . . . . . . . . . . . . 3.4.3.1 Send Normal Data .
PAGE 6
BSC Programmer’s Guide 4.15 Safe Store Option (17) . . . . . . . 4.16 Station ID Option (18) . . . . . . 4.17 Message Blocking Option (19) . . 4.17.1 Blocking Disabled . . . . . . . 4.17.2 Data Blocking . . . . . . . . . 4.17.3 3270 Command Blocking. . . 4.18 Block Checking Option (20) . . . 4.19 Queue Limit Option (21) . . . . . 4.20 Read Session Option (23) . . . . . 4.21 Interpoll Delay Option (25) . . . . 4.22 3270 Text Addressing Option (27) 4.23 DSR/DCD Delay Option (30) . . . 4.
PAGE 7
Contents 5.4.1.12 BSC 2780/3780 Flush Queue Command . . . . . . 5.4.1.13 BSC 2780/3780 Autodial Start Command . . . . . 5.4.1.14 BSC 2780/3780 Modem Configuration Command 5.4.1.15 BSC 2780/3780 Trace using dlWrite. . . . . . . . . 5.4.2 Information Requests using Raw dlWrite . . . . . . . . . 5.4.2.1 Request Buffer Report . . . . . . . . . . . . . . . . 5.4.2.2 Request Configuration Report . . . . . . . . . . . 5.4.2.3 Request Statistics Report. . . . . . . . . . . . . . . 5.4.2.4 Request Status Report . .
PAGE 8
BSC Programmer’s Guide 6.7.5 ASCII/CCITT-0 . . . . . . . . . . 6.8 Transmission Block Size Option (8). . 6.9 Data Translation Option (10) . . . . . 6.10 Station Priority Option (11). . . . . . 6.11 Space Compression Option (12) . . . 6.12 Conversational Mode Option (13) . . 6.13 Retry Limit Option (14) . . . . . . . . 6.14 Wait for Bid Delay Option (15) . . . . 6.15 Modem Control Option (16) . . . . . 6.15.1 RTS Signal . . . . . . . . . . . . . 6.15.2 DSR Signal . . . . . . . . . . . . 6.15.3 DCD Signal .
PAGE 9
Contents A BSC 3270 Line Control Procedures A.1 Control Station Procedures . . . . . A.1.1 General Poll. . . . . . . . . . . A.1.2 Device Selection . . . . . . . . A.1.3 Specific Poll . . . . . . . . . . . A.2 Tributary Station Procedures . . . . A.2.1 Normal Mode. . . . . . . . . . A.2.2 Test Mode . . . . . . . . . . . . A.3 Line Up/Down Reporting . . . . . . A.4 Virtual Device Procedures . . . . . A.4.1 Virtual Printer Operation . . . A.4.2 Virtual Display Operation . . . A.4.3 3270 Command Checking . .
PAGE 10
BSC Programmer’s Guide B.6 Idle Line Condition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225 C ASCII Translation Tables 227 D Error Codes 233 E BSC Loopback Test Program 237 E.1 F Loopback Test Programs. . . . . . . . . . . . . . . . . . . . . . . . . . . 237 BSC Detailed Command and Response Formats F.1 BSC Protocol Processing. . . . . . . . . F.1.1 Session Attach . . . . . . . . . . . . F.1.2 Set Buffer Size . . . . . . . . . . . . F.1.3 Link Configuration . . . . . . . . .
PAGE 11
List of Figures Figure 1–1: Freeway Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Figure 1–2: Embedded ICP Configuration . . . . . . . . . . . . . . . . . . . . . . . . 27 Figure 1–3: A Typical Freeway Server Environment . . . . . . . . . . . . . . . . . . . 29 Figure 2–1: Normal 2780 Text Block. . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 Figure 2–2: Transparent 2780 Text Block . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 12
BSC Programmer’s Guide Figure A–2: Device Selection Sequence. . . . . . . . . . . . . . . . . . . . . . . . . . 195 Figure A–3: Normal Operation for Virtual Printer . . . . . . . . . . . . . . . . . . . 198 Figure A–4: Printer Error During Printout. . . . . . . . . . . . . . . . . . . . . . . . 199 Figure A–5: Normal Operation of Virtual Display . . . . . . . . . . . . . . . . . . . . 200 Figure A–6: BSC 3270 Command Checking . . . . . . . . . . . . . . . . . . . . . . .
PAGE 13
List of Tables Table 2–1: BSC 3270 Session Access Modes . . . . . . . . . . . . . . . . . . . . . . . . 36 Table 2–2: BSC 3270 Access Modes for Various Operations . . . . . . . . . . . . . . . 37 Table 2–3: BSC 2780/3780 Session Access Modes . . . . . . . . . . . . . . . . . . . . . 43 Table 2–4: BSC 2780/3780 Access Modes for Various Operations . . . . . . . . . . . . 44 Table 3–1: DLI Call Sequence for BSC 3270 (Blocking I/O) . . . . . . . . . . . . . . .
PAGE 14
BSC Programmer’s Guide Table 5–10: BSC 2780/3780 Status Report Definition. . . . . . . . . . . . . . . . . . . 143 Table 5–11: Last Event Codes for Link Status Report . . . . . . . . . . . . . . . . . . . 145 Table 5–12: BSC 2780/3780 Response Codes . . . . . . . . . . . . . . . . . . . . . . . 151 Table 6–1: BSC 2780/3780 Link Configuration Options and Settings . . . . . . . . . 156 Table 6–2: Recommended Data Translation Settings . . . . . . . . . . . . . . . . . .
PAGE 15
List of Tables Table F–12: BSC Receive Data Responses . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 16
BSC Programmer’s Guide 16 DC 900-1340I
PAGE 17
Preface Purpose of Document This document describes the operation and programming interface required to use Protogate’s Binary Synchronous Communications (BSC) product for Protogate’s Freeway communications server or embedded ICP. Note In this document, the DLI API interface applies to both a Freeway server or an embedded ICP using DLITE. For the embedded ICP, also refer to the user’s guide for your ICP and operating system (for example, the ICP2432 User’s Guide for Windows NT (DLITE Interface)).
PAGE 18
BSC Programmer’s Guide • a Freeway communications server or an embedded ICP that runs the communications software • a client computer that runs the following: • TCP/IP (for a Freeway server) • Data link interface (DLI) • the user application program Organization of Document Chapter 1 is an overview of Freeway and the BSC product. Chapter 2 summarizes the basic communication protocol formats available on the BSC software package.
PAGE 19
Preface Appendix C contains the ASCII/EBCDIC code translation tables. Appendix D describes error handling and lists the error codes. Appendix E describes the BSC loopback test program. Appendix F gives detailed examples of command and response header formats. 11/16/98 Leslie: Changed appropriate documents to DC-908-xxxx (Export Restricted). Most are in the Military/Gove rnment separate table. Remove “Freeway” from several.
PAGE 20
BSC Programmer’s Guide Freeway Software Installation Support • • • • • Freeway Server User’s Guide DC 900-1333 Freeway Software Release Addendum: Client Platforms DC 900-1555 Getting Started with Freeway 1100/1150 DC 900-1369 Getting Started with Freeway 2000/4000 DC 900-1330 Loopback Test Procedures DC 900-1533 Embedded ICP Installation and Programming Support • • • • ICP2432 User’s Guide for Tru64 UNIX DC 900-1513 ICP2432 User’s Guide for OpenVMS Alpha (DLITE Interface) DC 900-1516 ICP2
PAGE 21
Preface • • • • • • • • • • • • • • BSCDEMO User’s Guide DC 900-1349 BSCTRAN Programmer’s Guide DC 900-1406 DDCMP Programmer’s Guide DC 900-1343 Freeway AUTODIN Programmer’s Guide DC 908-1558 Freeway FMP Programmer’s Guide DC 900-1339 Freeway Marketfeed 2000 Programmer’s Guide DC 900-1346 Freeway MRS Protocol Programmer’s Guide DC 900-1565 Freeway SIO STD-1300 Programmer’s Guide DC 908-1559 Freeway SWIFT and CHIPS Programmer’s Guide DC 900-1344 Military/Government Protocols Programmer’s
PAGE 22
BSC Programmer’s Guide embedded ICP product using DLITE (for example, the embedded ICP2432 using DLITE on a Windows NT system). Physical “ports” on the ICPs are logically referred to as “links.” However, since port and link numbers are usually identical (that is, port 0 is the same as link 0), this document uses the term “link.” Program code samples are written in the “C” programming language.
PAGE 23
Preface Revision DC 900-1340G Release Date April 1998 Description • • • DC 900-1340H November 1998 • • • • • DC 900-1340I December 2002 • Modify Section 1.1 through Section 1.4. Changes to BSC 3270: minor changes to Section 3.1.2 on page 47 and Section 3.2 on page 50, add dlpErrString function (Table 3–3 on page 53) Changes to BSC 2780/3780: minor changes to Section 5.1.2 on page 107 and Section 5.
PAGE 24
BSC Programmer’s Guide 24 DC 900-1340I
PAGE 25
Chapter 1 Introduction 1.1 Product Overview Most recent modification date: 03/25/98 Leslie: Remove “Freeway Embedded” and just say “embedded ICP” (as an interim fix prior to BIG makeover). Protogate provides a variety of wide-area network (WAN) connectivity solutions for real-time financial, defense, telecommunications, and process-control applications. Protogate’s Freeway server offers flexibility and ease of programming using a variety of LAN-based server hardware platforms.
PAGE 26
BSC Programmer’s Guide To maintain high data throughput, Freeway uses a multi-processor architecture to support the LAN and WAN services. The LAN interface is managed by a single-board computer, called the server processor. It uses the commercially available VxWorks operating system to provide a full-featured base for the LAN interface and layered services needed by Freeway.
PAGE 27
1: Introduction 1.1.2 Embedded ICP The embedded ICP connects your client computer directly to the WAN (for example, using Protogate’s ICP2432 PCIbus board). The embedded ICP provides client applications with the same WAN connectivity as the Freeway server, using the same data link interface. The ICP runs the communication protocol software using Protogate’s real-time operating system. Figure 1–2 shows the embedded ICP configuration.
PAGE 28
BSC Programmer’s Guide Summary of product features: • Provision of WAN connectivity either through a LAN-based Freeway server or directly using an embedded ICP • Elimination of difficult LAN and WAN programming and systems integration by providing a powerful and consistent data link interface • Variety of off-the-shelf communication protocols available from Protogate which are independent of the client operating system and hardware platform • Support for multiple WAN communication protocols simulta
PAGE 29
1: Introduction 1.2 Freeway Client-Server Environment The Freeway server acts as a gateway that connects a client on a local-area network to a wide-area network. Through Freeway, a client application can exchange data with a remote data link application. Your client application must interact with the Freeway server and its resident ICPs before exchanging data with the remote data link application.
PAGE 30
BSC Programmer’s Guide 1.2.1 Establishing Freeway Server Internet Addresses The Freeway server must be addressable in order for a client application to communicate with it. In the Figure 1–3 example, the TCP/IP Freeway server name is freeway2, and its unique Internet address is 192.52.107.100. The client machine where the client application resides is client1, and its unique Internet address is 192.52.107.99.
PAGE 31
1: Introduction 1.4.2 Opening a Session After the DLI and TSI configurations are properly defined, your client application uses the dlOpen function to establish a DLI session with an ICP link. As part of the session establishment process, the DLI establishes a TSI connection with the Freeway MsgMux through the TCP/IP BSD-style socket interface for the Freeway server, or directly to the client driver for the embedded ICP environment. 1.4.
PAGE 32
BSC Programmer’s Guide 1.5.1 Software Description Protogate’s BSC product includes the following major software components: • A group of communications software downloadable images: 1. Freeway server or embedded ICP software 2. Real-time operating system (OS/Impact or OS/Protogate) 3. BSC 3270 and BSC 2780/3780 communications software • DLI library for linking with client applications • A loopback test programs (bsc3270alp.c or bsc3780alp.
PAGE 33
Chapter 2 BSC Protocol Summary 2.1 BSC 3270 Protocol Implementation The Protogate Binary Synchronous Communications (BSC) product is a software package that allows applications running on the client to communicate through one or more serial ports (links) to devices using the IBM BSC 3270 and/or the BSC 2780/3780 protocol. Each BSC serial link handles all low-level protocol activity thus freeing the client processor to perform other tasks.
PAGE 34
BSC Programmer’s Guide 2.1.1 3270 Control Station Operation A link configured as a control station can poll up to 32 tributary stations (control units). Tributaries may be added to or removed from the polling list at any stage of link operation. Data blocks received from tributary stations are marked with the sender’s control unit (CU) number and device unit (DU) number. The control station selects tributary stations when it has data to send.
PAGE 35
2: BSC Protocol Summary 2.1.4 Messages and Transmission Blocks The client computer sends data to the BSC software as complete messages. A message consists of one or more buffers of text or binary data. The BSC control characters are not included in the message. The control characters are inserted by the Freeway server before transmitting the data. Once in memory, the messages may be transmitted in smaller blocks, called transmission blocks, to provide more accurate and efficient error control.
PAGE 36
BSC Programmer’s Guide The valid BSC 3270 access modes are defined in Table 2–1. Table 2–2 shows the required access modes for various operations. Note The concept of a Control session is unique to Protogate’s BSC product. Do not confuse it with the terms “control station” and “control unit,” which are defined by the BSC 3270 protocol. You can have a Control session on either a control station or a control unit (tributary station).
PAGE 37
2: BSC Protocol Summary Table 2–2: BSC 3270 Access Modes for Various Operations Operation Access Mode Required Reference Section Set Translation Table Manager or Read Section 3.4.1.1 Clear Statistics Manager or Read Section 3.4.1.2 Set ICP Message Buffer Size Any mode Section 3.4.1.3 Configure Link Manager or Read Section 3.4.1.4 Start Link Manager or Control Section 3.4.1.5 Stop Link Manager or Control Section 3.4.1.6 Set Poll List Manager Section 3.4.1.
PAGE 38
BSC Programmer’s Guide 2.3 BSC 2780/3780 Protocol Implementation The protocol used in the BSC 2780/3780 product is a logical, half-duplex, bisynchronous, point-to-point protocol used by IBM 2780 and IBM 3780 remote job entry terminals (sometimes called RJE terminals). Details on the operation of IBM’s BSC protocol can be found in document GA27-3004, General Information — Binary Synchronous Communications, IBM.
PAGE 39
2: BSC Protocol Summary Figure 2–2 shows the transparent 2780 text block. Each block starts with a data-linkescape STX character pair (a DLE STX character combination) and ends with a DLE ETB or DLE ETX character pair. Each record within the text block also starts with DLE STX and ends with a DLE US. In transparent operation, two SYN characters must be inserted after each block check character that follows DLE US.
PAGE 40
BSC Programmer’s Guide SYN SYN STX record RS record RS record ETX BCC PAD Figure 2–3: Normal 3780 Text Block SYN SYN DLE STX record DLE RS record DLE RS record DLE RS DLE ETX BCC PAD Figure 2–4: Transparent 3780 Text Block The maximum size for a 3780 text block is 512 bytes including the STX and ETX characters. BSC 3780 also allows for compression of two or more consecutive space characters within the text block.
PAGE 41
2: BSC Protocol Summary called transmission blocks, to provide more accurate and efficient error control. BSC begins each transmission block with a start-of-text (STX) control character and ends each with an end-of-transmission-block (ETB) control character, except for the last block of the message which ends with an end-of-text (ETX) character. All data blocking and deblocking is transparent to the user; however, the ICP message buffer size (Section 5.4.1.
PAGE 42
BSC Programmer’s Guide The following features allow greater programming flexibility: • Multiple levels of interface routines • Automatic dialing of SADL, AT, and V.25bis autodial modems • Trace session for recording protocol activity • Control session for control and monitoring of multiple links • Automatic text blocking and deblocking The multipoint (poll-select) protocol operation feature is not supported by the Protogate BSC 2780/3780 product. 2.
PAGE 43
2: BSC Protocol Summary Table 2–3: BSC 2780/3780 Session Access Modes Mode Usage Manager Set Manager mode for a session by setting the DLI “mode” configuration parameter to “mgr.” Manager mode gives the client the right to issue any command or request. There can be only one Manager session per link. Read Set Read mode for a session by setting the DLI “mode” configuration parameter to “read.
PAGE 44
BSC Programmer’s Guide Table 2–4: BSC 2780/3780 Access Modes for Various Operations Operation 44 Access Mode Required Reference Section Set Translation Table Manager or Read Section 5.4.1.1 Clear Statistics Manager, Read, or Control Section 5.4.1.2 Set ICP Message Buffer Size Manager, Read, or Control Section 5.4.1.3 Configure Link Manager, Read, or Control Section 5.4.1.4 Start Link Manager or Control Section 5.4.1.5 Stop Link Manager or Control Section 5.4.1.
PAGE 45
Chapter 3 Note Note BSC 3270 DLI Functions In this chapter, the DLI API interface applies to both a Freeway server or an embedded ICP using DLITE. For the embedded ICP, also refer to the user’s guide for your ICP and operating system (for example, the ICP2432 User’s Guide for Windows NT (DLITE Interface)). This chapter, along with Chapter 4 and Appendix A, should be read by programmers who are interfacing an application program to a BSC 3270 environment.
PAGE 46
BSC Programmer’s Guide • Appendix D explains error handling and provides a summary table of BSC error codes. The Freeway Data Link Interface Reference Guide gives complete DLI error code descriptions. • The Freeway Data Link Interface Reference Guide provides a generic code example which can guide your application program development, along with the program described in Appendix E of this manual. • Appendix F provides detailed command and response header formats. 3.
PAGE 47
3: BSC 3270 DLI Functions configurations are defined by specifying parameters in DLI and TSI ASCII configuration files and then running two preprocessor programs, dlicfg and tsicfg, to create binary configuration files. Refer to Chapter 7 of this document, as well as the Freeway Data Link Interface Reference Guide and the Freeway Transport Subsystem Interface Reference Guide.
PAGE 48
BSC Programmer’s Guide sequence (especially in BSC 3270). Refer to the Freeway Data Link Interface Reference Guide if you need to use Raw operation. Normal and Raw operations can be mixed. For example, the client application session can be configured for Normal operation (allowing DLI to handle link startup and configuration), but the read and write requests (Section 3.4 on page 55 and Section 3.
PAGE 49
3: BSC 3270 DLI Functions ware interrupt level in the completion handler established by the dlInit or dlOpen function, or by periodic use of dlPoll to query the I/O completion status. The asyncIO DLI configuration parameter specifies whether an application session uses blocking or non-blocking I/O. The alwaysQIO DLI configuration parameter further qualifies the operation of non-blocking I/O activity. Refer to the Freeway Data Link Interface Reference Guide for more information.
PAGE 50
BSC Programmer’s Guide 3.2 Example BSC 3270 Call Sequences Table 3–1 shows the sequence of DLI function calls to send and receive data using blocking I/O. Table 3–2 is the non-blocking I/O example. The remainder of this chapter and the Freeway Data Link Interface Reference Guide give further information about each function call. Note The example call sequences assume that the cfgLink and enable DLI configuration parameters are both set to “yes” (the defaults).
PAGE 51
3: BSC 3270 DLI Functions Caution When using non-blocking I/O, a dlRead request must always be queued to avoid loss of data or responses from the ICP (see Step 5 of Table 3–2). Table 3–2: DLI Call Sequence for BSC 3270 (Non-blocking I/O) 1. Call dlInit to initialize the DLI operating environment. The first parameter is your DLI binary configuration file name. 2. Call dlOpen for each required session (link) to get a session ID. 3. Call dlPoll to confirm the success of each session ID obtained in Step 2.
PAGE 52
BSC Programmer’s Guide 3.3 Overview of DLI Functions for BSC 3270 This section summarizes the DLI functions used in writing a client application.
PAGE 53
3: BSC 3270 DLI Functions Table 3–3: DLI Functions: Syntax and Parameters (Listed in Typical Call Order) DLI Function Parameter(s) Parameter Usage int dlInit (char *cfgFile, char *pUsrCb, int (*fUsrIOCH)(char *pUsrCb)); DLI binary configuration file name Optional I/O complete control block Optional IOCH and parameter int dlOpen1 (char *cSessionName, int (*fUsrIOCH) (char *pUsrCB, int iSessionID)); Session name in DLI config file Optional I/O completion handler Parameters for IOCH int dlPoll (int
PAGE 54
BSC Programmer’s Guide 3.3.1 DLI Optional Arguments Section 3.4 and Section 3.5 describe the dlWrite and dlRead functions for a BSC 3270 application. Both functions can use the optional arguments parameter to provide the protocol-specific information required for Raw operation (Section 3.1.2). The “C” definition of the optional arguments structure is shown in Figure 3–1.
PAGE 55
3: BSC 3270 DLI Functions 3.4 Overview of BSC 3270 Requests using dlWrite For BSC 3270 the dlWrite function supports three dlWrite categories: commands, information requests, and data transfer, which are discussed in detail in Section 3.4.1 through Section 3.4.3. Whether you use blocking or non-blocking I/O, each dlWrite request must be followed by a dlRead request to receive the command confirmation, information requested, or acknowledgment of the data transfer. Section 3.
PAGE 56
BSC Programmer’s Guide Table 3–4: Categories for BSC 3270 dlWrite Requests Category Commands to ICP Report Requests Data Transfer 56 DLI Request Code Usage DLI_PROT_CFG_LINK Configure link DLI_PROT_CHANGE_STATUS Change virtual 3270 device status DLI_PROT_CLR_STATISTICS Clear statistics DLI_PROT_CREATE_DEVICE Create virtual 3270 devices DLI_PROT_SAFE_STORE_ACK Send safe store acknowledge DLI_PROT_SEND_BIND Start link DLI_PROT_SEND_EOT Send EOT DLI_PROT_SEND_UNBIND Stop link DLI_PROT_S
PAGE 57
3: BSC 3270 DLI Functions 3.4.1 Commands using Raw dlWrite Section 3.4.1.1 through Section 3.4.1.12 explain how to issue specific commands to the BSC 3270 software using the dlWrite function. Call dlRead to receive the command confirmation response (the dlRead pOptArgs.usProtCommand field is set by the DLI). 3.4.1.1 Set Translation Table Command Use the dlWrite function with the DLI_PROT_SET_TRANS_TABLE pOptArgs.usProtCommand field set to to set translation table 1 or 2. Use the MSB of the pOptArgs.
PAGE 58
BSC Programmer’s Guide specify the CU. If the LSB of the field is not set to ‘1,’ the overall link statistics are not cleared. Use CU number 32 to clear statistics for all control units. An unsuccessful Clear Statistics command can return the following error code in the dlRead pOptArgs.iICPStatus field (see Appendix D for error handling): DLI_ICP_ERR_BAD_MODE The function request is not available for the requested access mode. 3.4.1.
PAGE 59
3: BSC 3270 DLI Functions DLI_ICP_ERR_BAD_MODE The function request is not available for the requested access mode. DLI_ICP_ERR_BAD_PARMS The parameter value(s) used for the function call are illegal. DLI_ICP_ERR_LINK_ACTIVE The link is already started. 3.4.1.
PAGE 60
BSC Programmer’s Guide pBuf configuration option = 1 (data rate) Word 0 configuration value = 9 (9600) 1 configuration option = 20 (block checking) 2 configuration value = 0 (disabled) 3 0 4 iBufLen = 10 Figure 3–2: Link Configuration Block with Two Options Each option number corresponds to a software-selectable option of the BSC 3270 software. The configuration value is used to set that option. Table 4–1 on page 86 lists the available options and values for the BSC 3270 protocol.
PAGE 61
3: BSC 3270 DLI Functions a link after issuing a Stop Link command (Section 3.4.1.6). After receiving this command, the BSC 3270 software turns on the DTR modem control signal and prepares the link to transmit and receive data according to the current configuration settings. After a link starts, data transmission can begin on the line.
PAGE 62
BSC Programmer’s Guide nate a session at the end of a client application. The Stop Link command is useful for temporarily stopping the link without terminating the session (for example, to reconfigure the link using the Link Configuration command). The link is restarted again by issuing a Start Link command. For blocking I/O a successful Stop Link command returns zero, but you must call dlRead to receive the DLI_PROT_RESP_UNBIND_ACK response indicating the link is deacti- vated.
PAGE 63
3: BSC 3270 DLI Functions BSC 3270 software responds with the new poll list using the same pOptArgs.usProtCommand field and format used to set the poll list. Byte pBuf 0 0 1 1 3 2 6 3 iBufLen = 4 Figure 3–3: Set Poll List Command Example It is possible to configure an “empty” poll list by issuing a poll list command with a –1 (hex FF) as the only CU number in the list.
PAGE 64
BSC Programmer’s Guide 3.4.1.8 Safe Store Acknowledge Command Use the dlWrite function with the DLI_PROT_SAFE_STORE_ACK pOptArgs.usProtCommand field set to to acknowledge a stored message. When the safe store option is enabled, this command must be sent to the BSC software after each end-of-message data block (pOptArgs.usProtCommand field set to DLI_PROT_SEND_NORM_DATA_EOM or DLI_PROT_SEND_TRANS_DATA_EOM) is received by the client.
PAGE 65
3: BSC 3270 DLI Functions Note that with the safe store option enabled, the client application program must send an acceptance (safe store acknowledge) or rejection (EOT) after every complete message is received. Otherwise, normal data communication on the line is suspended. If the last block of a received message contains a parity or block check error, BSC transmits a NAK response as it would with any other block containing an error.
PAGE 66
BSC Programmer’s Guide Safe Store on BSC 3270 Tributary Stations Unlike the control station, a tributary station is unable to send WACKs on the line to keep it active. In the 3270 protocol, a WACK from a tributary station constitutes a positive acknowledgment thus barring its use for safe store operation.
PAGE 67
3: BSC 3270 DLI Functions 3.4.1.10 Send EOT Command Use the dlWrite function with the DLI_PROT_SEND_EOT pOptArgs.usProtCommand field set to to reject a received message when using the safe store option (Section 4.15 on page 96). The Send EOT is queued behind any preceding outgoing messages. The BSC 3270 software returns a confirmation response with the dlRead pOptArgs.usProtCommand field set to DLI_PROT_SEND_EOT when the EOT is sent success- fully.
PAGE 68
BSC Programmer’s Guide pOptArgs.usProtCircuitID field to the control unit number to which the virtual devices are to be attached. Figure 3–5 is an example of the pBuf data area for a command to create virtual displays 0, 1, and 3 and virtual printers 2 and 4.
PAGE 69
3: BSC 3270 DLI Functions Table 3–5: Device Status Values Status Value Specified in the pOptArgs.iProtModifier Field Description DLI_ICP_ERR_NO_ERR The device is available and ready to accept 3270 commands from the control station. DLI_ICP_ERR_DEVICE_BUSY The device is available but is currently performing some operation (such as printing). DLI_ICP_ERR_DEVICE_UNAVAIL The device is unavailable or has become mechanically disabled (such as printer out of paper).
PAGE 70
BSC Programmer’s Guide Section A.4 on page 197 for more information on virtual device procedures and line sequence diagrams. An unsuccessful Change Virtual 3270 Device Status command can return one of the following error codes in the dlRead pOptArgs.iICPStatus field (see Appendix D for error handling): DLI_ICP_ERR_BAD_MODE The function request is not available for the requested access mode. DLI_ICP_ERR_BAD_PARMS The parameter value(s) used for the function call are illegal.
PAGE 71
3: BSC 3270 DLI Functions 3.4.2 Information Requests using Raw dlWrite Section 3.4.2.1 through Section 3.4.2.8 explain how to issue specific information requests to the BSC 3270 software using the dlWrite function. You must then make a Raw dlRead request to receive the report information (the dlRead pOptArgs.usProtCommand field is set by the DLI to reflect the type of report, and the iBufLen parameter indicates the size of the message).
PAGE 72
BSC Programmer’s Guide 3.4.2.2 Request Configuration Report Use the dlWrite function with the DLI_PROT_GET_LINK_CFG pOptArgs.usProtCommand field set to to request the current configuration option settings for a link. The dlRead configuration report response (the pOptArgs.usProtCommand field is set to DLI_PROT_GET_LINK_CFG by the DLI) consists of a sequence of 16-bit word pairs containing the option number in the first word and the option setting in the second.
PAGE 73
3: BSC 3270 DLI Functions Table 3–7: BSC 3270 Statistics Report Definition Word Statistic 1 Block check errors 2 Parity errors 3 Receive overrun errors 4 Buffer errors 5 Messages sent 6 Messages received 7 NAKs sent 8 NAKs received 9 Poll timeouts 10 Select timeouts 3.4.2.4 Request Status Report Use the dlWrite function with the DLI_PROT_GET_STATUS_REPORT pOptArgs.usProtCommand field set to to request the current link status.
PAGE 74
BSC Programmer’s Guide Table 3–8: Status Report Definition Word 1 2 3 4 5 6 7 8 74 Description Link status Current operation mode DTR DCD RTS CTS Receiver Transmitter 9 Reserved 10 Reserved 11 DSR Value Setting 0 off 1 on 2 starting 0 idle 1 DSR off 0 off 1 on 0 off 1 on 0 off 1 on 0 off 1 on 0 off 1 on 0 off 1 on 0 off 1 on DC 900-1340I
PAGE 75
3: BSC 3270 DLI Functions The signals DTR, DSR, DCD, RTS, and CTS are reported on when the link detects them. The transmitter or receiver is on while the link is actually transmitting or receiving data. The transmitter is also reported as on if the link is attempting (unsuccessfully) to transmit data on the line. This situation can occur if the transmit clock signal is not present. 3.4.2.5 Request Translation Table Report Use the dlWrite function with the pOptArgs.
PAGE 76
BSC Programmer’s Guide 3.4.2.7 Request BSC 3270 Poll List Use the dlWrite function with the DLI_PROT_GET_POLL_LIST pOptArgs.usProtCommand field set to to request the current BSC 3270 poll list. The dlRead poll list report response (the pOptArgs.usProtCommand field is set to DLI_PROT_GET_POLL_LIST by the DLI) has the same format as the dlWrite Set Poll List command (Figure 3–3 on page 63). 3.4.2.8 Request Virtual 3270 Device Status Use the dlWrite function with the pOptArgs.
PAGE 77
3: BSC 3270 DLI Functions When a tributary link is started, each device on that link has a status associated with it based on the settings of the device status bits. Every device on the link is in one of four general status conditions, which determines how that device responds to select sequences from the BSC 3270 master. Table 3–9 lists the status conditions and responses.
PAGE 78
BSC Programmer’s Guide 3.4.3 Data Transfer using Raw dlWrite The BSC 3270 software provides two write types (EOM and non-EOM) for each data transfer to allow the user to send or receive a single message that is larger than the configured ICP message buffer size. Each type of data block consists of n bytes of data, where n is a number from 0 to the maximum data size specified by the Set ICP Message Buffer Size command (Section 3.4.1.3). Set the MSB of the pOptArgs.
PAGE 79
3: BSC 3270 DLI Functions An unsuccessful dlWrite data transfer request can return one of the following error codes in the dlRead pOptArgs.iICPStatus field (see Appendix D for error handling): DLI_ICP_ERR_LINK_INACTIVE The link is stopped. DLI_ICP_ERR_BAD_MODE The function request is not available for the requested access mode. DLI_ICP_ERR_XMIT_TIMEOUT The protocol software was unable to transmit the data. This error occurs when some or all of the modem signals are not present. 3.4.3.
PAGE 80
BSC Programmer’s Guide 3.5 Overview of BSC 3270 Responses using Raw dlRead Table 3–10 shows the valid BSC 3270 codes sent to your application in response to a Raw dlRead request; the returned dlRead pOptArgs.usProtCommand field indicates the response code. If the dlRead return value is zero or positive, it indicates the number of bytes read; if it is less than zero, an error has occurred. BSC error codes that can be associated with the responses are returned in the pOptArgs.
PAGE 81
3: BSC 3270 DLI Functions Table 3–10: BSC 3270 Response Codes Category Received Data Sense/Status Message DLI Response Code in pOptArgs.usProtCommand Field Section DLI_PROT_SEND_NORM_DATA Normal received data Section 3.5.1 DLI_PROT_SEND_NORM_DATA_EOM Normal received data (end of message) Section 3.5.1 DLI_PROT_SEND_TRANS_DATA Transparent received data Section 3.5.1 DLI_PROT_SEND_TRANS_DATA_EOM Transparent received data (end of message) Section 3.5.
PAGE 82
BSC Programmer’s Guide Table 3–10: BSC 3270 Response Codes (Cont’d) Category Reports DLI Response Code in pOptArgs.usProtCommand Field Usage Section DLI_PROT_GET_BUF_REPORT Buffer report Section 3.4.2.1 DLI_PROT_GET_LINK_CFG Link configuration report Section 3.4.2.2 DLI_PROT_GET_STATISTICS_REPORT Statistics report Section 3.4.2.3 DLI_PROT_GET_STATUS_REPORT Link status report Section 3.4.2.4 DLI_PROT_GET_TRANS_TABLE Translation table report Section 3.4.2.
PAGE 83
3: BSC 3270 DLI Functions 3.5.1 Normal and Transparent Received Data The BSC 3270 software provides four read codes for data reception: two for normal data (DLI_PROT_SEND_NORM_DATA and DLI_PROT_SEND_NORM_DATA_EOM) and two for transparent data (DLI_PROT_SEND_NORM_DATA and DLI_PROT_SEND_NORM_DATA). For efficiency, normal data sometimes contains multiple messages from the serial lines in a single message buffer. 3.5.
PAGE 84
BSC Programmer’s Guide 84 DC 900-1340I
PAGE 85
Chapter 4 Note BSC 3270 Link Configuration Options This chapter, along with Chapter 3 and Appendix A, should be read by programmers who are interfacing an application program to a BSC 3270 environment. If you are programming BSC 2780/3780, refer to Chapter 5, Chapter 6, and Appendix B. This chapter describes the various link configuration options that can be set using the DLI configuration file described in Section 7.2 on page 188.
PAGE 86
BSC Programmer’s Guide Table 4–1: BSC 3270 Link Configuration Options and Settings Option Data Rate (bits/second) Number Value 1 2 Setting 0 75 1 110 2 135 3 150 4 300 5 600 6 1200 7 2400 8 4800 9 Clock Source Default ( ) 9600 10 19200 11 38400 12 56000 0 1 External Internal Reply Timer Length 3 n 3 n = number of seconds (1 to 1800) Number of Leading Sync Characters 4 n 3 n = sync chars (2 to 8) Protocol 5 1 3270 Parity 6 0 1 None 2 Character
PAGE 87
4: BSC 3270 Link Configuration Options Table 4–1: BSC 3270 Link Configuration Options and Settings (Cont’d) Option Conversational Mode Number Value 13 0 Default ( ) 1 Setting Disable Enable Retry Limit 14 n 3 n = number of retries (1 to 127) Poll List Delay 15 n 0 n = delay at end of master poll list in tenths of seconds (0 to 8192) Modem Control 16 0 1 Safe Store 17 HDX-1 2 HDX-2 3 FDX-2 0 1 Station ID 18 n Message Blocking 19 0 1 Block Checking 20 Enable 0 2
PAGE 88
BSC Programmer’s Guide Table 4–1: BSC 3270 Link Configuration Options and Settings (Cont’d) Option 3270 Text Addressing Number Value 27 Default ( ) 0 1 Setting Disable Normal 2 Reserved 3 Automatic printer emulation 4 Device emulation DSR/DCD Delay 30 n 3 n = reporting delay in seconds (1 to 127) Electrical Interface (Freeway 1000 only) 40 0 EIA-232 1 EIA-485 2 EIA-530/EIA-449 (balanced, EIA-422) 3 V.35 4 EIA-449 (unbalanced, EIA-423) 5 EIA-562 4.
PAGE 89
4: BSC 3270 Link Configuration Options • 4–8 links at 19,200 b/s • 16 links for a 16-port ICP at 9600 b/s To set this option using the DLI configuration file, use the dataRate parameter; for example, dataRate = 9600. See Table 7–1 on page 190. 4.2 Clock Source Option (2) The clock source option determines the source of the data clock signals for a link. Data clocking can be provided by the BSC software or received from an external source.
PAGE 90
BSC Programmer’s Guide nal clocking using a hardware jumper. If you need to set internal clocking, call the Protogate customer support number given in the Preface. 4.3 Reply Timer Length Option (3) The reply time is the length of time in seconds that the BSC 3270 software waits for the remote station to reply to a transmission. The transmission may be a poll, select, or data block.
PAGE 91
4: BSC 3270 Link Configuration Options page 72) which can be used by client application programs to verify the protocol running on the ICP. The DLI configuration program (Chapter 7) considers this protocol option to be protocol-independent, but it must be set to “BSC3270” in order to select the BSC 3270 protocol.
PAGE 92
BSC Programmer’s Guide When the EBCDIC/CRC-16 setting is used, the BSC control sequences are transmitted in 8-bit EBCDIC, and the CRC-16 block check polynomial is used. The parity option is ignored when using EBCDIC/CRC-16. The BSC software transmits ASCII control characters on the line with space parity when you select no parity (Section 4.6). To set this option using the DLI configuration file, use the charSet parameter; for example, charSet = “asciilrc8”. See Table 7–1 on page 190. 4.
PAGE 93
4: BSC 3270 Link Configuration Options For messages received on the communication line, the ICP message buffer size (Section 3.4.1.3 on page 58) is the maximum size that can be received; otherwise, the DLI_ICP_ERR_BUF_OVERFLOW error code is sent to the client application. To set this option using the DLI configuration file, use the transBlkSize parameter; for example, transBlkSize = 512. See Table 7–1 on page 190. 4.
PAGE 94
BSC Programmer’s Guide to the poll and select sequences that match the CU number configured with the station ID (Section 4.16). To set this option using the DLI configuration file, use the stationPri parameter; for example, stationPri = “master”. See Table 7–1 on page 190. 4.11 Conversational Mode Option (13) Conversational mode allows a remote station to respond to an ETX block with a data block, instead of responding with an ACK and waiting for line turnaround.
PAGE 95
4: BSC 3270 Link Configuration Options In some situations the remote computer may send a WACK (wait acknowledge) sequence instead of the expected response (ACK0 or ACK1) to a transmitted data block. BSC transmits an ENQ in response to the received WACK. The WACK–ENQ sequences are not counted by BSC. Thus it is possible for the remote computer to prevent the DLI_ICP_ERR_RETRY_EXCEEDED error by sending WACK until it is ready to send the correct response.
PAGE 96
BSC Programmer’s Guide Table 4–2: Modem Control Option Settings Value Setting Description 0 HDX-1 Half duplex, monitor DSR 1 FDX-1 Full duplex, monitor DSR 2 HDX-2 Half duplex, ignore DSR and DCD 3 FDX-2 Full duplex, ignore DSR and DCD mission is complete. In full-duplex operation (FDX-1 or FDX-2), the RTS signal is turned on when the link is started and stays on until the link is stopped.
PAGE 97
4: BSC 3270 Link Configuration Options To set this option using the DLI configuration file, use the safeStore parameter; for example, safeStore = ”no”. See Table 7–1 on page 190. 4.16 Station ID Option (18) This option determines the control unit number of a tributary station. Control units range from 0 to 31. If the station ID is set to 32, the tributary station enters “test mode.” See Section A.2.2 on page 196. This option is not used by links configured as control stations.
PAGE 98
BSC Programmer’s Guide buffer to the client. For outbound data, each message buffer is transmitted on the line as a separate transmission block. If the ICP message buffer size is larger than the maximum transmission block size, BSC 3270 performs message deblocking until the entire message buffer is transmitted. 4.17.
PAGE 99
4: BSC 3270 Link Configuration Options then deblocks the message such that the 3270 command strings are not split across transmission block boundaries. 4.18 Block Checking Option (20) This option determines what characters are included in the block check character (BCC) calculation on transmitted and received data blocks. If the received block check character does not match the BCC value calculated by BSC, the DLI_ICP_ERR_BAD_BCC error code is returned to the client application.
PAGE 100
BSC Programmer’s Guide 4.19 Queue Limit Option (21) The queue limit option is used to prevent the ICP message buffer pool from being exhausted. Message buffers for all links on the ICP are taken from the same memory pool. This method allows each link to draw buffers as demand increases. However, if a process in the client were to stop reading on one link without disabling the link, incoming messages could deplete the buffer supply and the other links would not be able to obtain buffers.
PAGE 101
4: BSC 3270 Link Configuration Options 4.20 Read Session Option (23) The read session option determines what happens on the line when data is received on a link for which there is no Read session (Section 2.2 on page 35) currently attached. Under ordinary circumstances a link has a Manager session reading incoming data and transmitting outgoing data, or it has a Manager session sending data and a Read session receiving incoming data.
PAGE 102
BSC Programmer’s Guide 4.22 3270 Text Addressing Option (27) This BSC 3270 option determines whether IBM 3270 embedded addressing is performed on inbound and outbound messages.
PAGE 103
4: BSC 3270 Link Configuration Options with the “start print” bit set in the write control character (WCC), the link responds to the data block with WACK instead of ACK. It then queues up a “device end” sense/status message to send in response to the next general poll received from the master. See Section A.4.3 on page 200 for more information on 3270 command checking. See Section A.4.4 on page 204 for more information on sense/status messages.
PAGE 104
BSC Programmer’s Guide report. If the signal returns before the delay time expires, the timer is reset and no report is made. To set this option using the DLI configuration file, use the dsrDelay parameter; for example, dsrDelay = 3. See Table 7–1 on page 190. 4.24 Electrical Interface Option (40) The electrical interface option applies to the Freeway 1000 model only and allows the electrical interface for each link to be set.
PAGE 105
Chapter 5 Note Note BSC 2780/3780 DLI Functions In this chapter, the DLI functions apply to both a Freeway server or an embedded ICP using DLITE. For the embedded ICP, also refer to the user’s guide for your ICP and operating system (for example, the ICP2432 User’s Guide for Windows NT (DLITE Interface)). This chapter, along with Chapter 6 and Appendix B, should be read by programmers who are interfacing an application program to a BSC 2780/3780 environment.
PAGE 106
BSC Programmer’s Guide • Appendix D explains error handling and provides a summary table of BSC error codes. The Freeway Data Link Interface Reference Guide gives complete DLI error code descriptions. • The Freeway Data Link Interface Reference Guide provides a generic code example which can guide your application program development, along with the programs described in Appendix E of this manual. 5.
PAGE 107
5: BSC 2780/3780 DLI Functions binary configuration files. Refer to Chapter 7 of this document, as well as the Freeway Data Link Interface Reference Guide and the Freeway Transport Subsystem Interface Reference Guide. ICP link configuration can be performed using any of the following methods: • The dlOpen function can configure the ICP links during the DLI session establishment process using the default ICP link configuration values provided by the protocol software.
PAGE 108
BSC Programmer’s Guide Normal and Raw operations can be mixed. For example, the client application session can be configured for Normal operation (allowing DLI to handle link startup and configuration), but the read and write requests (Section 5.4 on page 115 and Section 5.5 on page 150) can use Raw operation by including the optional arguments structure containing the protocol-specific information (Section 5.3.1 on page 114).
PAGE 109
5: BSC 2780/3780 DLI Functions The asyncIO DLI configuration parameter specifies whether an application session uses blocking or non-blocking I/O. The alwaysQIO DLI configuration parameter further qualifies the operation of non-blocking I/O activity. Refer to the Freeway Data Link Interface Reference Guide for more information.
PAGE 110
BSC Programmer’s Guide 5.2 Example BSC 2780/3780 Call Sequences Table 5–1 shows the sequence of DLI function calls to send and receive data using blocking I/O. Table 5–2 is the non-blocking I/O example. The remainder of this chapter and the Freeway Data Link Interface Reference Guide give further information about each function call. Note The example call sequences assume that the cfgLink and enable DLI configuration parameters are both set to “yes” (the defaults).
PAGE 111
5: BSC 2780/3780 DLI Functions Caution When using non-blocking I/O, a dlRead request must always be queued to avoid loss of data or responses from the ICP (see Step 5 of Table 5–2). Table 5–2: DLI Call Sequence for BSC 2780/3780 (Non-blocking I/O) 1. Call dlInit to initialize the DLI operating environment. The first parameter is your DLI binary configuration file name. 2. Call dlOpen for each required session (link) to get a session ID. 3.
PAGE 112
BSC Programmer’s Guide 5.3 Overview of DLI Functions for BSC 2780/3780 This section summarizes the DLI functions used in writing a client application.
PAGE 113
5: BSC 2780/3780 DLI Functions Table 5–3: DLI Functions: Syntax and Parameters (Listed in Typical Call Order) DLI Function Parameter(s) Parameter Usage int dlInit (char *cfgFile, char *pUsrCb, int (*fUsrIOCH)(char *pUsrCb)); DLI binary configuration file name Optional I/O complete control block Optional IOCH and parameter int dlOpen1 (char *cSessionName, int (*fUsrIOCH) (char *pUsrCB, int iSessionID)); Session name in DLI config file Optional I/O completion handler Parameters for IOCH int dlPoll
PAGE 114
BSC Programmer’s Guide 5.3.1 DLI Optional Arguments Section 5.4 and Section 5.5 describe the dlWrite and dlRead functions for a BSC 2780/3780 application. Both functions can use the optional arguments parameter to provide the protocol-specific information required for Raw operation (Section 5.1.2). The “C” definition of the optional arguments structure is shown in Figure 5–1.
PAGE 115
5: BSC 2780/3780 DLI Functions 5.4 Overview of BSC 2780/3780 Requests using dlWrite For BSC 2780/3780 the dlWrite function supports three dlWrite categories: commands, information requests, and data transfer, which are discussed in detail in Section 5.4.1 through Section 5.4.3. Whether you use blocking or non-blocking I/O, each Raw dlWrite request must be followed by a dlRead request to receive the command confirma- tion, information requested, or acknowledgment of the data transfer. Section 5.
PAGE 116
BSC Programmer’s Guide DLI_ICP_ERR_INBUF_OVERFLOW Input buffer overflow DLI_ICP_ERR_OUTBUF_OVERFLOW Output buffer overflow Table 5–4: Categories for BSC 2780/3780 dlWrite Requests Category Commands to ICP Report Requests 116 DLI Request Code Usage DLI_PROT_CFG_LINK Configure link DLI_PROT_CLR_STATISTICS Clear statistics DLI_PROT_FLUSH_QUEUE Flush queue DLI_PROT_MODEM_CFG Configure modem DLI_PROT_SAFE_STORE_ACK Send safe store acknowledge DLI_PROT_SEND_BIND Start link DLI_PROT_SEND_DIS
PAGE 117
5: BSC 2780/3780 DLI Functions Table 5–4: Categories for BSC 2780/3780 dlWrite Requests (Cont’d) Category Data Transfer DLI Request Code Usage DLI_PROT_SEND_HDR_DATA Transmit header data DLI_PROT_SEND_HDR_DATA_EOM Transmit header data with EOM DLI_PROT_SEND_NORM_DATA Transmit normal data DLI_PROT_SEND_NORM_DATA_EOM Transmit normal data with EOM1 DLI_PROT_SEND_PRIOR_DATA Transmit priority data DLI_PROT_SEND_PRIOR_DATA_EOM Transmit priority data with EOM DLI_PROT_SEND_TRANS_DATA Transmit tra
PAGE 118
BSC Programmer’s Guide 5.4.1 Commands using Raw dlWrite Section 5.4.1.1 through Section 5.4.1.15 explain how to issue specific commands to the BSC 2780/3780 software using the dlWrite function. Call dlRead to receive the command confirmation response (the dlRead pOptArgs.usProtCommand field is set by the DLI). 5.4.1.1 Set Translation Table Command Use the dlWrite function with the DLI_PROT_SET_TRANS_TABLE pOptArgs.usProtCommand field set to to set translation table 1 or 2.
PAGE 119
5: BSC 2780/3780 DLI Functions An unsuccessful Clear Statistics command can return the following error code in the dlRead pOptArgs.iICPStatus field (see Appendix D for error handling): DLI_ICP_ERR_BAD_MODE The function request is not available for the requested access mode. 5.4.1.3 Set ICP Message Buffer Size Command The ICP message buffer size applies to all links on the ICP. The DLI sets the ICP message buffer size as part of the configuration process during the dlOpen command.
PAGE 120
BSC Programmer’s Guide DLI_ICP_ERR_BAD_PARMS The parameter value(s) used for the function call are illegal. DLI_ICP_ERR_LINK_ACTIVE The link is already started. 5.4.1.
PAGE 121
5: BSC 2780/3780 DLI Functions Each option number corresponds to a software-selectable option of the BSC 2780/3780 software. The configuration value is used to set that option. Table 6–1 on page 156 lists the available options and values for the BSC 2780/3780 protocol. Note The Configure Link command can be used at any time during link operation. However, changing some option values while a link is running may result in unusual errors.
PAGE 122
BSC Programmer’s Guide depending on the setting of the modem control option, Section 6.15 on page 168) from the remote end. The link is not considered started until this signal is received. If you are using non-blocking I/O, you must also make a dlPoll request to read the completion status of the command. An unsuccessful Start Link command can return one of the following error codes in the dlRead pOptArgs.
PAGE 123
5: BSC 2780/3780 DLI Functions vated. If you are using non-blocking I/O, you must also make a dlPoll request to read the completion status of the command. An unsuccessful Stop Link command can return one of the following error codes in the dlRead pOptArgs.iICPStatus field (see Appendix D for error handling): DLI_ICP_ERR_BAD_MODE The function request is not available for the requested access mode. DLI_ICP_ERR_BAD_PARMS The parameter value(s) used for the function call are illegal. 5.4.1.
PAGE 124
BSC Programmer’s Guide the remote station. This is in contrast to the Send EOT command which causes the BSC software to reject the message by sending an EOT sequence instead of ACK. In this case, the remote station either records the data transmission as unsuccessful or attempts to retransmit the entire message. If the client sends a Safe Store Acknowledge command while the line is still “active” (i.e.
PAGE 125
5: BSC 2780/3780 DLI Functions remote station (forward abort) before the client sends the message acceptance/rejection. DLI_ICP_ERR_XMIT_ABORTED The remote computer (or BSC) sent EOT. The message is discarded. 5.4.1.8 Send EOT Command Use the dlWrite function with the DLI_PROT_SEND_EOT pOptArgs.usProtCommand field set to to reject a received message when using the safe store option (Section 6.16 on page 170). The Send EOT is queued behind any preceding outgoing messages.
PAGE 126
BSC Programmer’s Guide If the BSC 2780/3780 software receives a DLE EOT from the line, the client receives a disconnect message with the dlRead pOptArgs.usProtCommand field set to DLI_PROT_SEND_DISC. If there were any outgoing queued messages, they are returned with the dlRead pOptArgs.usProtCommand field set to DLI_PROT_RESP_LOCAL_ACK, and the dlRead pOptArgs.iICPStatus field set to DLI_ICP_ERR_XMIT_ABORTED (transmission aborted by EOT) error code.
PAGE 127
5: BSC 2780/3780 DLI Functions response. The BSC 2780/3780 forwards the response to the client with the dlRead pOptArgs.usProtCommand field also set to DLI_PROT_SEND_SIGNON. The initiating client then verifies the other station’s ID and confirms to the BSC 2780/3780 software with another Signon command (with the iBufLen parameter set to zero) or a Send EOT command with the pOptArgs.usProtCommand field set to DLI_PROT_SEND_EOT.
PAGE 128
BSC Programmer’s Guide The Send Disconnect command is used to: • reject a signon bid • reject a signon response An unsuccessful Signon command can return one of the following error codes in the dlRead pOptArgs.iICPStatus field (see Appendix D for error handling): DLI_ICP_ERR_BAD_MODE The function request is not available for the requested access mode. DLI_ICP_ERR_LINK_INACTIVE The link is stopped. 5.4.1.11 BSC 2780/3780 Poll Line with No Data Command Use the dlWrite function with the pOptArgs.
PAGE 129
5: BSC 2780/3780 DLI Functions Table 5–5: BSC 2780/3780 Error Responses on Poll Failure Local Acknowledge pOptArgs.iICPStatus Field Error Code Meaning DLI_ICP_ERR_XMIT_ABORTED EOT abort The remote station sent EOT instead of ACK0 in response to the ENQ poll. DLI_ICP_ERR_RETRY_EXCEEDED Retry limit exceeded The remote station did not respond to the bid within the number of retries specified by the Retry Limit option.
PAGE 130
BSC Programmer’s Guide DLI_ICP_ERR_LINK_INACTIVE The link is stopped. 5.4.1.12 BSC 2780/3780 Flush Queue Command Use the dlWrite function with the pOptArgs.usProtCommand field set to DLI_PROT_FLUSH_QUEUE to send a BSC 2780/3780 Flush Queue command to clear out any data acknowledgments that might remain when a link is stopped and restarted. If a transmission is in progress, the Flush Queue command causes any outbound queued messages to be returned to the client with the dlRead pOptArgs.
PAGE 131
5: BSC 2780/3780 DLI Functions 5.4.1.13 BSC 2780/3780 Autodial Start Command Use the dlWrite function with the pOptArgs.usProtCommand field set to DLI_PROT_START_AUTODIAL to send a BSC 2780/3780 Autodial Start command. The buffer pointed to by the pBuf parameter contains a string of a variable number of 8-bit bytes (up to 256) containing the dial string. An autodial start acknowledge response with the dlRead pOptArgs.
PAGE 132
BSC Programmer’s Guide Table 5–6: Autodial Start Acknowledge Errors Returned Error Code in the dlRead pOptArgs.iICPStatus Field Description (Modem Response1) DLI_ICP_ERR_NO_ERR Successful connection (for example, L, CTS detected, or CONNECT) DLI_ICP_ERR_LINK_ACTIVE The link is already started.
PAGE 133
5: BSC 2780/3780 DLI Functions F No answer tone (DLI_ICP_ERR_NO_ANSWER) E No dial tone (DLI_ICP_ERR_NO_DIALTONE) C Invalid command or configuration (DLI_ICP_ERR_BAD_MODEM_RESP) V.25bis Support If the modem type option is set to V.25bis, the Autodial Start command causes the BSC 2780/3780 software to insert the character string “CRN” at the start of the autodial string. The BSC 2780/3780 software then sends the autodial string to the modem and waits up to 60 seconds for CTS to be detected.
PAGE 134
BSC Programmer’s Guide CONNECT On line NO CARRIER No carrier detected (DLI_ICP_ERR_DSR_DOWN) BUSY Line Busy (DLI_ICP_ERR_DEVICE_BUSY) NO ANSWER No answer (DLI_ICP_ERR_NO_ANSWER) NO DIALTONENo dial tone detected (DLI_ICP_ERR_NO_DIALTONE) ERROR Invalid command or configuration (DLI_ICP_ERR_BAD_MODEM_RESP) 5.4.1.14 BSC 2780/3780 Modem Configuration Command Use the dlWrite function with the DLI_PROT_MODEM_CFG pOptArgs.usProtCommand field set to to send a BSC 2780/3780 Modem Configuration command.
PAGE 135
5: BSC 2780/3780 DLI Functions SADL Modem Configuration If the modem type option is set to SADL, the BSC 2780/3780 software sends the configuration string pointed to by the dlWrite pBuf parameter to the SADL modem. For example, the configuration string might be ‘01111,’ with the iBufLen parameter set to 5. To busy-out a SADL modem, you must send a configuration string that enables the busyout option (refer to your particular SADL modem user’s guide for the specific busy-out string).
PAGE 136
BSC Programmer’s Guide 5.4.1.15 BSC 2780/3780 Trace using dlWrite The following trace commands allow a client application program to monitor line activity. Refer to the Freeway Data Link Interface Reference Guide for possible dlWrite error returns. Start Trace Use the dlWrite function with the DLI_PROT_START_LINK_TRACE pOptArgs.usProtCommand field set to to send a BSC 2780/3780 Start Trace command.
PAGE 137
5: BSC 2780/3780 DLI Functions is limited to the size of the ICP message buffer minus the first 8 bytes of statistics). Refer to Figure 5–3 for the format of the link trace data. Byte 1 Byte 0 0 time 2 event line mode data length 4 6 8 data Figure 5–3: BSC 2780/3780 Link Trace Data Format The time is reported in relative time in tenths of seconds. The clock starts at zero when the Start Trace command is received. The time is a longword (4 bytes).
PAGE 138
BSC Programmer’s Guide Table 5–7: Trace Event Numbers Event 138 BSC Control Sequence 1 DSR/DCD change 2 ENQ 3 ETB text block 4 ETX text block 5 ACK0 6 ACK1 7 ACK 8 NAK 9 TTD 10 WACK 11 RVI 12 EOT 13 DLE EOT 14 Signon ENQ sequence 15 Signon ACK0 sequence 16 Autodial 17 Modem configuration 18 Modem timer 19 CTS detected DC 900-1340I
PAGE 139
5: BSC 2780/3780 DLI Functions If a block of data is associated with the BSC control sequence, data length indicates the number of characters transmitted or received, including start character (STX), end character (ETB/ETX/ACK0/ENQ), and BCC. The data length is limited to the size of the ICP message buffer minus the first 8 bytes of statistics. The received or transmitted data is reported in ASCII.
PAGE 140
BSC Programmer’s Guide 5.4.2 Information Requests using Raw dlWrite Section 5.4.2.1 through Section 5.4.2.6 explain how to issue specific information requests to the BSC 2780/3780 software using the dlWrite function. You must then make a Raw dlRead request to receive the report information (the dlRead pOptArgs.usProtCommand field is set by the DLI to reflect the type of report, and the iBufLen parameter indicates the size of the message).
PAGE 141
5: BSC 2780/3780 DLI Functions 5.4.2.2 Request Configuration Report Use the dlWrite function with the DLI_PROT_GET_LINK_CFG pOptArgs.usProtCommand field set to to request the current configuration option settings for a link. The dlRead configuration report response (the pOptArgs.usProtCommand field is set to DLI_PROT_GET_LINK_CFG by the DLI) consists of a sequence of 16-bit word pairs containing the option number in the first word and the option setting in the second.
PAGE 142
BSC Programmer’s Guide 5.4.2.4 Request Status Report Use the dlWrite function with the DLI_PROT_GET_STATUS_REPORT pOptArgs.usProtCommand field set to to request the current link status. The status report returned by dlRead is a snapshot of the link’s hardware and software condition. The dlRead status report response (the pOptArgs.usProtCommand field is set to DLI_PROT_GET_STATUS_REPORT by the DLI) is a twelve-word report containing the current link status as shown in Table 5–10.
PAGE 143
5: BSC 2780/3780 DLI Functions Table 5–10: BSC 2780/3780 Status Report Definition Word Description 1 Link status 2 Current operation mode 3 DTR 4 DCD 5 RTS 6 CTS 7 Receiver 8 Transmitter 9 10 11 12 Last event Reserved Reserved DSR DC 900-1340I Value Setting 0 1 2 0 1 2 3 4 5 6 7 8 9 10 11 12 13 0 1 0 1 0 1 0 1 0 1 0 1 1–18 Off On Starting Idle DSR off Transmit Receive Safe Unsafe Bidding Dial transmit Dial receive V.25 autodial AT autodial SADL configuration V.
PAGE 144
BSC Programmer’s Guide dial receive awaiting the modem’s message or messages on the status of the autodial sequence V.25 autodial sending a V.25 autodial string or waiting for a response to a V.25 autodial string from the modem AT autodial sending an AT autodial string or waiting for a response to an AT autodial string from the modem SADL configuration sending a configuration string to a SADL modem V.25 configuration sending a configuration string to a V.
PAGE 145
5: BSC 2780/3780 DLI Functions Table 5–11: Last Event Codes for Link Status Report Code DC 900-1340I Meaning 1 Timer expired 2 DSR/DCD change 3 V.
PAGE 146
BSC Programmer’s Guide 5.4.2.6 Request Software Version ID Use the dlWrite function with the pOptArgs.usProtCommand field set to DLI_PROT_GET_SOFTWARE_VER to request the software version ID. The dlRead software ver- sion report response (the pOptArgs.usProtCommand field is set to DLI_PROT_GET_SOFTWARE_VER by the DLI) is a one-line report such as the following: @(#) Protogate BSC for Freeway 2000 – V03.0k 02-May-01 OS/Impact Version V1.7 5.4.
PAGE 147
5: BSC 2780/3780 DLI Functions If the DLI localAck configuration parameter is set to “yes” (which is the default), the data acknowledge response is implied by a successful dlWrite. An unsuccessful dlWrite data transfer request can return one of the following error codes in the dlRead pOptArgs.iICPStatus field (see Appendix D for error handling): DLI_ICP_ERR_LINK_INACTIVE The link is stopped. DLI_ICP_ERR_BAD_MODE The function request is not available for the requested access mode.
PAGE 148
BSC Programmer’s Guide DLI_PROT_SEND_TRANS_DATA_EOM to send transparent data. The client can send transpar- ent data in either ASCII or EBCDIC mode. In either mode, the data is not code-converted. The blocks are preceded by DLE STX and terminated with either DLE ETB or DLE ETX. The DLE characters are not counted in the block size. The BSC 2780/3780 software performs all the required DLE insertion and deletion for transparent data streams. Refer back to Section 2.
PAGE 149
5: BSC 2780/3780 DLI Functions The BSC 2780/3780 software transmits the data in the modified format of Figure 5–5: SYN SYN DLE STX record 1 DLE US CRC SYN SYN DLE STX DLE US CRC … SYN SYN DLE STX record n record 2 DLE ETB CRC Figure 5–5: BSC 2780/3780 Modified Transparent 2780 Record Format The DLE characters are not counted in the transmission block size.
PAGE 150
BSC Programmer’s Guide 5.5 Overview of BSC 2780/3780 Responses using Raw dlRead Table 5–12 shows the valid BSC 2780/3780 codes sent to your application in response to a Raw dlRead request; the returned dlRead pOptArgs.usProtCommand field indicates the response code. If the dlRead return value is zero or positive, it indicates the number of bytes read; if it is less than zero, an error has occurred. BSC error codes that can be associated with the responses are returned in the pOptArgs.
PAGE 151
5: BSC 2780/3780 DLI Functions Table 5–12: BSC 2780/3780 Response Codes Category Received Data DLI Response Code in pOptArgs.usProtCommand Field Usage Reference Section DLI_PROT_SEND_NORM_DATA Normal received data Section 5.5.1 DLI_PROT_SEND_NORM_DATA_EOM Normal received data (end of message) Section 5.5.1 DLI_PROT_SEND_TRANS_DATA Transparent received data Section 5.5.1 DLI_PROT_SEND_TRANS_DATA_EOM Transparent received data (end of message) Section 5.5.
PAGE 152
BSC Programmer’s Guide Table 5–12: BSC 2780/3780 Response Codes (Cont’d) Category Command Confirmations Reports 1 DLI Response Code in pOptArgs.usProtCommand Field Reference Section Usage DLI_PROT_SET_TRANS_TABLE Set Translation Table confirmation. Section 5.4.1.1 DLI_PROT_CLR_STATISTICS Clear Statistics confirmation. Section 5.4.1.2 DLI_PROT_SET_BUF_SIZE Set ICP Message Buffer Size confirma- Section 5.4.1.3 tion. DLI_PROT_CFG_LINK Configure Link confirmation. Section 5.4.1.
PAGE 153
5: BSC 2780/3780 DLI Functions 5.5.
PAGE 154
BSC Programmer’s Guide Caution With larger transparent 2780 records (such that only one record fits into a transmission block), the BSC 2780/3780 software receives the block as: DLE STX record DLE ETB BCC This is exactly the same format as a 3780 transparent data block, and is therefore sent to the client as transparent data (dlRead pOptArgs.usProtCommand field set to DLI_PROT_SEND_TRANS_DATA).
PAGE 155
Chapter 6 Note BSC 2780/3780 Link Configuration Options This chapter, along with Chapter 5 and Appendix B, should be read by programmers who are interfacing an application program to a BSC 2780/3780 environment. If you are programming BSC 3270, refer to Chapter 3, Chapter 4, and Appendix A. This chapter describes the various link configuration options that can be set using the DLI configuration file described in Section 7.2 on page 188.
PAGE 156
BSC Programmer’s Guide Table 6–1: BSC 2780/3780 Link Configuration Options and Settings Option Data Rate (bits/second) Number Value 1 0 1 2 3 4 5 6 7 8 9 10 11 12 13 0 1 n n Clock Source 2 Reply Timer Length Number of Leading Sync Characters Protocol Parity 3 4 Character Set Transmission Block Size Data Translation a a 156 5 6 7 8 10 0 0 1 2 0 1 2 3 4 5 n 0 1 2 Default ( ) 3 3 512 Setting 75 110 135 150 300 600 1200 2400 4800 9600 19200 38400 56000 64000 External Internal
PAGE 157
6: BSC 2780/3780 Link Configuration Options Table 6–1: BSC 2780/3780 Link Configuration Options and Settings (Cont’d) Option Station Priority a Number Value 11 0 1 0 1 0 1 n n Space Compression a 12 Conversational Mode a 13 Retry Limit Wait for Bid Delay 14 15 Modem Control 16 Safe Store a 17 Message Blocking a 19 Block Checking a 20 Queue Limit a 21 EOM Line Control a 22 Read Sessiona 23 Alternating Ack a 24 a 0 1 2 3 4 5 6 7 0 1 0 1 0 1 2 0 n 0 1 2 3 0 1 0 1 Default ( )
PAGE 158
BSC Programmer’s Guide Table 6–1: BSC 2780/3780 Link Configuration Options and Settings (Cont’d) Number Value Default ( ) Line Turnaround Delay 25 n 0 TTD/WACK a 26 0 1 2 3 0 1 n 0 n 0 n 0 1 2 3 0 1 2 3 4 5 0 1 Option RVI Handling a 28 DSR/DCD Delay a TTD/WACK Limit a 30 31 Disconnect Timer Length 32 Modem Type 35 Electrical Interface (Freeway 1000 only) 40 Line Type 41 a 158 3 Setting n = delay after receiving EOT in tenths of seconds (1 to 8192) Disable Normal
PAGE 159
6: BSC 2780/3780 Link Configuration Options 6.1 Data Rate Option (1) The data rate can be set by the client for installations where the communications server must generate the data clocking signal. If external clocking is provided by a modem or modem eliminator, the configuration of the data rate is not required.
PAGE 160
BSC Programmer’s Guide 6.2.1 External Protogate recommends the external clock setting for most communications applications that involve a cable length greater than 25 feet. In the external setting, the clock generator is disabled. Data clocking must be supplied by an external source such as a modem or modem eliminator. Receive clocking is input through the receiver timing signal (EIA-232 pin 17), and transmit clocking is input through the transmitter timing signal (EIA-232 pin 15).
PAGE 161
6: BSC 2780/3780 Link Configuration Options 6.4 Number of Leading SYN Characters Option (4) This option specifies the number of SYN characters to precede all transmitted data blocks. Certain links may require more SYN characters to ensure synchronization on poor-quality lines. The minimum number of leading SYN characters is two; the maximum number is eight. To set this option using the DLI configuration file, use the numLeadSync parameter; for example, numLeadSync = 3. See Table 7–2 on page 191. 6.
PAGE 162
BSC Programmer’s Guide EBCDIC/CRC-16 character set is used. The parity used for ASCII transmission is normally odd. To set this option using the DLI configuration file, use the parity parameter; for example, parity = “odd”. See Table 7–2 on page 191. 6.7 Character Set Option (7) This option determines the character code for the BSC control sequences used on the transmission line. It also determines what type of block checking is done on data blocks.
PAGE 163
6: BSC 2780/3780 Link Configuration Options 6.7.1 ASCII/LRC-8 When this setting is used, the BSC control sequences are transmitted in 7-bit ASCII format, and LRC-8 block checking is performed. 6.7.2 EBCDIC/CRC-16 When this setting is used, the BSC control sequences are transmitted in 8-bit EBCDIC, and the CRC-16 block check polynomial is used. The parity option is ignored when using EBCDIC/CRC-16. 6.7.
PAGE 164
BSC Programmer’s Guide 0 none No data parity, no control character parity 1 odd No data parity, odd control character parity 2 even No data parity, even control character parity 6.8 Transmission Block Size Option (8) The BSC software has transmission buffers fixed at 4,096 bytes. Each link has one transmit buffer and one receive buffer.
PAGE 165
6: BSC 2780/3780 Link Configuration Options 6.9 Data Translation Option (10) This option invokes transmit and receive data translation using one of the two onboard ASCII/EBCDIC translation tables described in Appendix C, either of which can be changed by issuing a Set Translation Table command (Section 5.4.1.1 on page 118). This option is enabled only when the character set option (Section 6.7) is set to EBCDIC.
PAGE 166
BSC Programmer’s Guide To set this option using the DLI configuration file, use the dataTranslation parameter; for example, dataTranslation = “table1”. See Table 7–2 on page 191. 6.10 Station Priority Option (11) This option enables the link to operate as a slave or as a master station. The purpose of this option is to resolve any contention when both stations bid for the line at the same time.
PAGE 167
6: BSC 2780/3780 Link Configuration Options 6.12 Conversational Mode Option (13) Conversational mode allows a remote station to respond to an ETX block with a data block, instead of responding with an ACK and waiting for line turnaround. If this option is set to enable, conversational data responses are sent (when possible) on the line.
PAGE 168
BSC Programmer’s Guide To set this option using the DLI configuration file, use the retryLimit parameter; for example, retryLimit = 3. See Table 7–2 on page 191. 6.14 Wait for Bid Delay Option (15) This option controls the delay that occurs after BSC sends a message on a link which is followed by a normal line turnaround (EOT). The delay is intended to give the remote computer a chance to bid for the line if it has something to send, especially if the BSC software has several messages queued to send.
PAGE 169
6: BSC 2780/3780 Link Configuration Options Table 6–3: Modem Control Option Settings Value Setting Description 0 HDX-1 Half duplex, monitor DSR 1 FDX-1 Full duplex, monitor DSR 2 HDX-2 Half duplex, ignore DSR and DCD 3 FDX-2 Full duplex, ignore DSR and DCD 4 HDX-3 Half duplex, monitor DCD 5 FDX-3 Full duplex, monitor DCD 6 HDX-4 Half duplex, monitor DSR and DCD 7 FDX-4 Full duplex, monitor DSR and DCD 6.15.
PAGE 170
BSC Programmer’s Guide 6.15.3 DCD Signal The modem control option allows a link to use the data carrier detect (DCD) signal as DSR. With either the HDX-3 or FDX-3 setting, line activity ceases when the signal on the DCD pin is lost. With either the HDX-2 or FDX-2 setting, incoming DCD signals are ignored by the BSC software. With either the HDX-4 or FDX-4 setting, line activity ceases when the signal on either the DSR or DCD pin is lost. 6.
PAGE 171
6: BSC 2780/3780 Link Configuration Options Note When transparent data is received, blocking acts as if message blocking is set to disable.
PAGE 172
BSC Programmer’s Guide Freeway Communications Line Receive buffer ETX 100 STX ETB 100 STX ETB 2 3 100 STX 4096 Client Message buffers 1024 EOM Block 2nd Block 1st Block 100 100 100 3 2 1 1 DRWG-2442 Message Blocking = disabled Figure 6–3: Receive with Disabled Message Blocking Option Freeway Receive buffer ETX 100 STX 3 ETB 100 STX ETB 100 STX 2 1 4096 Client Message buffers EOM block 300 1024 Message Blocking = data blocking DRWG-2443 Communications Line Figure 6
PAGE 173
6: BSC 2780/3780 Link Configuration Options 6.17.1 Blocking Disabled If the message blocking option is set to disable, blocking/deblocking is not performed. For inbound data, each received transmission block is treated as a separate message buffer to the client. For outbound data, each message buffer is transmitted on the line as a separate transmission block.
PAGE 174
BSC Programmer’s Guide 6.17.3 BSC 2780/3780 Record Handling When message blocking is set to data blocking, the BSC 2780/3780 software performs 2780 and 3780 record handling if appropriate. The software scans the first block of all messages for 3780 record separator (RS) or 2780 unit separator (US) characters. The BSC 2780/3780 software performs 2780 or 3780 message blocking depending on which type of character it encounters first.
PAGE 175
6: BSC 2780/3780 Link Configuration Options 6.18 Block Checking Option (20) This option determines what characters are included in the block check character (BCC) calculation on transmitted and received data blocks. If the received block check character does not match the BCC value calculated by BSC, the DLI_ICP_ERR_BAD_BCC error code is returned to the client application. Block checking can be set to include or exclude the leading BSC control character or can be disabled completely.
PAGE 176
BSC Programmer’s Guide ing messages could deplete the buffer supply and the other links would not be able to obtain buffers. To prevent this from occurring, a queue limit can be placed on the BSC-to-client message queue for a particular link. When the queue limit is reached, the last buffer on the queue is marked with the DLI_ICP_ERR_QFULL error code, and all subsequent blocks from the link are discarded until the client program begins reading messages from the queue.
PAGE 177
6: BSC 2780/3780 Link Configuration Options If this option is set to reverse, the BSC 2780/3780 software automatically turns the line around by sending EOT after it transmits the last block of each message. If this option is set to hold, the BSC 2780/3780 software holds the line and continues sending messages as long as the software has more messages queued for transmission. The BSC 2780/3780 software turns the line around by sending EOT as soon as it sends the ETX block of the last queued message.
PAGE 178
BSC Programmer’s Guide option is set to disable (the default setting), incoming data blocks are routed to the Manager session for that link. If the option is set to enable, and the Read session for a given link is non-existent, incoming data blocks are NAK’d, and any buffers currently queued for the Read session are dequeued and discarded. When a Read session is resumed on that link, incoming data is sent to the Read session as is done normally.
PAGE 179
6: BSC 2780/3780 Link Configuration Options If this option is set to normal (TTD and WACK), and safe store acknowledge is set to enable (Section 6.16 and Section 5.4.1.7 on page 123), the BSC 2780/3780 software transmits a WACK instead of an ACK until the client responds with a safe store acknowledge. The BSC 2780/3780 software transmits a TTD after it transmits an ETB block and has no more client data to send. If this option is set to disable, the BSC 2780/3780 software does not transmit TTDs or WACKs.
PAGE 180
BSC Programmer’s Guide When an RVI is received during transmission of a message, the BSC 2780/3780 software indicates the successful transmission of a data block by setting the dlRead pOptArgs.usProtCommand field to DLI_PROT_RESP_LOCAL_ACK, and the dlRead pOptArgs.iICPStatus field to DLI_ICP_ERR_RVI_GOOD_RECV in the following two cases: 1. a data block is acknowledged by an RVI (when the continue option is selected) 2.
PAGE 181
6: BSC 2780/3780 Link Configuration Options report. If the signal returns before the delay time expires, the timer is reset and no report is made. To set this option using the DLI configuration file, use the dsrDelay parameter; for example, dsrDelay = 3. See Table 7–2 on page 191. 6.27 TTD/WACK Limit Option (31) This option limits the number of consecutive TTDs and WACKs that can be received by the ICP.
PAGE 182
BSC Programmer’s Guide To set this option using the DLI configuration file, use the discTimerLen parameter; for example, discTimerLen = 0. See Table 7–2 on page 191. 6.29 Modem Type Option (35) This option defines how the BSC 2780/3780 software handles the autodial start and modem configuration commands (Section 5.4.1.13 on page 131 and Section 5.4.1.14 on page 134, respectively). Choose one of four settings: disable, SADL, AT, or V.25bis.
PAGE 183
Chapter 7 Note BSC Link Configuration Using dlicfg The term “Freeway” can mean either a Freeway server or an embedded ICP. For the embedded ICP, also refer to the user’s guide for your ICP and operating system (for example, the ICP2432 User’s Guide for Windows NT (DLITE Interface)). 7.1 Configuration Overview Section 3.1.1 on page 46 (BSC 3270) and Section 5.1.1 on page 106 (BSC 2780/3780) summarized your choices for performing ICP link configuration.
PAGE 184
BSC Programmer’s Guide The DLI and TSI configuration process is a part of the loopback testing procedure described in Appendix E and the installation procedure described in the Freeway Server User’s Guide. During your client application development and testing, you might need to perform DLI and TSI configuration repeatedly. The DLI and TSI configuration procedures are summarized as follows (examples are for BSC 3270): 1.
PAGE 185
7: BSC Link Configuration Using dlicfg filename). If the optional filename is not supplied, the binary file is given the same name as your TSI text configuration file plus a .bin extension. tsicfg TSI-text-configuration-filename [TSI-binary-configuration-filename] VMS example: tsicfg bsc3270altcfg UNIX example: freeway/client/op-sys/bin/tsicfg bsc3270altcfg NT example: freeway\client\op-sys\bin\tsicfg bsc3270altcfg 5.
PAGE 186
BSC Programmer’s Guide UNIX example: mv bsc3270aldcfg.bin /usr/local/freeway/client/hpux/bin mv bsc3270altcfg.bin /usr/local/freeway/client/hpux/bin 7. If you have a VMS system, run the move.com command file from the [FREEWAY.CLIENT.TEST.BSC3270] directory. This moves the DLI and TSI binary configuration files you created in Step 4 and Step 5 into the bin directory for your particular TCP/IP package.
PAGE 187
7: BSC Link Configuration Using dlicfg Application dlicfg DLI DLI Text Configuration File DLI Configuration Preprocessor DLI Binary Configuration File TSI 2836 tsicfg TSI Text Configuration File TSI Configuration Preprocessor TSI Binary Configuration File Transport Environment Figure 7–1: DLI and TSI Configuration Process DC 900-1340I 187
PAGE 188
BSC Programmer’s Guide 7.2 DLI Session Configuration The DLI text configuration file used by the dlicfg program consists of the following sections: • A “main” section which specifies the DLI configuration for non-session-specific operations (described in the Freeway Data Link Interface Reference Guide) • One or more additional sections, each specifying a protocol-specific session associated with a particular Freeway serial communication link (port).
PAGE 189
7: BSC Link Configuration Using dlicfg main { asyncIO = “no”; tsiCfgName = “bsc3270altcfg.
PAGE 190
BSC Programmer’s Guide Table 7–1: BSC 3270 ICP Link Parameters and Defaults for Using dlicfg dlicfg Option Name Default Valid Values dataRate 9600 75, 110, 135, 150, 300, 600, 1200, 2400, 4800, 9600, 19200, 38400 or 56000 clockSource “external” “external” or “internal” replyTimerLen 3 1–1800 numLeadSync 3 2–8 protocol “BSC3270” “BSC3270” parity “odd” “none”, “odd” or “even” charSet “asciilrc8” “asciilrc8” or “ebcdiccrc16” transBlkSize 512 64–4096 dataTranslation “table1” “disab
PAGE 191
7: BSC Link Configuration Using dlicfg Table 7–2: BSC 2780/3780 ICP Link Parameters and Defaults for Using dlicfg dlicfg Option Name Default Valid Values dataRate 9600 75, 110, 135, 150, 300, 600, 1200, 2400, 4800, 9600, 19200, 38400, 56000 or 64000 clockSource “external” “external” or “internal” replyTimerLen 3 1–1800 numLeadSync 3 2–8 protocol “BSC3780” “BSC3780” parity “odd” “none”, “odd” or “even” charSet “ebcdiccrc16” “asciilrc8”, “ebcdiccrc16”, “asciicrc16”, “ebcdicccitt0” or “
PAGE 192
BSC Programmer’s Guide Table 7–2: BSC 2780/3780 ICP Link Parameters and Defaults for Using dlicfg (Cont’d) dlicfg Option Name Default Valid Values dsrDelay 3 1–127 ttdLimit 0 0–8192 discTimerLen 0 0–1800 modemType “SADL” “none”, “SADL”, “V25bis” or “AT” elecInterface “EIA232” “EIA232”, “EIA485”, “EIA530”, “V35”, “unbEIA449” or “EIA562” lineType “leased” “leased” or “dialUp” 1024 256–8192 “normal” “normal” or “transparent” msgBlkSize 1 writeType2 1 The msgBlkSize parameter allows
PAGE 193
Appendix A BSC 3270 Line Control Procedures This appendix defines line control procedures for the BSC 3270 protocol. Note This appendix, along with Chapter 3 and Chapter 4, should be read by programmers who are interfacing an application program to a BSC 3270 environment. If you are programming BSC 2780/3780, refer to Chapter 5, Chapter 6 and Appendix B. A.
PAGE 194
BSC Programmer’s Guide SYN SYN EOT PAD SYN SYN CUA CUA GPA GPA ENQ PAD Figure A–1: General Poll Format to control units in the order specified in the poll list given to the ICP in the Set Poll List command (Section 3.4.1.7 on page 62). Each control unit in the poll list is polled for input until the end of the list is reached. The BSC 3270 software then delays for the period specified by the poll list delay option (Section 4.13 on page 95).
PAGE 195
A: BSC 3270 Line Control Procedures SYN SYN EOT PAD SYN SYN CUA CUA DA DA ENQ PAD Figure A–2: Device Selection Sequence In order to give equal priority to input and output, at least one general poll is issued after each device selection sequence. A.1.3 Specific Poll The client application program may send a specific poll on the line by issuing a Specific Poll command (Section 3.4.1.9 on page 66) at any time while the link is active.
PAGE 196
BSC Programmer’s Guide A.2.1 Normal Mode A tributary link operates in normal mode when it acts as only one control unit. Normal mode is in effect when the station ID option is set to a CU number from 0 to 31. When the link is started, the BSC 3270 responds to only those poll and select sequences that contain the configured control number. All other sequences are received but ignored. A.2.2 Test Mode If the station ID option is set to 32, the tributary link enters “test mode.
PAGE 197
A: BSC 3270 Line Control Procedures A.4 Virtual Device Procedures The following sections describe some of the line procedures involving virtual devices. See Section 3.4.1.11 on page 67 to create virtual devices, Section 3.4.1.12 on page 69 to change the status of virtual devices, and Section 3.4.2.8 on page 76 to request a virtual device status report. A review of these sections would be helpful before reading the following sections. A.4.
PAGE 198
BSC Programmer’s Guide Client Freeway Communication Line select 3270 WRITE command byte with start print bit DLI_PROT_SEND_NORM_DATA_EOM dlRead pOptArgs.iICPStatus = DLI_ICP_ERR_DEVICE_BUSY general poll select DLI_PROT_CHANGE_STATUS dlWrite pOptArgs.
PAGE 199
A: BSC 3270 Line Control Procedures Client Freeway Communication Line select 3270 WRITE command byte with start print bit DLI_PROT_SEND_NORM_DATA_EOM dlRead pOptArgs.iICPStatus = DLI_ICP_ERR_DEVICE_BUSY DLI_PROT_CHANGE_STATUS dlWrite pOptArgs.iProtModifier = DLI_ICP_ERR_DEVICE_UNAVAIL (printer out of paper) general poll status message (IR, DE) DLI_PROT_CHANGE_STATUS dlWrite pOptArgs.
PAGE 200
BSC Programmer’s Guide Client Freeway Communication Line select 3270 WRITE command byte with start print bit DLI_PROT_SEND_NORM_DATA_EOM dlRead pOptArgs.iICPStatus = 0 Figure A–5: Normal Operation of Virtual Display A.4.3 3270 Command Checking A tributary link scans the incoming data stream for the presence of valid 3270 commands for devices configured either as displays or printers.
PAGE 201
A: BSC 3270 Line Control Procedures Client Freeway Communication Line select illegal 3270 command specific poll status message (CR) select 3270 command without leading char specific poll status message (OC) Figure A–6: BSC 3270 Command Checking DC 900-1340I 201
PAGE 202
BSC Programmer’s Guide Client Freeway Communication Line DLI_PROT_CHANGE_STATUS dlWrite pOptArgs.
PAGE 203
A: BSC 3270 Line Control Procedures Client Freeway Communication Line DLI_PROT_CHANGE_STATUS dlWrite pOptArgs.
PAGE 204
BSC Programmer’s Guide A.4.4 BSC 3270 Sense/Status Message Status and sense conditions are recorded by the BSC 3274 control unit for each attached device. These conditions include busy or ready status or detected errors. All remote status and sense conditions are combined into two bytes (per device), which are always sent in a status message from the 3274. In EBCDIC code, the sense/status bytes are sent as printable EBCDIC characters.
PAGE 205
A: BSC 3270 Line Control Procedures combinations of status and sense bits, only a portion of this total is normally used. These combinations are listed in Figure 4–9 of the 3274 Control Unit Description and Programmer’s Guide, IBM. A tributary link of the ICP can maintain any of the combinations of sense and status bits shown in Table A–1. Table A–1: Sense/Status Bit Combinations Sense/Status Bits Description CR An invalid or illegal 3270 command is received.
PAGE 206
BSC Programmer’s Guide A.5 Station Up/Down Reporting Station up/down reporting is based on line activity (as opposed to DSR/DCD up/down reporting, Section A.6, which is based on modem signals). When a link is started, all stations are assumed down. As stations become active, the BSC 3270 software notifies the client with the DLI_PROT_RESP_ERROR error report containing the DLI_ICP_ERR_STATION_UP information code.
PAGE 207
A: BSC 3270 Line Control Procedures When the DSR/DCD signal returns, BSC sends the client the DLI_PROT_RESP_ERROR error report containing the DLI_ICP_ERR_DSR_UP information code, and normal line operation resumes. DSR/DCD up/down reporting is disabled when the modem control option is set to HDX-2 or FDX-2. A.7 Freeway/Line Interface Freeway communicates to remote devices through serial connectors. The ports can be connected to standard modem cables. A.
PAGE 208
BSC Programmer’s Guide A.9 Clock Signals The BSC communication interface is designed to use either externally or internally generated clock signals. Clocking is selected through the clock source option (Section 4.2 on page 89). The BSC software always uses receive clocking provided by the receive data source. Under external clocking, BSC receives its transmit clocks from the remote computer. Under internal clocking, the transmit clock is internally generated and also output to the remote computer.
PAGE 209
Appendix B BSC 2780/3780 Control Procedures This appendix defines the control procedures for the BSC 2780/3780 protocol. Note This appendix, along with Chapter 5 and Chapter 6, should be read by programmers who are interfacing an application program to a BSC 2780/3780 environment. If you are programming BSC 3270, refer to Chapter 3, Chapter 4 and Appendix A. B.
PAGE 210
BSC Programmer’s Guide B.1.1 BSC 2780/3780 Software Initialization After downloading the software to the ICP, issue a dlOpen request. If the cfgLink and enable DLI configuration parameters are set to “no,” an optional Set ICP Message Buffer Size command (Section 5.4.1.3 on page 119) can be issued. If you do not issue the message buffer command, the size defaults to 1024 bytes.
PAGE 211
B: BSC 2780/3780 Control Procedures B.1.2 Normal Link Start To start link operation, the client issues a Link Configuration command (Section 5.4.1.4 on page 120) followed by Start Link command (Section 5.4.1.5 on page 121) to enable the link. If the client does not issue the link configuration command, the configuration set by the previous link configuration command (or the default configuration) takes effect when the link begins operation.
PAGE 212
BSC Programmer’s Guide B.1.3 Signon Procedure using BSC 2780/3780 Software Commands The BSC 2780/3780 software provides an optional initial signon procedure to allow the local and remote clients to exchange and validate station IDs after the links are enabled but before transferring data. Figure B–3 and Figure B–4 illustrate the difference in the signon sequence due to a change in the timing of the first data block from the client.
PAGE 213
B: BSC 2780/3780 Control Procedures Client Signon command = “LOCAL” dlWrite (DLI_PROT_SEND_SIGNON) Freeway Remote Station LOCAL REMOTE Signon response = “REMOTE” dlRead (DLI_PROT_SEND_SIGNON) Signon command (no data) dlWrite (DLI_PROT_SEND_SIGNON) Signon response (no data) dlRead (DLI_PROT_SEND_SIGNON) Less than 2 seconds . . .
PAGE 214
BSC Programmer’s Guide Client Signon command = “LOCAL” dlWrite (DLI_PROT_SEND_SIGNON) Freeway Remote Station LOCAL REMOTE Signon response = “REMOTE” dlRead (DLI_PROT_SEND_SIGNON) Signon command (no data) dlWrite (DLI_PROT_SEND_SIGNON) Signon response (no data) dlRead (DLI_PROT_SEND_SIGNON) More than 2 seconds . . .
PAGE 215
B: BSC 2780/3780 Control Procedures Client Freeway Remote Station REMOTE Signon response = “REMOTE” dlRead (DLI_PROT_SEND_SIGNON) Signon command = “LOCAL” dlWrite (DLI_PROT_SEND_SIGNON) LOCAL HELLO Data block = “HELLO” dlRead (DLI_PROT_SEND_NORM_DATA_EOM) Signon response (no data) dlRead (DLI_PROT_SEND_SIGNON) Figure B–5: Signon Procedure (Receive) DC 900-1340I 215
PAGE 216
BSC Programmer’s Guide B.1.4 Data Reception The BSC 2780/3780 software can receive data at any time after the link is started. The client application program should have a dlRead request issued at all times so the received data can be transferred to the client. Figure B–6 is an example of how the BSC 2780/3780 software receives a typical data message.
PAGE 217
B: BSC 2780/3780 Control Procedures B.1.5 Normal Data Transmission In Figure B–7, the client program sends a two-block message to the BSC 2780/3780 software to be transmitted on the line. The BSC 2780/3780 software segments the data into transmission blocks, sends the ETB/ETX blocks, sends the two acknowledgments to the client program, then turns the line around. Note The STX and ETX control characters are included in the transmission block size.
PAGE 218
BSC Programmer’s Guide B.1.6 Priority Data Reception Assuming the BSC 2780/3780 software has the RVI handling option (Section 6.25 on page 179) configured for continue, if the BSC 2780/3780 software receives a reverse interrupt during transmission, the message transmission finishes normally, and an RVI received code is returned in the error field of the data acknowledgment. The BSC 2780/3780 software then sends EOT to reverse the line and prepares to receive the priority data message.
PAGE 219
B: BSC 2780/3780 Control Procedures Client Freeway Remote Station Message A dlWrite (DLI_PROT_SEND_NORM_DATA_EOM) ENQ ACK0 Message B Block A1 (ETB) dlWrite (DLI_PROT_SEND_NORM_DATA_EOM) ACK1 Block A2 (ETB) RVI Block A3 (ETX) * Data Acknowledge A dlRead (DLI_PROT_RESP_LOCAL_ACK) pOptArgs.
PAGE 220
BSC Programmer’s Guide B.1.7 Recoverable Errors In Transmission Figure B–9 shows how the BSC 2780/3780 software handles recoverable line errors. Client Normal data Freeway dlWrite (DLI_PROT_SEND_NORM_DATA_EOM) Remote Station ENQ ACK0 Block 1 (ETB) (BCC error) NAK Block 1 (ETB) ACK1 Block 2 (ETB) (BCC error) NAK Block 2 (ETB) ACK0 Block 3 (ETX) Timeout ENQ . . .
PAGE 221
B: BSC 2780/3780 Control Procedures B.1.8 Unrecoverable Errors In Transmission When an unrecoverable transmission error occurs, the BSC 2780/3780 software discards all messages in the transmit queue. A data acknowledgment containing the appropriate error code in the dlRead pOptArgs.iICPStatus field is returned for each discarded message. Figure B–10 and Figure B–11 show examples of unrecoverable error handling.
PAGE 222
BSC Programmer’s Guide Client Normal data dlWrite (DLI_PROT_SEND_NORM_DATA_EOM) Freeway Remote Station ENQ ACK0 Block 1 (ETB) Block 2 (ETB) ACK1 EOT Data Acknowledge dlRead pOptArgs.
PAGE 223
B: BSC 2780/3780 Control Procedures B.1.9 Normal Link Stop The client can stop a link at any time by issuing a Stop Link command (Section 5.4.1.6 on page 122), which disables the transmitter and the receiver and returns any data buffers in use to the client. A call to dlClose (described in the Freeway Data Link Interface Reference Guide) also stops the link, but terminates the session as well. This is the normal method to terminate a session at the end of a client application.
PAGE 224
BSC Programmer’s Guide B.2 DSR/DCD Up/Down Reporting If the data set ready (DSR) or the data carrier detect (DCD) modem signal (depending on the setting of the modem control option, Section 6.15 on page 168) is lost while a link is active, BSC 2780/3780 suspends line operations for that link and notifies the client with the DLI_PROT_RESP_ERROR error report containing the DLI_ICP_ERR_DSR_DOWN error code.
PAGE 225
B: BSC 2780/3780 Control Procedures Table B–1: EIA-232 Modem Control Lines Signal Pin Direction Description RTS 4 Output For half-duplex, RTS is turned on just before transmission is started and turned off when transmission is complete. CTS 5 Input CTS is checked after RTS is turned on but prior to transmit. If CTS is on at this point, transmit is started and further changes in the CTS pin are ignored until the next block is ready to be transmitted.
PAGE 226
BSC Programmer’s Guide Table B–2: EIA-232 Clock Signals Signal 226 Pin Direction Description XMT CLK 15 Input External clocking: transmit clock Internal clocking: not used RCV CLK 17 Input External clocking: receive clock Internal clocking: receive clock EXT CLK 24 Output External clocking: not used Internal clocking: server-generated Clock signal to be connected to the XMT CLK of the local interface and the RCV CLK pin of the remote interface.
PAGE 227
Appendix C ASCII Translation Tables The BSC software contains two ASCII/EBCDIC translation tables. Both tables may be modified using software commands (Section 3.4.1.1 on page 57 and Section 5.4.1.1 on page 118). Table C–1 through Table C–4 show the contents of the translation tables as they would appear immediately after the communications server download.
PAGE 228
BSC Programmer’s Guide Table C–1: ASCII to EBCDIC Translation Table 1 0 1 2 3 4 5 6 7 8 9 A B C D E F 0 00 00 02 03 00 00 2E 2F 16 05 25 0B 0C 0D 0E 0F 1 00 11 12 13 3C 3D 00 00 18 19 3F 27 1C 1D 1E 1F 2 40 4F 7F 7B 5B 6C 50 7D 4D 5D 5C 4E 6B 60 4B 61 3 F0 F1 F2 F3 F4 F5 F6 F7 F8 F9 7A 5E 4C 7E 6E 6F 4 7C C1 C2 C3 C4 C5 C6 C7 C8 C9 D1 D2 D3 D4 D5 D6 5 D7 D8 D9 E2 E3 E4 E5 E6 E7 E8 E9 4A E0 5A
PAGE 229
C: ASCII Translation Tables Table C–2: EBCDIC to ASCII Translation Table 1 0 1 2 3 4 5 6 7 8 9 A B C D E F 0 00 01 02 03 9C 09 86 7F 97 8D 8E 0B 0C 0D 0E 0F 1 10 11 12 13 9D 85 08 87 18 19 92 8F 1C 1D 1E 1F 2 80 81 82 83 84 0A 17 1B 88 89 8A 8B 8C 05 06 07 3 90 91 16 93 94 95 96 04 98 99 9A 9B 14 15 9E 1A 4 20 A0 A1 A2 A3 A4 A5 A6 A7 A8 5B 2E 3C 28 2B 21 5 26 A9 AA AB EC AD AE AF B0 B1 5D 24 2A
PAGE 230
BSC Programmer’s Guide Table C–3: ASCII to EBCDIC Translation Table 2 0 1 2 3 4 5 6 7 8 9 A B C D E F 0 00 00 02 00 00 00 2E 2F 16 05 25 0B 0C 0D 0E 0F 1 00 11 12 13 3C 3D 00 00 18 19 3F 27 22 00 1E 1F 2 40 5A 7F 7B 5B 6C 50 7D 4D 5D 5C 4E 6B 60 4B 61 3 F0 F1 F2 F3 F4 F5 F6 F7 F8 F9 7A 5E 4C 7E 6E 6F 4 7C C1 C2 C3 C4 C5 C6 C7 C8 C9 D1 D2 D3 D4 D5 D6 5 D7 D8 D9 E2 E3 E4 E5 E6 E7 E8 E9 4A E0 6A
PAGE 231
C: ASCII Translation Tables Table C–4: EBCDIC to ASCII Translation Table 2 0 1 2 3 4 5 6 7 8 9 A B C D E F 0 00 01 02 03 00 09 00 7F 00 00 00 0B 0C 0D 0E 0F 1 10 11 12 13 00 00 08 00 18 19 00 00 1C 1D 1E 1F 2 00 00 00 00 00 0A 17 1B 00 00 00 00 00 05 06 07 3 00 00 16 00 00 00 00 04 00 00 00 00 14 15 00 1A 4 20 00 00 00 00 00 00 00 00 00 5B 2E 3C 28 2B 7C 5 26 00 00 00 00 00 00 00 00 00 21 24 2A
PAGE 232
BSC Programmer’s Guide 232 DC 900-1340I
PAGE 233
Appendix D Error Codes There are several methods used by the DLI and BSC software to report errors (Table D–1 lists the BSC errors). 1. The error code can be returned directly by the DLI function call. Typical errors are those described in the Freeway Data Link Interface Reference Guide. 2. The BSC errors listed in Table D–1 can be returned in the global variable iICPStatus. The DLI constant definitions are in the file dlicperr.h. 3.
PAGE 234
BSC Programmer’s Guide Table D–1: BSC Error Codes Code DLI Constant Name Meaning 0 DLI_ICP_ERR_NO_ERR A data block has been successfully transmitted or received on the line or a command has been successfully executed. 1 DLI_ONE_BLOCK One block of data has been sent. –103 DLI_ICP_ERR_NO_CLIENT (2 uses) The protocol software has the maximum number of clients registered for that link.
PAGE 235
D: Error Codes Table D–1: BSC Error Codes (Cont’d) Code DLI Constant Name Meaning –118 DLI_ICP_ERR_LINK_INACTIVE The link is stopped. –119 DLI_ICP_ERR_BAD_SESSID If this error occurs, please call Protogate. –121 DLI_ICP_ERR_NO_SESSION No more clients are available on this ICP. This error should never occur; if it does, please call Protogate. –122 DLI_ICP_ERR_BAD_PARMS The parameter value(s) used for the function call are illegal.
PAGE 236
BSC Programmer’s Guide Table D–1: BSC Error Codes (Cont’d) Code DLI Constant Name –131 DLI_ICP_ERR_STATION_DOWN A 3270 remote station has changed status from a logically active state to an inactive one. For control stations, this means that a remote tributary station failed to answer a general poll sequence within a required number of retries. The control unit number of the tributary station is placed in the CU byte of the pOptArgs.usCircuitID field of the error report.
PAGE 237
Appendix E BSC Loopback Test Program Note In this chapter, the DLI API interface applies to both a Freeway server or an embedded ICP using DLITE. For the embedded ICP, also refer to the user’s guide for your ICP and operating system (for example, the ICP2432 User’s Guide for Windows NT (DLITE Interface)). E.1 Loopback Test Programs The BSC loopback test programs and test directories are listed in Table E–1 and Table E–2, according to operating system (UNIX, VMS, or Windows NT).
PAGE 238
BSC Programmer’s Guide Table E–2: BSC 3780 Loopback Test Programs and Directories Operating System Program UNIX bsc3780alp.c BSC 3780 Test Directory usr/local/freeway/client/test/bsc3780 BSC3780ALP.C SYS$SYSDEVICE:[FREEWAY.CLIENT.TEST.BSC3780] VMS bsc3780alp.c Windows NT c:\freeway\client\test\bsc3780 To run the test program, perform the following steps: 1. Make sure the server TSI configuration parameter is correctly defined in the TSI text configuration file for each TSI connection definition.
PAGE 239
E: BSC Loopback Test Program hpux (for an HP/UX system) sol (for a Solaris system) aix (for an RS6000/AIX system) osf/1 (for an OSF1 system) UNIX example: make -f makefile.sol all For VMS: @MAKEVMS "" where is the TCP/IP package: MULTINET (for a Multinet system) TCPWARE (for TCPware system) UCX (for a UCX system) VMS example: @MAKEVMS "" UCX For NT: nmake -f makefile.
PAGE 240
BSC Programmer’s Guide The resulting binary configuration files have the same names with a .bin extension. For example, bsc3270aldcfg.bin. • Copies the DLI and TSI binary configuration files to the appropriate bin directory. UNIX example: freeway/client/op-sys/bin VMS example: [FREEWAY.CLIENT._tcp-sys.BIN] where is VAX or AXP for example, [FREEWAY.CLIENT.VAX_UCX.
PAGE 241
E: BSC Loopback Test Program UNIX example: mv bsc3270aldcfg.bin /usr/local/freeway/client/hpux/bin mv bsc3270altcfg.bin /usr/local/freeway/client/hpux/bin In a VMS system, if you run dlicfg and tsicfg instead of running the make file, you must do the following: • Before you run dlicfg and tsicfg, run the makefc.com command file to create the foreign commands used for dlicfg and tsicfg.
PAGE 242
BSC Programmer’s Guide 242 DC 900-1340I
PAGE 243
Appendix F BSC Detailed Command and Response Formats This appendix is intended as an aid to programmers writing an application program under one of the following conditions: 1. If you are writing to Protogate’s data link interface (DLI) using Raw operation, also refer to the Freeway Data Link Interface Reference Guide.
PAGE 244
BSC Programmer’s Guide F.1.2 Set Buffer Size The client application must process a DLI_PROT_SET_BUF_SIZE command and subsequent response to the ICP to set the maximum buffer size of data that is transmitted and/or received on the protocol link. This command message should be sent at the completion of the first link attach, and before any other command messages are sent to the ICP. The usICPCommand field of the ICP Header is DLI_ICP_CMD_WRITE. See Table F–6 on page 251. F.1.
PAGE 245
F: BSC Detailed Command and Response Formats The usICPCommand field of the ICP Header is DLI_ICP_CMD_WRITE. See Table F–11 on page 256. The client application is normally implemented to allow asynchronous receipt of both the acknowledgment to these commands, which is DLI_PROT_RESP_LOCAL_ACK (see Table F–11 on page 256), and receipt of data received at the data link (see Table F–12 on Roger LaFrance — The underlined appears to contradict Table F-11 on page 260? page 257).
PAGE 246
BSC Programmer’s Guide F.2 Command/Response Header Summary Table F–1 lists the commands and responses which are detailed in this appendix. The referenced tables show the required header field values for both the ICP Header and the Protocol Header. For the complete list of BSC 3270 commands and responses, see Table 3–4 on page 56 and Table 3–10 on page 81. For the complete list of BSC 2780/3780 commands and responses, see Table 5–4 on page 116 and Table 5–12 on page 151.
PAGE 247
F: BSC Detailed Command and Response Formats Table F–2: DLI_ICP_CMD_ATTACH Command and Response Command Value (Write) Response Value (Read) fill1 N/A N/A fill2 N/A N/A 16 16 DLI_ICP_CMD_ATTACH DLI_ICP_CMD_ATTACH iICPStatus See Note 1. See Note 2. usICPParms[0] See Note 3. See Note 3. usICPParms[1] 0 N/A usICPParms[2] 0 N/A DLI_ICP_CMD_ATTACH DLI_ICP_CMD_ATTACH iProtModifier See Note 4. See Note 2.
PAGE 248
BSC Programmer’s Guide Table F–3: DLI_ICP_CMD_DETACH Command and Response Command Value (Write) Response Value (Read) fill1 N/A N/A fill2 N/A N/A 16 16 DLI_ICP_CMD_DETACH DLI_ICP_CMD_DETACH See Note 1. See Note 2. usICPParms[0] 0 N/A usICPParms[1] 0 N/A usICPParms[2] 0 N/A DLI_ICP_CMD_DETACH DLI_ICP_CMD_DETACH iProtModifier See Note 3. See Note 4. usProtLinkID Link Number Link Number usProtCircuitID 0 N/A usProtSessionID See Note 5. See Note 5.
PAGE 249
F: BSC Detailed Command and Response Formats Table F–4: DLI_ICP_CMD_BIND Command and Response Command Value (Write) Response Value (Read) fill1 N/A N/A fill2 N/A N/A 16 16 DLI_ICP_CMD_BIND DLI_ICP_CMD_BIND See Note 1. See Note 2. usICPParms[0] 0 N/A usICPParms[1] 0 N/A usICPParms[2] 0 N/A DLI_ICP_CMD_BIND DLI_ICP_CMD_BIND iProtModifier N/A See Note 3. usProtLinkID Link Number Link Number usProtCircuitID 0 N/A usProtSessionID See Note 4. See Note 4.
PAGE 250
BSC Programmer’s Guide Table F–5: DLI_ICP_CMD_UNBIND Command and Response Command Value (Write) Response Value (Read) fill1 N/A N/A fill2 N/A N/A 16 16 DLI_ICP_CMD_UNBIND DLI_ICP_CMD_UNBIND See Note 1. See Note 2. usICPParms[0] 0 N/A usICPParms[1] 0 N/A usICPParms[2] 0 N/A DLI_ICP_CMD_UNBIND DLI_ICP_CMD_UNBIND iProtModifier 0 See Note 3. usProtLinkID Link Number Link Number usProtCircuitID 0 N/A usProtSessionID See Note 4. See Note 4.
PAGE 251
F: BSC Detailed Command and Response Formats Table F–6: DLI_PROT_SET_BUF_SIZE Command and Response Command Value (Write) Response Value (Read) fill1 0 N/A fill2 0 N/A iICPSize 18 18 DLI_ICP_CMD_WRITE DLI_ICP_CMD_WRITE See Note 1. See Note 2. usICPParms[0] 0 N/A usICPParms[1] 0 N/A usICPParms[2] 0 N/A DLI_PROT_SET_BUF_SIZE DLI_PROT_SET_BUF_SIZE iProtModifier 0 See Note 3. usProtLinkID See Note 4. N/A usProtCircuitID 0 N/A usProtSessionID See Note 5. See Note 5.
PAGE 252
BSC Programmer’s Guide Table F–7: BSC 3270 General Commands and Responses Command Value (Write) Response Value (Read) fill1 0 N/A fill2 0 N/A See Note 1. See Note 1. DLI_ICP_CMD_WRITE DLI_ICP_CMD_WRITE See Note 2. See Note 3. usICPParms[0] 0 N/A usICPParms[1] 0 N/A usICPParms[2] 0 N/A See Note 4. See Note 4. iProtModifier 0 See Note 5. usProtLinkID Link Number (if required) Link Number (if required) usProtCircuitID See Note 6. N/A usProtSessionID See Note 7. See Note 7.
PAGE 253
F: BSC Detailed Command and Response Formats Table F–8: BSC 3270 Device Creation and Modification Commands and Responses Header Command Value (Write) Response Value (Read) 0 0 See Note 1. N/A N/A See Note 1. DLI_ICP_CMD_WRITE DLI_ICP_CMD_WRITE See Note 2. 0 0 0 See Note 3. N/A N/A N/A DLI_PROT_CREATE_DEVICE or DLI_PROT_CHANGE_STATUS DLI_PROT_CREATE_DEVICE or DLI_PROT_CHANGE_STATUS See Note 4. Link Number See Note 6. See Note 7. 0 0 0 See Note 5. Link Number N/A See Note 7.
PAGE 254
BSC Programmer’s Guide Table F–9: BSC 2780/3780 General Commands and Responses Command Value (Write) Response Value (Read) fill1 0 N/A fill2 0 N/A See Note 1. See Note 1. DLI_ICP_CMD_WRITE DLI_ICP_CMD_WRITE See Note 2. See Note 3. usICPParms[0] 0 N/A usICPParms[1] 0 N/A usICPParms[2] 0 N/A See Note 4. See Note 4. iProtModifier 0 See Note 5. usProtLinkID Link Number (if required) Link Number (if required) usProtCircuitID 0 N/A usProtSessionID See Note 6. See Note 6.
PAGE 255
F: BSC Detailed Command and Response Formats Table F–10: DLI_PROT_SET_TRANS_TABLE Command and Response Command Value (Write) Response Value (Read) fill1 0 N/A fill2 0 N/A See Note 1. N/A DLI_ICP_CMD_WRITE DLI_ICP_CMD_WRITE See Note 2. See Note 3. usICPParms[0] 0 N/A usICPParms[1] 0 N/A usICPParms[2] 0 N/A DLI_PROT_SET_TRANS_TABLE DLI_PROT_SET_TRANS_TABLE iProtModifier N/A See Note 4. usProtLinkID Link Number Link Number usProtCircuitID See Note 5.
PAGE 256
BSC Programmer’s Guide Table F–11: BSC Transmit Data Commands and Response Header Command Value (Write) Response Value (Read) 0 0 See Note 1. N/A N/A 16 DLI_ICP_CMD_WRITE DLI_ICP_CMD_WRITE See Note 2. 0 0 0 See Note 3.
PAGE 257
F: BSC Detailed Command and Response Formats F.3 Response Header Format Table F–12 describes the header information for the responses associated with the receipt of data. Table F–12: BSC Receive Data Responses Header Field fill1 fill2 iICPSize ICP_header usICPCommand iICPStatus usICPParms[0] usICPParms[1] usICPParms[2] usProtCommand iProtModifier Prot_header usProtLinkID fill3 usProtSessionID fill4 fill5 fill6 Response Value (Read) N/A N/A See Note 1. DLI_ICP_CMD_READ See Note 2.
PAGE 258
BSC Programmer’s Guide 258 DC 900-1340I
PAGE 259
Index Numerics 3270 text addressing option 102 A Aborted transmission 179 Access modes 35, 37, 42, 44 control 36, 43 manager 36, 43 read 36, 43 trace 43 Addressing Internet 30 Alternating ACK control option 178 ASCII translation tables see Translation tables Attach session 243 header format 247 Audience 17 Autodial start command 131 AT support 133 SADL support 132 V.
PAGE 260
BSC Programmer’s Guide see Command codes see Data codes see Error codes see Information codes see Response codes Command blocking option 98 Command checking 200 Command codes 56, 116 DLI_ICP_CMD_ATTACH header format 247 DLI_ICP_CMD_BIND header format 249 DLI_ICP_CMD_DETACH header format 248 DLI_ICP_CMD_UNBIND header format 250 DLI_PROT_CFG_LINK 59, 120 DLI_PROT_CHANGE_STATUS 69 DLI_PROT_CLR_STATISTICS 57, 118 DLI_PROT_CREATE_DEVICE 67 header format 253 DLI_PROT_FLUSH_QUEUE 130 DLI_PROT_GET_DEVICE_STATUS 76
PAGE 261
Index data rate 88, 159 data translation 93, 165 disconnect timer length 181 DSR/DCD delay 103, 180 electrical interface 104, 182 EOM line control 176 interpoll delay 101 line turnaround delay 178 line type 182 message blocking 97, 170 BSC 2780/3780 records 174 command blocking 98 data blocking 98, 173 disabled 97, 173 modem control 95, 168 DCD signal 96, 170 DSR signal 96, 169 RTS signal 95, 169 modem type 182 number of leading SYN characters 90, 161 parity 91, 161, 162, 163 poll list delay 95 protocol 33
PAGE 262
BSC Programmer’s Guide Data rate option 88, 159 Data reception 153 multiple messages 153 Data transfer 78, 146 header data 149 header format 244, 256, 257 normal data 83, 149 priority data 149 transparent 2780 record 148 transparent data 83, 154 Data translation option 93, 165 DCD signal 96, 121, 170, 207, 225 Detach session 245 header format 248 Device address 194 Device emulation 103 Device selection 194 Device unit number 34, 66, 195 Direct memory access 29 Disable link (unbind) command 245 header format
PAGE 263
Index specific poll 66 start link 60, 121, 211 stop link 61, 122, 223 data transfer 78, 146 header data 149 normal data 79, 147, 217 priority data 149, 179, 218 transparent 2780 record 148 transparent data 79, 147, 154 information 71, 140 BSC 3270 poll list 76 buffer report 71, 140 configuration report 72, 141 software version ID 75, 146 statistics report 72, 141 status report 73, 142 translation table 75, 144 virtual 3270 device status 76 dlWrite (see also Functions) 53 Documents reference 19 Download sof
PAGE 264
BSC Programmer’s Guide 180 DLI_ICP_ERR_STATION_DOWN 101, 194, 195, 206 DLI_ICP_ERR_STATION_UP 101, 195, 206 DLI_ICP_ERR_USER_ABORT 129, 130 DLI_ICP_ERR_XMIT_ABORTED 65, 125, 126, 129, 222 DLI_ICP_ERR_XMIT_TIMEOUT 79, 88, 132, 147, 159, 196, 233 iICPStatus global variable 233 list of codes 233 optArgs.
PAGE 265
Index I/O blocking vs non-blocking 48, 108 L LAN interface processor 26 Line turnaround 217 Line bid abort 166 BSC 2780/3780 poll line 128 BSC 2780/3780 signon 126, 212 contention 166 Line control procedures 193 clock signals 208, 224 DSR/DCD up/down reporting 206, 224 Freeway/line interface 207, 224 idle line 208, 225 modem control lines 207, 224 Line turnaround 149, 176, 177, 179 Line turnaround delay option 178 Line type option 182 Line up/down reporting 196 Link configuration options see Configuration
PAGE 266
BSC Programmer’s Guide general 193 specific 195 Poll line with no data command 128 Poll list delay option 95 Poll list set command 62 Printer emulation 102 Priority data 179, 218 Processor Big Endian 247, 248, 249, 250, 251, 252, 253, 254, 255, 256 byte order 247, 248, 249, 250, 251, 252, 253, 254, 255, 256 Little Endian 247, 248, 249, 250, 251, 252, 253, 254, 255, 256 Product BSC 2780/3780 features 41 BSC 3270 features 35 features 28 introduction 25 overview 25 support 23 Programs test 237 Protocol BSC 278
PAGE 267
Index header format 253 DLI_PROT_CREATE_DEVICE header format 253 DLI_PROT_FLUSH_QUEUE 130 DLI_PROT_GET_DEVICE_STATUS 76 DLI_PROT_GET_LINK_CFG 141 DLI_PROT_GET_POLL_LIST 76 DLI_PROT_GET_SOFTWARE_VER 75, 146 DLI_PROT_GET_STATISTICS_REPORT 14 1 DLI_PROT_GET_STATUS_REPORT 142 DLI_PROT_GET_TRANS_TABLE 144 DLI_PROT_MODEM_CFG 134 DLI_PROT_RESP_BIND_ACK 61, 121, 211 DLI_PROT_RESP_ERROR 83, 154, 194, 196, 206, 207, 224, 233 see also Error codes DLI_PROT_RESP_LOCAL_ACK 78, 94, 126, 128, 130, 146, 167, 179, 180, 195,
PAGE 268
BSC Programmer’s Guide operation 34 procedures 195 safe store 66 up/down reporting 101 up/down reporting 206 Station ID option 97 Station priority option 93, 166 Statistics clear 57, 118 report 72, 141 Status message format 102 Status report 73, 142 Stop link see dlWrite categories, commands Stop link command 61, 122 Summary command header 246 response header 246 Support, product 23 T TCP/IP 28 package 184 VMS package 239 Technical support 23 telnet 28 Test mode 196 Test programs 237 Trace access mode 43 Tr
PAGE 269
BSC Programmer’s Guide DC 900-1340I Customer Report Form We are constantly improving our products. If you have suggestions or problems you would like to report regarding the hardware, software or documentation, please complete this form and mail it to Protogate at 12225 World Trade Drive, Suite R, San Diego, CA 92128, or fax it to (877) 473-0190. If you are reporting errors in the documentation, please enter the section and page number.
PAGE 270
Protogate, Inc.