idnits 2.17.1 draft-ietf-tn3270e-ohio-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 17 longer pages, the longest (page 14) being 61 lines == It seems as if not all pages are separated by form feeds - found 0 form feeds but 18 pages Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack a Security Considerations section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack an Authors' Addresses Section. ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There is 1 instance of too long lines in the document, the longest one being 1 character in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- Couldn't find a document date in the document -- date freshness check skipped. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) No issues found here. Summary: 7 errors (**), 0 flaws (~~), 3 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 TN3270E Working Group Thomas Brawn 3 Internet Draft: IBM Corporation 4 Expiration Date: October 1st, 1999 Stephen Gunn 5 Attachmate Corporation 7 Open Host Interface Objects 9 Status of this Memo 10 This document is an Internet-Draft and is in full conformance with 11 all provisions of Section 10 of RFC2026. 13 Internet-Drafts are working documents of the Internet Engineering 14 Task Force (IETF), its areas, and its working groups. Note that 15 other groups may also distribute working documents as 16 Internet-Drafts. 18 Internet-Drafts are draft documents valid for a maximum of six months 19 and may be updated, replaced, or obsoleted by other documents at any 20 time. It is inappropriate to use Internet-Drafts as reference 21 material or to cite them other than as "work in progress." The list 22 of current Internet-Drafts can be accessed at 23 http://www.ietf.org/ietf/1id-abstracts.txt 25 The list of Internet-Draft Shadow Directories can be accessed at 26 http://www.ietf.org/shadow.html. 28 Abstract 29 This draft addresses the need for a common, advanced, client 30 programming interface to mainframe host data. Application 31 developers, in particular third party application vendors, use 32 API's provided by client emulator programs to write applications 33 that access host data. Currently, the defacto standard HLLAPI is 34 the interface most commonly provided by these programs and the one 35 used by the third party application vendors. However, HLLAPI is 36 plagued by the fact that it doesn't exploit modern programming 37 techniques and is fragmented by multiple, proprietary 38 implementations. Client vendors have, over the last couple of years, 39 developed more advanced interfaces that exploit modern programming 40 advances. However no effort has been put into standardizing these 41 interfaces and application developers have been forced to either 42 chose to stay with HLLAPI or perform costly re-implementation of 43 their products to support each competing advanced client API. 45 The Open Host Interface Objects (OHIO) address the need for a 46 standardized advanced programming interface to the host data. OHIO 47 does not modify the TN3270/TN5250 protocol or datastream but instead 48 provides a common access method to that data once it arrives at the 49 client. OHIO uses an Object Oriented approach to divide the data into 50 logical objects, and provides methods on those objects to allow 51 standard access to the data. Details about the connection protocol 52 used to communicate with the host and the specific host platform. 54 Table of Contents 56 OPEN HOST INTERFACE OBJECTS FOR TN3270E . . . . . . . . . . . 1 57 STATUS OF THIS MEMO . . . . . . . . . . . . . . . . . . . . . 1 58 ABSTRACT . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 59 TABLE OF CONTENTS . . . . . . . . . . . . . . . . . . . . . . 2 60 1.0 INTRODUCTION . . . . . . . . . . . . . . . . . . . . . . . 2 61 2.0 OBJECT DEFINITIONS . . . . . . . . . . . . . . . . . . . . 3 62 2.1 OHIO . . . . . . . . . . . . . . . . . . . . . . . . . 3 63 2.2 OHIOFIELD . . . . . . . . . . . . . . . . . . . . . . . 6 64 2.3 OHIOFIELDS . . . . . . . . . . . . . . . . . . . . . . 8 65 2.4 OHIOMANAGER . . . . . . . . . . . . . . . . . . . . . . 9 66 2.5 OHIOOIA . . . . . . . . . . . . . . . . . . . . . . . . 10 67 2.6 OHIOPOSITION . . . . . . . . . . . . . . . . . . . . . 11 68 2.7 OHIOSCREEN . . . . . . . . . . . . . . . . . . . . . . 11 69 2.8 OHIOSESSION . . . . . . . . . . . . . . . . . . . . . . 14 70 2.9 OHIOSESSIONS . . . . . . . . . . . . . . . . . . . . . 15 71 3.0 ACKNOWLEDGMENTS . . . . . . . . . . . . . . . . . . . . . 15 72 4.0 REFERENCES . . . . . . . . . . . . . . . . . . . . . . . . 16 73 5.0 HOW TO CONTACT THE AUTHORS . . . . . . . . . . . . . . . . 16 74 APPENDIX A: OHIO JAVA MAPPING . . . . . . . . . . . . . . . . 16 75 APPENDIX B: OHIO ACTIVEX IDL MAPPING . . . . . . . . . . . . . 16 76 APPENDIX C: 3270 FORMAT CONTROL ORDERS . . . . . . . . . . . . 16 78 1.0 Introduction 80 The following is the Ohio containment hierarchy: 81 OhioManager: Contains one: 82 OhioSessions: Contains a collection of1: 83 OhioSession: Contains one: 84 OhioScreen: Contains one of each of: 85 OhioOIA: The operator information area 86 OhioFields: Contains a collection of: 87 OhioField: A field in the presentation space 89 Additional utility classes: 90 OhioPosition 92 The Ohio inheritance hierarchy is: 93 Ohio: Base class 94 OhioManager 95 OhioSessions 96 OhioSession 97 OhioScreen 98 OhioOIA 99 OhioFields 100 OhioField 101 OhioPosition 103 2.0 Object Definitions 105 OMG IDL Version 2.1 is used to define the following objects. For a 106 mapping of the IDL to Java, see Appendix A - Ohio Java Mapping. For 107 a mapping of the IDL to ActiveX IDL, see Appendix B - Ohio ActiveX 108 IDL Mapping. 110 Note: "1" based counting is used throughout this document for both 111 positions (the first position on the screen is position 1, not 112 position 0) and sizes (the first item in a collection is item 1, not 113 item 0). 115 2.1 Ohio 117 Base class for all Ohio classes. Contains all common Ohio methods 118 and properties. 120 Interface Ohio { 122 // This enum is used by: 123 // OhioFields.FindByString 124 // OhioScreen.FindString 125 Readonly Attribute enum OHIO_DIRECTION { 126 OHIO_DIRECTION_FORWARD // Forward (beginning towards end) 127 OHIO_DIRECTION_BACKWARD // Backward (end towards beginning) 128 }; 130 // This enum is used by: 131 // OhioSession.sessionType 132 Readonly Attribute enum OHIO_TYPE { 133 OHIO_TYPE_UNKNOWN // Unknown host 134 OHIO_TYPE_3270 // 3270 host 135 OHIO_TYPE_5250 // 5250 host 136 }; 137 // This enum is used by: 138 // OHIOSession.connected 139 // OHIOSession sessionChanged 140 Readonly Attribute enum OHIO_STATE { 141 OHIO_STATE_DISCONNECTED // The communication link to the 142 // host is disconnected. 143 OHIO_STATE_CONNECTED // The communication link to the 144 // host is connected. 145 }; 147 // This enum is used by: 148 // OHIOField.getData 149 // OHIOScreen.getData 150 Readonly Attribute enum OHIO_PLANE { 151 OHIO_PLANE_TEXT // Indicates Text Plane (character data) 152 OHIO_PLANE_COLOR // Indicates Color Plane (standard HLLAPI 153 // CGA color values) 154 OHIO_PLANE_FIELD // Indicates Field Attribute Plane (field 155 // attribute bytes) 156 OHIO_PLANE_EXTENDED // Indicates Extended Plane (extended 157 // attribute bytes) 158 }; 160 // These values are returned in the Ohio Color Plane from the 161 // following methods: 162 // OhioField.getData 163 // OhioScreen.getData 164 Readonly Attribute enum OHIO_COLOR { 165 OHIO_COLOR_BLACK 166 OHIO_COLOR_BLUE 167 OHIO_COLOR_GREEN 168 OHIO_COLOR_CYAN 169 OHIO_COLOR_RED 170 OHIO_COLOR_MAGENTA 171 OHIO_COLOR_WHITE 172 OHIO_COLOR_YELLOW 173 }; 175 // These values are returned in the Ohio Extended Field Plane 176 // from the following methods: 177 // OhioField.getData 178 // OhioScreen.getData 179 Readonly Attribute enum OHIO_EXTENDED { 180 OHIO_EXTENDED_HILITE // Bitmask for Highlighting Bits 181 OHIO_EXTENDED_COLOR // Bitmask for Color Bits 182 OHIO_EXTENDED_RESERVED // Bitmask for Reserved Bits 183 OHIO_EXTENDED_HILITE_NORMAL // Normal highlighting 184 OHIO_EXTENDED_HILITE_BLINK // Blinking highlighting 185 OHIO_EXTENDED_HILITE_REVERSEVIDEO // Reverse Video 186 // highlighting 188 OHIO_EXTENDED_HILITE_UNDERSCORE // Underscore 189 // highlighting 190 OHIO_EXTENDED_COLOR_DEFAULT // Default color 191 OHIO_EXTENDED_COLOR_BLUE // Blue 192 OHIO_EXTENDED_COLOR_RED // Red 193 OHIO_EXTENDED_COLOR_PINK // Pink 194 OHIO_EXTENDED_COLOR_GREEN // Green 195 OHIO_EXTENDED_COLOR_TURQUOISE // Turquoise 196 OHIO_EXTENDED_COLOR_YELLOW // Yellow 197 OHIO_EXTENDED_COLOR_WHITE // White 198 }; 200 // These values are returned in the Ohio Field Attributes from 201 // the following methods: 202 // OhioScreen.getData 203 Readonly Attribute enum OHIO_FIELD { 204 OHIO_FIELD_ATTRIBUTE // Bitmask for field attribute 205 OHIO_FIELD_PROTECTED // Protected field 206 OHIO_FIELD_NUMERIC // Numeric field 207 OHIO_FIELD_PEN_SELECTABLE // Pen selectable field 208 OHIO_FIELD_HIGH_INTENSITY // High intensity field 209 OHIO_FIELD_HIDDEN // Hidden field 210 OHIO_FIELD_RESERVED // Reserved field 211 OHIO_FIELD_MODIFIED // Modified field 212 }; 214 // This enum is used by: 215 // OhioScreen event processing 216 Readonly Attribute enum OHIO_UPDATE { 217 OHIO_UPDATE_CLIENT // Update initiated by client 218 OHIO_UPDATE_HOST // Update initiated by host 219 }; 221 // This enum is used by: 222 // OhioOIA.owner 223 Readonly Attribute enum OHIO_OWNER { 224 OHIO_OWNER_UNKNOWN // Uninitialized 225 OHIO_OWNER_APP // Application or 5250 host 226 OHIO_OWNER_MYJOB // 3270 - Myjob 227 OHIO_OWNER_NVT // 3270 in NVT mode 228 OHIO_OWNER_UNOWNED // 3270 - Unowned 229 OHIO_OWNER_SSCP // 3270 - SSCP 230 }; 232 // This enum is used by: 233 // OhioOIA.InputInhibited 234 Readonly Attribute enum OHIO_INPUTINHIBITED { 235 OHIO_INPUTINHIBITED_NOTINHIBITED // Input not inhibited 236 OHIO_INPUTINHIBITED_SYSTEM_WAIT // Input inhibited by a 237 // System Wait state ("X SYSTEM" or "X []") 239 OHIO_INPUTINHIBITED_COMMCHECK // Input inhibited by a 240 // communications check state ("X COMMxxx") 241 OHIO_INPUTINHIBITED_PROGCHECK // Input inhibited by a 242 // program check state ("X PROGxxx") 243 OHIO_INPUTINHIBITED_MACHINECHECK // Input inhibited by a 244 // machine check state ("X MACHxxx") 245 OHIO_INPUTINHIBITED_OTHER // Input inhibited by something 246 // other than above states 247 }; 249 // The OHIO version level of this implementation. The form is 250 // "OHIO nn.nn" 251 Readonly Attribute string OhioVersion; 253 // The name of the vendor providing this OHIO implementation. 254 // Format is vendor defined. 255 Readonly Attribute string VendorName; 257 // The vendor product version that is providing the OHIO 258 // implementation. Format is vendor specific. 259 Readonly Attribute string VendorProductVersion; 261 // The vendor object that provides non-standard, vendor 262 // specific extensions to the OHIO object. 263 Readonly Attribute Object VendorObject; 265 // Create an OhioPosition object. 266 // row The row coordinate. 267 // col The column coordinate. 268 OhioPosition CreateOhioPosition(row, col); 270 }; 272 2.2 OhioField 274 A field is the fundamental element of a virtual screen. A field 275 includes both data and attributes describing the field. The 276 OhioField class encapsulates a virtual screen field and provides 277 methods for accessing and manipulating field attributes and data. 279 OhioField objects can be accessed only through the OhioFields 280 object. 282 Interface OhioField { 284 // The starting position of the field. The position can range 285 // from 1 to the size of the virtual screen. The starting 286 // position of a field is the position of the first character 287 // in the field. 288 Readonly Attribute OhioPosition Start; 289 // The ending position of the field. The position can range 290 // from 1 to the size of the virtual screen. The ending 291 // position of a field is the position of the last character in 292 // the field. 293 Readonly Attribute OhioPosition End; 295 // The length of the field. A field's length can range 296 from 1 to the size of the 297 // virtual screen. 298 Readonly Attribute int Length; 300 // The attribute byte for the field. 301 Readonly Attribute int Attribute; 303 // Indicates whether or not the field has been modified. True 304 // if the field has been modified, otherwise false. 305 Readonly Attribute boolean Modified; 307 // Indicates whether or not the field is protected. True if 308 // the field is protected, otherwise false. 309 Readonly Attribute boolean Protected; 311 // Indicates whether or not the field is numeric-only. True if 312 // the field is numeric only, otherwise false. 313 Readonly Attribute boolean Numeric; 315 // Indicates whether or not the field is high-intensity. True 316 // if the field is high intensity, otherwise false. 317 Readonly Attribute boolean HighIntensity; 319 // Indicates whether or not the field is pen-selectable. True 320 // if the field is pen-selectable, otherwise false. 321 Readonly Attribute boolean PenSelectable; 323 // Indicates whether or not the field is hidden. True if the 324 // field is hidden, otherwise false. 325 Readonly Attribute boolean Hidden; 327 // The text plane data for the field. This is similar to the 328 // getData() method using the OHIO_PLANE_TEXT parameter, except 329 // the data is returned as a string instead of a character 330 // array. When setting the String property, if the string is 331 // shorter than the length of the field, the rest of the field 332 // is cleared. If the string is longer than the field, the 333 // text is truncated. A subsequent call to this property will 334 // not reflect the changed text. To see the changed text, do a 335 // refresh on the OhioFields collection and retrieve a new 336 // OhioField object. 337 Attribute string String; 338 // Returns data from the different planes (text, color, 339 // extended) associated with the field. The data is returned 340 // as a character array. 341 // targetPlane An OHIO_PLANE value indicating from which 342 // plane to retrieve the data. 343 char[] getData(OHIO_PLANE targetPlane); 345 }; 347 2.3 OhioFields 349 OhioFields contains a collection of the fields in the virtual 350 screen. It provides methods to iterate through the fields, find 351 fields based on location, and find fields containing a given 352 string. Each element of the collection is an instance of 353 OhioField. 355 OhioFields can only be accessed through OhioScreen using the 356 Fields property. OhioFields is a static view of the virtual 357 screen and does not reflect changes made to the virtual screen 358 after its construction. The field list can be updated with a new 359 view of the virtual screen using the Refresh() method. 361 Note: All OhioField objects returned by methods in this class are 362 invalidated when Refresh() is called. 364 Interface OhioFields { 366 // Returns the number of OhioField objects contained in this 367 // collection. 368 Readonly Attribute int Count; 370 // Returns the OhioField object at the given index. "One 371 // based" indexing is used in all Ohio collections. For 372 // example, the first OhioField in this collection is at 373 // index 1. 374 OhioField Item(int fieldIndex); 376 // Updates the collection of OhioField objects. All OhioField 377 // objects in the current virtual screen are added to the 378 // collection. Indexing of OhioField objects will not be 379 // preserved across refreshes. 380 void Refresh(); 382 // Searches the collection for the target string and returns 383 // the OhioField object containing that string. The string 384 // must be totally contained within the field to be considered 385 // a match. If the target string is not found, a null will be 386 // returned. 387 // targetString The target string. 389 // startPos The row and column where to start. The 390 // position is inclusive (for example, row 1, 391 // col 1 means that position 1,1 will be used 392 // as the starting location and 1,1 will be 393 // included in the search). 394 // length The length from startPos to include in the 395 // search. 396 // dir An OHIO_DIRECTION value. 397 // ignoreCase Indicates whether the search is case 398 // sensitive. True means that case will be 399 // ignored. False means the search will be 400 // case sensitive. 401 OhioField FindByString(String targetString, 402 OhioPosition startPos, 403 int length, 404 OHIO_DIRECTION dir, 405 boolean ignoreCase); 407 // Searches the collection for the target position and returns 408 // the OhioField object containing that position. If not 409 // found, returns a null. 410 // targetPosition The target row and column. 411 OhioField FindByPosition(OhioPosition targetPosition); 413 }; 415 2.4 OhioManager 417 The central repository for access to all OHIO sessions. The 418 OhioManager contains a list of all OhioSession objects available 419 on this system. 421 Interface OhioManager { 423 // An OhioSessions object containing the OhioSession objects 424 // available on this system. This list of objects is a static 425 // snapshot at the time the OhioSessions object is created. 426 // Use the OhioSessions.refresh method to obtain a new 427 // snapshot. 428 Readonly Attribute OhioSessions Sessions; 430 // Returns an OhioSession object based on the search parameters 431 // provided. 432 // ConfigurationResource A vendor specific string used to 433 // provide configuration information. 434 // SessionName The unique name associated with an 435 // OhioSession. 437 // The parameters are used as follows: 438 // Is ConfigurationResource provided? 439 // Yes - Is SessionName provided? 440 // Yes - Is OhioSession object with matching 441 // SessionName available on the system? 442 // Yes - Error, attempting to create an 443 // OhioSession object with a non-unique 444 // SessionName. 445 // No - Create an OhioSession object using 446 // SessionName and ConfigurationResource. 447 // No - Start a new OhioSession using 448 // ConfigurationResource and generating a new 449 // SessionName. 450 // No - Is SessionName provided? 451 // Yes - Is OhioSession object with matching 452 // SessionName available on the system? 453 // Yes - Return identified OhioSession object. 454 // No - Return null. 455 // No - Return null. 456 OhioSession OpenSession(String ConfigurationResource, 457 String SessionName); 459 // Closes an OhioSession object. The OhioSession is 460 // considered invalid and is removed from the list of 461 // OhioSession objects. 462 // SessionObject The OhioSession to close. 463 void CloseSession(OhioSession SessionObject); 465 // Closes an OhioSession object. The OhioSession is 466 // considered invalid and is removed from the list of 467 // OhioSession objects. 468 // SessionName The SessionName of the OhioSession to 469 // close. 470 void CloseSession(String SessionName); 472 }; 474 2.5 OhioOIA 476 The operator information area of a host session. This area is 477 used to provide status information regarding the state of the host 478 session and location of the cursor. 480 An OhioOIA object can be obtained using the GetOIA() method on an 481 instance of OhioScreen. 483 Interface OhioOIA { 484 // Indicates whether the field which contains the cursor is an 485 // alphanumeric field. True if the cursor is in an 486 // alphanumeric field, false otherwise. 487 Readonly Attribute boolean Alphanumeric; 489 // The communication check code. If InputInhibited returns 490 // OHIO_INPUTINHIBITED_COMMCHECK, this property will return the 491 // communication check code. 492 Readonly Attribute int CommCheckCode; 494 // Indicates whether or not input is inhibited. If input is 495 // inhibited, SendKeys or SendAID calls to the OhioScreen are 496 // not allowed. Why input is inhibited can be determined from 497 // the value returned. If input is inhibited for more than one 498 // reason, the highest value is returned. 499 Readonly Attribute OHIO_INPUTINHIBITED InputInhibited; 501 // The machine check code. If InputInhibited returns 502 // OHIO_INPUTINHIBITED_MACHINECHECK, this property will return 503 // the machine check code. 504 Readonly Attribute int MachineCheckCode; 506 // Indicates whether the field which contains the cursor is a 507 // numeric-only field. True if the cursor is in a numeric-only 508 // field, false otherwise. 509 Readonly Attribute boolean Numeric; 511 // Indicates the owner of the host connection. 512 Readonly Attribute OHIO_OWNER Owner; 514 // The program check code. If InputInhibited returns 515 // OHIO_INPUTINHIBITED_PROGCHECK, this property will return the 516 // program check code. 517 Readonly Attribute int ProgCheckCode; 519 }; 521 2.6 OhioPosition 523 Holds row and column coordinates. An OhioPosition can be 524 constructed by using CreateOhioPosition() on any Ohio class. 526 Interface OhioPosition { 528 // The row coordinate 529 Attribute int Row; 531 // The column coordinate. 532 Attribute int Column; 534 }; 535 2.7 OhioScreen 537 OhioScreen encapsulates the host presentation space. The 538 presentation space is a virtual screen which contains all the 539 characters and attributes that would be seen on a traditional 540 emulator screen. This virtual screen is the primary object for 541 text-based interactions with the host. The OhioScreen provides 542 methods that manipulate text, search the screen, send keystrokes 543 to the host, and work with the cursor. 545 An OhioScreen object can be obtained from the Screen property of 546 an instance of OhioSession. 548 The raw presentation space data is maintained in a series of 549 planes which can be accessed by various methods within this class. 550 The text plane contains the actual characters in the presentation 551 space. Most of the methods in OhioScreen class work exclusively 552 with the text plane. 554 The remaining planes contain the corresponding attributes for each 555 character in the text plane. The color plane contains color 556 characteristics. The field plane contains the field attributes. 557 The extended plane contains the extended field attributes. The 558 color, field, and extended planes are not interpreted by any of 559 the methods in this class. 561 Interface OhioScreen { 563 // The location of the cursor in the presentation space. The 564 // row and column of the cursor is contained within the 565 // OhioPosition object. 566 Attribute OhioPosition Cursor; 568 // The OhioOIA object associated with this presentation space. 569 // This object can be used to query the status of the operator 570 // information area. 571 Readonly Attribute OhioOIA OIA; 573 // The OhioFields object associated with this presentation 574 // space. This provides another way to access the data in the 575 // virtual screen. The OhioFields object contains a snapshot 576 // of all the fields in the current virtual screen. Fields 577 // provide methods for interpreting the data in the non-text 578 // planes. Zero length fields (due to adjacent field 579 // attributes) are not returned in the OhioFields collection. 580 // For unformatted screens, the returned collection contains 581 // only one OhioField that contains the whole virtual screen. 582 Readonly Attribute OhioFields Fields; 584 // The number of rows in the presentation space. 585 Readonly Attribute int Rows; 586 // The number of columns in the presentation space. 587 Readonly Attribute int Columns; 589 // The entire text plane of the virtual screen as a string. 590 // All null characters and Field Attribute characters are 591 // returned as blank space characters. 592 Readonly Attribute string String; 594 // Returns a character array containing the data from the Text, 595 // Color, Field or Extended plane of the virtual screen. 596 // start The row and column where to start. The position 597 // is inclusive (for example, row 1, col 1 means that 598 // position 1,1 will be used as the starting location 599 // and 1,1 will be included in the data). "start" 600 // must be positionally less than "end". 601 // end The row and column where to end. The position is 602 // inclusive (for example, row 1, col 1 means that 603 // position 1,1 will be used as the ending location 604 // and 1,1 will be included in the data). "end" must 605 // be positionally greater than "start". 606 // plane A valid OHIO_PLANE value. 607 char[] getData(OhioPosition start, 608 OhioPosition end, 609 OHIO_PLANE plane); 611 // Searches the text plane for the target string. If found, 612 // returns an OhioPosition object containing the target 613 // location. If not found, returns a null. The targetString 614 // must be completely contained by the target area for the 615 // search to be successful. Null characters in the text plane 616 // are treated as blank spaces during search processing. 617 // targetString The target string. 618 // startPos The row and column where to start. The 619 // position is inclusive (for example, row 1, 620 // col 1 means that position 1,1 will be used as 621 // the starting location and 1,1 will be included 622 // in the search). 623 // length The length from startPos to include in the 624 // search. 625 // dir An OHIO_DIRECTION value. 626 // ignoreCase Indicates whether the search is case 627 // sensitive. True means that case will be 628 // ignored. False means the search will be case 629 // sensitive. 630 OhioPosition FindString(string targetString, 631 OhioPosition start, 632 int length, 633 int OHIO_DIRECTION, 634 boolean ignoreCase); 636 // The sendKeys method sends a string of keys to the virtual 637 // screen. This method acts as if keystrokes were being typed 638 // from the keyboard. 639 // 640 // The keystrokes will be sent to the location given. If no 641 // location is provided, the keystrokes will be sent to the 642 // current cursor location. 643 // text The string of characters to be sent. 644 void sendKeys(string text, 645 OhioPosition location); 647 // The sendAid method sends an "aid" keystroke to the virtual 648 // screen. These aid keys can be though of as special 649 // keystrokes, like the Enter key, the Tab key, or the Page Up 651 // key. All the valid special key values are contained in the 652 // OHIO_AID enumeration. 653 // aidKey The aid key to send to the virtual screen. 654 void sendAid(OHIO_AID aidKey); 656 // The putString method sends a string to the virtual screen at 657 // the specified location. The string will overlay only 658 // unprotected fields, and any parts of the string which fall 660 // over protected fields will be discarded. 661 // text String to place in the virtual screen. 662 // location Position where the string should be written. 663 void setString(string text, 664 OhioPosition location); 666 }; 668 2.8 OhioSession 670 A host session. 672 Interface OhioSession { 674 // The configurationResource for this OhioSession object. 675 Readonly Attribute string ConfigurationResource; 677 // Indicates whether this OhioSession object is connected to a 678 // host. True means connected, false means not connected. 679 Readonly Attribute boolean Connected; 681 // The SessionName for this OhioSession object. The 682 // SessionName is unique among all instances of OhioSession. 683 Readonly Attribute string SessionName; 685 // The SessionType for this OhioSession object. 686 Readonly Attribute OHIO_TYPE SessionType; 687 // The OhioScreen object for this session. 688 Readonly Attribute OhioScreen Screen; 690 // Starts the communications link to the host. 691 void Connect(); 693 // Stops the communications link to the host. 694 void Disconnect(); 696 }; 698 2.9 OhioSessions 700 Contains a collection of OhioSession objects. This list is a 701 static snapshot of the list of OhioSession objects available at 702 the time of the snapshot. 704 Interface OhioSessions { 706 // The number of OhioSession objects contained in this 707 // collection. 708 Readonly Attribute int Count; 710 // The OhioSession object at the given index. "One based" 711 // indexing is used in all Ohio collections. For example, the 712 // first OhioSession in this collection is at index 1. 713 // index The index of the target OhioSession. 714 OhioSession Item(int index); 716 // The OhioSession object with the given SessionName. Returns 717 // null if no object with that name exists in this collection. 718 // SessionName The target name. 719 OhioSession Item(string SessionName); 721 // Updates the collection of OhioSession objects. All 722 // OhioSession objects that are available on the system at the 723 // time of the refresh will be added to the collection. 724 // Indexing of OhioSession objects will not be preserved across 725 // refreshes. 726 void Refresh(); 728 }; 730 3.0 Acknowledgments 732 This document was initiated in the TN3270E Working Group and was 733 completed by a dedicated group of interested parties. 735 The authors wish to thank the following individuals for their 736 contributions to this document: 737 - Jeffrey Altman, Columbia University 738 - Eugene Aresteanu, Eicon Technology 739 - Blair Cooper, Attachmate Corporation 740 - Andrew Duckworth, Platypus Partners, Inc. 741 - Brian L. Henry, Attachmate Corporation 742 - Gary Horen, WRQ 743 - Pierre Goyette, Hummingbird Communications, Ltd. 744 - Greg Knowles, IBM Corporation 745 - Warren Mackensen, NetManage, Inc. 746 - Mark McMillan, IBM Corporation 747 - Hemant Nanivadekar, Attachmate Corporation 748 - J. Burke Ryder, Attachmate Corporation 749 - Brian Webb, IBM Corporation 751 4.0 References 753 - International Business Machines Corporation, "eNetwork Personal 754 Communications Version 4.2 for Windows 95 and Windows NT Host 755 Access Class Library", September 1997. 756 - International Business Machines Corporation, "Host On-Demand 757 Version 2.0 Host Access Class Library for Java Reference", 758 October 1997. 759 - Attachmate Corporation, "EXTRA! Objects SDK Reference Guide for 760 C++", October 1997. 762 5.0 How to Contact the Authors 764 Thomas Brawn 765 IBM Corporation 766 4205 S. Miami Blvd 767 RTP, NC 27709 768 e-mail: brawntj@us.ibm.com 769 phone: 919-254-8301 771 Stephen Gunn 772 Attachmate Corporation 773 3617 131st Ave. S.E. 774 Bellevue, Washington 98006 775 e-mail: stevegu@attachmate.com 776 phone: 425-649-6221 778 Appendix A - Ohio Java Mapping 780 Available using anonymous ftp from ftp.boulder.ibm.com. Once 781 logged in, change to the software/standards/ohio/java directory 782 to download the Java classes. 784 Appendix B - Ohio ActiveX IDL Mapping 786 Available using anonymous ftp from ftp.boulder.ibm.com. Once 787 logged in, change to the software/standards/ohio/idl directory to 788 download the idl file. 790 Appendix C - 3270 Format Control Orders 792 This appendix specifies the representation of 3270 Format Control 793 Orders within OHIO text strings. 795 The following special control codes are classified as 3270 format 796 control orders. (This information is excerpted from the IBM 3270 797 Information Display System Data Stream Programmer's Reference, 798 Document Number GA23-0059-07.) On a 3270 display device, these 799 format control orders are stored in the device buffer and 800 displayed as shown below. Their representation in OHIO text 801 strings (OhioScreen and OhioField) is included in the ANSI and 802 UNICODE columns. The ANSI values were taken from the IBM 803 Character Data Representation Library Character Data 804 Representation Architecture Reference and Registry, Document 805 Number SC09-2190-00. The UNICODE values were taken from 806 ADDITIONAL CONTROL PICTURES FOR UNICODE, 807 ftp://kermit.columbia.edu/kermit/ucsterminal/control.txt. Some 808 of these values are proposed extensions to the Unicode Control 809 Pictures. 811 Abbr Order EBCDIC ANSI Unicode Displayed As 812 . 813 NUL Null 00 00 2400 A blank, suppressed on 814 Read Modified 815 SUB Substitute 3F 1A 241A A solid circle 816 DUP Duplicate 1C 1C E07B An overscore asterisk 817 FM Field Mark 1E 1E E07D An overscore semicolon 818 FF Form Feed 0C 0C 240C A blank 819 CR Carriage Return 0D 0D 240D A blank 820 NL New Line 15 85 2424 A blank 821 EM End of Medium 19 19 2419 A blank 822 EO Eight Ones FF 9F E07F A blank 824 Notes: 825 ANSI 85: Conflicts with "Next Line" C1 control character (ISO 826 6429). 827 ANSI 9F: Conflicts with "Application Program Command" C1 control 828 character (ISO 6429). 830 NUL is read back (by the host) as a null (x'00') on a Read Buffer 831 operation, but not read back on Read Modified operations. 833 NL, EM, FF, and CR are printer control codes with no display 834 function. However, the code must be supported to the extent of 835 being accepted and, on reading back, must appear as NL, EM, FF, 836 and CR respectively. All are displayed as a space. 838 FM and DUP are displayed as above. When read back, they appear 839 as the FM and DUP codes. 840 FM and DUP can be entered from the keyboard. They are stored in 841 the display buffer as controls; the current character set 842 selection has no effect on them. They are transmitted to the 843 application program as control codes. 845 The SUB local function, Error Override, entered from the 846 keyboard, is required only as a part of Field Validation.