Protogate Freeway 3600 Guía de usuario

Protogate, Inc.12225 World Trade Drive, Suite RSan Diego, CA 92128BSC Programmer’s GuideDC 900-1340IDecember 2002

10 DC 900-1340IBSC Programmer’s GuideB.6 Idle Line Condition... 225C ASCII Translation Tables 227D Error Codes 233E BSC Loop

100 DC 900-1340IBSC Programmer’s Guide4.19 Queue Limit Option (21)The queue limit option is used to prevent the ICP message buffer pool from beingexha

4: BSC 3270 Link Configuration OptionsDC 900-1340I 1014.20 Read Session Option (23)The read session option determines what happens on the line when da

102 DC 900-1340IBSC Programmer’s Guide4.22 3270 Text Addressing Option (27)This BSC 3270 option determines whether IBM 3270 embedded addressing is per

4: BSC 3270 Link Configuration OptionsDC 900-1340I 103with the “start print” bit set in the write control character (WCC), the link responds tothe dat

104 DC 900-1340IBSC Programmer’s Guidereport. If the signal returns before the delay time expires, the timer is reset and no reportis made. To set thi

DC 900-1340I 105Chapter5BSC 2780/3780 DLI FunctionsNoteIn this chapter, the DLI functions apply to both a Freeway serveror an embedded ICP using DLITE

106 DC 900-1340IBSC Programmer’s Guide• Appendix D explains error handling and provides a summary table of BSC errorcodes. The Freeway Data Link Inter

5: BSC 2780/3780 DLI FunctionsDC 900-1340I 107binary configuration files. Refer to Chapter 7 of this document, as well as the FreewayData Link Interfa

108 DC 900-1340IBSC Programmer’s GuideNormal and Raw operations can be mixed. For example, the client application sessioncan be configured for Normal

5: BSC 2780/3780 DLI FunctionsDC 900-1340I 109The asyncIO DLI configuration parameter specifies whether an application session usesblocking or non-blo

DC 900-1340I 11List of FiguresFigure 1–1: Freeway Configuration... 26Figure 1–2: Embedded ICP Configuration...

110 DC 900-1340IBSC Programmer’s Guide5.2 Example BSC 2780/3780 Call SequencesTa ble 5 –1 shows the sequence of DLI function calls to send and receive

5: BSC 2780/3780 DLI FunctionsDC 900-1340I 111CautionWhen using non-blocking I/O, a dlRead request must always bequeued to avoid loss of data or respo

112 DC 900-1340IBSC Programmer’s Guide5.3 Overview of DLI Functions for BSC 2780/3780This section summarizes the DLI functions used in writing a clien

5: BSC 2780/3780 DLI FunctionsDC 900-1340I 113Table 5–3: DLI Functions: Syntax and Parameters (Listed in Typical Call Order)DLI Function Parameter(s)

114 DC 900-1340IBSC Programmer’s Guide5.3.1 DLI Optional ArgumentsSection 5.4 and Section 5.5 describe the dlWrite and dlRead functions for aBSC 2780/

5: BSC 2780/3780 DLI FunctionsDC 900-1340I 1155.4 Overview of BSC 2780/3780 Requests using dlWriteFor BSC 2780/3780 the dlWrite function supports thre

116 DC 900-1340IBSC Programmer’s GuideDLI_ICP_ERR_INBUF_OVERFLOWInput buffer overflowDLI_ICP_ERR_OUTBUF_OVERFLOWOutput buffer overflow Table 5–4: Cat

5: BSC 2780/3780 DLI FunctionsDC 900-1340I 117Data TransferDLI_PROT_SEND_HDR_DATATransmit header dataDLI_PROT_SEND_HDR_DATA_EOMTransmit header data wi

118 DC 900-1340IBSC Programmer’s Guide5.4.1 Commands using Raw dlWriteSection 5.4.1.1 through Section 5.4.1.15 explain how to issue specific commands

5: BSC 2780/3780 DLI FunctionsDC 900-1340I 119An unsuccessful Clear Statistics command can return the following error code in thedlRead pOptArgs.iICPS

12 DC 900-1340IBSC Programmer’s GuideFigure A–2: Device Selection Sequence... 195Figure A–3: Normal Operation for Virtual Print

120 DC 900-1340IBSC Programmer’s GuideDLI_ICP_ERR_BAD_PARMSThe parameter value(s) used for the function call areillegal.DLI_ICP_ERR_LINK_ACTIVEThe lin

5: BSC 2780/3780 DLI FunctionsDC 900-1340I 121Each option number corresponds to a software-selectable option of the BSC 2780/3780software. The configu

122 DC 900-1340IBSC Programmer’s Guidedepending on the setting of the modem control option, Section 6.15 on page 168) fromthe remote end. The link is

5: BSC 2780/3780 DLI FunctionsDC 900-1340I 123vated. If you are using non-blocking I/O, you must also make a dlPoll request to read thecompletion stat

124 DC 900-1340IBSC Programmer’s Guidethe remote station. This is in contrast to the Send EOT command which causes the BSCsoftware to reject the messa

5: BSC 2780/3780 DLI FunctionsDC 900-1340I 125remote station (forward abort) before the client sendsthe message acceptance/rejection.DLI_ICP_ERR_XMIT_

126 DC 900-1340IBSC Programmer’s GuideIf the BSC 2780/3780 software receives a DLE EOT from the line, the client receives adisconnect message with the

5: BSC 2780/3780 DLI FunctionsDC 900-1340I 127response. The BSC 2780/3780 forwards the response to the client with the dlReadpOptArgs.usProtCommand fi

128 DC 900-1340IBSC Programmer’s GuideThe Send Disconnect command is used to:• reject a signon bid• reject a signon response An unsuccessful Signon co

5: BSC 2780/3780 DLI FunctionsDC 900-1340I 129When issuing a Poll Line command, wait until the data acknowledge response isreturned from the command b

DC 900-1340I 13List of TablesTable 2–1: BSC3270 Session Access Modes... 36Table 2–2: BSC 3270 Access Modes for Various Operations

130 DC 900-1340IBSC Programmer’s GuideDLI_ICP_ERR_LINK_INACTIVEThe link is stopped.5.4.1.12 BSC 2780/3780 Flush Queue CommandUse the dlWrite function

5: BSC 2780/3780 DLI FunctionsDC 900-1340I 1315.4.1.13 BSC 2780/3780 Autodial Start CommandUse the dlWrite function with the pOptArgs.usProtCommand fi

132 DC 900-1340IBSC Programmer’s GuideSADL SupportIf the modem type option is set to SADL, the Autodial Start command causes theBSC 2780/3780 software

5: BSC 2780/3780 DLI FunctionsDC 900-1340I 133FNo answer tone (DLI_ICP_ERR_NO_ANSWER)E No dial tone (DLI_ICP_ERR_NO_DIALTONE) C Invalid command or con

134 DC 900-1340IBSC Programmer’s GuideCONNECT On lineNO CARRIERNo carrier detected (DLI_ICP_ERR_DSR_DOWN)BUSY Line Busy (DLI_ICP_ERR_DEVICE_BUSY)NO AN

5: BSC 2780/3780 DLI FunctionsDC 900-1340I 135SADL Modem ConfigurationIf the modem type option is set to SADL, the BSC 2780/3780 software sends the co

136 DC 900-1340IBSC Programmer’s Guide5.4.1.15 BSC 2780/3780 Trace using dlWriteThe following trace commands allow a client application program to mon

5: BSC 2780/3780 DLI FunctionsDC 900-1340I 137is limited to the size of the ICP message buffer minus the first 8 bytes of statistics). Referto Figure

138 DC 900-1340IBSC Programmer’s GuideTable 5–7: Trace Event NumbersEvent BSC Control Sequence1 DSR/DCD change2 ENQ3 ETB text block4 ETX text block5 A

5: BSC 2780/3780 DLI FunctionsDC 900-1340I 139If a block of data is associated with the BSC control sequence, data length indicates thenumber of chara

14 DC 900-1340IBSC Programmer’s GuideTable 5–10: BSC 2780/3780 Status Report Definition... 143Table 5–11: Last Event Codes for Link St

140 DC 900-1340IBSC Programmer’s Guide5.4.2 Information Requests using Raw dlWriteSection 5.4.2.1 through Section 5.4.2.6 explain how to issue specifi

5: BSC 2780/3780 DLI FunctionsDC 900-1340I 1415.4.2.2 Request Configuration ReportUse the dlWrite function with the pOptArgs.usProtCommand field set t

142 DC 900-1340IBSC Programmer’s Guide5.4.2.4 Request Status ReportUse the dlWrite function with the pOptArgs.usProtCommand field set toDLI_PROT_GET_S

5: BSC 2780/3780 DLI FunctionsDC 900-1340I 143Table 5–10: BSC 2780/3780 Status Report DefinitionWo rd Description Va lue Setting1 Link status 0 Off1 O

144 DC 900-1340IBSC Programmer’s Guidedial receive awaiting the modem’s message or messages on the statusof the autodial sequenceV.25 autodial sending

5: BSC 2780/3780 DLI FunctionsDC 900-1340I 145Table 5–11: Last Event Codes for Link Status Report Code Meaning1 Timer expired 2 DSR/DCD change3 V.25 m

146 DC 900-1340IBSC Programmer’s Guide5.4.2.6 Request Software Version IDUse the dlWrite function with the pOptArgs.usProtCommand field set toDLI_PROT

5: BSC 2780/3780 DLI FunctionsDC 900-1340I 147If the DLI localAck configuration parameter is set to “yes” (which is the default), thedata acknowledge

148 DC 900-1340IBSC Programmer’s GuideDLI_PROT_SEND_TRANS_DATA_EOM to send transparent data. The client can send transpar-ent data in either ASCII or

5: BSC 2780/3780 DLI FunctionsDC 900-1340I 149The BSC 2780/3780 software transmits the data in the modified format of Figure 5–5: The DLE characters a

List of TablesDC 900-1340I 15Table F–12:BSC Receive Data Responses...257

150 DC 900-1340IBSC Programmer’s Guide5.5 Overview of BSC 2780/3780 Responses using Raw dlReadTa ble 5 –12 shows the valid BSC 2780/3780 codes sent to

5: BSC 2780/3780 DLI FunctionsDC 900-1340I 151Table 5–12: BSC 2780/3780 Response CodesCategoryDLI Response Code in pOptArgs.usProtCommand FieldUsageRe

152 DC 900-1340IBSC Programmer’s GuideCommand ConfirmationsDLI_PROT_SET_TRANS_TABLESet Translation Table confirmation. Section 5.4.1.1DLI_PROT_CLR_STA

5: BSC 2780/3780 DLI FunctionsDC 900-1340I 1535.5.1 Received DataThe BSC 2780/3780 software provides the following dlRead codes for data reception: •

154 DC 900-1340IBSC Programmer’s GuideCautionWith larger transparent 2780 records (such that only one recordfits into a transmission block), the BSC 2

DC 900-1340I 155Chapter6BSC 2780/3780 Link Configuration OptionsNoteThis chapter, along with Chapter 5 and Appendix B, should beread by programmers wh

156 DC 900-1340IBSC Programmer’s GuideTable 6–1: BSC 2780/3780 Link Configuration Options and SettingsOption Number Va lu eDefault ()SettingData Rate

6: BSC 2780/3780 Link Configuration OptionsDC 900-1340I 157Station Prioritya11 0  Slave1 MasterSpace Compressiona12 0  Disable1 EnableConversational

158 DC 900-1340IBSC Programmer’s GuideLine Turnaround Delay 25 n 0 n = delay after receiving EOT in tenths of seconds (1 to 8192)TTD/WACKa26 0 Disable

6: BSC 2780/3780 Link Configuration OptionsDC 900-1340I 1596.1 Data Rate Option (1) The data rate can be set by the client for installations where the

16 DC 900-1340IBSC Programmer’s Guide

160 DC 900-1340IBSC Programmer’s Guide6.2.1 External Protogate recommends the external clock setting for most communications applica-tions that involv

6: BSC 2780/3780 Link Configuration OptionsDC 900-1340I 1616.4 Number of Leading SYN Characters Option (4) This option specifies the number of SYN cha

162 DC 900-1340IBSC Programmer’s GuideEBCDIC/CRC-16 character set is used. The parity used for ASCII transmission is nor-mally odd.To set this option

6: BSC 2780/3780 Link Configuration OptionsDC 900-1340I 1636.7.1 ASCII/LRC-8 When this setting is used, the BSC control sequences are transmitted in 7

164 DC 900-1340IBSC Programmer’s Guide0 none No data parity, no control character parity 1 odd No data parity, odd control character parity2 even No d

6: BSC 2780/3780 Link Configuration OptionsDC 900-1340I 1656.9 Data Translation Option (10) This option invokes transmit and receive data translation

166 DC 900-1340IBSC Programmer’s GuideTo set this option using the DLI configuration file, use the dataTranslation parameter; forexample, dataTranslat

6: BSC 2780/3780 Link Configuration OptionsDC 900-1340I 1676.12 Conversational Mode Option (13)Conversational mode allows a remote station to respond

168 DC 900-1340IBSC Programmer’s GuideTo set this option using the DLI configuration file, use the retryLimit parameter; forexample, retryLimit = 3. S

6: BSC 2780/3780 Link Configuration OptionsDC 900-1340I 1696.15.1 RTS SignalWhen the modem control option is set to half-duplex operation (HDX-1, HDX-

DC 900-1340I 17PrefacePurpose of DocumentThis document describes the operation and programming interface required to useProtogate’s Binary Synchronous

170 DC 900-1340IBSC Programmer’s Guide6.15.3 DCD SignalThe modem control option allows a link to use the data carrier detect (DCD) signal asDSR. With

6: BSC 2780/3780 Link Configuration OptionsDC 900-1340I 171NoteWhen transparent data is received, blocking acts as if messageblocking is set to disabl

172 DC 900-1340IBSC Programmer’s GuideFigure 6–3: Receive with Disabled Message Blocking Option Figure 6–4: Receive with Data Blocking Option Communic

6: BSC 2780/3780 Link Configuration OptionsDC 900-1340I 1736.17.1 Blocking DisabledIf the message blocking option is set to disable, blocking/deblocki

174 DC 900-1340IBSC Programmer’s Guide6.17.3 BSC 2780/3780 Record HandlingWhen message blocking is set to data blocking, the BSC 2780/3780 software pe

6: BSC 2780/3780 Link Configuration OptionsDC 900-1340I 1756.18 Block Checking Option (20)This option determines what characters are included in the b

176 DC 900-1340IBSC Programmer’s Guideing messages could deplete the buffer supply and the other links would not be able toobtain buffers.To prevent t

6: BSC 2780/3780 Link Configuration OptionsDC 900-1340I 177If this option is set to reverse, the BSC 2780/3780 software automatically turns the linear

178 DC 900-1340IBSC Programmer’s Guideoption is set to disable (the default setting), incoming data blocks are routed to theManager session for that l

6: BSC 2780/3780 Link Configuration OptionsDC 900-1340I 179If this option is set to normal (TTD and WACK), and safe store acknowledge is set toenable

18 DC 900-1340IBSC Programmer’s Guide• a Freeway communications server or an embedded ICP that runs the communi-cations software• a client computer th

180 DC 900-1340IBSC Programmer’s GuideWhen an RVI is received during transmission of a message, the BSC 2780/3780 softwareindicates the successful tra

6: BSC 2780/3780 Link Configuration OptionsDC 900-1340I 181report. If the signal returns before the delay time expires, the timer is reset and no repo

182 DC 900-1340IBSC Programmer’s GuideTo set this option using the DLI configuration file, use the discTimerLen parameter; forexample, discTimerLen =

DC 900-1340I 183Chapter7BSC Link Configuration Using dlicfgNoteThe term “Freeway” can mean either a Freeway server or anembedded ICP. For the embedded

184 DC 900-1340IBSC Programmer’s GuideThe DLI and TSI configuration process is a part of the loopback testing proceduredescribed in Appendix E and the

7: BSC Link Configuration Using dlicfgDC 900-1340I 185filename). If the optional filename is not supplied, the binary file is given the samename as yo

186 DC 900-1340IBSC Programmer’s GuideUNIX example: mv bsc3270aldcfg.bin /usr/local/freeway/client/hpux/binmv bsc3270altcfg.bin /usr/local/freeway/cli

7: BSC Link Configuration Using dlicfgDC 900-1340I 187Figure 7–1: DLI and TSI Configuration ProcessApplicationDLITSITransportEnvironment2836dlicfgDLI

188 DC 900-1340IBSC Programmer’s Guide7.2 DLI Session ConfigurationThe DLI text configuration file used by the dlicfg program consists of the followin

7: BSC Link Configuration Using dlicfgDC 900-1340I 189main // DLI “main” section: //{asyncIO = “no”; // Wait for I/O completion //tsiCfgName = “bsc327

PrefaceDC 900-1340I 19Appendix C contains the ASCII/EBCDIC code translation tables.Appendix D describes error handling and lists the error codes.Appen

190 DC 900-1340IBSC Programmer’s GuideTable 7–1: BSC 3270 ICP Link Parameters and Defaults for Using dlicfgdlicfg Option Name Default Valid Valuesdata

7: BSC Link Configuration Using dlicfgDC 900-1340I 191Table 7–2: BSC 2780/3780 ICP Link Parameters and Defaults for Using dlicfgdlicfg Option Name Def

192 DC 900-1340IBSC Programmer’s GuidedsrDelay 3 1–127ttdLimit 0 0–8192discTimerLen 0 0–1800modemType “SADL” “none”, “SADL”, “V25bis” or “AT”elecInter

DC 900-1340I 193AppendixABSC 3270 Line Control ProceduresThis appendix defines line control procedures for the BSC 3270 protocol.NoteThis appendix, al

194 DC 900-1340IBSC Programmer’s Guideto control units in the order specified in the poll list given to the ICP in the Set Poll Listcommand (Section 3

A: BSC 3270 Line Control ProceduresDC 900-1340I 195In order to give equal priority to input and output, at least one general poll is issuedafter each

196 DC 900-1340IBSC Programmer’s GuideA.2.1 Normal ModeA tributary link operates in normal mode when it acts as only one control unit. Normalmode is i

A: BSC 3270 Line Control ProceduresDC 900-1340I 197A.4 Virtual Device ProceduresThe following sections describe some of the line procedures involving

198 DC 900-1340IBSC Programmer’s GuideFigure A–3: Normal Operation for Virtual PrinterClient FreewayCommunication Line<ACK0>3270 WRITE command b

A: BSC 3270 Line Control ProceduresDC 900-1340I 199Figure A–4: Printer Error During PrintoutClient FreewayCommunication Line3270 WRITE command byteDLI

Protogate, Inc.12225 World Trade Drive, Suite RSan Diego, CA 92128(858) 451-0865BSC Programmer’s Guide© 2002 Protogate, Inc. All rights reservedPrinte

20 DC 900-1340IBSC Programmer’s GuideFreeway Software Installation Support• Freeway Server User’s Guide DC 900-1333• Freeway Software Release Addendum

200 DC 900-1340IBSC Programmer’s GuideA.4.3 3270 Command CheckingA tributary link scans the incoming data stream for the presence of valid 3270 com-ma

A: BSC 3270 Line Control ProceduresDC 900-1340I 201Figure A–6: BSC 3270 Command CheckingClient FreewayCommunication Lineillegal 3270 command<EOT>

202 DC 900-1340IBSC Programmer’s GuideFigure A–7: RVI Ignored by BSC 3270 MasterClient FreewayCommunication Line3270 WRITE command byteselectspecific

A: BSC 3270 Line Control ProceduresDC 900-1340I 203Figure A–8: WACK Ignored by BSC 3270 MasterClient FreewayCommunication Line3270 WRITE command bytes

204 DC 900-1340IBSC Programmer’s GuideA.4.4 BSC 3270 Sense/Status MessageStatus and sense conditions are recorded by the BSC 3274 control unit for eac

A: BSC 3270 Line Control ProceduresDC 900-1340I 205combinations of status and sense bits, only a portion of this total is normally used.These combinat

206 DC 900-1340IBSC Programmer’s GuideA.5 Station Up/Down ReportingStation up/down reporting is based on line activity (as opposed to DSR/DCD up/downr

A: BSC 3270 Line Control ProceduresDC 900-1340I 207When the DSR/DCD signal returns, BSC sends the client the DLI_PROT_RESP_ERROR errorreport containin

208 DC 900-1340IBSC Programmer’s GuideA.9 Clock SignalsThe BSC communication interface is designed to use either externally or internally gen-erated c

DC 900-1340I 209AppendixBBSC 2780/3780 Control ProceduresThis appendix defines the control procedures for the BSC 2780/3780 protocol.NoteThis appendix

PrefaceDC 900-1340I 21Document ConventionsThis document follows the most significant byte first (MSB) and most significant wordfirst (MSW) conventions

210 DC 900-1340IBSC Programmer’s GuideB.1.1 BSC 2780/3780 Software InitializationAfter downloading the software to the ICP, issue a dlOpen request. If

B: BSC 2780/3780 Control ProceduresDC 900-1340I 211B.1.2 Normal Link StartTo start link operation, the client issues a Link Configuration command (Sec

212 DC 900-1340IBSC Programmer’s GuideB.1.3 Signon Procedure using BSC 2780/3780 Software CommandsThe BSC 2780/3780 software provides an optional init

B: BSC 2780/3780 Control ProceduresDC 900-1340I 213Figure B–3: Signon Procedure (Transmit with Immediate Data)Client FreewayRemote StationSignon comma

214 DC 900-1340IBSC Programmer’s GuideFigure B–4: Signon Procedure (Transmit with Delayed Data)Client FreewayRemote StationSignon command = “LOCAL”LOC

B: BSC 2780/3780 Control ProceduresDC 900-1340I 215Figure B–5: Signon Procedure (Receive)Client FreewayRemote StationREMOTE<ENQ>Signon response

216 DC 900-1340IBSC Programmer’s GuideB.1.4 Data ReceptionThe BSC 2780/3780 software can receive data at any time after the link is started. Theclient

B: BSC 2780/3780 Control ProceduresDC 900-1340I 217B.1.5 Normal Data TransmissionIn Figure B–7, the client program sends a two-block message to the B

218 DC 900-1340IBSC Programmer’s GuideB.1.6 Priority Data ReceptionAssuming the BSC 2780/3780 software has the RVI handling option (Section 6.25 onpag

B: BSC 2780/3780 Control ProceduresDC 900-1340I 219Figure B–8: Two-message Sequence with Priority Message InterruptClient FreewayRemote StationMessage

22 DC 900-1340IBSC Programmer’s Guideembedded ICP product using DLITE (for example, the embedded ICP2432 usingDLITE on a Windows NT system).Physical “

220 DC 900-1340IBSC Programmer’s GuideB.1.7 Recoverable Errors In TransmissionFigure B–9 shows how the BSC 2780/3780 software handles recoverable line

B: BSC 2780/3780 Control ProceduresDC 900-1340I 221B.1.8 Unrecoverable Errors In TransmissionWhen an unrecoverable transmission error occurs, the BSC

222 DC 900-1340IBSC Programmer’s GuideFigure B–11: Transmission Aborted by the Remote StationClient FreewayRemote StationACK0ENQBlock 1 (ETB)Normal da

B: BSC 2780/3780 Control ProceduresDC 900-1340I 223B.1.9 Normal Link StopThe client can stop a link at any time by issuing a Stop Link command (Sectio

224 DC 900-1340IBSC Programmer’s GuideB.2 DSR/DCD Up/Down ReportingIf the data set ready (DSR) or the data carrier detect (DCD) modem signal (dependin

B: BSC 2780/3780 Control ProceduresDC 900-1340I 225data source. Under external clocking, BSC receives its transmit clocks from the remotecomputer. Und

226 DC 900-1340IBSC Programmer’s GuideTable B– 2: EIA-232 Clock SignalsSignal Pin Direction DescriptionXMT CLK 15 Input External clocking: transmit c

DC 900-1340I 227AppendixCASCII Translation TablesThe BSC software contains two ASCII/EBCDIC translation tables. Both tables may bemodified using softw

228 DC 900-1340IBSC Programmer’s GuideTable C–1: ASCII to EBCDIC Translation Table 10 1 2 3 4 5 6 7 8 9 A B C D E F0 00 00 02 03 00 00 2E 2F 16 05 25

C: ASCII Translation TablesDC 900-1340I 229Table C– 2: EBCDIC to ASCII Translation Table 10 1 2 3 4 5 6 7 8 9 A B C D E F0 00 01 02 03 9C 09 86 7F 97

PrefaceDC 900-1340I 23Customer SupportIf you are having trouble with any Protogate product, call us at (858) 451-0865 Mondaythrough Friday between 8 a

230 DC 900-1340IBSC Programmer’s GuideTable C–3: ASCII to EBCDIC Translation Table 20 1 2 3 4 5 6 7 8 9 A B C D E F0 00 00 02 00 00 00 2E 2F 16 05 25

C: ASCII Translation TablesDC 900-1340I 231Table C– 4: EBCDIC to ASCII Translation Table 20 1 2 3 4 5 6 7 8 9 A B C D E F0 00 01 02 03 00 09 00 7F 00

232 DC 900-1340IBSC Programmer’s Guide

DC 900-1340I 233AppendixDError CodesThere are several methods used by the DLI and BSC software to report errors(Ta bl e D – 1 lists the BSC errors).1.

234 DC 900-1340IBSC Programmer’s GuideTable D– 1: BSC Error CodesCode DLI Constant Name Meaning0DLI_ICP_ERR_NO_ERRA data block has been successfully t

D: Error CodesDC 900-1340I 235–118DLI_ICP_ERR_LINK_INACTIVEThe link is stopped.–119DLI_ICP_ERR_BAD_SESSIDIf this error occurs, please call Protogate.–

236 DC 900-1340IBSC Programmer’s Guide–131DLI_ICP_ERR_STATION_DOWNA 3270 remote station has changed status from a logi-cally active state to an inacti

DC 900-1340I 237AppendixEBSC Loopback Test ProgramNoteIn this chapter, the DLI API interface applies to both a Freewayserver or an embedded ICP using

238 DC 900-1340IBSC Programmer’s GuideTo run the test program, perform the following steps:1. Make sure the server TSI configuration parameter is corr

E: BSC Loopback Test ProgramDC 900-1340I 239hpux (for an HP/UX system)sol (for a Solaris system)aix (for an RS6000/AIX system)osf/1 (for an OSF1 syste

24 DC 900-1340IBSC Programmer’s Guide

240 DC 900-1340IBSC Programmer’s GuideThe resulting binary configuration files have the same names with a .binextension. For example, bsc3270aldcfg.bi

E: BSC Loopback Test ProgramDC 900-1340I 241UNIX example: mv bsc3270aldcfg.bin /usr/local/freeway/client/hpux/binmv bsc3270altcfg.bin /usr/local/freew

242 DC 900-1340IBSC Programmer’s Guide

DC 900-1340I 243AppendixFBSC Detailed Command and Response FormatsThis appendix is intended as an aid to programmers writing an application programund

244 DC 900-1340IBSC Programmer’s GuideF.1.2 Set Buffer SizeThe client application must process a DLI_PROT_SET_BUF_SIZE command and subsequentresponse

F: BSC Detailed Command and Response FormatsDC 900-1340I 245The usICPCommand field of the ICP Header is DLI_ICP_CMD_WRITE. See Table F–11 onpage 256.

246 DC 900-1340IBSC Programmer’s GuideF.2 Command/Response Header SummaryTa ble F –1 lists the commands and responses which are detailed in this appen

F: BSC Detailed Command and Response FormatsDC 900-1340I 247Notes:1. Zero (0) for Big Endian clients (such as SunOS)0x4000 for Little Endian clients (

248 DC 900-1340IBSC Programmer’s GuideNotes:1. Zero (0) for Big Endian clients (such as SunOS)0x4000 for Little Endian clients (such as DEC)2. DLI ret

F: BSC Detailed Command and Response FormatsDC 900-1340I 249Notes:1. Zero (0) for Big Endian clients (such as SunOS)0x4000 for Little Endian clients (

DC 900-1340I 25Chapter1Introduction1.1 Product OverviewProtogate provides a variety of wide-area network (WAN) connectivity solutions forreal-time fin

250 DC 900-1340IBSC Programmer’s GuideNotes:1. Zero (0) for Big Endian clients (such as SunOS)0x4000 for Little Endian clients (such as DEC)2. DLI ret

F: BSC Detailed Command and Response FormatsDC 900-1340I 251Notes:1. Zero (0) for Big Endian clients (such as SunOS)0x4000 for Little Endian clients (

252 DC 900-1340IBSC Programmer’s GuideNotes:1. 16 plus the size of the data area2. Zero (0) for Big Endian clients (such as SunOS)0x4000 for Little En

F: BSC Detailed Command and Response FormatsDC 900-1340I 253Notes:1. To create a device, iICPSize is set to 16 plus the number of devices to create. T

254 DC 900-1340IBSC Programmer’s GuideNotes:1. 16 plus the size of the data area2. Zero (0) for Big Endian clients (such as SunOS)0x4000 for Little En

F: BSC Detailed Command and Response FormatsDC 900-1340I 255Notes:1. iICPSize = 528 (Protocol Header size (16) plus two 256-byte translation tables).

256 DC 900-1340IBSC Programmer’s GuideNotes:1. 16 plus the size of the data area2. Zero (0) for Big Endian clients (such as SunOS)0x4000 for Little En

F: BSC Detailed Command and Response FormatsDC 900-1340I 257F.3 Response Header FormatTa ble F –12 describes the header information for the responses

258 DC 900-1340IBSC Programmer’s Guide

DC 900-1340I 259IndexNumerics3270 text addressing option 102AAborted transmission 179Access modes 35, 37, 42, 44control 36, 43manager 36, 43read 36, 4

26 DC 900-1340IBSC Programmer’s GuideTo maintain high data throughput, Freeway uses a multi-processor architecture to sup-port the LAN and WAN service

260 DC 900-1340IBSC Programmer’s Guidesee Command codessee Data codessee Error codessee Information codessee Response codesCommand blocking option 98C

IndexDC 900-1340I 261data rate 88, 159data translation 93, 165disconnect timer length 181DSR/DCD delay 103, 180electrical interface 104, 182EOM line c

262 DC 900-1340IBSC Programmer’s GuideData rate option 88, 159Data reception 153multiple messages 153Data transfer 78, 146header data 149header format

IndexDC 900-1340I 263specific poll 66start link 60, 121, 211stop link 61, 122, 223data transfer 78, 146header data 149normal data 79, 147, 217priority

264 DC 900-1340IBSC Programmer’s Guide180DLI_ICP_ERR_STATION_DOWN 101, 194, 195, 206DLI_ICP_ERR_STATION_UP 101, 195, 206DLI_ICP_ERR_USER_ABORT 129, 13

IndexDC 900-1340I 265I/Oblocking vs non-blocking 48, 108LLAN interface processor 26Lineturnaround 217Line bidabort 166BSC 2780/3780 poll line 128BSC 2

266 DC 900-1340IBSC Programmer’s Guidegeneral 193specific 195Poll line with no data command 128Poll list delay option 95Poll list set command 62Printe

IndexDC 900-1340I 267header format 253DLI_PROT_CREATE_DEVICEheader format 253DLI_PROT_FLUSH_QUEUE 130DLI_PROT_GET_DEVICE_STATUS 76DLI_PROT_GET_LINK_CF

268 DC 900-1340IBSC Programmer’s Guideoperation 34procedures 195safe store 66up/down reporting 101up/down reporting 206Station ID option 97Station pri

BSC Programmer’s GuideDC 900-1340ICustomer Report FormWe are constantly improving our products. If you have suggestions or problems you wouldlike to r

1: IntroductionDC 900-1340I 271.1.2 Embedded ICPThe embedded ICP connects your client computer directly to the WAN (for example,using Protogate’s ICP2

Protogate, Inc.Customer Service12225 World Trade Drive, Suite RSan Diego, CA 92128

28 DC 900-1340IBSC Programmer’s GuideSummary of product features:• Provision of WAN connectivity either through a LAN-based Freeway server ordirectly

1: IntroductionDC 900-1340I 291.2 Freeway Client-Server EnvironmentThe Freeway server acts as a gateway that connects a client on a local-area network

DC 900-1340I 3ContentsList of Figures 11List of Tables 13Preface 171Introduction 251.1 Product Overview... 251.1.1 Freeway

30 DC 900-1340IBSC Programmer’s Guide1.2.1 Establishing Freeway Server Internet AddressesThe Freeway server must be addressable in order for a client

1: IntroductionDC 900-1340I 311.4.2 Opening a SessionAfter the DLI and TSI configurations are properly defined, your client application usesthe dlOpen

32 DC 900-1340IBSC Programmer’s Guide1.5.1 Software Description Protogate’s BSC product includes the following major software components:• A group of

DC 900-1340I 33Chapter2BSC Protocol Summary2.1 BSC 3270 Protocol ImplementationThe Protogate Binary Synchronous Communications (BSC) product is a soft

34 DC 900-1340IBSC Programmer’s Guide2.1.1 3270 Control Station OperationA link configured as a control station can poll up to 32 tributary stations (

2: BSC Protocol SummaryDC 900-1340I 352.1.4 Messages and Transmission BlocksThe client computer sends data to the BSC software as complete messages. A

36 DC 900-1340IBSC Programmer’s GuideThe valid BSC 3270 access modes are defined in Ta bl e 2 –1 . Ta ble 2 –2 shows the requiredaccess modes for vari

2: BSC Protocol SummaryDC 900-1340I 37Table 2–2: BSC 3270 Access Modes for Various OperationsOperation Access Mode Required Reference SectionSet Trans

38 DC 900-1340IBSC Programmer’s Guide2.3 BSC 2780/3780 Protocol ImplementationThe protocol used in the BSC 2780/3780 product is a logical, half-duplex

2: BSC Protocol SummaryDC 900-1340I 39Figure 2–2 shows the transparent 2780 text block. Each block starts with a data-link-escape STX character pair (

4 DC 900-1340IBSC Programmer’s Guide2.1.4 Messages and Transmission Blocks... 352.1.5 BSC 3270 Product Features...

40 DC 900-1340IBSC Programmer’s GuideThe maximum size for a 3780 text block is 512 bytes including the STX and ETX char-acters. BSC 3780 also allows f

2: BSC Protocol SummaryDC 900-1340I 41called transmission blocks, to provide more accurate and efficient error control. BSCbegins each transmission bl

42 DC 900-1340IBSC Programmer’s GuideThe following features allow greater programming flexibility:• Multiple levels of interface routines• Automatic d

2: BSC Protocol SummaryDC 900-1340I 43Table 2–3: BSC 2780/3780 Session Access ModesMode UsageManager Set Manager mode for a session by setting the D

44 DC 900-1340IBSC Programmer’s GuideTable 2–4: BSC 2780/3780 Access Modes for Various OperationsOperation Access Mode Required Reference SectionSet T

DC 900-1340I 45Chapter3BSC 3270 DLI FunctionsNoteIn this chapter, the DLI API interface applies to both a Freewayserver or an embedded ICP using DLITE

46 DC 900-1340IBSC Programmer’s Guide• Appendix D explains error handling and provides a summary table of BSC errorcodes. The Freeway Data Link Interf

3: BSC 3270 DLI FunctionsDC 900-1340I 47configurations are defined by specifying parameters in DLI and TSI ASCII configura-tion files and then running

48 DC 900-1340IBSC Programmer’s Guidesequence (especially in BSC 3270). Refer to the Freeway Data Link Interface Refer-ence Guide if you need to use R

3: BSC 3270 DLI FunctionsDC 900-1340I 49ware interrupt level in the completion handler established by the dlInit or dlOpen func-tion, or by periodic u

ContentsDC 900-1340I 53.4.2.2 Request Configuration Report ... 723.4.2.3 Request Statistics Report... 723.4.2.4 Requ

50 DC 900-1340IBSC Programmer’s Guide3.2 Example BSC 3270 Call SequencesTa ble 3 –1 shows the sequence of DLI function calls to send and receive data

3: BSC 3270 DLI FunctionsDC 900-1340I 51CautionWhen using non-blocking I/O, a dlRead request must always bequeued to avoid loss of data or responses f

52 DC 900-1340IBSC Programmer’s Guide3.3 Overview of DLI Functions for BSC 3270This section summarizes the DLI functions used in writing a client appl

3: BSC 3270 DLI FunctionsDC 900-1340I 53Table 3–3: DLI Functions: Syntax and Parameters (Listed in Typical Call Order)DLI Function Parameter(s) Parame

54 DC 900-1340IBSC Programmer’s Guide3.3.1 DLI Optional ArgumentsSection 3.4 and Section 3.5 describe the dlWrite and dlRead functions for a BSC 3270a

3: BSC 3270 DLI FunctionsDC 900-1340I 553.4 Overview of BSC 3270 Requests using dlWriteFor BSC 3270 the dlWrite function supports three dlWrite catego

56 DC 900-1340IBSC Programmer’s GuideTable 3–4: Categories for BSC 3270 dlWrite RequestsCategory DLI Request Code UsageCommandsto ICPDLI_PROT_CFG_LINK

3: BSC 3270 DLI FunctionsDC 900-1340I 573.4.1 Commands using Raw dlWriteSection 3.4.1.1 through Section 3.4.1.12 explain how to issue specific command

58 DC 900-1340IBSC Programmer’s Guidespecify the CU. If the LSB of the field is not set to ‘1,’ the overall link statistics are notcleared. Use CU num

3: BSC 3270 DLI FunctionsDC 900-1340I 59DLI_ICP_ERR_BAD_MODEThe function request is not available for the requestedaccess mode.DLI_ICP_ERR_BAD_PARMSTh

6 DC 900-1340IBSC Programmer’s Guide4.15 Safe Store Option (17)... 964.16 Station ID Option (18) ...

60 DC 900-1340IBSC Programmer’s GuideEach option number corresponds to a software-selectable option of the BSC 3270 soft-ware. The configuration value

3: BSC 3270 DLI FunctionsDC 900-1340I 61a link after issuing a Stop Link command (Section 3.4.1.6). After receiving this com-mand, the BSC 3270 softwa

62 DC 900-1340IBSC Programmer’s Guidenate a session at the end of a client application. The Stop Link command is useful fortemporarily stopping the li

3: BSC 3270 DLI FunctionsDC 900-1340I 63BSC 3270 software responds with the new poll list using the samepOptArgs.usProtCommand field and format used t

64 DC 900-1340IBSC Programmer’s Guide3.4.1.8 Safe Store Acknowledge CommandUse the dlWrite function with the pOptArgs.usProtCommand field set toDLI_PR

3: BSC 3270 DLI FunctionsDC 900-1340I 65Note that with the safe store option enabled, the client application program must sendan acceptance (safe stor

66 DC 900-1340IBSC Programmer’s GuideSafe Store on BSC 3270 Tributary StationsUnlike the control station, a tributary station is unable to send WACKs

3: BSC 3270 DLI FunctionsDC 900-1340I 673.4.1.10 Send EOT CommandUse the dlWrite function with the pOptArgs.usProtCommand field set toDLI_PROT_SEND_EO

68 DC 900-1340IBSC Programmer’s GuidepOptArgs.usProtCircuitID field to the control unit number to which the virtual devicesare to be attached.Figure 3

3: BSC 3270 DLI FunctionsDC 900-1340I 69An unsuccessful Create Virtual 3270 Devices command can return one of the followingerror codes in the dlRead p

ContentsDC 900-1340I 75.4.1.12 BSC 2780/3780 Flush Queue Command . . ...1305.4.1.13 BSC 2780/3780 Autodial Start Command . ...1315.4.1

70 DC 900-1340IBSC Programmer’s GuideSection A.4 on page 197 for more information on virtual device procedures and linesequence diagrams.An unsuccessf

3: BSC 3270 DLI FunctionsDC 900-1340I 713.4.2 Information Requests using Raw dlWriteSection 3.4.2.1 through Section 3.4.2.8 explain how to issue speci

72 DC 900-1340IBSC Programmer’s Guide3.4.2.2 Request Configuration ReportUse the dlWrite function with the pOptArgs.usProtCommand field set toDLI_PROT

3: BSC 3270 DLI FunctionsDC 900-1340I 73 3.4.2.4 Request Status ReportUse the dlWrite function with the pOptArgs.usProtCommand field set toDLI_PROT_GE

74 DC 900-1340IBSC Programmer’s GuideTable 3–8: Status Report DefinitionWo rd Description Va lue Setting1 Link status 0 off1 on2 starting2 Current o

3: BSC 3270 DLI FunctionsDC 900-1340I 75The signals DTR, DSR, DCD, RTS, and CTS are reported on when the link detects them.The transmitter or receiver

76 DC 900-1340IBSC Programmer’s Guide3.4.2.7 Request BSC 3270 Poll ListUse the dlWrite function with the pOptArgs.usProtCommand field set toDLI_PROT_G

3: BSC 3270 DLI FunctionsDC 900-1340I 77When a tributary link is started, each device on that link has a status associated with itbased on the setting

78 DC 900-1340IBSC Programmer’s Guide3.4.3 Data Transfer using Raw dlWrite The BSC 3270 software provides two write types (EOM and non-EOM) for each d

3: BSC 3270 DLI FunctionsDC 900-1340I 79An unsuccessful dlWrite data transfer request can return one of the following errorcodes in the dlRead pOptArg

8 DC 900-1340IBSC Programmer’s Guide6.7.5 ASCII/CCITT-0... 1636.8 Transmission Block Size Option (8)... 16

80 DC 900-1340IBSC Programmer’s Guide3.5 Overview of BSC 3270 Responses using Raw dlReadTa ble 3 –10 shows the valid BSC 3270 codes sent to your appli

3: BSC 3270 DLI FunctionsDC 900-1340I 81Table 3–10: BSC 3270 Response CodesCategoryDLI Response Code in pOptArgs.usProtCommand FieldUsage SectionRecei

82 DC 900-1340IBSC Programmer’s GuideReportsDLI_PROT_GET_BUF_REPORTBuffer report Section 3.4.2.1DLI_PROT_GET_LINK_CFGLink configuration report Section

3: BSC 3270 DLI FunctionsDC 900-1340I 833.5.1 Normal and Transparent Received DataThe BSC 3270 software provides four read codes for data reception: t

84 DC 900-1340IBSC Programmer’s Guide

DC 900-1340I 85Chapter4BSC 3270 Link Configuration OptionsNoteThis chapter, along with Chapter 3 and Appendix A, should beread by programmers who are

86 DC 900-1340IBSC Programmer’s GuideTable 4–1: BSC 3270 Link Configuration Options and SettingsOption Number Va l u eDefault ()SettingData Rate (bit

4: BSC 3270 Link Configuration OptionsDC 900-1340I 87Conversational Mode 13 0  Disable1 EnableRetry Limit 14 n 3 n = number of retries (1 to 127)Poll

88 DC 900-1340IBSC Programmer’s Guide4.1 Data Rate Option (1) The data rate can be set by the client for installations where the communications server

4: BSC 3270 Link Configuration OptionsDC 900-1340I 89• 4–8 links at 19,200 b/s• 16 links for a 16-port ICP at 9600 b/sTo set this option using the DLI

ContentsDC 900-1340I 9A BSC 3270 Line Control Procedures 193A.1 Control Station Procedures...193A.1.1 General Poll...

90 DC 900-1340IBSC Programmer’s Guidenal clocking using a hardware jumper. If you need to set internal clocking, call the Pro-togate customer support

4: BSC 3270 Link Configuration OptionsDC 900-1340I 91page 72) which can be used by client application programs to verify the protocol run-ning on the

92 DC 900-1340IBSC Programmer’s GuideWhen the EBCDIC/CRC-16 setting is used, the BSC control sequences are transmittedin 8-bit EBCDIC, and the CRC-16

4: BSC 3270 Link Configuration OptionsDC 900-1340I 93For messages received on the communication line, the ICP message buffer size(Section 3.4.1.3 on p

94 DC 900-1340IBSC Programmer’s Guideto the poll and select sequences that match the CU number configured with the stationID (Section 4.16).To set thi

4: BSC 3270 Link Configuration OptionsDC 900-1340I 95In some situations the remote computer may send a WACK (wait acknowledge)sequence instead of the

96 DC 900-1340IBSC Programmer’s Guidemission is complete. In full-duplex operation (FDX-1 or FDX-2), the RTS signal isturned on when the link is start

4: BSC 3270 Link Configuration OptionsDC 900-1340I 97To set this option using the DLI configuration file, use the safeStore parameter; forexample, saf

98 DC 900-1340IBSC Programmer’s Guidebuffer to the client. For outbound data, each message buffer is transmitted on the lineas a separate transmission

4: BSC 3270 Link Configuration OptionsDC 900-1340I 99then deblocks the message such that the 3270 command strings are not split acrosstransmission blo